pier-setup 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 July24
+
+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.en.md

@@ -0,0 +1,134 @@
+<div align="center">
+
+# pier · pi × herdr workspace fusion
+
+**pier** = **pi** × h**erdr** (a pier/dock — where things moor, dock, and fan out).
+
+[pi](https://pi.dev/) (`@earendil-works/pi-coding-agent`) is the coding-agent carrier; [herdr](https://herdr.dev/) is a terminal workspace manager. pier adds the two capabilities pi deliberately leaves out — a **todo list loop** and **interactive subagents** — and gives them the herdr pane/tab layer as their visual and interactive substrate.
+
+</div>
+
+---
+
+## What it is
+
+pier ships as **two halves**, installed separately:
+
+| Half | Package | Role |
+|---|---|---|
+| **pi extension** | `packages/pier-ext` (npm: [`pi-pier`](https://www.npmjs.com/package/pi-pier), [pi.dev gallery](https://pi.dev/packages/pi-pier)) | Injects `todo_write` / `subagent` / `list_agents` / `send_message` / `interrupt_agent` tools into a pi session, and reports pane state over the herdr socket API |
+| **herdr plugin** | `packages/pier-workbench` (`pier.workbench`) | Workspace bootstrap, blocked human-gate notifications, focus heat layout (focused pane grows in place) |
+
+### Highlights
+
+- **Todo loop**: `todo_write` with full-replace semantics, session JSONL as source of truth, correct branch rollback; live pane-title projection `▶i ○p ■b ✓c (N/M) · current task`; `/todos` command (including unblock)
+- **Interactive subagents**: every subagent = an isolated pi session in its own pane (separate context window); **a human can enter that pane and talk to it directly** (fix bugs, take over, answer ask_user_question)
+- **Soft write-locks**: per-pane lock tokens on write paths; cross-pane conflicts warn or block
+- **Role profiles**: built-in `master` / `worker-default`; custom roles as `.pi-herdr/roles/<name>.json`; toolset converges per role (deny rules are not bypassable)
+- **Human gate**: subagent `ask_user_question` → sidebar blocked marker + notification; manual takeover (ESC-interrupt then typing) is heuristically detected so the master pauses/returns management automatically
+- **Focus heat layout**: focused pane grows in place (0.72 target); blocked / ask / working / idle sized by weight; surplus panes collapse to title strips
+- **Settlement notice folding**: subagent settlements no longer flood back when a long main run ends — they inject at turn gaps, up to 3 shown, the rest folded with pointers
+
+## Installation
+
+### Requirements
+
+- Node ≥ 22
+- pi ≥ 0.84 (`@earendil-works/pi-coding-agent`)
+- herdr ≥ 0.8.0 (macOS / Linux / Windows; Windows is preview beta)
+
+### One-shot install (recommended)
+
+No clone needed — run the npm package directly:
+
+```sh
+npx pier-setup            # user mode: pi install npm:pi-pier + herdr plugin install + auto-generated bootstrap config
+npm i -g pier-setup       # or install globally, then just run pier-setup
+```
+
+Dev mode still requires cloning the repo:
+
+```sh
+git clone https://github.com/July24/pier && cd pier
+node install.mjs install --dev   # local-path pi install + herdr plugin link; code changes are live
+```
+
+The script verifies the environment (node / pi / herdr versions), probes pi's node
+and cli.js absolute paths, generates boot-config.json (user mode stores it in the
+herdr plugin config dir, so reinstalls don't lose it), and registers both halves.
+
+Other commands: `pier-setup update` (uninstall + reinstall, re-probes paths),
+`pier-setup uninstall --purge`. Override the distribution specs with
+`--pi-spec=` / `--herdr-spec=` (npm publishing or forks).
+
+### Manual install (equivalent steps)
+
+```sh
+# pi extension (any one; npm source = recommended user mode, git source = latest main, local path = dev mode)
+pi install npm:pi-pier                # user mode (npm release, auto-listed on the pi.dev/packages gallery)
+pi install git:github.com/July24/pier # user mode (tracks main)
+pi install ./packages/pier-ext        # development
+
+# herdr plugin
+herdr plugin install July24/pier/packages/pier-workbench --yes   # user mode (reinstall = update)
+herdr plugin link ./packages/pier-workbench                        # development
+```
+
+The extension degrades gracefully outside a herdr environment (see Scope below).
+
+### Scope (only the herdr × pi intersection is affected)
+
+- **pi outside herdr**: the extension degrades — reporting is free, workbench tools
+  (`subagent`, terminal family) return a clear "requires a herdr-managed pane" error;
+  `todo_write` / `ask_user_question` stay available (session JSONL is the authority,
+  no herdr dependency).
+- **other agents inside herdr (claude code / codex etc.)**: tabs without a pi pane
+  are excluded from heat reflow; blocked notifications are pi-only; master-tab
+  auto-bootstrap can be disabled with `autoBootstrap: false` in boot-config.
+
+### Bootstrap config (workbench half)
+
+Master-tab bootstrap needs local node / pi paths: `pier-setup` generates
+them automatically; manually, copy `packages/pier-workbench/scripts/boot-config.example.json`
+(placeholders for both macOS and Windows). User mode reads it from
+`herdr plugin config-dir pier.workbench`; dev mode from `packages/pier-workbench/scripts/boot-config.json`.
+
+### Usage
+
+1. Run pi inside a herdr workspace pane (`pi` in the pane); the extension detects `HERDR_ENV` and starts reporting
+2. The model can call `todo_write` (live pane-title projection), `subagent` (foreground / parallel / background), `list_agents` / `send_message` / `interrupt_agent`
+3. Every subagent = its own pane (observable, enterable, blocked notifies)
+4. Restart recovery: herdr session restore rebuilds panes automatically (subagent rpc session files are reported); resume the parent pi session with `/resume`
+
+## Repository layout
+
+```
+packages/
+  pier-ext/        # pi extension (npm: pi-pier): todo/subagent tools, herdr client, vocab authority, skill
+  pier-workbench/  # herdr plugin (pier.workbench): workspace bootstrap + blocked notify + heat layout
+docs/              # install guide, role profile docs, sidebar role config
+```
+
+## Testing
+
+```sh
+npm install --ignore-scripts
+npm test          # node --test, 244 unit tests (planner / todo replay / session tail / GC / lifecycle)
+```
+
+## Design principles
+
+- **Session JSONL is the single source of truth**: todos, delegations, and registries replay from session branches — restart and branch switches stay correct
+- **Event-driven, never poll**: state arrives via herdr event subscriptions (`pane.agent_status_changed` / `pane.closed`); one snapshot is taken only when an event fires
+- **Zero position migration**: the herdr BSP layout topology is fixed at creation; pier only adjusts split ratios — panes never move, they size by priority
+- **Best-effort projection layer**: reporting failures are silent and never block the pi main flow
+
+## License
+
+MIT
+
+---
+
+> 💡 **For contributors**: `.gitignore` is deliberately **not committed** to this repository (ignore rules are per-environment). Maintain your own rules based on `README.md` / `README.en.md`; `packages/pier-workbench/scripts/boot-config.json` is also machine-local (see the `.example.json` template).
+>
+> **Naming convention**: the brand is **pier** (repo/packages/plugin); runtime protocol identifiers keep the **`pi-herdr`** prefix (`.pi-herdr/roles/` dir, `pi-herdr.subs` session custom entries, `~/.pi/agent/herdr-pi/roles/` user dir) — they persist with user sessions/config files, renaming would break existing data, so they are the compatibility layer.

package/README.md

@@ -0,0 +1,130 @@
+<div align="center">
+
+# pier · pi × herdr 工作台融合
+
+**pier** = **pi** × h**erdr** 的融合体（码头/桥，对接、停泊、分发）。
+
+[pi](https://pi.dev/)（`@earendil-works/pi-coding-agent`）是 coding agent 载体，[herdr](https://herdr.dev/) 是终端工作区管理器。pier 补上 pi 刻意不内置的两项能力——**todo list 闭环**与**交互式子代理**——并让它们以 herdr 的 pane/tab 为视觉与交互底座。
+
+</div>
+
+---
+
+## 是什么
+
+pier 由**两个半区**组成，各装一处：
+
+| 半区 | 包 | 作用 |
+|---|---|---|
+| **pi 扩展** | `packages/pier-ext`（npm: [`pi-pier`](https://www.npmjs.com/package/pi-pier)，[pi.dev 市场](https://pi.dev/packages/pi-pier)） | 在 pi 会话里注入 `todo_write` / `subagent` / `list_agents` / `send_message` / `interrupt_agent` 工具 + 经 herdr socket API 上报 pane 状态 |
+| **herdr 插件** | `packages/pier-workbench`（`pier.workbench`） | 主 tab 引导、blocked 人类闸门通知、焦点热力布局（聚焦 pane 原地放大） |
+
+### 核心能力
+
+- **todo 闭环**：`todo_write` 全量替换语义、会话 JSONL 权威、分支正确回滚；窗格标题实时投影 `▶i ○p ■b ✓c (N/M) · 当前任务`；`/todos` 命令（含 unblock）可查看/编辑
+- **交互式子代理**：每个子代理 = 独立 pane 的隔离 pi 会话（独立上下文窗口）；**人类可随时进入该 pane 直接对话**（修 bug、接管、回答 ask_user_question）
+- **软锁防争抢**（写路径按 pane 粒度锁 token，冲突时警告/阻止）
+- **角色档案**：`master` / `worker-default` 内置，自定义 role 按 `.pi-herdr/roles/<name>.json` 挂载；工具集按角色收敛（deny 规则不可绕过）
+- **人类闸门**：子代理 `ask_user_question` → 侧边栏 blocked 标记 + 通知；用户手动接管（ESC 打断后输入）→ 启发式检测自动暂停/归还 master 管理
+- **焦点热力布局**：聚焦 pane 原地放大（0.72 目标），blocked / ask / working / idle 按权重分大小，多余 pane 自动压成 title 条
+- **结算通知折叠**：后台子代理结算不再攒到 run 结束洪水回填——turn 间隙注入，最多 3 条逐条展示、其余折叠指路
+
+## 安装
+
+### 环境要求
+
+- Node ≥ 22
+- pi ≥ 0.84（`@earendil-works/pi-coding-agent`）
+- herdr ≥ 0.8.0（macOS / Linux / Windows；Windows 为 preview beta）
+
+### 一键安装（推荐）
+
+无需克隆仓库，直接用 npm 包运行：
+
+```sh
+npx pier-setup            # 用户模式：pi install npm:pi-pier + herdr plugin install + 自动生成引导配置
+npm i -g pier-setup       # 或全局安装后直接跑 pier-setup
+```
+
+开发模式仍需克隆仓库：
+
+```sh
+git clone https://github.com/July24/pier && cd pier
+node install.mjs install --dev   # 本地路径 pi install + herdr plugin link，改码即生效
+```
+
+脚本自动校验环境（node / pi / herdr 版本）、探测 pi 的 node 与 cli.js 绝对路径、
+生成 boot-config.json（用户模式落 herdr 插件配置目录，重装不丢），并注册两半区。
+
+其他命令：`pier-setup update`（卸载+重装，重探测路径）、`pier-setup uninstall --purge`。
+发行规格可用 `--pi-spec=` / `--herdr-spec=` 覆盖（npm 发布或 fork 场景）。
+
+### 手动安装（等价步骤）
+
+```sh
+# pi 侧扩展（任选其一；npm 源 = 用户模式推荐，git 源 = 跟随仓库最新，本地路径 = 开发模式）
+pi install npm:pi-pier                # 用户模式（npm 发布版，自动出现在 pi.dev/packages 市场）
+pi install git:github.com/July24/pier # 用户模式（跟随 main 最新）
+pi install ./packages/pier-ext        # 开发期
+
+# herdr 侧插件
+herdr plugin install July24/pier/packages/pier-workbench --yes   # 用户模式（重装即更新）
+herdr plugin link ./packages/pier-workbench                        # 开发期
+```
+
+扩展在非 herdr 环境下自动降级（详见下节"作用域"）。
+
+### 作用域（只影响 herdr × pi 交叉场景）
+
+- **非 herdr 环境用 pi**：扩展自动降级——herdr 上报零成本，`subagent` / 终端族
+  工具返回"requires a herdr-managed pane"提示；`todo_write` / `ask_user_question`
+  照常可用（以会话 JSONL 为权威，无 herdr 依赖）。
+- **herdr 中用其他 agent（claude code / codex 等）**：不含 pi pane 的 tab 不参与
+  热力布局；blocked 通知只发给 pi；主 tab 自动引导可用 boot-config 的
+  `autoBootstrap: false` 关闭。
+
+### 引导配置（workbench 半区）
+
+master 主 tab 引导需要本机 node / pi 路径：`node install.mjs` 自动生成；手动可复制模板
+`packages/pier-workbench/scripts/boot-config.example.json`（含 macOS / Windows 双平台占位）。
+用户模式配置在 `herdr plugin config-dir pier.workbench`；开发模式在 `packages/pier-workbench/scripts/boot-config.json`。
+
+### 使用
+
+1. 在 herdr workspace 里开 pane 跑 pi（pane 内 `pi`），扩展检测 `HERDR_ENV` 自动开始上报
+2. 模型可调用 `todo_write`（窗格头实时投影）、`subagent`（前台/并行/后台）、`list_agents` / `send_message` / `interrupt_agent`
+3. 每个子代理 = 独立 pane（可观察、可进入交互、blocked 时触发通知）
+4. 重启恢复：herdr session 恢复自动重建 pane（子代理 rpc 会话文件已上报）；父 pi 会话用 `/resume` 恢复
+
+## 仓库结构
+
+```
+packages/
+  pier-ext/        # pi 扩展（npm: pi-pier）：todo/subagent 工具、herdr 客户端、vocab 权威、skill
+  pier-workbench/  # herdr 插件（pier.workbench）：主 tab 引导 + blocked 通知 + 热力布局
+docs/              # 安装手册、role 档案说明、侧边栏 role 配置
+```
+
+## 测试
+
+```sh
+npm install --ignore-scripts
+npm test          # node --test，244 项单测（规划器 / todo 重放 / 会话尾 / GC / 生命周期）
+```
+
+## 设计原则
+
+- **会话 JSONL 是唯一权威**：todo / 委派 / 注册表全部回放自会话分支，重启与分支切换正确
+- **事件驱动，不轮询**：状态经 herdr 事件订阅（`pane.agent_status_changed` / `pane.closed`）推送，仅事件触发时拉一次快照
+- **零位置迁移**：herdr BSP 布局拓扑创建时定死，pier 只调 split ratio——pane 位置永不动，大小按优先级重算
+- **尽力而为的投影层**：上报失败静默，绝不影响 pi 主流程
+
+## License
+
+MIT
+
+---
+
+> 💡 **开发说明**：`.gitignore` 刻意**不提交**到本仓库（本地资产忽略规则属个人环境）。贡献者请基于 `README.md` / `README.en.md` 自行维护忽略规则；`packages/pier-workbench/scripts/boot-config.json` 亦为本机配置（模板见 `.example.json`）。
+>
+> **命名约定**：品牌名 **pier**（仓库/包/插件），运行时协议标识保留 **`pi-herdr`** 前缀（`.pi-herdr/roles/` 目录、`pi-herdr.subs` 等会话 custom 条目、`~/.pi/agent/herdr-pi/roles/` 用户目录）——它们随用户会话/配置文件持久化，改动会破坏既有数据，属兼容层。

package/install.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+/**
+ * pier 一键安装/卸载/更新（跨平台：macOS / Linux / Windows）。
+ *
+ * 用法：
+ *   node install.mjs install  [--dev] [--hmr-dev] [--force]   # 安装（默认命令，可省略 install）
+ *   node install.mjs uninstall [--dev] [--purge]              # 卸载；--purge 连 boot-config.json 一起删
+ *   node install.mjs update   [--dev] [--hmr-dev] [--force]   # 更新 = 卸载注册 + 重新安装（重探测路径）
+ *
+ * 模式：
+ *   用户模式（默认）：pi install git:github.com/July24/pier（仓库根 package.json 的 pi 字段）
+ *                   + herdr plugin install July24/pier/packages/pier-workbench --yes
+ *                   boot-config.json 写 herdr plugin config-dir（reinstall 不丢）。
+ *   --dev 开发模式：pi install <repo>/packages/pier-ext + herdr plugin link <repo>/packages/pier-workbench
+ *                   （link 目录是活的，改码即生效；update 只重写 boot-config）。
+ *
+ * 发行规格可用 --pi-spec= / --herdr-spec= 覆盖（npm 发布或 fork 场景）。
+ * 失败语义：每步给出手动等价命令；步骤失败不阻断报告（exitCode=1）。
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)));
+const EXT_DIR = join(ROOT, 'packages', 'pier-ext');
+const WB_DIR = join(ROOT, 'packages', 'pier-workbench');
+const DEV_BOOT_CONFIG = join(WB_DIR, 'scripts', 'boot-config.json');
+const EXT_PATH = join(EXT_DIR, 'src', 'index.ts');
+const IS_WIN = process.platform === 'win32';
+
+const argv = process.argv.slice(2);
+const command = ['install', 'uninstall', 'update'].includes(argv[0]) ? argv.shift() : 'install';
+const flags = new Set(argv.filter((a) => a.startsWith('--') && !a.includes('=')));
+const optValue = (name) => argv.find((a) => a.startsWith(`--${name}=`))?.split('=').slice(1).join('=') ?? null;
+const dev = flags.has('--dev');
+const PI_SPEC = optValue('pi-spec') ?? 'npm:pi-pier';   // 用户模式默认 npm 发行版；--pi-spec=git:github.com/July24/pier 可跟随仓库 main
+const HERDR_SPEC = optValue('herdr-spec') ?? 'July24/pier/packages/pier-workbench';
+
+const log = (m) => console.log(m);
+const die = (m) => { console.error(`✗ ${m}`); process.exit(1); };
+
+/* ── 工具函数 ────────────────────────────────────────────────────── */
+function which(bin) {
+  try {
+    const out = execFileSync(IS_WIN ? 'where' : 'which', [bin], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    // where 可能多行（PATH 逐条命中），取第一条存在的
+    for (const line of out.split('\n').map((l) => l.trim()).filter(Boolean)) {
+      if (existsSync(line)) return line;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function run(cmd, args) {
+  return execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+function tryRun(cmd, args) {
+  try { run(cmd, args); return true; } catch (e) { log(`  (${e.message.split('\n')[0]})`); return false; }
+}
+
+function parseVersion(s) {
+  const m = String(s).match(/(\d+)\.(\d+)\.(\d+)/);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+function geVersion(v, min) {
+  for (let i = 0; i < 3; i++) {
+    if (v[i] !== min[i]) return v[i] > min[i];
+  }
+  return true;
+}
+
+/** herdr 插件配置目录（用户模式 boot-config 落点；插件已注册才存在路径语义）。 */
+function herdrConfigDir() {
+  try { return run('herdr', ['plugin', 'config-dir', 'pier.workbench']); } catch { return null; }
+}
+
+/* ── 环境校验（install 前置） ────────────────────────────────────── */
+function checkEnv() {
+  const [major] = process.versions.node.split('.').map(Number);
+  if (major < 22) die(`node ≥ 22 required, found ${process.versions.node}`);
+  log(`✓ node ${process.versions.node}`);
+  const piVersion = (() => { try { return parseVersion(run('pi', ['--version'])); } catch { return null; } })();
+  if (!piVersion || !geVersion(piVersion, [0, 84, 0])) {
+    die(`pi ≥ 0.84 required${piVersion ? `, found ${piVersion.join('.')}` : ' (pi not found or not runnable)'}. Install: npm i -g @earendil-works/pi-coding-agent`);
+  }
+  log(`✓ pi ${piVersion.join('.')}`);
+  const herdrVersion = (() => { try { return parseVersion(run('herdr', ['--version'])); } catch { return null; } })();
+  if (!herdrVersion || !geVersion(herdrVersion, [0, 8, 0])) {
+    die(`herdr ≥ 0.8.0 required${herdrVersion ? `, found ${herdrVersion.join('.')}` : ' (herdr not found)'}. Install: https://herdr.dev/`);
+  }
+  log(`✓ herdr ${herdrVersion.join('.')}`);
+  return { piVersion, herdrVersion };
+}
+
+/** pi 半区源：用户模式 git 规格，dev 模式本地目录。 */
+const piSource = () => (dev ? EXT_DIR : PI_SPEC);
+
+/* ── boot-config 探测与写入 ──────────────────────────────────────── */
+function probePiRuntime() {
+  const piBin = which('pi');
+  // bin 是 node shim：realpath 落到 .../pi-coding-agent/dist/cli.js（npm 布局，win/posix 同构）
+  if (piBin) {
+    try {
+      const real = realpathSync(piBin);
+      if (real.endsWith('cli.js') && existsSync(real)) {
+        return { piCli: real, piNode: process.execPath };
+      }
+    } catch { /* 落到兜底 */ }
+  }
+  // npm root -g 兜底：pi 不在 PATH（nvm shim 等）时按全局布局拼
+  try {
+    const gRoot = run('npm', ['root', '-g']);
+    const cand = join(gRoot, '@earendil-works', 'pi-coding-agent', 'dist', 'cli.js');
+    if (existsSync(cand)) return { piCli: cand, piNode: process.execPath };
+  } catch { /* npm 不可用 */ }
+  return null;
+}
+
+function writeBootConfig(hmrDev, force) {
+  const probed = probePiRuntime();
+  if (!probed) die('cannot locate pi cli.js (tried: pi shim realpath, npm root -g). Fill boot-config.json manually.');
+  if (!existsSync(EXT_PATH)) die(`pier-ext entry missing: ${EXT_PATH} (repo layout broken?)`);
+  // 用户模式 extPath 必须指向 herdr 管理的 checkout 内的扩展（安装 herdr 半区后才知道）；
+  // git 安装布局与本地同构：packages/pier-ext/src/index.ts。
+  const extPath = dev ? EXT_PATH
+    : join(herdrManagedRootGuess(), 'packages', 'pier-ext', 'src', 'index.ts');
+
+  const config = {
+    mainTabLabel: 'main',
+    piNode: probed.piNode,
+    piCli: probed.piCli,
+    extPath,
+    workbenchPluginId: 'pier.workbench',
+    hmrDev,
+  };
+
+  const target = dev ? DEV_BOOT_CONFIG : join(herdrConfigDir() ?? die('cannot resolve herdr plugin config-dir (is pier.workbench installed?)'), 'boot-config.json');
+  if (existsSync(target) && !force) {
+    let existing = null;
+    try { existing = JSON.parse(readFileSync(target, 'utf8')); } catch { /* 视为损坏 */ }
+    if (existing) {
+      log(`• ${target} exists, diff (existing → new):`);
+      for (const k of Object.keys(config)) {
+        if (existing[k] !== config[k]) log(`    ${k}: ${JSON.stringify(existing[k])} → ${JSON.stringify(config[k])}`);
+      }
+      log('  kept existing (use --force to overwrite)');
+      return;
+    }
+  }
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, JSON.stringify(config, null, 2) + '\n');
+  log(`✓ boot-config.json ${force ? 'overwritten (--force)' : 'written'} → ${target}`);
+  log(`  piNode = ${config.piNode}`);
+  log(`  piCli  = ${config.piCli}`);
+  log(`  extPath = ${config.extPath}`);
+}
+
+/** herdr 管理的插件 checkout 根（GitHub 安装布局：…/plugins/<owner>-<repo>/…）。 */
+function herdrManagedRootGuess() {
+  const dir = herdrConfigDir();
+  if (!dir) return '';
+  // config-dir 形如 <plugins-root>/<plugin-id>/config → checkout 在 <plugins-root>/<plugin-id>/
+  return resolve(dir, '..');
+}
+
+/* ── 三命令 ──────────────────────────────────────────────────────── */
+function install() {
+  const hmrDev = flags.has('--hmr-dev');
+  const force = flags.has('--force');
+  checkEnv();
+
+  if (dev) {
+    if (tryRun('pi', ['install', piSource()])) log('✓ pi extension installed (packages/pier-ext, local)');
+    else { console.error('✗ pi install failed'); log(`  manual: pi install ${EXT_DIR}`); process.exitCode = 1; }
+    if (tryRun('herdr', ['plugin', 'link', WB_DIR])) log('✓ herdr plugin linked (packages/pier-workbench, local)');
+    else { console.error('✗ herdr plugin link failed'); log(`  manual: herdr plugin link ${WB_DIR}`); process.exitCode = 1; }
+    writeBootConfig(hmrDev, force);
+  } else {
+    if (tryRun('pi', ['install', piSource()])) log(`✓ pi extension installed (${PI_SPEC})`);
+    else { console.error('✗ pi install failed'); log(`  manual: pi install ${PI_SPEC}`); process.exitCode = 1; }
+    if (tryRun('herdr', ['plugin', 'install', HERDR_SPEC, '--yes'])) log(`✓ herdr plugin installed (${HERDR_SPEC})`);
+    else { console.error('✗ herdr plugin install failed'); log(`  manual: herdr plugin install ${HERDR_SPEC}`); process.exitCode = 1; }
+    writeBootConfig(hmrDev, force);
+  }
+
+  log(`
+pier installed (${dev ? 'dev mode: local paths, code changes are live' : 'user mode: managed checkouts'}). Next:
+  1. start herdr, open/create a workspace — the main tab auto-bootstraps a pi session
+  2. inside pi, ask the model to use todo_write / subagent tools`);
+}
+
+function uninstall() {
+  const purge = flags.has('--purge');
+  if (tryRun('pi', ['remove', piSource()])) log('✓ pi extension removed');
+  else { console.error('✗ pi remove failed'); log(`  manual: pi remove ${piSource()}`); process.exitCode = 1; }
+
+  if (dev) {
+    if (tryRun('herdr', ['plugin', 'unlink', 'pier.workbench'])) log('✓ herdr plugin unlinked (files kept)');
+    else { console.error('✗ herdr plugin unlink failed'); log('  manual: herdr plugin unlink pier.workbench'); process.exitCode = 1; }
+    if (purge && existsSync(DEV_BOOT_CONFIG)) { rmSync(DEV_BOOT_CONFIG); log('✓ dev boot-config.json purged'); }
+  } else {
+    if (tryRun('herdr', ['plugin', 'uninstall', 'pier.workbench'])) log('✓ herdr plugin uninstalled (managed checkout removed)');
+    else { console.error('✗ herdr plugin uninstall failed'); log('  manual: herdr plugin uninstall pier.workbench'); process.exitCode = 1; }
+    if (purge) {
+      const dir = herdrConfigDir();
+      const f = dir ? join(dir, 'boot-config.json') : null;
+      if (f && existsSync(f)) { rmSync(f); log('✓ boot-config.json purged'); }
+    }
+  }
+  log(`\npier uninstalled.${purge ? '' : ' (boot-config.json kept; use --purge to remove)'}`);
+}
+
+if (command === 'uninstall') uninstall();
+else if (command === 'update') { log('== uninstall =='); uninstall(); log('\n== install =='); install(); }
+else install();

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "pier-setup",
+  "version": "0.1.0",
+  "description": "One-shot installer for pier: registers the pi-pier extension with pi and the pier.workbench plugin with herdr (install / uninstall / update)",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "pier-setup": "./install.mjs"
+  },
+  "files": [
+    "install.mjs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/July24/pier.git"
+  },
+  "homepage": "https://github.com/July24/pier#readme",
+  "bugs": {
+    "url": "https://github.com/July24/pier/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "pier",
+    "installer",
+    "herdr",
+    "coding-agent"
+  ],
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "test": "node --test \"packages/*/test/*.test.ts\""
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-group": "^1.0.1",
+    "@deepseek-ai/cordis-plugin-hmr": "^1.0.16",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
+    "@deepseek-ai/cordis-plugin-timer": "^1.1.3"
+  },
+  "pi": {
+    "extensions": [
+      "./packages/pier-ext/src/index.ts"
+    ],
+    "skills": [
+      "./packages/pier-ext/skills/pi-herdr-workflow"
+    ]
+  }
+}