L2 Wiki Engine

How Synapse asynchronously generates and maintains markdown documentation for your codebase.

The L2 layer maintains human-readable markdown summaries of files and modules under .synap/wiki/. Generation is fully asynchronous — it never blocks CLI commands, MCP responses, or AST indexing.

Architecture

  File Parsed / Project Initialized
              │
              ▼
  wiki_queue table (SQLite)
  ┌─────────────────────────────────┐
  │ status=pending                  │
  │ path=src/auth/service.py        │
  │ attempts=0                      │
  └─────────────────────────────────┘
              │
              │  Background worker polls every 5s
              ▼
  ┌─────────────────────────────────┐
  │  Wiki Worker (_wiki_worker_loop)│
  │                                 │
  │  1. Pull pending job            │
  │  2. Read symbol context (L1)    │
  │  3. Call LLM provider           │
  │  4. Write .synap/wiki/<file>.md │
  │  5. Delete queue record         │
  └─────────────────────────────────┘
              │
              ▼
  .synap/wiki/src/auth/service.md
  ┌─────────────────────────────────┐
  │ # src/auth/service.py           │
  │ ## AuthService                  │
  │ Handles JWT issuance and        │
  │ verification for API sessions.  │
  │ ...                             │
  └─────────────────────────────────┘

Retry & Failure Handling

If an LLM call fails (rate limit, timeout, provider error):

| Attempt | Backoff Delay | |---|---| | 1st retry | 2 seconds | | 2nd retry | 4 seconds | | 3rd retry | 8 seconds | | After 3 failures | Marked status=failed, warning logged on next daemon start |

Failed wiki jobs do not block other queue items. They are retried on next daemon start.

Lazy On-Demand Generation

When an agent calls synap wiki show <file> or an MCP tool requests a wiki page that doesn't exist yet, Synapse runs synchronous generation (ensure_wiki_page) — blocking until the page is written to disk, then returning it.

Structural Mode (No LLM)

If no LLM provider is configured (synap init . --skip-llm), Synapse writes placeholder files:

# src/auth/service.py
Structural mode only. Configure an LLM provider with `synap setup` to generate documentation.

This ensures the MCP get_wiki tool always returns a response rather than erroring.

Wiki CLI Commands

# List all generated wiki pages
synap wiki list .

# View a specific wiki page in the terminal
synap wiki show src/auth/service.py .

LLM Providers for Wiki

Wiki generation uses the llm_provider and llm_model set during synap setup. Recommended providers:

| Provider | Model | Cost | |---|---|---| | Ollama (recommended) | qwen2.5-coder:14b | Free (local) | | OpenAI | gpt-4o-mini | ~$0.0015/page | | Anthropic | claude-3-haiku | ~$0.0025/page | | Gemini | gemini-2.0-flash-lite | ~$0.0005/page |

See LLM Providers for full setup instructions.