datascape/AGENTS.md

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

Frontend Conventions

JS file scoping: each feature gets its own file. Global app behaviour goes in global-shortcuts.js. Feature-specific logic gets its own file (e.g. editor.js). Do not inline JS in the template or consolidate unrelated features into one file.

Keyboard shortcuts: ALT+SHIFT is the established modifier for all application shortcuts — it avoids collisions with browser and OS bindings. Do not use other modifiers for new shortcuts.

Editor toolbar: buttons use data-action (maps to a JS action function) and data-key (the ALT+SHIFT+KEY shortcut letter). Adding a data-key to a button automatically registers its shortcut — no extra wiring needed.

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