@caupulican/pi-adaptative 0.80.51 → 0.80.53

package/docs/resources.md

@@ -0,0 +1,178 @@
+# Resource Profiles & Library
+
+Pi can load a wide range of resources: extensions, skills, prompt templates, themes, agents. Across different projects and situations you rarely want all of them at once. **Resource profiles** are named on/off contracts that decide what is active, and the **Resources hub** is where you register a shared catalog of resources and curate which ones each project or situation uses.
+
+The system separates three ideas that are easy to conflate:
+
+- **Available** — what Pi can discover (from your catalog, plus user and project directories). "What exists."
+- **Enabled** — what is active right now, expressed as a profile. "What's on."
+- **Installed** — a physical copy under `~/.pi/agent/…` for portability to a machine without the catalog. "A local copy."
+
+The default workflow is *manage by enabling, not by copying*: keep one catalog as the source of truth and switch profiles per situation. Installing is a secondary path for offline/portable use.
+
+## Table of Contents
+
+- [The Resources hub](#the-resources-hub)
+- [Resource profiles](#resource-profiles)
+- [Profile files](#profile-files)
+- [Sources: a shared catalog](#sources-a-shared-catalog)
+- [Manage Library](#manage-library)
+- [Profiles as situations](#profiles-as-situations)
+- [Per-agent profiles](#per-agent-profiles)
+- [Install at user level](#install-at-user-level)
+- [Backup and restore](#backup-and-restore)
+- [Precedence](#precedence)
+
+## The Resources hub
+
+In interactive mode, open `/settings` and choose **Resources** to reach the **Resources Hub**:
+
+| Item | What it does |
+|------|--------------|
+| **Profile / Situation** | Select the active profile. |
+| **Manage Library** | Browse everything available and toggle what the active profile allows. |
+| **Manage Profiles / Situations** | Create, persist, or delete profile definitions. |
+| **Sources** | Register, trust, and remove external catalog directories. |
+
+When no source or profile exists yet, the hub surfaces a first-run nudge — **"Add your catalog directory →"** — pointing you at the setup step below.
+
+## Resource profiles
+
+A profile is an allow/block contract over six kinds: `extensions`, `skills`, `prompts`, `themes`, `agents`, and `tools`. Each kind takes glob-style patterns:
+
+- **`allow`** — when non-empty, only matching resources of that kind stay available.
+- **`block`** — removed after `allow` is applied.
+
+Empty `allow` means "allow all of this kind." `block: ["*"]` means "none."
+
+A profile may also bind a **model** and a **thinking level** that apply when the profile is active. Thinking is one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. Explicit CLI flags still win over a profile's model/thinking, which in turn win over the settings default.
+
+Profiles are stored in settings under `resourceProfiles`, and the active one(s) in `activeResourceProfile`:
+
+```json
+{
+  "resourceProfiles": {
+    "review": {
+      "tools": { "allow": ["read", "grep", "find", "ls", "bash"] },
+      "extensions": { "block": ["*"] }
+    }
+  },
+  "activeResourceProfile": "review"
+}
+```
+
+`activeResourceProfile` accepts a single name or an array; multiple active profiles are merged. Switch the active profile any time with `/profiles`.
+
+> The older `disabledResources` block lists still work as a simple reversible "turn these off" filter. Profiles are the richer, named, reusable form.
+
+## Profile files
+
+Besides inline settings, a profile can live as a standalone JSON file in `~/.pi/agent/profiles/` (or `<catalog>/profiles/` when shared through a source). The file wraps the resource contract with optional metadata:
+
+```json
+{
+  "name": "recon",
+  "description": "Fast read-only scout: cheap model, read tools only.",
+  "model": "anthropic/claude-haiku-4-5",
+  "thinking": "low",
+  "resources": {
+    "tools": { "allow": ["read", "grep", "find", "ls"] },
+    "extensions": { "block": ["*"] }
+  }
+}
+```
+
+File-based profiles appear by name alongside settings-based ones, so they can be version-controlled in a catalog and shared across machines.
+
+## Sources: a shared catalog
+
+A **source** is an external directory that Pi live-scans for resources. Point it at a folder structured like this and every kind is discovered automatically:
+
+```
+my-catalog/
+├── skills/
+├── extensions/
+├── prompts/
+├── themes/
+├── profiles/
+└── agents/
+```
+
+To register one:
+
+1. `/settings → Resources → Sources → Add` and point at the directory.
+2. Confirm the **trust** prompt.
+
+> **Security:** a source can contain executable extension code and skills that instruct the model. Pi only scans roots you have explicitly **trusted**; untrusted or missing roots are skipped. Review a catalog before trusting it.
+
+Registered roots are stored as `externalResourceRoots`; the trusted subset as `trustedResourceRoots`. Only roots that are both trusted and present are scanned. Because the scan is live, editing a file in the catalog is reflected on the next reload — no copy step.
+
+This makes a git repository of shared resources a natural catalog: clone it once, register it as a source, and it *is* your backup.
+
+## Manage Library
+
+**Manage Library** is the browser for going from "a folder of fifty things" to "this project uses these eight." It lists everything available per kind, with its source labelled (catalog vs. user vs. project), and lets you toggle each item on or off for the active profile.
+
+- **Fuzzy search** by name or description, so you never scroll a long list.
+- Both framings are supported: *allow only these* and *everything except these* — so you don't have to untick forty-seven items to keep three.
+- Toggles **apply live**. Turning an extension on or off loads or unloads it in place; its tools and commands appear or disappear without restarting the session. Lighter kinds (skills, prompts, themes) refresh the same way.
+- An item that a profile enables but that has since disappeared from the catalog is marked **`[missing]`** rather than silently dropped.
+
+By default, changes save to the active profile at the **directory-overlay** scope — a per-repository choice that writes no files into the project itself. You can also save to project or global scope.
+
+## Profiles as situations
+
+A profile *is* a situation. "Reviewing a PR," "scouting an unfamiliar repo," "heads-down implementation" are each just a profile with a curated set of resources and (optionally) a model. Switching the whole situation is one action:
+
+```bash
+/profiles review      # swap to the review situation
+```
+
+## Per-agent profiles
+
+When you delegate to a subagent (via the `subagent` extension), the agent can declare which profile it runs under in its frontmatter, so a scout runs read-only on a cheap model while a worker gets the full toolset:
+
+```markdown
+---
+name: scout
+description: Fast codebase recon.
+profile: recon
+---
+```
+
+Agents are discovered from your catalog's `agents/` directory the same way other kinds are, so the whole set travels with the catalog.
+
+## Install at user level
+
+Live scanning covers the day-to-day. For portability — a machine without the catalog checkout, or offline use — copy a trusted directory's resources into your user config:
+
+```bash
+/install-resources <dir>            # copy, skipping files that already exist
+/install-resources <dir> --force    # overwrite existing files
+```
+
+This copies `skills`, `extensions`, `prompts`, `themes`, `profiles`, and `agents` from `<dir>` into `~/.pi/agent/…`. The source must be trusted first (Pi prompts if it isn't, since extension code is executable). Installed agents land in `~/.pi/agent/agents`, where subagent discovery reads them.
+
+## Backup and restore
+
+Back up your personal configuration — profile definitions and resource settings — to a single JSON file:
+
+```bash
+/config-backup             # writes a default-named backup
+/config-backup my.json     # writes to a path
+/config-restore my.json    # merges it back, after confirmation
+```
+
+The backup bundles your profiles and the resource settings (`resourceProfiles`, `activeResourceProfile`, `externalResourceRoots`, `trustedResourceRoots`). It does **not** copy the catalog itself — that is what your git repository is for.
+
+> **Security:** restore is deliberately cautious. Restored external roots come back **untrusted**, so a new machine re-prompts before any code loads, and restore confirms before overwriting existing local config.
+
+## Precedence
+
+When the same resource name exists in more than one place, the order is:
+
+```
+Project (.pi/)  >  User (~/.pi/agent/)  >  External roots (in registration order)  >  Bundled
+```
+
+Same-named items shadow lower-precedence ones, and Manage Library shows each item's source so you can see which copy is winning.

package/docs/self-adaptation.md

@@ -0,0 +1,68 @@
+# Self-Adaptation
+
+Pi can turn something you just did into a durable, reusable capability. When a session reveals a repeatable workflow, Pi can draft a new **skill** or **extension** for it, check it for overlap with what you already have, validate it, and — once you approve — make it live the same turn. No restart, no hand-authoring boilerplate.
+
+This keeps a human on the edge of the loop: Pi proposes, you confirm, then it activates.
+
+## Table of Contents
+
+- [Commands](#commands)
+- [How proposal and activation are separated](#how-proposal-and-activation-are-separated)
+- [Skillify](#skillify)
+- [Extensionify](#extensionify)
+- [Learn](#learn)
+- [Duplicate detection](#duplicate-detection)
+- [Going live](#going-live)
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/skillify` | Capture a repeatable workflow from the session and draft a new skill. |
+| `/extensionify` | Scaffold a new extension (a tool or command) from the session. |
+| `/learn` | Reflect on the session, classify the lesson, and route it to the right outcome. |
+
+The same analysis is also available to the model as the `skillify`, `extensionify`, and `skill_audit` tools.
+
+## How proposal and activation are separated
+
+Authoring has a hard boundary between *drafting* and *committing*:
+
+- **Proposal** is non-destructive. The `skillify` and `extensionify` tools analyze the session, generate a draft, validate it, and return it. They never write to disk and never reload anything, so they are safe for the model — or a subagent — to call.
+- **Activation** is human-gated. The persistent write and the live reload happen only at the `/skillify` and `/extensionify` commands in your main session, and only after you confirm the draft.
+
+Because activation lives only at the interactive layer, a subagent can at most produce a proposal — it can never persist or activate a capability on its own.
+
+## Skillify
+
+`/skillify` builds a [skill](skills.md) from what the session demonstrated:
+
+1. It captures the repeatable process — goal, inputs, outputs, success criteria, and any corrections you made along the way.
+2. It applies skill-authoring doctrine (a focused, one-job skill with clear frontmatter).
+3. It drafts the `SKILL.md` and validates the name and description.
+4. It runs [duplicate detection](#duplicate-detection) against your loaded skills.
+5. It shows you the draft. On your confirmation, it writes the skill to `~/.pi/agent/skills/<name>/` and reloads it so `/skill:<name>` works immediately.
+
+The doctrine skills it leans on (`skill-architect`, `pi-harness-learning`) ship with Pi as bundled skills, so skillify works out of the box. Like any bundled resource, they can be overridden by your own versions or filtered out with a [resource profile](resources.md).
+
+## Extensionify
+
+`/extensionify` scaffolds an [extension](extensions.md) — an `index.ts` factory that registers a tool or command, plus an optional `package.json` manifest.
+
+Before anything is offered for activation, the candidate is **smoke-tested in isolation**: Pi runs the generated factory against a throwaway runtime, never the live one. If it throws, times out, or fails validation, the proposal comes back rejected with diagnostics, and activation refuses to write or load it. Only a clean isolated load — and your explicit confirmation — lets the real extension be written to `~/.pi/agent/extensions/<name>/` and loaded live.
+
+## Learn
+
+`/learn` is the broader post-session pass. It summarizes the durable lesson and classifies it: is this a memory, a refinement to an existing skill, a brand-new skill, a prompt, an extension, or nothing worth keeping? It then routes the lesson to the matching proposal — `skillify` or `extensionify`, a targeted edit, or a note — and surfaces the result for you to activate.
+
+`/learn` orchestrates; it never writes or activates on its own. Long-term memory storage is handled outside Pi; `/learn` routes to it rather than implementing it.
+
+## Duplicate detection
+
+The `skill_audit` tool guards against accumulating near-identical skills. Given a draft's name, description, and body, it scans your loaded skills and scores keyword overlap. Matches above the similarity threshold are flagged so you can **merge or refine** an existing skill instead of adding a redundant one.
+
+It runs entirely locally — no network call, no embedding model — so it is safe and instant. You can also call it on its own to audit an existing set of skills for overlap.
+
+## Going live
+
+Activation finishes by hot-reloading the new capability through the same live load/unload path the [Resources hub](resources.md#manage-library) uses. A skill or extension you just approved is usable the moment it is written — the ingest → author → live loop closes in a single turn.

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "0.80.48",
+  "version": "0.80.50",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "0.80.48",
+      "version": "0.80.50",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-anthropic",
   "private": true,
-  "version": "0.80.48",
+  "version": "0.80.50",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-gitlab-duo",
   "private": true,
-  "version": "0.80.48",
+  "version": "0.80.50",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/sandbox/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-sandbox",
-	"version": "0.80.48",
+	"version": "0.80.50",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-sandbox",
-			"version": "0.80.48",
+			"version": "0.80.50",
 			"dependencies": {
 				"@anthropic-ai/sandbox-runtime": "^0.0.26"
 			}

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-sandbox",
 	"private": true,
-	"version": "0.80.48",
+	"version": "0.80.50",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/with-deps/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-with-deps",
-  "version": "0.80.48",
+  "version": "0.80.50",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-with-deps",
-      "version": "0.80.48",
+      "version": "0.80.50",
       "dependencies": {
         "ms": "^2.1.3"
       },

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-with-deps",
   "private": true,
-  "version": "0.80.48",
+  "version": "0.80.50",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/npm-shrinkwrap.json

@@ -1,17 +1,17 @@
 {
 	"name": "@caupulican/pi-adaptative",
-	"version": "0.80.51",
+	"version": "0.80.53",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@caupulican/pi-adaptative",
-			"version": "0.80.51",
+			"version": "0.80.53",
 			"license": "MIT",
 			"dependencies": {
-				"@caupulican/pi-agent-core": "^0.80.51",
-				"@caupulican/pi-ai": "^0.80.51",
-				"@caupulican/pi-tui": "^0.80.51",
+				"@caupulican/pi-agent-core": "^0.80.53",
+				"@caupulican/pi-ai": "^0.80.53",
+				"@caupulican/pi-tui": "^0.80.53",
 				"@silvia-odwyer/photon-node": "0.3.4",
 				"chalk": "5.6.2",
 				"cross-spawn": "7.0.6",
@@ -474,11 +474,11 @@
 			}
 		},
 		"node_modules/@caupulican/pi-agent-core": {
-			"version": "0.80.51",
-			"resolved": "https://registry.npmjs.org/@caupulican/pi-agent-core/-/pi-agent-core-0.80.51.tgz",
+			"version": "0.80.53",
+			"resolved": "https://registry.npmjs.org/@caupulican/pi-agent-core/-/pi-agent-core-0.80.53.tgz",
 			"license": "MIT",
 			"dependencies": {
-				"@caupulican/pi-ai": "^0.80.51",
+				"@caupulican/pi-ai": "^0.80.53",
 				"ignore": "7.0.5",
 				"typebox": "1.1.38",
 				"yaml": "2.9.0"
@@ -488,8 +488,8 @@
 			}
 		},
 		"node_modules/@caupulican/pi-ai": {
-			"version": "0.80.51",
-			"resolved": "https://registry.npmjs.org/@caupulican/pi-ai/-/pi-ai-0.80.51.tgz",
+			"version": "0.80.53",
+			"resolved": "https://registry.npmjs.org/@caupulican/pi-ai/-/pi-ai-0.80.53.tgz",
 			"license": "MIT",
 			"dependencies": {
 				"@anthropic-ai/sdk": "0.91.1",
@@ -511,8 +511,8 @@
 			}
 		},
 		"node_modules/@caupulican/pi-tui": {
-			"version": "0.80.51",
-			"resolved": "https://registry.npmjs.org/@caupulican/pi-tui/-/pi-tui-0.80.51.tgz",
+			"version": "0.80.53",
+			"resolved": "https://registry.npmjs.org/@caupulican/pi-tui/-/pi-tui-0.80.53.tgz",
 			"license": "MIT",
 			"dependencies": {
 				"get-east-asian-width": "1.6.0",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@caupulican/pi-adaptative",
-	"version": "0.80.51",
+	"version": "0.80.53",
 	"description": "Adaptive fork of Pi coding agent for self-evolving agent harness experiments",
 	"type": "module",
 	"piConfig": {
@@ -41,9 +41,9 @@
 		"prepublishOnly": "npm run clean && npm run build && npm run shrinkwrap"
 	},
 	"dependencies": {
-		"@caupulican/pi-agent-core": "^0.80.51",
-		"@caupulican/pi-ai": "^0.80.51",
-		"@caupulican/pi-tui": "^0.80.51",
+		"@caupulican/pi-agent-core": "^0.80.53",
+		"@caupulican/pi-ai": "^0.80.53",
+		"@caupulican/pi-tui": "^0.80.53",
 		"@silvia-odwyer/photon-node": "0.3.4",
 		"chalk": "5.6.2",
 		"cross-spawn": "7.0.6",