AGENTS.md@packages/apple-tools git:20261014.31a93feA

Immutable. This exact content never changes and is served at /api/v1/blob/5ef39be08298f056.

# DOX — packages/apple-tools

Files in this directory. One row per source file. See change: add-apple-tools-imcp-plugin.

| File | Purpose |
|------|---------|
| `README.md` | Package overview. iMCP (Apple PIM) provisioning for pi via pi's built-in MCP (pi ≥ 1.0.0). macOS-only, no Mail. Install/provision/manual-grant, nine provisioning states. See change: migrate-mcp-to-pi-builtin. |
| `package.json` | pi-dashboard-plugin manifest. id `apple-tools`, priority 100. `dependsOn: ["mcp-client"]`. `requires: { paths: ["${imcpServerPath}"] }` (NO `piExtensions`). `configSchema` `./config.schema.json`. Claims `settings-section`→`AppleToolsSettings` (no `tab` — renders under the plugin's own row). `bin` `pi-apple-tools-install`. `pi.skills` `.pi/skills/apple-tools`. NO `pi-mcp-adapter` dep. No postinstall. See change: migrate-mcp-to-pi-builtin. |
| `config.schema.json` | JSON Schema 7. `imcpServerPath` only (default canonical `/Applications` location — the key the `paths` requirement interpolates). `exposure`/`toolExposure`/`enabled` deliberately absent: they live on the `mcpServers.iMCP` entry in mcp.json and are operator-owned (preserved on refresh). See change: migrate-mcp-to-pi-builtin. |
| `vitest.config.ts` | jsdom + react, shared setup-home globalSetup. |
| `tsconfig.json` | Extends tsconfig.base; jsx react-jsx; noEmit. |
| `.pi/skills/apple-tools/SKILL.md` | Agent skill. Seven reachable services; Mail exclusion + redirect to `apple-mail-fast-export`; Messages=iMessage/SMS; load-time `--check`; TCC revocation → menu-bar remediation. iMCP reached through pi's built-in MCP (pi ≥ 1.0.0), tools as `mcp__iMCP__*`. See change: migrate-mcp-to-pi-builtin. |
| `src/detect.ts` | Pure injectable probes: `parseVersion`/`compareVersions`/`meetsMinimum` (numeric, MIN_MACOS 15.3), `candidatePaths`/`discoverServer` (override-as-preference, ordered candidate list). Constants: IMCP_RELATIVE, IMCP_DOWNLOAD_URL, IMCP_BREW_CASK. |
| `src/install.ts` | `runInstaller(env, {check})` — the nine-state provisioning machine (write + write-suppressed check twin). `TerminalState` / `TERMINAL_STATES`, `InstallerEnv`, `InstallResult`. Post-brew re-discovery gate. Pure over injected env. Owns NO writer: `env.mcps` is the `mcp-client.config` service — `ensureServerEntry("iMCP", {command}, {kind:"global"})` (command refreshed; operator `enabled`/`exposure`/`toolExposure` + unknown keys preserved), `checkConfigFiles` (checks `mcpJson` only). `ensureAdapterPackage` + every `settings.json` write REMOVED. `relayConfigFailure` maps `ConfigRefusal` onto terminal states: `write-failed` → `CONFIG_WRITE_FAILED`, else `CONFIG_UNPARSEABLE`. See change: extract-mcp-client-plugin, migrate-mcp-to-pi-builtin. |
| `src/reconcile.ts` | `shouldReconcilePath` — server-side write-back guard (unset/default only, never over an operator override). `DEFAULT_IMCP_PATH`. |
| `src/doctor.ts` | `doctorProbe(env, packagePresent)` — read-only verdict from the shared checker; non-macOS never a remediation item. |
| `src/env.ts` | Real-environment `InstallerEnv` factory. The ONLY module that touches the real OS: `sw_vers`, brew via argv-array execFileSync (shared platform/exec wrapper). `createInstallerEnv`, BREW_TIMEOUT_MS. Builds `mcps` via `createMcpClientConfigService({configIO, knownCwds: () => [], paths?})` from `@blackbelt-technology/pi-dashboard-mcp-client-plugin/core` — hostless, global scope. Option `paths` (test seam) replaces the old `adapter`. Hardened atomic write moved to mcp-client `config-io.ts`; paths from `defaultLayerPaths`, so `PI_CODING_AGENT_DIR` is honoured. See change: extract-mcp-client-plugin, migrate-mcp-to-pi-builtin. |
| `src/bin/install.ts` | `pi-apple-tools-install [--check] [--path <p>]` CLI. Writes exactly ONE file (`~/.pi/agent/mcp.json`) in write mode; never the server plugin store. See change: migrate-mcp-to-pi-builtin. |
| `src/server/index.ts` | Plugin server entry. `ctx.consume<McpClientConfigService>("mcp-client.config")` at registration; absent → THROWS (fail closed — `dependsOn: ["mcp-client"]` guarantees ordering). `GET /api/apple-tools/status` (read-only, 10s TTL cache; iMCP readout via `readServerEntry("iMCP", {kind:"global"})`). `plugin_action` handler `run-installer` only (refuses the brew branch — delegates the long network install to the CLI). `set-disabled` / `set-direct-tools` DELETED — hard break, they live in mcp-client. Status readout fields `exposure` (display, default `codemode`) + `enabled` replace `directTools` + `disabled`. Path reconciliation via `updatePluginConfig` on the action path only. See change: extract-mcp-client-plugin, migrate-mcp-to-pi-builtin. |
| `src/client/index.tsx` | Intentionally empty client entry (`export {}`): the only claim loads lazily from `AppleToolsSettings.tsx` via manifest `module`. See change: lazy-plugin-claim-modules. |
| `src/client/AppleToolsSettings.tsx` | `AppleToolsSettings` settings-section panel (lazy `module`). Status readout, Run installer, path override; no directTools, no disable toggle (moved to mcp-client) — links "Manage MCP servers →" to `MANAGE_MCP_PATH` `/settings/plugins/mcp-client`. `useMissingDeps` reads this plugin's `missingDeps` from `GET /api/plugins`; a `mcp-client` gap renders a banner and hides the installer. Non-macOS inert state. See change: extract-mcp-client-plugin. |