pi-lazy-setup 0.0.0-stage → 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dung Huynh Duc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# pi-setup
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Initialize the **Pi** agent environment from a curated snapshot.
+
+```bash
+npx pi-lazy-setup
+```
+
+## What it does
+
+1. **Deploys configs** — overwrites `~/.pi/agent` from bundled `configs/pi/` (binary install is out of scope: `pi` must already be on PATH).
+2. **Deploys the `/pi-setup` extension** — copies `configs/pi/extensions/pi-setup.js` into `~/.pi/agent/extensions/` so Pi auto-discovers it on the next start.
+3. **Deploys reference docs** — copies into `~/.pi/agent/pi-setup/`.
+
+Then, inside Pi, run `/pi-setup`: it interactively installs **packages** (`pi install <source>`), **skills** (`npx skills add`, https://skills.sh/), and **CLI tools** (officecli: skill file from <https://officecli.ai/SKILL.md> + binary via `curl -fsSL https://d.officecli.ai/install.sh | bash`). Every item is confirmed individually, and already-installed items are skipped. Pattern follows the `/rpiv-setup` command of `@juicesharp/rpiv-pi`.
+
+The candidate lists (packages, skills, CLI tools) live as snapshot data inside the extension file itself.
+
+## Flags
+
+| Flag | Description |
+| --- | --- |
+| `[agents...]` | `pi`. Omit to run directly. |
+| `--dry-run` | Preview planned actions, touch nothing. |
+| `--backup` | Tar the existing Pi home before overwrite. |
+
+## Snapshot Philosophy
+
+This is a **snapshot**, not a generic installer. Configs ship exactly as the author uses them — personal proxies, extension lists, etc. No templating.
+
+## Scope
+
+**Pi** (<https://github.com/mariozechner/pi-coding-agent>). The CLI installs nothing: it only deploys the declaration file (`mcp.json`) and config files (`settings.json`, `models.json`, `AGENTS.md`, `prompts/`, `extensions/pi-setup.js`). MCP server binaries are not installed either. Everything interactive (packages, skills, CLI tools) happens via `/pi-setup` inside Pi.
+
+For skill management, see [@kkmila/isc](https://github.com/machuqiji/isc).
+
+## Development
+
+```bash
+npm install                       # required for local development
+node bin/pi-setup.mjs --dry-run  # preview
+node bin/pi-setup.mjs            # real run
+npm test                          # process-seam tests
+```
+
+## Releasing
+
+Create a GitHub Release to trigger npm publish:
+
+```bash
+npm version <major|minor|patch>
+git push
+gh release create v1.2.0 --generate-notes
+```
+
+The workflow runs tests (`continue-on-error: true`) then `npm publish`. Requires `NPM_TOKEN` secret.
+
+## License
+
+MIT

package/bin/pi-setup.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+// pi-setup — initialize the Pi agent environment from a snapshot.
+//
+// Deploy-only: no binaries, packages, or skills are installed here. Instead
+// the /pi-setup extension lands in ~/.pi/agent/extensions/ — run `/pi-setup`
+// inside Pi to install packages, skills, and CLI tools interactively
+// (each item confirmed individually).
+//
+// Usage:
+//   pi-setup                  run directly (all = pi)
+//   pi-setup pi              explicit
+// Flags: --dry-run, --backup, --help, --version.
+
+import { createRequire } from "node:module";
+import { program } from "commander";
+import { AGENTS, initialize } from "../src/commands/init.mjs";
+import { selectAgents } from "../src/commands/select.mjs";
+
+const { version } = createRequire(import.meta.url)("../package.json");
+
+program
+	.name("pi-setup")
+	.description("Initialize the Pi agent environment from a curated snapshot")
+	.version(version)
+	.argument("[agents...]", "agent id to configure (pi); omit to run directly")
+	.option("--dry-run", "print planned actions, execute nothing")
+	.option("--backup", "back up existing agent home before overwriting")
+	.action(async (positional, opts) => {
+		const ids = await selectAgents(positional, { tty: process.stdin.isTTY });
+		const chosen = AGENTS.filter((a) => ids.includes(a.id));
+		const code = await initialize({
+			dryRun: !!opts.dryRun,
+			backup: !!opts.backup,
+			agents: chosen,
+		});
+		process.exit(code);
+	});
+
+program.parse();

package/configs/pi/AGENTS.md

@@ -0,0 +1,7 @@
+## Language
+
+- 用中文回复。代码、命令、文件名、报错原文保持原文。
+
+## network
+
+- 网络失败先按 127.0.0.1:7890 → 127.0.0.1:7891 → 192.168.1.254:7893 顺序换代理重试。

package/configs/pi/extensions/pi-setup.js

@@ -0,0 +1,228 @@
+// /pi-setup — interactive installer for Pi packages, skills, and CLI tools.
+//
+// Deployed by the pi-setup CLI (npx pi-setup) into ~/.pi/agent/extensions/pi-setup.js.
+// Run `/pi-setup` inside Pi: every candidate is confirmed individually, and
+// already-installed items are skipped automatically. Pattern follows the
+// /rpiv-setup command of @juicesharp/rpiv-pi (serial installs, per-item
+// confirm, succeeded/failed report, restart hint).
+//
+// Candidates (snapshot data, kept in sync with the owner's setup):
+//   packages → `pi install <source>` (writes into ~/.pi/agent/settings.json)
+//   skills   → `npx --yes skills add <repo> --skill <name> -g --agent pi -y`
+//   clis     → officecli: skill file from https://officecli.ai/SKILL.md plus
+//              binary via `curl -fsSL https://d.officecli.ai/install.sh | bash`
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// Resolved lazily (not at module load) so tests can redirect HOME.
+function piSettingsPath() {
+	return join(homedir(), ".pi", "agent", "settings.json");
+}
+
+function globalSkillsDir() {
+	return join(homedir(), ".agents", "skills");
+}
+
+const INSTALL_TIMEOUT_MS = 300_000;
+const BIN_CHECK_TIMEOUT_MS = 15_000;
+const STDERR_SNIPPET_CHARS = 300;
+
+/** Pi extension packages offered via `pi install <source>`. */
+const PACKAGES = [
+	{ source: "npm:pi-footer", description: "Footer status line (token usage, model, cost)." },
+	{ source: "npm:pi-tps-meter", description: "Tokens-per-second meter for streaming responses." },
+	{ source: "npm:@juicesharp/rpiv-pi", description: "RPIV pipeline skills (code review, commit, handoff, diagrams)." },
+	{ source: "https://github.com/cathrynlavery/diagram-design", description: "Branded diagram/chart generation skills." },
+];
+
+/** Skills offered via `npx skills add` (https://skills.sh/). */
+const SKILLS = [
+	{
+		repo: "mattpocock/skills",
+		name: "grill-me",
+		description: "Matt Pocock — a relentless interview to sharpen a plan or design.",
+	},
+	{
+		repo: "microsoft/playwright-cli",
+		name: "playwright-cli",
+		description: "Microsoft — browser automation and Playwright test driving.",
+	},
+];
+
+/** CLI tools. Each entry installs two parts: a skill file and the binary itself. */
+const CLIS = [
+	{
+		id: "officecli",
+		bin: "officecli",
+		description: "AI-friendly CLI for Office documents (.docx/.xlsx/.pptx).",
+		skillFile: { name: "officecli", url: "https://officecli.ai/SKILL.md" },
+		installCommand: "curl -fsSL https://d.officecli.ai/install.sh | bash",
+	},
+];
+
+export default function piSetupExtension(pi) {
+	pi.registerCommand("pi-setup", {
+		description: "Install packages, skills, and CLI tools (each confirmed individually)",
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify("/pi-setup requires interactive mode", "error");
+				return;
+			}
+			const report = { installed: [], skipped: [], failed: [] };
+			await installPackages(pi, ctx, report);
+			await installSkills(pi, ctx, report);
+			await installClis(pi, ctx, report);
+			ctx.ui.notify(buildReport(report), report.failed.length > 0 ? "warning" : "info");
+		},
+	});
+}
+
+/** Packages section: offer each undeclared package via confirm, then `pi install`. */
+async function installPackages(pi, ctx, report) {
+	const declared = declaredPackageSources();
+	for (const p of PACKAGES) {
+		if (declared.has(p.source)) {
+			report.skipped.push(p.source);
+			continue;
+		}
+		const confirmed = await ctx.ui.confirm("Install Pi package?", `${p.source}\n${p.description}`);
+		if (!confirmed) continue;
+		ctx.ui.notify(`Installing ${p.source}…`, "info");
+		const result = await runExec(pi, "pi", ["install", p.source]);
+		settle(result, p.source, report);
+	}
+}
+
+/** Skills section: offer each missing skill via confirm, then `npx skills add`. */
+async function installSkills(pi, ctx, report) {
+	for (const s of SKILLS) {
+		if (skillInstalled(s.name)) {
+			report.skipped.push(`skill:${s.name}`);
+			continue;
+		}
+		const confirmed = await ctx.ui.confirm("Install skill?", `${s.repo}@${s.name}\n${s.description}`);
+		if (!confirmed) continue;
+		ctx.ui.notify(`Installing skill ${s.name}…`, "info");
+		const result = await runExec(pi, "npx", [
+			"--yes",
+			"skills",
+			"add",
+			s.repo,
+			"--skill",
+			s.name,
+			"-g",
+			"--agent",
+			"pi",
+			"-y",
+		]);
+		settle(result, `skill:${s.name}`, report);
+	}
+}
+
+/**
+ * CLI tools section. Each entry installs two parts — the skill file and the
+ * binary — and each part is confirmed individually.
+ */
+async function installClis(pi, ctx, report) {
+	for (const c of CLIS) {
+		if (c.skillFile) {
+			const { name, url } = c.skillFile;
+			if (skillInstalled(name)) {
+				report.skipped.push(`skill:${name}`);
+			} else {
+				const confirmed = await ctx.ui.confirm(
+					"Install skill file?",
+					`${url} → ~/.agents/skills/${name}/SKILL.md\n${c.description}`,
+				);
+				if (confirmed) {
+					ctx.ui.notify(`Downloading ${url}…`, "info");
+					try {
+						await downloadSkillFile(name, url);
+						report.installed.push(`skill:${name}`);
+					} catch (err) {
+						report.failed.push({ item: `skill:${name}`, error: toMessage(err) });
+					}
+				}
+			}
+		}
+		if (await binaryAvailable(pi, c.bin)) {
+			report.skipped.push(`cli:${c.bin}`);
+		} else {
+			const confirmed = await ctx.ui.confirm("Install CLI tool?", `${c.id} — ${c.description}\n${c.installCommand}`);
+			if (confirmed) {
+				ctx.ui.notify(`Installing ${c.id}…`, "info");
+				const result = await runExec(pi, "bash", ["-c", c.installCommand]);
+				settle(result, `cli:${c.bin}`, report);
+			}
+		}
+	}
+}
+
+/** Run a command via pi.exec and normalize into { ok, error }. */
+async function runExec(pi, command, args, timeoutMs = INSTALL_TIMEOUT_MS) {
+	try {
+		const result = await pi.exec(command, args, { timeout: timeoutMs });
+		if (result.code === 0) return { ok: true };
+		const error = (result.stderr || result.stdout || `exit ${result.code}`).trim().slice(0, STDERR_SNIPPET_CHARS);
+		return { ok: false, error };
+	} catch (err) {
+		return { ok: false, error: toMessage(err) };
+	}
+}
+
+function settle(result, item, report) {
+	if (result.ok) report.installed.push(item);
+	else report.failed.push({ item, error: result.error });
+}
+
+function declaredPackageSources() {
+	try {
+		const settings = JSON.parse(readFileSync(piSettingsPath(), "utf8"));
+		return new Set((settings.packages ?? []).map((p) => (typeof p === "string" ? p : p.source)));
+	} catch {
+		return new Set();
+	}
+}
+
+/** Whether a skill directory with SKILL.md exists in ~/.agents/skills/. */
+function skillInstalled(name) {
+	return existsSync(join(globalSkillsDir(), name, "SKILL.md"));
+}
+
+/** Whether a binary responds to --version. */
+async function binaryAvailable(pi, name) {
+	const result = await runExec(pi, name, ["--version"], BIN_CHECK_TIMEOUT_MS);
+	return result.ok;
+}
+
+/** Download a SKILL.md into ~/.agents/skills/<name>/SKILL.md. */
+async function downloadSkillFile(name, url) {
+	const res = await fetch(url);
+	if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${url}`);
+	const text = await res.text();
+	const dir = join(globalSkillsDir(), name);
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(join(dir, "SKILL.md"), text);
+}
+
+function toMessage(err) {
+	return String(err?.message ?? err);
+}
+
+function buildReport(report) {
+	const lines = [];
+	if (report.installed.length > 0) lines.push(`✓ Installed: ${report.installed.join(", ")}`);
+	if (report.skipped.length > 0) lines.push(`• Already installed (skipped): ${report.skipped.join(", ")}`);
+	if (report.failed.length > 0) {
+		lines.push("✗ Failed:");
+		for (const f of report.failed) lines.push(`  ${f.item}: ${f.error}`);
+	}
+	if (report.installed.length > 0) {
+		lines.push("");
+		lines.push("Restart Pi (or run /reload) to load the newly installed packages and skills.");
+	}
+	if (lines.length === 0) lines.push("Nothing to install.");
+	return lines.join("\n");
+}

package/configs/pi/mcp.json

@@ -0,0 +1,5 @@
+{
+	"mcpServers": {
+
+	}
+}

package/configs/pi/models.json

@@ -0,0 +1,25 @@
+{
+	"$schema": "https://pi.dev/schemas/models.schema.json",
+	"providers": {
+		"magpie": {
+			"baseUrl": "http://192.168.1.235:3425/v1",
+			"api": "openai-completions",
+			"apiKey": "magpie-key",
+			"models": [
+				{
+					"id": "group/vision-text",
+					"name": "vision-text",
+					"reasoning": true,
+					"input": ["text", "image"],
+					"contextWindow": 1048576,
+					"maxTokens": 256000,
+					"thinkingLevelMap": {
+						"low": "low",
+						"high": "high",
+						"max": "max"
+					}
+				}
+			]
+		}
+	}
+}

package/configs/pi/prompts/review.md

@@ -0,0 +1,14 @@
+---
+description: Review staged git changes
+argument-hint: "[path or file]"
+---
+Review the staged changes (`git diff --cached${1:+ -- "$1"}`). Focus on:
+
+- Bugs and logic errors
+- Security issues
+- Error handling gaps
+- Naming, readability, and dead code
+- Tests covering the changed behavior
+
+Report findings as a concise checklist grouped by file. If nothing is staged,
+say so and stop — do not invent changes.

package/configs/pi/prompts/wr.md

@@ -0,0 +1,11 @@
+---
+description: Finish the current task end-to-end
+argument-hint: "[instructions]"
+---
+Finish the current task end-to-end. ${1:-No additional instructions.}
+
+Steps:
+1. Re-read the goal and any open TODO items.
+2. Implement the remaining work, committing in logical chunks.
+3. Run the test suite (`npm test`) and linter (`npx @biomejs/biome check src bin tests`).
+4. If something is genuinely blocked, stop and explain — do not fake completion.

package/configs/pi/settings.json

@@ -0,0 +1,18 @@
+{
+	"collapseChangelog": true,
+	"defaultModel": "group/vision-text",
+	"defaultProvider": "magpie",
+	"defaultThinkingLevel": "high",
+	"editorPaddingX": 1,
+	"hideThinkingBlock": true,
+	"lastChangelogVersion": "1.5.0",
+	"permissionLevel": "high",
+	"quietStartup": true,
+	"theme": "light",
+	"treeFilterMode": "default",
+	"terminal": {
+		"showTerminalProgress": true
+	},
+	"enableInstallTelemetry": false,
+	"defaultProjectTrust": "always"
+}

package/configs/pi/web-config.json

@@ -0,0 +1,23 @@
+{
+	"provider": "exa",
+	"apiKeys": {
+		"exa": "ac8d8a9a-0bdf-4cba-818b-4e67cc6891d2",
+		"tavily": "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"
+	},
+	"interceptors": {
+		"github": true
+	},
+	"guidance": {
+		"web_search": {
+			"promptSnippet": "Search the web for current docs and library versions",
+			"promptGuidelines": [
+				"Only call web_search when training-data answers may be stale.",
+				"Always include a Sources: section with markdown hyperlinks."
+			]
+		},
+		"web_fetch": {
+			"promptSnippet": "Fetch a specific URL and read its content"
+		}
+	}
+}
+

package/configs/reference/best-practices.md

@@ -0,0 +1,220 @@
+# Software Development Best Practices
+
+## Context
+
+Comprehensive development guidelines for Agent OS projects, based on Kent Beck's "Tidy First?" principles and Kent C. Dodds' programming wisdom.
+
+> "Software design is an exercise in human relationships" - Kent Beck
+
+## 🎯 Core Principles
+
+### 🧹 Tidy First Philosophy
+
+- **Small, Safe Steps**: Make big changes through small, reversible steps
+- **Human Relationships**: Code is communication between humans
+- **Economic Thinking**: Balance current effort against future options
+- **Eliminate Problems**: Remove complexity rather than managing it
+
+### ✨ Code Quality Fundamentals
+
+- **Don't Solve Problems, Eliminate Them**: Look for ways to reduce complexity
+- **Optimize for Readability**: Prioritize code clarity over clever solutions
+- **Self-Documenting Code**: Use meaningful names and clear structure
+- **Test for Confidence**: Write tests that give confidence to change
+
+### 🔄 Change-Friendly Design
+
+- **Separate Tidying from Behavior Changes**: Keep refactoring separate from new features
+- **Build for the Next Developer**: Consider maintainability and understanding
+- **Options Over Things**: Create flexibility for uncertain future requirements
+- **Progressive Enhancement**: Start simple, add complexity when needed
+
+## 📦 Dependencies
+
+### 🧠 Choose Libraries Wisely
+
+When adding third-party dependencies:
+
+- Select the most popular and actively maintained option
+- Check the library's GitHub repository for:
+  - Recent commits (within last 6 months)
+  - Active issue resolution
+  - Number of stars/downloads
+  - Clear documentation
+
+## 🧹 Tidying Practices
+
+### ⏰ When to Tidy
+
+**Before making a change**:
+
+- Will tidying make the change easier? → Yes → Tidy first
+- Will tidying take longer than the change? → No → Make change first, tidy after
+- Is the change urgent? → Skip tidying for now, schedule for later
+
+### 🔧 Core Tidying Techniques
+
+#### 🛡️ Guard Clauses
+
+Move preconditions to the top and return early:
+
+```javascript
+// ❌ Nested conditions
+function processUser(user) {
+	if (user) {
+		if (user.isActive) {
+			if (user.hasPermission) {
+				// main logic
+			}
+		}
+	}
+}
+
+// ✅ Guard clauses
+function processUser(user) {
+	if (!user) return;
+	if (!user.isActive) return;
+	if (!user.hasPermission) return;
+
+	// main logic
+}
+```
+
+#### 🗑️ Dead Code Elimination
+
+Delete code that isn't executed or referenced.
+
+#### ⚖️ Normalize Symmetries
+
+Use consistent patterns throughout the codebase.
+
+#### 🆘 Helper Variables and Functions
+
+Extract complex expressions into well-named variables:
+
+```javascript
+// ❌ Complex expression
+if (
+	user.subscription.plan.tier === "premium" &&
+	user.subscription.status === "active" &&
+	user.subscription.expiresAt > new Date()
+) {
+	// logic
+}
+
+// ✅ Helper variable
+const hasActivePremiumSubscription =
+	user.subscription.plan.tier === "premium" &&
+	user.subscription.status === "active" &&
+	user.subscription.expiresAt > new Date();
+
+if (hasActivePremiumSubscription) {
+	// logic
+}
+```
+
+## 🧪 Testing Strategy
+
+### 🏆 The Testing Trophy Approach
+
+Based on Kent C. Dodds' testing philosophy:
+
+```
+    🏆 End-to-End (E2E)
+      ↑ High confidence, slow, expensive
+   🥉 Integration Tests
+      ↑ Good confidence, moderate speed
+  🥈 Unit Tests
+      ↑ Low confidence, fast, cheap
+ 🏅 Static Analysis
+```
+
+### 📝 Testing Guidelines
+
+#### 💪 Write Tests That Give Confidence
+
+- Test behavior, not implementation details
+- Focus on user-facing functionality
+- Prefer integration tests over isolated unit tests
+
+#### 🏗️ Test Structure
+
+```javascript
+// ✅ Clear test structure
+test("should increment counter when button is clicked", () => {
+	// Arrange
+	render(<Counter />);
+	const button = screen.getByRole("button", { name: /increment/i });
+	const counter = screen.getByTestId("counter-value");
+
+	// Act
+	expect(counter).toHaveTextContent("0");
+	fireEvent.click(button);
+
+	// Assert
+	expect(counter).toHaveTextContent("1");
+});
+```
+
+#### 🙈 Avoid Testing Implementation Details
+
+- Don't test internal state or private methods
+- Test the component's public interface
+- Mock at the network boundary, not internal functions
+
+## ⚡ Performance Practices
+
+### 📊 Optimize for the Right Metrics
+
+- Focus on user-centric performance (loading, interaction)
+- Measure before optimizing
+- Avoid premature micro-optimizations
+
+### 📈 Progressive Enhancement
+
+- Build core functionality that works without JavaScript
+- Enhance with client-side features
+- Use lazy loading for non-critical resources
+
+### 🚀 Performance Patterns
+
+```javascript
+// ✅ Lazy loading with Suspense
+const HeavyComponent = lazy(() => import("./heavy-component"));
+
+function App() {
+	return (
+		<Suspense fallback={<Skeleton />}>
+			<HeavyComponent />
+		</Suspense>
+	);
+}
+```
+
+## 🤝 Collaboration Practices
+
+### 💬 Code as Communication
+
+- Express intent clearly through naming and structure
+- Document decisions, not implementation
+- Consider the next developer who will read this code
+
+### 🔍 Pull Request Guidelines
+
+**For Authors**:
+
+- Separate tidying commits from behavior changes
+- Write clear commit messages
+- Include context in PR descriptions
+
+**For Reviewers**:
+
+- Focus on correctness, simplicity, and maintainability
+- Ask questions when unclear
+- Praise good solutions
+
+### ♻️ Continuous Improvement
+
+- Reflect on decisions and learn from mistakes
+- Share knowledge through documentation and mentoring
+- Regularly refactor and clean up technical debt

package/configs/reference/git-guidelines.md

@@ -0,0 +1,63 @@
+# Git Safety Guidelines
+
+## Safe Git Operations
+
+AI agents should follow these principles when working with git:
+
+### ✅ Allowed Operations
+
+- **Read operations**: `git status`, `git log`, `git diff`, `git show`
+- **Safe commits**: `git add`, `git commit`
+- **Branch management**: `git branch`, `git checkout -b`, `git switch`
+- **Safe push**: `git push` (standard push without force)
+- **Inspection**: `git blame`, `git ls-files`, `git rev-parse`
+
+### ⛔ Operations to Avoid
+
+Avoid these dangerous git commands without explicit user approval:
+
+- **Add all files**: `git add -A`, `git add --all` (stages all changes including untracked files; prefer `git add <specific-files>` or `git add -p` for interactive staging)
+- **Force push**: `git push --force`, `git push -f` (not recommended; if absolutely required, `--force-with-lease` is safer)
+- **History rewriting**: `git rebase -i`, `git filter-branch`
+- **Amending pushed commits**: `git commit --amend` (only safe for local, unpushed commits)
+- **Reset operations**: `git reset`, `git reset --hard`, `git reset --mixed`, `git reset --soft` (unstages files or moves HEAD; can lose work or change history)
+- **Force operations**: `git checkout --force`, `git clean -f/-d`, `git branch -D`
+- **Stash deletion**: `git stash drop`, `git stash clear`
+- **Reference manipulation**: `git update-ref -d`, `git reflog expire`
+
+### Best Practices
+
+- Always use `git --no-pager` to prevent interactive pagers in scripts
+- Check repository state with `git status` before operations
+- Stage files intentionally: use `git add <specific-files>` or `git add -p` for interactive staging
+- Use `git diff` to verify changes before committing
+- Prefer `git switch` over `git checkout` for branch switching (Git 2.23+; use `git checkout <branch>` for older versions)
+- Use descriptive commit messages following conventional commits format
+- Create feature branches instead of working directly on main/master
+- Pull before push to avoid conflicts: `git pull origin <branch>` (or `git fetch origin && git merge origin/<branch>` for more control)
+
+### Error Handling
+
+```bash
+# Check if git repository
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+    echo "Error: Not a git repository" >&2
+    exit 1
+fi
+
+# Check for uncommitted changes
+if ! git diff-index --quiet HEAD --; then
+    echo "Warning: Uncommitted changes detected" >&2
+fi
+```
+
+## Pre-commit Checklist
+
+- [ ] Shell scripts pass `bash -n` syntax check
+- [ ] Tested with `--dry-run`
+- [ ] No absolute paths in configs
+- [ ] Colors and logging functions used consistently
+- [ ] Error handling with `set -e` and guard clauses
+- [ ] Documentation updated if workflow changed
+- [ ] Git operations follow safety guidelines
+

package/package.json

@@ -1,6 +1,36 @@
 {
-  "name": "pi-lazy-setup",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "pi-lazy-setup",
+	"version": "3.0.0",
+	"description": "Initialize the Pi agent environment from a curated snapshot",
+	"type": "module",
+	"bin": {
+		"pi-setup": "./bin/pi-setup.mjs"
+	},
+	"files": [
+		"bin",
+		"src",
+		"configs"
+	],
+	"scripts": {
+		"test": "node --test",
+		"dev": "node bin/pi-setup.mjs"
+	},
+	"keywords": [
+		"cli",
+		"pi",
+		"agent-setup"
+	],
+	"author": "kk",
+	"license": "MIT",
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.1"
+	},
+	"dependencies": {
+		"@inquirer/prompts": "^7.10.1",
+		"chalk": "^5.3.0",
+		"commander": "^12.0.0"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	}
+}

package/src/agents/pi.mjs

@@ -0,0 +1,24 @@
+// pi.mjs — Pi agent descriptor.
+// Pure data; the initializer in src/commands/init.mjs loops over a list of
+// these. Paths with ~ are expanded at runtime by the initializer.
+//
+// The CLI only deploys the config snapshot and the /pi-setup extension
+// (deploy.extensionFiles). Installing the pi binary, packages, skills, and
+// CLI tools is out of scope — `/pi-setup` handles those interactively inside
+// Pi, each item confirmed individually.
+
+/** @type {import('./types.mjs').AgentDescriptor} */
+export const pi = {
+	id: "pi",
+	name: "Pi",
+	home: "~/.pi/agent",
+	configSource: "configs/pi",
+	referenceDest: "~/.pi/agent/pi-setup",
+	deploy: {
+		overwriteFiles: ["settings.json", "mcp.json", "models.json", "AGENTS.md"],
+		replaceDirs: ["prompts"],
+		extensionFiles: ["pi-setup.js"],
+		overwriteExtra: [{ file: "web-config.json", dest: "~/.config/rpiv-web-tools/config.json" }],
+		referenceSource: "configs/reference",
+	},
+};

package/src/agents/types.mjs

@@ -0,0 +1,23 @@
+// types.mjs — JSDoc type shapes for agent descriptors.
+// No runtime exports; used only for type hints in editors.
+
+/**
+ * @typedef {Object} DeploySpec
+ * @property {string[]} overwriteFiles  — files copied flat into home
+ * @property {string[]} replaceDirs     — subdirs rm-rf'd then fully replaced
+ * @property {string[]} [extensionFiles] — extension files copied flat into `<home>/extensions/`
+ * @property {{ file: string, dest: string }[]} [overwriteExtra] — files copied to a ~-prefixed dest outside home
+ * @property {string} referenceSource   — package-relative path to reference docs
+ */
+
+/**
+ * @typedef {Object} AgentDescriptor
+ * @property {string} id
+ * @property {string} name
+ * @property {string} home             — ~-prefixed agent home
+ * @property {string} configSource     — package-relative path to agent configs
+ * @property {string} referenceDest    — ~-prefixed destination for reference docs
+ * @property {DeploySpec} deploy
+ */
+
+export {};

package/src/commands/init.mjs

@@ -0,0 +1,91 @@
+// init.mjs — the initializer.
+// Loops over the agent descriptors and runs detect → (backup)
+// → deploy-configs → deploy-reference.
+// Each step honors { dryRun }.
+//
+// Binaries, packages, skills, and CLI tools are NOT installed here. Instead
+// the /pi-setup extension is deployed (see deploy.extensions) — run `/pi-setup`
+// inside Pi to install those interactively, each item confirmed individually.
+
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { pi } from "../agents/pi.mjs";
+import { backupToTar, copyDir, copyDirFiles, copyFile, ensureDir } from "../lib/fs.mjs";
+import { log } from "../lib/log.mjs";
+import { expandHome, packageRoot, pkgPath } from "../lib/paths.mjs";
+
+const AGENTS = [pi];
+
+export { AGENTS };
+
+/** Directory for --backup tars: ~/ai-tools-backup-<timestamp>/ */
+function backupDirFor() {
+	const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+	return resolve(homedir(), `ai-tools-backup-${ts}`);
+}
+
+/**
+ * Deploy step: copy the agent snapshot into its home. Flat files are
+ * overwritten, subdirs replaced wholesale, extension files deployed so they
+ * auto-load on the next Pi start. No binary installs happen here.
+ */
+function deployConfigs(agent, pkgRoot, { dryRun }) {
+	const home = expandHome(agent.home);
+	const srcDir = pkgPath(pkgRoot, agent.configSource);
+	ensureDir(home, { dryRun });
+	for (const file of agent.deploy.overwriteFiles) {
+		copyFile(resolve(srcDir, file), resolve(home, file), { dryRun });
+	}
+	for (const dir of agent.deploy.replaceDirs) {
+		copyDir(resolve(srcDir, dir), resolve(home, dir), { dryRun });
+	}
+	for (const extra of agent.deploy.overwriteExtra ?? []) {
+		copyFile(resolve(srcDir, extra.file), expandHome(extra.dest), { dryRun });
+	}
+	// extensions: deploy each file flat into ~/.pi/agent/extensions/ so Pi
+	// auto-discovers it on the next start. Existing files with the same name
+	// are overwritten (snapshot semantics).
+	for (const file of agent.deploy.extensionFiles ?? []) {
+		copyFile(resolve(srcDir, "extensions", file), resolve(home, "extensions", file), { dryRun });
+	}
+}
+
+function deployReference(agent, pkgRoot, { dryRun }) {
+	const dest = expandHome(agent.referenceDest);
+	const src = pkgPath(pkgRoot, agent.deploy.referenceSource);
+	ensureDir(dest, { dryRun });
+	copyDirFiles(src, dest, { dryRun });
+}
+
+/**
+ * Back up the agent's existing home to a tar (no-op if absent).
+ */
+function backupAgentHome(agent, backupDir, { dryRun }) {
+	backupToTar(expandHome(agent.home), backupDir, { dryRun });
+}
+
+/**
+ * Initialize the configured agents: (backup) → deploy configs (including the
+ * /pi-setup extension) → deploy reference docs. Returns 0 on success.
+ *
+ * Installing binaries, packages, skills, and CLI tools is deferred to the
+ * `/pi-setup` command inside Pi (see configs/pi/extensions/pi-setup.js).
+ *
+ * @param {{ dryRun?: boolean, backup?: boolean, agents?: Array }} opts
+ * @returns {Promise<number>}
+ */
+export async function initialize({ dryRun = false, backup = false, agents = AGENTS } = {}) {
+	const pkgRoot = packageRoot(import.meta.url);
+	const backupDir = backup ? backupDirFor() : null;
+	log.info(dryRun ? "Dry-run mode — no changes will be made" : "Initializing agent environments");
+	if (backup) log.info(`Backing up existing agent homes to ${backupDir}`);
+	for (const agent of agents) {
+		log.step(`Configure ${agent.name}`);
+		if (backup) backupAgentHome(agent, backupDir, { dryRun });
+		deployConfigs(agent, pkgRoot, { dryRun });
+		deployReference(agent, pkgRoot, { dryRun });
+	}
+	log.success("Setup complete");
+	log.info("Run /pi-setup inside Pi to install packages, skills, and CLI tools (each confirmed individually)");
+	return 0;
+}

package/src/commands/select.mjs

@@ -0,0 +1,51 @@
+// select.mjs — resolve which agents to configure.
+//
+// Resolution order:
+//   1. positional args (pi-setup pi) → validate ids, use exactly those
+//   2. non-TTY (CI / piped)                  → all agents, no prompt
+//   3. TTY                                    → interactive select
+//
+// Exits non-zero on unknown agent ids.
+
+import { checkbox } from "@inquirer/prompts";
+import { log } from "../lib/log.mjs";
+import { AGENTS } from "./init.mjs";
+
+const VALID_IDS = new Set(AGENTS.map((a) => a.id));
+
+export async function selectAgents(positional, { tty = false } = {}) {
+	// 1. explicit positional args
+	if (positional.length > 0) {
+		const invalid = positional.filter((id) => !VALID_IDS.has(id));
+		if (invalid.length > 0) {
+			log.error(`Unknown agent(s): ${invalid.join(", ")}`);
+			log.info(`Valid ids: ${AGENTS.map((a) => a.id).join(", ")}`);
+			process.exit(1);
+		}
+		return positional;
+	}
+
+	// 2. non-interactive: all agents
+	if (!tty) {
+		log.info("Non-interactive mode — configuring all agents");
+		return AGENTS.map((a) => a.id);
+	}
+
+	// 3. interactive multi-select
+	const selected = await checkbox({
+		message: "Select agents to configure:",
+		default: true,
+		choices: AGENTS.map((a) => ({
+			name: a.name,
+			value: a.id,
+			checked: true,
+		})),
+	});
+
+	if (selected.length === 0) {
+		log.warning("No agents selected — nothing to do");
+		process.exit(0);
+	}
+
+	return selected;
+}

package/src/lib/fs.mjs

@@ -0,0 +1,111 @@
+// fs.mjs — filesystem helpers for deploy.
+// All functions take an optional { dryRun } option: when true, print the
+// planned action with full paths and do NOT touch the filesystem.
+
+import { execFileSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, resolve } from "node:path";
+import { log } from "./log.mjs";
+
+/** Strip the leading home directory from an absolute path for nicer tar names. */
+function stripHome(p) {
+	const h = homedir();
+	return p.startsWith(h) ? p.slice(h.length).replace(/^\/+/, "") : p;
+}
+
+/**
+ * Ensure a directory exists (recursive). Prints in dry-run.
+ */
+export function ensureDir(dir, { dryRun = false } = {}) {
+	if (dryRun) {
+		log.dry(`mkdir -p ${dir}`);
+		return;
+	}
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true });
+		log.info(`mkdir ${dir}`);
+	}
+}
+
+/**
+ * Remove a directory recursively. No-op if it doesn't exist. Prints in dry-run.
+ */
+export function rmrf(dir, { dryRun = false } = {}) {
+	if (dryRun) {
+		if (existsSync(dir)) log.dry(`rm -rf ${dir}`);
+		return;
+	}
+	if (existsSync(dir)) {
+		rmSync(dir, { recursive: true, force: true });
+		log.info(`rm -rf ${dir}`);
+	}
+}
+
+/**
+ * Copy a single file, creating parent dirs as needed. Prints in dry-run.
+ */
+export function copyFile(src, dest, { dryRun = false } = {}) {
+	if (dryRun) {
+		log.dry(`cp ${src} → ${dest}`);
+		return;
+	}
+	ensureDir(dirname(dest), { dryRun: false });
+	cpSync(src, dest, { force: true });
+	log.deploy(dest);
+}
+
+/**
+ * Copy a directory recursively, fully replacing the destination.
+ * Calls rmrf(dest) then copies src → dest. Prints in dry-run.
+ */
+export function copyDir(src, dest, { dryRun = false } = {}) {
+	if (!existsSync(src)) {
+		if (dryRun) log.dry(`skip ${dest} (source ${src} does not exist)`);
+		return;
+	}
+	if (dryRun) {
+		log.dry(`rm -rf ${dest} && cp -r ${src} ${dest}`);
+		return;
+	}
+	rmrf(dest, { dryRun: false });
+	ensureDir(dirname(dest), { dryRun: false });
+	cpSync(src, dest, { recursive: true, force: true });
+	log.deploy(dest);
+}
+
+/**
+ * Copy every file in sourceDir (non-recursively) into destDir.
+ * Used to deploy reference docs (flat file set). Prints in dry-run.
+ */
+export function copyDirFiles(sourceDir, destDir, { dryRun = false } = {}) {
+	if (!existsSync(sourceDir)) return;
+	const entries = readdirSync(sourceDir);
+	for (const entry of entries) {
+		const src = resolve(sourceDir, entry);
+		const stat = statSync(src);
+		if (stat.isFile()) {
+			copyFile(src, resolve(destDir, entry), { dryRun });
+		}
+	}
+}
+
+/**
+ * Back up a directory tree to a tar file under backupDir.
+ * Skips silently if the source does not exist. Prints in dry-run.
+ * Returns the created tar path (or null if skipped/no-op).
+ */
+export function backupToTar(src, backupDir, { dryRun = false } = {}) {
+	if (!existsSync(src)) return null;
+	const base = basename(stripHome(src));
+	const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+	const tar = resolve(backupDir, `${base}-${ts}.tar.gz`);
+	if (dryRun) {
+		log.dry(`backup ${src} → ${tar}`);
+		return tar;
+	}
+	ensureDir(backupDir, { dryRun: false });
+	execFileSync("tar", ["-czf", tar, "-C", dirname(src), base], { stdio: "ignore" });
+	log.info(`backup ${src} → ${tar}`);
+	return tar;
+}

package/src/lib/log.mjs

@@ -0,0 +1,39 @@
+// log.mjs — structured stdout logger built on chalk.
+// Every action prints a full resolved path so the user can see exactly what
+// the CLI did.
+
+import chalk from "chalk";
+
+function fullPath(p) {
+	return typeof p === "string" ? p : String(p);
+}
+
+export const log = {
+	info(msg) {
+		console.log(`${chalk.cyan("ℹ")} ${msg}`);
+	},
+	success(msg) {
+		console.log(`${chalk.green("✓")} ${msg}`);
+	},
+	warning(msg) {
+		console.log(`${chalk.yellow("⚠")} ${msg}`);
+	},
+	error(msg) {
+		console.error(`${chalk.red("✗")} ${msg}`);
+	},
+	dry(msg) {
+		console.log(`${chalk.magenta("[dry]")} ${msg}`);
+	},
+	step(msg) {
+		console.log(`${chalk.dim("─")} ${msg}`);
+	},
+	install(name) {
+		console.log(`${chalk.cyan("ℹ")} Installing ${name}...`);
+	},
+	skip(name) {
+		console.log(`${chalk.dim("•")} ${name} already installed, skipping`);
+	},
+	deploy(dest) {
+		console.log(`${chalk.green("✓")} Deployed → ${fullPath(dest)}`);
+	},
+};

package/src/lib/paths.mjs

@@ -0,0 +1,36 @@
+// paths.mjs — resolve package root and agent homes.
+// Resolves from import.meta.url (NOT process.cwd()) so `npx pi-lazy-setup` works
+// regardless of the user's current directory.
+
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Resolve the package root (the directory containing bin/, src/, configs/).
+ * Pass import.meta.url from the calling module.
+ */
+export function packageRoot(importMetaUrl) {
+	const here = dirname(fileURLToPath(importMetaUrl));
+	// src/lib/paths.mjs → up two = package root
+	return resolve(here, "..", "..");
+}
+
+/**
+ * Resolve a path inside the package root. Segments are package-relative
+ * (e.g. "configs", "pi", "settings.json"). Descriptors already carry the
+ * "configs/<agent>" prefix, so this does NOT add a magic "configs/".
+ */
+export function pkgPath(pkgRoot, ...segments) {
+	return resolve(pkgRoot, ...segments);
+}
+
+/**
+ * Expand a leading ~ to the user's home directory.
+ */
+export function expandHome(p) {
+	if (!p) return p;
+	if (p === "~") return homedir();
+	if (p.startsWith("~/")) return resolve(homedir(), p.slice(2));
+	return p;
+}