README and HANDBOOK: relation to OKF

HANDBOOK.md

@@ -299,3 +299,23 @@ Create a Contract when a client — a frontend, an integration, an agent — wou
 Create a prompt when repeated agent work needs scoped context.
 
 Create a task when someone needs to execute bounded work.
+
+## Relation to OKF
+
+Google Cloud's [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) shares KDE's substrate: markdown with YAML frontmatter, cross-linked, versioned in git. It addresses a different layer. This comparison is as of OKF v0.2; the spec is young and changes between minor versions.
+
+| | OKF | KDE |
+| --- | --- | --- |
+| What it is | An interchange format | A governance process for knowledge |
+| On errors | Tolerant consumers: best effort, never reject a bundle for broken links or unknown fields | A strict gate: the validator fails CI |
+| Typical knowledge | Metadata about data and systems — tables, metrics, catalogs | Product rules and decisions for agents that change code |
+| Trust | Recorded: `verified` lists `{by, at}` events; a `human:` actor makes a document human-reviewed | Enforced: an agent-drafted document enters current truth only through human promotion |
+| Lifecycle | `status: draft \| stable \| deprecated`, plus `stale_after` | Supersession with history, a computed index of what applies today, and the list of dependents a supersession affects |
+| History and audit | `log.md` prose history per directory; `generated` and `verified` timestamps | Decision Records are superseded, never edited; approver and date are recorded on promotion; acceptance blocks can be rerun to show a spec still holds |
+| Retrieval for a task | `index.md` files for progressive disclosure; how to consume is left to the reader | A prescribed path: domain, generated `CONTEXT.md`, active decisions, current spec, then code |
+| Conflicting sources | Not addressed | Explicit precedence; conflicts are reported, never resolved silently |
+| Relation to code | None | Drift gate on pull requests; acceptance blocks run the project's tests |
+
+OKF has what KDE does not: per-claim provenance (`sources` with footnote ids), an explicit expiry (`stale_after`), several independent verifications per document, and attested computations — sanctioned calculations an agent may parameterize but not modify, checked by deterministic code.
+
+A KDE repository is not an OKF bundle today: OKF requires a non-empty `type` in the frontmatter of every markdown file other than `index.md` and `log.md`, and KDE derives the type from the folder and the id prefix, and generates `CONTEXT.md` without frontmatter.

README.md

@@ -137,7 +137,13 @@ Skip it for throwaway prototypes, single-purpose scripts, and code whose meaning
 
 The pieces are deliberately familiar: Decision Records (Nygard's ADRs), RFC processes, spec-driven development, the `AGENTS.md` convention, and domain partitioning from DDD. KDE is an operational synthesis for teams where agents implement, and its delta is what that tradition leaves out: a computable projection of current truth, explicit precedence between sources, consumption rules for agents, knowledge integrity as CI, and a governed path for knowledge that so far exists only in code.
 
-The substrate — markdown with YAML frontmatter, linked into a graph, versioned in git — is shared with Google Cloud's [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf), which is deliberately unopinionated. KDE operates the layer it leaves out: lifecycle, current truth, precedence, and governance of agent-authored knowledge.
+The raw material — markdown files with a short header, linked to each other, versioned in git — is the same one Google Cloud's [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) (OKF) uses, but the two solve different halves of the problem. OKF is a shared way to write knowledge down so any tool can read it, and it is deliberately forgiving: a reader takes whatever it finds. KDE is about knowledge you can rely on while you work:
+
+- **Trustworthy.** Nothing an agent writes counts until a person approves it, and a pull request fails when the code and the knowledge stop agreeing.
+- **Checkable after the fact.** Decisions are replaced, never rewritten, so you can see who approved what, when, and what it replaced; a spec's tests can be rerun at any time to show it still holds.
+- **Quick to find.** An agent starting a task does not search the whole repository: it goes to the area it is changing and reads the decisions that apply today, then the code — in the field, a domain's rules read in about 8,000 tokens instead of the 130,000 it took to work them out from the code.
+
+OKF does a few things KDE does not, such as setting a date when a document should be checked again and recording more than one reviewer. The [handbook](HANDBOOK.md#relation-to-okf) has the detailed comparison.
 
 ## This Repository