openapi/LLM.md

# openapi

**This repo does not decide what the Hanzo API is. It publishes what the API
says about itself.**

`hanzo.yaml` is OUTPUT. It is derived, by `publish.py`, from hanzo-inc/cloud's own
emitted `openapi.yaml` at one pinned release. To change the API you change the
code in hanzo-inc/cloud; there is nothing here to edit that would make a route
exist, and nothing here that can describe one that does not.

```
hanzo-inc/cloud  typed ops + handler doc comments
     │           (projected per app, woven, gated by regenerate-and-diff)
     ▼
  openapi.yaml @ a release   ── the ONE authority on what exists
     │
     ▼  publish.py            ── six codegen rules; no new operations, no new prose
  hanzo.yaml + CAPABILITIES.md + .spec-lock   ── this repo's whole output
     │
     ├─→ generate.py → python · typescript · java · kotlin · rust · go · ruby · php
     ├─→ skills.py   → /.well-known/agent-skills/  (hanzo · lux · zoo)
     └─→ the doc site, hanzoai/console's proxy-allow test, hanzoai/world
```

## The one command

```bash
python3 publish.py                   # re-pin to hanzo-inc/cloud's main, derive, write
python3 publish.py --ref v1.801.383  # re-pin to one release
python3 publish.py --check           # THE GATE: re-derive at the pinned ref and diff
python3 publish.py --current         # has cloud's document moved past the pin?
```

It reads a hanzo-inc/cloud checkout (`--cloud`, `CLOUD_DIR`, default `../cloud`)
and writes exactly three files: `hanzo.yaml`, `CAPABILITIES.md`, `.spec-lock`.
Nothing is ever written back to hanzo-inc/cloud — the traffic is one-way by
construction, this repo reads a ref.

## What was here before, and what it measured out to

52 hand-authored `<service>/openapi.yaml` specs, merged with cloud's document
laid on top. Measured at `hanzo-inc/[email protected]`, both documents loaded and
keyed by (METHOD, path):

| | |
|---|---:|
| the hand-merged master | **2093** operations |
| cloud's emitted document | **2333** |
| shared | **1908** |
| **master-only — nothing cloud serves under that name** | **185** |
| **cloud-only — served, and the master never mentioned it** | **425** |

Both halves are the same bug. The master described 8% of an API that does not
exist and missed 18% of the one that does, and it was the input to seven SDKs,
the doc site, the MCP tool catalogue and the agent-skills plane.

### The 185, triaged — with a nonsense-sibling control on every probe

Each was probed at `api.hanzo.ai` with **its own method** (a POST-only route
answers 404 to GET, so a GET sweep cannot tell "absent" from "wrong verb"), and
each probe carries a CONTROL: the same address with `-zzq9` appended to its last
literal segment. 119 are addresses no live route pattern covers; 66 sit under a
`{wildcardN}` relay route, which by construction answers identically for a real
path and an invented one and therefore decides nothing.

| verdict | n | reading |
|---|---:|---|
| **ABSENT** — real 404, control 404 | **36** | refuted. Nothing serves this. |
| **UNFALSIFIABLE** — real ≠ 404, control identical | **44** | a gate or a relay answered, not a route |
| **SERVED** — real ≠ 404, control 404 | **39** | live, and cloud's document lacks it |
| absorbed by a `{wildcardN}` relay | 66 | unfalsifiable by construction |

**A 404 on both sides IS a refutation, and it is the only way absence can ever be
shown.** The control exists to stop a 401/403/200 being read as existence — a
relay answers those for anything. It does not make 404 mean nothing; treating it
that way makes absence unprovable by construction, which would be a rule about
falsifiability that is itself unfalsifiable. `hanzoai/cli`'s drift gate settled
this from the other side: 404 refutes, 403 does not.

The 36 refuted: 8 `search` (Meilisearch's `dumps`, `export`, `keys`,
`multi-search`, `network`, `snapshots`, `swap-indexes`, `webhooks`), 6 `s3`
(`PUT /v1/s3/{bucket}` and its five `?policy`-style subresources), 12 `o11y`
(`api/v2/{healthz,livez,readyz}`, `ingestion`, `vm/query`, `vm/query_range`, and
six methods of an authored `{wildcard1}`), 3 `kv` (`batch`, `clusters`,
`namespaces`), 3 `billing` (`gpu-charge`, `gpu-eligibility`, `payment-methods`),
`POST /v1/admin/promos`, `GET /v1/edge/nodes`, `GET /v1/models/{model}`.

The 44 unfalsifiable are almost all one thing. `apps/product` installs
`requireKey` middleware on the `/v1/search` and `/v1/vector` subtrees, so every
address under those prefixes 401s BEFORE routing — real and invented alike —
while cloud registers exactly four routes under each (`/indexes`, `/stats`;
`/collections`, `/stats`). The master's 40 `search` and 15 `vector` operations
were verbatim copies of Meilisearch's and Qdrant's own APIs, describing an
upstream this fleet proxies nothing to. Decided by SOURCE rather than by probe,
they are absent too.

**The 39 SERVED are the honest cost, and every one is a hanzo-inc/cloud defect** —
itemised under "Handed to hanzo-inc/cloud". None is fixable here: authoring them
back would restore exactly the property this change removes.

### Fourteen more that were not even the right API

`account.yaml`, `auth.yaml`, `checkout.yaml`, `collection.yaml`, `coupon.yaml`,
`form.yaml`, `order.yaml`, `product.yaml`, `referrer.yaml`, `site.yaml`,
`store.yaml`, `transaction.yaml`, `user.yaml`, `variant.yaml` — **Swagger 2.0**
documents for `host: api.hanzo.io`, read by nothing in this repo or the fleet.
`api.hanzo.io` is a parked domain today: HTTPS presents no certificate for the
name (`tlsv1 unrecognized name`), and over HTTP `/account`, `/store` and the
control `/account-zzq9` all return the same registrar lander HTML. Deleted.

## `publish.py` — the six rules, and why each exists

A projection may not add an operation, may not remove one that is served, and may
not invent prose. It may only make the one document generatable. The measurement
that says the projection is needed at all:

```
openapi-generator-cli 7.14.0 validate -i <cloud openapi.yaml>  → [error] Spec has 1012 errors
                              generate -g typescript-axios     → SpecValidationException, 0 files
same, against hanzo.yaml                                       → 0 errors; api.ts written
```

| # | rule | n | the failure it prevents |
|---|---|---:|---|
| 1 | drop TRACE | 26 | the JVM generator writes `RequestMethod.TRACE` beside an enum that stops at PUT, so no Java or Kotlin client compiles. They are wildcard relays projecting every method their router matches — a fact about the router, not a client surface, and one every edge disables anyway. |
| 2 | drop `compat`-tagged ops | 23 | the SERVING binary declares that tag for a legacy address it keeps reachable. Dropping it respects the declaration: the served surface is unchanged, and the published one says each thing once instead of shipping two spellings of one operation. |
| 3 | two tags → the first | 23 | a generator emits one class per tag, so a two-tag operation is emitted twice under one identifier (`ApiPricingGetFullPricingRequest redeclared`). |
| 4 | no tag → `x-app`, else the `/v1/<product>` segment | 42 | untagged is not ungrouped, it is `DefaultApi`. |
| 5 | no `responses` → a `default` that says so | 986 | **the 1012.** A `default` with no content states exactly what is known: the route answers, and its shape is not declared at the source. Inventing a schema is the one thing this must not do. |
| 6 | operationIds unique under `genid`, original kept as `x-id` | 1 | unique as STRINGS is what OpenAPI asks and it is not enough — every generator strips punctuation and camel-cases, so `deleteSession` and `DeleteSession` become one name and the client declares one request type twice. |

Rule 6 is the one rule that CHANGES a value rather than dropping or adding one,
and an operationId is not only a codegen identifier — it is the **wire name of an
MCP tool**. `DELETE /v1/o11y/sessions` is published as `DeleteSession_2` and
served as `DeleteSession`, and the suffix went out verbatim in the tool catalogue
of three client distributions, naming a tool `POST /v1/mcp` answers to no such
name. So the rename now records what it renamed: `x-id` is the id hanzo-inc/cloud
emitted, written only where the two differ, and `tools.py`'s `wire()` is the one
place a tool takes its name. Measured against the live MCP server: 1299/1323 before,
1300/1323 after. The collision itself belongs upstream — two operations whose ids
differ only in case are one name to every generator there is.

There was a seventh, and it is gone, which is what the end state looks like when
it arrives one rule at a time. Cloud's emission used to declare **no security
scheme**, so a client generated from it sent no `Authorization` header and every
call 401'd; `publish.py` added `bearerAuth` and a document-level `security`.
Cloud declares both halves itself now — `bearer`, with the header spellings it
accepts — and the addition stopped adding and started **corrupting**: the
`setdefault` no longer fired while the requirement it wrote still did, so the
published document required a scheme it did not define. Measured on the
generated typescript: 2498 bearer call sites from cloud's document, 0 from the
projection, leaving 191 files importing a credential helper none of them called.
`test_a_client_can_authenticate` now asserts the pair agrees, whoever supplies
it.

**Every one of these belongs upstream.** The day cloud's emitter writes the
`default` and tags its own untagged routes, `publish.py` shrinks to nothing and
`hanzo.yaml` becomes a byte copy — or this repo becomes unnecessary. That is the
intended end state, and rule 5 alone is 90% of what is left.

### Three versions, three meanings, and they must not be collapsed

- the **API's** version is `/v1`, in the path, immutable;
- the **emitting release** is `info.x-spec.ref` (and `.spec-lock`), and the rule
  for choosing it is not "the newest": it is the newest release `api.hanzo.ai`
  fully answers for, which `--served` decides. Cloud's `main` runs ahead of the
  deployment — measured at 108 commits and 60 published-but-unserved operations —
  so pinning there would publish 60 dead endpoints to every SDK, doc page and
  agent skill;
- `info.version` is **8.0.0**, the generation of this PUBLICATION, and it is what
  every SDK's package version is cut from (`sdks.yaml`'s rust row pins
  `packageVersion` to it). It may only move forward: putting the cloud ref there
  would publish `1.801.383` over an `8.x` npm package and be rejected as a
  downgrade.

## `capabilities.yaml` — the one editorial decision left here

The document says which product owns an operation. It does not say which DOMAIN
a product belongs to when a reader is shown the whole API at once, and there is
no source in the code for that — a doc site's movements are a taste decision
about a reader. So `capabilities.yaml` groups the document's tags into nine
domains, and `publish.py` gates it BOTH ways: a served capability it does not
group fails the publish, and a name it groups that the document does not carry
fails too. The list cannot describe an API other than the one served; it can only
be a better or worse arrangement of it.

`internal`, `collapsed`, `pending`, `review` and `derived` are gone with the spec
dirs they were about. A capability appears the release it starts being served and
leaves the release it stops.

## The gates

| gate | question | needs | where |
|---|---|---|---|
| **`publish.py --served`** | **is every published operation one `api.hanzo.ai` answers for?** | **nothing** | **`hanzo.yml` `test:`, every build** |
| `test_publish.py` | does the committed artifact hold the six rules, offline? | nothing | same |
| `test_flows.py` | does every operationId `flows.yaml` names still exist? | nothing | same |
| `test_skills.py` | is the skills surface deterministic and well-formed? | nothing | same |
| `publish.py --check` | is `hanzo.yaml` what its own pinned input projects to? | a hanzo-inc/cloud checkout | `spec sync`, every push and PR |
| `publish.py --current` | has cloud's document moved past the pin? | same | same workflow, hourly clock only |
| `skills.py --check` | did `dist/` drift from the document? | nothing | on demand |
| `generate.py --check` | did a committed client drift from the document? | nothing | each SDK repo's own CI |

**The `needs` column is the whole lesson, and it was learned the expensive way.**
`--check` is the better question and it was the only one gating this artifact, so
when it turned out it could not run, nothing did. Twice, for two different
reasons, and the second one wore the first one's clothes.

FIRST, NOBODY COLLECTED IT. Both callers had been moved to `.hanzo/workflows`,
which only git.hanzo.ai collects, and at the time nothing on git.hanzo.ai
collected a push to this repo: it answered `ls-remote` and refused `push` with
*mirror repository is read-only*, pulling from github rather than receiving from
anyone, so `gh workflow list` returned nothing at all. That is fixed —
git.hanzo.ai is where this repo lives now, and `.hanzo/workflows` is where its
callers run.

SECOND, IT ASKED THE WRONG REPOSITORY. `SPEC_REPO` said `hanzoai/cloud`, and
that name now belongs to the re-rooted OSS core: twelve commits on `main`, no
shared ancestor with the product, no `openapi.yaml` anywhere in it. Being
public, the checkout SUCCEEDED and the failure arrived a step later as
publish.py's `no remote of .cloud carries openapi.yaml on 'main'` — which the
workflow discarded and replaced with a fixed sentence saying `hanzo.yaml` had
been hand-edited. It had not been: re-derived at its own pinned ref, the
committed artifact was byte-for-byte what that ref projects to. **A step that
overwrites a precise diagnosis with a canned one sends every reader hunting for
a diff that does not exist**, and it is why neither `::error::` wrapper exists
any more: publish.py says what is wrong, and `set -e` fails the step.

THE CREDENTIAL IS STILL THE OPEN ONE. hanzo-inc/cloud is private and in another
org, and the per-job token Hanzo Git mints reads the run's OWN repository and
anything public — nothing else. Measured on hanzoai/python-sdk run 91449, which
named the right repo and still took `curl: (22) ... 404` on the raw read. So
`spec sync` takes `HANZO_GIT_TOKEN`, the one name in this fleet for a credential
that reads git.hanzo.ai, and says which credential is missing rather than
letting `actions/checkout` report a private repo as "repository not found". It
is not sealed yet, and until it is, `--check` runs by hand and `served` holds
the line.

Measured while none of it ran: the pin was **81 hanzo-inc/cloud commits stale**,
`hanzo.yaml` carried a **hand edit** (a route deleted straight out of a generated
file), `--check` exited 1, `--current` exited 1, and `test_publish.py` failed —
three red gates on `main`, none of them running anywhere. The published document
advertised **19 operations nothing serves**, including `POST /v1/admin/credits`,
a money mint hanzo-inc/cloud had deleted.

`--served` is deliberately the WEAKER question, because it needs nothing: cloud
serves its own emission unauthenticated at `/v1/openapi.json`, so the running
deployment refutes a published route by itself. It runs in `hanzo.yml`'s `test:`
block — the one lane both hanzoai/ci and platform.hanzo.ai read — and it is now
the gate holding the line. Same shape and same rule as hanzo.ai's
`scripts/audit-catalog.mjs`, which gates the same document: one direction only,
and never fail on an unreachable API.

`--current` is on the clock and not on pushes deliberately: a stale pin is not a
broken artifact, and failing an unrelated PR for it trains people to ignore red.

### Which remote is cloud's main — discovered, never named

`--current` asked `origin/main` for two years, and `origin` is not a fact about a
checkout, only the name a clone happened to use. hanzo-inc/cloud answers on several
remotes and they are NOT one lineage: where `origin` is the GitHub OSS mirror,
`origin/main` holds no `openapi.yaml` at its root at all, so the question went to
a repository that does not carry the document and could only die or agree by
accident. It died, quietly, and the pin drifted 24 releases while nothing went
red. **A gate that cannot fail is not a gate**, and that is the whole reason
`--current` now resolves the remote instead of assuming it: fetch every remote,
keep those whose `main` holds the document, take the one that contains the
others. On a normal clone that is `origin`; on this fleet's checkouts it is
whichever remote points at git.hanzo.ai, and neither is written down anywhere.
The same resolution is the default when re-pinning, so `python3 publish.py` with
no `--ref` can no longer publish from the wrong lineage either.

### The known weakness of `--served`, stated rather than discovered

It ASKS THE NETWORK IN CI, and `hanzoai/cli`'s `driftgate` — the same gate for
the same document, one repo over — argues against exactly that: *"a gate that
needs the network in CI gets switched off, and a switched-off gate is worse than
none."* Its answer is to decomplect the two halves: `--refresh` asks and writes
`spec/live.json` (evidence, checked in), and the default RULES over that
evidence with no network at all.

That is the stronger shape and this is not it. `--served` never FAILS on an
unreachable API — no network, no verdict, exit 0, said loudly — which trades
driftgate's problem for a quieter one: an outage does not turn the build red, it
turns the gate OFF for that run, and nothing distinguishes a passing build from
an unasked one except the word NO VERDICT in the log.

It is the right trade HERE, for a reason that is about this repo rather than
about gates: the evidence driftgate commits would be a second derived copy of
the served path set, in the repo whose entire defect was keeping a second copy
of the API by hand. `hanzo.ai/scripts/audit-catalog.mjs` gates this same
document the same way for the same reason. If an outage is ever measured to have
hidden a real drift, take driftgate's shape — the ask and the rule are already
separate functions here (`refuted()` fetches; the caller decides).

## Who reads this repo

| consumer | reads | can it name an unserved route? |
|---|---|---|
| `hanzoai/{python,js}-sdk` | `hanzo.yaml` via `generate.py`, unless a `.spec-lock` names a release — then cloud's own document | no |
| `hanzo-go/sdk` | `hanzo.yaml` via its own `scripts/generate.sh` | no |
| `hanzo-rs/sdk` | `hanzo-inc/cloud@ref:openapi.yaml` directly, from git.hanzo.ai — it passes `--skip-validate-spec` and `cargo build` is the real gate | no |
| `hanzo-inc/cloud` agent-skills | `hanzo.yaml` via `skills.py` | no |
| `hanzoai/console` proxy-allow test | `hanzo.yaml` | no |
| `hanzoai/world` cloud-pulse | `hanzo.yaml` | no |
| the doc site | `hanzo-inc/cloud@ref:openapi.yaml` directly, from git.hanzo.ai | no |
| `hanzoai/cli` | `hanzo-inc/cloud@ref:openapi.yaml` directly — it needs raw existence, not codegen | no |

**The doc site left this document, and the reason generalises.** The six rules
make a document GENERATABLE; a doc page needs none of them, because it reads
paths, tags, summaries and schemas, every one of which cloud emits itself. So the
projection bought the reference nothing and cost it currency — its pin sat 19
cloud releases back, rendering four relay products with twelve operations
each where the document has one, one, one and two. A consumer belongs here only
while it needs what `publish.py` adds. Codegen does; prose does not.

**Reading the document is a git.hanzo.ai operation now.** `generate.py`'s
`fetch()` asked api.github.com, which mirrors hanzo-inc/cloud thousands of
commits behind and does not serve openapi.yaml at all, so it could only 404 —
and it reported that 404 as a missing credential, which sent readers hunting for
a token to fix a host with no file on it. One host, one credential:
`git.hanzo.ai/v1` and `HANZO_GIT_TOKEN`, the same name hanzoai/ci's client lane
hands its own read.
A fallback chain across hosts holding different documents is not a fallback, it
is a coin flip about which document you get.

**The skills plane is why "no" has to be structural.** `skills.py` emits a
`SKILL.md` per capability and nothing downstream re-checks it: no refutation
step, no liveness filter, no human between the file and the request. A skill for
an operation nothing serves is not a stale document, it is a working instruction
to an agent to call a dead endpoint. It reads `hanzo.yaml` now, cut by the
operation's own TAG — never by path prefix, because the two disagree wherever a
binary answers at a noun that is not its name (`/v1/chat/completions` is `chat`).
506 skills across 159 capabilities × 3 brands.

## Handed to hanzo-inc/cloud — the whole cost of this change, itemised

Nothing below is fixable in this repo, and every item is measured at
`[email protected]`.

### 1. Served and undescribed — the 39

- **17 are `/v1/ai/*`**: `deployments` (7), `signin-sessions` (7),
  `usages/{by-user,user-names}` (2), plus the ones the emission still calls
  `applications`/`sessions`. `apps/ai` projects that product from a committed
  `plugin/ai/openapi.json` subset instead of the mounted plugin's live registry —
  **a second authority INSIDE cloud, the same disease one level down**. This is
  the highest-value fix on the list, and it also collapses ~11 tags in
  `capabilities.yaml` (`query`, `query_multiple`, `install-patch`, `dev-bridge`,
  `wecom-bot`, `traffic`, `provider-flags`, `docs`, `health`, `feedback`,
  `documents`) that are that seam's hand-declared shrapnel rather than products.
- **`POST /v1/mcp`** — 200 with the tool list, control `/v1/mcp-zzq9` 404, in no
  document. The fleet's one MCP endpoint is undeclared, which cost `flows.yaml` its
  `tools` example. Note it answers 404 to GET, which is why a GET-only sweep has
  twice concluded it does not exist.
- **`GET /v1/{world,evals,referrals}/health`** — 200, controls 404, undescribed.
- **`GET /v1/o11y/services`** — 405, control 404: the address routes, and the
  verb is wrong on one side or the other.
- **`GET /v1/s3/` and `GET /v1/s3/{bucket}`** — 403 vs control 404. Cloud
  registers `/v1/s3/{name}` (provisioning) and `/v1/s3/buckets/…` (storage);
  `manifest/apps.go:83` already notes those two owners share one prefix.

### 2. Relay routes that can only ever emit `{wildcardN}` — 66 addresses

`bot` (32), `dns` (16), `tasks` (8), `collections` (5), `kms` (2), and one each
of `download`, `exec`, `files`. Each is a single `app.All("/v1/<x>/*")`
registration, so there is no per-operation site and the document can only show
the relay. The fix is projecting the mounted registry, exactly as for `apps/ai`;
until then these addresses are unknowable from outside, and the honest document
says so rather than guessing a list.

### 3. Shapes only the deleted master had — 302 operations

Not prose: **the master carried ZERO summaries or descriptions the document
lacks.** That argument is already won — cloud's emission carries a summary on
2333 of 2333 operations and a description on 2283, out of the handlers' own doc
comments. What it lacks is TYPES on routes that are not typed ops.

| product | ops | requestBody | 2xx schema | query params |
|---|---:|---:|---:|---:|
| ai | 184 | 85 | 183 | 1 |
| iam | 30 | 24 | 0 | 6 |
| functions | 10 | 2 | 10 | 2 |
| agents | 7 | 6 | 7 | 1 |
| security | 7 | 1 | 7 | 2 |
| admin | 6 | 2 | 6 | 2 |
| integrations | 6 | 2 | 1 | 4 |
| kms | 4 | 2 | 4 | 1 |
| evals | 4 | 3 | 3 | 1 |
| notify | 3 | 3 | 3 | 3 |
| affiliates · authz · git | 3 each | 3 | 9 | 1 |
| 26 more products | 39 | 25 | 38 | 8 |
| **TOTAL** | **302** | **152** | **261** | **31** |

Those shapes were hand approximations and they are gone. A route regains its
shape by becoming a `zip.Get[In, Out]`: the weave then carries body, parameters
and response from the code itself, and `publish.py` picks it up with no change
here. Writing them back would mean inventing shapes, which is what rule 5's
`default` exists to refuse.

**The query parameters are the sharp end**, because a missing filter is a
capability no client can reach at all:

| route | parameters the binary does not declare |
|---|---|
| `GET /v1/iam/oauth/authorize` | `client_id`, `redirect_uri`, `response_type`, `scope`, `state`, `code_challenge`, `code_challenge_method`, `provider` — **the whole OAuth handshake** |
| `GET /v1/integrations/{provider}/callback` · `/v1/integrations/slack/link{,/callback,/slack}` | `code`, `state`, `error` |
| `GET /v1/billing/usage` | `start`, `end` |
| `GET /v1/security/findings` · `/v1/security/scans` | `scanId`, `minSeverity`, `limit` |
| `GET /v1/platform/fleet` | `env`, `health`, `drift` |
| `GET /v1/kms/secrets` | `path`, `env` |
| `GET /v1/ml/models` | `stage`, `search` — a TYPED op whose `In` struct is simply incomplete |
| `GET /v1/websearch/search` | `q`, `format` — a search endpoint that declares no query |
| `GET /v1/evals/scores` · `/v1/admin/{affiliates,referrals}` · `/v1/functions/{metrics,{name}/invocations}` | `limit`, `runName`, `range` |
| `POST /v1/notify/send{,/email,/sms}` | `sync` |

### 4. Tag prose attributed to the wrong package

A tag's description comes from whichever package declared it first, so `org`,
`docs`, `health`, `memory`, `rag`, `chat` and a dozen more read "Package ai is
Hanzo AI —", and `files`, `download`, `upload` read "Package exec is the code
interpreter". Cosmetic, and visible on every doc page and in `CAPABILITIES.md`.

### 5. Three o11y schemas the Go client cannot be generated from — BLOCKING

Every generator Pascal-cases a property name and emits `Get<F>`, `Get<F>Ok`,
`Has<F>` and `Set<F>` beside it. Three schemas break under that:

| schema | property names | what Go does |
|---|---|---|
| `o11y.GettableAgentCheckIn` | `integration_config` **and** `integrationConfig`; `removed_at` **and** `removedAt` | `IntegrationConfig redeclared`, `RemovedAt redeclared` — two spellings of one field, side by side, commented "Older fields for backward compatibility with existing AWS agents" |
| `o11y.O11yPodOnboarding` | `hasClusterName`, `hasNamespaceName`, `hasNodeName` beside `clusterName`… | `field and method with the same name HasClusterName` |
| `o11y.PostableProfile` | `has_existing_observability_tool` beside `existing_observability_tool` | same |

MEASURED: `go build ./...` on the client generated from `hanzo.yaml` fails on
these three **and on nothing else** — renaming those keys in a scratch copy of the
document and regenerating gives **exit 0**. This repo must NOT rename them: a
field name is the wire, and a rename here would be exactly the invention the
whole change removes. `test_publish.py` pins the three as a CEILING, so a fourth
cannot arrive unnoticed while these stay open.

The old master did not have this because its copy of cloud's document was
STALE — 1967 operations against cloud's 2333, missing the whole o11y typing lane
that introduced these schemas. The bug arrives with publishing the current
release, not with the projection.

### 6. The five emitter rules

Rules 1–5 above plus the security scheme. Landing them deletes `publish.py`.

## The inference surface is NOT answered at an edge

An earlier version of this file, and of `hanzoai/cli`'s, asserted the bare-`/v1`
inference routes are "answered at the edge, not by cloud". That was a
rationalization and it is false. Measured with nonsense-sibling controls:

```
GET  /v1/models            200   |  GET  /v1/models-zzq9            404
POST /v1/chat/completions  401   |  POST /v1/chat/completions-zzq9  404
GET  /v1/tools             403   |  GET  /v1/tools-zzq9             404
POST /v1/event             401   |  POST /v1/event-zzq9             404
```

All four are in the document, served by the same host that answers everything
else, on the one chain: ingress → gateway → ZAP → cloud → ZAP/UDS → plugin.
`/v1/chat/completions` and its siblings are top-level because every OpenAI and
Anthropic SDK hard-codes those paths — there the PATH is the compatibility
contract — not because a different server answers them. If you find prose
anywhere claiming an edge exception, it is a bug in the prose.

## SDK generation — the ONE way

The interface is `hanzo.yaml`; the backend is **openapi-generator 7.14.0** for
every language. Each language repo owns its call site (`scripts/generate.sh`),
every per-language knob is data in `sdks.yaml`, and the invocation is logic that
lives once, in `generate.py`.

| Lang | Canonical repo | Generator | Ships as | Driven by |
|------|------|-----------|---------|---------|
| Python | `hanzoai/python-sdk` | `python` (urllib3, pydantic v2) | `hanzoai` on PyPI (`pkg/hanzo-inc/cloud`) | `generate.py` |
| TypeScript | `hanzoai/js-sdk` | `typescript-axios` | `hanzoai` on npm (`src/`) | `generate.py` |
| Java | `hanzoai/java-sdk` | `java` (okhttp-gson) | `ai.hanzo:hanzo-java-cloud` | `generate.py` |
| Kotlin | `hanzoai/kotlin-sdk` | `kotlin` (okhttp4+gson) | `ai.hanzo:hanzo-kotlin-cloud` | `generate.py` |
| Rust | **`hanzo-rs/sdk`** | `rust` (reqwest) | `crates/hanzo-client` | `generate.py` (+ `templates/rust/`) |
| Go | **`hanzo-go/sdk`** | `go` | `package hanzoai` at the MODULE ROOT, imported as `github.com/hanzoai/go-sdk` | `generate.py` |

Three repos were RENAMED and answer through a redirect (`hanzoai/go-sdk` →
`hanzo-go/sdk`, `hanzoai/rust-sdk` → `hanzo-rs/sdk`, `hanzoai/cpp-sdk` →
`hanzo-cpp/sdk`), so a stale name still resolves and hides the move;
`gh api repos/<old> --jq .full_name` prints the new one. Go's module path stays
`github.com/hanzoai/go-sdk` — that is what the proxy has.

**When a language leaves `sdks.yaml`**: a row exists while the WHOLE invocation is
expressible as data. What is NOT allowed is a row here AND flags there. **Both
departures have now come back** — go when `owned()` replaced directory ownership
with a set of files, rust when `templates:` landed — so every language this repo
generates is a row, and only `cpp` is still out (it needs generator 7.24.0, and
the pin is one version for everyone).

**`rust` was the first to leave and the last to return.** It needs a
`reqwest/api.mustache` override for the 16 operations whose binary body is
OPTIONAL, and the argument was that a template is a FILE that must sit beside its
flags — right about the risk, wrong about the address. `templates:` names a
directory under THIS repo (`templates/rust/`), so the override and its flags land
in one commit. The departure is what drifted: its script defaulted to
`hanzoai/openapi` `hanzo.yaml@main` while the `.spec-lock` beside it named
`hanzo-inc/cloud` `openapi.yaml` at a commit. Regenerating at the ref that lock
named, through the driver, reports `[rust] clean` — byte-identical to what the
155-line script produced.

**`hanzoai/ruby-sdk` was a row naming a client nobody shipped** — a hard 404 with
no redirect, while every genuinely renamed SDK answers 301, and no gem under
`hanzoai_cloud` or any other candidate. A visible gap is honest; a row that
generates into nothing is not.

### Which document each client is a projection of

`generate.py` resolves it per repo: `--spec` (the document by value, what
hanzoai/ci's `client:` lane passes), else that repo's `.spec-lock`, else this
checkout's `hanzo.yaml`. The fallback was removed once, correctly, while
`hanzo.yaml` was the hand-merged master; it is back because the file is a
projection now, and because the alternative was measured to produce zero files
in every language.

**Open, for the fleet**: each SDK repo's `hanzo.yml` declares
`client.spec.repo`, defaulting to `hanzo-inc/cloud`. Those should name
`hanzoai/openapi` / `hanzo.yaml` — the generatable projection — until rules 1–5
land upstream, at which point they should name `hanzo-inc/cloud` again and mean it.
Not changed here: those are other repos.

Every SDK also renders `flows.yaml` into its `examples/` — the same six journeys,
from the same operationIds, in every language. An SDK does not choose its own
examples any more than it chooses its own methods. Two of the six moved in this
change, both because a hand-authored operationId vanished with its hand-authored
spec: `hello` was `bot_authMe` (`/v1/bot/auth/me`, now behind a relay route) and
is `get_v1_keys`; `tools` was `mcp_rpc` (`POST /v1/mcp`, undeclared) and is
`get_v1_tools`. Both replacements were probed with controls — see `flows.yaml`.

### operationIds changed, deliberately, once

The `<svc>_` prefix `merge.py` applied is gone. It existed to keep 52 authored
specs from colliding, and with one document there is exactly **one** collision in
2284 operations. `cloud_get_v1_billing_balance` is now `get_v1_billing_balance`;
`gateway_createChatCompletion` is `post_v1_chat_completions`. A prefix invented
here was a second naming authority, and the bare id is the one the MCP server
already uses — a tool name is its operationId. Pin against the document, not
against a remembered method name.

## Conventions

- Every route is `/v1/<product>/<resource>`; a path segment names a THING and the
  METHOD says the verb. Where a binary answers at an address it inherited it tags
  that operation `compat`, and rule 2 keeps it out of the publication.
- IAM also answers OIDC discovery at the three unprefixed addresses the standards
  fix — `/.well-known/{openid-configuration,jwks,oauth-authorization-server}` —
  each the same handler as its `/v1/iam/` twin.
- No `/api/` prefix, no `deprecated: true`, no cross-brand references. Forward
  only.
- White-label is by DOMAIN: `skills.py` rewrites `api.hanzo.ai` / `hanzo.id` /
  `Hanzo` per brand, longest-host-first, and a Lux surface never says Hanzo.

## Licensing

`MIT OR Apache-2.0`, at your option — per HIP-0137 (`hanzoai/hips`, `HIPs/hip-0137-one-license.md`). Relicensed from BSD-3-Clause,
which HIP-0137 puts out of scope for `hanzoai`. The history reaches back to 2016
and is Hanzo's own; no third-party source survives in HEAD. Generated clients
are projections of this repo's spec and carry the same terms; `dist/` is built,
never committed.