# 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
- 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.
- Private/non-public repositories require mediated source-provider support.
- 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.

## 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. Treat
those surfaces as `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 |
| 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 |
| Stuck task / heartbeat stale | `wheelie work session status <work-or-session-ref> --json` | `reason=heartbeat_stale|checkpoint_missing`, `support_state=needs_reconnect|operator_attention_required`, `event_cursors` | a fresh checkpoint exists and resume/nudge is bounded and non-destructive | resume may repeat external mutation, no context-out exists, or event replay/status disagree |

These states mirror the executable runbook contract in
`docs/feature_design/con7858_wheelie_agent_support_runbooks.md` and should return
or summarize `wheelie_support_diagnosis_receipt/v1` fields.

## Stop conditions

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

- runaway cost, budget cap exceeded, 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.

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.