10-Auto-Documentation

📝

After every completed run, documentation is updated automatically inside marker blocks. Manual content outside markers is preserved.

1. Service

App\Services\Docs\DocumentationAutoUpdateService

Responsibilities:

run after final_summary

decide which docs are affected by the run's changes

regenerate auto-blocks in those docs

write a documentation_updates row per file changed

append a CHANGELOG_AI.md entry

mirror updated PROJECT_CONTEXT / PROJECT_MAP / DATABASE_SCHEMA into .claude/

emit docs_updated events

2. Marker convention

<!-- AUTO-GENERATED:START -->
...content owned by the agent...
<!-- AUTO-GENERATED:END -->

The agent only replaces content between markers. Markers missing? The service inserts them at the section's end with a one-time migration that asks the user via waiting_for_user if a doc has both manual content and auto blocks colliding.

3. Documents in scope

Path	What goes inside auto blocks
`docs/PROJECT_CONTEXT.md`	One-paragraph project pitch + stack + top entry points.
`docs/PROJECT_MAP.md`	The route↔controller↔model↔table table (see `16` template).
`docs/DATABASE_SCHEMA.md`	Tables, columns, indexes, FKs, model relations.
`docs/ARCHITECTURE_DIAGRAMS.md`	Mermaid diagrams (system, run lifecycle, RAG, file change, Git, iPhone, DB).
`docs/API_ENDPOINTS.md`	List of HTTP endpoints (verb, path, auth, summary).
`docs/RAG_SYSTEM.md`	Brief on indexing, retrieval, source types.
`docs/AGENT_WORKFLOW.md`	The orchestrator's state diagram and step list.
`docs/CLAUDE_CODE_INTEGRATION.md`	Tool list, allowed/blocked, safe mode behavior.
`docs/OPENAI_INTEGRATION.md`	Config keys + cost tracking.
`docs/SERVER_PARAMS.md`	Auto-table of every server param (secret values never rendered).
`docs/GIT_WORKFLOW.md`	Branch naming, push gating, rollback.
`docs/IPHONE_APP_PLAN.md`	Screen list + API endpoints used per screen.
`docs/SECURITY.md`	Threat model summary, allowlist/blocklist links.
`docs/CHANGELOG_AI.md`	Append-only entries per run (see §6).
`.cursor/rules/project-overview.mdc`	Mirror of PROJECT_CONTEXT highlights.
`.claude/PROJECT_CONTEXT.md`	Mirror of PROJECT_CONTEXT.md.
`.claude/RULES.md`	Synced from canonical rules.

4. Affected-doc detection

For each changed file in the run, a small ruleset maps to docs:

Change	Triggers update of
`routes/*.php`	PROJECT_MAP.md, API_ENDPOINTS.md, ARCHITECTURE_DIAGRAMS.md
`app/Http/Controllers/**`	PROJECT_MAP.md, API_ENDPOINTS.md
`app/Models/**`	DATABASE_SCHEMA.md, PROJECT_MAP.md
`database/migrations/**`	DATABASE_SCHEMA.md, PROJECT_MAP.md, ARCHITECTURE_DIAGRAMS.md (ER)
`app/Services/**`	PROJECT_MAP.md
`config/**`	PROJECT_CONTEXT.md, SERVER_PARAMS.md (if `agent_workspace.php`)
`.cursor/rules/**`	Cursor mirror only
`.claude/**`	Claude mirror only
`ios/**`	IPHONE_APP_PLAN.md
any	CHANGELOG_AI.md

5. Generation pipeline

flowchart LR
	A["final_summary event"] --> B["collect file changes"]
	B --> C["map to docs"]
	C --> D["regenerate auto-blocks"]
	D --> E["write files"]
	E --> F["documentation_updates rows"]
	F --> G["emit docs_updated"]
	G --> H["append CHANGELOG_AI.md"]
	H --> I["mirror to .claude/ and .cursor/"]

6. `CHANGELOG_AI.md` entry format

## 2026-05-11 · Run #148 — "Add /api/invoices endpoint"

- **Changed files**: app/Http/Controllers/Api/InvoiceController.php, app/Models/Invoice.php, database/migrations/2026_05_11_120000_create_invoices_table.php, routes/api.php, tests/Feature/InvoiceTest.php
- **Affected routes/controllers/models**: GET/POST /api/invoices → InvoiceController → Invoice → invoices
- **Database changes**: new table `invoices` (8 columns, 2 indexes)
- **API changes**: 2 new endpoints (GET, POST /api/invoices)
- **Known risks**: invoice PDF generator not yet implemented; placeholder used.
- **Tests done**: 6 added, 0 failed.
- **Snapshots**: pre_run #s-901, final #s-905

7. Safety

The service never overwrites content outside  markers.

It commits doc changes only when safety.auto_git_commit=true and only on the run's branch. By default docs are updated in the working tree and shown in the diff.

Secret values are stripped via SecretRedactionProcessor before write.

Generated diagrams are validated as Mermaid before write (mmdc --validate if available, regex fallback).

8. Performance

Doc updates run in the docs queue (Horizon supervisor) to avoid blocking the orchestrator.

Per-doc operations are idempotent: re-running produces byte-identical output for unchanged inputs.

9. Cursor / Claude mirror

A dedicated DocsMirrorService copies and trims the canonical docs into:

.cursor/rules/project-overview.mdc (PROJECT_CONTEXT compressed + key rules)

.claude/PROJECT_CONTEXT.md (full mirror inside auto-blocks)

.claude/RULES.md (canonical rules)

.claude/TOOLS.md (regenerated from server params allowlist/blocklist)

.claude/WORKFLOW.md (canonical workflow)