First public release, published as one snapshot. What changed between versions is in CHANGELOG.md. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
60 lines
5 KiB
Markdown
60 lines
5 KiB
Markdown
# 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, <https://github.com/GoogleCloudPlatform/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.
|