# okf-wiki Every standing rule in this repository is in this file or in `docs/rule-decisions.md`. Nothing is inherited from the repository this one replaces (`llm-ingestion-okf`). The rules removed on 06.11.2026 are in git history. ## Goal (the operator's words, without a solution) Point Claude Code at a folder of documents of any kind: documentation, one's own collections, mixed PDF and Office files. The result is a knowledge collection the operator trusts. Every claim on every page shows where it comes from, and the source can be opened. Questions, especially those that need several documents seen together, are answered better with the collection than without it. The operator's approved direction stands at the top of `PLAN.md` and wins where anything else disagrees; nobody rewords it without him. v1 is collection 1 (the Claude Code documentation and its release notes). v1.1 is one real folder of mixed PDF and Office files built without a code change, the operator's own questions to each collection, and a fresh collection 1 published; its finish line is in `PLAN.md`. A third collection and questions across collections come after v1.1 (operator 13.11.2026). ## The shape - **The unit is the concept,** built additively for each document read in. - **K, the fragment compiler, plus Google's link rule.** Code splits sources into blocks, the user's session writes short quoted fragments per pack of five sources through the skill (`skills/okf-wiki/SKILL.md`), and code assembles the pages. The model makes links from meaning; there is no code linker. The auditor checks only structure: every link points to a page that exists, no link sits in code, a heading or a footnote, every single-topic source has a main page, and every other concept page has a link from at least one main page (`index.md` does not count). - **One hard check at writing:** every sentence has a footnote to a source that exists and a quote that stands verbatim in it. Claims carry a provenance mark (`x-provenance`: documented | inferred | merged). Outdated-marking (`x-outdated`) is not in v1. The change warning is: code reports which sources are new, changed or gone and marks the pages built on them, so one source's contribution must be replaceable on its own. - **The auditor** (no model) reads sources into a locked raw-source layer (sha256 + page/slide/cell/line), checks every quote at its locator, SPEC § 11 conformance, links, orphans and index coverage, and renders a static HTML view. It is the collection's recurring health check. - **The independent reader** (`agents/okf-wiki-reader.md`) judges claims against their cited excerpts only, up to ten per call. v1's measurement stands. After v1 it reads a small random sample when a build changes. - **A read-only MCP server** serves lookups across collections. Plain file search always keeps working beside it. - The trial code in `evals/p1/` is not v1 code. ## Binding rules (the operator's; changing them is the operator's decision) 1. Shipped tools never call a language model or Claude Code. Model work happens in the user's own session through the skill. 2. `STATE.md`, `PLAN.md` and secrets stay local (gitignored), because this repository becomes public after v1. No marketing language. 3. Text derived from Anthropic documentation is never committed. The Claude Code docs test set lives outside the repository, and only its shape is published. 4. Forgejo only, never GitHub. Never commercial, and no link to the operator's employer: `tools/check-excluded-terms.sh` runs before every commit and on every commit message (install once per clone with `tools/install-hooks.sh`, from the main checkout). 5. Sources are always there as references: every concept links to the actual document or documents it comes from, with as exact a reference as is practical. ## The standard Google Open Knowledge Format, ; we keep it (operator 06.11.2026). `SPEC.md` at the pinned commit is the source of truth: before touching anything format-related, read its § 2 terminology and the section concerned, and quote the § number. Where it is not good enough for the goal, use `x-` fields, marked clearly, justified by a measurement, and movable to a standard field if Google adopts one. ## Working here - Test first (no production code without a failing test), `mypy --strict`, Conventional Commits, English in code and docs. - Tests: `python3 -m unittest discover -s tests` (also `gates/tests`, `evals/tests`); a single file with `-p 'test_X.py'`, because a `tests` package in site-packages shadows `tests.X`. - Types: `~/.local/bin/uvx --offline --with types-PyYAML mypy --strict okfwiki gates tests tools/*.py` (`python3 -m mypy` does not work on this machine). - One model build at a time: two runs would create the same concept twice. - An agent file edited during a session reaches subagents only after the session restarts. - Decisions the operator cannot take without reading code are taken here and written as "chose X because Y" in the commit.