# Wheelie launch support and friendly error states

Agent docs index: /llms.txt

Wheelie private preview support is a human support channel plus agent-readable
receipts. Start from typed Wheelie status commands, not raw terminal logs,
provider dashboards, screenshots of secrets, or private source dumps.

## Where to ask for help

- Email: support@continua.ai
- Discord/community: private-preview invite only. Use the Discord support channel
  named by your invite packet; if you do not have one, use email instead.
- Billing or allowance changes: email support. Wheelie private-preview billing is
  manual invoice or contract only.

Support owner for launch: the current Wheelie launch/support on-call owner.
Support is responsible for ensuring every support request that needs a response
is acknowledged, routed, or explicitly declined. During private preview, expect
best-effort human response within one business day; capacity, security, billing,
and launch-stop incidents should be escalated immediately to the launch/support
owner.

## Discord pinned guidance

Pin or mirror this exact guidance in the private-preview Discord support channel:

```text
Wheelie private preview support

Start here:
- Quickstart: https://wheelie.dev/docs/wheelie/quickstart.md
- BYOK/secrets: https://wheelie.dev/docs/wheelie/byok-secrets.md
- Support levels: https://wheelie.dev/docs/wheelie/support-levels.md
- Billing: https://wheelie.dev/docs/wheelie/billing.md
- Spend support states: https://wheelie.dev/docs/wheelie/spend-support-states.md
- Support/friendly errors: https://wheelie.dev/docs/wheelie/support.md

When asking for help, share:
- the command you ran, without secrets or raw tokens;
- the typed `schema_version`/`schemaVersion`, `reason`, `support_state`,
  `next_action`, `operation_refs`, `evidence_refs`, and `cursor` fields;
- redacted `wheelie://...` refs for work items, working copies, changes,
  validation/evidence, resources, previews, or operations.

Do not share provider API keys, OAuth codes, cookies, SSH keys, service-account
JSON, private source dumps, full terminal transcripts, capability-bearing preview
URLs, raw provider dashboard URLs, screenshots containing secrets, or local
absolute paths.

Private preview boundaries:
- Billing is manual invoice or contract only; spend/payment surfaces stay fixture/test, customer-direct/BYOK, private-pilot, disabled/fail-closed, or unsupported unless a scoped support receipt says otherwise.
- Private/non-public repositories require mediated source-provider support; see https://wheelie.dev/docs/wheelie/private-repos.md.
- Hosted issue-to-PR, preview URLs, checkpoint stores, and provider-backed
  submit/watch are adapter-, preview-, or allowlist-gated until Wheelie says
  otherwise in JSON.
- BYOK credentials are encrypted/write-only in storage; raw env/file projection
  means a process in your trusted workspace may be able to read the projected
  secret.
```

## Safe support bundle

Safe fields to share with support:

- `schema_version` or `schemaVersion`
- `reason`, `support_state`, `next_action`, `retry_after_seconds`
- `operation_refs`, `evidence_refs`, `work_item_ref`, `working_copy_id`,
  `change_ref`, `preview_route_ref`, `cursor`, and redacted artifact/log refs
- redacted resource, cost, validation, source snapshot, and support-case refs
- the minimal command family and arguments after removing secrets and private
  provider URLs

Do not share raw secrets, raw source payloads, private provider URLs, local
absolute paths, capability-bearing URLs, authorization headers, cookies, raw
provider payloads, raw terminal frames, private transcripts, or chain-of-thought.

## Source fetch and review failures

For `source.wheelie.dev` or `wheelie source fetch ...` failures, the contracted
safe support path is a reviewed Source support bundle from the hosted error
panel.

Browser Source error panels may prefill that flow with source URL, request ID,
and trace ID fields. Review the generated bundle before sending. If
the command is unavailable, email `support@continua.ai` with only the safe fields:
source host, command family, reason, `support_state`, `next_action`, request ID
or trace ID when present, opaque source/work/change refs, and the redaction
receipt. Do not include secrets, local paths, private source, raw logs,
screenshots with secrets, provider dashboards, or capability URLs.

## Hosted-app issue reports

The public launch path does not yet include self-serve hosted-app issue reports,
app-owner issue review, or customer-managed support-bundle export/delete. Native
hosted-preview issue/report storage may exist for validation, and route/storage
wiring may be promotion-ready, but the current public-live gate is still no-go
until an approved rollout has live route reachability, adapter-delivery readback,
and matching public docs. Treat those surfaces as `hosted_preview`,
`requires_adapter`, or `internal` unless a Wheelie command for your app returns a
live support receipt.

For a Wheelie-hosted app issue today:

1. Run the narrow status/readback command for the affected app, preview, work,
   validation, release, or resource.
2. Share only safe refs and support-bundle fields from the section above:
   app/environment/release/run/trace refs, reason, support state, next action,
   operation/evidence refs, cursors, and redacted artifact/log refs.
3. Email support or use the private-preview Discord support channel. Do not send
   raw screenshots, prompts, user payloads, source snippets, secrets, logs,
   capability URLs, or provider dashboard URLs unless support asks through an
   explicit redaction/consent path.

Issue trackers, chat integrations, source-control provider dashboards, and
runtime-provider dashboards are adapter or operator surfaces, not the public
customer contract for hosted-app issues.

## Friendly error states

| Symptom | Start command | Expected typed fields | Agent can self-remediate when | Ask user / operator when |
| --- | --- | --- | --- | --- |
| No capacity / queued too long | `wheelie resources status --json` | `reason=capacity_limited`, `support_state=retry_later|approval_required`, `retry_after_seconds`, `operation_refs` | retry-after is present and the retry keeps the same operation/idempotency refs | VM size, region, profile, budget, quota, or support staffing must change |
| Provider key invalid, revoked, or rate-limited | `wheelie auth status --provider <model-provider> --json` | `reason=credential_invalid|credential_revoked|provider_rate_limited`, `support_state=requires_auth|retry_later` | rate-limit includes `retry_after_seconds`, or a Wheelie session refresh is possible without exposing credentials | user must reconnect/rotate a key, switch provider mode, or approve managed credits |
| Repo/source auth missing | `wheelie source status --repo <org>/<repo> --json` | `reason=source_provider_auth_required|agent_grant_missing|repo_not_authorized|source_provider_adapter_required`, `support_state=requires_auth|requires_grant|requires_adapter` | a scoped trusted-agent grant can be requested through Wheelie auth or a public repo only needs refresh | GitHub app/OAuth/repo consent, private repo mediation, or repo-scope change is required; for private/non-public repos use [the private repo guide](./private-repos.md) |
| Provider work alias not imported | `wheelie work resolve-alias <provider-alias> --json` | `reason=provider_alias_not_imported`, `support_state=optional_adapter_absent`, `optional_adapter_absence_receipt` | continue with native `wheelie://` WorkGraph refs, or create/import the missing item locally | user explicitly needs that external provider alias mirrored or imported |
| Validation failed, missing, or stale | `wheelie validation status --change <change-id> --json` | `reason=evidence_stale|validation_failed|missing_evidence`, `support_state=rerun_required|blocked`, `evidence_refs` | a focused lane rerun or deterministic local fix updates evidence for the same candidate | failure is acceptance-shaped, spendful, wrong-candidate, or false-green |
| PR/change creation failed | `wheelie change status --change <change-id> --json` | `reason=change_not_published|provider_backpressure|pr_mutation_failed`, `support_state=blocked|retry_later|requires_adapter` | clean working copy only needs capture/publish or provider backpressure has retry-after | publishing changes external exposure, conflicts need product judgment, or partial provider mutation occurred |
| Preview failed or unhealthy | `wheelie preview status --preview <preview-ref> --json` | `reason=preview_capacity_exhausted|preview_health_failed|preview_capability_revoked`, `support_state=retry_later|requires_adapter|operator_attention_required`, `preview_route_ref` | bounded restart/GC is supported before public traffic and keeps the same preview refs | serving creates public ingress/spend, capability URL leaked, or allocation/health/revoke receipts disagree |
| Budget cap reached / runaway cost | `wheelie resources metering-sample --json --share-redacted` | `reason=budget_exceeded|approval_required`, `support_state=approval_required|fail_closed`, `cost_receipt_refs` | pausing/cancelling prevents spend without data loss or a cheaper lane satisfies the goal | continuing requires higher budget, paid provider mode, or post-cap operator approval |
| Spend/payment unavailable | Route-specific status command | `support_state=fixture_only|test_mode|customer_direct_byok|private_pilot|disabled_fail_closed|unsupported`, `money_movement_enabled=false`, `safe_next_action`, `fee_policy_ref`, `refund_dispute_owner_ref` | no-money fixture, customer-direct/BYOK, or manual support billing satisfies the need | money movement, issuing, checkout, refund/dispute automation, or provider mutation is requested |
| Stuck task / heartbeat stale | `wheelie work status <work-ref> --json`, then `wheelie work watch <work-ref> --cursor <token> --limit 100 --ndjson` when an event cursor is available | `reason=heartbeat_stale|checkpoint_missing`, `support_state=needs_reconnect|operator_attention_required`, `event_cursors` | status/watch shows a fresh checkpoint or safe next action; session attach/resume is explicitly listed by `wheelie work --help` or an attached adapter receipt | resume may repeat external mutation, no context-out exists, event replay/status disagree, or stable help does not expose the needed session command |

These states mirror the private executable runbook contract that support owners
maintain in the source repository. Public tools should return or summarize
`wheelie_support_diagnosis_receipt/v1` fields without exposing private runbook
paths.

## Stop conditions

Stop new admissions or pause the affected workflow when any of these occur:

- runaway cost, budget cap exceeded, unknown price, stale quote, or spend continuing after a cap receipt;
- suspected secret, token, credential, private source, capability URL, or support
  bundle leak;
- capacity exhaustion, queue age beyond the launch threshold, or no truthful ETA;
- p95 task, validation, preview, or support response latency is too slow for the
  current cohort target;
- stuck tasks with stale heartbeat and no checkpoint/context-out;
- validation false-green, wrong-candidate evidence, or missing terminal proof;
- preview URL cannot be revoked, health-checked, or tied to a safe capability;
- more than two unresolved launch-support issues per on-call person, p95 first
  response above four business hours for friends/family, or any serious incident
  without a named owner;
- a command asks for raw provider tokens, private dashboards, raw source, or
  unbounded transcripts instead of typed receipts;
- public copy or support text implies hidden fees, unapproved issuing,
  unsupported funds transfer, self-serve checkout, unapproved overage billing, or
  live commerce without a scoped support receipt.

Escalate serious failures to the Wheelie launch/support owner with a redacted
support bundle and, when customer-visible or safety-relevant, attach the
incident/postmortem packet. Do not promise a later agent follow-up unless a human
explicitly assigns that responsibility.