# AetherDesk AI PC Operator Surface

Generated: 2026-07-01

This map describes the current real-PC operator layer added around the AetherDesk shell. The goal is a local-first AI PC for agentic operations and systems workflows: fast keyboard control, persistent mission state, offline-safe request capture, proof snapshots, and handoff receipts.

## Core idea

AetherDesk should feel like a small real computer first, then an agent cockpit second.

The first moves should be obvious:

- `Ctrl+K`: search apps and actions.
- `Ctrl+Alt+Enter`: ask the AI PC what to do next.
- `Ctrl+Alt+Space`: choose a mission mode.
- `F2`: open the current AI PC Control Map.
- `F1`: quick help.

## Always-visible surfaces

### Mission dock

Shortcut: `Ctrl+Alt+.`

Purpose:

- Holds the current objective.
- Holds the next action.
- Holds notes for human plus agent continuity.
- Quick launches Agent, Files, Terminal, and Notebook.
- Adds `Copy handoff` once the handoff receipt layer mounts.

Local state:

- `aetherdesk.realPc.operatorSession`
- `aetherdesk.realPc.operatorSessionCollapsed`

### AI PC status HUD

Purpose:

- Shows mission mode.
- Shows queue count.
- Shows active request count.
- Shows snapshot count.
- Shows active/total window count.
- Quick buttons: Ask, Queue, Proof, Map.

Local state:

- `aetherdesk.realPc.aiStatusHudCollapsed`

### Backend sync pill

Shortcut: click pill or `Ctrl+Alt+Shift+U`

Purpose:

- Shows whether queued requests are local-only, syncing, synced, degraded, or pending.
- In `file://` preview, reports `local-preview` and does not throw.
- In served `http://` / `https://`, tries `/api/pc/agent-task` for unsynced requests.

Local state:

- `aetherdesk.realPc.backendSyncStatus`
- `aetherdesk.realPc.backendSyncHistory`

## Command overlays

### Quick help

Shortcut: `F1` or `Ctrl+Alt+/`

Purpose:

- Small help overlay for first-contact use.
- Buttons for Search, Files, Terminal, Agent, Notebook, Clear desktop, Restore windows, Switch windows.

### AI PC Control Map

Shortcut: `F2` or `Ctrl+Alt+Shift+/`

Purpose:

- Current full command map.
- Launch surface for Search, Help, Mission Modes, Session Dock, Ask, Queue, Handoff, Snapshots, Window Switcher, desktop recovery, tiling, and core apps.

### Preferences / Safe Reset

Shortcut: `Ctrl+Alt+,`

Purpose:

- Inspect local AI PC state.
- Copy full local state bundle as JSON.
- Reset first-run hint.
- Collapse or expand HUD and mission dock.
- Clear agent queue, snapshots, handoff receipts, or window layout with confirmation.

## Workflow overlays

### Mission modes

Shortcut: `Ctrl+Alt+Space`

Modes:

- `1` Build / Fix: Files, Terminal, Agent, Command Deck, Notebook.
- `2` Review / Prove: Files, Evidence Vault, Change Control, System, Notebook.
- `3` Research / Map: Agent Browser, Universal Finder, Map Room, Notebook, Agent.
- `4` Operate Agents: Agent Ops, Mission Board, Context Cart, Agent Fleet, Ops Timeline.
- `5` Handoff / Save: Notebook, Handoff, Evidence Vault, Operator Manual, Action Center.

Launching a mode updates the mission dock objective, next action, and mission mode.

### Global agent request bar

Shortcut: `Ctrl+Alt+Enter`

Purpose:

- Capture a task from anywhere.
- `Enter` queues the request.
- `Shift+Enter` opens Agent Ops without queueing.
- Recent requests can be reused.
- Submitted request updates mission dock next action and opens Agent Ops.

Local state:

- `aetherdesk.realPc.agentRequestQueue`

### Agent Queue board

Shortcut: `Ctrl+Alt+Shift+Enter`

Purpose:

- View captured requests.
- Promote a request into mission dock next action.
- Open Agent Ops for the selected request.
- Mark requests done.
- Remove requests.
- Clear completed requests.

Keyboard:

- Arrows select.
- `Enter` uses selected request.
- `Space` marks done.
- `Delete` / `Backspace` removes.
- `Escape` closes.

## Proof and handoff

### Copy handoff

Shortcut: `Ctrl+Alt+Shift+C`

Purpose:

- Copies a markdown handoff receipt.
- Includes timestamp, mission mode, objective, next action, notes, open windows, and core controls.
- Stores recent receipt history locally.

Local state:

- `aetherdesk.realPc.handoffReceipts`

### Black-box snapshot recorder

Shortcuts:

- `Ctrl+Alt+Shift+S`: record and copy snapshot.
- `Ctrl+Alt+Shift+V`: open snapshot viewer.

Snapshot captures:

- URL.
- viewport.
- mission dock state.
- agent request queue.
- handoff receipt metadata.
- open window titles/states/sizes.
- local `aetherdesk.realPc.*` state keys.

Local state:

- `aetherdesk.realPc.blackBoxSnapshots`

## Window and desktop control

### Desktop navigation

- Arrow keys move across visible desktop icons.
- `Home` / `End` jump first/last icon.
- `Enter` opens focused icon or Start row.
- Start menu supports ArrowUp, ArrowDown, Home, End, and Enter.

### Window switcher

Shortcut: `Ctrl+Alt+Tab`

Purpose:

- Shows open windows.
- Includes parked/minimized windows.
- Arrows select.
- `Enter` activates selected.
- `Escape` closes.

### Desktop recovery

Shortcuts:

- `Ctrl+Alt+Home`: park open windows / show desktop.
- `Ctrl+Alt+End`: restore parked windows.

### Keyboard window tiling

Shortcuts:

- `Ctrl+Alt+ArrowLeft`: snap active window left.
- `Ctrl+Alt+ArrowRight`: snap active window right.
- `Ctrl+Alt+ArrowUp`: maximize active window.
- `Ctrl+Alt+ArrowDown`: center active window.

## Preview and loading notes

The file preview path needs relative shell assets, not root-absolute paths:

- `real-pc-shell.css?v=21`
- `real-pc-shell.js?v=21`

This is important for `file://` preview behavior.

## Compact screen policy

For short or narrow screens, the shell biases toward daily-driver PC behavior:

- Hide/collapse nonessential widget surfaces.
- Keep desktop icons scrollable instead of clipped.
- Prioritize Files, Terminal, Notebook, Command Deck, Agent Ops, Browser, System, Manual, and Action Center.
- De-emphasize concept/evaluation tools instead of removing them.
- Keep taskbar, Start menu, help overlays, queue boards, and snapshot viewers compact.

## Offline-first backend sync policy

The request queue is local-first.

When served over `http://` or `https://`, the sync bridge attempts to promote unsynced requests to backend tasks via:

- `POST /api/pc/agent-task`

When opened through `file://`, sync status becomes `local-preview`; the desktop keeps operating without backend errors.

Manual sync:

- `Ctrl+Alt+Shift+U`
- click sync pill

## Main localStorage keys

- `aetherdesk.realPc.session`
- `aetherdesk.realPc.operatorSession`
- `aetherdesk.realPc.operatorSessionCollapsed`
- `aetherdesk.realPc.operatorHintDismissed`
- `aetherdesk.realPc.aiStatusHudCollapsed`
- `aetherdesk.realPc.agentRequestQueue`
- `aetherdesk.realPc.handoffReceipts`
- `aetherdesk.realPc.blackBoxSnapshots`
- `aetherdesk.realPc.backendSyncStatus`
- `aetherdesk.realPc.backendSyncHistory`

## Current resume point

The runtime shell now has the major operator affordances for a local AI PC:

- keyboard-first PC navigation
- compact short-screen layout
- mission/session memory
- mission modes
- global agent request capture
- queue management
- offline-first backend request sync
- handoff receipts
- black-box snapshots
- preferences and safe reset
- control map and quick help
- status HUD and sync pill

Next useful steps:

1. Run a visual/browser pass from a served `http://127.0.0.1` preview.
2. Consolidate appended JS modules into a cleaner internal registry if runtime behavior is confirmed.
3. Wire the backend `/api/pc/agent-task` response shape into the sync bridge if the live API differs from the tolerant parser.
4. Add a first-run guided tour only after visual density is checked.

## Safe Mode / panic recovery

Shortcut: `Ctrl+Alt+Shift+Backspace`

Boot options:

- `?safeMode=1`
- `?aipcSafe=1`

Purpose:

- Quiet the AI-PC chrome without deleting local state.
- Hide the mission dock, AI status HUD, backend sync pill, first-run hint, and widget stack.
- Close transient overlays like Help, Control Map, Mission Modes, Agent Queue, Snapshot Viewer, Preferences, and the request bar.
- Keep the base desktop, icons, windows, Start/search, and taskbar usable.

Local state:

- `aetherdesk.realPc.safeMode`

Use this if the screen gets crowded, a short-screen preview feels cramped, or an operator wants the shell to behave like a plain desktop before re-enabling the agent surfaces.
