@ishlabs/cli 0.23.0 → 0.24.0

package/dist/lib/segmentation.js

@@ -0,0 +1,105 @@
+/**
+ * Validation + nudge for media/text `segmentation` (the parsed value of
+ * `--segmentation-json` on `study create` / `iteration create`).
+ *
+ * THE PRINCIPLE these guard: **segments are semantic sections, not
+ * paragraphs.** Group related paragraphs into a few coherent sections
+ * (intro → argument → conclusion). A long article is usually 3–6 sections,
+ * not one per paragraph; `paragraph_start`/`paragraph_end` only mark where a
+ * section begins and ends — the unit is the *section*.
+ *
+ * - `validateSegmentation` is FATAL (throws ValidationError → exit 2) on a
+ *   malformed `section_based` shape — most importantly a missing/empty label,
+ *   which the backend would otherwise reject after a network round-trip.
+ * - `warnIfOverSegmented` is NON-FATAL: an agent that ignores the docs and
+ *   emits one section per paragraph gets a stderr nudge, but is never blocked
+ *   (over-segmenting can be intentional).
+ *
+ * Both take the already-JSON-parsed object; `undefined` is a no-op.
+ */
+import { writeSync } from "node:fs";
+import { c } from "./colors.js";
+import { ValidationError } from "./output.js";
+/** Throw on a malformed segmentation shape. No-op for undefined / unknown types. */
+export function validateSegmentation(seg) {
+    if (!seg || typeof seg !== "object")
+        return;
+    const s = seg;
+    if (s.type === "section_based") {
+        const sections = s.sections;
+        if (!Array.isArray(sections) || sections.length === 0) {
+            throw new ValidationError("section_based segmentation needs a non-empty `sections` array.", [], "Group related paragraphs into a few semantic sections (intro, argument, conclusion) — not one per paragraph.");
+        }
+        sections.forEach((raw, i) => {
+            const sec = (raw ?? {});
+            const name = typeof sec.name === "string" ? sec.name.trim() : "";
+            const label = typeof sec.label === "string" ? sec.label.trim() : "";
+            if (!name) {
+                throw new ValidationError(`section_based sections[${i}] is missing a non-empty \`name\`.`, []);
+            }
+            if (!label) {
+                throw new ValidationError(`section_based sections[${i}] ("${name}") is missing a non-empty \`label\`. ` +
+                    "Every section needs a human-readable label — it surfaces in the participant UI and in results.", []);
+            }
+            // Paragraph-bounded sections: validate the range when present. (A
+            // marker-bounded section_based variant may omit these — don't require.)
+            const start = sec.paragraph_start;
+            const end = sec.paragraph_end;
+            if (start !== undefined || end !== undefined) {
+                if (typeof start !== "number" || typeof end !== "number" || start < 0 || end <= start) {
+                    throw new ValidationError(`section_based sections[${i}] ("${name}") has an invalid paragraph range ` +
+                        `(paragraph_start=${String(start)}, paragraph_end=${String(end)}). ` +
+                        "Need paragraph_start >= 0 and paragraph_end > paragraph_start.", []);
+                }
+            }
+        });
+        return;
+    }
+    if (s.type === "time_based") {
+        const iv = s.intervals_seconds;
+        if (Array.isArray(iv)) {
+            for (let i = 1; i < iv.length; i++) {
+                const prev = iv[i - 1];
+                const cur = iv[i];
+                if (typeof prev !== "number" || typeof cur !== "number" || cur <= prev) {
+                    throw new ValidationError(`time_based intervals_seconds must be strictly ascending numbers ` +
+                        `(problem at index ${i}: ${String(prev)} → ${String(cur)}).`, []);
+                }
+            }
+        }
+    }
+}
+/**
+ * Non-fatal nudge toward semantic sections. Conservative on purpose: only
+ * fires for `section_based` with >= 5 sections that EACH span a single
+ * paragraph — the signature of one-section-per-paragraph — so a genuine
+ * 3-section piece never trips it. stderr only (keeps --json stdout clean);
+ * suppressed under --quiet.
+ */
+export function warnIfOverSegmented(seg, opts = {}) {
+    if (opts.quiet)
+        return;
+    if (!seg || typeof seg !== "object")
+        return;
+    const s = seg;
+    if (s.type !== "section_based" || !Array.isArray(s.sections))
+        return;
+    const sections = s.sections;
+    if (sections.length < 5)
+        return;
+    const allSingleParagraph = sections.every((sec) => {
+        const start = sec?.paragraph_start;
+        const end = sec?.paragraph_end;
+        return typeof start === "number" && typeof end === "number" && end - start <= 1;
+    });
+    if (!allSingleParagraph)
+        return;
+    // Synchronous fd-2 write, not console.error: this fires moments before the
+    // command's own output + a process.exit (via exitWithFlush), which truncates
+    // async-buffered stderr writes to a pipe/file. writeSync guarantees the nudge
+    // lands.
+    writeSync(2, `${c.yellow}⚠ ${sections.length} single-paragraph sections.${c.reset} ` +
+        "Segments are meant to be semantic sections — group related paragraphs into a few " +
+        "coherent sections (e.g. intro → argument → conclusion), not one per paragraph. " +
+        "A long article is usually 3–6 sections. Proceeding as-is.\n");
+}

package/dist/lib/skill-content.js

@@ -207,6 +207,10 @@ The most common multi-turn question: "user wants to change X — re-use the exis
 
 When in doubt: side-by-side comparison usually beats in-place edits. Ids are cheap; result history isn't.
 
+## Sharing results (no-login link)
+
+To hand a study to someone **without an ish account** — a prospect, a stakeholder — create a public share link. \`ish study share [study]\` prints a no-login \`share_url\` to the web viewer (summary, key insights, participant journeys, interactive frames, segment breakdowns). \`ish study share --list\` lists your links; \`ish study unshare <token>\` revokes one (takes the **raw token**, not a study id/alias). \`--expires <days>\` auto-expires the link. Brand the link by setting a workspace logo first: \`ish workspace update <id> --logo <url>\` — the logo shows on the shared page. Share **after** the study has run + been analyzed, so the viewer renders the summary + insights. Deep dive: \`ish docs get-page concepts/sharing\`. (CLI-only — the MCP has no share tool yet.)
+
 ## Pitfalls
 
 - **Cold start on free plan**: \`workspace_create\` returns \`usage_limit_reached\` at the free-plan cap (1 workspace). Always inspect with \`workspace_list\` first. **MCP-only recipe** (no \`--ensure\` available): \`workspace_list\` → if non-empty, use the first; if empty, \`workspace_create\`; if \`workspace_create\` returns \`usage_limit_reached\`, re-call \`workspace_list\` (a workspace exists you didn't see — possibly created by another session). **CLI shortcut**: \`ish workspace create --name <name> --ensure\` is idempotent by name.
@@ -222,9 +226,10 @@ When in doubt: side-by-side comparison usually beats in-place edits. Ids are che
 - **No per-page/per-timestamp scoping for media**: there's no "evaluate just slide 14" or "react to seconds 0-30" API. State the focus explicitly in the \`assignment\` text, or pre-stitch the artifact (e.g. replace one slide locally, upload as a new iteration).
 - **\`study get --json\` participants live at the top level**, not nested under \`iterations[*].participants\`. The backend split made \`/studies/{id}\` lite (metadata + iteration shells, no participant graph) and added \`/studies/{id}/participants\`; the CLI joins them so \`study get --json\` carries a flat \`participants[]\` with \`iteration_id\` on each row. Read \`.participants[]\`, not \`.iterations[].participants[]\`.
 - **All destructive deletes require \`--yes\` in non-TTY mode**: \`ish workspace delete\`, \`study delete\`, \`ask delete\`, \`person delete\`, \`source delete\`, \`chat endpoint delete\`. In \`--json\` mode (or any piped/non-TTY invocation), omitting \`--yes\` refuses with \`error_kind: "ConfirmationRequired"\` + an \`example\` field showing the same command with \`--yes\` appended. \`workspace delete\` is the highest-blast-radius: it removes ALL nested studies, asks, people, secrets, configs, sources, and chat endpoints — the prompt names them explicitly.
-- **\`ish login\` is idempotent**: with a valid saved token, \`ish login\` short-circuits with "Already logged in" and **does not open a new browser tab**. Use \`--force\` (or \`-f\`) only when actually switching accounts.
+- **\`ish login\` is idempotent**: with a saved token that is unexpired *and* still accepted by the API, \`ish login\` short-circuits with "Already logged in" and **does not open a new browser tab**. If the token is unexpired but the server rejects it (revoked, rotated signing key, or minted against the wrong env — e.g. a dev-Supabase token while calling the prod api), it re-runs the browser flow instead of falsely reporting success. Use \`--force\` (or \`-f\`) only when actually switching accounts.
 - **\`ish person create\` accepts inline flags** (mirrors \`person update\`): the file-only API (\`--file <path>\`) is preserved as an escape hatch but the common path is \`ish person create --name "X" --type ai --country US ...\` — \`--type\` defaults to \`ai\` when \`--file\` is omitted. See \`ish person create --help\` for the full inline-flag set including \`--household\` (MECE rule applies) and \`--accessibility-profile\`.
 - **\`ish status\` now surfaces \`chat_endpoint\`** alongside \`workspace\`/\`study\`/\`ask\`. Stale or orphan active refs get a \`warning\` + \`hint\` field on the affected ref (instead of silently dropping the \`name\`). On \`workspace use <other>\`, the CLI cascade-clears \`study\`/\`ask\`/\`chat_endpoint\` (they belong to the previous workspace).
+- **Share link URL host ≠ API host**: \`ish study share\` prints the backend-built \`share_url\` (the web frontend host). Use it verbatim — never reconstruct the URL from the API host or app URL; they differ. \`ish study unshare\` takes the **raw token** (from \`study share\` / \`study share --list\`), not a study id or alias.
 
 ## When in doubt
 
@@ -259,14 +264,22 @@ ish person generate \\
 # 4. Define the study + iteration A in one call (one-shot path).
 #    The same shape works for image (--image-urls), video / audio /
 #    document (--content-url <url>), and chat (--endpoint <id>).
+#    For text/media you can also pass --segmentation-json (+ email-styling
+#    --content-html/--sender-name/--sender-email/--featured-image-url) here,
+#    so a single SEGMENTED iteration is one call — no separate iteration
+#    create (which would leave an empty A + a redundant B).
+#    Segments are SEMANTIC sections, not paragraphs: group related paragraphs
+#    into a few coherent sections (a long article is usually 3-6 sections, not
+#    one per paragraph). The CLI errors on a missing label and warns on
+#    one-section-per-paragraph.
 ish study create --name "Onboarding UX" --modality interactive \\
     --url https://example.com --screen-format desktop \\
     --assignment "Sign up:Complete the signup flow" \\
     --question "How easy was it?"
 ish study use s-…
 
-# (Optional) add a B variant later instead of inline:
-# ish iteration create --url https://example.com/v2
+# (Optional) add a SECOND iteration only when you actually want to A/B:
+# ish iteration create --url https://example.com/v2   # auto-named "B" (next letter), not "CLI <date>"
 
 # 6. Run, blocking until done
 ish study run --all --wait
@@ -302,6 +315,59 @@ ish study get s-…                       # human: "✓ Add to cart 4/5 (80%)" p
 ish study get s-… --json --verbose      # step_completion[] incl. sample_failures[].participant_id
 \`\`\`
 
+### Rich question types (slider, likert, choice, number)
+
+\`--question\` makes simple text questions only. For \`slider\`, \`likert\`,
+\`single-choice\`, \`multiple-choice\`, \`number\`, or \`timing: "before"\`, use
+\`--questionnaire\` — which takes **inline JSON, an @file, or a path** (no temp
+file required). \`--question\` and \`--questionnaire\` are mutually exclusive.
+
+\`\`\`bash
+ish study create --name "Pricing page" --modality interactive --url https://example.com \\
+    --assignment "React:Look around as you normally would" \\
+    --questionnaire '[
+      {"question":"What do you think this does?","type":"text","timing":"after"},
+      {"question":"How easy was it to understand?","type":"slider","min":0,"max":10},
+      {"question":"How strongly do you agree it is for you?","type":"likert",
+       "labels":["Strongly disagree","Disagree","Neutral","Agree","Strongly agree"]},
+      {"question":"Which fits best?","type":"single-choice","options":["A","B","C"]},
+      {"question":"How many seats would you need?","type":"number"}
+    ]'
+# @file and path forms also work: --questionnaire @/tmp/q.json | ./q.json
+\`\`\`
+
+\`slider\` takes \`min\`/\`max\`(/\`step\`); \`likert\` takes \`labels\`;
+\`single-choice\`/\`multiple-choice\` take \`options\`. The CLI tolerates
+underscored type spellings (\`single_choice\`); the backend validates the shape.
+Same input forms on \`ish ask … --questions\`. See \`ish docs get-page concepts/questionnaire\`.
+
+### 1b. Share the results with someone (no-login link)
+
+Goal: hand the finished study to a prospect or stakeholder who has no ish
+account. Run + analyze first so the public viewer renders the summary.
+
+\`\`\`bash
+# (optional) brand the workspace — the logo shows on the shared page
+ish workspace update w-… --logo https://logo.clearbit.com/acme.com
+
+# generate the AI summary + key insights (needs ≥5 completed participants)
+ish study analyze s-… --wait
+
+# create the public, no-login link — the printed share_url is the deliverable
+ish study share s-…
+# → https://<frontend>/share/study/Hk9_…   (paste into an email)
+
+ish study share s-… --expires 30        # auto-expire in 30 days
+ish study share s-… --json              # { token, share_url, expires_at, created_at, id }
+
+# manage links
+ish study share --list                  # all your links: token, study, expires, revoked
+ish study unshare Hk9_… --yes           # revoke by RAW TOKEN — URL stops working
+\`\`\`
+
+The \`share_url\` host is the web frontend (built server-side) — use it
+verbatim; don't reconstruct it. Deep dive: \`ish docs get-page concepts/sharing\`.
+
 ## 2. Quick A/B ask with image variants
 
 Goal: ship 30 simulated reactions to two hero images, with a "which do
@@ -585,7 +651,7 @@ also in \`study poll --json\`. Branch on it instead of treating
 \`interaction_count: 0\` as a generic failure.
 
 Pre-flight tip: \`ish workspace info\` exposes
-\`{studies_used, studies_max, participants_used, participants_max, tier}\` so
+\`{studies_used, studies_max, people_used, people_max, concurrent_participants_max, workspace_members_max, tier}\` so
 you can branch on plan caps before \`study create\` returns
 \`error_code: usage_limit_reached\`.
 
@@ -1035,6 +1101,12 @@ table, projection shapes, and the defensive null-handling rules.
 - For \`ask\` write-paths (update/archive/wait/add-questions/add-people),
   default JSON is compact (changed fields + alias). Pass \`--verbose\` for
   the full Ask payload.
+- The \`ish study create\`/\`update --json\` echo always shows
+  \`assignments\` and \`interview_questions\` — \`[]\` when the study has
+  none, never dropped. Trust it: an empty \`assignments\` means you
+  genuinely created a study with no assignment (add one before
+  \`study run\`, or it fails with "Study has no assignments"); you don't
+  need a follow-up \`study get --verbose\` to tell "none" from "stripped".
 - \`person generate --json\` returns \`{job: {id, status, person_ids},
   profiles: [...]}\`; each person is the lean person shape with its
   evidence-grounded \`scenarios\` attached (\`--no-scenarios\` to omit,
@@ -1127,7 +1199,7 @@ ish <command> --help
 | \`mcp\`       | Wire the hosted ish MCP server into local AI    | guides/mcp-add              |
 |             | clients (Cursor, VS Code, Claude Code,          |                             |
 |             | Claude Desktop, Windsurf). Idempotent.          |                             |
-| \`login\`     | Browser-based auth. Idempotent: short-circuits on valid saved token. \`--force\` to switch accounts. | —                           |
+| \`login\`     | Browser-based auth. Idempotent: short-circuits only when the saved token is unexpired AND server-accepted. \`--force\` to switch accounts. | —                           |
 | \`logout\`    | Clear saved credentials                         | —                           |
 | \`status\`    | Show active session (user, workspace,           | concepts/active-context     |
 |             | study, ask, token validity) — alias \`whoami\`    |                             |

package/dist/lib/types.d.ts

@@ -22,6 +22,8 @@ export interface ProductUpdateInput {
     description?: string;
     color?: string;
     base_url?: string;
+    /** External logo image URL — backend sets `logo.path` directly (feeds product_logo_url on shared study links). */
+    logo_url?: string;
 }
 export type SecretScope = "agent" | "project";
 export type SecretVariableType = "secret" | "variable";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ishlabs/cli",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "The command-line interface for ish",
   "type": "module",
   "bin": {
@@ -45,9 +45,11 @@
     "@sentry/bun": "^10.13.0",
     "@sentry/node": "^10.13.0",
     "commander": "^13.0.0",
+    "http-proxy": "^1.18.1",
     "playwright-core": "^1.58.2"
   },
   "devDependencies": {
+    "@types/http-proxy": "^1.17.17",
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0"
   }