simple-skills-manager 1.0.1

package/menu.ts

@@ -0,0 +1,1292 @@
+/**
+ * The /skills-manager TUI: the library tree navigator (browse + exposure
+ * checkboxes), adding skills to the store (editor / .md import / directory
+ * import), adding roots (guided or adopting a native pi location), the
+ * scan-and-approve ceremony, enabling, refreshing, removal, and extension
+ * settings. Every mutating action validates through config.ts, saves
+ * through the atomic writer, and tells the caller to reload pi.
+ *
+ * Native pi roots are rendered honestly: pi exposes their skills through
+ * its own discovery whether the manager likes it or not, so their leaves
+ * are red and locked (mirrored for visibility) rather than toggleable,
+ * with the footer explaining how to revoke native exposure (remove the
+ * files, or launch pi with --no-skills).
+ *
+ * The core (registration and the scan cache) lives in index.ts; this
+ * module only manages the single config file and the store interactively.
+ */
+
+import { createHash } from "node:crypto";
+import { lstat, mkdir, readFile, rm } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder, getMarkdownTheme, getSettingsListTheme, type ThemeColor } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, matchesKey, type SettingItem, SettingsList, Text } from "@earendil-works/pi-tui";
+import {
+    CONFIG_FILE,
+    CONFIG_PATH,
+    DEFAULT_SETTINGS,
+    MAX_SKILL_NAME_CHARS,
+    SKILL_NAME_RE,
+    STORE_DIR,
+    computeExposedSkills,
+    expandUserPath,
+    findRoot,
+    findStoreRoot,
+    fingerprint,
+    isNativePath,
+    loadManagerConfig,
+    manifestSkills,
+    mutablePathWarning,
+    nativeDiscoveryWarning,
+    removeRootEntry,
+    resolvedRootPath,
+    saveManagerConfig,
+    scanSummary,
+    skillFilePath,
+    skillGroup,
+    upsertRoot,
+    validateRoot,
+    writeConfigText,
+    type ManagerConfig,
+    type ManagedRoot,
+    type RootConfig,
+    type SkillManifest,
+    type SkillSnapshot,
+} from "./config.ts";
+import { copyTreeInto, parseFrontmatter, renderDirTree, scanRoot, snapshotSkillFile } from "./scan.ts";
+import { bulletList, errText, sanitizeExternalText, stripJsonComments, writeFileAtomic } from "./util.ts";
+
+// ─── TUI helpers ────────────────────────────────────────────────────────────
+
+async function showMarkdown(title: string, content: string, ctx: ExtensionCommandContext): Promise<void> {
+    await ctx.ui.custom((_tui, theme, _keybindings, done) => {
+        const container = new Container();
+        container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+        container.addChild(new Text(theme.fg("accent", theme.bold(title)), 1, 0));
+        container.addChild(new Markdown(content, 1, 1, getMarkdownTheme()));
+        container.addChild(new Text(theme.fg("dim", "Enter or Esc to close"), 1, 0));
+        container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+        return {
+            render: (width: number) => container.render(width),
+            invalidate: () => container.invalidate(),
+            handleInput: (data: string) => {
+                if (matchesKey(data, "enter") || matchesKey(data, "escape")) done(undefined);
+            },
+        };
+    });
+}
+
+/** Surface a validation rejection as a markdown issue list. */
+async function showIssues(
+    ctx: ExtensionCommandContext,
+    title: string,
+    issues: string[],
+    note?: string,
+): Promise<void> {
+    await showMarkdown(title, `${bulletList(issues)}${note ? `\n\n${note}` : ""}`, ctx);
+}
+
+async function loadConfigForMenu(ctx: ExtensionCommandContext): Promise<ManagerConfig | undefined> {
+    try {
+        return await loadManagerConfig();
+    } catch (error) {
+        const reason = errText(error);
+        await showMarkdown(
+            "simple-skills-manager configuration error",
+            `The config file could not be loaded:\n\n\`\`\`text\n${sanitizeExternalText(reason)}\n\`\`\`\n\n` +
+            `Fix the file at \`${CONFIG_PATH}\` and retry. You can open it for editing from this menu ` +
+            `(**Extension settings → Edit the config file**).`,
+            ctx,
+        );
+        return undefined;
+    }
+}
+
+/** The set of skill instruction files pi's own native discovery is exposing
+ *  right now (live mirror detection). */
+function nativeActivePaths(ctx: ExtensionCommandContext): Set<string> {
+    const skills = ctx.getSystemPromptOptions()?.skills ?? [];
+    return new Set(skills.map((skill) => skill.filePath ?? ""));
+}
+
+function rootState(root: ManagedRoot): string {
+    if (root.issues.length) return "invalid";
+    return root.config.enabled ? "enabled" : "disabled";
+}
+
+/** Exposure labels resolve ${...} templates against cwd; a template that
+ *  cannot resolve yet simply shows zero exposed (it fails closed at scan). */
+function safeRootPath(root: ManagedRoot, workspace: string): string {
+    try {
+        return resolvedRootPath(root.config, workspace);
+    } catch {
+        return "";
+    }
+}
+
+/** skillFilePath that fails closed (undefined) when the root's path template
+ *  cannot be resolved — the tree must never crash on an unresolved root. */
+function safeSkillFilePath(root: ManagedRoot, snapshot: SkillSnapshot, ctx: ExtensionCommandContext): string | undefined {
+    try {
+        return skillFilePath(root.config, snapshot, ctx.cwd);
+    } catch {
+        return undefined;
+    }
+}
+
+/** The exposed skills of a root, failing closed to an empty list when its
+ *  path template cannot be resolved yet. */
+function safeExposedSkills(root: ManagedRoot, ctx: ExtensionCommandContext, nativeActive: Set<string>): SkillSnapshot[] {
+    try {
+        return computeExposedSkills(root.config, ctx.cwd, nativeActive);
+    } catch {
+        return [];
+    }
+}
+
+function rootLabel(root: ManagedRoot, ctx: ExtensionCommandContext, nativeActive: Set<string>): string {
+    const skills = manifestSkills(root.config);
+    // For native roots, "mirrored" is the honest state whenever pi is
+    // actively exposing from this location — "disabled" would suggest a
+    // control the manager does not have.
+    const state = root.config.native && nativeRootHasLive(root, ctx, nativeActive) ? "mirrored" : rootState(root);
+    const rootPath = safeRootPath(root, ctx.cwd);
+    const exposed = rootPath && root.normalized && !root.issues.length
+        ? safeExposedSkills(root, ctx, nativeActive).length
+        : 0;
+    const flags = [
+        root.config.store ? "store" : "",
+        root.config.native ? "native pi" : "",
+        root.config.transport === "single-skill" ? "single-skill" : "",
+        root.auto ? "auto-detected" : "",
+    ].filter(Boolean).join(", ");
+    return `${root.config.name} — ${state} · ${exposed}/${skills.length} skills${flags ? ` · ${flags}` : ""}`;
+}
+
+/** True when pi's live native exposure includes anything under this root's path. */
+function nativeRootHasLive(root: ManagedRoot, ctx: ExtensionCommandContext, nativeActive: Set<string>): boolean {
+    const rootPath = safeRootPath(root, ctx.cwd);
+    if (!rootPath) return false;
+    for (const filePath of nativeActive) {
+        if (filePath.startsWith(`${rootPath}/`)) return true;
+    }
+    return false;
+}
+
+async function pickRoot(ctx: ExtensionCommandContext, config: ManagerConfig, title: string, filter?: (root: ManagedRoot) => boolean): Promise<ManagedRoot | undefined> {
+    const roots = filter ? config.roots.filter(filter) : config.roots;
+    if (!roots.length) {
+        ctx.ui.notify("No matching library roots are configured — add one first", "warning");
+        return undefined;
+    }
+    const nativeActive = nativeActivePaths(ctx);
+    const labels = roots.map((root) => rootLabel(root, ctx, nativeActive));
+    const selected = await ctx.ui.select(title, labels);
+    const index = selected ? labels.indexOf(selected) : -1;
+    return index >= 0 ? roots[index] : undefined;
+}
+
+function rootDetails(root: ManagedRoot, ctx: ExtensionCommandContext): string {
+    const config = root.config;
+    const skills = manifestSkills(config);
+    const scannedAt = typeof config.manifest?.scannedAt === "string" ? config.manifest.scannedAt : "unknown";
+    const lines = [
+        `**State:** ${config.enabled ? "enabled" : "disabled"}${root.auto ? " · auto-detected" : ""}${root.issues.length ? " (with issues)" : ""}`,
+        `**Transport:** ${config.transport}`,
+        `**Path:** \`${config.path}\``,
+        `**Store root:** ${config.store ? "yes — skills added via /skills-manager accumulate here" : "no"}`,
+        `**Native pi location:** ${config.native ? "yes — pi exposes skills here itself; the manager mirrors (red, locked), it cannot revoke" : "no"}`,
+        `**Loading:** lazy; the directory is not scanned until an approved skill is invoked`,
+        `**Approved manifest:** ${config.manifest ? `${skills.length} skills from ${scannedAt}` : "none"}`,
+        `**Exposed by the manager:** ${safeExposedSkills(root, ctx, nativeActivePaths(ctx)).map((skill) => skill.name).join(", ") || "none"}`,
+    ];
+    if (config.native) {
+        const rootPath = safeRootPath(root, ctx.cwd);
+        const liveCount = rootPath
+            ? [...nativeActivePaths(ctx)].filter((filePath) => filePath.startsWith(`${rootPath}/`)).length
+            : 0;
+        lines.push(`**Exposed by pi itself (right now):** ${liveCount} skill(s)${liveCount ? " — outside the manager's control while native discovery is active" : " (native discovery is off or found nothing)"}`);
+    }
+    lines.push(`**Definitions and manifests live in:** \`${CONFIG_PATH}\``);
+    if (root.issues.length) lines.push("", "### Issues", ...root.issues.map((issue) => `- ${issue}`));
+    return lines.filter(Boolean).join("\n");
+}
+
+// ─── The library tree navigator ────────────────────────────────────────────
+
+type LeafKind = "normal" | "mirror" | "unscanned" | "rejected" | "issues";
+
+type Leaf = {
+    kind: LeafKind;
+    root: ManagedRoot;
+    label: string;
+    snapshot?: SkillSnapshot;
+    reason?: string;
+    checked: boolean;
+};
+
+type Row = {
+    id: string;
+    depth: 0 | 1 | 2;
+    type: "root" | "group" | "leaf";
+    label: string;
+    leaf?: Leaf;
+};
+
+type TreeState = {
+    folded: Set<string>;
+    selected: number;
+    /** root name → skill name → checked; toggles not yet applied to the config. */
+    changed: Map<string, Map<string, boolean>>;
+    flash: string | undefined;
+};
+
+type TreeAction = { kind: "exit" } | { kind: "inspect"; row: Row };
+
+/** Build the flat tree rows: roots sit flat at the top level; groups (the
+ *  first path segment under a root) nest skills beneath them. Exported for
+ *  the smoke test. */
+export function buildTreeRows(config: ManagerConfig, ctx: ExtensionCommandContext, nativeActive: Set<string>): Row[] {
+    const rows: Row[] = [];
+    config.roots.forEach((root, rootIndex) => {
+        rows.push({ id: `r:${rootIndex}`, depth: 0, type: "root", label: rootLabel(root, ctx, nativeActive) });
+        if (root.issues.length && !manifestSkills(root.config).length) {
+            rows.push({
+                id: `l:${rootIndex}:issues`, depth: 1, type: "leaf",
+                label: `${root.issues.length} issue(s) — press Enter to view`,
+                leaf: { kind: "issues", root, label: "issues", checked: false, reason: bulletList(root.issues) },
+            });
+            // Native roots keep going: their unscanned skills show as red
+            // unapproved-but-live leaves — visibility is the whole point.
+            if (!root.config.native) return;
+        }
+        const rootPath = safeRootPath(root, ctx.cwd);
+        const leaves: { group: string; leaf: Leaf }[] = [];
+        for (const snapshot of manifestSkills(root.config)) {
+            const skillPath = safeSkillFilePath(root, snapshot, ctx);
+            const mirrored = root.config.native && skillPath !== undefined && nativeActive.has(skillPath);
+            leaves.push({
+                group: skillGroup(snapshot.dirPath),
+                leaf: {
+                    kind: mirrored ? "mirror" : "normal",
+                    root,
+                    label: snapshot.name,
+                    snapshot,
+                    checked: mirrored
+                        || (root.config.enabled && (root.config.skills.mode === "all" || root.config.skills.include.includes(snapshot.name))),
+                },
+            });
+        }
+        for (const rejected of root.config.manifest?.rejected ?? []) {
+            leaves.push({
+                group: skillGroup(rejected.dirPath),
+                leaf: {
+                    kind: "rejected",
+                    root,
+                    label: rejected.dirPath === "." ? "(root-level file)" : rejected.dirPath,
+                    checked: false,
+                    reason: rejected.reason,
+                },
+            });
+        }
+        if (root.config.native && rootPath) {
+            // Skills pi is natively exposing from this root that are not in
+            // the approved manifest — visibility is the whole point of mirroring.
+            const known = new Set(
+                manifestSkills(root.config)
+                    .map((snapshot) => safeSkillFilePath(root, snapshot, ctx))
+                    .filter((path): path is string => path !== undefined),
+            );
+            const rejectedDirs = (root.config.manifest?.rejected ?? [])
+                .filter((rejected) => rejected.dirPath !== ".")
+                .map((rejected) => resolve(rootPath, rejected.dirPath));
+            for (const filePath of nativeActive) {
+                if (!filePath.startsWith(`${rootPath}/`) || known.has(filePath) || !filePath.toLowerCase().endsWith(".md")) continue;
+                const parent = resolve(dirname(filePath));
+                if (rejectedDirs.some((dir) => parent === dir || parent.startsWith(`${dir}/`))) continue;
+                leaves.push({
+                    group: skillGroup(relative(rootPath, filePath)),
+                    leaf: {
+                        kind: "unscanned",
+                        root,
+                        label: relative(rootPath, filePath),
+                        checked: false,
+                        reason: "pi is exposing this skill natively, but it is not in the approved manifest — use Scan or refresh to adopt it",
+                    },
+                });
+            }
+        }
+        // Emit group rows + leaf rows; "ungrouped" first, then alphabetical.
+        const groups = [...new Set(leaves.map((entry) => entry.group))].sort((a, b) =>
+            a === "ungrouped" ? -1 : b === "ungrouped" ? 1 : a.localeCompare(b));
+        for (const group of groups) {
+            rows.push({ id: `g:${rootIndex}:${group}`, depth: 1, type: "group", label: group });
+            for (const entry of leaves.filter((item) => item.group === group)) {
+                rows.push({
+                    id: `l:${rootIndex}:${entry.group}:${entry.leaf.label}`,
+                    depth: 2,
+                    type: "leaf",
+                    label: entry.leaf.label,
+                    leaf: entry.leaf,
+                });
+            }
+        }
+    });
+    return rows;
+}
+
+function visibleRows(rows: Row[], folded: Set<string>): Row[] {
+    const visible: Row[] = [];
+    let insideFoldedRoot = false;
+    let insideFoldedGroup = false;
+    for (const row of rows) {
+        if (row.type === "root") {
+            insideFoldedRoot = folded.has(row.id);
+            insideFoldedGroup = false;
+            visible.push(row);
+            continue;
+        }
+        if (insideFoldedRoot) continue;
+        if (row.type === "group") {
+            insideFoldedGroup = folded.has(row.id);
+            visible.push(row);
+            continue;
+        }
+        if (insideFoldedGroup) continue;
+        visible.push(row);
+    }
+    return visible;
+}
+
+export type { Row, Leaf };
+export { visibleRows };
+
+type TreeTheme = { fg: (color: ThemeColor, text: string) => string; inverse: (text: string) => string; bold: (text: string) => string };
+
+function renderRow(row: Row, selected: boolean, theme: TreeTheme): string {
+    const indent = " ".repeat(row.depth * 2);
+    let text: string;
+    if (row.type === "root") {
+        text = `${indent}${theme.bold(row.label)}`;
+    } else if (row.type === "group") {
+        text = `${indent}${theme.fg("accent", row.label)}`;
+    } else {
+        const leaf = row.leaf!;
+        const description = leaf.snapshot ? ` — ${leaf.snapshot.description.replace(/\s+/g, " ").slice(0, 100)}` : "";
+        const hiddenNote = leaf.snapshot?.hidden ? theme.fg("muted", " ⌁ hidden from model") : "";
+        if (leaf.kind === "mirror") {
+            text = `${indent}${theme.fg("error", `[⊘] ${leaf.label}`)}${description}${theme.fg("error", " — native pi: exposed by pi's own discovery (cannot be revoked here)")}${hiddenNote}`;
+        } else if (leaf.kind === "unscanned") {
+            text = `${indent}${theme.fg("error", `[⊘] ${leaf.label}`)} ${theme.fg("error", leaf.reason ?? "")}`;
+        } else if (leaf.kind === "rejected") {
+            text = `${indent}${theme.fg("warning", `[!] ${leaf.label}`)} ${theme.fg("warning", leaf.reason ?? "")}`;
+        } else if (leaf.kind === "issues") {
+            text = `${indent}${theme.fg("warning", `[!] ${row.label}`)}`;
+        } else {
+            const body = `${indent}${leaf.checked ? "[√]" : "[ ]"} ${leaf.label}${description}${hiddenNote}`;
+            text = leaf.checked ? body : theme.fg("dim", body);
+        }
+    }
+    return selected ? theme.inverse(text) : text;
+}
+
+function treeFooter(config: ManagerConfig, nativeActive: Set<string>, flash: string | undefined, theme: TreeTheme): string[] {
+    if (flash) return [theme.fg("warning", flash)];
+    const nativeRoots = config.roots.filter((root) => root.config.native);
+    const lines = ["↑/↓ move · space toggle exposure / fold · enter inspect / fold · esc save & close"];
+    if (nativeRoots.length) {
+        lines.push(nativeActive.size > 0
+            ? theme.fg("error", "red ⊘ leaves: pi exposes these natively; revoke by removing the files or launching pi with --no-skills (library-only mode)")
+            : "native discovery: OFF (library-only mode) — native-root skills are fully gated here");
+    }
+    return lines;
+}
+
+/** One round of the tree dialog. Renders fresh on every frame (a new
+ *  Container per render call), so folds, toggles, and the selection bar
+ *  update live. Returns the next action for the loop. */
+async function runTreeDialog(
+    ctx: ExtensionCommandContext,
+    config: ManagerConfig,
+    nativeActive: Set<string>,
+    state: TreeState,
+): Promise<TreeAction> {
+    const rows = buildTreeRows(config, ctx, nativeActive);
+    let visible = visibleRows(rows, state.folded);
+    let selected = Math.min(state.selected, Math.max(0, visible.length - 1));
+    state.flash = undefined;
+
+    return await ctx.ui.custom((_tui, theme, _keybindings, done) => {
+        return {
+            render: (width: number) => {
+                const container = new Container();
+                container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+                container.addChild(new Text(theme.fg("accent", theme.bold("Skills library")), 1, 0));
+                visible.forEach((row, index) => container.addChild(new Text(renderRow(row, index === selected, theme), 0, 0)));
+                container.addChild(new Text("", 0, 0));
+                for (const line of treeFooter(config, nativeActive, state.flash, theme)) {
+                    container.addChild(new Text(line, 1, 0));
+                }
+                container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+                return container.render(width);
+            },
+            invalidate: () => undefined,
+            handleInput: (data: string) => {
+                if (matchesKey(data, "up")) {
+                    selected = Math.max(0, selected - 1);
+                    return;
+                }
+                if (matchesKey(data, "down")) {
+                    selected = Math.min(visible.length - 1, selected + 1);
+                    return;
+                }
+                if (matchesKey(data, "space")) {
+                    const row = visible[selected];
+                    if (row?.type === "root" || row?.type === "group") {
+                        if (state.folded.has(row.id)) state.folded.delete(row.id);
+                        else state.folded.add(row.id);
+                        visible = visibleRows(rows, state.folded);
+                        selected = Math.min(selected, Math.max(0, visible.length - 1));
+                        return;
+                    }
+                    if (row?.type === "leaf") {
+                        const leaf = row.leaf!;
+                        if (leaf.kind === "mirror") {
+                            state.flash = "Locked: pi exposes this skill natively — remove the file or launch pi with --no-skills to revoke.";
+                        } else if (leaf.kind === "unscanned") {
+                            state.flash = "Not in the approved manifest — use Scan or refresh to adopt it.";
+                        } else if (leaf.kind === "rejected") {
+                            state.flash = "This skill failed the scan — press Enter for the reason.";
+                        } else if (leaf.kind === "normal") {
+                            let perRoot = state.changed.get(leaf.root.config.name);
+                            if (!perRoot) state.changed.set(leaf.root.config.name, perRoot = new Map());
+                            const current = perRoot.get(leaf.label) ?? leaf.checked;
+                            perRoot.set(leaf.label, !current);
+                        }
+                    }
+                    return;
+                }
+                if (matchesKey(data, "enter")) {
+                    state.selected = selected;
+                    const row = visible[selected];
+                    if (row) done({ kind: "inspect", row });
+                    return;
+                }
+                if (matchesKey(data, "escape")) {
+                    state.selected = selected;
+                    done({ kind: "exit" });
+                    return;
+                }
+            },
+        };
+    });
+}
+
+/** Apply toggled exposure to the config; returns true when anything changed. */
+function applyTreeChanges(config: ManagerConfig, changed: Map<string, Map<string, boolean>>): boolean {
+    let dirty = false;
+    for (const [rootName, perRoot] of changed) {
+        const root = findRoot(config, rootName);
+        if (!root || !root.normalized) continue;
+        const current = new Set(root.config.skills.mode === "all" ? manifestSkills(root.config).map((skill) => skill.name) : root.config.skills.include);
+        const finalChecked = new Set<string>();
+        for (const skill of manifestSkills(root.config)) {
+            const toggled = perRoot.get(skill.name);
+            if (toggled === true) finalChecked.add(skill.name);
+            else if (toggled === false) finalChecked.delete(skill.name);
+            else if (root.config.enabled && current.has(skill.name)) finalChecked.add(skill.name);
+        }
+        if (root.config.enabled && finalChecked.size === current.size && [...finalChecked].every((name) => current.has(name))) continue;
+        if (!root.config.enabled && finalChecked.size === 0) continue;
+        if (!root.config.manifest && finalChecked.size > 0) continue; // enabling requires a manifest
+        dirty = true;
+        // Checking any skill enables the root; unchecking every skill disables
+        // it (an enabled root with an empty selection registers nothing).
+        upsertRoot(config, {
+            ...root.config,
+            enabled: finalChecked.size > 0,
+            skills: { mode: "selected", include: [...finalChecked] },
+        });
+    }
+    return dirty;
+}
+
+/** The full tree interaction loop: browse, toggle, inspect, save on exit. */
+async function libraryTree(ctx: ExtensionCommandContext, config: ManagerConfig): Promise<boolean> {
+    const state: TreeState = { folded: new Set(), selected: 0, changed: new Map(), flash: undefined };
+    while (true) {
+        const action = await runTreeDialog(ctx, config, nativeActivePaths(ctx), state);
+        if (action.kind === "exit") {
+            if (!state.changed.size) return false;
+            const dirty = applyTreeChanges(config, state.changed);
+            if (!dirty) return false;
+            if (!await ctx.ui.confirm("Apply exposure changes?", "Toggled skills are written to the config; pi reloads to re-register them.")) return false;
+            await saveManagerConfig(config);
+            ctx.ui.notify("Exposure updated; reloading", "info");
+            return true;
+        }
+        const row = action.row;
+        if (row.type === "root") {
+            const root = config.roots[Number(row.id.slice(2))]!;
+            await showMarkdown(root.config.name, rootDetails(root, ctx), ctx);
+            if (await rootActions(ctx, config, root)) return true; // a save + reload already happened
+        } else if (row.type === "group") {
+            // Enter folds a group, same as space would.
+            if (state.folded.has(row.id)) state.folded.delete(row.id);
+            else state.folded.add(row.id);
+        } else if (row.type === "leaf") {
+            if (await inspectLeaf(ctx, config, row.leaf!)) return true; // a save + reload already happened
+        }
+    }
+}
+
+/** Enter on a leaf: details, view, edit (store only), remove (store only).
+ *  Returns true when the config changed and pi should reload. */
+async function inspectLeaf(ctx: ExtensionCommandContext, config: ManagerConfig, leaf: Leaf): Promise<boolean> {
+    const root = leaf.root;
+    if (leaf.kind === "issues" || leaf.kind === "rejected" || leaf.kind === "unscanned") {
+        await showMarkdown(leaf.kind === "issues" ? `${root.config.name} — issues` : leaf.label, leaf.reason ?? "", ctx);
+        return false;
+    }
+    const snapshot = leaf.snapshot!;
+    const rootPath = safeRootPath(root, ctx.cwd);
+    if (!rootPath) {
+        ctx.ui.notify(`The path of ${root.config.name} cannot be resolved (an environment variable it references is not set)`, "error");
+        return false;
+    }
+    const path = skillFilePath(root.config, snapshot, ctx.cwd);
+    const skillDir = join(rootPath, snapshot.dirPath === "." ? "" : snapshot.dirPath);
+    const lines = [
+        `**Name:** ${snapshot.name}`,
+        `**Description:** ${snapshot.description}`,
+        `**Group:** ${skillGroup(snapshot.dirPath)}`,
+        `**Root:** ${root.config.name}${root.config.store ? " (store)" : ""}${root.config.native ? " (native pi)" : ""}`,
+        `**Directory:** \`${skillDir}\``,
+        `**Content hash:** \`${snapshot.contentHash.slice(0, 16)}…\``,
+        `**Files:** ${snapshot.fileCount}`,
+        `**Executable scripts:** ${snapshot.executableScripts.join(", ") || "none"}${snapshot.executableScripts.length ? " — the model may be instructed to run these" : ""}`,
+        `**Hidden from model:** ${snapshot.hidden ? "yes (invocable via skill:<name> only)" : "no"}`,
+        `**Exposure:** ${leaf.kind === "mirror" ? "mirrored — pi exposes this natively" : leaf.checked ? "exposed" : "not exposed"}`,
+    ];
+    // Live drift state: hash the bytes on disk against the approval (bounded:
+    // a swollen file is reported, not loaded into memory).
+    let drift: string;
+    try {
+        const info = await lstat(path);
+        if (info.size > config.settings.maxSkillBytes) {
+            drift = `⚠ the file now exceeds settings.maxSkillBytes (${config.settings.maxSkillBytes} bytes) — refresh this root before it can be invoked`;
+        } else {
+            const bytes = await readFile(path);
+            drift = createHash("sha256").update(bytes).digest("hex") === snapshot.contentHash
+                ? "approved content matches the file on disk"
+                : "⚠ content changed since approval — refresh this root before it can be invoked";
+        }
+    } catch (error) {
+        drift = `⚠ the file can no longer be read: ${errText(error)}`;
+    }
+    lines.push(`**Live check:** ${drift}`);
+    await showMarkdown(snapshot.name, lines.join("\n"), ctx);
+
+    const actions = ["View the full skill file"];
+    if (root.config.store) actions.push("Edit the skill file", "Remove this skill");
+    actions.push("Back");
+    const choice = await ctx.ui.select(`${snapshot.name} — actions`, actions);
+    if (!choice || choice === "Back") return false;
+    if (choice === "View the full skill file") {
+        try {
+            const info = await lstat(path);
+            if (info.size > config.settings.maxSkillBytes) throw new Error(`over ${config.settings.maxSkillBytes} bytes`);
+            const content = sanitizeExternalText(await readFile(path, "utf8"));
+            await showMarkdown(`${snapshot.name} — skill file`, `\`\`\`markdown\n${content.slice(0, 60_000)}${content.length > 60_000 ? "\n… (truncated for display)" : ""}\n\`\`\``, ctx);
+        } catch (error) {
+            ctx.ui.notify(`Could not read the skill file: ${errText(error)}`, "error");
+        }
+        return false;
+    }
+    if (choice === "Edit the skill file") return await editStoreSkill(ctx, config, root, snapshot);
+    if (choice === "Remove this skill") return await removeStoreSkill(ctx, config, root, snapshot);
+    return false;
+}
+
+/** Edit a store skill in the TUI editor. Saving through the manager is an
+ *  approval act: the snapshot is refreshed so the skill does not fail as
+ *  drifted after its own edit. */
+async function editStoreSkill(ctx: ExtensionCommandContext, config: ManagerConfig, root: ManagedRoot, snapshot: SkillSnapshot): Promise<boolean> {
+    const path = skillFilePath(root.config, snapshot, ctx.cwd);
+    let current: string;
+    try {
+        current = await readFile(path, "utf8");
+    } catch (error) {
+        ctx.ui.notify(`Could not read ${path}: ${errText(error)}`, "error");
+        return false;
+    }
+    const edited = await ctx.ui.editor(`${path} (frontmatter name/description required)`, current);
+    if (edited === undefined || edited === current) return false;
+    await writeFileAtomic(path, edited);
+    let refreshed: SkillSnapshot;
+    try {
+        // Preserve the instruction file name: a root-level .md store skill
+        // must not silently fall back to SKILL.md after its own edit.
+        refreshed = await snapshotSkillFile(path, snapshot.dirPath, config.settings, snapshot.file ?? "SKILL.md");
+    } catch (error) {
+        ctx.ui.notify(`Saved, but the skill is now invalid: ${errText(error)}. Fix the frontmatter and re-save.`, "error");
+        return false;
+    }
+    const manifest = root.config.manifest!;
+    const skills = manifestSkills(root.config).filter((skill) => skill.name !== snapshot.name && skill.name !== refreshed.name);
+    skills.push(refreshed);
+    const wasExposed = root.config.skills.mode === "all" || root.config.skills.include.includes(snapshot.name);
+    const include = [...new Set([
+        ...root.config.skills.include.filter((name) => name !== snapshot.name && name !== refreshed.name),
+        ...(wasExposed ? [refreshed.name] : []),
+    ])];
+    upsertRoot(config, {
+        ...root.config,
+        skills: { mode: root.config.skills.mode, include: root.config.skills.mode === "all" ? [] : include },
+        manifest: { ...manifest, skills },
+    });
+    await saveManagerConfig(config);
+    ctx.ui.notify(`Saved ${refreshed.name}; reloading`, "info");
+    return true;
+}
+
+/** Delete a store skill: its directory, or — for a root-level .md skill,
+ *  whose "directory" is the store itself — just the instruction file.
+ *  Refuses anything outside the store either way. */
+async function removeStoreSkill(ctx: ExtensionCommandContext, config: ManagerConfig, root: ManagedRoot, snapshot: SkillSnapshot): Promise<boolean> {
+    const rootPath = safeRootPath(root, ctx.cwd);
+    const storePath = resolve(STORE_DIR);
+    const skillDir = resolve(join(rootPath || storePath, snapshot.dirPath === "." ? "" : snapshot.dirPath));
+    const fileOnly = skillDir === storePath; // a root-level .md skill: its file is the skill
+    const target = fileOnly ? resolve(skillFilePath(root.config, snapshot, ctx.cwd)) : skillDir;
+    if (!target.startsWith(`${storePath}/`)) {
+        ctx.ui.notify("Refusing to delete anything outside the store directory", "error");
+        return false;
+    }
+    if (!await ctx.ui.confirm(
+        `Remove ${snapshot.name}?`,
+        `Delete \`${target}\` and remove it from the approved manifest? The skill stops being exposed after reload.`,
+    )) return false;
+    await rm(target, { recursive: true, force: true }).catch((error) =>
+        ctx.ui.notify(`Removed from the manifest, but the deletion failed: ${errText(error)}`, "warning"));
+    const manifest = root.config.manifest!;
+    upsertRoot(config, {
+        ...root.config,
+        skills: {
+            mode: root.config.skills.mode,
+            include: root.config.skills.include.filter((name) => name !== snapshot.name),
+        },
+        manifest: {
+            ...manifest,
+            skills: manifestSkills(root.config).filter((skill) => skill.name !== snapshot.name),
+        },
+    });
+    await saveManagerConfig(config);
+    ctx.ui.notify(`Removed ${snapshot.name}; reloading`, "info");
+    return true;
+}
+
+// ─── Adding skills to the store ────────────────────────────────────────────
+
+/** Shared tail of every add-skill method: snapshot the written skill into
+ *  the store root's manifest, offer exposure, save, reload. */
+async function finalizeStoreSkill(
+    ctx: ExtensionCommandContext,
+    config: ManagerConfig,
+    skillFile: string,
+    dirPath: string,
+): Promise<boolean> {
+    const store = findStoreRoot(config);
+    if (!store) {
+        ctx.ui.notify("The registrar has no store root; add one first", "error");
+        return false;
+    }
+    const snapshot = await snapshotSkillFile(skillFile, dirPath, config.settings);
+    const skills = manifestSkills(store.config).filter((skill) => skill.name !== snapshot.name);
+    skills.push(snapshot);
+    const expose = await ctx.ui.confirm(
+        `Add ${snapshot.name} to the library?`,
+        `The skill is written into the store and snapshotted into the approved manifest. Expose it to the model now (it loads lazily on first use)?`,
+    );
+    if (!expose) {
+        ctx.ui.notify(`The file remains at ${dirname(skillFile)} but is not in the library; Scan or refresh the store root to adopt it`, "warning");
+        return false;
+    }
+    upsertRoot(config, {
+        ...store.config,
+        enabled: true,
+        skills: { mode: "selected", include: [...new Set([...store.config.skills.include, snapshot.name])] },
+        manifest: {
+            version: 1,
+            fingerprint: fingerprint(store.config),
+            scannedAt: new Date().toISOString(),
+            skills,
+        },
+    });
+    await saveManagerConfig(config);
+    ctx.ui.notify(`Saved ${snapshot.name} to the store; reloading`, "info");
+    return true;
+}
+
+async function promptSkillIdentity(ctx: ExtensionCommandContext, fallbackName?: string, fallbackDescription?: string): Promise<{ name: string; description: string } | undefined> {
+    const name = (await ctx.ui.input("Skill name (lowercase letters, numbers, hyphens)", fallbackName ?? "my-skill"))?.trim();
+    if (!name) return undefined;
+    if (!SKILL_NAME_RE.test(name) || name.length > MAX_SKILL_NAME_CHARS) {
+        ctx.ui.notify(`Skill names are 1-${MAX_SKILL_NAME_CHARS} lowercase letters, numbers, or single hyphens`, "error");
+        return undefined;
+    }
+    const description = (await ctx.ui.input("What does this skill do and when should it be used?", fallbackDescription ?? ""))?.trim();
+    if (!description) return undefined;
+    return { name, description };
+}
+
+/** A single path segment for a group (subdirectory of the store). */
+async function promptGroup(ctx: ExtensionCommandContext): Promise<string | undefined> {
+    const group = (await ctx.ui.input("Group (optional — a subdirectory of the store; skills in it display as a group)", ""))?.trim();
+    if (!group) return "";
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(group) || group.length > 64) {
+        ctx.ui.notify("A group name is a single path segment (letters, numbers, dots, underscores, hyphens)", "error");
+        return undefined;
+    }
+    return group;
+}
+
+async function addSkillToStore(ctx: ExtensionCommandContext, config: ManagerConfig): Promise<boolean> {
+    if (!findStoreRoot(config)) {
+        ctx.ui.notify("The registrar has no store root; restore it in the config file first", "error");
+        return false;
+    }
+    await mkdir(STORE_DIR, { recursive: true }).catch(() => undefined);
+    const method = await ctx.ui.select("Add a skill to the store", [
+        "Write a new SKILL.md in the editor",
+        "Import an .md file (copied into the store)",
+        "Import a directory (copied wholesale)",
+        "Cancel",
+    ]);
+    if (!method || method === "Cancel") return false;
+    const group = await promptGroup(ctx);
+    if (group === undefined) return false;
+
+    if (method === "Write a new SKILL.md in the editor") {
+        const identity = await promptSkillIdentity(ctx);
+        if (!identity) return false;
+        const scaffold =
+            `---\nname: ${identity.name}\ndescription: ${identity.description.replace(/\n/g, " ")}\n---\n\n` +
+            `# ${identity.name}\n\n${identity.description}\n\n## Usage\n\n` +
+            `(Write the instructions the model should follow. Reference helper scripts and reference\nfiles with relative paths from the skill directory.)\n`;
+        const edited = await ctx.ui.editor("New SKILL.md (frontmatter is prewritten)", scaffold);
+        if (edited === undefined) return false;
+        const parsed = parseFrontmatter(edited);
+        const finalIdentity = parsed.data
+            ? {
+                name: SKILL_NAME_RE.test(parsed.data["name"] ?? "") ? parsed.data["name"]! : identity.name,
+                description: (parsed.data["description"] ?? identity.description).trim() || identity.description,
+            }
+            : identity;
+        const dirPath = group ? `${group}/${finalIdentity.name}` : finalIdentity.name;
+        const destination = join(STORE_DIR, dirPath, "SKILL.md");
+        if (await lstat(destination).catch(() => undefined)) {
+            ctx.ui.notify(`A skill already exists at ${destination}`, "error");
+            return false;
+        }
+        await mkdir(join(STORE_DIR, dirPath), { recursive: true });
+        await writeFileAtomic(destination, edited);
+        return await finalizeStoreSkill(ctx, config, destination, dirPath);
+    }
+
+    if (method === "Import an .md file (copied into the store)") {
+        const input = await ctx.ui.input("Path to the .md file", "~/Downloads/my-skill.md");
+        if (!input) return false;
+        const source = expandUserPath(input, ctx.cwd);
+        const info = await lstat(source).catch(() => undefined);
+        if (!info?.isFile() || info.isSymbolicLink()) {
+            ctx.ui.notify("The import must be a regular file", "error");
+            return false;
+        }
+        if (info.size > config.settings.maxSkillBytes) {
+            ctx.ui.notify(`The file exceeds settings.maxSkillBytes (${config.settings.maxSkillBytes} bytes)`, "error");
+            return false;
+        }
+        const text = await readFile(source, "utf8");
+        const parsed = parseFrontmatter(text);
+        const identity = parsed.data?.["name"] && parsed.data?.["description"]
+            ? { name: parsed.data["name"], description: parsed.data["description"] }
+            : await promptSkillIdentity(ctx, parsed.data?.["name"], parsed.data?.["description"]);
+        if (!identity) return false;
+        const finalText = parsed.data
+            ? text
+            : `---\nname: ${identity.name}\ndescription: ${identity.description.replace(/\n/g, " ")}\n---\n\n${text}`;
+        const dirPath = group ? `${group}/${identity.name}` : identity.name;
+        const destination = join(STORE_DIR, dirPath, "SKILL.md");
+        if (await lstat(destination).catch(() => undefined)) {
+            ctx.ui.notify(`A skill already exists at ${destination}`, "error");
+            return false;
+        }
+        await mkdir(join(STORE_DIR, dirPath), { recursive: true });
+        await writeFileAtomic(destination, finalText);
+        ctx.ui.notify(`Copied ${source} into the store (the original is untouched)`, "info");
+        return await finalizeStoreSkill(ctx, config, destination, dirPath);
+    }
+
+    // Directory import: wholesale copy; find the SKILL.md if it is not at the root.
+    const input = await ctx.ui.input("Path to the skill directory", "~/Downloads/their-skill");
+    if (!input) return false;
+    const source = expandUserPath(input, ctx.cwd);
+    const info = await lstat(source).catch(() => undefined);
+    if (!info?.isDirectory() || info.isSymbolicLink()) {
+        ctx.ui.notify("The import must be a regular directory", "error");
+        return false;
+    }
+    let skillDir = source;
+    if (!await lstat(join(source, "SKILL.md")).catch(() => undefined)) {
+        const tree = await renderDirTree(source, 4);
+        let chosen: string | undefined;
+        while (!chosen) {
+            await showMarkdown(
+                `${source} — no SKILL.md at the root`,
+                `This directory has no SKILL.md at its root. Its tree (all depths up to 4):\n\n\`\`\`text\n${tree}\n\`\`\`\n\nWhich one is the skill's SKILL.md? Type its full path.`,
+                ctx,
+            );
+            const answer = await ctx.ui.input("Full path of the SKILL.md", join(source, "…"));
+            if (!answer) return false;
+            const candidate = expandUserPath(answer, source);
+            const rel = relative(source, candidate);
+            if (!rel || rel.startsWith("..") || !candidate.toLowerCase().endsWith(".md")
+                || !(await lstat(candidate).catch(() => undefined))?.isFile()) {
+                ctx.ui.notify("That is not an .md file inside the printed tree — try again, or leave empty to cancel", "error");
+                continue;
+            }
+            chosen = candidate;
+        }
+        skillDir = dirname(chosen) || source;
+    }
+    const skillMdPath = join(skillDir, "SKILL.md");
+    const skillMdInfo = await lstat(skillMdPath).catch(() => undefined);
+    if (!skillMdInfo?.isFile() || skillMdInfo.isSymbolicLink()) {
+        ctx.ui.notify(`The chosen SKILL.md must be a regular file: ${skillMdPath}`, "error");
+        return false;
+    }
+    if (skillMdInfo.size > config.settings.maxSkillBytes) {
+        ctx.ui.notify(`The file exceeds settings.maxSkillBytes (${config.settings.maxSkillBytes} bytes)`, "error");
+        return false;
+    }
+    const parsed = parseFrontmatter((await readFile(skillMdPath)).toString("utf8"));
+    const identity = parsed.data?.["name"] && parsed.data?.["description"]
+        ? { name: parsed.data["name"], description: parsed.data["description"] }
+        : await promptSkillIdentity(ctx, parsed.data?.["name"], parsed.data?.["description"]);
+    if (!identity) return false;
+    const dirPath = group ? `${group}/${identity.name}` : identity.name;
+    const destination = join(STORE_DIR, dirPath);
+    if (await lstat(destination).catch(() => undefined)) {
+        ctx.ui.notify(`A skill already exists at ${destination}`, "error");
+        return false;
+    }
+    // Copy the skill's own directory (the one holding the chosen SKILL.md),
+    // not the whole import source — when the SKILL.md is nested, copying
+    // the source would leave the copy without a root-level SKILL.md.
+    const result = await copyTreeInto(skillDir, destination, config.settings);
+    if (result.skipped.length) {
+        ctx.ui.notify(`Copied ${result.copied} file(s); skipped: ${result.skipped.join(", ").slice(0, 200)}`, "warning");
+    } else {
+        ctx.ui.notify(`Copied ${result.copied} file(s) into the store (the original is untouched)`, "info");
+    }
+    return await finalizeStoreSkill(ctx, config, join(destination, "SKILL.md"), dirPath);
+}
+
+// ─── Adding roots and the scan ceremony ────────────────────────────────────
+
+/** The scan ceremony: explicit confirmation, scan, inspection. Returns
+ *  the scan outcome; exposure and enabling are decided by the caller. */
+async function scanWithCeremony(
+    ctx: ExtensionCommandContext,
+    config: ManagerConfig,
+    rootConfig: RootConfig,
+    action: string,
+): Promise<Awaited<ReturnType<typeof scanRoot>> | undefined> {
+    const issues = validateRoot(rootConfig, config.settings);
+    if (issues.length) {
+        await showIssues(ctx, "Library root rejected", issues);
+        return undefined;
+    }
+    let summary: string;
+    try {
+        summary = scanSummary(rootConfig, ctx.cwd);
+    } catch (error) {
+        ctx.ui.notify(errText(error), "error");
+        return undefined;
+    }
+    const warnings = [mutablePathWarning(rootConfig.path), nativeDiscoveryWarning(rootConfig.path)].filter(Boolean);
+    const nativeNote = rootConfig.native
+        ? "\n\nNote: this is a native pi location — while pi's native discovery is active, found skills are exposed by pi itself regardless; the manager mirrors them (red, locked in the tree)."
+        : "";
+    const approved = await ctx.ui.confirm(
+        action,
+        `${summary}${warnings.length ? `\n\n${warnings.join("\n\n")}` : ""}\n\nSkills are untrusted instructions the model may follow, and their scripts may be executed with your permissions. Scanning only reads the directory.${nativeNote}`,
+    );
+    if (!approved) return undefined;
+    ctx.ui.notify(`Scanning ${rootConfig.name}...`, "info");
+    let outcome;
+    try {
+        outcome = await scanRoot(rootConfig, ctx.cwd, config.settings);
+    } catch (error) {
+        await showMarkdown("Skill scan failed", `\`\`\`text\n${sanitizeExternalText(errText(error)).slice(0, 16_000)}\n\`\`\``, ctx);
+        return undefined;
+    }
+    await showMarkdown("Skill scan result", [
+        `Discovered **${outcome.skills.length}** skill(s); **${outcome.rejected.length}** rejected; **${outcome.issues.length}** warning(s).`,
+        "",
+        ...outcome.skills.map((skill) => {
+            const scripts = skill.executableScripts.length ? `\n  - ⚠ executable scripts: ${skill.executableScripts.join(", ")}` : "";
+            const hidden = skill.hidden ? " · hidden from model" : "";
+            return `- **${skill.name}** (${skillGroup(skill.dirPath)}) — ${skill.description.replace(/\s+/g, " ").slice(0, 300)} · ${skill.fileCount} file(s)${hidden}${scripts}`;
+        }),
+        ...(outcome.rejected.length ? ["", "### Rejected", ...outcome.rejected.map((rejected) => `- ⚠ \`${rejected.dirPath}\` — ${rejected.reason}`)] : []),
+        ...(outcome.issues.length ? ["", "### Warnings", ...outcome.issues.map((issue) => `- ${issue}`)] : []),
+    ].join("\n"), ctx);
+    if (!outcome.skills.length) {
+        ctx.ui.notify("No valid skills were found in this root", "warning");
+        return undefined;
+    }
+    return outcome;
+}
+
+async function addRoot(ctx: ExtensionCommandContext, config: ManagerConfig): Promise<boolean> {
+    const method = await ctx.ui.select("Add a library root to the registrar", [
+        "Guided skills directory (a folder of skill folders)",
+        "Guided single skill (one directory with a SKILL.md)",
+        "Cancel",
+    ]);
+    if (!method || method === "Cancel") return false;
+    const name = (await ctx.ui.input("Library root name (lowercase-name)", "my-skills"))?.trim();
+    if (!name) return false;
+    const path = (await ctx.ui.input("Path to the directory", "~/.claude/skills"))?.trim();
+    if (!path) return false;
+    const transport = method === "Guided single skill (one directory with a SKILL.md)" ? "single-skill" : "skills-dir";
+    const native = isNativePath(path);
+    const base: RootConfig = {
+        name, enabled: false, transport, path,
+        native: native ? true : undefined,
+        connection: "lazy",
+        skills: { mode: "selected", include: [] },
+    };
+    if (native) {
+        ctx.ui.notify("Recognized as a native pi location — exposure will be mirrored, not gated", "info");
+    } else {
+        const warning = nativeDiscoveryWarning(path);
+        if (warning) ctx.ui.notify(warning, "warning");
+    }
+    if (findRoot(config, name)) {
+        ctx.ui.notify(`A library root named ${name} already exists; refresh or remove it instead`, "error");
+        return false;
+    }
+    const outcome = await scanWithCeremony(ctx, config, base, `Scan ${path} for skills?`);
+    if (!outcome) return false;
+    const selection = await chooseExposure(ctx, { version: 1, fingerprint: "", scannedAt: outcome.scannedAt, skills: outcome.skills });
+    if (!selection) return false;
+    upsertRoot(config, {
+        ...base,
+        enabled: true,
+        skills: selection,
+        manifest: {
+            version: 1,
+            fingerprint: fingerprint(base),
+            scannedAt: outcome.scannedAt,
+            skills: outcome.skills,
+            rejected: outcome.rejected.length ? outcome.rejected : undefined,
+        },
+    });
+    await saveManagerConfig(config);
+    ctx.ui.notify(`Saved root ${name}; reloading`, "info");
+    return true;
+}
+
+/** Ask which of a freshly approved manifest's skills are exposed. */
+async function chooseExposure(ctx: ExtensionCommandContext, manifest: SkillManifest, initial: Set<string> = new Set()): Promise<{ mode: "all" | "selected"; include: string[] } | undefined> {
+    if (!manifest.skills.length) return { mode: "selected", include: [] };
+    const choice = await ctx.ui.select("Skill exposure", [
+        "Choose individual skills (recommended)",
+        `Expose all ${manifest.skills.length} skills`,
+        "Keep all skills disabled",
+        "Cancel",
+    ]);
+    if (!choice || choice === "Cancel") return undefined;
+    if (choice.startsWith("Expose all")) return { mode: "all", include: [] };
+    if (choice === "Keep all skills disabled") return { mode: "selected", include: [] };
+    const enabled = new Set(initial);
+    await ctx.ui.custom((_tui, theme, _keybindings, done) => {
+        const container = new Container();
+        container.addChild(new Text(theme.fg("accent", theme.bold("Choose skills to expose")), 1, 1));
+        const items: SettingItem[] = manifest.skills.map((skill) => ({
+            id: skill.name,
+            label: `${skill.name} (${skillGroup(skill.dirPath)})`,
+            currentValue: enabled.has(skill.name) ? "on" : "off",
+            values: ["off", "on"],
+        }));
+        const list = new SettingsList(
+            items,
+            Math.min(items.length + 2, 18),
+            getSettingsListTheme(),
+            (id, value) => {
+                if (value === "on") enabled.add(id);
+                else enabled.delete(id);
+            },
+            () => done(undefined),
+            { enableSearch: true },
+        );
+        container.addChild(list);
+        container.addChild(new Text(theme.fg("dim", "Toggle with Enter/Space; Esc closes and saves the selection"), 1, 0));
+        return {
+            render: (width: number) => container.render(width),
+            invalidate: () => container.invalidate(),
+            handleInput: (data: string) => list.handleInput?.(data),
+        };
+    });
+    return { mode: "selected", include: manifest.skills.map((skill) => skill.name).filter((name) => enabled.has(name)) };
+}
+
+/** Enable or disable one root (bulk pause/resume that preserves the
+ *  per-skill selection). Reached from the root's detail view. */
+async function toggleRootEntry(ctx: ExtensionCommandContext, config: ManagerConfig, root: ManagedRoot): Promise<boolean> {
+    if (root.issues.length) {
+        ctx.ui.notify(`Fix the issues for ${root.config.name} first (see the tree)`, "error");
+        return false;
+    }
+    const enabled = !root.config.enabled;
+    if (enabled && !root.config.manifest) {
+        ctx.ui.notify("Scan the root and approve a skill manifest before enabling it", "error");
+        return false;
+    }
+    if (!await ctx.ui.confirm(
+        `${enabled ? "Enable" : "Disable"} ${root.config.name}`,
+        root.config.native && enabled
+            ? "Native roots mirror pi's own exposure while native discovery is active; the selection applies in library-only mode (--no-skills)."
+            : enabled
+                ? "Its selected skills will be registered after reload; the directory is still scanned lazily."
+                : "Its skills will no longer be registered after reload.",
+    )) return false;
+    upsertRoot(config, { ...root.config, enabled });
+    await saveManagerConfig(config);
+    ctx.ui.notify(`${enabled ? "Enabled" : "Disabled"} ${root.config.name}; reloading`, "info");
+    return true;
+}
+
+/** Scan or refresh one root: the approval ceremony, then exposure choice.
+ *  For auto-detected native roots this is the adoption path. */
+async function refreshRootEntry(ctx: ExtensionCommandContext, config: ManagerConfig, root: ManagedRoot): Promise<boolean> {
+    const outcome = await scanWithCeremony(ctx, config, root.config, `Re-scan ${root.config.name}?`);
+    if (!outcome) return false;
+    // Drop selected skills that no longer exist; never silently keep names
+    // absent from the freshly approved manifest.
+    const available = new Set(outcome.skills.map((skill) => skill.name));
+    const initial = new Set(root.config.skills.mode === "all"
+        ? outcome.skills.map((skill) => skill.name)
+        : root.config.skills.include.filter((name) => available.has(name)));
+    const selection = await chooseExposure(ctx, { version: 1, fingerprint: "", scannedAt: outcome.scannedAt, skills: outcome.skills }, initial);
+    if (!selection) return false;
+    // A disabled root that just got skills selected is offered the toggle.
+    let enabled = root.config.enabled;
+    if (!enabled && (selection.mode === "all" || selection.include.length)) {
+        enabled = await ctx.ui.confirm(
+            `Enable ${root.config.name} now?`,
+            "Its selected skills will be registered after reload; the directory is still scanned lazily.",
+        );
+    }
+    upsertRoot(config, {
+        ...root.config,
+        enabled,
+        skills: selection,
+        manifest: {
+            version: 1,
+            fingerprint: fingerprint(root.config),
+            scannedAt: outcome.scannedAt,
+            skills: outcome.skills,
+            rejected: outcome.rejected.length ? outcome.rejected : undefined,
+        },
+    });
+    await saveManagerConfig(config);
+    ctx.ui.notify(`Refreshed ${root.config.name}; reloading`, "info");
+    return true;
+}
+
+/** Remove one root's entry (unregister only; files are never touched). */
+async function removeRootEntryFlow(ctx: ExtensionCommandContext, config: ManagerConfig, root: ManagedRoot): Promise<boolean> {
+    if (root.config.store) {
+        ctx.ui.notify("The store root is built in; remove its skills individually instead", "error");
+        return false;
+    }
+    if (root.auto) {
+        ctx.ui.notify(
+            "This root was auto-detected as a native pi location — pi exposes its skills regardless, so the library shows it for visibility. Scan or refresh it to adopt it properly.",
+            "warning",
+        );
+        return false;
+    }
+    if (!await ctx.ui.confirm(
+        `Remove ${root.config.name}?`,
+        `Delete its definition and approved manifest from ${CONFIG_PATH}? The directory on disk is never touched.`,
+    )) return false;
+    removeRootEntry(config, root.config.name);
+    await saveManagerConfig(config);
+    ctx.ui.notify(`Removed ${root.config.name}; reloading`, "info");
+    return true;
+}
+
+/** Enter on a root row: overview plus the root's actions. Returns true when
+ *  the config changed and pi should reload. */
+async function rootActions(ctx: ExtensionCommandContext, config: ManagerConfig, root: ManagedRoot): Promise<boolean> {
+    const actions = [];
+    if (root.config.enabled || root.config.manifest) actions.push(`${root.config.enabled ? "Disable" : "Enable"} this root (keeps the skill selection)`);
+    actions.push("Scan or refresh this root");
+    if (!root.config.store && !root.auto) actions.push("Remove this root");
+    actions.push("Back");
+    const choice = await ctx.ui.select(`${root.config.name} — actions`, actions);
+    if (!choice || choice === "Back") return false;
+    if (choice.startsWith("Scan or refresh")) return await refreshRootEntry(ctx, config, root);
+    if (choice.startsWith("Remove this root")) return await removeRootEntryFlow(ctx, config, root);
+    if (choice.startsWith("Disable") || choice.startsWith("Enable")) return await toggleRootEntry(ctx, config, root);
+    return false;
+}
+
+async function refreshRoot(ctx: ExtensionCommandContext, config: ManagerConfig): Promise<boolean> {
+    const root = await pickRoot(ctx, config, "Scan or refresh a library root");
+    if (!root) return false;
+    return await refreshRootEntry(ctx, config, root);
+}
+
+async function removeRootOrSkill(ctx: ExtensionCommandContext, config: ManagerConfig): Promise<boolean> {
+    const kind = await ctx.ui.select("Remove…", ["A skill from the store", "A library root", "Cancel"]);
+    if (!kind || kind === "Cancel") return false;
+    if (kind === "A library root") {
+        const root = await pickRoot(ctx, config, "Remove which library root?", (item) => !item.config.store && !item.auto);
+        if (!root) return false;
+        return await removeRootEntryFlow(ctx, config, root);
+    }
+    const root = await pickRoot(ctx, config, "Remove a skill from which root?", (item) => Boolean(item.config.store && item.normalized));
+    if (!root) return false;
+    const skills = manifestSkills(root.config);
+    if (!skills.length) {
+        ctx.ui.notify("This root has no approved skills", "warning");
+        return false;
+    }
+    const labels = skills.map((skill) => `${skill.name} (${skillGroup(skill.dirPath)})`);
+    const selected = await ctx.ui.select("Remove which skill?", labels);
+    const index = selected ? labels.indexOf(selected) : -1;
+    if (index < 0) return false;
+    return await removeStoreSkill(ctx, config, root, skills[index]!);
+}
+
+// ─── Extension settings ─────────────────────────────────────────────────────
+
+async function extensionSettings(ctx: ExtensionCommandContext, config: ManagerConfig): Promise<boolean> {
+    while (true) {
+        const action = await ctx.ui.select("Extension settings", [
+            "View current settings",
+            "Edit the config file",
+            "Reset settings to defaults",
+            "Back",
+        ]);
+        if (!action || action === "Back") return false;
+        if (action === "View current settings") {
+            const lines = [
+                `**Config file:** \`${CONFIG_PATH}\``,
+                `**Skill store:** \`${STORE_DIR}\``,
+                `**Library roots:** ${config.roots.length}`,
+                "",
+                "### Settings",
+                `**maxResultBytes:** ${config.settings.maxResultBytes} (default ${DEFAULT_SETTINGS.maxResultBytes})`,
+                `**maxResultLines:** ${config.settings.maxResultLines} (default ${DEFAULT_SETTINGS.maxResultLines})`,
+                `**maxSkills:** ${config.settings.maxSkills} (default ${DEFAULT_SETTINGS.maxSkills})`,
+                `**toolNameLimit:** ${config.settings.toolNameLimit} (default ${DEFAULT_SETTINGS.toolNameLimit})`,
+                `**maxSkillBytes:** ${config.settings.maxSkillBytes} (default ${DEFAULT_SETTINGS.maxSkillBytes})`,
+                `**maxScanFiles:** ${config.settings.maxScanFiles} (default ${DEFAULT_SETTINGS.maxScanFiles})`,
+            ];
+            if (config.settingsIssues.length) {
+                lines.push("", "### Settings issues", ...config.settingsIssues.map((issue) => `- ${issue}`));
+            }
+            await showMarkdown("simple-skills-manager settings", lines.join("\n"), ctx);
+        } else if (action === "Edit the config file") {
+            let text: string;
+            try {
+                text = await readFile(CONFIG_PATH, "utf8");
+            } catch (error) {
+                ctx.ui.notify(`Could not read ${CONFIG_PATH}: ${errText(error)}`, "error");
+                continue;
+            }
+            const edited = await ctx.ui.editor(`${CONFIG_FILE} (JSONC comments allowed; saving strips them)`, text);
+            if (edited === undefined || edited === text) continue;
+            try {
+                // Validate before writing: refuse to persist an unparseable file.
+                JSON.parse(stripJsonComments(edited));
+            } catch (error) {
+                ctx.ui.notify(`Not saved — invalid JSON: ${errText(error)}`, "error");
+                continue;
+            }
+            try {
+                await writeConfigText(edited);
+            } catch (error) {
+                ctx.ui.notify(`Not saved: ${errText(error)}`, "error");
+                continue;
+            }
+            try {
+                await loadManagerConfig();
+            } catch (error) {
+                ctx.ui.notify(`Saved, but the config has issues: ${errText(error)}`, "warning");
+                return true;
+            }
+            ctx.ui.notify("Config saved; reloading to apply", "info");
+            return true;
+        } else if (action === "Reset settings to defaults") {
+            if (!await ctx.ui.confirm(
+                "Reset settings to defaults?",
+                "All six tunables return to their built-in defaults. Library roots and manifests are kept.",
+            )) continue;
+            config.settings = { ...DEFAULT_SETTINGS };
+            config.settingsIssues = [];
+            await saveManagerConfig(config);
+            ctx.ui.notify("Settings reset; reloading to apply", "info");
+            return true;
+        }
+    }
+}
+
+// ─── Menu loop ─────────────────────────────────────────────────────────────
+
+/** The /skills-manager command loop. Re-loads the config from disk every
+ *  iteration so hand edits and other processes are picked up between
+ *  actions; returns after any action that changed the config file (the
+ *  caller reloads pi to re-register skills). */
+export async function runSkillsManagerMenu(ctx: ExtensionCommandContext): Promise<void> {
+    while (true) {
+        const config = await loadConfigForMenu(ctx);
+        if (!config) return;
+        if (config.created) {
+            ctx.ui.notify(`Created a starter config at ${CONFIG_PATH}`, "info");
+        }
+        const action = await ctx.ui.select("Skills library", [
+            "Open the library tree (browse and toggle exposure)",
+            "Add a skill to the store",
+            "Add or import a library root",
+            "Scan or refresh a root",
+            "Remove a skill or a root",
+            "Extension settings",
+            "Close",
+        ]);
+        if (!action || action === "Close") return;
+        try {
+            let changed = false;
+            if (action === "Open the library tree (browse and toggle exposure)") changed = await libraryTree(ctx, config);
+            else if (action === "Add a skill to the store") changed = await addSkillToStore(ctx, config);
+            else if (action === "Add or import a library root") changed = await addRoot(ctx, config);
+            else if (action === "Scan or refresh a root") changed = await refreshRoot(ctx, config);
+            else if (action === "Remove a skill or a root") changed = await removeRootOrSkill(ctx, config);
+            else if (action === "Extension settings") changed = await extensionSettings(ctx, config);
+            if (changed) {
+                await ctx.reload();
+                return;
+            }
+        } catch (error) {
+            ctx.ui.notify(errText(error), "error");
+        }
+    }
+}