@scira/cli 0.1.6 → 0.1.7

package/dist/agent/harness-agent.js

@@ -5,6 +5,10 @@ import { createClaudeCode } from "@ai-sdk/harness-claude-code";
 import { createCodex } from "@ai-sdk/harness-codex";
 import { createLocalSandbox } from "../providers/harness/local-sandbox.js";
 import { createResearchTools } from "../tools/agent-tools.js";
+import { SKILLS } from "./skills.js";
+// Scira's built-in skills surfaced to the harness runtime (the adapter
+// materializes them natively — e.g. Claude Code writes them as SKILL.md files).
+const HARNESS_SKILLS = SKILLS.map((s) => ({ name: s.name, description: s.summary, content: s.content }));
 /** Resolve a promise but never hang the caller longer than `ms`. Clears the timer when settled so it can't keep the event loop alive (e.g. delaying quit). */
 function withTimeout(p, ms) {
     let timer;
@@ -48,8 +52,14 @@ function buildAgent(provider, config, workspacePath, instructions, runPath) {
     // Cast bridges the project's `ai` Tool type to the harness's bundled-`ai`
     // ToolSet (same runtime shape, different package versions).
     const tools = { multiWebSearch: webSearch, readUrl };
+    // The harness CLI writes relative to its own working directory and has no
+    // knowledge of Scira's run layout, so pin the exact run directory and require
+    // absolute paths for artifacts — otherwise it guesses (e.g. ~/.scira/runs/).
+    const runDir = path.resolve(runPath);
+    const runDirSteer = `\n\nRUN DIRECTORY: Write every run artifact — plan.md, notes.md, sources.jsonl, claims.jsonl, report.md — to this exact absolute path, nowhere else:\n  ${runDir}\nFor example, the report goes to ${runDir}/report.md. Always use the absolute path; do not use a bare "sources.jsonl" or a ".scira/runs/…" path. If a file already exists, Read it before writing (your Write tool requires that) — or edit it in place.`;
     // Positive, authoritative steering pointing at the unique tool name.
-    const fullInstructions = `${instructions}\n\nWEB ACCESS: For any web search use the \`multiWebSearch\` tool and pass 3-5 query variations in a single call (it searches them in parallel). Use \`readUrl\` to read a specific page. These are your only web tools.`;
+    const webSteer = `\n\nWEB ACCESS: For any web search use the \`multiWebSearch\` tool and pass 3-5 query variations in a single call (it searches them in parallel). Use \`readUrl\` to read a specific page. These are your only web tools.`;
+    const fullInstructions = `${instructions}${runDirSteer}${webSteer}`;
     // No `auth`: the bundled CLI authenticates with the user's local login
     // (`claude login` → ~/.claude, `codex login` → ~/.codex). We never pass an
     // API key, so a Pro/Max/ChatGPT subscription session is used as-is.
@@ -65,7 +75,7 @@ function buildAgent(provider, config, workspacePath, instructions, runPath) {
             // Built-in harness web search is always disabled.
             webSearch: false
         });
-    return new HarnessAgent({ harness, sandbox, permissionMode, instructions: fullInstructions, tools });
+    return new HarnessAgent({ harness, sandbox, permissionMode, instructions: fullInstructions, tools, skills: HARNESS_SKILLS });
 }
 /** Settings that, if changed, require rebuilding the session (not just the prompt). */
 function settingsFingerprint(provider, config) {

package/dist/agent/main-agent.js

@@ -26,7 +26,7 @@ You are in plan mode. Explore and plan before making changes.
 - Read-only bash is OK: ls, cat, git status, git log, git diff, find, grep (workspace-relative paths only)
 - When the plan is ready, summarize it and tell the user to type /plan to exit plan mode and begin execution`;
 }
-function instructions(goal, config, options = {}) {
+function instructions(goal, config, options = {}, runPath) {
     const { workspacePath } = options;
     const planMode = resolvePlanMode(options);
     const now = new Date();
@@ -43,12 +43,13 @@ function instructions(goal, config, options = {}) {
 
 PROJECT LAYOUT:
 - Project root (codebase): ${workspacePath}
-- Run harness (.scira/runs/…): plan.md, notes.md, report.md, sources.jsonl, claims.jsonl, todos.json
+- This run's directory: ${runPath ?? "(the active run)"}  ← artifacts live here
+- Run artifacts: plan.md, notes.md, report.md, sources.jsonl, claims.jsonl, todos.json — pass the bare filename (e.g. \`report.md\`) or the absolute path above. Don't guess a \`.scira/runs/…\` path.
 
 FILE TOOLS:
 - readFile / writeFile / editFile route automatically:
-  - Harness files by bare name: plan.md, notes.md, report.md, sources.jsonl → stored under .scira/runs/
-  - Everything else (src/…, package.json, …) → project root
+  - Harness files (plan.md, notes.md, report.md, sources.jsonl, claims.jsonl): pass the BARE filename only — e.g. \`plan.md\`. The tool puts it in this run's directory for you. Never prefix it with a directory, \`.scira\`, \`runs\`, or \`latest\`; those paths are rejected.
+  - Source code / project files (src/…, package.json, …): relative to the project root.
 - Never write source code under .scira. Never put harness files at the project root.
 
 CODING TOOLS:
@@ -63,7 +64,7 @@ When the task involves code:
 - Use editFile for precise changes, writeFile for new source files (paths like src/foo.ts)
 - Run tests/builds with bash; use bash action=background for servers then action=output to check logs
 - Match existing code style and patterns` : "";
-    return `You are Scira AI CLI, made by Zaid Mukaddam, an autonomous research ${workspacePath ? "and coding " : ""}agent.${workspacePath ? " Source code lives at the project root; harness artifacts live under .scira/runs/." : " You operate inside a single run directory on the user's machine."}
+    return `You are Scira AI CLI, made by Zaid Mukaddam, an autonomous research ${workspacePath ? "and coding " : ""}agent.${workspacePath ? ` Source code lives at the project root; run artifacts live in this run's directory${runPath ? ` (${runPath})` : ""}.` : ` You operate inside a single run directory${runPath ? ` (${runPath})` : ""} on the user's machine.`}
 
 Your goal:
 ${goal}
@@ -136,7 +137,7 @@ export async function createResearchAgent(runPath, goal, config, onApprovalRequi
             provider: config.llmProvider,
             config,
             workspacePath: options.workspacePath ?? process.cwd(),
-            instructions: instructions(goal, config, options)
+            instructions: instructions(goal, config, options, runPath)
         });
     }
     const bridge = await createMcpBridge(config);
@@ -149,18 +150,18 @@ export async function createResearchAgent(runPath, goal, config, onApprovalRequi
     const bgContext = options.backgroundTasks ? await options.backgroundTasks.formatContextForAgent() : "";
     const agent = new ToolLoopAgent({
         model: getLanguageModel(config),
-        instructions: instructions(goal, config, options) + bgContext + devtoolsInstructionsBlock(bridge.toolNames),
+        instructions: instructions(goal, config, options, runPath) + bgContext + devtoolsInstructionsBlock(bridge.toolNames),
         tools,
         stopWhen: isLoopFinished()
     });
     return { agent, close: bridge.close };
 }
-function oneShotInstructions(goal, hasDevtools, options = {}) {
+function oneShotInstructions(goal, hasDevtools, options = {}, runPath) {
     const { workspacePath } = options;
     const planMode = resolvePlanMode(options);
     const codingHint = workspacePath ? `
 
-Project root: ${workspacePath}. readFile/writeFile/editFile route code paths to the project root; harness files (plan.md, notes.md, …) stay under .scira/runs/.
+Project root: ${workspacePath}. readFile/writeFile/editFile route code paths to the project root; run artifacts (plan.md, notes.md, …) go in this run's directory${runPath ? ` (${runPath})` : ""} — pass the bare filename or that absolute path.
 - listWorkspaceDir, grepWorkspace, bash (with background tasks), todo
 Use them for code questions, debugging, and implementation tasks.` : "";
     const now = new Date();
@@ -210,7 +211,7 @@ export async function createOneShotAgent(runPath, goal, config, onApprovalRequir
             provider: config.llmProvider,
             config,
             workspacePath: options.workspacePath ?? process.cwd(),
-            instructions: oneShotInstructions(goal, false, options)
+            instructions: oneShotInstructions(goal, false, options, runPath)
         });
     }
     const bridge = await createMcpBridge(config);
@@ -222,7 +223,7 @@ export async function createOneShotAgent(runPath, goal, config, onApprovalRequir
     const bgContext = options.backgroundTasks ? await options.backgroundTasks.formatContextForAgent() : "";
     const agent = new ToolLoopAgent({
         model: getLanguageModel(config),
-        instructions: oneShotInstructions(goal, bridge.toolNames.length > 0, options) + bgContext + devtoolsInstructionsBlock(bridge.toolNames),
+        instructions: oneShotInstructions(goal, bridge.toolNames.length > 0, options, runPath) + bgContext + devtoolsInstructionsBlock(bridge.toolNames),
         tools,
         stopWhen: isLoopFinished()
     });

package/dist/cli/index.js

@@ -29,6 +29,17 @@ import { createMcpBridge } from "../tools/mcp-bridge.js";
 import { saveGlobalMcpConfig } from "../config/load-config.js";
 import { runOAuthFlow } from "../tools/mcp-oauth.js";
 import { initCommand } from "./commands/init.js";
+import { checkForUpdate, formatUpdateNotice } from "../utils/update-check.js";
+// Once per invocation (throttled to a real npm check at most daily): surface an
+// available update. The TUI shows it as an in-app notice; CLI commands print it.
+// Skip for --version/--help so those stay instant (the daily check can spend up
+// to ~3s on the network, and sade prints+exits for these before any command).
+const argv = process.argv.slice(2);
+const wantsUpdateCheck = !argv.some((a) => ["-v", "--version", "-h", "--help"].includes(a));
+const update = wantsUpdateCheck ? await checkForUpdate(pkgVersion) : null;
+const updateNotice = update ? formatUpdateNotice(update) : undefined;
+// The TUI renders the notice in-app, so the finally banner would double it up.
+let noticeShownInApp = false;
 const prog = sade("scira");
 prog
     .version(pkgVersion)
@@ -40,7 +51,8 @@ prog
     const question = opts._.length > 0 ? opts._.join(" ") : undefined;
     const config = await loadConfig();
     if (!question) {
-        await openTuiHome(config);
+        noticeShownInApp = !!updateNotice;
+        await openTuiHome(config, updateNotice);
         return;
     }
     requireLlmKeys(config);
@@ -66,7 +78,8 @@ prog
     const config = await loadConfig();
     const run = await createRun(question, config);
     if (opts.tui) {
-        await openTui(run.path, config);
+        noticeShownInApp = !!updateNotice;
+        await openTui(run.path, config, updateNotice);
     }
     else if (opts.shell) {
         await openShell(run.path, config);
@@ -87,7 +100,8 @@ prog
         await openShell(runPath, config);
     }
     else {
-        await openTui(runPath, config);
+        noticeShownInApp = !!updateNotice;
+        await openTui(runPath, config, updateNotice);
     }
 });
 prog
@@ -132,7 +146,7 @@ prog
     const runPath = await findRun(runId, config);
     let output;
     if (fmt === "md") {
-        output = await Bun.file(`${runPath}/report.md`).text();
+        output = await Bun.file(`${runPath}/report.md`).text().catch(() => "");
     }
     else {
         const { toJson, toCsv } = await import("../export/formatters.js");
@@ -493,3 +507,9 @@ catch (error) {
     console.error(error instanceof Error ? error.message : String(error));
     process.exitCode = 1;
 }
+finally {
+    // Reminder after a CLI command finishes. Skipped when the TUI already
+    // rendered the notice in-app, so we don't show it twice.
+    if (updateNotice && !noticeShownInApp)
+        process.stderr.write(`\n\x1b[2m${updateNotice}\x1b[0m\n`);
+}

package/dist/cli/shell/shell.js

@@ -19,7 +19,7 @@ export async function openShell(runPath, config) {
                     console.log(await renderStatus(runPath));
                     break;
                 case "/plan":
-                    console.log(await Bun.file(getRunPaths(runPath).plan).text());
+                    console.log(await Bun.file(getRunPaths(runPath).plan).text().catch(() => "No plan.md yet."));
                     break;
                 case "/run":
                     await runResearchAgent(runPath, state.goal, config);

package/dist/cli/shell/tui.js

@@ -2,13 +2,13 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { render } from "ink";
 import { SciraApp } from "../../ui/ink/SciraApp.js";
 import { closeAllHarnessSessions } from "../../agent/harness-agent.js";
-export async function openTuiHome(config) {
-    const instance = render(_jsx(SciraApp, { config: config }), { alternateScreen: true, maxFps: 20, exitOnCtrlC: false });
+export async function openTuiHome(config, updateNotice) {
+    const instance = render(_jsx(SciraApp, { config: config, updateNotice: updateNotice }), { alternateScreen: true, maxFps: 20, exitOnCtrlC: false });
     await instance.waitUntilExit();
     await closeAllHarnessSessions();
 }
-export async function openTui(runPath, config) {
-    const instance = render(_jsx(SciraApp, { runPath: runPath, config: config }), { alternateScreen: true, maxFps: 20, exitOnCtrlC: false });
+export async function openTui(runPath, config, updateNotice) {
+    const instance = render(_jsx(SciraApp, { runPath: runPath, config: config, updateNotice: updateNotice }), { alternateScreen: true, maxFps: 20, exitOnCtrlC: false });
     await instance.waitUntilExit();
     await closeAllHarnessSessions();
 }

package/dist/providers/llm/models.js

@@ -42,15 +42,16 @@ async function listXaiModels() {
     if (!key)
         return STATIC_MODELS.xai;
     try {
-        // OpenAI-compatible models endpoint
-        const response = await fetch("https://api.x.ai/v1/models", {
+        // The language-models endpoint returns only text/chat models (it excludes
+        // the image/video/embedding models that /v1/models lists).
+        const response = await fetch("https://api.x.ai/v1/language-models", {
             headers: { Authorization: `Bearer ${key}` },
             signal: AbortSignal.timeout(15000)
         });
         if (!response.ok)
-            throw new Error(`xAI models endpoint returned ${response.status}`);
+            throw new Error(`xAI language-models endpoint returned ${response.status}`);
         const payload = await response.json();
-        const models = (payload.data ?? []).map((m) => ({ id: m.id }));
+        const models = (payload.models ?? payload.data ?? []).map((m) => ({ id: m.id }));
         return models.length > 0 ? models : STATIC_MODELS.xai;
     }
     catch {

package/dist/storage/run-store.js

@@ -2,6 +2,7 @@ import { mkdir, readdir, rm, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { createRunId } from "../utils/ids.js";
 import { appendJsonl, readJsonl } from "./jsonl.js";
+import { isHarnessProvider } from "../providers/llm/registry.js";
 export function getRunPaths(runPath) {
     return {
         root: runPath,
@@ -27,15 +28,21 @@ export async function createRun(goal, config, projectRoot = process.cwd()) {
     await mkdir(paths.artifacts, { recursive: true });
     await mkdir(paths.snapshots, { recursive: true });
     await Bun.write(paths.goal, `# Goal\n\n${goal}\n`);
-    await Bun.write(paths.plan, "# Research Plan\n\nPending plan generation.\n");
     await Bun.write(paths.research, researchInstructions());
     await Bun.write(paths.scope, `${JSON.stringify({ goal, maxSources: config.maxSources, citationPolicy: config.citationPolicy }, null, 2)}\n`);
     await Bun.write(paths.progress, progressText("created", "Generate and approve research plan."));
-    await Bun.write(paths.sources, "");
-    await Bun.write(paths.claims, "");
-    await Bun.write(paths.notes, "# Notes\n\n");
-    await Bun.write(paths.report, "# Report\n\nDraft not generated yet.\n");
     await Bun.write(paths.handoff, handoffText(goal, "created"));
+    // The local-harness providers (claude-code / codex) run their own CLI, whose
+    // Write tool refuses to overwrite a file it hasn't Read first. Pre-seeding the
+    // agent-written artifacts would block it, so leave those for the agent to
+    // create fresh. summarizeRun tolerates the missing files.
+    if (!isHarnessProvider(config.llmProvider)) {
+        await Bun.write(paths.plan, "# Research Plan\n\nPending plan generation.\n");
+        await Bun.write(paths.sources, "");
+        await Bun.write(paths.claims, "");
+        await Bun.write(paths.notes, "# Notes\n\n");
+        await Bun.write(paths.report, "# Report\n\nDraft not generated yet.\n");
+    }
     await logEvent(paths.root, "run.created", { goal });
     return summarizeRun(paths.root);
 }

package/dist/tools/workspace.js

@@ -55,6 +55,14 @@ function projectRootFromPath(absPath) {
         return normalized.slice(0, -"/.scira".length) || "/";
     return undefined;
 }
+/** Absolute form of `candidate` if it lands inside the run directory, else null. */
+function absInsideRun(runPath, workspacePath, raw) {
+    if (!isAbsolute(raw) && !workspacePath)
+        return null; // can't resolve a relative path without a root
+    const abs = isAbsolute(raw) ? resolve(raw) : resolve(workspacePath, raw);
+    const rel = relative(resolve(runPath), abs);
+    return !rel.startsWith("..") && !isAbsolute(rel) ? abs : null;
+}
 export function resolveToolPath(runPath, workspacePath, candidate) {
     const raw = candidate.trim();
     if (raw.startsWith("run:")) {
@@ -62,6 +70,13 @@ export function resolveToolPath(runPath, workspacePath, candidate) {
         const abs = resolveInsideRun(runPath, inner);
         return { abs, displayPath: inner, scope: "run" };
     }
+    // A full/absolute path that points into the run directory routes to the run —
+    // so the model can use the run dir path we hand it, not only bare names.
+    const runAbs = absInsideRun(runPath, workspacePath, raw);
+    if (runAbs) {
+        const display = relative(resolve(runPath), runAbs) || ".";
+        return { abs: runAbs, displayPath: display, scope: "run" };
+    }
     if (workspacePath && !isRunArtifactPath(raw)) {
         const abs = resolveInsideWorkspace(workspacePath, raw);
         return { abs, displayPath: raw, scope: "workspace" };

package/dist/ui/ink/SciraApp.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { useCallback, useMemo, useRef, useState } from "react";
 import { Box, Text, useApp, useStdout, useStdin } from "ink";
-import { CHAT_COMMANDS, MENU_VISIBLE, SPINNER_FRAMES, LOADING_PHRASES } from "./constants.js";
+import { COMMAND_GROUPS, KEY_HINTS, MENU_VISIBLE, SPINNER_FRAMES, LOADING_PHRASES } from "./constants.js";
 import { CWD_DISPLAY, wrapText, wrapInputWithCursor, loadInputHistory, saveInputHistory, linkAtMouseColumn, openExternalUrl } from "./lib/utils.js";
 import { deleteRun } from "../../storage/run-store.js";
 import { saveGlobalConfig } from "../../config/load-config.js";
@@ -20,7 +20,7 @@ import { useSubmit } from "./hooks/use-submit.js";
 import { useSession } from "./hooks/use-session.js";
 import { useMouse } from "./hooks/use-mouse.js";
 import { ThemeProvider, useTheme } from "./hooks/use-theme.js";
-export function SciraApp({ runPath: initialRunPath, config: initialConfig }) {
+export function SciraApp({ runPath: initialRunPath, config: initialConfig, updateNotice }) {
     const { exit } = useApp();
     const { stdout } = useStdout();
     const { stdin } = useStdin();
@@ -37,7 +37,7 @@ export function SciraApp({ runPath: initialRunPath, config: initialConfig }) {
     const [screen, setScreen] = useState(initialRunPath ? "chat" : "home");
     const [currentRunPath, setCurrentRunPath] = useState(initialRunPath);
     const [config, setConfig] = useState(initialConfig);
-    const [notice, setNotice] = useState("");
+    const [notice, setNotice] = useState(updateNotice ?? "");
     const [pendingRerun, setPendingRerun] = useState(false);
     const [mcpOpen, setMcpOpen] = useState(false);
     const [mcpRowIdx, setMcpRowIdx] = useState(0);
@@ -338,7 +338,7 @@ export function SciraApp({ runPath: initialRunPath, config: initialConfig }) {
     const caret = Math.max(0, Math.min(cursorPos, inputText.length));
     const { lines: inputLines, cursorLine, cursorCol } = wrapInputWithCursor(rawInputText, textWidth, showCursor ? caret : -1);
     const commandMenuHeight = activeSuggestions.length > 0 ? Math.min(MENU_VISIBLE, activeSuggestions.length) + 3 : 0;
-    const helpHeight = helpOpen ? Math.min(14, CHAT_COMMANDS.length + 4) : 0;
+    const helpHeight = helpOpen ? KEY_HINTS.length + COMMAND_GROUPS.length + 7 : 0;
     const approvalPreviewLines = approvalPending
         ? Math.min(5, wrapText(approvalPending.description, Math.max(10, innerWidth - 4)).length)
         : 0;
@@ -447,7 +447,7 @@ export function SciraApp({ runPath: initialRunPath, config: initialConfig }) {
     const activeUsage = usage[config.model];
     const themed = (node) => (_jsx(ThemeProvider, { config: config, children: node }));
     if (screen === "home") {
-        return themed(_jsxs(Box, { flexDirection: "column", width: cols, height: rows, paddingX: 2, children: [_jsx(TipCycler, { setTipIndex: setTipIndex }), (!sessionsModalOpen || mcpOpen) && stdout !== undefined && stdin !== undefined && (_jsx(MouseTracker, { stdout: stdout, stdin: stdin, onData: handleMouseData, onUnmount: () => setHoveredIdx(null) })), busy && _jsx(AnimationTick, { setBlink: setBlink, setFrame: setFrame, setReasoningTick: setReasoningTick }), _jsx(TopBar, { screen: screen, runState: runState, fullMode: fullMode, planMode: planMode, activeUsage: activeUsage, busy: busy, frame: frame, cwdDisplay: CWD_DISPLAY, config: config }), _jsx(HomeScreen, { cols: cols, rows: rows, sessions: sessions, selectedIdx: selectedIdx, hoveredIdx: hoveredIdx, heroHidden: heroHidden, notice: notice, tipIndex: tipIndex, commandMenuHeight: commandMenuHeight, mcpOpen: mcpOpen, sessionsModalOpen: sessionsModalOpen, sessionsModalIdx: sessionsModalIdx, inputText: inputText, config: config, modelName: modelName, clickMapRef: clickMapRef, hoverMapRef: hoverMapRef, setSelectedIdx: setSelectedIdx, setSessionsModalOpen: setSessionsModalOpen, setSessionsModalIdx: setSessionsModalIdx, setNotice: setNotice, openRun: openRun, submitHome: submitHome, exit: exit }), _jsxs(Box, { flexDirection: "column", paddingBottom: 1, children: [_jsx(CommandMenuBox, { activeSuggestions: activeSuggestions, activeSuggestionKind: activeSuggestionKind, commandMenuIndex: commandMenuIndex, innerWidth: innerWidth, sessions: sessions, config: config }), _jsx(InputBar, { inputLines: inputLines, cursorLine: cursorLine, cursorCol: cursorCol, showCursor: showCursor, approvalPending: inputBlocked, busy: busy, frame: frame, boxWidth: boxWidth, modelName: modelName, planMode: planMode, config: config }), _jsx(HintLine, { screen: screen, busy: busy, modeLabel: pendingPlanMode ? "PLAN MODE" : "", modeColor: "cyan", config: config })] }), _jsx(MenuDialog, { menu: menu, cols: cols, rows: rows, config: config }), _jsx(McpDialog, { open: mcpOpen, config: config, cols: cols, rows: rows, selectedIdx: mcpRowIdx, hoveredIdx: hoveredIdx, onToggle: handleMcpToggle, onRemove: handleMcpRemove, clickMapRef: clickMapRef, hoverMapRef: hoverMapRef })] }));
+        return themed(_jsxs(Box, { flexDirection: "column", width: cols, height: rows, paddingX: 2, children: [_jsx(TipCycler, { setTipIndex: setTipIndex }), (!sessionsModalOpen || mcpOpen) && stdout !== undefined && stdin !== undefined && (_jsx(MouseTracker, { stdout: stdout, stdin: stdin, onData: handleMouseData, onUnmount: () => setHoveredIdx(null) })), busy && _jsx(AnimationTick, { setBlink: setBlink, setFrame: setFrame, setReasoningTick: setReasoningTick }), _jsx(TopBar, { screen: screen, runState: runState, fullMode: fullMode, planMode: planMode, activeUsage: activeUsage, busy: busy, frame: frame, cwdDisplay: CWD_DISPLAY, config: config }), _jsx(HomeScreen, { cols: cols, rows: rows, sessions: sessions, selectedIdx: selectedIdx, hoveredIdx: hoveredIdx, heroHidden: heroHidden, notice: notice, tipIndex: tipIndex, commandMenuHeight: commandMenuHeight + helpHeight, mcpOpen: mcpOpen, sessionsModalOpen: sessionsModalOpen, sessionsModalIdx: sessionsModalIdx, inputText: inputText, config: config, modelName: modelName, clickMapRef: clickMapRef, hoverMapRef: hoverMapRef, setSelectedIdx: setSelectedIdx, setSessionsModalOpen: setSessionsModalOpen, setSessionsModalIdx: setSessionsModalIdx, setNotice: setNotice, openRun: openRun, submitHome: submitHome, exit: exit }), _jsxs(Box, { flexDirection: "column", paddingBottom: 1, children: [_jsx(CommandMenuBox, { activeSuggestions: activeSuggestions, activeSuggestionKind: activeSuggestionKind, commandMenuIndex: commandMenuIndex, innerWidth: innerWidth, sessions: sessions, config: config }), _jsx(HelpBox, { open: helpOpen, innerWidth: innerWidth, config: config }), _jsx(InputBar, { inputLines: inputLines, cursorLine: cursorLine, cursorCol: cursorCol, showCursor: showCursor, approvalPending: inputBlocked, busy: busy, frame: frame, boxWidth: boxWidth, modelName: modelName, planMode: planMode, config: config }), _jsx(HintLine, { screen: screen, busy: busy, modeLabel: pendingPlanMode ? "PLAN MODE" : "", modeColor: "cyan", config: config })] }), _jsx(MenuDialog, { menu: menu, cols: cols, rows: rows, config: config }), _jsx(McpDialog, { open: mcpOpen, config: config, cols: cols, rows: rows, selectedIdx: mcpRowIdx, hoveredIdx: hoveredIdx, onToggle: handleMcpToggle, onRemove: handleMcpRemove, clickMapRef: clickMapRef, hoverMapRef: hoverMapRef })] }));
     }
     return themed(_jsxs(Box, { flexDirection: "column", width: cols, height: rows, paddingX: 2, children: [stdout !== undefined && stdin !== undefined && (_jsx(MouseTracker, { stdout: stdout, stdin: stdin, onData: handleMouseData, onUnmount: () => setHoveredIdx(null) })), busy && _jsx(AnimationTick, { setBlink: setBlink, setFrame: setFrame, setReasoningTick: setReasoningTick }), _jsx(TopBar, { screen: screen, runState: runState, fullMode: fullMode, planMode: planMode, activeUsage: activeUsage, busy: busy, frame: frame, cwdDisplay: CWD_DISPLAY, config: config }), _jsx(Box, { flexDirection: "column", height: contentRows, flexShrink: 0, justifyContent: feedLines.length > contentRows ? "flex-end" : "flex-start", paddingTop: 1, overflow: "hidden", children: visibleLines }), _jsxs(ChatInputChrome, { children: [_jsx(CommandMenuBox, { activeSuggestions: activeSuggestions, activeSuggestionKind: activeSuggestionKind, commandMenuIndex: commandMenuIndex, innerWidth: innerWidth, sessions: sessions, config: config }), _jsx(HelpBox, { open: helpOpen, innerWidth: innerWidth, config: config }), approvalPending && _jsx(ApprovalBox, { toolName: approvalPending.toolName, description: approvalPending.description, innerWidth: innerWidth, config: config }), linkPending && _jsx(LinkOpenBox, { url: linkPending.url, innerWidth: innerWidth, config: config }), _jsx(InputBar, { inputLines: inputLines, cursorLine: cursorLine, cursorCol: cursorCol, showCursor: showCursor, approvalPending: inputBlocked, busy: busy, frame: frame, boxWidth: boxWidth, modelName: modelName, planMode: planMode, config: config }), _jsx(HintLine, { screen: screen, busy: busy, modeLabel: fullMode ? "FULL RESEARCH" : planMode ? "PLAN MODE" : "", modeColor: fullMode ? "magenta" : "cyan", scrollLabel: scrollLabel, hasDoneGroups: doneGroupKeys.length > 0, hasFocusedGroup: focusedGroupKey !== null, hasLinkHover: hasLinkHover || !!linkPending, alwaysAllowLinks: config.alwaysAllowLinks, config: config })] }), _jsx(MenuDialog, { menu: menu, cols: cols, rows: rows, config: config }), _jsx(McpDialog, { open: mcpOpen, config: config, cols: cols, rows: rows, selectedIdx: mcpRowIdx, hoveredIdx: hoveredIdx, onToggle: handleMcpToggle, onRemove: handleMcpRemove, clickMapRef: clickMapRef, hoverMapRef: hoverMapRef })] }));
 }

package/dist/ui/ink/components/overlays.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Box, Text } from "ink";
-import { SPINNER_FRAMES, CHAT_COMMANDS, COMMAND_DESCRIPTIONS, MENU_VISIBLE } from "../constants.js";
+import { SPINNER_FRAMES, COMMAND_DESCRIPTIONS, COMMAND_GROUPS, KEY_HINTS, MENU_VISIBLE } from "../constants.js";
 import { fmtTokens, wrapText, displayWidth } from "../lib/utils.js";
 import { LLM_PROVIDER_LABELS } from "../../../providers/llm/registry.js";
 import { useTheme } from "../hooks/use-theme.js";
@@ -78,7 +78,10 @@ export function HelpBox({ open, innerWidth, config }) {
     const theme = useTheme();
     if (!open)
         return null;
-    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: theme.border, paddingX: 1, children: [_jsxs(Text, { bold: true, color: theme.text, children: ["help ", _jsx(Text, { color: theme.textDim, children: "esc close" })] }), _jsx(Text, { color: theme.textDim, children: "─".repeat(Math.max(10, innerWidth - 6)) }), _jsx(Text, { color: theme.textDim, children: "scroll  \u2191/\u2193  k/j  u/d  pgup/pgdn" }), _jsx(Text, { color: theme.textDim, children: "autocomplete  / commands \u00B7 @ files \u00B7 # sessions" }), _jsx(Text, { color: theme.textDim, children: "─".repeat(Math.max(10, innerWidth - 6)) }), CHAT_COMMANDS.map((cmd) => (_jsxs(Box, { gap: 2, children: [_jsx(Text, { color: theme.accent, children: cmd }), _jsx(Text, { color: theme.textDim, children: COMMAND_DESCRIPTIONS[cmd] })] }, cmd)))] }));
+    const rule = "─".repeat(Math.max(10, innerWidth - 6));
+    const keyW = Math.max(...KEY_HINTS.map((h) => h.keys.length));
+    const labelW = Math.max(...COMMAND_GROUPS.map((g) => g.label.length));
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: theme.border, paddingX: 1, children: [_jsxs(Text, { bold: true, color: theme.text, children: ["help ", _jsx(Text, { color: theme.textDim, children: "\u00B7 esc to close \u00B7 type / to search a command" })] }), _jsx(Text, { color: theme.textDim, children: rule }), _jsx(Text, { bold: true, color: theme.textDim, children: "keys" }), KEY_HINTS.map((h) => (_jsxs(Box, { gap: 2, children: [_jsx(Text, { color: theme.accent, children: h.keys.padEnd(keyW) }), _jsx(Text, { color: theme.textDim, children: h.action })] }, h.keys))), _jsx(Text, { color: theme.textDim, children: rule }), _jsx(Text, { bold: true, color: theme.textDim, children: "commands" }), COMMAND_GROUPS.map((g) => (_jsxs(Box, { gap: 2, children: [_jsx(Text, { color: theme.textDim, children: g.label.padEnd(labelW) }), _jsx(Text, { color: theme.accent, wrap: "truncate", children: g.commands.join("  ") })] }, g.label)))] }));
 }
 export function LinkOpenBox({ url, innerWidth, config }) {
     const theme = useTheme();

package/dist/ui/ink/constants.js

@@ -4,6 +4,21 @@ export const FILE_MENTION_MAX_CHARS = 20000;
 export const FILE_MENTION_SKIP = new Set([".git", "node_modules", "dist", ".scira"]);
 export const PROVIDERS = ["parallel", "exa", "firecrawl"];
 export const CHAT_COMMANDS = ["/help", "/home", "/new", "/plan", "/rerun", "/report", "/sources", "/claims", "/why", "/mcp", "/copy", "/usage", "/rename", "/model", "/llm", "/provider", "/thinking", "/reasoning", "/theme", "/links", "/key", "/keys", "/stop", "/back", "/quit"];
+/** Commands grouped by purpose, for the /help reference. */
+export const COMMAND_GROUPS = [
+    { label: "Model", commands: ["/llm", "/model", "/provider", "/plan", "/thinking", "/reasoning"] },
+    { label: "Session", commands: ["/new", "/rerun", "/rename", "/report", "/sources", "/claims", "/why", "/copy", "/usage"] },
+    { label: "Setup", commands: ["/key", "/keys", "/mcp", "/theme", "/links"] },
+    { label: "Go", commands: ["/home", "/back", "/stop", "/quit"] },
+];
+/** Keyboard shortcuts shown in /help (not discoverable via the `/` autocomplete). */
+export const KEY_HINTS = [
+    { keys: "↑↓ jk u/d pgup/dn", action: "scroll" },
+    { keys: "^C ^C / ^D", action: "quit" },
+    { keys: "esc", action: "clear input / close" },
+    { keys: "/ @ #", action: "commands · files · sessions" },
+    { keys: "[ ] C", action: "navigate / toggle tool groups" },
+];
 /** Slash commands that take an argument; ⏎ from the menu appends a space instead of running. */
 export const COMMANDS_NEEDING_ARGS = new Set(["/theme", "/key", "/rename", "/why", "/links"]);
 export const COMMAND_DESCRIPTIONS = {
@@ -43,6 +58,7 @@ export const TOOL_ICONS = {
     verifyClaim: "✓",
     webSearch: "⌕",
     multiWebSearch: "⌕",
+    fileChange: "✎",
     readUrl: "↗",
     listSkills: "★",
     readSkill: "★",

package/dist/ui/ink/lib/tool-result.js

@@ -222,9 +222,15 @@ function formatListSkills(result, width, theme) {
     });
 }
 function formatShellOutput(result, width, theme) {
-    if (!result.trim())
+    // Codex returns `{ exitCode, output }`; Claude returns the output string directly.
+    let text = result;
+    const obj = parseObj(result);
+    if (obj && typeof obj.output === "string") {
+        text = typeof obj.exitCode === "number" && obj.exitCode !== 0 ? `[exit ${obj.exitCode}]\n${obj.output}` : obj.output;
+    }
+    if (!text.trim())
         return [[seg("(no output)", { dim: true, color: theme.textDim })]];
-    return result.split("\n").flatMap((line) => plainLines(line, width, { color: theme.textDim }));
+    return text.split("\n").flatMap((line) => plainLines(line, width, { color: theme.textDim }));
 }
 function formatFileContent(result, width, theme) {
     const rows = result.split("\n");
@@ -521,10 +527,20 @@ function formatBuiltinBody(real, rawInput, result, width, theme) {
             return formatSubagentBody(input, result, width, theme);
         case "ToolSearch":
             return formatToolSearchBody(input, result, width, theme);
+        case "fileChange":
+            return formatFileChangeBody(input ?? parseObj(result), theme);
         default:
             return null;
     }
 }
+/** Codex/Claude file mutation event → a single colored "<event>  <path>" line. */
+function formatFileChangeBody(fc, theme) {
+    if (!fc)
+        return null;
+    const event = String(fc.event ?? "change");
+    const color = event === "delete" ? theme.error : event === "create" ? theme.success : theme.accent;
+    return [[seg(`${event}  `, { color }), seg(String(fc.path ?? ""), { color: theme.text })]];
+}
 /** Multi-line formatted tool output for the feed panel. */
 export function formatToolResultLines(rawName, inputSummary, rawResult, status, contentWidth, theme, expanded = true, rawInput) {
     const name = canonicalToolName(rawName);

package/dist/ui/ink/lib/utils.js

@@ -324,6 +324,8 @@ export function summarizeToolInput(rawName, input) {
         return String(obj.name ?? obj.skill ?? "");
     if (name === "createClaim" || name === "verifyClaim")
         return String(obj.id ?? "");
+    if (name === "fileChange")
+        return `${String(obj.event ?? "change")} ${String(obj.path ?? "")}`.trim();
     if (stripped === "ToolSearch")
         return String(obj.query ?? "");
     if (stripped === "Task" || stripped === "Agent")

package/dist/utils/update-check.js

@@ -0,0 +1,63 @@
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const PKG = "@scira/cli";
+const CACHE_FILE = join(homedir(), ".scira", "update-check.json");
+const THROTTLE_MS = 24 * 60 * 60 * 1000; // check npm at most once a day
+/** `true` when `latest` is a higher semver than `current` (pre-release suffixes ignored). */
+function isNewer(latest, current) {
+    const parse = (v) => v.split("-")[0].split(".").map((n) => Number.parseInt(n, 10) || 0);
+    const a = parse(latest), b = parse(current);
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const x = a[i] ?? 0, y = b[i] ?? 0;
+        if (x !== y)
+            return x > y;
+    }
+    return false;
+}
+async function fetchLatest() {
+    try {
+        const res = await fetch(`https://registry.npmjs.org/${PKG}/latest`, {
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(3000),
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return data.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns the available update (or null), checking npm at most once per day.
+ * Network/parse failures resolve to null and are swallowed — this never throws
+ * and never blocks for more than ~3s (and only that once a day).
+ */
+export async function checkForUpdate(current) {
+    let cache = null;
+    try {
+        cache = (await Bun.file(CACHE_FILE).json());
+    }
+    catch { /* no/invalid cache */ }
+    const now = Date.now();
+    let latest = cache?.latest ?? null;
+    if (!cache || now - cache.checkedAt > THROTTLE_MS) {
+        // Keep the previously-known version on a failed fetch — a transient network
+        // error shouldn't discard an update we already knew about (and then suppress
+        // it for the rest of the throttle window).
+        latest = (await fetchLatest()) ?? latest;
+        // Persist (even on failure) so we don't re-check on every command today.
+        try {
+            await mkdir(join(homedir(), ".scira"), { recursive: true });
+            await Bun.write(CACHE_FILE, JSON.stringify({ checkedAt: now, latest }));
+        }
+        catch { /* best-effort */ }
+    }
+    return latest && isNewer(latest, current) ? { current, latest } : null;
+}
+/** One-line, human-facing update message. */
+export function formatUpdateNotice(u) {
+    return `Update available: ${u.current} → ${u.latest} · run "bun add -g ${PKG}"`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scira/cli",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Scira — terminal-native AI research agent with grounded sources, verified claims, and local run storage.",
   "license": "MIT",
   "type": "module",