@ishlabs/cli 0.8.4 → 0.9.0

package/dist/lib/docs.js

@@ -18,7 +18,7 @@ Workspace (= product)
 ├── Tester Profiles ────── reusable audience personas (alias: tp-…)
 │     └── Sources ──────── transcripts/audio/images that seed generation
 ├── Study ──────────────── persistent research artifact (alias: s-…)
-│     ├── modality ──────── interactive | text | video | audio | image | document
+│     ├── modality ──────── interactive | text | video | audio | image | document | chat
 │     ├── assignments ───── tasks the tester does
 │     ├── questionnaire ─── questions the tester answers
 │     └── Iterations ────── one configured run (URL or content) (alias: i-…)
@@ -47,7 +47,8 @@ Two top-level run verbs:
   and prints active workspace/study/ask. See \`concepts/active-context\`.
 - Running your first study? \`ish docs get-page guides/first-study\`.
 - Comparing study vs ask? \`ish docs get-page concepts/run-verbs\`.
-- Need machine-readable output? \`ish docs get-page reference/json-mode\`.
+- **Output modes** (display vs capture vs chain — \`--human\`, \`--get\`,
+  \`--json\`)? \`ish docs get-page reference/json-mode\`.
 - Auth gated URL? \`ish docs get-page concepts/site-access\`.
 
 ## Install the skill into this project
@@ -74,6 +75,22 @@ A workspace carries:
 - Site-access credentials (encrypted at rest) — see \`concepts/site-access\`.
 - Tester profiles + sources visible to every study/ask in the workspace.
 
+## Selecting a workspace per command
+
+\`--workspace <id>\` works at the **program root** as well as on each
+subcommand — both forms are equivalent, and the subcommand-level flag
+wins on conflict:
+
+\`\`\`
+ish --workspace w-6ec study list           # program root
+ish study list --workspace w-6ec           # subcommand (same effect)
+ish --workspace w-6ec study list --workspace w-other   # w-other wins
+\`\`\`
+
+Use whichever is most natural for your scripting. Without either, the
+CLI falls back to \`ISH_WORKSPACE\` (env var) and then the
+\`workspace\` saved in \`~/.ish/config.json\`.
+
 ## Common commands
 
 \`\`\`
@@ -91,8 +108,9 @@ ish workspace site-access status
 const CONCEPT_STUDY = `# concept: study
 
 A **study** is the persistent research artifact. It defines:
-- \`modality\`: \`interactive\` (the tester drives a real browser) or one of
-  \`text | video | audio | image | document\` (media reaction studies).
+- \`modality\`: \`interactive\` (the tester drives a real browser), one of
+  \`text | video | audio | image | document\` (media reaction studies),
+  or \`chat\` (multi-turn probe against an external chatbot endpoint).
 - \`content_type\` (media studies only): \`email | social_post | ad | …\` —
   controls the framing the tester is given.
 - \`assignments\`: the tasks the tester performs. See \`concepts/assignment\`.
@@ -148,6 +166,21 @@ Every study response carries two status-shaped fields:
 The CLI also surfaces a \`status_inferred\` field + stderr warning when
 it detects raw-vs-derived inconsistencies. See \`reference/json-mode\`.
 
+## Deleting a study
+
+\`ish study delete <id>\` requires explicit confirmation:
+
+- **Interactive (TTY)**: prompts on stderr; type \`y\` to proceed.
+- **Non-interactive** (\`--json\`, piped, or non-TTY stdin): pass
+  \`-y\` / \`--yes\` to confirm. Without it, the CLI exits with usage
+  code 2 rather than deleting silently.
+
+\`\`\`
+ish study delete s-b2c              # interactive prompt
+ish study delete s-b2c --yes        # skip prompt
+ish study delete s-b2c --json --yes # JSON consumers must be explicit
+\`\`\`
+
 ## Generate vs create
 
 \`ish study generate --problem "..."\` runs an LLM-backed flow that
@@ -168,9 +201,9 @@ pick was wrong.
 const CONCEPT_ITERATION = `# concept: iteration
 
 An **iteration** is one configured run of a study. It carries the
-volatile bits — the URL (interactive) or the media (video/text/etc.) —
-while the study carries the persistent shape (assignments, questionnaire,
-modality).
+volatile bits — the URL (interactive), the media (video/text/etc.), or
+the chatbot endpoint (chat) — while the study carries the persistent
+shape (assignments, questionnaire, modality).
 
 - Alias prefix: \`i-\`
 - A study has 1..N iterations. \`ish study run\` defaults to the latest.
@@ -192,9 +225,19 @@ ish iteration create --study s-b2c --url https://example.com
 # Interactive on mobile screen format:
 ish iteration create --url https://example.com --screen-format mobile_portrait
 
+# Figma interactive (file_key + start_node_id required):
+ish iteration create --platform figma --url https://figma.com/proto \\
+    --screen-format mobile_portrait --file-key abc123 --start-node-id 0:1 \\
+    --flow-name "Onboarding A"
+
 # Text/email content from a file:
 ish iteration create --content-text @./email.html --title "Newsletter"
 
+# Email iteration with sender + featured hero image:
+ish iteration create --content-text @./email.txt --content-html @./email.html \\
+    --sender-name "Marketing" --sender-email "marketing@example.com" \\
+    --featured-image-url https://cdn.example.com/hero.png
+
 # Video (URL or local file):
 ish iteration create --content-url ./video.mp4
 
@@ -204,11 +247,113 @@ ish iteration create --image-urls "./a.png,./b.png"
 # Document (PDF):
 ish iteration create --content-url ./report.pdf
 
+# Chat — probe a saved chatbot endpoint:
+ish iteration create --chat-endpoint-id ce-... --max-turns 10 --early-termination
+
 # Inspect:
 ish iteration list --study s-b2c
 ish iteration get i-d4e
 \`\`\`
 
+## Segments and segment labels
+
+For media iterations (video, audio, text, image, document), reactions
+can be collected per **segment** instead of over the whole asset. A
+segment is a contiguous slice of the iteration's content — a 30-second
+window of a video, a paragraph range of an email, a section of a PDF.
+Each segment can carry a human-readable **label** ("Intro", "Pricing
+section", "Call to action") that surfaces in the tester UI and in
+results.
+
+Segments live inside the iteration's \`segmentation\` field — there is
+no separate segments resource. Three discriminated shapes:
+
+- **time_based** (video, audio): boundaries in seconds. Segment 0 runs
+  from \`intervals_seconds[0]\` to \`intervals_seconds[1]\`, etc.
+  Optional \`labels[]\` names each segment.
+
+  \`\`\`json
+  {
+    "type": "time_based",
+    "intervals_seconds": [0, 30, 60, 90],
+    "labels": ["Hook", "Feature 1", "Feature 2", "CTA"]
+  }
+  \`\`\`
+
+- **section_based** (text, document, image copy): explicit list of
+  named sections, either marker-bounded or paragraph-bounded.
+
+  \`\`\`json
+  {
+    "type": "section_based",
+    "sections": [
+      { "name": "intro", "label": "Intro",   "paragraph_start": 0, "paragraph_end": 1 },
+      { "name": "body",  "label": "Body",    "paragraph_start": 1, "paragraph_end": 4 },
+      { "name": "cta",   "label": "Call to action", "paragraph_start": 4, "paragraph_end": 5 }
+    ]
+  }
+  \`\`\`
+
+- **page_based** (document): pages are auto-derived from the document.
+  No additional fields.
+
+Pass via \`--segmentation-json '<json>'\` on \`iteration create\`.
+
+### Default segmentation for text/image iterations
+
+For text- and image-modality iterations created without
+\`--segmentation-json\`, the worker synthesises a single whole-content
+section so a minimal \`ish iteration create --content-text "..."\` runs
+end-to-end. Author your own segmentation when you want section-level
+reactions; otherwise the default just works.
+
+### content_config — early termination + selected segments
+
+A sibling of \`segmentation\` that controls how the tester progresses
+through segments:
+
+- \`early_termination: true\` — stop the session once every selected
+  segment has been seen.
+- \`selected_segment_indices: [0, 2]\` — only show these segment
+  indices; \`null\` (default) means all segments are active.
+
+Pass via \`--content-config-json '<json>'\`.
+
+## HTML content (text + media captions)
+
+- **Text modality**: pair plain \`--content-text\` with rich
+  \`--content-html\` to render emails / articles with formatting. The
+  plain text is what testers reason over; the HTML is what they see.
+- **Media captions** (video, audio, image): \`--copy-text\` and
+  \`--copy-html\` attach a caption to the media — the social-post
+  pattern. Add \`--social-platform\` (instagram/tiktok/facebook/linkedin/x)
+  for platform-specific framing, and \`--copy-position before|after\`
+  for ordering relative to the media.
+
+Captions can carry their own segmentation when you want
+paragraph-by-paragraph reactions to a long caption. Use the
+\`--details-json\` escape hatch to pass a nested
+\`copy_content.segmentation\`.
+
+## Chat modality
+
+Chat iterations probe an external chatbot endpoint by having a tester
+hold a multi-turn conversation against it. Two ways to wire the
+endpoint:
+
+\`\`\`
+# Reference a saved endpoint row (recommended — reproducible):
+ish iteration create --chat-endpoint-id ce-...
+
+# Inline endpoint config (one-off):
+ish iteration create --chat-endpoint-json '{"url":"https://...","headers":{...}}'
+\`\`\`
+
+Tunables:
+- \`--max-turns N\` — cap the conversation length (default 12, max 50).
+- \`--early-termination\` — let the worker end the session early when
+  the tester signals the conversation is over.
+
 ## No more auto-empty iteration A
 
 \`ish study create\` and \`ish study generate\` **do not auto-create
@@ -229,16 +374,6 @@ then retry.
 
 Treat this as actionable, not transient — re-running won't change anything.
 
-## Default segmentation for text/image iterations
-
-For text-modality iterations created with just \`--content-text\` (and
-similarly \`--image-urls\` for image), the worker now synthesises a
-single whole-content section if no \`segmentation\` was supplied. This
-means a minimal \`ish iteration create --study s-XYZ --content-text
-"..."\` actually runs end-to-end without you needing to author a
-SegmentationConfig manually. Author your own segmentation when you
-want section-level reactions; otherwise the default just works.
-
 ## Related
 
 - \`concepts/study\` — the parent artifact.
@@ -379,7 +514,12 @@ ish ask results a-6ec --json | jq '.rounds[0].aggregates'
 
 For \`--wants-pick\` / \`--wants-ratings\` rounds, \`ask results --json\`
 includes an \`aggregates\` field per round so you don't have to parse
-prose:
+prose. Each individual pick also carries a **\`pick_confidence\`** score
+(0..1) — the model's self-reported confidence in its variant choice.
+Use it to break ties: when two variants are nominally close on count,
+the variant with higher mean \`pick_confidence\` is the more decisive
+choice. \`pick_confidence\` is only present on rounds run with
+\`--wants-pick\`.
 
 \`\`\`json
 {
@@ -517,6 +657,24 @@ ish profile create --file profile.json
 Expected JSON: \`{ "name": "...", "type": "ai", "gender": "female",
 "country": "US", "occupation": "...", "bio": "..." }\`
 
+## Generation behavior to expect
+
+- **Latency**: \`profile generate\` is LLM-backed and typically takes
+  10–20s for 1–5 profiles. The CLI emits stderr progress lines
+  (\`generating N profiles…\` then \`generated N profiles\`) so you
+  know it's not stuck. Suppress with \`--quiet\`.
+- **Brief fidelity**: bios reference domain-specific terms from your
+  description verbatim or as close paraphrase. If you mention
+  \`F-skatt\`, "manual Excel invoicing", "Stripe payouts", or similar
+  tools/jargon, expect those terms (or paraphrases) to appear in
+  each generated bio's daily-routine framing — not sanded down to
+  generic prose.
+- **DOB diversity**: month-and-day are derived from a deterministic
+  per-profile hash so birthdays spread across the year (no more
+  every-profile-on-\`06-15\`). Year follows the requested age.
+  Re-generating the same name/country/occupation/age yields the
+  same DOB.
+
 ## Related
 
 - \`concepts/source\` — the inputs to \`profile generate\`.
@@ -577,6 +735,24 @@ flags. Two ways to select:
 The two modes are **mutually exclusive** — pass either \`--profile\` or
 the filter set, not both.
 
+## Empty-pool suggestions
+
+When a filter combination matches zero profiles, the error message
+includes the top three populated countries that satisfy your *other*
+filters — so you can pivot to a country with actual coverage without a
+second \`profile list\` round-trip:
+
+\`\`\`
+$ ish study run --country XX --min-age 35 --sample 5
+Error: No simulatable AI tester profiles in workspace w-b32 match:
+       --country XX --min-age 35.
+       Populated countries with these other filters: SE (12), DE (8), NL (3).
+       Broaden your filters or run \`ish profile list\` to inspect the pool.
+\`\`\`
+
+The suggestion is best-effort — it never replaces the original error,
+just augments it.
+
 ## Defaults
 
 - \`ish study run\` with no audience flags → reuses the iteration's
@@ -709,6 +885,13 @@ ish study cancel <tester_id>              # cancel a running simulation
 \`<tester_id>\` accepts a tester alias (\`t-…\`) or a full UUID. The
 study-level \`poll\`/\`wait\` forms also exist (\`--study <id>\` /
 \`--iteration <id>\`) for whole-batch progress.
+
+## Related
+
+- \`reference/json-mode\` — output modes (display vs capture vs chain).
+  Use \`--get tester_aliases\` to capture the run's testers without
+  piping through \`jq\`. \`--human\` forces table output even through
+  \`tee\`/redirection.
 `;
 const REFERENCE_ALIASES = `# reference: aliases
 
@@ -740,15 +923,84 @@ ish profile generate --source tps-3a4 --count 4
 The full UUID is also always accepted. Add \`--verbose\` to JSON output
 to see UUIDs alongside aliases.
 `;
-const REFERENCE_JSON_MODE = `# reference: JSON output for agents
+const REFERENCE_JSON_MODE = `# reference: output modes for agents
+
+\`ish\` distinguishes **three output modes** so agents don't have to
+post-process CLI output with \`jq\` or \`python\` for routine tasks:
+
+1. **Display mode (human)** — readable tables and key/value blocks.
+   Default on a TTY. Force it anywhere with \`--human\` (e.g. \`ish
+   workspace list --human | tee /tmp/x.txt\` keeps the table layout
+   even though stdout is redirected).
+2. **Capture mode (single value)** — \`--get <field>\` extracts the
+   value at a dotted path and prints it bare (no JSON quotes, no
+   indentation). Use this to feed one CLI's output into another:
+   \`ASK=$(ish ask create … --get alias)\` instead of
+   \`ASK=$(ish ask create … --json | jq -r .alias)\`.
+3. **Chain mode (full JSON)** — \`--json\` (or auto-enabled when stdout
+   is piped). Returns structured payloads for downstream parsing.
+   Reach for this only when you actually need multiple fields or a
+   nested shape; for one value, \`--get\` is shorter.
+
+## Picking the right mode
+
+| You want to…                              | Mode                                             |
+|-------------------------------------------|--------------------------------------------------|
+| Show the user a list of workspaces        | bare command (TTY) or \`--human\` if redirecting   |
+| Capture an alias for a follow-up command  | \`--get alias\`                                   |
+| Inspect a specific nested field           | \`--get tester_profile.name\`                     |
+| Compare 2+ fields, or pipe into jq        | \`--json\` (or auto-on when piped)                |
+| Force human output through \`tee\`         | \`--human\`                                       |
+| Force JSON on a TTY                       | \`--json\`                                        |
+
+\`--get\` and \`--human\` are mutually exclusive — capture and display are
+different intents; pick one. \`--get\` implies \`--json\` internally so the
+renderer always has structured data to extract from; you don't need to
+add \`--json\` yourself.
+
+### Worked example: display vs. capture
+
+\`\`\`bash
+# Display: bare command on a TTY → human table.
+ish workspace list
+
+# Capture: feed one alias into the next command, no jq required.
+ASK=$(ish ask create --new --name demo \\
+        --prompt "Which?" --variant text:A --variant text:B \\
+        --sample 30 --get alias)
+ish ask wait "$ASK" --timeout 600
+
+# Capture across an entire list: one value per line.
+ish workspace list --get alias
+# w-6ec
+# w-d02
+# …
 
-Every command that produces output supports machine-readable JSON. JSON
-mode is **auto-enabled when stdout is piped**, so an agent rarely needs
-\`--json\` explicitly.
+# Display preserved through tee:
+ish ask results "$ASK" --human | tee /tmp/transcript.txt
+\`\`\`
 
 ## Flags
 
-- \`--json\`            — force JSON output even on a TTY.
+- \`--human\`            — force human-readable output regardless of TTY
+                          state (overrides the auto-flip-to-JSON when
+                          stdout is piped). Mutually exclusive with
+                          \`--get\`.
+- \`--get <field>\`      — extract a single field from the JSON response
+                          and print only its bare value. Supports dotted
+                          paths (\`tester_profile.name\`). On a paginated
+                          \`{items: [...]}\` response, the path
+                          auto-descends into \`items\` so \`--get alias\`
+                          on a list yields one value per line. Implies
+                          \`--json\` internally; mutually exclusive with
+                          \`--human\`. Strings/numbers/bools are printed
+                          unquoted; \`null\` prints as an empty line;
+                          arrays print one element per line; objects
+                          print as compact one-line JSON. Missing field
+                          → exit 2 with a usage error.
+- \`--json\`             — force JSON output even on a TTY. Auto-enabled
+                          when stdout is piped (unless \`--human\` is
+                          set).
 - \`--fields a,b,c\`    — keep only these fields in JSON output (e.g.
                           \`alias,name,status\`). Filters per item only;
                           list wrappers (\`{items, total, returned,
@@ -757,7 +1009,9 @@ mode is **auto-enabled when stdout is piped**, so an agent rarely needs
                           write paths) the full server payload instead
                           of the compact response.
 - \`-q, --quiet\`        — suppress progress messages on stderr (errors
-                          still go to stderr).
+                          still go to stderr). \`--get\` implies
+                          \`--quiet\` so the bare value is the only
+                          thing on stdout.
 
 ## Stable shape rules
 
@@ -854,9 +1108,12 @@ The CLI guarantees these contracts so agents can chain safely:
   in the \`testers[]\` array, and a "Failed testers" subsection in
   human output. Empty when the tester succeeded.
 - **\`profile list\` emits a stderr pagination hint** when
-  \`has_more=true\` and stdout is human (TTY, not piped, not \`--quiet\`).
-  Format: "showing N–M of TOTAL; pass --offset M --limit N for more."
-  JSON consumers read \`has_more\` directly off the envelope.
+  \`has_more=true\` and \`--quiet\` is not set. The hint goes to **stderr
+  in every mode** including \`--json\` and piped stdout — it never
+  pollutes machine-readable stdout but is visible to any agent that
+  reads stderr (which they should, for warnings and progress). Format:
+  "showing N–M of TOTAL; pass --offset M --limit N for more."
+  JSON consumers can also read \`has_more\` directly off the envelope.
 - **\`ask results --json\` adds an \`aggregates\` field per round.** For
   rounds with \`wants_pick\`/\`wants_ratings\`, the CLI computes the
   verdict locally so agents don't have to parse comment prose:
@@ -938,25 +1195,43 @@ a structured error object on **stdout** and a human message on
 ## Examples
 
 \`\`\`
-ish workspace list --json | jq '.[].alias'
-ish study get s-b2c --fields alias,name,status,iterations
+# Display (table on TTY, JSON when piped):
+ish workspace list
+
+# Display preserved through tee/pipe (force human):
+ish ask results a-6ec --human | tee /tmp/results.txt
+
+# Capture a single alias to feed into the next command:
+WS=$(ish workspace list --get alias | head -1)
+
+# Inspect a nested field:
+ish study tester t-a17 --get tester_profile.name
+
+# Chain (full JSON for jq when you need multiple fields):
+ish study get s-b2c --fields alias,name,status,iterations --json
 ish ask results a-6ec --round 1 --json
-ish profile generate --description "..." --count 3 --json | jq '.[].alias'
 \`\`\`
 
 ## Composing commands
 
-JSON mode + alias resolution makes pipelines safe:
+\`--get\` removes most of the \`jq\` shims agents reach for. Capture in
+a script, then display the final result back to the user:
 
 \`\`\`
-ITER=$(ish iteration create --url https://example.com --json | jq -r .alias)
-TESTERS=$(ish study run --iteration "$ITER" --sample 5 --country SE \\
-            --json | jq -r '.tester_aliases[]')
+# Capture — bare values, no jq needed:
+ITER=$(ish iteration create --url https://example.com --get alias)
+TESTERS=$(ish study run --iteration "$ITER" --sample 5 --country SE --get tester_aliases)
 for t in $TESTERS; do
   ish study wait "$t" --timeout 600
 done
-ish study results --json | jq .
+
+# Display the final results to the user, even though we're in a script:
+ish study results --human
 \`\`\`
+
+When you genuinely need multiple fields in one parse pass, \`--json\` is
+still the right tool — \`--get\` is for single-value capture, not for
+reshaping output.
 `;
 const GUIDE_FIRST_STUDY = `# guide: your first study, end to end
 
@@ -1098,7 +1373,9 @@ of scope: \`workspace\`, \`config\`, \`docs\`, \`init\`, \`login\`,
 ## Related
 
 - \`reference/aliases\` — the prefix scheme used by every entity.
-- \`reference/json-mode\` — output contracts for piping \`ish status\`.
+- \`reference/json-mode\` — output modes (display vs capture vs chain),
+  including \`--get workspace.alias\` to capture the active workspace
+  without piping \`ish status --json\` through \`jq\`.
 `;
 const REFERENCE_BILLING_LIMITS = `# reference: billing tier limits
 
@@ -1201,7 +1478,7 @@ const PAGES = [
     {
         slug: "concepts/iteration",
         title: "concept: iteration",
-        description: "One configured run of a study (URL or media).",
+        description: "One configured run of a study (URL, media, or chat). Covers segments, segment labels, and HTML content.",
         body: CONCEPT_ITERATION,
     },
     {
@@ -1272,8 +1549,8 @@ const PAGES = [
     },
     {
         slug: "reference/json-mode",
-        title: "reference: JSON output for agents",
-        description: "JSON, --fields, --verbose, exit codes, pipe behaviour.",
+        title: "reference: output modes for agents (display, capture, chain)",
+        description: "Display vs capture vs chain: --human, --get, --json, --fields, exit codes, pipe behavior.",
         body: REFERENCE_JSON_MODE,
     },
     {

package/dist/lib/output.d.ts

@@ -9,6 +9,12 @@
 /** Set by withClient() based on global flags. */
 export declare function setVerbose(v: boolean): void;
 export declare function setFields(fields?: string[]): void;
+/**
+ * Pattern Ω capture mode: when set, jsonOutput() returns the bare value at
+ * the dotted path instead of the full JSON. Cleared between command runs by
+ * each invocation of `applyGlobals()`.
+ */
+export declare function setGetField(field?: string): void;
 /** Per-call output options for stable JSON contracts. */
 export interface OutputOptions {
     /**