pi-pier 0.1.2 → 0.1.4

package/README.md

@@ -1,22 +1,40 @@
 # pi-pier
 
+> [!IMPORTANT]
+> **This npm package is only the pi-extension half of pier.** pier is a two-half system — this extension plus a **herdr plugin** (`pier.workbench`). Without the herdr side you still get `todo_write` / `ask_user_question`, but subagents, pane integration, notifications, and the workspace bootstrap all require herdr. See [Install the herdr half](#install-the-herdr-half-companion-plugin) below.
+
 **pier** = **pi** × h**erdr** — a [pi](https://pi.dev/) extension that fuses coding agent sessions with the [herdr](https://herdr.dev/) pane/tab orchestrator.
 
-`pi-pier` is the **pi extension half** of the [pier monorepo](https://github.com/July24/pier). It fills two gaps pi deliberately leaves open — the **todo list loop** and **interactive subagents** — using herdr panes/tabs as the visual and interaction substrate. It degrades gracefully outside herdr.
+`pi-pier` fills two gaps pi deliberately leaves open — the **todo list loop** and **interactive subagents** — using herdr panes/tabs as the visual and interaction substrate. It degrades gracefully outside herdr.
 
-## Install
+## Install (this pi half)
 
 ```sh
 pi install npm:pi-pier
 ```
 
-Or from git:
+Or from git (monorepo root, same content):
 
 ```sh
 pi install git:github.com/July24/pier
 ```
 
-> The companion **herdr plugin half** (`pier.workbench`: main-tab bootstrap, blocked-gate notifications, focus-heat layout) is installed separately via `herdr plugin install July24/pier/packages/pier-workbench`, or all at once with the one-shot installer in the [repo](https://github.com/July24/pier): `node install.mjs`.
+## Install the herdr half (companion plugin)
+
+The herdr plugin `pier.workbench` provides the other half: main-tab bootstrap (auto-start a pi master session per workspace), blocked-gate notifications (system notifications when a subagent waits for a human), and the focus-heat layout (focused pane grows in place). Install it from the same repo:
+
+```sh
+herdr plugin install July24/pier/packages/pier-workbench --yes
+```
+
+Or install **both halves at once** with the one-shot installer from the monorepo:
+
+```sh
+git clone https://github.com/July24/pier && cd pier
+node install.mjs        # user mode: installs both halves + generates local bootstrap config
+```
+
+The installer also verifies node / pi / herdr versions, probes local paths, and writes the workbench bootstrap config (`boot-config.json`) into herdr's plugin config dir.
 
 ## What you get
 
@@ -45,7 +63,7 @@ Outside a herdr environment the extension auto-degrades: herdr reporting costs n
 
 - Node ≥ 22
 - pi ≥ 0.84 (`@earendil-works/pi-coding-agent`)
-- herdr ≥ 0.8.0 for the full pane experience (optional)
+- **herdr ≥ 0.8.0** — required for subagents / pane integration / notifications (see the IMPORTANT note above); without it only `todo_write` / `ask_user_question` work
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-pier",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "pier: pi extension that fuses pi agent sessions with the herdr pane/tab orchestrator — todo_write loop closure + interactive subagents in isolated panes",
   "license": "MIT",
   "type": "module",

package/src/core/grid-shape.ts

@@ -1,6 +1,10 @@
 /**
- * D91 网格形态：spawn 时挑「最大格子沿长轴分裂」，让 pane 自然铺成方格
- * （用户愿景：股票热力图式方格；横向格更易读最新输出）。
+ * D97 网格形态：spawn 时挑「最大格子」一律 down（上下拆），让 pane 长成全宽横条。
+ *
+ * 动因（用户实证）：热力把非焦点格压窄后，横条仍保全宽——pane title 静帧
+ * （slim-frame.ts 同源投影）一行横读；旧「方格」拓扑的非焦点格是竖窄条，
+ * title 折成一竖列不可读。静帧 overlay 的可见性谓词（长宽 < TUI 下限）与
+ * 本拓扑配套：横条命中行数下限、存量竖条命中列数下限，两代布局都被接住。
  *
  * 依据 herdr 0.8.2 源码：ratio = split 节点 first child 份额（split_rect：
  * first_w = width*ratio）；layout.apply 不能挂接既有 pane（只建新 shell），
@@ -67,8 +71,9 @@ export function paneCells(root: ShapeNode, width = 200, height = 50): PaneCell[]
 }
 
 /**
- * 挑分裂目标：面积最大的格子（并列取先序第一，稳定），沿长轴分裂——
- * 宽 ≥ 1.3×高 → right（左右分，保格子横向可读），否则 down。
+ * 挑分裂目标：面积最大的格子（并列取先序第一，稳定），一律 down（上下拆）。
+ * 模型 200×50 下 pane 数上限（热力 MAX_AUTO_LAYOUT_PANES=10）内条高最低 5 行
+ * ——低于 TUI 可用下限即静帧，正是设计语义（条 = title 帧，点击放大看真身）。
  * exclude = 不许动的格子（board 等无 agent 常驻 shell）。
  */
 export function pickGridSplit(
@@ -82,5 +87,5 @@ export function pickGridSplit(
   for (const c of cells) {
     if (c.w * c.h > best.w * best.h + 1e-9) best = c;
   }
-  return { targetPaneId: best.id, direction: best.w > best.h * 1.3 ? 'right' : 'down' };
+  return { targetPaneId: best.id, direction: 'down' };
 }