API & contract stability

Public beta preview

Guuey is in public beta preview. Until general availability, public surfaces can still change with the product — including breaking changes without a deprecation window. Pin exact @guuey/* package versions and expect to update.

What is versioned today

Some contracts already carry explicit versioning, preview or not:

• guuey.json is schema-versioned. The root "schema" field is a decimal integer string (currently "1"), bumped only on a change an older reader cannot interpret correctly. A document declaring a newer schema is refused everywhere — the CLI says SCHEMA_TOO_NEW (upgrade @guuey/cli), the API answers 400 SCHEMA_UNSUPPORTED — never best-effort parsed. The CLI and the platform API compare against the same constant in @guuey/config, so they can only disagree when one of them is out of date. Details: Agents as code.
• The theme schema is additive-only. Parsing is lenient, unknown keys pass through, and new tokens ship with defaults — a stored theme keeps parsing against future versions. See Theming.
• Client SDKs: the exported functions are the contract. The SSE frame grammar and other wire details underneath them are internal and can change between releases. See Build your own surface.

The @guuey/* packages are versioned in lockstep and are pre-1.0 (0.x): a minor-version bump can carry breaking changes until the packages reach 1.0.

The posture at general availability

At general availability, the platform’s public contracts move to a stability posture:

• Additive evolution. The HTTP API (https://api.us-east-1.guuey.com/v1) and the CLI’s machine-readable output grow by adding fields and endpoints; existing ones are not removed or renamed without a deprecation cycle.
• Versioned schema. guuey.json keeps the "schema" mechanism above; when a "2" ships, the 1 → 2 migration lands in @guuey/config so the CLI and the API pick it up together, and documents you wrote against "1" keep working.
• Announced deprecations. Anything scheduled for removal is announced with a migration path before it goes away.

What is never a contract

Internals stay internal at every stage: the SSE frame grammar under the SDKs, undocumented endpoints, the shape of server-rendered HTML, and anything not described in these docs. If you find yourself depending on one of them, tell us what the documented surface is missing.