88 lines
3.8 KiB
Markdown
88 lines
3.8 KiB
Markdown
# 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 `` 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
|