@ishlabs/cli 0.8.3 → 0.8.4

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
@@ -142,9 +146,47 @@ See \`references/workflows.md\` in this skill for end-to-end transcripts:
   stdout is piped**, so an agent rarely needs \`--json\` explicitly.
 - \`--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\` is accepted on every workspace-scoped subcommand.**
+  Pass it reflexively on any \`ask\`/\`study\`/\`iteration\`/\`profile\`/
+  \`source\` subcommand — when workspace is inferable from an ID alias
+  it's silently ignored.
 - 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 +195,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 +300,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
@@ -348,6 +418,27 @@ 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                                                                 |
+|-------------------------------------------|----------------------------------------|--------------------------------------------------------------------|
+| 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'\`        | \`--json\` already has \`tester_ids[]\` and \`tester_aliases[]\`        |
+
+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 +467,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                                     | —                           |
 

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.4",
   "description": "The command-line interface for Ish",
   "type": "module",
   "bin": {