forge-server 0.1.0

package/plugin/skills/visual-explainer/prompts/diff-review.md

@@ -0,0 +1,68 @@
+---
+description: Generate a visual HTML diff review — before/after architecture comparison with code review analysis
+---
+Load the visual-explainer skill, then generate a comprehensive visual diff review as a self-contained HTML page.
+
+Follow the visual-explainer skill workflow. Read the reference template, CSS patterns, and mermaid theming references before generating. Use a GitHub-diff-inspired aesthetic with red/green before/after panels, but vary fonts and palette from previous diagrams.
+
+**Scope detection** — determine what to diff based on `$1`:
+- Branch name (e.g. `main`, `develop`): working tree vs that branch
+- Commit hash: that specific commit's diff (`git show <hash>`)
+- `HEAD`: uncommitted changes only (`git diff` and `git diff --staged`)
+- PR number (e.g. `#42`): `gh pr diff 42`
+- Range (e.g. `abc123..def456`): diff between two commits
+- No argument: default to `main`
+
+**Data gathering phase** — run these first to understand the full scope:
+- `git diff --stat <ref>` for file-level overview
+- `git diff --name-status <ref> --` for new/modified/deleted files (separate src from tests)
+- Line counts: compare key files between `<ref>` and working tree (`git show <ref>:file | wc -l` vs `wc -l`)
+- New public API surface: grep added lines for exported symbols, public functions, classes, interfaces (adapt the pattern to the project's language — `export`/`function`/`class`/`interface` for TS/JS, `def`/`class` for Python, `func`/`type` for Go, etc.)
+- Feature inventory: grep for new actions, keybindings, config fields, event types on both sides
+- Read all changed files in full — include surrounding code paths needed to validate behavior
+- Check whether `CHANGELOG.md` has an entry for these changes
+- Check whether `README.md` or `docs/*.md` need updates given any new or changed features
+- Reconstruct decision rationale: if this work was done in the current session, mine the conversation for approaches discussed, alternatives rejected, and trade-offs made. Check for progress docs (`~/.agent/memory/{project}/progress.md`, `~/.pi/agent/memory/{project}/progress.md`) or plan files that may contain reasoning. For committed changes, read commit messages and PR descriptions.
+
+**Verification checkpoint** — before generating HTML, produce a structured fact sheet of every claim you will present in the review:
+- Every quantitative figure: line counts, file counts, function counts, test counts
+- Every function, type, and module name you will reference
+- Every behavior description: what code does, what changed, before vs. after
+- For each, cite the source: the git command output that produced it, or the file:line where you read it
+Verify each claim against the code. If something cannot be verified, mark it as uncertain rather than stating it as fact. This fact sheet is your source of truth during HTML generation — do not deviate from it.
+
+**Diagram structure** — the page should include:
+1. **Executive summary** — not just a dry before/after. Lead with the *intuition*: why do these changes exist? What problem were they solving, what was the core insight? Then the factual scope (X files, Y lines, Z new modules). Aim for "aha moment" clarity — a reader who only sees this section should understand the essence of the change. *Visual treatment: this is the visual anchor — use hero depth (larger type 20-24px, subtle accent-tinted background, more padding than other sections).*
+2. **KPI dashboard** — lines added/removed, files changed, new modules, test counts. Include a **housekeeping** indicator: whether CHANGELOG.md was updated (green/red badge) and whether docs need changes (green/yellow/red).
+3. **Module architecture** — how the file structure changed, with a Mermaid dependency graph of the current state. Wrap in `.mermaid-wrap` with zoom controls (+/−/reset buttons), Ctrl/Cmd+scroll zoom, and click-and-drag panning (grab/grabbing cursors). See css-patterns.md "Mermaid Zoom Controls" for the full pattern.
+4. **Major feature comparisons** — side-by-side before/after panels for each significant area of change (UI, data flow, API surface, config, etc.). Overflow prevention: apply `min-width: 0` on all grid/flex children and `overflow-wrap: break-word` on panels. Never use `display: flex` on `<li>` for marker characters — use absolute positioning instead (see css-patterns.md Overflow Protection).
+5. **Flow diagrams** — Mermaid flowchart, sequence, or state diagrams for any new lifecycle/pipeline/interaction patterns. Same zoom controls as section 3.
+6. **File map** — full tree with color-coded new/modified/deleted indicators. *Visual treatment: compact — consider `<details>` collapsed by default for pages with many sections.*
+7. **Test coverage** — before/after test file counts and what's covered
+8. **Code review** — structured Good/Bad/Ugly analysis of the changes:
+   - **Good**: Solid choices, improvements, clean patterns worth calling out
+   - **Bad**: Concrete issues — bugs, regressions, missing error handling, logic errors
+   - **Ugly**: Subtle problems — tech debt introduced, maintainability concerns, things that work now but will bite later
+   - **Questions**: Anything unclear or that needs the author's clarification
+   - Use styled cards with green/red/amber/blue left-border accents matching the diff color language. Each item should reference specific files and line ranges. If nothing to flag in a category, say "None found" rather than omitting the section.
+9. **Decision log** — for each significant design choice in the diff, a styled card with:
+   - **Decision**: one-line summary of what was decided (e.g., "Promise-based deferred resolution instead of event emitters for cleanup signaling")
+   - **Rationale**: why this approach — constraints, trade-offs, what it enables. Pull from conversation context if available, infer from code structure if not.
+   - **Alternatives considered**: what was rejected and why, if recoverable
+   - **Confidence**: whether this rationale was explicitly discussed (high — sourced from conversation/docs) or inferred from the code (medium — flagged as inference). Low confidence means the rationale couldn't be recovered at all.
+   - Visual treatment by confidence level — use left-border accent colors consistent with the diff color language: **High** (sourced from conversation/docs): green left border. **Medium** (inferred from code): blue left border, labeled "inferred." **Low** (not recoverable): amber left border, "rationale not recoverable — document before committing" warning. Low-confidence cards are cognitive debt hotspots — tell the user to document the reasoning before committing.
+10. **Re-entry context** — a concise "note from present-you to future-you" covering the following. *Visual treatment: compact — consider `<details>` collapsed by default for pages with many sections.*
+   - **Key invariants**: assumptions the changed code relies on that aren't enforced by types or tests (e.g., "cleanup must be called before session switch or artifacts leak")
+   - **Non-obvious coupling**: files or behaviors that are connected in ways that aren't visible from imports alone (e.g., "the feed renderer reads events written by the overlay — changing the event schema requires updating both")
+   - **Gotchas**: things that would surprise someone modifying this code in two weeks. Edge cases, ordering dependencies, implicit contracts.
+   - **Don't forget**: if the changes require follow-up work (migration, config update, docs), list it here.
+
+**Visual hierarchy**: Sections 1-3 should dominate the viewport on load (hero depth, larger type, more padding). Sections 6+ are reference material and should feel lighter (flat or recessed depth, compact layout, collapsible where appropriate).
+
+**Optional illustrations** — if `surf` CLI is available (`which surf`), consider generating a hero banner or conceptual illustration via `surf gemini --generate-image` when it would enhance the page. Embed as base64 data URI. See css-patterns.md "Generated Images" for container styles. Skip if surf isn't available or the diff is purely structural.
+
+Include responsive section navigation. Use diff-style visual language throughout: red for removed/before, green for added/after, yellow for modified, blue for neutral context. Write to `~/.agent/diagrams/` and open in browser.
+
+Ultrathink.
+
+$@

package/plugin/skills/visual-explainer/prompts/fact-check.md

@@ -0,0 +1,63 @@
+---
+description: Verify the factual accuracy of a document against the actual codebase, correct inaccuracies in place
+---
+Load the visual-explainer skill, then verify the factual accuracy of a document that makes claims about a codebase. Read the file, extract every verifiable claim, check each against the actual code and git history, correct inaccuracies in place, and add a verification summary.
+
+For HTML files: read `./references/css-patterns.md` to match the existing page's styling when inserting the verification summary.
+
+**Target file** — determine what to verify from `$1`:
+- Explicit path: verify that specific file (`.html`, `.md`, or any text document)
+- No argument: verify the most recently modified `.html` file in `~/.agent/diagrams/` (`ls -t ~/.agent/diagrams/*.html | head -1`)
+
+Auto-detect the document type and adjust the verification strategy:
+- **HTML review pages** (diff-review, plan-review, project-recap): detect from page content, verify against the git ref or plan file the review was based on
+- **Plan/spec documents** (markdown): verify file references, function/type names, behavior descriptions, and architecture claims against the current codebase
+- **Any other document**: extract and verify whatever factual claims about code it contains
+
+**Phase 1: Extract claims.** Read the file. Extract every verifiable factual claim:
+- **Quantitative**: line counts, file counts, function counts, module counts, test counts, any numeric metrics
+- **Naming**: function names, type names, module names, file paths referenced in the document
+- **Behavioral**: descriptions of what code does, how things work, before/after comparisons
+- **Structural**: architecture claims, dependency relationships, import chains, module boundaries
+- **Temporal**: git history claims, commit attributions, timeline entries
+
+Skip subjective analysis (opinions, design judgments, readability assessments) — these aren't verifiable facts.
+
+**Phase 2: Verify against source.** For each extracted claim, go to the source:
+- Re-read every file referenced in the document — check function signatures, type definitions, behavior descriptions against the actual code
+- For claims about git history: re-run git commands (`git diff --stat`, `git log`, `git diff --name-status`, etc.) and compare output against the document's numbers
+- For diff-reviews: read both the ref version (`git show <ref>:file`) and working tree version to verify before/after claims aren't swapped or fabricated
+- For plan docs: verify that files, functions, and types the plan references actually exist and behave as described
+- For project-recaps: re-run `git log` commands to verify activity narrative and timeline
+
+Classify each claim:
+- **Confirmed**: claim matches the code/output exactly
+- **Corrected**: claim was inaccurate — note what was wrong and what the correct value is
+- **Unverifiable**: claim can't be checked (e.g., references a file that doesn't exist, or a behavior that requires runtime testing)
+
+**Phase 3: Correct in place.** Edit the file directly using surgical text replacements:
+- Fix incorrect numbers, function names, file paths, behavior descriptions
+- Fix before/after swaps (a common error class in review pages)
+- If a section is fundamentally wrong (not just a detail error), rewrite that section's content while preserving the surrounding structure
+- For HTML: preserve layout, CSS, animations, Mermaid diagrams (unless they contain factual errors in node labels or edge descriptions)
+- For markdown: preserve heading structure, formatting, and document organization
+
+**Phase 4: Add verification summary.**
+- **HTML files**: insert a verification section as a banner at the top or final section, matching the page's existing styling. Use a subtle card with muted colors.
+- **Markdown files**: append a `## Verification Summary` section at the end of the document.
+
+Include in the summary:
+- Total claims checked
+- Claims confirmed (with count)
+- Corrections made (with brief list of what was fixed: "Changed `processCleanup` to `runCleanup` to match actual function name in `worker.ts:45`")
+- Unverifiable claims flagged (if any)
+
+**Phase 5: Report.** Tell the user what was checked, what was corrected, and open the file (HTML in browser, markdown path in chat). If nothing needed correction, say so — the verification still has value as confirmation.
+
+This is not a re-review. It does not second-guess analysis, opinions, or design judgments. It does not change the document's structure or organization. It is a fact-checker — it verifies that the data presented matches reality, corrects what doesn't, and leaves everything else alone.
+
+Write corrections to the original file.
+
+Ultrathink.
+
+$@

package/plugin/skills/visual-explainer/prompts/generate-slides.md

@@ -0,0 +1,18 @@
+---
+description: Generate a stunning magazine-quality slide deck as a self-contained HTML page
+---
+Load the visual-explainer skill, then generate a slide deck for: $@
+
+Follow the visual-explainer skill workflow. Read the reference template at `./templates/slide-deck.html` and slide patterns at `./references/slide-patterns.md` before generating. Also read `./references/css-patterns.md` for shared patterns (Mermaid zoom controls, depth tiers, overflow protection) and `./references/libraries.md` for Mermaid theming, Chart.js, and font pairings.
+
+**Slide output is always opt-in.** Only generate slides when this command is invoked or the user explicitly asks for a slide deck.
+
+**Aesthetic:** Pick a distinctive direction from the 4 slide presets in slide-patterns.md (Midnight Editorial, Warm Signal, Terminal Mono, Swiss Clean) or riff on the existing 8 aesthetic directions adapted for slides. Vary from previous decks. Commit to one direction and carry it through every slide.
+
+**Narrative structure:** Slides have a temporal dimension — compose a story arc, not a list of sections. Start with impact (title), build context (overview), deep dive (content, diagrams, data), resolve (summary/next steps). Plan the slide sequence and assign a composition (centered, left-heavy, split, full-bleed) to each slide before writing HTML.
+
+**Visual richness:** Proactively reach for visuals. If `surf` CLI is available (`which surf`), generate images for title slide backgrounds and full-bleed slides via `surf gemini --generate-image`. Add SVG decorative accents, inline sparklines, mini-charts, and small Mermaid diagrams where they make the story more compelling. Visual-first, text-second.
+
+**Compositional variety:** Consecutive slides must vary their spatial approach. Alternate between centered, left-heavy, right-heavy, split, edge-aligned, and full-bleed. Three centered slides in a row means push one off-axis.
+
+Write to `~/.agent/diagrams/` and open the result in the browser.

package/plugin/skills/visual-explainer/prompts/generate-web-diagram.md

@@ -0,0 +1,10 @@
+---
+description: Generate a beautiful standalone HTML diagram and open it in the browser
+---
+Load the visual-explainer skill, then generate an HTML diagram for: $@
+
+Follow the visual-explainer skill workflow. Read the reference template and CSS patterns before generating. Pick a distinctive aesthetic that fits the content — vary fonts, palette, and layout style from previous diagrams.
+
+If `surf` CLI is available (`which surf`), consider generating an AI illustration via `surf gemini --generate-image` when an image would genuinely enhance the page — a hero banner, conceptual illustration, or educational diagram that Mermaid can't express. Match the image style to the page's palette. Embed as base64 data URI. See css-patterns.md "Generated Images" for container styles. Skip images when the topic is purely structural or data-driven.
+
+Write to `~/.agent/diagrams/` and open the result in the browser.

package/plugin/skills/visual-explainer/prompts/plan-review.md

@@ -0,0 +1,86 @@
+---
+description: Generate a visual HTML plan review — current codebase state vs. proposed implementation plan
+---
+Load the visual-explainer skill, then generate a comprehensive visual plan review as a self-contained HTML page, comparing the current codebase against a proposed implementation plan.
+
+Follow the visual-explainer skill workflow. Read the reference template, CSS patterns, and mermaid theming references before generating. Use a blueprint/editorial aesthetic with current-state vs. planned-state panels, but vary fonts and palette from previous diagrams.
+
+**Inputs:**
+- Plan file: `$1` (path to a markdown plan, spec, or RFC document)
+- Codebase: `$2` if provided, otherwise the current working directory
+
+**Data gathering phase** — read and cross-reference these before generating:
+
+1. **Read the plan file in full.** Extract:
+   - The problem statement and motivation
+   - Each proposed change (files to modify, new files, deletions)
+   - Rejected alternatives and their reasoning
+   - Any explicit scope boundaries or non-goals
+
+2. **Read every file the plan references.** For each file mentioned in the plan, read the current version in full. Also read files that import or depend on those files — the plan may not mention all ripple effects.
+
+3. **Map the blast radius.** From the codebase, identify:
+   - What imports/requires the files being changed (grep for import paths)
+   - What tests exist for the affected files (look for corresponding `.test.*` / `.spec.*` files)
+   - Config files, types, or schemas that might need updates
+   - Public API surface that callers depend on
+
+4. **Cross-reference plan vs. code.** For each change the plan proposes, verify:
+   - Does the file/function/type the plan references actually exist in the current code?
+   - Does the plan's description of current behavior match what the code actually does?
+   - Are there implicit assumptions about code structure that don't hold?
+
+**Verification checkpoint** — before generating HTML, produce a structured fact sheet of every claim you will present in the review:
+- Every quantitative figure: file counts, estimated lines, function counts, test counts
+- Every function, type, and module name you will reference from both the plan and the codebase
+- Every behavior description: what the code currently does vs. what the plan proposes
+- For each, cite the source: the plan section or the file:line where you read it
+Verify each claim against the code and the plan. If something cannot be verified, mark it as uncertain rather than stating it as fact. This fact sheet is your source of truth during HTML generation — do not deviate from it.
+
+**Diagram structure** — the page should include:
+
+1. **Plan summary** — lead with the *intuition*: what problem does this plan solve, and what's the core insight behind the approach? Then the scope: how many files touched, estimated scale of changes, new modules or tests planned. A reader who only sees this section should understand the plan's essence. *Visual treatment: this is the visual anchor — use hero depth (larger type 20-24px, subtle accent-tinted background, more padding than other sections).*
+
+2. **Impact dashboard** — files to modify, files to create, files to delete, estimated lines added/removed, new test files planned, dependencies affected. Include a **completeness** indicator: whether the plan covers tests (green/red), docs updates (green/yellow/red), and migration/rollback (green/grey for N/A).
+
+3. **Current architecture** — Mermaid diagram of how the affected subsystem works *today*. Focus only on the parts the plan touches — don't diagram the entire codebase. Show the data flow, dependencies, and call paths that will change. Wrap in `.mermaid-wrap` with zoom controls (+/−/reset buttons), Ctrl/Cmd+scroll zoom, and click-and-drag panning (grab/grabbing cursors). See css-patterns.md "Mermaid Zoom Controls" for the full pattern. *Visual treatment: use matching Mermaid layout direction and node names as section 4 so the visual diff is obvious.*
+
+4. **Planned architecture** — Mermaid diagram of how the subsystem will work *after* the plan is implemented. Use the same node names and layout direction as the current architecture diagram so the differences are visually obvious. Same zoom controls as section 3. *Highlight new nodes with a glow or accent border, removed nodes with strikethrough or reduced opacity, changed edges with a different stroke color.*
+
+5. **Change-by-change breakdown** — for each change in the plan, a side-by-side panel. Overflow prevention: apply `min-width: 0` on all grid/flex children and `overflow-wrap: break-word` on panels. Never use `display: flex` on `<li>` for marker characters — use absolute positioning instead (see css-patterns.md Overflow Protection).
+   - **Left (current):** what the code does now, with relevant snippets or function signatures
+   - **Right (planned):** what the plan proposes, with the plan's own code examples if provided
+   - **Rationale:** below each side-by-side panel, extract _why_ the plan chose this approach. Pull from the plan's reasoning, rejected alternatives section, or inline justifications. If the plan includes a "rejected alternatives" section, map those rejections to the specific changes they apply to. Flag changes where the plan says _what_ to do but not _why_ — these are pre-implementation cognitive debt.
+   - Flag any discrepancies where the plan's description of current behavior doesn't match the actual code
+
+6. **Dependency & ripple analysis** — *visual treatment: compact — consider `<details>` collapsed by default for pages with many sections.* What other code depends on the files being changed. Table or Mermaid graph showing callers, importers, and downstream effects the plan may not explicitly address. Color-code: covered by plan (green), not mentioned but likely affected (amber), definitely missed (red).
+
+7. **Risk assessment** — styled cards for:
+   - **Edge cases** the plan doesn't address
+   - **Assumptions** the plan makes about the codebase that should be verified
+   - **Ordering risks** if changes need to be applied in a specific sequence
+   - **Rollback complexity** if things go wrong
+   - **Cognitive complexity** — areas where the plan introduces non-obvious coupling, action-at-a-distance behavior, implicit ordering requirements, or contracts that exist only in the developer's memory. Distinct from bug risk — these are "you'll forget how this works in a month" risks. Each cognitive complexity flag gets a brief mitigation suggestion (e.g., "add a comment explaining the ordering requirement" or "consider a runtime assertion that validates the invariant"). Note: cognitive complexity flags belong here when they're about specific code patterns; broader concerns about the plan's overall approach (overengineering, lock-in, maintenance burden) belong in section 8's Ugly category.
+   - Each risk gets a severity indicator (low/medium/high)
+
+8. **Plan review** — structured Good/Bad/Ugly analysis of the plan itself:
+   - **Good**: Solid design decisions, things the plan gets right, well-reasoned tradeoffs
+   - **Bad**: Gaps in the plan — missing files, unaddressed edge cases, incorrect assumptions about current code
+   - **Ugly**: Subtle concerns — complexity being introduced, maintenance burden, things that will work initially but cause problems at scale
+   - **Questions**: Ambiguities that need the plan author's clarification before implementation begins
+   - Use styled cards with green/red/amber/blue left-border accents. Each item should reference specific plan sections and code files. If nothing to flag in a category, say "None found" rather than omitting the section.
+9. **Understanding gaps** — a closing dashboard that rolls up decision-rationale gaps from section 5 and cognitive complexity flags from section 7:
+   - Count of changes with clear rationale vs. missing rationale (visual bar chart or progress indicator)
+   - List of cognitive complexity flags with severity
+   - Explicit recommendations: "Before implementing, document the rationale for changes X and Y — the plan doesn't explain why these approaches were chosen over alternatives"
+   - This section makes cognitive debt visible _before_ the work starts, when it's cheapest to address.
+
+**Visual hierarchy**: Sections 1-4 should dominate the viewport on load (hero depth for summary, elevated for architecture diagrams). Sections 6+ are reference material and should feel lighter (flat or recessed depth, compact layout, collapsible where appropriate).
+
+**Optional illustrations** — if `surf` CLI is available (`which surf`), consider generating a conceptual illustration of the planned system via `surf gemini --generate-image` when it would help the reader visualize the change. Embed as base64 data URI. See css-patterns.md "Generated Images" for container styles. Skip if surf isn't available or the plan is purely structural.
+
+Include responsive section navigation. Use a current-vs-planned visual language throughout: blue/neutral for current state, green/purple for planned additions, amber for areas of concern, red for gaps or risks. Write to `~/.agent/diagrams/` and open in browser.
+
+Ultrathink.
+
+$@

package/plugin/skills/visual-explainer/prompts/project-recap.md

@@ -0,0 +1,61 @@
+---
+description: Generate a visual HTML project recap — rebuild mental model of a project's current state, recent decisions, and cognitive debt hotspots
+---
+Load the visual-explainer skill, then generate a comprehensive visual project recap as a self-contained HTML page.
+
+Follow the visual-explainer skill workflow. Read the reference template, CSS patterns, and mermaid theming references before generating. Use a warm editorial or paper/ink aesthetic with muted blues and greens, but vary fonts and palette from previous diagrams.
+
+**Time window** — determine the recency window from `$1`:
+- Shorthand like `2w`, `30d`, `3m`: parse to git's `--since` format (`2w` → `"2 weeks ago"`, `30d` → `"30 days ago"`, `3m` → `"3 months ago"`)
+- If `$1` doesn't match a time pattern, treat it as free-form context and use the default window
+- No argument: default to `2w` (2 weeks)
+
+**Data gathering phase** — run these first to understand the project:
+
+1. **Project identity.** Read `README.md`, `CHANGELOG.md`, `package.json` / `Cargo.toml` / `pyproject.toml` / `go.mod` for name, description, version, dependencies. Read the top-level file structure.
+
+2. **Recent activity.** `git log --oneline --since=<window>` for commit history. `git log --stat --since=<window>` for file-level change scope. `git shortlog -sn --since=<window>` for contributor activity. Identify which areas of the codebase were most active.
+
+3. **Current state.** Check for uncommitted changes (`git status`). Check for stale branches (`git branch --no-merged`). Look for TODO/FIXME comments in recently changed files. Read progress docs if they exist (`~/.agent/memory/{project}/progress.md`, `~/.pi/agent/memory/{project}/progress.md`, `.pi/todos/`, or similar).
+
+4. **Decision context.** Read recent commit messages for rationale. If running in the same session as recent work, mine the conversation history. Read any plan docs, RFCs, or ADRs in the project directory.
+
+5. **Architecture scan.** Read key source files to understand the module structure and dependencies. Focus on entry points, public API surface, and the files most frequently changed in the time window.
+
+**Verification checkpoint** — before generating HTML, produce a structured fact sheet of every claim you will present in the recap:
+- Every quantitative figure: commit counts, file counts, line counts, branch counts
+- Every module, function, and type name you will reference
+- Every behavior and architecture description
+- For each, cite the source: the git command output that produced it, or the file:line where you read it
+Verify each claim against the code. If something cannot be verified, mark it as uncertain rather than stating it as fact. This fact sheet is your source of truth during HTML generation — do not deviate from it.
+
+**Optional hero image** — if `surf` CLI is available (`which surf`), generate a hero banner via `surf gemini --generate-image --aspect-ratio 16:9` that visually captures the project's identity or domain. Match the style to the page's palette. Embed as base64 data URI using the `.hero-img-wrap` pattern from css-patterns.md. Place above or just below the title. Skip if surf isn't available — the page should stand on its own.
+
+**Diagram structure** — the page should include:
+1. **Project identity** — not the README blurb. A *current-state* summary: what this project does, who uses it, what stage it's at (early dev, stable, actively shipping features). Include version, key dependencies, and the one-sentence "elevator pitch" for someone who forgot what they were building.
+2. **Architecture snapshot** — Mermaid diagram of the system as it exists today. Focus on the conceptual modules and their relationships, not every file. Label nodes with what they do, not just file names. Wrap in `.mermaid-wrap` with zoom controls (+/−/reset buttons), Ctrl/Cmd+scroll zoom, and click-and-drag panning (grab/grabbing cursors). See css-patterns.md "Mermaid Zoom Controls" for the full pattern. *Visual treatment: this is the visual anchor — use hero depth (elevated container, larger padding, subtle accent-tinted background). The rest of the page hangs off this diagram.*
+3. **Recent activity** — not raw git log. A human-readable narrative grouped by theme: feature work, bug fixes, refactors, infrastructure. Timeline visualization with the most significant changes called out. For each theme, a one-sentence summary of what happened and why it mattered.
+4. **Decision log** — key design decisions from the time window. Extracted from commit messages, conversation history, plan docs, progress docs. Each entry: what was decided, why, what was considered. This is the highest-value section for fighting cognitive debt — the reasoning that evaporates first.
+5. **State of things** — *visual treatment: use the KPI card pattern from css-patterns.md — large hero numbers for working/broken/blocked/in-progress counts, with color-coded trend indicators.* A dashboard of:
+   - What's working (stable, shipped, tested)
+   - What's in progress (uncommitted work, open branches, active TODOs)
+   - What's broken or degraded (known bugs, failing tests, tech debt items)
+   - What's blocked (waiting on external input, dependencies, decisions)
+6. **Mental model essentials** — the 5-10 things you need to hold in your head to work on this project effectively:
+   - Key invariants and contracts (what must always be true)
+   - Non-obvious coupling (things connected in ways you wouldn't guess from the file tree)
+   - Gotchas (common mistakes, easy-to-forget requirements, things that break silently)
+   - Naming conventions or patterns the codebase follows
+7. **Cognitive debt hotspots** — *visual treatment: use amber-tinted cards with severity indicators (colored left border: red for high, amber for medium, blue for low).* Areas where understanding is weakest:
+   - Code that changed recently but has no documented rationale
+   - Complex modules with no tests
+   - Areas where multiple people (or agents) made overlapping changes
+   - Files that are frequently modified but poorly understood
+   - Flag each with a severity and a concrete suggestion (e.g., "add a doc comment to `buildCoordinationInstructions` explaining the 4 coordination levels — this function is called from 3 places and the behavior is non-obvious")
+8. **Next steps** — inferred from recent activity, open TODOs, project trajectory. Not prescriptive — just "here's where the momentum was pointing when you left." Include any explicit next-step notes from progress docs or plan files.
+
+Include responsive section navigation. Use a warm, approachable visual language: muted blues and greens for architecture, amber callouts for cognitive debt hotspots, green/blue/amber/red for state-of-things status. Overflow prevention on any side-by-side or grid-based sections: apply `min-width: 0` on all grid/flex children and `overflow-wrap: break-word`. Never use `display: flex` on `<li>` for marker characters — use absolute positioning instead (see css-patterns.md Overflow Protection). Write to `~/.agent/diagrams/` and open in browser.
+
+Ultrathink.
+
+$@