@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/skill-registry/README.md

@@ -1,25 +1,62 @@
 # @pi-unipi/skill-registry
 
-**Placeholder package.** It ships no extension code — only skills — and exists so the
-bundled skill set keeps loading through the `@pi-unipi/unipi` umbrella manifest.
+Decides which skills the agent sees: per-project on/off, a vault of extra skills, and jev-judged exposure.
 
-The twenty skills that used to live in `@pi-unipi/workflow` moved here when that
-package was repurposed for **plan mode** and **permission modes**. They are plain
-`SKILL.md` instruction files; the slash commands that used to dispatch them
-(`/unipi:brainstorm`, `/unipi:work`, `/unipi:review-work`, `/unipi:auto`, …) were
-removed — plan mode (`/unipi:plan`, `Alt+P`) and ordinary prompting replace them. Every skill is still
-loadable by name via `/skill:<name>` or by reading its `SKILL.md`, and jev skill
-judging still sees them.
+## Commands
 
-## Roadmap
+| Command | Description |
+|---------|-------------|
+| `/unipi:skills` | Opens `/unipi:settings` on Skills (proxy, exposure, and the **Skill settings…** row) |
 
-This package becomes the real skill registry: discovery, install/update of third-party
-skill packs, and the metadata (capability tags, model hints) that jev skill judging and
-the `/unipi:settings` hub will consume. Until then it is a mount point, deliberately
-code-free.
+## Skill settings
 
-## Layout
+`/unipi:settings` → Skills → **Skill settings…** opens a grid of every skill pi loaded, like Fusion's preset editor:
 
 ```
-skills/<name>/SKILL.md   # one directory per skill
+Skill settings · 42 skills · editing global · proxy on
+    E   M    skill                source  description
+ › [x] [ ]   api-contract         user    Check REST/JSON API changes ...
+   [ ] [ ]   aws-deploy           vault   Deploy services to AWS with ...
+
+E enabled — the model sees it (judged first when exposure is on); off removes it and blocks /skill:name
+M must show — always listed, even when judging would hide it
+bright = set in global · dim = inherited
 ```
+
+| Key | Action |
+|-----|--------|
+| `↑` `↓` | Move between skills (PgUp/PgDn page) |
+| `←` `→` | Move between the E / M columns |
+| `space` | Toggle the cell |
+| `d` | Clear the cell in the edited scope (inherit again) |
+| `g` | Edit the global or the project scope |
+| `p` | Skill proxy on/off |
+| type | Filter by name, source or description (Esc clears) |
+| `enter` / `esc` | Save / cancel |
+
+Cells show the effective value: project over global over the default (vault skills off, everything else on). Only the cells you changed are written, each option on its own, so a project can override just one.
+
+## Skill proxy
+
+Off by default. While off, pi's skills pass through untouched (exposure judging still applies), vault skills stay hidden, and your choices are saved but not applied. Turn it on and:
+
+- Skills turned **off** are removed from the session, including `/skill:name`.
+- The **vault**, `~/.unipi/skill-vault/`, takes part. Keep as many skills there as you like; they stay off until a scope turns them on, so a project only gets the ones it needs. Changes apply on the next prompt, no reload needed. Any folder with a `SKILL.md`, up to three levels deep (`vault/<skill>/` or `vault/<pack>/<skill>/`).
+
+## Exposure
+
+Settings → Skills → Exposure:
+
+- **judged** (default) — when more skills are available than *Max skills listed* (12), the first real request of the session picks the listed set, and it stays fixed for the session so the system prompt never changes (prefix cache intact). Greetings don't count.
+  1. **Named skills are always kept.** A skill whose name appears in the request (`agent-browser`, "grill me") or a word only its name contains ("ssh into **coffee**" → `coffee-sandbox`) is listed without asking a model.
+  2. **jev scores the rest** against the request; those above the threshold are listed best first, up to *Max skills listed* in total.
+  3. **Hidden skills are still named.** The system prompt gets a short section listing every hidden skill by folder, so the agent knows it exists and can read its `SKILL.md`.
+  4. **Later requests** that name a hidden skill (or, with *recheck*, that jev finds it relevant to) get a message pointing at it. The system prompt itself never changes.
+- **all** — every skill is listed.
+- **off** — UniPi's bundled skills are removed from the list.
+
+jev uses the shared Decision Model (Settings → Skills → Decision model: inherit or custom). If jev is unavailable, every skill is listed.
+
+## License
+
+MIT

package/packages/skill-registry/index.ts

@@ -0,0 +1,230 @@
+/**
+ * @pi-unipi/skill-registry — Extension entry
+ *
+ * Per turn (before_agent_start), on pi's discovered skills:
+ *   1. registry (proxy on): drop skills turned off — removed from the session,
+ *      /skill:name included; the vault is mounted via resources_discover and
+ *      stays off until a scope turns a skill on.
+ *   2. exposure: off (bundled stripped) | all | judged (see src/judge.ts).
+ * Plus /unipi:skills (the hub opened on Skills), the "Skill settings…" overlay
+ * (per-skill Enabled / Must show, src/editor.ts), and the
+ * reveal event kanboard uses to surface a skill mid-session.
+ */
+
+import { existsSync } from "node:fs";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { emitEvent, getPackageVersion, harnessMetadata, HUB_OVERLAY_OPTIONS, MODULES, openSettingsHub, registerCommandRunner, setSettings, UNIPI_EVENTS } from "@pi-unipi/core";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { applyRegistry, isBundledSkillLocation, isUnderDir, skillCommandName, skillDir, skillSource, type CatalogSkill } from "./src/registry.js";
+import { readSkillsSettings, readStateLayers, writeStateLayers } from "./src/settings.js";
+import { SkillEditor, type EditorResult } from "./src/editor.js";
+import { listVaultSkills, vaultDir } from "./src/vault.js";
+import {
+  decideTurn,
+  emptyState,
+  HIDDEN_SECTION,
+  restoreState,
+  revealMessage,
+  SKILLS_JUDGED_ENTRY,
+  SKILLS_REVEALED_ENTRY,
+  toEntry,
+  type SessionSkillsState,
+} from "./src/judge.js";
+
+export { SKILLS_JUDGED_ENTRY, SKILLS_REVEALED_ENTRY } from "./src/judge.js";
+
+const VERSION = getPackageVersion(dirname(fileURLToPath(import.meta.url)));
+
+/** Event another module emits to reveal a skill by name (append-only). */
+export const SKILL_REVEAL_EVENT = "unipi:skills:reveal";
+
+export default function skillRegistry(pi: ExtensionAPI) {
+  let state: SessionSkillsState | null = null;
+  let lastCatalog: CatalogSkill[] = [];
+  let disabled = new Set<string>();
+
+  const sessionState = (ctx: ExtensionContext): SessionSkillsState => {
+    const id = ctx.sessionManager.getSessionId();
+    if (!state || state.sessionId !== id) state = emptyState(id);
+    return state;
+  };
+
+  /** Everything the manager can show: last catalog ∪ pi's skill commands ∪ vault. */
+  const allSkills = (): CatalogSkill[] => {
+    const byName = new Map<string, CatalogSkill>();
+    for (const s of lastCatalog) byName.set(s.name, s);
+    try {
+      for (const c of pi.getCommands()) {
+        if (c.source !== "skill") continue;
+        const name = c.name.replace(/^skill:/, "");
+        if (!byName.has(name)) byName.set(name, { name, description: c.description ?? "", filePath: c.sourceInfo?.path });
+      }
+    } catch {
+      // getCommands unavailable (tests) — catalog + vault only.
+    }
+    for (const v of listVaultSkills()) if (!byName.has(v.name)) byName.set(v.name, v);
+    return [...byName.values()];
+  };
+
+  const invalidateJudgement = () => {
+    if (state) state.judged = false;
+  };
+
+  /** "Skill settings…" — the per-skill E/M overlay. */
+  const openEditor = async (ctx: ExtensionContext) => {
+    if (!ctx.hasUI) return;
+    const cwd = ctx.cwd ?? process.cwd();
+    const vault = vaultDir();
+    const skills = allSkills()
+      .map((sk) => ({ name: sk.name, description: sk.description, source: skillSource(sk, cwd, vault) }))
+      .sort((a, b) => a.name.localeCompare(b.name));
+    const before = readStateLayers(cwd);
+    const settings = readSkillsSettings(cwd);
+    const hasProject = Object.keys(before.project).length > 0;
+    const result = await ctx.ui.custom<EditorResult>(
+      (tui, theme, _kb, done) =>
+        new SkillEditor({
+          skills,
+          layers: before,
+          proxy: settings.proxy,
+          initialScope: hasProject ? "project" : "global",
+          theme: { fg: (c, text) => theme.fg(c as never, text), bold: (text) => theme.bold(text) },
+          onDone: done,
+          onRenderRequest: () => tui.requestRender(),
+        }),
+      HUB_OVERLAY_OPTIONS,
+    );
+    if (result.type !== "saved") return;
+    const writes = writeStateLayers(cwd, before, result.layers);
+    if (result.proxy !== settings.proxy) setSettings("skills", { proxy: result.proxy }, "global", cwd);
+    if (writes > 0 || result.proxy !== settings.proxy) {
+      invalidateJudgement();
+      ctx.ui.notify(`Skill settings saved (${writes} change${writes === 1 ? "" : "s"}${result.proxy !== settings.proxy ? `, proxy ${result.proxy ? "on" : "off"}` : ""}) — applies from the next prompt`, "info");
+    }
+  };
+  registerCommandRunner("unipi:skills-editor", async (raw: unknown) => openEditor(raw as ExtensionContext));
+
+  pi.registerCommand("unipi:skills", {
+    description: "Skill settings — proxy, exposure, and per-skill Enabled / Must show (opens /unipi:settings on Skills)",
+    handler: async (_args, ctx) => {
+      await openSettingsHub(ctx, {
+        filter: "skills",
+        onChanged: (ns) => {
+          if (ns === "skills") invalidateJudgement();
+        },
+      });
+    },
+  });
+
+  // The vault is always mounted so toggles apply without /reload; while the
+  // proxy is off, vault skills are filtered out below (and /skill:name blocked).
+  pi.on("resources_discover", () => {
+    try {
+      const vault = vaultDir();
+      return existsSync(vault) ? { skillPaths: [vault] } : undefined;
+    } catch {
+      return undefined;
+    }
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    try {
+      state = restoreState(ctx.sessionManager.getSessionId(), ctx.sessionManager.getEntries());
+      emitEvent(pi, UNIPI_EVENTS.MODULE_READY, { name: MODULES.SKILL_REGISTRY, version: VERSION, commands: ["unipi:skills"], tools: [] });
+    } catch {
+      // never block startup
+    }
+  });
+
+  // A skill turned off is gone for the session — /skill:name included.
+  pi.on("input", (event, ctx) => {
+    try {
+      const name = skillCommandName(event.text ?? "");
+      if (!name || !disabled.has(name)) return undefined;
+      ctx.ui?.notify?.(`Skill "${name}" is turned off here. Turn it on in /unipi:skills.`, "warning");
+      return { action: "handled" as const };
+    } catch {
+      return undefined;
+    }
+  });
+
+  pi.events?.on?.(SKILL_REVEAL_EVENT, (payload: unknown) => {
+    try {
+      const data = payload as { names?: unknown } | undefined;
+      if (!Array.isArray(data?.names) || !state) return;
+      const names = data.names.map(String).filter((n) => !state!.revealed.has(n));
+      const entries = state.hidden.filter((h) => names.includes(h.name));
+      if (entries.length === 0) return;
+      for (const e of entries) state.revealed.add(e.name);
+      pi.appendEntry(SKILLS_REVEALED_ENTRY, { names: entries.map((e) => e.name) });
+      pi.sendMessage({ customType: "unipi-skills-revealed", content: revealMessage(entries), display: true, details: { unipiHarness: harnessMetadata({ source: "Skills", title: "Skill reveal", synopsis: `${String(entries.length)} relevant skill(s)` }, "direct") } }, { triggerTurn: false });
+    } catch {
+      // ignore
+    }
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    try {
+      const cwd = ctx.cwd ?? process.cwd();
+      const options = event.systemPromptOptions;
+      const catalog = (options.skills ?? []) as unknown as CatalogSkill[];
+      lastCatalog = catalog;
+      const settings = readSkillsSettings(cwd);
+
+      const vault = vaultDir();
+      let pool = catalog;
+      let mustShow = new Set<string>();
+      disabled = new Set();
+      if (settings.proxy) {
+        const result = applyRegistry(catalog, settings.states, cwd, vault);
+        pool = result.listed;
+        disabled = result.disabled;
+        mustShow = result.mustShow;
+      } else {
+        pool = catalog.filter((s) => {
+          const inVault = isUnderDir(skillDir(s), vault);
+          if (inVault) disabled.add(s.name);
+          return !inVault;
+        });
+      }
+
+      const setSkills = (list: CatalogSkill[]) => {
+        options.skills = list as unknown as typeof options.skills;
+      };
+      if (settings.exposure.mode !== "judged") {
+        setSkills(settings.exposure.mode === "off" ? pool.filter((s) => mustShow.has(s.name) || !isBundledSkillLocation(skillDir(s))) : pool);
+        delete options.sections[HIDDEN_SECTION];
+        return undefined;
+      }
+
+      const out = await decideTurn({
+        prompt: event.prompt,
+        catalog: pool.map(toEntry),
+        settings: settings.exposure,
+        cwd,
+        state: sessionState(ctx),
+        mustShow,
+      });
+      setSkills(pool.filter((s) => out.listed.has(s.name)));
+      if (out.index) options.sections[HIDDEN_SECTION] = out.index;
+      else delete options.sections[HIDDEN_SECTION];
+      if (out.freeze) pi.appendEntry(SKILLS_JUDGED_ENTRY, out.freeze);
+      if (out.status && ctx.hasUI) ctx.ui.setStatus("skills", out.status);
+      if (out.reveal.length > 0) {
+        pi.appendEntry(SKILLS_REVEALED_ENTRY, { names: out.reveal.map((r) => r.name) });
+        return {
+          message: {
+            customType: "unipi-skills-revealed",
+            content: revealMessage(out.reveal),
+            display: true,
+            details: { unipiHarness: harnessMetadata({ source: "Skills", title: "Skill reveal", synopsis: `${String(out.reveal.length)} relevant skill(s)` }, "before_agent_start") },
+          },
+        };
+      }
+      return undefined;
+    } catch {
+      return undefined; // never abort a turn
+    }
+  });
+}

package/packages/skill-registry/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/skill-registry",
-  "version": "3.0.0-alpha.2",
-  "description": "Placeholder for the upcoming unipi skill registry — hosts the bundled workflow skills",
+  "version": "3.0.0-alpha.21",
+  "description": "Skill registry for pi — per-project skill on/off, a skill vault, and jev-judged skill exposure",
   "type": "module",
   "license": "MIT",
   "author": "Neuron Mr White",
@@ -12,23 +12,34 @@
   },
   "keywords": [
     "pi-package",
-    "pi-skills",
     "unipi",
     "skill-registry"
   ],
   "files": [
-    "skills/**/*",
-    "README.md"
+    "index.ts",
+    "src/**/*.ts",
+    "README.md",
+    "!src/**/*.test.ts"
   ],
   "publishConfig": {
     "access": "public"
   },
   "pi": {
-    "extensions": [],
-    "skills": [
-      "./skills"
+    "extensions": [
+      "./index.ts"
     ],
     "prompts": [],
     "themes": []
+  },
+  "main": "index.ts",
+  "dependencies": {
+    "@pi-unipi/core": "3.0.0-alpha.21"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.87.1",
+    "@earendil-works/pi-tui": "^0.87.1"
+  },
+  "scripts": {
+    "test": "npx tsx --test tests/*.test.ts"
   }
 }

package/packages/skill-registry/src/editor.ts

@@ -0,0 +1,206 @@
+/**
+ * @pi-unipi/skill-registry — "Skill settings…" overlay (like Fusion's preset editor)
+ *
+ *   Skill settings · 47 skills · editing project · proxy on
+ *   Search: (type to filter)
+ *   ────────────────────────────────────────────────────────────
+ *        E   M    skill                 source
+ *   ›   [x] [ ]   sql-review            user     Review SQL migrations…
+ *       [ ] [ ]   aws-deploy            vault    Deploy services to AWS…
+ *
+ *   E enabled — the model sees it (judged first when exposure is on); off removes it and blocks /skill:name
+ *   M must show — always listed, even when judging would hide it
+ *   ↑↓ skill · ←→ column · space toggle · d inherit · g scope · p proxy · enter save · esc cancel · type to filter
+ *
+ * Each cell shows the EFFECTIVE value; a value set in the layer being edited
+ * is bright, an inherited one dim. Changes are held until Enter.
+ */
+
+import { Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { frameOverlay } from "@pi-unipi/core";
+import type { SkillSource } from "./registry.js";
+import type { SkillState } from "./settings.js";
+
+export type Column = "enabled" | "mustShow";
+export const COLUMNS: readonly Column[] = ["enabled", "mustShow"];
+const LETTER: Record<Column, string> = { enabled: "E", mustShow: "M" };
+
+export interface EditorSkill {
+  name: string;
+  description: string;
+  source: SkillSource;
+}
+
+export type Scope = "global" | "project";
+export type Layers = Record<Scope, Record<string, SkillState>>;
+
+export interface EditorResult {
+  type: "saved" | "cancelled";
+  /** The layers as edited (only meaningful when saved). */
+  layers: Layers;
+  proxy: boolean;
+}
+
+export interface EditorOptions {
+  skills: readonly EditorSkill[];
+  layers: Layers;
+  proxy: boolean;
+  initialScope: Scope;
+  theme: { fg: (color: string, text: string) => string; bold: (text: string) => string };
+  onDone: (result: EditorResult) => void;
+  onRenderRequest?: () => void;
+  visibleRows?: number;
+}
+
+function defaultFor(column: Column, source: SkillSource): boolean {
+  if (column === "enabled") return source !== "vault";
+  return false;
+}
+
+/** Effective value of one cell: project over global over the source default. */
+export function cellValue(layers: Layers, skill: EditorSkill, column: Column): { value: boolean; from: Scope | "default" } {
+  const p = layers.project[skill.name]?.[column];
+  if (typeof p === "boolean") return { value: p, from: "project" };
+  const g = layers.global[skill.name]?.[column];
+  if (typeof g === "boolean") return { value: g, from: "global" };
+  return { value: defaultFor(column, skill.source), from: "default" };
+}
+
+function printable(data: string): string | undefined {
+  if (data.length !== 1) return undefined;
+  const code = data.charCodeAt(0);
+  return code < 32 || code === 127 ? undefined : data;
+}
+
+export class SkillEditor {
+  private readonly opts: EditorOptions;
+  private readonly layers: Layers;
+  private proxy: boolean;
+  private scope: Scope;
+  private search = "";
+  private selected = 0;
+  private column = 0;
+  private done = false;
+
+  constructor(opts: EditorOptions) {
+    this.opts = opts;
+    this.layers = { global: structuredClone(opts.layers.global), project: structuredClone(opts.layers.project) };
+    this.proxy = opts.proxy;
+    this.scope = opts.initialScope;
+  }
+
+  private filtered(): EditorSkill[] {
+    const q = this.search.toLowerCase();
+    const list = q ? this.opts.skills.filter((s) => `${s.name} ${s.source} ${s.description}`.toLowerCase().includes(q)) : [...this.opts.skills];
+    return list;
+  }
+
+  handleInput(data: string): void {
+    if (this.done) return;
+    const list = this.filtered();
+    const cur = list[this.selected];
+    const col = COLUMNS[this.column]!;
+    if (matchesKey(data, Key.escape)) {
+      if (this.search) {
+        this.search = "";
+        this.selected = 0;
+      } else {
+        this.done = true;
+        this.opts.onDone({ type: "cancelled", layers: this.layers, proxy: this.proxy });
+        return;
+      }
+    } else if (matchesKey(data, Key.enter) || data === "\r") {
+      this.done = true;
+      this.opts.onDone({ type: "saved", layers: this.layers, proxy: this.proxy });
+      return;
+    } else if (matchesKey(data, Key.up)) this.selected = Math.max(0, this.selected - 1);
+    else if (matchesKey(data, Key.down)) this.selected = Math.min(Math.max(0, list.length - 1), this.selected + 1);
+    else if (matchesKey(data, Key.left) || matchesKey(data, "shift+tab")) this.column = (this.column + COLUMNS.length - 1) % COLUMNS.length;
+    else if (matchesKey(data, Key.right) || matchesKey(data, Key.tab)) this.column = (this.column + 1) % COLUMNS.length;
+    else if (matchesKey(data, Key.pageUp)) this.selected = Math.max(0, this.selected - this.window());
+    else if (matchesKey(data, Key.pageDown)) this.selected = Math.min(Math.max(0, list.length - 1), this.selected + this.window());
+    else if ((data === " " || matchesKey(data, Key.space)) && cur) {
+      const next = !cellValue(this.layers, cur, col).value;
+      const layer = this.layers[this.scope];
+      layer[cur.name] = { ...layer[cur.name], [col]: next };
+    } else if (!this.search && data === "d" && cur) {
+      const entry = this.layers[this.scope][cur.name];
+      if (entry) {
+        delete entry[col];
+        if (Object.keys(entry).length === 0) delete this.layers[this.scope][cur.name];
+      }
+    } else if (!this.search && data === "g") this.scope = this.scope === "global" ? "project" : "global";
+    else if (!this.search && data === "p") this.proxy = !this.proxy;
+    else if (matchesKey(data, Key.backspace) || data === "\x7f") {
+      this.search = this.search.slice(0, -1);
+      this.selected = 0;
+    } else {
+      const ch = printable(data);
+      if (ch === undefined || ch === " ") return;
+      this.search += ch;
+      this.selected = 0;
+    }
+    this.opts.onRenderRequest?.();
+  }
+
+  private window(): number {
+    return this.opts.visibleRows ?? Math.max(5, Math.min(18, (process.stdout.rows ?? 40) - 16));
+  }
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    return frameOverlay(this.body(Math.max(20, width - 2)), width, { title: "Skill settings" });
+  }
+
+  private body(width: number): string[] {
+    const t = this.opts.theme;
+    const list = this.filtered();
+    if (this.selected >= list.length) this.selected = Math.max(0, list.length - 1);
+    const fit = (s: string) => truncateToWidth(s, Math.max(1, width - 1));
+    const lines: string[] = [];
+    lines.push(fit(`${t.fg("accent", t.bold("Skill settings"))} ${t.fg("dim", `· ${list.length} skills · editing `)}${t.fg("accent", this.scope)}${t.fg("dim", " · proxy ")}${this.proxy ? t.fg("success", "on") : t.fg("warning", "off — saved but not applied (p)")}`));
+    lines.push(fit(`${t.fg("dim", "Search:")} ${this.search ? t.fg("text", this.search) : t.fg("dim", "(type to filter)")}`));
+    lines.push(t.fg("dim", "─".repeat(Math.max(1, width - 2))));
+
+    const nameW = Math.min(28, Math.max(10, ...list.map((s) => s.name.length)) + 1);
+    const head = COLUMNS.map((c, i) => (i === this.column ? t.fg("accent", t.bold(` ${LETTER[c]} `)) : t.fg("dim", ` ${LETTER[c]} `))).join(" ");
+    lines.push(fit(`   ${head}   ${t.fg("dim", "skill".padEnd(nameW))} ${t.fg("dim", "source ")} ${t.fg("dim", "description")}`));
+
+    const win = this.window();
+    const start = Math.max(0, Math.min(this.selected - Math.floor(win / 2), list.length - win));
+    const end = Math.min(list.length, start + win);
+    if (list.length === 0) lines.push(t.fg("warning", "  No skills match."));
+    if (start > 0) lines.push(t.fg("dim", `  ↑ ${start} more`));
+    for (let i = start; i < end; i++) {
+      const s = list[i]!;
+      const hl = i === this.selected;
+      const cells = COLUMNS.map((c, ci) => {
+        const { value, from } = cellValue(this.layers, s, c);
+        const glyph = value ? "[x]" : "[ ]";
+        if (hl && ci === this.column) return t.fg("accent", t.bold(glyph));
+        if (from === this.scope) return value ? t.fg("success", glyph) : t.fg("text", glyph);
+        return t.fg("dim", glyph);
+      }).join(" ");
+      const name = s.name.length > nameW - 1 ? `${s.name.slice(0, nameW - 2)}…` : s.name;
+      const label = hl ? t.fg("accent", name.padEnd(nameW)) : t.fg("text", name.padEnd(nameW));
+      const src = t.fg(s.source === "vault" ? "warning" : "dim", s.source.padEnd(7));
+      const desc = t.fg("dim", s.description.replace(/\s+/g, " "));
+      lines.push(fit(` ${hl ? t.fg("accent", "›") : " "} ${cells}   ${label} ${src} ${desc}`));
+    }
+    if (end < list.length) lines.push(t.fg("dim", `  ↓ ${list.length - end} more`));
+
+    lines.push("");
+    const legend: Array<[Column, string]> = [
+      ["enabled", "enabled — the model sees it (judged first when exposure is on); off removes it and blocks /skill:name"],
+      ["mustShow", "must show — always listed, even when judging would hide it"],
+    ];
+    for (const [c, text] of legend) {
+      const active = COLUMNS[this.column] === c;
+      lines.push(fit(`${active ? t.fg("accent", t.bold(LETTER[c])) : t.fg("dim", LETTER[c])} ${active ? t.fg("text", text) : t.fg("dim", text)}`));
+    }
+    lines.push(fit(t.fg("dim", `bright = set in ${this.scope} · dim = inherited`)));
+    lines.push(fit(t.fg("dim", "↑↓ skill · ←→ column · space toggle · d inherit · g scope · p proxy · enter save · esc cancel · type to filter")));
+    return lines.map((l) => (visibleWidth(l) > width ? truncateToWidth(l, width) : l));
+  }
+}