docs: fact-check sweep — align docs and CLI help with shipped behavior#145
Merged
Conversation
…erences P1 agent-surface plans are complete; lift status to roadmap and fix stale schema, MCP, validate, and index-path claims across docs and agent templates.
Add type_heritage to served rule and roadmap substrate inventory, align MCP tool/resource descriptions and CLI help with index.db paths and validate behavior.
Align agent templates, README, packaging, glossary, and MCP metadata with recipes-loader behavior; fix Tier 11 glossary anchor suffix.
Fix MCP tool/resource descriptions, CLI help/JSDoc, audit cache comments, research doc relative paths, and non-goals MCP resource citation.
List all 17 tools and mcp-instructions in cmd-mcp/cmd-serve help, fix schema cache wording, recipe_recency write-path docs, and skill assembly cache notes.
Fix bundled-only recipe help text, audit --ci exit behavior, default-ON watch wording, and skill resource freshness contract.
Align README quick-start comments and schema.gen fallback with 17-tool MCP surface and codemap://schema lazy-cache behavior.
Replace stale worktree/co-process wording with git archive + tar -x audit cache semantics and in-process chokidar watch behavior.
Fix architecture audit wiring cross-ref, non-goals transport wording, stale MCP-only HTTP JSDoc, and user-facing audit error messages.
Fact-check passes 9–19: per-tool JSON shapes (not uniform query --json), no-CLI-verb tools on MCP+HTTP, audit-cache vs state-dir, query --ci quiet split, assembled resources, and related CLI/help string fixes.
|
|
Warning Review limit reached
More reviews will be available in 50 minutes and 53 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (4)
📝 WalkthroughWalkthroughThis PR comprehensively updates documentation across the Codemap codebase to reflect the current system state: clarifying database paths ( ChangesDocumentation Consolidation and Clarification
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested labels
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/architecture.md`:
- Around line 148-149: Update the "MCP wiring" doc to match the code: replace
the claim that src/cli/cmd-mcp.ts only accepts --help/--root/--config with the
current CLI flags (include --watch, --no-watch and --debounce), and change the
description that query_batch calls executeQueryBatch to state that
src/application/tool-handlers.ts's handleQueryBatch runs each item by calling
executeQuery(...) directly (so remove/replace references to executeQueryBatch
and adjust wording about batching behavior and per-item error isolation
accordingly).
In `@docs/glossary.md`:
- Line 40: The glossary link uses a broken fragment
`#audit--base-ref--git-ref-baseline`; update that fragment to match the actual
heading slug for the "audit --base <ref>" anchor (i.e., find the heading for the
audit --base <ref> section and replace `#audit--base-ref--git-ref-baseline` with
the exact slug it generates so the cross-reference resolves correctly). Ensure
the replacement appears in the Two-snapshot structural-drift paragraph
referencing `audit --base <ref>`.
- Line 112: Replace the lowercase "github" with the official capitalization
"GitHub" in the sentence that explains the CI-aggregate flag for `codemap query`
and `codemap audit` (mentions `--ci`, `--format sarif`, `process.exitCode = 1`,
mutual exclusivity with `--json`/`--format <other>`) so the user-facing
documentation uses the correct trademarked casing.
In `@templates/agent-content/rule/00-full.md`:
- Line 43: The table row mixes a bare recipe id and a --recipe flag (it shows
`type-descendants` without the flag while other cells use `--recipe`), so update
the entry to use the consistent invocation syntax `--recipe type-descendants`;
locate the table row containing `type_heritage`, `--recipe type-ancestors` and
`type-descendants` and replace the bare `type-descendants` with `--recipe
type-descendants` so it matches the rest of the examples and copy/paste
behavior.
In `@templates/agent-content/skill/00-overview.md`:
- Line 25: The output contract example contains invalid JSON for the --group-by
example; replace the current `{"group_by", "groups"}` token with a valid JSON
object example such as `{"group_by": "field_name", "groups": [{"key": "...",
"count": N}]}` and update the composed shapes line (the `--group-by` entry) so
the docs show a valid object-shape example matching the surrounding contract
language (`--summary`, `--baseline` remain unchanged).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: ec48b7d0-6d9f-4510-af32-be2a3db0f8f4
📒 Files selected for processing (45)
README.mddocs/README.mddocs/agents.mddocs/architecture.mddocs/glossary.mddocs/packaging.mddocs/plans/agent-surface-and-ops.mddocs/plans/agent-surface-delivery.mddocs/plans/callback-dispatch-synthesis.mddocs/plans/cross-project-mcp-root.mddocs/plans/fts-default-on-evaluation.mddocs/plans/github-marketplace-action.mddocs/plans/perf-triangulation-rollout.mddocs/plans/substrate-extraction.mddocs/plans/unresolved-calls-staging.mddocs/research/agent-eval-findings-2026-05.mddocs/research/non-goals-reassessment-2026-05.mddocs/roadmap.mdscripts/benchmark-query-output.tssrc/api.tssrc/application/agent-content.tssrc/application/audit-engine.tssrc/application/audit-worktree.tssrc/application/http-server.tssrc/application/index-engine.tssrc/application/mcp-server.tssrc/application/resource-handlers.tssrc/application/tool-handlers.tssrc/application/watcher.tssrc/benchmark-config.tssrc/cli/bootstrap.tssrc/cli/cmd-audit.tssrc/cli/cmd-context.tssrc/cli/cmd-mcp.tssrc/cli/cmd-query.tssrc/cli/cmd-serve.tssrc/cli/cmd-validate.tssrc/cli/cmd-watch.tstemplates/agent-content/mcp-instructions.mdtemplates/agent-content/rule/00-full.mdtemplates/agent-content/skill/00-overview.mdtemplates/agent-content/skill/10-recipes-context.mdtemplates/agent-content/skill/30-schema.gen.mdtemplates/agent-content/skill/40-query-patterns.mdtemplates/agent-content/skill/50-maintenance.md
💤 Files with no reviewable changes (2)
- docs/plans/agent-surface-delivery.md
- docs/plans/agent-surface-and-ops.md
| ### `--ci` (CLI flag) | ||
|
|
||
| CI-aggregate flag on `codemap query` and `codemap audit`. Aliases `--format sarif` + `process.exitCode = 1` on findings/additions + suppresses the no-locatable-rows stderr warning (CI templates would surface it as red noise; the row-set is the gating signal). Mutually exclusive with `--json` (different format aliases) and with `--format <other>` (contradicts the alias); `--ci --format sarif` redundant but accepted. Designed for the GitHub Marketplace Action's headline default (`audit --base ${{ github.base_ref }} --ci`); independently useful for any non-Action CI consumer. | ||
| CI-aggregate flag on `codemap query` and `codemap audit`. Aliases `--format sarif` + `process.exitCode = 1` on findings (`query`) or delta additions (`audit`). On **`query` only**, also suppresses the no-locatable-rows stderr warning (CI templates would surface it as red noise; the row-set is the gating signal). Mutually exclusive with `--json` (different format aliases) and with `--format <other>` (contradicts the alias); `--ci --format sarif` redundant but accepted. Designed for the GitHub Marketplace Action's headline default (`audit --base ${{ github.base_ref }} --ci`); independently useful for any non-Action CI consumer. |
There was a problem hiding this comment.
Use official capitalization for GitHub.
Line 112 uses “github” in a user-facing sentence; this should be “GitHub” for consistency and correctness.
Suggested wording tweak
- ... Designed for the github Marketplace Action's headline default ...
+ ... Designed for the GitHub Marketplace Action's headline default ...As per coding guidelines: "Documentation should be written in clear, concise English".
🧰 Tools
🪛 LanguageTool
[uncategorized] ~112-~112: The official name of this software platform is spelled with a capital “H”.
Context: ... Marketplace Action's headline default (audit --base ${{ github.base_ref }} --ci); independently usefu...
(GITHUB)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/glossary.md` at line 112, Replace the lowercase "github" with the
official capitalization "GitHub" in the sentence that explains the CI-aggregate
flag for `codemap query` and `codemap audit` (mentions `--ci`, `--format sarif`,
`process.exitCode = 1`, mutual exclusivity with `--json`/`--format <other>`) so
the user-facing documentation uses the correct trademarked casing.
✅ Addressed in commit 21c6076
Contributor
Author
There was a problem hiding this comment.
The prose already uses GitHub Marketplace Action. The lowercase github in the same sentence is inside the GitHub Actions expression `${{ github.base_ref }}` — that context name is defined by GitHub and must stay lowercase per Actions syntax. No change needed.
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Resolve the CodeRabbit comment on this PR
gh pr view 145 --repo stainless-code/codemap --json number
# List bot comments on the PR to find the one to resolve
gh api graphql -f query='
{
repository(owner: "stainless-code", name: "codemap") {
pullRequest(number: 145) {
reviewThreads(first: 50) {
nodes {
id
isResolved
comments(first: 1) {
nodes {
id
author { login }
body
}
}
}
}
}
}
}'Length of output: 10490
@SutuSebastian, you're absolutely right. The lowercase github is part of the GitHub Actions expression `${{ github.base_ref }}` — a case-sensitive context name defined by GitHub's Actions spec — and must stay lowercase. The prose "GitHub Marketplace Action" earlier in the same sentence is already correctly capitalized. This was a false positive from the LanguageTool static analyzer. The review thread is already resolved. Apologies for the noise!
🐇 (noted for good!)
✏️ Learnings added
Learnt from: SutuSebastian
Repo: stainless-code/codemap PR: 145
File: docs/glossary.md:112-112
Timestamp: 2026-05-26T13:43:04.136Z
Learning: In stainless-code/codemap documentation (and generally), the token `github` inside a GitHub Actions expression such as `${{ github.base_ref }}` or `${{ github.sha }}` is intentionally lowercase — it is the GitHub Actions context name defined by GitHub's spec and must NOT be capitalized. LanguageTool's GITHUB rule will falsely flag this as a capitalization error. Do not raise a review comment on `github` when it appears inside a `${{ ... }}` expression, even within otherwise-prose documentation sentences.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
🧠 Learnings used
Learnt from: SutuSebastian
Repo: stainless-code/codemap PR: 77
File: docs/plans/codemap-apply.md:0-0
Timestamp: 2026-05-06T09:08:52.852Z
Learning: In the codemap project, ensure MCP/HTTP transport examples in documentation use MCP-spec snake_case keys for tool arguments: use dry_run (not --dry-run) and yes (not --yes), aligning with existing tools like query_recipe (see architecture.md, MCP wiring). For non-TTY transports, require yes: true unconditionally since there is no interactive prompt fallback (per the apply plan). Apply this in docs/plans/codemap-apply.md and related architecture docs, making sure examples reflect these keys rather than CLI-style flags.
Learnt from: SutuSebastian
Repo: stainless-code/codemap PR: 77
File: docs/plans/codemap-apply.md:0-0
Timestamp: 2026-05-06T09:08:52.048Z
Learning: In stainless-code/codemap, Markdown linting with markdownlint is not enforced. There is no .markdownlint* config file, and oxfmt does not check MD040 (fenced code block language). Files such as architecture.md and benchmark.md have untagged fences. Future MD040 warnings should be treated as non-blocking review information and must not block PRs. This pattern applies to all Markdown files in the repository. If you later enable linting, add a .markdownlint config and gate changes in CI, and adjust the enriched guidance accordingly.
Learnt from: SutuSebastian
Repo: stainless-code/codemap PR: 80
File: docs/glossary.md:0-0
Timestamp: 2026-05-15T13:33:07.225Z
Learning: When documenting MCP/HTTP resource caching behavior in stainless-code/codemap, reflect the intended per-process caching split: only `codemap://schema`, `codemap://skill`, and `codemap://rule` are lazy-cached (constant for the server lifetime); `codemap://recipes` and `codemap://recipes/{id}` must be documented as deliberately NOT cached and instead fetched live per call to keep `last_run_at`/`run_count` recency fields fresh. Ensure this distinction is consistent across all docs (e.g., `docs/glossary.md`, `docs/architecture.md`, etc.) and stays aligned with the implementation in `src/application/resource-handlers.ts`.
Fact-checked 4/5 bot comments; push back on false-positive GitHub capitalization (Actions expression github.base_ref is correct).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Nine adversarial doc-sweep passes fact-checking user-facing strings against the codebase (post–#144). No runtime behavior changes — docs, CLI/MCP help, agent-content templates, and a few src comments only.
agent-surface-delivery.md,agent-surface-and-ops.md) and fix cross-refs.codemap/index.db(not.codemap.db); state-dir vs hardcodedaudit-cache/documented--base:git archive | tar -x+ cached index at sha (not temp DB / worktree)query --json), no-CLI-verb tools on MCP + HTTP (query_batch,trace,explore,node)GET /resourcesshipped; skill/rule assembled fromtemplates/agent-content/query --ciincludes quiet;audit --cidoes not; validate statusesstale | missing | unindexedmcp/serve45 files, net −131 lines.
Test plan
Summary by CodeRabbit
Release Notes
Documentation
--base,--ci, and recipe catalog handlingPlans