tesseract-ripple/docs-protocol

Documentation Auto-Update Protocol

Reference for keeping ~/claude-projects/docs/ in sync with config reality.

Docs files and their triggers

1. File edits — editing a config file or script in a monitored path

| Docs file | Triggered by file edits in... | |---|---| | claude-setup.md | ~/.claude/ structure, settings.json, agents, skills, MCP servers, ~/claude-projects/ directory tree | | latex-setup.md | LaTeX toolchain, VS Code LaTeX extensions, .latexmkrc, bib tools | | terminal-setup.md | ~/.config/kitty/, ~/.config/tmux/, ~/.claude/keybindings.json, fish config, readline | | claude-usage-widget.md | ~/claude-projects/claude-usage/, SwiftBar plugin, ~/.claude/usage-*.json |

2. Policy/convention changes — rules in CLAUDE.md that affect a documented domain

| Docs file | Also triggered by policy changes about... | |---|---| | latex-setup.md | LaTeX compilation policies, document conventions, formatting rules, package usage guidelines | | terminal-setup.md | Shell conventions, keybinding policies, tmux workflow rules | | claude-setup.md | Hook behavior policies, memory system rules, subagent model selection rules, cost guidelines |

A policy change is anything in CLAUDE.md that a reader of the corresponding docs file would want to know.

If you edit a config file or add a policy not covered above, create a new file under docs/ and add a row to the relevant table.

Structural changes (not just file edits)

Doc updates are also triggered by structural changes that don't involve editing existing files:

• Creating new directories under ~/.claude/ or ~/claude-projects/ (e.g., git clone, mkdir)
• Adding/removing scripts, agents, or skills
• Creating/deleting symlinks
• Changes to MCP server configuration

These happen via Bash, not Edit/Write. The PostToolUse hook on Bash catches structural commands (mkdir, cp, mv, git clone) in monitored paths.

claude-setup.md scope

Update when you add, remove, or change:

• Workflows or automation (memory system, EOD agents, etc.)
• Skills or slash commands
• Subagents
• Settings (permissions, hooks, model defaults)
• Directory structure under ~/.claude/ or ~/claude-projects/
• MCP server configuration

Do not put user artifact documentation (LaTeX setups, paper notes, tool configs) in claude-setup.md. That content belongs in its own file under docs/.

General rules

• Use targeted edits — do not rewrite whole files.
• Count docs updates toward the session memory-write budget (≤2 edits per file per session).
• Do not update docs for trivial changes (typo fixes, minor reformatting).