Rebuild agent-memory.dev as a technical showcase

docs/todos/2026-06-19-issue-321-website-technical-showcase/spec.md

@@ -0,0 +1,51 @@
+# Issue 321 Website Technical Showcase Spec
+
+## Brief
+
+Rebuild the existing `website/` landing page so a technical developer can understand how agentmemory works from the first screen. The page should show the engineering: iii workers/functions/triggers, capture hooks, memory tier consolidation, hybrid BM25/vector/graph retrieval, reranking, viewer/iii-console proof, adapter coverage, and quickstart flow.
+
+The approved visual source is the current repo: `website/README.md`, `DESIGN.md`, existing CSS modules, local screenshots/GIFs under `website/public/`, and the issue #321 brief. The implementation must evolve the existing black/gold technical identity into a deeper systems showcase. It should reduce generic SaaS marketing cadence and avoid repeated tiny uppercase section-eyebrows as the main page grammar.
+
+Interactivity level: full local interactivity for controls that appear on the page, using deterministic seeded data. The site must not require a running agentmemory daemon, auth, cookies, public deployment, or external services to render its demos.
+
+## Design Direction
+
+The first viewport should be an architecture-in-motion hero: observation capture enters the memory runtime, retrieval fans out across lexical, semantic, and graph streams, and consolidation emits auditable higher-order memory. The goal is not a decorative graph. It should be a legible, deterministic technical scene with copy that explains the runtime in concrete terms.
+
+The body should move from system primitives to proof:
+
+1. iii composition: workers, functions, and triggers as the runtime contract.
+2. Memory pipeline: raw observation, compressed summary, memory, semantic/procedural outputs, crystals, insights, lessons, and facets where source evidence supports them.
+3. Hybrid retrieval lab: seeded query examples showing BM25, vector, graph, fusion, and rerank evidence.
+4. Viewer and iii-console: local screenshots/GIFs that show observation stream, state, traces, and graph surfaces.
+5. Adapter grid: text-first inventory of supported connect adapters, driven by generated metadata where possible.
+6. Comparison and quickstart: feature-axis comparison without competitor logos, and commands that match README guidance.
+
+## Data And Truth Sources
+
+- Version: `package.json`.
+- MCP tools: `src/mcp/tools-registry.ts`.
+- REST endpoints: `src/triggers/api.ts`.
+- Hook types: `src/types.ts`.
+- Connect adapters: `src/cli/connect/index.ts`.
+- Skills: `plugin/skills/`.
+- Tests: `test/**/*.test.ts`.
+- Source-generated website metadata: `website/scripts/gen-meta.mjs` and `website/lib/generated-meta.json`.
+
+Hard-coded counts are acceptable only when they are not project facts, such as fixed demo fixture row counts. Project facts shown to users must come from generated metadata or be avoided.
+
+## Accessibility And Performance
+
+- The page must be usable at desktop and mobile widths without text overlap or horizontal overflow.
+- Interactive tabs, query choices, copy buttons, and nav controls must be keyboard reachable.
+- Canvas/animation content must have non-visual text equivalents.
+- `prefers-reduced-motion` must pause or simplify continuous animation and typewriter effects.
+- Local media should not be made heavier. Avoid adding new raster assets unless generated or repo-owned and necessary.
+- No new third-party logos, proprietary fonts, competitor logos, or stock images.
+
+## Out Of Scope
+
+- Public deployment, demo URLs, GIF/video PR artifacts.
+- Framework, hosting, dependency, package-manager, auth, persistence, API, or runtime changes.
+- Moving the docs site or changing `/docs` rewrites.
+- Editing the Vue/Vite viewer implementation except as a reference source.

docs/todos/2026-06-19-issue-321-website-technical-showcase/todo.md

@@ -0,0 +1,171 @@
+# Issue 321 - Website Technical Showcase
+
+Scope: `website/` in `/Users/A1538552/.codex/worktrees/fda1/agentmemory`
+Branch: `issue/321-website-technical-showcase`
+Issue: https://github.com/wbugitlab1/agentmemory/issues/321
+PR target: `origin/main`
+
+## Sprint Contract
+
+Goal: Rebuild the existing `website/` landing page into a source-backed technical showcase for agentmemory without changing the website framework, deploy target, package manager, dependency graph, auth, persistence, APIs, or runtime boundaries.
+
+Scope:
+- Existing Next.js App Router site under `website/`.
+- Website metadata generation under `website/scripts/gen-meta.mjs` and `website/lib/meta.ts`.
+- Website task-local docs in this directory.
+- Tests that protect source-derived website facts and stale count regressions.
+
+Non-goals:
+- No public deployment or live demo URL.
+- No framework switch, `website-v2/`, Tailwind, animation library, WebContainer, server-side live runtime, or new dependency.
+- No unlicensed third-party assets, fonts, logos, or competitor logos.
+- No changes to core memory APIs, auth, persistence, schema, iii-engine boundaries, remotes, or project policy.
+- No work on issues other than #321.
+
+Acceptance criteria:
+- Issue #321 validity is recorded with GitHub and local repo evidence.
+- The first viewport shows agentmemory engineering in motion, not generic sales copy.
+- The site covers iii primitives, memory tiers, hybrid retrieval, graph/viewer/iii-console proof, adapters, comparison, quickstart, and docs landing paths.
+- Numeric claims used by the website are source-derived or intentionally non-numeric.
+- Demos are deterministic seeded/local proof and do not call a live daemon or public service.
+- Responsive and accessibility checks cover desktop and mobile, keyboard navigation, reduced motion, and layout overflow.
+- Repo-native verification passes or any blocker is recorded with evidence.
+
+Intended verification:
+- `corepack pnpm install --frozen-lockfile --ignore-scripts` if dependencies are absent.
+- Red/green targeted tests for website source-derived counts.
+- `corepack pnpm --dir website run gen-meta`.
+- Targeted Vitest checks covering website count consistency.
+- `corepack pnpm --dir website run build`.
+- Browser/Playwright rendered checks for first meaningful screen, console health, desktop/mobile screenshots, interaction proof, and reduced motion.
+- `git diff --check`.
+- Required security gates before commit: Semgrep for non-trivial website code/config changes and staged Gitleaks before commit. OSV only if dependency, lockfile, container, vendored, or third-party package surfaces change.
+
+Known boundaries:
+- Routine issue reads, branch setup, push, PR creation, clean green merge, and thread archival are authorized by the delegated workflow.
+- Human checkpoint required before public deployment, changing framework/deploy target/dependencies, adding external services or network calls, using unlicensed assets/fonts/logos, accepting skipped/failing verification, or expanding beyond issue #321.
+- The imported upstream issue process mentions forking `rohitg00/agentmemory` and public deployment; those instructions are out of scope for this worktree and conflict with the current delegation.
+
+Stop conditions:
+- A credible implementation path requires a new dependency, framework, deploy target, public deployment, live runtime wiring, auth/security/persistence/API change, or unlicensed asset.
+- Verification fails twice with the same unexplained failure mode.
+- A required security gate produces findings that cannot be fixed within scope.
+- The branch has unrelated dirty changes that would be overwritten or staged.
+
+## Arena Synthesis
+
+Candidates:
+- Candidate 1: `/tmp/arena-issue-321/candidate-1/report.md`
+- Candidate 2: `/tmp/arena-issue-321/candidate-2/report.md`
+- Candidate 3: `/tmp/arena-issue-321/candidate-3/report.md`
+- Cross-judge: `/tmp/arena-issue-321/judge/report.md`
+
+Decision: Valid issue. Use Candidate 3 as the synthesis base.
+
+Confidence: High. All candidates and the cross-judge agreed the issue is valid and not an exact duplicate. All converged on keeping the existing `website/` Next/Vercel target, avoiding dependencies/deploy changes, using deterministic seeded demos, and keeping stats source-derived.
+
+Grafts:
+- From Candidate 2: richer issue-search/source-path inventory, #479 dependency-bump conflict risk, media/performance notes, and security-gate framing.
+- From Candidate 1: explicit separation of `src/viewer/app` as a Vue/Vite reference surface rather than website code to merge, local asset inventory, and source-derived stats guidance.
+
+Rejected:
+- Candidate 2's claim that current `gen-meta.mjs` misses multiline REST endpoints; judge verified the regex matched the then-current source count. After merging latest `origin/main`, generated metadata returns 135 REST endpoints.
+- Any path that follows the imported upstream contest process literally: no public deployment, upstream fork PR, deploy target swap, or new `website-v2/` without explicit approval.
+- New third-party logos, proprietary imagery, external fonts, animation libraries, Tailwind, WebContainers, or live daemon wiring.
+
+## Feature / Verification Matrix
+
+| Change | Verification method | Status | Evidence |
+|---|---|---|---|
+| Record issue validity and arena synthesis | GitHub issue read, local reports, task record | Complete | Issue #321 open; candidate and judge reports under `/tmp/arena-issue-321/` |
+| Source-derived website facts | Red/green Vitest; `gen-meta`; stale-count search | Complete | Targeted test failed red on stale `Compare.tsx` count, then passed after metadata changes; post-merge `gen-meta` generated v0.9.28, 61 MCP tools, 135 REST endpoints, 20 connect adapters, 15 skills, 2626 tests; live-route stale scans clean |
+| Technical showcase page rebuild | Next build; browser desktop/mobile visual QA | Complete | `corepack pnpm --dir website run build` passed; rendered QA covered 1440x900, 1024x768, and 390x844 with no horizontal overflow |
+| Deterministic search/pipeline interactions | Browser interaction proof and reduced-motion check | Complete | Hero text equivalent present; pause/resume works; SearchLab selected MCP surface query and showed reranked output; CommandCenter console tab showed `$ iii console --port 3114`; reduced-motion reload remained usable |
+| Existing framework/deploy/dependency boundaries preserved | Git diff, package manifests, Vercel config review | Complete for PR; merge checkpoint pending | No dependency or lockfile changes; Next/Vercel website root unchanged; branch push and PR are within delegated authorization; merge may trigger public deployment and still requires checkpoint if it cannot be ruled out |
+| Security and secret scan gates | Semgrep and staged Gitleaks before commit | Complete | Semgrep `p/default` completed with 0 findings; staged Gitleaks completed with no leaks found |
+
+## Subagent Ledger
+
+| Workstream | Scope | Edits allowed | Expected output | Result | Residual risk |
+|---|---|---:|---|---|---|
+| Arena candidate 1 | Read-only issue validity/design direction | No | `/tmp/arena-issue-321/candidate-1/report.md` | Complete | None beyond read-only uncertainty |
+| Arena candidate 2 | Read-only issue validity/design direction | No | `/tmp/arena-issue-321/candidate-2/report.md` | Complete | One generator-regex claim rejected |
+| Arena candidate 3 | Read-only issue validity/design direction | No | `/tmp/arena-issue-321/candidate-3/report.md` | Complete | None material |
+| Arena cross-judge | Read-only candidate scoring | No | `/tmp/arena-issue-321/judge/report.md` | Complete | Same GPT-family models only; no different model family available |
+
+## Progress
+
+- [x] Read active repo instructions and required skills.
+- [x] Inspected initial git state.
+- [x] Created `issue/321-website-technical-showcase` from verified `origin/main` commit `8b24a9c25576ec546f7ffac9963db412a9efda6a`.
+- [x] Verified remotes and confirmed `origin` target.
+- [x] Read local website stack/docs/scripts and issue evidence.
+- [x] Ran arena validity/design synthesis.
+- [x] Recorded Sprint Contract and Feature / Verification Matrix.
+- [x] Write implementation plan.
+- [x] Review plan.
+- [x] Implement with TDD where behavior is testable.
+- [x] Run verification.
+- [ ] Prepare commit, push, PR, clean green merge, and archive if all gates pass.
+
+## Pre-Implementation Review Notes
+
+Reviewer findings triaged as valid and fixed in `plan.md`:
+- `fixed`: Metadata verification could pass fallback/stale counts. Plan now requires fail-fast metadata generation and exact equality against source-derived counts.
+- `fixed`: Hero animation accessibility was under-specified. Plan now requires a non-visual text equivalent and rendered QA proof.
+- `fixed`: Quickstart copy and mobile nav behavior were omitted from QA. Plan now includes explicit keyboard/copy/mobile-nav checks.
+- `fixed`: Current rendered route uses GitHub API/token and remote image paths. Plan now owns removing render-time GitHub stats and remote image dependencies or proving any legacy matches are unimported.
+- `fixed`: Stale-owner scan did not align with owned files. Plan now expands ownership to `website/lib/github.ts`, `GitHubStarButton`, and `next.config.ts` where needed.
+- `fixed`: PR-readiness verification omitted full repo test and CI parity. Plan now requires `corepack pnpm test`, build, skills check, lint, website build, and explicit handling if any are blocked.
+- `fixed`: Rendered QA was not reproducible enough. Plan now names viewport sizes, overflow assertions, reduced-motion emulation, interaction assertions, network checks, and screenshot evidence paths.
+- `fixed`: Merge may trigger public deployment. Plan now requires a no-public-deploy merge checkpoint unless public deployment can be ruled out.
+
+Dependency setup evidence: `corepack pnpm install --frozen-lockfile --ignore-scripts` completed successfully and did not change manifests or lockfiles. It reported a local-bin warning because `dist/cli.mjs` is absent before build.
+
+## Implementation Evidence
+
+- Added a website count-consistency guard in `test/tool-count-consistency.test.ts`; it failed red on the stale hard-coded website counts, then passed after implementation.
+- Extended `website/scripts/gen-meta.mjs` and `website/lib/meta.ts` so website-visible project facts include connect adapters and plugin skills and fail fast instead of falling back to stale literals.
+- Rebuilt the landing route around deterministic local sections: architecture, memory pipeline, seeded hybrid retrieval, runtime viewer proof, comparison, adapter matrix, and quickstart.
+- Removed render-time GitHub stats and remote image allowlist from the rendered landing route; legacy GitHub/stat modules still exist but are unimported by the rebuilt route.
+- `corepack pnpm exec vitest run test/tool-count-consistency.test.ts test/consistency.test.ts` passed 22 tests.
+- `corepack pnpm --dir website run build` passed after the rebuild.
+
+## Rendered QA Evidence
+
+- Production local server: `corepack pnpm --dir website exec next start --hostname 127.0.0.1 --port 3000`.
+- In-app browser QA: loaded `http://127.0.0.1:3000/`, title matched technical metadata, console warnings/errors were empty, external runtime resources did not include GitHub API, raw GitHub, or `svgl.app`.
+- Default viewport: hero text equivalent present; pause/resume toggled `Pause animation` to `Resume animation` and back; SearchLab MCP-surface query showed `Return registry, server handler, REST bridge, index registration, tests, and docs surfaces.`; CommandCenter console tab showed `$ iii console --port 3114`.
+- Quickstart copy: browser clipboard permission was blocked in the test runner; UI surfaced `CLIPBOARD BLOCKED` rather than silently failing.
+- Resizable browser QA: 1440x900, 1024x768, and 390x844 all had `scrollWidth <= clientWidth`.
+- Mobile QA at 390x844: desktop nav hidden, mobile menu button visible, menu opened with `PIPELINE` visible, Escape closed it, and focus returned to `Open menu`.
+- Reduced motion: emulated `prefers-reduced-motion: reduce`; page stayed nonblank, no overflow, hero text equivalent remained present, and pause control remained reachable.
+
+## Verification Evidence
+
+- `corepack pnpm exec vitest run test/tool-count-consistency.test.ts test/consistency.test.ts`: passed 2 files, 22 tests.
+- `git diff --check` and `git diff --cached --check`: passed after trimming EOF whitespace in newly added files.
+- `corepack pnpm test`: passed 211 files, 2902 tests after merging latest `origin/main`.
+- `corepack pnpm run build`: passed. Build emitted existing tsdown plugin-timing and ineffective-dynamic-import warnings, with no failure.
+- `corepack pnpm run skills:check`: passed, 15 skills checked.
+- `corepack pnpm run lint`: passed.
+- `corepack pnpm --dir website run build`: passed with routes `/`, `/_not-found`, `/opengraph-image`, and `/twitter-image`.
+- `semgrep scan --config p/default --error --metrics=off .`: passed, 0 findings.
+- `gitleaks protect --staged --redact`: passed, no leaks found.
+- OSV was not run because no dependency files, lockfiles, container images, vendored code, or third-party package surfaces changed.
+
+## Implementation Review
+
+Findings: no blocking or non-blocking findings after staged diff review.
+
+Evidence inspected:
+- Staged file list and changed hunks for website route composition, metadata generation, count-consistency tests, and new showcase sections.
+- Scope scans for stale hard-coded website counts, removed remote image hosts, `rohitg00/agentmemory` links in live-route files, render-time GitHub API/token usage, debug leftovers, type suppressions, and hidden `any` use.
+- Browser QA evidence for responsive layout, mobile menu behavior, hero animation controls, SearchLab, CommandCenter tabs, console health, reduced motion, and runtime external-resource requests.
+
+Adversarial review: no additional subagent was used for this post-code review because the available subagent tool is restricted to explicit delegation requests. A separate local adversarial pass checked parser fragility, render-time network boundaries, generated metadata truth sources, clipboard permission behavior, mobile navigation focus, and public-deploy merge risk.
+
+Residual risks and caveats:
+- The in-app browser denied clipboard writes; the quickstart copy UI surfaced `CLIPBOARD BLOCKED` instead of silently failing.
+- Generated browser QA artifacts remain untracked in the worktree and are intentionally not staged.
+- A PR merge may trigger a public Vercel deployment outside visible repo configuration. If this cannot be ruled out before merge, stop for a human checkpoint before merging.

test/consistency.test.ts

@@ -74,9 +74,11 @@ describe("Consistency checks", () => {
   it("website iii console launch command matches README guidance", () => {
     const readme = readText("README.md");
     const commandCenter = readText("website/components/CommandCenter.tsx");
+    const showcase = readText("website/lib/showcase.ts");
 
     expect(readme).toContain("iii console --port 3114");
-    expect(commandCenter).toContain('launch: "iii console --port 3114"');
+    expect(showcase).toContain('launch: "iii console --port 3114"');
+    expect(commandCenter).toContain("{panel.launch}");
     expect(commandCenter).not.toContain("iii-console --port 3114");
   });