Magic Docs — Self-Maintaining Documentation

Automatically maintain documentation files marked with a special header. When a Magic Doc is encountered, update it with relevant new information discovered during the conversation.

Magic Doc Format

A Magic Doc is any markdown file whose first line matches:

# MAGIC DOC: <Title>

Optional second line (italics) provides update instructions:

# MAGIC DOC: Service Port Map
_Update whenever a new service, port, or domain is discovered_

Creating a New Magic Doc

When user asks to create a self-maintaining document:

1. Create the file with the MAGIC DOC header
2. Add optional instruction line in italics
3. Populate with current known information
4. Inform the user that this doc will be updated automatically when relevant information appears in conversation

Example:

# MAGIC DOC: Project Architecture
_Update when new services, dependencies, or architectural decisions are discovered_

## Services
- **OpenClaw Gateway**: port 18789, loopback
- **WeCom Bridge**: port 9000, loopback

## Dependencies
- Node.js v24
- Nginx (custom build at /usr/local/nginx)

---
*Last updated: 2026-03-31 by magic-docs*

Updating a Magic Doc

When new information relevant to a Magic Doc is discovered during a conversation:

Detection

• The document was read earlier in the conversation
• New facts related to its topic were discovered (new port, new service, config change, etc.)

Update Process

1. Read the current Magic Doc content
2. Identify new information from the conversation that belongs in the document
3. Determine where it fits in the existing structure
4. Apply the update using file edit (preserve existing structure)
5. Update the "Last updated" timestamp at the bottom

Update Rules

• Only add information that was verified during the conversation (not guessed)
• Preserve existing entries unless they are confirmed outdated
• If an existing entry is outdated, update it and note the change
• Add a "Last updated" line at the bottom: *Last updated: YYYY-MM-DD by magic-docs*
• Do not reorganize the entire document — make minimal, targeted edits
• If the document grows beyond 200 lines, suggest splitting into sections with references

Good Candidates for Magic Docs

Not Good Candidates

• Files that change via git commits (the source of truth is git, not conversation)
• Files with strict formatting requirements (generated configs, JSON, YAML)
• Temporary notes (use session-summary instead)