Bundle doctrine — owner interim notes (provenance)

Point-in-time provenance document. These are the owner’s original framing notes, written ahead of the 2026-07-16 doctrine session (moved here from canonical’s gitignored scratch surface, where this was the only copy). Every question below was resolved by the ratified bundle-doctrine and the bl-465 research closure — read that first; this file records what prompted it.

Background

There was a comment towards the end of a prior session, related to the example approach on the Google repo which was that their “index generator (bundle/index.py) groups sections mechanically by frontmatter type, alphabetically, with recursive per-directory indexes - grouping is derived from the data, never configured” - which I believe was followed by a comment that this isn’t what we’re doing currently.
Another comment was “canonical-okf-platform is the deployment showcase bundle, not system knowledge” but in the same session it was noted that this is the approach which all three google examples take i.e., system knowledge is intertwined with domain knowledge.
As OKF is a new framework, we need to ensure that we’re getting this right, and now is the cheapest time to do so.

Additional information

I’ve completed some investigation and found a useful website which expands on the okf concept (https://okf.md/spec/), and also provides some further examples (https://okf.md/examples/), which I believe are useful as they’re outcome-based, which is potentially something we haven’t defined clearly enough for why we’re implementing OKF as part of the Canonical platform.
- The relevance of “outcome-based” here is that this was the big shift that id-71 (AI tooling audit and rework) started, in terms of working back from the outcome humans and agents need, and then building the platform and AI tooling to meet those needs. OKF bundles and concepts are a critical aspect of this, but were only recently introduced to the platform and so id-71 documentation was written without awareness of OKF, but it has rich context which is directly relevant to what we need to be doing with OKF.
  - I’ve identified four documents below which would likely be most valuable here, taken from the id-71 docs site spec folder:
    - lane-a-workflow-inventory-strawman.md
    - headless-requirement-refinement.md
    - RESEARCH.md
    - platform-agents-architecture.md
Along with the above OKF website, I’ve also re-reviewed the original OKF blog post (https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) - the entire post is of course valuable, but I’ve picked out some comments which I think are most relevant here and listed these below:
- “intended to be vendor-neutral, and to provide an agent- and human-friendly standard for representing the metadata, context, and curated knowledge that modern AI systems need.”
- “the information that foundation models use is overwhelmingly internal knowledge: the schema of a table, your business’ meaning of a metric, the runbook for an incident, the join paths between two systems, the deprecation notice for an old API, etc.”
- “Survives moving between systems, organizations, and tools”
- “give your agents a shared markdown library that grows more useful over time”
- “A bundle hand-authored by a human can be consumed by an AI agent. A bundle generated by a metadata export pipeline can be browsed in a visualizer. A bundle synthesized by one LLM can be queried by another. The format is the contract; the tooling at each end is independently swappable.”
- “whether you’re building a knowledge catalog, an enrichment pipeline, a wiki tailored to AI agents, or anything in the AI knowledge domain”
A lot of OKF examples refer to systems/codebases, and maybe this is an area that’s being conflated by us, for example, there’s a comment on the blog which is “Lives in version control alongside the code it describes”, but in the same blog, they reference writing producers for various sources e.g., database, documentation side, website, and so on. What may then make sense for us is understanding what the OKF bundles need to cover. Probably the most valauble document for helping to define this would be .lavish/corpus-reframe-review.html, especially the “Target model” section, and the following sentence: “the pipeline is a refinery that turns messy evidence into governed canon — and the gate lives at promotion.” i.e., the intention of Canonical is to be able to ingest data from various sources, and make it useable by humans and agents alike, across various application types. We can “point” okf producers at the client’s other systems - “the discovery agent hunting for concept-worthy data”, but we’ll also have connectors to other locations/systems - “Connect to source, pipeline extracts, business knowledge grows.”
- The entire Canonical “Platform” setup is entirely for us, to enable dogfooding, E2E, and promotion gating to clients, which is why the current data in the concept files is synthetic, but if I’ve understood correctly, what we personally would then have is the synthetic OKF setup (canonical-okf-platform) replicating a client organisation e.g., with synthetic business data, but also, for our own purposes, a separate setup which you and I will use when continuing to develop the platform - the crossover being that as client data is being stored in the system it’s a key OKF system of record source, which will need to be understood by humans and agents, and so there will presumably be a core set of concepts which will ship to each new client, existing on Platform and Client private git repos, but our personal OKF bundles for the system will grow separately to these - similar to the current docs-site, which is only used by you and I and is probably the next place we would point a bundle producer at, after the platform itself.
You’ll also see from id-132.39 that we’re investigating the UI surface for our OKF setup, and that one option is utilising Understand-Anything (https://github.com/Egonex-AI/Understand-Anything). Whilst the focus of id-132.39 was looking at UA from a UI perspective, I’m not sure if it was overlooked that running /Understand-Anything, when it’s connected to an LLM, to me at least, appears to output something akin to an OKF bundle shape - are we missing an easy trick here, especially given that the pilot already was able to adjust the setup to accommodate the OKF bundle shape.

Resolution map (added at ratification)

Note above	Resolution
Mechanical vs configured index grouping	Reconciled pre-session (bl-463 alignment check); open rider: type-grouped no-map default (unratified)
Showcase vs system knowledge	Bundle taxonomy — four classes; bl-465 closed `ready`
Outcome-based “why”	Why-OKF affordance statement in bundle-doctrine.md (id-71 A17/A19/A20/A21/A22)
Producers pointed at client systems	Path 1: connectors feed the PIPELINE (evidence), never the bundle directly
Core concept set shipping to clients	`canonical-okf-system` separate sibling bundle, prove→pin→promote
Personal/system bundle for platform dev	`canonical-okf-internal` (bl-478, parked)
UA “easy trick”	Rejected as producer except `/understand-knowledge` over docs at page grain (anchor = the page)