The Verb Spec

Manifest Format

Every verb is declared as a VerbRecord — a single JSON object that carries the verb's identity, schema, shape, and surface coverage.

{
  "name": "payments.preview_refund_impact",
  "description": "Project the impact of refunding a transaction WITHOUT executing it.",
  "shape": "preview",
  "side_effects": "read",
  "input_schema": {
    "type": "object",
    "properties": {
      "transaction_id": { "type": "integer", "minimum": 1 }
    },
    "required": ["transaction_id"]
  },
  "output_schema": { "$ref": "/schema/shapes/preview.json" },
  "surfaces": ["http", "mcp_stdio", "webmcp", "ucp", "cli"],
  "requires_consent": false,
  "tier_floor": "starter"
}

Field reference

Naming conventions

Dot-notation for agent-attraction verbs (the multi-transport surface): {domain}.{verb} — the domain groups verbs logically (crm, payments, inventory, infrastructure, deal, customer).

Snake_case for ADA dispatcher verbs (the typed-phrase / consent-gated surface) — charge_invoice, subscription_upgrade_tier. These are the verbs that require human confirmation; the snake_case name is what the LLM emits in its function call.

Both styles coexist in one registry. The ADA-to-manifest bridge auto-mirrors snake_case names into the unified registry so discovery surfaces see the full set.

Registration semantics

Manifest endpoint

The live manifest is public and needs no key to read:

GET /api/v1/agent/verbs?surface=mcp_stdio

Returns VerbRecords filtered by surface, cached for 5 minutes. New verbs appear within 5 minutes of a backend deploy — no client-side package republish.

Shapes

A shape is the response contract. An agent that knows the shape knows how to read the answer before it calls the verb.

Every verb declares one. The registry is the authority on which shapes exist and how many verbs carry each — the tiles above read it live. The table below describes what each shape gives an agent, which is the part that does not drift.

Transport Bindings

One registry, four projections. Adding a verb to the unified registry lights up all four transports automatically.

                    UNIFIED_VERB_REGISTRY
                            │
     ┌──────────────┬───────┴──────────┬──────────────┐
    CLI         MCP stdio          WebMCP            UCP
 shell agent   Claude Desktop    in-browser     buyer-agent
               Cursor/Windsurf   Chrome agent   Gemini/ChatGPT

CLI

Shell-running agents (Claude Code, Codex, scripts) invoke verbs via the CLI.

solid verbs list --json          # full manifest
solid verbs list --shape preview # filter by shape

solid agent dispatch <verb> --args '{"key": "value"}' --json [--confirm] [--phrase "..."]

Write verbs require --confirm. Typed-phrase verbs require --phrase "EXACT PHRASE". Shortcut commands promote high-traffic verbs to first-class: solid infra diagnose, solid deal create, solid customer-context 42.

MCP stdio

MCP-speaking runtimes (Claude Desktop, Cursor, Windsurf, Cline) load the server via npx. Discovery is standard tools/list; invocation is standard tools/call. Verb names map 1:1 to tool names.

{
  "mcpServers": {
    "solidnumber": {
      "command": "npx",
      "args": ["-y", "@solidnumber/mcp"],
      "env": { "SOLID_API_KEY": "sk_solid_..." }
    }
  }
}

The MCP server is a thin bridge. It fetches the manifest from /api/v1/agent/verbs?surface=mcp_stdio and caches it for 5 minutes, so new verbs appear in tools/list without an npm republish. Auth is the SOLID_API_KEY env var — optional for read verbs, required for writes.

WebMCP

In-browser agents discover verbs via the W3C draft API — navigator.modelContext.registerTool() on page load, registered per surface (dashboard, portal, developer, tenant-site, public). Auth is the session cookie; the browser's authenticated session binds the company_id. Tenants are born WebMCP-aware with no manual setup.

GET  /api/v1/webmcp/manifest?surface={dashboard|portal|developer|tenant-site|public}
POST /api/v1/webmcp/execute/{tool_name}
     { "input": { ... }, "surface": "dashboard" }

UCP (Universal Commerce Protocol)

Public buyer-agents (Gemini AI Mode, ChatGPT shopping) discover capabilities at GET /.well-known/ucp. Invocation is HTTP with RFC 9421 ES256 message signatures; verbs map to capabilities under the com.solidnumber.* namespace. Auth is a per-company JWK rotation lifecycle (pending → active → rotating → retired), private keys encrypted at rest and RLS-protected.

The differentiator: Solid# exposes a hierarchical agent graph (platform → company → sales / AR / AP / commissions / service / compliance / marketing / ops sub-agents) instead of the stock UCP single-checkout-endpoint model.

Error contract

All four transports return errors in the same envelope:

{
  "ok": false,
  "verb": "infrastructure_resize",
  "error": {
    "reason": "no_managed_droplet",
    "message": "This company has no managed droplet.",
    "hint": "Use subscription_upgrade_tier for capacity changes."
  }
}

reason is machine-readable — the agent pattern-matches on it. message is for humans and LLMs. hint is the actionable next step.

Receipt Contract

Every write verb returns a receipt. The receipt is the proof that an action happened, the handle to undo it, and the key to replay it safely.

Idempotency

If no key is supplied the runtime generates one. Keys expire after 24 hours.

Receipt chains

A transaction produces a parent receipt with child receipts per step. Reverting the parent reverts all children in reverse order.

{
  "transaction_id": "tx_abc123",
  "status": "committed",
  "audit_id": 4243,
  "steps": [
    { "verb": "crm_contact_update", "audit_id": 4244, "status": "completed" },
    { "verb": "email_send",         "audit_id": 4245, "status": "completed" }
  ],
  "rollback_handle": "tx:tx_abc123:rollback_all"
}

Treat rollback_handle as opaque — never parse or construct one.

Audit log

Every dispatch writes an AIAuditLog row — including denials. The row captures company and user, agent type, action type, category, status, request data, reversibility and approval trail.

Denied attempts are the most important rows. They prove the safety layer is working.

Consent Gates

Write verbs are classified by risk. Each class defines the minimum approval gate the runtime enforces before the action executes.

Roles are hierarchical — read_only < employee < admin < owner — and each class enforces a minimum. A WRITE_FINANCIAL verb denies employee and read_only at dispatch time.

Typed-phrase protocol

1. Agent calls the verb with _confirmed=false. The runtime returns a preflight response with metadata and no side effects.
2. Runtime generates the required phrase — e.g. CHARGE $50.00 to invoice #4242.
3. Frontend displays the phrase verbatim and asks the human to type it. No paraphrasing.
4. Human types it. The frontend sends { verb, args, confirm: true, typed_phrase }.
5. Runtime validates. The phrase is bound into an HMAC nonce at step 2, so a mismatch is denied with reason: "phrase_mismatch" and tampering between dispatch and confirm is cryptographically blocked.
6. Action executes. Receipt is returned.

The nonce embeds a timestamp plus an HMAC-SHA256 of the dispatch payload, and expires after 5 minutes. Replay or tampering fails validation.

Daily caps

Caps reset at midnight UTC. Exceeding one returns reason: "daily_cap_exceeded".

Cross-transport consent

Blocked verbs

Some names are permanently blocked — never callable by an agent, regardless of role or confirmation:

These exist as defense-in-depth against an LLM hallucinating a dangerous verb name. The safe alternatives (gdpr_delete_contact behind an IRREVERSIBLE gate) are named differently on purpose.