# 99Pages Agentic OS V3

Powered By Ng Tick Kee (Founder of UiBC Training Hub)

Commercial V3 workbench for 99Pages Agentic OS.

V3 keeps V1 intact and focuses on the pieces that make an agent feel reliable in production:

- CLI-first task execution.
- Durable run event stream.
- Deterministic sentinel checks that cost zero tokens.
- AI Workforce-only model routing.
- Main agent fixed to MiniMax 2.5.
- Per-module sub-agent model assignment.
- MCP-native local app projection.
- Agent-native applications that are CLI-addressable MCP capabilities first.

## Runtime Shape

Core CLI is the login, session, event, approval, and execution owner. Sub CLI can
call any registered MCP for manual operation or agent-guided operation. Cockpit
is not a monolithic runtime; it is an entry/projection layer over local MCP apps.

```text
Core CLI
  -> login/session/license
  -> event stream + approval gate
  -> MCP registry and local app lifecycle
  -> Sub CLI dispatch

Sub CLI
  -> manual MCP operation
  -> agent-guided MCP calls

MCP
  -> manifest/status/start/stop/call/open
  -> UI is optional; most MCPs expose capability only
  -> user-supplied HTML5 UI uses user-owned tokens
```

## UI Policy

Every app is a CLI-addressable MCP capability first. Every UI is optional
projection. The agent operates data and tools; humans approve, inspect, and
consume reports.

MCPs do not need a bundled HTML5 frontend to be useful. The default contract is
`ui_kind: none`, which means Core CLI/Sub CLI access the MCP through tools and
events only. A module advertises `ui_kind: bundled` only when we ship and
maintain its local UI. If a user wants a custom HTML5 surface, it should be
registered as `ui_kind: user_supplied` and created with the user's own tokens,
keys, or design tools.

This keeps the maintained surface small: 99Pages provides the capability,
approval policy, lifecycle hooks, and event stream; optional UI can come later
without blocking CLI release.

## Core Documents

Start from [V3 Core Documents](docs/V3_CORE_DOCUMENTS.md).

The V3 writing set includes:

- [SDK Contract](docs/SDK_CONTRACT.md)
- [SDK Development Plan](docs/SDK_DEVELOPMENT_PLAN.md)
- [Main Agent Default Profile](docs/MAIN_AGENT_PROFILE.md)
- [User Operation And MCP Guide](docs/USER_OPERATION_AND_MCP_GUIDE.md)
- [PDR V3](docs/PDR_V3.md)
- [Textbook Plan V3](docs/TEXTBOOK_PLAN_V3.md)
- [System Deployment V3](docs/SYSTEM_DEPLOYMENT_V3.md)
- [app.99pages.uk HTML5/PWA Deployment](docs/APP_99PAGES_HTML5_DEPLOYMENT.md)
- [Commercial Model Strategy](docs/COMMERCIAL_MODEL_STRATEGY.md)

## CLI Shape

```powershell
99p doctor
99p bootstrap
99p bootstrap --yes
99p version
99p update
99p update --source <release_dir> --apply
99p run "deploy this workspace to my VPS"
99p runs
99p watch <run_id>
99p events <run_id>
99p shell
99p approve <approval_id> --resume
99p models
99p mcp manifest
99p mcp status
99p mcp call <module> <tool> [json]
99p mcp resume <approval_id>
99p mcp open <module>
99p apps list
99p apps manifest
99p apps tools <app>
99p apps call <app> <tool> [json]
99p subcli mcp open <module>
99p keybox tools
99p keybox call <tool> [json]
99p project tools | call <tool> [json] | open | status
99p workflow tools | call <tool> [json] | open | status
99p miniapp tools | call <tool> [json] | open | status
99p fs walk <tools|call> ... | actions <tools|call> ...
99p pty tools | call <tool> [json] | open | status
99p browser tools | call <tool> [json] | open | status
99p device tools | call <tool> [json] | open | status
99p wiki tools | call <tool> [json] | open | status
99p library tools | call <tool> [json] | open | status
99p trace tools | call <tool> [json] | open | status
99p harness tools | call <tool> [json] | open | status
99p ssh tools | call <tool> [json] | open | status
99p sentinel once
99p sentinel start
```

## Three-Platform Bootstrap

V3 is CLI-first and ships as one package with three platform builds. Users
should start through the launcher, not by choosing binaries manually:

One-line install:

```powershell
irm https://download.99pages.uk/99pages-agentic-os-v3/latest/install.ps1 | iex
```

```bash
curl -fsSL https://download.99pages.uk/99pages-agentic-os-v3/latest/install.sh | sh
```

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

```bash
./99p.sh doctor
./99p.sh bootstrap
./99p.sh tui
```

The launchers auto-detect OS/architecture and call the matching binary. Runtime
data, MCP modules, logs, and run state remain shared under `.agentic-os`.

## Registered Install Path

Commercial V3 USB copies are burned by Windows but run on Windows, macOS, and
Linux. The Windows burner writes a USB root marker at the drive root and
`.99pages-device-lock.json` inside the install folder. The CLI validates the USB
root marker plus the portable folder anchor on every OS.

On Windows, changing `E:` to `F:` is fine. On macOS/Linux, mounting the same USB
under another mount point is also fine. Moving the software folder to another
relative path, or copying only the software folder without the USB root marker,
fails the `device_anchor` check. The Windows volume serial is still recorded for
`99pages.uk` registration and audit, but it is not required for macOS/Linux
runtime.

`doctor`, `version`, and `bootstrap` remain available so the operator can see
the problem and complete the portal-approved binding flow. If the folder is
moved to a different relative location, copied outside the registered install
anchor, or re-sold, operational commands stop with an install-anchor mismatch
until the seat is re-bound through `99pages.uk`.

Windows USB factory burn:

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

The direct CLI startup path is:

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

`doctor` checks the current platform, Go, Git, shell policy, configs, and MCP
registry. `bootstrap` creates local runtime folders. With `--yes`, it can try to
install missing platform dependencies through the native package surface:

- Windows: `winget`
- macOS: `brew`
- Linux: `apt-get`, `dnf`, `yum`, or `apk`

The install step is best-effort because OS permissions differ. If automatic
installation cannot run, `bootstrap` prints the exact command or hint needed.

## Updates

Users update through CLI/TUI:

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

On Windows, updates are staged next to the current executable and an
`.apply-update.cmd` script is generated because a running `.exe` cannot replace
itself safely. macOS/Linux can replace the current binary directly.

SubCLI and Keybox are first-class CLI surfaces. SubCLI performs manual or
agent-guided MCP operation under the Core login/session. Keybox owns local
secret/key writes and exports; write/export actions go through human approval
before execution.

Mini App Builder is also MCP CLI first. The maintained contract is schema
generation, database preparation, data import/write, report output, and update
events. Visual screens can be added later through app.99pages.uk or
user-supplied UI only when the project needs them.

On Windows, all CLI surfaces should be opened through PowerShell with UTF-8
input/output so Chinese input works consistently. Use `99p shell` for the local
operator shell. Core CLI also passes `AGENTIC_OS_CLI_SHELL=powershell` and
`AGENTIC_OS_CLI_ENCODING=utf-8` into MCP processes.

## Core Principle

The local timer never calls a model. It checks deterministic conditions such as memory, disk, queue backlog, and MCP health. Only matched conditions create a run that can wake the AI Workforce ReAct loop.

```text
sentinel tick
  -> local checks
  -> condition matched?
    no  -> sleep, 0 token
    yes -> append event + create run
       -> wake AI Workforce
       -> stream every step
       -> request approval when needed
```

## Model Governance

Users do not see raw providers. They see roles, capabilities, and tiers. All execution goes through AI Workforce.

```text
main_agent:
  model: minimax-2.5

module_agents:
  coding: controlled by Workforce policy
  ops: controlled by Workforce policy
  finance: controlled by Workforce policy
  media: controlled by Workforce policy
  wiki: controlled by Workforce policy
```

## Status

Initial V3 skeleton. Not a replacement for V1 yet.
