@fingerskier/augment 0.3.0 → 0.3.1

package/docs/FEATURES.md

@@ -146,6 +146,49 @@ Run without a clone via `npx -y @fingerskier/augment <command>`:
   hook over stdin JSON. Host-wired by `install`; rarely called directly.
 - `help` — full usage.
 
+## Pi Package
+
+The npm package is also a first-class Pi package (`keywords: ["pi-package"]` and
+a `pi` manifest in `package.json`). `pi install npm:@fingerskier/augment` loads:
+
+- `dist/pi/extension.js` — a Pi extension that registers namespaced
+  `augment_*` tools and slash commands.
+- `integrations/pi/skills/augment-context/SKILL.md` — Pi-specific workflow
+  guidance using the `augment_*` tool names.
+
+The Pi extension does not replace built-ins such as `read`; MCP `read` is exposed
+as `augment_read_memory`. It lazily connects to the shared daemon from tools and
+session events (no background resources start in the extension factory), warms
+`init_project` on `session_start`, injects recalled task context on
+`before_agent_start`, and reminds or follows up after non-trivial turns to
+persist durable work.
+
+Pi tools:
+
+- `augment_init_project`, `augment_list_projects`
+- `augment_search`, `augment_project_context`, `augment_read_memory`
+- `augment_upsert`, `augment_link`, `augment_list_links`, `augment_unlink`
+- `augment_tally`, `augment_sleep_candidates`
+- `augment_memory_insights`, `augment_memory_graph`
+
+Pi commands:
+
+- `/augment-context [query]`
+- `/augment-persist [summary]`
+- `/augment-dashboard [--no-open]`
+- `/augment-tally [verdict] [--surface S] [--note ...]`
+- `/augment-sleep`
+
+Pi-specific environment variables:
+
+- `AUGMENT_PI_AUTO_CONTEXT=inject|reminder|off` (default `inject`).
+- `AUGMENT_PI_AUTO_PERSIST=reminder|followup|off` (default `reminder`).
+- `AUGMENT_PI_CONTEXT_LIMIT` (default `5`).
+- `AUGMENT_PI_CONTEXT_MAX_CHARS` (default `12000`).
+
+The existing Claude and Codex installers, MCP server, daemon, CLI, and hook flow
+remain unchanged.
+
 ## Lifecycle Hooks
 
 Both installed integrations wire the same `hooks/hooks.json` (Claude Code and
@@ -487,7 +530,8 @@ Both installers also provision the shared hook runtime once via
 run through a direct `node <entry>` invocation (tens of milliseconds) instead of
 an npm bootstrap on every event. If npm is unavailable at install time the
 installer prints the manual command; hooks fail open (silent no-ops) until it is
-run.
+run. This installer path is independent of the [Pi Package](#pi-package) manifest
+and remains the supported setup for Claude Code and Codex.
 
 ## Deferred
 

package/integrations/pi/skills/augment-context/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: augment-context
+description: Use Augment local memories from Pi to gather and persist project context during coding sessions.
+---
+
+# Augment Context for Pi
+
+Use this skill when working in a repository with the `@fingerskier/augment` Pi package installed.
+
+## Session Start
+
+1. Use injected Augment memory if it is already present.
+2. If no injected memory appears, call `augment_project_context` with the user's task summary.
+3. Read exact memories with `augment_read_memory` when search results identify likely governing context.
+
+## Before Code Changes
+
+1. Call `augment_search` for the file, component, command, error, or behavior being touched.
+2. If work depends on a prior decision, read and follow the relevant `SPEC` or `ARCH` memory.
+3. If no relevant memory exists but the task creates a durable requirement or decision, create one before implementation.
+
+## Memory Triggers
+
+Call `augment_upsert` whenever one of these durable events happens:
+
+- A requirement, API contract, data model, or tool contract is clarified: use `SPEC`.
+- An implementation approach, tradeoff, transport choice, persistence model, or architecture decision is made: use `ARCH`.
+- A bug, risk, failing behavior, or blocker is discovered: use `ISSUE`.
+- Follow-up work is intentionally deferred: use `TODO`.
+- A meaningful implementation milestone is completed: use `WORK`.
+- A test scenario, regression case, or verification rule is learned: use `SPEC` or `WORK`, whichever is more durable.
+
+Call `augment_init_project` first when you need the `project_id` for `augment_upsert`.
+
+## Links
+
+After creating or updating a memory:
+
+1. Use `augment_link` when a memory implements, depends on, blocks, parents, or relates to another memory.
+2. Prefer linking new `WORK` notes to the `SPEC`, `ARCH`, `ISSUE`, or `TODO` they address.
+3. Prefer relative memory paths for durable cross-machine identity; numeric ids are local handles.
+
+## Session Finish
+
+For almost every session that did real work (skip only pure Q&A, read-only inspection, or trivial mechanical ops like commit-only turns):
+
+1. Upsert a concise `WORK` memory with what changed, key files, and verification.
+2. Upsert or update `TODO` memories for known remaining work.
+3. Link the final `WORK` memory to the relevant planning/decision memories.
+
+## Guardrails
+
+- Do not store secrets, credentials, tokens, or private keys.
+- Do not store huge logs, dependency dumps, generated files, or full source files.
+- Keep each memory focused; split large notes before calling `augment_upsert`.
+- Treat numeric memory IDs as local handles. Relative paths are the durable identity.
+- Use returned search text directly as context; do not ask Augment to summarize.
+- Default to upserting when a turn did real work. When unsure, upsert.
+- Do not create memories for facts already obvious from the current diff, or that duplicate an existing memory; update the existing memory instead.

package/package.json

@@ -1,9 +1,20 @@
 {
   "name": "@fingerskier/augment",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Local RAG memory system for coding agents",
-  "type": "module",
-  "publishConfig": {
+  "keywords": [
+    "pi-package",
+    "pi",
+    "opencode",
+    "memory",
+    "rag",
+    "mcp",
+    "coding-agent"
+  ],
+  "type": "module",
+  "main": "./dist/opencode/plugin.js",
+  "types": "./dist/opencode/plugin.d.ts",
+  "publishConfig": {
     "access": "public"
   },
   "bin": {
@@ -11,6 +22,14 @@
     "augment-daemon": "./dist/bin/augment-daemon.js",
     "augment-mcp": "./dist/bin/augment-mcp.js"
   },
+  "pi": {
+    "extensions": [
+      "./dist/pi/extension.js"
+    ],
+    "skills": [
+      "./integrations/pi/skills"
+    ]
+  },
   "files": [
     "dist",
     "docs",
@@ -26,6 +45,22 @@
     "prepack": "npm run check",
     "prepublishOnly": "npm run check"
   },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@huggingface/transformers": "^3.8.0",
     "@libsql/client": "^0.15.15",
@@ -36,8 +71,10 @@
     "zod": "^3.25.76"
   },
   "devDependencies": {
+    "@opencode-ai/plugin": "^1.17.15",
     "@types/node": "^24.3.0",
     "tsx": "^4.20.5",
+    "typebox": "^1.1.38",
     "typescript": "^5.9.2"
   },
   "engines": {