Document docs anchor vs normalize pipeline

Author: flyingrobots

CONTRIBUTING.md

@@ -82,7 +82,7 @@ If the hook fails, fix the reported issues and retry the commit.
 
 ### Docs Normalization (AST pipeline)
 
-We run a deterministic Markdown normalizer (unified/remark) as a prebuild check. It parses Markdown to an AST, applies project transforms (anchors, TOC, link fixes), and stringifies back. This keeps anchors and spacing lint-clean and idempotent.
+We run a deterministic Markdown normalizer (unified/remark) as a prebuild check. It parses Markdown to an AST, applies project transforms (link fixes, SPEC/TECH-SPEC linkification), and stringifies back. This keeps formatting/linting idempotent without touching anchors.
 
 Manual runs:
 
@@ -91,6 +91,26 @@ npm run docs:normalize          # write normalized Markdown
 npm run docs:normalize:check    # fail if normalization would change files
 ```
 
+#### Anchors & TOC vs normalize
+
+Two different tools touch documentation, with clear separation of concerns:
+
+- `scripts/anchors_and_toc.py` (Python):
+  - Sole owner of `<a id="…"></a>` anchors and AUTOGENERATED TOC blocks.
+  - Use when you change headings or want to regenerate anchors/TOCs:
+    - `python3 scripts/anchors_and_toc.py --write --paths docs/FEATURES.md`
+  - CI may run this on specific files before docs build.
+
+- `npm run docs:normalize` (Node/remark):
+  - Does **not** create or modify anchors/TOCs — it preserves whatever is in the Markdown.
+  - Only normalizes markdown syntax and fixes SPEC/TECH-SPEC links / relative paths.
+  - Safe to run frequently; it is idempotent by design.
+
+Rule of thumb:
+
+- If you edited headings/sections and need fresh anchors or TOC entries, run the Python anchor script.
+- For day-to-day changes (copy edits, extra paragraphs, examples), just run `npm run docs:normalize` and rely on the pre-push hook.
+
 Pre-push hook (opt-out flags; each step runs by default):
 
 - Set `PREPUSH_SKIP_DOCS=1` to skip the VitePress docs build.