# Log

## 2026-07-31

**Update** — Added a deterministic migration preflight after Luna and Sonnet independently confused
historical prose and fenced YAML examples with active metadata. The bundled `kb-lint` checker now
supports `--inventory [--json]`, parsing only leading concept frontmatter while reporting body
`# Citations` separately; it emits exact counts and paths for every observed top-level key and status
value. The shared version profile now requires that inventory before and after bundle-wide format or
lifecycle migrations, forbids repository-wide grep as the classifier for active metadata, and makes
concept/key accounting, extension preservation, postflight counts, and conformance explicit
completion criteria. Regression fixtures reproduce the false-positive pattern, and the repository
baseline locks the correct v0.1 inventory (52 timestamps and citation headings, 15 resources, two
deprecated statuses, and zero active generated/sources/superseded fields). Released as skills
package `0.3.1`.

**Update** — Migrated the distributed `kb-*` skill family to an OKF v0.2 producer/consumer profile:
vendored the authoritative v0.2 spec, made new scaffolds emit v0.2, replaced legacy producer
`timestamp`/`# Citations` guidance with `generated`/structured `sources` and keyed footnotes, added
trust/freshness/attestation consumption, extended deterministic lint and graph output, and retained
declared v0.1 maintenance through the §13 compatibility fallbacks. The package is now `0.3.0`; this
repository's own bundle remains intentionally authored in v0.1 pending a separate dogfooding migration.

**Ingest** — Re-assessed [openwiki (langchain-ai)](./ecosystem/openwiki_langchain_v2.md) from a re-fetch of its GitHub README. The 2026-07-01 assessment is now materially wrong: openwiki **emits OKF v0.1 bundles** in both modes (was "Not OKF") and has a general-knowledge **"Personal mode"** ingesting connectors — git-repo, Gmail, Notion, X, Web Search, Hacker News (was "codebase docs only"). High-confidence supersede (same `resource`, trust model §1/§3): wrote new concept [openwiki_langchain_v2](./ecosystem/openwiki_langchain_v2.md) (`supersedes: openwiki_langchain`), tombstoned [the old page](./ecosystem/openwiki_langchain.md) (`status: superseded`, `superseded_by`), and relinked [ecosystem index](./ecosystem/index.md), [landscape](./ecosystem/landscape.md), and [skill design](./design/skill_design.md). openwiki is now a **direct OKF-emitting peer and plausible interop target**; its remaining gap is **no trust model**, which sharpens our v0.2 provenance/trust differentiation. Open question: openwiki targets OKF v0.1 while this bundle documents v0.2 — worth watching whether it adopts the v0.2 provenance/trust families.

**Update** — Completed the OpenWiki impact sweep that the initial ingest missed: superseded the stale [2026-07-01 competitor comparison](./ecosystem/competitor_comparison.md) with a [current four-way comparison](./ecosystem/competitor_comparison_v2.md), linked it from the OpenWiki successor and ecosystem index, narrowed unsupported claims about OpenWiki's trust model to what its README documents, and adopted OKF v0.2 `status: deprecated` on retired concepts.

**Update** — Migrated the `spec/` pages to document **OKF v0.2** (full re-spec), ingested from the [SPEC.md reference](./references/okf_spec.md). Two breaking changes now recorded with consumer fallbacks: `timestamp` superseded by `generated.at`, and the body `# Citations` list superseded by the [`sources`](./spec/citations.md) frontmatter family. Rewrote the breaking-change pages ([frontmatter](./spec/frontmatter.md), [citations→provenance](./spec/citations.md), [versioning](./spec/versioning.md) now §12) and the renumbered/additive pages ([body](./spec/body.md), [cross-linking](./spec/cross_linking.md) §6 with path-valued fields and the `references/` convention, [index files](./spec/index_files.md) §8, [log files](./spec/log_files.md) §9, [conformance](./spec/conformance.md) §11 with the optional-family rules and trust tiers). Created four new pages: [Provenance, Trust & Lifecycle](./spec/provenance_trust_lifecycle.md) (§5), [Actor Convention](./spec/actor_convention.md) (§7), [Attested Computations](./spec/attested_computations.md) (§10), and [Changes from v0.1](./spec/changes_from_v01.md) (§13). Each page carries an in-page "Changed from v0.1" note. Updated both the [spec index](./spec/index.md) and the [root index](./index.md), and recorded what v0.2 shipped in [OKF Spec Evolution](./design/spec_evolution.md). The bundle continues to *document* v0.2 while remaining *authored* in v0.1 (`okf_version: "0.1"`); re-authoring the bundle's own frontmatter to v0.2 is a separate future exercise.

## 2026-07-01

**Ingest** — Assessed [openwiki (langchain-ai)](./ecosystem/openwiki_langchain.md), a new LangChain CLI that auto-documents codebases for agents. Verdict: **adjacent lane, not a format competitor** — plain markdown (no frontmatter/`type`), codebase-docs only, no trust model, regenerates from source. Matters for two reasons: (1) LangChain entering hardens the "agent-maintained wiki" category and our positioning as the OKF/general-knowledge/trust-modeled option; (2) its agent prompt is a proven source of `kb-ingest` techniques — git-evidence grounding, plan-then-write, read-only research subagents — now recorded in [Skill Design](./design/skill_design.md). Added ecosystem landscape category 7 (codebase-doc generators).

**Update** — Pre-publish pass. Generated [viz.html](./index.md) for this bundle (committed at bundle root, like the OKF samples). Anonymized the two implementation prior-art pages for public release — a [personal work wiki](./implementations/personal_work_wiki.md) and an [OKF-native agent](./implementations/okf_native_agent.md) — removing internal project/program names, private repo URLs, and the author's home path while keeping the structural lessons. Added repo-level `README.md` (mattpocock-style: why → install → skills-by-invocation → self-documenting bundle), `LICENSE` (MIT + Apache-2.0 attribution for the vendored SPEC), and `.gitignore`. Prepared to publish as `stjbrown/agent-knowledge`.

**Creation** — Built **`kb-visualize`** (user-invoked) — completes the family (6/6). A bundled `scripts/graph.py` (no deps) extracts the deterministic graph model — nodes by `type`, edges + `cited_by` backlinks from cross-links, frontmatter + body per node; the agent then **authors** the view (adaptive, can scope to a subgraph), rather than running a fixed template. Key branch: render as **native UI** where the host supports it (Claude/Codex Desktop), else a **self-contained HTML file** (Cytoscape + marked via CDN, model inlined). View mirrors a conformant OKF viewer: colored force-graph, detail panel with in-view link navigation, backlinks, search, type filter. Read-only (no log entry from the skill itself). Tested `graph.py` on this bundle (46 nodes/325 edges/5 types; hub = `operations/ingest` at 25 inbound) and the example bundle. **Family fully cross-links; manifest lists all six.**

**Creation** — Built **`kb-lint`** (user-invoked) — the maintenance health-check. Two passes: a **deterministic conformance** check via a bundled `scripts/conformance.py` (self-contained `python3`, zero-install — reuses the mechanical §9 check without depending on an external validator; ERROR = hard §9 failure, warn = broken links/non-ISO dates which never fail per §5.3) and a **drift audit** (contradictions, stale claims, orphans, missing cross-refs, coverage/provenance gaps) with an exhaustive "every check, whole bundle" completion criterion. Severity-grouped report + append-only log summary; `fix` mode repairs only safe/unambiguous issues and flags meaning-level ones for ingest (never edits a claim in place). Tested the script against this bundle (55 files/46 concepts, conformant) and the example bundle — both clean. Registered in the manifest. Family now 5/6; only `kb-visualize` remains.

**Update** — Ran a `writing-great-skills` audit pass over the built skills. Fixed one real **duplication** smell: `kb-ingest` step 5 restated the trust model's supersede/conflict/event rules that already live in `kb/reference/trust-model.md` (the single source of truth) — collapsed it to *execute the plan, following the trust model for mechanics*. Confirmed `kb-query` step 3's read-time rules are **not** duplication (the trust model covers only the writing side; read-time behavior has no other home). No no-ops/sprawl found elsewhere worth cutting.

**Creation** — Built **`kb-ingest`** (model-invoked) — the core differentiator no competitor has: read a raw source once → extract → integrate across the bundle under the trust model. 9 steps, each with a checkable completion criterion (the premature-completion defense for this long sequence): locate bundle + read its schema layer → read/classify source → **plan** (openwiki's plan-then-write; the plan becomes the checklist later steps complete against) → store source as a Reference (provenance, N:1) → integrate under the trust model (supersede/conflict/events-additive, both-direction cross-links) → re-synthesize overviews → update indexes → append log → retire source + commit. Read-only research subagents allowed for large batches; only the main run writes. Registered in the manifest. All kb-ingest cross-links resolve; remaining forward-refs are kb-lint/kb-visualize.

**Update** — Fixed the `kb` hub's ambient-consult line to **route** to `kb-query` rather than describe the read inline (single-source-of-truth: reading logic lives only in kb-query). Built **`kb-query`** (model-invoked): two modes (explicit question + ambient consult for another task), progressive-disclosure navigation, currency/conflict-aware reading (follow `superseded_by`; answer contested questions with nuance), cite specific concepts, and file valuable answers back so queries compound — each step with a checkable completion criterion. Registered it in `.claude-plugin/plugin.json`. Remaining skill cross-links are forward-refs to kb-ingest/kb-lint/kb-visualize.

**Creation** — Built the skill foundation under `skills/`: the **`kb` hub** (model-invoked router — `SKILL.md`, `reference/SPEC.md` vendored verbatim, `reference/glossary.md`, `reference/trust-model.md`, `templates/{concept,index,log}.md`, and a self-contained conformant `example-bundle/` that doubles as kb-init's seed) and **`kb-init`** (user-invoked scaffolder: default `knowledge/`, custom path, multi-bundle aware, writes the schema layer as `spec/` concepts, print-a-prompt domain tailoring). Added `.claude-plugin/plugin.json` (skills.sh + Claude Code plugin, mattpocock/skills layout). Example-bundle verified conformant; remaining cross-links are forward-refs to the not-yet-built action skills.

**Update** — Settled the three open build decisions in [Skill Design](./design/skill_design.md): (1) distribution → skills.sh single-plugin layout (mattpocock/skills model — `skills/<name>/SKILL.md` + `.claude-plugin/plugin.json`, no build step; family ships as one plugin so action skills reach the `kb` hub's shared reference); (2) schema layer → in-bundle `spec/` concepts written by `kb-init`; (3) trust model → the full opinionated OKF-native-agent trust model. Build starts: `kb` hub → `kb-init` → `kb-ingest` → `kb-query` → `kb-lint` → `kb-visualize`.

**Creation** — Filed [Skill Design — the kb-* family](./design/skill_design.md): the build plan, designed with the `writing-great-skills` framework. Decided `kb-` naming ("knowledge bundle," OKF's own term; no user-facing "okf"), a `kb` hub skill (router + single source of truth holding the vendored spec/glossary/trust-model/templates/example bundle), and the invocation split — model-invoke only the daily verbs (`kb-ingest`, `kb-query`) + the hub; user-invoke the deliberate ones (`kb-init`, `kb-lint`, `kb-visualize`, `kb-search`) → three descriptions in context, not seven. Records leading words, the ingest premature-completion guard, build-vs-reuse, build order, and the three open decisions (distribution, schema-layer location, trust-model strictness).

**Update** — Audited `references/` for source-vs-synthesis (per §8 + #91). Found two pages that were *our analysis*, not source material, mis-typed as `Reference`: moved them to a new **`design/`** section and retyped to `Concept` — `references/okf_spec_evolution.md` → [design/spec_evolution.md](./design/spec_evolution.md), `references/okf_sample_bundles.md` → [design/sample_bundle_lessons.md](./design/sample_bundle_lessons.md) (dropped their `resource:`, since a synthesis concept isn't *bound to* the asset it cites). `references/` is now pure source pointers; `design/` holds our format/build analysis; `ecosystem/` holds analysis of other projects. Fixed all inbound/outbound links and added [design/index.md](./design/index.md).

**Update** — Read the full SPEC.md end-to-end (previously worked from a fetch-summary) and reviewed [discussion #91](https://github.com/GoogleCloudPlatform/knowledge-catalog/discussions/91) on references. Corrected a gap in [citations](./spec/citations.md): §8 explicitly allows citations to point into a `references/` subdirectory that mirrors external material as first-class concepts, and #91's canonical-source-vs-derived-text discipline. Documented both there and in [OKF Spec Evolution §6](./design/spec_evolution.md#6-keeping-source-material-in-the-bundle-8--discussion-91). Confirms the infographic's `references/` placement is spec-backed, not a stylistic choice.

**Ingest** — Added a two-panel "OKF vs. RAG" infographic as a marketing/explainer asset. Stored both images under `assets/images/` (immutable), created [OKF vs. RAG infographic](./references/okf_vs_rag_infographic.md) with descriptive alt text and honest *unverified-source* provenance, and cross-linked it from [RAG vs. LLM Wiki](./concepts/rag_vs_llm_wiki.md). **Source unverified** (social-media capture) — confirm rights/attribution before public use.

**Update** — Converted the entire bundle from absolute (`/…`) to **relative** cross-links (473 links across 51 files) so it renders correctly on GitHub and for any non-OKF-aware reader, aligning with the reference agent and sample bundles (see [OKF Spec Evolution §1](./design/spec_evolution.md#1-link-form-is-being-reversed-recommend-relative-not-absolute)). Rewrote [cross-linking](./spec/cross_linking.md) §5.1/§5.2 to present relative as the practical recommendation, and recorded the resolved/pending decisions (trust-model field names, README/LICENSE tolerance) in the spec-evolution page.

**Creation** — Bootstrapped the bundle. Created the root [index](./index.md) and this log.

**Creation** — Wrote the [concepts](./concepts/index.md) section: LLM Wiki, three-layer architecture, compounding artifact, progressive disclosure, RAG comparison, Memex, knowledge bundle, concept document.

**Creation** — Wrote the [spec](./spec/index.md) section: one concept per OKF v0.1 spec section (motivation, terminology, bundle structure, reserved filenames, frontmatter, body, cross-linking, index files, log files, citations, conformance, versioning).

**Creation** — Wrote the [operations](./operations/index.md) section (ingest, query, lint), the [implementations](./implementations/index.md) section (a personal work wiki, an OKF-native agent), and the [references](./references/index.md) section (OKF spec, OKF README, Karpathy gist, qmd).

**Creation** — Added the [ecosystem](./ecosystem/index.md) section, synthesized from the ~900 comments on Karpathy's gist: a [landscape](./ecosystem/landscape.md) survey of 200+ projects, a [critiques](./ecosystem/critiques.md) page (truth maintenance, token cost, markdown-vs-database), and six featured projects (OmegaWiki, karpathy-llm-wiki, wiki-skills, okf-harness, synthadoc, commonplace).

**Creation** — Added [OKF Sample Bundles](./design/sample_bundle_lessons.md) reference, capturing design lessons from Google's ga4/stackoverflow/crypto_bitcoin bundles (minimal per-directory indexes, no log.md in generated snapshots, relative links, non-atomic concepts).

**Creation** — Added three OKF-native competitors/peers to the ecosystem: [okf-skills (scaccogatto)](./ecosystem/okf_skills_scaccogatto.md) — our closest competitor; [openknowledge (openknowledge-sh)](./ecosystem/openknowledge_cli.md) — Go CLI + registry + viewer; and [kiso (oak-invest)](./ecosystem/kiso.md) — a Java bundle publisher. Updated the landscape's "where OKF sits" analysis: the native cohort is real and our differentiator must be the maintenance loop + portability seam, not another author/validate/visualize toolkit.

**Creation** — Filed [Competitor Comparison](./ecosystem/competitor_comparison.md): a feature-by-feature analysis of okf-skills vs. openknowledge vs. our plan, based on reading their actual SKILL.md files, templates, and validation code. Conclusion: reuse their deterministic validation + visualization/export; differentiate on raw-source ingest, the trust model, and the schema-layer portability seam. Proposed a three-skill scope (okf-init, okf-ingest, okf-lint).

**Creation** — Filed [OKF Spec Evolution](./design/spec_evolution.md) from reviewing the open PRs on knowledge-catalog. Key findings: link form is being reversed (relative recommended over absolute, PR #165 — flags an open decision for this bundle); only `type` is truly required (#145/#161, validates our checker); a trust/provenance axis is emerging (#58 §12 trust&safety, #159 `reliability`, #50 `sources`) that aligns with our differentiator and may standardize field names; hand-authored domain bundles with per-bundle `spec/` files are being legitimized (#144 cricket), validating our schema-layer approach. Added an in-flux note to [cross-linking](./spec/cross_linking.md).
