musememory 2.3.0 → 3.0.1

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
 ```

package/.agents/standards/git-workflow.md

@@ -87,6 +87,11 @@ All releases and git tags must follow strict `vX.Y.Z` semantic versioning:
 - Sync `package.json` `"version"` with the `vX.Y.Z` tag in the release commit.
 - Stage on `release/vX.Y.Z` from `dev` → merge to `master` → back-merge to `dev`.
 - CI publishes on `v*` tag push (`git tag -a vX.Y.Z -m "release: vX.Y.Z"`). Never publish manually.
+- **README "What's New" Rule**:
+  - Keep only the current release/feature highlights in `README.md` under `## 🚀 What's New`.
+  - Do NOT accumulate historical version blocks (`### vX.Y.Z`).
+  - Do NOT write version headers (`### vX.Y.Z`) inside `## 🚀 What's New`; format as a clean, plain-English bullet list understandable to non-technical users.
+  - Detailed versioned change history lives strictly in `CHANGELOG.md`.
 
 ---
 

package/.agents/standards/workflows.md

@@ -52,3 +52,16 @@ To balance velocity with rigor, overhead is strictly proportional to task risk:
 - **Archive Work Artifacts**: Move completed plans or temporary scratchpads into `.agents/archive/` using the timestamped format `[title]-[YYYYMMDD-HHMMSS].md`.
 - **DOX Pass**: Update `./.agents/context/current.md` and the nearest owning `AGENTS.md`.
 - **Memory Update**: Persist newly confirmed invariants or architectural decisions into `./.memory`.
+
+---
+
+## 3. Mandatory PR & Post-Merge Pipeline (principal rule, 2026-10-15)
+
+1. **One PR per feature.** Every feature or fix lands on its own branch (`feat/*`, `fix/*`) off `dev`. Never commit directly to `main`, `master`, or `dev`.
+2. **Per-phase subagent worktrees.** Every phase starts by dispatching multiple subagents, each in its own worktree, doing the work there. The orchestrator reconciles terminal results back into the feature branch. Execution model: one branch per ticket (`fix/T-xxx`), full gate per commit (`bun test` + `tsc --noEmit` + `bun run build`).
+3. **After feature work merges to `dev`, run in order, end-to-end:**
+   a. `updatedocs` skill — complete mode (doc↔code drift sync; CHANGELOG/docs alignment).
+   b. `updateagents` skill — all modes (AGENTS.md + `.agents/` context synchronization).
+   c. `git` skill — end-to-end, **stopping before release**. Release cutting is principal-confirmed only; never auto-release.
+4. **Docs upkeep.** Update CHANGELOG.md, CONTRIBUTING.md, and credits (package.json author/contributors, README credits) whenever required: behavioral changes, new dependencies, new contributors, process changes.
+5. Gates unchanged: green per commit, Why/What/Verification commit bodies, zero secret exposure, English only.