The three faces of a capability, from the authoring screen
Semantics, contract and policy are three separate decisions on one form — here's what each one actually controls, and why the contract is frozen the moment it publishes.
A capability's authoring form asks for three things, and they're kept visually and structurally separate because they answer three different questions and change on three different schedules.
Face 1 — semantics: what the model reads
This is the summary, "use when," "do not use when," and disambiguation text. It's prompt engineering stored as data rather than code, and it's genuinely revisable after publication — a summary that quietly misleads the model is a defect, and one that could only be fixed by cutting a whole new version would simply never get fixed.
Synonyms here are tri-state, not a simple list: leaving the box untouched on an edit leaves the stored trigger phrases alone; opening it and clearing it removes them all. Retrieval tuning means removing an over-broad synonym at least as often as adding a new one, so the form has to be able to say "leave it" and "clear it" as two different requests.
Face 2 — contract: what's asked for, what's promised back
This is frozen the moment the capability is first declared, and there's no separate contract editor on the revision screen — deliberately. Every prompt, eval, flow, rule and portal block written against this capability depends on that exact shape. Moving it later breaks everything downstream of it at once.
The editor itself is a table — field name, type, required, description — because that's the real decision an author is making: what does the resident have to tell us, and what do we promise to answer with. The description column matters more than it looks: it's the sentence the model reads about that argument. A raw JSON Schema editor is one click away for anything the table can't express (a nested object, oneOf, a $ref), and it opens automatically if your schema already uses one of those.
Policy — the floor every binding inherits
- Required assurance (A0 through A4) — a tenant's binding may raise this, never lower it.
- Sensitivity / data class — from Public up through SpecialCategory — decides retention, caching and who on staff may ever see the value.
- Entitlement — an optional named check beyond identity alone.
- Cache TTL and cache key fields — left blank, nothing here is cached.
- Requires confirmation and idempotency window — for a Write capability these aren't switches you choose; the aggregate forces confirmation on, and the form says so rather than pretending it's optional.
Edit the semantics from a published capability's own detail screen, not from the original creation form — that's the "revise" path, and it's the only one available once the contract has shipped.