Add MkDocs documentation: architecture, deployment, development, decisions

docs/decisions/content-location.md

@@ -0,0 +1,42 @@
+# Content Location (resolved)
+
+!!! success "Resolved"
+    Option A was implemented. Content lives in `pages/` and `blog/` at the container repo root. Astro loads them via glob loaders with `base: '../pages'` and `base: '../blog'`. Vite is configured with `server.fs.allow: ['..']`.
+
+---
+
+This document records the design question that was open during early development and the options considered.
+
+## The question
+
+Where should wiki content (the `.md` files the community edits) live, and how should Astro load them?
+
+The constraint: Astro's rendering engine lives in the `site/` submodule (`brutsalvadi/astro-bloomz`). Content is wiki-specific and should not be committed to the engine's history.
+
+## Why symlinks failed
+
+Symlinking `bincio_wiki/pages/` → `site/src/content/entries/` was tried and 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 in dev mode.
+
+## Options considered
+
+**Option A — Astro glob `base` pointing outside `site/`** ✓ *chosen*
+
+```ts
+loader: glob({ pattern: '**/*.md', base: '../pages' })
+```
+
+`../pages` relative to `site/` resolves to `bincio_wiki/pages/`. No symlinks. Content stays in the container repo. Vite's `server.fs.allow: ['..']` is required to permit serving files outside the project root in dev.
+
+**Option B — Copy/sync at dev time**
+
+Keep source at `bincio_wiki/pages/`. Add a watcher step to `dev.sh` that syncs changes to `site/src/content/entries/` (gitignored there). Edit server already uses `WIKI_PAGES_DIR`.
+
+Downside: two-directory sync is extra moving parts; a crash means stale content.
+
+**Option C — Absorb Astro into `bincio_wiki`**
+
+Remove the submodule. Move Astro source into `bincio_wiki/src/`. Cleanest at runtime but loses the reusable engine submodule.
+
+## Outcome
+
+Option A works correctly. Both Vite's file watcher and Astro's content layer see changes to `pages/` and `blog/` in dev. The `contentDeleteWatcher` plugin handles the edge case of deleted files (which require clearing the data store to prevent stale entries).

docs/decisions/lingua.md

@@ -0,0 +1,31 @@
+---
+title: Lingua e Internazionalizzazione
+---
+
+# Lingua e Internazionalizzazione
+
+Questo wiki è principalmente in italiano. Di seguito le opzioni valutate e la decisione presa.
+
+## Opzioni considerate
+
+### A — Solo italiano (1–2 ore)
+Sostituire le ~8 stringhe di interfaccia in inglese con italiano. Tutto il contenuto viene scritto in italiano. Nessun cambiamento strutturale.
+
+### B — Italiano di default, lingue miste tolerate (zero effort)
+Il wiki è una raccolta piatta di pagine: chi scrive in italiano lo fa, chi vuole contribuire in inglese può farlo. I `[[WikiLink]]` funzionano per nome file indipendentemente dalla lingua del contenuto. Opzione adottata per ora.
+
+### C — Bilingue completo `/it/` e `/en/` (1–2 giorni di sviluppo)
+Astro 6 supporta l'i18n routing nativo. Richiederebbe:
+- Dividere `pages/` in `pages/it/` e `pages/en/`
+- Aggiornare la content collection e la generazione degli URL
+- Aggiungere un selettore di lingua nella nav
+- Decidere come i `[[WikiLink]]` attraversano i confini linguistici
+- Un indice semtree per lingua o condiviso
+
+Il punto 4 è quello genuinamente complesso: il sistema wikibonsai non ha una risposta standard per i link cross-language.
+
+## Decisione attuale
+
+**Opzione B.** Si scrive in italiano. Se il wiki cresce e serve un mirror curato in inglese, si migra a C. La migrazione da B a C è breaking (gli URL cambiano), ma gestibile quando ci sarà abbastanza contenuto da motivarla.
+
+Le stringhe dell'interfaccia possono essere tradotte in italiano in 30 minuti, indipendentemente dal resto.