# AetherDesk Support Runbook

Status: paid-pilot draft.

## Start/reuse

For portable customers:

```powershell
START-AETHERDESK.cmd
```

The launcher reuses an already-healthy server on the selected port and opens:

```text
http://127.0.0.1:5717/?resetDesktop=1&portable=1
```

## First checks

Inside the UI:

1. Click the `SA` tray button.
2. Confirm `POWER ACCESS: READ-ONLY`.
3. Click `Headless check`.
4. Click `Crash recovery`.
5. Run the default real PowerShell command.

CLI checks:

```powershell
npm run aetherdesk:system-access:hardening
npm run aetherdesk:auth-hooks:smoke
```

## Logs and receipts

Portable logs:

```text
artifacts/portable_logs
```

System Access receipts:

```text
artifacts/aetherdesk_system_access_receipts.jsonl
```

MCP hook config:

```text
artifacts/aetherdesk_mcp_hooks.json
```

## Port conflict

Use System Access -> `Crash recovery`.

Confirm:

- current server PID
- port owner process name
- process path
- startup log tail

Do not kill a process unless the customer confirms the PID/path belongs to the stale AetherDesk server.

## Update

Preserve `artifacts/` before replacing app files.

See:

```text
UPDATE_POLICY.md
```

## One-command support bundle

For paid pilots, collect a secret-safe support snapshot with:

```powershell
npm run aetherdesk:support:bundle
```

The bundle writes JSON and Markdown under `artifacts/support_bundles/`. It probes local AetherDesk health/status endpoints, includes release manifest/integrity data, tails system-access receipts, reads MCP hook state, and redacts common token/secret patterns before writing output.

## Agent workflow spine

AetherDesk now exposes repeatable system workflows through shared human/agent routes:

```powershell
npm run aetherdesk:agent-workflows:smoke
```

See `docs/AGENT_WORKFLOW_SPINE.md`. The spine provides `GET /api/agent/workflows`, `POST /api/agent/workflows/:id/run`, and `GET /api/agent/workflows/receipts`, with allowlisted scripts and receipts under `artifacts/aetherdesk_workflow_receipts/`.

## Operations digest

Paid-pilot readiness now includes an operations digest:

```powershell
npm run aetherdesk:ops:digest
```

This creates `artifacts/aetherdesk_ops_digest/latest.json` and `latest.md`, summarizing release, workflow, support, and System Access evidence into one handoff for agents or support.

## Ops autopilot

For support or handoff triage, generate a plan-only autopilot receipt:

```powershell
npm run aetherdesk:ops:autopilot
```

The latest receipt lives under `artifacts/aetherdesk_ops_autopilot/latest.json` and `latest.md`. Use `npm run aetherdesk:ops:autopilot:run-safe` only when you intentionally want it to run the safe maintenance catalog.

## System catalog

For orientation before agent work, generate or inspect the system catalog:

```powershell
npm run aetherdesk:system:catalog
```

Latest artifacts live at `artifacts/aetherdesk_system_catalog/latest.json` and `latest.md`. Agents should prefer `GET /api/agent/system-catalog` before guessing which scripts, workflows, roots, or artifact lanes exist.

## Mission packet

For a clean agent handoff, generate the mission packet:

```powershell
npm run aetherdesk:mission:packet
```

Latest artifacts live at `artifacts/aetherdesk_mission_packets/latest.json`, `latest.md`, and `latest-agent-prompt.txt`. This is the preferred handoff packet for another agent entering the system.

## AI PC scorecard

For support/readiness triage, generate the scorecard:

```powershell
npm run aetherdesk:ai-pc:scorecard
```

Latest artifacts live at `artifacts/aetherdesk_ai_pc_scorecard/latest.json` and `latest.md`. The scorecard intentionally lists weak evidence, including visual/live-machine gaps, instead of claiming completion from narrow checks.

## Agent bootstrap

For the quickest support/agent entrypoint, generate or read the bootstrap packet:

```powershell
npm run aetherdesk:agent:bootstrap
```

Latest artifacts live at `artifacts/aetherdesk_agent_bootstrap/latest.json` and `latest.md`. Agents should read `GET /api/agent/bootstrap` first, then follow the listed routes and safety invariants.

## Visual proof support triage

When a customer or operator says the desktop does not look right, collect:

- `npm run aetherdesk:agent-workflows:visual`
- `npm run aetherdesk:visual-proof:doctor`
- `GET /api/agent/visual-proof`
- `artifacts/aetherdesk_visual_proof/latest.json`

Treat `contract-proven-live-blocked` as an honest known gap: the UI source contract passed, but live browser screenshot proof has not been established in this environment. Do not claim live visual verification until the doctor reports `live_browser_visual: true` from a real bounded visual proof.

## Live visual proof support triage

For visual complaints or demo readiness, run:

- `npm run aetherdesk:live-visual:proof`
- `npm run aetherdesk:visual-proof:doctor`
- `GET /api/agent/live-visual-proof`
- `GET /api/agent/visual-proof`

A live visual receipt with `ok: true` and `proof_ok: false` means the support artifact worked but the browser/screenshot proof did not pass. Use the receipt's `child.stderr_tail`, screenshot list, and failed checks to distinguish launch failure, route load failure, screenshot failure, and contrast/readability regression.

## Control-plane support proof

For safety/control support issues, prefer the self-hosted proof before asking the customer to keep a server open:

- `npm run aetherdesk:control-plane:proof`
- `GET /api/agent/control-plane-proof`
- `artifacts/aetherdesk_control_plane_proof/latest.json`

A passing proof means the local control routes, MCP toggle/sign-in intents, read-only PowerShell boundary, denial receipts, and receipt field shape all worked against an ephemeral server. If it fails, use the failed `checks` array and compact route list in the artifact before expanding the surface.

## Soak recovery support proof

When investigating drift, flaky visual launch, stale routes, or repeated-start reliability, run:

- `npm run aetherdesk:soak:recovery`
- `GET /api/agent/soak-recovery`
- `artifacts/aetherdesk_soak_recovery/latest.json`

The default run performs two bounded cycles. Increase coverage with `AETHERDESK_SOAK_CYCLES=3` or higher after a short run passes. Do not treat a single point-in-time scorecard as a soak result; use the cycle list and failures array from the soak artifact.

## Customer machine doctor

When a fresh/customer machine cannot start AetherDesk, collect:

- `npm run aetherdesk:customer:doctor`
- `artifacts/aetherdesk_customer_doctor/latest.json`
- `GET /api/agent/customer-doctor` if the server can start

If artifact directories are missing, use `npm run aetherdesk:customer:repair`; this only creates safe local artifact directories and writes a receipt. If modules are missing, the receipt suggests `npm install` but does not run it automatically. If the default port is occupied and not healthy, the receipt suggests setting `AETHERDESK_PORT` or stopping the conflicting process.

## License entitlement support proof

For paid pilot onboarding or license questions, collect:

- `npm run aetherdesk:license:proof`
- `artifacts/aetherdesk_license_entitlement/latest.json`
- `GET /api/agent/license-entitlement` if the server can start

Default customer id is `local-pilot`. Set `AETHERDESK_CUSTOMER_ID`, `AETHERDESK_LICENSE_EDITION`, and `AETHERDESK_LICENSE_DAYS` for a named pilot. Set `AETHERDESK_LICENSE_SECRET` only in a trusted support environment when you want an HMAC-signed pilot entitlement receipt.

## Public-sale readiness proof

For broad-sale reviews, collect:

- `npm run aetherdesk:public-sale:readiness`
- `artifacts/aetherdesk_public_sale_readiness/latest.json`
- `GET /api/agent/public-sale-readiness` if the server can start

A passing artifact does not mean public sale is complete. It means the paid-pilot evidence is intact and the remaining public-sale blockers are machine-readable.
