@lebronj/pi-suite 0.1.4 → 0.1.5

package/README.md

@@ -15,7 +15,7 @@ pi install npm:pi-subagents
 Or use the bootstrap script to install Pi, configure the team OpenAI-compatible endpoint, install this suite, and set up Bun + qmd for memory search:
 
 ```bash
-curl -fsSL https://registry.npmjs.org/@lebronj/pi-suite/-/pi-suite-0.1.3.tgz | tar -xzO package/scripts/bootstrap.sh | bash
+curl -fsSL https://registry.npmjs.org/@lebronj/pi-suite/-/pi-suite-0.1.5.tgz | tar -xzO package/scripts/bootstrap.sh | bash
 ```
 
 ## What Is Included
@@ -23,7 +23,7 @@ curl -fsSL https://registry.npmjs.org/@lebronj/pi-suite/-/pi-suite-0.1.3.tgz | t
 - Local extensions: goal mode, pet, prompt URL widget, TUI redraw stats, snake, TPS notifications.
 - Prompts: changelog audit, issue analysis, PR review, wrap workflow.
 - Skills: provider checklist, weather, LeetCode array practice, Pi capability reference, image-to-editable-PPT workflow.
-- Vendored package: `@jhp/pi-memory`.
+- Vendored package: `@jhp/pi-memory`, including qmd search, external curator service, and memory/skill-draft versioning.
 
 Install optional packages separately if needed:
 
@@ -49,7 +49,7 @@ The bootstrap script asks for an API key and writes:
 
 The API key is written to `~/.pi/agent/models.json` on the user's machine. Do not publish a shared key in this package.
 
-## Memory Search
+## Memory And Versioning
 
 `@jhp/pi-memory` works without qmd for core memory features:
 
@@ -67,6 +67,20 @@ qmd collection add ~/.pi/agent/memory --name pi-memory
 qmd embed
 ```
 
+Memory versioning is enabled by default. It snapshots `~/.pi/agent/memory` and `~/.pi/agent/skill-drafts` into `~/.pi/agent/evolution`, commits local changes automatically, and leaves push manual by default.
+
+Useful commands:
+
+```bash
+/memory-version-status
+/memory-version-snapshot optional reason
+/memory-version-list
+/memory-version-restore <snapshot-id> [memory|skill-drafts|all]
+/memory-version-push
+```
+
+Default evolution remote: `https://github.com/LRM-Teams/pi-evolution.git`. Keep it private because it stores memory plaintext. Set `PI_EVOLUTION_AUTO_PUSH=1` only if automatic remote sync is desired.
+
 ## Goal Mode
 
 Use `/goal <objective>` to keep Pi working on one task until it is verified complete. Goal mode injects hidden task context, enables a `goal` tool for completion/drop/resume, and auto-continues between turns instead of stopping at a minimal implementation.

package/extensions/goal-mode.ts

@@ -192,6 +192,10 @@ export default function goalModeExtension(pi: ExtensionAPI): void {
 		if (previousTools) {
 			pi.setActiveTools(previousTools);
 			previousTools = undefined;
+			return;
+		}
+		if (activeTools.includes(GOAL_TOOL_NAME)) {
+			pi.setActiveTools(activeTools.filter((tool) => tool !== GOAL_TOOL_NAME));
 		}
 	}
 
@@ -421,6 +425,8 @@ export default function goalModeExtension(pi: ExtensionAPI): void {
 		autoContinue = restored.autoContinue;
 		if (goal?.status === "active") {
 			setGoalToolEnabled(true);
+		} else {
+			setGoalToolEnabled(false);
 		}
 		updateUi(ctx);
 	});

package/extensions/pet.ts

@@ -23,6 +23,9 @@
 
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import { complete, type Message } from "@earendil-works/pi-ai";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 import {
 	BorderedLoader,
 	convertToLlm,
@@ -112,6 +115,7 @@ const PET_ITEMS: PetItem[] = [
 	{ id: "violet-badge", name: "Violet Badge", rarity: "epic", glyph: "#", color: "error", trigger: "memory" },
 	{ id: "star-crown", name: "Star Crown", rarity: "legendary", glyph: "^", color: "warning", trigger: "memory" },
 ];
+const PERSISTED_PET_PROFILE_FILE = join(homedir(), ".pi", "agent", "pet-profile.json");
 const PET_COMMAND_COMPLETIONS: PetCommandCompletion[] = [
 	{ name: "on", description: "Show the pet" },
 	{ name: "off", description: "Hide the pet" },
@@ -244,6 +248,105 @@ const PET_ART: Record<PetKind, Record<PetMood | "blink" | "sleep", string[][]>>
 	},
 };
 
+function colorItemGlyph(item: PetItem, theme: Theme, glyph = item.glyph): string {
+	return item.rarity === "common" ? glyph : theme.fg(item.color, glyph);
+}
+
+function replaceFirstMatch(lines: string[], replacements: Array<[string, string]>): string[] {
+	return lines.map((line) => {
+		for (const [from, to] of replacements) {
+			if (line.includes(from)) return line.replace(from, to);
+		}
+		return line;
+	});
+}
+
+function chestReplacements(species: PetKind, mark: string): Array<[string, string]> {
+	switch (species) {
+		case "cat":
+			return [["> ^ <", `> ${mark} <`]];
+		case "dog":
+			return [["\\_^_/", `\\_${mark}_/`]];
+		case "fox":
+			return [["\\ v /", `\\ ${mark} /`]];
+		case "bot":
+			return [["|___|", `|_${mark}_|`]];
+	}
+}
+
+function scarfReplacements(species: PetKind): Array<[string, string]> {
+	switch (species) {
+		case "cat":
+			return [["> ^ <", "~ ^ ~"]];
+		case "dog":
+			return [["\\_^_/", "~_^_~"]];
+		case "fox":
+			return [["\\ v /", "~ v ~"]];
+		case "bot":
+			return [["|___|", "|~~~|"]];
+	}
+}
+
+function lensReplacements(species: PetKind, lens: string): Array<[string, string]> {
+	switch (species) {
+		case "cat":
+		case "fox":
+			return [
+				["( o.o )", `( ${lens}.o )`],
+				["( -.- )", `( ${lens}.- )`],
+				["( ^.^ )", `( ${lens}.^ )`],
+				["( >.< )", `( ${lens}.< )`],
+			];
+		case "dog":
+			return [
+				["( o o )", `( ${lens} o )`],
+				["( - - )", `( ${lens} - )`],
+				["( ^ ^ )", `( ${lens} ^ )`],
+				["( > < )", `( ${lens} < )`],
+			];
+		case "bot":
+			return [
+				["[ o_o ]", `[ ${lens}_o ]`],
+				["[ -_- ]", `[ ${lens}_- ]`],
+				["[ ^_^ ]", `[ ${lens}_^ ]`],
+				["[ >_< ]", `[ ${lens}_< ]`],
+			];
+	}
+}
+
+function addItemParticles(lines: string[], item: PetItem, theme: Theme, frame: number): string[] {
+	if (item.rarity !== "epic" && item.rarity !== "legendary") return lines;
+	const glyphs = item.rarity === "legendary" ? ["*", "+", "."] : ["*", "."];
+	const left = theme.fg(item.color, glyphs[frame % glyphs.length] ?? "*");
+	const right = theme.fg(item.color, glyphs[(frame + 1) % glyphs.length] ?? "+");
+	if (item.rarity === "legendary") return [`    ${left} ${colorItemGlyph(item, theme, "^")} ${right}`, ...lines];
+	return lines.map((line, index) => (index === 0 ? `${left} ${line} ${right}` : line));
+}
+
+function decoratePetArt(species: PetKind, art: string[], item: PetItem | undefined, theme: Theme, frame: number): string[] {
+	if (!item) return [...art];
+	const mark = colorItemGlyph(item, theme);
+	let lines = [...art];
+
+	switch (item.id) {
+		case "memory-lens":
+			lines = replaceFirstMatch(lines, lensReplacements(species, mark));
+			break;
+		case "green-scarf":
+			lines = replaceFirstMatch(lines, scarfReplacements(species));
+			break;
+		case "tin-bell":
+		case "amber-token":
+		case "violet-badge":
+			lines = replaceFirstMatch(lines, chestReplacements(species, mark));
+			break;
+		case "star-crown":
+			break;
+	}
+
+	return addItemParticles(lines, item, theme, frame);
+}
+
 class PetComponent implements Component {
 	private profile: PetProfile;
 	private mood: PetMood = "idle";
@@ -299,9 +402,10 @@ class PetComponent implements Component {
 	render(width: number): string[] {
 		const pose = this.getPose();
 		const frames = PET_ART[this.profile.species][pose];
-		const art = frames[this.frame % frames.length] ?? frames[0];
+		const baseArt = frames[this.frame % frames.length] ?? frames[0];
 		const equipped = getPetItem(this.profile.equippedItemId);
-		const charm = equipped ? ` ${this.theme.fg(equipped.color, equipped.glyph)}` : "";
+		const art = decoratePetArt(this.profile.species, baseArt, equipped, this.theme, this.frame);
+		const charm = equipped ? ` ${colorItemGlyph(equipped, this.theme)}` : "";
 		const title = `${this.profile.name} ${this.profile.rarity} ${this.profile.personality}`;
 		const label = this.theme.fg("accent", `pet:${this.profile.species}`);
 		const mood = this.theme.fg("dim", this.mood);
@@ -374,6 +478,23 @@ function defaultProfile(): PetProfile {
 	};
 }
 
+function readPersistedProfile(): PetProfile | undefined {
+	try {
+		return normalizeProfile(JSON.parse(readFileSync(PERSISTED_PET_PROFILE_FILE, "utf8")));
+	} catch {
+		return undefined;
+	}
+}
+
+function writePersistedProfile(profile: PetProfile): void {
+	try {
+		mkdirSync(dirname(PERSISTED_PET_PROFILE_FILE), { recursive: true });
+		writeFileSync(PERSISTED_PET_PROFILE_FILE, `${JSON.stringify(profile, undefined, 2)}\n`, "utf8");
+	} catch {
+		// Session-local pet state still works if the durable profile cannot be written.
+	}
+}
+
 function normalizeProfile(value: unknown): PetProfile | undefined {
 	if (!value || typeof value !== "object") return undefined;
 	const partial = value as Partial<PetProfile>;
@@ -655,16 +776,26 @@ export default function petExtension(pi: ExtensionAPI) {
 	let agentRunning = false;
 
 	function saveProfile(): void {
+		writePersistedProfile(profile);
 		pi.appendEntry(PET_PROFILE_TYPE, profile);
 	}
 
 	function restoreProfile(ctx: ExtensionContext): void {
+		const durableProfile = readPersistedProfile();
+		if (durableProfile) {
+			profile = durableProfile;
+			return;
+		}
+
 		const entries = ctx.sessionManager.getEntries();
 		for (let i = entries.length - 1; i >= 0; i--) {
 			const entry = entries[i];
 			if (entry.type !== "custom" || entry.customType !== PET_PROFILE_TYPE) continue;
 			const saved = normalizeProfile(entry.data);
-			if (saved) profile = saved;
+			if (saved) {
+				profile = saved;
+				writePersistedProfile(profile);
+			}
 			return;
 		}
 	}

package/extensions/simple-replies.ts

@@ -0,0 +1,10 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function simpleRepliesExtension(pi: ExtensionAPI): void {
+	pi.on("before_agent_start", async (event) => {
+		if (event.prompt.trim().toLowerCase() !== "hi") return undefined;
+		return {
+			systemPrompt: `${event.systemPrompt}\n\nFor this turn only, the user's entire message is "hi". Reply exactly: hi`,
+		};
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lebronj/pi-suite",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "JHP's Pi extension suite for team coding workflows",
   "type": "module",
   "keywords": [

package/scripts/bootstrap.sh

@@ -94,12 +94,49 @@ link_if_safe() {
 WORKSPACE_DIR="${PI_WORKSPACE_DIR:-$PWD}"
 WORKSPACE_PI_DIR="$WORKSPACE_DIR/.pi"
 MEMORY_DIR="$AGENT_DIR/memory"
+EVOLUTION_DIR="${PI_EVOLUTION_DIR:-$AGENT_DIR/evolution}"
+EVOLUTION_REMOTE="${PI_EVOLUTION_REMOTE:-https://github.com/LRM-Teams/pi-evolution.git}"
+EVOLUTION_BRANCH="${PI_EVOLUTION_BRANCH:-main}"
 SUITE_SKILLS_DIR="${PI_SUITE_SKILLS_DIR:-$AGENT_DIR/npm/node_modules/@lebronj/pi-suite/skills}"
 
 mkdir -p "$MEMORY_DIR"
 link_if_safe "$MEMORY_DIR" "$WORKSPACE_PI_DIR/memory" "memory"
 link_if_safe "$SUITE_SKILLS_DIR" "$WORKSPACE_PI_DIR/skills" "skills"
 
+setup_evolution_repo() {
+  if [ "${PI_EVOLUTION_ENABLED:-1}" = "0" ]; then
+    echo "Memory evolution versioning disabled by PI_EVOLUTION_ENABLED=0."
+    return 0
+  fi
+  if ! command -v git >/dev/null 2>&1; then
+    echo "Skip memory evolution repo setup: git is not installed."
+    return 0
+  fi
+  if [ -e "$EVOLUTION_DIR" ] && [ ! -d "$EVOLUTION_DIR/.git" ]; then
+    if [ -z "$(find "$EVOLUTION_DIR" -mindepth 1 -maxdepth 1 -print -quit 2>/dev/null)" ]; then
+      rmdir "$EVOLUTION_DIR"
+    else
+      echo "Skip memory evolution repo setup: $EVOLUTION_DIR exists and is not a git repo."
+      return 0
+    fi
+  fi
+  if [ ! -e "$EVOLUTION_DIR" ]; then
+    mkdir -p "$(dirname "$EVOLUTION_DIR")"
+    if ! git clone --branch "$EVOLUTION_BRANCH" "$EVOLUTION_REMOTE" "$EVOLUTION_DIR"; then
+      mkdir -p "$EVOLUTION_DIR"
+      git -C "$EVOLUTION_DIR" init -b "$EVOLUTION_BRANCH" 2>/dev/null || git -C "$EVOLUTION_DIR" init
+      git -C "$EVOLUTION_DIR" checkout -B "$EVOLUTION_BRANCH" >/dev/null 2>&1 || true
+      git -C "$EVOLUTION_DIR" remote add origin "$EVOLUTION_REMOTE" 2>/dev/null || true
+    fi
+  fi
+  mkdir -p "$EVOLUTION_DIR/memory" "$EVOLUTION_DIR/skill-drafts" "$EVOLUTION_DIR/snapshots" "$EVOLUTION_DIR/manifests"
+  echo "Memory evolution repo ready: $EVOLUTION_DIR"
+  echo "Remote: $EVOLUTION_REMOTE"
+  echo "Auto push remains off by default. Use /memory-version-push or PI_EVOLUTION_AUTO_PUSH=1."
+}
+
+setup_evolution_repo
+
 ensure_bun() {
   if command -v bun >/dev/null 2>&1; then
     return 0

package/skills/pi-skill/SKILL.md

@@ -5,11 +5,11 @@ description: Reference for this pi agent's installed capabilities, tools, memory
 
 # Pi Skill
 
-This skill is the local capability index for this pi setup. Use it to answer "what can you do?", choose the right tool/workflow, and keep user-facing capability docs synchronized when features change.
+This skill is the local capability index for this pi setup. Use it to answer "what can you do?", choose the right workflow, and keep user-facing capability docs synchronized when features change.
 
 ## Maintenance Rule
 
-When adding, removing, renaming, or materially changing any pi capability in this workspace, update this skill in the same change. This includes tools, packages, extensions, memory behavior, skills, subagents, MCP servers, web/search integrations, and code-intelligence workflows.
+When adding, removing, renaming, or materially changing any pi capability in this workspace, update this skill in the same change. This includes tools, packages, extensions, memory behavior, skills, subagents, MCP servers, web/search integrations, code-intelligence workflows, commands, prompt templates, and bootstrap behavior.
 
 ## Core Coding Tools
 
@@ -17,24 +17,27 @@ When adding, removing, renaming, or materially changing any pi capability in thi
 - `bash`: run shell commands; prefer `rg`/`rg --files` for search.
 - `edit`: precise exact-text replacements in one file.
 - `write`: create or overwrite files.
-- `lsp_diagnostics` / `lsp_navigation`: primary code-intelligence path for diagnostics, definitions, references, hover, symbols, call hierarchy, rename, and workspace diagnostics.
-- `ast_grep_search` / `ast_grep_replace` / `ast_dump`: semantic AST-aware code search and replacement; prefer over raw text search for code patterns.
-- `lens_diagnostics`: inspect pi-lens warnings/errors for files touched this session.
+- `goal`: inspect, resume/drop, or complete an active goal-mode objective when goal mode is running.
+- `lsp_diagnostics` / `lsp_navigation`: code-intelligence path for diagnostics, definitions, references, hover, symbols, call hierarchy, rename, and workspace diagnostics when pi-lens/LSP tools are installed.
+- `ast_grep_search` / `ast_grep_replace` / `ast_dump`: AST-aware code search and replacement when pi-lens tools are installed; prefer over raw text search for structural code patterns.
+- `lens_diagnostics`: inspect pi-lens warnings/errors for files touched this session when available.
 
-## Memory
+## Memory And Self-Evolution
 
-Installed memory package: `@jhp/pi-memory` from `.pi/packages/pi-memory`.
+Installed memory capability comes from `@jhp/pi-memory`, vendored inside `@lebronj/pi-suite` and also usable as a standalone pi package.
 
 Memory files live under `~/.pi/agent/memory/`:
 
 - `MEMORY.md`: durable facts, decisions, and preferences.
 - `USER.md`: structured user profile and stable preferences.
 - `STATE.md`: current dated state, events, temporary facts, and quotas.
-- `REVIEW.md`: review queue for stale or merge-candidate memories.
+- `REVIEW.md`: review queue for stale memories, learning candidates, and promotion proposals.
 - `SCRATCHPAD.md`: checklist for open items.
-- `daily/YYYY-MM-DD.md`: daily append-only logs.
+- `daily/YYYY-MM-DD.md`: daily append-only logs and session handoffs.
 - `.curator-state.json`: last curator run state.
+- `.curator-service.json`: external curator service state.
 - `audit/curator.jsonl`: curator audit trail.
+- `~/.pi/agent/skill-drafts/<slug>/SKILL.md`: disabled skill drafts created after explicit approval.
 
 Memory tools:
 
@@ -44,9 +47,17 @@ Memory tools:
 - `scratchpad`: add/done/undo/clear/list checklist items.
 - `memory_search`: qmd-backed keyword, semantic, or deep search across memory files.
 - `memory_curate`: manually run curator lifecycle rules.
-- `memory_curator_enable`: enable external daily curator service using systemd user timer or cron fallback.
+- `memory_learning_approve`: approve a proposed memory promotion or disabled skill draft by exact id.
+- `memory_learning_reject`: reject or archive a review candidate/proposal without deleting it.
+- `memory_skill_drafts`: list proposed skill drafts.
+- `memory_curator_enable`: enable the external daily curator service using systemd user timer or cron fallback.
 - `memory_curator_disable`: disable and uninstall the external daily curator service.
 - `memory_curator_status`: show service backend, schedule, and state.
+- `memory_version_status`: show local evolution repo status, remote, branch, dirty state, last commit, and auto-push setting.
+- `memory_version_snapshot`: manually snapshot `memory/` and `skill-drafts/`, sync mirrors, and commit.
+- `memory_version_list`: list recent snapshots.
+- `memory_version_restore`: restore `memory`, `skill-drafts`, or `all` from a snapshot id after creating a pre-restore backup.
+- `memory_version_push`: manually push the local evolution repo to GitHub.
 
 Structured metadata example:
 
@@ -55,18 +66,65 @@ Structured metadata example:
 User plans to watch the NBA Finals.
 ```
 
-Curator behavior:
+Curator and learning behavior:
 
-- Exact dedupe.
-- Event status transitions: `planned -> today -> past`.
+- Exact duplicate entries are deduplicated.
+- Event status transitions: `planned -> today -> past` based on `date`.
 - Expired temporary memories go to `REVIEW.md`, not automatic deletion.
-- Quotas reset when month/reset rolls over.
+- Quotas reset when `month` or `reset` rolls over.
 - Mutations are audited to `audit/curator.jsonl`.
-- External service control lives in `@jhp/pi-memory`: `jhp-pi-memory-curator enable|disable|status|run-once`.
-- The external curator service is independent of the pi process. It uses a systemd user timer when available, with cron fallback, so scheduled curation can run even when pi is closed.
-- Users can ask pi to enable, disable, or inspect the service via `memory_curator_enable`, `memory_curator_disable`, and `memory_curator_status`.
+- Session shutdown may extract conservative learning candidates into `REVIEW.md`; they are not injected as normal memory and are not auto-enabled.
+- Repeated candidates can become proposed memory promotions or proposed disabled skill drafts after `memory_curate`.
+- Approval is explicit by default: memory proposals write to memory stores; skill proposals write disabled drafts under `~/.pi/agent/skill-drafts/`.
+- The curator avoids semantic auto-delete/merge; ambiguous learning stays in review first.
+
+Memory versioning:
+
+- Runtime memory remains authoritative at `~/.pi/agent/memory`; disabled skill drafts remain authoritative at `~/.pi/agent/skill-drafts`.
+- Versioning mirror and snapshots live at `~/.pi/agent/evolution` by default.
+- Default remote is `https://github.com/LRM-Teams/pi-evolution.git`; it should be private because memory is committed in plaintext.
+- Automatic local snapshot + commit is enabled by default; automatic push is disabled unless `PI_EVOLUTION_AUTO_PUSH=1`.
+- Snapshots run before mutating memory tools, curator runs, learning approve/reject, session summaries/handoffs, compact handoffs, restore, and external curator `run-once`.
+- Slash commands: `/memory-version-status`, `/memory-version-snapshot [reason]`, `/memory-version-list`, `/memory-version-restore <snapshot-id> [memory|skill-drafts|all]`, `/memory-version-push`.
+- Restore always writes a pre-restore snapshot first, then restores selected files and commits the restored state.
+
+External curator service:
+
+- This is the main self-evolution maintenance loop: it can run daily outside the pi process, even when pi is closed.
+- It uses a systemd user timer when available, with cron fallback.
+- On `session_start` and after `/reload`, pi-memory checks service status. If the service is disabled and UI is available, it shows a startup hint with enable/status/disable commands.
+- Enable with `/memory-curator-enable 03:00` or ask the agent to call `memory_curator_enable`.
+- Inspect with `/memory-curator-status` or `memory_curator_status`.
+- Disable with `/memory-curator-disable` or `memory_curator_disable`.
+- CLI equivalent: `jhp-pi-memory-curator enable|disable|status|run-once` when the binary is linked by the package manager.
+- Disable startup hints with `PI_MEMORY_CURATOR_STARTUP_HINT=0` if a user does not want reminders.
 - Before uninstalling `@jhp/pi-memory`, run `memory_curator_disable` or `jhp-pi-memory-curator disable` so any systemd timer or cron entry is removed.
-- `.pi/extensions/memory-curator.ts` is deprecated and only warns users to use `@jhp/pi-memory` service tools.
+
+QMD search:
+
+- Core memory works without qmd.
+- `memory_search` requires qmd for keyword, semantic, and deep search.
+- Bootstrap attempts to install Bun + qmd, adds `~/.pi/agent/memory` as the `pi-memory` collection, and runs `qmd embed`.
+- After writes, qmd updates run in the background by default; use `PI_MEMORY_QMD_UPDATE=manual` or `off` to change that.
+
+Useful memory environment variables:
+
+- `PI_MEMORY_DIR`: override memory storage directory.
+- `PI_MEMORY_SNAPSHOT`: `stable` or `per-turn` context injection mode.
+- `PI_MEMORY_QMD_UPDATE`: `background`, `manual`, or `off`.
+- `PI_MEMORY_NO_SEARCH=1`: disable per-turn search injection.
+- `PI_MEMORY_SUMMARIZE_TRANSITIONS=1`: also summarize lifecycle transitions such as `/reload`.
+- `PI_MEMORY_LEARNING`: `off`, `review`, or `auto-review`.
+- `PI_MEMORY_SKILL_DRAFTS`: `off` or `review`.
+- `PI_MEMORY_AUTO_APPROVE_MEMORY=1`: automatically approve newly created memory proposals.
+- `PI_MEMORY_AUTO_APPROVE_SKILL_DRAFTS=1`: automatically create newly proposed disabled skill drafts.
+- `PI_MEMORY_CURATOR_STARTUP_HINT=0`: hide the disabled-curator startup hint.
+- `PI_EVOLUTION_ENABLED=0`: disable snapshot + git versioning.
+- `PI_EVOLUTION_DIR`: override evolution repo directory; default `~/.pi/agent/evolution`.
+- `PI_EVOLUTION_REMOTE`: override remote; default `https://github.com/LRM-Teams/pi-evolution.git`.
+- `PI_EVOLUTION_BRANCH`: override branch; default `main`.
+- `PI_EVOLUTION_AUTO_COMMIT=0`: disable automatic local commits.
+- `PI_EVOLUTION_AUTO_PUSH=1`: push automatically after commits.
 
 ## Web And Research
 
@@ -74,11 +132,11 @@ Curator behavior:
 - `fetch_content`: fetch readable content from URLs, GitHub repos, YouTube transcripts/video frames, and local videos. For video questions, pass the user's exact question as `prompt`.
 - `get_search_content`: retrieve full content saved by `web_search` or `fetch_content`.
 - `code_search`: search programming examples, docs, APIs, GitHub, and Stack Overflow; use for library/API/debugging questions before implementation.
-- `librarian` skill: use for evidence-backed open-source library internals with exact GitHub source citations.
+- `librarian` skill: use for evidence-backed open-source library internals with exact GitHub source citations when installed.
 
 ## Subagents
 
-Use the `pi-subagents` skill and `subagent` tool for delegation.
+Use the `pi-subagents` skill and `subagent` tool for delegation when installed.
 
 Typical uses:
 
@@ -95,7 +153,7 @@ Rules:
 
 ## MCP
 
-Use `mcp` to discover and call Model Context Protocol servers/tools.
+Use `mcp` to discover and call Model Context Protocol servers/tools when `pi-mcp-adapter` is installed.
 
 Common flow:
 
@@ -109,9 +167,36 @@ mcp({ tool: "tool_name", args: "{}" })
 
 Do not route built-in pi tools through MCP; call them directly.
 
-## Existing Skills
+## Goal Mode
+
+Goal mode is provided by `goal-mode.ts`.
+
+- Start with `/goal <objective>`.
+- It injects hidden goal context, enables the `goal` tool, and auto-continues until the objective is complete, paused, dropped, blocked, or interrupted.
+- The agent must verify current files/checks before calling `goal({ op: "complete" })`.
+- Useful commands: `/goal show`, `/goal pause`, `/goal resume`, `/goal drop`, `/goal auto on`, `/goal auto off`.
+
+## Pet Companion
+
+The pet extension provides a small terminal companion and durable profile.
+
+- Command: `/pet`.
+- Subcommands include `on`, `off`, `cat`, `dog`, `fox`, `bot`, `name`, `mood`, `checkin`, `feed`, `bag`, `equip`, `unequip`, `position`, `reset`, and `ask`.
+- `/pet ask <question>` answers from current context without saving the answer into the main session.
+- Item drops can happen from tool usage, memory events, and daily check-ins, with pity counters.
+- Pet profile/inventory is mirrored at `~/.pi/agent/pet-profile.json` so equipment survives `/new` and future sessions.
+
+## UI And Utility Extensions
 
-Local project skills currently include:
+- `prompt-url-widget.ts`: detects PR/issue prompt templates, fetches GitHub metadata with `gh`, shows a widget, and names the session when possible.
+- `redraws.ts`: `/tui` shows TUI full redraw stats.
+- `snake.ts`: `/snake` opens a TUI snake game; `Esc` pauses/saves, `q` quits, arrows/WASD move.
+- `tps.ts`: after each assistant run, shows tokens-per-second and token usage details.
+- `memory-curator.ts`: deprecated compatibility notice only; external curation is managed by pi-memory service tools.
+
+## Skills
+
+Suite skills currently include:
 
 - `add-llm-provider`: checklist for adding providers to `packages/ai`.
 - `image-to-editable-ppt-slide`: rebuild reference images as editable PowerPoint slides.
@@ -119,7 +204,7 @@ Local project skills currently include:
 - `weather`: current weather and forecasts using no-key services.
 - `pi-skill`: this capability index.
 
-Package-provided skills currently include:
+Optional package-provided skills can include:
 
 - `librarian`: library internals research with source citations.
 - `pi-subagents`: subagent delegation workflows.
@@ -128,11 +213,24 @@ Package-provided skills currently include:
 - `write-ast-grep-rule`: author pi-lens ast-grep rules.
 - `write-tree-sitter-rule`: author pi-lens tree-sitter rules.
 
-## Pi Package And Extension Notes
+## Prompt Templates
+
+Suite prompt templates currently include:
+
+- `/cl`: changelog audit workflow.
+- `/is`: issue analysis workflow.
+- `/pr`: GitHub PR review workflow.
+- `/wr`: wrap-up workflow with final comment guidance.
+
+## Package And Bootstrap Notes
+
+Global user package configuration is in `~/.pi/agent/settings.json`; project package configuration is in `.pi/settings.json` and `.pi/npm/package.json`.
+
+Current suite package:
 
-Project package configuration is in `.pi/settings.json` and `.pi/npm/package.json`.
+- `@lebronj/pi-suite`: bundles local extensions, prompts, suite skills, vendored `@jhp/pi-memory`, and optional package hooks for `pi-mcp-adapter`, `pi-subagents`, and `pi-web-access`.
 
-Current project packages:
+Common project packages:
 
 - `@jhp/pi-memory`
 - `pi-web-access`
@@ -140,16 +238,24 @@ Current project packages:
 - `pi-subagents`
 - `pi-lens`
 
-Project extensions are in `.pi/extensions/`. Important current extensions:
+Bootstrap behavior:
 
-- `pet.ts`: terminal pet UI with `/pet` subcommands, argument autocomplete for actions such as `/pet ask`, `/pet position`, and `/pet equip`, plus item drops with pity counters.
-- `memory-curator.ts`: deprecated compatibility notice only. The external curator service is managed by `@jhp/pi-memory`.
+- Installs global `@earendil-works/pi-coding-agent`.
+- Writes the team OpenAI-compatible provider to `~/.pi/agent/models.json`.
+- Sets default provider/model in `~/.pi/agent/settings.json`.
+- Runs `pi install npm:@lebronj/pi-suite` by default.
+- Creates `~/.pi/agent/memory` and links it into the workspace `.pi/memory` when safe.
+- Optionally initializes the local `~/.pi/agent/evolution` repo for memory/skill-draft snapshots; it never writes tokens or enables auto-push.
+- Links suite skills into the workspace `.pi/skills` when safe.
+- Installs Bun + qmd when possible and initializes the `pi-memory` qmd collection.
+- Does not auto-enable the external memory curator service; the startup hint explains how to enable it.
 
 ## Recommended Workflows
 
-- For code changes: inspect files, edit, run targeted tests if tests changed, then run `npm run check` for repo code changes.
+- For code changes: inspect files, edit deliberately, run targeted tests, then run the repo's relevant check command.
 - For memory changes: use `memory_write` for new facts and `memory_edit` for updates/removals.
 - For time-sensitive memory: write structured `STATE.md` entries with `type`, `status`, and date/reset metadata.
+- For self-evolution upkeep: keep the external curator service enabled unless the user opts out, and review `REVIEW.md` proposals before approving memory or skill promotions.
 - For web facts or current events: use `web_search`; for page/video details, use `fetch_content`.
 - For library internals: use `librarian` or `code_search` with source-backed evidence.
 - For broad or risky tasks: use subagents for investigation/review, then integrate deliberately.