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

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

@@ -0,0 +1,289 @@
+/**
+ * @pi-unipi/skill-registry — skill exposure judging
+ *
+ * mode "judged": on the session's first REAL prompt (greetings don't count),
+ * if more skills are available than `maxSkills`, pick the listed set and
+ * freeze it for the session — the rendered system prompt then stays
+ * byte-identical every turn (prefix cache intact).
+ *
+ * Picking:
+ *   1. Pins — a skill whose name, or a distinctive word of it, appears in the
+ *      prompt is always kept. No model needed ("ssh into coffee" → coffee-sandbox).
+ *   2. jev scores every remaining skill against the prompt; ≥ threshold stay,
+ *      best first, at most maxSkills in total.
+ *   3. Everything else is hidden — but NAMED in a static "other installed
+ *      skills" section with where each lives, so the model knows it exists.
+ * Later prompts: pinned or (with recheck) jev-relevant hidden skills are
+ * announced in a message; the system prompt never changes after the freeze.
+ */
+
+import { basename, dirname } from "node:path";
+import { homedir } from "node:os";
+import { askJev, isChatter, resolveDecisionModel, type JevAnswer } from "@pi-unipi/core";
+import { skillDir, type CatalogSkill } from "./registry.js";
+import type { ExposureSettings } from "./settings.js";
+
+/** Session-persisted entry types (pi.appendEntry custom entries). */
+export const SKILLS_JUDGED_ENTRY = "unipi:skills-judged";
+export const SKILLS_REVEALED_ENTRY = "unipi:skills-revealed";
+/** System-prompt section naming the hidden skills. */
+export const HIDDEN_SECTION = "unipi-skills-hidden";
+/** At most this many skills announced per later prompt. */
+export const REVEAL_CAP = 5;
+
+export interface Entry {
+  name: string;
+  description: string;
+  location: string;
+}
+
+export function toEntry(s: CatalogSkill): Entry {
+  return { name: s.name, description: s.description, location: skillDir(s) };
+}
+
+// ─── pins ─────────────────────────────────────────────────────────────────
+
+/** Words too common to identify a skill on their own. */
+const COMMON = new Set([
+  "work", "create", "list", "show", "find", "help", "test", "tests", "mode", "auto", "quick", "review",
+  "execute", "gather", "context", "scan", "issues", "full", "output", "write", "writing", "agent",
+  "agents", "user", "with", "your", "from", "this", "that", "into", "gain", "debt", "teach", "plan",
+  "check", "tool", "tools", "file", "files", "code", "docs", "task", "tasks", "make", "build",
+]);
+
+function words(text: string): Set<string> {
+  return new Set(text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean));
+}
+
+export function nameTokens(name: string): string[] {
+  return name.toLowerCase().split(/[-_\s]+/).filter((t) => t.length >= 4);
+}
+
+/**
+ * Skills the prompt names: the whole name ("coffee-sandbox" / "coffee
+ * sandbox"), or a distinctive name word — ≥4 letters, in exactly one skill
+ * name, not a common word ("coffee" → coffee-sandbox, "kanboard").
+ */
+export function pinnedSkills(entries: readonly Entry[], prompt: string): Set<string> {
+  // pi's image attachments render as "[Image #1]" placeholders in the prompt;
+  // they must not read as mentions of a skill named "image".
+  const clean = prompt.replace(/\[Image #\d+\]/gi, " ");
+  const lower = ` ${clean.toLowerCase().replace(/\s+/g, " ")} `;
+  const promptWords = words(clean);
+  const freq = new Map<string, number>();
+  for (const e of entries) for (const t of new Set(nameTokens(e.name))) freq.set(t, (freq.get(t) ?? 0) + 1);
+  const pins = new Set<string>();
+  for (const e of entries) {
+    const n = e.name.toLowerCase();
+    if (lower.includes(`/skill:${n}`)) {
+      pins.add(e.name);
+      continue;
+    }
+    // A one-word name that is also a common word ("work", "plan") is not a
+    // mention; hyphenated names and uncommon single words are.
+    const nameable = n.includes("-") || !COMMON.has(n);
+    const escaped = n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (nameable && (lower.includes(` ${n.replace(/-/g, " ")} `) || new RegExp(`[^a-z0-9-]${escaped}[^a-z0-9-]`).test(lower))) {
+      pins.add(e.name);
+      continue;
+    }
+    if (nameTokens(e.name).some((t) => !COMMON.has(t) && freq.get(t) === 1 && promptWords.has(t))) pins.add(e.name);
+  }
+  return pins;
+}
+
+// ─── jev ──────────────────────────────────────────────────────────────────
+
+export function judgeRequest(
+  entries: readonly Entry[],
+  prompt: string,
+  cwdBase: string,
+): { state: string; questions: Record<string, { type: "noul"; instructions: string }> } {
+  const state = `${prompt.slice(0, 4000)}\n[project: ${cwdBase}]`;
+  const questions: Record<string, { type: "noul"; instructions: string }> = {};
+  entries.forEach((entry, i) => {
+    questions[`s${i}`] = {
+      type: "noul",
+      instructions: `Would the skill "${entry.name}" help handle this request? Skill: ${entry.description.slice(0, 300)}`,
+    };
+  });
+  return { state, questions };
+}
+
+/**
+ * Pins always stay; others need ≥ threshold, best first, total capped at
+ * maxSkills (pins may exceed it — they were asked for by name). Kept set
+ * returned in catalog order.
+ */
+export function applyJudgement(
+  entries: readonly Entry[],
+  answers: Record<string, JevAnswer> | null,
+  settings: Pick<ExposureSettings, "threshold" | "maxSkills">,
+  pins: ReadonlySet<string> = new Set(),
+): { kept: Entry[]; hidden: Entry[] } {
+  const scored = entries.map((entry, i) => ({
+    entry,
+    score: typeof answers?.[`s${i}`]?.noul === "number" ? (answers[`s${i}`]!.noul as number) : 0,
+  }));
+  const keep = new Set<Entry>(entries.filter((e) => pins.has(e.name)));
+  for (const { entry, score } of scored.filter((s) => !keep.has(s.entry) && s.score >= settings.threshold).sort((a, b) => b.score - a.score)) {
+    if (keep.size >= Math.max(1, settings.maxSkills)) break;
+    keep.add(entry);
+  }
+  return { kept: entries.filter((e) => keep.has(e)), hidden: entries.filter((e) => !keep.has(e)) };
+}
+
+// ─── hidden index ─────────────────────────────────────────────────────────
+
+function tilde(path: string): string {
+  const home = homedir();
+  return path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+}
+
+/**
+ * Static section naming every hidden skill, grouped by the folder that holds
+ * it (`<folder>/<name>/SKILL.md`), so the model can load one on demand.
+ */
+export function hiddenIndex(hidden: readonly Entry[]): string {
+  if (hidden.length === 0) return "";
+  const groups = new Map<string, string[]>();
+  const odd: string[] = [];
+  for (const e of [...hidden].sort((a, b) => a.name.localeCompare(b.name))) {
+    if (e.location && basename(e.location) === e.name) {
+      const parent = tilde(dirname(e.location));
+      groups.set(parent, [...(groups.get(parent) ?? []), e.name]);
+    } else {
+      odd.push(`${e.name} (${tilde(e.location)}/SKILL.md)`);
+    }
+  }
+  const lines = [
+    `Other installed skills — not listed above for this session, but available. To use one, read <folder>/<name>/SKILL.md, or tell the user it can be run as /skill:<name>.`,
+  ];
+  for (const [folder, names] of groups) lines.push(`- ${folder}/: ${names.join(", ")}`);
+  for (const o of odd) lines.push(`- ${o}`);
+  return lines.join("\n");
+}
+
+// ─── per-session frozen state ────────────────────────────────────────────
+
+export interface SessionSkillsState {
+  sessionId: string;
+  judged: boolean;
+  kept: string[];
+  hidden: Entry[];
+  /** The hidden index as frozen (must stay byte-identical). */
+  index: string;
+  revealed: Set<string>;
+}
+
+export function emptyState(sessionId: string): SessionSkillsState {
+  return { sessionId, judged: false, kept: [], hidden: [], index: "", revealed: new Set() };
+}
+
+/** Rebuild the frozen state from session entries (resume / fork / reload). */
+export function restoreState(sessionId: string, entries: ReadonlyArray<object>): SessionSkillsState {
+  const state = emptyState(sessionId);
+  for (const entry of entries) {
+    const { customType, data } = entry as { customType?: string; data?: Record<string, unknown> };
+    if (customType === SKILLS_JUDGED_ENTRY && Array.isArray(data?.kept) && Array.isArray(data?.hidden)) {
+      state.judged = true;
+      state.kept = data.kept.map(String);
+      state.hidden = (data.hidden as Entry[]).map((h) => ({
+        name: String(h.name ?? ""),
+        description: String(h.description ?? ""),
+        location: String(h.location ?? ""),
+      }));
+      state.index = typeof data.index === "string" ? data.index : "";
+      state.revealed = new Set();
+    } else if (customType === SKILLS_REVEALED_ENTRY && Array.isArray(data?.names)) {
+      for (const name of data.names) state.revealed.add(String(name));
+    }
+  }
+  return state;
+}
+
+// ─── the per-turn decision ───────────────────────────────────────────────
+
+export interface TurnInput {
+  prompt: string;
+  /** Skills available this turn after the registry (listed candidates). */
+  catalog: readonly Entry[];
+  settings: ExposureSettings;
+  cwd: string;
+  state: SessionSkillsState;
+  /** Skills the user marked "Must show": always listed, never judged away. */
+  mustShow?: ReadonlySet<string>;
+  /** jev transport; injected in tests. */
+  ask?: (req: { state: string; questions: Record<string, unknown> }) => Promise<Record<string, JevAnswer> | null>;
+}
+
+export interface TurnOutput {
+  /** Names to list this turn. */
+  listed: Set<string>;
+  /** Hidden-skills section text ("" = none). */
+  index: string;
+  /** Skills to announce in a message this turn. */
+  reveal: Entry[];
+  /** Freeze record to persist (first judged turn only). */
+  freeze?: { kept: string[]; hidden: Entry[]; index: string; failOpen?: boolean };
+  status?: string;
+}
+
+export async function decideTurn(input: TurnInput): Promise<TurnOutput> {
+  const { prompt, catalog, settings, state } = input;
+  const all = new Set(catalog.map((e) => e.name));
+  const ask = input.ask ?? ((req) => askJev({ ...req, settings: resolveDecisionModel(input.cwd, "skills"), env: process.env }));
+
+  if (!state.judged) {
+    if (catalog.length <= settings.maxSkills) return { listed: all, index: "", reveal: [] };
+    if (isChatter(prompt)) return { listed: all, index: "", reveal: [], status: "skills: waiting for a real request" };
+    const pins = new Set([...pinnedSkills(catalog, prompt), ...(input.mustShow ?? [])]);
+    const answers = await ask(judgeRequest(catalog, prompt, basename(input.cwd)));
+    const failOpen = answers === null;
+    const { kept, hidden } = failOpen ? { kept: [...catalog], hidden: [] } : applyJudgement(catalog, answers, settings, pins);
+    const index = hiddenIndex(hidden);
+    state.judged = true;
+    state.kept = kept.map((e) => e.name);
+    state.hidden = hidden;
+    state.index = index;
+    return {
+      listed: new Set(state.kept),
+      index,
+      reveal: [],
+      freeze: { kept: state.kept, hidden, index, ...(failOpen ? { failOpen: true } : {}) },
+      status: `skills: ${kept.length}/${catalog.length} listed`,
+    };
+  }
+
+  // Frozen: re-apply the same set and the same index; announcements only.
+  const listed = new Set(state.kept.filter((n) => all.has(n)));
+  // A skill pinned after the freeze is listed from now on (a deliberate change).
+  for (const n of input.mustShow ?? []) if (all.has(n)) listed.add(n);
+  const candidates = state.hidden.filter((h) => all.has(h.name) && !state.revealed.has(h.name) && !listed.has(h.name));
+  const reveal: Entry[] = [];
+  if (candidates.length > 0 && !isChatter(prompt)) {
+    const pins = pinnedSkills(candidates, prompt);
+    reveal.push(...candidates.filter((c) => pins.has(c.name)));
+    if (settings.recheck && reveal.length < REVEAL_CAP) {
+      const rest = candidates.filter((c) => !pins.has(c.name));
+      const answers = rest.length ? await ask(judgeRequest(rest, prompt, basename(input.cwd))) : null;
+      if (answers) {
+        rest.forEach((c, i) => {
+          const score = answers[`s${i}`]?.noul;
+          if (typeof score === "number" && score >= settings.threshold) reveal.push(c);
+        });
+      }
+    }
+  }
+  const announced = reveal.slice(0, REVEAL_CAP);
+  for (const r of announced) state.revealed.add(r.name);
+  return { listed, index: state.index, reveal: announced, status: `skills: ${listed.size}/${listed.size + state.hidden.length} listed` };
+}
+
+export function revealMessage(reveal: readonly Entry[]): string {
+  return (
+    `Relevant skills for this request (not in your skills list):\n` +
+    reveal.map((r) => `- ${r.name} — ${r.description.slice(0, 200)} (${tilde(r.location)}/SKILL.md)`).join("\n") +
+    `\nRead a skill's SKILL.md before using it.`
+  );
+}

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

@@ -0,0 +1,87 @@
+/**
+ * @pi-unipi/skill-registry — per-skill state resolution (pure)
+ *
+ * Defaults: pi-discovered skills are on and listed; vault skills are off
+ * until a scope turns them on. Explicit states from the merged settings
+ * (project over global) override the defaults.
+ */
+
+import { homedir } from "node:os";
+import type { SkillState } from "./settings.js";
+
+/** The slice of pi's Skill the registry needs. */
+export interface CatalogSkill {
+  name: string;
+  description: string;
+  filePath?: string;
+  baseDir?: string;
+}
+
+export type SkillSource = "vault" | "project" | "user" | "unipi" | "package";
+
+export function skillDir(s: CatalogSkill): string {
+  return s.baseDir ?? (s.filePath ? s.filePath.replace(/\/SKILL\.md$/, "") : "");
+}
+
+export function isUnderDir(path: string, dir: string): boolean {
+  const d = dir.endsWith("/") ? dir : `${dir}/`;
+  return path === dir || path.startsWith(d);
+}
+
+/** Unipi's own bundled skills (npm install or dev checkout). */
+export function isBundledSkillLocation(location: string): boolean {
+  return location.includes("/@pi-unipi/") || /\/unipi\/packages\//.test(location);
+}
+
+export function skillSource(s: CatalogSkill, cwd: string, vault: string): SkillSource {
+  const dir = skillDir(s);
+  if (isUnderDir(dir, vault)) return "vault";
+  if (isBundledSkillLocation(dir)) return "unipi";
+  if (isUnderDir(dir, cwd)) return "project";
+  const home = homedir();
+  if (isUnderDir(dir, `${home}/.agents/skills`) || isUnderDir(dir, `${home}/.pi/agent/skills`)) return "user";
+  return "package";
+}
+
+export interface EffectiveState {
+  enabled: boolean;
+  mustShow: boolean;
+}
+
+export function effectiveState(state: SkillState | undefined, source: SkillSource): EffectiveState {
+  const mustShow = state?.mustShow === true;
+  // Must show implies enabled and is always listed.
+  return { enabled: mustShow || (state?.enabled ?? source !== "vault"), mustShow };
+}
+
+export interface RegistryResult<T> {
+  /** Listed skills the user pinned ("Must show"): exposure never hides them. */
+  mustShow: Set<string>;
+  /** Skills listed for the model. */
+  listed: T[];
+  /** Names removed from the session entirely (/skill:name is blocked too). */
+  disabled: Set<string>;
+}
+
+export function applyRegistry<T extends CatalogSkill>(
+  catalog: readonly T[],
+  states: Record<string, SkillState>,
+  cwd: string,
+  vault: string,
+): RegistryResult<T> {
+  const listed: T[] = [];
+  const disabled = new Set<string>();
+  const mustShow = new Set<string>();
+  for (const skill of catalog) {
+    const eff = effectiveState(states[skill.name], skillSource(skill, cwd, vault));
+    if (eff.mustShow) mustShow.add(skill.name);
+    if (!eff.enabled) disabled.add(skill.name);
+    else listed.push(skill);
+  }
+  return { listed, disabled, mustShow };
+}
+
+/** `/skill:name args` → name, else undefined. */
+export function skillCommandName(text: string): string | undefined {
+  return text.trim().match(/^\/skill:([a-z0-9][a-z0-9-]*)/i)?.[1];
+}

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

@@ -0,0 +1,259 @@
+/**
+ * @pi-unipi/skill-registry — settings (namespace `skills`)
+ *
+ *   proxy          — off (default): pi's skills pass through untouched (only
+ *                    exposure judging applies) and vault skills stay hidden.
+ *                    on: the per-skill states below apply, vault included.
+ *   states.<name>  — { enabled, mustShow } per skill, edited in
+ *                    the "Skill settings…" overlay (src/editor.ts). The engine
+ *                    merges global + project layers per option, so a project
+ *                    can turn a vault skill on (or pin a skill) just for itself.
+ *   exposure       — judged | all | off, threshold, maxSkills, recheck.
+ *
+ * Migrates the pre-registry `utility.skills` block into `skills.exposure`.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import {
+  decisionModelSection,
+  DEFAULT_DECISION_OVERRIDE,
+  getSettings,
+  globalSettingsPath,
+  projectSettingsPath,
+  getSettingsScoped,
+  registerSettings,
+  setSettings,
+  unsetSettings,
+  type SettingsSection,
+} from "@pi-unipi/core";
+
+export type ExposureMode = "judged" | "all" | "off";
+
+export interface ExposureSettings {
+  mode: ExposureMode;
+  /** Minimum jev relevance (0–1) for a skill to stay listed. */
+  threshold: number;
+  /** Cap on listed skills; a catalog at or under it is never judged. */
+  maxSkills: number;
+  /** Announce newly relevant hidden skills on later prompts. */
+  recheck: boolean;
+}
+
+export interface SkillState {
+  /** false = removed from the session entirely (catalog and /skill:name). */
+  enabled?: boolean;
+  /** true = always listed and enabled, even when exposure judging would hide it. */
+  mustShow?: boolean;
+}
+
+export interface SkillsSettings {
+  proxy: boolean;
+  states: Record<string, SkillState>;
+  exposure: ExposureSettings;
+}
+
+export const DEFAULT_EXPOSURE: ExposureSettings = {
+  mode: "judged",
+  threshold: 0.8,
+  maxSkills: 12,
+  recheck: true,
+};
+
+export const NAMESPACE = "skills";
+
+const STATIC_SECTIONS: SettingsSection[] = [
+  {
+    title: "Skill registry",
+    description: "Turn skills on or off per project, and keep a vault of extra skills",
+    fields: [
+      { key: "proxy", type: "boolean", label: "Skill proxy", description: "Apply the per-skill choices below and include ~/.unipi/skill-vault (off = pi's skills as-is, vault hidden)" },
+    ],
+  },
+  {
+    title: "Exposure",
+    description: "Which skills are listed in the system prompt",
+    fields: [
+      {
+        key: "exposure.mode",
+        type: "enum",
+        label: "Skill exposure",
+        options: [
+          { value: "judged", label: "judged (jev decides)" },
+          { value: "all", label: "all (no judging)" },
+          { value: "off", label: "off (bundled stripped)" },
+        ],
+        description: "judged = jev picks the skills listed for the session",
+      },
+      { key: "exposure.threshold", type: "number", label: "Relevance threshold", min: 0, max: 1, description: "Minimum jev relevance for a skill to stay listed" },
+      { key: "exposure.maxSkills", type: "number", label: "Max skills listed", min: 1 },
+      { key: "exposure.recheck", type: "boolean", label: "Announce newly relevant skills on later prompts" },
+    ],
+  },
+];
+
+registerSettings({
+  namespace: NAMESPACE,
+  label: "Skills",
+  defaults: {
+    proxy: false,
+    states: {},
+    exposure: { ...DEFAULT_EXPOSURE },
+    decisionModel: DEFAULT_DECISION_OVERRIDE,
+  },
+  schema: [
+    {
+      ...STATIC_SECTIONS[0]!,
+      fields: [
+        ...STATIC_SECTIONS[0]!.fields,
+        { key: "states", type: "action", label: "Skill settings…", description: "Per skill: Enabled / Must show, per global or project scope", command: "unipi:skills-editor" },
+      ],
+    },
+    ...STATIC_SECTIONS.slice(1),
+    decisionModelSection({ title: "Skills — Decision model" }),
+  ],
+});
+
+type Layer = Record<string, SkillState>;
+
+/** The raw per-skill states of each layer (what the editor starts from). */
+export function readStateLayers(cwd: string): { global: Layer; project: Layer } {
+  const layer = (scope: "global" | "project") => normalizeStates((getSettingsScoped(NAMESPACE, scope, cwd) ?? {}).states);
+  return { global: layer("global"), project: layer("project") };
+}
+
+const OPTIONS = ["enabled", "mustShow"] as const;
+
+/**
+ * Write only what changed: a set option becomes `states.<name>.<opt>`, a
+ * cleared one is unset (inherits again). Returns the number of cells written.
+ */
+export function writeStateLayers(cwd: string, before: { global: Layer; project: Layer }, after: { global: Layer; project: Layer }): number {
+  let writes = 0;
+  for (const scope of ["global", "project"] as const) {
+    const names = new Set([...Object.keys(before[scope]), ...Object.keys(after[scope])]);
+    for (const name of names) {
+      for (const opt of OPTIONS) {
+        const was = before[scope][name]?.[opt];
+        const now = after[scope][name]?.[opt];
+        if (was === now) continue;
+        if (now === undefined) unsetSettings(NAMESPACE, `states.${name}.${opt}`, scope, cwd);
+        else setSettings(NAMESPACE, { states: { [name]: { [opt]: now } } }, scope, cwd);
+        writes++;
+      }
+    }
+  }
+  return writes;
+}
+
+function readJson(file: string): Record<string, unknown> | null {
+  try {
+    return fs.existsSync(file) ? (JSON.parse(fs.readFileSync(file, "utf-8")) as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(file: string, data: unknown): void {
+  fs.mkdirSync(file.slice(0, file.lastIndexOf("/")), { recursive: true });
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
+  fs.renameSync(tmp, file);
+}
+
+/**
+ * One-time per layer: `utility.skills` (mode/threshold/maxSkills/recheck, or
+ * the older `discovery` boolean) → `skills.exposure`. The utility block is
+ * removed so the value has a single owner.
+ */
+export function migrateUtilitySkills(cwd: string): void {
+  const pairs: Array<[string, string]> = [
+    [globalSettingsPath("utility"), globalSettingsPath(NAMESPACE)],
+    [projectSettingsPath(cwd, "utility"), projectSettingsPath(cwd, NAMESPACE)],
+  ];
+  for (const [from, to] of pairs) {
+    try {
+      const util = readJson(from);
+      const old = util?.skills as Record<string, unknown> | undefined;
+      if (!util || !old || typeof old !== "object") continue;
+      const exposure: Record<string, unknown> = {};
+      if (old.mode === "judged" || old.mode === "all" || old.mode === "off") exposure.mode = old.mode;
+      else if (old.discovery === false) exposure.mode = "off";
+      for (const key of ["threshold", "maxSkills", "recheck"]) if (old[key] !== undefined) exposure[key] = old[key];
+      const target = readJson(to) ?? {};
+      const existing = (target.exposure as Record<string, unknown> | undefined) ?? {};
+      writeJson(to, { ...target, exposure: { ...exposure, ...existing } });
+      const { skills: _moved, ...rest } = util;
+      writeJson(from, rest);
+    } catch {
+      // Corrupt layer — defaults apply.
+    }
+  }
+}
+
+/** v2: pi settings.json `unipi.skills.discovery` → global `skills.exposure.mode`, once. */
+function importPiSettingsDiscovery(): void {
+  try {
+    const agentDir = process.env.PI_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+    const raw = readJson(path.join(agentDir, "settings.json")) as { unipi?: { skills?: { discovery?: unknown } } } | null;
+    const discovery = raw?.unipi?.skills?.discovery;
+    if (typeof discovery !== "boolean") return;
+    const file = globalSettingsPath(NAMESPACE);
+    const layer = readJson(file) ?? {};
+    const exposure = (layer.exposure as Record<string, unknown> | undefined) ?? {};
+    if (exposure.mode !== undefined) return;
+    writeJson(file, { ...layer, exposure: { ...exposure, mode: discovery ? "judged" : "off" } });
+  } catch {
+    // absent / unreadable — defaults apply
+  }
+}
+
+export function normalizeExposure(raw: unknown): ExposureSettings {
+  const e = (raw ?? {}) as Record<string, unknown>;
+  return {
+    mode: e.mode === "judged" || e.mode === "all" || e.mode === "off" ? e.mode : DEFAULT_EXPOSURE.mode,
+    threshold: typeof e.threshold === "number" && e.threshold >= 0 && e.threshold <= 1 ? e.threshold : DEFAULT_EXPOSURE.threshold,
+    maxSkills: typeof e.maxSkills === "number" && e.maxSkills >= 1 ? Math.floor(e.maxSkills) : DEFAULT_EXPOSURE.maxSkills,
+    recheck: typeof e.recheck === "boolean" ? e.recheck : DEFAULT_EXPOSURE.recheck,
+  };
+}
+
+/**
+ * Per-skill states. Migrates on read: the legacy "on" | "unlisted" | "off"
+ * strings, and the dropped `discoverable` flag — `discoverable: false` was the
+ * old unlisted state and now means disabled, unless mustShow (which wins).
+ */
+export function normalizeStates(raw: unknown): Record<string, SkillState> {
+  const out: Record<string, SkillState> = {};
+  if (!raw || typeof raw !== "object") return out;
+  for (const [name, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (value === "off" || value === "unlisted") out[name] = { enabled: false };
+    else if (value === "on") out[name] = { enabled: true };
+    else if (value && typeof value === "object") {
+      const v = value as Record<string, unknown>;
+      const state: SkillState = {};
+      if (typeof v.enabled === "boolean") state.enabled = v.enabled;
+      if (typeof v.mustShow === "boolean") state.mustShow = v.mustShow;
+      if (v.discoverable === false && state.enabled !== false && !state.mustShow) state.enabled = false;
+      out[name] = state;
+    }
+  }
+  return out;
+}
+
+export function readSkillsSettings(cwd: string = process.cwd()): SkillsSettings {
+  try {
+    migrateUtilitySkills(cwd);
+    importPiSettingsDiscovery();
+    const raw = getSettings(NAMESPACE, cwd) as Record<string, unknown>;
+    return {
+      proxy: raw.proxy === true,
+      states: normalizeStates(raw.states),
+      exposure: normalizeExposure(raw.exposure),
+    };
+  } catch {
+    return { proxy: false, states: {}, exposure: { ...DEFAULT_EXPOSURE } };
+  }
+}
+