@pasko70/pibo 1.7.7 → 1.7.9

package/dist/debug/index.js

@@ -52,6 +52,10 @@ export async function runDebugCli(argv = process.argv) {
             await runDebugRuns(args.slice(1));
             return;
         }
+        if (args[0] === "resources") {
+            await runDebugResources(args.slice(1));
+            return;
+        }
         if (args[0] === "signals") {
             await runDebugSignals(args.slice(1));
             return;
@@ -77,6 +81,19 @@ export async function runDebugCli(argv = process.argv) {
         process.exitCode = 1;
     }
 }
+async function runDebugResources(args) {
+    if (args[0] === "--help" || args[0] === "-h") {
+        printDebugResourcesDiscovery();
+        return;
+    }
+    const options = parseOptions(args);
+    const { collectGatewayResourceSnapshot, renderGatewayResourceSnapshotText } = await import("../core/gateway-resource-guard.js");
+    const snapshot = await collectGatewayResourceSnapshot();
+    if (options.json)
+        console.log(JSON.stringify(snapshot, null, 2));
+    else
+        console.log(renderGatewayResourceSnapshotText(snapshot));
+}
 async function runDebugDb(args) {
     if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
         printDebugDbDiscovery();
@@ -1007,6 +1024,7 @@ Commands:
   failures List failed tool calls and trace/session errors
   jobs     Inspect durable Pibo jobs and DLQ
   runs     Inspect durable yielded runs
+  resources Show gateway memory reserve, related child processes, and heavy daemons
   signals  Inspect live session signal snapshots through Chat Web APIs
   telemetry Inspect runtime observability telemetry
   web      Inspect browser render state via CDP
@@ -1019,12 +1037,34 @@ Next:
   pibo debug messages <pibo-session-id> list
   pibo debug trace <pibo-session-id> --running-only
   pibo debug events stream --topic pibo.output
+  pibo debug resources --json
   pibo debug signals tree ps_...
   pibo debug telemetry sessions --active
   pibo debug web targets
   pibo debug pty run -- pibo tui:sessions --demo
 `);
 }
+function printDebugResourcesDiscovery() {
+    console.log(`pibo debug resources - inspect gateway resource guard state
+
+Usage:
+  pibo debug resources [--json]
+
+Reports:
+  Gateway RSS/heap headroom, host free-memory reserve, direct child processes, and known heavy local daemons such as ComfyUI or Unity when process listing is available.
+
+Environment:
+  PIBO_GATEWAY_RESOURCE_GUARD=warn|block|off
+  PIBO_GATEWAY_MIN_FREE_MEMORY_BYTES=<bytes>
+  PIBO_GATEWAY_MIN_HEAP_AVAILABLE_BYTES=<bytes>
+  PIBO_GATEWAY_MAX_RSS_BYTES=<bytes>
+  PIBO_GATEWAY_KNOWN_DAEMON_WARNING_RSS_BYTES=<bytes>
+
+Next:
+  pibo debug resources --json
+  pibo compute health --json
+`);
+}
 function printDebugSignalsDiscovery() {
     console.log(`pibo debug signals - inspect live Session Signal snapshots
 

package/dist/mcp/output.js

@@ -50,6 +50,17 @@ export function truncateToolDescription(description, maxLength = TOOL_DESCRIPTIO
         return normalized;
     return `${normalized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
 }
+/**
+ * Return an info-view summary without generated OpenAPI error-response noise.
+ */
+export function summarizeToolDescriptionForInfo(description) {
+    if (!description)
+        return undefined;
+    const withoutErrorResponses = description
+        .replace(/\s*Error Responses:\s*[\s\S]*$/i, '')
+        .trim();
+    return truncateToolDescription(withoutErrorResponses);
+}
 /**
  * Format server list for display
  */
@@ -140,15 +151,19 @@ export function formatServerDetails(serverName, config, tools, withDescriptions
         lines.push(`  ${color(tool.name, colors.green)}`);
         const toolSummary = withDescriptions
             ? tool.description
-            : truncateToolDescription(tool.description);
+            : summarizeToolDescriptionForInfo(tool.description);
         if (toolSummary) {
             lines.push(`    ${color(toolSummary, colors.dim)}`);
         }
         // Show parameters from schema
         const schema = tool.inputSchema;
-        if (schema.properties) {
-            lines.push(`    ${color('Parameters:', colors.yellow)}`);
-            for (const [name, prop] of Object.entries(schema.properties)) {
+        const parameters = Object.entries(schema.properties ?? {});
+        lines.push(`    ${color('Parameters:', colors.yellow)}`);
+        if (parameters.length === 0) {
+            lines.push(`      ${color('No parameters', colors.dim)}`);
+        }
+        else {
+            for (const [name, prop] of parameters) {
                 const required = schema.required?.includes(name)
                     ? 'required'
                     : 'optional';

package/dist/providers/openai-gpt56.js

@@ -0,0 +1,153 @@
+import { getModels } from "@mariozechner/pi-ai";
+import { getOAuthProvider } from "@mariozechner/pi-ai/oauth";
+export const OPENAI_PROVIDER_ID = "openai";
+export const OPENAI_RESPONSES_API = "openai-responses";
+export const OPENAI_BASE_URL = "https://api.openai.com/v1";
+export const OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
+export const OPENAI_CODEX_PROVIDER_ID = "openai-codex";
+export const OPENAI_CODEX_RESPONSES_API = "openai-codex-responses";
+export const OPENAI_CODEX_BASE_URL = "https://chatgpt.com/backend-api";
+const OPENAI_GPT_56_CONTEXT_WINDOW = 1_050_000;
+const OPENAI_CODEX_GPT_56_CONTEXT_WINDOW = 272_000;
+const GPT_56_MAX_TOKENS = 128_000;
+export const OPENAI_GPT_56_MODELS = [
+    {
+        id: "gpt-5.6",
+        name: "GPT-5.6 (Sol alias)",
+        cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 6.25 },
+    },
+    {
+        id: "gpt-5.6-sol",
+        name: "GPT-5.6 Sol",
+        cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 6.25 },
+    },
+    {
+        id: "gpt-5.6-terra",
+        name: "GPT-5.6 Terra",
+        cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 3.125 },
+    },
+    {
+        id: "gpt-5.6-luna",
+        name: "GPT-5.6 Luna",
+        cost: { input: 1, output: 6, cacheRead: 0.1, cacheWrite: 1.25 },
+    },
+];
+const OPENAI_GPT_56_MODEL_IDS = new Set(OPENAI_GPT_56_MODELS.map((model) => model.id));
+export function getBuiltInOpenAiModels() {
+    return getBuiltInProviderModels(OPENAI_PROVIDER_ID);
+}
+export function getBuiltInOpenAiCodexModels() {
+    return getBuiltInProviderModels(OPENAI_CODEX_PROVIDER_ID);
+}
+export function buildOpenAiGpt56Models(baseModels = getBuiltInOpenAiModels()) {
+    return buildProviderGpt56Models({
+        providerId: OPENAI_PROVIDER_ID,
+        api: OPENAI_RESPONSES_API,
+        baseUrl: OPENAI_BASE_URL,
+        contextWindow: OPENAI_GPT_56_CONTEXT_WINDOW,
+        thinkingLevelMap: { off: null, xhigh: "xhigh" },
+        baseModels,
+        modelCost: (model) => model.cost,
+    });
+}
+export function buildOpenAiCodexGpt56Models(baseModels = getBuiltInOpenAiCodexModels()) {
+    return buildProviderGpt56Models({
+        providerId: OPENAI_CODEX_PROVIDER_ID,
+        api: OPENAI_CODEX_RESPONSES_API,
+        baseUrl: OPENAI_CODEX_BASE_URL,
+        contextWindow: OPENAI_CODEX_GPT_56_CONTEXT_WINDOW,
+        thinkingLevelMap: { xhigh: "xhigh", minimal: "low" },
+        baseModels,
+        modelCost: (model) => ({ ...model.cost, cacheWrite: 0 }),
+    });
+}
+export function registerOpenAiGpt56Models(modelRegistry, options = {}) {
+    const baseOpenAiModels = options.baseOpenAiModels ?? getBuiltInOpenAiModels();
+    const openAiModels = buildOpenAiGpt56Models(baseOpenAiModels);
+    const openAiAdded = countMissingGpt56Models(baseOpenAiModels, OPENAI_PROVIDER_ID);
+    modelRegistry.registerProvider(OPENAI_PROVIDER_ID, {
+        baseUrl: OPENAI_BASE_URL,
+        api: OPENAI_RESPONSES_API,
+        apiKey: OPENAI_API_KEY_ENV,
+        models: openAiModels,
+    });
+    const baseOpenAiCodexModels = options.baseOpenAiCodexModels ?? getBuiltInOpenAiCodexModels();
+    const openAiCodexModels = buildOpenAiCodexGpt56Models(baseOpenAiCodexModels);
+    const openAiCodexAdded = countMissingGpt56Models(baseOpenAiCodexModels, OPENAI_CODEX_PROVIDER_ID);
+    const openAiCodexOAuth = getOpenAiCodexOAuthConfig();
+    modelRegistry.registerProvider(OPENAI_CODEX_PROVIDER_ID, {
+        name: openAiCodexOAuth.name,
+        baseUrl: OPENAI_CODEX_BASE_URL,
+        api: OPENAI_CODEX_RESPONSES_API,
+        oauth: openAiCodexOAuth,
+        models: openAiCodexModels,
+    });
+    return {
+        registered: true,
+        providers: 2,
+        models: openAiModels.length + openAiCodexModels.length,
+        added: openAiAdded + openAiCodexAdded,
+    };
+}
+export function findOpenAiGpt56Model(modelRegistry, model) {
+    if (!model?.provider || !model.id)
+        return undefined;
+    if (model.provider !== OPENAI_PROVIDER_ID && model.provider !== OPENAI_CODEX_PROVIDER_ID)
+        return undefined;
+    if (!OPENAI_GPT_56_MODEL_IDS.has(model.id))
+        return undefined;
+    return modelRegistry.find(model.provider, model.id);
+}
+function getBuiltInProviderModels(providerId) {
+    try {
+        return getModels(providerId);
+    }
+    catch {
+        return [];
+    }
+}
+function buildProviderGpt56Models(options) {
+    const providerBaseModels = options.baseModels
+        .filter((model) => model.provider === options.providerId)
+        .map(cloneModel);
+    const existingIds = new Set(providerBaseModels.map((model) => model.id));
+    const additions = OPENAI_GPT_56_MODELS
+        .filter((model) => !existingIds.has(model.id))
+        .map((model) => openAiGpt56ModelToRegistryModel(model, options));
+    return [...providerBaseModels, ...additions];
+}
+function countMissingGpt56Models(baseModels, providerId) {
+    const existingIds = new Set(baseModels.filter((model) => model.provider === providerId).map((model) => model.id));
+    return OPENAI_GPT_56_MODELS.filter((model) => !existingIds.has(model.id)).length;
+}
+function cloneModel(model) {
+    return {
+        ...model,
+        input: [...model.input],
+        cost: { ...model.cost },
+        headers: model.headers ? { ...model.headers } : undefined,
+        compat: model.compat ? { ...model.compat } : undefined,
+    };
+}
+function openAiGpt56ModelToRegistryModel(model, options) {
+    return {
+        id: model.id,
+        name: model.name,
+        api: options.api,
+        provider: options.providerId,
+        baseUrl: options.baseUrl,
+        reasoning: true,
+        thinkingLevelMap: options.thinkingLevelMap,
+        input: ["text", "image"],
+        cost: options.modelCost(model),
+        contextWindow: options.contextWindow,
+        maxTokens: GPT_56_MAX_TOKENS,
+    };
+}
+function getOpenAiCodexOAuthConfig() {
+    const provider = getOAuthProvider(OPENAI_CODEX_PROVIDER_ID);
+    if (!provider)
+        throw new Error("OpenAI Codex OAuth provider is unavailable.");
+    const { id: _id, ...oauth } = provider;
+    return oauth;
+}

package/dist/ralph/cli.js

@@ -4,6 +4,7 @@ import { createDefaultPiboRalphStore } from './store.js';
 import { createBuiltInRalphStopConditions } from './stopping.js';
 import { DEFAULT_PIBO_PROFILE_NAME } from '../plugins/builtin.js';
 import { getRalphJobTemplate, listRalphJobTemplates } from './templates.js';
+import { parsePiboThinkingLevel } from '../core/thinking.js';
 function printDiscovery() {
     console.log(`pibo ralph
 
@@ -34,6 +35,49 @@ function printJson(value) { console.log(JSON.stringify(value, null, 2)); }
 function maxIterations(value) { if (value === undefined)
     return undefined; const parsed = Number(value); if (!Number.isInteger(parsed) || parsed < 1)
     throw new Error('--max-iterations must be a positive integer'); return parsed; }
+function parseModelOverride(value) {
+    if (value === undefined)
+        return undefined;
+    const slash = value.indexOf('/');
+    if (slash <= 0 || slash === value.length - 1)
+        throw new Error('--model must use provider/model syntax, for example openai/gpt-5');
+    const provider = value.slice(0, slash).trim();
+    const id = value.slice(slash + 1).trim();
+    if (!provider || !id)
+        throw new Error('--model must use provider/model syntax, for example openai/gpt-5');
+    return { provider, id };
+}
+function parseThinkingOverride(value) { return value === undefined ? undefined : parsePiboThinkingLevel(value); }
+function applyRuntimeCreateOptions(input, options) {
+    const modelOverride = parseModelOverride(options.model);
+    const thinkingLevel = parseThinkingOverride(options.thinking);
+    if (modelOverride)
+        input.modelOverride = modelOverride;
+    if (thinkingLevel)
+        input.thinkingLevel = thinkingLevel;
+    if (options.fast !== undefined)
+        input.fastMode = options.fast;
+}
+function applyRuntimePatchOptions(patch, options) {
+    if (options.model !== undefined && options.clearModel)
+        throw new Error('Choose either --model or --clear-model, not both');
+    if (options.thinking !== undefined && options.clearThinking)
+        throw new Error('Choose either --thinking or --clear-thinking, not both');
+    if (options.fast !== undefined && options.clearFast)
+        throw new Error('Choose either --fast/--no-fast or --clear-fast, not both');
+    if (options.clearModel)
+        patch.modelOverride = null;
+    else if (options.model !== undefined)
+        patch.modelOverride = parseModelOverride(options.model);
+    if (options.clearThinking)
+        patch.thinkingLevel = null;
+    else if (options.thinking !== undefined)
+        patch.thinkingLevel = parseThinkingOverride(options.thinking);
+    if (options.clearFast)
+        patch.fastMode = null;
+    else if (options.fast !== undefined)
+        patch.fastMode = options.fast;
+}
 function templatePatch(id) {
     if (!id)
         return {};
@@ -77,18 +121,18 @@ export async function runRalphCli(argv = process.argv) {
     else
         for (const job of jobs)
             console.log(formatRalphJobLine(job)); store.close(); });
-    program.command('add').description('Create a Ralph job').option('--template <id>', 'Built-in job template id').option('--prompt <text>', 'Task prompt').option('--name <name>', 'Job name').option('--description <text>', 'Job description').option('--profile <profile>', 'Agent profile', DEFAULT_PIBO_PROFILE_NAME).option('--room <room-id>', 'Target room id').option('--default-chat', 'Target the shared default chat').option('--max-iterations <n>', 'Stop after n completed run attempts')
+    program.command('add').description('Create a Ralph job').option('--template <id>', 'Built-in job template id').option('--prompt <text>', 'Task prompt').option('--name <name>', 'Job name').option('--description <text>', 'Job description').option('--profile <profile>', 'Agent profile', DEFAULT_PIBO_PROFILE_NAME).option('--room <room-id>', 'Target room id').option('--default-chat', 'Target the shared default chat').option('--max-iterations <n>', 'Stop after n completed run attempts').option('--model <provider/model>', 'Runtime model override, for example openai/gpt-5').option('--thinking <level>', 'Runtime thinking level override: off, minimal, low, medium, high, xhigh').option('--fast', 'Enable runtime fast mode').option('--no-fast', 'Disable runtime fast mode')
         .option('--start', 'Start immediately').option('--json', 'Print JSON').action((options) => { const base = templatePatch(options.template); const prompt = options.prompt ?? base.prompt; if (typeof prompt !== 'string' || !prompt.trim())
-        throw new Error('Choose --template <id> or provide --prompt <text>'); const store = createDefaultPiboRalphStore({ path: program.opts().store }); const job = store.createJob({ name: options.name ?? base.name, description: options.description ?? base.description, enabled: options.start === true, target: targetFromOptions(options), profile: options.profile, prompt, maxIterations: options.maxIterations !== undefined ? maxIterations(options.maxIterations) : typeof base.maxIterations === 'number' ? base.maxIterations : undefined, stopPolicy: base.stopPolicy ?? undefined }); if (options.json)
+        throw new Error('Choose --template <id> or provide --prompt <text>'); const input = { name: options.name ?? base.name, description: options.description ?? base.description, enabled: options.start === true, target: targetFromOptions(options), profile: options.profile, prompt, maxIterations: options.maxIterations !== undefined ? maxIterations(options.maxIterations) : typeof base.maxIterations === 'number' ? base.maxIterations : undefined, stopPolicy: base.stopPolicy ?? undefined }; applyRuntimeCreateOptions(input, options); const store = createDefaultPiboRalphStore({ path: program.opts().store }); const job = store.createJob(input); if (options.json)
         printJson(job);
     else
         console.log(`${job.id}\t${job.enabled ? 'running' : 'stopped'}\t${job.name}`); store.close(); });
-    program.command('edit').argument('<id>', 'Ralph job id').description('Update a Ralph job').option('--template <id>', 'Apply a built-in job template before explicit overrides').option('--prompt <text>', 'Task prompt').option('--name <name>', 'Job name').option('--description <text>', 'Job description').option('--profile <profile>', 'Agent profile').option('--room <room-id>', 'Target room id').option('--default-chat', 'Target the shared default chat').option('--max-iterations <n>', 'Stop after n completed run attempts').option('--json', 'Print JSON').action((id, options) => { const store = createDefaultPiboRalphStore({ path: program.opts().store }); const patch = { ...templatePatch(options.template) }; if (options.name !== undefined)
+    program.command('edit').argument('<id>', 'Ralph job id').description('Update a Ralph job').option('--template <id>', 'Apply a built-in job template before explicit overrides').option('--prompt <text>', 'Task prompt').option('--name <name>', 'Job name').option('--description <text>', 'Job description').option('--profile <profile>', 'Agent profile').option('--room <room-id>', 'Target room id').option('--default-chat', 'Target the shared default chat').option('--max-iterations <n>', 'Stop after n completed run attempts').option('--model <provider/model>', 'Set runtime model override, for example openai/gpt-5').option('--clear-model', 'Clear runtime model override').option('--thinking <level>', 'Set runtime thinking level override: off, minimal, low, medium, high, xhigh').option('--clear-thinking', 'Clear runtime thinking level override').option('--fast', 'Enable runtime fast mode').option('--no-fast', 'Disable runtime fast mode').option('--clear-fast', 'Clear runtime fast mode override').option('--json', 'Print JSON').action((id, options) => { const store = createDefaultPiboRalphStore({ path: program.opts().store }); const patch = { ...templatePatch(options.template) }; if (options.name !== undefined)
         patch.name = options.name; if (options.description !== undefined)
         patch.description = options.description; if (options.profile !== undefined)
         patch.profile = options.profile; if (options.prompt !== undefined)
         patch.prompt = options.prompt; if (options.maxIterations !== undefined)
-        patch.maxIterations = maxIterations(options.maxIterations); const target = maybeTargetFromOptions(options); if (target)
+        patch.maxIterations = maxIterations(options.maxIterations); applyRuntimePatchOptions(patch, options); const target = maybeTargetFromOptions(options); if (target)
         patch.target = target; if (Object.keys(patch).length === 0)
         throw new Error('No Ralph job update fields provided'); const job = store.updateJob(id, patch); if (!job)
         throw new Error('Ralph job not found'); if (options.json)
@@ -145,7 +189,7 @@ export async function runRalphCli(argv = process.argv) {
     else
         for (const run of runs)
             console.log(formatRalphRunLine(run)); store.close(); });
-    if (argv.length <= 2 || argv.includes('--help') || argv.includes('-h')) {
+    if (argv.length <= 2 || (argv.length === 3 && (argv[2] === '--help' || argv[2] === '-h'))) {
         printDiscovery();
         return;
     }

package/dist/session-ui/terminalRows.js

@@ -129,6 +129,9 @@ function createToolRowCandidate(node, turnId) {
         const row = createCommandToolRow(node, command);
         return { row, turnId, exploring: undefined };
     }
+    if (isWebSearchToolName(node.title)) {
+        return { row: createWebSearchToolRow(node), turnId };
+    }
     const image = classifyImageTool(node);
     if (image) {
         const row = createImageToolRow(node, image);
@@ -161,6 +164,38 @@ function createToolRowCandidate(node, turnId) {
     const exploring = classifyExploringTool(node);
     return { row, turnId, exploring };
 }
+function createWebSearchToolRow(node) {
+    const status = mapStatus(node.status);
+    const query = webSearchQuery(node);
+    const sourceCount = webSearchSourceCount(node.output);
+    const lines = [
+        {
+            prefix: "bullet",
+            tokens: [token(webSearchVerb(node.status), toneForStatus(node.status), node.status === "error" ? "bold" : "semibold")],
+        },
+    ];
+    if (query) {
+        lines.push({ prefix: "detail", tokens: [token(`query: ${JSON.stringify(query)}`, "cyan")] });
+    }
+    if (node.status === "done" && sourceCount !== undefined) {
+        lines.push({ prefix: "detail", tokens: [token(`sources: ${sourceCount}`, "dim")] });
+    }
+    if (node.status === "error" && node.error) {
+        lines.push({ prefix: "detail", tokens: [token(node.error, "red")] });
+    }
+    return {
+        id: node.id,
+        kind: "tool.call",
+        status,
+        errorKind: node.status === "error" ? "tool" : undefined,
+        lines,
+        sourceNodeIds: [node.id],
+        input: node.input,
+        output: node.output,
+        error: node.error,
+        expandable: node.input !== undefined || node.output !== undefined || Boolean(node.error),
+    };
+}
 function createImageToolRow(node, image) {
     const status = mapStatus(node.status);
     const detailLabel = image.path ? `Path: ${image.path}` : image.artifactId ? `Artifact: ${image.artifactId}` : image.query ? `Query: ${image.query}` : image.mimeType ? `Type: ${image.mimeType}` : "Image content returned";
@@ -962,6 +997,30 @@ function isShellToolName(name) {
         normalized === "bash" ||
         normalized === "terminal");
 }
+function isWebSearchToolName(name) {
+    return (name ?? "").trim().toLowerCase() === "web_search";
+}
+function webSearchVerb(status) {
+    if (status === "running")
+        return "Searching web";
+    if (status === "error")
+        return "Web search failed";
+    return "Searched web";
+}
+function webSearchQuery(node) {
+    const input = isRecord(node.input) ? node.input : undefined;
+    const output = isRecord(node.output) ? node.output : undefined;
+    return stringValue(input?.query) ?? stringValue(output?.query) ?? stringValue(node.summary);
+}
+function webSearchSourceCount(output) {
+    if (!isRecord(output))
+        return undefined;
+    const explicit = output.sourceCount ?? output.sourcesCount;
+    if (typeof explicit === "number" && Number.isFinite(explicit))
+        return explicit;
+    const sources = output.sources ?? output.citations ?? output.results;
+    return Array.isArray(sources) ? sources.length : undefined;
+}
 function shellCommandValue(value) {
     if (!isRecord(value))
         return undefined;

package/dist/skills/cli.js

@@ -1,14 +1,13 @@
 import { Command } from "commander";
 import { createDefaultPiboPluginRegistry } from "../plugins/builtin.js";
-import { UserSkillManager } from "../user-skills/manager.js";
+import { ScopedUserSkillManager, normalizeUserSkillScope, normalizeWritableUserSkillScope, } from "../user-skills/manager.js";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import os from "node:os";
 function printJson(value) {
     console.log(JSON.stringify(value, null, 2));
 }
 export async function runSkillsCli(argv) {
-    const manager = new UserSkillManager(os.homedir());
+    const manager = new ScopedUserSkillManager();
     const program = new Command();
     program
         .name("pibo skills")
@@ -37,9 +36,10 @@ export async function runSkillsCli(argv) {
     program
         .command("list")
         .description("List user skills managed by this CLI")
+        .option("--scope <scope>", "Skill scope: global, workspace, or all", "all")
         .option("--json", "Print JSON")
         .action((options) => {
-        const skills = manager.list();
+        const skills = manager.list(normalizeUserSkillScope(options.scope));
         if (options.json) {
             printJson(skills);
             return;
@@ -48,24 +48,26 @@ export async function runSkillsCli(argv) {
             console.log("No user skills registered.");
             return;
         }
-        console.log("NAME\t\tENABLED\tSOURCE\t\tDESCRIPTION");
+        console.log("NAME\t\tSCOPE\t\tENABLED\tSOURCE\t\tDESCRIPTION");
         for (const s of skills) {
             const enabled = s.enabled ? "yes" : "no";
-            console.log(`${s.name}\t${enabled}\t\t${s.source}\t${s.description}`);
+            console.log(`${s.name}\t${s.scope ?? "global"}\t${enabled}\t\t${s.source}\t${s.description}`);
         }
     });
     program
         .command("show")
         .description("Show a skill's markdown content")
         .argument("<name>", "Skill name")
-        .action((name) => {
-        const skill = manager.get(name);
+        .option("--scope <scope>", "Skill scope: global, workspace, or all", "all")
+        .action((name, options) => {
+        const scope = normalizeUserSkillScope(options.scope);
+        const skill = manager.get(name, scope);
         if (!skill) {
             console.error(`Skill "${name}" not found.`);
             process.exitCode = 1;
             return;
         }
-        console.log(manager.getSkillMarkdown(skill.id));
+        console.log(manager.getSkillMarkdown(skill.id, scope));
     });
     program
         .command("add")
@@ -73,6 +75,7 @@ export async function runSkillsCli(argv) {
         .argument("<name>", "Skill name (kebab-case)")
         .requiredOption("--file <path>", "Path to markdown file")
         .option("--description <text>", "Short description")
+        .option("--scope <scope>", "Skill scope: global or workspace", "global")
         .action((name, options) => {
         const filePath = resolve(options.file);
         const markdown = readFileSync(filePath, "utf-8");
@@ -80,58 +83,65 @@ export async function runSkillsCli(argv) {
             name,
             description: options.description ?? "",
             markdown,
-        });
-        printJson({ id: skill.id, name: skill.name, enabled: skill.enabled });
+        }, normalizeWritableUserSkillScope(options.scope));
+        printJson({ id: skill.id, name: skill.name, scope: skill.scope, enabled: skill.enabled });
     });
     program
         .command("remove")
         .description("Remove a user skill")
         .argument("<name>", "Skill name")
-        .action((name) => {
-        const skill = manager.get(name);
+        .option("--scope <scope>", "Skill scope: global, workspace, or all", "all")
+        .action((name, options) => {
+        const scope = normalizeUserSkillScope(options.scope);
+        const skill = manager.get(name, scope);
         if (!skill) {
             console.error(`Skill "${name}" not found.`);
             process.exitCode = 1;
             return;
         }
-        manager.remove(skill.id);
+        manager.remove(skill.id, scope);
         console.log(`Removed skill "${skill.name}".`);
     });
     program
         .command("enable")
         .description("Enable a user skill")
         .argument("<name>", "Skill name")
-        .action((name) => {
-        const skill = manager.get(name);
+        .option("--scope <scope>", "Skill scope: global, workspace, or all", "all")
+        .action((name, options) => {
+        const scope = normalizeUserSkillScope(options.scope);
+        const skill = manager.get(name, scope);
         if (!skill) {
             console.error(`Skill "${name}" not found.`);
             process.exitCode = 1;
             return;
         }
-        manager.setEnabled(skill.id, true);
+        manager.setEnabled(skill.id, true, scope);
         console.log(`Enabled skill "${skill.name}".`);
     });
     program
         .command("disable")
         .description("Disable a user skill")
         .argument("<name>", "Skill name")
-        .action((name) => {
-        const skill = manager.get(name);
+        .option("--scope <scope>", "Skill scope: global, workspace, or all", "all")
+        .action((name, options) => {
+        const scope = normalizeUserSkillScope(options.scope);
+        const skill = manager.get(name, scope);
         if (!skill) {
             console.error(`Skill "${name}" not found.`);
             process.exitCode = 1;
             return;
         }
-        manager.setEnabled(skill.id, false);
+        manager.setEnabled(skill.id, false, scope);
         console.log(`Disabled skill "${skill.name}".`);
     });
     program
         .command("install")
         .description("Install a skill from a URL (GitHub or skills.sh)")
         .argument("<url>", "Skill URL")
-        .action(async (url) => {
-        const skill = await manager.installFromUrl(url);
-        printJson({ id: skill.id, name: skill.name, source: skill.source });
+        .option("--scope <scope>", "Skill scope: global or workspace", "global")
+        .action(async (url, options) => {
+        const skill = await manager.installFromUrl(url, normalizeWritableUserSkillScope(options.scope));
+        printJson({ id: skill.id, name: skill.name, scope: skill.scope, source: skill.source });
     });
     if (argv.length <= 2) {
         program.outputHelp();

package/dist/tools/guides.js

@@ -63,6 +63,23 @@ pibo ralph add \\
 
 Explicit options override template fields.
 
+Runtime overrides are optional and apply to sessions created by the job:
+
+\`\`\`bash
+pibo ralph add \\
+  --room "<room-id>" \\
+  --prompt "Use a specific runtime." \\
+  --model openai/gpt-5 \\
+  --thinking high \\
+  --fast \\
+  --json
+
+pibo ralph edit <job-id> --model openai/gpt-5 --thinking medium --no-fast --json
+pibo ralph edit <job-id> --clear-model --clear-thinking --clear-fast --json
+\`\`\`
+
+Use \`--model <provider/model>\`, \`--thinking off|minimal|low|medium|high|xhigh\`, and \`--fast\`/\`--no-fast\` to set runtime options. Use the \`--clear-*\` flags on \`edit\` to return to profile/default runtime behavior.
+
 ## Inspect and Debug
 
 \`\`\`bash