# AetherDesk AI-PC handoff

This handoff records the current AI-PC spine added to the classic AetherDesk desktop.

## Current shape

- `This PC` is the main PC-like home surface.
- `Command Palette` is the fast lane for workflows, places, safety tools, and selected-item agent actions.
- Desktop icons use PC semantics: single-click selects, double-click opens.
- Right-click desktop menu exposes PC actions.
- Workspace explorer is bounded to named roots: AetherDesk, SCBE-AETHERMOORE, Avalon Notes, LocalOnly.
- Agent Queue creates receipt-backed tasks from selected files/folders.
- Workspace Explorer can create intent-specific tasks: review, map, organize, implement.
- Agent Outputs stores generated reports, plans, and patch proposals.
- Apply Requests gate outputs before any mutation.
- Diff Previews create preview-only patch scaffolds.
- Apply Approvals record the final approval latch.
- Apply Receipts record locked/refused/failed/applied attempts.
- Rollback Receipts record backup restore attempts.
- AI-PC Readiness shows online, locked, and restart-required subsystem state.
- `Portable Link` shows PWA install state, localhost/tablet URLs, service worker status, and LAN backend policy.

## Safety model

- File browsing is bounded to named workspace roots.
- Agent work starts as receipts and artifacts.
- Mutation is locked unless `AETHERDESK_ENABLE_APPLY=1`.
- Apply requires exact confirmation: `APPLY <approval-id>`.
- Rollback requires exact confirmation: `ROLLBACK <apply-receipt-id>`.
- Unified diff paths must stay inside the selected target boundary.
- Backups are written before an enabled apply.
- Rollback restores recorded backups only.

## Restart

Use the safe restart helper:

```powershell
powershell -ExecutionPolicy Bypass -File "C:\Users\issda\AetherDesk\scripts\aetherdesk-restart-safe.ps1"
```

Or use the package script:

```powershell
npm run aetherdesk:restart
```

To start with the apply runner enabled:

```powershell
powershell -ExecutionPolicy Bypass -File "C:\Users\issda\AetherDesk\scripts\aetherdesk-restart-safe.ps1" -EnableApply
```

Or:

```powershell
npm run aetherdesk:restart:apply
```

For trusted-network tablet or phone access, start the LAN backend deliberately:

```powershell
npm run aetherdesk:lan
```

Then open `Portable Link` or `GET /api/portable-device` for the actual LAN URLs. Plain LAN HTTP is useful as a wireless controller, but install/service-worker behavior generally needs localhost/loopback or HTTPS.

## Next validation

- Restart AetherDesk.
- Open `http://127.0.0.1:5717/`.
- Open `This PC`.
- Open `Portable Link`.
- Refresh AI-PC Readiness.
- Inspect the current AI-PC snapshot:

```text
GET /api/pc/snapshot
```

- Run the locked-mode smoke verifier:

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

Or:

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

- Run the disposable apply drill in locked mode:

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

- After restarting with apply enabled, run the enabled apply/rollback drill:

```powershell
npm run aetherdesk:ai-pc:drill:apply
```

- Verify workspace explorer, agent queue, outputs, apply gates, diff previews, approvals, apply receipts, and rollback receipts report online or locked as expected.
- Only test enabled apply on a disposable file inside a disposable workspace path.

## Real PC shell pass

The landing page now loads `real-pc-shell.css` and `real-pc-shell.js` as a full-screen AetherDesk AI PC shell before the older app surface: desktop icons, single-click selection, double-click open, draggable/maximizable/minimizable windows, Start menu, taskbar/tray, right-click desktop context menu, clock, command drawer, notebook, Files, This PC, Agent Ops, System, and Handoff windows.

Keyboard behavior: Ctrl+K or Ctrl+Space opens Start search. Enter opens the focused desktop icon or the first Start result. Escape closes Start/context menus.

This is intentionally an overlay shell, so the preview immediately reads as a computer even if the backend process is stale. Backend-powered panes still report restart/API state honestly.

## PC affordance pass

The shell now has desktop widgets, toast notifications, titlebar snap-left/snap-right controls, Start power actions for checkpoint/snapshot flow, and direct hotkeys for Agent Ops, Files, Terminal, and System. Agent Ops also exposes quick task buttons that use the currently selected file/folder when available.

## Resume and work modes pass

The shell now stores a local desktop session in browser localStorage under `aetherdesk.realPc.session`, including open windows, window geometry, minimized/maximized state, active window, selected workspace root/path, and selected file metadata. On reload it restores the prior desktop instead of always returning to a blank landing state.

Work modes were added for Writing Desk, Code Cockpit, Research Room, Agent Operations, and System Bench. They can be launched from desktop widgets, Start search, or This PC, and they open/snap the relevant native windows into a useful layout.

## Agent workbench pass

Agent Ops now behaves like a native job board. It can create tasks from the selected file/folder or a typed target, shows online counts for the major workflow lanes, renders recent task/output cards, and renders receipt lanes for apply requests, diffs, approvals, apply receipts, rollback receipts, and session checkpoints. This keeps agent work visible while preserving the backend approval/apply gates.

## Map Room pass

The desktop now includes a `Map Room` app. It is a native systems-workflow view that exposes workspace roots, work modes, the agentic route from context to task to receipts to gated apply/rollback, and launch buttons for Files, Agent Ops, Terminal, Research Room, and Agent Operations. Roots can be opened directly in Files or sent into a `map` task when the backend route is available.

## Action Center pass

The desktop now includes an `Action Center` app and tray button. Notifications are persisted in browser localStorage under `aetherdesk.realPc.notifications` and shown in a native notification history. Action Center also includes operator runbooks for reviewing a system, mapping a workspace, organizing files, implementing safely, and checkpoint/handoff. Runbooks open the right work mode and create agent tasks through the existing task route when available.

The Action Center hotkey is Ctrl+Alt+X.

## Command Deck pass

The desktop now includes a `Command Deck` app, tray button, Start/footer launch, and Ctrl+Alt+D hotkey. It accepts short operator commands such as `map this workspace`, `review selected`, `open code cockpit`, `checkpoint`, or `show action center`, then routes them into existing apps, work modes, session checkpoint/snapshot flow, or agent task creation.

Command history is persisted locally in browser localStorage under `aetherdesk.realPc.commandHistory`. The router is intentionally bounded and deterministic: it does not execute arbitrary shell text; it maps recognized operator intent into the existing AetherDesk surfaces and safety gates.

## Pinboard and desktop shortcut pass

The desktop now includes a `Pinboard` app, tray button, Start/footer launch, and desktop shortcut generation for pinned targets. Pins are persisted in browser localStorage under `aetherdesk.realPc.pins` and can represent workspace roots, folders, files, or reusable agent targets.

Pins appear as desktop icons and can be opened like shortcuts. Pinboard cards can open a target or create review/map/organize agent tasks from that target. Files, Agent Ops, Map Room, and Command Deck can all create pins from the current context. The Command Deck understands phrases like `pin this`, `pin current`, `save shortcut`, `open pinboard`, and `show pins`.

## Control Panel pass

The desktop now includes a `Control Panel` app, tray button, Start/footer launch, This PC launch, System Bench placement, and Ctrl+Alt+P hotkey. It manages browser-local AetherDesk shell state and reports backend safety status when `/api/pc/manifest` is reachable.

Control Panel can export the local brain JSON for `aetherdesk.realPc.session`, `aetherdesk.realPc.notifications`, `aetherdesk.realPc.commandHistory`, `aetherdesk.realPc.pins`, and `aetherdesk.realPc.note`. It can clear those browser-local shell records individually. These controls do not delete repository files or workspace files.

Command Deck now routes `control panel` and `settings` into this app.

## Status Spine pass

The desktop now includes a `Status Spine` app, desktop icon, tray button, mission-widget summary, System Bench placement, This PC launch, Control Panel launch, and Ctrl+Alt+H hotkey. It checks existing AetherDesk routes client-side and summarizes health, manifest/snapshot/workspace reachability, agent task/output counts, apply request/diff/approval/receipt/rollback/checkpoint counts, apply-lock posture, and local shell counts for pins, command history, notifications, and open windows.

The Status Spine refreshes on boot and approximately every 30 seconds while the shell is open. It does not restart the backend, mutate files, or prove runtime correctness by itself; route failures are shown as restart/backend attention items so the operator can choose when to restart around other agents.

Command Deck now routes `status`, `health`, and `status spine` into this app.

## Workflow Library pass

The desktop now includes a `Workflow Library` app, desktop icon, tray button, Start/footer launch, ops/system work mode placement, and Ctrl+Alt+L hotkey. It provides bounded recipes for reviewing the current system, mapping a workspace, organizing a target, implementing safely, checkpoint/handoff, and staging the safe apply drill command.

Recipe history is persisted locally under `aetherdesk.realPc.workflowHistory` and included in Control Panel export/clear controls. Recipes are deterministic and bounded: they open work modes, create agent tasks through `/api/pc/agent-task` when available, save checkpoints through the checkpoint route, or stage known terminal commands. They do not execute arbitrary shell text or bypass the apply approval gates.

Command Deck now routes `workflow library`, `workflows`, `recipes`, and recipe names such as `review current system`, `map workspace`, `implement safely`, and `safe apply drill`.

## Briefing Room pass

The desktop now includes a `Briefing Room` app, desktop icon, tray button, Start/footer launch, Research/Ops/System work mode placement, and Ctrl+Alt+B hotkey. It generates copyable agent handoff briefs from the current AI PC state: current target, Status Spine route/apply posture, local pins, recent workflow runs, recent commands, recent notifications, failed route attention items, and suggested next operator moves.

Brief history is persisted locally under `aetherdesk.realPc.briefHistory`, included in Control Panel export/clear controls, and counted by Status Spine. Command Deck now routes `briefing room`, `briefing`, `brief`, `handoff brief`, `generate brief`, and `make brief` into this app/flow.

Briefs are context packets for humans and agents; they do not prove runtime readiness. Use Status Spine, manifest/snapshot routes, and explicit validation when a claim needs proof.

## Agent Fleet pass

The desktop now includes an `Agent Fleet` app, desktop icon, tray button, Start/footer launch, Agent Operations work mode placement, and Ctrl+Alt+G hotkey. It exposes role cards for Reviewer, Mapper, Organizer, Implementer, Repair Agent, and Handoff Writer. Each role creates a visible `/api/pc/agent-task` item against the current target when the backend task route is available.

Fleet shortcuts include `review + map` and `full scout` crews. Fleet history is persisted locally under `aetherdesk.realPc.fleetHistory`, included in Control Panel export/clear controls, counted by Status Spine, and included in Briefing Room handoff packets.

Command Deck now routes `agent fleet`, `fleet`, `crew`, `full scout`, `review and map`, and `review + map` into this app/flow. Fleet launches create tasks and history only; they do not bypass output, diff preview, approval, apply, backup, or rollback gates.

## Ops Timeline pass

The desktop now includes an `Ops Timeline` app, desktop icon, tray button, Start/footer launch, Agent Operations/System Bench work mode placement, and Ctrl+Alt+O hotkey. It builds a chronological local activity trail across notifications, Command Deck history, Workflow Library runs, Briefing Room briefs, Agent Fleet launches, Pinboard pins, and Status Spine refreshes.

Ops Timeline can copy the local activity trail to the clipboard, is counted by Status Spine, and is included in Briefing Room generated briefs. Command Deck now routes `ops timeline`, `timeline`, `activity log`, and `activity` into this app.

The timeline is a browser-local operator trail. Backend task/output/apply receipt details still live in Agent Ops/Status Spine and should be inspected there when proof is required.

## Context Cart pass

The desktop now includes a `Context Cart` app, desktop icon, tray button, Start/footer launch, Research/Agent Operations work mode placement, and Ctrl+Alt+Q hotkey. It collects multiple roots, folders, files, pins, or workflow targets into a browser-local multi-target basket persisted under `aetherdesk.realPc.contextCart`.

Targets can be added from Files, Agent Ops, Map Room roots, Pinboard cards, and Command Deck phrases such as `add to cart`, `cart this`, and `add current to cart`. Context Cart can create one task per item for review/map/organize/summarize/repair/implement, or launch review+map/full-scout crews across all cart items.

Context Cart is included in Control Panel export/clear controls, counted by Status Spine, listed in Briefing Room handoff packets, and shown in Ops Timeline. Batch actions create visible task requests only; they do not execute arbitrary shell text or bypass output, diff preview, approval, apply, backup, or rollback gates.

## Mission Board pass

The desktop now includes a `Mission Board` app, desktop icon, tray button, Start/footer launch, Agent Operations work mode placement, and Ctrl+Alt+M hotkey. Missions bind an objective to the current target, current Context Cart items, status, and progress notes so the AI PC has a durable center of gravity for daily-driver systems work.

Missions are persisted locally under `aetherdesk.realPc.missions`, included in Control Panel export/clear controls, counted by Status Spine, listed in Briefing Room handoff packets, and shown in Ops Timeline. Mission cards can mark active/waiting/done, add progress notes, launch a review+map fleet, start the review workflow, or generate a mission brief.

Command Deck now routes `mission board`, `mission`, `missions`, `create mission`, and `new mission` into this app/flow. Mission actions organize context and create visible tasks/briefs only; they do not mutate workspace files or bypass apply gates.

## Evidence Vault pass

The desktop now includes an `Evidence Vault` app, desktop icon, tray button, Start/footer launch, Agent Operations/System Bench work mode placement, and Ctrl+Alt+V hotkey. It captures local evidence snapshots that bundle Status Spine state, current target, missions, Context Cart, pins, Ops Timeline, and a generated evidence brief.

Evidence snapshots are persisted locally under `aetherdesk.realPc.evidenceHistory`, included in Control Panel export/clear controls, counted by Status Spine, listed in Briefing Room handoff packets, and shown in Ops Timeline. Command Deck routes `evidence vault`, `evidence`, `proof`, `capture evidence`, `evidence snapshot`, and `proof packet` into this app/flow.

Evidence Vault helps distinguish claims from evidence, but it does not replace explicit validation. Backend outputs, apply receipts, rollback receipts, and checkpoint details should still be inspected through Agent Ops/Status Spine when a claim needs proof.

## Change Control pass

The desktop now includes a `Change Control` app, desktop icon, tray button, Start/footer launch, Agent Operations/System Bench work mode placement, and Ctrl+Alt+Y hotkey. It inspects the gated mutation lanes for apply requests, diff previews, approvals, apply receipts, rollback receipts, and session checkpoints using the existing `/api/pc/*` routes when the backend is reachable.

Change Control renders the mutation ladder as Request -> Diff preview -> Approval -> Apply receipt -> Rollback receipt, reports lane reachability/counts, links to Agent Ops/Evidence Vault/Terminal, and can stage the known safe apply drill command in Terminal. It does not approve, apply, or rollback by itself.

Command Deck now routes `change control`, `apply center`, `apply lane`, `diff preview`, `rollback`, and `approval` into this app. Briefing Room suggested next steps now point mutation/proof work toward Change Control. This keeps file mutation visually separated from ordinary task creation and preserves the approval/apply/backup/rollback boundary.

## Operator Manual pass

The desktop now includes an `Operator Manual` app, desktop icon, tray button, Start/footer launch, System Bench work mode placement, and Ctrl+Alt+/ hotkey. It provides an in-shell directory of native apps, one-click app launch cards, work mode summaries, hotkeys, local storage keys, and core safety/proof boundaries.

Command Deck now routes `operator manual`, `manual`, `help`, `hotkeys`, and `shortcuts` into this app. The manual is intentionally local and non-mutating; it improves discoverability and operator confidence without touching backend state or workspace files.

## Universal Finder pass

The desktop now includes a `Universal Finder` app, desktop icon, tray button, Start/footer launch, Research Room work mode placement, and Ctrl+Alt+I hotkey. It searches across native apps, work modes, pins, Context Cart items, missions, Evidence Vault snapshots, Briefing Room briefs, Workflow Library runs/recipes, Agent Fleet history, Command Deck history, notifications, and Ops Timeline events.

Finder results can open apps/work modes, open pins, run workflow recipes, or open cart targets in Files. Command Deck now routes `universal finder`, `finder`, `find`, and `search` into this app. Universal Finder is local and non-mutating; it improves recall and navigation across the growing AI PC cockpit.

## Control Bridge pass

The desktop now includes a `Control Bridge` app, tray button, Start/footer launch, System Bench placement, and Ctrl+Alt+Z hotkey. It is the visual/programmatic coordination room: the shell posts live window state to `/api/desktop/state`, reads `/api/control/surfaces` and `/api/control/snapshot`, and shows control modes, programmatic routes, open windows, and external surfaces such as AetherBrowser headless and Computer Use.

The backend now exposes `/api/control/surfaces`, `/api/control/snapshot`, and guarded `/api/control/action`. `/api/desktop/state` accepts the real PC shell apps, layout, active target, viewport, and control mode so an agent can read the same desktop state the operator sees. Loop-safe browser controls such as wait/scroll/reload/back/forward now return a virtual no-op when no browser session exists instead of hanging on Playwright startup.

## Agent OS hook surface pass

Implemented the first coordinated visual/backend Agent OS layer:

- New desktop apps: `Model Hub`, `Browser Workbench`, `Tool Dock`, `Renderer Lab`, and `Steady State`.
- New work mode: `Agent OS`, arranging Steady State, Model Hub, Browser Workbench, Tool Dock, Renderer Lab, and Control Bridge.
- New backend routes: `/api/app-hooks` and `/api/steady-state`.
- Updated Status Spine/System checks to include app hooks, steady state, provider status, commands, and shell profiles.
- Window manager polish: resize handles, active-window border, titlebar double-click maximize/restore, and better dynamic tiling for larger worksets.

Important boundaries:

- Headless/repeatable browsing uses `/api/browser/action` and AetherBrowser headless surfaces where available.
- Visible-screen work belongs to Computer Use when a real UI, simulator, or legacy app has no clean API.
- LLM provider integration is hook/status-first. OpenAI/GPT, Anthropic/Claude, xAI/Grok, Groq, Hugging Face, Ollama, and LM Studio lanes are discoverable through `/api/app-hooks` and `/api/providers`, but remote calls are not auto-sent from the new UI.
- Tool runs still go through allowlisted `/api/run/:command_id`, `/api/shell/profiles`, `/api/shell/run`, agent routes, and receipt lanes.

## Desktop parity, CLI, Ollama, and immersive controls pass

Added the next Agent OS layer:

- New apps: `Desktop Parity`, `CLI Systems`, `Ollama Hub`, and `Immersive Controls`.
- New work mode: `Immersive Desk`, arranging Desktop Parity, Immersive Controls, Ollama Hub, Browser Workbench, and Steady State.
- New backend routes: `/api/desktop-parity`, `/api/cli-systems`, `/api/ollama/status`, `/api/immersive-controls`, and `/api/immersive-controls/event`.
- New control mode: `immersive-control`.
- New hands-free display mode: larger controls and stronger focus outlines toggled from Immersive Controls.

Important boundaries:

- `CLI Systems` exposes package scripts, command allowlist, shell profiles, and known local system paths; it does not create a raw arbitrary shell lane.
- `Ollama Hub` is the first-class local model surface; `/api/ollama/status` returns a useful payload even when Ollama is offline.
- `Immersive Controls` uses browser/device APIs when available: SpeechRecognition, speech synthesis, WebXR, Gamepad, and Vibration. Voice phrases can open safe desktop surfaces or stage work; they do not bypass task, command, or Change Control gates.
- Haptic/gamepad events are recorded as action-log entries through `/api/immersive-controls/event` for now. Real hardware bindings should be added after device probing.

## Agent Browser Playwright pass

Added the first full browser app surface:

- New desktop app: `Agent Browser`, a Playwright-backed browser window with address bar, stable session ID, screenshot viewport, session rail, and detachable controller panel.
- New backend routes: `/api/browser/capabilities`, `/api/browser/sessions`, and `/api/browser/session/:session_id`, alongside the existing `/api/browser/action` and `/api/browser/launch`.
- Updated app hooks, steady state, renderer sources, control surfaces, worksets, hotkeys, hands-free routing, and desktop state so the visual browser and programmatic browser lane report the same control model.

Important boundaries:

- Use `Agent Browser` and `/api/browser/action` when an agent needs repeatable browsing, screenshots, page text, ARIA snapshots, selectors, clicks, typing, scrolling, history, or receipts.
- Use `Browser Workbench` as the route/catalog/reference surface for browser integrations.
- Use Computer Use when the task requires real visible software, simulator windows, legacy UI, or a browser page that cannot be driven reliably through Playwright/headless routes.

## PowerShell GitHub fork lane

Added the user's PowerShell forks into the AetherDesk CLI/tool map:

- Primary fork: `issdandavis/PowerShellSCBE`, forked from `PowerShell/PowerShell`, description `PowerShell for every system! SCBE specific`.
- Secondary fork: `issdandavis/PowerShellForGitHub`, forked from `microsoft/PowerShellForGitHub`.
- New backend route: `/api/powershell/forks`.
- `CLI Systems` now shows both forks, their GitHub URLs, parent repos, planned clone paths under `C:\dev`, and buttons for GitHub status, opening the repo, and staging a clone command.

Important boundary:

- These forks are read/status and clone-planning lanes by default. AetherDesk does not clone, build, install, or replace the host PowerShell runtime unless a later explicit task asks for that operation.

## Feature package pass

AetherDesk can now emit a complete feature handoff package from the live backend registry:

```powershell
npm run aetherdesk:feature-package
```

The package is written under `artifacts/feature-packages/aetherdesk-feature-package-<timestamp>` with a matching `.zip` when PowerShell `Compress-Archive` succeeds. It includes `manifest.json`, `feature-lanes.json`, CSV catalogs for desktop apps, commands, and programmatic routes, selected docs, and recent benchmark/screenshot evidence.

The same generator is exposed through the allowlisted `feature_package` command in `/api/commands` and `/api/run/feature_package`. It writes package artifacts only; it does not clone, push, install, deploy, read secrets, or mutate external repositories.
