cite-citadel: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

cite-citadel (CLI: citadel, PyPI package: cite-citadel) is an LLM-maintained, fully-cited personal wiki in Google's Open Knowledge Format, with an MCP server so an AI can search and read it. It implements Karpathy's LLM-Wiki pattern: drop arbitrary text-bearing files into raw/, and one agentic CLI session per source folds each into a cross-linked OKF wiki under wiki/. Pure Python 3.12, KISS. Runtime deps are only mcp, pyyaml, pypdf, and rich (all pure-Python, no native weight) — there is no LLM SDK and no API key: ingest shells out to a coding-agent CLI you already have logged in (claude/copilot/agy).

Commands

Setup: uv sync (creates .venv, installs deps + the dev group + the citadel script).

Use the portable invocation everywhere — it works identically on Linux/macOS/Windows and needs no .exe (the uv run citadel … shorthand often breaks on Windows because AV quarantines uv's generated citadel.exe):

uv run python -m citadel <subcommand>

Subcommands: init [DIR] (scaffold a workspace: citadel.toml marker, .env, raw/, wiki/; idempotent), ingest [paths…] (fold raw/ into the wiki; --verbose/-v streams the agent session, --log-dir DIR writes a transcript per agent session (named after how the source was read — pdf-text/pdf-native/office-text — shortened by path segment), --quiet drops the live progress display, --jobs N/-j folds N sources in CONCURRENTLY (default 1 = serial; CITADEL_JOBS), --full-rescan distrusts the manifest's stat cache and re-hashes every tracked source, --force <paths> deliberately re-reads already-ingested sources as a reconcile — it requires explicit paths and is refused without them, --reingest <paths> goes one step further: each named tracked source is re-imported FRESH — a kind="delete" cleanup session strips its previous facts (manifest entry dropped), then the same run ingests it as a brand-new source under the current model + rules — the full re-think reconcile's keep-the-existing-treatment rule deliberately avoids (requires explicit paths like --force; the two flags and --retry refuse to combine; a failed cleanup blocks that source's fresh session), --retry re-runs everything STUCK without naming paths: every failed source still on disk plus every ingested source no wiki page cites — the zero-entry sources the run report flags as no_pages and status marks NO PAGES — as forced reconciles; it refuses paths/--force and exits 0 when nothing is stuck, --guidance TEXT hands this ONE run a free-text steer ("create one machine registry from the maintenance lists") appended to each source-reading session's prompt — within the rules, never overriding citations; max 2000 chars, CITADEL_INGEST_GUIDANCE is the env twin, the MCP wiki_ingest takes it as a per-call argument, and the steer joins the resume checkpoint identity), refresh [--limit N] [--min-age-days D] [--stale-rules] [--dry-run] [--jobs N] (the THIRD lifecycle: re-verify the least-recently-checked sources — ordered by the manifest's ingested_at stamp, oldest/stampless first — through forced reconcile sessions on an explicit per-run budget of N sources; the sustainable alternative to regenerating the wiki after a model upgrade; --stale-rules narrows the queue to the (stale) sources — the one command that clears that marker after a rules edit), curate [--dry-run] [--limit N] [--stale-rules] [--diff PATH] [--retry] [--guidance TEXT] [paths…] (the SECOND lifecycle: improve EXISTING pages — re-sort/split/re-ground/resolve contradictions/fix locators — against a recomputed findings checklist; --guidance is the curate twin of ingest's steer — it directs structure and may ground an uncited sentence but never changes a cited fact, carried in the cluster's findings file, and the paths it names (a page, a folder, a glob) are curated even when no detector flagged them), status (read-only per-source state table: ingested / failed / skipped-duplicate / ignored / oversized / pending; MCP twin wiki_status), doctor (read-only setup health check — OK/WARN/FAIL lines for workspace / rules / config-parse fallbacks / agent CLI / the configured ingest model / raw roots / wiki placement (the wiki nested inside a raw root) / child paths (the UNC-vs-drive-letter cwd) / manifest / billing / agent instructions (instruction files in/above the workspace a NON-isolated session would load, per backend — llm._INSTRUCTION_FILES) / the MCP SDK (mcp.server.mcpserver imports, version inside the mcp>=2,<3 pin; CI's mcp-floor job runs the server tests on exactly 2.0.0) / the HTTP-serve posture / wiki-git state / a best-effort PyPI update check / workspace coherence; every check runs isolated, so one that raises is its own FAIL line, never a traceback; needs no workspace, exits 1 only on a FAIL; --probe ADDS one tiny paid session per configured model — llm.probe_session, production argv + hermetic flags, claude also --tools ""/--max-budget-usd/--no-session-persistence when advertised, in a throwaway temp dir with a ≤120 s timeout, following ingest's --bare retry rule — so a credential-stripping --bare, a CLI not logged in for -p, or a rejected model id shows before the first source pays), adopt (record THIS workspace root in the manifest's meta.workspaces after a move or a writer-machine switch — no agent session, under the run lock, refuses a re-keyed key space (manifest.workspace_rekeyed) and never rewrites a corrupt manifest; the free fix for the "written by a workspace rooted at" warning, which names it, as does doctor's manifest line; CLI-only, never on a read-only mirror), serve [--http [--host H] [--port P] [--path /mcp] [--read-only]] (the MCP server — stdio by default; --http serves the SAME surface over MCP's Streamable HTTP transport for a client that is not on this machine, mandatory bearer token, loopback default, optional read-only), capture <text> [--from WHO] [--topic T] (append one attributed note from a conversation to the raw/ capture log raw/captures/YYYY-MM.md; - reads stdin; the next ingest folds it in — the conversational-capture bridge, MCP twin wiki_capture), search <query> [--tag T] [--limit N], define <term> / read <rel_path> / raw <key> [--locator L] / neighbors <rel_path> / index / sources (CLI twins of the wiki_define/wiki_read/wiki_raw/wiki_neighbors/wiki_index/wiki_sources MCP tools — full CLI↔MCP parity), tags [tag], lint [--stale-days N] (exit 3 when the report is not clean — its own code, distinct from the usage/no-workspace exit 2), check [paths…], view [--out PATH] [--no-open] [--obsidian] [--lang CODE] (--lang overrides CITADEL_WIKI_LANG for the viewer's UI chrome + <html lang>), rules list|show|eject. citadel --version prints the version and (like --help) needs no workspace.