cite-citadel copilot-instructions.md

GitHub Copilot instructions — cite-citadel

Repository guidance for GitHub Copilot. Generated from CLAUDE.md — do not edit this file by hand: change CLAUDE.md and regenerate with CITADEL_WRITE_COPILOT_DOC=1 uv run pytest tests/test_packaging.py -k copilot -q. The drift guard in tests/test_packaging.py fails whenever the two disagree.

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 source, --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] [--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), 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 — STRUCTURAL only, 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 / the HTTP-serve posture / wiki-git state / a best-effort PyPI update check / workspace coherence; needs no workspace, exits 1 only on a FAIL), 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], rules list|show|eject. citadel --version prints the version and (like --help) needs no workspace.