{ "markdown": "# K-Ops\n\n

\n \"K-Ops\n

\n\n**Your research should not live in a graveyard of browser tabs.**\n\n`K-Ops` is a local, agent-operated research pipeline for turning links,\nPDFs, repositories, notes, and files into a durable Markdown knowledge vault.\nRaw evidence is preserved, sources are normalized, claims are extracted into\nmachine-readable registries, contradictions are surfaced, answers are governed by\na consequence-tier gate and filed back into the vault, and health checks make\nepistemic debt visible.\n\nThe project is intentionally file-native. You should be able to inspect every\nartifact with a text editor, review changes with Git, and open the curated\nvault directly in Obsidian.\n\n> **Release status:** `v0.3.0` is a software-packaging release candidate for\n> governance CLI tooling that has been run against the real 1,279-source `agkb`\n> vault. It is not a claim that the product thesis is validated: K-Ops has\n> served zero decision-tier answers to date, and the roadmap's M2.5 product\n> gate remains open. See [`docs/ROADMAP.md`](docs/ROADMAP.md) and\n> [`docs/RELEASE_PLAN.md`](docs/RELEASE_PLAN.md).\n\n> **Why it's built this way, how it compares to the Karpathy-style LLM wiki\n> pattern, the architecture, and — importantly — its trust model and limits:\n> see [`docs/DESIGN.md`](docs/DESIGN.md).** K-Ops is a governed research-workflow\n> substrate, not an autonomous truth oracle.\n\n---\n\n## The Loop\n\n```\nCapture -> Normalize -> Compile -> Ask -> Render\n```\n\n1. **Capture** - add URLs, PDFs, GitHub repos, notes, or local files.\n2. **Normalize** - ingest them into `data/raw/` and register them in `data/registry.json`.\n3. **Compile** - agents turn raw content into source summaries, then merge them into concept pages under `notes/`, generating OKF progressive index files.\n4. **Ask** - query the vault in natural language; Python seeds the prompt with local retrieval results and files grounded answers back into `notes/Answers/`.\n5. **Render** - convert the current knowledge base into memos, outlines, slides, or reports.\n\n## What You Get\n\n- direct single-source capture with `kops add `\n- batch source ingestion for URLs, PDFs, local files, and note files\n- GitHub repository ingestion with repository snapshot support\n- normalized source artifacts under `data/raw/` and a source registry in `data/registry.json`\n- an Obsidian-ready vault under `notes/` with auto-generated `index.md` progressive-disclosure listings\n- prompt templates and role-based skills for ingestion, compilation, healing, Q&A, rendering, and research\n- machine-readable claim and contradiction registries plus a vault scorecard\n- a Python CLI in `kops/kb.py` that orchestrates the workflow with Codex CLI, Claude Code, or Gemini CLI\n- repo-root `.obsidian/` settings so the repository can be opened directly in Obsidian\n\n### Governance and evidence layer\n\nAnswers and renders are governed, not free-form:\n\n- **consequence-tier gating** of `ask` and `render`: the output gate freezes a\n **context package**, enforces an **answer-to-claim map**, and refuses,\n qualifies, or abstains when the evidence does not clear the requested stakes\n level (`output_gate.py`, `context_package.py`, `answer_claim_map.py`,\n `tier_policy.py`)\n- **canonical evidence objects** plus an append-only, git-reviewable\n **validation-event audit ledger** (`evidence_model.py`, `evidence_store.py`,\n `validation_log.py`)\n- **automatic source-change invalidation** that cascades to dependent notes and\n claims (`invalidation.py`)\n- **source-independence lineage** for corroboration (`source_lineage.py`),\n **typed contradictions** (`typed_contradictions.py`), and **supervised\n distillation proposals** (`distillation.py`, proposal-only)\n- a versioned **evaluation harness** and a published **benchmark report** at\n `research/benchmarks/REPORT.md` (`eval_metrics.py`, `benchmark_report.py`)\n- a **pure entailment judge** (`entailment_judge.py`) that runs as an *advisory*\n audit only — it is **uncalibrated and non-gating**, is not wired into any\n compile/heal/answer gate, and must not be treated as a trust guarantee\n (calibration pending, see `research/benchmarks/CALIBRATION.md`)\n\nStill **not** shipped: MCP serving, an SDK, a viewer/UI, and\nembedding/hybrid retrieval.\n\n---\n\n## Requirements\n\n- Python 3.11+\n- `uv`\n- one supported agent CLI on your `PATH`: `codex`, `claude`, or `gemini`\n\nCommon fallback executable names (`codex-cli`, `claude-code`, `gemini-cli`) are\ndetected automatically. Override the detected command with environment\nvariables if needed:\n\n```bash\nexport KB_CODEX_CMD=\"codex\"\nexport KB_CLAUDE_CMD=\"claude\"\nexport KB_GEMINI_CMD=\"gemini\"\n```\n\n---\n\n## Setup\n\nThere are two ways to use K-Ops: **install the `kops` CLI** and run it against\nyour own vault, or **clone the repo** to develop the tooling itself.\n\n### Install `uv`\n\nIf `uv` is not already installed:\n\n```bash\nbrew install uv\n# or\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n### Option A — Install the `kops` CLI (run it against any vault)\n\nInstall the packaged CLI from PyPI once `v0.3.0` is published, then point it at\nany vault. Only the tooling is installed — your vault stays a plain folder of\nMarkdown, and no private data ever lives with the code.\n\n```bash\nuv tool install k-ops\n```\n\nBefore the first PyPI publication, or to install the development tip, use\n`uv tool install --from git+https://github.com/arnaudgelas/K-Ops kops`.\n\nRun it from inside a vault (it walks up to find `config/kb_config.yaml`), or\ntarget one explicitly with `--vault`:\n\n```bash\ncd ~/my-vault && kops compile --agent codex\nkops --vault ~/my-vault validate # from anywhere\n```\n\n`kops --help` works without a vault. Bundled assets (validation schema, prompt\ntemplates, skills) ship inside the wheel, so no source checkout is needed.\n\n### Option B — Develop the tooling (work on K-Ops itself)\n\nClone the repo and use `uv` for an editable dev environment:\n\n```bash\nuv sync # install deps + kops in editable mode\nuv run kops --help # run the CLI from the checkout\nuv run pytest # run the test suite\n```\n\nCommand examples below use the `uv run kops ...` (dev) form. With Option A\ninstalled, drop the `uv run` prefix and just use `kops ...`.\n\n---\n\n## Quick Start\n\n### 1. Add a source\n\nFor daily capture, add one URL, GitHub repository, or local file directly:\n\n```bash\nuv run kops add https://example.com/article\nuv run kops add https://github.com/owner/repo\nuv run kops add ./papers/interesting-paper.pdf\n```\n\nFor batch capture, use a newline-delimited input file (see `examples/links.txt`,\n`examples/kb-seed-sources.txt`, `examples/project-on-fire-sources.txt`). Each\nline can point to a URL, local file, or note path:\n\n```text\nhttps://example.com/article\nhttps://arxiv.org/abs/1706.03762\nhttps://github.com/owner/repo\n./examples/sample-note.md\n./papers/interesting-paper.pdf\n```\n\n### 2. Ingest a batch\n\n```bash\nuv run kops ingest --input examples/links.txt\n```\n\nThe ingest flow automatically routes:\n\n- GitHub repository URLs to the repository snapshot ingest path\n- GitHub repo page URLs such as `.../tree/main` or `.../blob/main/README.md` to the underlying repository\n- other URLs to the regular web/PDF ingest path\n- local files to direct copy/normalization\n\nBoth `add` and `ingest` create `data/raw//{original.*,normalized.md,metadata.json}`\nand update `data/registry.json`. Force a branch for GitHub repository URLs with\n`--branch main`.\n\n### 3. Compile the vault\n\n```bash\nuv run kops compile --agent codex # or: claude, gemini\n```\n\nThis writes `.tmp/compile_plan.json`, uses `templates/compile_prompt.md`, and\nupdates `notes/Sources/`, `notes/Concepts/`, `notes/Home.md`, and `notes/TODO.md`.\n\n### 4. Ask a question\n\n```bash\nuv run kops ask --agent codex --question \"What are the main claims and open questions?\"\nuv run kops ask --agent codex --question \"...\" --tier decision\n```\n\nThis seeds the Q&A prompt with local retrieval results and writes a timestamped\nanswer memo to `notes/Answers/`. The runtime rejects answer memos that leave\nrequired provenance fields such as `retrieval_path` empty.\n\n`ask` (and `render`) accept `--tier {exploratory|recommendation|decision|autonomous}`,\nthe consequence tier that governs the evidence bar. The default is `exploratory`\n(lowest stakes); higher tiers make the output gate refuse, qualify, or abstain\nwhen the supporting evidence is too weak to act at that stakes level.\n\n### 5. Heal and lint\n\n```bash\nuv run kops heal --agent claude\nuv run kops lint\n```\n\n`heal` surfaces contradictions, unsupported claims, and weak structure. `lint`\nchecks vault consistency and backlink integrity.\n\n### 6. Validate and inspect quality\n\n```bash\nuv run kops validate\nuv run kops extract-claims\nuv run kops extract-contradictions\nuv run kops scorecard\n```\n\n`validate` confirms the vault paths load. The registry commands rebuild the\nmachine-readable claim and contradiction layers, and `scorecard` summarizes\nhealth drift.\n\n### 7. Render output\n\n```bash\nuv run kops render --agent codex --format memo --prompt \"Write a 1-page executive memo\"\n```\n\nSupported formats: `memo`, `slides`, `outline`, `report`. Rendered outputs are\nwritten under `outputs/`.\n\n### 8. Install CLI runtime assets\n\n```bash\nuv run kops install-agent-assets --agent all --scope project\n```\n\nThis syncs the repo's Codex skills, Claude Code agents and commands, and Gemini\nCLI commands/context into the selected runtime locations.\n\n### 9. Use agent-native entries\n\nAfter installing runtime assets, you can run the same loop from Claude Code,\nCodex, or Gemini instead of only through `kops/kb.py`. If you are already inside\none of those tools, just say what you want:\n\n| Workflow | Just say (with Claude Code, Codex, or Gemini) | Python CLI |\n|---|---|---|\n| Ingest source | `ingest this source` | `uv run kops ingest --input examples/links.txt` |\n| Consolidate vault | `consolidate the vault` | `uv run kops compile --agent ` |\n| Ask question | `answer this question from the vault: ...` | `uv run kops ask --agent --question \"...\"` |\n| Heal vault | `heal the vault` | `uv run kops heal --agent ` |\n| Render output | `render this as a memo: ...` | `uv run kops render --agent --format memo --prompt \"...\"` |\n\nUse the Python CLI for mechanical fetching and registry updates. Use the\nagent-native entries when you are already inside Claude Code, Codex, or Gemini\nand want that runtime to perform the synthesis-heavy pass.\n\n---\n\n## Command Reference\n\n### Ingest\n\n- `add `: ingest one URL, GitHub repo URL, or local file directly\n- `add --branch `: override the branch for a GitHub repo URL\n- `ingest --input `: ingest URLs and local paths from a newline-separated input file\n- `ingest --branch `: override the branch for GitHub repository URLs\n- `ingest --fail-fast`: stop at the first ingestion error\n- HTML articles/pages receive a structural manifest regardless of byte size; source notes use a recursive argument map with claims owned by their narrowest supporting section\n- `ingest-github --repo `: capture every tracked path at the exact shallow-clone commit without reading file bodies or inferring architecture\n- `ingest-github --repo --architecture-depth `: add an explicit, persisted, budgeted architecture analysis; `trace` requires a scope or question and `audit` also requires `--question` and `--tier`\n- Repository analysis accepts repeatable `--scope`, `--scope-package`, `--scope-symbol`, and `--scope-concept` selectors plus hard `--max-*` and `--dependency-hops` limits\n- Documentation, source, and tests are the default semantic views. Build, CI, and deployment bodies remain excluded unless enabled with `--include-view`; inventory still records their paths.\n- `ingest-github --compile-agent `: compile immediately after ingesting the repository\n- `repository-analysis-status [--source-id ]`: list persisted analysis runs and their state/consumption\n- `check-repo-analysis --manifest --analysis [--tier <...>] [--span-verification ] [--check]`: lint repository coverage, claims, and evidence; high tiers fail closed on incomplete, stale, truncated, or unverified evidence\n- `refresh --agent <...>`: re-fetch/re-clone every source in `data/registry.json`, then compile the vault\n\n### Vault Work\n\n- `compile --agent <...>`: compile source summaries into durable notes (runs an inner-loop verify after the agent write — rebuilds registries and flags a regressing write; `--no-verify` to skip)\n- `compile-large --source-id `: run the bottom-up summarization orchestrator for large sources (>50 nodes)\n- `ask --agent <...> --question `: generate an answer memo from the vault; `--tier ` sets the consequence tier (default `exploratory`)\n- `heal --agent <...>`: run the healing prompt (also runs the inner-loop verify; `--no-verify` to skip)\n- `render --agent <...> --format --prompt `: generate an output artifact; `--tier <...>` sets the consequence tier (default `exploratory`)\n- `uv run python -m kops.generate_indexes`: regenerate Source Atlas, Topic Atlas, and OKF directory indexes\n\n### Maintenance\n\n- `lint`: check registry, source notes, concept links, and backlink consistency\n- `lint --strict`: fail on backlink drift\n- `lint --fix-backlinks`: append missing source backlinks into concept evidence sections where possible\n- `lint --check`: dry-run index generation in memory and fail if any auto-generated index files differ\n- `normalize-github-sources`: align GitHub-backed metadata fields (`--dry-run` to preview)\n- `migrate-repo-manifests [paths...] [--apply]`: migrate sampled manifests to v2; dry-run by default and never upgrades partial legacy coverage\n- `invalidate-repo-refresh ... [--apply] [--flag]`: reconcile two repository captures and queue stale evidence/claims; dry-run by default and never rewrites claim text\n- `backfill source-notes`: create or repair missing source-summary notes\n- `backfill source-metadata`: backfill registry and raw metadata fields\n- `backfill concept-quality`: backfill concept claim-quality metadata\n- `backfill answer-quality`: backfill answer memo quality metadata\n- `install-agent-assets`: sync skills and prompt templates into agent runtime locations\n- `extract-claims`: rebuild `data/claims.json`\n- `search --scope claims --query `: search the claim registry\n- `extract-contradictions`: rebuild `data/contradictions.json`\n- `search --scope contradictions --query `: search contradiction records\n- `verify-spans`: check each claim's `quote=` anchor actually appears in its source; writes `data/span_verification.json`; `--check` fails closed on a mismatch\n- `scorecard`: compute `data/scorecard.json`\n- `scorecard`: run the scorecard audit under an explicit audit command name\n- `review-queue`: one prioritised list of everything needing human review (failed spans, blocked/quarantined/unsupported claims, undocumented contradictions, flagged sources, unreviewed probes, gaps); `--severity`, `--format`\n- `signal-log`: record/report the deterministic quality-signal vector over time (`data/history/signals.jsonl`, gitignored) and gate on it — `--record` appends a datapoint, `--check` exits non-zero on a hard regression\n- `next-action`: the loop controller — recommend the single highest-leverage next repair and a convergence verdict (`blocking` / `cleanup` / `converged`) from the deterministic signals; `--format`, `--check` (exit non-zero on a blocking state)\n- `consequence-gate --tier `: check whether the evidence clears the bar to act at a given stakes level; `--concept`, `--check`\n- `stale-impact`: list notes flagged for revalidation\n- `clear-stale-flags`: remove `revalidation_required` flags\n- `retract --reason `: revoke a bad source, map its blast radius, flag dependents for revalidation, and re-block dependent claims; `--dry-run`, `--status`, `--format` (flags/reports only — never rewrites claims)\n- `validate`: confirm the vault config and required paths load\n- `maintenance`: run the full mechanical maintenance pass (`--agent <...>` optionally refreshes and recompiles first)\n- `bootstrap --target `: create a new blank starter knowledge base with the same scripts, templates, and note structure (`--force` to overwrite, `--with-examples` to add a tiny example input folder)\n- `sync-kops --target `: compare the canonical `kops/` package with a downstream vault; add `--apply` to synchronize it and write `.kops-upstream.json`\n- `verify-kops-sync --target `: verify a downstream `kops/` copy against its recorded upstream manifest without requiring the K-Ops checkout\n\nK-Ops is the source of truth for `kops/`. Bootstrapped vaults contain a\nself-contained downstream copy; reusable changes land and pass tests here\nfirst, then `sync-kops --apply` propagates them. Do not develop two divergent\nimplementations and reconcile them by hand.\n\n### Governance and Evaluation\n\nAnswers and renders pass through a consequence-tier output gate; these commands\ninspect the evidence bar and measure the pipeline end to end. See also the\nrelated governance commands listed under Maintenance and Graph and Export:\n`consequence-gate`, `retract`, `review-queue`, `stale-impact`,\n`clear-stale-flags`, and `check-content-drift`.\n\n- `consequence-gate --tier `: check whether the evidence clears the bar to act at a given stakes level; `--concept`, `--format `, `--check`\n- `benchmark`: run the end-to-end evaluation metrics harness over the held-out corpus; `--snapshot`/`--no-snapshot`, `--provider >`, `--entailment` (advisory judge), `--top-k`, `--corpus`, `--golden-set`, `--out-dir`\n- `benchmark-report`: render `research/benchmarks/REPORT.md` from the benchmark metrics; `--run` to re-run the harness first, `--out`, `--eval-runs-dir`, `--corpus`, `--golden-set`\n- `eval --init`: create the golden Q&A evaluation scaffold if it does not exist\n- `eval --check`: validate the golden Q&A scaffold and golden-set schema\n\n### Graph and Export\n\n- `export-vault`: write a zip archive containing `.obsidian/` and `notes/`\n- `export-index`: export a structured vault manifest (`--format csv` for CSV)\n- `check-content-drift [--flag]`: detect raw-content drift (content-hash) for any source and flag the source note + derived pages `revalidation_required`\n- `backfill content-hash [--force]`: seed (or re-baseline) the `content_hash` drift baseline on source notes\n- `build-graph`: build the vault graph and retention report\n- `community-audit`: cluster the concept graph and report communities, bridge nodes, fragile clusters, and cross-cluster knowledge gaps; writes `data/graph/community_audit.json`; `--format`, `--min-shared`\n- `search --query `: search the graph\n- `search --scope graph --start `: traverse the graph from a node\n- `retention-report`: write the retention report on its own\n\n### Research Runs\n\nThe repo supports a resumable research-run workflow in `research/` for\nhigher-stakes topics. Active run files live outside the curated vault so they can\nbe resumed without polluting concept pages.\n\n- `research-start --topic --tier `\n- `research-status [topic|all]`\n- `research-collect --agent --topic --tier <...>`\n- `research-review --agent <...> --topic --tier <...>`\n- `research-report --agent <...> --topic --tier <...>`\n- `research-import --topic --path --provider [--origin