@khanglvm/outline-cli 0.1.2 → 0.1.4

package/src/agent-skills.js

@@ -1,71 +1,173 @@
 import { CliError } from "./errors.js";
 
-const AI_SKILL_DATA_VERSION = "2026-03-05.1";
+const AI_SKILL_DATA_VERSION = "2026-03-07.1";
 const AI_HELP_SECTION_ID = "ai-skills";
 const QUICK_START_HELP_SECTION_ID = "quick-start-agent";
-const QUICK_START_HELP_VERSION = "2026-03-05.1";
+const QUICK_START_HELP_VERSION = "2026-03-07.1";
 
 const QUICK_START_AGENT_PLAYBOOK = {
   title: "outline-cli onboarding for non-expert users",
   audience: "AI agents assisting non-expert users in terminal setup and first usage.",
   objective:
-    "Install outline-cli globally, discover required setup commands, guide profile creation with follow-up questions, then demonstrate example use cases in natural language.",
+    "Use this guide only for first-time setup or when profile/auth access is missing. For normal work, prefer direct task execution with search.research, documents.search, documents.info, and batch before reading onboarding docs.",
   steps: [
     {
       step: 1,
-      title: "Install outline-cli globally",
-      command: "npm i -g @khanglvm/outline-cli",
-      successCheck: "outline-cli --help",
+      title: "Confirm whether onboarding help is actually needed",
+      commands: [
+        "outline-cli --version",
+        "outline-cli profile list",
+      ],
+      fallbackCommands: [
+        "npm i -g @khanglvm/outline-cli@latest",
+        "outline-cli --version",
+        "outline-cli profile list",
+      ],
+      successCheck: "If version and profile list both work, skip onboarding help and proceed directly to the user's task.",
     },
     {
       step: 2,
+      title: "Load full onboarding guide only when setup is missing or broken",
+      command: "outline-cli tools help quick-start-agent --view full",
+    },
+    {
+      step: 3,
+      title: "Suggest optional outline-cli skill installation via npx skills",
+      question:
+        "Would you like me to install the outline-cli skill now via npx skills for all currently supported local AI tools? This helps future AI sessions use the right workflow by default.",
+      commandTemplates: [
+        "npx skills add https://github.com/khanglvm/skills --skill outline-cli -y",
+      ],
+      decisionRules: [
+        "If user explicitly approves, run the command in headless mode exactly once so installation applies to currently supported local tools.",
+        "If user declines, skip installation and continue onboarding without blocking profile setup.",
+      ],
+      expectedSignals: [
+        "Successful install prints completion output from npx skills.",
+        "Failure should be reported with the exact command and next recovery step.",
+      ],
+    },
+    {
+      step: 4,
       title: "Inspect command surfaces before asking the user for inputs",
       commands: [
-        "outline-cli --help",
         "outline-cli profile --help",
-        "outline-cli tools --help",
         "outline-cli invoke --help",
       ],
     },
     {
-      step: 3,
-      title: "Ask follow-up questions for missing setup values",
+      step: 5,
+      title: "List existing profiles first and branch setup flow",
+      command: "outline-cli profile list",
+      decisionRules: [
+        "If one or more profiles exist, show them and ask whether to use an existing profile or create a new one.",
+        "If no profiles exist, continue with new profile setup questions.",
+      ],
+    },
+    {
+      step: 6,
+      title: "Ask for Outline base URL with beginner-friendly explanation",
+      question:
+        "What is your Outline base URL? This is the web address you open in your browser to use Outline.",
+      examples: [
+        "Official cloud: https://app.getoutline.com",
+        "Custom/self-hosted: https://docs.yourcompany.com",
+      ],
+      guidance: [
+        "Use https:// and do not include a trailing path.",
+        "If unsure, copy the URL from your browser while viewing your Outline workspace home.",
+      ],
+    },
+    {
+      step: 7,
+      title: "Validate the provided base URL before asking for API key",
+      commandTemplates: [
+        'curl -sS -o /dev/null -w "HTTP %{http_code}\\n" "<base-url>"',
+        'curl -sS -o /dev/null -w "API %{http_code}\\n" "<base-url>/api/auth.info"',
+      ],
+      expectedSignals: [
+        "Base URL check should return a reachable HTTP status (often 200/301/302).",
+        "API auth endpoint without token often returns 401/403, which still confirms domain + API route are reachable.",
+      ],
+    },
+    {
+      step: 8,
+      title: "Guide user to create API key in Outline UI",
+      apiKeySettingsUrlTemplate: "<base-url>/settings/api-and-apps",
+      fallbackNavigation: "In Outline UI: Settings → API & Apps",
+      apiKeyConfigTemplate: [
+        "Name: outline-cli-<profile-id-or-your-name>",
+        "Expiration date: choose your policy (for example 90 days or no expiry if policy allows)",
+        "Scopes: leave empty for same permissions as your user, or restrict to needed endpoints",
+      ],
+      scopeExamples: [
+        "Read-focused starter scope: *.info documents.search collections.list",
+        "Document automation scope: documents.* collections.info",
+      ],
+      requiredUserAction:
+        "Create the key, then copy the generated token value (typically starts with ol_api_) and share it with the agent for profile setup.",
+    },
+    {
+      step: 9,
+      title: "Ask follow-up questions for remaining setup values (one at a time)",
       questions: [
-        "What is your Outline base URL?",
         "What is your Outline API key?",
         "What profile id do you want? (default to prod if user has no preference)",
       ],
     },
     {
-      step: 4,
-      title: "Guide profile setup and set it as default",
+      step: 10,
+      title: "Guide profile setup (API key mode) and set it as default",
       command:
-        'outline-cli profile add <profile-id> --base-url <base-url> --api-key "<api-key>" --set-default',
+        'outline-cli profile add <profile-id> --base-url <base-url> --auth-type apiKey --api-key "<api-key>" --set-default',
     },
     {
-      step: 5,
+      step: 11,
       title: "Verify profile authentication",
       command: "outline-cli profile test <profile-id> --pretty",
     },
     {
-      step: 6,
-      title: "Show example use cases in plain language and run one command per example",
+      step: 12,
+      title: "Show natural-language prompts for what the AI agent can do with outline-cli",
+      minimumPromptCount: 10,
+      naturalLanguagePrompts: [
+        "Find our onboarding checklist in Outline.",
+        "List recent documents in the Engineering collection.",
+        "Show me a summary of document <document-id>.",
+        "Create a draft release notes document with today's date.",
+        "Append a short status update to document <document-id>.",
+        "Find documents mentioning incident response in the last month.",
+        "Show who can access document <document-id>.",
+        "Compare two documents and list key differences.",
+        "Generate a TODO list from document <document-id>.",
+        "Find stale docs that have not been updated recently.",
+      ],
       commandTemplates: [
         'outline-cli invoke documents.search --args \'{"query":"onboarding checklist","mode":"semantic","limit":5,"view":"summary"}\' --pretty',
+        'outline-cli invoke documents.list --args \'{"limit":5,"view":"summary"}\' --pretty',
         'outline-cli invoke documents.info --args \'{"id":"<document-id>","view":"summary"}\' --pretty',
       ],
     },
   ],
   interactionRules: [
     "Use short and clear explanations for beginners.",
+    "Do not open onboarding help for routine tasks when a working profile already exists.",
+    "For routine read tasks, start with search.research, documents.search, documents.info, or batch before reading contracts/help.",
+    "Always suggest optional outline-cli skill installation via npx skills and ask for explicit approval before running install.",
+    "If approved, run npx skills installation in headless mode (`-y`, no tool-specific agent filter) and continue onboarding.",
+    "Always run profile list before profile add.",
+    "Prefer API key authentication for beginner onboarding unless the user explicitly requests another auth mode.",
+    "Explain base URL and API key steps in plain language, then validate the domain before requesting the API key.",
     "Ask one question at a time when required information is missing.",
     "If a command fails, explain the cause and provide the exact next command.",
     "Confirm each step completion before moving to the next step.",
+    "After setup, provide at least 10 natural-language prompts and run one command example.",
   ],
 };
 
 const AI_GLOBAL_GUIDANCE = {
   principles: [
+    "Start with the best-fit task tool first; open help/contracts only after validation fails or capability is unclear.",
     "Use ids/summary views first, then hydrate only selected records.",
     "Prefer batch operations (queries, ids, or batch command) before multi-call loops.",
     "For heavy retrieval, use search.research with precisionMode + perQueryView/perQueryHitLimit to control token cost.",
@@ -707,11 +809,46 @@ function summarizeQuickStartPlaybook() {
     title: QUICK_START_AGENT_PLAYBOOK.title,
     audience: QUICK_START_AGENT_PLAYBOOK.audience,
     objective: QUICK_START_AGENT_PLAYBOOK.objective,
-    steps: QUICK_START_AGENT_PLAYBOOK.steps.map((row) => ({
-      step: row.step,
-      title: row.title,
-      command: row.command || null,
-    })),
+    steps: QUICK_START_AGENT_PLAYBOOK.steps.map((row) => {
+      const summaryRow = {
+        step: row.step,
+        title: row.title,
+      };
+      if (row.command) {
+        summaryRow.command = row.command;
+      }
+      if (Array.isArray(row.commands)) {
+        summaryRow.commands = row.commands;
+      }
+      if (Array.isArray(row.questions)) {
+        summaryRow.questions = row.questions;
+      }
+      if (row.question) {
+        summaryRow.question = row.question;
+      }
+      if (row.minimumPromptCount) {
+        summaryRow.minimumPromptCount = row.minimumPromptCount;
+      }
+      if (Array.isArray(row.commandTemplates)) {
+        summaryRow.commandTemplates = row.commandTemplates;
+      }
+      if (Array.isArray(row.decisionRules)) {
+        summaryRow.decisionRules = row.decisionRules;
+      }
+      if (Array.isArray(row.expectedSignals)) {
+        summaryRow.expectedSignals = row.expectedSignals;
+      }
+      if (row.apiKeySettingsUrlTemplate) {
+        summaryRow.apiKeySettingsUrlTemplate = row.apiKeySettingsUrlTemplate;
+      }
+      if (Array.isArray(row.apiKeyConfigTemplate)) {
+        summaryRow.apiKeyConfigTemplate = row.apiKeyConfigTemplate;
+      }
+      if (Array.isArray(row.scopeExamples)) {
+        summaryRow.scopeExamples = row.scopeExamples;
+      }
+      return summaryRow;
+    }),
     interactionRules: QUICK_START_AGENT_PLAYBOOK.interactionRules,
     nextCommand: "outline-cli tools help quick-start-agent --view full",
   };
@@ -850,7 +987,7 @@ export function listHelpSections() {
       id: QUICK_START_HELP_SECTION_ID,
       title: "AI setup onboarding",
       description:
-        "Copy-ready AI onboarding instructions to install outline-cli, guide profile setup, and demonstrate first use cases.",
+        "First-time AI setup only: verify installation, guide API-key profile setup, and provide starter prompts when no working profile exists.",
       commandExample: "outline-cli tools help quick-start-agent --view full",
     },
     {

package/src/cli.js

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import path from "node:path";
+import { createRequire } from "node:module";
 import { getAgentSkillHelp, getQuickStartAgentHelp, listHelpSections } from "./agent-skills.js";
 import {
   buildProfile,
@@ -21,9 +22,12 @@ import {
   removeProfileFromKeychain,
   secureProfileForStorage,
 } from "./secure-keyring.js";
-import { getToolContract, invokeTool, listTools } from "./tools.js";
+import { getToolContract, invokeTool, listTools, resolveToolInvocation } from "./tools.js";
 import { mapLimit, parseJsonArg, parseCsv, toInteger } from "./utils.js";
 
+const require = createRequire(import.meta.url);
+const { version: packageVersion } = require("../package.json");
+
 function configureSharedOutputOptions(command) {
   return command
     .option("--config <path>", "Config file path", defaultConfigPath())
@@ -44,23 +48,6 @@ function buildStoreFromOptions(opts) {
   });
 }
 
-async function getRuntime(opts, overrideProfileId) {
-  const configPath = path.resolve(opts.config || defaultConfigPath());
-  const config = await loadConfig(configPath);
-  const selectedProfile = getProfile(config, overrideProfileId || opts.profile);
-  const profile = hydrateProfileFromKeychain({
-    configPath,
-    profile: selectedProfile,
-  });
-  const client = new OutlineClient(profile);
-  return {
-    configPath,
-    config,
-    profile,
-    client,
-  };
-}
-
 function parseHeaders(input) {
   if (!input) {
     return {};
@@ -79,6 +66,130 @@ function parseHeaders(input) {
   return headers;
 }
 
+function isBrokenPipeError(err) {
+  return err?.code === "EPIPE" || err?.errno === -32;
+}
+
+function safeWrite(stream, content, exitCode = 0) {
+  try {
+    return stream.write(content);
+  } catch (err) {
+    if (isBrokenPipeError(err)) {
+      process.exit(exitCode);
+    }
+    throw err;
+  }
+}
+
+function installBrokenPipeGuards() {
+  const handlePipeError = (exitCode) => (err) => {
+    if (isBrokenPipeError(err)) {
+      process.exit(exitCode);
+      return;
+    }
+    throw err;
+  };
+
+  process.stdout.on("error", handlePipeError(0));
+  process.stderr.on("error", handlePipeError(process.exitCode || 1));
+}
+
+const PROFILE_ROUTING_ARG_KEYS = [
+  "query",
+  "queries",
+  "question",
+  "questions",
+  "title",
+  "titles",
+  "description",
+  "name",
+  "keywords",
+  "collectionId",
+  "documentId",
+  "parentDocumentId",
+  "id",
+  "ids",
+  "url",
+  "shareId",
+  "email",
+];
+
+function collectRoutingHints(value, bucket, depth = 0) {
+  if (value === undefined || value === null || depth > 2) {
+    return;
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed) {
+      bucket.push(normalizeUrlHint(trimmed) || trimmed);
+    }
+    return;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    bucket.push(String(value));
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value.slice(0, 8)) {
+      collectRoutingHints(item, bucket, depth + 1);
+    }
+    return;
+  }
+  if (typeof value === "object") {
+    for (const [key, nested] of Object.entries(value).slice(0, 8)) {
+      if (PROFILE_ROUTING_ARG_KEYS.includes(key)) {
+        collectRoutingHints(nested, bucket, depth + 1);
+      }
+    }
+  }
+}
+
+function buildProfileRoutingQuery(context = {}) {
+  const bucket = [];
+  const tool = String(context.tool || "").trim();
+  if (tool) {
+    bucket.push(tool.replace(/[._]+/g, " "));
+  }
+  const args = context.args && typeof context.args === "object" ? context.args : {};
+  for (const key of PROFILE_ROUTING_ARG_KEYS) {
+    if (key in args) {
+      collectRoutingHints(args[key], bucket);
+    }
+  }
+  return [...new Set(bucket.map((item) => String(item || "").trim()).filter(Boolean))].join(" ");
+}
+
+function isLikelyReadOnlyToolName(tool, args = {}) {
+  if (args?.performAction === true) {
+    return false;
+  }
+  const name = String(tool || "").toLowerCase();
+  return !/(^|\.)(create|update|delete|remove|restore|duplicate|revoke|invite|suspend|activate|import|apply|rotate|cleanup|templatize|add_|remove_|permanent_delete|empty_trash|batch_update|safe_update)/.test(name);
+}
+
+async function getRuntime(opts, overrideProfileId, context = {}) {
+  const configPath = path.resolve(opts.config || defaultConfigPath());
+  const config = await loadConfig(configPath);
+  const selectedProfile = getProfile(config, overrideProfileId || opts.profile, {
+    query: buildProfileRoutingQuery(context),
+    allowAutoSelect: isLikelyReadOnlyToolName(context.tool, context.args),
+    suggestionLimit: 3,
+  });
+  const { selection: profileSelection, ...storedProfile } = selectedProfile;
+  const profile = hydrateProfileFromKeychain({
+    configPath,
+    profile: storedProfile,
+  });
+  const client = new OutlineClient(profile);
+  return {
+    configPath,
+    config,
+    profile,
+    client,
+    profileSelection,
+  };
+}
+
 const URL_HINT_PATH_MARKERS = new Set(["doc", "d", "share", "s"]);
 
 function normalizeUrlHint(value) {
@@ -144,7 +255,7 @@ function formatError(err) {
 }
 
 function writeNdjsonLine(value) {
-  process.stdout.write(`${JSON.stringify(value)}\n`);
+  safeWrite(process.stdout, `${JSON.stringify(value)}\n`);
 }
 
 function emitNdjson(payload) {
@@ -233,11 +344,12 @@ async function emitOutput(store, payload, opts, emitOptions = {}) {
 }
 
 export async function run(argv = process.argv) {
+  installBrokenPipeGuards();
   const program = new Command();
   program
     .name("outline-cli")
     .description("Agent-optimized CLI for Outline API")
-    .version("0.1.0")
+    .version(packageVersion)
     .showHelpAfterError(true);
 
   const profile = program.command("profile").description("Manage Outline profiles");
@@ -353,6 +465,11 @@ export async function run(argv = process.argv) {
     .command("list")
     .description("List configured profiles")
     .option("--config <path>", "Config file path", defaultConfigPath())
+    .option("--output <format>", "Output format: json|ndjson", "json")
+    .option("--result-mode <mode>", "Result mode: auto|inline|file", "auto")
+    .option("--inline-max-bytes <n>", "Max inline JSON payload size", "12000")
+    .option("--tmp-dir <path>", "Directory for large result files")
+    .option("--pretty", "Pretty-print JSON output", false)
     .action(async (opts) => {
       const configPath = path.resolve(opts.config || defaultConfigPath());
       const config = await loadConfig(configPath);
@@ -360,16 +477,13 @@ export async function run(argv = process.argv) {
         ...redactProfile(item),
         isDefault: config.defaultProfile === item.id,
       }));
-      const store = new ResultStore({ pretty: true });
-      await store.emit(
-        {
-          ok: true,
-          configPath,
-          defaultProfile: config.defaultProfile,
-          profiles,
-        },
-        { mode: "inline", pretty: true, label: "profile-list" }
-      );
+      const store = buildStoreFromOptions(opts);
+      await emitOutput(store, {
+        ok: true,
+        configPath,
+        defaultProfile: config.defaultProfile,
+        profiles,
+      }, opts, { mode: opts.resultMode, label: "profile-list", pretty: !!opts.pretty });
     });
 
   profile
@@ -377,40 +491,44 @@ export async function run(argv = process.argv) {
     .description("Suggest best-matching profile(s) by id/name/base-url/description/keywords")
     .option("--config <path>", "Config file path", defaultConfigPath())
     .option("--limit <n>", "Max number of profile matches to return", "5")
+    .option("--output <format>", "Output format: json|ndjson", "json")
+    .option("--result-mode <mode>", "Result mode: auto|inline|file", "auto")
+    .option("--inline-max-bytes <n>", "Max inline JSON payload size", "12000")
+    .option("--tmp-dir <path>", "Directory for large result files")
+    .option("--pretty", "Pretty-print JSON output", false)
     .action(async (query, opts) => {
       const configPath = path.resolve(opts.config || defaultConfigPath());
       const config = await loadConfig(configPath);
       const result = suggestProfiles(config, query, { limit: toInteger(opts.limit, 5) });
-      const store = new ResultStore({ pretty: true });
-      await store.emit(
-        {
-          ok: true,
-          configPath,
-          defaultProfile: config.defaultProfile,
-          ...result,
-          bestMatch: result.matches[0] || null,
-        },
-        { mode: "inline", pretty: true, label: "profile-suggest" }
-      );
+      const store = buildStoreFromOptions(opts);
+      await emitOutput(store, {
+        ok: true,
+        configPath,
+        defaultProfile: config.defaultProfile,
+        ...result,
+        bestMatch: result.matches[0] || null,
+      }, opts, { mode: opts.resultMode, label: "profile-suggest", pretty: !!opts.pretty });
     });
 
   profile
     .command("show [id]")
     .description("Show one profile (redacted)")
     .option("--config <path>", "Config file path", defaultConfigPath())
+    .option("--output <format>", "Output format: json|ndjson", "json")
+    .option("--result-mode <mode>", "Result mode: auto|inline|file", "auto")
+    .option("--inline-max-bytes <n>", "Max inline JSON payload size", "12000")
+    .option("--tmp-dir <path>", "Directory for large result files")
+    .option("--pretty", "Pretty-print JSON output", false)
     .action(async (id, opts) => {
       const configPath = path.resolve(opts.config || defaultConfigPath());
       const config = await loadConfig(configPath);
       const profileData = getProfile(config, id);
-      const store = new ResultStore({ pretty: true });
-      await store.emit(
-        {
-          ok: true,
-          configPath,
-          profile: redactProfile(profileData),
-        },
-        { mode: "inline", pretty: true, label: "profile-show" }
-      );
+      const store = buildStoreFromOptions(opts);
+      await emitOutput(store, {
+        ok: true,
+        configPath,
+        profile: redactProfile(profileData),
+      }, opts, { mode: opts.resultMode, label: "profile-show", pretty: !!opts.pretty });
     });
 
   profile
@@ -726,6 +844,7 @@ export async function run(argv = process.argv) {
   tools
     .command("contract [name]")
     .description("Show tool contract (signature, usage, best practices)")
+    .option("--pretty", "Pretty-print JSON output", false)
     .action(async (name, opts, cmd) => {
       const merged = { ...cmd.parent.opts(), ...opts };
       const store = buildStoreFromOptions(merged);
@@ -789,8 +908,11 @@ export async function run(argv = process.argv) {
       if (
         sectionName === "quick-start-agent" ||
         sectionName === "quickstart-agent" ||
+        sectionName === "quick-start" ||
         sectionName === "quickstart" ||
-        sectionName === "setup"
+        sectionName === "setup" ||
+        sectionName === "agent" ||
+        sectionName === "onboarding"
       ) {
         await emitOutput(
           store,
@@ -823,11 +945,21 @@ export async function run(argv = process.argv) {
   );
 
   invoke.action(async (tool, opts) => {
-    const runtime = await getRuntime(opts);
-    const store = buildStoreFromOptions(opts);
     const args = (await parseJsonArg({ json: opts.args, file: opts.argsFile, name: "args" })) || {};
+    const resolution = resolveToolInvocation(tool, args);
+    const runtime = await getRuntime(opts, undefined, {
+      tool: resolution.resolvedName,
+      args: resolution.args,
+    });
+    const store = buildStoreFromOptions(opts);
     const result = await invokeTool(runtime, tool, args);
-    await emitOutput(store, result, opts, {
+    const output = runtime.profileSelection?.autoSelected
+      ? {
+        ...result,
+        profileRouting: runtime.profileSelection,
+      }
+      : result;
+    await emitOutput(store, output, opts, {
       label: `tool-${tool.replace(/\./g, "-")}`,
       mode: opts.resultMode,
     });
@@ -855,19 +987,25 @@ export async function run(argv = process.argv) {
     const store = buildStoreFromOptions(opts);
     const clientCache = new Map();
 
-    async function runtimeForProfile(profileId) {
-      const selected = getProfile(config, profileId || opts.profile);
-      if (!clientCache.has(selected.id)) {
+    async function runtimeForProfile(profileId, context = {}) {
+      const selected = getProfile(config, profileId || opts.profile, {
+        query: buildProfileRoutingQuery(context),
+        allowAutoSelect: isLikelyReadOnlyToolName(context.tool, context.args),
+        suggestionLimit: 3,
+      });
+      const { selection: profileSelection, ...storedProfile } = selected;
+      if (!clientCache.has(storedProfile.id)) {
         const hydrated = hydrateProfileFromKeychain({
           configPath,
-          profile: selected,
+          profile: storedProfile,
         });
-        clientCache.set(selected.id, {
+        clientCache.set(storedProfile.id, {
           profile: hydrated,
           client: new OutlineClient(hydrated),
+          profileSelection,
         });
       }
-      return clientCache.get(selected.id);
+      return clientCache.get(storedProfile.id);
     }
 
     const parallel = toInteger(opts.parallel, 4);
@@ -879,7 +1017,11 @@ export async function run(argv = process.argv) {
         if (!operation.tool) {
           throw new CliError(`Operation at index ${index} is missing tool`);
         }
-        const runtime = await runtimeForProfile(operation.profile);
+        const resolution = resolveToolInvocation(operation.tool, operation.args || {});
+        const runtime = await runtimeForProfile(operation.profile, {
+          tool: resolution.resolvedName,
+          args: resolution.args,
+        });
         const payload = await invokeTool(runtime, operation.tool, operation.args || {});
         const mode = (opts.itemEnvelope || "compact").toLowerCase();
         const compactResult =
@@ -895,9 +1037,11 @@ export async function run(argv = process.argv) {
         return {
           index,
           tool: operation.tool,
+          ...(payload?.tool && payload.tool !== operation.tool ? { resolvedTool: payload.tool } : {}),
           profile: runtime.profile.id,
           ok: true,
           result: mode === "full" ? payload : compactResult,
+          ...(runtime.profileSelection?.autoSelected ? { profileRouting: runtime.profileSelection } : {}),
           ...(mode === "full" || Object.keys(compactMeta).length === 0 ? {} : { meta: compactMeta }),
         };
       } catch (err) {
@@ -945,7 +1089,7 @@ export async function run(argv = process.argv) {
       const merged = { ...cmd.parent.opts(), ...opts };
       const store = buildStoreFromOptions(merged);
       const content = await store.read(file);
-      process.stdout.write(content.content);
+      safeWrite(process.stdout, content.content);
     });
 
   tmp
@@ -973,7 +1117,7 @@ export async function run(argv = process.argv) {
     await program.parseAsync(argv);
   } catch (err) {
     const output = formatError(err);
-    process.stderr.write(`${JSON.stringify(output, null, 2)}\n`);
+    safeWrite(process.stderr, `${JSON.stringify(output, null, 2)}\n`, process.exitCode || 1);
     process.exitCode = process.exitCode || 1;
   }
 }