From 7207cfdbd08225536aeb73b4d4971f570cd3df70 Mon Sep 17 00:00:00 2001
From: Klagarge <remi@heredero.ch>
Date: Sat, 10 Oct 2026 21:02:59 +0200
Subject: [PATCH] docs: update README and AGENT.md for the scripts layout

Assisted-by: Delta:zai-glm-5.3
---
 AGENT.md  | 21 +++++++++++++++---
 README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++----------
 2 files changed, 73 insertions(+), 14 deletions(-)

diff --git a/AGENT.md b/AGENT.md
index 7f83047..eefbc8e 100644
--- a/AGENT.md
+++ b/AGENT.md
@@ -1,5 +1,20 @@
 # Agent Rules for Yggdrasil Migration
 
-*   **Commit Policy**: Small conventional commits. One logical change per commit. Must be committed only once that step is verified and working. Append `Assisted-by: Delta:gemini-3.1-pro` to the footer.
-*   **Toolchain**: Pinned versions of `calepin` (0.0.61) and `typst` (0.15.1) are downloaded locally into `tools/`. Global installs must not be used by the build process.
-*   **Verification**: Ensure all builds pass locally (`just clean`, `just tools`, `just build`) before committing changes to track files correctly. Do not alter legacy documentation in `legacy_docs/`.
+*   **Commit Policy**: Small conventional commits. One logical change per
+    commit, committed only once that step is verified and working. End every
+    commit message with a blank line followed by an
+    `Assisted-by: Delta:zai-glm-5.3` footer.
+*   **Layout**: Sources live in `site/` (`calepin.toml` + `.typ` pages),
+    generated output in `public/` (gitignored), pinned binaries in `tools/`
+    (gitignored), helper scripts in `scripts/`, and the old Docsify
+    documentation stays untouched in `legacy_docs/`.
+*   **Toolchain**: `calepin` (0.0.61) and `typst` (0.15.1) are pinned in
+    `scripts/bootstrap.sh` and downloaded into `tools/` with checksum
+    verification. The build must never depend on global installs. CI installs
+    the same pinned versions by calling the same scripts.
+*   **Verification**: Before committing, run a fresh cycle: `rm -rf tools`,
+    then `just clean`, then `just build` — the build must succeed with no
+    calepin on `PATH`. Verify the served site (`just preview`): home 200,
+    category page 200, sub-page 200, missing page shows the 404 page,
+    `sitemap.xml` present. After every test/clean cycle `git status` must stay
+    clean.
diff --git a/README.md b/README.md
index 632815c..c087d34 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,64 @@
 # Yggdrasil
 
-A knowledge base migrated to [Calepin](https://vincentarelbundock.github.io/calepin/), a Typst-based static site generator.
+Personal knowledge base built as a static website with
+[Calepin](https://vincentarelbundock.github.io/calepin/), a Typst-based static
+site generator.
 
-## Quick Start
+## Layout
 
-1.  **Dependencies**: You need the `just` command runner.
-2.  **Bootstrap Toolchain**: Run `just tools`. This downloads pinned versions of `calepin` and `typst` into the `tools/` directory. No global installation is required.
-3.  **Build**: Run `just build` to generate the static site in the `public/` directory.
-4.  **Preview**: Run `just preview` or `just watch` to view the site locally.
+- `site/` — website sources: `calepin.toml` + `.typ` pages
+- `public/` — generated site (gitignored)
+- `tools/` — pinned `calepin` and `typst` binaries (gitignored, downloaded on demand)
+- `scripts/` — helper scripts used by the Justfile and CI
+- `legacy_docs/` — the old Docsify documentation, kept unmodified for reference
 
-## Adding Content
+## Quick start
 
-*   Source files are located in `site/`.
-*   To add a page, create a `.typ` file and link it in the `site/calepin.toml` configuration under `[sidebar]` or `[pages]`.
-*   Categories are structured as subdirectories (e.g., `site/thermo/`) with their own `index.typ`.
+`just` is the only prerequisite — the toolchain is downloaded and
+checksum-verified into `tools/` on first use (no global installs, no cargo):
+
+    just          # list recipes
+    just tools    # download the pinned toolchain into tools/
+    just build    # compile site/ into public/
+    just preview  # build, then serve the site locally
+    just watch    # rebuild on change and serve
+    just clean    # remove public/ and build caches
+
+## Adding a page
+
+Create `site/<category>/<page>.typ`:
+
+```typst
+#set document(title: [Page title])
+#metadata((title: "Page title", translation_key: "category-page")) <website-metadata>
+
+#title()
+
+= Page title
+
+Content…
+```
+
+and reference it in `site/calepin.toml`:
+
+```toml
+[[sidebar.section.item]]
+target = "<category>/<page>.typ"
+```
+
+Sidebar labels come from the page's `#metadata(...)` line, not from the config.
+
+## Adding a category
+
+1. Create `site/<category>/` with an `index.typ`, using
+   `#metadata((title: "Overview", ...))` for its sidebar label.
+2. Add a `[[sidebar.section]]` named after the category in `calepin.toml`,
+   listing the index page and its sub-pages.
 
 ## Deployment
 
-The site is built as a set of static files in the `public/` folder. A Gitea Actions workflow `.gitea/workflows/build.yml` runs on push to build and upload these files as an artifact. They can be deployed to any static host.
+`just build` produces a fully static site in `public/`: HTML pages plus
+`sitemap.xml`, `robots.txt`, and `llms.txt`. The Gitea Actions workflow in
+`.gitea/workflows/build.yml` builds the site on every push with the same
+pinned toolchain and uploads `public/` as an artifact for deployment to any
+static host.