STEP 9 OF 10

Governance: The Rule Book

/gateway → Rules is where a tenant's Constitution lives — the versioned Articles and Statutes that the Action Gateway checks every agent-originated action against. Every tenant starts on a platform default. This guide covers replacing it with your own policy, from an actual PDF.

Two ways to start

A tenant with no ratified rules of its own sees two cards: Upload your policy PDF and Start from platform rules (the seeded default that already governs every tenant until you ratify your own). Uploading is what this guide walks through.

curl -X POST "https://your-control-plane-host/api/v1/rule-book/import-pdf" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@your-ai-usage-policy.pdf"

Only PDFs are accepted, and there's a hard size limit — both rejected with a clear 422/413, not a silent truncation.

What happens to the PDF

The real text is extracted from the document (not an LLM's paraphrase of what a policy PDF "probably says") and a bounded tool-calling loop proposes Articles and Statutes grounded in it. The grounding is checked, not assumed: every proposed statute's source_excerpt has to be a real, verbatim substring of the extracted text. A proposal that paraphrases instead of quoting is rejected mid-loop and the model is asked to try again — you'll never see a rule in the draft whose "quote" isn't actually in your document.

The result lands as a new draft ConstitutionVersion — nothing governs anything yet. The platform default (or your previous ratified version) keeps governing until you explicitly ratify the draft.

Reviewing the draft

Each proposed statute shows its plain-language body, an enforcement kind badge, and the source excerpt it was drawn from as a quote you can check against the PDF yourself. Five enforcement kinds exist, and each means something different once ratified:

• authority — materializes a real AuthorityMatrix row for the mapped action kind; the next matching action goes through this rule at the gateway
• budget — adjusts the tenant's real GatewayBudget cap
• guardrail — wires into an agent's AgentGuardrails (tool allowlist, PII redaction, etc.)
• autonomy — wires into AutonomyGrant
• advisory — text only, recorded and shown, nothing blocks on it

You can edit a statute's body or enforcement kind before ratifying, or remove one the synthesis got wrong:

curl -X PUT "https://your-control-plane-host/api/v1/rule-book/versions/{version_id}/statutes/{statute_id}" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"body": "No agent may export customer data to a destination outside approved storage.", "enforcement_kind": "authority"}'

curl -X DELETE "https://your-control-plane-host/api/v1/rule-book/versions/{version_id}/statutes/{statute_id}" \
  -H "Authorization: Bearer $TOKEN"

Once ratified, a statute is immutable — editing after that point is rejected; a correction means importing or drafting a new version that supersedes it.

Ratifying

curl -X POST "https://your-control-plane-host/api/v1/rule-book/versions/{version_id}/ratify" \
  -H "Authorization: Bearer $TOKEN"

This signs the version, marks it RATIFIED, and marks whatever was active before as superseded. authority/budget/guardrail/autonomy statutes materialize into their real tables in the same call — this is the point where the rule starts actually being enforced, not just displayed. The data-plane runtime picks up the new Constitution on its next sync.

The effect shows up immediately in two places: a matching action that previously came back pending (no rule to check it against) now comes back denied (or requires_approval), citing the statute by number; and the statute appears in the relevant agent's Boundaries tab with enforced_at: gateway, linking to the run step where it fired.

Reading a ratified Constitution

By default the Rules tab renders plain language — the body text, no hashes, no version IDs. Engineer mode is an explicit toggle that adds the technical detail back: signed_hash, source_excerpt, version metadata. Most reviewers never need it; it's there for anyone auditing the chain of custody from PDF to enforced rule.

What's next

Step 10 — Python SDK: the last stop in this track — scripting everything covered so far, agents included, from code instead of the dashboard.