Docs Maintainer

Overview

Keep docs/ accurate after substantial code changes by updating, adding, or removing documentation in a separate, follow-up commit.

Workflow (run after the feature commit)

1. Identify the behavior changes introduced by the feature commit (new behavior, removed behavior, or changed behavior).
2. Search docs/ for impacted material (use rg -n "<keyword>" docs).
3. Update documentation to match the new behavior:
   • Add new module files when a new user-facing feature, API route, or data model is added.
   • Update existing module sections when behavior, data shape, or flows change.
   • Delete docs for removed features and remove links from the index.
4. Update the index and navigation:
   • docs/README.md must link to any new docs and remove links to deleted docs.
   • Update docs/architecture/site-map.md for route changes.
   • Update docs/api/routes.md for API route changes.
   • Update docs/data/data-models.md for schema changes.
5. Validate internal links in docs/:

bash
1python3 - <<'PY'
2import os, re
3root = "docs"
4missing = []
5if not os.path.isdir(root):
6    raise SystemExit('docs directory not found. Run from repo root.')
7link_re = re.compile(r"\[[^\]]*\]\(([^)]+)\)")
8for dirpath, _, filenames in os.walk(root):
9    for fn in filenames:
10        if not fn.endswith(".md"):
11            continue
12        path = os.path.join(dirpath, fn)
13        with open(path, "r", encoding="utf-8") as f:
14            text = f.read()
15        for link in link_re.findall(text):
16            if link.startswith(("http://", "https://", "mailto:")):
17                continue
18            if link.startswith("#"):
19                continue
20            link_path = link.split("#", 1)[0]
21            if not link_path:
22                continue
23            target = os.path.normpath(os.path.join(dirpath, link_path))
24            if not os.path.exists(target):
25                missing.append((path, link, target))
26if missing:
27    print("Missing links:")
28    for m in missing:
29        print(m)
30    raise SystemExit(1)
31print("All internal links resolved.")
32PY

6. Commit the documentation changes separately (after the feature commit). Use a clear message like docs: update for <feature>.

Scope reminders

• Focus on user-facing behavior, APIs, data model changes, and onboarding/admin flows.
• If a change does not affect any documented behavior or assumptions, no docs update is required.