Incrementally maintain ai-docs map indexes while enforcing consistent map templates across repositories. Use when asked to update ai-docs/map after code changes, fix stale Path entries, add canonical or hotspot navigation for new or moved modules, or produce a concise map and template drift report.
Update only impacted ai-docs/map/ scopes. Keep documentation pointer-based, navigation-critical, and minimal. Resolve the diff range automatically from the ai-docs Git baseline label, and enforce consistent map file templates so incremental edits do not drift across projects.
commit_window (optional): Number of latest commits to inspect.focus (optional): Extra scope hints from the user (for example loss, dataset, predictor).enforce_templates (optional, default true): Whether to normalize impacted map files to the map template profile.Interpretation rules:
commit_window is provided and N > 0: inspect files changed in HEAD~N..HEAD plus current uncommitted changes.commit_window is omitted: read ai-docs/_meta/git-baseline.md, extract AI-DOCS-BASELINE-COMMIT, and inspect files changed in plus current uncommitted changes.<baseline>..HEADUse this sequence before map edits:
ai-docs/_meta/template-profile.md.AI-DOCS-TEMPLATE-PROFILE: <profile> when present.ai-docs-v1 map rules.metadata or builtin).Map template rules for ai-docs-v1:
AI-MAP: token near the top of each map index file.## Key files section with curated entries.## Related links at the end.### Path: `path/to/file`
Purpose: One-line role of this file in the architecture.
Key symbols: Core classes/functions/constants for navigation.
Pitfalls: High-risk assumptions or common break points.
When commit_window is omitted, use this sequence:
ai-docs/_meta/git-baseline.md.AI-DOCS-BASELINE-COMMIT: <sha>.git cat-file -e <sha>^{commit}).<sha>..HEAD as the committed diff range.git log -1 --format=%H -- ai-docsmetadata, git-log, or none).ai-docs/00-START-HERE.md before exploration or edits.ai-docs/map/.Path: entries and template drift in impacted indexes.enforce_templates=trueai-docs/_meta/git-baseline.md to current HEAD metadata after map update pass, including no-op passes where map content was already up to date.Use commands like these (adjust as needed):
# 1) Read baseline commit from ai-docs metadata
rg -No "AI-DOCS-BASELINE-COMMIT:\\s*([0-9a-f]{40})" -r '$1' ai-docs/_meta/git-baseline.md
# 2) Validate baseline commit
git cat-file -e <BASELINE_COMMIT>^{commit}
# 3) Changed files by baseline range (default path)
git diff --name-only <BASELINE_COMMIT>..HEAD
# 4) Changed files by commit window override
git diff --name-only HEAD~<N>..HEAD
# 5) Uncommitted changes
git diff --name-only
git diff --name-only --cached
# 6) Locate map files for impacted scopes
find ai-docs/map -type f | sort
# 7) Verify Path entries
rg -n "Path:" ai-docs/map
# 8) Verify map template markers
rg -n "^AI-MAP:" ai-docs/map
rg -n "^### Path:|^Purpose:|^Key symbols:|^Pitfalls:" ai-docs/map
ai-docs/map/ tree.ai-docs/_meta/git-baseline.md and ai-docs/_meta/template-profile.md machine-parseable with stable keys.Return these sections at minimum:
rg -n "Path:" ai-docs/map and map template checksIf no map updates are needed, state that explicitly and include verification results and baseline refresh outcome.