LLM Consumption Standard

This page is the contract for any LLM agent or code assistant that wants to consume the beef monorepo docs as a read-only source of truth. It is also the schema reference for the JSONL exports.

Quick start (30 seconds, fresh LLM session)

If connected to Foxy360 MCP, call foxy360_docs_search first.
Use foxy360_docs_get for full docs by doc_id.
Use foxy360_docs_resolve_glossary for overloaded terms.
Use foxy360_docs_manifest for checksums and corpus statistics.
If Foxy360 is unavailable, generate the local export with node scripts/docs-build-kb-export.mjs, then use the local tools/docs-mcp/ server or read the JSONL files directly from apps/sirloin/internal/app/foxy360/docskb/kb/.

For Claude Code teammates, prefer the MCP server at tools/docs-mcp/ (see its README for the .mcp.json fragment).

Export schema (v1)

All exports are produced by scripts/docs-build-kb-export.mjs. The schema version is in manifest.json#schema_version and on each chunk record (schema_version: 1).

`apps/sirloin/internal/app/foxy360/docskb/kb/index.jsonl` — one chunk per line

{
  "schema_version": 1,
  "doc_id":         "overview/docs-coverage",     // unique slug
  "doc_path":       "docs/src/content/docs/overview/docs-coverage.md",
  "doc_url":        "/overview/docs-coverage/",
  "title":          "Docs Coverage Tracker",
  "description":   "Current state of docs vs reality...",
  "domain":         "meta",                       // first of domains[]
  "domains":        ["meta", "docs"],
  "owner":          "@law",                       // or null, or "unassigned"
  "status":         "active",
  "stability":      "stable",                     // stable|aging|draft|deprecated|unknown
  "last_reviewed":  "2026-05-05",                 // YYYY-MM-DD
  "doc_type":       "tracker",
  "related_docs":   ["docs/.../docs-roadmap.md"],
  "chunk_id":       "overview/docs-coverage#0001",
  "chunk_index":    1,
  "chunk_total":    12,
  "section":        "Services (Phase 2)",         // H2 heading or null
  "body":           "...",                        // markdown text
  "code_refs":      [{"path": "apps/...", "line": 898}],
  "doc_code_refs":  [...],                        // union across all chunks of this doc
  "todos":          [{"owner": "@law", "tag": "law", "note": "..."}],
  "checksum":       "sha256:..."                  // body checksum
}

`apps/sirloin/internal/app/foxy360/docskb/kb/glossary.jsonl` — one term per line

{
  "term":       "Customer",
  "definition": "Chargebee-side billing identity. NOT the same as Clerk user...",
  "domain":     "Chargebee",                      // disambiguator from "## Term (Domain)" heading
  "owner":      null,
  "source":     "overview/glossary"
}

`apps/sirloin/internal/app/foxy360/docskb/kb/manifest.json` — corpus envelope

{
  "schema_version":      1,
  "generated_at":        "2026-05-05T17:39:00Z",
  "doc_count":           131,
  "chunk_count":         1101,
  "glossary_term_count": 38,
  "corpus_checksum":     "sha256:...",            // sha256 of sorted file paths + per-file sha256
  "index_checksum":      "sha256:...",            // sha256 of index.jsonl bytes
  "glossary_checksum":   "sha256:...",
  "manifest_checksum":   "sha256:...",
  "docs": [
    { "doc_id": "...", "doc_url": "...", "owner": "...", "todos": [...], "code_refs": [...] }
  ]
}

corpus_checksum and index_checksum are the load-bearing values for agents caching the export. Compare them on every fetch.

Refusal patterns

These are the rules the beef-docs Claude skill enforces. Other agents should follow the same patterns.

When to defer to a TODO(@owner)

If a chunk’s todos[] contains a marker with an owner set, the answer to that section requires human judgment. Quote the TODO and the owner; do not fabricate a resolution.

Q: How is the audit log persisted?
KB: docs/src/content/docs/overview/glossary.md#0008 contains
    TODO(@law): identify the audit-log persistence backend and retention.
A: This is an open question. The glossary tags @law as the owner;
   ping them or check apps/strip/internal/app/authorization/.

When to cite a path:line

If a claim about code reality is load-bearing (a function exists, a constant has a value, a bug reproduces in a specific file), cite path:line (or path:start-end). The citation linter (scripts/docs-check-citations.mjs) verifies these. Do not invent line numbers — re-read the file if unsure, or omit the line.

When to refuse

Refuse to answer if the question requires owner judgment that the docs explicitly defer:

Questions about post-incident decisions when the runbook says “escalate to oncall”.
Trade-off questions where the ADR did not pick a side.
Questions whose answer would change a security boundary, an SLA, or a customer commitment.

Refusal format:

This question is owned by <owner>. The relevant doc is <doc_url>; the
TODO/quote is "<text>". I won't guess.

Tag conventions (write side)

Authors of new docs:

Field	Required	Notes
`title`	Yes	Hard-failed by `frontmatter-check`.
`description`	Soft	Surfaces in the embedded KB export.
`owner`	Soft	Must be `@law`, `@pawel`, `@marty`, `@vlad`, `@zen`, or `unassigned`. Hard-failed if outside the allowlist. Forbidden: `@lawzava`, `@platowski`.
`status`	Soft	`active`, `draft`, `deprecated`, `superseded`, ADR-only `Proposed`/`Accepted`.
`stability`	Derived	Computed by the export from `status` + `last_reviewed`.
`last_reviewed`	Soft	`YYYY-MM-DD`. Drives `stability` (>90 days → `aging`).
`domains`	Soft	YAML list. First entry seeds `domain`.
`doc_type`	Soft	Free-form (`runbook`, `oncall`, `architecture`, `decision`, `tracker`, etc.).
`related_docs`	Soft	Repo-relative paths. Surfaces in chunk records.
`related_code`	Soft	Repo-relative paths (no line). Joined with body-extracted refs into `doc_code_refs`.

TODO(@owner) markers in the body are first-class — they propagate into chunk and doc records. Use TODO(verify) for bot-checkable claims; use TODO(@law|@pawel|@marty|@vlad|@zen) for owner-judgment items. Do not invent new tag forms.

CI gates

The new gates added by ADR 2026-05-05-llm-native-docs:

Gate	Script	What it does
`kb-export-build`	`scripts/docs-check-kb-sync.sh`	Builds the export in scratch and runs the KB smoke test.
`frontmatter-check`	`scripts/docs-check-frontmatter.mjs`	Fails on missing `title`, forbidden owner tags, unknown owner.
`citation-check`	`scripts/docs-check-citations.mjs`	Verifies every `path:line` and `path:start-end` cite resolves.

Run them locally:

node scripts/docs-build-kb-export.mjs   # generate the local export
bash  scripts/docs-check-kb-sync.sh     # verify generator output
node scripts/docs-check-frontmatter.mjs # validate frontmatter
node scripts/docs-check-citations.mjs   # verify path:line cites
node scripts/docs-kb-test.mjs           # round-trip TODO(@owner) smoke test

Versioning

Schema bumps follow this rule:

Additive (new optional field on chunk record, new field in manifest): no schema_version bump. Consumers ignore unknown fields.
Breaking (rename, retype, removal): bump schema_version and update this page in the same PR. The MCP server and the beef-docs skill must be updated atomically; the kb-export-build gate verifies the rebuilt export.

Embedded artifact only

The exports are generated into apps/sirloin/internal/app/foxy360/docskb/kb/ during Sirloin Docker builds and local make build/test targets, then embedded into the Foxy360 MCP binary. Do not publish the JSONL files to any third party — they may contain references to internal infrastructure, vendor names, or owner tags.