# V3 System Deployment Guide

## Deployment Model

V3 runs locally first. Cloud and HTML5 surfaces project the local runtime.

```text
Core CLI
  -> TUI / PowerShell
  -> MCP registry
  -> events and approvals
  -> app.99pages.uk projection
```

## Supported Platforms

- Windows: PowerShell UTF-8 required.
- macOS: shell + Homebrew recommended.
- Linux: shell + apt/dnf/yum/apk depending on distro.

## Startup Flow

Burn-ready packages include all platform binaries plus auto-detect launchers.

Windows:

```powershell
.\99p.cmd doctor
.\99p.cmd bootstrap
.\99p.cmd tui
```

macOS/Linux:

```bash
chmod +x ./99p.sh
./99p.sh doctor
./99p.sh bootstrap
./99p.sh tui
```

Direct binary flow:

```powershell
99p doctor
99p bootstrap
99p tui
```

Use `99p bootstrap --yes` only when the operator wants V3 to attempt native
dependency installation.

## Registration And Path Binding

The commercial flow starts at `99pages.uk`. The portal records the customer,
seat, device/workspace, Windows USB volume serial, USB root id, and intended
portable install anchor before local operation is enabled. The local CLI does
not treat the first bootstrap path as trusted by itself. It expects either a USB
device lock or the portal-approved install lock to exist first.

Windows USB factory burn:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\burn-windows-usb.ps1 -TargetDrive E: -Force
```

The burner copies the package to the target USB folder and writes:

```text
<usb root>/.99pages-usb-root.json
```

and:

```text
<usb install folder>/.99pages-device-lock.json
```

The root marker plus device lock contain the USB root id and portable folder
anchor. The Windows volume serial is recorded for portal registration and audit.
Changing Windows drive letters or mounting the same USB on macOS/Linux does not
break the binding. Moving the software folder to another relative path, or
copying only the software folder without the root marker, fails the
`device_anchor` check.

The portal install lock lives at:

```text
<shared host home>/install.lock.json
```

Core CLI, SubCLI, TUI, MCP shortcuts, and `99p update` enforce the registered
device/install anchor before running. `doctor`, `version`, and `bootstrap` stay
open for diagnosis and authorized rebinding. The install anchor compares the
path relative to the USB root marker, not the OS mount path. Moving the package
to another relative folder creates an install-anchor mismatch. The operator must
rebind the seat through `99pages.uk` before the copy can operate again.

Factory/development builds can set `AGENTIC_OS_V3_ALLOW_LOCAL_BIND=1` with
`bootstrap --yes` to write a local lock without the portal. This must not be
used as the commercial customer flow.

## Local Runtime Paths

- V3 home: `%USERPROFILE%\.99pages-agentic-os-v3`
- Shared host home: `%USERPROFILE%\.agentic-os`
- MCP modules: `%USERPROFILE%\.agentic-os\modules`
- Runtime state: `%USERPROFILE%\.agentic-os\run`
- Logs: `%USERPROFILE%\.agentic-os\logs`

macOS/Linux use the equivalent home directory paths.

The three platform binaries share the same host-home layout, so MCP modules,
logs, events, and data remain portable across Windows/macOS/Linux when copied
with the `.agentic-os` data root.

## Update Flow

```powershell
99p update
99p update --source <release_dir> --apply
```

`update` detects the current OS/architecture and looks for the matching binary
in the release root, `dist`, or `burn-ready`. Windows stages the replacement and
generates an apply script; macOS/Linux replace the current binary directly.

## Required Checks

- Go available for local build/development.
- Git available for SDK/app development.
- PowerShell on Windows.
- Config files available.
- MCP registry discoverable.

## Deployment Steps

1. Install or unpack V3.
2. Register customer, seat, device/workspace, and install path at `99pages.uk`.
3. Run `99p doctor`.
4. Run `99p bootstrap`.
5. Install/register MCP modules.
6. Verify `99p apps list`.
7. Verify `99p tui`.
8. Pair app.99pages.uk only after local CLI is stable.

## V1/V2 Lessons Kept

- V1 portable delivery proved USB/device binding and payload packaging.
- V2 proved event stream, bridge, and MCP registry.
- V3 removes heavy UI assumptions and keeps capability-only apps as the default.
