docs: media model = git files beside articles (Garage S3 dropped); update README/PLAN/maps

docs/MEDIA-PLAN.md

@@ -0,0 +1,110 @@
+# Plan — Robust media: images co-located with articles, git-as-source-of-truth
+
+Status: **PROPOSED** — awaiting your review, then I implement exactly this.
+
+## 0. Problem statement (why we're here)
+
+The S3/Garage + Decap-media path produced a fragile system: a wrong-signing SDK default,
+orphan attachments landing at repo root (aboutme.jpeg, webdevelopment.jpeg), a Decap media
+library that writes into git instead of S3, and no single robust place for images. We are
+**dropping Garage S3 for Kontra media entirely**. Images live as **files in the content
+repo, co-located with their article** — one source of truth, versioned, backed up, and
+served by the app.
+
+## 1. Target layout (Option A — images with their article)
+
+```
+content/
+└── subjects/
+    └── world/
+        ├── _subject.yaml
+        ├── chinese-chips/
+        │   ├── chinese-chips.md      ← article (same filename → same URL /articles/chinese-chips)
+        │   ├── aboutme.jpeg          ← images beside their article
+        │   └── hero.jpg
+        ├── southern-harbor/
+        │   ├── southern-harbor.md
+        │   └── harbor.jpg
+        └── river-border/
+            └── river-border.md
+```
+
+- **Slug is unchanged** (from filename) — URLs `/articles/<slug>` stay identical.
+- **Obsidian's native setting** ("attachments: same folder as current file") puts images
+  beside the article automatically — no config drift, no stray files at repo root.
+- **Decap** reads/writes the same git tree, so it sees the same folders (its image widget
+  becomes a string `{{media:...}}`; no library files committed).
+- **App** serves images at `/media/<path>` by reading the repo folder — a plain file server.
+
+## 2. Why Option A over a top-level media/ folder
+
+- Obsidian's default attachment behavior (same folder) needs **zero configuration** and
+  cannot orphan files — the exact failure mode that created `aboutme.jpeg` at root.
+- Each article is a **self-contained folder** (text + images): move/copy/archive in one step.
+- Collisions impossible — filenames only clash within the same article.
+- Serving complexity is identical to a central media folder (both are static file serving).
+
+## 3. Changes required (minimal, mechanical)
+
+1. **Content repo**
+   - Migrate articles to folders: `subjects/<s>/<slug>/<slug>.md` (+ move their images in).
+   - Move stray images (`aboutme.jpeg`, `webdevelopment.jpeg`) into their article folder.
+   - Add `content/.gitignore`: nothing special (images are intentionally tracked now);
+     but add `.trash/` to gitignore so Obsidian's trash stops entering git.
+   - Add `/media`-relevant note in `_templates/article.md`.
+2. **App loader** (`app/src/content.go`)
+   - Make article discovery **recurse one level** under each subject folder (currently
+     non-recursive: `*.md` at subject root, `_subject.yaml` skipped). New rule:
+     - `subjects/<s>/<slug>.md` (flat, existing) **and** `subjects/<s>/<slug>/*.md` (new).
+     - Still skip `_`-prefixed files/dirs (config, templates).
+   - Slug = filename without `.md`, unchanged.
+3. **App media route** (`app/src/main.go` + handler)
+   - Replace the Garage proxy: `/media/{path...}` → serve the file from
+     `<content>/subjects/<s>/<slug>/<path>` or from the repo root `media/` if any.
+     Simplest robust: look up `<content>/<path>` in the content root (covers any location)
+     with a safe-path guard (no `..`), set Content-Type from extension.
+   - **Reference convention (DECIDED)**: full repo-relative path — `{{media:chinese-chips/aboutme.jpeg}}`.
+     The app maps `/media/{path...}` → file relative to content root (safe-path guarded).
+   - Remove `/admin/media` upload page + Garage upload endpoint + minio-go dependency
+     (or keep minio-go for future — recommend removing to keep binary lean).
+4. **Front-matter/{{media:}}**
+   - `{{media:chinese-chips/aboutme.jpeg}}` → `/media/chinese-chips/aboutme.jpeg` →
+     the app serves the file from the content root (safe-path guarded). Works for images in
+     any folder (article folders, pages).
+   - Obsidian/Decap reference images by the same repo-relative path:
+     `{{media:<slug>/<filename>}}` for an image beside its article.
+5. **Cleanup**
+   - Delete `real2.png` (+ `photonic-chips.png` leftover) from bucket — irrelevant now (S3 dropped).
+   - Remove the Garage bucket/key/kontra-day specific bits if unused elsewhere.
+   - Update `PLAN.md`, `DESIGN.md` (media section), `README.md`, `docs/OVERVIEW.md`
+     to the new model; remove S3/Decap-media claims.
+6. **Backups**
+   - Media now lives in the **content git repo** → backed up wherever the repo is:
+     Gitea (.35) + production clone (.13) + the existing offsite/NAB backup chain.
+   - No new backup config needed.
+
+## 4. Migration steps (in order)
+
+1. Commit a branch: move the 5 known articles into folders (+ images), update `.gitignore`.
+2. Loosen the loader (change #2), build, verify all existing URLs return 200.
+3. Swap the media route (change #3), build, verify `{{media:...}}` images serve from the repo.
+4. Push → autosync pulls to .13 → rebuild container with new binary.
+5. Remove the Decap media-library bits + S3 env from compose (or keep env unused).
+6. Fix the test article's references; verify Obsidian + Decap + site all agree.
+7. Update the docs (PLAN/DESIGN/README/OVERVIEW) and delete stale bucket artifacts.
+8. Full end-to-end: edit image in Obsidian → push → live in ~30s; delete image → 404s.
+
+## 5. Risks / notes
+
+- The loader change (recurse one level) is the only behavioral change to content discovery;
+  existing flat articles still work, so rollback is one revert.
+- `/media/<path>` file serving must guard against path traversal (`..`) — handled in change #3.
+- Obsidian trash: `.trash/` is already in the repo (Obsidian's own folder) — gitignoring it
+  stops it syncing to Gitea while keeping local trash.
+- No secrets change; Gitea deploy token stays in `.env` (gitignored).
+
+## 6. Out of scope (unless you ask)
+
+- Reintroducing any S3/Garage for Kontra media.
+- A browser-based media manager beyond the simple file page.
+- Multi-editor auth beyond the existing Gitea/Obsidian workflow.