@devosurf/tesser 0.1.0-alpha.3 → 0.1.0-alpha.4

package/dist/index.js

@@ -1,8 +1,8 @@
 // packages/cli/src/index.ts
 import { execFile as execFile2 } from "node:child_process";
-import { readFileSync as readFileSync4 } from "node:fs";
+import { readFileSync as readFileSync5 } from "node:fs";
 import { promisify as promisify2 } from "node:util";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 
 // packages/sdk/src/internal/codec.ts
 var NotSerializableError = class extends TypeError {
@@ -126,14 +126,14 @@ var UNIT_MS = {
   w: 6048e5
 };
 var PART = /(\d+(?:\.\d+)?)(ms|s|m|h|d|w)/g;
-function parseDuration(input, what = "duration") {
-  if (typeof input === "number") {
-    if (!Number.isFinite(input) || input < 0) {
-      throw new TypeError(`${what}: expected a non-negative number of ms, got ${input}`);
+function parseDuration(input2, what = "duration") {
+  if (typeof input2 === "number") {
+    if (!Number.isFinite(input2) || input2 < 0) {
+      throw new TypeError(`${what}: expected a non-negative number of ms, got ${input2}`);
     }
-    return input;
+    return input2;
   }
-  const s = input.trim();
+  const s = input2.trim();
   let total = 0;
   let matchedLen = 0;
   for (const m of s.matchAll(PART)) {
@@ -142,7 +142,7 @@ function parseDuration(input, what = "duration") {
   }
   if (matchedLen === 0 || matchedLen !== s.replace(/\s+/g, "").length) {
     throw new TypeError(
-      `${what}: "${input}" is not a duration \u2014 use forms like "250ms", "30s", "5m", "1h30m", "2d"`
+      `${what}: "${input2}" is not a duration \u2014 use forms like "250ms", "30s", "5m", "1h30m", "2d"`
     );
   }
   return Math.round(total);
@@ -251,7 +251,7 @@ function buildConnectorClient(connector, invoke) {
     for (const [key, child] of Object.entries(tree)) {
       const childPath = [...path, key];
       if (isAction(child)) {
-        node[key] = (input) => invoke(childPath, child, input);
+        node[key] = (input2) => invoke(childPath, child, input2);
       } else {
         node[key] = walk(child, childPath);
       }
@@ -469,7 +469,7 @@ function buildOperators(def, ctx, callModel) {
   const usage = { tokens: 0, outputTokens: 0 };
   const out = {};
   for (const [operatorKey, op] of Object.entries(def.operators ?? {})) {
-    out[operatorKey] = (input) => executeOperator({ def, ctx, operatorKey, op, input, usage, callModel });
+    out[operatorKey] = (input2) => executeOperator({ def, ctx, operatorKey, op, input: input2, usage, callModel });
   }
   return Object.freeze(out);
 }
@@ -664,8 +664,8 @@ function buildHarnesses(def, _ctx, callHarness) {
         if (!request.output) throw new TerminalError(`harness.${harnessKey}: output schema is required`);
         const raw = await callHarness({ automationId: def.id, harnessKey, harness: h, request });
         const serial = toSerializable2(raw, `harness.${harnessKey} result`);
-        const output = await validateSchema(request.output, serial.output, `harness.${harnessKey} output`);
-        return { ...serial, output: toSerializable2(output, `harness.${harnessKey} output`) };
+        const output2 = await validateSchema(request.output, serial.output, `harness.${harnessKey} output`);
+        return { ...serial, output: toSerializable2(output2, `harness.${harnessKey} output`) };
       }
     };
   }
@@ -702,14 +702,18 @@ var EXIT = {
 
 // packages/cli/src/output.ts
 var Output = class {
-  constructor(json) {
-    this.json = json;
+  format;
+  constructor(formatOrJson) {
+    this.format = typeof formatOrJson === "boolean" ? formatOrJson ? "json" : "text" : formatOrJson;
+  }
+  get json() {
+    return this.format !== "text";
   }
-  json;
   /** Emit the command's data result. `human` renders the no-JSON form. */
   data(value, human) {
     if (this.json) {
-      process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+      const pretty = this.format === "json";
+      process.stdout.write(JSON.stringify(value, null, pretty ? 2 : 0) + "\n");
     } else {
       process.stdout.write((human ? human(value) : JSON.stringify(value, null, 2)) + "\n");
     }
@@ -720,7 +724,8 @@ var Output = class {
   }
   fail(code, message, extra) {
     if (this.json) {
-      process.stdout.write(JSON.stringify({ error: { code, message, ...extra } }, null, 2) + "\n");
+      const pretty = this.format === "json";
+      process.stdout.write(JSON.stringify({ error: { code, message, ...extra } }, null, pretty ? 2 : 0) + "\n");
     } else {
       process.stderr.write(`error: ${message}
 `);
@@ -857,9 +862,214 @@ function resolveTarget(opts) {
 }
 
 // packages/cli/src/login.ts
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stderr as output } from "node:process";
 function resolveLoginInstance(cmdOpts, globalOpts) {
   return cmdOpts.url ?? cmdOpts.instance ?? globalOpts.url ?? DEFAULT_INSTANCE_URL;
 }
+async function resolveLoginInputs(cmdOpts, globalOpts) {
+  if ((cmdOpts.token !== void 0 || globalOpts.token !== void 0) && cmdOpts.tokenStdin === true) {
+    throw new CliError(EXIT.USAGE, "use either --token/--token-stdin, not both");
+  }
+  const token = cmdOpts.token ?? globalOpts.token ?? (cmdOpts.tokenStdin === true ? await readTrimmedStdin("token") : void 0);
+  const instance = resolveLoginInstance(cmdOpts, globalOpts);
+  if (token !== void 0 && token.length > 0) return { instance, token };
+  if (isInteractive()) {
+    const promptedInstance = await promptLine("Instance URL", instance);
+    const promptedToken = await promptSecret("API token");
+    if (promptedToken.length === 0) throw new CliError(EXIT.USAGE, "empty API token");
+    return { instance: promptedInstance || instance, token: promptedToken };
+  }
+  throw new CliError(
+    EXIT.USAGE,
+    "missing API token \u2014 pass --token-stdin, set TESSER_TOKEN, or run `tesser login` in an interactive terminal"
+  );
+}
+function isInteractive() {
+  return input.isTTY === true && output.isTTY === true;
+}
+async function readTrimmedStdin(label) {
+  const chunks = [];
+  for await (const chunk of input) chunks.push(chunk);
+  const value = Buffer.concat(chunks).toString("utf8").trim();
+  if (value.length === 0) throw new CliError(EXIT.USAGE, `empty ${label} on stdin`);
+  return value;
+}
+async function promptLine(label, defaultValue) {
+  const rl = createInterface({ input, output });
+  try {
+    const suffix = defaultValue ? ` [${defaultValue}]` : "";
+    return (await rl.question(`${label}${suffix}: `)).trim() || defaultValue;
+  } finally {
+    rl.close();
+  }
+}
+async function promptSecret(label) {
+  if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== "function") {
+    throw new CliError(EXIT.USAGE, "cannot prompt for a token without an interactive terminal; use --token-stdin");
+  }
+  output.write(`${label}: `);
+  input.setRawMode(true);
+  input.resume();
+  input.setEncoding("utf8");
+  return await new Promise((resolve, reject) => {
+    let value = "";
+    const cleanup = () => {
+      input.off("data", onData);
+      input.setRawMode(false);
+      output.write("\n");
+    };
+    const onData = (char) => {
+      if (char === "") {
+        cleanup();
+        reject(new CliError(EXIT.USAGE, "login cancelled"));
+        return;
+      }
+      if (char === "\r" || char === "\n") {
+        cleanup();
+        resolve(value.trim());
+        return;
+      }
+      if (char === "\x7F" || char === "\b") {
+        value = value.slice(0, -1);
+        return;
+      }
+      value += char;
+    };
+    input.on("data", onData);
+  });
+}
+
+// packages/cli/src/completion.ts
+var COMMANDS = [
+  "schema",
+  "init",
+  "upgrade",
+  "login",
+  "link",
+  "status",
+  "test",
+  "build",
+  "dev",
+  "deploy",
+  "connect",
+  "auth",
+  "harness",
+  "secrets",
+  "runs",
+  "logs",
+  "replay",
+  "rollback",
+  "doctor",
+  "completion"
+];
+var CHILDREN = {
+  auth: ["claude-code", "pi"],
+  harness: ["connect"],
+  "harness connect": ["claude-code", "pi"],
+  secrets: ["list", "set", "rm"],
+  runs: ["list", "show", "trigger", "signal", "cancel"]
+};
+function completionScript(shell) {
+  if (shell === "bash") return bashCompletion();
+  if (shell === "zsh") return zshCompletion();
+  throw new CliError(EXIT.USAGE, "completion shell must be bash or zsh");
+}
+function bashCompletion() {
+  const commands2 = COMMANDS.join(" ");
+  const cases = Object.entries(CHILDREN).map(([parent, children]) => `    "${parent}") COMPREPLY=( $(compgen -W "${children.join(" ")}" -- "$cur") ) ;;`).join("\n");
+  return `# bash completion for tesser
+_tesser_completion() {
+  local cur prev words cword
+  _init_completion -n : || return
+  if [[ $cword -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "${commands2}" -- "$cur") )
+    return
+  fi
+  local parent="\${COMP_WORDS[1]}"
+  if [[ $cword -ge 3 ]]; then parent="\${COMP_WORDS[1]} \${COMP_WORDS[2]}"; fi
+  case "$parent" in
+${cases}
+  esac
+}
+complete -F _tesser_completion tesser
+`;
+}
+function zshCompletion() {
+  const commandLines = COMMANDS.map((command) => `    '${command}: :->${command.replace(/ /g, "-")}'`).join(" \\\n");
+  return `#compdef tesser
+_tesser() {
+  local -a commands
+  _arguments -C     '(-h --help)'{-h,--help}'[display help]'     '--json[machine output]'     '(-o --output)'{-o,--output}'[output format]:format:(auto text json ndjson)'     '1:command:->cmds'     '*::arg:->args'
+  case $state in
+    cmds)
+      _values 'tesser commands' ${commandLines}
+      ;;
+    args)
+      case $words[1] in
+        secrets) _values 'secrets commands' list set rm ;;
+        runs) _values 'runs commands' list show trigger signal cancel ;;
+        auth) _values 'auth commands' claude-code pi ;;
+        harness) _values 'harness commands' connect ;;
+      esac
+      ;;
+  esac
+}
+_tesser
+`;
+}
+
+// packages/cli/src/inputs.ts
+import { readFile } from "node:fs/promises";
+function parseJsonLiteral(value, label) {
+  try {
+    return JSON.parse(value);
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    throw new CliError(EXIT.USAGE, `invalid JSON for ${label}: ${detail}`);
+  }
+}
+async function readTextInput(pathOrDash, label) {
+  if (pathOrDash === "-") {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+  }
+  try {
+    return await readFile(pathOrDash, "utf8");
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    throw new CliError(EXIT.USAGE, `cannot read ${label} file ${pathOrDash}: ${detail}`);
+  }
+}
+async function resolveJsonInput(opts) {
+  if (opts.literal !== void 0 && opts.file !== void 0) {
+    throw new CliError(EXIT.USAGE, `use either --${opts.label} or --${opts.label}-file, not both`);
+  }
+  if (opts.literal !== void 0) return parseJsonLiteral(opts.literal, `--${opts.label}`);
+  if (opts.file !== void 0) return parseJsonLiteral(await readTextInput(opts.file, `--${opts.label}`), `--${opts.label}-file`);
+  return void 0;
+}
+function parseIntOption(value, label, opts = {}) {
+  if (!/^\d+$/.test(value)) throw new CliError(EXIT.USAGE, `${label} must be an integer`);
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) throw new CliError(EXIT.USAGE, `${label} is too large`);
+  if (opts.min !== void 0 && parsed < opts.min) throw new CliError(EXIT.USAGE, `${label} must be >= ${opts.min}`);
+  if (opts.max !== void 0 && parsed > opts.max) throw new CliError(EXIT.USAGE, `${label} must be <= ${opts.max}`);
+  return parsed;
+}
+function projectFields(items, fieldsCsv) {
+  if (fieldsCsv === void 0 || fieldsCsv.trim() === "") return items;
+  const fields = fieldsCsv.split(",").map((field) => field.trim()).filter(Boolean);
+  if (fields.length === 0) return items;
+  return items.map((item) => {
+    const out = {};
+    for (const field of fields) {
+      if (field in item) out[field] = item[field];
+    }
+    return out;
+  });
+}
 
 // packages/cli/src/project.ts
 import { mkdtempSync, existsSync as existsSync2, readdirSync, statSync } from "node:fs";
@@ -1074,22 +1284,109 @@ Then rerun: tesser deploy${opts.local ? " --local" : ""}`
   throw new CliError(EXIT.ERROR, "timed out waiting for the deploy to settle", { last });
 }
 
+// packages/cli/src/commands/doctor.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "node:fs";
+import { join as join3 } from "node:path";
+async function doctor(out, opts) {
+  const checks = [];
+  checks.push({
+    name: "project",
+    ok: opts.target.projectRoot !== null,
+    severity: opts.target.projectRoot ? "info" : "warning",
+    message: opts.target.projectRoot ? `Project ${opts.target.project ?? "(unnamed)"} found` : "No tesser.json found from this directory",
+    ...opts.target.projectRoot ? {} : { hint: "Run inside a Tesser Project, or create one with `tesser init <name>`." }
+  });
+  checks.push({
+    name: "auth-token",
+    ok: opts.target.token !== void 0,
+    severity: opts.target.token ? "info" : "warning",
+    message: opts.target.token ? "API token is configured" : "No API token configured",
+    ...opts.target.token ? {} : { hint: "Run `tesser login` or set TESSER_TOKEN." }
+  });
+  if (opts.target.projectRoot) {
+    const pkgPath = join3(opts.target.projectRoot, "package.json");
+    const lockPath = join3(opts.target.projectRoot, "pnpm-lock.yaml");
+    checks.push({
+      name: "package-json",
+      ok: existsSync3(pkgPath),
+      severity: existsSync3(pkgPath) ? "info" : "warning",
+      message: existsSync3(pkgPath) ? "package.json exists" : "package.json missing"
+    });
+    checks.push({
+      name: "pnpm-lock",
+      ok: existsSync3(lockPath),
+      severity: existsSync3(lockPath) ? "info" : "warning",
+      message: existsSync3(lockPath) ? "pnpm-lock.yaml exists" : "pnpm-lock.yaml missing",
+      ...existsSync3(lockPath) ? {} : { hint: "Run `pnpm install` and commit pnpm-lock.yaml for reproducible Instance builds." }
+    });
+    if (existsSync3(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync2(pkgPath, "utf8"));
+        const pinned = pkg.dependencies?.["@devosurf/tesser-sdk"] ?? pkg.devDependencies?.["@devosurf/tesser"];
+        checks.push({
+          name: "tesser-pins",
+          ok: typeof pinned === "string" && pinned.length > 0 && pinned !== "latest",
+          severity: typeof pinned === "string" && pinned.length > 0 && pinned !== "latest" ? "info" : "warning",
+          message: pinned ? `Tesser package pin detected (${pinned})` : "No Tesser package pin detected",
+          ...pinned && pinned !== "latest" ? {} : { hint: "Run `tesser upgrade` with the target CLI version." }
+        });
+      } catch (cause) {
+        checks.push({ name: "package-json-parse", ok: false, severity: "warning", message: `package.json is not valid JSON: ${String(cause)}` });
+      }
+    }
+  }
+  let network;
+  if (opts.network && opts.target.token) {
+    try {
+      network = { ok: true, health: await opts.client.get("/health") };
+      checks.push({ name: "instance-health", ok: true, severity: "info", message: `Instance reachable at ${opts.target.url}` });
+    } catch (cause) {
+      const error = cause instanceof Error ? cause.message : String(cause);
+      network = { ok: false, error };
+      checks.push({
+        name: "instance-health",
+        ok: false,
+        severity: "error",
+        message: error,
+        hint: "Check --url/TESSER_URL and the API token, or rerun with --no-network for local checks only."
+      });
+    }
+  }
+  const report = {
+    ok: checks.every((check) => check.severity !== "error" && check.ok),
+    cliVersion: opts.version,
+    node: process.version,
+    cwd: process.cwd(),
+    project: opts.target.project ?? null,
+    projectRoot: opts.target.projectRoot,
+    instance: opts.target.url,
+    auth: { tokenPresent: opts.target.token !== void 0 },
+    checks,
+    ...network !== void 0 ? { network } : {}
+  };
+  out.data(report, (r) => {
+    const lines = [`Tesser CLI ${r.cliVersion}`, `instance: ${r.instance}`, `project: ${r.project ?? "(none)"}`];
+    for (const check of r.checks) lines.push(`${check.ok ? "ok" : check.severity}: ${check.name} \u2014 ${check.message}${check.hint ? ` (${check.hint})` : ""}`);
+    return lines.join("\n");
+  });
+}
+
 // packages/cli/src/commands/dev.ts
 import { randomBytes } from "node:crypto";
 import { spawn as spawn2 } from "node:child_process";
-import { existsSync as existsSync3, watch } from "node:fs";
-import { join as join3, dirname as dirname2 } from "node:path";
+import { existsSync as existsSync4, watch } from "node:fs";
+import { join as join4, dirname as dirname2 } from "node:path";
 function findServerBin(start) {
   const envBin = process.env["TESSER_SERVER_BIN"];
-  if (envBin && existsSync3(envBin)) {
+  if (envBin && existsSync4(envBin)) {
     return envBin.endsWith(".mjs") || envBin.endsWith(".js") ? [process.execPath, envBin] : [envBin];
   }
   let dir = start;
   for (; ; ) {
-    const entry = join3(dir, "node_modules", "@devosurf", "tesser-server", "bin", "tesser-server.mjs");
-    if (existsSync3(entry)) return [process.execPath, entry];
-    const shim = join3(dir, "node_modules", ".bin", "tesser-server");
-    if (existsSync3(shim)) return [shim];
+    const entry = join4(dir, "node_modules", "@devosurf", "tesser-server", "bin", "tesser-server.mjs");
+    if (existsSync4(entry)) return [process.execPath, entry];
+    const shim = join4(dir, "node_modules", ".bin", "tesser-server");
+    if (existsSync4(shim)) return [shim];
     const parent = dirname2(dir);
     if (parent === dir) return null;
     dir = parent;
@@ -1111,7 +1408,7 @@ async function dev(out, projectRoot, project, opts) {
     env: {
       ...process.env,
       PORT: String(port),
-      TESSER_DATA_DIR: join3(projectRoot, ".tesser"),
+      TESSER_DATA_DIR: join4(projectRoot, ".tesser"),
       TESSER_BOOTSTRAP_TOKEN: token,
       TESSER_BASE_URL: url,
       DATABASE_URL: ""
@@ -1161,7 +1458,7 @@ async function dev(out, projectRoot, project, opts) {
   await syncOnce();
   if (opts.watch !== false) {
     let timer = null;
-    watch(join3(projectRoot, "automations"), { recursive: true }, () => {
+    watch(join4(projectRoot, "automations"), { recursive: true }, () => {
       if (timer) clearTimeout(timer);
       timer = setTimeout(() => {
         out.log("change detected \u2014 redeploying\u2026");
@@ -1177,12 +1474,12 @@ async function dev(out, projectRoot, project, opts) {
 }
 
 // packages/cli/src/commands/init.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "node:fs";
-import { join as join5 } from "node:path";
+import { existsSync as existsSync6, mkdirSync as mkdirSync3, readdirSync as readdirSync2, writeFileSync as writeFileSync3 } from "node:fs";
+import { join as join6 } from "node:path";
 
 // packages/cli/src/commands/project-docs.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join4 } from "node:path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join5 } from "node:path";
 var TESSER_DEPENDENCIES = ["@devosurf/tesser-sdk", "@devosurf/tesser-connectors"];
 var TESSER_DEV_DEPENDENCIES = ["@devosurf/tesser", "@devosurf/tesser-server", "@devosurf/tesser-testing"];
 var GENERATED_DOC_PATHS = [
@@ -1213,13 +1510,13 @@ function projectPackageJson(name, version) {
   };
 }
 function writeProjectAgentInstructions(root, projectName, version, opts) {
-  const path = join4(root, "AGENTS.md");
-  if (!opts.overwrite && existsSync4(path)) return false;
+  const path = join5(root, "AGENTS.md");
+  if (!opts.overwrite && existsSync5(path)) return false;
   writeFileSync2(path, projectAgentsMd(projectName, version));
   return true;
 }
 function writeTesserGeneratedDocs(root, projectName, version) {
-  const docsDir = join4(root, ".tesser", "docs");
+  const docsDir = join5(root, ".tesser", "docs");
   mkdirSync2(docsDir, { recursive: true });
   const docs = {
     "manifest.json": JSON.stringify(
@@ -1240,7 +1537,7 @@ function writeTesserGeneratedDocs(root, projectName, version) {
     "connectors.md": connectorsReferenceMd(version)
   };
   for (const [file, content] of Object.entries(docs)) {
-    writeFileSync2(join4(docsDir, file), content);
+    writeFileSync2(join5(docsDir, file), content);
   }
   return [...GENERATED_DOC_PATHS];
 }
@@ -1256,7 +1553,7 @@ function tesserGitignore() {
 `;
 }
 function ensureTesserDocsGitignore(root) {
-  const path = join4(root, ".gitignore");
+  const path = join5(root, ".gitignore");
   const block = `
 # Tesser local runtime state from \`tesser dev\`; keep generated agent docs committed.
 .tesser/*
@@ -1264,21 +1561,21 @@ function ensureTesserDocsGitignore(root) {
 !.tesser/docs/
 !.tesser/docs/**
 `;
-  if (!existsSync4(path)) {
+  if (!existsSync5(path)) {
     writeFileSync2(path, tesserGitignore());
     return true;
   }
-  const existing = readFileSync2(path, "utf8");
+  const existing = readFileSync3(path, "utf8");
   if (existing.includes("!.tesser/docs/**")) return false;
   writeFileSync2(path, existing.replace(/\s*$/, "\n") + block);
   return true;
 }
 function upgradeProject(out, project, version) {
-  const packagePath = join4(project.root, "package.json");
-  if (!existsSync4(packagePath)) {
+  const packagePath = join5(project.root, "package.json");
+  if (!existsSync5(packagePath)) {
     throw new CliError(EXIT.USAGE, "not inside a package-backed Tesser project (missing package.json)");
   }
-  const pkg = JSON.parse(readFileSync2(packagePath, "utf8"));
+  const pkg = JSON.parse(readFileSync3(packagePath, "utf8"));
   pinTesserPackages(pkg, version);
   writeFileSync2(packagePath, JSON.stringify(pkg, null, 2) + "\n");
   const docs = writeTesserGeneratedDocs(project.root, project.name, version);
@@ -1377,7 +1674,7 @@ Commit \`package.json\`, \`pnpm-lock.yaml\`, \`.tesser/docs/\`, and any Automati
 function cliReferenceMd(version) {
   return `# Tesser CLI reference
 
-Generated for \`@devosurf/tesser@${version}\`. The CLI is the agent interface: prefer \`--json\` when output will drive follow-up actions. stdout is data; stderr is logs/progress.
+Generated for \`@devosurf/tesser@${version}\`. The CLI is the agent interface: prefer \`--output json\` (or \`--json\`) when output will drive follow-up actions. stdout is data; stderr is logs/progress. \`tesser schema\` prints the machine-readable command contract without auth or network.
 
 ## Install and invoke
 
@@ -1396,7 +1693,7 @@ tesser init my-project --instance https://tesser.example.com
 cd my-project
 pnpm install                    # creates pnpm-lock.yaml; commit it
 git init && git add -A && git commit -m init
-tesser login --url https://tesser.example.com --token "$TESSER_TOKEN"
+printf '%s' "$TESSER_TOKEN" | tesser login --url https://tesser.example.com --token-stdin
 tesser link --json              # registers this Project on the Instance
 tesser test --json
 tesser build --json
@@ -1405,9 +1702,9 @@ tesser deploy --json
 
 ## Commands agents commonly use
 
-- \`tesser init <name> [--dir DIR] [--instance URL]\` \u2014 scaffold a Project.
+- \`tesser init <name> [--dir DIR] [--instance URL] [--force]\` \u2014 scaffold a Project; refuses non-empty directories unless forced.
 - \`tesser upgrade\` \u2014 pin Tesser packages to this CLI version and refresh \`.tesser/docs/\`. To target a version: \`npx @devosurf/tesser@<version> upgrade\`.
-- \`tesser login --url URL --token TOKEN\` \u2014 verify and store a profile. Prefer \`TESSER_TOKEN\` over pasting tokens into chat.
+- \`printf '%s' "$TESSER_TOKEN" | tesser login --url URL --token-stdin\` \u2014 verify and store a profile. Humans may run \`tesser login\` and use masked prompts; avoid \`--token\` because argv can leak.
 - \`tesser link [--repo URL] --json\` \u2014 register the Project and print deploy-key/webhook setup data. CLI output must not include private keys or webhook secrets.
 - \`tesser status --json\` \u2014 instance health and deploy state.
 - \`tesser test [--smoke-only] [--automation ID] --json\` \u2014 fast local tests plus generated smoke tests.
@@ -1416,13 +1713,17 @@ tesser deploy --json
 - \`tesser deploy [--ref REF] [--local] [--no-wait] --json\` \u2014 server-side build/test/promotion. Exit code 4 means halted on missing credentials; run \`tesser connect\`.
 - \`tesser connect [--wait] [--status TOKEN] --json\` \u2014 mint or poll the human connect link. The human supplies credentials in the browser; the agent only sees readiness.
 - \`tesser secrets list --json\`, \`tesser secrets rm <name> --json\`, \`printenv MY_SECRET | tesser secrets set <name> --value-stdin --json\`. Never put secret values in argv.
-- \`tesser runs list|show|trigger|signal|cancel --json\`; \`tesser logs <runId> [--follow]\`; \`tesser replay <runId>\`.
+- \`tesser schema --json\` \u2014 inspect commands, arguments, outputs, exit codes, and mutation markers.
+- \`tesser doctor --json\` \u2014 local Project/auth/package preflight; use \`--no-network\` for offline checks.
+- \`tesser completion bash|zsh\` \u2014 print shell completion scripts.
+- \`tesser runs list [--limit N] [--offset N] [--fields id,status] --json\`; \`tesser runs trigger <automation> --input-file - --json\`; \`tesser runs signal <runId> <name> --payload-file - --json\`; \`tesser runs show|cancel --json\`; \`tesser logs <runId> [--follow] [--limit N] [--offset N] [-o ndjson]\`; \`tesser replay <runId>\`.
+- \`tesser harness connect claude-code --connect CONNECT_URL\` and \`tesser harness connect pi --connect CONNECT_URL\` \u2014 preferred Harness credential namespace; legacy \`tesser auth ...\` aliases remain.
 - \`tesser rollback <automation> --to <version> --json\` \u2014 alias re-point; no rebuild.
 
 ## Credential safety
 
 - Do not ask the user to paste secrets into chat. Use masked secret prompts where your harness supports them, or ask the human to run a command locally.
-- Never pass raw secret values as CLI arguments. Use environment variables, profiles, connect links, OAuth, or \`--value-stdin\`.
+- Never pass raw secret values as CLI arguments. Use masked prompts, environment variables, profiles, connect links, OAuth, \`--token-stdin\`, \`--value-stdin\`, or \`--*-file -\` stdin lanes.
 - Treat connect links and status tokens as sensitive operational material.
 
 ## Deploy hygiene
@@ -1520,83 +1821,7 @@ For Connector calls, mock the Step result by Step name. Replay fixtures produced
 `;
 }
 function connectorsReferenceMd(version) {
-  return `# Tesser Connector reference
-
-Generated for \`@devosurf/tesser-connectors@${version}\`. A Connector is a typed integration; a Connection is an authed runtime instance injected by the Credential broker.
-
-## Available connector imports
-
-\`\`\`ts
-import {
-  anthropic,
-  claudeCode,
-  github,
-  gmail,
-  googleCalendar,
-  googleDocs,
-  googleDrive,
-  googleSheets,
-  http,
-  outlookMail,
-  pi,
-  resend,
-  slack,
-} from "@devosurf/tesser-connectors";
-\`\`\`
-
-Only import Connectors that the Automation declares in \`connections: { ... }\`.
-
-## Pattern
-
-\`\`\`ts
-import { defineAutomation, onSchedule } from "@devosurf/tesser-sdk";
-import { github, slack } from "@devosurf/tesser-connectors";
-import { z } from "zod";
-
-export default defineAutomation({
-  id: "digest",
-  trigger: onSchedule({ cron: "0 9 * * *", tz: "UTC" }),
-  connections: { github, slack },
-  output: z.object({ posted: z.boolean(), count: z.number() }),
-
-  run: async (_input, ctx) => {
-    const issues = await ctx.step("fetch-open-issues", () =>
-      ctx.connections.github.issues.list({ state: "open", labels: ["bug"] }),
-    );
-
-    if (issues.length === 0) return { posted: false, count: 0 };
-
-    await ctx.step("post-to-slack", () =>
-      ctx.connections.slack.chat.postMessage({ channel: "#ops", text: \`\${issues.length} bugs\` }),
-    );
-
-    return { posted: true, count: issues.length };
-  },
-});
-\`\`\`
-
-## Common Actions
-
-- \`ctx.connections.http.get({ url, headers?, query? })\` and \`ctx.connections.http.request({ method, url, headers?, query?, body?, bodyText? })\`. Generic writes are not retry-safe; still wrap them in a Step.
-- \`ctx.connections.github.issues.list({ repo?, state?, labels?, limit? })\`, \`issues.create({ repo, title, body?, labels? })\`, \`issues.comment({ repo, number, body })\`, \`repos.get({ repo })\`.
-- \`ctx.connections.slack.chat.postMessage({ channel, text, threadTs? })\` and related Slack chat/conversation/user Actions.
-- \`ctx.connections.resend.emails.send(...)\`, Gmail and Outlook Mail Actions (Outlook accepts optional \`mailbox\` for shared mailbox \`/users/{userPrincipalName}\` access), Google Calendar/Docs/Drive/Sheets Actions, Anthropic model Actions, Claude Code/Pi Harness-related Connectors: inspect package types or examples before using.
-
-## Connector triggers
-
-Some Connectors expose typed triggers, e.g. GitHub issue triggers, Slack event triggers, Gmail/Outlook mailbox poll triggers. Use the Connector's \`triggers\` constructors; do not hand-roll webhook delivery unless no Connector exists.
-
-\`\`\`ts
-trigger: github.triggers.issueOpened({ repo: "owner/repo" })
-\`\`\`
-
-## Safety rules
-
-- Connector Actions are not automatically durable. The Automation author must wrap every Action call in \`ctx.step\`.
-- The imported Connector is not a token-bearing client. The authed client exists only at \`ctx.connections.<name>\` inside \`run\`.
-- For bespoke APIs, combine \`http\` with declared \`secrets: { ... }\`; do not put API keys in source, tests, logs, CLI args, or committed env files.
-- If deploy halts on a missing Connection, surface \`tesser connect\` output to the human. The agent must not complete OAuth or paste raw secrets itself.
-`;
+  return '# Tesser Connector reference\n\nGenerated for `@devosurf/tesser-connectors@__VERSION__`. This file is intentionally a source map, not a duplicated API reference. The installed Connector package is the authoritative version-pinned reference. Do not rely on training data, memory, or hand-written summaries.\n\n## Hard rule\n\nDo not guess Connector APIs from memory, training data, old examples, or web search. After `pnpm install`, inspect the installed package in `node_modules/@devosurf/tesser-connectors`.\n\n## Source-of-truth order\n\n1. Project policy: `AGENTS.md` and `.tesser/docs/connectors.md`.\n2. Connector inventory: `node_modules/@devosurf/tesser-connectors/manifest.json`.\n3. Import names: `node_modules/@devosurf/tesser-connectors/index.ts`.\n4. Exact input/output schemas, samples, triggers, provider quirks: `node_modules/@devosurf/tesser-connectors/<connector-id>/index.ts`.\n5. Provider OAuth facts: `node_modules/@devosurf/tesser-connectors/providers/*.ts` and `catalog/index.ts`.\n\nNever edit `node_modules`. Read it, then edit the Automation under `automations/<id>/` and validate with `tesser test --json` / `tesser build --json`.\n\n## Quick inspection commands\n\nRun `pnpm install` first if `node_modules` is absent.\n\n```bash\n# Barrel export names: use these names in `import { ... } from "@devosurf/tesser-connectors"`.\nsed -n \'1,180p\' node_modules/@devosurf/tesser-connectors/index.ts\n\n# Installed connector inventory with actions/triggers.\nnode - <<\'NODE\'\nconst fs = require(\'node:fs\');\nconst manifest = JSON.parse(fs.readFileSync(\'node_modules/@devosurf/tesser-connectors/manifest.json\', \'utf8\'));\nfor (const c of manifest.connectors) {\n  console.log("");\n  console.log(`${c.id}: ${c.describe}`);\n  const auth = Object.keys(c.auth ?? {});\n  if (auth.length) console.log(`  auth: ${auth.join(\', \')}`);\n  if (c.actions?.length) console.log(`  actions: ${c.actions.map((a) => `${a.path} [${a.safety}${a.retrySafe ? \', retry-safe\' : \'\'}]`).join(\', \')}`);\n  if (c.triggers?.length) console.log(`  triggers: ${c.triggers.map((t) => `${t.id} [${t.strategy}]`).join(\', \')}`);\n}\nNODE\n\n# Exact schemas for one Connector, including Zod input/output objects.\nsed -n \'1,260p\' node_modules/@devosurf/tesser-connectors/outlook-mail/index.ts\n```\n\n## Authoring pattern\n\n```ts\nimport { defineAutomation, onSchedule } from "@devosurf/tesser-sdk";\nimport { github, slack } from "@devosurf/tesser-connectors";\nimport { z } from "zod";\n\nexport default defineAutomation({\n  id: "digest",\n  trigger: onSchedule({ cron: "0 9 * * *", tz: "UTC" }),\n  connections: { github, slack },\n  output: z.object({ posted: z.boolean(), count: z.number() }),\n\n  run: async (_input, ctx) => {\n    const issues = await ctx.step("fetch-open-issues", () =>\n      ctx.connections.github.issues.list({ state: "open", labels: ["bug"] }),\n    );\n\n    if (issues.length === 0) return { posted: false, count: 0 };\n\n    await ctx.step("post-to-slack", () =>\n      ctx.connections.slack.chat.postMessage({ channel: "#ops", text: `${issues.length} bugs` }),\n    );\n\n    return { posted: true, count: issues.length };\n  },\n});\n```\n\n## Rules that matter more than the Connector API\n\n- A Connector import is not an authed client. It is a typed requirement declaration.\n- Runtime calls go through `ctx.connections.<connection-key>` inside `run`.\n- Every Connector Action call must be inside `ctx.step(...)`.\n- Declare raw credentials separately with `secrets: { name: secret({ describe: "..." }) }`.\n- The Credential broker injects values at runtime; agents must never read or print tokens/secrets.\n- Deploy halts on missing Connections or Secrets; a human completes the connect link.\n\n## Connector ids currently shipped in this package\n\nRead `manifest.json` for the authoritative list. Current ids include core HTTP/email/repo/chat/calendar/document/spreadsheet/model/harness Connectors such as `http`, `github`, `slack`, `resend`, `gmail`, `outlook-mail`, Google Connectors, and Harness/model Connectors. Do not hardcode this list in Automations or docs; inspect the installed manifest.\n'.replaceAll("__VERSION__", version);
 }
 
 // packages/cli/src/commands/init.ts
@@ -1628,17 +1853,23 @@ function init(out, name, opts, version) {
   if (!/^[a-z][a-z0-9-]{0,63}$/.test(name)) {
     throw new CliError(EXIT.USAGE, "project name must be kebab-case");
   }
-  const root = join5(opts.dir ?? process.cwd(), name);
-  if (existsSync5(join5(root, "tesser.json"))) {
-    throw new CliError(EXIT.CONFLICT, `${root} is already a Tesser project`);
+  const root = join6(opts.dir ?? process.cwd(), name);
+  if (existsSync6(root) && !opts.force) {
+    if (existsSync6(join6(root, "tesser.json"))) {
+      throw new CliError(EXIT.CONFLICT, `${root} is already a Tesser project`);
+    }
+    const entries = readdirSync2(root).filter((entry) => entry !== ".DS_Store");
+    if (entries.length > 0) {
+      throw new CliError(EXIT.CONFLICT, `${root} is not empty \u2014 choose a new name or pass --force to write into it`);
+    }
   }
-  mkdirSync3(join5(root, "automations", "hello"), { recursive: true });
+  mkdirSync3(join6(root, "automations", "hello"), { recursive: true });
   writeFileSync3(
-    join5(root, "tesser.json"),
+    join6(root, "tesser.json"),
     JSON.stringify({ project: name, ...opts.instance !== void 0 ? { instance: opts.instance } : {} }, null, 2) + "\n"
   );
   writeFileSync3(
-    join5(root, "package.json"),
+    join6(root, "package.json"),
     JSON.stringify(
       projectPackageJson(name, version),
       null,
@@ -1646,7 +1877,7 @@ function init(out, name, opts, version) {
     ) + "\n"
   );
   writeFileSync3(
-    join5(root, "tsconfig.json"),
+    join6(root, "tsconfig.json"),
     JSON.stringify(
       {
         compilerOptions: {
@@ -1664,16 +1895,16 @@ function init(out, name, opts, version) {
     ) + "\n"
   );
   writeFileSync3(
-    join5(root, "vitest.config.ts"),
+    join6(root, "vitest.config.ts"),
     `import { defineConfig } from "vitest/config";
 export default defineConfig({ test: { globals: true, include: ["automations/**/*.test.ts"] } });
 `
   );
-  writeFileSync3(join5(root, ".gitignore"), tesserGitignore());
+  writeFileSync3(join6(root, ".gitignore"), tesserGitignore());
   writeProjectAgentInstructions(root, name, version, { overwrite: true });
   const docs = writeTesserGeneratedDocs(root, name, version);
-  writeFileSync3(join5(root, "automations", "hello", "index.ts"), EXAMPLE_AUTOMATION);
-  writeFileSync3(join5(root, "automations", "hello", "index.test.ts"), EXAMPLE_TEST);
+  writeFileSync3(join6(root, "automations", "hello", "index.ts"), EXAMPLE_AUTOMATION);
+  writeFileSync3(join6(root, "automations", "hello", "index.test.ts"), EXAMPLE_TEST);
   const next = [
     "cd " + name,
     "pnpm install",
@@ -1694,18 +1925,18 @@ next:
 }
 
 // packages/cli/src/commands/replay.ts
-import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync4, existsSync as existsSync6 } from "node:fs";
-import { join as join6 } from "node:path";
+import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync4, existsSync as existsSync7 } from "node:fs";
+import { join as join7 } from "node:path";
 async function replay(out, api2, projectRoot, runId) {
   const { replay: run } = await api2.get(`/runs/${runId}/replay`);
-  const dir = join6(projectRoot, "automations", run.automation_id);
-  if (!existsSync6(dir)) {
+  const dir = join7(projectRoot, "automations", run.automation_id);
+  if (!existsSync7(dir)) {
     throw new CliError(EXIT.NOT_FOUND, `automation directory not found locally: automations/${run.automation_id}`);
   }
   const shortId = run.id.slice(0, 8);
-  const fixtureDir = join6(dir, "__replays__");
+  const fixtureDir = join7(dir, "__replays__");
   mkdirSync4(fixtureDir, { recursive: true });
-  const fixturePath = join6(fixtureDir, `${shortId}.replay.json`);
+  const fixturePath = join7(fixtureDir, `${shortId}.replay.json`);
   writeFileSync4(
     fixturePath,
     JSON.stringify(
@@ -1723,7 +1954,7 @@ async function replay(out, api2, projectRoot, runId) {
       2
     ) + "\n"
   );
-  const testPath = join6(dir, `replay-${shortId}.test.ts`);
+  const testPath = join7(dir, `replay-${shortId}.test.ts`);
   writeFileSync4(
     testPath,
     `// Regression frozen from run ${run.id} (recorded status: ${run.status}).
@@ -1757,8 +1988,8 @@ run \`tesser test\` to execute it`
 
 // packages/cli/src/commands/test.ts
 import { execFile } from "node:child_process";
-import { existsSync as existsSync7 } from "node:fs";
-import { join as join7 } from "node:path";
+import { existsSync as existsSync8 } from "node:fs";
+import { join as join8 } from "node:path";
 import { promisify } from "node:util";
 
 // packages/testing/src/engine.ts
@@ -1977,7 +2208,7 @@ async function executeAutomation(def, opts = {}) {
           `side effects must live inside a step (ADR-0002) \u2014 wrap the call: ctx.step("name", () => ctx.connections.${fullPath}(...))`
         );
       }
-      const input2 = await validateSchema(
+      const input3 = await validateSchema(
         actionDef.input,
         rawInput ?? {},
         `${fullPath} input`
@@ -1992,7 +2223,7 @@ async function executeAutomation(def, opts = {}) {
           for (const seg of path) node = node?.[seg];
           if (node !== void 0) {
             return {
-              value: typeof node === "function" ? await node(input2) : node,
+              value: typeof node === "function" ? await node(input3) : node,
               validate: false
             };
           }
@@ -2001,7 +2232,7 @@ async function executeAutomation(def, opts = {}) {
         if (stepMock !== void 0) {
           return {
             value: typeof stepMock === "function" ? await stepMock(
-              input2,
+              input3,
               { action: actionPath, connection: connKey }
             ) : stepMock,
             validate: false
@@ -2019,16 +2250,16 @@ async function executeAutomation(def, opts = {}) {
       try {
         const { value, validate } = await resolve();
         const result = validate ? await validateSchema(actionDef.output, value, `${fullPath} sample output`) : value;
-        const record = { args: [input2], step: step.name, action: fullPath, result };
+        const record = { args: [input3], step: step.name, action: fullPath, result };
         recordCall(spyFor(step.name), record);
         recordCall(spyFor(fullPath), record);
-        connectorCalls.push({ step: step.name, action: fullPath, input: input2 });
+        connectorCalls.push({ step: step.name, action: fullPath, input: input3 });
         return result;
       } catch (err) {
-        const record = { args: [input2], step: step.name, action: fullPath, error: String(err) };
+        const record = { args: [input3], step: step.name, action: fullPath, error: String(err) };
         recordCall(spyFor(step.name), record);
         recordCall(spyFor(fullPath), record);
-        connectorCalls.push({ step: step.name, action: fullPath, input: input2 });
+        connectorCalls.push({ step: step.name, action: fullPath, input: input3 });
         throw err;
       }
     });
@@ -2193,7 +2424,7 @@ async function executeAutomation(def, opts = {}) {
     recordCall(spyFor(`harness.${harnessKey}`), { args: [request], step: step.name, result });
     return result;
   });
-  let input = opts.input;
+  let input2 = opts.input;
   const trigger = def.trigger;
   let inputSchema = def.input ?? (trigger.kind === "webhook" ? trigger.input : trigger.kind === "event" ? trigger.event?.schema : void 0);
   if (trigger.kind === "connector" && trigger.connectorId !== void 0) {
@@ -2203,16 +2434,16 @@ async function executeAutomation(def, opts = {}) {
     const decl = connector?.__connector.triggers?.[trigger.triggerId ?? ""];
     if (decl) {
       inputSchema = def.input ?? decl.output;
-      if (input === void 0) {
-        input = connector?.__connector.samples?.[`trigger:${trigger.triggerId}`];
+      if (input2 === void 0) {
+        input2 = connector?.__connector.samples?.[`trigger:${trigger.triggerId}`];
       }
     }
   }
-  if (input === void 0 && inputSchema && trigger.kind !== "schedule") {
-    input = await sampleFromSchema(inputSchema);
+  if (input2 === void 0 && inputSchema && trigger.kind !== "schedule") {
+    input2 = await sampleFromSchema(inputSchema);
   }
-  if (inputSchema && input !== void 0) {
-    input = await validateSchema(inputSchema, input, `automation "${def.id}" input`);
+  if (inputSchema && input2 !== void 0) {
+    input2 = await validateSchema(inputSchema, input2, `automation "${def.id}" input`);
   }
   const finish = (status, result, error) => {
     const stepsByName = {};
@@ -2255,11 +2486,11 @@ async function executeAutomation(def, opts = {}) {
     };
   };
   try {
-    let output = await def.run(input, ctx);
+    let output2 = await def.run(input2, ctx);
     if (def.output) {
-      output = await validateSchema(def.output, output, `automation "${def.id}" output`);
+      output2 = await validateSchema(def.output, output2, `automation "${def.id}" output`);
     }
-    return finish("completed", output);
+    return finish("completed", output2);
   } catch (err) {
     for (const item of [...undoStack].reverse()) {
       try {
@@ -2334,7 +2565,7 @@ async function smokeModelScripts(def) {
 }
 
 // packages/testing/src/cassette.ts
-import { mkdirSync as mkdirSync5, readFileSync as readFileSync3, writeFileSync as writeFileSync5 } from "node:fs";
+import { mkdirSync as mkdirSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync5 } from "node:fs";
 import { dirname as dirname3 } from "node:path";
 import { createHash } from "node:crypto";
 
@@ -2343,9 +2574,9 @@ var exec = promisify(execFile);
 function findVitest(projectRoot) {
   let dir = projectRoot;
   for (; ; ) {
-    const bin = join7(dir, "node_modules", ".bin", process.platform === "win32" ? "vitest.cmd" : "vitest");
-    if (existsSync7(bin)) return bin;
-    const parent = join7(dir, "..");
+    const bin = join8(dir, "node_modules", ".bin", process.platform === "win32" ? "vitest.cmd" : "vitest");
+    if (existsSync8(bin)) return bin;
+    const parent = join8(dir, "..");
     if (parent === dir) return null;
     dir = parent;
   }
@@ -2355,7 +2586,7 @@ async function runTests(out, projectRoot, opts) {
     (a) => opts.filter === void 0 || a.automationId === opts.filter
   );
   if (automations.length === 0) {
-    throw new CliError(EXIT.USAGE, `no automations found under ${join7(projectRoot, "automations")}`);
+    throw new CliError(EXIT.USAGE, `no automations found under ${join8(projectRoot, "automations")}`);
   }
   const report = {
     passed: true,
@@ -2442,13 +2673,309 @@ async function runTests(out, projectRoot, opts) {
   process.exit(report.passed ? EXIT.OK : EXIT.TESTS_FAILED);
 }
 
+// packages/cli/src/schema.ts
+var errorRows = [
+  ["error", EXIT.ERROR, true, "Unexpected internal error"],
+  ["usage", EXIT.USAGE, false, "Bad arguments or missing Project context"],
+  ["tests_failed", EXIT.TESTS_FAILED, false, "Local validation failed"],
+  ["halted_credentials", EXIT.HALTED_CREDENTIALS, false, "Deploy/connect halted on missing credentials"],
+  ["auth", EXIT.AUTH, false, "Cannot reach or authenticate against the Instance"],
+  ["not_found", EXIT.NOT_FOUND, false, "Requested resource does not exist"],
+  ["conflict", EXIT.CONFLICT, false, "Operation conflicts with current state"],
+  ["deploy_failed", EXIT.DEPLOY_FAILED, false, "Build, test gate, or deploy failed"]
+];
+var commands = [
+  {
+    name: "schema",
+    description: "Emit the machine-readable CLI contract without auth, config, or network",
+    mutating: false,
+    args: [{ name: "command", type: "string[]", required: false }],
+    output_fields: ["clispec", "name", "version", "global_args", "commands", "errors", "outcomes"]
+  },
+  {
+    name: "completion",
+    description: "Print a shell completion script",
+    mutating: false,
+    args: [{ name: "shell", type: "string", enum: ["bash", "zsh"], required: true }],
+    output_fields: []
+  },
+  {
+    name: "doctor",
+    description: "Agent preflight for local Project, auth, pins, and optional Instance health",
+    mutating: false,
+    args: [{ name: "--no-network", type: "boolean", required: false, default: false }],
+    output_fields: ["ok", "cliVersion", "node", "cwd", "project", "projectRoot", "instance", "auth", "checks", "network"]
+  },
+  {
+    name: "init",
+    description: "Scaffold a new Project",
+    mutating: true,
+    args: [
+      { name: "name", type: "string", required: true },
+      { name: "--dir", type: "string", required: false },
+      { name: "--instance", type: "string", required: false },
+      { name: "--force", type: "boolean", required: false, default: false }
+    ],
+    output_fields: ["created", "tesserVersion", "docs", "next"]
+  },
+  {
+    name: "upgrade",
+    description: "Pin Tesser packages to this CLI version and refresh generated Project docs",
+    mutating: true,
+    args: [],
+    output_fields: ["upgraded", "tesserVersion", "docs", "next"]
+  },
+  {
+    name: "login",
+    description: "Verify and store Instance API credentials in a local profile",
+    mutating: true,
+    args: [
+      { name: "--url", type: "string", required: false, default: "http://localhost:8377" },
+      { name: "--token-stdin", type: "boolean", required: false, default: false },
+      { name: "--token", type: "string", required: false, secret: true, deprecated: "Prefer --token-stdin" },
+      { name: "--save-profile", type: "string", required: false, default: "default" }
+    ],
+    output_fields: ["profile", "url"]
+  },
+  {
+    name: "link",
+    description: "Register this Project on the Instance and wire git-sync",
+    mutating: true,
+    args: [{ name: "--repo", type: "string", required: false }],
+    output_fields: ["id", "name", "repoUrl", "deployKeyPublic", "webhookSetupUrl"]
+  },
+  {
+    name: "status",
+    description: "Instance and Project deploy status",
+    mutating: false,
+    args: [],
+    output_fields: ["instance", "health", "status", "project", "deploy"]
+  },
+  {
+    name: "test",
+    description: "Run colocated tests plus generated smoke tests",
+    mutating: false,
+    args: [
+      { name: "--smoke-only", type: "boolean", required: false, default: false },
+      { name: "--automation", type: "string", required: false }
+    ],
+    output_fields: ["passed", "colocated", "smoke", "failures"]
+  },
+  {
+    name: "build",
+    description: "Build and statically extract automation manifests locally",
+    mutating: false,
+    args: [],
+    output_fields: ["automations"]
+  },
+  {
+    name: "dev",
+    description: "Run a local Instance with embedded Postgres and deploy-on-change",
+    mutating: true,
+    args: [
+      { name: "--port", type: "integer", required: false, default: 8377 },
+      { name: "--no-watch", type: "boolean", required: false, default: false }
+    ],
+    output_fields: []
+  },
+  {
+    name: "deploy",
+    description: "Sync git or a local tree to the Instance and promote on green",
+    mutating: true,
+    args: [
+      { name: "--ref", type: "string", required: false },
+      { name: "--local", type: "boolean", required: false, default: false },
+      { name: "--no-wait", type: "boolean", required: false, default: false }
+    ],
+    output_fields: ["status", "report", "live"]
+  },
+  {
+    name: "harness connect claude-code",
+    description: "Connect Claude Code as a brokered Harness (alias of auth claude-code)",
+    mutating: true,
+    args: [
+      { name: "--connect", type: "string", required: true },
+      { name: "--mode", type: "string", enum: ["subscription", "apiKey"], required: false, default: "subscription" },
+      { name: "--token-stdin", type: "boolean", required: false, default: false, secret: true },
+      { name: "--from-env", type: "string", required: false, secret: true },
+      { name: "--scope", type: "string", enum: ["workspace", "per_user"], required: false, default: "workspace" },
+      { name: "--end-user-id", type: "string", required: false },
+      { name: "--bin", type: "string", required: false, default: "claude" }
+    ],
+    output_fields: ["connector", "mode", "connected"]
+  },
+  {
+    name: "harness connect pi",
+    description: "Connect Pi as a brokered Harness (alias of auth pi)",
+    mutating: true,
+    args: [
+      { name: "--connect", type: "string", required: true },
+      { name: "--mode", type: "string", enum: ["anthropicOAuth", "anthropicApiKey"], required: false, default: "anthropicOAuth" },
+      { name: "--token-stdin", type: "boolean", required: false, default: false, secret: true },
+      { name: "--from-env", type: "string", required: false, secret: true },
+      { name: "--scope", type: "string", enum: ["workspace", "per_user"], required: false, default: "workspace" },
+      { name: "--end-user-id", type: "string", required: false }
+    ],
+    output_fields: ["connector", "mode", "connected"]
+  },
+  {
+    name: "connect",
+    description: "Mint or poll the human connect link for missing credentials",
+    mutating: true,
+    args: [
+      { name: "--wait", type: "boolean", required: false, default: false },
+      { name: "--status", type: "string", required: false }
+    ],
+    output_fields: ["url", "token", "requirements", "status"]
+  },
+  {
+    name: "secrets list",
+    description: "List Secret names only",
+    mutating: false,
+    args: [],
+    output_fields: ["secrets"]
+  },
+  {
+    name: "secrets set",
+    description: "Set a Secret from stdin; never accepts the value on argv",
+    mutating: true,
+    args: [
+      { name: "name", type: "string", required: true },
+      { name: "--value-stdin", type: "boolean", required: true, secret: true }
+    ],
+    output_fields: ["set", "changed"]
+  },
+  {
+    name: "secrets rm",
+    description: "Delete a Secret by name",
+    mutating: true,
+    args: [{ name: "name", type: "string", required: true }],
+    output_fields: ["deleted", "changed"]
+  },
+  {
+    name: "runs list",
+    description: "List runs with bounded output",
+    mutating: false,
+    args: [
+      { name: "--automation", type: "string", required: false },
+      { name: "--status", type: "string", required: false },
+      { name: "--limit", type: "integer", required: false, default: 25 },
+      { name: "--offset", type: "integer", required: false, default: 0 },
+      { name: "--fields", type: "string", required: false }
+    ],
+    output_fields: ["runs", "total", "limit", "offset", "truncated"]
+  },
+  {
+    name: "runs show",
+    description: "Show a run with bounded log output",
+    mutating: false,
+    args: [
+      { name: "runId", type: "string", required: true },
+      { name: "--log-limit", type: "integer", required: false, default: 100 },
+      { name: "--log-offset", type: "integer", required: false, default: 0 }
+    ],
+    output_fields: ["run", "steps", "logs", "logsTotal", "logsLimit", "logsOffset", "logsTruncated"]
+  },
+  {
+    name: "runs trigger",
+    description: "Manually trigger an Automation",
+    mutating: true,
+    args: [
+      { name: "automation", type: "string", required: true },
+      { name: "--input", type: "json", required: false },
+      { name: "--input-file", type: "path|-", required: false },
+      { name: "--env", type: "string", required: false, default: "production" }
+    ],
+    output_fields: ["runId"]
+  },
+  {
+    name: "runs signal",
+    description: "Deliver a Signal to a suspended run",
+    mutating: true,
+    args: [
+      { name: "runId", type: "string", required: true },
+      { name: "name", type: "string", required: true },
+      { name: "--payload", type: "json", required: false },
+      { name: "--payload-file", type: "path|-", required: false }
+    ],
+    output_fields: ["delivered"]
+  },
+  {
+    name: "runs cancel",
+    description: "Cancel a queued or suspended run",
+    mutating: true,
+    args: [{ name: "runId", type: "string", required: true }],
+    output_fields: ["cancelled", "changed"]
+  },
+  {
+    name: "logs",
+    description: "Print bounded run logs or follow until settle",
+    mutating: false,
+    args: [
+      { name: "runId", type: "string", required: true },
+      { name: "--follow", type: "boolean", required: false, default: false },
+      { name: "--limit", type: "integer", required: false, default: 100 },
+      { name: "--offset", type: "integer", required: false, default: 0 }
+    ],
+    output_fields: ["run", "logs", "logsTotal", "logsLimit", "logsOffset", "logsTruncated"]
+  },
+  {
+    name: "replay",
+    description: "Freeze a real run as a regression fixture and test",
+    mutating: true,
+    args: [{ name: "runId", type: "string", required: true }],
+    output_fields: ["runId", "fixture", "test"]
+  },
+  {
+    name: "rollback",
+    description: "Re-point an Automation alias to a prior immutable version",
+    mutating: true,
+    args: [
+      { name: "automation", type: "string", required: true },
+      { name: "--to", type: "integer", required: true },
+      { name: "--env", type: "string", required: false, default: "production" }
+    ],
+    output_fields: ["rolledBack", "automation", "env", "toVersion", "changed"]
+  }
+];
+function cliSchema(version, commandPrefix) {
+  const filtered = commandPrefix ? commands.filter((command) => command.name === commandPrefix || command.name.startsWith(`${commandPrefix} `)) : commands;
+  return {
+    clispec: "0.2",
+    name: "tesser",
+    version,
+    description: "Code-first, agent-native automation CLI",
+    global_args: [
+      { name: "--json", type: "boolean", default: false, description: "Alias for --output json" },
+      { name: "--output", short: "-o", type: "string", enum: ["auto", "text", "json", "ndjson"], default: "auto" },
+      { name: "--url", type: "string", required: false },
+      { name: "--token", type: "string", required: false, secret: true },
+      { name: "--profile", type: "string", required: false }
+    ],
+    commands: filtered,
+    errors: errorRows.map(([kind, exitCode, retryable, description]) => ({ kind, exit_code: exitCode, retryable, description })),
+    outcomes: []
+  };
+}
+
 // packages/cli/src/index.ts
 var exec2 = promisify2(execFile2);
 var program = new Command();
-var VERSION = JSON.parse(readFileSync4(new URL("../package.json", import.meta.url), "utf8")).version;
+var VERSION = JSON.parse(readFileSync5(new URL("../package.json", import.meta.url), "utf8")).version;
 function setup() {
   const opts = program.opts();
-  return { out: new Output(opts.json ?? false), opts };
+  return { out: new Output(resolveOutputFormat(opts)), opts };
+}
+function resolveOutputFormat(opts) {
+  if (opts.json) return "json";
+  const requested = opts.output ?? "auto";
+  if (requested === "auto") return process.stdout.isTTY ? "text" : "json";
+  return requested;
+}
+function isJsonRequestedFromArgv() {
+  const idx = process.argv.findIndex((arg) => arg === "--output" || arg === "-o");
+  const explicitOutput = idx >= 0 ? process.argv[idx + 1] : void 0;
+  return process.argv.includes("--json") || explicitOutput === "json" || explicitOutput === "ndjson";
 }
 function target(opts) {
   return resolveTarget({
@@ -2468,8 +2995,30 @@ function requireProject(opts) {
   }
   return { name: t.project, root: t.projectRoot };
 }
-program.name("tesser").version(VERSION).description("Code-first, agent-native automation. stdout = data, stderr = logs; --json everywhere.").option("--json", "machine output: one JSON document on stdout").option("--url <url>", "instance URL (overrides tesser.json / profile)").option("--token <token>", "API token (overrides TESSER_TOKEN / profile)").option("--profile <name>", "config profile");
-program.command("init").argument("<name>", "project name (kebab-case)").option("--dir <dir>", "parent directory").option("--instance <url>", "instance URL to write into tesser.json").description("scaffold a new Project (one repo of automations)").action((name, cmdOpts) => {
+program.name("tesser").version(VERSION).description("Code-first, agent-native automation. stdout = data, stderr = logs; --json everywhere.").option("--json", "machine output: one JSON document on stdout (alias for --output json)").addOption(new Option("-o, --output <format>", "output format").choices(["auto", "text", "json", "ndjson"]).default("auto")).option("--url <url>", "instance URL (overrides tesser.json / profile)").option("--token <token>", "API token (overrides TESSER_TOKEN / profile)").option("--profile <name>", "config profile").exitOverride().configureOutput({ outputError: () => {
+} }).action(() => {
+  const out = new Output(resolveOutputFormat(program.opts()));
+  if (out.json) out.fail(EXIT.USAGE, "missing command");
+  program.outputHelp({ error: true });
+  process.exit(EXIT.USAGE);
+});
+program.command("completion").argument("<shell>", "bash or zsh").description("print shell completion script").action((shell) => {
+  const { out } = setup();
+  try {
+    out.data(completionScript(shell), (script) => script.replace(/\n$/, ""));
+  } catch (err) {
+    toExit(err, out);
+  }
+});
+program.command("schema").argument("[command...]", "optional command subtree, e.g. runs list").description("emit the machine-readable CLI contract (no auth, config, or network needed)").action((parts) => {
+  const { out } = setup();
+  try {
+    out.data(cliSchema(VERSION, parts.length > 0 ? parts.join(" ") : void 0));
+  } catch (err) {
+    toExit(err, out);
+  }
+});
+program.command("init").argument("<name>", "project name (kebab-case)").option("--dir <dir>", "parent directory").option("--instance <url>", "instance URL to write into tesser.json").option("--force", "write into an existing non-empty directory").description("scaffold a new Project (one repo of automations)").action((name, cmdOpts) => {
   const { out } = setup();
   try {
     init(out, name, cmdOpts, VERSION);
@@ -2485,12 +3034,10 @@ program.command("upgrade").description("pin Tesser packages to this CLI version
     toExit(err, out);
   }
 });
-program.command("login").option("--token <token>", "API token from the instance (printed at first boot)").option("--url <url>", `instance URL (defaults to ${DEFAULT_INSTANCE_URL})`).option("--instance <url>", "deprecated alias for --url").option("--save-profile <name>", "profile name", "default").description("store instance credentials in ~/.config/tesser (or use env TESSER_TOKEN)").action(async (cmdOpts) => {
+program.command("login").option("--token <token>", "API token from the instance (discouraged: argv can leak; prefer --token-stdin)").option("--token-stdin", "read the API token from stdin").option("--url <url>", `instance URL (defaults to ${DEFAULT_INSTANCE_URL})`).option("--instance <url>", "deprecated alias for --url").option("--save-profile <name>", "profile name", "default").description("store instance credentials in ~/.config/tesser (or use env TESSER_TOKEN)").action(async (cmdOpts) => {
   const { out, opts } = setup();
   try {
-    const token = cmdOpts.token ?? opts.token;
-    if (!token) throw new CliError(EXIT.USAGE, "missing required option '--token <token>'");
-    const instance = resolveLoginInstance(cmdOpts, opts);
+    const { instance, token } = await resolveLoginInputs(cmdOpts, opts);
     const client = new ApiClient(instance, token);
     await client.get("/health");
     const config = readConfig();
@@ -2574,7 +3121,8 @@ program.command("dev").option("--port <port>", "port for the local instance", "8
   const { out, opts } = setup();
   try {
     const { name, root } = requireProject(opts);
-    await dev(out, root, name, { port: Number(cmdOpts.port), ...cmdOpts.watch === false ? { watch: false } : {} });
+    const port = parseIntOption(cmdOpts.port, "--port", { min: 1, max: 65535 });
+    await dev(out, root, name, { port, ...cmdOpts.watch === false ? { watch: false } : {} });
   } catch (err) {
     toExit(err, out);
   }
@@ -2596,6 +3144,23 @@ auth.command("pi").requiredOption("--connect <urlOrToken>", "Tesser /connect/<to
     toExit(err, out);
   }
 });
+var harnessConnect = program.command("harness").description("brokered Harness helpers").command("connect").description("connect a Harness credential through a Tesser connect link");
+harnessConnect.command("claude-code").requiredOption("--connect <urlOrToken>", "Tesser /connect/<token> URL or token").option("--mode <mode>", "subscription or apiKey", "subscription").option("--token-stdin", "read token from stdin instead of running claude setup-token").option("--from-env <name>", "read token from an environment variable").option("--scope <scope>", "workspace or per_user", "workspace").option("--end-user-id <id>", "end-user id for per_user connections").option("--bin <path>", "claude binary", "claude").description("connect Claude Code as a brokered Harness; alias of `tesser auth claude-code`").action(async (cmdOpts) => {
+  const { out, opts } = setup();
+  try {
+    await authClaudeCode(out, target(opts).url, cmdOpts);
+  } catch (err) {
+    toExit(err, out);
+  }
+});
+harnessConnect.command("pi").requiredOption("--connect <urlOrToken>", "Tesser /connect/<token> URL or token").option("--mode <mode>", "anthropicOAuth or anthropicApiKey", "anthropicOAuth").option("--token-stdin", "read token from stdin").option("--from-env <name>", "read token from an environment variable").option("--scope <scope>", "workspace or per_user", "workspace").option("--end-user-id <id>", "end-user id for per_user connections").description("connect Pi as a brokered Harness; alias of `tesser auth pi`").action(async (cmdOpts) => {
+  const { out, opts } = setup();
+  try {
+    await authPi(out, target(opts).url, cmdOpts);
+  } catch (err) {
+    toExit(err, out);
+  }
+});
 program.command("connect").option("--wait", "poll until the human completes the link").option("--status <token>", "check an existing connect link").description("mint a connect link for missing credentials; the human completes it in a browser (ADR-0005)").action(async (cmdOpts) => {
   const { out, opts } = setup();
   try {
@@ -2613,20 +3178,22 @@ program.command("connect").option("--wait", "poll until the human completes the
       out.data({ url: null, requirements: [] }, () => "nothing missing \u2014 all requirements are satisfied");
       return;
     }
-    out.data(minted, () => `open in a browser to connect:
+    if (!cmdOpts.wait) {
+      out.data(minted, () => `open in a browser to connect:
   ${minted.url}`);
-    if (cmdOpts.wait) {
-      for (; ; ) {
-        await new Promise((r) => setTimeout(r, 2e3));
-        const status = await client.get(`/connect-links/${minted.token}/status`);
-        if (status.status === "completed") {
-          out.log("connect link completed \u2713");
-          return;
-        }
-        if (status.status === "expired") throw new CliError(EXIT.HALTED_CREDENTIALS, "connect link expired");
+      process.exit(EXIT.HALTED_CREDENTIALS);
+    }
+    out.log(`open in a browser to connect:
+  ${minted.url}`);
+    for (; ; ) {
+      await new Promise((r) => setTimeout(r, 2e3));
+      const status = await client.get(`/connect-links/${minted.token}/status`);
+      if (status.status === "completed") {
+        out.data({ ...minted, status: "completed" }, () => "connect link completed \u2713");
+        return;
       }
+      if (status.status === "expired") throw new CliError(EXIT.HALTED_CREDENTIALS, "connect link expired");
     }
-    process.exit(EXIT.HALTED_CREDENTIALS);
   } catch (err) {
     toExit(err, out);
   }
@@ -2654,7 +3221,7 @@ secrets.command("set").argument("<name>").option("--value-stdin", "read the valu
     const value = Buffer.concat(chunks).toString("utf8").replace(/\n$/, "");
     if (value.length === 0) throw new CliError(EXIT.USAGE, "empty value on stdin");
     await api(opts).put(`/secrets/${encodeURIComponent(name)}`, { value });
-    out.data({ set: name }, () => `secret "${name}" set \u2713`);
+    out.data({ set: name, changed: true }, () => `secret "${name}" set \u2713`);
   } catch (err) {
     toExit(err, out);
   }
@@ -2662,53 +3229,62 @@ secrets.command("set").argument("<name>").option("--value-stdin", "read the valu
 secrets.command("rm").argument("<name>").action(async (name) => {
   const { out, opts } = setup();
   try {
-    out.data(await api(opts).delete(`/secrets/${encodeURIComponent(name)}`));
+    const result = await api(opts).delete(`/secrets/${encodeURIComponent(name)}`);
+    out.data({ ...result, changed: result.deleted });
   } catch (err) {
     toExit(err, out);
   }
 });
 var runs = program.command("runs").description("inspect and drive runs");
-runs.command("list").option("--automation <id>").option("--status <status>").option("--limit <n>", "max rows", "25").action(async (cmdOpts) => {
+runs.command("list").option("--automation <id>").option("--status <status>").option("--limit <n>", "max rows", "25").option("--offset <n>", "rows to skip", "0").option("--fields <csv>", "comma-separated fields to include in each run").action(async (cmdOpts) => {
   const { out, opts } = setup();
   try {
     const { name } = requireProject(opts);
-    const params = new URLSearchParams({ project: name, limit: cmdOpts.limit });
+    const limit = parseIntOption(cmdOpts.limit, "--limit", { min: 1, max: 200 });
+    const offset = parseIntOption(cmdOpts.offset, "--offset", { min: 0 });
+    const params = new URLSearchParams({ project: name, limit: String(limit), offset: String(offset) });
     if (cmdOpts.automation) params.set("automation", cmdOpts.automation);
     if (cmdOpts.status) params.set("status", cmdOpts.status);
     const data = await api(opts).get(`/runs?${params}`);
-    out.data(
-      data,
-      (d) => d.runs.map((r) => `${r.id}  ${r.automation_id}  ${r.status}  (${r.trigger_kind})  ${r.created_at}`).join("\n") || "(no runs)"
-    );
+    const projected = { ...data, runs: projectFields(data.runs, cmdOpts.fields) };
+    out.data(projected, (d) => {
+      const rows = d.runs.map((r) => `${r.id ?? "?"}  ${r.automation_id ?? "?"}  ${r.status ?? "?"}  (${r.trigger_kind ?? "?"})  ${r.created_at ?? "?"}`).join("\n") || "(no runs)";
+      return d.truncated ? `${rows}
+(showing ${d.runs.length} of ${d.total ?? "?"}; use --offset for more)` : rows;
+    });
   } catch (err) {
     toExit(err, out);
   }
 });
-runs.command("show").argument("<runId>").action(async (runId) => {
+runs.command("show").argument("<runId>").option("--log-limit <n>", "max log rows", "100").option("--log-offset <n>", "log rows to skip", "0").action(async (runId, cmdOpts) => {
   const { out, opts } = setup();
   try {
-    out.data(await api(opts).get(`/runs/${runId}`));
+    const logLimit = parseIntOption(cmdOpts.logLimit, "--log-limit", { min: 1, max: 500 });
+    const logOffset = parseIntOption(cmdOpts.logOffset, "--log-offset", { min: 0 });
+    out.data(await api(opts).get(`/runs/${runId}?${new URLSearchParams({ logLimit: String(logLimit), logOffset: String(logOffset) })}`));
   } catch (err) {
     toExit(err, out);
   }
 });
-runs.command("trigger").argument("<automation>").option("--input <json>", "input payload as JSON").option("--env <env>", "environment", "production").action(async (automation, cmdOpts) => {
+runs.command("trigger").argument("<automation>").option("--input <json>", "input payload as JSON").option("--input-file <path>", "read input JSON from a file, or '-' for stdin").option("--env <env>", "environment", "production").action(async (automation, cmdOpts) => {
   const { out, opts } = setup();
   try {
     const { name } = requireProject(opts);
     const body = { project: name, automation, env: cmdOpts.env };
-    if (cmdOpts.input !== void 0) body["input"] = JSON.parse(cmdOpts.input);
+    const input2 = await resolveJsonInput({ literal: cmdOpts.input, file: cmdOpts.inputFile, label: "input" });
+    if (input2 !== void 0) body["input"] = input2;
     out.data(await api(opts).post("/runs", body));
   } catch (err) {
     toExit(err, out);
   }
 });
-runs.command("signal").argument("<runId>").argument("<name>").option("--payload <json>", "signal payload as JSON").action(async (runId, name, cmdOpts) => {
+runs.command("signal").argument("<runId>").argument("<name>").option("--payload <json>", "signal payload as JSON").option("--payload-file <path>", "read signal payload JSON from a file, or '-' for stdin").action(async (runId, name, cmdOpts) => {
   const { out, opts } = setup();
   try {
+    const payload = await resolveJsonInput({ literal: cmdOpts.payload, file: cmdOpts.payloadFile, label: "payload" });
     out.data(
       await api(opts).post(`/runs/${runId}/signals/${encodeURIComponent(name)}`, {
-        ...cmdOpts.payload !== void 0 ? { payload: JSON.parse(cmdOpts.payload) } : {}
+        ...payload !== void 0 ? { payload } : {}
       })
     );
   } catch (err) {
@@ -2718,28 +3294,43 @@ runs.command("signal").argument("<runId>").argument("<name>").option("--payload
 runs.command("cancel").argument("<runId>").action(async (runId) => {
   const { out, opts } = setup();
   try {
-    out.data(await api(opts).post(`/runs/${runId}/cancel`));
+    const result = await api(opts).post(`/runs/${runId}/cancel`);
+    out.data({ ...result, changed: result.cancelled });
   } catch (err) {
     toExit(err, out);
   }
 });
-program.command("logs").argument("<runId>").option("--follow", "poll until the run settles").description("step logs for one run").action(async (runId, cmdOpts) => {
+program.command("logs").argument("<runId>").option("--follow", "poll until the run settles").option("--limit <n>", "max log rows per page", "100").option("--offset <n>", "log rows to skip", "0").description("step logs for one run").action(async (runId, cmdOpts) => {
   const { out, opts } = setup();
   try {
     const client = api(opts);
-    let printed = 0;
+    const limit = parseIntOption(cmdOpts.limit, "--limit", { min: 1, max: 500 });
+    let offset = parseIntOption(cmdOpts.offset, "--offset", { min: 0 });
+    let finalDetail = null;
     for (; ; ) {
-      const detail = await client.get(`/runs/${runId}`);
-      const fresh = detail.logs.slice(printed);
-      printed = detail.logs.length;
-      if (out.json && !cmdOpts.follow) {
-        out.data(detail);
+      const detail = await client.get(`/runs/${runId}?${new URLSearchParams({ logLimit: String(limit), logOffset: String(offset) })}`);
+      finalDetail = detail;
+      if (!cmdOpts.follow) {
+        if (out.json) out.data(detail);
+        else {
+          for (const l of detail.logs) process.stdout.write(`[${l.level}]${l.step ? ` (${l.step})` : ""} ${l.msg}
+`);
+          if (detail.logsTruncated) out.log(`showing ${detail.logs.length} of ${detail.logsTotal ?? "?"}; use --offset for more`);
+        }
         return;
       }
-      for (const l of fresh) out.log(`[${l.level}]${l.step ? ` (${l.step})` : ""} ${l.msg}`);
-      if (!cmdOpts.follow || ["completed", "failed", "cancelled"].includes(detail.run.status)) {
-        if (!out.json) out.log(`run ${detail.run.status}`);
-        else out.data(detail);
+      if (out.format === "ndjson") {
+        for (const l of detail.logs) process.stdout.write(JSON.stringify({ log: l }) + "\n");
+      } else if (!out.json) {
+        for (const l of detail.logs) process.stdout.write(`[${l.level}]${l.step ? ` (${l.step})` : ""} ${l.msg}
+`);
+      }
+      offset += detail.logs.length;
+      if (detail.logsTruncated) continue;
+      if (["completed", "failed", "cancelled"].includes(detail.run.status)) {
+        if (out.format === "ndjson") process.stdout.write(JSON.stringify({ run: detail.run }) + "\n");
+        else if (out.json) out.data(finalDetail);
+        else out.log(`run ${detail.run.status}`);
         return;
       }
       await new Promise((r) => setTimeout(r, 1e3));
@@ -2761,13 +3352,22 @@ program.command("rollback").argument("<automation>").requiredOption("--to <versi
   const { out, opts } = setup();
   try {
     const { name } = requireProject(opts);
-    out.data(
-      await api(opts).post(`/projects/${name}/rollback`, {
-        automation,
-        toVersion: Number(cmdOpts.to),
-        env: cmdOpts.env
-      })
-    );
+    const toVersion = parseIntOption(cmdOpts.to, "--to", { min: 1 });
+    const result = await api(opts).post(`/projects/${name}/rollback`, {
+      automation,
+      toVersion,
+      env: cmdOpts.env
+    });
+    out.data({ ...result, changed: true });
+  } catch (err) {
+    toExit(err, out);
+  }
+});
+program.command("doctor").option("--no-network", "skip Instance health checks").description("agent preflight: local Project, auth, pins, and optional Instance health").action(async (cmdOpts) => {
+  const { out, opts } = setup();
+  try {
+    const resolved = target(opts);
+    await doctor(out, { version: VERSION, target: resolved, client: new ApiClient(resolved.url, resolved.token), network: cmdOpts.network !== false });
   } catch (err) {
     toExit(err, out);
   }
@@ -2787,7 +3387,17 @@ program.command("status").description("instance + project deploy status").action
   }
 });
 program.parseAsync().catch((err) => {
-  const out = new Output(process.argv.includes("--json"));
+  if (isCommanderHelp(err)) process.exit(err.exitCode ?? EXIT.OK);
+  const out = new Output(isJsonRequestedFromArgv() ? "json" : process.stdout.isTTY ? "text" : "json");
+  if (isCommanderUsageError(err)) {
+    out.fail(EXIT.USAGE, err.message.replace(/^error: /, ""));
+  }
   toExit(err, out);
 });
+function isCommanderHelp(err) {
+  return typeof err === "object" && err !== null && err.code === "commander.helpDisplayed";
+}
+function isCommanderUsageError(err) {
+  return typeof err === "object" && err !== null && typeof err.code === "string" && err.code.startsWith("commander.") && typeof err.message === "string";
+}
 //# sourceMappingURL=index.js.map