Upgrade guide


title: "Upgrade guide" type: navigation docs_shell: true


Upgrade guide

How to upgrade between llmwiki releases. Most releases are drop-in (pip install -U llm-wiki-plus or brew upgrade llmwiki) — this page documents the exceptions: schema migrations, config changes, and behaviour flips that affect what happens on your next sync.

The canonical per-release detail is CHANGELOG.md — this guide focuses on "what might break".

Optional one-time cleanup. candidates discard now turns every [[link]] to the discarded name into plain text (or, with --redirect PAGE, into [[PAGE|text]] plus a ## Aliases entry on that page), and the synth topic vocabulary no longer offers discarded names. Candidates you discarded before this release still have links pointing into wiki/archive/, which lint reports under link_integrity. Clean them up offline — no LLM call, raw/ never written, safe to re-run:

llmwiki migrate discarded-topic-links --vault /path/to/vault --dry-run
llmwiki migrate discarded-topic-links --vault /path/to/vault
# point some names at an existing page instead of unlinking them:
llmwiki migrate discarded-topic-links --vault /path/to/vault --redirect "Old Name=ExistingPage"

The same run moves candidate stubs that a / in their name had filed into a subfolder (candidates/entities/A/B thing.md) to their flat path (candidates/entities/A-B thing.md); an existing file at the flat path is never overwritten and is reported as a conflict. Rebuild afterwards: llmwiki build --vault <vault>. discard() callers in Python now receive a DiscardResult — use .path for the archived file.

Expect suggestions on the first run if you ever used candidates merge. A merged candidate's links belong on the page it was merged into, and a survivor page only answers to the merged-away name through the ## Aliases entry that merges started recording in #139. For an older merge — or one whose survivor you later renamed or re-filed — the archived reason.txt is the last record of where those links point. The migration therefore leaves such a name linked and prints what it thinks the page is, exiting 1:

merged, left linked: 1
  - Old Name — merged into foo (587 links)
      --redirect "Old Name=code-foo"

Check each suggested page, then re-run with those --redirect lines (--redirect "Old Name=code-foo"), which points the links at the survivor and records the alias so the next run reports nothing. If a name really was noise rather than a merge, --force unlinks it like any dismissal. The rest of the run applies either way, so you can take the redirects in a second pass.

Unreleased — add / wiki_add no longer synthesize by default (#273)

Behaviour flip, no data migration. Scripts and agents that expected synth-on-add must opt in:

  • Default: llmwiki add and MCP wiki_add write raw docs and rebuild the site; they do not create wiki/sources/ pages.
  • Opt in: pass --synthesize (CLI) or synthesize: true (MCP) on the same invocation, or run llmwiki synth afterward.
  • --no-synthesize: warn+no-op for one release (synthesis is already off); remove it when convenient.
  • --no-build / no_build: still skip the site rebuild.
  • Stdin / MCP text: llmwiki add - and MCP content record source: "piped" (no tempfile provenance).

Unreleased — synth clean stop on Ctrl+C or backend usage limit (#181)

Behaviour flip, no data migration. Scripts and schedulers that read exit codes should check these:

  • New exit code 75: synth and all exit 75 when the synthesis backend (Claude CLI, Cursor Agent CLI or Ollama) reports an exhausted usage quota in its error message. The run stops starting new sources, finishes the pages in flight, harvests what landed, and leaves the rest pending (Deferred: in wiki/log.md) instead of logging one error per remaining source. Treat 75 as "retry after the reset time", not as a failure. A plain rate-limit 429 ("Too Many Requests") is still a per-source error.
  • all no longer returns 0 after Ctrl+C: an interrupted synth step now makes all exit 130 (later stages still run for the pages that landed). A second Ctrl+C while in-flight pages finish kills the Claude / Cursor CLI processes and ends the run at once; with Ollama it waits for in-flight requests up to the Ollama timeout.
  • Lint failure no longer masks earlier codes: all --lint-fail … used to return 2 even when an earlier step had failed; now the code of the earliest failing step wins — lint's 2 applies only when no earlier step failed.
  • Reinstall automation: wrappers installed by install-automation before this release always logged EXIT:0. Run llmwiki install-automation again so the log's EXIT: line and the scheduler both see the real exit code.

Unreleased — source pages filed under a stale name (#265)

Optional offline migration, recommended when synth keeps skipping sources. After upgrade:

  • Symptom: every synth run reports skipped N source(s) already claimed by a real page under another name (older releases printed one real source page already claims this source line per source), and synth --estimate / Home keep counting those sources as pending. The pages were filed under a name an earlier release derived — a generic session description shared by many sessions, or the whole raw filename after the date — while synth now derives <date>-<slug> for them.
  • Number-shaped slugs: a raw slug: that looks like a number (0123, 68657849, 12e4) now keeps its written text in the page name instead of falling back to the raw filename, which produced a doubled date (<date>-<date>T<hh-mm>-<project>-<slug>). Existing pages under that doubled name are moved by the same migration.
  • Fix: run llmwiki migrate source-page-paths --vault <vault> --dry-run, check the planned moves, collisions and ambiguous links, then run it without --dry-run. It moves each real page to its derived path (a doc's --part-NN pages move together), rewrites [[old-stem]] links and sources: entries across wiki/ (wiki/archive/ and the log are left alone), and records synth state so the next synth treats the source as done. Zero LLM, raw/ never written; a second run changes nothing.
  • Left for you: a real page already at the derived path is reported as a collision and both pages stay put; a bare [[old-stem]] that more than one page answers to follows the one candidate that links back to the referring page; with no such candidate, or several, it is reported as ambiguous and not rewritten (the report says how many of those will break). Rebuild afterwards: llmwiki build --vault <vault>.
llmwiki migrate source-page-paths --vault /path/to/vault --dry-run
llmwiki migrate source-page-paths --vault /path/to/vault

Unreleased — Findability by page title (#259)

No required migration. After upgrade:

  • Title is the findability key: llmwiki search, MCP wiki_search, and the page_findability lint rule judge findability by each page's frontmatter title, not by slug/filename or bare link text. Slug/filename stays filesystem and [[wikilink]] resolution metainfo (link_integrity still covers broken links).
  • R2 removed: page_findability no longer searches for raw wikilink anchor strings (e.g. hub pages that list many [[session-slug]] sources no longer fail findability solely because the slug string is not a search hit). Title-not-found / ranked-past-cap errors are unchanged.
  • Prefer [[slug|Title]]: visible link text should show the page title while the slug keeps resolution stable. Bare [[slug]] links that resolve correctly are not findability failures.
  • Optional cosmetic migrate: when you want display text to match titles across existing wiki pages, run offline llmwiki migrate wikilink-titles --vault <vault> [--dry-run] — reads titles already on disk under wiki/, rewrites resolving bare [[slug]] to [[slug|Title]], zero LLM, raw/ never written. Not required for lint green. Fenced/example [[slug]] tokens are rewritten the same as prose — skim --dry-run changed pages before apply. Rebuild after apply if you want HTML to show the new display text: llmwiki build --vault <vault>.
  • Re-run after #262: if an earlier wikilink-titles pass left case/punctuation variants bare (e.g. [[LLM-Wiki]] while the page is llm-wiki), run the migrate again — those uniquely fold to a page under shared norm_page_key (same fold as link_integrity / harvest) and rewrite to [[canonical-slug|Title]]. True aliases and ambiguous collisions stay skipped.
llmwiki migrate wikilink-titles --vault /path/to/vault --dry-run
llmwiki migrate wikilink-titles --vault /path/to/vault

Unreleased — private vaults keep real home paths (#253)

Behaviour flip, no required migration. sync (and llmwiki add source: paths) no longer rewrite the home-path username to USER by default: new key redaction.redact_username defaults to false. API key, token, and email redaction is unchanged and still always runs.

  • Mixed vault after upgrade: files synced before the upgrade keep /Users/USER/… / -Users-USER-…; new files carry real paths. The site restores cwd either way.
  • Restore real paths in old files: llmwiki migrate raw-unredaction --vault PATH --dry-run, then without --dry-run, then llmwiki build --vault PATH. It touches only home-path and dash-encoded positions, never a bare USER word, and is idempotent.
  • Warning — repositories that commit raw/: a vault synced by the composite Action (action.yml) or the reusable workflow (.github/workflows/llmwiki-action.yml) runs llmwiki sync inside the repository checkout, so real home paths land in committed files. Such repositories must set "redact_username": true under redaction in config.json. This matters most on self-hosted runners, whose home directory belongs to a real account.
  • You share raw/ or publish the site: set "redact_username": true under redaction in config.json before the next sync, and run llmwiki migrate raw-redaction --vault PATH for files synced after the upgrade.

Unreleased — Session description: assigned names + scored fallback (#249)

No migration. After upgrade, optional refresh of existing raw sessions:

  • Assigned names win: when an adapter exposes a session title, that becomes description: (redacted). Claude Code: customTitle then aiTitle. Cursor CLI: store meta name, except the placeholder New Agent (treated as absent). Other adapters: none yet — ChatGPT already sets a conversation title on its own convert path.
  • Scored fallback: without an assigned name, convert ranks real user prompts (type bands → position → length 0..120) and picks the top. Punctuation-only turns are out. Cursor XML chrome is normalized off the description path so scores are not dominated by <user_info> wrappers.
  • Refresh: llmwiki sync --force then llmwiki build rewrites raw/sessions/ and the site. No wiki synth required — description: is convert-time frontmatter only.
Adapter Assigned-name source
claude_code customTitle + aiTitle
cursor_cli store meta name (not New Agent)
others none yet (ChatGPT uses conversation title on its own path)

Unreleased — Claude control tags + session TOC (#229)

No migration. After upgrade:

  • Re-convert Claude sessions if tags leaked into raw/: llmwiki sync --force then llmwiki build. Convert now strips Claude Code local-command / slash-command envelopes (local-command-caveat, command-name, …) and background-task [SYSTEM NOTIFICATION …] / <task-notification> blocks so they never become description: or Conversation prose. Non-empty <command-args> are kept on the slash label (/implement-feature https://…); injected command/skill markdown dumps are skipped for description:; user-prompt newlines become markdown hard breaks. Already-written raw/sessions/*.md keep the old text until force-synced. (Under #249, description: may still select a scored slash turn when it outranks prose.)
  • Session TOC: rebuild alone is enough for layout — the “On this page” nav is sticky in a Raw-style left column below the hero (not fixed over the title band), appears when the article has ≥2 headings, and uses the same max-width: 860px collapse as Raw.

2.3.0 — Home Pipeline state stamps + Automation panel shrink (#234)

No migration. After upgrade + rebuild:

  • Pipeline state on Home: Eligible sources + Knowledge tables stay clean; Timeline holds Last sync / Last synth / Last build / Last lint. A lint-error note appears under the Candidates table when the last lint recorded an error.
  • Automation is settings-only (shorter): no stage timestamps, no lint-fail reminder, no installer Updated line; short Synth backend line (spend hint); Agent hooks and Watch on separate lines. Maintain wording: site refreshes once after summarization.
  • Standalone llmwiki lint updates llmwiki-state.json and copies site/llmwiki-state.js — it does not rewrite HTML. --lint-fail on all does not undo the site built earlier in that run.
  • --fail-fast still stops the full pipeline at the first failure; without it, later stages (including build) continue after an earlier failure.

2.3.0 — Cursor Agent CLI synthesis backend (#230)

synthesis.backend accepts "cursor_cli": shells out to Cursor Agent CLI (agent / cursor-agent on $PATH) the same way claude uses claude -p. Defaults: model composer-2.5, timeout 180s. Settings live under nested synthesis.cursor_cli (and nested synthesis.claude / synthesis.ollama); flat claude_* keys still work as fallbacks.

  • One-run override: llmwiki synth --backend cursor_cli (also honoured by --check / --estimate) — does not write config.json.
  • Not session ingest: this is the synthesis generator. The contrib adapters cursor_cli (Agent CLI chats) and cursor_ide (IDE Composer) only convert transcripts into raw/.
  • Cost estimates: --estimate prices Cursor models from the packaged model_pricing.csv (Cursor-published Composer / Grok rates + agent --model aliases). No live Agent CLI price fetch. Stand-in rows (if any) are labeled in source / notes.
  • Overview: build --synthesize follows the active backend; dummy / unavailable skips the overview LLM.
  • install-automation: interactive backend prompt and --synth-backend accept cursor_cli.

2.2.0 — install from PyPI as llm-wiki-plus (#210)

The published distribution is llm-wiki-plus (llmwiki and llm-wiki are unavailable on PyPI). The import and CLI stay llmwiki.

pip install -U llm-wiki-plus
llmwiki --version   # → 2.2.0

Optional graph extra: pip install 'llm-wiki-plus[graph]'. Re-run llmwiki install-agent-kit --dest PATH after upgrade so retired slash commands (/wiki-export-marp, /wiki-synthesize) are pruned from an older kit install (#214). Prefer /wiki-synth (add sources-only when you want the old synthesize path).

2.1.0 — CLI help as a lifecycle map (#112)

llmwiki --help is grouped into six lifecycle sections. Command renames that affect scripts and muscle memory:

Old name Replacement
synthesize synth (old default was sources-only; today's synth does sources + harvest unless you pass --sources-only)
consolidate-topics gone — synth prepares known names at the start of each sources pass
migrate-state migrate state
migrate-raw-redaction migrate raw-redaction
migrate-tools-used migrate tools-used
migrate-page-kinds migrate page-kinds
migrate-topic-kinds migrate topic-kinds
migrate-broken-provenance migrate broken-provenance

List migrations with llmwiki migrate or llmwiki migrate --list. Nothing runs until you pick a name. Prefer --dry-run first. The /wiki-synthesize slash alias is retired — /wiki-synth is the command, and synth --sources-only is the flag for the sources-only pass.

2.1.0 — durable sync lookback (#192)

Optional shared filters.since and per-adapter adapters.<name>.since (YYYY-MM-DD, or "all" to skip the date gate for one source). Unset still means unlimited history.

  • Set a lookback before enabling a long-retention store so the first bare sync does not convert years of history. CLI --since still overrides for one run.
  • llmwiki configure-sources asks shared start date first (Enter = today−30, or keep a stored date), then per source shows Sessions · Earliest · In last 30 days before Enable / path / start date. Enable means the source is on the next bare sync (Cursor IDE included). Skipped interviews invent no dates.
  • The next successful sync with a durable lookback prunes that coding-agent adapter’s sync.files stamps older than the window (CLI --since does not GC; notes intake is not GC’d). Lookback-only skips are never remembered as done, so widening the date later can pick them up. GC does not delete raw/ or queue/synth/quarantine/ops.
  • Cursor IDE registry name is cursor_ide (was cursor) so it is distinct from cursor_cli. --adapter cursor and a legacy adapters.cursor config block still work. Prefer adapters.cursor_ide in new configs. Existing sync.files keys prefixed cursor:: are rewritten to cursor_ide:: on the next state load so Composer threads are not re-converted.
  • llmwiki adapters enabled column is yes/no (will the next bare sync include this source). The old active column and auto / explicit / off labels are gone. Keys and inheritance: configuration-reference.md — Sync lookback.

2.1.0 — MCP tool consolidation (#196)

The stdio MCP server registers six tools: wiki_search, wiki_read_page, wiki_health, wiki_sync, wiki_export, wiki_add. There are no alias stubs for retired names.

Retired Replacement
wiki_query wiki_search with question or mode=extract
wiki_list_sources wiki_search with list_sources=true
wiki_confidence / wiki_lifecycle / wiki_category_browse wiki_search with mode=filter and the matching filter_by
wiki_lint wiki_health (same lint JSON keys; adds totals)
wiki_dashboard wiki_health (totals field)

Full parameter tables: mcp.md. Historical telemetry rows keep the logged tool name; llmwiki usage and Analytics fold retired names into the canonical six-tool surface.

2.0.0 — static site, pipeline, and MCP (from v1.5.0)

Read this first

  1. Re-run llmwiki install-automation if you schedule llmwiki all — bare all now includes sync and synth. With a real synthesis backend, add --no-synth (or --no-sync --no-synth) to keep the old behaviour (#156).
  2. Run llmwiki configure-sources after upgrade if you use Cursor Agent CLI, OpenClaw, Codex, or other non-Claude stores (#182).
  3. Stop using llmwiki serve — open <vault>/site/index.html. Candidate decisions on /candidates.html execute via llmwiki candidates apply --vault <vault> --actions - (#109).
  4. Update MCP clients — replace wiki_entity_search with wiki_search; parse wiki_lint as llmwiki lint --json (#102, #150).
  5. Run migrations when applicable: - llmwiki migrate page-kinds --vault <vault> if you have wiki/questions/ or wiki/comparisons/ - llmwiki migrate topic-kinds --vault <vault> for #147 catch-up on older source pages (#174) - llmwiki migrate broken-provenance --vault <vault> after Cursor CLI re-sync left broken source_file hops (#180)
  6. Re-sync Cursor Agent CLI (llmwiki sync --force or targeted re-convert) so is_headless, sessionId, and timestamps are correct (#180).
  7. Rebuild the site — llmwiki build --vault <vault> refreshes vendored assets, topic pages, pipeline widgets, and provenance links.

Breaking changes

  • llmwiki serve / POST /api/candidates / /wiki-serve gone — static files + CLI review (#109).
  • llmwiki all default pipeline is sync → synth → build → graph → lint (#156).
  • Lint default on all is --lint-fail never (report only) (#156).
  • MCP wiki_lint JSON shape matches CLI (BREAKING); filter issues by rule; old keys orphans / broken_links are gone (#150).
  • wiki_entity_search removed — wiki_search(term, kind=…, format=…) (#102).
  • llmwiki consolidate-topics is gone (#147 / #112) — known-names prepare is part of synth.
  • synth --allow-unclassified removed (#102).
  • type: question / type: comparison invalid — migrate page-kinds (#109).
  • entity_consistency lint rule removed; unknown --rules names fail (#102).

Session sources and adapters

  • Bare llmwiki sync loads every enabled ingest-ready adapter whose store exists; enabled: false is honoured (#182).
  • Obsidian and ChatGPT export stay opt-in (adapters.*.enabled: true).
  • filters.exclude_headless (default on) skips automated launches for every coding-agent adapter; re-sync to classify older Cursor CLI rows (#180).
  • Cursor IDE Composer ingest works via bare llmwiki sync after configure-sources Enable (or llmwiki sync --adapter cursor_ide) (#2 / #192) — parses global state.vscdb. Set filters.since / adapters.cursor_ide.since (or pass --since) before the first large run. Alias --adapter cursor / legacy adapters.cursor still resolve. Cursor Agent CLI remains cursor_cli.

Synthesis and candidates

  • Prefer llmwiki synth — synthesize is removed (#112); use --sources-only when you want the old sources-only default (#90).
  • Next synth rewrites source pages lacking parseable topic bullets once (#147); optional migrate topic-kinds for cheap catch-up (#174). Vocabulary now carries known kind into each source pass (#257); pages that only lack kinds still use migrate topic-kinds, not a full re-synth.
  • Promote needs no LLM — empty Key Facts copy from source fact: bullets; rewrite-key-facts still needs a backend (#147, #103).
  • wiki/archive/ is cold storage — discarded candidates stay resolved in harvest; first lint after upgrade may report more broken links (#140).
  • synth --estimate Already synthesized follows synth state, not pages-on-disk alone (#163).
  • Ctrl+C during synth exits 130 after recording pages that reached disk (#145).

Site and review

  • Open site/index.html (or file://) — highlight.js and vis-network are vendored (#109, #127).
  • llmwiki build --local-root PATH for portable published paths (#109).
  • candidates apply rebuilds site/ unless --no-rebuild (#109).
  • llmwiki export / llmwiki reindex CLI removed — use build; catalog reconciles on sync / synth / candidate actions (#82).

Lint and MCP

  • <vault>/llmwiki.json — lint.disabled_rules to opt out of named checks (#150).
  • llmwiki lint --min-refs N and llmwiki all --min-refs N share harvest threshold (default 3) (#150).
  • llmwiki lint --fail-on-warnings for warning-severity gate (#150).
  • llmwiki lint --include-llm removed — drop the flag from scripts (#72).
  • provenance_integrity may report new errors on broken sources: / source_file: chains (#122).

Automation

  • install-automation plain-language wizard, cron --schedule, --job {ingest,maintain} (#156).
  • --with-sync / --with-synth still parse but are inert — use --no-sync / --no-synth to opt out (#156).
  • --profile {A,B,C} deprecated — A→ingest, B/C→maintain; --hour/--minute superseded by --schedule.
  • llmwiki install-agent-kit --dest PATH replaces manual .claude/commands copy and .claude-plugin/ (#109).

No action needed

  • /vs/ removed — never wired into normal builds (#138).
  • Honest Home pipeline counts — eligible sources and On disk column (#81).
  • Estimate Candidates labelled pre-run state, not a harvest forecast (#113).
  • entity_type on existing pages — inert metadata; optional re-stamp wiki/projects/ to type: project (#102).

v1.5.0 — Analytics layout + CallMcpTool migration

After upgrading the engine, rebuild the vault site so Analytics picks up the new section order and heatmaps:

llmwiki build --vault /path/to/vault
# or, when vault.default_path is already configured:
llmwiki build

build also one-shot backfills synth.pipeline in llmwiki-state.json / llmwiki-state.js when that key is missing (state last written by v1.4.0). That fills the Home State widget without a separate synth --estimate. The refresh is local-only (no API / no tokens) and runs only on a shape mismatch — later builds skip it once the snapshot exists. Sync / add / estimate still refresh the snapshot when content changes.

Optional: expand CallMcpTool entries in already-synced raw/sessions/*.md when the originating agent session file still exists:

llmwiki migrate tools-used --vault /path/to/vault --dry-run
llmwiki migrate tools-used --vault /path/to/vault
llmwiki build --vault /path/to/vault

When the origin store is gone (TTL / deleted sessions), rows are skipped safely — the migrator never invents MCP tool names. Prefer this over sync --force for the same TTL reasons as other raw rewrites: agent transcripts are usually retained only ~30 days, so force re-convert often has nothing left to read.

See reference/state-persistence.md for how usage logs, rollup, daily series, and state file relate.

v1.5.0 — index cwd restore + encoded-path redaction (#56)

For AI agents maintaining a user's vault: after the user upgrades llm-wiki (pull / pip install -U / brew), fix their vault — not the llm-wiki git clone. The engine change alone does not rewrite site/ or raw/.

Required: rebuild the site

llmwiki build --vault /path/to/their/vault
# or, if vault.default_path is already set in that checkout's config.json:
llmwiki build

That regenerates site/projects/index.html and site/sessions/index.html with restored local cwds (and a Cwd column on the sessions table).

If you skip the rebuild (engine updated, old site/ left as-is):

Symptom Why
projects/index.html still mixes /Users/USER/… (or /home/USER/…) with real paths Stale HTML from before restore/autodetect fixes
Session detail shows a usable cd … && claude --resume …, but the sessions index does not Index never restored paths until #56; old build has no Cwd column
Descriptions on the sessions table still contain …/USER/… Same — restore runs at build time
Grep checks from #56 stay non-zero (grep -c '/Users/USER/' site/sessions/index.html) Expected until rebuild

Nothing in raw/ or wiki/ is harmed by skipping rebuild; only the browsable site stays wrong / inconsistent with session heroes.

Optional: deterministic raw/ redaction rewrite (no LLM)

56 also teaches convert to rewrite dash-encoded agent-store segments

(~/.claude/projects/-Users-<name>-… → -Users-USER-…). New syncs do that automatically.

Existing raw/sessions/*.md are immutable during normal sync. For a vault that stays private and local, leaving old raw/ alone is fine — site restore already shows usable local cwds after rebuild.

When the user intends to publish or share raw/ (or otherwise wants the USER placeholder complete in every path shape already on disk), run the deterministic migrator — it rewrites path strings in place, does not call the LLM, does not enqueue synthesize, and does not touch wiki/:

# preview
llmwiki migrate raw-redaction --vault /path/to/their/vault --dry-run
# or: python3 scripts/migrate_raw_encoded_username.py --vault … --dry-run

llmwiki migrate raw-redaction --vault /path/to/their/vault
llmwiki build --vault /path/to/their/vault

Do not use llmwiki sync --force / re-convert from ~/.claude/projects/ or Cursor session folders for this:

  • Agent stores usually retain transcripts only ~30 days (Claude Code retention; Cursor similar). Older sessions in raw/ often have no source file left to re-convert from — force-sync silently skips or fails those rows while still looking like “migration work”.
  • Force-sync is the wrong tool anyway: agents may follow it with synth / queue digest and burn LLM tokens rewriting wiki pages that did not need to change. The path-string rewrite above is enough.

If you skip the raw migrator (normal for private vaults):

  • Day-to-day browsing and resume: unaffected after rebuild.
  • Old raw/ rows that already contain -Users-<real-username>-… next to a redacted /Users/USER/… prefix keep that incomplete masking until migrate raw-redaction (or a future sync of still-present sources). That is a redaction-contract gap for publish/share workflows, not data escaping a private vault.

Config note

If root config.json copied the examples placeholder "redaction": { "real_username": "" }, #56 re-autodetects after overlay so restore works again. No manual config edit required unless the user wants username redaction, which needs redaction.redact_username: true (#253).

Downgrading is guarded (#29)

Pointing an older checkout at a vault a newer engine wrote used to silently reconvert everything under the old slug scheme, duplicating raw/. As of #29, sync refuses to run when the vault's llmwiki-state.json was written by a newer meta.schema_version, or is present but unreadable:

error: <vault>/llmwiki-state.json: state file was written by a newer llmwiki
(schema_version=2 > 1). Upgrade llmwiki, or pass --force-resync to reconvert
from scratch ...

The fix is to upgrade the engine to match the vault. Only pass sync --force-resync if you genuinely want a full reconvert from scratch (it implies --force and may duplicate an already-populated raw/). This guard protects the newer→older direction; the older engine that lacks it still can't see the unified file, so keep engines at or ahead of the version that last wrote the vault.

Moving an in-clone wiki into a vault (pre-v1.5.0 checkouts only)

29 shipped in v1.5.0, so a fresh install is vault-first and nothing here applies to it. If you ran a pre-release checkout that kept raw/ and wiki/ inside the git clone and you are now setting vault.default_path, move the content by hand — there is no migration command, and two trees holding the same wiki drift silently:

llmwiki init --vault /path/to/vault          # scaffold + seed the vault
cp -r raw/ wiki/ /path/to/vault/             # move your content across
llmwiki sync --vault /path/to/vault --no-auto-build   # reconcile index after copy
llmwiki lint --vault /path/to/vault --rules index_sync

Two things to do explicitly, because neither is obvious:

  • Delete the demo entries from the copied index.md. The clone's wiki/index.md catalogs the repo's demo pages (entities/Anthropic.md, concepts/CachePricing.md, projects/demo-*.md). Copied into a vault that has none of them, every one becomes a dead index link. llmwiki sync --no-auto-build reconciles the catalog for you — that is the reason to run it right after the copy.
  • Remove the leftover ignored pages from the clone. raw/ and wiki/ are gitignored, so anything left behind is invisible to git status but still real on disk. A command run without a vault (or from a script with a different config) writes there, and you end up with pages that exist in only one of the two trees.

v1.4.0 — unified queue + vault state (hard cutover)

Requires Python ≥ 3.12.

One-time migration required if your vault still has legacy dotfiles:

python3 scripts/migrate_state_v1_4_0.py --state-file /path/to/vault/llmwiki-state.json
# or:
llmwiki migrate state --state-file /path/to/vault/llmwiki-state.json
# optional cleanup after verifying:
# rm -rf /path/to/vault/.llmwiki-state.json ...

What changed

Before After
.llmwiki-state.json, .llmwiki-synth-state.json, .llmwiki-queue.json, .llmwiki-pending-prompts/ <vault>/llmwiki-state.json (+ llmwiki-state.js sidecar)
LLMWIKI_ROOT env var vault.default_path in config.json
SessionStart auto-sync hook Manual llmwiki queue run
synthesis.backend: agent_delegate Removed — use dummy, ollama, or claude
external wiki_tasks queue ownership llmwiki queue enqueue into vault state
Python 3.9–3.11 Python ≥ 3.12
llmwiki add synthesized whole backlog add synthesizes only the docs it just wrote

New commands

llmwiki queue status
llmwiki queue enqueue --task-type add_doc --source https://example.com
llmwiki queue run --limit 20

Rebuild the site after upgrading so the Home page loads llmwiki-state.js from site/ (build copies the vault sidecar into the site tree).

State path isolation (v1.4.0+)

The active state file is process-scoped: llmwiki CLI entry points call configure_state_file once from --vault / --state-file / config.json vault.default_path. Library code and tests must pass an explicit state_file= override or rely on that configured path — there are no import-time vault bindings.

If llmwiki-state.json looks truncated (e.g. only a handful of synth.files keys after a test run), re-run the migration against your vault:

PYTHONPATH=/path/to/llm-wiki python3 scripts/migrate_state_v1_4_0.py \
  --state-file /path/to/vault/llmwiki-state.json

Legacy dotfiles (.llmwiki-state.json, .llmwiki-synth-state.json, …) are merged in; verify sync.files / synth.files counts before deleting them.

Re-run migrate state to repair dead synth_request items (#23)

Vaults migrated with the first v1.4.0 migrator carry queue items with task_type: "synth_request". The queue runner has no handler for that type, so llmwiki queue run marks every one of them status: error. Re-run the migration — it purges them, and enqueues a single synthesize task if (and only if) real backlog remains:

llmwiki migrate state --state-file /path/to/vault/llmwiki-state.json
llmwiki queue run --vault /path/to/vault

The migration resolves each legacy .llmwiki-pending-prompts/<uuid>.md against the pending sentinel pages left in wiki/sources/, so it is safe to rm -rf .llmwiki-pending-prompts/ afterwards — the prompts themselves are never needed again.

Check synthesis.backend before syncing (#23)

agent, agent-delegate, and agent_delegate were removed in v1.4.0. resolve_backend() reads them as a typo and silently falls back to dummy, which writes stub pages (Auto-synthesized from session) into wiki/sources/. migrate state prints a WARNING: when your config.json still names one — set synthesis.backend to claude, ollama, or dummy, then re-synthesize:

llmwiki synth --vault /path/to/vault

Stub pages left behind by the dummy backend count as unsynthesized backlog (#24): llmwiki queue status reports them under unsynth_total, llmwiki lint flags them with the stub_source_pages rule, and llmwiki synth refills them with a real backend.

v1.3.83+ — unified queue preview (superseded by v1.4.0)

Same migration as v1.4.0; use scripts/migrate_state_v1_4_0.py.

v1.3.0 — consolidated 1.2.x patch roll-up

Released: 2026-04-26.

Summary

Drop-in upgrade from any 1.2.x. v1.3.0 consolidates 38 in-tree patch versions (1.2.1 → 1.2.38) under one minor release tag — no breaking API changes, no schema migrations, no config changes.

pip install -U llm-wiki-plus  # → 1.3.0
llmwiki --version             # → 1.3.0

What's in it

The full per-fix detail is preserved under the [1.2.x] entries in CHANGELOG.md. Two themes:

  1. Opus 4.7 deep code-review backlog (#403, ~26 issues) — every correctness, perf, and observability finding got a one-issue-one-PR fix. Headliners: is_subagent strict path check (#406), derive_session_slug UUID-prefix collision (#424), tilde-fence counting in _close_open_fence (#419), wiki_query ranking length normalisation (#418), wiki_search cap (#413), per-vault synth state (#420), --force sync persisting _meta/_counters (#426), subprocess claude_path resolved via shutil.which (#421).

  2. Performance + features — DuplicateDetection lint rule rewritten with bucket+fingerprint+SequenceMatcher (1s vs minutes on 500 pages, #412), perf-budget test suite (-m slow, #429), md_to_plain_text cache (#417), auto-seeded project stubs pre-populated from session metadata (#425), 2 new lint rules (frontmatter_count_consistency, tools_consistency, #378), wiki-all slash command, _context.md folder convention (#60).

Breaking — none

Same CLI surface, same config schema, same on-disk state format. The only thing that changed is that the next plain sync after a forced re-sync will now correctly identify already-processed files as unchanged (was: re-processed every time, #426).

Schema migrations — none

State files written by 1.2.x are read verbatim by 1.3.0.

v1.2.0 — first stable on the 1.x line

Released: 2026-04-25.

Install changes

  • PyPI distribution name is llm-wiki-plus — llmwiki belongs to another author, and PyPI's name-similarity rule also rejects llm-wiki as too close to it, so the distribution carries a -plus suffix. The Python module + CLI command stay llmwiki, only the pip install line changes: ```bash pip install llm-wiki-plus # was: pip install llmwiki llmwiki --version # → 1.2.0 (CLI name unchanged) python3 -c "import llmwiki" # still works (import name unchanged)
Releases before the rename documented this distribution as `llm-notebook`; that name was never published for this fork and no longer appears in install instructions (#210).

### Removed CLI subcommands

The CLI was slimmed in #362. If you scripted any of these, replace as noted:

- `llmwiki schedule` — removed. Schedule `llmwiki sync` directly via your OS's job runner (launchd / systemd / Task Scheduler).
- `llmwiki install-skills` — removed. Manually copy `.claude/commands/wiki-*.md` into `~/.claude/commands/` for global availability.
- `llmwiki check-links` — removed. Use the GitHub Actions link-check workflow instead.
- `llmwiki watch`, `llmwiki manifest`, `llmwiki link-obsidian`, `llmwiki export-obsidian`, `llmwiki export-marp`, `llmwiki export-qmd`, `llmwiki eval` — also removed. (`llmwiki eval` was never a live CLI — structural scoring never shipped; use `llmwiki lint` for wiki quality.)

### Removed adapters

`jira_adapter`, `meeting`, `pdf` were removed in #363. If you depended on any of them, pin v1.1.0-rc8 until you migrate.

### Demo data correctness

`user_messages` / `tool_calls` counts on the 8 demo session files were 2–10× higher than the body actually contained. The values are now recomputed from body content. Two new lint rules (`#16 frontmatter_count_consistency`, `#17 tools_consistency`) prevent regression.

### `sync --force` no longer drops colliding sessions

If you ran `sync --force` against a corpus where two sources had the same canonical filename (rare but real on large corpora), one of them was silently overwritten. Fix: per-run filename tracking now disambiguates regardless of `--force`. Affected ~200 of 495 sessions on a real corpus we tested.

### New: `llmwiki all`

One-shot pipeline runner for CI:

```bash
llmwiki all                  # build → graph → lint
llmwiki all --strict         # exit 2 on any lint warning

Schema migrations

None. JSON sibling files now correctly emit int and bool types for user_messages / tool_calls / is_subagent (were strings); any downstream that string-compared is_subagent == "false" now needs is_subagent is False.

v1.1.0-rc5

Released: 2026-04-21.

New behaviour

  • Session transcripts strip project-local file refs. Anchors pointing at tasks.md, user_profile.md, settings.gradle.kts, .kiro/…, /Users/…, etc. are unwrapped into inline <span class="session-ref dead-link"> — the filename stays visible but the anchor doesn't 404. No action required.

  • README.md and CONTRIBUTING.md now compile as site pages. site/README.html and site/CONTRIBUTING.html ship alongside changelog.html. Link rewriter routes to the compiled page instead of GitHub for these two files.

  • /wiki-synthesize slash command — wraps llmwiki synth --sources-only (prefer /wiki-synth). Copy via llmwiki install-agent-kit --dest PATH. (llmwiki install-skills was removed in v1.2.0.) (retired in #214 — use /wiki-synth)

  • Dual-mode docs landing pages. docs/modes/api/ and docs/modes/agent/ exist as skeletons; the actual API / Agent backends ship with #315 / #316.

Schema migrations

None. Fully backwards-compatible with rc4 state files.

Breaking

None.

v1.1.0-rc4

Released: 2026-04-20.

New behaviour

  • Obsidian is opt-in now. Past versions fired the Obsidian adapter on every sync by default. If your workflow relied on that, add this to sessions_config.json:

```json { "obsidian": { "enabled": true } }


Context: [#326](https://github.com/AlexanderMakarov/llm-wiki/issues/326). Runs as of rc3; surfaced in `llmwiki adapters` column `will_fire`.

- **Graph clicks respect compiled-site existence.** Nodes whose corresponding page wasn't rendered to HTML show a tooltip instead of opening a 404. No action needed — if you see the tooltip on entity / concept / nav pages that's the new design.

- **Backlinks now propagate.** Run `llmwiki backlinks` once to inject managed `## Referenced by` sections into every linked-to page. Idempotent, dry-runnable, prune-able:

```bash
llmwiki backlinks --dry-run --verbose   # preview
llmwiki backlinks                       # commit writes
llmwiki backlinks --prune               # strip every block

Schema migrations

  • .llmwiki-state.json keys rewrite from absolute paths to <adapter>::<home-relative-path> on first load under rc3+. Migration is automatic and idempotent. If you moved your repo to a new machine, old state will be preserved verbatim — re-sync to reindex.

  • .llmwiki-quarantine.json is a new local file (gitignored). First appears when a convert error happens. Inspect with llmwiki quarantine list.

  • Frontmatter tags: / topics: convention is lint-enforced (rule #14 tags_topics_convention) — projects use topics:, everything else uses tags:. Run llmwiki tag convention to see violations. llmwiki tag rename <old> <new> rewrites across every page.

Breaking — none

No breaking CLI or config changes. Every test pre-upgrade keeps passing post-upgrade.

v1.1.0-rc3

See the release notes for the full rc3 gap-sweep bundle. No migration required.

v1.0.0 → v1.1.0-rc1

Config: synthesis.backend now accepts "ollama" in addition to the default "dummy". See docs/reference/prompt-caching.md for the ollama setup.

wiki/candidates/ directory is new — created automatically by ingest when it sees a brand-new entity/concept. Triage with /wiki-candidates (renamed from /wiki-review in rc3).

Older versions

Pre-v1.0 milestones shipped under internal sprint tags. Upgrade from v0.9.x to v1.0.0 in one step — no intermediate migration required. If you're on a pre-0.9 build, start fresh: llmwiki init in a new tree and re-run sync.

Keyboard shortcuts

⌘K / Ctrl+KOpen command palette
/Focus search
g hGo to home
g pGo to projects
g sGo to sessions
j / kNext / prev row (tables)
?Show this help
EscClose dialogs

Structured queries

Mix key:value filters with free text in the palette:

type:sessionOnly session pages
project:llm-wikiFilter by project name (substring)
model:claudeFilter by model name (substring)
date:>2026-03-01Sessions after a date
date:<2026-04-01Sessions before a date
tags:rustPages mentioning a tag/topic
sort:dateSort results by date (newest first)

Example: type:session project:llm-wiki date:>2026-04 sort:date