Reference Data¶

Licensed commands. Every CortexBuild command except auth and the host-invoked hook requires a valid licence. If you see license required, run cortexbuild auth activate --key <token> (or cortexbuild auth refresh if a lease simply lapsed) and try again. --help always works.

Rules are prose: policies, conventions, the things an agent needs to follow. Some of the most valuable knowledge a team has is not prose at all — it is machine-generated: a database schema dump, a GraphQL catalogue, an OpenAPI inventory, an architecture or service-dependency reference regenerated straight from a live system. That kind of artefact does not belong inside a rule. Inlining a few-hundred-kilobyte schema dump into every rule file would bloat every rendered surface — CLAUDE.md, AGENTS.md, .github/copilot-instructions.md — which is on the wire on every turn of every governed session.

Until now, CortexBuild had no concept for this at all. A rule could point at a catalogue with a sentence of prose, but the catalogue itself was untracked, unversioned, and never checked for drift. The reference-data registry gives it a governed home, without ever inlining the content anywhere.

The concept¶

A reference entry is a declared pointer to a file already in your repo:

Field	Meaning
`id`	Stable slug (kebab-case)
`path`	Repo-relative path to the artefact
`kind`	`schema` \| `api` \| `catalogue` \| `architecture` \| `other`
`description`	One line: what it is
`generated_by`	Free text: what produced it (a tool, a script, a query)
`regenerate`	Optional: the exact command that regenerates it
`max_age_days`	Optional: report stale once the file is older than this

Entries live in .cortexbuild/reference.yaml, which is committed — it is the declaration, not the data. The artefacts it points at stay wherever your repo already keeps them; CortexBuild never copies or inlines their content.

This generalises the provenance/staleness model that shipped for the code graph's GRAPH_REPORT.md: a generated artefact is only useful to an agent if the agent can also tell whether it is still trustworthy.

Managing the registry¶

# Register an artefact you already have
cortexbuild reference add docs/reference/pg-schema.sql \
  --id pg-schema \
  --kind schema \
  --description "Live PostgreSQL schema dump" \
  --generated-by "pg_dump --schema-only" \
  --regenerate "scripts/dump-schema.sh" \
  --max-age-days 14

# See what is registered
cortexbuild reference list

# Check freshness
cortexbuild reference check

reference check stamps each entry's content hash, size, and mtime into a local, gitignored cache (.cortexbuild/reference-state.json) and reports one of three outcomes per entry:

fresh — matches the last-recorded check (and, if declared, within max_age_days).
stale — either it has never been checked before, its content changed since the last check, or it is older than its own max_age_days.
missing — the declared path does not exist on disk.

Exit codes follow the same three-way split: 0 when every entry is fresh, 1 when any entry is stale or missing, 2 when an entry could not be checked at all (for example, a permissions error).

What agents see¶

Once the registry has at least one entry, every rendered instruction surface (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, .cortexbuild/INSTRUCTIONS.md, …) gains a short "Reference data" section: id, kind, path, description, and freshness as of the last render. The content of the artefact itself is never inlined — an agent is told to open the file when its task touches that area, and to run cortexbuild reference check if the section reports an entry stale. A repo that has never declared a registry renders exactly as it did before — the section only appears once something is registered.

cortexbuild doctor reports a stale or missing entry as a decision-needing governance state, naming the regenerate command when the entry declared one.

Workflow¶

cortexbuild reference add <path> --id ... --kind ... --description ... for each generated catalogue you want agents to know about.
cortexbuild render so the new entry reaches every tool surface.
Whenever the underlying system changes, regenerate the artefact and run cortexbuild reference check to re-stamp its baseline. Wire this into whatever already regenerates the artefact (a cron job, a CI step, a pre-commit hook) so staleness never silently drifts.

See also Adopt Your Own Governance for how this fits alongside rules, skills, and agents you bring in from an existing homegrown setup.