Register a capability — the admin runbook

Step by step, in verbs: take a capability from nothing to agent-ready, whether it comes from a provider like fal or from a community orchestrator. Only the first step differs by source; everything after it is identical.

This is the task guide. For why each stage exists and what "done" means, read Onboard a capability — the six stages.

The shape of it

  step 1   register            ← the ONLY step that differs by source
  step 2   price               cap_price
  step 3   make discoverable   cap_route          ← the step people skip
  step 4   document            cap_docs
  step 5   measure             cap_probe
  step 6   promote             cap_promote        ← optional; explicit-name is a valid ship

  at any point: cap_status  →  which stage is open, and the exact next action

cap_status({ capability: "<name>" })

The one-call version

If you would rather not walk the steps, cap_plan returns the whole work order in a single call — the six-stage audit, the collision check, the price at the house margin, the drafted docs, and the probe step, each tagged with who does it:

cap_plan({ capability: "minimax-music-3", model_id: "minimax/music-3",
           upstream_usd: 0.002, unit: "second" })

minimax-music-3 — onboarding plan (provider)
current: NOT_STARTED — not registered anywhere

•  1. 1 · register       [off-platform] add model id "minimax/music-3" to the provider node's
                         capability config and restart the adapter…
•  3. 2 · price          [repo] upstream_usd 0.002 per second → ships at $0.0021/second (+5%)
✗  4. 3 · discoverable   [repo] NAME COLLISION — resolves to "minimax-h3-i2v". Registering the
                         name alone will NOT fix this…
•  7. 6 · measure        [verb] cap_probe({ …, n: 5, confirm: true })
✗  8. gate · promote     [verb] refuses until every stage above is clear

2 blocked, 6 ready to do. Clear the blocked ones first.

verbyou can run it from here   repoa file you edit and review in a diff   off-platforma change on the provider node

It composes cap_status, cap_route, cap_price and cap_docs rather than re-deriving them, so it cannot tell you something those verbs would contradict. It does not fetch the provider's page — pass the facts you read — and it does not call orch_onboard; it names it, because that verb is admin-gated.

What to say

You do not type verb names. Say the outcome; the agent picks the verb. This is the whole vocabulary:

Two worked sessions

You do not call these verbs by name. You say what you want in an admin MCP session and the agent picks them — the value of knowing the verbs is being able to check that it picked the right ones, and to read what comes back. Both sessions below are real: the routing findings are what these names actually resolve to today.

Session A — a new provider model

Someone posts that MiniMax Music 3 is on fal: complete songs up to five minutes, holding theme and vocal identity across the whole length.

Session B — a community orchestrator

An operator says their runners are healthy on an RTX 5080 and visible through /discovery, offering realesrgan-x4plus-upscale (wire app realesrgan-upscale) and whisper-large-v3-asr.

Step 1 — register

The one step with two tracks. Both end with the capability existing; neither makes it reachable by name yet.

orch_onboard({
  discovery_url: "https://their-node:8935/discovery",
  contact_email: "them@example.org",
  network: "arbitrum-one-mainnet"
})

Verify: the capability appears on /capabilities with a display price. Then cap_status — stage 1 should be ✓.

Step 2 — price it

cap_price({ capability: "<name>" })
cap_price({ capability: "<name>", params: { duration: 30, resolution: "720p" } })

The first call audits: is there a verified cost basis, and does the shipped price equal that basis at the house margin? The second quotes a specific request through the same estimator create_media uses, so you see what a real job costs — tiers, per-call add-ons, minimum billed quantity and all.

Step 3 — make it discoverable the step people skip

This is where a registered capability becomes one the agent can actually route to. Check it before you believe it:

cap_route({ query: "<name>" })

You are looking for “resolves to itself”. Anything else means a caller naming this capability is served something else:

The fix is four small edits, and it is the same four every time:

1. add the name to FALLBACK_CAPABILITIES and CAPABILITY_KIND;
2. add an explicit resolver guard before prefix matching — without it the absorption comes straight back;
3. declare its INPUT_REQUIREMENTS;
4. update the resolution golden so the change is reviewable in a diff.

Also give it a latency prior and a timeout entry. A capability with a prior and no timeout gets cut off at the default and billed — see the ceiling note at the bottom.

Verify: cap_route says SAFE, and cap_status stage 3 is ✓.

Step 4 — document it

cap_docs({ capability: "<name>" })

Returns a skill and a playbook as content, not files — the derivable facts (kind, price, tiers, add-ons, input, chain, measured latency) already filled in, with TODOs everywhere judgement is needed. Fill those in and commit them.

The three TODOs are the only parts worth reading, and none can be generated:

• What it uniquely does. If you cannot finish that sentence, it may not need its own skill — it may need a line in an existing one.
• What it cannot do. This earns more trust than the first one. Name the neighbour that is the better answer.
• Where the provider's docs are wrong. Check before deciding nothing surprised you — a parameter the schema rejects though the pricing page sells it, an option that returns extra assets free.

The playbook must compose: a brief that calls one capability and stops is a model card. Show it working with a finishing or export step. The showcase needs real rendered media — no placeholders.

Step 5 — measure it

cap_probe({ capability: "<name>", inputs: { /* cheapest legal settings */ } })        // plan only
cap_probe({ capability: "<name>", inputs: { … }, n: 5, confirm: true })              // renders

Without confirm you get the plan and the estimated total and nothing renders. With it, up to 5 real renders, each reserving against the same 24h spend cap create_media uses before dispatching.

Probe at the cheapest settings that still exercise the real path — lowest resolution, shortest legal duration. The point is the contract and the latency, not the picture.

It prints the SLA, timeout and measured-p95 values to paste. It does not write them: those tables are read on every dispatch, and one bad sample must not re-time the fleet. Size the timeout from the maximum duration the capability accepts, not from the probe you happened to run.

Then write the smoke report, including what you did not measure.

Step 6 — promote it (optional)

cap_promote({ capability: "<name>" })                  // dry run
cap_promote({ capability: "<name>", confirm: true })    // records it

Promotion moves a capability from reachable by explicit name to chosen for users — intent keywords, fallback chains, tier defaults. It requires all six stages clear and ≥4 successful runs at ≥80%.

A refusal is the normal answer for something new, and is not an error: it names the missing stage or the sample count. NAME_ONLY is a legitimate shipped state — the capability is usable, documented and priced; it simply is not picked automatically yet.

It records the decision and prints the routing-table edits rather than making them. Those tables are reviewed in a diff.

Keeping it working

Auditing what is already onboarded

The same two read-only verbs, in a loop, over an orchestrator's capability list. Two minutes per orchestrator, no renders:

orch_get({ id: "<orchestrator>" })            // → its capability names
cap_status({ capability: "<each>" })          // → which stages are open
cap_route({ query: "<each>" })                // → is it silently absorbed?

That is exactly how the 8-of-9 finding surfaced. If you onboard an orchestrator, audit it the same day.

Done means

cap_status returns COMPLETE, CI is green, and it is deployed. Anything less is NAME_ONLY — shippable, honestly labelled, and not yet chosen automatically.