pi-skill-stacks 0.4.2 → 0.6.0

package/README.md

@@ -1,13 +1,6 @@
 # pi-skill-stacks
 
-A [pi](https://github.com/earendil-works/pi-mono) package that groups your skills into named stacks you can toggle on and off, so an agent session only pays for the skills it needs. `/stacks` opens an overlay; disabled skills vanish from the system prompt, `/skill:` commands, and discovery.
-
-## What it does
-
-- `/stacks` opens a two-pane overlay. Left: stacks with on/off state, create (`n`), delete (`d`), and `a` to add skills that aren't in any stack yet. Right: the selected stack's members; `space` removes one, `enter` opens the skill's full markdown in a viewer pane. So you can build and edit stacks without touching JSON. Changes persist as you make them; pi reloads once when you close the overlay, and only if a toggle actually changed `settings.json`.
-- `/stacks on <stack>` / `/stacks off <stack>` toggle a single stack (with argument completion); `/stacks list` prints state without changing anything. Bare `/stacks` outside the TUI (RPC/print mode) prints the list too.
-- Toggling off writes `!skills/<dir>/SKILL.md` exclusion patterns into the global settings `skills` array — pi's own override mechanism — so disabled skills are excluded everywhere, not just from the prompt. The extension only ever removes patterns it wrote itself (tracked in `managedExclusions`); hand-written `pi config` entries are left alone.
-- The bundled header extension replaces pi's startup `[Skills]` listing with a compact line like `matt-pocock (28), firecrawl (28) · 76/76 skills active` (with `off: <name> (n)` segments for disabled stacks) and hides the `[Themes]` section.
+A [pi](https://github.com/earendil-works/pi-mono) package that groups skills into named stacks you can toggle on and off. Disabled skills leave the system prompt, `/skill:` commands, and discovery.
 
 ## Install
 
@@ -15,27 +8,25 @@ A [pi](https://github.com/earendil-works/pi-mono) package that groups your skill
 pi install npm:pi-skill-stacks
 ```
 
-or from git:
+## Use
 
-```bash
-pi install git:github.com/oscabriel/pi-skill-stacks
-```
+`/stacks` opens an overlay. Left pane: stacks with on/off state. Right pane: the selected stack's members. `enter` on a member shows its markdown.
 
-Or from a local checkout:
+| Pane | Keys |
+| --- | --- |
+| stacks | `↑`/`↓` select · `space` on/off · `→` members · `a` add skills · `n` new stack · `d` delete · `esc` close |
+| members | `↑`/`↓` move · `space` remove · `→` view · `a` add skills · `←` back |
+| viewer | `↑`/`↓` scroll (mouse wheel in fullscreen) · `←` back |
 
-```bash
-pi install /path/to/pi-skill-stacks
-```
+`a` opens a picker of skills not yet in any stack. Type to filter it, `space` to mark several, `enter` to add. To move a skill between stacks, `space` it out of one and `a` it into the other.
 
-Use `-l` to install project-local instead of global. Try it without installing:
+With no stacks defined, `enter` (or `n`) creates the first one and opens the picker right after.
 
-```bash
-pi -e git:github.com/oscabriel/pi-skill-stacks
-```
+From the command line: `/stacks on <stack>`, `/stacks off <stack>`, `/stacks list`.
 
-## Configure stacks
+## How it works
 
-The package ships with no stacks. Open `/stacks` and press `n` to create one, or write `~/.pi/agent/skill-stacks.json` (or `<agentDir>/skill-stacks.json`; `PI_CODING_AGENT_DIR` is honoured like pi does) by hand:
+Stacks live in `~/.pi/agent/skill-stacks.json` (`PI_CODING_AGENT_DIR` is honoured). You can edit it by hand:
 
 ```json
 {
@@ -46,66 +37,18 @@ The package ships with no stacks. Open `/stacks` and press `n` to create one, or
 }
 ```
 
-Each stack maps a name to skill names. Skills are discovered the way pi discovers them: every `SKILL.md` under `~/.agents/skills/` and `<agentDir>/skills/`, recursing into subdirectories (skipping dot-directories and `node_modules`), named by the frontmatter `name` or, failing that, the directory name. Nested skills get full-path exclusion patterns such as `!skills/group/nested/SKILL.md`.
-
-A project can add or override stack definitions in `<project>/.pi/skill-stacks.json`. Project stacks contribute definitions only; on/off state is global. In the overlay they can be toggled but not edited or deleted — edit the project file instead.
-
-The config file is validated on every load. A malformed entry (a stack that isn't an array, invalid JSON, and so on) aborts the command with an error and nothing is written, rather than defaulting to an empty config and saving that back.
-
-## Overlay keys
-
-Navigation is consistent across panes: `←`/`esc` always goes back a pane, `→`/`tab` (or `enter` on a member) always goes forward. `←` in the leftmost pane and `→` in the viewer do nothing.
-
-| Pane | Keys |
-| --- | --- |
-| stacks | `↑`/`↓` (or `k`/`j`) select · `space` on/off · `→`/`l`/`tab`/`enter` into members · `a` add skills · `n` new stack · `d` delete · `esc`/`q` close |
-| members | `↑`/`↓` (or `k`/`j`) move · `space` remove the skill · `enter`/`→`/`tab` view skill · `a` add skills · `←`/`h`/`esc` back to stacks |
-| skill viewer | `↑`/`↓` (or `k`/`j`) scroll · `enter`/`←`/`h`/`esc` back to members |
-| add skills dialog | `↑`/`↓` move · `space` mark · `enter` add the marked skills (or the highlighted one) · `esc` cancel |
-| new stack / delete dialogs | `enter` confirm · `esc` cancel |
-
-The `a`, `n` and `d` dialogs open as small overlays on top of `/stacks`. `a` lists only skills that no stack holds yet. To move a skill between stacks, `space` it out of one and `a` it into the other.
-
-In fullscreen TUI mode the mouse wheel scrolls the skill viewer when the pointer is over the overlay. In regular mode the terminal owns the mouse and wheel input goes to its own scrollback.
-
-`enter` in the members pane opens the skill's full markdown in a viewer pane inside the overlay: frontmatter dim, headings bold, bullets and indented code rendered, links shown as their text.
-
-The title bar shows `reload pending` once a change has touched `settings.json`; the reload runs when you close the overlay.
-
-## Rules
-
-- **Overlap:** a skill is excluded only when it appears in at least one stack and no enabled stack contains it. Skills in no stack are never touched. So disabling a stack whose members all also belong to an enabled stack excludes nothing.
-- **Stacks, not skills:** `on`/`off` take stack names only. To exclude a single skill regardless of stacks, use `pi config` (its `!` entries are respected and never claimed).
-- **Persist-then-reload:** `on`/`off` commands write immediately and reload if `settings.json` changed. In the overlay every change is written as you make it and a single reload runs on close, again only if `settings.json` changed; re-stacking alone doesn't need one (the header line catches up on the next reload).
-- **Other projects' stacks:** a project stack you disabled from inside its project stays disabled when you toggle things elsewhere. Its `disabledStacks` entry and the exclusions written for its skills are preserved, because from another directory those skills are "in no stack" and so left alone.
-
-## Header
-
-The header extension swaps pi's full skills listing for a compact summary and hides `[Themes]`. It also replaces the stock header banner with a minimal one-line directory label. If you run your own header extension (custom art, dashboard, and so on), disable this one and keep yours — add a filter to the package entry in `settings.json`:
-
-```json
-{
-  "packages": [
-    {
-      "source": "git:github.com/oscabriel/pi-skill-stacks",
-      "extensions": ["!extensions/header.ts"]
-    }
-  ]
-}
-```
+Skills are discovered like pi does: every `SKILL.md` under `~/.agents/skills/` and `<agentDir>/skills/`, named by frontmatter `name` or the directory name. A project can add stack definitions in `<project>/.pi/skill-stacks.json`; those can be toggled but not edited from the overlay.
 
-Your header extension can import the section machinery from this package's `extensions/header.ts` to render the same compact line itself: `buildSkillsSection(cwd, theme)` builds the node, `replaceSkillsSection(root, node)` and `hideThemesSection(root)` splice pi's sections, `isOurSection`, `firstLineOf`, and `renderedText` are the matchers, and `SectionTheme`/`RenderableNode` are the structural types they take.
+Turning a stack off writes `!skills/<dir>/SKILL.md` patterns into the `skills` array of `~/.pi/agent/settings.json`, pi's own exclusion mechanism. The package only removes patterns it wrote itself; hand-written entries stay. A skill is excluded only when no enabled stack contains it, and skills in no stack are never touched. pi reloads once when the overlay closes, only if `settings.json` changed.
 
-## Notes
+Stack names that don't match a discovered skill are flagged `missing` and not counted.
 
-- If a stack references skill names that don't resolve to a discovered skill, every `/stacks` invocation warns with the missing names, and the overlay flags them inline as `missing`.
-- Counts in the overlay and header only include discovered skills, so a stale name doesn't inflate the numbers.
-- `settings.json` is rewritten without a trailing newline to match pi's own formatting; `skill-stacks.json` ends with one.
+For other extensions, `loadStacksSummary()` in `src/store.ts` returns stack names, on/off state, and counts (`totalCount`, `activeCount`, `unstackedCount`).
 
 ## Develop
 
 ```bash
-npm install        # dev-only: pi's type declarations for tsc
-npm run check      # typecheck
-npm test           # node --test
+npm install
+npm run check
+npm test
 ```

package/extensions/dialogs.ts

@@ -7,10 +7,30 @@
 import { type Component, type Focusable, Input, Key, matchesKey } from "@earendil-works/pi-tui";
 import { frameEdge, frameInnerWidth, frameRow, type OverlayTheme, padToWidth } from "./frame.ts";
 
-/** Single-line text prompt. Resolves with the trimmed value, or undefined on escape. */
-export class PromptDialog implements Component, Focusable {
-  private readonly input = new Input();
+/**
+ * A dialog built around one pi-tui Input. Focus is forwarded to the Input so it
+ * emits the hardware-cursor marker (IME placement) while the dialog is open.
+ */
+abstract class InputDialog implements Component, Focusable {
+  protected readonly input = new Input();
   private _focused = false;
+
+  get focused() {
+    return this._focused;
+  }
+
+  set focused(value: boolean) {
+    this._focused = value;
+    this.input.focused = value;
+  }
+
+  abstract handleInput(data: string): void;
+  abstract render(width: number): string[];
+  invalidate() {}
+}
+
+/** Single-line text prompt. Resolves with the trimmed value, or undefined on escape. */
+export class PromptDialog extends InputDialog {
   private readonly theme: OverlayTheme;
   private readonly title: string;
   private readonly placeholder: string | undefined;
@@ -22,22 +42,13 @@ export class PromptDialog implements Component, Focusable {
     placeholder: string | undefined,
     done: (value: string | undefined) => void,
   ) {
+    super();
     this.theme = theme;
     this.title = title;
     this.placeholder = placeholder;
     this.done = done;
   }
 
-  /** Propagate focus to the Input so it emits the hardware-cursor marker (IME placement). */
-  get focused() {
-    return this._focused;
-  }
-
-  set focused(value: boolean) {
-    this._focused = value;
-    this.input.focused = value;
-  }
-
   handleInput(data: string) {
     if (matchesKey(data, Key.enter) || data === "\n") {
       this.done(this.input.getValue().trim());
@@ -48,8 +59,6 @@ export class PromptDialog implements Component, Focusable {
     }
   }
 
-  invalidate() {}
-
   render(width: number) {
     const inner = frameInnerWidth(width);
     const [inputLine = ""] = this.input.render(inner);
@@ -100,11 +109,12 @@ export class ConfirmDialog implements Component {
 }
 
 /**
- * Pick one or more skills from a list. `space` marks, `enter` resolves with the
- * marked set (or just the highlighted skill when nothing is marked), `esc`
- * resolves undefined.
+ * Pick one or more skills from a searchable list. Typing filters (case-insensitive
+ * substring); `space` marks, `enter` resolves with the marked set (or just the
+ * highlighted skill when nothing is marked — marks survive refiltering), `esc`
+ * resolves undefined. Arrows move; plain letters go to the filter, so no j/k here.
  */
-export class PickDialog implements Component {
+export class PickDialog extends InputDialog {
   static readonly MAX_ROWS = 16;
 
   private readonly theme: OverlayTheme;
@@ -114,6 +124,8 @@ export class PickDialog implements Component {
   private readonly marked = new Set<string>();
   private cursor = 0;
   private offset = 0;
+  /** Filtered view of `items`, recomputed only when the query changes. */
+  private matchCache: { query: string; items: string[] } | undefined;
 
   constructor(
     theme: OverlayTheme,
@@ -121,6 +133,7 @@ export class PickDialog implements Component {
     items: readonly string[],
     done: (picked: string[] | undefined) => void,
   ) {
+    super();
     this.theme = theme;
     this.title = title;
     this.items = items;
@@ -129,45 +142,74 @@ export class PickDialog implements Component {
 
   handleInput(data: string) {
     if (matchesKey(data, Key.enter) || data === "\n") {
-      const highlighted = this.items[this.cursor];
+      const matches = this.matches();
+      const highlighted = matches[this.cursor];
       const picked = this.marked.size > 0 ? this.items.filter((s) => this.marked.has(s)) : highlighted ? [highlighted] : [];
       this.done(picked);
     } else if (matchesKey(data, Key.escape)) {
       this.done(undefined);
-    } else if (matchesKey(data, Key.down) || data === "j") {
+    } else if (matchesKey(data, Key.down)) {
       this.move(1);
-    } else if (matchesKey(data, Key.up) || data === "k") {
+    } else if (matchesKey(data, Key.up)) {
       this.move(-1);
     } else if (data === " ") {
-      const skill = this.items[this.cursor];
+      const skill = this.matches()[this.cursor];
       if (!skill) return;
       if (this.marked.has(skill)) this.marked.delete(skill);
       else this.marked.add(skill);
+    } else {
+      this.input.handleInput(data);
+      this.clampToMatches();
     }
   }
 
-  invalidate() {}
-
   render(width: number) {
+    const inner = frameInnerWidth(width);
     const rows = this.visibleRows();
+    const matches = this.matches();
     const lines = [frameEdge(this.theme, width, this.title, true)];
+    const query = this.input.getValue();
+    const [inputLine = ""] = this.input.render(inner);
+    lines.push(frameRow(this.theme, width, query === "" ? this.theme.fg("dim", "type to filter") : inputLine));
     for (let row = 0; row < rows; row += 1) {
       const index = this.offset + row;
-      const skill = this.items[index];
-      lines.push(frameRow(this.theme, width, skill ? this.cell(skill, index, frameInnerWidth(width)) : ""));
+      const skill = matches[index];
+      lines.push(frameRow(this.theme, width, skill ? this.cell(skill, index, inner) : ""));
     }
     const marked = this.marked.size > 0 ? ` · ${this.marked.size} marked` : "";
-    lines.push(frameEdge(this.theme, width, `↑↓ move · space mark · enter add${marked} · esc cancel`, false));
+    const filtered = query === "" ? "" : ` · ${matches.length}/${this.items.length}`;
+    lines.push(frameEdge(this.theme, width, `type filter · ↑↓ move · space mark · enter add${marked}${filtered} · esc cancel`, false));
     return lines;
   }
 
   private visibleRows() {
-    return Math.max(1, Math.min(PickDialog.MAX_ROWS, this.items.length));
+    return Math.max(1, Math.min(PickDialog.MAX_ROWS, this.matches().length));
+  }
+
+  /** Items that match the current filter, in list order. Cached per query; callers must not mutate it. */
+  private matches(): readonly string[] {
+    const query = this.input.getValue().trim().toLowerCase();
+    if (this.matchCache?.query !== query) {
+      this.matchCache = {
+        query,
+        items: query === "" ? [...this.items] : this.items.filter((item) => item.toLowerCase().includes(query)),
+      };
+    }
+    return this.matchCache.items;
+  }
+
+  /** Keep cursor and scroll window inside the filtered list after a query change. */
+  private clampToMatches() {
+    const total = this.matches().length;
+    this.cursor = Math.max(0, Math.min(total - 1, this.cursor));
+    const rows = this.visibleRows();
+    this.offset = Math.max(0, Math.min(this.offset, Math.max(0, total - rows)));
   }
 
   private move(delta: number) {
-    if (this.items.length === 0) return;
-    this.cursor = Math.max(0, Math.min(this.items.length - 1, this.cursor + delta));
+    const total = this.matches().length;
+    if (total === 0) return;
+    this.cursor = Math.max(0, Math.min(total - 1, this.cursor + delta));
     const rows = this.visibleRows();
     if (this.cursor < this.offset) this.offset = this.cursor;
     else if (this.cursor >= this.offset + rows) this.offset = this.cursor - rows + 1;

package/extensions/frame.ts

@@ -37,3 +37,33 @@ export function frameRow(theme: OverlayTheme, width: number, content: string) {
 
 /** Width available to content inside `frameRow`. */
 export const frameInnerWidth = (width: number) => Math.max(0, width - 4);
+
+/** Word-wrap plain text to `width` display columns; over-long words are hard-split. */
+export function wrapText(text: string, width: number): string[] {
+  const out: string[] = [];
+  for (const paragraph of text.split("\n")) {
+    if (paragraph === "") {
+      out.push("");
+      continue;
+    }
+    let line = "";
+    for (const word of paragraph.split(" ")) {
+      const candidate = line ? `${line} ${word}` : word;
+      if (visibleWidth(candidate) <= width) {
+        line = candidate;
+        continue;
+      }
+      if (line) out.push(line);
+      let rest = word;
+      while (visibleWidth(rest) > width) {
+        let cut = width;
+        while (cut > 1 && visibleWidth(rest.slice(0, cut)) > width) cut -= 1;
+        out.push(rest.slice(0, cut));
+        rest = rest.slice(cut);
+      }
+      line = rest;
+    }
+    if (line) out.push(line);
+  }
+  return out;
+}

package/extensions/overlay.ts

@@ -19,8 +19,10 @@ import {
   visibleWidth,
 } from "@earendil-works/pi-tui";
 import { ConfirmDialog, PickDialog, PromptDialog } from "./dialogs.ts";
-import { frameEdge, type OverlayTheme, padToWidth } from "./frame.ts";
+import { frameEdge, type OverlayTheme, padToWidth, wrapText } from "./frame.ts";
+import { homedir } from "node:os";
 import type { StackMap, StacksSummary } from "../src/core.ts";
+import { defaultSkillRoots } from "../src/store.ts";
 import {
   StacksOverlayModel,
   type MemberRow,
@@ -72,6 +74,24 @@ const CELL_PREFIX_WIDTH = CURSOR.length + 3 + 1;
 const projectStackNotice = (stack: string) =>
   `"${stack}" is defined in .pi/skill-stacks.json; edit it there`;
 
+/** The directories skills are discovered from, with $HOME shortened to `~`. */
+function skillRootsNotice() {
+  const home = homedir();
+  const shown = defaultSkillRoots().map(({ dir }) => (dir.startsWith(home) ? `~${dir.slice(home.length)}` : dir));
+  return `No skills discovered (looked in ${shown.join(" and ")})`;
+}
+
+// Paragraphs only — wrapText reflows each to the members pane's width.
+const EMPTY_INTRO = [
+  "No stacks yet",
+  "",
+  "A stack is a named group of skills you can switch on and off together. Skills that are off leave the system prompt, /skill: commands, and discovery.",
+  "",
+  "Press n (or enter) to create one. You'll pick its skills right after.",
+  "",
+  "Later, a adds skills to the selected stack and space switches it on or off.",
+].join("\n");
+
 /**
  * Wheel direction from a terminal mouse report: -1 up, +1 down, 0 not a wheel
  * event. Matches pi-tui's parseWheelEvent — in fullscreen mode pi captures the
@@ -141,9 +161,14 @@ export class StacksOverlay {
       matchesKey(data, Key.tab) ||
       data === "l"
     ) {
-      this.model.setFocus("members");
-      this.model.moveMember(0, this.memberRows());
-      this.tui.requestRender();
+      if (this.model.stackCount === 0) {
+        // first-run shortcut: enter on an empty list starts the create flow
+        this.openNewStackDialog();
+      } else {
+        this.model.setFocus("members");
+        this.model.moveMember(0, this.memberRows());
+        this.tui.requestRender();
+      }
     } else if (data === "n") {
       this.openNewStackDialog();
     } else if (data === "d") {
@@ -247,7 +272,15 @@ export class StacksOverlay {
 
       let members: string;
       if (!stack) {
-        members = row === 0 ? hint(" no stacks · n creates one", membersW) : blank(membersW);
+        const intro = wrapText(EMPTY_INTRO, Math.max(10, membersW - 1));
+        const text = intro[row];
+        if (text === undefined) {
+          members = blank(membersW);
+        } else if (row === 0) {
+          members = padToWidth(this.theme.fg("accent", this.theme.bold(` ${text}`)), membersW);
+        } else {
+          members = padToWidth(this.theme.fg("text", ` ${text}`), membersW);
+        }
       } else if (row === 0) {
         members = this.renderStackHeader(stack, membersW);
       } else if (row === 1) {
@@ -287,22 +320,27 @@ export class StacksOverlay {
           ["↑↓", "scroll"],
           ["←", "back"],
         ])
-      : this.model.focus === "stacks"
+      : this.model.stackCount === 0
         ? this.hintBar([
-            ["↑↓", "select"],
-            ["space", "on/off"],
-            ["→", "members"],
-            ["a", "add skills"],
-            ["n", "new stack"],
-            ["d", "delete"],
+            ["n/enter", "new stack"],
             ["esc", "close"],
           ])
-        : this.hintBar([
-            ["↑↓", "move"],
-            ["space", "remove"],
-            ["←/→", "back/view"],
-            ["a", "add skills"],
-          ]);
+        : this.model.focus === "stacks"
+          ? this.hintBar([
+              ["↑↓", "select"],
+              ["space", "on/off"],
+              ["→", "members"],
+              ["a", "add skills"],
+              ["n", "new stack"],
+              ["d", "delete"],
+              ["esc", "close"],
+            ])
+          : this.hintBar([
+              ["↑↓", "move"],
+              ["space", "remove"],
+              ["←/→", "back/view"],
+              ["a", "add skills"],
+            ]);
     lines.push(this.border(width, help, false));
     return lines;
   }
@@ -333,6 +371,7 @@ export class StacksOverlay {
 
   private openNewStackDialog() {
     void this.withDialog(async () => {
+      const wasEmpty = this.model.stackCount === 0;
       const name = (await this.callbacks.input("New stack name", "e.g. writing"))?.trim();
       if (!name) return;
       if (!this.model.createStack(name)) {
@@ -340,9 +379,30 @@ export class StacksOverlay {
         return;
       }
       this.apply();
+      if (wasEmpty) await this.pickSkillsForSelectedStack();
     });
   }
 
+  /** The add-skills picker for the selected stack, shared by `a` and the first-run create flow. */
+  private async pickSkillsForSelectedStack() {
+    const name = this.model.selectedStack;
+    if (!name) return;
+    if (this.model.isProjectStack(name)) {
+      this.callbacks.notify(projectStackNotice(name), "warning");
+      return;
+    }
+    const unstacked = this.model.unstackedSkills();
+    if (unstacked.length === 0) {
+      this.callbacks.notify(
+        this.model.discoveredCount === 0 ? skillRootsNotice() : "Every discovered skill is already in a stack",
+        "info",
+      );
+      return;
+    }
+    const picked = await this.callbacks.pick(`Add to ${name} · ${unstacked.length} unstacked`, unstacked);
+    if (picked && this.model.addSkills(picked) === "added") this.apply();
+  }
+
   private openDeleteDialog() {
     const name = this.model.selectedStack;
     if (!name) return;
@@ -362,21 +422,8 @@ export class StacksOverlay {
 
   /** `a`: pick from the skills no stack holds yet and add them to the selected stack. */
   private openAddDialog() {
-    const name = this.model.selectedStack;
-    if (!name) return;
-    if (this.model.isProjectStack(name)) {
-      this.callbacks.notify(projectStackNotice(name), "warning");
-      return;
-    }
-    const unstacked = this.model.unstackedSkills();
-    if (unstacked.length === 0) {
-      this.callbacks.notify("Every discovered skill is already in a stack", "info");
-      return;
-    }
-    void this.withDialog(async () => {
-      const picked = await this.callbacks.pick(`Add to ${name} · ${unstacked.length} unstacked`, unstacked);
-      if (picked && this.model.addSkills(picked) === "added") this.apply();
-    });
+    if (!this.model.selectedStack) return;
+    void this.withDialog(() => this.pickSkillsForSelectedStack());
   }
 
   private bodyRows() {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-skill-stacks",
-  "version": "0.4.2",
-  "description": "Pi package that groups skills into named stacks you can manage from a /stacks overlay — toggle stacks on/off and re-stack skills without editing JSON. Exclusions are written through pi's own settings override mechanism, and a compact [Skills] header line replaces the per-scope listing.",
+  "version": "0.6.0",
+  "description": "Pi package that groups skills into named stacks you can manage from a /stacks overlay — toggle stacks on/off and re-stack skills without editing JSON. Exclusions are written through pi's own settings override mechanism.",
   "keywords": [
     "pi-package",
     "pi",
@@ -27,8 +27,7 @@
   },
   "pi": {
     "extensions": [
-      "./extensions/index.ts",
-      "./extensions/header.ts"
+      "./extensions/index.ts"
     ]
   },
   "devDependencies": {

package/src/core.ts

@@ -36,7 +36,9 @@ export interface StacksSummary {
   offStacks: string[];
   totalCount: number;
   activeCount: number;
-  /** Per-stack status in definition order, for the header section body. */
+  /** Discovered skills that no stack contains. */
+  unstackedCount: number;
+  /** Per-stack status in definition order. */
   stacks: StackStatus[];
 }
 
@@ -59,6 +61,9 @@ export function missingSkillNames(stacks: StackMap, discovered: DiscoveredSkills
   return missing;
 }
 
+/** Every skill name any stack references, discovered or not. */
+export const stackedSkills = (stacks: StackMap) => new Set(Object.values(stacks).flat());
+
 /**
  * A skill is excluded iff it appears in at least one stack and no enabled
  * stack contains it. Skills in no stack are never excluded.
@@ -161,7 +166,7 @@ export function nextDisabledStacks(
   return sortNames(new Set([...unseen, ...visibleDisabled]));
 }
 
-/** Counts for the compact `[Skills]` header line. Only discovered skills are counted. */
+/** Stack, active-skill, and unstacked-skill counts. Only discovered skills are counted. */
 export function summarizeStacks(
   stacks: StackMap,
   disabledStacks: string[],
@@ -169,9 +174,12 @@ export function summarizeStacks(
 ): StacksSummary {
   const stackNames = Object.keys(stacks);
   const excluded = computeExcludedSkills(stacks, disabledStacks);
+  const stacked = stackedSkills(stacks);
   let activeCount = 0;
+  let unstackedCount = 0;
   for (const name of discovered.keys()) {
     if (!excluded.has(name)) activeCount += 1;
+    if (!stacked.has(name)) unstackedCount += 1;
   }
   const disabled = new Set(disabledStacks);
   return {
@@ -179,6 +187,7 @@ export function summarizeStacks(
     offStacks: disabledStacks.filter((name) => stackNames.includes(name)),
     totalCount: discovered.size,
     activeCount,
+    unstackedCount,
     stacks: Object.entries(stacks).map(([name, skills]) => ({
       name,
       size: skills.filter((skill) => discovered.has(skill)).length,

package/src/overlay-model.ts

@@ -8,7 +8,13 @@
 // to them would be shadowed by the project config on the next merge.
 
 import { renderMarkdown, type MarkdownStyler } from "./markdown.ts";
-import { computeExcludedSkills, sortNames, type DiscoveredSkills, type StackMap } from "./core.ts";
+import {
+  computeExcludedSkills,
+  sortNames,
+  stackedSkills,
+  type DiscoveredSkills,
+  type StackMap,
+} from "./core.ts";
 
 export type OverlayFocus = "stacks" | "members" | "viewer";
 
@@ -130,7 +136,7 @@ export class StacksOverlayModel {
 
   /** Discovered skills that no stack (enabled or not) contains, sorted. */
   unstackedSkills() {
-    const stacked = new Set(Object.values(this.stackMap).flat());
+    const stacked = stackedSkills(this.stackMap);
     return sortNames([...this.discovered.keys()].filter((skill) => !stacked.has(skill)));
   }
 

package/src/store.ts

@@ -246,9 +246,10 @@ export function updateSettingsSkills(path: string, skills: string[]) {
 }
 
 /**
- * Fresh-from-disk summary for the compact `[Skills]` header line.
- * Returns undefined when no stacks are configured (leave pi's section alone).
- * Throws ConfigError on malformed config; the header catches and falls back.
+ * Fresh-from-disk stacks summary for external consumers (e.g. a user's own
+ * header extension). Not used by the package itself.
+ * Returns undefined when no stacks are configured. Throws ConfigError on
+ * malformed config; callers decide whether to fall back.
  */
 export function loadStacksSummary(cwd: string) {
   const global = loadStacksConfig();

package/extensions/header.ts

@@ -1,262 +0,0 @@
-/**
- * pi-skill-stacks header extension: replaces pi's startup `[Skills]` section
- * with a compact one-line summary (e.g. `matt-pocock (28), firecrawl (28) ·
- * 76/76 skills active`), hides the `[Themes]` section, and renders a minimal
- * one-line banner in place of pi's stock header.
- *
- * Disable this file (settings.json package filter `!extensions/header.ts`) to
- * keep your own header extension; the /stacks command extension is unaffected.
- * The section-building helpers are exported so a custom header can reuse them.
- *
- * Mechanism notes:
- * - pi's startup sections are childless leaves inside one container. The
- *   container's first rendered line can itself be "[Skills]" (when no
- *   [Context] section precedes it), so matchers require !hasChildren.
- * - showLoadedResources runs after extension session_start handlers, so
- *   post-paint sweeps alone flash the full listing for a frame. addChild
- *   wrapping swaps our node in at insertion time instead. Timed sweeps stay
- *   as fallback for late installs; resources_discover re-runs the walk.
- */
-import { homedir } from "node:os";
-import { isAbsolute, relative } from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { loadStacksSummary } from "../src/store.ts";
-
-export interface RenderableNode {
-  children?: RenderableNode[];
-  addChild?(component: RenderableNode): void;
-  invalidate(): void;
-  render(width: number): string[];
-}
-
-/** Subset of pi's Theme we use; the real Theme is assignable to it. */
-export interface SectionTheme {
-  fg(color: "mdHeading" | "dim", text: string): string;
-}
-
-export interface DashboardTui extends RenderableNode {
-  requestRender(force?: boolean): void;
-}
-
-const RESET = "\x1b[0m";
-const BOLD = "\x1b[1m";
-const DIM = "\x1b[2m";
-const ANSI_PATTERN =
-  /[\u001B\u009B][[\]()#;?]*(?:(?:(?:[a-zA-Z\d]*(?:;[a-zA-Z\d]*)*)?\u0007)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]))/g;
-
-const hasChildren = (
-  component: RenderableNode,
-): component is RenderableNode & { children: RenderableNode[] } => Array.isArray(component.children);
-
-export function renderedText(component: RenderableNode) {
-  try {
-    return component.render(200).join("\n").replace(ANSI_PATTERN, "");
-  } catch {
-    return "";
-  }
-}
-
-export function firstLineOf(component: RenderableNode) {
-  return renderedText(component)
-    .split("\n")
-    .find((line) => line.trim())
-    ?.trim();
-}
-
-// Marks the section nodes we build, so the addChild interceptor and the sweep
-// never re-match them (their first rendered line is also exactly "[Skills]").
-const ourSections = new WeakSet<object>();
-
-export const isOurSection = (component: object) => ourSections.has(component);
-
-/** A pi section leaf we should act on: exact header line, childless, not one of ours. */
-const isPiSection = (child: RenderableNode, header: string) =>
-  firstLineOf(child) === header && !hasChildren(child) && !isOurSection(child);
-
-export function hideThemesSection(component: RenderableNode): boolean {
-  if (!hasChildren(component)) return false;
-
-  for (let index = 0; index < component.children.length; index += 1) {
-    const child = component.children[index]!;
-    // Leaf check: pi's section components are childless ExpandableText nodes.
-    // The parent resources container can render the same first line when it's
-    // the first section, and matching it would splice out every section.
-    if (isPiSection(child, "[Themes]")) {
-      const next = component.children[index + 1];
-      const removeCount = next && renderedText(next).trim() === "" ? 2 : 1;
-      component.children.splice(index, removeCount);
-      component.invalidate();
-      return true;
-    }
-    if (hideThemesSection(child)) return true;
-  }
-  return false;
-}
-
-/**
- * Build a replacement [Skills] section styled like pi's own sections:
- * mdHeading header line, dim indented body listing each stack with its size,
- * disabled stacks separately, plus the active-skill count. Data is read fresh
- * from disk so it stays correct across /reload. Returns undefined when no
- * stacks are configured or the config is unreadable (pi's section is left alone).
- */
-export function buildSkillsSection(cwd: string, theme: SectionTheme | undefined) {
-  let summary;
-  try {
-    summary = loadStacksSummary(cwd);
-  } catch {
-    return undefined;
-  }
-  if (!summary) return undefined;
-  const heading = (text: string) => (theme ? theme.fg("mdHeading", text) : `${BOLD}${text}${RESET}`);
-  const dim = (text: string) => (theme ? theme.fg("dim", text) : `${DIM}${text}${RESET}`);
-  const label = (stack: { name: string; size: number }) => `${stack.name} (${stack.size})`;
-  const on = summary.stacks.filter((stack) => stack.enabled).map(label).join(", ");
-  const off = summary.stacks.filter((stack) => !stack.enabled).map(label).join(", ");
-  const parts: string[] = [];
-  if (on) parts.push(on);
-  if (off) parts.push(`off: ${off}`);
-  parts.push(`${summary.activeCount}/${summary.totalCount} skills active`);
-  const section = new Text(`${heading("[Skills]")}\n${dim(`  ${parts.join(" · ")}`)}`, 0, 0);
-  ourSections.add(section);
-  return section;
-}
-
-export function replaceSkillsSection(component: RenderableNode, section: Text): boolean {
-  if (!hasChildren(component)) return false;
-
-  for (let index = 0; index < component.children.length; index += 1) {
-    const child = component.children[index]!;
-    if (isPiSection(child, "[Skills]")) {
-      component.children.splice(index, 1, section);
-      component.invalidate();
-      return true;
-    }
-    if (replaceSkillsSection(child, section)) return true;
-  }
-  return false;
-}
-
-function formatDirectory(cwd: string) {
-  const home = homedir();
-  if (cwd === home) return "~";
-  const rel = relative(home, cwd);
-  return rel.startsWith("..") || isAbsolute(rel) ? cwd : `~/${rel}`;
-}
-
-export default function skillStacksHeader(pi: ExtensionAPI) {
-  let cwd = process.cwd();
-  let activeTui: DashboardTui | undefined;
-  let sectionTheme: SectionTheme | undefined;
-  let banner: string[] = [];
-  let fixupTimers: Array<ReturnType<typeof setTimeout>> = [];
-  const interceptedContainers = new WeakSet<object>();
-
-  // One disk read per fixup cycle: the interceptor and every sweep in the
-  // cycle share the same section instead of re-scanning the skill roots.
-  let cachedSection: { cwd: string; section: Text | undefined } | undefined;
-  function skillsSection() {
-    if (!cachedSection || cachedSection.cwd !== cwd) {
-      cachedSection = { cwd, section: buildSkillsSection(cwd, sectionTheme) };
-    }
-    return cachedSection.section;
-  }
-
-  // Wrap addChild on every container reachable from the TUI root so pi's
-  // [Skills] section is swapped (and [Themes] dropped) at insertion time,
-  // before the first paint.
-  function interceptContainers(node: RenderableNode) {
-    if (hasChildren(node) && typeof node.addChild === "function" && !interceptedContainers.has(node)) {
-      interceptedContainers.add(node);
-      const original = node.addChild.bind(node);
-      let dropNextBlank = false;
-      node.addChild = (child: RenderableNode) => {
-        if (dropNextBlank) {
-          dropNextBlank = false;
-          // The spacer pi adds right after the section it belongs to.
-          if (!renderedText(child).trim()) return;
-        }
-        if (!isOurSection(child)) {
-          const firstLine = firstLineOf(child);
-          if (firstLine === "[Themes]") {
-            dropNextBlank = true;
-            return;
-          }
-          if (firstLine === "[Skills]") {
-            const section = skillsSection();
-            if (section) {
-              original(section);
-              return;
-            }
-          }
-        }
-        original(child);
-      };
-    }
-    if (hasChildren(node)) {
-      for (const child of node.children) interceptContainers(child);
-    }
-  }
-
-  // Fallback for sections that were inserted before we wrapped their
-  // container (e.g. this extension loading into an already-painted session).
-  function sweepHeader(tui: DashboardTui) {
-    let changed = hideThemesSection(tui);
-    const section = skillsSection();
-    if (section && replaceSkillsSection(tui, section)) changed = true;
-    if (changed) tui.requestRender(true);
-  }
-
-  function clearFixupTimers() {
-    for (const timer of fixupTimers) clearTimeout(timer);
-    fixupTimers = [];
-  }
-
-  function scheduleHeaderFixups(tui: DashboardTui) {
-    clearFixupTimers();
-    cachedSection = undefined;
-    interceptContainers(tui);
-    sweepHeader(tui);
-    for (const delay of [0, 50, 250, 1_000]) {
-      fixupTimers.push(setTimeout(() => sweepHeader(tui), delay));
-    }
-  }
-
-  pi.on("session_start", (_event, ctx) => {
-    cwd = ctx.cwd;
-    if (ctx.mode !== "tui") return;
-
-    ctx.ui.setHeader((tui, theme) => {
-      activeTui = tui;
-      sectionTheme = theme;
-      const label = theme.fg("muted", formatDirectory(cwd));
-      banner = [];
-      scheduleHeaderFixups(tui);
-
-      return {
-        render(width: number) {
-          // One dim centered line: the working directory.
-          if (banner.length === 0) {
-            const padding = Math.max(0, Math.floor((width - visibleWidth(label)) / 2));
-            banner = [truncateToWidth(`${" ".repeat(padding)}${label}`, width)];
-          }
-          return banner;
-        },
-        invalidate() {
-          banner = [];
-        },
-      };
-    });
-  });
-
-  pi.on("resources_discover", () => {
-    if (activeTui) scheduleHeaderFixups(activeTui);
-  });
-
-  pi.on("session_shutdown", (_event, ctx) => {
-    clearFixupTimers();
-    activeTui = undefined;
-    if (ctx.mode === "tui") ctx.ui.setHeader(undefined);
-  });
-}