Synthadoc

Prerequisites

LLM API key — at least one required (unless using Claude Code or Opencode — see the last two rows below):

Tavily API key (optional — enables web search): Get a free key at tavily.com. Without it, web search jobs will fail but all other features work normally.

---

Set a wiki as the default so -w is not required for any subsequent command

synthadoc use my-wiki

Requires TAVILY_API_KEY to be set.

#

4. LLM-compiled content can be overconfident; Synthadoc audits it

An LLM synthesising source documents naturally produces confident prose — but may overstate claims, omit caveats, or accept a source's framing uncritically. The adversarial lint pass runs a concurrent second-LLM review of every page: it plays devil's advocate to surface issues the primary model accepted too readily — contested estimates, unsupported superlatives, and claims that contradict well-established facts. Warnings are stored in page frontmatter and surfaced in both the CLI report and the Obsidian lint modal. The reviewer is calibrated to flag only high-confidence issues, producing a useful signal without noise. For the strongest signal, point the adversarial pass at a different model family: a distinct model is far more likely to challenge assumptions than the same model reviewing its own output.

Installation

Step 1 — Clone and install

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

If you already have Synthadoc wikis installed, upgrade the Obsidian plugin in all registered wikis to keep them in sync:

synthadoc plugin upgrade

Step 6 — Install a demo wiki, then start the engine

A wiki is a self-contained, structured knowledge base — a folder of Markdown pages linked by topic, maintained and cross-referenced automatically by Synthadoc. Think of it as a living document that grows smarter with every source you feed it: each ingest pass adds new pages, updates existing ones, and flags contradictions. For your own work, you can build and grow a domain-specific wiki — whether that's market research, a technical knowledge base, or a team handbook — and query it in plain English or other languages at any time.

A wiki must be installed before the engine can serve it. The fastest way to get started is the History of Computing demo, which ships with 13 pre-built pages and sample source files — no LLM API key required to browse it.

First time — install the demo wiki:

```bash

Install the demo (includes pre-built pages and raw sources — no LLM call needed)

synthadoc install history-of-computing --target ~/wikis --demo

Sync new source files into an existing demo install (additive only, no overwrites)

synthadoc demo sync history-of-computing

Install the Obsidian plugin directly into the active Obsidian vault

synthadoc plugin install history-of-computing ```

Then uninstall — two-step confirmation required, no --yes escape

synthadoc uninstall my-wiki ```

For Obsidian plugin commands see Appendix A — Obsidian Plugin Command Reference in the Quick-Start Guide.

---

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 Dataview in Obsidian
3. Install the Synthadoc plugin and open the vault
4. Review wiki structure and key files (index, purpose, AGENTS.md, dashboard)
5. Query the pre-built wiki — including knowledge gap detection
6. Batch ingest all demo source files
7. Run lint — auto-promote clean pages to active
8. Manage page lifecycle — 5-state machine (draft → active → stale/contradicted/archived), manual transitions, immutable audit trail
9. Resolve a contradiction
10. Fix an orphan page
11. Run the adversarial lint pass — flag overstated claims across all pages
12. Web search ingestion with automatic decomposition
13. Ingest a YouTube video
14. Enrich the wiki with scaffold (regenerate/update index, purpose, AGENTS.md)
15. Audit features (token cost, history, events)
16. Schedule recurring operations
17. Set up query-scoped routing with ROUTING.md
18. Stage and review candidate pages before promoting them
19. Build a context pack for grounded LLM prompts
20. Verify claim provenance — source-line citations, broken citation audit, global provenance table
21. Export your wiki — llms.txt, llms-full.txt, GraphML wikilink graph, agent-ready JSON with provenance and lifecycle history
22. Use the web chat UI — streaming answers, session-aware hint chips, citations in-browser
23. Query caching — understand how answers are cached and how to bypass with --no-cache

---

Command Reference by Use Case

Example sources.txt:

Token usage: totals + daily breakdown

synthadoc audit cost -w my-wiki # last 30 days synthadoc audit cost --days 7 -w my-wiki # last 7 days

List available demo templates

synthadoc demo list

Configuration

You do not need to configure anything to run the demo. The demo wiki ships with its own settings and sensible built-in defaults cover everything else. Set your API key env var, run synthadoc serve, and go.

For the full configuration reference — layer precedence, global vs. per-project config, all keys and defaults — see Appendix E — Configuration in the Quick-Start Guide, or docs/design.md — Configuration for the complete technical reference.

---

Setting up a wiki

```bash

See docs/design.md § "schedule sub-commands" for the config.toml format

synthadoc schedule apply -w my-wiki

Port is per-wiki — check [server] port in <wiki-root>/.synthadoc/config.toml

~/.synthadoc/config.toml

[observability] exporter = "otlp" otlp_endpoint = "http://localhost:4317" ```

Check for configuration problems

synthadoc status -w my-wiki # prints pre-flight warnings

Step 4 — Set your API keys

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

Synthadoc defaults to Gemini Flash as the LLM provider — it's free, requires no credit card, and offers 1 million tokens per day. Get a key at aistudio.google.com/app/apikey (click "Create API key").

Web search uses Tavily (TAVILY_API_KEY) — optional, only needed for synthadoc ingest "search for: …" jobs.

```bash

Create a new empty wiki (LLM scaffold runs automatically if API key is set)

synthadoc install my-wiki --target ~/wikis --domain "Machine Learning"

Start HTTP API + job worker (foreground — terminal stays attached)

synthadoc serve -w my-wiki

YouTube video — transcript extracted automatically, no API key needed.

Open the browser-based chat interface for a wiki

synthadoc web -w my-wiki ```

This opens your browser to a local chat interface at http://localhost:{port}/app. The Web UI is local-only and is not accessible from the network — authentication and authorisation are not yet available in the Community Edition.

The UI detects whether you are new to the wiki, exploring, or a returning user and shows contextual hint chips. Ask questions in the text box; answers stream in as the LLM generates them. Citations appear below each answer; knowledge-gap callouts suggest ingesting more content when the wiki lacks coverage.

Administrative Reference

Step 3 — Test the Obsidian plugin

The pre-built main.js is committed to the repo — you do not need to rebuild it unless you modify the plugin source code. To run the plugin unit tests:

cd obsidian-plugin
npm install
npm test         # runs Vitest unit tests

If you modify src/main.ts, rebuild the bundle before installing:

npm run build    # produces main.js

Knowledge gap workflow

When a query returns thin or empty results, the wiki doesn't yet cover the topic. Fill the gap with a targeted web search ingest, wait for jobs, then re-query. Each ingest cycle makes the wiki denser — future queries need the web less.

See docs/design.md — Knowledge gap workflow for the full pattern.

See docs/design.md for a full description of how ingest, contradiction detection, and orphan tracking work under the hood.

---

OpenTelemetry integration

By default, traces and metrics are written to <wiki-root>/.synthadoc/logs/traces.jsonl. To send to any OTLP backend (Jaeger, Grafana Tempo, Honeycomb, Datadog):

```toml

Key differentiators vs. RAG

RAG chunks documents and retrieves them at query time. Synthadoc compiles knowledge: every new source is synthesized into the existing wiki graph at ingest time.

• Contradictions are caught, not blended. When two sources disagree, Synthadoc flags the page — RAG silently averages both claims.
• Knowledge is linked, not scattered. [[wikilinks]] connect related pages into a navigable graph visible in Obsidian and queryable with Dataview.
• The artifact outlives the tool. Close the server, open the wiki folder in any Markdown editor — the knowledge is all there, human-readable, no proprietary format.
• Cost-efficient at scale. Two-step ingest with cached analysis means repeated ingest of similar sources costs near-zero tokens. Three cache layers stack for lint and query too.
• Ingest is durable, not fragile. Every ingest request becomes a queued job with automatic retry and a persistent audit record. Batch a hundred documents and resume after a crash — no work is lost.

---

Bulk-register all jobs declared in [[schedule.jobs]] in config.toml (alternative to schedule add)

Ask a question — answer streams token-by-token as the LLM generates it

synthadoc query "What is Moore's Law?" -w my-wiki