Synthadoc

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.

#

Installation

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

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 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.1 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 — build the wikilink graph, explore clusters in the web UI Graph tab, click a node to query it

---

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

Update existing demo pages from the latest template (overwrites demo pages)

synthadoc demo sync history-of-computing --force

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

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

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 ```

→ Full walkthrough (session modes, multi-turn conversation, session history sidebar): Quick-Start Guide — Step 22

Administrative Reference

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

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