Required context & the Open Knowledge Format¶

RAC — Required Available Context — is how a conditional agentic loop declares the knowledge that must exist before agents run: always a description of that knowledge (an LLM wiki, a Terraform-described architecture, an API spec), never the content itself — a rule the Open Knowledge Format states as its own central premise, which is why the two compose cleanly.

The data model is $defs.racItem in schemas/cal.schema.json; the enforcement and the readiness checklist live in src/cal.mjs.

What a RAC item is¶

A CAL connects multiple cartridges into a process, and its tasks assume things about the world: there is a wiki describing this codebase, the infrastructure is described by Terraform, the warehouse schema is documented somewhere. A RAC item makes each assumption explicit, checkable, and portable:

{
  "id": "infra-arch",
  "kind": "terraform",
  "required": true,
  "description": "Terraform modules describing the network + IAM architecture (structure only, not the .tf contents).",
  "check": { "type": "file-glob", "hint": "infra/**/*.tf" }
}

(from the shipped sample, registry/cals/io.github.lboel/ship-a-feature/1.0.0.cal.json)

There is deliberately no content field — the schema forbids one outright:

"not": { "required": ["content"] }

and the linter in src/cal.mjs enforces the same invariant at validation time:

if ('content' in r) issues.push(`rac ${r.id} MUST NOT carry content — description only`)

RAC kinds¶

Check types¶

The check object says how a host (or a human) confirms the described knowledge is actually available. It verifies presence, not content:

Why descriptions only¶

Three reasons, each load-bearing:

1. Portability. A CAL that embedded a wiki dump or .tf files would only be valid for one repo at one moment. A CAL that describes the required knowledge ("Terraform describing the network + IAM architecture") is reusable across any environment that can satisfy the check.
2. Safety / no data exfiltration. RAC items travel inside CAL files and alongside cartridges designed to be shared. Descriptions of infrastructure can travel; the infrastructure code itself cannot. This is the same posture as the memory partition's fail-closed scrub gate: the export path refuses to ship secrets, and the RAC schema refuses to even have a place to put them.
3. The open-envelope principle. The standard keeps the descriptive layer fully open while protected knowledge remains in its authoritative environment (SPEC §1, goal 5). RAC sits squarely in that descriptive layer: reading a CAL tells you what knowledge a process needs without leaking what anyone knows. ACX does not define payment or entitlement semantics.

The same boundary, drawn as a picture:

flowchart LR
    subgraph CAL["CAL file (shareable)"]
        R["RAC item<br/>description + check + okf<br/>(no content — schema-forbidden)"]
    end
    subgraph ENV["Your environment (stays home)"]
        W["the actual wiki"]
        T["the actual .tf files"]
        S["the actual schema doc"]
    end
    R -. "check: mcp-resource" .-> W
    R -. "check: file-glob" .-> T
    R -. "check: manual" .-> S

RAC vs transferable memory¶

RAC and the memory partition answer complementary questions:

An agent's field-learned, repo-specific memory (portable: false) is quarantined behind a fingerprint match and stripped on ROM export — which is exactly why RAC exists: the repo-specific knowledge a process depends on cannot ride along in the cartridge, so the CAL declares it as required external context instead.

The readiness checklist, live¶

acx workflow ready validates the structure, resolves participants, and prints the RAC checklist. The checklist shape from the shipped sample looks like this (acx cal is the compatibility alias; the final readiness verdict depends on the receiving roster's resolved proofs):

$ node --experimental-sqlite src/cli.mjs cal \
    registry/cals/io.github.lboel/ship-a-feature/1.0.0.cal.json \
    --cartridges registry/cartridges
CAL: Ship a data-pipeline feature  (5 nodes, 3 participants)
...
Required Available Context (RAC — descriptions only, confirm before running):
  □ infra-arch       [terraform] Terraform modules describing the network + IAM architecture (structure only, not the .tf contents).  (check: file-glob infra/**/*.tf)
  □ code-wiki        [wiki] An LLM-readable wiki / knowledge map of the codebase: modules, data flows, conventions.  (check: mcp-resource wiki://project/overview)
  · warehouse-schema [api-spec] A description of the target Snowflake warehouse schema (table names + grains, not the data).  (check: manual confirm the DE team shared the schema doc)

□ marks required items; · marks optional ones (required: false). Tasks reference these by id (requires: {rac: ["infra-arch", "code-wiki"]}), and edge conditions can branch on availability with the structured condition {"racAvailable": "warehouse-schema"} — no expression eval anywhere. The full node/edge/participant model is on the conditional agentic loops page.

The Open Knowledge Format¶

The Open Knowledge Format (OKF) is an open, vendor-neutral specification (v0.1, published by Google Cloud in the GoogleCloudPlatform/knowledge-catalog repo) for the exact problem RAC dances around: organizational knowledge — schemas, metric definitions, runbooks, deprecation notices — scattered across catalogs, wikis, and heads, unreachable by agents. Its design principles are "just markdown, just files, just YAML frontmatter": no SDK, no account, no backend.

OKF v0.1 in brief:

• A Knowledge Bundle is "a self-contained, hierarchical collection of knowledge documents" — a directory tree of markdown files, the unit of distribution.
• A Concept is one unit of knowledge, one markdown document; its Concept ID is the file's bundle-relative path minus .md — path = identity.
• Reserved filenames: index.md (a per-directory listing enabling progressive disclosure — agents navigate one level at a time) and log.md (chronological update history).
• Frontmatter: type is required (a short non-empty string; conformance = every non-reserved .md has valid frontmatter with a non-empty type); title, description, resource (URI of the underlying asset), tags, timestamp are optional.
• Concepts cross-link with ordinary markdown links; consumers must tolerate broken links. The links form a knowledge graph.

The rac.okf field¶

Every RAC item may carry an okf object — in the current schema a free-form object documented as an "optional Open Knowledge Format descriptor of the required knowledge artifact (metadata only)". The natural convention is to mirror OKF frontmatter, in one of two shapes:

{
  "id": "code-wiki",
  "kind": "wiki",
  "description": "An LLM-readable wiki / knowledge map of the codebase.",
  "check": { "type": "mcp-resource", "hint": "wiki://project/overview" },
  "okf": {
    "type": "Code Wiki",
    "title": "Project knowledge map",
    "description": "LLM-readable knowledge map of the codebase",
    "tags": ["codebase"]
  }
}

{
  "id": "warehouse-schema",
  "kind": "api-spec",
  "description": "Description of the target warehouse schema.",
  "okf": {
    "bundle": "https://github.com/acme/data-wiki",
    "concept": "warehouse/orders"
  }
}

The RAC description stays authoritative for the CAL; okf.description is the interoperable copy for OKF tooling. And because an OKF descriptor is metadata-only by definition, attaching one can never violate the no-content rule — the schema's not: {required: ["content"]} applies to the item regardless.

Suggested kind → okf.type mapping:

Where OKF meets acx init --from-code¶

LangChain's OpenWiki is an open-source CLI that generates and maintains an LLM-readable wiki for a codebase; version 0.2 adopted OKF as its output convention — frontmatter on every page, generated per-directory index.md summaries, a changelog. The stated benefit is that OKF's hierarchy and index files make large wikis navigable by agents while reducing token consumption.

acx init --from-code (see generating an agent set) sits on the other side of the same handshake. It analyzes a codebase — heuristically, with no LLM involved (package.json dependencies, *.tf files, Dockerfile/CI, test layout, python markers, SECURITY.md) — and generates an agent set, a CAL, and RAC items describing the code knowledge the loop will need. Dogfooded on this very repository:

$ node --experimental-sqlite src/cli.mjs init --from-code . --out /tmp/agentset
Analyzed .
Generated an agent set in /tmp/agentset:
  • backend_dev      caps=implement-feature  (node package.json present)
  • devops_engineer  caps=deploy  (Dockerfile / CI workflows)
  • qa_engineer      caps=test-authoring  (test files/dir)
Required Available Context (descriptions only):
  □ code-wiki      [wiki] An LLM-readable knowledge map / wiki of the codebase: modules, data flows, conventions (structure only).

That code-wiki RAC item describes precisely the artifact OpenWiki produces. The division of labor:

flowchart LR
    OW["OpenWiki (LangChain)<br/>generates the knowledge<br/>as an OKF bundle"] --> B["OKF bundle<br/>(markdown + frontmatter<br/>+ index.md)"]
    AI["acx init --from-code<br/>declares the knowledge<br/>as a RAC item"] --> RI["rac: code-wiki<br/>description + check"]
    RI -. "check confirms" .-> B
    RI --> CAL["CAL readiness verdict<br/>(acx workflow ready)"]

One tool produces codebase knowledge in an open format; the other declares and verifies that such knowledge is required and present. Neither ships the knowledge inside the process definition — both formats forbid it by design.

Cartridge knowledge as an OKF bundle¶

A cartridge's transferable memory records already carry OKF-shaped metadata — title, summary, tags, timestamp, sourceType (see memory). Mapping them to an OKF bundle is mechanical: one concept file per portable: true record (frontmatter type from sourceType, description from summary), index.md per topic group, log.md from the record timeline — while portable: false records stay out, exactly as the memory partition's quarantine rule already demands. No such acx export --okf command exists today; the point is that the two formats' invariants compose without friction, because both were built on describe, don't ship.

Related pages¶

• Conditional agentic loops — the full CAL model that RAC items live in: participants, nodes, structured conditions, the per-cartridge skill set.
• Generating an agent set from code — acx init and --from-code end to end.
• Memory partition — transferable vs field-learned memory, the scrub gate, the fingerprint.
• Capabilities — the open descriptive layer and independently verified evidence that RAC's placement follows.