# AetherDesk AI-PC operating map

## Prime directive

AetherDesk should feel and operate like a local PC for agentic systems work:

- normal desktop first
- bounded tools second
- agent automation third
- mutation only after visible review gates

## Current repo snapshot

Verified from `C:\Users\issda\AetherDesk` on `2026-07-03 04:54 -07:00`.

This is not a junk-cleanup map. AetherDesk is a live work surface with active product, workflow, runtime, and agent-ops lanes. Treat it as a system to refresh, receipt, and route through bounded commands, not as a deletion candidate.

Current first-class productive lanes visible in the repo:

- `Windows AI App Health`: `npm run aetherdesk:windows-ai-health`, bounded shell profile `windows_ai_app_health`; checks Microsoft account service, Store/AppX services, Codex/Claude package state, CrossDevice quiet state, and AppRepository/IdentityCRL ACL health.
- `Public Self-Serve Action Cards`: `npm run aetherdesk:public-self-serve:actions`, route `GET /api/agent/public-self-serve-action-cards`; stages commercial setup blockers without storing secrets, signing keys, payment keys, or legal attestations.
- `YouTube Studio`: `npm run aetherdesk:youtube:studio`, route `GET /api/agent/youtube-studio`; stages local book-to-episode/movie adaptation packs, video/audio edit plans, scripts, voiceover direction, captions, upload metadata, live-stream planning, and publish receipts while keeping source books/media read-only and OAuth tokens, stream keys, upload consent, external-editor handoffs, and real channel writes outside artifacts.
- `User Quote Library`: `npm run aetherdesk:quote-library`, route `GET /api/agent/user-quote-library`; builds the writing voice bank from bounded exact-path and bounded note-root sources with immutable `original_quote` cards, spelling-fixed `raw_quote`/`corrected_quote` working text, before/after edit receipts, spelling-habit profile, voice palette, theme/search index, style fingerprint, Obsidian/Markdown handoff, source receipts, and fast chapter-use packets for fiction, nonfiction, KDP prep, narration, and YouTube adaptation.
- `Workflow Factory`: `npm run aetherdesk:workflow:factory`, route `GET /api/agent/workflow-factory`; turns rough workflow ideas into reviewable packets with stages, actions, receipts, route/UI plans, and proof plans before promotion.
- `Workflow-making Workflow`: `npm run aetherdesk:workflow:workflow-making-workflow`; materialized local scaffold under `scripts/aetherdesk-workflow-workflow-making-workflow.js` with doc `docs/generated-workflows/workflow-making-workflow.md`. This is artifact-write only until a route, desktop UI, and smoke validator are explicitly promoted.
- `Node Pipeline Studio`: `npm run aetherdesk:node-pipeline:studio`, route `GET /api/agent/node-pipeline-studio`; local graph workflow runtime that writes pipeline JSON, Mermaid diagrams, state, receipts, and graph notes without arbitrary shell nodes or external writes.
- `Biohub Adaptation Engine`: `npm run aetherdesk:biohub:adaptation`; detects whether the Biohub lane needs system growth instead of parameter tuning, then writes adaptation receipts, agent prompt, and action cards under `artifacts/biohub_adaptation_engine`.
- `Biohub Packet Audit`: `npm run aetherdesk:biohub:packet-audit -- --input C:\path\to\submission.csv` or `npm run aetherdesk:biohub:packet-audit:self-test`; turns a Biohub submission packet into GeoSeal voxel/node stats, lattice edge-distance checks, and lineage/division receipts, then writes both `latest-*` pointers and source-stamped archived audit receipts under `artifacts/biohub_adaptation_engine`. Tests use `--out-dir` so self-test receipts do not overwrite the operator-facing latest receipt.
- `Biohub Audit Comparison`: `npm run aetherdesk:biohub:compare-audits -- --candidate <candidate-audit.json> --baseline <baseline-audit.json>`; compares packet-audit receipts and emits a promote/review/no-clear-improvement decision with long-edge, integrity, and risk-flag deltas. It also supports `--out-dir` for temp/test artifact roots.
- `Biohub Submission Pack`: `npm run aetherdesk:biohub:submission-pack -- --submission C:\path\to\submission.csv`; verifies the candidate CSV hash against the candidate audit and comparison receipts, then writes a portable package under `artifacts/biohub_submission_pack` with `submission.csv`, candidate audit, comparison, and manifest files.
- `AI PC Refresh`: `npm run aetherdesk:ai-pc:refresh`, route `GET /api/agent/ai-pc-refresh`; regenerates the central artifact brain in dependency order.

## Main surfaces

- `This PC`: home, readiness, places, explorer, queues, outputs, gates, receipts.
- `Command Palette`: fast search lane for workflows, places, safety tools, and selected-item agent actions.
- `Workspace Explorer`: bounded browsing for known roots.
- `Agent Queue`: selected file/folder to receipt-backed task.
- `Agent Outputs`: reports, plans, and patch proposals.
- `Apply Requests`: review gates from generated outputs.
- `Diff Previews`: preview-only patch scaffolds.
- `Apply Approvals`: final approval receipts.
- `Apply Receipts`: mutation attempts and audit trail.
- `Rollback Receipts`: recovery attempts and backup restore trail.
- `Portable Link`: PWA install state, local/tablet URLs, LAN backend bind state, and wireless-control policy.

## Portable device mode

Default start stays local-only:

```powershell
npm run aetherdesk
```

Trusted-network tablet/phone access is explicit:

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

That sets `AETHERDESK_LAN=1`, binds the server to `0.0.0.0`, and exposes LAN URLs through `GET /api/portable-device`. The same endpoint reports `/manifest.json`, `/sw.js`, install readiness notes, and the remote-control policy.

Important platform boundary: service workers and PWA install prompts generally require HTTPS, localhost, or loopback. A plain `http://192.168.x.x:5717` tablet session is a browser controller and may not be install-quality until an HTTPS/tunnel/pairing layer is added.

Remote devices do not get raw shell by default. They still use the same bounded app routes, browser action routes, agent tasks, receipts, and Change Control gates.

## Workflows

Use the `Command Palette` in `This PC` for fast navigation. Useful searches include:

- `code`
- `SCBE`
- `review`
- `checkpoint`
- `smoke`
- `apply`
- `snapshot`

### Writing desk

Open `Word` plus `AI Desk`.

Use for:

- articles
- docs
- product descriptions
- research notes
- system explanations

### Code desk

Open `Editor` plus `PowerShell`.

Use for:

- implementation
- debugging
- local scripts
- repo operations
- bounded patch work

### Research cockpit

Open `Browser` plus `Notebook`.

Use for:

- web reading
- source gathering
- synthesis
- evidence capture

### Agent operations

Open `AI Desk`, `Terminal`, and `Task Manager`.

Use for:

- agent task supervision
- receipts
- review gates
- system work loops

### System health

Open `System Monitor` plus `Receipts`.

Use for:

- readiness checks
- runtime status
- audit review
- recovery decisions

## Safety ladder

1. Browse bounded workspace.
2. Create agent task with a clear intent.
3. Approve task.
4. Run read-only inspection.
5. Generate report, plan, or patch proposal.
6. Create apply request.
7. Create diff preview.
8. Approve apply.
9. Apply only with explicit enablement and exact confirmation.
10. Roll back only with explicit enablement and exact confirmation.

## Apply mode

Default state is locked.

To enable apply for a process:

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

Even when enabled, apply requires:

- concrete unified diff
- target boundary checks
- exact `APPLY <approval-id>` confirmation
- backup before mutation
- apply receipt after mutation

Rollback requires:

- applied receipt
- complete backup map
- exact `ROLLBACK <apply-receipt-id>` confirmation
- rollback receipt after restore

## Agent task intents

Workspace Explorer exposes these task intents:

- `review`: inspect a selected file or folder and identify useful next steps.
- `map`: summarize structure, important files, and system boundaries.
- `organize`: propose cleanup, grouping, or workflow improvements.
- `implement`: prepare an implementation path through reports, proposals, and gated diffs.

The intent does not bypass safety gates. Every path still goes through receipts, review, diff preview, approval, backup, and rollback rules.

## Recommended validation

Start with locked mode first.

Validate:

- readiness panel
- locked-mode smoke verifier
- workspace explorer
- agent queue
- output creation
- apply request creation
- diff preview creation
- apply approval creation
- locked apply receipt
- locked rollback receipt

Only test enabled apply on a disposable folder and file.

Run the smoke verifier after restart:

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

Or:

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

Disposable apply drill:

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

Enabled disposable apply and rollback drill:

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

Agent-readable manifest:

```text
GET /api/pc/manifest
```

Agent-readable current snapshot:

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

## 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 makes the visual desktop and backend programmatic access inspectable as one system: control modes, `/api/desktop/state`, `/api/desktop/action`, `/api/control/surfaces`, `/api/control/snapshot`, current windows, active target, and external control lanes.

The backend control contract distinguishes observe-only, headless browser, visible-screen, local-tool, GitHub, communication, and gated-mutation modes. Use AetherBrowser headless for repeatable browser state, Computer Use for visible software without clean APIs, AetherDesk APIs for local tool/workspace/task/receipt lanes, and Change Control for mutation.

## Agent OS hook surface pass

The desktop now includes `Model Hub`, `Browser Workbench`, `Tool Dock`, `Renderer Lab`, and `Steady State` apps, plus an `Agent OS` work mode. These apps are registered in the backend desktop app registry, launch from desktop icons, Start, tray buttons, This PC, context menu, and hotkeys, and sync through `/api/desktop/state` like the rest of the shell.

Backend routes added for this pass:

- `/api/app-hooks`: read-only hook manifest for provider lanes, browser control, allowlisted tools, renderer surfaces, steady-state, and safety boundaries.
- `/api/steady-state`: compact pulse for active app, control mode, window counts, provider readiness, queues, attention items, and stable routes.

`Model Hub` reads `/api/providers`, `/api/app-hooks`, and `/api/ai/models`; local Ollama chat stays explicit through `/api/ai/chat`. Remote providers such as OpenAI/GPT, Anthropic/Claude, xAI/Grok, Groq, and Hugging Face are status/hook lanes only here; the UI shows secret presence booleans and never exposes secret values.

`Browser Workbench` is the default browser cockpit and separates `/api/browser/launch` for AetherBrowser startup from `/api/browser/action` for repeatable browser state and screenshots. It exposes `GET /api/aetherbrowser/workbench-readiness` as the first read-only triage route: it summarizes frontdoor/headless health, chooses the recommended lane, and returns executable next-action cards plus a `primary_action` for the next best move. It also exposes `POST /api/aetherbrowser/start` as the explicit local start gate for the AetherBrowser headless backend; backend health and `headless_ready` are separate signals, so a live `/health` response does not make the headless route the recommended lane unless `/headless/capabilities` is reachable. It exposes the SCBE persistent Chrome frontdoor through `GET /api/aetherbrowser/frontdoor`, `POST /api/aetherbrowser/frontdoor/start`, `POST /api/aetherbrowser/frontdoor/open`, `GET /api/aetherbrowser/frontdoor/tabs`, `POST /api/aetherbrowser/frontdoor/focus`, `POST /api/aetherbrowser/frontdoor/guide`, `POST /api/aetherbrowser/frontdoor/inspect`, `POST /api/aetherbrowser/frontdoor/screen`, `POST /api/aetherbrowser/frontdoor/click-text`, `POST /api/aetherbrowser/frontdoor/click-selector`, `POST /api/aetherbrowser/frontdoor/type-text`, `POST /api/aetherbrowser/frontdoor/fill-selector`, `POST /api/aetherbrowser/frontdoor/press-key`, `POST /api/aetherbrowser/frontdoor/workflow`, `GET /api/aetherbrowser/frontdoor/workflows`, `GET/POST /api/aetherbrowser/frontdoor/workflow-library`, and `POST /api/aetherbrowser/frontdoor/workflow-library/:id/run`; GET frontdoor is status-only, POST start/open are explicit operator actions, GET tabs is read-only CDP inventory, POST focus is browser-window focus with a screenshot receipt, POST guide is a read-only control/selector inventory with screenshot evidence, POST inspect/screen are read-only evidence captures, POST click/type/key plus click-selector/fill-selector are bounded browser-only touch actions, POST workflow supports read-only `dry_run` previews plus target/role guide resolution before running bounded guide/action/wait plans with per-step expectation checks, one final receipt, a displayable screenshot data URL, and a structured repair receipt on failure, GET workflows summarizes recent workflow/repair receipts with replayable workflow payloads without touching the browser or loading screenshots, workflow-library saves reusable local templates, and workflow-library `:id/run` previews by default before any explicit saved-template run. It presents the frontdoor/headless lanes as the preferred repeatable path and Computer Use as the visible-screen fallback for real software, legacy UI, simulators, or pages without a clean API.

`Agent Browser` is the operator-facing browser cockpit for the same headless lane. It reads `/api/browser/capabilities` for the tool catalog, `/api/browser/sessions` for active Playwright pages, `/api/browser/session/:session_id?screenshot=1` for snapshots, and `/api/browser/action` for goto, screenshot, text, ARIA, guide, click, hover, type, keypress, scroll, wait, back, forward, reload, and close. Its detachable controller is the Claude-Chrome-style pop-out surface; agents should still prefer the backend routes for repeatability and use the UI as a visible state/receipt surface.

`Tool Dock` reads `/api/commands`, `/api/shell/profiles`, `/api/agent/actions`, and `/api/app-hooks`; command runs still go through allowlisted `/api/run/:command_id` and receipt lanes. `Renderer Lab` maps screenshot/artifact sources into Evidence Vault and Browser Workbench. `Steady State` reads `/api/steady-state` and gives the operator/agent a single heartbeat for whether the system is coordinated.

Window behavior now supports resize grips, titlebar double-click maximize/restore, active-window emphasis, and dynamic grid tiling for larger worksets.

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

The desktop now has four additional first-class apps:

- `Desktop Parity`: reads `/api/desktop-parity` and compares AetherDesk to a real desktop across windowing, launcher/search, taskbar/tray, file manager, bounded terminal/CLI, local LLM, app hooks, voice input, VR/spatial mode, haptics/gamepad, and receipts.
- `CLI Systems`: reads `/api/cli-systems` and docks AetherDesk package scripts, allowlisted `/api/run/:command_id` commands, bounded `/api/shell/run` profiles, SCBE-AETHERMOORE, AetherBrowser, verifier-bench, `C:\dev\CODING_SYSTEMS.md`, `C:\dev\DEV_MAP.md`, and Ollama route pointers.
- `Windows AI App Health`: a bounded `/api/shell/run` profile and `npm run aetherdesk:windows-ai-health` probe for Microsoft account service state, Store/AppX services, Codex/Claude package state, CrossDevice quiet state, and the AppRepository/IdentityCRL ACLs that can break Store installs.
- `PowerShell GitHub forks`: `CLI Systems` reads `/api/powershell/forks` through `/api/cli-systems` and exposes `issdandavis/PowerShellSCBE` as the primary SCBE-specific fork of `PowerShell/PowerShell`, plus `issdandavis/PowerShellForGitHub` as a GitHub API module fork. These are GitHub-backed status/clone-planning lanes until an explicit clone/build/install task is requested.
- `Ollama Hub`: reads `/api/ollama/status`, `/api/ai/models`, and `/api/ai/chat` so the local model runtime has a dedicated status/model/prompt surface separate from remote provider hooks.
- `Immersive Controls`: reads `/api/immersive-controls`, detects browser-native SpeechRecognition, speech synthesis, WebXR, Gamepad API, and Vibration API support client-side, and records control events through `/api/immersive-controls/event`.

The backend now includes an `immersive-control` mode in the control-mode registry. It is read-only by default: VR, voice, gamepad, dwell, and haptic signals can open safe desktop surfaces, toggle hands-free display mode, or record input events, but workspace mutation still requires the normal allowlisted command, task, or Change Control lanes.

The shell also gained an `Immersive Desk` work mode that opens Desktop Parity, Immersive Controls, Ollama Hub, Browser Workbench, and Steady State together. Hands-free mode enlarges controls and strengthens focus outlines for less precise input, while preserving the same API boundaries.

## Feature package

Use the feature package command when AetherDesk needs to hand its full current surface to another agent, release reviewer, or implementation lane:

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

The package is generated from backend exports instead of a static list. It captures desktop app registry, control modes, programmatic routes, app hooks, CLI systems, PowerShell forks, browser capabilities, desktop parity assessment, command allowlist, shell profiles, docs, and recent evidence artifacts.

Programmatic lane:

- Command ID: `feature_package`
- Script: `aetherdesk:feature-package`
- API run route: `POST /api/run/feature_package`
- Output root: `artifacts/feature-packages/`
- Boundary: package/evidence write only; no clone, install, push, deploy, secret read, or external mutation.

## Commerce control-plane pass

The AI PC now has a secret-safe commerce status lane for public-sale and pilot operations.

Headless command:

```powershell
npm run aetherdesk:payments:map
```

Artifact root:

```text
artifacts/aetherdesk_payment_entitlement_map/
```

Programmatic route:

```text
GET /api/agent/payment-entitlement-map
```

The map separates payment channels from entitlement unlocks:

- Website sales use Stripe Checkout/Billing.
- Google Pay and Cash App Pay are website payment methods through Stripe.
- Google Play Billing is separate for Play Store digital unlocks/subscriptions.
- npm and PyPI distribute packages; they do not process payment.
- Manual Cash App is a founder/pilot fallback only and must be converted into a signed entitlement receipt before unlock.

`npm run aetherdesk:ops:digest` now includes the latest payment entitlement map so agents can see whether commerce is ready without reading secrets, calling Stripe, or guessing from docs.

Workflow Library/API action:

```text
payment_entitlement_map
```

This workflow runs `npm run aetherdesk:payments:map` through the existing receipted agent workflow lane with `artifact-write` scope.

## Public self-serve action cards pass

The AI PC now has public self-serve setup cards for the remaining external blockers: code signing, entitlement/license provider, Stripe Checkout/Billing, Google Pay and Cash App Pay through Stripe, Google Play Billing, legal review, npm, PyPI, and manual Cash App founder fallback.

Visual operator entry: open **This PC -> Public Launch**. The same cards are available from the desktop icon, launcher nav, mission card, quick-button strip, and command finder so an agent or human can stage the next public-sale step without hunting through docs.

The pass also writes an auditable launch trail:

- `artifacts/aetherdesk_public_self_serve_action_cards/latest.receipts.json`
- `artifacts/aetherdesk_public_self_serve_action_cards/latest.state.json`

Every card action receives an action/card id, access tier, allowed/denied posture, timestamp, reason, blockers, and boundary. External account writes, sign-ins, money movement, legal attestations, code-signing material, and secret entry are visible but denied until the operator handles them outside artifacts.

Headless command:

```powershell
npm run aetherdesk:public-self-serve:actions
```

Programmatic route:

```text
GET /api/agent/public-self-serve-action-cards
```

Workflow Library/API action:

```text
public_self_serve_action_cards
```

Boundary: external account setup is explicit; secrets, signing keys, payment keys, provider tokens, and legal attestations are never written to artifacts.

## Proof Lab pass

The AI PC now has a Proof Lab map for decomposition, verification, and weak-model evidence.

Headless command:

```powershell
npm run aetherdesk:proof-lab:map
```

Artifact root:

```text
artifacts/aetherdesk_proof_lab_map/
```

Programmatic route:

```text
GET /api/agent/proof-lab-map
```

The map is intentionally evidence-first. It does not run a model, call Colab, or claim a fresh pass. It inventories the local `pokeslice` stack, the Forge Driver and receipt generator, Colab notebook/build artifacts, and any visible `forgerun` JSON. Its buyer-facing story is the core AetherDesk proof pattern:

- weak or naive solver hits a composed-task wall
- the system decomposes into leaf tasks
- each leaf is tested
- the assembled artifact must pass an integration gate
- failed integration becomes a useful refusal receipt rather than a fake green

The Proof Lab map now names the Forge Driver as the structural scaffold for a Layer 2 process verifier. The existing scaffold already covers task-structure decomposition, independent leaf gates, assembly, integration, and useful refusal receipts. It also detects generator-wired verifier hooks in `C:\dev\colab\build_forge_run.py`:

- Temperature oscillation: split best-of-N sampling into low-temperature and high-temperature bands, then mark a chunk fragile when only high-temperature samples pass.
- Confidence span probe: rank the chunk trace by temperature-band fragility and identify the most sensitive span.
- Confidence binary search: recursively split the solved chunk trace and follow the temperature-fragile half until one sensitive chunk remains.

The remaining boundary is live evidence: run the regenerated Colab weak-model notebook for real low/high pass counts, then promote the static binary-search receipt into active perturbation/replay search.

`npm run aetherdesk:ops:digest` now includes the latest Proof Lab map so agents can see the decomposition/verification evidence status in the same brief as release, commerce, support, SCBE bridge, and private-workspace health.

Workflow Library/API action:

```text
proof_lab_map
```

This workflow runs `npm run aetherdesk:proof-lab:map` through the existing receipted agent workflow lane with `artifact-write` scope.

## Container runtime wiring pass

The AI PC now has a container/runtime wiring lane for Docker and Docker-like tools.

Headless command:

```powershell
npm run aetherdesk:containers:map
```

Programmatic route:

```text
GET /api/agent/container-wire-map
```

Workflow Library/API action:

```text
container_wire_map
```

The map treats Docker Desktop, Podman, WSL2, Dev Containers, Dagger, kind/minikube, nerdctl/containerd, and Nix-style shells as wireable runtime lanes. Its policy is local-first and sign-in-light: do not block agents on account setup when useful local work is possible, and ask for sign-in only when private registries, cloud runtimes, pushes, or paid/account-scoped features require it.

## AI PC refresh pass

The AI PC now has a one-command artifact refresh lane for the central operating brain.

Headless command:

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

Workflow Library/API action:

```text
ai_pc_refresh
```

Programmatic latest-receipt route:

```text
GET /api/agent/ai-pc-refresh
```

This runs the safe artifact writers in dependency order: system catalog, systems/workflows map, SCBE bridge, private workspace health, container wire map, sign-in wire map, runtime quickstart, runtime action cards, payment entitlement map, Proof Lab map, public-sale config/readiness/launch kit, YouTube Studio lane, User Quote Library, Node Pipeline Studio, public self-serve action cards, ops digest, ops autopilot, scorecard, objective ledger, mission packet, and agent bootstrap.

Boundary: this refresh does not install runtimes, sign in to providers, store tokens, run Colab, call Stripe, push images, upload videos, publish to YouTube, create clusters, or mutate user workspaces beyond AetherDesk artifact outputs.

During the refresh, child artifact writers receive `AETHERDESK_AI_PC_REFRESH_IN_PROGRESS=1` so the objective ledger can recognize the active refresh cycle before the final refresh receipt has been written. Outside that run, the ledger expects `artifacts/aetherdesk_ai_pc_refresh/latest.json` to exist as evidence.

## Sign-in wiring pass

The AI PC now has a sign-in friction map so agents know when accounts are optional, required, or avoidable.

Headless command:

```powershell
npm run aetherdesk:signin:map
```

Programmatic route:

```text
GET /api/agent/signin-wire-map
```

Workflow Library/API action:

```text
signin_wire_map
```

The policy is hands-free by default: continue with local/public work whenever possible, ask for auth only at account-scoped boundaries, prefer official device-code/browser sign-in when needed, and never store tokens in AetherDesk artifacts.

## Wireable runtime quickstart pass

The AI PC now has compact runtime/sign-in action cards derived from the container and sign-in maps.

Headless command:

```powershell
npm run aetherdesk:runtime:quickstart
```

Programmatic route:

```text
GET /api/agent/runtime-quickstart
```

Workflow Library/API action:

```text
runtime_quickstart
```

The quickstart is the short human/agent action layer: run locally first, avoid Docker sign-in blocks with Podman/WSL/Dev Containers where possible, stage registry/cloud sign-in only at real account boundaries, and keep credentials out of artifacts.

## Runtime action cards pass

The AI PC now has a UI-button-ready runtime action manifest.

Headless command:

```powershell
npm run aetherdesk:runtime:actions
```

Programmatic route:

```text
GET /api/agent/runtime-action-cards
```

Workflow Library/API action:

```text
runtime_action_cards
```

The manifest exposes Docker, Podman, WSL2, Dev Containers, Dagger, local Kubernetes, nerdctl/containerd, Nix, and private-registry boundary cards. Safe probes are marked separately from install/admin, reboot, sign-in, secret, and remote-write actions.

## Auth boundary receipt pass

The AI PC now has an auth-boundary receipt for login screens and account-scoped blockers.

Headless command:

```powershell
npm run aetherdesk:auth:receipt -- --provider=docker_registry --action="private image pull" --fallback="used local Podman build"
```

Programmatic latest route:

```text
GET /api/agent/auth-boundary-receipt
```

Workflow Library/API action:

```text
auth_boundary_receipt
```

The receipt does not sign in or store secrets. It records the exact blocked account-scoped action, the fastest official sign-in path, and the local/public fallback used so work can continue.


## YouTube Studio lane

The AI PC now has a local-first YouTube production lane for adapting books into episodes/movies, scripts, local video/audio edit planning, custom AI voiceover direction, captions, upload metadata, live-stream planning, channel updates, and publish receipts.

Visual operator entry: open **This PC -> YouTube Studio**. The same cards are available from the desktop icon, launcher nav, side rail, mission card, quick-button strip, command finder, and shared action-card panel.

Headless command:

```powershell
npm run aetherdesk:youtube:studio
npm run aetherdesk:youtube:adapt-books
npm run aetherdesk:youtube:episode-pack
npm run aetherdesk:youtube:animatic
npm run aetherdesk:youtube:edit-studio
npm run aetherdesk:youtube:assembly-pack
```

Programmatic route:

```text
GET /api/agent/youtube-studio
GET /api/youtube/edit-plan
GET /api/youtube/assembly-pack
GET /api/youtube/animatic-preview
```

Workflow:

```text
youtube_studio_lane
```

Artifacts:

- `artifacts/aetherdesk_youtube_studio/latest.json`
- `artifacts/aetherdesk_youtube_studio/latest.md`
- `artifacts/aetherdesk_youtube_studio/latest.receipts.json`
- `artifacts/aetherdesk_youtube_studio/latest.state.json`
- `artifacts/aetherdesk_youtube_studio/latest.book-adaptation.json`
- `artifacts/aetherdesk_youtube_studio/latest.book-adaptation.md`
- `artifacts/aetherdesk_youtube_studio/latest.episode-production.json`
- `artifacts/aetherdesk_youtube_studio/latest.episode-production.md`
- `artifacts/aetherdesk_youtube_studio/episode_packs/episode_01/production-pack.json`
- `artifacts/aetherdesk_youtube_studio/episode_packs/episode_01/chapter_draft.md`
- `artifacts/aetherdesk_youtube_studio/episode_packs/episode_01/canon_map.json`
- `artifacts/aetherdesk_youtube_studio/episode_packs/episode_01/continuity_flags.md`
- `artifacts/aetherdesk_youtube_studio/episode_packs/episode_01/shot-list.json`
- `artifacts/aetherdesk_youtube_studio/episode_packs/episode_01/captions.scaffold.srt`
- `artifacts/aetherdesk_youtube_studio/episode_packs/episode_01/animatic-manifest.json`
- `artifacts/aetherdesk_youtube_studio/episode_packs/episode_01/animatic-preview.html`
- `artifacts/aetherdesk_youtube_studio/latest.animatic-manifest.json`
- `artifacts/aetherdesk_youtube_studio/latest.animatic-preview.html`
- `artifacts/aetherdesk_youtube_studio/latest.video-assembly.json`
- `artifacts/aetherdesk_youtube_studio/latest.video-assembly.md`
- `artifacts/aetherdesk_youtube_studio/episode_packs/episode_01/assembly/README.md`
- `artifacts/aetherdesk_youtube_studio/episode_packs/episode_01/assembly/asset-prompts/*.image.txt`
- `artifacts/aetherdesk_youtube_studio/episode_packs/episode_01/assembly/asset-prompts/*.motion.txt`
- `artifacts/aetherdesk_youtube_studio/episode_packs/episode_01/assembly/voiceover/voiceover-master.txt`
- `artifacts/aetherdesk_youtube_studio/episode_packs/episode_01/assembly/voiceover/voiceover-master.ssml`
- `artifacts/aetherdesk_youtube_studio/episode_packs/episode_01/assembly/captions/episode_01.assembly.srt`
- `artifacts/aetherdesk_youtube_studio/episode_packs/episode_01/assembly/captions/episode_01.chapters.txt`
- `artifacts/aetherdesk_youtube_studio/episode_packs/episode_01/assembly/render/render-commands.ps1`
- `artifacts/aetherdesk_youtube_studio/episode_packs/episode_01/assembly/qa/qa-checklist.md`
- `artifacts/aetherdesk_youtube_studio/latest.edit-plan.json`
- `artifacts/aetherdesk_youtube_studio/latest.edit-plan.md`
- `artifacts/aetherdesk_youtube_studio/editing_projects/<media>/README.md`
- `artifacts/aetherdesk_youtube_studio/editing_projects/<media>/edit-plan.json`
- `artifacts/aetherdesk_youtube_studio/editing_projects/<media>/captions/*.draft.srt`
- `artifacts/aetherdesk_youtube_studio/editing_projects/<media>/captions/*.chapters.txt`

Book adaptation behavior: the lane scans bounded manuscript/book roots such as `book-backups`, `aethromoor-novel`, `artifacts/book_making/kdp`, and `artifacts/youtube_studio/scripts`, then stages an 8-episode season plan, movie treatment, trailer pack, AI voiceover script, invideo brief, storyboard prompt, continuity audit prompt, and caption prompt. Source books are read-only and the output is an adaptation plan, not a source manuscript rewrite.

Episode production behavior: the lane materializes the selected episode into a production folder with a narration draft, source profile, canon map, continuity flags, shot list, caption scaffold, and invideo/voice/editor handoff prompts. It follows the story-canon contract (`chapter_draft.md`, `canon_map.json`, `continuity_flags.md`) and avoids direct manuscript dialogue unless explicitly approved.

Animatic behavior: the lane converts the episode pack into a local HTML storyboard/timeline preview with shot timing, caption-aligned narration, prompt slots, and an asset-slot contract. This is a review surface before any image/video generation or upload.

Assembly behavior: the lane converts the animatic and Episode 1 production pack into an editor-ready assembly folder with 16:9 asset prompts, motion prompts, a voiceover master, provider-neutral SSML draft, captions, chapters, render commands, and a QA checklist. This makes the next step concrete for human editors and AI tools while keeping generation providers, voice secrets, and YouTube publishing outside the artifact boundary.

Video/audio editing behavior: the lane scans bounded local media roots such as `Videos`, `Videos\YouTube`, `Downloads`, `Music`, `OneDrive\Videos`, `OneDrive\Pictures`, and `artifacts/youtube_studio/renders`, then creates a non-destructive edit setup for each top media source: project folder, edit-plan JSON, README, ffmpeg command deck, loudness/denoise commands, clean WAV target, review-master target, upload-master target, Shorts draft target, thumbnail frame target, caption scaffold, and chapter scaffold. Source media is read-only and originals are not overwritten. If `ffmpeg` or `ffprobe` are missing, render commands stay blocked and the lane records `winget install Gyan.FFmpeg` as the operator setup command.

Boundary: source rights, canon review, OAuth tokens, client secrets, stream keys, upload consent, voice-provider secrets, external editor handoffs, and real channel writes stay outside artifacts. Agents should keep local adaptation briefs, edit plans, voiceover plans, captions, metadata, and receipts moving until the operator signs in and explicitly consents to video generation, upload, live, or channel writes.


## Workflow factory

The AI PC now includes a workflow-making workflow.

Visual operator entry: open **This PC -> Workflow Factory**. The same cards are available from the desktop icon, launcher nav, side rail, mission card, quick-button strip, command finder, and shared action-card panel.

Headless command:

```powershell
npm run aetherdesk:workflow:factory
```

Programmatic route:

```text
GET /api/agent/workflow-factory
```

Workflow:

```text
workflow_factory
```

Artifacts:

- `artifacts/aetherdesk_workflow_factory/latest.json`
- `artifacts/aetherdesk_workflow_factory/latest.md`
- `artifacts/aetherdesk_workflow_factory/latest.packet.json`
- `artifacts/aetherdesk_workflow_factory/latest.packet.md`
- `artifacts/aetherdesk_workflow_factory/latest.receipts.json`
- `artifacts/aetherdesk_workflow_factory/latest.state.json`

Boundary: proposal-first workflow creation. The factory does not auto-edit server/UI from a rough idea; it creates a reviewable packet with stages, action cards, receipts, route/UI plan, and proof plan.

The factory can also materialize a real local artifact-writing scaffold when explicitly run with `--materialize`. Current generated scaffold:

- Command: `npm run aetherdesk:workflow:workflow-making-workflow`
- Script: `scripts/aetherdesk-workflow-workflow-making-workflow.js`
- Doc: `docs/generated-workflows/workflow-making-workflow.md`
- Boundary: local artifact workflow only; no host-write, no external account writes, and no secrets in artifacts.


## Node Pipeline Studio pass

The AI PC now has a free local node-based workflow builder/runtime lane.

Headless command:

```powershell
npm run aetherdesk:node-pipeline:studio
```

Programmatic route:

```text
GET /api/agent/node-pipeline-studio
```

Visual operator entry: open **This PC -> Node Pipeline**. It stages local graph cards into the terminal lane and can compose linked graph JSON plus bounded graph notes before creating workflow packets.

Boundary: the studio writes local artifacts, Mermaid diagrams, state, and receipts only. It does not run arbitrary shell nodes, store secrets, require sign-in, or mutate external services by default.
