@nurix/etna 0.18.23 → 0.18.25

package/data/harnesses/mobile/skills/brainstorm/templates/references.md

@@ -1,28 +0,0 @@
-# References
-
-This file collects **external prior art** — repos, docs, papers, talks — with one-line pointers to what we use each for. Reference implementations beat invented solutions: if someone has already solved the problem you're about to design, the right move is to link it here and use it, not re-derive.
-
-References are not bookmarks. Every entry should answer the question "what specific pattern, idea, or implementation do we lift from this?" A reference without that grounding decays into noise. If you can't write the one-line "what we use it for", you probably don't need the entry.
-
-References to **source materials** copied into `./plan/sources/` during the session also live here — point at the local copy, not the original location. This keeps the brainstorm self-contained.
-
-When a referenced thing changes (renames, moves, deprecation), **update or remove the entry**. A stale reference that no longer points at what the description claims is worse than no reference — it teaches the reader to distrust the file.
-
----
-
-## Internal repos / paths
-
-- `~/path/to/repo` — [what pattern we borrow]
-- `~/path/to/another` — [what pattern we borrow]
-
-## Source materials (this session)
-
-- `./plan/sources/[file]` — [original location, why it's relevant]
-
-## External docs
-
-- `https://example.com/foo` — [what we use it for]
-
-## Papers / talks
-
-- [Title] — [link or citation] — [the specific idea we're applying]

package/data/harnesses/mobile/skills/brainstorm/templates/rejected.md

@@ -1,33 +0,0 @@
-# Rejected alternatives
-
-This file captures **paths that were considered and rejected**, with the reason for rejection. Its purpose is to prevent re-litigation: when someone proposes the same alternative six weeks later, this file answers "we already looked at that; here's why we didn't go that way."
-
-Each entry needs four load-bearing parts: **Considered** (what was proposed, in concrete terms), **Evidence on the table** (what prior art, findings, or arguments were in front of the decider when they declined — this is what separates an informed rejection from an unexamined one), **Rejected because** (the specific reason — "didn't fit" is useless to future-you; name the constraint, the cost, the risk), and **Re-evaluate if** (what would need to change for the rejected path to become viable again). The re-evaluate field stops the rejection from looking permanent when it isn't — most rejections are scope-conditional, not absolute.
-
-This file is **eager**, not lazy (the memory contract): it materializes the moment the user knowingly declines a presented option, in the same turn — an informed rejection that lives only in the transcript is a leak.
-
-This is one of the four places inside the brainstorm folder where past tense and "we considered X" framing is permitted (the others: `decisions.md`, `references.md`, git history). The whole point of this file is to capture the path-not-taken so future architects don't have to re-discover it.
-
-If circumstances change and a rejected path becomes attractive again, **do not silently revive it**. Add a new question to `questions.md` that references the rejection here, and resolve it explicitly. The new decision can override the rejection — but it should override, not pretend the rejection never happened.
-
----
-
-## R1 — [Rejected option]
-
-**Considered.** [What was proposed.]
-
-**Evidence on the table.** [The prior art, findings, or arguments in front of the decider at the moment of declining — cite the evidence note or basis file if one carries it.]
-
-**Rejected because.** [The reason. Be specific.]
-
-**Re-evaluate if.** [What would change to make this viable.]
-
-**Came up during.** [Q-number or D-number for context.]
-
----
-
-## R2 — [Rejected option]
-
-(same format)
-
----

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

@@ -1,49 +0,0 @@
-# [Thing] — source of truth
-
-> 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 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`.
-> No doc taxonomy → a `Readme.md` at the topic's home.
-
-## What it is
-
-[One paragraph, present tense: what the thing is, what it does, who uses it. Distilled from `thesis.md`.]
-
-## How it works
-
-[The model — entities, relationships, the main flow — lifted from `domain-model.md` into plain,
-reader-first description. Prose and tables; a diagram only if it earns its tokens.]
-
-## Parts
-
-[One row per component / module / piece: name · role · what it owns · what it depends on.]
-
-| Part | Role | Owns | Depends on |
-| --- | --- | --- | --- |
-|  |  |  |  |
-
-## Why it's shaped this way
-
-[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 ADs — cite them,
-don't reproduce them.]
-
-## Constraints & non-goals
-
-[Accepted tradeoffs phrased as current fact ("a 5-second lag is accepted for predictable throughput")
-and what is explicitly out of scope.]
-
-## Open questions
-
-[One line pointing at `docs/history/brainstorms/{topic}/questions.md` if any remain open. Omit if none.]
-
----
-
-_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/brainstorm/templates/state.md

@@ -1 +0,0 @@
-STATE: open MODE: dump COMPLEXITY: medium SESSION STARTED: YYYY-MM-DD SESSION CLOSED: CURRENT TOPIC: (one line — updated on every topic shift) LAST SYNC: never SYNC IN FLIGHT: no

package/data/harnesses/mobile/skills/brainstorm/templates/tech.md

@@ -1,23 +0,0 @@
-# Tech
-
-This file holds the **technology choices** for the idea. It is seeded at bootstrap from the harness's opinionated stack (e.g. `.claude/rules/general.md` recommended-packages table) when one exists — those rows arrive as defaults, not decisions.
-
-Its job afterward is to be a **lens**: when a conversation move conflicts with a row here, the sync (or the skill, in the moment) surfaces it — _"you just proposed local component stores; the stack says Redux Toolkit — deviating or steering back?"_ A confirmed deviation gets recorded below with its why; an unconfirmed conflict becomes an open question.
-
-## Stack
-
-| Layer        | Choice             | Source                      |
-| ------------ | ------------------ | --------------------------- |
-| [e.g. UI]    | [react ^19]        | harness default             |
-| [e.g. state] | [@reduxjs/toolkit] | harness default             |
-| [layer]      | [choice]           | decided this session — D[n] |
-
-## Deviations
-
-Each deviation from a harness default carries a why:
-
-### [Choice] instead of [default]
-
-**Why.** [Constraint, requirement, or incident that justifies the deviation.]
-
-**Scope.** [Whole project, or only a named module/surface.]

package/data/harnesses/mobile/skills/brainstorm/templates/thesis.md

@@ -1,21 +0,0 @@
-# Thesis
-
-This file is the **running narrative of what we are designing** — the single place a cold reader (or the next session) goes to understand the idea as it currently stands. It is rewritten freely as the idea evolves; it always describes the _current_ shape, never the journey (writing posture per `build.md`'s mode).
-
-Keep it prose-first. If a section outgrows this file at high complexity, it may move to a numbered deep-dive doc (`01-foo.md`) at the session root with a one-line pointer left here.
-
-## What this is
-
-[2–5 paragraphs. What the thing is, who it's for, what it does. Distilled from the basis at `start` and kept current by the loop.]
-
-## Aspect map
-
-The thinking dimensions for _this_ idea — proposed by the skill from the basis, edited by the user at `start`. The sync agent audits coverage against this list: an aspect with no content anywhere becomes an open question.
-
-- [ ] [aspect — e.g. users & jobs]
-- [ ] [aspect — e.g. domain model]
-- [ ] [aspect — e.g. architecture]
-- [ ] [aspect — e.g. tech]
-- [ ] [aspect — e.g. risks]
-
-Check an aspect only when it has real content in the pillars, not when it has merely been mentioned.

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

@@ -1,172 +0,0 @@
----
-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 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
-
-**This skill is a template & generator library, not an orchestrator.** It supplies the templates, the frontmatter-derivation generator, and the co-authoring workflow that _agents_ call to produce individual docs. It does **not** baseline, audit, or reconcile a repo's doc tree — that is the **`maintenance` agent (baseline mode)**, which calls this skill for each template it scaffolds. Reach here to generate _one_ doc from a template; reach for the `maintenance` agent (baseline mode) to bring a whole repo into shape.
-
-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.
-
----
-
-## Decision Tree
-
-```
-User request
-    │
-    ├─ "Baseline/reconcile docs" ──────▶ maintenance agent (baseline mode) (it calls this skill per template)
-    │
-    ├─ "Document feature/module (LLD)" ▶ Feature (LLD) Template
-    │
-    ├─ "Create/update changelog" ──────▶ Changelog Template (record)
-    │
-    ├─ "Document data flow" ───────────▶ Feature Template (Architecture section)
-    │
-    ├─ "Document Redux/state" ─────────▶ Feature Template (State section)
-    │
-    ├─ "Add to protected files" ───────▶ Protected Files 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
-    │
-    ├─ "One-shot migration/upgrade" ───▶ Migration Runbook Template (record)
-    │
-    ├─ "Create/update root README" ────▶ Project Root README Template
-    │
-    ├─ "Create/update plan" ───────────▶ Plan Template (record)
-    │
-    ├─ "Update existing doc" ──────────▶ Preserve existing structure
-    │
-    └─ No template matches ────────────▶ Co-Authoring Workflow (below)
-```
-
----
-
-## Naming & Lifecycle
-
-| 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 |
-
----
-
-## Frontmatter Derivation
-
-When creating or updating a feature doc, derive its **`owns:` frontmatter** — the code-path globs it is canonical for — from the source the doc describes. Code ownership lives in each feature doc's `owns:` frontmatter (the SessionStart hook unions them into the injected ownership index); there is no hand-maintained ownership map.
-
-### 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 template, project its `owns:` globs
-- **Doc update** — when the documented scope changes, update the doc's `owns:` globs
-
-### How to derive the frontmatter
-
-A feature doc's launch-map frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body.
-
-**1. `owns:`** (the path scope)
-
-Read the doc's content. Extract every source file path it references (file listings, function locations, component paths). Group them into the narrowest glob patterns that cover all referenced files without overlapping another doc's `owns:` globs at equal specificity. A doc may own several globs.
-
-| Doc references                       | Glob                      |
-| ------------------------------------ | ------------------------- |
-| Multiple files under one directory   | `src/feature/**`          |
-| Specific files in a shared directory | List each file explicitly |
-| A single entry-point file            | The exact file path       |
-
-Glob each pattern against the codebase; drop any that match nothing.
-
-**2. `module:`**
-
-The single bounded-context label this feature belongs to, or omit it for a cross-cutting feature that belongs to no single context. A module is a label, not a folder — features sharing a `module:` value are what ties that module to code (a filter over the generated ownership index).
-
-**3. `keywords:` & `status:`**
-
-`keywords:` are the discovery terms topic→doc lookup rides. `status:` is `active`, `draft`, or `deprecated` — it steers the model toward live docs and away from draft/deprecated ones.
-
-A doc's dependencies on other docs are expressed inline in its prose (links); cross-cutting contracts are diagnosed by the `boundary` skill from source, not persisted.
-
-### Rules
-
-- One canonical doc per path. A doc's `owns:` globs must not overlap another doc's at equal specificity — the narrower glob wins; equal-specificity overlap is an ownership conflict to resolve.
-- Use glob patterns for directories, explicit paths for individual files. Don't list paths that don't exist in the codebase.
-- When a doc covers a deep feature with sub-specs (e.g., `editor/`), each sub-spec owns its own globs — don't duplicate a path across siblings.
-- For baseline/reconcile with many docs, use parallel sub-agents to read source and propose `owns:` globs.
-
----
-
-## Co-Authoring Workflow
-
-For docs that don't match templates:
-
-**Stage 1: Context Gathering**
-
-- Ask: Audience? Purpose? Existing format?
-- Have user dump all context, then ask 5-10 clarifying questions
-
-**Stage 2: Structure & Draft**
-
-- Propose section structure, draft section by section
-- User indicates changes (don't edit directly — learn their style)
-
----
-
-## Resources
-
-| File | Use For |
-| --- | --- |
-| `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

@@ -1,203 +0,0 @@
-# Documentation Examples
-
-Good vs bad examples showing the key differences.
-
----
-
-## Example 1: Function Documentation
-
-### ❌ Bad: Full Implementation
-
-```markdown
-### mergeData
-
-function mergeData(server, local, changes) { const result = {}; const serverMap = new Map(server.map((i) => [i.id, i])); // ... 30 more lines return result; }
-```
-
-**Problems:** Will become obsolete, focuses on HOW not WHAT.
-
-### ✅ Good: Contract Only
-
-```markdown
-### `mergeData(serverData, localData, changes)`
-
-**Goal:** Merge server data with local changes **Input:**
-
-- `serverData` (array) - Fresh from API
-- `localData` (array) - Current state
-- `changes` (object) - `{ added, updated, removed }` **Output:** `{ merged: array, conflicts: array }`
-
-**Merge Rules:**
-
-- Server wins for conflicts
-- Local additions preserved
-- Local removals marked as intent
-```
-
----
-
-## Example 2: State Documentation
-
-### ❌ Bad: State Everywhere
-
-```markdown
-## Component State
-
-const [items, setItems] = useState([]);
-
-## Hook State
-
-{ data: items, isLoading: loading, error: null }
-
-## Redux State
-
-{ items: [], loading: false, error: null }
-```
-
-**Problems:** Documents transient state, repeats shapes.
-
-### ✅ Good: Persistence Points Only
-
-```markdown
-## State
-
-**Frontend (at persistence):** { "data": [], "changes": { "added": [], "updated": [], "removed": [] } // "cache": {} // UNUSED: Deprecated }
-
-**Storage:** localStorage `app_state`
-
-**Backend:** model Item { id String @id data Json }
-```
-
----
-
-## Example 3: Changelog
-
-### ❌ Bad: Vague
-
-```markdown
-# 2025-01-05 - Updates
-
-## Changes
-
-- Updated editor
-- Fixed bugs
-- Improved performance
-
-## Files
-
-- Various files in src/
-```
-
-### ✅ Good: Function-Level Detail
-
-```markdown
-# 2025-01-05 - Version-Based Merge
-
-## Summary
-
-Replaced change-tracking merge with version-based conflict resolution.
-
-## Changes
-
-### Added
-
-- `mergeAndDerive(server, local, versionsMatch, type)` in `src/utils/merge.js`
-  - Purpose: Single-pass merge with change detection
-  - Returns: `{ merged, changes }`
-
-### Changed
-
-- `useDataSync()` in `src/hooks/useDataSync.js`
-  - Changed: Now compares versions before merge
-
-### Removed
-
-- `deriveChanges()` from `src/utils/derive.js`
-  - Replaced by: Logic in `mergeAndDerive()`
-
-## Breaking Changes
-
-⚠️ **Merge behavior changed**
-
-- Old: Local changes always preserved
-- New: Local preserved only if versions match
-
-## Files Changed
-
-- `src/hooks/useDataSync.js`
-- `src/utils/merge.js`
-- `src/utils/derive.js` (deleted)
-```
-
----
-
-## Example 4: Data Flow
-
-### ❌ Bad: Prose Description
-
-```markdown
-When the page loads, the useAppInit hook calls the syncData function. This function first fetches data from the server using the API. Then it gets the local data from Redux. After that, it compares versions...
-```
-
-### ✅ Good: Diagram + Key Points
-
-```markdown
-## Data Flow
-
-┌─────────────────────────────────────────┐ │ DATA SYNC │ ├─────────────────────────────────────────┤ │ │ │ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │Server│────▶│Merge │────▶│Redux │ │ │ │ API │ │ │ │Store │ │ │ └──────┘ └──────┘ └──────┘ │ │ │ │ │ ▼ │ │ Version Check │ │ │ └─────────────────────────────────────────┘
-
-**Trigger:** `useAppInit()` on page load **Version Rule:** Match → local wins, Mismatch → server wins
-```
-
----
-
-## 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                        |
-| ---------- | -------------------- | --------------------------- |
-| Code       | Full implementations | Signatures + contracts      |
-| 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                 |