Update Docs
Ensures documentation stays in sync with code changes. Run before or during every PR that touches library code.
Before anything else
- Read CLAUDE.md — understand tier boundaries (core vs ee/), dropped features, and session model
- Read .docs-style-guide.md — binding terminology reference
Step 1: Detect what changed
git diff main...HEAD --name-only
Map changes to affected docs:
| Source file |
Affected doc pages |
src/edictum/pipeline.py, contracts.py |
concepts/how-it-works.md, architecture.md |
src/edictum/yaml_engine/ |
contracts/yaml-reference.md, contracts/operators.md |
src/edictum/adapters/*.py |
corresponding adapters/*.md page |
src/edictum/session.py, limits.py |
concepts/contracts.md, architecture.md |
src/edictum/audit.py, telemetry.py |
audit/sinks.md, audit/telemetry.md |
src/edictum/cli/ |
cli.md |
src/edictum/envelope.py |
concepts/principals.md, architecture.md |
pyproject.toml (version) |
install commands across docs |
src/edictum/__init__.py (API) |
quickstart.md, all adapter pages |
If no library code changed (docs-only PR), skip to Step 4.
Step 2: Read the changed code
For each changed file:
- Read the file and the diff (
git diff main...HEAD -- <file>)
- Identify: new public APIs, changed signatures, new classes, removed exports, changed behavior
Step 3: Update affected docs
For each affected page:
- Read the current doc
- Skip if already correct
- Update code examples, descriptions, YAML examples
- Verify terminology against .docs-style-guide.md:
- "contracts" not "policies" or "rules"
- "denied" not "blocked"
- "enforces" not "governs"
- "pipeline" not "engine"
- "tool call" not "function call"
- "adapter" not "integration" or "plugin"
- "observe mode" not "shadow mode"
- "finding" / "findings" not "alert"
- Verify tier boundaries against CLAUDE.md:
- FileAuditSink is core (not ee/)
- StdoutAuditSink is core
- Webhook/Splunk/Datadog sinks are ee/
- PIIDetector protocol is core, implementations are ee/
- MemoryBackend is the only StorageBackend (no Redis/DB)
- No references to dropped features
Step 4: Update README if needed
If public API, install extras, framework support, or version changed:
- Read README.md
- Update affected sections
- Ensure README matches docs/index.md positioning
Step 5: Verify the build
python -m mkdocs build --strict 2>&1
Fix any broken links, missing pages, or YAML errors.
Step 6: Report
Summarize:
- Which code files changed
- Which doc pages were updated (and what changed)
- Which doc pages were checked but needed no changes
- Build verification result
Rules
- Don't rewrite for the sake of rewriting. Only update what the code change actually affects.
- Don't add features that don't exist. If code was added but not released, note it as unreleased.
- Don't reference dropped features. No Redis/DB StorageBackend, no reset_session().
- Preserve the voice. Match existing style — problem first, short paragraphs, code examples.
- Check cross-links. Verify links in updated pages still work.
- README and homepage must stay aligned. If you update one, check the other.
1---2name: update-docs-53description: Sync documentation with code changes. Use on every PR that touches library code to keep docs accurate and consistent.4---5
6# Update Docs
7
8Ensures documentation stays in sync with code changes. Run before or during every PR that touches library code.
9
10## Before anything else
11
121. **Read CLAUDE.md** — understand tier boundaries (core vs ee/), dropped features, and session model
132. **Read .docs-style-guide.md** — binding terminology reference
14
15## Step 1: Detect what changed
16
17```bash
18git diff main...HEAD --name-only
19```
20
21Map changes to affected docs:
22
23| Source file | Affected doc pages |
24|---|---|
25| `src/edictum/pipeline.py`, `contracts.py` | concepts/how-it-works.md, architecture.md |
26| `src/edictum/yaml_engine/` | contracts/yaml-reference.md, contracts/operators.md |
27| `src/edictum/adapters/*.py` | corresponding adapters/*.md page |
28| `src/edictum/session.py`, `limits.py` | concepts/contracts.md, architecture.md |
29| `src/edictum/audit.py`, `telemetry.py` | audit/sinks.md, audit/telemetry.md |
30| `src/edictum/cli/` | cli.md |
31| `src/edictum/envelope.py` | concepts/principals.md, architecture.md |
32| `pyproject.toml` (version) | install commands across docs |
33| `src/edictum/__init__.py` (API) | quickstart.md, all adapter pages |
34
35If no library code changed (docs-only PR), skip to Step 4.
36
37## Step 2: Read the changed code
38
39For each changed file:
401. Read the file and the diff (`git diff main...HEAD -- <file>`)
412. Identify: new public APIs, changed signatures, new classes, removed exports, changed behavior
42
43## Step 3: Update affected docs
44
45For each affected page:
461. Read the current doc
472. Skip if already correct
483. Update code examples, descriptions, YAML examples
494. **Verify terminology** against .docs-style-guide.md:
50 - "contracts" not "policies" or "rules"
51 - "denied" not "blocked"
52 - "enforces" not "governs"
53 - "pipeline" not "engine"
54 - "tool call" not "function call"
55 - "adapter" not "integration" or "plugin"
56 - "observe mode" not "shadow mode"
57 - "finding" / "findings" not "alert"
585. **Verify tier boundaries** against CLAUDE.md:
59 - FileAuditSink is core (not ee/)
60 - StdoutAuditSink is core
61 - Webhook/Splunk/Datadog sinks are ee/
62 - PIIDetector protocol is core, implementations are ee/
63 - MemoryBackend is the only StorageBackend (no Redis/DB)
64 - No references to dropped features
65
66## Step 4: Update README if needed
67
68If public API, install extras, framework support, or version changed:
691. Read README.md
702. Update affected sections
713. Ensure README matches docs/index.md positioning
72
73## Step 5: Verify the build
74
75```bash
76python -m mkdocs build --strict 2>&1
77```
78
79Fix any broken links, missing pages, or YAML errors.
80
81## Step 6: Report
82
83Summarize:
84- Which code files changed
85- Which doc pages were updated (and what changed)
86- Which doc pages were checked but needed no changes
87- Build verification result
88
89## Rules
90
91- **Don't rewrite for the sake of rewriting.** Only update what the code change actually affects.
92- **Don't add features that don't exist.** If code was added but not released, note it as unreleased.
93- **Don't reference dropped features.** No Redis/DB StorageBackend, no reset_session().
94- **Preserve the voice.** Match existing style — problem first, short paragraphs, code examples.
95- **Check cross-links.** Verify links in updated pages still work.
96- **README and homepage must stay aligned.** If you update one, check the other.
majiayu000