# AetherDesk AI PC Developer Handoff

Date: 2026-07-01

Objective: build the best AI PC possible for agentic operations and systems workflows.

This checkpoint summarizes the current AetherDesk AI PC work so a future agent can continue without guessing.

## Core runtime files touched

- `C:\Users\issda\AetherDesk\aetherdesk\public\index.html`
- `C:\Users\issda\AetherDesk\aetherdesk\public\real-pc-shell.css`
- `C:\Users\issda\AetherDesk\aetherdesk\public\real-pc-shell.js`
- `C:\Users\issda\AetherDesk\aetherdesk\public\aetherdesk-ai-pc-manifest.json`

## Runtime direction

The shell is being shaped into a local-first AI PC:

- desktop-first visual model
- keyboard-first operation
- compact short-screen support
- visible mission state
- global operator-to-agent request capture
- local queue management
- mission mode workspaces
- proof/handoff snapshots
- offline-first backend request sync
- safe reset and Safe Mode
- machine-readable control manifest

## Major operator surfaces added

- First-run operator hint
- Keyboard desktop icon navigation
- Start menu keyboard row navigation
- Show-desktop / restore-window shortcuts
- Window switcher
- Quick Help
- Window tiling
- Mission dock
- Mission Mode launcher
- Handoff receipt copy action
- Global agent request bar
- Agent Queue board
- Black-box snapshot recorder and viewer
- AI PC Control Map
- AI PC status HUD
- Preferences / Safe Reset overlay
- Offline-first backend request sync bridge
- Backend sync status pill
- Safe Mode

## Most important shortcuts

- `Ctrl+K`: Start/search
- `F1`: Quick Help
- `F2`: AI PC Control Map
- `Ctrl+Alt+Enter`: Ask the AI PC
- `Ctrl+Alt+Shift+Enter`: Agent Queue
- `Ctrl+Alt+Space`: Mission Modes
- `Ctrl+Alt+.`: Mission dock
- `Ctrl+Alt+Tab`: Window switcher
- `Ctrl+Alt+Home`: Show desktop / park windows
- `Ctrl+Alt+End`: Restore parked windows
- `Ctrl+Alt+Arrow*`: tile active window
- `Ctrl+Alt+Shift+C`: Copy handoff
- `Ctrl+Alt+Shift+S`: Record black-box snapshot
- `Ctrl+Alt+Shift+V`: Snapshot viewer
- `Ctrl+Alt+Shift+U`: Manual backend sync
- `Ctrl+Alt+,`: Preferences
- `Ctrl+Alt+Shift+Backspace`: Safe Mode

## New scripts

- `C:\Users\issda\AetherDesk\scripts\aetherdesk-ai-pc-preview-server.js`
- `C:\Users\issda\AetherDesk\scripts\aetherdesk-ai-pc-launch.ps1`
- `C:\Users\issda\AetherDesk\scripts\aetherdesk-ai-pc-launch.cmd`
- `C:\Users\issda\AetherDesk\scripts\aetherdesk-ai-pc-static-smoke.js`

## New docs

- `C:\Users\issda\AetherDesk\docs\AETHERDESK_AI_PC_OPERATOR_SURFACE.md`
- `C:\Users\issda\AetherDesk\docs\AETHERDESK_AI_PC_ACCEPTANCE_CHECKLIST.md`
- `C:\Users\issda\AetherDesk\docs\AETHERDESK_AI_PC_QUICK_CARDS.md`
- `C:\Users\issda\AetherDesk\docs\AETHERDESK_AI_PC_PREVIEW_RUNBOOK.md`
- `C:\Users\issda\AetherDesk\docs\AETHERDESK_AI_PC_AGENT_MANIFEST.md`
- `C:\Users\issda\AetherDesk\docs\AETHERDESK_AI_PC_DEVELOPER_HANDOFF_2026-07-01.md`

## Validation status

Runtime validation has not been performed in this thread.

Reason: the working rules required no tests or validation unless explicitly requested. The browser automation layer also refused direct `file://` navigation under policy, so a proper visual pass should use the localhost preview server.

Do not claim the runtime is complete until the acceptance checklist has been exercised.

## Static preflight command

When validation is allowed, start with:

```powershell
node C:\Users\issda\AetherDesk\scripts\aetherdesk-ai-pc-static-smoke.js
```

This checks markers, manifest, docs, launchers, preview endpoints, and expected asset paths. It does not prove runtime behavior.

## Localhost preview commands

Start preview:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File C:\Users\issda\AetherDesk\scripts\aetherdesk-ai-pc-launch.ps1
```

Or:

```powershell
node C:\Users\issda\AetherDesk\scripts\aetherdesk-ai-pc-preview-server.js
```

Default preview URL:

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

Safe Mode preview URL:

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

Operator manifest endpoint:

```text
http://127.0.0.1:5717/api/pc/operator-manifest
```

## Current risk areas

1. `real-pc-shell.js` has many appended IIFE modules. This is fast for progress but should eventually be consolidated into a registry/module pattern.
2. Shortcut collisions are possible because many listeners operate at document capture level.
3. Runtime order should be visually checked. Some modules wait for `.real-pc-shell`, but overlay stacking needs real browser testing.
4. Backend sync parser is tolerant, but the live `/api/pc/agent-task` shape must be verified before calling it done.
5. `file://` preview may behave differently from localhost. Prefer `http://127.0.0.1` for actual testing.
6. The UI may be too visually dense on very short screens even with compact and Safe Mode layers.
7. The static smoke script checks markers and paths, not actual event behavior.

## Best next pass

When the user allows validation:

1. Run static smoke.
2. Launch localhost preview.
3. Open `http://127.0.0.1:5717/?resetDesktop=1`.
4. Test squat viewport around `900x520`.
5. Walk the acceptance checklist.
6. Fix only the failures found visually.
7. If runtime looks stable, consolidate appended JS modules into a cleaner internal registry.

## Do not do blindly

- Do not mark the goal complete without a visual/runtime pass.
- Do not remove localStorage keys without user intent.
- Do not kill background processes from scripts; foreground preview with `Ctrl+C` is the safe launcher path.
- Do not assume `file://` behavior equals served preview behavior.
- Do not keep adding hidden shortcuts without updating the manifest and docs.

## Current product sentence

AetherDesk is becoming a local-first AI PC: a desktop-like workspace where the operator can search, open files/terminal/notebook/agent surfaces, capture requests, manage an agent queue, launch mission modes, preserve handoffs and snapshots, sync to backend when available, and recover instantly with Safe Mode.
