@layers/amba-mcp 1.0.1 → 4.0.2

package/dist/expo-build-prompt.js

@@ -0,0 +1,641 @@
+//#region src/resources/amba-setup.ts
+/**
+* Canonical long-form Amba setup guide — markdown body.
+*
+* Companion to the short-form `instructions` field served by the MCP
+* server's initialize response. The pointer "Full guide: amba://setup"
+* in those instructions tells the agent to fetch this resource when it
+* needs more detail than the ~1 KB summary provides.
+*
+* Consumed by:
+*
+*   - The MCP resource at `amba://setup`, registered by
+*     `registerAllResources()` in `./index.ts` and exposed by the
+*     hosted MCP server at `mcp.amba.dev`. Any client (Claude Code,
+*     Cursor, Codex, Cowork, etc.) can fetch it via `resources/read`.
+*
+* Twin: this body is the server-side mirror of
+* `packages/cli/skill-bundle/SKILL.md`, which the CLI installs locally
+* during `npx @layers/amba init`. The two surfaces target two
+* different audiences:
+*
+*   - `SKILL.md` ships to a local `.claude/skills/amba/` and assumes
+*     the agent CAN shell out (the bootstrap path can `npx @layers/amba
+*     signup`). It also writes credentials into `.env.local` + `~/.amba/`.
+*   - `AMBA_SETUP_GUIDE_MD` (this constant) is served by the hosted MCP
+*     and assumes the agent CANNOT shell out (e.g. Claude.ai web).
+*     The bootstrap path must therefore use the `amba_developer_signup`
+*     MCP tool (the only pre-auth tool the server registers).
+*
+* The playbook shape (Step 0 → Step 1 classify → Step 2 confirm →
+* Step 3 wire → Step 4 report) is identical between the two, so an
+* agent reading either ends up at the same outcome. A drift gate test
+* in `amba-setup.test.ts` asserts the structural anchors match.
+*
+* Taxonomy: the SDK capability map below is grouped under the canonical
+* 7-category taxonomy (Identity / Engagement / Gamification / Economy /
+* Social / Analytics / Infrastructure) — same shape as `categories.ts`,
+* the marketing-site feature grid, and the docs IA. Drift is caught by
+* `amba-setup.test.ts`.
+*
+* The body is plain CommonMark — no MDX, no JSX — so it renders
+* identically wherever it lands.
+*/
+const AMBA_SETUP_GUIDE_MD = `# Amba
+
+## What Amba is
+
+Amba is the backend your app calls at runtime via the SDK. The MCP tools (\`amba_*\`) are for provisioning at build time — call them as the coding agent.
+
+One Amba project = one isolated tenant database + one set of API keys + a hosted MCP at \`mcp.amba.dev\` for agent-driven provisioning. The runtime traffic goes through an SDK (\`@layers/amba-*\` on npm, \`Amba\` on SPM / Maven / pub.dev). The provisioning traffic — what you're about to do — goes through the tools listed below.
+
+Your job is to take the user from "I have an app" to "Amba is wired in and the features are real" in one pass, without 12 follow-up questions. The journey below is the standard playbook. Don't deviate without a reason.
+
+## Step 0 — Bootstrap credentials
+
+You're in an MCP client (Claude.ai web, Claude Desktop, Cursor, Windsurf, etc.) without a local CLI. The MCP server has one tool that works **without** a Bearer token: \`amba_developer_signup\`. Use it to mint a personal access token (PAT), project, and client/server keys in a single round trip — no browser, no email verification.
+
+Call:
+
+\`\`\`
+amba_developer_signup({
+  email: "sandbox-<unix-seconds>-<6char-nonce>@layers.com",
+  password: "<32 random base64url chars>",
+  name: "amba-sandbox-agent"
+})
+\`\`\`
+
+The response shape:
+
+\`\`\`json
+{
+  "data": {
+    "pat": "amb_dpat_…",
+    "developer": { "id": "…", "email": "…", "tier": "agent_sandbox" },
+    "project": {
+      "project_id": "…",
+      "client_key": "amb_ck_…",
+      "server_key": "amb_sk_…",
+      "provisioning_status": "provisioning",
+      "verify_url": "https://app.amba.dev/verify?token=…",
+      "verify_token": "…"
+    }
+  }
+}
+\`\`\`
+
+After signup, the PAT is in your hand — keep building in THIS session immediately. Pass \`pat: "<the PAT from the response>"\` as an inline argument on every subsequent \`amba_*\` tool call; the inline arg overrides the inbound Bearer for that one call so no client config change is needed mid-session. For future sessions, write the matching snippet from \`mcp_config\` to the customer's MCP-client config file so the static Bearer takes over automatically on the next launch.
+
+The project status is \`"provisioning"\` immediately after signup; the per-tenant DB activates within ~5 seconds. Don't block — your next call may briefly retry, that's fine. If you want to be polite, call \`amba_projects_get_provisioning_status({ project_id })\` once and proceed when it returns \`"active"\` (or after 15s, whichever first).
+
+Tell the user where their credentials live:
+
+- \`pat\` — the Bearer they should configure in this MCP client's settings (and treat like a password).
+- \`project_id\`, \`client_key\` — the values they paste into their app's \`.env.local\` / \`.env\`.
+- \`server_key\` — never ship to user devices; only into a server \`.env\` or a secret manager. The \`amb_dev_sk_\` / \`amb_live_sk_\` prefix is the marker.
+
+**Already have a PAT?** Skip the signup. Call \`amba_developer_me({})\` to verify the Bearer; if it succeeds, either reuse the most recent project (\`amba_projects_list\`) or call \`amba_projects_create({ name: "<app-name>", platform: "all" })\` and then \`amba_api_keys_create\` twice to mint client + server keys for \`environment: "development"\`.
+
+## Step 1 — Classify the app
+
+Look at what the user told you and at any files they shared. You're trying to pick one of ten presets in 30 seconds, not write a treatise. Inputs:
+
+- The user's prompt — "I'm building a fitness tracker" / "a marketplace for…" / "a Duolingo for X".
+- README content if shared.
+- \`package.json\` / \`pubspec.yaml\` / \`build.gradle.kts\` / \`Package.swift\` — framework + dependencies.
+- Screen / view names — \`WorkoutScreen\`, \`MatchView\`, \`LessonPage\`, \`CartView\`, \`ProductDetail\`, \`ChatThread\`.
+
+Pick the closest match:
+
+| Preset | When | Default Amba surfaces |
+| --- | --- | --- |
+| **fitness** | health / fitness tracker (workouts, steps, meditation) | identity (Apple+Google), push, XP, achievements, streaks, leaderboards, content (daily tips) |
+| **social** | social network / community (friends, feeds, groups) | identity, push, friends, groups, feeds, messaging, moderation, content |
+| **marketplace** | commerce / marketplace (catalog, stores, payments) | identity, push, catalog, stores, currencies (loyalty), reviews, segments |
+| **productivity** | productivity / SaaS tool (collaboration, milestones) | identity (Apple+Google+OTP), push, collections, achievements, content (changelog), segments |
+| **education** | education / learning app (courses, progress, rewards) | identity, push, XP, achievements, streaks, leaderboards, content (lessons), onboarding |
+| **game** | game / casual gaming | identity (anon-first), push, XP, achievements, currencies, inventory, leaderboards, challenges, stores |
+| **dating** | dating / matching app | identity (phone-OTP), push, friends (matches), messaging, moderation (heavy), reviews |
+| **content_creator** | content platform (feeds, subscriptions, tips) | identity, push, feeds, content, currencies (tips), referrals, stores (subscriptions) |
+| **ai_chatbot** | AI / chatbot / assistant app | identity, push, AI prompts, currencies (credits), content (system prompts), onboarding |
+| **custom** | none of the above | pick features individually |
+
+Detection heuristics, in priority order:
+
+1. The user's own description — most direct signal.
+2. Filename match in \`screens/\` or \`views/\` (high signal).
+3. Dependency in \`package.json\` — \`react-native-health\` → fitness, \`@stream-io/*\` → social or dating, \`@stripe/*\` → marketplace, \`revenuecat\` → marketplace or content_creator.
+4. README copy — "fitness", "habit", "match", "chat", "store", "subscription".
+
+If two presets tie, pick the one the user's filenames match more closely. If still tied or no signal, fall back to **custom** and let them pick.
+
+## Step 2 — Confirm with the user
+
+Use a single multi-choice. Quote the surfaces from the table above so they know what they're getting.
+
+**Question 1: classification + scope**
+
+> I'm reading this as a **\\{kind\\}** app. I'd wire up: **\\{surfaces\\}**. Sound right?
+>
+> 1. Yes, wire it up as proposed (Recommended)
+> 2. Same kind but I want to pick features individually
+> 3. Wrong kind — let me pick from the list
+> 4. Custom — I'll pick features manually
+
+If the user picks 1, go to Step 3. If 2 or 4, follow up with a multi-select of surfaces. If 3, present the table again and pick a different preset.
+
+**Question 2 (preset-specific):** see the per-surface sub-resources (\`amba://setup/<surface>\`) for the full "Common follow-ups" list. Examples:
+
+- **fitness / game / education** — leaderboard scope? (all-time, weekly, daily, none)
+- **game / content_creator** — virtual currency name? (\`gold\`, \`gems\`, \`coins\`, \`credits\` — defaults to \`coins\`)
+- **content_creator** — monetization? (tips, subscriptions, both)
+- **dating** — phone OTP or email-only? (phone strongly recommended)
+- **ai_chatbot** — daily free credit cap?
+
+Batch the follow-ups into one or two multi-choice rounds. Don't drip-feed six separate questions.
+
+## Step 3 — Wire it up
+
+For each surface in the confirmed set, read the relevant sub-resource and execute its procedure. Each sub-resource is the full per-surface playbook (MCP tools + SDK init per stack + common follow-ups + re-run behavior):
+
+- **identity** (auth, anonymous/Apple/Google/OTP/magic-link, link/unlink) → \`amba://setup/identity\`
+- **engagement** (push, segments, content libraries, onboarding flows, deeplinks, referrals, tracked links) → \`amba://setup/engagement\`
+- **gamification** (XP rules, achievements, streaks, leaderboards, challenges) → \`amba://setup/gamification\`
+- **economy** (currencies, catalog, stores, inventory) → \`amba://setup/economy\`
+- **social** (friends, groups, feeds, messaging, moderation, reviews) → \`amba://setup/social\`
+- **infrastructure** (collections / DB tables, functions, analytics, AI prompts, media, secrets, configs, integrations, sites) → \`amba://setup/infrastructure\`
+
+The general flow for every surface:
+
+1. **Detect stack.** Look at \`package.json\`, \`pubspec.yaml\`, \`build.gradle.kts\`, \`ios/*.xcodeproj\`. The detection rules:
+   - \`pubspec.yaml\` present → Flutter.
+   - \`package.json\` with \`expo\` → Expo.
+   - \`package.json\` with \`react-native\` (no \`expo\`) → bare React Native.
+   - \`package.json\` with \`react\` (no \`react-native\`) → web (or Next.js — same SDK).
+   - \`Package.swift\` or \`*.xcodeproj\` only → iOS Swift.
+   - \`build.gradle.kts\` or \`build.gradle\` with \`com.android.application\` → Android Kotlin.
+   - Multiple (e.g. \`ios/\` + \`android/\` inside an Expo repo) → Expo wins.
+
+2. **Create resources via MCP.** Call the \`amba_<surface>_create\` tools to mint the definitions. Always include \`project_id\` from the project you created in Step 0. Always show the user the tool call before making destructive changes (creating a resource isn't destructive — but creating 30 of them is noisy).
+
+3. **Write SDK init code.** Drop the per-stack snippet (from the sub-resource) into the user's entry file. Detection:
+   - Expo / React Native: \`app/_layout.tsx\`, \`App.tsx\`, \`index.js\` (in that order)
+   - web / Next.js: \`app/layout.tsx\`, \`pages/_app.tsx\`, \`src/main.tsx\`, \`src/App.tsx\`
+   - iOS Swift: \`Sources/<App>/<App>App.swift\`, \`App/AppDelegate.swift\`
+   - Android Kotlin: \`app/src/main/java/.../<App>.kt\` (the \`Application\` subclass — create one if missing)
+   - Flutter: \`lib/main.dart\`
+
+   Always make additive edits — \`await Amba.configure(...)\` next to existing init, not replacing it. Never refactor existing auth or storage code; if the user has Firebase Auth or Supabase, leave it. Amba's auth is opt-in per call.
+
+4. **Run the project's existing test command** to confirm nothing broke. Detection:
+   - \`package.json\` \`scripts.test\` → \`npm test\` (or \`pnpm test\` if \`pnpm-lock.yaml\` present)
+   - \`pubspec.yaml\` → \`flutter test\`
+   - \`build.gradle.kts\` → \`./gradlew test\` (skip on first wire-up — slow)
+   - iOS — skip (need a simulator).
+
+   If tests fail because of your edits, undo the offending edit and surface a clear error. If they fail for unrelated reasons (pre-existing red), note it and proceed.
+
+5. **Verify with the SDK.** Tell the user to call \`Amba.diagnostics.ping()\` (\`Amba.Diagnostics.Ping()\` on Unity) in their entry file. It returns \`{ ok, server_project_id, environment, key_fingerprint, latency_ms }\`. \`ok: true\` with the expected \`server_project_id\` confirms the wiring.
+
+## Step 4 — Report
+
+Tell the user a structured summary. Use this exact shape so they can skim it fast:
+
+\`\`\`
+Amba is wired in. Here's what changed:
+
+DONE
+  - identity: Apple + Google sign-in available; signInAnonymously() called at app start
+  - gamification: 3 achievements, 1 streak, 1 leaderboard created
+    resources: first_workout, week_warrior, century_club / daily_workout / weekly_xp
+  - engagement: push registration wired; default segment "active_users" created
+
+SKIPPED (low signal — re-run with /amba <feature> if you want them)
+  - economy: no in-app currency UI found in your screens
+  - social: no friends/feed surfaces found
+
+NEEDS YOUR INPUT
+  - Apple Sign In: add the "Sign in with Apple" capability in Xcode > Signing & Capabilities.
+  - Google Sign In: paste your Google OAuth client ID into amba_projects_update({ google_oauth_client_id: "..." }).
+  - APNs / FCM: upload credentials in app.amba.dev before push delivers.
+
+NEXT STEPS
+  - Paste AMBA_CLIENT_KEY into your build env (already shown above)
+  - Trigger a workout in your existing flow — watch the achievement unlock + XP land
+  - Open https://app.amba.dev to see users pour in
+\`\`\`
+
+Be specific. List resources by key, not "some achievements". If something needs the user's input (third-party credentials, OAuth client IDs, push certs), say it clearly with the exact next action.
+
+## Stance (read this once)
+
+- **Don't ask which surfaces to use.** Classify, then confirm in one multi-choice. The taxonomy is the whole point.
+- **Default to additive, non-breaking changes.** Don't refactor existing auth, storage, or networking code. Drop in \`await Amba.configure(...)\` next to whatever the user already has.
+- **Never create resources without the user's confirmation in Step 2.** A 3rd-party "convenience" achievement called \`first_login\` is debt.
+- **If something is genuinely ambiguous** (leaderboard scope, currency real-money vs virtual, dating phone vs email), ask via a follow-up multi-choice. Don't guess and don't paragraph-it.
+- **clientKey vs serverKey.** \`AMBA_CLIENT_KEY\` (\`amb_dev_ck_…\` in dev, \`amb_live_ck_…\` in prod) ships to user devices. \`AMBA_SERVER_KEY\` (\`amb_dev_sk_…\` / \`amb_live_sk_…\`) never does — only into server \`.env\` or a secret manager. Mixing them is the #1 security mistake; if you're writing into a file that ships with the app binary, it's the client key, period.
+- **Don't echo the PAT in chat output on every call.** Showing it once after signup is fine; do not repeat it.
+
+## Get credentials (cheat sheet)
+
+- No terminal, in an MCP client: call \`amba_developer_signup\` (no Bearer required) — this guide's Step 0.
+- With a terminal: \`npx -y @layers/amba init\` signs up, mints a project + client/server keys, writes \`.env.local\` + \`AMBA.md\`, installs the \`/amba\` skill, and wires \`mcpServers.amba\` into every detected MCP-client config in one command. Auto-detects non-TTY invocations (the coding-agent bash-tool case) and runs headlessly.
+- Bind the sandbox account to a real email later: \`npx @layers/amba claim me@example.com\`. The backend emails a one-click magic link; clicking it lifts the sandbox cap to the Free tier.
+- Hosted MCP endpoint: \`https://mcp.amba.dev/mcp\` (Streamable HTTP, Bearer auth).
+
+## SDKs
+
+| Stack | Registry | Package |
+|---|---|---|
+| Browser / Node / React / React Native / Expo | npm | \`@layers/amba-{web,node,react,react-native,expo}\` |
+| Swift | SPM | \`https://github.com/layers/amba-sdk-ios\` |
+| Kotlin | Maven Central | \`com.layers.amba:amba-sdk-android\` |
+| Flutter | pub.dev | \`amba\` |
+| Unity | UPM (git) | \`https://github.com/layers/amba-sdk-unity.git\` |
+
+All SDKs expose the same surface: \`Amba.configure({ projectId, apiKey })\`, then \`Amba.events.track(...)\`, \`Amba.users.*\`, \`Amba.collections.*\`, etc. Per-stack quickstart pages with the exact initialization snippet: \`https://docs.amba.dev/sdk/<framework>\`.
+
+## What Amba does
+
+### Identity
+- **users** — app-user registry. Auto-created on first SDK call; admin via \`amba_users_*\`.
+- **roles + permissions** — RBAC. Define with \`amba_roles_create\`; assign via \`amba_roles_assign\`.
+- **api_keys** — client + server keys per project. Mint via \`amba_api_keys_create\`.
+
+### Engagement
+- **onboarding** — multi-step first-run flows. Define with \`amba_onboarding_create\`; SDK \`Amba.onboarding.next()\`.
+- **segments** — user cohorts. Define with \`amba_segments_create\`; used as push/feed targets.
+- **push** — scheduled or triggered notifications. Chain: configure integrations (apns/fcm) → \`amba_push_campaigns_create\` → \`amba_push_campaigns_send\` (or schedule).
+- **referrals** — referral codes. Define with \`amba_referrals_create\`.
+- **deeplinks** — universal links. Set domain with \`amba_deeplinks_set_config\`.
+- **tracked_links** — UTM-tagged outbound links. Define with \`amba_tracked_links_create\`.
+- **content** — episodic delivery (lessons, quotes, daily prompts). Chain: \`amba_content_libraries_create\` → \`amba_content_items_add\` → \`amba_content_schedules_create\`.
+
+### Gamification
+- **xp** — experience points + level. Define rules with \`amba_xp_rules_create\`; SDK \`Amba.xp.getBalance\`.
+- **achievements** — earnable badges. Define with \`amba_achievements_create\`; unlock via xp rules or \`amba_inventory_grant_item\`.
+- **streaks** — recurring engagement counters. Define with \`amba_streaks_create\`; client calls \`Amba.streaks.qualify(key)\`.
+- **leaderboards** — ranked user lists. Define with \`amba_leaderboards_create\`; populated from events.
+- **challenges** — time-bounded goals. Define with \`amba_challenges_create\`; progress via SDK.
+
+### Economy
+- **currencies** — virtual currencies (coins, gems). Define with \`amba_currencies_create\`; grant via \`amba_currencies_grant\` or event rules via \`amba_currency_grant_rules_create\`.
+- **catalog + stores** — purchasable items + storefronts. Chain: \`amba_catalog_items_create\` → \`amba_catalog_items_set_price\` → \`amba_stores_create\` → \`amba_stores_add_listing\`. (Define currency first.)
+- **inventory** — items users own. Read via SDK \`Amba.inventory.*\`; grant with \`amba_inventory_grant_item\`.
+
+### Social
+- **friendships** — friend graph. SDK \`Amba.friends.*\`; admin via \`amba_friendships_*\`.
+- **groups** — guilds/parties/chats. Define with \`amba_groups_create\`; members managed via SDK + admin tools.
+- **messaging** — DMs + group chat. Enabled by default; moderate via \`amba_messaging_*\`.
+- **feeds** — algorithmic activity feeds. Define ranking with \`amba_feeds_rules_create\`.
+- **reviews** — user-submitted reviews. Enabled by default; moderate via \`amba_reviews_*\`.
+- **moderation** — content review queue + trust scores. Configure with \`amba_moderation_configure\`; review via \`amba_moderation_queue_list\`.
+
+### Analytics
+- **events** — track user actions. SDK \`Amba.events.track()\`; query via \`amba_events_count\`.
+- **sessions** — session telemetry. Tracked automatically; query via \`amba_sessions_list\`.
+- **analytics** — funnels + retention. Query via \`amba_analytics_get\`.
+
+### Infrastructure
+- **collections** — your own typed key-value tables. Define with \`amba_collections_create\`; read/write from SDK \`Amba.client.*\`.
+- **functions** — serverless TypeScript handlers. Deploy with \`amba_functions_deploy\`; schedule with \`amba_functions_schedule\`.
+- **sites** — static site hosting at \`*.app.amba.host\`. Deploy with \`amba_sites_deploy\`.
+- **media** — file storage + CDN. Upload via \`amba_media_upload\`.
+- **secrets** — env vars for functions. Set via \`amba_secrets_set\`.
+- **configs** — remote config flags. Define with \`amba_configs_create\`.
+- **integrations** — third-party webhooks (RevenueCat, Superwall, AppsFlyer, etc.). Configure with \`amba_integrations_configure\`.
+- **ai_prompts** — versioned LLM prompts callable from SDK. Define with \`amba_ai_prompts_create\`; call via \`amba_ai_prompts_invoke\`.
+`;
+/** Canonical URI for the MCP resource. */
+const AMBA_SETUP_GUIDE_URI = "amba://setup";
+/** Canonical MIME type for the guide body. */
+const AMBA_SETUP_GUIDE_MIME = "text/markdown";
+/**
+* Body-version marker. Bumped when the canonical body changes shape
+* in a way that downstream agents should re-read. The CLI embeds it
+* into every fan-out file (\`CLAUDE.md\`, \`AGENTS.md\`, etc.) so a
+* re-init can detect stale content. Bumped to \`v2\` when this PR
+* replaced the capability-only guide with the full classify → confirm
+* → wire-up playbook.
+*/
+const AMBA_SETUP_GUIDE_BODY_VERSION = "v2";
+//#endregion
+//#region src/resources/expo-build-prompt.ts
+/**
+* Canonical Amba Expo build prompt — markdown body (no MDX frontmatter).
+*
+* Source of truth for three customer-facing surfaces:
+*
+*   1. The published docs page at
+*      `https://docs.amba.dev/prompts/expo-build` — the MDX file at
+*      `apps/docs/content/docs/prompts/expo-build.mdx` ships the same
+*      body wrapped in fumadocs frontmatter.
+*   2. The MCP resource `amba://prompts/expo-build` registered by
+*      `registerAllResources()` in `./index.ts` and exposed by the
+*      hosted MCP server at `mcp.amba.dev`.
+*   3. The inlined snapshot baked into the `/amba-build` Claude Code
+*      skill by `amba init --sandbox` (see `packages/cli/src/skills.ts`).
+*
+* Drift between this constant and the MDX file is caught by
+* `expo-build-prompt.test.ts` — that test reads the MDX from disk,
+* strips the YAML frontmatter, and asserts it equals `EXPO_BUILD_PROMPT_MD`.
+*
+* **Update protocol:** edit the MDX (it's the human-facing surface;
+* it renders on docs.amba.dev). Re-run the drift test. The test will
+* fail with a diff. Apply the same diff here. The two are kept in
+* sync by hand because the MDX must be statically parseable for
+* fumadocs + we can't import `.md` files as raw strings without a
+* build-step that pulls in extra config.
+*
+* The body itself is plain CommonMark — no MDX components, no JSX —
+* so it renders identically as `.md` (the MCP / skill consumers) and
+* as `.mdx` (the docs site).
+*/
+const EXPO_BUILD_PROMPT_MD = `> **Last reviewed:** 2026-05-17. The canonical version of this page lives
+> at [docs.amba.dev/prompts/expo-build](https://docs.amba.dev/prompts/expo-build).
+> If you're reading an inlined snapshot from your
+> \`.claude/skills/amba-build/SKILL.md\`, check the URL above for updates.
+
+This is the prompt an AI coding agent runs to build a full Expo app
+where Amba is the only backend. It's structured as a single \`/goal\`
+directive — paste it, replace \`<DESIGN_HASH>\` with whatever describes
+your design (a URL, a description, a Figma link), and let the agent
+execute.
+
+## Quick setup
+
+The CLI handles signup, project provisioning, env-file writes, and MCP
+client config wiring in one command:
+
+\`\`\`bash
+npx -y @layers/amba init
+\`\`\`
+
+That's the entire setup. The CLI:
+
+1. Signs up an agent-mode developer account (no browser, no email
+   verification needed for sandbox).
+2. Creates an Amba project and mints a client key + admin PAT.
+3. Writes \`.env.local\` (\`AMBA_PROJECT_ID\`, \`AMBA_CLIENT_KEY\`,
+   \`AMBA_API_URL\`).
+4. Writes \`AMBA.md\` (project-scoped context for the agent).
+5. Auto-wires \`mcpServers.amba\` into every MCP client config it
+   detects on disk — Claude Code, Cursor, Windsurf.
+6. Verifies the PAT against the API and confirms it's good.
+
+The Amba MCP toolset (\`amba_*\` tools — ~130 of them) is available to
+the agent immediately: pass the freshly-minted \`pat\` as an inline
+argument on every \`amba_*\` call in the current session. The next time
+your MCP client starts it picks the PAT up from the config as the
+inbound Bearer automatically — at that point the \`pat\` arg becomes
+optional. No restart needed; nothing for you to do.
+
+If you have the \`/amba-build\` skill installed (via
+\`npx -y @layers/amba init\`), invoke it directly:
+
+\`\`\`
+/amba-build <DESIGN_HASH>
+\`\`\`
+
+Otherwise paste the prompt below.
+
+## Current known gotchas
+
+Three remaining wrinkles you may hit. Everything else from the 2026-05
+DX cascade is fixed.
+
+- **Web CORS** — the public API does not currently send
+  \`Access-Control-Allow-Origin\` for browser-origin requests. Use the
+  agent's circuit-break-on-second-failure rule for web targets; for
+  Expo (iOS + Android) you'll never see this.
+- **React Native bundle size** — the React Native SDK adds ~4 MB to
+  the JS bundle today. Functional, just heavier than the long-term
+  goal. Tracked separately.
+- **Sandbox MAU cap (100)** — the agent-mode sandbox tier caps at 100
+  monthly active users. If you blow through it during testing, call
+  \`amba_users_reset_sandbox\` to clear the counter — that tool exists
+  specifically for this. Upgrade to the Free tier (1,000 MAU, 500 MB
+  DB) by running \`amba claim me@example.com\` from the terminal — the
+  backend emails a one-click magic link to the address you pass in;
+  clicking it binds the account to that email and lifts the cap.
+
+## How to read the design
+
+If \`<DESIGN_HASH>\` is a URL to a packaged design (e.g. a download
+link from your design tool of choice), unpack it before you start:
+
+\`\`\`bash
+mkdir -p design && cd design
+curl -L "<DESIGN_HASH>" -o design.tar.gz
+gunzip -c design.tar.gz | tar -x
+ls
+# Expected: README, chats/, project/ (or equivalent)
+\`\`\`
+
+Read the README first — it should tell you what each subdirectory
+holds. The \`chats/\` directory typically contains conversation logs
+that capture the design intent in dialog form; treat them as the
+authoritative source for tone and feature priorities. The \`project/\`
+directory holds the structured asset graph (screens, components,
+styles).
+
+If \`<DESIGN_HASH>\` is a freeform description (not a URL), skip the
+unpacking and treat the description text as the design brief.
+
+## Use Amba for everything
+
+The rule: any feature that touches data, identity, scheduling,
+notifications, content, or social — use Amba. Don't reach for
+AsyncStorage-as-database, don't bring in Firebase / Supabase / your
+own server, don't roll a custom auth layer. The point of this build
+is that Amba covers it all.
+
+Specifically: every feature in the design that needs a backend maps
+to an Amba primitive. If you can't find a fit, the rule is **escalate
+in the gaps log** (see the verification gate), not "ship without
+Amba." Skipping a primitive needs a written justification — the
+verification gate enforces this.
+
+## Feature → Amba primitive map
+
+| App feature                                        | Amba primitive                          | MCP tools                                                                                                                                                                           |
+| -------------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| User accounts (anonymous + Apple + Google + email) | Auth                                    | \`amba_developer_signup\` (one-time bootstrap), \`Amba.signIn()\` SDK calls                                                                                                             |
+| Profile data (name, avatar, prefs)                 | App users                               | \`amba_users_list\`, \`amba_users_get\`, \`amba_users_bulk_update\`                                                                                                                       |
+| Daily content (tips, lessons, quotes)              | Content libraries + schedules           | \`amba_content_libraries_create\`, \`amba_content_items_add\`, \`amba_content_schedules_create\`, \`amba_content_list_libraries\`, \`amba_content_list_items\`, \`amba_content_list_schedules\` |
+| Push notifications                                 | Push campaigns                          | \`amba_push_campaigns_create\`, \`amba_push_campaigns_send\`, \`amba_push_send_test\`, \`amba_push_list_campaigns\`                                                                         |
+| User segments (e.g. inactive 7d, premium)          | Segments                                | \`amba_segments_create\`, \`amba_segments_list\`, \`amba_segments_evaluate\`                                                                                                              |
+| Daily streaks                                      | Streaks                                 | \`amba_streaks_create\`, \`amba_streaks_list\` (call \`streaks.qualify()\` from the SDK to record activity)                                                                               |
+| XP and levels                                      | XP rules                                | \`amba_xp_rules_create\`, \`amba_xp_rules_list\`, \`amba_users_get_xp\`                                                                                                                   |
+| Achievements / badges                              | Achievements                            | \`amba_achievements_create\`, \`amba_achievements_list\`, \`amba_achievements_get\`                                                                                                       |
+| Challenges (time-limited goals)                    | Challenges                              | \`amba_challenges_create\`, \`amba_challenges_list\`, \`amba_challenges_list_participants\`                                                                                               |
+| Leaderboards                                       | Leaderboards                            | \`amba_leaderboards_create\`, \`amba_leaderboards_list\`, \`amba_leaderboards_get\`                                                                                                       |
+| In-app currency / virtual goods                    | Economy (currencies + catalog + stores) | \`amba_currencies_create\`, \`amba_catalog_items_create\`, \`amba_stores_create\`, \`amba_currencies_grant\`, \`amba_users_get_inventory\`                                                    |
+| Social (friends, groups, feed, DMs)                | Social primitives                       | \`amba_create_group\`, \`amba_groups_list\`, \`amba_groups_update_member\`, \`amba_friendships_list\` (feeds + messaging via SDK: \`Amba.feeds.*\`, \`Amba.messaging.*\`)                       |
+| Remote feature flags / config                      | Configs                                 | \`amba_configs_create\`, \`amba_configs_list\`, \`amba_configs_update\`                                                                                                                   |
+| Entitlements (premium / paywall)                   | RevenueCat / Superwall integration      | \`amba_integrations_configure\`, \`amba_integrations_test\`                                                                                                                             |
+| Custom data (anything not above)                   | Collections                             | \`amba_collections_create\`, \`amba_collections_alter\`, \`amba_collections_list\`, \`amba_admin_insert_row\`, \`amba_admin_list_rows\`, plus client-side \`Amba.collections.*\`                |
+| Analytics / event tracking                         | Events                                  | \`Amba.events.track(...)\` from the SDK; query with \`amba_analytics_get\`, \`amba_users_list_events\`                                                                                    |
+
+Every primitive above has list / read MCP tools you can use to verify
+seed data after creation — the verification gate uses these to catch
+"fake implementation" failure modes (where the app code thinks a thing
+was created but nothing actually landed in the backend).
+
+## Seed data
+
+Before writing app code, seed the backend with enough data that every
+screen in the design has something realistic to render. Order:
+
+1. **Configs** — feature flags + tunable constants the app reads at
+   boot (\`amba_configs_create\`).
+2. **Segments** — at least one (e.g. "new_user", first 7 days) so
+   targeting works downstream.
+3. **Content libraries + schedules** — daily content for any
+   tips/quotes/lessons screen. Seed ≥30 items so the carousel /
+   day-stepper doesn't loop visibly.
+4. **Streaks** — define the streak shape (daily / weekly, grace
+   window, freeze policy).
+5. **XP rules** — events → XP-award rules so XP accrues from real
+   gameplay.
+6. **Achievements** — unlock criteria for badges.
+7. **Challenges** — at least one active challenge with rewards.
+8. **Leaderboards** — XP, streaks, or any custom metric.
+9. **Currencies + catalog + stores** — virtual currency, catalog
+   items, store listings (only if the design has an economy screen).
+10. **Collections** — schemas + sample rows for any custom data the
+    app needs (e.g. user-generated content, journal entries, custom
+    list items).
+11. **Push campaigns** — at least one welcome push + one re-engagement
+    push targeting your "new_user" segment.
+
+After seeding, the verification gate (below) confirms each primitive
+exists by calling the matching \`amba_*_list\` MCP tool. Empty list →
+failure.
+
+## Engineering rules
+
+These are non-negotiable. Violating any one of them fails the build
+gate.
+
+- **Expo Router with typed routes.** Use \`expo-router\` and enable
+  \`experiments.typedRoutes\` in \`app.json\`. Every screen is a
+  filesystem route; no manual navigation stacks.
+- **TypeScript strict mode.** \`strict: true\` in \`tsconfig.json\`. Zero
+  \`any\`. Zero \`@ts-ignore\`. \`tsc --noEmit\` must pass.
+- **React Native primitives only.** \`View\`, \`Text\`, \`Pressable\`,
+  \`ScrollView\`, \`FlatList\`, \`Image\`. No \`div\`, no \`span\`, no DOM-only
+  libs. The build target is iOS + Android + Web — every screen has to
+  render on all three.
+- **Fonts via expo-font.** Don't ship system-font-only screens; load
+  the design's typography via \`useFonts\` and gate the splash screen
+  on load.
+- **Persistence via AsyncStorage.** Anything you cache client-side
+  (theme choice, last-viewed-item, dismissed banners) goes in
+  AsyncStorage. Never sprinkle direct file I/O.
+- **Theme system.** A single \`theme.ts\` exports light + dark token
+  maps; consume via a \`useTheme()\` hook. The verification gate
+  toggles light ↔ dark and screenshots; if any screen has hardcoded
+  colors that don't flip, the gate fails.
+- **Circuit-break on second failure.** If two consecutive Amba API
+  calls fail with the same error, stop retrying and surface a clean
+  empty-state to the user. Don't loop forever; don't crash. The web
+  CORS issue (above) is the most likely trigger.
+- **Deterministic offline fallback.** When \`fetch\` fails (airplane
+  mode, network drop), the app renders **deterministic** placeholder
+  content — same content per \`userId + day\` — never random. Real data
+  swaps in when the network returns.
+- **Three-platform bundle gate.** \`expo export --platform web\`,
+  \`expo export --platform ios\`, and \`expo export --platform android\`
+  must all succeed. If any one fails, the build fails. No
+  "shipped iOS-only, web is broken" — the rule is parity.
+- **Don't name a tab \`settings.tsx\`.** Use \`account.tsx\` or
+  \`preferences.tsx\` instead. Expo Router's static web export generates
+  \`settings.html\` correctly but does not resolve direct URL navigation
+  to \`/settings\` — the client-side router shows an unmatched-route
+  error while other tab names work fine. (Observed in dogfood; upstream
+  behavior, not an Amba issue.)
+
+## Verification gate
+
+Before declaring the build done, run every check in this list. Any
+failure means the build is not done — fix and re-run.
+
+\`\`\`bash
+# Type-check
+pnpm tsc --noEmit
+
+# Three-platform export
+pnpm expo export --platform web
+pnpm expo export --platform ios
+pnpm expo export --platform android
+\`\`\`
+
+Then, from inside the agent (use the Amba MCP tools):
+
+- \`amba_analytics_get\` → at least one event tracked end-to-end
+  through \`Amba.events.track()\` from the app.
+- \`amba_users_list\` → at least one user exists (the agent's own
+  anonymous signin counts).
+- For every primitive the seed step created, call the matching
+  \`amba_*_list\` and assert non-empty:
+  - \`amba_configs_list\`
+  - \`amba_segments_list\`
+  - \`amba_content_list_libraries\`, \`amba_content_list_items\`,
+    \`amba_content_list_schedules\`
+  - \`amba_streaks_list\`
+  - \`amba_xp_rules_list\`
+  - \`amba_achievements_list\`
+  - \`amba_challenges_list\`
+  - \`amba_leaderboards_list\`
+  - \`amba_currencies_list\` (if economy seeded)
+  - \`amba_catalog_list\` (if catalog seeded)
+  - \`amba_collections_list\` + \`amba_admin_list_rows\` per collection
+  - \`amba_push_list_campaigns\`
+- Empty list for any seeded primitive → the implementation is fake
+  (UI exists but never wrote to the backend). Failure.
+- Manually walk every route in the browser (\`expo start --web\`),
+  screenshot each, and confirm:
+  - Light theme renders cleanly.
+  - Dark theme renders cleanly (toggle and re-screenshot every
+    route).
+  - Empty states render when collections are empty (fresh-install
+    simulation: wipe AsyncStorage, reload).
+- \`amba_users_reset_sandbox\` to confirm you can recover from the MAU
+  cap if you blew past 50 during testing.
+
+Skipping any primitive's seed step requires a one-line written
+justification in the gaps log (next section). "We don't need
+streaks" is fine; silence is not.
+
+## Final output
+
+When done, write a final report to \`BUILD_REPORT.md\` in the project
+root. Required sections:
+
+- **Start timestamp** (when the agent started).
+- **End timestamp** (when the verification gate last passed).
+- **MCP call inventory** — every \`amba_*\` tool you invoked, with a
+  count. Lets a human reviewer audit "did this agent actually use
+  Amba for X" at a glance.
+- **Primitive coverage table** — one row per primitive from the
+  Feature → Amba primitive map. Mark each ✅ (used), ⚠️ (used with
+  caveats — explain), or ⏭ (skipped — justify in one line).
+- **Gaps log** — every primitive you skipped, every feature you
+  couldn't fit cleanly to an Amba primitive, every workaround. One
+  line per gap, no marketing language.
+- **\`seed-report.json\`** — machine-readable seed summary:
+  \`{ "primitive": "<name>", "created": <count>, "listed": <count> }\`
+  for every primitive. The \`listed\` count comes from the
+  \`amba_*_list\` call in the verification gate. \`created ===
+listed\` for every row is the success condition.
+
+If \`BUILD_REPORT.md\` is missing any required section, or
+\`seed-report.json\` is missing, the build is not done.
+`;
+/** Canonical URI for the MCP resource. */
+const EXPO_BUILD_PROMPT_URI = "amba://prompts/expo-build";
+/** Canonical MIME type for the prompt body. */
+const EXPO_BUILD_PROMPT_MIME = "text/markdown";
+//#endregion
+export { AMBA_SETUP_GUIDE_MD as a, AMBA_SETUP_GUIDE_BODY_VERSION as i, EXPO_BUILD_PROMPT_MIME as n, AMBA_SETUP_GUIDE_MIME as o, EXPO_BUILD_PROMPT_URI as r, AMBA_SETUP_GUIDE_URI as s, EXPO_BUILD_PROMPT_MD as t };

package/dist/index.d.ts

@@ -16,6 +16,10 @@
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ApiClient } from './api-client.js';
+export { registerAllResources } from './resources/index.js';
+export { EXPO_BUILD_PROMPT_MD, EXPO_BUILD_PROMPT_MIME, EXPO_BUILD_PROMPT_URI, AMBA_SETUP_GUIDE_MD, AMBA_SETUP_GUIDE_MIME, AMBA_SETUP_GUIDE_URI, AMBA_SETUP_GUIDE_BODY_VERSION, AMBA_SETUP_IDENTITY_MD, AMBA_SETUP_IDENTITY_MIME, AMBA_SETUP_IDENTITY_URI, AMBA_SETUP_ENGAGEMENT_MD, AMBA_SETUP_ENGAGEMENT_MIME, AMBA_SETUP_ENGAGEMENT_URI, AMBA_SETUP_GAMIFICATION_MD, AMBA_SETUP_GAMIFICATION_MIME, AMBA_SETUP_GAMIFICATION_URI, AMBA_SETUP_ECONOMY_MD, AMBA_SETUP_ECONOMY_MIME, AMBA_SETUP_ECONOMY_URI, AMBA_SETUP_SOCIAL_MD, AMBA_SETUP_SOCIAL_MIME, AMBA_SETUP_SOCIAL_URI, AMBA_SETUP_INFRASTRUCTURE_MD, AMBA_SETUP_INFRASTRUCTURE_MIME, AMBA_SETUP_INFRASTRUCTURE_URI, AMBA_SETUP_SUB_RESOURCES, } from './resources/index.js';
+export { CATEGORY_META, CATEGORY_ORDER, TOOL_CATEGORY, getToolCategory } from './categories.js';
+export type { AmbaCategory } from './categories.js';
 /**
  * Register every Amba MCP tool group against the given server, using the
  * given API client. A single `McpServer` instance should only have this