Living Documentation: Magic Docs vs Synapse vs Codex
Your documentation is outdated from the moment you write it. Three systems try to solve this. None succeeds alone. Together they'd be unbeatable.
Documentation dies the day after you write it. Every developer knows this. The README says "18 modules" but the code has 21. The API doc lists 80 endpoints but there are 95. The changelog hasn't been updated for three sprints.
This article closes our comparative series by analyzing how three CadencesLab systems attack the same problem from different angles:
Magic Docs
Claude Code — AI maintains files automatically
Synapse Docs
Architecture-as-Code — structured docs with manual audit
Codex Index
Embeddings + Vectorize — semantic search
And at the end we propose Magic Codex — a system combining all three to create documentation that writes, updates, audits, and indexes itself.
Magic Docs: AI That Maintains Your Docs
Claude Code has a brilliant concept: if a file starts with # MAGIC DOC: [Title], the AI maintains it automatically. When related code changes, a background agent updates the document.
🪄 How It Works
# MAGIC DOC: Authentication System ## Overview JWT-based auth with refresh tokens. Entry point: `src/auth/index.ts` ## Architecture - Login → verify → issue JWT (15min) + refresh (7d) - Middleware: `authGuard()` in every protected route - Token storage: httpOnly cookie ## Key Files - `src/auth/jwt.ts` — token generation - `src/auth/middleware.ts` — route guard - `src/auth/refresh.ts` — token renewal ─────────────────────────────────── Auto-maintained by Claude Code. Last updated when auth/ changed. Philosophy: "BE TERSE. High signal only. OVERVIEWS, ARCHITECTURE, ENTRY POINTS"
✓ Strengths
- 100% automatic (AI updates)
- Inline with code (same folder)
- Terse: essentials only, signal > noise
- Updates when code changes
✗ Weaknesses
- Only works with Claude Code
- No versioning (latest state only)
- No semantic search
- Low discoverability (must know it exists)
Architecture-as-Code: Structured Docs
Synapse Studio treats documentation as an engineering artifact: Markdown files versioned in Git, with predictable structure and auditable metrics.
📋 Synapse Documents
SYNAPSE_ARCHITECTURE.md
System metrics, modules, lines of code
SYNAPSE_CHANGELOG.md
Entries per version, documented changes
SYNAPSE_API.md
Endpoints documented, parameters, responses
SYNAPSE_AGENTS_GUIDE.md
Agent guide, capabilities, routing
🔍 The drift problem: In our last Synapse audit we discovered the docs said "18 modules" but the code had 21. Said "80+ endpoints" but there were 95. Said "~6,900 backend lines" but there were 8,562. Documentation drifts — always.
✓ Strengths
- Structured (predictable format)
- Versioned in Git (full history)
- Comprehensive (architecture + API + agents)
- Auditable (can verify against code)
✗ Weaknesses
- Manual (requires humans to update)
- Goes stale between audits
- No semantic search (just Ctrl+F)
- No automated updates
Semantic Indexing: Search Without Knowing
Codex doesn't generate docs — it indexes them. It takes existing content, generates embeddings with bge-m3 via Workers AI, and stores them in Vectorize for semantic search.
🔍 Indexing Pipeline
// Codex Indexing Pipeline index-codex-content.cjs ├── Scan: 38 articles (Astro) ├── Extract: sections, headings, paragraphs ├── Chunk: smart splitting (~500 tokens/chunk) ├── Embed: Workers AI (bge-m3) ├── Store: Vectorize index └── Result: 695 chunks searchable // Search flow User query → embed → nearest neighbors → ranked results "how does auth work?" → [auth.astro §3, security.astro §2, ...]
✓ Strengths
- Semantic search (no exact keywords needed)
- Scales well (695 → 10,000 chunks, no changes)
- Format-agnostic (HTML, MD, Astro…)
- Automatic re-indexing
✗ Weaknesses
- Doesn't generate docs (only searches existing)
- Doesn't update content (index ≠ update)
- Quality depends on source
- No versioning of its own
Comparison Table
| Aspect | Magic Docs | Synapse | Codex |
|---|---|---|---|
| Auto-generation | ✅ AI | ❌ manual | ❌ index only |
| Auto-update | ✅ on code change | ❌ needs audit | ✅ re-index |
| Semantic search | ❌ | ❌ | ✅ |
| Versioning | ❌ | ✅ Git | ❌ |
| Format | Free text (terse) | Structured Markdown | Chunks + embeddings |
| Accuracy | High (AI reads code) | Drifts | Depends on source |
| Discoverability | Low | Medium | High |
| Tooling | Claude Code | Git + manual | Workers AI + Vectorize |
Magic Docs generates. Synapse structures. Codex searches. None does all three. But together…
What Each Can Learn
Synapse ← Magic Docs
Add Magic Doc headers to existing docs
Convert SYNAPSE_ARCHITECTURE.md to # MAGIC DOC: Synapse Architecture. When Claude Code edits Synapse, docs update automatically.
Auto-audit CI pipeline
Instead of manual audits, a CI script counts modules, endpoints, lines → compares with docs → if drift >10% → automatic PR with corrections.
Claude Code ← Codex
Semantic index over Magic Docs
Index all Magic Docs with embeddings. Suddenly they're searchable: "how does authentication work?" → finds the auth Magic Doc without knowing it exists.
Cross-reference graph
Embeddings enable automatic related-doc discovery. Auth Magic Doc + Permissions Magic Doc → automatic link detected by vector proximity.
Magic Codex: The Ideal System
Combining all three approaches, a 4-layer system emerges that definitively solves the living documentation problem:
✨ Magic Codex — 4 Layers
Magic Doc Headers — AI generates and maintains inline documentation. Files with # MAGIC DOC: headers auto-update when code changes.
Structured Templates — Changelogs and architecture docs with predictable format. Versioned in Git. The skeleton stays stable — content auto-fills.
Semantic Indexing — Everything chunked and embedded in Vectorize. Smart search, automatic cross-references, similarity-based discovery.
CI/CD Integration — Audit pipeline detects drift. Auto-PR with corrections. Automatic re-indexing. Docs that audit themselves.
💡 The dream: documentation that writes itself (Magic Docs), structures itself (templates), searches itself (embeddings), audits itself (CI), and fixes itself (auto-PR). None of the three systems does it all — but together, it's possible.
Implementation Plan for CadencesLab
Add Magic Doc headers to Synapse docs
Immediate impact. 30 minutes of work. Docs auto-update every time Claude Code touches the code.
CI metrics audit script
1 week. Script counts modules, endpoints, lines and compares with ARCHITECTURE.md. Alerts if drift > 10%.
Extend Codex indexer for Magic Docs
2 weeks. The indexer already processes Astro — add support for .md with Magic Doc headers. Semantic search over technical docs.
Cross-reference graph with embeddings
1 month. For each doc, compute the N nearest docs by vector distance. Generate automatic "Related" links.
Auto-PR on detected drift
1 month. When the audit CI detects discrepancy, generate automatic PR with corrections. Human review before merge.
10 Articles, 1 Conclusion
This 10-article series — 6 deep-dives + 4 comparisons — has taken Claude Code apart piece by piece and compared it with our own systems. The conclusion?
It's not about who's better.
Claude Code is a brilliant consumer product built for individual developers. CadencesLab is a multi-tenant platform built for businesses. Different domains with different constraints.
But the patterns are transferable. The tri-state ACL, progressive compression, Magic Docs, sacred data pattern, coordinator with isolated workers — each of these concepts can improve what we build. And that's exactly what we'll do.
The best code isn't written — it's discovered by comparing how others solve the same problem in a different way.
Enjoyed the series?
At Cadences we build systems that learn from the best — including Claude Code. If you want to bring these patterns to your product, let's talk.
Gonzalo Monzón
Founder of CadencesLab. Builds Synapse, Codex, and NutriNen. Analyzed Claude Code to extract patterns that make our own systems better.