fix(ci): scope typecheck to packages/** to fix broken CI

.github/workflows/ci.yml

@@ -40,7 +40,7 @@ jobs:
         run: pnpm --filter './packages/**' build
 
       - name: Typecheck
-        run: pnpm -r exec tsc --noEmit
+        run: pnpm --filter './packages/**' exec tsc --noEmit
 
       - name: Test
         run: pnpm test

docs/guide/capability-matrix.md

@@ -42,7 +42,7 @@ Legend:
 | `skills`                         | ✅      | ✅     | ✅   | —                                                                                           | Universal.                                                          |
 | `hooks` (lifecycle)              | ⚠️     | ⚠️    | ❌   | Copilot/Gemini: use HTTP or `command` handlers (see [Hooks](/guide/hooks)).                 | Kimi supports a subset (see below).                                  |
 | `subagentStart` / `subagentStop` | ❌      | ❌    | ❌   | TUI fidelity only — implement per-harness via native plugin config if you really need it.    | No universal primitive planned.                                    |
-| `tools[]`                        | ✅      | ✅     | ❌   | —                                                                                           | First-class tool emission.                                          |
+| `tools[]`                        | ⚠️      | ⚠️    | ❌   | Use `mcpServers` instead (not emitted on these Tier-2 harnesses).                           | No first-class tool emission; emit WARN.                            |
 | `mcpServers`                     | ❌      | ❌    | ❌   | Wire the MCP server directly into the harness's native config — no agentplugins path needed. | Not on the manifest path; harness-level wiring only.                |
 
 Kimi supported hooks: `preToolUse`, `userPromptSubmit`, `sessionStart`, `notification`, `permissionRequest`. Inline handlers auto-wrapped as Node.js command scripts (v0.5.0).

docs/guide/hooks.md

@@ -228,7 +228,7 @@ interface HookContext {
   toolInput?: unknown       // for tool hooks
   prompt?: string           // for prompt hooks
   agentName?: string        // for subagent hooks
-  error?: string            // for onError
+  error?: string            // for postToolUseFailure, stopFailure
 }
 ```
 
@@ -240,7 +240,7 @@ Returning an object lets you influence the agent's behavior:
 interface HookResult {
   block?: boolean           // stop the action
   reason?: string           // explanation (shown to the agent)
-  additionalContext?: string// inject context into the turn
+  additionalContext?: string // inject context into the turn
   modifiedInput?: unknown   // rewrite the tool input
 }
 ```

docs/guide/introduction.md

@@ -22,7 +22,7 @@ Every AI agent framework ships its own plugin system with its own manifest forma
 | Pi Mono            | TypeScript extensions        | inline only           |
 
 
-**Seven frameworks, seven different APIs.** A plugin author who wants reach across the ecosystem maintains seven forks of the same logic. Users who switch harnesses lose every plugin they configured.
+**Seven frameworks, seven different APIs.** A plugin author who wants to reach across the ecosystem maintains seven forks of the same logic. Users who switch harnesses lose every plugin they configured.
 
 ## The solution
 

docs/guide/manifest.md

@@ -55,7 +55,8 @@ The `hooks` object maps universal lifecycle event names to handlers. There are *
 
 | Category | Hooks |
 |---|---|
-| Session | `sessionStart`, `sessionEnd`, `setup` |
+| Session | `sessionStart`, `sessionEnd` |
+| Setup | `setup` |
 | Prompt | `userPromptSubmit`, `userPromptExpansion` |
 | Tool | `preToolUse`, `postToolUse`, `postToolUseFailure` |
 | Permission | `permissionRequest`, `permissionDenied` |
@@ -215,6 +216,23 @@ sidecar: {
 | `health` | `string` | Health check URL. |
 | `restart` | `'always' \| 'on-failure' \| 'no'` | Restart policy. |
 
+## Install setup
+
+The optional top-level `setup` field declares a one-shot install command. After `agentplugins add`, the CLI prompts for trust and runs it once. It is distinct from the `hooks.setup` lifecycle hook.
+
+```typescript
+setup: {
+  command: './scripts/install.sh',
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `command` | `string` | yes | Shell command to run after install. |
+| `args` | `string[]` | no | Arguments passed to the command. |
+
+If `setup` is omitted, the CLI auto-detects `install.sh` → `setup.sh` → `postinstall.mjs` → `postinstall.js` (first hit). See [Linting](/guide/linting) and [Porting](/guide/porting#security--setup-on-install) for details.
+
 ## Rules
 
 The `rules` array declares behavioral rules — allow/deny/warn patterns applied to tool calls.

docs/reference/adapters.md

@@ -12,9 +12,9 @@ An adapter compiles the universal manifest into one target platform's native for
 | `gemini` | JSON manifest | command | subset | ⚠️ | ❌ |
 | `kimi` | JSON manifest | command | subset | ⚠️ | ❌ |
 | `opencode` | TypeScript plugin + `opencode.json` | inline (reference) | subset | ✅ | ✅ |
-| `pimono` | TypeScript extension + `package.json` | inline (reference) | subset | ✅ | ✅ |
+| `pimono` | TypeScript extension + `package.json` | inline (reference) | subset | ✅ | ⚠️ |
 
-⚠️ = WARN emitted; `tools[]` is not natively emitted — use `mcpServers` for Claude/Codex (Tier-1 universal tool path).
+⚠️ = WARN emitted; `tools[]` is not natively emitted — use `mcpServers` for Claude/Codex (Tier-1 universal tool path). Pi Mono has no built-in MCP; `tools[]` is the native tool path.
 
 Two families: **JSON-emitting** adapters (claude, codex, copilot, gemini, kimi) produce static manifest files the host reads at startup. **Code-emitting** adapters (opencode, pimono) produce real TypeScript modules the host imports and calls.