pi-lazy-setup 0.0.0-stage → 2.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,57 @@
-# 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. **Installs the binary** — `pi` via npm. Skips if already on PATH.
+2. **Deploys configs** — overwrites `~/.pi/agent` from bundled `configs/pi/`.
+3. **Deploys reference docs** — copies into `~/.pi/agent/pi-setup/`.
+4. **Installs default skills** — via `npx skills add` (https://skills.sh/).
+
+## 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>). MCP server binaries are not installed — only the declaration file (`mcp.json`) and config files (`settings.json`, `models.json`, `AGENTS.md`, `prompts/`) are deployed.
+
+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,36 @@
+#!/usr/bin/env node
+
+// pi-setup — initialize the Pi agent environment from a snapshot.
+//
+// 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,
+			tty: !!process.stdin.isTTY,
+			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/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": "2.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/packages.mjs

@@ -0,0 +1,28 @@
+// packages.mjs — Pi extension packages offered for install via `pi install`.
+// The settings.json snapshot ships WITHOUT a "packages" key; the initializer
+// prompts the user to pick which ones to install (interactive TTY only;
+// non-interactive runs skip package install entirely — nothing is
+// auto-installed).
+
+/**
+ * Packages offered for installation. `source` is passed verbatim to
+ * `pi install`, which writes the declaration into ~/.pi/agent/settings.json.
+ */
+export const DEFAULT_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.",
+	},
+];

package/src/agents/pi.mjs

@@ -0,0 +1,27 @@
+// 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.
+import { DEFAULT_PACKAGES } from "./packages.mjs";
+import { DEFAULT_SKILLS } from "./skills.mjs";
+
+/** @type {import('./types.mjs').AgentDescriptor} */
+export const pi = {
+	id: "pi",
+	name: "Pi",
+	home: "~/.pi/agent",
+	configSource: "configs/pi",
+	referenceDest: "~/.pi/agent/pi-setup",
+	install: {
+		kind: "npm",
+		pkg: "@mariozechner/pi-coding-agent",
+		bin: "pi",
+	},
+	deploy: {
+		overwriteFiles: ["settings.json", "mcp.json", "models.json", "AGENTS.md"],
+		replaceDirs: ["prompts"],
+		overwriteExtra: [{ file: "web-config.json", dest: "~/.config/rpiv-web-tools/config.json" }],
+		referenceSource: "configs/reference",
+	},
+	skills: { specs: DEFAULT_SKILLS, cliAgent: "pi" },
+	packages: { specs: DEFAULT_PACKAGES },
+};

package/src/agents/skills.mjs

@@ -0,0 +1,19 @@
+// skills.mjs — skill specs available to install from remote via `npx skills add`.
+// Each spec is "owner/repo@skill" (see https://skills.sh/).
+// The initializer prompts the user to pick which ones to install
+// (interactive TTY only; non-interactive runs skip skill install).
+
+/**
+ * Skills offered for installation. Sourced from remote via
+ * `npx skills add` (https://skills.sh/).
+ */
+export const DEFAULT_SKILLS = [
+	{
+		spec: "mattpocock/skills@grill-me",
+		description: "Matt Pocock — a relentless interview to sharpen a plan or design.",
+	},
+	{
+		spec: "microsoft/playwright-cli@playwright-cli",
+		description: "Microsoft — browser automation and Playwright test driving.",
+	},
+];

package/src/agents/types.mjs

@@ -0,0 +1,54 @@
+// types.mjs — JSDoc type shapes for agent descriptors.
+// No runtime exports; used only for type hints in editors.
+
+/**
+ * @typedef {Object} InstallSpec
+ * @property {"npm"} kind
+ * @property {string} [pkg]      — npm package name
+ * @property {string} bin        — binary name to detect on PATH
+ */
+
+/**
+ * @typedef {Object} DeploySpec
+ * @property {string[]} overwriteFiles  — files copied flat into home
+ * @property {string[]} replaceDirs     — subdirs rm-rf'd then fully replaced
+ * @property {{ file: string, dest: string }[]} [overwriteExtra] — files copied to a ~-prefixed dest outside home
+ * @property {string} referenceSource   — package-relative path to reference docs
+ * @property {SkillsSpec} [skills]      — default skills to install from remote
+ * @property {PackagesSpec} [packages]  — extension packages offered via `pi install`
+ */
+
+/**
+ * @typedef {Object} SkillSpec
+ * @property {string} spec          — "owner/repo@skill" identifier
+ * @property {string} [description] — shown in the interactive skill picker
+ */
+
+/**
+ * @typedef {Object} SkillsSpec
+ * @property {SkillSpec[]} specs     — skills offered for install (user selects)
+ * @property {string} [cliAgent]    — lowercase skills-CLI agent name; install via `npx skills add`
+ */
+/**
+ * @typedef {Object} PackageSpec
+ * @property {string} source        — package source passed to `pi install`
+ * @property {string} [description] — shown in the interactive package picker
+ */
+
+/**
+ * @typedef {Object} PackagesSpec
+ * @property {PackageSpec[]} specs — packages offered for install (user selects)
+ */
+
+/**
+ * @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 {InstallSpec} install
+ * @property {DeploySpec} deploy
+ */
+
+export {};

package/src/commands/init.mjs

@@ -0,0 +1,189 @@
+// init.mjs — the initializer.
+// Loops over the agent descriptors and runs detect → install → (backup)
+// → deploy-configs → deploy-reference → select-packages → install-packages
+// → select-skills → install-skills.
+// Each step honors { dryRun }.
+
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { checkbox } from "@inquirer/prompts";
+import { pi } from "../agents/pi.mjs";
+import { detectBinary, runCommand } from "../lib/exec.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}`);
+}
+
+/**
+ * Install step: detect the agent's binary on PATH; if missing, run the
+ * install command. No-op (print only) in dry-run.
+ */
+async function installStep(agent, { dryRun }) {
+	const present = dryRun ? false : detectBinary(agent.install.bin);
+	if (present) {
+		if (!dryRun) log.skip(agent.name);
+		else log.dry(`detect ${agent.install.bin} (assume present → skip)`);
+		return 0;
+	}
+	// install
+	const cmdline = installCmdline(agent.install);
+	if (dryRun) {
+		log.dry(`detect ${agent.install.bin} → missing → install`);
+	}
+	log.install(agent.name);
+	return runCommand(cmdline, { dryRun });
+}
+
+function installCmdline(spec) {
+	if (spec.kind === "npm") return `npm install -g ${spec.pkg}`;
+	throw new Error(`unknown install kind: ${spec.kind}`);
+}
+
+/**
+ * Deploy agent configs: overwrite flat files, replace subdirs wholesale.
+ */
+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 });
+	}
+}
+
+function deployReference(agent, pkgRoot, { dryRun }) {
+	const dest = expandHome(agent.referenceDest);
+	const src = pkgPath(pkgRoot, agent.deploy.referenceSource);
+	ensureDir(dest, { dryRun });
+	copyDirFiles(src, dest, { dryRun });
+}
+
+/**
+ * Skills step: let the user pick which skills to install (interactive TTY),
+ * then install each selected one from remote via `npx skills add`
+ * (https://skills.sh/). Non-interactive runs skip skill install entirely —
+ * nothing is auto-installed.
+ */
+async function installSkillsStep(agent, { dryRun, tty }) {
+	const spec = agent.skills;
+	if (!spec) return 0;
+	let selected = [];
+	if (tty) {
+		selected = await checkbox({
+			message: "Select skills to install:",
+			choices: spec.specs.map((s) => ({
+				name: s.spec,
+				value: s.spec,
+				description: s.description,
+				checked: true,
+			})),
+		});
+		if (selected.length === 0) {
+			log.info("No skills selected — skipping skill install");
+			return 0;
+		}
+	} else {
+		log.info(`Non-interactive mode — skipping skill install (available: ${spec.specs.map((s) => s.spec).join(", ")})`);
+		return 0;
+	}
+	for (const skill of selected) {
+		const { repo, name } = parseSkillSpec(skill);
+		const cmdline = `npx --yes skills add ${repo} --skill ${name} -g --agent ${spec.cliAgent} -y`;
+		log.install(`${skill} → ${spec.cliAgent}`);
+		const code = await runCommand(cmdline, { dryRun });
+		if (code !== 0) return code;
+	}
+	return 0;
+}
+
+/**
+ * Packages step: let the user pick which Pi extension packages to install
+ * (interactive TTY), then install each via `pi install <source>`, which
+ * writes the declaration into ~/.pi/agent/settings.json. Non-interactive
+ * runs skip package install entirely — nothing is auto-installed.
+ */
+async function installPackagesStep(agent, { dryRun, tty }) {
+	const spec = agent.packages;
+	if (!spec) return 0;
+	let selected = [];
+	if (tty) {
+		selected = await checkbox({
+			message: "Select Pi extension packages to install:",
+			choices: spec.specs.map((p) => ({
+				name: p.source,
+				value: p.source,
+				description: p.description,
+				checked: false,
+			})),
+		});
+		if (selected.length === 0) {
+			log.info("No packages selected — skipping package install");
+			return 0;
+		}
+	} else {
+		const available = spec.specs.map((p) => p.source).join(", ");
+		log.info(`Non-interactive mode — skipping package install (available: ${available})`);
+		return 0;
+	}
+	for (const source of selected) {
+		const cmdline = `pi install ${source}`;
+		log.install(`${source} → ${agent.name}`);
+		const code = await runCommand(cmdline, { dryRun });
+		if (code !== 0) return code;
+	}
+	return 0;
+}
+
+/** Parse "owner/repo@skill" into { repo, name }. */
+function parseSkillSpec(spec) {
+	const at = spec.lastIndexOf("@");
+	if (at < 0) throw new Error(`skill spec missing @skill: ${spec}`);
+	return { repo: spec.slice(0, at), name: spec.slice(at + 1) };
+}
+
+/**
+ * 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. Returns 0 on success, non-zero on failure.
+ *
+ * @param {{ dryRun?: boolean, backup?: boolean, tty?: boolean, agents?: Array }} opts
+ * @returns {Promise<number>}
+ */
+export async function initialize({ dryRun = false, backup = false, tty = 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}`);
+	let rc = 0;
+	for (const agent of agents) {
+		log.step(`Configure ${agent.name}`);
+		rc ||= await installStep(agent, { dryRun });
+		if (backup) backupAgentHome(agent, backupDir, { dryRun });
+		deployConfigs(agent, pkgRoot, { dryRun });
+		deployReference(agent, pkgRoot, { dryRun });
+		rc ||= await installPackagesStep(agent, { dryRun, tty });
+		rc ||= await installSkillsStep(agent, { dryRun, tty });
+	}
+	if (rc === 0) log.success("Setup complete");
+	return rc;
+}

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/exec.mjs

@@ -0,0 +1,40 @@
+// exec.mjs — exec + detect helpers that honor --dry-run.
+//
+// runCommand takes a single shell command string. In dry-run mode it prints
+// "[dry] <cmd>" instead of spawning. In real mode it spawns with shell:true
+// and inherited stdio, returning the exit code.
+
+import { spawn, spawnSync } from "node:child_process";
+
+/**
+ * Run a shell command. If dryRun is true, only print the command.
+ * Returns 0 on success, non-zero on failure. Resolves a Promise.
+ */
+export function runCommand(cmdline, { dryRun = false, cwd } = {}) {
+	if (dryRun) {
+		console.log(`[dry] ${cmdline}`);
+		return Promise.resolve(0);
+	}
+	return new Promise((resolve) => {
+		const child = spawn(cmdline, { cwd, stdio: "inherit", shell: true });
+		child.on("close", (code) => resolve(code ?? 1));
+		child.on("error", () => resolve(1));
+	});
+}
+
+/**
+ * Detect whether a binary is on PATH. Synchronous — used by the detect step
+ * to decide install-vs-skip. Returns boolean.
+ *
+ * The command is passed as a single string, NOT as an args array: args +
+ * shell:true triggers Node's DEP0190 DeprecationWarning, which is printed
+ * asynchronously — it lands inside the first interactive prompt that follows
+ * and shifts the cursor, breaking @inquirer's screen clearing (stale frames).
+ */
+export function detectBinary(name) {
+	const result = spawnSync(`command -v ${name}`, {
+		shell: true,
+		stdio: "ignore",
+	});
+	return result.status === 0;
+}

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;
+}