Rewrite user docs, trim developer-only _docs pages, add python-multipart

docs/content-location.md

@@ -0,0 +1,102 @@
+---
+title: Content location and structure
+---
+
+# Content location and structure
+
+Two open design questions about where wiki content lives and how it can be
+organised on disk.
+
+---
+
+## Q1 — Content in `site/` vs `bincio_wiki/`
+
+### The tension
+
+Ideally wiki content (the `.md` files the community edits) would live in
+`bincio_wiki/`, the container repo. The Astro app is a reusable engine;
+content is wiki-specific. Mixing them means content commits go into the
+`astro-bloomz` submodule history, and updating the engine requires care not
+to disturb content.
+
+Currently content is at `site/src/content/entries/` (inside the submodule).
+
+### Why symlinks failed
+
+Symlinking `bincio_wiki/pages/` → `site/src/content/entries/` was tried but
+abandoned: macOS's fsevents (used by Vite's file watcher) does not follow
+symlinks reliably, causing Astro's hot-reload and content layer to miss
+changes or crash.
+
+### Options
+
+**Option A — Astro glob `base` pointing outside `site/`**
+
+Change `content.config.ts` to use a relative or absolute path that escapes
+the `site/` directory:
+
+```ts
+loader: glob({ pattern: '**/*.md', base: '../pages' })
+```
+
+`../pages` from the Astro project root (`site/`) resolves to
+`bincio_wiki/pages/`. No symlinks. Content stays in the container repo.
+
+Risk: Vite (which Astro uses internally) may refuse to watch files outside
+the project root by default. This can be overridden with
+`server.watch.ignored` / `server.fs.allow` in `astro.config.mjs`, but needs
+testing. Build-time collection (no watch) is likely fine regardless.
+
+**Option B — Copy/sync at dev time**
+
+Keep content source at `bincio_wiki/pages/` (source of truth). Add a step to
+`dev.sh` that watches `pages/` and syncs changes to
+`site/src/content/entries/` (gitignored there). Build step copies before
+`astro build`.
+
+Edit server already reads `WIKI_PAGES_DIR` from the environment, so pointing
+it at `bincio_wiki/pages/` is a one-line change. The sync is the only new
+piece.
+
+Downside: a two-directory sync is extra moving parts; a crash or missed sync
+during dev means stale content in the browser.
+
+**Option C — Absorb Astro app into `bincio_wiki`**
+
+Remove the submodule entirely. Move Astro source into `bincio_wiki/src/`.
+Content and engine live together, content at `src/content/entries/`.
+
+Cleanest at runtime, but loses `astro-bloomz` as a reusable starting point
+for other sites. Only worth it if we never intend to fork the engine again.
+
+### Recommendation
+
+Try **Option A** first — it is a two-line change and, if Vite's file watcher
+cooperates, gives us exactly the right separation with minimal risk. If the
+watcher proves problematic in dev, fall back to **Option B**.
+
+---
+
+## Q2 — Subdirectory support in the edit panel
+
+### Current state
+
+The backend already handles subdirectory slugs fully:
+- `_SAFE_SLUG` regex allows `/` in slugs
+- Routes use `{slug:path}` so FastAPI preserves slashes
+- `_list()` uses `rglob("*.md")` — nested files are already listed
+- `_save()` calls `path.parent.mkdir(parents=True, exist_ok=True)`
+
+The frontend edit panel, however, only offers flat slug input. Work needed:
+- Allow the "new page" field to accept a slug with `/` (e.g. `archivio/2024/festa`)
+- Show nested entries grouped by prefix in the page list
+- Possibly add a folder picker or breadcrumb
+
+### Pictures
+
+Not yet addressed. Open questions:
+- Where are images stored? (options: `site/public/img/`, alongside content,
+  or a dedicated `bincio_wiki/assets/` tree)
+- How does the edit panel upload/reference them?
+- How are they referenced from markdown (`/img/foo.jpg` vs relative `./foo.jpg`)?
+- Are images versioned in git or stored out-of-band?