user-quick-start-guide.md

# Synthadoc User Quick-Start Guide

**Version: v1.4.1 (Community Edition)**

This guide walks you through the **History of Computing** demo wiki — a fully wired
Synthadoc environment with 13 pre-built pages and six raw source files that cover every
major engine feature. No setup beyond following the steps below is required.

> **Before you start:** complete the [README Installation](../README.md#installation) section —
> install synthadoc (production or development), set your API key, install the demo wiki, and start the engine.
> Then come back here.
>
> **Already installed the demo wiki?** Skip `synthadoc install` and run `synthadoc templates sync history-of-computing --force` instead. This updates all pre-built demo pages and source files to the latest template, including pages with citation markers added in recent releases. `--force` only overwrites demo template files — your own ingested pages and `.synthadoc/` config and audit data are never touched.

---

## Table of Contents

1. [Verify the demo server has started](#step-1--verify-the-demo-server-has-started)
2. [Install the Synthadoc plugin](#step-2--install-the-synthadoc-plugin)
3. [Open the vault in Obsidian](#step-3--open-the-vault-in-obsidian)
4. [Review the wiki structure and key files](#step-4--review-the-wiki-structure-and-key-files)
5. [Query the pre-built wiki (CLI + Obsidian)](#step-5--query-the-pre-built-wiki-cli--obsidian)
6. [Batch ingest all demo sources](#step-6--batch-ingest-all-demo-sources)
7. [Run lint — promote pages to active](#step-7--run-lint--promote-pages-to-active)
8. [Manage page lifecycle](#step-8--manage-page-lifecycle)
9. [Resolve a contradiction](#step-9--resolve-a-contradiction)
10. [Fix an orphan page](#step-10--fix-an-orphan-page)
11. [Run the adversarial review](#step-11--run-the-adversarial-review)
12. [Web search ingestion](#step-12--web-search-ingestion)
13. [Ingest a YouTube video](#step-13--ingest-a-youtube-video)
14. [Enrich the wiki with scaffold](#step-14--enrich-the-wiki-with-scaffold)
15. [Audit features](#step-15--audit-features)
16. [Scheduling recurring operations](#step-16--scheduling-recurring-operations)
17. [Set up ROUTING.md — scoped search](#step-17--set-up-routingmd--scoped-search)
18. [Configure candidates staging](#step-18--configure-candidates-staging)
19. [Build a context pack](#step-19--build-a-context-pack)
20. [Establish claim-level provenance](#claim-provenance)
21. [Export your wiki — llms.txt, GraphML, JSON, OKF bundle](#step-21--export-your-wiki)
22. [Use the web chat UI](#step-22--use-the-web-chat-ui)
23. [Query caching](#step-23--query-caching)
24. [Knowledge Graph](#knowledge-graph)
25. [Ingest an AI session transcript](#session-ingest)
26. [Agentic Maintenance Workflows](#agentic-workflows)
27. [Scan and retract sensitive data](#step-27--scan-and-retract-sensitive-data)

**Appendices**

- [Appendix A — Obsidian Plugin Command Reference](#appendix-a--obsidian-plugin-command-reference)
- [Appendix B — Hooks: auto-commit wiki to git](#appendix-b--hooks-auto-commit-wiki-to-git)
- [Appendix C — Switching LLM providers](#appendix-c--switching-llm-providers)
- [Appendix D — Tavily web search key](#appendix-d--tavily-web-search-key)
- [Appendix E — Configuration](#appendix-e--configuration)
- [Appendix G — Using a Coding Tool as Your LLM Provider](#appendix-g--using-a-coding-tool-as-your-llm-provider)
- [Appendix H — BM25 Routing Performance Benchmarks](#appendix-h--bm25-routing-performance-benchmarks)
- [Appendix I — Connect Claude via MCP](#appendix-i--connect-claude-via-mcp)
- [Appendix J — Backup & Restore](#appendix-j--backup--restore)
- [Appendix K — Domain Templates](#appendix-k--domain-templates)
- [Appendix L — Cross-Wiki Queries](#appendix-l--cross-wiki-queries)

---

<a name="verify-server"></a>

## Step 1 — Verify the demo server has started

If you ran `synthadoc serve -w history-of-computing` or
`synthadoc serve -w history-of-computing --background` in the README, the server
should already be listening on port 7070. Confirm it is up:

```bash
synthadoc status -w history-of-computing
```

Expected output:

```
Wiki:         /home/user/wikis/history-of-computing
Pages:        13
Jobs pending: 0
Jobs total:   0
```

Or probe the health endpoint directly:

```bash
curl http://127.0.0.1:7070/health
# → {"status":"ok"}
```

If neither responds, start the server now:

```bash
# Foreground (terminal stays attached — logs stream to console)
synthadoc serve -w history-of-computing

# Background (terminal is released — logs go to wiki log file)
synthadoc serve -w history-of-computing --background
```

![synthadoc serve startup banner](png/synthadoc-serve.png)

The banner confirms the port, wiki path, active LLM provider/model, and PID. If you see
`Warning: TAVILY_API_KEY is not set`, web search (Step 10) will not work — see
[Appendix D — Tavily web search key](#appendix-d--tavily-web-search-key).

If the server does not start, the most common cause is the port already being in use.
Check `<wiki-root>/.synthadoc/config.toml` for `[server] port` and use `--port N` to
override if needed.

> To use Claude Code or Opencode as your LLM provider instead of a direct API key, see [Appendix G](#appendix-g--using-a-coding-tool-as-your-llm-provider).

### Set your active wiki (do this once)

```bash
synthadoc use history-of-computing
```

From this point on, every command in this guide omits `-w history-of-computing` — the active wiki is resolved automatically.

To see which wiki is active at any time:

```bash
synthadoc use
```

---

<a name="install-plugin"></a>

## Step 2 — Plugin already installed

No separate plugin step is needed. `synthadoc install` already copied both the Synthadoc plugin and the Dataview plugin directly into the vault's plugins folder, pre-enabled them, and set the correct server URL.

> **Reading View set automatically:** the installer writes `"defaultViewMode": "preview"` to `.obsidian/app.json`, so Obsidian opens wiki pages in Reading View by default. This is required for citation chips (`^[file:L-L]`) to render — they are invisible in Edit or Live Preview mode. You can change this later in Obsidian's Settings → Editor → Default view.

> **Upgrading an existing installation?** Run `synthadoc plugin upgrade` to push the updated plugin binary to all registered wikis. This is only needed when upgrading Synthadoc — not for new installs.

Now open Obsidian.

---

<a name="open-vault"></a>

## Step 3 — Open the vault in Obsidian

**Obsidian must already be installed** — download from **[obsidian.md](https://obsidian.md)** if not.

### 1. Open the vault

In Obsidian: **Open folder as vault** → select the installed wiki folder:

- **Windows:** `%USERPROFILE%\wikis\history-of-computing`
- **Linux / macOS:** `~/wikis/history-of-computing`

Obsidian will immediately show a safety prompt:

> **"[Author] has a plugin in this vault…"**
> Trust author and enable plugin / Keep plugins disabled

Click **Trust author and enable plugin**. Without this the Synthadoc (and Dataview) plugins remain disabled and no Synthadoc commands will be available.

> **Tip — show all file types:** By default Obsidian hides file types it does not
> natively understand (`.xlsx`, `.pptx`, etc.). To show them: **Settings → Files and
> links → Show all file types → on**.

### 2. Verify both plugins are active

Both Synthadoc and Dataview are already installed **and enabled** by Step 2 — no manual toggling required. Obsidian picks them up automatically when you open the vault.

Go to **Settings → Community Plugins** to confirm both show a blue enabled toggle. While there:

1. Click the gear icon next to **Synthadoc**
2. Confirm **Server URL** is `http://127.0.0.1:7070` (set automatically from `config.toml` — if the port ever changes, re-run `synthadoc plugin install` to update it)
3. Close settings

The **Synthadoc ribbon icon** (book icon on the far-left sidebar) confirms the plugin is
active. All Synthadoc commands are reachable via the Command Palette (`Ctrl/Cmd+P` →
type `Synthadoc`).

![Synthadoc ribbon icon](png/synthadoc-ribbon-icon.png)

![Obsidian vault with pre-built wiki](png/synthadoc-vault-demo.png)

> **Dataview cache:** If the dashboard disagrees with `synthadoc lint report`, drop the
> cache: `Ctrl/Cmd+P` → **Dataview: Drop all cached file metadata**, then reopen the
> dashboard. The CLI report is always authoritative.

---

<a name="wiki-structure"></a>

## Step 4 — Review the wiki structure and key files

Open the vault explorer. The key files and folders:

```
history-of-computing/
  wiki/                   ← compiled Markdown pages (open these in Obsidian)
    index.md              ← table of contents with [[wikilinks]] to every page
    dashboard.md          ← live Dataview tables — contradictions, orphans, recently added/updated/archived
    purpose.md            ← scope definition — what belongs in this wiki and what to skip
    overview.md           ← LLM-generated 2-paragraph summary of the entire wiki
    alan-turing.md        ← example pre-built topic page
    grace-hopper.md       ← ...and so on for each of the 13 pre-built pages
  raw_sources/            ← source documents to ingest (PDF, PPTX, XLSX, PNG, MD)
  AGENTS.md               ← LLM instructions for Codex/OpenCode — domain guidelines for ingest and query
  CLAUDE.md               ← same instructions, Claude Code format (read automatically when you open this folder in Claude Code)
  GEMINI.md               ← same instructions, Gemini CLI format
  log.md                  ← human-readable activity log of every ingest and lint event
  .synthadoc/
    config.toml           ← per-wiki settings (port, LLM provider, cost limits)
    audit.db              ← immutable audit trail (ingest history, costs, events)
    jobs.db               ← job queue (persistent across server restarts)
    cache.db              ← LLM response cache (reduces repeat spend)
```

**Open these files in Obsidian now:**


| File                  | What to look at                                                                                                                                                                                                                                                                                                                    |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wiki/index.md`       | Pre-generated category structure with`[[wikilinks]]` to each page                                                                                                                                                                                                                                                                  |
| `wiki/dashboard.md`   | Live Dataview tables — contradictions, orphans, recently added / updated / archived                                                                                                                                                                                                                                               |
| `wiki/alan-turing.md` | YAML frontmatter:`status`, `confidence`, `tags`, `sources[]`                                                                                                                                                                                                                                                                       |
| `AGENTS.md`           | Domain-specific guidelines for Codex/OpenCode agents — LLM reads this on every ingest                                                                                                                                                                                                                                             |
| `CLAUDE.md`           | Same guidelines in Claude Code format — loaded automatically when you open this folder in Claude Code                                                                                                                                                                                                                             |
| `GEMINI.md`           | Same guidelines in Gemini CLI format                                                                                                                                                                                                                                                                                               |
| `wiki/purpose.md`     | Scope definition for History of Computing — five sections (Overview, What Belongs, Out of Scope, Intended Audience, Primary Use Cases). Each section contains a`<!-- synthadoc:scaffold -->` marker: content you add **above** a marker is preserved when you re-run `synthadoc scaffold`; content below is refreshed by the LLM. |

> **Upgrading an existing wiki?** If your wiki was created before v1.0.2, it will have `AGENTS.md` but not `CLAUDE.md` or `GEMINI.md`. Run `synthadoc scaffold` once to generate all three with LLM-produced guidelines that match your current wiki content.

### dashboard.md — what each section shows

`wiki/dashboard.md` contains four live Dataview tables. Open it in Obsidian (Reading View) after installing the Dataview plugin to see them update automatically as you work through this guide.


| Section                | What it shows                                                                          | Powered by                                                    |
| ---------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| **Contradicted pages** | Pages whose sources conflict — need manual resolution                                 | `status = "contradicted"`                                     |
| **Orphan pages**       | Pages with no inbound`[[wikilinks]]` — run lint first to populate                     | `orphan = true` (set by lint)                                 |
| **Recently added**     | The 10 most recently created pages, newest first                                       | `created` frontmatter field                                   |
| **Recently updated**   | Pages that have been re-ingested with new source material since their initial creation | `updated` frontmatter field — only present after a re-ingest |
| **Recently archived**  | Pages currently in`archived` state — retired from active use                          | `status = "archived"`                                         |

**Recently added vs. Recently updated** — these are intentionally separate:

- **Recently added** lists every page by its `created` date. A freshly installed demo wiki shows all pages here because they were all created at install time.
- **Recently updated** only appears for pages that have been re-ingested after their initial creation. The `updated` field is written by the ingest engine when it merges new source material into an existing page — it is absent on first creation. This means the table starts empty in a fresh install and grows as you re-ingest sources with `--force` or ingest new files that map to existing pages.

**Recently archived** — to restore a page from this list, change its `status` back to `active` in Obsidian's Properties panel, or use the CLI:

```bash
synthadoc lifecycle restore <slug> --reason "source re-added"
```

> **Dataview cache:** If a table disagrees with `synthadoc status` or `synthadoc lint report`, drop the cache: `Ctrl/Cmd+P` → **Dataview: Drop all cached file metadata**, then reopen `dashboard.md`. The CLI is always authoritative.

---

<a name="query-wiki"></a>

## Step 5 — Query the pre-built wiki (CLI + Obsidian)

### CLI queries

The wiki already has 13 pages on computing history — query them before ingesting anything:

```bash
synthadoc query "How did Alan Turing influence modern computers?"
synthadoc query "What is Moore's Law and why does it matter?"
synthadoc query "How did Unix influence the open-source movement?"
```

Each answer streams to your terminal token-by-token as the LLM generates it. Citations to source pages appear at the end of the answer. For scripts or pipes that need buffered output, add `--no-stream`:

```bash
synthadoc query "How did Alan Turing influence modern computers?" --no-stream
```

### Compound and multi-part queries

Synthadoc automatically decomposes complex questions into focused sub-queries, retrieves
pages for each part in parallel, then synthesises a single merged answer:

```bash
# Two-part question — decomposes into two independent BM25 searches
synthadoc query "Compare Alan Turing's theoretical contributions with Von Neumann's architectural contributions."

# Multi-hop causal question — automatically decomposed
synthadoc query "How did Moore's Law shape both hardware design and software expectations over time?"
```

The server log shows the decomposition:

```
query decomposed into 2 sub-question(s):
  "Alan Turing theoretical contributions" | "Von Neumann architectural contributions"
```

Simple single-topic questions decompose to one sub-question and behave identically to
a direct query — no extra LLM cost.

> **Proportional context budget (v1.0):** Synthadoc allocates sources proportionally to the model's context window rather than capping at a fixed top-N. A larger model context means more wiki pages included in the answer. You do not need to configure this — it adapts automatically to whichever LLM provider you have set.

> **Slow provider?** If you have enabled thinking mode on a reasoning model (e.g. MiniMax M3 with `thinking = "enabled"`), responses can take longer.
> If you see a timeout error, pass `--timeout 120`:
>
> ```bash
> synthadoc query "How did Moore's Law shape hardware design?" --timeout 120
> ```

### Knowledge gap detection

If the wiki does not cover a topic, Synthadoc detects the gap automatically:

```bash
synthadoc query "What is quantum error correction?"
```

Expected output (example):

```
No relevant pages found on this topic.

[!tip] Knowledge Gap Detected
Your wiki doesn't have enough on this topic yet. Enrich it with a web search:

  synthadoc ingest "search for: quantum error correction methods"
  synthadoc ingest "search for: quantum computing hardware qubits"
```

The suggested search strings are generated automatically. Run one of the suggestions
after Step 12 to fill the gap.

![CLI query result with knowledge gap callout](png/cli-gap-detection.png)

### Query from Obsidian

Open the Command Palette (`Ctrl/Cmd+P`) → `Synthadoc: Query: ask the wiki...` → type a
question → press `Ctrl/Cmd+Enter`. The answer appears in a responsive modal with
clickable `[[wikilinks]]`.

![Obsidian query modal with answer](png/ui-gap-detection.png)

### Aliases — alternative names for a page

Every wiki page (pre-built or ingest-created) has an `aliases` field in its frontmatter.
It starts empty and is visible in Obsidian's **Properties** panel. Add alternative
names or abbreviations so the query engine can match them without knowing the exact page title.

**Try it now with `wiki/alan-turing.md`:**

1. Open `wiki/alan-turing.md` in Obsidian
2. In the **Properties** panel, click the `aliases` field and add one or more names:

```yaml
---
title: Alan Turing
aliases:
  - Turing
  - father of computer science
  - Turing machine inventor
---
```

3. Save the file, then query using an alias instead of the page title:

```bash
synthadoc query "What did Turing contribute to computing?"
# "Turing" expands to the alan-turing slug before BM25 runs
```

Aliases are matched case-insensitively. Longest match wins — so if two pages each define
an alias and one is a longer substring of the query, the longer one takes precedence.

### OKF compatibility fields

Every page compiled by Synthadoc also carries two fields that align with Google's [Open Knowledge Format (OKF) v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md):


| Field      | What it contains                                                                                          | Set by                                            |
| ---------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `type`     | Knowledge classifier:`concept`, `person`, `technology`, `event`, `organization`, `location`, or `product` | Ingest — LLM classifies during the analysis pass |
| `resource` | Primary source URL (only present for URL-sourced pages)                                                   | Ingest — auto-populated from the URL             |

These fields make Synthadoc wikis directly consumable by any OKF-aware agent without an export step. Pages ingested from local files have no `resource` field.

**`resource` vs `sources` — what's the difference?**

Both point at source material, but for different audiences:

- **`sources`** is Synthadoc's internal audit record — an array that grows as more files are ingested into the same page, storing the file path, SHA-256 hash, byte size, and ingestion timestamp. Used for dedup, stale detection, and cost tracking.
- **`resource`** is the OKF citation — a single URL that any agent or human can follow to the original source, without needing to understand Synthadoc's schema.

For URL sources both refer to the same URL; for local files only `sources` is present.

**Migrating pages created before v0.9.0** — older pages have no `type` field. Force re-ingest to backfill it:

```bash
synthadoc ingest path/to/source.pdf --force
# or for a URL source
synthadoc ingest "https://example.com/article" --force
```

The `--force` flag skips the duplicate check and re-runs the analysis pass, which classifies the knowledge type and writes it to the page's frontmatter. Existing content is appended to, not replaced. If `type` is already set, it is not overwritten.

---

<a name="batch-ingest"></a>

## Step 6 — Batch ingest all demo sources

The six source files in `raw_sources/` are designed to demonstrate every ingest scenario:


| File                               | Skill      | Scenario                                                                                                                                                                 |
| ---------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `turing-enigma-decryption.pdf`     | `pdf`      | **A — Clean merge**: enriches `alan-turing` with Bletchley Park and Bombe detail                                                                                        |
| `computing-pioneers-timeline.xlsx` | `xlsx`     | **A — Clean merge**: structured two-sheet timeline; enriches multiple pages                                                                                             |
| `cs-milestones-overview.pptx`      | `pptx`     | **A — Clean merge + new pages**: 6-slide deck; creates `eniac`, `transistor-and-moores-law`, `internet-history`; enriches `ada-lovelace`, `alan-turing`, `grace-hopper` |
| `first-compiler-controversy.pdf`   | `pdf`      | **B — Conflict**: contradicts `grace-hopper` (A-0 vs FORTRAN dispute)                                                                                                   |
| `quantum-computing-primer.png`     | `image`    | **A — New page**: vision LLM extracts key concepts; creates `quantum-computing`                                                                                         |
| `konrad-zuse-z3-computer.md`       | `markdown` | **C — Orphan**: specific niche topic; creates `konrad-zuse` with no inbound links                                                                                       |

### Run batch ingest

**CLI:**

```bash
synthadoc ingest --batch raw_sources/
```

**Obsidian:** Command Palette → `Synthadoc: Ingest...` → select the **All raw_sources** tab

![Synthadoc Ingest modal — All raw_sources tab queuing source files for batch ingest](png/synthadoc-batch-ingest-raw-sources.png)

Both enqueue one job per file. Watch them:

```bash
synthadoc jobs list
```

![synthadoc jobs list terminal output](png/job-list-terminal.png)

Wait until all six show `completed`. Filter by status if needed:

```bash
synthadoc jobs list --status pending
synthadoc jobs list --status completed
```

Or from Obsidian: Command Palette → `Synthadoc: Jobs...` → use the status-filter checkboxes. The table defaults to newest jobs first; click **Status**, **Operation**, or **Created** headers to re-sort.

![Obsidian Jobs list modal with status filter dropdown](png/synthadoc-jobs-modal.png)

### Verify the results

Once all jobs complete, open **Graph view** (`Ctrl/Cmd+G`) — new nodes appear for the
ingested topics and link into the existing graph.

![Obsidian Graph View after batch ingest](png/synthadoc-graph-after.png)

> **Pages are created as `draft` — queries come after lint.** Every page produced by ingest starts in the `draft` state — compiled but not yet reviewed. Only `active` and `stale` pages enter the BM25 search index; `draft`, `contradicted`, and `archived` pages are excluded from query results. Run lint in Step 7 to promote clean pages to `active` first, then verify with queries at the end of that step.

> **Pre-LLM sanitizer (v1.0):** Before sending any source to the LLM, Synthadoc strips zero-width characters, bidirectional text overrides, hidden HTML, and instruction-override phrases that could cause the model to misinterpret content. This runs automatically — no configuration needed. See [design.md §29](design.md#29-pre-llm-source-sanitizer) for the full table of sanitizer categories, actions, and warning behaviour.

> **Large sources:** Synthadoc applies a default character limit of 32,000 characters per source before the LLM call. Sources that exceed this limit are truncated; the compiled page records `truncated: true` in its `sources:` frontmatter and `synthadoc lint` emits a warning with a suggested override command. To raise the limit for a single ingest run `synthadoc ingest papers/large-textbook.pdf --max-source-chars 128000`, or set it globally in `.synthadoc/config.toml` under `[ingest] max_source_chars = 128000`.

---

<a name="lint-run"></a>

## Step 7 — Run lint — promote pages to active

Every page created by ingest in Step 6 starts as `draft`. A lint run validates each page — checking for contradictions, orphan pages, dangling links, and citation presence — and automatically promotes clean pages to `active`.

> **Citation presence warnings:** Lint Check 5b warns when a page has 50 or more words but no `^[filename:L-L]` citation markers. This is a diagnostic, not an error — the page is still promoted to `active`. It usually means the LLM did not follow the citation-format instruction precisely; re-ingesting the source with a more capable model (Gemini 2.5 Flash or higher) resolves it. See `synthadoc audit citations --broken` to review all citation failures.

### 1. Check status before running lint

```bash
synthadoc status
```

Expected output (after batch ingest, before lint):

```
[wiki: history-of-computing]
Wiki:         ~/wikis/history-of-computing
Pages:        18
Jobs pending: 0
Jobs total:   6

Page lifecycle:
  active         0
  draft          5  <- run `synthadoc lint run` to promote
  stale          0
  contradicted   0
  archived       0
```

The 5 `draft` pages are the new pages created by ingest. The 13 pre-built demo pages are not shown yet — they have no lifecycle record until lint runs for the first time and syncs their state.

### 2. Run lint

```bash
synthadoc lint run
synthadoc jobs list           # watch progress
```

Wait until the lint job shows `completed`.

You can also run lint from the Obsidian plugin — open the command palette (`Ctrl/Cmd+P`) and choose **Synthadoc: Lint: run…**:

![Synthadoc Run Lint panel in Obsidian](png/synthadoc-lint-run.png)

### 3. Check status after lint

```bash
synthadoc status
```

Expected output:

```
[wiki: history-of-computing]
Wiki:         ~/wikis/history-of-computing
Pages:        18
Jobs pending: 0
Jobs total:   7

Page lifecycle:
  active        17
  draft          0
  stale          0
  contradicted   1  <- review required
  archived       0
```

All 5 draft pages were promoted to `active`. The 13 pre-built pages were registered in the lifecycle system for the first time — 12 became `active`, and `grace-hopper` became `contradicted` (see Step 9).

### 4. Review the lint report

`synthadoc status` shows counts. `synthadoc lint report` shows what actually needs your attention — contradicted pages, orphan pages with no inbound links, adversarial warnings, and citation issues.

```bash
synthadoc lint report
```

Expected output (one contradicted page in the demo wiki):

```
Contradicted pages (1) - need review:

  grace-hopper
    Why flagged: Wikipedia source conflicts with the ACM oral history on the COBOL
    standardisation timeline.
    -> Open wiki/grace-hopper.md, resolve the conflict, then set status: active
    -> Or re-run: synthadoc lint -w history-of-computing --auto-resolve
```

You can also open the report from the Obsidian plugin — open the command palette (`Ctrl/Cmd+P`) and choose **Synthadoc: Lint: report**. The modal shows the same information with action buttons.

The contradicted `grace-hopper` page is explained and resolved in Step 9.

### 5. Verify with queries

All pages are now `active` and in the search index. Run queries that use content from the newly ingested sources:

```bash
synthadoc query "What was the Bombe machine and who built it?"
synthadoc query "Who invented FORTRAN and when?"
synthadoc query "What did Konrad Zuse contribute to computing history?"
```

Each answer should cite specific source lines from the ingested files. If a query returns no results or thin answers, check `synthadoc status` — any page still in `draft` or `contradicted` is excluded from the index until it is promoted or resolved.

---

<a name="lifecycle"></a>

## Step 8 — Manage page lifecycle

Most knowledge bases treat every page the same — ingested means trusted. Synthadoc is different: every compiled page carries a lifecycle state that reflects whether it has been reviewed, whether its source has changed, and whether a conflict has been detected. Pages you haven't reviewed yet are `draft`. Pages whose source files have been modified since ingest are automatically flagged `stale`. Pages with conflicting sources are marked `contradicted`. Pages whose source has disappeared are `archived`. Every state change — automated or manual — is permanently recorded with who triggered it and why.

> **Differentiation:** RAG pipelines and competing wiki tools have no equivalent concept. They ingest content and serve it forever, with no way to know whether the underlying source is still current, whether two sources contradict each other, or whether a page was ever reviewed. Synthadoc's 5-state lifecycle machine turns your wiki from a static dump into a living, auditable knowledge base.

### Lifecycle states


| State          | Meaning                                     | How it is reached                                               | What to do                                           |
| -------------- | ------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------- |
| `draft`        | Compiled but not yet lint-reviewed          | Automatic on ingest                                             | Run lint to auto-promote clean pages                 |
| `active`       | Lint-reviewed, current, trusted             | Lint auto-promotes from`draft`                                  | No action needed                                     |
| `contradicted` | Sources conflict, or adversarial gate fired | Lint detects contradiction or ≥ threshold adversarial warnings | Resolve conflict or fix flagged claims, then re-lint |
| `stale`        | Source file has changed since last ingest   | Lint detects SHA-256 hash mismatch                              | Re-ingest the updated source with`--force`           |
| `archived`     | Source removed or explicitly retired        | Lint auto-archives on missing source; or manual                 | Restore to`draft` if source returns                  |

### Check lifecycle status (CLI)

```bash
synthadoc status
```

```
Wiki: history-of-computing
  active         18
  draft           0
  stale           0
  contradicted    1
  archived        0
```

### Manage states in Obsidian

Open the Command Palette (`Ctrl/Cmd+P`) → **Synthadoc: Manage Page Lifecycle**. A sortable, filterable table shows every wiki page with its current state, last transition timestamp, and the action buttons valid for that state. Filter by state using the checkboxes at the top, or sort by any column header. Click an action button — a **reason dialog** appears before the transition commits, ensuring every manual change is documented.

![Synthadoc Manage Page Lifecycle modal — one row per page showing current state, last changed timestamp, and action buttons](png/synthadoc-lifecycle-mgmt.png)

Switch to the **Audit Log** tab to see the full history of every state transition across all pages — searchable by slug, filterable by target state, sortable by any column, with pagination.

![Synthadoc Lifecycle Audit Log tab — searchable history of state transitions with From/To state chips, triggered-by, timestamp, and reason columns](png/synthadoc-lifecycle-audit.png)

### Manual state transitions (CLI)

The CLI gives you control over page state outside of lint automation. Transitions follow the lifecycle graph — only semantically valid paths are accepted; invalid ones are rejected with a clear error:

```bash
# Promote a page to active after manual review (draft/stale/contradicted → active)
synthadoc lifecycle activate alan-turing --reason "reviewed and verified"

# Retire a page whose source has been superseded (any non-archived state → archived)
synthadoc lifecycle archive alan-turing --reason "replaced by v2 source"

# Restore an archived page back to draft for re-review (archived → draft)
synthadoc lifecycle restore alan-turing --reason "source re-added to raw_sources"

# View the full transition history for a page
synthadoc lifecycle log konrad-zuse
```

### Stale detection — local files

If a source file on disk changes after ingest, the next lint run detects the SHA-256 hash mismatch and marks the page `stale`. This catches silent content drift — source documents updated without anyone re-ingesting them.

**Walk-through with the demo wiki:**

1. **Edit the raw source file** — open `raw_sources/konrad-zuse-z3-computer.md` in any text editor. Add a sentence at the very end of the file:

   ```
   Updated: The Z3 blueprint later influenced Plankalkül, Zuse's programming language.
   ```

   Save the file.
2. **Run lint** — the hash mismatch is detected automatically:

   ```bash
   synthadoc lint run
   ```
3. **Find which pages are now stale** — `synthadoc status` shows the counts but not which pages. To see the specific pages, use the **Lifecycle Management** panel in the Obsidian plugin, or run:

   ```bash
   synthadoc lifecycle log --state stale
   ```

   ```
   [wiki: history-of-computing]
   Slug          From    To      By    Timestamp            Reason
   konrad-zuse   active  stale   lint  2026-05-28T18:11:13  source file modified since last ingest
   ```
4. **Inspect the full transition history for the page:**

   ```bash
   synthadoc lifecycle log konrad-zuse
   ```
5. **Resolve staleness** — re-ingest the updated file:

   ```bash
   synthadoc ingest raw_sources/konrad-zuse-z3-computer.md --force
   ```

   The next `synthadoc lint run` returns the page to `active`.

The same mechanism works for any raw source format — markdown, plain text, PDF, DOCX. Once a file is re-ingested, the stored hash updates and lint no longer flags the page as stale.

### URL source availability and freshness

Pages ingested from web URLs or YouTube are also monitored — but these checks are opt-in to avoid adding network calls to every lint run.

**Archived — URL has gone away**

Enable HTTP availability checks with the `--check-urls` flag or a config option:

```bash
synthadoc lint run --check-urls
```

```toml
# config.toml
[lint]
check_url_availability = true
```

When enabled, lint issues an HTTP HEAD request for each URL-sourced page. A 404 or 410 response transitions the page to `archived`. YouTube videos are probed via the transcript system — a deleted or private video triggers `archived`. Network timeouts and other transient errors leave the page unchanged (conservative: no false positives from transient failures).

**Stale — URL content is old**

To flag URL-sourced pages that have not been re-ingested recently:

```toml
[audit]
url_staleness_days = 90   # 0 = never flag (default)
```

When non-zero, lint compares the `ingested_at` timestamp in the audit database to today. Pages older than the threshold are marked `stale`, prompting a re-ingest:

```bash
synthadoc ingest "https://example.com/article" --force
```

### Audit trail

Every state transition — automated by lint or triggered manually — is permanently appended to an immutable event log. The log captures the slug, the previous state, the new state, who triggered the change (`ingest`, `lint`, `cli`, or `api`), the timestamp, and the reason.

```bash
synthadoc lifecycle log konrad-zuse
```

```
[wiki: history-of-computing]
Slug          From    To      By      Timestamp            Reason
konrad-zuse   null    draft   ingest  2026-05-28T14:58:50  new page created by ingest
konrad-zuse   draft   active  lint    2026-05-28T17:54:51  lint passed
konrad-zuse   active  stale   lint    2026-05-28T18:11:13  source file modified since last ingest
konrad-zuse   stale   draft   ingest  2026-05-28T18:30:56  re-ingest of stale page
konrad-zuse   draft   active  lint    2026-05-28T18:31:23  lint passed
```

> For enterprise wikis, this trail answers the compliance questions: "when was this page reviewed, by what process, and why was it changed?" — without requiring anyone to maintain that record manually.

#### Snapshots and content recovery

Synthadoc automatically captures a **content snapshot** — a frozen copy of the page body
— every time anything meaningful happens to a page. Three situations trigger a snapshot:


| Trigger                          | What causes it                                                                                                                                                             | Example                                        |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| **Manual lifecycle transition**  | You activate, archive, or restore a page via the CLI, Obsidian plugin, API, or the MCP`synthadoc_lifecycle` tool                                                           | `synthadoc lifecycle activate konrad-zuse`     |
| **Lint-driven state change**     | Lint promotes a page, marks it stale, archives it for a missing source, or auto-resolves a contradiction                                                                   | `synthadoc lint run --auto-resolve`            |
| **Manual file edit in Obsidian** | You edit a wiki page directly in Obsidian; the plugin detects the save and sends the content to the server (2-second debounce, only records when content actually changed) | Edit`wiki/orphan-page.md` in Obsidian and save |

Snapshots are listed **newest-first**. Index 1 is always the most recent snapshot; older
snapshots carry higher index numbers.

> **Deduplication for manual edits:** the Obsidian plugin compares the saved content to
> the last stored snapshot before writing. If you save without changing anything, no
> snapshot is created. This keeps the snapshot history meaningful without accumulating
> identical entries.

---

**Walkthrough: view snapshot history, compare versions, and roll back**

**Setup — make an edit in Obsidian**

Open `wiki/konrad-zuse.md` in Obsidian and add the following sentence at the very end
of the page body:

```
Note: this claim needs a second source before the next release.
```

Save (Ctrl+S on Windows, Cmd+S on Mac) and wait three seconds. The Obsidian plugin
detects the change and automatically captures a snapshot of the page — no extra command
needed.

Verify two entries now appear in the history:

```bash
synthadoc lifecycle history konrad-zuse -w history-of-computing
```

```
Index  Timestamp (UTC)       From → To                     Content           Reason
----------------------------------------------------------------------------------------------------
    1  2026-08-07 10:15:00   active → active                4,026 chars       manual edit detected by Obsidian plugin
    2  2026-05-28 17:54:51   draft → active                 3,967 chars       lint passed
```

Index 1 (4,026 chars) is the Obsidian edit snapshot — the body with the added sentence.
Index 2 (3,967 chars) is the original activation body, before your edit.

**Step 1 — Browse in the Obsidian Content Snapshots tab**

Open the Obsidian plugin → find `konrad-zuse` → **Manage Page Lifecycle** → switch to the
**Content Snapshots** tab. Type `konrad-zuse` in the **Filter by slug…** input to narrow
the list to this page.

Two rows appear, newest first. The `draft → active` row is the original activation body —
the one you want to compare against.

![Synthadoc Content Snapshots tab — list of snapshots for a page with diff view and rollback](png/synthadoc-lifecycle-snapshots.png)

**Step 2 — View the diff**

Click **View** on the `draft → active` row. An inline diff opens comparing that snapshot
against the current wiki file — added lines in green, removed lines in red, YAML
frontmatter stripped so the diff focuses on content only.

The diff shows the sentence you added:

```diff
+ Note: this claim needs a second source before the next release.
```

```bash
# Equivalent CLI approach — find the index of the draft → active row and export it:
synthadoc lifecycle history konrad-zuse --index 2 --show-content -w history-of-computing > original.md
diff original.md wiki/konrad-zuse.md
```

![Synthadoc snapshot diff view — line-by-line comparison with added/removed lines highlighted and Rollback button](png/synthadoc-lifecycle-snapshot-diff.png)

**Step 3 — Roll back to the original body**

**Via Obsidian:** you are already on the diff view from Step 2 — click **Rollback to this
version**. The plugin saves the current (edited) body as a new snapshot first, then
overwrites the wiki file with the original — removing the added sentence.

**Via CLI:**

```bash
synthadoc lifecycle rollback konrad-zuse --index 2 --reason "removing accidental note" -w history-of-computing
```

After the rollback the added sentence is gone and the wiki file is back to 3,967 chars.

**Step 4 — Confirm: the history gained one entry**

```bash
synthadoc lifecycle history konrad-zuse -w history-of-computing
```

```
Index  Timestamp (UTC)       From → To                     Content           Reason
----------------------------------------------------------------------------------------------------
    1  2026-08-07 10:22:00   active → active                4,026 chars       rollback:2:removing accidental…
    2  2026-08-07 10:15:00   active → active                4,026 chars       manual edit detected by Obsidian plugin
    3  2026-05-28 17:54:51   draft → active                 3,967 chars       lint passed
```

Index 1 is the rollback record — the edited body auto-saved before the overwrite, so the
rollback is always undoable. Roll back to index 1 to get the edited body back.

> **Lifecycle transitions also capture snapshots.** Every time a page changes state —
> draft → active, active → archived, and so on — Synthadoc records a snapshot at that
> moment, with the same diff and rollback support. You do not need to edit a page in
> Obsidian to build up a snapshot history; routine lifecycle events produce it
> automatically.

---

**Common use cases:**

- Undo an accidental edit made directly in Obsidian
- Recover content overwritten by a failed re-ingest
- Audit exactly what a page said when it first went live
- Undo a rollback by rolling back to the index-1 record that was auto-saved before it

#### Content Snapshots tab — reference

The **Content Snapshots** tab in the **Manage Page Lifecycle** modal is the Obsidian
surface for everything above.

**What the tab shows:**

- All snapshots across all pages, sorted by slug then by index when unfiltered
- Snapshot index (1 = newest per slug), the state transition that triggered it, who
  triggered it (`lint`, `cli`, `api`, `MANUAL_EDIT`), the timestamp, and the content size
- A **Filter by slug…** input with a × clear button to narrow the list to one page

**Actions:**

- **Click any row** — opens the corresponding wiki page in the main Obsidian panel
- **View** — opens the inline diff described in Step 2 above
- **Rollback** — executes the rollback described in Step 3 above; the current body is
  always saved first, so every rollback is undoable

---

<a name="resolve-contradiction"></a>

## Step 9 — Resolve a contradiction

After `first-compiler-controversy.pdf` is processed, `wiki/grace-hopper.md` will have:

```yaml
status: contradicted
```

The PDF argues that Hopper's A-0 was a loader rather than a compiler, and that FORTRAN
(1957) was the first production compiler — contradicting the existing page.

**Check via CLI:**

```bash
synthadoc lint report
```

```
Contradicted pages (1) - need review:

  grace-hopper
    -> Open wiki/grace-hopper.md, resolve the conflict, then set status: active
    -> Or run: synthadoc workflow run --name contradiction-resolver
```

**In Obsidian:** open `wiki/dashboard.md` — `grace-hopper` appears in the
**Contradicted pages** Dataview table. The Properties panel shows `status: contradicted`.

![Dashboard showing contradicted page](png/synthadoc-wiki-conflict.png)

### Option 1 — Agentic contradiction resolver (recommended)

The contradiction resolver is a conversational workflow that walks through each
contradicted page one at a time, proposes a fix, shows you the exact diff, and
asks for your approval before writing anything.

> **Two sources of contradicted pages**
>
> - **Source conflict** — a newly ingested document contradicts an existing page;
>   the page is flagged `status: contradicted` with a `contradiction_note`
>   describing the conflict. This is the scenario demonstrated in this step.
> - **Adversarial gate** — during a lint run the adversarial reviewer flags a page
>   for dubious or unsupported claims at or above the configured threshold (see
>   Step 27). The page is auto-demoted to `contradicted`. The resolver handles both
>   types through the same workflow.

> **Web UI not started yet?** Run `synthadoc web -w history-of-computing` — your browser opens automatically. Full web UI walkthrough is in [Step 22](#web-chat-ui).

**From the web UI:**

After any response that mentions contradicted pages — a lint run, a status query,
or a lint report — a pre-filled suggestion appears below the assistant's reply:

> "1 page marked contradicted — run the contradiction resolver to fix them interactively?"

Click it to send. The suggestion fires automatically whenever the LLM's answer
includes a non-zero contradicted page count; it clears once you act on it.

"Run contradiction resolver" also appears as a chip in the sidebar whenever the
chat mode is set to **Health Check** or **Power User**, and as a follow-up chip
after any response about lint or contradiction topics.

Alternatively, type:

> "Run contradiction resolver"

The resolver will:

1. Show the list of contradicted pages and a cost estimate, then ask "Proceed?"
2. For each page: read the current content and the conflicting source, propose a
   rewrite that reconciles both views fairly, and display the full unified diff.
3. Ask "Apply this change?" — you approve or skip each one individually.
4. After you approve, re-lint only that page. If it passes, the page is
   automatically promoted to *active*. If it fails, a different strategy is tried
   (up to 3 attempts per page).
5. Print a final summary: fixed, unresolved, and skipped counts, followed by the
   updated lifecycle state counts as ground truth.

**From the CLI:**

```bash
# Resolve all contradicted pages
synthadoc workflow run --name contradiction-resolver

# Resolve only the grace-hopper page
synthadoc workflow run --name contradiction-resolver --slug grace-hopper

# Resolve only adversarial-gate demotions
synthadoc workflow run --name contradiction-resolver --type adversarial

# Resolve only source-conflict demotions
synthadoc workflow run --name contradiction-resolver --type source-conflict
```

The CLI renders the same approval prompts and diff previews as the web UI.

### Option 2 — Manual resolution

1. Open `wiki/grace-hopper.md` in Obsidian
2. Edit the body to reflect a nuanced view — Hopper pioneered automated code generation
   with A-0; Backus and IBM delivered the first production compiler with FORTRAN in 1957
3. Change `status: contradicted` → `status: active` in the Properties panel
4. Save — the Contradicted pages table clears immediately

This is fast for a single well-understood conflict, but leaves no lifecycle audit record
of the reasoning.

### Option 3 — LLM auto-resolve (headless)

```bash
synthadoc lint run --auto-resolve
synthadoc jobs status <job-id>
```

The LLM proposes a resolution, appends it as a `**Resolution:**` block, and sets
`status: active`. No approval step — suitable for CI or batch processing where
interactive review is not practical.

Or from Obsidian: Command Palette → `Synthadoc: Lint: run with auto-resolve`.

### Option 4 — Resolve via MCP (Claude Desktop or Claude Code)

> **Prerequisite:** Synthadoc must be registered as an MCP server in Claude. See [Appendix I — Connect Claude via MCP](#appendix-i--connect-claude-via-mcp) for the `claude mcp add` command and Claude Desktop config.

With Synthadoc connected as an MCP server, Claude can resolve contradictions using its
own LLM — the brain/memory architecture in action. Claude reasons about the conflict,
writes the resolution, then commits the lifecycle transition with a proper audit trail.

Ask Claude in a single prompt:

> "The grace-hopper page is contradicted. Read it, resolve the A-0 compiler controversy by presenting both scholarly views fairly, update the page, then mark it active with a reason."

Claude will execute this as three tool calls in sequence and produce an audit trail:

```
Slug          From          To      By    Timestamp            Reason
grace-hopper  null          draft   ingest  2026-05-28T14:58:50  new page created
grace-hopper  draft         active  lint    2026-05-28T17:54:51  lint passed
grace-hopper  active  contradicted  lint    2026-05-28T18:30:00  conflict: A-0 compiler claim
grace-hopper  contradicted  active  mcp     2026-06-18T21:45:00  Resolved: A-0 controversy — both views preserved
```

> **Dashboard still showing the contradiction?** Dataview may be serving stale metadata.
> Drop the cache: `Ctrl/Cmd+P` → **Dataview: Drop all cached file metadata**, then reopen
> `dashboard.md`. If `synthadoc lint report` shows "all clear", the file is already
> correct — Dataview just has not caught up yet.

---

<a name="fix-orphan"></a>

## Step 10 — Fix an orphan page

The pre-built demo wiki includes `wiki/ada-lovelace.md`, but no other page links to it.
That makes it an **orphan** — a page with no inbound `[[wikilinks]]`.

**Check via CLI:**

```bash
synthadoc lint report
```

```
Orphan pages (2) - no inbound links:

  ada-lovelace
    -> Add [[ada-lovelace]] to a related content page, e.g.:
         - [[ada-lovelace]] — computing history, programming languages, operating systems, hardware innovation
  quantum-computing-primer
    -> Add [[quantum-computing-primer]] to a related content page, e.g.:
         - [[quantum-computing-primer]] — Quantum Computing Primer
```

**In Obsidian:** open `wiki/dashboard.md` — `ada-lovelace` and `quantum-computing-primer` appear in the **Orphan pages**
Dataview table.

> **Note on Graph view:** Obsidian's Graph view draws edges for both inbound and outbound
> links, so an orphan page that contains its own `[[wikilinks]]` to other pages may appear
> connected. Synthadoc defines an orphan as having **no inbound links** — always use
> `synthadoc lint report` as the authoritative check.

### Option 1 — Agentic orphan resolver (recommended)

The orphan resolver is a conversational workflow that finds each orphan page one at a time,
searches for the best page to link it from using up to four strategies, shows you the exact diff,
and asks for your approval before writing anything.

> **Web UI not started yet?** Run `synthadoc web -w history-of-computing` — your browser opens automatically. Full web UI walkthrough is in [Step 22](#web-chat-ui).

**From the web UI:**

Open the web chat UI. You have four entry points:

- **Hint chip:** The **"Run orphan resolver"** chip appears in the sidebar whenever the wiki has at least one orphaned page — click it to start immediately.
- **Pre-filled suggestion:** After any response that mentions orphaned pages — a lint run, a status query, or a lint report — a pre-filled prompt appears below the reply — click it directly:

  > *2 orphaned pages detected — run the orphan resolver to link them interactively?*
  >
- **Graph tab:** Orphaned pages appear as isolated nodes at the edges of the knowledge graph. A **"Run orphan resolver"** chip is shown in the Graph tab sidebar when isolated nodes are present — click it without leaving the graph view.
- **Free text:** Type **"run orphan resolver"** at any time.

The resolver will:

1. Call `tool_find_orphaned_pages`, show the list and a cost estimate, then ask "Proceed?"
2. For each orphan: try up to four progressively broader search strategies to find a natural host page:
   - `title_bm25` — BM25 keyword match on the orphan's title
   - `content_bm25` — BM25 keyword match on the orphan's first paragraph
   - `full_title_scan` — LLM selects from a dump of all active page titles
   - `contextual_reasoning` — LLM uses the full orphan body for richer judgment
3. Propose a contextually natural `[[wikilink]]` insertion into the best candidate, and display the full unified diff.
4. Ask "Apply this change?" — you approve or skip each one individually.
5. After you approve, run a graph-level re-check to confirm the orphan is resolved before moving on.
6. Ask "Continue to next orphan?" — you can stop at any point.
7. Print a final summary: resolved, unresolved, and skipped counts.

> **Side-effect resolution:** Fixing one orphan often incidentally links a second. The pre-check at the start of each orphan's loop catches this and marks it as resolved with no extra LLM calls.

> **If all four strategies are exhausted**, the workflow escalates with a notice listing every candidate page considered and four concrete next steps: re-run the workflow (LLM non-determinism may produce a better candidate), manually add the wikilink, archive the page if it's out of scope, or create a hub page and re-run.

**From the CLI:**

```bash
# Resolve all orphaned pages
synthadoc workflow run --name orphan-resolver

# Resolve only the ada-lovelace page
synthadoc workflow run --name orphan-resolver --slug ada-lovelace
```

The CLI renders the same approval prompts and diff previews as the web UI.

### Option 2 — Manual link insertion

Open `wiki/programming-languages-overview.md` and add a reference:

```
Ada Lovelace is widely credited as [[ada-lovelace|the first programmer]], having written
the first algorithm intended to be executed by Charles Babbage's Analytical Engine in 1843.
```

Save — the orphan disappears from the dashboard immediately.

This is fast for a single well-understood orphan, but leaves no lifecycle audit record of
the reasoning.

### Option 3 — Resolve via MCP (Claude Desktop or Claude Code)

> **Prerequisite:** Synthadoc must be registered as an MCP server in Claude. See [Appendix I — Connect Claude via MCP](#appendix-i--connect-claude-via-mcp) for the `claude mcp add` command and Claude Desktop config.

With Synthadoc connected as an MCP server, Claude can fix orphans autonomously — it reads the wiki, finds a relevant page to add the link to, writes the change, and re-runs lint to confirm the fix.

**Step 1 — Find orphans:**

> "Are there any orphan pages in my history-of-computing wiki?"

Claude calls `synthadoc_lint_report` for the authoritative orphan list (instant, no LLM cost). For the demo wiki this returns `mechanical-computing` among the orphans.

**Step 2 — Fix the orphan:**

> "The mechanical-computing page is an orphan. Find the most relevant page in the wiki and add a wikilink to it."

Claude reads `mechanical-computing`, notices it already contains `[[von-neumann-architecture]]` in its body, and recognises this as a natural reciprocal — `von-neumann-architecture` should link back. It adds:

```
The concept of a general-purpose programmable machine with distinct memory,
arithmetic, and control components was anticipated by Charles Babbage's
Analytical Engine designs of the 1830s — see [[mechanical-computing]] for
the pre-electronic tradition that foreshadowed this architecture by over a
century.
```

Claude calls `synthadoc_write_page` to insert this into `von-neumann-architecture`.

**Step 3 — Verify:**

> "Re-run lint report and confirm mechanical-computing is no longer an orphan."

Claude calls `synthadoc_lint_report` again — `mechanical-computing` is gone from the orphan list.

> **Why Claude chose von-neumann-architecture:** `mechanical-computing` already contained `[[von-neumann-architecture]]` — making it a natural reciprocal link rather than a forced one. Claude read the page content before deciding, not just the slug names.

To archive an orphan that is genuinely out of scope instead:

> "Archive the mechanical-computing page — it's an orphan and not relevant to this wiki."

Claude calls `synthadoc_lifecycle` with `to_state="archived"` and a reason, writing a permanent audit record.

### Option 4 — Delete and re-ingest later

If the page content quality is poor, delete `wiki/ada-lovelace.md` from Obsidian and
pull in a fresh source via web search:

```bash
synthadoc ingest "search for: Ada Lovelace contributions to computing history"
```

### Deleting a page and cleaning up its references

When a page is archived — whether via `synthadoc lifecycle archive`, the Obsidian Lifecycle modal, the MCP `synthadoc_lifecycle` tool, or automatically by lint detecting that all source files are gone — Synthadoc immediately removes all `[[page-name]]` wikilinks pointing to it from every other active page. No extra `lint run` is required.

- Inline links (`[[old-page]]`) become plain text.
- List-item-only links (`- [[old-page]]`) are dropped entirely.
- Already-archived pages and system pages (index, dashboard, purpose) are not rewritten.

The CLI reports which pages were updated:

```
synthadoc lifecycle archive old-page -w my-wiki --reason "replaced by updated source"
  old-page: active -> archived
  Cascade: [[old-page]] removed from 2 page(s): cpu-design, transistor-history
```

If a page has multiple source files and only some are missing from disk, lint marks it `stale` (not archived) so you can re-ingest the surviving sources. The page is only auto-archived when every local source file is gone.

Lint's dangling-link cleanup (`lint run`) remains available as a safety net for any dead links that predate a v1.0.2 upgrade or arrive through other paths.

---

<a name="adversarial-review"></a>

## Step 11 — Run the adversarial review

Standard lint validates wiki structure — contradictions, orphan pages, dangling links. The
**adversarial review** adds a second independent LLM pass that interrogates every page for
epistemic overreach: overstated claims, unsupported assertions, and high-confidence statements
the source material does not support.

The adversarial review runs automatically as part of every `synthadoc lint run`. No extra flag is
needed.

### Run lint with adversarial review

```bash
synthadoc lint run
synthadoc jobs list           # watch progress
synthadoc lint report         # view results when complete
```

The pre-built pages already contain the kinds of sweeping historical claims an adversarial
reviewer will flag — no additional ingest is needed before this step, though running Step 6
first gives the adversarial review more content to work with.

The reviewer flags **up to 3 issues per page by default** (configurable via `adversarial_max_per_page` in `config.toml`) and only flags claims it is highly confident
about — defensible or nuanced statements are skipped. The full history-of-computing demo
wiki (13 pre-built pages plus pages created in Step 6) typically produces **10–15 warnings**,
giving a meaningful but not overwhelming signal.

Sample output for the history-of-computing demo wiki (after Step 6 batch ingest; exact
wording varies by LLM):

```
Contradicted pages (0)
Orphan pages (0)

Adversarial warnings (3):

  alan-turing
    Claim:   "Saved over fourteen million lives."
    Concern: This specific figure lacks scholarly consensus — historians dispute both any
             precise death-count and the causal attribution of lives saved to Turing's
             cryptanalysis alone. The claim conflates a speculative timeline reduction with
             a precise casualty figure that is unsupported in academic literature.

  artificial-intelligence-history
    Claim:   "These systems exhibit emergent capabilities that were not explicitly programmed."
    Concern: "Emergence" in large language models is disputed — several researchers argue
             that capability gains are smooth and predictable at scale, and that the label
             "emergent" reflects measurement choices rather than a genuine phase transition.

  personal-computer-revolution
    Claim:   "IBM's decision to build the PC from off-the-shelf parts ... was the most
             consequential business decision of the era."
    Concern: An unsupported superlative — Microsoft's retention of the MS-DOS licence and
             Intel's exclusive CPU supply deal were equally pivotal; "most consequential"
             requires a comparison the text does not make.
```

> **Note:** Re-ingest suggestions only appear for pages whose sources were ingested from local
> files (absolute paths) or URLs. Pre-built demo pages use placeholder source references,
> so no re-ingest command is shown — use `synthadoc ingest <source>` manually if needed.

### What each warning means

Each adversarial warning has two parts:


| Field       | Meaning                                                         |
| ----------- | --------------------------------------------------------------- |
| **Claim**   | The exact sentence or phrase flagged as potentially problematic |
| **Concern** | Why the adversarial reviewer flagged it — the specific doubt   |

The adversarial LLM is deliberately skeptical. Not every warning requires action — some claims
are defensible with context the LLM does not have. Read each concern before deciding what to do.

### What to do with a warning


| Situation                                              | Action                                                                     |
| ------------------------------------------------------ | -------------------------------------------------------------------------- |
| Claim is accurate, concern is addressed by other pages | Do nothing — the wiki is fine                                             |
| Claim is a genuine overstatement                       | Edit the page in Obsidian and soften the language                          |
| Source has been updated since last ingest              | Re-ingest with`--force` to bypass dedup: `synthadoc ingest <file> --force` |
| Claim needs a counterbalancing perspective             | Ingest a different source:`synthadoc ingest <other-source>`                |
| Page quality is poor overall                           | Delete the page and re-ingest:`synthadoc ingest <new-source>`              |

> **Re-ingesting the same unchanged source won't fix an overstatement.** The LLM will read
> the same text and likely produce the same claim. For overstatements, edit the page directly
> in Obsidian. Use `--force` only when the source document itself has new or updated content.

### Hands-on exercise

The `alan-turing` warning flags the "fourteen million lives" figure as lacking scholarly
consensus. Fix it:

1. Open `wiki/alan-turing.md` in Obsidian
2. Find the sentence in the **Wartime Contributions** section that mentions lives saved
   (added when you ingested `turing-enigma-decryption.pdf` in Step 6)
3. Remove the specific casualty figure and replace with qualified language:
   ```
   Historians credit Turing's Bombe with dramatically accelerating Allied codebreaking,
   though estimates of the war's duration and lives affected vary widely across sources.
   ```
4. Save — the next lint run will re-evaluate the page and the warning will clear

### Verify the warning cleared

```bash
synthadoc lint run
synthadoc lint report
```

The `alan-turing` adversarial warning should no longer appear.

### View warnings in Obsidian

Open the Command Palette (`Ctrl/Cmd+P`) → `Synthadoc: Lint: report` → click the
**Adversarial** tab. Flagged claims and the **⚠** icon appear in **orange** so warnings
stand out immediately. The **Concern:** label is also orange; the concern text itself is
muted for readability. Suggested re-ingest commands appear below each entry.

The same label-coloring convention applies across all tabs: **Why flagged:** in the
Contradictions tab uses orange, and **Suggested index entry:** in the Orphans tab uses
accent blue (it is a suggestion, not a warning), so you can scan the full report at a
glance without reading every line.

![Synthadoc Lint report — Adversarial tab showing flagged claims across multiple pages](png/lint-report-adversarial.png)

> **Skip the adversarial pass:** If you want a fast structural-only lint, open
> `Synthadoc: Lint: run...` and tick **Skip adversarial review**. This also clears any
> existing `lint_warnings` from frontmatter so stale warnings do not linger.

### Optional — adjust the warning cap

By default the adversarial reviewer flags at most 2 issues per page. Raise the cap for a thorough audit; lower it to reduce noise on large wikis:

```toml
# config.toml
[lint]
adversarial_max_per_page = 3  # must be >= adversarial_gate_threshold; raise to 4–5 for a deeper review
```

If `[lint]` is absent from `config.toml`, Synthadoc defaults to 2 — no file change needed.

### Optional — automatic page demotion (adversarial gate)

When a page accumulates too many adversarial warnings it is a signal that its claims are contested and it should not be serving as an authoritative source in query answers. The **adversarial gate** automates this: at the end of every lint run, any `active` or `stale` page whose warning count reaches or exceeds the threshold is automatically transitioned to `contradicted`.

New wikis created with `synthadoc init` have the gate enabled at `2` by default. Existing wikis upgrading to v1.3.0 have the gate disabled — enable it by adding one line to `config.toml`:

```toml
# config.toml
[lint]
adversarial_gate_threshold = 2   # recommended: 2 (general), 1 (compliance-sensitive)
```

The demotion is auditable — it appears in `synthadoc lifecycle log` with reason `"auto-demoted: N adversarial warning(s) ≥ gate threshold T"` — and is reversible with `synthadoc lifecycle activate <slug> --reason "..."` after you resolve the flagged claims.

Pages already in `contradicted`, `archived`, or `draft` states are never affected by the gate. Setting the value to `0` or removing the key disables the gate entirely.

The number of pages auto-demoted during each lint run is shown in `synthadoc lint report` under the **Adversarial** tab as **Auto-demoted**.

### Optional — appoint a dedicated judge model

By default the adversarial review shares the lint model. The most effective configuration is a
*different provider entirely*: a model from a distinct family, trained on different data with
different inductive biases, will surface blind spots and challenge assumptions that the primary
model would systematically miss. Same-model self-review has limited value; cross-model review
does not:

```toml
# config.toml
[agents]
lint        = { provider = "minimax",   model = "MiniMax-M3", thinking = "disabled" }
adversarial = { provider = "anthropic", model = "claude-sonnet-4-6" }   # independent judge — different model family, different inductive biases
```

The two providers are intentionally different — when a model from one family reviews the
output of a model from another, neither shares the training-induced assumptions that cause
same-model review to miss systematic errors.

---

<a name="web-search-ingest"></a>

## Step 12 — Web search ingestion

> **Requires `TAVILY_API_KEY`** — see [Appendix D](#appendix-d--tavily-web-search-key).
> Without it, web search jobs fail with `[ERR-SKILL-004]`. All other features work normally.

### How web search decomposition works

Synthadoc **decomposes web search topics** into multiple focused keyword sub-queries
before hitting Tavily. Each sub-query fires a separate parallel search, URLs are
deduplicated across all results, and each is enqueued as an individual ingest job.
This produces richer, more targeted pages than a single broad search.

```
Input: "search for: history of ARPANET and internet origins"

Server log:
  web search decomposed into 3 queries:
    "ARPANET creation 1969 DARPA" | "TCP/IP protocol development history" | "internet origins packet switching"

Result: 3 parallel Tavily searches → ~60 URLs ingested vs ~20 from a single search
```

Decomposition falls back gracefully — if the LLM call fails, the original phrase is used as
a single query and the ingest always completes.

### Run a web search ingest

```bash
synthadoc ingest "search for: Dennis Ritchie C programming language Bell Labs history"
synthadoc ingest "search for: ENIAC first general purpose electronic computer history"
```

Each command fans out to up to 20 URL ingest jobs. The commands return immediately —
all processing happens in the background. Watch progress with:

```bash
synthadoc jobs list
```

> **How long does it take?**
>
> - **Free-tier Gemini (15 RPM) or Groq:** Two searches produce ~20–40 LLM calls. The
>   server retries automatically when the rate limit is hit (you will see
>   `Rate limit (429) — waiting 60 s` in the server log — this is normal). Expect
>   **3–8 minutes** for both searches to fully complete.
> - **Paid tier or free-trial tier (Gemini paid, MiniMax, Anthropic, OpenAI, Qwen DashScope):** No rate-limit retries.
>   Both searches typically finish in **under 2 minutes**.
>
> **Recommendation:** Web search ingest works best with a paid or free-trial provider.
> Qwen DashScope offers **1 million free tokens** (90-day trial) with no rate-limit delays —
> a good option if you want free-tier speed without the wait.
> See [Appendix C — Switching LLM providers](#appendix-c--switching-llm-providers).

Pages such as `dennis-ritchie`, `eniac-history`, and related topics will be created or
enriched. The `wiki/overview.md` page is regenerated automatically after each batch
completes.

### Control the scope

Limit how many URLs are enqueued (default: 20):

```bash
synthadoc ingest "search for: quantum computing IBM Google" --max-results 5
```

**Batch via manifest file:** the demo wiki ships a `sources.txt` at the wiki root (outside `raw_sources/` — a `.txt` inside that folder would be treated as a text document rather than a manifest). It already contains these web search entries alongside YouTube and PDF sources:

```
search for: Dennis Ritchie C programming language Bell Labs history
find on the web: Linus Torvalds Linux kernel creation 1991
search for: Ada Lovelace first programmer Analytical Engine Babbage
look up: history of ARPANET and internet origins
```

Ingest all sources at once:

```bash
synthadoc ingest --file sources.txt
```

### Web search from Obsidian — live view

Open the Command Palette → `Synthadoc: Ingest... → web search tab`:

1. Type a topic — e.g. `Linus Torvalds Linux kernel creation 1991`
2. Set **Max results** (1–50, default 20) to control scope
3. Adjust **Poll interval** if desired (default: 2000 ms)
4. Press `Ctrl/Cmd+Enter` or click **Search**

The modal transitions to a live view:

- **Searching the web…** — while Tavily fetches
- **Found N URLs — ingesting…** — as fan-out jobs are created
- **Ingesting N URLs… (M done)** — counting completed child jobs
- A **Pages** list grows in real time as each URL ingest completes
- **Errors** (blocked domains, 404s) appear in red
- **Done — N page(s) written.** when all jobs settle

![Obsidian web search live view](png/synthadoc-search-live-view.png)

The modal prepends `search for:` automatically — just type the topic, no prefix needed.

---

<a name="youtube-ingest"></a>

## Step 13 — Ingest a YouTube video

Pass any YouTube URL directly — the transcript is extracted automatically from the
YouTube caption system (no API key, no audio download). Both the full URL and the
short-link form (`https://youtu.be/...`) are accepted:

```bash
synthadoc ingest "https://www.youtube.com/watch?v=O5nskjZ_GoI"
```

This ingests *Early Computing: Crash Course Computer Science #1*, which covers Hollerith,
Babbage, Lovelace, and the first programmable machines — a natural fit for the demo wiki.
The YouTube entries in `sources.txt` (see Step 10) include this video, so running
`synthadoc ingest --file sources.txt` handles it alongside the web searches.

The wiki page opens with an **executive summary** — a brief description of what the video
covers, the main topics as bullet points, and the key takeaway — so you can assess
relevance at a glance. The full timestamped transcript follows for precise cross-referencing.

> **Captions required** — the video must have captions (auto-generated or manually added).
> Check by opening the video on YouTube → `...` → **Show transcript**. If no transcript
> panel appears, the source is skipped with a warning and ingestion continues.

> **Short vs. long videos** — short videos produce a single wiki page. Long videos are
> chunked automatically by the existing `max_pages_per_ingest` limit.

Watch progress:

```bash
synthadoc jobs list
```

> **Tavily search + YouTube** — if Tavily returns YouTube URLs as web search results, they
> are automatically routed to the YouTube transcript skill. No extra steps needed.

---

<a name="scaffold"></a>

## Step 14 — Enrich the wiki with scaffold

After batch ingest, the wiki has grown from 10 pre-built pages to 12 or more. **Scaffold**
reads the current wiki state and uses the LLM to regenerate the structure files —
`wiki/index.md`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and `wiki/purpose.md` — so they
reflect what the wiki has actually become. Existing pages that are already linked in
`index.md` are detected as **protected slugs** and preserved; only unlinked and new
categories are refreshed.

> **Upgrading an existing wiki?** If your wiki was created with an earlier version of
> Synthadoc, running `synthadoc scaffold` is all you need to get `CLAUDE.md` and
> `GEMINI.md` for the first time. The command regenerates all three skill files with
> LLM-produced domain guidelines that match your current wiki content.

### Run scaffold

```bash
synthadoc scaffold
```

Expected output:

```
Reading current wiki content…
Generating domain-specific scaffold (History of Computing)…
  Protected slugs: alan-turing, grace-hopper, von-neumann-architecture, unix-history, … (10 pages)
  Scaffold complete — domain-specific content generated.
wiki/index.md updated
AGENTS.md   updated
CLAUDE.md   updated
GEMINI.md   updated
wiki/purpose.md updated
```

Open `wiki/index.md` in Obsidian — it now has richer category headings that reflect the
full post-ingest wiki (e.g. **Pioneers and Visionaries**, **Hardware Milestones**,
**Software and Languages**, **European Computing**, **Emerging Technology**).

### Re-run scaffold at any time

As the wiki grows, re-running scaffold keeps the index structure current and refreshes
all three agent skill files with updated domain guidelines:

```bash
synthadoc scaffold
```

`config.toml` and `dashboard.md` are **never touched** by scaffold.

### Schedule scaffold automatically

To keep the index fresh without manual intervention:

```bash
# Weekly scaffold refresh — every Sunday at 4 AM
synthadoc schedule add --op "scaffold" --cron "0 4 * * 0"
```

### Protect custom content with the scaffold marker

By default, re-running scaffold rewrites the entire `index.md`. If you want to add your own
intro text, notes, or links that survive future scaffold runs, add the marker on its own line:

```markdown
My custom wiki intro — maintained by hand.

<!-- synthadoc:scaffold -->

## Pioneers and Visionaries
- [[alan-turing]]
...
```

Everything **above** the marker is your protected zone — scaffold never touches it.
Everything **below** is rewritten each time. If the marker is absent, scaffold rewrites
the whole file as before.

### Per-section markers in purpose.md

`wiki/purpose.md` uses a more granular approach — each `## Section` has its own marker. This lets you annotate individual sections (for example, add a note about what kind of sources belong in the wiki) without losing your annotations when scaffold regenerates the rest.

```markdown
## Overview

My organization-specific note about this wiki.

<!-- synthadoc:scaffold -->

LLM-generated overview content refreshed each scaffold run.

## What Belongs

<!-- synthadoc:scaffold -->

LLM-generated scope definition — no custom note above, so only this line is rewritten.
```

Text you write **above** the marker in any section is preserved. Text below is refreshed.
Sections where you have not added a marker are treated the same as before (fully refreshed).

→ Full design spec: [Design §34 — Synthadoc Scaffold Marker](design.md#34-synthadoc-scaffold-marker)

---

<a name="audit"></a>

## Step 15 — Audit features

The `synthadoc audit` commands query the append-only `audit.db` — no `sqlite3` required.

### Ingest history

```bash
synthadoc audit history
```

Shows the last 50 ingest records: timestamp, source file, wiki pages created/updated,
token count, and cost. Use `--limit N` (or `-n N`) for more records, `--offset N` to skip to a later page,
and `--json` for machine-readable output. The title line shows the total row count so you know how many
records exist (`50 of 312`). To page through: `synthadoc audit history -n 50 --offset 50` for records 51–100.
In the **Obsidian Audit modal**, the Ingest History tab is fully paginated with ← Prev / Next → buttons.

![synthadoc audit history output](png/synthadoc-audit-history.png)

### Cost summary

```bash
synthadoc audit cost
```

Expected output:

```
Period: last 30 days
Total tokens : 22,400
Total cost   : $0.143
Sources processed: 6
Avg cost/source  : $0.024
```

Pass `--days 7` for a weekly view. Per-model cost tracking is fully live in v0.2.0.

![synthadoc audit cost output](png/synthadoc-audit-cost.png)

### Query history

```bash
synthadoc audit queries
```

Shows recent questions asked, how many sub-questions each was decomposed into, token
usage, and per-query cost. Especially useful after running the compound queries in Step 5.
Use `--limit N` and `--offset N` to page through a large history:
`synthadoc audit queries -n 50 --offset 50` shows records 51–100.
The title shows the total count (`50 of 3782`) so you can tell how many records exist beyond the current page.
In the **Obsidian Audit modal**, the Query History tab is paginated (50 per page) with ← Prev / Next → navigation.

![synthadoc audit queries — query history table showing questions, sub-question count, tokens, and cost](png/audit-queries.png)

### Audit events

```bash
synthadoc audit events
```

Shows raw job-level audit events (start/finish, errors). Use `--limit N` and `--offset N` to page:
`synthadoc audit events -n 100 --offset 100` shows events 101–200.
Paginated in the Obsidian Audit modal (100 events per page) with ← Prev / Next → navigation and a total count in the page label.

Expected after Steps 6–10:

```
2026-04-21 10:12  contradiction_found   grace-hopper ← first-compiler-controversy.pdf
2026-04-21 10:14  auto_resolved         grace-hopper (confidence: 0.91)
```

Records every contradiction detection, auto-resolution, and cost gate trigger.

![synthadoc audit events output](png/synthadoc-audit-events.png)

---

<a name="scheduling"></a>

## Step 16 — Scheduling recurring operations

Hooks react to events that already happened. The scheduler goes the other direction —
it proactively triggers operations on a timer, keeping the wiki fresh automatically.

### Register a nightly batch ingest

```bash
synthadoc schedule add --op "ingest --batch raw_sources/" --cron "0 2 * * *"
```

This registers a 2 AM daily ingest directly with the OS scheduler (`crontab` on
macOS/Linux, Task Scheduler on Windows). No background daemon required.

### Register a weekly lint pass + weekly scaffold refresh

```bash
synthadoc schedule add --op "lint run" --cron "0 3 * * 0"
synthadoc schedule add --op "scaffold" --cron "0 4 * * 0"
```

### Verify

```bash
synthadoc schedule list
```

Expected output — each row now shows the schedule, next run time, last run, and last result:

```
ID                   Schedule           Next Run             Last Run             Last Result    Command
sched-a3f1b2c4       0 2 * * *          2026-05-31 02:00     —                    —              synthadoc ... schedule run --op "ingest --batch raw_sources/"
sched-b7e9d012       0 3 * * 0          2026-06-01 03:00     —                    —              synthadoc ... schedule run --op "lint run"
sched-c9f3e201       0 4 * * 0          2026-06-01 04:00     —                    —              synthadoc ... schedule run --op "scaffold"
```

Next run time is computed from the cron expression on macOS/Linux, and read from the OS Task Scheduler on Windows.

### Check run history

Each time a scheduled job fires, the outcome (status, duration, and any output or error) is recorded in the schedule history log. View recent runs:

```bash
synthadoc schedule history
```

```
Run ID               Op              Started              Duration    Status
------------------------------------------------------------------------
run-a1b2c3d4         lint run        2026-05-31 03:00       47.3s    success
run-342a7e95         ingest          2026-05-30 23:11        0.8s    failed
run-bc56dc6a         scaffold        2026-05-30 23:04       31.2s    success

Details
-------
run-a1b2c3d4  lint run  success
  Checked 47 pages. 2 adversarial warnings. 0 orphan pages.

run-342a7e95  ingest  failed
  exit code 1: MINIMAX_API_KEY is not set

run-bc56dc6a  scaffold  success
  Scaffold complete — domain-specific content generated.
```

The **Details** section only appears when runs have output to show. Successful runs display captured output; failed runs display the error. A `failed` run means either `synthadoc serve` was not running when the task fired, or the operation itself encountered an error. Re-run manually with `synthadoc schedule run --op "lint run"` to recover.

### Clean up the scheduled tasks

Remove the scheduled jobs when you no longer need them:

```bash
synthadoc schedule remove sched-a3f1b2c4
synthadoc schedule remove sched-b7e9d012
synthadoc schedule remove sched-c9f3e201
```

> **Production use:** for always-on scheduling, run `synthadoc serve` as a background
> service (systemd, launchd, or Windows Service) so the server is available when the OS
> fires the scheduled task. If a run is missed (server down or machine asleep), it will
> not automatically retry — check `synthadoc schedule history` for failures and re-run
> manually if needed.

---

<a name="routing"></a>

## Step 17 — Set up ROUTING.md — scoped search

As your wiki grows, BM25 searches the full corpus for every query. **ROUTING.md** groups pages
into named topic branches so queries only search the most relevant slice — reducing noise,
improving retrieval precision, and significantly cutting search latency on large wikis (see
[Appendix H](#appendix-h--bm25-routing-performance-benchmarks) for measured results).

![ROUTING.md scoped query flow](png/synthadoc-routing.png)

### Generate ROUTING.md from your current index

```bash
synthadoc routing init
```

This reads the `## Section` headings in `wiki/index.md` and writes `ROUTING.md` at the wiki
root. Example output:

```
ROUTING.md created — 5 branches, 12 slugs.
```

Open `ROUTING.md` — it looks like this:

```markdown
## Pioneers and Visionaries
- [[alan-turing]]
- [[grace-hopper]]
- [[ada-lovelace]]

## Hardware Milestones
- [[eniac]]
- [[von-neumann-architecture]]
```

### Manage routing in Obsidian

Open the Command Palette (`Ctrl/Cmd+P`) → **Synthadoc: Routing: manage ROUTING.md**. The modal shows the current ROUTING.md content and three actions: **Init** (generate from index.md), **Validate** (report dangling slugs and duplicates), and **Clean** (remove dangling entries).

![Synthadoc routing modal — ROUTING.md initialised, showing branch count confirmation and file content preview](png/synthadoc-routing-init.png)

### Edit and extend

Add new branches or move slugs by hand. ROUTING.md is just a Markdown file — the format is
`## BranchName` headings with `- [[slug]]` entries. Each slug should appear in exactly one branch.

If you accidentally list the same slug under two branches, the search result is still correct — `bm25_search` converts the scoped slug list to a set before scoring, so the page is never double-counted. However, the branch assignment becomes ambiguous: a query that picks either branch will find the page regardless of which one was intended. Use `routing validate` to catch these duplicates before they cause confusion.

### Validate and clean

After deleting wiki pages, some slugs in ROUTING.md may dangle. `routing validate` also reports slugs that appear in more than one branch:

```bash
synthadoc routing validate   # report dangling slugs and cross-branch duplicates (dry run)
synthadoc routing clean      # remove dangling slugs
```

Example output when a duplicate is found:

```
Issues in ROUTING.md (1):
  [Hardware]  [[alan-turing]] (duplicate — also in 'People')
```

Fix by removing the entry from the branch where it does not belong, then re-run `validate` to confirm.

### How it works at query time

When the server receives a query it asks the LLM to pick the 1-2 most relevant branches,
then restricts BM25 to only those slugs. If no branch is clearly relevant it falls back to
full-corpus search automatically.

New pages created by ingest are auto-placed into the most appropriate branch.

---

<a name="staging"></a>

## Step 18 — Configure candidates staging

By default, every ingested source that produces a new page writes it directly to `wiki/`.
**Candidates staging** lets you review new pages before they influence queries and lint.

### Enable staging

```bash
synthadoc staging policy threshold
```

With `threshold` policy, pages whose confidence is below the minimum go to
`wiki/candidates/` instead of `wiki/`. The default minimum is `high`:

```bash
# Lower the bar — medium-confidence pages also go to candidates/
synthadoc staging policy threshold --min-confidence medium
```

Or stage everything for full manual review:

```bash
synthadoc staging policy all
```

Changes take effect on the next ingest job — no server restart needed.

### Review candidates after an ingest run

```bash
synthadoc candidates list
```

Example output:

```
Candidates (3):
  early-internet-history           confidence: medium   ingested: 2026-05-06T14:22:11
  punch-card-era                   confidence: low      ingested: 2026-05-06T14:22:45
  vacuum-tube-computers            confidence: medium   ingested: 2026-05-06T14:23:01
```

![Candidates list in Obsidian](png/synthadoc-candidates.png)

### Promote or discard

```bash
synthadoc candidates promote early-internet-history   # move to wiki/
synthadoc candidates discard punch-card-era           # delete
synthadoc candidates promote --all                    # promote everything
```

### Manage staging from Obsidian

**Set the policy** — Command Palette → `Synthadoc: Staging: manage staging policy...`:

- The modal shows the current policy in plain language at the top.
- Click **Off**, **All**, or **Threshold** in the segmented control.
- When **Threshold** is selected, a second control appears — pick **High**, **Medium**, or **Low** as the minimum confidence.
- Click **Save**. The status block updates immediately to confirm the change.
- Click **Candidate pages →** at the bottom of the modal to jump straight to the Candidates panel.

**Review and promote candidates** — Command Palette → `Synthadoc: Candidates: review candidate pages...`:

- The modal lists every staged page with its slug, colour-coded confidence badge, and ingest timestamp.
- Check individual rows and click **Promote Selected** or **Discard Selected**.
- Use **Promote All** or **Discard All** to act on every candidate at once.
- The table reloads after each action, so the count stays current.
- Click **← Staging policy** at the bottom to jump back to the Staging modal.

### Turn staging off

```bash
synthadoc staging policy off
```

Or from Obsidian: `Synthadoc: Staging: manage staging policy...` → select **Off** → **Save**.

---

<a name="context-pack"></a>

## Step 19 — Build a context pack

A **context pack** is a token-bounded evidence bundle assembled from the wiki. It decomposes your goal into sub-questions, runs parallel BM25 searches across the wiki, and packs the highest-scoring excerpts into a single cited Markdown document within a token budget.

### Build a pack from the CLI

```bash
synthadoc context build "early computing pioneers"
```

Output is Markdown printed to the terminal:

```markdown
# Context Pack: early computing pioneers
Generated: 2026-05-07T09:14:22
Token budget: 4000 | Used: 1823

---

## [[alan-turing]] — relevance: 3.42
> Alan Turing developed the theoretical basis of modern computation through his 1936 paper
> on computable numbers. He proposed the concept of a universal machine capable of simulating
> any algorithm...
Source: `wiki/alan-turing.md` | Confidence: high | Tags: mathematics, computation

## [[grace-hopper]] — relevance: 2.91
> Grace Hopper pioneered compiler development and coined the term debugging after finding
> a moth in a relay. Her work on COBOL brought programming to business users...
Source: `wiki/grace-hopper.md` | Confidence: high | Tags: programming, navy

## [[ada-lovelace]] — relevance: 2.44
> Ada Lovelace wrote what is considered the first algorithm intended for a mechanical
> computer, the Analytical Engine designed by Charles Babbage...
Source: `wiki/ada-lovelace.md` | Confidence: high | Tags: mathematics, history

---

## Omitted — token budget exceeded
- [[charles-babbage]] — ~420 tokens
- [[john-von-neumann]] — ~390 tokens
```

Each entry is cited with its source page, confidence, and tags. Pages that did not fit within the budget are listed in the omitted section.

### Use cases

**Feed into an external LLM prompt** — paste the terminal output directly into Claude.ai, ChatGPT, or any other chat interface as grounded context before asking a question:

```bash
synthadoc context build "transistor history and Moore's Law" | pbcopy   # macOS — copies to clipboard
```

**Save next to a document you are writing** — keep the evidence bundle alongside your draft:

```bash
synthadoc context build "early computing pioneers" --output ~/drafts/computing-brief.md
```

**Pipe into another CLI tool** — chain with any tool that reads from stdin:

```bash
synthadoc context build "Von Neumann architecture" --output /tmp/ctx.md
llm -f /tmp/ctx.md "write a 500-word article based on this"
```

### Adjust the token budget

```bash
synthadoc context build "early computing pioneers" --tokens 2000
```

Set a permanent default in `config.toml`:

```toml
[query]
context_token_budget = 6000
```

### Build a context pack via MCP (Claude Code)

With Synthadoc registered as an MCP server, you can ask Claude to build a context pack directly inside a Claude Code session — no CLI needed.

> "Build me a context pack on early computing pioneers, budget 10,000 tokens."

Claude calls `synthadoc_context`, receives the ranked excerpt bundle, and can immediately reason over it or feed it into a follow-up synthesis prompt — all within the same conversation.

See the full step-by-step demo in [Appendix I — Demo: context pack via Claude Code](#appendix-i--connect-claude-via-mcp), including a real example output from the history-of-computing wiki (1,280 / 10,000 tokens used).

> **Prerequisite:** Synthadoc must be registered as an MCP server. See [Appendix I — Connect Claude via MCP](#appendix-i--connect-claude-via-mcp) for the `claude mcp add` command.

---

<a name="claim-provenance"></a>

## Step 20 — Establish claim-level provenance

Every compiled wiki page is a synthesis — the LLM draws on source text and rewrites it as prose. **Claim-level provenance** closes the audit gap: during ingest, a dedicated annotation pass inserts a `^[filename:L-L]` citation marker at the end of each substantive paragraph, mapping the compiled claim to the exact line range in the raw source that supports it. Markers are stored in the page body, validated by lint, and recorded in the audit database. In Obsidian they render as interactive chips — one click opens the Source Viewer, showing the referenced lines with surrounding context. For PDF sources, a pagemap sidecar resolves the line number to the correct page for direct navigation.

### Re-ingest sources to generate citations

Citation markers are injected during ingest. The demo wiki ships with pre-compiled page stubs — static content that was never run through the annotation pass. When you ran Step 6, Synthadoc annotated only the sections it synthesised during that run; the pre-built stub content was not touched. To get full citation coverage across the entire page, you need to re-synthesise from scratch — but because the source files have not changed since Step 6, the normal dedup check would skip them. The **Force re-ingest** option bypasses the duplicate check so every file runs through the full pipeline including the citation annotation pass, regardless of whether it was previously ingested.

**From the Obsidian plugin (recommended):**

1. Open the Command Palette (`Ctrl/Cmd+P`) → **Synthadoc: Ingest sources**
2. Switch to the **All raw_sources** tab
3. Check **Force re-ingest (skip duplicate check)**
4. Click **Ingest all**

All supported files in your `raw_sources/` folder are queued immediately. You can watch progress under **Jobs** in the Obsidian command palette or with:

```bash
synthadoc jobs list
```

Wait until all jobs reach `completed` status before checking for citation markers.

**Why --force is needed:** Synthadoc records a hash of every ingested source file in the audit database. On subsequent ingest of the same unchanged file, the hash matches and the job is skipped — this is intentional to avoid redundant LLM calls. `--force` overrides this check so the annotation pass runs even on previously seen files.

### Inspect citation chips in Reading View

Once the re-ingest jobs complete, open any wiki page in **Reading View** (`Ctrl/Cmd+E`, or click the book icon in the top-right toolbar). Citation chips are rendered by a post-processor that only runs in Reading View — they will not appear in Edit or Live Preview mode. Paragraphs that make a substantive claim now end with an inline citation chip:

```
Alan Turing proposed the Turing Test in 1950.^[turing-biography.txt:12-24]
```

Click a chip to open the **Source Viewer** — the exact lines from the source file, highlighted, with ±5 lines of context. For PDF sources, a **"Open PDF at page N →"** button resolves the line number to the correct PDF page via a pagemap sidecar and opens it in Obsidian's native PDF viewer.

![Synthadoc citation chips on the alan-turing wiki page — each chip links to the exact source lines](png/claim-level-citation.png)

### Audit provenance across the whole wiki

Open the Obsidian command palette → **Synthadoc: View Page Provenance**. A sortable, paginated table shows every citation across the wiki. You can drag the modal by its title bar to reposition it, and all cell content can be selected and copied. Sort by source file to audit a single document, or filter by slug to see all claims for one page. Click any row to open the Source Viewer for that citation's exact line range.

![Page Provenance modal showing citation table with a Source Viewer popup open for a PDF row — pagination is pinned below the table](png/page-provenance-line-range.png)

### Find broken citations

```bash
# CLI — show citations that failed validation
synthadoc audit citations --broken

# All citations for one page
synthadoc audit citations --page alan-turing
```

![CLI output of audit citations for the alan-turing page — table of source file, line range, and claim excerpt for every recorded citation](png/audit-citation.png)

The lint report also shows a **Citation Issues** section listing any broken, out-of-range, or malformed markers:

```bash
synthadoc lint report
```

→ To fix broken citations automatically, use the **[Broken Citation Resolver workflow](#demo--broken-citation-resolver)** — it fuzzy-matches renamed source files, removes malformed markers, and confirms every fix before writing.

### Checking citation faithfulness

The structural citation check confirms that each `^[filename:L-L]` marker references a known source file and valid line range. **Citation faithfulness** goes further: it uses an LLM to verify that the claim text preceding each marker is actually supported by those source lines.

**CLI walkthrough:**

The CLI delegates all LLM work to the running `synthadoc serve` process — no API key is needed in your terminal. Before posting a job, the command reads the local cache to decide what actually needs to run:

- **No prior results** → full audit across all active pages.
- **Some pages re-ingested since the last audit** → only those stale pages are re-audited; the rest are shown from cache at no cost.
- **All results fresh** → the cached table is printed immediately without any server round-trip.
- **`--force`** → always enqueues a full re-run regardless of cache state.

```bash
# Run the audit (cache-aware: automatically skips pages already up to date)
synthadoc audit citations --faithfulness

# Skip the cost confirmation prompt (e.g. in CI)
synthadoc audit citations --faithfulness --yes

# Force a full re-run even if the cache is fresh
synthadoc audit citations --faithfulness --force

# Scope to one page for a quick spot check
synthadoc audit citations --faithfulness --page bell-labs

# Machine-readable output
synthadoc audit citations --faithfulness --json
```

While the audit runs, progress is printed per page (`Auditing "bell-labs" (3/12)…`) so you can track long wiki runs without staring at a blank prompt.

The report shows one row per citation with a verdict:


| Verdict          | Meaning                                                |
| ---------------- | ------------------------------------------------------ |
| ✅ supported     | Source lines clearly back the claim                    |
| ⚠️ drift       | Claim overstates or partially misrepresents the source |
| ❌ hallucination | Source contradicts or is unrelated to the claim        |
| — skipped       | Source file not available on disk                      |

The command exits with code `1` when any drift or hallucination is found, making it easy to use in CI pipelines.

**Obsidian walkthrough:**

1. Open the command palette and run **Synthadoc: Audit: citation faithfulness...**
   (Or open the Audit modal and click the **Citation faithfulness** tab.)
2. The tab opens with the **last cached results** already loaded (if any), and automatically calculates a cost estimate for the current scope — no button press required.
3. Choose scope using the button group at the top: **All active pages** runs the audit across every active page; **Specific page** reveals a slug search field with fuzzy autocomplete (fetched from your active pages). Switching scope immediately filters the results table and refreshes the cost estimate.
4. When a specific page is selected and it has been audited before, the table shows only that page's cached results. If it has not been audited yet, a prompt appears — click **▶ Run Audit** to check it.
5. A yellow banner appears when one or more pages have been re-ingested since the last audit — click **Re-run stale** to update only those pages without re-checking the rest. The banner explains what "stale" means and what the re-run will do.
6. To run a full fresh audit, click **▶ Run Audit** (shown when no results exist) or **▶ Re-run Audit** (shown when cached results are already present). The audit runs as a background job on the server — the button is disabled immediately and a live progress line appears showing the current page being checked and the count so far (e.g. `⏳ Auditing — 4/12 pages (checking "konrad-zuse")`). You do not need to keep the plugin open: if you close and reopen the tab while an audit is still running, the tab automatically reconnects to the in-progress job and resumes showing progress until it completes.
7. Results appear in a sortable, paginated table (25 rows per page) with columns: **Page**, **Citation**, **Verdict**, **Reason**, and **Audited** (the local date and time of the last audit for that citation). Click the **Page** or **Verdict** column header to sort. A "Last audited: …" line below the table shows the most recent audit timestamp across all cached results. **Click any page name in the table** to jump directly to that page in the Obsidian editor, with the citation marker selected and scrolled into view — useful for quickly locating and correcting flagged claims without hunting through the document.
8. The **verdict summary** at the bottom shows coloured counts — ❌ hallucinations in red, ⚠️ drifts in amber, ✅ supported in green — alongside guidance on what to do next.

![Citation faithfulness tab showing scope buttons, live results table with clickable page links, verdict chips, and summary bar](png/synthadoc-citation-faithfulness.png)

**What to do with drift or hallucination results:**

Citation faithfulness is **informational** — it flags which claims need attention, but corrections are manual. When you see ❌ hallucinations or ⚠️ drifts:

1. Sort the table by **Verdict** to bring flagged entries to the top.
2. Note the **Page** slug and **Citation** marker (e.g. `^[arpanet.pdf:3-5]`).
3. Open that page in Obsidian, find the citation marker in the body text, and locate the referenced lines in `.synthadoc/extracted/` (or click the citation chip in Reading View to open the Source Viewer).
4. Choose a correction:
   - **Correct the claim** — rewrite it to accurately reflect what the source says.
   - **Update the source reference** — point the marker at a source that does support the claim.
   - **Re-ingest with a newer source** — if the original document has been updated, re-ingest it with `synthadoc ingest <file> --force` and re-run the audit.
   - **Use the Contradiction Resolver** — if the page was demoted to `contradicted`, the resolver workflow can help rewrite or re-ground the affected claims.

**Configuring a dedicated judge model for faithfulness:**

The faithfulness audit uses the same LLM you have configured under `[agents.adversarial]` — the same dedicated judge model that runs the adversarial lint pass. This is intentional: both tasks are *judgment* tasks (the model reads content and renders a verdict), so sharing one "judge" role keeps configuration simple.

By default, if you have not set `[agents.adversarial]`, the audit falls back to your `[agents]` default model. To use a different, potentially cheaper or more neutral model for all judgment tasks — both adversarial lint and citation faithfulness — set it once in `synthadoc.toml`:

```toml
[agents]
provider = "anthropic"
model    = "claude-sonnet-5"   # used for ingest and query

[agents.adversarial]
provider = "anthropic"
model    = "claude-haiku-4-5-20251001"   # judge model: runs adversarial lint + faithfulness audit
```

Or point faithfulness (and adversarial lint) at a different provider entirely:

```toml
[agents.adversarial]
provider = "openai"
model    = "gpt-4o-mini"
```

When the server starts an audit job you will see a line in its log confirming which model is in use:

```
Faithfulness audit: anthropic/claude-haiku-4-5-20251001 (dedicated judge)
```

If `[agents.adversarial]` is not set:

```
Faithfulness audit: anthropic/claude-sonnet-5 (default — tip: set [agents].adversarial in config.toml to use a dedicated judge model)
```

---

## Step 21 — Export your wiki

Synthadoc exports your wiki in five machine-readable formats — all assembled server-side from cached data with **zero additional LLM calls**. Use exports to feed reviewed knowledge to an external AI assistant, load your wiki's link structure into a graph analysis tool, or integrate page content into an agent pipeline. Because exports respect the lifecycle filter, you can choose to export only `active` pages — the ones that have passed lint review — rather than everything that has ever been ingested.

> **Differentiation:** Unlike static document exports from other tools, Synthadoc's exports carry the full provenance chain. The `json` format includes the exact source lines that support every claim, the complete state transition history for each page, and the API cost that was spent compiling it. The `okf` format makes your wiki directly consumable by any OKF-aware agent — no code changes needed on the consumer side.

### What each format contains


| Format          | What it exports                                                                                                                                                                                                                                                                                                                                                                                                                          | Best used for                                                    |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `llms.txt`      | Page titles + one-line summaries, structured per the[llmstxt.org](https://llmstxt.org) spec. Contradicted/stale pages appear in a **Needs Review** section; archived pages are omitted.                                                                                                                                                                                                                                                  | Feeding AI assistants a compact, navigable wiki index            |
| `llms-full.txt` | Full page content for all pages, separated by`---` dividers, with status and confidence headers. Provenance footnotes (`^[source.txt:42-58]`) are preserved verbatim. No size limit.                                                                                                                                                                                                                                                     | Large-context LLM prompts, RAG pipelines, offline reading        |
| `graphml`       | Directed wikilink graph — one node per page, one edge per`[[wikilink]]`. Each node carries the page title, lifecycle state, confidence level, orphan flag, inbound link count, and routing branch. Compatible with yEd, Gephi, and Cytoscape.                                                                                                                                                                                           | Visualising knowledge structure, detecting hub pages and orphans |
| `json`          | Full structured dump per page: content, tags, sources, claims with source line ranges, lifecycle transition history, routing branch, and per-page ingest cost and token usage. Wiki-level: total compilation cost and routing branch memberships.                                                                                                                                                                                        | Agent pipelines, programmatic processing, compliance audits      |
| `okf`           | [OKF v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) bundle directory — one Markdown file per page with conformant YAML frontmatter (`generated`, `status`, `synthadoc_lifecycle`, optional `sources`/`verified`/`stale_after`), an `index.md` with `okf_version: "0.2"`, and a plain-markdown `log.md` change log. `[[wikilinks]]` are rewritten to OKF relative paths. Default includes **active + contradicted** pages only; contradicted pages carry `status: draft`, `synthadoc_lifecycle: contradicted`, and a `> **Contradiction:** …` blockquote in the body. | Any OKF-aware agent or tool —**zero code changes needed**       |

### Status filter — export only what you trust

The `--status` flag scopes the export to a specific lifecycle state:


| Value           | What is included                  | When to use it                                                                    |
| --------------- | --------------------------------- | --------------------------------------------------------------------------------- |
| `all` (default) | Every non-archived page¹         | Full snapshot                                                                     |
| `active`        | Only lint-reviewed, trusted pages | **Recommended for AI consumption** — avoids feeding unreviewed content to an LLM |
| `draft`         | Pages awaiting first lint pass    | Reviewing what has been ingested but not yet approved                             |
| `stale`         | Pages whose source has changed    | Identifying content that needs re-ingest                                          |
| `contradicted`  | Pages with detected conflicts     | Targeted review of known issues                                                   |
| `archived`      | Retired pages                     | Audit or recovery                                                                 |

¹ **OKF exception:** `--format okf` with the default `all` includes only `active` and `contradicted` pages — draft and stale are excluded because they carry unverified content. Pass `--status active` for a clean trusted-only bundle.

### CLI

`--output` accepts any absolute or relative path and is resolved from your current working directory.

```bash
# Active pages only — compact index of trusted knowledge (llms.txt spec)
synthadoc export --format llms.txt --status active

# All pages — full content with provenance footnotes preserved
synthadoc export --format llms-full.txt --output exports/history-full.txt

# Wikilink graph — open in yEd, Gephi, or Cytoscape
synthadoc export --format graphml --output exports/history.graphml

# Agent-ready JSON — claims, lifecycle history, per-page cost, routing
synthadoc export --format json --output exports/history.json

# OKF v0.2 bundle — consumable by any OKF-aware agent without code changes
synthadoc export --format okf --output ~/exports/history-okf/
```

**Flags:** `--format/-f` (required: `llms.txt`, `llms-full.txt`, `graphml`, `json`, `okf`), `--output/-o` (file path or directory; omit to print to stdout; **required** for `okf`), `--status/-s` (default `all`).

> **OKF export writes a directory**, not a single file — `--output` must point to a directory path (it will be created if it does not exist).

> **Keep the OKF bundle outside your wiki folder.** Place it anywhere — `~/exports/history-okf/`, `../okf-bundles/history/`, an absolute path — as long as it is not inside the Obsidian vault. Files inside the vault are candidates for ingest; an OKF bundle contains derived Markdown that would be re-ingested as source material if left there.

Requires `synthadoc serve` to be running.

### In Obsidian

Open the Command Palette (`Ctrl/Cmd+P`) → **Synthadoc: Export Wiki**.

The modal opens with a description panel explaining each format, a format dropdown, a full-width output path field (pre-filled with today's date and the correct extension or folder name), and a status filter. Click **Export**. For all formats except `okf` the file is written inside the vault and opened automatically. For `okf`, the output field defaults to `~/exports/{vault-name}-okf-{date}/` — a folder outside the vault — and the bundle is written there directly via the filesystem.

![Synthadoc Export Wiki modal — format dropdown, description panel, output path field, status filter, and Export button](png/synthadoc-export-wiki.png)

When **GraphML** is selected, a **View Graph** button appears. Click it for an inline Cytoscape.js preview of your wiki's link structure before saving to file.

![Synthadoc inline knowledge graph viewer — nodes represent wiki pages, edges represent wikilinks, with a View Graph preview inside Obsidian](png/synthadoc-export-kg.png)

### What makes the JSON export unique

Open `exports/history.json` and inspect any page entry. You will find fields no other wiki export tool produces:

- **`claims[]`** — every annotated paragraph linked to the exact source lines that support it (`source_file`, `line_start`, `line_end`, `claim_excerpt`). Not "cited from X" — but "line 42–58 of X."
- **`lifecycle_history[]`** — the complete state transition log for this page: from/to state, timestamp, triggered by, and reason. You can audit exactly when a page was reviewed and how it got to its current state.
- **`ingest_cost_usd` / `ingest_tokens`** — the cumulative API cost and token count spent compiling this page across all of its source files. Know which pages drove cost.

### Opening GraphML in external tools

The exported `.graphml` file can be loaded in any of these free tools:

**yEd Graph Editor** (recommended for getting started)

1. Download from [yworks.com/yed](https://www.yworks.com/products/yed) (free, Windows/Mac/Linux)
2. Open yEd → **File → Open** → select your `.graphml` file
3. Apply a layout: **Layout → Hierarchical** or **Layout → Organic** for best results
4. Node labels show page titles; edges show wikilink direction

**Gephi** (recommended for large wikis and analysis)

1. Download from [gephi.org](https://gephi.org) (free, open source)
2. **File → Open** your `.graphml` file
3. Run **Layout → ForceAtlas2** in the Layout panel; enable **Prevent Overlap** in Tuning to spread nodes apart
4. To show node labels: click the **label toggle button** (marked **Aα** or **T**) in the bottom toolbar next to the Nodes slider
5. Color nodes by the `status` attribute to see which pages are `active`, `stale`, or `contradicted` at a glance
6. Use **Statistics** to compute degree centrality or community detection

**Cytoscape** (recommended for programmatic analysis)

1. Download from [cytoscape.org](https://cytoscape.org) (free)
2. **File → Import → Network from File** → select your `.graphml`
3. Apply a layout from the **Layout** menu

### OKF bundle export — zero-code agent consumption

The `okf` format produces a directory bundle that any [OKF v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)-aware agent can read without knowing anything about Synthadoc. Every wiki page becomes a conformant Markdown file with YAML frontmatter; knowledge types, cross-links, and lifecycle history are all preserved.

By default the bundle includes **active and contradicted pages only** — draft and stale pages are excluded because they contain unverified or outdated content. Contradicted pages are included deliberately: they carry `status: draft` and `synthadoc_lifecycle: contradicted` in their frontmatter so OKF consumers that read metadata can distinguish them from unverified drafts, and a `> **Contradiction:** …` blockquote appended to the body so consumers that only read Markdown text still see the conflict note.

**Export the demo wiki as an OKF bundle:**

```bash
# Write the bundle outside the wiki folder — keeps it away from Obsidian ingest
synthadoc export --format okf --output ~/exports/history-okf/
```

The bundle looks like this:

```
~/exports/history-okf/
  index.md              ← OKF index, pages grouped by type (person, technology, …)
  log.md                ← lifecycle change history, newest first
  wiki/
    alan-turing.md      ← one OKF concept file per wiki page
    grace-hopper.md
    …
```

Each concept file carries a conformant frontmatter block — here is `alan-turing.md`:

```yaml
---
type: person
title: Alan Turing
description: Father of theoretical computer science and pioneer of the Turing machine.
tags:
  - mathematics
  - computation
  - cryptography
generated:
  by: synthadoc/ingest-pipeline
  at: '2026-04-22'
status: stable
synthadoc_lifecycle: active
confidence: high
verified:
  by: process:synthadoc-lint
  at: '2026-04-22T09:15:00'
---

Alan Turing (1912–1954) developed the theoretical basis of modern computation…

See also: [Von Neumann Architecture](von-neumann-architecture.md)
```

**Run the OKF consumer agent demo:**

Synthadoc ships a standalone consumer agent at `tests/integration/okf_consumer_agent.py`. It imports nothing from Synthadoc — only standard-library modules, `pyyaml`, and whichever API client you choose — proving that any OKF-aware tool works against the bundle without modification.

Three providers are supported: Anthropic (default), the opencode CLI, and any OpenAI-compatible endpoint.

```bash
# Anthropic (default) — Pattern A: grounded domain Q&A
python tests/integration/okf_consumer_agent.py \
    --bundle ~/exports/history-okf \
    --question "Who pioneered compiler development and what did they build?"

# opencode CLI — same question, delegated to the local opencode agent
python tests/integration/okf_consumer_agent.py \
    --bundle ~/exports/history-okf \
    --question "Who pioneered compiler development and what did they build?" \
    --provider opencode --model opencode/big-pickle

# OpenAI-compatible endpoint (e.g. MiniMax)
python tests/integration/okf_consumer_agent.py \
    --bundle ~/exports/history-okf \
    --question "Who pioneered compiler development and what did they build?" \
    --base-url https://api.minimax.io/v1 --model MiniMax-M3
```

Add `--type person` (Pattern B) to any of the above to filter the bundle by OKF type before building context:

```bash
# Pattern B — type-routed discovery with opencode
python tests/integration/okf_consumer_agent.py \
    --bundle ~/exports/history-okf \
    --question "List all computing pioneers and their key contributions" \
    --type person --provider opencode --model opencode/big-pickle
```

The agent reads `index.md` to discover available knowledge types, loads only the concept files that match the requested type (when `--type` is given), builds a grounded context, and asks the LLM to answer using only the OKF bundle content — citing the source file path for every claim.

> **Requirements by provider:**
> - **Anthropic (default):** `pip install anthropic pyyaml` and `ANTHROPIC_API_KEY` set.
> - **opencode:** `npm install -g opencode-ai` (must be authenticated) and `pip install pyyaml`. No API key needed in the environment.
> - **OpenAI-compatible:** `pip install openai pyyaml` and `OPENAI_API_KEY` (or `MINIMAX_API_KEY`) set.
>
> The Synthadoc server does not need to be running — the agent reads the exported bundle directly from disk.

---

<a name="web-chat-ui"></a>

## Step 22 — Use the web chat UI

The `synthadoc web` command opens a browser-based chat interface for your wiki. Unlike the CLI query command, the web UI supports multi-turn conversation and shows contextual hint chips based on your session history.

### Open the web UI

```bash
synthadoc web -w history-of-computing
```

Your browser opens automatically to the web chat interface.

![Synthadoc Query Agent Web UI](png/synthadoc-query-agent-web-UI.png)

### Session modes

The UI detects the state of your wiki and your session history, then adapts:


| Mode badge       | When it appears                                       | Hint chips shown                                                    |
| ---------------- | ----------------------------------------------------- | ------------------------------------------------------------------- |
| **New Wiki**     | Fewer than 5 wiki pages exist                         | Onboarding — guides you through ingesting your first documents     |
| **Explorer**     | ≥5 pages, first time opening the UI for this wiki    | Discovery — broad overview questions to explore the wiki           |
| **Health Check** | ≥5 pages, returning user, ≥1 stale page in the wiki | Lifecycle review — suggests running lint or inspecting stale pages |
| **Power User**   | ≥5 pages, returning user, no stale pages             | Context-sensitive follow-ups based on your last answer              |

The mode badge appears above the title on the welcome screen. It reflects the wiki's current state at the moment the session was created — the mode is determined when you open the browser tab, not updated mid-session. To see an updated mode after running lint and promoting pages, open a new browser tab.

### Asking questions

Type a question in the text box and press **Enter** (or click **Ask**). The answer streams in word-by-word as the LLM generates it — no waiting for the full response.

Below each answer:

- **Citations** — rendered as numbered footnotes (`[^1]`, `[^2]`, …) with source filename and line range. Each `^[filename:L-L]` marker in the answer is converted to a GFM footnote reference; the definitions appear at the bottom of the answer block. (In Obsidian, the same markers render as interactive citation chips in Reading View.)
- **Knowledge gap callout** — appears when the wiki lacks coverage; suggests `search for:` ingest commands to fill the gap
- **Hint chips** — suggested follow-up questions based on the current answer and your session history

### Multi-turn conversation

Each question in a session builds on the previous ones. The server stores your conversation history and passes it to the query pipeline so follow-up questions like "What came before that?" resolve correctly against the previous answer. Follow-up questions are automatically rewritten into standalone form before retrieval — context-dependent phrases resolve against the right topic without you having to repeat it.

#### Single-turn queries to try first

Type any of these into the chat box and press **Enter**. They work well as standalone questions with the history-of-computing demo wiki:

**Factual retrieval:**

```
Who is Alan Turing and what was his most significant contribution?
What is Moore's Law and has it held up over time?
What was ENIAC and why was it significant?
```

**Multi-source reasoning:**

```
What are the differences between von Neumann and Harvard architectures?
How did the transition from vacuum tubes to transistors change computing?
```

**Gap detection** — these topics are not in the demo wiki yet; expect a knowledge gap callout with suggested ingest commands:

```
What is the history of quantum computing milestones?
Who invented the USB standard?
```

> **CLI equivalent:** All of the above can also be run from the terminal with `synthadoc query "<question>"` if you prefer the command line. The web UI and CLI share the same query pipeline and cache.

#### Multi-turn sequences (web UI or CLI)

**Thread 1 — context carry-over with pronouns** (best stress test for conversation memory):

```
Turn 1:  "Who invented the transistor?"
         → Names the inventors at Bell Labs

Turn 2:  "Which company did they work for?"
         ↑ "they" resolves to the transistor inventors from Turn 1

Turn 3:  "What other inventions came out of that same lab?"
         ↑ "that same lab" resolves to Bell Labs — correct without repeating it
```

**Thread 2 — deepening on a topic**:

```
Turn 1:  "What was the significance of the 1936 Turing machine paper?"
         → Covers computability, halting problem, foundations of CS

Turn 2:  "How did that influence the design of the first real computers?"
         ↑ "that" resolves to the Turing machine concept

Turn 3:  "Which of those early computers had the most commercial impact?"
         ↑ "those early computers" carries over from Turn 2's answer
```

**Thread 3 — pivot mid-conversation**:

```
Turn 1:  "Tell me about Claude Shannon and information theory"
Turn 2:  "How does that relate to data compression?"
Turn 3:  "What about its connection to cryptography?"
```

**Try it now with the history-of-computing demo wiki:**

```
You:        "How did Alan Turing contribute to breaking the Enigma code?"
Assistant:  "...Turing's Bombe machine at Bletchley Park..."

You:        "Who else worked with him there?"
            ↑ Resolves "him" → Alan Turing, "there" → Bletchley Park
```

#### Synthadoc operation multi-turn

The web UI also supports multi-turn for Synthadoc operations — not just wiki content queries.

**Job status drill-down:**

```
You:        "Show me job status"
Assistant:  Shows a table of all jobs with status, operation, and timing.
            Presents chip buttons for each Job ID.

You click chip "353958ca"
            → Full detail for that job: status, operation, started/finished, error (if any)

You click chip "6b7d1fa7" (from the same chip list)
            → Full detail for the second job — no re-query needed
```

**Multi-status job filter:**

```
You:        "Show me failed and skipped jobs"
            → Filtered job table showing only those two statuses
```

**Clarify prompts.** When you ask to perform an action but don't specify which page — for example, "Activate a draft page" — the assistant responds with a numbered list of candidate pages. Click a chip or type a page name to complete the action:

```
You:        "Activate a draft page"
Assistant:  "Which page would you like to activate?
             1. konrad-zuse
             2. quantum-computing
             (or type a page name)"

You click chip "1" → page is activated
```

**Notice messages.** Long sessions automatically compress older turns into a `[Session summary]` to keep the context window manageable. When this first happens you see an inline notice:

```
ℹ Earlier conversation turns were summarised to fit the session window.
```

### Session history sidebar

The left navigation bar shows your recent runs grouped by session. Synthadoc persists sessions on the server, so your history survives page refreshes and restarts.

- **Single-turn sessions** appear as a flat entry showing the first question and the time elapsed since the last activity.
- **Multi-turn sessions** appear as a collapsible group with a turn count badge (e.g. `3 turns`). Click the **▸** chevron to expand and see each follow-up question indented below the root.
- **Restoring a session** — click any session root or child turn to reload the full conversation history into the chat window. The context is fully restored so you can continue asking follow-up questions as if you never left.
- **New Run** — click **+ New Run** at the top of the sidebar to start a fresh session with a new session ID.

### Settings — query timeout

The ⚙ gear icon in the bottom-left corner of the chat window opens a settings popover. Use it to set the **per-request query timeout** (10–600 seconds, default 60 s) without editing `config.toml`. The value is saved in your browser's `localStorage` and persists across page refreshes.

Increase the timeout when using a reasoning model (e.g. MiniMax M3, Qwen with thinking enabled) that takes longer on large or complex questions. Lower it to fail fast if you suspect the server is hanging.

### Theme — dark, light, and system mode

The **theme toggle** button sits at the right end of the tab bar (Chat | Graph | [toggle]). Clicking it cycles through three modes:

| Mode | Effect |
| --- | --- |
| **System** (default) | Follows your OS `prefers-color-scheme` setting — dark on a dark-mode OS, light on a light-mode OS |
| **Dark** | Deep navy background with purple/violet accent |
| **Light** | Off-white background with the same accent |

Your choice is saved in your browser's `localStorage` and restored on the next page load. A small inline script applies the stored preference before React renders, so there is no flash of the wrong theme.

In system or dark mode the hero background image is visible behind the chat content. In light mode (or system mode on a light-theme OS) the background falls back to a plain white surface — the dark image does not bleed through.

### Configure conversation history depth

The number of prior turns included in each request is configurable via `config.toml`. The default (5 turns) covers most sessions:

```toml
# <wiki-root>/.synthadoc/config.toml
[chat]
conversation_history_turns = 5   # set to 0 to disable conversation memory
```

**When the session exceeds the limit**, the oldest turns are automatically compressed into a single `[Session summary]` entry by the summarization component. The summary preserves the key facts and context from those turns so follow-up questions still resolve correctly — no history is simply discarded. You will see an inline notice in the chat the first time compression occurs:

```
ℹ Earlier conversation turns were summarised to fit the session window.
```

Increase `conversation_history_turns` if you want more raw turns retained before compression kicks in. Set it to `0` to disable conversation memory entirely (each question is treated independently).

Each new browser tab starts a fresh session. History is not shared between tabs.

---

<a name="query-caching"></a>

## Step 23 — Query caching

`synthadoc query` (and the web chat UI) cache answers automatically. The second time you ask the same question against the same wiki, the answer returns instantly from cache without an LLM call.

### How the cache works

The cache key is a hash of:

- The question text (after normalisation)
- The current wiki **epoch** — a version counter that increments whenever you ingest new content or change a page's lifecycle state

This means cached answers are always consistent with the current wiki. A new ingest automatically invalidates old cached answers so you never see a stale result.

### Bypassing the cache

```bash
# Always call the LLM, even if the answer is cached
synthadoc query "What is Moore's Law?" --no-cache
```

Use `--no-cache` when:

- You want to verify the answer is still correct after an ingest
- You are debugging a query or testing a new LLM provider
- You suspect the cache entry is stale for any reason

The `--no-cache` flag is available on `synthadoc query`. The web chat UI uses the cache by default — tick the **Bypass cache** checkbox at the bottom of the chat window to skip the cache for that request. To force a full refresh for all subsequent queries, use `synthadoc cache clear`.

### Cache management

The query cache lives in the same `cache.db` as the ingest response cache. Clear all cached answers at once:

```bash
synthadoc cache clear -w history-of-computing
```

> **Note:** The query cache is separate from the ingest cache layers. Clearing the cache removes both query answers and LLM responses cached during ingest — the next lint run and the next ingest of any source will re-run LLM calls.

<a name="knowledge-graph"></a>

## Step 24 — Knowledge Graph

The knowledge graph visualises how your wiki pages connect. Synthadoc builds it automatically during lint using two signals:

- **Wikilink edges** — drawn when one page contains `[[another-page]]`. Each occurrence adds +1 to the edge weight.
- **Co-source edges** — drawn when two pages were compiled from the same source file (matched by content hash). Each shared source adds +2 to the edge weight. These edges appear immediately after ingest, even before any wikilinks exist.

Edge thickness reflects total weight (thicker = stronger relationship). Dashed edges are pure co-source connections — pages related by origin but not yet cross-linked. Solid edges include at least one wikilink. Louvain cluster detection colours pages that are densely connected in the same group.

### Build the graph

Run lint to trigger graph construction (if you completed Step 6, the graph is already ready):

```bash
synthadoc lint run -w history-of-computing
```

Lint prints a summary line when the graph is built:

```
[graph] 110 nodes, 349 edges, 5 clusters
```

> **Note:** The graph builds automatically on every lint run. You never need to run a separate command to rebuild it.

### Open the Graph tab

1. Start the web UI (if not already running):
   ```bash
   synthadoc web
   ```
2. Open `http://localhost:7070/app` in your browser.
3. Click the **Graph** tab in the top navigation bar.

The force-directed graph appears: nodes are wiki pages, edge thickness reflects relationship strength, dashed edges are co-source connections, and node colours represent detected knowledge clusters.

> On first load, the server may need a moment to hydrate the graph from the database. A brief spinner shows while it loads — the tab switches to the graph automatically when ready.

### Explore clusters

Zoom and pan with your mouse or trackpad. Pages with more inbound links appear larger. Colour groups represent Louvain clusters — Synthadoc identified these as related knowledge neighbourhoods.

In the history-of-computing demo you will see clusters forming around computing pioneers, hardware eras, and software history.

Before running lint, you may notice isolated nodes floating at the edges — pages with no wikilinks pointing to or from them, or with broken citation links. These are orphan pages that have not yet been connected to the rest of the knowledge graph.

![Knowledge graph before lint — isolated nodes with broken or missing links visible at the edges](png/synthadoc-knowledge-graph-with-broken-links.png)

After lint resolves dangling links and the graph is rebuilt, the same wiki becomes significantly more connected. Pages that were isolated now have edges to related neighbours, and the cluster structure becomes clearer.

![Knowledge graph after lint — 110 nodes, denser cluster structure with fewer isolated pages](png/synthadoc-knowledge-graph.png)

### Click a node to query it

Click any node to open its detail panel:

- **Title** and **slug**
- **Type** (`concept`, `person`, `event`, …)
- **Lifecycle state** (`active`, `draft`, `stale`, …)
- **Questions to explore** — suggested follow-up questions for that page
- **"Ask about this →"** button

Click **Ask about this →** to jump to the Chat tab with a pre-filled query about that page. The answer is drawn from the wiki and citations appear inline.

### When to use which graph view

Synthadoc provides two knowledge graph views powered by the same `GET /graph` endpoint. Choose based on what you want to do next:


| I want to…                                      | Use                                                               |
| ------------------------------------------------ | ----------------------------------------------------------------- |
| Ask a question about a page                      | **Web UI Graph tab** — click a node → "Ask about this →"       |
| Read or edit a page I found in the graph         | **Obsidian panel** — click a node to open it in the current pane |
| Explore graph topology while staying in Obsidian | **Obsidian panel**                                                |
| See graph and chat side by side                  | **Web UI**                                                        |

> **Rule of thumb:** Use the **web UI** when you want to ask questions about a node. Use the **Obsidian panel** when you want to navigate to and edit a page.

### Open the graph panel in Obsidian

You can explore the same knowledge graph without leaving Obsidian. Open the command palette (`Ctrl/Cmd+P`) and run **"Graph: show knowledge graph"**.

The panel shows all wiki pages as force-directed nodes coloured by cluster. Use the **type filter** dropdown to narrow to a specific knowledge type (concept, person, event…). If your wiki has more than 300 pages, the 300 most-connected are shown with an explanatory banner — use the type filter to narrow the view.

**Interactions:**

- **Hover** a node — tooltip shows title, slug, type, state, cluster, and connection count.
- **Click** a node — opens the wiki page in the current pane; the node is highlighted gold.
- **Drag** a node — re-pins it to a new position.
- **Scroll** to zoom in/out; **drag the background** to pan.

Edge thickness encodes connection strength (thicker = more wikilinks + shared sources). Dashed edges are co-source relationships — pages compiled from the same source document.

![Obsidian knowledge graph panel — force-directed graph with cluster colours, type filter, and hover tooltip](png/synthadoc-obsidian-kg.png)

---

<a name="session-ingest"></a>

## Step 25 — Ingest an AI session transcript

AI coding sessions contain a rich record of problem-solving — architecture decisions,
debugging steps, code explanations, and implementation rationale — that would otherwise
be lost after the conversation ends. The session skill turns any Claude Code, Codex, or
Cursor `.jsonl` session file into a searchable wiki page.

### What gets ingested

The skill extracts only the substantive conversation turns:

- **User questions / instructions** (≥ 3 words) — the problems you brought to the session
- **Assistant answers** (≥ 20 words) — explanations, code walk-throughs, and decisions

Filtered out automatically: tool calls, shell output, file reads, thinking blocks,
sub-agent scaffolding, and session metadata lines. This means file contents and
credentials in tool output never reach the wiki.

### Locate your Claude Code session files

Claude Code stores sessions under `~/.claude/projects/`. Each project directory
contains one `.jsonl` file per conversation:

```bash
ls ~/.claude/projects/
# e.g.: -Users-yourname-workspace-myproject/
ls ~/.claude/projects/-Users-yourname-workspace-myproject/
# e.g.: 4f8c2a1b-3e9d-4a6b-8c1f-2d7e0a3b5f9c.jsonl
```

### Ingest a session file

Pass the `.jsonl` path directly — no need to copy the file into the wiki directory first.
Synthadoc's CLI automatically signals the server that the file may be outside the wiki root,
and the server accepts this for local (127.0.0.1) connections:

```bash
synthadoc ingest ~/.claude/projects/-Users-yourname-workspace-myproject/4f8c2a1b-3e9d-4a6b-8c1f-2d7e0a3b5f9c.jsonl
```

Synthadoc detects the `.jsonl` extension, routes to the session skill, and creates a
wiki page. The page slug is auto-derived from the session date and the first substantive
user message — for example `session-2026-07-15-how-do-i-implement-sliding`.

Watch progress:

```bash
synthadoc jobs list
```

### Demo walkthrough — capture a debugging session

This walkthrough shows the full flow using a typical Claude Code session.

**1. Find the session file**

Suppose you just finished a debugging session in your `my-project` workspace. List the
available sessions sorted by modification time to find the most recent:

```bash
ls -lt ~/.claude/projects/-Users-yourname-workspace-my-project/*.jsonl | head -5
```

Copy the path of the most recent file — for example:

```
~/.claude/projects/-Users-yourname-workspace-my-project/2b7e1f3c-4a8d-4c9b-b5e2-1f0c3a7d2e8b.jsonl
```

**2. Ingest it**

```bash
synthadoc ingest ~/.claude/projects/-Users-yourname-workspace-my-project/2b7e1f3c-4a8d-4c9b-b5e2-1f0c3a7d2e8b.jsonl -w my-wiki
```

Expected output:

```
[ingest] source: .../2b7e1f3c-....jsonl  format=claude_code  turns=47
[ingest] page: session-2026-07-15-why-is-my-async-queue-deadlock  (draft)
[ingest] done  1 page created
```

**3. Check the result**

```bash
synthadoc query "why did my async queue deadlock" -w my-wiki
```

The answer cites the session page with source-line precision. The session is now part of
the permanent wiki — queryable alongside all your other sources.

**4. Ingest multiple sessions at once**

Create a batch file (`sessions.txt`) listing session paths one per line:

```
# sessions.txt
~/.claude/projects/-Users-yourname-workspace-my-project/2b7e1f3c-....jsonl
~/.claude/projects/-Users-yourname-workspace-my-project/9a3d5e2f-....jsonl
~/.claude/projects/-Users-yourname-workspace-other-project/1c4b8f7a-....jsonl
```

Then run:

```bash
synthadoc ingest --file sessions.txt -w my-wiki
```

### Limitations and tips


| Concern                      | Detail                                                                                                                                                                                                             |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Long sessions**            | Very long sessions are truncated at`max_source_chars` (default 400 000 chars). Raise the limit with `--max-source-chars 800000` for very active sessions.                                                          |
| **Tool output excluded**     | Shell output and file reads are stripped from the wiki page. Re-ingest the original source files separately if you need the file contents indexed.                                                                 |
| **Re-ingest is safe**        | Synthadoc deduplicates by source hash — re-ingesting the same`.jsonl` file will update the existing page rather than create a duplicate.                                                                          |
| **Codex / Cursor sessions**  | The same command works for Codex and Cursor`.jsonl` exports — format is detected automatically.                                                                                                                   |
| **Private content**          | Session files may contain proprietary code. Keep your wiki on a local or private server and review what the page contains before sharing.                                                                          |
| **Sanitization**             | Extracted turns pass through the standard pre-LLM source sanitizer (zero-width chars, bidi overrides, HTML comments, instruction-override phrases) — the same step applied to every PDF, URL, and DOCX source.    |
| **Obsidian plugin / web UI** | Neither the Obsidian plugin nor the web UI can ingest session files directly — they do not send local filesystem paths outside the wiki root. Use the CLI (`synthadoc ingest <path>`) for session file ingestion. |

---

<a name="step-26--agentic-maintenance-workflows"></a>
<a name="agentic-workflows"></a>

## Step 26 — Agentic Maintenance Workflows

The web chat UI can drive wiki maintenance conversationally — no terminal required. Type a maintenance request in plain English and the system confirms with you, re-ingests pages, fixes broken links, and runs lint, all from a single chat turn.

Seven workflows are available, listed in the order the web UI will pre-prompt them at session start:


| Workflow                          | Example phrase                   | Scope                                                                                                                                                                                                   |
| --------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Contradiction resolver**        | "run contradiction resolver"     | For each contradicted page: reads content and sources, proposes a rewrite, shows the full diff, applies after approval, re-lints the page, and promotes it to*active* if it passes                      |
| **Stale-pages bulk reingest**     | "re-ingest stale pages"          | Finds every stale page, re-ingests each one in sequence, then runs lint                                                                                                                                 |
| **Page-by-slug reingest**         | "re-ingest the alan-turing page" | Re-ingests one named page regardless of state (active, draft, or stale), then runs lint                                                                                                                 |
| **Orphan resolver**               | "run orphan resolver"            | Finds pages with no incoming`[[wikilinks]]` and proposes natural link insertions into topically related active pages; retries with 4 progressively broader search strategies before escalating          |
| **Broken wikilinks scan and fix** | "scan for broken wikilinks"      | Scans all active pages for`[[slug]]` references that resolve to no existing page; suggests corrections and fixes them after confirmation                                                                |
| **Broken citation resolver**      | "fix broken citations"           | Scans all active pages for broken`^[file:L-L]` source markers (`broken_ref` / `malformed` / `out_of_range`); proposes targeted fixes with fuzzy source-name matching; validates each fix with a re-scan |
| **Lint run and full report**      | "run lint"                       | Runs a full lint pass, waits for it to complete, then surfaces the complete report in a single conversational turn                                                                                      |
| **Scaffold and report**           | "run scaffold"                   | Previews the domain and files to overwrite, asks for confirmation, then regenerates`index.md`, `purpose.md`, `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md`                                                  |

### Demo — resolve contradicted pages

**Prerequisites:** At least one page in `contradicted` state. Complete Step 9
setup (ingest `first-compiler-controversy.pdf`) or run a full lint pass — the
adversarial gate will demote any page whose flagged-claim count meets the
threshold.

Open the web chat UI. You have three entry points:

- **Hint chip:** The **"Run contradiction resolver"** chip appears in the sidebar whenever the wiki has at least one contradicted page — click it to start immediately.
- **Pre-filled suggestion:** After any response that mentions contradicted pages, a pre-filled prompt appears below the reply — click it directly:

  > *1 page marked contradicted — run the contradiction resolver to fix them interactively?*
  >
- **Free text:** Type **"run contradiction resolver"** at any time.

**Step 1 — Cost estimate and approval**

```
Scope: all  ·  1 contradicted page  ·  estimated ~0.1s / ~$0.003
Proceed?
```

> **Yes, proceed** / **No, cancel**

Click **Yes, proceed**.

**Step 2 — Propose rewrite**

The agent reads the current page and the conflicting source (for source-conflict
pages) or the flagged claims (for gate-demoted pages), formulates a reconciling
rewrite, and displays the full unified diff:

```diff
- Grace Hopper completed the A-0 compiler in 1952, making it the first
- compiler ever written.
+ Grace Hopper completed the A-0 system in 1952 — a pioneering loader and
+ linker that automated the assembly of code from reusable subroutines.
+ The first production compiler is generally credited to the FORTRAN team
+ at IBM (1957).
```

> *Apply this change?*
> **Apply** / **Skip this page**

Click **Apply**.

![Contradiction resolver — diff approval UI with 6 contradicted pages queued](png/contradiction-resolver.png)

**Step 3 — Scoped re-lint**

```
Re-linting grace-hopper…
Scoped lint running... (14s)  ✓ passed — 0 warnings, no contradiction note
✅ grace-hopper → active  (strategy: Strategy 1 — Content rewrite, attempt 1)
```

**Step 4 — Final summary**

```
Contradiction Resolver — Complete

✅ Fixed (1):
  grace-hopper — Strategy 1 — Content rewrite

⚠ Unresolved (0):
⏭ Skipped (0):

Wiki lifecycle counts: draft=0  active=12  stale=0  contradicted=0  archived=1
```

The contradicted count reaches zero — no further action needed.

> **Tip:** If the rewrite does not pass re-lint on the first attempt, the
> workflow automatically selects a different strategy (web ingest, force
> re-ingest, or cross-page resolution) for up to 3 attempts. After 3 failures
> it escalates with a plain-language diagnosis and concrete suggestions, leaving
> the page in *contradicted* for manual review.

**Scoping the resolver**

```bash
synthadoc workflow run --name contradiction-resolver                             # all contradicted pages
synthadoc workflow run --name contradiction-resolver --slug grace-hopper         # one page
synthadoc workflow run --name contradiction-resolver --type adversarial          # adversarial-gate demotions only
synthadoc workflow run --name contradiction-resolver --type source-conflict      # source-conflict demotions only
```

---

### Demo — re-ingest all stale pages

The History of Computing demo includes the `konrad-zuse` page whose source file can be modified to trigger stale detection. First manufacture a stale page:

1. In Obsidian, open `raw_sources/konrad-zuse-z3-computer.md` and make any small change — add a word, fix a typo, or append a note at the end. Save the file.
2. Run lint to detect the change:

```bash
# konrad-zuse transitions from active to stale
synthadoc lint run -w history-of-computing
synthadoc status -w history-of-computing   # stale: 1
```

Now open the web chat UI:

```bash
synthadoc web -w history-of-computing
```

Type: **"show me the wiki status"**

The response shows 1 stale page. Because stale pages were detected, the chat input is
automatically pre-filled with a suggested follow-up — something like:

> *Re-ingest 1 stale page: konrad-zuse*

Press **Enter** to send it. A confirmation card appears:

> *Found 1 stale page: konrad-zuse. Re-ingest it?*
> **Yes, re-ingest all** / **No, cancel**

Click **Yes, re-ingest all**. Inline progress events stream as the workflow runs each step:

```
Looking up stale pages…
Re-ingesting konrad-zuse-z3-computer.md…
Polling job…  ✓ completed
Running lint…
Lint running... (8s)  ✓ completed
Checking page states…
```

When done, the workflow writes a plain-text summary showing the re-ingest outcome, the lint result (pass/fail), and the final lifecycle state of each page — `konrad-zuse` appears as ✓ active. No second step is needed: lint runs as part of the workflow.

### Demo — re-ingest a specific page by slug

Use this when you want to refresh one page regardless of its current lifecycle state — active, draft, or stale. No stale transition is needed.

In the web chat UI, type: **"re-ingest the alan-turing page"**

The agent looks up the source path and asks for confirmation:

> *Re-ingest alan-turing from `.../alan-turing.md`?*
> **Yes** / **No, cancel**

Confirm. Inline progress events stream as the workflow runs:

```
Looking up source for alan-turing…
Re-ingesting alan-turing.md…
Polling job…  ✓ completed
Running lint…
Lint running... (8s)  ✓ completed
Checking page states…
```

When done, the workflow writes a plain-text summary showing the re-ingest outcome, the lint result, and the final lifecycle state — `alan-turing` appears as ✓ active. Lint runs as part of the workflow; no second step is needed.

### Maintenance chips in the web UI graph sidebar

In the web UI **Graph tab**, click any node to open the node detail panel. A **Maintenance** section appears at the bottom of the panel with two chips:


| Chip                              | What happens                                                                      |
| --------------------------------- | --------------------------------------------------------------------------------- |
| **⚑ Check this page for issues** | Sends "Check the [slug] page for issues" to the chat                              |
| **↻ Re-ingest this page**        | Sends "Re-ingest the [slug] page" to the chat, triggering a page-by-slug reingest |

Clicking either chip routes the request through the normal confirmation flow — the agent confirms before doing anything.

---

### Demo — orphan resolver

Pages with no incoming `[[wikilinks]]` from other active pages are invisible to
navigation and less likely to be cited or discovered. The orphan resolver finds
these pages and proposes natural link insertions into topically related pages.

In the web chat UI, type: **"run orphan resolver"**

The workflow first calls `tool_find_orphaned_pages` to identify all pages with `orphan: true` frontmatter, shows a cost estimate, and asks for confirmation. Then for each orphan it tries up to four progressively broader search strategies:

1. BM25 search by title keywords
2. BM25 search by content terms from the orphan's first paragraph
3. LLM selection from a dump of all active page titles
4. LLM contextual reasoning with the full orphan body

For each strategy, it proposes a `[[wikilink]]` insertion into the best candidate page, shows the unified diff, and applies the change after your approval. A graph-level re-check confirms the orphan is resolved before moving on.

**To target a single page:**

```bash
synthadoc workflow run --name orphan-resolver --slug ada-lovelace
```

**If all four strategies are exhausted**, the workflow escalates with a `tool_notify` message listing every candidate page considered and four concrete next steps: re-run the workflow (LLM non-determinism may produce a better candidate on a fresh attempt), manually add the wikilink, archive the page if it's out of scope, or create a hub page and re-run.

The Web UI shows a **"Run orphan resolver"** hint chip whenever orphaned pages are detected at session start or after a lint run.

---

### Demo — scan and fix broken wikilinks

**Setup — manufacture broken wikilinks in the History of Computing demo wiki**

Open these three files in Obsidian (Edit view or any text editor) and convert the bare slug references to wikilinks, then save each file:


| File                           | Change                                                                 |
| ------------------------------ | ---------------------------------------------------------------------- |
| `wiki/eniac.md`                | Change`john-mauchly` to `[[john-mauchly]]` in the Designers section    |
| `wiki/history-of-computing.md` | Change`ada-lovelace` to `[[ada-lovelace]]` in the 1843 milestone entry |
| `wiki/grace-hopper.md`         | Change`harvard-mark-i` to `[[harvard-mark-i]]` in the first paragraph  |

None of these slugs have a corresponding `.md` page in the wiki — `john-mauchly`, `ada-lovelace`, and `harvard-mark-i` are referenced but uncompiled, making them broken wikilinks.

**Run the workflow**

In the web chat UI, type: **"scan for broken wikilinks"**

The agent scans all active pages and presents a confirmation card listing every affected page and proposed fix:

> *Found 3 broken wikilinks across 3 pages:*
> *• eniac: `[[john-mauchly]]` → remove link (no similar page found)*
> *• grace-hopper: `[[harvard-mark-i]]` → remove link (no similar page found)*
> *• history-of-computing: `[[ada-lovelace]]` → remove link (no similar page found)*
> *Stale/draft pages were excluded. Promote them to active to include in the scan.*
> **Yes, fix all** / **No, cancel**

Click **Yes, fix all**. The agent removes the `[[...]]` markup from each page while preserving the display text, runs a lint pass to validate, and reports the final state of each page.

> **Fuzzy suggestions:** When the broken link is a likely typo — for example `[[alan-tunring]]` where `alan-turing` exists — the agent proposes a corrected replacement instead of a removal. The fix scope shows both the original and the suggested target before you confirm.

If your wiki has no broken links, the workflow reports: *"No broken wikilinks found. Wiki link integrity is clean."* — no confirmation card appears.

**Only active pages are scanned.** If a stale or draft page has broken links, promote it to active first, then re-run the scan.

---

### Demo — broken citation resolver

Source citation markers in the form `^[file.txt:L-L]` can break when a source file is renamed, re-ingested under a new path, or when the marker syntax is malformed. The broken citation resolver finds and fixes them.

In the web chat UI, type: **"fix broken citations"**

The workflow scans all active pages and presents a confirmation card listing each broken marker and its proposed fix:

> *Found 2 broken citation(s) across 1 page(s):*
> *• my-page: `^[biographie.txt:1-5]` — broken_ref (suggested fix: `^[biography.txt:1-5]`)*
> **Yes, fix all** / **No, cancel**

Click **Yes, fix all**. The agent applies each fix, re-scans the affected page to confirm the citation is resolved, and reports the final state.

**Fix strategy:**

- `broken_ref` — fuzzy-matches the citation filename against the page's actual source files. If a match ≥ 72% similarity is found, the filename is corrected (line range preserved). Otherwise the marker is removed.
- `malformed` / `out_of_range` — the marker is removed. Surrounding prose is preserved.

**To target a single page:**

```bash
synthadoc workflow run --name broken-citation-resolver --slug my-page
```

If the wiki has no broken citations, the workflow reports: *"No broken citations found. Citation integrity is clean."* — no confirmation card appears.

**Only active pages are scanned.** Promote a stale or draft page to active first if its citations need checking.

---

### Demo — run lint and view the full report

This workflow runs a full lint pass from a single chat message and immediately streams the results — no separate `synthadoc lint run` needed.

In the web chat UI or Obsidian query modal, type: **"run lint and show me the report"**

Inline progress messages appear as the agent works:

```
Running lint check…
Lint running... (8s)
Fetching lint report…
```

When the lint job completes, the agent streams a structured report:

```
### Lint Report (2026-08-12)

**Summary**
- Dangling links removed: 3
- Orphan pages: 26
- Contradictions: 0 resolved, 0 flagged

**Contradicted Pages**
(none)

**Adversarial Warnings**
(none)

**Orphan Pages**
- ajay-bhatt
- antikythera-mechanism
- ...
```

No confirmation is required — lint runs and reports autonomously. Any other triggering phrase also works:

- `"run lint"`
- `"run a full lint check and show me what needs attention"`

> **Tip:** Run lint first to get a full picture, then follow up in the same session: "scan for broken wikilinks" or "re-ingest stale pages".

---

### Demo — run scaffold

This workflow regenerates the wiki's core scaffold files from a single chat message. It shows you what will be overwritten and requires confirmation before writing anything.

In the web chat UI, type: **"run scaffold"**

The agent first previews the operation:

```
Domain: History of Computing
Files that will be overwritten:
  wiki/index.md
  wiki/purpose.md
  AGENTS.md
  CLAUDE.md
  GEMINI.md
  ROUTING.md  ← only listed if it already exists

User-written content above the <!-- synthadoc:scaffold --> marker is preserved.
Run scaffold for 'History of Computing'?
```

Click **Run scaffold** to confirm. Inline progress appears as the job runs:

```
Running scaffold for 'History of Computing'...
Scaffold running... (8s)
✓ Scaffold complete — 14 pages categorised
```

The final report shows:

- Domain scaffolded
- Files written
- Number of pages updated with category labels (`categories_updated`)
- Whether `ROUTING.md` was regenerated

Any other triggering phrase also works:

- `"rebuild scaffold"`
- `"regenerate scaffold for my wiki"`

> **Tip:** Re-run scaffold after adding a significant batch of new pages to keep the index categories and AGENTS.md guidelines current with the wiki's actual scope.

### How it works

Each workflow runs as an agentic tool-call loop that streams inline progress after every step — you see what the agent is doing as it happens. All destructive operations (re-ingest, link fix, scaffold write, content rewrite) require your explicit confirmation before anything is changed. Declining exits cleanly with no side effects.

**Key behaviours by workflow:**


| Workflow                   | Confirmation                       | Key behaviour                                                                                                                                    |
| -------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Stale bulk**             | ✓ required                        | Re-ingests pages one at a time; a single failure does not abort the run — remaining pages continue                                              |
| **By slug**                | ✓ required                        | Force-re-ingests regardless of current lifecycle state                                                                                           |
| **Broken wikilinks**       | ✓ required (if any found)         | If the wiki is already clean, the workflow stops after scanning — no card appears                                                               |
| **Lint report**            | none                               | Lint is read-only; runs and reports autonomously                                                                                                 |
| **Scaffold**               | ✓ required                        | User-written content above`<!-- synthadoc:scaffold -->` markers is always preserved                                                              |
| **Contradiction resolver** | ✓ required ×2 (cost + each diff) | Shows full diff before every write; re-lints only the changed page; promotes on pass or escalates after 3 failed attempts                        |
| **Orphan resolver**        | ✓ required ×2 (cost + each diff) | 4-strategy retry per orphan; graph-level re-check after each fix; escalates with candidate list and suggested next steps after 4 failed attempts |

For tool-level detail — per-workflow tool sets, SSE extensions (`tool_progress`, `confirm_request`, `done.pre_prompt`), routing architecture, loop constraints, pre-prompt mechanics, and audit trail — see [§35 Contradiction Resolver Workflow](design.md#35-contradiction-resolver-workflow) in the design doc.

→ **CLI and API provider differences by workflow:** [Provider Compatibility](design.md#provider-compatibility) — all seven workflows work with both provider types; the table shows confirm-gate pattern and execution model for each.

→ Full CLI command reference: [README — Agentic workflows](../README.md#agentic-workflows)

---

## Step 27 — Scan and retract sensitive data

Before sharing or publishing wiki content, scan for accidentally included personal or secret data — API keys, email addresses, phone numbers, SSNs, credit card numbers, and passwords.

**Option 1: Dry-run scan (recommended first step)**

```bash
synthadoc retract scan
```

The scan reports every match — page name, line number, and data type — without revealing any sensitive values. Nothing is modified.

**Option 2: Apply redactions**

```bash
synthadoc retract scan --apply
```

Prompts for confirmation, then writes `[REDACTED]` substitutions to each affected page. Run without `--yes` to review the list before committing.

**Option 3: Incremental scan (changed pages only)**

```bash
synthadoc retract scan --changed-only
synthadoc retract scan --apply --changed-only --yes
```

Skips pages that have not been modified since the last completed scan cycle. Useful for frequent manual checks on large wikis — only recently ingested or edited pages are checked.

**Option 4: Single-page scan**

```bash
synthadoc retract scan --slug my-page
synthadoc retract scan --slug my-page --apply --yes
```

**Option 5: Auto-schedule (background)**

Add to `config.toml` for automatic weekly scanning:

```toml
[security]
sensitive_scan_enabled = true
scan_interval_days = 7
```

The background scanner is incremental: each cycle only scans pages whose modification time is newer than the previous run. The server also automatically scans any pages written by an ingest job immediately after that job completes, so sensitive data is caught before the weekly pass.

View recent scan history:

```bash
synthadoc retract status
```

**Custom patterns**

Extend coverage to organisation-specific patterns without code changes.
In `config.toml`:

```toml
[[security.custom_patterns]]
name = "internal_token"
pattern = "INTERNAL-[A-Z0-9]{16}"
```

Matched lines are redacted the same way as built-in patterns.

## Citation quality

Generated pages include inline citation markers that link each claim to the
source lines it came from. When you view a page in Obsidian's **Reading View**,
these markers appear as clickable footnotes (`[1]`, `[2]`, etc.).

If a generated page has no citations, Synthadoc logs a warning suggesting you
switch to a more capable model. Models known to produce reliable citations:
Gemini 2.5 Flash, Gemini 2.5 Pro, MiniMax-M3, Claude Haiku 4.5 or later.

Cheaper flash-tier models may not follow the citation format — this is a known
limitation of smaller models and is not a bug in Synthadoc.

---

## Protected pages

Once you promote a page to `active` status, it is protected against silent
overwriting. If a new source contradicts an active page, Synthadoc flags it
for your review rather than replacing the page's content automatically.

To promote a page to active: `synthadoc lifecycle activate <slug>`

---

## Updating demo wikis

After upgrading Synthadoc, sync your demo wikis to pick up new content:

```bash
synthadoc templates sync --force   # overwrite existing wiki pages from the latest template (picks up citation markers and other page updates)
synthadoc templates sync           # additive only — copies new raw_sources and new wiki pages; existing wiki pages are not overwritten
```

## Uninstall a wiki

> **Caution:** Uninstalling permanently deletes the wiki directory and all its contents — pages, source files, audit database, and config. This cannot be undone. Run `synthadoc backup` first if you want to keep a copy:
>
> ```bash
> synthadoc backup -w history-of-computing   # creates a timestamped zip you can restore later
> ```

To uninstall:

```bash
synthadoc uninstall history-of-computing
```

The command asks for two confirmations — a yes/no prompt and then requires you to type the wiki name — before anything is deleted. This applies to both demo wikis and your own wikis.

---

## What's next?

You have now walked through every major Synthadoc feature on the demo wiki. When you're
ready to build a wiki for your own domain:

- **[README — Creating Your Own Wiki](../README.md#creating-your-own-wiki)** — step-by-step guide: install, configure, scaffold, ingest, and grow your wiki

Key differences from the demo:

- `synthadoc install <name> --target <dir> --domain "<your domain>"` generates LLM
  scaffold for your domain at install time (index categories, AGENTS.md, CLAUDE.md, GEMINI.md, purpose.md)
- Drop your own source files into `raw_sources/` and run batch ingest
- Use web search to fill knowledge gaps as your wiki grows
- Schedule nightly ingests and weekly scaffold refresh to keep it current automatically

---

# Appendix A — Obsidian Plugin Command Reference

All commands are accessible via the Command Palette (`Ctrl/Cmd+P` → type `Synthadoc`).

### Ingest


| Command                            | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Synthadoc: Ingest...`             | Tabbed modal with four ingest modes:**Web search** (type a topic, polls live), **URL** (paste a URL, polls live until complete), **All raw_sources** (queues every supported file in `raw_sources/`), **Pick files** (click **Browse…** to choose a folder, click **Scan** to list supported files — `wiki/` sub-folder contents and system files such as `log.md`, `routing.md`, `agents.md`, `readme.md`, `dashboard.md`, `index.md`, `overview.md`, and `claude.md` are excluded automatically with a count shown — then select files and click **Ingest selected**), and **Web search** (type a topic, set max results and poll interval, polls live). |
| `Synthadoc: Ingest: web search...` | Standalone live-polling modal — type a topic, set max results (1–50, default 20) and poll interval (500–10000 ms, default 2000 ms). Shows phase text, live pages list, and URL errors as fan-out jobs complete.`Ctrl/Cmd+Enter` to submit.                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Query


| Command                             | What it does                                                                                                                                                                                                                                                                         |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Synthadoc: Query: ask the wiki...` | Responsive modal — ask a natural-language question; the answer streams in token-by-token as the LLM generates it. Clickable`[[wikilinks]]` link to source pages. `Ctrl/Cmd+Enter` to submit. If a knowledge gap is detected, shows a callout with suggested `search for:` commands. |

### Lint


| Command                   | What it does                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Synthadoc: Lint: run...` | Modal with**Auto-resolve** and **Skip adversarial review** checkboxes. Runs a full lint pass with concurrent adversarial review of every page; polls progress live and reports contradiction, orphan, and adversarial warning counts when complete. Tick **Skip adversarial review** to run lint without the adversarial pass (also clears existing `lint_warnings`). |
| `Synthadoc: Lint: report` | Full lint report in a 3-tab modal —**Contradictions**, **Orphans**, and **Adversarial**. The Adversarial tab shows each flagged claim with its concern and suggested re-ingest commands derived from the page's source files.                                                                                                                                        |

### Jobs


| Command              | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Synthadoc: Jobs...` | Job table with status-filter checkboxes (pending, in_progress, completed, failed, skipped, dead, cancelled). Defaults to newest jobs first. Click**Status**, **Operation**, or **Created** column headers to sort — ▲ ascending, ▼ descending, ⇅ unsorted; click again to toggle direction. Auto-refreshes every 10 s (configurable). Paginated at 25 per page. Error details shown inline for failed/dead/cancelled jobs. **Retry selected** button is enabled when one or more checked jobs are failed, dead, or cancelled — click to re-queue them. **Delete selected** removes checked terminal jobs. A **Purge old jobs** footer row lets you enter a day threshold and remove old completed/dead records in one click. |

> **Tip — cancelling a bad batch:** `synthadoc jobs cancel -w <wiki> --yes` marks every
> pending job as `skipped` immediately. Follow up with `synthadoc jobs purge` to remove
> the skipped records.

### Wiki


| Command                                   | What it does                                                                                                                                             |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Synthadoc: Wiki: regenerate scaffold...` | Rewrites`index.md`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and `purpose.md` using the LLM. Polls job status live. All existing wiki pages are preserved. |

### Lifecycle


| Command                            | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Synthadoc: Manage Page Lifecycle` | Two-tab modal.**Current States tab** — sortable, filterable, paginated table of all wiki pages with their current lifecycle state (`draft`, `active`, `contradicted`, `stale`, `archived`) and last transition timestamp. State filter checkboxes narrow the table. Click column headers to sort. Each row shows valid transition action buttons — click to trigger a transition; a reason dialog appears before committing. Draft and stale badge links on the lint modal and jobs panel open this table pre-filtered to that state. **Audit Log tab** — full history of every lifecycle state transition across all pages; searchable by slug, filterable by target state, sortable by any column, with pagination. Each row shows slug, From state, To state, triggered-by (`ingest`, `lint`, `cli`, `api`), timestamp, and reason. |

### Audit


| Command               | What it does                                                                                                                                                                                                                                                                                                                                   |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Synthadoc: Audit...` | Tabbed modal with four views:**Query history** — recent questions, sub-question counts, tokens, cost per query. **Ingest history** — source file, wiki page slug, tokens, cost, timestamp. **Events** — contradictions found, auto-resolutions, cost gate triggers (max 1000). **Cost summary** — total tokens + USD with daily breakdown. |

### Routing


| Command                                    | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Synthadoc: Routing: manage ROUTING.md...` | Modal panel with three buttons.**Init** creates `ROUTING.md` from your current `index.md` branch structure (enabled only when `ROUTING.md` does not exist). **Validate** reports dangling slugs — pages listed in `ROUTING.md` that no longer exist — as a dry-run with no changes made (enabled only when `ROUTING.md` exists). **Clean** removes dangling slugs from `ROUTING.md` and refreshes the preview (enabled only when `ROUTING.md` exists). Results show per-entry `[Branch] [[slug]]` detail rows inline. |

### Staging & Candidates


| Command                                            | What it does                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Synthadoc: Staging: manage staging policy...`     | Shows the current policy in plain language. A segmented control switches between**Off**, **All**, and **Threshold**. When **Threshold** is selected, a second control sets the minimum confidence (**High** / **Medium** / **Low**). **Save** applies the change immediately. A footer link opens the Candidates panel.                                                 |
| `Synthadoc: Candidates: review candidate pages...` | Paginated table (50 per page) of all staged candidate pages. Each row shows the slug, colour-coded confidence badge, and ingest timestamp. Check rows and click**Promote Selected** or **Discard Selected**, or use **Promote All** / **Discard All** to act on every candidate at once. Table reloads after each action. A footer link opens the Staging policy panel. |

### Context packs


| Command                                     | What it does                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Synthadoc: Context: build context pack...` | Enter a goal or question and a token budget (default 4000). Press**Build Context Pack** or `Ctrl/Cmd+Enter`. The server decomposes the goal, retrieves the most relevant wiki pages via BM25, and packs them into a single cited Markdown document within the budget. The result appears in a read-only text area. **Copy to Clipboard** copies it to the OS clipboard; **Save as .md** downloads it as a Markdown file. |

### Export


| Command                  | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Synthadoc: Export Wiki` | Modal with a format dropdown (`okf`, `json`, `llms.txt`, `llms-full.txt`, `graphml`), a full-width output path field pre-filled with today's date and the correct extension, and a status filter selector. A brief description at the top explains what each format contains. Click **Export** to write the file to your vault's `exports/` folder; the file opens automatically. For GraphML format, a **View Graph** button also appears for an inline Cytoscape.js preview — nodes are coloured by lifecycle state (active=green, draft=yellow, stale=orange, contradicted=red, archived=grey) and edges represent wikilinks. To load the graph in a dedicated tool, export to file and open in **yEd**, **Gephi**, or **Cytoscape**. |

> **UX note:** All modals are draggable and support full text selection and copy-paste.

### Ribbon icon

The Synthadoc ribbon icon (left sidebar) shows live engine status: `✅ online · 12 pages`
or `❌ offline — run 'synthadoc serve'`. Right-click the ribbon to pin it if it is hidden
below other plugin icons.

---

## Appendix B — Hooks: auto-commit wiki to git

Hooks are shell commands triggered on lifecycle events. Wire `git-auto-commit.py` so
every successful ingest produces a git commit.

### One-time setup

**1. Initialise git in the wiki root:**

```bash
cd ~/wikis/history-of-computing
git init
git add .
git commit -m "init: initial wiki snapshot"
```

**2. Copy the hook script:**

```bash
cp /path/to/synthadoc-repo/hooks/git-auto-commit.py .
```

**3. Add to `.synthadoc/config.toml`:**

```toml
[hooks]
on_ingest_complete = "python git-auto-commit.py"
```

**4. Restart the server** to pick up the config change.

### Verify

After the next ingest:

```bash
git log --oneline -3
```

```
a3f1b2c wiki: ingest konrad-zuse-z3-computer.md → created konrad-zuse
d9e4c81 wiki: ingest turing-enigma-decryption.pdf → updated alan-turing
```

> **More hooks:** see [`hooks/README.md`](../hooks/README.md) for the full library and
> contribution guidelines. Available events: `on_ingest_complete`, `on_lint_complete`.

---

## Appendix C — Switching LLM providers

Synthadoc defaults to **Gemini Flash** — free, no credit card, 1 million tokens per day.
Switch by editing `<wiki-root>/.synthadoc/config.toml` and restarting the server.


| Provider      | Env var             | Free tier                                          | Vision          |
| ------------- | ------------------- | -------------------------------------------------- | --------------- |
| `gemini`      | `GEMINI_API_KEY`    | **Yes — default** · 15 RPM / 1M tokens/day       | Yes             |
| `groq`        | `GROQ_API_KEY`      | Yes — fast Llama, 100K tokens/day                 | No              |
| `ollama`      | _(none)_            | Yes — fully local;**GPU required** (CPU too slow) | Model-dependent |
| `minimax`     | `MINIMAX_API_KEY`   | No — cheapest paid text rates                     | No              |
| `anthropic`   | `ANTHROPIC_API_KEY` | No — highest quality, pay-per-token               | Yes             |
| `openai`      | `OPENAI_API_KEY`    | No — pay-per-token                                | Yes             |
| `qwen`        | `QWEN_API_KEY`      | Yes — 1M free tokens (90-day trial), then paid    | Model-dependent |
| `deepseek`    | `DEEPSEEK_API_KEY`  | No — very affordable pricing                      | No              |
| `claude-code` | _(none)_            | Yes — uses your Claude Code subscription, no key  | No              |
| `opencode`    | _(none)_            | Yes — free via Opencode Zen, no API key           | No              |

> CLI providers (`claude-code`, `opencode`) require no API key but need the tool installed and authenticated in your terminal. Web search still requires `TAVILY_API_KEY`. See [Appendix G](#appendix-g--using-a-coding-tool-as-your-llm-provider) for setup details.

**Change the provider** — edit `.synthadoc/config.toml`. Keep exactly one `default` line uncommented; comment out the rest with `#`:

```toml
[agents]
# Uncomment exactly one line — comment out all others

default = { provider = "gemini",    model = "gemini-2.5-flash" }                    # Gemini Flash (default, free tier)
# default = { provider = "groq",      model = "openai/gpt-oss-20b" }               # Groq (paid, $0.075/$0.30 per 1M)
# default = { provider = "qwen",      model = "qwen-plus" }                              # Qwen via DashScope (1M free tokens)
# default = { provider = "qwen",      model = "qwen-plus", thinking = "disabled" }      # Qwen — thinking suppressed (faster)
# default = { provider = "deepseek",  model = "deepseek-v4-flash" }                              # DeepSeek (very affordable, non-thinking)
# default = { provider = "deepseek",  model = "deepseek-v4-flash", thinking = "enabled" }       # DeepSeek thinking mode (chain-of-thought; replaces deepseek-reasoner)
# default = { provider = "minimax",   model = "MiniMax-M3", thinking = "disabled" } # MiniMax M3 (fast, low-cost)
# default = { provider = "anthropic", model = "claude-sonnet-4-6" }                 # Anthropic Sonnet (high quality)
# default = { provider = "anthropic", model = "claude-opus-4-8" }                   # Anthropic Opus (highest quality)
# default = { provider = "openai",    model = "gpt-4o-mini" }                       # OpenAI
# default = { provider = "ollama",    model = "llama3.2" }                          # Ollama (local, GPU required)
# default = { provider = "claude-code" }                                             # Claude Code CLI (no API key)
# default = { provider = "opencode", model = "opencode/big-pickle" }                # Opencode Zen (free; connect first: opencode → /connect → select Zen)
```

Restart `synthadoc serve`. The startup banner confirms `LLM: <provider>/<model>`.

> **Rate limit tips:**
>
> - **Gemini** free tier: 15 RPM. If you see `429 RateLimitError` during a long ingest, wait 60 s and retry, or switch to Groq or MiniMax.
> - **Groq** free tier: 100K tokens/day — adequate for short demo sessions; heavy web search ingest can exhaust it.
> - **MiniMax:** no free tier. M3 supports multimodal (text + image) and a `thinking` field: set `thinking = "disabled"` for faster, cheaper responses; omit it to use the model default.
> - **Thinking field (MiniMax M3, Qwen DashScope):** Add `thinking = "disabled"` to your `agents.default` line to suppress chain-of-thought reasoning. Useful when you want lower latency and cost and don't need the model to reason step-by-step. Example: `default = { provider = "minimax", model = "MiniMax-M3", thinking = "disabled" }`
> - **Ollama — GPU required:** Local Ollama models require a CUDA or Metal GPU to be practically usable. On CPU-only machines, processing an 8 K-token context takes 5–10 minutes before the first token is generated — well beyond any reasonable timeout. If you do not have a GPU, use a cloud provider instead (Gemini 2.5 Flash Lite is free). Install Ollama from [ollama.com](https://ollama.com); no API key needed.
> - **Qwen cloud (DashScope):** New accounts get **1 million free tokens** (valid 90 days after activating Model Studio). Set `QWEN_API_KEY` (get one at [bailian.console.aliyun.com](https://bailian.console.aliyun.com/)) and use `model = "qwen-plus"` or `"qwen-max"`. DashScope supports a `thinking` field: set `thinking = "disabled"` for faster responses.
> - **DeepSeek:** Very affordable cloud API. Use `deepseek-v4-flash` for standard mode or add `thinking = "enabled"` for chain-of-thought reasoning (the latter replaces the deprecated `deepseek-reasoner`). Set `DEEPSEEK_API_KEY` (get one at [platform.deepseek.com](https://platform.deepseek.com/api_keys)).

---

## Appendix D — Tavily web search key

Web search ingestion (Step 10) requires a Tavily API key. Get a free key at
**[tavily.com](https://tavily.com)** (1,000 searches/month, no credit card required).

**Set the key:**

```bash
# Linux / macOS
export TAVILY_API_KEY="tvly-your-key-here"

# Windows (cmd.exe — current session)
set TAVILY_API_KEY=tvly-your-key-here

# Windows (cmd.exe — permanent)
setx TAVILY_API_KEY tvly-your-key-here
```

If this key is absent, the server starts normally but web search jobs fail with
`[ERR-SKILL-004]`. All other features work without it.

---

## Appendix E — 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.

Read this appendix when you are ready to run a real wiki or change a default.

### How configuration works

Settings are resolved in three layers — later layers win:

```
1. Built-in defaults          (always applied)
2. ~/.synthadoc/config.toml   (global — your preferences across all wikis)
3. <wiki-root>/.synthadoc/config.toml   (per-project — overrides for one wiki)
```

Neither file is required. If both are absent, the built-in defaults take effect.

### Global config — `~/.synthadoc/config.toml`

**Use this to set preferences that apply to every wiki on your machine** — primarily your default LLM provider and the wiki registry.

```toml
[agents]
default = { provider = "gemini", model = "gemini-2.5-flash" }  # free tier
lint    = { provider = "groq",   model = "openai/gpt-oss-20b" }  # cheaper for lint

[wikis]
research = "~/wikis/research"
work     = "~/wikis/work"
```

Common reason to edit: switching from the Anthropic default to Gemini Flash (free tier) so all wikis use it without touching each project config.

### Per-project config — `<wiki-root>/.synthadoc/config.toml`

**Use this when one wiki needs different settings from the global default** — a different port, tighter cost limits, wiki-specific hooks, or web search.

```toml
[server]
port = 7071          # required if running more than one wiki simultaneously

[cost]
soft_warn_usd = 0.50
hard_gate_usd = 2.00

[ingest]
fetch_timeout_seconds = 60   # increase if slow sites time out during web search

[web_search]
provider    = "tavily"
max_results = 20

# Optional: enable semantic re-ranking (downloads ~130 MB model once)
# [search]
# vector = true
# vector_top_candidates = 20   # BM25 candidate pool before cosine re-rank

[hooks]
on_ingest_complete = "python git-auto-commit.py"
```

Common reason to edit: each wiki needs its own port when running multiple wikis at the same time.

Full config reference including all keys, defaults, and multi-wiki setup: [docs/design.md — Configuration](design.md#configuration).

---

## Appendix F — Build Your Own Wiki from scratch

This appendix walks through creating a wiki for your own domain — no demo template.

### 1. Install

```bash
synthadoc install my-research --target ~/wikis --domain "My research domain"
synthadoc use my-research
synthadoc status
```

`--domain` is a free-text description of the subject area — the LLM uses it to generate
domain-aware starter files: `wiki/index.md`, `wiki/purpose.md`, `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md`.

### 2. Start the server

```bash
synthadoc serve -w my-research
```

### 3. Scaffold

Before ingesting any content, run scaffold once to build a clean, domain-aware index:

```bash
synthadoc scaffold
```

### 4. Ingest sources

```bash
synthadoc ingest path/to/document.pdf
synthadoc ingest "https://example.com/article"
synthadoc ingest "search for: <your domain topic>"
synthadoc jobs list
```

### 5. Query

```bash
synthadoc query "What are the key themes?"
```

### 6. Lint

```bash
synthadoc lint report
synthadoc lint run --auto-resolve
```

### 7. Open in Obsidian

Open `~/wikis/my-research` as an Obsidian vault.

### Working with multiple wikis

```bash
synthadoc use finance-wiki     # switch active wiki
synthadoc status               # checks finance-wiki
synthadoc status -w legal-wiki # one-off check without switching
synthadoc use                  # confirm which wiki is active
```


| Method                         | Scope                               |
| ------------------------------ | ----------------------------------- |
| `synthadoc use <name>`         | Persistent across terminal sessions |
| `export SYNTHADOC_WIKI=<name>` | Current shell session only          |
| `-w <name>` on command         | Single command only                 |

---

## Appendix G — Using a Coding Tool as Your LLM Provider

If you already have a **Claude Code** or **Opencode** subscription, you can use it to power Synthadoc's LLM calls — no separate API key required.

### Setup

Open `.synthadoc/config.toml` in your wiki root, comment out the active `default` line, and uncomment the one for your tool:

```toml
[agents]
# default = { provider = "claude-code" }                                       # no API key — uses your Claude Code subscription
# default = { provider = "opencode", model = "opencode/big-pickle" }          # free via Opencode Zen — connect first: opencode → /connect → select Zen
```

For Claude Code, `model` is optional — omit it to use Claude Code's own configured default. For Opencode, specify `model = "opencode/big-pickle"` to use the free Zen tier. Restart the server after saving.

Ensure the tool is installed and authenticated in your terminal before starting the server. No environment variables are required.

![Switching LLM providers in config.toml — Claude Code enabled](png/synthadoc-switch-provider.png)

> **Web search still needs Tavily.** Even with a CLI provider, `search for:` ingest requires a `TAVILY_API_KEY`. The free tier (1,000 searches/month, no credit card required) is more than enough for typical Synthadoc use — see [Appendix D](#appendix-d--tavily-web-search-key).

> **Note:** CLI providers use BM25 search only — vector/semantic search (`[search] vector = true`) is not supported and will be silently bypassed.

> **Agentic workflows:** All seven maintenance workflows (ingest, wikilinks, citations, contradiction, orphan, lint, scaffold) are fully supported by CLI providers. Each workflow uses a Python-driven path that calls the same tool functions directly — no LLM wire-format loop is sent to the subprocess. See [Provider Compatibility](design.md#provider-compatibility) for the per-workflow execution model.

### Demo: ingest + query

Start the server and ingest a source as normal:

```bash
synthadoc serve -w my-wiki
synthadoc ingest "https://example.com/article" -w my-wiki
synthadoc query "What does the article cover?" -w my-wiki
```

The output is identical to a direct API provider. The only difference is that each LLM call is handled by Claude Code or Opencode running as a subprocess.

> **Performance note:** CLI providers add subprocess startup overhead per LLM call. For high-volume batch ingest, a direct API provider (`anthropic`, `gemini`, etc.) is faster.

### Demo: temporary provider override

If your coding tool quota is exhausted and you need to continue ingesting, override the provider for the current server session without editing `config.toml`:

```bash
synthadoc serve -w my-wiki --provider anthropic
```

This uses `ANTHROPIC_API_KEY` (or whichever provider you specify) for that session only. When quota resets, restart without `--provider` to return to the CLI provider.

### Troubleshooting

**"usage quota exhausted" error in job log:**
Your coding tool subscription has hit its usage limit. Options:

1. Wait for quota to reset (typically a few hours)
2. Retry the job: `synthadoc ingest <source> -w my-wiki`
3. Switch temporarily: `synthadoc serve -w my-wiki --provider anthropic`

**"not found in PATH" error on server start:**
Install and authenticate the coding tool first:

- Claude Code: [claude.ai/code](https://claude.ai/code)
- Opencode: [opencode.ai](https://opencode.ai)

---

## Appendix H — BM25 Routing Performance Benchmarks

Measured on Windows 11, Python 3.14, pytest-benchmark 5.2.3 (`time.perf_counter`).
Synthetic wiki with 10 branches; scoped tests search 2 branches (~20% of corpus).
Each result is the median of 5 rounds.

> **What these numbers measure:** The BM25 corpus is built from disk on the first query and then cached in memory for the lifetime of the server process. The reported medians reflect **warm-cache latency** — rounds 2–5 of each benchmark run, where all page content is already in memory. Cold-start latency (the very first query after server start, or immediately after a page write that invalidates the cache) will be higher, proportional to page count and local disk speed. On a running server handling real traffic, warm-cache numbers are representative of typical query latency.

### Scoped search (2 of 10 branches)


| Pages | Median |   Min |   Max |
| ----: | -----: | ----: | ----: |
|   100 |  14 ms |  5 ms | 36 ms |
|   500 |  16 ms |  7 ms | 19 ms |
|  1000 |   9 ms |  8 ms | 12 ms |
| 10000 |  41 ms | 39 ms | 50 ms |

Routing keeps latency nearly flat across corpus sizes — the search is bounded by branch size, not total page count.

### Full-corpus search (no routing)


| Pages | Median |    Min |    Max |
| ----: | -----: | -----: | -----: |
|   100 |   7 ms |   6 ms |  32 ms |
|   500 |  14 ms |  14 ms |  16 ms |
|  1000 |  22 ms |  21 ms |  31 ms |
| 10000 | 191 ms | 184 ms | 210 ms |

Full-corpus BM25 scales roughly linearly with page count. At 10000 pages the median is 191 ms — comfortably within a 500 ms interactive budget.

### Takeaway

For wikis under ~1000 pages the difference between scoped and full-corpus is negligible (both under 25 ms). At 10000 pages routing delivers a **4–5× speedup** (41 ms vs. 191 ms). Enable ROUTING.md ([Step 17](#step-17--set-up-routingmd--scoped-search)) once your wiki exceeds a few hundred pages.

---

<a name="appendix-i--connect-claude-via-mcp"></a>

## Appendix I — Connect Claude via MCP

Synthadoc exposes an MCP server so Claude Desktop, Claude Code, or any MCP-compatible agent can use your wiki as persistent domain memory.

**Architecture:** Claude is the brain — it receives your questions, searches the wiki, reads pages, and synthesises answers using its own LLM. Synthadoc is the memory — it stores pages, runs keyword search, and manages lifecycle and jobs. Synthadoc does not call an LLM for content questions in MCP mode. The only exceptions are `synthadoc_ingest` (synthesis at write time) and `synthadoc_lint` (adversarial review), which are inherently wiki-side operations.

**Key distinction:** Web UI — Synthadoc is the interface. MCP — Claude is the interface.

---

### Transport options


|                          | Claude Desktop      | Claude Code CLI | Custom agents (n8n, LangGraph…) |
| ------------------------ | ------------------- | --------------- | -------------------------------- |
| **stdio** (`--mcp-only`) | Yes — only option  | Yes             | No                               |
| **HTTP/SSE** (`url`)     | No — not supported | Yes             | Yes                              |

Claude Desktop only supports stdio — it spawns Synthadoc as a subprocess and manages the process lifecycle. HTTP/SSE is available for Claude Code and any custom MCP client.

---

### Security note

Synthadoc binds to `127.0.0.1` (localhost) by default. This means:

- **No remote access** — the server is only reachable from the same machine. Other hosts on your network cannot connect.
- **No authentication** — any process on the same machine can reach the API. Do not change the bind address to `0.0.0.0` on a shared or networked machine without adding a reverse proxy with authentication in front.

If you need remote access (e.g. connecting from a different machine), put Synthadoc behind a reverse proxy (nginx, Caddy) and require authentication at the proxy layer — do not expose port 7070 directly.

---

### Multiple wikis

Register each wiki as a separate entry. Synthadoc prefixes every tool description with `Wiki: <wiki-name>.` at startup — so Claude knows which server covers which domain and routes correctly without you having to specify it.

> **Claude Desktop key names:** Claude Desktop does not accept hyphens in MCP server key names. Use underscores instead (e.g. `synthadoc_history_of_computing`, not `synthadoc-history-of-computing`).

**Claude Desktop (stdio):**

```json
{
  "mcpServers": {
    "synthadoc_history_of_computing": {
      "command": "C:\\Users\\<you>\\...\\synthadoc.exe",
      "args": ["serve", "-w", "C:\\Users\\<you>\\wikis\\history-of-computing", "--mcp-only"]
    },
    "synthadoc_ai_research": {
      "command": "C:\\Users\\<you>\\...\\synthadoc.exe",
      "args": ["serve", "-w", "C:\\Users\\<you>\\wikis\\ai-research", "--mcp-only"]
    }
  }
}
```

**Claude Code / custom agents (HTTP/SSE):**

```powershell
synthadoc serve -w "C:\wikis\history-of-computing"   # port 7070
synthadoc serve -w "C:\wikis\ai-research"             # port 7071
```

```json
{
  "mcpServers": {
    "synthadoc-history-of-computing": { "url": "http://127.0.0.1:7070/mcp/sse" },
    "synthadoc-ai-research":          { "url": "http://127.0.0.1:7071/mcp/sse" }
  }
}
```

---

### Claude Desktop

Claude Desktop only supports stdio — it spawns Synthadoc as a subprocess and manages it automatically.

**Step 1 — Find the full path to `synthadoc.exe`**

Claude Desktop uses a restricted PATH and will not find `synthadoc` by name alone:

```powershell
(Get-Command synthadoc).Source
```

Typical result on Windows: `C:\Users\<you>\AppData\Roaming\Python\Python314\Scripts\synthadoc.exe`

**Step 2 — Add the config entry**

```json
{
  "mcpServers": {
    "synthadoc_history_of_computing": {
      "command": "C:\\Users\\<you>\\AppData\\Roaming\\Python\\Python314\\Scripts\\synthadoc.exe",
      "args": ["serve", "-w", "C:\\Users\\<you>\\wikis\\history-of-computing", "--mcp-only"]
    }
  }
}
```

Use **absolute paths** for both `synthadoc.exe` and the wiki root. Relative paths and wiki name aliases do not work from Claude Desktop. Key names must use underscores, not hyphens — Claude Desktop rejects hyphenated server names.

**Step 3 — Restart Claude Desktop**

Fully quit from the system tray, then reopen.

---

### Claude Code

Claude Code supports both SSE (recommended — connects to a running server) and stdio.

#### SSE transport (recommended)

**Step 1 — Start the Synthadoc server**

```powershell
synthadoc serve -w "C:\Users\<you>\wikis\history-of-computing"
```

**Step 2 — Register the MCP server**

```powershell
claude mcp add --transport sse synthadoc-history-of-computing http://127.0.0.1:7070/mcp/sse
```

> Use `--transport sse`, not `--transport http` — FastMCP uses the SSE protocol, not Streamable HTTP.

**Step 3 — Verify**

```powershell
claude mcp list
```

`synthadoc-history-of-computing` should show `✔ Connected`.

**Step 4 — Test in a Claude Code session**

```powershell
claude
```

Ask: `What's the status of my wiki?` — Claude Code calls `synthadoc_status` directly against the running server.

#### stdio transport

Use this if you don't want to manage a separate server process:

```powershell
claude mcp add synthadoc-history-of-computing "C:\Users\<you>\...\synthadoc.exe" -- serve -w "C:\Users\<you>\wikis\history-of-computing" --mcp-only
```

---

### HTTP/SSE (n8n, LangGraph, custom agents)

The same endpoint works for any MCP-compatible client:

```
MCP SSE endpoint: http://127.0.0.1:7070/mcp/sse
```

No API key required. Verify it is live:

```
curl -i http://127.0.0.1:7070/mcp/sse
```

You should receive `HTTP/1.1 200 OK` with `content-type: text/event-stream` and the connection will hang open (correct — SSE streams stay open).

---

### What to ask once connected

**Wiki content questions** — Claude fetches raw content and synthesises the answer itself (no LLM call on the Synthadoc side):


| Example prompt                                                        | Tool used                                                                  |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| "What's the status of my wiki?"                                       | `synthadoc_status`                                                         |
| "List all pages in the wiki"                                          | `synthadoc_list_pages`                                                     |
| "Show me only the active pages"                                       | `synthadoc_list_pages` (status filter)                                     |
| "Search for Grace Hopper"                                             | `synthadoc_search`                                                         |
| "Read the grace-hopper page"                                          | `synthadoc_read_page`                                                      |
| "What does my wiki say about quantum error correction?"               | `synthadoc_search` + `synthadoc_read_page`                                 |
| "Show me the adversarial warnings for the early-neural-networks page" | `synthadoc_read_page`                                                      |
| "Which pages have citations? Show me what they are."                  | `synthadoc_list_pages` + `synthadoc_read_page`                             |
| "Build me a context pack on early neural networks"                    | `synthadoc_context`                                                        |
| "Export my wiki in OKF format"                                        | `synthadoc_export` (okf — writes folder to default path, tells you where) |
| "Export only active pages as llms.txt"                                | `synthadoc_export` (format + status_filter, returns content inline)        |

**Wiki health — zero cost, instant:**


| Example prompt                  | Tool used               |
| ------------------------------- | ----------------------- |
| "Which pages are contradicted?" | `synthadoc_lint_report` |
| "Are there any orphan pages?"   | `synthadoc_lint_report` |
| "Give me a wiki health summary" | `synthadoc_lint_report` |

**Synthadoc operations** — Claude manages the wiki on your behalf:


| Example prompt                                        | Tool used             |
| ----------------------------------------------------- | --------------------- |
| "List recent jobs"                                    | `synthadoc_jobs`      |
| "Show me any failed or skipped jobs"                  | `synthadoc_jobs`      |
| "Ingest this URL: https://example.com/paper"          | `synthadoc_ingest`    |
| "Run a full lint check on the wiki"                   | `synthadoc_lint`      |
| "Mark the grace-hopper page as stale — needs review" | `synthadoc_lifecycle` |

---

### Demo: context pack via Claude Code

Once connected, ask Claude Code:

> **"Build me a context pack on early neural networks"**

Claude calls `synthadoc_context` automatically and returns something like:

```
Here's the context pack assembled for "early neural networks" (1,280 / 10,000 tokens used):

Directly Relevant Pages

| Slug                            | Relevance | Confidence | Tags                                              |
|---------------------------------|-----------|------------|---------------------------------------------------|
| artificial-intelligence-history | 9.65      | High       | neural-networks, deep-learning, machine-learning  |
| computing-history-timeline      | 11.16     | Medium     | artificial-intelligence, deep-learning, algorithms|

Key excerpts:

artificial-intelligence-history — Covers Turing's 1950 Turing Test paper, the 1956 Dartmouth
Conference (where "artificial intelligence" was coined), and the first AI winter (1974–1980).

computing-history-timeline — Traces from Ada Lovelace (1843) through Turing (1936), von Neumann
architecture (1945), and includes tags for deep-learning milestones.
```

**What the response tells you:**


| Field                        | Meaning                                                                                |
| ---------------------------- | -------------------------------------------------------------------------------------- |
| `tokens_used / token_budget` | How much of the budget was consumed — pages stop being added once the budget is full  |
| `relevance`                  | BM25 score — higher means stronger keyword match to your goal                         |
| `confidence`                 | LLM-assigned confidence in the page's coverage of the topic                            |
| `omitted`                    | Pages that were relevant but didn't fit within the budget (none here — only 13% used) |

To request a tighter pack (forces prioritisation and shows omitted pages clearly):

> **"Build a context pack on early neural networks with a 2000 token budget"**

---

### Tool reference

**Claude** = Claude's LLM synthesises the answer (no Synthadoc LLM call). **Synthadoc** = Synthadoc's configured LLM provider runs (tokens billed to your provider account). **Neither** = pure data read or write, no LLM involved.


| Tool                    | Parameters                                                                                                                                           | What it does                                                                                                                                                                      | Who calls LLM? |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `synthadoc_search`      | `terms: str`                                                                                                                                         | BM25 keyword search — returns ranked titles, slugs, and snippets                                                                                                                 | Claude         |
| `synthadoc_read_page`   | `slug: str`                                                                                                                                          | Read a page's full content, status, type, tags, adversarial warnings, and source citations                                                                                        | Claude         |
| `synthadoc_list_pages`  | `status?: str` (default `"all"`)                                                                                                                     | List all pages with title, status, type, and`has_sources` flag; filterable by lifecycle state                                                                                     | Neither        |
| `synthadoc_write_page`  | `slug: str`, `content: str`, `title?: str`                                                                                                           | Update page content (clears contradiction note, bumps epoch)                                                                                                                      | Neither        |
| `synthadoc_status`      | *(none)*                                                                                                                                             | Get wiki page count and path                                                                                                                                                      | Neither        |
| `synthadoc_jobs`        | `status?: str` (`all`/`pending`/`running`/`completed`/`failed`/`skipped`/`cancelled`/`dead`)                                                         | List recent jobs, optionally filtered by status                                                                                                                                   | Neither        |
| `synthadoc_lifecycle`   | `slug: str`, `to_state: str`, `reason: str`                                                                                                          | Transition a page's lifecycle state; writes an immutable audit record                                                                                                             | Neither        |
| `synthadoc_lint_report` | *(none)*                                                                                                                                             | Instant wiki health read — contradicted pages, orphans, adversarial warning counts;**no job, no LLM**                                                                            | Neither        |
| `synthadoc_context`     | `goal: str`, `token_budget?: int` (default `10000`)                                                                                                  | Build a token-budgeted context pack — ranked excerpts that fit within the budget; omitted slugs listed separately                                                                | Neither        |
| `synthadoc_export`      | `format?: str` (default `"okf"`), `output_path?: str` (okf defaults to `<wiki>/exports/<name>-okf-<date>/`), `status_filter?: str` (default `"all"`) | Export the wiki. `pages` in the response = exported wiki pages only (system pages are always excluded). `files_written` (OKF only) includes index.md and log.md in addition to wiki pages. OKF with `status_filter="all"` exports active + contradicted pages only; draft, stale, and archived are excluded. Other formats export all pages matching the filter. Formats: `okf`, `llms.txt`, `llms-full.txt`, `json`, `graphml` | Neither        |
| `synthadoc_ingest`      | `source: str`                                                                                                                                        | Enqueue a URL or file for ingest — returns a job ID                                                                                                                              | Synthadoc      |
| `synthadoc_lint`        | `scope?: str` (default `"all"`)                                                                                                                      | Enqueue a full LLM lint analysis — returns a job ID; use`synthadoc_jobs` to poll                                                                                                 | Synthadoc      |

Valid `to_state` values for `synthadoc_lifecycle`: `active`, `draft`, `stale`, `contradicted`, `archived`.

> **lint vs. lint_report:** Use `synthadoc_lint_report` to check current wiki health instantly (no tokens spent). Use `synthadoc_lint` when you want to run fresh LLM analysis — it enqueues a background job and returns a job ID.

> **Tuning the context budget:** `synthadoc_context` defaults to 10 000 tokens per pack. Pass `token_budget` in the tool call to override for a single request (e.g. `token_budget: 20000`). To change the project-wide default, add this to `.synthadoc/config.toml`:
>
> ```toml
> [query]
> context_token_budget = 20000
> ```

For architecture details and the brain/memory use case framing, see [docs/design.md — MCP Server](design.md#27-mcp-server).

---

### Troubleshooting

**Server does not appear in the panel**

- Use the full path to `synthadoc.exe`, not the bare command name
- Use absolute paths for the wiki root — aliases and relative paths are not resolved by Claude Desktop
- Fully quit Claude Desktop from the system tray before reopening (window close is not a full restart)

**Server appears but shows an error badge**

- Click **View Logs** in the Developer panel to see the startup error
- Verify the wiki path exists and contains a `.synthadoc/` directory (run `synthadoc serve -w <path> --mcp-only` manually to confirm it starts)

**SSE endpoint returns 404**

- The correct URL is `/mcp/sse`, not `/mcp` or `/mcp/`
- Verify the server is running with `curl -i http://127.0.0.1:7070/`

---

<a name="appendix-j--backup--restore"></a>

## Appendix J — Backup & Restore

### When to use it


| Scenario                                                                   | Command                                   |
| -------------------------------------------------------------------------- | ----------------------------------------- |
| Move wiki to another machine                                               | `backup` on old machine, `restore` on new |
| Snapshot before a risky operation (routing clean, adversarial lint)        | `backup` before running the operation     |
| Development workflow: freeze a good state, do risky dev, restore if needed | `backup` → dev work → `restore`         |
| CI/test fixture: start from a known state before each run                  | `restore` at test start                   |
| Share an exact wiki state with a colleague                                 | Send the zip, they run`restore`           |

### Database reliability — WAL mode

All Synthadoc databases (`audit.db`, `jobs.db`, `cache.db`) run in **WAL mode** (SQLite Write-Ahead Logging). WAL mode allows concurrent reads during writes, which eliminates `database is locked` errors when the CLI, Obsidian plugin, and server access the database simultaneously — a common source of friction on Windows. No configuration is needed; existing databases upgrade automatically on first open after a Synthadoc upgrade.

Backup uses in-process serialization rather than a file copy, making `synthadoc backup` safe to run against a live database on any platform.

### Backup

```
synthadoc backup -w <wiki>
```

Creates a timestamped compressed zip in the current directory:

```
synthadoc-backup-history-of-computing-20260624-103000.zip
```

**What's included by default:** wiki pages, candidates, config, audit database, exports, query cache, raw sources, and root-level wiki files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `ROUTING.md`, `log.md`, and any `*.txt` batch ingest files) when present.

**Flags:**

```
--output <dir>       Write zip to this directory (default: current directory)
--no-sources         Exclude raw_sources/ (reduces size for large crawled wikis)
--no-exports         Exclude exports/ directory
--no-cache           Exclude cache.db
```

### Restore

```
synthadoc restore <backup.zip>
```

Restores to the same directory as the zip file by default. Detects port conflicts and suggests the next free port.

**Flags:**

```
--name <name>        Restore under a different wiki name
--target <dir>       Parent directory for the restored wiki (default: zip's folder)
--port <N>           Use this port (skips interactive prompt)
```

**Post-restore checklist (printed automatically):**

1. Set your LLM API key in your environment
2. `synthadoc serve -w <wiki-name>`
3. Open the vault in Obsidian — the Obsidian plugin is reinstalled and pre-enabled automatically; Server URL is updated to match the restored port, no manual steps needed

### What is and isn't backed up


| Item                                                          | Included?  | Notes                                                                          |
| ------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------ |
| `wiki/*.md`                                                   | ✓ Always  | All compiled wiki pages                                                        |
| `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `ROUTING.md`, `log.md` | ✓ Always  | Wiki root files                                                                |
| `hooks/`                                                      | ✓ Always  | User hook scripts                                                              |
| `.synthadoc/config.toml`                                      | ✓ Always  | Server config                                                                  |
| `.synthadoc/audit.db`                                         | ✓ Always  | Full audit trail, lifecycle state, chat history                                |
| `.synthadoc/extracted/`                                       | ✓ Always  | Text sidecars + PDF pagemaps — required by Source Viewer and Provenance modal |
| `.synthadoc/cache.db`                                         | ✓ Default | Skip with`--no-cache`                                                          |
| `exports/`                                                    | ✓ Default | Skip with`--no-exports`                                                        |
| `raw_sources/`                                                | ✓ Default | Skip with`--no-sources` to reduce zip size                                     |
| LLM API keys                                                  | ✗ Never   | Never stored in config; set via environment variable                           |
| `jobs.db`                                                     | ✗ Never   | Stale job queue; job*history* is in `audit.db`                                 |
| `embeddings.db`                                               | ✗ Never   | Rebuilt automatically on next server start                                     |
| `server.pid`                                                  | ✗ Never   | Machine-specific process ID                                                    |
| `logs/`                                                       | ✗ Never   | Server application logs                                                        |

---

## Appendix K — Domain Templates

Domain templates give you a production-ready wiki structure on day one — no
blank-canvas decisions required. Each template is a curated starting point for
a specific industry domain, with pre-built routing, domain-tuned agent
guidelines, scaffold stubs, blank intake forms, and a hand-picked list of
seeds to ingest first.

### Browse available templates

```bash
synthadoc templates list
```

Output shows all 30 templates grouped by category:

```
Templates  ──────────────────────────────────────────────
  business/
    project-management          Project charters, status reports, risk registers, and meeting notes
    product-management          Product specs, roadmaps, user research, and feature backlogs
    hr-people                   Job descriptions, onboarding docs, performance reviews, and org charts
    marketing                   Campaign briefs, brand guidelines, content calendars, and competitive intel
  finance/
    investment                  Deal memos, financial models, due diligence, and portfolio company pages
    mortgage                    Loan products, pipeline reports, underwriting guidelines, and compliance
    banking                     Product catalogs, credit applications, compliance docs, and internal guides
    accounting                  Journal entries, reconciliations, period-close checklists, and policies
  technology/
    software-dev                ADRs, runbooks, feature specs, and engineering onboarding
    devops                      Incident post-mortems, change requests, runbooks, and deployment checklists
    ai-ml                       Experiment logs, model cards, dataset catalogs, and evaluation frameworks
    data-engineering            Pipeline docs, dataset registries, data quality rules, and SLAs
  ...
  Install:  synthadoc install <name> --target <dir> --template <category/domain>
  Example:  synthadoc install my-wiki --target ~/wikis --template finance/investment
```

### Install a template wiki

```bash
synthadoc install my-wiki --target ~/wikis --template technology/software-dev
synthadoc serve my-wiki
```

The install applies the template delta on top of a standard blank wiki:

1. **Agent skill files** — `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` regenerated with domain-specific guidelines
2. **`ROUTING.md`** — query routing table pre-built for the domain's knowledge branches
3. **`wiki/purpose.md` and `wiki/index.md`** — domain-appropriate purpose statement and index structure
4. **Stub pages** — 8–12 pre-named pages covering core knowledge areas (e.g. for `software-dev`: architecture, api-design, deployment, incident-response)
5. **Intake forms** — blank `template-*.md` files in each `raw_sources/<type>/` subfolder — copy, fill in, and ingest
6. **Staging enabled** — `staging_policy = "all"` so every ingest lands in `candidates/` for review before promotion
7. **Scheduled maintenance** — weekly lint (Sunday 2:00 AM) and weekly scaffold (Sunday 3:00 AM) pre-registered

### Follow the seeds

After install, open `seeds.md` in your wiki root. It lists curated starting sources
for your domain — reference docs, public datasets, official guidelines. Pick a few
that match your use case and ingest them:

```bash
synthadoc ingest "https://docs.github.com/en/actions" -w my-wiki
```

All new pages land in `candidates/` for your review.

### Use the intake forms

Each `raw_sources/<type>/template-*.md` file is a blank form for that source type.
To add a new source:

1. Copy the form and rename it (drop `template-` prefix): `cp raw_sources/specs/template-spec.md raw_sources/specs/auth-service-spec.md`
2. Fill in the form fields
3. Ingest: `synthadoc ingest raw_sources/specs/auth-service-spec.md -w my-wiki`

Template files (the `template-` prefix) are automatically excluded from `--batch`
ingestion — only your filled-in copies are processed.

### Keep your template up to date

After upgrading synthadoc, refresh the template-managed files:

```bash
# Update seeds, routing, agent files, and intake forms — never touches your ingested pages
synthadoc templates sync

# Also refresh stub pages that have never been ingested (sources: [])
synthadoc templates sync --force

# Sync a specific wiki by name
synthadoc templates sync my-wiki
```

> **Deprecation notice:** `synthadoc demo sync` is deprecated. Use
> `synthadoc templates sync` — it handles both demo wikis and template-based
> wikis with the same syntax and flags.

### Template reference

See [`synthadoc/templates/README.md`](../synthadoc/templates/README.md) for
the complete listing of all 30 templates with install commands, the full
directory structure each template ships, and instructions for authoring your own.

---

## Appendix L — Cross-Wiki Queries

Cross-wiki queries let you ask a single question across multiple Synthadoc wikis and receive one unified, synthesised answer. The system automatically routes the question to the most relevant wikis and merges results.

### When to use cross-wiki queries

Use cross-wiki mode when the answer you need lives across more than one knowledge domain, and manually searching each wiki would be slow or error-prone. Common scenarios:

- **Cross-domain analysis** — "How do our banking risk controls interact with our investment portfolio limits?" draws from both a banking-regulations wiki and an investment-policy wiki in one query.
- **Aggregate reporting** — "Summarise Q3 compliance findings across all business units" fans out to each business-unit wiki and returns a merged summary.
- **Incident response** — "What are the runbook steps and the relevant SLA commitments for a database outage?" pulls from an ops wiki and a contracts wiki simultaneously.
- **Policy synthesis** — "What HR policies apply to a contractor who also holds a client-facing role?" merges results from an HR-policy wiki and a client-engagement wiki.
- **Onboarding queries** — "Give me an overview of our tech stack, team structure, and coding standards" covers engineering, people, and handbook wikis in a single answer.

Each answer includes `[[wiki-name::PageTitle]]` citations so you can trace every claim back to its source wiki.

### Prerequisites

You need at least two wikis installed. Each wiki is automatically registered in the global registry when you run `synthadoc install`. Use `--template` to apply a domain-specific starter (pre-built seeds, routing, and guidelines):

```bash
synthadoc install finance-wiki --target ~/wikis --template finance/investment
synthadoc install legal-wiki   --target ~/wikis --template legal/compliance
```

`--target` is the parent directory; each wiki is created as `<target>/<name>/`. Run `synthadoc templates list` to see all available templates.

### Step 1 — Start servers

Start all registered wikis at once, or only the ones relevant to your query — cross-wiki queries fan out only to running wikis, so starting a subset is a valid way to scope the results:

```bash
# Start all registered wikis
synthadoc serve --all --background

# Or start only the wikis you need (e.g. 2 of 5 registered)
synthadoc serve -w finance-wiki --background
synthadoc serve -w legal-wiki --background
```

Each server starts on its registered port. `--all` skips any wiki whose port is already responding.

### Step 2 — Check status

```bash
synthadoc status --all
```

Output:

```
wiki           port   status    pages
finance-wiki   7070   running   142
legal-wiki     7071   running   38
ops-wiki       7072   stopped   —
```

Any wiki showing `stopped` cannot participate in cross-wiki queries. Start it with `synthadoc serve -w ops-wiki --background` to make it available. Whether it is actually queried then depends on your routing configuration — if `CROSS_WIKI_ROUTING.md` is in place it must appear in a matching rule; otherwise the LLM selects relevant wikis automatically based on each wiki's `purpose.md` summary.

### Step 3 — Run your first cross-wiki query

```bash
synthadoc query --cross-wiki "What are our M&A covenants and deployment runbooks?" -w finance-wiki
```

The `-w` flag identifies the coordinator wiki (any registered wiki will do). The `--cross-wiki` flag fans the question out across all running registered wikis.

![Cross-wiki query — fan-out across multiple wiki domains](png/cross-wiki-queries.png)

### Step 4 — Understanding citation format

Cross-wiki answers use a two-part citation format:

```
[[wiki-name::PageTitle]]
```

For example:

```
[[finance-wiki::Valuation Methods]]
[[legal-wiki::NDA Template]]
```

In the web UI (`synthadoc web`), these render as two-part pills: `[wiki-name]  Page Title`.

### Step 5 — Configuring CROSS_WIKI_ROUTING.md

By default the coordinator selects relevant wikis automatically using the LLM and each wiki's `purpose.md` summary. For predictable routing you can create an optional override file:

```bash
# Generate the file from your registry, then open for editing
synthadoc cross-wiki routing init

# Print current contents
synthadoc cross-wiki routing show

# Open in $EDITOR
synthadoc cross-wiki routing edit
```

The file lives at `~/.synthadoc/CROSS_WIKI_ROUTING.md`. After `routing init`, it looks like this:

```markdown
# Cross-Wiki Routing
# Generated by `synthadoc cross-wiki routing init`

## default
wikis: finance-wiki, legal-wiki, ops-wiki
keywords:
```

The `default` section (empty `keywords:`) is the fallback — it receives any query that doesn't match a keyword rule. Edit the file to add named sections that pin topic areas to specific wikis:

```markdown
# Cross-Wiki Routing

## finance
wikis: finance-wiki, banking-wiki
keywords: M&A, covenant, valuation, investment, portfolio

## legal
wikis: legal-wiki
keywords: contract, NDA, compliance, regulatory

## ops
wikis: ops-wiki
keywords: deployment, runbook, incident, SLA, outage

## default
wikis: finance-wiki, legal-wiki, ops-wiki
keywords:
```

The first section whose `keywords:` list contains a word found in the query is used; if none match, the `default` section applies. When the file is absent or cannot be parsed, the system falls back to LLM auto-routing and logs a warning.

### Step 6 — Using the Web UI

Open the chat interface for any registered wiki:

```bash
synthadoc web -w finance-wiki
```

In the chat input bar:

- **Globe toggle (🌐)** — at the right end of the input bar. Click to enable cross-wiki mode. Default: OFF. Your choice persists between sessions.
- **Context bar** — when the toggle is ON, a narrow strip above the conversation shows which wikis will be queried. After the response it shows which wikis responded and which (if any) were offline.
- **Citation pills** — cross-wiki citations render as `[wiki-name]  Page Title`.

### Step 7 — When a wiki is offline

If a target wiki is offline when the query runs, the context bar updates to show which wikis were offline:

```
🌐 Searched: finance-wiki · legal-wiki  ·  ⚠ ops-wiki offline
```

The CLI prints a similar warning to stderr. The answer is still synthesised from the available wikis.

To restore a stopped wiki:

```bash
synthadoc stop -w ops-wiki      # (if the process is stuck)
synthadoc serve -w ops-wiki --background
synthadoc status --all          # confirm it is now running
```

Then re-run your query to include it.

### Reference

For full architecture detail, API reference, and graceful degradation behaviour see [§40 Cross-Wiki Queries in the design doc](design.md#40-cross-wiki-queries-v140).