Synthadoc

Installation

Choose one way to run Synthadoc:

Docker

Prerequisites: a container runtime only (Docker Engine or Desktop, Apple container, or wslc). No Python, pip, or synthadoc install on the host: every command, including creating the wiki, runs in a container.

For server deployments, team wikis, CI/CD pipelines, and isolated personal use, Synthadoc ships an OCI image, chenp/synthadoc, for linux/amd64 and linux/arm64. It works with Docker Engine and Docker Desktop, the Apple container tool (macOS 26+ Apple Silicon), and WSL Containers (wslc, Windows 11). One container serves one wiki. The HTTP API, Web UI (/app), and MCP over HTTP (/mcp) all share the wiki's port, and the wiki files stay on the host so Obsidian keeps working unchanged.

Commands are shown for Linux / macOS. On Windows, expand the Windows (Command Prompt) block for single-line cmd.exe versions: \ line continuation and ~ in -v paths don't work there. (In PowerShell, replace %USERPROFILE% with $env:USERPROFILE.)

1. Create the wiki in a one-off container. It lands in ~/wikis/history-of-computing; note the port it prints, e.g. 7070. docker run downloads the image on first use. Run docker pull chenp/synthadoc:latest later to update a cached image.

mkdir -p ~/wikis
docker run --rm -v ~/wikis:/wikis chenp/synthadoc:latest \
  synthadoc install history-of-computing --target /wikis --demo

<details> <summary>Windows (Command Prompt)</summary>

if not exist "%USERPROFILE%\wikis" mkdir "%USERPROFILE%\wikis"
docker run --rm -v "%USERPROFILE%\wikis:/wikis" chenp/synthadoc:latest synthadoc install history-of-computing --target /wikis --demo

</details>

2. Put your LLM API key in ~/wikis/.env, never on the command line. Create it with any text editor (Windows: notepad "%USERPROFILE%\wikis\.env"). For example, to use MiniMax:

```bash

Install a wiki and start the engine

A wiki is a self-contained knowledge base — a folder of Markdown pages maintained and cross-referenced automatically by Synthadoc. The fastest way to get started is the History of Computing demo (13 pre-built pages, no LLM API key required to browse).

```bash

1. Pick a template and install

Browse the 30 available templates across 9 categories and pick the one closest to your domain:

synthadoc templates list

Install with a template (example: consumer and competitive market research):

synthadoc install my-market-wiki --target ~/wikis --template research/market-research
synthadoc use my-market-wiki   # set as default — no -w needed from here on

If none of the 30 templates fits, install without one and provide a --domain description instead:

synthadoc install my-wiki --target ~/wikis --domain "Your domain description"

→ Full template catalog and per-category install commands: synthadoc/templates/README.md

Quick-Start Guide

The History of Computing demo includes 13 pre-built pages, raw source files covering clean-merge, contradiction, and orphan scenarios, and a full walkthrough of key Synthadoc feature.

Full step-by-step walkthrough: docs/user-quick-start-guide.md

The guide covers:

1. Verify the demo server started (banner, health check)
2. Install the Synthadoc plugin (auto-installs Dataview) and open the vault
3. Review wiki structure and key files (index, purpose, AGENTS.md, dashboard)
4. Query the pre-built wiki — including knowledge gap detection
5. Batch ingest all demo source files
6. Run lint — auto-promote clean pages to active
7. Manage page lifecycle — 5-state machine (draft → active → stale/contradicted/archived), manual transitions, immutable audit trail
8. Resolve a contradiction
9. Fix an orphan page
10. Run the adversarial lint pass — flag overstated claims across all pages
11. Web search ingestion with automatic decomposition
12. Ingest a YouTube video
13. Enrich the wiki with scaffold (regenerate/update index, purpose, AGENTS.md)
14. Audit features (token cost, history, events)
15. Schedule recurring operations
16. Set up query-scoped routing with ROUTING.md
17. Stage and review candidate pages before promoting them
18. Build a context pack for grounded LLM prompts
19. Verify claim provenance — source-line citations, broken citation audit, global provenance table
20. Export your wiki — llms.txt, llms-full.txt, GraphML wikilink graph, agent-ready JSON with provenance and lifecycle history, OKF v0.2 bundle for zero-code agent consumption
21. Use the web chat UI — streaming answers, session-aware hint chips, citations in-browser
22. Query caching — understand how answers are cached and how to bypass with --no-cache
23. Backup and restore — create a portable wiki zip, restore on a different machine
24. Knowledge graph — weighted edges (wikilink + co-source signals), explore clusters in the web UI Graph tab, click a node to query it
25. Ingest an AI session transcript — turn Claude Code, Codex, or chat conversations into structured wiki pages
26. Agentic maintenance workflows — eight conversational workflows via web UI or CLI: re-ingest stale pages (bulk or by slug), scan and fix broken wikilinks, run lint and view the full report, run scaffold and regenerate wiki files, resolve contradicted pages interactively (diff shown before every write, human approval required), resolve orphaned pages by inserting natural wikilinks into related content, fix broken source citation markers, detect and repair content quality issues (duplicate sections, thin/empty sections, broken markdown structure) with LLM-assisted analysis — agent confirms before touching anything, streams inline progress
27. Scan and retract sensitive data — dry-run to surface API keys, emails, SSNs, credit cards, and custom patterns; apply redactions with a single confirmation; incremental --changed-only mode for recurring runs; audit trail records pattern names only (never the values)

---

~/wikis/.env

MINIMAX_API_KEY=sk-...

optional — enables web search ingest

TAVILY_API_KEY=tvly-...

Keep comments on their own line; `--env-file` does not strip a trailing `# …` from a value.

Then select the **same provider** in `~/wikis/history-of-computing/.synthadoc/config.toml`. Under `[agents]`, comment out the active `default =` line and uncomment the matching one:

**3. Run the server in a container**, using the same port on both sides of `-p`:

<details>
<summary>Windows (Command Prompt)</summary>

</details>

**4. Use it.** Open the Web UI at `http://localhost:7070/app`, or run the CLI inside the container (same on every platform):

After editing config.toml, run docker restart history-of-computing. After changing .env, remove and re-create the container (docker rm -f history-of-computing, then step 3 again), because restart does not re-read .env.

See docs/docker-deploy.md for the full deployment guide: architecture, API key setup, platform-native runtimes, Docker Compose (single wiki, multi-wiki with cross-wiki queries, Ollama sidecar), CI/CD, file permissions, security, and maintenance.

Docker users: the rest of this Installation section (Development, Set your API keys with shell exports, and Install a wiki and start the engine) is for the pip install. With Docker, API keys go in the .env file, and any synthadoc … command elsewhere in this README runs as docker exec <container> synthadoc … (no -w needed).

---

2. Configure your LLM provider and start the server

Open ~/.wikis/my-market-wiki/.synthadoc/config.toml and set your LLM provider, then start:

synthadoc serve
synthadoc status   # should show 0 pages and the scheduled jobs registered

→ Provider list and API key setup: Quick-Start Guide — Appendix C

synthadoc install copies the Synthadoc and Dataview plugins into the vault and pre-enables them. Open the wiki folder in Obsidian — both plugins are active immediately. A local web UI is also available at http://localhost:{port}/app via synthadoc web.

Interfaces & Integration

Set your API keys

At least one LLM API key is required — unless you use Claude Code or Opencode as your provider (no separate API key needed — see Coding tool CLI providers).

Synthadoc defaults to Gemini Flash — free tier, no credit card, 1 million tokens per day. Get a key at aistudio.google.com/app/apikey (click "Create API key").

```bash