musememory 3.0.0 → 3.0.1

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/context/current.md

@@ -1,12 +1,68 @@
 # 📍 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.1`  
+> **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).
 
 ---
 
 ## ⏭️ 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.1**), 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.

package/.agents/context/product.md

@@ -1,101 +1,167 @@
 # 📦 Muse Memory Product Scope & Capabilities
 
-> **Binary Names**: `memory` (primary), `musememory` (alias), `npx musememory` (zero-install)  
-> **MCP Protocol**: MCP 2024-11-05 (stdio transport)  
+> **Binary Names**: `memory` (primary), `musememory` (alias), `npx musememory` (zero-install)
+> **MCP Protocol**: MCP `2024-11-05`, `2025-06-18` (stdio transport)
 > **Runtime**: Bun / TypeScript (Node-compatible bundle)
+> **Authoritative counts**: [`claims.json`](../../claims.json) — generated from `src/` by `scripts/generate-claims.ts`.
+> **Authoritative tool list**: [`docs/mcp-tool-matrix.json`](../../docs/mcp-tool-matrix.json) — generated, never hand-typed.
+> **Full tool + flag reference**: [`docs/cli-reference.md`](../../docs/cli-reference.md) — generated.
+> **Agent contract**: [`docs/agent-reference.md`](../../docs/agent-reference.md).
+
+> ⚠️ **Do not hand-type tool or command names in this file.** Every tool name
+> below is asserted against the live registry by
+> `test/marketing_claims.test.ts`; a name that does not exist fails the build.
 
 ---
 
 ## 🎯 Executive Overview
 
-Muse Memory is a zero-daemon, file-backed cognitive memory engine designed to give AI agents (Claude Code, Cursor, Antigravity, Windsurf, Codex, Gemini CLI, Hermes, OpenCode, OpenClaw, etc.) persistent, self-organizing memory across sessions without external database daemons or cloud servers.
+Muse Memory is a zero-daemon, file-backed cognitive memory engine that gives AI agents
+(Claude Code, Cursor, Antigravity, Windsurf, Codex, Gemini CLI, Hermes, OpenCode,
+OpenClaw, and the rest of the detected registry) persistent, self-organizing memory
+across sessions — without an external database daemon, an account, or a cloud service.
+
+- **MCP tools registered**: `claims.json → mcpTools`
+- **Task profiles**: `claims.json → mcpProfiles` (`core`, `coding`, `debugging`, `review`, `architecture`, `maintenance`, `full`)
+- **Coding agents auto-wired**: `claims.json → agentPlatforms`
+- **External memory formats importable**: `claims.json → migratorProviders`
+- **Credential rule families**: `claims.json → credentialRuleFamilies`
+- **Background daemons**: `claims.json → backgroundDaemons`
 
 ---
 
-## 🔌 Comprehensive MCP Tool Matrix
+## 🔌 Flagship Orchestration & Intelligence Tools
 
-### 🎯 Flagship Orchestration & Intelligence Tools
 | MCP Tool | Execution Phase | Agent Purpose |
 | :--- | :--- | :--- |
-| `muse_context` | **Flagship Orchestration** | Unified context fusion: single-call query combining search, active file, symbol, error messages, and task intent under strict knapsack token budgets. |
-| `muse_health` | **Quality Gate** | 5-Pillar Project Health Gate: single-call audit of store integrity, code anchors, doc/code alignment, anti-pattern sentry, and technical debt with A-F grading and PASS/WARN/FAIL status. |
-| `muse_why` | **Cognition / "Why" Reasoner** | Traces code evolution backwards through past bug fixes, ADRs, trade-offs, and invariants to explain *why* code is designed the way it is before refactoring. |
-| `muse_bug_clusters` | **Fragility Hotspots** | Clusters recurring bugs into 5 root-cause categories with subsystem fragility scoring. |
-| `muse_tech_debt` | **Technical Debt Registry** | Scans code and memory for TODO/FIXME markers, unsafe `as any` casts, and drifted anchors with remediation advice. |
-| `muse_memory_for_code`| **Code-to-Memory** | Queries all memories, ADRs, constraints, and bugs associated with a code file and symbol. |
-| `muse_code_for_memory`| **Memory-to-Code** | Resolves all native code anchors and affected source files for a given memory entry. |
-| `memory_adr_record` | **Architecture Decisions**| Records first-class ADRs with drivers, decision, consequences, options considered, and native code anchors. |
-| `memory_adr_list` | **ADR Discovery** | Lists architecture decision records filtered by status (`proposed`, `accepted`, `superseded`, `rejected`). |
-| `memory_drift_audit` | **Drift Detection** | Bi-directional documentation $\longleftrightarrow$ code drift engine across 6 alignment states. |
-| `memory_capture_negative` | **Negative Sentry** | Records failed approaches, anti-patterns, and reproduction commands to prevent repeating mistakes. |
-| `memory_promote_scope` | **Scoped Promotion** | Promotes memory along 3-tier ladder (`local` $\rightarrow$ `project` $\rightarrow$ `global`) with 5× repeated success policy and universal generalization. |
-| `memory_archive` / `rehydrate` | **Archival Lifecycle** | Evaluates and manages `active` $\rightarrow$ `cold` $\rightarrow$ `dormant` $\rightarrow$ `archived` lifecycle with query rehydration. |
-| `anchor_create` / `verify` / `audit` | **Code Identity** | Creates, verifies, and audits line-independent structural code anchors. |
-| `muse_sync_broadcast` / `ingest` | **P2P Gossip Mesh** | Broadcasts and ingests portable sealed SyncPackets with deduplication and contradiction flagging. |
-| `muse_sync_status` / `pool` | **Sync Coordination** | Tracks peer vector clocks and synchronizes memories bidirectionally via shared drop-directory pool. |
-| `muse_mesh_status` | **Monorepo Topology** | Discovers monorepo workspaces and multi-repo sibling groups with package dependencies and stores. |
-| `muse_mesh_query` | **Cross-Project Query** | Queries memories across the entire workspace mesh with origin package provenance tags. |
-| `muse_mesh_audit` | **Contract Verification** | Audits cross-package dependency contracts, entrypoint exports, and cross-repo code anchors. |
-| `muse_mesh_link` | **Mesh Linking** | Explicitly links or unlinks external repository paths into the workspace mesh registry. |
-
-### 🛠️ Core Memory & Lifecycle Tools
+| `muse_context` | **Flagship Orchestration** | Unified context fusion: single-call query combining search, active file, symbol, error messages and task intent under strict knapsack token budgets. |
+| `muse_health` | **Quality Gate** | 5-Pillar Project Health Gate: store integrity, code anchors, doc/code alignment, anti-pattern sentry and technical debt, with A-F grading and PASS/WARN/FAIL status. |
+| `muse_why` | **Cognition / "Why" Reasoner** | Traces code evolution backwards through past bug fixes, ADRs, trade-offs and invariants before a refactor. |
+| `muse_bug_clusters` | **Fragility Hotspots** | Clusters recurring bugs into root-cause categories with subsystem fragility scoring. |
+| `muse_tech_debt` | **Technical Debt Registry** | Scans code and memory for TODO/FIXME markers, unsafe `as any` casts and drifted anchors. |
+| `muse_code_impact` | **Blast Radius** | Synthesises code callers, governing ADRs, negative warnings and a risk score for a file. |
+| `muse_pr_context` | **Change Context** | Generates a memory-grounded PR description from a git diff. |
+| `muse_memory_for_code` | **Code-to-Memory** | Queries all memories, ADRs, constraints and bugs associated with a code file and symbol. |
+| `muse_code_for_memory` | **Memory-to-Code** | Resolves all native code anchors and affected source files for a given memory entry. |
+| `muse_reconcile_anchors` | **Anchor Repair** | Prunes dead references and refreshes structural hashes across the store. |
+| `muse_profile_list` | **Tool Management** | Lists the task-focused profiles and the tools each one exposes. |
+| `memory_adr_record` / `memory_adr_list` | **Architecture Decisions** | Records and lists living ADRs with drivers, consequences, options considered and native code anchors. |
+| `memory_drift_audit` | **Drift Detection** | Bi-directional documentation ↔ code drift engine across 6 alignment states. |
+| `memory_negative_capture` | **Negative Sentry** | Records failed approaches, anti-patterns and reproduction commands so they are not repeated. |
+| `memory_promote` | **Scoped Promotion** | Promotes memory along the `local` → `project` → `global` ladder with a 5× repeated-success policy. |
+| `memory_archive` / `memory_rehydrate` | **Archival Lifecycle** | Manages `active` → `cold` → `dormant` → `archived` with query rehydration. |
+| `memory_anchor_create` / `memory_anchor_verify` / `memory_anchor_audit` | **Code Identity** | Creates, verifies and audits line-independent structural code anchors. |
+| `muse_sync_broadcast` / `muse_sync_ingest` | **P2P Gossip Mesh** | Broadcasts and ingests sealed `SyncPacket`s with deduplication and contradiction flagging. |
+| `muse_sync_status` / `muse_sync_pool` | **Sync Coordination** | Tracks peer vector clocks and synchronises memories through the shared drop-directory pool. |
+| `muse_mesh_status` | **Monorepo Topology** | Discovers monorepo workspaces and multi-repo sibling groups. |
+| `muse_mesh_query` | **Cross-Project Query** | Queries memories across the workspace mesh with origin-package provenance tags. |
+| `muse_mesh_audit` | **Contract Verification** | Audits cross-package dependency contracts, entrypoint exports and cross-repo anchors. |
+| `muse_mesh_link` | **Mesh Linking** | Links or unlinks external repository paths in the workspace mesh registry. |
+
+## 🛠️ Core Memory & Lifecycle Tools
+
 | MCP Tool | Execution Phase | Agent Purpose |
 | :--- | :--- | :--- |
-| `get_context` | **Session Start / Init** | Fast token-budgeted prompt context injection: retrieves `USER.md`, active `CURRENT.md` constraints, and top-$K$ scored memories. |
-| `memory_capture` | **Learning / Task End** | Capture new durable facts, verified architectural decisions, operational rules, or bug resolutions directly into memory. |
-| `memory_propose` | **Speculative Learning** | Propose a candidate memory requiring confirmation before permanent indexing. |
-| `memory_confirm` | **Validation Phase** | Promote a `candidate` or `disputed` memory to `confirmed` status. |
-| `memory_supersede` | **Refactoring / Updates** | Formally link an obsolete memory to a newer confirmed memory so agents never hallucinate deprecated patterns. |
-| `memory_search` | **Targeted Lookups** | Query the SQLite store and YAML mirrors using multi-factor similarity matching and tags. |
-| `memory_conflicts` | **Conflict Audit** | Lists conflicting memories detected by the semantic contradiction engine. |
-| `memory_resolve_conflict` | **Conflict Resolution**| Resolves contradictions via `supersede`, `historical`, `reject`, or `keep_both`. |
-| `memory_roi` | **Utility & ROI** | Computes memory reuse metrics, application success rates, and regression penalties. |
-| `memory_search_transcripts` | **Historical Archaeology** | Full-text dialogue search across past JSONL conversation transcripts with conversation bookends. |
-| `memory_audit` | **Compliance Check** | Inspect the append-only operational ledger (`.memory/audit.jsonl`). |
-| `profile_list` / `switch` | **Tool Management** | Lists and activates task-focused MCP profiles to eliminate agent tool bloat. |
+| `get_context` | **Session Start / Init** | Token-budgeted prompt context injection: `USER.md`, active `CURRENT.md` constraints and top-$K$ scored memories. **Call this on the first turn of every session.** |
+| `muse_context` | **Task Start** | Task-shaped fused context (constraints + ranked memories + negative lessons + code anchors). |
+| `memory_capture` | **Learning / Task End** | Persist a durable fact, decision, rule or fix. Secret-scanned and citation-verified. |
+| `memory_confirm` | **Validation Phase** | Promote a `candidate` or `disputed` memory to `confirmed`. |
+| `memory_supersede` | **Refactoring / Updates** | Link an obsolete memory to a newer confirmed one so deprecated patterns are never served. |
+| `search` | **Targeted Lookups** | Ranked search over the store with a score breakdown and filters. |
+| `memory_recall` | **Targeted Lookups** | Recall active and confirmed memories with verification levels and related graph links. |
+| `memory_current` / `memory_get_constraints` / `memory_set_constraints` | **Constraints** | Read, append and manage the active working constraints in `CURRENT.md`. |
+| `memory_resolve_conflict` | **Conflict Resolution** | Resolves contradictions via `supersede`, `historical`, `reject` or `keep_both`. |
+| `memory_roi` | **Utility & ROI** | Computes reuse metrics, application success rates and regression penalties. |
+| `memory_search_transcripts` | **Historical Archaeology** | Full-text dialogue search across past JSONL transcripts with conversation bookends. |
+| `memory_audit` | **Compliance Check** | Inspects the append-only operational ledger (`.memory/audit.jsonl`). |
+| `memory_verify` / `memory_verify_strict` | **Integrity Gate** | Runs an entry's template-gated verification command, or the full strict integrity gate. |
 
 ---
 
 ## ⚙️ Task-Focused MCP Profiles
 
-Muse Memory prevents agent context bloat by providing 6 pre-configured tool profiles:
-
-- **`core`** (Minimal): `get_context`, `memory_search`, `memory_capture`, `memory_current`, `profile_list`, `profile_switch`.
-- **`coding`**: Core tools + `muse_context`, `muse_why`, `muse_code_for_memory`, `muse_memory_for_code`, `anchor_*`.
-- **`debugging`**: Core tools + `muse_why`, `muse_bug_clusters`, `memory_capture_negative`, `memory_verify`.
-- **`review`**: Core tools + `muse_health`, `muse_tech_debt`, `memory_drift_audit`, `anchor_audit`.
-- **`architecture`**: Core tools + `muse_context`, `muse_health`, `memory_adr_*`, `memory_drift_audit`, `muse_why`.
-- **`maintenance`**: Core tools + `muse_health`, `memory_promote_scope`, `memory_archive`, `memory_archive_sweep`, `memory_lifecycle_stats`.
-- **`full`**: Unrestricted exposure of all 61 MCP tools.
+Seven profiles keep the tool surface small. The authoritative mapping is
+`PROFILE_TOOL_DEFINITIONS` in `src/orchestrator/profiles.ts`; call
+`muse_profile_list` for the live list. Select a profile with the
+`MUSE_MCP_PROFILE` environment variable.
+
+| Profile | Purpose |
+| :--- | :--- |
+| `core` | Minimal footprint: context injection and rapid capture. |
+| `coding` | Active development, code anchors, contextual fusion. |
+| `debugging` | Bug diagnosis, error resolution, observations, negative lessons. |
+| `review` | Code review, architectural audit, conflict verification. |
+| `architecture` | System design, promotions, entity wiki, tree indexing, mesh. |
+| `maintenance` | Repository health, deduplication, archival lifecycle, mesh. |
+| `full` | The complete registry — every registered tool. |
 
 ---
 
 ## 💻 CLI Command Surface
 
+Only the commands an agent actually calls. The full matrix — every command,
+every flag, generated from `src/cli.ts` — is in
+[`docs/cli-reference.md`](../../docs/cli-reference.md).
+
 ```bash
-# Health & Observability (5-Pillar Quality Gate)
-memory health [--json] [--global]
-
-# Retrieval & Context
-memory context [--query "..."] [--budget 2000] [--tier 0|1|2]
-memory search "<query>" [--tags arch,auth]
-memory recall "<id>"
-
-# Knowledge Lifecycle
-memory capture --title "..." --type architecture --content "..."
-memory propose --title "..." --content "..."
-memory confirm <id>
-memory supersede <old-id> <new-id>
-memory stale <id>
-memory audit [--limit 20]
-
-# Personas & Constraints
-memory persona [developer|designer|marketer|casual]
-memory current --add "Must use Bun v1.2"
-
-# Diagnostics, Server & Optimization
-memory optimize [--dry-run] [--force] [--project core]
-memory doctor
-memory validate --dry-run
-memory mcp [--profile coding|review|architecture|core|full]
+# Session start
+memory context [query] --token-budget 2000   # fused context for the prompt
+memory search "<query>" --limit 10            # ranked search with score breakdown
+
+# Capture and lifecycle
+memory capture "<text>" --project <name>      # persist a memory
+memory confirm <id>                           # candidate -> confirmed
+memory supersede <old_id> --with <new_id>     # replace, keeping lineage
+memory current get                            # read active constraints
+memory current set "<text>" --project <name>  # append a constraint
+memory link <id> --related <id1,id2>          # bidirectional relation
+
+# Governance
+memory audit [--operation OP] [--limit N]     # query the audit ledger
+memory validate [--dry-run]                   # schema + referential integrity
+memory verify <id> --strict                   # integrity gate
+memory doctor                                 # ecosystem health diagnostic
+memory health [--json]                        # 5-pillar health gate
 ```
+
+### Commands that do **not** exist
+
+These appear in older notes and are wrong — calling them fails:
+
+| Wrong | Correct |
+| :--- | :--- |
+| `memory persona <archetype>` | `memory user init <archetype>` |
+| `memory current --add "..."` | `memory current set "..."` |
+| `memory recall "<id>"` | `memory recall "<query>"` — ID lookup is `memory checkout <id>` |
+| `memory stale <id>` | `memory stale [--days N]` — it **lists** stale entries |
+| `memory mcp --profile coding` | Set `MUSE_MCP_PROFILE=coding` in the environment |
+| `memory health --global` | `memory health --json` only — no `--global` flag |
+
+---
+
+## 🔒 Trust Gates (behaviour an agent must assume)
+
+| Gate | When | Behaviour |
+| :--- | :--- | :--- |
+| Secret scan (Vibeguard) | every write | The write is **refused**; the rule name is reported, never the value. |
+| Citation verification | every write with an anchor | **Refused** under the default `fail_fast` policy when the cited file/symbol does not exist; drift is flagged and stamped. |
+| Freshness gate | every recall | Memories whose anchors drifted are **withheld** and reported (`withheld_memories` + `freshness_notice`), never silently served. `include_drifted: true` returns them with a `⚠ FRESHNESS` warning. |
+| Ingest sanitisation | import / harvest | Injected `<memory-context>` blocks and base64 payloads are stripped before the text is stored — including into `CURRENT.md`. |
+| Template-gated execution | `memory verify` | Only `bun test <relative test file>`, `bunx tsc --noEmit` and `node --check <relative path>` may run. There is no shell-execution tool. |
+
+---
+
+## 📁 Storage Layout
+
+| Path | Scope | Contents |
+| :--- | :--- | :--- |
+| `.memory/memory.db` | project | SQLite (WAL + FTS5): memories, anchors, graph edges, FTS index. |
+| `.memory/memories/*.yaml` | project | One human-readable YAML file per memory — the secondary mirror. |
+| `.memory/CURRENT.md` | project | Active working constraints and session handoffs. |
+| `.memory/USER.md` | project | Persona and working preferences. |
+| `.memory/observations.jsonl` | project | Append-only event log the harvester mines. |
+| `.memory/audit.jsonl` | project | Tamper-evident write ledger. |
+| `.memory/sync_pool/` | project | Zero-daemon shared gossip pool. |
+| `~/.memory/` | global | The same layout; project scope wins on conflict. |
+
+Everything is a plain file. There is no server, no port and no service to keep alive.

package/.agents/context/roadmap.md

@@ -15,6 +15,14 @@
 
 ## 🚀 Active Roadmap & Future Horizons (Agentic Cognitive OS Evolution)
 
+### 0. **DX & Project Showcase Assets (Pending Triage)**
+- **Production-Grade Showcase Demo Video & GIF**:
+  - Re-record high-fidelity terminal demo video (`showreel.mp4`) and GIF (`muse-memory-demo.gif`) reflecting v3.0.0 capabilities.
+  - Showcase real workflows: failure attribution with decaying strikes, negative fix-pair mining, HOT.md candidate compounding, `memory branch` / `checkout`, and MCP context recall.
+  - Replace legacy inaccurate SVG render with an authentic, crisp terminal capture.
+
+---
+
 ### 1. **R17: Tri-Cognitive Memory Architecture (Procedural Playbooks & Episodic Horizons)**
 - **Procedural Playbook Engine (`ProceduralMemory`)**:
   - Capture executable tool-calling workflows, pre-conditions, step trajectories, verification assertions, and rollback recipes distilled from successful agent sessions.

package/.agents/research/research-brief-agent-memory-migrator.md

@@ -3,7 +3,7 @@
 **Depth**: deep  
 **Date**: 2026-08-22  
 **Target Repository**: `harshsinghmp/musememory`  
-**Primary Deliverable**: Interactive Dashboard at [`musemeory-comparison.html`](file:///home/harsh/Projects/musememory/musemeory-comparison.html) & Autonomous First-Install Migrator
+**Primary Deliverable**: Interactive Dashboard at [`docs/research/musememory-comparison.html`](../../docs/research/musememory-comparison.html) & Autonomous First-Install Migrator
 
 ---
 

package/.agents/standards/README.md

@@ -0,0 +1,42 @@
+# 📚 Standards Index
+
+> **Reading order**: the root [`AGENTS.md`](../../AGENTS.md) is the router. It
+> links the standards that apply to this repository. Everything else in this
+> folder is retained but **not routed** — see "Unrouted standards" below.
+>
+> Load a standard on demand, not up front. Each one states what it governs and
+> when to open it.
+
+## Routored from `AGENTS.md`
+
+| Standard | Governs |
+| :--- | :--- |
+| [`execution-kernel.md`](./execution-kernel.md) | Judgment laws, refactoring discipline, code-complete standards, byte-capping. |
+| [`security-vibeguard.md`](./security-vibeguard.md) | Secret isolation, the Destructive Command Gate, untrusted tool output. |
+| [`system-design.md`](./system-design.md) | Domain modelling, resilience, migration rehearsal, schemas. |
+| [`workflows.md`](./workflows.md) | Scaled tiers, the 5-phase pipeline, PR-per-feature and the post-merge sequence. |
+| [`git-workflow.md`](./git-workflow.md) | Branch lifecycle, commit standards, SemVer. |
+| [`dox-hierarchy.md`](./dox-hierarchy.md) | Reading order, child document shape, the closeout checklist, the pruning loop. |
+| [`council-roles.md`](./council-roles.md) | Muse / Sol / Jasper / Crew / Nexus responsibilities and subagent dispatch policy. |
+| [`memory-context.md`](./memory-context.md) | Context hygiene, the `.memory` store lifecycle, durable proposals. |
+| [`frontend-astro.md`](./frontend-astro.md) | The `apps/website` stack: the `/musememory` base-path rule, generated assets, the a11y and visual gates. |
+
+The brand and accessibility standards live in [`../brand/`](../brand/) and are
+routed from the same place: `design.md`, `bem-conventions.md`, `a11y.md` and
+`screenshots/README.md`.
+
+## Unrouted standards (retained, not applicable)
+
+These files are kept for the day the stack changes. They are **not** linked
+from `AGENTS.md` because following them today would lead an agent to build
+something this repository does not have.
+
+| Standard | Why it is not routed |
+| :--- | :--- |
+| [`frontend-nextjs.md`](./frontend-nextjs.md) | The site is Astro with static output. There is no Next.js, no React Server Components, and no SSR adapter in this repository. |
+| [`backend-workers-hono.md`](./backend-workers-hono.md) | Hono is not a dependency. The engine is a Bun/TypeScript CLI and an MCP stdio server; there is no HTTP worker tier. |
+| [`tech-stacks.md`](./tech-stacks.md) | A general catalogue of stacks rather than a standard. Useful when choosing a new dependency, not when implementing in this one. |
+
+If a future change adopts one of these stacks, re-link the file from
+`AGENTS.md` **and** rewrite it against the real codebase before it is used —
+most generic standards assume a different layout than this repository has.