axoviq-ai/synthadoc

Synthadoc

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

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

Table of Contents

Who Is It For?

Inspiration and Vision

Problems Addressed

Why Synthadoc?

Knowledge Quality

Knowledge Structure

Search & Query

Interfaces & Integration

Content Sources

Operations & Trust

Business value

Architecture

What's Included

Installation

Production

pip install synthadoc
synthadoc --version   # confirm it works

Docker

# 1. Create the wiki on the host (one time) — note the port it prints, e.g. 7070
synthadoc install history-of-computing --target ~/wikis --demo

# 2. Put your LLM key in .env (never on the command line), e.g. GEMINI_API_KEY=...
#    and select that provider in ~/wikis/history-of-computing/.synthadoc/config.toml

# 3. Run the server in a container — same port on both sides
docker run -d --name history-of-computing \
  -v ~/wikis/history-of-computing:/wiki \
  -p 7070:7070 --env-file .env \
  chenp/synthadoc:latest

# 4. Use it — Web UI at http://localhost:7070/app, or the CLI inside the container
docker exec history-of-computing synthadoc query "Who was Alan Turing?"
docker exec history-of-computing synthadoc lint run --wait

Development

Step 1 — Clone and install

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

Step 2 — Run the test suite

pytest --ignore=tests/performance/ -q

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

Step 3 — Obsidian plugin development (optional)

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

Set your API keys

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

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

Install a wiki and start the engine

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

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

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

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

synthadoc stop -w history-of-computing

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

Quick-Start Guide

Creating Your Own Wiki

1. Pick a template and install

synthadoc templates list

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

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

2. Configure your LLM provider and start the server

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

3. Add your sources and ingest

synthadoc ingest raw_sources/ --batch          # all local files at once
synthadoc ingest "https://example.com/report"  # a web URL
synthadoc ingest "search for: Bank of Canada rate outlook 2025"  # web search
synthadoc jobs list                            # watch progress

4. Review and promote candidates

synthadoc candidates list
synthadoc candidates promote --all     # or promote individually by slug
synthadoc candidates discard <slug>

5. Query, lint, and scaffold

synthadoc query "What are the current consumer confidence trends in Canada?"
synthadoc lint run          # validates pages, promotes clean drafts to active
synthadoc lint report       # view issues and citation violations
synthadoc scaffold          # regenerates index.md with richer category links

6. Context packs and MCP

synthadoc context build "Canadian consumer confidence trends" --tokens 4000

# Replace 7070 with the port shown when you ran synthadoc serve
claude mcp add --transport sse synthadoc-my-market-wiki http://127.0.0.1:7070/mcp/sse

Configuration

Command Reference by Use Case

Setting up a wiki

# Create a new wiki (LLM scaffold runs automatically; port is auto-assigned to avoid conflicts)
synthadoc install my-wiki --target ~/wikis --domain "Machine Learning"

# Pin a specific port manually
synthadoc install my-wiki --target ~/wikis --domain "Machine Learning" --port 7071

# Install the demo (includes pre-built pages and raw sources — no LLM call needed)
synthadoc install history-of-computing --target ~/wikis --demo

# List available demo templates
synthadoc demo list

# List all 30 domain templates (and demos) — browse before installing
synthadoc templates list

# Install with a domain template — pre-configured guidelines, routing, and starter pages
synthadoc install my-finance-wiki --target ~/wikis --template finance/investment

# Sync a demo or template wiki — refresh seeds, routing, agent files, and intake forms
synthadoc templates sync history-of-computing

# Also refresh stub pages that have never been ingested (sources: [])
synthadoc templates sync history-of-computing --force

# Reinstall the Obsidian plugin into a wiki's vault — normally done automatically by synthadoc install
synthadoc plugin install history-of-computing

# Push the updated plugin binary to every registered wiki after a Synthadoc upgrade
synthadoc plugin upgrade

Switching the active wiki

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

# Check which wiki is currently active
synthadoc use

# Clear the saved default (revert to requiring -w on every command)
synthadoc use --clear

Refreshing wiki scaffold

# Regenerate scaffold for an existing wiki
synthadoc scaffold -w my-wiki

# Schedule weekly refresh (runs every Sunday at 4 AM)
synthadoc schedule add --op "scaffold" --cron "0 4 * * 0" -w my-wiki

Running the server

# Start HTTP API + job worker (foreground — terminal stays attached)
synthadoc serve -w my-wiki

# Detach to background — banner shown, then shell is released
# All logs go to <wiki>/.synthadoc/logs/synthadoc.log
synthadoc serve -w my-wiki --background

# Custom port
synthadoc serve -w my-wiki --port 7071

# Bind to all interfaces (team server, remote access, containers) — default is 127.0.0.1
synthadoc serve -w my-wiki --host 0.0.0.0

# Verbose debug logging to console
synthadoc serve -w my-wiki --verbose

# Start servers for all registered wikis in the background (cross-wiki queries)
synthadoc serve --all --background

# Stop the active wiki server
synthadoc stop

# Stop a named wiki server
synthadoc stop -w my-wiki

# Stop all running wiki servers
synthadoc stop --all

Ingesting sources

# Single file or URL
synthadoc ingest report.pdf -w my-wiki
synthadoc ingest https://example.com/article -w my-wiki

# Entire folder — enqueues each file; the worker processes jobs sequentially
synthadoc ingest --batch raw_sources/ -w my-wiki

# Manifest file — ingest a curated list of sources in one shot.
# sources.txt: one entry per line; each line is either an absolute file path
# (PDF, DOCX, PPTX, MD, …) or a URL. Blank lines and # comments are ignored.
# Each entry becomes a separate job in the queue, processed sequentially.
#
# Example sources.txt:
#   /home/user/docs/research-paper.pdf
#   /home/user/slides/keynote.pptx
#   https://en.wikipedia.org/wiki/Alan_Turing
#   # this line is ignored
synthadoc ingest --file sources.txt -w my-wiki

# Force re-ingest (bypass deduplication and cache)
synthadoc ingest --force report.pdf -w my-wiki

# Web search — triggers a Tavily search, then ingests each result URL as a child job.
# Prefix the query with any recognised intent: "search for:", "find on the web:",
# "look up:", or "web search:"  (prefix is stripped before the search is sent)
# Requires TAVILY_API_KEY to be set.
#
# Note: web search content is NOT saved to raw_sources/. The flow is direct:
#   query → Tavily → URLs → each URL fetched → wiki pages written
# raw_sources/ is for user-provided local files (PDF, DOCX, PPTX, etc.) only.
# The wiki pages themselves are the persistent output of a web search.
synthadoc ingest "search for: Bank of Canada interest rate decisions 2024" -w my-wiki
synthadoc ingest "find on the web: unemployment trends Ontario Q1 2025" -w my-wiki

# Limit how many URLs are enqueued (default 20, overrides [web_search] max_results)
synthadoc ingest "search for: quantum computing basics" --max-results 5 -w my-wiki

# Multiple web searches at once via a manifest file
# web-searches.txt:
#   search for: Bank of Canada interest rate decisions 2024
#   find on the web: unemployment trends Ontario Q1 2025
#   look up: Toronto housing market affordability index
synthadoc ingest --file web-searches.txt -w my-wiki

# YouTube video — transcript extracted automatically, no API key needed.
# The video must have captions (auto-generated or manual).
# Check: open the video on YouTube → ... → Show transcript.
synthadoc ingest "https://www.youtube.com/watch?v=O5nskjZ_GoI" -w my-wiki
synthadoc ingest "https://youtu.be/O5nskjZ_GoI" -w my-wiki

# YouTube URLs returned by web search are also routed automatically:
# if Tavily returns a YouTube URL, the transcript is ingested instead of the page HTML.
synthadoc ingest "search for: history of computing lecture" -w my-wiki

Querying

# Ask a question — answer streams token-by-token as the LLM generates it
synthadoc query "What is Moore's Law?" -w my-wiki

# Blocking mode (no streaming) — useful in scripts or pipes
synthadoc query "What is Moore's Law?" --no-stream -w my-wiki

# Skip the cache — always call the LLM even if the answer is cached
synthadoc query "What is Moore's Law?" --no-cache -w my-wiki

# Save the answer as a new wiki page
synthadoc query "What is Moore's Law?" --save -w my-wiki

Cross-wiki queries

# Query across all running registered wikis
synthadoc query --cross-wiki "What are our M&A covenants and deployment runbooks?" -w my-wiki

# Check which wikis are running
synthadoc status --all

# Manage the optional CROSS_WIKI_ROUTING.md override
synthadoc cross-wiki routing init    # generate from registry, then edit
synthadoc cross-wiki routing show    # print current contents
synthadoc cross-wiki routing edit    # open in $EDITOR

Web Chat UI

# Open the browser-based chat interface for a wiki
synthadoc web -w my-wiki

Linting

# Run a full lint pass (enqueues job)
synthadoc lint run -w my-wiki

# Only contradictions
synthadoc lint run --scope contradictions -w my-wiki

# Auto-apply high-confidence resolutions
synthadoc lint run --auto-resolve -w my-wiki

# Skip adversarial review (structural checks only; also clears existing warnings)
synthadoc lint run --no-adversarial -w my-wiki

# Skip lifecycle checks (structural and adversarial checks only)
synthadoc lint run --no-lifecycle -w my-wiki

# Block until lint finishes, printing phase progress (scripts, CI, docker exec)
# Exits with code 1 if the server stays unreachable
synthadoc lint run --wait -w my-wiki

# Instant report (reads wiki files directly, no server needed)
synthadoc lint report -w my-wiki

Agentic workflows

# List all available workflows (with descriptions and accepted parameters)
synthadoc workflow list

# Run a workflow by name
synthadoc workflow run --name lint-report -w my-wiki
synthadoc workflow run --name broken-wikilinks -w my-wiki
synthadoc workflow run --name scaffold -w my-wiki
synthadoc workflow run --name ingest-lint -w my-wiki

# Contradiction resolver — resolve all contradicted pages
synthadoc workflow run --name contradiction-resolver -w my-wiki

# Resolve only one page by slug
synthadoc workflow run --name contradiction-resolver --slug alan-turing -w my-wiki

# Scope to pages demoted by the adversarial gate
synthadoc workflow run --name contradiction-resolver --type adversarial -w my-wiki

# Scope to pages with source-level contradictions
synthadoc workflow run --name contradiction-resolver --type source-conflict -w my-wiki

# Custom timeout (default 3600 s)
synthadoc workflow run --name contradiction-resolver --timeout 7200 -w my-wiki

# Orphan resolver — find pages with no incoming wikilinks and insert natural links
synthadoc workflow run --name orphan-resolver -w my-wiki

# Resolve only one orphaned page by slug
synthadoc workflow run --name orphan-resolver --slug ada-lovelace -w my-wiki

# Broken citation resolver — fix broken ^[file:L-L] source markers (broken_ref / malformed / out_of_range)
synthadoc workflow run --name broken-citation-resolver -w my-wiki

# Fix citations on a single page only
synthadoc workflow run --name broken-citation-resolver --slug my-page -w my-wiki

# Content health resolver — fix duplicate sections, thin/empty sections, broken markdown structure
synthadoc workflow run --name content-health -w my-wiki

# Fix content issues on a single page only
synthadoc workflow run --name content-health --slug alan-turing -w my-wiki

# List every content health fix (timestamp + pre-fix snapshot)
synthadoc workflow run --name content-health list -w my-wiki

# Undo one content health fix — restores the page's pre-fix snapshot
synthadoc workflow run --name content-health roll back alan-turing -w my-wiki

Sensitive data retraction

# Dry-run — show pattern matches without making changes
synthadoc retract scan -w my-wiki

# Dry-run for a single page
synthadoc retract scan --slug ada-lovelace -w my-wiki

# Only scan pages modified since the last scan cycle (incremental)
synthadoc retract scan --changed-only -w my-wiki

# Apply redactions across all pages (prompts for confirmation)
synthadoc retract scan --apply -w my-wiki

# Apply only to recently-modified pages, auto-confirm
synthadoc retract scan --apply --changed-only --yes -w my-wiki

# Apply without confirmation prompt
synthadoc retract scan --apply --yes -w my-wiki

# Show recent scan history from the audit log
synthadoc retract status -w my-wiki
synthadoc retract status --json -w my-wiki

Managing page lifecycle

# Show page counts by lifecycle state
synthadoc status -w my-wiki

# Show running/stopped table for all registered wikis (for cross-wiki setup)
synthadoc status --all

# Promote a draft page to active after manual review
synthadoc lifecycle activate <slug> -w my-wiki --reason "reviewed and verified"

# Archive a page whose source has been superseded
synthadoc lifecycle archive <slug> -w my-wiki --reason "replaced by updated source"
# After archiving, any [[slug]] references in other pages are cleaned up automatically.
# The output reports which pages were updated:
#   Cascade: [[old-page]] removed from 2 page(s): cpu-design, transistor-history

# Restore an archived page back to draft for re-review
synthadoc lifecycle restore <slug> -w my-wiki --reason "source re-added"

# View full state history for a page (or all pages)
synthadoc lifecycle log <slug> -w my-wiki
synthadoc lifecycle log -w my-wiki

# Browse content snapshots captured at each lifecycle transition
synthadoc lifecycle history <slug> -w my-wiki
synthadoc lifecycle history <slug> --index 1 -w my-wiki            # inspect newest snapshot
synthadoc lifecycle history <slug> --index 2 --show-content -w my-wiki  # print full body

# Restore the page body to a prior snapshot (rollback is itself snapshotted, so it is undoable)
synthadoc lifecycle rollback <slug> --index 2 --reason "restoring original body" -w my-wiki

# Purge old lifecycle events to reclaim audit.db space
synthadoc audit lifecycle purge -w my-wiki --before 2026-01-01
synthadoc audit lifecycle purge -w my-wiki --keep-latest 100

Monitoring jobs

# List all jobs (oldest first by default)
synthadoc jobs list -w my-wiki

# Sort column — created_at (default) | status | operation
synthadoc jobs list --sort created_at -w my-wiki   # oldest first (default)
synthadoc jobs list --sort status -w my-wiki        # alphabetical by status
synthadoc jobs list --sort operation -w my-wiki     # alphabetical by operation type

# Sort direction — asc (default) | desc
synthadoc jobs list --order desc -w my-wiki                     # newest first
synthadoc jobs list --sort status --order desc -w my-wiki       # status Z→A

# Filter by status — pending | in_progress | completed | failed | skipped | dead | cancelled
synthadoc jobs list --status pending -w my-wiki
synthadoc jobs list --status failed -w my-wiki
synthadoc jobs list --status dead -w my-wiki

# Combine sort, order, and status freely
synthadoc jobs list --status failed --sort created_at --order desc -w my-wiki

# Single job detail
synthadoc jobs status <job-id> -w my-wiki

# Retry a dead job
synthadoc jobs retry <job-id> -w my-wiki

# Cancel all pending jobs at once (e.g. after a bad batch ingest)
synthadoc jobs cancel -w my-wiki        # prompts for confirmation
synthadoc jobs cancel --yes -w my-wiki  # skip confirmation

# Remove old records
synthadoc jobs purge --older-than 30 -w my-wiki

Inspecting ingest results

# Preview how a source will be analysed without writing pages
synthadoc ingest report.pdf --analyse-only -w my-wiki
# → {"entities": [...], "tags": [...], "summary": "..."}

Audit trail

# Ingest history: timestamp, source file, wiki page, tokens, cost
synthadoc audit history -w my-wiki                    # last 50 records (shows total)
synthadoc audit history -n 100 -w my-wiki             # last 100 records
synthadoc audit history -n 50 --offset 50 -w my-wiki  # page 2 (records 51-100)
synthadoc audit history --json -w my-wiki             # raw JSON for scripting

# Query history: question, sub-questions, tokens, cost
synthadoc audit queries -w my-wiki                    # last 50 records (shows total)
synthadoc audit queries -n 100 -w my-wiki             # last 100 records
synthadoc audit queries -n 50 --offset 50 -w my-wiki  # page 2 (records 51-100)
synthadoc audit queries --json -w my-wiki             # raw JSON for scripting

# Token usage: totals + daily breakdown
synthadoc audit cost -w my-wiki               # last 30 days
synthadoc audit cost --days 7 -w my-wiki      # last 7 days

# Audit events: contradictions found, auto-resolutions, cost gate triggers
synthadoc audit events -w my-wiki                      # last 100 events (shows total)
synthadoc audit events -n 100 --offset 100 -w my-wiki  # page 2 (events 101-200)
synthadoc audit events --json -w my-wiki               # raw JSON for scripting

# Claim citations: source-line provenance for every annotated claim
synthadoc audit citations -w my-wiki                    # all citations (last 50)
synthadoc audit citations --page alan-turing -w my-wiki # citations for one page
synthadoc audit citations --source turing.pdf -w my-wiki # citations from one source
synthadoc audit citations --broken -w my-wiki           # validation failures only
synthadoc audit citations --json -w my-wiki             # raw JSON for scripting

synthadoc audit citations --faithfulness              # all active pages
synthadoc audit citations --faithfulness --page SLUG  # single page
synthadoc audit citations --faithfulness --force      # re-run even if cache is fresh
synthadoc audit citations --faithfulness --yes        # skip cost prompt (e.g. in CI)
synthadoc audit citations --faithfulness --json       # machine-readable output
# Results cached per-page; Obsidian tab shows cached results instantly on open

Scheduling recurring jobs

# Register a nightly ingest
synthadoc schedule add --op "ingest --batch raw_sources/" --cron "0 2 * * *" -w my-wiki

# Weekly lint
synthadoc schedule add --op "lint run" --cron "0 3 * * 0" -w my-wiki

# Bulk-register all jobs declared in [[schedule.jobs]] in config.toml (alternative to schedule add)
# See docs/design.md § "schedule sub-commands" for the config.toml format
synthadoc schedule apply -w my-wiki

# List scheduled jobs (shows schedule, next run, last run, last result)
synthadoc schedule list -w my-wiki

# Remove a scheduled job
synthadoc schedule remove <id> -w my-wiki

# Run a scheduled operation immediately and record the result in the audit trail
synthadoc schedule run --op "lint run" -w my-wiki

# Show recent scheduled run history
synthadoc schedule history -w my-wiki
synthadoc schedule history --limit 50 -w my-wiki

Routing

# Bootstrap ROUTING.md from current index.md branch structure (run once)
synthadoc routing init -w my-wiki

# Report dangling slugs (pages listed in ROUTING.md that no longer exist)
synthadoc routing validate -w my-wiki

# Auto-remove dangling slugs from ROUTING.md
synthadoc routing clean -w my-wiki

Candidates staging

# Show current staging policy
synthadoc staging policy -w my-wiki

# Route all new pages to staging (review everything)
synthadoc staging policy all -w my-wiki

# Only stage pages below a confidence threshold (auto-promote high-confidence)
synthadoc staging policy threshold --min-confidence high -w my-wiki

# Turn staging off (pages go directly to wiki/)
synthadoc staging policy off -w my-wiki

# List candidate pages awaiting review
synthadoc candidates list -w my-wiki

# Promote a specific page (moves it from candidates/ to wiki/)
synthadoc candidates promote my-page-slug -w my-wiki

# Promote all candidates at once
synthadoc candidates promote --all -w my-wiki

# Discard a specific candidate
synthadoc candidates discard my-page-slug -w my-wiki

# Discard all candidates
synthadoc candidates discard --all -w my-wiki

Context packs

# Print to terminal — inspect, copy, or pipe
synthadoc context build "How did transistors change computing?" -w my-wiki

# Copy to clipboard and paste into an LLM chat (macOS)
synthadoc context build "early computing pioneers" -w my-wiki | pbcopy

# Custom token budget (default 4000)
synthadoc context build "Early programming languages" --tokens 8000 -w my-wiki

# Save next to a document you are writing
synthadoc context build "Rise of microprocessors" --output ~/drafts/computing-brief.md -w my-wiki

Exporting

# Active pages as LLM context (llms.txt spec)
synthadoc export --format llms.txt --status active -w my-wiki

# Full content dump with provenance footnotes preserved
synthadoc export --format llms-full.txt --output exports/wiki-full.txt -w my-wiki

# Export wikilink graph as GraphML — open in yEd, Gephi, or Cytoscape
synthadoc export --format graphml --output exports/wiki.graphml -w my-wiki

# Agent-ready JSON with provenance, lifecycle history, and compilation cost
synthadoc export --format json --output exports/wiki.json -w my-wiki

# OKF v0.2 bundle — consumable by any OKF-aware agent without code changes
# Write outside the wiki folder to avoid Obsidian picking up bundle files as source
synthadoc export --format okf --output ~/exports/my-wiki-okf/ -w my-wiki

Backup & Restore

# Backup to the current directory
synthadoc backup -w my-wiki

# Backup to a specific directory, excluding raw source files to reduce size
synthadoc backup -w my-wiki --output ~/backups --no-sources

# Restore to the same folder as the zip (default)
synthadoc restore synthadoc-backup-my-wiki-20260624-103000.zip

# Restore under a different name to a specific location on a specific port
synthadoc restore backup.zip --name my-wiki-staging --target ~/wikis --port 7071

Removing a wiki

# Stop the wiki server (background or foreground)
synthadoc stop -w my-wiki

# Then uninstall — two-step confirmation required, no --yes escape
synthadoc uninstall my-wiki

Administrative Reference

Health and status

# Wiki statistics: pages, queue depth, cache hit rate
synthadoc status -w my-wiki

# Liveness probe (useful in scripts and monitoring)
# Port is per-wiki — check [server] port in <wiki-root>/.synthadoc/config.toml
# Default is 7070; each additional wiki uses its own port (7071, 7072, …)
curl http://127.0.0.1:7070/health

Wiki:         /home/user/wikis/my-wiki
Pages:        34
  active         34
  draft           0
  stale           0
  contradicted    0
  archived        0
Jobs pending: 0
Jobs total:   12

Logs

# Tail and pretty-print with jq
tail -f .synthadoc/logs/synthadoc.log | jq .

# Filter to errors only
tail -f .synthadoc/logs/synthadoc.log | jq 'select(.level == "ERROR")'

# Filter to a specific job
# job_id is present only on records logged in job context (ingest/lint workers)
tail -f .synthadoc/logs/synthadoc.log | jq 'select(.job_id == "abc123")'

Audit trail

synthadoc audit history -w my-wiki          # table: timestamp, source file, wiki page, tokens, cost
synthadoc audit history -n 100 -w my-wiki   # last 100 records (default 50)
synthadoc audit history --json -w my-wiki   # raw JSON for scripting

synthadoc audit cost -w my-wiki             # total tokens + daily breakdown, last 30 days
synthadoc audit cost --days 7 -w my-wiki    # weekly view
synthadoc audit cost --json -w my-wiki      # {total_tokens, total_cost_usd, daily: [...]}

synthadoc audit events -w my-wiki           # table: timestamp, job_id, event type, metadata
synthadoc audit events --json -w my-wiki    # raw JSON

synthadoc audit citations -w my-wiki                     # all claim citations (last 50)
synthadoc audit citations --page alan-turing -w my-wiki  # citations for one page
synthadoc audit citations --source turing.pdf -w my-wiki # citations from one source file
synthadoc audit citations --broken -w my-wiki            # validation failures only
synthadoc audit citations --json -w my-wiki              # raw JSON for scripting

Cache management

# Remove all cached LLM responses
# Output: "Cache cleared: N entries removed."
synthadoc cache clear -w my-wiki

OpenTelemetry integration

# ~/.synthadoc/config.toml
[observability]
exporter      = "otlp"
otlp_endpoint = "http://localhost:4317"

Debugging

# Start server with DEBUG console logging
synthadoc serve -w my-wiki --verbose

# Check for configuration problems
synthadoc status -w my-wiki     # prints pre-flight warnings

# View recent job failures
synthadoc jobs list --status failed -w my-wiki
synthadoc jobs status <job-id> -w my-wiki    # shows error message + traceback

# Force a re-ingest to rule out cache issues
synthadoc ingest --force problem.pdf -w my-wiki

Understanding Logs and the Audit Trail

Customization

Links