# 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.

Slack user integration is currently `fixture-only` for its launch-preview support row:
the checked packet covers OAuth install shape, workspace/channel/user/thread/search
readback, approval-gated posting, token custody/revocation, and cross-workspace
denial through a fake Slack provider. Do not claim live Slack workspace access
until a public zero-context demo workspace receipt proves the live flow; private
Continua Slack channels are never a fallback for external users.

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.

## Agent-readable surface doctrine

Every Wheelie, platformd, or Gravity-built product surface should choose the
strongest honest access mode below and return it as machine-readable status.
Browser automation, screenshots, raw provider dashboards, and prose logs are not
the product boundary.

| Access mode | Product meaning | Agent behavior |
| --- | --- | --- |
| API-first | The surface has a documented command, HTTP/API route, or typed manifest/receipt that can be driven without a browser. | Use JSON status/results for snapshots, NDJSON/SSE with cursors for watches, and idempotency keys for mutations. |
| Browser-mediated fallback | A human browser flow is needed for sign-in, consent, payment approval, device pairing, or another capability grant, but the browser step returns to a typed status surface. | Open or present the signed link/code only when the receipt asks for it; resume from the returned operation/support-state receipt instead of scraping the page. |
| Links-only | Wheelie can point to a docs page, provider page, support article, or manual destination, but it cannot perform or verify the action for the selected scope. | Share the link and stop or ask the user; do not infer success from page existence, URL shape, or a screenshot. |
| Support-only | A human/support/operator action is required and no self-serve product path is currently supported. | Produce a redacted support bundle with typed refs, blockers, and safe next action; do not attempt hidden provider/admin work. |

### Surface checklist

A surface is agent-readable only when the applicable items are explicit:

- Snapshot reads return JSON with `schema_version` or `schemaVersion`, stable
  refs, `support_state`, `reason`, `next_action`, and blockers or gaps.
- Long-running operations return an `operation_ref`, idempotency key semantics for
  mutations, progress status, terminal status, and safe retry/repair guidance.
- Event streams use bounded NDJSON/SSE with cursors, limits, max-wait behavior,
  final status, and resume semantics; polling fallback is labeled as fallback.
- Auth, actor, permission, budget, and capability decisions are receipt-backed;
  caller-supplied IDs, emails, headers, or provider URLs are not authority.
- Browser links are for human consent or review only; typed receipts remain the
  automation authority after the browser step.
- Evidence hooks name validation environment, candidate/source refs, evidence
  refs, support gaps, and degraded provider-native enrichment where applicable.
- Privacy and cost boundaries are typed: no raw secrets, raw private source,
  capability-bearing URLs, raw prompts, raw provider payloads, or high-cardinality
  private identifiers in normal receipts or support bundles.
- Unsupported, allowlist, adapter-required, fixture-only, and support-only states
  fail closed with a safe next action instead of silently falling through to raw
  provider CLIs, dashboards, SSH sessions, or browser automation.

### Existing implementation roots

This doctrine does not create a new implementation lane. Use the owning roots
that already exist:

- Public Wheelie CLI/support-state contract: this page, [CLI support map](./cli.md),
  [Support and friendly error states](./support.md), the public command manifest,
  and the signed/native Wheelie trust-root command implementation.
- Platformd capability IA: [Platform capabilities](./platform-capabilities.md),
  active app manifests, operation receipts, and support/readiness receipts.
- Platformd events/observability: `platformd.events`, `platformd.observability`,
  their docs/contracts, and the existing observability/events implementation
  roots; OpenTelemetry is an ingestion path, not product authority.
- Alerting: the deferred alerting surface owns alert-family and incident
  evidence decisions; do not fold alert implementation into generic support docs.
- Spend/payments: MoneyRouter spend capabilities and [Spend support
  states](./spend-support-states.md) own funds-movement readiness, approvals, fee
  receipts, and fail-closed gates.
- Gravity-specific API/support truth remains owned by the relevant Gravity runtime
  route, app, and support-state docs; this page only defines the reusable public
  surface rule.

### Recommended first proof surface

Validate this doctrine first on the existing platformd observability readback
path for a local or isolated-stack Wheelie app: app stdout/stderr or structured
logs should be readable through the public Wheelie/platformd log readback with
JSON status, stable app/deployment/environment/request refs, redaction policy,
`support_state`, evidence refs, and typed provider-enrichment gaps. That is the
smallest current surface that exercises API-first readback, platformd ownership,
support-gap truth, and evidence hooks without creating duplicate implementation
work.

## Machine-readable support-state gate

The public command manifest and [public support-state matrix](./support-state-matrix.md)
emit typed launch-gate metadata for every row: `support_state`,
`validation_environment`, `production_path_status`, `green_launch_row`,
`docs_paths`, and `evidence_refs`.

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 planned 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.