# Forge Plugin Management

Forge provides a public installation path for independently released providers while keeping the Controller trust boundary small. Official providers are **separate products** with their own repositories and releases; Forge owns how those providers are selected, installed, registered, authorized, and executed.

## Official catalog

```bash
forge plugin catalog
```

| Plugin ID | Product | Pinned release | Platforms |
| --- | --- | --- | --- |
| `desktop_operator` | [Forge Desktop Operator](https://github.com/moretea-labs/forge-desktop-operator) | `v0.4.5` | macOS |
| `design` | [Forge Design](https://github.com/moretea-labs/forge-design) | `v0.3.0` | macOS, Linux, Windows |
| `personal_knowledge` | [Personal Knowledge Assistant](https://github.com/moretea-labs/personal-knowledge-assistant) | `v0.2.1` | macOS, Linux, Windows |
| `figma` | [Forge Figma Bridge](https://github.com/moretea-labs/forge-figma-bridge) | `v0.3.0` | macOS |

Investment Decision System remains an independent product and is intentionally not a Forge plugin.

## Product facades and generic provider management

The native macOS provider has a product-level **Computer** facade. This is the preferred user surface:

```bash
forge computer setup
forge computer status
forge computer doctor
forge computer update
forge computer uninstall
# destructive provider-state removal is explicit:
forge computer uninstall --purge
```

`Computer` is the Forge product/capability identity. `desktop_operator` remains the implementation/provider identity used for trusted registration, release diagnostics, the stable macOS app bundle, LaunchAgent, socket, and TCC permissions. Its provider release is independent from the Forge Runtime release. Desktop Operator owns native macOS Computer observe/input/capture/console-unlock/element capabilities; Browser automation remains under the separate Browser provider authority rather than being claimed by the Desktop Operator catalog. `status` is a bounded projection of registration and recorded health, never proof inferred from a host browser; `doctor` refreshes provider health before reporting platform, registration, pinned-release, and readiness checks only on a compatible provider platform, and otherwise reports the stored incompatible registration without probing its transport. Setup/update use the same pinned official catalog transaction as generic plugin installation and fail before mutation when no compatible native provider exists. Uninstall invokes the provider-owned native uninstaller before Forge removes registration/package state, and fails closed rather than orphaning a native service when that lifecycle cannot be proven.

Generic provider administration remains available for diagnostics and non-Computer providers:

```bash
forge plugin install design
forge plugin install personal_knowledge
forge plugin install figma           # macOS, Figma bridge app/service required
forge plugin install desktop_operator   # compatibility/advanced path on macOS
forge plugin list --refresh
```

**Updating the Forge CLI does not automatically update external providers.** On macOS, use `forge computer update` after upgrading Forge; for other providers explicitly re-run `forge plugin install <id>` after checking `forge plugin catalog`. Re-running `forge plugin install <id>` installs the version currently pinned by Forge. A catalog version change is a reviewed Forge source change; providers cannot silently self-update through a ChatGPT request.

## User workflow: install, configure, use

1. Run `npm install -g @moretea-labs/forge@latest` and `forge setup next` to update the package/runtime connector contract.
2. On macOS, run `forge computer setup` (or `forge computer update` for an existing provider), then `forge computer doctor` and `forge computer status --json`. Native Accessibility/Screen Recording permissions may require manual approval.
3. Review `forge plugin catalog` and install only the extra providers you need, e.g. `forge plugin install design`, `forge plugin install personal_knowledge`, or `forge plugin install figma` on macOS.
4. Run `forge plugin list --refresh`. A provider registration is not evidence that its app, socket, browser or service authentication is ready.
5. Connect ChatGPT via the [MCP tutorial](tutorials/02-connect-chatgpt.md), then request a bounded outcome such as checking an open webpage, reviewing an authorized Finder folder, inspecting a design asset, or searching a configured local knowledge base. ChatGPT chooses typed actions, and Forge checks scope, authorization and evidence.

See the [Computer and Plugins Wiki guide](wiki/Computer-and-Plugins.md) and the [Browser runbook](operations/controller-browser-plugin.md). Computer is currently backed by a macOS-only native provider; do not promise native desktop control on Linux/Windows. Browser and Figma readiness depend on the selected browser mode or running app-specific bridge.

## Controller-global user plugin authority

Plugin installation, enabled state, connection configuration, and reusable user authorization are owned once by the current Controller instance. Enabling Gmail, Google Calendar, Google Tasks, Resend, Browser, or App Store Connect makes that same connection available from every registered project. Supplying `repo_id` does not select another plugin instance or Grant domain; it identifies Work attribution and repository resources only. Project-specific business values belong in typed action arguments.

The one-way migration selects a legacy config only when all copies agree or exactly one enabled value is unambiguous. It then writes `Controller Home/system/plugins/config/<plugin>.json` and retires the corresponding repository copies. Conflicting Browser profiles or App Store Connect identities are preserved without choosing or deleting one; an explicit global configuration is required to resolve them. Existing exact-target plugin Grants migrate to `controller:global` only when one live match is unambiguous, preserving the grant ID and authorization target.

## Trust boundary

Official installation uses the package-owned [`assets/plugin-registry.v1.json`](../assets/plugin-registry.v1.json). Forge:

1. resolves only catalog entries shipped with the installed Forge package;
2. accepts only the fixed Moretea Labs HTTPS repository declared by that entry;
3. checks out the immutable Git tag declared by the catalog;
4. verifies the provider's `forge-plugin.json` identity and protocol declaration;
5. runs the fixed `forge-plugin-install.mjs` installer entrypoint;
6. validates the returned provider registration;
7. writes it through the existing Controller Home external-registration authority;
8. projects health and actions through the normal typed plugin surface.

Forge does **not** scan sibling directories, accept a model-provided executable path, or provide a generic arbitrary-shell plugin transport.

## Responsibility split

### Forge core owns

- trusted distribution and registration;
- action schema and policy projection;
- authorization and confirmations;
- resource claims and concurrency boundaries;
- idempotency and action receipts;
- health projection and execution evidence.

### External providers own

- domain implementation;
- provider-local data and configuration;
- provider protocol implementation;
- platform-specific installation details;
- independent tests, releases, security policy, and support surface.

This split keeps Forge extensible without moving product-specific implementation into the core repository.

## Provider transports

### `unix_socket_jsonl`

Used by long-lived native providers such as Forge Desktop Operator. Forge connects to a stable local Unix socket on Unix hosts or a Windows named pipe on Windows after trusted provider installation and lifecycle verification; both use the same bounded JSONL protocol.

### `managed_cli_json`

Used by bounded one-shot providers such as Forge Design and Personal Knowledge Assistant. Forge launches a fixed runtime/helper pair from the installed package, validates the handshake, sends one bounded request, receives one bounded response, and terminates the process.

Both transports resolve to the same `AssistantPluginManifest` and `plugin_action_execute` policy/evidence path.

## Updates and rollback

Provider package directories are versioned and installed transactionally. Trusted registration is replaced only after package identity and installer output validate. If a new provider release fails validation or health checks, the existing registration is not silently replaced with an untrusted or partially installed provider.

Forge's catalog intentionally favors **reviewed pinned releases** over automatic marketplace-style updates. This is slower than an unbounded plugin marketplace and materially easier to audit.

## Provider development

Provider repositories expose their own development/install instructions. A provider release intended for the official catalog should have:

- a public repository and immutable version tag;
- a bounded `forge-plugin.json` contract;
- a deterministic `forge-plugin-install.mjs` entrypoint;
- focused protocol/health/action tests;
- CI, security reporting, support, and contribution documentation;
- no machine-specific paths, credentials, or user data in the public release.

The catalog is updated only after a fresh-install acceptance test proves the provider can be installed without relying on local sibling repositories.