feat(profile): materialize global Pi and OMP profiles

CHANGELOG.md

@@ -22,6 +22,13 @@
 - Native Pi package and OMP marketplace-plugin lifecycle support for install,
   update, uninstall, status, and list output, with fail-closed trust and
   ownership checks.
+- Global Pi and OMP profiles declared in `~/.allagents/workspace.yaml`, with
+  preflighted install/status/remove commands, generated launchers, incremental
+  managed-versus-referenced ownership state, and repeatable
+  `allagents update --profile`.
+- Pi profile MCP materialization with an explicitly declared, usable
+  profile-scoped `pi-mcp-adapter`, plus native OMP named-profile marketplace
+  lifecycle and revision verification.
 
 
 ## [1.0.0] - 2026-03-13

README.md

@@ -91,9 +91,13 @@ clients:
 |---|---|
 | `allagents init <path>` | Create a workspace (optionally `--from owner/repo`) |
 | `allagents update` | Sync all plugins to workspace |
+| `allagents update --profile <name>` | Reconcile an installed global profile |
 | `allagents plugin install <spec>` | Install a plugin |
 | `allagents plugin uninstall <spec>` | Remove a plugin |
 | `allagents plugin list` | List installed plugins and skills with source, scope, and clients |
+| `allagents profile install <name> --yes` | Install a declared global profile |
+| `allagents profile status [name]` | Inspect declared and installed profiles |
+| `allagents profile remove <name> --yes` | Remove unchanged managed profile resources |
 | `allagents skill add <name>` | Add a skill from a repo (plural `skills` alias supported) |
 | `allagents skill list` | List skills and status |
 | `allagents mcp add <name> <commandOrUrl>` | Add an MCP server and sync to clients |

docs/src/content/docs/docs/reference/cli.mdx

@@ -6,7 +6,7 @@ description: Complete reference for AllAgents CLI commands.
 ## Top-Level Commands
 
 ```bash
-allagents update [--offline] [--dry-run] [--client <client>] [--scope <scope>]
+allagents update [--offline] [--dry-run] [--client <client>] [--scope <scope>] [--profile <name>...]
 allagents status
 ```
 
@@ -20,9 +20,20 @@ Updates plugins in the workspace using non-destructive sync. By default, remote
 | `--dry-run` | Preview changes without applying them |
 | `-c, --client <client>` | Sync only the specified client (e.g., `opencode`, `claude`) |
 | `-s, --scope <scope>` | Sync scope: `project` (default) or `user` |
+| `--profile <name>` | Reconcile only this installed global profile; repeatable |
 
 When `--scope user` is used, sync targets the user-level workspace at `~/.allagents/workspace.yaml` and installs plugins to user directories (`~/.claude/`, `~/.codex/`, etc.) instead of the project.
 
+Without `--profile`, update independently attempts the user workspace, every
+installed profile that still has a declaration, and the current project
+workspace, in that order. A failure in one pass does not skip later passes, but
+the command exits nonzero after all applicable work completes.
+
+Using one or more `--profile` filters validates the entire selected set before
+mutation, updates only those installed and still-declared profiles, and skips
+ordinary user and project sync. `--profile` cannot be combined with `--scope`
+or `--client`.
+
 **Non-destructive behavior:**
 - First sync overlays files without deleting existing user files
 - Subsequent syncs only remove files previously synced by AllAgents
@@ -38,6 +49,30 @@ only removes resources whose ownership it can corroborate.
 
 When `vscode` is in the `clients` list, sync also generates a `.code-workspace` file with repository paths resolved to absolute paths. See the [Workspaces guide](/docs/guides/workspaces/#vscode-workspace-generation) for details.
 
+### profile
+
+```bash
+allagents profile install <name> [--yes] [--dry-run] [--offline]
+allagents profile status [name]
+allagents profile remove <name> [--yes] [--dry-run] [--offline]
+```
+
+Profile declarations exist only in `~/.allagents/workspace.yaml`. `install`
+and `remove` display a complete plan before mutation and require confirmation;
+scripts and JSON mode must pass `--yes`. `--dry-run` emits the same resolved
+plan without writing profile state, client files, native package state, or
+launchers.
+
+`status` reports declared, installed, missing, drifted, partial, unsupported,
+and declaration-missing resources. Omitting the name opens a selector only on
+an interactive terminal; non-interactive and JSON callers must provide it.
+
+Removal works from ownership state even after the declaration is deleted. It
+deletes only unchanged managed resources, releases referenced resources, and
+retains modified, shared, failed, or uncorroborated resources for inspection
+and retry. There is intentionally no `allagents profile update`; use repeatable
+`allagents update --profile <name>`.
+
 ### status
 
 Show the sync status of all configured plugins and skills.

docs/src/content/docs/docs/reference/clients.mdx

@@ -58,8 +58,13 @@ Native install mode delegates plugin lifecycle to Pi's package manager. Pi
 0.85.1 through 0.85.x is supported. Package sources may be npm specs such as
 `npm:pi-extension`, Git repositories, or local paths. Project-native operations
 fail before mutation unless Pi's trusted settings outside the project boundary
-authorize that project. AllAgents inspects `pi-mcp-adapter` state but does not
-install or configure the adapter.
+authorize that project. Ordinary workspace sync only inspects
+`pi-mcp-adapter`; a Pi global profile may declare
+`npm:pi-mcp-adapter` with `install: native` and then materialize profile-scoped
+MCP configuration after the installed package is verified as usable.
+Pre-existing usable adapters are recorded as referenced and preserved.
+Pi profile launchers select an isolated `PI_CODING_AGENT_DIR` while retaining
+the caller's working directory and normal project package discovery.
 
 ### OMP
 
@@ -74,6 +79,13 @@ Ordinary OMP operations always address the unnamed profile: AllAgents removes
 inherited `OMP_PROFILE`, `PI_PROFILE`, and `PI_CONFIG_FILES` selectors while
 preserving the active HOME and XDG roots.
 
+OMP global profiles use the runtime's native `--profile <name>` selector.
+AllAgents pins HOME, `PI_CONFIG_DIR`, and active XDG roots consistently across
+planning, native commands, status, and generated launchers. The canonical
+GitHub `main` ref is resolved to a revision before mutation and verified against
+OMP's marketplace checkout. Profile removal unregisters a marketplace only
+when this profile introduced it and no installed plugin still references it.
+
 ### VSCode
 
 VSCode syncs the same skills, agent file, and GitHub overrides as Copilot. Additionally, adding `vscode` to `clients` triggers automatic `.code-workspace` file generation and MCP config syncing during `allagents update`. See the [Workspaces guide](/docs/guides/workspaces/#vscode-workspace-generation) for details.

docs/src/content/docs/docs/reference/configuration.mdx

@@ -73,6 +73,72 @@ scope. Project installs require trust recorded outside the project-controlled
 Pi agent root. OMP native mode accepts marketplace-backed plugin specs at
 project or user scope and requires OMP 18.1.17 or newer.
 
+### Global Profiles
+
+Named profiles are declared only in the user workspace at
+`~/.allagents/workspace.yaml`. A project `.allagents/workspace.yaml` containing
+`profiles` is invalid.
+
+```yaml
+profiles:
+  compound-engineering:
+    clients:
+      - name: omp
+        install: native
+        launcher: omp-compound
+    plugins:
+      - source: EveryInc/compound-engineering-plugin
+        ref: main
+        install: native
+
+  pi-tools:
+    clients:
+      - name: pi
+        install: native
+        launcher: pi-tools
+    plugins:
+      - source: ./pi-package
+        install: native
+      - source: npm:pi-mcp-adapter
+        install: native
+    mcpServers:
+      local-tools:
+        command: node
+        args: [/absolute/path/to/server.mjs]
+        env:
+          API_TOKEN: ${API_TOKEN}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `profiles.<name>.clients` | Yes | One or more object-form profile clients |
+| `clients[].name` | Yes | Supported profile client; currently `pi` or `omp` |
+| `clients[].install` | No | Default plugin mode, `file` by default |
+| `clients[].launcher` | No | Safe command basename written to the configured user bin directory |
+| `clients[].settings` | No | Strict client settings object; Pi and OMP currently accept no settings |
+| `profiles.<name>.plugins` | No | Profile plugin declarations; defaults to an empty list |
+| `plugins[].source` | Yes | npm, GitHub, marketplace, or local source supported by the selected adapter |
+| `plugins[].ref` | No | Requested Git ref for a GitHub source |
+| `plugins[].install` | No | Per-plugin `file` or `native` override |
+| `plugins[].clients` | No | Restrict the plugin to named clients in this profile |
+| `plugins[].skills` | No | Skill allowlist or `{ exclude: [...] }` where the adapter supports filtering |
+| `profiles.<name>.mcpServers` | No | Profile-scoped stdio or HTTP MCP declarations |
+
+Relative local plugin sources resolve from the user's home directory, not the
+current project. Profile names and launcher names are safe command basenames;
+machine paths, resolved revisions, generated launcher paths, and ownership
+state are not declaration fields.
+
+MCP credentials must remain runtime references. Environment values and HTTP
+headers accept exact `${ENV_VAR}` references only, and credential-bearing
+command arguments must use the same exact form. Resolved secret values are
+never written to plans, launchers, profile state, or generated configuration.
+
+Install profiles explicitly with `allagents profile install <name> --yes`.
+Ordinary `allagents update` reconciles installed, still-declared profiles;
+repeat `--profile <name>` to select only installed profiles. Removing a
+declaration does not uninstall it—use `allagents profile remove <name> --yes`.
+
 ### Setup Commands
 
 The optional top-level `setup` field is an ordered list. A string runs on every

src/cli/agent-help.ts

@@ -21,6 +21,11 @@ import {
   pluginValidateMeta,
 } from './metadata/plugin.js';
 import { updateMeta } from './metadata/self.js';
+import {
+  profileInstallMeta,
+  profileRemoveMeta,
+  profileStatusMeta,
+} from './metadata/profile.js';
 import {
   initMeta,
   setupMeta,
@@ -49,6 +54,9 @@ const allCommands: AgentCommandMeta[] = [
   skillsSearchMeta,
   skillsUpdateMeta,
   updateMeta,
+  profileInstallMeta,
+  profileStatusMeta,
+  profileRemoveMeta,
 ];
 
 /**

src/cli/commands/plugin.ts

@@ -84,7 +84,10 @@ import {
   formatPluginSource,
   getPluginDisplayName,
 } from '../../utils/plugin-path.js';
-import { parseWorkspaceConfig } from '../../utils/workspace-parser.js';
+import {
+  parseUserWorkspaceConfig,
+  parseWorkspaceConfig,
+} from '../../utils/workspace-parser.js';
 
 
 /**
@@ -823,7 +826,10 @@ const pluginListCmd = command({
       ): Promise<void> {
         if (!existsSync(configPath)) return;
         try {
-          const config = await parseWorkspaceConfig(configPath);
+          const config =
+            scope === 'user'
+              ? await parseUserWorkspaceConfig(configPath)
+              : await parseWorkspaceConfig(configPath);
           const { plans } = buildPluginSyncPlans(
             config.plugins,
             config.clients,