musememory 3.0.0 → 3.0.2

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.

package/.agents/standards/frontend-astro.md

@@ -1,50 +1,132 @@
 # 🚀 Astro Frontend Engineering Standards
 
-> **Runtime Target**: Astro v7.2.x · Bun / Node pinned runtime · TypeScript Strict · `@astrojs/cloudflare`
+> **Runtime Target**: Astro v7.3.x · Bun / Node runtime · TypeScript Strict
+> **Applies to**: `apps/website/` — the Muse Memory marketing and documentation site.
 
 ---
 
-## 1. Architectural Conventions
+## 1. Project Shape (verified against this repo)
 
-### Static-First & Island Hydration
-- **Static by Default**: All `.astro` components render to static HTML at build time or server edge.
-- **Selective Hydration**: Hydrate client islands with `client:*` directives ONLY when user interaction requires it:
-  - `client:load` — Critical above-the-fold interactive components (e.g., global navigation toggle, hero configurator).
-  - `client:idle` — Lower-priority interactive widgets (e.g., search modal, newsletter popup).
-  - `client:visible` — Below-the-fold components (e.g., heavy testimonials carousel, interactive calculator).
-  - `client:media` — Components conditional on media queries.
+| Fact | Value | Source of truth |
+| :--- | :--- | :--- |
+| Framework | Astro `^7.3.5` | `apps/website/package.json` |
+| Output | `static` (no SSR adapter) | `apps/website/astro.config.mjs` |
+| Base path | `/musememory` (GitHub Pages) | `apps/website/astro.config.mjs` |
+| Site origin | `https://harshsinghmp.github.io` | `apps/website/astro.config.mjs` |
+| Styling | Plain CSS with design tokens (no Tailwind, no UnoCSS) | `apps/website/src/styles/global.css` |
+| Motion | CSS keyframes + one inlined `IntersectionObserver` script | `apps/website/src/scripts/motion.ts` |
+| Tests | `bun test` (axe-core + Playwright audits) | `apps/website/scripts/audit-*.ts` |
 
-### Content Collections & Validation
-- Content collections live strictly in `src/content/`.
-- Every collection must define a strict **Zod schema** in `src/content/config.ts`.
-- Validate all incoming parameters, frontmatter, and external data at the collection boundary.
+> The generic Astro standard assumes `@astrojs/cloudflare`, Tailwind v4 and
+> Motion.dev. **This project does not use them.** Do not introduce an SSR
+> adapter, a utility CSS framework, or a JS animation runtime to solve a
+> problem the current stack already solves.
 
 ---
 
-## 2. Styling & Motion Standards
+## 2. Architectural Conventions
 
-- **Styling**: UnoCSS v66.x or Tailwind CSS v4 utility classes inline. Extract to a dedicated component or BEM class when a utility pattern is repeated 3+ times.
-- **Design Tokens**: Consume design tokens from `./.agents/brand/tokens/` or CSS variables. Never introduce arbitrary raw hex codes or ad-hoc pixel values.
-- **Animations**: Use **Motion.dev** (Framer Motion v12+). All animations must respect `@media (prefers-reduced-motion: reduce)`.
+### Static by default
+Every page renders to static HTML at build time. There is no client framework
+and no hydration directive (`client:load` and friends are not used — the site
+ships zero framework JS). Interactive behaviour is progressive enhancement:
+the navigation menu is a `<details>` element, the FAQ is `<details>`, the
+reveal animation is CSS plus one observer.
+
+### The base path is not optional
+The site is served from `/musememory/`. **Every** internal URL must be built
+from `import.meta.env.BASE_URL` or it will resolve on the domain root and
+404. A root-absolute `/favicon.svg` is a bug, not a style choice.
+
+```astro
+<a href={`${import.meta.env.BASE_URL}/docs`}>Docs</a>
+```
+
+### Shared components, not copied markup
+Navigation, footer and the logo live in `src/components/`. They were
+copy-pasted per page and had already drifted (the 404 page had no nav at
+all). If a page needs a nav variant, add a prop — do not fork the component.
+
+### The published numbers are generated
+`claims.json` (repository root) holds every countable claim, generated from
+`src/` by `scripts/generate-claims.ts`. The site imports it:
+
+```astro
+import claims from "../../../../claims.json";
+```
+
+Never hand-type a count, a tool total or a test count into a page. A test
+(`test/marketing_claims.test.ts`) fails the build if the prose and the code
+disagree.
+
+### Content collections
+`src/content/` does not exist in this project. If it is ever introduced, every
+collection must define a strict schema and validate at the collection
+boundary.
 
 ---
 
-## 3. Testing & Code Quality
+## 3. Styling & Motion Standards
 
-- **Testing**: Vitest for unit and component tests; Playwright for end-to-end user journeys. Tests live adjacent to source files (`*.test.ts`).
-- **No Network in Tests**: Never run unit tests that make real outbound network requests. Mock at the `fetch` boundary.
-- **Type Strictness**: No `any` or forced casts (`as unknown as Type`). Fix the root interface.
-- **Clean Logging**: Never commit `console.log`. Use structured logging or logger utilities.
+- **Tokens only**: consume the CSS custom properties in `global.css` or the
+  JSON in `./.agents/brand/tokens/`. Never introduce an arbitrary hex code.
+- **Text colour is restricted**: only `--text`, `--text-dim` and `--text-faint`
+  may carry text. The depth palette (`--plasma`, `--indigo`, `--edge-*`) is
+  decorative and has no contrast obligation. Every text token is audited
+  against WCAG 2.2 AA by `scripts/audit-a11y.ts`.
+- **Class naming**: BEM per `./.agents/brand/bem-conventions.md`.
+- **Animations** must respect `@media (prefers-reduced-motion: reduce)`.
+- **The reveal contract**: an element that is on screen must be visible. The
+  `IntersectionObserver` uses `threshold: 0` and `rootMargin: "0px"` so the
+  trigger boundary is exactly the viewport. A ratio threshold silently
+  strands any `.reveal` taller than the viewport.
+- **`transform` is owned by one rule**: `.reveal` and `.tilt` both write
+  `transform`, so they must be composed in a single declaration. Never split
+  them across two selectors.
 
 ---
 
-## 4. Standard Commands
+## 4. Testing & Code Quality
 
+- **Accessibility gate**: `bun run --cwd apps/website scripts/audit-a11y.ts`
+  — axe-core on every page (zero critical/serious) plus a computed-contrast
+  check of every token pair.
+- **Visual gate**: `bun run --cwd apps/website scripts/audit-visual.ts` —
+  375 / 768 / 1280 viewports on every page: horizontal overflow, console
+  errors, the reveal runtime, and the nav CTA.
+- **No network in tests**: mock at the `fetch` boundary.
+- **Type strictness**: no `any` and no `as unknown as T`. Fix the interface.
+- **No `console.log`** in committed code.
+
+### Assets are generated, never hand-edited
 ```bash
-bun install      # Install dependencies
-bun dev          # Local dev server
-bun build        # Production build (@astrojs/cloudflare)
-bun test         # Run Vitest suite
-bun lint --fix   # Run linter with autofix
-bun typecheck    # Run tsc --noEmit
+bun run --cwd apps/website brand   # favicon, OG card, twitter card, banner
+bun run --cwd apps/website build   # astro build + llms.txt / llms-full.txt
+```
+Brand PNGs are rasterised from SVG with resvg using the fonts already vendored
+in `showreel-hf/assets/fonts`, so the output is deterministic and needs no
+browser download. `llms.txt` and `llms-full.txt` are generated from the built
+HTML, so the agent-readable layer cannot drift from the site.
+
+---
+
+## 5. Standard Commands
+
+```bash
+# From the repository root
+bun run site:dev            # astro dev
+bun run site:build          # astro build + llms.txt / llms-full.txt
+bun run site:preview        # preview the built site
+
+# From apps/website
+bun run dev                 # astro dev
+bun run build               # astro build && build-llms-txt.ts
+bun run brand               # regenerate brand assets
+bun run llms                # regenerate the agent-readable text layer
+
+# Quality gates
+bun run --cwd apps/website scripts/audit-a11y.ts
+bun run --cwd apps/website scripts/audit-visual.ts
+bun test                    # the whole repository suite
+bunx tsc --noEmit           # type check
 ```