openapi/capabilities.yaml

# capabilities.yaml — the ONE editorial decision left in this repo.
#
# NOT a registry of what exists. hanzoai/cloud decides that, by registering a
# route; `hanzo.yaml` reports it. This file answers the one question the document
# does not: which DOMAIN a capability belongs under when a reader is shown the
# whole API at once. That is presentation, and presentation has no source in the
# code — a doc site's movements are a taste decision about a reader, not a fact
# about a router.
#
# It is curation over the document, and curation is gated BOTH ways by
# publish.py:
#
#   • a capability the document carries and this file does not group FAILS the
#     publish. A new product is a name somebody has to place, and letting one
#     default into a bucket is how 235 tags once ended up ungrouped while the
#     doc site rendered four.
#   • a name grouped here that the document does NOT carry FAILS too. Nothing
#     serves it, so nothing can be filed under it — and a name that outlives its
#     routes is exactly the drift this repo was rebuilt to make impossible.
#
# So the list below cannot describe an API other than the one that is served. It
# can only be a worse or better arrangement of the one that is.
#
# `tags:` are the tags OPERATIONS CARRY in cloud's emission — the product, which
# is the first path segment after /v1/, or the owning Go package where a route
# has no /v1 prefix. They are not directory names. There are no directories.


domains:
  - id: identity
    title: "Identity & Trust"
    role: "who you are · what you may touch · where secrets live"
    # `trust` is the outward half of what this domain already holds: audit,
    # compliance and risk are what an organization keeps, and the trust centre
    # is what it PUBLISHES of them — controls, framework coverage, policies,
    # subprocessors, and the evidence rows standing behind each control. Same
    # facts, read by a reviewer instead of an owner, so it files beside them
    # rather than under a documents or marketing heading.
    tags: [iam, authz, kms, security, team, audit, compliance, risk,
           validator, wallet, entitlement, account, dataset, label,
           reference, trust]

  - id: intelligence
    title: "Intelligence"
    role: "models · agents · evaluation — the mind of the cloud"
    # The bare-/v1 inference surface — /v1/chat/completions, /v1/models,
    # /v1/embeddings — is Hanzo AI's OpenAI- and Anthropic-compatible face,
    # where the PATH is the compatibility contract because every vendor SDK
    # hard-codes it. Those routes tag themselves `ai`: one product serves them,
    # so one name carries them, and the paths stay exactly where the SDKs
    # expect. The hand-declared long tail that used to sit beside them is gone,
    # which is what apps/ai projecting its mounted registry was always going to
    # do to it.
    tags: [ai, agents, ml, eval, benchmark, prompt, exec, sandbox, tools,
           ask, code, engine, translate, lsp]

  - id: data
    title: "Data"
    role: "the stores every capability writes to and reads from"
    # `taxonomy` is the classification the console reads to arrange products —
    # a stored vocabulary that other capabilities look terms up in, which is
    # the same shape as `catalog` and not a surface of its own.
    # `graph` is that argument at full size: assertions about entities, a
    # vocabulary naming the relations in use, and a rule that says which of two
    # disagreeing assertions is in force. It answers what is true as of an
    # instant, which is a store being read, not a product being used.
    tags: [s3, base, kv, search, index, catalog, taxonomy, sync, crawl,
           websearch, provisioning, knowledge, graph]

  - id: streams
    title: "Streams"
    role: "messaging · durable tasks · async orchestration"
    # `tel` is the carrier leg of the delivery `notify` already names: notify is
    # "transactional email and SMS, sent through your org's own provider
    # credential", and tel holds the numbers that SMS leaves from and the calls
    # that share the carrier with it. It files here rather than under
    # Applications because a call is a message reaching a person over somebody
    # else's network, not a surface of its own.
    # `integrations` files here for the same reason and now says so plainly: it
    # absorbed `connectors`, so one name covers the provider registry, the
    # caller's own connections, the custody of each connector's secret and the
    # token rotation that keeps it live. What it does is carry data between this
    # cloud and another one, which is `destination` and `webhook`'s family.
    tags: [tasks, pubsub, mq, notify, tel, auto, flow, webhook, event,
           channels, destination, integrations]

  - id: observability
    title: "Observability"
    role: "see everything — telemetry · analytics · usage"
    tags: [o11y, metrics, usage, openapi, leaderboard]

  - id: commerce
    title: "Commerce"
    role: "the economy — meter · price · bill · reward"
    tags: [commerce, marketplace, billing, pricing, books, captable, crm,
           referral, affiliate, author, licensing, x402, marketing,
           campaign, ad, experiment, treasury, plan, allowance]

  - id: platform
    title: "Platform"
    role: "the cloud fabric — deploy · provision · route · host"
    # `node` is a machine of yours that dials in and holds the socket open, so
    # you can ask it to run a command and get the answer back. That makes it
    # fabric — the same domain as the rest of what runs work — and not
    # Intelligence's `exec` or `sandbox`, which run code on machines that are
    # OURS. Whose hardware it is decides which of the two a caller wants.
    tags: [platform, deploy, projects, registry, gateway, ingress, dns,
           domain, cloudflare, network, flags, visor, node]

  - id: applications
    title: "Applications"
    role: "the user-facing surfaces built on all of the above"
    # `todo` is a list a person keeps — a surface, which is what this domain
    # is for. It is NOT streams' `tasks`: that one is the durable async queue
    # work is handed to. Two words, two things, and the only thing they share
    # is the English.
    # `standing` reports what keeping an entity in good standing costs each
    # year, itemised. The subject is the entity, not the money, which is why it
    # sits beside `company` and `legal` rather than under Commerce — that
    # domain is for money this cloud moves, and this is a bill somebody else
    # sends you.
    tags: [git, template, blueprint, bot, world, todo, framework, content,
           guide, help, meet, share, social, esign, dataroom, company,
           legal, pref, settings, functions, sbom, link, seo, standing]

  - id: chain
    title: "Chain"
    role: "the networks the cloud speaks to — enumerate · call · read balances"
    # One product, and it used to read as three: `chains` listed the networks,
    # `rpc` made the call, `tokens` read a holder's balance. All three are now
    # /v1/web3/* and tag themselves `web3`, which is the same three things said
    # once. `explorer` is the other half — what has already been read off a
    # chain and kept: how far each indexer has caught up, and what the on-chain
    # oracles report. They are not Platform, which is the fabric this cloud RUNS
    # on, and a chain is something it TALKS TO.
    tags: [web3, explorer]