@nurix/etna 0.18.20 → 0.18.22

package/data/harnesses/mobile/rules/database.md

@@ -0,0 +1,38 @@
+# Database
+
+Fixed conventions for relational schemas — table/column/index **names**, the **key vocabulary** (`id` / `slug` / `label`), column types, and Drizzle mirrors — so the same concept carries the same name in **every** Nurix project. This is a cross-project consistency rule: **one concept, one name, everywhere** — never `slug` in one repo and `handle` / `key` / `code` in another. General code naming (variables, files, casing) is [`nomenclature.md`](nomenclature.md); this rule owns the database.
+
+Written for SQLite / Cloudflare D1 + Drizzle (the concrete types below). The **names and key vocabulary are engine-agnostic** — a Postgres project keeps the same column names and semantics with native types (`uuid`, `timestamptz`, `boolean`).
+
+## Keys & the shared vocabulary
+
+Three column roles are fixed across every table and every project:
+
+- **`id`** — the primary key, **always a UUID** (`TEXT PRIMARY KEY` on D1, `uuid` on Postgres). Never a synthetic or natural key (`type_page_button`, `human:default` are ❌). Runtime rows mint a UUIDv7; seed rows derive a deterministic UUIDv5 of the natural key so re-seeds stay stable. Never mix synthetic and UUID ids in one table.
+- **`slug`** — the **stable key other rows reference**: `UNIQUE`, lowercase `snake_case`. **Foreign keys point at `slug`, not `id`.** One concept = one slug name across every table and repo. ❌ Never rename this role `handle`, `key`, `code`, or `name` in a different project — it is always `slug`.
+- **`label`** — the **human display name**. Always `label` — ❌ never `name`, `title`, or `display_name`.
+
+Reference columns name what they point at: `<entity>_id` for a UUID-PK reference (`user_id`, `app_id`), `<entity>_slug` for a slug reference (`source_slug`).
+
+- **Enforced** (the referenced row must exist) → a real `FOREIGN KEY (<x>_slug) REFERENCES <table>(slug)`.
+- **Drift-tolerant** (a controlled-vocabulary value that may fall off-list) → a plain value column, **no** FK, paired with an `is_*` boolean recording whether the value is in the canonical set.
+
+## Naming
+
+- **Tables** — `snake_case`, plural noun for what they hold (`users`, `apps`, `devices`).
+- **Junction (M:N) tables** — `<entityA>_<entityB>_map`, **always**, even when the join carries its own columns; singular stems, owning/anchor entity first (`app_user_map`, `app_device_map`). ❌ Never a "nice" noun (`members`, `installs`, `memberships`, `enrolments`) — the name must read as a join, and a reviewer should know both sides from it.
+- **Columns** — `snake_case`; booleans `is_*` / `has_*`; timestamps `created_at` / `updated_at`; foreign keys `<entity>_id`.
+- **Indexes** — `<table>_<col(s)>_idx`; unique `<table>_<col(s)>_unique`; a junction's composite unique reads `<table>_<colA>_<colB>_unique` (`app_user_map_app_user_unique`).
+- **Drizzle mirror** — the exported object is the camelCase table name (`app_user_map` → `appUserMap`); column props are the camelCase of the column (`created_at` → `createdAt`). The `sqliteTable("…")` string and every index name must match the DDL (`init.sql`) exactly — the schema-parity boundary.
+
+## Column types (SQLite / D1)
+
+- **Timestamps** — `created_at` + `updated_at`, both `TEXT NOT NULL DEFAULT (datetime('now'))`, on **every** table — except append-only logs, which carry only `created_at`.
+- **Booleans** — `INTEGER`, named `is_*` / `has_*` (Drizzle `integer(…, { mode: "boolean" })`).
+- **JSON** — `TEXT` (Drizzle `text(…, { mode: "json" })`).
+
+## Vocabulary / lookup tables
+
+A controlled-vocabulary table (statuses, kinds, categories) follows a fixed shape: `id` (UUID) · `slug` (UNIQUE) · `label` · optional `description` · `status` · timestamps.
+
+- **Seeds are generated, never hand-written** — the source of truth is a CSV or a shared package; a generator emits the `*.seed.sql` with UUIDv5 ids and an idempotent `ON CONFLICT(slug)` upsert that preserves live counts / admin-tuned columns. Hand-editing seed SQL is ❌ — regenerate it.

package/data/harnesses/mobile/rules/general.md

@@ -1,5 +1,7 @@
 # General Standards
 
+Runtime versions and the canonical package list — the workspace baseline every Nurix code harness loads. Web-frontend/styling conventions are [`frontend.md`](frontend.md); the Express server and the API response envelope are [`express.md`](express.md).
+
 ## Runtime Versions
 
 - **Node.js:** 22 LTS (latest)
@@ -45,43 +47,3 @@ No alternatives. Just use these.
 | fast-deep-equal          | ^3.1.3    | Deep equality checks   | lodash.isEqual             |
 | @ngneat/falso            | latest    | Fake data generation   | @faker-js/faker, chance    |
 | pino                     | ^10.1.0   | Logging                | winston                    |
-
-## Frontend
-
-Tailwind v4 + shadcn-based UI; conventions below.
-
-- **Build every UI through the `design` skill** — route the brief through it instead of hand-rolling layouts; it owns the archetype, personality tokens, and `@nurix/components` wiring.
-- **Light mode is the default** — design for the light theme as the default; dark mode is opt-in, never the default.
-- **@nurix/\* are restricted-scope npm packages** — installed from the npm registry, auto-authed by a read token in `~/.npmrc`. Just attempt the install; the token authenticates you automatically. Don't pre-empt or second-guess it. If the install actually fails, flag it to the user — never reach for alternatives, a substitute package, or `npm login`.
-- **@nurix/components** — the UI component library (restricted-scope npm package, pre-built); import by subpath, e.g. `@nurix/components/button`.
-- No components.json / shadcn CLI scaffold (.tsx, not .jsx) — consume the prebuilt library; never `npx shadcn add`.
-- Vite: `@tailwindcss/vite` + `@vitejs/plugin-react-swc`. Pin react / react-dom / react/jsx-runtime / react/jsx-dev-runtime to the app's single copy via `resolve.alias` (@nurix/\* ship nested react — keep one hook dispatcher).
-- Tailwind v4, CSS-only (no tailwind.config.js, no PostCSS): styling runs through the `@tailwindcss/vite` plugin.
-- CSS entry `globals.css`, imports in order — `@import "./personality.css"` (token source) → `@import "tailwindcss"` → the library's `styles.css` — then `@theme inline {…}` mapping vars to tokens.
-- Tokens: CSS vars in `:root, :root[data-theme="light"]` + the archetype selector `[data-style="…"]` (personality.css), consumed as semantic Tailwind tokens (bg-card, text-foreground). Honor the archetype's radius/theme decisions (e.g. re-assert `--radius-*` to 0 for a flat archetype; add `@custom-variant dark` only if the project opts into dark mode, and keep light as the default). The library bundles class-variance-authority, clsx, tailwind-merge.
-- Plus general styling rules (spacing in 2/4/6/8, object-cover, truncate, motion, color tokens — never hardcoded hex in components).
-
-## Express 5.x
-
-```javascript
-app.use(cors({ origin: process.env.FRONTEND_URL }));
-app.use(compression());
-app.use(express.json({ limit: '10mb' }));
-app.use(rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));
-```
-
-- Middleware order: body parsers → custom middleware → routes → error handlers (centralized, last). Auth via middleware. Use Express Router for modular routes.
-
-## API Response Format
-
-```json
-{
-  "status": 1,
-  "message": "Message sent successfully",
-  "data": { "delivered": [{ "user@example.com": 2 }] }
-}
-```
-
-Error: `{ "status": 0, "message": "Error description", "data": null }`
-
-HTTP codes: `200`, `201` (created), `400`, `401` (not authenticated), `403` (not authorized), `404`, `500`

package/data/harnesses/mobile/rules/nomenclature.md

@@ -31,11 +31,4 @@
 
 ## Database
 
-Naming for D1 tables, columns, indexes, and their Drizzle mirrors. (For column **types** — PK shape, timestamp columns — see the Cloudflare D1 Schema rule, not here; this section governs names only.)
-
-- **Tables** : snake_case. Entity / hub tables use the plural noun for the thing they hold. Examples: `users`, `apps`, `devices`, `services`.
-- **Junction (M:N) tables** : name a many-to-many join `<entityA>_<entityB>_map` — **always**, even when the join carries its own columns (a `role`, a secret, a status). The `_map` suffix is the signal that a row is a relationship, not an entity; extra attributes on the join do **not** earn it a standalone noun. Use the **singular** stem of each side, owning/anchor entity first (mirror the existing tables — `app_*`). Examples: `app_user_map` (apps ⨯ users), `app_device_map` (apps ⨯ devices), `app_service_map` (apps ⨯ services).
-  - ❌ Don't invent a "nice" noun for a junction — no `members`, `installs`, `memberships`, `enrolments`. A reviewer should read the table name and know both sides and that it's a join.
-- **Columns** : snake_case. Foreign keys are `<entity>_id` (`user_id`, `app_id`, `device_id`, `service_id`). Booleans follow the boolean rule (`is_*`/`has_*`); timestamps are `created_at` / `updated_at`.
-- **Indexes** : `<table>_<col(s)>_idx`; unique indexes `<table>_<col(s)>_unique`. The composite unique on a junction reads `<table>_<colA>_<colB>_unique` — e.g. `app_user_map_app_user_unique`, `app_device_map_device_app_unique`.
-- **Drizzle mirror** : the exported table object is the camelCase of the snake_case table name (`app_user_map` → `appUserMap`); column TS properties are the camelCase of the column (`created_at` → `createdAt`, `service_key` → `serviceKey`). The snake_case string passed to `sqliteTable("…")` and every index name must match `seed/init.sql` exactly (the G1 schema-parity boundary).
+Table, column, index, and key naming for relational schemas — the `id` / `slug` / `label` vocabulary, junction `_map` tables, and Drizzle mirrors — lives in [`database.md`](database.md), the cross-project database conventions rule. Kept there, not here, so there is one canonical home and the same concept carries the same name in every project.

package/data/harnesses/mobile/rules/nustack.md

@@ -0,0 +1,150 @@
+# Nustack — `@nurix/*` Packages: naming, monorepo layout, and publishing
+
+How a `@nurix/*` multi-package repo is **named**, **structured**, and **shipped**. For consuming an already-published `@nurix/*` package (auth, install, imports), see the Consuming section of [`typescript.md`](typescript.md).
+
+---
+
+## 1. Package naming
+
+Every workspace package is scoped to **`@nurix/`**. The segment after the scope encodes **intent** — the dot vs. hyphen is semantic, not cosmetic:
+
+| Form                                            | Meaning                                                                                                                                                                                  | Examples                                                                                                           |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `@nurix/workflows-sdk` (hyphen, single segment) | The **published, externally-destined** surface. A clean `@nurix/*` name is a published _contract_ — changing an export or peer dep is a breaking change for consumers outside this repo. | `@nurix/workflows-sdk`                                                                                             |
+| `@nurix/workflows.<name>` (dot separator)       | **Internal** to the workflows product — `private: true`, refactor freely, no external consumers.                                                                                         | `@nurix/workflows.agent-core`, `.worker`, `.gateway`, `.secrets`, `.connector`, `.playground`, `.playground-tests` |
+| `@nurix/<name>` (plain, no `workflows` prefix)  | Cross-repo **shared libs** owned _elsewhere_ and merely consumed here — never renamed.                                                                                                   | `@nurix/contracts`, `@nurix/components`                                                                            |
+
+- The `<name>` segment is always **kebab-case** (`agent-core`, `playground-tests`).
+- The dot is **not** a path separator, so subpath exports still resolve: `@nurix/workflows.agent-core/nodes`.
+- The dot tracks "internal product package," not the `private` flag exactly — `@nurix/workflows.secrets` is `private: false` because it's extraction-bound (slated to move to a sibling repo/namespace), yet still wears the dotted internal name. Today `-sdk` is the only clean published form.
+
+**Naming a new package:** internal to this repo? → `@nurix/workflows.<thing>`, `private: true`, kebab-case `<thing>` (the default). Externally consumed contract? → clean `@nurix/<thing>` (rare). Shared lib from another repo? → keep its existing `@nurix/<name>`.
+
+---
+
+## 2. Monorepo & package boundaries
+
+One `tsconfig.base.json` at the repo root is the **single owner of TS policy** — the strict set (see [`typescript.md`](typescript.md)), `target`, and any option uniform across packages (here, `module`/`moduleResolution`). Each package's `tsconfig.json` is thin: it `extends` the base, then adds only its own *coordinates* (`rootDir`/`outDir`/`include`) and genuine *environment* overrides (`lib`/`types`/`jsx`, plus `module`/`moduleResolution` when a package's module system genuinely differs — a Worker, browser, or NodeNext package). That is environment, not policy. Never re-declare or weaken a *policy* option locally (no per-package `strict: false`, no widening `noUncheckedIndexedAccess`). A framework that owns its own base (e.g. an Astro app on `astro/tsconfigs/strict`) is the one allowed exception.
+
+- **Internal packages are source-first.** A `private: true` workspace package exposes its API through the `exports` field pointing at TypeScript source (`"types"`/`"default"` → `./src/index.ts`) — consumed across the workspace with **no build step**. Prefer the `exports` field; don't add a bare `main`/`module` to new packages. Add one typed subpath per public surface (`"./nodes": { "types": "./src/nodes/index.ts", "default": "./src/nodes/index.ts" }`); consumers import the subpath, **never** a deep relative path into another package's `src/`.
+- **Published packages build to `dist` — never ship raw `src`.** The moment a package crosses a publish boundary (`private: false`), it compiles with `tsc` (`declaration: true`, `declarationMap: true` from the base), ships `files: ["dist"]`, and points `exports`/`types` at `./dist/*` (use `publishConfig.exports` to swap source→dist on publish if the dev entry stays on source). `prepublishOnly` runs the build.
+- **Declare host singletons as `peerDependencies`** on published libraries (`react`, `react-dom`, the framework client) so consumers keep one copy; never bundle them. Apps depend on them directly.
+- **Single-source shared dep versions with pnpm `catalog:`** — `typescript`, `zod`, `vitest`, `react`, type packages. One version per dependency across the workspace so every package's types resolve identically; no per-manifest version drift.
+- **Reach for TS project references only when it hurts** — adopt `references` once the typecheck/build graph is slow enough to feel. Until then, `pnpm -r typecheck` over independent `extends` configs is the correct default.
+
+---
+
+## 3. Publishing & the release pipeline
+
+`@nurix/*` packages publish to **npmjs.org with `restricted` access** — only npm users with read rights to the `nurix` org can install them. Reference implementations: `~/dev/components` (`@nurix/components`, library) and `~/dev/etna/packages/cli` (`@nurix/etna`, CLI).
+
+### 3.1 Prerequisites (one-time, org-wide)
+
+1. **npm org `nurix`** exists and you're a member with publish rights — <https://www.npmjs.com/settings/nurix/packages>.
+2. **An npm automation token** with `Read and write` for the `nurix` scope — npm → Generate New Token → Automation.
+3. **The token added as a GitHub Actions secret** named `NPM_PUBLISH_TOKEN` on every publishing repo. `NPM_PUBLISH_TOKEN` is the convention; pick another name only with a strong reason.
+
+### 3.2 `package.json` — required fields
+
+```jsonc
+{
+  "name": "@nurix/<package-name>", // The scope makes it discoverable to org members.
+  "version": "0.1.0",              // Start at 0.1.0; the workflow bumps from here.
+  "private": false,                // MUST be false (or omitted). `npm publish` refuses if true.
+  "publishConfig": { "access": "restricted" }, // Scoped + private: only org members can install.
+  "files": ["dist"]                // Whitelist of what ships. Anything outside is excluded.
+}
+```
+
+- **`publishConfig.access`** — `"restricted"` (recommended): visible only to `nurix`-org readers. `"public"`: world-readable (free, but only if you mean it). Omitting it on a scoped package defaults to `restricted`; be explicit anyway.
+- **`files`** — without it, npm publishes everything not in `.gitignore`, **including source**. Library → `["dist"]`; CLI (etna) → `["bin/", "data/", "README.md"]`. Don't list `package.json`/`README.md` — npm always includes them.
+- **Build hooks** — `prepack` for build steps that must produce files in `files` (also runs on install-as-git-dep); `prepublishOnly` for publish-only steps. Either alone is fine; `@nurix/components` runs both.
+- **Other useful fields** — `type: "module"`, `engines.node`, `bin` (CLIs), `main`/`module`/`types`/`exports` (libraries), `sideEffects: ["**/*.css"]`, `repository` (with `directory` for monorepos), `license: "UNLICENSED"`.
+
+### 3.3 The publish workflow (generic template)
+
+The dual-trigger pattern: a push to the default branch auto-ships a patch; a manual dispatch picks minor/major.
+
+```yaml
+name: Publish to npm
+on:
+  push:
+    branches: [dev]               # your default branch
+    paths:                        # ONLY paths that change what ships — else every README edit publishes
+      - 'src/**'
+      - 'scripts/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - '.github/workflows/publish.yml'
+  workflow_dispatch:
+    inputs:
+      bump: { description: 'Version bump', type: choice, options: [patch, minor, major], default: patch }
+permissions: { contents: write }  # push the version-bump commit + tag
+concurrency: { group: publish, cancel-in-progress: false }  # monorepo: group: publish-<pkg>
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with: { fetch-depth: 0, token: '${{ secrets.GITHUB_TOKEN }}' }
+      - uses: actions/setup-node@v5
+        with: { node-version: 22, registry-url: 'https://registry.npmjs.org' }  # writes .npmrc using $NODE_AUTH_TOKEN
+      - run: npm ci                 # skip ONLY if the build is pure-Node with no deps (e.g. @nurix/etna)
+      - run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - run: npm version ${{ inputs.bump || 'patch' }} -m "chore: release v%s [skip ci]"
+      - run: npm publish            # prepublishOnly / prepack runs the build
+        env: { NODE_AUTH_TOKEN: '${{ secrets.NPM_PUBLISH_TOKEN }}' }
+      - run: git push --follow-tags # pushes the bump commit AND the v<version> tag npm created
+```
+
+**Why dual-trigger is safe** — three safeguards prevent an infinite publish loop: (1) `paths:` scopes the push trigger to artifact-affecting files; (2) `[skip ci]` in the bump commit makes GitHub skip the workflow that bump would otherwise re-trigger; (3) `concurrency: cancel-in-progress: false` queues near-simultaneous merges instead of racing for a version number.
+
+**`registry-url` is load-bearing** — without `registry-url: https://registry.npmjs.org` on `setup-node`, it never writes the `.npmrc` line that uses `$NODE_AUTH_TOKEN`, and the publish falls back to anonymous auth and fails.
+
+### 3.4 The three ways to ship
+
+- **A. Auto on merge (common).** Land on the default branch; if a `paths:`-filtered file changed, the workflow fires and ships a patch.
+- **B. Manual dispatch (minor/major).** **Actions → Publish to npm → Run workflow**, pick `bump = minor|major`.
+- **C. Local (CI down / one-off):** `npm version <patch|minor|major>` → `npm publish` → `git push --follow-tags`.
+
+Local auth uses two tokens, two homes: a **read** token in `~/.npmrc` (`//registry.npmjs.org/:_authToken=…`) for `npm install`, and `NPM_PUBLISH_TOKEN` as an env var (sourced from `~/.zsh_secrets` or equivalent, **not** in `.npmrc` or the repo) for `npm publish`.
+
+> **Agent guard — if `NPM_PUBLISH_TOKEN` isn't in the environment, do not work around it.** No `npm login` to swap the user's auth, no rewriting `~/.npmrc`, no substituting the read token (it lacks publish rights → `403`), no `--registry` overrides, no temp-file token. Instead **stop and report**: "This repo can't publish locally — `NPM_PUBLISH_TOKEN` isn't set. Source `~/.zsh_secrets` (or wherever you keep it) and re-run, or trigger the CI workflow." Some users publish exclusively from CI — that's the default path for a reason.
+
+Verify after any flow: `https://www.npmjs.com/package/@nurix/<name>` and a clean-dir `npx @nurix/<name>@latest`.
+
+### 3.5 Monorepo deviations
+
+When the package lives in `packages/<pkg>/` of a multi-package repo:
+
+- **`working-directory: packages/<pkg>`** on the bump and publish steps so they operate on the right `package.json`.
+- **Scoped concurrency** — `group: publish-<pkg>` lets sibling packages publish in parallel.
+- **Tag prefix — only with multiple tagging packages.** `npm version --tag-version-prefix="<pkg>-v"` (→ `<pkg>-v0.2.0`) is worth it only when more than one package cuts release tags, so they don't collide. A single publishable package (etna's case, even though it's laid out as a monorepo) uses plain `v0.2.0`.
+
+A repo with one publishable package only needs `working-directory`; skip the prefix, and concurrency scoping is optional.
+
+### 3.6 Common pitfalls
+
+- **402 Payment Required** — `access: "public"` on an org without a plan for free public scoped packages. Use `"restricted"` (or upgrade the plan).
+- **403 Forbidden** — `NPM_PUBLISH_TOKEN` missing/wrong, or its user lacks `nurix` write access, or it's a read-only (not Automation) token.
+- **"Cannot publish over previously published version x.y.z"** — a bump ran but publish failed and was re-run without rebasing. `git reset` the bump and let CI re-bump, or `npm version patch && git push --follow-tags && npm publish`.
+- **Publish succeeds but `npx @nurix/foo` is "command not found"** — no `bin` field, or `bin` points outside `files`, or the script is missing its `#!/usr/bin/env node` shebang.
+- **"Git working directory not clean" on `npm version`** — the checkout has untracked/modified files; build only into `.gitignore`d paths (the components repo builds into `dist/`).
+- **Published tarball contains source** — missing `files` in `package.json`. Add `["dist"]` and republish.
+- **Auto-publish fires too often** — no `paths:` filter or one that's too broad. Tighten it to artifact-affecting files, or drop the push trigger for `workflow_dispatch`-only.
+- **Workflow loops forever** — the bump commit lacks `[skip ci]`. Invoke `npm version` with `-m "chore: release v%s [skip ci]"`.
+- **A normal commit silently skips its own push** — the inverse trap. GitHub scans the head commit's **whole message** (subject _and_ body) for skip directives (`[skip ci]`, `[ci skip]`, `[no ci]`, `[skip actions]`, `***NO_CI***`). If any hand-written commit merely _mentions_ the literal token in prose, the entire push is skipped and the publish never fires (symptom: branch moved, paths matched, Actions on — yet zero runs for the SHA). Never write the literal token in a commit message or PR body unless you mean it; to ship a push that carried it by accident, re-trigger via **Run workflow** / `gh workflow run … --ref dev`.
+
+---
+
+## 4. Quick checklist for a new `@nurix/*` package
+
+- [ ] `package.json`: `name: "@nurix/X"`, `version: "0.1.0"`, `private: false`, `publishConfig.access: "restricted"`, `files: [...]`
+- [ ] Build step wired into `prepack` (or `prepublishOnly`)
+- [ ] Name follows §1; if it's a workspace member, boundaries follow §2
+- [ ] `.github/workflows/publish.yml` from §3.3
+- [ ] `NPM_PUBLISH_TOKEN` secret added to the repo
+- [ ] First publish from local (`npm publish`) to verify the pipeline, then a no-op commit to verify CI
+- [ ] README notes the `@nurix` scope so consumers know they need org access

package/data/harnesses/mobile/skills/brainstorm/README.md

@@ -128,13 +128,13 @@ The writing posture is a **mode** chosen at intake, folded into `build.md`:
 
 ## Exit artifacts
 
-The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one subfolder per topic). At `stop`, after the final five-source sync (self-containment included — the record is verified standalone-readable exactly when it's about to become the only survivor of the session), the skill _offers_ what to **publish** from it (`AskUserQuestion`, multi-select — a session can emit more than one):
+The session writes a design record at `docs/research/{topic}-brainstorming/` (one folder per topic), moved to `docs/history/brainstorms/{topic}/` on harvest. At `stop`, after the final five-source sync (self-containment included — the record is verified standalone-readable exactly when it's about to become the only survivor of the session), the skill _offers_ what to **publish** from it (`AskUserQuestion`, multi-select — a session can emit more than one):
 
 - **Source of truth** — one consolidated, README-style canonical doc for the thing designed (`templates/source-of-truth.md`); lands in the repo's feature/architecture doc home, else a topic `Readme.md`.
 - **Plans** — one or more executable plan docs → `docs/history/plans/` (Status: Draft).
-- **Harvest into the living docs** — conclusions dispersed by scope into ADRs, the domain model, and the backlog.
+- **Harvest into the living docs** — conclusions dispersed by scope into ADs (architecture decisions), the domain model, and the backlog.
 
-The `docs/brainstorm/{topic}/` record is **kept** whichever you pick — never deleted; it is the provenance every artifact traces back to. See `exit-artifacts.md`.
+The session record is **kept** whichever you pick — never deleted; on harvest it moves to `docs/history/brainstorms/{topic}/` as the provenance every artifact traces back to. See `exit-artifacts.md`.
 
 ---
 
@@ -159,4 +159,4 @@ brainstorm/                  # the skill (in .claude/skills/)
 └── templates/        # pillar templates + evidence.md + source-of-truth.md, used in the record and at stop
 ```
 
-The session itself is written to `docs/brainstorm/{topic}/` (kept, committed) — not here.
+The session itself is written to `docs/research/{topic}-brainstorming/` (committed; moved to `docs/history/brainstorms/{topic}/` on harvest) — not here.

package/data/harnesses/mobile/skills/brainstorm/SKILL.md

@@ -42,6 +42,8 @@ Write as if the transcript is already deleted — it will be. The folder must le
 
 ## `start`
 
+First, consult the two indexes — never scan folders. `docs/research/Readme.md` lists **active** sessions; `docs/history/brainstorms/Readme.md` lists **harvested** ones. Match the topic against both: an active match → resume it (§3, reusing its folder); a harvested match → surface that prior exploration and ask whether to reopen it (move the folder back to `docs/research/{topic}-brainstorming/`) or branch a fresh topic; no match → a new session. Then:
+
 ### 1. The entry gate
 
 A session needs substance before it opens. Ask for a **basis**: a reference document (path or URL), or a one-shot brain dump of the whole idea, right now, in prose.
@@ -62,7 +64,7 @@ Then propose the **aspect map**: the thinking dimensions for _this specific idea
 
 ### 3. Bootstrap
 
-Session folder: `docs/brainstorm/{topic}/` — a **committed, kept** design record, one subfolder per design topic (slug the topic; confirm it in one line). Resume an existing topic by reusing its folder if it already holds a `state.md`. The record stays in the repo after the exit artifacts publish (it is the provenance they distil from — see `exit-artifacts.md`), so it lives under `docs/` like any other durable project knowledge, not at the repo root. Create only the pillars the complexity calls for, from `templates/` (never overwrite existing files; if a template is missing, create the file from the field lists in **Pillars**). `basis/` holds the frozen inputs; `evidence/` materializes on the first session-produced analysis (memory contract, rule 3). Write top-level `state.md`:
+Session folder: `docs/research/{topic}-brainstorming/` — a **committed** design record, one folder per design topic (slug the topic; confirm it in one line). Add a row to the `docs/research/Readme.md` index. Resume an existing topic by reusing its folder if it already holds a `state.md`. The record lives here while the session is active; on close **and** harvest it moves to `docs/history/brainstorms/{topic}/` as the provenance the exit artifacts distil from (see `stop` and `exit-artifacts.md`). Create only the pillars the complexity calls for, from `templates/` (never overwrite existing files; if a template is missing, create the file from the field lists in **Pillars**). `basis/` holds the frozen inputs; `evidence/` materializes on the first session-produced analysis (memory contract, rule 3). Write top-level `state.md`:
 
 ```
 STATE: open
@@ -136,8 +138,8 @@ Zero means _"audited against the five sources and clean"_ — never _"nothing ca
 
 1. Run a final sync (wait for any in-flight sync first). It audits all five sources — self-containment included, so the record is verified standalone-readable exactly when it is about to become the only survivor of the session.
 2. **Coherent** → say so and proceed. **Questions open** → list them plainly (English first, codes in parentheses) and offer per question: resolve now (mini-converge) / park explicitly (backlog or non-goals, with reason) / leave open and stop anyway — the folder keeps full state and resumes exactly where it left off. Flag parked **self-containment** gaps distinctly: parking one means the record ships not fully standalone.
-3. **Publish exit artifacts** — see `exit-artifacts.md`. Offer the choice (`AskUserQuestion`, multi-select): a **source of truth** (one consolidated README-style doc — the standing reference for the thing designed), **plans** (executable work → `docs/history/plans/`), and/or **harvest into the living docs** (conclusions dispersed by scope into ADRs, the domain model, the backlog). The `docs/brainstorm/{topic}/` record is **kept** (committed) whichever you pick — it is the provenance every artifact traces back to and the seed the next session resumes from.
-4. Write `STATE: closed` + one-line reason. Print: _"Run `/brainstorm start` to resume."_
+3. **Publish exit artifacts** — see `exit-artifacts.md`. Offer the choice (`AskUserQuestion`, multi-select): a **source of truth** (one consolidated README-style doc — the standing reference for the thing designed), **plans** (executable work → `docs/history/plans/`), and/or **harvest into the living docs** (conclusions dispersed by scope into ADs — architecture decisions — the domain model, the backlog). The session record is **kept** (committed) whichever you pick — it is the provenance every artifact traces back to and the seed the next session resumes from.
+4. Write `STATE: closed` + one-line reason. If the harvest is complete (conclusions dispersed into the living docs), **move** the folder from `docs/research/{topic}-brainstorming/` to `docs/history/brainstorms/{topic}/` and update both indexes — drop its row from `docs/research/Readme.md`, add it to `docs/history/brainstorms/Readme.md`. If the session is only paused (questions parked, more to come), leave it in `docs/research/` and update its index row's status. Print: _"Run `/brainstorm start` to resume."_
 
 ## Conduct — holds for the whole session
 

package/data/harnesses/mobile/skills/brainstorm/exit-artifacts.md

@@ -1,8 +1,9 @@
 # Exit artifacts
 
-What `/brainstorm stop` publishes from a closed session. The `docs/brainstorm/{topic}/` record is **kept
+What `/brainstorm stop` publishes from a closed session. The session record is **kept
 either way** — committed provenance, never a scratchpad. Exit artifacts copy the session's _conclusions_
-outward into the form the work needs; the record stays as the source they trace back to.
+outward into the form the work needs; the record stays as the source they trace back to — and, once
+harvested, moves from `docs/research/{topic}-brainstorming/` to `docs/history/brainstorms/{topic}/`.
 
 At `stop`, after the final sync, **offer the artifact choice** (`AskUserQuestion`, multi-select — a session
 can publish more than one):
@@ -21,7 +22,7 @@ does; pick it too if you want both the one-doc reference and the integrated head
 
 One consolidated, README-style document — the canonical reference for the thing designed. Distil every
 pillar into it: `thesis.md` → what it is; `domain-model.md` → how it works + parts; `decisions.md` →
-present-tense rationale (no `D-N` codes, no options-considered — those stay in the record and ADRs);
+present-tense rationale (no `D-N` codes, no options-considered — those stay in the record and ADs);
 `non-goals.md` + accepted tradeoffs → constraints; still-open questions → a one-line pointer back to the
 record. Template: `templates/source-of-truth.md`.
 
@@ -44,19 +45,22 @@ not folders — a finding scoped to one module still lands in `docs/architecture
 
 | Session source | Destination |
 | --- | --- |
-| Decisions (any scope) | one ADR per cohesive theme → `docs/architecture/adr/NNN-{slug}.md` (`documentation` skill ADR template; `status:` frontmatter is the lifecycle source of truth; rejected alternatives → the ADR's Options Considered table) |
+| Decisions (any scope) | one AD per decision subject → `docs/architecture/decisions/AD-NNN-{slug}.md` (`documentation` skill AD template; `status:` frontmatter is the lifecycle source of truth; rejected alternatives → the AD's Options Considered table). A decision that revises an already-recorded subject does **not** mint a new AD — update that AD's body in place and append the revision to its Decision Changelog |
 | `domain-model.md` | `docs/architecture/domain-model.md`; note any IA / cross-cutting contract change there — the `boundary` skill reads it from source at the next plan check |
-| Doctrine / glossary / rejected | `docs/architecture/{domain-model,glossary}.md`, or the relevant ADR |
-| `tech.md` deviations | `docs/architecture/references.md` or the relevant ADR |
+| Doctrine / glossary / rejected | `docs/architecture/{domain-model,glossary}.md`, or the relevant AD |
+| `tech.md` deviations | `docs/architecture/references.md` or the relevant AD |
 | `non-goals.md` / `references.md` | `docs/architecture/{non-goals,references}.md` |
 | `backlog.md` | `docs/history/backlog.md` (P0–P3) |
 | Still-open questions | `docs/architecture/open-questions.md`, each with a _Resolution lands in_ pointer |
 
 Append a changelog entry at `docs/history/changelog/YYYY-MM-DD-brainstorm-{slug}.md` listing what was published where.
 
-## After publishing — keep the record
+## After publishing — move the record to history
 
-**Keep `docs/brainstorm/{topic}/` — never delete it.** The exit artifacts now carry the distilled
-conclusions, but the record stays committed as their provenance: a traceable source for every published
-headline, and the seed the next `/brainstorm start` on this topic resumes from. Retire a topic's folder
-by hand only when the design line is truly dead.
+**Move `docs/research/{topic}-brainstorming/` → `docs/history/brainstorms/{topic}/`, and update both
+`Readme.md` indexes** (drop the row from `docs/research/Readme.md`, add it to
+`docs/history/brainstorms/Readme.md`). The exit artifacts now carry the distilled conclusions; the record
+itself is **kept** — never deleted — but as harvested provenance it belongs under `docs/history/brainstorms/`:
+a traceable source for every published headline, and the seed the next `/brainstorm start` on this topic
+resumes from. A session that is only **paused** (not harvested) stays in `docs/research/`. Retire a topic's
+folder by hand only when the design line is truly dead.

package/data/harnesses/mobile/skills/brainstorm/templates/source-of-truth.md

@@ -3,8 +3,8 @@
 > This is a **source-of-truth doc**: the standing, canonical reference for [thing]. Write it like a
 > README — present tense, reader-first, the thing described as it _is_. It is **not a plan** (no steps,
 > status, or sequencing — those go to `docs/history/plans/`) and **not the brainstorm record** (no
-> `Q-N`/`D-N` codes, no "Why / How to apply" ledger, no rejected alternatives — those stay in
-> `docs/brainstorm/{topic}/` and any ADRs). One document; if a section outgrows it, link out, don't sprawl.
+> `Q-N`/`D-N` codes, no "Why / How to apply" ledger, no rejected alternatives — those stay in the harvested
+> record at `docs/history/brainstorms/{topic}/` and any ADs). One document; if a section outgrows it, link out, don't sprawl.
 >
 > **Placement.** In a repo with a feature-doc system this lands as `docs/features/{slug}.md` and carries
 > that system's frontmatter (`owns:` / `module:` / `keywords:` / `status:`). Cross-cutting → `docs/architecture/{slug}.md`.
@@ -31,7 +31,7 @@ reader-first description. Prose and tables; a diagram only if it earns its token
 
 [The load-bearing decisions, folded into present-tense rationale — "the index is single-writer because
 concurrent writes corrupted it," not "we decided X over Y." No decision codes, no options-considered
-table. The full rationale and the roads not taken live in the brainstorm record and ADRs — cite them,
+table. The full rationale and the roads not taken live in the brainstorm record and ADs — cite them,
 don't reproduce them.]
 
 ## Constraints & non-goals
@@ -41,9 +41,9 @@ and what is explicitly out of scope.]
 
 ## Open questions
 
-[One line pointing at `docs/brainstorm/{topic}/pillars/questions.md` if any remain open. Omit if none.]
+[One line pointing at `docs/history/brainstorms/{topic}/questions.md` if any remain open. Omit if none.]
 
 ---
 
-_Distilled from `docs/brainstorm/{topic}/`. That record holds the rationale, the rejected alternatives,
+_Distilled from `docs/history/brainstorms/{topic}/`. That record holds the rationale, the rejected alternatives,
 and the provenance for everything above._

package/data/harnesses/mobile/skills/documentation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: documentation
-description: Template & generator library for technical docs — the skill agents call to produce a doc from a template. Use to (1) document a feature or module (the feature doc is the feature's LLD — low-level design — written in LLD Mode), (2) create or update a changelog entry, (3) document data flows or Redux state, (4) add to protected files, (5) record an architecture decision (ADR), (6) create or update the project root README, (7) create or update a plan, (8) derive a feature doc's `owns:` frontmatter (the code-path globs it owns) from code, (9) scaffold a standard doc (README, structure.md, CHANGELOG, backlog, memory) from its template, (10) document an operations procedure (setup, deployment, maintenance), or (11) co-author any technical doc. Baselining / reconciling a repo's docs to the installed harness version is the **`maintenance` agent (baseline mode)** (which calls this skill for each template) — this skill does not orchestrate baseline. Triggers on "document this", "create docs", "update changelog", "add to protected files", "ADR", "architecture decision", "root README", "plan", "feature doc", "LLD".
+description: Template & generator library for technical docs — the skill agents call to produce a doc from a template. Use to (1) document a feature or module (the feature doc is the feature's LLD — low-level design — written in LLD Mode), (2) create or update a changelog entry, (3) document data flows or Redux state, (4) add to protected files, (5) record or revise an architecture decision (an AD), (6) create or update the project root README, (7) create or update a plan, (8) derive a feature doc's `owns:` frontmatter (the code-path globs it owns) from code, (9) scaffold a standard doc (README, structure.md, CHANGELOG, backlog, memory) from its template, (10) document an operations procedure (setup, deployment, maintenance) or a one-shot migration runbook, (11) write a steering doc (system overview, domain model, glossary, non-goals, security overview, testing strategy), (12) catalog the API surface or the environment/config registry, or (13) co-author any technical doc. Baselining / reconciling a repo's docs to the installed harness version is the **`maintenance` agent (baseline mode)** (which calls this skill for each template) — this skill does not orchestrate baseline. Triggers on "document this", "create docs", "update changelog", "add to protected files", "AD", "ADR", "architecture decision", "root README", "plan", "feature doc", "LLD", "glossary", "domain model", "runbook", "API reference".
 ---
 
 # Technical Documentation Skill
@@ -9,12 +9,31 @@ description: Template & generator library for technical docs — the skill agent
 
 Document contracts and architecture, not implementation details. Show function signatures and API shapes — never paste full implementations (they rot fast). Use ASCII diagrams over prose for flows. Only document state at persistence boundaries (Redux persistence, DB schemas, API shapes), not component-level or transient state. Mark deprecated fields with `// UNUSED:` comments. Breaking changes belong in changelogs only, not module docs.
 
+---
+
+## The Two Natures
+
+Every document is exactly one of two things. Decide which before writing a word — every rule in this skill derives from the split.
+
+| | **Truth document** | **Record** |
+| --- | --- | --- |
+| States | Absolutes — how the system is, **now** | What happened — a dated account of activity |
+| Named by | Topic: `auth.md`, `AD-003-persistence.md` | Date: `YYYY-MM-DD-slug.md` (or append position) |
+| On change | Body rewritten in place the moment reality changes | Never edited — frozen at completion or append-only |
+| Read to | Act correctly today | Trace provenance, diagnose, audit |
+| Lives in | `docs/features/`, `docs/architecture/`, `docs/operations/`, `docs/tests/`, READMEs | `docs/history/` (plans, changelog, brainstorms, research, migrations), `docs/research/`, `docs/memory/` |
+
+The two guarantees are complementary and both break on mixing: a reader holding a **truth document** must never need history to interpret it; a reader holding a **record** must be able to trust it was never rewritten. So the natures never share a document body.
+
+- **Truth documents never narrate history.** No migration/fold stories, no dated "shipped/verified on YYYY-MM-DD" markers, no "was X → now Y" journeys, no provenance asides ("ex-`@nurix/X`, folded 2026-06-12"). When the system changes, the change-story goes to `docs/history/` (a changelog entry) and the truth document simply becomes correct in present tense. When you find historical narration in a truth document, rewrite it to the present-tense fact and let the record carry the story.
+- **Records are never edited to match the present.** A completed plan stays wrong-in-hindsight; a changelog entry describes close-time state; a scope change gets a *new* dated record that links back, never an edit to a frozen one.
+- **The one bridge — head is truth, tail is provenance.** An **Architecture Decision (AD)** ends with a **Decision Changelog**: the single sanctioned dated-history section inside a truth document, because for a decision the journey (what each revision reversed, and what triggered it) is part of the reasoning. The AD body stays current-truth-only; the tail carries the dates and links to the plans that implemented each revision. No other truth document carries dated history.
+- **Truth documents cite records for the _why_, never the _when_.** `Provenance: AD-002` is good; "decided in AD-002 and shipped 2026-06-13" is not. Routing/index docs point only to truth documents — never to a plan or changelog entry as the "read first" source.
+
 **No empty stubs.** Never leave a template section as an empty placeholder — omit any section with nothing real to say (each template declares its required core; everything else is optional). Write an explicit "None" only where the absence itself is information (e.g., a plan's Cross-Module Contracts Affected, an LLD's Ownership Conflicts). An empty table stub reads as "not yet researched"; an omitted section reads as "doesn't apply" — keep those meanings distinct.
 
 **No redirect docs.** When moving a doc to a new location, delete the old file entirely. Update all references (cross-doc links, memory files) to point to the new path. Never leave a stub file that says "Moved to X" — redirect docs rot, clutter the repo, and create false search hits.
 
-**Present tense, current state only.** Active docs (everything outside `docs/history/`) describe the system _as it is now_ — what exists and how it works today. They never narrate how it got there: no migration/fold history, no dated "shipped/verified/built on YYYY-MM-DD" markers, no "ex-`@nurix/X`, folded 2026-06-12" provenance, no "was X → now Y" change journeys, no "removed/deleted in the <date> fold". The historical record — when and how things changed — lives **only** in `docs/history/` (changelog, plans); `docs/memory/` is the agent's dated log and is likewise exempt, and an ADR's **Decision Changelog** section is the one sanctioned dated-history section inside an active doc (the ADR body itself stays current-truth-only). A doc may cite an ADR for the _why_ (the decision rationale), but must not narrate the _when/how it changed_. Routing/index docs point only to current authority docs — never to a historical plan or changelog as the "read first" source. When you find historical narration in an active doc, rewrite it to the present-tense fact and let `docs/history/` carry the story.
-
 ---
 
 ## Decision Tree
@@ -24,23 +43,39 @@ User request
     │
     ├─ "Baseline/reconcile docs" ──────▶ maintenance agent (baseline mode) (it calls this skill per template)
     │
-    ├─ "Document feature/module (LLD)" ▶ Module Template
+    ├─ "Document feature/module (LLD)" ▶ Feature (LLD) Template
     │
-    ├─ "Create/update changelog" ──────▶ Changelog Template
+    ├─ "Create/update changelog" ──────▶ Changelog Template (record)
     │
-    ├─ "Document data flow" ───────────▶ Module Template (Architecture section)
+    ├─ "Document data flow" ───────────▶ Feature Template (Architecture section)
     │
-    ├─ "Document Redux/state" ─────────▶ Module Template (State section)
+    ├─ "Document Redux/state" ─────────▶ Feature Template (State section)
     │
     ├─ "Add to protected files" ───────▶ Protected Files Template
     │
-    ├─ "Record architecture decision" ─▶ ADR Template
+    ├─ "Record/revise architecture
+    │    decision" ────────────────────▶ AD Template (one per subject; revisions update it in place)
+    │
+    ├─ "System at a glance" ───────────▶ System Overview Template
+    │
+    ├─ "Domain model / glossary /
+    │    non-goals" ───────────────────▶ Steering Templates
+    │
+    ├─ "Catalog the API surface" ──────▶ API Reference Template
+    │
+    ├─ "Document env vars / config" ───▶ Environment Registry Template
+    │
+    ├─ "Security / threat model" ──────▶ Security Overview Template
+    │
+    ├─ "Testing strategy" ─────────────▶ Testing Strategy Template
+    │
+    ├─ "Recurring procedure/setup" ────▶ Operations Procedure Template
     │
-    ├─ "Document a procedure/setup" ───▶ Operations Procedure Template
+    ├─ "One-shot migration/upgrade" ───▶ Migration Runbook Template (record)
     │
     ├─ "Create/update root README" ────▶ Project Root README Template
     │
-    ├─ "Create/update plan" ───────────▶ Plan Template
+    ├─ "Create/update plan" ───────────▶ Plan Template (record)
     │
     ├─ "Update existing doc" ──────────▶ Preserve existing structure
     │
@@ -51,10 +86,19 @@ User request
 
 ## Naming & Lifecycle
 
-- Features: `kebab-case.md` — living reference, status `Active`
-- Plans: `YYYY-MM-DD-kebab-case.md` — frozen after `Complete` or `Abandoned`
-- Changelogs: `YYYY-MM-DD-kebab-case.md` — append-only
-- Memory: `{agent-name}.md` — agent-maintained
+| Document | Nature | Name | Lifecycle |
+| --- | --- | --- | --- |
+| Feature (LLD) | Truth | `kebab-case.md` | Living; `status:` `draft` → `active` → `deprecated` |
+| Architecture Decision | Truth | `AD-NNN-kebab-case.md` | Living; `Proposed` → `Accepted` → `Deprecated`; revisions rewrite the body + append to its Decision Changelog |
+| Steering docs (overview, domain model, glossary, non-goals, security, testing strategy) | Truth | fixed names | Living |
+| API reference / environment registry | Truth | fixed names | Living |
+| Operations procedure | Truth | `kebab-case.md` | Living |
+| Protected files | Truth | `protected-files.md` | Living |
+| Plan | Record | `YYYY-MM-DD-kebab-case.md` | Freezes at `Complete` / `Abandoned` |
+| Changelog entry | Record | `YYYY-MM-DD-kebab-case.md` | Frozen; master index append-only |
+| Migration runbook | Record | `YYYY-MM-DD-kebab-case.md` | Freezes once executed, outcome stamped |
+| Research | Record | `history/research/{topic}/` | Frozen snapshot |
+| Memory | Record | `{agent-name}.md` | Append-only dated ledger |
 
 ---
 
@@ -65,7 +109,7 @@ When creating or updating a feature doc, derive its **`owns:` frontmatter** —
 ### When to run
 
 - **Baseline / reconcile** — for every feature doc whose code paths aren't yet declared in its `owns:` frontmatter (the `maintenance` agent (baseline mode) calls this)
-- **New feature doc** — when creating a doc via the Feature/Module template, project its `owns:` globs
+- **New feature doc** — when creating a doc via the Feature template, project its `owns:` globs
 - **Doc update** — when the documented scope changes, update the doc's `owns:` globs
 
 ### How to derive the frontmatter
@@ -123,6 +167,6 @@ For docs that don't match templates:
 
 | File | Use For |
 | --- | --- |
-| `references/templates.md` | docs/README.md, structure.md, the feature-frontmatter contract, scaffolds (CHANGELOG, backlog, memory), feature, changelog, plan, operations procedure, protected files, ADR, project root README templates |
-| `references/style-guide.md` | Writing rules, formatting conventions |
+| `references/templates.md` | docs/README.md, structure.md, the feature-frontmatter contract, scaffolds (CHANGELOG, backlog, memory), feature, changelog, plan, operations procedure, migration runbook, protected files, AD, steering docs (system overview, domain model, glossary, non-goals, security, testing strategy), API reference, environment registry, project root README templates |
+| `references/style-guide.md` | Writing rules, formatting conventions, the two-natures tense rules |
 | `references/examples.md` | Good vs bad documentation examples |

package/data/harnesses/mobile/skills/documentation/references/examples.md

@@ -151,6 +151,46 @@ When the page loads, the useAppInit hook calls the syncData function. This funct
 
 ---
 
+## Example 5: Architecture Decision revision
+
+### ❌ Bad: Supersession chain
+
+```
+docs/architecture/decisions/
+├── AD-002-auth-keycloak.md        (status: Superseded)
+├── AD-006-auth-better-auth.md     (status: Superseded, "supersedes AD-002")
+└── AD-011-auth-better-auth-v2.md  (status: Accepted, "supersedes AD-006")
+```
+
+**Problems:** Three files hold one subject; the reader must diff a chain to learn the current truth; two of the three are wrong-but-present (the same pathology as keeping `report_v1.sql` beside the live `report_v2.sql`); the reasoning that killed Keycloak is stranded in a dead file nobody opens.
+
+### ✅ Good: One subject, updated in place
+
+```
+docs/architecture/decisions/
+└── AD-002-auth.md                 (status: Accepted, last-updated bumped)
+```
+
+```markdown
+## Decision
+
+We use Better Auth with one-shot credential issuance…   ← current truth, no journey
+
+…
+
+## Decision Changelog
+
+- 2026-05-02 — Moved issuance to one-shot tokens because refresh-token theft
+  surfaced in review. Implemented by [plan](…). (Previously: long-lived refresh tokens.)
+- 2026-03-18 — Replaced Keycloak with Better Auth because self-hosting cost
+  outweighed SSO needs. Implemented by [plan](…). (Previously: Keycloak.)
+- 2026-01-10 — Initial decision accepted. Implemented by [plan](…).
+```
+
+**Why it works:** The body answers "how does auth work and why" without archaeology; the tail preserves every reversal with its trigger; the rejected alternatives stay findable in the one file a reader actually opens.
+
+---
+
 ## Quick Comparison
 
 | Aspect     | Bad                  | Good                        |
@@ -159,4 +199,5 @@ When the page loads, the useAppInit hook calls the syncData function. This funct
 | State      | Every occurrence     | Persistence points only     |
 | Flows      | Prose paragraphs     | ASCII diagrams              |
 | Changelogs | "Updated X"          | Function names + migrations |
+| Decisions  | New doc per revision | One AD per subject, updated in place |
 | Length     | 100+ lines           | 20-40 lines                 |