diff --git a/docs/todos/2026-06-19-issue-321-website-technical-showcase/plan.md b/docs/todos/2026-06-19-issue-321-website-technical-showcase/plan.md new file mode 100644 index 000000000..802835138 --- /dev/null +++ b/docs/todos/2026-06-19-issue-321-website-technical-showcase/plan.md @@ -0,0 +1,358 @@ +# Website Technical Showcase Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Rebuild the existing `website/` landing page into a source-backed technical showcase for agentmemory issue #321. + +**Architecture:** Keep the current Next.js App Router site and Vercel root. Add a small source-derived metadata expansion, a typed local showcase data module, and focused React/CSS module sections that render deterministic seeded demos without live daemon calls or new dependencies. + +**Tech Stack:** Next.js 16 App Router, React 19, TypeScript 6, CSS Modules, pnpm 11, Vitest. + +--- + +## Source Of Truth + +Spec path: `docs/todos/2026-06-19-issue-321-website-technical-showcase/spec.md` +Task record: `docs/todos/2026-06-19-issue-321-website-technical-showcase/todo.md` +No separate durable product spec exists; the issue brief, arena synthesis, and task-local spec are the source of truth. + +GitHub PR prep is mandatory after implementation. The delegated issue workflow authorizes routine issue reads, branch push, PR creation, clean green merge, and thread archival after green verification. It does not authorize public deployment, dependency changes, framework/deploy-target changes, or skipped verification. + +## File Structure + +- Modify `test/tool-count-consistency.test.ts`: add regression checks that website count-bearing surfaces do not hard-code current or stale MCP/REST counts. +- Modify `website/scripts/gen-meta.mjs`: derive connect adapter and skill counts from source directories. +- Modify `website/lib/generated-meta.json`: regenerated by `corepack pnpm --dir website run gen-meta`. +- Modify `website/lib/meta.ts`: expose `connectAdapters` and `skills`. +- Modify or delete `website/lib/github.ts` and `website/components/GitHubStarButton.tsx`: remove render-time GitHub API/token dependencies from the landing page, or prove they are no longer imported by the rendered route. +- Modify `website/next.config.ts`: remove remote image allowlist if no rendered website assets need it after the adapter grid is text-first. +- Create `website/lib/showcase.ts`: typed fixture data for primitives, pipeline stages, seeded retrieval traces, command-center panels, and text-only adapter groups. +- Replace or heavily modify `website/components/Hero.tsx` and `website/components/MemoryGraph.tsx`: deterministic architecture hero. +- Create `website/components/Architecture.tsx` and `website/components/Architecture.module.css`: iii worker/function/trigger diagram. +- Create `website/components/MemoryPipeline.tsx` and `website/components/MemoryPipeline.module.css`: tier walkthrough. +- Create `website/components/SearchLab.tsx` and `website/components/SearchLab.module.css`: seeded hybrid retrieval interaction. +- Modify `website/components/CommandCenter.tsx` and `website/components/CommandCenter.module.css`: source-backed proof section using existing local screenshots/GIFs. +- Modify `website/components/Compare.tsx` and `website/components/Compare.module.css`: use generated counts and text-only comparison. +- Modify `website/components/Agents.tsx` and `website/components/Agents.module.css`: text-first adapter grid without adding new remote logos. +- Modify `website/components/Stats.tsx` and `website/components/Stats.module.css`: source-derived stats and technical labels. +- Modify `website/components/Install.tsx`, `website/components/Footer.tsx`, `website/components/Nav.tsx`, and related CSS only as needed to align copy/links with the issue scope and origin target. +- Modify `website/app/page.tsx`: compose the new section order. +- Modify `website/app/layout.tsx`: update metadata copy to technical-showcase language. +- Modify `website/app/globals.css`: shared typography, reduced-motion, focus, and button refinements. +- Modify `website/README.md`: update structure notes for the rebuilt site. + +## Task 1: Add A Failing Count-Consistency Test + +**Files:** +- Modify: `test/tool-count-consistency.test.ts` + +- [ ] **Step 1: Add the failing regression test** + +Add source-count helpers near `readText()`: + +```ts +function countRestApiEndpoints(): number { + return Array.from(readText("src/triggers/api.ts").matchAll(/api_path:\s*["`]/g)).length; +} + +function countConnectAdapters(): number { + const src = readText("src/cli/connect/index.ts"); + const match = src.match(/export const ADAPTERS:[\s\S]*?=\s*\[([\s\S]*?)\];/); + if (!match) throw new Error("ADAPTERS export not found"); + return match[1]!.split(",").map((entry) => entry.trim()).filter(Boolean).length; +} + +function countPluginSkills(): number { + return readdirSync(join(ROOT, "plugin", "skills"), { withFileTypes: true }) + .filter((entry) => entry.isDirectory() && entry.name !== "_shared").length; +} +``` + +Add this test inside `describe("Tool count consistency", () => { ... })` after the existing `metadata surfaces do not advertise stale tool counts` test: + +```ts + it("website count-bearing sections derive project facts instead of hard-coding them", () => { + const compare = readText("website/components/Compare.tsx"); + const commandCenter = readText("website/components/CommandCenter.tsx"); + const generatedMeta = JSON.parse(readText("website/lib/generated-meta.json")); + + expect(compare).not.toContain('["REST ENDPOINTS", "133"'); + expect(compare).not.toContain('["MCP TOOLS", "60"'); + expect(commandCenter).not.toContain("121 HTTP ENDPOINTS"); + expect(generatedMeta.mcpTools).toBe(EXPECTED_TOOL_COUNT); + expect(generatedMeta.restEndpoints).toBe(countRestApiEndpoints()); + }); +``` + +- [ ] **Step 2: Run the targeted test and verify RED** + +Run: `corepack pnpm exec vitest run test/tool-count-consistency.test.ts -t "website count-bearing sections derive project facts"` + +Expected: FAIL because `Compare.tsx` currently hard-codes `133` REST endpoints and `60` MCP tools, `CommandCenter.tsx` hard-codes `121 HTTP ENDPOINTS`, and `generated-meta.json` currently has `56` MCP tools. + +## Task 2: Extend Website Generated Metadata + +**Files:** +- Modify: `website/scripts/gen-meta.mjs` +- Modify: `website/lib/meta.ts` +- Modify: `website/lib/generated-meta.json` +- Modify: `test/tool-count-consistency.test.ts` + +- [ ] **Step 1: Add adapter and skill assertions to the failing test** + +Extend the new test from Task 1 with exact source-count equality: + +```ts + expect(generatedMeta.connectAdapters).toBe(countConnectAdapters()); + expect(generatedMeta.skills).toBe(countPluginSkills()); +``` + +- [ ] **Step 2: Run the targeted test and verify RED** + +Run: `corepack pnpm exec vitest run test/tool-count-consistency.test.ts -t "website count-bearing sections derive project facts"` + +Expected: FAIL because `generated-meta.json` does not yet expose `connectAdapters` or `skills`. + +- [ ] **Step 3: Update `gen-meta.mjs`** + +Add helpers that count `ADAPTERS` entries in `src/cli/connect/index.ts` and skill directories under `plugin/skills/`, excluding `_shared`. Add `connectAdapters` and `skills` to the generated JSON object and log line. + +- [ ] **Step 4: Remove silent fallback counts** + +Replace fallback expressions such as `mcpTools || 45`, `hooks || 12`, `restEndpoints || 107`, and `testsPassing || 794` with fail-fast validation. If any required source count is zero or missing, throw an error that names the missing source file/count. Generated website facts must not silently fall back to stale literals. + +- [ ] **Step 5: Update `meta.ts`** + +Add `connectAdapters: number` and `skills: number` to `ProjectMeta`, then return those fields from `getProjectMeta()`. + +- [ ] **Step 6: Regenerate metadata** + +Run: `corepack pnpm --dir website run gen-meta` + +Expected: `website/lib/generated-meta.json` contains current version, 61 MCP tools, 12 hooks, the current source-derived REST endpoint count, 20 connect adapters, and 15 skills. + +- [ ] **Step 7: Run the targeted test and verify GREEN** + +Run: `corepack pnpm exec vitest run test/tool-count-consistency.test.ts -t "website count-bearing sections derive project facts"` + +Expected: PASS. + +## Task 3: Create Typed Showcase Data + +**Files:** +- Create: `website/lib/showcase.ts` + +- [ ] **Step 1: Add `showcase.ts` with local deterministic data** + +Create typed exports for: +- `primitiveFlow`: worker/function/trigger cards with concrete agentmemory examples. +- `memoryStages`: raw observation through facets/lessons/insights stages. +- `retrievalQueries`: seeded queries with BM25, vector, graph, fusion, and rerank rows. +- `commandPanels`: viewer, iii-console, state, traces panels using existing local assets. +- `adapterGroups`: text-only adapter groups for native plugins and MCP/REST-compatible clients. + +The content must use ASCII punctuation only, no emojis, and no em dashes. + +- [ ] **Step 2: Use source-backed counts only through component props** + +Do not place current MCP, REST, hook, adapter, skill, or test counts in `showcase.ts`. Components should receive those values from `getProjectMeta()`. + +## Task 4: Rebuild The First Viewport And Stats + +**Files:** +- Modify: `website/components/Hero.tsx` +- Modify: `website/components/Hero.module.css` +- Modify: `website/components/MemoryGraph.tsx` +- Modify: `website/components/MemoryGraph.module.css` +- Modify: `website/components/Stats.tsx` +- Modify: `website/components/Stats.module.css` + +- [ ] **Step 1: Replace pitch-first hero copy** + +Use technical copy that states agentmemory is a local iii-engine memory runtime for coding agents. Show source-derived `version`, `mcpTools`, `restEndpoints`, and `connectAdapters` in compact proof rows. + +- [ ] **Step 2: Make `MemoryGraph` deterministic** + +Replace random node seeding with a fixed pipeline scene: hook event, iii trigger, memory function, state write, retrieval fan-out, rerank, and audit trail. Respect `prefers-reduced-motion` and expose pause/resume. + +- [ ] **Step 3: Add a non-visual hero equivalent** + +Keep the canvas decorative if needed, but render an accessible ordered text equivalent of the same pipeline sequence in the hero DOM. The text equivalent must be visible or screen-reader reachable, must not depend on animation, and must be included in rendered QA. + +- [ ] **Step 4: Update `Stats`** + +Show generated source facts: MCP tools, REST endpoints, hook types, connect adapters, skills, and tests. Keep benchmark percentages only where they are already documented in README and label them clearly. + +## Task 5: Add Architecture, Pipeline, And Search Sections + +**Files:** +- Create: `website/components/Architecture.tsx` +- Create: `website/components/Architecture.module.css` +- Create: `website/components/MemoryPipeline.tsx` +- Create: `website/components/MemoryPipeline.module.css` +- Create: `website/components/SearchLab.tsx` +- Create: `website/components/SearchLab.module.css` +- Modify: `website/app/page.tsx` + +- [ ] **Step 1: Add `Architecture`** + +Render workers, functions, and triggers from `primitiveFlow`. Include concrete examples such as `mem::remember`, `mem::smart-search`, and HTTP/MCP triggers. + +- [ ] **Step 2: Add `MemoryPipeline`** + +Render the seeded observation through higher-order memory stages. Make each stage readable without animation and responsive in a single column on mobile. + +- [ ] **Step 3: Add `SearchLab`** + +Implement a client component with query buttons. Selecting a query updates BM25/vector/graph/rerank evidence rows from `retrievalQueries`. The initial state must be meaningful, keyboard-operable, and clear that this is a seeded local replay. + +- [ ] **Step 4: Wire the sections into `page.tsx`** + +Order: `Hero`, `Stats`, `Architecture`, `MemoryPipeline`, `SearchLab`, `CommandCenter`, `Compare`, `Agents`, `Install`. + +## Task 6: Refactor Proof, Compare, Adapter, And Quickstart Sections + +**Files:** +- Modify: `website/components/CommandCenter.tsx` +- Modify: `website/components/CommandCenter.module.css` +- Modify: `website/components/Compare.tsx` +- Modify: `website/components/Compare.module.css` +- Modify: `website/components/Agents.tsx` +- Modify: `website/components/Agents.module.css` +- Modify: `website/components/Install.tsx` +- Modify: `website/components/Install.module.css` +- Modify: `website/components/Nav.tsx` +- Modify: `website/components/MobileNavToggle.tsx` +- Modify: `website/components/Footer.tsx` + +- [ ] **Step 1: Refactor `CommandCenter`** + +Use `commandPanels` and generated metadata. Remove hard-coded stale endpoint text. Keep existing local images only. + +- [ ] **Step 2: Refactor `Compare`** + +Accept `mcpTools`, `restEndpoints`, `hooks`, `connectAdapters`, and `skills` props. Render a text-only feature-axis comparison and avoid competitor logos. + +- [ ] **Step 3: Refactor `Agents`** + +Replace remote logo grids with a text-first adapter matrix sourced from `adapterGroups`. Use generated adapter and skill counts in headings/copy. + +- [ ] **Step 4: Update links and quickstart** + +Keep `/docs` links and quickstart commands aligned with README. Use `https://github.com/wbugitlab1/agentmemory` for repository links in touched website components. + +- [ ] **Step 5: Remove render-time GitHub stats and remote image dependencies** + +Remove `fetchRepoStats` and `GitHubStarButton` from the rendered landing route. Delete or leave unused modules only if `rg -n "fetchRepoStats|GitHubStarButton|GITHUB_TOKEN|api.github.com|remotePatterns|raw.githubusercontent.com|svgl.app|github.com/.+\\.png" website` proves they are no longer imported by `website/app/page.tsx` or rendered route components. Prefer deleting dead website modules when they are fully replaced and task-owned. + +## Task 7: Polish Responsive, Accessibility, And Metadata + +**Files:** +- Modify: `website/app/globals.css` +- Modify: `website/app/layout.tsx` +- Modify: `website/app/opengraph-image.tsx` +- Modify: `website/app/twitter-image.tsx` +- Modify: changed component CSS modules as needed +- Modify: `website/README.md` + +- [ ] **Step 1: Update global styling** + +Keep committed brand colors but improve readability: body copy mixed case, line length 65-75ch, visible focus states, no repeated eyebrow dependency, and no negative letter spacing beyond the active design constraints. + +- [ ] **Step 2: Update metadata and social images** + +Replace sales copy with technical-showcase language. Remove stale hard-coded counts from social images or use stable non-count wording. + +- [ ] **Step 3: Update website README** + +Reflect the new section structure and note that generated metadata drives project facts. + +- [ ] **Step 4: Search for banned/stale text** + +Run: `rg -n "—|∞|121 HTTP ENDPOINTS|REST ENDPOINTS\", \"133|MCP TOOLS\", \"60|56 tools|129 endpoints|rohitg00/agentmemory|GITHUB_TOKEN|api.github.com|raw.githubusercontent.com|svgl.app|remotePatterns" website` + +Expected: no issue-scope stale count references, render-time GitHub API/token reads, or remote image dependencies in the rendered website route. If unused legacy website files still match, prove they are unimported or remove them. + +## Task 8: Verify And Prepare For GitHub PR Flow + +**Files:** +- Modify task record final notes in `docs/todos/2026-06-19-issue-321-website-technical-showcase/todo.md` + +- [ ] **Step 1: Run dependency setup if still needed** + +Run: `test -d node_modules || corepack pnpm install --frozen-lockfile --ignore-scripts` + +Expected: dependencies materialized without manifest or lockfile changes. + +- [ ] **Step 2: Run targeted tests** + +Run: `corepack pnpm exec vitest run test/tool-count-consistency.test.ts test/consistency.test.ts` + +Expected: PASS. + +- [ ] **Step 3: Run full repo tests required before PR** + +Run: `corepack pnpm test` + +Expected: PASS. This is required by `AGENTS.md` before PR. + +- [ ] **Step 4: Run local CI parity checks where feasible** + +Run: +- `corepack pnpm run build` +- `corepack pnpm run skills:check` +- `corepack pnpm run lint` + +Expected: PASS. If a command is too expensive or blocked by an environment issue, record the exact blocker and rely on remote PR CI only after a current-turn human checkpoint accepts that limitation. + +- [ ] **Step 5: Run website build** + +Run: `corepack pnpm --dir website run build` + +Expected: PASS with no framework error overlay in generated output. + +- [ ] **Step 6: Run rendered QA** + +Start: `corepack pnpm --dir website run dev` + +Verify with Browser plugin or Playwright at `1440x900`, `1024x768`, and `390x844`. Save screenshots outside the repo, for example under `/tmp/agentmemory-issue-321-qa/`. + +Required assertions: +- app loads and first meaningful screen renders, +- no Next.js error overlay, +- console has no relevant errors/warnings, +- screenshots show no text overlap or horizontal overflow, +- `document.documentElement.scrollWidth <= document.documentElement.clientWidth` at each viewport, +- the hero pipeline text equivalent is present in the DOM and matches the visual sequence, +- hero pause/resume works, +- SearchLab query selection changes evidence rows, +- CommandCenter tabs work, +- quickstart copy button can be keyboard-activated and shows copied state, +- mobile nav opens, closes, supports Escape where implemented, and does not trap focus incorrectly, +- keyboard focus reaches interactive controls, +- reduced-motion emulation renders usable nonblank content with continuous animation disabled or simplified, +- no render-time network requests go to GitHub API, raw GitHub image URLs, `svgl.app`, or other removed remote image hosts. + +- [ ] **Step 7: Run formatting and diff checks** + +Run: `git diff --check` + +Expected: PASS. + +- [ ] **Step 8: Run required security gates** + +Run Semgrep for non-trivial code/config changes: +`semgrep scan --config p/default --error --metrics=off .` + +Before commit after staging: +`gitleaks protect --staged --redact` + +OSV is not required unless dependency, lockfile, container, vendored, or third-party package surfaces changed. + +- [ ] **Step 9: Check merge/deploy boundary** + +Before merging a PR, verify whether merging `website/**` to `origin/main` can trigger a public deployment such as Vercel. If this cannot be ruled out from repo/GitHub evidence, stop for a human checkpoint before merging. Branch push and PR creation remain authorized by the delegated workflow. + +- [ ] **Step 10: Update task record** + +Record verification evidence, caveats, residual risks, and Feature / Verification Matrix results in `todo.md`. diff --git a/docs/todos/2026-06-19-issue-321-website-technical-showcase/spec.md b/docs/todos/2026-06-19-issue-321-website-technical-showcase/spec.md new file mode 100644 index 000000000..e63494e5c --- /dev/null +++ b/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. diff --git a/docs/todos/2026-06-19-issue-321-website-technical-showcase/todo.md b/docs/todos/2026-06-19-issue-321-website-technical-showcase/todo.md new file mode 100644 index 000000000..067382293 --- /dev/null +++ b/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. diff --git a/test/consistency.test.ts b/test/consistency.test.ts index 932c48942..bc7069b33 100644 --- a/test/consistency.test.ts +++ b/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"); }); diff --git a/test/tool-count-consistency.test.ts b/test/tool-count-consistency.test.ts index ac7bf4d40..2bef95edc 100644 --- a/test/tool-count-consistency.test.ts +++ b/test/tool-count-consistency.test.ts @@ -36,6 +36,23 @@ function readText(relativePath: string): string { return readFileSync(join(ROOT, relativePath), "utf-8"); } +function countRestApiEndpoints(): number { + return Array.from(readText("src/triggers/api.ts").matchAll(/api_path:\s*["`]/g)).length; +} + +function countConnectAdapters(): number { + const src = readText("src/cli/connect/index.ts"); + const match = src.match(/export const ADAPTERS:[\s\S]*?=\s*\[([\s\S]*?)\];/); + if (!match) throw new Error("ADAPTERS export not found"); + return match[1]!.split(",").map((entry) => entry.trim()).filter(Boolean).length; +} + +function countPluginSkills(): number { + return readdirSync(join(ROOT, "plugin", "skills"), { + withFileTypes: true, + }).filter((entry) => entry.isDirectory() && entry.name !== "_shared").length; +} + describe("Tool count consistency", () => { it("registry exposes the expected number of tools", () => { expect(getAllTools().length).toBe(EXPECTED_TOOL_COUNT); @@ -101,6 +118,20 @@ describe("Tool count consistency", () => { } }); + it("website count-bearing sections derive project facts instead of hard-coding them", () => { + const compare = readText("website/components/Compare.tsx"); + const commandCenter = readText("website/components/CommandCenter.tsx"); + const generatedMeta = JSON.parse(readText("website/lib/generated-meta.json")); + + expect(compare).not.toContain('["REST ENDPOINTS", "133"'); + expect(compare).not.toContain('["MCP TOOLS", "60"'); + expect(commandCenter).not.toContain("121 HTTP ENDPOINTS"); + expect(generatedMeta.mcpTools).toBe(EXPECTED_TOOL_COUNT); + expect(generatedMeta.restEndpoints).toBe(countRestApiEndpoints()); + expect(generatedMeta.connectAdapters).toBe(countConnectAdapters()); + expect(generatedMeta.skills).toBe(countPluginSkills()); + }); + it("integration README badges advertise the current tool count", () => { for (const path of INTEGRATION_TOOL_COUNT_SURFACES) { const integrationReadme = readText(path); diff --git a/website/README.md b/website/README.md index b38cacaab..de9dce726 100644 --- a/website/README.md +++ b/website/README.md @@ -1,7 +1,7 @@ # agentmemory website -Next.js 16 App Router landing page for agentmemory. Lamborghini-inspired -black + gold design system. Deploys to Vercel with zero config. +Next.js 16 App Router technical showcase for agentmemory. It keeps the +existing black + gold design system and deploys to Vercel with zero config. ## Stack @@ -33,28 +33,31 @@ No env vars required. Node.js 22.13.0 or newer. ``` website/ app/ - layout.tsx — + fonts + metadata + viewport - page.tsx — composes the landing sections in order - globals.css — design tokens, buttons, section-head utilities + layout.tsx - + fonts + metadata + viewport + page.tsx - composes the technical showcase sections + globals.css - design tokens, buttons, section utilities components/ - Nav.tsx — hexagonal bull mark + menu - Hero.tsx — title + lede + CTAs - MemoryGraph.tsx — client canvas animation + hexagonal pause + scroll rail - Stats.tsx — counter-up on intersect - Primitives.tsx — three cards with 3D mouse tilt - LiveTerminal.tsx — typewriter replay of memory.recall + consolidate - Compare.tsx — agentmemory vs Mem0/Letta/Cognee table - Agents.tsx — supported-agents grid - Install.tsx — click-to-copy npm + console commands - Footer.tsx — source / changelog / license links - ScrollProgress.tsx — thin gold progress bar at the top of the viewport + Nav.tsx - local navigation and source links + Hero.tsx - architecture-in-motion first viewport + MemoryGraph.tsx - deterministic canvas pipeline with pause control + Stats.tsx - source-derived project facts + Architecture.tsx - iii worker/function/trigger composition + MemoryPipeline.tsx - observation-to-memory tier walkthrough + SearchLab.tsx - seeded hybrid retrieval replay + CommandCenter.tsx - viewer and iii-console proof panels + Compare.tsx - text-only architecture comparison + Agents.tsx - text-first adapter matrix + Install.tsx - click-to-copy quickstart commands + Footer.tsx - source / changelog / license links + ScrollProgress.tsx - thin progress bar at the top of the viewport next.config.ts tsconfig.json package.json ``` Each interactive component is a `"use client"` island. Everything else -renders on the server. +renders on the server. Project facts come from `scripts/gen-meta.mjs`, which +reads the repository source at build time and writes `lib/generated-meta.json`. ## Design source diff --git a/website/app/layout.tsx b/website/app/layout.tsx index 95cb92ffb..62aa73c9f 100644 --- a/website/app/layout.tsx +++ b/website/app/layout.tsx @@ -18,9 +18,9 @@ const jetbrains = JetBrains_Mono({ export const metadata: Metadata = { metadataBase: new URL("https://agentmemory.dev"), - title: "AGENTMEMORY — PERSISTENT MEMORY FOR AI CODING AGENTS", + title: "agentmemory - Technical Memory Runtime For Coding Agents", description: - "The memory layer your coding agent should have had from day one. 95.2% retrieval R@5. 92% fewer tokens. 0 external databases. Works with every agent.", + "A local iii-engine memory runtime for coding agents: hooks, MCP tools, REST endpoints, hybrid retrieval, graph memory, and auditable consolidation.", icons: { icon: [{ url: "/icon.svg", type: "image/svg+xml" }], apple: "/icon.svg", @@ -28,7 +28,7 @@ export const metadata: Metadata = { openGraph: { title: "agentmemory", description: - "Persistent memory for AI coding agents. Runs locally. Zero external databases.", + "A technical showcase of the local memory runtime behind agentmemory.", type: "website", url: "/", }, @@ -36,7 +36,7 @@ export const metadata: Metadata = { card: "summary_large_image", title: "agentmemory", description: - "Persistent memory for AI coding agents. Runs locally. Zero external databases.", + "Hooks, MCP, REST, graph memory, and hybrid retrieval for coding agents.", }, }; diff --git a/website/app/opengraph-image.tsx b/website/app/opengraph-image.tsx index bff489cb2..a76da449f 100644 --- a/website/app/opengraph-image.tsx +++ b/website/app/opengraph-image.tsx @@ -1,6 +1,6 @@ import { ImageResponse } from "next/og"; -export const alt = "agentmemory — persistent memory for AI coding agents"; +export const alt = "agentmemory - technical memory runtime for coding agents"; export const size = { width: 1200, height: 630 }; export const contentType = "image/png"; @@ -56,8 +56,8 @@ export default function Image() { textTransform: "uppercase", }} > - AGENT - MEMORY + MEMORY + RUNTIME
- Persistent memory for AI coding agents. Runs locally. Zero external - databases. + Hooks, MCP, REST, graph memory, hybrid retrieval, and audited + consolidation inside one local iii-engine runtime.
@@ -88,16 +88,16 @@ export default function Image() { }} >
- 95.2% - RETRIEVAL R@5 + iii + WORKER
- 92% - FEWER TOKENS + MCP + TOOLS
- 0 - EXTERNAL DBs + GRAPH + RETRIEVAL
diff --git a/website/app/page.tsx b/website/app/page.tsx index afb4a4075..444274bc0 100644 --- a/website/app/page.tsx +++ b/website/app/page.tsx @@ -2,12 +2,11 @@ import { ScrollProgress } from "@/components/ScrollProgress"; import { Nav } from "@/components/Nav"; import { Hero } from "@/components/Hero"; import { Stats } from "@/components/Stats"; -import { Primitives } from "@/components/Primitives"; -import { Features } from "@/components/Features"; +import { Architecture } from "@/components/Architecture"; +import { MemoryPipeline } from "@/components/MemoryPipeline"; +import { SearchLab } from "@/components/SearchLab"; import { CommandCenter } from "@/components/CommandCenter"; -import { LiveTerminal } from "@/components/LiveTerminal"; import { Compare } from "@/components/Compare"; -import { Testimonials } from "@/components/Testimonials"; import { Agents } from "@/components/Agents"; import { Install } from "@/components/Install"; import { Footer } from "@/components/Footer"; @@ -20,23 +19,27 @@ export default function Page() {