@groeponline/pi-wishcraft 1.4.12 → 1.4.14

package/CHANGELOG.md

@@ -2,8 +2,32 @@
 
 ## [Unreleased]
 
+## [1.4.14] - 2026-09-05
+
+## [1.4.13] - 2026-09-05
+
+### Added
+- Skill Studio panes wired end-to-end (`/studio`): the fullscreen workbench now connects the registry-backed list, a detail pane (health, category override, usage count, frontmatter keys, model-invocation flag, and resolved local references with ✓/✗), actions (create from template, edit in-app with cache invalidation, doctor), and AI advice with explain/integrate/examples/improve modes — streamed through the advise engine with DeepWiki wiki context and insert-into-editor. The fail-closed placeholder gate is lifted; the entrypoint keeps its guards (closed without UI, warning + closed in RPC mode).
+- DeepWiki disk cache gains bounded LRU eviction (`maxEntries`, default 64) on top of the existing TTL + stale-fallback behavior.
+- Tests: studio pane render, key routing + refresh, entrypoint guards, and LRU eviction covered; 723 passing.
+
 ## [1.4.12] - 2026-09-05
 
+### Added
+- Skill Studio: browse the ChefGroep global skill registry alongside local skills (`loadSkillStudioCatalog`): registry-only skills surface with routing metadata and a "registry source not readable" warning when the file is unavailable on this host.
+- Motion rail: impressive adaptive rail with motion-driven routing (#83).
+
+### Changed
+- AGENTS.md rewritten to the current architecture (#80).
+- Compound Engineering overlay example clarified: explainer archival and sweep state paths now reference `<docs_root>` (#68); devDependency `@earendil-works/pi-coding-agent` bumped to 0.84.3.
+
+### Removed
+- Dead agent-tools (patch, ripgrep) with no runtime consumers (#81).
+
+### Fixed
+- Rail/render fixes shipped with the studio registry work (#79).
+- Tests: `session_compact_failed` regression coverage — clearing compacting state, settling the signal, and blocking post-compact queue items with the error (#68).
+
 ## [1.4.11] - 2026-08-30
 
 ## [1.4.10] - 2026-08-30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groeponline/pi-wishcraft",
-  "version": "1.4.12",
+  "version": "1.4.14",
   "description": "Operator cockpit for Pi: live powerline status, searchable skills, idea queue, sticky Bash, hooks, policy controls, and session UX.",
   "type": "module",
   "files": [

package/src/studio/component.ts

@@ -1,21 +1,24 @@
-/**
- * Fullscreen studio component (U5, KTD3). Non-overlay `ctx.ui.custom()` —
- * the editor-replacing variant, unlike the Deck's centered overlay. Panes are
- * placeholders here; U6-U10 fill list/detail/actions/advice content.
- */
+/** Fullscreen Skill Studio workbench. The component owns presentation and input;
+ * the existing skills modules remain the only discovery and mutation backend. */
 
 import { matchesKey } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+  buildListRows,
+  filterListRows,
+} from "./list.ts";
+import { resolveReferences, type ResolvedReference } from "./inspect.ts";
+import { readSkillBody, type SkillEntry, type SkillUsage } from "../extension/skills/skill-registry.ts";
+import type { AdvicePane } from "./advice-pane.ts";
+import type { AdviseMode } from "./advise/prompts.ts";
 import {
   createStudioState,
   handleStudioKey,
   STUDIO_PANES,
 } from "./state.ts";
-import type { StudioKeyEvent, StudioState } from "./types.ts";
-import type { SkillEntry } from "../extension/skills/skill-registry.ts";
-import { buildListRows, filterListRows } from "./list.ts";
+import type { StudioKeyEvent, StudioPaneId, StudioState } from "./types.ts";
 
-const PANE_LABELS: Record<string, string> = {
+const PANE_LABELS: Record<StudioPaneId, string> = {
   list: "Skills",
   detail: "Detail",
   actions: "Actions",
@@ -27,11 +30,31 @@ const HELP_LINES: readonly string[] = [
   "",
   "  j / k or arrows   Move selection",
   "  /                 Filter skills",
-  "  Tab               Cycle pane focus",
+  "  Tab or 1-4        Focus a pane",
+  "  Enter             Open the selected skill",
+  "  n                 Create a skill",
+  "  e                 Edit the selected skill",
+  "  d                 Run doctor",
+  "  a                 Focus AI advice",
+  "  r                 Run advice · i insert answer",
   "  ?                 Toggle this help",
   "  q / Esc           Exit studio",
 ];
 
+export interface StudioComponentOptions {
+  entries?: readonly SkillEntry[];
+  usage?: ReadonlyMap<string, SkillUsage>;
+  advicePane?: AdvicePane;
+  adviceMode?: AdviseMode;
+  onRefresh?: () => readonly SkillEntry[];
+  onCreate?: () => Promise<void> | void;
+  onEdit?: (entry: SkillEntry) => Promise<void> | void;
+  onDoctor?: () => Promise<void> | void;
+  onAdvice?: (entry: SkillEntry, mode: AdviseMode, pane: AdvicePane) => Promise<void> | void;
+  onInsert?: (pane: AdvicePane) => Promise<void> | void;
+  onError?: (error: unknown) => void;
+}
+
 export function mapRawInput(data: string): StudioKeyEvent {
   if (matchesKey(data, "escape")) return { key: "escape" };
   if (matchesKey(data, "return")) return { key: "return" };
@@ -47,55 +70,132 @@ export function mapRawInput(data: string): StudioKeyEvent {
   return { key: "other" };
 }
 
-export function renderStudioFrame(
+function fit(text: string, width: number): string {
+  if (width <= 0) return "";
+  return text.length <= width ? text : `${text.slice(0, Math.max(0, width - 1))}…`;
+}
+
+function safeReadReferences(entry: SkillEntry): ResolvedReference[] {
+  return resolveReferences(readSkillBody(entry.filePath), entry.baseDir);
+}
+
+function selectedEntry(
+  entries: readonly SkillEntry[],
+  query: string,
+  selectedIndex: number,
+): SkillEntry | null {
+  const rows = filterListRows(buildListRows(entries), query);
+  const row = rows[selectedIndex] ?? rows[0];
+  return entries.find((entry) => entry.filePath === row?.filePath) ?? null;
+}
+
+function renderHelp(theme: Theme): string[] {
+  return HELP_LINES.map((line, index) => {
+    if (index === 0) return theme.fg("accent", line);
+    return theme.fg(index === HELP_LINES.length - 1 ? "dim" : "muted", line);
+  });
+}
+
+function renderList(
   theme: Theme,
   width: number,
+  entries: readonly SkillEntry[],
   state: StudioState,
-  entries: readonly SkillEntry[] = [],
 ): string[] {
-  if (state.mode === "help") {
-    const lines = [theme.fg("accent", HELP_LINES[0] ?? ""), ""];
-    for (const line of HELP_LINES.slice(2)) lines.push(theme.fg("muted", line));
-    lines.push("", theme.fg("dim", "Press q, Esc, or Enter to close help"));
+  const rows = filterListRows(buildListRows(entries), state.filterQuery);
+  const visible = rows.slice(Math.max(0, state.selectedIndex - 5), state.selectedIndex + 7);
+  const lines = [theme.fg("accent", `SKILLS · ${rows.length}/${entries.length}`)];
+  if (state.filterQuery) lines.push(theme.fg("muted", `filter: ${state.filterQuery}`));
+  if (rows.length === 0) {
+    lines.push(theme.fg("warning", "No skills match this filter"));
     return lines;
   }
+  for (const row of visible) {
+    const absolute = rows.indexOf(row);
+    const marker = absolute === state.selectedIndex ? "›" : " ";
+    const warning = row.warning ? theme.fg("warning", " ⚠") : "";
+    lines.push(
+      `${theme.fg(absolute === state.selectedIndex ? "accent" : "text", `${marker} ${fit(row.name, Math.max(8, width - 18))}`)} ${theme.fg("dim", `[${row.badge}]`)}${warning}`,
+    );
+    if (absolute === state.selectedIndex && row.description) {
+      lines.push(theme.fg("muted", `  ${fit(row.description, Math.max(8, width - 4))}`));
+    }
+  }
+  return lines;
+}
 
-  const focusMark = (pane: string): string =>
-    state.focus === pane ? theme.fg("accent", `[${PANE_LABELS[pane] ?? pane}]`) : theme.fg("dim", ` ${PANE_LABELS[pane] ?? pane} `);
-  const header = STUDIO_PANES.map((pane) => focusMark(pane)).join(" ");
-  const filterLine = state.mode === "filter"
-    ? theme.fg("accent", `filter: ${state.filterQuery}_`)
-    : state.filterQuery ? theme.fg("muted", `filter: ${state.filterQuery}`) : theme.fg("dim", "press / to filter, ? for help");
+function renderDetail(theme: Theme, width: number, entry: SkillEntry | null, usage: ReadonlyMap<string, SkillUsage>): string[] {
+  if (!entry) return [theme.fg("accent", "DETAIL"), theme.fg("dim", "Select a skill from the list")];
+  const body = readSkillBody(entry.filePath);
+  const refs = safeReadReferences(entry);
+  const use = usage.get(entry.name);
+  const health = entry.warning ? theme.fg("warning", "warn") : theme.fg("success", "ok");
+  const override = entry.category === "project" ? "project override" : entry.category === "global" ? "global default" : "standalone";
+  const lines = [
+    theme.fg("accent", `DETAIL · ${fit(entry.name, Math.max(8, width - 10))}`),
+    theme.fg("muted", fit(entry.description || "No description", width)),
+    theme.fg("dim", `health: ${health} · ${override} · used: ${use?.count ?? 0}×`),
+    theme.fg("dim", `file: ${fit(entry.filePath, Math.max(8, width - 6))}`),
+    theme.fg("dim", `frontmatter: ${entry.frontmatterKeys.join(", ") || "none"}`),
+    theme.fg("dim", `model invocation: ${entry.disableModelInvocation ? "off" : "on"}`),
+    theme.fg("accent", `REFERENCES · ${refs.length}`),
+  ];
+  if (refs.length === 0) lines.push(theme.fg("dim", "  none detected"));
+  for (const ref of refs.slice(0, 5)) {
+    lines.push(theme.fg(ref.exists ? "muted" : "warning", `  ${ref.exists ? "✓" : "✗"} ${fit(ref.href, Math.max(8, width - 6))}`));
+  }
+  return lines;
+}
 
-  const rows = filterListRows(buildListRows(entries), state.filterQuery);
-  const selectedIndex = rows.length ? Math.min(state.selectedIndex, rows.length - 1) : 0;
-  const selected = rows[selectedIndex];
-  const radius = 4;
-  const from = Math.max(0, selectedIndex - radius);
-  const visible = rows.slice(from, from + 9);
-  const lines: string[] = [theme.fg("accent", `Skill Studio · ${rows.length} skills`), header, filterLine, theme.fg("dim", "─".repeat(Math.max(1, Math.min(width - 1, 78))))];
-
-  if (!selected) {
-    lines.push(theme.fg("muted", "No skills match the current filter."));
-  } else {
-    for (let i = 0; i < visible.length; i += 1) {
-      const row = visible[i]!;
-      const absolute = from + i;
-      const mark = absolute === selectedIndex ? ">" : " ";
-      const route = row.routingCategory ? ` · ${row.routingCategory}/${row.routingFamily ?? "general"}` : "";
-      const drift = row.registryDrift ? " · drift" : "";
-      const text = `${mark} [${row.badge}] ${row.name}${route}${drift}`;
-      lines.push(absolute === selectedIndex ? theme.fg("accent", text) : theme.fg("muted", text));
-    }
-    lines.push(theme.fg("dim", "─".repeat(Math.max(1, Math.min(width - 1, 78)))));
-    lines.push(theme.fg("accent", selected.name));
-    lines.push(theme.fg("muted", selected.description || "No description"));
-    const ownership = [selected.role && `role=${selected.role}`, selected.routerParent && `parent=${selected.routerParent}`].filter(Boolean).join(" · ");
-    if (ownership) lines.push(theme.fg("dim", ownership));
-    lines.push(theme.fg("dim", selected.filePath));
-    if (selected.warning) lines.push(theme.fg("warning", `warning: ${selected.warning}`));
+function adviceModeLabel(mode: AdviseMode): string {
+  return mode === "explain" ? "explain" : mode === "integrate" ? "integrate" : mode === "examples" ? "examples" : "improve";
+}
+
+function renderAdvice(theme: Theme, width: number, entry: SkillEntry | null, pane: AdvicePane, mode: AdviseMode): string[] {
+  const lines = [
+    theme.fg("accent", `AI ADVICE · ${adviceModeLabel(mode)}`),
+    entry ? theme.fg("muted", `skill: ${entry.name}`) : theme.fg("dim", "Select a skill first"),
+    theme.fg("dim", "r run · e explain · g integrate · x examples · m improve · i insert"),
+  ];
+  if (pane.state === "running") lines.push(theme.fg("accent", "Thinking…"));
+  if (pane.state === "unavailable") lines.push(theme.fg("warning", `Advice unavailable: ${pane.error ?? "unknown error"}`));
+  const text = pane.text.trim();
+  if (text) {
+    lines.push(theme.fg("text", fit(text.replace(/\n/g, " "), Math.max(8, width - 2))));
+  } else if (pane.state === "idle") {
+    lines.push(theme.fg("dim", "Advice uses the selected skill and its local references."));
   }
-  lines.push(theme.fg("dim", "q/Esc exit · / filter · j/k navigate · Tab focus · ? help"));
+  return lines;
+}
+
+export function renderStudioFrame(
+  theme: Theme,
+  width: number,
+  state: StudioState,
+  options: Pick<StudioComponentOptions, "entries" | "usage" | "advicePane" | "adviceMode"> = {},
+): string[] {
+  if (state.mode === "help") return renderHelp(theme);
+  const entries = options.entries ?? [];
+  const usage = options.usage ?? new Map<string, SkillUsage>();
+  const pane = options.advicePane ?? { state: "idle", text: "", error: null } as AdvicePane;
+  const entry = selectedEntry(entries, state.filterQuery, state.selectedIndex);
+  const mode: AdviseMode = options.adviceMode ?? "explain";
+  const innerWidth = Math.max(20, width - 2);
+  const lines = [
+    theme.fg("accent", "Skill Studio"),
+    STUDIO_PANES.map((paneId) => state.focus === paneId ? theme.fg("accent", `[${PANE_LABELS[paneId]}]`) : theme.fg("dim", ` ${PANE_LABELS[paneId]} `)).join(" "),
+    theme.fg("dim", "─".repeat(Math.max(1, Math.min(innerWidth, 72)))),
+  ];
+  lines.push(...renderList(theme, innerWidth, entries, state));
+  lines.push(theme.fg("dim", "─".repeat(Math.max(1, Math.min(innerWidth, 72)))));
+  lines.push(...renderDetail(theme, innerWidth, entry, usage));
+  lines.push(theme.fg("dim", "─".repeat(Math.max(1, Math.min(innerWidth, 72)))));
+  lines.push(theme.fg("accent", "ACTIONS"));
+  lines.push(theme.fg("muted", "n create · e edit · d doctor · Enter detail"));
+  lines.push(theme.fg("dim", "─".repeat(Math.max(1, Math.min(innerWidth, 72)))));
+  lines.push(...renderAdvice(theme, innerWidth, entry, pane, mode));
+  lines.push(theme.fg("dim", "─".repeat(Math.max(1, Math.min(innerWidth, 72)))));
+  lines.push(theme.fg("dim", "q/Esc exit · / filter · Tab focus · ? help"));
   return lines;
 }
 
@@ -103,23 +203,77 @@ export function createStudioComponent(
   theme: Theme,
   done: (value: string | null) => void,
   onStateChange?: (state: StudioState) => void,
-  entries: readonly SkillEntry[] = [],
+  options: StudioComponentOptions = {},
 ) {
   let state = createStudioState();
+  let entries = [...(options.entries ?? [])];
+  let adviceMode: AdviseMode = "explain";
+  let finished = false;
+  const pane = options.advicePane ?? {
+    state: "idle",
+    text: "",
+    error: null,
+    run: async () => {},
+    reset: () => {},
+  } as AdvicePane;
+
+  const refresh = () => {
+    const next = options.onRefresh?.();
+    if (next) entries = [...next];
+  };
+  const current = () => selectedEntry(entries, state.filterQuery, state.selectedIndex);
+  const notifyChange = (next: StudioState) => {
+    state = next;
+    onStateChange?.(state);
+  };
+  const invoke = (work: () => Promise<void> | void) => {
+    void Promise.resolve(work()).then(() => {
+      refresh();
+    }).catch((error: unknown) => options.onError?.(error));
+  };
+  const focus = (paneId: StudioPaneId) => notifyChange({ ...state, focus: paneId });
+  const runAdvice = () => {
+    const entry = current();
+    if (!entry || !options.onAdvice) return;
+    invoke(() => options.onAdvice!(entry, adviceMode, pane));
+  };
 
   return {
     focused: true,
     invalidate() {},
     render(width: number) {
-      return renderStudioFrame(theme, width, state, entries);
+      return renderStudioFrame(theme, width, state, { entries, usage: options.usage, advicePane: pane, adviceMode });
     },
     handleInput(data: string) {
-      const next = handleStudioKey(state, mapRawInput(data));
-      if (next !== state) {
-        state = next;
-        onStateChange?.(state);
+      if (state.mode === "normal") {
+        if (data >= "1" && data <= "4") {
+          focus(STUDIO_PANES[Number(data) - 1] ?? "list");
+          return;
+        }
+        if (data === "\r" || matchesKey(data, "return")) {
+          if (state.focus === "list") focus("detail");
+          return;
+        }
+        if (state.focus === "advice") {
+          if (data === "e") adviceMode = "explain";
+          else if (data === "g") adviceMode = "integrate";
+          else if (data === "x") adviceMode = "examples";
+          else if (data === "m") adviceMode = "improve";
+          else if (data === "r") runAdvice();
+          else if (data === "i" && options.onInsert) invoke(() => options.onInsert!(pane));
+        } else if (state.focus === "actions" || state.focus === "detail" || state.focus === "list") {
+          if (data === "n" && options.onCreate) invoke(() => options.onCreate!());
+          else if (data === "e" && current() && options.onEdit) invoke(() => options.onEdit!(current()!));
+          else if (data === "d" && options.onDoctor) invoke(() => options.onDoctor!());
+          else if (data === "a") focus("advice");
+          else if (data === "i" && pane.state === "ok" && options.onInsert) invoke(() => options.onInsert!(pane));
+          else if (state.focus === "detail" && data === "r") runAdvice();
+        }
       }
-      if (state.exitRequested) {
+      const next = handleStudioKey(state, mapRawInput(data));
+      if (next !== state) notifyChange(next);
+      if (state.exitRequested && !finished) {
+        finished = true;
         done(null);
       }
     },

package/src/studio/deepwiki/cache.ts

@@ -1,11 +1,21 @@
-/** DeepWiki disk cache (U9). TTL + stale fallback, no LRU (ponytail: add when
- *  the cache directory count actually grows). */
+/** DeepWiki disk cache (U9). TTL + stale fallback + bounded LRU eviction. */
 
-import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  utimesSync,
+  writeFileSync,
+} from "node:fs";
 import { join } from "node:path";
 import { getAgentPath } from "../../paths/agent-dirs.ts";
 import type { RepoRef } from "./extract.ts";
 
+const DEFAULT_MAX_ENTRIES = 64;
+
 export function resolveCacheDir(override?: string): string {
   return override ?? getAgentPath("wishcraft-cache", "deepwiki");
 }
@@ -21,32 +31,96 @@ export interface CacheReadResult<T> {
   entry: CacheFile<T> | null;
 }
 
+export interface CacheOptions {
+  ttlMs: number;
+  now?: number;
+  maxEntries?: number;
+}
+
 function fileFor(dir: string, repo: RepoRef): string {
   return join(dir, repo.owner, `${repo.repo}.json`);
 }
 
+function cacheFiles(dir: string): string[] {
+  const files: string[] = [];
+  let owners: string[];
+  try {
+    owners = readdirSync(dir);
+  } catch {
+    return files;
+  }
+  for (const owner of owners) {
+    const ownerDir = join(dir, owner);
+    let entries: string[];
+    try {
+      entries = readdirSync(ownerDir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.endsWith(".json")) files.push(join(ownerDir, entry));
+    }
+  }
+  return files;
+}
+
+/** Remove least-recently-used entries until the cache is within its cap. */
+export function evictCacheEntries(dir: string, maxEntries = DEFAULT_MAX_ENTRIES): void {
+  const cap = Math.max(1, Math.floor(maxEntries));
+  const files = cacheFiles(dir);
+  if (files.length <= cap) return;
+  const ordered = files
+    .map((file) => {
+      try {
+        return { file, atimeMs: statSync(file).atimeMs, mtimeMs: statSync(file).mtimeMs };
+      } catch {
+        return { file, atimeMs: 0, mtimeMs: 0 };
+      }
+    })
+    .sort((a, b) => (a.atimeMs - b.atimeMs) || (a.mtimeMs - b.mtimeMs));
+  for (const item of ordered.slice(0, files.length - cap)) {
+    try {
+      unlinkSync(item.file);
+    } catch {
+      // A concurrent cleanup must not break advice or cache reads.
+    }
+  }
+}
+
+function touch(file: string, now: number): void {
+  try {
+    const date = new Date(now);
+    utimesSync(file, date, date);
+  } catch {
+    // Cache recency is best-effort metadata.
+  }
+}
+
 export async function writeCacheEntry<T>(
   dir: string,
   repo: RepoRef,
   data: T,
-  options: { ttlMs: number; now?: number },
+  options: CacheOptions,
 ): Promise<void> {
   const now = options.now ?? Date.now();
   const file = fileFor(dir, repo);
   mkdirSync(join(dir, repo.owner), { recursive: true });
   writeFileSync(file, JSON.stringify({ savedAt: now, data }), "utf8");
+  touch(file, now);
+  evictCacheEntries(dir, options.maxEntries);
 }
 
 export async function readCacheEntry<T>(
   dir: string,
   repo: RepoRef,
-  options: { ttlMs: number; now?: number },
+  options: CacheOptions,
 ): Promise<CacheReadResult<T>> {
   const now = options.now ?? Date.now();
   const file = fileFor(dir, repo);
   if (!existsSync(file)) return { status: "miss", stale: false, entry: null };
   try {
     const raw = JSON.parse(readFileSync(file, "utf8")) as CacheFile<T>;
+    touch(file, now);
     const fresh = now - raw.savedAt <= options.ttlMs;
     return { status: fresh ? "hit" : "miss", stale: !fresh, entry: raw };
   } catch {
@@ -57,7 +131,7 @@ export async function readCacheEntry<T>(
 export async function withCache<T>(
   dir: string,
   repo: RepoRef,
-  options: { ttlMs: number; now?: number },
+  options: CacheOptions,
   networkFetch: () => Promise<T>,
 ): Promise<CacheReadResult<T>> {
   const fresh = await readCacheEntry<T>(dir, repo, options);

package/src/studio/open.ts

@@ -4,20 +4,179 @@
  * context arrives via parameters only.
  */
 
+import { readFileSync, writeFileSync } from "node:fs";
+import { getAgentPath } from "../paths/agent-dirs.ts";
 import type { RuntimeState } from "../extension/core/types.ts";
+import {
+  getSkillUsage,
+  invalidateSkillCache,
+  loadSkillStudioCatalog,
+  readSkillBody,
+  type SkillEntry,
+} from "../extension/skills/skill-registry.ts";
+import { runStudioAction } from "./actions.ts";
+import { createAdvicePane, advicePaneInsert } from "./advice-pane.ts";
 import { createStudioComponent } from "./component.ts";
-import { loadSkillStudioCatalog, invalidateSkillCache } from "../extension/skills/skill-registry.ts";
+import { extractRepos, type RepoRef } from "./deepwiki/extract.ts";
+import { callTool } from "./deepwiki/client.ts";
+import { withCache } from "./deepwiki/cache.ts";
+import type { AdviseStreamProvider } from "./advise/engine.ts";
 
-/**
- * Keep the operator command fail-closed until list/detail/actions/advice are
- * actually wired into the fullscreen component. The scaffold stays available
- * to tests and follow-up implementation without exposing a misleading command.
- */
+/** The fullscreen component is now connected to discovery, actions, and advice. */
 export const SKILL_STUDIO_PANES_READY = true;
 
+const DEEPWIKI_TTL_MS = 24 * 60 * 60 * 1000;
+const DEEPWIKI_MAX_ENTRIES = 64;
+const DEEPWIKI_ENDPOINT = "https://mcp.deepwiki.com/mcp";
+
+type StudioContext = {
+  hasUI: boolean;
+  mode: string;
+  cwd?: string;
+  ui: {
+    notify(message: string, type?: "info" | "warning" | "error"): void;
+    custom<T>(factory: (...args: any[]) => any, options?: { overlay?: boolean }): Promise<T>;
+    input?(title: string, placeholder?: string): Promise<string | undefined>;
+    select?(title: string, options: string[]): Promise<string | undefined>;
+    confirm?(title: string, message: string): Promise<boolean>;
+    editor?(title: string, prefill?: string): Promise<string | undefined>;
+    getEditorText?(): string;
+    setEditorText?(text: string): void;
+  };
+  model?: {
+    id: string;
+    contextWindow: number;
+    maxTokens: number;
+    provider: string;
+    baseUrl?: string;
+  };
+  modelRegistry?: {
+    getProvider(provider: string): {
+      stream(model: unknown, context: unknown, options: Record<string, unknown>): AsyncIterable<unknown>;
+    } | undefined;
+    getApiKeyAndHeaders(model: unknown): Promise<{
+      ok: boolean;
+      apiKey?: string;
+      headers?: Record<string, string | null>;
+      env?: Record<string, string>;
+      baseUrl?: string;
+    }>;
+  };
+};
+
+interface WikiPayload {
+  content: string;
+}
+
+function referencesFor(entry: SkillEntry): { name: string; content: string }[] {
+  const body = readSkillBody(entry.filePath);
+  const refs = body.matchAll(/\[[^\]]+\]\((references|scripts)\/[^)\s]+\)/g);
+  const sections: { name: string; content: string }[] = [];
+  for (const match of refs) {
+    const hrefMatch = /\(([^)\s]+)\)/.exec(match[0] ?? "");
+    const href = hrefMatch?.[1];
+    if (!href) continue;
+    try {
+      sections.push({ name: href, content: readFileSync(`${entry.baseDir}/${href}`, "utf8") });
+    } catch {
+      sections.push({ name: href, content: "(missing local reference)" });
+    }
+  }
+  return sections;
+}
+
+async function fetchWiki(repo: RepoRef): Promise<WikiPayload> {
+  const structure = await callTool<{ content?: { type: string; text?: string }[] }>(
+    "read_wiki_structure",
+    { repo: `${repo.owner}/${repo.repo}` },
+    DEEPWIKI_ENDPOINT,
+  );
+  const structureText = structure.content?.map((part) => part.text ?? "").join("\n") ?? "";
+  const contents = await callTool<{ content?: { type: string; text?: string }[] }>(
+    "read_wiki_contents",
+    { repo: `${repo.owner}/${repo.repo}` },
+    DEEPWIKI_ENDPOINT,
+  );
+  const contentText = contents.content?.map((part) => part.text ?? "").join("\n") ?? "";
+  return { content: `${structureText}\n\n${contentText}`.trim() };
+}
+
+async function localWikiContext(entry: SkillEntry, notify: (message: string, type?: "info" | "warning" | "error") => void) {
+  const sections: { name: string; content: string }[] = [];
+  for (const repo of extractRepos(readSkillBody(entry.filePath))) {
+    const cached = await withCache(
+      getAgentPath("wishcraft-cache", "deepwiki"),
+      repo,
+      { ttlMs: DEEPWIKI_TTL_MS, maxEntries: DEEPWIKI_MAX_ENTRIES },
+      () => fetchWiki(repo),
+    );
+    if (cached.entry?.data.content) {
+      sections.push({ name: `${repo.owner}/${repo.repo}`, content: cached.entry.data.content });
+    }
+    if (cached.stale || !cached.entry) {
+      notify(`DeepWiki unavailable for ${repo.owner}/${repo}; using local skill context`, "warning");
+    }
+  }
+  return sections;
+}
+
+async function runAdviceFor(
+  ctx: StudioContext,
+  entry: SkillEntry,
+  mode: "explain" | "integrate" | "examples" | "improve",
+  pane: ReturnType<typeof createAdvicePane>,
+): Promise<void> {
+  const model = ctx.model;
+  const registry = ctx.modelRegistry;
+  const provider = model && registry ? registry.getProvider(model.provider) : undefined;
+  if (!model || !registry || !provider) {
+    await pane.run({ mode, skillName: entry.name, body: readSkillBody(entry.filePath), references: referencesFor(entry), wiki: [], provider: null, signal: new AbortController().signal });
+    return;
+  }
+  const auth = await registry.getApiKeyAndHeaders(model);
+  if (!auth.ok) {
+    await pane.run({ mode, skillName: entry.name, body: readSkillBody(entry.filePath), references: referencesFor(entry), wiki: [], provider: null, signal: new AbortController().signal });
+    return;
+  }
+  const requestModel = auth.baseUrl ? { ...model, baseUrl: auth.baseUrl } : model;
+  const streamProvider: AdviseStreamProvider = {
+    stream: (_advisorModel, context, options) => provider.stream(requestModel, {
+      systemPrompt: context.prompt?.system,
+      messages: [{ role: "user", content: [{ type: "text", text: context.prompt?.user ?? "" }], timestamp: Date.now() }],
+    }, {
+      apiKey: auth.apiKey,
+      headers: auth.headers,
+      env: auth.env,
+      signal: options.signal,
+      maxTokens: options.maxTokens,
+    }),
+  };
+  const references = referencesFor(entry);
+  const wiki = await localWikiContext(entry, (message, type) => ctx.ui.notify(message, type));
+  await pane.run({
+    mode,
+    skillName: entry.name,
+    body: readSkillBody(entry.filePath),
+    references,
+    wiki,
+    provider: streamProvider,
+    model: { id: model.id, contextWindow: model.contextWindow, maxTokens: model.maxTokens },
+    signal: new AbortController().signal,
+  });
+}
+
+async function editSkill(ctx: StudioContext, entry: SkillEntry): Promise<void> {
+  if (!ctx.ui.editor) return;
+  const next = await ctx.ui.editor(`Edit skill: ${entry.name}`, readFileSync(entry.filePath, "utf8"));
+  if (next === undefined) return;
+  writeFileSync(entry.filePath, next, "utf8");
+  invalidateSkillCache();
+  ctx.ui.notify(`Updated ${entry.name}`, "info");
+}
+
 export async function openSkillStudio(
   rt: RuntimeState,
-  ctx: any,
+  ctx: StudioContext,
 ): Promise<void> {
   if (!rt.enabled) {
     if (ctx.hasUI) ctx.ui.notify("Skill Studio requires the Signal UI to be enabled", "info");
@@ -33,10 +192,45 @@ export async function openSkillStudio(
   }
   rt.currentCtx = ctx;
   invalidateSkillCache();
-  const entries = loadSkillStudioCatalog(process.cwd());
-
+  const cwd = ctx.cwd ?? process.cwd();
+  const pane = createAdvicePane();
+  let entries = loadSkillStudioCatalog(cwd);
   await ctx.ui.custom(
-    (_tui: any, theme: any, _keybindings: any, done: (value: string | null) => void) =>
-      createStudioComponent(theme, done, undefined, entries),
+    (_tui: unknown, theme: any, _keybindings: unknown, done: (value: string | null) => void) =>
+      createStudioComponent(theme, done, undefined, {
+        entries,
+        usage: getSkillUsage(),
+        advicePane: pane,
+        onRefresh: () => {
+          entries = loadSkillStudioCatalog(cwd);
+          return entries;
+        },
+        onCreate: async () => {
+          const name = await ctx.ui.input?.("New skill", "skill-name");
+          if (!name) return;
+          const template = await ctx.ui.select?.("Template", ["standard", "browser-workflow", "cli-workflow", "review-checklist"]);
+          const result = await runStudioAction({ type: "create", name, template: (template ?? "standard") as "standard" | "browser-workflow" | "cli-workflow" | "review-checklist", skillsRoot: getAgentPath("skills") }, {
+            confirm: (message) => ctx.ui.confirm?.("Confirm", message) ?? Promise.resolve(false),
+          });
+          ctx.ui.notify(result.message, result.kind === "error" ? "error" : "info");
+        },
+        onEdit: (entry) => editSkill(ctx, entry),
+        onDoctor: async () => {
+          const result = await runStudioAction({ type: "doctor", cwd }, { confirm: async () => false });
+          ctx.ui.notify(result.message, result.kind === "error" ? "error" : "info");
+        },
+        onAdvice: (entry, mode, targetPane) => runAdviceFor(ctx, entry, mode, targetPane),
+        onInsert: (targetPane) => {
+          if (!ctx.ui.getEditorText || !ctx.ui.setEditorText) return;
+          advicePaneInsert(targetPane, {
+            appendUserMessage(text) {
+              const current = ctx.ui.getEditorText!();
+              ctx.ui.setEditorText!(`${current}${current ? "\n\n" : ""}${text}\n`);
+            },
+          });
+          ctx.ui.notify("Advice inserted into the editor", "info");
+        },
+        onError: (error) => ctx.ui.notify(error instanceof Error ? error.message : String(error), "error"),
+      }),
   );
 }