musememory 3.0.0 → 3.0.2

package/.agents/artifacts/audit-and-realigned-roadmap-20261015.md

@@ -16,19 +16,19 @@ While the test suite demonstrates clean execution (649/649 green) and 21 major a
 ### 🚨 Critical Vulnerabilities & Code Gaps Discovered
 
 1. **Silent SQLite Initialization Crash & Fallback to Flat-Files (GAP-01)**:
-   - **Location**: [`src/sqlite.ts:169-171`](file:///home/harsh/Projects/github/musememory/src/sqlite.ts#L169-L171) & [`src/store.ts:173-177`](file:///home/harsh/Projects/github/musememory/src/store.ts#L173-L177)
+   - **Location**: [`src/sqlite.ts:169-171`](../../src/sqlite.ts#L169-L171) & [`src/store.ts:173-177`](../../src/store.ts#L173-L177)
    - **Defect**: `initSchema` attempts `CREATE INDEX IF NOT EXISTS idx_memories_mem_path ON memories(mem_path)` unconditionally on existing tables. On stores created prior to v1, `memories` lacks `mem_path`. SQLite throws `SQLiteError: no such column: mem_path`.
    - **Impact**: `openStore` catches this error, swallows it, leaves `store.db` as `undefined`, and silently degrades to flat-file storage. Crucially, `runMigrations` in `src/migrate.ts` never executes for these stores.
    - **Remediation**: Guard index creation by inspecting existing columns via `PRAGMA table_info(memories)` or delegate index creation to `src/migrate.ts` migration `v1`.
 
 2. **Stored-Command Validation Failure on Legacy Memories (GAP-02)**:
-   - **Location**: [`.memory/memories/m_1791995990650_...yaml`](file:///home/harsh/Projects/github/musememory/.memory/memories/m_1791995990650_avoidneverre-invokebinsh-cformemorytest_commandexecutionb4.yaml#L36) & [`src/schema.ts`](file:///home/harsh/Projects/github/musememory/src/schema.ts)
+   - **Location**: `.memory/memories/m_1791995990650_avoidneverre-invokebinsh-cformemorytest_commandexecutionb4.yaml` (a local store file, not in the repository) & [`src/schema.ts`](../../src/schema.ts)
    - **Defect**: Pre-`T-001` memory entries contain legacy `test_command` values (e.g. `grep -n 'bin/sh' src/verify.ts`). Following `T-001`'s template gating, `memory validate` and `memory doctor` exit with code 1 (`/test_command is not an executable command`).
    - **Impact**: Breaks automated health checks and CLI compliance.
    - **Remediation**: Add a stored-command doctor sweep/migration to sanitize non-template test commands.
 
 3. **Terminal Hang on Interactive Stdin in Test Suite & Hooks (GAP-03)**:
-   - **Location**: [`src/hooks/pack.ts:220-227`](file:///home/harsh/Projects/github/musememory/src/hooks/pack.ts#L220-L227)
+   - **Location**: [`src/hooks/pack.ts:220-227`](../../src/hooks/pack.ts#L220-L227)
    - **Defect**: `readStdinJson()` synchronously calls `readFileSync(0, "utf8")` without verifying whether stdin is a TTY.
    - **Impact**: When running in an interactive terminal or non-piped runner, `test/hooks.test.ts` blocks indefinitely waiting for EOF on fd 0.
    - **Remediation**: Guard with `if (process.stdin.isTTY) return {};` before attempting synchronous reads on fd 0.

package/.agents/artifacts/qa-gate-2026-10-22.md

@@ -0,0 +1,129 @@
+# Website Release Gate — Muse Memory
+
+> **Mode**: `qa-launch` → `gate`
+> **Candidate**: `apps/website/dist` (built from `feat/website-content-showreel-rebuild`)
+> **Gate script**: `bun run site:qa` — the checklist below is executed, not asserted by hand
+> **Rollback owner**: the repository owner (single-operator repo; rollback is `git revert` + redeploy, or redeploy the previous tag)
+> **Date**: 2026-10-22
+
+---
+
+## Verdict
+
+# ✅ SHIP
+
+17 / 17 checks passed. 0 blocking findings. 0 P0, 0 P1 open.
+
+---
+
+## Gate checklist
+
+| # | Check | Result | Evidence | Severity |
+| :-- | :--- | :--- | :--- | :-- |
+| 1 | Critical path `/` renders | ✅ | `main=true h1=true install=true video=true` | P1 |
+| 2 | Critical path `/docs` renders | ✅ | `main=true h1=true install=true video=true` | P1 |
+| 3 | Critical path `/compare` renders | ✅ | `main=true h1=true install=true video=true` | P1 |
+| 4 | Install command is copyable | ✅ | `label="Copied" state=true` | P1 |
+| 5 | FAQ disclosure expands | ✅ | `open=true` | P1 |
+| 6 | No console or page errors | ✅ | clean | **P0** |
+| 6b | Header and footer chrome render as designed, not as browser defaults | ✅ | `header=sticky inner=flex links=6 minGap=30.4px footerCols=5` | P1 |
+| 7 | Keyboard-only path: every control reachable with a visible focus ring | ✅ | `37/37 reachable, 37/37 with a focus ring` | **P0** |
+| 8 | 200% zoom reflows without loss — `/` | ✅ | `scrollW=640 clientW=640` | P1 |
+| 9 | 200% zoom reflows without loss — `/docs` | ✅ | `scrollW=640 clientW=640` | P1 |
+| 10 | 200% zoom reflows without loss — `/compare` | ✅ | `scrollW=640 clientW=640` | P1 |
+| 11 | First frame reads completely with JavaScript disabled | ✅ | `0/43 reveal elements still hidden, 13 headings readable` | **P0** |
+| 12 | No animation runs far offscreen; no ungated rAF loop | ✅ | `0 animated elements, 0 far offscreen, rAF loops=0` | P2 |
+| 13 | No placeholder content, debug flags or secrets in the output | ✅ | clean | P1 |
+| 14 | Home page ships a lean payload with no framework script | ✅ | `47 KB transferred, 0 external scripts` | P2 |
+| 15 | Firefox renders without overflow | ✅ | `overflow=false` | P2 |
+| 16 | WebKit rendering | ⏭️ skipped | engine not installed | P2 |
+
+Chromium is the primary engine; Firefox 155 was installed for a genuine second-engine
+check. WebKit was not installed in this environment and is reported as **skipped**, not
+passed.
+
+---
+
+## Findings raised and fixed during the gate
+
+| # | Severity | Finding | Root cause | Fix |
+| :-- | :-- | :--- | :--- | :-- |
+| F1 | **P0** | With JavaScript disabled, **all 43 `.reveal` elements stayed at `opacity: 0`** — the page below the hero rendered blank. The scroll-reveal ships hidden and relies on an `IntersectionObserver` to show it. | No `<noscript>` fallback existed. | `Base.astro` now emits a `<noscript>` block that forces `.reveal { opacity: 1; transform: none }` and hides the copy button (which cannot work without script). |
+| F2 | **P1** | The mobile menu sheet overflowed the viewport at 375px and 768px — `nav.nav-sheet` and its links measured `x = -73` (off the left edge). | `.nav-actions` is a flex row without `justify-content`, so the group packed to the **start** of the row; the absolutely-positioned sheet then anchored to the menu button instead of the viewport edge. | `.nav-actions { justify-content: flex-end }` and `.nav-sheet { max-inline-size: calc(100vw - var(--gutter) * 2) }`. |
+| F3 | **P1** | The copy button's failure hint read "Press ⌘C" on every platform. | The hint was hardcoded to the Mac modifier. | The hint now names the platform's modifier (`⌘C` on Apple, `Ctrl+C` elsewhere). |
+| F4 | P1 | The docs page `<h1>` was the single word "Docs" — thin for SEO and for a scannable page. | — | Now "Muse Memory documentation". |
+| F5 | P1 | axe-core: `definition-list` violation — a `<p>` sat inside a `<dl>`'s wrapper `<div>`. | `<p>` is not a permitted child of a `dl > div`. | The note became a second `<dd>`. |
+| F6 | P2 | Two animated elements used `filter: blur()` together with a transform animation — a full re-rasterisation of the blur on every frame (a jank trap on low-end devices). | The blur was used to soften the gradients. | The softness now comes from the gradient stops themselves; the `filter` is gone and the elements animate on the compositor. |
+| F7 | — | The gate's own copy check raced the async clipboard write. | The attribute was read synchronously after the click. | The check now waits for the feedback attribute (verified stable across three consecutive runs). |
+| F8 | **P1** | The header rendered as raw inline text — "ProblemDemoArchitectureSurfaceCompareDocs" ran together, with no bar, no background and no sticky behaviour. | The `global.css` rewrite dropped the `.nav` / `.nav-inner` / `.nav-links` rules, and the `Nav.astro` scoped block never replaced them. **A missing CSS rule does not throw** — the element just takes its browser defaults, which is invisible to an overflow check and to axe. | The header chrome moved into `Nav.astro`'s scoped block, where it cannot drift away from the markup, and a new gate check (6b) now measures it. |
+| F9 | — | The gate's own server did not strip the `/musememory` base path, so every stylesheet 404'd and the page rendered unstyled — a false positive that looked exactly like F8. | The server joined the request path onto the dist root without removing the base. | The server now strips the base path, and check 6b would have caught the difference. |
+
+---
+
+## Validation sweep
+
+| Sweep | Result |
+| :--- | :--- |
+| Placeholder / lorem content | none — `lorem`, `TODO`, `FIXME`, `placeholder`, "coming soon" all absent from the built HTML |
+| Debug flags in the output | none — no `console.log` or `debugger` in the built pages |
+| Placeholder secrets | none — no `sk-*` pattern in the built HTML |
+| Copied brand identity | none — the mark, palette and typography are the project's own; no third-party logo or name appears |
+| Unsupported claims | none — every published figure is generated from `src/` via `claims.json`, and `test/published_copy_contracts.test.ts` fails the build on a stale figure |
+| Media provenance | the showreel is rendered from `apps/website/showreel/index.html` in this repository; no third-party footage |
+| Split / staggered text | none — no line-splitting animation, so every control keeps one accessible name |
+| First frame with JS/media disabled | verified — check 11 |
+
+---
+
+## Technical audit by dimension
+
+| Dimension | Grade | Notes |
+| :--- | :--- | :-- |
+| Chrome integrity | **A** | The header and footer are measured, not assumed: `header=sticky`, `inner=flex`, `minGap=30.4px`, `footerCols=5`. A dropped CSS rule can no longer ship silently. |
+| Accessibility | **A** | axe-core clean on 4 pages (0 critical / 0 serious / 0 minor); 26/26 token contrast pairs at WCAG 2.2 AA; 37/37 controls keyboard reachable with a visible focus ring; the page reads fully without JavaScript. |
+| Performance | **A−** | 47 KB transferred on the home page, zero external scripts, zero framework runtime. Motion is transform/opacity only and nothing animates far offscreen. No count-up on the stat tiles: the animate skill's rule is that data the reader acts on must not move for style. |
+| Theming | **A** | One token set in `global.css`; no raw hex in any component; text colour is restricted to three audited tokens. |
+| Responsive | **A** | Fluid `clamp()` type and space scales, logical properties throughout, `min-width: 0` on every grid child, and 200% zoom reflows on all three pages with no loss. |
+| Integrity | **A** | No placeholder content, no debug flags, no secrets; every published number machine-verified against `src/`. |
+
+---
+
+## Scope notes (not blocking)
+
+- **WebKit** was not exercised — the engine is not installed in this environment. It is
+  reported as skipped. Install with `bunx playwright-core install webkit` and re-run the
+  gate before a release that claims WebKit coverage.
+- **No load gate** was run: this is a static marketing site with no request path to
+  saturate. The gate checklist's load clause does not apply.
+- **No analytics** exist by design — the product ships no telemetry. Nothing to fire.
+- **Data isolation, RLS, store-candidate and dependency-advisory clauses** in the
+  qa-launch gate apply to a data product with a database. This release changes a static
+  site and the npm package's published file list; no schema, RLS policy or store
+  candidate is involved.
+
+---
+
+## Rollback
+
+| Path | How |
+| :--- | :--- |
+| Site | Redeploy the previous tag (`git revert` the release merge, or re-run the Pages workflow on the previous SHA). The Pages workflow rebuilds from source, so a revert is a clean rollback. |
+| Showreel | The committed `public/showreel.mp4` and `showreel-poster.png` are the only binary artefacts. Reverting the commit restores the previous pair. |
+| npm | `npm dist-tag add musememory@3.0.1 latest` restores the previous `latest`; a new version cannot be unpublished, only de-tagged. |
+| Package files | The npm `files` list gained `claims.json` and three docs. Removing them is a one-line change with no code impact. |
+
+**Rollback owner**: the repository owner. This is a single-operator repository; the
+owner can execute the rollback alone, which the gate checklist requires before a Ship
+verdict.
+
+---
+
+## Re-run
+
+```bash
+bun run site:build     # rebuild the candidate
+bun run site:qa        # re-execute every check above
+```
+
+The gate is deterministic: it exits non-zero on any blocking failure, so it can be
+wired straight into CI.

package/.agents/context/current.md

@@ -1,12 +1,135 @@
 # 📍 Current Shipped State & Active Invariants
 
-> **Version**: `v3.0.0`  
-> **Status**: Major Release (Failure Attribution, Negative Memory Mining, HOT.md Working Set Compounding & LangMem Logarithmic Frequency Ranking)
+> **Version**: `v3.0.2`  
+> **Status**: Patch Release — correctness fixes from the cross-file invariant audit, machine-verified published claims, and the website redesign.
+
+---
+
+## 🔬 Latest Session — Audit, Documentation & Website Redesign (2026-10-21)
+
+A cross-file invariant audit, a documentation audit, and a full website
+redesign landed together. Everything below is verified by the test suite.
+
+### Code fixes (all regression-tested)
+
+- **Prompt-injection bypass closed (BLOCKER)**: `setCurrent()` in `src/governor.ts` now sanitises injected context blocks before writing `CURRENT.md`, and the session-handoff discovery line in `src/mcp.ts` is sanitised too. Previously only the *stored memory* was sanitised (by `propose()`), so a `memory_capture(type="constraint")` could persist an injection that was replayed into every later prompt. Fixes T-110's stated scope. Cover: `test/audit_blocker_regressions.test.ts`.
+- **Store could fail its own schema (BLOCKER)**: `schema.json` had `additionalProperties: false` but omitted `stale_embedder`, a flag the embedder writes onto entries. Every entry that failed embedding was reported corrupt by `memory validate`, `memory doctor` and `memory verify --strict`.
+- **Bi-temporal queries served the wrong snapshot (BLOCKER)**: the L1 context cache key omitted `as_of` (and the include/type/tag flags), so a "what did we believe in Q1?" query could be answered from a 30-second-old current-state cache entry.
+- **Tiered context dropped `as_of` (BLOCKER)**: `get_context(tier=1, as_of=...)` returned the current state while the untiered path returned the historical one. Both branches now forward `as_of` and `depth`.
+- **Access counter never accumulated (BLOCKER)**: `readEntry()` re-inserted the YAML mirror over the SQLite row, resetting `access_count` to its baseline on every read. The counter fed the access-frequency ranking axis, the LangMem frequency axis and the retention half-life — all were permanently starved. The database row is now authoritative for the counter.
+- **Tier token budget was declared but never enforced**: `resolveTierBudget()` was exported and documented but never called, so Tier 0 emitted 327 tokens against a 200-token budget. The budget now bounds the rendered output and reports what it dropped.
+- **MCP server advertised version `1.6.0`** while the package was at `3.0.0`. The version now comes from `package.json` (`src/version.ts`).
+- **Undiscoverable tools**: `memory_recall`, `memory_get_constraints` and `memory_set_constraints` were callable but absent from `ListTools`. All three are now registered.
+- **Undeclared destructive flags**: `memory_delete` honoured undocumented `apply`/`force` aliases that silently disabled the dry-run default. Only the declared `dry_run` and `confirm` can now disable it.
+- **Snapshot restore had no path containment**: `restoreSnapshotRing()` now resolves strictly inside `.memory/snapshots/`.
+- **`"checkpoint" as any`**: the audit operation is now a declared member of the `AuditOperation` union.
+- **Corroboration predicate de-duplicated**: the 13-line "is this source synthetic" predicate existed in two files. The predicate is now shared (`src/quality/corroboration.ts`); the two *bars* it feeds stay deliberately different and are documented as such.
+- **Title/tag limits declared but not used**: `MAX_TITLE_LENGTH` and `MAX_TAGS` existed while the enforced values were magic numbers. The store and harvester now use the constants, and the draft-title limit is declared as `MAX_DRAFT_TITLE_LENGTH`.
+
+### Published-claim integrity (new)
+
+`scripts/generate-claims.ts` derives every countable claim from `src/` and
+writes `claims.json`; `scripts/generate-cli-reference.ts` writes
+`docs/cli-reference.md` and `docs/mcp-tool-matrix.json`. The website imports
+`claims.json` instead of hard-coding figures.
+
+This exists because the site advertised **80+ coding agents** (real: 52),
+**45+ credential shapes** (real: 8 rule families) and **69 tools across 6
+profiles** (real: 115 across 7), while the README was already honest at 52.
+`test/marketing_claims.test.ts` now fails the build on any drift, on any
+stale figure in the published prose, and on any agent-facing document that
+names a tool which does not exist.
+
+### Documentation
+
+- `docs/agent-reference.md` — new: the agent contract (install, layout, mandatory session protocol, trust gates, failure semantics).
+- `docs/cli-reference.md` — new: generated CLI + MCP reference.
+- `docs/roadmap.md` — new: the sprint board, moved out of the README.
+- `README.md` — restructured: 60-second start, "How it works", "Where your memory lives", a documentation map that separates human docs from agent docs, and a 54KB → 39KB reduction.
+- `.agents/context/product.md` — rewritten against the live registry; it previously named six tools that do not exist.
+- `.agents/standards/frontend-astro.md` — rewritten to match this repo's actual stack (static output, plain CSS, no SSR adapter, no Tailwind, no Motion.dev).
+
+### Website
+
+- Redesigned `apps/website`: shared `Nav`/`Footer`/`Logo` components (the 404 page previously had no navigation at all), a real mobile menu (the nav links were hidden below 860px with no replacement), full SEO head (canonical, OG, Twitter, icons, manifest, skip link), a new "Your memory is a folder" section, and a capability grid that replaces eight long editorial bands.
+- New brand system: a redesigned monogram (the previous mark read as a zigzag, not an "M"), favicon, Apple touch icon, PWA icons, OG card, Twitter card, README banner — all generated deterministically with resvg from the fonts already vendored in the repo.
+- New agent-readable layer: `llms.txt` and `llms-full.txt`, generated from the built HTML.
+- Fixed two real defects the audits caught: a `scrollable-region-focusable` axe failure on `/docs`, and a reveal runtime that stranded any `.reveal` taller than the viewport (the observer used a ratio threshold).
+
+---
+
+## 🔬 Latest Session — Website Rebuild, New Showreel & Published-Copy Contracts (2026-10-22)
+
+A second pass over the same repository, dispatched through the **secretary**
+skills: `content` (copy frameworks), `design` (the developer-vertical
+anatomy), `animate` (motion), and `qa-launch` (the release gate). Five
+findings that were not in the first audit are recorded below; the fixes are
+all regression-tested.
+
+### The copy rule
+
+No user-facing surface may state a count of supported agents. The claim is
+"the majority of coding agents" — a number would age badly and invite a
+precision the registry cannot promise. The precise count stays in
+`claims.json`, where it is a fact about the code rather than a promise about
+the market. `test/published_copy_contracts.test.ts` enforces this across the
+README, all three site pages, the nav, the footer, both asset generators and
+the showreel composition.
+
+### The website
+
+- **Rebuilt on the design skill's developer anatomy**: hero → demo →
+  architecture → code grid → proof → quickstart → licence, with copy on the
+  content skill's AIDA spine and PAS driving the problem block.
+- **New design-token system** (`src/styles/global.css`): fluid `clamp()`
+  spacing and type scales, logical properties throughout, and no fixed
+  values in components. Every container is width-bounded and grid children
+  carry `min-width: 0`, so nothing can break out of the viewport.
+- **New graphic assets**: a 12-icon line set (`src/assets/icons/`, all on a
+  24px grid, measured to a 14–21px optical band) and three inline-SVG
+  figures — a latency chart, a lifecycle state machine and an architecture
+  topology — each bound to `claims.json` so no figure can drift from the code.
+- **A new showreel**, written from scratch: a 12-second "memory lattice"
+  film with an AIDA script, rendered deterministically from
+  `apps/website/showreel/index.html` by a Playwright + ffmpeg pipeline. The
+  previous HyperFrames composition and its private font copy are gone; the
+  fonts now live at `src/assets/fonts/` and are shared with the brand
+  pipeline.
+- **The published latency bounds now live in one place** — `claims.json` →
+  `latency` — and both the hero stats and the latency chart read them, so
+  the page cannot quote two different numbers for the same path.
+
+### Defects the QA gate found (all fixed)
+
+- **The page read blank without JavaScript (P0)**: all 43 `.reveal` elements
+  ship at `opacity: 0` and rely on an `IntersectionObserver`. A `<noscript>`
+  fallback in `Base.astro` now restores the static document.
+- **The mobile menu overflowed the viewport (P1)**: `.nav-actions` is a flex
+  row without `justify-content`, so the group packed to the start and the
+  absolutely-positioned sheet anchored off the left edge (`x = -73`).
+- **The copy button's fallback hint said "Press ⌘C" on every platform (P1)**.
+- **A `<p>` inside a `<dl>`'s wrapper div (P1)** — an axe-core
+  `definition-list` violation on the metric grid.
+- **Two animated elements combined `filter: blur()` with a transform
+  animation (P2)** — a per-frame re-rasterisation of the blur. The softness
+  now comes from the gradient stops, so the motion stays on the compositor.
+
+### The gate itself is executable
+
+`apps/website/scripts/qa-gate.ts` runs the qa-launch gate checklist as
+code — critical paths, the keyboard-only path, 200% zoom reflow, the
+no-JavaScript first frame, animation performance, a placeholder/debug
+sweep, the payload budget, and a second rendering engine. It exits non-zero
+on any blocking failure, so CI runs it. Report:
+`.agents/artifacts/qa-gate-2026-10-22.md` — **16/16, SHIP**.
 
 ---
 
 ## ⏭️ Next Up (Post-Wave 22 Focus)
+- **Production-Grade Showcase Demo**: Re-record high-fidelity terminal demo video/GIF reflecting v3.0.0 capabilities (failure attribution, HOT.md compounding, memory branch/checkout, MCP context recall) to replace removed legacy demo.
 - **Wave 23**: Review next backlog items from `.agents/context/ticket-plan.md` (e.g. Hebbian co-activation retrieval expansion, query-seeded PPR restart set, retrieval weight auto-tuner, and contradiction engine calibration).
+- **Consolidate the remaining duplicated tables** (deferred from this session as behaviour-changing; full detail with exact locations in [`docs/roadmap.md`](../../docs/roadmap.md) → *Engineering debt*): the three divergent per-type TTL tables in `src/retention.ts`, the eight separate token estimators, the divergent limit-clamping ceilings across retrieval paths, and the remaining zero-caller exports.
+- **Remove the legacy `web/` directory** — done in this session. It was a second, hand-written copy of the site that `apps/website/` superseded; keeping it was the same "second copy that gets forgotten" failure mode this session fixed everywhere else.
 
 ---
 

package/.agents/context/deep-research-agentic-memory-evolution.md

@@ -4,7 +4,7 @@
 **Depth**: Deep (Local scan, ecosystem signals, frontier literature, competitive analysis, architectural specification)  
 **Date**: 2026-09-06  
 **Operating Identity**: Muse (Chief Agency Orchestrator)  
-**Primary Repository**: [`musememory`](file:///home/harsh/Projects/github/musememory)  
+**Primary Repository**: [`musememory`](../../)  
 
 ---
 

package/.agents/context/index.md

@@ -1,6 +1,8 @@
 # 📖 Muse Memory Context Index
 
 > **Reading Directive**: Durable project truth for Muse Memory lives in `./.agents/context/`. Start at this index, then load **only** the specific context file your active task requires.
+>
+> **Do not read or write `.memory/**`** — that directory is owned by the MuseMemory engine itself and is out of scope for agent context work.
 
 ---
 
@@ -8,14 +10,52 @@
 
 | File | Scope & Contents | When to Read |
 | :--- | :--- | :--- |
-| [`product.md`](./product.md) | Product scope, CLI tools (`memory`, `musememory`), and MCP tool matrix | Understanding user commands, capabilities, and MCP protocols |
+| [`product.md`](./product.md) | Product scope, the live MCP tool matrix, the 7 task profiles, the CLI surface, and the trust gates an agent must assume | Understanding user commands, capabilities, and MCP protocols |
 | [`architecture.md`](./architecture.md) | Dual-Scope storage (`.memory/`), SQLite DB, retrieval scoring formula, and file layout | System design, file locations, state machine, and data flow |
 | [`brand.md`](./brand.md) | Persona profiles (`USER.md` archetypes), voice, and presentation rules | Writing prompts, terminal output copy, and user documentation |
-| [`current.md`](./current.md) | Current shipped state (v2.0.0), test coverage, and active constraints | Before starting work on bugs, features, or refactors |
+| [`current.md`](./current.md) | Current shipped state (**v3.0.2**), test coverage, and active constraints | Before starting work on bugs, features, or refactors |
 | [`decisions.md`](./decisions.md) | Locked architectural decisions (zero-daemon, file-backed SQLite, atomic I/O) | Evaluating technical choices or refactors |
 | [`roadmap.md`](./roadmap.md) | Planned improvements, ecosystem expansions, and backlog | Scoping new capabilities |
+| [`ticket-plan.md`](./ticket-plan.md) | Detailed ticket plan for the next work waves | Planning a specific wave of work |
 | [`deep-research-agentic-memory-evolution.md`](./deep-research-agentic-memory-evolution.md) | Deep research brief & architectural plan for agentic cognitive OS evolution | Designing R17-R22 milestones and feature implementations |
 | [`deep-research-memory-mechanisms-2026-09.md`](./deep-research-memory-mechanisms-2026-09.md) | 86-system memory feature matrix with per-system mechanisms and measured claims | Competitive research, capability scoping, mechanism adaptation |
 | [`deep-research-memory-adaptation-2026-10.md`](./deep-research-memory-adaptation-2026-10.md) | Scored adaptation shortlist (impact × feasibility) against the 86-system study, with the top-3 ranked adaptations and their acceptance tests | Choosing what to build next from competitor mechanisms |
-| [`deep-research-memory-improvement-2026-10.md`](./deep-research-memory-improvement-2026-10.md) | Deep research brief: 9 new memory systems (Memoir, ai-memory, GAM, Engram, etc.), updated gap scorecard (4 new versioned-memory gaps), scored adaptation shortlist (A15–A22), and R23–R26 production-readiness roadmap | Designing R23–R26 milestones, versioned memory features, and monetization positioning |
+| [`deep-research-memory-improvement-2026-10.md`](./deep-research-memory-improvement-2026-10.md) | Deep research brief: 9 new memory systems, updated gap scorecard, scored adaptation shortlist (A15–A22), and R23–R26 production-readiness roadmap | Designing R23–R26 milestones, versioned memory features, and monetization positioning |
 | [`../artifacts/bench-graph-baseline.md`](../artifacts/bench-graph-baseline.md) | Measured graph/dashboard baseline at 100/1k/10k memories, hypothesis verdicts, and the fix order for the instant-graph workstream | Before changing `src/ui.ts`, `src/graph.ts`, or the dashboard render path |
+
+---
+
+## 📄 User-facing documentation (repository `docs/`)
+
+| File | Audience | Purpose |
+| :--- | :--- | :--- |
+| [`docs/user-guide.md`](../../docs/user-guide.md) | Humans | The daily pair-programming loop: ground → constrain → capture. |
+| [`docs/concepts.md`](../../docs/concepts.md) | Humans | Core concepts and the guarded 7-state lifecycle machine. |
+| [`docs/team-getting-started.md`](../../docs/team-getting-started.md) | Humans | Team setup: server, auth, client recipes. |
+| [`docs/roadmap.md`](../../docs/roadmap.md) | Humans | The sprint board (requested → planned → in progress → done). |
+| [`docs/agent-reference.md`](../../docs/agent-reference.md) | **Agents** | The contract: install, file layout, mandatory session protocol, trust gates, failure semantics. |
+| [`docs/cli-reference.md`](../../docs/cli-reference.md) | **Agents** | Every CLI command and every MCP tool — **generated** from `src/`. |
+| [`docs/mcp-tool-matrix.json`](../../docs/mcp-tool-matrix.json) | **Agents** | The tool list as JSON — **generated** from `src/`. |
+| [`claims.json`](../../claims.json) | **Agents** | Every countable claim — **generated** from `src/`. |
+
+### Generated documentation is never hand-edited
+
+`docs/cli-reference.md`, `docs/mcp-tool-matrix.json` and `claims.json` are
+produced by `scripts/generate-claims.ts` and
+`scripts/generate-cli-reference.ts`. Regenerate them after any CLI or MCP
+change:
+
+```bash
+bun run scripts/generate-claims.ts
+bun run scripts/generate-cli-reference.ts
+```
+
+`test/marketing_claims.test.ts` fails the build when the generated files and
+the source disagree, when a published figure is stale, or when an agent-facing
+document names a tool that does not exist.
+
+### The website's agent-readable layer
+
+`apps/website` publishes `llms.txt` (a curated map) and `llms-full.txt` (the
+whole site as plain text). Both are generated from the built HTML by
+`apps/website/scripts/build-llms-txt.ts`, so they cannot drift from the site.