openkos 0.2.0__tar.gz → 0.2.3__tar.gz

{openkos-0.2.0 → openkos-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openkos
-Version: 0.2.0
+Version: 0.2.3
 Summary: Local-first engine that turns your scattered text into a living, portable knowledge base in the Open Knowledge Format (OKF)
 Keywords: okf,open-knowledge-format,knowledge-base,knowledge-graph,local-first,rag,llm,second-brain,cli
 Author: Jason
@@ -33,97 +33,89 @@ Description-Content-Type: text/markdown
 
 # OpenKOS
 
+[![PyPI](https://img.shields.io/pypi/v/openkos)](https://pypi.org/project/openkos/)
+[![Python](https://img.shields.io/pypi/pyversions/openkos)](https://pypi.org/project/openkos/)
+[![CI](https://github.com/jasonssdev/openkos/actions/workflows/ci.yml/badge.svg)](https://github.com/jasonssdev/openkos/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/jasonssdev/openkos/blob/main/LICENSE)
+
 **Open Knowledge Orchestration System** — a local-first engine for the Open Knowledge Format.
 
 OpenKOS turns your scattered text into a living, portable knowledge base your AI agents can actually use — compiled once, kept current, and stored as plain [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) files so it is never locked to any app, model, or vendor.
 
-> **Project status: alpha.** OpenKOS runs: the Compiler and the Graph-and-Memory arcs (MVP 1 and MVP 2) are complete — 19 CLI verbs, hybrid retrieval, and the full forget/purge lifecycle all ship today. The API may still change between releases, but OpenKOS is published and installable now — `pip install openkos`, see [Getting started](#getting-started). Early contributors and feedback are welcome — see [Contributing](#contributing).
+> **Project status: alpha.** The Compiler and the Graph-and-Memory arcs (MVP 1 and MVP 2) are complete and shipped. The API may still change between releases, but OpenKOS is published and installable now. Early contributors and feedback are welcome — see [Contributing](#contributing).
 
 ---
 
-## The problem
-
-Your AI assistant forgets everything between sessions, so you re-explain the same context every time and the insights you build together disappear into chat history. Meanwhile your notes pile up in folders nobody keeps current. Two powerful things — your knowledge and your models — sit side by side, disconnected.
+## Quickstart
 
-Retrieval (RAG) doesn't fix this: it re-reads your raw documents on every question and rediscovers everything from scratch. Nothing accumulates. The cross-references are never drawn, the contradictions never reconciled.
+Five steps from a fresh machine to your first cited answer. Everything runs on your computer: no accounts, no API keys, nothing leaves your machine.
 
-## The idea
+**1 · Install [Ollama](https://ollama.com)** — the local AI runtime OpenKOS talks to. Download it, open it once, and it stays running in the background.
 
-Instead of retrieving from raw sources every time, an LLM can *incrementally build and maintain* a persistent, interlinked knowledge base that sits between you and your sources — Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern. Knowledge is compiled once and then kept current. It compounds.
+**2 · Pull the two default models** (one time, ~6 GB total):
 
-In June 2026 Google Cloud published a vendor-neutral specification for that pattern: the **Open Knowledge Format (OKF)** — a directory of markdown files with YAML frontmatter, portable across any tool. It is young (v0.1, still a draft) but open, minimal, and gaining adoption. Google's framing was: *"What's missing is a format, not another service,"* and they invited the community to build producers and consumers.
+```bash
+ollama pull qwen3:8b   # chat model — extraction and answers (~5 GB)
+ollama pull bge-m3     # embedding model — semantic search (~1.2 GB)
+```
 
-**OpenKOS is that producer and consumer, built for individuals and running entirely on your machine.**
+> There is a third, **optional** model for naming relations during curation (`ollama pull gemma2:27b`, **15.6 GB**). Skip it for now — if a command wants it, the error message tells you exactly what to pull.
 
-## Before / after
-
-| | Without OpenKOS | With OpenKOS |
-| --- | --- | --- |
-| Asking your AI about your own notes | It re-reads raw files every time | It answers from a compiled, cited knowledge base |
-| New source | Piles up unread | Compiled into a Source plus typed knowledge objects, each linked to its source |
-| Provenance | "Where did this come from?" is a guess | Every object links back to its immutable source |
-| Facts that change | Old claims quietly rot | Freshness stamps keep the base honest over time |
-| Portability | Trapped in one app | Plain OKF files — open in Obsidian, VS Code, GitHub, anything |
-| Privacy | Your knowledge leaves your machine | Local-first, offline-capable, local models |
-
-## What it feels like
+**3 · Install the engine** (needs Python 3.12+ and [git](https://git-scm.com)):
 
 ```bash
-# point OpenKOS at a folder of text and compile it into an OKF bundle
-openkos ingest ./sources
-
-# ask a question and get a cited answer from the compiled knowledge
-openkos query "what did I conclude about how to live well?"
-
-# check the base stays honest — stale `as of` stamps and orphan pages
-openkos lint
+uv tool install openkos   # or: pipx install openkos — or: pip install openkos
 ```
 
-*(The full command set — 19 verbs spanning ingest, cited query, the typed graph, entity resolution, volatility tiers (`suggest-volatility`/`set-volatility`), and the forget/purge lifecycle — is in [`docs/cli.md`](https://github.com/jasonssdev/openkos/blob/main/docs/cli.md).)*
-
-## Getting started
+To track the latest unreleased `main` instead: `uv tool install git+https://github.com/jasonssdev/openkos`.
 
-> Alpha: the commands below run today. OpenKOS is on **PyPI** — install the released version below, or install from the GitHub repository to track the latest `main`. The API may still change between releases.
+**4 · Check the setup before anything can fail:**
 
-OpenKOS is a local-first command-line tool. You install the engine once, then create a knowledge bundle per knowledge base — much like installing git once and running `git init` in many repositories.
+```bash
+openkos doctor
+```
 
-**Prerequisites:** Python 3.12+; [git](https://git-scm.com); [git-filter-repo](https://github.com/newren/git-filter-repo) (only needed for `purge`); and a local model runtime — [Ollama](https://ollama.com) with the chat model (`ollama pull qwen3:8b`) and the embedding model (`ollama pull bge-m3`) pulled. No accounts, no API keys: nothing leaves your machine.
+Every line should read `[PASS]` except *Workspace initialized* — you haven't created one yet. `doctor` is also the first thing to run whenever something misbehaves later.
 
-**Install the engine** (once):
+**5 · Create a knowledge base and run the loop:**
 
 ```bash
-uv tool install openkos   # or: pipx install openkos — or: pip install openkos
+mkdir ~/knowledge && cd ~/knowledge
+openkos init                          # picks your models, scaffolds the workspace
+openkos ingest ./meeting-notes.txt    # compile a source — a file, a folder, or a glob
+openkos query "what did we decide?"   # an answer with citations, from your own knowledge
 ```
 
-This installs the `openkos` command on your PATH. To try it once without a persistent install, run it ephemerally:
+From here, `openkos next` always tells you the one thing worth doing, and `openkos --help` lists every command, grouped. The full reference is [`docs/cli.md`](https://github.com/jasonssdev/openkos/blob/main/docs/cli.md); the end-to-end experience is [`docs/user-journey.md`](https://github.com/jasonssdev/openkos/blob/main/docs/user-journey.md).
 
-```bash
-uvx openkos --help
-```
+**What `init` set up for you.** `raw/` holds your immutable sources; `bundle/` is the pure-OKF knowledge base — plain markdown you can open in Obsidian, VS Code, or GitHub, and take anywhere; `openkos.yaml` is the engine config. The folder is also a git repository **you never have to operate**: every command commits its own changes, and `git log` / `git diff` / `git revert` are always there for inspection and undo.
 
-Prefer the latest unreleased `main`? Install from the repository instead — the same command with a git URL:
+---
 
-```bash
-uv tool install git+https://github.com/jasonssdev/openkos
-```
+## The problem
 
-**Create a bundle** (per knowledge base):
+Your AI assistant forgets everything between sessions, so you re-explain the same context every time and the insights you build together disappear into chat history. Meanwhile your notes pile up in folders nobody keeps current. Two powerful things — your knowledge and your models — sit side by side, disconnected.
 
-```bash
-mkdir ~/knowledge && cd ~/knowledge
-openkos init
-```
+Retrieval (RAG) doesn't fix this: it re-reads your raw documents on every question and rediscovers everything from scratch. Nothing accumulates. The cross-references are never drawn, the contradictions never reconciled.
 
-`init` scaffolds the workspace — `raw/` for your immutable sources and `bundle/` for the compiled OKF bundle (starting with just `index.md` and `log.md`; concept-type folders are never pre-created, only added as you ingest) — then writes `AGENTS.md` and, last, the `openkos.yaml` marker. It refuses without writing anything if the directory already looks like a workspace. Sources sit beside the bundle rather than inside it, so `bundle/` stays pure OKF: portable, conformant, and shareable on its own.
+## The idea
 
-**Then the loop:**
+Instead of retrieving from raw sources every time, an LLM can *incrementally build and maintain* a persistent, interlinked knowledge base that sits between you and your sources — Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern. Knowledge is compiled once and then kept current. It compounds.
 
-```bash
-openkos ingest ./meeting-notes.txt   # compile a source into the bundle
-openkos query "what did we decide?"  # get a cited answer
-```
+In June 2026 Google Cloud published a vendor-neutral specification for that pattern: the **Open Knowledge Format (OKF)** — a directory of markdown files with YAML frontmatter, portable across any tool. It is young (v0.1, still a draft) but open, minimal, and gaining adoption. Google's framing was: *"What's missing is a format, not another service,"* and they invited the community to build producers and consumers.
+
+**OpenKOS is that producer and consumer, built for individuals and running entirely on your machine.**
 
-See [`docs/cli.md`](https://github.com/jasonssdev/openkos/blob/main/docs/cli.md) for the full command reference and [`docs/user-journey.md`](https://github.com/jasonssdev/openkos/blob/main/docs/user-journey.md) for the end-to-end experience.
+## Before / after
+
+| | Without OpenKOS | With OpenKOS |
+| --- | --- | --- |
+| Asking your AI about your own notes | It re-reads raw files every time | It answers from a compiled, cited knowledge base |
+| New source | Piles up unread | Compiled into a Source plus typed knowledge objects, each linked to its source |
+| Provenance | "Where did this come from?" is a guess | Every object links back to its immutable source |
+| Facts that change | Old claims quietly rot | Freshness stamps keep the base honest over time |
+| Portability | Trapped in one app | Plain OKF files — open in Obsidian, VS Code, GitHub, anything |
+| Privacy | Your knowledge leaves your machine | Local-first, offline-capable, local models |
 
 ## Philosophy
 
@@ -148,7 +140,7 @@ The wedge, in one line: **the local-first, personal producer-consumer-runtime fo
 OpenKOS ships in three MVP arcs, each usable on its own. Full detail in [`docs/roadmap.md`](https://github.com/jasonssdev/openkos/blob/main/docs/roadmap.md).
 
 - **MVP 1 — The Compiler. (Complete.)** The Karpathy loop, locally, over text: ingest → OKF concepts with provenance → cited query → freshness lint. Useful in an afternoon.
-- **MVP 2 — The Graph and Memory. (Complete.)** Entity/relationship extraction and reversible merge, a typed knowledge graph (an OpenKOS layer over OKF's untyped links — other tools still read the bundle fine), hybrid retrieval (lexical FTS5 + local vectors + graph, fused via RRF with PageRank), a fail-closed sensitivity filter (confidential concepts never reach the LLM), reference-aware `forget` plus an irreversible `purge` (right-to-be-forgotten), and answers that file back into the base (`query --save`, the two-output rule).
+- **MVP 2 — The Graph and Memory. (Complete.)** Entity/relationship extraction and reversible merge, a typed knowledge graph (an OpenKOS layer over OKF's untyped links — other tools still read the bundle fine), hybrid retrieval (lexical and semantic, rank-fused), a fail-closed sensitivity filter (confidential concepts never leave the machine — held back from any backend that is not verifiably local), a guided curation loop, reference-aware `forget` plus an irreversible `purge` (right-to-be-forgotten), and answers that file back into the base (the two-output rule).
 - **MVP 3 — The Runtime and Interoperability.** An MCP server and APIs so agents use OpenKOS as durable memory; full OKF import/export with the wider ecosystem.
 
 Beyond that: a desktop app, graph visualization, richer memory, and federation — explored only after the MVPs prove out with real users.
@@ -165,10 +157,10 @@ Beyond that: a desktop app, graph visualization, richer memory, and federation
 - [`docs/glossary.md`](https://github.com/jasonssdev/openkos/blob/main/docs/glossary.md) — definitions of the core vocabulary
 - [`docs/faq.md`](https://github.com/jasonssdev/openkos/blob/main/docs/faq.md) — frequently asked questions
 - [`docs/user-journey.md`](https://github.com/jasonssdev/openkos/blob/main/docs/user-journey.md) — the end-to-end user experience
-- [`docs/testing.md`](https://github.com/jasonssdev/openkos/blob/main/docs/testing.md) — manual end-to-end testing walkthrough (all 19 commands)
+- [`docs/testing.md`](https://github.com/jasonssdev/openkos/blob/main/docs/testing.md) — manual end-to-end testing walkthrough
 - [`docs/cli.md`](https://github.com/jasonssdev/openkos/blob/main/docs/cli.md) — the command-line reference
 - [`docs/brand.md`](https://github.com/jasonssdev/openkos/blob/main/docs/brand.md) — visual identity: isotype, wordmark, palette, typography
-- [`docs/adr/`](https://github.com/jasonssdev/openkos/blob/main/docs/adr/) — architecture decision records (the log begins with the first code-time decision)
+- [`docs/adr/`](https://github.com/jasonssdev/openkos/blob/main/docs/adr/) — architecture decision records
 
 ## Contributing
 

{openkos-0.2.0 → openkos-0.2.3}/README.md

@@ -1,96 +1,88 @@
 # OpenKOS
 
+[![PyPI](https://img.shields.io/pypi/v/openkos)](https://pypi.org/project/openkos/)
+[![Python](https://img.shields.io/pypi/pyversions/openkos)](https://pypi.org/project/openkos/)
+[![CI](https://github.com/jasonssdev/openkos/actions/workflows/ci.yml/badge.svg)](https://github.com/jasonssdev/openkos/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/jasonssdev/openkos/blob/main/LICENSE)
+
 **Open Knowledge Orchestration System** — a local-first engine for the Open Knowledge Format.
 
 OpenKOS turns your scattered text into a living, portable knowledge base your AI agents can actually use — compiled once, kept current, and stored as plain [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) files so it is never locked to any app, model, or vendor.
 
-> **Project status: alpha.** OpenKOS runs: the Compiler and the Graph-and-Memory arcs (MVP 1 and MVP 2) are complete — 19 CLI verbs, hybrid retrieval, and the full forget/purge lifecycle all ship today. The API may still change between releases, but OpenKOS is published and installable now — `pip install openkos`, see [Getting started](#getting-started). Early contributors and feedback are welcome — see [Contributing](#contributing).
+> **Project status: alpha.** The Compiler and the Graph-and-Memory arcs (MVP 1 and MVP 2) are complete and shipped. The API may still change between releases, but OpenKOS is published and installable now. Early contributors and feedback are welcome — see [Contributing](#contributing).
 
 ---
 
-## The problem
-
-Your AI assistant forgets everything between sessions, so you re-explain the same context every time and the insights you build together disappear into chat history. Meanwhile your notes pile up in folders nobody keeps current. Two powerful things — your knowledge and your models — sit side by side, disconnected.
+## Quickstart
 
-Retrieval (RAG) doesn't fix this: it re-reads your raw documents on every question and rediscovers everything from scratch. Nothing accumulates. The cross-references are never drawn, the contradictions never reconciled.
+Five steps from a fresh machine to your first cited answer. Everything runs on your computer: no accounts, no API keys, nothing leaves your machine.
 
-## The idea
+**1 · Install [Ollama](https://ollama.com)** — the local AI runtime OpenKOS talks to. Download it, open it once, and it stays running in the background.
 
-Instead of retrieving from raw sources every time, an LLM can *incrementally build and maintain* a persistent, interlinked knowledge base that sits between you and your sources — Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern. Knowledge is compiled once and then kept current. It compounds.
+**2 · Pull the two default models** (one time, ~6 GB total):
 
-In June 2026 Google Cloud published a vendor-neutral specification for that pattern: the **Open Knowledge Format (OKF)** — a directory of markdown files with YAML frontmatter, portable across any tool. It is young (v0.1, still a draft) but open, minimal, and gaining adoption. Google's framing was: *"What's missing is a format, not another service,"* and they invited the community to build producers and consumers.
+```bash
+ollama pull qwen3:8b   # chat model — extraction and answers (~5 GB)
+ollama pull bge-m3     # embedding model — semantic search (~1.2 GB)
+```
 
-**OpenKOS is that producer and consumer, built for individuals and running entirely on your machine.**
+> There is a third, **optional** model for naming relations during curation (`ollama pull gemma2:27b`, **15.6 GB**). Skip it for now — if a command wants it, the error message tells you exactly what to pull.
 
-## Before / after
-
-| | Without OpenKOS | With OpenKOS |
-| --- | --- | --- |
-| Asking your AI about your own notes | It re-reads raw files every time | It answers from a compiled, cited knowledge base |
-| New source | Piles up unread | Compiled into a Source plus typed knowledge objects, each linked to its source |
-| Provenance | "Where did this come from?" is a guess | Every object links back to its immutable source |
-| Facts that change | Old claims quietly rot | Freshness stamps keep the base honest over time |
-| Portability | Trapped in one app | Plain OKF files — open in Obsidian, VS Code, GitHub, anything |
-| Privacy | Your knowledge leaves your machine | Local-first, offline-capable, local models |
-
-## What it feels like
+**3 · Install the engine** (needs Python 3.12+ and [git](https://git-scm.com)):
 
 ```bash
-# point OpenKOS at a folder of text and compile it into an OKF bundle
-openkos ingest ./sources
-
-# ask a question and get a cited answer from the compiled knowledge
-openkos query "what did I conclude about how to live well?"
-
-# check the base stays honest — stale `as of` stamps and orphan pages
-openkos lint
+uv tool install openkos   # or: pipx install openkos — or: pip install openkos
 ```
 
-*(The full command set — 19 verbs spanning ingest, cited query, the typed graph, entity resolution, volatility tiers (`suggest-volatility`/`set-volatility`), and the forget/purge lifecycle — is in [`docs/cli.md`](https://github.com/jasonssdev/openkos/blob/main/docs/cli.md).)*
-
-## Getting started
+To track the latest unreleased `main` instead: `uv tool install git+https://github.com/jasonssdev/openkos`.
 
-> Alpha: the commands below run today. OpenKOS is on **PyPI** — install the released version below, or install from the GitHub repository to track the latest `main`. The API may still change between releases.
+**4 · Check the setup before anything can fail:**
 
-OpenKOS is a local-first command-line tool. You install the engine once, then create a knowledge bundle per knowledge base — much like installing git once and running `git init` in many repositories.
+```bash
+openkos doctor
+```
 
-**Prerequisites:** Python 3.12+; [git](https://git-scm.com); [git-filter-repo](https://github.com/newren/git-filter-repo) (only needed for `purge`); and a local model runtime — [Ollama](https://ollama.com) with the chat model (`ollama pull qwen3:8b`) and the embedding model (`ollama pull bge-m3`) pulled. No accounts, no API keys: nothing leaves your machine.
+Every line should read `[PASS]` except *Workspace initialized* — you haven't created one yet. `doctor` is also the first thing to run whenever something misbehaves later.
 
-**Install the engine** (once):
+**5 · Create a knowledge base and run the loop:**
 
 ```bash
-uv tool install openkos   # or: pipx install openkos — or: pip install openkos
+mkdir ~/knowledge && cd ~/knowledge
+openkos init                          # picks your models, scaffolds the workspace
+openkos ingest ./meeting-notes.txt    # compile a source — a file, a folder, or a glob
+openkos query "what did we decide?"   # an answer with citations, from your own knowledge
 ```
 
-This installs the `openkos` command on your PATH. To try it once without a persistent install, run it ephemerally:
+From here, `openkos next` always tells you the one thing worth doing, and `openkos --help` lists every command, grouped. The full reference is [`docs/cli.md`](https://github.com/jasonssdev/openkos/blob/main/docs/cli.md); the end-to-end experience is [`docs/user-journey.md`](https://github.com/jasonssdev/openkos/blob/main/docs/user-journey.md).
 
-```bash
-uvx openkos --help
-```
+**What `init` set up for you.** `raw/` holds your immutable sources; `bundle/` is the pure-OKF knowledge base — plain markdown you can open in Obsidian, VS Code, or GitHub, and take anywhere; `openkos.yaml` is the engine config. The folder is also a git repository **you never have to operate**: every command commits its own changes, and `git log` / `git diff` / `git revert` are always there for inspection and undo.
 
-Prefer the latest unreleased `main`? Install from the repository instead — the same command with a git URL:
+---
 
-```bash
-uv tool install git+https://github.com/jasonssdev/openkos
-```
+## The problem
 
-**Create a bundle** (per knowledge base):
+Your AI assistant forgets everything between sessions, so you re-explain the same context every time and the insights you build together disappear into chat history. Meanwhile your notes pile up in folders nobody keeps current. Two powerful things — your knowledge and your models — sit side by side, disconnected.
 
-```bash
-mkdir ~/knowledge && cd ~/knowledge
-openkos init
-```
+Retrieval (RAG) doesn't fix this: it re-reads your raw documents on every question and rediscovers everything from scratch. Nothing accumulates. The cross-references are never drawn, the contradictions never reconciled.
 
-`init` scaffolds the workspace — `raw/` for your immutable sources and `bundle/` for the compiled OKF bundle (starting with just `index.md` and `log.md`; concept-type folders are never pre-created, only added as you ingest) — then writes `AGENTS.md` and, last, the `openkos.yaml` marker. It refuses without writing anything if the directory already looks like a workspace. Sources sit beside the bundle rather than inside it, so `bundle/` stays pure OKF: portable, conformant, and shareable on its own.
+## The idea
 
-**Then the loop:**
+Instead of retrieving from raw sources every time, an LLM can *incrementally build and maintain* a persistent, interlinked knowledge base that sits between you and your sources — Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern. Knowledge is compiled once and then kept current. It compounds.
 
-```bash
-openkos ingest ./meeting-notes.txt   # compile a source into the bundle
-openkos query "what did we decide?"  # get a cited answer
-```
+In June 2026 Google Cloud published a vendor-neutral specification for that pattern: the **Open Knowledge Format (OKF)** — a directory of markdown files with YAML frontmatter, portable across any tool. It is young (v0.1, still a draft) but open, minimal, and gaining adoption. Google's framing was: *"What's missing is a format, not another service,"* and they invited the community to build producers and consumers.
+
+**OpenKOS is that producer and consumer, built for individuals and running entirely on your machine.**
 
-See [`docs/cli.md`](https://github.com/jasonssdev/openkos/blob/main/docs/cli.md) for the full command reference and [`docs/user-journey.md`](https://github.com/jasonssdev/openkos/blob/main/docs/user-journey.md) for the end-to-end experience.
+## Before / after
+
+| | Without OpenKOS | With OpenKOS |
+| --- | --- | --- |
+| Asking your AI about your own notes | It re-reads raw files every time | It answers from a compiled, cited knowledge base |
+| New source | Piles up unread | Compiled into a Source plus typed knowledge objects, each linked to its source |
+| Provenance | "Where did this come from?" is a guess | Every object links back to its immutable source |
+| Facts that change | Old claims quietly rot | Freshness stamps keep the base honest over time |
+| Portability | Trapped in one app | Plain OKF files — open in Obsidian, VS Code, GitHub, anything |
+| Privacy | Your knowledge leaves your machine | Local-first, offline-capable, local models |
 
 ## Philosophy
 
@@ -115,7 +107,7 @@ The wedge, in one line: **the local-first, personal producer-consumer-runtime fo
 OpenKOS ships in three MVP arcs, each usable on its own. Full detail in [`docs/roadmap.md`](https://github.com/jasonssdev/openkos/blob/main/docs/roadmap.md).
 
 - **MVP 1 — The Compiler. (Complete.)** The Karpathy loop, locally, over text: ingest → OKF concepts with provenance → cited query → freshness lint. Useful in an afternoon.
-- **MVP 2 — The Graph and Memory. (Complete.)** Entity/relationship extraction and reversible merge, a typed knowledge graph (an OpenKOS layer over OKF's untyped links — other tools still read the bundle fine), hybrid retrieval (lexical FTS5 + local vectors + graph, fused via RRF with PageRank), a fail-closed sensitivity filter (confidential concepts never reach the LLM), reference-aware `forget` plus an irreversible `purge` (right-to-be-forgotten), and answers that file back into the base (`query --save`, the two-output rule).
+- **MVP 2 — The Graph and Memory. (Complete.)** Entity/relationship extraction and reversible merge, a typed knowledge graph (an OpenKOS layer over OKF's untyped links — other tools still read the bundle fine), hybrid retrieval (lexical and semantic, rank-fused), a fail-closed sensitivity filter (confidential concepts never leave the machine — held back from any backend that is not verifiably local), a guided curation loop, reference-aware `forget` plus an irreversible `purge` (right-to-be-forgotten), and answers that file back into the base (the two-output rule).
 - **MVP 3 — The Runtime and Interoperability.** An MCP server and APIs so agents use OpenKOS as durable memory; full OKF import/export with the wider ecosystem.
 
 Beyond that: a desktop app, graph visualization, richer memory, and federation — explored only after the MVPs prove out with real users.
@@ -132,10 +124,10 @@ Beyond that: a desktop app, graph visualization, richer memory, and federation
 - [`docs/glossary.md`](https://github.com/jasonssdev/openkos/blob/main/docs/glossary.md) — definitions of the core vocabulary
 - [`docs/faq.md`](https://github.com/jasonssdev/openkos/blob/main/docs/faq.md) — frequently asked questions
 - [`docs/user-journey.md`](https://github.com/jasonssdev/openkos/blob/main/docs/user-journey.md) — the end-to-end user experience
-- [`docs/testing.md`](https://github.com/jasonssdev/openkos/blob/main/docs/testing.md) — manual end-to-end testing walkthrough (all 19 commands)
+- [`docs/testing.md`](https://github.com/jasonssdev/openkos/blob/main/docs/testing.md) — manual end-to-end testing walkthrough
 - [`docs/cli.md`](https://github.com/jasonssdev/openkos/blob/main/docs/cli.md) — the command-line reference
 - [`docs/brand.md`](https://github.com/jasonssdev/openkos/blob/main/docs/brand.md) — visual identity: isotype, wordmark, palette, typography
-- [`docs/adr/`](https://github.com/jasonssdev/openkos/blob/main/docs/adr/) — architecture decision records (the log begins with the first code-time decision)
+- [`docs/adr/`](https://github.com/jasonssdev/openkos/blob/main/docs/adr/) — architecture decision records
 
 ## Contributing
 

openkos-0.2.3/pyproject.toml

@@ -0,0 +1,131 @@
+[project]
+name = "openkos"
+version = "0.2.3"
+description = "Local-first engine that turns your scattered text into a living, portable knowledge base in the Open Knowledge Format (OKF)"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.12"
+keywords = [
+    "okf",
+    "open-knowledge-format",
+    "knowledge-base",
+    "knowledge-graph",
+    "local-first",
+    "rag",
+    "llm",
+    "second-brain",
+    "cli",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Text Processing :: Indexing",
+    "Typing :: Typed",
+]
+dependencies = [
+    "networkx>=3.4",
+    "python-frontmatter>=1.3.0",
+    "pyyaml>=6.0.3",
+    "scipy>=1.14",
+    "sqlite-vec>=0.1.6",
+    "typer>=0.27.0",
+]
+
+[[project.authors]]
+name = "Jason"
+email = "jasonssdev@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/jasonssdev/openkos"
+Repository = "https://github.com/jasonssdev/openkos"
+Issues = "https://github.com/jasonssdev/openkos/issues"
+Changelog = "https://github.com/jasonssdev/openkos/blob/main/CHANGELOG.md"
+
+[project.scripts]
+openkos = "openkos.cli.main:app"
+
+[build-system]
+requires = ["uv_build>=0.11.29,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "git-filter-repo>=2.47.0",
+    "mypy>=2.3.0",
+    "pre-commit>=4.6.0",
+    "pydantic>=2.13.4",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruamel-yaml>=0.19.1",
+    "ruff>=0.15.21",
+    "types-networkx>=3.6.1.20260624",
+    "types-pyyaml>=6.0.12.20260518",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = [
+    "--import-mode=importlib",
+    "--strict-markers",
+]
+markers = ["live_backend: test deliberately reaches a live Ollama backend"]
+
+[tool.coverage.run]
+source = ["openkos"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "S",
+    "DTZ",
+    "PT",
+    "PTH",
+    "RUF",
+]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101"]
+
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = [
+    "typer.Argument",
+    "typer.Option",
+]
+
+[tool.mypy]
+python_version = "3.12"
+files = [
+    "src",
+    "tests",
+]
+strict = true
+warn_unreachable = true
+enable_error_code = [
+    "ignore-without-code",
+    "redundant-expr",
+    "truthy-bool",
+    "possibly-undefined",
+]
+
+[[tool.mypy.overrides]]
+module = "sqlite_vec.*"
+ignore_missing_imports = true

openkos-0.2.0/pyproject.toml → openkos-0.2.3/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "openkos"
-version = "0.2.0"
+version = "0.2.3"
 description = "Local-first engine that turns your scattered text into a living, portable knowledge base in the Open Knowledge Format (OKF)"
 readme = "README.md"
 license = "Apache-2.0"
@@ -74,7 +74,23 @@ dev = [
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = ["--import-mode=importlib"]
+# `--strict-markers` turns an unregistered marker into a collection error
+# instead of a `PytestUnknownMarkWarning` nobody reads (#264). The entire
+# opt-out from the unit suite's fail-closed network guard is a marker NAME
+# matched as a string, so a misspelled `live_backend` would otherwise leave
+# BOTH autouse fixtures installed while reading as a deliberate opt-out --
+# and, combined with the absorbability the guard's own docstring concedes,
+# a mis-marked live-backend pin would degrade through a broad handler and
+# read green while never contacting the backend it claims to measure. That
+# is #217's silence, re-entered through the escape hatch.
+addopts = ["--import-mode=importlib", "--strict-markers"]
+markers = [
+    # Opts a test out of the unit suite's fail-closed network guard (#217).
+    # Reserved for assumption pins that measure the real backend and already
+    # gate themselves on a reachability probe -- not an escape hatch for a
+    # unit test that is merely inconvenient to stub.
+    "live_backend: test deliberately reaches a live Ollama backend",
+]
 
 # Coverage is opt-in: `--cov` is deliberately not in pytest's addopts, so plain
 # `uv run pytest` stays fast for the local loop. CI passes `--cov`, and because

{openkos-0.2.0 → openkos-0.2.3}/src/openkos/bundle/index.py

@@ -227,3 +227,81 @@ def remove_index_entry(index_text: str, concept_id: str) -> tuple[str, int]:
     if removed == 0:
         return index_text, 0
     return frontmatter_block + "".join(kept_lines), removed
+
+
+_LABELLED_LINK_RE = re.compile(r"\[([^\]]*)\]\(([^)]+)\)")
+_LABEL_UNSAFE_CHARS_RE = re.compile(r"[\[\]()`]")
+
+
+def _reject_markdown_link_delimiters(field: str, value: str) -> None:
+    """Raise `ValueError` if `value` contains `[`, `]`, `(`, `)`, or a
+    backtick (Slice 2 review finding, corroborated by execution).
+
+    The LABEL span written by `relabel_index_entry` is the one place a
+    title is interpolated without becoming the link target or description,
+    so it is the one place a slipped-through delimiter lets the REST of the
+    bullet be rewritten: `[`/`]` forges a second link, `(`/`)` breaks the
+    existing target. Either way `_LINK_RE`/`_LABELLED_LINK_RE` then match
+    the FORGED link, not the real one -- verified by execution: the bullet
+    becomes invisible to both `relabel_index_entry` and `remove_index_entry`.
+    """
+    if _LABEL_UNSAFE_CHARS_RE.search(value):
+        raise ValueError(
+            f"index.md: {field!r} must not contain a markdown link delimiter "
+            "('[', ']', '(', ')') or a backtick"
+        )
+
+
+def relabel_index_entry(
+    index_text: str, concept_id: str, new_title: str
+) -> tuple[str, int]:
+    """Rewrite the LABEL of every bullet whose FIRST markdown link resolves to
+    `concept_id`, leaving slug, link target, and description untouched.
+
+    `remove_index_entry`'s twin: same frontmatter-splitting discipline, same
+    line-walk, same "first link only" candidate rule, same zero/duplicate
+    count semantics -- but this REWRITES a span instead of dropping a line.
+    Identity is `_link_identity(target) == concept_id`, never a label-text
+    match, because the whole point of this function is to correct a label
+    that has drifted from the document's actual `title` -- matching on the
+    (stale) label itself would never find the bullet that needs fixing.
+
+    Uses a SEPARATE regex, `_LABELLED_LINK_RE`, rather than adding a capture
+    group to the module-level `_LINK_RE`: `remove_index_entry` reads
+    `_LINK_RE.search(...).group(1)` as the link TARGET and depends on
+    `_LINK_RE` having exactly one group, so widening it here would silently
+    break that call site.
+
+    Only the label span between `[` and `]` of the bullet's first link is
+    replaced; the link target, the ` - ` separator, the description, the
+    bullet marker, leading indentation, and the line ending all round-trip
+    verbatim. `_reject_newline` and `_reject_markdown_link_delimiters` both
+    guard `new_title` (see the latter's own docstring for why the label
+    span is the one place that must be escaped). Count semantics mirror
+    `remove_index_entry`: zero matches returns `(index_text, 0)` unchanged --
+    not an error, since catalog drift is not a reason to refuse an otherwise
+    safe relabel; more than one match (a duplicate catalog entry) relabels
+    ALL of them, reporting the total, since leaving one stale label behind
+    would be worse than the duplicate itself.
+    """
+    _reject_newline("new_title", new_title)
+    _reject_markdown_link_delimiters("new_title", new_title)
+    frontmatter_block, body = _split_frontmatter_verbatim(index_text)
+    lines = body.splitlines(keepends=True)
+    result_lines: list[str] = []
+    relabeled = 0
+    for line in lines:
+        stripped = line.lstrip()
+        if stripped.startswith(_BULLET_MARKERS):
+            match = _LABELLED_LINK_RE.search(stripped)
+            if match is not None and _link_identity(match.group(2)) == concept_id:
+                start, end = match.span(1)
+                stripped = stripped[:start] + new_title + stripped[end:]
+                indent = line[: len(line) - len(line.lstrip())]
+                line = indent + stripped
+                relabeled += 1
+        result_lines.append(line)
+
+    if relabeled == 0:
+        return index_text, 0
+    return frontmatter_block + "".join(result_lines), relabeled