synthadoc

Synthadoc

      .-+###############+-.
    .##                   ##.
   ##    .----.   .----.    ##
  ##    /######\ /######\    ##
  ##    |######| |######|    ##
  ##    | [SD] | | wiki |    ##
  ##    |######| |######|    ##
  ##    \######/ \######/    ##
   ##    '----'   '----'    ##
    '##                   ##'
      '-+###############+-'

       S Y N T H A D O C
    Community Edition  v1.5.1
  ────────────────────────────────
  Domain-agnostic LLM wiki engine

Document version: v1.5.1

Engineered for solo users and enterprises alike, providing a domain-specific knowledge base that scales seamlessly while maintaining accuracy through autonomous self-optimization.

Built for individuals, small teams, and large organizations who need a knowledge base that stays accurate as documents accumulate.

Documentation, FAQ and articles: https://axoviq.com/resources/synthadoc

Synthadoc reads your raw source documents — PDFs, spreadsheets, PPTs, web pages, images, videos, Word files, TXTs, and AI session transcripts (.jsonl) — and uses an LLM to synthesize them into a persistent, structured wiki. Cross-references are built automatically, contradictions are detected and surfaced, orphan pages are flagged, and every answer cites its sources. Outputs are stored as local Markdown files, ensuring seamless integration and autonomous management within Obsidian or any wiki-compliant ecosystem.

---

---

Table of Contents

• Who Is It For?
• Inspiration and Vision
• Problems Addressed
• Why Synthadoc?
• Architecture
• What's Included
• Installation
• Quick-Start Guide
• Creating Your Own Wiki
• Configuration
• Command Reference by Use Case
• Administrative Reference
• Understanding Logs and the Audit Trail
• Customization
• Links

---

Who Is It For?

Synthadoc scales from a single researcher to a company-wide knowledge platform:

Team size	Typical use case
Solo / 1–2 people	Personal research wiki, freelance knowledge base, indie hacker documentation - run it free on Gemini Flash or a local Ollama model with zero ongoing cost
Small team (3–20)	Centralized internal knowledge base for startups and departments that aggregates diverse individual data sources into a unified, high-integrity wiki. The system automatically resolves contradictions and scales autonomously, ensuring organizational intelligence grows in tandem with your team
Medium / enterprise	Compliance-sensitive knowledge bases that must stay local; per-department wikis on separate ports; audit trail for every ingest and cost event; hook system for CI/CD integration; OpenTelemetry for ops dashboards

Built for large wikis. Measured on wikis of thousands of pages: keyword search finds the pages for an answer in about 20 ms at 2,000 pages; semantic search, on by default for new wikis when installed, puts the right page in the top 5 for 70% of questions asked in your own words, up from 48%; and the knowledge graph opens a 5,000-page wiki as a clickable overview of named topic clusters in about 6 seconds.

The web UI's Graph tab on a 5,000-page test wiki: 100,801 links summarised as 24 named clusters. Click a cluster to see its pages. How it works

No cloud account. No vendor lock-in. The wiki is plain Markdown — open it in any editor, back it up with git, sync it with any cloud drive.

---

Inspiration and Vision

"The LLM should be able to maintain a wiki for you." — Andrej Karpathy, LLM Wiki gist

Most knowledge-management tools retrieve and summarize at query time. Synthadoc inverts this: it compiles knowledge at ingest time. Every new source enriches and cross-links the entire corpus, not just appends a new chunk. The wiki is the artifact — readable, editable, and browsable without any tool running.

Long-term alignment:

Direction	How Synthadoc moves there
Agent orchestration	Orchestrator dispatches parallel ingest, query, and lint sub-agents with cost guards and retry backoff
Sub-agent skills/plugins	Featuring a 3-tier lazy-load capability system, the platform allows for the injection of custom skills and hooks via a plug-and-play interface, ensuring core stability is never compromised during extension
LLM wiki vs. RAG	Pre-compiled structured knowledge beats query-time synthesis for contradiction detection, graph traversal, and offline access
CLI / HTTP	A unified interface via CLI and RESTful endpoints, the system streamlines full-spectrum integration: from data ingestion and querying to automated linting, security auditing, and job orchestration
Local-first	All data stays on your machine; localhost-only network binding; no cloud dependency except the LLM API itself
Provider choice	LLM backends including free-tier Gemini and Groq, paid Anthropic/OpenAI/DeepSeek/MiniMax/Qwen (DashScope), local Ollama and Qwen, and coding-tool CLI providers (Claude Code, Opencode) — no API key required if you already have a subscription

---

Problems Addressed

RAG retrieves document chunks at query time. Synthadoc compiles knowledge at ingest — synthesising sources into a linked, audited wiki graph so contradictions are caught, claims are traced to sources, and the artifact survives outside the tool.

Problem	Synthadoc approach
Contradictions blended silently	Ingest-time conflict detection; page flaggedstatus: contradicted; auto-resolve or queue for human review
No links between related content	[[wikilinks]] auto-built on every ingest pass; weighted graph (wikilink + co-source signals) with Louvain clustering in web UI
Orphan pages never surfaced	Lint reports unreferenced pages with ready-to-paste index entries
LLM output can be overconfident	Adversarial second-LLM pass flags overstated claims, unsupported superlatives, and contestable facts per page
Claims lack source traceability	^[file:L-L] citation on every claim; Source Viewer in Obsidian; PDF page resolution; broken-citation lint
Knowledge lifecycle invisible	5-state machine (draft → active → contradicted / stale → archived); auto-transitions via lint; immutable event log
Repeat ingest is expensive	3-layer cache (embedding, LLM, provider prompt) — repeat lint on unchanged pages costs near-zero tokens
Knowledge locked in proprietary tools	Plain Markdown + YAML frontmatter; OKF v0.2 compatible; fully offline-readable in any editor
Wiki structure drifts with growth	scaffold regenerates index, AGENTS.md, and purpose.md from current wiki state without touching linked pages
Migration requires full re-ingestion	Single-zip backup + restore with port/domain rewriting; no re-ingestion needed
Cost and compliance exposure	Localhost-only; per-job token+cost log; configurable soft-warn and hard-gate thresholds

Citation quality: Generated pages include inline citations linking every claim to its source lines. Pages without citations trigger a model-compatibility warning — use Gemini 2.5 Flash or higher for reliable citation annotation.

Active page protection: Pages promoted to active status are protected — sources that contradict them are flagged for review rather than overwriting the human-reviewed content.

---

Why Synthadoc?

Every Yes below is a built-in feature — no add-ons or upgrades required.

Knowledge Quality

Capability	Synthadoc	Typical RAG	NotebookLM	Notion AI
Ingest-time synthesis — sources compiled into the wiki at ingest; not re-summarised at query time	Yes	No	Partial	No
Contradiction detection & resolution — conflicting claims flagged status: contradicted; auto-resolve available; full conflict history	Yes	No	No	No
Adversarial claim review + gate — concurrent second-LLM pass flags overstated claims, unsupported superlatives, and contestable facts per page; configurable gate auto-demotes pages that exceed the warning threshold to contradicted	Yes	No	No	No
Claim-level provenance — ^[file:L-L] citation on every claim; Source Viewer in Obsidian; PDF page resolution; broken-citation lint	Yes	No	Partial	No
5-state lifecycle machine — draft → active → contradicted / stale → archived; auto-transitions via lint; immutable event log; cascade link cleanup on archive; only active and stale pages enter the BM25 search index	Yes	No	No	No
Pre-LLM source sanitizer — strips zero-width chars, bidi overrides, hidden HTML, and instruction-override phrases before any LLM call	Yes	No	No	No

Knowledge Structure

Capability	Synthadoc	Typical RAG	NotebookLM	Notion AI
Weighted knowledge graph + D3 visualisation — [[wikilinks]] auto-built at ingest; co-source edges connect pages compiled from the same document; edge thickness reflects combined weight; dashed edges for co-source-only relationships; Louvain cluster colouring; click node to query; scales to thousands of pages — wikis over 300 pages open on a cluster overview (named clusters, click to drill in), 5,000 pages in ~6 s at 60 fps; Obsidian graph panel: same graph inside Obsidian via Canvas, type filter, click node to open page	Yes	No	Partial	No
Orphan page detection — unreferenced pages surfaced by lint with ready-to-paste index entries	Yes	No	No	No
Query-scoped routing — ROUTING.md maps wiki branches to page slugs; queries auto-select relevant branches; new pages auto-slotted	Yes	No	No	No
Candidates staging — ingest pages to a staging area first; review, promote, or discard before they enter the live wiki	Yes	No	No	No
Scaffold automation — regenerates index categories, AGENTS.md/CLAUDE.md/GEMINI.md, and purpose.md from current wiki state; protected pages never overwritten	Yes	No	No	No
Domain templates — 30 fully-authored templates (finance, technology, healthcare, legal, and more) so you start with the right agent guidelines, routing, and structure from day one	Yes	No	No	No

Search & Query

Capability	Synthadoc	Typical RAG	NotebookLM	Notion AI
Query decomposition + gap detection — compound questions split into parallel BM25 sub-queries; thin results trigger a knowledge-gap callout with suggested web searches	Yes	Partial	No	No
BM25 TF fallback + compound identifier search — reliable results on small corpora (IDF collapse → TF fallback); underscore identifiers expanded at index and query time so capex growth matches capex_growth	Yes	No	No	No
Web search → wiki pages — Tavily search fans out into parallel URL ingest jobs; gap callout in web UI suggests searches inline	Yes	No	No	No
Semantic search — on by default for new wikis when installed (pip install "synthadoc[vectors]", built into the Docker image): BM25 fused with local embeddings (BAAI/bge-small-en-v1.5); Chinese/Japanese/Korean text stays on keyword search; finds pages asked about in your own words, keeps exact-name precision (benchmark)	Yes (optional)	Varies	No	No
Streaming output + query cache — token-by-token streaming; cache key = question + wiki version; auto-invalidates on ingest or lifecycle change	Yes	Partial	Partial	Partial
Proportional context budget — sources allocated proportionally to model context window (60 % wiki / 20 % history / 15 % system / 5 % index); replaces fixed top-N cap	Yes	No	No	No
Cross-wiki federation — synthadoc query --cross-wiki fans out a single query across all registered running wikis; LLM auto-routes to relevant wikis; [[wiki-name::PageTitle]] citation pills; amber offline banner when a target wiki is unreachable; graceful degradation when wikis are offline	Yes	No	No	No

Interfaces & Integration

Capability	Synthadoc	Typical RAG	NotebookLM	Notion AI
Obsidian integration — native plugin: ingest modal, streaming query, lint report, lifecycle controls, context pack builder, provenance viewer, export modal, knowledge graph panel (Canvas force graph, type filter, hover tooltip, click-to-open page); background vault monitoring (auto-snapshot on every file save, 2 s debounce, dedup so unchanged saves are free); Reading View set as default on install so citation chips are visible immediately	Yes	No	No	No
Web chat UI — synthadoc web: streaming answers, session sidebar, multi-turn history, knowledge-gap callouts, knowledge graph tab, light/dark/system theme toggle	Yes	No	Yes	Yes
MCP server — 12 tools; Claude Desktop (stdio), Claude Code (SSE), n8n/LangGraph (HTTP/SSE); brain+memory architecture; no double-LLM cost for reads	Yes	No	No	No
Context packs — goal → sub-questions → token-budget evidence pack; REST + MCP callable; paste into any LLM chat as grounded context	Yes	No	No	No
Export formats — llms.txt, llms-full.txt, GraphML, JSON (provenance + lifecycle), OKF v0.2 bundle; lifecycle-filtered; zero extra LLM calls	Yes	No	Partial	No
Multi-platform agent skill files — AGENTS.md (Codex/OpenCode), CLAUDE.md (Claude Code), GEMINI.md (Gemini CLI); all include full CLI quick-reference, domain guidelines, MCP tool table; regenerated by scaffold	Yes	No	No	No

Content Sources

Capability	Synthadoc	Typical RAG	NotebookLM	Notion AI
Multi-format ingest — PDF, DOCX, PPTX, XLSX/CSV, Markdown, TXT, images (vision), web URLs, YouTube transcripts, AI session transcripts (.jsonl)	Yes	Varies	Partial	Partial
Web search decomposition — broad topics decomposed into focused Tavily keyword searches; results merged and deduplicated	Yes	No	No	Partial
YouTube transcript ingest — timestamped transcript + executive summary; no API key; auto-generated captions supported	Yes	No	Yes	No
Multilingual / CJK queries — Chinese, Japanese, Korean — no false knowledge gaps	Yes	Limited	No	No
Multiple LLM providers + coding tools — Gemini, Groq, Qwen, MiniMax, DeepSeek, Anthropic, OpenAI, Ollama, Kimi; Claude Code and Opencode (no API key needed)	Yes	No	No	No

Operations & Trust

Capability	Synthadoc	Typical RAG	NotebookLM	Notion AI
Local-first + offline artifact — source documents never leave your machine; compiled wiki is plain Markdown, fully readable offline in any editor without the server	Yes	Varies	No	No
Portable backup / restore — single zip: wiki pages + audit/lifecycle DB + config; port and domain rewriting on restore; migrate machines without re-ingesting	Yes	No — re-ingest required	No — AI metadata lost	No
Lifecycle content snapshots + rollback — page body captured at every lifecycle transition (manual CLI/Obsidian, lint-driven auto-transition, or Obsidian vault save); deduplicated so unchanged saves cost nothing; browse per-page version history with lifecycle history (newest-first, with reason); restore any prior version with lifecycle rollback; rollback saves the current body first so it is always undoable	Yes	No	No	Partial — Notion has time-based edit history (plan-gated, no lifecycle tie, no auditable rollback)
Cost guard + full audit trail — per-job token + cost log; soft-warn and hard-gate thresholds; audit citations validates every claim citation; immutable event log	Yes	No	No	No
Citation faithfulness audit — on-demand LLM verification that each claim's text is actually supported by its cited source lines; per-page result cache with staleness detection; findings surfaced in the Obsidian source viewer	Yes	No	No	No
Resumable job queue + retry — every ingest/lint job persisted with status and error; batch a hundred documents and resume after a crash	Yes	No	No	No
Custom skills + CI hooks — subclass BaseSkill for new file formats; 2 hook events (on_ingest_complete + on_lint_complete); example git auto-commit hook included; blocking hooks can gate operations	Yes	Limited	No	No
Per-source truncation flag — --max-source-chars caps any source (PDF, DOCX, web page, plain text) before the LLM call; truncated sources flagged with truncated: true in frontmatter and warned in lint output	Yes	No	No	No
Docker deployment — official chenp/synthadoc image (amd64 + arm64); one container per wiki with HTTP API, Web UI, and MCP on one port; Compose recipes for multi-wiki cross-wiki queries and an Ollama sidecar; non-root, secrets via --env-file only	Yes	Varies — usually DIY	No	No
Multi-wiki isolation — each wiki on its own port with independent config, audit trail, and job queue; switch with synthadoc use	Yes	No	Partial	No
Agentic maintenance workflows — nine conversational workflows (stale-page re-ingest, broken wikilinks fix, lint report, scaffold regeneration, contradiction resolver, orphan resolver, broken citation resolver, content health resolver) via web UI or synthadoc workflow CLI; confirm-before-act gate on all writes; graph sidebar chips trigger workflows with one click	Yes	No	No	No
Sensitive Data Retract — scan all wiki pages for API keys, emails, SSNs, credit cards, and custom patterns; apply [REDACTED] in place; background scan is incremental (only pages modified since the last cycle are checked); server auto-scans ingested pages immediately after each ingest job completes; --changed-only CLI flag for incremental manual runs; synthadoc retract status captures the full retraction audit trail (slug, pattern names, counts — never the sensitive values themselves)	Yes	No	No	No

Business value

Value	How
Faster onboarding	New team members query the wiki instead of digging through documents
Audit trail	Every ingest recorded inaudit.db with source hash, token count, and timestamp
Cost control	Configurable thresholds; 3-layer cache reduces repeat spend
Compliance	Local-first — source documents and compiled knowledge never leave your machine
Extensibility	Hooks fire on every event; custom skills load without a server restart

---

Architecture

For full architecture details, data models, API reference, and plugin development guide see docs/design.md.

---

What's Included

See docs/design.md — Appendix A: Release Feature Index for a full feature list by version.

---

Installation

Choose one way to run Synthadoc:

	Install with pip	Run with Docker
Host requirements	Python 3.11+	A container runtime only, with no Python or pip on the host
Best for	Personal use on one machine	Team or shared servers, CI/CD, isolated or reproducible runtimes
Steps	Production, then Set your API keys and Install a wiki and start the engine	Docker below, then the Docker Deployment Guide

Production

Prerequisites: Python 3.11+. No Node.js, no Git, no build steps.

pip install "synthadoc[vectors]"   # recommended — includes semantic search
pip install synthadoc              # lightweight install, no semantic search
synthadoc --version                # confirm it works

The Obsidian plugin is bundled inside the package. New wikis created with synthadoc install have it installed automatically. If you are upgrading an existing Synthadoc installation, run synthadoc plugin upgrade to push the updated plugin binary to all registered wikis.

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

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

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:

# ~/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:

[agents]
default = { provider = "minimax", model = "MiniMax-M3", thinking = "disabled" }

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

docker run -d --name history-of-computing \
  -v ~/wikis/history-of-computing:/wiki \
  -p 7070:7070 \
  --env-file ~/wikis/.env \
  chenp/synthadoc:latest

docker run -d --name history-of-computing -v "%USERPROFILE%\wikis\history-of-computing:/wiki" -p 7070:7070 --env-file "%USERPROFILE%\wikis\.env" chenp/synthadoc:latest

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

docker exec history-of-computing synthadoc query "Who was Alan Turing?"
docker exec history-of-computing synthadoc lint run --wait

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).

---

Development

For developers modifying the Python engine, running the test suite, or developing the Obsidian plugin TypeScript.

Additional prerequisites: Git (any). Node.js 18+ only if modifying the plugin TypeScript source.

Step 1 — Clone and install

git clone https://github.com/axoviq-ai/synthadoc.git
cd synthadoc
pip install -e ".[dev]"

[dev] adds pytest, respx, and the other test dependencies. Tests require a source checkout — they are not included in the pip wheel.

Step 2 — Run the test suite

pytest --ignore=tests/performance/ -q

Expected: all tests pass, 0 failures. Performance benchmarks (optional):

pytest tests/performance/ -v --benchmark-disable

Step 3 — Obsidian plugin development (optional)

The compiled plugin is bundled with the package and kept up to date by CI — no build step is needed to work on the Python side or run tests.

If you modify the TypeScript source under obsidian-plugin/src/, recompile and sync it into the Python package manually:

cd obsidian-plugin
npm install           # first time only, or after package.json changes
# edit src/main.ts or other source files
npm run build         # compile TypeScript → main.js (also syncs to synthadoc/data/obsidian-plugin/)
npm test              # run Vitest unit tests
cd ..

---

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").

Provider	Free tier	Vision	Get key
Gemini Flash	Yes — 15 RPM / 1M tokens/day, no credit card	Yes	aistudio.google.com
Groq	Yes — rate-limited	No	console.groq.com
Ollama	Yes — runs locally, no key (GPU required)	Model-dependent	ollama.com
Qwen	Yes — 1M free tokens (90-day trial), then paid DashScope	Model-dependent	bailian.console.aliyun.com
MiniMax	No — pay-per-token	Yes	platform.minimax.io
DeepSeek	No — pay-per-token (very cheap text rates)	No	platform.deepseek.com
Kimi	No — pay-per-token; kimi-k3 ($3/$15/1M, 1M ctx), kimi-k2.6 ($0.95/$4/1M)	No	bailian.console.aliyun.com
Anthropic	No	Yes	console.anthropic.com
OpenAI	No	Yes	platform.openai.com
Claude Code	Included with subscription — no API key	No	Setprovider = "claude-code" in config.toml
Opencode	Free via Opencode Zen — no API key	No	Setprovider = "opencode", model = "opencode/big-pickle" in config.toml; connect first: run opencode → /connect → select Zen

# macOS / Linux — add to ~/.bashrc or ~/.zshrc to persist
export GEMINI_API_KEY=AIza…          # default — free tier, 1M tokens/day
export GROQ_API_KEY=gsk_…            # alternative free tier — 100K tokens/day
export ANTHROPIC_API_KEY=sk-ant-…    # paid — highest quality
export OPENAI_API_KEY=sk-…           # paid
export MINIMAX_API_KEY=…             # paid — text rates (image support)
export DEEPSEEK_API_KEY=…            # paid — text rates (no image support)
export QWEN_API_KEY=…                # DashScope cloud — 1M free tokens trial (DASHSCOPE_API_KEY also accepted)
export KIMI_API_KEY=…                # Kimi (DashScope) — kimi-k3 flagship, kimi-k2.6 general (QWEN_API_KEY also accepted)
export TAVILY_API_KEY=tvly-…         # web search (optional)

# Windows cmd — current session only
set GEMINI_API_KEY=AIza…
set GROQ_API_KEY=gsk_…
set ANTHROPIC_API_KEY=sk-ant-…
set OPENAI_API_KEY=sk-…
set MINIMAX_API_KEY=…
set DEEPSEEK_API_KEY=…
set QWEN_API_KEY=…                   # DASHSCOPE_API_KEY also accepted
set KIMI_API_KEY=…                   # QWEN_API_KEY also accepted
set TAVILY_API_KEY=tvly-…

Web search uses Tavily (TAVILY_API_KEY) — optional, only needed for synthadoc ingest "search for: …" jobs. Get a free key at tavily.com.

---

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).

# Linux / macOS
synthadoc install history-of-computing --target ~/wikis --demo

# Windows (cmd.exe)
synthadoc install history-of-computing --target %USERPROFILE%\wikis --demo

Then start the engine:

# Foreground — logs stream to the console
synthadoc serve -w history-of-computing

# Background — releases the terminal
synthadoc serve -w history-of-computing --background

The server binds to http://localhost:7070 (localhost-only). Leave it running while you work — the Obsidian plugin, CLI ingest commands, and query commands all talk to it.

To switch LLM provider, edit [agents] in <wiki-root>/.synthadoc/config.toml and restart synthadoc serve. See Appendix — Switching LLM providers for step-by-step instructions.

To stop a background server:

synthadoc stop -w history-of-computing

Upgrading: after updating synthadoc (via pip install --upgrade "synthadoc[vectors]" or git pull), restart the server to pick up the new code, then run these to keep registered wikis in sync:

synthadoc plugin upgrade         # push updated Obsidian plugin binary to all registered wikis
synthadoc templates sync --force # demo and template wikis — refresh seeds, routing, agent files, and stubs

Neither command requires the server to be running.

Upgrading a Docker deployment: docker pull chenp/synthadoc:latest, then remove and re-create the container with the same docker run command; wiki data on the host is untouched. Then run inside the container to sync the plugin and templates:

docker exec <container> synthadoc plugin upgrade      # push updated plugin binary to the wiki vault
docker exec <container> synthadoc templates sync      # refresh seeds, routing, agent files, and stubs

See Docker Deployment Guide — Updating the image.

---

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; large wikis open on a cluster overview
25. Ingest an AI session transcript — turn Claude Code, Codex, or chat conversations into structured wiki pages
26. Agentic maintenance workflows — nine 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 n