Specification, v1

schema_version in every document, /v1/ in every path. Breaking changes only in a new major, and the previous major stays available for at least twelve months.

Machine-readable

• schema.json — profiles P0 and P1
• /v1/index.json — the catalog index
• agent.txt — what a client must do before running anything

Normative documents

• Machine contract, v1 — The catalog is a set of static artifacts (§10). There is no service to query and no database behind it, which is what makes the whole catalog rebuildable from Git with one command — and what shapes the contract below.
• Attestations — T3 exists so that trust can rise above what the catalog can check statically without the catalog owning a runner. That only works if somebody who is not us can issue a claim we can verify — which makes this format the load-bearing part…
• Derivative works and licensing — Content comes from public repositories. What arrives is P0 — prose with frontmatter, which is browsable and impossible to run. Everything that makes a procedure runnable happens when it is lifted to P1, and a lifted procedure is a…
• Error codes — Every message this catalog produces carries a code. §18.7 lets the message itself stay short — name the location, name the fix — because the code resolves here, where the rule is explained. A code with no entry would make that a promise…
• Execution contract, v1 — P0/P1/P2 say how much structure a document has. R0/R1/R2 say how much of this contract a client enforces. They are independent axes, and the catalog should be able to say so: a perfect P2 document read by an R0 client is unsupervised.
• Graph model, v1 — A runbook's graph is the structural projection of profile P1. It has three consumers — the linter, the renderer and the editor — and exactly one definition, here. Graph invariants are the structural half of T1/T2 (§8): the same rules…
• Identifiers, references and URLs — URLs are the most permanent thing this project ships. Agent pins point at them, external documentation links to them, indexes cache them. Everything else can be rewritten; these cannot.
• Injected-instruction detection — Published because it has to be. §19 refuses a safety score whose methodology is not published, on the grounds that a rating nobody can check is a rating nobody should believe. The same standard applies to our own detector: a publisher who…
• P1 → Open Workflow DSL, v1 — Without this mapping the catalog is a format island (§5). The mapping is what makes "implementable on any engine" checkable rather than rhetorical.
• Publishers and namespaces — A namespace is the unit of provenance. Verification, reputation and takedown all attach to it, and a registry without that is a supply-chain compromise waiting to happen (AST02).
• Relations between runbooks — A procedure rarely stands alone: one prepares another, one undoes another, one is where a third hands off, one is a step of something larger. These four edges are how a record says so, and the graph stops being intra-runbook and becomes a…
• Run reports — A run report is what a supervised run (§13.3, profile R2) leaves behind. It is an optional extension of this specification: the catalog does not depend on receiving any, anyone may collect them, and our collector is a reference rather than…
• Record signing and tier S — content_hash proves a record has not changed since the catalog fetched it. It does not say who published it, and it cannot: an attacker who can get a record into the catalog can get a consistent hash for it as well. A signature is the…
• Trust ladder, v1 — A level is computed, never assigned. Every one is a predicate over evidence a third party could recompute. The moment a level can be set by hand, the badge means nothing — and §19's argument against unexplained safety scores would apply to…
• Facet vocabularies and how they change — A facet exists only if people filter by it, or if it affects execution safety. That is the whole defence against schema bloat, and without a process attached it is an opinion in a document.