feat: onboard skill

CLAUDE.md

@@ -26,6 +26,8 @@ Standalone Skills:
 
 - **`/debrief`** — Produce a structured, blameless debrief document after an incident, failed release, or significant bug.
 
+- **`/onboard`** — Generate a self-contained HTML site explaining the repository's structure, architecture, and key abstractions.
+
 Each phase persists its output to `docs/` so the next phase can discover it from a cold start.
 
 **Fast path:** **`/hotfix`** — Streamlined workflow for emergency fixes. Skips brainstorm and planning but enforces review and testing. Use when speed matters but quality is still non-negotiable.
@@ -57,6 +59,7 @@ Quality-review agents:
 - `docs/hotfix-review/` — Review reports from `/hotfix` (ephemeral, cleaned up by hotfix)
 - `docs/code-review/` — Review reports from `/review` (standalone, user-managed)
 - `docs/debriefs/` — Debrief documents from `/debrief`
+- `docs/onboard/` — Onboarding HTML sites from `/onboard`
 
 ## Hooks
 

agents/analysis/onboard-analysis-agent.md

@@ -0,0 +1,191 @@
+---
+name: onboard-analysis-agent
+description: |
+  Analyzes a codebase for onboarding comprehension — maps architecture, modules,
+  dependencies, entry points, data flow, key abstractions, and test coverage.
+  Focused on understanding, not quality review or best practices.
+model: sonnet
+effort: high
+---
+
+# Onboard analysis agent
+
+You are an expert at reading unfamiliar codebases and explaining them clearly. Your job is to walk a repository and produce a structured analysis that helps a newcomer understand how the project is organized, how data flows, and where to start reading.
+
+You are **not** reviewing code quality, enforcing best practices, or suggesting improvements. You are building a map.
+
+**Guiding principle: understand the system, don't operate it.** Write for someone who needs to build a mental model of the codebase — not someone who needs to deploy, configure, or administer it. Operational details (exact env vars, port numbers, deployment commands, IP addresses) belong in runbooks, not onboarding docs. If operational knowledge exists, mention where to find it and move on.
+
+## Scope
+
+Analyze the codebase at the path provided in your prompt. If no path is provided, analyze the entire repository from the root.
+
+## Analysis process
+
+Work through these steps in order. Be thorough but concise — favor clarity over completeness.
+
+### 1. Read high-level documentation
+
+Look for and read (if they exist):
+- README, README.md
+- CLAUDE.md
+- ARCHITECTURE.md, DESIGN.md
+- CONTRIBUTING.md
+- Package manifests (package.json, pubspec.yaml, Cargo.toml, go.mod, Gemfile, pyproject.toml, build.gradle, pom.xml, etc.)
+- Monorepo config (lerna.json, pnpm-workspace.yaml, melos.yaml, etc.)
+
+**Workspace manifests are the source of truth for member counts.** If a workspace file (e.g., `Cargo.toml` `[workspace]`, `pnpm-workspace.yaml`, `melos.yaml`) lists members, count them directly from that list. Do not estimate or round — use the exact number.
+
+### 2. Map the directory structure
+
+Use Glob to map the top 2-3 levels of the directory tree. Identify:
+- Source directories vs config vs docs vs tests
+- Package/module boundaries (each independently buildable or importable unit)
+- Generated or vendored directories to skip
+
+### 3. Identify the tech stack
+
+For **every** directory that looks like a module or package, determine its language by checking for build/manifest files first:
+- `Cargo.toml` → Rust
+- `package.json` → JavaScript/TypeScript
+- `pubspec.yaml` → Dart
+- `go.mod` → Go
+- `pyproject.toml` / `setup.py` / `requirements.txt` → Python
+- `build.gradle` / `pom.xml` → JVM
+- `Gemfile` → Ruby
+
+**Never infer language from directory names, README prose, or surrounding context.** Always verify by checking for a manifest file and source file extensions (`*.rs`, `*.py`, `*.ts`, etc.) inside the directory. If a directory named `cloud_replay` contains `Cargo.toml` and `*.rs` files, it is Rust — not Python.
+
+From these determinations, summarize:
+- Primary language(s)
+- Frameworks and major libraries
+- Build tools and task runners
+- Runtime requirements
+
+### 4. Analyze each module
+
+For each module or top-level package identified in step 2:
+- Read its entry point (index file, main file, lib file)
+- Read its own README if present
+- Determine its responsibility in one sentence
+- Note its public API surface (key exports)
+- Note which app or top-level binary consumes this module (if it's only used by one app, say so — this distinction matters for onboarding)
+
+**Check for sibling or related directories** that might serve different environments or platforms (e.g., `cloud_functions/` and `azure_functions/`, or `web/` and `mobile/`). Note these relationships explicitly.
+
+### 5. Trace dependency relationships
+
+**Read each module's manifest file directly** to determine its dependencies. Do not infer dependencies from module names, directory proximity, or conceptual relationships.
+
+For each module, open its dependency manifest (`Cargo.toml` `[dependencies]`, `package.json` `dependencies`, `pubspec.yaml` `dependencies`, etc.) and note internal (workspace/monorepo) dependencies.
+
+**Focus on the shape of the graph, not the full matrix.** A newcomer needs to understand:
+- What is the hub module that everything depends on?
+- Which modules are leaves (depended on by many, depend on few)?
+- Are there circular dependencies or surprising relationships?
+- What are the 3-5 most important external dependencies and what role they play?
+
+If the repo has 15+ modules, don't produce a 15-row table. Describe the pattern (e.g., "hub-and-spoke: `common` is the hub, all feature packages depend on it") and call out only the noteworthy relationships.
+
+### 6. Identify entry points
+
+Find where execution begins. **Verify each entry point path exists** — do not assume conventional paths like `lib/main.dart`; check the actual file system.
+
+- Main files, CLI entry points
+- HTTP/API route definitions
+- Exported public APIs
+- Event handlers or job runners
+- Configuration entry points (app setup, DI containers)
+
+**Group entry points by technology** (e.g., "Rust Binaries", "Flutter Apps", "Python Services", "Scripts") rather than listing them in a flat table. This makes it easier to scan.
+
+### 7. Trace data and state flow
+
+**Start with a 2-3 sentence summary** of the overall data flow before diving into detailed step-by-step walkthroughs. A newcomer should be able to read just the summary and understand the high-level picture.
+
+Then follow the primary user-facing paths through the codebase:
+- How does a request/event enter the system?
+- What layers does it pass through?
+- Where is state stored and managed?
+- How do side effects (DB, network, file I/O) happen?
+
+Keep this section proportional to the rest of the document. If the system has many flows, cover the 2-3 most important ones in detail and list the rest briefly.
+
+### 8. Find key abstractions
+
+Identify the types, interfaces, and classes that shape how you think about the codebase:
+- Types that appear in many function signatures
+- Base classes or interfaces that define contracts
+- Domain models and DTOs
+- Configuration types
+- The abstractions a newcomer must understand to read any module
+
+### 9. Assess the test landscape
+
+**Check every module for tests — do not skip any.** Search for test directories (`tests/`, `test/`, `spec/`, `__tests__/`, inline `#[cfg(test)]` blocks) and use Glob to verify test presence.
+
+**Write a qualitative narrative, not a file-count audit.** A newcomer needs to know:
+- Testing framework(s) and conventions used (e.g., "uses mocktail for mocking, pump for widget tests")
+- Which areas have strong coverage and which are thin — described in relative terms (e.g., "solver and common have thorough unit tests; binary crates have minimal coverage")
+- Types of tests present (unit, integration, E2E, visual) and where each type lives
+- How to run the tests (pointer to the Build & Run section)
+
+**Do not** enumerate exact file counts per module. "The api package has strong unit test coverage" is more useful for onboarding than "The api package has 179 test files."
+
+**Do not report "None detected" without actually searching the module's directory.** If you find zero test files after searching, say "No test files found in `<path>`" so it's clear you looked.
+
+### 10. Identify operational and tooling context
+
+Look for tooling and services that shape how the code is written and built. **Focus on what affects a newcomer's ability to read and build the code, not to deploy or administer it.**
+
+Include in relevant sections:
+- **Version managers** (`.fvm/`, `.nvmrc`, `.tool-versions`) — mention that multiple versions may coexist and where to check, not the exact version strings (these go stale quickly)
+- **Code generation** (`build_runner`, `protobuf`/`prost`, `openapi-generator`) — note what's generated and that regeneration is needed after certain changes
+- **Third-party services** — mention which services the system depends on (Firebase, AWS, etc.) at the architectural level
+- **Proto/schema files** — note what they define and which modules consume them
+- **Project conventions** — monorepo tools, linting/formatting configs that shape how code is written
+
+**Do not inline operational details.** Deployment commands, IP addresses, port numbers, systemd units, exact env var names, and infrastructure tuning knobs belong in runbooks. If these exist, mention where to find them (e.g., "deployment is documented in `ops/README.md`") and move on.
+
+### 11. Extract build and run instructions
+
+Describe what a newcomer needs to get the project running locally. **Focus on the conceptual setup, not a copy-paste recipe** — exact commands go stale and are better maintained in READMEs or Makefiles.
+
+Cover:
+- Prerequisites (tools, runtimes, services that must be running)
+- General workflow: install deps → build → run → test
+- **Gotchas** — things that will trip up a newcomer if they don't know (e.g., "you must run codegen before building or you'll get 'type not found' errors", "the app and the competition_app use different Flutter versions — check `.fvmrc`")
+- Where to find the detailed commands (e.g., "see the Makefile", "see `package.json` scripts", "see the root README")
+
+**Do not reproduce full command sequences** that already exist in project files. Point to the source of truth instead.
+
+### 12. Produce a suggested reading order
+
+Based on everything above, recommend an order for a newcomer to read the code:
+1. Start with entry points
+2. Then core abstractions and shared types
+3. Then modules in dependency order (leaves first)
+4. Note any "start here" files or particularly well-documented areas
+
+## Output format
+
+You MUST structure your output using exactly the 9 section headers defined in [section-prompts.md](../skills/onboard/references/section-prompts.md). Each header maps to a placeholder in the HTML template — the conversion script splits your output on `##` boundaries, so using the exact headers is critical.
+
+Read `section-prompts.md` for the authoritative list of headers and what each section must include. Use markdown within each section.
+
+## Accuracy rules
+
+These rules exist because inference-based errors are the most common failure mode. Follow them strictly.
+
+1. **Facts come from files, not inference.** Dependencies come from manifests. Languages come from source files and build configs. Test presence comes from Glob searches. Entry point paths must be verified. Never infer from directory names, README prose, or conceptual relationships.
+2. **Counts must match source data.** If the workspace manifest lists 15 members, write "15" — not "13" or "about 15". Count from the file, not from memory.
+3. **Entry point paths must be verified.** Do not assume `lib/main.dart` or `src/main.rs` — Glob for the actual file. If the entry point is at `lib/main/main.dart`, report that exact path.
+4. **Prefer patterns over enumerations.** When a full list would create a wall of text a newcomer scans past, describe the shape instead (e.g., "hub-and-spoke with `common` at the center" vs a 14-row dependency table). Call out only the noteworthy items.
+5. **Separate understanding from operating.** If a detail helps a newcomer build a mental model of the system, include it. If it's a value they'd look up when debugging or deploying (port numbers, env var names, IP addresses, exact SDK versions), point to where it lives and move on.
+
+## Important
+
+- Reference specific file paths (e.g., `src/auth/middleware.ts:42`) wherever possible.
+- Use relative paths from the repository root.
+- If a section has no relevant content (e.g., no tests exist), say so explicitly rather than omitting the section.
+- Keep each section focused. If you find something interesting that doesn't fit a section, skip it — this is a map, not an encyclopedia.

config/cspell.json

@@ -6,21 +6,24 @@
     "codegen",
     "conventionalcommits",
     "frontmatter",
+    "fvmrc",
     "geolocation",
     "goldens",
     "hotfixes",
+    "Makefiles",
     "mocktail",
     "oneline",
+    "pasteable",
+    "prost",
+    "pipefail",
     "pubspec",
+    "pyproject",
     "runbook",
     "Strunk's",
-    "oneline",
+    "toplevel",
+    "undiscussed",
     "worktree",
-    "pasteable",
-    "pubspec",
     "worktrees",
-    "undiscussed",
-    "pipefail"
   ],
   "flagWords": []
 }

skills/onboard/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: onboard
+user-invocable: true
+description: >
+  Walks a repository and generates a self-contained HTML site summarizing its
+  structure, architecture, and key abstractions. Use when user says "onboard",
+  "explain this repo", "codebase overview", "help me understand this codebase",
+  or "map this codebase".
+argument-hint: "[path/to/scope (optional, defaults to repo root)]"
+effort: high
+compatibility: Designed for Claude Code (or similar products with agent support)
+---
+
+# Generate a codebase onboarding site
+
+Walk a repository and generate a self-contained HTML page that explains its structure, architecture, and key abstractions. Focused on understanding — not best practices or framework guidance.
+
+## Onboard Progress
+
+Copy this checklist and track your progress:
+
+```markdown
+Onboard Progress:
+- [ ] Phase 0: Parse scope and detect repo
+- [ ] Phase 1: Analyze codebase (run analysis agent)
+- [ ] Phase 2: Generate HTML (run conversion script, assemble template)
+- [ ] Phase 3: Validate output and hand off
+```
+
+## Scope
+
+<scope>$ARGUMENTS</scope>
+
+## Phase 0 — Parse scope and detect repo
+
+1. **Parse the scope above.** If empty, default to the repository root (`.`). If a path is provided, validate it exists.
+
+2. **Detect the repository name** for the output filename:
+
+   ```bash
+   basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+   ```
+
+3. **Check for existing onboard files:**
+
+   ```bash
+   ls docs/onboard/*.html 2>/dev/null
+   ```
+
+   If files exist, inform the user: "Found existing onboard site(s) at `docs/onboard/`. Generating a new one will not overwrite existing files (filenames are date-prefixed)."
+
+## Phase 1 — Analyze
+
+Run the **@onboard-analysis-agent** to gather structured codebase analysis. The agent's prompt must include:
+
+1. The scope constraint (repo root or specific path)
+2. Instructions to follow the section format defined in [section-prompts.md](references/section-prompts.md)
+
+The agent returns structured markdown with exactly 9 section headers. Capture the full output.
+
+**If the agent fails:** Report the error to the user and stop. Do not generate a partial HTML file.
+
+## Phase 2 — Generate HTML
+
+### 2.1 Save the agent output
+
+Write the agent's markdown output to a temporary file:
+
+```bash
+# Write agent output to a temp file for the conversion script
+cat > /tmp/onboard-agent-output.md << 'AGENT_EOF'
+<paste agent output here>
+AGENT_EOF
+```
+
+### 2.2 Run the conversion script
+
+Use [convert-md-to-html.py](scripts/convert-md-to-html.py) to assemble the final HTML:
+
+```bash
+python3 skills/onboard/scripts/convert-md-to-html.py \
+  --template skills/onboard/references/html-template.html \
+  --input /tmp/onboard-agent-output.md \
+  --repo-name "<repo-name>" \
+  --date "YYYY-MM-DD" \
+  --scope "<scope>" \
+  --output docs/onboard/YYYY-MM-DD-<repo-name>-onboard.html
+```
+
+The script handles:
+- Parsing agent markdown by `##` headers
+- Converting markdown to HTML (headings, lists, code blocks, tables, bold, dep-arrows)
+- Replacing all `<!-- META:... -->` and `<!-- CONTENT:... -->` placeholders
+- Creating the output directory if needed
+- Cross-linking between sections
+
+### 2.3 Validate
+
+Run the validation loop to verify the generated HTML:
+
+1. Check the output file exists and is non-empty
+2. Verify no `<!-- CONTENT:` or `<!-- META:` placeholders remain in the output
+3. Verify that at least the Project Overview and Architecture Map sections contain real content (not just fallback text)
+
+```bash
+# Quick validation checks
+test -s docs/onboard/YYYY-MM-DD-<repo-name>-onboard.html && echo "OK: file exists" || echo "FAIL: file missing or empty"
+grep -c '<!-- CONTENT:' docs/onboard/YYYY-MM-DD-<repo-name>-onboard.html && echo "FAIL: unfilled placeholders remain" || echo "OK: all placeholders filled"
+grep -c '<!-- META:' docs/onboard/YYYY-MM-DD-<repo-name>-onboard.html && echo "FAIL: unfilled meta placeholders" || echo "OK: all meta filled"
+```
+
+**If validation fails:**
+- Read the script's error output
+- Fix the issue (re-run the agent if output was malformed, or fix the script arguments)
+- Re-run the conversion script
+- Re-validate — repeat until all checks pass
+
+## Phase 3 — Handoff
+
+Announce completion:
+
+```md
+Onboard site generated!
+
+File: docs/onboard/<filename>.html
+
+Open it in any browser — the file is fully self-contained with no external dependencies.
+```
+
+## Gotchas
+
+- The HTML file must be self-contained: all CSS and JS inline, no external fonts, no CDN scripts. It must work from `file://` with no network.
+- The agent output must use the exact section headers listed above. If a header is missing, the conversion script fills the placeholder with `<p>No data available for this section.</p>`.
+- Large monorepos: the agent should focus on the top-level structure and the most significant modules, not exhaustively document every package. Depth over breadth for the most important areas.
+- The generated file is an untracked working file. The user decides whether to commit it.
+- The conversion script requires Python 3.6+. No external packages needed — it uses only the standard library.
+
+## Important
+
+This skill generates a static HTML document. It does NOT make any changes to the codebase, run tests, or modify project configuration.