@sage-protocol/pi-adapter 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-protocol/pi-adapter",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Sage Protocol MCP integration for pi coding agent",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,6 +30,7 @@
     "build": "tsc -p tsconfig.build.json",
     "dev": "tsc -p tsconfig.build.json --watch",
     "clean": "rm -rf dist",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
     "test": "vitest --run",
     "prepublishOnly": "npm run clean && npm run build"
   },
@@ -37,7 +38,7 @@
     "@sinclair/typebox": "^0.34.0"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "^0.55.0"
+    "@mariozechner/pi-coding-agent": ">=0.61.0 <0.65.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/skills/sage-bridge/SKILL.md

@@ -4,7 +4,9 @@ description: >
   Pi adapter bridge for Sage Protocol. Search and activate prompt packs, libraries,
   and governance tools via the sage_search, sage_execute, sage_status MCP tools.
   Use when: building something new (search first), managing prompts/libraries,
-  DAO governance, bounties, chat rooms, or needing web search.
+  DAO governance, bounties, chat rooms, or needing web search. Don't use when:
+  the task is only local file editing or standard shell work with no Sage routing,
+  library, governance, or external-search need.
 ---
 
 # Sage Protocol Skill
@@ -64,8 +66,8 @@ sage_search({ domain: "prompts", action: "search", params: { query: "your task"
 **2. Inspect** — Read full details before activating.
 
 ```json
-sage_search({ domain: "skills", action: "get", params: { key: "skill-key" } })
-sage_search({ domain: "prompts", action: "get", params: { key: "prompt-key" } })
+sage_execute({ domain: "skills", action: "get", params: { key: "skill-key" } })
+sage_execute({ domain: "prompts", action: "get", params: { key: "prompt-key" } })
 ```
 
 **3. Activate** — Load skills that match the task.
@@ -103,6 +105,71 @@ Proactively search Sage when:
 
 ---
 
+## Recommended Pi Setup
+
+Keep pi thin and let Sage own routing behavior.
+
+Recommended `.pi/settings.json` shape in a local monorepo:
+
+```json
+{
+  "packages": [
+    "../packages/sage-pi-adapter",
+    {
+      "source": "../packages/sage-pi-export",
+      "skills": ["skills/*/SKILL.md"],
+      "extensions": [],
+      "prompts": [],
+      "themes": []
+    },
+    {
+      "source": "npm:oh-pi",
+      "extensions": ["!**"]
+    }
+  ],
+  "skills": [
+    "-../.agents/skills/frontend-design/SKILL.md",
+    "-~/.pi/agent/skills/prompt-builder/SKILL.md",
+    "-~/.pi/agent/skills/sage/SKILL.md",
+    "-~/.pi/agent/skills/sage-codebase/SKILL.md"
+  ],
+  "enableSkillCommands": true
+}
+```
+
+Mental model:
+
+- pi/OpenClaw = transport and tool surface
+- `sage` = base router skill
+- thin entrypoint library = recurring session-entry behavior layer
+- peer libraries = specialized review, critique, or domain augmentation
+
+Discovery rule:
+
+- prefer the curated `packages/sage-pi-export` package for Pi
+- avoid broad runtime roots like `~/.local/share/sage/skills` unless you explicitly want Pi to validate installed, versioned, and backup skill directories too
+
+Authoring and distribution model:
+
+- repo-authored skills and entrypoint definitions are the authoring source
+- on-chain libraries are the shared distribution and sync/pull surface
+- local sync is development convenience, not the product center
+
+Dispatch rule:
+
+- entrypoint behaviors should compose stable Sage-owned dependency skills by key instead of duplicating their bodies
+- examples of dependency-surface dispatch targets: `code-review`, `ceo-plan-review`, `vc-office-hours` from `sage-review-foundations`
+
+Export rule:
+
+- author real skills under `packages/sage/skills/`
+- declare the Pi-visible subset in `packages/sage/pi-export.manifest.json`
+- materialize `packages/sage-pi-export/skills/` with `node scripts/util/sync-sage-pi-export.mjs`
+
+Do not encode long-lived routing policy into the harness when a Sage skill or library can own it.
+
+---
+
 ## Bash CLI Quick Reference
 
 Use bash fallback when MCP tools are unavailable or for commands not covered by tools.