@notis_ai/cli 0.2.12 → 0.2.14

package/dist/scaffolds/notis-random/packages/sdk/src/hooks/useDatabaseSubscription.ts

@@ -0,0 +1,76 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import { useDocuments, type UseDocumentsOptions, type UseDocumentsResult } from './useDocuments';
+import type { DocumentRecord } from '../runtime';
+
+export interface UseDatabaseSubscriptionOptions extends UseDocumentsOptions {
+  /** Set to false to keep the query but skip the change feed. */
+  subscribe?: boolean;
+}
+
+export interface UseDatabaseSubscriptionResult extends UseDocumentsResult {
+  /** Alias of `documents`, for views that think in rows. */
+  rows: DocumentRecord[];
+  /** True while a live change feed is attached to this database. */
+  live: boolean;
+}
+
+/**
+ * Query a Notis database and keep it fresh without polling.
+ *
+ * ```tsx
+ * const { rows, live, refetch } = useDatabaseSubscription('workspaces');
+ * ```
+ *
+ * A change on the database wakes the hook, which then refetches through the
+ * usual `LOCAL_NOTIS_DATABASE_QUERY` path — the change feed is a signal only
+ * and never carries row data. Hosts without a change feed (the dev harness,
+ * the screenshot stub, the vite preview) still return rows; `live` is false
+ * there and the app should keep offering its manual refresh.
+ */
+export function useDatabaseSubscription(
+  databaseSlug: string,
+  options: UseDatabaseSubscriptionOptions = {},
+): UseDatabaseSubscriptionResult {
+  const runtime = useNotisRuntime();
+  const { subscribe = true, ...documentOptions } = options;
+  const { documents, loading, error, refetch } = useDocuments(databaseSlug, documentOptions);
+  const [live, setLive] = useState(false);
+
+  const refetchRef = useRef(refetch);
+  useEffect(() => {
+    refetchRef.current = refetch;
+  }, [refetch]);
+
+  const enabled = options.enabled !== false && subscribe;
+
+  useEffect(() => {
+    if (!runtime?.subscribeDatabase || !enabled || !databaseSlug) {
+      setLive(false);
+      return;
+    }
+
+    let cancelled = false;
+    const unsubscribe = runtime.subscribeDatabase(
+      databaseSlug,
+      () => {
+        refetchRef.current();
+      },
+      {
+        onStatusChange: (isLive) => {
+          if (!cancelled) setLive(isLive);
+        },
+      },
+    );
+
+    return () => {
+      cancelled = true;
+      setLive(false);
+      unsubscribe?.();
+    };
+  }, [runtime, databaseSlug, enabled]);
+
+  return { documents, rows: documents, loading, error, refetch, live };
+}

package/dist/scaffolds/notis-random/packages/sdk/src/hooks/useHandover.ts

@@ -0,0 +1,75 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import { useNotisRuntime } from '../provider';
+import type { HandoverPayload, HandoverResult } from '../runtime';
+
+export interface UseHandoverResult {
+  /** Hand the work over. Rejects when the host has no manager chat. */
+  handover: (payload: HandoverPayload) => Promise<HandoverResult>;
+  /** True while the manager chat is being prepared. */
+  pending: boolean;
+  error: Error | null;
+  /**
+   * False when the host cannot hand work over (dev harness, vite preview).
+   * Render the app's own fallback — a copyable prompt, say — when it is false.
+   */
+  available: boolean;
+}
+
+/**
+ * Hand a piece of work from app code to the Notis manager chat.
+ *
+ * An app displays work; the manager runs it. `handover` puts the message in
+ * the chat surface that already owns streaming progress, billing, cancellation
+ * and the transcript, and the app watches its own databases for the result.
+ *
+ * ```tsx
+ * const { handover, pending, available } = useHandover();
+ *
+ * return available ? (
+ *   <Button
+ *     disabled={pending}
+ *     onClick={() => { void handover({ prompt: 'Create a workspace on notis to ...' }); }}
+ *   >
+ *     Send to Notis
+ *   </Button>
+ * ) : (
+ *   <CopyablePrompt prompt="Create a workspace on notis to ..." />
+ * );
+ * ```
+ *
+ * Pass `skill` to bind the work to a skill declared in `notis.config.ts`; the
+ * host rejects a key the app does not declare. `autoSend` is accepted for
+ * forward compatibility; today's hosts always return `drafted` and let the
+ * user press send.
+ */
+export function useHandover(): UseHandoverResult {
+  const runtime = useNotisRuntime();
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const handover = useCallback(
+    async (payload: HandoverPayload): Promise<HandoverResult> => {
+      if (!runtime?.handover) {
+        throw new Error('This Notis host cannot hand work to the manager chat.');
+      }
+
+      setPending(true);
+      setError(null);
+
+      try {
+        return await runtime.handover(payload);
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        throw e;
+      } finally {
+        setPending(false);
+      }
+    },
+    [runtime],
+  );
+
+  return { handover, pending, error, available: Boolean(runtime?.handover) };
+}

package/dist/scaffolds/notis-random/packages/sdk/src/index.ts

@@ -13,6 +13,11 @@ export { NotisProvider, useNotisRuntime } from './provider';
 export { useNotis } from './hooks/useNotis';
 export { useDocuments } from './hooks/useDocuments';
 export type { UseDocumentsOptions, UseDocumentsResult } from './hooks/useDocuments';
+export { useDatabaseSubscription } from './hooks/useDatabaseSubscription';
+export type {
+  UseDatabaseSubscriptionOptions,
+  UseDatabaseSubscriptionResult,
+} from './hooks/useDatabaseSubscription';
 export { useDocument } from './hooks/useDocument';
 export type { UseDocumentOptions, UseDocumentResult } from './hooks/useDocument';
 export { useUpsertDocument } from './hooks/useUpsertDocument';
@@ -22,6 +27,10 @@ export type { UseDatabaseSchemaResult } from './hooks/useDatabaseSchema';
 export { useTool } from './hooks/useTool';
 export type { ToolCallState, UseToolResult } from './hooks/useTool';
 export { useTools } from './hooks/useTools';
+export { useHandover } from './hooks/useHandover';
+export type { UseHandoverResult } from './hooks/useHandover';
+export { useCloudComputer } from './hooks/useCloudComputer';
+export type { UseCloudComputerResult } from './hooks/useCloudComputer';
 export { useNotisNavigation } from './hooks/useNotisNavigation';
 export { useTopBarSearch } from './hooks/useTopBarSearch';
 export { useBackend } from './hooks/useBackend';
@@ -37,6 +46,7 @@ export {
   extractRichText,
   getDocumentPreview,
   getRelationIds,
+  getSecretValue,
   isPresentString,
   markdownToPlainText,
   normalizeDatabaseProperty,
@@ -64,6 +74,9 @@ export type { MultiSelectDragOverlayProps } from './components/MultiSelectDragOv
 // Types (re-exported for convenience)
 export type {
   AppDescriptor,
+  CloudComputerCliAuthFacts,
+  CloudComputerFacts,
+  CloudComputerSandboxFacts,
   CollectionItem,
   CollectionItemDetail,
   DatabaseDescriptor,
@@ -72,12 +85,16 @@ export type {
   DatabasePropertyType,
   DocumentContentType,
   DocumentRecord,
+  HandoverPayload,
+  HandoverResult,
   NotisDocumentEditorProps,
   NotisRuntime,
   NotisRuntimeContext,
   NotisRuntimeUI,
   QueryFilter,
   RouteDescriptor,
+  SecretPropertyValue,
+  SubscribeDatabaseOptions,
   ToolDescriptor,
   ToolInputSchema,
 } from './runtime';

package/dist/scaffolds/notis-random/packages/sdk/src/runtime.ts

@@ -25,7 +25,21 @@ export type DatabasePropertyType =
   | 'status'
   | 'relation'
   | 'formula'
-  | 'files';
+  | 'files'
+  | 'secret';
+
+/**
+ * The value of a `secret` property. The platform stores a pointer to a
+ * credential held elsewhere and never the credential itself, so there is
+ * deliberately nothing here to read the secret material from — only whether
+ * one is attached, which credential it is, and its lifecycle state.
+ */
+export interface SecretPropertyValue {
+  present: boolean;
+  reference: string | null;
+  status: string | null;
+  metadata: Record<string, unknown> | null;
+}
 
 export interface DatabasePropertyOption {
   id?: string | null;
@@ -188,6 +202,84 @@ export interface NotisRuntimeUI {
 // NotisRuntime
 // ---------------------------------------------------------------------------
 
+/**
+ * Options for `NotisRuntime.subscribeDatabase`.
+ */
+export interface SubscribeDatabaseOptions {
+  /**
+   * Called with `true` once a live change feed is attached, and with `false`
+   * when it drops or is torn down. Hosts without a change feed (dev harness,
+   * screenshot stub, vite preview) never call it, so `live` stays false there.
+   */
+  onStatusChange?: (live: boolean) => void;
+}
+
+/**
+ * Work an app hands to the Notis manager chat through `NotisRuntime.handover`.
+ */
+export interface HandoverPayload {
+  /** The message the manager should act on. */
+  prompt: string;
+  /**
+   * Key of a skill declared in `notis.config.ts` -> `skills[].key`. The host
+   * rejects a key this app does not declare. Omit to hand over plain work.
+   */
+  skill?: string;
+  /**
+   * Accepted for forward compatibility. The portal never submits a composer on
+   * the user's behalf today, so every handover resolves `drafted`; `sent` is
+   * reserved for a host that can genuinely dispatch the run.
+   */
+  autoSend?: boolean;
+}
+
+export interface HandoverResult {
+  /** `drafted` when the user still has to press send, `sent` when it went straight through. */
+  status: 'drafted' | 'sent';
+}
+
+/**
+ * The user's cloud computer, as far as an app may see it.
+ *
+ * `exists` is false when the user has never had a sandbox provisioned. A
+ * `status` of anything other than `'running'` means the VM is asleep; reading
+ * these facts never wakes it.
+ */
+export interface CloudComputerSandboxFacts {
+  exists: boolean;
+  status: string | null;
+  provider: string | null;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+/**
+ * Whether a CLI inside the cloud computer is signed in.
+ *
+ * `authenticated: null` means *unknown*, never *signed out*: the sandbox was
+ * not running, or the probe could not answer. `reason` says which
+ * (`'sandbox_not_running'`, `'no_sandbox'`, `'sandbox_status_unknown'`,
+ * `'probe_failed'`, `'not_signed_in'`).
+ */
+export interface CloudComputerCliAuthFacts {
+  authenticated: boolean | null;
+  account: string | null;
+  checked_at: string | null;
+  reason: string | null;
+}
+
+export interface CloudComputerFacts {
+  /**
+   * False when this host cannot answer at all — no cloud computer on the user's
+   * plan, or the platform could not resolve the facts. Render whatever the app
+   * did before rather than an error.
+   */
+  available: boolean;
+  reason?: string | null;
+  sandbox: CloudComputerSandboxFacts | null;
+  cli_auth: { gh: CloudComputerCliAuthFacts };
+}
+
 export interface NotisRuntime {
   app: AppDescriptor;
   route: RouteDescriptor;
@@ -195,6 +287,45 @@ export interface NotisRuntime {
   context: NotisRuntimeContext;
   ui?: NotisRuntimeUI;
 
+  /**
+   * Subscribe to changes on an app-owned database. Returns an unsubscribe.
+   *
+   * The change notification is only a signal — it carries no rows. Consumers
+   * react by refetching through the normal tool path, so app scoping,
+   * permissions and billing are unchanged. Use the `useDatabaseSubscription`
+   * hook rather than calling this directly.
+   */
+  subscribeDatabase?(
+    slug: string,
+    onChange: () => void,
+    options?: SubscribeDatabaseOptions,
+  ): () => void;
+
+  /**
+   * Hand a piece of work to the Notis manager chat. The app cannot run an
+   * agent itself: it describes the job, and the manager surface owns progress,
+   * billing, cancellation and the transcript. Results come back to the app
+   * through its own databases (see `useDatabaseSubscription`).
+   *
+   * Use the `useHandover` hook rather than calling this directly. Hosts
+   * without a manager chat (the dev harness, the vite preview) leave it
+   * undefined, so keep whatever fallback the app already offers.
+   */
+  handover?(payload: HandoverPayload): Promise<HandoverResult>;
+
+  /**
+   * Read-only facts about the user's cloud computer. Requires
+   * `capabilities.cloudComputer: 'read'` in `notis.config.ts` plus the user's
+   * approval; resolving it never creates, resumes or commands a sandbox.
+   *
+   * Use the `useCloudComputer` hook rather than calling this directly. Hosts
+   * without a cloud computer (the dev harness, the vite preview) answer
+   * `{ available: false }`, so keep whatever fallback the app already has.
+   * `{ refresh: true }` bypasses the host's short answer cache — the hook's
+   * refresh() sends it so a just-completed sign-in becomes visible.
+   */
+  cloudComputerFacts?(options?: { refresh?: boolean }): Promise<CloudComputerFacts>;
+
   navigate?: (payload: { kind: string; [key: string]: unknown }) => void;
 
   registerTopBarSearch?: (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notis_ai/cli",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "description": "Agent-first Notis CLI for apps and generic tool execution",
   "type": "module",
   "bin": {

package/skills/notis-apps/SKILL.md

@@ -31,7 +31,8 @@ All Notis apps are built using the Notis CLI, either locally in a repo workspace
 - Before installing, inspect the listing's `required_capabilities`. Explain each
   requested capability and obtain explicit approval; only then pass the matching
   token in `approved_capabilities`. Never infer capability approval. The current
-  workspace-wide read token is `workspace_databases_read`.
+  workspace-wide read token is `workspace_databases_read`; the read-only
+  cloud computer token is `cloud_computer_read`.
 
 ## Architecture
 
@@ -76,7 +77,7 @@ App code never accesses the runtime directly -- it uses SDK hooks (`useTool`, `u
 3. **Component rendering** -- Apps render as React components directly in the portal. No iframes.
    The portal owns the `ShadowRoot`, theme tokens, and runtime provider.
 4. **HTTP bridge** -- Runtime calls use fetch to `/portal_views/runtime_query`
-5. **Declarative tools** -- Tool access declared in `notis.config.ts`, enforced server-side
+5. **Declarative tools** -- Tool access is declared in `notis.config.ts` by the final names returned by tool discovery and enforced server-side. Views can call native Notis, connected integrations, PostForMe, and MCP tools directly; metered calls use the same credit-cap and usage-billing path as the CLI.
 6. **shadcn + Notis theme** -- Apps must use shadcn components with the live Notis theme provided by the portal
 7. **Phosphor icons only** -- Always `phosphor:` prefix. Never emojis.
 8. **Database refs only** -- `notis.config.ts` references existing databases by slug. The schema source of truth lives in the `databases` table, not in the manifest. Every native database is owned by exactly one app (`databases.owner_app_id`): creating one through `LOCAL_NOTIS_DATABASE_UPSERT_DATABASE` requires the owning app's slug or id in the `app` argument, install/dev materialization stamps ownership automatically, and deleting an app deletes its databases and their documents.
@@ -124,9 +125,9 @@ These are the most common mistakes agents make. Each one wastes time and produce
 2. **Pull only installed apps.** If the user explicitly wants to fork an app they already installed, run `npx --package @notis_ai/cli@latest -- notis apps list`, then `npx --package @notis_ai/cli@latest -- notis apps pull <app-id> ./<dir>`. To fork a Store app that is not installed, tell the user to install it from `/store` first.
 3. **Edit the listing source.** Update `name` (slug), `title`, description, icon, accent, author, categories, tagline, databases, routes, and tools in `notis.config.ts`. Declare a database as a string for schema-only Store packaging; use `{ slug: 'templates', seedDocuments: true }` only when its rows are deliberate starter content for every installer. Keep the complete Store release history in the root `CHANGELOG.md`, newest entry first, using `## [Release title] - YYYY-MM-DD` (or `{PR_MERGE_DATE}` before publication). The first entry powers **What’s New** and the same file powers **Version History**. `icon` is a `phosphor:<name>` value or `metadata/icon.png`; when unset the app shows its **two-letter initials** everywhere (store, sidebar, app details). `accent` optionally pins the avatar color to one of `blue|violet|emerald|amber|rose|sky|fuchsia|teal` (default derived from the app id). Icon/accent flow through deploy onto the app row + listing and can also be set later via the `update_app` tool.
 4. **Build pages in `app/`.** Reuse scaffold code wherever it fits.
-5. **Iterate live.** Run `npx --package @notis_ai/cli@latest -- notis apps dev` so the target desktop's **Local development** sidebar group discovers the app and renders the local bundle. Keep this command running for as long as the user is testing; stopping it removes the temporary Local development entry. Read the command's `Target desktop` line instead of guessing between Notis, Notis Beta, or a source-workspace desktop.
-6. **Capture listing screenshots.** Declare 3–6 screenshots in `notis.config.ts`, each with a stable `path`, descriptive `alt`, and optional `route`/`scenario`/`focus`/`theme`, then run `npx --package @notis_ai/cli@latest -- notis apps screenshot`. Use `focus` to frame a real app root without empty browser canvas; use `theme: 'light'` or `theme: 'dark'` to match both the Portal render and Store backdrop, and pair both modes when that best represents the app. It renders the configured states in a headless harness and writes exact 2000x1250 PNGs under `metadata/`, using the deterministic Store presentation by default (`--raw` is diagnostic only). Apps are icon-led like Raycast — the icon set in `notis.config.ts` represents the app, so there is no cover image, only these screenshots. Never hand-author the PNGs; regenerate them when routes or UI change.
-7. **Verify locally.** Run `npm install`, then `npx --package @notis_ai/cli@latest -- notis apps build` and `npx --package @notis_ai/cli@latest -- notis apps verify`. Surface the verify report and fix failures.
+5. **Iterate live.** Run `npx --package @notis_ai/cli@latest -- notis apps dev` so the target desktop's **Local development** sidebar group discovers the app and renders the local bundle. Keep this command running for as long as the user is testing; stopping it removes the temporary Local development entry. Read the command's `Target desktop` line instead of guessing between Notis, Notis Beta, or a source-workspace desktop. Add `--live-data` to point the session at the installed app's real databases instead of its own empty dev copies -- it applies to that session only, and warns and falls back when the app has not been deployed yet.
+6. **Capture listing screenshots.** Declare 3–6 screenshots in `notis.config.ts`, each with a stable `path`, descriptive `alt`, and optional `route`/`scenario`/`focus`/`theme`, then run `npx --package @notis_ai/cli@latest -- notis apps screenshot`. Use `focus` to frame a real app root without empty browser canvas; use `theme: 'light'` or `theme: 'dark'` to match both the Portal render and Store backdrop, and pair both modes when that best represents the app. It renders the configured states in a headless harness and writes exact 2000x1250 PNGs under `metadata/`, using the deterministic Store presentation by default (`--raw` is diagnostic only). Apps are icon-led like Raycast — the icon set in `notis.config.ts` represents the app, so there is no cover image, only these screenshots. Never hand-author the PNGs; regenerate them when routes or UI change. A `scenario` names an entry in `metadata/screenshot-fixtures.json`; besides `actions` it may carry its own `tools` and `requests`, shallow-merged per key over the file-level ones for that capture, which is how the same route is shown both populated and in its first-run empty state.
+7. **Verify locally.** Run `npm install`, then `npx --package @notis_ai/cli@latest -- notis apps build` and `npx --package @notis_ai/cli@latest -- notis apps verify`. Surface the verify report and fix failures. Incomplete listing media is only a `Store readiness:` warning there; run `notis apps verify --listing` before publish to make it a failure.
 8. **Local-development-first handoff — STOP HERE.** Keep `apps dev` running and hand off to the user: tell them the app is live in the target desktop's **Local development** sidebar group (green `DEV` badge) and ask them to test it there. Building a new app to this point, without deploying, is a **complete and expected** result. Do NOT proceed to `apps create` / `apps deploy` yet — wait for the user to test and explicitly ask to deploy. (`apps dev` is what puts the app in Local development; without a running session the app never appears there.) **Before handing off, complete all three acceptance checks:**
    1. Target: capture the CLI's `Target desktop: <name>` line and make sure that exact desktop app is running and signed in.
    2. Bundle: the reported loopback `/snapshot` URL responds successfully and contains the expected manifest/routes.
@@ -194,7 +195,7 @@ Create `notis.config.ts` with:
 - **name** -- Display name
 - **databases** -- Slug references to existing Notis databases
 - **routes** -- Route-first sidebar entries with explicit `slug`, optional `parentSlug`, and optional `collection.sidebar` tree config
-- **tools** -- Tool names the app can call at runtime
+- **tools** -- Final tool names the app can call at runtime. Use the shared discovery flow (`COMPOSIO_SEARCH_TOOLS`, then `COMPOSIO_GET_TOOL_SCHEMAS`) while building the app, and copy the returned final names into this list. Examples include `LOCAL_NOTIS_DATABASE_QUERY`, `LOCAL_NOTIS_MONID_RUN`, `GMAIL_SEND_EMAIL`, `LOCAL_POSTFORME_CREATE_POST`, and `LOCAL_MCP_<SERVER>_<TOOL>`. App code calls each declared name directly through `useTool`; it does not wrap provider or MCP calls in `COMPOSIO_MULTI_EXECUTE_TOOL`. Access stays scoped to the signed-in user's own connections, native database tools stay scoped to the app's databases unless `capabilities.workspaceDatabases: 'read'` is granted, and metered tools use the CLI-equivalent credit-cap and fail-closed usage-billing path.
 
 For collection-backed sidebars, use the route schema directly:
 
@@ -436,6 +437,9 @@ All hooks are imported from `@notis/sdk`:
 | `useNotisNavigation()` | `() => { toRoute, toDocument, toApp }` | Navigate between routes, documents, or the app root |
 | `useTopBarSearch(opts)` | `({ value, onChange, placeholder?, onSubmit? }) => { setLoading }` | Bind the current view to the Portal-owned top-bar search input |
 | `useBackend()` | `() => { request }` | Raw backend request proxy with JWT auth |
+| `useDatabaseSubscription(slug, opts?)` | `(slug: string, opts?) => { rows, documents, loading, error, refetch, live }` | Query a database and refetch it when its rows change. `live` is false on hosts without a change feed (dev harness, vite preview) -- keep a manual refresh for those |
+| `useHandover()` | `() => { handover, pending, error, available }` | Hand a prompt (optionally bound to a declared skill) to the Notis manager chat, which owns progress, billing and cancellation. `available` is false on hosts with no chat -- fall back to a copyable prompt |
+| `useCloudComputer()` | `() => { facts, loading, error, refresh }` | Read-only cloud computer facts: sandbox existence/status and whether the GitHub CLI is signed in. Requires `capabilities.cloudComputer: 'read'` plus the user's approval; `facts.available === false` means answer from the app's own fallback |
 
 ### Typed tool calls
 
@@ -487,7 +491,7 @@ This uploads the bundle and editable source snapshot directly to Supabase storag
 
 ### Headless harness verification
 
-Run `npx --package @notis_ai/cli@latest -- notis apps verify` after `npx --package @notis_ai/cli@latest -- notis apps build`. Use `--mode live` after deploy to exercise the real `/portal_views/runtime_query` with the CLI JWT instead of stub data. If `agent-browser` is unavailable, pass `--no-browser` to print URLs and use `--keep-open` for interactive triage with `notis-browser-control`.
+Run `npx --package @notis_ai/cli@latest -- notis apps verify` after `npx --package @notis_ai/cli@latest -- notis apps build`. Use `--mode live` after deploy to exercise the real `/portal_views/runtime_query` with the CLI JWT instead of stub data; live mode also fails a route whose runtime calls all errored, which a well-behaved error state would otherwise hide. If `agent-browser` is unavailable, pass `--no-browser` to print URLs and use `--keep-open` for interactive triage with `notis-browser-control`.
 
 #### What the harness catches that `npx --package @notis_ai/cli@latest -- notis apps build` does not
 

package/skills/notis-apps/cli.md

@@ -119,11 +119,14 @@ When to use: Run this inside a single app or a monorepo root with apps/<name>/no
 Options:
 - `--port <number>` — Local bundle server port (default: 5173).
 - `--no-open` — Do not auto-open the desktop Portal local development app.
+- `--live-data` — Read and write the installed app's real databases instead of empty dev copies. Applies to this session only; warns and falls back when the app is not installed yet.
+- `--grant-cloud-shell` — Approve a cloudComputer: 'shell' declaration without the interactive prompt. The grant persists for this dev app; authorship alone never grants it.
 
 Examples:
 - `npx --package @notis_ai/cli@latest -- notis apps dev`
 - `npx --package @notis_ai/cli@latest -- notis apps dev ./my-app`
 - `npx --package @notis_ai/cli@latest -- notis apps dev ./workspace --port 5200`
+- `npx --package @notis_ai/cli@latest -- notis apps dev --live-data  # iterate on a view over the installed app's real rows`
 
 ### `npx --package @notis_ai/cli@latest -- notis apps build [dir]`
 
@@ -137,15 +140,16 @@ Examples:
 
 ### `npx --package @notis_ai/cli@latest -- notis apps verify [dir]`
 
-Validate every route and the production Store listing contract.
+Validate that every route renders and reports Store listing readiness.
 
-When to use: After notis apps screenshot, before deploy. Catches render-time crashes, missing runtime calls, and incomplete listing media that the build step cannot detect.
+When to use: Any time after notis apps build, and before deploy. Catches render-time crashes and missing runtime calls. Incomplete listing media is reported as a warning; pass --listing to fail on it instead.
 
 Options:
 - `--routes <slugs>` — Comma-separated route slugs. Default: every route in manifest.
 - `--port <n>` — Loopback port. Default: auto-pick.
 - `--skip-build` — Skip notis apps build; reuse existing .notis/output/.
-- `--mode <mode>` — stub | live. Default stub. Live posts to /portal_views/runtime_query with the CLI JWT.
+- `--mode <mode>` — stub | live. Default stub. Live posts to /portal_views/runtime_query with the CLI JWT and fails routes whose runtime calls all errored.
+- `--listing` — Fail instead of warn when the Store listing (tagline, categories, screenshots, changelog) is incomplete.
 - `--no-browser` — Start the harness server and print URLs; do not drive agent-browser.
 - `--keep-open` — Leave server + browser session running after report (for manual triage).
 
@@ -153,6 +157,7 @@ Examples:
 - `npx --package @notis_ai/cli@latest -- notis apps verify`
 - `npx --package @notis_ai/cli@latest -- notis apps verify --routes notes`
 - `npx --package @notis_ai/cli@latest -- notis apps verify --mode live`
+- `npx --package @notis_ai/cli@latest -- notis apps verify --listing  # gate on Store listing readiness before publish`
 - `npx --package @notis_ai/cli@latest -- notis apps verify --no-browser  # start the harness, drive agent-browser yourself`
 
 ### `npx --package @notis_ai/cli@latest -- notis apps screenshot [dir]`

package/skills/notis-cli/SKILL.md

@@ -31,6 +31,8 @@ Use the registry-resolved published npm package everywhere:
 
 Always use this NPX command form so the agent runs the current published CLI. In hosted shells, the CLI is pre-authenticated through `NOTIS_JWT`. On a local machine the CLI holds its own OAuth grant: `notis login` authorizes one in the browser, and signing in to the Notis desktop app authorizes one automatically for that account. Either way the grant belongs to the CLI, which refreshes it without the desktop app running.
 
+`@latest` is correct for every account, including beta ones. Each deployment reports which published build belongs to it, `notis login` pins that on the profile, and a later run that finds itself on the wrong build hands the invocation to the right one before doing anything. Never substitute a channel by hand: pinning `@beta` on a production profile is how a machine ends up running a build its API does not expect. `notis doctor` reports the active channel, and `NOTIS_CLI_AUTO_CHANNEL=0` turns the hand-off off for a run.
+
 This `notis-cli` skill is delivered through normal Notis skill sync for the signed-in user, alongside other curated skills.
 
 ## Profiles: accounts and endpoints

package/src/cli.js

@@ -1,3 +1,4 @@
+import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -6,10 +7,17 @@ import { COMMAND_SPECS, GROUP_SUMMARIES } from './command-specs/index.js';
 import { OutputManager } from './runtime/output.js';
 import { asCliError } from './runtime/errors.js';
 import { reportCliCommand } from './runtime/telemetry.js';
+import {
+  CHANNEL_SWITCH_ENV,
+  resolveChannelSwitch,
+} from './runtime/channel.js';
 import {
   DEFAULT_PROFILE,
+  getProfile,
+  loadConfig,
   resolveOutputMode,
   resolveRuntimeProfile,
+  resolveWorktreeRuntime,
   workspacePath,
 } from './runtime/profiles.js';
 
@@ -232,7 +240,157 @@ export function createProgram() {
   return program;
 }
 
+/**
+ * Read the two global flags that decide which build should serve this run.
+ *
+ * Commander cannot help here: the decision has to be made before the program
+ * parses, because the answer may be to hand the whole invocation to a
+ * different process. Only `--profile` and `--api-base` matter, and both are
+ * plain `--flag value` pairs.
+ */
+export function readChannelRelevantFlags(args = []) {
+  const flags = {};
+  for (const [index, token] of args.entries()) {
+    for (const [flag, key] of [['--profile', 'profile'], ['--api-base', 'apiBase']]) {
+      if (token === flag) flags[key] = args[index + 1];
+      else if (token.startsWith(`${flag}=`)) flags[key] = token.slice(flag.length + 1);
+    }
+  }
+  return flags;
+}
+
+export function channelProfileForArgs(
+  args = [],
+  env = process.env,
+  { config: suppliedConfig, worktreeRuntime: suppliedWorktreeRuntime } = {},
+) {
+  // An explicit endpoint overrides the stored profile for this run, so it also
+  // decides the build: `--api-base https://api-beta.notis.ai` on a production
+  // profile is a deliberate one-off beta call.
+  const { profile: profileName, apiBase } = readChannelRelevantFlags(args);
+  if (apiBase) {
+    return { api_base: apiBase };
+  }
+  if (env.NOTIS_API_BASE) {
+    return { api_base: env.NOTIS_API_BASE };
+  }
+  const config = suppliedConfig || loadConfig();
+  const explicitProfile = profileName || env.NOTIS_PROFILE;
+  if (explicitProfile) {
+    return getProfile(config, explicitProfile);
+  }
+  const resolvedWorktree = suppliedWorktreeRuntime === undefined
+    ? resolveWorktreeRuntime()
+    : suppliedWorktreeRuntime;
+  // A stopped local-only worktree must reach the normal routing error on the
+  // current build. Switching based on an unrelated shared profile would escape
+  // the worktree boundary before that fail-closed check runs.
+  if (resolvedWorktree?.unavailable) {
+    return {};
+  }
+  if (resolvedWorktree?.profile) {
+    return resolvedWorktree;
+  }
+  // NOTIS_JWT replaces the credential, not the route. Unless NOTIS_API_BASE
+  // was explicit above, the selected/current profile still owns the channel.
+  return getProfile(config, config.current_profile || DEFAULT_PROFILE);
+}
+
+function interruptedExitCode(signal) {
+  if (signal === 'SIGINT') return 130;
+  if (signal === 'SIGTERM') return 143;
+  return 1;
+}
+
+export function executeChannelSwitch(
+  decision,
+  args,
+  env,
+  { spawn = spawnSync } = {},
+) {
+  const childEnv = { ...env, [CHANNEL_SWITCH_ENV]: '1' };
+  // First make npm resolve and boot the target package without executing the
+  // requested command. That distinguishes an unavailable tag/network from a
+  // legitimate non-zero exit of the handed-off CLI, which must be propagated
+  // rather than retried locally after a possible mutation.
+  const probe = spawn(decision.command, [...decision.args, '--version'], {
+    stdio: 'ignore',
+    env: childEnv,
+  });
+  if (probe.signal) {
+    return {
+      ...decision,
+      exitCode: interruptedExitCode(probe.signal),
+      reason: 'switch_interrupted',
+    };
+  }
+  if (probe.error || probe.status !== 0) {
+    return { ...decision, switch: false, reason: 'switch_unavailable' };
+  }
+
+  const result = spawn(decision.command, [...decision.args, ...args], {
+    stdio: 'inherit',
+    env: childEnv,
+  });
+  if (result.signal) {
+    return {
+      ...decision,
+      exitCode: interruptedExitCode(result.signal),
+      reason: 'switch_interrupted',
+    };
+  }
+  if (result.error || typeof result.status !== 'number') {
+    return { ...decision, switch: false, reason: 'switch_failed' };
+  }
+  return { ...decision, exitCode: result.status };
+}
+
+/**
+ * Hand this invocation to the published build the profile is pinned to.
+ *
+ * Returns the decision rather than exiting so tests can assert on it. Any
+ * failure to reach the other build is non-fatal: running the wrong channel is
+ * a much smaller problem than refusing to run at all.
+ */
+export function switchChannelIfNeeded(
+  argv = process.argv,
+  env = process.env,
+  { spawn = spawnSync, platform = process.platform, moduleDirectory } = {},
+) {
+  const args = argv.slice(2);
+  let profile;
+  try {
+    profile = channelProfileForArgs(args, env);
+  } catch {
+    return { switch: false, reason: 'profile_unreadable' };
+  }
+  const decision = resolveChannelSwitch({
+    runningVersion: CLI_VERSION,
+    profile,
+    moduleDirectory: moduleDirectory || dirname(fileURLToPath(import.meta.url)),
+    env,
+    platform,
+  });
+  if (!decision.switch) {
+    return decision;
+  }
+
+  const result = executeChannelSwitch(decision, args, env, { spawn });
+  if (!result.switch) {
+    process.stderr.write(
+      `Notis CLI could not start the ${decision.targetChannel} build for this profile; `
+      + `continuing on ${decision.runningChannel}.\n`,
+    );
+  }
+  return result;
+}
+
 export async function run(argv = process.argv) {
+  const switched = switchChannelIfNeeded(argv);
+  if (switched.switch) {
+    process.exitCode = switched.exitCode;
+    return;
+  }
   const program = createProgram();
   await program.parseAsync(argv);
 }