# User Operation And MCP Guide

This guide teaches the main agent how to explain 99Pages Agentic OS to users and
how to choose the right MCP capability.

## First Explanation

99Pages Agentic OS is a CLI-first private assistant system. Core CLI owns login,
session, approvals, events, and execution. MCP modules provide capabilities such
as projects, mini apps, knowledge, media, files, browser, and automation.
app.99pages.uk is a HTML5/PWA projection layer for reports and control, not the
main runtime.

Default language is English. The user may change language preference.

## First Commands

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

Useful daily commands:

```powershell
99p apps list
99p apps tools <app>
99p apps call <app> <tool> [json]
99p mcp manifest
99p mcp audit
99p update
```

In TUI, the same operations are slash commands:

```text
/doctor
/bootstrap
/apps list
/mcp audit
/project tools
/miniapp tools
/update
```

## Approval Rules

The main agent must ask approval before:

- writing or exporting secrets;
- deleting, moving, or overwriting files;
- running shell or remote commands;
- deploying to servers;
- sending external messages;
- starting paid image, video, audio, or other media jobs;
- using user-owned API keys.

## MCP Capability Groups

### Execution

- `project`: project planning, code, files, reports, delivery.
- `workflow`: multi-step SOP and automation workflows.
- `miniapp-builder`: schema, database, data import, report-first mini apps.
- `subcli`: manual and agent-guided MCP operation.
- `harness`: tests, verification, acceptance checks.
- `trace`: logs, event tracing, failure analysis.

### Knowledge

- `knowledge`: general retrieval and synthesis.
- `wiki`: 99Pages product doctrine and internal reference.
- `library`: user or organization knowledge library.
- `docparse`: document parsing and extraction.
- `websearch`: current web search and source-backed answers.
- `wikipedia`: background encyclopedia summaries.
- `rss`: feed and news summaries.

### Device And Files

- `fs-walk`: read-only file discovery.
- `fs-actions`: file creation, edits, moves, deletion with approval.
- `pty`: local shell commands with approval.
- `ssh`: remote server commands with approval.
- `browseruse-headless`: browser automation and extraction.
- `computeruse`: desktop control with strict approval.
- `devices`: device and binding state.
- `xpra`: graphical projection/bridge when available.

### Security And Commercial

- `keybox`: local secrets and API keys.
- `license`: license and entitlement state.
- `devices`: seat/device/USB binding status.

### Communication

- `telegram-bot`: Telegram remote control and autopoll.
- `calendar`: schedule and agenda workflows.
- `ingest-email`: email import and summaries.
- `voice`: audio/voice workflows.
- `tts`: text-to-speech output.

### Media

- `vision`: image and screenshot understanding.
- `ui2json`: convert UI images into structured JSON.
- `image`: text-to-image and image-to-image jobs.
- `media-workflow-runner`: managed media job coordination.

Managed image/video defaults use Together.ai through `portal.99pages.uk` new-api
when the user does not choose a provider. User-owned media APIs are used when
the user explicitly chooses or supplies a provider key.

### Utility

- `briefing`: short summaries and readouts.
- `chat`: conversation and task translation.
- `cleanup`: cleanup recommendations.
- `cockpit`: local projection/entry layer only.
- `dashboards`: KPI and dashboard data.
- `duckdb`: local analytical database.
- `environ`: environment inspection.
- `gh`: GitHub operations.
- `habits`: habit/routine tracking.
- `journal`: notes and logs.
- `library-ui`: optional library projection.
- `patterns`: recurring pattern detection.
- `people`: people/contact records.
- `push`: notifications.
- `skills`: skill/capability inspection.
- `tags`: metadata and categorization.
- `webapp`: HTML5/PWA/report UI artifacts.
- `workforce-pro`: AI Workforce routing and agent coordination.

## Planned Add-On

`brainstorm` is the planned Intelligence Brain Storm MCP. It will let the user
store up to five OpenRouter model slots and run a panel discussion. The user's
OpenRouter keys pay for the panel; the main agent coordinates and summarizes.

## How The Main Agent Should Choose

- For project delivery: start with `project`, then use `fs-walk`, `fs-actions`,
  `harness`, and `trace` as needed.
- For mini apps: use `miniapp-builder` first; HTML5 is optional projection.
- For HTML5/PWA: use `webapp`; keep data/schema/report as the source of truth.
- For current information: use `websearch` and cite sources in final reports.
- For local knowledge: use `wiki`, `library`, `knowledge`, or `docparse`.
- For paid media: explain cost and provider choice before calling media MCPs.
- For secrets: use `keybox` and require approval.
- For shell/server work: use `pty` or `ssh` and require approval.
