# Wheelie support levels

Agent docs index: /llms.txt

Wheelie public docs use explicit support levels so humans and coding agents do
not treat unavailable or adapter-specific surfaces as launch-ready APIs.

| Support level | Meaning | Agent behavior |
| --- | --- | --- |
| native | Intended to work in the public launch path for the documented scope. | Use it for the first-run plan. |
| preview | Visible and typed, but dependent on an adapter, account state, or maturing surface. | Probe status first and expect safe fallback states. |
| allowlist | Requires explicit access, capacity, budget, or credential approval. | Stop and request access or approval before spendful work. |
| fixture-only | Checked contract, local demo, or no-money prototype without live effects. | Inspect schema and run dry-run demos only; do not claim live availability. |
| unsupported | Not available for public launch. | Avoid it and use the documented native path. |

Every unavailable or gated command should report machine-readable fields such as
`support_state`, `reason`, `next_action`, `blockers`, and `operation_ref`. When a
launch user needs help, route them through [Support and friendly error
states](./support.md) and share redacted typed refs instead of raw
terminal/provider output.

Private and other non-public GitHub repository attach is launch-deferred unless
the selected repo returns a mediated source-provider adapter or allowlist
receipt. `source_provider_adapter_required` / `requires_adapter` is the correct
safe outcome; do not bypass it with raw provider tokens or local
credential-helper state. Use the dedicated [private/non-public GitHub repo
guide](./private-repos.md) for the user-facing flow and unsupported shortcuts.

Unavailable prototype surfaces are not part of the public launch path unless a
public Wheelie command explicitly reports a supported state. Fixture-only demos
must not be described as live provider access, live freshness, public pricing,
or payment support.

Spend/payment surfaces have an additional public copy boundary in [Spend support
states](./spend-support-states.md). They must expose
`money_movement_enabled=false` unless the exact account, app, environment, and
approval scope has a current support receipt saying otherwise.

## Machine-readable support-state gate

The public command manifest emits typed launch-gate metadata for every row:
`support_state`, `validation_environment`, `production_path_status`, and
`green_launch_row`.

Support-state values are intentionally more precise than the human-facing support
levels:

| Support state | Meaning | Green launch rule |
| --- | --- | --- |
| live | Production path is wired for the documented scope. | May be a green launch row when validation evidence metadata and expected JSON fields are present. |
| hosted_preview | Behavior is only proven on a hosted-preview route or equivalent preview surface. | Must not be promoted to a native/live claim without hosted-preview validation evidence, route-auth negative coverage, adapter/readback evidence where applicable, public docs updates, and rollout evidence. |
| test_mode | Behavior is deterministic test mode only. | Never green for public launch claims. |
| fixture_only | Behavior is backed only by checked fixtures or docs examples. | Never green for public launch claims. |
| requires_adapter | Public command exists, but live effects require an attached project/source/change/validation adapter. | May be first-run guidance only when output includes `support_state`, `reason`, and `next_action`. |
| optional_adapter_absent | Native/local authority can continue, but an imported provider alias or mirror is absent. | Do not prompt users to install an external tracker for native WorkGraph work; import/mirror only if they explicitly need that provider alias. |
| allowlist | Access, capacity, budget, or credentials require explicit approval. | May be documented as gated, not as generally available. |
| disabled_fail_closed | Money movement or material spend is blocked by missing approval, stale receipt, kill switch, unsupported capability, or policy. | Never green; report the blocker and safe next action. |
| provider_readback_ready | Provider/custody/account posture can be read, but execution still requires matching budget, approval, support-state, and custody receipts. | May support read-only status, not execution or payment claims. |
| roadmap | A public-safe placeholder for a future surface with no current product support. | Never green; show a supported alternative or stop. |
| unsupported | Not available for public launch. | Never green for launch work. |

`validation_environment` distinguishes `HERMETIC`, `ISOLATED_STACK`,
`HOSTED_PREVIEW`, `SHARED_STAGING`, and `LIVE_EXTERNAL` evidence. A row that is
fixture_only, test_mode, documented-only, or unsupported must fail the
support-level gate if it is marked as a green launch row.