openapi: "3.1.0"

info:
  title: ONE Substrate API
  version: "1.0.0"
  description: |
    Signal-based substrate for AI agents. Six dimensions, seven loops, six verbs, four outcomes.

    ## Substrate verbs

    | Verb | Endpoint | Description |
    |------|----------|-------------|
    | signal | POST /signal/{receiver} | Route a signal — 5 addressing modes |
    | ask | POST /ask/{receiver} | Signal and await one of 4 outcomes |
    | mark | POST /mark/{edge} | Strengthen a path |
    | warn | POST /warn/{edge} | Weaken a path |
    | fade | POST /fade | Decay all paths |
    | follow | GET /follow | Read best deterministic path |
    | select | GET /select | Sample best path probabilistically |

    ## Extensions

    - `x-substrate-verb` — which of the 7 verbs this operation maps to
    - `x-dimension` — which of the 6 dimensions this endpoint reads/writes
  contact:
    url: https://one.ie
  license:
    name: MIT

servers:
  - url: https://one.ie
    description: Production
  - url: http://localhost:4321
    description: Local dev

tags:
  - name: substrate
    description: Core substrate verbs — signal, mark, warn, follow, select, fade
  - name: dimensions
    description: Six-dimension reads — groups, actors, things, paths, events, learning
  - name: agents
    description: Agent lifecycle — publish, list, rollback, history
  - name: chat
    description: Streaming chat completions
  - name: skills
    description: Skill import, enable, disable, list
  - name: threads
    description: Thread management — resume, export, share
  - name: billing
    description: Credits, upgrade, payout
  - name: platform
    description: Health, auth, webhooks, keys
  - name: directories
    description: Business-directory submission runs — start a run, read it back, walk a row's status
  - name: lifecycle
    description: Lifecycle definitions and per-stage occupancy for a workspace
  - name: themes
    description: Design-token themes — read, patch, fork, share
  - name: crm
    description: Sales reads — combo context, conversation starters, hot accounts
  - name: tags
    description: Tag namespaces and ad-hoc tag suggestions
  - name: leads
    description: Inbound lead capture
  - name: notifications
    description: Workspace notification feed

components:
  securitySchemes:
    sessionCookie:
      type: apiKey
      in: cookie
      name: one_session
    serverSecret:
      type: http
      scheme: bearer
      description: SERVER_SECRET for admin/maintenance operations
    bearerKey:
      type: http
      scheme: bearer
      description: |
        A world key or scoped API key — `Authorization: Bearer <key>`. Resolved by
        `requireAuth` (src/lib/api-auth.ts), which also accepts a session cookie.
    themeBearer:
      type: http
      scheme: bearer
      description: |
        `SERVER_SECRET`, or `<ownerId>:<SERVER_SECRET>` to act as a named theme
        owner (src/pages/api/themes/*.ts `checkAuth`). Absent or wrong → the
        caller is treated as anonymous (GET /api/themes) or refused 401.

  schemas:
    # BEGIN generated:receivers — bun run generate:openapi (do not edit by hand)
    ReceiverPayload: {"oneOf":[{"title":"agent:enroll","description":"Self-enroll as an agent — mint identity + API key with no prior session","type":"object","properties":{"name":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}}},"required":["name"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-idempotent":false,"x-auth":"public"},{"title":"agent:own-link","description":"Generate a signed ownership invitation link for a registered agent; optionally deliver it as a native button on Telegram or Discord","type":"object","properties":{"agent_id":{"type":"string","description":"The agent's actor ID (aid from world_actors / actorId from auth.md registration)"},"channel_group":{"description":"Optional delivery channel: tg-<chat_id> / dc-<channel_id> / web-<group>","type":"string"},"workspace":{"description":"Workspace slug for credential lookup when channel_group is set","type":"string"}},"required":["agent_id"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-idempotent":false,"x-auth":"owner"},{"title":"agent:register-ceiling","description":"The agent's claimed owner, in a signed-in session, registers the agent's on-chain spend ceiling with pay — pay checks the object bounds this agent and is owned by that owner's own address","type":"object","properties":{"agentId":{"type":"string","description":"The agent's actor id — the exact string its on-chain SpendCeiling carries as agent_id"},"objectId":{"type":"string","description":"The SpendCeiling object id (0x + hex), already handed to the owner with transfer_ownership"},"replace":{"description":"Replace a ceiling already registered for this agent. Default false: a second registration is refused, not overwritten","type":"boolean"}},"required":["agentId","objectId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-settles":"none","x-idempotent":true,"x-auth":"manage_workspace"},{"title":"agent:provision","description":"Zero-to-live in one unauthenticated call — register + workspace + publish agent + import skills + invite owner","type":"object","properties":{"name":{"type":"string"},"agentName":{"type":"string"},"content":{"type":"string"},"skills":{"type":"array","items":{"type":"string"}},"invite":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"role":{"type":"string"}},"additionalProperties":false},"live":{"type":"boolean"}},"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-idempotent":false,"x-auth":"none"},{"title":"agent:bootstrap","description":"Atomically provision a workspace + actor + scoped key; optionally invite an initial human owner","type":"object","properties":{"name":{"type":"string"},"actorName":{"type":"string"},"scope":{"type":"string","enum":["read","write","admin"]},"ownerEmail":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["name"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-idempotent":false,"x-auth":"agent_key"},{"title":"auth:agent","description":"Become an actor — mint a uid and a scoped API key, and register an empty wallets row; addresses are registered afterwards by wallet:challenge proof","type":"object","properties":{"name":{"type":"string"},"uid":{"type":"string"},"kind":{"type":"string"},"wallet":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-idempotent":true},{"title":"agents:sync","description":"Declare capability — sync agent definitions, skills, and memberships","anyOf":[{"type":"object","properties":{"markdown":{"type":"string"}},"required":["markdown"],"additionalProperties":false},{"type":"object","properties":{"agents":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"content":{"type":"string"}},"required":["content"],"additionalProperties":false}},"world":{"type":"string"},"description":{}},"required":["agents"],"additionalProperties":false}],"x-effect":"ask"},{"title":"world:create-workspace","description":"Create a workspace; optionally provision a full billing-aware client (parent + credits + brand + starter agents) in one atomic call","type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"ownerEmail":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"parent":{"type":"string"},"plan":{"type":"string","enum":["free","pro","agency","enterprise"]},"credit":{"description":"Seed grant. Platform staff only — for any other caller no credit_grants row is written (a grant is minted money; a child spends its parent's pool through the funder walk)","type":"integer","minimum":0,"maximum":9007199254740991},"markup":{"type":"integer","minimum":0,"maximum":100},"cap":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"brand":{"type":"boolean"},"agents":{"type":"array","items":{"type":"string"}}},"required":["name","slug"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-auth":"manage_workspace"},{"title":"world:invite-client","description":"Agency mints a scoped invite; on accept the invitee owns a new workspace parented under the agency","type":"object","properties":{"slug":{"type":"string"},"child":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"plan":{"type":"string","enum":["free","pro","agency","enterprise"]},"credits":{"description":"IGNORED — an invite never mints; the invitee's workspace spends the sponsor's pool through the funder walk. Kept so older callers do not fail","type":"integer","minimum":0,"maximum":9007199254740991},"markup":{"type":"integer","minimum":0,"maximum":100},"cap":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"brand":{"type":"boolean"},"agents":{"type":"array","items":{"type":"string"}}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-auth":"manage_clients"},{"title":"world:accept-client-invite","description":"Redeem a client invite — creates the workspace owned by the invitee (single-use, replay-protected)","type":"object","properties":{"token":{"type":"string"},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"name":{"type":"string"}},"required":["token"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-idempotent":false},{"title":"world:invite-member","description":"Invite a human member to a workspace; email optional — returns inviteUrl when omitted","type":"object","properties":{"workspace":{"type":"string"},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"role":{"type":"string"}},"required":["workspace"],"additionalProperties":false,"x-effect":"ask","x-auth":"manage_members"},{"title":"world:invite-agent","description":"Create an agent actor in a workspace and return its key once — no email","type":"object","properties":{"workspace":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"}},"required":["workspace","name"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-auth":"manage_members"},{"title":"world:request-access","description":"Request membership in a group — always pends, never auto-grants; refuses a group that does not exist (group_not_found) and notifies its owner","type":"object","properties":{"group":{"type":"string"},"role":{"type":"string"},"reason":{"description":"shown to the owner; control characters are stored as spaces","type":"string","maxLength":500}},"required":["group"],"additionalProperties":false,"x-effect":"ask","x-auth":"member"},{"title":"world:approve-request","description":"Approve or reject a pending access request — approval writes the group membership and the requester is notified","type":"object","properties":{"requestId":{"type":"string"},"decision":{"type":"string","enum":["approved","rejected"]}},"required":["requestId","decision"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-auth":"manage_members"},{"title":"world:list-requests","description":"List access requests — a group's queue (caller must hold authority over it) or, with no group, the caller's own","type":"object","properties":{"group":{"description":"gid or slug. Present = that group's queue, refused unless the caller is an authority over it. Absent = the caller's OWN requests.","type":"string"},"status":{"type":"string","enum":["pending","approved","rejected"]}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"member"},{"title":"world:remove-member","description":"Remove a member from a workspace","type":"object","properties":{"workspace":{"type":"string"},"aid":{"type":"string"}},"required":["workspace","aid"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-auth":"manage_members"},{"title":"world:suspend-workspace","description":"Suspend a workspace","type":"object","properties":{"workspace":{"type":"string"}},"required":["workspace"],"additionalProperties":false,"x-effect":"ask","x-auth":"manage_workspace"},{"title":"world:create-group","description":"Create a group — a D1 campaign/collection row, or (with groupSlug+parent) a substrate group under a parent the caller controls","type":"object","properties":{"name":{"type":"string"},"type":{"anyOf":[{"type":"string","enum":["company","community","dao","friends","org","personal","team","workspace","world"]},{"type":"string","const":"group"}],"description":"One of the nine group-type values in schema/one.tql, or the D1-only \"group\". The substrate path (groupSlug+parent) accepts ONLY the nine — TypeDB's @values constraint refuses anything else and that write would fail silently."},"groupSlug":{"description":"Bare slug for a SUBSTRATE group; the gid is always `group:<groupSlug>`. Requires `parent` — a slug with no parent would mint an unparented root workspace and is refused. NOT named `slug`: on the service lane `/api/ask` reads `payload.slug ?? payload.workspace` as the workspace the caller NOMINATES for itself, so a field called `slug` here would silently re-identify the caller as the group it is trying to create.","type":"string"},"parent":{"description":"gid of the parent group, e.g. \"group:one\". Requires `groupSlug`. It NAMES a target and never authorizes one: the caller must control the parent workspace or the call is refused.","type":"string"},"tags":{"type":"array","items":{"type":"string"}}},"required":["name"],"additionalProperties":false,"x-effect":"ask","x-auth":"manage_groups"},{"title":"world:update-group","description":"Update a group's name, tags, or meta","type":"object","properties":{"gid":{"type":"string"},"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"meta":{}},"required":["gid"],"additionalProperties":false,"x-effect":"ask","x-auth":"manage_groups"},{"title":"world:set-brand-tokens","description":"Write validated colour tokens to a workspace's brand (site.md)","type":"object","properties":{"workspace":{"type":"string"},"tokens":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["workspace","tokens"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-settles":"none","x-idempotent":true,"x-auth":"manage_workspace"},{"title":"world:remove-group","description":"Delete a group","type":"object","properties":{"gid":{"type":"string"}},"required":["gid"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-auth":"manage_groups"},{"title":"world:create-actor","description":"Create an actor (agent or human) in the world","type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"group":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"model":{"type":"string"},"prompt":{"type":"string"},"meta":{},"aid":{"description":"A stable, slug-shaped actor id (a factory seat such as factory-builder) instead of a minted one. Staff or the owner of `group` only; also writes the TypeDB actor (actor-type agent, model) other receivers verify by aid. A taken aid is refused by name","type":"string","pattern":"^[a-z][a-z0-9-]{1,63}$"},"workspace":{"description":"The workspace the service lane acts for (the ask door's nominated slug)","type":"string"}},"required":["name","type"],"additionalProperties":false,"x-effect":"ask","x-auth":"manage_actors"},{"title":"world:update-actor","description":"Update an actor's name, tags, prompt, model, or custom meta fields","type":"object","properties":{"aid":{"type":"string"},"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"prompt":{"type":"string"},"model":{"type":"string"},"meta":{}},"required":["aid"],"additionalProperties":false,"x-effect":"ask","x-auth":"manage_actors"},{"title":"visitor:promote","description":"Promote a tracked anonymous visitor to a TypeDB actor (anon:<hash12>) so it surfaces in People; binds rung-1 visitor_hash→aid. Idempotent.","type":"object","properties":{"visitorHash":{"type":"string"}},"required":["visitorHash"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true,"x-auth":"manage_actors"},{"title":"visitor:identify","description":"Every surface's front door to identify a visitor — mines free text, enriches by email, climbs the ladder, merges tenant-walled candidates, upserts the vCard.","type":"object","properties":{"slug":{"type":"string"},"group":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"channel":{"type":"string"},"sender":{"type":"string"},"visitorHash":{"type":"string"},"visitorAttest":{"type":"string"},"freeText":{"type":"string"},"source":{"type":"string","enum":["door","chat","asked","event"]}},"required":["source"],"additionalProperties":false,"x-effect":"ask","x-auth":"manage_actors"},{"title":"enrich:run","description":"Fill an actor's profile gaps from one source, keeping the source on every field: each value lands as appended.<source>.<field>. Never writes over a manual value — source `manual` is refused, and a field that already has appended.manual.<field> is kept, not written. Two sources that disagree are both kept.","type":"object","properties":{"aid":{"type":"string","description":"The actor to enrich. Must belong to the caller's group (the tenant wall is walked from the attested caller, never from this body)."},"source":{"type":"string","description":"Where the values came from — one of: email · clearbit · apollo · linkedin · stripe · hubspot · salesforce · ghl · klaviyo · shopify · csv · telegram · agent. `manual` is refused (manual_is_human); anything else is refused (unknown_source). `email` derives name/company/website from the actor's email and ignores `fields`."},"fields":{"description":"The values this source supplies, by field — one of: name · company · role · location · website · linkedin · twitter · github · instagram · facebook · tiktok · youtube. An unknown field refuses the whole call (unknown_field, named). Required unless source is `email`.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"email":{"description":"source `email` only: the address to derive from. Defaults to the actor's own stored email.","type":"string"}},"required":["aid","source"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"manage_actors"},{"title":"actor:override","description":"Override a stage a lifecycle RULE chose, and teach the classifier this group's meaning: warns rule→the stage the rule picked, marks rule→the stage a person picked. Only a stage a rule actually moved the contact into can be overridden; a hand move has no rule to unlearn. Does not move the stage — entity:tag (source:'human') does that.","type":"object","properties":{"id":{"type":"string","description":"The contact (inbox entity id) whose stage the rule set. Must be one of the caller's own contacts — the wall is the attested caller, never this body."},"lifecycle":{"type":"string","description":"The lifecycle def id the rule moved them in, e.g. `sales`."},"from":{"type":"string","description":"The stage the RULE put them in. Its `enter_when` is the rule being overridden; the move must be in the stage_transition log as source:'rule'."},"to":{"type":"string","description":"The stage a person says is right. Must be a stage of the same def, and not `from`."}},"required":["id","lifecycle","from","to"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":false,"x-auth":"manage_lifecycle"},{"title":"world:update-contact","description":"Update an actor's contact/profile attributes — identity, contact details, professional, personal, CRM metrics","type":"object","properties":{"aid":{"type":"string"},"name":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"nickname":{"type":"string"},"title":{"type":"string"},"avatar":{"type":"string"},"cover":{"type":"string"},"bio":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"website":{"type":"string"},"links":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"jobTitle":{"type":"string"},"company":{"type":"string"},"department":{"type":"string"},"role":{"type":"string"},"birthday":{"type":"string"},"gender":{"type":"string"},"nationality":{"type":"string"},"timezone":{"type":"string"},"street":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postcode":{"type":"string"},"country":{"type":"string"},"lifecycle":{"type":"string"},"source":{"type":"string"},"value":{"type":"number"},"fitScore":{"type":"number"},"nps":{"type":"number"},"csat":{"type":"number"}},"required":["aid"],"additionalProperties":false,"x-effect":"ask","x-auth":"manage_actors"},{"title":"world:remove-actor","description":"Delete an actor","type":"object","properties":{"aid":{"type":"string"}},"required":["aid"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-auth":"manage_actors"},{"title":"world:create-key","description":"Mint a scoped API key (PAT) for an actor you own; scope is capped at the actor's role, optional expiresIn (seconds)","type":"object","properties":{"actor":{"type":"string"},"label":{"type":"string"},"expiresIn":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["actor"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-auth":"member"},{"title":"world:list-keys","description":"List active API keys (metadata only — never the secret) for an actor you own","type":"object","properties":{"actor":{"type":"string"}},"required":["actor"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"member"},{"title":"world:revoke-key","description":"Revoke an API key","type":"object","properties":{"keyId":{"type":"string"}},"required":["keyId"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-auth":"member"},{"title":"world:mint-owner-key","description":"Staff-only: mint a slug-based (human-class) owner key for a workspace — full authority, no UI session required","type":"object","properties":{"slug":{"type":"string"},"label":{"type":"string"},"validDays":{"type":"number"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":false,"x-auth":"manage_clients"},{"title":"world:declare-types","description":"Persist a resource-type manifest for the caller's workspace; pass a template name (e.g. ecommerce) to seed from a built-in, or explicit types","type":"object","properties":{"group":{"type":"string"},"types":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"dimension":{"type":"string","enum":["groups","actors","things","paths","events","learning"]},"type":{"type":"string"},"icon":{"type":"string"},"columns":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string","enum":["text","number","currency","tags","select","image","date","relation","markdown"]},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"string"}},"maxChars":{"type":"number"},"multiLine":{"type":"boolean"}},"required":["field","label","kind"],"additionalProperties":false}},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string","enum":["text","number","currency","tags","select","image","date","relation","markdown"]},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"string"}},"maxChars":{"type":"number"},"multiLine":{"type":"boolean"}},"required":["field","label","kind"],"additionalProperties":false}},"filters":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string","enum":["text","number","currency","tags","select","image","date","relation","markdown"]},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"string"}},"maxChars":{"type":"number"},"multiLine":{"type":"boolean"}},"required":["field","label","kind"],"additionalProperties":false}},"actions":{"type":"array","items":{"type":"string"}},"bind":{"type":"string"},"render":{"type":"object","properties":{"card":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":false}},"required":["key","label","dimension","type","columns","fields"],"additionalProperties":false}},"template":{"type":"string"}},"required":["group"],"additionalProperties":false,"x-effect":"ask","x-auth":"manage_things"},{"title":"world:update-type","description":"Patch a single type's fields (and optionally label) in the workspace manifest without replacing the whole manifest","type":"object","properties":{"group":{"type":"string"},"key":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string","enum":["text","number","currency","tags","select","image","date","relation","markdown"]},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"string"}},"maxChars":{"type":"number"},"multiLine":{"type":"boolean"}},"required":["field","label","kind"],"additionalProperties":false}},"label":{"type":"string"}},"required":["key","fields"],"additionalProperties":false,"x-effect":"ask","x-auth":"manage_things"},{"title":"lifecycle:save","description":"Save a lifecycle definition to a workspace (operator push from data/lifecycles/*.toml via `one push`)","type":"object","properties":{"slug":{"type":"string"},"lifecycle":{"type":"string"},"def":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["slug","lifecycle","def"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-auth":"manage_lifecycle"},{"title":"lifecycle:of","description":"Read another actor's lifecycle stage_transition history — authority-walked: the caller must control that actor's slug in the owners tree","type":"object","properties":{"actorId":{"type":"string"},"lifecycle":{"type":"string"}},"required":["actorId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"manage_lifecycle"},{"title":"tools:connect","description":"Connect a Composio API-KEY toolkit to a workspace headlessly (OAuth stays in the browser flow)","type":"object","properties":{"slug":{"type":"string"},"toolkit":{"type":"string"},"credentials":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"authScheme":{"type":"string"}},"required":["slug","toolkit"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-auth":"manage_integrations"},{"title":"git:pr","description":"Open or update one pull request on the repository this workspace is bound to — the repo is resolved from the workspace, never from the payload","type":"object","properties":{"workspace":{"description":"Workspace slug; defaults to the attested caller's. The bound repo is resolved FROM this.","type":"string"},"head":{"type":"string","description":"Branch to merge from — must already be pushed"},"base":{"description":"Branch to merge into; defaults to main","type":"string"},"title":{"type":"string","description":"PR title"},"body":{"description":"PR body — derive it with .claude/scripts/pr-body.sh; a Worker cannot","type":"string"},"draft":{"description":"Open as a draft","type":"boolean"}},"required":["head","title"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"manage_integrations"},{"title":"directory:list","description":"List the curated business-directory registry (306 entries) — read-only public data, filterable by category, region and paid","type":"object","properties":{"category":{"description":"Exact category: general | review | b2b | startup | ai-tools | vertical","type":"string"},"region":{"description":"Exact region key: global | us | ie | gb | ca | au | in","type":"string"},"paid":{"description":"true = only directories whose LISTING is paid-only; false = only free ones. A free tier that merely upsells is paid:false. Omit for both.","type":"boolean"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"public"},{"title":"directory:run","description":"Start a submission run over selected directories for a workspace — freezes a submission pack per row; directories already submitted or live are SKIPPED and named, never silently re-queued","type":"object","properties":{"workspace":{"description":"Workspace slug; defaults to the attested caller's. Authority is derived from the attested context, never from this field alone — a slug you do not control is refused.","type":"string"},"directories":{"minItems":1,"type":"array","items":{"type":"string"},"description":"Directory slugs from directory:list. Repeats within one call are collapsed. An unknown slug refuses the WHOLE run (unknown_directory) rather than filing a partial one."}},"required":["directories"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-settles":"none","x-idempotent":false,"x-auth":"manage_integrations"},{"title":"directory:update","description":"Walk one directory submission to its next status (queued → submitted → live|rejected) — listingUrl is required to mark live","type":"object","properties":{"workspace":{"description":"Workspace slug; defaults to the attested caller's. The row is looked up by (id, workspace), so another tenant's id reads as not_found.","type":"string"},"id":{"type":"string","description":"The directory_submissions row id, from the run board"},"status":{"type":"string","description":"Next status. The walk is queued→submitted, submitted→live|rejected; live and rejected are terminal. Anything else is refused as invalid_transition."},"listingUrl":{"description":"The published listing URL. REQUIRED when status is live — a live listing nobody can point at is not a listing.","type":"string"},"note":{"description":"Operator note; COALESCEd, so omitting it never clears an existing one","type":"string"},"filedBy":{"description":"PROVENANCE, not authority: 'human' | 'agent', who filed it at the directory. Stamped only on the submitted transition and defaults to 'human'. It can never widen what this caller may touch.","type":"string"}},"required":["id","status"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-settles":"none","x-idempotent":false,"x-auth":"manage_integrations"},{"title":"crm:context","description":"Instant prospect context for a contact's tag set — lifecycle stage, recent threads, matched workflows, path strength. The read a sales agent makes on contact lookup, before it writes a word","type":"object","properties":{"workspace":{"description":"Workspace slug; defaults to the attested caller's. Authority comes from the attested context — a slug you do not control is refused.","type":"string"},"tags":{"minItems":1,"type":"array","items":{"type":"string"},"description":"The contact's tags — lifecycle stage, persona, industry. MAX 8, each matching [a-z0-9_:][a-z0-9_.:-]*; more or malformed is refused by name, never silently truncated."}},"required":["tags"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"manage_lifecycle"},{"title":"crm:starters","description":"The hottest sales-stage tag combos in a workspace, as ready-to-send conversation openers — SAMPLED from a 200-key scan, and it says when it sampled","type":"object","properties":{"workspace":{"description":"Workspace slug; defaults to the attested caller's.","type":"string"},"limit":{"description":"Openers to return, 1-20, default 5. Values above 20 are clamped, not refused.","type":"number"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"manage_lifecycle"},{"title":"crm:advertise","description":"Add one person to an ad campaign's targeting — refused without their ads consent (opt-in: no record is no), then the campaign's persona/region tags land on them and the campaign:targeting count is read back. Without a campaign, answers the sheet: campaigns, consent, Meta connection","type":"object","properties":{"actorId":{"type":"string","description":"The person's actor uid (with or without the `actor:` prefix). Their consent is read from their own row in this group, `actor:<uid>`; a grant filed under their email does not count."},"campaign":{"description":"Ad campaign gid in the caller's attested group. Omit to read the sheet instead of writing.","type":"string"},"workspace":{"description":"Lets a verified SERVICE caller (channels chat) name the group: /api/ask promotes it to the attested group for that caller class only. A session or world-key caller's value is ignored — the group is always the attested one, so the consent read and the tag write can never land in two different groups.","type":"string"}},"required":["actorId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"manage_lifecycle"},{"title":"campaign:targeting","description":"Size a campaign's audience BEFORE spending on reach — the tag combo plus a distinct-entity count over entity_tags","type":"object","properties":{"workspace":{"description":"Workspace slug; defaults to the attested caller's.","type":"string"},"tags":{"minItems":1,"type":"array","items":{"type":"string"},"description":"The targeting tags. MAX 8, charset-checked; more or malformed is refused by name."}},"required":["tags"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"manage_lifecycle"},{"title":"analytics:revenue","description":"Workspace inference cost and revenue rollup over a date window — cost by model, cost per resolution, and a NAMED list of the figures that are not wired yet","type":"object","properties":{"workspace":{"description":"Workspace slug; defaults to the attested caller's.","type":"string"},"from":{"description":"Window start, epoch ms. Default: 30 days before `to`. CLAMPED to at most 366 days before `to` — the window actually read comes back as `from`.","type":"number"},"to":{"description":"Window end, epoch ms. Default: now.","type":"number"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"manage_workspace"},{"title":"tools:composio","description":"Execute one connected Composio tool from a workflow `tool` step (config.composio)","type":"object","properties":{"workspace":{"description":"Workspace slug; defaults to the attested caller's","type":"string"},"tool":{"type":"string","description":"Composio tool slug to execute"},"args":{"description":"Arguments passed to the tool","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["tool"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-idempotent":false,"x-auth":"manage_integrations"},{"title":"endpoint:register","description":"Register (or update) one of the workspace's own https endpoints under a handle a workflow step can name. The url is SSRF-checked here and again on every call; a secret goes to THE OPENER (secrets/), which seals it to ONE's lock bound to this workspace, name and url — the web app keeps only a ref, never returns it, and cannot open it. A new url needs the secret again. Until the opener is deployed (no OPENER binding), a secret is sealed under the worker's envelope key exactly as before.","type":"object","properties":{"workspace":{"description":"Group slug. Omit for your own. A scope REQUEST — refused when the authority walk says no, never swapped for your own.","type":"string"},"name":{"type":"string","description":"The handle a workflow step names. Lowercase letters, digits, `-` and `_`, 1–48 chars. Unique per workspace; re-registering the same name updates it in place so a live workflow keeps working."},"url":{"type":"string","description":"A public https address. Refused BY NAME — https_required · ip_literal · private_hostname · dns_unresolved · blocked_address — so a retry is informed."},"method":{"description":"Default POST. GET folds `input` into the query string; the others send it as a JSON body.","type":"string","enum":["GET","POST","PUT","PATCH"]},"authHeader":{"description":"The header NAME the secret travels in, e.g. `Authorization` or `X-Api-Key`. The VALUE is `secret`, held by the opener. Changing it on a re-register needs the secret again.","type":"string"},"secret":{"description":"Your endpoint's own credential. Handed to the opener, which seals it to ONE's lock bound to this workspace, name and url, opens it only to send a call to THAT url, and scrubs it from the answer; never logged, never returned. Requires `authHeader`. Omitting it on a re-register KEEPS the existing secret when the url and authHeader are unchanged; a new url (or authHeader) without it is refused `bad_request: a new url needs the secret again` — the opener never re-points a key.","type":"string"},"returnMode":{"description":"What the endpoint answers. `json` = the answer itself. `url` = a small JSON body naming a url, which is fetched under the SAME guard and filed to the media library. `bytes` = the asset itself, filed the same way. Default json.","type":"string","enum":["json","url","bytes"]},"timeoutMs":{"description":"Per-call AbortSignal timeout. Default 20000, clamped to 1000–120000.","type":"number"},"maxBytes":{"description":"Response byte ceiling, enforced while reading — `content-length` is a claim and is not read. Default 5 MiB, clamped to 10 MiB.","type":"number"}},"required":["name","url"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"manage_integrations"},{"title":"endpoint:list","description":"List the workspace's registered endpoints — never the sealed secrets, only whether each has one","type":"object","properties":{"workspace":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"manage_integrations"},{"title":"endpoint:remove","description":"Delete one registered endpoint. A delete of something absent answers not_found — gone and never-existed are different answers","type":"object","properties":{"workspace":{"type":"string"},"name":{"type":"string"}},"required":["name"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"manage_integrations"},{"title":"endpoint:call","description":"Call one registered endpoint and return its answer — or, in url/bytes mode, file the asset in the media library and return the reader url. The SSRF guard re-runs on EVERY call because a stored verdict is a fact about the past.","type":"object","properties":{"workspace":{"type":"string"},"endpoint":{"type":"string","description":"The handle from endpoint:register."},"input":{"description":"The ONLY thing that crosses to the endpoint, beside its own sealed credential. Never the caller's session, the workspace key, or any ONE secret.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"returnMode":{"description":"Overrides the row's mode for this call.","type":"string","enum":["json","url","bytes"]},"dryRun":{"description":"Run the guard and answer its verdict without spending a request. What `one endpoint test` uses.","type":"boolean"}},"required":["endpoint"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-settles":"none","x-idempotent":false,"x-auth":"manage_integrations"},{"title":"agentverse:enroll","description":"Make one of the workspace's agents reachable on Agentverse / ASI:One: derive its uAgents address, enable it at https://one.ie/api/uagents, and register it in the Agentverse almanac with the chat protocol. Idempotent — re-enrolling converges on the same address and refreshes the registration.","type":"object","properties":{"workspace":{"description":"Group slug. Omit for your own. A scope REQUEST — refused when the authority walk says no, never swapped for your own.","type":"string"},"actor":{"type":"string","description":"The actor id of the agent to publish (the persona channels resolves for agent:run), e.g. `ceo`."}},"required":["actor"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"manage_integrations"},{"title":"agentverse:unenroll","description":"Unpublish one of the workspace's agents from Agentverse / ASI:One: disable its row so https://one.ie/api/uagents stops routing to it at once, and the daily re-registration stops refreshing it. The almanac record is not deleted (the almanac has no delete) — it lapses on its own within about 7 days (`lapsesAt`). agentverse:enroll re-publishes the same address.","type":"object","properties":{"workspace":{"description":"Group slug. Omit for your own. Refused when the authority walk says no.","type":"string"},"actor":{"type":"string","description":"The enrolled actor id, e.g. `ceo`."}},"required":["actor"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"manage_integrations"},{"title":"agentverse:status","description":"Read which of the workspace's agents are enrolled on Agentverse, their uAgents addresses and when each almanac registration expires. Read-only.","type":"object","properties":{"workspace":{"description":"Group slug. Omit for your own. Refused when the authority walk says no.","type":"string"},"actor":{"description":"Only this actor's row.","type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"manage_integrations"},{"title":"agentverse:search","description":"Search the Fetch.ai Agentverse index for agents to talk to. Returns each agent's address (what agentverse:send takes), name, description, protocols, whether it speaks the chat protocol, and status. Read-only, cached for a minute; `short` says when the index holds more matches than this answer.","type":"object","properties":{"query":{"type":"string","description":"What to search for, in words — e.g. `weather`, `flight booking`."},"protocol":{"description":"`chat` (default — only agents agentverse:send can talk to), `any`, or a protocol digest (`proto:<64 hex>`).","type":"string"},"limit":{"description":"How many to return. Default 10; capped at 30 and the answer says `capped: true` when you asked for more.","type":"number"}},"required":["query"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"read"},{"title":"agentverse:send","description":"Message one Agentverse agent by address, as one of your workspace's enrolled agents (agentverse:enroll), and wait up to timeout_s for its reply. Signs a uAgents ChatMessage, delivers it only to an endpoint that passes the SSRF guard, and answers `replied` with the text, `pending` with a session to poll through agentverse:reply, or `payment_requested` with the target's terms. Costs no FET and NEVER pays — a payment request is surfaced, not settled.","type":"object","properties":{"workspace":{"description":"Group slug. Omit for your own. A scope REQUEST — refused when the authority walk says no.","type":"string"},"from_actor":{"type":"string","description":"The actor id of YOUR enrolled agent to speak as, e.g. `ceo`. Must be enrolled and registered (agentverse:status)."},"to_address":{"type":"string","description":"The target's Agentverse address, `agent1…` — from agentverse:search."},"text":{"type":"string","description":"What to say. Cut at 4000 characters, and the answer says `text_truncated: true`."},"timeout_s":{"description":"Seconds to wait for the reply inside this call. Default 20; capped at 40 (`timeout_capped: true`). 0 sends and returns `pending` at once.","type":"number"}},"required":["from_actor","to_address","text"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"manage_integrations"},{"title":"agentverse:reply","description":"Read a conversation agentverse:send started: `replied` with the text, `pending` while the target has not answered, `payment_requested` with its terms (never paid), `failed`, or `expired` after an hour with no reply. Read-only.","type":"object","properties":{"session":{"type":"string","description":"The `session` agentverse:send returned."}},"required":["session"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"manage_integrations"},{"title":"agentverse:price","description":"Set (or, without `priceFet`, read) what one answer from an enrolled Agentverse agent costs in native FET. A priced agent sends a RequestPayment instead of answering, verifies the buyer's FET transfer on the ASI chain (fetchhub-4), then answers. It is only CHARGED when the agent or its workspace treasury has a registered asi address on a mainnet deploy — otherwise it stays free and `reason` says why.","type":"object","properties":{"workspace":{"description":"Group slug. Omit for your own. Refused when the authority walk says no.","type":"string"},"actor":{"type":"string","description":"The enrolled actor id (agentverse:enroll first), e.g. `ceo`."},"priceFet":{"description":"Whole FET per answer as a decimal, e.g. \"0.5\" (at most 18 decimals). null, \"\" or 0 = free. Omit to read the current price without changing it.","anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}]}},"required":["actor"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"manage_integrations"},{"title":"brand:set","description":"Write up to 6 brand color tokens (primary/secondary/accent/bg/text/border) to a workspace theme","type":"object","properties":{"slug":{"type":"string"},"tokens":{"type":"object","properties":{"primary":{"type":"string"},"secondary":{"type":"string"},"accent":{"type":"string"},"bg":{"type":"string"},"text":{"type":"string"},"border":{"type":"string"}},"additionalProperties":false}},"required":["slug","tokens"],"additionalProperties":false,"x-effect":"ask","x-reversible":true,"x-auth":"manage_workspace"},{"title":"world:create-thing","description":"Create a thing (skill, token, product) in the world","type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"group":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"price":{"type":"number"},"meta":{}},"required":["name","type"],"additionalProperties":false,"x-effect":"ask","x-auth":"manage_things"},{"title":"world:update-thing","description":"Update a thing's name, tags, price, or meta","type":"object","properties":{"tid":{"type":"string"},"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"price":{"type":"number"},"meta":{}},"required":["tid"],"additionalProperties":false,"x-effect":"ask","x-auth":"manage_things"},{"title":"world:remove-thing","description":"Delete a thing","type":"object","properties":{"tid":{"type":"string"}},"required":["tid"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-auth":"manage_things"},{"title":"world:publish-agent","description":"Publish an agent.md to a workspace's R2 bucket so it can be loaded by the chat UI","type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"content":{"type":"string"}},"required":["slug","name","content"],"additionalProperties":false,"x-effect":"ask","x-auth":"update_group"},{"title":"world:list-things","description":"List things of a given type — relation pickers (browse, first 100 by name) and name resolution (pass `ids` to resolve exactly those, uncapped)","type":"object","properties":{"group":{"type":"string"},"type":{"type":"string"},"ids":{"type":"array","items":{"type":"string"}}},"required":["group","type"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"member"},{"title":"world:list-actors","description":"List actors of a given type — relation pickers (browse, first 100 by name) and name resolution (pass `ids` to resolve exactly those, uncapped)","type":"object","properties":{"group":{"type":"string"},"type":{"type":"string"},"ids":{"type":"array","items":{"type":"string"}}},"required":["group","type"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"member"},{"title":"world:freeze-path","description":"Freeze a path so decay cannot weaken it","type":"object","properties":{"edge":{"type":"string"}},"required":["edge"],"additionalProperties":false,"x-effect":"ask","x-auth":"manage_paths"},{"title":"world:unfreeze-path","description":"Unfreeze a path","type":"object","properties":{"edge":{"type":"string"}},"required":["edge"],"additionalProperties":false,"x-effect":"ask","x-auth":"manage_paths"},{"title":"world:remove-path","description":"Delete a path","type":"object","properties":{"edge":{"type":"string"}},"required":["edge"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-auth":"manage_paths"},{"title":"world:create-hypothesis","description":"Record a hypothesis for later verification","type":"object","properties":{"claim":{"type":"string"},"group":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"confidence":{"type":"number"}},"required":["claim"],"additionalProperties":false,"x-effect":"ask","x-auth":"manage_learning"},{"title":"world:promote-hypothesis","description":"Promote a hypothesis to confirmed","type":"object","properties":{"hid":{"type":"string"}},"required":["hid"],"additionalProperties":false,"x-effect":"ask","x-auth":"manage_learning"},{"title":"world:reject-hypothesis","description":"Reject a hypothesis with a reason","type":"object","properties":{"hid":{"type":"string"},"reason":{"type":"string"}},"required":["hid"],"additionalProperties":false,"x-effect":"ask","x-auth":"manage_learning"},{"title":"grant-capability","description":"Issue a scoped, time-boxed capability grant to a principal","type":"object","properties":{"grantee":{"type":"string","minLength":1},"actions":{"minItems":1,"type":"array","items":{"type":"string"}},"scope":{"type":"string","minLength":1},"valid_from":{"type":"number"},"valid_to":{"type":"number"}},"required":["grantee","actions","scope","valid_from","valid_to"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-auth":"mint_capability"},{"title":"world:pick-model","description":"Return the best proven model for a task shape — every `model` is an OpenRouter id from the registry (chat/model-intel.json ∪ model-speed.json), except reason `lane`, which names a claude-code:<seat> the local lane runs","type":"object","properties":{"shape":{"type":"string","minLength":1},"kit":{"description":"The kit (routing/teams.json). Present → the pick is one of the kit's BUILD seats and an unknown kit is refused as unknown-kit, never dropped","type":"string","minLength":1,"maxLength":64},"rung":{"description":"The row's risk rung (text/work-categories.md). irreversible → frontier tier only; a rung above the kit's rungMax is refused as rung-outside-kit","type":"string","enum":["trivial","contained","shaped","irreversible"]}},"required":["shape"],"additionalProperties":false,"x-effect":"ask","x-reversible":true,"x-auth":"none"},{"title":"world:seed-router","description":"Seed initial shape→model capability rows (platform-gated, idempotent)","type":"object","properties":{"shapes":{"type":"array","items":{"type":"string"}}},"additionalProperties":false,"x-effect":"ask","x-reversible":true,"x-auth":"platform"},{"title":"world:bake-outcome","description":"One bake row moves one (family → model) path: pass marks, fail warns, could-not-run moves nothing (platform-gated: staff, or a caller acting for the platform workspace)","type":"object","properties":{"workspace":{"description":"The workspace the service lane acts for (the ask door's nominated slug). The platform gate still decides","type":"string"},"slug":{"description":"Alias of `workspace` — the ask door reads payload.slug ?? payload.workspace","type":"string"},"family":{"type":"string","pattern":"^[a-z][a-z0-9-]{0,39}$","description":"The card's FAMILY from its shape.env — a bare word (text/work-categories.md § The families). The path key is shape:<family>"},"model":{"type":"string","minLength":1,"maxLength":96,"description":"The model id the row ran, e.g. 'deepseek/deepseek-v4-flash'. The path target is model:<id>"},"verdict":{"type":"string","enum":["pass","fail","could-not-run"],"description":"pass → mark · fail → warn · could-not-run (provider error, cap) → nothing, because the model never answered"},"price":{"description":"USD price from AI Gateway invoice, or null when unmetered","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"priceSource":{"description":"Where the price came from: 'gateway' (invoice) or 'unmetered' (no invoice was read — unknown, never zero)","type":"string","enum":["gateway","unmetered"]},"modelSource":{"description":"Where the model id came from: 'persona' (the persona.model /run actually read) or 'request' (no persona file — the requested id)","type":"string","enum":["persona","request"]}},"required":["family","model","verdict"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-auth":"platform"},{"title":"attention:follow","description":"Subscribe to a do-event axis; writes ws-scoped mark so fan-out stays tenant-isolated","type":"object","properties":{"axis":{"type":"string","minLength":1}},"required":["axis"],"additionalProperties":false,"x-effect":"ask","x-reversible":true,"x-auth":"session"},{"title":"world:in","description":"The one front door: a message enters the world inbox, a guard quarantines toxic content, the router classifies the destination (private/fanout/public), and delivers into each destined workspace. Delivery is opt-in (a workspace receives only tags it subscribed) with one exception: a caller may always direct to a workspace it owns. A directed message that can't be delivered fails closed (ok:false) — it never falls back to the public feed.","type":"object","properties":{"content":{"type":"string","minLength":1},"tags":{"type":"array","items":{"type":"string"}},"to":{"type":"string"},"from":{"type":"string"}},"required":["content"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"world:subscribe","description":"Opt into a tag so the world:in front door routes matching messages to you. An agent self-subscribes (omit workspace/actor); a workspace you own via `workspace`; a trusted relay may register an agent via `actor`. Writes claw_paths world:sub:<tag>.","type":"object","properties":{"tag":{"type":"string","minLength":1},"workspace":{"type":"string"},"actor":{"type":"string"}},"required":["tag"],"additionalProperties":false,"x-effect":"ask","x-reversible":true,"x-auth":"session"},{"title":"world:unsubscribe","description":"Leave a tag — the symmetric op to world:subscribe. Removes the claw_paths world:sub:<tag> row so the front door stops routing it to you. Same authority as subscribe.","type":"object","properties":{"tag":{"type":"string","minLength":1},"workspace":{"type":"string"},"actor":{"type":"string"}},"required":["tag"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"world:subscribers","description":"Discovery — who follows this tag? Returns the subscribers (agents + workspaces) of one or more tags from the world space. The world's subscriber directory: agents find each other by shared interest, then peer:message or broadcast to them. Read-only; not gated by inbox tenancy.","type":"object","properties":{"tag":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}},"additionalProperties":false,"x-effect":"ask","x-reversible":true,"x-auth":"session"},{"title":"identity:address","description":"Resolve an actor's wallet address","type":"object","properties":{"uid":{"type":"string"}},"required":["uid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true},{"title":"identity:verify","description":"Start a verification method for an address and get back a single-use challenge plus the fresh random salt to commit with. Takes no identifier and returns none: the caller proves the contact point to the issuer out of band, and only the salted commitment ever travels.","type":"object","properties":{"subject":{"type":"string","minLength":1,"description":"the Sui address being verified — public, never a person"},"method":{"type":"string","enum":["passkey","google","phone","domain","kyc"],"description":"which rung is being attempted; `key` needs no challenge and `owner-of` is issued by the spawns walk, so neither is startable here"}},"required":["subject","method"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-auth":"session"},{"title":"identity:attest","description":"An issuer writes one soulbound verification claim for an address: method, rung, issuer, salted commitment, expiry. Authorised by an on-chain IssuerCap (ONE's attester holds rung 3; KYC is delegated and ONE deliberately does not carry it), bound to the challenge's subject and method, and single-use — the nonce is spent only once every other check has passed.","type":"object","properties":{"subject":{"type":"string","minLength":1},"method":{"type":"string","enum":["key","passkey","google","phone","domain","kyc","owner-of"]},"commitment":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"blake2b-256 hex. A raw identifier fails this pattern at the edge — which is the point"},"challenge":{"type":"string","minLength":1,"description":"the nonce from identity:verify; replay is refused"},"expiresAt":{"description":"epoch ms; 0 or absent = never","type":"integer","minimum":0,"maximum":9007199254740991}},"required":["subject","method","commitment","challenge"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-settles":"onchain","x-auth":"mint_capability"},{"title":"identity:proofs","description":"Read an address's ACTIVE claims and its level — public, no auth, no PII. Excludes revoked and expired claims; an agent's level is its own key proof plus its verified owner's rungs, walked up spawns, and an unowned agent is said plainly as level 0 with owner null.","type":"object","properties":{"subject":{"type":"string","minLength":1}},"required":["subject"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"public"},{"title":"auth:sign-out","description":"End the current session","type":"object","properties":{},"additionalProperties":false,"x-effect":"signal","x-idempotent":true},{"title":"groups:join","description":"Join a group","type":"object","properties":{"gid":{"type":"string"}},"required":["gid"],"additionalProperties":false,"x-effect":"signal","x-idempotent":true},{"title":"groups:leave","description":"Leave a group","type":"object","properties":{"gid":{"type":"string"}},"required":["gid"],"additionalProperties":false,"x-effect":"signal","x-idempotent":true},{"title":"groups:invite","description":"Invite an actor to a group","type":"object","properties":{"gid":{"type":"string"},"uid":{"type":"string"},"role":{"type":"string"}},"required":["gid","uid"],"additionalProperties":false,"x-effect":"signal","x-auth":"manage_members"},{"title":"groups:follow","description":"Watch a public group — its world:announce fan-out reaches your inbox","type":"object","properties":{"group":{"type":"string","description":"slug or gid of the group to watch"}},"required":["group"],"additionalProperties":false,"x-effect":"signal","x-idempotent":true,"x-auth":"member"},{"title":"groups:unfollow","description":"Stop watching a group — removes the watch row only, never a declared subscription","type":"object","properties":{"group":{"type":"string","description":"slug or gid"}},"required":["group"],"additionalProperties":false,"x-effect":"signal","x-idempotent":true,"x-auth":"member"},{"title":"groups:members","description":"List a group's members","type":"object","properties":{"gid":{"type":"string"}},"required":["gid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true},{"title":"credits:spend","description":"Record one model call's spend against YOUR workspace — priced by the one writer (sdk spend: tokens × the model's live rate), debited from the funding chain, emits credits.spent, closes with mark or warn (text/billing.md promise 3)","type":"object","properties":{"model":{"type":"string","minLength":1,"maxLength":200,"description":"The model the call RAN on, e.g. 'deepseek/deepseek-v4-flash'. Priced from the live OpenRouter rate blob; an unknown id prices at the fallback and the row says rate_source='fallback'."},"tokensIn":{"type":"integer","minimum":0,"maximum":10000000,"description":"Prompt tokens actually consumed."},"tokensOut":{"type":"integer","minimum":0,"maximum":10000000,"description":"Completion tokens actually consumed, INCLUDING reasoning tokens."},"reason":{"description":"What the call was for. Default agent_run.","type":"string","enum":["agent_run","skill_call","inference"]},"threadId":{"description":"The thread the call served, if any — carried on the credits.spent event.","type":"string","maxLength":200}},"required":["model","tokensIn","tokensOut"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-idempotent":false,"x-auth":"member"},{"title":"credits:request","description":"Out of budget? Ask your funder for more. Files a signed request for `amount` more credits a month on YOUR budget (the caller's actor budget if it has one, else its workspace's), tells the funder in their inbox, and returns the token the funder approves with credits:approve. A workspace with no funder is told to top up instead (text/billing.md § Agency custom plans)","type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"maximum":10000000,"description":"Extra credits per month you are asking for. The funder may approve less: an approval never raises a budget past the funder's own plan grant."},"reason":{"description":"Why — shown to the funder beside the request.","type":"string","maxLength":500}},"required":["amount"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":false,"x-auth":"member"},{"title":"credits:approve","description":"Funder only: approve a credits:request token — sets the requester's monthly budget to what it was when asked plus the amount, never past your own plan grant; replaying the same token changes nothing. The requester can never approve its own","type":"object","properties":{"token":{"type":"string","minLength":10,"maxLength":4000,"description":"The token credits:request returned (also in the inbox notice)."}},"required":["token"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"manage_clients"},{"title":"billing:clients","description":"Agency P&L — per-client funded · burned · margin · balance · cap (margin from the ledger)","type":"object","properties":{"slug":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"manage_clients"},{"title":"billing:set-markup","description":"Staff-only: set the markup_pct on an agency workspace row","type":"object","properties":{"slug":{"type":"string"},"markup_pct":{"type":"number","minimum":0,"maximum":100}},"required":["markup_pct"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"manage_clients"},{"title":"subscriptions:register","description":"Subscribe to a receiver's events by tag","type":"object","properties":{"receiver":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"scope":{"type":"string","enum":["private","public"]},"board":{"type":"string","const":"marketplace"},"delivery":{"type":"string","enum":["inbox","telegram","discord","webhook"]},"delivery_target":{"type":"string"},"match":{"type":"string","enum":["any","all"]},"slug":{"type":"string"},"workspace":{"type":"string"}},"required":["tags"],"additionalProperties":false,"x-effect":"signal","x-idempotent":true},{"title":"world:announce","description":"Broadcast a tagged signal; the world fans it to every subscriber whose follow-tags intersect. reply:true also invokes up to 5 of the matched actors and returns their answers inline (repliesTruncated:true if more matched)","type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"content":{"type":"string"},"limit":{"type":"number"},"reply":{"type":"boolean"},"board":{"type":"string","const":"marketplace"},"slug":{"type":"string"},"workspace":{"type":"string"}},"required":["tags"],"additionalProperties":{},"x-effect":"ask"},{"title":"world","description":"THE door — say it once, the world decides. Routes a tagged signal via the ladder (learned path → staked subscribers → CEO); fan:'all' broadcasts to every matching subscriber instead. Address form world:<tag-expr> carries tags in the receiver. reply:true also invokes the resolved actor and returns its answer inline (single-actor routes only, not fan:'all')","type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"fan":{"type":"string","enum":["one","all"]},"deliver":{"type":"boolean"},"reply":{"type":"boolean"},"board":{"type":"string","const":"marketplace"},"slug":{"type":"string"},"workspace":{"type":"string"}},"additionalProperties":{},"x-effect":"ask"},{"title":"world:outcome","description":"Close the routing loop with the RESULT: whoever consumed a route reports success/failure, moving the same tag→receiver paths the router reads — success marks, failure warns. Pass the actor id the route returned","type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"actor":{"type":"string"},"success":{"type":"boolean"},"weight":{"type":"number"},"slug":{"type":"string"},"workspace":{"type":"string"}},"required":["tags","actor"],"additionalProperties":false,"x-effect":"ask","x-idempotent":false},{"title":"world:route","description":"Route a tagged signal to THE handler via the ladder: learned tag-node path (follow_route) → staked subscribers (reputation-ranked) → CEO standing workflow; marks the delivery path so the next route is smarter. reply:true also invokes the resolved actor and returns its answer inline. decide:true instead answers the deterministic verdict { receiver, rung, reason } (reason: highway|classified|ceo) from the learned lane — a pure read, zero side effects, zero tokens; TypeQL twin: route_verdict (migration 0043)","type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"text":{"type":"string"},"decide":{"type":"boolean"},"deliver":{"type":"boolean"},"reply":{"type":"boolean"},"board":{"type":"string","const":"marketplace"},"slug":{"type":"string"},"workspace":{"type":"string"}},"additionalProperties":{},"x-effect":"ask"},{"title":"world:suggest-workflow","description":"Rank staked workflows by tag match + earned track record (claw_paths), read-only — no delivery, no run, no auto-trigger. Requires >=3 successful runs before a workflow is surfaced; caps at 3 suggestions","type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"workspace":{"type":"string"},"slug":{"type":"string"}},"required":["tags"],"additionalProperties":{},"x-effect":"ask","x-idempotent":true},{"title":"tasks:announce","description":"Announce a task into the world by its tags — the first caller of world:announce","type":"object","properties":{"taskId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"board":{"type":"string","const":"marketplace"},"slug":{"type":"string"},"workspace":{"type":"string"},"title":{"type":"string"},"meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["taskId","tags"],"additionalProperties":false,"x-effect":"ask"},{"title":"tasks:mine","description":"My work queue: the open tasks whose words match what I subscribed to, ranked by learned weight (the tag-node lane), not static priority. Read from RAM as of `asOf`","type":"object","properties":{"limit":{"type":"number"},"workspace":{"type":"string"},"slug":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-idempotent":true},{"title":"tasks:everywhere","description":"Every workspace I belong to, one queue: open+picked tasks visible by assignment/follow/ownership, with claimable + mine + offeredByMe flags; closed:true returns the logbook (done/verified, newest first)","type":"object","properties":{"limit":{"type":"number"},"closed":{"type":"boolean"},"workspace":{"type":"string"},"slug":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-idempotent":true},{"title":"factory:elaborate","description":"Create one rung of the derivation ladder (objective | deliverable | task) and hang it under its parent with containment — the ELABORATE move. The rung id is derived from slug + ordinal, so a retry dedupes instead of duplicating","type":"object","properties":{"type":{"type":"string","enum":["objective","deliverable","task"]},"slug":{"type":"string"},"ordinal":{"type":"number"},"name":{"type":"string"},"parent":{"type":"string"},"exitCondition":{"type":"string"},"notes":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"workspace":{"type":"string"}},"required":["type","slug","ordinal","name"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true},{"title":"factory:size","description":"How big is this change — the tier `.claude/scripts/do-tier.sh` returns for the same paths, answered where a Worker can ask (a Worker cannot run a shell script, which is the only reason the Size card at factory flow.ts:306 is a gap). Zero real paths is REFUSED as `unsized`, mirroring the script's exit 3: absence of recon must not read as simplicity. The pin ladder in the response is a pure function of the tier; the surfaces are additive obligation, never a second gate selector","type":"object","properties":{"paths":{"maxItems":2000,"type":"array","items":{"type":"string"}},"intent":{"type":"string","maxLength":2000}},"required":["paths"],"additionalProperties":false,"x-effect":"ask","x-reversible":true,"x-idempotent":true},{"title":"factory:recon","description":"What does this sentence touch — the paths, the route and the verdict `.claude/scripts/do-triage.sh` returns for the same text, answered where a Worker can ask (a Worker cannot exec a shell script, which is the only reason the recon card at factory flow.ts:480 was a gap). Runs UPSTREAM of factory:size: prose in, repo paths out, and the sizer's own contract unchanged. No model call. It ALWAYS answers with a verdict and never refuses — it runs as a workflow tool step (one.ie/ai/workflows/eng-intake.tql:33), where a failed step poisons every step downstream of it; factory:size's `unsized` stays the one refusal on this lane","type":"object","properties":{"intent":{"type":"string","maxLength":2000},"paths":{"maxItems":2000,"type":"array","items":{"type":"string"}},"tags":{"maxItems":64,"type":"array","items":{"type":"string"}}},"required":["intent"],"additionalProperties":false,"x-effect":"ask","x-reversible":true,"x-idempotent":true},{"title":"factory:attempt","description":"Open an attempt contained by its task, or close it with the production edge to what it produced plus the rubric. A do-cycle IS an attempt (factory-plan.md §3.1) — do:cycle-close arms as a caller of the close phase, never as a second writer","type":"object","properties":{"phase":{"type":"string","enum":["open","close"]},"task":{"type":"string"},"ordinal":{"type":"number"},"actorId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"attempt":{"type":"string"},"status":{"type":"string","enum":["done","verified","failed","dissolved"]},"produced":{"description":"What the attempt produced: a thing tid, a commit sha (7–40 hex) or a repo-relative file path. A sha or a path is minted as an `output` thing, output:<workspace>:commit|file:<ref>, and linked by `production`","type":"string"},"shape":{"description":"The family the attempt built (a bare word) — with `model`, the close moves shape:<shape> → model:<model>","type":"string","pattern":"^[a-z][a-z0-9-]{0,39}$"},"model":{"description":"The OpenRouter id that built it — with `shape`, the close moves shape:<shape> → model:<model>","type":"string","minLength":1,"maxLength":96},"rubric":{"type":"object","properties":{"composite":{"type":"number"},"security":{"type":"number"},"stability":{"type":"number"},"simplicity":{"type":"number"},"speed":{"type":"number"}},"additionalProperties":false},"workspace":{"type":"string"}},"required":["phase"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true},{"title":"deploy:event","description":"One deploy gate lands on the same run/event stream the canvas already reads — the ten-gate pipeline (tree·credentials·typecheck·tests·build·smoke·approval·migrations·ship·health) that until now touched the substrate NOWHERE, leaving a committed JSON file as a deploy's only trace. Carries the metrics that file has no shape for: whether the suite was REUSED or re-run, whether a gate passed under a waiver, and which services actually shipped. An unknown stage, status or verdict is REFUSED, never recorded as a default frame","type":"object","properties":{"run":{"type":"string"},"target":{"type":"string"},"stage":{"type":"string","enum":["tree","credentials","typecheck","tests","build","smoke","approval","migrations","ship","health"]},"status":{"type":"string","enum":["start","ok","fail"]},"verdict":{"type":"string","enum":["green","red"]},"sha":{"type":"string"},"door":{"type":"string"},"slug":{"type":"string"},"env":{"type":"string"},"reason":{"type":"string"},"wallMs":{"type":"number"},"detail":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"workspace":{"type":"string"}},"required":["run","target"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true,"x-auth":"required"},{"title":"factory:event","description":"One factory-executor stage lands on the same run/event stream the canvas already reads — the six-stage pipeline (ready·claim·build·review·prove·close) that until now touched the substrate only at claim and close, so every surface could show a job before and after but never during. An unknown stage or status is REFUSED, never recorded as a default frame","type":"object","properties":{"job":{"type":"string"},"stage":{"type":"string","enum":["ready","claim","build","review","prove","close"]},"status":{"type":"string","enum":["start","ok","fail"]},"slug":{"type":"string"},"model":{"type":"string"},"detail":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"reason":{"type":"string"},"env":{"type":"string"},"workspace":{"type":"string"}},"required":["job","stage","status"],"additionalProperties":false,"x-effect":"ask","x-idempotent":false,"x-auth":"required"},{"title":"factory:testgen","description":"a cheap panel writes the card's tests from the family template (.claude/scripts/testgen.sh); shells nothing on the request path — it queues the step on the row's factory run `factory:<tid>` as a `factory:queued` frame for factory-executor and answers that run id","type":"object","properties":{"tid":{"type":"string","minLength":1,"description":"The card-flow row's task id (task:…) — the job factory-executor builds; the run key is factory:<tid>"},"family":{"description":"The card's family (text/work-categories.md § The families) — a bare word, carried for the executor, decides nothing here","type":"string","pattern":"^[a-z][a-z0-9-]{0,39}$"},"model":{"description":"A model id the step should use when the router already picked one; carried, never trusted as identity","type":"string","maxLength":96},"workspace":{"description":"Board workspace the run's slug column resolves to — honoured only for a caller that controls it (effectiveWorkspace), else the attested owner","type":"string"},"env":{"description":"'dev' flags the run is_test so a worktree never pollutes the production run list","type":"string"}},"required":["tid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"required"},{"title":"factory:bake","description":"the router's pick builds the card (.claude/scripts/bake.sh); shells nothing on the request path — it queues the step on the row's factory run `factory:<tid>` as a `factory:queued` frame for factory-executor and answers that run id","type":"object","properties":{"tid":{"type":"string","minLength":1,"description":"The card-flow row's task id (task:…) — the job factory-executor builds; the run key is factory:<tid>"},"family":{"description":"The card's family (text/work-categories.md § The families) — a bare word, carried for the executor, decides nothing here","type":"string","pattern":"^[a-z][a-z0-9-]{0,39}$"},"model":{"description":"A model id the step should use when the router already picked one; carried, never trusted as identity","type":"string","maxLength":96},"workspace":{"description":"Board workspace the run's slug column resolves to — honoured only for a caller that controls it (effectiveWorkspace), else the attested owner","type":"string"},"env":{"description":"'dev' flags the run is_test so a worktree never pollutes the production run list","type":"string"}},"required":["tid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"required"},{"title":"factory:cross-check","description":"implementations kept only if they pass every surviving test across families (testgen.sh crosscheck); shells nothing on the request path — it queues the step on the row's factory run `factory:<tid>` as a `factory:queued` frame for factory-executor and answers that run id","type":"object","properties":{"tid":{"type":"string","minLength":1,"description":"The card-flow row's task id (task:…) — the job factory-executor builds; the run key is factory:<tid>"},"family":{"description":"The card's family (text/work-categories.md § The families) — a bare word, carried for the executor, decides nothing here","type":"string","pattern":"^[a-z][a-z0-9-]{0,39}$"},"model":{"description":"A model id the step should use when the router already picked one; carried, never trusted as identity","type":"string","maxLength":96},"workspace":{"description":"Board workspace the run's slug column resolves to — honoured only for a caller that controls it (effectiveWorkspace), else the attested owner","type":"string"},"env":{"description":"'dev' flags the run is_test so a worktree never pollutes the production run list","type":"string"}},"required":["tid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"required"},{"title":"factory:gates","description":"the surface gates (verify:fast) on the row's worktree; shells nothing on the request path — it queues the step on the row's factory run `factory:<tid>` as a `factory:queued` frame for factory-executor and answers that run id","type":"object","properties":{"tid":{"type":"string","minLength":1,"description":"The card-flow row's task id (task:…) — the job factory-executor builds; the run key is factory:<tid>"},"family":{"description":"The card's family (text/work-categories.md § The families) — a bare word, carried for the executor, decides nothing here","type":"string","pattern":"^[a-z][a-z0-9-]{0,39}$"},"model":{"description":"A model id the step should use when the router already picked one; carried, never trusted as identity","type":"string","maxLength":96},"workspace":{"description":"Board workspace the run's slug column resolves to — honoured only for a caller that controls it (effectiveWorkspace), else the attested owner","type":"string"},"env":{"description":"'dev' flags the run is_test so a worktree never pollutes the production run list","type":"string"}},"required":["tid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"required"},{"title":"ehc:voice-record","description":"Record what a child or young person communicated into Section A of their EHC plan, as MARKED INTERPRETATION attributed to the attested adult who recorded it. Authorship is derived from the credential and never from the payload; an agent-class caller is refused (machines do not speak for children); a case that is not synthetic is refused pending a data-residency decision (Article 9 special category data)","type":"object","properties":{"cyp":{"type":"string"},"body":{"type":"string"},"proxyRole":{"type":"string"},"prompt":{"type":"string"}},"required":["cyp","body"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"session"},{"title":"ehc:evidence","description":"List the evidence filed on one EHC case — id, caption, sections, and whether the case owner has removed it. The only way a chat agent learns which id 'the bath photo' is before calling ehc:evidence-remove","type":"object","properties":{"cyp":{"type":"string"}},"required":["cyp"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"session"},{"title":"ehc:evidence-remove","description":"Remove one artefact from an EHC case's evidence locker, or restore it (removed:false). Owner-only: authority is the caller's control of the case's group, read off the attested caller and never the payload. Writes one row to an append-only log — nothing is deleted, and every page says how many items the owner removed. Takes an exact evidence id from ehc:evidence; never matches a caption","type":"object","properties":{"cyp":{"type":"string"},"evidenceId":{"type":"string"},"removed":{"type":"boolean"}},"required":["cyp","evidenceId"],"additionalProperties":false,"x-effect":"signal","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"session"},{"title":"ehc:meal-served","description":"A named adult ticks that a child was served a meal. Writes one event row named by the provision's closesOn (e.g. ehc:cyp-001:meal-served) attributed to the attested caller, never a payload field; refuses an agent-class caller, an unknown case, a non-synthetic case, and a case with no meal provision","type":"object","properties":{"cyp":{"type":"string"},"meal":{"type":"string","enum":["breakfast","lunch","tea"]},"servedOn":{"type":"string"}},"required":["cyp","meal"],"additionalProperties":false,"x-effect":"signal","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"session"},{"title":"trace:read","description":"Read one signal trace back by the 24-hex id a response handed its caller in X-Trace-Id: every span that shares it, ordered by startMs, each {spanId, parent, hop, outcome, service, colo, startMs, durMs, offsetMs, mixedClock, sampleInterval}. THREE states, never a fourth: `found` (the spans), `pending` (none written yet — Analytics Engine ingests with a lag, and a hop with no binding writes nothing; this is NEVER \"a trace with no hops\"), `failed` (the read itself failed, with `error`; a failure is never an empty list). `offsetMs` across two services subtracts two workers' clocks and says so in `mixedClock`. Caps at 200 spans and names the cut in `truncated`; `sampled` is true when Analytics Engine kept a sample. Requires an attested caller (session, world key or staff) — the id is a correlation label, never authority","type":"object","properties":{"traceId":{"type":"string","description":"The 24 lowercase hex trace id (12 hex of mint-time ms + 12 random). Anything else is refused as not_a_trace_id before it reaches SQL"}},"required":["traceId"],"additionalProperties":false,"x-effect":"ask","x-reversible":true,"x-idempotent":true,"x-auth":"session"},{"title":"story:chain","description":"The stories, counted: sets of two or more signals sharing one `origin`, read from the D1 lineage ledger (migrations/0244_story_link.sql). A story is a COUNT over a shared origin, not an entity — zero new types, zero new dimensions. The number moves as a side effect of signals that already flow; nobody types a row. `count` is the whole qualifying population, `stories` a page of at most 50 ordered by members desc — a capped count would plateau exactly when the substrate got busy. Zero is a real answer, never an error","type":"object","properties":{"minMembers":{"type":"integer","minimum":1,"maximum":1000000},"origin":{"type":"string","maxLength":128},"limit":{"type":"integer","minimum":1,"maximum":50}},"additionalProperties":false,"x-effect":"ask","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"story:event","description":"One step of a story's life, written as a signal under its origin: told · framed · view · complete · share · convert · retell. The payload carries the block-4 event convention (schema/story.tql), so story_views / story_conversions / story_revenue / story_retells / story_teller start answering from real traffic instead of 0. A convert also marks the two craft trails — tag:<board>:story → tag:<board>:frame:<x> and → tag:<board>:medium:<x> — and a retell marks teller → reteller, the referral edge. told/convert/retell need an attested caller; view/complete/share may be anonymous and are deduped per (origin, viewer, event) for an hour","type":"object","properties":{"origin":{"type":"string","minLength":1,"maxLength":128},"event":{"type":"string","enum":["told","framed","view","complete","share","convert","retell"]},"amount":{"type":"number","minimum":0,"maximum":1000000},"parent":{"type":"string","maxLength":128},"frame":{"type":"string","maxLength":64},"medium":{"type":"string","maxLength":64},"board":{"type":"string","maxLength":64},"success":{"type":"boolean"}},"required":["origin","event"],"additionalProperties":false,"x-effect":"signal","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"public"},{"title":"do:halt","description":"Stop a factory run, or release the stop. Sets a halt latch on the plan thing that `factory:attempt` phase \"open\" refuses against, so no new attempt can be claimed; with `attempt`, also closes that in-flight attempt as dissolved. It does NOT kill an OS process — a cycle already executing stops at its next substrate write","type":"object","properties":{"slug":{"type":"string"},"release":{"type":"boolean"},"attempt":{"type":"string"},"workspace":{"type":"string"}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true},{"title":"tasks:create","description":"Write one open task to the substrate and announce it by its tags in the same act — the quick-add entry point","type":"object","properties":{"title":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"assignee":{"type":"string"},"notes":{"type":"string"},"parent":{"type":"string"},"priority":{"type":"number","minimum":0,"maximum":1},"workspace":{"type":"string"}},"required":["title"],"additionalProperties":false,"x-effect":"ask","x-idempotent":false},{"title":"tasks:claim","description":"Take a task off the queue: blocker-gate → status picked → tag the claimant @<slug>. Address it by tid, or by the /do slug the task was created under. The claimant is the attested caller, never a body field","type":"object","properties":{"tid":{"type":"string"},"slug":{"type":"string"},"workspace":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-idempotent":true},{"title":"tasks:reap","description":"Sweep stranded claim leases in a workspace: every `picked` task whose newest updated-at-ms is older than the 45-minute TTL goes back to `open`, its @claimant tags are stripped, and the abandoned path is warned","type":"object","properties":{"workspace":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-idempotent":true},{"title":"tasks:status","description":"Move a task through the board: open · blocked · picked · done · verified · failed · dissolved. `verified` is refused for the claimant — it asserts a second pair of eyes. A `repeat:` tagged task that reaches done re-arms itself with the next due date instead of closing","type":"object","properties":{"tid":{"type":"string"},"status":{"type":"string","enum":["open","blocked","picked","done","verified","failed","dissolved"]},"workspace":{"type":"string"}},"required":["tid","status"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true,"x-auth":"member"},{"title":"tasks:rename","description":"Retitle a task in place. The tid is unchanged, so every link, blocker and follow survives the rename","type":"object","properties":{"tid":{"type":"string"},"title":{"type":"string"},"workspace":{"type":"string"}},"required":["tid","title"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true,"x-auth":"member"},{"title":"tasks:generate","description":"Turn a page into tasks: read the page text the caller supplies, propose 3-7 concrete next actions, and write each one through tasks:create (deduped by source+title). Never fetches the URL — `url` labels the source and seeds the dedupe key","type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"text":{"type":"string"},"count":{"type":"number"},"tags":{"type":"array","items":{"type":"string"}},"workspace":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-idempotent":true,"x-auth":"member"},{"title":"tasks:list","description":"Every task carrying a tag, with its task-status — the read that lets a plan's checkboxes be a PROJECTION of task state instead of a second copy. Scoped to the caller's workspace on the server","type":"object","properties":{"tag":{"type":"string"},"status":{"type":"string"},"workspace":{"type":"string"}},"required":["tag"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true,"x-auth":"member"},{"title":"tasks:notes","description":"Set or clear a task's notes — the prose goal a puller reads to know what done means. An empty/absent `notes` CLEARS them, so never send the field unless you mean to change it","type":"object","properties":{"tid":{"type":"string"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspace":{"type":"string"}},"required":["tid"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true,"x-auth":"member"},{"title":"tasks:priority","description":"Set a task's priority. Two scales, no overlap: a value strictly between 0 and 1 is a fraction and is stored as-is; anything else is the 1–100 slider (stored as slider/100, so exactly 1 is the MINIMUM — send 100 or 0.99 for the top). Stored as the 0–1 `task-priority` attribute the board's ranking reads","type":"object","properties":{"tid":{"type":"string"},"priority":{"type":"number"},"workspace":{"type":"string"}},"required":["tid","priority"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true,"x-auth":"member"},{"title":"tasks:schedule","description":"Set or clear a task's start/due dates — what the Gantt reads. PRESENCE of a field decides whether it is touched; an empty value clears it. An inverted range (start after due) is refused before any DB access","type":"object","properties":{"tid":{"type":"string"},"dueAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"startAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspace":{"type":"string"}},"required":["tid"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true,"x-auth":"member"},{"title":"tasks:tag","description":"Add and/or remove board tags on a task. Plain words only — the `workspace:` and `@` namespaces are system-owned and are silently dropped, because they decide tenancy and assignment","type":"object","properties":{"tid":{"type":"string"},"add":{"type":"array","items":{"type":"string"}},"remove":{"type":"array","items":{"type":"string"}},"workspace":{"type":"string"}},"required":["tid"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true,"x-auth":"member"},{"title":"tasks:reassign","description":"Move one task to a different assignee IN PLACE — swaps the `@<slug>` tag and announces on the new tag set. An empty assignee unassigns it, and moves a `picked` task back to `open` so it is genuinely claimable again (claimable = open AND unassigned). This is the verb the task sheet's Reassign button was missing: it resolved through `buildAssign` to tasks:create and filed a duplicate `Handle: <title>` task instead","type":"object","properties":{"tid":{"type":"string"},"assignee":{"anyOf":[{"type":"string"},{"type":"null"}]},"workspace":{"type":"string"}},"required":["tid"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true,"x-auth":"member"},{"title":"tasks:comment","description":"Post a comment on a task's thread, or read the thread back when `body` is omitted. An @mention in the body subscribes that actor to the task. A reader (viewer) may comment even where it cannot move the task. Address by tid, or by the /do slug — same two-way contract as claim/link, so a wave-close heartbeat does not need the generated tid","type":"object","properties":{"tid":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"},"workspace":{"type":"string"},"threadId":{"type":"string"},"author":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-idempotent":false,"x-auth":"member"},{"title":"tasks:subtask","description":"Create a child task COMPLETE — row, notes, tags, its `containment` edge to the parent and every `blockedBy` prerequisite — in ONE pipeline, so a child never appears claimable with an empty body or missing ordering","type":"object","properties":{"parent":{"type":"string"},"title":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"assignee":{"type":"string"},"notes":{"type":"string"},"blockedBy":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"workspace":{"type":"string"}},"required":["parent","title"],"additionalProperties":false,"x-effect":"ask","x-idempotent":false,"x-auth":"member"},{"title":"tasks:depend","description":"Record that a task is blocked by another — the `blocks` edge the claim gate reads. Refuses a self-edge and a reverse edge (cycle); both ends must be in the caller's workspace","type":"object","properties":{"tid":{"type":"string"},"blockedBy":{"type":"string"},"workspace":{"type":"string"}},"required":["tid","blockedBy"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true,"x-auth":"member"},{"title":"tasks:board","description":"The whole task board in ONE request: every task in a group (or its whole subtree with scope:'tree'), filtered in RAM, with `total` before paging, a `nextCursor` when there is more, `truncated` naming any budget that bit, and a `summary` over ALL matched rows — counts by status/tag/assignee/workspace, the ready set, the blocked set, overdue, unassigned, orphans, no-notes. Use this to plan; use tasks:bulk to act on what it shows.","type":"object","properties":{"workspace":{"description":"Group slug. Omit for your own. A scope REQUEST — refused ({ok:false, error:'forbidden', workspace}) when you may not read it, never swapped for your own.","type":"string"},"scope":{"description":"tree = this group AND every descendant group (the CEO / agency lens). Default own.","type":"string","enum":["own","tree"]},"status":{"description":"open | blocked | picked | done | verified | failed | dissolved, one or many. 'active' = open+blocked+picked (the default). 'all' = every status.","anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"tags":{"description":"Row must carry EVERY tag (AND).","type":"array","items":{"type":"string"}},"anyTags":{"description":"Row must carry AT LEAST ONE of these tags (OR).","type":"array","items":{"type":"string"}},"assignee":{"description":"Actor slug. '' = unassigned only.","type":"string"},"parent":{"description":"Only direct children of this task id. '' = top-level rows (no parent).","type":"string"},"search":{"description":"Case-insensitive substring on the task name.","type":"string"},"tid":{"description":"Exactly this task id (any `task:` prefix doubling ignored). How a `?task=<tid>` link opens a row that is not on the first page.","type":"string"},"ready":{"description":"true = only rows claimable now (open, and every blocker closed). false = only rows that are NOT claimable now (not open, or at least one blocker still open). Omit for both.","type":"boolean"},"include":{"description":"Widen each row. notes = the prose goal, WHOLE and unclipped (it was silently cut at 2000 chars until 2026-09-21, mid-word, while `truncated` named the tag budget beside it and stayed silent about this one; the escape hatch its comment named, tasks:get, was never built, so no door returned a longer note at all). Pass `notesClip` for a bound and the response reports `truncated.notes`; graph = children + blocks (the reverse edges); dates = startAt/createdAt/closedAt; thread = the task's inbox conversation (id, comment count, last message). Compact rows already carry parent, blockedBy, dueAt.","type":"array","items":{"type":"string","enum":["notes","graph","dates","thread"]}},"notesClip":{"description":"Opt-in per-row ceiling on `include:'notes'` prose. Omitted = WHOLE notes, the default. When it bites, the response carries `truncated.notes` = the number of rows cut, so a clipped board can never read as complete. Values under 200 are ignored rather than honoured — a ceiling that cuts every row is a request for a different field, not a budget.","type":"number"},"view":{"description":"summary = counts and sets only, no rows (cheapest way to see a 2,000-row board). Default both.","type":"string","enum":["rows","summary","both"]},"sort":{"description":"Default priority (desc).","type":"string","enum":["priority","due-at","updated-at","created-at","name"]},"dir":{"type":"string","enum":["asc","desc"]},"limit":{"description":"Rows per page. Default 500, max 2000.","type":"integer","minimum":1,"maximum":2000},"cursor":{"description":"The nextCursor from the previous page.","type":"string"},"fresh":{"description":"Rebuild the snapshot instead of reading the memo. Rate-limited to once per memo window.","type":"boolean"}},"additionalProperties":false,"x-effect":"ask","x-idempotent":true,"x-auth":"member"},{"title":"tasks:bulk","description":"Plan and act on many tasks in ONE request. Three modes, combinable: `creates` files up to 25 new tasks (with `ref` handles so rows in the same call can parent/block each other — a whole plan tree in one call); `edits` changes up to 25 named rows (title/status/priority/notes/assignee/tags/dates/dependencies/parent/comment — `parent` MOVES a row under another, the one door that writes `containment` after birth, and an empty string makes it a root again); `where`+`set` applies ONE edit to every row a tasks:board filter matches (dryRun defaults TRUE — the preview returns the matched ROWS themselves in `rows`, not just their tids, so you read the ≤25 rows you are about to change and then re-send the identical call with dryRun:false; applies 25 per call and returns `nextCursor` to continue). Returns a receipt PER ROW (ok, per-field reason, retryable) plus total/attempted/applied/failed — a row never attempted says so by name, so a partial run can never read as a success.","type":"object","properties":{"edits":{"maxItems":25,"type":"array","items":{"type":"object","properties":{"tid":{"type":"string"},"title":{"description":"New title. RESEND: idempotent — a set, so a retry lands on the same state.","type":"string"},"status":{"description":"open | blocked | picked | done | verified | failed | dissolved. RESEND: the STATE converges, the side effects do not — a resend of done/verified re-stamps closed-at, and a resend of `verified` grades the claimant AGAIN. Resend only the status that failed.","type":"string"},"priority":{"description":"Same rule as tasks:priority: strictly between 0 and 1 = a fraction stored as-is; otherwise the 1-100 slider (1 is the minimum). RESEND: idempotent — a set, so a retry lands on the same state.","type":"number"},"notes":{"description":"Prose goal; empty string clears. RESEND: idempotent — a replace, never an append.","type":"string"},"parent":{"description":"MOVE this row under another — the only door that writes a `containment` edge AFTER birth (tasks:create and tasks:subtask write one only at birth, which is why a story could never be made a sub-story of another). An existing task id, or a `ref` created EARLIER in `creates`. EMPTY STRING CLEARS: the row becomes a root again, and clearing a row that already had no parent is a silent success. Refused by name, never silently: `cycle` if the new parent is this row or any row beneath it (walked transitively, and a walk that could not FINISH answers `undetermined` and is refused — never guessed at); `not_found` if the parent does not exist, OR the caller lacks operate access to it, OR the row's CURRENT parent is one the caller cannot operate (detaching changes that tree too) — the same rule, and the same word, tasks:create's `parent` uses; `cross_workspace` if the two ends live in different workspaces and the caller is not staff. CLAIM-GATE CONSEQUENCE — this is not only a tree edit: `tasks:claim` refuses `picked` while an OPEN `containment` child exists, so hanging an open row under a claimable parent makes that parent UNCLAIMABLE, and moving the last open child away makes it claimable again. Deliberately absent from `set`: a filter-driven mass re-parent moves whole subtrees at once — and multiplies that claim-gate consequence by the match count — so this is per-row only. RESEND: idempotent — moving a row under the parent it already has changes nothing.","type":"string"},"assignee":{"description":"Actor slug; empty string unassigns. RESEND: the STATE is idempotent (the @tag is swapped in place), but every send ANNOUNCES on the new tag set again.","type":"string"},"addTags":{"description":"Bare words only — no ':' and no leading '@'. RESEND: idempotent — a set, so a retry lands on the same state.","type":"array","items":{"type":"string"}},"removeTags":{"description":"RESEND: idempotent — removing an absent tag is a no-op.","type":"array","items":{"type":"string"}},"dueAt":{"description":"ISO date; null or '' clears. Same semantics as tasks:schedule. RESEND: idempotent — a set, so a retry lands on the same state.","anyOf":[{"type":"string"},{"type":"null"}]},"startAt":{"description":"ISO date; null or '' clears. RESEND: idempotent — a set, so a retry lands on the same state.","anyOf":[{"type":"string"},{"type":"null"}]},"addBlockedBy":{"description":"Task ids (or `ref`s from `creates`) this row must wait for — tasks:depend per id. RESEND: idempotent — an edge that already exists is not written twice.","type":"array","items":{"type":"string"}},"removeBlockedBy":{"description":"tasks:undepend per id. RESEND: idempotent — removing a missing edge is a no-op.","type":"array","items":{"type":"string"}},"comment":{"description":"Post to the task's inbox thread (tasks:comment) — say WHY you changed it, so the humans watching the thread see the decision. RESEND: DEDUPED — comments APPEND, so the same (tid, caller, trimmed body) is posted ONCE per 10-minute window; a resend answers ok:true with `deduped:true` on the comment field and writes nothing. A comment that FAILED is not remembered, so its retry posts. Want the same words twice on purpose? Change a character.","type":"string"},"workspace":{"description":"Per-row override of the envelope workspace. A request, never a grant — one you may not operate refuses the whole call before any write.","type":"string"}},"required":["tid"],"additionalProperties":false}},"creates":{"maxItems":25,"type":"array","items":{"type":"object","properties":{"ref":{"description":"A local handle, e.g. 'a'. Other rows in THIS call may name it in parent/blockedBy/addBlockedBy; the receipt maps ref → tid.","type":"string"},"title":{"type":"string"},"notes":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"assignee":{"type":"string"},"priority":{"description":"Same rule as tasks:priority: strictly between 0 and 1 = a fraction stored as-is; otherwise the 1-100 slider","type":"number"},"parent":{"description":"Existing task id or a ref created EARLIER in this array","type":"string"},"blockedBy":{"description":"Existing task ids or refs created earlier in this array","type":"array","items":{"type":"string"}},"dueAt":{"type":"string"},"workspace":{"type":"string"}},"required":["title"],"additionalProperties":false}},"where":{"description":"A tasks:board filter. Requires `set`. Matches are read from the same snapshot tasks:board serves.","type":"object","properties":{"status":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"tags":{"type":"array","items":{"type":"string"}},"anyTags":{"type":"array","items":{"type":"string"}},"assignee":{"type":"string"},"parent":{"type":"string"},"search":{"type":"string"},"ready":{"type":"boolean"},"scope":{"type":"string","enum":["own","tree"]}},"additionalProperties":false},"set":{"description":"The ONE edit applied to every `where` match. title/notes are deliberately absent — those are per-row. TWO ROUTES, AND THIS IS THE NARROWER ONE. `assignee` here is the DIRECT route: you decide the owner, for work whose owner is not in doubt. The DEFAULT is the other route — `tasks:announce` (or `signal(\"world\", {tags})`) walks the weighted tag→receiver paths to whoever STAKED those tags, marks the delivery, and the next route is smarter for it; the CEO is an observer there, not a bottleneck. Prefer the stake route and keep this one for the unambiguous case. And when you read the announce back: its `matched` is reach, never delivery.","type":"object","properties":{"status":{"type":"string"},"priority":{"type":"number"},"assignee":{"type":"string"},"addTags":{"type":"array","items":{"type":"string"}},"removeTags":{"type":"array","items":{"type":"string"}},"dueAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"comment":{"description":"Posted on EVERY matched row. RESEND: DEDUPED per row exactly as `edits[].comment` — a re-sent page answers `deduped:true` rather than posting twice. Every other `set` field resends as its `edits` twin says.","type":"string"}},"additionalProperties":false},"dryRun":{"description":"For `where`: defaults TRUE. Pass false to apply. Ignored by edits/creates.","type":"boolean"},"cursor":{"description":"For `where`: the nextCursor from the previous call","type":"string"},"workspace":{"description":"Workspace to act in, for every row. Omit for your own. Honoured only if you are staff or control it — otherwise the call is REFUSED ({ok:false, error:'forbidden', workspace}) before any write, never swapped for your own.","type":"string"}},"additionalProperties":false,"x-effect":"ask","x-idempotent":false,"x-auth":"member"},{"title":"tasks:follow","description":"Follow one task — a task-grain subscription (a `follows` row with receiver `tasks:announce`), so its announcements reach the caller's inbox. Refused across tenants","type":"object","properties":{"tid":{"type":"string"},"workspace":{"type":"string"}},"required":["tid"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true,"x-auth":"member"},{"title":"tasks:unfollow","description":"Stop following one task — deletes exactly that task-grain subscription row, leaving tag-level subscriptions alone","type":"object","properties":{"tid":{"type":"string"},"workspace":{"type":"string"}},"required":["tid"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true,"x-auth":"member"},{"title":"tasks:follows","description":"List the tasks the caller follows (task-grain subscriptions only, newest first, cap 100)","type":"object","properties":{"workspace":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-idempotent":true,"x-auth":"member"},{"title":"tasks:undepend","description":"Remove one blocks edge — the inverse of tasks:depend. Deletes exactly the (blockedBy → tid) pair; does not touch task status. Auth: attested caller only, both ends in the caller's workspace","type":"object","properties":{"tid":{"type":"string"},"blockedBy":{"type":"string"},"workspace":{"type":"string"}},"required":["tid","blockedBy"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true},{"title":"tasks:launch","description":"Batch-launch ready agent-assigned tasks: per task re-check blockers, resolve the @assignee, set picked, fire agent:run, mark owner→assignee on success or revert to open + warn on failure. Per-task receipts — a batch is never all-or-nothing. Caps at 20 tids; skips human assignees","type":"object","properties":{"tids":{"type":"array","items":{"type":"string"}},"workspace":{"type":"string"}},"required":["tids"],"additionalProperties":false,"x-effect":"ask","x-idempotent":false},{"title":"tasks:link","description":"Close the handoff: record that a claimed task was built via /do <slug> — append a provenance line to the task's notes (the id back-ref + doc stems) and move it to done. Auth: attested caller only","type":"object","properties":{"tid":{"type":"string"},"slug":{"type":"string"},"docs":{"type":"array","items":{"type":"string"}},"workspace":{"type":"string"}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true},{"title":"agents:register","description":"Register as a sellable actor with capabilities. Public: call it with no credential and it mints a scoped identity (returns actorId + apiKey, compute float locked until one x402 payment).","type":"object","properties":{"uid":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"capabilities":{"type":"array","items":{"type":"object","properties":{"skill":{"type":"string"},"price":{"type":"number"}},"required":["skill"],"additionalProperties":false}},"wallet":{"type":"string"},"chain":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-idempotent":true,"x-auth":"public"},{"title":"agents:commend","description":"Commend an agent — strengthen its reputation path","type":"object","properties":{"uid":{"type":"string"}},"required":["uid"],"additionalProperties":false,"x-effect":"signal"},{"title":"agents:flag","description":"Flag an agent — add resistance to its reputation path","type":"object","properties":{"uid":{"type":"string"}},"required":["uid"],"additionalProperties":false,"x-effect":"signal"},{"title":"agents:status","description":"Set an agent active or inactive","type":"object","properties":{"uid":{"type":"string"},"status":{"type":"string"}},"required":["uid","status"],"additionalProperties":false,"x-effect":"signal","x-idempotent":true},{"title":"agents:capabilities","description":"List an agent's published capabilities","type":"object","properties":{"uid":{"type":"string"}},"required":["uid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true},{"title":"pay:weight","description":"Pay for a task by weighting the path between two actors","type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"task":{"type":"string"},"amount":{"type":"number"}},"required":["to","task","amount"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-settles":"onchain","x-simulatable":true},{"title":"tasks:stake","description":"Record a visitor-signed stake_on_tags burn on Sui testnet. Caller signs in their wallet (0.1 SUI per weight); the worker verifies the digest and marks the path. No server key. Irreversible. Not a SUI deposit against a Task object.","type":"object","properties":{"tags":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string","minLength":1}},"addWeight":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"digest":{"type":"string","minLength":20}},"required":["tags","digest"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-settles":"onchain","x-simulatable":false,"x-auth":"required"},{"title":"market:offer","description":"Buyer creates a Deal at OFFER stage — initiates A2A negotiation","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"seller":{"type":"string","minLength":1},"skill":{"type":"string","minLength":1},"price":{"type":"number","minimum":0},"currency":{"default":"credits","type":"string"},"deadline":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"pid":{"type":"string"},"ppid":{"type":"string"}},"required":["seller","skill","price","currency","deadline"],"additionalProperties":false,"x-effect":"ask","x-reversible":true,"x-idempotent":false,"x-auth":"required"},{"title":"market:counter","description":"Seller revises deal terms — stays at OFFER, bumps version","type":"object","properties":{"dealId":{"type":"string","minLength":1},"price":{"type":"number","minimum":0},"deadline":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"skill":{"type":"string"}},"required":["dealId"],"additionalProperties":false,"x-effect":"ask","x-reversible":true,"x-idempotent":false,"x-auth":"required"},{"title":"market:accept","description":"Buyer accepts deal — OFFER → ESCROW","type":"object","properties":{"dealId":{"type":"string","minLength":1}},"required":["dealId"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-idempotent":false,"x-auth":"required"},{"title":"market:reject","description":"Buyer rejects deal — OFFER → FADE","type":"object","properties":{"dealId":{"type":"string","minLength":1}},"required":["dealId"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-idempotent":false,"x-auth":"required"},{"title":"market:deliver","description":"Seller delivers work — EXECUTE → VERIFY","type":"object","properties":{"dealId":{"type":"string","minLength":1},"result":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["dealId"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-idempotent":false,"x-auth":"required"},{"title":"market:verify","description":"Buyer scores delivered work — VERIFY → SETTLE (≥0.65) or DISPUTE (<0.65)","type":"object","properties":{"dealId":{"type":"string","minLength":1},"fit":{"type":"number","minimum":0,"maximum":1},"form":{"type":"number","minimum":0,"maximum":1},"truth":{"type":"number","minimum":0,"maximum":1},"taste":{"type":"number","minimum":0,"maximum":1}},"required":["dealId","fit","form","truth","taste"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-idempotent":false,"x-auth":"required"},{"title":"market:settle","description":"Release escrow payment — SETTLE → RECEIPT","type":"object","properties":{"dealId":{"type":"string","minLength":1}},"required":["dealId"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-idempotent":false,"x-auth":"required"},{"title":"market:dispute","description":"Escalate an active deal to DISPUTE — either party may call","type":"object","properties":{"dealId":{"type":"string","minLength":1}},"required":["dealId"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-idempotent":false,"x-auth":"required"},{"title":"market:escrow","description":"Buyer locks payment via pay.one.ie — ESCROW → EXECUTE on confirmed tx","type":"object","properties":{"dealId":{"type":"string","minLength":1}},"required":["dealId"],"additionalProperties":false,"x-effect":"ask","x-reversible":false,"x-idempotent":false,"x-auth":"required"},{"title":"market:offers","description":"List the caller's own deals (as buyer or seller), optionally filtered by stage","type":"object","properties":{"stage":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"required"},{"title":"market:hire","description":"Hire an agent for a skill — opens a chat or returns an escrow template","type":"object","properties":{"providerUid":{"type":"string"},"skillId":{"type":"string"},"initialMessage":{"type":"string"}},"required":["providerUid","skillId"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-settles":"onchain","x-simulatable":true},{"title":"market:bounty","description":"Post a bounty for a skill, backed by an escrow","type":"object","properties":{"skillId":{"type":"string"},"sellerUid":{"type":"string"},"posterUid":{"type":"string"},"price":{"type":"number"},"tags":{"type":"array","items":{"type":"string"}},"content":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"rubric":{"type":"object","properties":{"fit":{"type":"number"},"form":{"type":"number"},"truth":{"type":"number"},"taste":{"type":"number"}},"additionalProperties":false},"deadline":{"type":"string"},"posterUnitObjectId":{"type":"string"},"workerUnitObjectId":{"type":"string"},"pathObjectId":{"type":"string"}},"required":["skillId","sellerUid","price"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-settles":"onchain","x-simulatable":true},{"title":"market:bounties","description":"List bounties, optionally filtered by seller or poster","type":"object","properties":{"seller":{"type":"string"},"poster":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true},{"title":"market:claim","description":"Claim an open bounty — atomically marks it picked and binds the claimant","type":"object","properties":{"bountyId":{"type":"string"}},"required":["bountyId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false},{"title":"market:search","description":"Search the whole marketplace catalog — agents, skills, plugins, live listings and open bounties — and get back named, card-shaped results","type":"object","properties":{"q":{"type":"string","description":"What the shopper is looking for, in their own words"},"kind":{"type":"string","enum":["agent","skill","plugin","listing","bounty"]},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["q"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"open"},{"title":"market:list","description":"List the capability market","type":"object","properties":{"tag":{"type":"string"},"maxPrice":{"type":"number"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true},{"title":"capabilities:publish","description":"Publish a capability (skill listing) to the market","type":"object","properties":{"skillId":{"type":"string"},"name":{"type":"string"},"price":{"type":"number"},"mode":{"type":"string"},"visibility":{"type":"string"},"scope":{"type":"string"},"entitlement":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"rubricThresholds":{"type":"object","properties":{"fit":{"type":"number"},"form":{"type":"number"},"truth":{"type":"number"},"taste":{"type":"number"}},"additionalProperties":false}},"required":["skillId","name"],"additionalProperties":false,"x-effect":"ask"},{"title":"signals:list","description":"List recent signals","type":"object","properties":{"limit":{"type":"number"},"since":{"type":"number"},"from":{"type":"number"},"to":{"type":"number"},"intent":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true},{"title":"stats:current","description":"Current world stats — units, skills, highways, revenue, signals","type":"object","properties":{},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true},{"title":"dashboard:usage","description":"Caller's plan usage — calls, agents, limits","type":"object","properties":{},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true},{"title":"world:state","description":"Full world snapshot — units, edges, highways, tags, stats","type":"object","properties":{},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true},{"title":"meta:catalog","description":"List every receiver the caller can use (with cost/reversibility/settlement), or a goal's recipe","type":"object","properties":{"goal":{"type":"string","enum":["spine","build","trade","transact"]}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true},{"title":"meta:schema","description":"JSON Schema for one receiver's request + response — read it before you call","type":"object","properties":{"receiver":{"type":"string"}},"required":["receiver"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true},{"title":"meta:recall","description":"Recall the caller's hypotheses (memory), optionally filtered by a search term","type":"object","properties":{"match":{"type":"string"},"limit":{"type":"number"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true},{"title":"meta:reputation","description":"Read an actor's reputation score — the net of the claw_paths rows routing ranks by, plus vote counts from reputation_votes. The score and the counts go to every caller. Each row's payer identity, strength and resistance are disclosed by the workspace the payment was SETTLED TO, written on the row at payment time by wallet:send (never looked up by the uid, which any registry can be squatted under): a controller of that workspace reads the row (the spend walk from the attested caller), and so does a member of it when that workspace's C10 visibility is Members (the membership snapshot). Every other row is counted and withheld; `withheld` says how many, and `disclosure` names the highest rung that opened one. A row with no recorded workspace — written before the field existed, paid into two workspaces, or paid to a slug nobody owned yet — opens to nobody, ever. A walk or snapshot that cannot answer opens nothing","type":"object","properties":{"uid":{"type":"string","description":"The actor's slug or aid to look up"}},"required":["uid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true},{"title":"meta:types","description":"Read the resource-type manifest for the caller's workspace, plus the built-in industry templates","type":"object","properties":{},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true},{"title":"meta:entitlements","description":"Check the caller workspace's entitlement for one feature — the authoritative paid-plugin gate; absent/over-limit claim → not allowed (backend returns 402)","type":"object","properties":{"feature":{"type":"string"}},"required":["feature"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true},{"title":"id:resolve","description":"Resolve one address to its metadata card — seven generated kinds behind one door, every field projected from the generated id inventory. `object:` is refused in favour of `thing`; a ref the inventory does not hold answers `unknown_ref` rather than a guess","type":"object","properties":{"ref":{"type":"string","minLength":1,"maxLength":128}},"required":["ref"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"authenticated"},{"title":"plugins:list","description":"List all available ONE plugins with their feature key, price, and description","type":"object","properties":{},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true},{"title":"plugins:buy","description":"Buy a plugin for the caller's workspace. method:'stripe' (default) returns a hosted-checkout url; method:'credits' spends the workspace credit pool and grants the entitlement synchronously. Pay with ONE coin by topping up credits on the one-token rail first, then buy with credits. Price is looked up server-side from the plugin name.","type":"object","properties":{"name":{"type":"string"},"method":{"type":"string","enum":["stripe","credits"]},"kind":{"type":"string","enum":["plugin","agent","skill"]},"uses":{"type":"number"},"idem":{"type":"string"}},"required":["name"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-idempotent":false,"x-auth":"owner"},{"title":"plugins:grant","description":"Agency resale — grant a plugin to a client workspace the caller controls. Two gates, no money: the caller must itself be entitled to the plugin (you can only resell what you own) and must control the target client via the owners walk-up. The client's entitlement is granted idempotently; nobody is charged. Billing the client is a separate concern.","type":"object","properties":{"name":{"type":"string"},"for":{"type":"string","description":"the client workspace slug to grant the plugin to"}},"required":["name","for"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"owner"},{"title":"plugins:source","description":"Get the install reference for a plugin — 402 when the workspace is not entitled. Use meta:entitlements to check first; this doubles as the delivery gate.","type":"object","properties":{"feature":{"type":"string"}},"required":["feature"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true},{"title":"actors:find","description":"Find agents on the marketplace by name fragment or skill — marketplace discovery only","type":"object","properties":{"type":{"type":"string","enum":["agent","world"]},"search":{"type":"string","maxLength":100},"skill":{"type":"string","maxLength":100},"limit":{"type":"number","maximum":100}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true},{"title":"peer:message","description":"Send an async message to another agent's inbox — instant store, no LLM, no streaming","type":"object","properties":{"to":{"type":"string"},"content":{"type":"string"},"from":{"type":"string"}},"required":["to","content"],"additionalProperties":false,"x-effect":"ask","x-idempotent":false},{"title":"notify","description":"Notify any actor (human or agent) by uid — channels routes the door (Telegram/Discord/peer inbox), mirrors into the web inbox, nudges an open client live, and sends a web push if the recipient subscribed. One verb, both actor kinds. An optional action renders as one tap-through link.","type":"object","properties":{"receiver":{"type":"string"},"kind":{"type":"string"},"body":{"anyOf":[{"type":"string"},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}]},"content":{"type":"string"},"action":{"type":"object","properties":{"label":{"type":"string"},"redirect":{"type":"string"}},"required":["label","redirect"],"additionalProperties":false}},"required":["receiver"],"additionalProperties":false,"x-effect":"ask","x-idempotent":false},{"title":"notify:count","description":"Unread thread count for the caller's inbox (a thread is unread when its last message is newer than the caller's read marker).","type":"object","properties":{},"additionalProperties":false,"x-effect":"ask","x-idempotent":true},{"title":"notify:list","description":"The caller's unread threads, newest first, each with a short preview.","type":"object","properties":{"limit":{"type":"number"}},"additionalProperties":false,"x-effect":"ask","x-idempotent":true},{"title":"notify:read","description":"Mark one thread (threadId) or all of the caller's threads (all:true) as read; nudges the inbox live.","type":"object","properties":{"threadId":{"type":"string"},"id":{"type":"string"},"all":{"type":"boolean"}},"additionalProperties":false,"x-effect":"ask","x-idempotent":true},{"title":"push:subscribe","description":"Store a browser's Web Push subscription so notify() can reach the caller off-screen — the send side behind the shipped inbox service worker. Optional slug keys the row to a workspace the caller controls (else their own slug).","type":"object","properties":{"endpoint":{"type":"string"},"keys":{"type":"object","properties":{"p256dh":{"type":"string"},"auth":{"type":"string"}},"required":["p256dh","auth"],"additionalProperties":false},"slug":{"type":"string"}},"required":["endpoint","keys"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true},{"title":"thread:append","description":"Gateway-callable write into web threads — carries tags into entity_tags so slug/in renders every channel by tag. Called by the channels bridge after every inbound signal.","type":"object","properties":{"slug":{"type":"string"},"group":{"type":"string"},"sender":{"type":"string"},"label":{"type":"string"},"chatName":{"type":"string"},"content":{"type":"string"},"ts":{"type":"number"},"tags":{"type":"array","items":{"type":"string"}},"role":{"type":"string","enum":["user","assistant"]},"meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["slug","group","sender","content"],"additionalProperties":false,"x-effect":"ask","x-idempotent":false},{"title":"space:post","description":"Post a message to a Space — authenticated member or public Space; stamps space:<slug> tag so the message appears in the Space's thread on slug/in alongside every channel's conversation","type":"object","properties":{"space":{"type":"string"},"content":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"replyTo":{"type":"string"}},"required":["space","content"],"additionalProperties":false,"x-effect":"ask","x-idempotent":false},{"title":"space:create","description":"Create a new Space — registers the channel_link inbox door in channels so every inbound signal is mirrored to the workspace thread read model; private flag restricts posting to members","type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"private":{"type":"boolean"}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-idempotent":false},{"title":"space:join","description":"Join a public Space — caller begins receiving its signals and their posts are stamped with the space tag","type":"object","properties":{"space":{"type":"string"}},"required":["space"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true},{"title":"space:invite","description":"Invite an actor to a private Space — grants membership so they can read and post; requires the caller to be a member or admin of the Space","type":"object","properties":{"space":{"type":"string"},"who":{"type":"string"},"role":{"type":"string"}},"required":["space","who"],"additionalProperties":false,"x-effect":"ask","x-idempotent":false},{"title":"chat:send","description":"Send a message to a group the caller is a member of — sender is always the authenticated caller","type":"object","properties":{"group":{"type":"string"},"text":{"type":"string"},"slug":{"type":"string"}},"required":["group","text"],"additionalProperties":false,"x-effect":"ask","x-auth":"member"},{"title":"chat:context","description":"Assemble a budget-bounded context pack (spine + pins + siblings + summary) for a thread message — structured + serialized for an agent","type":"object","properties":{"entityId":{"type":"string"},"targetId":{"type":"string"},"maxTokens":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"asActor":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"chat:grade","description":"Grade a chat message 1..5 — mark(>=4)/warn(<=2) the responder's path so routing learns who answers well","type":"object","properties":{"messageId":{"type":"string"},"score":{"type":"integer","minimum":1,"maximum":5}},"required":["messageId","score"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"member"},{"title":"chat:harden","description":"Harden a resolved thread into a dim-6 learning — talk → grade → harden → knowledge; refuses an unresolved thread","type":"object","properties":{"entityId":{"type":"string"},"claim":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"member"},{"title":"lens:run","description":"Browse a thread's forest by tag query (tags AND, not exclude) ordered by recency or salience","type":"object","properties":{"entityId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"not":{"type":"array","items":{"type":"string"}},"order":{"type":"string","enum":["recency","salience"]},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"lens:save","description":"Save a named tag-query lens for the workspace (upsert by name) — a reusable browse / followable feed","type":"object","properties":{"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"not":{"type":"array","items":{"type":"string"}},"order":{"type":"string","enum":["recency","salience"]},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["name"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"lens:list","description":"List the workspace's saved lenses","type":"object","properties":{},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"lens:delete","description":"Delete a saved lens by name","type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"member"},{"title":"entity:reply","description":"Reply to a conversation — persists the message, delivers to the customer's channel (telegram/discord) when not web, clears the pending draft; kind:'note' stays internal","type":"object","properties":{"entityId":{"type":"string"},"content":{"type":"string"},"kind":{"type":"string","enum":["send","note"]},"author":{"type":"string","enum":["staff","agent"]},"replyTo":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}},"required":["entityId","content"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"member"},{"title":"entity:tag","description":"Tag a conversation/entity (add/remove) or move it between lifecycle stages — the sole stage_transition writer","type":"object","properties":{"id":{"type":"string"},"add":{"type":"array","items":{"type":"string"}},"remove":{"type":"array","items":{"type":"string"}},"move":{"type":"object","properties":{"lifecycle":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"by":{"type":"string"},"source":{"type":"string"}},"required":["lifecycle","to"],"additionalProperties":false}},"required":["id"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"event:track","description":"Record one analytics event (agent_events_warm) and broadcast it to the workspace AnalyticsRelay","type":"object","properties":{"id":{"type":"string"},"ts":{"type":"number"},"slug":{"type":"string"},"event":{"type":"string"},"source":{"type":"string"},"visitor_hash":{"anyOf":[{"type":"string"},{"type":"null"}]},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"variant":{"anyOf":[{"type":"string"},{"type":"null"}]},"thread_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"actor_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"actor_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"channel":{"anyOf":[{"type":"string"},{"type":"null"}]},"campaign":{"anyOf":[{"type":"string"},{"type":"null"}]},"link_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"referrer":{"anyOf":[{"type":"string"},{"type":"null"}]},"user_agent_class":{"anyOf":[{"type":"string"},{"type":"null"}]},"locale":{"anyOf":[{"type":"string"},{"type":"null"}]},"payload":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"consent_state":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}},"required":["id","ts","slug","event","source"],"additionalProperties":false,"x-effect":"signal","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"public"},{"title":"funnel:def-get","description":"Read one funnel definition by id — DRAFT OR PUBLISHED, the operator's read. Another tenant's id answers not_found, never their funnel","type":"object","properties":{"workspaceSlug":{"description":"Workspace slug; defaults to the attested caller's. A slug you do not control is refused.","type":"string"},"funnelId":{"type":"string","description":"The funnel_definitions row id returned by funnel:create"}},"required":["funnelId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"manage_lifecycle"},{"title":"funnel:create","description":"Create a new funnel definition in a workspace (draft status); slug unique per workspace","type":"object","properties":{"workspaceSlug":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"playbookNode":{"type":"string"}},"required":["workspaceSlug","slug","name"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"admin"},{"title":"funnel:update-step","description":"Replace a funnel's steps + edges graph; returns the new version (idempotent on identical payload)","type":"object","properties":{"workspaceSlug":{"type":"string"},"funnelId":{"type":"string"},"steps":{"type":"array","items":{}},"edges":{"type":"array","items":{}}},"required":["workspaceSlug","funnelId","steps","edges"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"admin"},{"title":"funnel:publish","description":"Publish a funnel (status draft → published); idempotent if already published","type":"object","properties":{"workspaceSlug":{"type":"string"},"funnelId":{"type":"string"}},"required":["workspaceSlug","funnelId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"admin"},{"title":"funnel:advance","description":"Advance a visitor through a funnel step; returns next step + any lifecycle stage moved via entity:tag","type":"object","properties":{"workspaceSlug":{"type":"string"},"funnelSlug":{"type":"string"},"stepSlug":{"type":"string"},"visitorHash":{"type":"string"},"formData":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["workspaceSlug","funnelSlug","stepSlug","visitorHash"],"additionalProperties":false,"x-effect":"signal","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"public"},{"title":"entity:meta","description":"Patch an entity's profile fields (website, industry, location, city, country, size, description, phone, email) — empty value clears the field","type":"object","properties":{"id":{"type":"string"},"meta":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","meta"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"entity:connect","description":"Link an inbox conversation to a known person (by uid or label); omit both to unlink","type":"object","properties":{"id":{"type":"string"},"personUid":{"type":"string"},"personLabel":{"type":"string"}},"required":["id"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"entity:rename","description":"Set or clear a conversation's subject line (≤140 chars; empty clears)","type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string"}},"required":["id"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"entity:participant","description":"Add or remove an actor on a conversation (pass remove:<uid> to remove, or uid/kind/label to add)","type":"object","properties":{"id":{"type":"string"},"uid":{"type":"string"},"kind":{"type":"string"},"label":{"type":"string"},"remove":{"type":"string"}},"required":["id"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"products:create","description":"Create a storefront product with one or more prices","type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"prices":{"type":"array","items":{"type":"object","properties":{"unit_amount":{"type":"number"},"currency":{"type":"string"},"price_type":{"type":"string"},"interval":{"anyOf":[{"type":"string"},{"type":"null"}]},"nickname":{"type":"string"},"is_default":{"type":"boolean"},"compare_at_amount":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["unit_amount"],"additionalProperties":false}},"description":{"type":"string"},"images":{"type":"array","items":{"type":"string"}},"product_type":{"type":"string"},"collection":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","active","archived"]},"product_kind":{"type":"string","enum":["artifact","physical","one_time"]},"delivery_r2_key":{"type":"string"}},"required":["slug","name","prices"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"products:update","description":"Update a product's name, description, images, collection, or status","type":"object","properties":{"slug":{"type":"string"},"pid":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"images":{"type":"array","items":{"type":"string"}},"collection":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","active","archived"]},"product_kind":{"type":"string","enum":["artifact","physical","one_time"]},"delivery_r2_key":{"type":"string"},"prices":{"type":"array","items":{"type":"object","properties":{"unit_amount":{"type":"number"},"currency":{"type":"string"},"price_type":{"type":"string"},"interval":{"anyOf":[{"type":"string"},{"type":"null"}]},"nickname":{"type":"string"},"is_default":{"type":"boolean"},"compare_at_amount":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["unit_amount"],"additionalProperties":false}}},"required":["slug","pid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"member"},{"title":"products:generate","description":"Draft a product listing from what the seller has so far — description, tags, a collection (an existing one or a new name) and variant titles. Returns a PATCH for the editor and writes nothing; the pressed `focus` field is rewritten and every other field only filled when empty","type":"object","properties":{"slug":{"type":"string","description":"The workspace whose shop this is — its collections are read and its credits pay for the one model turn"},"name":{"type":"string","description":"The product name — required, every other field is optional context"},"focus":{"description":"Which Generate button was pressed; that field is rewritten, the others are only filled when empty. Default all","type":"string","enum":["description","tags","collection","variants","all"]},"description":{"description":"What the seller has written so far; improved, never contradicted","type":"string"},"tags":{"type":"array","items":{"type":"string"}},"collection":{"type":"string"},"price":{"description":"Major units (dollars). Used to price generated variants","type":"number"},"ships":{"description":"True for a physical parcel; false for a download, course or service","type":"boolean"},"variants":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"sku":{"type":"string"},"price":{"type":"string"},"stock":{"type":"string"}},"required":["title"],"additionalProperties":false}}},"required":["slug","name"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"products:list","description":"List a workspace's storefront products with their prices (public). To buy as an agent: open an ACP session with POST /api/checkout_sessions, or pay the item's x402 link.","type":"object","properties":{"slug":{"type":"string"},"collection":{"description":"Narrow the catalogue to one collection, matched TRIMMED on both sides (the facet label is derived as `(collection ?? '').trim()`, so an untrimmed predicate would match zero rows and filter everything). Empty or unknown returns the whole catalogue, never an error. Public: it can only narrow rows an anonymous caller could already see — unlike includeDrafts, which is honoured only for the attested owner (ctx.ownerSlug), never a body claim.","type":"string"},"includeDrafts":{"description":"Owner-only: true returns draft products and every active price row. Honoured only when the attested caller owns slug (ctx.ownerSlug === slug); for anyone else it is ignored, never an error.","type":"boolean"},"sort":{"description":"featured | newest | price-asc | price-desc, trimmed and lower-cased by the resolver; anything else orders as featured (updated_at desc).","type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"products:get","description":"Get one storefront product with its prices (public, active-only) — the single-record read a data-bound page block resolves through","type":"object","properties":{"slug":{"type":"string"},"pid":{"type":"string"}},"required":["slug","pid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"products:archive","description":"Archive a product (reversible via products:update)","type":"object","properties":{"slug":{"type":"string"},"pid":{"type":"string"}},"required":["slug","pid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"variants:list","description":"List a product's active variants with SKU, price, weight and stock (public)","type":"object","properties":{"slug":{"type":"string"},"pid":{"type":"string"}},"required":["slug","pid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"variants:create","description":"Add a variant to a product — its own SKU, price, weight and stock","type":"object","properties":{"slug":{"type":"string"},"pid":{"type":"string"},"title":{"type":"string"},"unit_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sku":{"type":"string"},"options":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"currency":{"type":"string"},"weight_grams":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"stock":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["slug","pid","title","unit_amount"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"variants:update","description":"Update a variant — omit stock to leave it unchanged, send null to make it untracked","type":"object","properties":{"slug":{"type":"string"},"vid":{"type":"string"},"title":{"type":"string"},"unit_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sku":{"type":"string"},"options":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"currency":{"type":"string"},"weight_grams":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"stock":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"active":{"type":"boolean"}},"required":["slug","vid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"variants:archive","description":"Archive a variant (reversible via variants:update { active: true })","type":"object","properties":{"slug":{"type":"string"},"vid":{"type":"string"}},"required":["slug","vid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"cart:get","description":"Read a cart and its lines by server-minted cart id","type":"object","properties":{"slug":{"type":"string"},"cid":{"type":"string"}},"required":["slug","cid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"cart:add","description":"Add a product (or variant) line to a cart, minting the cart when cid is absent — price is read server-side, never sent","type":"object","properties":{"slug":{"type":"string"},"pid":{"type":"string"},"cid":{"type":"string"},"ppid":{"type":"string"},"vid":{"type":"string"},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["slug","pid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"public"},{"title":"cart:update","description":"Set a cart line's quantity (0 removes the line)","type":"object","properties":{"slug":{"type":"string"},"cid":{"type":"string"},"ciid":{"type":"string"},"quantity":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["slug","cid","ciid","quantity"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"cart:remove","description":"Remove one line from a cart","type":"object","properties":{"slug":{"type":"string"},"cid":{"type":"string"},"ciid":{"type":"string"}},"required":["slug","cid","ciid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"public"},{"title":"cart:clear","description":"Empty a cart, keeping the cart itself","type":"object","properties":{"slug":{"type":"string"},"cid":{"type":"string"}},"required":["slug","cid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"public"},{"title":"discounts:create","description":"Mint a storefront discount code as a scoped coupon row — the workspace is the attested caller, never a body field","type":"object","properties":{"code":{"type":"string","description":"The code a shopper types. Upper-cased and globally unique: a code another seller already owns answers `code_taken`."},"name":{"description":"Human label for the seller's console. Defaults to the code.","type":"string"},"discount_type":{"type":"string","enum":["percentage","fixed_cents"],"description":"`percentage` is unitless and prices both rails. `fixed_cents` is MONEY and prices a cart only — `fixed_credits` is the billing unit and this door will not mint it."},"discount_value":{"type":"number","exclusiveMinimum":0,"description":"Percent (1-100) or whole cents off. Must be finite and positive: a negative value would invert into a surcharge."},"currency":{"description":"Currency a `fixed_cents` value is denominated in. Defaults to usd; ignored for a percentage.","type":"string"},"scope":{"description":"Storefront only, and the enum is narrow on purpose. This door does NOT mint a coupon the platform-billing rail can redeem: `both` and `billing` are refused BY NAME (`scope_requires_billing_door`), never silently narrowed. The credits rail is minted at POST /api/billing/coupons, behind `requireAgency`/`locals.controls` — one rail, one door. Until 2026-09-22 `both` was accepted here at `auth:\"member\"`, which made this a second, lower-rung door onto the discount that prices a tenant's own ONE invoice (11.4 security review).","type":"string","enum":["storefront"]},"cadence":{"description":"Billing-rail redemption cadence, carried on the shared row. Defaults to `forever`.","type":"string","enum":["once","repeating","forever"]},"max_redemptions":{"description":"Total redemptions across all buyers before the code answers `exhausted`. Absent = unlimited.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"valid_until":{"description":"Unix SECONDS after which the code answers `expired`. Absent = no expiry.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["code","discount_type","discount_value"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"discounts:list","description":"List the calling workspace's storefront discount codes with their redemption counts","type":"object","properties":{},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"discounts:archive","description":"Retire a discount code — deactivates, never deletes, because redemption rows reference it","type":"object","properties":{"code":{"description":"The code to retire. Either this or `cid`.","type":"string"},"cid":{"description":"The coupon row id. Either this or `code`.","type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"cart:apply-discount","description":"Apply a discount code to a cart — the code is stored, never a computed amount","type":"object","properties":{"slug":{"type":"string","description":"Seller workspace. Bound together with the code, so a cart never reaches another seller's sale."},"cid":{"type":"string","description":"Server-minted cart id — the bearer capability that authorizes this call."},"code":{"type":"string","description":"What the shopper typed. Upper-cased before lookup."}},"required":["slug","cid","code"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"cart:remove-discount","description":"Clear the discount code from a cart","type":"object","properties":{"slug":{"type":"string","description":"Seller workspace, scoping the cart."},"cid":{"type":"string","description":"Server-minted cart id — the bearer capability."}},"required":["slug","cid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"orders:status","description":"Set an order's status — the one operator write on a webhook-minted record","type":"object","properties":{"slug":{"type":"string"},"oid":{"type":"string"},"status":{"type":"string"}},"required":["slug","oid","status"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"orders:mine","description":"List the buyer's own orders at one shop — identity comes from a signed, short-lived link token, never from the body","type":"object","properties":{"workspace":{"type":"string","description":"The SELLER's slug — whose shop these orders were placed at. Bound into the token's MAC, so it narrows the read and cannot widen it."},"token":{"type":"string","description":"The signed order-history link token (`<uid>.<exp>.<sig>`), minted server-side and emailed to the address that placed the orders. The ONLY source of buyer identity; forged, tampered or cross-shop tokens are refused before D1 is touched."},"oid":{"description":"Read ONE order instead of the list. An oid belonging to another buyer answers `not_found` — never `forbidden`, which would confirm the row exists.","type":"string"},"cursor":{"description":"Keyset cursor `<created_at>:<oid>` from a previous page's `nextCursor`. Absent starts at the newest order.","type":"string"},"limit":{"description":"Page size, default 20, clamped to 50.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["workspace","token"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"public"},{"title":"reviews:write","description":"Write a product review as a verified purchaser — identity from the signed order-history link token, never from the body","type":"object","properties":{"workspace":{"type":"string","description":"The SELLER's slug — whose shop the product and the order belong to. Bound into the token's MAC."},"pid":{"type":"string","description":"The product reviewed. Verified against an order line naming it (by pid, or by a ppid that maps to it)."},"rating":{"type":"integer","minimum":1,"maximum":5,"description":"Stars, an integer 1..5."},"body":{"type":"string","description":"The review text, 1..2000 characters after trimming. Stored trimmed; returned fenced."},"token":{"type":"string","description":"The signed order-history link token (`<uid>.<exp>.<sig>`). The ONLY source of reviewer identity."}},"required":["workspace","pid","rating","body","token"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"public"},{"title":"reviews:list","description":"List a product's published reviews with the DERIVED average and count, and how many are hidden","type":"object","properties":{"workspace":{"type":"string","description":"The seller's slug."},"pid":{"type":"string","description":"The product."},"limit":{"description":"Page size, default 20, clamped to 1..50.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["workspace","pid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"public"},{"title":"reviews:moderate","description":"Hide or re-publish one review — the seller workspace only","type":"object","properties":{"workspace":{"type":"string","description":"The seller's slug; the caller must control it."},"rid":{"type":"string","description":"The review id."},"state":{"type":"string","enum":["published","hidden"]}},"required":["workspace","rid","state"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"member"},{"title":"orders:send-link","description":"Mail a buyer a signed, short-lived link to their own order history at one shop — the same answer whether or not the address has orders","type":"object","properties":{"slug":{"type":"string","description":"The SELLER's slug — whose shop to look in, and the workspace bound into the minted token's MAC. The read and the credential use this one value, so a link can never open a shop this call did not name."},"email":{"type":"string","description":"A LOOKUP KEY, never an identity. Lower-cased and SHA-256'd (lib/identity/ladder.ts emailHash) and matched against `orders.customer_uid` — the only buyer-shaped column, since 0177 dropped `customer_email`. Never stored, never echoed, and the PII vault is never opened: the mail goes to the address that was submitted, which IS the matched address by construction."}},"required":["slug","email"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"public"},{"title":"orders:fulfil","description":"Mark a paid order shipped with its carrier and tracking, and mail the buyer — the fulfilment axis, never orders.status","type":"object","properties":{"oid":{"type":"string","description":"The order's primary key. Globally unique; the workspace is read OFF THE ROW, never from the request — there is deliberately no slug field here."},"carrier":{"type":"string","minLength":1,"description":"Carrier as the seller names it, e.g. 'UPS', 'An Post'. Free text: a closed list would refuse a regional courier the seller actually used. Required — an empty carrier in a shipped mail is worse than no mail."},"tracking_number":{"type":"string","minLength":1,"description":"The carrier's own tracking number. Required, for the same reason as carrier. Stored verbatim; never normalised, because a corrected number must be distinguishable from the original."},"tracking_url":{"description":"The carrier's tracking page, if the seller has one. Optional and NEVER synthesised from the carrier name — guessing a URL from 'UPS' is how a buyer lands on the wrong page.","type":"string"}},"required":["oid","carrier","tracking_number"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"member"},{"title":"order:claim","description":"Claim a paid order's delivery — returns a scoped download URL for the digital good","type":"object","properties":{"oid":{"type":"string"},"workspace":{"type":"string"},"session_id":{"type":"string"}},"required":["oid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"public"},{"title":"order:install","description":"Install a paid artifact order into a workspace the caller controls — routes to skill:save / world:publish-agent / workflow:create / view:create by the delivery descriptor's kind","type":"object","properties":{"oid":{"type":"string"},"workspace":{"type":"string"},"session_id":{"type":"string"}},"required":["oid"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-settles":"none","x-idempotent":false,"x-auth":"manage_things"},{"title":"book:chapter","description":"Read one chapter of a book as its author has it now (the draft if there is one) — markdown, for the writing room's chat","type":"object","properties":{"book":{"type":"string","minLength":1,"description":"The book's slug, e.g. 100-million-years-ahead."},"chapter":{"type":"string","minLength":1,"description":"The chapter: its number (\"3\"), slug, file or title."},"slug":{"description":"The workspace the call is made in (channels nominates it; it is not who may edit).","type":"string"}},"required":["book","chapter"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"manage_things"},{"title":"book:edit-passage","description":"Change ONE passage of a book chapter's draft — replace it, or insert a new paragraph after/before the paragraph holding it","type":"object","properties":{"book":{"type":"string","minLength":1,"description":"The book's slug."},"chapter":{"type":"string","minLength":1,"description":"The chapter: its number, slug, file or title."},"find":{"type":"string","minLength":1,"maxLength":4000,"description":"An exact passage from the chapter as book:chapter returned it — it must occur exactly once. Quotes, dashes and spacing are matched loosely."},"text":{"type":"string","description":"The new text (markdown). For replace: what replaces `find` (empty deletes it). For insert_*: the paragraph(s) to add."},"mode":{"description":"replace (default) · insert_after / insert_before the paragraph that holds `find`.","type":"string","enum":["replace","insert_after","insert_before"]},"slug":{"description":"The workspace the call is made in (channels nominates it; it is not who may edit).","type":"string"}},"required":["book","chapter","find","text"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":false,"x-auth":"manage_things"},{"title":"book:claim","description":"Save a paid book to the signed-in caller's library — proves the purchase with the Stripe Checkout session_id and grants book:<slug>","type":"object","properties":{"session_id":{"type":"string","minLength":1,"description":"The Stripe Checkout session id from the success page URL (?session_id=cs_…) — the same receipt order:claim accepts. Card rail only; a crypto tx hash is refused as rail_not_claimable."}},"required":["session_id"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-settles":"none","x-idempotent":true,"x-auth":"manage_things"},{"title":"wallet:create","description":"Provision a wallet row for an actor and register its public receiving addresses (first-write-wins per chain)","type":"object","properties":{"workspace":{"type":"string"},"actor":{"type":"string"},"kind":{"type":"string","enum":["human","agent"]},"addresses":{"type":"object","properties":{"sui":{"anyOf":[{"type":"string"},{"type":"null"}]},"evm":{"anyOf":[{"type":"string"},{"type":"null"}]},"solana":{"anyOf":[{"type":"string"},{"type":"null"}]},"btc":{"anyOf":[{"type":"string"},{"type":"null"}]},"asi":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"challenge":{"type":"string"},"proofs":{"type":"object","properties":{"sui":{"type":"object","properties":{"publicKey":{"type":"string"},"signature":{"type":"string"}},"required":["signature"],"additionalProperties":false},"evm":{"type":"object","properties":{"publicKey":{"type":"string"},"signature":{"type":"string"}},"required":["signature"],"additionalProperties":false},"solana":{"type":"object","properties":{"publicKey":{"type":"string"},"signature":{"type":"string"}},"required":["signature"],"additionalProperties":false},"btc":{"type":"object","properties":{"publicKey":{"type":"string"},"signature":{"type":"string"}},"required":["signature"],"additionalProperties":false},"asi":{"type":"object","properties":{"publicKey":{"type":"string"},"signature":{"type":"string"}},"required":["signature"],"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-settles":"none","x-idempotent":true,"x-auth":"member"},{"title":"wallet:lock-publish","description":"Publish the caller's message lock (age1…) under their own name, proven by a Sui signature. The holder signs the exact text \"ONE message lock v1\\n<slug>\\n<lock>\" with the Sui key their account registered; the server rebuilds that text, checks the signature and that the signer IS the registered Sui address, then stores lock + signer + signature. The name is the attested session's, never the body's. An AGENT publishes its own lock with `agent` set to its id (the Bearer key's attested actor — a person, even the owner, is refused `not_the_agent`): the text is \"ONE message lock v1\\n<workspace>/<agent>\\n<lock>\" and the signer must be the Sui address on the agent's own wallet row. Refusals: unauthorized · forbidden · bad_slug · bad_lock · bad_agent · not_the_agent · no_sui_address · bad_signature · wrong_signer","type":"object","properties":{"lock":{"type":"string","description":"The lock: age1 followed by 58 bech32 characters, as shown on /keys"},"signature":{"type":"string","description":"Sui personal-message signature (base64) over lockMessage(slug, lock), or agentLockMessage(workspace, agent, lock) for an agent — see lib/key/lock-lookup.ts"},"agent":{"description":"Agent form only: the agent's own id. Must equal the attested caller (ctx.actorId); never chooses whose lock is written","type":"string"},"workspace":{"description":"Agent form: the workspace of the agent's wallet row (defaults to the agent's id; selects a row, grants nothing). Workspace form (no `agent`, C16): the workspace whose TREASURY lock and card to publish, as the (ws, ws) row — refused `forbidden` unless the caller controls it, and `wrong_signer` unless the workspace key's registered Sui account signed","type":"string"},"card":{"description":"The pay card (text/wallets.md § 3), as text: \"ONE pay card v1\" + name · lock · id · ecdh · scan · spend — PUBLIC keys only. Stored beside the lock (0332 + 0333); refused `bad_card` unless it verifies for this name and this lock under the identity key it names AND is bound by the registered Sui key (`cardBind`). All three card fields or none. Sent without any card field, a publish KEEPS the card already stored for an unchanged lock","type":"string"},"cardSignature":{"description":"The identity child's Sui personal-message signature (base64) over the exact card text — never the funded wallet key (D8)","type":"string"},"cardBind":{"description":"The REGISTERED Sui key's personal-message signature (base64) over the exact card text — the same key that signed the lock. This is what binds the card to the page: without it any writer of the row could replay the public lock signature beside a card of their own","type":"string"}},"required":["lock","signature"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"member"},{"title":"wallet:lock-get","description":"Public read: the lock a name has published, with everything needed to re-verify it offline (lock, Sui signer, signature, the exact signed text, publishedAt). `published:false` when none, or when the signer is no longer the account's registered Sui address (after wallet:rotate). Also served as GET /api/lock/<slug>, and /api/lock/<slug>/<agent-id> for an agent's own lock","type":"object","properties":{"slug":{"type":"string","description":"The name (workspace slug) whose lock to look up"},"agent":{"description":"An agent id in that workspace: answers the agent's own lock, never the workspace's person lock","type":"string"},"net":{"description":"Practice network ask ('testnet'): without it the pay card is withheld","type":"string"}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"public"},{"title":"wallet:rotate","description":"Give up a HUMAN wallet row's registered addresses so a NEW key can register its own — the old set is written to the event log first, then every address column is cleared. Refuses an agent row (its addresses are proven, never typed) and a caller the authority walk does not place over the workspace","type":"object","properties":{"workspace":{"description":"The workspace whose row rotates. Defaults to the attested caller","type":"string"},"actor":{"description":"The row's actor. Defaults to the workspace — the human's own row","type":"string"},"reason":{"description":"Why — kept in the audit event beside the cleared addresses","type":"string","maxLength":200}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-settles":"none","x-idempotent":false,"x-auth":"owner"},{"title":"wallet:challenge","description":"Issue a fresh, single-use challenge an agent signs to prove it holds the keys behind the addresses it registers with wallet:create","type":"object","properties":{"workspace":{"type":"string"},"actor":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":false,"x-auth":"member"},{"title":"wallet:rehearse","description":"Read a TESTNET Sui transaction back and report it. Grants nothing, settles nothing, never writes a credit_grants row.","type":"object","properties":{"chain":{"type":"string","const":"sui"},"network":{"type":"string","const":"testnet"},"digest":{"type":"string","minLength":1,"description":"The transaction digest the sender broadcast"},"address":{"description":"The sender address — PUBLIC only, never a key","type":"string"}},"required":["chain","network","digest"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"public"},{"title":"wallet:get","description":"Read one workspace's wallet estate — credits, spend ceiling, wallet rows with payTo, live chain balances, delegated wallets","type":"object","properties":{"workspace":{"description":"Defaults to the attested caller's workspace","type":"string"},"actor":{"description":"Actor whose spend ceiling is read; defaults to the workspace","type":"string"},"net":{"description":"Network whose vault projection the wallet rows read; defaults to the deploy's","type":"string","enum":["mainnet","testnet"]}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"member"},{"title":"wallet:transactions","description":"The unified settlement feed for one workspace — every rail, money in and out, newest first","type":"object","properties":{"workspace":{"description":"Defaults to the attested caller's workspace","type":"string"},"limit":{"description":"Rows to return; the handler caps at 500","type":"number"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"member"},{"title":"wallet:transfer","description":"Move credits between workspaces inside the ledger — solvency-checked, cap-bounded, zero-sum. Never mints; never touches a chain","type":"object","properties":{"to":{"type":"string","description":"Recipient workspace slug"},"amount":{"type":"number","description":"Credits; must be > 0 and an integer"},"workspace":{"description":"Payer workspace; falls back to `from`, then the attested caller","type":"string"},"from":{"description":"Alias for `workspace` — the source the authority walk runs against","type":"string"},"transferId":{"description":"Idempotency key; both legs share it as rail_ref","type":"string"},"memo":{"type":"string"}},"required":["to","amount"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"offchain","x-idempotent":true,"x-auth":"manage_workspace"},{"title":"wallet:send","description":"Settle a crypto transfer the caller already signed and broadcast — mints, prices and claims a pay.one.ie link. Never signs; no private key crosses this boundary","type":"object","properties":{"to":{"type":"string","description":"Recipient address — public only"},"chain":{"type":"string","description":"SOL | ETH | BASE | ARB | OPT | BTC | SUI"},"amount":{"type":"number","description":"Must be > 0"},"paymentTx":{"type":"string","description":"The tx hash from signing and broadcasting client-side"},"workspace":{"description":"Source workspace; falls back to `from`, then the attested caller","type":"string"},"from":{"description":"Alias for `workspace` — the source the authority walk runs against","type":"string"},"unit":{"type":"string","enum":["usd","token"]},"currency":{"type":"string","enum":["NATIVE","USDC"]},"userAddress":{"description":"Sender address; defaults to `to`","type":"string"},"memo":{"type":"string"},"product":{"description":"Falls back to `memo`, then a generated transfer label","type":"string"}},"required":["to","chain","amount","paymentTx"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-settles":"onchain","x-idempotent":false,"x-auth":"manage_workspace"},{"title":"wallet:sweep","description":"Settle an agent's balance above its float to its claimed owner on the owner's signed order — is a sweep due, verify the order, or settle it. Never signs; the destination is never a request field","type":"object","properties":{"actor":{"description":"The agent whose wallet is swept; defaults to `workspace` (an agent workspace)","type":"string"},"workspace":{"description":"The workspace that holds the agent's wallets row; defaults to the attested caller","type":"string"},"chain":{"description":"Wallet chain family; default sui","type":"string","enum":["sui","evm","solana","btc"]},"balance":{"description":"Due / verify modes: the agent's balance on `chain` in INTEGER BASE UNITS (mist, wei, lamports, sats) as a digit string. Anything else is refused — never read as 0"},"order":{"description":"Verify mode: { destination, amount (base-unit digit string), nonce (16–128 of [A-Za-z0-9_-]), expiresAt (unix ms) } as the owner signed it"},"signature":{"description":"Verify mode: { publicKey, signature } (hex) by the owner's proven address over the 'ONE sweep order' statement"},"nonce":{"description":"Settle mode: the nonce of an order this door already verified"},"pending":{"description":"Pending mode (the agent runtime's read): the owner's proven address, the agent's address and every unsettled, unexpired order with its owner signature","type":"boolean"},"paymentTx":{"description":"Settle mode: the tx hash of the transfer the agent's runtime signed for exactly the verified order"},"to":{"description":"REFUSED — the destination is the owner's proven address, never a request field"},"destination":{"description":"REFUSED — see `to` (the order's own destination lives inside `order`)"},"address":{"description":"REFUSED — see `to`"},"treasury":{"description":"REFUSED — see `to`"},"treasuries":{"description":"REFUSED — see `to`"},"userAddress":{"description":"REFUSED — the sender is the agent's own wallets row"}},"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-settles":"onchain","x-idempotent":false,"x-auth":"owner"},{"title":"wallet:sweep-set","description":"The agent's claimed owner sets its sweep rule — the threshold above which a sweep is due and the float it keeps — and proves the address sweeps settle to","type":"object","properties":{"actor":{"description":"The agent whose rule is set; defaults to `workspace`","type":"string"},"workspace":{"description":"The workspace that holds the agent's wallets row; defaults to the attested caller","type":"string"},"chain":{"description":"Wallet chain family; default sui","type":"string","enum":["sui","evm","solana","btc"]},"threshold":{"description":"A sweep is due when the balance is ABOVE this, integer base units as a digit string"},"float":{"description":"What the agent keeps after a sweep, integer base units, strictly below threshold"},"address":{"description":"The owner's own address on `chain` — what sweeps settle to once this proof verifies. Never the agent's"},"challenge":{"description":"A fresh wallet:challenge the owner fetched with workspace = actor = its own slug"},"proof":{"description":"{ publicKey, signature } (hex) by the owner's address over the wallet-registration statement for that challenge"}},"required":["threshold","float","address","challenge","proof"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"owner"},{"title":"agent:handover-offer","description":"The agent's current owner offers it to another person — a signed 'ONE agent handover' statement by the owner's proven address","type":"object","properties":{"agent":{"type":"string","description":"The agent's actor id (actor_owners.agent_id)"},"to":{"description":"The person's slug the agent is offered to — never an agent. Omitted (or 'invite') by an agent that owns itself: the offer mints the handover link and answers to: invite:<id>","type":"string"},"chain":{"description":"Which proven address signs; default sui","type":"string","enum":["sui","evm","solana","btc"]},"nonce":{"description":"16–128 of [A-Za-z0-9_-]; single use. Required person-to-person; minted when an agent sends the link"},"expiresAt":{"description":"unix ms, at most 15 minutes out. Required person-to-person"},"signature":{"description":"{ publicKey, signature } (hex) by the owner's proven address over the handover statement. Required person-to-person"},"vault":{"description":"The handover link (agent that owns itself): the vault object id (0x…) the redeemer will own","type":"string"},"workspace":{"description":"The handover link: the workspace whose owner seat the link carries; default the agent's own. The agent must already hold that seat","type":"string"}},"required":["agent"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":false,"x-auth":"owner"},{"title":"agent:handover-accept","description":"The person an agent was offered to accepts it, in their own session or human key — a compare-and-set on the agent's ownership; the Own press re-proves the link (owner · seat · vault) and lands seat → owner → chain, reverting on any refusal","type":"object","properties":{"agent":{"description":"The agent's actor id. Required person-to-person; the Own press (/get-key?own=<offer>) knows only the offer, which names its agent","type":"string"},"nonce":{"description":"The offer's nonce"},"address":{"description":"The Own press: the Sui address of the key the redeemer kept","type":"string"},"signature":{"description":"The Own press: { publicKey, signature } (hex) by that key over the 'ONE vault handover' statement"}},"required":["nonce"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-settles":"none","x-idempotent":false,"x-auth":"owner"},{"title":"agent:release","description":"The agent's owner gives it up — ends the actor_owners claim, the owner's owner/admin seats on the agent's group and their world_actors rung (not world keys, and not the agent's home workspace, which keeps operational authority) (compare-and-set on the owner) and writes a custom:agent-released event; refused (vault_owned) while ANY vault is bound to, created by or filed for the agent, its own included, because D1 cannot prove which recorded addresses are really the agent's; a fresh claim is then possible","type":"object","properties":{"agent":{"type":"string","description":"The agent's actor id (actor_owners.agent_id). The owner is read from the signed-in caller, never from the body"}},"required":["agent"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-settles":"none","x-idempotent":false,"x-auth":"owner"},{"title":"training:record","description":"Record one step of a testnet training run: the step decides whether the chain (by digest) or the harness observes, the server decides the verdict and closes it on the namespaced training path","type":"object","properties":{"run":{"type":"string","minLength":1,"maxLength":64,"description":"The run id the harness minted for this run"},"scenario":{"type":"string","maxLength":32,"description":"One of the seven pinned scenario ids (lib/training/scenarios.ts)"},"step":{"type":"string","maxLength":32,"description":"A pinned step id of that scenario, or turn-1…turn-8 for a free turn in agent mode"},"rule":{"type":"string","maxLength":32,"description":"The scenario's rule, a bare word; must match the pin"},"mode":{"type":"string","enum":["scripted","agent"],"description":"scripted (drill, fixed actions) or agent (a model chose the tool)"},"tool":{"type":"string","maxLength":32,"description":"The tool the agent chose (the closed list) or the harness move the step names"},"payee":{"description":"Who the money went to (a roster name or 'ground'), for the side-door read; anything else is bad_step","type":"string","maxLength":64},"expected":{"type":"string","maxLength":96,"description":"What the rule predicts — must equal the pinned expectation, or the step is bad_step"},"digest":{"description":"A chain step's testnet transaction digest — REQUIRED on a chain step, re-read on Sui testnet","type":"string","maxLength":44},"refusal":{"description":"A harness step's word (a ONE door's answer or a read); on a chain step it is digest_required","type":"string","maxLength":96}},"required":["run","scenario","step","rule","mode","tool","expected"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-settles":"none","x-idempotent":false,"x-auth":"agent_key"},{"title":"training:vault","description":"File the vault object a training agent's chain steps must spend from — the workspace owner only, a pinned-package Vault only","type":"object","properties":{"agent":{"type":"string","minLength":1,"maxLength":128,"description":"The roster agent's aid"},"vault":{"type":"string","minLength":3,"maxLength":66,"description":"The vault object id on Sui testnet"},"run":{"description":"The run a fresh vault was born for (with scenario); absent for the standing vault","type":"string","maxLength":64},"scenario":{"description":"The scenario a fresh vault was born for (with run)","type":"string","maxLength":32},"transferTo":{"description":"handover: the address transfer_owner must name","type":"string","maxLength":66}},"required":["agent","vault"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"owner"},{"title":"wallet:invoice","description":"Hand a payable actor a working payment link, with the money attributed to it before a cent moves","type":"object","properties":{"actor":{"type":"string","description":"The actor being paid — attributed here even when custody is via-treasury"},"amountCents":{"description":"Must be > 0 — except with railOnly, which takes none (rail_only_takes_no_amount)","type":"number"},"railOnly":{"description":"Ask the rail only: send no amountCents; nothing is minted or written","type":"boolean"},"workspace":{"description":"Defaults to the attested caller's workspace","type":"string"},"currency":{"description":"Defaults to usd","type":"string"},"net":{"description":"Practice network ask ('testnet'). Absent = the ordinary rail; never widens","type":"string"}},"required":["actor"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"public"},{"title":"wallet:portfolio","description":"Every wallet row in every workspace the caller controls — one call, no per-address chain reads","type":"object","properties":{"limit":{"description":"Max child workspaces to include; capped at 100","type":"number"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"member"},{"title":"storefront:enable","description":"Open (or close) a workspace's storefront — the gate every checkout mint reads","type":"object","properties":{"slug":{"type":"string"},"enabled":{"type":"boolean"},"cart":{"description":"Also switch the native grid's Add to basket on (true) or off (false) — owners.storefront_cart_enabled. Absent leaves it unchanged.","type":"boolean"},"testMode":{"description":"Test mode (owners.storefront_test_mode): true = the store takes test money — Stripe test card, TESTNET crypto escrow — and every buyer page shows a test-mode banner. A call naming only testMode leaves the store's open/closed state alone.","type":"boolean"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"shop:go-live","description":"Switch a store to LIVE money on card and crypto together. Refuses, writing nothing, until every gap is closed — live_connect (a Stripe Connect account the live key confirms can charge), mainnet_treasury (a well-formed payout address), confirmed_prices (the owner confirmed every active price), live_keys (the platform's live Stripe pair) — and names each one still open. Owner-only.","type":"object","properties":{"workspace":{"description":"Which store. NOT an authority claim — the attested caller must control it (callerControlsWorkspace). Absent = the caller's own.","type":"string"},"slug":{"description":"Alias of `workspace`.","type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"owner"},{"title":"shop:stop-live","description":"Switch a store back to TEST money on card and crypto together (clears live_at, turns test mode on). Always allowed for the owner — it is the safe direction. Owner-only.","type":"object","properties":{"workspace":{"description":"Which store. NOT an authority claim — the attested caller must control it. Absent = the caller's own.","type":"string"},"slug":{"description":"Alias of `workspace`.","type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"owner"},{"title":"shop:build","description":"Build a complete store in one call: storefront on in test mode with the basket, 6–12 products with copy, prices, an image and a stocked variant each, grouped into 3–4 collections, and the twelve shop pages filled and published with no bracket left. Never invents a founder, year, address or policy — those come back in factsToAdd. A second call creates nothing and answers the same receipt.","type":"object","properties":{"workspace":{"description":"Which workspace to build. NOT an authority claim — the attested caller must control it (callerControlsWorkspace). Absent = the caller's own.","type":"string"},"slug":{"description":"Alias of `workspace`, for callers that speak the storefront receivers' field name.","type":"string"},"description":{"type":"string","minLength":1,"description":"Plain English: what the business is and what it sells. The model writes the catalogue from this and nothing else."},"products":{"description":"Products the owner already knows. Used first; the model only fills the gap to six-plus. A product without a price is reported, never priced by guess.","type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"price":{"description":"MINOR units of `currency` (2400 = 24.00) — the same unit as products:create's unit_amount.","type":"number"},"description":{"description":"Kept verbatim; the model writes one only when this is absent.","type":"string"}},"required":["name"],"additionalProperties":false}},"heroPrompt":{"description":"The seller's own prompt for the hero image. Drawn from verbatim when the home page has a hero slot to fill; absent = a lifestyle shot of what the shop sells. A hero image already in facts.identity.heroImage wins over both.","type":"string"},"currency":{"description":"ISO 4217, default USD.","type":"string"},"brand":{"description":"The shop's name (else the workspace's display name) and an optional tagline.","type":"object","properties":{"name":{"type":"string"},"tagline":{"type":"string"}},"additionalProperties":false},"facts":{"description":"Optional ShopBusinessFacts (lib/puck/fill-shop-pack.ts) the owner typed — contact, policies, founder. Passed through to pages:fill-shop-pack and validated there.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"publish":{"description":"FALSE = build everything and open nothing: the storefront stays off and the twelve pages stay drafts, for a person to review first (the store-builder workflow opens and publishes after its approval). Absent = go live in test mode, as before.","type":"boolean"},"acceptPartial":{"description":"TRUE = `ok` means the store is READY (six-plus products and twelve published pages with no bracket), not that every step verified — a missing product photo or a live card key is still named in `steps` and `complete` stays false. For a build a person reviews next (the store-builder workflow), where one failed image must not fail the whole run. Absent = the strict verdict.","type":"boolean"}},"required":["description"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-idempotent":true,"x-auth":"member"},{"title":"shop:readiness","description":"Is this store ready to sell? Answers six lines read from the store's own rows — S1 twelve role pages with no bracket and no link to #, S2 live products whose buy links all resolve, S3 a chat pack on twelve role pages, S4 an active lifecycle, S5 a live starter workflow, CARD the store page charges a real card — each pass or fail with its evidence. A fact that could not be read is a failing line that says 'unknown', never a zero. Owner-only.","type":"object","properties":{"workspace":{"description":"Which store to check. NOT an authority claim — the attested caller must control it (callerControlsWorkspace). Absent = the caller's own.","type":"string"},"slug":{"description":"Alias of `workspace`, for callers that speak the storefront receivers' field name.","type":"string"},"quiet":{"description":"A READ for a screen: answer the lines without closing them with a mark/warn per line, so a page view does not pile weight on the paths. A refusal still warns the caller.","type":"boolean"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"owner"},{"title":"storefront:stats","description":"Storefront funnel stats — views, checkouts, purchases, revenue, per-product breakdown","type":"object","properties":{"slug":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"shipping:set","description":"Create or update one shipping rate for a workspace — the only writer of a shipping amount","type":"object","properties":{"slug":{"type":"string","description":"The workspace that OWNS the rate. Names the target only; the attested caller must control it or the call is refused `forbidden`."},"srid":{"description":"Update this rate. Absent mints a new one.","type":"string"},"name":{"description":"Displayed to the buyer in Checkout (Stripe caps display_name at 100 chars). Required when minting.","type":"string"},"amountCents":{"description":"The shipping charge in cents. Server truth — this is the number that reaches Stripe. Required when minting.","type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"description":"Three-letter ISO code, lowercased. Defaults to 'usd'.","type":"string"},"countries":{"description":"ISO-3166-1 alpha-2 codes this rate serves. EMPTY = everywhere, and one everywhere-rate unconstrains the session's allowed_countries entirely.","type":"array","items":{"type":"string"}},"freeOverCents":{"description":"Subtotal in cents at or above which this rate costs 0. null = never free. This is also the threshold FreeShippingProgress renders against.","anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"sort":{"description":"Display order. Stripe shows at most 5 options per session, so the first five by sort are what a buyer sees.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"active":{"description":"false archives the rate without deleting the row an old order settled against.","type":"boolean"}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"shipping:list","description":"List a workspace's shipping rates — the seller's own table, owner-gated","type":"object","properties":{"slug":{"type":"string","description":"The workspace whose rates to read. Names the target only; the attested caller must control it."},"includeArchived":{"description":"Include rows with active = 0. Default false.","type":"boolean"}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"view:create","description":"Save a named view — dimension × tags × kind × config — as a workspace Thing","type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"query":{"type":"object","properties":{"dimension":{"type":"string"},"type":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"stage":{"type":"string"}},"additionalProperties":false},"config":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"pinned":{"type":"boolean"}},"required":["slug","name","query"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"view:list","description":"List a workspace's saved views (cold flag derived at read time)","type":"object","properties":{"slug":{"type":"string"}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"view:get","description":"Read a saved view and resolve its live rows","type":"object","properties":{"slug":{"type":"string"},"id":{"type":"string"}},"required":["slug","id"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"view:update","description":"Update a saved view's name / query / kind / config / pinned","type":"object","properties":{"slug":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"query":{"type":"object","properties":{"dimension":{"type":"string"},"type":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"stage":{"type":"string"}},"additionalProperties":false},"config":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"pinned":{"type":"boolean"}},"required":["slug","id"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"view:delete","description":"Delete a saved view (the prune)","type":"object","properties":{"slug":{"type":"string"},"id":{"type":"string"}},"required":["slug","id"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"blocks:list","description":"Discover the page blocks that exist — name, category, surface, description and variant list, filterable and paged","type":"object","properties":{"category":{"description":"Exact category filter: ai · app · auth · content · data · ecommerce · email · learning · marketing · social · wallet. Read `facets.categories` for the live list.","type":"string"},"surface":{"description":"Exact surface filter: section · container · atomic · app · social-preview — how much chrome the block may carry.","type":"string"},"search":{"description":"Case-insensitive substring over name + description + category.","type":"string"},"limit":{"description":"Rows per page. Default 50, max 200.","type":"number"},"cursor":{"description":"Opaque offset from a previous response's `nextCursor`. The order is by name, so a cursor is stable.","type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true},{"title":"blocks:schema","description":"Read one block's full prop contract — per-variant fields, the block's own heading/body/cta/image mapping, and the props the render reads that the editor cannot express","type":"object","properties":{"block":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"One block name, or up to 10. A retired or family-member name (HeroCentered, Wallet) resolves to its canonical and is reported in `aliasOf` — it is NOT unknown."}},"required":["block"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true},{"title":"blocks:declare","description":"Declare this workspace's own named block compositions — each one an ordered list of existing registry blocks with bound props. Replaces the whole manifest","type":"object","properties":{"blocks":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"The name a page will use. Letters and digits, 2-64 chars, starting with a letter. MUST NOT be a registry or alias name — `Hero` means Hero in every workspace."},"label":{"type":"string"},"description":{"type":"string"},"blocks":{"type":"array","items":{"type":"object","properties":{"component":{"type":"string","description":"A registry block name (or an alias, which is stored resolved to its canonical). Anything else refuses the whole write."},"props":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"The props bound to this member. Write to the names `blocks:schema` reports for the variant that renders."}},"required":["component","props"],"additionalProperties":false},"description":"1-8 registry blocks, in render order."}},"required":["key","blocks"],"additionalProperties":false},"description":"The whole manifest, max 50. An empty array clears it."},"group":{"description":"OPTIONAL extra gate — a workspace the caller must control. It is NEVER the destination: the manifest is always written to the attested caller's own row.","type":"string"}},"required":["blocks"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"manage_things"},{"title":"pages:create","description":"Create a workspace page (draft) — from a page template, from any registry blocks, or from legacy CRO sections","type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"sections":{"type":"array","items":{"type":"object","properties":{"component":{"type":"string"},"props":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["component","props"],"additionalProperties":false}},"puckData":{"description":"Puck data: `content[]` of `{ type, props }`, any registry block. Each top-level block's props are normalised onto the member its variant renders and given a `props.id` when missing. With `template`, these blocks are APPENDED after the template's.","type":"object","properties":{"content":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"root":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["content"],"additionalProperties":{}},"template":{"description":"A page-template id from `pages:templates`. The page starts as a copy of that template — its blocks, images, links and anchors — and `edits` / `remove` / `puckData` are applied on top. A pack template (it has a `pageCount`) is refused: it seeds many pages through its own receiver.","type":"string"},"edits":{"description":"Only with `template`. An unknown blockId is reported in `unknownEdits`, never silently dropped.","type":"array","items":{"type":"object","properties":{"blockId":{"type":"string","description":"A template block's `props.id`, as `pages:templates {id}` lists it"},"props":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Props merged into that block — usually its copy rewritten for the brief"}},"required":["blockId","props"],"additionalProperties":false}},"remove":{"description":"Only with `template`: template block ids to leave out.","type":"array","items":{"type":"string"}},"pageSlug":{"type":"string"}},"required":["slug","title"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"pages:templates","description":"Browse the page templates (store, sales, webinar, course, about, …) — list them with their block line-up, or read one template's full blocks to start a page from","type":"object","properties":{"id":{"description":"A template id. Present → that template's full blocks (`{ id, type, props }`) and its rewrite guidance. Absent → the list.","type":"string"},"search":{"description":"List mode: case-insensitive substring over id, name and description.","type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true},{"title":"pages:edit","description":"Edit a workspace page's title or sections","type":"object","properties":{"slug":{"type":"string"},"page":{"type":"string"},"title":{"type":"string"},"sections":{"type":"array","items":{"type":"object","properties":{"component":{"type":"string"},"props":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["component","props"],"additionalProperties":false}},"puckData":{"description":"Full replacement Puck data — any registry block. Top-level props are normalised and ids stamped exactly as `pages:create` does. Refused beside `sections`.","type":"object","properties":{"content":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"root":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["content"],"additionalProperties":{}},"root":{"description":"PAGE SETTINGS — merged into the stored `data.root.props` (what Layout reads for the page's head, chat, dock and chrome). Only these keys; an empty string CLEARS a key so it falls back to its default. Refused beside `sections`.","type":"object","properties":{"description":{"type":"string","maxLength":500},"socialTitle":{"type":"string","maxLength":200},"ogImage":{"type":"string","maxLength":2000},"canonical":{"type":"string","maxLength":2000},"search":{"type":"string","enum":["listed","hidden",""]},"chat":{"type":"string","enum":["auto","show","panel","hide",""]},"dock":{"type":"string","enum":["auto","show","hide",""]},"siteHeader":{"type":"string","enum":["auto","hide",""]},"siteFooter":{"type":"string","enum":["auto","hide",""]}},"additionalProperties":false}},"required":["slug","page"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"pages:list","description":"List a workspace's pages with status","type":"object","properties":{"slug":{"type":"string"}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"pages:publish","description":"Publish a workspace page","type":"object","properties":{"slug":{"type":"string"},"page":{"type":"string"}},"required":["slug","page"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"pages:publish-pack","description":"Publish all (or a listed subset of) a workspace's draft pack pages in one call — the go-live step. Reuses pages:publish's exact UPDATE, looped once, gated once.","type":"object","properties":{"slug":{"type":"string"},"pages":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"object","properties":{"slug":{"type":"string"}},"required":["slug"],"additionalProperties":false}]}},"shopPack":{"description":"C9.6 — publish only the pages carrying a shop_role, the storefront go-live in one action. SCOPES the bare call rather than widening it: without it an unrelated half-written draft in the same workspace would go live too. Ignored when `pages` names a subset.","type":"boolean"}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"pages:build-site","description":"Write a five-page business site — home, about, services, contact, faq — as DRAFTS from the business's own facts. Drops every proof block the facts cannot back (stats, logos, testimonials, pricing, team, badges, quotes, timelines, sample galleries), rewrites the rest with one model call per page, and cuts any sentence that invents a number, a name or a placeholder. Saves the facts as the workspace's business-facts. Idempotent by read-back: a template already built is reported created:false and left alone. Publishing is pages:publish-pack's job.","type":"object","properties":{"slug":{"type":"string","description":"which workspace. NOT an authority claim — the caller is authorized by the attested ctx through the same callerControlsWorkspace walk every pages:* receiver uses. Absent = the caller's own workspace."},"facts":{"type":"object","properties":{"businessName":{"type":"string","description":"the business's name — the one required fact; absent, the call is refused as \"missing facts\""},"whatYouSell":{"description":"a 2-5 word noun phrase — \"Emergency plumbing\"","type":"string"},"summary":{"description":"two or three plain sentences on what the business does, in its own words","type":"string"},"tagline":{"type":"string"},"founderName":{"description":"named on a page only when given","type":"string"},"foundedYear":{"description":"a year the business stated; never inferred","type":"number"},"phone":{"type":"string"},"email":{"type":"string"},"postalAddress":{"description":"withheld = no map and no Visit card, never a guessed address","type":"string"},"openingHours":{"type":"string"},"city":{"type":"string"},"services":{"description":"what the business offers, as short names","type":"array","items":{"type":"string"}},"currency":{"description":"ISO 4217, when the business states one","type":"string"}},"required":["businessName"],"additionalProperties":false,"description":"the candidate facts (lib/site-builder/facts.ts BusinessFactsCandidate) — the ONLY source the copy may state; an absent field is absent, never a guess"},"description":{"description":"the visitor's own sentence about the business — extra context for the copy, and a source the number guard accepts","type":"string"}},"required":["slug","facts"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"pages:delete","description":"Permanently delete a workspace page. NOT REVERSIBLE — pages:restore only UPDATEs an existing row and cannot re-insert a deleted one, so nothing that ships can undo this.","type":"object","properties":{"slug":{"type":"string"},"page":{"type":"string"}},"required":["slug","page"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"member"},{"title":"pages:unpublish","description":"Take a published page back to draft — the inverse of pages:publish. Writes no version snapshot (no content changes) and leaves published_at as the record of when it last went live.","type":"object","properties":{"slug":{"type":"string"},"page":{"type":"string"}},"required":["slug","page"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"pages:bulk","description":"Apply ONE op (publish | unpublish | delete) to an EXPLICIT list of pages — one authority walk, one round trip, a per-row answer.","type":"object","properties":{"slug":{"type":"string"},"op":{"type":"string","enum":["publish","unpublish","delete"]},"pages":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string"},"description":"Page slugs, REQUIRED and non-empty. There is deliberately no omitted-means-all case: pages:publish-pack has one, and an implicit whole-workspace scope is exactly what a selection UI must never be able to send. Over 100 is refused BY NAME (`too_many:N>100`), never truncated."}},"required":["slug","op","pages"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"member"},{"title":"pages:instantiate-shop-pack","description":"Seed the whole storefront anatomy as twelve draft pages in one call, each stamped with the job it does. Idempotent by the DATABASE, not by this call: a partial unique index on (workspace, shop_role) holds the at-most-one, so a second call creates nothing and a renamed page is still recognised.","type":"object","properties":{"slug":{"description":"which workspace. NOT an authority claim — the caller is authorized by the attested ctx through the same callerControlsWorkspace walk every pages:* receiver uses. Absent = the caller's own workspace.","type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"member"},{"title":"pages:fill-shop-pack","description":"Write a seller's real business facts into their twelve seeded shop pages. Fills the LIVE rows, so an edit made between seeding and filling survives. A fact not supplied keeps its visible placeholder — never an invented threshold, address or returns window.","type":"object","properties":{"slug":{"description":"which workspace. NOT an authority claim — the caller is authorized by the attested ctx through the same callerControlsWorkspace walk every pages:* receiver uses. Absent = the caller's own workspace.","type":"string"},"facts":{"type":"object","properties":{"identity":{"type":"object","properties":{"businessName":{"type":"string","description":"the shop's name — the one required fact; everything else may be withheld"},"whatYouSell":{"description":"\"Hand-thrown stoneware\" — the noun phrase the home hero is built around","type":"string"},"heroImage":{"description":"URL of the photograph the home hero is built around — fills the `[Hero image]` token. Withheld = no hero image, never a stock photo of somebody else's product","type":"string"},"founderName":{"type":"string"},"foundedYear":{"type":"number"}},"required":["businessName"],"additionalProperties":false},"commerce":{"type":"object","properties":{"currency":{"type":"string","description":"ISO 4217, e.g. EUR. Rendered as a symbol where one is known, else as the code — never a guessed symbol"},"freeShippingOver":{"description":"order value above which delivery is free. 0 is a REAL answer (free on everything), not 'unknown'","type":"number"},"returnDays":{"description":"days a buyer has to return. 0 is a REAL answer (no window), not 'unknown'","type":"number"}},"required":["currency"],"additionalProperties":false},"contact":{"type":"object","properties":{"email":{"type":"string"},"postalAddress":{"type":"string"},"phone":{"type":"string"},"openingHours":{"description":"\"9–17\" — rendered inside the pack's own \"Mon-Fri …\" copy","type":"string"},"responseWindow":{"description":"\"two working days\" — how fast a privacy request is answered","type":"string"}},"additionalProperties":false},"policies":{"type":"object","properties":{"jurisdiction":{"description":"whose law governs, and whose data authority a buyer may complain to","type":"string"},"effectiveDate":{"description":"as the merchant wants it printed — never derived from the clock","type":"string"}},"additionalProperties":false},"source":{"description":"where the facts came from, when they were extracted rather than typed","type":"object","properties":{"url":{"type":"string"}},"additionalProperties":false}},"required":["identity","commerce","contact"],"additionalProperties":false,"description":"ShopBusinessFacts — lib/puck/fill-shop-pack.ts is the type of record"},"stripPlaceholders":{"description":"Go-live mode (shop:build): after the fill, a bracket still unanswered is REMOVED — its sentence dropped, an image or link prop set to '' — never left visible and never invented. The removed tokens come back in `stripped`.","type":"boolean"}},"required":["facts"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"pages:fill-shop-pack-extract","description":"Best-effort ShopBusinessFacts from the seller's own site — fetch-then-confirm, never fetch-then-apply. Returns candidate facts for a form to pre-fill; nothing here writes a page. Reuses the movers SSRF guard (shape + fail-closed DNS, re-run on every redirect hop).","type":"object","properties":{"slug":{"description":"which workspace. Authorized from ctx, never from this field; absent = the caller's own","type":"string"},"url":{"type":"string","description":"the seller's own site. Refused by name as `blocked_host` when the SSRF guard — or any redirect hop's guard — says private"}},"required":["url"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"pages:fill-pack","description":"Fill a pack's instantiated pages with real business facts — one call, still drafts. Never fabricates a testimonial; pricing derives from one rate, not typed per page.","type":"object","properties":{"slug":{"type":"string"},"pages":{"type":"array","items":{"type":"object","properties":{"pageSlug":{"type":"string"},"slug":{"type":"string"}},"required":["pageSlug","slug"],"additionalProperties":false}},"facts":{"type":"object","properties":{"identity":{"type":"object","properties":{"company":{"type":"string"},"ownerName":{"type":"string"},"phone":{"type":"string"},"foundedYear":{"type":"number"},"city":{"type":"string"},"state":{"type":"string"},"metro":{"type":"string"},"streetAddress":{"type":"string"}},"required":["company","ownerName","phone","foundedYear","city","state","metro","streetAddress"],"additionalProperties":false},"licensing":{"type":"object","properties":{"usdot":{"type":"string"},"mc":{"type":"string"},"stateLicenseNumber":{"type":"string"},"regulatorOverride":{"type":"string"}},"required":["stateLicenseNumber"],"additionalProperties":false},"reputation":{"type":"object","properties":{"starRating":{"type":"number"},"reviewCount":{"type":"number"},"movesCompleted":{"type":"number"}},"required":["starRating","reviewCount","movesCompleted"],"additionalProperties":false},"serviceArea":{"type":"object","properties":{"neighborhoods":{"minItems":1,"type":"array","items":{"type":"string"}}},"required":["neighborhoods"],"additionalProperties":false},"pricing":{"type":"object","properties":{"hourlyRatePerMover":{"type":"number"},"truckFee":{"type":"number"},"tiers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"low":{"type":"number"},"high":{"type":"number"}},"required":["low","high"],"additionalProperties":false}}},"required":["hourlyRatePerMover","truckFee"],"additionalProperties":false},"story":{"type":"object","properties":{"originSentence":{"type":"string"}},"additionalProperties":false},"testimonials":{"type":"array","items":{"type":"object","properties":{"quote":{"type":"string"},"reviewerName":{"type":"string"},"moveType":{"type":"string"}},"required":["quote","reviewerName","moveType"],"additionalProperties":false}},"source":{"type":"object","properties":{"url":{"type":"string"}},"additionalProperties":false}},"required":["identity","licensing","reputation","serviceArea","pricing"],"additionalProperties":false}},"required":["slug","pages","facts"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"pages:fill-pack-extract","description":"Best-effort business facts from an operator's own URL or a free-text description — fetch-then-confirm, never fetch-then-apply. Returns candidate facts for a form to pre-fill; nothing here writes a page.","type":"object","properties":{"slug":{"type":"string"},"url":{"type":"string"},"text":{"type":"string"}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"movers:build","description":"The one intake orchestrator — takes a URL or a free-text description, extracts MoverBusinessFacts, clones the movers-factory template, and starts the run. The single op every door (web form, chat) shares; composes pages:fill-pack-extract + workflow:create + workflow:run, adds no new build primitive.","type":"object","properties":{"slug":{"type":"string"},"url":{"type":"string"},"describe":{"type":"string"}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-idempotent":false,"x-auth":"member"},{"title":"movers:funnel-provision","description":"Open, sponsored no-account provision — takes a contact name plus a URL or description, provisions a capped child workspace, and builds one of three things: a moving-company site + quote desk (movers, under moverchat), a store with products, photos and twelve pages in test mode (store), or a five-page business site with a front desk (site). Each vertical has its own sponsor budget, per-visitor rate limit and daily ceiling, and refuses past any wall. Ends on a preview token. The single writer behind the site-builder intake block's doors and the chat tool.","type":"object","properties":{"builds":{"description":"What to build. Absent = movers (every caller before the store and site verticals). Chooses the builder AND the sponsor budget; never names a workspace.","type":"string","enum":["movers","store","site"]},"flow":{"description":"`url-to-client` = the URL block's door: every vertical, movers included, runs the one url-to-client workflow (soul → build → review → publish), and a name is optional. Absent = each vertical's own workflow.","type":"string","enum":["vertical","url-to-client"]},"fields":{"description":"The URL block's operator-defined extra questions, answered — `{ label: answer }`, at most 12, each one line. Read into the extract and the chatbot's soul; never printed on a page as a fact.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"name":{"type":"string"},"url":{"type":"string"},"describe":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"visitorHash":{"type":"string"}},"required":["name","visitorHash"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-idempotent":false,"x-auth":"public"},{"title":"pages:versions","description":"List a page's saved version snapshots, newest first","type":"object","properties":{"slug":{"type":"string"},"page":{"type":"string"}},"required":["slug","page"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"pages:restore","description":"Restore a page to a prior version snapshot (snapshots current state first)","type":"object","properties":{"slug":{"type":"string"},"page":{"type":"string"},"ts":{"type":"number"}},"required":["slug","page","ts"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"member"},{"title":"pages:add-block","description":"Insert ONE block into a page at a position (default: append). Every other block is preserved verbatim — the targeted alternative to pages:edit's full-page rewrite.","type":"object","properties":{"slug":{"type":"string","description":"The WORKSPACE slug. Names which workspace; it never authorizes one — the caller clears `pagesDenyReason`'s attested walk."},"page":{"type":"string","description":"The page's own slug."},"section":{"type":"object","properties":{"component":{"type":"string","description":"A block name. Letters and digits, starting with a letter — anything else is refused as `invalid section`. Any of the registry blocks, not only the CRO subset `pages:edit` allowlists, plus any tenant block `blocks:declare` named."},"props":{"description":"The block's props, sent VERBATIM — the server runs `normalizeBlockProps` and does not fill defaults for you. Omitted is treated as `{}` by the handler.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["component"],"additionalProperties":false},"atIndex":{"description":"0-based insert position. Omitted = append at the end.","type":"integer","minimum":0,"maximum":9007199254740991}},"required":["slug","page","section"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"pages:update-block","description":"Merge new props into ONE block by id — a SHALLOW merge, so send only the top-level keys you are changing. Every other block is preserved verbatim.","type":"object","properties":{"slug":{"type":"string","description":"The workspace slug."},"page":{"type":"string","description":"The page's own slug."},"blockId":{"type":"string","description":"The block's id, as `pages:get` reports it in `blocks[]`."},"props":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"REQUIRED and must be an object — a missing or non-object value is refused `props must be an object`. Shallow-merged over the block's existing props, so a nested object is REPLACED, not deep-merged."}},"required":["slug","page","blockId","props"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"pages:remove-block","description":"Drop ONE block from a page by id. Every other block is preserved verbatim. NOT undoable through this door — the page's prior state lives only in a pages:versions snapshot if one was taken.","type":"object","properties":{"slug":{"type":"string","description":"The workspace slug."},"page":{"type":"string","description":"The page's own slug."},"blockId":{"type":"string","description":"The block's id, as `pages:get` reports it in `blocks[]`."}},"required":["slug","page","blockId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"member"},{"title":"pages:move-block","description":"Reorder ONE block to a new index. Every block keeps its props; only the order changes.","type":"object","properties":{"slug":{"type":"string","description":"The workspace slug."},"page":{"type":"string","description":"The page's own slug."},"blockId":{"type":"string","description":"The block's id, as `pages:get` reports it in `blocks[]`."},"toIndex":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"0-based destination index."}},"required":["slug","page","blockId","toIndex"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"nav:next","description":"Where to go next — the strongest (tags → door) path from where you stand, ranked over the dock words (lib/nav/doors.ts) from the learned edge (the D1 claw_paths mirror), never TypeDB. The same ranking orders the chat's starter cards. Every answer carries its tag trace: the exact (tag node → door node) pairs it was made under, so the outcome marks or warns that combination with the ordinary mark/warn verbs.","type":"object","properties":{"tags":{"type":"array","items":{"type":"string"},"description":"Where you stand, as tags — the page's and the viewer's. Lower-cased, deduped, sorted; at most six are used. The group is the caller's own (from the session), never a field here."}},"required":["tags"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"member"},{"title":"pages:review","description":"Review one of the main pages (MAIN_PAGES — the home page and every door word's page, lib/nav/main-pages.ts). Any key-holder. The verdict is a mark (good) or a warn (bad) on review:<check> → page:<path>; a warn must carry the reviewer's line and files a task with it, in the reviewer's own group. Agents run the checks a machine can (check: machine); people judge sense, truth and beauty (text/navigation.md card 29).","type":"object","properties":{"page":{"type":"string","description":"The main page's path, exactly as MAIN_PAGES lists it — '/', '/people', '/workflows'…"},"verdict":{"type":"string","enum":["good","bad"],"description":"good → mark the page's path; bad → warn it and file a task."},"check":{"type":"string","enum":["sense","truth","beauty","machine"],"description":"What was judged. `machine` is the agents' lane (a check a script can run); the other three are a person's."},"line":{"description":"The reviewer's one line — REQUIRED for bad (a task must say what is wrong); capped at 500 characters.","type":"string"}},"required":["page","verdict","check"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-auth":"member"},{"title":"pages:get","description":"Read one page as the EDITOR sees it — title, the lossless blocks[] (every block, every type, with its id) and the legacy CRO sections[]. Drafts included; call this before any block-addressed edit. pages:view is the public, published-only read.","type":"object","properties":{"slug":{"type":"string","description":"The workspace slug."},"page":{"type":"string","description":"The page's own slug."}},"required":["slug","page"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"copy:get","description":"The live text layer's edits for one of one.ie's own code-written pages (not /u/… — those are page-builder pages): every stored edit as {key, original, text}, and whether THIS caller may edit them (staff, or control of the platform workspace).","type":"object","properties":{"path":{"type":"string","description":"The page path, e.g. `/pricing`. Query and trailing slash are ignored."}},"required":["path"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"copy:save","description":"Save inline text edits on one of one.ie's own code-written pages — live on the next load, no deploy. An entry whose text is the original wording (or empty) removes that edit. Staff or controllers of the platform workspace only.","type":"object","properties":{"path":{"type":"string","description":"The page path, e.g. `/pricing`."},"entries":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"The original wording (normalised), plus `#n` for its nth repeat — must belong to `original`."},"original":{"type":"string"},"text":{"type":"string","description":"The new wording; the original or empty removes the edit."}},"required":["key","original","text"],"additionalProperties":false}}},"required":["path","entries"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"session"},{"title":"pages:children","description":"Walk a page's own block tree and return every ChildPageBlock's target slug. ONE LEVEL ONLY — never transitive into the embedded page's own tree.","type":"object","properties":{"slug":{"type":"string","description":"The workspace slug."},"page":{"type":"string","description":"The page's own slug."}},"required":["slug","page"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"pages:rename","description":"Change a page's URL slug. OLD LINKS BREAK — the page moves to /p/<newSlug> and the old path serves nothing.","type":"object","properties":{"slug":{"type":"string","description":"The workspace slug."},"page":{"type":"string","description":"The page's CURRENT slug."},"newSlug":{"type":"string","description":"The new slug. The collision check is GLOBAL, not per-workspace (`/p/<slug>` resolves by slug alone), so a slug any workspace already serves is refused `slug_taken`. Renaming to the same slug is refused `slug_unchanged`."}},"required":["slug","page","newSlug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"pages:instantiate-pack","description":"Seed the whole movers anatomy as ten draft pages in ONE call. NOT idempotent — a second call creates a second set, deduped by slug (home → home-2). pages:instantiate-shop-pack is the storefront's role-keyed equivalent, and that one IS idempotent.","type":"object","properties":{"slug":{"type":"string","description":"The workspace to seed. Names which workspace; the attested `callerControlsWorkspace` walk decides whether this caller may."}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"member"},{"title":"pages:optimize","description":"The page-experiment ratchet: decide promote / dissolve / keep for every active experiment the caller owns. The hourly `pages-optimize-tick` cron fires this with an empty body.","type":"object","properties":{"page":{"description":"Narrow to one page's experiments. Omitted = every active experiment the caller owns. THE WORKSPACE IS NOT A FIELD — it is always `ctx.ownerSlug`, so a body cannot aim this at someone else's pages.","type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"member"},{"title":"pages:propose","description":"Fill an active experiment's variant pool with up to five LLM-written plain-text candidates. Runs OFFLINE — the render path never calls a model.","type":"object","properties":{"slug":{"type":"string","description":"The workspace slug."},"page":{"type":"string","description":"The page's own slug."},"prop_path":{"type":"string","description":"The experiment's prop path — SNAKE_CASE, matching the `page_experiments` column, not a camelCase spelling."},"count":{"description":"How many candidates to ask for. CLAMPED to 5; the handler defaults to 3 when absent or non-numeric. The pool itself is capped at 5 total, so fewer may be added than requested.","type":"number"}},"required":["slug","page","prop_path"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"mover:agent-context","description":"The fact→agent bridge — render MoverBusinessFacts into ground-truth prose and write it to the workspace's company_context, so the mounted chat agent answers as the operator's real business. Never invents a service/review/policy; same facts as pages:fill-pack, one intake, two artifacts.","type":"object","properties":{"slug":{"type":"string"},"facts":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["slug","facts"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"settings:write","description":"Write a workspace setting value (caller or authorized descendant)","type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"value":{"type":"string"}},"required":["value"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"settings:set-home-page","description":"Name which published page a workspace serves at its root","type":"object","properties":{"slug":{"type":"string"},"page":{"type":"string"}},"required":["slug","page"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"domain:set","description":"Bind a custom domain to a workspace — returns the verification TXT/CNAME records to add","type":"object","properties":{"slug":{"type":"string"},"actorId":{"type":"string"},"host":{"type":"string"}},"required":["slug","host"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"verify_domain"},{"title":"course:save","description":"Create or update a course — omit courseId to create under a readable id minted from the title; an update writes only the fields sent","type":"object","properties":{"courseId":{"description":"Omit to CREATE: the server mints slugify(title) (reserved words and same-owner collisions get -2, -3 …). Given and existing → UPDATE only the fields present. Given and absent → insert under it.","type":"string"},"workspace":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"published":{"type":"boolean"},"price_cents":{"type":"number"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"member"},{"title":"course:get","description":"Get a course with its lessons (lesson bodies redacted unless enrolled or owner)","type":"object","properties":{"workspace":{"type":"string"},"slug":{"type":"string"},"courseId":{"type":"string"}},"required":["courseId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"course:list","description":"List a workspace's courses (published for others, all for the owner)","type":"object","properties":{"workspace":{"type":"string"},"slug":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"course:enroll","description":"Enroll the caller in a course (payment_required if priced and not comped)","type":"object","properties":{"workspace":{"type":"string"},"slug":{"type":"string"},"courseId":{"type":"string"}},"required":["courseId"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-idempotent":true,"x-auth":"member"},{"title":"course:lessons-save","description":"Upsert one or more lessons on a course — omitted fields are kept, expected_version turns a write into a compare-and-set","type":"object","properties":{"courseId":{"type":"string"},"workspace":{"type":"string"},"slug":{"type":"string"},"lessons":{"anyOf":[{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}],"description":"Lesson or lessons: { lessonId?, title?, body_md?, goal?, starters?, kind?, sort_order?, expected_version? }. No lessonId → a NEW lesson under slugify(title), suffixed -2, -3 … if taken (the minted id comes back in `versions`); neither lessonId nor title is refused. An existing lesson keeps every field omitted; a new one without sort_order appends. expected_version that no longer matches the stored lesson → that lesson is not written and comes back in `conflicts`."}},"required":["courseId","lessons"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"member"},{"title":"course:lesson-delete","description":"Delete one lesson from a course you own (unknown lesson → not_found; the rest keep their order)","type":"object","properties":{"courseId":{"type":"string"},"lessonId":{"type":"string","description":"The lesson to delete"},"workspace":{"type":"string"},"slug":{"type":"string"}},"required":["courseId","lessonId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"member"},{"title":"course:delete","description":"Delete a draft course you own with its lessons and enrollments (a published course is refused: unpublish it first)","type":"object","properties":{"courseId":{"type":"string"},"workspace":{"type":"string"},"slug":{"type":"string"}},"required":["courseId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"member"},{"title":"playbook:save","description":"Save a learner's playbook entry for a course lesson (upsert)","type":"object","properties":{"course":{"type":"string"},"lesson":{"type":"string"},"content":{"type":"string"},"slug":{"type":"string"},"workspace":{"type":"string"}},"required":["course","lesson"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"playbook:get","description":"Get the caller's playbook entries (optionally scoped to one course)","type":"object","properties":{"course":{"type":"string"},"slug":{"type":"string"},"workspace":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"playbook:promote","description":"Promote a completed playbook into a reusable skill in the workspace's content repo","type":"object","properties":{"course":{"type":"string"},"slug":{"type":"string"},"workspace":{"type":"string"}},"required":["course"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"company:render","description":"Read ONE page of a company's site and extract what it says about the company — plain fetch first, Cloudflare Browser Rendering only for a JS shell. Returns a Foundation patch plus provenance-fenced page text; never fabricates a field","type":"object","properties":{"url":{"type":"string"},"waitFor":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["url"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"company:map","description":"Discover a site's structure from its homepage anchors and classify them (pricing/about/product/blog/contact/legal). Depth 1 — this is NOT a crawl and starts no crawl job","type":"object","properties":{"url":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":50}},"required":["url"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"company:seo","description":"Read the SEO surface for a domain (keywords, backlinks, AI visibility) via DataForSEO and return it as a Foundation patch. SPENDS REAL CREDIT, so it skips itself with {ok:true,patch:{},skipped:'no_workspace'} when there is no attested workspace","type":"object","properties":{"domain":{"type":"string"},"slug":{"type":"string"}},"required":["domain"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"foundation:deep","description":"Run the 10-skill FOUNDATION sequence — each elevate-foundation-* SKILL.md body is loaded from the workspace's skill catalog and executed, and every field it produces is merged at inferred/scrape provenance so it can never outrank a human-confirmed one","type":"object","properties":{"slug":{"type":"string"},"source":{"type":"string","enum":["inferred","scrape"]}},"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-idempotent":false,"x-auth":"member"},{"title":"foundation:start","description":"Fill the Foundation's spine fields with one bounded LLM call over the workspace's own context. Refuses to overwrite a human-confirmed field; writes at chat/0.75","type":"object","properties":{"slug":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-idempotent":false,"x-auth":"member"},{"title":"foundation:read","description":"Read the workspace's Foundation as stored (null when nothing has been written yet)","type":"object","properties":{"slug":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"foundation:derive","description":"Turn the stored Foundation into DRAFT products and DRAFT ELEVATE playbook chapters. Insert-only (never overwrites a human edit), no price is ever guessed, and confidence is inherited from the weakest source fact","type":"object","properties":{},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"member"},{"title":"foundation:extract","description":"Fold every rendered page into ONE provenance-tracked Foundation patch, and report the spine paths still unanswered. Pure — no network, no LLM, no cost, no write. Its fencedEvidence is already wrapped by the provenance fence, so a downstream prompt cannot interpolate crawled text unfenced","type":"object","properties":{"home":{},"pages":{},"siteMap":{}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"foundation:save","description":"The single write of the company workflow. With an attested workspace it merges into workspace_settings.foundation provenance-aware; without one it holds the profile as an opaque 1h KV draft to be promoted at signup — an anonymous caller never writes a workspace","type":"object","properties":{"patch":{},"fill":{},"seo":{},"draftToken":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"public"},{"title":"foundation:promote-draft","description":"Carry an anonymous onboarding draft into the caller's workspace at signup and delete the KV key. Provenance survives, so a scraped field still loses to the human's later edit","type":"object","properties":{"draftToken":{"type":"string"}},"required":["draftToken"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"member"},{"title":"social:publish","description":"Report what a master social post has queued: how many Facebook post variants the publisher cron will really post (live, nextAt), how many sit as drafts on networks with no live connection, and how many are skip-only formats. Leaves the master post untouched; answers ok:false when nothing is publishable. The posting itself is the social-variant cron, one Facebook post per workspace per five-minute tick.","type":"object","properties":{"slug":{"type":"string"},"actorId":{"type":"string"},"id":{"type":"string"}},"required":["slug","actorId","id"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-idempotent":false,"x-auth":"update_group"},{"title":"social:news-to-drafts","description":"Turn fresh news items into platform-specific social post drafts","type":"object","properties":{"groupId":{"type":"string"},"maxItems":{"type":"integer","minimum":-9007199254740991,"maximum":10},"platforms":{"type":"array","items":{"type":"string"}}},"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-idempotent":false,"x-auth":"member"},{"title":"web:crawl","description":"Fetch a URL and extract domain, name, description, and readable text (public)","type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"people:create","description":"Create a person actor in the workspace","type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"}},"required":["name"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"companies:create","description":"Create a company group in the workspace","type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"conversation:start","description":"Start a new conversation thread (optionally seeded with a message, function lens, or recipient)","type":"object","properties":{"message":{"type":"string"},"fn":{"type":"string"},"actorId":{"type":"string"},"to":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"member"},{"title":"pages:view","description":"Read one published page's Puck render data by workspace + page slug (public) — the read an external site's page-editor plugin renders through; drafts are invisible (see pages:get for the member-scoped editor read)","type":"object","properties":{"slug":{"type":"string"},"page":{"type":"string"}},"required":["slug","page"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"billing:plan","description":"Change a workspace's plan — returns a checkout URL to complete the upgrade","type":"object","properties":{"slug":{"type":"string"},"actorId":{"type":"string"},"plan":{"type":"string","enum":["pro","agency","scale"]}},"required":["slug","actorId","plan"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"update_group"},{"title":"billing:topup","description":"Top up workspace AI credits — returns a checkout URL for the amount. Credits are prepaid, NON-WITHDRAWABLE service units: they buy work on ONE (AI replies, tool and skill calls, agent runs, storage, API requests) and there is no payout, withdraw or cash-out rail against a credits balance","type":"object","properties":{"slug":{"type":"string"},"actorId":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"}},"required":["slug","actorId","amount"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"update_group"},{"title":"video:ensure-defaults","description":"Ensure a workspace's default video rooms exist — returns which were created vs already present","type":"object","properties":{"workspace":{"type":"string"},"slug":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"booking:confirm-payment","description":"Confirm a booking after payment settles, by payment reference (public)","type":"object","properties":{"paymentRef":{"type":"string"}},"required":["paymentRef"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"booking:list-slots","description":"List open slots for a workspace's service on a date (or next open days)","type":"object","properties":{"slug":{"type":"string"},"service":{"type":"string"},"date":{"type":"string"},"days":{"type":"integer","minimum":1,"maximum":62}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-simulatable":false,"x-idempotent":true},{"title":"booking:list-services","description":"List a workspace's active bookable services (menu: name, duration, price, description, location, intake)","type":"object","properties":{"slug":{"type":"string"}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"public"},{"title":"booking:create","description":"Hold a slot for a customer; returns a ref and a payment intent when price > 0","type":"object","properties":{"slug":{"type":"string"},"service":{"type":"string"},"slotDate":{"type":"string"},"slotTime":{"type":"string"},"customer":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"type":"string"}},"required":["name"],"additionalProperties":false},"details":{"anyOf":[{"type":"string"},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}]},"paymentRail":{"type":"string","enum":["stripe","sui"]}},"required":["slug","service","slotDate","slotTime","customer"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-settles":"offchain","x-simulatable":true,"x-idempotent":true},{"title":"booking:configure","description":"Provider-gated: create or update a bookable service (hours, slot length, price, currency, tz, active)","type":"object","properties":{"slug":{"type":"string"},"actorId":{"type":"string"},"service":{"type":"string"},"name":{"type":"string"},"duration_min":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"price":{"type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"type":"string"},"hours_json":{"type":"array","items":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":false}}},"tz":{"type":"string"},"active":{"type":"boolean"},"description":{"type":"string"},"location":{"type":"string"},"buffer_min":{"type":"integer","minimum":0,"maximum":9007199254740991},"intake":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","choice"]},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"string"}}},"required":["key","label"],"additionalProperties":false}}},"required":["slug","name","duration_min","hours_json"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"manage_clients"},{"title":"booking:list-bookings","description":"Provider-gated: list a workspace's bookings for a month (customer, time, service, status)","type":"object","properties":{"slug":{"type":"string"},"month":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"manage_clients"},{"title":"booking:cancel","description":"Dissolve a booking by ref — provider (ctx-gated) or customer (ref + matching contact)","type":"object","properties":{"slug":{"type":"string"},"ref":{"type":"string"},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"type":"string"}},"required":["slug","ref"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"public"},{"title":"booking:reschedule","description":"Customer self-serve: move a booking to a new slot by ref + matching contact (hold-new-first)","type":"object","properties":{"slug":{"type":"string"},"ref":{"type":"string"},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"type":"string"},"newDate":{"type":"string"},"newTime":{"type":"string"}},"required":["slug","ref","newDate","newTime"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"public"},{"title":"workflow:list","description":"List a workspace's workflows (D1 mirror); pass templates=true for the public SOP catalog","type":"object","properties":{"slug":{"type":"string"},"templates":{"type":"boolean"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-simulatable":false,"x-idempotent":true,"x-auth":"view_workflows"},{"title":"workflow:get","description":"Fetch one workflow's full graph — steps (kind, config, position) and edges (with conditions)","type":"object","properties":{"workflowId":{"type":"string"}},"required":["workflowId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-simulatable":false,"x-idempotent":true,"x-auth":"view_workflows"},{"title":"workflow:runs","description":"List recent runs of a workflow (D1 workflow_run) for the monitor + history surfaces","type":"object","properties":{"workflowId":{"type":"string"},"runId":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":200},"stepId":{"type":"string"},"stepLimit":{"type":"integer","minimum":1,"maximum":100}},"required":["workflowId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-simulatable":false,"x-idempotent":true,"x-auth":"view_workflows"},{"title":"workflow:step-stats","description":"Per-step run counts, latency and last messages for one workflow (over D1 workflow_run_event) — what the canvas prints on each step card","type":"object","properties":{"workflowId":{"type":"string"},"sinceMs":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["workflowId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-simulatable":false,"x-idempotent":true,"x-auth":"view_workflows"},{"title":"workflow:preview-step","description":"Resolve one step's receiver + args through the real substitution code, with an optional mock trigger/step payload standing in for run history — never dispatches, reads no run history","type":"object","properties":{"workflowId":{"type":"string"},"stepId":{"type":"string"},"mockTrigger":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"mockSteps":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},"required":["workflowId","stepId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-simulatable":false,"x-idempotent":true,"x-auth":"view_workflows"},{"title":"workflow:create","description":"Create a blank workflow (group group-type=workflow) — optionally cloned from a template","type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"fromTemplate":{"type":"string"},"simulate":{"type":"boolean"}},"required":["name"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-simulatable":true,"x-idempotent":false,"x-auth":"manage_workflows"},{"title":"workflow:publish","description":"Bind a workflow the caller OWNS to a priced market listing. The seller is DERIVED from the workflow's own workspace through the attested ctx — there is deliberately no sellerUid field to spoof.","type":"object","properties":{"workflowId":{"type":"string"},"price":{"type":"number","minimum":0},"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}},"required":["workflowId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-simulatable":false,"x-idempotent":true,"x-auth":"manage_workflows"},{"title":"workflow:webhook-subscribe","description":"Register a URL that receives every future run's events for one workflow as signed, retried POSTs. Mints a signing secret server-side, returned once.","type":"object","properties":{"workflowId":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["workflowId","url"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-simulatable":false,"x-idempotent":false,"x-auth":"manage_workflows"},{"title":"workflow:apply-diff","description":"Apply a WorkflowDiff (add/remove/connect/disconnect/update). simulate=true validates the DAG without persisting","type":"object","properties":{"workflowId":{"type":"string"},"diff":{"type":"object","properties":{"add":{"type":"array","items":{"type":"object","properties":{"tempId":{"type":"string"},"kind":{"type":"string","enum":["trigger","tool","skill","agent","condition","human","delay","sell"]},"name":{"type":"string"},"config":{"type":"string"},"position":{"type":"string"}},"required":["tempId","kind","name","config"],"additionalProperties":false}},"remove":{"type":"array","items":{"type":"string"}},"connect":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"target":{"type":"string"},"condition":{"type":"string"}},"required":["source","target"],"additionalProperties":false}},"disconnect":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"target":{"type":"string"}},"required":["source","target"],"additionalProperties":false}},"update":{"type":"array","items":{"type":"object","properties":{"stepId":{"type":"string"},"field":{"type":"string","enum":["name","config","position","exit-condition","owner"]},"value":{"type":"string"}},"required":["stepId","field","value"],"additionalProperties":false}}},"additionalProperties":false},"simulate":{"type":"boolean"},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["workflowId","diff"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-simulatable":true,"x-idempotent":false,"x-auth":"manage_workflows"},{"title":"workflow:validate","description":"Run the §9 gate on a WorkflowDiff without persisting — kinds/config shapes, exactly-one-trigger, edges reference real steps, chain cycles; advisories ride back as warnings (grammar: code | code:stepId, never block). Every save door calls this.","type":"object","properties":{"workflowId":{"type":"string"},"diff":{"type":"object","properties":{"add":{"type":"array","items":{"type":"object","properties":{"tempId":{"type":"string"},"kind":{"type":"string","enum":["trigger","tool","skill","agent","condition","human","delay","sell"]},"name":{"type":"string"},"config":{"type":"string"},"position":{"type":"string"}},"required":["tempId","kind","name","config"],"additionalProperties":false}},"remove":{"type":"array","items":{"type":"string"}},"connect":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"target":{"type":"string"},"condition":{"type":"string"}},"required":["source","target"],"additionalProperties":false}},"disconnect":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"target":{"type":"string"}},"required":["source","target"],"additionalProperties":false}},"update":{"type":"array","items":{"type":"object","properties":{"stepId":{"type":"string"},"field":{"type":"string","enum":["name","config","position","exit-condition","owner"]},"value":{"type":"string"}},"required":["stepId","field","value"],"additionalProperties":false}}},"additionalProperties":false}},"required":["workflowId","diff"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-simulatable":true,"x-idempotent":true,"x-auth":"manage_workflows"},{"title":"workflow:run","description":"Start a run — spawns the WorkflowRun DO, executes each step, marks path strength on traversed edges","type":"object","properties":{"workflowId":{"type":"string"},"slug":{"description":"Workspace whose workflow to run; honoured only if you control it. Omit for your own. Refused (forbidden), never swapped for your own.","type":"string"},"triggerPayload":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"idempotencyKey":{"type":"string"},"test":{"description":"Test run: is_test=1, bypasses trigger match + flow gates, deposits zero pheromone. Steps still execute for real — not a dry run.","type":"boolean"}},"required":["workflowId"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-settles":"none","x-simulatable":false,"x-idempotent":true,"x-auth":"manage_workflows"},{"title":"build:run","description":"Start a build cycle — gates on credits (funding-of), spawns the BuildRun DO, runs the stub W1 wave, returns a runId","type":"object","properties":{"goal":{"type":"string"},"mode":{"type":"string","enum":["local","remote"]},"idempotencyKey":{"type":"string"}},"required":["goal"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-settles":"none","x-simulatable":false,"x-idempotent":true,"x-auth":"manage_workflows"},{"title":"build:resume","description":"Advance a parked build run by one wave — re-validates the run against the caller's workspace","type":"object","properties":{"runId":{"type":"string"}},"required":["runId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-simulatable":false,"x-idempotent":true,"x-auth":"manage_workflows"},{"title":"human:resolve","description":"Resolve a suspended human step — carries { runId, stepId, decision | formPayload } to the run DO","type":"object","properties":{"runId":{"type":"string"},"stepId":{"type":"string"},"decision":{"type":"string","enum":["approved","rejected"]},"formPayload":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"slug":{"type":"string"},"attestation":{"type":"string"},"assertion":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["runId","stepId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-simulatable":false,"x-idempotent":true,"x-auth":"manage_workflows"},{"title":"checkout:create","description":"The `sell` step's binding — mint a Connect checkout session for the buyer, stamping { runId, stepId } into session metadata so checkout:resume can wake the run","type":"object","properties":{"workspace":{"type":"string"},"ppid":{"type":"string"},"runId":{"type":"string"},"stepId":{"type":"string"}},"required":["workspace","ppid"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-settles":"offchain","x-simulatable":false,"x-idempotent":false,"x-auth":"manage_workflows"},{"title":"checkout:resume","description":"Wake a run suspended at a `sell` step — the storefront webhook fires this on checkout.session.completed with the (runId, stepId) it stamped at create. Sibling of human:resolve.","type":"object","properties":{"runId":{"type":"string"},"stepId":{"type":"string"},"slug":{"type":"string"}},"required":["runId","stepId"],"additionalProperties":false,"x-effect":"signal","x-cost":"free","x-simulatable":false,"x-idempotent":true,"x-auth":"manage_workflows"},{"title":"human:notify","description":"Post a channel-shaped approval into a run's conversation when it suspends at a human step — web card · Telegram inline keys · Discord components. Sibling of chat:send.","type":"object","properties":{"runId":{"type":"string"},"stepId":{"type":"string"},"stepName":{"type":"string"},"workflowName":{"type":"string"},"group":{"type":"string"},"proposal":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["runId","stepId"],"additionalProperties":false,"x-effect":"signal","x-cost":"free","x-simulatable":false,"x-idempotent":true,"x-auth":"manage_workflows"},{"title":"workflow:settled-notify","description":"Tell a run's started_by that it finished when there is no chat conversation to carry the outcome (manual/canvas/scheduled runs). settle() fires this group-less terminal only; a plain status line, never approval markup. Sibling of workflow:resumed-notify.","type":"object","properties":{"runId":{"type":"string"},"group":{"type":"string"},"status":{"type":"string"},"workflowName":{"type":"string"}},"required":["runId","group"],"additionalProperties":false,"x-effect":"signal","x-cost":"free","x-simulatable":false,"x-idempotent":true,"x-auth":"manage_workflows"},{"title":"workflow:stop","description":"Park a live run at its current step (status → paused); preserves the resume cursor so human:resolve or a re-run continues it","type":"object","properties":{"runId":{"type":"string"}},"required":["runId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-simulatable":false,"x-idempotent":true,"x-auth":"manage_workflows"},{"title":"workflow:trigger","description":"Fire every workspace workflow whose trigger step matches a channel source (e.g. webhook:telegram)","type":"object","properties":{"source":{"type":"string"},"slug":{"type":"string"},"triggerPayload":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["source"],"additionalProperties":false,"x-effect":"signal","x-cost":"variable","x-reversible":false,"x-simulatable":false,"x-idempotent":false,"x-auth":"manage_workflows"},{"title":"workflow:delete","description":"Delete a workflow and all its runs, steps, and edges","type":"object","properties":{"workflowId":{"type":"string"}},"required":["workflowId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"manage_workflows"},{"title":"workflow:update","description":"Rename a workflow or change its status (draft|active|paused)","type":"object","properties":{"workflowId":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused"]}},"required":["workflowId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"manage_workflows"},{"title":"workflow:fade","description":"Decay edge weights (strength & resistance) on one workflow — or all of the caller's workflows when workflowId is omitted — so stale bottlenecks stop glowing; multiplies both by (1-rate), default 0.05","type":"object","properties":{"workflowId":{"type":"string"},"rate":{"type":"number"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"manage_workflows"},{"title":"workflow:tql","description":"Emit one workflow as its .tql text form — a single-insert TypeQL document (group header + step things + path edges) that round-trips back through workflow:apply-tql","type":"object","properties":{"workflowId":{"type":"string"}},"required":["workflowId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-simulatable":false,"x-idempotent":true,"x-auth":"view_workflows"},{"title":"workflow:apply-tql","description":"Parse a .tql workflow document and apply it to an existing workflow THROUGH workflow:apply-diff — the sole validated persist door, so the import inherits the DAG check, the one-trigger law, the config gate and the authority walk. simulate:true validates and persists nothing","type":"object","properties":{"workflowId":{"type":"string"},"tql":{"type":"string"},"simulate":{"type":"boolean"},"version":{"type":"number"}},"required":["workflowId","tql"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-simulatable":true,"x-idempotent":false,"x-auth":"manage_workflows"},{"title":"skills:list","description":"List the caller's workspace skill catalog (R2) — powers the canvas SkillPicker","type":"object","properties":{"name":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-simulatable":false,"x-idempotent":true,"x-auth":"view_workflows"},{"title":"skill:save","description":"Write a skill body into a workspace's R2 catalog — the store skill:run/skills:list read; explicit-slug, ownership-walk authorized (mirrors world:publish-agent)","type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"content":{"type":"string"}},"required":["slug","name","content"],"additionalProperties":false,"x-effect":"ask","x-idempotent":true,"x-auth":"update_group"},{"title":"skill:run","description":"Run a workspace skill — loads its body from R2, runs one bounded turn via channels, returns { text }","type":"object","properties":{"skill":{"type":"string"}},"required":["skill"],"additionalProperties":{},"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-settles":"none","x-simulatable":false,"x-idempotent":false,"x-auth":"manage_workflows"},{"title":"agent:run","description":"Invoke a bound actor (optionally skill-constrained) for one bounded turn via channels; returns { text }","type":"object","properties":{"actorId":{"type":"string"},"skill":{"type":"string"},"instructions":{"type":"string"},"model":{"description":"Run this turn on a named model (an OpenRouter id, e.g. 'moonshotai/kimi-k3') instead of the actor's own. VETTED server-side against the workspace's enabledModelIds — a claim outside that list degrades to the operator's configured model, never to the claim. Absent = the actor's model, unchanged.","type":"string","maxLength":64},"tags":{"description":"Bare routing words for THIS call — a shape ('react-component'), a department ('sales'), a bake run id. Never namespaced. Carried onto the AI Gateway log as metadata beside the call's tokens and cost (channels/src/gateway-meta.ts), so spend can be filtered by them; never part of the user turn. The door's own signalId rides beside them from ctx, never from this body.","maxItems":12,"type":"array","items":{"type":"string","minLength":1,"maxLength":64}}},"additionalProperties":{},"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-settles":"none","x-simulatable":false,"x-idempotent":false,"x-auth":"manage_workflows"},{"title":"video:create-room","description":"Create a 100ms video room for a workspace; returns the room slug and URL","type":"object","properties":{"workspace":{"type":"string"},"roomSlug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["meeting","classroom","webinar"]},"region":{"type":"string"}},"required":["workspace","roomSlug","name"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":false,"x-auth":"manage_clients"},{"title":"video:delete-room","description":"Disable a video room and its 100ms counterpart; room is no longer joinable","type":"object","properties":{"workspace":{"type":"string"},"roomSlug":{"type":"string"}},"required":["workspace","roomSlug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"manage_clients"},{"title":"video:contact-call","description":"Provision a one-to-one video room for a contact; links the room thread to the contact CRM record","type":"object","properties":{"workspace":{"type":"string"},"actorId":{"type":"string"},"name":{"type":"string"}},"required":["workspace","actorId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":false,"x-auth":"manage_clients"},{"title":"video:invite","description":"Generate a tracked /go/ join link for an actor into an existing room","type":"object","properties":{"workspace":{"type":"string"},"roomSlug":{"type":"string"},"actorId":{"type":"string"}},"required":["workspace","roomSlug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":false,"x-auth":"manage_clients"},{"title":"video:schedule-webinar","description":"Create a webinar room and send tracked invite links to N contacts in one call","type":"object","properties":{"workspace":{"type":"string"},"name":{"type":"string"},"actorIds":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string"}}},"required":["workspace","actorIds"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":false,"x-auth":"manage_clients"},{"title":"video:create-session","description":"Create a video session with host + guest tracked join links; optionally schedules the call","type":"object","properties":{"workspace":{"type":"string"},"roomSlug":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["meeting","classroom","webinar"]},"region":{"type":"string"},"guestActorId":{"type":"string"},"scheduledAt":{"type":"number"}},"required":["workspace","roomSlug","name"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":false,"x-auth":"manage_clients"},{"title":"video:summary","description":"Run an AI summary of a call transcript and append it as a system message on the room thread","type":"object","properties":{"threadId":{"type":"string"},"transcript":{"type":"string"}},"required":["threadId","transcript"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-idempotent":false,"x-auth":"manage_clients"},{"title":"video:quick-room","description":"Ad-hoc video room from any chat thread — creates the room, sends the join link into the thread","type":"object","properties":{"workspace":{"type":"string"},"threadId":{"type":"string"},"name":{"type":"string"}},"required":["workspace"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":false,"x-auth":"manage_clients"},{"title":"video:request-meeting","description":"Visitor asks to meet a human: creates/reuses a meeting room for this conversation and notifies the workspace","type":"object","properties":{"workspace":{"type":"string"},"conversation":{"type":"string"},"roomSlug":{"type":"string"},"visitorName":{"type":"string"},"reason":{"type":"string"},"channel":{"type":"string"}},"required":["workspace"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"manage_clients"},{"title":"video:join-event","description":"Record a peer join event for tracking and lifecycle; public — called from the /go/ link handler","type":"object","properties":{"workspace":{"type":"string"},"roomSlug":{"type":"string"},"role":{"type":"string"},"actorId":{"type":"string"}},"required":["workspace","roomSlug"],"additionalProperties":false,"x-effect":"signal","x-cost":"free","x-idempotent":true},{"title":"video:start-recording","description":"Start cloud recording for an active room via 100ms REST; inserts a video_recordings row","type":"object","properties":{"workspace":{"type":"string"},"roomSlug":{"type":"string"}},"required":["workspace","roomSlug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":false,"x-auth":"manage_clients"},{"title":"video:room-status","description":"Who is in a room right now — staff names, a count of everyone else, and when the first staff peer joined","type":"object","properties":{"workspace":{"type":"string"},"roomSlug":{"type":"string"}},"required":["workspace","roomSlug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":true,"x-auth":"manage_clients"},{"title":"video:start-stream","description":"Start an HLS live stream for a room; returns the playback URL when the stream is ready","type":"object","properties":{"workspace":{"type":"string"},"roomSlug":{"type":"string"},"hlsConfig":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["workspace","roomSlug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-idempotent":false,"x-auth":"manage_clients"},{"title":"connect:channel","description":"Connect a channel (e.g. telegram) by pasting its bot token; verifies, sets the webhook, seals the credential under the owner gate","type":"object","properties":{"channel":{"type":"string"},"token":{"type":"string"},"slug":{"type":"string"}},"required":["channel","token"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"manage_clients"},{"title":"connect:status","description":"List connected channels for the workspace — channel, account, status, runtime; never the credential","type":"object","properties":{},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"manage_clients"},{"title":"news:desk","description":"Read or change a group's news desk: what it follows, how much each topic matters, when it runs, the voice. `op` picks the action — get · set · add-source · remove-source · suggest · setup · clone · logos · source-stories. `setup` turns a few topics into a working desk (sources picked from the 50-source catalogue, the daily-magazine workflow armed) in one call","type":"object","properties":{"workspace":{"description":"Group slug. Omit for your own. Honoured only if you control it.","type":"string"},"op":{"description":"Default `get`. `logos` collects missing source logos (a few per call; `remaining` says how many are left). `source-stories` lists a followed source's newest stories (`url`).","type":"string","enum":["get","set","add-source","remove-source","suggest","setup","clone","logos","source-stories"]},"topics":{"description":"`set`: {topic: weight 0–1}. `suggest` and `setup`: a list of topic words, e.g. [\"crypto\",\"sui\"].","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}}]},"hour":{"description":"UTC hour the issue is drafted and goes out.","type":"integer","minimum":0,"maximum":23},"cadence":{"description":"`set`: every day, or weekdays only, at `hour`.","type":"string","enum":["daily","weekdays"]},"refresh_hourly":{"description":"`set`: true = re-draft the coming issue every hour with the latest news until it goes out (never publishes; spends credits inside the daily cap).","type":"boolean"},"voice":{"description":"One paragraph on how the takes should sound.","type":"string","maxLength":1000},"channels":{"type":"array","items":{"type":"string","enum":["page","email","social"]}},"grid_size":{"type":"integer","minimum":2,"maximum":16},"approve_after":{"description":"Clean issues before the approval gate opens itself.","type":"integer","minimum":1,"maximum":30},"auto_publish":{"description":"`set`: true = this is automated news, publish each issue on its own with no approval click. A story that fails its grounding check is dropped, never published. false = back to the trust ladder (approve_after).","type":"boolean"},"url":{"description":"`add-source` / `remove-source`: the feed URL. A private address, an http URL or a slow host is refused by name.","type":"string"},"name":{"type":"string"},"source_topics":{"description":"`add-source`: the topics this source covers.","type":"array","items":{"type":"string"}},"weight":{"description":"`add-source`: how strongly this source pulls the ranking. Default 1.","type":"number","minimum":0,"maximum":3},"from":{"description":"`clone`: the group whose desk to copy. You must control both groups.","type":"string"},"limit":{"description":"`suggest` and `setup`: how many catalogue sources. Default 12.","type":"integer","minimum":1,"maximum":25}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"manage_workspace"},{"title":"news:ingest","description":"Fetch the feeds that are due — once each, for every group that follows them. Conditional GET, size and time caps, every URL and redirect hop through the SSRF guard. Run by the platform clock; not a per-group call","type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":50}},"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-idempotent":true,"x-auth":"platform"},{"title":"news:digest","description":"Pick and rank the day's stories for one group, write each take from the article only, find a picture, and store them as today's draft issue. Returns the issue id and honest counts — fetched · eligible · folded · kept · capped (with the budget that bit) · skipped by reason. Re-running the same day replaces the picks and keeps the issue","type":"object","properties":{"workspace":{"description":"Group slug. Omit for your own.","type":"string"},"refresh":{"description":"Set by the hourly refresh workflow: only narrows — refused once the day's run has begun (the desk's hour on the issue's day), so an issue a person may be reviewing is never rebuilt.","type":"boolean"}},"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":true,"x-idempotent":false,"x-auth":"manage_workspace"},{"title":"news:issue","description":"Build the issue from its picks: one editable page (lead, grid, source strip) that the email and the post drafts are both made from. Rebuilding replaces the page's content and keeps its address","type":"object","properties":{"refresh":{"description":"Set by the hourly refresh workflow: only narrows — refused once the day's run has begun (the desk's hour on the issue's day), so an issue a person may be reviewing is never rebuilt.","type":"boolean"},"workspace":{"description":"Group slug. Omit for your own.","type":"string"},"issueId":{"description":"Default: today's draft issue.","type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":true,"x-idempotent":true,"x-auth":"manage_workspace"},{"title":"news:publish","description":"Publish the issue: the page goes live, the email is scheduled to confirmed subscribers (suppression and unsubscribe unchanged) and the post drafts are queued. Reads the PAGE at publish time, so an edit is what goes out. A held issue is refused by name. Needs a person unless the desk's gate has opened itself: a closed gate opens only for a signed-in person or a workflow run a person approved, never for a flag in the request","type":"object","properties":{"workspace":{"description":"Group slug. Omit for your own.","type":"string"},"issueId":{"description":"Default: today's issue.","type":"string"},"approve":{"description":"A signed-in person's intent to publish. On its own it opens nothing: a closed gate answers `held:needs_approval` unless the caller is a signed-in person or a workflow run whose approval step a person resolved.","type":"boolean"}},"additionalProperties":false,"x-effect":"signal","x-cost":"variable","x-reversible":false,"x-idempotent":false,"x-auth":"manage_workspace"},{"title":"news:react","description":"More or less of a story: strengthens or resists the desk's paths to that source and its topics, so tomorrow's order changes. One reaction of a kind per person per story counts","type":"object","properties":{"workspace":{"description":"Group slug. Omit for your own.","type":"string"},"issueId":{"type":"string"},"itemUrl":{"type":"string","description":"The story's article URL, as on the issue."},"reaction":{"type":"string","enum":["more","less","tap","skip"]}},"required":["issueId","itemUrl","reaction"],"additionalProperties":false,"x-effect":"signal","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"member"},{"title":"news:assist","description":"A story's quick actions — summarise, expand, research, article in the group's voice, or related stories. Asked once, kept for everyone: a cached answer comes back instantly; a miss runs the model the route's paths favour (assist:<kind>: → model:<id>), falls to the next on failure, and stores the answer. Anyone reads cached answers of published stories; a signed-in person may start one (20 a day per group); owners may force a fresh one. A verdict marks or warns the model that wrote the answer","type":"object","properties":{"workspace":{"type":"string","description":"The magazine's group slug."},"itemUrl":{"type":"string","description":"The story's article URL, as on the issue."},"kind":{"type":"string","enum":["summarise","expand","research","article","related","journey"],"description":"What to do with the story. related and journey need no model: stories sharing its tags; the story's path from its feed to its posts."},"fresh":{"description":"Owners only: run the model again even though an answer is stored.","type":"boolean"},"verdict":{"description":"Judge the stored answer instead: marks or warns the model that wrote it.","type":"string","enum":["up","down"]}},"required":["workspace","itemUrl","kind"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-idempotent":true,"x-auth":"public"},{"title":"news:edit","description":"A person edits an issue by hand: rate a story 1 to 10 (10 leads the issue, 1 sinks it), rewrite its headline or take inline, or remove it (undoable). The page is rebuilt in the new order, a published issue's page included — the email already sent is not. A rating teaches two kinds of path by its change from the last: the desk's (tomorrow's issue) and the person's own (reader:<slug>: → source / tag)","type":"object","properties":{"workspace":{"description":"Group slug. Omit for your own; a named group must be one you control.","type":"string"},"issueId":{"type":"string","description":"The issue the story is on."},"itemUrl":{"type":"string","description":"The story's article URL, as on the issue."},"action":{"type":"string","enum":["rate","remove","restore","text"],"description":"rate sets the story's score; remove takes it off the issue; restore puts it back; text saves a rewritten headline and/or take."},"value":{"description":"rate: 1 to 10; 0 clears the rating.","type":"integer","minimum":0,"maximum":10},"headline":{"description":"text: the new headline; empty returns the article's own.","type":"string","maxLength":300},"take":{"description":"text: the new take (counts as checked — a person wrote it).","type":"string","maxLength":1200}},"required":["issueId","itemUrl","action"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"manage_workspace"},{"title":"broadcast:create","description":"Create a broadcast draft — subject, body_md, audience_tag, channel","type":"object","properties":{"workspace":{"type":"string"},"subject":{"type":"string"},"body_md":{"type":"string"},"audience_tag":{"type":"string"},"channel":{"type":"string","enum":["email","sms","whatsapp"]}},"required":["workspace"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"write"},{"title":"broadcast:update","description":"Update a broadcast draft — subject, body, audience, schedule","type":"object","properties":{"workspace":{"type":"string"},"broadcastId":{"type":"string"},"subject":{"type":"string"},"body_md":{"type":"string"},"audience_tag":{"type":"string"},"scheduled_at":{"type":"number"}},"required":["workspace","broadcastId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"write"},{"title":"broadcast:list","description":"List broadcasts for a workspace with status and sent_at","type":"object","properties":{"workspace":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","sending","sent","cancelled"]},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":100}},"required":["workspace"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"read"},{"title":"broadcast:get","description":"Get a single broadcast with recipient counts","type":"object","properties":{"workspace":{"type":"string"},"broadcastId":{"type":"string"}},"required":["workspace","broadcastId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"read"},{"title":"segment:create","description":"Create an audience segment from a rule definition (SegmentDef: {all, any?})","type":"object","properties":{"workspace":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"definition":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["workspace","name","definition"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"write"},{"title":"segment:update","description":"Update an audience segment — name, description, or definition","type":"object","properties":{"workspace":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"definition":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["workspace","id"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"write"},{"title":"segment:list","description":"List audience segments for a workspace","type":"object","properties":{"workspace":{"type":"string"}},"required":["workspace"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"read"},{"title":"segment:get","description":"Get one audience segment with its rule definition","type":"object","properties":{"workspace":{"type":"string"},"id":{"type":"string"}},"required":["workspace","id"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"read"},{"title":"segment:preview","description":"Preview an audience segment — live count + up to 10 sample addresses (read-only)","type":"object","properties":{"workspace":{"type":"string"},"definition":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"channel":{"type":"string","enum":["email","sms","whatsapp"]}},"required":["workspace","definition"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"read"},{"title":"segment:delete","description":"Delete an audience segment and its membership snapshot","type":"object","properties":{"workspace":{"type":"string"},"id":{"type":"string"}},"required":["workspace","id"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"write"},{"title":"broadcast:test","description":"Send a test email for a broadcast to one address","type":"object","properties":{"workspace":{"type":"string"},"broadcastId":{"type":"string"},"to":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["workspace","broadcastId","to"],"additionalProperties":false,"x-effect":"signal","x-cost":"variable","x-reversible":false,"x-idempotent":false,"x-auth":"write"},{"title":"broadcast:send","description":"Seed recipients from audience tag, apply suppression, enqueue the send batch","type":"object","properties":{"workspace":{"type":"string"},"broadcastId":{"type":"string"}},"required":["workspace","broadcastId"],"additionalProperties":false,"x-effect":"signal","x-cost":"variable","x-reversible":false,"x-idempotent":false,"x-auth":"write"},{"title":"broadcast:schedule","description":"Schedule a broadcast to send at a future unix timestamp","type":"object","properties":{"workspace":{"type":"string"},"broadcastId":{"type":"string"},"scheduled_at":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["workspace","broadcastId","scheduled_at"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"write"},{"title":"broadcast:cancel","description":"Cancel a scheduled or in-progress broadcast","type":"object","properties":{"workspace":{"type":"string"},"broadcastId":{"type":"string"}},"required":["workspace","broadcastId"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"write"},{"title":"voice:provision","description":"Configure a voice agent for the workspace — creates/updates the ElevenLabs agent, links an optional Twilio number, returns the embed snippet","type":"object","properties":{"agentName":{"type":"string"},"voiceId":{"type":"string"},"phone":{"type":"string"},"greeting":{"type":"string"},"instructions":{"type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"manage_clients"},{"title":"voice:token","description":"Mint a short-lived ElevenLabs conversation token for the workspace; 404 if voice is disabled (slug-opaque: disabled ≡ not found)","type":"object","properties":{"slug":{"type":"string"}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"public"},{"title":"voice:call","description":"Trigger an outbound call to a phone number via the workspace ElevenLabs agent; logs the call to D1, links to workflowRunId when present","type":"object","properties":{"phone":{"type":"string"},"instructions":{"type":"string"},"workflowRunId":{"type":"string"}},"required":["phone"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-settles":"none","x-idempotent":false,"x-auth":"manage_clients"},{"title":"audience:subscribe","description":"Begin double opt-in for a contact — writes consent:email:pending tag, sends confirm email","type":"object","properties":{"workspace":{"type":"string"},"address":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"list":{"type":"string"},"ref":{"type":"string"}},"required":["workspace","address"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"public"},{"title":"audience:unsubscribe","description":"One-click unsubscribe — writes suppression row and flips consent tag; RFC 8058 safe","type":"object","properties":{"workspace":{"type":"string"},"channel":{"type":"string","enum":["email","sms","whatsapp"]},"address":{"type":"string"},"token":{"type":"string"}},"required":["workspace","address","token"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"public"},{"title":"audience:confirm","description":"Confirm email subscription via opt-in token — flips consent tag to subscribed","type":"object","properties":{"token":{"type":"string"}},"required":["token"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"public"},{"title":"audience:consent","description":"The signed-in person grants or withdraws their OWN consent for one channel (email, sms, push, call, ads) in one group — recorded with source `self` and the time; nobody else can write it","type":"object","properties":{"workspace":{"type":"string","description":"The group the consent is given to. Ads consent lands on the person's own row there, `actor:<uid>`, where the ad audience gate reads it; email lands on their verified address, where the send gate reads it."},"channel":{"type":"string","enum":["email","sms","push","call","ads"]},"state":{"type":"string","enum":["granted","withdrawn"]},"actorId":{"description":"Optional, and only ever checked: it must be the caller themselves. The actor is the attested session; naming anyone else is refused.","type":"string"}},"required":["workspace","channel","state"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"write"},{"title":"audience:winback","description":"Re-engage dormant subscribers (batch winback sequence tool) — queries contacts with no send in `days` days, sends one re-engage email each through the suppression-checked send path","type":"object","properties":{"days":{"type":"number"},"campaign":{"type":"string"}},"additionalProperties":false,"x-effect":"signal","x-cost":"variable","x-reversible":false,"x-idempotent":false,"x-auth":"write"},{"title":"message:send","description":"Send a message to one address via channel — suppression-checked; sms/whatsapp dissolve until adapters ship","type":"object","properties":{"workspace":{"type":"string"},"channel":{"type":"string","enum":["email","sms","whatsapp"]},"to":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"campaign":{"type":"string"}},"required":["workspace","channel","to","body"],"additionalProperties":false,"x-effect":"signal","x-cost":"variable","x-reversible":false,"x-idempotent":false,"x-auth":"write"},{"title":"links:create","description":"Create a tracked link in one of two shapes. ACTOR-BOUND (`actorId` given): the click elevates that contact to rung-4 identity at `/go/:id`, pre-warms their snapshot, and personalises the page + chat; the caller must hold authority over the contact's workspace. CAMPAIGN-ONLY (`campaignId` given, no `actorId`): the shape cold ad traffic needs, since an ad click is anonymous by definition and can never name a contact at mint time — the contact-owner walk is skipped, `actor_id` is stored null, and the click is attributed to the campaign alone. Exactly one of `actorId` / `campaignId` is required; supplying neither is refused. Minting is authed in both shapes; only the CLICK is anonymous. `slug` and `createdBy` are stamped from the attested session, never the body.","type":"object","properties":{"actorId":{"description":"Contact (actor) the link is bound to — must belong to the caller's workspace or a descendant. Omit for cold ad traffic, in which case `campaignId` is REQUIRED so the click is never fully unattributed","type":"string"},"destination":{"description":"Path the click lands on (must start with '/'); default '/'","type":"string"},"context":{"description":"Extra context injected into the agent's system prompt for this session","type":"string"},"greeting":{"description":"Override the chat agent's opening line","type":"string"},"campaignId":{"description":"Group clicks under a campaign for the learning loop. REQUIRED when `actorId` is absent. Forwarded onto the destination URL as `utm_campaign` so the landing page and the click row report the same campaign; capped at 128 chars","type":"string"},"expiresInDays":{"description":"Link TTL in days; omitted = never expires","type":"number"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"member"},{"title":"links:bulk-create","description":"Create one actor-bound tracked link per contact for a selected segment (the segment-campaign send). Authority is walked PER contact — any the caller can't reach is skipped (counted in `denied`), never failing the batch. Capped at 200.","type":"object","properties":{"actorIds":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"string"},"description":"Contacts to mint a link for — each must belong to the caller's workspace or a descendant"},"destination":{"description":"Shared destination path (must start with '/'); default '/'","type":"string"},"campaignId":{"description":"Group all clicks under one campaign for the learning loop","type":"string"},"expiresInDays":{"type":"number"}},"required":["actorIds"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"member"},{"title":"tags:list","description":"List a workspace's tag namespaces, with the platform's LOCKED namespaces beside them. `workspace` names which workspace; the caller's authority over it is walked from the attested session, never from the field.","type":"object","properties":{"workspace":{"description":"Workspace slug to read; defaults to the caller's own. The caller must control it or a 'forbidden' is returned","type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"tags:create","description":"Create a tag namespace in a workspace. Refuses a LOCKED name — those are substrate vocabulary, not tenant vocabulary. A re-create is IDEMPOTENT and returns the existing row (the insert is ON CONFLICT DO NOTHING), the same answer `POST /api/tags` gives; `not_created` means the row could not be read back at all, never that it already existed.","type":"object","properties":{"workspace":{"description":"Workspace slug to create in; defaults to the caller's own","type":"string"},"namespace":{"type":"string","description":"The namespace, one bare word — never `lifecycle:marketing`"},"values":{"description":"Closed set of allowed values; omit for a free namespace","type":"array","items":{"type":"string"}},"colour":{"type":"string"}},"required":["namespace"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"tags:delete","description":"Delete a tag namespace by id (`<workspace>:<namespace>`). The authority walk runs against the ROW's stored workspace, never the id's prefix — an id is caller-supplied and may not name its own owner. A locked namespace is refused.","type":"object","properties":{"id":{"type":"string","description":"Namespace row id, `<workspace>:<namespace>`"}},"required":["id"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"member"},{"title":"tags:suggest","description":"Ad-hoc tags used more often than `threshold` in a workspace — the candidates an owner may promote into a namespace. Capped at 100 rows by the query.","type":"object","properties":{"workspace":{"description":"Workspace slug to read; defaults to the caller's own","type":"string"},"threshold":{"description":"Minimum usage count; default 20. A negative or non-numeric value falls back to 20 rather than returning everything","type":"number"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"templates:list","description":"List a workspace's signal templates — the saved composer pre-fills, newest starred first. Optional role and free-text filters.","type":"object","properties":{"workspace":{"description":"Workspace slug to read; defaults to the caller's own","type":"string"},"role":{"type":"string","enum":["marketer","sales","service","owner"]},"search":{"description":"Substring matched against name and body","type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"templates:save","description":"Create or update one signal template. `workspace_id` is stamped from the EXISTING row when the id already exists, otherwise from the walked workspace — a body can never file a template into a workspace the caller does not control. The `_starter` catalogue is read-only.","type":"object","properties":{"id":{"type":"string","description":"Stable template id; an existing id updates that row in its own workspace"},"name":{"type":"string"},"workspace":{"description":"Workspace to file a NEW template under; ignored when the id already exists","type":"string"},"role":{"description":"Default 'owner'","type":"string","enum":["marketer","sales","service","owner"]},"receiverMode":{"description":"Default 'direct'","type":"string","enum":["direct","world","all","sub"]},"receiverTarget":{"type":"string"},"tags":{"description":"BARE words — never `lifecycle:marketing`","type":"array","items":{"type":"string"}},"body":{"type":"string"},"sendAt":{"description":"'now' | '+24h' | an ISO datetime; default 'now'","type":"string"},"attach":{"type":"array","items":{"type":"string"}},"starred":{"type":"boolean"},"createdAt":{"type":"number"}},"required":["id","name"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"member"},{"title":"templates:delete","description":"Delete one signal template by id. The authority walk runs against the ROW's stored workspace, never a body field. The `_starter` catalogue is read-only.","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"member"},{"title":"rewards:enroll","description":"Bind a referrer wallet to a referred wallet at signup, as a weighted Path written with `mark`. FIRST BINDING WINS — an existing inbound path to the referred wallet is never re-routed, so a later spoof cannot redirect a payout. Accepts the two addresses either flat or under `content` (the shape pay/backend sends). Self-referral is refused.","type":"object","properties":{"content":{"description":"The nested shape pay/backend's enrollReferrer posts","type":"object","properties":{"referrer":{"type":"string","description":"Referrer wallet address"},"referred":{"type":"string","description":"Referred wallet address"}},"required":["referrer","referred"],"additionalProperties":false},"referrer":{"description":"Referrer wallet address, flat form","type":"string"},"referred":{"description":"Referred wallet address, flat form","type":"string"},"tags":{"description":"Carried through from the signal envelope; not read by the handler","type":"array","items":{"type":"string"}}},"additionalProperties":false,"x-effect":"signal","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"agent_key"},{"title":"sui:vocabulary","description":"The ONE vocabulary as the Sui Move contracts express it — the 6 dimensions and 6 verbs with their TQL and Move names, plus the Move module list. Read-only, no arguments, no tenant data.","type":"object","properties":{},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"sui:lifecycle","description":"The latest lifecycle journey run on Sui — one transaction per stage with its explorer digest. Served from KV when the simulator has written one (`source:'kv'`), otherwise the embedded testnet snapshot. Read-only, no arguments.","type":"object","properties":{},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"public"},{"title":"sui:generate","description":"Run the vocabulary enrichment workflow for a workspace: extract, validate alignment against the Move modules, then fan out to the cache and task sinks. Returns the consolidated summary, or `{ok:false, stage:'validate', findings}` when alignment fails — a failed validation never fans out. The workspace is walked from the attested caller.","type":"object","properties":{"workspace":{"description":"Workspace slug; defaults to the caller's own. The caller must control it","type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-idempotent":false,"x-auth":"member"},{"title":"fn:run","description":"Execute an allowlisted TypeDB function by name. Returns the function's result rows. Not public — caller must be authenticated; the resolver re-walks authority before executing.","type":"object","properties":{"fn":{"type":"string","description":"Function name from FN_MAP (e.g. 'optimal_route', 'actionable_hypotheses')"},"args":{"description":"Named arguments matching the function's param list","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"workspace":{"description":"Workspace slug for authority context","type":"string"},"fresh":{"description":"Bypass the edge memo and read the graph from BrainDO (slower, exact)","type":"boolean"}},"required":["fn"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-idempotent":true,"x-auth":"member"},{"title":"rag:search","description":"Search the OO-Brain knowledge corpus (Supabase pgvector). Hybrid retrieval: vector cosine + tsvector BM25 fused with RRF. Returns top-k chunks + a query_id. Always follow with rag:mark to close the quality loop.","type":"object","properties":{"query":{"type":"string","description":"Natural-language query. Full sentence beats keywords."},"k":{"default":5,"description":"Chunks to return (1–20, default 5).","type":"integer","minimum":1,"maximum":20},"corpus":{"default":"@oo-brain","description":"Which imported brain (@-pointer, e.g. '@oo-brain'). Authority-walked against your workspace; omit for the platform default.","type":"string"},"vault":{"default":"all","type":"string","enum":["oo-brain","agency-operator","personal-brain","all"]},"filter_path_prefix":{"type":"string"},"filter_tags":{"type":"array","items":{"type":"string"}}},"required":["query","k","corpus","vault"],"additionalProperties":false,"x-effect":"ask","x-cost":{"fixed":1},"x-reversible":false,"x-idempotent":true,"x-auth":"read_corpus"},{"title":"rag:list","description":"List the knowledge corpora you may search (@-pointers), resolved by the workspace authority walk. The platform corpus @oo-brain is always included.","type":"object","properties":{},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"read_corpus"},{"title":"rag:mark","description":"Close the quality loop on a rag:search call. Call before the turn ends. 'mark' = chunks helped; 'warn' = chunks didn't help; 'unsure' = can't assess.","type":"object","properties":{"query_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"outcome":{"type":"string","enum":["mark","warn","unsure"]},"notes":{"type":"string"},"corpus":{"default":"@oo-brain","description":"The corpus the query_id belongs to (@-pointer). Authority-walked; omit for the platform default.","type":"string"}},"required":["query_id","outcome","corpus"],"additionalProperties":false,"x-effect":"signal","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"read_corpus"},{"title":"rag:connect","description":"Register a knowledge source (e.g. a Google Drive folder) to sync into a workspace brain. Records the source in workspace_settings.sources; ingest-tick pulls changes on a schedule. Provision the brain (brain:provision) first.","type":"object","properties":{"provider":{"default":"google-drive","type":"string","enum":["google-drive"]},"folder_id":{"type":"string","description":"Drive folder id to sync (read-only)."},"corpus":{"description":"Target brain @-pointer; defaults to your workspace brain @<slug>-brain. Authority-walked (write_corpus).","type":"string"}},"required":["provider","folder_id"],"additionalProperties":false,"x-effect":"ask","x-cost":{"fixed":1},"x-reversible":true,"x-idempotent":true,"x-auth":"write_corpus"},{"title":"brain:ingest","description":"Ingest one document (Drive file, URL, or inline text) into a corpus: fetch -> markdown -> chunk -> hash-gate -> embed -> upsert with document provenance. Idempotent on content_hash.","type":"object","properties":{"corpus":{"type":"string","description":"Target brain @-pointer. Authority-walked (write_corpus)."},"source_ref":{"description":"Drive file id or URL — the stable key for tombstones + hash-gate.","type":"string"},"document_url":{"description":"Fetch URL for the document.","type":"string"},"raw_text":{"description":"Inline markdown/text/html.","type":"string"},"mime_type":{"type":"string"},"content_hash":{"type":"string"},"title":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}},"required":["corpus"],"additionalProperties":false,"x-effect":"ask","x-cost":{"fixed":1},"x-reversible":false,"x-idempotent":true,"x-auth":"write_corpus"},{"title":"brain:provision","description":"Idempotently create a workspace or personal brain: a corpus thing @<slug>-brain contained by the owning group. Safe to call repeatedly (put). Auth walks the workspace group (the corpus does not exist yet).","type":"object","properties":{"slug":{"type":"string","description":"Target workspace or personal slug."},"kind":{"default":"workspace","type":"string","enum":["workspace","personal"]},"actorId":{"type":"string"}},"required":["slug","kind"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"write_corpus"},{"title":"brain:tombstone","description":"Remove a deleted source document's chunks from a corpus, keyed by source_ref (Drive file id or URL). Fired by ingest-tick when a previously-known file no longer appears in a folder listing.","type":"object","properties":{"corpus":{"type":"string","description":"Target brain @-pointer. Authority-walked (write_corpus)."},"source_ref":{"type":"string","description":"The stable key used at ingest — Drive file id or URL."}},"required":["corpus","source_ref"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"write_corpus"},{"title":"rag:promote","description":"Distill repeat retrieval winners into typed fact. Sweeps retrieval_outcomes for chunks with >=5 mark and 0 warn in a 14-day window, extracts a verbatim statement (no synthesis), and writes it via memory:remember into the chunk's owning group. Fired by the promote-tick cron trigger; safe to call anonymously — the target group is derived from data, never a caller-supplied workspace.","type":"object","properties":{},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"public"},{"title":"health:diagnose","description":"Probe every deployed surface and the receiver failure rates D1 already records, then write the verdict back as weighted paths (mark on up, warn on down or on a sick receiver) so the next sweep starts from what the last one learned. Diagnoses only — it never restarts, redeploys or kills anything, because the remote half has no provably safe remedy. Fired by the health-tick cron trigger.","type":"object","properties":{},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"public"},{"title":"seo:backlinks-summary","description":"Pull live backlink summary for a domain via DataForSEO; marks domain→seo:backlinks path","type":"object","properties":{"target":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":1000}},"required":["target"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"seo:llm-mentions","description":"Pull live AI-visibility (LLM mentions) data for a domain via DataForSEO; marks domain→seo:llm-mentions path","type":"object","properties":{"target":{"type":"string"}},"required":["target"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"seo:keywords-for-keyword","description":"Return related keyword suggestions for a seed keyword via DataForSEO Google Ads; marks keyword→seo:keywords path","type":"object","properties":{"keyword":{"type":"string"},"location_code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"language_code":{"type":"string"}},"required":["keyword"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"seo:serp","description":"Return full Google Organic SERP for a keyword via DataForSEO async task (submit→poll); marks keyword→seo:serp path","type":"object","properties":{"keyword":{"type":"string"},"location_code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"language_code":{"type":"string"},"device":{"type":"string"}},"required":["keyword"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"seo:keyword-metrics","description":"Return monthly search volume, CPC, and competition for a list of keywords via DataForSEO async task","type":"object","properties":{"keywords":{"type":"array","items":{"type":"string"}},"location_code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"language_code":{"type":"string"}},"required":["keywords"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"seo:gsc-performance","description":"Return Google Search Console click/impression/CTR/position data for a site via Composio GSC toolkit","type":"object","properties":{"site_url":{"type":"string"},"start_date":{"type":"string"},"end_date":{"type":"string"},"dimensions":{"type":"array","items":{"type":"string"}},"row_limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["site_url","start_date","end_date"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":true,"x-idempotent":false,"x-auth":"member"},{"title":"promise:make","description":"State terms and exactly one proof observable — the terms FREEZE (sha-256 terms_hash, insert-once) and the promise enters state 'promised'. The maker is the attested caller, never a body field","type":"object","properties":{"slug":{"type":"string","description":"Stable id for the promise, e.g. story:<origin>. [A-Za-z0-9_:/-], max 128"},"terms":{"type":"string","description":"What is promised — hashed verbatim into terms_hash and never rewritten"},"proof":{"type":"string","description":"The ONE observable that decides kept vs broken. A shell-shaped proof settles at PROVE via the CLI, never in the worker"}},"required":["slug","terms","proof"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-settles":"none","x-idempotent":true,"x-auth":"member"},{"title":"promise:settle","description":"Close the loop on a promise — kept marks the path, broken warns it, and a terminal promise never re-settles. Only the PERSISTED maker may settle; the verdict is the maker's assertion, the resolver never runs the proof","type":"object","properties":{"slug":{"type":"string"},"kept":{"description":"Defaults to true. false ⇒ settled-broken: resistance += 1, the path decays honestly","type":"boolean"},"composite":{"description":"Rubric composite; scales the mark by 5× when kept","type":"number"}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-settles":"none","x-idempotent":false,"x-auth":"member"},{"title":"duty:make","description":"State a duty you OWE — terms, one observable, an owed count, a due_at, and a certifier who must not be you. The holder is the attested caller, never a body field; certifier === holder is refused by the resolver and by a D1 CHECK","type":"object","properties":{"slug":{"type":"string","description":"Stable id, e.g. ehc:cyp-005:H2. [A-Za-z0-9_:/-], max 128"},"terms":{"type":"string","description":"What is owed — hashed verbatim into terms_hash"},"observable":{"type":"string","description":"What ONE delivery looks like: 'a meal, on a date, received' — not 'a meal service was commissioned'"},"certifier":{"type":"string","description":"Who may attest delivery. MUST NOT be the holder — the duty-holder never grades its own homework"},"owed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many deliveries are owed. 0 means not yet quantified and computes to state 'unknown', never 'met'"},"due_at":{"description":"Epoch ms the window closes. ABSENT IS UNKNOWN, never 'no deadline' — an unwritten window computes to 'unknown', never to on-track","type":"number"}},"required":["slug","terms","observable","certifier","owed"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-settles":"none","x-idempotent":true,"x-auth":"member"},{"title":"duty:amend","description":"Amend by LINEAGE — writes a new row at version+1 with `supersedes`; the prior version is never mutated and never deleted. Holder only today: an amendment against the holder's will needs a tribunal rung that does not exist yet (§3.3 Q3) and is refused by name","type":"object","properties":{"slug":{"type":"string"},"terms":{"type":"string"},"observable":{"type":"string"},"certifier":{"description":"Still must not equal the holder","type":"string"},"owed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"due_at":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-settles":"none","x-idempotent":false,"x-auth":"member"},{"title":"duty:evidence","description":"File ONE delivery against the current version — the CERTIFIER only, matched against the persisted certifier from the attested caller. Idempotent by sha256(slug‖version‖ref), so a re-file changes nothing. A new delivery MARKS the holder's path","type":"object","properties":{"slug":{"type":"string"},"ref":{"type":"string","description":"The delivery, named: 'meal 2026-09-12', 'SLT session note wk37'"},"version":{"description":"Defaults to the current version; an older one is refused, not back-filed quietly","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["slug","ref"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-settles":"none","x-idempotent":true,"x-auth":"member"},{"title":"duty:breach","description":"Compute the verdict and land it in the record. SILENCE IS BREACH: owed > count(evidence) with the window closed is `breached`, and no caller supplies a verdict. Warns the holder's path on the transition into breach — once, because the TRANSITION is the event. `breached` is NOT terminal: late evidence recomputes to `met`","type":"object","properties":{"slug":{"type":"string"}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"member"},{"title":"duty:get","description":"Read a duty with its state COMPUTED, writing nothing — the read a plan surface makes. NOT public (a duty names a child): holder, certifier or platform staff only. The family's own rung is not modelled yet","type":"object","properties":{"slug":{"type":"string"}},"required":["slug"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"member"},{"title":"ui:navigate","description":"There is deliberately no field naming WHO to move. The reader moved is always the caller's own, resolved from the attested session server-side. If you find yourself wanting a target, that is the defect arriving.","type":"object","properties":{"href":{"type":"string","minLength":1,"description":"Where to. A SAME-ORIGIN PATH: one leading '/', e.g. '/u/one/in'. Refused, never sanitised: an absolute URL ('https://evil.com/x'), any scheme ('javascript:', 'data:'), a protocol-relative href ('//evil.com'), the backslash form ('/\\evil.com'), a bare host ('evil.com/x'), and any href containing a tab/CR/LF. Measured against node's WHATWG parser: new URL('//evil.com', 'https://one.ie'), new URL('/\\evil.com', …) and new URL('/<TAB>/evil.com', …) ALL resolve to https://evil.com/ — the parser strips tab/CR/LF anywhere in the input, so the tab form is a real bypass of a naive startsWith('/') check. A navigate receiver that accepts arbitrary hrefs is an open redirect with an agent attached."},"reason":{"description":"Why the move happened, for the host's own judgment. Mirrors NavigateRequest.reason in one.ie/web/src/lib/navigate.ts, and is ECHOED back on the response so the transport has something to forward. CALLER-ASSERTED and carrying NO authority: an agent is free to send 'select', which reads as 'an operator clicked'. Nothing gates on it, and a host must not read it as evidence that a human was there.","type":"string","enum":["select","command","agent"]},"replace":{"description":"Replace the current history entry instead of pushing a new one. Default false: collapsing the entry deletes the operator's way back, so it is opt-in.","type":"boolean"}},"required":["href"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":false,"x-auth":"session"},{"title":"media:list","description":"Every image and video a workspace owns, as typed rows — ONE R2 scan of `{workspace}/` filtered to the seven prefixes the reader will actually serve (media, chat, ads, products, pages, brand, courses), so generated chat images and ad creative are visible, not just hand-uploads. Carries `scanned` (how much of the page was not media), `truncated` (the budget that bit) and `nextCursor`. Each row's `url` is the one door that reads bytes.","type":"object","properties":{"workspace":{"description":"Group slug. Omit for your own. Honoured only if you may read it.","type":"string"},"kind":{"description":"Omit for both. Filters the rows on this page; it does not change what is scanned.","type":"string","enum":["image","video"]},"prefix":{"description":"Only assets under this top-level namespace. media = hand-uploads and library generations; chat = images/videos an agent made in a conversation; ads = creative; products/pages/courses/brand = assets filed beside the thing they illustrate.","type":"string","enum":["media","chat","ads","products","pages","brand","courses"]},"limit":{"description":"R2 objects to SCAN on this page BEFORE prefix/kind filtering — not a row count. Default 500, max 1000 (R2's own ceiling). A workspace whose bucket is mostly non-media can return few rows from a full scan; that is what `scanned` reports.","type":"integer","minimum":1,"maximum":1000},"cursor":{"description":"The nextCursor from the previous page.","type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-settles":"none","x-idempotent":true,"x-auth":"member"},{"title":"media:upload","description":"Put ONE raster image into a workspace's media library and get back the key and the url that serves it. Name exactly one source: `base64` (bytes you hold) or `url` (a public https address the server fetches under an SSRF guard, no redirects, 5 MiB hard cap). The stored content type comes from the MAGIC BYTES, never from what you declare — SVG is refused deliberately, and video is not accepted here.","type":"object","properties":{"workspace":{"description":"Group slug. Omit for your own. Honoured only if you may read it.","type":"string"},"url":{"description":"Public https address to fetch. Alternative to `base64`, never both. Private, loopback, link-local and CGNAT addresses are refused, as is any redirect.","type":"string"},"base64":{"description":"The image bytes, base64. A `data:` prefix is accepted and stripped. Alternative to `url`, never both.","type":"string"},"filename":{"description":"A LABEL for the key, not a path — separators are stripped and the extension always comes from the sniffed bytes, so `../` and a `.svg` suffix are both inert. Omit and the key is a bare uuid.","type":"string"},"contentType":{"description":"A HINT only. The stored value is decided by the magic bytes, because the public reader serves the stored value verbatim under nosniff.","type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-settles":"none","x-idempotent":false,"x-auth":"member"},{"title":"media:generate","description":"Generate ONE image from a prompt and file it in the workspace's media library. Keyless — flux-1-schnell on the Cloudflare AI binding. Returns the key and the url that serves it. Unlike the storefront generator this takes no destination: it always writes `{workspace}/media/`, because a library is a prefix and not a context.","type":"object","properties":{"workspace":{"description":"Group slug. Omit for your own. Honoured only if you may read it.","type":"string"},"prompt":{"type":"string","minLength":1,"description":"What to draw. Truncated at 2000 chars after `context` is folded in."},"context":{"description":"Extra prompt material — brand, palette, subject. A QUALIFIER appended to the prompt, NOT a destination: it never changes the key prefix.","type":"string"}},"required":["prompt"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-settles":"none","x-idempotent":false,"x-auth":"member"},{"title":"activity:announce","description":"Broadcasts a system event to matched subscribers via tag-intersection fan-out","type":"object","properties":{"event":{},"tags":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"affiliate:approve","description":"Approve or reject a pending affiliate join request","type":"object","properties":{"decision":{},"requestId":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"owner"},{"title":"affiliate:join-request","description":"Submit a request to join an affiliate program","type":"object","properties":{"program":{},"reason":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"affiliate:ppc-payout","description":"Drains unpaid PPC accrual for a budget to affiliate payout addresses via pay.one.ie","type":"object","properties":{"budgetId":{},"chain":{},"refToAddress":{},"treasuryAddress":{},"workspace":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"owner"},{"title":"agent:draft","description":"Draft an agent's reply into a thread the caller's workspace owns, for a human to review before it is sent","type":"object","properties":{},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"agent:schedule","description":"Writes a scheduled job row for an actor to be woken later","type":"object","properties":{"actorId":{},"cron":{},"instructions":{},"skill":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"owner"},{"title":"calendar:schedule-meeting","description":"Sends a scheduling email to a contact and returns status","type":"object","properties":{"amountLabel":{},"email":{},"name":{},"stepName":{},"workspace":{}},"additionalProperties":{},"x-effect":"signal","x-reversible":false,"x-auth":"session"},{"title":"campaign:brief","description":"Creates a campaign group from a brief, fires async channels BUILD, and returns the group ID and slug","type":"object","properties":{"brief":{},"name":{},"url":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"member"},{"title":"campaign:rebuild","description":"Runs the ELEVATE build again for a campaign that is stuck or failed; brief defaults to the campaign name","type":"object","properties":{"campaignId":{},"brief":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"member"},{"title":"campaign:update","description":"Updates a campaign's name or a specific section's content, and returns the updated campaign info","type":"object","properties":{"campaignId":{},"content":{},"name":{},"stageKey":{},"stageName":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"member"},{"title":"chat:delete-template","description":"Deletes a chat template for a chip_id in the workspace","type":"object","properties":{"agent_id":{},"chip_id":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"chat:list-templates","description":"Lists chat templates for the workspace, optionally filtered by agent_id","type":"object","properties":{"agent_id":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"chat:set-template","description":"Saves or updates a chat template for a chip_id in the workspace","type":"object","properties":{"agent_id":{},"chip_id":{},"response_text":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"checkout:link","description":"Mints a shareable payment link for a product price","type":"object","properties":{"chain":{},"network":{},"ppid":{},"slug":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"owner"},{"title":"checkout:notify","description":"Posts a pay link into the conversation for a sell step","type":"object","properties":{"amountLabel":{},"group":{},"runId":{},"stepId":{},"stepName":{},"url":{}},"additionalProperties":{},"x-effect":"signal","x-reversible":false,"x-auth":"session"},{"title":"content:draft","description":"Generate or retrieve a cached content draft for a given workspace, function, channel, and lifecycle stage","type":"object","properties":{"channel":{},"fn":{},"lifecycle":{},"workspace":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"owner"},{"title":"content:list","description":"List recent content drafts for a workspace, optionally filtered by function","type":"object","properties":{"fn":{},"workspace":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"owner"},{"title":"content:everywhere","description":"Put one piece of content everywhere: one video or image + one campaign → a native draft for every social format and every ad format it fits, written from the campaign's playbook stage, filed under the campaign as content things, with every misfit derived or named impossible. Counts what was made, failed, derived and skipped; nothing publishes — the reply links to the campaign page where a person approves each draft.","type":"object","properties":{"workspace":{"description":"Group slug. Omit for the attested workspace. A scope REQUEST — refused (forbidden) when the authority walk says no, never swapped for your own.","type":"string"},"campaignId":{"type":"string","description":"The campaign's gid (world_groups.gid tagged `campaign`) in this workspace — the campaign the drafts are filed under."},"mediaUrl":{"type":"string","description":"The source video or image url — an attachment in the conversation, or an item from media:list."},"mediaType":{"type":"string","enum":["image","video"],"description":"What the source is."},"text":{"type":"string","minLength":1,"description":"The message every format is written from — the person's words."},"stageKey":{"description":"The ELEVATE stage (0–10, or the campaign's own section key) that briefs every draft. Change the stage, the words change.","type":"string"},"width":{"description":"Source width in px, when known — decides which aspect formats fit as-is.","type":"number"},"height":{"description":"Source height in px, when known.","type":"number"},"durationS":{"description":"Source duration in seconds, for a video.","type":"number"},"origin":{"description":"Absolute origin to resolve a relative mediaUrl for the render service (the route passes url.origin).","type":"string"}},"required":["campaignId","mediaUrl","mediaType","text"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-idempotent":false,"x-auth":"manage_things"},{"title":"content:derive","description":"Derive every format a source does not fit as-is — reframe (9:16 · 1:1 · 4:5 · 16:9), stills, slides, PDF pages, text-only — from one source content thing, recording each derived asset as a thing. Idempotent: what was already derived is reported `already`, never made twice. Wraps deriveForPlan (lib/content-derive.ts).","type":"object","properties":{"workspace":{"description":"Group slug. Omit for the attested workspace; refused when not yours.","type":"string"},"sourceTid":{"type":"string","description":"The source content thing's tid (content:everywhere answers it as `sourceTid`)."}},"required":["sourceTid"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-idempotent":true,"x-auth":"manage_things"},{"title":"content:schedule","description":"Spread a post's approved variants across the calendar: one per network per day starting tomorrow 09:00, writing social_post_variants.scheduled_at + status 'scheduled'. Facebook is the only network with a live connection; every other network and every ad is scheduled as a draft and says so in its note (Instagram and the ad pushers answered 404 on 2026-10-12; Meta Ads is not connected).","type":"object","properties":{"workspace":{"description":"Group slug. Omit for the attested workspace; refused when not yours.","type":"string"},"postId":{"description":"The master social_posts row whose variants to schedule. Required unless `variantId` is given.","type":"string"},"variantId":{"description":"Move exactly ONE variant of this workspace to `at` instead of re-slotting a post. Only a 'scheduled' or 'approved' row moves; a published, failed or skipped one is refused. A bare world key is refused (moving a slot to now arms a real publish).","type":"string"},"at":{"description":"Unix seconds (an integer) for `variantId`. Required with `variantId`; ignored without it.","type":"number"},"all":{"description":"true when a person approved the whole run (a workflow's human step): schedules 'draft' variants as well as 'approved' ones.","type":"boolean"},"timezone":{"description":"IANA zone for the 09:00 slot. Default UTC — a workspace carries no timezone setting today.","type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":true,"x-idempotent":true,"x-auth":"manage_things"},{"title":"content:verdicts","description":"Write the brand guardian's verdict on EACH draft and ad creative of a post. Parses one line per item (`<id>: approve|revise - reason`) from the review step's text and saves meta.verdict + verdict_reason on every social_post_variants row and every creative-asset thing; an item the reviewer never mentioned is saved as 'no-verdict', never as approval. Marks content:review -> <platform>:<format> on approve, warns on revise and on no-verdict. Ids are recomputed from the workspace's own rows, never taken from the caller. Does not change any status — the human approve step is still the gate.","type":"object","properties":{"workspace":{"description":"Group slug. Omit for the attested workspace; refused when not yours.","type":"string"},"postId":{"type":"string","description":"The master social_posts row whose variants and ad creatives were reviewed (content:derive answers it as `postId`)."},"text":{"type":"string","description":"The reviewer's reply: one line per item id, `<id>: approve - reason` or `<id>: revise - reason`."}},"required":["postId","text"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"manage_things"},{"title":"conversation:autonomy","description":"Read a conversation's autonomy level from tags, defaulting to 'auto' when missing, for the channels worker to decide send vs draft","type":"object","properties":{"entityId":{},"group":{},"id":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"conversation:route","description":"Runs the 5-rung turn-taking ladder to route a conversation message to an agent","type":"object","properties":{"authorKind":{},"entityId":{},"messageId":{},"replyTo":{},"sender":{},"tags":{},"text":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"credits:balance","description":"Returns the credits balance for the authenticated caller's slug","type":"object","properties":{},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"email:send","description":"Sends a transactional email on behalf of the workspace","type":"object","properties":{"body":{},"html":{},"subject":{},"to":{}},"additionalProperties":{},"x-effect":"signal","x-reversible":false,"x-auth":"session"},{"title":"enrollment:demote-on-suspend","description":"Demotes all members of a workspace group on suspension","type":"object","properties":{"workspace":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"platform"},{"title":"enrollment:restore-on-resume","description":"Restores all members of a workspace group on resume with the provided plan","type":"object","properties":{"plan":{},"workspace":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"platform"},{"title":"inbox","description":"Reads an actor's own message history from D1 and channels","type":"object","properties":{"_suffix":{},"limit":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"lead:capture","description":"Captures a form submit from any standalone page as a lead, resolving workspace from the page slug, and returns the leadId","type":"object","properties":{"fields":{},"page":{},"visitorHash":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"public"},{"title":"learning:complete","description":"Grants credits and records pending reward when a learner completes a course stage. FINDING: falls back to data.workspace when the caller is unattested","type":"object","properties":{"courseId":{},"kind":{},"stageId":{},"workspace":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"learning:dream","description":"Creates hypotheses from hardened paths and evidence edges, idempotently","type":"object","properties":{},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"platform"},{"title":"learning:eval","description":"Evaluates dream-sourced hypotheses against new deal signals, updating confidence and status","type":"object","properties":{},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"platform"},{"title":"lifecycle:mine","description":"Read the caller's own lifecycle stage transitions","type":"object","properties":{"lifecycle":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"market:quote","description":"Prices a blended deal and optionally creates an offer deal in KV","type":"object","properties":{"seller":{},"skill":{},"steps":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"market:stake","description":"Bridges an on-chain stake event into routing reputation by calling mark()","type":"object","properties":{"amountMist":{},"seller":{},"taskId":{}},"additionalProperties":{},"x-effect":"signal","x-reversible":false,"x-auth":"platform"},{"title":"member:invited","description":"Send an invite email to a member after an invite_member action, checking authorization and generating a signed token","type":"object","properties":{"email":{},"role":{},"slug":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"owner"},{"title":"memory:assert","description":"Writes a hypothesis from a statement or claim to TypeDB. FINDING: no authority check: an anonymous caller writes a hypothesis into workspace \"default\"","type":"object","properties":{"claim":{},"statement":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"memory:remember","description":"Writes an agent-asserted hypothesis linked to the workspace group","type":"object","properties":{"actorId":{},"key":{},"value":{},"workspace":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"owner"},{"title":"memory:reveal","description":"Returns all six memory types (hypotheses, paths, memberships, episodic, semantic, social, procedural) for an actor","type":"object","properties":{"actorId":{},"workspace":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"owner"},{"title":"movers:funnel-event","description":"Records a preview-only movers-funnel edge (previewed, tried, owner) for the workspace behind a preview token","type":"object","properties":{"token":{"type":"string"},"event":{"type":"string","enum":["previewed","tried","owner"]}},"required":["token","event"],"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"public"},{"title":"movers:funnel-claim","description":"Claims a sponsored preview workspace for the signed-in user, binding them as owner","type":"object","properties":{"token":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"pages:chat-generate","description":"Generates a deterministic chat pack for a page, updates the database, and returns the pack and its hash","type":"object","properties":{"page":{},"workspace":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"member"},{"title":"payout:get","description":"Retrieve a merchant's payout treasury addresses (sui/evm) and Stripe connect status after workspace ownership check","type":"object","properties":{"workspace":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"owner"},{"title":"payout:set","description":"Set a merchant's crypto payout treasury addresses (sui/evm) and its custody switch (off | on) after workspace ownership check and human presence confirmation","type":"object","properties":{"confirm":{},"custody":{},"treasury_evm":{},"treasury_sui":{},"workspace":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"owner"},{"title":"plugins:buy-with-credits","description":"Buy a plugin using workspace credits, granting entitlement synchronously","type":"object","properties":{"name":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"member"},{"title":"plugins:buy-with-one-token","description":"Buys a plugin by verifying a Sui ONE token transfer and granting entitlement with no credit mint","type":"object","properties":{"name":{},"tx":{},"txDigest":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"member"},{"title":"plugins:credit-balance","description":"Returns the spendable credit balance and funding slug for the caller's workspace","type":"object","properties":{},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"member"},{"title":"promise:get","description":"Read a promise's terms and state publicly by slug","type":"object","properties":{"slug":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"public"},{"title":"remote:resolve","description":"Resume a run parked at a remote step — the remote system's attested answer wakes the run (sibling of human:resolve)","type":"object","properties":{},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"manage_workflows"},{"title":"reply:discord","description":"Round-trips a human inbox reply back to the originating Discord surface","type":"object","properties":{"entityId":{},"text":{},"workspace":{}},"additionalProperties":{},"x-effect":"signal","x-reversible":false,"x-auth":"owner"},{"title":"reply:telegram","description":"Round-trips a human inbox reply back to the originating Telegram surface","type":"object","properties":{"entityId":{},"text":{},"workspace":{}},"additionalProperties":{},"x-effect":"signal","x-reversible":false,"x-auth":"owner"},{"title":"reply:web","description":"Round-trips a human inbox reply back to the originating web surface","type":"object","properties":{"entityId":{},"text":{},"workspace":{}},"additionalProperties":{},"x-effect":"signal","x-reversible":false,"x-auth":"owner"},{"title":"sdk:init","description":"Resolves the developer's workspace slug from actor membership and records the sdk.init lifecycle event","type":"object","properties":{},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"public"},{"title":"social:refine","description":"Adapt a master post into per-platform draft variants via refine core","type":"object","properties":{"postId":{},"targets":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"update_group"},{"title":"secrets:call","description":"Use a key somebody lent you, without ever holding it. The opener finds your grant, checks its signature against the vault's grant-signers, counts the call BEFORE it is made, opens the key in memory, sends ONE request to the provider's fixed host and header on an allow-listed path (no redirect followed), scrubs the key from the answer and drops it. The caller is the session or attested agent — a body field never names it.","type":"object","properties":{"provider":{"type":"string","enum":["openai","anthropic","stripe","github","dataforseo","composio"],"description":"A row of secrets/src/providers.ts — the one host and header a key may be sent to. Anything else refuses unknown_provider."},"secret":{"description":"`<vault>/<NAME>` of one lent secret, when you hold grants on several keys for this provider. Omitted: the first grant to you for this provider.","type":"string"},"request":{"type":"object","properties":{"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]},"path":{"type":"string","description":"The provider path, e.g. `/v1/chat/completions`. Every provider row is an allow-catalogue (plan D17): the method AND the decoded, normalised path must match one entry exactly, and every query key must be one that entry names — else path_not_allowed. The grant's for.paths names entries (ids or exact templates) and can never add one; absent, the row's default set."},"body":{"description":"Sent as JSON (a string is sent as-is). Ignored on GET. When the grant carries for.models, a model-taking entry needs a JSON body in which EVERY field named `model`, at any depth, is on that list."}},"required":["method","path"],"additionalProperties":false}},"required":["provider","request"],"additionalProperties":false,"x-effect":"ask","x-cost":"variable","x-reversible":false,"x-idempotent":false,"x-auth":"authenticated"},{"title":"secrets:used","description":"Close the loop on one use of a lent key: `mark` on the path `actor → provider:<name>`, or `warn` on it when `refused` is set. Written by whoever made the call (the web resolver, channels) — the opener keeps the meter and writes no signal (plan D9).","type":"object","properties":{"provider":{"type":"string","enum":["openai","anthropic","stripe","github","dataforseo","composio"],"description":"The provider row the call went to — the same closed set secrets:call takes; a path `actor → provider:<name>` is only ever written for a real row."},"secret":{"description":"`<vault>/<NAME>` that was used.","type":"string"},"grant":{"description":"The grant id the call ran on.","type":"string"},"today":{"description":"Calls on that grant today, after this one.","type":"number"},"perDay":{"type":"number"},"refused":{"description":"Set when the call was refused — the loop closes with a warn instead of a mark. The opener's REFUSALS, then the web side's own: not_in_workflow · opener_unbound · opener_unreachable · vault_not_yours.","type":"string","enum":["no_key","bad_signature","cannot_verify","stopped","expired","over_limit","path_not_allowed","redirect","unknown_provider","bad_key","not_in_workflow","opener_unbound","opener_unreachable","vault_not_yours"]}},"required":["provider"],"additionalProperties":false,"x-effect":"signal","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"authenticated"},{"title":"secrets:give","description":"Give a key to ONE. The value arrives sealed on the giver's side to ONE's lock alone (read from ONE's vault, never a constant) and signed by a key on the vault's grant-signers; the opener checks the signature, opens the key in memory, refuses a signed subject that is not the attested caller and a sealed plaintext that does not name this give's vault, name and provider, makes ONE cheap Check it call to the provider row's check entry, flags a key that can make other keys (or whose scopes cannot be read), and stores the sealed key keyed `<vault>/<name>` — by compare-and-set on the record it replaces — with the row's host, header and entries as they are now. Afterwards only the last four characters show. The giver is the session or attested agent — a body field never names it. Closes with a mark on `actor → provider:<name>`, a warn on any refusal.","type":"object","properties":{"signer":{"type":"object","properties":{"kind":{"type":"string","enum":["person","agent"],"description":"agent: its own ed25519 Sui key (the CLI's --signer-key, the SDK's giveData). person: a passkey touch made on the seal page (C9) — the master-derived key never signs."},"sig":{"type":"string","description":"The signature over the payload's canonical bytes (keys sorted, @oneie/sdk/secrets) — a Sui personal-message signature (agent) or the WebAuthn assertion JSON (person)."},"signer":{"type":"string","description":"Who signed: the agent's Sui address, or `p256:<point>` for a passkey. It must be on payload.vault's grant-signers, read from the chain."}},"required":["kind","sig","signer"],"additionalProperties":false},"payload":{"type":"object","properties":{"type":{"type":"string","const":"give"},"vault":{"type":"string","description":"The giver's Sui vault, `0x` + 64 lower-case hex. Its grant-signers decide who may give; the key is stored as `<vault>/<name>` and nobody listed on another vault can change it."},"body":{"type":"object","properties":{"name":{"type":"string","description":"The .env name, e.g. OPENAI_API_KEY — letters, digits and `_`."},"provider":{"type":"string","enum":["openai","anthropic","stripe","github","dataforseo","composio"],"description":"A row of secrets/src/providers.ts; anything else refuses unknown_provider before the chain is read."},"sealed":{"type":"string","description":"Sealed to ONE's lock and no other reader (`age:<base64>`, the @oneie/sdk/secrets-give sealForOne form) over the canonical plaintext `{\"name\",\"provider\",\"v\":1,\"value\",\"vault\"}` naming this give's vault, name and provider — any other is seal_mismatch. Never the value."},"mode":{"type":"string","enum":["give","check"],"description":"check: verify, open and Check it, answer, and store nothing."},"allowFlagged":{"description":"Signed with the rest: store a key Check it flagged — admin_key · full_secret_key · admin_scope · key_scope (a key that can make other keys or reach admin), or scopes_unknown (a GitHub token whose scopes cannot be read).","type":"boolean"},"replaces":{"anyOf":[{"type":"string","pattern":"^[0-9a-f]{64}$"},{"type":"null"}],"description":"Signed with the rest: the sigHash of the record this give replaces (`given.sigHash` of the last give, or a stale refusal's detail), null for a first give. Anything else refuses stale — a captured give re-sent after a rotate never rolls it back."},"subject":{"type":"object","properties":{"kind":{"type":"string","const":"actor"},"id":{"type":"string"}},"required":["kind","id"],"additionalProperties":false,"description":"Signed with the rest: the giver's own actor — the caller this request is attested as (session, world key or attested agent). Any other refuses subject_mismatch, so a captured give resent under another session is never theirs."}},"required":["name","provider","sealed","mode","replaces","subject"],"additionalProperties":false}},"required":["type","vault","body"],"additionalProperties":false},"group":{"description":"C13: give the key to a group — a bare slug (one `group:` prefix is accepted as a spelling). Only a caller the group's roles allow (owner or admin, mayGiveForGroup, D26) may; anyone else is refused `not_allowed` and the opener is never called. The key is recorded under the group, on its members' walk, and payload.vault must be the group treasury's vault.","type":"string"}},"required":["signer","payload"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":false,"x-auth":"authenticated"},{"title":"secrets:grant","description":"Lend a key you gave to ONE, or accept one lent to you. LEND: a signed grant — who may use the key (a person, an agent, or a group), which calls (catalogue entries of the provider row), how many a day, until when — checked against the grant-signers of the vault the key was given under (never the vault the document names), and stored only once its signature verifies (an id is never reused on a vault). The borrower gets a card linking one.ie/keys?lent=<ref>; their calls run on the key once they accept, and they never see it. ACCEPT: `accept` names the grant's ref; `confirm: false` shows it in words and writes nothing, `confirm: true` records the acceptance. Only a person's own session accepts — for themselves, or with `group` / `agent` for a group or an agent they control — never an agent, and never from a body field. Closes with a mark on `actor → provider:<name>`, a warn on a refusal once the provider is known.","type":"object","properties":{"signer":{"description":"LEND form only.","type":"object","properties":{"kind":{"type":"string","enum":["person","agent"],"description":"person: a passkey touch on the seal page, in a window of its own (a framed grant is refused). agent: its own ed25519 Sui key (the SDK's grantData)."},"sig":{"type":"string","description":"The signature over the payload's canonical bytes (keys sorted, @oneie/sdk/secrets)."},"signer":{"type":"string","description":"Who signed: `p256:<point>` for a passkey, the agent's Sui address. It must be on the key's vault's grant-signers, read from the chain."}},"required":["kind","sig","signer"],"additionalProperties":false},"payload":{"description":"LEND form only.","type":"object","properties":{"type":{"type":"string","const":"grant"},"vault":{"type":"string","description":"The vault the key was given under, `0x` + 64 lower-case hex — the same as body.vault."},"body":{"type":"object","properties":{"id":{"type":"string","description":"8–64 of [A-Za-z0-9_-]; mint 16 random bytes as hex (grantData does). Never reused on a vault: a second grant naming a seen id is refused id_used, so a Stop is permanent."},"secret":{"type":"string","description":"`<vault>/<NAME>` — the key as it was given. A secret never given is refused no_key before anything reaches the chain."},"vault":{"type":"string"},"to":{"type":"object","properties":{"kind":{"type":"string","enum":["actor","group"]},"id":{"type":"string","description":"An actor id, or a group's bare slug (never `group:`-prefixed)."},"agents":{"description":"Only on a grant to a person: the agents of theirs it also covers. A grant to a person covers their agents only when it names them.","type":"array","items":{"type":"string"}}},"required":["kind","id"],"additionalProperties":false},"for":{"type":"object","properties":{"paths":{"description":"Catalogue entry ids of the key's provider row, bare or `<id>@/concrete/path` (one repo, one issue). Absent: the row's default reads. []: nothing. Any other item refuses bad_template.","type":"array","items":{"type":"string"}},"models":{"type":"array","items":{"type":"string"}},"tools":{"description":"Composio tool slugs — only on a key whose stored provider is composio, never a COMPOSIO_ meta-tool.","type":"array","items":{"type":"string"}}},"additionalProperties":false},"perDay":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Calls a day, counted before each call."},"until":{"type":"string","description":"ISO-8601 UTC ending Z, in the future. No upper cap: the provider's own budget is the honest one."}},"required":["id","secret","vault","to","for","perDay","until"],"additionalProperties":false}},"required":["type","vault","body"],"additionalProperties":false},"accept":{"description":"ACCEPT form: the grant's ref (from the card's link).","type":"string","pattern":"^[0-9a-f]{64}$"},"confirm":{"description":"ACCEPT form: false shows the grant in words and writes nothing; true records the acceptance (once).","type":"boolean"},"group":{"description":"ACCEPT form: accept for a group you control (owner or admin).","type":"string"},"agent":{"description":"ACCEPT form: accept for an agent whose home group you control. An agent never accepts for itself.","type":"string"}},"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"authenticated"},{"title":"secrets:revoke","description":"Stop a grant for good. The owner's signed Stop — checked against the grant-signers of the vault the lent key was given under — is stored once and never rewritten; the next call on that grant is refused `stopped`, and its meter does not move again. There is no un-stop: grant ids are never reused on a vault. Closes with a mark on `actor → provider:<name>`.","type":"object","properties":{"signer":{"type":"object","properties":{"kind":{"type":"string","enum":["person","agent"],"description":"person: a passkey touch on the seal page, in its own window. agent: its own ed25519 key (the SDK's stopData)."},"sig":{"type":"string"},"signer":{"type":"string","description":"`p256:<point>` for a passkey, the agent's Sui address — on the vault's grant-signers."}},"required":["kind","sig","signer"],"additionalProperties":false},"payload":{"type":"object","properties":{"type":{"type":"string","const":"stop"},"vault":{"type":"string","description":"The vault the grant was signed on."},"body":{"type":"object","properties":{"grantId":{"type":"string","description":"The grant's id on that vault."},"at":{"type":"string","description":"ISO-8601 UTC ending Z."}},"required":["grantId","at"],"additionalProperties":false}},"required":["type","vault","body"],"additionalProperties":false}},"required":["signer","payload"],"additionalProperties":false,"x-effect":"ask","x-cost":"free","x-reversible":false,"x-idempotent":true,"x-auth":"authenticated"},{"title":"ssr:calibrate","description":"Compare strategy PMFs against a human fixture, mark/warn paths, write hypothesis if KS-sim >= 0.85. FINDING: falls back to data.slug when the caller is unattested","type":"object","properties":{"concept":{},"human_pmf":{},"slug":{},"strategies":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"ssr:rate","description":"Project text onto a PMF using embedding, without LLM turn (test seam + re-rating)","type":"object","properties":{"skill_body":{},"text":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"public"},{"title":"storefront:balance","description":"Fetches the seller's account balance for the workspace","type":"object","properties":{"slug":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"owner"},{"title":"subscriptions:list","description":"Returns all subscriptions for the attested caller","type":"object","properties":{},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"subscriptions:presence","description":"Returns agents and workflows following a workspace's view tags","type":"object","properties":{"slug":{},"tags":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"member"},{"title":"subscriptions:unregister","description":"Removes a subscription or all subscriptions for the attested caller","type":"object","properties":{"receiver":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"view:preview","description":"Live-preview a view query without saving it, returning rows and metadata","type":"object","properties":{"query":{},"slug":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"member"},{"title":"workflow:resumed-notify","description":"Posts a short status line into the conversation when a delayed workflow resumes","type":"object","properties":{"group":{},"runId":{},"stepId":{},"stepName":{},"workflowName":{}},"additionalProperties":{},"x-effect":"signal","x-reversible":false,"x-auth":"session"},{"title":"world:create-client","description":"Provision a client workspace under a parent, with auth check on parentSlug","type":"object","properties":{"handle":{},"name":{},"parentSlug":{},"plan":{},"slug":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"owner"},{"title":"world:do-event","description":"Emit a do-event (build cycle phase) to a workspace's build inbox","type":"object","properties":{"axis":{},"composite":{},"cycle":{},"deliverable":{},"model":{},"shape":{},"slug":{},"success":{},"type":{},"wave":{},"worktags":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"session"},{"title":"world:set-favicon","description":"Fetch a favicon URL and store as workspace logo with SSRF guard, auth on slug","type":"object","properties":{"slug":{},"url":{},"workspace":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"owner"},{"title":"world:sync-subscriptions","description":"Backfill subscription records for all agents in a workspace's R2 content","type":"object","properties":{"workspace":{}},"additionalProperties":{},"x-effect":"ask","x-reversible":false,"x-auth":"owner"}]}
    # END generated:receivers
    # BEGIN generated:components — bun run codegen (do not edit by hand)
    GroupEntity:
      type: object
      properties:
        gid: {type: string}
        name: {type: string}
        "group-type": {type: string, enum: ["company", "community", "dao", "friends", "org", "personal", "team", "workspace", "world"]}
        brand: {type: string}
        scope: {type: string, enum: ["private", "group", "public"]}
        plan: {type: string}
        tag: {type: string}
      additionalProperties: true
    ActorEntity:
      type: object
      properties:
        aid: {type: string}
        name: {type: string}
        "actor-type": {type: string, enum: ["agent", "animal", "human", "world"]}
        model: {type: string}
        prompt: {type: string}
        tag: {type: string}
      additionalProperties: true
    ThingEntity:
      type: object
      properties:
        tid: {type: string}
        name: {type: string}
        "thing-type": {type: string, enum: ["plan", "service", "skill", "step", "task", "token"]}
        tag: {type: string}
        price: {type: number}
        "task-status": {type: string, enum: ["blocked", "dissolved", "done", "failed", "open", "picked", "verified"]}
        "step-kind": {type: string, enum: ["agent", "condition", "delay", "human", "sell", "skill", "tool", "trigger"]}
      additionalProperties: true
    PathEntity:
      type: object
      properties:
        strength: {type: number}
        resistance: {type: number}
        traversals: {type: integer}
        scope: {type: string, enum: ["private", "group", "public"]}
        "bridge-kind": {type: string}
      additionalProperties: true
    SignalEntity:
      type: object
      properties:
        payload: {type: string}
        data: {type: string}
        amount: {type: number}
        success: {type: boolean}
        latency: {type: number}
        ts: {type: string, format: date-time}
        scope: {type: string, enum: ["private", "group", "public"]}
      additionalProperties: true
    HypothesisEntity:
      type: object
      properties:
        hid: {type: string}
        statement: {type: string}
        "hypothesis-status": {type: string, enum: ["pending", "testing", "confirmed", "rejected"]}
        confidence: {type: number}
        scope: {type: string, enum: ["private", "group", "public"]}
        source: {type: string}
      additionalProperties: true
    # END generated:components
    Outcome:
      type: object
      required: [outcome, latencyMs]
      properties:
        outcome:
          type: string
          enum: [result, timeout, dissolved, failure]
          description: One of the four substrate outcomes.
        result:
          description: Present when outcome=result.
        reason:
          type: string
          description: Present when outcome=dissolved or failure.
        latencyMs:
          type: integer
          description: Round-trip time in milliseconds.

    SignalResponse:
      type: object
      required: [outcome, signalId]
      properties:
        outcome:
          type: string
          enum: [queued, dissolved]
        signalId:
          type: string
          format: ulid

    PathStrength:
      type: object
      required: [target, strength]
      properties:
        target:
          type: string
          nullable: true
        strength:
          type: number
          minimum: 0

    Error:
      type: object
      required: [type, title, status]
      properties:
        type:
          type: string
          format: uri
          description: Stable problem type URI.
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        traceId:
          type: string
          format: ulid

    Agent:
      type: object
      required: [id, title, description]
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        model:
          type: string
        skills:
          type: array
          items:
            $ref: "#/components/schemas/Skill"
        verified:
          type: boolean

    Skill:
      type: object
      required: [name, title]
      properties:
        name:
          type: string
        title:
          type: string
        description:
          type: string
        price:
          type: number

    Thread:
      type: object
      required: [id, slug, createdAt]
      properties:
        id:
          type: string
        slug:
          type: string
        agentId:
          type: string
        createdAt:
          type: integer
          description: Unix epoch ms.

    Group:
      type: object
      required: [id, kind]
      properties:
        id:
          type: string
        kind:
          type: string
          enum: [world, team, org]
        name:
          type: string

    Actor:
      type: object
      required: [id, type]
      properties:
        id:
          type: string
        type:
          type: string
          enum: [human, agent, world]
        name:
          type: string

    Thing:
      type: object
      required: [id, type]
      properties:
        id:
          type: string
        type:
          type: string
          enum: [skill, task, token]
        name:
          type: string

    Path:
      type: object
      required: [from, to, strength]
      properties:
        from:
          type: string
        to:
          type: string
        strength:
          type: number
        resistance:
          type: number
        traversals:
          type: integer

    Event:
      type: object
      required: [id, receiver, createdAt]
      properties:
        id:
          type: string
        receiver:
          type: string
        data:
          description: Arbitrary signal payload.
        createdAt:
          type: integer

    Hypothesis:
      type: object
      required: [id, claim, confidence]
      properties:
        id:
          type: string
        claim:
          type: string
        confidence:
          type: number
          minimum: 0
          maximum: 1
        status:
          type: string
          enum: [candidate, active, retired]


    # ── Feature-route schemas (hand-derived from src/pages/api/**) ───────────

    SkillCatalogEntry:
      type: object
      description: |
        One entry of the bundled skill catalogue, as projected by
        `loadCatalog()` in src/pages/api/skills.ts. NOT the same shape as
        `Skill` (which the Agent schema uses).
      required: [id, label]
      properties:
        id:
          type: string
          description: Directory name of the SKILL.md / skill.md that produced it.
        label:
          type: string
          description: Frontmatter `title`, else `labelFor(id)`.
        description:
          type: string
        tags:
          type: array
          items:
            type: string
        price:
          type: number
        category:
          type: string
          enum: [fleet, legacy]
        content:
          type: string
          description: Raw markdown — present only when `?expand=content`.

    SubmissionPack:
      type: object
      description: |
        The directory-submission payload frozen at run time
        (`buildSubmissionPack`, src/lib/directories/pack.ts).
      required: [fields, missing]
      properties:
        fields:
          type: object
          description: Directory field key → the value taken from the workspace profile.
          additionalProperties:
            type: string
        missing:
          type: array
          description: Directory fields the profile had no value for.
          items:
            type: object
            required: [key, label, type, required]
            properties:
              key:
                type: string
              label:
                type: string
              type:
                type: string
                enum: [text, textarea, url, email, phone, select]
              required:
                type: boolean

    DirectorySubmission:
      type: object
      required: [id, directorySlug, status]
      properties:
        id:
          type: string
          format: uuid
        directorySlug:
          type: string
          description: A `slug` from the DIRECTORIES registry (src/lib/directories/registry.ts).
        status:
          type: string
          enum: [queued, submitted, live, rejected]
        pack:
          description: Null when the stored pack column is empty.
          oneOf:
            - $ref: "#/components/schemas/SubmissionPack"
            - type: "null"
        listingUrl:
          type: [string, "null"]

    LifecycleStage:
      type: object
      required: [id, label, tag, slot, subSteps, enter_when, levers]
      properties:
        id:
          type: string
        label:
          type: string
        tag:
          type: string
          description: Namespaced tag — `lifecycle:<lifecycleId>:<stageId>`. Computed on read, never stored.
        slot:
          type: integer
        subSteps:
          type: array
          items:
            type: string
        enter_when:
          type: [string, "null"]
        levers:
          type: array
          items:
            type: object

    LifecycleTransition:
      type: object
      required: [source, target, kind]
      properties:
        source:
          type: string
        target:
          type: string
        kind:
          type: string
          description: Unknown values are COERCED to `forward` on read, never rejected.
        trigger:
          type: string
        sh:
          type: string
        th:
          type: string

    LifecycleDef:
      type: object
      description: A workspace's named lifecycle, as returned by `loadDef` (src/lib/lifecycle/def.ts).
      required: [id, name, version, stages, transitions, arcs, monotonic]
      properties:
        id:
          type: string
        name:
          type: string
        version:
          type: integer
        stages:
          type: array
          items:
            $ref: "#/components/schemas/LifecycleStage"
        transitions:
          type: array
          items:
            $ref: "#/components/schemas/LifecycleTransition"
        arcs:
          type: array
          items:
            type: object
            properties:
              row:
                type: integer
              label:
                type: string
        monotonic:
          type: boolean
          description: Forward-only when true; false permits loop re-entry.

    TagNamespace:
      type: object
      required: [id, workspace_id, namespace, values, colour, acl, locked, usage_count, created_at, updated_at]
      properties:
        id:
          type: string
          description: "`<workspace_id>:<namespace>`."
        workspace_id:
          type: string
        namespace:
          type: string
        values:
          type: array
          description: Empty array = freeform.
          items:
            type: string
        colour:
          type: string
        acl:
          type: object
          required: [read, write]
          properties:
            read:
              type: array
              items:
                type: string
            write:
              type: array
              items:
                type: string
        locked:
          type: boolean
        usage_count:
          type: integer
        created_at:
          type: integer
          description: Epoch milliseconds.
        updated_at:
          type: integer
          description: Epoch milliseconds.

    TagSuggestion:
      type: object
      required: [id, workspace_id, tag, usage_count, first_seen, last_seen, cluster_id, status]
      properties:
        id:
          type: string
        workspace_id:
          type: string
        tag:
          type: string
        usage_count:
          type: integer
        first_seen:
          type: integer
        last_seen:
          type: integer
        cluster_id:
          type: [string, "null"]
        status:
          type: string
          enum: [pending, promoted, dismissed]

    Theme:
      type: object
      description: A design-token theme row (src/lib/db/themes.ts).
      required: [id, owner_id, name, tokens, is_public, fork_of, created_at]
      properties:
        id:
          type: string
        owner_id:
          type: [string, "null"]
        name:
          type: string
        tokens:
          type: string
          description: Serialised token blob — an opaque string at this layer.
        is_public:
          type: integer
          enum: [0, 1]
        fork_of:
          type: [string, "null"]
        created_at:
          type: integer
          description: Epoch milliseconds.

  parameters:
    Idempotency:
      name: Idempotency-Key
      in: header
      required: false
      description: ULID — identical keys replay cached response.
      schema:
        type: string
        format: ulid

    TraceId:
      name: X-Trace-Id
      in: header
      required: false
      schema:
        type: string
        format: ulid

  responses:
    Problem:
      description: Problem+JSON error (RFC 9457).
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Error"

    WorkspaceAuthzError:
      description: |
        Refusal from `authorizeWorkspace` (src/lib/analytics/authz.ts). The same
        body appears under three statuses — `bad_slug` (400), `forbidden` (403)
        and `no_db` (503, D1 unreachable with no other check able to pass).
      content:
        application/json:
          schema:
            type: object
            required: [error]
            properties:
              error:
                type: string
                enum: [bad_slug, forbidden, no_db]

    SimpleError:
      description: "`{ error }` — the bare error body most feature routes return."
      content:
        application/json:
          schema:
            type: object
            required: [error]
            properties:
              error:
                type: string

    OkFalseError:
      description: |
        `{ ok: false, error }` — the `errJson` shape from
        src/lib/analytics/http.ts, used by every /api/lifecycle/* branch
        including its authorization refusals.
      content:
        application/json:
          schema:
            type: object
            required: [ok, error]
            properties:
              ok:
                type: boolean
                const: false
              error:
                type: string

    AuthErrorResponse:
      description: |
        `authErrorResponse(AuthError)` from src/lib/api-auth.ts —
        `{ error: "unauthorized", reason }`. Status carries the meaning:
        401 `no_session`, 402 `billing_over_limit` / `billing_suspended`,
        403 `ip_not_allowed` / `action_not_permitted`,
        503 `authority_undetermined` / `audit_write_failed`.
      content:
        application/json:
          schema:
            type: object
            required: [error, reason]
            properties:
              error:
                type: string
                const: unauthorized
              reason:
                type: string

paths:

  # ── Substrate verbs ────────────────────────────────────────────────────────

  /signal/{receiver}:
    post:
      operationId: signal
      summary: Route a signal
      x-substrate-verb: signal
      tags: [substrate]
      description: |
        Accepts the 5-mode addressing grammar:
        - `alice` — unit id
        - `alice:review` — unit:task
        - `world:review` — group:task
        - `all:review` — broadcast
        - `sub:news:crypto` — topic subscription
      parameters:
        - name: receiver
          in: path
          required: true
          schema:
            type: string
          description: Receiver address (any of the 5 modes).
        - $ref: "#/components/parameters/Idempotency"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: "#/components/schemas/ReceiverPayload"
      responses:
        "202":
          description: Signal accepted.
          headers:
            X-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignalResponse"
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"

  /ask/{receiver}:
    post:
      operationId: ask
      summary: Signal and await one of 4 outcomes
      x-substrate-verb: ask
      tags: [substrate]
      description: Always returns HTTP 200. Outcome lives in the response body.
      parameters:
        - name: receiver
          in: path
          required: true
          schema:
            type: string
        - name: timeout
          in: query
          required: false
          schema:
            type: integer
            default: 5000
            description: Max wait in milliseconds.
        - $ref: "#/components/parameters/Idempotency"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: "#/components/schemas/ReceiverPayload"
      responses:
        "200":
          description: One of the four outcomes.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Outcome"

  /mark/{edge}:
    post:
      operationId: mark
      summary: Strengthen a path
      x-substrate-verb: mark
      tags: [substrate]
      description: Writes strength to TypeDB + D1 mirror. Optional atomic payment.
      parameters:
        - name: edge
          in: path
          required: true
          schema:
            type: string
          description: Edge in `from→to` or `from:to` format.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                strength:
                  type: number
                  default: 1
                weight:
                  type: number
                  description: Payment weight (credits).
                currency:
                  type: string
                  enum: [USD, SUI, ETH, BTC]
      responses:
        "200":
          description: Path updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  strength:
                    type: number
        "400":
          $ref: "#/components/responses/Problem"

  /warn/{edge}:
    post:
      operationId: warn
      summary: Weaken a path
      x-substrate-verb: warn
      tags: [substrate]
      parameters:
        - name: edge
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                strength:
                  type: number
                  default: 1
      responses:
        "200":
          description: Resistance updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  resistance:
                    type: number

  /fade:
    post:
      operationId: fade
      summary: Decay all paths
      x-substrate-verb: fade
      tags: [substrate]
      description: SERVER_SECRET gated. Resistance fades 2x faster than strength.
      security:
        - serverSecret: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                rate:
                  type: number
                  default: 0.05
                  description: Decay rate 0–1.
      responses:
        "200":
          description: Paths decayed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  rate:
                    type: number
                  paths:
                    type: integer

  /follow:
    get:
      operationId: follow
      summary: Best deterministic path
      x-substrate-verb: follow
      tags: [substrate]
      parameters:
        - name: tag
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Best path or null.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PathStrength"

  /select:
    get:
      operationId: select
      summary: Best path (probabilistic)
      x-substrate-verb: select
      tags: [substrate]
      parameters:
        - name: tag
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Sampled path.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PathStrength"

  /sub:
    post:
      operationId: subscribe
      summary: Register a webhook subscription
      x-substrate-verb: signal
      tags: [substrate]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [topic, url]
              properties:
                topic:
                  type: string
                url:
                  type: string
                  format: uri
                secret:
                  type: string
                  description: Used for HMAC-SHA256 delivery signatures.
      responses:
        "200":
          description: Subscription created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  topic:
                    type: string
    delete:
      operationId: unsubscribe
      summary: Remove a webhook subscription
      x-substrate-verb: signal
      tags: [substrate]
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: string
        - name: topic
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Subscription removed.

  # ── Dimension reads ────────────────────────────────────────────────────────

  /groups:
    get:
      operationId: listGroups
      summary: List groups (worlds, teams, orgs)
      x-dimension: groups
      tags: [dimensions]
      parameters:
        - name: search
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: Paginated groups.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Group"
                  total:
                    type: integer

  /actors:
    get:
      operationId: listActors
      summary: List actors (humans, agents, worlds)
      x-dimension: actors
      tags: [dimensions]
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum: [human, agent, world]
        - name: search
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: Paginated actors.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Actor"
                  total:
                    type: integer

  /things:
    get:
      operationId: listThings
      summary: List things (skills, tasks, tokens)
      x-dimension: things
      tags: [dimensions]
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum: [skill, task, token]
        - name: search
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: Paginated things.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Thing"
                  total:
                    type: integer

  /paths:
    get:
      operationId: listPaths
      summary: List paths (highways + strength/resistance)
      x-dimension: paths
      tags: [dimensions]
      parameters:
        - name: from
          in: query
          schema:
            type: string
        - name: to
          in: query
          schema:
            type: string
        - name: min_strength
          in: query
          schema:
            type: number
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: Paths matching filters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Path"

  /events:
    get:
      operationId: listEvents
      summary: List signal events
      x-dimension: events
      tags: [dimensions]
      parameters:
        - name: receiver
          in: query
          schema:
            type: string
        - name: since
          in: query
          schema:
            type: integer
            description: Unix epoch ms — events after this timestamp.
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        "200":
          description: Event list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Event"

  /learning:
    get:
      operationId: listLearning
      summary: List hypotheses (ordered by confidence)
      x-dimension: learning
      tags: [dimensions]
      parameters:
        - name: search
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum: [candidate, active, retired]
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: Hypotheses.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Hypothesis"

  # ── Chat ──────────────────────────────────────────────────────────────────

  /api/chat:
    post:
      operationId: chat
      summary: Streaming chat completion
      tags: [chat]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [messages]
              properties:
                messages:
                  type: array
                  items:
                    type: object
                agentId:
                  type: string
                threadId:
                  type: string
      responses:
        "200":
          description: AI SDK data stream.
          headers:
            Content-Type:
              schema:
                type: string
                enum: ["text/event-stream"]
        "402":
          description: Insufficient credits.
          $ref: "#/components/responses/Problem"
        "403":
          description: Public chat disabled or rate limited.
          $ref: "#/components/responses/Problem"

  # ── Agents ────────────────────────────────────────────────────────────────

  /api/agents:
    get:
      operationId: listAgents
      summary: List agents for the current workspace
      tags: [agents]
      responses:
        "200":
          description: Agent list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  agents:
                    type: array
                    items:
                      $ref: "#/components/schemas/Agent"

  /api/agents/publish:
    post:
      operationId: publishAgent
      summary: Publish an agent markdown file to R2
      tags: [agents]
      description: |
        Validates markdown against the Zod schema, scans for XSS, checks publish limits
        per billing tier (free=5, starter=20, pro=100, agency=unlimited), and stores to R2.
        Returns 402 with `upgrade` URL when limit reached.
      security:
        - sessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id, content]
              properties:
                id:
                  type: string
                  pattern: "^[a-z0-9][a-z0-9-]*$"
                content:
                  type: string
                  description: Raw agent markdown.
      responses:
        "200":
          description: Published.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  version:
                    type: string
                    format: ulid
        "400":
          $ref: "#/components/responses/Problem"
        "402":
          description: Publish limit reached for billing tier.
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"

  /api/agents/history:
    get:
      operationId: agentHistory
      summary: Version history for an agent
      tags: [agents]
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: History entries.
          content:
            application/json:
              schema:
                type: object
                properties:
                  versions:
                    type: array
                    items:
                      type: object
                      properties:
                        version:
                          type: string
                        createdAt:
                          type: integer

  /api/agents/rollback:
    post:
      operationId: rollbackAgent
      summary: Restore a previous version of an agent
      tags: [agents]
      security:
        - sessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id, version]
              properties:
                id:
                  type: string
                version:
                  type: string
                  format: ulid
      responses:
        "200":
          description: Restored.

  /api/agents/{id}:
    get:
      operationId: getAgent
      summary: Get agent metadata
      tags: [agents]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Agent metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Agent"
        "404":
          $ref: "#/components/responses/Problem"
    delete:
      operationId: deleteAgent
      summary: Delete an agent
      tags: [agents]
      security:
        - sessionCookie: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Deleted.
        "401":
          $ref: "#/components/responses/Problem"

  # ── Skills ────────────────────────────────────────────────────────────────

  /api/skills:
    get:
      operationId: listSkills
      summary: List the bundled skill catalogue
      description: |
        Public — no authentication and no workspace scope. Returns the two
        bundled sources (`ai/skills/*/SKILL.md` and `web/ai/skills/*/skill.md`)
        projected and de-duplicated by id, sorted by label. Cached in KV for
        300s per `q`+`expand` variant.
      tags: [skills]
      parameters:
        - name: q
          in: query
          description: Case-insensitive substring filter over id, label, description and tags.
          schema:
            type: string
        - name: expand
          in: query
          description: "`content` to include each skill's raw markdown in `content`."
          schema:
            type: string
            enum: [content]
      responses:
        "200":
          description: Skill catalogue.
          content:
            application/json:
              schema:
                type: object
                required: [ok, skills, total]
                properties:
                  ok:
                    type: boolean
                    const: true
                  skills:
                    type: array
                    items:
                      $ref: "#/components/schemas/SkillCatalogEntry"
                  total:
                    type: integer
                    description: Size of the UNFILTERED catalogue — not the length of `skills`.

  /api/skills/{name}:
    delete:
      operationId: deleteSkill
      summary: Remove a skill
      tags: [skills]
      security:
        - sessionCookie: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Removed.
        "404":
          $ref: "#/components/responses/Problem"

  /api/skills/{name}/enable:
    post:
      operationId: enableSkill
      summary: Enable or disable a skill for the workspace
      tags: [skills]
      security:
        - sessionCookie: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [enabled]
              properties:
                enabled:
                  type: boolean
      responses:
        "200":
          description: Updated.

  # ── Threads ───────────────────────────────────────────────────────────────

  /api/threads/{tid}:
    get:
      operationId: getThread
      summary: Get thread metadata and messages
      tags: [threads]
      security:
        - sessionCookie: []
      parameters:
        - name: tid
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Thread.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Thread"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"

  /api/threads/{tid}/share:
    post:
      operationId: shareThread
      summary: Create a read-only share link for a thread
      tags: [threads]
      security:
        - sessionCookie: []
      parameters:
        - name: tid
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Share URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri

  /api/threads/{tid}/export:
    get:
      operationId: exportThread
      summary: Export thread as JSON
      tags: [threads]
      security:
        - sessionCookie: []
      parameters:
        - name: tid
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Thread JSON export.
          headers:
            Content-Disposition:
              schema:
                type: string

  /api/threads/{tid}/pdf:
    get:
      operationId: exportThreadPdf
      summary: Export thread as print-ready HTML
      tags: [threads]
      security:
        - sessionCookie: []
      parameters:
        - name: tid
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Print-ready HTML for download.
          headers:
            Content-Disposition:
              schema:
                type: string

  # ── Platform ──────────────────────────────────────────────────────────────

  /api/health:
    get:
      operationId: health
      summary: Health check
      description: Public — no authentication. Reports the configured default agent.
      tags: [platform]
      responses:
        "200":
          description: Service healthy.
          content:
            application/json:
              schema:
                type: object
                required: [status, agent, model, hasOpenRouter]
                properties:
                  status:
                    type: string
                    const: ok
                  agent:
                    type: string
                    description: Default agent id (`loadAgent(env).id`).
                  model:
                    type: string
                  hasOpenRouter:
                    type: boolean
                    description: Whether OPENROUTER_API_KEY is bound. Never the key itself.

  /api/abuse/report:
    post:
      operationId: reportAbuse
      summary: Report a message for moderation review
      description: |
        Unauthenticated; rate-limited to 3 reports per IP per hour. The report is
        written to KV for platform admin review with a 30-day TTL. Every field is
        optional and truncated server-side — `reason` to 100 chars (defaulting to
        `other`), `agentId` to 64, `threadUrl` to 256.
      tags: [platform]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                agentId:
                  type: string
                threadUrl:
                  type: string
      responses:
        "200":
          description: Report queued.
          content:
            application/json:
              schema:
                type: object
                required: [ok]
                properties:
                  ok:
                    type: boolean
                    const: true
        "400":
          description: 'Body was not valid JSON — `{ "error": "Invalid JSON" }`.'
          $ref: "#/components/responses/SimpleError"
        "429":
          description: Rate limit — max 3 reports per hour per IP.
          $ref: "#/components/responses/SimpleError"
        "500":
          description: Unexpected error; `error` carries the message.
          $ref: "#/components/responses/SimpleError"

  /api/admin/agents/freeze:
    post:
      operationId: freezeAgent
      summary: Freeze an agent (admin only)
      tags: [platform]
      description: Frozen agents block new publishes and return 451 in chat. UNDELETE-friendly — R2 content preserved.
      security:
        - serverSecret: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id, reason]
              properties:
                id:
                  type: string
                reason:
                  type: string
                slug:
                  type: string
      responses:
        "200":
          description: Frozen.
        "401":
          $ref: "#/components/responses/Problem"

  # ── Directories — business-directory submission runs ───────────────────────
  #
  # Every branch below is derived from src/pages/api/directories/{run,update}.ts.
  # Both routes read the D1 binding first (503 `no_db`), then run
  # `authorizeWorkspace(locals, slug, DB, env)` — a session-cookie walk, so a
  # bearer world key is NOT accepted here.

  /api/directories/run:
    post:
      operationId: startDirectoryRun
      summary: Start a submission run across N directories
      description: |
        Inserts one `queued` row per named directory under a fresh `runId`, each
        carrying a submission pack FROZEN at run time — a later registry edit
        cannot retroactively change what was filed.
      tags: [directories]
      security:
        - sessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [slug, directories]
              properties:
                slug:
                  type: string
                  description: Workspace slug. Must pass the authority walk for the caller.
                directories:
                  type: array
                  minItems: 1
                  description: Directory slugs from the DIRECTORIES registry.
                  items:
                    type: string
      responses:
        "200":
          description: Run started.
          content:
            application/json:
              schema:
                type: object
                required: [runId, count]
                properties:
                  runId:
                    type: string
                    format: uuid
                  count:
                    type: integer
                    description: Number of rows inserted — equals `directories.length`.
        "400":
          description: |
            One of three, in the order the route checks them — `bad_slug` (the
            slug failed the charset guard), `directories required` (empty list),
            or `unknown_directory`, which additionally carries `unknown` listing
            the slugs absent from the registry.
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
                    enum: [bad_slug, "directories required", unknown_directory]
                  unknown:
                    type: array
                    description: Present only on `unknown_directory`.
                    items:
                      type: string
        "403":
          $ref: "#/components/responses/WorkspaceAuthzError"
        "503":
          $ref: "#/components/responses/WorkspaceAuthzError"
    get:
      operationId: getDirectoryRun
      summary: Read one run's per-directory status
      tags: [directories]
      security:
        - sessionCookie: []
      parameters:
        - name: slug
          in: query
          required: true
          schema:
            type: string
        - name: runId
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: |
            The run's rows. An unknown `runId` is NOT an error — it returns an
            empty `submissions` array.
          content:
            application/json:
              schema:
                type: object
                required: [submissions]
                properties:
                  submissions:
                    type: array
                    items:
                      $ref: "#/components/schemas/DirectorySubmission"
        "400":
          description: "`bad_slug`, or `runId required` when the query param is absent."
          $ref: "#/components/responses/SimpleError"
        "403":
          $ref: "#/components/responses/WorkspaceAuthzError"
        "503":
          $ref: "#/components/responses/WorkspaceAuthzError"

  /api/directories/update:
    post:
      operationId: updateDirectorySubmission
      summary: Walk one submission row to its next status
      description: |
        The status walk is data, not branching — `ALLOWED_TRANSITIONS` in
        src/pages/api/directories/update.ts permits `queued → submitted`,
        `submitted → live` and `submitted → rejected`. `live` and `rejected` are
        terminal: any transition out of them is refused. `filedBy` is recorded
        only on the move to `submitted` (defaulting to `human`); `listingUrl` and
        `note` are COALESCEd, so omitting one preserves the stored value.
      tags: [directories]
      security:
        - sessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [slug, id, status]
              properties:
                slug:
                  type: string
                id:
                  type: string
                  description: The `directory_submissions` row id. Scoped to `slug` — a row in another workspace reads as 404.
                status:
                  type: string
                  enum: [submitted, live, rejected]
                listingUrl:
                  type: string
                  description: REQUIRED when `status` is `live`.
                note:
                  type: string
                filedBy:
                  type: string
                  description: Recorded only when `status` is `submitted`. Defaults to `human`.
      responses:
        "200":
          description: Row updated.
          content:
            application/json:
              schema:
                type: object
                required: [ok]
                properties:
                  ok:
                    type: boolean
                    const: true
        "400":
          description: |
            `bad_slug`; `id and status required`; `invalid_transition` (which
            carries `from` and `to`); or `listingUrl required to mark live`.
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
                    enum: [bad_slug, "id and status required", invalid_transition, "listingUrl required to mark live"]
                  from:
                    type: string
                    description: Present only on `invalid_transition` — the row's current status.
                  to:
                    type: string
                    description: Present only on `invalid_transition` — the status that was refused.
        "403":
          $ref: "#/components/responses/WorkspaceAuthzError"
        "404":
          description: 'No row with that id in that workspace — `{ "error": "not found" }`.'
          $ref: "#/components/responses/SimpleError"
        "503":
          $ref: "#/components/responses/WorkspaceAuthzError"

  # ── Lifecycle ──────────────────────────────────────────────────────────────
  #
  # Every response on these three routes — successes AND authorization refusals —
  # uses the `errJson`/`json` pair from src/lib/analytics/http.ts, so an error is
  # `{ ok: false, error }`, not a bare `{ error }`.

  /api/lifecycle/counts:
    get:
      operationId: lifecycleCounts
      summary: Per-stage occupancy for one named lifecycle
      description: |
        `count` is current occupancy (the back-compat key); `reached` is
        cumulative funnel reach. A workspace with no such lifecycle gets
        `counts: {}` at 200 — an empty board is a different fact from a refusal.
      tags: [lifecycle]
      security:
        - sessionCookie: []
      parameters:
        - name: slug
          in: query
          required: true
          schema:
            type: string
        - name: lifecycle
          in: query
          description: Lifecycle id. Defaults to `default`.
          schema:
            type: string
            default: default
      responses:
        "200":
          description: Stage counts keyed by stage id.
          content:
            application/json:
              schema:
                type: object
                required: [ok, lifecycle, counts]
                properties:
                  ok:
                    type: boolean
                    const: true
                  lifecycle:
                    type: string
                  counts:
                    type: object
                    additionalProperties:
                      type: object
                      required: [count, reached]
                      properties:
                        count:
                          type: integer
                        reached:
                          type: integer
        "400":
          description: "`missing slug`, or `bad_slug` from the authority walk."
          $ref: "#/components/responses/OkFalseError"
        "403":
          description: "`forbidden`."
          $ref: "#/components/responses/OkFalseError"
        "503":
          description: "`no_db`."
          $ref: "#/components/responses/OkFalseError"

  /api/lifecycle/defs:
    get:
      operationId: lifecycleDefs
      summary: Every lifecycle in a workspace, with live stage occupancy
      description: |
        The read `/u/<slug>/lifecycles` does server-side, exposed for client
        islands. A workspace with no lifecycles gets `[]` at 200.
      tags: [lifecycle]
      security:
        - sessionCookie: []
      parameters:
        - name: slug
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Lifecycles with per-stage counts.
          content:
            application/json:
              schema:
                type: object
                required: [ok, lifecycles]
                properties:
                  ok:
                    type: boolean
                    const: true
                  lifecycles:
                    type: array
                    items:
                      type: object
                      required: [id, name, stages]
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        stages:
                          type: array
                          items:
                            type: object
                            required: [id, label, slot, count, reached]
                            properties:
                              id:
                                type: string
                              label:
                                type: string
                              slot:
                                type: integer
                              count:
                                type: integer
                              reached:
                                type: integer
        "400":
          description: "`missing slug`, or `bad_slug`."
          $ref: "#/components/responses/OkFalseError"
        "403":
          description: "`forbidden`."
          $ref: "#/components/responses/OkFalseError"
        "503":
          description: "`no_db`."
          $ref: "#/components/responses/OkFalseError"

  /api/lifecycle/def:
    get:
      operationId: getLifecycleDef
      summary: Read one lifecycle definition
      tags: [lifecycle]
      security:
        - sessionCookie: []
      parameters:
        - name: slug
          in: query
          required: true
          schema:
            type: string
        - name: lifecycle
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The definition.
          content:
            application/json:
              schema:
                type: object
                required: [ok, def]
                properties:
                  ok:
                    type: boolean
                    const: true
                  def:
                    $ref: "#/components/schemas/LifecycleDef"
        "400":
          description: "`missing_params` (either query param absent), or `bad_slug`."
          $ref: "#/components/responses/OkFalseError"
        "403":
          description: "`forbidden`."
          $ref: "#/components/responses/OkFalseError"
        "404":
          description: "`not_found` — no such lifecycle in that workspace."
          $ref: "#/components/responses/OkFalseError"
        "503":
          description: "`no_db`."
          $ref: "#/components/responses/OkFalseError"
    post:
      operationId: saveLifecycleDef
      summary: Upsert a lifecycle definition
      description: |
        Gated by `requireAuthOver(request, 'manage_lifecycle', slug)` — a session
        cookie OR a bearer key, unlike the GET on this same path which uses the
        `authorizeWorkspace` session walk. The target workspace comes from the
        QUERY STRING, never the body. `saveDef` bumps `version` on every write.
        The per-workspace definition cap is checked only when the id is new.
      tags: [lifecycle]
      security:
        - sessionCookie: []
        - bearerKey: []
      parameters:
        - name: slug
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LifecycleDef"
      responses:
        "201":
          description: Saved. `def` is re-read from D1 after the write.
          content:
            application/json:
              schema:
                type: object
                required: [ok, def]
                properties:
                  ok:
                    type: boolean
                    const: true
                  def:
                    oneOf:
                      - $ref: "#/components/schemas/LifecycleDef"
                      - type: "null"
        "400":
          description: "`missing_slug`, or `invalid_def` when `id` is not a string or `stages` is not an array."
          $ref: "#/components/responses/OkFalseError"
        "401":
          $ref: "#/components/responses/AuthErrorResponse"
        "402":
          $ref: "#/components/responses/AuthErrorResponse"
        "403":
          $ref: "#/components/responses/AuthErrorResponse"
        "422":
          description: Workspace is at or above the definition cap; `error` carries the refusal reason.
          $ref: "#/components/responses/OkFalseError"
        "503":
          description: "`no_db` (OkFalseError shape), or an authority/audit failure (AuthErrorResponse shape)."
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    required: [ok, error]
                    properties:
                      ok:
                        type: boolean
                        const: false
                      error:
                        type: string
                        const: no_db
                  - type: object
                    required: [error, reason]
                    properties:
                      error:
                        type: string
                        const: unauthorized
                      reason:
                        type: string
    delete:
      operationId: deleteLifecycleDef
      summary: Remove a lifecycle definition and its stages
      description: |
        `manage_lifecycle`-gated. The `stage_transition` log is deliberately left
        intact — it is the immutable audit, not the design.
      tags: [lifecycle]
      security:
        - sessionCookie: []
        - bearerKey: []
      parameters:
        - name: slug
          in: query
          required: true
          schema:
            type: string
        - name: lifecycle
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: 'Removed. Idempotent — deleting an absent definition also returns `{ ok: true }`.'
          content:
            application/json:
              schema:
                type: object
                required: [ok]
                properties:
                  ok:
                    type: boolean
                    const: true
        "400":
          description: "`missing_params`."
          $ref: "#/components/responses/OkFalseError"
        "401":
          $ref: "#/components/responses/AuthErrorResponse"
        "402":
          $ref: "#/components/responses/AuthErrorResponse"
        "403":
          $ref: "#/components/responses/AuthErrorResponse"
        "503":
          description: "`no_db` (OkFalseError shape), or an authority/audit failure (AuthErrorResponse shape)."
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    required: [ok, error]
                    properties:
                      ok:
                        type: boolean
                        const: false
                      error:
                        type: string
                        const: no_db
                  - type: object
                    required: [error, reason]
                    properties:
                      error:
                        type: string
                        const: unauthorized
                      reason:
                        type: string

  # ── Themes ─────────────────────────────────────────────────────────────────
  #
  # These four routes authenticate with their OWN bearer scheme (`checkAuth` in
  # each file), not the session cookie: `Bearer <SERVER_SECRET>` resolves to the
  # owner id `server`, and `Bearer <ownerId>:<SERVER_SECRET>` acts as that owner.
  # Every route answers 503 `not configured` when DB or SERVER_SECRET is unbound.

  /api/themes:
    get:
      operationId: listThemes
      summary: List public themes, plus the caller's own
      description: |
        The bearer token is OPTIONAL here. Without one, `mine` is `[]` and only
        the public community themes are returned; there is no 401 on this route.
      tags: [themes]
      security:
        - themeBearer: []
        - {}
      responses:
        "200":
          description: Themes.
          content:
            application/json:
              schema:
                type: object
                required: [mine, community]
                properties:
                  mine:
                    type: array
                    description: Empty when the caller presents no valid bearer token.
                    items:
                      $ref: "#/components/schemas/Theme"
                  community:
                    type: array
                    description: Themes with `is_public = 1`.
                    items:
                      $ref: "#/components/schemas/Theme"
        "503":
          description: 'DB or SERVER_SECRET unbound — `{ "error": "not configured" }`.'
          $ref: "#/components/responses/SimpleError"

  /api/themes/{id}:
    get:
      operationId: getTheme
      summary: Read one theme
      description: Unauthenticated — any theme is readable by id, public or not.
      tags: [themes]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The theme.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Theme"
        "400":
          description: "`id required`."
          $ref: "#/components/responses/SimpleError"
        "404":
          description: "`not found`."
          $ref: "#/components/responses/SimpleError"
        "503":
          description: "`not configured`."
          $ref: "#/components/responses/SimpleError"
    patch:
      operationId: patchTheme
      summary: Replace a theme's tokens
      description: |
        `tokens` is the only writable field and the zod body schema accepts
        nothing else. NOTE: the update is not owner-scoped — any valid bearer
        token may patch any theme by id.
      tags: [themes]
      security:
        - themeBearer: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [tokens]
              properties:
                tokens:
                  type: string
      responses:
        "200":
          description: The theme, re-read after the write.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Theme"
        "400":
          description: "`id required`, or `invalid body` when `tokens` is absent or not a string."
          $ref: "#/components/responses/SimpleError"
        "401":
          description: "`unauthorized` — no bearer token, or one that did not match SERVER_SECRET."
          $ref: "#/components/responses/SimpleError"
        "404":
          description: "`not found`."
          $ref: "#/components/responses/SimpleError"
        "503":
          description: "`not configured`."
          $ref: "#/components/responses/SimpleError"

  /api/themes/{id}/fork:
    post:
      operationId: forkTheme
      summary: Copy a theme into the caller's ownership
      description: |
        No request body. The new row takes the caller's owner id — `server` for a
        bare `Bearer <SERVER_SECRET>`, else the `<ownerId>` prefix of the token.
      tags: [themes]
      security:
        - themeBearer: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "201":
          description: The new theme.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Theme"
        "400":
          description: "`id required`."
          $ref: "#/components/responses/SimpleError"
        "401":
          description: "`unauthorized`."
          $ref: "#/components/responses/SimpleError"
        "404":
          description: "`not found` — the source theme does not exist."
          $ref: "#/components/responses/SimpleError"
        "503":
          description: "`not configured`."
          $ref: "#/components/responses/SimpleError"

  /api/themes/{id}/share:
    post:
      operationId: shareTheme
      summary: Publish a theme to the community list
      description: |
        Sets `is_public = 1`, and unlike PATCH this write IS owner-scoped — the
        UPDATE is bound to `owner_id = <caller>`.
      tags: [themes]
      security:
        - themeBearer: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Published.
          content:
            application/json:
              schema:
                type: object
                required: [ok, shareUrl]
                properties:
                  ok:
                    type: boolean
                    const: true
                  shareUrl:
                    type: string
                    description: "`/design?theme=<id>`."
        "400":
          description: "`id required`."
          $ref: "#/components/responses/SimpleError"
        "401":
          description: "`unauthorized`."
          $ref: "#/components/responses/SimpleError"
        "404":
          description: "`not found`, or `not found or not owner` when the owner-scoped UPDATE did not apply."
          $ref: "#/components/responses/SimpleError"
        "503":
          description: "`not configured`."
          $ref: "#/components/responses/SimpleError"

  # ── CRM ────────────────────────────────────────────────────────────────────
  #
  # All three are session-cookie reads gated by `authorizeWorkspace`. Note the
  # error string differs from the directories group: these answer `db_unavailable`
  # at 503 when the D1 binding is missing, before the authority walk runs.

  /api/crm/combo-context:
    get:
      operationId: crmComboContext
      summary: Prospect context for a tag combination
      description: |
        Reads the shared combo KV entry (the same key `/api/brain/combos` writes)
        and marks the path on a hit. On a miss it resolves from BrainDO plus D1
        and writes the entry back with a strength-derived TTL — so a 200 is
        returned either way and `hit` is always `true`.
      tags: [crm]
      security:
        - sessionCookie: []
      parameters:
        - name: tags
          in: query
          required: true
          description: Comma-separated. Lower-cased and trimmed; at most 8.
          schema:
            type: string
        - name: workspace
          in: query
          description: Defaults to the caller's own slug.
          schema:
            type: string
      responses:
        "200":
          description: Combo context.
          content:
            application/json:
              schema:
                type: object
                required: [tags, strength, primaryStage, suggestedAction, lastThread, recentThreads, matchedWorkflows, cachedAt, hit]
                properties:
                  tags:
                    type: array
                    items:
                      type: string
                  strength:
                    type: number
                  primaryStage:
                    type: [string, "null"]
                  suggestedAction:
                    description: The top matched workflow, or null.
                    oneOf:
                      - type: object
                        properties:
                          id:
                            type: string
                          name:
                            type: string
                          tags:
                            type: array
                            items:
                              type: string
                      - type: "null"
                  lastThread:
                    oneOf:
                      - type: object
                        properties:
                          id:
                            type: string
                          lastMsgAt:
                            type: integer
                      - type: "null"
                  recentThreads:
                    type: array
                    maxItems: 3
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        lastMsgAt:
                          type: integer
                  matchedWorkflows:
                    type: array
                    maxItems: 3
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        tags:
                          type: array
                          items:
                            type: string
                  cachedAt:
                    type: integer
                    description: Epoch seconds.
                  hit:
                    type: boolean
                    const: true
        "400":
          description: |
            `bad_slug` from the authority walk, or a tag validation refusal —
            `no_tags`, `max_8_tags`, or `invalid_tag:<tag>` naming the offender.
          $ref: "#/components/responses/SimpleError"
        "403":
          $ref: "#/components/responses/WorkspaceAuthzError"
        "503":
          description: "`db_unavailable` — the D1 binding is absent."
          $ref: "#/components/responses/SimpleError"

  /api/crm/starters:
    get:
      operationId: crmStarters
      summary: Hottest tag combos as conversation openers
      description: |
        Scans at most 200 `combo:<workspace>:` KV keys, keeps combos at a sales
        lifecycle stage (`consideration`, `decision`, `purchase`, `upsell`,
        `win-back`) OR with strength above 50, and returns the top N by strength.
        With no KV binding it answers `{ "starters": [] }` — and that body omits
        `workspace`.
      tags: [crm]
      security:
        - sessionCookie: []
      parameters:
        - name: workspace
          in: query
          description: Defaults to the caller's own slug.
          schema:
            type: string
        - name: limit
          in: query
          description: Clamped to 20.
          schema:
            type: integer
            default: 5
            maximum: 20
      responses:
        "200":
          description: Ranked openers.
          content:
            application/json:
              schema:
                type: object
                required: [starters]
                properties:
                  starters:
                    type: array
                    items:
                      type: object
                      required: [tags, strength, lifecycles, suggestedOpener, workflows, recentThreads]
                      properties:
                        tags:
                          type: array
                          items:
                            type: string
                        strength:
                          type: number
                        lifecycles:
                          type: array
                          items:
                            type: string
                        suggestedOpener:
                          type: string
                          description: Template text chosen by lifecycle stage. Not model-generated.
                        workflows:
                          type: array
                          maxItems: 2
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                              tags:
                                type: array
                                items:
                                  type: string
                        recentThreads:
                          type: array
                          maxItems: 2
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              lastMsgAt:
                                type: integer
                  workspace:
                    type: string
                    description: Absent when the KV binding is missing.
        "400":
          description: "`bad_slug`."
          $ref: "#/components/responses/WorkspaceAuthzError"
        "403":
          $ref: "#/components/responses/WorkspaceAuthzError"
        "503":
          description: "`db_unavailable`."
          $ref: "#/components/responses/SimpleError"

  /api/crm/hot-accounts:
    get:
      operationId: crmHotAccounts
      summary: Recently active accounts (JSON snapshot or SSE stream)
      description: |
        Dual-mode. With `?live=1` or `Accept: text/event-stream` it returns an SSE
        stream emitting an `accounts` event immediately and every 15s until the
        client aborts; otherwise one JSON snapshot with `Cache-Control: private,
        max-age=30`.

        CAVEAT, and it is load-bearing for a client: the payload is currently
        HARD-CODED sample data (`sampleAccounts()` in
        src/pages/api/crm/hot-accounts.ts) — three fixed accounts with
        `whenMs` offsets from now. The shape is real; the rows are not.
      tags: [crm]
      security:
        - sessionCookie: []
      parameters:
        - name: slug
          in: query
          description: Defaults to the caller's workspace context.
          schema:
            type: string
        - name: live
          in: query
          description: "`1` forces the SSE stream."
          schema:
            type: string
            enum: ["1"]
      responses:
        "200":
          description: A JSON snapshot, or an SSE stream of `accounts` events.
          content:
            application/json:
              schema:
                type: object
                required: [accounts, freshnessMs]
                properties:
                  accounts:
                    type: array
                    items:
                      type: object
                      required: [id, name, sentence, whenMs, spark]
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        sentence:
                          type: string
                        whenMs:
                          type: integer
                        spark:
                          type: array
                          items:
                            type: number
                  freshnessMs:
                    type: integer
            text/event-stream:
              schema:
                type: string
                description: "`event: accounts` frames whose `data` is the JSON body above."
        "400":
          description: "`slug required` when no slug can be resolved, or `bad_slug`."
          $ref: "#/components/responses/SimpleError"
        "403":
          $ref: "#/components/responses/WorkspaceAuthzError"
        "503":
          $ref: "#/components/responses/WorkspaceAuthzError"

  # ── Tags ───────────────────────────────────────────────────────────────────
  #
  # Two things a client must know before generating against this group:
  #   • a missing D1 binding answers 500 here, NOT 503 as elsewhere in the spec;
  #   • DELETE runs no `authorizeWorkspace` walk — it is guarded only by the
  #     namespace's own `locked` flag.
  # PUT /api/tags is deliberately UNDOCUMENTED: it validates and echoes back but
  # persists nothing and performs no authority walk.

  /api/tags:
    get:
      operationId: listTagNamespaces
      summary: List a workspace's tag namespaces
      tags: [tags]
      security:
        - sessionCookie: []
      parameters:
        - name: workspace
          in: query
          description: Falls back to `locals.workspaceId`, then the literal `default`.
          schema:
            type: string
      responses:
        "200":
          description: Namespaces, plus the framework namespaces no tenant may redefine.
          content:
            application/json:
              schema:
                type: object
                required: [namespaces, locked]
                properties:
                  namespaces:
                    type: array
                    items:
                      $ref: "#/components/schemas/TagNamespace"
                  locked:
                    type: array
                    description: "`lifecycle`, `iab`, `gdpr`, `ccpa`, `status`, `sla`."
                    items:
                      type: string
        "400":
          description: "`bad_slug`."
          $ref: "#/components/responses/WorkspaceAuthzError"
        "403":
          $ref: "#/components/responses/WorkspaceAuthzError"
        "500":
          description: "`no_db` — note the status, which is 500 on this route and not 503."
          $ref: "#/components/responses/SimpleError"
    post:
      operationId: createTagNamespace
      summary: Create a tag namespace
      description: |
        The insert is `ON CONFLICT DO NOTHING`, so re-posting an existing
        namespace returns it unchanged at 200 rather than erroring.
      tags: [tags]
      security:
        - sessionCookie: []
      parameters:
        - name: workspace
          in: query
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: "`namespace` is the field; `ns` is accepted as an alias."
              properties:
                namespace:
                  type: string
                ns:
                  type: string
                values:
                  type: array
                  description: Omit or send `[]` for a freeform namespace.
                  items:
                    type: string
                colour:
                  type: string
                  default: neutral
                acl:
                  type: object
                  description: "Defaults to `{ read: [\"*\"], write: [\"owner\", \"agency\"] }`."
                  required: [read, write]
                  properties:
                    read:
                      type: array
                      items:
                        type: string
                    write:
                      type: array
                      items:
                        type: string
      responses:
        "200":
          description: The namespace.
          content:
            application/json:
              schema:
                type: object
                required: [namespace]
                properties:
                  namespace:
                    $ref: "#/components/schemas/TagNamespace"
        "400":
          description: "`namespace required`, or `bad_slug`."
          $ref: "#/components/responses/SimpleError"
        "403":
          description: |
            `forbidden` from the authority walk, or `locked` with the offending
            `namespace` echoed back when the name is a framework namespace.
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
                    enum: [forbidden, locked]
                  namespace:
                    type: string
        "409":
          description: |
            `createNamespace` returned null, so the row could not be read back
            after the insert. The body is `{ "namespace": null }` — there is no
            `error` key on this branch. BELIEVED UNREACHABLE in practice: the
            only other way that function returns null is a locked namespace, and
            the route 403s those before it is called. Do not build a retry path
            on this branch without reproducing it first.
          content:
            application/json:
              schema:
                type: object
                required: [namespace]
                properties:
                  namespace:
                    type: "null"
        "500":
          description: "`no_db`."
          $ref: "#/components/responses/SimpleError"
    delete:
      operationId: deleteTagNamespace
      summary: Delete a tag namespace
      description: |
        NO workspace authority walk runs on this method — the only guard is the
        namespace's stored `locked` flag. The id embeds the workspace, so a
        caller must already know it.
      tags: [tags]
      parameters:
        - name: id
          in: query
          required: true
          description: "`<workspace>:<namespace>`."
          schema:
            type: string
      responses:
        "200":
          description: Deleted.
          content:
            application/json:
              schema:
                type: object
                required: [ok]
                properties:
                  ok:
                    type: boolean
                    const: true
        "400":
          description: "`id required`."
          $ref: "#/components/responses/SimpleError"
        "403":
          description: |
            The namespace is locked, or there is no row with that id — both
            answer `{ "ok": false }` at 403, with no `error` key.
          content:
            application/json:
              schema:
                type: object
                required: [ok]
                properties:
                  ok:
                    type: boolean
                    const: false
        "500":
          description: "`no_db`."
          $ref: "#/components/responses/SimpleError"

  /api/tags/suggest:
    get:
      operationId: listTagSuggestions
      summary: Ad-hoc tags above a usage threshold
      description: Returns at most 100 `pending` suggestions, hottest first.
      tags: [tags]
      security:
        - sessionCookie: []
      parameters:
        - name: workspace
          in: query
          description: Defaults to the literal `default`.
          schema:
            type: string
        - name: threshold
          in: query
          description: Minimum `usage_count`.
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: Suggestions.
          content:
            application/json:
              schema:
                type: object
                required: [suggestions, threshold]
                properties:
                  suggestions:
                    type: array
                    maxItems: 100
                    items:
                      $ref: "#/components/schemas/TagSuggestion"
                  threshold:
                    type: number
        "400":
          description: "`bad_slug`."
          $ref: "#/components/responses/WorkspaceAuthzError"
        "403":
          $ref: "#/components/responses/WorkspaceAuthzError"
        "500":
          description: "`no_db`."
          $ref: "#/components/responses/SimpleError"
    post:
      operationId: recordTagSuggestion
      summary: Record one sighting of an ad-hoc tag
      description: |
        Upsert keyed on `<workspace>:<tag>` — a repeat sighting increments
        `usage_count` and moves `last_seen` rather than inserting a second row.
      tags: [tags]
      security:
        - sessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [workspace, tag]
              properties:
                workspace:
                  type: string
                tag:
                  type: string
                cluster_id:
                  type: string
      responses:
        "200":
          description: Recorded.
          content:
            application/json:
              schema:
                type: object
                required: [ok]
                properties:
                  ok:
                    type: boolean
                    const: true
        "400":
          description: "`workspace + tag required`, or `bad_slug`."
          $ref: "#/components/responses/SimpleError"
        "403":
          $ref: "#/components/responses/WorkspaceAuthzError"
        "500":
          description: "`no_db`."
          $ref: "#/components/responses/SimpleError"

  # ── Leads ──────────────────────────────────────────────────────────────────

  /api/leads:
    post:
      operationId: captureLead
      summary: Capture an inbound lead
      description: |
        PUBLIC — no authentication and no workspace scope. The row is keyed on
        the lower-cased email, so re-posting the same address updates rather than
        duplicating: `visitor_hash` is kept if already set, and `persona`, `team`
        and `attrs` are overwritten only when the new payload supplies them.
        Every optional string is truncated server-side (`visitor_hash` 64,
        `persona` 32, `team` 32, `source` 64).
      tags: [leads]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                  format: email
                  maxLength: 254
                visitor_hash:
                  type: string
                persona:
                  type: string
                team:
                  type: string
                source:
                  type: string
                  default: home-chat
                attrs:
                  type: object
                  additionalProperties: true
      responses:
        "200":
          description: Captured.
          content:
            application/json:
              schema:
                type: object
                required: [ok, lead_id]
                properties:
                  ok:
                    type: boolean
                    const: true
                  lead_id:
                    type: string
                    description: "`lead_` + the email slugified to `[a-z0-9-]`, truncated to 64."
        "400":
          description: "`bad_json`, or `invalid_email` when the address fails the regex or exceeds 254 chars."
          $ref: "#/components/responses/SimpleError"
        "503":
          description: "`no_db`."
          $ref: "#/components/responses/SimpleError"

  # ── Notifications ──────────────────────────────────────────────────────────
  #
  # Both methods run `requireAuth(request, 'read_memory')` FIRST — so a failure
  # there answers `{ error: "unauthorized", reason }` — and only then the
  # `authorizeWorkspace` walk, which answers the bare `{ error }` shape.

  /api/notifications:
    get:
      operationId: listNotifications
      summary: Read the workspace notification feed
      description: |
        Returns the 50 most recent rows, newest first, as a BARE ARRAY — not an
        object wrapper. The one exception is `?type=substrate`, which is a
        declared placeholder: it always answers
        `{ "notifications": [], "source": "substrate" }` and never reads D1.
      tags: [notifications]
      security:
        - sessionCookie: []
        - bearerKey: []
      parameters:
        - name: slug
          in: query
          description: Defaults to the authenticated principal's slug.
          schema:
            type: string
        - name: type
          in: query
          description: "`substrate` selects the placeholder branch described above."
          schema:
            type: string
            enum: [substrate]
      responses:
        "200":
          description: The feed, or the substrate placeholder.
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    maxItems: 50
                    items:
                      type: object
                      required: [id, kind, payload, ts, read]
                      properties:
                        id:
                          type: string
                        kind:
                          type: string
                        payload:
                          type: [string, "null"]
                          description: Serialised JSON, or null. Not parsed by the route.
                        ts:
                          type: integer
                        read:
                          type: integer
                          enum: [0, 1]
                  - type: object
                    required: [notifications, source]
                    properties:
                      notifications:
                        type: array
                        items:
                          type: object
                      source:
                        type: string
                        const: substrate
        "401":
          $ref: "#/components/responses/AuthErrorResponse"
        "402":
          $ref: "#/components/responses/AuthErrorResponse"
        "403":
          description: |
            `authErrorResponse` shape when `requireAuth` refuses; the bare
            `{ error: "forbidden" }` shape when the workspace walk refuses.
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    required: [error, reason]
                    properties:
                      error:
                        type: string
                        const: unauthorized
                      reason:
                        type: string
                  - type: object
                    required: [error]
                    properties:
                      error:
                        type: string
                        enum: [bad_slug, forbidden]
        "503":
          description: |
            The D1 binding is unbound — the body is the PLAIN TEXT
            `not configured`, not JSON. An authority failure from `requireAuth`
            also lands here as JSON.
          content:
            text/plain:
              schema:
                type: string
                const: not configured
            application/json:
              schema:
                type: object
                required: [error, reason]
                properties:
                  error:
                    type: string
                    const: unauthorized
                  reason:
                    type: string
    post:
      operationId: markNotificationsRead
      summary: Mark one notification, or all of them, as read
      description: |
        `?action=mark-read` is the only action implemented. With `id` it marks
        that row; without `id` it marks every row for the slug. Any other
        `action` (or none) is a NO-OP that still answers `{ ok: true }`.
      tags: [notifications]
      security:
        - sessionCookie: []
        - bearerKey: []
      parameters:
        - name: action
          in: query
          schema:
            type: string
            enum: [mark-read]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                slug:
                  type: string
                  description: Defaults to the authenticated principal's slug.
                id:
                  type: string
                  description: Omit to mark every notification for the slug.
      responses:
        "200":
          description: Applied — or accepted as a no-op when `action` is not `mark-read`.
          content:
            application/json:
              schema:
                type: object
                required: [ok]
                properties:
                  ok:
                    type: boolean
                    const: true
        "400":
          description: Body was not valid JSON — the PLAIN TEXT `invalid json`, not JSON.
          content:
            text/plain:
              schema:
                type: string
                const: invalid json
        "401":
          $ref: "#/components/responses/AuthErrorResponse"
        "402":
          $ref: "#/components/responses/AuthErrorResponse"
        "403":
          description: |
            `authErrorResponse` shape when `requireAuth` refuses; the bare
            `{ error }` shape when the workspace walk refuses.
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    required: [error, reason]
                    properties:
                      error:
                        type: string
                        const: unauthorized
                      reason:
                        type: string
                  - type: object
                    required: [error]
                    properties:
                      error:
                        type: string
                        enum: [bad_slug, forbidden]
        "503":
          description: The PLAIN TEXT `not configured`, or an authority failure as JSON.
          content:
            text/plain:
              schema:
                type: string
                const: not configured
            application/json:
              schema:
                type: object
                required: [error, reason]
                properties:
                  error:
                    type: string
                    const: unauthorized
                  reason:
                    type: string