# 99Pages Agentic OS V3 Deployment Plan

This plan turns V3 into the commercial control layer without rewriting Cockpit
as a monolith. Core CLI and Sub CLI come first. Each MCP can later expose its
own HTML5 UI and be opened on demand; Cockpit is the entry/projection layer over
those local MCP apps.

## Deployment Principles

- Keep Core CLI/SubCLI as the execution layer and login/session owner.
- Keep Cockpit and app.99pages.uk as projection surfaces.
- Keep each MCP independent and locally operated.
- Do not require every MCP to have HTML5 UI; default to capability-only modules.
- User-requested custom MCP UIs are user-supplied and use user-owned tokens.
- Keep run events as the single source of truth for progress.
- Keep MCP, Skill, Plugin, and Mini App as one capability registry.
- Keep provider/model details behind AI Workforce policy.
- Do not burn USB builds until the local PWA and CLI bridge pass smoke tests.

## Phase 0: Freeze Commercial Boundaries

Status: ready to execute.

- Confirm V1 USB delivery remains stable while V3 evolves.
- Confirm USBLock-Pro passphrase/vault is not in the commercial 99Pages USB UX.
- Confirm Magic Link, local Keybox, and USB/device binding are the default flow.
- Confirm app.99pages.uk is remote user dashboard, not local Cockpit.
- Confirm portal.99pages.uk is admin/SubAdmin only.
- Confirm hidden relay/bridge endpoints are never shown in human-facing UI.

Exit gate:

- Release checklist states these boundaries.
- No source code or provider secrets are copied into portable media.

## Phase 1: Core CLI Bridge

Status: next implementation target.

The bridge is a local HTTP/WebSocket adapter over deterministic `99p` commands.
It is not a second agent runtime and it is not a bash editor.

Required bridge actions:

- `run.create`: create a Core CLI run.
- `run.list`: list recent runs.
- `run.events`: stream durable JSONL events.
- `mcp.audit`: inspect the installed MCP registry.
- `mcp.manifest`: return the Core CLI source-of-truth MCP manifest.
- `mcp.status`: inspect local MCP app lifecycle state.
- `mcp.start`: start one local MCP app runtime.
- `mcp.stop`: stop one local MCP app runtime.
- `mcp.open`: open one MCP's optional HTML5 projection.
- `mcp.tools`: list module tools.
- `mcp.call`: call approved module tools.
- `subcli.spawn`: spawn a SubCLI task.
- `subcli.result`: fetch/wait for a SubCLI result.
- `telegram.status`: inspect the background poller.
- `telegram.start`: start controlled long polling.
- `telegram.stop`: stop controlled long polling.
- `health.check`: run deterministic checks and route scoring through the hidden
  internal health tier.

Exit gate:

- Browser disconnect does not kill active runs.
- All mutating actions produce approval events unless pre-authorized.
- Bridge logs stay under `.agentic-os/logs`.

## Phase 2: MCP-Native Cockpit Projection

Status: HTML5 can lag the CLI. First make every MCP independently callable.
Only add per-MCP HTML5 views where they pay for themselves.

The first screen is a launcher/projection index, not a second runtime:

- MCP manifest and status, including `ui_kind`.
- Active runs and approvals from the event stream.
- Open buttons only for MCPs that advertise an `open_url`.
- Core CLI prompt projection.
- Telegram remote-control status.

Exit gate:

- `http://127.0.0.1:<port>/` opens local Cockpit, not app.99pages.uk.
- The install link carries any required local access token.
- The UI can refresh without losing active run state.

## Phase 3: Optional UI Registry

Status: seed in `configs/panel_registry.json`.

Every MCP capability should be registered once. UI is optional and explicitly
declared:

- `ui_kind: none`: capability-only MCP; no maintained HTML5 surface.
- `ui_kind: bundled`: 99Pages-maintained local HTML5 surface.
- `ui_kind: user_supplied`: customer/team-owned HTML5 surface, created with
  user-owned tokens and connected through the Core CLI bridge.

High-frequency apps may get bundled views, but they still use the same
capability registry.

Required panels:

- Health Score.
- Core Chat.
- Web Terminal.
- Runs.
- MCP Market.
- Agents.
- Wiki/Library.
- Mini App Builder.
- Devices.
- Settings.
- Virtual Desktop.

Exit gate:

- No panel hard-codes a raw provider.
- No panel owns duplicate business logic.
- No MCP is forced to ship a UI.
- Each panel maps to CLI commands, MCP tools, or run events.

## Phase 4: Telegram Progress Projection

Status: long polling and agent loop are verified; event projection still needs
acceptance.

Telegram must mirror the same run progress users see in Core CLI and Cockpit:

- User input accepted.
- Run created.
- Agent selected.
- Step started.
- Tool called.
- Tool result summarized.
- Approval required when needed.
- Run completed or failed.

Exit gate:

- A real Telegram task produces more than a final answer.
- The bot can report product name, version, copyright, and capability summary.

## Phase 5: Mini App Builder

Status: design accepted, implementation after bridge/panel registry.

Each generated Mini App uses:

- HTML5/PWA route.
- SQLite database.
- Capability manifest.
- Optional chatbot panel connected to Core CLI/SubCLI.
- Export path for HTML and spreadsheet artifacts.

Exit gate:

- A sample Mini App can be created, opened, written to SQLite, and listed in the
  MCP Market.

## Phase 6: Cross-Platform Packaging

Status: final gate before USB burn.

- Windows: PowerShell/Core CLI.
- macOS: shell adapter/Core CLI.
- Linux/VPS: shell adapter/Core CLI.
- Remote-control browser: PWA only.

Exit gate:

- Compiled artifacts exist for Windows, macOS, and Linux.
- USB/SSD mode uses the same portable structure.
- Local test passes before writing to E:.
