@ishlabs/cli 0.8.1 → 0.8.3

package/dist/commands/config.js

@@ -7,7 +7,14 @@ import { output, formatConfigList } from "../lib/output.js";
 export function registerConfigCommands(program) {
     const config = program
         .command("config")
-        .description("Manage simulation configs");
+        .description("Manage simulation configs")
+        .addHelpText("after", `
+A simulation config tunes how testers behave during a run (model, timing, retries, etc.).
+Pass \`--config <id>\` to \`ish study run\` to override the default for one dispatch.
+
+Configs are global — not scoped to a workspace. The --workspace flag is rejected. Use aliases (c-...) or UUIDs to identify configs.
+
+Run \`ish docs overview\` for the full mental model.`);
     config
         .command("list")
         .description("List all simulation configs")
@@ -22,9 +29,25 @@ export function registerConfigCommands(program) {
         .command("create")
         .description("Create a simulation config")
         .requiredOption("--file <path>", "JSON file with config data")
+        .addHelpText("after", "\nMinimal body: {\"name\": \"...\", \"model_settings\": {...}}. See `ish config schema` for the full JSON Schema.")
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const body = await readJsonFileOrStdin(opts.file);
+            const proposedName = typeof body.name === "string" ? body.name : "";
+            // Names are informational; aliases (c-...) are canonical. Warn if a
+            // config with the same name already exists so the user isn't surprised
+            // when a list shows duplicates.
+            if (proposedName) {
+                try {
+                    const existing = await client.get("/dev/simulation-configs");
+                    if (existing.some((c) => c.name === proposedName)) {
+                        process.stderr.write(`Note: a config named "${proposedName}" already exists. Aliases (c-...) are the canonical handle.\n`);
+                    }
+                }
+                catch {
+                    // Best-effort: skip the warning if the pre-check fails.
+                }
+            }
             const data = await client.post("/dev/simulation-configs", body);
             const result = data;
             if (result.id)
@@ -59,6 +82,7 @@ export function registerConfigCommands(program) {
         .description("Update a simulation config")
         .argument("<id>", "Config ID")
         .requiredOption("--file <path>", "JSON file with update data")
+        .addHelpText("after", "\nMinimal body: {\"name\": \"...\", \"model_settings\": {...}}. See `ish config schema` for the full JSON Schema.")
         .action(async (id, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const body = await readJsonFileOrStdin(opts.file);

package/dist/commands/docs.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ish docs — Offline, in-binary documentation aimed at AI coding agents.
+ *
+ * Modeled on LiveKit's `lk docs` and Speakeasy's `speakeasy agent`. The
+ * goal is that an agent that only ever sees what `ish --help` and
+ * subcommands print can still reach a complete domain primer without
+ * needing the README or web docs.
+ *
+ * Surface:
+ *   ish docs                        # alias for `ish docs overview`
+ *   ish docs overview               # mental model + traversal hints
+ *   ish docs list                   # every page with one-line description
+ *   ish docs get-page <slug>        # full markdown for one page
+ *   ish docs search <query>         # keyword search across all pages
+ */
+import type { Command } from "commander";
+export declare function registerDocsCommands(program: Command): void;

package/dist/commands/docs.js

@@ -0,0 +1,147 @@
+/**
+ * ish docs — Offline, in-binary documentation aimed at AI coding agents.
+ *
+ * Modeled on LiveKit's `lk docs` and Speakeasy's `speakeasy agent`. The
+ * goal is that an agent that only ever sees what `ish --help` and
+ * subcommands print can still reach a complete domain primer without
+ * needing the README or web docs.
+ *
+ * Surface:
+ *   ish docs                        # alias for `ish docs overview`
+ *   ish docs overview               # mental model + traversal hints
+ *   ish docs list                   # every page with one-line description
+ *   ish docs get-page <slug>        # full markdown for one page
+ *   ish docs search <query>         # keyword search across all pages
+ */
+import { getGlobals } from "../lib/command-helpers.js";
+import { listPages, getPage, searchPages, } from "../lib/docs.js";
+import { output, outputList } from "../lib/output.js";
+function printOverview(json) {
+    const page = getPage("overview");
+    if (!page)
+        throw new Error("Overview page is missing.");
+    if (json) {
+        output(page, json);
+        return;
+    }
+    process.stdout.write(page.body);
+    if (!page.body.endsWith("\n"))
+        process.stdout.write("\n");
+}
+function printList(json) {
+    const pages = listPages();
+    if (json) {
+        outputList(pages.map((p) => ({
+            slug: p.slug,
+            title: p.title,
+            description: p.description,
+        })), json);
+        return;
+    }
+    const widest = pages.reduce((n, p) => Math.max(n, p.slug.length), 0);
+    for (const p of pages) {
+        const pad = " ".repeat(widest - p.slug.length + 2);
+        process.stdout.write(`  ${p.slug}${pad}${p.description}\n`);
+    }
+    process.stdout.write("\nRead a page:   ish docs get-page <slug>\n" +
+        "Search:        ish docs search <query>\n");
+}
+function printPage(slug, json) {
+    const page = getPage(slug);
+    if (!page) {
+        const available = listPages().map((p) => p.slug);
+        const err = new Error(`Unknown page "${slug}". Available pages:\n  ${available.join("\n  ")}`);
+        if (json) {
+            output({ error: "page_not_found", slug, available_slugs: available }, json);
+            process.exit(4);
+        }
+        throw err;
+    }
+    if (json) {
+        output(page, json);
+        return;
+    }
+    process.stdout.write(page.body);
+    if (!page.body.endsWith("\n"))
+        process.stdout.write("\n");
+}
+function printSearch(query, json) {
+    const hits = searchPages(query, 20);
+    if (json) {
+        outputList(hits, json);
+        return;
+    }
+    if (hits.length === 0) {
+        process.stdout.write(`No matches for "${query}".\n`);
+        return;
+    }
+    for (const hit of hits) {
+        process.stdout.write(`${hit.slug}  —  ${hit.title}\n`);
+        process.stdout.write(`  ${hit.snippet}\n\n`);
+    }
+    process.stdout.write(`Read a result:   ish docs get-page <slug>\n`);
+}
+export function registerDocsCommands(program) {
+    const docs = program
+        .command("docs")
+        .description("Offline docs for agents — mental model, concept pages, search")
+        .addHelpText("after", `\nSubcommands:
+  overview              Mental model + how to navigate (default)
+  list                  All pages with one-line descriptions
+  get-page <slug>       Full markdown for one page
+  search <query>        Keyword search across all pages
+
+Examples:
+  $ ish docs                                    # overview
+  $ ish docs list
+  $ ish docs get-page concepts/study
+  $ ish docs search "assignment"
+  $ ish docs get-page reference/json-mode --json | jq -r .body
+`)
+        .action((_opts, cmd) => {
+        // Bare `ish docs` → overview.
+        const globals = getGlobals(cmd);
+        printOverview(globals.json);
+    });
+    docs
+        .command("overview")
+        .description("Print the agent-facing mental model and traversal hints")
+        .addHelpText("after", "\nExamples:\n  $ ish docs overview\n  $ ish docs overview --json")
+        .action((_opts, cmd) => {
+        const globals = getGlobals(cmd);
+        printOverview(globals.json);
+    });
+    docs
+        .command("list")
+        .description("List every doc page with its one-line description")
+        .addHelpText("after", "\nExamples:\n  $ ish docs list\n  $ ish docs list --json | jq '.[].slug'")
+        .action((_opts, cmd) => {
+        const globals = getGlobals(cmd);
+        printList(globals.json);
+    });
+    docs
+        .command("get-page")
+        .description("Print the full markdown for one page")
+        .argument("<slug>", "Page slug, e.g. concepts/study (see `ish docs list`)")
+        .addHelpText("after", `\nExamples:
+  $ ish docs get-page overview
+  $ ish docs get-page concepts/study
+  $ ish docs get-page reference/aliases
+  $ ish docs get-page concepts/run-verbs --json`)
+        .action((slug, _opts, cmd) => {
+        const globals = getGlobals(cmd);
+        printPage(slug, globals.json);
+    });
+    docs
+        .command("search")
+        .description("Keyword search across every doc page")
+        .argument("<query>", "Search query (case-insensitive substring)")
+        .addHelpText("after", `\nExamples:
+  $ ish docs search assignment
+  $ ish docs search "site access"
+  $ ish docs search audience --json`)
+        .action((query, _opts, cmd) => {
+        const globals = getGlobals(cmd);
+        printSearch(query, globals.json);
+    });
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ish init — Install the ish Agent Skill into a project.
+ *
+ * Spec the skill conforms to: https://agentskills.io/specification
+ *
+ * Default target is `.claude/skills/ish/` because Claude Code is the
+ * largest install base and originator of the SKILL.md format. Other
+ * agents (Codex, Cursor, Cline, Roo Code) read `.agents/skills/<name>/`
+ * — pass `--target agents` or `--target both`.
+ *
+ * The skill is materialised from in-binary string constants
+ * (src/lib/skill-content.ts) so the same content ships in both `tsc`
+ * builds and `bun build --compile` single-binary builds.
+ */
+import type { Command } from "commander";
+export declare function registerInitCommands(program: Command): void;

package/dist/commands/init.js

@@ -0,0 +1,182 @@
+/**
+ * ish init — Install the ish Agent Skill into a project.
+ *
+ * Spec the skill conforms to: https://agentskills.io/specification
+ *
+ * Default target is `.claude/skills/ish/` because Claude Code is the
+ * largest install base and originator of the SKILL.md format. Other
+ * agents (Codex, Cursor, Cline, Roo Code) read `.agents/skills/<name>/`
+ * — pass `--target agents` or `--target both`.
+ *
+ * The skill is materialised from in-binary string constants
+ * (src/lib/skill-content.ts) so the same content ships in both `tsc`
+ * builds and `bun build --compile` single-binary builds.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getGlobals } from "../lib/command-helpers.js";
+import { output } from "../lib/output.js";
+import { buildSkillFiles, getSkillMd, SKILL_TARGETS, } from "../lib/skill-content.js";
+function resolveTargets(opts) {
+    if (opts.dir) {
+        return [{ key: "claude", path: opts.dir, consumers: ["custom"] }];
+    }
+    if (opts.target === "both")
+        return SKILL_TARGETS;
+    return SKILL_TARGETS.filter((t) => t.key === opts.target);
+}
+/**
+ * Per-file idempotence: matching contents are skipped, non-matching
+ * existing contents trigger a refusal unless --force is set. Files in
+ * the directory that aren't part of the bundle are never touched.
+ */
+function writeBundle(root, files, force) {
+    const conflicts = [];
+    const plan = [];
+    for (const file of files) {
+        const abs = path.join(root, file.relativePath);
+        let prior;
+        try {
+            prior = fs.readFileSync(abs, "utf-8");
+        }
+        catch {
+            // not present
+        }
+        if (prior === file.contents) {
+            plan.push({ file, action: "skip" });
+        }
+        else if (prior !== undefined && !force) {
+            conflicts.push(file.relativePath);
+        }
+        else {
+            plan.push({ file, action: "write" });
+        }
+    }
+    if (conflicts.length > 0) {
+        throw new Error(`Refusing to overwrite existing files in ${root}:\n` +
+            conflicts.map((f) => `  - ${f}`).join("\n") +
+            `\n\nRe-run with --force to overwrite, or pass --dir <path> to write elsewhere.`);
+    }
+    fs.mkdirSync(root, { recursive: true });
+    const written = [];
+    const skipped = [];
+    for (const item of plan) {
+        const abs = path.join(root, item.file.relativePath);
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        if (item.action === "skip") {
+            skipped.push(item.file.relativePath);
+            continue;
+        }
+        fs.writeFileSync(abs, item.file.contents, "utf-8");
+        written.push(item.file.relativePath);
+    }
+    return { root, written, skipped };
+}
+function buildHints(targets, opts) {
+    if (opts.dir) {
+        return [
+            "Custom directory: tell your agent where to find this skill (most agents " +
+                "look at .claude/skills/<name>/ or .agents/skills/<name>/).",
+        ];
+    }
+    const installed = new Set(targets.map((t) => t.key));
+    const hints = [];
+    for (const target of SKILL_TARGETS) {
+        if (installed.has(target.key))
+            continue;
+        const consumers = target.consumers.join(", ");
+        hints.push(`${consumers}: install to ${target.path} via ` +
+            `\`ish init --target ${target.key}${opts.force ? " --force" : ""}\` ` +
+            `(or copy: \`cp -r ${targets[0]?.path ?? ".claude/skills/ish"} ${target.path}\`).`);
+    }
+    return hints;
+}
+export function registerInitCommands(program) {
+    program
+        .command("init")
+        .description("Install the ish Agent Skill into a project (Claude Code, Codex, Cursor, Cline, Roo Code)")
+        .option("--target <which>", "Where to install: claude (.claude/skills/ish), agents (.agents/skills/ish), or both", "claude")
+        .option("--dir <path>", "Write to a custom directory instead of a recognised target path")
+        .option("--stdout", "Print the SKILL.md to stdout instead of writing files (skips references/)")
+        .option("--force", "Overwrite existing files in the target directory")
+        .addHelpText("after", `\nExamples:
+  $ ish init                            # → .claude/skills/ish/  (Claude Code)
+  $ ish init --target agents            # → .agents/skills/ish/  (Codex / Cursor / Cline / Roo)
+  $ ish init --target both              # both of the above
+  $ ish init --dir vendor/ish-skill     # custom path
+  $ ish init --stdout > /tmp/SKILL.md   # just the SKILL.md
+  $ ish init --force                    # overwrite existing skill files
+
+Where do skills live?
+  Claude Code         .claude/skills/<name>/      (also read by Cursor for back-compat)
+  Codex / Cursor /    .agents/skills/<name>/      (cross-vendor convention)
+    Cline / Roo Code
+
+Spec: https://agentskills.io/specification`)
+        .action(async (rawOpts, cmd) => {
+        const globals = getGlobals(cmd);
+        try {
+            const target = String(rawOpts.target ?? "claude");
+            if (!["claude", "agents", "both"].includes(target)) {
+                throw new Error(`Invalid --target "${target}". Valid: claude | agents | both.`);
+            }
+            const opts = {
+                target,
+                dir: typeof rawOpts.dir === "string" ? rawOpts.dir : undefined,
+                stdout: rawOpts.stdout === true,
+                force: rawOpts.force === true,
+            };
+            if (opts.stdout) {
+                process.stdout.write(getSkillMd());
+                return;
+            }
+            const targets = resolveTargets(opts);
+            const files = buildSkillFiles();
+            const results = [];
+            for (const t of targets) {
+                results.push(writeBundle(t.path, files, !!opts.force));
+            }
+            const hints = buildHints(targets, opts);
+            if (globals.json) {
+                output({
+                    ok: true,
+                    installed: results.map((r) => ({
+                        root: r.root,
+                        written: r.written,
+                        skipped: r.skipped,
+                    })),
+                    other_paths: hints,
+                }, true);
+                return;
+            }
+            for (const r of results) {
+                if (r.written.length === 0 && r.skipped.length > 0) {
+                    process.stdout.write(`Skill already up to date at ${r.root} (${r.skipped.length} files unchanged).\n`);
+                }
+                else {
+                    process.stdout.write(`Installed skill at ${r.root}\n`);
+                    for (const f of r.written)
+                        process.stdout.write(`  + ${f}\n`);
+                    for (const f of r.skipped)
+                        process.stdout.write(`  = ${f} (unchanged)\n`);
+                }
+            }
+            if (hints.length > 0) {
+                process.stdout.write("\nOther agent paths you may want to populate:\n");
+                for (const h of hints)
+                    process.stdout.write(`  - ${h}\n`);
+            }
+            process.stdout.write("\nTip: run `ish docs overview` next — it's the entry point your agent should hit first.\n");
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (globals.json) {
+                output({ ok: false, error: message }, true);
+            }
+            else {
+                process.stderr.write(`${message}\n`);
+            }
+            process.exit(2);
+        }
+    });
+}

package/dist/commands/iteration.d.ts

@@ -1,5 +1,9 @@
 /**
- * ish iteration — Manage iterations (usually created via `simulation run`).
+ * ish iteration — Manage iterations of a study.
+ *
+ * An iteration carries the run-time details (URL for interactive,
+ * content/file for media). Create one before `ish study run` dispatches
+ * simulations against it.
  */
 import type { Command } from "commander";
 export declare function registerIterationCommands(program: Command): void;