@ishlabs/cli 0.27.1 → 0.28.1

package/dist/commands/feedback.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ish feedback — report a bug, request a feature, or send any other feedback
+ * to the ish team straight from the terminal.
+ *
+ * Transport: posts to the ish backend (`POST /api/v1/product-feedback` via
+ * ApiClient) with the user's bearer token. The backend inserts into the
+ * `product_feedback` table — the same table the web app's "Send feedback"
+ * dialog writes to — using its privileged connection, so CLI reports show up
+ * alongside web feedback. Per ADR-0029 (ish-frontend), clients submit through
+ * api.ishlabs.io, NEVER via Supabase PostgREST directly: the `sb_publishable_*`
+ * key shipped in this binary is deliberately powerless against the database.
+ * (The web flow additionally mirrors to Notion + captures PostHog server-side;
+ * those are deferred for the CLI.)
+ *
+ * Diagnostics: to help whoever triages the report, the user's message is
+ * augmented with an environment + active-config block (opt out with
+ * --no-diagnostics), and optionally (--health) the `ish check` setup checklist
+ * plus the tail of ~/.ish/local-sim.log. The reporter's identity (user_id /
+ * user_email) is attached server-side from the JWT, not here.
+ */
+import type { Command } from "commander";
+export declare function registerFeedbackCommands(program: Command): void;

package/dist/commands/feedback.js

@@ -0,0 +1,259 @@
+/**
+ * ish feedback — report a bug, request a feature, or send any other feedback
+ * to the ish team straight from the terminal.
+ *
+ * Transport: posts to the ish backend (`POST /api/v1/product-feedback` via
+ * ApiClient) with the user's bearer token. The backend inserts into the
+ * `product_feedback` table — the same table the web app's "Send feedback"
+ * dialog writes to — using its privileged connection, so CLI reports show up
+ * alongside web feedback. Per ADR-0029 (ish-frontend), clients submit through
+ * api.ishlabs.io, NEVER via Supabase PostgREST directly: the `sb_publishable_*`
+ * key shipped in this binary is deliberately powerless against the database.
+ * (The web flow additionally mirrors to Notion + captures PostHog server-side;
+ * those are deferred for the CLI.)
+ *
+ * Diagnostics: to help whoever triages the report, the user's message is
+ * augmented with an environment + active-config block (opt out with
+ * --no-diagnostics), and optionally (--health) the `ish check` setup checklist
+ * plus the tail of ~/.ish/local-sim.log. The reporter's identity (user_id /
+ * user_email) is attached server-side from the JWT, not here.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import pkg from "../../package.json" with { type: "json" };
+import { loadConfig } from "../config.js";
+import { withClient } from "../lib/command-helpers.js";
+import { resolveApiUrl } from "../lib/auth.js";
+import { output } from "../lib/output.js";
+import { c } from "../lib/colors.js";
+const { version: CLI_VERSION } = pkg;
+const FEEDBACK_TYPES = ["bug", "feature", "other"];
+const DESCRIPTION_MIN = 10;
+const DESCRIPTION_MAX = 4000;
+const TITLE_MIN = 3;
+const TITLE_MAX = 120;
+const TYPE_NOUN = {
+    bug: "Bug report",
+    feature: "Feature request",
+    other: "Feedback",
+};
+function validationError(message) {
+    // `name === "ValidationError"` maps to exit code 2 in exitCodeFromError.
+    const err = new Error(message);
+    err.name = "ValidationError";
+    return err;
+}
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        process.stdin.setEncoding("utf-8");
+        process.stdin.on("data", (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", reject);
+    });
+}
+/**
+ * Resolve the feedback body from the positional argument, an `@file`
+ * reference, or piped stdin — the same input idioms the rest of the CLI uses
+ * for text fields (no interactive prompt; the CLI is for autonomous agents).
+ */
+async function resolveDescription(message) {
+    if (message && message.startsWith("@")) {
+        const path = message.slice(1);
+        try {
+            return readFileSync(path, "utf-8");
+        }
+        catch {
+            throw new Error(`Cannot read file: ${path}`);
+        }
+    }
+    // Explicit stdin sentinel, or no argument with something piped in.
+    if (message === "-" || (message === undefined && !process.stdin.isTTY)) {
+        return readStdin();
+    }
+    if (message === undefined) {
+        throw validationError('No feedback message. Pass it as an argument, pipe it on stdin, or use @file:\n' +
+            '  ish feedback "the save button on the profile page does nothing"\n' +
+            '  ish feedback --type feature "let me export interactions as CSV"\n' +
+            "  ish feedback @bug-report.md\n" +
+            '  echo "..." | ish feedback -');
+    }
+    return message;
+}
+function deriveTitle(explicit, description, type) {
+    if (explicit !== undefined) {
+        const t = explicit.trim();
+        if (t.length < TITLE_MIN) {
+            throw validationError(`--title must be at least ${TITLE_MIN} characters.`);
+        }
+        return t.slice(0, TITLE_MAX);
+    }
+    // Mirror the web dialog: first non-empty line of the message becomes the
+    // title, capped to TITLE_MAX. Fall back to a generic title so the table's
+    // NOT NULL + min-length contract is always satisfied even for terse bodies.
+    const firstLine = description
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => l.length > 0) ?? "";
+    const candidate = firstLine.slice(0, TITLE_MAX).trim();
+    return candidate.length >= TITLE_MIN ? candidate : `${TYPE_NOUN[type]} from CLI`;
+}
+// ── Diagnostics ────────────────────────────────────────────────────────────
+//
+// Appended to the message so whoever debugs the report has grounded context.
+// None of this needs the JWT — the backend attaches the reporter's identity
+// from the token. The aim is maximal useful signal without a schema change.
+/** Always-on, instant one-liner: the bare minimum a debugger needs. */
+function platformLine(dev) {
+    return `Sent via ish CLI v${CLI_VERSION} · ${process.platform} ${process.arch} · node ${process.versions.node}${dev ? " · dev" : ""}`;
+}
+/** Active-config context (instant; no subprocesses). Default-on. */
+function diagnosticsBlock(apiUrl) {
+    const cfg = loadConfig();
+    const lines = [
+        "Diagnostics (auto-attached; pass --no-diagnostics to omit)",
+        `- Active workspace: ${cfg.workspace ?? "none"}`,
+        `- Active study: ${cfg.study ?? "none"}`,
+        `- Active ask: ${cfg.ask ?? "none"}`,
+        `- API: ${apiUrl}`,
+    ];
+    return lines.join("\n");
+}
+/** Setup/health checklist, reusing `ish check`'s probes. Heavier (subprocess
+ *  probes for xcrun/adb), so gated behind --health. */
+async function healthBlock() {
+    try {
+        const { runChecks } = await import("./doctor.js");
+        const checks = await runChecks();
+        const MARK = {
+            pass: "OK",
+            warn: "WARN",
+            fail: "FAIL",
+            skip: "--",
+        };
+        const lines = checks.map((ch) => {
+            const fix = (ch.status === "warn" || ch.status === "fail") && ch.fix
+                ? ` (fix: ${ch.fix})`
+                : "";
+            return `- [${MARK[ch.status] ?? ch.status}] ${ch.name}: ${ch.message ?? ""}${fix}`.trimEnd();
+        });
+        return ["Setup checks (ish check):", ...lines].join("\n");
+    }
+    catch (e) {
+        return `Setup checks: could not run (${e instanceof Error ? e.message : String(e)}).`;
+    }
+}
+/** Tail of the local-simulation debug log, when present. Written to
+ *  ~/.ish/local-sim.log by `study run --local --debug`. */
+function localSimLogTail(maxLines = 80) {
+    // Match the literal path debug.ts writes to (it uses homedir()/.ish, not the
+    // ISH_HOME-aware paths helper), so we read exactly where the log lands.
+    const logFile = join(homedir(), ".ish", "local-sim.log");
+    if (!existsSync(logFile))
+        return undefined;
+    try {
+        const tail = readFileSync(logFile, "utf-8").split("\n").slice(-maxLines).join("\n").trim();
+        if (!tail)
+            return undefined;
+        return [
+            `Recent local-sim log (last ${maxLines} lines of ~/.ish/local-sim.log):`,
+            "```",
+            tail,
+            "```",
+        ].join("\n");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Assemble everything appended to the user's message. */
+async function buildAppendix(opts) {
+    const sections = [platformLine(opts.dev)];
+    if (opts.diagnostics)
+        sections.push(diagnosticsBlock(opts.apiUrl));
+    if (opts.health) {
+        sections.push(await healthBlock());
+        const log = localSimLogTail();
+        if (log)
+            sections.push(log);
+    }
+    return "\n\n—\n" + sections.join("\n\n");
+}
+export function registerFeedbackCommands(program) {
+    program
+        .command("feedback")
+        .description("Report a bug or send feedback to the ish team")
+        .argument("[message]", "Feedback text. Use @path to read from a file, or - to read from stdin.")
+        .option("--type <type>", "Feedback type: bug | feature | other", "bug")
+        .option("--title <title>", "Short title (default: first line of the message)")
+        .option("--no-diagnostics", "Don't attach environment/account diagnostics to the report")
+        .option("--health", "Also run setup checks (ish check) and attach recent local-sim logs — useful for simulation/setup bugs")
+        .option("--dry-run", "Print exactly what would be sent (including diagnostics) without submitting")
+        .addHelpText("after", `\nExamples:
+  $ ish feedback "the save button on the profile page does nothing"
+  $ ish feedback --type feature "let me export interactions as CSV"
+  $ ish feedback --type other "the guided setup was great"
+  $ ish feedback @bug-report.md
+  $ ish study run … --local --debug 2>err.txt; ish feedback @err.txt --health
+  $ git log -1 --oneline | ish feedback -
+
+Reports go to the ish team and show up alongside web feedback. Sends as the
+logged-in user (run \`ish login\` first). bug is the default type. To give
+whoever debugs it the most signal, attach the failing command's output via
+@file or stdin; environment + active-config diagnostics are attached
+automatically (opt out with --no-diagnostics), and --health adds setup
+checks + local-sim logs.`)
+        .action(async (message, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const type = opts.type;
+            if (!FEEDBACK_TYPES.includes(type)) {
+                throw validationError(`Invalid --type "${opts.type}". Must be one of: ${FEEDBACK_TYPES.join(", ")}.`);
+            }
+            const rawDescription = await resolveDescription(message);
+            const description = rawDescription.trim();
+            if (description.length === 0) {
+                throw validationError('No feedback message. Pass it as an argument, pipe it on stdin, or use @file:\n' +
+                    '  ish feedback "the save button on the profile page does nothing"\n' +
+                    '  ish feedback --type feature "let me export interactions as CSV"\n' +
+                    "  ish feedback @bug-report.md");
+            }
+            if (description.length < DESCRIPTION_MIN) {
+                throw validationError(`Please add a bit more detail (at least ${DESCRIPTION_MIN} characters).`);
+            }
+            if (description.length > DESCRIPTION_MAX) {
+                throw validationError(`Feedback is too long (${description.length} chars; max ${DESCRIPTION_MAX}).`);
+            }
+            const title = deriveTitle(opts.title, description, type);
+            const apiUrl = resolveApiUrl(globals.apiUrl, globals.dev);
+            const appendix = await buildAppendix({
+                apiUrl,
+                dev: globals.dev,
+                diagnostics: opts.diagnostics,
+                health: opts.health ?? false,
+            });
+            const body = {
+                type,
+                title,
+                description: description + appendix,
+            };
+            if (opts.dryRun) {
+                if (!globals.quiet) {
+                    console.error(`${c.dim}Dry run — nothing sent. This is what would be submitted:${c.reset}`);
+                }
+                output(body, globals.json);
+                return;
+            }
+            if (!globals.quiet) {
+                console.error(`Sending ${type} report…`);
+            }
+            const data = await client.post("/product-feedback", body);
+            if (!globals.quiet) {
+                console.error(`${c.green}✓${c.reset} Thanks! Your ${type} report was sent to the ish team.`);
+            }
+            output(data, globals.json, { writePath: true });
+        });
+    });
+}

package/dist/commands/study-run.js

@@ -493,9 +493,28 @@ Examples:
                 chatMode = readChatMode(iteration.details);
                 isPair = chatMode === "participant_pair";
             }
-            if (!iterationHasContent(iteration.details, modality)) {
-                const flagHint = describeRequiredContentFlag(modality, isPair ? "participant_pair" : undefined);
+            // Native (ios/android) interactive iterations name their target via
+            // `app_artifact`, which is OPTIONAL at create time: `ish iteration create
+            // --platform ios` with no --app stores it as "chosen at run time" (no
+            // app_artifact) and the app is supplied here via --app. The web app's
+            // "Run on your device" panel generates exactly that command
+            // (`ish study run --local --platform ios --app ./Build.app …`), so a
+            // run-time --app must satisfy the content requirement even though the
+            // iteration itself carries no stored target. `iterationHasContent` only
+            // sees the persisted details, so layer the run-time flag on top here.
+            const iterationPlatform = normalizePlatform(readIterationDetails(iteration.details).platform);
+            const isNativeIteration = iterationPlatform === "ios" || iterationPlatform === "android";
+            const runtimeAppProvided = isNativeIteration && typeof opts.app === "string" && opts.app.trim().length > 0;
+            if (!iterationHasContent(iteration.details, modality) && !runtimeAppProvided) {
                 const iterAlias = tagAlias(ALIAS_PREFIX.iteration, iterationId);
+                if (isNativeIteration) {
+                    // The target is an app, not a URL — point at --app, not --url.
+                    const ext = iterationPlatform === "ios" ? ".app" : ".apk";
+                    throw new Error(`Iteration "${iterationLabel}" (${iterAlias}) is a native ${iterationPlatform} iteration with no app set. ` +
+                        `Pass \`--app <path-to-${ext}-or-bundle-id>\` on this run, ` +
+                        `or store one on the iteration via \`ish iteration update ${iterAlias} --details-json '{"app_artifact":"<bundle-id-or-path>"}'\`, then retry.`);
+                }
+                const flagHint = describeRequiredContentFlag(modality, isPair ? "participant_pair" : undefined);
                 throw new Error(`Iteration "${iterationLabel}" (${iterAlias}) has no ${isMedia ? "content" : isPair ? "people/scenarios" : isChat ? "endpoint" : "URL"} configured yet. ` +
                     `Add ${isMedia ? "content" : isPair ? "the pair-mode payload" : isChat ? "an endpoint" : "a URL"} with ` +
                     `\`ish iteration create --study ${resolvedStudy} ${flagHint}\` ` +

package/dist/commands/workspace.js

@@ -296,7 +296,7 @@ async function collectWorkspaceUsage(client, workspaceId) {
         people_used: typeof participants.total === "number" ? participants.total : 0,
         people_max: lookupLimit("maxCustomPersons"),
         concurrent_participants_max: lookupLimit("maxConcurrentParticipants"),
-        workspace_members_max: lookupLimit("maxWorkspaceMembers"),
+        workspace_members_max: lookupLimit("maxSeats"),
     };
 }
 // ---------------------------------------------------------------------------

package/dist/index.js

@@ -20,6 +20,7 @@ import { registerInitCommands } from "./commands/init.js";
 import { registerMcpCommands } from "./commands/mcp.js";
 import { registerSecretCommands } from "./commands/secret.js";
 import { registerDoctorCommands } from "./commands/doctor.js";
+import { registerFeedbackCommands } from "./commands/feedback.js";
 import { AGENT_HELP_FOOTER } from "./lib/docs.js";
 import { runInline, EXIT_USAGE, injectGlobalWorkspaceOption } from "./lib/command-helpers.js";
 import { resolveApiUrl, resolveToken, verifyToken } from "./lib/auth.js";
@@ -512,6 +513,7 @@ registerInitCommands(program);
 registerMcpCommands(program);
 registerSecretCommands(program);
 registerDoctorCommands(program);
+registerFeedbackCommands(program);
 program
     .command("upgrade")
     .description("Update ish to the latest version")

package/dist/lib/command-helpers.js

@@ -6,7 +6,7 @@ import * as fs from "node:fs";
 import { resolveApiUrl, resolveToken } from "./auth.js";
 import { getAppUrl } from "../auth.js";
 import { ApiClient, ApiError } from "./api-client.js";
-import { outputError, setVerbose, setFields, setGetField } from "./output.js";
+import { outputError, shouldSuggestReport, setVerbose, setFields, setGetField } from "./output.js";
 import { setColorsEnabled, colorsEnabled } from "./colors.js";
 import { loadConfig } from "../config.js";
 import { resolveId } from "./alias-store.js";
@@ -513,7 +513,10 @@ export async function withClient(cmd, fn) {
             await fn(client, globals);
         }
         catch (err) {
-            outputError(err, globals.json);
+            // Nudge to report genuine faults — but never when the failing command
+            // IS `ish feedback` (don't suggest reporting via the thing that broke).
+            const suggestReport = shouldSuggestReport(err) && commandPath(cmd).split(".")[0] !== "feedback";
+            outputError(err, globals.json, { suggestReport });
             await exitWithFlush(exitCodeFromError(err));
         }
     });
@@ -530,7 +533,8 @@ export async function runInline(cmd, fn) {
             await fn(globals);
         }
         catch (err) {
-            outputError(err, globals.json);
+            const suggestReport = shouldSuggestReport(err) && commandPath(cmd).split(".")[0] !== "feedback";
+            outputError(err, globals.json, { suggestReport });
             await exitWithFlush(exitCodeFromError(err));
         }
     });

package/dist/lib/docs.js

@@ -2549,6 +2549,15 @@ from envelopes that don't originate from an HTTP response (Commander
 parse errors, local validation failures, alias-resolution errors). Do
 not branch on \`status: 0\` — that value is never emitted as of 0.20.
 
+A **\`report\`** field appears on *genuine faults* — uncategorized
+client errors, \`server\`/5xx, network failures, and unknown throws —
+carrying the suggested \`ish feedback "…"\` invocation to report the
+bug. It is deliberately **absent** on user-actionable failures (usage /
+validation exit 2, auth exit 3, not-found exit 4, \`usage_limit_reached\`)
+so agents don't report their own input mistakes. In human mode the same
+nudge prints as a \`→ Looks like a bug? Report it: …\` line on stderr.
+See \`guides/feedback\`.
+
 ## Conventions
 
 - Successful commands exit 0 and print one JSON object/array on stdout.
@@ -3224,23 +3233,26 @@ request time, for any client, is the backend's \`TIER_LIMITS\` dict in
 
 ## Limits enforced
 
-| Limit                       | Free | Media | Starter | Pro | Enterprise |
-|-----------------------------|------|-------|---------|-----|------------|
-| \`maxProducts\`               | 1    | 1     | ∞       | ∞   | ∞          |
-| \`maxStudiesPerProduct\`      | 3    | ∞     | ∞       | ∞   | ∞          |
-| \`maxIterationsPerStudy\`     | 2    | ∞     | ∞       | ∞   | ∞          |
-| \`maxCustomPersons\`          | 3    | 10    | 10      | ∞   | ∞          |
-| \`maxConcurrentParticipants\` | 3    | 3     | 10      | 50  | ∞          |
-| \`maxWorkspaceMembers\`       | 1    | 1     | 1       | 10  | ∞          |
-| \`maxSeats\`                  | 1    | 1     | 1       | 10  | ∞          |
+| Limit                       | Free | Starter | Pro | Enterprise |
+|-----------------------------|------|---------|-----|------------|
+| \`maxProducts\`               | 1    | 3       | ∞   | ∞          |
+| \`maxStudiesPerProduct\`      | 3    | 15      | ∞   | ∞          |
+| \`maxAsksPerProduct\`         | 3    | 15      | ∞   | ∞          |
+| \`maxIterationsPerStudy\`     | 2    | 5       | ∞   | ∞          |
+| \`maxCustomPersons\`          | 3    | 10      | ∞   | ∞          |
+| \`maxConcurrentParticipants\` | 3    | 10      | 50  | ∞          |
+| \`maxSeats\`                  | 1    | 1       | 10  | ∞          |
 
 Commands that may hit a limit: \`ish workspace create\`,
-\`ish study create\`, \`ish study generate\`, \`ish iteration create\`,
+\`ish study create\`, \`ish study generate\`, \`ish ask create\`
+(and \`ish ask run --new\`), \`ish iteration create\`,
 \`ish person create\`, \`ish person generate\`.
 
-\`maxConcurrentParticipants\` gates how many participants can be in-flight
-at once per dispatch. \`maxWorkspaceMembers\` gates workspace membership
-(seats). Both are enforced server-side.
+\`maxConcurrentParticipants\` caps how many participants a single run can
+include — cumulative per iteration for studies, per ask for asks — and is
+enforced when participants are created/added, not at dispatch. \`maxSeats\`
+gates workspace membership (active members + pending invitations). Both are
+enforced server-side.
 
 ## What you see when a limit is hit
 
@@ -3292,6 +3304,7 @@ upgrade or delete an existing resource to free up headroom.
   that page is about *how many credits each run draws*).
 - \`concepts/workspace\` — \`maxProducts\` is per-account.
 - \`concepts/study\`     — \`maxStudiesPerProduct\` gates study creation.
+- \`concepts/ask\`       — \`maxAsksPerProduct\` gates ask creation.
 - \`concepts/iteration\` — \`maxIterationsPerStudy\` gates iteration creation.
 - \`concepts/person\`   — \`maxCustomPersons\` gates person creation.
 - \`reference/json-mode\` — full error envelope shape and exit codes.
@@ -4410,6 +4423,14 @@ The platform defaults to the iteration's; \`--app\` on \`study run\` overrides t
 stored target with a fresh local build. The WebDriverAgent runner cold-starts
 slowly the first time (~30-60s) and is then reused across participants.
 
+If the iteration was created **without** \`--app\` (its target is "chosen at run
+time"), supply the app on the run instead — there's nothing stored to default
+from:
+
+\`\`\`
+ish study run --local --platform ios --app ./Build.app --all --wait
+\`\`\`
+
 ## 3b. Parallel runs — \`--parallel N\` (iOS + Android)
 
 \`\`\`
@@ -4466,6 +4487,74 @@ reproducible runs.
 - \`reference/screenshots\` — grouped index vs per-interaction frames.
 - \`guides/first-study\` — the browser-URL version of this flow.
 `;
+const GUIDE_FEEDBACK = `# guide: report a bug or send feedback
+
+\`ish feedback\` files a bug report, feature request, or general note
+straight from the terminal — to the same place the web app's "Send
+feedback" dialog goes. As the agent operating the CLI, you usually see
+a failure first; this is how you hand it to the team without leaving
+the shell.
+
+\`\`\`bash
+ish feedback "the save button on the profile page does nothing"
+ish feedback --type feature "let me export interactions as CSV"
+ish feedback --type other "the guided setup was great"
+\`\`\`
+
+## The message
+
+Pass the body as the positional argument, or read it from elsewhere —
+the same idioms as other text fields:
+
+- \`ish feedback @bug-report.md\` — read the body from a file.
+- \`… 2>err.txt; ish feedback @err.txt\` — attach a failing command's output.
+- \`some-cmd 2>&1 | ish feedback -\` — read the body from stdin.
+
+The body must be at least 10 characters. \`--title\` is optional; by
+default the first line of the message becomes the title.
+
+## Type
+
+\`--type\` is one of \`bug\` (default), \`feature\`, or \`other\` — the same
+three the web dialog offers.
+
+## Diagnostics (help whoever debugs it)
+
+To give the debugger as much grounded signal as possible, the report
+auto-attaches an environment + account block: ish CLI version, OS,
+node, the logged-in account, and your active workspace/study/ask. Opt
+out with \`--no-diagnostics\`.
+
+\`--health\` adds more for simulation/setup bugs: it runs the \`ish check\`
+setup checklist (Xcode, simulators, adb, Chromium, account) and
+attaches the tail of \`~/.ish/local-sim.log\` when present. Use it
+whenever the bug involves \`study run --local\` or native device setup.
+
+\`--dry-run\` prints exactly what would be sent (message + diagnostics)
+without submitting — preview it first if you're unsure.
+
+## When the CLI nudges you to report
+
+On a *genuine fault* (uncategorized client error, 5xx/\`server\`, network
+failure, unknown throw) the CLI appends a hint: a \`report\` field in the
+\`--json\` error envelope, and a \`→ Looks like a bug? Report it: …\` line
+on stderr in human mode. It is intentionally **silent** on
+user-actionable failures (usage, validation, auth, not-found,
+usage-limit) so the nudge stays high-signal. When you see it, that
+error is worth an \`ish feedback\` — paste what you were doing and add
+\`--health\` if it was a local/native run.
+
+## Where it lands
+
+Sends as the logged-in user (run \`ish login\` first) through the ish
+backend, so reports show up alongside web feedback in the team's review
+surface. Output is the created row \`{id, type, title, status}\`.
+
+## Related
+
+- \`reference/json-mode\` — the \`report\` field + error envelope.
+- \`guides/native-app\` — when to reach for \`--health\`.
+`;
 const PAGES = [
     {
         slug: "overview",
@@ -4641,6 +4730,12 @@ const PAGES = [
         description: "One command wires the hosted ish MCP server into Cursor, VS Code, Claude Code, Claude Desktop, and Windsurf. Idempotent, atomic, preserves unrelated keys, no tokens written.",
         body: GUIDE_MCP_ADD,
     },
+    {
+        slug: "guides/feedback",
+        title: "guide: report a bug or send feedback (`ish feedback`)",
+        description: "File a bug/feature/other report from the terminal: message via arg/@file/stdin, --type, auto-attached environment+account diagnostics (--no-diagnostics to opt out), --health for setup checks + local-sim logs, --dry-run preview. Also: the `report` hint the CLI appends to genuine-fault errors.",
+        body: GUIDE_FEEDBACK,
+    },
 ];
 const PAGES_BY_SLUG = new Map(PAGES.map((p) => [p.slug, p]));
 export function listPages() {

package/dist/lib/local-sim/actions.d.ts

@@ -10,15 +10,31 @@
  * lives there, not here.
  */
 import type { Page } from "playwright-core";
-import type { LocalStepAction, ActionResult, ContextValue, TreeData } from "./types.js";
+import type { LocalStepAction, ActionResult, ContextValue, WireContextValue, TreeData } from "./types.js";
 import type { TabManager } from "./tabs.js";
 /**
  * Execute a single action on the page.
  */
 export declare function executeAction(page: Page, action: LocalStepAction, treeData: TreeData, contextValues: ContextValue[], tabs?: TabManager): Promise<ActionResult>;
+/**
+ * Normalize the backend's wire context-value shape ({@link WireContextValue}:
+ * `{key, requires_resolution, …}`) into the internal {@link ContextValue}
+ * ({name, type, …}) the executors and {@link resolveTextValue} consume.
+ *
+ * This mapping is the fix for a long-standing silent break: the backend has
+ * always sent `key`/`requires_resolution`, the CLI has always read `name`/`type`,
+ * and nothing mapped between them — so var/secret lookups never matched and the
+ * agent typed the literal key (e.g. `LOGIN_USERNAME`) into login fields on web,
+ * iOS and Android alike. `requires_resolution` is true for secrets (resolved at
+ * runtime) and false for preloaded variables.
+ */
+export declare function normalizeContextValues(wire: WireContextValue[]): ContextValue[];
 /**
  * Resolve the actual text to type from an action, handling var/secret value types.
- * Exported so the native (Android) executor can resolve values the same way.
+ * Exported so the native (Android/iOS) executors can resolve values the same way.
+ *
+ * `contextValues` must already be normalized via {@link normalizeContextValues}
+ * — the lookup matches on `name`, which is the backend's `key` post-mapping.
  */
 export declare function resolveTextValue(action: LocalStepAction, contextValues: ContextValue[]): string;
 /**

package/dist/lib/local-sim/actions.js

@@ -376,9 +376,32 @@ async function executeKeyboardShortcut(page, action) {
     await page.keyboard.press(combo);
 }
 // --- Helpers ---
+/**
+ * Normalize the backend's wire context-value shape ({@link WireContextValue}:
+ * `{key, requires_resolution, …}`) into the internal {@link ContextValue}
+ * ({name, type, …}) the executors and {@link resolveTextValue} consume.
+ *
+ * This mapping is the fix for a long-standing silent break: the backend has
+ * always sent `key`/`requires_resolution`, the CLI has always read `name`/`type`,
+ * and nothing mapped between them — so var/secret lookups never matched and the
+ * agent typed the literal key (e.g. `LOGIN_USERNAME`) into login fields on web,
+ * iOS and Android alike. `requires_resolution` is true for secrets (resolved at
+ * runtime) and false for preloaded variables.
+ */
+export function normalizeContextValues(wire) {
+    return wire.map(cv => ({
+        name: cv.key,
+        type: cv.requires_resolution ? "secret" : "var",
+        value: cv.value,
+        ...(cv.description != null && { description: cv.description }),
+    }));
+}
 /**
  * Resolve the actual text to type from an action, handling var/secret value types.
- * Exported so the native (Android) executor can resolve values the same way.
+ * Exported so the native (Android/iOS) executors can resolve values the same way.
+ *
+ * `contextValues` must already be normalized via {@link normalizeContextValues}
+ * — the lookup matches on `name`, which is the backend's `key` post-mapping.
  */
 export function resolveTextValue(action, contextValues) {
     if (action.value_type === "var" || action.value_type === "secret") {

package/dist/lib/local-sim/android.js

@@ -403,10 +403,15 @@ export class AndroidDevice {
             await settle(250);
         }
         const text = resolveTextValue(action, this.contextValues);
-        if (action.mode === "click_type") {
+        // Clear before typing by default — ADBKeyboard's type broadcast APPENDS, so
+        // a retried or app-pre-filled field would otherwise accumulate text. This is
+        // the replace-on-type semantic the browser (select-all+type) and iOS paths
+        // also use; previously only click_type cleared. Skip the clear+type entirely
+        // when there's nothing to type so an empty no-op can't wipe the field.
+        if (text) {
             await adbKeyboardClear();
+            await adbKeyboardType(text);
         }
-        await adbKeyboardType(text);
         if (action.submit) {
             await settle(150);
             await pressKeyEvent("KEYCODE_ENTER");

package/dist/lib/local-sim/ios.js

@@ -33,7 +33,7 @@
 import { resolveTextValue } from "./actions.js";
 import { requireOneBootedSimulator, screenshotPng, terminateApp, launchApp, installApp, uninstallApp, isAppInstalled, bundleIdFromApp, appBuildFromSimulator, } from "./simctl.js";
 // iOS UI interaction + a11y run through WebDriverAgent (XCUITest), not idb.
-import { ensureWda, closeWda, describeScreen, describeAll, activeBundleId, uiTap, uiLongPress, uiSwipe, uiText, uiKey, HID_KEY_RETURN, } from "./xcuitest.js";
+import { ensureWda, closeWda, describeScreen, describeAll, activeBundleId, uiTap, uiLongPress, uiSwipe, uiText, uiClearActiveField, uiKey, HID_KEY_RETURN, } from "./xcuitest.js";
 import { isLocalPath } from "../upload.js";
 import { deNormalizePoint, deNormalizeDrag, pointToPixel } from "./coordinates.js";
 import { parseXcuiHierarchy, serializeNativeTree, boundsCenter } from "./native-a11y.js";
@@ -456,12 +456,16 @@ export class IOSDevice {
             await settle(250);
         }
         const text = resolveTextValue(action, this.contextValues);
-        // WDA text input appends to the focused field; for click_type (replace) there
-        // is no idb "clear", so we rely on the field being empty after focus. The
-        // vision agent typically taps an empty field, so this matches Android's
-        // common path; a true select-all clear isn't exposed by idb.
-        if (text)
+        // WDA's /wda/keys APPENDS to the focused field, so clear it first — typing
+        // replaces by default (matching the browser select-all+type and Android's
+        // ADB_CLEAR_TEXT). uiClearActiveField uses WDA's native element clear on the
+        // focused element; it's best-effort, so a non-editable focus simply no-ops
+        // and we fall back to appending. Only clear when we actually have text to
+        // type, so an empty/no-op type never wipes the field.
+        if (text) {
+            await uiClearActiveField(this.udid);
             await uiText(this.udid, text);
+        }
         if (action.submit) {
             await settle(150);
             await uiKey(this.udid, HID_KEY_RETURN);

package/dist/lib/local-sim/loop.js

@@ -8,7 +8,7 @@
 import { appendFileSync } from "node:fs";
 import { launchSharedBrowser, FULL_PAGE_HEIGHT_CAP_PX_MOBILE, FULL_PAGE_HEIGHT_CAP_PX_DESKTOP, } from "./browser.js";
 import { uploadScreenshot } from "./upload.js";
-import { detectNoVisibleChange, describeAction, classifyStepKind } from "./actions.js";
+import { detectNoVisibleChange, describeAction, classifyStepKind, normalizeContextValues } from "./actions.js";
 import { createDevice } from "./device.js";
 import { nativeStateResetWarning } from "./ios.js";
 import { provisionDevicePool, maxConcurrentDevices, totalMemBytes, PER_DEVICE_MB, } from "./device-pool.js";
@@ -427,7 +427,10 @@ async function runSingleSimulation(client, participantId, participantName, opts,
         assignments: initResponse.assignments,
         participant_background: initResponse.participant_background,
         participant_language: initResponse.participant_language,
-        context_values: initResponse.context_values,
+        // Map the backend wire shape ({key, requires_resolution}) into the internal
+        // {name, type} ContextValue the devices/resolveTextValue expect. Without
+        // this every var/secret lookup misses and the literal key gets typed.
+        context_values: normalizeContextValues(initResponse.context_values),
         max_interactions: initResponse.max_interactions,
         agent_model: initResponse.agent_model,
         dom_model: initResponse.dom_model,

package/dist/lib/local-sim/types.d.ts

@@ -27,7 +27,7 @@ export interface LocalSimInitResponse {
     participant_background: Record<string, unknown> | null;
     participant_language: string | null;
     config: Record<string, unknown>;
-    context_values: ContextValue[];
+    context_values: WireContextValue[];
     max_interactions: number;
     agent_model: string;
     dom_model: string;
@@ -40,6 +40,32 @@ export interface LocalSimAssignment {
     instructions: string;
     sequence: number;
 }
+/**
+ * Wire shape of a context value exactly as the backend serializes it
+ * (ish-backend `app/runs/values.py` `ContextValue` → `/simulation/local/init`):
+ * the identifier field is `key` (NOT `name`), and `requires_resolution` is the
+ * secret-vs-variable discriminator (NO `type` field). The CLI normalizes this
+ * into the internal {@link ContextValue} shape at ingestion via
+ * {@link normalizeContextValues}.
+ *
+ * History: the internal shape below has used `name`/`type` since v0.7.0 while the
+ * backend has always sent `key`/`requires_resolution`. Because the two were
+ * assumed identical and consumed without mapping, every `resolveTextValue`
+ * lookup (`find(v => v.name === action.value)`) silently missed and the agent
+ * typed the literal key (e.g. `LOGIN_USERNAME`) into the field on every
+ * platform. Keep this interface faithful to the wire so the mismatch can't
+ * recur unnoticed.
+ */
+export interface WireContextValue {
+    key: string;
+    description?: string | null;
+    value: string | null;
+    requires_resolution: boolean;
+}
+/**
+ * Internal context-value shape used by the executors / {@link resolveTextValue}.
+ * Produced from {@link WireContextValue} by {@link normalizeContextValues}.
+ */
 export interface ContextValue {
     name: string;
     type: "var" | "secret";

package/dist/lib/local-sim/xcuitest.d.ts

@@ -76,6 +76,30 @@ export declare function uiText(udid: string, text: string): Promise<void>;
  * map it to a newline (see WDA_RETURN). Unknown codes are a no-op-safe error.
  */
 export declare function uiKey(udid: string, keycode: number): Promise<void>;
+/**
+ * Extract the element id from a WDA active-element payload, accepting both the
+ * W3C key and the legacy `ELEMENT` alias. Pure + exported for unit testing the
+ * (fiddly) key handling without a live runner. Returns null when the shape has
+ * no usable id (nothing focused / non-element response).
+ */
+export declare function parseActiveElementId(value: unknown): string | null;
+/**
+ * Clear the currently-focused text field via WDA's native element clear — the
+ * same select-all+delete Appium's `clear()` performs, so it handles multiline
+ * and arbitrary cursor positions correctly.
+ *
+ * Why this exists: `uiText` posts to `/wda/keys`, which APPENDS to the focused
+ * field. Without a clear, re-typing a field (a retry, or a field the app
+ * pre-filled) accumulates text (e.g. `LOGIN_USERNAMELOGIN_USERNAME…`). The
+ * coordinate/vision typing path has no element uuid up front, so we resolve the
+ * focused element with `GET …/element/active`, then `POST …/element/:uuid/clear`.
+ *
+ * Best-effort by design: a non-editable focus (or any WDA hiccup) just returns
+ * false and the caller falls back to the prior append behavior — clearing is an
+ * improvement, never a hard precondition for typing. Returns true when a clear
+ * was actually issued.
+ */
+export declare function uiClearActiveField(udid: string): Promise<boolean>;
 /** Re-export so a future ios.ts can drop the simctl HID constant. */
 export declare const HID_KEY_RETURN = 40;
 export {};

package/dist/lib/local-sim/xcuitest.js

@@ -331,5 +331,53 @@ export async function uiKey(udid, keycode) {
     const s = await getSession(udid);
     await wdaCall(s.port, "POST", `/session/${s.sessionId}/wda/keys`, { value: [WDA_RETURN] });
 }
+/**
+ * The W3C WebDriver element-reference key. `GET …/element/active` returns the
+ * focused element under this key (WDA also historically mirrors it as `ELEMENT`).
+ */
+const W3C_ELEMENT_KEY = "element-6066-11e4-a52e-4f735466cecf";
+/**
+ * Extract the element id from a WDA active-element payload, accepting both the
+ * W3C key and the legacy `ELEMENT` alias. Pure + exported for unit testing the
+ * (fiddly) key handling without a live runner. Returns null when the shape has
+ * no usable id (nothing focused / non-element response).
+ */
+export function parseActiveElementId(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const obj = value;
+    const id = obj[W3C_ELEMENT_KEY] ?? obj.ELEMENT;
+    return typeof id === "string" && id.length > 0 ? id : null;
+}
+/**
+ * Clear the currently-focused text field via WDA's native element clear — the
+ * same select-all+delete Appium's `clear()` performs, so it handles multiline
+ * and arbitrary cursor positions correctly.
+ *
+ * Why this exists: `uiText` posts to `/wda/keys`, which APPENDS to the focused
+ * field. Without a clear, re-typing a field (a retry, or a field the app
+ * pre-filled) accumulates text (e.g. `LOGIN_USERNAMELOGIN_USERNAME…`). The
+ * coordinate/vision typing path has no element uuid up front, so we resolve the
+ * focused element with `GET …/element/active`, then `POST …/element/:uuid/clear`.
+ *
+ * Best-effort by design: a non-editable focus (or any WDA hiccup) just returns
+ * false and the caller falls back to the prior append behavior — clearing is an
+ * improvement, never a hard precondition for typing. Returns true when a clear
+ * was actually issued.
+ */
+export async function uiClearActiveField(udid) {
+    try {
+        const s = await getSession(udid);
+        const active = unwrap(await wdaCall(s.port, "GET", `/session/${s.sessionId}/element/active`));
+        const uuid = parseActiveElementId(active);
+        if (!uuid)
+            return false;
+        await wdaCall(s.port, "POST", `/session/${s.sessionId}/element/${uuid}/clear`, {});
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Re-export so a future ios.ts can drop the simctl HID constant. */
 export const HID_KEY_RETURN = 40;

package/dist/lib/output.d.ts

@@ -46,7 +46,17 @@ export declare class ValidationError extends Error {
     hint?: string | undefined;
     constructor(message: string, valid_options: string[], hint?: string | undefined);
 }
-export declare function outputError(err: unknown, json: boolean): void;
+/**
+ * Whether an error is worth nudging the user to report via `ish feedback`.
+ * Excludes user-actionable failures — usage/validation, auth (login),
+ * not-found, and usage-limit (upgrade) — so the hint stays high-signal and
+ * agents don't reflexively report their own input mistakes. Genuine faults
+ * (5xx, unexpected client errors, unknown throws) get the nudge.
+ */
+export declare function shouldSuggestReport(err: unknown): boolean;
+export declare function outputError(err: unknown, json: boolean, opts?: {
+    suggestReport?: boolean;
+}): void;
 export declare function printTable(headers: string[], rows: string[][]): void;
 export declare function printKeyValue(obj: Record<string, unknown>, indent?: string): void;
 export declare function formatWorkspaceList(workspaces: Record<string, unknown>[], json: boolean): void;

package/dist/lib/output.js

@@ -562,8 +562,48 @@ function remapEntityName(message) {
         .replace(/\bAttachment not found\b/g, "Source not found")
         .replace(/\battachment not found\b/g, "source not found");
 }
-export function outputError(err, json) {
+// Shown after a genuine fault so the operating agent (the CLI's primary user)
+// knows it can hand the failure straight to the ish team. Kept short.
+const REPORT_HINT_HUMAN = 'Looks like a bug? Report it: ish feedback "what you were trying to do" (add --health for setup/sim issues)';
+const REPORT_HINT_JSON = 'ish feedback "<what you were trying to do>" — add --health for setup/sim issues';
+/**
+ * Whether an error is worth nudging the user to report via `ish feedback`.
+ * Excludes user-actionable failures — usage/validation, auth (login),
+ * not-found, and usage-limit (upgrade) — so the hint stays high-signal and
+ * agents don't reflexively report their own input mistakes. Genuine faults
+ * (5xx, unexpected client errors, unknown throws) get the nudge.
+ */
+export function shouldSuggestReport(err) {
+    if (err instanceof ValidationError)
+        return false;
+    if (err instanceof ApiError) {
+        if (err.status === 400 ||
+            err.status === 401 ||
+            err.status === 402 || // insufficient credits — buy credits, not a bug
+            err.status === 403 ||
+            err.status === 404 ||
+            err.status === 422) {
+            return false;
+        }
+        if (err.error_code === "usage_limit_reached")
+            return false;
+        return true;
+    }
+    if (err instanceof Error) {
+        const tagged = err;
+        if (err.name === "ValidationError")
+            return false;
+        if (tagged.error_code === "auth_failed")
+            return false;
+        if (tagged.error_kind === "ConfirmationRequired")
+            return false;
+        return true;
+    }
+    return true;
+}
+export function outputError(err, json, opts = {}) {
     const suggestions = suggestionsForError(err);
+    const report = opts.suggestReport === true;
     if (err instanceof ApiError) {
         // Surface backend-structured fields when present in the response body
         // (e.g. 422 errors return `errors: [{loc, msg, type, input, allowed_values}]`,
@@ -621,6 +661,7 @@ export function outputError(err, json) {
                 ...(seededAliases && { seeded_but_not_dispatched_aliases: seededAliases }),
                 ...(bodyErrors !== undefined && { errors: bodyErrors }),
                 ...(mergedSuggestions.length > 0 && { suggestions: mergedSuggestions }),
+                ...(report && { report: REPORT_HINT_JSON }),
             }));
         }
         else {
@@ -724,6 +765,7 @@ export function outputError(err, json) {
                 ...(seededIds && { seeded_but_not_dispatched_ids: seededIds }),
                 ...(seededAliases && { seeded_but_not_dispatched_aliases: seededAliases }),
                 ...(mergedSuggestions.length > 0 && { suggestions: mergedSuggestions }),
+                ...(report && { report: REPORT_HINT_JSON }),
             }));
         }
         else {
@@ -736,12 +778,24 @@ export function outputError(err, json) {
     }
     else {
         if (json) {
-            console.error(JSON.stringify({ error: String(err), error_code: "unknown_error", retryable: false }));
+            console.error(JSON.stringify({
+                error: String(err),
+                error_code: "unknown_error",
+                retryable: false,
+                ...(report && { report: REPORT_HINT_JSON }),
+            }));
         }
         else {
             console.error(`Error: ${err}`);
         }
     }
+    // A single human-mode nudge for genuine faults (gated by the caller via
+    // shouldSuggestReport). The JSON branches above carry the same hint as a
+    // `report` field. ValidationError's own JSON branch intentionally omits it
+    // (usage errors aren't bugs); the caller never sets suggestReport there.
+    if (!json && report) {
+        console.error(`  ${c.dim}→ ${REPORT_HINT_HUMAN}${c.reset}`);
+    }
 }
 // --- Entity-specific formatters (human mode) ---
 export function printTable(headers, rows) {

package/dist/lib/skill-content.js

@@ -1143,6 +1143,14 @@ table, projection shapes, and the defensive null-handling rules.
   confirmed. The orphan-tunnel-on-startup-404 bug is fixed.
 - The \`Warning: Could not verify token (network error). Proceeding
   anyway.\` stderr line is gone on green runs.
+- On a **genuine fault** (uncategorized client error, 5xx/\`server\`,
+  network, unknown throw) the error envelope adds a \`report\` field and
+  human mode prints a \`→ Looks like a bug? Report it: …\` line. File it
+  with \`ish feedback "what you were doing"\` (add \`--health\` for
+  local/native-run bugs). The nudge is deliberately silent on
+  user-actionable errors (usage, validation, auth, not-found,
+  usage-limit), so when you see it, it's worth reporting. See
+  guides/feedback.
 
 ## Common reshaping → use the CLI, not jq/python
 
@@ -1211,6 +1219,7 @@ ish <command> --help
 |             | study, ask, token validity) — alias \`whoami\`    |                             |
 | \`connect\`   | Cloudflare tunnel exposing localhost            | —                           |
 | \`upgrade\`   | Self-update                                     | —                           |
+| \`feedback\`  | Report a bug / feature request / note to the ish team. \`--health\` attaches setup checks + local-sim logs. | guides/feedback |
 
 ## Discovering flags safely
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ishlabs/cli",
-  "version": "0.27.1",
+  "version": "0.28.1",
   "description": "The command-line interface for ish",
   "type": "module",
   "bin": {