From 6a09fe4d989377c472f42a80b680b52c3b7210fb Mon Sep 17 00:00:00 2001
From: luxick <git@luxick.de>
Date: Fri, 10 Apr 2026 08:47:34 +0200
Subject: [PATCH] Add agents files

---
 AGENTS.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md |  4 +--
 2 files changed, 75 insertions(+), 2 deletions(-)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..43efcbc
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,73 @@
+# AGENTS.md — Personal Wiki (go-wiki)
+
+## Project Philosophy
+This is a minimal personal wiki where the **folder structure is the wiki**.
+There is no database, no CMS, no abstraction layer between the user and their files.
+Every decision should reinforce this — if a proposed solution adds indirection between
+the filesystem and what the user sees, question it.
+
+## Core Concept
+- Every folder *is* a page
+- `index.md` in a folder is that page's content
+- All related files (PDFs, images, CAD files, etc.) live in the same folder as `index.md`
+- Image links in `index.md` like `![](photo.jpg)` work because siblings are served at the same path
+- There are no "attachments" — files are just files in a folder
+
+## Target Environment
+- Runs on a QNAP TS-431P3 NAS (Annapurna Labs AL-314, ARMv7 32-bit, `linux/arm`)
+- All files live on the NAS and are mounted/accessed locally by the binary
+- Users access via browser over Wireguard VPN from Windows, Linux, and Android
+- Must cross-compile cleanly: `GOARCH=arm GOOS=linux GOARM=7 go build`
+
+## Tech Constraints
+- **Language:** Go
+- **Output:** Single static binary, no installer, no runtime dependencies
+- **Markdown:** `goldmark` for server-side rendering — no other markdown libraries
+- **Assets:** Embedded via `embed.FS` — no external asset serving or CDN
+- **HTTP:** stdlib `net/http` only — no web framework
+- **Dependencies:** Keep to an absolute minimum. If stdlib can do it, use stdlib.
+
+## HTTP Interface
+The entire API surface should stay minimal:
+
+| Method | Path | Behaviour |
+|--------|------|-----------|
+| GET | `/{path}` | If folder: render `index.md` + list contents. If file: serve raw. |
+| GET | `/{path}?edit` | Mobile-friendly editor with `index.md` content in a textarea |
+| POST | `/{path}` | Write updated `index.md` to disk |
+
+Do not add endpoints beyond these without a concrete stated need.
+
+## UI Principles
+- Mobile-first — the primary editing device is Android over Wireguard
+- No JavaScript frameworks — vanilla JS only, and only when necessary
+- No build pipeline for frontend assets — what is embedded is what is served
+- Readable on small screens without zooming
+- Fast on a low-power ARM CPU — no heavy rendering, no large payloads
+
+## Auth
+- Basic auth is sufficient — this is a personal tool on a private VPN
+- Do not over-engineer access control
+
+## What to Avoid
+- No database of any kind
+- No indexing or caching layer unless explicitly requested and justified
+- No parallel folder structures (the DokuWiki anti-pattern: `pages/` mirrored by `media/`)
+- No frameworks (web, ORM, DI, etc.)
+- No build steps for frontend assets
+- Do not suggest Docker unless the user asks — a plain binary is preferred
+
+## Development Order
+When building new features, follow this priority order:
+1. Correctness on the filesystem (never corrupt or lose user files)
+2. Mobile usability
+3. Simplicity of implementation
+4. Performance
+
+## Out of Scope (for now)
+These are explicitly deferred — do not implement or scaffold unless asked:
+- Full-text search
+- File upload via browser
+- Version history / git integration
+- Multi-user support
+- Tagging or metadata beyond `index.md` content
diff --git a/README.md b/README.md
index 6f0d8ef..0633d5c 100644
--- a/README.md
+++ b/README.md
@@ -15,8 +15,8 @@ go run . -dir ./wiki -addr :8080 -user me -pass secret
 # local
 go build -o datascape .
 
-# QNAP NAS (linux/arm64)
-GOOS=linux GOARCH=arm64 go build -o datascape .
+# QNAP NAS (linux/arm)
+GOOS=linux GOARCH=arm go build -o datascape .
 ```
 
 ## Usage