@ishlabs/cli 0.26.0 → 0.27.0

package/dist/lib/local-sim/screen-signature.js

@@ -0,0 +1,166 @@
+/**
+ * Native "screen signature" v2 — a SCROLL-INVARIANT structural identity for a
+ * logical native screen, derived from the accessibility tree, sent to the
+ * backend as an entry/cross-run frame anchor (Phase 2 of native frame
+ * continuity; Phase 1 reuses the prior frame on pure scroll/keyboard steps).
+ *
+ * FCIS: this module is PURE (NativeNode[] + coarse inputs in, signature out) —
+ * no device access. The device gathers the coarse inputs (foreground activity /
+ * bundle id) and the parsed tree; this turns them into `{value, usable}`.
+ *
+ * The signature has two parts:
+ *   coarse  — a cheap, almost-always-available anchor (android `package|activity`,
+ *             ios `bundleId|navTitle`).
+ *   tokens  — the persistent CHROME tokens that are NOT scroll content. Each
+ *             chrome node contributes its resource-id (`id:…`) AND its label
+ *             (`tx:…`) when present. This is what makes the signature
+ *             scroll-invariant AND lets two same-activity screens be told apart.
+ *
+ * WHY v2 (two verified gaps in the id-only v1):
+ *  1. LABELS close the shared-chrome OVER-MERGE. A single-Activity app — Jetpack
+ *     Compose (exposes NO resource-ids beyond the framework `android:id/content`)
+ *     or a View app with a fixed toolbar+container shared across fragments —
+ *     gives two DISTINCT screens the SAME id-set → identical signature → SILENT
+ *     over-merge (the cardinal failure). But those screens DO differ in chrome
+ *     LABELS (a home screen vs a settings sub-screen show different toolbar /
+ *     button text). Including labels makes distinct screens produce distinct
+ *     signatures, and makes Compose usable at all (label-only tokens).
+ *  2. STRUCTURAL scroll-exclusion replaces v1's geometric `contains()`. v1
+ *     excluded scroll content by bounds-containment, which (a) mis-flagged an
+ *     overlay/FAB sitting inside a list's rect as content (→ could over-merge),
+ *     and (b) on iOS the scroll CONTAINER is isAccessible=0 and pruned from the
+ *     NativeNode[], so geometric exclusion never fired (scroll changed the
+ *     signature → over-split, feature inert). v2 excludes by TREE STRUCTURE: a
+ *     node is content iff `insideScrollable` (it has a scrollable ANCESTOR),
+ *     computed during parsing — see native-a11y.ts. The scroll container's OWN
+ *     tokens are kept (it's durable chrome; `insideScrollable` is about
+ *     descendants).
+ *
+ * The remaining failure mode after v2 is SAFE: dynamic chrome labels (a live
+ * clock, an unread badge) cause OVER-SPLIT (a new frame), never over-merge — the
+ * backend just mints a fresh frame, which is the conservative direction.
+ *
+ * USABLE GUARD (load-bearing, unchanged in spirit): `usable` is true only with
+ * >= MIN_STABLE_TOKENS tokens. A signature derived from an empty/sparse token
+ * set must NEVER be sent — sha1("") (and any near-empty set) collides across
+ * distinct screens and would silently over-merge them. When unusable the caller
+ * omits the field entirely and the backend falls back to Phase-1 continuity.
+ * This is the SAFE default: Flutter (no a11y tree) and the sparsest screens
+ * degrade here; id-rich Android and label-rich Compose are the validated wins.
+ */
+import { createHash } from "node:crypto";
+/** Minimum stable-chrome tokens for a signature to be usable (sent to the backend). */
+export const MIN_STABLE_TOKENS = 2;
+/**
+ * App-bar / title chrome resource-ids. A node whose resource-id matches carries
+ * the SCREEN TITLE (e.g. a CollapsingToolbar's title, an ActionBar/Toolbar title).
+ * On modern Android the title sits INSIDE the scrollable app-bar (CoordinatorLayout
+ * / NestedScrollView), so structural scroll-exclusion drops it — collapsing every
+ * sub-screen of a single host activity (e.g. Android Settings' `.SubSettings`) to
+ * the SAME generic outer-container ids and silently OVER-MERGING distinct screens
+ * (proven live: Display/Apps/Network all → one frame). We rescue the title LABEL
+ * even when `insideScrollable`: the title text is the screen's most reliable
+ * discriminator and is scroll-INVARIANT (it stays constant as the bar collapses).
+ *
+ * WHY no `_title$` here (removed): a trailing-`_title$` rescue was originally added
+ * to also catch Android `homepage_title`, but (a) `homepage_title` is the VOLATILE
+ * home big-title we deliberately do NOT want to rescue, and (b) `_title$`
+ * OVER-MATCHES iOS list-row section ids that are pure SCROLL CONTENT —
+ * `MOTION_TITLE`, `SPEECH_TITLE`, `LIVE_SPEECH_TITLE`, `VOCAL_SHORTCUTS_TITLE`
+ * (role=text, insideScrollable=true). Rescuing those re-includes scroll-content row
+ * labels in the signature, so scrolling reveals different rows and CHURNS the
+ * signature → over-fragment (iOS Settings/Accessibility split into two frames). The
+ * SubSettings over-merge discriminator rides on the explicitly-matched
+ * `collapsing_toolbar` / `action_bar` / `toolbar`, NOT on an arbitrary `_title$`.
+ */
+const TITLE_CHROME_ID = /(collapsing_toolbar|action_bar|toolbar)$/;
+function isTitleChrome(resourceId) {
+    return resourceId !== "" && TITLE_CHROME_ID.test(resourceId.toLowerCase());
+}
+/** Max length of a label token's value — bounds the hashed string on chatty labels. */
+const LABEL_TOKEN_MAX_LENGTH = 64;
+/**
+ * Normalized role of the iOS navigation bar after `normalizeRole` in
+ * native-a11y.ts (`AXNavigationBar`/`NavigationBar` → "navigationbar"). The
+ * spike matched the raw "NavigationBar" role; the CLI's NativeNode carries the
+ * normalized role, so we match the normalized form here.
+ */
+const IOS_NAV_BAR_ROLE = "navigationbar";
+function sha1(s) {
+    return createHash("sha1").update(s).digest("hex");
+}
+/** First nav-bar node's label (iOS), else "" — best-effort coarse signal. */
+function iosNavTitle(nodes) {
+    const nav = nodes.find((n) => n.role === IOS_NAV_BAR_ROLE);
+    return nav ? nav.label.trim() : "";
+}
+/** The coarse, almost-always-available anchor token. */
+function coarseToken(nodes, coarse) {
+    if (coarse.platform === "android") {
+        return `${coarse.package ?? ""}|${coarse.activity ?? ""}`;
+    }
+    return `${coarse.bundleId ?? ""}|${iosNavTitle(nodes)}`;
+}
+/** Collapse whitespace, lowercase, and cap length so a label token is stable. */
+function normalizeLabelToken(label) {
+    const collapsed = label.replace(/\s+/g, " ").trim().toLowerCase();
+    return collapsed.length <= LABEL_TOKEN_MAX_LENGTH
+        ? collapsed
+        : collapsed.slice(0, LABEL_TOKEN_MAX_LENGTH);
+}
+/**
+ * Sorted, de-duped token set of the persistent CHROME — every node that is NOT
+ * scroll content (`!insideScrollable`). Each such node contributes:
+ *   - `id:<resourceId>`  when its resource-id is non-empty, and
+ *   - `tx:<label>`       when its label is non-empty (normalized).
+ * A scroll CONTAINER's own tokens ARE kept (the container is durable chrome;
+ * `insideScrollable` flags its descendants, not the container). Labels are the
+ * v2 win: they discriminate single-Activity screens that share a chrome id-set
+ * (and give Compose, which exposes no ids, a usable signature at all).
+ */
+function stableTokenSet(nodes) {
+    const out = new Set();
+    for (const n of nodes) {
+        const id = (n.resourceId ?? "").trim();
+        const label = n.label.trim();
+        // App-bar / title chrome carries the screen's name but sits inside the
+        // scrollable app-bar on modern Android — rescue its scroll-invariant LABEL
+        // even when insideScrollable (its generic container id is NOT added; the
+        // label is the discriminator). See TITLE_CHROME_ID.
+        if (label && isTitleChrome(id))
+            out.add(`tx:${normalizeLabelToken(label)}`);
+        if (n.insideScrollable)
+            continue; // scroll content — shifts under a scroll
+        // Suppress the `id:` token for a self-named / generic nav control. On iOS,
+        // parseXcuiHierarchy promotes the WDA `name` to resourceId, but WDA reports a
+        // NON-DETERMINISTIC name for the nav back button — "BackButton" when fresh,
+        // the parent screen's title (e.g. "Settings") once scrolled — while its
+        // visible label stays constant. That churn flips the `id:` token between
+        // scroll states and fragments the same screen. Drop the id when it's the
+        // literal "BackButton" OR is redundant with the node's own label (id ===
+        // normalized label): in both cases the `id:` carries no identity beyond the
+        // already-emitted `tx:` label. We KEEP the `tx:` token below.
+        const redundantNavId = id !== "" &&
+            (id === "BackButton" ||
+                (label !== "" && normalizeLabelToken(id) === normalizeLabelToken(label)));
+        if (id && !redundantNavId)
+            out.add(`id:${id}`);
+        if (label)
+            out.add(`tx:${normalizeLabelToken(label)}`);
+    }
+    return [...out].sort();
+}
+/**
+ * Compute the screen signature from this step's parsed tree + coarse inputs.
+ * `value` is `platform|coarse|sha1(tokens)`; `usable` gates whether it's safe to
+ * send (>= MIN_STABLE_TOKENS distinct stable chrome tokens).
+ */
+export function computeScreenSignature(nodes, coarse) {
+    const tokens = stableTokenSet(nodes);
+    const value = `${coarse.platform}|${coarseToken(nodes, coarse)}|${sha1(tokens.join(","))}`;
+    return {
+        value,
+        usable: tokens.length >= MIN_STABLE_TOKENS,
+        tokenCount: tokens.length,
+    };
+}

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

@@ -53,3 +53,18 @@ export declare function isAppInstalled(udid: string, bundleId: string): Promise<
  * terminate+launch a just-installed app without diffing the app list.
  */
 export declare function bundleIdFromApp(appPath: string): Promise<string | null>;
+/**
+ * Read the installed app's marketing version + build number from the booted
+ * simulator. `simctl listapps` emits a (NeXTSTEP) plist of every installed
+ * bundle; we round-trip it through `plutil -convert json` and index by bundle
+ * id. JSON-not-keypath because a bundle id's dots (`com.apple.Preferences`)
+ * collide with plutil's `-extract` keypath separator.
+ *
+ * Best-effort: returns null on any failure (the run never depends on it). Works
+ * for both CLI-installed `.app`s and pre-installed system/app-store bundles —
+ * by call time the bundle id is already resolved.
+ */
+export declare function appBuildFromSimulator(udid: string, bundleId: string): Promise<{
+    version: string | null;
+    build: string | null;
+} | null>;

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

@@ -16,7 +16,7 @@
  */
 import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
-import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
@@ -142,3 +142,43 @@ export async function bundleIdFromApp(appPath) {
         return null;
     }
 }
+/**
+ * Read the installed app's marketing version + build number from the booted
+ * simulator. `simctl listapps` emits a (NeXTSTEP) plist of every installed
+ * bundle; we round-trip it through `plutil -convert json` and index by bundle
+ * id. JSON-not-keypath because a bundle id's dots (`com.apple.Preferences`)
+ * collide with plutil's `-extract` keypath separator.
+ *
+ * Best-effort: returns null on any failure (the run never depends on it). Works
+ * for both CLI-installed `.app`s and pre-installed system/app-store bundles —
+ * by call time the bundle id is already resolved.
+ */
+export async function appBuildFromSimulator(udid, bundleId) {
+    const dir = await mkdtemp(join(tmpdir(), "ish-ios-apps-"));
+    const path = join(dir, "apps.plist");
+    try {
+        const { stdout } = await execFileAsync(XCRUN, ["simctl", "listapps", udid], {
+            timeout: 60_000,
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        await writeFile(path, stdout);
+        const { stdout: json } = await execFileAsync(PLUTIL, ["-convert", "json", "-o", "-", path], {
+            timeout: 10_000,
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        const apps = JSON.parse(json);
+        const app = apps[bundleId];
+        if (!app)
+            return null;
+        return {
+            version: app.CFBundleShortVersionString ?? null,
+            build: app.CFBundleVersion ?? null,
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true }).catch(() => { });
+    }
+}

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

@@ -12,10 +12,12 @@ export interface LocalSimInitRequest {
     iteration_id: string;
 }
 export interface IterationDetails {
-    url: string;
+    url?: string;
     platform: string;
     screen_format: "desktop" | "mobile_portrait";
     locale?: string;
+    /** Native (ios/android): the app target to install/launch (bundle id / package / path). */
+    app_artifact?: string;
 }
 export interface LocalSimInitResponse {
     participant_id: string;
@@ -221,6 +223,14 @@ export interface RecordInteraction {
     assignment_status: AssignmentStatus;
     tabs?: LocalTabInfo[];
 }
+export interface LocalSimInteractionRequest {
+    participant_id: string;
+    product_id: string;
+    interaction: RecordInteraction;
+}
+export interface LocalSimInteractionResponse {
+    interaction_id: string;
+}
 export interface AssignmentStatusUpdate {
     assignment_id: string;
     status: string;
@@ -229,7 +239,6 @@ export interface AssignmentStatusUpdate {
 export interface LocalSimRecordRequest {
     participant_id: string;
     product_id: string;
-    interactions: RecordInteraction[];
     final_status: string;
     assignment_statuses: AssignmentStatusUpdate[];
 }

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

@@ -45,6 +45,13 @@ export declare function closeWda(udid: string): Promise<void>;
 export declare function describeScreen(udid: string): Promise<IosScreen>;
 /** Raw WDA `/source?format=json` string — feed to `parseXcuiHierarchy`. */
 export declare function describeAll(udid: string): Promise<string>;
+/**
+ * The foreground app's bundle id via WDA `GET /wda/activeAppInfo`, a coarse
+ * input for the screen signature. Best-effort: returns "" on any failure (the
+ * signature degrades to a bundleId-less coarse token, and the run never depends
+ * on this read).
+ */
+export declare function activeBundleId(udid: string): Promise<string>;
 export declare function uiTap(udid: string, x: number, y: number): Promise<void>;
 export declare function uiLongPress(udid: string, x: number, y: number, durationMs?: number): Promise<void>;
 export declare function uiSwipe(udid: string, x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;

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

@@ -250,6 +250,22 @@ export async function describeAll(udid) {
     const json = await wdaCall(s.port, "GET", `/session/${s.sessionId}/source?format=json`);
     return JSON.stringify(json);
 }
+/**
+ * The foreground app's bundle id via WDA `GET /wda/activeAppInfo`, a coarse
+ * input for the screen signature. Best-effort: returns "" on any failure (the
+ * signature degrades to a bundleId-less coarse token, and the run never depends
+ * on this read).
+ */
+export async function activeBundleId(udid) {
+    try {
+        const s = await getSession(udid);
+        const v = unwrap(await wdaCall(s.port, "GET", "/wda/activeAppInfo"));
+        return typeof v.bundleId === "string" ? v.bundleId : "";
+    }
+    catch {
+        return "";
+    }
+}
 // ── Gestures (W3C pointer actions; coordinates in POINTS) ────────────────────
 function pointerAction(steps) {
     return {

package/dist/lib/modality.js

@@ -97,8 +97,13 @@ export function iterationHasContent(details, modality) {
         const ep = readExternalChatbotEndpoint(details);
         return !!ep.endpoint || !!ep.chatbot_endpoint_id;
     }
-    // interactive (default)
-    return typeof d.url === "string" && d.url.length > 0;
+    // interactive (default): browser/figma iterations carry a `url`; native
+    // (ios/android) iterations carry an `app_artifact` instead and need no URL
+    // (the backend made url optional for native — ish-backend 9708e06e). Either
+    // satisfies "has content".
+    const hasUrl = typeof d.url === "string" && d.url.length > 0;
+    const hasApp = typeof d.app_artifact === "string" && d.app_artifact.length > 0;
+    return hasUrl || hasApp;
 }
 /** The flag fragment a user should pass to populate content for a given modality. */
 export function describeRequiredContentFlag(modality, chatMode) {

package/dist/lib/paths.d.ts

@@ -20,4 +20,10 @@ export declare function cloudflaredBin(): string;
 export declare function wdaDir(): string;
 /** Stamp file recording which CLI/runner version the cached WDA bundle is for. */
 export declare function wdaVersionFile(): string;
+/**
+ * Path to `adb` inside Google's standalone Android platform-tools, when we've
+ * fetched it into `binDir()` on demand (the zip unpacks a `platform-tools/`
+ * dir). Mirrors `cloudflaredBin()` / `wdaDir()`.
+ */
+export declare function adbBin(): string;
 export declare function connectLockPath(): string;

package/dist/lib/paths.js

@@ -46,6 +46,15 @@ export function wdaDir() {
 export function wdaVersionFile() {
     return path.join(wdaDir(), "VERSION");
 }
+/**
+ * Path to `adb` inside Google's standalone Android platform-tools, when we've
+ * fetched it into `binDir()` on demand (the zip unpacks a `platform-tools/`
+ * dir). Mirrors `cloudflaredBin()` / `wdaDir()`.
+ */
+export function adbBin() {
+    const exe = process.platform === "win32" ? "adb.exe" : "adb";
+    return path.join(binDir(), "platform-tools", exe);
+}
 export function connectLockPath() {
     return path.join(rootDir(), "connect.lock");
 }

package/dist/lib/report-readiness.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Best-effort readiness reporting to the ish backend.
+ *
+ * After the CLI computes its native-simulation readiness checks (the same
+ * array `ish check <platform> --json` emits), we POST them to
+ * `${apiUrl}/api/v1/connect/device` so the ish web app can render a live
+ * native-readiness panel. This is the native analog of how `ish connect
+ * <port>` registers a cloudflare tunnel: a side-channel that tells the
+ * backend "this developer's machine is (or isn't) ready to drive a native
+ * iOS/Android simulation right now."
+ *
+ * Contract (must match the backend exactly):
+ *
+ *   POST /api/v1/connect/device
+ *   {
+ *     "platform":    "ios" | "android",
+ *     "checks":      [ {key,name,group,status,message?,fix?}, ... ],
+ *     "overall":     "pass" | "warn" | "fail" | "skip",
+ *     "cli_version": "<package.json version>"
+ *   }
+ *
+ * This is COMPLETELY best-effort. It never throws, never blocks the command,
+ * never writes to stdout, and silently returns when the user isn't logged in
+ * or is offline. The CLI's normal output and exit code are unaffected. The
+ * only side-channel is an optional stderr line under a `debug` flag, mirroring
+ * how connect.ts logs its own warnings.
+ */
+import type { GlobalOpts } from "./command-helpers.js";
+import type { Check, CheckStatus } from "../commands/doctor.js";
+/**
+ * POST the platform-scoped readiness checks to the backend. Best-effort:
+ * resolves auth + posts inside a single try/catch, swallowing every error.
+ *
+ * @param platform  The native platform the checks were scoped to.
+ * @param checks    The exact `runChecks()` array (already scoped to `platform`).
+ * @param overall   The aggregate status (`overall(checks)`).
+ * @param globals   Resolved CLI globals — used only for `--api-url` / `--dev`
+ *                  / `--token` resolution. Pass the command's `globals`.
+ * @param opts.debug  When true, log a one-line failure note to stderr (off by
+ *                    default so the post is silent). Mirrors connect.ts.
+ */
+export declare function reportReadiness(platform: "ios" | "android", checks: Check[], overall: CheckStatus, globals: Pick<GlobalOpts, "apiUrl" | "dev" | "token" | "tokenFile">, opts?: {
+    debug?: boolean;
+}): Promise<void>;

package/dist/lib/report-readiness.js

@@ -0,0 +1,74 @@
+/**
+ * Best-effort readiness reporting to the ish backend.
+ *
+ * After the CLI computes its native-simulation readiness checks (the same
+ * array `ish check <platform> --json` emits), we POST them to
+ * `${apiUrl}/api/v1/connect/device` so the ish web app can render a live
+ * native-readiness panel. This is the native analog of how `ish connect
+ * <port>` registers a cloudflare tunnel: a side-channel that tells the
+ * backend "this developer's machine is (or isn't) ready to drive a native
+ * iOS/Android simulation right now."
+ *
+ * Contract (must match the backend exactly):
+ *
+ *   POST /api/v1/connect/device
+ *   {
+ *     "platform":    "ios" | "android",
+ *     "checks":      [ {key,name,group,status,message?,fix?}, ... ],
+ *     "overall":     "pass" | "warn" | "fail" | "skip",
+ *     "cli_version": "<package.json version>"
+ *   }
+ *
+ * This is COMPLETELY best-effort. It never throws, never blocks the command,
+ * never writes to stdout, and silently returns when the user isn't logged in
+ * or is offline. The CLI's normal output and exit code are unaffected. The
+ * only side-channel is an optional stderr line under a `debug` flag, mirroring
+ * how connect.ts logs its own warnings.
+ */
+import { resolveApiUrl, resolveToken } from "./auth.js";
+import { ApiClient } from "./api-client.js";
+import pkg from "../../package.json" with { type: "json" };
+/** Backend endpoint (relative to the `/api/v1` base ApiClient prepends). */
+const DEVICE_ENDPOINT = "/connect/device";
+/**
+ * POST the platform-scoped readiness checks to the backend. Best-effort:
+ * resolves auth + posts inside a single try/catch, swallowing every error.
+ *
+ * @param platform  The native platform the checks were scoped to.
+ * @param checks    The exact `runChecks()` array (already scoped to `platform`).
+ * @param overall   The aggregate status (`overall(checks)`).
+ * @param globals   Resolved CLI globals — used only for `--api-url` / `--dev`
+ *                  / `--token` resolution. Pass the command's `globals`.
+ * @param opts.debug  When true, log a one-line failure note to stderr (off by
+ *                    default so the post is silent). Mirrors connect.ts.
+ */
+export async function reportReadiness(platform, checks, overall, globals, opts = {}) {
+    try {
+        const apiUrl = resolveApiUrl(globals.apiUrl, globals.dev);
+        // resolveToken throws when the user isn't logged in (or a network blip
+        // prevents an expired-token refresh) — that throw is caught below and we
+        // silently return, exactly as required for the offline / logged-out case.
+        const token = await resolveToken(globals.token, apiUrl, globals.tokenFile);
+        const client = new ApiClient({ apiUrl, token });
+        await client.post(DEVICE_ENDPOINT, {
+            platform,
+            checks,
+            overall,
+            cli_version: pkg.version,
+        }, 
+        // Tight timeout: `ish check` awaits this so the beacon lands before the
+        // process exits, but the panel POST must never stall the command. 2.5s
+        // is plenty on a healthy backend and bounds the worst case if the host
+        // is unreachable or hung.
+        { timeout: 2_500 });
+    }
+    catch (err) {
+        // Swallow everything. A logged-out user, an offline machine, an old
+        // backend without the endpoint, a 5xx — none of it should ever surface
+        // to the user or change the command's behavior.
+        if (opts.debug) {
+            const reason = err instanceof Error ? err.message : String(err);
+            console.error(`(readiness report skipped: ${reason})`);
+        }
+    }
+}

package/dist/lib/skill-content.js

@@ -230,6 +230,8 @@ To hand a study to someone **without an ish account** — a prospect, a stakehol
 - **\`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.
+- **Native app iterations (ios/android) name the app, not a URL**: \`ish iteration create --platform ios --app <bundle-id>\` stores the target as \`app_artifact\` (no URL). The iteration remembers it, so \`ish study run --local\` needs **no \`--app\` on reruns** (it defaults from the iteration). Pass \`--app <path-to.app|.apk>\` only to override with a fresh local build. \`--app\` is optional at create time (omit it for "chosen at run time"). Only \`browser\`/\`figma\` iterations require \`--url\`.
+- **Local runs have no server-side screenshots**: \`ish study run --local\` (including ios/android) writes a per-step HTML debug report to \`~/.ish/debug/sim-*.html\` (path printed at the end of the run) instead of pushing screenshots to the server. \`ish study screenshots list\` on a local-only study finds none — open the debug report instead.
 
 ## When in doubt
 

package/package.json

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