hanzo-dev 55ef5731e0 docs: the first sentence is the product the customer bought, not the plumbing ...

A package's first sentence is not prose that stays in the file. openapi.Synopsis
reads it at describe time, describe.go stamps it into that app's own subset as
info.description, the weave lifts it onto the product's OpenAPI tag, and the same
string is the CLI group help line and the MCP door prose. So it is the ONE
sentence a paying customer reads before they know anything else about us — and
across this slice it was answering a question they never asked.

"Package functions mounts the Hanzo Cloud /v1/functions surface" tells a buyer
where our routes live. It does not tell them they can publish code and call it
over HTTP. "Package meet is the CONTROL plane for the virtual office" names our
half of a split they cannot see. "Package o11y is the ONE owner of the cloud
binary's observability plane — ... every part of the concept:" published a colon:
the paragraph had no sentence break, so the whole registry-internals paragraph
WAS the description. Thirty-seven packages led with a mount point, a route
prefix, an implementation noun or an internal ordering argument.

Each now opens with what the customer gets, in their words, and every fact that
was in the old opener is kept verbatim one sentence down — the route prefix, the
tenancy boundary, the fail-closed behaviour, the topology. Nothing is deleted;
it is reordered so the first sentence answers "what is this" and the rest answers
"how does it work". The four packages here with no customer (k8s, s3admin,
datastore, controlplane) keep an internal first sentence, minus the ALL-CAPS and
the word "binary" that made them read like release notes.

openapi.yaml and plugin/*/openapi.json are regenerated from source in the same
commit, because a doc change IS a published-surface change and the drift gate is
right to say so.

Co-authored-by: Hanzo Dev <dev@hanzo.ai>

2026-07-30 22:52:20 -07:00

12 KiB

Raw Permalink Blame History