openkos 0.1.0__tar.gz

openkos-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: openkos
+Version: 0.1.0
+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
+Author-email: Jason <jasonssdev@gmail.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Typing :: Typed
+Requires-Dist: networkx>=3.4
+Requires-Dist: python-frontmatter>=1.3.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: scipy>=1.14
+Requires-Dist: sqlite-vec>=0.1.6
+Requires-Dist: typer>=0.27.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/jasonssdev/openkos
+Project-URL: Repository, https://github.com/jasonssdev/openkos
+Project-URL: Issues, https://github.com/jasonssdev/openkos/issues
+Project-URL: Changelog, https://github.com/jasonssdev/openkos/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# OpenKOS
+
+**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 — 18 CLI verbs, hybrid retrieval, and the full forget/purge lifecycle all ship today. The API may still change, and there is no published release yet (no PyPI package, no tagged version) — but you can install straight from this repository today, see [Getting started](#getting-started). 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.
+
+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.
+
+## The idea
+
+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.
+
+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.**
+
+## 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
+
+```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
+```
+
+*(The full command set — 18 verbs spanning ingest, cited query, the typed graph, entity resolution, and the forget/purge lifecycle — is in [`docs/cli.md`](docs/cli.md).)*
+
+## Getting started
+
+> Alpha: the commands below run today. OpenKOS is **not yet published to PyPI**, so for now install straight from the GitHub repository — no clone required. A published `pip install openkos` will follow once the API stabilizes.
+
+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.
+
+**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.
+
+**Install the engine** (once, from the repository):
+
+```bash
+uv tool install git+https://github.com/jasonssdev/openkos   # or: pipx install git+https://github.com/jasonssdev/openkos
+```
+
+This installs the `openkos` command on your PATH. To try it once without a persistent install, run it ephemerally instead:
+
+```bash
+uvx --from git+https://github.com/jasonssdev/openkos openkos --help
+```
+
+To upgrade later, re-run the install command (uv reinstalls from the latest `main`). Once OpenKOS reaches PyPI, this becomes `uv tool install openkos` — no git URL needed.
+
+**Create a bundle** (per knowledge base):
+
+```bash
+mkdir ~/knowledge && cd ~/knowledge
+openkos init
+```
+
+`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.
+
+**Then the loop:**
+
+```bash
+openkos ingest ./meeting-notes.txt   # compile a source into the bundle
+openkos query "what did we decide?"  # get a cited answer
+```
+
+See [`docs/cli.md`](docs/cli.md) for the full command reference and [`docs/user-journey.md`](docs/user-journey.md) for the end-to-end experience.
+
+## Philosophy
+
+- **Local-first and private by default.** Runs on your machine, works offline, built for local models. The cloud is optional, never required.
+- **Standard-aligned, not bespoke.** We adopt OKF rather than invent a format, and adopt its definitions rather than restate them. An open, vendor-neutral specification is the most agnostic choice there is.
+- **Living knowledge, honest over time.** Sources are immutable; concept documents evolve as you learn; fast-changing facts carry freshness stamps so nothing silently becomes a lie.
+- **The human curates; the engine maintains.** You source, explore, and ask. OpenKOS does the bookkeeping — extraction, linking, freshness, indexing.
+- **Reconstructible and explainable.** Every index, embedding, and graph rebuilds from the canonical bundle plus sources. Answers always cite.
+
+## How OpenKOS relates to the ecosystem
+
+We build on the shoulders of prior work rather than competing with it:
+
+- **[Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)** — the seminal pattern. OpenKOS is a concrete engine that instantiates it.
+- **[Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing)** (Google Cloud) — the standard we store and exchange in. Google's reference stack targets enterprise cloud data (BigQuery); OpenKOS is its local-first, personal counterpart.
+- **Obsidian-based tools** (obsidian-mind, obsidian-second-brain) — excellent, but tied to Obsidian and packaged as prompt/skill conventions. OpenKOS is a standalone, app-agnostic engine whose output is portable OKF.
+
+The wedge, in one line: **the local-first, personal producer-consumer-runtime for OKF that nobody else has built.**
+
+## Roadmap at a glance
+
+OpenKOS ships in three MVP arcs, each usable on its own. Full detail in [`docs/roadmap.md`](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 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.
+
+## Documentation
+
+- [`docs/vision.md`](docs/vision.md) — vision, philosophy, and positioning
+- [`docs/philosophy.md`](docs/philosophy.md) — the foundational essay: what knowledge is and why OpenKOS matters
+- [`docs/knowledge-object-model.md`](docs/knowledge-object-model.md) — how knowledge is represented (OKF + the OpenKOS layer)
+- [`docs/roadmap.md`](docs/roadmap.md) — the MVP roadmap
+- [`docs/tech_stack.md`](docs/tech_stack.md) — technology choices
+- [`docs/architecture.md`](docs/architecture.md) — repository and bundle structure, and source versioning
+- [`docs/okf-alignment.md`](docs/okf-alignment.md) — how OpenKOS relates to OKF
+- [`docs/glossary.md`](docs/glossary.md) — definitions of the core vocabulary
+- [`docs/faq.md`](docs/faq.md) — frequently asked questions
+- [`docs/user-journey.md`](docs/user-journey.md) — the end-to-end user experience
+- [`docs/cli.md`](docs/cli.md) — the command-line reference
+- [`docs/brand.md`](docs/brand.md) — visual identity: isotype, wordmark, palette, typography
+- [`docs/adr/`](docs/adr/) — architecture decision records (the log begins with the first code-time decision)
+
+## Contributing
+
+OpenKOS is early, which is the best time to shape it. The clearest entry points are the "community can contribute" notes under the current MVP in the [roadmap](docs/roadmap.md). Please open an issue to discuss anything larger than a small change before sending a PR, so we can make sure it fits and can be merged.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to get involved and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards. Maintainers: see [MAINTAINERS.md](MAINTAINERS.md) for how contributions are reviewed and decided.
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).

openkos-0.1.0/README.md

@@ -0,0 +1,143 @@
+# OpenKOS
+
+**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 — 18 CLI verbs, hybrid retrieval, and the full forget/purge lifecycle all ship today. The API may still change, and there is no published release yet (no PyPI package, no tagged version) — but you can install straight from this repository today, see [Getting started](#getting-started). 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.
+
+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.
+
+## The idea
+
+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.
+
+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.**
+
+## 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
+
+```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
+```
+
+*(The full command set — 18 verbs spanning ingest, cited query, the typed graph, entity resolution, and the forget/purge lifecycle — is in [`docs/cli.md`](docs/cli.md).)*
+
+## Getting started
+
+> Alpha: the commands below run today. OpenKOS is **not yet published to PyPI**, so for now install straight from the GitHub repository — no clone required. A published `pip install openkos` will follow once the API stabilizes.
+
+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.
+
+**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.
+
+**Install the engine** (once, from the repository):
+
+```bash
+uv tool install git+https://github.com/jasonssdev/openkos   # or: pipx install git+https://github.com/jasonssdev/openkos
+```
+
+This installs the `openkos` command on your PATH. To try it once without a persistent install, run it ephemerally instead:
+
+```bash
+uvx --from git+https://github.com/jasonssdev/openkos openkos --help
+```
+
+To upgrade later, re-run the install command (uv reinstalls from the latest `main`). Once OpenKOS reaches PyPI, this becomes `uv tool install openkos` — no git URL needed.
+
+**Create a bundle** (per knowledge base):
+
+```bash
+mkdir ~/knowledge && cd ~/knowledge
+openkos init
+```
+
+`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.
+
+**Then the loop:**
+
+```bash
+openkos ingest ./meeting-notes.txt   # compile a source into the bundle
+openkos query "what did we decide?"  # get a cited answer
+```
+
+See [`docs/cli.md`](docs/cli.md) for the full command reference and [`docs/user-journey.md`](docs/user-journey.md) for the end-to-end experience.
+
+## Philosophy
+
+- **Local-first and private by default.** Runs on your machine, works offline, built for local models. The cloud is optional, never required.
+- **Standard-aligned, not bespoke.** We adopt OKF rather than invent a format, and adopt its definitions rather than restate them. An open, vendor-neutral specification is the most agnostic choice there is.
+- **Living knowledge, honest over time.** Sources are immutable; concept documents evolve as you learn; fast-changing facts carry freshness stamps so nothing silently becomes a lie.
+- **The human curates; the engine maintains.** You source, explore, and ask. OpenKOS does the bookkeeping — extraction, linking, freshness, indexing.
+- **Reconstructible and explainable.** Every index, embedding, and graph rebuilds from the canonical bundle plus sources. Answers always cite.
+
+## How OpenKOS relates to the ecosystem
+
+We build on the shoulders of prior work rather than competing with it:
+
+- **[Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)** — the seminal pattern. OpenKOS is a concrete engine that instantiates it.
+- **[Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing)** (Google Cloud) — the standard we store and exchange in. Google's reference stack targets enterprise cloud data (BigQuery); OpenKOS is its local-first, personal counterpart.
+- **Obsidian-based tools** (obsidian-mind, obsidian-second-brain) — excellent, but tied to Obsidian and packaged as prompt/skill conventions. OpenKOS is a standalone, app-agnostic engine whose output is portable OKF.
+
+The wedge, in one line: **the local-first, personal producer-consumer-runtime for OKF that nobody else has built.**
+
+## Roadmap at a glance
+
+OpenKOS ships in three MVP arcs, each usable on its own. Full detail in [`docs/roadmap.md`](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 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.
+
+## Documentation
+
+- [`docs/vision.md`](docs/vision.md) — vision, philosophy, and positioning
+- [`docs/philosophy.md`](docs/philosophy.md) — the foundational essay: what knowledge is and why OpenKOS matters
+- [`docs/knowledge-object-model.md`](docs/knowledge-object-model.md) — how knowledge is represented (OKF + the OpenKOS layer)
+- [`docs/roadmap.md`](docs/roadmap.md) — the MVP roadmap
+- [`docs/tech_stack.md`](docs/tech_stack.md) — technology choices
+- [`docs/architecture.md`](docs/architecture.md) — repository and bundle structure, and source versioning
+- [`docs/okf-alignment.md`](docs/okf-alignment.md) — how OpenKOS relates to OKF
+- [`docs/glossary.md`](docs/glossary.md) — definitions of the core vocabulary
+- [`docs/faq.md`](docs/faq.md) — frequently asked questions
+- [`docs/user-journey.md`](docs/user-journey.md) — the end-to-end user experience
+- [`docs/cli.md`](docs/cli.md) — the command-line reference
+- [`docs/brand.md`](docs/brand.md) — visual identity: isotype, wordmark, palette, typography
+- [`docs/adr/`](docs/adr/) — architecture decision records (the log begins with the first code-time decision)
+
+## Contributing
+
+OpenKOS is early, which is the best time to shape it. The clearest entry points are the "community can contribute" notes under the current MVP in the [roadmap](docs/roadmap.md). Please open an issue to discuss anything larger than a small change before sending a PR, so we can make sure it fits and can be merged.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to get involved and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards. Maintainers: see [MAINTAINERS.md](MAINTAINERS.md) for how contributions are reviewed and decided.
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).

openkos-0.1.0/pyproject.toml

@@ -0,0 +1,149 @@
+[project]
+name = "openkos"
+version = "0.1.0"
+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"
+authors = [
+    { name = "Jason", email = "jasonssdev@gmail.com" }
+]
+requires-python = ">=3.12"
+keywords = [
+    "okf",
+    "open-knowledge-format",
+    "knowledge-base",
+    "knowledge-graph",
+    "local-first",
+    "rag",
+    "llm",
+    "second-brain",
+    "cli",
+]
+# The `License ::` trove classifier is deliberately omitted: `license` above is
+# an SPDX expression (PEP 639), and declaring the license twice makes modern
+# build backends warn or fail. The SPDX string is the single source of truth.
+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.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"]
+
+# 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
+# the gate lives here, a local `uv run pytest --cov` gates identically to CI.
+[tool.coverage.run]
+source = ["openkos"]
+# Line coverage alone lets an `if` that never goes both ways read as covered;
+# branch coverage counts each direction.
+branch = true
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+
+# Ruff infers `target-version` from `project.requires-python` (3.12) and
+# defaults `line-length` to 88; neither is restated here. The formatter runs on
+# defaults, so there is no [tool.ruff.format] section.
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # Pyflakes: undefined names, unused imports
+    "I",   # isort: deterministic import order, keeps the layering rule auditable
+    "UP",  # pyupgrade: the 3.12 floor means no back-compat idioms are needed
+    "B",   # bugbear: mutable defaults, `raise ... from`, unstrict `zip`
+    "SIM", # flake8-simplify
+    "S",   # bandit: untrusted user text, YAML frontmatter, git subprocess
+    "DTZ", # naive datetimes would corrupt OKF `as of` / freshness stamps
+    "PT",  # flake8-pytest-style: tests are a first-class quality gate
+    "PTH", # pathlib: the engine is filesystem-centric and must stay portable
+    "RUF", # Ruff-specific, incl. RUF100 (unused noqa) to keep suppressions honest
+]
+ignore = [
+    "E501", # line length is the formatter's job; E501 only fights it on long strings/URLs
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "S101", # `assert` is what a test is made of
+]
+
+[tool.ruff.lint.flake8-bugbear]
+# `typer.Argument(...)`/`typer.Option(...)` in a parameter default is the
+# idiomatic Typer CLI pattern (B008 normally flags a mutable default called
+# at definition time), and both are effectively immutable declarative
+# markers, not runtime state. `bool`/`str | None`-annotated parameters are
+# already exempt by B008's own immutable-type check; `Path`-annotated ones
+# (e.g. `ingest`'s `src` argument) are not, so both callables are listed
+# explicitly here for consistency across every future Typer command.
+extend-immutable-calls = ["typer.Argument", "typer.Option"]
+
+[tool.mypy]
+# Pin the analysis target to the declared floor so a contributor on a newer
+# interpreter cannot merge code that is broken on 3.12.
+python_version = "3.12"
+files = ["src", "tests"]
+strict = true
+# Not implied by `strict`: dead code left by a wrong narrowing is a real bug,
+# and `py.typed` means our type errors become our consumers' type errors.
+warn_unreachable = true
+enable_error_code = [
+    "ignore-without-code", # a bare `# type: ignore` silences more than it claims
+    "redundant-expr",
+    "truthy-bool",       # catches `if obj:` on an always-truthy object
+    "possibly-undefined",
+]
+
+# `sqlite-vec` ships no type stubs; this keeps `mypy . --strict` (repo-wide,
+# incl. tests) green without weakening `strict` for the rest of the codebase.
+[[tool.mypy.overrides]]
+module = "sqlite_vec.*"
+ignore_missing_imports = true

openkos-0.1.0/src/openkos/__init__.py

@@ -0,0 +1 @@
+"""openkos: local-first engine that compiles text into a portable knowledge base."""

openkos-0.1.0/src/openkos/bundle/__init__.py

@@ -0,0 +1,4 @@
+"""Canonical OKF bundle: the rendered and written shape of `bundle/`.
+
+Never imports from the derived layer (`retrieval`, `graph`, `memory`).
+"""

openkos-0.1.0/src/openkos/bundle/bundle.py

@@ -0,0 +1,28 @@
+"""Writes the OKF bundle root: `index.md` and `log.md`.
+
+The only module in `bundle/` that touches the filesystem — `index.py` and
+`log.py` stay pure renderers.
+"""
+
+from datetime import date
+from pathlib import Path
+
+from openkos import fsio
+from openkos.bundle.index import render_index
+from openkos.bundle.log import render_log
+
+
+def create(bundle_dir: Path, today: date) -> None:
+    """Create a fresh bundle at `bundle_dir`: `index.md` then `log.md`.
+
+    Both files are written with exclusive-create mode ("x"): a colliding
+    file raises `FileExistsError` instead of being overwritten (D2). This
+    closes the Phase-A -> B TOCTOU window only for these two leaf files —
+    NOT for `bundle_dir.mkdir(parents=True, exist_ok=True)` above, where a
+    racing writer adding a non-colliding file is silently absorbed (known,
+    accepted limitation, D2). No cleanup path on a mid-write failure (D3): a
+    partially written bundle is left as-is for manual recovery.
+    """
+    bundle_dir.mkdir(parents=True, exist_ok=True)
+    fsio.write_exclusive(bundle_dir / "index.md", render_index())
+    fsio.write_exclusive(bundle_dir / "log.md", render_log(today))