jeo-code 0.1.0

package/src/commands/mcp.ts

@@ -0,0 +1,18 @@
+import { runMcpServer } from "../mcp";
+
+export async function runMcpCommand(args: string[]): Promise<void> {
+  const sub = args[0];
+  if (sub === "serve" || !sub) {
+    await runMcpServer();
+    return;
+  }
+  if (sub === "tools") {
+    const { TOOLS } = await import("../mcp");
+    console.log(`Available joc-mcp tools (${TOOLS.length}):`);
+    for (const t of TOOLS) console.log(`  ${t.name.padEnd(28)} ${t.description}`);
+    return;
+  }
+  console.log(`unknown 'joc mcp' subcommand: ${sub}`);
+  console.log("Usage: joc mcp [serve|tools]");
+  process.exit(1);
+}

package/src/commands/models.ts

@@ -0,0 +1,104 @@
+import { readGlobalConfig } from "../agent/state";
+import { listAliases, resolveModelId } from "../ai/model-registry";
+import { resolveProvider, resolveRoleModel } from "../ai/model-manager";
+import { describeAllProviders } from "../ai/provider-status";
+import { discoverModels } from "../ai/model-discovery";
+import { formatLiveModels, formatCatalogTable, formatEnrichedModels } from "../tui/components/config-panel";
+import { MODEL_CATALOG, fuzzyMatchCatalog, type ThinkLevel } from "../ai/model-catalog";
+import { enrichAll, filterCapable, sortByCapability, knownCount } from "../ai/model-enrich";
+
+async function probeOllama(baseUrl: string): Promise<string[]> {
+  try {
+    const r = await fetch(`${baseUrl.replace(/\/$/, "")}/api/tags`, { signal: AbortSignal.timeout(2500) });
+    if (!r.ok) return [];
+    const data = (await r.json()) as { models?: { name: string }[] };
+    return (data.models ?? []).map(m => `ollama/${m.name}`);
+  } catch {
+    return [];
+  }
+}
+
+async function probeOpenAiCompat(baseUrl: string): Promise<string[]> {
+  try {
+    const r = await fetch(`${baseUrl.replace(/\/$/, "")}/models`, { signal: AbortSignal.timeout(2500) });
+    if (!r.ok) return [];
+    const data = (await r.json()) as { data?: { id: string }[] };
+    return (data.data ?? []).map(m => `openai/${m.id}`);
+  } catch {
+    return [];
+  }
+}
+
+export async function runModelsCommand(args: string[] = []): Promise<void> {
+  const checkMode = args.includes("--check");
+  const providerFilter = args.find(a => ["anthropic", "openai", "gemini", "ollama"].includes(a.toLowerCase()))?.toLowerCase();
+  if (args.includes("--catalog")) {
+    const query = args.find(a => !a.startsWith("--") && !["anthropic", "openai", "gemini", "ollama"].includes(a.toLowerCase()));
+    const rows = query ? fuzzyMatchCatalog(query) : [...MODEL_CATALOG];
+    console.log("\n=== joc models --catalog ===");
+    console.log(`Known model capabilities${query ? ` matching '${query}'` : ""}:`);
+    for (const line of formatCatalogTable(rows)) console.log(line);
+    return;
+  }
+  if (args.includes("--caps")) {
+    const cfg = await readGlobalConfig();
+    const def = await resolveModelId(cfg.defaultModel);
+    const thinkArg = args.find(a => a.startsWith("--thinking="))?.split("=")[1] as ThinkLevel | undefined;
+    const filter = {
+      thinking: thinkArg,
+      images: args.includes("--images") ? true : undefined,
+      minContext: args.includes("--long") ? 200_000 : undefined,
+    };
+    console.log("\n=== joc models --caps (live + capabilities) ===");
+    const live = await discoverModels({ config: cfg, timeoutMs: 4000 });
+    const enriched = sortByCapability(filterCapable(enrichAll(live), filter));
+    const { known, unknown } = knownCount(enriched);
+    for (const line of formatEnrichedModels(enriched, { current: def })) console.log(line);
+    console.log(`\n${known} with known capabilities, ${unknown} unknown.`);
+    return;
+  }
+  const config = await readGlobalConfig();
+  console.log("\n=== joc models ===");
+  const resolved = await resolveModelId(config.defaultModel);
+  console.log(`Default model: ${config.defaultModel}${resolved !== config.defaultModel ? ` → ${resolved}` : ""} → ${resolveProvider(resolved)}`);
+  console.log(`Role tiers: smol=${resolveRoleModel("smol", config)} · slow=${resolveRoleModel("slow", config)} · plan=${resolveRoleModel("plan", config)}`);
+
+  const aliases = await listAliases();
+  console.log("\nAliases (use as the model id; config overrides built-ins):");
+  for (const [alias, target] of Object.entries(aliases)) {
+    console.log(`  ${alias.padEnd(10)} → ${target.padEnd(22)} (${resolveProvider(target)})`);
+  }
+
+  const ollamaBase = config.ollamaBaseUrl ?? "http://localhost:11434";
+  const ollama = await probeOllama(ollamaBase);
+  console.log(`\nLocal Ollama (${ollamaBase}):`);
+  if (ollama.length) for (const m of ollama.slice(0, 30)) console.log(`  ${m}`);
+  else console.log("  (none reachable)");
+
+  if (config.openaiBaseUrl) {
+    const compat = await probeOpenAiCompat(config.openaiBaseUrl);
+    console.log(`\nOpenAI-compatible (${config.openaiBaseUrl}):`);
+    if (compat.length) for (const m of compat.slice(0, 30)) console.log(`  ${m}`);
+    else console.log("  (none reachable)");
+  }
+  console.log("\nProvider credentials:");
+  for (const status of await describeAllProviders(config)) {
+    const base = status.baseUrl ? `  [${status.baseUrl}]` : "";
+    console.log(`  ${status.name.padEnd(10)} ${status.ready ? "✓" : "·"} ${status.label}${base}`);
+  }
+
+  console.log("\nLive models (logged-in providers):");
+  let live = await discoverModels({ config, timeoutMs: 4000 });
+  if (providerFilter) live = live.filter(r => r.provider === providerFilter);
+  if (checkMode) {
+    for (const r of live) {
+      const mark = r.ok ? "✓" : "✗";
+      const detail = r.ok ? `${r.models.length} models (${r.source})` : `${r.error} (${r.source})`;
+      console.log(`  ${mark} ${r.provider.padEnd(10)} ${detail}`);
+    }
+    return;
+  }
+  for (const line of formatLiveModels(live, { current: resolved, perProvider: 20 })) console.log(line);
+
+  console.log("\nSet a default with 'joc setup' or JOC_DEFAULT_MODEL=<id>.");
+}

package/src/commands/ralplan.ts

@@ -0,0 +1,86 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { callLlm } from "../agent/loop";
+import {
+  readWorkflowState,
+  writeWorkflowState,
+  getLocalJocDir,
+  type WorkflowState,
+} from "../agent/state";
+
+export async function runRalplanCommand(): Promise<void> {
+  const cwd = process.cwd();
+
+  // Read deep-interview state
+  const interviewState = await readWorkflowState("deep-interview", cwd);
+  if (!interviewState || interviewState.current_phase !== "complete" || !interviewState.seed_path) {
+    console.log(
+      `[ERROR] No crystallized requirements found. Please run 'joc deep-interview' to crystallize requirements first.`
+    );
+    return;
+  }
+
+  const seedPath = interviewState.seed_path;
+  console.log(`\n=== Starting Ralplan Planning Stage ===`);
+  console.log(`Reading requirements seed from: ${seedPath}`);
+
+  let seedContent = "";
+  try {
+    seedContent = await fs.readFile(seedPath, "utf-8");
+  } catch (err: any) {
+    console.log(`[ERROR] Failed to read seed file: ${err.message}`);
+    return;
+  }
+
+  // Initialize ralplan state
+  const ralplanState: WorkflowState = {
+    active: true,
+    current_phase: "planning",
+    skill: "ralplan" as const,
+    slug: interviewState.slug,
+    seed_path: seedPath,
+  };
+  await writeWorkflowState("ralplan", ralplanState, cwd);
+
+  console.log("Generating resilient task sequence plan (Critiqued by Planner/Architect/Critic)...");
+
+  // Standard multi-role system prompt
+  const systemPrompt = 
+    `You are the Ralplan Orchestrator, combining three expert roles:\n` +
+    `1. Planner: Focuses on sequencing tasks into a highly logical, outcome-based progression.\n` +
+    `2. Architect: Reviews technical feasibility, structural directories, and patterns.\n` +
+    `3. Critic: Critiques the plan for vagueness, redundant copies, and missing steps.\n\n` +
+    `Analyze the given crystallized spec (seed.yaml) and generate a step-by-step implementation plan.\n` +
+    `Output the final plan in YAML format. Ensure it contains a clear sequence of tasks with descriptive names and target files.\n` +
+    `Output ONLY the YAML. Do not include markdown wraps or code blocks.`;
+
+  const messages = [
+    { role: "user" as const, content: `Here is the crystallized spec (seed.yaml):\n\n${seedContent}` }
+  ];
+
+  try {
+    const rawPlan = await callLlm(messages, { systemPrompt });
+    const cleanPlan = rawPlan.replace(/```yaml|```/g, "").trim();
+
+    const planDir = path.join(getLocalJocDir(cwd), "plans");
+    await fs.mkdir(planDir, { recursive: true });
+    const planPath = path.join(planDir, `plan-${interviewState.slug}.yaml`);
+
+    await fs.writeFile(planPath, cleanPlan, "utf-8");
+    console.log(`\n[SUCCESS] Plan successfully created and saved to: ${planPath}`);
+
+    ralplanState.current_phase = "complete";
+    ralplanState.plan_path = planPath;
+    ralplanState.approved = false;
+    await writeWorkflowState("ralplan", ralplanState, cwd);
+
+    console.log("\nPlan preview:");
+    console.log("-----------------------------------------");
+    console.log(cleanPlan);
+    console.log("-----------------------------------------");
+    console.log("\n[Handoff Ready] The blueprint is prepared. Run 'joc team' to execute the plan.");
+
+  } catch (error: any) {
+    console.log(`[ERROR calling LLM during Planning]: ${error.message}`);
+  }
+}

package/src/commands/resume.ts

@@ -0,0 +1,6 @@
+import { runLaunchCommand } from "./launch";
+
+/** `joc resume [id]` — resume the latest (or a specific) interactive session. */
+export async function runResumeCommand(args: string[] = []): Promise<void> {
+  return runLaunchCommand(["--resume", ...args]);
+}

package/src/commands/setup-helpers.ts

@@ -0,0 +1,93 @@
+/**
+ * Pure helpers for the model/provider setting flow (`joc setup`). Extracted from
+ * the readline-driven command so the validation, normalization, recommendation,
+ * and summary logic is unit-testable without a TTY.
+ */
+import type { ProviderName } from "../ai/types";
+import { recommendedModel, validateModelId, suggestModels, findCatalogEntry, catalogForProvider } from "../ai/model-catalog-compat";
+import { resolveProvider } from "../ai/model-manager";
+import type { Config } from "../agent/state";
+
+/**
+ * Normalize a base URL: trim, default when blank, add `http://` when no scheme,
+ * strip trailing slashes. Returns the fallback unchanged when input is empty.
+ */
+export function normalizeBaseUrl(input: string | undefined, fallback: string): string {
+  let u = (input ?? "").trim();
+  if (!u) u = fallback;
+  if (!u) return u;
+  if (!/^https?:\/\//i.test(u)) u = `http://${u}`;
+  return u.replace(/\/+$/, "");
+}
+
+export interface ModelChoiceResult {
+  model: string;
+  known: boolean;
+  /** Non-fatal advisory (provider mismatch or uncatalogued id). */
+  warning?: string;
+  /** "Did you mean" candidates when the typed id is unrecognized. */
+  suggestions: string[];
+}
+
+/**
+ * Resolve the default model from a (possibly blank) typed value for a provider:
+ *  - blank → the provider's recommended model
+ *  - known id → accepted (warns when it routes to a different provider)
+ *  - unknown id → accepted but flagged with "did you mean" suggestions
+ */
+export function chooseDefaultModel(typed: string | undefined, provider: ProviderName): ModelChoiceResult {
+  const t = (typed ?? "").trim();
+  if (!t) {
+    const rec = recommendedModel(provider) ?? "";
+    return { model: rec, known: !!findCatalogEntry(rec), suggestions: [] };
+  }
+  const v = validateModelId(t, provider);
+  if (v.known) {
+    const warning =
+      v.providerMatch === false ? `Note: '${t}' routes to ${v.entry!.provider}, not ${provider}.` : undefined;
+    return { model: t, known: true, warning, suggestions: [] };
+  }
+  return {
+    model: t,
+    known: false,
+    warning: `'${t}' is not in the model catalog (it may still work).`,
+    suggestions: suggestModels(t),
+  };
+}
+
+/** Top-N recommended catalog rows for a provider, as `id — note` display lines. */
+export function recommendedModelsFor(provider: ProviderName, n = 5): string[] {
+  return catalogForProvider(provider)
+    .slice(0, n)
+    .map(e => `${e.id}${e.note ? ` — ${e.note}` : ""}`);
+}
+
+/** Human list of providers that are configured in a config object. */
+export function buildEnabledProviders(config: Config): string[] {
+  const enabled: string[] = [];
+  const cfg = config as Config & { openaiBaseUrl?: string };
+  if (cfg.providers?.anthropic || cfg.oauth?.anthropic) enabled.push("anthropic");
+  if (cfg.providers?.openai || cfg.oauth?.openai) enabled.push("openai");
+  if (cfg.providers?.gemini || cfg.oauth?.gemini) enabled.push("gemini");
+  if (cfg.ollamaBaseUrl) enabled.push(`ollama(${cfg.ollamaBaseUrl})`);
+  if (cfg.openaiBaseUrl) enabled.push(`openai-compatible(${cfg.openaiBaseUrl})`);
+  return enabled;
+}
+
+/**
+ * Build the post-save summary lines: default model + the provider it routes to,
+ * catalog metadata when known, and the enabled-provider list.
+ */
+export function buildSetupSummary(config: Config): string[] {
+  const lines: string[] = [];
+  const model = config.defaultModel;
+  const provider = resolveProvider(model);
+  const entry = findCatalogEntry(model);
+  const meta = entry
+    ? ` (${entry.contextWindow ? `${Math.round(entry.contextWindow / 1000)}k ctx` : "ctx ?"}${entry.reasoning ? ", reasoning" : ""})`
+    : "";
+  lines.push(`Default model: ${model} → ${provider}${meta}`);
+  const enabled = buildEnabledProviders(config);
+  lines.push(`Enabled providers: ${enabled.join(", ") || "None"}`);
+  return lines;
+}

package/src/commands/setup.ts

@@ -0,0 +1,190 @@
+import { createInterface } from "node:readline/promises";
+import { saveGlobalConfig, readGlobalConfig, type Config } from "../agent/state";
+import {
+  interactiveLogin,
+  getStoredOAuth,
+  OAUTH_FLOW_REGISTRY,
+  openInBrowser,
+  type AuthProvider,
+  type OAuthController,
+} from "../auth";
+import {
+  normalizeBaseUrl,
+  chooseDefaultModel,
+  recommendedModelsFor,
+  buildSetupSummary,
+} from "./setup-helpers";
+
+/** Print a model choice's advisory warning + "did you mean" suggestions, if any. */
+function reportModelChoice(r: { warning?: string; suggestions: string[] }): void {
+  if (r.warning) console.log(`  ${r.warning}`);
+  if (r.suggestions.length) console.log(`  Did you mean: ${r.suggestions.join(", ")}?`);
+}
+
+type ProviderChoice = "anthropic" | "openai" | "gemini" | "ollama" | "lmstudio" | "openai-compatible";
+
+const DEFAULT_MODELS: Record<ProviderChoice, string> = {
+  anthropic: "claude-3-5-sonnet-20241022",
+  openai: "gpt-4o",
+  gemini: "gemini-2.0-flash",
+  ollama: "ollama/llama3.1:8b",
+  lmstudio: "openai/local-model",
+  "openai-compatible": "openai/local-model",
+};
+
+const DEFAULT_BASE_URLS: Partial<Record<ProviderChoice, string>> = {
+  ollama: "http://localhost:11434",
+  lmstudio: "http://localhost:1234/v1",
+  "openai-compatible": "http://localhost:8000/v1",
+};
+
+async function listOllamaModels(baseUrl: string): Promise<string[]> {
+  try {
+    const r = await fetch(`${baseUrl}/api/tags`, { signal: AbortSignal.timeout(2000) });
+    if (!r.ok) return [];
+    const data = (await r.json()) as { models?: { name: string }[] };
+    return (data.models ?? []).map(m => m.name);
+  } catch {
+    return [];
+  }
+}
+
+async function listOpenAiCompatibleModels(baseUrl: string, apiKey?: string): Promise<string[]> {
+  try {
+    const r = await fetch(`${baseUrl}/models`, {
+      headers: apiKey ? { authorization: `Bearer ${apiKey}` } : {},
+      signal: AbortSignal.timeout(2000),
+    });
+    if (!r.ok) return [];
+    const data = (await r.json()) as { data?: { id: string }[] };
+    return (data.data ?? []).map(m => m.id);
+  } catch {
+    return [];
+  }
+}
+
+export async function runSetupCommand(): Promise<void> {
+  const current = await readGlobalConfig();
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  console.log("\n=== @jeo-code CLI Configuration (joc setup) ===");
+  console.log("Configure providers, API keys / OAuth tokens, and default model.\n");
+
+  console.log("Available provider types:");
+  console.log("  1) anthropic           — Claude (API key or OAuth bearer)");
+  console.log("  2) openai              — GPT (API key or OAuth bearer)");
+  console.log("  3) gemini              — Google AI Studio (API key or OAuth bearer)");
+  console.log("  4) ollama              — local Ollama (no auth)");
+  console.log("  5) lmstudio            — local LM Studio (OpenAI-compatible)");
+  console.log("  6) openai-compatible   — custom OpenAI-compatible (vLLM, llama-cpp-server, ...)");
+  console.log("  7) skip                — keep existing values, just change defaults\n");
+
+  const sel = (await rl.question("Configure which provider? [1-7]: ")).trim();
+  const map: Record<string, ProviderChoice | "skip"> = {
+    "1": "anthropic", "2": "openai", "3": "gemini",
+    "4": "ollama",    "5": "lmstudio", "6": "openai-compatible",
+    "7": "skip",
+  };
+  const choice = map[sel] ?? "skip";
+
+  const next: Config = JSON.parse(JSON.stringify(current)) as Config;
+  next.providers = next.providers || {};
+  next.oauth = next.oauth || {};
+
+  if (choice === "anthropic" || choice === "openai" || choice === "gemini") {
+    const authMode = (
+      await rl.question("Auth mode: (b)rowser OAuth login, (t)oken paste, or api (k)ey? [b]: ")
+    ).trim().toLowerCase();
+    if (authMode === "t") {
+      const tok = await rl.question(`${choice} OAuth bearer token: `);
+      if (tok.trim()) next.oauth[choice] = tok.trim();
+    } else if (authMode === "k") {
+      const key = await rl.question(`${choice} API key [${current.providers[choice] ? "********" : "None"}]: `);
+      if (key.trim()) next.providers[choice] = key.trim();
+    } else {
+      const flow = OAUTH_FLOW_REGISTRY[choice as AuthProvider];
+      if (!flow.verifiedEndToEnd && flow.note) console.log(`Note: ${flow.note}`);
+      const ctrl: OAuthController = {
+        onAuth: ({ url, instructions }) => {
+          console.log(`Opening browser:\n  ${url}\n`);
+          if (instructions) console.log(instructions + "\n");
+          void openInBrowser(url);
+        },
+        onProgress: msg => console.log(`  … ${msg}`),
+        onManualCodeInput: async () =>
+          (await rl.question("Paste redirect URL or code (or wait for the browser callback): ")).trim(),
+      };
+      try {
+        const { email } = await interactiveLogin(choice as AuthProvider, ctrl);
+        const stored = await getStoredOAuth(choice as AuthProvider);
+        if (stored) next.oauth[choice] = stored;
+        console.log(`[SUCCESS] OAuth login complete for ${choice}${email ? ` (${email})` : ""}.`);
+      } catch (err) {
+        console.log(`[FAILED] OAuth login: ${(err as Error).message}`);
+        console.log("Falling back — you can paste an API key instead.");
+        const key = await rl.question(`${choice} API key [skip]: `);
+        if (key.trim()) next.providers[choice] = key.trim();
+      }
+    }
+    console.log(`\nRecommended ${choice} models:`);
+    for (const m of recommendedModelsFor(choice)) console.log(`  - ${m}`);
+    const dm = await rl.question(`Default model for ${choice} [${recommendedModelsFor(choice)[0]?.split(" ")[0] ?? DEFAULT_MODELS[choice]}]: `);
+    const picked = chooseDefaultModel(dm, choice);
+    reportModelChoice(picked);
+    next.defaultModel = picked.model || DEFAULT_MODELS[choice];
+  } else if (choice === "ollama") {
+    const url = await rl.question(`Ollama base URL [${current.ollamaBaseUrl || DEFAULT_BASE_URLS.ollama}]: `);
+    next.ollamaBaseUrl = normalizeBaseUrl(url, current.ollamaBaseUrl || DEFAULT_BASE_URLS.ollama!);
+    console.log(`Probing models at ${next.ollamaBaseUrl} …`);
+    const models = await listOllamaModels(next.ollamaBaseUrl!);
+    if (models.length) {
+      console.log("Detected local Ollama models:");
+      models.slice(0, 20).forEach((m, i) => console.log(`  - ${m}`));
+      const def = await rl.question(`Default model (ollama/<name>) [${"ollama/" + (models[0] ?? "llama3.1:8b")}]: `);
+      next.defaultModel = def.trim() || `ollama/${models[0] ?? "llama3.1:8b"}`;
+      reportModelChoice(chooseDefaultModel(next.defaultModel, "ollama"));
+    } else {
+      console.log("  (no models detected — Ollama not reachable, defaulting to llama3.1:8b)");
+      const picked = chooseDefaultModel(await rl.question(`Default model [${DEFAULT_MODELS.ollama}]: `), "ollama");
+      reportModelChoice(picked);
+      next.defaultModel = picked.model || DEFAULT_MODELS.ollama;
+    }
+  } else if (choice === "lmstudio" || choice === "openai-compatible") {
+    const dflt = DEFAULT_BASE_URLS[choice]!;
+    const url = normalizeBaseUrl(await rl.question(`Base URL [${dflt}]: `), dflt);
+    const key = (await rl.question(`API key (optional, blank for none): `)).trim();
+    // Reuse the openai slot for compat (loop.ts treats OpenAI URL when openai key is set).
+    // To not collide, keep an explicit override field via env-style.
+    next.providers.openai = key || next.providers.openai;
+    process.env.OPENAI_BASE_URL = url; // session hint
+    console.log(`Probing models at ${url} …`);
+    const models = await listOpenAiCompatibleModels(url, key);
+    if (models.length) {
+      console.log("Detected models:");
+      models.slice(0, 20).forEach(m => console.log(`  - ${m}`));
+      const def = await rl.question(`Default model (openai/<name>) [openai/${models[0]}]: `);
+      next.defaultModel = def.trim() || `openai/${models[0]}`;
+      reportModelChoice(chooseDefaultModel(next.defaultModel, "openai"));
+    } else {
+      console.log("  (no models detected — endpoint not reachable yet)");
+      const picked = chooseDefaultModel(await rl.question(`Default model [${DEFAULT_MODELS[choice]}]: `), "openai");
+      reportModelChoice(picked);
+      next.defaultModel = picked.model || DEFAULT_MODELS[choice];
+    }
+    // Persist base URL by writing it to the config via a non-typed field — adopt a small extension.
+    (next as Config & { openaiBaseUrl?: string }).openaiBaseUrl = url;
+  }
+
+  const level = (await rl.question(`Thinking level (low/medium/high) [${current.thinkingLevel || "medium"}]: `)).trim();
+  next.thinkingLevel = (level || current.thinkingLevel || "medium") as "low" | "medium" | "high";
+
+  rl.close();
+
+  // Drop empty oauth/providers to keep config tidy.
+  if (next.oauth && !next.oauth.anthropic && !next.oauth.openai && !next.oauth.gemini) delete next.oauth;
+
+  await saveGlobalConfig(next);
+  console.log("\n[SUCCESS] Configuration saved to ~/.joc/config.json");
+  for (const line of buildSetupSummary(next)) console.log(line);
+  console.log("");
+}

package/src/commands/skills.ts

@@ -0,0 +1,38 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { SKILLS, getSkill, formatSkill, skillNames } from "../skills/catalog";
+import { getLocalJocDir } from "../agent/state";
+
+export async function runSkillsCommand(args: string[] = []): Promise<void> {
+  // `joc skills --write [dir]` materializes bundled skill docs to disk (gjc-style SKILL.md files).
+  if (args[0] === "--write") {
+    const cwd = process.cwd();
+    const dir = args[1] ? path.resolve(cwd, args[1]) : path.join(getLocalJocDir(cwd), "skills");
+    await fs.mkdir(dir, { recursive: true });
+    for (const s of SKILLS) {
+      const file = path.join(dir, `${s.name}.md`);
+      await fs.writeFile(file, `# ${s.name}\n\n${formatSkill(s)}\n`, "utf-8");
+    }
+    console.log(`Wrote ${SKILLS.length} skill docs to ${dir}`);
+    return;
+  }
+
+  const name = args[0];
+  if (name) {
+    const skill = getSkill(name);
+    if (!skill) {
+      console.log(`Unknown skill: ${name}\nAvailable: ${skillNames().join(", ")}`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log(formatSkill(skill));
+    return;
+  }
+
+  console.log("\n=== joc skills ===");
+  console.log("Bundled workflow skills (run 'joc skills <name>' for details, --write to export):\n");
+  for (const s of SKILLS) {
+    console.log(`  ${s.name.padEnd(16)} ${s.summary}`);
+  }
+  console.log("");
+}