@ishlabs/cli 0.8.3 → 0.8.5

package/dist/lib/skill-content.js

@@ -96,6 +96,10 @@ use **ask** for quick reactions to text/image variants.
 ## High-frequency commands
 
 \`\`\`bash
+# First command on a cold start — confirms login + active context:
+ish status              # or: ish whoami
+# → user, active workspace/study/ask, token validity, API url
+
 # Auth & active selection (saved to ~/.ish/config.json)
 ish login
 ish workspace use w-6ec
@@ -136,15 +140,129 @@ See \`references/workflows.md\` in this skill for end-to-end transcripts:
 - Targeting a gated URL (basic auth, session cookie, login form)
 - Re-running a study with a fresh audience
 
+## Display vs. capture: the right output mode
+
+Three output modes — pick the one matching your intent, **don't reach
+for \`jq\` / \`python\` reflexively**:
+
+| Intent                                          | Use                  |
+|-------------------------------------------------|----------------------|
+| Show the user a list/table                      | bare command (TTY) or \`--human\` |
+| Capture one value to feed into the next command | \`--get <field>\`     |
+| Parse multiple fields / nested shape            | \`--json\`            |
+
+\`--get\` extracts a single field from the JSON response and prints its
+bare value. It supports dotted paths and auto-descends into list
+\`items\` so \`--get alias\` on a paginated list yields one alias per
+line. \`--human\` forces human output even when stdout is piped — use
+it when you want to \`tee\` a table to a file but still show it. The
+two flags are mutually exclusive (capture and display are different
+intents).
+
+### Worked example — capture in a script, display to the user
+
+\`\`\`bash
+# DON'T: shim around the CLI with jq just to grab one value.
+# ASK=$(ish ask create … --json | jq -r .alias)
+
+# DO: capture mode — bare value, exit 0.
+ASK=$(ish ask create --new --name demo \\
+        --prompt "Which?" --variant text:A --variant text:B \\
+        --sample 30 --get alias)
+
+# DON'T: pipe --json through jq when you want to show the user a table.
+# ish ask results "$ASK" --json | jq … | tee /tmp/x.txt
+
+# DO: --human keeps the table layout even through tee.
+ish ask results "$ASK" --human | tee /tmp/transcript.txt
+\`\`\`
+
+Missing field on \`--get\` → exit 2 with a usage error. \`--get\` also
+implies \`--quiet\` so the bare value is the only thing on stdout.
+
 ## Output handling
 
 - Every command supports \`--json\`. JSON mode is **auto-enabled when
   stdout is piped**, so an agent rarely needs \`--json\` explicitly.
+- **\`--get <field>\` is the right way to capture a single value.**
+  Dotted paths supported (\`tester_profile.name\`); on a paginated
+  \`{items: [...]}\` response, a leading non-\`items\` segment
+  auto-descends into items. Replaces the
+  \`--json | jq -r .field\` shim. Implies \`--json\` and \`--quiet\`.
+- **\`--human\` forces human output even when stdout is piped.** Use it
+  to \`tee\` a table without losing the layout. Mutually exclusive
+  with \`--get\`.
 - \`--fields a,b,c\` strips JSON output to the listed fields (saves
   tokens). \`--verbose\` adds full UUIDs and timestamps.
+- **Stdout is data only.** All progress, status, and "Open in browser"
+  hints go to stderr; \`--json | jq -e .\` parses cleanly without
+  defensive piping.
+- **List responses are a six-key envelope:** \`{items, total, returned,
+  limit, offset, has_more}\`. Use \`has_more\` to detect truncation;
+  don't count items yourself.
+- **Use \`runtime_status\`, not \`status\`, on study responses.** Values:
+  \`draft | running | completed | completed_with_errors | cancelled\`.
+  Derived from iteration testers' actual state — never reports
+  \`failed\` while completed runs exist. The CLI also surfaces
+  \`status_inferred\` + a stderr warning when raw \`status\` and the
+  testers disagree.
+- **\`study generate --json\` returns \`modality_rationale\`** (one
+  short sentence). Inspect it before adding iterations; if the LLM
+  picked the wrong modality, override via
+  \`ish study update <id> --modality text\`.
+- **Failed testers expose \`error_message\`.** \`study tester --json\`
+  and \`study results --json\` (in \`testers[]\`) include
+  \`error_message: "<reason>"\` for any tester with \`status: failed\`.
+  Don't drill into logs — read the field. \`study results\` also
+  includes a top-level \`failed_count\` alongside \`completed_count\`.
+- **\`ask add-questions\` is additive by default.** Appending a
+  follow-up question to a completed round preserves prior comments,
+  picks, and ratings; only the new question is dispatched. Pass
+  \`--redispatch-all\` for the legacy reset-and-rerun behavior.
+- **\`ask results --json\` adds \`cross_round_summary\` for 2+ rounds.**
+  Top-level field with per-round picks/winner snapshots and
+  \`picks_delta\` (R1 → last). Don't diff two \`ask results\` calls by
+  hand.
+- **\`--workspace\` works at the program root AND every subcommand.**
+  \`ish --workspace w-6ec study list\` and \`ish study list --workspace
+  w-6ec\` are equivalent; if both are passed, the subcommand-level
+  flag wins. Without either, the CLI falls back to \`ISH_WORKSPACE\`
+  env then the active workspace in \`~/.ish/config.json\`.
+- **\`profile generate\` emits stderr progress.** \`generating N
+  profiles…\` then \`generated N profiles\` around the ~10–20s LLM
+  call. Suppress with \`--quiet\`. Generated bios reference the
+  brief's domain context naturally (occupation, daily work,
+  frustrations) — they no longer parrot vocabulary from the brief
+  verbatim. DOBs spread across the year instead of all-on-\`06-15\`.
+- **Empty-pool errors include a country-suggestion line.** When
+  \`study run\` / \`ask run --new\` rejects because \`--country XX\`
+  matched zero profiles, the error includes the top-3 populated
+  countries that satisfy your *other* filters. Pivot directly without
+  a second \`profile list\` round-trip.
+- **\`<entity> list\` emits a stderr pagination hint** when
+  \`has_more=true\` and \`--quiet\` is unset. Goes to stderr in **every
+  mode** (including \`--json\` and piped stdout) — it never pollutes
+  machine-readable stdout but is visible to any agent reading stderr.
+  Format: "showing N–M of TOTAL; pass --offset M --limit N for more."
+- **\`study delete\` requires explicit confirmation.** Interactive:
+  prompts on stderr. Non-interactive (\`--json\`, piped, non-TTY
+  stdin): pass \`-y\` / \`--yes\` to confirm. Without it, the CLI
+  exits with usage code 2.
+- **\`ask add-questions\` supports \`--wait\` / \`--timeout\`.** Match
+  the parity of \`ask create\` and \`ask run\`. Without \`--wait\` the
+  command returns after dispatch (round still running).
+- **\`pick_confidence\` (0..1) is on every \`--wants-pick\` response.**
+  The model's self-reported confidence in its variant choice. Use it
+  to break ties when nominal pick counts are close. See
+  \`ish docs get-page concepts/ask\`.
 - Exit codes carry meaning: 0 success, 2 usage/validation,
   3 auth, 4 not-found, 5 transient. See
   \`ish docs get-page reference/json-mode\`.
+- **Tier limits surface as \`error_code: "usage_limit_reached"\`**
+  (HTTP 403, exit 1, non-retryable). The error body includes
+  \`tier\`, \`limit\`, \`current\`, \`max\`, \`upgrade_url\`. Do not
+  retry — branch on the code and surface the upgrade link. See
+  \`ish docs get-page reference/billing-limits\`.
 - Aliases (\`s-…\`, \`a-…\`, \`tp-…\`, \`i-…\`, \`t-…\`, \`tps-…\`, \`w-…\`)
   are accepted anywhere a UUID is. See
   \`ish docs get-page reference/aliases\`.
@@ -153,22 +271,42 @@ See \`references/workflows.md\` in this skill for end-to-end transcripts:
 
 1. **Don't paste flags from memory.** The CLI evolves; flags change.
    Run \`ish <command> --help\` to confirm before constructing a command.
-2. **Don't run \`ish study run\` before an iteration exists** — create
-   one first via \`ish iteration create --url …\` (or \`--content-url …\`
-   for media studies). The error message tells you this, but the round
-   trip wastes time.
-3. **Don't pass \`--profile\` together with demographic filters** — they
+2. **Don't pipe \`--json\` through \`python\`/\`jq\` to reshape output** —
+   the CLI already has the affordances:
+   - Inspect a few specific entities? \`ish profile get tp-1b9 tp-fc1
+     tp-2fc\` (also works for \`study get\`, \`iteration get\`, \`ask
+     get\`). Returns a \`{items:[...], total:N}\` envelope.
+   - Want only certain fields? \`--fields alias,name,country,occupation\`.
+   - Need counts of a nested array? \`ask get\` / \`ask create --wait\`
+     already include \`testers_count\`, \`responses_total\`,
+     \`responses_complete\` (per-round and aggregate). Don't recount.
+   - Want machine-readable A/B verdicts? \`ask results --json\` already
+     ships \`aggregates: { picks, ratings, winner }\` per round.
+3. **Don't run \`ish study run\` against an empty study.** \`ish study
+   create\` and \`ish study generate\` no longer auto-create iteration
+   A — the first explicit \`ish iteration create\` becomes A. Running
+   \`study run\` on a study with zero iterations exits 2; create one
+   first via \`ish iteration create --url …\` / \`--content-url …\` /
+   \`--content-text …\`. Or pass \`--content-text\` / \`--url\` directly
+   on \`study create\` for a one-shot study + iteration A.
+4. **Don't pass \`--profile\` together with demographic filters** — they
    are mutually exclusive. Either explicit IDs or
    \`--country\`/\`--gender\`/\`--min-age\`/\`--max-age\` + \`--sample\`.
-4. **Don't change audience between rounds of an ask.** It's fixed at
+5. **Don't change audience between rounds of an ask.** It's fixed at
    ask creation. Use \`ish ask add-testers\` to *extend* it; you can't
    replace it.
-5. **Don't try to put credentials in the URL** for gated study URLs.
+6. **Don't try to put credentials in the URL** for gated study URLs.
    Configure them once on the workspace via
    \`ish workspace site-access …\` (basic-auth, cookie, login).
    See \`ish docs get-page concepts/site-access\`.
-6. **Don't commit \`~/.ish/config.json\`** — it stores tokens and active
+7. **Don't commit \`~/.ish/config.json\`** — it stores tokens and active
    workspace/study/ask selections. It lives in \`$HOME\`, not the repo.
+8. **Don't retry \`usage_limit_reached\` errors.** Tier caps
+   (\`maxProducts\`, \`maxStudiesPerProduct\`, \`maxIterationsPerStudy\`,
+   \`maxCustomTesterProfiles\`) are enforced server-side. The error body
+   carries \`tier\`, \`limit\`, \`current\`, \`max\`, \`upgrade_url\` — show
+   the upgrade link or delete an existing resource to free headroom.
+   See \`ish docs get-page reference/billing-limits\` for the table.
 
 ## Authentication
 
@@ -238,9 +376,17 @@ ish ask run --new --name "hero shots" \\
     --variant image:./hero-b.png::label=B \\
     --sample 30 --wants-pick --wait
 
-ish ask results --json | jq .
+# Read the verdict directly — no comment-parsing required:
+ish ask results --json | jq '.rounds[0].aggregates'
+# → { "picks": { "A": 22, "B": 8 },
+#     "winner": { "letter": "A", "count": 22, "tied": false } }
 \`\`\`
 
+For \`--wants-pick\` / \`--wants-ratings\` rounds, \`ask results --json\`
+adds an \`aggregates\` field per round with \`picks\`, \`ratings\` (mean
++ n per variant), and a \`winner\`. See \`ish docs get-page
+reference/json-mode\` for the full shape.
+
 Add a follow-up round with no audience change:
 
 \`\`\`bash
@@ -334,6 +480,35 @@ URL=$(jq -r 'select(.status=="connected") | .tunnel_url' /tmp/ish-tunnel.log | h
 ish iteration create --url "$URL"
 \`\`\`
 
+## 7. Display-vs-capture: a script that does both
+
+Goal: drive an A/B in a script, capture aliases without \`jq\`, and
+still show the human a readable result table at the end.
+
+\`\`\`bash
+# Capture mode — bare values, suitable for shell variables.
+ASK=$(ish ask create --new --name "tagline AB" \\
+        --prompt "Which sounds better?" \\
+        --variant text:"Short and punchy." \\
+        --variant text:"A longer, descriptive line." \\
+        --sample 30 --wants-pick --get alias)
+
+# Wait silently — exit code is what matters here.
+ish ask wait "$ASK" --timeout 600 --quiet
+
+# Capture the winner letter for downstream branching:
+WINNER=$(ish ask results "$ASK" --get rounds.aggregates.winner.letter)
+echo "Winning variant: $WINNER"
+
+# Display mode — show the user the full results table even though
+# we're inside a script (stdout is piped to tee).
+ish ask results "$ASK" --human | tee "/tmp/ask-\${ASK}.txt"
+\`\`\`
+
+The mental rule: **\`--get\` is for capture, bare commands / \`--human\`
+are for display, \`--json\` is for chaining (multiple fields at once).**
+If you find yourself reaching for \`jq -r .x\`, you wanted \`--get x\`.
+
 ## Tips for chaining commands as an agent
 
 - Capture aliases from JSON: \`ITER=$(ish iteration create --url … --json | jq -r .alias)\`
@@ -348,6 +523,31 @@ ish iteration create --url "$URL"
   the full Ask payload.
 - For \`profile generate --json\`, \`simulation_config\` is trimmed by
   default (~9× smaller). Pass \`--include-simulation-config\` to include it.
+- On \`error_code: "usage_limit_reached"\` (HTTP 403), don't retry —
+  read \`tier\`, \`limit\`, \`current\`, \`max\`, and \`upgrade_url\` from
+  the JSON body to construct a recovery message. \`profile generate\` /
+  \`study generate\` refuse the entire batch when the post-generation
+  count would exceed the cap; re-issue with a smaller \`--count\`.
+
+## Common reshaping → use the CLI, not jq/python
+
+| You want to…                              | Don't                                  | Do                                                                 |
+|-------------------------------------------|----------------------------------------|--------------------------------------------------------------------|
+| Capture a single value (alias, id, …)     | \`--json \\| jq -r .alias\`             | \`--get alias\`                                                      |
+| Capture a nested value                    | \`--json \\| jq -r .tester_profile.name\` | \`--get tester_profile.name\`                                        |
+| Capture every alias from a list           | \`--json \\| jq -r '.items[].alias'\`   | \`--get alias\` (auto-descends into \`items\`, one per line)            |
+| Force human output through tee/redirect   | none, output silently became JSON      | \`--human\`                                                          |
+| Look up 2-3 specific profiles             | \`profile list --json \\| jq '.items[] \\| select(...)'\` | \`ish profile get tp-1b9 tp-fc1 tp-2fc\`                             |
+| Show only some fields                     | \`--json \\| jq '{alias, name, country}'\` | \`--fields alias,name,country\`                                      |
+| Count testers on an ask                   | \`--json \\| jq '.testers \\| length'\`  | \`ish ask get a-… --fields alias,testers_count\`                     |
+| Count responses on a round                | \`--json \\| jq '.rounds[0].responses \\| length'\` | \`ish ask get a-… --fields alias,rounds,responses_complete,responses_total\` |
+| Pick the A/B winner                       | \`--json \\| jq '.rounds[0].responses…'\` | \`ish ask results a-… --json\` then read \`.rounds[].aggregates.winner\` |
+| List of testers from \`study run\`        | \`--json \\| jq '.testers[].id'\`        | \`--get tester_aliases\` (or \`tester_ids\` for UUIDs)                |
+
+The bias here is intentional: \`ish\` ships shapes designed for agent
+consumption. If you find yourself reaching for \`jq\` or \`python\` to
+reshape ish output, run \`ish docs search <keyword>\` first — there is
+almost always a flag that does the work for you.
 `;
 const COMMANDS_MD = `# ish commands — quick index
 
@@ -376,6 +576,8 @@ ish <command> --help
 |             | Cursor / Cline / Roo project                    |                             |
 | \`login\`     | Browser-based auth                              | —                           |
 | \`logout\`    | Clear saved credentials                         | —                           |
+| \`status\`    | Show active session (user, workspace,           | concepts/active-context     |
+|             | study, ask, token validity) — alias \`whoami\`    |                             |
 | \`connect\`   | Cloudflare tunnel exposing localhost            | —                           |
 | \`upgrade\`   | Self-update                                     | —                           |
 
@@ -403,6 +605,8 @@ is expected. Full UUIDs always work too. See
 
 | Flag             | Effect                                                   |
 |------------------|----------------------------------------------------------|
+| \`--get <field>\`  | **Capture mode.** Print the bare value at the dotted path; auto-descends into list \`items\`. Implies \`--json\` + \`--quiet\`. Replaces \`--json \\| jq -r .field\`. |
+| \`--human\`        | **Force display mode** even when stdout is piped (overrides JSON-when-piped). Mutually exclusive with \`--get\`. |
 | \`--json\`         | JSON output (auto-on when stdout is piped)               |
 | \`--fields a,b\`   | Keep only listed fields in JSON                          |
 | \`--verbose\`      | Include UUIDs + timestamps in JSON                       |
@@ -410,6 +614,9 @@ is expected. Full UUIDs always work too. See
 | \`-t, --token\`    | Auth token (else ISH_TOKEN env, else \`ish login\` saved)  |
 | \`--api-url\`      | Override backend (default https://api.ishlabs.io)        |
 
+See \`ish docs get-page reference/json-mode\` for the full display-vs-
+capture-vs-chain decision rule.
+
 ## Exit codes
 
 \`0\` ok · \`1\` general · \`2\` usage/validation · \`3\` auth ·

package/dist/lib/types.d.ts

@@ -97,6 +97,7 @@ export interface StudyCreateInput {
     assignments?: Assignment[];
     interview_questions?: InterviewQuestion[];
     start_frame_id?: string;
+    iteration?: IterationCreateInput;
 }
 export interface StudyUpdateInput {
     name?: string;
@@ -124,7 +125,7 @@ export interface Iteration {
     updated_at: string;
 }
 export interface IterationCreateInput {
-    name: string;
+    name?: string;
     description?: string;
     details?: Record<string, unknown>;
 }
@@ -290,6 +291,7 @@ export interface AddTestersInput {
 }
 export interface AddRoundQuestionsInput {
     questions: InterviewQuestion[];
+    redispatch_all?: boolean;
 }
 export interface AskAudienceTester {
     id: string;

package/dist/upgrade.js

@@ -40,10 +40,10 @@ export async function upgrade(currentVersion, targetVersion) {
     }
     const latest = targetVersion || (await getLatestVersion());
     if (latest === currentVersion) {
-        console.log(`Already up to date (v${currentVersion}).`);
+        console.error(`Already up to date (v${currentVersion}).`);
         return;
     }
-    console.log(`Updating ish v${currentVersion} → v${latest}...`);
+    console.error(`Updating ish v${currentVersion} → v${latest}...`);
     const target = getPlatformTarget();
     const ext = process.platform === "win32" ? ".exe" : "";
     const assetName = `ish-${target}${ext}`;
@@ -100,5 +100,5 @@ export async function upgrade(currentVersion, targetVersion) {
         chmodSync(tmpPath, 0o755);
         renameSync(tmpPath, execPath);
     }
-    console.log(`Updated to v${latest}.`);
+    console.error(`Updated to v${latest}.`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ishlabs/cli",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "The command-line interface for Ish",
   "type": "module",
   "bin": {