# V3 SDK Contract

The V3 SDK contract defines how developers build apps for 99Pages Agentic OS.

## Principle

An SDK app is not a frontend first. It is an MCP capability package that can be
called from Core CLI, SubCLI, TUI, bridge, app.99pages.uk, and agents.

## Required Package Shape

Each SDK app must provide:

- `manifest`: app id, name, version, category, modes, risk metadata, optional UI.
- `tools`: MCP tools with JSON schema-like argument contracts.
- `events`: progress, report, artifact, approval, and error event names.
- `data_contract`: schema, migration, storage path, and import/export contract.
- `reports`: final human-readable result format.
- `approval_policy`: actions that need human approval.
- `bootstrap`: dependency check and setup instructions.

## Manifest Fields

```json
{
  "name": "miniapp-builder",
  "description": "Build schema/database/report-first mini apps.",
  "category": "workflow",
  "modes": ["manual", "agent"],
  "requires_approval": false,
  "approval_actions": ["write_database", "run_migration", "export_data"],
  "ui_kind": "none",
  "ui_token_policy": "not_required",
  "open_url": ""
}
```

## Tool Contract

Every tool should accept JSON and return text or structured JSON text. Tools
must be deterministic where possible and emit events for long-running work.

Tool naming should use verbs:

- `Inspect`
- `Plan`
- `GenerateSchema`
- `PrepareDatabase`
- `ImportData`
- `WriteData`
- `Run`
- `Report`
- `Export`

## Approval Contract

The SDK must mark risky actions clearly:

- Write/delete/move files.
- Write/export secrets.
- Run shell/remote shell.
- Run migration.
- Write production database.
- Send messages externally.
- Control browser/computer/remote device.

Core CLI is responsible for the approval gate. SDK apps must expose enough
metadata for Core CLI to decide.

## Data Contract

Data is the key asset. Each app must document:

- Database type: SQLite by default.
- Schema version.
- Migration path.
- Import format.
- Export/report format.
- Storage root.
- Backup strategy.

## UI Contract

`ui_kind` defaults to `none`.

- `none`: capability-only app.
- `bundled`: 99Pages-maintained local HTML5 projection.
- `user_supplied`: customer-owned UI using user-owned tokens/design tools.

UI must never own business logic. It only projects events, data, approvals, and
reports.
