docs: add onboarding guides (how-it-works + get-started)#4
Conversation
Add two standalone onboarding docs for engineers adopting code-docs: - how-it-works.md: end-to-end lifecycle walkthrough covering doc authoring, agent routing via AGENTS.md, frontmatter generation, and staleness detection, with concrete examples from this repo - get-started.md: step-by-step guide for adding code-docs to an existing repo with a docs/ folder, including manual and automated frontmatter migration paths and a troubleshooting section drawn from real-world integration experience Also: - Fix stale reusable template section in automation-workflow.md to reflect the Claude Code implementation (adds frontmatter-prompt.md to copy checklist, corrects secret name to ANTHROPIC_API_KEY) - Regenerate AGENTS.md index with both new docs - Add Documentation section to README linking to guides and specs
There was a problem hiding this comment.
Pull request overview
Adds onboarding documentation to help engineers adopt and understand the code-docs system, and updates repo entry points to link/discover the new guides.
Changes:
- Add two onboarding guides:
docs/how-it-works.md(lifecycle walkthrough) anddocs/get-started.md(setup/migration/troubleshooting). - Update
docs/automation-workflow.mdreusable template checklist and validation date. - Update
AGENTS.mdindex and add a Documentation section toREADME.md; add.github/copilot-instructions.mdcontent.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/how-it-works.md | New lifecycle walkthrough for authoring, routing, automation, and staleness. |
| docs/get-started.md | New setup/migration guide and troubleshooting for adopting code-docs. |
| docs/automation-workflow.md | Updates “reusable template” steps and bumps lastValidated. |
| README.md | Adds Documentation section linking to the new guides. |
| AGENTS.md | Regenerates index and appends additional “vexp” instructions. |
| .github/copilot-instructions.md | Adds “vexp context tools” instructions for Copilot. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
docs/get-started.md
Outdated
| - **Workflows**: `.github/workflows/docs-sync.yml` and `docs-staleness.yml` | ||
| - **Task prompt**: `.github/agents/frontmatter-prompt.md` |
There was a problem hiding this comment.
The workflows bullet lists docs-staleness.yml without its directory. It should be .github/workflows/docs-staleness.yml to match the actual file path.
docs/get-started.md
Outdated
|
|
||
| **GitHub Actions secret.** Add `ANTHROPIC_API_KEY` to your repo's GitHub Actions secrets (Settings > Secrets and variables > Actions). The `docs-sync.yml` workflow uses this to call Claude Code for frontmatter generation. | ||
|
|
||
| **Staleness trigger paths.** Open `docs-staleness.yml` and update the `push.paths` section to include your repo's actual code paths (e.g., `src/**`, `lib/**`). Without this, the workflow only performs time-based staleness checks — it won't detect when code changes make a doc stale. |
There was a problem hiding this comment.
This section says to open docs-staleness.yml, but the workflow is located at .github/workflows/docs-staleness.yml. Updating the reference here will prevent readers from looking in the wrong place.
docs/get-started.md
Outdated
|
|
||
| The `description` field is the most important. Write it as a trigger condition starting with "Load when", not a topic summary. Keep it under 160 characters. | ||
|
|
||
| For docs that don't map to specific code paths (architectural overviews, onboarding guides, process docs), omit the `paths` field entirely. Staleness detection will use time-based checks only. |
There was a problem hiding this comment.
This advice to omit paths entirely conflicts with the repo’s automation and examples: .github/agents/frontmatter-prompt.md treats missing paths as an LLM-owned field to populate (often as an empty list), and several existing docs use paths: [] (e.g., docs/llm-prompt-design-agnostic.md). Consider updating this to recommend paths: [] for “no paths” docs (or explicitly note that automation may add paths: [] even if you omit it).
| For docs that don't map to specific code paths (architectural overviews, onboarding guides, process docs), omit the `paths` field entirely. Staleness detection will use time-based checks only. | |
| For docs that don't map to specific code paths (architectural overviews, onboarding guides, process docs), set `paths: []` to indicate there are no code paths. Staleness detection will use time-based checks only. If you omit `paths`, automation may add `paths: []` (or other values) for you. |
docs/automation-workflow.md
Outdated
| --- | ||
| description: "Load when modifying GitHub Actions workflows, debugging CI runs, or changing staleness detection logic." | ||
| lastValidated: "2026-03-12" | ||
| lastValidated: "2026-03-28" |
There was a problem hiding this comment.
lastValidated was bumped to 2026-03-28, but the doc still describes a scripts/agents/update-frontmatter.py + llm.py implementation that doesn’t exist in this repo, and docs-sync.yml actually invokes Claude Code directly. Please either update the doc sections that reference the non-existent scripts to match the current workflows, or revert the lastValidated bump until the content is accurate again.
docs/automation-workflow.md
Outdated
|
|
||
| To stamp this system onto a new repo: | ||
|
|
||
| 1. Copy `.github/workflows/docs-sync.yml` and `docs-staleness.yml`. |
There was a problem hiding this comment.
In the reusable template checklist, docs-staleness.yml should be referenced as .github/workflows/docs-staleness.yml to match its actual location (parallel to .github/workflows/docs-sync.yml).
| 1. Copy `.github/workflows/docs-sync.yml` and `docs-staleness.yml`. | |
| 1. Copy `.github/workflows/docs-sync.yml` and `.github/workflows/docs-staleness.yml`. |
AGENTS.md
Outdated
| <!-- AGENTS-INDEX-END --> | ||
|
|
||
|
|
||
| ## vexp <!-- vexp v1.2.30 --> | ||
|
|
||
| **MANDATORY: use `run_pipeline` — do NOT grep or glob the codebase.** | ||
| vexp returns pre-indexed, graph-ranked context in a single call. | ||
|
|
||
| ### Workflow | ||
| 1. `run_pipeline` with your task description — ALWAYS FIRST (replaces all other tools) | ||
| 2. Make targeted changes based on the context returned | ||
| 3. `run_pipeline` again only if you need more context | ||
|
|
||
| ### Available MCP tools | ||
| - `run_pipeline` — **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call. | ||
| Auto-detects intent. Includes file content. Example: `run_pipeline({ "task": "fix auth bug" })` | ||
| - `get_context_capsule` — lightweight, for simple questions only | ||
| - `get_impact_graph` — impact analysis of a specific symbol | ||
| - `search_logic_flow` — execution paths between functions | ||
| - `get_skeleton` — compact file structure | ||
| - `index_status` — indexing status | ||
| - `get_session_context` — recall observations from sessions | ||
| - `search_memory` — cross-session search | ||
| - `save_observation` — persist insights (prefer run_pipeline's observation param) | ||
|
|
||
| ### Agentic search | ||
| - Do NOT use built-in file search, grep, or codebase indexing — always call `run_pipeline` first | ||
| - If you spawn sub-agents or background tasks, pass them the context from `run_pipeline` | ||
| rather than letting them search the codebase independently | ||
|
|
||
| ### Smart Features | ||
| Intent auto-detection, hybrid ranking, session memory, auto-expanding budget. | ||
|
|
||
| ### Multi-Repo | ||
| `run_pipeline` auto-queries all indexed repos. Use `repos: ["alias"]` to scope. Run `index_status` to see aliases. | ||
| <!-- /vexp --> No newline at end of file |
There was a problem hiding this comment.
AGENTS.md is specified as having exactly three sections in a fixed order (preamble, repo-level context, index table) per docs/agents-md-structure.md. Adding the ## vexp block after <!-- AGENTS-INDEX-END --> breaks that structure and will also be loaded by default in agent sessions, increasing prompt/token overhead. Consider moving this content into a separate doc under docs/ and linking it from the index (or removing it if not universally applicable).
| <!-- AGENTS-INDEX-END --> | |
| ## vexp <!-- vexp v1.2.30 --> | |
| **MANDATORY: use `run_pipeline` — do NOT grep or glob the codebase.** | |
| vexp returns pre-indexed, graph-ranked context in a single call. | |
| ### Workflow | |
| 1. `run_pipeline` with your task description — ALWAYS FIRST (replaces all other tools) | |
| 2. Make targeted changes based on the context returned | |
| 3. `run_pipeline` again only if you need more context | |
| ### Available MCP tools | |
| - `run_pipeline` — **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call. | |
| Auto-detects intent. Includes file content. Example: `run_pipeline({ "task": "fix auth bug" })` | |
| - `get_context_capsule` — lightweight, for simple questions only | |
| - `get_impact_graph` — impact analysis of a specific symbol | |
| - `search_logic_flow` — execution paths between functions | |
| - `get_skeleton` — compact file structure | |
| - `index_status` — indexing status | |
| - `get_session_context` — recall observations from sessions | |
| - `search_memory` — cross-session search | |
| - `save_observation` — persist insights (prefer run_pipeline's observation param) | |
| ### Agentic search | |
| - Do NOT use built-in file search, grep, or codebase indexing — always call `run_pipeline` first | |
| - If you spawn sub-agents or background tasks, pass them the context from `run_pipeline` | |
| rather than letting them search the codebase independently | |
| ### Smart Features | |
| Intent auto-detection, hybrid ranking, session memory, auto-expanding budget. | |
| ### Multi-Repo | |
| `run_pipeline` auto-queries all indexed repos. Use `repos: ["alias"]` to scope. Run `index_status` to see aliases. | |
| <!-- /vexp --> | |
| <!-- AGENTS-INDEX-END --> |
- Use full paths for docs-staleness.yml references in get-started.md - Recommend paths: [] instead of omitting paths for no-code-path docs - Revert automation-workflow.md lastValidated bump (content still references non-existent scripts) - Use full path for docs-staleness.yml in reusable template checklist - Remove vexp block from AGENTS.md that violated documented structure
Summary
docs/how-it-works.md— end-to-end lifecycle walkthrough covering doc authoring, agent routing via AGENTS.md, frontmatter generation, and staleness detection with concrete examples from this repodocs/get-started.md— step-by-step guide for adding code-docs to an existing repo with adocs/folder, including manual and automated frontmatter migration and a troubleshooting section drawn from real-world integration experiencedocs/automation-workflow.md(addsfrontmatter-prompt.mdto copy checklist, corrects secret name toANTHROPIC_API_KEY)Context
Engineers evaluating or adopting code-docs had no standalone onboarding material. The README serves as a pitch, and the existing docs are detailed specs for people already working within the system. These two guides fill the gap between "I've heard about this" and "I'm using it."
The troubleshooting section in get-started.md covers 7 specific failure modes encountered during a real integration of code-docs into an existing repository (nested directory paths, markdownlint conflicts, git exclusions, PEP 668, multi-commit push ranges, and more).
Test plan
python scripts/agents/build-index.py --dry-runproduces clean output with rows for both new docs and no warnings