docs: publish the user documentation as a Zensical site on GitHub Pages

.github/workflows/docs.yml

@@ -0,0 +1,38 @@
+name: docs
+
+# Builds the user documentation site on every pull request, and publishes it to
+# GitHub Pages on each push to develop. Zensical is the version pinned in
+# uv.lock, installed by `mise run docs:build`.
+on:
+  pull_request:
+  push:
+    branches: [develop]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac # v2
+      - run: mise run docs:build
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
+        if: github.event_name == 'push' && github.ref == 'refs/heads/develop'
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/develop'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5
+        id: deployment

.gitignore

@@ -16,3 +16,6 @@ __pycache__/
 # Local server data
 /data/
 .env
+
+# Documentation site, built by `mise run docs:build`
+/site/

AGENTS.md

@@ -17,6 +17,15 @@ decision records, documentation, code, comments and commit messages. The only
 exception is user-facing memory content, whose language is a store setting
 (for example French for the `accounting-firm` preset's synthetic data).
 
+## User documentation
+
+The user documentation site is built from `docs/` with Zensical
+(`zensical.toml`, `mise run docs:build`) and published to GitHub Pages from
+`develop`. A milestone is not delivered until the site documents what it adds.
+Each task that changes user-visible behaviour (a command, an option, an
+output, an installation or upgrade step, a connector flow) updates its page in
+the same change, and a new page goes into the `nav` of `zensical.toml`.
+
 ## Tests
 
 Tests are either unit or integration tests, and live in the matching folder:

README.md

@@ -8,8 +8,12 @@ engagements. With tiroir, the organisation of memory is configuration: you
 declare your drawers, and tiroir handles storage, indexing, retrieval, context
 injection and sync.
 
-> **Status: design phase.** Nothing is usable yet. The requirements are being
-> written; code follows once the design is approved.
+**Documentation: [ancelin-code.github.io/tiroir](https://ancelin-code.github.io/tiroir/)**
+
+> **Status: 0.1.0.** One server for a team, run with Docker Compose behind
+> Caddy, administered from the command line, and connected to Claude Desktop
+> with tools to search, read and log memory. More surfaces follow, milestone
+> by milestone.
 
 ## Principles
 
@@ -29,29 +33,46 @@ injection and sync.
 - **Humans own the synthesis.** Logs are append-only, and summaries change only
   after you confirm.
 
+## Quickstart
+
+On a VPS with Docker Compose and a domain name pointing to it:
+
+```sh
+git clone https://github.com/ancelin-code/tiroir.git && cd tiroir
+cp .env.example .env    # set TIROIR_DOMAIN and TIROIR_ACME_EMAIL
+docker compose pull && docker compose up -d
+docker compose exec tiroir tiroir admin init
+```
+
+Then follow the documentation:
+
+- [Install tiroir on a VPS](https://ancelin-code.github.io/tiroir/install/vps/):
+  the stack, the first administrator, a member and a store.
+- [Connect Claude Desktop](https://ancelin-code.github.io/tiroir/connect/claude-desktop/):
+  add the server as a custom connector and sign in.
+- [CLI reference](https://ancelin-code.github.io/tiroir/reference/cli/): the
+  administration commands.
+
 ## Planned surfaces
 
-- An MCP server for Claude Desktop and Claude Code.
-- A Claude Code adapter with automatic context injection.
+- A member CLI and the Claude Code plugin with automatic context injection.
 - A guided setup skill that interviews you and designs your schema.
-- A CLI for setup, indexing, search, validation, sync, migration and erasure.
-- Presets for developers and accounting firms, with synthetic data.
+- Presets beyond accounting firms, starting with developers.
 
-## Install
+## Contributing
 
-- [Install tiroir on a VPS](docs/install/vps.md): the Compose stack behind
-  Caddy, the first administrator, a member and a store from a preset.
-- [Connect Claude Desktop](docs/connect/claude-desktop.md): add the server as
-  a custom connector and sign in.
-- [Skeleton exit check](docs/milestones/skeleton-exit-check.md): the checklist
-  run against a real server at the end of the first milestone.
+`mise run check` runs every check, `mise run stack` builds the image from the
+working tree and starts the stack, and `mise run docs:serve` previews the
+documentation site.
 
 ## Project documents
 
 - [Product brief](docs/brief.md): vision, principles and constraints.
 - [Requirements](delivery/prd.md): what v1 must do, checkably.
 - [Prior art review](docs/research/prior-art.md): what we learned from existing
   agent memory projects.
+- [Skeleton exit check](docs/milestones/skeleton-exit-check.md): the checklist
+  run against a real server at the end of the first milestone.
 
 ## Licence
 

delivery/tasks/docs-001.md

@@ -0,0 +1,76 @@
+---
+id: docs-001
+title: Publish the user documentation as a Zensical site on GitHub Pages
+type: docs
+epic: docs
+depends_on: []
+parallel: true
+conflicts_with: []
+tier: build
+review: []
+---
+
+## Context
+
+The 0.1.0 release works end to end, and its guides (`docs/install/vps.md`,
+`docs/connect/claude-desktop.md`) sit as loose Markdown. Users need a site, and
+every later milestone must update it. Delivery Kit's launch plan picked
+Zensical on GitHub Pages with the `llms.txt` output; follow the same choice.
+The requirements are in [the PRD](../prd.md).
+
+## Scope
+
+Files this task is expected to touch:
+
+- `zensical.toml` (site configuration and navigation)
+- `docs/index.md` (home page: what tiroir is, who it is for, where to start)
+- `docs/install/vps.md` (the image is now published: pull it instead of
+  building, in the start and upgrade steps; `TIROIR_TAG` takes `v0.1.0` style
+  tags or `latest`)
+- `docs/connect/claude-desktop.md` (only what the site needs, such as links)
+- `docs/reference/cli.md` (user-facing CLI reference, written for users from
+  `delivery/contracts/cli.md`, not copied from it)
+- `.github/workflows/docs.yml` (build on pull requests, deploy to GitHub Pages
+  from `develop`)
+- `pyproject.toml`, `uv.lock` (Zensical as a pinned dev dependency, with its
+  licence checked by `mise run licenses`)
+- `mise.toml` (`docs:build` and `docs:serve` tasks)
+- `README.md` (slim: pitch, quickstart, link to the site; fix the stale
+  "design phase, nothing is usable yet" line)
+- `AGENTS.md` (a short rule: a milestone is not delivered until the site
+  documents what it adds; each task that changes user-visible behaviour
+  updates its page)
+- `delivery/tasks/docs-001.md`
+
+Out of scope:
+
+- ADRs, contracts, the brief, research notes and milestone notes stay in the
+  repository and out of the site's navigation.
+- A custom domain, search plugins beyond Zensical's defaults, a theme redesign.
+- Documenting features that do not exist yet.
+
+## Acceptance criteria
+
+- `mise run docs:build` builds the site with no warning, and the output holds an
+  `llms.txt`.
+- The navigation holds exactly: Home, Install (VPS), Connect (Claude Desktop),
+  Reference (CLI).
+- `docs/install/vps.md` no longer says that no image is published, and starts
+  and upgrades the stack with `docker compose pull` and `up -d`, with
+  no `--build`; `compose.yaml` still builds locally for contributors.
+- The CLI reference lists every command of the CLI contract with its arguments
+  and an example, and matches the real `tiroir --help` output.
+- The workflow builds on pull requests and deploys to GitHub Pages only on push
+  to `develop`; Zensical is pinned to an exact version.
+- The README links to the site and to nothing that moved without a working
+  target.
+- `AGENTS.md` states the per-milestone documentation rule.
+- `mise run check` and `mise run licenses` pass.
+
+## Validation
+
+```sh
+mise run docs:build
+mise run check
+mise run licenses
+```

docs/index.md

@@ -0,0 +1,40 @@
+# tiroir
+
+**Configurable, scoped memory for AI agents.** *Tiroir* is French for *drawer*.
+
+tiroir gives AI agents a memory organised the way their users actually work. A
+developer thinks in repositories, an accountant in client files, a consultant
+in engagements. With tiroir, that organisation is configuration: a store holds
+drawers, and tiroir handles storage, indexing and retrieval. Memory is plain
+Markdown in a Git repository on your own server; nothing leaves it.
+
+## Who it is for
+
+- **Administrators** who run one tiroir server for themselves or their team, on
+  a VPS with Docker Compose.
+- **Members** of that team who connect Claude Desktop to the server, then ask
+  Claude to search their memory and to log what happened.
+
+## What version 0.1.0 does
+
+- One server, started with Docker Compose behind Caddy, which obtains the HTTPS
+  certificate by itself. The image is published for `amd64` and `arm64`.
+- Members, personal and team stores, and read or write access, managed with
+  the [administration CLI](reference/cli.md) inside the container.
+- A store starts from a preset. The one bundled preset, `accounting-firm`,
+  comes with invented client drawers to try the server on.
+- Claude Desktop connects as a custom connector, signs in with OAuth, and gets
+  four tools: search, read, log, and the list of the stores the member can
+  reach.
+
+## Where to start
+
+1. [Install tiroir on a VPS](install/vps.md): the stack, the first
+   administrator, a member and a store.
+2. [Connect Claude Desktop](connect/claude-desktop.md): add the server as a
+   custom connector and sign in.
+3. [CLI reference](reference/cli.md): every administration command, with its
+   arguments and an example.
+
+tiroir is open source under the Apache-2.0 licence; its code is on
+[GitHub](https://github.com/ancelin-code/tiroir).

docs/install/vps.md

@@ -22,8 +22,10 @@ database server and sends no e-mail.
 
 ## 1. Get the stack
 
-The stack is three files: `compose.yaml`, `deploy/Caddyfile` and `.env`. Clone
-the repository on the VPS:
+The stack is three files: `compose.yaml`, `deploy/Caddyfile` and `.env`. The
+tiroir image itself is published at `ghcr.io/ancelin-code/tiroir`, for `amd64`
+and `arm64`, so nothing is built on the VPS. Clone the repository on the VPS to
+get the three files:
 
 ```sh
 git clone https://github.com/ancelin-code/tiroir.git
@@ -42,18 +44,18 @@ Edit `.env`:
 |---|---|
 | `TIROIR_DOMAIN` | Your domain name, without `https://`. The server's public address, `https://<domain>`, is also its OAuth issuer, so it cannot change later without every member signing in again. Use `localhost` to try the stack on your own machine. |
 | `TIROIR_ACME_EMAIL` | The e-mail address given to the certificate authority. |
-| `TIROIR_TAG` | The tag given to the image built in step 3. Leave `latest`. |
+| `TIROIR_TAG` | The image tag to run: `latest` follows the newest release, a release tag such as `v0.1.0` stays on that release until you change it. |
 | `TIROIR_PROXY_SUBNET` | The private subnet of the stack's network, where Caddy runs. Leave the default unless it clashes with a network of yours. |
 
 ## 3. Start the stack
 
 ```sh
-docker compose up -d --build
+docker compose pull
+docker compose up -d
 ```
 
-No tiroir image is published yet, so Compose builds it from the cloned
-repository (a few minutes on the first run), pulls Caddy, then starts both.
-Check that they run and that the server answers through Caddy:
+Compose pulls the tiroir image for the tag in `.env` and the Caddy image, then
+starts both. Check that they run and that the server answers through Caddy:
 
 ```sh
 docker compose ps
@@ -122,12 +124,14 @@ To force it, run `docker compose exec tiroir tiroir admin index`.
 
 ## 7. Upgrade
 
-In this version, an upgrade fetches the new code, rebuilds the image and
-restarts the stack:
+An upgrade updates the stack files, pulls the new image and restarts the
+stack. With `TIROIR_TAG=latest`, this moves to the newest release; with a
+release tag, change `TIROIR_TAG` in `.env` to the new release first.
 
 ```sh
 git pull
-docker compose up -d --build
+docker compose pull
+docker compose up -d
 ```
 
 The server migrates its database at start, and logs a warning if the database