@layers/amba 4.0.3 → 4.1.0

package/dist/ship/config.d.ts

@@ -0,0 +1,98 @@
+/**
+ * `amba ship` config — the typed, hand-validated launch config.
+ *
+ * One file per repo (default `amba.ship.json`) describes how to take this Expo
+ * app from code-complete to live on the App Store and Google Play. It carries
+ * NON-SECRET identifiers and the NAME of the env var holding the Expo token —
+ * never secret values (the App Store Connect `.p8` and Play service-account
+ * JSON live in `eas.json`, owned by the app repo, exactly where the build runs).
+ *
+ * Validation is hand-rolled (the CLI deliberately ships no `zod` — see
+ * `_internal/shared.ts` for the same return-all-errors-at-once pattern). The
+ * field names are the canonical contract; `validateShipConfig` reports every
+ * problem in one pass and enforces the cross-field invariants.
+ *
+ * Monetization is NOT described here: the App Store / Play product catalog is
+ * Amba's monetization control plane (`amba monetization`, the durable Track H
+ * apply against the provider). `ship` only flips `monetization.enabled` to
+ * decide whether to verify that catalog is in sync before building.
+ */
+/** The ordered launch phases. `ship` runs them in this sequence. */
+export declare const SHIP_PHASES: readonly ["preflight", "monetization", "build", "submit", "metadata", "release"];
+export type Phase = (typeof SHIP_PHASES)[number];
+export declare const SHIP_PLATFORMS: readonly ["ios", "android"];
+export type Platform = (typeof SHIP_PLATFORMS)[number];
+/** Google Play release tracks `ship` can submit to. */
+export declare const PLAY_TRACKS: readonly ["internal", "alpha", "beta", "production"];
+export type PlayTrack = (typeof PLAY_TRACKS)[number];
+/** Default config filename when no `--config <path>` is passed. */
+export declare const DEFAULT_SHIP_CONFIG_FILE = "amba.ship.json";
+export interface ShipConfig {
+    /** Schema version of this config file (forward-compatible migrations). */
+    version: number;
+    app: {
+        /** Lowercase key used to scope the per-app launch state file. */
+        slug: string;
+        /** Human-facing app name (App Store / Play display). */
+        name: string;
+        /** Marketing version MAJOR.MINOR.PATCH. */
+        version: string;
+        /** iOS bundle identifier (reverse-DNS). */
+        bundleId: string;
+        /** Android application id (reverse-DNS); may equal bundleId. */
+        androidPackage: string;
+    };
+    build: {
+        /** EAS build profile (a `build.<profile>` key in eas.json), e.g. "production". */
+        profile: string;
+        /** Platforms to build/submit/release. At least one. */
+        platforms: Platform[];
+    };
+    ios: {
+        /**
+         * App Store Connect numeric app id. `null` until the app record exists.
+         * EAS Submit cannot create the record (and under --non-interactive cannot
+         * prompt for it, eas-cli #2418), so `ship` treats a null value as a manual
+         * gate on the submit phase.
+         */
+        ascAppId: string | null;
+    };
+    android: {
+        /** Track the submit phase lands on; release promotes it to production. */
+        track: PlayTrack;
+    };
+    monetization: {
+        /**
+         * When true, `ship` verifies the App Store / Play product catalog is in
+         * sync with the Amba monetization control plane before building, and gates
+         * if it has drifted (run `amba monetization apply`). When false (the
+         * default for apps that don't sell anything), the monetization phase is a
+         * no-op skip.
+         */
+        enabled: boolean;
+    };
+    secrets: {
+        /** NAME of the env var holding the Expo token for non-interactive EAS auth. */
+        expoTokenEnvVar: string;
+    };
+}
+export type ValidateResult = {
+    ok: true;
+    config: ShipConfig;
+} | {
+    ok: false;
+    errors: string[];
+};
+/**
+ * Validate an untrusted parsed JSON value into a typed `ShipConfig`,
+ * collecting EVERY problem (not just the first) so a misconfigured file
+ * surfaces all its issues in one run. Returns the typed config on success.
+ */
+export declare function validateShipConfig(raw: unknown): ValidateResult;
+/**
+ * A starter config written by `amba ship init`. Placeholders are intentionally
+ * obvious so the validator's invariants don't pass on an unedited file's IDs
+ * (the reverse-DNS / semver placeholders DO validate so `--phase preflight`
+ * works immediately; the operator swaps in their real values).
+ */
+export declare function shipConfigTemplate(slug: string): ShipConfig;

package/dist/ship/exec.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The external-command boundary for `amba ship`.
+ *
+ * Every shell-out (always `eas`) goes through an `Executor`, so the phase
+ * logic — which args get built, how `--json` output is parsed, which failures
+ * map to which manual gate — is unit-tested against a fake executor with NO
+ * live cloud, no EAS account, and no Apple/Google credentials. The default
+ * `createNodeExecutor()` is a thin, shell-free wrapper around
+ * `node:child_process.spawn` (mirrors the launch toolkit's `lib/exec`).
+ */
+export interface ExecRunOptions {
+    /** Extra environment variables merged over process.env. */
+    env?: NodeJS.ProcessEnv;
+    /** Working directory for the child. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Hard timeout in ms. On expiry the child is SIGKILLed and the call rejects. */
+    timeoutMs?: number;
+    /** If true, stream child stdout/stderr live to this process. Default false. */
+    stream?: boolean;
+    /** If true, log the command and return a synthetic success WITHOUT running. */
+    dryRun?: boolean;
+}
+export interface ExecResult {
+    /** The redacted command line, for logging / state. */
+    command: string;
+    code: number;
+    stdout: string;
+    stderr: string;
+    /** True when the call was skipped because of dry-run. */
+    dryRun: boolean;
+}
+export interface Executor {
+    /** Run a command. Resolves on exit 0; REJECTS (with an actionable message) otherwise. */
+    run(cmd: string, args: string[], opts?: ExecRunOptions): Promise<ExecResult>;
+}
+/**
+ * Redact secret-shaped tokens from a string before it is logged. A backstop,
+ * not a license — `ship` never puts secret values on a command line (EAS reads
+ * its token from the env and its store creds from eas.json). Covers Expo /
+ * common access-token shapes and `Bearer`/`sk_` prefixes.
+ */
+export declare function redactSecrets(text: string): string;
+/** A backing executor over `node:child_process.spawn`. Never invokes a shell. */
+export declare function createNodeExecutor(globalDryRun?: boolean): Executor;
+/**
+ * Run a command and report success/failure WITHOUT throwing — for read-only
+ * "is this CLI installed/authed?" probes where a non-zero exit is data, not a
+ * fatal error.
+ */
+export declare function probe(exec: Executor, cmd: string, args: string[], opts?: ExecRunOptions): Promise<{
+    ok: boolean;
+    result?: ExecResult;
+}>;

package/dist/ship/orchestrator.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The `amba ship` orchestrator.
+ *
+ * Sequences the requested phases in canonical order, honoring per-app
+ * idempotency state (skip phases already `done` unless `--force`), propagating
+ * a global `--dry-run` to every phase, and stopping the chain at the first gate
+ * or failure (later phases depend on earlier ones — the "clear a gate → re-run"
+ * loop). It owns ALL state writes and the clock; the phase runners stay pure of
+ * both. Returns structured rows for the command layer to render.
+ */
+import type { Phase, Platform, ShipConfig } from './config.js';
+import type { Executor } from './exec.js';
+import { type PhaseRunner } from './phases.js';
+export type RowStatus = 'done' | 'skipped' | 'gate' | 'failed' | 'pending' | 'dry-run';
+export interface ShipRow {
+    phase: Phase;
+    status: RowStatus;
+    detail: string;
+    gates?: string[];
+}
+export interface ShipResult {
+    rows: ShipRow[];
+    /** A gate stopped the chain (human store action needed) — not an error. */
+    blocked: boolean;
+    /** A phase errored. */
+    failed: boolean;
+}
+export interface ShipRunOptions {
+    config: ShipConfig;
+    /** Which phases to run (any subset of SHIP_PHASES). */
+    phases: Phase[];
+    platforms: Platform[];
+    exec: Executor;
+    dryRun: boolean;
+    force: boolean;
+    stateBaseDir?: string;
+    env?: NodeJS.ProcessEnv;
+    now?: () => string;
+    log?: (line: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+    /** Resolve the linked Amba project id (default: from .env.local). */
+    resolveProjectId?: () => Promise<string | null>;
+    /** Admin GET (default: the real api-client). Injected in tests. */
+    adminGet?: <T>(path: string) => Promise<{
+        data: T;
+    }>;
+    /** Phase runners (default: the real registry). Injected in tests. */
+    runners?: Record<Phase, PhaseRunner>;
+    releasePollMs?: number;
+    releaseMaxWaitMs?: number;
+}
+export declare function runShip(opts: ShipRunOptions): Promise<ShipResult>;

package/dist/ship/phases.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The six `amba ship` phases.
+ *
+ * Each runner receives a `ShipContext` (config + an injected `Executor` for
+ * `eas`, an injected admin-API `adminGet`, a project resolver, and state
+ * accessors) and returns a `PhaseOutcome`. The cloud-touching work is all
+ * behind those injection points, so the arg-building, `--json` parsing, and
+ * failure→manual-gate mapping below are unit-tested with no live cloud.
+ *
+ * Honest gates: several launch steps are NOT API-automatable (create the App
+ * Store Connect / Play app record, the Apple Paid-Apps agreement, screenshots,
+ * store review). A runner DETECTS such a step and returns `status: 'gate'` with
+ * the exact action + console URL, rather than pretending it is automated.
+ */
+import type { Executor } from './exec.js';
+import type { Phase, Platform, ShipConfig } from './config.js';
+import type { PhaseStatus } from './state.js';
+export interface ShipContext {
+    config: ShipConfig;
+    exec: Executor;
+    platforms: Platform[];
+    dryRun: boolean;
+    force: boolean;
+    env: NodeJS.ProcessEnv;
+    now: () => string;
+    log: (line: string) => void;
+    /** Read a phase's persisted note (a JSON string) or null. */
+    getNote: (phase: Phase) => string | null;
+    /** Checkpoint a phase's status + note mid-run. No-op under dryRun. */
+    checkpoint: (phase: Phase, status: PhaseStatus, note: string) => void;
+    /** Resolve the linked Amba project id, or null when no project is linked. */
+    resolveProjectId: () => Promise<string | null>;
+    /** GET an admin API path → `{ data }`. */
+    adminGet: <T>(path: string) => Promise<{
+        data: T;
+    }>;
+    /** Sleep helper (injected so release-polling is instant in tests). */
+    sleep: (ms: number) => Promise<void>;
+    /** Build-completion poll cadence (release phase). Small values in tests. */
+    releasePollMs: number;
+    releaseMaxWaitMs: number;
+}
+export interface PhaseOutcome {
+    status: 'done' | 'gate' | 'failed' | 'skipped';
+    detail: string;
+    /** Structured JSON note to persist (build/submit/release maps). */
+    note?: string;
+    /** Human-action items when status === 'gate' (printed prominently). */
+    gates?: string[];
+}
+export type PhaseRunner = (ctx: ShipContext) => Promise<PhaseOutcome>;
+export declare function easBuildArgs(platform: Platform, profile: string): string[];
+export declare function easSubmitArgs(input: {
+    platform: Platform;
+    profile: string;
+    buildId: string | null;
+    track?: string;
+}): string[];
+export declare function easBuildViewArgs(buildId: string): string[];
+export declare function easMetadataArgs(profile: string): string[];
+export interface EasBuild {
+    id: string;
+    status?: string;
+    platform?: string;
+    appVersion?: string;
+    artifacts?: {
+        applicationArchiveUrl?: string;
+        buildUrl?: string;
+    };
+    buildDetailsPageUrl?: string;
+}
+export interface EasSubmission {
+    id?: string;
+    status?: string;
+    platform?: string;
+    buildId?: string;
+    submissionDetailsPageUrl?: string;
+}
+/** Pull the build object for `platform` out of `eas build --json` stdout. */
+export declare function extractBuild(raw: string, platform: Platform): EasBuild;
+export declare function artifactUrlOf(b: EasBuild): string | null;
+/** Parse the submission object for `platform` out of `eas submit --json` stdout. */
+export declare function parseSubmission(raw: string, platform: Platform): EasSubmission;
+export declare function diagnoseBuildFailure(message: string): string;
+/** A submit failure that needs a human store action, or null for a plain error. */
+export declare function diagnoseSubmitGate(platform: Platform, message: string): string | null;
+export declare const PHASE_RUNNERS: Record<Phase, PhaseRunner>;

package/dist/ship/state.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `amba ship` per-app idempotency state.
+ *
+ * Each app's launch progress is a JSON file at `.amba/ship-state/<slug>.json`
+ * recording, per phase, whether it is done / failed / blocked-by-a-human-gate /
+ * in-progress, when, and an optional structured `note` (e.g. the build ids a
+ * later phase reads back). The orchestrator uses it to skip already-done phases
+ * and to resume the "clear a gate → re-run" loop.
+ *
+ * PURITY RULE: this module NEVER reads the clock itself — callers pass an
+ * ISO-8601 timestamp into every mutation so it stays deterministically
+ * testable (the orchestrator owns the clock). The file is purely an
+ * optimization/audit log: deleting it is safe because every phase re-detects
+ * real cloud state before mutating.
+ */
+import type { Phase } from './config.js';
+export type PhaseStatus = 'pending' | 'in-progress' | 'done' | 'failed' | 'gate';
+export interface PhaseRecord {
+    status: PhaseStatus;
+    /** ISO timestamp of the last status change (supplied by the caller). */
+    updatedAt: string;
+    /** Free-form note: build ids, a short reason, etc. NEVER secrets. */
+    note?: string;
+}
+export interface ShipState {
+    slug: string;
+    /** Schema version of this state file (forward-compatible migrations). */
+    stateVersion: 1;
+    /**
+     * The app marketing version the recorded phases shipped. When it changes, the
+     * orchestrator invalidates the binary-scoped phases (build → release) so a
+     * version bump rebuilds instead of skipping a stale `done`.
+     */
+    appVersion?: string;
+    phases: Partial<Record<Phase, PhaseRecord>>;
+}
+/** Path to the state file for a slug, under `<baseDir>/.amba/ship-state/`. */
+export declare function shipStatePath(slug: string, baseDir?: string): string;
+/** Load state for a slug, or a fresh empty state if none exists. Pure read. */
+export declare function loadShipState(slug: string, baseDir?: string): ShipState;
+/** Write state atomically (write temp, then rename) to avoid partial files. */
+export declare function saveShipState(state: ShipState, baseDir?: string): void;
+/**
+ * Return a NEW state with one phase updated. Pure: does not touch disk and does
+ * not read the clock — the caller passes `timestamp`. Use `saveShipState` to
+ * persist.
+ */
+export declare function withPhase(state: ShipState, phase: Phase, status: PhaseStatus, timestamp: string, note?: string): ShipState;
+/** True if a phase is recorded as done. Used by the orchestrator for idempotency. */
+export declare function isPhaseDone(state: ShipState, phase: Phase): boolean;
+/** The record for a phase, or a synthetic pending record if never run. */
+export declare function phaseRecord(state: ShipState, phase: Phase): PhaseRecord;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@layers/amba",
-  "version": "4.0.3",
-  "description": "amba — agent-native backend-as-a-service. Functions, collections, storage, AI, email, queues, sites — one CLI to spin up your project and ship to production. `npx @layers/amba init` to start.",
+  "version": "4.1.0",
+  "description": "amba — agent-native backend-as-a-service. Functions, collections, storage, AI, email, queues, sites, and `amba ship` to take an Expo app live on the App Store + Google Play. `npx @layers/amba init` to start.",
   "type": "module",
   "bin": {
     "amba": "dist/index.js"
@@ -49,8 +49,8 @@
     "tsdown": "^0.12.5",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@layers/amba-mcp": "4.0.2",
-    "@layers/amba-shared": "4.0.2"
+    "@layers/amba-shared": "4.0.4",
+    "@layers/amba-mcp": "4.0.6"
   },
   "scripts": {
     "build": "tsdown && tsc --emitDeclarationOnly",

package/skill-bundle/SKILL.md

@@ -71,6 +71,8 @@ Check whether a project exists in this directory:
 
 > **If you don't see Amba MCP tools available** (no `mcp__amba__*` in your tool list), Amba's MCP server isn't wired into your agent's tool surface this session. Run `npx -y @layers/amba init` via your bash tool — it provisions the account/project, writes `.env.local`, installs this skill, and wires the MCP entry into the user's agent config so the typed tools light up on the next agent launch.
 >
+> **If your harness ALSO blocks that bash command** (a locked-down agent: no installer, no network egress, no settings edits) — do NOT try to add the MCP server yourself, run the installer another way, or edit your own settings/permissions to authorize it. Refusing to self-modify or widen your own permissions is correct; don't circumvent it. Instead, ask the developer to run **one** command in **their own** terminal (not subject to your sandbox): `npx @layers/amba init`. It creates the account with no browser and writes `AMBA_PROJECT_ID` + `AMBA_CLIENT_KEY` to `.env.local`. Ask them to run it, say when it's done, then resume from Step 0 by reading `.env.local`. Pasting an `amb_ck_…` client key is the last-resort lite path — enough to wire `Amba.configure()` + verify events land, but a client key alone can't do admin provisioning (achievements, collections, segments), which needs the PAT/server key.
+>
 > Do not pause to ask the user about restarting. You have **three** working paths for admin operations in this session, in order of preference:
 >
 > 1. **POST JSON-RPC directly to `https://mcp.amba.dev/mcp`** (recommended — full 178-tool surface, no client wiring needed). Amba's MCP is plain HTTP, not stdio. Read the PAT from `~/.amba/credentials.json` (`.pat` field), then `curl` (or `fetch`) the endpoint:

package/skill-bundle/references/infrastructure.md

@@ -15,7 +15,7 @@ A collection is a schema-first table inside the project's isolated tenant databa
 | `amba_collections_create` / `amba_create_collection` | Create a typed collection. | `{ project_id, name: "todos", columns: [{ name: "title", type: "text", nullable: false }, { name: "done", type: "boolean", nullable: false, default: false }, { name: "due_at", type: "timestamptz", nullable: true }] }` |
 | `amba_collections_list` / `amba_list_collections` | List collections in this project. | `{ project_id }` |
 | `amba_collections_get` / `amba_get_collection` | Read one collection's schema. | `{ project_id, collection_name: "todos" }` |
-| `amba_collections_alter` / `amba_alter_collection` | Add / drop columns, add / drop indexes. | `{ project_id, collection_name: "todos", add_columns: [{ name: "priority", type: "int", nullable: true }] }` |
+| `amba_collections_alter` / `amba_alter_collection` | Add / drop columns, add / drop indexes. | `{ project_id, collection_name: "todos", add_columns: [{ name: "priority", type: "integer", nullable: true }] }` |
 | `amba_collections_delete` / `amba_delete_collection` | Drop the table (destructive). | `{ project_id, collection_name }` |
 | `amba_admin_insert_row` | Insert a row as the developer (bypasses user-scope). Useful for seed data. | `{ project_id, collection: "todos", row: { title: "Sample todo", done: false } }` |
 | `amba_admin_list_rows` | Read rows as the developer (bypasses user-scope — sees every user's rows). | `{ project_id, collection: "todos", limit: 100 }` |
@@ -28,7 +28,7 @@ A collection is a schema-first table inside the project's isolated tenant databa
 | `amba_client_find_rows` | Filter / sort / paginate rows (end-user). | `{ project_id, api_key, session_token, collection, filter: {...}, order_by: [...], limit: 50 }` |
 | `amba_client_find_nearest_rows` | Vector-similarity search (rows with a `vector(<dim>)` column). | `{ project_id, api_key, session_token, collection, vector_column: "embedding", query_vector: [...], k: 10 }` |
 
-Column types: `text`, `int`, `bigint`, `float`, `boolean`, `timestamptz`, `date`, `json`, `jsonb`, `uuid`, `vector(<dim>)` (e.g. `vector(1536)` for OpenAI embeddings).
+Column types: `text`, `integer`, `bigint`, `numeric`, `boolean`, `timestamptz`, `date`, `jsonb`, `uuid`, `vector(<dim>)` (e.g. `vector(1536)` for OpenAI embeddings), plus array forms `text[]`, `integer[]`, `bigint[]`, `numeric[]`, `boolean[]`, `uuid[]`. Use `integer` (not `int`), `numeric` (not `float`/`real`/`double`), and `jsonb` (not `json`) — the validator rejects the aliases.
 
 ### Functions (serverless code)
 
@@ -48,16 +48,21 @@ Run user code in a sandbox triggered by HTTP, cron, or webhook. The function get
 
 ### AI prompts
 
-Managed LLM templates: stored prompt with model + system message + variables, callable by name from the SDK. The actual LLM call is rewritten per-tenant — the customer's API keys (Anthropic / OpenAI) live in the tenant secrets, never on the device.
+Managed LLM templates: a stored prompt with provider + model + system message, invoked by name from the SDK. The actual LLM call is rewritten server-side per-tenant — the customer's provider API key (Anthropic / OpenAI / Mistral / Gemini) stays server-side, never on the device.
+
+**Two steps, in order:** register the provider key with `amba_ai_providers_set`, then create prompts against it. A prompt registered before its provider has a key still saves, but invocations fail with `provider_not_configured` (424) until the key is set. The provider key is **not** a function secret — `amba_secrets_set` writes function-scoped Worker secrets the AI gateway never reads; provider keys live in a separate gateway-owned store set only via `amba_ai_providers_set`.
 
 | Tool | Purpose | Example args |
 | --- | --- | --- |
-| `amba_ai_prompts_create` / `amba_create_ai_prompt` | Create a prompt template. | `{ project_id, key: "summarize", model: "claude-opus-4-5", system: "Summarize the user's text in 2 sentences.", variables: ["text"] }` |
+| `amba_ai_providers_set` | Register / rotate the upstream provider API key. **Do this first.** | `{ project_id, provider: "anthropic", api_key: "sk-ant-..." }` |
+| `amba_ai_providers_list` | List registered providers (`configured` = key set). | `{ project_id }` |
+| `amba_ai_providers_delete` | Revoke a provider key (fails if prompts still reference it). | `{ project_id, provider: "anthropic" }` |
+| `amba_ai_prompts_create` / `amba_create_ai_prompt` | Create a prompt template. | `{ project_id, name: "summarize", provider: "anthropic", model: "claude-opus-4-5", system_prompt: "Summarize the user's text in 2 sentences.", client_invokable: true }` |
 | `amba_ai_prompts_list` / `amba_list_ai_prompts` | List prompts. | `{ project_id }` |
-| `amba_ai_prompts_get` / `amba_get_ai_prompt` | Read one prompt. | `{ project_id, key }` |
-| `amba_ai_prompts_update` / `amba_update_ai_prompt` | Edit a prompt (model swap, system message change). | `{ project_id, key, system: "..." }` |
-| `amba_ai_prompts_invoke` / `amba_invoke_ai_prompt` | Invoke a prompt server-side (no client involvement — admin testing). | `{ project_id, key, variables: { text: "..." } }` |
-| `amba_ai_prompts_delete` / `amba_delete_ai_prompt` | Delete. | `{ project_id, key }` |
+| `amba_ai_prompts_get` / `amba_get_ai_prompt` | Read one prompt. | `{ project_id, name }` |
+| `amba_ai_prompts_update` / `amba_update_ai_prompt` | Edit a prompt (replaces all fields; bumps version). | `{ project_id, name, provider, model, system_prompt: "..." }` |
+| `amba_ai_prompts_invoke` / `amba_invoke_ai_prompt` | Invoke a prompt server-side (admin testing). `messages` is a provider-shaped array. | `{ project_id, name, messages: [{ role: "user", content: "..." }] }` |
+| `amba_ai_prompts_delete` / `amba_delete_ai_prompt` | Delete. | `{ project_id, name }` |
 
 ### Analytics + events + sessions
 
@@ -75,7 +80,7 @@ Managed LLM templates: stored prompt with model + system message + variables, ca
 
 | Tool | Purpose | Example args |
 | --- | --- | --- |
-| `amba_secrets_set` / `amba_set_secret` | Set a tenant secret (encrypted at rest). Use for third-party API keys called from functions. | `{ project_id, name: "OPENAI_API_KEY", value: "sk-..." }` |
+| `amba_secrets_set` / `amba_set_secret` | Set a **function-scoped** secret (encrypted at rest; bound on the next deploy). For third-party API keys called from your functions — NOT AI provider keys (use `amba_ai_providers_set` for those). | `{ project_id, name: "STRIPE_WEBHOOK_SECRET", value: "whsec_..." }` |
 | `amba_secrets_get` / `amba_get_secret` | Read a secret (returns `"<redacted>"` unless explicitly requested). | `{ project_id, name }` |
 | `amba_secrets_list` / `amba_list_secrets` | List secret names. | `{ project_id }` |
 | `amba_secrets_delete` / `amba_delete_secret` | Delete. | `{ project_id, name }` |
@@ -138,9 +143,9 @@ const newTodo = await Amba.collections.insert('todos', {
 await Amba.collections.update('todos', newTodo.id, { done: true });
 await Amba.collections.delete('todos', newTodo.id);
 
-// AI — call a managed prompt
+// AI — call a managed prompt (prompt_slug names the registered prompt)
 const response = await Amba.ai.anthropic.messages.create({
-  prompt_key: 'summarize',
+  prompt_slug: 'summarize',
   variables: { text: 'A long article about backend services …' },
 });
 // response.content — the model's reply
@@ -230,8 +235,7 @@ try await Amba.events.track("app_opened", properties: ["source": "deep_link"])
 
 // AI
 let reply = try await Amba.ai.anthropic.messages.create(
-    promptKey: "summarize",
-    variables: ["text": "A long article..."]
+    request: AiMessageRequest(promptSlug: "summarize", variables: ["text": "A long article..."])
 )
 ```
 
@@ -248,8 +252,7 @@ val showBeta = Amba.flags.get("beta_feature")
 Amba.events.track("app_opened", mapOf("source" to "deep_link"))
 
 val reply = Amba.ai.anthropic.messages.create(
-    promptKey = "summarize",
-    variables = mapOf("text" to "A long article…")
+    AiMessageRequest(promptSlug = "summarize", variables = mapOf("text" to "A long article…"))
 )
 ```
 
@@ -268,7 +271,7 @@ final showBeta = await Amba.flags.get('beta_feature');
 await Amba.events.track('app_opened', {'source': 'deep_link'});
 
 final reply = await Amba.ai.anthropic.messages.create(
-  promptKey: 'summarize',
+  promptSlug: 'summarize',
   variables: {'text': 'A long article…'},
 );
 ```
@@ -333,7 +336,7 @@ Batch.
 2. Before creating:
    - `amba_collections_list` — match on `name`. Collisions: never silently recreate (data loss). Offer `amba_collections_alter` to add new columns instead.
    - `amba_functions_list` — match on `name`. Collisions: ask to redeploy (with the new source) or skip.
-   - `amba_ai_prompts_list` — match on `key`. Same.
+   - `amba_ai_prompts_list` — match on `name`. Same. (And `amba_ai_providers_list` — match on `provider`; re-running `amba_ai_providers_set` rotates the key in place.)
    - `amba_integrations_list` — match on `provider`. Same.
    - `amba_configs_list` — match on `key`. Same.