# AetherDesk AI PC: Start Here

Generated: 2026-07-01

This is the short index for the current AI PC work. Use it before changing the shell.

## Current state

AetherDesk has a real-PC operator layer in progress:

- desktop shell assets
- keyboard-first controls
- mission dock
- mission modes
- agent request queue
- handoff receipts
- black-box snapshots
- preferences and Safe Mode
- offline-first backend sync bridge
- manifest and acceptance gates
- validation scaffolding

Important: runtime validation has not been completed. Do not mark the goal complete until a served-preview validation report exists.

## First thing to do next

When validation is allowed, run this sequence:

```powershell
node C:\Users\issda\AetherDesk\scripts\aetherdesk-ai-pc-static-smoke.js
powershell -NoProfile -ExecutionPolicy Bypass -File C:\Users\issda\AetherDesk\scripts\aetherdesk-ai-pc-launch.ps1
node C:\Users\issda\AetherDesk\scripts\aetherdesk-ai-pc-create-validation-report.js --validator "agent" --preview-url "http://127.0.0.1:5717/?resetDesktop=1" --viewports "1280x720,900x520" --backend-mode "static-preview"
```

Then fill the generated report from the actual localhost preview.

## Runtime files

```text
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
```

## Launch files

```text
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
```

Default URL:

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

Safe Mode URL:

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

## Human operator docs

Read in this order:

```text
C:\Users\issda\AetherDesk\docs\AETHERDESK_AI_PC_QUICK_CARDS.md
C:\Users\issda\AetherDesk\docs\AETHERDESK_AI_PC_OPERATOR_SURFACE.md
C:\Users\issda\AetherDesk\docs\AETHERDESK_AI_PC_PREVIEW_RUNBOOK.md
```

## Agent-readable artifacts

```text
C:\Users\issda\AetherDesk\aetherdesk\public\aetherdesk-ai-pc-manifest.json
C:\Users\issda\AetherDesk\aetherdesk\public\aetherdesk-ai-pc-acceptance-gates.json
C:\Users\issda\AetherDesk\aetherdesk\public\aetherdesk-ai-pc-validation-report-template.json
C:\Users\issda\AetherDesk\docs\AETHERDESK_AI_PC_AGENT_MANIFEST.md
```

Served manifest endpoint:

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

## Validation docs and scripts

```text
C:\Users\issda\AetherDesk\scripts\aetherdesk-ai-pc-static-smoke.js
C:\Users\issda\AetherDesk\scripts\aetherdesk-ai-pc-create-validation-report.js
C:\Users\issda\AetherDesk\docs\AETHERDESK_AI_PC_ACCEPTANCE_CHECKLIST.md
C:\Users\issda\AetherDesk\docs\AETHERDESK_AI_PC_ACCEPTANCE_GATES.md
C:\Users\issda\AetherDesk\docs\AETHERDESK_AI_PC_VALIDATION_REPORTS.md
C:\Users\issda\AetherDesk\docs\AETHERDESK_AI_PC_VALIDATION_REPORT_TEMPLATE.md
```

## Engineering handoff and backlog

```text
C:\Users\issda\AetherDesk\docs\AETHERDESK_AI_PC_DEVELOPER_HANDOFF_2026-07-01.md
C:\Users\issda\AetherDesk\docs\AETHERDESK_AI_PC_POST_VALIDATION_BACKLOG.md
C:\Users\issda\AetherDesk\docs\AETHERDESK_AI_PC_REFACTOR_ROADMAP.md
```

## Highest-risk areas

- Many appended JS modules need consolidation after validation.
- Multiple document-level keyboard listeners may collide.
- Overlay stacking needs served-preview testing.
- Short-screen visual density needs real viewport testing.
- Backend sync bridge needs real `/api/pc/agent-task` verification.
- Static smoke proves markers, not behavior.

## Operator emergency order

If the UI feels crowded:

1. `Ctrl+Alt+Shift+Backspace`: Safe Mode.
2. `Ctrl+K`: search for Files, Terminal, Agent, Notebook.
3. `F2`: Control Map.
4. `Ctrl+Alt+Enter`: Ask the AI PC.
5. `Ctrl+Alt+Shift+S`: record snapshot before risky changes.

## Product rule

AetherDesk should feel like a computer first:

- obvious search
- recoverable windows
- visible mission
- fast agent request capture
- local queue
- proof before handoff
- safe reset when crowded

Do not add more runtime surfaces until the served-preview validation gates have evidence.

## One-command validation prep

When validation is allowed, this runs static smoke and creates a dated validation report scaffold:

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

To also launch the foreground localhost preview after the preflight:

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

Safe Mode preview:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File C:\Users\issda\AetherDesk\scripts\aetherdesk-ai-pc-validation-next.ps1 -LaunchPreview -SafeMode
```
