@ambasada/cli 0.8.5 → 0.8.6

package/dist/ambasada.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // <define:__AMBASADA_TEMPLATES__>
-var define_AMBASADA_TEMPLATES_default = { next: { ".claude/skills/ambasada-product/SKILL.md": "---\nname: ambasada-product\ndescription: Build an app on Ambasada and put it online. Use when the user wants to make an app, tool, game or website, start one with `npm create ambasada@latest`, run it with `ambasada dev`, publish it with `ambasada deploy` at <slug>.ambasada.dev, show it in the Ambasada app (mini app, notifications, sign-in), store data in the app's SQLite database, KV or file storage, make it realtime with Durable Objects or an agent (Agents SDK), bring a site built in ChatGPT, Lovable, Bolt or v0, or upgrade a project made with an older CLI (`ambasada upgrade`). Default stack: Next.js on Cloudflare.\n---\n\n# Build an app on Ambasada and put it online\n\nAn app is **one website** (one Cloudflare Worker) at `https://<your-slug>.ambasada.dev`. It comes with\nSign in with Ambasada (Ambasada ID), a SQLite database, key-value, file storage and Durable Objects for\nrealtime. If you want, it also gets a mini app inside the Ambasada app, with push notifications (off by default). No servers, no\nCloudflare account, no keys to configure.\n\n## Start\n\n```sh\nnpm create ambasada@latest my-app           # Next.js (default)\ncd my-app && npm install\nnpx ambasada dev                            # the mock API + your site, no login\n```\n\nOther templates: add `-- --template spa` (Vite + React; for code exported from Lovable or Bolt) or\n`-- --template worker` (plain HTML + small fetch handlers; the smallest possible app). All three have the\nsame `ambasada.config.ts`, sign-in routes, notifications webhook and storage helpers, and a notes example.\n\n## What to read\n\n| The user wants to\u2026 | Read |\n|---|---|\n| know where files go, what Next.js features are allowed, secrets, who is signed in | [reference/stack.md](reference/stack.md) |\n| store data (tables, migrations), sessions or caches, uploads; make it live between people (chat, presence, a shared board, counters); build an AI agent | [reference/storage.md](reference/storage.md) |\n| run it locally, put it online, use their own Cloudflare account | [reference/dev-and-deploy.md](reference/dev-and-deploy.md) |\n| make it look good and easy to use | [reference/design.md](reference/design.md) |\n| show up in the Ambasada app (optional: `npx ambasada miniapp enable`), send push notifications, sign people in inside the app | [reference/mini-app.md](reference/mini-app.md) |\n| build in ChatGPT, Lovable, Bolt or v0 and bring it here | [reference/build-elsewhere.md](reference/build-elsewhere.md) |\n| upgrade a project made with an older CLI | [reference/upgrading.md](reference/upgrading.md) |\n\nFor the Hack A Ton (TON payments, offerings, the agent that runs a shop): `npx ambasada add village`, then\nthe **ambasada-village** skill.\n\n## Rules (break one and the app does not work)\n\n1. **One app = one Worker.** No separate backend, no Docker. State lives in the app's SQLite (`env.DB`),\n   key-value (`env.KV`), file storage (`env.FILES`) or a Durable Object, never in module variables.\n   See [reference/storage.md](reference/storage.md).\n2. **Only the allowed Next.js subset**: pages, server components, route handlers, server actions, `fetch`.\n   No `next/image` default loader, no ISR/`revalidate`, no `fs`/`child_process`/native packages, no custom\n   server, no `middleware.ts`/`proxy.ts`, no `runtime = \"edge\"`. See [reference/stack.md](reference/stack.md#nextjs-allowed-and-banned).\n3. **Keys never reach the browser.** They live in `.env` locally and `ambasada env set` online; only server\n   code reads them. Never prefix one with `NEXT_PUBLIC_`.\n4. **Sign-in is Ambasada ID.** Use the template's `/api/auth/*` routes and `auth.user(req)`; don't add\n   Clerk, Auth.js or Supabase Auth, and don't build an accounts table. Key per-person data by `user.id`.\n5. **Tables change through migrations**: a new `db/migrations/NNNN_name.sql` per change, never edits to an\n   applied one; `npx ambasada db migrate` after deploying.\n\n## When the user is not a developer\n\nDo the work; don't ask them to edit code. Ask at most: what it does and for whom. Then build one page, run\n`npx ambasada dev`, open it, use it as the fake visitor, and show them it worked. Explain in one sentence\nper step, no jargon.\n", ".claude/skills/ambasada-product/reference/build-elsewhere.md": "# Built in ChatGPT, Lovable, Bolt or v0\n\nThree ways, easiest first.\n\n## A. Keep it hosted there, link it\n\nGood for: a site that is finished where it is and only needs to show up in the Ambasada app.\n\n1. On a laptop with Node 22+, once:\n\n   ```sh\n   npm create ambasada@latest my-app -- --miniapp --entry /   # its ambasada.config.ts and the manifest\n   cd my-app && npm install\n   npx ambasada login\n   npx ambasada link https://YOUR-SITE\n   ```\n\n2. The site must serve `/.well-known/ambasada.json` and `/icon.png` (copy them from the new project's\n   `public/`; `npx ambasada dev` writes the manifest there) and pass `npx ambasada check https://YOUR-SITE`\n   ([mini-app.md](mini-app.md)).\n\nLimit: Sign in with Ambasada, notifications and the app's database, KV and files come with hosting on\nambasada.dev. A site hosted elsewhere keeps its own backend; use B or C to get them.\n\n## B. Bring the code home (recommended for Lovable and Bolt)\n\nGood for: anything with real work behind it. You get hosting on ambasada.dev and the full rules.\n\n1. Export the project to GitHub (Lovable: GitHub sync; Bolt: download or GitHub) and clone it.\n2. `npm create ambasada@latest my-app -- --template spa` and copy the exported `src/` (components, pages,\n   styles) into the new project's `src/`, replacing the starter UI. Keep the template's `api/`, `lib/`,\n   `db/`, `ambasada.config.ts`, `wrangler.jsonc` and `vite.config.ts`.\n3. Open the project in Claude Code, Cursor or Codex and say:\n\n   > This is an Ambasada app (see .claude/skills/ambasada-product). Replace Supabase/Firebase with the\n   > app's env.DB (tables in db/migrations), env.KV and env.FILES, and any login with Sign in with Ambasada\n   > (api/auth.ts, /api/auth/me). Then run it with `npx ambasada dev`.\n\n4. `npx ambasada dev`, try it, then `npx ambasada deploy`.\n\n## C. ChatGPT (or any chat) writes the code, you paste it\n\n1. `npm create ambasada@latest my-app`, `cd my-app && npm install`, `npx ambasada dev`.\n2. Paste this into ChatGPT, then the files it mentions, then your idea:\n\n   > I have a Next.js 16 App Router project that runs on Cloudflare Workers (OpenNext). Rules: no `fs`, no\n   > native packages, no `next/image` (use `<img>`), no middleware, no `revalidate`, no other login than the\n   > one in `app/api/auth`. Data goes in SQLite through `lib/db.ts` (tables in `db/migrations/*.sql`), the\n   > signed-in person comes from `currentUser()` in `lib/ambasada.ts`. Below are my `app/page.tsx`,\n   > `app/api/notes/route.ts` and `db/migrations/0001_init.sql`. Rewrite them for my idea: the main action\n   > visible on a phone without scrolling. Write complete files, one code block per file, with the file path\n   > above each. My idea: \u2026\n\n3. Paste each file where ChatGPT says, keep `npx ambasada dev` running, check the page. New tables: a new\n   file in `db/migrations/` (never edit an applied one). When it works: `npx ambasada deploy` and\n   `npx ambasada db migrate`.\n\nUse ChatGPT to write files, not to decide the stack: if its answer adds Prisma, Supabase, NextAuth,\n`next/image` or a `middleware.ts`, tell it \"that's banned in my project, do it without\".\n", ".claude/skills/ambasada-product/reference/design.md": '# Design for people who decide in 10 seconds\n\nPeople open your app on a phone, often inside the Ambasada app, between two other things. They decide in\nseconds whether it is for them. Build for that.\n\n## One page, one action\n\n- **One page first.** What it is, and the one thing to do, fit on the first screen of a phone (375 \xD7 667).\n  Extra pages only when the action needs them.\n- **One action.** One button that does the main thing. Add a second only after people use the first.\n- **Few words.** A headline of up to 8 words, one sentence under it, the button. Cut every adjective you can.\n- **Show the result.** One example of what people get (an image, a sample text) beats any description.\n- **No walls.** No signup before the first use, no cookie banner, no tour. Ask for sign-in when the app\n  needs to remember someone (Sign in with Ambasada is one tap inside the Ambasada app).\n\n## The button\n\n- Label it with the action: **Make my poem**, not **Submit**.\n- Big (at least 48 px tall), full width on phones, one strong colour, nothing else in that colour.\n- If people must type something first, put that one field right above the button.\n- After the action, show the result, or "Working on it\u2026" and the result appearing when ready (a live room\n  or polling). Never a blank page.\n\n## Look\n\n- The templates use `@ambasada/ui` (the Ambasada app\'s look: tokens, `ui-card`, `ui-button`); start there\n  ([mini-app.md](mini-app.md)). Otherwise plain CSS: one font, two colours plus grey, generous spacing.\n- Large text: 18 px body on phones, a headline twice that. Light theme.\n- Works with one thumb: tap targets 48 px, no hover-only menus.\n- Loads fast: no video backgrounds, no 3 MB hero images, no animation libraries.\n\n## Words\n\n- Say what they get, not how it works. "A logo in 1 minute", not "AI-powered logo generation".\n- Write in the language of your users; one is fine.\n\n## Before and after\n\n```\nBad:  Welcome to PoemForge\u2122, the next-generation AI-powered creative writing platform\n      [Features] [Pricing] [About] [Sign up]   \u2026scroll\u2026   [Get started]\n\nGood: Your name as a folk poem\n      Type a name. Get a 4-line Romanian folk poem in 10 seconds.\n      [ Name: _________ ]\n      [   Make my poem   ]\n      "Ana, floare de la munte, / \u2026"  \u2190 one real example\n```\n', ".claude/skills/ambasada-product/reference/dev-and-deploy.md": "# Run it, put it online\n\n## `ambasada dev`: everything on your laptop\n\n```sh\nnpx ambasada dev\n```\n\nStarts two things:\n\n1. a **mock Ambasada API** on `http://127.0.0.1:8788`: same routes and signatures as the real one. Sign in\n   with Ambasada signs you in as \"Fake Visitor\"; `apps.notify` lands in a fake hub; `ambasada.store` and\n   `ambasada.files` work in memory. Open it in a browser for a page with what happened.\n2. **your site** with its normal dev server (`next dev`, `vite` or `wrangler dev`), pointed at the mock.\n\nNo login. The app's database, KV, files and Durable Objects run locally too (wrangler, `.wrangler/state`);\n`ambasada dev` applies `db/migrations/` to the local database before it starts the site.\n\nTry it: open your site, sign in, add a note. With the mini app on, `http://localhost:3000/app?ambasada_shell=mock`\n(your `miniapp.entry`) pretends to be inside the Ambasada app (host bar insets, silent sign-in).\n\n`npx ambasada dev --mock-only` starts only the mock, if you run your site yourself. The mock's keys:\n`AMBASADA_API_URL=http://127.0.0.1:8788`, `AMBASADA_API_KEY=sk_test_dev` (already in the project's `.env`).\n\n## `ambasada deploy`: online at `<slug>.ambasada.dev`\n\nOnce, in the app's folder:\n\n```sh\nnpx ambasada login        # opens a page: sign in with Ambasada ID\n```\n\n(If it asks for a key instead: https://developer.ambasada.dev \u2192 your app \u2192 a project key, `vk_\u2026`.)\nEach app's key is kept under its id: with two apps on one laptop, log in once in each folder, and each folder uses\nits own. `deploy`, `db`/`kv`/`files`, `env`, `logs`, `tunnel` and the village's commands that change something refuse\na key of another app than the folder's `id` (\"this folder is X, you are logged in as Y\"); `--company Y` goes ahead.\n\nThen, every time you want the new version online:\n\n```sh\nnpx ambasada deploy\n```\n\nIt does, in order:\n\n1. **build**: `opennextjs-cloudflare build` (Next), `vite build` (spa) or a bundle of the Worker (worker);\n2. **smoke test**: runs the built Worker locally in workerd and requests `/` and `/.well-known/ambasada.json`\n   (written from `ambasada.config.ts` first, when the mini app is on: [mini-app.md](mini-app.md));\n   a crash stops the deploy (skip with `--no-smoke` only if you know why it fails);\n3. **upload**: the URL is `https://<your-slug>.ambasada.dev`, with `AMBASADA_API_KEY`, `AMBASADA_API_URL`,\n   Sign in with Ambasada and the app secret set for you, and the app's own database, KV namespace and bucket\n   bound as `DB`, `KV`, `FILES` (created on the first deploy) plus the Durable Objects from `wrangler.jsonc`.\n\nThe database's tables are not created by the deploy: run `npx ambasada db migrate` (it applies the new files\nin `db/migrations/`). No Cloudflare account needed. `--dry-run` builds and prints what it would upload.\n\nYour own secrets (an API key for another service): `npx ambasada env set NAME value` (live within about 30 s, and on\nevery deploy); `npx ambasada env list` shows the names.\n\nLimits: 10 MB compressed bundle, 1000 static files, short CPU time per request (waiting on `fetch` does not\ncount). Heavy work belongs in an API you call, or a Durable Object, not in one request.\n\n## `ambasada dev --tunnel`: your laptop, live\n\nWhen the Ambasada app, sign-in or webhooks need to reach the version on your laptop (before deploying, or to\ndebug), log in once, then:\n\n```sh\nnpx ambasada dev --tunnel         # your dev server, against the real API, at https://<slug>-dev.ambasada.dev\nnpx ambasada tunnel --port 5173   # or: only the tunnel, for a server you started yourself\n```\n\nUntil Ctrl+C, `https://<slug>-dev.ambasada.dev` is your app's URL. There is no mock in this mode. The first\ntime takes up to 2 minutes while the address is published; after that it is instant. Only one terminal per\napp at a time: `--force` takes it over. More: docs/TUNNEL.md.\n\n## `ambasada deploy --own`: your own Cloudflare account\n\nRuns `wrangler deploy` into your account (you need `npx wrangler login` first), then\n`ambasada link <your workers.dev URL>`. Set the secrets yourself: `npx wrangler secret put AMBASADA_API_KEY`.\n\n## `ambasada link`: the app is hosted somewhere else\n\n```sh\nnpx ambasada link https://my-thing.lovable.app\n```\n\nSets `product.url` in `ambasada.config.ts` and checks that `<url>/health` answers. Use it for Lovable, Bolt,\nv0, Vercel, your own server. See [build-elsewhere.md](build-elsewhere.md).\n\n## Watch it run\n\n```sh\nnpx ambasada logs --follow     # the last deploy and new errors\nnpx ambasada check https://<slug>.ambasada.dev   # https, no redirects, speed; the mini-app rules when it is on\n```\n\nThe Developer app (https://developer.ambasada.dev) has deploys, errors, users and the storage tabs.\n\n## Upgrading\n\nA new devkit: `npx ambasada upgrade` (dependencies, skills, mechanical code changes), then\n[upgrading.md](upgrading.md) for the steps a coding agent does.\n\n## When it goes wrong\n\n| Symptom | Fix |\n|---|---|\n| build fails on `fs`, `child_process`, a `.node` file, `sharp` | a banned package: see [stack.md](stack.md#nextjs-allowed-and-banned) |\n| smoke test: `/` answers 500 | open `npx ambasada dev`, load `/`, read the terminal error |\n| `no such table: \u2026` online | `npx ambasada db migrate` |\n| a Durable Object migration is refused on deploy | never edit or remove a deployed tag in `wrangler.jsonc`'s `migrations`; add the next one ([storage.md](storage.md)) |\n| `CONFIG: no API key` | missing `AMBASADA_API_KEY`: `.env` locally, `ambasada login` before deploying |\n| sign-in loops back to the login page | `PUBLIC_URL` differs from the URL in the browser; remove it or fix it |\n| `this app uses the village \u2026 not installed` | a Hack A Ton project: `npx ambasada upgrade` (adds `@ambasada/village`) |\n", ".claude/skills/ambasada-product/reference/mini-app.md": '# The app inside the Ambasada app (mini app)\n\n**Optional, opt in with `npx ambasada miniapp enable`** (or `npm create ambasada@latest my-app -- --miniapp`). An app\nis a website first; most stay that way. The mini app is one more surface of it, at a path: what the Ambasada mobile\napp opens, with silent sign-in and push notifications. Platform spec: docs/MINI-APPS.md (\xA715, decision 15.6).\n\n## Turn it on\n\n```sh\nnpx ambasada miniapp enable              # at /app; --entry /in-app for another path, --entry / for the whole site\nnpx ambasada miniapp                     # on or off, and the entry\nnpx ambasada miniapp enable --entry /app --force   # move it: --force removes what the old entry left (it lists them otherwise)\n```\n\nIt adds:\n\n| | |\n|---|---|\n| `miniapp: { entry: "/app", age_rating: "4+", kind: "tool" }` | `ambasada.config.ts`; optional `support` (email or URL, else the app\'s `support`), `tags` (\u2264 5), `subtitle`, `description`, `icon`, `category`, `accent`, `scopes`, `visibility`. The hub refuses an app without `age_rating` (`4+`, `9+`, `12+`, `17+`) |\n| the in-app layout and page, no site header | `app/app/` (Next), `src/in-app/InApp.tsx` rendered by `src/main.tsx` (spa), `web/app.html` (worker) |\n| `ready()` and silent sign-in | `app/app/in-app.tsx`, `src/in-app/shell.ts`, `web/in-app.js`; with `--entry /` hooked into the root layout instead |\n| a placeholder icon, 1024\xD71024 | `public/icon.png` (`web/icon.png`): replace it, keep it square and opaque |\n| `@ambasada/miniapp` | `package.json` (Next, spa): run `npm install` |\n\nThe manifest, `/.well-known/ambasada.json`, is not a file you keep: `ambasada dev` and `ambasada deploy` write it\nfrom `ambasada.config.ts` (id, name, description, `miniapp`) into `public/` (`web/`), and `.gitignore` leaves it out.\nTo write it by hand, put your own there and drop that `.gitignore` line: yours wins. Without `miniapp`, nothing is\nserved, `ambasada check` says "mini app: off" and the deploy does not register the app with the Ambasada app.\n\n## Is it listed?\n\n`ambasada deploy` registers the app with the Ambasada hub only when it serves the manifest, then checks it. It prints:\n\n```\n\u2713 in the Ambasada app: Listed for the event\n! in the Ambasada app: Unlisted \xB7 needs: icon, viewport\n  mini app: off, not in the Ambasada app (`ambasada miniapp enable` adds one)\n```\n\nUnlisted apps work, but only you see them in the Ambasada app. Fix what `needs` says and deploy again,\nor run `npx ambasada check https://<slug>.ambasada.dev` (or `npx ambasada check` for the local folder).\nThe checks: `/.well-known/ambasada.json` valid, `icon.png` a 1024\xD71024 PNG with no transparency, the entry page\nhas `<meta name="viewport" content="width=device-width, initial-scale=1">`, no dark-only theme, it answers in under\n3 s without a redirect, `/api/auth/callback` exists, the notifications webhook answers a signed ping. With the mini\napp off, only https, no redirects and the response time of `/`.\nConnected tools can do the same through MCP: `app_status`, `app_check`.\n\n## Look like the app: @ambasada/ui\n\nThe templates import `@ambasada/ui` (tokens, Inter + JetBrains Mono, `ui-card`, `ui-button`, `ui-row`,\n`ui-pill`, `ui-sheet`, `ui-stepper`, `ui-empty`, `ui-skeleton`). Use those classes before writing CSS.\nReact: `import { Card, Button, Sheet } from "@ambasada/ui/react"`. Plain HTML: one\n`<link rel="stylesheet" href="https://unpkg.com/@ambasada/ui@0.8/dist/ambasada-ui.css">`.\nLeave space for the app\'s bar: the page uses `--ambasada-safe-area-*` and `--ambasada-host-bar`.\nLight theme only; one red (primary) button per screen.\n\n## Notifications\n\nAlready wired in every template; they work once the mini app is on:\n\n| Piece | Where |\n|---|---|\n| manifest: `"scopes": ["identity", "notifications"]`, `"notifications": { "webhook": "/api/ambasada/webhook" }`, `"privacy_url": "/privacy"` | generated from `ambasada.config.ts` (the defaults; `miniapp.scopes` to change them) |\n| the webhook: verifies the hub\'s signature, saves `token \u2194 Ambasada user id` in `ambasada.store` | `app/api/ambasada/webhook/route.ts` (Next), `api/ambasada-webhook.ts` (spa, worker) |\n| `notifyUser(app, userId, { \u2026 })`: push to one person if they turned notifications on | `lib/notifications.ts` |\n| the privacy page the scopes need | `app/(site)/privacy/page.tsx`, `public/privacy.html`, `web/privacy.html` |\n\nSend one when something the person waits for happens (their order is ready), never as marketing:\n\n```ts\nimport { notifyUser } from "../lib/notifications.ts";\n\nconst user = await ambasada().auth.user(req);            // signed in with Ambasada\nif (user) await notifyUser(ambasada(), user.id, {\n  notification_id: `order-${id}-ready`,                  // unique per message; repeats are dropped for 24 h\n  title: "Your translation is ready",                    // \u2264 40 characters\n  body: "Tap to read it.",                               // \u2264 140\n  url: `/orders/${id}`,                                  // a path on your site: where the tap opens\n});\n```\n\nPeople turn notifications on in the app (the app asks; the page can ask too with\n`notifications.request()` from `@ambasada/miniapp`, from a button). The secret (`AMBASADA_APP_SECRET`) is\ninjected by `ambasada deploy`; never put it in the browser.\n\n## Signed in without a consent screen\n\nInside the Ambasada app the page signs in silently: `auth.signIn()` from `@ambasada/miniapp` gets a short\ntoken from the app and POSTs it to `/api/auth/shell`, which sets the same session as "Sign in with\nAmbasada". Server code doesn\'t change: `currentUser()` / `ambasada().auth.user(req)` work either way.\nOn the web, the button and consent screen stay. Silent sign-in needs the app to be Verified; until then\n`signIn()` resolves `null` and the button shows.\n\n## Try it locally\n\n`npx ambasada dev` plays the hub (with the mini app on): when your app starts it sends a signed `ping` and\n`notifications_enabled` to your webhook (the token lands in the store as\n`ambasada/notifications/user_fake_visitor`), and its `/api/apps/notify` accepts pushes for that token\n(they show in the terminal). Open `http://localhost:3000/app?ambasada_shell=mock` (your entry) to pretend to be\ninside the app: the fake shell signs you in silently as "Fake Visitor".\n', ".claude/skills/ambasada-product/reference/stack.md": '# The stack: Next.js on Cloudflare\n\nEvery Ambasada app is one Cloudflare Worker. The default template builds it from **Next.js 16.4**\nwith **@opennextjs/cloudflare 1.20** (the OpenNext adapter) and the `nodejs_compat` flag. You write a\nnormal Next.js App Router app; `ambasada deploy` turns it into a Worker.\n\n## Folder layout (template `next`)\n\n```\nmy-app/\n  app/layout.tsx               <html>, the Ambasada look (@ambasada/ui) and globals.css\n  app/(site)/layout.tsx        the site\'s header (app/account.tsx) around its pages; (site) is not in the URL\n  app/(site)/page.tsx          the landing page\n  app/notes.tsx                the notes example (a client component calling app/api/notes)\n  app/api/notes/route.ts       rows in env.DB, the list cached in env.KV\n  app/api/files/route.ts       uploads to env.FILES; app/files/[...key]/route.ts serves them\n  app/api/auth/*/route.ts      Sign in with Ambasada: login, callback, logout, me, shell (silent, in the app)\n  app/api/ambasada/webhook/    the Ambasada app\'s events: who turned notifications on (reference/mini-app.md)\n  app/account.tsx              the header: "Sign in with Ambasada", or the person\'s name and avatar\n  app/(site)/privacy/page.tsx  what you keep about people (the mini app\'s privacy_url)\n  app/(site)/room/             the live room demo\n  app/app/                     the mini app, once on (`ambasada miniapp enable`): its layout, page and in-app.tsx\n  lib/ambasada.ts              the Ambasada client for server code (reads the Worker env)\n  lib/notifications.ts         notifyUser(): a push to one person who turned notifications on\n  lib/db.ts, kv.ts, files.ts   env.DB, env.KV, env.FILES (reference/storage.md); lib/bindings.ts reaches them\n  db/migrations/               the database\'s tables, one .sql file per change\n  src/realtime/                the live room (a Durable Object) and its React hook\n  ambasada.config.ts           app id, name, one-line description, product URL, `miniapp` (optional)\n  wrangler.jsonc               Worker settings (nodejs_compat, assets) and the bindings DB, KV, FILES, ROOMS\n  worker.ts                    the Worker entry: live rooms\' WebSockets, then the Next.js app\n  open-next.config.ts          OpenNext settings; leave as is\n  .env                         secrets for local runs (never commit, never send to the browser)\n  .ambasada/project.json       the template and devkit version (`ambasada upgrade` reads it); commit it\n  .claude/skills/              this skill\n```\n\nOne more endpoint = one more `app/api/<name>/route.ts`. Data it keeps goes in `env.DB` (a migration in\n`db/migrations/`), `env.KV` or `env.FILES` ([storage.md](storage.md)).\n\n## Using the client\n\nServer code only (route handlers, server components, server actions):\n\n```ts\n// app/api/hello/route.ts\nimport { ambasada } from "../../../lib/ambasada.ts";\n\nexport async function GET(req: Request) {\n  const user = await ambasada().auth.user(req);\n  return Response.json({ hello: user?.name ?? "stranger" });\n}\n```\n\n`lib/ambasada.ts` creates one client per Worker instance with `createAmbasada({ env })` from `@ambasada/sdk`,\nwhere `env` comes from `getCloudflareContext()` (deployed); under `next dev` the SDK reads `process.env`.\nIt reads `AMBASADA_API_KEY` and `AMBASADA_API_URL` (default https://api.ambasada.dev). The client has `auth`\n(below), `apps` (notifications, [mini-app.md](mini-app.md)), `store` and `files`.\n\n## Who is signed in\n\nEvery hosted app gets **Sign in with Ambasada** (Ambasada ID) for free: no keys, no settings.\nThe template\'s header already has the button. In server code:\n\n```ts\nimport { currentUser } from "../lib/ambasada.ts";\nimport { bindings } from "../lib/bindings.ts";\nimport { run } from "../lib/db.ts";\n\nconst user = await currentUser(); // null, or { id, name, avatar_url, builder, pass, member_since, \u2026 }\nif (!user) redirect("/api/auth/login?returnTo=/orders");\nawait run(bindings().DB, "INSERT INTO orders (user_id, item) VALUES (?, ?)", user.id, item); // key per-person data by user.id\n```\n\nIn a route handler, `ambasada().auth.user(req)` does the same. Client components fetch `/api/auth/me`.\nAsk for the email only if you need it: `/api/auth/login` calls `auth.login(req, { email: true })`.\nDon\'t build your own login or accounts table, and don\'t add Clerk, Auth.js or Supabase Auth.\n\n## Next.js: allowed and banned\n\nAllowed, and enough for any product here:\n\n- pages and layouts (`app/**/page.tsx`, `layout.tsx`), server components, client components (`"use client"`)\n- route handlers (`app/api/**/route.ts`), server actions (`"use server"`)\n- `fetch` to any HTTPS API, `next/link`, `next/font`, plain CSS / CSS modules / Tailwind\n\nBanned (they fail on Workers or break the deploy):\n\n| Don\'t | Do instead |\n|---|---|\n| `next/image` with the default loader | `<img>`, or `images: { unoptimized: true }` in `next.config.ts` |\n| ISR, `export const revalidate = \u2026`, `revalidatePath`, `unstable_cache` | render on each request (`export const dynamic = "force-dynamic"`), or cache results in `env.KV` |\n| `fs`, `child_process`, `sharp`, `bcrypt`, `sqlite3`, `puppeteer`, any native package | `fetch` an API (an LLM provider with your own key in a secret, for example) |\n| a custom server (`server.js`, Express inside Next) | route handlers |\n| `middleware.ts` / `proxy.ts`, `export const runtime = "edge"` | check inside the page or route handler; Next\'s default runtime is right |\n| Prisma, Drizzle with a database, Supabase, Firebase, Mongo, Redis | `env.DB` (SQLite), `env.KV`, `env.FILES` ([storage.md](storage.md)) |\n| writing files at runtime, global variables as storage | `env.DB`, `env.KV`, `env.FILES` or a Durable Object (each request can run on a different machine) |\n\nKeep the bundle small: the Worker limit is 10 MB compressed. Big UI kits and icon packs are the usual cause.\n\n## Where data lives\n\nThe app has its own SQLite database (`env.DB`), key-value (`env.KV`), file storage (`env.FILES`, public at\n`/files/<key>`) and Durable Objects for live state, created at the first deploy. Which one fits, the migrations\nworkflow and copy-paste patterns: [storage.md](storage.md).\n\nAlso there, for small things: `ambasada.store` (JSON, 1 MB for the whole app: settings, not user data) and\n`ambasada.files.put(\u2026)` \u2192 `{ url }` (platform-hosted files that expire).\n\n## Secrets\n\n- Local: `.env` in the project (Cloudflare\'s `.dev.vars` works too). The template writes it with test\n  values for `ambasada dev`. Both are in `.gitignore`; keep them there.\n- Deployed: `ambasada deploy` injects `AMBASADA_API_KEY`, `AMBASADA_API_URL`, the Sign in with Ambasada\n  credentials (`AMBASADA_AUTH_*`) and the mini-app secret (`AMBASADA_APP_SECRET`, with `AMBASADA_HUB_URL`\n  and `AMBASADA_APP_ORIGIN`) for you. With `--own`, set them yourself: `npx wrangler secret put AMBASADA_API_KEY`.\n- Other services\' keys (an OpenAI key, say): `.env` locally, `npx ambasada env set OPENAI_API_KEY \u2026` online;\n  read on the server only.\n- Anything named `NEXT_PUBLIC_*` is copied into the browser. Never put a key there.\n- Never paste a key into a page, a client component, a prompt for a no-code builder, or a commit.\n\n## Variants\n\n- `spa`: Vite + React with `@cloudflare/vite-plugin`, for code exported from Lovable or Bolt. The\n  `api/` endpoints are small fetch handlers; the React app calls them with `fetch("/api/\u2026")`.\n- `worker`: `web/` (plain HTML/CSS) plus `api/*.ts` fetch handlers. Best when the app is a page or two.\n\nThe rules on this page (state, secrets, no native packages) apply to all three.\n', ".claude/skills/ambasada-product/reference/storage.md": '# Data, files and realtime\n\nEvery app on ambasada.dev gets a real database, key-value, file storage and Durable Objects. They are created\nat the first `ambasada deploy` and bound to the Worker on every deploy; nothing to sign up for or configure.\nLocally (`ambasada dev`, `wrangler dev`, `vite`) wrangler runs the same things from `.wrangler/state`.\n\n| Need | Use | Not |\n|---|---|---|\n| anything with rows: users\' data, orders, posts, scores, anything you query, sort or join | `env.DB` (SQLite, D1) | KV, files, `ambasada.store` |\n| sessions, caches of slow results, feature flags, "seen this already" | `env.KV` | a table you scan |\n| uploads, images, audio, PDFs, generated files | `env.FILES` (R2), public at `/files/<key>` | base64 in the database |\n| state several people see change live: chat, presence, a shared board, a game table, live counters, a queue, rate limits, one thing per entity | a Durable Object (`env.ROOMS` in the templates) | polling the database |\n| an AI agent with memory, schedules and live state per user or task | the Agents SDK (`examples/agent/`) | a cron that rereads everything |\n| a few small settings for a tiny app | `ambasada.store` (1 MB per app) | user data of any size |\n\nQuotas per app: database 500 MB, KV 1 GB, files 5 GB. A database over its quota stops the next deploy.\n\n## `env.DB`: SQLite\n\nSchema lives in `db/migrations/`, one file per change, applied in name order, never edited once applied:\n\n```sql\n-- db/migrations/0002_orders.sql\nCREATE TABLE orders (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  user_id TEXT NOT NULL,\n  item TEXT NOT NULL,\n  paid INTEGER NOT NULL DEFAULT 0,\n  created_at INTEGER NOT NULL\n);\nCREATE INDEX orders_user ON orders (user_id, created_at);\n```\n\n```sh\nnpx wrangler d1 migrations apply DB --local   # the local database, for ambasada dev\nnpx ambasada db migrate                       # the app\'s database online (run before or right after deploying)\nnpx ambasada db shell "SELECT * FROM orders LIMIT 5"\n```\n\nQuery with `lib/db.ts` (SQL with `?` placeholders, typed rows, no ORM):\n\n```ts\nimport { all, batch, first, run } from "../lib/db.ts";\n\ntype Order = { id: number; user_id: string; item: string; paid: number; created_at: number };\nconst mine = await all<Order>(env.DB, "SELECT * FROM orders WHERE user_id = ? ORDER BY created_at DESC LIMIT 50", user.id);\nconst one = await first<Order>(env.DB, "SELECT * FROM orders WHERE id = ?", id);\nconst { lastRowId } = await run(env.DB, "INSERT INTO orders (user_id, item, created_at) VALUES (?, ?, ?)", user.id, item, Date.now());\nawait batch(env.DB, [["UPDATE stock SET n = n - 1 WHERE item = ?", item], ["UPDATE orders SET paid = 1 WHERE id = ?", id]]); // all or nothing\n```\n\nIn Next.js route handlers and server components, the bindings come from `bindings()` (`lib/bindings.ts`):\n`const { DB } = bindings();`. In the spa and worker templates, handlers get `env`.\n\nRules: always placeholders, never string-built SQL. Key per-person rows by the Ambasada user id\n(`auth.user(req).id`). Add an index for every `WHERE` you run often. Times as `Date.now()` integers.\n\n## `env.KV`: sessions, caches, flags\n\nReads are fast everywhere; a write shows up everywhere within about a minute; one write per second per key.\n\n```ts\nimport { cached, getJson, putJson } from "../lib/kv.ts";\n\nawait putJson(env.KV, `session:${id}`, { userId }, { ttl: 60 * 60 * 24 });\nconst session = await getJson<{ userId: string }>(env.KV, `session:${id}`);\nconst stats = await cached(env.KV, "home:stats", 300, () => computeStats(env)); // recompute at most every 5 min\n```\n\nNot for counters, balances or anything two people write at once: use `env.DB` (a transaction) or a Durable Object.\n\n## `env.FILES`: uploads and generated files\n\n```ts\nimport { serveFile, upload } from "../lib/files.ts";\n\n// POST /api/files: a signed-in person uploads (the templates\' api/files.ts)\nconst { key, url } = await upload(env.FILES, req.body, { contentType: req.headers.get("content-type") ?? undefined, folder: `u/${user.id}` });\nawait run(env.DB, "INSERT INTO photos (user_id, file_key) VALUES (?, ?)", user.id, key); // keep the key, not the bytes\n\n// GET /files/*: already wired in every template, with ETag, ranges and cache headers\nreturn serveFile(env.FILES, req);\n```\n\n`url` is `/files/<key>` on the app (`https://<slug>.ambasada.dev/files/<key>`): public to anyone with the link.\nPrivate files: store them under a key nobody can guess and serve them from your own route that checks\n`auth.user(req)` first, instead of `/files/*`. `npx ambasada files list | put | url | delete` from the terminal.\n\n## Durable Objects: realtime and per-entity state\n\nA Durable Object is one tiny server per id (a room, a document, a match, a user) with its own SQLite, that\nevery request for that id reaches. Use one whenever people must see each other\'s changes live, or one thing\nmust never be updated by two requests at once. The templates ship `src/realtime/room.ts` (`env.ROOMS`):\n\n```ts\n// the Worker: /api/rooms/<id>/ws \u2192 the room\nconst room = /^\\/api\\/rooms\\/([^/]+)\\/ws$/.exec(pathname);\nif (room) return env.ROOMS.getByName(decodeURIComponent(room[1]!)).fetch(req);\n```\n\n```ts\n// the room (shortened): WebSocket hibernation, broadcast, its own SQLite\nexport class Room extends DurableObject<unknown> {\n  async fetch(req: Request) {\n    const { 0: client, 1: server } = new WebSocketPair();\n    this.ctx.acceptWebSocket(server);              // hibernation: no cost while nobody talks\n    server.serializeAttachment({ name: "guest" }); // per-connection data that survives hibernation\n    return new Response(null, { status: 101, webSocket: client });\n  }\n  async webSocketMessage(ws: WebSocket, data: string | ArrayBuffer) {\n    this.ctx.storage.sql.exec("INSERT INTO messages (text, at) VALUES (?, ?)", String(data), Date.now());\n    for (const peer of this.ctx.getWebSockets()) peer.send(String(data)); // everyone in the room\n  }\n}\n```\n\n```tsx\n// the browser (React): src/realtime/use-room.ts\nconst { messages, online, send, status } = useRoom(roomId, { name: user.name });\n```\n\nA new class needs a binding and a migration in `wrangler.jsonc` (new tags go at the end; never edit or remove one\nthat was deployed; to drop a class add `{ "tag": "v3", "deleted_classes": ["Old"] }`):\n\n```jsonc\n"durable_objects": { "bindings": [{ "name": "ROOMS", "class_name": "Room" }, { "name": "BOARDS", "class_name": "Board" }] },\n"migrations": [{ "tag": "v1", "new_sqlite_classes": ["Room"] }, { "tag": "v2", "new_sqlite_classes": ["Board"] }]\n```\n\nExport the class from the Worker\'s entry (`src/worker.ts`; spa `worker/index.ts`; next `worker.ts`).\nOther shapes, same pattern: presence (who is online), a live counter (`UPDATE \u2026 RETURNING`, then broadcast), a\nper-user rate limit (`getByName(user.id)`), a job queue (`this.ctx.storage.setAlarm`). A Durable Object belongs\nto this app; other apps can\'t reach it. Under `next dev` they don\'t run: use `npm run preview` (workerd).\n\n## Agents (Agents SDK)\n\nFor agentic products (an assistant per user, a research task that runs for minutes, a bot that follows up),\nuse the Cloudflare Agents SDK: `examples/agent/` in the template (`npm i agents`, four lines to wire). An agent\nis a Durable Object with live state synced to clients (`setState`, `useAgent` in React), `this.sql`,\n`this.schedule(\u2026)` and WebSockets. One agent per user or task: `/agents/agent-example/<user id>`.\n\n## Don\'t\n\n- Poll (`setInterval(fetch\u2026)`) for what others changed: a Durable Object + WebSocket pushes it.\n- Put files or base64 in the database or KV: `env.FILES`, and keep the key in a row.\n- Keep user data in `ambasada.store`: it is 1 MB for the whole app.\n- Keep state in module variables or global objects: every request may run on another machine.\n- Count, rank or move money in KV: use a SQL transaction (`batch`) or a Durable Object.\n- Build SQL by joining strings with user input: `?` placeholders.\n- Edit an applied migration: add the next file.\n- Add Prisma, Drizzle with Postgres, Supabase, Firebase, Mongo or Redis: everything above is already here.\n', ".claude/skills/ambasada-product/reference/upgrading.md": "# Upgrading a project\n\n`npx ambasada upgrade` does the mechanical part: every `@ambasada/*` dependency to the CLI's version, the\npackage manager, `.claude/skills/ambasada-*` re-synced (the project's own skills are left alone), the code\nchanges listed below as \"done by `upgrade`\", the `ambasada check` rules, and `.ambasada/project.json`\n(the template and devkit version). `npx ambasada upgrade --check` only reports.\n\nWhat is left is below, per version, for a coding agent. Do the steps for every version between the one in\n`.ambasada/project.json` (none: 0.7) and the current one, in order. After each, run the app with\n`npx ambasada dev` and the project's `typecheck` script.\n\n## 0.7 \u2192 0.8: the platform and the village split\n\n0.8 splits the devkit: `@ambasada/sdk` and `ambasada` are the platform (sign-in, notifications, storage,\nhosting); the Hack A Ton economy (TON, checkout, offerings, the agent) is the add-on `@ambasada/village`.\n\nDone by `upgrade`:\n\n- the village names (`village`, `createVillage`, `offering`, `defineCompany`, `isVillageError`, the receipt and\n  webhook helpers, their types) import from `@ambasada/village`; in a village app `createAmbasada` became\n  `createVillage` and `DEFAULT_API_URL` became `DEFAULT_VILLAGE_API_URL` (their 0.7 meaning);\n- `@ambasada/village` added to `package.json` when the app has `offerings.ts` or an `idea`;\n- `.env` / `.dev.vars`: `AMBASADA_API_URL=https://hackaton.ambasada.id` became `https://api.ambasada.dev` plus\n  `AMBASADA_VILLAGE_API_URL=https://hackaton.ambasada.id`;\n- the `ambasada-payments` skill replaced by `ambasada-village`.\n\nFor the agent:\n\n1. **Platform code uses the platform client.** Files that only sign people in, send notifications or use\n   `store`/`files` can import `createAmbasada` / `ambasada` from `@ambasada/sdk` instead of the village client.\n   Leave files that sell, check receipts or call `llm` on the village client.\n2. **Config.** `ambasada.config.ts` may stay `defineCompany({ id, name, idea, \u2026 })`; the 0.8 form is\n   `defineCompany(defineApp({ id, name, description, product }), { idea, offerings, agent })` with\n   `defineApp` from `@ambasada/sdk`. Add a one-line `description` (the manifest's subtitle).\n3. **CLI calls.** In scripts, READMEs and `package.json`: `ambasada wallet|ledger|offerings|market|steer|webhook|links`\n   \u2192 `ambasada village \u2026`, `ambasada logs --agent` \u2192 `ambasada village logs --agent`, `ambasada dev buy` \u2192\n   `ambasada village dev buy`. The old spellings still work through 1.x with a warning.\n4. **Pages that load pay.js** from `AMBASADA_API_URL` should use the village client's `apiUrl` (or\n   `AMBASADA_VILLAGE_API_URL`): `AMBASADA_API_URL` is the platform's from 0.8.\n5. **Login.** The CLI's login moved from `~/.config/village` to `~/.config/ambasada` (moved on first use);\n   nothing to do unless a script reads that file.\n6. Run `npx ambasada check`, `npx ambasada dev` and the typecheck; deploy when they pass.\n", "AGENTS.md": "# Agents\n\nThis is an Ambasada app: Next.js that runs as one Cloudflare Worker (OpenNext), with `@ambasada/sdk` for\nsign-in, notifications and the store. Read `README.md` first, and `.claude/skills/ambasada-product/`.\nRun it with `npm run dev` (`ambasada dev`: the mock API + `next dev`). Data and realtime (`env.DB`, `env.KV`,\n`env.FILES`, live rooms): `.claude/skills/ambasada-product/reference/storage.md`.\n\n<!-- BEGIN:nextjs-agent-rules -->\n\n## This is NOT the Next.js you know\n\nThis version has breaking changes \u2014 APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.\n\nThis block is written and re-added by `next dev` \u2014 verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.\n\n<!-- END:nextjs-agent-rules -->\n", "README.md": "# My App\n\nAn app on Ambasada, Next.js on one Cloudflare Worker (template `next`): sign-in with Ambasada ID, a database,\nkey-value, files and live rooms; a mini app inside the Ambasada app if you want one. Everything here is a default;\nchange anything.\n\n```\nambasada.config.ts          id, name, one-line description, where the app runs\napp/(site)/, app/notes.tsx  the site: header, landing page, room, privacy; the notes example\napp/api/auth/*              Sign in with Ambasada (login, callback, logout, me, shell); app/account.tsx is the header\napp/api/ambasada/webhook    the Ambasada app's events (notifications on/off); lib/notifications.ts sends pushes\napp/api/notes, app/api/files   env.DB + env.KV, uploads to env.FILES; app/files/[...key] serves them\nlib/ambasada.ts             the SDK client from the Worker's env (getCloudflareContext), process.env under `next dev`\nlib/db.ts, kv.ts, files.ts  env.DB, env.KV, env.FILES; db/migrations/ the tables; lib/bindings.ts reaches them\nsrc/realtime/               the live room (a Durable Object) and its React hook; worker.ts routes its WebSockets\nnext.config.ts, open-next.config.ts, wrangler.jsonc, worker.ts   Next.js \u2192 one Worker (OpenNext, nodejs_compat)\n.claude/skills/             docs your coding agent reads (ambasada-product)\n```\n\n## 1. Run it (2 min)\n\nNeeds Node \u2265 22.\n\n```sh\nnpm install\nnpm run dev                # `ambasada dev`: the mock Ambasada API on :8788 + `next dev` on http://localhost:3000\n```\n\nOpen http://localhost:3000: add a note, sign in (the mock signs you in as \"Fake Visitor\"), open /room in two tabs.\nhttp://127.0.0.1:8788 is the mock's page (sign-ins, notifications, the store). `ambasada dev` points your app at the\nmock whatever `.env` says.\n\n## 2. Make it yours\n\n- `ambasada.config.ts`: name and description.\n- A new endpoint: `app/api/<name>/route.ts`. Data goes in `env.DB` (a migration in `db/migrations/`), `env.KV` or `env.FILES`.\n- Ask your coding agent: it has the ambasada-product skill (stack, storage, sign-in, mini app, deploy).\n\nStay inside what runs on a Worker: pages, server components, route handlers, server actions and `fetch`.\nNot: the `next/image` default loader, ISR / `revalidate`, `fs`, `child_process` or native packages, a custom\nserver. `npm run preview` builds the Worker (`opennextjs-cloudflare build`) and runs it in workerd, as in production.\n\n## 3. Go live (1 min)\n\n```sh\nnpx ambasada login         # Ambasada ID, or a project key from https://developer.ambasada.dev\nnpx ambasada deploy        # build, smoke test, host at https://my-app.ambasada.dev\nnpx ambasada db migrate    # db/migrations \u2192 the app's database\nnpx ambasada logs          # the last deploy and recent errors\n```\n\nSign-in, notifications and the storage are set up by the deploy; nothing to configure. Your own secrets:\n`npx ambasada env set NAME value`. Hosting elsewhere: `npx opennextjs-cloudflare build && npx opennextjs-cloudflare deploy`, then `npx ambasada link https://\u2026`.\n\n**Sign in with Ambasada**: the header's button signs people in with their Ambasada ID; on the server,\n`ambasada(\u2026).auth.user(req)` gives `{ id, name, avatar_url, builder, pass }` or null.\n\n## Storage and realtime\n\nEvery app gets these, provisioned at the first `ambasada deploy`; locally wrangler keeps them in `.wrangler/state`.\n\n| Binding | For | Here |\n|---|---|---|\n| `env.DB` | SQLite: anything relational | `lib/db.ts`, tables in `db/migrations/`, example `app/api/notes/route.ts` |\n| `env.KV` | sessions, caches, flags | `lib/kv.ts` (the notes cache) |\n| `env.FILES` | uploads, generated files; public at `/files/<key>` | `lib/files.ts`, upload `app/api/files/route.ts` |\n| `env.ROOMS` | live state shared between people (Durable Object) | `src/realtime/room.ts` (wired in `worker.ts`), hook `src/realtime/use-room.ts`, demo at `/room` |\n\n```sh\nnpx wrangler d1 migrations apply DB --local   # db/migrations \u2192 the local database (ambasada dev)\nnpx ambasada db migrate                       # \u2026 \u2192 the app's database online\nnpx ambasada db shell \"SELECT * FROM notes\"   # or `ambasada db shell` for a prompt\nnpx ambasada kv list | get <key> | put <key> <value> | delete <key>\nnpx ambasada files put <file> | list | url <key> | delete <key>\n```\n\nUnder `next dev`, `env.DB`, `env.KV` and `env.FILES` work (`lib/bindings.ts`); live rooms need workerd: `npm run preview`.\n\nOptional: an agent with the Agents SDK in `examples/agent/` (its README: `npm i agents` and four lines to wire it).\n\n## In the Ambasada app (optional)\n\nOff by default: this is a website. `npx ambasada miniapp enable` adds a mini app at `/app` (`--entry /` for the whole\nsite): `miniapp: { entry: \"/app\" }` in `ambasada.config.ts`, app/app/ (layout, page) and app/app/in-app.tsx, a placeholder\n`public/icon.png`, and the manifest `ambasada dev` and `deploy` serve at `/.well-known/ambasada.json`. Then\n`http://localhost:3000/app?ambasada_shell=mock` pretends to be inside the Ambasada app. The ambasada-product skill:\nreference/mini-app.md.\n\n## Rules worth knowing\n\n- State lives in `env.DB`, `env.KV`, `env.FILES` or a Durable Object, never in module variables: a Worker has many instances.\n- Secrets only in `.env` locally and `ambasada env set` online; never in the code or `wrangler.jsonc` vars.\n- `npx ambasada check` runs the checks (https, no redirects, speed; the mini-app rules when it is on); `npx ambasada upgrade` after a new devkit.\n\nFor the Hack A Ton: `npx ambasada add village` (the add-on).\n\nBuilt by [CENTYSO](https://centyso.com) for [Ambasada](https://ambasada.id).\n", "ambasada.config.ts": 'import { defineApp } from "@ambasada/sdk";\n\nexport default defineApp({\n  id: "my-app",\n  name: "My App",\n  // One line about the app (the subtitle of its Ambasada mini app, if you add one: `ambasada miniapp enable`).\n  description: "Notes, a live room and sign-in",\n  // Where the app runs. `ambasada dev` serves it on http://localhost:3000; hosted, it is https://my-app.ambasada.dev\n  // (`ambasada deploy` sets it; `ambasada link https://\u2026` when you host elsewhere).\n  product: { url: "http://localhost:3000" },\n});\n', "app/(site)/layout.tsx": `import type { ReactNode } from "react";
+var define_AMBASADA_TEMPLATES_default = { next: { ".claude/skills/ambasada-product/SKILL.md": "---\nname: ambasada-product\ndescription: Build an app on Ambasada and put it online. Use when the user wants to make an app, tool, game or website, start one with `npm create ambasada@latest`, run it with `ambasada dev`, publish it with `ambasada deploy` at <slug>.ambasada.dev, show it in the Ambasada app (mini app, notifications, sign-in), store data in the app's SQLite database, KV or file storage, make it realtime with Durable Objects or an agent (Agents SDK), bring a site built in ChatGPT, Lovable, Bolt or v0, or upgrade a project made with an older CLI (`ambasada upgrade`). Default stack: Next.js on Cloudflare.\n---\n\n# Build an app on Ambasada and put it online\n\nAn app is **one website** (one Cloudflare Worker) at `https://<your-slug>.ambasada.dev`. It comes with\nSign in with Ambasada (Ambasada ID), a SQLite database, key-value, file storage and Durable Objects for\nrealtime. If you want, it also gets a mini app inside the Ambasada app, with push notifications (off by default). No servers, no\nCloudflare account, no keys to configure.\n\n## Start\n\n```sh\nnpm create ambasada@latest my-app           # Next.js (default)\ncd my-app && npm install\nnpx ambasada dev                            # the mock API + your site, no login\n```\n\nOther templates: add `-- --template spa` (Vite + React; for code exported from Lovable or Bolt) or\n`-- --template worker` (plain HTML + small fetch handlers; the smallest possible app). All three have the\nsame `ambasada.config.ts`, sign-in routes, notifications webhook and storage helpers, and a notes example.\n\n## What to read\n\n| The user wants to\u2026 | Read |\n|---|---|\n| know where files go, what Next.js features are allowed, secrets, who is signed in | [reference/stack.md](reference/stack.md) |\n| store data (tables, migrations), sessions or caches, uploads; make it live between people (chat, presence, a shared board, counters); build an AI agent | [reference/storage.md](reference/storage.md) |\n| run it locally, put it online, use their own Cloudflare account | [reference/dev-and-deploy.md](reference/dev-and-deploy.md) |\n| make it look good and easy to use | [reference/design.md](reference/design.md) |\n| show up in the Ambasada app (optional: `npx ambasada miniapp enable`), send push notifications, sign people in inside the app | [reference/mini-app.md](reference/mini-app.md) |\n| build in ChatGPT, Lovable, Bolt or v0 and bring it here | [reference/build-elsewhere.md](reference/build-elsewhere.md) |\n| upgrade a project made with an older CLI | [reference/upgrading.md](reference/upgrading.md) |\n\nFor the Hack A Ton (TON payments, offerings, the agent that runs a shop): `npx ambasada add village`, then\nthe **ambasada-village** skill.\n\n## Rules (break one and the app does not work)\n\n1. **One app = one Worker.** No separate backend, no Docker. State lives in the app's SQLite (`env.DB`),\n   key-value (`env.KV`), file storage (`env.FILES`) or a Durable Object, never in module variables.\n   See [reference/storage.md](reference/storage.md).\n2. **Only the allowed Next.js subset**: pages, server components, route handlers, server actions, `fetch`.\n   No `next/image` default loader, no ISR/`revalidate`, no `fs`/`child_process`/native packages, no custom\n   server, no `middleware.ts`/`proxy.ts`, no `runtime = \"edge\"`. See [reference/stack.md](reference/stack.md#nextjs-allowed-and-banned).\n3. **Keys never reach the browser.** They live in `.env` locally and `ambasada env set` online; only server\n   code reads them. Never prefix one with `NEXT_PUBLIC_`.\n4. **Sign-in is Ambasada ID.** Use the template's `/api/auth/*` routes and `auth.user(req)`; don't add\n   Clerk, Auth.js or Supabase Auth, and don't build an accounts table. Key per-person data by `user.id`.\n5. **Tables change through migrations**: a new `db/migrations/NNNN_name.sql` per change, never edits to an\n   applied one; `npx ambasada db migrate` after deploying.\n\n## When the user is not a developer\n\nDo the work; don't ask them to edit code. Ask at most: what it does and for whom. Then build one page, run\n`npx ambasada dev`, open it, use it as the fake visitor, and show them it worked. Explain in one sentence\nper step, no jargon.\n", ".claude/skills/ambasada-product/reference/build-elsewhere.md": "# Built in ChatGPT, Lovable, Bolt or v0\n\nThree ways, easiest first.\n\n## A. Keep it hosted there, link it\n\nGood for: a site that is finished where it is and only needs to show up in the Ambasada app.\n\n1. On a laptop with Node 22+, once:\n\n   ```sh\n   npm create ambasada@latest my-app -- --miniapp --entry /   # its ambasada.config.ts and the manifest\n   cd my-app && npm install\n   npx ambasada login\n   npx ambasada link https://YOUR-SITE\n   ```\n\n2. The site must serve `/.well-known/ambasada.json` and `/icon.png` (copy them from the new project's\n   `public/`; `npx ambasada dev` writes the manifest there) and pass `npx ambasada check https://YOUR-SITE`\n   ([mini-app.md](mini-app.md)).\n\nLimit: Sign in with Ambasada, notifications and the app's database, KV and files come with hosting on\nambasada.dev. A site hosted elsewhere keeps its own backend; use B or C to get them.\n\n## B. Bring the code home (recommended for Lovable and Bolt)\n\nGood for: anything with real work behind it. You get hosting on ambasada.dev and the full rules.\n\n1. Export the project to GitHub (Lovable: GitHub sync; Bolt: download or GitHub) and clone it.\n2. `npm create ambasada@latest my-app -- --template spa` and copy the exported `src/` (components, pages,\n   styles) into the new project's `src/`, replacing the starter UI. Keep the template's `api/`, `lib/`,\n   `db/`, `ambasada.config.ts`, `wrangler.jsonc` and `vite.config.ts`.\n3. Open the project in Claude Code, Cursor or Codex and say:\n\n   > This is an Ambasada app (see .claude/skills/ambasada-product). Replace Supabase/Firebase with the\n   > app's env.DB (tables in db/migrations), env.KV and env.FILES, and any login with Sign in with Ambasada\n   > (api/auth.ts, /api/auth/me). Then run it with `npx ambasada dev`.\n\n4. `npx ambasada dev`, try it, then `npx ambasada deploy`.\n\n## C. ChatGPT (or any chat) writes the code, you paste it\n\n1. `npm create ambasada@latest my-app`, `cd my-app && npm install`, `npx ambasada dev`.\n2. Paste this into ChatGPT, then the files it mentions, then your idea:\n\n   > I have a Next.js 16 App Router project that runs on Cloudflare Workers (OpenNext). Rules: no `fs`, no\n   > native packages, no `next/image` (use `<img>`), no middleware, no `revalidate`, no other login than the\n   > one in `app/api/auth`. Data goes in SQLite through `lib/db.ts` (tables in `db/migrations/*.sql`), the\n   > signed-in person comes from `currentUser()` in `lib/ambasada.ts`. Below are my `app/page.tsx`,\n   > `app/api/notes/route.ts` and `db/migrations/0001_init.sql`. Rewrite them for my idea: the main action\n   > visible on a phone without scrolling. Write complete files, one code block per file, with the file path\n   > above each. My idea: \u2026\n\n3. Paste each file where ChatGPT says, keep `npx ambasada dev` running, check the page. New tables: a new\n   file in `db/migrations/` (never edit an applied one). When it works: `npx ambasada deploy` and\n   `npx ambasada db migrate`.\n\nUse ChatGPT to write files, not to decide the stack: if its answer adds Prisma, Supabase, NextAuth,\n`next/image` or a `middleware.ts`, tell it \"that's banned in my project, do it without\".\n", ".claude/skills/ambasada-product/reference/design.md": '# Design for people who decide in 10 seconds\n\nPeople open your app on a phone, often inside the Ambasada app, between two other things. They decide in\nseconds whether it is for them. Build for that.\n\n## One page, one action\n\n- **One page first.** What it is, and the one thing to do, fit on the first screen of a phone (375 \xD7 667).\n  Extra pages only when the action needs them.\n- **One action.** One button that does the main thing. Add a second only after people use the first.\n- **Few words.** A headline of up to 8 words, one sentence under it, the button. Cut every adjective you can.\n- **Show the result.** One example of what people get (an image, a sample text) beats any description.\n- **No walls.** No signup before the first use, no cookie banner, no tour. Ask for sign-in when the app\n  needs to remember someone (Sign in with Ambasada is one tap inside the Ambasada app).\n\n## The button\n\n- Label it with the action: **Make my poem**, not **Submit**.\n- Big (at least 48 px tall), full width on phones, one strong colour, nothing else in that colour.\n- If people must type something first, put that one field right above the button.\n- After the action, show the result, or "Working on it\u2026" and the result appearing when ready (a live room\n  or polling). Never a blank page.\n\n## Look\n\n- The templates use `@ambasada/ui` (the Ambasada app\'s look: tokens, `ui-card`, `ui-button`); start there\n  ([mini-app.md](mini-app.md)). Otherwise plain CSS: one font, two colours plus grey, generous spacing.\n- Large text: 18 px body on phones, a headline twice that. Light theme.\n- Works with one thumb: tap targets 48 px, no hover-only menus.\n- Loads fast: no video backgrounds, no 3 MB hero images, no animation libraries.\n\n## Words\n\n- Say what they get, not how it works. "A logo in 1 minute", not "AI-powered logo generation".\n- Write in the language of your users; one is fine.\n\n## Before and after\n\n```\nBad:  Welcome to PoemForge\u2122, the next-generation AI-powered creative writing platform\n      [Features] [Pricing] [About] [Sign up]   \u2026scroll\u2026   [Get started]\n\nGood: Your name as a folk poem\n      Type a name. Get a 4-line Romanian folk poem in 10 seconds.\n      [ Name: _________ ]\n      [   Make my poem   ]\n      "Ana, floare de la munte, / \u2026"  \u2190 one real example\n```\n', ".claude/skills/ambasada-product/reference/dev-and-deploy.md": "# Run it, put it online\n\n## `ambasada dev`: everything on your laptop\n\n```sh\nnpx ambasada dev\n```\n\nStarts two things:\n\n1. a **mock Ambasada API** on `http://127.0.0.1:8788`: same routes and signatures as the real one. Sign in\n   with Ambasada signs you in as \"Fake Visitor\"; `apps.notify` lands in a fake hub; `ambasada.store` and\n   `ambasada.files` work in memory. Open it in a browser for a page with what happened.\n2. **your site** with its normal dev server (`next dev`, `vite` or `wrangler dev`), pointed at the mock.\n\nNo login. The app's database, KV, files and Durable Objects run locally too (wrangler, `.wrangler/state`);\n`ambasada dev` applies `db/migrations/` to the local database before it starts the site.\n\nTry it: open your site, sign in, add a note. With the mini app on, `http://localhost:3000/app?ambasada_shell=mock`\n(your `miniapp.entry`) pretends to be inside the Ambasada app (host bar insets, silent sign-in).\n\n`npx ambasada dev --mock-only` starts only the mock, if you run your site yourself. The mock's keys:\n`AMBASADA_API_URL=http://127.0.0.1:8788`, `AMBASADA_API_KEY=sk_test_dev` (already in the project's `.env`).\n\n## `ambasada deploy`: online at `<slug>.ambasada.dev`\n\nOnce, in the app's folder:\n\n```sh\nnpx ambasada login        # opens a page: sign in with Ambasada ID\n```\n\n(If it asks for a key instead: https://developer.ambasada.dev \u2192 your app \u2192 a project key, `vk_\u2026`.)\nEach app's key is kept under its id: with two apps on one laptop, log in once in each folder, and each folder uses\nits own. `deploy`, `db`/`kv`/`files`, `env`, `logs`, `tunnel` and the village's commands that change something refuse\na key of another app than the folder's `id` (\"this folder is X, you are logged in as Y\"); `--company Y` goes ahead.\n\nThen, every time you want the new version online:\n\n```sh\nnpx ambasada deploy\n```\n\nIt does, in order:\n\n1. **build**: `opennextjs-cloudflare build` (Next), `vite build` (spa) or a bundle of the Worker (worker);\n2. **smoke test**: runs the built Worker locally in workerd and requests `/` and `/.well-known/ambasada.json`\n   (written from `ambasada.config.ts` first, when the mini app is on: [mini-app.md](mini-app.md));\n   a crash stops the deploy (skip with `--no-smoke` only if you know why it fails);\n3. **upload**: the URL is `https://<your-slug>.ambasada.dev`, with `AMBASADA_API_KEY`, `AMBASADA_API_URL`,\n   Sign in with Ambasada and the app secret set for you, and the app's own database, KV namespace and bucket\n   bound as `DB`, `KV`, `FILES` (created on the first deploy) plus the Durable Objects from `wrangler.jsonc`.\n\nThe database's tables are not created by the deploy: run `npx ambasada db migrate` (it applies the new files\nin `db/migrations/`). No Cloudflare account needed. `--dry-run` builds and prints what it would upload.\n\nYour own secrets (an API key for another service): `npx ambasada env set NAME value` (live within about 30 s, and on\nevery deploy); `npx ambasada env list` shows the names. `.env` (and `.env.local`, `.env.production`, `.dev.vars`) never\ngoes online: the deploy builds without them, so a value that is only there is missing on ambasada.dev; `env set` it.\n\nLimits: 10 MB compressed bundle, 1000 static files, short CPU time per request (waiting on `fetch` does not\ncount). Heavy work belongs in an API you call, or a Durable Object, not in one request.\n\n## `ambasada dev --tunnel`: your laptop, live\n\nWhen the Ambasada app, sign-in or webhooks need to reach the version on your laptop (before deploying, or to\ndebug), log in once, then:\n\n```sh\nnpx ambasada dev --tunnel         # your dev server, against the real API, at https://<slug>-dev.ambasada.dev\nnpx ambasada tunnel --port 5173   # or: only the tunnel, for a server you started yourself\n```\n\nUntil Ctrl+C, `https://<slug>-dev.ambasada.dev` is your app's URL. There is no mock in this mode. The first\ntime takes up to 2 minutes while the address is published; after that it is instant. Only one terminal per\napp at a time: `--force` takes it over. More: docs/TUNNEL.md.\n\n## `ambasada deploy --own`: your own Cloudflare account\n\nRuns `wrangler deploy` into your account (you need `npx wrangler login` first), then\n`ambasada link <your workers.dev URL>`. Set the secrets yourself: `npx wrangler secret put AMBASADA_API_KEY`.\n\n## `ambasada link`: the app is hosted somewhere else\n\n```sh\nnpx ambasada link https://my-thing.lovable.app\n```\n\nSets `product.url` in `ambasada.config.ts` and checks that `<url>/health` answers. Use it for Lovable, Bolt,\nv0, Vercel, your own server. See [build-elsewhere.md](build-elsewhere.md).\n\n## Watch it run\n\n```sh\nnpx ambasada logs --follow     # the last deploy and new errors\nnpx ambasada check https://<slug>.ambasada.dev   # https, no redirects, speed; the mini-app rules when it is on\n```\n\nThe Developer app (https://developer.ambasada.dev) has deploys, errors, users and the storage tabs.\n\n## Upgrading\n\nA new devkit: `npx ambasada upgrade` (dependencies, skills, mechanical code changes), then\n[upgrading.md](upgrading.md) for the steps a coding agent does.\n\n## When it goes wrong\n\n| Symptom | Fix |\n|---|---|\n| build fails on `fs`, `child_process`, a `.node` file, `sharp` | a banned package: see [stack.md](stack.md#nextjs-allowed-and-banned) |\n| smoke test: `/` answers 500 | open `npx ambasada dev`, load `/`, read the terminal error |\n| `no such table: \u2026` online | `npx ambasada db migrate` |\n| a Durable Object migration is refused on deploy | never edit or remove a deployed tag in `wrangler.jsonc`'s `migrations`; add the next one ([storage.md](storage.md)) |\n| `CONFIG: no API key` | missing `AMBASADA_API_KEY`: `.env` locally, `ambasada login` before deploying |\n| sign-in loops back to the login page | `PUBLIC_URL` differs from the URL in the browser; remove it or fix it |\n| `this app uses the village \u2026 not installed` | a Hack A Ton project: `npx ambasada upgrade` (adds `@ambasada/village`) |\n", ".claude/skills/ambasada-product/reference/mini-app.md": '# The app inside the Ambasada app (mini app)\n\n**Optional, opt in with `npx ambasada miniapp enable`** (or `npm create ambasada@latest my-app -- --miniapp`). An app\nis a website first; most stay that way. The mini app is one more surface of it, at a path: what the Ambasada mobile\napp opens, with silent sign-in and push notifications. Platform spec: docs/MINI-APPS.md (\xA715, decision 15.6).\n\n## Turn it on\n\n```sh\nnpx ambasada miniapp enable              # at /app; --entry /in-app for another path, --entry / for the whole site\nnpx ambasada miniapp                     # on or off, and the entry\nnpx ambasada miniapp enable --entry /app --force   # move it: --force removes what the old entry left (it lists them otherwise)\nnpx ambasada miniapp disable             # off again: the config key, the manifest and the glue (pages at /app stay until --force)\n```\n\nIt adds:\n\n| | |\n|---|---|\n| `miniapp: { entry: "/app", age_rating: "4+", kind: "tool" }` | `ambasada.config.ts`; optional `support` (email or URL, else the app\'s `support`), `tags` (\u2264 5), `subtitle`, `description`, `icon`, `category`, `accent`, `scopes`, `visibility`. The hub refuses an app without `age_rating` (`4+`, `9+`, `12+`, `17+`) |\n| the in-app layout and page, no site header | `app/app/` (Next), `src/in-app/InApp.tsx` rendered by `src/main.tsx` (spa), `web/app.html` (worker) |\n| `ready()` and silent sign-in | `app/app/in-app.tsx`, `src/in-app/shell.ts`, `web/in-app.js`; with `--entry /` hooked into the root layout instead |\n| a placeholder icon, 1024\xD71024 | `public/icon.png` (`web/icon.png`): replace it, keep it square and opaque |\n| `@ambasada/miniapp` | `package.json` (Next, spa): run `npm install` |\n\nThe manifest, `/.well-known/ambasada.json`, is not a file you keep: `ambasada dev` and `ambasada deploy` write it\nfrom `ambasada.config.ts` (id, name, description, `miniapp`) into `public/` (`web/`), and `.gitignore` leaves it out.\nTo write it by hand, put your own there and drop that `.gitignore` line: yours wins. Without `miniapp`, nothing is\nserved, `ambasada check` says "mini app: off" and the deploy does not register the app with the Ambasada app.\n\n## Is it listed?\n\n`ambasada deploy` registers the app with the Ambasada hub only when it serves the manifest, then checks it. It prints:\n\n```\n\u2713 in the Ambasada app: Listed for the event\n! in the Ambasada app: Unlisted \xB7 needs: icon, viewport\n  mini app: off, not in the Ambasada app (`ambasada miniapp enable` adds one)\n```\n\nUnlisted apps work, but only you see them in the Ambasada app. Fix what `needs` says and deploy again,\nor run `npx ambasada check https://<slug>.ambasada.dev` (or `npx ambasada check` for the local folder).\nThe checks: `/.well-known/ambasada.json` valid, `icon.png` a 1024\xD71024 PNG with no transparency, the entry page\nhas `<meta name="viewport" content="width=device-width, initial-scale=1">`, no dark-only theme, it answers in under\n3 s without a redirect, `/api/auth/callback` exists, the notifications webhook answers a signed ping. With the mini\napp off, only https, no redirects and the response time of `/`. On a first deploy the webhook\'s secret takes a few\nminutes to arrive: the deploy says `checks: running (up to 5 min)`, and `npx ambasada check` shows the result.\nConnected tools can do the same through MCP: `app_status`, `app_check`.\n\n## Look like the app: @ambasada/ui\n\nThe templates import `@ambasada/ui` (tokens, Inter + JetBrains Mono, `ui-card`, `ui-button`, `ui-row`,\n`ui-pill`, `ui-sheet`, `ui-stepper`, `ui-empty`, `ui-skeleton`). Use those classes before writing CSS.\nReact: `import { Card, Button, Sheet } from "@ambasada/ui/react"`. Plain HTML: one\n`<link rel="stylesheet" href="https://unpkg.com/@ambasada/ui@0.8/dist/ambasada-ui.css">`.\nLeave space for the app\'s bar: the page uses `--ambasada-safe-area-*` and `--ambasada-host-bar`.\nLight theme only; one red (primary) button per screen.\n\n## Notifications\n\nAlready wired in every template; they work once the mini app is on:\n\n| Piece | Where |\n|---|---|\n| manifest: `"scopes": ["identity", "notifications"]`, `"notifications": { "webhook": "/api/ambasada/webhook" }`, `"privacy_url": "/privacy"` | generated from `ambasada.config.ts` (the defaults; `miniapp.scopes` to change them) |\n| the webhook: verifies the hub\'s signature, saves `token \u2194 Ambasada user id` in `ambasada.store` | `app/api/ambasada/webhook/route.ts` (Next), `api/ambasada-webhook.ts` (spa, worker) |\n| `notifyUser(app, userId, { \u2026 })`: push to one person if they turned notifications on | `lib/notifications.ts` |\n| the privacy page the scopes need | `app/(site)/privacy/page.tsx`, `public/privacy.html`, `web/privacy.html` |\n\nSend one when something the person waits for happens (their order is ready), never as marketing:\n\n```ts\nimport { notifyUser } from "../lib/notifications.ts";\n\nconst user = await ambasada().auth.user(req);            // signed in with Ambasada\nif (user) await notifyUser(ambasada(), user.id, {\n  notification_id: `order-${id}-ready`,                  // unique per message; repeats are dropped for 24 h\n  title: "Your translation is ready",                    // \u2264 40 characters\n  body: "Tap to read it.",                               // \u2264 140\n  url: `/orders/${id}`,                                  // a path on your site: where the tap opens\n});\n```\n\nPeople turn notifications on in the app (the app asks; the page can ask too with\n`notifications.request()` from `@ambasada/miniapp`, from a button). The secret (`AMBASADA_APP_SECRET`) is\ninjected by `ambasada deploy`; never put it in the browser.\n\n## Signed in without a consent screen\n\nInside the Ambasada app the page signs in silently: `auth.signIn()` from `@ambasada/miniapp` gets a short\ntoken from the app and POSTs it to `/api/auth/shell`, which sets the same session as "Sign in with\nAmbasada". Server code doesn\'t change: `currentUser()` / `ambasada().auth.user(req)` work either way.\nOn the web, the button and consent screen stay. Silent sign-in needs the app to be Verified; until then\n`signIn()` resolves `null` and the button shows.\n\n## Try it locally\n\n`npx ambasada dev` plays the hub (with the mini app on): when your app starts it sends a signed `ping` and\n`notifications_enabled` to your webhook (the token lands in the store as\n`ambasada/notifications/user_fake_visitor`), and its `/api/apps/notify` accepts pushes for that token\n(they show in the terminal). Open `http://localhost:3000/app?ambasada_shell=mock` (your entry) to pretend to be\ninside the app: the fake shell signs you in silently as "Fake Visitor".\n', ".claude/skills/ambasada-product/reference/stack.md": '# The stack: Next.js on Cloudflare\n\nEvery Ambasada app is one Cloudflare Worker. The default template builds it from **Next.js 16.4**\nwith **@opennextjs/cloudflare 1.20** (the OpenNext adapter) and the `nodejs_compat` flag. You write a\nnormal Next.js App Router app; `ambasada deploy` turns it into a Worker.\n\n## Folder layout (template `next`)\n\n```\nmy-app/\n  app/layout.tsx               <html>, the Ambasada look (@ambasada/ui) and globals.css\n  app/(site)/layout.tsx        the site\'s header (app/account.tsx) around its pages; (site) is not in the URL\n  app/(site)/page.tsx          the landing page\n  app/notes.tsx                the notes example (a client component calling app/api/notes)\n  app/api/notes/route.ts       rows in env.DB, the list cached in env.KV\n  app/api/files/route.ts       uploads to env.FILES; app/files/[...key]/route.ts serves them\n  app/api/auth/*/route.ts      Sign in with Ambasada: login, callback, logout, me, shell (silent, in the app)\n  app/api/ambasada/webhook/    the Ambasada app\'s events: who turned notifications on (reference/mini-app.md)\n  app/account.tsx              the header: "Sign in with Ambasada", or the person\'s name and avatar\n  app/(site)/privacy/page.tsx  what you keep about people (the mini app\'s privacy_url)\n  app/(site)/room/             the live room demo\n  app/app/                     the mini app, once on (`ambasada miniapp enable`): its layout, page and in-app.tsx\n  lib/ambasada.ts              the Ambasada client for server code (reads the Worker env)\n  lib/notifications.ts         notifyUser(): a push to one person who turned notifications on\n  lib/db.ts, kv.ts, files.ts   env.DB, env.KV, env.FILES (reference/storage.md); lib/bindings.ts reaches them\n  db/migrations/               the database\'s tables, one .sql file per change\n  src/realtime/                the live room (a Durable Object) and its React hook\n  ambasada.config.ts           app id, name, one-line description, product URL, `miniapp` (optional)\n  wrangler.jsonc               Worker settings (nodejs_compat, assets) and the bindings DB, KV, FILES, ROOMS\n  worker.ts                    the Worker entry: live rooms\' WebSockets, then the Next.js app\n  open-next.config.ts          OpenNext settings; leave as is\n  .env                         secrets for local runs (never commit, never send to the browser)\n  .ambasada/project.json       the template and devkit version (`ambasada upgrade` reads it); commit it\n  .claude/skills/              this skill\n```\n\nOne more endpoint = one more `app/api/<name>/route.ts`. Data it keeps goes in `env.DB` (a migration in\n`db/migrations/`), `env.KV` or `env.FILES` ([storage.md](storage.md)).\n\n## Using the client\n\nServer code only (route handlers, server components, server actions):\n\n```ts\n// app/api/hello/route.ts\nimport { ambasada } from "../../../lib/ambasada.ts";\n\nexport async function GET(req: Request) {\n  const user = await ambasada().auth.user(req);\n  return Response.json({ hello: user?.name ?? "stranger" });\n}\n```\n\n`lib/ambasada.ts` creates one client per Worker instance with `createAmbasada({ env })` from `@ambasada/sdk`,\nwhere `env` comes from `getCloudflareContext()` (deployed); under `next dev` the SDK reads `process.env`.\nIt reads `AMBASADA_API_KEY` and `AMBASADA_API_URL` (default https://api.ambasada.dev). The client has `auth`\n(below), `apps` (notifications, [mini-app.md](mini-app.md)), `store` and `files`.\n\n## Who is signed in\n\nEvery hosted app gets **Sign in with Ambasada** (Ambasada ID) for free: no keys, no settings.\nThe template\'s header already has the button. In server code:\n\n```ts\nimport { currentUser } from "../lib/ambasada.ts";\nimport { bindings } from "../lib/bindings.ts";\nimport { run } from "../lib/db.ts";\n\nconst user = await currentUser(); // null, or { id, name, avatar_url, builder, pass, member_since, \u2026 }\nif (!user) redirect("/api/auth/login?returnTo=/orders");\nawait run(bindings().DB, "INSERT INTO orders (user_id, item) VALUES (?, ?)", user.id, item); // key per-person data by user.id\n```\n\nIn a route handler, `ambasada().auth.user(req)` does the same. Client components fetch `/api/auth/me`.\nAsk for the email only if you need it: `/api/auth/login` calls `auth.login(req, { email: true })`.\nDon\'t build your own login or accounts table, and don\'t add Clerk, Auth.js or Supabase Auth.\n\n## Next.js: allowed and banned\n\nAllowed, and enough for any product here:\n\n- pages and layouts (`app/**/page.tsx`, `layout.tsx`), server components, client components (`"use client"`)\n- route handlers (`app/api/**/route.ts`), server actions (`"use server"`)\n- `fetch` to any HTTPS API, `next/link`, `next/font`, plain CSS / CSS modules / Tailwind\n\nBanned (they fail on Workers or break the deploy):\n\n| Don\'t | Do instead |\n|---|---|\n| `next/image` with the default loader | `<img>`, or `images: { unoptimized: true }` in `next.config.ts` |\n| ISR, `export const revalidate = \u2026`, `revalidatePath`, `unstable_cache` | render on each request (`export const dynamic = "force-dynamic"`), or cache results in `env.KV` |\n| `fs`, `child_process`, `sharp`, `bcrypt`, `sqlite3`, `puppeteer`, any native package | `fetch` an API (an LLM provider with your own key in a secret, for example) |\n| a custom server (`server.js`, Express inside Next) | route handlers |\n| `middleware.ts` / `proxy.ts`, `export const runtime = "edge"` | check inside the page or route handler; Next\'s default runtime is right |\n| Prisma, Drizzle with a database, Supabase, Firebase, Mongo, Redis | `env.DB` (SQLite), `env.KV`, `env.FILES` ([storage.md](storage.md)) |\n| writing files at runtime, global variables as storage | `env.DB`, `env.KV`, `env.FILES` or a Durable Object (each request can run on a different machine) |\n\nKeep the bundle small: the Worker limit is 10 MB compressed. Big UI kits and icon packs are the usual cause.\n\n## Where data lives\n\nThe app has its own SQLite database (`env.DB`), key-value (`env.KV`), file storage (`env.FILES`, public at\n`/files/<key>`) and Durable Objects for live state, created at the first deploy. Which one fits, the migrations\nworkflow and copy-paste patterns: [storage.md](storage.md).\n\nAlso there, for small things: `ambasada.store` (JSON, 1 MB for the whole app: settings, not user data) and\n`ambasada.files.put(\u2026)` \u2192 `{ url }` (platform-hosted files that expire).\n\n## Secrets\n\n- Local: `.env` in the project (Cloudflare\'s `.dev.vars` works too). The template writes it with test\n  values for `ambasada dev`. Both are in `.gitignore`; keep them there.\n- Deployed: `ambasada deploy` injects `AMBASADA_API_KEY`, `AMBASADA_API_URL`, the Sign in with Ambasada\n  credentials (`AMBASADA_AUTH_*`) and the mini-app secret (`AMBASADA_APP_SECRET`, with `AMBASADA_HUB_URL`\n  and `AMBASADA_APP_ORIGIN`) for you. With `--own`, set them yourself: `npx wrangler secret put AMBASADA_API_KEY`.\n- Your app\'s own URL (links in emails, notifications, answers): `appOrigin()` in `lib/ambasada.ts`, from\n  `AMBASADA_APP_ORIGIN` (the deploy and `ambasada dev` set it), not `req.url`: a call the platform forwards to your\n  app may come without its Host.\n- Other services\' keys (an OpenAI key, say): `.env` locally, `npx ambasada env set OPENAI_API_KEY \u2026` online;\n  read on the server only. `ambasada deploy` builds without `.env*`: nothing in them reaches the Worker.\n- Anything named `NEXT_PUBLIC_*` (`VITE_*` in the spa) is copied into the browser. Never put a key there. From `.env`\n  they work under `ambasada dev` only; a public value the live page needs goes in the code.\n- Never paste a key into a page, a client component, a prompt for a no-code builder, or a commit.\n\n## Variants\n\n- `spa`: Vite + React with `@cloudflare/vite-plugin`, for code exported from Lovable or Bolt. The\n  `api/` endpoints are small fetch handlers; the React app calls them with `fetch("/api/\u2026")`.\n- `worker`: `web/` (plain HTML/CSS) plus `api/*.ts` fetch handlers. Best when the app is a page or two.\n\nThe rules on this page (state, secrets, no native packages) apply to all three.\n', ".claude/skills/ambasada-product/reference/storage.md": '# Data, files and realtime\n\nEvery app on ambasada.dev gets a real database, key-value, file storage and Durable Objects. They are created\nat the first `ambasada deploy` and bound to the Worker on every deploy; nothing to sign up for or configure.\nLocally (`ambasada dev`, `wrangler dev`, `vite`) wrangler runs the same things from `.wrangler/state`.\n\n| Need | Use | Not |\n|---|---|---|\n| anything with rows: users\' data, orders, posts, scores, anything you query, sort or join | `env.DB` (SQLite, D1) | KV, files, `ambasada.store` |\n| sessions, caches of slow results, feature flags, "seen this already" | `env.KV` | a table you scan |\n| uploads, images, audio, PDFs, generated files | `env.FILES` (R2), public at `/files/<key>` | base64 in the database |\n| state several people see change live: chat, presence, a shared board, a game table, live counters, a queue, rate limits, one thing per entity | a Durable Object (`env.ROOMS` in the templates) | polling the database |\n| an AI agent with memory, schedules and live state per user or task | the Agents SDK (`examples/agent/`) | a cron that rereads everything |\n| a few small settings for a tiny app | `ambasada.store` (1 MB per app) | user data of any size |\n\nQuotas per app: database 500 MB, KV 1 GB, files 5 GB. A database over its quota stops the next deploy.\n\n## `env.DB`: SQLite\n\nSchema lives in `db/migrations/`, one file per change, applied in name order, never edited once applied:\n\n```sql\n-- db/migrations/0002_orders.sql\nCREATE TABLE orders (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  user_id TEXT NOT NULL,\n  item TEXT NOT NULL,\n  paid INTEGER NOT NULL DEFAULT 0,\n  created_at INTEGER NOT NULL\n);\nCREATE INDEX orders_user ON orders (user_id, created_at);\n```\n\n```sh\nnpx wrangler d1 migrations apply DB --local   # the local database, for ambasada dev\nnpx ambasada db migrate                       # the app\'s database online (run before or right after deploying)\nnpx ambasada db shell "SELECT * FROM orders LIMIT 5"\n```\n\nQuery with `lib/db.ts` (SQL with `?` placeholders, typed rows, no ORM):\n\n```ts\nimport { all, batch, first, run } from "../lib/db.ts";\n\ntype Order = { id: number; user_id: string; item: string; paid: number; created_at: number };\nconst mine = await all<Order>(env.DB, "SELECT * FROM orders WHERE user_id = ? ORDER BY created_at DESC LIMIT 50", user.id);\nconst one = await first<Order>(env.DB, "SELECT * FROM orders WHERE id = ?", id);\nconst { lastRowId } = await run(env.DB, "INSERT INTO orders (user_id, item, created_at) VALUES (?, ?, ?)", user.id, item, Date.now());\nawait batch(env.DB, [["UPDATE stock SET n = n - 1 WHERE item = ?", item], ["UPDATE orders SET paid = 1 WHERE id = ?", id]]); // all or nothing\n```\n\nIn Next.js route handlers and server components, the bindings come from `bindings()` (`lib/bindings.ts`):\n`const { DB } = bindings();`. In the spa and worker templates, handlers get `env`.\n\nRules: always placeholders, never string-built SQL. Key per-person rows by the Ambasada user id\n(`auth.user(req).id`). Add an index for every `WHERE` you run often. Times as `Date.now()` integers.\n\n## `env.KV`: sessions, caches, flags\n\nReads are fast everywhere; a write shows up everywhere within about a minute; one write per second per key.\n\n```ts\nimport { cached, getJson, putJson } from "../lib/kv.ts";\n\nawait putJson(env.KV, `session:${id}`, { userId }, { ttl: 60 * 60 * 24 });\nconst session = await getJson<{ userId: string }>(env.KV, `session:${id}`);\nconst stats = await cached(env.KV, "home:stats", 300, () => computeStats(env)); // recompute at most every 5 min\n```\n\nNot for counters, balances or anything two people write at once: use `env.DB` (a transaction) or a Durable Object.\n\n## `env.FILES`: uploads and generated files\n\n```ts\nimport { serveFile, upload } from "../lib/files.ts";\n\n// POST /api/files: a signed-in person uploads (the templates\' api/files.ts)\nconst { key, url } = await upload(env.FILES, req.body, { contentType: req.headers.get("content-type") ?? undefined, folder: `u/${user.id}` });\nawait run(env.DB, "INSERT INTO photos (user_id, file_key) VALUES (?, ?)", user.id, key); // keep the key, not the bytes\n\n// GET /files/*: already wired in every template, with ETag, ranges and cache headers\nreturn serveFile(env.FILES, req);\n```\n\n`url` is `/files/<key>` on the app (`https://<slug>.ambasada.dev/files/<key>`): public to anyone with the link.\nPrivate files: store them under a key nobody can guess and serve them from your own route that checks\n`auth.user(req)` first, instead of `/files/*`. `npx ambasada files list | put | url | delete` from the terminal.\n\n## Durable Objects: realtime and per-entity state\n\nA Durable Object is one tiny server per id (a room, a document, a match, a user) with its own SQLite, that\nevery request for that id reaches. Use one whenever people must see each other\'s changes live, or one thing\nmust never be updated by two requests at once. The templates ship `src/realtime/room.ts` (`env.ROOMS`):\n\n```ts\n// the Worker: /api/rooms/<id>/ws \u2192 the room\nconst room = /^\\/api\\/rooms\\/([^/]+)\\/ws$/.exec(pathname);\nif (room) return env.ROOMS.getByName(decodeURIComponent(room[1]!)).fetch(req);\n```\n\n```ts\n// the room (shortened): WebSocket hibernation, broadcast, its own SQLite\nexport class Room extends DurableObject<unknown> {\n  async fetch(req: Request) {\n    const { 0: client, 1: server } = new WebSocketPair();\n    this.ctx.acceptWebSocket(server);              // hibernation: no cost while nobody talks\n    server.serializeAttachment({ name: "guest" }); // per-connection data that survives hibernation\n    return new Response(null, { status: 101, webSocket: client });\n  }\n  async webSocketMessage(ws: WebSocket, data: string | ArrayBuffer) {\n    this.ctx.storage.sql.exec("INSERT INTO messages (text, at) VALUES (?, ?)", String(data), Date.now());\n    for (const peer of this.ctx.getWebSockets()) peer.send(String(data)); // everyone in the room\n  }\n}\n```\n\n```tsx\n// the browser (React): src/realtime/use-room.ts\nconst { messages, online, send, status } = useRoom(roomId, { name: user.name });\n```\n\nA new class needs a binding and a migration in `wrangler.jsonc` (new tags go at the end; never edit or remove one\nthat was deployed; to drop a class add `{ "tag": "v3", "deleted_classes": ["Old"] }`):\n\n```jsonc\n"durable_objects": { "bindings": [{ "name": "ROOMS", "class_name": "Room" }, { "name": "BOARDS", "class_name": "Board" }] },\n"migrations": [{ "tag": "v1", "new_sqlite_classes": ["Room"] }, { "tag": "v2", "new_sqlite_classes": ["Board"] }]\n```\n\nExport the class from the Worker\'s entry (`src/worker.ts`; spa `worker/index.ts`; next `worker.ts`).\nOther shapes, same pattern: presence (who is online), a live counter (`UPDATE \u2026 RETURNING`, then broadcast), a\nper-user rate limit (`getByName(user.id)`), a job queue (`this.ctx.storage.setAlarm`). A Durable Object belongs\nto this app; other apps can\'t reach it. Under `next dev` they don\'t run: use `npm run preview` (workerd).\n\n## Agents (Agents SDK)\n\nFor agentic products (an assistant per user, a research task that runs for minutes, a bot that follows up),\nuse the Cloudflare Agents SDK: `examples/agent/` in the template (`npm i agents`, four lines to wire). An agent\nis a Durable Object with live state synced to clients (`setState`, `useAgent` in React), `this.sql`,\n`this.schedule(\u2026)` and WebSockets. One agent per user or task: `/agents/agent-example/<user id>`.\n\n## Don\'t\n\n- Poll (`setInterval(fetch\u2026)`) for what others changed: a Durable Object + WebSocket pushes it.\n- Put files or base64 in the database or KV: `env.FILES`, and keep the key in a row.\n- Keep user data in `ambasada.store`: it is 1 MB for the whole app.\n- Keep state in module variables or global objects: every request may run on another machine.\n- Count, rank or move money in KV: use a SQL transaction (`batch`) or a Durable Object.\n- Build SQL by joining strings with user input: `?` placeholders.\n- Edit an applied migration: add the next file.\n- Add Prisma, Drizzle with Postgres, Supabase, Firebase, Mongo or Redis: everything above is already here.\n', ".claude/skills/ambasada-product/reference/upgrading.md": "# Upgrading a project\n\n`npx ambasada upgrade` does the mechanical part: every `@ambasada/*` dependency to the CLI's version, the\npackage manager, `.claude/skills/ambasada-*` re-synced (the project's own skills are left alone), the code\nchanges listed below as \"done by `upgrade`\", the `ambasada check` rules, and `.ambasada/project.json`\n(the template and devkit version). `npx ambasada upgrade --check` only reports.\n\nWhat is left is below, per version, for a coding agent. Do the steps for every version between the one in\n`.ambasada/project.json` (none: 0.7) and the current one, in order. After each, run the app with\n`npx ambasada dev` and the project's `typecheck` script.\n\n## 0.7 \u2192 0.8: the platform and the village split\n\n0.8 splits the devkit: `@ambasada/sdk` and `ambasada` are the platform (sign-in, notifications, storage,\nhosting); the Hack A Ton economy (TON, checkout, offerings, the agent) is the add-on `@ambasada/village`.\n\nDone by `upgrade`:\n\n- the village names (`village`, `createVillage`, `offering`, `defineCompany`, `isVillageError`, the receipt and\n  webhook helpers, their types) import from `@ambasada/village`; in a village app `createAmbasada` became\n  `createVillage` and `DEFAULT_API_URL` became `DEFAULT_VILLAGE_API_URL` (their 0.7 meaning);\n- `@ambasada/village` added to `package.json` when the app has `offerings.ts` or an `idea`;\n- `.env` / `.dev.vars`: `AMBASADA_API_URL=https://hackaton.ambasada.id` became `https://api.ambasada.dev` plus\n  `AMBASADA_VILLAGE_API_URL=https://hackaton.ambasada.id`;\n- the `ambasada-payments` skill replaced by `ambasada-village`.\n\nFor the agent:\n\n1. **Platform code uses the platform client.** Files that only sign people in, send notifications or use\n   `store`/`files` can import `createAmbasada` / `ambasada` from `@ambasada/sdk` instead of the village client.\n   Leave files that sell, check receipts or call `llm` on the village client.\n2. **Config.** `ambasada.config.ts` may stay `defineCompany({ id, name, idea, \u2026 })`; the 0.8 form is\n   `defineCompany(defineApp({ id, name, description, product }), { idea, offerings, agent })` with\n   `defineApp` from `@ambasada/sdk`. Add a one-line `description` (the manifest's subtitle).\n3. **CLI calls.** In scripts, READMEs and `package.json`: `ambasada wallet|ledger|offerings|market|steer|webhook|links`\n   \u2192 `ambasada village \u2026`, `ambasada logs --agent` \u2192 `ambasada village logs --agent`, `ambasada dev buy` \u2192\n   `ambasada village dev buy`. The old spellings still work through 1.x with a warning.\n4. **Pages that load pay.js** from `AMBASADA_API_URL` should use the village client's `apiUrl` (or\n   `AMBASADA_VILLAGE_API_URL`): `AMBASADA_API_URL` is the platform's from 0.8.\n5. **Login.** The CLI's login moved from `~/.config/village` to `~/.config/ambasada` (moved on first use);\n   nothing to do unless a script reads that file.\n6. Run `npx ambasada check`, `npx ambasada dev` and the typecheck; deploy when they pass.\n", "AGENTS.md": "# Agents\n\nThis is an Ambasada app: Next.js that runs as one Cloudflare Worker (OpenNext), with `@ambasada/sdk` for\nsign-in, notifications and the store. Read `README.md` first, and `.claude/skills/ambasada-product/`.\nRun it with `npm run dev` (`ambasada dev`: the mock API + `next dev`). Data and realtime (`env.DB`, `env.KV`,\n`env.FILES`, live rooms): `.claude/skills/ambasada-product/reference/storage.md`.\n\n<!-- BEGIN:nextjs-agent-rules -->\n\n## This is NOT the Next.js you know\n\nThis version has breaking changes \u2014 APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.\n\nThis block is written and re-added by `next dev` \u2014 verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.\n\n<!-- END:nextjs-agent-rules -->\n", "README.md": "# My App\n\nAn app on Ambasada, Next.js on one Cloudflare Worker (template `next`): sign-in with Ambasada ID, a database,\nkey-value, files and live rooms; a mini app inside the Ambasada app if you want one. Everything here is a default;\nchange anything.\n\n```\nambasada.config.ts          id, name, one-line description, where the app runs\napp/(site)/, app/notes.tsx  the site: header, landing page, room, privacy; the notes example\napp/api/auth/*              Sign in with Ambasada (login, callback, logout, me, shell); app/account.tsx is the header\napp/api/ambasada/webhook    the Ambasada app's events (notifications on/off); lib/notifications.ts sends pushes\napp/api/notes, app/api/files   env.DB + env.KV, uploads to env.FILES; app/files/[...key] serves them\nlib/ambasada.ts             the SDK client from the Worker's env (getCloudflareContext), process.env under `next dev`\nlib/db.ts, kv.ts, files.ts  env.DB, env.KV, env.FILES; db/migrations/ the tables; lib/bindings.ts reaches them\nsrc/realtime/               the live room (a Durable Object) and its React hook; worker.ts routes its WebSockets\nnext.config.ts, open-next.config.ts, wrangler.jsonc, worker.ts   Next.js \u2192 one Worker (OpenNext, nodejs_compat)\n.claude/skills/             docs your coding agent reads (ambasada-product)\n```\n\n## 1. Run it (2 min)\n\nNeeds Node \u2265 22.\n\n```sh\nnpm install\nnpm run dev                # `ambasada dev`: the mock Ambasada API on :8788 + `next dev` on http://localhost:3000\n```\n\nOpen http://localhost:3000: add a note, sign in (the mock signs you in as \"Fake Visitor\"), open /room in two tabs.\nhttp://127.0.0.1:8788 is the mock's page (sign-ins, notifications, the store). `ambasada dev` points your app at the\nmock whatever `.env` says.\n\n## 2. Make it yours\n\n- `ambasada.config.ts`: name and description.\n- A new endpoint: `app/api/<name>/route.ts`. Data goes in `env.DB` (a migration in `db/migrations/`), `env.KV` or `env.FILES`.\n- Ask your coding agent: it has the ambasada-product skill (stack, storage, sign-in, mini app, deploy).\n\nStay inside what runs on a Worker: pages, server components, route handlers, server actions and `fetch`.\nNot: the `next/image` default loader, ISR / `revalidate`, `fs`, `child_process` or native packages, a custom\nserver. `npm run preview` builds the Worker (`opennextjs-cloudflare build`) and runs it in workerd, as in production.\n\n## 3. Go live (1 min)\n\n```sh\nnpx ambasada login         # Ambasada ID, or a project key from https://developer.ambasada.dev\nnpx ambasada deploy        # build, smoke test, host at https://my-app.ambasada.dev\nnpx ambasada db migrate    # db/migrations \u2192 the app's database\nnpx ambasada logs          # the last deploy and recent errors\n```\n\nSign-in, notifications and the storage are set up by the deploy; nothing to configure. Your own secrets:\n`npx ambasada env set NAME value`. Hosting elsewhere: `npx opennextjs-cloudflare build && npx opennextjs-cloudflare deploy`, then `npx ambasada link https://\u2026`.\n\n**Sign in with Ambasada**: the header's button signs people in with their Ambasada ID; on the server,\n`ambasada(\u2026).auth.user(req)` gives `{ id, name, avatar_url, builder, pass }` or null.\n\n## Storage and realtime\n\nEvery app gets these, provisioned at the first `ambasada deploy`; locally wrangler keeps them in `.wrangler/state`.\n\n| Binding | For | Here |\n|---|---|---|\n| `env.DB` | SQLite: anything relational | `lib/db.ts`, tables in `db/migrations/`, example `app/api/notes/route.ts` |\n| `env.KV` | sessions, caches, flags | `lib/kv.ts` (the notes cache) |\n| `env.FILES` | uploads, generated files; public at `/files/<key>` | `lib/files.ts`, upload `app/api/files/route.ts` |\n| `env.ROOMS` | live state shared between people (Durable Object) | `src/realtime/room.ts` (wired in `worker.ts`), hook `src/realtime/use-room.ts`, demo at `/room` |\n\n```sh\nnpx wrangler d1 migrations apply DB --local   # db/migrations \u2192 the local database (ambasada dev)\nnpx ambasada db migrate                       # \u2026 \u2192 the app's database online\nnpx ambasada db shell \"SELECT * FROM notes\"   # or `ambasada db shell` for a prompt\nnpx ambasada kv list | get <key> | put <key> <value> | delete <key>\nnpx ambasada files put <file> | list | url <key> | delete <key>\n```\n\nUnder `next dev`, `env.DB`, `env.KV` and `env.FILES` work (`lib/bindings.ts`); live rooms need workerd: `npm run preview`.\n\nOptional: an agent with the Agents SDK in `examples/agent/` (its README: `npm i agents` and four lines to wire it).\n\n## In the Ambasada app (optional)\n\nOff by default: this is a website. `npx ambasada miniapp enable` adds a mini app at `/app` (`--entry /` for the whole\nsite): `miniapp: { entry: \"/app\" }` in `ambasada.config.ts`, app/app/ (layout, page) and app/app/in-app.tsx, a placeholder\n`public/icon.png`, and the manifest `ambasada dev` and `deploy` serve at `/.well-known/ambasada.json`. Then\n`http://localhost:3000/app?ambasada_shell=mock` pretends to be inside the Ambasada app. The ambasada-product skill:\nreference/mini-app.md.\n\n## Rules worth knowing\n\n- State lives in `env.DB`, `env.KV`, `env.FILES` or a Durable Object, never in module variables: a Worker has many instances.\n- Secrets only in `.env` locally and `ambasada env set` online; never in the code or `wrangler.jsonc` vars.\n- `npx ambasada check` runs the checks (https, no redirects, speed; the mini-app rules when it is on); `npx ambasada upgrade` after a new devkit.\n\nFor the Hack A Ton: `npx ambasada add village` (the add-on).\n\nBuilt by [CENTYSO](https://centyso.com) for [Ambasada](https://ambasada.id).\n", "ambasada.config.ts": 'import { defineApp } from "@ambasada/sdk";\n\nexport default defineApp({\n  id: "my-app",\n  name: "My App",\n  // One line about the app (the subtitle of its Ambasada mini app, if you add one: `ambasada miniapp enable`).\n  description: "Notes, a live room and sign-in",\n  // Where the app runs. `ambasada dev` serves it on http://localhost:3000; hosted, it is https://my-app.ambasada.dev\n  // (`ambasada deploy` sets it; `ambasada link https://\u2026` when you host elsewhere).\n  product: { url: "http://localhost:3000" },\n});\n', "app/(site)/layout.tsx": `import type { ReactNode } from "react";
 import { Account } from "../account.tsx";
 
 /** The site's pages (the route group adds nothing to the URL): the header with sign-in, then the page. */
@@ -81,14 +81,11 @@ body { margin: 0; }
 .eyebrow::before { content: "// "; }
 h1 { margin: var(--space-2) 0 var(--space-3); font-size: clamp(2.2rem, 7vw, 3.4rem); font-weight: var(--weight-semibold); line-height: 1.05; letter-spacing: -0.03em; }
 .lead { margin: 0 0 var(--space-8); font-size: 1.125rem; color: var(--color-ink-2); }
-.checkout { display: grid; gap: var(--space-4); }
 textarea, select { font: inherit; font-size: var(--text-base); color: inherit; padding: 10px 12px; border: 1px solid var(--color-line); border-radius: var(--radius-sm); background: var(--color-surface); }
 textarea:focus, select:focus { outline: none; border-color: var(--color-accent); box-shadow: 0 0 0 3px var(--color-accent-soft); }
 textarea { resize: vertical; min-height: 7rem; }
 .row { display: flex; flex-wrap: wrap; gap: var(--space-3); align-items: center; justify-content: space-between; }
 label { display: flex; gap: var(--space-2); align-items: center; color: var(--color-ink-2); }
-.pay::before { content: "\u25C6 "; opacity: 0.8; }
-.tip { margin-top: var(--space-10); padding-top: var(--space-6); border-top: 1px solid var(--color-line); }
 .small, footer { color: var(--color-ink-3); font-size: var(--text-sm); }
 footer { margin-top: calc(var(--space-10) + var(--space-2)); }
 code { font-family: var(--font-mono); font-size: 0.9em; background: var(--color-surface-2); padding: 0.1em 0.35em; border-radius: var(--radius-xs); }
@@ -118,7 +115,7 @@ export default function RootLayout({ children }: { children: ReactNode }) {
     </html>
   );
 }
-`, "app/notes.tsx": '"use client";\n\nimport { useEffect, useState } from "react";\n\ntype Note = { id: number; text: string; created_at: number };\n\n/** The notes example: GET and POST /api/notes (app/api/notes/route.ts). */\nexport function Notes() {\n  const [notes, setNotes] = useState<Note[]>([]);\n  const [text, setText] = useState("");\n  const load = () =>\n    fetch("/api/notes")\n      .then((res) => res.json() as Promise<{ notes: Note[] }>)\n      .then((r) => setNotes(r.notes))\n      .catch(() => setNotes([]));\n  useEffect(() => void load(), []);\n  return (\n    <form\n      className="ui-card"\n      onSubmit={async (e) => {\n        e.preventDefault();\n        if (!text.trim()) return;\n        await fetch("/api/notes", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ text }) });\n        setText("");\n        await load();\n      }}\n    >\n      <div className="row">\n        <input value={text} onChange={(e) => setText(e.target.value)} maxLength={500} placeholder="A note" aria-label="A note" />\n        <button type="submit" className="ui-button">\n          Add\n        </button>\n      </div>\n      <ul>\n        {notes.map((n) => (\n          <li key={n.id}>{n.text}</li>\n        ))}\n      </ul>\n    </form>\n  );\n}\n', "db/migrations/0001_init.sql": "-- The app's first table. Add the next change as db/migrations/0002_<what>.sql (never edit an applied file), then:\n--   npx wrangler d1 migrations apply DB --local   (ambasada dev)\n--   npx ambasada db migrate                       (online)\nCREATE TABLE notes (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  text TEXT NOT NULL,\n  created_at INTEGER NOT NULL\n);\nCREATE INDEX notes_created ON notes (created_at);\n", "examples/agent/README.md": '# Agent (optional): the Cloudflare Agents SDK\n\nFor agentic products: an agent per user, document or task, with live state, its own SQL, schedules and\nWebSockets (`agent.ts`). It is a Durable Object, so it runs on ambasada.dev like the live rooms. To turn it on:\n\n1. `npm i agents`\n2. `wrangler.jsonc`: add the binding and a migration after the existing ones:\n   ```jsonc\n   "durable_objects": { "bindings": [{ "name": "ROOMS", "class_name": "Room" }, { "name": "AgentExample", "class_name": "AgentExample" }] },\n   "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Room"] }, { "tag": "v2", "new_sqlite_classes": ["AgentExample"] }]\n   ```\n3. In the Worker entry (`src/worker.ts`; spa: `worker/index.ts`; next: `worker.ts`):\n   ```ts\n   export { AgentExample } from "../examples/agent/agent.ts"; // next: "./examples/agent/agent.ts"\n   import { routeAgents } from "../examples/agent/agent.ts";\n   // first thing in fetch():\n   const agent = await routeAgents(req, env as unknown as Record<string, unknown>);\n   if (agent) return agent;\n   ```\n4. In the browser (React): `useAgent({ agent: "agent-example", name: user.id, onStateUpdate: setState })` from\n   `agents/react`; `agent.send("hello")`. Plain fetch: `GET /agents/agent-example/<name>`.\n\n`ambasada deploy` sends the new class and its migration; nothing else to set up. Docs: https://developers.cloudflare.com/agents/\n', "examples/agent/agent.ts": '/**\n * Optional: an agent with the Cloudflare Agents SDK (`agents`), for agentic products. An agent is a Durable\n * Object with superpowers: state synced live to every connected client (`setState`), its own SQL (`this.sql`),\n * scheduled work (`this.schedule`), WebSockets and HTTP. One instance per name: per user, per document, per task.\n * Not wired in by default: examples/agent/README.md has the four steps.\n */\nimport { Agent, routeAgentRequest, type Connection, type WSMessage } from "agents";\n\ntype State = { notes: number; lastNote: string | null };\n\nexport class AgentExample extends Agent<Cloudflare.Env, State> {\n  initialState: State = { notes: 0, lastNote: null };\n\n  async onStart() {\n    this.sql`CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY AUTOINCREMENT, text TEXT NOT NULL, at INTEGER NOT NULL)`;\n  }\n\n  // GET /agents/agent-example/<name>: what this agent knows.\n  async onRequest(_req: Request): Promise<Response> {\n    const notes = this.sql<{ id: number; text: string; at: number }>`SELECT id, text, at FROM notes ORDER BY id DESC LIMIT 20`;\n    return Response.json({ state: this.state, notes });\n  }\n\n  // A client (useAgent in the browser) sent a message: remember it, sync the new state to every client,\n  // and come back to it in a minute (call an LLM here, send a notification, \u2026).\n  async onMessage(connection: Connection, message: WSMessage) {\n    const text = String(message).slice(0, 2000);\n    this.sql`INSERT INTO notes (text, at) VALUES (${text}, ${Date.now()})`;\n    this.setState({ notes: this.state.notes + 1, lastNote: text });\n    await this.schedule(60, "followUp", { text });\n    connection.send(JSON.stringify({ ok: true }));\n  }\n\n  async followUp(payload: { text: string }) {\n    console.log(`a minute ago someone wrote: ${payload.text}`);\n  }\n}\n\n/** In your Worker\'s fetch, before your own routes: answers /agents/<agent>/<name> (HTTP and WebSocket). */\nexport const routeAgents = (req: Request, env: Record<string, unknown>) => routeAgentRequest(req, env);\n', gitignore: "node_modules/\n.next/\n.open-next/\n.wrangler/\nnext-env.d.ts\n*.tsbuildinfo\n.env*\n.dev.vars*\n.DS_Store\n# build output of `ambasada deploy`; project.json (template, devkit version) is kept\n.ambasada/*\n!.ambasada/project.json\n", "lib/ambasada.ts": 'import { createAmbasada, type Ambasada, type AmbasadaUser } from "@ambasada/sdk";\nimport { getCloudflareContext } from "@opennextjs/cloudflare";\nimport { headers } from "next/headers";\n\n/**\n * The Worker\'s env (secrets injected at deploy, `.env` locally). Under `next dev` there is no\n * Cloudflare context: the SDK then reads process.env, which `ambasada dev` points at the mock.\n */\nfunction cloudflareEnv(): Record<string, unknown> | undefined {\n  try {\n    return getCloudflareContext().env as unknown as Record<string, unknown>;\n  } catch {\n    return undefined;\n  }\n}\n\n/** A variable from the Worker\'s env, else process.env. */\nexport function env(name: string): string | undefined {\n  const value = cloudflareEnv()?.[name] ?? process.env[name];\n  return typeof value === "string" && value ? value : undefined;\n}\n\nlet client: Ambasada | undefined;\n\n/** One client per isolate: it caches the API\'s signing keys. */\nexport function ambasada(): Ambasada {\n  return (client ??= createAmbasada({ env: cloudflareEnv() }));\n}\n\n/** Who is signed in with Ambasada (app/api/auth/*), in server components and route handlers; null when signed out. */\nexport async function currentUser(): Promise<AmbasadaUser | null> {\n  return ambasada().auth.user({ headers: await headers() });\n}\n', "lib/bindings.ts": `import { getCloudflareContext } from "@opennextjs/cloudflare";
+`, "app/notes.tsx": '"use client";\n\nimport { useEffect, useState } from "react";\n\ntype Note = { id: number; text: string; created_at: number };\n\n/** The notes example: GET and POST /api/notes (app/api/notes/route.ts). */\nexport function Notes() {\n  const [notes, setNotes] = useState<Note[]>([]);\n  const [text, setText] = useState("");\n  const load = () =>\n    fetch("/api/notes")\n      .then((res) => res.json() as Promise<{ notes: Note[] }>)\n      .then((r) => setNotes(r.notes))\n      .catch(() => setNotes([]));\n  useEffect(() => void load(), []);\n  return (\n    <form\n      className="ui-card"\n      onSubmit={async (e) => {\n        e.preventDefault();\n        if (!text.trim()) return;\n        await fetch("/api/notes", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ text }) });\n        setText("");\n        await load();\n      }}\n    >\n      <div className="row">\n        <input value={text} onChange={(e) => setText(e.target.value)} maxLength={500} placeholder="A note" aria-label="A note" />\n        <button type="submit" className="ui-button">\n          Add\n        </button>\n      </div>\n      <ul>\n        {notes.map((n) => (\n          <li key={n.id}>{n.text}</li>\n        ))}\n      </ul>\n    </form>\n  );\n}\n', "db/migrations/0001_init.sql": "-- The app's first table. Add the next change as db/migrations/0002_<what>.sql (never edit an applied file), then:\n--   npx wrangler d1 migrations apply DB --local   (ambasada dev)\n--   npx ambasada db migrate                       (online)\nCREATE TABLE notes (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  text TEXT NOT NULL,\n  created_at INTEGER NOT NULL\n);\nCREATE INDEX notes_created ON notes (created_at);\n", "examples/agent/README.md": '# Agent (optional): the Cloudflare Agents SDK\n\nFor agentic products: an agent per user, document or task, with live state, its own SQL, schedules and\nWebSockets (`agent.ts`). It is a Durable Object, so it runs on ambasada.dev like the live rooms. To turn it on:\n\n1. `npm i agents`\n2. `wrangler.jsonc`: add the binding and a migration after the existing ones:\n   ```jsonc\n   "durable_objects": { "bindings": [{ "name": "ROOMS", "class_name": "Room" }, { "name": "AgentExample", "class_name": "AgentExample" }] },\n   "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Room"] }, { "tag": "v2", "new_sqlite_classes": ["AgentExample"] }]\n   ```\n3. In the Worker entry (`src/worker.ts`; spa: `worker/index.ts`; next: `worker.ts`):\n   ```ts\n   export { AgentExample } from "../examples/agent/agent.ts"; // next: "./examples/agent/agent.ts"\n   import { routeAgents } from "../examples/agent/agent.ts";\n   // first thing in fetch():\n   const agent = await routeAgents(req, env as unknown as Record<string, unknown>);\n   if (agent) return agent;\n   ```\n4. In the browser (React): `useAgent({ agent: "agent-example", name: user.id, onStateUpdate: setState })` from\n   `agents/react`; `agent.send("hello")`. Plain fetch: `GET /agents/agent-example/<name>`.\n\n`ambasada deploy` sends the new class and its migration; nothing else to set up. Docs: https://developers.cloudflare.com/agents/\n', "examples/agent/agent.ts": '/**\n * Optional: an agent with the Cloudflare Agents SDK (`agents`), for agentic products. An agent is a Durable\n * Object with superpowers: state synced live to every connected client (`setState`), its own SQL (`this.sql`),\n * scheduled work (`this.schedule`), WebSockets and HTTP. One instance per name: per user, per document, per task.\n * Not wired in by default: examples/agent/README.md has the four steps.\n */\nimport { Agent, routeAgentRequest, type Connection, type WSMessage } from "agents";\n\ntype State = { notes: number; lastNote: string | null };\n\nexport class AgentExample extends Agent<Cloudflare.Env, State> {\n  initialState: State = { notes: 0, lastNote: null };\n\n  async onStart() {\n    this.sql`CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY AUTOINCREMENT, text TEXT NOT NULL, at INTEGER NOT NULL)`;\n  }\n\n  // GET /agents/agent-example/<name>: what this agent knows.\n  async onRequest(_req: Request): Promise<Response> {\n    const notes = this.sql<{ id: number; text: string; at: number }>`SELECT id, text, at FROM notes ORDER BY id DESC LIMIT 20`;\n    return Response.json({ state: this.state, notes });\n  }\n\n  // A client (useAgent in the browser) sent a message: remember it, sync the new state to every client,\n  // and come back to it in a minute (call an LLM here, send a notification, \u2026).\n  async onMessage(connection: Connection, message: WSMessage) {\n    const text = String(message).slice(0, 2000);\n    this.sql`INSERT INTO notes (text, at) VALUES (${text}, ${Date.now()})`;\n    this.setState({ notes: this.state.notes + 1, lastNote: text });\n    await this.schedule(60, "followUp", { text });\n    connection.send(JSON.stringify({ ok: true }));\n  }\n\n  async followUp(payload: { text: string }) {\n    console.log(`a minute ago someone wrote: ${payload.text}`);\n  }\n}\n\n/** In your Worker\'s fetch, before your own routes: answers /agents/<agent>/<name> (HTTP and WebSocket). */\nexport const routeAgents = (req: Request, env: Record<string, unknown>) => routeAgentRequest(req, env);\n', gitignore: "node_modules/\n.next/\n.open-next/\n.wrangler/\nnext-env.d.ts\n*.tsbuildinfo\n.env*\n.dev.vars*\n.DS_Store\n# build output of `ambasada deploy`; project.json (template, devkit version) is kept\n.ambasada/*\n!.ambasada/project.json\n", "lib/ambasada.ts": 'import { createAmbasada, type Ambasada, type AmbasadaUser } from "@ambasada/sdk";\nimport { getCloudflareContext } from "@opennextjs/cloudflare";\nimport { headers } from "next/headers";\n\n/**\n * The Worker\'s env (secrets injected at deploy, `.env` locally). Under `next dev` there is no\n * Cloudflare context: the SDK then reads process.env, which `ambasada dev` points at the mock.\n */\nfunction cloudflareEnv(): Record<string, unknown> | undefined {\n  try {\n    return getCloudflareContext().env as unknown as Record<string, unknown>;\n  } catch {\n    return undefined;\n  }\n}\n\n/** A variable from the Worker\'s env, else process.env. */\nexport function env(name: string): string | undefined {\n  const value = cloudflareEnv()?.[name] ?? process.env[name];\n  return typeof value === "string" && value ? value : undefined;\n}\n\n/**\n * This app\'s own origin (https://<slug>.ambasada.dev online, the dev server locally): AMBASADA_APP_ORIGIN, which\n * `ambasada deploy` and `ambasada dev` set, else the request\'s. Not `req.url` alone: a call the platform forwards (an\n * agent\'s purchase, a webhook) reaches Next.js without the Host it builds `req.url` from (`https://undefined`).\n */\nexport function appOrigin(req?: Request): string {\n  return env("AMBASADA_APP_ORIGIN") ?? (req ? new URL(req.url).origin : "http://localhost:3000");\n}\n\nlet client: Ambasada | undefined;\n\n/** One client per isolate: it caches the API\'s signing keys. */\nexport function ambasada(): Ambasada {\n  return (client ??= createAmbasada({ env: cloudflareEnv() }));\n}\n\n/** Who is signed in with Ambasada (app/api/auth/*), in server components and route handlers; null when signed out. */\nexport async function currentUser(): Promise<AmbasadaUser | null> {\n  return ambasada().auth.user({ headers: await headers() });\n}\n', "lib/bindings.ts": `import { getCloudflareContext } from "@opennextjs/cloudflare";
 import type { Database } from "./db.ts";
 import type { Bucket } from "./files.ts";
 import type { KeyValue } from "./kv.ts";
@@ -135,7 +132,7 @@ export interface Bindings {
 }
 
 export const bindings = (): Bindings => getCloudflareContext().env as unknown as Bindings;
-`, "lib/db.ts": '/**\n * env.DB: this app\'s SQLite database (Cloudflare D1). The tables come from db/migrations/*.sql:\n * `npx ambasada db migrate` online, `npx wrangler d1 migrations apply DB --local` for `ambasada dev`.\n * A tiny typed layer, no ORM: SQL with ? placeholders in, plain objects out.\n *\n *   const notes = await all<Note>(env.DB, "SELECT * FROM notes ORDER BY id DESC LIMIT ?", 20);\n *   const note = await first<Note>(env.DB, "SELECT * FROM notes WHERE id = ?", id);\n *   const { lastRowId } = await run(env.DB, "INSERT INTO notes (text) VALUES (?)", text);\n *   await batch(env.DB, [["UPDATE a SET n = n - 1 WHERE id = ?", 1], ["UPDATE b SET n = n + 1 WHERE id = ?", 2]]); // one transaction\n */\n\nexport type Param = string | number | boolean | null | ArrayBuffer;\n\n/** What this file needs from a D1 binding (env.DB satisfies it). */\nexport interface Database {\n  prepare(query: string): Statement;\n  batch(statements: Statement[]): Promise<unknown[]>;\n}\n\nexport interface Statement {\n  bind(...values: unknown[]): Statement;\n  all<T = Record<string, unknown>>(): Promise<{ results: T[] }>;\n  first<T = Record<string, unknown>>(): Promise<T | null>;\n  run(): Promise<{ meta: { changes: number; last_row_id: number } }>;\n}\n\nconst statement = (db: Database, query: string, params: Param[]) => db.prepare(query).bind(...params);\n\n/** Every row. */\nexport async function all<T = Record<string, unknown>>(db: Database, query: string, ...params: Param[]): Promise<T[]> {\n  return (await statement(db, query, params).all<T>()).results;\n}\n\n/** The first row, or null. */\nexport function first<T = Record<string, unknown>>(db: Database, query: string, ...params: Param[]): Promise<T | null> {\n  return statement(db, query, params).first<T>();\n}\n\n/** INSERT, UPDATE, DELETE: how many rows changed and the last inserted id. */\nexport async function run(db: Database, query: string, ...params: Param[]): Promise<{ changes: number; lastRowId: number }> {\n  const { meta } = await statement(db, query, params).run();\n  return { changes: meta.changes, lastRowId: meta.last_row_id };\n}\n\n/** Several statements in one transaction: all of them apply, or none. */\nexport async function batch(db: Database, statements: [query: string, ...params: Param[]][]): Promise<void> {\n  await db.batch(statements.map(([query, ...params]) => statement(db, query, params)));\n}\n', "lib/files.ts": '/**\n * env.FILES: this app\'s file storage (Cloudflare R2). Uploads and generated files; each one is public at\n * /files/<key> on the app\'s own address (the /files/* route calls serveFile). Don\'t keep files in the database.\n *\n *   const { key, url } = await upload(env.FILES, req.body, { contentType: "image/png" });   // url: /files/u/\u2026\n *   return serveFile(env.FILES, req);                                                        // GET /files/*\n *\n * Files are public to anyone with the URL: keep private documents behind your own route that checks who asks.\n * `npx ambasada files put|list|delete|url` manages them from the terminal.\n */\n\n/** What this file needs from an R2 binding (env.FILES satisfies it). */\nexport interface Bucket {\n  put(key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null, options?: { httpMetadata?: { contentType?: string } }): Promise<unknown>;\n  get(key: string, options?: { onlyIf?: Headers; range?: Headers }): Promise<StoredFile | null>;\n  delete(key: string): Promise<void>;\n}\n\nexport interface StoredFile {\n  httpEtag: string;\n  size: number;\n  httpMetadata?: { contentType?: string };\n  range?: { offset?: number; length?: number; suffix?: number };\n  body?: ReadableStream;\n}\n\nexport const FILES_PATH = "/files/";\n\n/** Stores `body` under a new random key (in `folder`) \u2192 `{ key, url }`, url relative to the app (/files/<key>). */\nexport async function upload(bucket: Bucket, body: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null, options: { contentType?: string; folder?: string } = {}): Promise<{ key: string; url: string }> {\n  const key = `${options.folder ?? "u"}/${crypto.randomUUID()}`;\n  await bucket.put(key, body, { httpMetadata: { contentType: options.contentType ?? "application/octet-stream" } });\n  return { key, url: fileUrl(key) };\n}\n\nexport const fileUrl = (key: string) => `${FILES_PATH}${key.split("/").map(encodeURIComponent).join("/")}`;\n\n/** GET/HEAD /files/<key>: the file with its type, an ETag (304 when unchanged), byte ranges, and a cache header. */\nexport async function serveFile(bucket: Bucket, req: Request): Promise<Response> {\n  if (req.method !== "GET" && req.method !== "HEAD") return new Response(null, { status: 405, headers: { allow: "GET, HEAD" } });\n  const path = new URL(req.url).pathname;\n  const key = decodeURIComponent(path.slice(path.indexOf(FILES_PATH) + FILES_PATH.length));\n  if (!key) return new Response("Not found", { status: 404 });\n  const file = await bucket.get(key, { onlyIf: req.headers, range: req.headers });\n  if (!file) return new Response("Not found", { status: 404 });\n  const headers = new Headers({ etag: file.httpEtag, "cache-control": "public, max-age=3600", "accept-ranges": "bytes" });\n  if (file.httpMetadata?.contentType) headers.set("content-type", file.httpMetadata.contentType);\n  if (!file.body) return new Response(null, { status: 304, headers }); // If-None-Match matched: nothing changed\n  const r = file.range;\n  if (r && req.headers.has("range")) {\n    const offset = r.suffix !== undefined ? file.size - r.suffix : (r.offset ?? 0);\n    const length = r.suffix ?? r.length ?? file.size - offset;\n    headers.set("content-range", `bytes ${offset}-${offset + length - 1}/${file.size}`);\n    headers.set("content-length", String(length));\n    return new Response(req.method === "HEAD" ? null : file.body, { status: 206, headers });\n  }\n  headers.set("content-length", String(file.size));\n  return new Response(req.method === "HEAD" ? null : file.body, { headers });\n}\n', "lib/kv.ts": '/**\n * env.KV: this app\'s key-value store (Cloudflare KV). Fast reads everywhere, writes visible within about a\n * minute, at most one write per second per key. Good for sessions, caches and feature flags; not for counters\n * or anything two people change at once (use env.DB, or a Durable Object for live state).\n *\n *   await putJson(env.KV, `session:${id}`, { user }, { ttl: 60 * 60 * 24 });\n *   const session = await getJson<{ user: string }>(env.KV, `session:${id}`);\n *   const page = await cached(env.KV, "home:stats", 60, () => computeStats());\n */\n\n/** What this file needs from a KV binding (env.KV satisfies it). */\nexport interface KeyValue {\n  get(key: string, type: "text"): Promise<string | null>;\n  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;\n  delete(key: string): Promise<void>;\n}\n\n/** The value saved under `key`, parsed; null when there is none (or it expired). */\nexport async function getJson<T>(kv: KeyValue, key: string): Promise<T | null> {\n  const text = await kv.get(key, "text");\n  return text === null ? null : (JSON.parse(text) as T);\n}\n\n/** Saves `value` as JSON. `ttl`: seconds until it disappears (at least 60). */\nexport function putJson(kv: KeyValue, key: string, value: unknown, options: { ttl?: number } = {}): Promise<void> {\n  return kv.put(key, JSON.stringify(value), options.ttl ? { expirationTtl: Math.max(60, options.ttl) } : undefined);\n}\n\nexport function remove(kv: KeyValue, key: string): Promise<void> {\n  return kv.delete(key);\n}\n\n/** `load()`\'s result, kept for `ttl` seconds: a cache in front of something slow. */\nexport async function cached<T>(kv: KeyValue, key: string, ttl: number, load: () => Promise<T>): Promise<T> {\n  const hit = await getJson<T>(kv, key);\n  if (hit !== null) return hit;\n  const value = await load();\n  await putJson(kv, key, value, { ttl });\n  return value;\n}\n', "lib/notifications.ts": '// Who turned notifications on, and how to reach them (docs/MINI-APPS.md \xA77). The hub sends a token per person\n// to the webhook route (api/ambasada-webhook.ts; app/api/ambasada/webhook/route.ts in Next); it lives in your\n// ambasada.store under the person\'s Ambasada user id.\nimport type { Ambasada, AppNotifyInput } from "@ambasada/sdk";\n\nconst key = (user: string) => `ambasada/notifications/${user}`;\n\nexport const saveToken = (app: Ambasada, user: string, token: string) => app.store.set(key(user), { token, enabled_at: new Date().toISOString() });\nexport const forgetToken = (app: Ambasada, user: string) => app.store.delete(key(user));\n\n/**\n * A push to one person (their Ambasada user id, e.g. `(await app.auth.user(req)).id`), if they turned\n * notifications on. False when they haven\'t, or the hub said the token is gone (then it is forgotten).\n *   await notifyUser(app, user.id, { notification_id: `order-${id}`, title: "Your translation is ready", body: "\u2026", url: `/orders/${id}` });\n */\nexport async function notifyUser(app: Ambasada, user: string, notification: Omit<AppNotifyInput, "tokens" | "users">): Promise<boolean> {\n  const saved = await app.store.get<{ token: string }>(key(user));\n  if (!saved) return false;\n  const result = await app.apps.notify({ ...notification, tokens: [saved.token] });\n  if (result.invalid.includes(saved.token)) await forgetToken(app, user);\n  return result.sent.includes(saved.token);\n}\n', "next.config.ts": 'import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare";\nimport type { NextConfig } from "next";\n\n// The product runs as one Cloudflare Worker (OpenNext). Stick to pages, server components, route\n// handlers, server actions and fetch: no next/image default loader, ISR, fs or native dependencies.\nconst nextConfig: NextConfig = {\n  // `ambasada dev --tunnel` serves `next dev` at https://<slug>-dev.ambasada.dev: let it load dev assets and HMR from there.\n  allowedDevOrigins: ["*.ambasada.dev"],\n};\n\nexport default nextConfig;\n\n// `next dev` reaches env.DB, env.KV and env.FILES (wrangler\'s local copies) through getCloudflareContext() (lib/bindings.ts).\ninitOpenNextCloudflareForDev();\n', "open-next.config.ts": 'import { defineCloudflareConfig } from "@opennextjs/cloudflare";\n\n// `opennextjs-cloudflare build` turns the Next.js app into one Worker (.open-next/worker.js + assets).\nexport default defineCloudflareConfig();\n', "package.json": '{\n  "name": "@ambasada/template-next",\n  "version": "0.1.0",\n  "private": true,\n  "description": "An Ambasada app: Next.js as one Cloudflare Worker (OpenNext), with sign-in, notifications and storage.",\n  "type": "module",\n  "engines": {\n    "node": ">=22"\n  },\n  "scripts": {\n    "dev": "ambasada dev",\n    "build": "next build",\n    "build:worker": "opennextjs-cloudflare build",\n    "preview": "opennextjs-cloudflare build && wrangler dev --port 3000",\n    "typecheck": "next typegen && tsc --noEmit && wrangler types node_modules/.worker-env.d.ts && tsc -p tsconfig.worker.json",\n    "ambasada": "ambasada"\n  },\n  "dependencies": {\n    "@ambasada/sdk": "workspace:*",\n    "@ambasada/ui": "workspace:*",\n    "@opennextjs/cloudflare": "~1.20.15",\n    "next": "~16.4.3",\n    "react": "~19.3.1",\n    "react-dom": "~19.3.1"\n  },\n  "devDependencies": {\n    "@ambasada/cli": "workspace:*",\n    "@types/node": "^22.20.5",\n    "@types/react": "^19.3.0",\n    "@types/react-dom": "^19.3.0",\n    "typescript": "~5.9.3",\n    "wrangler": "^4.156.1"\n  }\n}\n', "src/realtime/room.ts": '/**\n * A live room (Durable Object `Room`, bound as env.ROOMS): everyone connected to the same room id shares it.\n *\n *   GET /api/rooms/<id>/ws  (WebSocket)  \u2192 env.ROOMS.getByName(id).fetch(req)\n *   client \u2192 { "text": "hi" }            server \u2192 { type: "history", messages } on join,\n *                                                 { type: "message", message } to everyone,\n *                                                 { type: "presence", online } when people come and go\n *\n * WebSocket hibernation: the object sleeps between messages and the connections stay open, so an idle room\n * costs nothing. Its own SQLite (`ctx.storage.sql`) keeps the last 50 messages, replayed to whoever joins.\n * The same shape fits presence, live counters, a game table, a queue or a rate limit: one object per thing.\n */\nimport { DurableObject } from "cloudflare:workers";\n\nconst KEEP = 50;\n\nexport type RoomMessage = { id: number; name: string; text: string; at: number };\nexport type RoomEvent = { type: "history"; messages: RoomMessage[] } | { type: "message"; message: RoomMessage } | { type: "presence"; online: number };\n\nexport class Room extends DurableObject<unknown> {\n  constructor(ctx: DurableObjectState, env: unknown) {\n    super(ctx, env);\n    ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS messages (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, text TEXT NOT NULL, at INTEGER NOT NULL)");\n  }\n\n  async fetch(req: Request): Promise<Response> {\n    if (req.headers.get("upgrade") !== "websocket") return Response.json({ online: this.ctx.getWebSockets().length, messages: this.history() });\n    // Who is talking: the client says. Behind Sign in with Ambasada, pass the signed-in name from your route instead.\n    const name = (new URL(req.url).searchParams.get("name") ?? "").trim().slice(0, 40) || "guest";\n    const { 0: client, 1: server } = new WebSocketPair();\n    this.ctx.acceptWebSocket(server);\n    server.serializeAttachment({ name });\n    server.send(JSON.stringify({ type: "history", messages: this.history() } satisfies RoomEvent));\n    this.broadcast({ type: "presence", online: this.ctx.getWebSockets().length });\n    return new Response(null, { status: 101, webSocket: client });\n  }\n\n  async webSocketMessage(ws: WebSocket, data: string | ArrayBuffer): Promise<void> {\n    let text = "";\n    try {\n      text = String((JSON.parse(typeof data === "string" ? data : new TextDecoder().decode(data)) as { text?: unknown }).text ?? "").trim().slice(0, 2000);\n    } catch {\n      return;\n    }\n    if (!text) return;\n    const { name } = ws.deserializeAttachment() as { name: string };\n    const at = Date.now();\n    const { id } = this.ctx.storage.sql.exec<{ id: number }>("INSERT INTO messages (name, text, at) VALUES (?, ?, ?) RETURNING id", name, text, at).one();\n    this.ctx.storage.sql.exec("DELETE FROM messages WHERE id <= ?", id - KEEP);\n    this.broadcast({ type: "message", message: { id, name, text, at } });\n  }\n\n  async webSocketClose(ws: WebSocket, code: number, reason: string): Promise<void> {\n    try {\n      ws.close(code, reason);\n    } catch {\n      // already closed\n    }\n    this.broadcast({ type: "presence", online: this.ctx.getWebSockets().filter((s) => s !== ws).length });\n  }\n\n  private history(): RoomMessage[] {\n    return this.ctx.storage.sql.exec<RoomMessage>("SELECT id, name, text, at FROM messages ORDER BY id").toArray();\n  }\n\n  private broadcast(event: RoomEvent): void {\n    const text = JSON.stringify(event);\n    for (const ws of this.ctx.getWebSockets()) {\n      try {\n        ws.send(text);\n      } catch {\n        // a closing socket: webSocketClose cleans up\n      }\n    }\n  }\n}\n', "src/realtime/use-room.ts": '/**\n * `useRoom(id)`: a live room in a React component (src/realtime/room.ts on the server). Reconnects on its own.\n *\n *   const { messages, online, send, status } = useRoom("lobby", { name: "Ana" });\n */\n"use client";\nimport { useCallback, useEffect, useRef, useState } from "react";\n\nexport type RoomMessage = { id: number; name: string; text: string; at: number };\ntype RoomEvent = { type: "history"; messages: RoomMessage[] } | { type: "message"; message: RoomMessage } | { type: "presence"; online: number };\n\nexport function useRoom(id: string, options: { name?: string } = {}) {\n  const [messages, setMessages] = useState<RoomMessage[]>([]);\n  const [online, setOnline] = useState(0);\n  const [status, setStatus] = useState<"connecting" | "open" | "closed">("connecting");\n  const socket = useRef<WebSocket | null>(null);\n\n  useEffect(() => {\n    let stopped = false;\n    let retry: ReturnType<typeof setTimeout> | undefined;\n    let tries = 0;\n    const connect = () => {\n      const url = new URL(`/api/rooms/${encodeURIComponent(id)}/ws`, location.href);\n      url.protocol = url.protocol === "https:" ? "wss:" : "ws:";\n      if (options.name) url.searchParams.set("name", options.name);\n      const ws = new WebSocket(url);\n      socket.current = ws;\n      setStatus("connecting");\n      const timeout = setTimeout(() => ws.close(), 10_000); // no answer (e.g. `next dev`, which can\'t serve rooms): retry later\n      ws.onopen = () => {\n        clearTimeout(timeout);\n        tries = 0;\n        setStatus("open");\n      };\n      ws.onmessage = (e) => {\n        const event = JSON.parse(String(e.data)) as RoomEvent;\n        if (event.type === "history") setMessages(event.messages);\n        else if (event.type === "message") setMessages((m) => [...m.slice(-49), event.message]);\n        else setOnline(event.online);\n      };\n      ws.onclose = () => {\n        clearTimeout(timeout);\n        setStatus("closed");\n        if (!stopped) retry = setTimeout(connect, Math.min(30_000, 1000 * 2 ** tries++)); // back off; give up never\n      };\n    };\n    connect();\n    return () => {\n      stopped = true;\n      clearTimeout(retry);\n      socket.current?.close();\n    };\n  }, [id, options.name]);\n\n  const send = useCallback((text: string) => {\n    if (socket.current?.readyState !== WebSocket.OPEN) return false;\n    socket.current.send(JSON.stringify({ text }));\n    return true;\n  }, []);\n\n  return { messages, online, status, send };\n}\n', "tsconfig.json": '{\n  "compilerOptions": {\n    "target": "ES2022",\n    "lib": [\n      "DOM",\n      "DOM.Iterable",\n      "ES2022"\n    ],\n    "module": "ESNext",\n    "moduleResolution": "Bundler",\n    "jsx": "react-jsx",\n    "strict": true,\n    "noEmit": true,\n    "skipLibCheck": true,\n    "isolatedModules": true,\n    "allowImportingTsExtensions": true,\n    "resolveJsonModule": true,\n    "esModuleInterop": true,\n    "incremental": true,\n    "plugins": [\n      {\n        "name": "next"\n      }\n    ],\n    "allowJs": true\n  },\n  "include": [\n    "next-env.d.ts",\n    "**/*.ts",\n    "**/*.tsx",\n    ".next/types/**/*.ts",\n    ".next/dev/types/**/*.ts"\n  ],\n  "exclude": [\n    "node_modules",\n    ".open-next",\n    ".wrangler",\n    "worker.ts",\n    "src/realtime/room.ts",\n    "examples"\n  ]\n}\n', "tsconfig.worker.json": '{\n  // worker.ts and the Durable Objects run in workerd, not in Next.js: their types come from\n  // `wrangler types` (npm run typecheck writes them to node_modules/.worker-env.d.ts).\n  "compilerOptions": {\n    "target": "ES2022",\n    "lib": ["ES2022"],\n    "module": "ESNext",\n    "moduleResolution": "Bundler",\n    "strict": true,\n    "noEmit": true,\n    "skipLibCheck": true,\n    "isolatedModules": true,\n    "allowImportingTsExtensions": true,\n    "types": []\n  },\n  "files": ["node_modules/.worker-env.d.ts", "worker.ts", "src/realtime/room.ts"]\n}\n', "worker.ts": '/**\n * The Worker\'s entry (wrangler.jsonc `main`): the live rooms\' WebSockets, which Next.js can\'t answer\n * (/api/rooms/<id>/ws \u2192 src/realtime/room.ts), then everything else to the Next.js app OpenNext built.\n * Durable Object classes are exported from here.\n */\n// @ts-ignore: .open-next/worker.js is written by `opennextjs-cloudflare build`\nimport { default as nextApp } from "./.open-next/worker.js";\n\nexport { Room } from "./src/realtime/room.ts";\n\nexport default {\n  async fetch(req, env, ctx) {\n    const room = /^\\/api\\/rooms\\/([^/]+)\\/ws$/.exec(new URL(req.url).pathname);\n    if (room) return env.ROOMS.getByName(decodeURIComponent(room[1]!)).fetch(req);\n    return nextApp.fetch(req, env, ctx);\n  },\n} satisfies ExportedHandler<Env>;\n', "wrangler.jsonc": '{\n  "$schema": "node_modules/wrangler/config-schema.json",\n  // One Worker: worker.ts (live rooms, then the Next.js app built by OpenNext into .open-next/) plus static assets.\n  "name": "my-app",\n  "main": "worker.ts",\n  "compatibility_date": "2026-09-01",\n  "compatibility_flags": ["nodejs_compat"],\n  "assets": {\n    "directory": ".open-next/assets",\n    "binding": "ASSETS"\n  },\n  // Storage and realtime: env.DB (SQLite), env.KV, env.FILES and the live rooms (src/realtime/room.ts).\n  // No ids: wrangler keeps local copies in .wrangler/state; `ambasada deploy` attaches the app\'s real ones.\n  "d1_databases": [{ "binding": "DB", "database_name": "my-app", "migrations_dir": "db/migrations", "migrations_table": "_ambasada_migrations" }],\n  "kv_namespaces": [{ "binding": "KV" }],\n  "r2_buckets": [{ "binding": "FILES", "bucket_name": "my-app" }],\n  "durable_objects": { "bindings": [{ "name": "ROOMS", "class_name": "Room" }] },\n  // Every Durable Object class needs a migration; add new ones at the end, never edit or remove an applied tag.\n  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Room"] }],\n  "observability": { "enabled": true }\n}\n' }, spa: { ".claude/skills/ambasada-product/SKILL.md": "---\nname: ambasada-product\ndescription: Build an app on Ambasada and put it online. Use when the user wants to make an app, tool, game or website, start one with `npm create ambasada@latest`, run it with `ambasada dev`, publish it with `ambasada deploy` at <slug>.ambasada.dev, show it in the Ambasada app (mini app, notifications, sign-in), store data in the app's SQLite database, KV or file storage, make it realtime with Durable Objects or an agent (Agents SDK), bring a site built in ChatGPT, Lovable, Bolt or v0, or upgrade a project made with an older CLI (`ambasada upgrade`). Default stack: Next.js on Cloudflare.\n---\n\n# Build an app on Ambasada and put it online\n\nAn app is **one website** (one Cloudflare Worker) at `https://<your-slug>.ambasada.dev`. It comes with\nSign in with Ambasada (Ambasada ID), a SQLite database, key-value, file storage and Durable Objects for\nrealtime. If you want, it also gets a mini app inside the Ambasada app, with push notifications (off by default). No servers, no\nCloudflare account, no keys to configure.\n\n## Start\n\n```sh\nnpm create ambasada@latest my-app           # Next.js (default)\ncd my-app && npm install\nnpx ambasada dev                            # the mock API + your site, no login\n```\n\nOther templates: add `-- --template spa` (Vite + React; for code exported from Lovable or Bolt) or\n`-- --template worker` (plain HTML + small fetch handlers; the smallest possible app). All three have the\nsame `ambasada.config.ts`, sign-in routes, notifications webhook and storage helpers, and a notes example.\n\n## What to read\n\n| The user wants to\u2026 | Read |\n|---|---|\n| know where files go, what Next.js features are allowed, secrets, who is signed in | [reference/stack.md](reference/stack.md) |\n| store data (tables, migrations), sessions or caches, uploads; make it live between people (chat, presence, a shared board, counters); build an AI agent | [reference/storage.md](reference/storage.md) |\n| run it locally, put it online, use their own Cloudflare account | [reference/dev-and-deploy.md](reference/dev-and-deploy.md) |\n| make it look good and easy to use | [reference/design.md](reference/design.md) |\n| show up in the Ambasada app (optional: `npx ambasada miniapp enable`), send push notifications, sign people in inside the app | [reference/mini-app.md](reference/mini-app.md) |\n| build in ChatGPT, Lovable, Bolt or v0 and bring it here | [reference/build-elsewhere.md](reference/build-elsewhere.md) |\n| upgrade a project made with an older CLI | [reference/upgrading.md](reference/upgrading.md) |\n\nFor the Hack A Ton (TON payments, offerings, the agent that runs a shop): `npx ambasada add village`, then\nthe **ambasada-village** skill.\n\n## Rules (break one and the app does not work)\n\n1. **One app = one Worker.** No separate backend, no Docker. State lives in the app's SQLite (`env.DB`),\n   key-value (`env.KV`), file storage (`env.FILES`) or a Durable Object, never in module variables.\n   See [reference/storage.md](reference/storage.md).\n2. **Only the allowed Next.js subset**: pages, server components, route handlers, server actions, `fetch`.\n   No `next/image` default loader, no ISR/`revalidate`, no `fs`/`child_process`/native packages, no custom\n   server, no `middleware.ts`/`proxy.ts`, no `runtime = \"edge\"`. See [reference/stack.md](reference/stack.md#nextjs-allowed-and-banned).\n3. **Keys never reach the browser.** They live in `.env` locally and `ambasada env set` online; only server\n   code reads them. Never prefix one with `NEXT_PUBLIC_`.\n4. **Sign-in is Ambasada ID.** Use the template's `/api/auth/*` routes and `auth.user(req)`; don't add\n   Clerk, Auth.js or Supabase Auth, and don't build an accounts table. Key per-person data by `user.id`.\n5. **Tables change through migrations**: a new `db/migrations/NNNN_name.sql` per change, never edits to an\n   applied one; `npx ambasada db migrate` after deploying.\n\n## When the user is not a developer\n\nDo the work; don't ask them to edit code. Ask at most: what it does and for whom. Then build one page, run\n`npx ambasada dev`, open it, use it as the fake visitor, and show them it worked. Explain in one sentence\nper step, no jargon.\n", ".claude/skills/ambasada-product/reference/build-elsewhere.md": "# Built in ChatGPT, Lovable, Bolt or v0\n\nThree ways, easiest first.\n\n## A. Keep it hosted there, link it\n\nGood for: a site that is finished where it is and only needs to show up in the Ambasada app.\n\n1. On a laptop with Node 22+, once:\n\n   ```sh\n   npm create ambasada@latest my-app -- --miniapp --entry /   # its ambasada.config.ts and the manifest\n   cd my-app && npm install\n   npx ambasada login\n   npx ambasada link https://YOUR-SITE\n   ```\n\n2. The site must serve `/.well-known/ambasada.json` and `/icon.png` (copy them from the new project's\n   `public/`; `npx ambasada dev` writes the manifest there) and pass `npx ambasada check https://YOUR-SITE`\n   ([mini-app.md](mini-app.md)).\n\nLimit: Sign in with Ambasada, notifications and the app's database, KV and files come with hosting on\nambasada.dev. A site hosted elsewhere keeps its own backend; use B or C to get them.\n\n## B. Bring the code home (recommended for Lovable and Bolt)\n\nGood for: anything with real work behind it. You get hosting on ambasada.dev and the full rules.\n\n1. Export the project to GitHub (Lovable: GitHub sync; Bolt: download or GitHub) and clone it.\n2. `npm create ambasada@latest my-app -- --template spa` and copy the exported `src/` (components, pages,\n   styles) into the new project's `src/`, replacing the starter UI. Keep the template's `api/`, `lib/`,\n   `db/`, `ambasada.config.ts`, `wrangler.jsonc` and `vite.config.ts`.\n3. Open the project in Claude Code, Cursor or Codex and say:\n\n   > This is an Ambasada app (see .claude/skills/ambasada-product). Replace Supabase/Firebase with the\n   > app's env.DB (tables in db/migrations), env.KV and env.FILES, and any login with Sign in with Ambasada\n   > (api/auth.ts, /api/auth/me). Then run it with `npx ambasada dev`.\n\n4. `npx ambasada dev`, try it, then `npx ambasada deploy`.\n\n## C. ChatGPT (or any chat) writes the code, you paste it\n\n1. `npm create ambasada@latest my-app`, `cd my-app && npm install`, `npx ambasada dev`.\n2. Paste this into ChatGPT, then the files it mentions, then your idea:\n\n   > I have a Next.js 16 App Router project that runs on Cloudflare Workers (OpenNext). Rules: no `fs`, no\n   > native packages, no `next/image` (use `<img>`), no middleware, no `revalidate`, no other login than the\n   > one in `app/api/auth`. Data goes in SQLite through `lib/db.ts` (tables in `db/migrations/*.sql`), the\n   > signed-in person comes from `currentUser()` in `lib/ambasada.ts`. Below are my `app/page.tsx`,\n   > `app/api/notes/route.ts` and `db/migrations/0001_init.sql`. Rewrite them for my idea: the main action\n   > visible on a phone without scrolling. Write complete files, one code block per file, with the file path\n   > above each. My idea: \u2026\n\n3. Paste each file where ChatGPT says, keep `npx ambasada dev` running, check the page. New tables: a new\n   file in `db/migrations/` (never edit an applied one). When it works: `npx ambasada deploy` and\n   `npx ambasada db migrate`.\n\nUse ChatGPT to write files, not to decide the stack: if its answer adds Prisma, Supabase, NextAuth,\n`next/image` or a `middleware.ts`, tell it \"that's banned in my project, do it without\".\n", ".claude/skills/ambasada-product/reference/design.md": '# Design for people who decide in 10 seconds\n\nPeople open your app on a phone, often inside the Ambasada app, between two other things. They decide in\nseconds whether it is for them. Build for that.\n\n## One page, one action\n\n- **One page first.** What it is, and the one thing to do, fit on the first screen of a phone (375 \xD7 667).\n  Extra pages only when the action needs them.\n- **One action.** One button that does the main thing. Add a second only after people use the first.\n- **Few words.** A headline of up to 8 words, one sentence under it, the button. Cut every adjective you can.\n- **Show the result.** One example of what people get (an image, a sample text) beats any description.\n- **No walls.** No signup before the first use, no cookie banner, no tour. Ask for sign-in when the app\n  needs to remember someone (Sign in with Ambasada is one tap inside the Ambasada app).\n\n## The button\n\n- Label it with the action: **Make my poem**, not **Submit**.\n- Big (at least 48 px tall), full width on phones, one strong colour, nothing else in that colour.\n- If people must type something first, put that one field right above the button.\n- After the action, show the result, or "Working on it\u2026" and the result appearing when ready (a live room\n  or polling). Never a blank page.\n\n## Look\n\n- The templates use `@ambasada/ui` (the Ambasada app\'s look: tokens, `ui-card`, `ui-button`); start there\n  ([mini-app.md](mini-app.md)). Otherwise plain CSS: one font, two colours plus grey, generous spacing.\n- Large text: 18 px body on phones, a headline twice that. Light theme.\n- Works with one thumb: tap targets 48 px, no hover-only menus.\n- Loads fast: no video backgrounds, no 3 MB hero images, no animation libraries.\n\n## Words\n\n- Say what they get, not how it works. "A logo in 1 minute", not "AI-powered logo generation".\n- Write in the language of your users; one is fine.\n\n## Before and after\n\n```\nBad:  Welcome to PoemForge\u2122, the next-generation AI-powered creative writing platform\n      [Features] [Pricing] [About] [Sign up]   \u2026scroll\u2026   [Get started]\n\nGood: Your name as a folk poem\n      Type a name. Get a 4-line Romanian folk poem in 10 seconds.\n      [ Name: _________ ]\n      [   Make my poem   ]\n      "Ana, floare de la munte, / \u2026"  \u2190 one real example\n```\n', ".claude/skills/ambasada-product/reference/dev-and-deploy.md": "# Run it, put it online\n\n## `ambasada dev`: everything on your laptop\n\n```sh\nnpx ambasada dev\n```\n\nStarts two things:\n\n1. a **mock Ambasada API** on `http://127.0.0.1:8788`: same routes and signatures as the real one. Sign in\n   with Ambasada signs you in as \"Fake Visitor\"; `apps.notify` lands in a fake hub; `ambasada.store` and\n   `ambasada.files` work in memory. Open it in a browser for a page with what happened.\n2. **your site** with its normal dev server (`next dev`, `vite` or `wrangler dev`), pointed at the mock.\n\nNo login. The app's database, KV, files and Durable Objects run locally too (wrangler, `.wrangler/state`);\n`ambasada dev` applies `db/migrations/` to the local database before it starts the site.\n\nTry it: open your site, sign in, add a note. With the mini app on, `http://localhost:3000/app?ambasada_shell=mock`\n(your `miniapp.entry`) pretends to be inside the Ambasada app (host bar insets, silent sign-in).\n\n`npx ambasada dev --mock-only` starts only the mock, if you run your site yourself. The mock's keys:\n`AMBASADA_API_URL=http://127.0.0.1:8788`, `AMBASADA_API_KEY=sk_test_dev` (already in the project's `.env`).\n\n## `ambasada deploy`: online at `<slug>.ambasada.dev`\n\nOnce, in the app's folder:\n\n```sh\nnpx ambasada login        # opens a page: sign in with Ambasada ID\n```\n\n(If it asks for a key instead: https://developer.ambasada.dev \u2192 your app \u2192 a project key, `vk_\u2026`.)\nEach app's key is kept under its id: with two apps on one laptop, log in once in each folder, and each folder uses\nits own. `deploy`, `db`/`kv`/`files`, `env`, `logs`, `tunnel` and the village's commands that change something refuse\na key of another app than the folder's `id` (\"this folder is X, you are logged in as Y\"); `--company Y` goes ahead.\n\nThen, every time you want the new version online:\n\n```sh\nnpx ambasada deploy\n```\n\nIt does, in order:\n\n1. **build**: `opennextjs-cloudflare build` (Next), `vite build` (spa) or a bundle of the Worker (worker);\n2. **smoke test**: runs the built Worker locally in workerd and requests `/` and `/.well-known/ambasada.json`\n   (written from `ambasada.config.ts` first, when the mini app is on: [mini-app.md](mini-app.md));\n   a crash stops the deploy (skip with `--no-smoke` only if you know why it fails);\n3. **upload**: the URL is `https://<your-slug>.ambasada.dev`, with `AMBASADA_API_KEY`, `AMBASADA_API_URL`,\n   Sign in with Ambasada and the app secret set for you, and the app's own database, KV namespace and bucket\n   bound as `DB`, `KV`, `FILES` (created on the first deploy) plus the Durable Objects from `wrangler.jsonc`.\n\nThe database's tables are not created by the deploy: run `npx ambasada db migrate` (it applies the new files\nin `db/migrations/`). No Cloudflare account needed. `--dry-run` builds and prints what it would upload.\n\nYour own secrets (an API key for another service): `npx ambasada env set NAME value` (live within about 30 s, and on\nevery deploy); `npx ambasada env list` shows the names.\n\nLimits: 10 MB compressed bundle, 1000 static files, short CPU time per request (waiting on `fetch` does not\ncount). Heavy work belongs in an API you call, or a Durable Object, not in one request.\n\n## `ambasada dev --tunnel`: your laptop, live\n\nWhen the Ambasada app, sign-in or webhooks need to reach the version on your laptop (before deploying, or to\ndebug), log in once, then:\n\n```sh\nnpx ambasada dev --tunnel         # your dev server, against the real API, at https://<slug>-dev.ambasada.dev\nnpx ambasada tunnel --port 5173   # or: only the tunnel, for a server you started yourself\n```\n\nUntil Ctrl+C, `https://<slug>-dev.ambasada.dev` is your app's URL. There is no mock in this mode. The first\ntime takes up to 2 minutes while the address is published; after that it is instant. Only one terminal per\napp at a time: `--force` takes it over. More: docs/TUNNEL.md.\n\n## `ambasada deploy --own`: your own Cloudflare account\n\nRuns `wrangler deploy` into your account (you need `npx wrangler login` first), then\n`ambasada link <your workers.dev URL>`. Set the secrets yourself: `npx wrangler secret put AMBASADA_API_KEY`.\n\n## `ambasada link`: the app is hosted somewhere else\n\n```sh\nnpx ambasada link https://my-thing.lovable.app\n```\n\nSets `product.url` in `ambasada.config.ts` and checks that `<url>/health` answers. Use it for Lovable, Bolt,\nv0, Vercel, your own server. See [build-elsewhere.md](build-elsewhere.md).\n\n## Watch it run\n\n```sh\nnpx ambasada logs --follow     # the last deploy and new errors\nnpx ambasada check https://<slug>.ambasada.dev   # https, no redirects, speed; the mini-app rules when it is on\n```\n\nThe Developer app (https://developer.ambasada.dev) has deploys, errors, users and the storage tabs.\n\n## Upgrading\n\nA new devkit: `npx ambasada upgrade` (dependencies, skills, mechanical code changes), then\n[upgrading.md](upgrading.md) for the steps a coding agent does.\n\n## When it goes wrong\n\n| Symptom | Fix |\n|---|---|\n| build fails on `fs`, `child_process`, a `.node` file, `sharp` | a banned package: see [stack.md](stack.md#nextjs-allowed-and-banned) |\n| smoke test: `/` answers 500 | open `npx ambasada dev`, load `/`, read the terminal error |\n| `no such table: \u2026` online | `npx ambasada db migrate` |\n| a Durable Object migration is refused on deploy | never edit or remove a deployed tag in `wrangler.jsonc`'s `migrations`; add the next one ([storage.md](storage.md)) |\n| `CONFIG: no API key` | missing `AMBASADA_API_KEY`: `.env` locally, `ambasada login` before deploying |\n| sign-in loops back to the login page | `PUBLIC_URL` differs from the URL in the browser; remove it or fix it |\n| `this app uses the village \u2026 not installed` | a Hack A Ton project: `npx ambasada upgrade` (adds `@ambasada/village`) |\n", ".claude/skills/ambasada-product/reference/mini-app.md": '# The app inside the Ambasada app (mini app)\n\n**Optional, opt in with `npx ambasada miniapp enable`** (or `npm create ambasada@latest my-app -- --miniapp`). An app\nis a website first; most stay that way. The mini app is one more surface of it, at a path: what the Ambasada mobile\napp opens, with silent sign-in and push notifications. Platform spec: docs/MINI-APPS.md (\xA715, decision 15.6).\n\n## Turn it on\n\n```sh\nnpx ambasada miniapp enable              # at /app; --entry /in-app for another path, --entry / for the whole site\nnpx ambasada miniapp                     # on or off, and the entry\nnpx ambasada miniapp enable --entry /app --force   # move it: --force removes what the old entry left (it lists them otherwise)\n```\n\nIt adds:\n\n| | |\n|---|---|\n| `miniapp: { entry: "/app", age_rating: "4+", kind: "tool" }` | `ambasada.config.ts`; optional `support` (email or URL, else the app\'s `support`), `tags` (\u2264 5), `subtitle`, `description`, `icon`, `category`, `accent`, `scopes`, `visibility`. The hub refuses an app without `age_rating` (`4+`, `9+`, `12+`, `17+`) |\n| the in-app layout and page, no site header | `app/app/` (Next), `src/in-app/InApp.tsx` rendered by `src/main.tsx` (spa), `web/app.html` (worker) |\n| `ready()` and silent sign-in | `app/app/in-app.tsx`, `src/in-app/shell.ts`, `web/in-app.js`; with `--entry /` hooked into the root layout instead |\n| a placeholder icon, 1024\xD71024 | `public/icon.png` (`web/icon.png`): replace it, keep it square and opaque |\n| `@ambasada/miniapp` | `package.json` (Next, spa): run `npm install` |\n\nThe manifest, `/.well-known/ambasada.json`, is not a file you keep: `ambasada dev` and `ambasada deploy` write it\nfrom `ambasada.config.ts` (id, name, description, `miniapp`) into `public/` (`web/`), and `.gitignore` leaves it out.\nTo write it by hand, put your own there and drop that `.gitignore` line: yours wins. Without `miniapp`, nothing is\nserved, `ambasada check` says "mini app: off" and the deploy does not register the app with the Ambasada app.\n\n## Is it listed?\n\n`ambasada deploy` registers the app with the Ambasada hub only when it serves the manifest, then checks it. It prints:\n\n```\n\u2713 in the Ambasada app: Listed for the event\n! in the Ambasada app: Unlisted \xB7 needs: icon, viewport\n  mini app: off, not in the Ambasada app (`ambasada miniapp enable` adds one)\n```\n\nUnlisted apps work, but only you see them in the Ambasada app. Fix what `needs` says and deploy again,\nor run `npx ambasada check https://<slug>.ambasada.dev` (or `npx ambasada check` for the local folder).\nThe checks: `/.well-known/ambasada.json` valid, `icon.png` a 1024\xD71024 PNG with no transparency, the entry page\nhas `<meta name="viewport" content="width=device-width, initial-scale=1">`, no dark-only theme, it answers in under\n3 s without a redirect, `/api/auth/callback` exists, the notifications webhook answers a signed ping. With the mini\napp off, only https, no redirects and the response time of `/`.\nConnected tools can do the same through MCP: `app_status`, `app_check`.\n\n## Look like the app: @ambasada/ui\n\nThe templates import `@ambasada/ui` (tokens, Inter + JetBrains Mono, `ui-card`, `ui-button`, `ui-row`,\n`ui-pill`, `ui-sheet`, `ui-stepper`, `ui-empty`, `ui-skeleton`). Use those classes before writing CSS.\nReact: `import { Card, Button, Sheet } from "@ambasada/ui/react"`. Plain HTML: one\n`<link rel="stylesheet" href="https://unpkg.com/@ambasada/ui@0.8/dist/ambasada-ui.css">`.\nLeave space for the app\'s bar: the page uses `--ambasada-safe-area-*` and `--ambasada-host-bar`.\nLight theme only; one red (primary) button per screen.\n\n## Notifications\n\nAlready wired in every template; they work once the mini app is on:\n\n| Piece | Where |\n|---|---|\n| manifest: `"scopes": ["identity", "notifications"]`, `"notifications": { "webhook": "/api/ambasada/webhook" }`, `"privacy_url": "/privacy"` | generated from `ambasada.config.ts` (the defaults; `miniapp.scopes` to change them) |\n| the webhook: verifies the hub\'s signature, saves `token \u2194 Ambasada user id` in `ambasada.store` | `app/api/ambasada/webhook/route.ts` (Next), `api/ambasada-webhook.ts` (spa, worker) |\n| `notifyUser(app, userId, { \u2026 })`: push to one person if they turned notifications on | `lib/notifications.ts` |\n| the privacy page the scopes need | `app/(site)/privacy/page.tsx`, `public/privacy.html`, `web/privacy.html` |\n\nSend one when something the person waits for happens (their order is ready), never as marketing:\n\n```ts\nimport { notifyUser } from "../lib/notifications.ts";\n\nconst user = await ambasada().auth.user(req);            // signed in with Ambasada\nif (user) await notifyUser(ambasada(), user.id, {\n  notification_id: `order-${id}-ready`,                  // unique per message; repeats are dropped for 24 h\n  title: "Your translation is ready",                    // \u2264 40 characters\n  body: "Tap to read it.",                               // \u2264 140\n  url: `/orders/${id}`,                                  // a path on your site: where the tap opens\n});\n```\n\nPeople turn notifications on in the app (the app asks; the page can ask too with\n`notifications.request()` from `@ambasada/miniapp`, from a button). The secret (`AMBASADA_APP_SECRET`) is\ninjected by `ambasada deploy`; never put it in the browser.\n\n## Signed in without a consent screen\n\nInside the Ambasada app the page signs in silently: `auth.signIn()` from `@ambasada/miniapp` gets a short\ntoken from the app and POSTs it to `/api/auth/shell`, which sets the same session as "Sign in with\nAmbasada". Server code doesn\'t change: `currentUser()` / `ambasada().auth.user(req)` work either way.\nOn the web, the button and consent screen stay. Silent sign-in needs the app to be Verified; until then\n`signIn()` resolves `null` and the button shows.\n\n## Try it locally\n\n`npx ambasada dev` plays the hub (with the mini app on): when your app starts it sends a signed `ping` and\n`notifications_enabled` to your webhook (the token lands in the store as\n`ambasada/notifications/user_fake_visitor`), and its `/api/apps/notify` accepts pushes for that token\n(they show in the terminal). Open `http://localhost:3000/app?ambasada_shell=mock` (your entry) to pretend to be\ninside the app: the fake shell signs you in silently as "Fake Visitor".\n', ".claude/skills/ambasada-product/reference/stack.md": '# The stack: Next.js on Cloudflare\n\nEvery Ambasada app is one Cloudflare Worker. The default template builds it from **Next.js 16.4**\nwith **@opennextjs/cloudflare 1.20** (the OpenNext adapter) and the `nodejs_compat` flag. You write a\nnormal Next.js App Router app; `ambasada deploy` turns it into a Worker.\n\n## Folder layout (template `next`)\n\n```\nmy-app/\n  app/layout.tsx               <html>, the Ambasada look (@ambasada/ui) and globals.css\n  app/(site)/layout.tsx        the site\'s header (app/account.tsx) around its pages; (site) is not in the URL\n  app/(site)/page.tsx          the landing page\n  app/notes.tsx                the notes example (a client component calling app/api/notes)\n  app/api/notes/route.ts       rows in env.DB, the list cached in env.KV\n  app/api/files/route.ts       uploads to env.FILES; app/files/[...key]/route.ts serves them\n  app/api/auth/*/route.ts      Sign in with Ambasada: login, callback, logout, me, shell (silent, in the app)\n  app/api/ambasada/webhook/    the Ambasada app\'s events: who turned notifications on (reference/mini-app.md)\n  app/account.tsx              the header: "Sign in with Ambasada", or the person\'s name and avatar\n  app/(site)/privacy/page.tsx  what you keep about people (the mini app\'s privacy_url)\n  app/(site)/room/             the live room demo\n  app/app/                     the mini app, once on (`ambasada miniapp enable`): its layout, page and in-app.tsx\n  lib/ambasada.ts              the Ambasada client for server code (reads the Worker env)\n  lib/notifications.ts         notifyUser(): a push to one person who turned notifications on\n  lib/db.ts, kv.ts, files.ts   env.DB, env.KV, env.FILES (reference/storage.md); lib/bindings.ts reaches them\n  db/migrations/               the database\'s tables, one .sql file per change\n  src/realtime/                the live room (a Durable Object) and its React hook\n  ambasada.config.ts           app id, name, one-line description, product URL, `miniapp` (optional)\n  wrangler.jsonc               Worker settings (nodejs_compat, assets) and the bindings DB, KV, FILES, ROOMS\n  worker.ts                    the Worker entry: live rooms\' WebSockets, then the Next.js app\n  open-next.config.ts          OpenNext settings; leave as is\n  .env                         secrets for local runs (never commit, never send to the browser)\n  .ambasada/project.json       the template and devkit version (`ambasada upgrade` reads it); commit it\n  .claude/skills/              this skill\n```\n\nOne more endpoint = one more `app/api/<name>/route.ts`. Data it keeps goes in `env.DB` (a migration in\n`db/migrations/`), `env.KV` or `env.FILES` ([storage.md](storage.md)).\n\n## Using the client\n\nServer code only (route handlers, server components, server actions):\n\n```ts\n// app/api/hello/route.ts\nimport { ambasada } from "../../../lib/ambasada.ts";\n\nexport async function GET(req: Request) {\n  const user = await ambasada().auth.user(req);\n  return Response.json({ hello: user?.name ?? "stranger" });\n}\n```\n\n`lib/ambasada.ts` creates one client per Worker instance with `createAmbasada({ env })` from `@ambasada/sdk`,\nwhere `env` comes from `getCloudflareContext()` (deployed); under `next dev` the SDK reads `process.env`.\nIt reads `AMBASADA_API_KEY` and `AMBASADA_API_URL` (default https://api.ambasada.dev). The client has `auth`\n(below), `apps` (notifications, [mini-app.md](mini-app.md)), `store` and `files`.\n\n## Who is signed in\n\nEvery hosted app gets **Sign in with Ambasada** (Ambasada ID) for free: no keys, no settings.\nThe template\'s header already has the button. In server code:\n\n```ts\nimport { currentUser } from "../lib/ambasada.ts";\nimport { bindings } from "../lib/bindings.ts";\nimport { run } from "../lib/db.ts";\n\nconst user = await currentUser(); // null, or { id, name, avatar_url, builder, pass, member_since, \u2026 }\nif (!user) redirect("/api/auth/login?returnTo=/orders");\nawait run(bindings().DB, "INSERT INTO orders (user_id, item) VALUES (?, ?)", user.id, item); // key per-person data by user.id\n```\n\nIn a route handler, `ambasada().auth.user(req)` does the same. Client components fetch `/api/auth/me`.\nAsk for the email only if you need it: `/api/auth/login` calls `auth.login(req, { email: true })`.\nDon\'t build your own login or accounts table, and don\'t add Clerk, Auth.js or Supabase Auth.\n\n## Next.js: allowed and banned\n\nAllowed, and enough for any product here:\n\n- pages and layouts (`app/**/page.tsx`, `layout.tsx`), server components, client components (`"use client"`)\n- route handlers (`app/api/**/route.ts`), server actions (`"use server"`)\n- `fetch` to any HTTPS API, `next/link`, `next/font`, plain CSS / CSS modules / Tailwind\n\nBanned (they fail on Workers or break the deploy):\n\n| Don\'t | Do instead |\n|---|---|\n| `next/image` with the default loader | `<img>`, or `images: { unoptimized: true }` in `next.config.ts` |\n| ISR, `export const revalidate = \u2026`, `revalidatePath`, `unstable_cache` | render on each request (`export const dynamic = "force-dynamic"`), or cache results in `env.KV` |\n| `fs`, `child_process`, `sharp`, `bcrypt`, `sqlite3`, `puppeteer`, any native package | `fetch` an API (an LLM provider with your own key in a secret, for example) |\n| a custom server (`server.js`, Express inside Next) | route handlers |\n| `middleware.ts` / `proxy.ts`, `export const runtime = "edge"` | check inside the page or route handler; Next\'s default runtime is right |\n| Prisma, Drizzle with a database, Supabase, Firebase, Mongo, Redis | `env.DB` (SQLite), `env.KV`, `env.FILES` ([storage.md](storage.md)) |\n| writing files at runtime, global variables as storage | `env.DB`, `env.KV`, `env.FILES` or a Durable Object (each request can run on a different machine) |\n\nKeep the bundle small: the Worker limit is 10 MB compressed. Big UI kits and icon packs are the usual cause.\n\n## Where data lives\n\nThe app has its own SQLite database (`env.DB`), key-value (`env.KV`), file storage (`env.FILES`, public at\n`/files/<key>`) and Durable Objects for live state, created at the first deploy. Which one fits, the migrations\nworkflow and copy-paste patterns: [storage.md](storage.md).\n\nAlso there, for small things: `ambasada.store` (JSON, 1 MB for the whole app: settings, not user data) and\n`ambasada.files.put(\u2026)` \u2192 `{ url }` (platform-hosted files that expire).\n\n## Secrets\n\n- Local: `.env` in the project (Cloudflare\'s `.dev.vars` works too). The template writes it with test\n  values for `ambasada dev`. Both are in `.gitignore`; keep them there.\n- Deployed: `ambasada deploy` injects `AMBASADA_API_KEY`, `AMBASADA_API_URL`, the Sign in with Ambasada\n  credentials (`AMBASADA_AUTH_*`) and the mini-app secret (`AMBASADA_APP_SECRET`, with `AMBASADA_HUB_URL`\n  and `AMBASADA_APP_ORIGIN`) for you. With `--own`, set them yourself: `npx wrangler secret put AMBASADA_API_KEY`.\n- Other services\' keys (an OpenAI key, say): `.env` locally, `npx ambasada env set OPENAI_API_KEY \u2026` online;\n  read on the server only.\n- Anything named `NEXT_PUBLIC_*` is copied into the browser. Never put a key there.\n- Never paste a key into a page, a client component, a prompt for a no-code builder, or a commit.\n\n## Variants\n\n- `spa`: Vite + React with `@cloudflare/vite-plugin`, for code exported from Lovable or Bolt. The\n  `api/` endpoints are small fetch handlers; the React app calls them with `fetch("/api/\u2026")`.\n- `worker`: `web/` (plain HTML/CSS) plus `api/*.ts` fetch handlers. Best when the app is a page or two.\n\nThe rules on this page (state, secrets, no native packages) apply to all three.\n', ".claude/skills/ambasada-product/reference/storage.md": '# Data, files and realtime\n\nEvery app on ambasada.dev gets a real database, key-value, file storage and Durable Objects. They are created\nat the first `ambasada deploy` and bound to the Worker on every deploy; nothing to sign up for or configure.\nLocally (`ambasada dev`, `wrangler dev`, `vite`) wrangler runs the same things from `.wrangler/state`.\n\n| Need | Use | Not |\n|---|---|---|\n| anything with rows: users\' data, orders, posts, scores, anything you query, sort or join | `env.DB` (SQLite, D1) | KV, files, `ambasada.store` |\n| sessions, caches of slow results, feature flags, "seen this already" | `env.KV` | a table you scan |\n| uploads, images, audio, PDFs, generated files | `env.FILES` (R2), public at `/files/<key>` | base64 in the database |\n| state several people see change live: chat, presence, a shared board, a game table, live counters, a queue, rate limits, one thing per entity | a Durable Object (`env.ROOMS` in the templates) | polling the database |\n| an AI agent with memory, schedules and live state per user or task | the Agents SDK (`examples/agent/`) | a cron that rereads everything |\n| a few small settings for a tiny app | `ambasada.store` (1 MB per app) | user data of any size |\n\nQuotas per app: database 500 MB, KV 1 GB, files 5 GB. A database over its quota stops the next deploy.\n\n## `env.DB`: SQLite\n\nSchema lives in `db/migrations/`, one file per change, applied in name order, never edited once applied:\n\n```sql\n-- db/migrations/0002_orders.sql\nCREATE TABLE orders (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  user_id TEXT NOT NULL,\n  item TEXT NOT NULL,\n  paid INTEGER NOT NULL DEFAULT 0,\n  created_at INTEGER NOT NULL\n);\nCREATE INDEX orders_user ON orders (user_id, created_at);\n```\n\n```sh\nnpx wrangler d1 migrations apply DB --local   # the local database, for ambasada dev\nnpx ambasada db migrate                       # the app\'s database online (run before or right after deploying)\nnpx ambasada db shell "SELECT * FROM orders LIMIT 5"\n```\n\nQuery with `lib/db.ts` (SQL with `?` placeholders, typed rows, no ORM):\n\n```ts\nimport { all, batch, first, run } from "../lib/db.ts";\n\ntype Order = { id: number; user_id: string; item: string; paid: number; created_at: number };\nconst mine = await all<Order>(env.DB, "SELECT * FROM orders WHERE user_id = ? ORDER BY created_at DESC LIMIT 50", user.id);\nconst one = await first<Order>(env.DB, "SELECT * FROM orders WHERE id = ?", id);\nconst { lastRowId } = await run(env.DB, "INSERT INTO orders (user_id, item, created_at) VALUES (?, ?, ?)", user.id, item, Date.now());\nawait batch(env.DB, [["UPDATE stock SET n = n - 1 WHERE item = ?", item], ["UPDATE orders SET paid = 1 WHERE id = ?", id]]); // all or nothing\n```\n\nIn Next.js route handlers and server components, the bindings come from `bindings()` (`lib/bindings.ts`):\n`const { DB } = bindings();`. In the spa and worker templates, handlers get `env`.\n\nRules: always placeholders, never string-built SQL. Key per-person rows by the Ambasada user id\n(`auth.user(req).id`). Add an index for every `WHERE` you run often. Times as `Date.now()` integers.\n\n## `env.KV`: sessions, caches, flags\n\nReads are fast everywhere; a write shows up everywhere within about a minute; one write per second per key.\n\n```ts\nimport { cached, getJson, putJson } from "../lib/kv.ts";\n\nawait putJson(env.KV, `session:${id}`, { userId }, { ttl: 60 * 60 * 24 });\nconst session = await getJson<{ userId: string }>(env.KV, `session:${id}`);\nconst stats = await cached(env.KV, "home:stats", 300, () => computeStats(env)); // recompute at most every 5 min\n```\n\nNot for counters, balances or anything two people write at once: use `env.DB` (a transaction) or a Durable Object.\n\n## `env.FILES`: uploads and generated files\n\n```ts\nimport { serveFile, upload } from "../lib/files.ts";\n\n// POST /api/files: a signed-in person uploads (the templates\' api/files.ts)\nconst { key, url } = await upload(env.FILES, req.body, { contentType: req.headers.get("content-type") ?? undefined, folder: `u/${user.id}` });\nawait run(env.DB, "INSERT INTO photos (user_id, file_key) VALUES (?, ?)", user.id, key); // keep the key, not the bytes\n\n// GET /files/*: already wired in every template, with ETag, ranges and cache headers\nreturn serveFile(env.FILES, req);\n```\n\n`url` is `/files/<key>` on the app (`https://<slug>.ambasada.dev/files/<key>`): public to anyone with the link.\nPrivate files: store them under a key nobody can guess and serve them from your own route that checks\n`auth.user(req)` first, instead of `/files/*`. `npx ambasada files list | put | url | delete` from the terminal.\n\n## Durable Objects: realtime and per-entity state\n\nA Durable Object is one tiny server per id (a room, a document, a match, a user) with its own SQLite, that\nevery request for that id reaches. Use one whenever people must see each other\'s changes live, or one thing\nmust never be updated by two requests at once. The templates ship `src/realtime/room.ts` (`env.ROOMS`):\n\n```ts\n// the Worker: /api/rooms/<id>/ws \u2192 the room\nconst room = /^\\/api\\/rooms\\/([^/]+)\\/ws$/.exec(pathname);\nif (room) return env.ROOMS.getByName(decodeURIComponent(room[1]!)).fetch(req);\n```\n\n```ts\n// the room (shortened): WebSocket hibernation, broadcast, its own SQLite\nexport class Room extends DurableObject<unknown> {\n  async fetch(req: Request) {\n    const { 0: client, 1: server } = new WebSocketPair();\n    this.ctx.acceptWebSocket(server);              // hibernation: no cost while nobody talks\n    server.serializeAttachment({ name: "guest" }); // per-connection data that survives hibernation\n    return new Response(null, { status: 101, webSocket: client });\n  }\n  async webSocketMessage(ws: WebSocket, data: string | ArrayBuffer) {\n    this.ctx.storage.sql.exec("INSERT INTO messages (text, at) VALUES (?, ?)", String(data), Date.now());\n    for (const peer of this.ctx.getWebSockets()) peer.send(String(data)); // everyone in the room\n  }\n}\n```\n\n```tsx\n// the browser (React): src/realtime/use-room.ts\nconst { messages, online, send, status } = useRoom(roomId, { name: user.name });\n```\n\nA new class needs a binding and a migration in `wrangler.jsonc` (new tags go at the end; never edit or remove one\nthat was deployed; to drop a class add `{ "tag": "v3", "deleted_classes": ["Old"] }`):\n\n```jsonc\n"durable_objects": { "bindings": [{ "name": "ROOMS", "class_name": "Room" }, { "name": "BOARDS", "class_name": "Board" }] },\n"migrations": [{ "tag": "v1", "new_sqlite_classes": ["Room"] }, { "tag": "v2", "new_sqlite_classes": ["Board"] }]\n```\n\nExport the class from the Worker\'s entry (`src/worker.ts`; spa `worker/index.ts`; next `worker.ts`).\nOther shapes, same pattern: presence (who is online), a live counter (`UPDATE \u2026 RETURNING`, then broadcast), a\nper-user rate limit (`getByName(user.id)`), a job queue (`this.ctx.storage.setAlarm`). A Durable Object belongs\nto this app; other apps can\'t reach it. Under `next dev` they don\'t run: use `npm run preview` (workerd).\n\n## Agents (Agents SDK)\n\nFor agentic products (an assistant per user, a research task that runs for minutes, a bot that follows up),\nuse the Cloudflare Agents SDK: `examples/agent/` in the template (`npm i agents`, four lines to wire). An agent\nis a Durable Object with live state synced to clients (`setState`, `useAgent` in React), `this.sql`,\n`this.schedule(\u2026)` and WebSockets. One agent per user or task: `/agents/agent-example/<user id>`.\n\n## Don\'t\n\n- Poll (`setInterval(fetch\u2026)`) for what others changed: a Durable Object + WebSocket pushes it.\n- Put files or base64 in the database or KV: `env.FILES`, and keep the key in a row.\n- Keep user data in `ambasada.store`: it is 1 MB for the whole app.\n- Keep state in module variables or global objects: every request may run on another machine.\n- Count, rank or move money in KV: use a SQL transaction (`batch`) or a Durable Object.\n- Build SQL by joining strings with user input: `?` placeholders.\n- Edit an applied migration: add the next file.\n- Add Prisma, Drizzle with Postgres, Supabase, Firebase, Mongo or Redis: everything above is already here.\n', ".claude/skills/ambasada-product/reference/upgrading.md": "# Upgrading a project\n\n`npx ambasada upgrade` does the mechanical part: every `@ambasada/*` dependency to the CLI's version, the\npackage manager, `.claude/skills/ambasada-*` re-synced (the project's own skills are left alone), the code\nchanges listed below as \"done by `upgrade`\", the `ambasada check` rules, and `.ambasada/project.json`\n(the template and devkit version). `npx ambasada upgrade --check` only reports.\n\nWhat is left is below, per version, for a coding agent. Do the steps for every version between the one in\n`.ambasada/project.json` (none: 0.7) and the current one, in order. After each, run the app with\n`npx ambasada dev` and the project's `typecheck` script.\n\n## 0.7 \u2192 0.8: the platform and the village split\n\n0.8 splits the devkit: `@ambasada/sdk` and `ambasada` are the platform (sign-in, notifications, storage,\nhosting); the Hack A Ton economy (TON, checkout, offerings, the agent) is the add-on `@ambasada/village`.\n\nDone by `upgrade`:\n\n- the village names (`village`, `createVillage`, `offering`, `defineCompany`, `isVillageError`, the receipt and\n  webhook helpers, their types) import from `@ambasada/village`; in a village app `createAmbasada` became\n  `createVillage` and `DEFAULT_API_URL` became `DEFAULT_VILLAGE_API_URL` (their 0.7 meaning);\n- `@ambasada/village` added to `package.json` when the app has `offerings.ts` or an `idea`;\n- `.env` / `.dev.vars`: `AMBASADA_API_URL=https://hackaton.ambasada.id` became `https://api.ambasada.dev` plus\n  `AMBASADA_VILLAGE_API_URL=https://hackaton.ambasada.id`;\n- the `ambasada-payments` skill replaced by `ambasada-village`.\n\nFor the agent:\n\n1. **Platform code uses the platform client.** Files that only sign people in, send notifications or use\n   `store`/`files` can import `createAmbasada` / `ambasada` from `@ambasada/sdk` instead of the village client.\n   Leave files that sell, check receipts or call `llm` on the village client.\n2. **Config.** `ambasada.config.ts` may stay `defineCompany({ id, name, idea, \u2026 })`; the 0.8 form is\n   `defineCompany(defineApp({ id, name, description, product }), { idea, offerings, agent })` with\n   `defineApp` from `@ambasada/sdk`. Add a one-line `description` (the manifest's subtitle).\n3. **CLI calls.** In scripts, READMEs and `package.json`: `ambasada wallet|ledger|offerings|market|steer|webhook|links`\n   \u2192 `ambasada village \u2026`, `ambasada logs --agent` \u2192 `ambasada village logs --agent`, `ambasada dev buy` \u2192\n   `ambasada village dev buy`. The old spellings still work through 1.x with a warning.\n4. **Pages that load pay.js** from `AMBASADA_API_URL` should use the village client's `apiUrl` (or\n   `AMBASADA_VILLAGE_API_URL`): `AMBASADA_API_URL` is the platform's from 0.8.\n5. **Login.** The CLI's login moved from `~/.config/village` to `~/.config/ambasada` (moved on first use);\n   nothing to do unless a script reads that file.\n6. Run `npx ambasada check`, `npx ambasada dev` and the typecheck; deploy when they pass.\n", "README.md": "# My App\n\nAn app on Ambasada, Vite + React on one Cloudflare Worker (template `spa`): sign-in with Ambasada ID, a database,\nkey-value, files and live rooms; a mini app inside the Ambasada app if you want one. Everything here is a default;\nchange anything.\n\n```\nambasada.config.ts          id, name, one-line description, where the app runs\nsrc/                        the React app (drop a Lovable/Bolt export here); src/App.tsx has the header and the notes example\nworker/index.ts             the Worker: /api/<name> \u2192 api/<name>.ts, everything else is the app\napi/auth.ts                 Sign in with Ambasada (login, callback, logout, me, shell)\napi/ambasada-webhook.ts     the Ambasada app's events (notifications on/off); lib/notifications.ts sends pushes\napi/notes.ts, api/files.ts  env.DB + env.KV, uploads to env.FILES\nlib/ambasada.ts             the SDK client from the Worker's env\nlib/db.ts, kv.ts, files.ts  env.DB, env.KV, env.FILES; db/migrations/ the tables\nsrc/realtime/               the live room (a Durable Object) and its React hook\nvite.config.ts, wrangler.jsonc   @cloudflare/vite-plugin: `vite` runs the app and the Worker together\n.claude/skills/             docs your coding agent reads (ambasada-product)\n```\n\n## 1. Run it (2 min)\n\nNeeds Node \u2265 22.\n\n```sh\nnpm install\nnpm run dev                # `ambasada dev`: the mock Ambasada API on :8788 + `vite` on http://localhost:3000\n```\n\nOpen http://localhost:3000: add a note, sign in (the mock signs you in as \"Fake Visitor\"), open /room in two tabs.\nhttp://127.0.0.1:8788 is the mock's page (sign-ins, notifications, the store). `ambasada dev` points your app at the\nmock whatever `.env` says.\n\n## 2. Make it yours\n\n- `ambasada.config.ts`: name and description.\n- A new endpoint: `api/<name>.ts` (and a line in `worker/index.ts`). Data goes in `env.DB` (a migration in `db/migrations/`), `env.KV` or `env.FILES`.\n- Ask your coding agent: it has the ambasada-product skill (stack, storage, sign-in, mini app, deploy).\n\n## 3. Go live (1 min)\n\n```sh\nnpx ambasada login         # Ambasada ID, or a project key from https://developer.ambasada.dev\nnpx ambasada deploy        # build, smoke test, host at https://my-app.ambasada.dev\nnpx ambasada db migrate    # db/migrations \u2192 the app's database\nnpx ambasada logs          # the last deploy and recent errors\n```\n\nSign-in, notifications and the storage are set up by the deploy; nothing to configure. Your own secrets:\n`npx ambasada env set NAME value`. Hosting elsewhere: `npx vite build && npx wrangler deploy`, then `npx ambasada link https://\u2026`.\n\n**Sign in with Ambasada**: the header's button signs people in with their Ambasada ID; on the server,\n`ambasada(\u2026).auth.user(req)` gives `{ id, name, avatar_url, builder, pass }` or null.\n\n## Storage and realtime\n\nEvery app gets these, provisioned at the first `ambasada deploy`; locally wrangler keeps them in `.wrangler/state`.\n\n| Binding | For | Here |\n|---|---|---|\n| `env.DB` | SQLite: anything relational | `lib/db.ts`, tables in `db/migrations/`, example `api/notes.ts` |\n| `env.KV` | sessions, caches, flags | `lib/kv.ts` (the notes cache) |\n| `env.FILES` | uploads, generated files; public at `/files/<key>` | `lib/files.ts`, upload `api/files.ts` |\n| `env.ROOMS` | live state shared between people (Durable Object) | `src/realtime/room.ts`, hook `src/realtime/use-room.ts`, demo at `/room` |\n\n```sh\nnpx wrangler d1 migrations apply DB --local   # db/migrations \u2192 the local database (ambasada dev)\nnpx ambasada db migrate                       # \u2026 \u2192 the app's database online\nnpx ambasada db shell \"SELECT * FROM notes\"   # or `ambasada db shell` for a prompt\nnpx ambasada kv list | get <key> | put <key> <value> | delete <key>\nnpx ambasada files put <file> | list | url <key> | delete <key>\n```\n\nOptional: an agent with the Agents SDK in `examples/agent/` (its README: `npm i agents` and four lines to wire it).\n\n## In the Ambasada app (optional)\n\nOff by default: this is a website. `npx ambasada miniapp enable` adds a mini app at `/app` (`--entry /` for the whole\nsite): `miniapp: { entry: \"/app\" }` in `ambasada.config.ts`, src/in-app/ (the in-app page, rendered by src/main.tsx under the entry), a placeholder\n`public/icon.png`, and the manifest `ambasada dev` and `deploy` serve at `/.well-known/ambasada.json`. Then\n`http://localhost:3000/app?ambasada_shell=mock` pretends to be inside the Ambasada app. The ambasada-product skill:\nreference/mini-app.md.\n\n## Rules worth knowing\n\n- State lives in `env.DB`, `env.KV`, `env.FILES` or a Durable Object, never in module variables: a Worker has many instances.\n- Secrets only in `.env` locally and `ambasada env set` online; never in the code or `wrangler.jsonc` vars.\n- `npx ambasada check` runs the checks (https, no redirects, speed; the mini-app rules when it is on); `npx ambasada upgrade` after a new devkit.\n\nFor the Hack A Ton: `npx ambasada add village` (the add-on).\n\nBuilt by [CENTYSO](https://centyso.com) for [Ambasada](https://ambasada.id).\n", "ambasada.config.ts": 'import { defineApp } from "@ambasada/sdk";\n\nexport default defineApp({\n  id: "my-app",\n  name: "My App",\n  // One line about the app (the subtitle of its Ambasada mini app, if you add one: `ambasada miniapp enable`).\n  description: "Notes, a live room and sign-in",\n  // Where the app runs. `ambasada dev` serves it on http://localhost:3000; hosted, it is https://my-app.ambasada.dev\n  // (`ambasada deploy` sets it; `ambasada link https://\u2026` when you host elsewhere).\n  product: { url: "http://localhost:3000" },\n});\n', "api/ambasada-webhook.ts": '// POST /api/ambasada/webhook: the Ambasada app\'s events for this mini app (docs/MINI-APPS.md \xA77), signed with\n// AMBASADA_APP_SECRET (injected on ambasada.dev; `ambasada dev` plays the hub and sends a ping and\n// notifications_enabled here when it starts). The manifest points here: notifications.webhook.\nimport { isAmbasadaError } from "@ambasada/sdk";\nimport { ambasada, type Env } from "../lib/ambasada.ts";\nimport { forgetToken, saveToken } from "../lib/notifications.ts";\n\nexport default async function appWebhook(req: Request, env: Env): Promise<Response> {\n  const app = ambasada(env);\n  try {\n    const event = await app.apps.verifyWebhook(req); // throws if forged or stale\n    switch (event.event) {\n      case "notifications_enabled":\n      case "app_added":\n        if (event.token) await saveToken(app, event.user, event.token);\n        break;\n      case "notifications_disabled":\n      case "app_removed":\n        await forgetToken(app, event.user);\n        break;\n      case "ping": // `ambasada check` and the registry: answer 200\n        break;\n    }\n    return new Response("ok");\n  } catch (error) {\n    if (isAmbasadaError(error)) return error.toResponse();\n    throw error;\n  }\n}\n', "api/auth.ts": '// Sign in with Ambasada (Ambasada ID, OAuth + PKCE): zero setup. On https://<slug>.ambasada.dev the deploy\n// injects AMBASADA_AUTH_*; under `ambasada dev` the mock signs you in as a fake visitor.\n//   GET /api/auth/login?returnTo=/   \u2192 the Ambasada ID consent screen\n//   GET /api/auth/callback           \u2192 back from it: sets an HttpOnly session cookie, redirects to returnTo\n//   GET /api/auth/logout             \u2192 clears it\n//   GET /api/auth/me                 \u2192 { user } (null when signed out), for the browser\n//   POST /api/auth/shell { token }   \u2192 silent sign-in inside the Ambasada app: the same session, no consent screen\n//                                      (the page calls `auth.signIn()` from @ambasada/miniapp)\n// On the server: `await ambasada(env).auth.user(req)` \u2192 { id, name, avatar_url, builder, pass, \u2026 } or null.\nimport { isAmbasadaError } from "@ambasada/sdk";\nimport { ambasada, type Env } from "../lib/ambasada.ts";\n\nexport default async function auth(req: Request, env: Env): Promise<Response> {\n  const { auth } = ambasada(env);\n  try {\n    switch (new URL(req.url).pathname.replace(/\\/+$/, "")) {\n      case "/api/auth/login":\n        return await auth.login(req);\n      case "/api/auth/callback":\n        return await auth.callback(req);\n      case "/api/auth/logout":\n        return auth.logout(req);\n      case "/api/auth/shell":\n        return await auth.shell(req);\n      case "/api/auth/me": {\n        // Under `ambasada dev` the page needs the mock issuer for its fake shell (?ambasada_shell=mock).\n        const devIssuer = env.AMBASADA_AUTH_ISSUER?.startsWith("http://") ? env.AMBASADA_AUTH_ISSUER : undefined;\n        return Response.json({ user: await auth.user(req), configured: auth.configured, ...(devIssuer ? { dev_issuer: devIssuer } : {}) }, { headers: { "cache-control": "no-store" } });\n      }\n    }\n    return Response.json({ error: { code: "NOT_FOUND", message: "no such route" } }, { status: 404 });\n  } catch (error) {\n    if (isAmbasadaError(error)) return error.toResponse();\n    throw error;\n  }\n}\n', "api/files.ts": '// POST /api/files (raw body, content-type): a signed-in person uploads a file to env.FILES (lib/files.ts)\n// \u2192 { key, url }; the url (/files/<key>) is public and served by the /files/* route.\nimport { ambasada, type Env } from "../lib/ambasada.ts";\nimport { upload } from "../lib/files.ts";\n\nconst MAX_BYTES = 10 * 1024 * 1024;\n\nexport default async function files(req: Request, env: Env): Promise<Response> {\n  if (req.method !== "POST") return Response.json({ error: { code: "INVALID_REQUEST", message: "POST the file" } }, { status: 405 });\n  const user = await ambasada(env).auth.user(req);\n  if (!user) return Response.json({ error: { code: "UNAUTHORIZED", message: "sign in to upload" } }, { status: 401 });\n  const size = Number(req.headers.get("content-length") ?? 0);\n  if (!size || size > MAX_BYTES) return Response.json({ error: { code: "INVALID_REQUEST", message: "send a file up to 10 MB with a content-length" } }, { status: 413 });\n  const stored = await upload(env.FILES, req.body, { contentType: req.headers.get("content-type") ?? undefined, folder: `u/${user.id}` });\n  return Response.json(stored, { status: 201 });\n}\n', "api/notes.ts": '// GET /api/notes: the latest notes from env.DB (lib/db.ts), cached a minute in env.KV (lib/kv.ts).\n// POST /api/notes { text }: adds one. The table is db/migrations/0001_init.sql.\nimport type { Env } from "../lib/ambasada.ts";\nimport { all, run } from "../lib/db.ts";\nimport { cached, remove } from "../lib/kv.ts";\n\ntype Note = { id: number; text: string; created_at: number };\n\nexport default async function notes(req: Request, env: Env): Promise<Response> {\n  if (req.method === "POST") {\n    const { text } = (await req.json().catch(() => ({}))) as { text?: unknown };\n    if (typeof text !== "string" || !text.trim() || text.length > 500) {\n      return Response.json({ error: { code: "INVALID_REQUEST", message: "body must be { text }, 1 to 500 characters" } }, { status: 400 });\n    }\n    const { lastRowId } = await run(env.DB, "INSERT INTO notes (text, created_at) VALUES (?, ?)", text.trim(), Date.now());\n    await remove(env.KV, "notes:latest");\n    return Response.json({ id: lastRowId }, { status: 201 });\n  }\n  const latest = await cached(env.KV, "notes:latest", 60, () => all<Note>(env.DB, "SELECT id, text, created_at FROM notes ORDER BY id DESC LIMIT 20"));\n  return Response.json({ notes: latest });\n}\n', "db/migrations/0001_init.sql": "-- The app's first table. Add the next change as db/migrations/0002_<what>.sql (never edit an applied file), then:\n--   npx wrangler d1 migrations apply DB --local   (ambasada dev)\n--   npx ambasada db migrate                       (online)\nCREATE TABLE notes (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  text TEXT NOT NULL,\n  created_at INTEGER NOT NULL\n);\nCREATE INDEX notes_created ON notes (created_at);\n", "examples/agent/README.md": '# Agent (optional): the Cloudflare Agents SDK\n\nFor agentic products: an agent per user, document or task, with live state, its own SQL, schedules and\nWebSockets (`agent.ts`). It is a Durable Object, so it runs on ambasada.dev like the live rooms. To turn it on:\n\n1. `npm i agents`\n2. `wrangler.jsonc`: add the binding and a migration after the existing ones:\n   ```jsonc\n   "durable_objects": { "bindings": [{ "name": "ROOMS", "class_name": "Room" }, { "name": "AgentExample", "class_name": "AgentExample" }] },\n   "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Room"] }, { "tag": "v2", "new_sqlite_classes": ["AgentExample"] }]\n   ```\n3. In the Worker entry (`src/worker.ts`; spa: `worker/index.ts`; next: `worker.ts`):\n   ```ts\n   export { AgentExample } from "../examples/agent/agent.ts"; // next: "./examples/agent/agent.ts"\n   import { routeAgents } from "../examples/agent/agent.ts";\n   // first thing in fetch():\n   const agent = await routeAgents(req, env as unknown as Record<string, unknown>);\n   if (agent) return agent;\n   ```\n4. In the browser (React): `useAgent({ agent: "agent-example", name: user.id, onStateUpdate: setState })` from\n   `agents/react`; `agent.send("hello")`. Plain fetch: `GET /agents/agent-example/<name>`.\n\n`ambasada deploy` sends the new class and its migration; nothing else to set up. Docs: https://developers.cloudflare.com/agents/\n', "examples/agent/agent.ts": '/**\n * Optional: an agent with the Cloudflare Agents SDK (`agents`), for agentic products. An agent is a Durable\n * Object with superpowers: state synced live to every connected client (`setState`), its own SQL (`this.sql`),\n * scheduled work (`this.schedule`), WebSockets and HTTP. One instance per name: per user, per document, per task.\n * Not wired in by default: examples/agent/README.md has the four steps.\n */\nimport { Agent, routeAgentRequest, type Connection, type WSMessage } from "agents";\n\ntype State = { notes: number; lastNote: string | null };\n\nexport class AgentExample extends Agent<Cloudflare.Env, State> {\n  initialState: State = { notes: 0, lastNote: null };\n\n  async onStart() {\n    this.sql`CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY AUTOINCREMENT, text TEXT NOT NULL, at INTEGER NOT NULL)`;\n  }\n\n  // GET /agents/agent-example/<name>: what this agent knows.\n  async onRequest(_req: Request): Promise<Response> {\n    const notes = this.sql<{ id: number; text: string; at: number }>`SELECT id, text, at FROM notes ORDER BY id DESC LIMIT 20`;\n    return Response.json({ state: this.state, notes });\n  }\n\n  // A client (useAgent in the browser) sent a message: remember it, sync the new state to every client,\n  // and come back to it in a minute (call an LLM here, send a notification, \u2026).\n  async onMessage(connection: Connection, message: WSMessage) {\n    const text = String(message).slice(0, 2000);\n    this.sql`INSERT INTO notes (text, at) VALUES (${text}, ${Date.now()})`;\n    this.setState({ notes: this.state.notes + 1, lastNote: text });\n    await this.schedule(60, "followUp", { text });\n    connection.send(JSON.stringify({ ok: true }));\n  }\n\n  async followUp(payload: { text: string }) {\n    console.log(`a minute ago someone wrote: ${payload.text}`);\n  }\n}\n\n/** In your Worker\'s fetch, before your own routes: answers /agents/<agent>/<name> (HTTP and WebSocket). */\nexport const routeAgents = (req: Request, env: Record<string, unknown>) => routeAgentRequest(req, env);\n', gitignore: "node_modules/\ndist/\n.wrangler/\n*.tsbuildinfo\n.env*\n.dev.vars*\n.DS_Store\n# build output of `ambasada deploy`; project.json (template, devkit version) is kept\n.ambasada/*\n!.ambasada/project.json\n", "index.html": '<!doctype html>\n<html lang="en">\n  <head>\n    <meta charset="utf-8" />\n    <meta name="viewport" content="width=device-width, initial-scale=1" />\n    <title>My App</title>\n  </head>\n  <body>\n    <div id="root"></div>\n    <script type="module" src="/src/main.tsx"></script>\n  </body>\n</html>\n', "lib/ambasada.ts": 'import { createAmbasada, type Ambasada } from "@ambasada/sdk";\nimport type { Room } from "../src/realtime/room.ts";\n\n/** The Worker\'s env: `.env` locally (`ambasada dev` points it at the mock), secrets injected at deploy. */\nexport interface Env {\n  ASSETS: Fetcher;\n  /** The app\'s SQLite database (lib/db.ts), key-value (lib/kv.ts), files (lib/files.ts) and live rooms (src/realtime/room.ts). */\n  DB: D1Database;\n  KV: KVNamespace;\n  FILES: R2Bucket;\n  ROOMS: DurableObjectNamespace<Room>;\n  AMBASADA_API_KEY?: string;\n  /** Set by `ambasada deploy` and `ambasada dev`; the SDK defaults to https://api.ambasada.dev. */\n  AMBASADA_API_URL?: string;\n  AMBASADA_APP_ID?: string;\n  /** Sign in with Ambasada (api/auth.ts): set by `ambasada deploy` on ambasada.dev, and by `ambasada dev`. */\n  AMBASADA_AUTH_CLIENT_ID?: string;\n  AMBASADA_AUTH_CLIENT_SECRET?: string;\n  AMBASADA_AUTH_ISSUER?: string;\n  /** Mini-app notifications (api/ambasada-webhook.ts, lib/notifications.ts): set on ambasada.dev and by `ambasada dev`. */\n  AMBASADA_APP_SECRET?: string;\n  AMBASADA_HUB_URL?: string;\n  AMBASADA_APP_ORIGIN?: string;\n  /** Your public URL, if the Worker sees another host (behind a proxy). */\n  PUBLIC_URL?: string;\n}\n\nlet client: Ambasada | undefined;\n\n/** One client per isolate: it caches the API\'s signing keys. */\nexport function ambasada(env: Env): Ambasada {\n  return (client ??= createAmbasada({ env: env as unknown as Record<string, unknown> }));\n}\n', "lib/db.ts": '/**\n * env.DB: this app\'s SQLite database (Cloudflare D1). The tables come from db/migrations/*.sql:\n * `npx ambasada db migrate` online, `npx wrangler d1 migrations apply DB --local` for `ambasada dev`.\n * A tiny typed layer, no ORM: SQL with ? placeholders in, plain objects out.\n *\n *   const notes = await all<Note>(env.DB, "SELECT * FROM notes ORDER BY id DESC LIMIT ?", 20);\n *   const note = await first<Note>(env.DB, "SELECT * FROM notes WHERE id = ?", id);\n *   const { lastRowId } = await run(env.DB, "INSERT INTO notes (text) VALUES (?)", text);\n *   await batch(env.DB, [["UPDATE a SET n = n - 1 WHERE id = ?", 1], ["UPDATE b SET n = n + 1 WHERE id = ?", 2]]); // one transaction\n */\n\nexport type Param = string | number | boolean | null | ArrayBuffer;\n\n/** What this file needs from a D1 binding (env.DB satisfies it). */\nexport interface Database {\n  prepare(query: string): Statement;\n  batch(statements: Statement[]): Promise<unknown[]>;\n}\n\nexport interface Statement {\n  bind(...values: unknown[]): Statement;\n  all<T = Record<string, unknown>>(): Promise<{ results: T[] }>;\n  first<T = Record<string, unknown>>(): Promise<T | null>;\n  run(): Promise<{ meta: { changes: number; last_row_id: number } }>;\n}\n\nconst statement = (db: Database, query: string, params: Param[]) => db.prepare(query).bind(...params);\n\n/** Every row. */\nexport async function all<T = Record<string, unknown>>(db: Database, query: string, ...params: Param[]): Promise<T[]> {\n  return (await statement(db, query, params).all<T>()).results;\n}\n\n/** The first row, or null. */\nexport function first<T = Record<string, unknown>>(db: Database, query: string, ...params: Param[]): Promise<T | null> {\n  return statement(db, query, params).first<T>();\n}\n\n/** INSERT, UPDATE, DELETE: how many rows changed and the last inserted id. */\nexport async function run(db: Database, query: string, ...params: Param[]): Promise<{ changes: number; lastRowId: number }> {\n  const { meta } = await statement(db, query, params).run();\n  return { changes: meta.changes, lastRowId: meta.last_row_id };\n}\n\n/** Several statements in one transaction: all of them apply, or none. */\nexport async function batch(db: Database, statements: [query: string, ...params: Param[]][]): Promise<void> {\n  await db.batch(statements.map(([query, ...params]) => statement(db, query, params)));\n}\n', "lib/files.ts": '/**\n * env.FILES: this app\'s file storage (Cloudflare R2). Uploads and generated files; each one is public at\n * /files/<key> on the app\'s own address (the /files/* route calls serveFile). Don\'t keep files in the database.\n *\n *   const { key, url } = await upload(env.FILES, req.body, { contentType: "image/png" });   // url: /files/u/\u2026\n *   return serveFile(env.FILES, req);                                                        // GET /files/*\n *\n * Files are public to anyone with the URL: keep private documents behind your own route that checks who asks.\n * `npx ambasada files put|list|delete|url` manages them from the terminal.\n */\n\n/** What this file needs from an R2 binding (env.FILES satisfies it). */\nexport interface Bucket {\n  put(key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null, options?: { httpMetadata?: { contentType?: string } }): Promise<unknown>;\n  get(key: string, options?: { onlyIf?: Headers; range?: Headers }): Promise<StoredFile | null>;\n  delete(key: string): Promise<void>;\n}\n\nexport interface StoredFile {\n  httpEtag: string;\n  size: number;\n  httpMetadata?: { contentType?: string };\n  range?: { offset?: number; length?: number; suffix?: number };\n  body?: ReadableStream;\n}\n\nexport const FILES_PATH = "/files/";\n\n/** Stores `body` under a new random key (in `folder`) \u2192 `{ key, url }`, url relative to the app (/files/<key>). */\nexport async function upload(bucket: Bucket, body: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null, options: { contentType?: string; folder?: string } = {}): Promise<{ key: string; url: string }> {\n  const key = `${options.folder ?? "u"}/${crypto.randomUUID()}`;\n  await bucket.put(key, body, { httpMetadata: { contentType: options.contentType ?? "application/octet-stream" } });\n  return { key, url: fileUrl(key) };\n}\n\nexport const fileUrl = (key: string) => `${FILES_PATH}${key.split("/").map(encodeURIComponent).join("/")}`;\n\n/** GET/HEAD /files/<key>: the file with its type, an ETag (304 when unchanged), byte ranges, and a cache header. */\nexport async function serveFile(bucket: Bucket, req: Request): Promise<Response> {\n  if (req.method !== "GET" && req.method !== "HEAD") return new Response(null, { status: 405, headers: { allow: "GET, HEAD" } });\n  const path = new URL(req.url).pathname;\n  const key = decodeURIComponent(path.slice(path.indexOf(FILES_PATH) + FILES_PATH.length));\n  if (!key) return new Response("Not found", { status: 404 });\n  const file = await bucket.get(key, { onlyIf: req.headers, range: req.headers });\n  if (!file) return new Response("Not found", { status: 404 });\n  const headers = new Headers({ etag: file.httpEtag, "cache-control": "public, max-age=3600", "accept-ranges": "bytes" });\n  if (file.httpMetadata?.contentType) headers.set("content-type", file.httpMetadata.contentType);\n  if (!file.body) return new Response(null, { status: 304, headers }); // If-None-Match matched: nothing changed\n  const r = file.range;\n  if (r && req.headers.has("range")) {\n    const offset = r.suffix !== undefined ? file.size - r.suffix : (r.offset ?? 0);\n    const length = r.suffix ?? r.length ?? file.size - offset;\n    headers.set("content-range", `bytes ${offset}-${offset + length - 1}/${file.size}`);\n    headers.set("content-length", String(length));\n    return new Response(req.method === "HEAD" ? null : file.body, { status: 206, headers });\n  }\n  headers.set("content-length", String(file.size));\n  return new Response(req.method === "HEAD" ? null : file.body, { headers });\n}\n', "lib/kv.ts": '/**\n * env.KV: this app\'s key-value store (Cloudflare KV). Fast reads everywhere, writes visible within about a\n * minute, at most one write per second per key. Good for sessions, caches and feature flags; not for counters\n * or anything two people change at once (use env.DB, or a Durable Object for live state).\n *\n *   await putJson(env.KV, `session:${id}`, { user }, { ttl: 60 * 60 * 24 });\n *   const session = await getJson<{ user: string }>(env.KV, `session:${id}`);\n *   const page = await cached(env.KV, "home:stats", 60, () => computeStats());\n */\n\n/** What this file needs from a KV binding (env.KV satisfies it). */\nexport interface KeyValue {\n  get(key: string, type: "text"): Promise<string | null>;\n  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;\n  delete(key: string): Promise<void>;\n}\n\n/** The value saved under `key`, parsed; null when there is none (or it expired). */\nexport async function getJson<T>(kv: KeyValue, key: string): Promise<T | null> {\n  const text = await kv.get(key, "text");\n  return text === null ? null : (JSON.parse(text) as T);\n}\n\n/** Saves `value` as JSON. `ttl`: seconds until it disappears (at least 60). */\nexport function putJson(kv: KeyValue, key: string, value: unknown, options: { ttl?: number } = {}): Promise<void> {\n  return kv.put(key, JSON.stringify(value), options.ttl ? { expirationTtl: Math.max(60, options.ttl) } : undefined);\n}\n\nexport function remove(kv: KeyValue, key: string): Promise<void> {\n  return kv.delete(key);\n}\n\n/** `load()`\'s result, kept for `ttl` seconds: a cache in front of something slow. */\nexport async function cached<T>(kv: KeyValue, key: string, ttl: number, load: () => Promise<T>): Promise<T> {\n  const hit = await getJson<T>(kv, key);\n  if (hit !== null) return hit;\n  const value = await load();\n  await putJson(kv, key, value, { ttl });\n  return value;\n}\n', "lib/notifications.ts": '// Who turned notifications on, and how to reach them (docs/MINI-APPS.md \xA77). The hub sends a token per person\n// to the webhook route (api/ambasada-webhook.ts; app/api/ambasada/webhook/route.ts in Next); it lives in your\n// ambasada.store under the person\'s Ambasada user id.\nimport type { Ambasada, AppNotifyInput } from "@ambasada/sdk";\n\nconst key = (user: string) => `ambasada/notifications/${user}`;\n\nexport const saveToken = (app: Ambasada, user: string, token: string) => app.store.set(key(user), { token, enabled_at: new Date().toISOString() });\nexport const forgetToken = (app: Ambasada, user: string) => app.store.delete(key(user));\n\n/**\n * A push to one person (their Ambasada user id, e.g. `(await app.auth.user(req)).id`), if they turned\n * notifications on. False when they haven\'t, or the hub said the token is gone (then it is forgotten).\n *   await notifyUser(app, user.id, { notification_id: `order-${id}`, title: "Your translation is ready", body: "\u2026", url: `/orders/${id}` });\n */\nexport async function notifyUser(app: Ambasada, user: string, notification: Omit<AppNotifyInput, "tokens" | "users">): Promise<boolean> {\n  const saved = await app.store.get<{ token: string }>(key(user));\n  if (!saved) return false;\n  const result = await app.apps.notify({ ...notification, tokens: [saved.token] });\n  if (result.invalid.includes(saved.token)) await forgetToken(app, user);\n  return result.sent.includes(saved.token);\n}\n', "package.json": '{\n  "name": "@ambasada/template-spa",\n  "version": "0.1.0",\n  "private": true,\n  "description": "An Ambasada app: Vite + React (Lovable/Bolt exports) and api/*.ts handlers as one Cloudflare Worker.",\n  "type": "module",\n  "engines": {\n    "node": ">=22"\n  },\n  "scripts": {\n    "dev": "ambasada dev",\n    "build": "vite build",\n    "preview": "vite build && vite preview --port 3000",\n    "typecheck": "tsc -b",\n    "ambasada": "ambasada"\n  },\n  "dependencies": {\n    "@ambasada/sdk": "workspace:*",\n    "@ambasada/ui": "workspace:*",\n    "react": "~19.3.1",\n    "react-dom": "~19.3.1"\n  },\n  "devDependencies": {\n    "@ambasada/cli": "workspace:*",\n    "@cloudflare/vite-plugin": "^1.67.0",\n    "@cloudflare/workers-types": "^5.20261102.1",\n    "@types/node": "^22.20.5",\n    "@types/react": "^19.3.0",\n    "@types/react-dom": "^19.3.0",\n    "@vitejs/plugin-react": "^6.1.2",\n    "typescript": "~5.9.3",\n    "vite": "^8.3.5",\n    "wrangler": "^4.156.1"\n  }\n}\n', "public/privacy.html": `<!doctype html>
+`, "lib/db.ts": '/**\n * env.DB: this app\'s SQLite database (Cloudflare D1). The tables come from db/migrations/*.sql:\n * `npx ambasada db migrate` online, `npx wrangler d1 migrations apply DB --local` for `ambasada dev`.\n * A tiny typed layer, no ORM: SQL with ? placeholders in, plain objects out.\n *\n *   const notes = await all<Note>(env.DB, "SELECT * FROM notes ORDER BY id DESC LIMIT ?", 20);\n *   const note = await first<Note>(env.DB, "SELECT * FROM notes WHERE id = ?", id);\n *   const { lastRowId } = await run(env.DB, "INSERT INTO notes (text) VALUES (?)", text);\n *   await batch(env.DB, [["UPDATE a SET n = n - 1 WHERE id = ?", 1], ["UPDATE b SET n = n + 1 WHERE id = ?", 2]]); // one transaction\n */\n\nexport type Param = string | number | boolean | null | ArrayBuffer;\n\n/** What this file needs from a D1 binding (env.DB satisfies it). */\nexport interface Database {\n  prepare(query: string): Statement;\n  batch(statements: Statement[]): Promise<unknown[]>;\n}\n\nexport interface Statement {\n  bind(...values: unknown[]): Statement;\n  all<T = Record<string, unknown>>(): Promise<{ results: T[] }>;\n  first<T = Record<string, unknown>>(): Promise<T | null>;\n  run(): Promise<{ meta: { changes: number; last_row_id: number } }>;\n}\n\nconst statement = (db: Database, query: string, params: Param[]) => db.prepare(query).bind(...params);\n\n/** Every row. */\nexport async function all<T = Record<string, unknown>>(db: Database, query: string, ...params: Param[]): Promise<T[]> {\n  return (await statement(db, query, params).all<T>()).results;\n}\n\n/** The first row, or null. */\nexport function first<T = Record<string, unknown>>(db: Database, query: string, ...params: Param[]): Promise<T | null> {\n  return statement(db, query, params).first<T>();\n}\n\n/** INSERT, UPDATE, DELETE: how many rows changed and the last inserted id. */\nexport async function run(db: Database, query: string, ...params: Param[]): Promise<{ changes: number; lastRowId: number }> {\n  const { meta } = await statement(db, query, params).run();\n  return { changes: meta.changes, lastRowId: meta.last_row_id };\n}\n\n/** Several statements in one transaction: all of them apply, or none. */\nexport async function batch(db: Database, statements: [query: string, ...params: Param[]][]): Promise<void> {\n  await db.batch(statements.map(([query, ...params]) => statement(db, query, params)));\n}\n', "lib/files.ts": '/**\n * env.FILES: this app\'s file storage (Cloudflare R2). Uploads and generated files; each one is public at\n * /files/<key> on the app\'s own address (the /files/* route calls serveFile). Don\'t keep files in the database.\n *\n *   const { key, url } = await upload(env.FILES, req.body, { contentType: "image/png" });   // url: /files/u/\u2026\n *   return serveFile(env.FILES, req);                                                        // GET /files/*\n *\n * Files are public to anyone with the URL: keep private documents behind your own route that checks who asks.\n * `npx ambasada files put|list|delete|url` manages them from the terminal.\n */\n\n/** What this file needs from an R2 binding (env.FILES satisfies it). */\nexport interface Bucket {\n  put(key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null, options?: { httpMetadata?: { contentType?: string } }): Promise<unknown>;\n  get(key: string, options?: { onlyIf?: Headers; range?: Headers }): Promise<StoredFile | null>;\n  delete(key: string): Promise<void>;\n}\n\nexport interface StoredFile {\n  httpEtag: string;\n  size: number;\n  httpMetadata?: { contentType?: string };\n  range?: { offset?: number; length?: number; suffix?: number };\n  body?: ReadableStream;\n}\n\nexport const FILES_PATH = "/files/";\n\n/** Stores `body` under a new random key (in `folder`) \u2192 `{ key, url }`, url relative to the app (/files/<key>). */\nexport async function upload(bucket: Bucket, body: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null, options: { contentType?: string; folder?: string } = {}): Promise<{ key: string; url: string }> {\n  const key = `${options.folder ?? "u"}/${crypto.randomUUID()}`;\n  await bucket.put(key, body, { httpMetadata: { contentType: options.contentType ?? "application/octet-stream" } });\n  return { key, url: fileUrl(key) };\n}\n\nexport const fileUrl = (key: string) => `${FILES_PATH}${key.split("/").map(encodeURIComponent).join("/")}`;\n\n/** GET/HEAD /files/<key>: the file with its type, an ETag (304 when unchanged), byte ranges, and a cache header. */\nexport async function serveFile(bucket: Bucket, req: Request): Promise<Response> {\n  if (req.method !== "GET" && req.method !== "HEAD") return new Response(null, { status: 405, headers: { allow: "GET, HEAD" } });\n  const path = new URL(req.url).pathname;\n  const key = decodeURIComponent(path.slice(path.indexOf(FILES_PATH) + FILES_PATH.length));\n  if (!key) return new Response("Not found", { status: 404 });\n  const file = await bucket.get(key, { onlyIf: req.headers, range: req.headers });\n  if (!file) return new Response("Not found", { status: 404 });\n  const headers = new Headers({ etag: file.httpEtag, "cache-control": "public, max-age=3600", "accept-ranges": "bytes" });\n  if (file.httpMetadata?.contentType) headers.set("content-type", file.httpMetadata.contentType);\n  if (!file.body) return new Response(null, { status: 304, headers }); // If-None-Match matched: nothing changed\n  const r = file.range;\n  if (r && req.headers.has("range")) {\n    const offset = r.suffix !== undefined ? file.size - r.suffix : (r.offset ?? 0);\n    const length = r.suffix ?? r.length ?? file.size - offset;\n    headers.set("content-range", `bytes ${offset}-${offset + length - 1}/${file.size}`);\n    headers.set("content-length", String(length));\n    return new Response(req.method === "HEAD" ? null : file.body, { status: 206, headers });\n  }\n  headers.set("content-length", String(file.size));\n  return new Response(req.method === "HEAD" ? null : file.body, { headers });\n}\n', "lib/kv.ts": '/**\n * env.KV: this app\'s key-value store (Cloudflare KV). Fast reads everywhere, writes visible within about a\n * minute, at most one write per second per key. Good for sessions, caches and feature flags; not for counters\n * or anything two people change at once (use env.DB, or a Durable Object for live state).\n *\n *   await putJson(env.KV, `session:${id}`, { user }, { ttl: 60 * 60 * 24 });\n *   const session = await getJson<{ user: string }>(env.KV, `session:${id}`);\n *   const page = await cached(env.KV, "home:stats", 60, () => computeStats());\n */\n\n/** What this file needs from a KV binding (env.KV satisfies it). */\nexport interface KeyValue {\n  get(key: string, type: "text"): Promise<string | null>;\n  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;\n  delete(key: string): Promise<void>;\n}\n\n/** The value saved under `key`, parsed; null when there is none (or it expired). */\nexport async function getJson<T>(kv: KeyValue, key: string): Promise<T | null> {\n  const text = await kv.get(key, "text");\n  return text === null ? null : (JSON.parse(text) as T);\n}\n\n/** Saves `value` as JSON. `ttl`: seconds until it disappears (at least 60). */\nexport function putJson(kv: KeyValue, key: string, value: unknown, options: { ttl?: number } = {}): Promise<void> {\n  return kv.put(key, JSON.stringify(value), options.ttl ? { expirationTtl: Math.max(60, options.ttl) } : undefined);\n}\n\nexport function remove(kv: KeyValue, key: string): Promise<void> {\n  return kv.delete(key);\n}\n\n/** `load()`\'s result, kept for `ttl` seconds: a cache in front of something slow. */\nexport async function cached<T>(kv: KeyValue, key: string, ttl: number, load: () => Promise<T>): Promise<T> {\n  const hit = await getJson<T>(kv, key);\n  if (hit !== null) return hit;\n  const value = await load();\n  await putJson(kv, key, value, { ttl });\n  return value;\n}\n', "lib/notifications.ts": '// Who turned notifications on, and how to reach them (docs/MINI-APPS.md \xA77). The hub sends a token per person\n// to the webhook route (api/ambasada-webhook.ts; app/api/ambasada/webhook/route.ts in Next); it lives in your\n// ambasada.store under the person\'s Ambasada user id.\nimport type { Ambasada, AppNotifyInput } from "@ambasada/sdk";\n\nconst key = (user: string) => `ambasada/notifications/${user}`;\n\nexport const saveToken = (app: Ambasada, user: string, token: string) => app.store.set(key(user), { token, enabled_at: new Date().toISOString() });\nexport const forgetToken = (app: Ambasada, user: string) => app.store.delete(key(user));\n\n/**\n * A push to one person (their Ambasada user id, e.g. `(await app.auth.user(req)).id`), if they turned\n * notifications on. False when they haven\'t, or the hub said the token is gone (then it is forgotten).\n *   await notifyUser(app, user.id, { notification_id: `order-${id}`, title: "Your translation is ready", body: "\u2026", url: `/orders/${id}` });\n */\nexport async function notifyUser(app: Ambasada, user: string, notification: Omit<AppNotifyInput, "tokens" | "users">): Promise<boolean> {\n  const saved = await app.store.get<{ token: string }>(key(user));\n  if (!saved) return false;\n  const result = await app.apps.notify({ ...notification, tokens: [saved.token] });\n  if (result.invalid.includes(saved.token)) await forgetToken(app, user);\n  return result.sent.includes(saved.token);\n}\n', "next.config.ts": 'import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare";\nimport type { NextConfig } from "next";\n\n// The product runs as one Cloudflare Worker (OpenNext). Stick to pages, server components, route\n// handlers, server actions and fetch: no next/image default loader, ISR, fs or native dependencies.\nconst nextConfig: NextConfig = {\n  // `ambasada dev --tunnel` serves `next dev` at https://<slug>-dev.ambasada.dev: let it load dev assets and HMR from there.\n  allowedDevOrigins: ["*.ambasada.dev"],\n};\n\nexport default nextConfig;\n\n// `next dev` reaches env.DB, env.KV and env.FILES (wrangler\'s local copies) through getCloudflareContext() (lib/bindings.ts).\ninitOpenNextCloudflareForDev();\n', "open-next.config.ts": 'import { defineCloudflareConfig } from "@opennextjs/cloudflare";\n\n// `opennextjs-cloudflare build` turns the Next.js app into one Worker (.open-next/worker.js + assets).\nexport default defineCloudflareConfig();\n', "package.json": '{\n  "name": "@ambasada/template-next",\n  "version": "0.1.0",\n  "private": true,\n  "description": "An Ambasada app: Next.js as one Cloudflare Worker (OpenNext), with sign-in, notifications and storage.",\n  "type": "module",\n  "engines": {\n    "node": ">=22"\n  },\n  "scripts": {\n    "dev": "ambasada dev",\n    "build": "next build",\n    "build:worker": "opennextjs-cloudflare build",\n    "preview": "opennextjs-cloudflare build && wrangler dev --port 3000",\n    "typecheck": "next typegen && tsc --noEmit && wrangler types node_modules/.worker-env.d.ts && tsc -p tsconfig.worker.json",\n    "ambasada": "ambasada"\n  },\n  "dependencies": {\n    "@ambasada/sdk": "workspace:*",\n    "@ambasada/ui": "workspace:*",\n    "@opennextjs/cloudflare": "~1.20.15",\n    "next": "~16.4.3",\n    "react": "~19.3.1",\n    "react-dom": "~19.3.1"\n  },\n  "devDependencies": {\n    "@ambasada/cli": "workspace:*",\n    "@types/node": "^22.20.5",\n    "@types/react": "^19.3.0",\n    "@types/react-dom": "^19.3.0",\n    "typescript": "~5.9.3",\n    "wrangler": "^4.156.1"\n  },\n  "allowScripts": {\n    "esbuild": true,\n    "fsevents": true,\n    "workerd": true\n  }\n}\n', "src/realtime/room.ts": '/**\n * A live room (Durable Object `Room`, bound as env.ROOMS): everyone connected to the same room id shares it.\n *\n *   GET /api/rooms/<id>/ws  (WebSocket)  \u2192 env.ROOMS.getByName(id).fetch(req)\n *   client \u2192 { "text": "hi" }            server \u2192 { type: "history", messages } on join,\n *                                                 { type: "message", message } to everyone,\n *                                                 { type: "presence", online } when people come and go\n *\n * WebSocket hibernation: the object sleeps between messages and the connections stay open, so an idle room\n * costs nothing. Its own SQLite (`ctx.storage.sql`) keeps the last 50 messages, replayed to whoever joins.\n * The same shape fits presence, live counters, a game table, a queue or a rate limit: one object per thing.\n */\nimport { DurableObject } from "cloudflare:workers";\n\nconst KEEP = 50;\n\nexport type RoomMessage = { id: number; name: string; text: string; at: number };\nexport type RoomEvent = { type: "history"; messages: RoomMessage[] } | { type: "message"; message: RoomMessage } | { type: "presence"; online: number };\n\nexport class Room extends DurableObject<unknown> {\n  constructor(ctx: DurableObjectState, env: unknown) {\n    super(ctx, env);\n    ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS messages (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, text TEXT NOT NULL, at INTEGER NOT NULL)");\n  }\n\n  async fetch(req: Request): Promise<Response> {\n    if (req.headers.get("upgrade") !== "websocket") return Response.json({ online: this.ctx.getWebSockets().length, messages: this.history() });\n    // Who is talking: the client says. Behind Sign in with Ambasada, pass the signed-in name from your route instead.\n    const name = (new URL(req.url).searchParams.get("name") ?? "").trim().slice(0, 40) || "guest";\n    const { 0: client, 1: server } = new WebSocketPair();\n    this.ctx.acceptWebSocket(server);\n    server.serializeAttachment({ name });\n    server.send(JSON.stringify({ type: "history", messages: this.history() } satisfies RoomEvent));\n    this.broadcast({ type: "presence", online: this.ctx.getWebSockets().length });\n    return new Response(null, { status: 101, webSocket: client });\n  }\n\n  async webSocketMessage(ws: WebSocket, data: string | ArrayBuffer): Promise<void> {\n    let text = "";\n    try {\n      text = String((JSON.parse(typeof data === "string" ? data : new TextDecoder().decode(data)) as { text?: unknown }).text ?? "").trim().slice(0, 2000);\n    } catch {\n      return;\n    }\n    if (!text) return;\n    const { name } = ws.deserializeAttachment() as { name: string };\n    const at = Date.now();\n    const { id } = this.ctx.storage.sql.exec<{ id: number }>("INSERT INTO messages (name, text, at) VALUES (?, ?, ?) RETURNING id", name, text, at).one();\n    this.ctx.storage.sql.exec("DELETE FROM messages WHERE id <= ?", id - KEEP);\n    this.broadcast({ type: "message", message: { id, name, text, at } });\n  }\n\n  async webSocketClose(ws: WebSocket, code: number, reason: string): Promise<void> {\n    try {\n      ws.close(code, reason);\n    } catch {\n      // already closed\n    }\n    this.broadcast({ type: "presence", online: this.ctx.getWebSockets().filter((s) => s !== ws).length });\n  }\n\n  private history(): RoomMessage[] {\n    return this.ctx.storage.sql.exec<RoomMessage>("SELECT id, name, text, at FROM messages ORDER BY id").toArray();\n  }\n\n  private broadcast(event: RoomEvent): void {\n    const text = JSON.stringify(event);\n    for (const ws of this.ctx.getWebSockets()) {\n      try {\n        ws.send(text);\n      } catch {\n        // a closing socket: webSocketClose cleans up\n      }\n    }\n  }\n}\n', "src/realtime/use-room.ts": '/**\n * `useRoom(id)`: a live room in a React component (src/realtime/room.ts on the server). Reconnects on its own.\n *\n *   const { messages, online, send, status } = useRoom("lobby", { name: "Ana" });\n */\n"use client";\nimport { useCallback, useEffect, useRef, useState } from "react";\n\nexport type RoomMessage = { id: number; name: string; text: string; at: number };\ntype RoomEvent = { type: "history"; messages: RoomMessage[] } | { type: "message"; message: RoomMessage } | { type: "presence"; online: number };\n\nexport function useRoom(id: string, options: { name?: string } = {}) {\n  const [messages, setMessages] = useState<RoomMessage[]>([]);\n  const [online, setOnline] = useState(0);\n  const [status, setStatus] = useState<"connecting" | "open" | "closed">("connecting");\n  const socket = useRef<WebSocket | null>(null);\n\n  useEffect(() => {\n    let stopped = false;\n    let retry: ReturnType<typeof setTimeout> | undefined;\n    let tries = 0;\n    const connect = () => {\n      const url = new URL(`/api/rooms/${encodeURIComponent(id)}/ws`, location.href);\n      url.protocol = url.protocol === "https:" ? "wss:" : "ws:";\n      if (options.name) url.searchParams.set("name", options.name);\n      const ws = new WebSocket(url);\n      socket.current = ws;\n      setStatus("connecting");\n      const timeout = setTimeout(() => ws.close(), 10_000); // no answer (e.g. `next dev`, which can\'t serve rooms): retry later\n      ws.onopen = () => {\n        clearTimeout(timeout);\n        tries = 0;\n        setStatus("open");\n      };\n      ws.onmessage = (e) => {\n        const event = JSON.parse(String(e.data)) as RoomEvent;\n        if (event.type === "history") setMessages(event.messages);\n        else if (event.type === "message") setMessages((m) => [...m.slice(-49), event.message]);\n        else setOnline(event.online);\n      };\n      ws.onclose = () => {\n        clearTimeout(timeout);\n        setStatus("closed");\n        if (!stopped) retry = setTimeout(connect, Math.min(30_000, 1000 * 2 ** tries++)); // back off; give up never\n      };\n    };\n    connect();\n    return () => {\n      stopped = true;\n      clearTimeout(retry);\n      socket.current?.close();\n    };\n  }, [id, options.name]);\n\n  const send = useCallback((text: string) => {\n    if (socket.current?.readyState !== WebSocket.OPEN) return false;\n    socket.current.send(JSON.stringify({ text }));\n    return true;\n  }, []);\n\n  return { messages, online, status, send };\n}\n', "tsconfig.json": '{\n  "compilerOptions": {\n    "target": "ES2022",\n    "lib": [\n      "DOM",\n      "DOM.Iterable",\n      "ES2022"\n    ],\n    "module": "ESNext",\n    "moduleResolution": "Bundler",\n    "jsx": "react-jsx",\n    "strict": true,\n    "noEmit": true,\n    "skipLibCheck": true,\n    "isolatedModules": true,\n    "allowImportingTsExtensions": true,\n    "resolveJsonModule": true,\n    "esModuleInterop": true,\n    "incremental": true,\n    "plugins": [\n      {\n        "name": "next"\n      }\n    ],\n    "allowJs": true\n  },\n  "include": [\n    "next-env.d.ts",\n    "**/*.ts",\n    "**/*.tsx",\n    ".next/types/**/*.ts",\n    ".next/dev/types/**/*.ts"\n  ],\n  "exclude": [\n    "node_modules",\n    ".open-next",\n    ".wrangler",\n    "worker.ts",\n    "src/realtime/room.ts",\n    "examples"\n  ]\n}\n', "tsconfig.worker.json": '{\n  // worker.ts and the Durable Objects run in workerd, not in Next.js: their types come from\n  // `wrangler types` (npm run typecheck writes them to node_modules/.worker-env.d.ts).\n  "compilerOptions": {\n    "target": "ES2022",\n    "lib": ["ES2022"],\n    "module": "ESNext",\n    "moduleResolution": "Bundler",\n    "strict": true,\n    "noEmit": true,\n    "skipLibCheck": true,\n    "isolatedModules": true,\n    "allowImportingTsExtensions": true,\n    "types": []\n  },\n  "files": ["node_modules/.worker-env.d.ts", "worker.ts", "src/realtime/room.ts"]\n}\n', "worker.ts": '/**\n * The Worker\'s entry (wrangler.jsonc `main`): the live rooms\' WebSockets, which Next.js can\'t answer\n * (/api/rooms/<id>/ws \u2192 src/realtime/room.ts), then everything else to the Next.js app OpenNext built.\n * Durable Object classes are exported from here.\n */\n// @ts-ignore: .open-next/worker.js is written by `opennextjs-cloudflare build`\nimport { default as nextApp } from "./.open-next/worker.js";\n\nexport { Room } from "./src/realtime/room.ts";\n\nexport default {\n  async fetch(req, env, ctx) {\n    const room = /^\\/api\\/rooms\\/([^/]+)\\/ws$/.exec(new URL(req.url).pathname);\n    if (room) return env.ROOMS.getByName(decodeURIComponent(room[1]!)).fetch(req);\n    return nextApp.fetch(req, env, ctx);\n  },\n} satisfies ExportedHandler<Env>;\n', "wrangler.jsonc": '{\n  "$schema": "node_modules/wrangler/config-schema.json",\n  // One Worker: worker.ts (live rooms, then the Next.js app built by OpenNext into .open-next/) plus static assets.\n  "name": "my-app",\n  "main": "worker.ts",\n  "compatibility_date": "2026-09-01",\n  "compatibility_flags": ["nodejs_compat"],\n  "assets": {\n    "directory": ".open-next/assets",\n    "binding": "ASSETS"\n  },\n  // Storage and realtime: env.DB (SQLite), env.KV, env.FILES and the live rooms (src/realtime/room.ts).\n  // No ids: wrangler keeps local copies in .wrangler/state; `ambasada deploy` attaches the app\'s real ones.\n  "d1_databases": [{ "binding": "DB", "database_name": "my-app", "migrations_dir": "db/migrations", "migrations_table": "_ambasada_migrations" }],\n  "kv_namespaces": [{ "binding": "KV" }],\n  "r2_buckets": [{ "binding": "FILES", "bucket_name": "my-app" }],\n  "durable_objects": { "bindings": [{ "name": "ROOMS", "class_name": "Room" }] },\n  // Every Durable Object class needs a migration; add new ones at the end, never edit or remove an applied tag.\n  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Room"] }],\n  "observability": { "enabled": true }\n}\n' }, spa: { ".claude/skills/ambasada-product/SKILL.md": "---\nname: ambasada-product\ndescription: Build an app on Ambasada and put it online. Use when the user wants to make an app, tool, game or website, start one with `npm create ambasada@latest`, run it with `ambasada dev`, publish it with `ambasada deploy` at <slug>.ambasada.dev, show it in the Ambasada app (mini app, notifications, sign-in), store data in the app's SQLite database, KV or file storage, make it realtime with Durable Objects or an agent (Agents SDK), bring a site built in ChatGPT, Lovable, Bolt or v0, or upgrade a project made with an older CLI (`ambasada upgrade`). Default stack: Next.js on Cloudflare.\n---\n\n# Build an app on Ambasada and put it online\n\nAn app is **one website** (one Cloudflare Worker) at `https://<your-slug>.ambasada.dev`. It comes with\nSign in with Ambasada (Ambasada ID), a SQLite database, key-value, file storage and Durable Objects for\nrealtime. If you want, it also gets a mini app inside the Ambasada app, with push notifications (off by default). No servers, no\nCloudflare account, no keys to configure.\n\n## Start\n\n```sh\nnpm create ambasada@latest my-app           # Next.js (default)\ncd my-app && npm install\nnpx ambasada dev                            # the mock API + your site, no login\n```\n\nOther templates: add `-- --template spa` (Vite + React; for code exported from Lovable or Bolt) or\n`-- --template worker` (plain HTML + small fetch handlers; the smallest possible app). All three have the\nsame `ambasada.config.ts`, sign-in routes, notifications webhook and storage helpers, and a notes example.\n\n## What to read\n\n| The user wants to\u2026 | Read |\n|---|---|\n| know where files go, what Next.js features are allowed, secrets, who is signed in | [reference/stack.md](reference/stack.md) |\n| store data (tables, migrations), sessions or caches, uploads; make it live between people (chat, presence, a shared board, counters); build an AI agent | [reference/storage.md](reference/storage.md) |\n| run it locally, put it online, use their own Cloudflare account | [reference/dev-and-deploy.md](reference/dev-and-deploy.md) |\n| make it look good and easy to use | [reference/design.md](reference/design.md) |\n| show up in the Ambasada app (optional: `npx ambasada miniapp enable`), send push notifications, sign people in inside the app | [reference/mini-app.md](reference/mini-app.md) |\n| build in ChatGPT, Lovable, Bolt or v0 and bring it here | [reference/build-elsewhere.md](reference/build-elsewhere.md) |\n| upgrade a project made with an older CLI | [reference/upgrading.md](reference/upgrading.md) |\n\nFor the Hack A Ton (TON payments, offerings, the agent that runs a shop): `npx ambasada add village`, then\nthe **ambasada-village** skill.\n\n## Rules (break one and the app does not work)\n\n1. **One app = one Worker.** No separate backend, no Docker. State lives in the app's SQLite (`env.DB`),\n   key-value (`env.KV`), file storage (`env.FILES`) or a Durable Object, never in module variables.\n   See [reference/storage.md](reference/storage.md).\n2. **Only the allowed Next.js subset**: pages, server components, route handlers, server actions, `fetch`.\n   No `next/image` default loader, no ISR/`revalidate`, no `fs`/`child_process`/native packages, no custom\n   server, no `middleware.ts`/`proxy.ts`, no `runtime = \"edge\"`. See [reference/stack.md](reference/stack.md#nextjs-allowed-and-banned).\n3. **Keys never reach the browser.** They live in `.env` locally and `ambasada env set` online; only server\n   code reads them. Never prefix one with `NEXT_PUBLIC_`.\n4. **Sign-in is Ambasada ID.** Use the template's `/api/auth/*` routes and `auth.user(req)`; don't add\n   Clerk, Auth.js or Supabase Auth, and don't build an accounts table. Key per-person data by `user.id`.\n5. **Tables change through migrations**: a new `db/migrations/NNNN_name.sql` per change, never edits to an\n   applied one; `npx ambasada db migrate` after deploying.\n\n## When the user is not a developer\n\nDo the work; don't ask them to edit code. Ask at most: what it does and for whom. Then build one page, run\n`npx ambasada dev`, open it, use it as the fake visitor, and show them it worked. Explain in one sentence\nper step, no jargon.\n", ".claude/skills/ambasada-product/reference/build-elsewhere.md": "# Built in ChatGPT, Lovable, Bolt or v0\n\nThree ways, easiest first.\n\n## A. Keep it hosted there, link it\n\nGood for: a site that is finished where it is and only needs to show up in the Ambasada app.\n\n1. On a laptop with Node 22+, once:\n\n   ```sh\n   npm create ambasada@latest my-app -- --miniapp --entry /   # its ambasada.config.ts and the manifest\n   cd my-app && npm install\n   npx ambasada login\n   npx ambasada link https://YOUR-SITE\n   ```\n\n2. The site must serve `/.well-known/ambasada.json` and `/icon.png` (copy them from the new project's\n   `public/`; `npx ambasada dev` writes the manifest there) and pass `npx ambasada check https://YOUR-SITE`\n   ([mini-app.md](mini-app.md)).\n\nLimit: Sign in with Ambasada, notifications and the app's database, KV and files come with hosting on\nambasada.dev. A site hosted elsewhere keeps its own backend; use B or C to get them.\n\n## B. Bring the code home (recommended for Lovable and Bolt)\n\nGood for: anything with real work behind it. You get hosting on ambasada.dev and the full rules.\n\n1. Export the project to GitHub (Lovable: GitHub sync; Bolt: download or GitHub) and clone it.\n2. `npm create ambasada@latest my-app -- --template spa` and copy the exported `src/` (components, pages,\n   styles) into the new project's `src/`, replacing the starter UI. Keep the template's `api/`, `lib/`,\n   `db/`, `ambasada.config.ts`, `wrangler.jsonc` and `vite.config.ts`.\n3. Open the project in Claude Code, Cursor or Codex and say:\n\n   > This is an Ambasada app (see .claude/skills/ambasada-product). Replace Supabase/Firebase with the\n   > app's env.DB (tables in db/migrations), env.KV and env.FILES, and any login with Sign in with Ambasada\n   > (api/auth.ts, /api/auth/me). Then run it with `npx ambasada dev`.\n\n4. `npx ambasada dev`, try it, then `npx ambasada deploy`.\n\n## C. ChatGPT (or any chat) writes the code, you paste it\n\n1. `npm create ambasada@latest my-app`, `cd my-app && npm install`, `npx ambasada dev`.\n2. Paste this into ChatGPT, then the files it mentions, then your idea:\n\n   > I have a Next.js 16 App Router project that runs on Cloudflare Workers (OpenNext). Rules: no `fs`, no\n   > native packages, no `next/image` (use `<img>`), no middleware, no `revalidate`, no other login than the\n   > one in `app/api/auth`. Data goes in SQLite through `lib/db.ts` (tables in `db/migrations/*.sql`), the\n   > signed-in person comes from `currentUser()` in `lib/ambasada.ts`. Below are my `app/page.tsx`,\n   > `app/api/notes/route.ts` and `db/migrations/0001_init.sql`. Rewrite them for my idea: the main action\n   > visible on a phone without scrolling. Write complete files, one code block per file, with the file path\n   > above each. My idea: \u2026\n\n3. Paste each file where ChatGPT says, keep `npx ambasada dev` running, check the page. New tables: a new\n   file in `db/migrations/` (never edit an applied one). When it works: `npx ambasada deploy` and\n   `npx ambasada db migrate`.\n\nUse ChatGPT to write files, not to decide the stack: if its answer adds Prisma, Supabase, NextAuth,\n`next/image` or a `middleware.ts`, tell it \"that's banned in my project, do it without\".\n", ".claude/skills/ambasada-product/reference/design.md": '# Design for people who decide in 10 seconds\n\nPeople open your app on a phone, often inside the Ambasada app, between two other things. They decide in\nseconds whether it is for them. Build for that.\n\n## One page, one action\n\n- **One page first.** What it is, and the one thing to do, fit on the first screen of a phone (375 \xD7 667).\n  Extra pages only when the action needs them.\n- **One action.** One button that does the main thing. Add a second only after people use the first.\n- **Few words.** A headline of up to 8 words, one sentence under it, the button. Cut every adjective you can.\n- **Show the result.** One example of what people get (an image, a sample text) beats any description.\n- **No walls.** No signup before the first use, no cookie banner, no tour. Ask for sign-in when the app\n  needs to remember someone (Sign in with Ambasada is one tap inside the Ambasada app).\n\n## The button\n\n- Label it with the action: **Make my poem**, not **Submit**.\n- Big (at least 48 px tall), full width on phones, one strong colour, nothing else in that colour.\n- If people must type something first, put that one field right above the button.\n- After the action, show the result, or "Working on it\u2026" and the result appearing when ready (a live room\n  or polling). Never a blank page.\n\n## Look\n\n- The templates use `@ambasada/ui` (the Ambasada app\'s look: tokens, `ui-card`, `ui-button`); start there\n  ([mini-app.md](mini-app.md)). Otherwise plain CSS: one font, two colours plus grey, generous spacing.\n- Large text: 18 px body on phones, a headline twice that. Light theme.\n- Works with one thumb: tap targets 48 px, no hover-only menus.\n- Loads fast: no video backgrounds, no 3 MB hero images, no animation libraries.\n\n## Words\n\n- Say what they get, not how it works. "A logo in 1 minute", not "AI-powered logo generation".\n- Write in the language of your users; one is fine.\n\n## Before and after\n\n```\nBad:  Welcome to PoemForge\u2122, the next-generation AI-powered creative writing platform\n      [Features] [Pricing] [About] [Sign up]   \u2026scroll\u2026   [Get started]\n\nGood: Your name as a folk poem\n      Type a name. Get a 4-line Romanian folk poem in 10 seconds.\n      [ Name: _________ ]\n      [   Make my poem   ]\n      "Ana, floare de la munte, / \u2026"  \u2190 one real example\n```\n', ".claude/skills/ambasada-product/reference/dev-and-deploy.md": "# Run it, put it online\n\n## `ambasada dev`: everything on your laptop\n\n```sh\nnpx ambasada dev\n```\n\nStarts two things:\n\n1. a **mock Ambasada API** on `http://127.0.0.1:8788`: same routes and signatures as the real one. Sign in\n   with Ambasada signs you in as \"Fake Visitor\"; `apps.notify` lands in a fake hub; `ambasada.store` and\n   `ambasada.files` work in memory. Open it in a browser for a page with what happened.\n2. **your site** with its normal dev server (`next dev`, `vite` or `wrangler dev`), pointed at the mock.\n\nNo login. The app's database, KV, files and Durable Objects run locally too (wrangler, `.wrangler/state`);\n`ambasada dev` applies `db/migrations/` to the local database before it starts the site.\n\nTry it: open your site, sign in, add a note. With the mini app on, `http://localhost:3000/app?ambasada_shell=mock`\n(your `miniapp.entry`) pretends to be inside the Ambasada app (host bar insets, silent sign-in).\n\n`npx ambasada dev --mock-only` starts only the mock, if you run your site yourself. The mock's keys:\n`AMBASADA_API_URL=http://127.0.0.1:8788`, `AMBASADA_API_KEY=sk_test_dev` (already in the project's `.env`).\n\n## `ambasada deploy`: online at `<slug>.ambasada.dev`\n\nOnce, in the app's folder:\n\n```sh\nnpx ambasada login        # opens a page: sign in with Ambasada ID\n```\n\n(If it asks for a key instead: https://developer.ambasada.dev \u2192 your app \u2192 a project key, `vk_\u2026`.)\nEach app's key is kept under its id: with two apps on one laptop, log in once in each folder, and each folder uses\nits own. `deploy`, `db`/`kv`/`files`, `env`, `logs`, `tunnel` and the village's commands that change something refuse\na key of another app than the folder's `id` (\"this folder is X, you are logged in as Y\"); `--company Y` goes ahead.\n\nThen, every time you want the new version online:\n\n```sh\nnpx ambasada deploy\n```\n\nIt does, in order:\n\n1. **build**: `opennextjs-cloudflare build` (Next), `vite build` (spa) or a bundle of the Worker (worker);\n2. **smoke test**: runs the built Worker locally in workerd and requests `/` and `/.well-known/ambasada.json`\n   (written from `ambasada.config.ts` first, when the mini app is on: [mini-app.md](mini-app.md));\n   a crash stops the deploy (skip with `--no-smoke` only if you know why it fails);\n3. **upload**: the URL is `https://<your-slug>.ambasada.dev`, with `AMBASADA_API_KEY`, `AMBASADA_API_URL`,\n   Sign in with Ambasada and the app secret set for you, and the app's own database, KV namespace and bucket\n   bound as `DB`, `KV`, `FILES` (created on the first deploy) plus the Durable Objects from `wrangler.jsonc`.\n\nThe database's tables are not created by the deploy: run `npx ambasada db migrate` (it applies the new files\nin `db/migrations/`). No Cloudflare account needed. `--dry-run` builds and prints what it would upload.\n\nYour own secrets (an API key for another service): `npx ambasada env set NAME value` (live within about 30 s, and on\nevery deploy); `npx ambasada env list` shows the names. `.env` (and `.env.local`, `.env.production`, `.dev.vars`) never\ngoes online: the deploy builds without them, so a value that is only there is missing on ambasada.dev; `env set` it.\n\nLimits: 10 MB compressed bundle, 1000 static files, short CPU time per request (waiting on `fetch` does not\ncount). Heavy work belongs in an API you call, or a Durable Object, not in one request.\n\n## `ambasada dev --tunnel`: your laptop, live\n\nWhen the Ambasada app, sign-in or webhooks need to reach the version on your laptop (before deploying, or to\ndebug), log in once, then:\n\n```sh\nnpx ambasada dev --tunnel         # your dev server, against the real API, at https://<slug>-dev.ambasada.dev\nnpx ambasada tunnel --port 5173   # or: only the tunnel, for a server you started yourself\n```\n\nUntil Ctrl+C, `https://<slug>-dev.ambasada.dev` is your app's URL. There is no mock in this mode. The first\ntime takes up to 2 minutes while the address is published; after that it is instant. Only one terminal per\napp at a time: `--force` takes it over. More: docs/TUNNEL.md.\n\n## `ambasada deploy --own`: your own Cloudflare account\n\nRuns `wrangler deploy` into your account (you need `npx wrangler login` first), then\n`ambasada link <your workers.dev URL>`. Set the secrets yourself: `npx wrangler secret put AMBASADA_API_KEY`.\n\n## `ambasada link`: the app is hosted somewhere else\n\n```sh\nnpx ambasada link https://my-thing.lovable.app\n```\n\nSets `product.url` in `ambasada.config.ts` and checks that `<url>/health` answers. Use it for Lovable, Bolt,\nv0, Vercel, your own server. See [build-elsewhere.md](build-elsewhere.md).\n\n## Watch it run\n\n```sh\nnpx ambasada logs --follow     # the last deploy and new errors\nnpx ambasada check https://<slug>.ambasada.dev   # https, no redirects, speed; the mini-app rules when it is on\n```\n\nThe Developer app (https://developer.ambasada.dev) has deploys, errors, users and the storage tabs.\n\n## Upgrading\n\nA new devkit: `npx ambasada upgrade` (dependencies, skills, mechanical code changes), then\n[upgrading.md](upgrading.md) for the steps a coding agent does.\n\n## When it goes wrong\n\n| Symptom | Fix |\n|---|---|\n| build fails on `fs`, `child_process`, a `.node` file, `sharp` | a banned package: see [stack.md](stack.md#nextjs-allowed-and-banned) |\n| smoke test: `/` answers 500 | open `npx ambasada dev`, load `/`, read the terminal error |\n| `no such table: \u2026` online | `npx ambasada db migrate` |\n| a Durable Object migration is refused on deploy | never edit or remove a deployed tag in `wrangler.jsonc`'s `migrations`; add the next one ([storage.md](storage.md)) |\n| `CONFIG: no API key` | missing `AMBASADA_API_KEY`: `.env` locally, `ambasada login` before deploying |\n| sign-in loops back to the login page | `PUBLIC_URL` differs from the URL in the browser; remove it or fix it |\n| `this app uses the village \u2026 not installed` | a Hack A Ton project: `npx ambasada upgrade` (adds `@ambasada/village`) |\n", ".claude/skills/ambasada-product/reference/mini-app.md": '# The app inside the Ambasada app (mini app)\n\n**Optional, opt in with `npx ambasada miniapp enable`** (or `npm create ambasada@latest my-app -- --miniapp`). An app\nis a website first; most stay that way. The mini app is one more surface of it, at a path: what the Ambasada mobile\napp opens, with silent sign-in and push notifications. Platform spec: docs/MINI-APPS.md (\xA715, decision 15.6).\n\n## Turn it on\n\n```sh\nnpx ambasada miniapp enable              # at /app; --entry /in-app for another path, --entry / for the whole site\nnpx ambasada miniapp                     # on or off, and the entry\nnpx ambasada miniapp enable --entry /app --force   # move it: --force removes what the old entry left (it lists them otherwise)\nnpx ambasada miniapp disable             # off again: the config key, the manifest and the glue (pages at /app stay until --force)\n```\n\nIt adds:\n\n| | |\n|---|---|\n| `miniapp: { entry: "/app", age_rating: "4+", kind: "tool" }` | `ambasada.config.ts`; optional `support` (email or URL, else the app\'s `support`), `tags` (\u2264 5), `subtitle`, `description`, `icon`, `category`, `accent`, `scopes`, `visibility`. The hub refuses an app without `age_rating` (`4+`, `9+`, `12+`, `17+`) |\n| the in-app layout and page, no site header | `app/app/` (Next), `src/in-app/InApp.tsx` rendered by `src/main.tsx` (spa), `web/app.html` (worker) |\n| `ready()` and silent sign-in | `app/app/in-app.tsx`, `src/in-app/shell.ts`, `web/in-app.js`; with `--entry /` hooked into the root layout instead |\n| a placeholder icon, 1024\xD71024 | `public/icon.png` (`web/icon.png`): replace it, keep it square and opaque |\n| `@ambasada/miniapp` | `package.json` (Next, spa): run `npm install` |\n\nThe manifest, `/.well-known/ambasada.json`, is not a file you keep: `ambasada dev` and `ambasada deploy` write it\nfrom `ambasada.config.ts` (id, name, description, `miniapp`) into `public/` (`web/`), and `.gitignore` leaves it out.\nTo write it by hand, put your own there and drop that `.gitignore` line: yours wins. Without `miniapp`, nothing is\nserved, `ambasada check` says "mini app: off" and the deploy does not register the app with the Ambasada app.\n\n## Is it listed?\n\n`ambasada deploy` registers the app with the Ambasada hub only when it serves the manifest, then checks it. It prints:\n\n```\n\u2713 in the Ambasada app: Listed for the event\n! in the Ambasada app: Unlisted \xB7 needs: icon, viewport\n  mini app: off, not in the Ambasada app (`ambasada miniapp enable` adds one)\n```\n\nUnlisted apps work, but only you see them in the Ambasada app. Fix what `needs` says and deploy again,\nor run `npx ambasada check https://<slug>.ambasada.dev` (or `npx ambasada check` for the local folder).\nThe checks: `/.well-known/ambasada.json` valid, `icon.png` a 1024\xD71024 PNG with no transparency, the entry page\nhas `<meta name="viewport" content="width=device-width, initial-scale=1">`, no dark-only theme, it answers in under\n3 s without a redirect, `/api/auth/callback` exists, the notifications webhook answers a signed ping. With the mini\napp off, only https, no redirects and the response time of `/`. On a first deploy the webhook\'s secret takes a few\nminutes to arrive: the deploy says `checks: running (up to 5 min)`, and `npx ambasada check` shows the result.\nConnected tools can do the same through MCP: `app_status`, `app_check`.\n\n## Look like the app: @ambasada/ui\n\nThe templates import `@ambasada/ui` (tokens, Inter + JetBrains Mono, `ui-card`, `ui-button`, `ui-row`,\n`ui-pill`, `ui-sheet`, `ui-stepper`, `ui-empty`, `ui-skeleton`). Use those classes before writing CSS.\nReact: `import { Card, Button, Sheet } from "@ambasada/ui/react"`. Plain HTML: one\n`<link rel="stylesheet" href="https://unpkg.com/@ambasada/ui@0.8/dist/ambasada-ui.css">`.\nLeave space for the app\'s bar: the page uses `--ambasada-safe-area-*` and `--ambasada-host-bar`.\nLight theme only; one red (primary) button per screen.\n\n## Notifications\n\nAlready wired in every template; they work once the mini app is on:\n\n| Piece | Where |\n|---|---|\n| manifest: `"scopes": ["identity", "notifications"]`, `"notifications": { "webhook": "/api/ambasada/webhook" }`, `"privacy_url": "/privacy"` | generated from `ambasada.config.ts` (the defaults; `miniapp.scopes` to change them) |\n| the webhook: verifies the hub\'s signature, saves `token \u2194 Ambasada user id` in `ambasada.store` | `app/api/ambasada/webhook/route.ts` (Next), `api/ambasada-webhook.ts` (spa, worker) |\n| `notifyUser(app, userId, { \u2026 })`: push to one person if they turned notifications on | `lib/notifications.ts` |\n| the privacy page the scopes need | `app/(site)/privacy/page.tsx`, `public/privacy.html`, `web/privacy.html` |\n\nSend one when something the person waits for happens (their order is ready), never as marketing:\n\n```ts\nimport { notifyUser } from "../lib/notifications.ts";\n\nconst user = await ambasada().auth.user(req);            // signed in with Ambasada\nif (user) await notifyUser(ambasada(), user.id, {\n  notification_id: `order-${id}-ready`,                  // unique per message; repeats are dropped for 24 h\n  title: "Your translation is ready",                    // \u2264 40 characters\n  body: "Tap to read it.",                               // \u2264 140\n  url: `/orders/${id}`,                                  // a path on your site: where the tap opens\n});\n```\n\nPeople turn notifications on in the app (the app asks; the page can ask too with\n`notifications.request()` from `@ambasada/miniapp`, from a button). The secret (`AMBASADA_APP_SECRET`) is\ninjected by `ambasada deploy`; never put it in the browser.\n\n## Signed in without a consent screen\n\nInside the Ambasada app the page signs in silently: `auth.signIn()` from `@ambasada/miniapp` gets a short\ntoken from the app and POSTs it to `/api/auth/shell`, which sets the same session as "Sign in with\nAmbasada". Server code doesn\'t change: `currentUser()` / `ambasada().auth.user(req)` work either way.\nOn the web, the button and consent screen stay. Silent sign-in needs the app to be Verified; until then\n`signIn()` resolves `null` and the button shows.\n\n## Try it locally\n\n`npx ambasada dev` plays the hub (with the mini app on): when your app starts it sends a signed `ping` and\n`notifications_enabled` to your webhook (the token lands in the store as\n`ambasada/notifications/user_fake_visitor`), and its `/api/apps/notify` accepts pushes for that token\n(they show in the terminal). Open `http://localhost:3000/app?ambasada_shell=mock` (your entry) to pretend to be\ninside the app: the fake shell signs you in silently as "Fake Visitor".\n', ".claude/skills/ambasada-product/reference/stack.md": '# The stack: Next.js on Cloudflare\n\nEvery Ambasada app is one Cloudflare Worker. The default template builds it from **Next.js 16.4**\nwith **@opennextjs/cloudflare 1.20** (the OpenNext adapter) and the `nodejs_compat` flag. You write a\nnormal Next.js App Router app; `ambasada deploy` turns it into a Worker.\n\n## Folder layout (template `next`)\n\n```\nmy-app/\n  app/layout.tsx               <html>, the Ambasada look (@ambasada/ui) and globals.css\n  app/(site)/layout.tsx        the site\'s header (app/account.tsx) around its pages; (site) is not in the URL\n  app/(site)/page.tsx          the landing page\n  app/notes.tsx                the notes example (a client component calling app/api/notes)\n  app/api/notes/route.ts       rows in env.DB, the list cached in env.KV\n  app/api/files/route.ts       uploads to env.FILES; app/files/[...key]/route.ts serves them\n  app/api/auth/*/route.ts      Sign in with Ambasada: login, callback, logout, me, shell (silent, in the app)\n  app/api/ambasada/webhook/    the Ambasada app\'s events: who turned notifications on (reference/mini-app.md)\n  app/account.tsx              the header: "Sign in with Ambasada", or the person\'s name and avatar\n  app/(site)/privacy/page.tsx  what you keep about people (the mini app\'s privacy_url)\n  app/(site)/room/             the live room demo\n  app/app/                     the mini app, once on (`ambasada miniapp enable`): its layout, page and in-app.tsx\n  lib/ambasada.ts              the Ambasada client for server code (reads the Worker env)\n  lib/notifications.ts         notifyUser(): a push to one person who turned notifications on\n  lib/db.ts, kv.ts, files.ts   env.DB, env.KV, env.FILES (reference/storage.md); lib/bindings.ts reaches them\n  db/migrations/               the database\'s tables, one .sql file per change\n  src/realtime/                the live room (a Durable Object) and its React hook\n  ambasada.config.ts           app id, name, one-line description, product URL, `miniapp` (optional)\n  wrangler.jsonc               Worker settings (nodejs_compat, assets) and the bindings DB, KV, FILES, ROOMS\n  worker.ts                    the Worker entry: live rooms\' WebSockets, then the Next.js app\n  open-next.config.ts          OpenNext settings; leave as is\n  .env                         secrets for local runs (never commit, never send to the browser)\n  .ambasada/project.json       the template and devkit version (`ambasada upgrade` reads it); commit it\n  .claude/skills/              this skill\n```\n\nOne more endpoint = one more `app/api/<name>/route.ts`. Data it keeps goes in `env.DB` (a migration in\n`db/migrations/`), `env.KV` or `env.FILES` ([storage.md](storage.md)).\n\n## Using the client\n\nServer code only (route handlers, server components, server actions):\n\n```ts\n// app/api/hello/route.ts\nimport { ambasada } from "../../../lib/ambasada.ts";\n\nexport async function GET(req: Request) {\n  const user = await ambasada().auth.user(req);\n  return Response.json({ hello: user?.name ?? "stranger" });\n}\n```\n\n`lib/ambasada.ts` creates one client per Worker instance with `createAmbasada({ env })` from `@ambasada/sdk`,\nwhere `env` comes from `getCloudflareContext()` (deployed); under `next dev` the SDK reads `process.env`.\nIt reads `AMBASADA_API_KEY` and `AMBASADA_API_URL` (default https://api.ambasada.dev). The client has `auth`\n(below), `apps` (notifications, [mini-app.md](mini-app.md)), `store` and `files`.\n\n## Who is signed in\n\nEvery hosted app gets **Sign in with Ambasada** (Ambasada ID) for free: no keys, no settings.\nThe template\'s header already has the button. In server code:\n\n```ts\nimport { currentUser } from "../lib/ambasada.ts";\nimport { bindings } from "../lib/bindings.ts";\nimport { run } from "../lib/db.ts";\n\nconst user = await currentUser(); // null, or { id, name, avatar_url, builder, pass, member_since, \u2026 }\nif (!user) redirect("/api/auth/login?returnTo=/orders");\nawait run(bindings().DB, "INSERT INTO orders (user_id, item) VALUES (?, ?)", user.id, item); // key per-person data by user.id\n```\n\nIn a route handler, `ambasada().auth.user(req)` does the same. Client components fetch `/api/auth/me`.\nAsk for the email only if you need it: `/api/auth/login` calls `auth.login(req, { email: true })`.\nDon\'t build your own login or accounts table, and don\'t add Clerk, Auth.js or Supabase Auth.\n\n## Next.js: allowed and banned\n\nAllowed, and enough for any product here:\n\n- pages and layouts (`app/**/page.tsx`, `layout.tsx`), server components, client components (`"use client"`)\n- route handlers (`app/api/**/route.ts`), server actions (`"use server"`)\n- `fetch` to any HTTPS API, `next/link`, `next/font`, plain CSS / CSS modules / Tailwind\n\nBanned (they fail on Workers or break the deploy):\n\n| Don\'t | Do instead |\n|---|---|\n| `next/image` with the default loader | `<img>`, or `images: { unoptimized: true }` in `next.config.ts` |\n| ISR, `export const revalidate = \u2026`, `revalidatePath`, `unstable_cache` | render on each request (`export const dynamic = "force-dynamic"`), or cache results in `env.KV` |\n| `fs`, `child_process`, `sharp`, `bcrypt`, `sqlite3`, `puppeteer`, any native package | `fetch` an API (an LLM provider with your own key in a secret, for example) |\n| a custom server (`server.js`, Express inside Next) | route handlers |\n| `middleware.ts` / `proxy.ts`, `export const runtime = "edge"` | check inside the page or route handler; Next\'s default runtime is right |\n| Prisma, Drizzle with a database, Supabase, Firebase, Mongo, Redis | `env.DB` (SQLite), `env.KV`, `env.FILES` ([storage.md](storage.md)) |\n| writing files at runtime, global variables as storage | `env.DB`, `env.KV`, `env.FILES` or a Durable Object (each request can run on a different machine) |\n\nKeep the bundle small: the Worker limit is 10 MB compressed. Big UI kits and icon packs are the usual cause.\n\n## Where data lives\n\nThe app has its own SQLite database (`env.DB`), key-value (`env.KV`), file storage (`env.FILES`, public at\n`/files/<key>`) and Durable Objects for live state, created at the first deploy. Which one fits, the migrations\nworkflow and copy-paste patterns: [storage.md](storage.md).\n\nAlso there, for small things: `ambasada.store` (JSON, 1 MB for the whole app: settings, not user data) and\n`ambasada.files.put(\u2026)` \u2192 `{ url }` (platform-hosted files that expire).\n\n## Secrets\n\n- Local: `.env` in the project (Cloudflare\'s `.dev.vars` works too). The template writes it with test\n  values for `ambasada dev`. Both are in `.gitignore`; keep them there.\n- Deployed: `ambasada deploy` injects `AMBASADA_API_KEY`, `AMBASADA_API_URL`, the Sign in with Ambasada\n  credentials (`AMBASADA_AUTH_*`) and the mini-app secret (`AMBASADA_APP_SECRET`, with `AMBASADA_HUB_URL`\n  and `AMBASADA_APP_ORIGIN`) for you. With `--own`, set them yourself: `npx wrangler secret put AMBASADA_API_KEY`.\n- Your app\'s own URL (links in emails, notifications, answers): `appOrigin()` in `lib/ambasada.ts`, from\n  `AMBASADA_APP_ORIGIN` (the deploy and `ambasada dev` set it), not `req.url`: a call the platform forwards to your\n  app may come without its Host.\n- Other services\' keys (an OpenAI key, say): `.env` locally, `npx ambasada env set OPENAI_API_KEY \u2026` online;\n  read on the server only. `ambasada deploy` builds without `.env*`: nothing in them reaches the Worker.\n- Anything named `NEXT_PUBLIC_*` (`VITE_*` in the spa) is copied into the browser. Never put a key there. From `.env`\n  they work under `ambasada dev` only; a public value the live page needs goes in the code.\n- Never paste a key into a page, a client component, a prompt for a no-code builder, or a commit.\n\n## Variants\n\n- `spa`: Vite + React with `@cloudflare/vite-plugin`, for code exported from Lovable or Bolt. The\n  `api/` endpoints are small fetch handlers; the React app calls them with `fetch("/api/\u2026")`.\n- `worker`: `web/` (plain HTML/CSS) plus `api/*.ts` fetch handlers. Best when the app is a page or two.\n\nThe rules on this page (state, secrets, no native packages) apply to all three.\n', ".claude/skills/ambasada-product/reference/storage.md": '# Data, files and realtime\n\nEvery app on ambasada.dev gets a real database, key-value, file storage and Durable Objects. They are created\nat the first `ambasada deploy` and bound to the Worker on every deploy; nothing to sign up for or configure.\nLocally (`ambasada dev`, `wrangler dev`, `vite`) wrangler runs the same things from `.wrangler/state`.\n\n| Need | Use | Not |\n|---|---|---|\n| anything with rows: users\' data, orders, posts, scores, anything you query, sort or join | `env.DB` (SQLite, D1) | KV, files, `ambasada.store` |\n| sessions, caches of slow results, feature flags, "seen this already" | `env.KV` | a table you scan |\n| uploads, images, audio, PDFs, generated files | `env.FILES` (R2), public at `/files/<key>` | base64 in the database |\n| state several people see change live: chat, presence, a shared board, a game table, live counters, a queue, rate limits, one thing per entity | a Durable Object (`env.ROOMS` in the templates) | polling the database |\n| an AI agent with memory, schedules and live state per user or task | the Agents SDK (`examples/agent/`) | a cron that rereads everything |\n| a few small settings for a tiny app | `ambasada.store` (1 MB per app) | user data of any size |\n\nQuotas per app: database 500 MB, KV 1 GB, files 5 GB. A database over its quota stops the next deploy.\n\n## `env.DB`: SQLite\n\nSchema lives in `db/migrations/`, one file per change, applied in name order, never edited once applied:\n\n```sql\n-- db/migrations/0002_orders.sql\nCREATE TABLE orders (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  user_id TEXT NOT NULL,\n  item TEXT NOT NULL,\n  paid INTEGER NOT NULL DEFAULT 0,\n  created_at INTEGER NOT NULL\n);\nCREATE INDEX orders_user ON orders (user_id, created_at);\n```\n\n```sh\nnpx wrangler d1 migrations apply DB --local   # the local database, for ambasada dev\nnpx ambasada db migrate                       # the app\'s database online (run before or right after deploying)\nnpx ambasada db shell "SELECT * FROM orders LIMIT 5"\n```\n\nQuery with `lib/db.ts` (SQL with `?` placeholders, typed rows, no ORM):\n\n```ts\nimport { all, batch, first, run } from "../lib/db.ts";\n\ntype Order = { id: number; user_id: string; item: string; paid: number; created_at: number };\nconst mine = await all<Order>(env.DB, "SELECT * FROM orders WHERE user_id = ? ORDER BY created_at DESC LIMIT 50", user.id);\nconst one = await first<Order>(env.DB, "SELECT * FROM orders WHERE id = ?", id);\nconst { lastRowId } = await run(env.DB, "INSERT INTO orders (user_id, item, created_at) VALUES (?, ?, ?)", user.id, item, Date.now());\nawait batch(env.DB, [["UPDATE stock SET n = n - 1 WHERE item = ?", item], ["UPDATE orders SET paid = 1 WHERE id = ?", id]]); // all or nothing\n```\n\nIn Next.js route handlers and server components, the bindings come from `bindings()` (`lib/bindings.ts`):\n`const { DB } = bindings();`. In the spa and worker templates, handlers get `env`.\n\nRules: always placeholders, never string-built SQL. Key per-person rows by the Ambasada user id\n(`auth.user(req).id`). Add an index for every `WHERE` you run often. Times as `Date.now()` integers.\n\n## `env.KV`: sessions, caches, flags\n\nReads are fast everywhere; a write shows up everywhere within about a minute; one write per second per key.\n\n```ts\nimport { cached, getJson, putJson } from "../lib/kv.ts";\n\nawait putJson(env.KV, `session:${id}`, { userId }, { ttl: 60 * 60 * 24 });\nconst session = await getJson<{ userId: string }>(env.KV, `session:${id}`);\nconst stats = await cached(env.KV, "home:stats", 300, () => computeStats(env)); // recompute at most every 5 min\n```\n\nNot for counters, balances or anything two people write at once: use `env.DB` (a transaction) or a Durable Object.\n\n## `env.FILES`: uploads and generated files\n\n```ts\nimport { serveFile, upload } from "../lib/files.ts";\n\n// POST /api/files: a signed-in person uploads (the templates\' api/files.ts)\nconst { key, url } = await upload(env.FILES, req.body, { contentType: req.headers.get("content-type") ?? undefined, folder: `u/${user.id}` });\nawait run(env.DB, "INSERT INTO photos (user_id, file_key) VALUES (?, ?)", user.id, key); // keep the key, not the bytes\n\n// GET /files/*: already wired in every template, with ETag, ranges and cache headers\nreturn serveFile(env.FILES, req);\n```\n\n`url` is `/files/<key>` on the app (`https://<slug>.ambasada.dev/files/<key>`): public to anyone with the link.\nPrivate files: store them under a key nobody can guess and serve them from your own route that checks\n`auth.user(req)` first, instead of `/files/*`. `npx ambasada files list | put | url | delete` from the terminal.\n\n## Durable Objects: realtime and per-entity state\n\nA Durable Object is one tiny server per id (a room, a document, a match, a user) with its own SQLite, that\nevery request for that id reaches. Use one whenever people must see each other\'s changes live, or one thing\nmust never be updated by two requests at once. The templates ship `src/realtime/room.ts` (`env.ROOMS`):\n\n```ts\n// the Worker: /api/rooms/<id>/ws \u2192 the room\nconst room = /^\\/api\\/rooms\\/([^/]+)\\/ws$/.exec(pathname);\nif (room) return env.ROOMS.getByName(decodeURIComponent(room[1]!)).fetch(req);\n```\n\n```ts\n// the room (shortened): WebSocket hibernation, broadcast, its own SQLite\nexport class Room extends DurableObject<unknown> {\n  async fetch(req: Request) {\n    const { 0: client, 1: server } = new WebSocketPair();\n    this.ctx.acceptWebSocket(server);              // hibernation: no cost while nobody talks\n    server.serializeAttachment({ name: "guest" }); // per-connection data that survives hibernation\n    return new Response(null, { status: 101, webSocket: client });\n  }\n  async webSocketMessage(ws: WebSocket, data: string | ArrayBuffer) {\n    this.ctx.storage.sql.exec("INSERT INTO messages (text, at) VALUES (?, ?)", String(data), Date.now());\n    for (const peer of this.ctx.getWebSockets()) peer.send(String(data)); // everyone in the room\n  }\n}\n```\n\n```tsx\n// the browser (React): src/realtime/use-room.ts\nconst { messages, online, send, status } = useRoom(roomId, { name: user.name });\n```\n\nA new class needs a binding and a migration in `wrangler.jsonc` (new tags go at the end; never edit or remove one\nthat was deployed; to drop a class add `{ "tag": "v3", "deleted_classes": ["Old"] }`):\n\n```jsonc\n"durable_objects": { "bindings": [{ "name": "ROOMS", "class_name": "Room" }, { "name": "BOARDS", "class_name": "Board" }] },\n"migrations": [{ "tag": "v1", "new_sqlite_classes": ["Room"] }, { "tag": "v2", "new_sqlite_classes": ["Board"] }]\n```\n\nExport the class from the Worker\'s entry (`src/worker.ts`; spa `worker/index.ts`; next `worker.ts`).\nOther shapes, same pattern: presence (who is online), a live counter (`UPDATE \u2026 RETURNING`, then broadcast), a\nper-user rate limit (`getByName(user.id)`), a job queue (`this.ctx.storage.setAlarm`). A Durable Object belongs\nto this app; other apps can\'t reach it. Under `next dev` they don\'t run: use `npm run preview` (workerd).\n\n## Agents (Agents SDK)\n\nFor agentic products (an assistant per user, a research task that runs for minutes, a bot that follows up),\nuse the Cloudflare Agents SDK: `examples/agent/` in the template (`npm i agents`, four lines to wire). An agent\nis a Durable Object with live state synced to clients (`setState`, `useAgent` in React), `this.sql`,\n`this.schedule(\u2026)` and WebSockets. One agent per user or task: `/agents/agent-example/<user id>`.\n\n## Don\'t\n\n- Poll (`setInterval(fetch\u2026)`) for what others changed: a Durable Object + WebSocket pushes it.\n- Put files or base64 in the database or KV: `env.FILES`, and keep the key in a row.\n- Keep user data in `ambasada.store`: it is 1 MB for the whole app.\n- Keep state in module variables or global objects: every request may run on another machine.\n- Count, rank or move money in KV: use a SQL transaction (`batch`) or a Durable Object.\n- Build SQL by joining strings with user input: `?` placeholders.\n- Edit an applied migration: add the next file.\n- Add Prisma, Drizzle with Postgres, Supabase, Firebase, Mongo or Redis: everything above is already here.\n', ".claude/skills/ambasada-product/reference/upgrading.md": "# Upgrading a project\n\n`npx ambasada upgrade` does the mechanical part: every `@ambasada/*` dependency to the CLI's version, the\npackage manager, `.claude/skills/ambasada-*` re-synced (the project's own skills are left alone), the code\nchanges listed below as \"done by `upgrade`\", the `ambasada check` rules, and `.ambasada/project.json`\n(the template and devkit version). `npx ambasada upgrade --check` only reports.\n\nWhat is left is below, per version, for a coding agent. Do the steps for every version between the one in\n`.ambasada/project.json` (none: 0.7) and the current one, in order. After each, run the app with\n`npx ambasada dev` and the project's `typecheck` script.\n\n## 0.7 \u2192 0.8: the platform and the village split\n\n0.8 splits the devkit: `@ambasada/sdk` and `ambasada` are the platform (sign-in, notifications, storage,\nhosting); the Hack A Ton economy (TON, checkout, offerings, the agent) is the add-on `@ambasada/village`.\n\nDone by `upgrade`:\n\n- the village names (`village`, `createVillage`, `offering`, `defineCompany`, `isVillageError`, the receipt and\n  webhook helpers, their types) import from `@ambasada/village`; in a village app `createAmbasada` became\n  `createVillage` and `DEFAULT_API_URL` became `DEFAULT_VILLAGE_API_URL` (their 0.7 meaning);\n- `@ambasada/village` added to `package.json` when the app has `offerings.ts` or an `idea`;\n- `.env` / `.dev.vars`: `AMBASADA_API_URL=https://hackaton.ambasada.id` became `https://api.ambasada.dev` plus\n  `AMBASADA_VILLAGE_API_URL=https://hackaton.ambasada.id`;\n- the `ambasada-payments` skill replaced by `ambasada-village`.\n\nFor the agent:\n\n1. **Platform code uses the platform client.** Files that only sign people in, send notifications or use\n   `store`/`files` can import `createAmbasada` / `ambasada` from `@ambasada/sdk` instead of the village client.\n   Leave files that sell, check receipts or call `llm` on the village client.\n2. **Config.** `ambasada.config.ts` may stay `defineCompany({ id, name, idea, \u2026 })`; the 0.8 form is\n   `defineCompany(defineApp({ id, name, description, product }), { idea, offerings, agent })` with\n   `defineApp` from `@ambasada/sdk`. Add a one-line `description` (the manifest's subtitle).\n3. **CLI calls.** In scripts, READMEs and `package.json`: `ambasada wallet|ledger|offerings|market|steer|webhook|links`\n   \u2192 `ambasada village \u2026`, `ambasada logs --agent` \u2192 `ambasada village logs --agent`, `ambasada dev buy` \u2192\n   `ambasada village dev buy`. The old spellings still work through 1.x with a warning.\n4. **Pages that load pay.js** from `AMBASADA_API_URL` should use the village client's `apiUrl` (or\n   `AMBASADA_VILLAGE_API_URL`): `AMBASADA_API_URL` is the platform's from 0.8.\n5. **Login.** The CLI's login moved from `~/.config/village` to `~/.config/ambasada` (moved on first use);\n   nothing to do unless a script reads that file.\n6. Run `npx ambasada check`, `npx ambasada dev` and the typecheck; deploy when they pass.\n", "README.md": "# My App\n\nAn app on Ambasada, Vite + React on one Cloudflare Worker (template `spa`): sign-in with Ambasada ID, a database,\nkey-value, files and live rooms; a mini app inside the Ambasada app if you want one. Everything here is a default;\nchange anything.\n\n```\nambasada.config.ts          id, name, one-line description, where the app runs\nsrc/                        the React app (drop a Lovable/Bolt export here); src/App.tsx has the header and the notes example\nworker/index.ts             the Worker: /api/<name> \u2192 api/<name>.ts, everything else is the app\napi/auth.ts                 Sign in with Ambasada (login, callback, logout, me, shell)\napi/ambasada-webhook.ts     the Ambasada app's events (notifications on/off); lib/notifications.ts sends pushes\napi/notes.ts, api/files.ts  env.DB + env.KV, uploads to env.FILES\nlib/ambasada.ts             the SDK client from the Worker's env\nlib/db.ts, kv.ts, files.ts  env.DB, env.KV, env.FILES; db/migrations/ the tables\nsrc/realtime/               the live room (a Durable Object) and its React hook\nvite.config.ts, wrangler.jsonc   @cloudflare/vite-plugin: `vite` runs the app and the Worker together\n.claude/skills/             docs your coding agent reads (ambasada-product)\n```\n\n## 1. Run it (2 min)\n\nNeeds Node \u2265 22.\n\n```sh\nnpm install\nnpm run dev                # `ambasada dev`: the mock Ambasada API on :8788 + `vite` on http://localhost:3000\n```\n\nOpen http://localhost:3000: add a note, sign in (the mock signs you in as \"Fake Visitor\"), open /room in two tabs.\nhttp://127.0.0.1:8788 is the mock's page (sign-ins, notifications, the store). `ambasada dev` points your app at the\nmock whatever `.env` says.\n\n## 2. Make it yours\n\n- `ambasada.config.ts`: name and description.\n- A new endpoint: `api/<name>.ts` (and a line in `worker/index.ts`). Data goes in `env.DB` (a migration in `db/migrations/`), `env.KV` or `env.FILES`.\n- Ask your coding agent: it has the ambasada-product skill (stack, storage, sign-in, mini app, deploy).\n\n## 3. Go live (1 min)\n\n```sh\nnpx ambasada login         # Ambasada ID, or a project key from https://developer.ambasada.dev\nnpx ambasada deploy        # build, smoke test, host at https://my-app.ambasada.dev\nnpx ambasada db migrate    # db/migrations \u2192 the app's database\nnpx ambasada logs          # the last deploy and recent errors\n```\n\nSign-in, notifications and the storage are set up by the deploy; nothing to configure. Your own secrets:\n`npx ambasada env set NAME value`. Hosting elsewhere: `npx vite build && npx wrangler deploy`, then `npx ambasada link https://\u2026`.\n\n**Sign in with Ambasada**: the header's button signs people in with their Ambasada ID; on the server,\n`ambasada(\u2026).auth.user(req)` gives `{ id, name, avatar_url, builder, pass }` or null.\n\n## Storage and realtime\n\nEvery app gets these, provisioned at the first `ambasada deploy`; locally wrangler keeps them in `.wrangler/state`.\n\n| Binding | For | Here |\n|---|---|---|\n| `env.DB` | SQLite: anything relational | `lib/db.ts`, tables in `db/migrations/`, example `api/notes.ts` |\n| `env.KV` | sessions, caches, flags | `lib/kv.ts` (the notes cache) |\n| `env.FILES` | uploads, generated files; public at `/files/<key>` | `lib/files.ts`, upload `api/files.ts` |\n| `env.ROOMS` | live state shared between people (Durable Object) | `src/realtime/room.ts`, hook `src/realtime/use-room.ts`, demo at `/room` |\n\n```sh\nnpx wrangler d1 migrations apply DB --local   # db/migrations \u2192 the local database (ambasada dev)\nnpx ambasada db migrate                       # \u2026 \u2192 the app's database online\nnpx ambasada db shell \"SELECT * FROM notes\"   # or `ambasada db shell` for a prompt\nnpx ambasada kv list | get <key> | put <key> <value> | delete <key>\nnpx ambasada files put <file> | list | url <key> | delete <key>\n```\n\nOptional: an agent with the Agents SDK in `examples/agent/` (its README: `npm i agents` and four lines to wire it).\n\n## In the Ambasada app (optional)\n\nOff by default: this is a website. `npx ambasada miniapp enable` adds a mini app at `/app` (`--entry /` for the whole\nsite): `miniapp: { entry: \"/app\" }` in `ambasada.config.ts`, src/in-app/ (the in-app page, rendered by src/main.tsx under the entry), a placeholder\n`public/icon.png`, and the manifest `ambasada dev` and `deploy` serve at `/.well-known/ambasada.json`. Then\n`http://localhost:3000/app?ambasada_shell=mock` pretends to be inside the Ambasada app. The ambasada-product skill:\nreference/mini-app.md.\n\n## Rules worth knowing\n\n- State lives in `env.DB`, `env.KV`, `env.FILES` or a Durable Object, never in module variables: a Worker has many instances.\n- Secrets only in `.env` locally and `ambasada env set` online; never in the code or `wrangler.jsonc` vars.\n- `npx ambasada check` runs the checks (https, no redirects, speed; the mini-app rules when it is on); `npx ambasada upgrade` after a new devkit.\n\nFor the Hack A Ton: `npx ambasada add village` (the add-on).\n\nBuilt by [CENTYSO](https://centyso.com) for [Ambasada](https://ambasada.id).\n", "ambasada.config.ts": 'import { defineApp } from "@ambasada/sdk";\n\nexport default defineApp({\n  id: "my-app",\n  name: "My App",\n  // One line about the app (the subtitle of its Ambasada mini app, if you add one: `ambasada miniapp enable`).\n  description: "Notes, a live room and sign-in",\n  // Where the app runs. `ambasada dev` serves it on http://localhost:3000; hosted, it is https://my-app.ambasada.dev\n  // (`ambasada deploy` sets it; `ambasada link https://\u2026` when you host elsewhere).\n  product: { url: "http://localhost:3000" },\n});\n', "api/ambasada-webhook.ts": '// POST /api/ambasada/webhook: the Ambasada app\'s events for this mini app (docs/MINI-APPS.md \xA77), signed with\n// AMBASADA_APP_SECRET (injected on ambasada.dev; `ambasada dev` plays the hub and sends a ping and\n// notifications_enabled here when it starts). The manifest points here: notifications.webhook.\nimport { isAmbasadaError } from "@ambasada/sdk";\nimport { ambasada, type Env } from "../lib/ambasada.ts";\nimport { forgetToken, saveToken } from "../lib/notifications.ts";\n\nexport default async function appWebhook(req: Request, env: Env): Promise<Response> {\n  const app = ambasada(env);\n  try {\n    const event = await app.apps.verifyWebhook(req); // throws if forged or stale\n    switch (event.event) {\n      case "notifications_enabled":\n      case "app_added":\n        if (event.token) await saveToken(app, event.user, event.token);\n        break;\n      case "notifications_disabled":\n      case "app_removed":\n        await forgetToken(app, event.user);\n        break;\n      case "ping": // `ambasada check` and the registry: answer 200\n        break;\n    }\n    return new Response("ok");\n  } catch (error) {\n    if (isAmbasadaError(error)) return error.toResponse();\n    throw error;\n  }\n}\n', "api/auth.ts": '// Sign in with Ambasada (Ambasada ID, OAuth + PKCE): zero setup. On https://<slug>.ambasada.dev the deploy\n// injects AMBASADA_AUTH_*; under `ambasada dev` the mock signs you in as a fake visitor.\n//   GET /api/auth/login?returnTo=/   \u2192 the Ambasada ID consent screen\n//   GET /api/auth/callback           \u2192 back from it: sets an HttpOnly session cookie, redirects to returnTo\n//   GET /api/auth/logout             \u2192 clears it\n//   GET /api/auth/me                 \u2192 { user } (null when signed out), for the browser\n//   POST /api/auth/shell { token }   \u2192 silent sign-in inside the Ambasada app: the same session, no consent screen\n//                                      (the page calls `auth.signIn()` from @ambasada/miniapp)\n// On the server: `await ambasada(env).auth.user(req)` \u2192 { id, name, avatar_url, builder, pass, \u2026 } or null.\nimport { isAmbasadaError } from "@ambasada/sdk";\nimport { ambasada, type Env } from "../lib/ambasada.ts";\n\nexport default async function auth(req: Request, env: Env): Promise<Response> {\n  const { auth } = ambasada(env);\n  try {\n    switch (new URL(req.url).pathname.replace(/\\/+$/, "")) {\n      case "/api/auth/login":\n        return await auth.login(req);\n      case "/api/auth/callback":\n        return await auth.callback(req);\n      case "/api/auth/logout":\n        return auth.logout(req);\n      case "/api/auth/shell":\n        return await auth.shell(req);\n      case "/api/auth/me": {\n        // Under `ambasada dev` the page needs the mock issuer for its fake shell (?ambasada_shell=mock).\n        const devIssuer = env.AMBASADA_AUTH_ISSUER?.startsWith("http://") ? env.AMBASADA_AUTH_ISSUER : undefined;\n        return Response.json({ user: await auth.user(req), configured: auth.configured, ...(devIssuer ? { dev_issuer: devIssuer } : {}) }, { headers: { "cache-control": "no-store" } });\n      }\n    }\n    return Response.json({ error: { code: "NOT_FOUND", message: "no such route" } }, { status: 404 });\n  } catch (error) {\n    if (isAmbasadaError(error)) return error.toResponse();\n    throw error;\n  }\n}\n', "api/files.ts": '// POST /api/files (raw body, content-type): a signed-in person uploads a file to env.FILES (lib/files.ts)\n// \u2192 { key, url }; the url (/files/<key>) is public and served by the /files/* route.\nimport { ambasada, type Env } from "../lib/ambasada.ts";\nimport { upload } from "../lib/files.ts";\n\nconst MAX_BYTES = 10 * 1024 * 1024;\n\nexport default async function files(req: Request, env: Env): Promise<Response> {\n  if (req.method !== "POST") return Response.json({ error: { code: "INVALID_REQUEST", message: "POST the file" } }, { status: 405 });\n  const user = await ambasada(env).auth.user(req);\n  if (!user) return Response.json({ error: { code: "UNAUTHORIZED", message: "sign in to upload" } }, { status: 401 });\n  const size = Number(req.headers.get("content-length") ?? 0);\n  if (!size || size > MAX_BYTES) return Response.json({ error: { code: "INVALID_REQUEST", message: "send a file up to 10 MB with a content-length" } }, { status: 413 });\n  const stored = await upload(env.FILES, req.body, { contentType: req.headers.get("content-type") ?? undefined, folder: `u/${user.id}` });\n  return Response.json(stored, { status: 201 });\n}\n', "api/notes.ts": '// GET /api/notes: the latest notes from env.DB (lib/db.ts), cached a minute in env.KV (lib/kv.ts).\n// POST /api/notes { text }: adds one. The table is db/migrations/0001_init.sql.\nimport type { Env } from "../lib/ambasada.ts";\nimport { all, run } from "../lib/db.ts";\nimport { cached, remove } from "../lib/kv.ts";\n\ntype Note = { id: number; text: string; created_at: number };\n\nexport default async function notes(req: Request, env: Env): Promise<Response> {\n  if (req.method === "POST") {\n    const { text } = (await req.json().catch(() => ({}))) as { text?: unknown };\n    if (typeof text !== "string" || !text.trim() || text.length > 500) {\n      return Response.json({ error: { code: "INVALID_REQUEST", message: "body must be { text }, 1 to 500 characters" } }, { status: 400 });\n    }\n    const { lastRowId } = await run(env.DB, "INSERT INTO notes (text, created_at) VALUES (?, ?)", text.trim(), Date.now());\n    await remove(env.KV, "notes:latest");\n    return Response.json({ id: lastRowId }, { status: 201 });\n  }\n  const latest = await cached(env.KV, "notes:latest", 60, () => all<Note>(env.DB, "SELECT id, text, created_at FROM notes ORDER BY id DESC LIMIT 20"));\n  return Response.json({ notes: latest });\n}\n', "db/migrations/0001_init.sql": "-- The app's first table. Add the next change as db/migrations/0002_<what>.sql (never edit an applied file), then:\n--   npx wrangler d1 migrations apply DB --local   (ambasada dev)\n--   npx ambasada db migrate                       (online)\nCREATE TABLE notes (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  text TEXT NOT NULL,\n  created_at INTEGER NOT NULL\n);\nCREATE INDEX notes_created ON notes (created_at);\n", "examples/agent/README.md": '# Agent (optional): the Cloudflare Agents SDK\n\nFor agentic products: an agent per user, document or task, with live state, its own SQL, schedules and\nWebSockets (`agent.ts`). It is a Durable Object, so it runs on ambasada.dev like the live rooms. To turn it on:\n\n1. `npm i agents`\n2. `wrangler.jsonc`: add the binding and a migration after the existing ones:\n   ```jsonc\n   "durable_objects": { "bindings": [{ "name": "ROOMS", "class_name": "Room" }, { "name": "AgentExample", "class_name": "AgentExample" }] },\n   "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Room"] }, { "tag": "v2", "new_sqlite_classes": ["AgentExample"] }]\n   ```\n3. In the Worker entry (`src/worker.ts`; spa: `worker/index.ts`; next: `worker.ts`):\n   ```ts\n   export { AgentExample } from "../examples/agent/agent.ts"; // next: "./examples/agent/agent.ts"\n   import { routeAgents } from "../examples/agent/agent.ts";\n   // first thing in fetch():\n   const agent = await routeAgents(req, env as unknown as Record<string, unknown>);\n   if (agent) return agent;\n   ```\n4. In the browser (React): `useAgent({ agent: "agent-example", name: user.id, onStateUpdate: setState })` from\n   `agents/react`; `agent.send("hello")`. Plain fetch: `GET /agents/agent-example/<name>`.\n\n`ambasada deploy` sends the new class and its migration; nothing else to set up. Docs: https://developers.cloudflare.com/agents/\n', "examples/agent/agent.ts": '/**\n * Optional: an agent with the Cloudflare Agents SDK (`agents`), for agentic products. An agent is a Durable\n * Object with superpowers: state synced live to every connected client (`setState`), its own SQL (`this.sql`),\n * scheduled work (`this.schedule`), WebSockets and HTTP. One instance per name: per user, per document, per task.\n * Not wired in by default: examples/agent/README.md has the four steps.\n */\nimport { Agent, routeAgentRequest, type Connection, type WSMessage } from "agents";\n\ntype State = { notes: number; lastNote: string | null };\n\nexport class AgentExample extends Agent<Cloudflare.Env, State> {\n  initialState: State = { notes: 0, lastNote: null };\n\n  async onStart() {\n    this.sql`CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY AUTOINCREMENT, text TEXT NOT NULL, at INTEGER NOT NULL)`;\n  }\n\n  // GET /agents/agent-example/<name>: what this agent knows.\n  async onRequest(_req: Request): Promise<Response> {\n    const notes = this.sql<{ id: number; text: string; at: number }>`SELECT id, text, at FROM notes ORDER BY id DESC LIMIT 20`;\n    return Response.json({ state: this.state, notes });\n  }\n\n  // A client (useAgent in the browser) sent a message: remember it, sync the new state to every client,\n  // and come back to it in a minute (call an LLM here, send a notification, \u2026).\n  async onMessage(connection: Connection, message: WSMessage) {\n    const text = String(message).slice(0, 2000);\n    this.sql`INSERT INTO notes (text, at) VALUES (${text}, ${Date.now()})`;\n    this.setState({ notes: this.state.notes + 1, lastNote: text });\n    await this.schedule(60, "followUp", { text });\n    connection.send(JSON.stringify({ ok: true }));\n  }\n\n  async followUp(payload: { text: string }) {\n    console.log(`a minute ago someone wrote: ${payload.text}`);\n  }\n}\n\n/** In your Worker\'s fetch, before your own routes: answers /agents/<agent>/<name> (HTTP and WebSocket). */\nexport const routeAgents = (req: Request, env: Record<string, unknown>) => routeAgentRequest(req, env);\n', gitignore: "node_modules/\ndist/\n.wrangler/\n*.tsbuildinfo\n.env*\n.dev.vars*\n.DS_Store\n# build output of `ambasada deploy`; project.json (template, devkit version) is kept\n.ambasada/*\n!.ambasada/project.json\n", "index.html": '<!doctype html>\n<html lang="en">\n  <head>\n    <meta charset="utf-8" />\n    <meta name="viewport" content="width=device-width, initial-scale=1" />\n    <title>My App</title>\n  </head>\n  <body>\n    <div id="root"></div>\n    <script type="module" src="/src/main.tsx"></script>\n  </body>\n</html>\n', "lib/ambasada.ts": "import { createAmbasada, type Ambasada } from \"@ambasada/sdk\";\nimport type { Room } from \"../src/realtime/room.ts\";\n\n/** The Worker's env: `.env` locally (`ambasada dev` points it at the mock), secrets injected at deploy. */\nexport interface Env {\n  ASSETS: Fetcher;\n  /** The app's SQLite database (lib/db.ts), key-value (lib/kv.ts), files (lib/files.ts) and live rooms (src/realtime/room.ts). */\n  DB: D1Database;\n  KV: KVNamespace;\n  FILES: R2Bucket;\n  ROOMS: DurableObjectNamespace<Room>;\n  /** On ambasada.dev: a service binding to the API, which the SDK uses for its calls (set by `ambasada deploy`). */\n  AMBASADA_API?: Fetcher;\n  AMBASADA_API_KEY?: string;\n  /** Set by `ambasada deploy` and `ambasada dev`; the SDK defaults to https://api.ambasada.dev. */\n  AMBASADA_API_URL?: string;\n  AMBASADA_APP_ID?: string;\n  /** Sign in with Ambasada (api/auth.ts): set by `ambasada deploy` on ambasada.dev, and by `ambasada dev`. */\n  AMBASADA_AUTH_CLIENT_ID?: string;\n  AMBASADA_AUTH_CLIENT_SECRET?: string;\n  AMBASADA_AUTH_ISSUER?: string;\n  /** Mini-app notifications (api/ambasada-webhook.ts, lib/notifications.ts): set on ambasada.dev and by `ambasada dev`. */\n  AMBASADA_APP_SECRET?: string;\n  AMBASADA_HUB_URL?: string;\n  /** This app's origin, set by `ambasada deploy` and `ambasada dev`: use `appOrigin(env, req)`. */\n  AMBASADA_APP_ORIGIN?: string;\n}\n\n/**\n * This app's own origin (https://<slug>.ambasada.dev online, the dev server locally): AMBASADA_APP_ORIGIN, which\n * `ambasada deploy` and `ambasada dev` set, else the request's (a call the platform forwards may carry another host).\n */\nexport function appOrigin(env: Env, req: Request): string {\n  return env.AMBASADA_APP_ORIGIN ?? new URL(req.url).origin;\n}\n\nlet client: Ambasada | undefined;\n\n/** One client per isolate: it caches the API's signing keys. */\nexport function ambasada(env: Env): Ambasada {\n  return (client ??= createAmbasada({ env: env as unknown as Record<string, unknown> }));\n}\n", "lib/db.ts": '/**\n * env.DB: this app\'s SQLite database (Cloudflare D1). The tables come from db/migrations/*.sql:\n * `npx ambasada db migrate` online, `npx wrangler d1 migrations apply DB --local` for `ambasada dev`.\n * A tiny typed layer, no ORM: SQL with ? placeholders in, plain objects out.\n *\n *   const notes = await all<Note>(env.DB, "SELECT * FROM notes ORDER BY id DESC LIMIT ?", 20);\n *   const note = await first<Note>(env.DB, "SELECT * FROM notes WHERE id = ?", id);\n *   const { lastRowId } = await run(env.DB, "INSERT INTO notes (text) VALUES (?)", text);\n *   await batch(env.DB, [["UPDATE a SET n = n - 1 WHERE id = ?", 1], ["UPDATE b SET n = n + 1 WHERE id = ?", 2]]); // one transaction\n */\n\nexport type Param = string | number | boolean | null | ArrayBuffer;\n\n/** What this file needs from a D1 binding (env.DB satisfies it). */\nexport interface Database {\n  prepare(query: string): Statement;\n  batch(statements: Statement[]): Promise<unknown[]>;\n}\n\nexport interface Statement {\n  bind(...values: unknown[]): Statement;\n  all<T = Record<string, unknown>>(): Promise<{ results: T[] }>;\n  first<T = Record<string, unknown>>(): Promise<T | null>;\n  run(): Promise<{ meta: { changes: number; last_row_id: number } }>;\n}\n\nconst statement = (db: Database, query: string, params: Param[]) => db.prepare(query).bind(...params);\n\n/** Every row. */\nexport async function all<T = Record<string, unknown>>(db: Database, query: string, ...params: Param[]): Promise<T[]> {\n  return (await statement(db, query, params).all<T>()).results;\n}\n\n/** The first row, or null. */\nexport function first<T = Record<string, unknown>>(db: Database, query: string, ...params: Param[]): Promise<T | null> {\n  return statement(db, query, params).first<T>();\n}\n\n/** INSERT, UPDATE, DELETE: how many rows changed and the last inserted id. */\nexport async function run(db: Database, query: string, ...params: Param[]): Promise<{ changes: number; lastRowId: number }> {\n  const { meta } = await statement(db, query, params).run();\n  return { changes: meta.changes, lastRowId: meta.last_row_id };\n}\n\n/** Several statements in one transaction: all of them apply, or none. */\nexport async function batch(db: Database, statements: [query: string, ...params: Param[]][]): Promise<void> {\n  await db.batch(statements.map(([query, ...params]) => statement(db, query, params)));\n}\n', "lib/files.ts": '/**\n * env.FILES: this app\'s file storage (Cloudflare R2). Uploads and generated files; each one is public at\n * /files/<key> on the app\'s own address (the /files/* route calls serveFile). Don\'t keep files in the database.\n *\n *   const { key, url } = await upload(env.FILES, req.body, { contentType: "image/png" });   // url: /files/u/\u2026\n *   return serveFile(env.FILES, req);                                                        // GET /files/*\n *\n * Files are public to anyone with the URL: keep private documents behind your own route that checks who asks.\n * `npx ambasada files put|list|delete|url` manages them from the terminal.\n */\n\n/** What this file needs from an R2 binding (env.FILES satisfies it). */\nexport interface Bucket {\n  put(key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null, options?: { httpMetadata?: { contentType?: string } }): Promise<unknown>;\n  get(key: string, options?: { onlyIf?: Headers; range?: Headers }): Promise<StoredFile | null>;\n  delete(key: string): Promise<void>;\n}\n\nexport interface StoredFile {\n  httpEtag: string;\n  size: number;\n  httpMetadata?: { contentType?: string };\n  range?: { offset?: number; length?: number; suffix?: number };\n  body?: ReadableStream;\n}\n\nexport const FILES_PATH = "/files/";\n\n/** Stores `body` under a new random key (in `folder`) \u2192 `{ key, url }`, url relative to the app (/files/<key>). */\nexport async function upload(bucket: Bucket, body: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null, options: { contentType?: string; folder?: string } = {}): Promise<{ key: string; url: string }> {\n  const key = `${options.folder ?? "u"}/${crypto.randomUUID()}`;\n  await bucket.put(key, body, { httpMetadata: { contentType: options.contentType ?? "application/octet-stream" } });\n  return { key, url: fileUrl(key) };\n}\n\nexport const fileUrl = (key: string) => `${FILES_PATH}${key.split("/").map(encodeURIComponent).join("/")}`;\n\n/** GET/HEAD /files/<key>: the file with its type, an ETag (304 when unchanged), byte ranges, and a cache header. */\nexport async function serveFile(bucket: Bucket, req: Request): Promise<Response> {\n  if (req.method !== "GET" && req.method !== "HEAD") return new Response(null, { status: 405, headers: { allow: "GET, HEAD" } });\n  const path = new URL(req.url).pathname;\n  const key = decodeURIComponent(path.slice(path.indexOf(FILES_PATH) + FILES_PATH.length));\n  if (!key) return new Response("Not found", { status: 404 });\n  const file = await bucket.get(key, { onlyIf: req.headers, range: req.headers });\n  if (!file) return new Response("Not found", { status: 404 });\n  const headers = new Headers({ etag: file.httpEtag, "cache-control": "public, max-age=3600", "accept-ranges": "bytes" });\n  if (file.httpMetadata?.contentType) headers.set("content-type", file.httpMetadata.contentType);\n  if (!file.body) return new Response(null, { status: 304, headers }); // If-None-Match matched: nothing changed\n  const r = file.range;\n  if (r && req.headers.has("range")) {\n    const offset = r.suffix !== undefined ? file.size - r.suffix : (r.offset ?? 0);\n    const length = r.suffix ?? r.length ?? file.size - offset;\n    headers.set("content-range", `bytes ${offset}-${offset + length - 1}/${file.size}`);\n    headers.set("content-length", String(length));\n    return new Response(req.method === "HEAD" ? null : file.body, { status: 206, headers });\n  }\n  headers.set("content-length", String(file.size));\n  return new Response(req.method === "HEAD" ? null : file.body, { headers });\n}\n', "lib/kv.ts": '/**\n * env.KV: this app\'s key-value store (Cloudflare KV). Fast reads everywhere, writes visible within about a\n * minute, at most one write per second per key. Good for sessions, caches and feature flags; not for counters\n * or anything two people change at once (use env.DB, or a Durable Object for live state).\n *\n *   await putJson(env.KV, `session:${id}`, { user }, { ttl: 60 * 60 * 24 });\n *   const session = await getJson<{ user: string }>(env.KV, `session:${id}`);\n *   const page = await cached(env.KV, "home:stats", 60, () => computeStats());\n */\n\n/** What this file needs from a KV binding (env.KV satisfies it). */\nexport interface KeyValue {\n  get(key: string, type: "text"): Promise<string | null>;\n  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;\n  delete(key: string): Promise<void>;\n}\n\n/** The value saved under `key`, parsed; null when there is none (or it expired). */\nexport async function getJson<T>(kv: KeyValue, key: string): Promise<T | null> {\n  const text = await kv.get(key, "text");\n  return text === null ? null : (JSON.parse(text) as T);\n}\n\n/** Saves `value` as JSON. `ttl`: seconds until it disappears (at least 60). */\nexport function putJson(kv: KeyValue, key: string, value: unknown, options: { ttl?: number } = {}): Promise<void> {\n  return kv.put(key, JSON.stringify(value), options.ttl ? { expirationTtl: Math.max(60, options.ttl) } : undefined);\n}\n\nexport function remove(kv: KeyValue, key: string): Promise<void> {\n  return kv.delete(key);\n}\n\n/** `load()`\'s result, kept for `ttl` seconds: a cache in front of something slow. */\nexport async function cached<T>(kv: KeyValue, key: string, ttl: number, load: () => Promise<T>): Promise<T> {\n  const hit = await getJson<T>(kv, key);\n  if (hit !== null) return hit;\n  const value = await load();\n  await putJson(kv, key, value, { ttl });\n  return value;\n}\n', "lib/notifications.ts": '// Who turned notifications on, and how to reach them (docs/MINI-APPS.md \xA77). The hub sends a token per person\n// to the webhook route (api/ambasada-webhook.ts; app/api/ambasada/webhook/route.ts in Next); it lives in your\n// ambasada.store under the person\'s Ambasada user id.\nimport type { Ambasada, AppNotifyInput } from "@ambasada/sdk";\n\nconst key = (user: string) => `ambasada/notifications/${user}`;\n\nexport const saveToken = (app: Ambasada, user: string, token: string) => app.store.set(key(user), { token, enabled_at: new Date().toISOString() });\nexport const forgetToken = (app: Ambasada, user: string) => app.store.delete(key(user));\n\n/**\n * A push to one person (their Ambasada user id, e.g. `(await app.auth.user(req)).id`), if they turned\n * notifications on. False when they haven\'t, or the hub said the token is gone (then it is forgotten).\n *   await notifyUser(app, user.id, { notification_id: `order-${id}`, title: "Your translation is ready", body: "\u2026", url: `/orders/${id}` });\n */\nexport async function notifyUser(app: Ambasada, user: string, notification: Omit<AppNotifyInput, "tokens" | "users">): Promise<boolean> {\n  const saved = await app.store.get<{ token: string }>(key(user));\n  if (!saved) return false;\n  const result = await app.apps.notify({ ...notification, tokens: [saved.token] });\n  if (result.invalid.includes(saved.token)) await forgetToken(app, user);\n  return result.sent.includes(saved.token);\n}\n', "package.json": '{\n  "name": "@ambasada/template-spa",\n  "version": "0.1.0",\n  "private": true,\n  "description": "An Ambasada app: Vite + React (Lovable/Bolt exports) and api/*.ts handlers as one Cloudflare Worker.",\n  "type": "module",\n  "engines": {\n    "node": ">=22"\n  },\n  "scripts": {\n    "dev": "ambasada dev",\n    "build": "vite build",\n    "preview": "vite build && vite preview --port 3000",\n    "typecheck": "tsc -b",\n    "ambasada": "ambasada"\n  },\n  "dependencies": {\n    "@ambasada/sdk": "workspace:*",\n    "@ambasada/ui": "workspace:*",\n    "react": "~19.3.1",\n    "react-dom": "~19.3.1"\n  },\n  "devDependencies": {\n    "@ambasada/cli": "workspace:*",\n    "@cloudflare/vite-plugin": "^1.67.0",\n    "@cloudflare/workers-types": "^5.20261102.1",\n    "@types/node": "^22.20.5",\n    "@types/react": "^19.3.0",\n    "@types/react-dom": "^19.3.0",\n    "@vitejs/plugin-react": "^6.1.2",\n    "typescript": "~5.9.3",\n    "vite": "^8.3.5",\n    "wrangler": "^4.156.1"\n  },\n  "allowScripts": {\n    "esbuild": true,\n    "fsevents": true,\n    "workerd": true\n  }\n}\n', "public/privacy.html": `<!doctype html>
 <!-- /privacy: the manifest's privacy_url. Apps that ask for scopes (identity, notifications) need one to be Listed
      (docs/MINI-APPS.md \xA72). Say plainly what you keep; edit it when that changes. -->
 <html lang="en">
@@ -191,14 +188,11 @@ body { margin: 0; }
 .eyebrow::before { content: "// "; }
 h1 { margin: var(--space-2) 0 var(--space-3); font-size: clamp(2.2rem, 7vw, 3.4rem); font-weight: var(--weight-semibold); line-height: 1.05; letter-spacing: -0.03em; }
 .lead { margin: 0 0 var(--space-8); font-size: 1.125rem; color: var(--color-ink-2); }
-.checkout { display: grid; gap: var(--space-4); }
 textarea, select { font: inherit; font-size: var(--text-base); color: inherit; padding: 10px 12px; border: 1px solid var(--color-line); border-radius: var(--radius-sm); background: var(--color-surface); }
 textarea:focus, select:focus { outline: none; border-color: var(--color-accent); box-shadow: 0 0 0 3px var(--color-accent-soft); }
 textarea { resize: vertical; min-height: 7rem; }
 .row { display: flex; flex-wrap: wrap; gap: var(--space-3); align-items: center; justify-content: space-between; }
 label { display: flex; gap: var(--space-2); align-items: center; color: var(--color-ink-2); }
-.pay::before { content: "\u25C6 "; opacity: 0.8; }
-.tip { margin-top: var(--space-10); padding-top: var(--space-6); border-top: 1px solid var(--color-line); }
 .small, footer { color: var(--color-ink-3); font-size: var(--text-sm); }
 footer { margin-top: calc(var(--space-10) + var(--space-2)); }
 code { font-family: var(--font-mono); font-size: 0.9em; background: var(--color-surface-2); padding: 0.1em 0.35em; border-radius: var(--radius-xs); }
@@ -210,7 +204,7 @@ a { color: var(--color-accent-text); }
 .account img { width: 28px; height: 28px; border-radius: 50%; object-fit: cover; background: var(--color-line); }
 .account a { font-weight: var(--weight-regular); font-size: var(--text-sm); color: var(--color-ink-2); }
 [hidden] { display: none !important; }
-`, "tsconfig.app.json": '{\n  "compilerOptions": {\n    "composite": true,\n    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",\n    "target": "ES2022",\n    "lib": ["ES2022", "DOM", "DOM.Iterable"],\n    "module": "ESNext",\n    "moduleResolution": "Bundler",\n    "jsx": "react-jsx",\n    "strict": true,\n    "noEmit": true,\n    "skipLibCheck": true,\n    "isolatedModules": true,\n    "verbatimModuleSyntax": true,\n    "allowImportingTsExtensions": true\n  },\n  "include": ["src"],\n  "exclude": ["src/realtime/room.ts"]\n}\n', "tsconfig.json": '{\n  "files": [],\n  "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.worker.json" }, { "path": "./tsconfig.node.json" }]\n}\n', "tsconfig.node.json": '{\n  "compilerOptions": {\n    "composite": true,\n    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",\n    "target": "ES2022",\n    "lib": ["ES2023"],\n    "types": ["node"],\n    "module": "ESNext",\n    "moduleResolution": "Bundler",\n    "strict": true,\n    "noEmit": true,\n    "skipLibCheck": true,\n    "isolatedModules": true,\n    "verbatimModuleSyntax": true\n  },\n  "include": ["vite.config.ts"]\n}\n', "tsconfig.worker.json": '{\n  "compilerOptions": {\n    "composite": true,\n    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.worker.tsbuildinfo",\n    "target": "ES2022",\n    "lib": ["ES2022"],\n    "types": ["@cloudflare/workers-types"],\n    "module": "ESNext",\n    "moduleResolution": "Bundler",\n    "strict": true,\n    "noEmit": true,\n    "skipLibCheck": true,\n    "isolatedModules": true,\n    "verbatimModuleSyntax": true,\n    "allowImportingTsExtensions": true\n  },\n  "include": ["worker", "api", "lib", "src/realtime/room.ts", "ambasada.config.ts"]\n}\n', "vite.config.ts": 'import { cloudflare } from "@cloudflare/vite-plugin";\nimport react from "@vitejs/plugin-react";\nimport { defineConfig } from "vite";\n\nexport default defineConfig({\n  plugins: [react(), cloudflare()],\n  // allowedHosts: `ambasada dev --tunnel` serves this at https://<slug>-dev.ambasada.dev.\n  server: { port: 3000, allowedHosts: [".ambasada.dev"] },\n});\n', "worker/index.ts": '/**\n * The app\'s Worker (`vite` runs it locally through @cloudflare/vite-plugin):\n *\n *   /api/<name>  \u2192 api/<name>.ts (fetch handlers; add yours to API below)\n *   /api/auth/*  \u2192 api/auth.ts: Sign in with Ambasada (login, callback, logout, me, shell)\n *   /api/ambasada/webhook \u2192 api/ambasada-webhook.ts: the Ambasada app\'s events (notifications on/off, ping)\n *   /api/notes, /api/files \u2192 api/notes.ts (env.DB + env.KV), api/files.ts (uploads to env.FILES)\n *   /api/rooms/<id>/ws \u2192 the live room <id> (src/realtime/room.ts, a Durable Object); demo at /room\n *   /files/*     \u2192 files from env.FILES (lib/files.ts)\n *   /health      \u2192 { ok: true }\n *   the rest     \u2192 the React app in src/ (static assets; unknown paths get index.html, see wrangler.jsonc)\n */\nimport appWebhook from "../api/ambasada-webhook.ts";\nimport auth from "../api/auth.ts";\nimport files from "../api/files.ts";\nimport notes from "../api/notes.ts";\nimport type { Env } from "../lib/ambasada.ts";\nimport { FILES_PATH, serveFile } from "../lib/files.ts";\n\nexport { Room } from "../src/realtime/room.ts";\n\ntype Handler = (req: Request, env: Env) => Promise<Response>;\nconst API: Record<string, Handler> = { files, notes };\n\nexport default {\n  async fetch(req, env) {\n    const { pathname } = new URL(req.url);\n    try {\n      if (pathname === "/health") return Response.json({ ok: true });\n      if (pathname.startsWith("/api/auth/")) return await auth(req, env);\n      if (pathname === "/api/ambasada/webhook") return await appWebhook(req, env);\n      const room = /^\\/api\\/rooms\\/([^/]+)\\/ws$/.exec(pathname);\n      if (room) return await env.ROOMS.getByName(decodeURIComponent(room[1]!)).fetch(req);\n      if (pathname.startsWith(FILES_PATH)) return await serveFile(env.FILES, req);\n      const api = /^\\/api\\/([^/]+)\\/?$/.exec(pathname);\n      const handler = api ? API[api[1]!] : undefined;\n      if (handler) return await handler(req, env);\n      if (api) return Response.json({ error: { code: "NOT_FOUND", message: "no such route" } }, { status: 404 });\n      return env.ASSETS.fetch(req);\n    } catch (error) {\n      console.error(error);\n      return Response.json({ error: { code: "INTERNAL", message: "internal error" } }, { status: 500 });\n    }\n  },\n} satisfies ExportedHandler<Env>;\n', "wrangler.jsonc": '{\n  "$schema": "node_modules/wrangler/config-schema.json",\n  // One Worker: worker/index.ts answers /api/*, /files/* and /health; the React app (vite build) is served as assets.\n  "name": "my-app",\n  "main": "worker/index.ts",\n  "compatibility_date": "2026-09-01",\n  "compatibility_flags": ["nodejs_compat"],\n  "assets": {\n    "binding": "ASSETS",\n    "not_found_handling": "single-page-application",\n    "run_worker_first": ["/api/*", "/files/*", "/health"]\n  },\n  // Storage and realtime: env.DB (SQLite), env.KV, env.FILES and the live rooms (src/realtime/room.ts).\n  // No ids: wrangler keeps local copies in .wrangler/state; `ambasada deploy` attaches the app\'s real ones.\n  "d1_databases": [{ "binding": "DB", "database_name": "my-app", "migrations_dir": "db/migrations", "migrations_table": "_ambasada_migrations" }],\n  "kv_namespaces": [{ "binding": "KV" }],\n  "r2_buckets": [{ "binding": "FILES", "bucket_name": "my-app" }],\n  "durable_objects": { "bindings": [{ "name": "ROOMS", "class_name": "Room" }] },\n  // Every Durable Object class needs a migration; add new ones at the end, never edit or remove an applied tag.\n  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Room"] }],\n  "observability": { "enabled": true }\n}\n' }, worker: { ".claude/skills/ambasada-product/SKILL.md": "---\nname: ambasada-product\ndescription: Build an app on Ambasada and put it online. Use when the user wants to make an app, tool, game or website, start one with `npm create ambasada@latest`, run it with `ambasada dev`, publish it with `ambasada deploy` at <slug>.ambasada.dev, show it in the Ambasada app (mini app, notifications, sign-in), store data in the app's SQLite database, KV or file storage, make it realtime with Durable Objects or an agent (Agents SDK), bring a site built in ChatGPT, Lovable, Bolt or v0, or upgrade a project made with an older CLI (`ambasada upgrade`). Default stack: Next.js on Cloudflare.\n---\n\n# Build an app on Ambasada and put it online\n\nAn app is **one website** (one Cloudflare Worker) at `https://<your-slug>.ambasada.dev`. It comes with\nSign in with Ambasada (Ambasada ID), a SQLite database, key-value, file storage and Durable Objects for\nrealtime. If you want, it also gets a mini app inside the Ambasada app, with push notifications (off by default). No servers, no\nCloudflare account, no keys to configure.\n\n## Start\n\n```sh\nnpm create ambasada@latest my-app           # Next.js (default)\ncd my-app && npm install\nnpx ambasada dev                            # the mock API + your site, no login\n```\n\nOther templates: add `-- --template spa` (Vite + React; for code exported from Lovable or Bolt) or\n`-- --template worker` (plain HTML + small fetch handlers; the smallest possible app). All three have the\nsame `ambasada.config.ts`, sign-in routes, notifications webhook and storage helpers, and a notes example.\n\n## What to read\n\n| The user wants to\u2026 | Read |\n|---|---|\n| know where files go, what Next.js features are allowed, secrets, who is signed in | [reference/stack.md](reference/stack.md) |\n| store data (tables, migrations), sessions or caches, uploads; make it live between people (chat, presence, a shared board, counters); build an AI agent | [reference/storage.md](reference/storage.md) |\n| run it locally, put it online, use their own Cloudflare account | [reference/dev-and-deploy.md](reference/dev-and-deploy.md) |\n| make it look good and easy to use | [reference/design.md](reference/design.md) |\n| show up in the Ambasada app (optional: `npx ambasada miniapp enable`), send push notifications, sign people in inside the app | [reference/mini-app.md](reference/mini-app.md) |\n| build in ChatGPT, Lovable, Bolt or v0 and bring it here | [reference/build-elsewhere.md](reference/build-elsewhere.md) |\n| upgrade a project made with an older CLI | [reference/upgrading.md](reference/upgrading.md) |\n\nFor the Hack A Ton (TON payments, offerings, the agent that runs a shop): `npx ambasada add village`, then\nthe **ambasada-village** skill.\n\n## Rules (break one and the app does not work)\n\n1. **One app = one Worker.** No separate backend, no Docker. State lives in the app's SQLite (`env.DB`),\n   key-value (`env.KV`), file storage (`env.FILES`) or a Durable Object, never in module variables.\n   See [reference/storage.md](reference/storage.md).\n2. **Only the allowed Next.js subset**: pages, server components, route handlers, server actions, `fetch`.\n   No `next/image` default loader, no ISR/`revalidate`, no `fs`/`child_process`/native packages, no custom\n   server, no `middleware.ts`/`proxy.ts`, no `runtime = \"edge\"`. See [reference/stack.md](reference/stack.md#nextjs-allowed-and-banned).\n3. **Keys never reach the browser.** They live in `.env` locally and `ambasada env set` online; only server\n   code reads them. Never prefix one with `NEXT_PUBLIC_`.\n4. **Sign-in is Ambasada ID.** Use the template's `/api/auth/*` routes and `auth.user(req)`; don't add\n   Clerk, Auth.js or Supabase Auth, and don't build an accounts table. Key per-person data by `user.id`.\n5. **Tables change through migrations**: a new `db/migrations/NNNN_name.sql` per change, never edits to an\n   applied one; `npx ambasada db migrate` after deploying.\n\n## When the user is not a developer\n\nDo the work; don't ask them to edit code. Ask at most: what it does and for whom. Then build one page, run\n`npx ambasada dev`, open it, use it as the fake visitor, and show them it worked. Explain in one sentence\nper step, no jargon.\n", ".claude/skills/ambasada-product/reference/build-elsewhere.md": "# Built in ChatGPT, Lovable, Bolt or v0\n\nThree ways, easiest first.\n\n## A. Keep it hosted there, link it\n\nGood for: a site that is finished where it is and only needs to show up in the Ambasada app.\n\n1. On a laptop with Node 22+, once:\n\n   ```sh\n   npm create ambasada@latest my-app -- --miniapp --entry /   # its ambasada.config.ts and the manifest\n   cd my-app && npm install\n   npx ambasada login\n   npx ambasada link https://YOUR-SITE\n   ```\n\n2. The site must serve `/.well-known/ambasada.json` and `/icon.png` (copy them from the new project's\n   `public/`; `npx ambasada dev` writes the manifest there) and pass `npx ambasada check https://YOUR-SITE`\n   ([mini-app.md](mini-app.md)).\n\nLimit: Sign in with Ambasada, notifications and the app's database, KV and files come with hosting on\nambasada.dev. A site hosted elsewhere keeps its own backend; use B or C to get them.\n\n## B. Bring the code home (recommended for Lovable and Bolt)\n\nGood for: anything with real work behind it. You get hosting on ambasada.dev and the full rules.\n\n1. Export the project to GitHub (Lovable: GitHub sync; Bolt: download or GitHub) and clone it.\n2. `npm create ambasada@latest my-app -- --template spa` and copy the exported `src/` (components, pages,\n   styles) into the new project's `src/`, replacing the starter UI. Keep the template's `api/`, `lib/`,\n   `db/`, `ambasada.config.ts`, `wrangler.jsonc` and `vite.config.ts`.\n3. Open the project in Claude Code, Cursor or Codex and say:\n\n   > This is an Ambasada app (see .claude/skills/ambasada-product). Replace Supabase/Firebase with the\n   > app's env.DB (tables in db/migrations), env.KV and env.FILES, and any login with Sign in with Ambasada\n   > (api/auth.ts, /api/auth/me). Then run it with `npx ambasada dev`.\n\n4. `npx ambasada dev`, try it, then `npx ambasada deploy`.\n\n## C. ChatGPT (or any chat) writes the code, you paste it\n\n1. `npm create ambasada@latest my-app`, `cd my-app && npm install`, `npx ambasada dev`.\n2. Paste this into ChatGPT, then the files it mentions, then your idea:\n\n   > I have a Next.js 16 App Router project that runs on Cloudflare Workers (OpenNext). Rules: no `fs`, no\n   > native packages, no `next/image` (use `<img>`), no middleware, no `revalidate`, no other login than the\n   > one in `app/api/auth`. Data goes in SQLite through `lib/db.ts` (tables in `db/migrations/*.sql`), the\n   > signed-in person comes from `currentUser()` in `lib/ambasada.ts`. Below are my `app/page.tsx`,\n   > `app/api/notes/route.ts` and `db/migrations/0001_init.sql`. Rewrite them for my idea: the main action\n   > visible on a phone without scrolling. Write complete files, one code block per file, with the file path\n   > above each. My idea: \u2026\n\n3. Paste each file where ChatGPT says, keep `npx ambasada dev` running, check the page. New tables: a new\n   file in `db/migrations/` (never edit an applied one). When it works: `npx ambasada deploy` and\n   `npx ambasada db migrate`.\n\nUse ChatGPT to write files, not to decide the stack: if its answer adds Prisma, Supabase, NextAuth,\n`next/image` or a `middleware.ts`, tell it \"that's banned in my project, do it without\".\n", ".claude/skills/ambasada-product/reference/design.md": '# Design for people who decide in 10 seconds\n\nPeople open your app on a phone, often inside the Ambasada app, between two other things. They decide in\nseconds whether it is for them. Build for that.\n\n## One page, one action\n\n- **One page first.** What it is, and the one thing to do, fit on the first screen of a phone (375 \xD7 667).\n  Extra pages only when the action needs them.\n- **One action.** One button that does the main thing. Add a second only after people use the first.\n- **Few words.** A headline of up to 8 words, one sentence under it, the button. Cut every adjective you can.\n- **Show the result.** One example of what people get (an image, a sample text) beats any description.\n- **No walls.** No signup before the first use, no cookie banner, no tour. Ask for sign-in when the app\n  needs to remember someone (Sign in with Ambasada is one tap inside the Ambasada app).\n\n## The button\n\n- Label it with the action: **Make my poem**, not **Submit**.\n- Big (at least 48 px tall), full width on phones, one strong colour, nothing else in that colour.\n- If people must type something first, put that one field right above the button.\n- After the action, show the result, or "Working on it\u2026" and the result appearing when ready (a live room\n  or polling). Never a blank page.\n\n## Look\n\n- The templates use `@ambasada/ui` (the Ambasada app\'s look: tokens, `ui-card`, `ui-button`); start there\n  ([mini-app.md](mini-app.md)). Otherwise plain CSS: one font, two colours plus grey, generous spacing.\n- Large text: 18 px body on phones, a headline twice that. Light theme.\n- Works with one thumb: tap targets 48 px, no hover-only menus.\n- Loads fast: no video backgrounds, no 3 MB hero images, no animation libraries.\n\n## Words\n\n- Say what they get, not how it works. "A logo in 1 minute", not "AI-powered logo generation".\n- Write in the language of your users; one is fine.\n\n## Before and after\n\n```\nBad:  Welcome to PoemForge\u2122, the next-generation AI-powered creative writing platform\n      [Features] [Pricing] [About] [Sign up]   \u2026scroll\u2026   [Get started]\n\nGood: Your name as a folk poem\n      Type a name. Get a 4-line Romanian folk poem in 10 seconds.\n      [ Name: _________ ]\n      [   Make my poem   ]\n      "Ana, floare de la munte, / \u2026"  \u2190 one real example\n```\n', ".claude/skills/ambasada-product/reference/dev-and-deploy.md": "# Run it, put it online\n\n## `ambasada dev`: everything on your laptop\n\n```sh\nnpx ambasada dev\n```\n\nStarts two things:\n\n1. a **mock Ambasada API** on `http://127.0.0.1:8788`: same routes and signatures as the real one. Sign in\n   with Ambasada signs you in as \"Fake Visitor\"; `apps.notify` lands in a fake hub; `ambasada.store` and\n   `ambasada.files` work in memory. Open it in a browser for a page with what happened.\n2. **your site** with its normal dev server (`next dev`, `vite` or `wrangler dev`), pointed at the mock.\n\nNo login. The app's database, KV, files and Durable Objects run locally too (wrangler, `.wrangler/state`);\n`ambasada dev` applies `db/migrations/` to the local database before it starts the site.\n\nTry it: open your site, sign in, add a note. With the mini app on, `http://localhost:3000/app?ambasada_shell=mock`\n(your `miniapp.entry`) pretends to be inside the Ambasada app (host bar insets, silent sign-in).\n\n`npx ambasada dev --mock-only` starts only the mock, if you run your site yourself. The mock's keys:\n`AMBASADA_API_URL=http://127.0.0.1:8788`, `AMBASADA_API_KEY=sk_test_dev` (already in the project's `.env`).\n\n## `ambasada deploy`: online at `<slug>.ambasada.dev`\n\nOnce, in the app's folder:\n\n```sh\nnpx ambasada login        # opens a page: sign in with Ambasada ID\n```\n\n(If it asks for a key instead: https://developer.ambasada.dev \u2192 your app \u2192 a project key, `vk_\u2026`.)\nEach app's key is kept under its id: with two apps on one laptop, log in once in each folder, and each folder uses\nits own. `deploy`, `db`/`kv`/`files`, `env`, `logs`, `tunnel` and the village's commands that change something refuse\na key of another app than the folder's `id` (\"this folder is X, you are logged in as Y\"); `--company Y` goes ahead.\n\nThen, every time you want the new version online:\n\n```sh\nnpx ambasada deploy\n```\n\nIt does, in order:\n\n1. **build**: `opennextjs-cloudflare build` (Next), `vite build` (spa) or a bundle of the Worker (worker);\n2. **smoke test**: runs the built Worker locally in workerd and requests `/` and `/.well-known/ambasada.json`\n   (written from `ambasada.config.ts` first, when the mini app is on: [mini-app.md](mini-app.md));\n   a crash stops the deploy (skip with `--no-smoke` only if you know why it fails);\n3. **upload**: the URL is `https://<your-slug>.ambasada.dev`, with `AMBASADA_API_KEY`, `AMBASADA_API_URL`,\n   Sign in with Ambasada and the app secret set for you, and the app's own database, KV namespace and bucket\n   bound as `DB`, `KV`, `FILES` (created on the first deploy) plus the Durable Objects from `wrangler.jsonc`.\n\nThe database's tables are not created by the deploy: run `npx ambasada db migrate` (it applies the new files\nin `db/migrations/`). No Cloudflare account needed. `--dry-run` builds and prints what it would upload.\n\nYour own secrets (an API key for another service): `npx ambasada env set NAME value` (live within about 30 s, and on\nevery deploy); `npx ambasada env list` shows the names.\n\nLimits: 10 MB compressed bundle, 1000 static files, short CPU time per request (waiting on `fetch` does not\ncount). Heavy work belongs in an API you call, or a Durable Object, not in one request.\n\n## `ambasada dev --tunnel`: your laptop, live\n\nWhen the Ambasada app, sign-in or webhooks need to reach the version on your laptop (before deploying, or to\ndebug), log in once, then:\n\n```sh\nnpx ambasada dev --tunnel         # your dev server, against the real API, at https://<slug>-dev.ambasada.dev\nnpx ambasada tunnel --port 5173   # or: only the tunnel, for a server you started yourself\n```\n\nUntil Ctrl+C, `https://<slug>-dev.ambasada.dev` is your app's URL. There is no mock in this mode. The first\ntime takes up to 2 minutes while the address is published; after that it is instant. Only one terminal per\napp at a time: `--force` takes it over. More: docs/TUNNEL.md.\n\n## `ambasada deploy --own`: your own Cloudflare account\n\nRuns `wrangler deploy` into your account (you need `npx wrangler login` first), then\n`ambasada link <your workers.dev URL>`. Set the secrets yourself: `npx wrangler secret put AMBASADA_API_KEY`.\n\n## `ambasada link`: the app is hosted somewhere else\n\n```sh\nnpx ambasada link https://my-thing.lovable.app\n```\n\nSets `product.url` in `ambasada.config.ts` and checks that `<url>/health` answers. Use it for Lovable, Bolt,\nv0, Vercel, your own server. See [build-elsewhere.md](build-elsewhere.md).\n\n## Watch it run\n\n```sh\nnpx ambasada logs --follow     # the last deploy and new errors\nnpx ambasada check https://<slug>.ambasada.dev   # https, no redirects, speed; the mini-app rules when it is on\n```\n\nThe Developer app (https://developer.ambasada.dev) has deploys, errors, users and the storage tabs.\n\n## Upgrading\n\nA new devkit: `npx ambasada upgrade` (dependencies, skills, mechanical code changes), then\n[upgrading.md](upgrading.md) for the steps a coding agent does.\n\n## When it goes wrong\n\n| Symptom | Fix |\n|---|---|\n| build fails on `fs`, `child_process`, a `.node` file, `sharp` | a banned package: see [stack.md](stack.md#nextjs-allowed-and-banned) |\n| smoke test: `/` answers 500 | open `npx ambasada dev`, load `/`, read the terminal error |\n| `no such table: \u2026` online | `npx ambasada db migrate` |\n| a Durable Object migration is refused on deploy | never edit or remove a deployed tag in `wrangler.jsonc`'s `migrations`; add the next one ([storage.md](storage.md)) |\n| `CONFIG: no API key` | missing `AMBASADA_API_KEY`: `.env` locally, `ambasada login` before deploying |\n| sign-in loops back to the login page | `PUBLIC_URL` differs from the URL in the browser; remove it or fix it |\n| `this app uses the village \u2026 not installed` | a Hack A Ton project: `npx ambasada upgrade` (adds `@ambasada/village`) |\n", ".claude/skills/ambasada-product/reference/mini-app.md": '# The app inside the Ambasada app (mini app)\n\n**Optional, opt in with `npx ambasada miniapp enable`** (or `npm create ambasada@latest my-app -- --miniapp`). An app\nis a website first; most stay that way. The mini app is one more surface of it, at a path: what the Ambasada mobile\napp opens, with silent sign-in and push notifications. Platform spec: docs/MINI-APPS.md (\xA715, decision 15.6).\n\n## Turn it on\n\n```sh\nnpx ambasada miniapp enable              # at /app; --entry /in-app for another path, --entry / for the whole site\nnpx ambasada miniapp                     # on or off, and the entry\nnpx ambasada miniapp enable --entry /app --force   # move it: --force removes what the old entry left (it lists them otherwise)\n```\n\nIt adds:\n\n| | |\n|---|---|\n| `miniapp: { entry: "/app", age_rating: "4+", kind: "tool" }` | `ambasada.config.ts`; optional `support` (email or URL, else the app\'s `support`), `tags` (\u2264 5), `subtitle`, `description`, `icon`, `category`, `accent`, `scopes`, `visibility`. The hub refuses an app without `age_rating` (`4+`, `9+`, `12+`, `17+`) |\n| the in-app layout and page, no site header | `app/app/` (Next), `src/in-app/InApp.tsx` rendered by `src/main.tsx` (spa), `web/app.html` (worker) |\n| `ready()` and silent sign-in | `app/app/in-app.tsx`, `src/in-app/shell.ts`, `web/in-app.js`; with `--entry /` hooked into the root layout instead |\n| a placeholder icon, 1024\xD71024 | `public/icon.png` (`web/icon.png`): replace it, keep it square and opaque |\n| `@ambasada/miniapp` | `package.json` (Next, spa): run `npm install` |\n\nThe manifest, `/.well-known/ambasada.json`, is not a file you keep: `ambasada dev` and `ambasada deploy` write it\nfrom `ambasada.config.ts` (id, name, description, `miniapp`) into `public/` (`web/`), and `.gitignore` leaves it out.\nTo write it by hand, put your own there and drop that `.gitignore` line: yours wins. Without `miniapp`, nothing is\nserved, `ambasada check` says "mini app: off" and the deploy does not register the app with the Ambasada app.\n\n## Is it listed?\n\n`ambasada deploy` registers the app with the Ambasada hub only when it serves the manifest, then checks it. It prints:\n\n```\n\u2713 in the Ambasada app: Listed for the event\n! in the Ambasada app: Unlisted \xB7 needs: icon, viewport\n  mini app: off, not in the Ambasada app (`ambasada miniapp enable` adds one)\n```\n\nUnlisted apps work, but only you see them in the Ambasada app. Fix what `needs` says and deploy again,\nor run `npx ambasada check https://<slug>.ambasada.dev` (or `npx ambasada check` for the local folder).\nThe checks: `/.well-known/ambasada.json` valid, `icon.png` a 1024\xD71024 PNG with no transparency, the entry page\nhas `<meta name="viewport" content="width=device-width, initial-scale=1">`, no dark-only theme, it answers in under\n3 s without a redirect, `/api/auth/callback` exists, the notifications webhook answers a signed ping. With the mini\napp off, only https, no redirects and the response time of `/`.\nConnected tools can do the same through MCP: `app_status`, `app_check`.\n\n## Look like the app: @ambasada/ui\n\nThe templates import `@ambasada/ui` (tokens, Inter + JetBrains Mono, `ui-card`, `ui-button`, `ui-row`,\n`ui-pill`, `ui-sheet`, `ui-stepper`, `ui-empty`, `ui-skeleton`). Use those classes before writing CSS.\nReact: `import { Card, Button, Sheet } from "@ambasada/ui/react"`. Plain HTML: one\n`<link rel="stylesheet" href="https://unpkg.com/@ambasada/ui@0.8/dist/ambasada-ui.css">`.\nLeave space for the app\'s bar: the page uses `--ambasada-safe-area-*` and `--ambasada-host-bar`.\nLight theme only; one red (primary) button per screen.\n\n## Notifications\n\nAlready wired in every template; they work once the mini app is on:\n\n| Piece | Where |\n|---|---|\n| manifest: `"scopes": ["identity", "notifications"]`, `"notifications": { "webhook": "/api/ambasada/webhook" }`, `"privacy_url": "/privacy"` | generated from `ambasada.config.ts` (the defaults; `miniapp.scopes` to change them) |\n| the webhook: verifies the hub\'s signature, saves `token \u2194 Ambasada user id` in `ambasada.store` | `app/api/ambasada/webhook/route.ts` (Next), `api/ambasada-webhook.ts` (spa, worker) |\n| `notifyUser(app, userId, { \u2026 })`: push to one person if they turned notifications on | `lib/notifications.ts` |\n| the privacy page the scopes need | `app/(site)/privacy/page.tsx`, `public/privacy.html`, `web/privacy.html` |\n\nSend one when something the person waits for happens (their order is ready), never as marketing:\n\n```ts\nimport { notifyUser } from "../lib/notifications.ts";\n\nconst user = await ambasada().auth.user(req);            // signed in with Ambasada\nif (user) await notifyUser(ambasada(), user.id, {\n  notification_id: `order-${id}-ready`,                  // unique per message; repeats are dropped for 24 h\n  title: "Your translation is ready",                    // \u2264 40 characters\n  body: "Tap to read it.",                               // \u2264 140\n  url: `/orders/${id}`,                                  // a path on your site: where the tap opens\n});\n```\n\nPeople turn notifications on in the app (the app asks; the page can ask too with\n`notifications.request()` from `@ambasada/miniapp`, from a button). The secret (`AMBASADA_APP_SECRET`) is\ninjected by `ambasada deploy`; never put it in the browser.\n\n## Signed in without a consent screen\n\nInside the Ambasada app the page signs in silently: `auth.signIn()` from `@ambasada/miniapp` gets a short\ntoken from the app and POSTs it to `/api/auth/shell`, which sets the same session as "Sign in with\nAmbasada". Server code doesn\'t change: `currentUser()` / `ambasada().auth.user(req)` work either way.\nOn the web, the button and consent screen stay. Silent sign-in needs the app to be Verified; until then\n`signIn()` resolves `null` and the button shows.\n\n## Try it locally\n\n`npx ambasada dev` plays the hub (with the mini app on): when your app starts it sends a signed `ping` and\n`notifications_enabled` to your webhook (the token lands in the store as\n`ambasada/notifications/user_fake_visitor`), and its `/api/apps/notify` accepts pushes for that token\n(they show in the terminal). Open `http://localhost:3000/app?ambasada_shell=mock` (your entry) to pretend to be\ninside the app: the fake shell signs you in silently as "Fake Visitor".\n', ".claude/skills/ambasada-product/reference/stack.md": '# The stack: Next.js on Cloudflare\n\nEvery Ambasada app is one Cloudflare Worker. The default template builds it from **Next.js 16.4**\nwith **@opennextjs/cloudflare 1.20** (the OpenNext adapter) and the `nodejs_compat` flag. You write a\nnormal Next.js App Router app; `ambasada deploy` turns it into a Worker.\n\n## Folder layout (template `next`)\n\n```\nmy-app/\n  app/layout.tsx               <html>, the Ambasada look (@ambasada/ui) and globals.css\n  app/(site)/layout.tsx        the site\'s header (app/account.tsx) around its pages; (site) is not in the URL\n  app/(site)/page.tsx          the landing page\n  app/notes.tsx                the notes example (a client component calling app/api/notes)\n  app/api/notes/route.ts       rows in env.DB, the list cached in env.KV\n  app/api/files/route.ts       uploads to env.FILES; app/files/[...key]/route.ts serves them\n  app/api/auth/*/route.ts      Sign in with Ambasada: login, callback, logout, me, shell (silent, in the app)\n  app/api/ambasada/webhook/    the Ambasada app\'s events: who turned notifications on (reference/mini-app.md)\n  app/account.tsx              the header: "Sign in with Ambasada", or the person\'s name and avatar\n  app/(site)/privacy/page.tsx  what you keep about people (the mini app\'s privacy_url)\n  app/(site)/room/             the live room demo\n  app/app/                     the mini app, once on (`ambasada miniapp enable`): its layout, page and in-app.tsx\n  lib/ambasada.ts              the Ambasada client for server code (reads the Worker env)\n  lib/notifications.ts         notifyUser(): a push to one person who turned notifications on\n  lib/db.ts, kv.ts, files.ts   env.DB, env.KV, env.FILES (reference/storage.md); lib/bindings.ts reaches them\n  db/migrations/               the database\'s tables, one .sql file per change\n  src/realtime/                the live room (a Durable Object) and its React hook\n  ambasada.config.ts           app id, name, one-line description, product URL, `miniapp` (optional)\n  wrangler.jsonc               Worker settings (nodejs_compat, assets) and the bindings DB, KV, FILES, ROOMS\n  worker.ts                    the Worker entry: live rooms\' WebSockets, then the Next.js app\n  open-next.config.ts          OpenNext settings; leave as is\n  .env                         secrets for local runs (never commit, never send to the browser)\n  .ambasada/project.json       the template and devkit version (`ambasada upgrade` reads it); commit it\n  .claude/skills/              this skill\n```\n\nOne more endpoint = one more `app/api/<name>/route.ts`. Data it keeps goes in `env.DB` (a migration in\n`db/migrations/`), `env.KV` or `env.FILES` ([storage.md](storage.md)).\n\n## Using the client\n\nServer code only (route handlers, server components, server actions):\n\n```ts\n// app/api/hello/route.ts\nimport { ambasada } from "../../../lib/ambasada.ts";\n\nexport async function GET(req: Request) {\n  const user = await ambasada().auth.user(req);\n  return Response.json({ hello: user?.name ?? "stranger" });\n}\n```\n\n`lib/ambasada.ts` creates one client per Worker instance with `createAmbasada({ env })` from `@ambasada/sdk`,\nwhere `env` comes from `getCloudflareContext()` (deployed); under `next dev` the SDK reads `process.env`.\nIt reads `AMBASADA_API_KEY` and `AMBASADA_API_URL` (default https://api.ambasada.dev). The client has `auth`\n(below), `apps` (notifications, [mini-app.md](mini-app.md)), `store` and `files`.\n\n## Who is signed in\n\nEvery hosted app gets **Sign in with Ambasada** (Ambasada ID) for free: no keys, no settings.\nThe template\'s header already has the button. In server code:\n\n```ts\nimport { currentUser } from "../lib/ambasada.ts";\nimport { bindings } from "../lib/bindings.ts";\nimport { run } from "../lib/db.ts";\n\nconst user = await currentUser(); // null, or { id, name, avatar_url, builder, pass, member_since, \u2026 }\nif (!user) redirect("/api/auth/login?returnTo=/orders");\nawait run(bindings().DB, "INSERT INTO orders (user_id, item) VALUES (?, ?)", user.id, item); // key per-person data by user.id\n```\n\nIn a route handler, `ambasada().auth.user(req)` does the same. Client components fetch `/api/auth/me`.\nAsk for the email only if you need it: `/api/auth/login` calls `auth.login(req, { email: true })`.\nDon\'t build your own login or accounts table, and don\'t add Clerk, Auth.js or Supabase Auth.\n\n## Next.js: allowed and banned\n\nAllowed, and enough for any product here:\n\n- pages and layouts (`app/**/page.tsx`, `layout.tsx`), server components, client components (`"use client"`)\n- route handlers (`app/api/**/route.ts`), server actions (`"use server"`)\n- `fetch` to any HTTPS API, `next/link`, `next/font`, plain CSS / CSS modules / Tailwind\n\nBanned (they fail on Workers or break the deploy):\n\n| Don\'t | Do instead |\n|---|---|\n| `next/image` with the default loader | `<img>`, or `images: { unoptimized: true }` in `next.config.ts` |\n| ISR, `export const revalidate = \u2026`, `revalidatePath`, `unstable_cache` | render on each request (`export const dynamic = "force-dynamic"`), or cache results in `env.KV` |\n| `fs`, `child_process`, `sharp`, `bcrypt`, `sqlite3`, `puppeteer`, any native package | `fetch` an API (an LLM provider with your own key in a secret, for example) |\n| a custom server (`server.js`, Express inside Next) | route handlers |\n| `middleware.ts` / `proxy.ts`, `export const runtime = "edge"` | check inside the page or route handler; Next\'s default runtime is right |\n| Prisma, Drizzle with a database, Supabase, Firebase, Mongo, Redis | `env.DB` (SQLite), `env.KV`, `env.FILES` ([storage.md](storage.md)) |\n| writing files at runtime, global variables as storage | `env.DB`, `env.KV`, `env.FILES` or a Durable Object (each request can run on a different machine) |\n\nKeep the bundle small: the Worker limit is 10 MB compressed. Big UI kits and icon packs are the usual cause.\n\n## Where data lives\n\nThe app has its own SQLite database (`env.DB`), key-value (`env.KV`), file storage (`env.FILES`, public at\n`/files/<key>`) and Durable Objects for live state, created at the first deploy. Which one fits, the migrations\nworkflow and copy-paste patterns: [storage.md](storage.md).\n\nAlso there, for small things: `ambasada.store` (JSON, 1 MB for the whole app: settings, not user data) and\n`ambasada.files.put(\u2026)` \u2192 `{ url }` (platform-hosted files that expire).\n\n## Secrets\n\n- Local: `.env` in the project (Cloudflare\'s `.dev.vars` works too). The template writes it with test\n  values for `ambasada dev`. Both are in `.gitignore`; keep them there.\n- Deployed: `ambasada deploy` injects `AMBASADA_API_KEY`, `AMBASADA_API_URL`, the Sign in with Ambasada\n  credentials (`AMBASADA_AUTH_*`) and the mini-app secret (`AMBASADA_APP_SECRET`, with `AMBASADA_HUB_URL`\n  and `AMBASADA_APP_ORIGIN`) for you. With `--own`, set them yourself: `npx wrangler secret put AMBASADA_API_KEY`.\n- Other services\' keys (an OpenAI key, say): `.env` locally, `npx ambasada env set OPENAI_API_KEY \u2026` online;\n  read on the server only.\n- Anything named `NEXT_PUBLIC_*` is copied into the browser. Never put a key there.\n- Never paste a key into a page, a client component, a prompt for a no-code builder, or a commit.\n\n## Variants\n\n- `spa`: Vite + React with `@cloudflare/vite-plugin`, for code exported from Lovable or Bolt. The\n  `api/` endpoints are small fetch handlers; the React app calls them with `fetch("/api/\u2026")`.\n- `worker`: `web/` (plain HTML/CSS) plus `api/*.ts` fetch handlers. Best when the app is a page or two.\n\nThe rules on this page (state, secrets, no native packages) apply to all three.\n', ".claude/skills/ambasada-product/reference/storage.md": '# Data, files and realtime\n\nEvery app on ambasada.dev gets a real database, key-value, file storage and Durable Objects. They are created\nat the first `ambasada deploy` and bound to the Worker on every deploy; nothing to sign up for or configure.\nLocally (`ambasada dev`, `wrangler dev`, `vite`) wrangler runs the same things from `.wrangler/state`.\n\n| Need | Use | Not |\n|---|---|---|\n| anything with rows: users\' data, orders, posts, scores, anything you query, sort or join | `env.DB` (SQLite, D1) | KV, files, `ambasada.store` |\n| sessions, caches of slow results, feature flags, "seen this already" | `env.KV` | a table you scan |\n| uploads, images, audio, PDFs, generated files | `env.FILES` (R2), public at `/files/<key>` | base64 in the database |\n| state several people see change live: chat, presence, a shared board, a game table, live counters, a queue, rate limits, one thing per entity | a Durable Object (`env.ROOMS` in the templates) | polling the database |\n| an AI agent with memory, schedules and live state per user or task | the Agents SDK (`examples/agent/`) | a cron that rereads everything |\n| a few small settings for a tiny app | `ambasada.store` (1 MB per app) | user data of any size |\n\nQuotas per app: database 500 MB, KV 1 GB, files 5 GB. A database over its quota stops the next deploy.\n\n## `env.DB`: SQLite\n\nSchema lives in `db/migrations/`, one file per change, applied in name order, never edited once applied:\n\n```sql\n-- db/migrations/0002_orders.sql\nCREATE TABLE orders (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  user_id TEXT NOT NULL,\n  item TEXT NOT NULL,\n  paid INTEGER NOT NULL DEFAULT 0,\n  created_at INTEGER NOT NULL\n);\nCREATE INDEX orders_user ON orders (user_id, created_at);\n```\n\n```sh\nnpx wrangler d1 migrations apply DB --local   # the local database, for ambasada dev\nnpx ambasada db migrate                       # the app\'s database online (run before or right after deploying)\nnpx ambasada db shell "SELECT * FROM orders LIMIT 5"\n```\n\nQuery with `lib/db.ts` (SQL with `?` placeholders, typed rows, no ORM):\n\n```ts\nimport { all, batch, first, run } from "../lib/db.ts";\n\ntype Order = { id: number; user_id: string; item: string; paid: number; created_at: number };\nconst mine = await all<Order>(env.DB, "SELECT * FROM orders WHERE user_id = ? ORDER BY created_at DESC LIMIT 50", user.id);\nconst one = await first<Order>(env.DB, "SELECT * FROM orders WHERE id = ?", id);\nconst { lastRowId } = await run(env.DB, "INSERT INTO orders (user_id, item, created_at) VALUES (?, ?, ?)", user.id, item, Date.now());\nawait batch(env.DB, [["UPDATE stock SET n = n - 1 WHERE item = ?", item], ["UPDATE orders SET paid = 1 WHERE id = ?", id]]); // all or nothing\n```\n\nIn Next.js route handlers and server components, the bindings come from `bindings()` (`lib/bindings.ts`):\n`const { DB } = bindings();`. In the spa and worker templates, handlers get `env`.\n\nRules: always placeholders, never string-built SQL. Key per-person rows by the Ambasada user id\n(`auth.user(req).id`). Add an index for every `WHERE` you run often. Times as `Date.now()` integers.\n\n## `env.KV`: sessions, caches, flags\n\nReads are fast everywhere; a write shows up everywhere within about a minute; one write per second per key.\n\n```ts\nimport { cached, getJson, putJson } from "../lib/kv.ts";\n\nawait putJson(env.KV, `session:${id}`, { userId }, { ttl: 60 * 60 * 24 });\nconst session = await getJson<{ userId: string }>(env.KV, `session:${id}`);\nconst stats = await cached(env.KV, "home:stats", 300, () => computeStats(env)); // recompute at most every 5 min\n```\n\nNot for counters, balances or anything two people write at once: use `env.DB` (a transaction) or a Durable Object.\n\n## `env.FILES`: uploads and generated files\n\n```ts\nimport { serveFile, upload } from "../lib/files.ts";\n\n// POST /api/files: a signed-in person uploads (the templates\' api/files.ts)\nconst { key, url } = await upload(env.FILES, req.body, { contentType: req.headers.get("content-type") ?? undefined, folder: `u/${user.id}` });\nawait run(env.DB, "INSERT INTO photos (user_id, file_key) VALUES (?, ?)", user.id, key); // keep the key, not the bytes\n\n// GET /files/*: already wired in every template, with ETag, ranges and cache headers\nreturn serveFile(env.FILES, req);\n```\n\n`url` is `/files/<key>` on the app (`https://<slug>.ambasada.dev/files/<key>`): public to anyone with the link.\nPrivate files: store them under a key nobody can guess and serve them from your own route that checks\n`auth.user(req)` first, instead of `/files/*`. `npx ambasada files list | put | url | delete` from the terminal.\n\n## Durable Objects: realtime and per-entity state\n\nA Durable Object is one tiny server per id (a room, a document, a match, a user) with its own SQLite, that\nevery request for that id reaches. Use one whenever people must see each other\'s changes live, or one thing\nmust never be updated by two requests at once. The templates ship `src/realtime/room.ts` (`env.ROOMS`):\n\n```ts\n// the Worker: /api/rooms/<id>/ws \u2192 the room\nconst room = /^\\/api\\/rooms\\/([^/]+)\\/ws$/.exec(pathname);\nif (room) return env.ROOMS.getByName(decodeURIComponent(room[1]!)).fetch(req);\n```\n\n```ts\n// the room (shortened): WebSocket hibernation, broadcast, its own SQLite\nexport class Room extends DurableObject<unknown> {\n  async fetch(req: Request) {\n    const { 0: client, 1: server } = new WebSocketPair();\n    this.ctx.acceptWebSocket(server);              // hibernation: no cost while nobody talks\n    server.serializeAttachment({ name: "guest" }); // per-connection data that survives hibernation\n    return new Response(null, { status: 101, webSocket: client });\n  }\n  async webSocketMessage(ws: WebSocket, data: string | ArrayBuffer) {\n    this.ctx.storage.sql.exec("INSERT INTO messages (text, at) VALUES (?, ?)", String(data), Date.now());\n    for (const peer of this.ctx.getWebSockets()) peer.send(String(data)); // everyone in the room\n  }\n}\n```\n\n```tsx\n// the browser (React): src/realtime/use-room.ts\nconst { messages, online, send, status } = useRoom(roomId, { name: user.name });\n```\n\nA new class needs a binding and a migration in `wrangler.jsonc` (new tags go at the end; never edit or remove one\nthat was deployed; to drop a class add `{ "tag": "v3", "deleted_classes": ["Old"] }`):\n\n```jsonc\n"durable_objects": { "bindings": [{ "name": "ROOMS", "class_name": "Room" }, { "name": "BOARDS", "class_name": "Board" }] },\n"migrations": [{ "tag": "v1", "new_sqlite_classes": ["Room"] }, { "tag": "v2", "new_sqlite_classes": ["Board"] }]\n```\n\nExport the class from the Worker\'s entry (`src/worker.ts`; spa `worker/index.ts`; next `worker.ts`).\nOther shapes, same pattern: presence (who is online), a live counter (`UPDATE \u2026 RETURNING`, then broadcast), a\nper-user rate limit (`getByName(user.id)`), a job queue (`this.ctx.storage.setAlarm`). A Durable Object belongs\nto this app; other apps can\'t reach it. Under `next dev` they don\'t run: use `npm run preview` (workerd).\n\n## Agents (Agents SDK)\n\nFor agentic products (an assistant per user, a research task that runs for minutes, a bot that follows up),\nuse the Cloudflare Agents SDK: `examples/agent/` in the template (`npm i agents`, four lines to wire). An agent\nis a Durable Object with live state synced to clients (`setState`, `useAgent` in React), `this.sql`,\n`this.schedule(\u2026)` and WebSockets. One agent per user or task: `/agents/agent-example/<user id>`.\n\n## Don\'t\n\n- Poll (`setInterval(fetch\u2026)`) for what others changed: a Durable Object + WebSocket pushes it.\n- Put files or base64 in the database or KV: `env.FILES`, and keep the key in a row.\n- Keep user data in `ambasada.store`: it is 1 MB for the whole app.\n- Keep state in module variables or global objects: every request may run on another machine.\n- Count, rank or move money in KV: use a SQL transaction (`batch`) or a Durable Object.\n- Build SQL by joining strings with user input: `?` placeholders.\n- Edit an applied migration: add the next file.\n- Add Prisma, Drizzle with Postgres, Supabase, Firebase, Mongo or Redis: everything above is already here.\n', ".claude/skills/ambasada-product/reference/upgrading.md": "# Upgrading a project\n\n`npx ambasada upgrade` does the mechanical part: every `@ambasada/*` dependency to the CLI's version, the\npackage manager, `.claude/skills/ambasada-*` re-synced (the project's own skills are left alone), the code\nchanges listed below as \"done by `upgrade`\", the `ambasada check` rules, and `.ambasada/project.json`\n(the template and devkit version). `npx ambasada upgrade --check` only reports.\n\nWhat is left is below, per version, for a coding agent. Do the steps for every version between the one in\n`.ambasada/project.json` (none: 0.7) and the current one, in order. After each, run the app with\n`npx ambasada dev` and the project's `typecheck` script.\n\n## 0.7 \u2192 0.8: the platform and the village split\n\n0.8 splits the devkit: `@ambasada/sdk` and `ambasada` are the platform (sign-in, notifications, storage,\nhosting); the Hack A Ton economy (TON, checkout, offerings, the agent) is the add-on `@ambasada/village`.\n\nDone by `upgrade`:\n\n- the village names (`village`, `createVillage`, `offering`, `defineCompany`, `isVillageError`, the receipt and\n  webhook helpers, their types) import from `@ambasada/village`; in a village app `createAmbasada` became\n  `createVillage` and `DEFAULT_API_URL` became `DEFAULT_VILLAGE_API_URL` (their 0.7 meaning);\n- `@ambasada/village` added to `package.json` when the app has `offerings.ts` or an `idea`;\n- `.env` / `.dev.vars`: `AMBASADA_API_URL=https://hackaton.ambasada.id` became `https://api.ambasada.dev` plus\n  `AMBASADA_VILLAGE_API_URL=https://hackaton.ambasada.id`;\n- the `ambasada-payments` skill replaced by `ambasada-village`.\n\nFor the agent:\n\n1. **Platform code uses the platform client.** Files that only sign people in, send notifications or use\n   `store`/`files` can import `createAmbasada` / `ambasada` from `@ambasada/sdk` instead of the village client.\n   Leave files that sell, check receipts or call `llm` on the village client.\n2. **Config.** `ambasada.config.ts` may stay `defineCompany({ id, name, idea, \u2026 })`; the 0.8 form is\n   `defineCompany(defineApp({ id, name, description, product }), { idea, offerings, agent })` with\n   `defineApp` from `@ambasada/sdk`. Add a one-line `description` (the manifest's subtitle).\n3. **CLI calls.** In scripts, READMEs and `package.json`: `ambasada wallet|ledger|offerings|market|steer|webhook|links`\n   \u2192 `ambasada village \u2026`, `ambasada logs --agent` \u2192 `ambasada village logs --agent`, `ambasada dev buy` \u2192\n   `ambasada village dev buy`. The old spellings still work through 1.x with a warning.\n4. **Pages that load pay.js** from `AMBASADA_API_URL` should use the village client's `apiUrl` (or\n   `AMBASADA_VILLAGE_API_URL`): `AMBASADA_API_URL` is the platform's from 0.8.\n5. **Login.** The CLI's login moved from `~/.config/village` to `~/.config/ambasada` (moved on first use);\n   nothing to do unless a script reads that file.\n6. Run `npx ambasada check`, `npx ambasada dev` and the typecheck; deploy when they pass.\n", "README.md": "# My App\n\nAn app on Ambasada, one bare Cloudflare Worker (template `worker`): sign-in with Ambasada ID, a database,\nkey-value, files and live rooms; a mini app inside the Ambasada app if you want one. Everything here is a default;\nchange anything.\n\n```\nambasada.config.ts          id, name, one-line description, where the app runs\nsrc/worker.ts               the Worker: /api/<name> \u2192 api/<name>.ts, / (landing page), the rest from web/\napi/auth.ts                 Sign in with Ambasada (login, callback, logout, me, shell)\napi/ambasada-webhook.ts     the Ambasada app's events (notifications on/off); lib/notifications.ts sends pushes\napi/notes.ts, api/files.ts  env.DB + env.KV, uploads to env.FILES\nlib/ambasada.ts             the SDK client from the Worker's env\nlib/db.ts, kv.ts, files.ts  env.DB, env.KV, env.FILES; db/migrations/ the tables\nsrc/realtime/room.ts        the live room (a Durable Object); web/room.html is the demo\nweb/                        the landing page, static assets\nwrangler.jsonc              one Worker + assets, nodejs_compat, the storage bindings\n.claude/skills/             docs your coding agent reads (ambasada-product)\n```\n\n## 1. Run it (2 min)\n\nNeeds Node \u2265 22.\n\n```sh\nnpm install\nnpm run dev                # `ambasada dev`: the mock Ambasada API on :8788 + `wrangler dev` on http://localhost:3000\n```\n\nOpen http://localhost:3000: add a note, sign in (the mock signs you in as \"Fake Visitor\"), open /room in two tabs.\nhttp://127.0.0.1:8788 is the mock's page (sign-ins, notifications, the store). `ambasada dev` points your app at the\nmock whatever `.env` says.\n\n## 2. Make it yours\n\n- `ambasada.config.ts`: name and description.\n- A new endpoint: `api/<name>.ts` (and a line in `src/worker.ts`). Data goes in `env.DB` (a migration in `db/migrations/`), `env.KV` or `env.FILES`.\n- Ask your coding agent: it has the ambasada-product skill (stack, storage, sign-in, mini app, deploy).\n\nNo framework, no build step: `wrangler` bundles `src/worker.ts`, and `web/` is served as is.\n\n## 3. Go live (1 min)\n\n```sh\nnpx ambasada login         # Ambasada ID, or a project key from https://developer.ambasada.dev\nnpx ambasada deploy        # build, smoke test, host at https://my-app.ambasada.dev\nnpx ambasada db migrate    # db/migrations \u2192 the app's database\nnpx ambasada logs          # the last deploy and recent errors\n```\n\nSign-in, notifications and the storage are set up by the deploy; nothing to configure. Your own secrets:\n`npx ambasada env set NAME value`. Hosting elsewhere: `npx wrangler deploy`, then `npx ambasada link https://\u2026`.\n\n**Sign in with Ambasada**: the header's button signs people in with their Ambasada ID; on the server,\n`ambasada(\u2026).auth.user(req)` gives `{ id, name, avatar_url, builder, pass }` or null.\n\n## Storage and realtime\n\nEvery app gets these, provisioned at the first `ambasada deploy`; locally wrangler keeps them in `.wrangler/state`.\n\n| Binding | For | Here |\n|---|---|---|\n| `env.DB` | SQLite: anything relational | `lib/db.ts`, tables in `db/migrations/`, example `api/notes.ts` |\n| `env.KV` | sessions, caches, flags | `lib/kv.ts` (the notes cache) |\n| `env.FILES` | uploads, generated files; public at `/files/<key>` | `lib/files.ts`, upload `api/files.ts` |\n| `env.ROOMS` | live state shared between people (Durable Object) | `src/realtime/room.ts`, demo at `/room` |\n\n```sh\nnpx wrangler d1 migrations apply DB --local   # db/migrations \u2192 the local database (ambasada dev)\nnpx ambasada db migrate                       # \u2026 \u2192 the app's database online\nnpx ambasada db shell \"SELECT * FROM notes\"   # or `ambasada db shell` for a prompt\nnpx ambasada kv list | get <key> | put <key> <value> | delete <key>\nnpx ambasada files put <file> | list | url <key> | delete <key>\n```\n\nOptional: an agent with the Agents SDK in `examples/agent/` (its README: `npm i agents` and four lines to wire it).\n\n## In the Ambasada app (optional)\n\nOff by default: this is a website. `npx ambasada miniapp enable` adds a mini app at `/app` (`--entry /` for the whole\nsite): `miniapp: { entry: \"/app\" }` in `ambasada.config.ts`, web/app.html and web/in-app.js, a placeholder\n`web/icon.png`, and the manifest `ambasada dev` and `deploy` serve at `/.well-known/ambasada.json`. Then\n`http://localhost:3000/app?ambasada_shell=mock` pretends to be inside the Ambasada app. The ambasada-product skill:\nreference/mini-app.md.\n\n## Rules worth knowing\n\n- State lives in `env.DB`, `env.KV`, `env.FILES` or a Durable Object, never in module variables: a Worker has many instances.\n- Secrets only in `.env` locally and `ambasada env set` online; never in the code or `wrangler.jsonc` vars.\n- `npx ambasada check` runs the checks (https, no redirects, speed; the mini-app rules when it is on); `npx ambasada upgrade` after a new devkit.\n\nFor the Hack A Ton: `npx ambasada add village` (the add-on).\n\nBuilt by [CENTYSO](https://centyso.com) for [Ambasada](https://ambasada.id).\n", "ambasada.config.ts": 'import { defineApp } from "@ambasada/sdk";\n\nexport default defineApp({\n  id: "my-app",\n  name: "My App",\n  // One line about the app (the subtitle of its Ambasada mini app, if you add one: `ambasada miniapp enable`).\n  description: "Notes, a live room and sign-in",\n  // Where the app runs. `ambasada dev` serves it on http://localhost:3000; hosted, it is https://my-app.ambasada.dev\n  // (`ambasada deploy` sets it; `ambasada link https://\u2026` when you host elsewhere).\n  product: { url: "http://localhost:3000" },\n});\n', "api/ambasada-webhook.ts": '// POST /api/ambasada/webhook: the Ambasada app\'s events for this mini app (docs/MINI-APPS.md \xA77), signed with\n// AMBASADA_APP_SECRET (injected on ambasada.dev; `ambasada dev` plays the hub and sends a ping and\n// notifications_enabled here when it starts). The manifest points here: notifications.webhook.\nimport { isAmbasadaError } from "@ambasada/sdk";\nimport { ambasada, type Env } from "../lib/ambasada.ts";\nimport { forgetToken, saveToken } from "../lib/notifications.ts";\n\nexport default async function appWebhook(req: Request, env: Env): Promise<Response> {\n  const app = ambasada(env);\n  try {\n    const event = await app.apps.verifyWebhook(req); // throws if forged or stale\n    switch (event.event) {\n      case "notifications_enabled":\n      case "app_added":\n        if (event.token) await saveToken(app, event.user, event.token);\n        break;\n      case "notifications_disabled":\n      case "app_removed":\n        await forgetToken(app, event.user);\n        break;\n      case "ping": // `ambasada check` and the registry: answer 200\n        break;\n    }\n    return new Response("ok");\n  } catch (error) {\n    if (isAmbasadaError(error)) return error.toResponse();\n    throw error;\n  }\n}\n', "api/auth.ts": '// Sign in with Ambasada (Ambasada ID, OAuth + PKCE): zero setup. On https://<slug>.ambasada.dev the deploy\n// injects AMBASADA_AUTH_*; under `ambasada dev` the mock signs you in as a fake visitor.\n//   GET /api/auth/login?returnTo=/   \u2192 the Ambasada ID consent screen\n//   GET /api/auth/callback           \u2192 back from it: sets an HttpOnly session cookie, redirects to returnTo\n//   GET /api/auth/logout             \u2192 clears it\n//   GET /api/auth/me                 \u2192 { user } (null when signed out), for the browser\n//   POST /api/auth/shell { token }   \u2192 silent sign-in inside the Ambasada app: the same session, no consent screen\n//                                      (the page calls `auth.signIn()` from @ambasada/miniapp)\n// On the server: `await ambasada(env).auth.user(req)` \u2192 { id, name, avatar_url, builder, pass, \u2026 } or null.\nimport { isAmbasadaError } from "@ambasada/sdk";\nimport { ambasada, type Env } from "../lib/ambasada.ts";\n\nexport default async function auth(req: Request, env: Env): Promise<Response> {\n  const { auth } = ambasada(env);\n  try {\n    switch (new URL(req.url).pathname.replace(/\\/+$/, "")) {\n      case "/api/auth/login":\n        return await auth.login(req);\n      case "/api/auth/callback":\n        return await auth.callback(req);\n      case "/api/auth/logout":\n        return auth.logout(req);\n      case "/api/auth/shell":\n        return await auth.shell(req);\n      case "/api/auth/me": {\n        // Under `ambasada dev` the page needs the mock issuer for its fake shell (?ambasada_shell=mock).\n        const devIssuer = env.AMBASADA_AUTH_ISSUER?.startsWith("http://") ? env.AMBASADA_AUTH_ISSUER : undefined;\n        return Response.json({ user: await auth.user(req), configured: auth.configured, ...(devIssuer ? { dev_issuer: devIssuer } : {}) }, { headers: { "cache-control": "no-store" } });\n      }\n    }\n    return Response.json({ error: { code: "NOT_FOUND", message: "no such route" } }, { status: 404 });\n  } catch (error) {\n    if (isAmbasadaError(error)) return error.toResponse();\n    throw error;\n  }\n}\n', "api/files.ts": '// POST /api/files (raw body, content-type): a signed-in person uploads a file to env.FILES (lib/files.ts)\n// \u2192 { key, url }; the url (/files/<key>) is public and served by the /files/* route.\nimport { ambasada, type Env } from "../lib/ambasada.ts";\nimport { upload } from "../lib/files.ts";\n\nconst MAX_BYTES = 10 * 1024 * 1024;\n\nexport default async function files(req: Request, env: Env): Promise<Response> {\n  if (req.method !== "POST") return Response.json({ error: { code: "INVALID_REQUEST", message: "POST the file" } }, { status: 405 });\n  const user = await ambasada(env).auth.user(req);\n  if (!user) return Response.json({ error: { code: "UNAUTHORIZED", message: "sign in to upload" } }, { status: 401 });\n  const size = Number(req.headers.get("content-length") ?? 0);\n  if (!size || size > MAX_BYTES) return Response.json({ error: { code: "INVALID_REQUEST", message: "send a file up to 10 MB with a content-length" } }, { status: 413 });\n  const stored = await upload(env.FILES, req.body, { contentType: req.headers.get("content-type") ?? undefined, folder: `u/${user.id}` });\n  return Response.json(stored, { status: 201 });\n}\n', "api/notes.ts": '// GET /api/notes: the latest notes from env.DB (lib/db.ts), cached a minute in env.KV (lib/kv.ts).\n// POST /api/notes { text }: adds one. The table is db/migrations/0001_init.sql.\nimport type { Env } from "../lib/ambasada.ts";\nimport { all, run } from "../lib/db.ts";\nimport { cached, remove } from "../lib/kv.ts";\n\ntype Note = { id: number; text: string; created_at: number };\n\nexport default async function notes(req: Request, env: Env): Promise<Response> {\n  if (req.method === "POST") {\n    const { text } = (await req.json().catch(() => ({}))) as { text?: unknown };\n    if (typeof text !== "string" || !text.trim() || text.length > 500) {\n      return Response.json({ error: { code: "INVALID_REQUEST", message: "body must be { text }, 1 to 500 characters" } }, { status: 400 });\n    }\n    const { lastRowId } = await run(env.DB, "INSERT INTO notes (text, created_at) VALUES (?, ?)", text.trim(), Date.now());\n    await remove(env.KV, "notes:latest");\n    return Response.json({ id: lastRowId }, { status: 201 });\n  }\n  const latest = await cached(env.KV, "notes:latest", 60, () => all<Note>(env.DB, "SELECT id, text, created_at FROM notes ORDER BY id DESC LIMIT 20"));\n  return Response.json({ notes: latest });\n}\n', "db/migrations/0001_init.sql": "-- The app's first table. Add the next change as db/migrations/0002_<what>.sql (never edit an applied file), then:\n--   npx wrangler d1 migrations apply DB --local   (ambasada dev)\n--   npx ambasada db migrate                       (online)\nCREATE TABLE notes (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  text TEXT NOT NULL,\n  created_at INTEGER NOT NULL\n);\nCREATE INDEX notes_created ON notes (created_at);\n", "examples/agent/README.md": '# Agent (optional): the Cloudflare Agents SDK\n\nFor agentic products: an agent per user, document or task, with live state, its own SQL, schedules and\nWebSockets (`agent.ts`). It is a Durable Object, so it runs on ambasada.dev like the live rooms. To turn it on:\n\n1. `npm i agents`\n2. `wrangler.jsonc`: add the binding and a migration after the existing ones:\n   ```jsonc\n   "durable_objects": { "bindings": [{ "name": "ROOMS", "class_name": "Room" }, { "name": "AgentExample", "class_name": "AgentExample" }] },\n   "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Room"] }, { "tag": "v2", "new_sqlite_classes": ["AgentExample"] }]\n   ```\n3. In the Worker entry (`src/worker.ts`; spa: `worker/index.ts`; next: `worker.ts`):\n   ```ts\n   export { AgentExample } from "../examples/agent/agent.ts"; // next: "./examples/agent/agent.ts"\n   import { routeAgents } from "../examples/agent/agent.ts";\n   // first thing in fetch():\n   const agent = await routeAgents(req, env as unknown as Record<string, unknown>);\n   if (agent) return agent;\n   ```\n4. In the browser (React): `useAgent({ agent: "agent-example", name: user.id, onStateUpdate: setState })` from\n   `agents/react`; `agent.send("hello")`. Plain fetch: `GET /agents/agent-example/<name>`.\n\n`ambasada deploy` sends the new class and its migration; nothing else to set up. Docs: https://developers.cloudflare.com/agents/\n', "examples/agent/agent.ts": '/**\n * Optional: an agent with the Cloudflare Agents SDK (`agents`), for agentic products. An agent is a Durable\n * Object with superpowers: state synced live to every connected client (`setState`), its own SQL (`this.sql`),\n * scheduled work (`this.schedule`), WebSockets and HTTP. One instance per name: per user, per document, per task.\n * Not wired in by default: examples/agent/README.md has the four steps.\n */\nimport { Agent, routeAgentRequest, type Connection, type WSMessage } from "agents";\n\ntype State = { notes: number; lastNote: string | null };\n\nexport class AgentExample extends Agent<Cloudflare.Env, State> {\n  initialState: State = { notes: 0, lastNote: null };\n\n  async onStart() {\n    this.sql`CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY AUTOINCREMENT, text TEXT NOT NULL, at INTEGER NOT NULL)`;\n  }\n\n  // GET /agents/agent-example/<name>: what this agent knows.\n  async onRequest(_req: Request): Promise<Response> {\n    const notes = this.sql<{ id: number; text: string; at: number }>`SELECT id, text, at FROM notes ORDER BY id DESC LIMIT 20`;\n    return Response.json({ state: this.state, notes });\n  }\n\n  // A client (useAgent in the browser) sent a message: remember it, sync the new state to every client,\n  // and come back to it in a minute (call an LLM here, send a notification, \u2026).\n  async onMessage(connection: Connection, message: WSMessage) {\n    const text = String(message).slice(0, 2000);\n    this.sql`INSERT INTO notes (text, at) VALUES (${text}, ${Date.now()})`;\n    this.setState({ notes: this.state.notes + 1, lastNote: text });\n    await this.schedule(60, "followUp", { text });\n    connection.send(JSON.stringify({ ok: true }));\n  }\n\n  async followUp(payload: { text: string }) {\n    console.log(`a minute ago someone wrote: ${payload.text}`);\n  }\n}\n\n/** In your Worker\'s fetch, before your own routes: answers /agents/<agent>/<name> (HTTP and WebSocket). */\nexport const routeAgents = (req: Request, env: Record<string, unknown>) => routeAgentRequest(req, env);\n', gitignore: "node_modules/\n.env*\n.dev.vars*\n.wrangler/\ndist/\n.DS_Store\n# build output of `ambasada deploy`; project.json (template, devkit version) is kept\n.ambasada/*\n!.ambasada/project.json\n", "lib/ambasada.ts": 'import { createAmbasada, type Ambasada } from "@ambasada/sdk";\nimport type { Room } from "../src/realtime/room.ts";\n\n/** The Worker\'s env: `.env` locally (`ambasada dev` points it at the mock), secrets injected at deploy. */\nexport interface Env {\n  ASSETS: Fetcher;\n  /** The app\'s SQLite database (lib/db.ts), key-value (lib/kv.ts), files (lib/files.ts) and live rooms (src/realtime/room.ts). */\n  DB: D1Database;\n  KV: KVNamespace;\n  FILES: R2Bucket;\n  ROOMS: DurableObjectNamespace<Room>;\n  AMBASADA_API_KEY?: string;\n  /** Set by `ambasada deploy` and `ambasada dev`; the SDK defaults to https://api.ambasada.dev. */\n  AMBASADA_API_URL?: string;\n  AMBASADA_APP_ID?: string;\n  /** Sign in with Ambasada (api/auth.ts): set by `ambasada deploy` on ambasada.dev, and by `ambasada dev`. */\n  AMBASADA_AUTH_CLIENT_ID?: string;\n  AMBASADA_AUTH_CLIENT_SECRET?: string;\n  AMBASADA_AUTH_ISSUER?: string;\n  /** Mini-app notifications (api/ambasada-webhook.ts, lib/notifications.ts): set on ambasada.dev and by `ambasada dev`. */\n  AMBASADA_APP_SECRET?: string;\n  AMBASADA_HUB_URL?: string;\n  AMBASADA_APP_ORIGIN?: string;\n  /** Your public URL, if the Worker sees another host (behind a proxy). */\n  PUBLIC_URL?: string;\n}\n\nlet client: Ambasada | undefined;\n\n/** One client per isolate: it caches the API\'s signing keys. */\nexport function ambasada(env: Env): Ambasada {\n  return (client ??= createAmbasada({ env: env as unknown as Record<string, unknown> }));\n}\n', "lib/db.ts": '/**\n * env.DB: this app\'s SQLite database (Cloudflare D1). The tables come from db/migrations/*.sql:\n * `npx ambasada db migrate` online, `npx wrangler d1 migrations apply DB --local` for `ambasada dev`.\n * A tiny typed layer, no ORM: SQL with ? placeholders in, plain objects out.\n *\n *   const notes = await all<Note>(env.DB, "SELECT * FROM notes ORDER BY id DESC LIMIT ?", 20);\n *   const note = await first<Note>(env.DB, "SELECT * FROM notes WHERE id = ?", id);\n *   const { lastRowId } = await run(env.DB, "INSERT INTO notes (text) VALUES (?)", text);\n *   await batch(env.DB, [["UPDATE a SET n = n - 1 WHERE id = ?", 1], ["UPDATE b SET n = n + 1 WHERE id = ?", 2]]); // one transaction\n */\n\nexport type Param = string | number | boolean | null | ArrayBuffer;\n\n/** What this file needs from a D1 binding (env.DB satisfies it). */\nexport interface Database {\n  prepare(query: string): Statement;\n  batch(statements: Statement[]): Promise<unknown[]>;\n}\n\nexport interface Statement {\n  bind(...values: unknown[]): Statement;\n  all<T = Record<string, unknown>>(): Promise<{ results: T[] }>;\n  first<T = Record<string, unknown>>(): Promise<T | null>;\n  run(): Promise<{ meta: { changes: number; last_row_id: number } }>;\n}\n\nconst statement = (db: Database, query: string, params: Param[]) => db.prepare(query).bind(...params);\n\n/** Every row. */\nexport async function all<T = Record<string, unknown>>(db: Database, query: string, ...params: Param[]): Promise<T[]> {\n  return (await statement(db, query, params).all<T>()).results;\n}\n\n/** The first row, or null. */\nexport function first<T = Record<string, unknown>>(db: Database, query: string, ...params: Param[]): Promise<T | null> {\n  return statement(db, query, params).first<T>();\n}\n\n/** INSERT, UPDATE, DELETE: how many rows changed and the last inserted id. */\nexport async function run(db: Database, query: string, ...params: Param[]): Promise<{ changes: number; lastRowId: number }> {\n  const { meta } = await statement(db, query, params).run();\n  return { changes: meta.changes, lastRowId: meta.last_row_id };\n}\n\n/** Several statements in one transaction: all of them apply, or none. */\nexport async function batch(db: Database, statements: [query: string, ...params: Param[]][]): Promise<void> {\n  await db.batch(statements.map(([query, ...params]) => statement(db, query, params)));\n}\n', "lib/files.ts": '/**\n * env.FILES: this app\'s file storage (Cloudflare R2). Uploads and generated files; each one is public at\n * /files/<key> on the app\'s own address (the /files/* route calls serveFile). Don\'t keep files in the database.\n *\n *   const { key, url } = await upload(env.FILES, req.body, { contentType: "image/png" });   // url: /files/u/\u2026\n *   return serveFile(env.FILES, req);                                                        // GET /files/*\n *\n * Files are public to anyone with the URL: keep private documents behind your own route that checks who asks.\n * `npx ambasada files put|list|delete|url` manages them from the terminal.\n */\n\n/** What this file needs from an R2 binding (env.FILES satisfies it). */\nexport interface Bucket {\n  put(key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null, options?: { httpMetadata?: { contentType?: string } }): Promise<unknown>;\n  get(key: string, options?: { onlyIf?: Headers; range?: Headers }): Promise<StoredFile | null>;\n  delete(key: string): Promise<void>;\n}\n\nexport interface StoredFile {\n  httpEtag: string;\n  size: number;\n  httpMetadata?: { contentType?: string };\n  range?: { offset?: number; length?: number; suffix?: number };\n  body?: ReadableStream;\n}\n\nexport const FILES_PATH = "/files/";\n\n/** Stores `body` under a new random key (in `folder`) \u2192 `{ key, url }`, url relative to the app (/files/<key>). */\nexport async function upload(bucket: Bucket, body: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null, options: { contentType?: string; folder?: string } = {}): Promise<{ key: string; url: string }> {\n  const key = `${options.folder ?? "u"}/${crypto.randomUUID()}`;\n  await bucket.put(key, body, { httpMetadata: { contentType: options.contentType ?? "application/octet-stream" } });\n  return { key, url: fileUrl(key) };\n}\n\nexport const fileUrl = (key: string) => `${FILES_PATH}${key.split("/").map(encodeURIComponent).join("/")}`;\n\n/** GET/HEAD /files/<key>: the file with its type, an ETag (304 when unchanged), byte ranges, and a cache header. */\nexport async function serveFile(bucket: Bucket, req: Request): Promise<Response> {\n  if (req.method !== "GET" && req.method !== "HEAD") return new Response(null, { status: 405, headers: { allow: "GET, HEAD" } });\n  const path = new URL(req.url).pathname;\n  const key = decodeURIComponent(path.slice(path.indexOf(FILES_PATH) + FILES_PATH.length));\n  if (!key) return new Response("Not found", { status: 404 });\n  const file = await bucket.get(key, { onlyIf: req.headers, range: req.headers });\n  if (!file) return new Response("Not found", { status: 404 });\n  const headers = new Headers({ etag: file.httpEtag, "cache-control": "public, max-age=3600", "accept-ranges": "bytes" });\n  if (file.httpMetadata?.contentType) headers.set("content-type", file.httpMetadata.contentType);\n  if (!file.body) return new Response(null, { status: 304, headers }); // If-None-Match matched: nothing changed\n  const r = file.range;\n  if (r && req.headers.has("range")) {\n    const offset = r.suffix !== undefined ? file.size - r.suffix : (r.offset ?? 0);\n    const length = r.suffix ?? r.length ?? file.size - offset;\n    headers.set("content-range", `bytes ${offset}-${offset + length - 1}/${file.size}`);\n    headers.set("content-length", String(length));\n    return new Response(req.method === "HEAD" ? null : file.body, { status: 206, headers });\n  }\n  headers.set("content-length", String(file.size));\n  return new Response(req.method === "HEAD" ? null : file.body, { headers });\n}\n', "lib/kv.ts": '/**\n * env.KV: this app\'s key-value store (Cloudflare KV). Fast reads everywhere, writes visible within about a\n * minute, at most one write per second per key. Good for sessions, caches and feature flags; not for counters\n * or anything two people change at once (use env.DB, or a Durable Object for live state).\n *\n *   await putJson(env.KV, `session:${id}`, { user }, { ttl: 60 * 60 * 24 });\n *   const session = await getJson<{ user: string }>(env.KV, `session:${id}`);\n *   const page = await cached(env.KV, "home:stats", 60, () => computeStats());\n */\n\n/** What this file needs from a KV binding (env.KV satisfies it). */\nexport interface KeyValue {\n  get(key: string, type: "text"): Promise<string | null>;\n  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;\n  delete(key: string): Promise<void>;\n}\n\n/** The value saved under `key`, parsed; null when there is none (or it expired). */\nexport async function getJson<T>(kv: KeyValue, key: string): Promise<T | null> {\n  const text = await kv.get(key, "text");\n  return text === null ? null : (JSON.parse(text) as T);\n}\n\n/** Saves `value` as JSON. `ttl`: seconds until it disappears (at least 60). */\nexport function putJson(kv: KeyValue, key: string, value: unknown, options: { ttl?: number } = {}): Promise<void> {\n  return kv.put(key, JSON.stringify(value), options.ttl ? { expirationTtl: Math.max(60, options.ttl) } : undefined);\n}\n\nexport function remove(kv: KeyValue, key: string): Promise<void> {\n  return kv.delete(key);\n}\n\n/** `load()`\'s result, kept for `ttl` seconds: a cache in front of something slow. */\nexport async function cached<T>(kv: KeyValue, key: string, ttl: number, load: () => Promise<T>): Promise<T> {\n  const hit = await getJson<T>(kv, key);\n  if (hit !== null) return hit;\n  const value = await load();\n  await putJson(kv, key, value, { ttl });\n  return value;\n}\n', "lib/notifications.ts": '// Who turned notifications on, and how to reach them (docs/MINI-APPS.md \xA77). The hub sends a token per person\n// to the webhook route (api/ambasada-webhook.ts; app/api/ambasada/webhook/route.ts in Next); it lives in your\n// ambasada.store under the person\'s Ambasada user id.\nimport type { Ambasada, AppNotifyInput } from "@ambasada/sdk";\n\nconst key = (user: string) => `ambasada/notifications/${user}`;\n\nexport const saveToken = (app: Ambasada, user: string, token: string) => app.store.set(key(user), { token, enabled_at: new Date().toISOString() });\nexport const forgetToken = (app: Ambasada, user: string) => app.store.delete(key(user));\n\n/**\n * A push to one person (their Ambasada user id, e.g. `(await app.auth.user(req)).id`), if they turned\n * notifications on. False when they haven\'t, or the hub said the token is gone (then it is forgotten).\n *   await notifyUser(app, user.id, { notification_id: `order-${id}`, title: "Your translation is ready", body: "\u2026", url: `/orders/${id}` });\n */\nexport async function notifyUser(app: Ambasada, user: string, notification: Omit<AppNotifyInput, "tokens" | "users">): Promise<boolean> {\n  const saved = await app.store.get<{ token: string }>(key(user));\n  if (!saved) return false;\n  const result = await app.apps.notify({ ...notification, tokens: [saved.token] });\n  if (result.invalid.includes(saved.token)) await forgetToken(app, user);\n  return result.sent.includes(saved.token);\n}\n', "package.json": '{\n  "name": "@ambasada/template-worker",\n  "version": "0.1.0",\n  "private": true,\n  "description": "An Ambasada app: one bare Cloudflare Worker, web/ + api/*.ts fetch handlers.",\n  "type": "module",\n  "engines": {\n    "node": ">=22"\n  },\n  "scripts": {\n    "dev": "ambasada dev",\n    "preview": "wrangler dev --port 3000",\n    "typecheck": "tsc -p .",\n    "ambasada": "ambasada"\n  },\n  "dependencies": {\n    "@ambasada/sdk": "workspace:*"\n  },\n  "devDependencies": {\n    "@ambasada/cli": "workspace:*",\n    "@cloudflare/workers-types": "^5.20261102.1",\n    "typescript": "~5.9.3",\n    "wrangler": "^4.156.1"\n  }\n}\n', "src/realtime/room.ts": '/**\n * A live room (Durable Object `Room`, bound as env.ROOMS): everyone connected to the same room id shares it.\n *\n *   GET /api/rooms/<id>/ws  (WebSocket)  \u2192 env.ROOMS.getByName(id).fetch(req)\n *   client \u2192 { "text": "hi" }            server \u2192 { type: "history", messages } on join,\n *                                                 { type: "message", message } to everyone,\n *                                                 { type: "presence", online } when people come and go\n *\n * WebSocket hibernation: the object sleeps between messages and the connections stay open, so an idle room\n * costs nothing. Its own SQLite (`ctx.storage.sql`) keeps the last 50 messages, replayed to whoever joins.\n * The same shape fits presence, live counters, a game table, a queue or a rate limit: one object per thing.\n */\nimport { DurableObject } from "cloudflare:workers";\n\nconst KEEP = 50;\n\nexport type RoomMessage = { id: number; name: string; text: string; at: number };\nexport type RoomEvent = { type: "history"; messages: RoomMessage[] } | { type: "message"; message: RoomMessage } | { type: "presence"; online: number };\n\nexport class Room extends DurableObject<unknown> {\n  constructor(ctx: DurableObjectState, env: unknown) {\n    super(ctx, env);\n    ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS messages (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, text TEXT NOT NULL, at INTEGER NOT NULL)");\n  }\n\n  async fetch(req: Request): Promise<Response> {\n    if (req.headers.get("upgrade") !== "websocket") return Response.json({ online: this.ctx.getWebSockets().length, messages: this.history() });\n    // Who is talking: the client says. Behind Sign in with Ambasada, pass the signed-in name from your route instead.\n    const name = (new URL(req.url).searchParams.get("name") ?? "").trim().slice(0, 40) || "guest";\n    const { 0: client, 1: server } = new WebSocketPair();\n    this.ctx.acceptWebSocket(server);\n    server.serializeAttachment({ name });\n    server.send(JSON.stringify({ type: "history", messages: this.history() } satisfies RoomEvent));\n    this.broadcast({ type: "presence", online: this.ctx.getWebSockets().length });\n    return new Response(null, { status: 101, webSocket: client });\n  }\n\n  async webSocketMessage(ws: WebSocket, data: string | ArrayBuffer): Promise<void> {\n    let text = "";\n    try {\n      text = String((JSON.parse(typeof data === "string" ? data : new TextDecoder().decode(data)) as { text?: unknown }).text ?? "").trim().slice(0, 2000);\n    } catch {\n      return;\n    }\n    if (!text) return;\n    const { name } = ws.deserializeAttachment() as { name: string };\n    const at = Date.now();\n    const { id } = this.ctx.storage.sql.exec<{ id: number }>("INSERT INTO messages (name, text, at) VALUES (?, ?, ?) RETURNING id", name, text, at).one();\n    this.ctx.storage.sql.exec("DELETE FROM messages WHERE id <= ?", id - KEEP);\n    this.broadcast({ type: "message", message: { id, name, text, at } });\n  }\n\n  async webSocketClose(ws: WebSocket, code: number, reason: string): Promise<void> {\n    try {\n      ws.close(code, reason);\n    } catch {\n      // already closed\n    }\n    this.broadcast({ type: "presence", online: this.ctx.getWebSockets().filter((s) => s !== ws).length });\n  }\n\n  private history(): RoomMessage[] {\n    return this.ctx.storage.sql.exec<RoomMessage>("SELECT id, name, text, at FROM messages ORDER BY id").toArray();\n  }\n\n  private broadcast(event: RoomEvent): void {\n    const text = JSON.stringify(event);\n    for (const ws of this.ctx.getWebSockets()) {\n      try {\n        ws.send(text);\n      } catch {\n        // a closing socket: webSocketClose cleans up\n      }\n    }\n  }\n}\n', "src/worker.ts": '/**\n * The app: one Cloudflare Worker (`wrangler dev`, or `ambasada dev` with the mock API).\n *\n *   /api/<name>  \u2192 api/<name>.ts (fetch handlers; add yours to API below)\n *   /api/auth/*  \u2192 api/auth.ts: Sign in with Ambasada (login, callback, logout, me, shell)\n *   /api/ambasada/webhook \u2192 api/ambasada-webhook.ts: the Ambasada app\'s events (notifications on/off, ping)\n *   /api/notes, /api/files \u2192 api/notes.ts (env.DB + env.KV), api/files.ts (uploads to env.FILES)\n *   /api/rooms/<id>/ws \u2192 the live room <id> (src/realtime/room.ts, a Durable Object); demo at /room\n *   /files/*     \u2192 files from env.FILES (lib/files.ts)\n *   /            \u2192 web/index.html with who is signed in filled in\n *   the rest     \u2192 static files from web/ (wrangler.jsonc \u2192 assets)\n */\nimport appWebhook from "../api/ambasada-webhook.ts";\nimport auth from "../api/auth.ts";\nimport files from "../api/files.ts";\nimport notes from "../api/notes.ts";\nimport { ambasada, type Env } from "../lib/ambasada.ts";\nimport { FILES_PATH, serveFile } from "../lib/files.ts";\n\nexport { Room } from "./realtime/room.ts";\n\ntype Handler = (req: Request, env: Env) => Promise<Response>;\nconst API: Record<string, Handler> = { files, notes };\n\n/** The landing page, with the header\'s "Sign in with Ambasada" button or, once signed in, the person\'s name and avatar. */\nasync function landing(req: Request, env: Env): Promise<Response> {\n  const { auth } = ambasada(env);\n  const user = await auth.user(req);\n  return new HTMLRewriter()\n    .on("[data-auth-signin]", { element: (el) => void ((user || !auth.configured) && el.remove()) })\n    .on("[data-auth-user]", { element: (el) => void (user ? el.removeAttribute("hidden") : el.remove()) })\n    .on("[data-auth-avatar]", { element: (el) => void (user?.avatar_url ? el.setAttribute("src", user.avatar_url) : el.remove()) })\n    .on("[data-auth-name]", { element: (el) => void el.setInnerContent(user?.name ?? "Signed in") })\n    .transform(await env.ASSETS.fetch(req));\n}\n\nexport default {\n  async fetch(req, env) {\n    const { pathname } = new URL(req.url);\n    try {\n      if (pathname === "/health") return Response.json({ ok: true });\n      if (pathname.startsWith("/api/auth/")) return await auth(req, env);\n      if (pathname === "/api/ambasada/webhook") return await appWebhook(req, env);\n      const room = /^\\/api\\/rooms\\/([^/]+)\\/ws$/.exec(pathname);\n      if (room) return await env.ROOMS.getByName(decodeURIComponent(room[1]!)).fetch(req);\n      if (pathname.startsWith(FILES_PATH)) return await serveFile(env.FILES, req);\n      const api = /^\\/api\\/([^/]+)\\/?$/.exec(pathname);\n      if (api) {\n        const handler = API[api[1]!];\n        return handler ? await handler(req, env) : Response.json({ error: { code: "NOT_FOUND", message: "no such route" } }, { status: 404 });\n      }\n      if (pathname === "/") return await landing(req, env);\n      return env.ASSETS.fetch(req);\n    } catch (error) {\n      console.error(error);\n      return Response.json({ error: { code: "INTERNAL", message: "internal error" } }, { status: 500 });\n    }\n  },\n} satisfies ExportedHandler<Env>;\n', "tsconfig.json": '{\n  "compilerOptions": {\n    "target": "ES2022",\n    "module": "ESNext",\n    "moduleResolution": "Bundler",\n    "lib": ["ES2022"],\n    "types": ["@cloudflare/workers-types"],\n    "strict": true,\n    "noEmit": true,\n    "skipLibCheck": true,\n    "isolatedModules": true,\n    "verbatimModuleSyntax": true,\n    "allowImportingTsExtensions": true\n  },\n  "include": ["ambasada.config.ts", "src", "api", "lib"]\n}\n', "web/index.html": `<!doctype html>
+`, "tsconfig.app.json": '{\n  "compilerOptions": {\n    "composite": true,\n    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",\n    "target": "ES2022",\n    "lib": ["ES2022", "DOM", "DOM.Iterable"],\n    "module": "ESNext",\n    "moduleResolution": "Bundler",\n    "jsx": "react-jsx",\n    "strict": true,\n    "noEmit": true,\n    "skipLibCheck": true,\n    "isolatedModules": true,\n    "verbatimModuleSyntax": true,\n    "allowImportingTsExtensions": true\n  },\n  "include": ["src"],\n  "exclude": ["src/realtime/room.ts"]\n}\n', "tsconfig.json": '{\n  "files": [],\n  "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.worker.json" }, { "path": "./tsconfig.node.json" }]\n}\n', "tsconfig.node.json": '{\n  "compilerOptions": {\n    "composite": true,\n    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",\n    "target": "ES2022",\n    "lib": ["ES2023"],\n    "types": ["node"],\n    "module": "ESNext",\n    "moduleResolution": "Bundler",\n    "strict": true,\n    "noEmit": true,\n    "skipLibCheck": true,\n    "isolatedModules": true,\n    "verbatimModuleSyntax": true\n  },\n  "include": ["vite.config.ts"]\n}\n', "tsconfig.worker.json": '{\n  "compilerOptions": {\n    "composite": true,\n    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.worker.tsbuildinfo",\n    "target": "ES2022",\n    "lib": ["ES2022"],\n    "types": ["@cloudflare/workers-types"],\n    "module": "ESNext",\n    "moduleResolution": "Bundler",\n    "strict": true,\n    "noEmit": true,\n    "skipLibCheck": true,\n    "isolatedModules": true,\n    "verbatimModuleSyntax": true,\n    "allowImportingTsExtensions": true\n  },\n  "include": ["worker", "api", "lib", "src/realtime/room.ts", "ambasada.config.ts"]\n}\n', "vite.config.ts": 'import { cloudflare } from "@cloudflare/vite-plugin";\nimport react from "@vitejs/plugin-react";\nimport { defineConfig } from "vite";\n\nexport default defineConfig({\n  plugins: [react(), cloudflare()],\n  // allowedHosts: `ambasada dev --tunnel` serves this at https://<slug>-dev.ambasada.dev.\n  server: { port: 3000, allowedHosts: [".ambasada.dev"] },\n});\n', "worker/index.ts": '/**\n * The app\'s Worker (`vite` runs it locally through @cloudflare/vite-plugin):\n *\n *   /api/<name>  \u2192 api/<name>.ts (fetch handlers; add yours to API below)\n *   /api/auth/*  \u2192 api/auth.ts: Sign in with Ambasada (login, callback, logout, me, shell)\n *   /api/ambasada/webhook \u2192 api/ambasada-webhook.ts: the Ambasada app\'s events (notifications on/off, ping)\n *   /api/notes, /api/files \u2192 api/notes.ts (env.DB + env.KV), api/files.ts (uploads to env.FILES)\n *   /api/rooms/<id>/ws \u2192 the live room <id> (src/realtime/room.ts, a Durable Object); demo at /room\n *   /files/*     \u2192 files from env.FILES (lib/files.ts)\n *   /health      \u2192 { ok: true }\n *   the rest     \u2192 the React app in src/ (static assets; unknown paths get index.html, see wrangler.jsonc)\n */\nimport appWebhook from "../api/ambasada-webhook.ts";\nimport auth from "../api/auth.ts";\nimport files from "../api/files.ts";\nimport notes from "../api/notes.ts";\nimport type { Env } from "../lib/ambasada.ts";\nimport { FILES_PATH, serveFile } from "../lib/files.ts";\n\nexport { Room } from "../src/realtime/room.ts";\n\ntype Handler = (req: Request, env: Env) => Promise<Response>;\nconst API: Record<string, Handler> = { files, notes };\n\nexport default {\n  async fetch(req, env) {\n    const { pathname } = new URL(req.url);\n    try {\n      if (pathname === "/health") return Response.json({ ok: true });\n      if (pathname.startsWith("/api/auth/")) return await auth(req, env);\n      if (pathname === "/api/ambasada/webhook") return await appWebhook(req, env);\n      const room = /^\\/api\\/rooms\\/([^/]+)\\/ws$/.exec(pathname);\n      if (room) return await env.ROOMS.getByName(decodeURIComponent(room[1]!)).fetch(req);\n      if (pathname.startsWith(FILES_PATH)) return await serveFile(env.FILES, req);\n      const api = /^\\/api\\/([^/]+)\\/?$/.exec(pathname);\n      const handler = api ? API[api[1]!] : undefined;\n      if (handler) return await handler(req, env);\n      if (api) return Response.json({ error: { code: "NOT_FOUND", message: "no such route" } }, { status: 404 });\n      return env.ASSETS.fetch(req);\n    } catch (error) {\n      console.error(error);\n      return Response.json({ error: { code: "INTERNAL", message: "internal error" } }, { status: 500 });\n    }\n  },\n} satisfies ExportedHandler<Env>;\n', "wrangler.jsonc": '{\n  "$schema": "node_modules/wrangler/config-schema.json",\n  // One Worker: worker/index.ts answers /api/*, /files/* and /health; the React app (vite build) is served as assets.\n  "name": "my-app",\n  "main": "worker/index.ts",\n  "compatibility_date": "2026-09-01",\n  "compatibility_flags": ["nodejs_compat"],\n  "assets": {\n    "binding": "ASSETS",\n    "not_found_handling": "single-page-application",\n    "run_worker_first": ["/api/*", "/files/*", "/health"]\n  },\n  // Storage and realtime: env.DB (SQLite), env.KV, env.FILES and the live rooms (src/realtime/room.ts).\n  // No ids: wrangler keeps local copies in .wrangler/state; `ambasada deploy` attaches the app\'s real ones.\n  "d1_databases": [{ "binding": "DB", "database_name": "my-app", "migrations_dir": "db/migrations", "migrations_table": "_ambasada_migrations" }],\n  "kv_namespaces": [{ "binding": "KV" }],\n  "r2_buckets": [{ "binding": "FILES", "bucket_name": "my-app" }],\n  "durable_objects": { "bindings": [{ "name": "ROOMS", "class_name": "Room" }] },\n  // Every Durable Object class needs a migration; add new ones at the end, never edit or remove an applied tag.\n  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Room"] }],\n  "observability": { "enabled": true }\n}\n' }, worker: { ".claude/skills/ambasada-product/SKILL.md": "---\nname: ambasada-product\ndescription: Build an app on Ambasada and put it online. Use when the user wants to make an app, tool, game or website, start one with `npm create ambasada@latest`, run it with `ambasada dev`, publish it with `ambasada deploy` at <slug>.ambasada.dev, show it in the Ambasada app (mini app, notifications, sign-in), store data in the app's SQLite database, KV or file storage, make it realtime with Durable Objects or an agent (Agents SDK), bring a site built in ChatGPT, Lovable, Bolt or v0, or upgrade a project made with an older CLI (`ambasada upgrade`). Default stack: Next.js on Cloudflare.\n---\n\n# Build an app on Ambasada and put it online\n\nAn app is **one website** (one Cloudflare Worker) at `https://<your-slug>.ambasada.dev`. It comes with\nSign in with Ambasada (Ambasada ID), a SQLite database, key-value, file storage and Durable Objects for\nrealtime. If you want, it also gets a mini app inside the Ambasada app, with push notifications (off by default). No servers, no\nCloudflare account, no keys to configure.\n\n## Start\n\n```sh\nnpm create ambasada@latest my-app           # Next.js (default)\ncd my-app && npm install\nnpx ambasada dev                            # the mock API + your site, no login\n```\n\nOther templates: add `-- --template spa` (Vite + React; for code exported from Lovable or Bolt) or\n`-- --template worker` (plain HTML + small fetch handlers; the smallest possible app). All three have the\nsame `ambasada.config.ts`, sign-in routes, notifications webhook and storage helpers, and a notes example.\n\n## What to read\n\n| The user wants to\u2026 | Read |\n|---|---|\n| know where files go, what Next.js features are allowed, secrets, who is signed in | [reference/stack.md](reference/stack.md) |\n| store data (tables, migrations), sessions or caches, uploads; make it live between people (chat, presence, a shared board, counters); build an AI agent | [reference/storage.md](reference/storage.md) |\n| run it locally, put it online, use their own Cloudflare account | [reference/dev-and-deploy.md](reference/dev-and-deploy.md) |\n| make it look good and easy to use | [reference/design.md](reference/design.md) |\n| show up in the Ambasada app (optional: `npx ambasada miniapp enable`), send push notifications, sign people in inside the app | [reference/mini-app.md](reference/mini-app.md) |\n| build in ChatGPT, Lovable, Bolt or v0 and bring it here | [reference/build-elsewhere.md](reference/build-elsewhere.md) |\n| upgrade a project made with an older CLI | [reference/upgrading.md](reference/upgrading.md) |\n\nFor the Hack A Ton (TON payments, offerings, the agent that runs a shop): `npx ambasada add village`, then\nthe **ambasada-village** skill.\n\n## Rules (break one and the app does not work)\n\n1. **One app = one Worker.** No separate backend, no Docker. State lives in the app's SQLite (`env.DB`),\n   key-value (`env.KV`), file storage (`env.FILES`) or a Durable Object, never in module variables.\n   See [reference/storage.md](reference/storage.md).\n2. **Only the allowed Next.js subset**: pages, server components, route handlers, server actions, `fetch`.\n   No `next/image` default loader, no ISR/`revalidate`, no `fs`/`child_process`/native packages, no custom\n   server, no `middleware.ts`/`proxy.ts`, no `runtime = \"edge\"`. See [reference/stack.md](reference/stack.md#nextjs-allowed-and-banned).\n3. **Keys never reach the browser.** They live in `.env` locally and `ambasada env set` online; only server\n   code reads them. Never prefix one with `NEXT_PUBLIC_`.\n4. **Sign-in is Ambasada ID.** Use the template's `/api/auth/*` routes and `auth.user(req)`; don't add\n   Clerk, Auth.js or Supabase Auth, and don't build an accounts table. Key per-person data by `user.id`.\n5. **Tables change through migrations**: a new `db/migrations/NNNN_name.sql` per change, never edits to an\n   applied one; `npx ambasada db migrate` after deploying.\n\n## When the user is not a developer\n\nDo the work; don't ask them to edit code. Ask at most: what it does and for whom. Then build one page, run\n`npx ambasada dev`, open it, use it as the fake visitor, and show them it worked. Explain in one sentence\nper step, no jargon.\n", ".claude/skills/ambasada-product/reference/build-elsewhere.md": "# Built in ChatGPT, Lovable, Bolt or v0\n\nThree ways, easiest first.\n\n## A. Keep it hosted there, link it\n\nGood for: a site that is finished where it is and only needs to show up in the Ambasada app.\n\n1. On a laptop with Node 22+, once:\n\n   ```sh\n   npm create ambasada@latest my-app -- --miniapp --entry /   # its ambasada.config.ts and the manifest\n   cd my-app && npm install\n   npx ambasada login\n   npx ambasada link https://YOUR-SITE\n   ```\n\n2. The site must serve `/.well-known/ambasada.json` and `/icon.png` (copy them from the new project's\n   `public/`; `npx ambasada dev` writes the manifest there) and pass `npx ambasada check https://YOUR-SITE`\n   ([mini-app.md](mini-app.md)).\n\nLimit: Sign in with Ambasada, notifications and the app's database, KV and files come with hosting on\nambasada.dev. A site hosted elsewhere keeps its own backend; use B or C to get them.\n\n## B. Bring the code home (recommended for Lovable and Bolt)\n\nGood for: anything with real work behind it. You get hosting on ambasada.dev and the full rules.\n\n1. Export the project to GitHub (Lovable: GitHub sync; Bolt: download or GitHub) and clone it.\n2. `npm create ambasada@latest my-app -- --template spa` and copy the exported `src/` (components, pages,\n   styles) into the new project's `src/`, replacing the starter UI. Keep the template's `api/`, `lib/`,\n   `db/`, `ambasada.config.ts`, `wrangler.jsonc` and `vite.config.ts`.\n3. Open the project in Claude Code, Cursor or Codex and say:\n\n   > This is an Ambasada app (see .claude/skills/ambasada-product). Replace Supabase/Firebase with the\n   > app's env.DB (tables in db/migrations), env.KV and env.FILES, and any login with Sign in with Ambasada\n   > (api/auth.ts, /api/auth/me). Then run it with `npx ambasada dev`.\n\n4. `npx ambasada dev`, try it, then `npx ambasada deploy`.\n\n## C. ChatGPT (or any chat) writes the code, you paste it\n\n1. `npm create ambasada@latest my-app`, `cd my-app && npm install`, `npx ambasada dev`.\n2. Paste this into ChatGPT, then the files it mentions, then your idea:\n\n   > I have a Next.js 16 App Router project that runs on Cloudflare Workers (OpenNext). Rules: no `fs`, no\n   > native packages, no `next/image` (use `<img>`), no middleware, no `revalidate`, no other login than the\n   > one in `app/api/auth`. Data goes in SQLite through `lib/db.ts` (tables in `db/migrations/*.sql`), the\n   > signed-in person comes from `currentUser()` in `lib/ambasada.ts`. Below are my `app/page.tsx`,\n   > `app/api/notes/route.ts` and `db/migrations/0001_init.sql`. Rewrite them for my idea: the main action\n   > visible on a phone without scrolling. Write complete files, one code block per file, with the file path\n   > above each. My idea: \u2026\n\n3. Paste each file where ChatGPT says, keep `npx ambasada dev` running, check the page. New tables: a new\n   file in `db/migrations/` (never edit an applied one). When it works: `npx ambasada deploy` and\n   `npx ambasada db migrate`.\n\nUse ChatGPT to write files, not to decide the stack: if its answer adds Prisma, Supabase, NextAuth,\n`next/image` or a `middleware.ts`, tell it \"that's banned in my project, do it without\".\n", ".claude/skills/ambasada-product/reference/design.md": '# Design for people who decide in 10 seconds\n\nPeople open your app on a phone, often inside the Ambasada app, between two other things. They decide in\nseconds whether it is for them. Build for that.\n\n## One page, one action\n\n- **One page first.** What it is, and the one thing to do, fit on the first screen of a phone (375 \xD7 667).\n  Extra pages only when the action needs them.\n- **One action.** One button that does the main thing. Add a second only after people use the first.\n- **Few words.** A headline of up to 8 words, one sentence under it, the button. Cut every adjective you can.\n- **Show the result.** One example of what people get (an image, a sample text) beats any description.\n- **No walls.** No signup before the first use, no cookie banner, no tour. Ask for sign-in when the app\n  needs to remember someone (Sign in with Ambasada is one tap inside the Ambasada app).\n\n## The button\n\n- Label it with the action: **Make my poem**, not **Submit**.\n- Big (at least 48 px tall), full width on phones, one strong colour, nothing else in that colour.\n- If people must type something first, put that one field right above the button.\n- After the action, show the result, or "Working on it\u2026" and the result appearing when ready (a live room\n  or polling). Never a blank page.\n\n## Look\n\n- The templates use `@ambasada/ui` (the Ambasada app\'s look: tokens, `ui-card`, `ui-button`); start there\n  ([mini-app.md](mini-app.md)). Otherwise plain CSS: one font, two colours plus grey, generous spacing.\n- Large text: 18 px body on phones, a headline twice that. Light theme.\n- Works with one thumb: tap targets 48 px, no hover-only menus.\n- Loads fast: no video backgrounds, no 3 MB hero images, no animation libraries.\n\n## Words\n\n- Say what they get, not how it works. "A logo in 1 minute", not "AI-powered logo generation".\n- Write in the language of your users; one is fine.\n\n## Before and after\n\n```\nBad:  Welcome to PoemForge\u2122, the next-generation AI-powered creative writing platform\n      [Features] [Pricing] [About] [Sign up]   \u2026scroll\u2026   [Get started]\n\nGood: Your name as a folk poem\n      Type a name. Get a 4-line Romanian folk poem in 10 seconds.\n      [ Name: _________ ]\n      [   Make my poem   ]\n      "Ana, floare de la munte, / \u2026"  \u2190 one real example\n```\n', ".claude/skills/ambasada-product/reference/dev-and-deploy.md": "# Run it, put it online\n\n## `ambasada dev`: everything on your laptop\n\n```sh\nnpx ambasada dev\n```\n\nStarts two things:\n\n1. a **mock Ambasada API** on `http://127.0.0.1:8788`: same routes and signatures as the real one. Sign in\n   with Ambasada signs you in as \"Fake Visitor\"; `apps.notify` lands in a fake hub; `ambasada.store` and\n   `ambasada.files` work in memory. Open it in a browser for a page with what happened.\n2. **your site** with its normal dev server (`next dev`, `vite` or `wrangler dev`), pointed at the mock.\n\nNo login. The app's database, KV, files and Durable Objects run locally too (wrangler, `.wrangler/state`);\n`ambasada dev` applies `db/migrations/` to the local database before it starts the site.\n\nTry it: open your site, sign in, add a note. With the mini app on, `http://localhost:3000/app?ambasada_shell=mock`\n(your `miniapp.entry`) pretends to be inside the Ambasada app (host bar insets, silent sign-in).\n\n`npx ambasada dev --mock-only` starts only the mock, if you run your site yourself. The mock's keys:\n`AMBASADA_API_URL=http://127.0.0.1:8788`, `AMBASADA_API_KEY=sk_test_dev` (already in the project's `.env`).\n\n## `ambasada deploy`: online at `<slug>.ambasada.dev`\n\nOnce, in the app's folder:\n\n```sh\nnpx ambasada login        # opens a page: sign in with Ambasada ID\n```\n\n(If it asks for a key instead: https://developer.ambasada.dev \u2192 your app \u2192 a project key, `vk_\u2026`.)\nEach app's key is kept under its id: with two apps on one laptop, log in once in each folder, and each folder uses\nits own. `deploy`, `db`/`kv`/`files`, `env`, `logs`, `tunnel` and the village's commands that change something refuse\na key of another app than the folder's `id` (\"this folder is X, you are logged in as Y\"); `--company Y` goes ahead.\n\nThen, every time you want the new version online:\n\n```sh\nnpx ambasada deploy\n```\n\nIt does, in order:\n\n1. **build**: `opennextjs-cloudflare build` (Next), `vite build` (spa) or a bundle of the Worker (worker);\n2. **smoke test**: runs the built Worker locally in workerd and requests `/` and `/.well-known/ambasada.json`\n   (written from `ambasada.config.ts` first, when the mini app is on: [mini-app.md](mini-app.md));\n   a crash stops the deploy (skip with `--no-smoke` only if you know why it fails);\n3. **upload**: the URL is `https://<your-slug>.ambasada.dev`, with `AMBASADA_API_KEY`, `AMBASADA_API_URL`,\n   Sign in with Ambasada and the app secret set for you, and the app's own database, KV namespace and bucket\n   bound as `DB`, `KV`, `FILES` (created on the first deploy) plus the Durable Objects from `wrangler.jsonc`.\n\nThe database's tables are not created by the deploy: run `npx ambasada db migrate` (it applies the new files\nin `db/migrations/`). No Cloudflare account needed. `--dry-run` builds and prints what it would upload.\n\nYour own secrets (an API key for another service): `npx ambasada env set NAME value` (live within about 30 s, and on\nevery deploy); `npx ambasada env list` shows the names. `.env` (and `.env.local`, `.env.production`, `.dev.vars`) never\ngoes online: the deploy builds without them, so a value that is only there is missing on ambasada.dev; `env set` it.\n\nLimits: 10 MB compressed bundle, 1000 static files, short CPU time per request (waiting on `fetch` does not\ncount). Heavy work belongs in an API you call, or a Durable Object, not in one request.\n\n## `ambasada dev --tunnel`: your laptop, live\n\nWhen the Ambasada app, sign-in or webhooks need to reach the version on your laptop (before deploying, or to\ndebug), log in once, then:\n\n```sh\nnpx ambasada dev --tunnel         # your dev server, against the real API, at https://<slug>-dev.ambasada.dev\nnpx ambasada tunnel --port 5173   # or: only the tunnel, for a server you started yourself\n```\n\nUntil Ctrl+C, `https://<slug>-dev.ambasada.dev` is your app's URL. There is no mock in this mode. The first\ntime takes up to 2 minutes while the address is published; after that it is instant. Only one terminal per\napp at a time: `--force` takes it over. More: docs/TUNNEL.md.\n\n## `ambasada deploy --own`: your own Cloudflare account\n\nRuns `wrangler deploy` into your account (you need `npx wrangler login` first), then\n`ambasada link <your workers.dev URL>`. Set the secrets yourself: `npx wrangler secret put AMBASADA_API_KEY`.\n\n## `ambasada link`: the app is hosted somewhere else\n\n```sh\nnpx ambasada link https://my-thing.lovable.app\n```\n\nSets `product.url` in `ambasada.config.ts` and checks that `<url>/health` answers. Use it for Lovable, Bolt,\nv0, Vercel, your own server. See [build-elsewhere.md](build-elsewhere.md).\n\n## Watch it run\n\n```sh\nnpx ambasada logs --follow     # the last deploy and new errors\nnpx ambasada check https://<slug>.ambasada.dev   # https, no redirects, speed; the mini-app rules when it is on\n```\n\nThe Developer app (https://developer.ambasada.dev) has deploys, errors, users and the storage tabs.\n\n## Upgrading\n\nA new devkit: `npx ambasada upgrade` (dependencies, skills, mechanical code changes), then\n[upgrading.md](upgrading.md) for the steps a coding agent does.\n\n## When it goes wrong\n\n| Symptom | Fix |\n|---|---|\n| build fails on `fs`, `child_process`, a `.node` file, `sharp` | a banned package: see [stack.md](stack.md#nextjs-allowed-and-banned) |\n| smoke test: `/` answers 500 | open `npx ambasada dev`, load `/`, read the terminal error |\n| `no such table: \u2026` online | `npx ambasada db migrate` |\n| a Durable Object migration is refused on deploy | never edit or remove a deployed tag in `wrangler.jsonc`'s `migrations`; add the next one ([storage.md](storage.md)) |\n| `CONFIG: no API key` | missing `AMBASADA_API_KEY`: `.env` locally, `ambasada login` before deploying |\n| sign-in loops back to the login page | `PUBLIC_URL` differs from the URL in the browser; remove it or fix it |\n| `this app uses the village \u2026 not installed` | a Hack A Ton project: `npx ambasada upgrade` (adds `@ambasada/village`) |\n", ".claude/skills/ambasada-product/reference/mini-app.md": '# The app inside the Ambasada app (mini app)\n\n**Optional, opt in with `npx ambasada miniapp enable`** (or `npm create ambasada@latest my-app -- --miniapp`). An app\nis a website first; most stay that way. The mini app is one more surface of it, at a path: what the Ambasada mobile\napp opens, with silent sign-in and push notifications. Platform spec: docs/MINI-APPS.md (\xA715, decision 15.6).\n\n## Turn it on\n\n```sh\nnpx ambasada miniapp enable              # at /app; --entry /in-app for another path, --entry / for the whole site\nnpx ambasada miniapp                     # on or off, and the entry\nnpx ambasada miniapp enable --entry /app --force   # move it: --force removes what the old entry left (it lists them otherwise)\nnpx ambasada miniapp disable             # off again: the config key, the manifest and the glue (pages at /app stay until --force)\n```\n\nIt adds:\n\n| | |\n|---|---|\n| `miniapp: { entry: "/app", age_rating: "4+", kind: "tool" }` | `ambasada.config.ts`; optional `support` (email or URL, else the app\'s `support`), `tags` (\u2264 5), `subtitle`, `description`, `icon`, `category`, `accent`, `scopes`, `visibility`. The hub refuses an app without `age_rating` (`4+`, `9+`, `12+`, `17+`) |\n| the in-app layout and page, no site header | `app/app/` (Next), `src/in-app/InApp.tsx` rendered by `src/main.tsx` (spa), `web/app.html` (worker) |\n| `ready()` and silent sign-in | `app/app/in-app.tsx`, `src/in-app/shell.ts`, `web/in-app.js`; with `--entry /` hooked into the root layout instead |\n| a placeholder icon, 1024\xD71024 | `public/icon.png` (`web/icon.png`): replace it, keep it square and opaque |\n| `@ambasada/miniapp` | `package.json` (Next, spa): run `npm install` |\n\nThe manifest, `/.well-known/ambasada.json`, is not a file you keep: `ambasada dev` and `ambasada deploy` write it\nfrom `ambasada.config.ts` (id, name, description, `miniapp`) into `public/` (`web/`), and `.gitignore` leaves it out.\nTo write it by hand, put your own there and drop that `.gitignore` line: yours wins. Without `miniapp`, nothing is\nserved, `ambasada check` says "mini app: off" and the deploy does not register the app with the Ambasada app.\n\n## Is it listed?\n\n`ambasada deploy` registers the app with the Ambasada hub only when it serves the manifest, then checks it. It prints:\n\n```\n\u2713 in the Ambasada app: Listed for the event\n! in the Ambasada app: Unlisted \xB7 needs: icon, viewport\n  mini app: off, not in the Ambasada app (`ambasada miniapp enable` adds one)\n```\n\nUnlisted apps work, but only you see them in the Ambasada app. Fix what `needs` says and deploy again,\nor run `npx ambasada check https://<slug>.ambasada.dev` (or `npx ambasada check` for the local folder).\nThe checks: `/.well-known/ambasada.json` valid, `icon.png` a 1024\xD71024 PNG with no transparency, the entry page\nhas `<meta name="viewport" content="width=device-width, initial-scale=1">`, no dark-only theme, it answers in under\n3 s without a redirect, `/api/auth/callback` exists, the notifications webhook answers a signed ping. With the mini\napp off, only https, no redirects and the response time of `/`. On a first deploy the webhook\'s secret takes a few\nminutes to arrive: the deploy says `checks: running (up to 5 min)`, and `npx ambasada check` shows the result.\nConnected tools can do the same through MCP: `app_status`, `app_check`.\n\n## Look like the app: @ambasada/ui\n\nThe templates import `@ambasada/ui` (tokens, Inter + JetBrains Mono, `ui-card`, `ui-button`, `ui-row`,\n`ui-pill`, `ui-sheet`, `ui-stepper`, `ui-empty`, `ui-skeleton`). Use those classes before writing CSS.\nReact: `import { Card, Button, Sheet } from "@ambasada/ui/react"`. Plain HTML: one\n`<link rel="stylesheet" href="https://unpkg.com/@ambasada/ui@0.8/dist/ambasada-ui.css">`.\nLeave space for the app\'s bar: the page uses `--ambasada-safe-area-*` and `--ambasada-host-bar`.\nLight theme only; one red (primary) button per screen.\n\n## Notifications\n\nAlready wired in every template; they work once the mini app is on:\n\n| Piece | Where |\n|---|---|\n| manifest: `"scopes": ["identity", "notifications"]`, `"notifications": { "webhook": "/api/ambasada/webhook" }`, `"privacy_url": "/privacy"` | generated from `ambasada.config.ts` (the defaults; `miniapp.scopes` to change them) |\n| the webhook: verifies the hub\'s signature, saves `token \u2194 Ambasada user id` in `ambasada.store` | `app/api/ambasada/webhook/route.ts` (Next), `api/ambasada-webhook.ts` (spa, worker) |\n| `notifyUser(app, userId, { \u2026 })`: push to one person if they turned notifications on | `lib/notifications.ts` |\n| the privacy page the scopes need | `app/(site)/privacy/page.tsx`, `public/privacy.html`, `web/privacy.html` |\n\nSend one when something the person waits for happens (their order is ready), never as marketing:\n\n```ts\nimport { notifyUser } from "../lib/notifications.ts";\n\nconst user = await ambasada().auth.user(req);            // signed in with Ambasada\nif (user) await notifyUser(ambasada(), user.id, {\n  notification_id: `order-${id}-ready`,                  // unique per message; repeats are dropped for 24 h\n  title: "Your translation is ready",                    // \u2264 40 characters\n  body: "Tap to read it.",                               // \u2264 140\n  url: `/orders/${id}`,                                  // a path on your site: where the tap opens\n});\n```\n\nPeople turn notifications on in the app (the app asks; the page can ask too with\n`notifications.request()` from `@ambasada/miniapp`, from a button). The secret (`AMBASADA_APP_SECRET`) is\ninjected by `ambasada deploy`; never put it in the browser.\n\n## Signed in without a consent screen\n\nInside the Ambasada app the page signs in silently: `auth.signIn()` from `@ambasada/miniapp` gets a short\ntoken from the app and POSTs it to `/api/auth/shell`, which sets the same session as "Sign in with\nAmbasada". Server code doesn\'t change: `currentUser()` / `ambasada().auth.user(req)` work either way.\nOn the web, the button and consent screen stay. Silent sign-in needs the app to be Verified; until then\n`signIn()` resolves `null` and the button shows.\n\n## Try it locally\n\n`npx ambasada dev` plays the hub (with the mini app on): when your app starts it sends a signed `ping` and\n`notifications_enabled` to your webhook (the token lands in the store as\n`ambasada/notifications/user_fake_visitor`), and its `/api/apps/notify` accepts pushes for that token\n(they show in the terminal). Open `http://localhost:3000/app?ambasada_shell=mock` (your entry) to pretend to be\ninside the app: the fake shell signs you in silently as "Fake Visitor".\n', ".claude/skills/ambasada-product/reference/stack.md": '# The stack: Next.js on Cloudflare\n\nEvery Ambasada app is one Cloudflare Worker. The default template builds it from **Next.js 16.4**\nwith **@opennextjs/cloudflare 1.20** (the OpenNext adapter) and the `nodejs_compat` flag. You write a\nnormal Next.js App Router app; `ambasada deploy` turns it into a Worker.\n\n## Folder layout (template `next`)\n\n```\nmy-app/\n  app/layout.tsx               <html>, the Ambasada look (@ambasada/ui) and globals.css\n  app/(site)/layout.tsx        the site\'s header (app/account.tsx) around its pages; (site) is not in the URL\n  app/(site)/page.tsx          the landing page\n  app/notes.tsx                the notes example (a client component calling app/api/notes)\n  app/api/notes/route.ts       rows in env.DB, the list cached in env.KV\n  app/api/files/route.ts       uploads to env.FILES; app/files/[...key]/route.ts serves them\n  app/api/auth/*/route.ts      Sign in with Ambasada: login, callback, logout, me, shell (silent, in the app)\n  app/api/ambasada/webhook/    the Ambasada app\'s events: who turned notifications on (reference/mini-app.md)\n  app/account.tsx              the header: "Sign in with Ambasada", or the person\'s name and avatar\n  app/(site)/privacy/page.tsx  what you keep about people (the mini app\'s privacy_url)\n  app/(site)/room/             the live room demo\n  app/app/                     the mini app, once on (`ambasada miniapp enable`): its layout, page and in-app.tsx\n  lib/ambasada.ts              the Ambasada client for server code (reads the Worker env)\n  lib/notifications.ts         notifyUser(): a push to one person who turned notifications on\n  lib/db.ts, kv.ts, files.ts   env.DB, env.KV, env.FILES (reference/storage.md); lib/bindings.ts reaches them\n  db/migrations/               the database\'s tables, one .sql file per change\n  src/realtime/                the live room (a Durable Object) and its React hook\n  ambasada.config.ts           app id, name, one-line description, product URL, `miniapp` (optional)\n  wrangler.jsonc               Worker settings (nodejs_compat, assets) and the bindings DB, KV, FILES, ROOMS\n  worker.ts                    the Worker entry: live rooms\' WebSockets, then the Next.js app\n  open-next.config.ts          OpenNext settings; leave as is\n  .env                         secrets for local runs (never commit, never send to the browser)\n  .ambasada/project.json       the template and devkit version (`ambasada upgrade` reads it); commit it\n  .claude/skills/              this skill\n```\n\nOne more endpoint = one more `app/api/<name>/route.ts`. Data it keeps goes in `env.DB` (a migration in\n`db/migrations/`), `env.KV` or `env.FILES` ([storage.md](storage.md)).\n\n## Using the client\n\nServer code only (route handlers, server components, server actions):\n\n```ts\n// app/api/hello/route.ts\nimport { ambasada } from "../../../lib/ambasada.ts";\n\nexport async function GET(req: Request) {\n  const user = await ambasada().auth.user(req);\n  return Response.json({ hello: user?.name ?? "stranger" });\n}\n```\n\n`lib/ambasada.ts` creates one client per Worker instance with `createAmbasada({ env })` from `@ambasada/sdk`,\nwhere `env` comes from `getCloudflareContext()` (deployed); under `next dev` the SDK reads `process.env`.\nIt reads `AMBASADA_API_KEY` and `AMBASADA_API_URL` (default https://api.ambasada.dev). The client has `auth`\n(below), `apps` (notifications, [mini-app.md](mini-app.md)), `store` and `files`.\n\n## Who is signed in\n\nEvery hosted app gets **Sign in with Ambasada** (Ambasada ID) for free: no keys, no settings.\nThe template\'s header already has the button. In server code:\n\n```ts\nimport { currentUser } from "../lib/ambasada.ts";\nimport { bindings } from "../lib/bindings.ts";\nimport { run } from "../lib/db.ts";\n\nconst user = await currentUser(); // null, or { id, name, avatar_url, builder, pass, member_since, \u2026 }\nif (!user) redirect("/api/auth/login?returnTo=/orders");\nawait run(bindings().DB, "INSERT INTO orders (user_id, item) VALUES (?, ?)", user.id, item); // key per-person data by user.id\n```\n\nIn a route handler, `ambasada().auth.user(req)` does the same. Client components fetch `/api/auth/me`.\nAsk for the email only if you need it: `/api/auth/login` calls `auth.login(req, { email: true })`.\nDon\'t build your own login or accounts table, and don\'t add Clerk, Auth.js or Supabase Auth.\n\n## Next.js: allowed and banned\n\nAllowed, and enough for any product here:\n\n- pages and layouts (`app/**/page.tsx`, `layout.tsx`), server components, client components (`"use client"`)\n- route handlers (`app/api/**/route.ts`), server actions (`"use server"`)\n- `fetch` to any HTTPS API, `next/link`, `next/font`, plain CSS / CSS modules / Tailwind\n\nBanned (they fail on Workers or break the deploy):\n\n| Don\'t | Do instead |\n|---|---|\n| `next/image` with the default loader | `<img>`, or `images: { unoptimized: true }` in `next.config.ts` |\n| ISR, `export const revalidate = \u2026`, `revalidatePath`, `unstable_cache` | render on each request (`export const dynamic = "force-dynamic"`), or cache results in `env.KV` |\n| `fs`, `child_process`, `sharp`, `bcrypt`, `sqlite3`, `puppeteer`, any native package | `fetch` an API (an LLM provider with your own key in a secret, for example) |\n| a custom server (`server.js`, Express inside Next) | route handlers |\n| `middleware.ts` / `proxy.ts`, `export const runtime = "edge"` | check inside the page or route handler; Next\'s default runtime is right |\n| Prisma, Drizzle with a database, Supabase, Firebase, Mongo, Redis | `env.DB` (SQLite), `env.KV`, `env.FILES` ([storage.md](storage.md)) |\n| writing files at runtime, global variables as storage | `env.DB`, `env.KV`, `env.FILES` or a Durable Object (each request can run on a different machine) |\n\nKeep the bundle small: the Worker limit is 10 MB compressed. Big UI kits and icon packs are the usual cause.\n\n## Where data lives\n\nThe app has its own SQLite database (`env.DB`), key-value (`env.KV`), file storage (`env.FILES`, public at\n`/files/<key>`) and Durable Objects for live state, created at the first deploy. Which one fits, the migrations\nworkflow and copy-paste patterns: [storage.md](storage.md).\n\nAlso there, for small things: `ambasada.store` (JSON, 1 MB for the whole app: settings, not user data) and\n`ambasada.files.put(\u2026)` \u2192 `{ url }` (platform-hosted files that expire).\n\n## Secrets\n\n- Local: `.env` in the project (Cloudflare\'s `.dev.vars` works too). The template writes it with test\n  values for `ambasada dev`. Both are in `.gitignore`; keep them there.\n- Deployed: `ambasada deploy` injects `AMBASADA_API_KEY`, `AMBASADA_API_URL`, the Sign in with Ambasada\n  credentials (`AMBASADA_AUTH_*`) and the mini-app secret (`AMBASADA_APP_SECRET`, with `AMBASADA_HUB_URL`\n  and `AMBASADA_APP_ORIGIN`) for you. With `--own`, set them yourself: `npx wrangler secret put AMBASADA_API_KEY`.\n- Your app\'s own URL (links in emails, notifications, answers): `appOrigin()` in `lib/ambasada.ts`, from\n  `AMBASADA_APP_ORIGIN` (the deploy and `ambasada dev` set it), not `req.url`: a call the platform forwards to your\n  app may come without its Host.\n- Other services\' keys (an OpenAI key, say): `.env` locally, `npx ambasada env set OPENAI_API_KEY \u2026` online;\n  read on the server only. `ambasada deploy` builds without `.env*`: nothing in them reaches the Worker.\n- Anything named `NEXT_PUBLIC_*` (`VITE_*` in the spa) is copied into the browser. Never put a key there. From `.env`\n  they work under `ambasada dev` only; a public value the live page needs goes in the code.\n- Never paste a key into a page, a client component, a prompt for a no-code builder, or a commit.\n\n## Variants\n\n- `spa`: Vite + React with `@cloudflare/vite-plugin`, for code exported from Lovable or Bolt. The\n  `api/` endpoints are small fetch handlers; the React app calls them with `fetch("/api/\u2026")`.\n- `worker`: `web/` (plain HTML/CSS) plus `api/*.ts` fetch handlers. Best when the app is a page or two.\n\nThe rules on this page (state, secrets, no native packages) apply to all three.\n', ".claude/skills/ambasada-product/reference/storage.md": '# Data, files and realtime\n\nEvery app on ambasada.dev gets a real database, key-value, file storage and Durable Objects. They are created\nat the first `ambasada deploy` and bound to the Worker on every deploy; nothing to sign up for or configure.\nLocally (`ambasada dev`, `wrangler dev`, `vite`) wrangler runs the same things from `.wrangler/state`.\n\n| Need | Use | Not |\n|---|---|---|\n| anything with rows: users\' data, orders, posts, scores, anything you query, sort or join | `env.DB` (SQLite, D1) | KV, files, `ambasada.store` |\n| sessions, caches of slow results, feature flags, "seen this already" | `env.KV` | a table you scan |\n| uploads, images, audio, PDFs, generated files | `env.FILES` (R2), public at `/files/<key>` | base64 in the database |\n| state several people see change live: chat, presence, a shared board, a game table, live counters, a queue, rate limits, one thing per entity | a Durable Object (`env.ROOMS` in the templates) | polling the database |\n| an AI agent with memory, schedules and live state per user or task | the Agents SDK (`examples/agent/`) | a cron that rereads everything |\n| a few small settings for a tiny app | `ambasada.store` (1 MB per app) | user data of any size |\n\nQuotas per app: database 500 MB, KV 1 GB, files 5 GB. A database over its quota stops the next deploy.\n\n## `env.DB`: SQLite\n\nSchema lives in `db/migrations/`, one file per change, applied in name order, never edited once applied:\n\n```sql\n-- db/migrations/0002_orders.sql\nCREATE TABLE orders (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  user_id TEXT NOT NULL,\n  item TEXT NOT NULL,\n  paid INTEGER NOT NULL DEFAULT 0,\n  created_at INTEGER NOT NULL\n);\nCREATE INDEX orders_user ON orders (user_id, created_at);\n```\n\n```sh\nnpx wrangler d1 migrations apply DB --local   # the local database, for ambasada dev\nnpx ambasada db migrate                       # the app\'s database online (run before or right after deploying)\nnpx ambasada db shell "SELECT * FROM orders LIMIT 5"\n```\n\nQuery with `lib/db.ts` (SQL with `?` placeholders, typed rows, no ORM):\n\n```ts\nimport { all, batch, first, run } from "../lib/db.ts";\n\ntype Order = { id: number; user_id: string; item: string; paid: number; created_at: number };\nconst mine = await all<Order>(env.DB, "SELECT * FROM orders WHERE user_id = ? ORDER BY created_at DESC LIMIT 50", user.id);\nconst one = await first<Order>(env.DB, "SELECT * FROM orders WHERE id = ?", id);\nconst { lastRowId } = await run(env.DB, "INSERT INTO orders (user_id, item, created_at) VALUES (?, ?, ?)", user.id, item, Date.now());\nawait batch(env.DB, [["UPDATE stock SET n = n - 1 WHERE item = ?", item], ["UPDATE orders SET paid = 1 WHERE id = ?", id]]); // all or nothing\n```\n\nIn Next.js route handlers and server components, the bindings come from `bindings()` (`lib/bindings.ts`):\n`const { DB } = bindings();`. In the spa and worker templates, handlers get `env`.\n\nRules: always placeholders, never string-built SQL. Key per-person rows by the Ambasada user id\n(`auth.user(req).id`). Add an index for every `WHERE` you run often. Times as `Date.now()` integers.\n\n## `env.KV`: sessions, caches, flags\n\nReads are fast everywhere; a write shows up everywhere within about a minute; one write per second per key.\n\n```ts\nimport { cached, getJson, putJson } from "../lib/kv.ts";\n\nawait putJson(env.KV, `session:${id}`, { userId }, { ttl: 60 * 60 * 24 });\nconst session = await getJson<{ userId: string }>(env.KV, `session:${id}`);\nconst stats = await cached(env.KV, "home:stats", 300, () => computeStats(env)); // recompute at most every 5 min\n```\n\nNot for counters, balances or anything two people write at once: use `env.DB` (a transaction) or a Durable Object.\n\n## `env.FILES`: uploads and generated files\n\n```ts\nimport { serveFile, upload } from "../lib/files.ts";\n\n// POST /api/files: a signed-in person uploads (the templates\' api/files.ts)\nconst { key, url } = await upload(env.FILES, req.body, { contentType: req.headers.get("content-type") ?? undefined, folder: `u/${user.id}` });\nawait run(env.DB, "INSERT INTO photos (user_id, file_key) VALUES (?, ?)", user.id, key); // keep the key, not the bytes\n\n// GET /files/*: already wired in every template, with ETag, ranges and cache headers\nreturn serveFile(env.FILES, req);\n```\n\n`url` is `/files/<key>` on the app (`https://<slug>.ambasada.dev/files/<key>`): public to anyone with the link.\nPrivate files: store them under a key nobody can guess and serve them from your own route that checks\n`auth.user(req)` first, instead of `/files/*`. `npx ambasada files list | put | url | delete` from the terminal.\n\n## Durable Objects: realtime and per-entity state\n\nA Durable Object is one tiny server per id (a room, a document, a match, a user) with its own SQLite, that\nevery request for that id reaches. Use one whenever people must see each other\'s changes live, or one thing\nmust never be updated by two requests at once. The templates ship `src/realtime/room.ts` (`env.ROOMS`):\n\n```ts\n// the Worker: /api/rooms/<id>/ws \u2192 the room\nconst room = /^\\/api\\/rooms\\/([^/]+)\\/ws$/.exec(pathname);\nif (room) return env.ROOMS.getByName(decodeURIComponent(room[1]!)).fetch(req);\n```\n\n```ts\n// the room (shortened): WebSocket hibernation, broadcast, its own SQLite\nexport class Room extends DurableObject<unknown> {\n  async fetch(req: Request) {\n    const { 0: client, 1: server } = new WebSocketPair();\n    this.ctx.acceptWebSocket(server);              // hibernation: no cost while nobody talks\n    server.serializeAttachment({ name: "guest" }); // per-connection data that survives hibernation\n    return new Response(null, { status: 101, webSocket: client });\n  }\n  async webSocketMessage(ws: WebSocket, data: string | ArrayBuffer) {\n    this.ctx.storage.sql.exec("INSERT INTO messages (text, at) VALUES (?, ?)", String(data), Date.now());\n    for (const peer of this.ctx.getWebSockets()) peer.send(String(data)); // everyone in the room\n  }\n}\n```\n\n```tsx\n// the browser (React): src/realtime/use-room.ts\nconst { messages, online, send, status } = useRoom(roomId, { name: user.name });\n```\n\nA new class needs a binding and a migration in `wrangler.jsonc` (new tags go at the end; never edit or remove one\nthat was deployed; to drop a class add `{ "tag": "v3", "deleted_classes": ["Old"] }`):\n\n```jsonc\n"durable_objects": { "bindings": [{ "name": "ROOMS", "class_name": "Room" }, { "name": "BOARDS", "class_name": "Board" }] },\n"migrations": [{ "tag": "v1", "new_sqlite_classes": ["Room"] }, { "tag": "v2", "new_sqlite_classes": ["Board"] }]\n```\n\nExport the class from the Worker\'s entry (`src/worker.ts`; spa `worker/index.ts`; next `worker.ts`).\nOther shapes, same pattern: presence (who is online), a live counter (`UPDATE \u2026 RETURNING`, then broadcast), a\nper-user rate limit (`getByName(user.id)`), a job queue (`this.ctx.storage.setAlarm`). A Durable Object belongs\nto this app; other apps can\'t reach it. Under `next dev` they don\'t run: use `npm run preview` (workerd).\n\n## Agents (Agents SDK)\n\nFor agentic products (an assistant per user, a research task that runs for minutes, a bot that follows up),\nuse the Cloudflare Agents SDK: `examples/agent/` in the template (`npm i agents`, four lines to wire). An agent\nis a Durable Object with live state synced to clients (`setState`, `useAgent` in React), `this.sql`,\n`this.schedule(\u2026)` and WebSockets. One agent per user or task: `/agents/agent-example/<user id>`.\n\n## Don\'t\n\n- Poll (`setInterval(fetch\u2026)`) for what others changed: a Durable Object + WebSocket pushes it.\n- Put files or base64 in the database or KV: `env.FILES`, and keep the key in a row.\n- Keep user data in `ambasada.store`: it is 1 MB for the whole app.\n- Keep state in module variables or global objects: every request may run on another machine.\n- Count, rank or move money in KV: use a SQL transaction (`batch`) or a Durable Object.\n- Build SQL by joining strings with user input: `?` placeholders.\n- Edit an applied migration: add the next file.\n- Add Prisma, Drizzle with Postgres, Supabase, Firebase, Mongo or Redis: everything above is already here.\n', ".claude/skills/ambasada-product/reference/upgrading.md": "# Upgrading a project\n\n`npx ambasada upgrade` does the mechanical part: every `@ambasada/*` dependency to the CLI's version, the\npackage manager, `.claude/skills/ambasada-*` re-synced (the project's own skills are left alone), the code\nchanges listed below as \"done by `upgrade`\", the `ambasada check` rules, and `.ambasada/project.json`\n(the template and devkit version). `npx ambasada upgrade --check` only reports.\n\nWhat is left is below, per version, for a coding agent. Do the steps for every version between the one in\n`.ambasada/project.json` (none: 0.7) and the current one, in order. After each, run the app with\n`npx ambasada dev` and the project's `typecheck` script.\n\n## 0.7 \u2192 0.8: the platform and the village split\n\n0.8 splits the devkit: `@ambasada/sdk` and `ambasada` are the platform (sign-in, notifications, storage,\nhosting); the Hack A Ton economy (TON, checkout, offerings, the agent) is the add-on `@ambasada/village`.\n\nDone by `upgrade`:\n\n- the village names (`village`, `createVillage`, `offering`, `defineCompany`, `isVillageError`, the receipt and\n  webhook helpers, their types) import from `@ambasada/village`; in a village app `createAmbasada` became\n  `createVillage` and `DEFAULT_API_URL` became `DEFAULT_VILLAGE_API_URL` (their 0.7 meaning);\n- `@ambasada/village` added to `package.json` when the app has `offerings.ts` or an `idea`;\n- `.env` / `.dev.vars`: `AMBASADA_API_URL=https://hackaton.ambasada.id` became `https://api.ambasada.dev` plus\n  `AMBASADA_VILLAGE_API_URL=https://hackaton.ambasada.id`;\n- the `ambasada-payments` skill replaced by `ambasada-village`.\n\nFor the agent:\n\n1. **Platform code uses the platform client.** Files that only sign people in, send notifications or use\n   `store`/`files` can import `createAmbasada` / `ambasada` from `@ambasada/sdk` instead of the village client.\n   Leave files that sell, check receipts or call `llm` on the village client.\n2. **Config.** `ambasada.config.ts` may stay `defineCompany({ id, name, idea, \u2026 })`; the 0.8 form is\n   `defineCompany(defineApp({ id, name, description, product }), { idea, offerings, agent })` with\n   `defineApp` from `@ambasada/sdk`. Add a one-line `description` (the manifest's subtitle).\n3. **CLI calls.** In scripts, READMEs and `package.json`: `ambasada wallet|ledger|offerings|market|steer|webhook|links`\n   \u2192 `ambasada village \u2026`, `ambasada logs --agent` \u2192 `ambasada village logs --agent`, `ambasada dev buy` \u2192\n   `ambasada village dev buy`. The old spellings still work through 1.x with a warning.\n4. **Pages that load pay.js** from `AMBASADA_API_URL` should use the village client's `apiUrl` (or\n   `AMBASADA_VILLAGE_API_URL`): `AMBASADA_API_URL` is the platform's from 0.8.\n5. **Login.** The CLI's login moved from `~/.config/village` to `~/.config/ambasada` (moved on first use);\n   nothing to do unless a script reads that file.\n6. Run `npx ambasada check`, `npx ambasada dev` and the typecheck; deploy when they pass.\n", "README.md": "# My App\n\nAn app on Ambasada, one bare Cloudflare Worker (template `worker`): sign-in with Ambasada ID, a database,\nkey-value, files and live rooms; a mini app inside the Ambasada app if you want one. Everything here is a default;\nchange anything.\n\n```\nambasada.config.ts          id, name, one-line description, where the app runs\nsrc/worker.ts               the Worker: /api/<name> \u2192 api/<name>.ts, / (landing page), the rest from web/\napi/auth.ts                 Sign in with Ambasada (login, callback, logout, me, shell)\napi/ambasada-webhook.ts     the Ambasada app's events (notifications on/off); lib/notifications.ts sends pushes\napi/notes.ts, api/files.ts  env.DB + env.KV, uploads to env.FILES\nlib/ambasada.ts             the SDK client from the Worker's env\nlib/db.ts, kv.ts, files.ts  env.DB, env.KV, env.FILES; db/migrations/ the tables\nsrc/realtime/room.ts        the live room (a Durable Object); web/room.html is the demo\nweb/                        the landing page, static assets\nwrangler.jsonc              one Worker + assets, nodejs_compat, the storage bindings\n.claude/skills/             docs your coding agent reads (ambasada-product)\n```\n\n## 1. Run it (2 min)\n\nNeeds Node \u2265 22.\n\n```sh\nnpm install\nnpm run dev                # `ambasada dev`: the mock Ambasada API on :8788 + `wrangler dev` on http://localhost:3000\n```\n\nOpen http://localhost:3000: add a note, sign in (the mock signs you in as \"Fake Visitor\"), open /room in two tabs.\nhttp://127.0.0.1:8788 is the mock's page (sign-ins, notifications, the store). `ambasada dev` points your app at the\nmock whatever `.env` says.\n\n## 2. Make it yours\n\n- `ambasada.config.ts`: name and description.\n- A new endpoint: `api/<name>.ts` (and a line in `src/worker.ts`). Data goes in `env.DB` (a migration in `db/migrations/`), `env.KV` or `env.FILES`.\n- Ask your coding agent: it has the ambasada-product skill (stack, storage, sign-in, mini app, deploy).\n\nNo framework, no build step: `wrangler` bundles `src/worker.ts`, and `web/` is served as is.\n\n## 3. Go live (1 min)\n\n```sh\nnpx ambasada login         # Ambasada ID, or a project key from https://developer.ambasada.dev\nnpx ambasada deploy        # build, smoke test, host at https://my-app.ambasada.dev\nnpx ambasada db migrate    # db/migrations \u2192 the app's database\nnpx ambasada logs          # the last deploy and recent errors\n```\n\nSign-in, notifications and the storage are set up by the deploy; nothing to configure. Your own secrets:\n`npx ambasada env set NAME value`. Hosting elsewhere: `npx wrangler deploy`, then `npx ambasada link https://\u2026`.\n\n**Sign in with Ambasada**: the header's button signs people in with their Ambasada ID; on the server,\n`ambasada(\u2026).auth.user(req)` gives `{ id, name, avatar_url, builder, pass }` or null.\n\n## Storage and realtime\n\nEvery app gets these, provisioned at the first `ambasada deploy`; locally wrangler keeps them in `.wrangler/state`.\n\n| Binding | For | Here |\n|---|---|---|\n| `env.DB` | SQLite: anything relational | `lib/db.ts`, tables in `db/migrations/`, example `api/notes.ts` |\n| `env.KV` | sessions, caches, flags | `lib/kv.ts` (the notes cache) |\n| `env.FILES` | uploads, generated files; public at `/files/<key>` | `lib/files.ts`, upload `api/files.ts` |\n| `env.ROOMS` | live state shared between people (Durable Object) | `src/realtime/room.ts`, demo at `/room` |\n\n```sh\nnpx wrangler d1 migrations apply DB --local   # db/migrations \u2192 the local database (ambasada dev)\nnpx ambasada db migrate                       # \u2026 \u2192 the app's database online\nnpx ambasada db shell \"SELECT * FROM notes\"   # or `ambasada db shell` for a prompt\nnpx ambasada kv list | get <key> | put <key> <value> | delete <key>\nnpx ambasada files put <file> | list | url <key> | delete <key>\n```\n\nOptional: an agent with the Agents SDK in `examples/agent/` (its README: `npm i agents` and four lines to wire it).\n\n## In the Ambasada app (optional)\n\nOff by default: this is a website. `npx ambasada miniapp enable` adds a mini app at `/app` (`--entry /` for the whole\nsite): `miniapp: { entry: \"/app\" }` in `ambasada.config.ts`, web/app.html and web/in-app.js, a placeholder\n`web/icon.png`, and the manifest `ambasada dev` and `deploy` serve at `/.well-known/ambasada.json`. Then\n`http://localhost:3000/app?ambasada_shell=mock` pretends to be inside the Ambasada app. The ambasada-product skill:\nreference/mini-app.md.\n\n## Rules worth knowing\n\n- State lives in `env.DB`, `env.KV`, `env.FILES` or a Durable Object, never in module variables: a Worker has many instances.\n- Secrets only in `.env` locally and `ambasada env set` online; never in the code or `wrangler.jsonc` vars.\n- `npx ambasada check` runs the checks (https, no redirects, speed; the mini-app rules when it is on); `npx ambasada upgrade` after a new devkit.\n\nFor the Hack A Ton: `npx ambasada add village` (the add-on).\n\nBuilt by [CENTYSO](https://centyso.com) for [Ambasada](https://ambasada.id).\n", "ambasada.config.ts": 'import { defineApp } from "@ambasada/sdk";\n\nexport default defineApp({\n  id: "my-app",\n  name: "My App",\n  // One line about the app (the subtitle of its Ambasada mini app, if you add one: `ambasada miniapp enable`).\n  description: "Notes, a live room and sign-in",\n  // Where the app runs. `ambasada dev` serves it on http://localhost:3000; hosted, it is https://my-app.ambasada.dev\n  // (`ambasada deploy` sets it; `ambasada link https://\u2026` when you host elsewhere).\n  product: { url: "http://localhost:3000" },\n});\n', "api/ambasada-webhook.ts": '// POST /api/ambasada/webhook: the Ambasada app\'s events for this mini app (docs/MINI-APPS.md \xA77), signed with\n// AMBASADA_APP_SECRET (injected on ambasada.dev; `ambasada dev` plays the hub and sends a ping and\n// notifications_enabled here when it starts). The manifest points here: notifications.webhook.\nimport { isAmbasadaError } from "@ambasada/sdk";\nimport { ambasada, type Env } from "../lib/ambasada.ts";\nimport { forgetToken, saveToken } from "../lib/notifications.ts";\n\nexport default async function appWebhook(req: Request, env: Env): Promise<Response> {\n  const app = ambasada(env);\n  try {\n    const event = await app.apps.verifyWebhook(req); // throws if forged or stale\n    switch (event.event) {\n      case "notifications_enabled":\n      case "app_added":\n        if (event.token) await saveToken(app, event.user, event.token);\n        break;\n      case "notifications_disabled":\n      case "app_removed":\n        await forgetToken(app, event.user);\n        break;\n      case "ping": // `ambasada check` and the registry: answer 200\n        break;\n    }\n    return new Response("ok");\n  } catch (error) {\n    if (isAmbasadaError(error)) return error.toResponse();\n    throw error;\n  }\n}\n', "api/auth.ts": '// Sign in with Ambasada (Ambasada ID, OAuth + PKCE): zero setup. On https://<slug>.ambasada.dev the deploy\n// injects AMBASADA_AUTH_*; under `ambasada dev` the mock signs you in as a fake visitor.\n//   GET /api/auth/login?returnTo=/   \u2192 the Ambasada ID consent screen\n//   GET /api/auth/callback           \u2192 back from it: sets an HttpOnly session cookie, redirects to returnTo\n//   GET /api/auth/logout             \u2192 clears it\n//   GET /api/auth/me                 \u2192 { user } (null when signed out), for the browser\n//   POST /api/auth/shell { token }   \u2192 silent sign-in inside the Ambasada app: the same session, no consent screen\n//                                      (the page calls `auth.signIn()` from @ambasada/miniapp)\n// On the server: `await ambasada(env).auth.user(req)` \u2192 { id, name, avatar_url, builder, pass, \u2026 } or null.\nimport { isAmbasadaError } from "@ambasada/sdk";\nimport { ambasada, type Env } from "../lib/ambasada.ts";\n\nexport default async function auth(req: Request, env: Env): Promise<Response> {\n  const { auth } = ambasada(env);\n  try {\n    switch (new URL(req.url).pathname.replace(/\\/+$/, "")) {\n      case "/api/auth/login":\n        return await auth.login(req);\n      case "/api/auth/callback":\n        return await auth.callback(req);\n      case "/api/auth/logout":\n        return auth.logout(req);\n      case "/api/auth/shell":\n        return await auth.shell(req);\n      case "/api/auth/me": {\n        // Under `ambasada dev` the page needs the mock issuer for its fake shell (?ambasada_shell=mock).\n        const devIssuer = env.AMBASADA_AUTH_ISSUER?.startsWith("http://") ? env.AMBASADA_AUTH_ISSUER : undefined;\n        return Response.json({ user: await auth.user(req), configured: auth.configured, ...(devIssuer ? { dev_issuer: devIssuer } : {}) }, { headers: { "cache-control": "no-store" } });\n      }\n    }\n    return Response.json({ error: { code: "NOT_FOUND", message: "no such route" } }, { status: 404 });\n  } catch (error) {\n    if (isAmbasadaError(error)) return error.toResponse();\n    throw error;\n  }\n}\n', "api/files.ts": '// POST /api/files (raw body, content-type): a signed-in person uploads a file to env.FILES (lib/files.ts)\n// \u2192 { key, url }; the url (/files/<key>) is public and served by the /files/* route.\nimport { ambasada, type Env } from "../lib/ambasada.ts";\nimport { upload } from "../lib/files.ts";\n\nconst MAX_BYTES = 10 * 1024 * 1024;\n\nexport default async function files(req: Request, env: Env): Promise<Response> {\n  if (req.method !== "POST") return Response.json({ error: { code: "INVALID_REQUEST", message: "POST the file" } }, { status: 405 });\n  const user = await ambasada(env).auth.user(req);\n  if (!user) return Response.json({ error: { code: "UNAUTHORIZED", message: "sign in to upload" } }, { status: 401 });\n  const size = Number(req.headers.get("content-length") ?? 0);\n  if (!size || size > MAX_BYTES) return Response.json({ error: { code: "INVALID_REQUEST", message: "send a file up to 10 MB with a content-length" } }, { status: 413 });\n  const stored = await upload(env.FILES, req.body, { contentType: req.headers.get("content-type") ?? undefined, folder: `u/${user.id}` });\n  return Response.json(stored, { status: 201 });\n}\n', "api/notes.ts": '// GET /api/notes: the latest notes from env.DB (lib/db.ts), cached a minute in env.KV (lib/kv.ts).\n// POST /api/notes { text }: adds one. The table is db/migrations/0001_init.sql.\nimport type { Env } from "../lib/ambasada.ts";\nimport { all, run } from "../lib/db.ts";\nimport { cached, remove } from "../lib/kv.ts";\n\ntype Note = { id: number; text: string; created_at: number };\n\nexport default async function notes(req: Request, env: Env): Promise<Response> {\n  if (req.method === "POST") {\n    const { text } = (await req.json().catch(() => ({}))) as { text?: unknown };\n    if (typeof text !== "string" || !text.trim() || text.length > 500) {\n      return Response.json({ error: { code: "INVALID_REQUEST", message: "body must be { text }, 1 to 500 characters" } }, { status: 400 });\n    }\n    const { lastRowId } = await run(env.DB, "INSERT INTO notes (text, created_at) VALUES (?, ?)", text.trim(), Date.now());\n    await remove(env.KV, "notes:latest");\n    return Response.json({ id: lastRowId }, { status: 201 });\n  }\n  const latest = await cached(env.KV, "notes:latest", 60, () => all<Note>(env.DB, "SELECT id, text, created_at FROM notes ORDER BY id DESC LIMIT 20"));\n  return Response.json({ notes: latest });\n}\n', "db/migrations/0001_init.sql": "-- The app's first table. Add the next change as db/migrations/0002_<what>.sql (never edit an applied file), then:\n--   npx wrangler d1 migrations apply DB --local   (ambasada dev)\n--   npx ambasada db migrate                       (online)\nCREATE TABLE notes (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  text TEXT NOT NULL,\n  created_at INTEGER NOT NULL\n);\nCREATE INDEX notes_created ON notes (created_at);\n", "examples/agent/README.md": '# Agent (optional): the Cloudflare Agents SDK\n\nFor agentic products: an agent per user, document or task, with live state, its own SQL, schedules and\nWebSockets (`agent.ts`). It is a Durable Object, so it runs on ambasada.dev like the live rooms. To turn it on:\n\n1. `npm i agents`\n2. `wrangler.jsonc`: add the binding and a migration after the existing ones:\n   ```jsonc\n   "durable_objects": { "bindings": [{ "name": "ROOMS", "class_name": "Room" }, { "name": "AgentExample", "class_name": "AgentExample" }] },\n   "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Room"] }, { "tag": "v2", "new_sqlite_classes": ["AgentExample"] }]\n   ```\n3. In the Worker entry (`src/worker.ts`; spa: `worker/index.ts`; next: `worker.ts`):\n   ```ts\n   export { AgentExample } from "../examples/agent/agent.ts"; // next: "./examples/agent/agent.ts"\n   import { routeAgents } from "../examples/agent/agent.ts";\n   // first thing in fetch():\n   const agent = await routeAgents(req, env as unknown as Record<string, unknown>);\n   if (agent) return agent;\n   ```\n4. In the browser (React): `useAgent({ agent: "agent-example", name: user.id, onStateUpdate: setState })` from\n   `agents/react`; `agent.send("hello")`. Plain fetch: `GET /agents/agent-example/<name>`.\n\n`ambasada deploy` sends the new class and its migration; nothing else to set up. Docs: https://developers.cloudflare.com/agents/\n', "examples/agent/agent.ts": '/**\n * Optional: an agent with the Cloudflare Agents SDK (`agents`), for agentic products. An agent is a Durable\n * Object with superpowers: state synced live to every connected client (`setState`), its own SQL (`this.sql`),\n * scheduled work (`this.schedule`), WebSockets and HTTP. One instance per name: per user, per document, per task.\n * Not wired in by default: examples/agent/README.md has the four steps.\n */\nimport { Agent, routeAgentRequest, type Connection, type WSMessage } from "agents";\n\ntype State = { notes: number; lastNote: string | null };\n\nexport class AgentExample extends Agent<Cloudflare.Env, State> {\n  initialState: State = { notes: 0, lastNote: null };\n\n  async onStart() {\n    this.sql`CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY AUTOINCREMENT, text TEXT NOT NULL, at INTEGER NOT NULL)`;\n  }\n\n  // GET /agents/agent-example/<name>: what this agent knows.\n  async onRequest(_req: Request): Promise<Response> {\n    const notes = this.sql<{ id: number; text: string; at: number }>`SELECT id, text, at FROM notes ORDER BY id DESC LIMIT 20`;\n    return Response.json({ state: this.state, notes });\n  }\n\n  // A client (useAgent in the browser) sent a message: remember it, sync the new state to every client,\n  // and come back to it in a minute (call an LLM here, send a notification, \u2026).\n  async onMessage(connection: Connection, message: WSMessage) {\n    const text = String(message).slice(0, 2000);\n    this.sql`INSERT INTO notes (text, at) VALUES (${text}, ${Date.now()})`;\n    this.setState({ notes: this.state.notes + 1, lastNote: text });\n    await this.schedule(60, "followUp", { text });\n    connection.send(JSON.stringify({ ok: true }));\n  }\n\n  async followUp(payload: { text: string }) {\n    console.log(`a minute ago someone wrote: ${payload.text}`);\n  }\n}\n\n/** In your Worker\'s fetch, before your own routes: answers /agents/<agent>/<name> (HTTP and WebSocket). */\nexport const routeAgents = (req: Request, env: Record<string, unknown>) => routeAgentRequest(req, env);\n', gitignore: "node_modules/\n.env*\n.dev.vars*\n.wrangler/\ndist/\n.DS_Store\n# build output of `ambasada deploy`; project.json (template, devkit version) is kept\n.ambasada/*\n!.ambasada/project.json\n", "lib/ambasada.ts": "import { createAmbasada, type Ambasada } from \"@ambasada/sdk\";\nimport type { Room } from \"../src/realtime/room.ts\";\n\n/** The Worker's env: `.env` locally (`ambasada dev` points it at the mock), secrets injected at deploy. */\nexport interface Env {\n  ASSETS: Fetcher;\n  /** The app's SQLite database (lib/db.ts), key-value (lib/kv.ts), files (lib/files.ts) and live rooms (src/realtime/room.ts). */\n  DB: D1Database;\n  KV: KVNamespace;\n  FILES: R2Bucket;\n  ROOMS: DurableObjectNamespace<Room>;\n  /** On ambasada.dev: a service binding to the API, which the SDK uses for its calls (set by `ambasada deploy`). */\n  AMBASADA_API?: Fetcher;\n  AMBASADA_API_KEY?: string;\n  /** Set by `ambasada deploy` and `ambasada dev`; the SDK defaults to https://api.ambasada.dev. */\n  AMBASADA_API_URL?: string;\n  AMBASADA_APP_ID?: string;\n  /** Sign in with Ambasada (api/auth.ts): set by `ambasada deploy` on ambasada.dev, and by `ambasada dev`. */\n  AMBASADA_AUTH_CLIENT_ID?: string;\n  AMBASADA_AUTH_CLIENT_SECRET?: string;\n  AMBASADA_AUTH_ISSUER?: string;\n  /** Mini-app notifications (api/ambasada-webhook.ts, lib/notifications.ts): set on ambasada.dev and by `ambasada dev`. */\n  AMBASADA_APP_SECRET?: string;\n  AMBASADA_HUB_URL?: string;\n  /** This app's origin, set by `ambasada deploy` and `ambasada dev`: use `appOrigin(env, req)`. */\n  AMBASADA_APP_ORIGIN?: string;\n}\n\n/**\n * This app's own origin (https://<slug>.ambasada.dev online, the dev server locally): AMBASADA_APP_ORIGIN, which\n * `ambasada deploy` and `ambasada dev` set, else the request's (a call the platform forwards may carry another host).\n */\nexport function appOrigin(env: Env, req: Request): string {\n  return env.AMBASADA_APP_ORIGIN ?? new URL(req.url).origin;\n}\n\nlet client: Ambasada | undefined;\n\n/** One client per isolate: it caches the API's signing keys. */\nexport function ambasada(env: Env): Ambasada {\n  return (client ??= createAmbasada({ env: env as unknown as Record<string, unknown> }));\n}\n", "lib/db.ts": '/**\n * env.DB: this app\'s SQLite database (Cloudflare D1). The tables come from db/migrations/*.sql:\n * `npx ambasada db migrate` online, `npx wrangler d1 migrations apply DB --local` for `ambasada dev`.\n * A tiny typed layer, no ORM: SQL with ? placeholders in, plain objects out.\n *\n *   const notes = await all<Note>(env.DB, "SELECT * FROM notes ORDER BY id DESC LIMIT ?", 20);\n *   const note = await first<Note>(env.DB, "SELECT * FROM notes WHERE id = ?", id);\n *   const { lastRowId } = await run(env.DB, "INSERT INTO notes (text) VALUES (?)", text);\n *   await batch(env.DB, [["UPDATE a SET n = n - 1 WHERE id = ?", 1], ["UPDATE b SET n = n + 1 WHERE id = ?", 2]]); // one transaction\n */\n\nexport type Param = string | number | boolean | null | ArrayBuffer;\n\n/** What this file needs from a D1 binding (env.DB satisfies it). */\nexport interface Database {\n  prepare(query: string): Statement;\n  batch(statements: Statement[]): Promise<unknown[]>;\n}\n\nexport interface Statement {\n  bind(...values: unknown[]): Statement;\n  all<T = Record<string, unknown>>(): Promise<{ results: T[] }>;\n  first<T = Record<string, unknown>>(): Promise<T | null>;\n  run(): Promise<{ meta: { changes: number; last_row_id: number } }>;\n}\n\nconst statement = (db: Database, query: string, params: Param[]) => db.prepare(query).bind(...params);\n\n/** Every row. */\nexport async function all<T = Record<string, unknown>>(db: Database, query: string, ...params: Param[]): Promise<T[]> {\n  return (await statement(db, query, params).all<T>()).results;\n}\n\n/** The first row, or null. */\nexport function first<T = Record<string, unknown>>(db: Database, query: string, ...params: Param[]): Promise<T | null> {\n  return statement(db, query, params).first<T>();\n}\n\n/** INSERT, UPDATE, DELETE: how many rows changed and the last inserted id. */\nexport async function run(db: Database, query: string, ...params: Param[]): Promise<{ changes: number; lastRowId: number }> {\n  const { meta } = await statement(db, query, params).run();\n  return { changes: meta.changes, lastRowId: meta.last_row_id };\n}\n\n/** Several statements in one transaction: all of them apply, or none. */\nexport async function batch(db: Database, statements: [query: string, ...params: Param[]][]): Promise<void> {\n  await db.batch(statements.map(([query, ...params]) => statement(db, query, params)));\n}\n', "lib/files.ts": '/**\n * env.FILES: this app\'s file storage (Cloudflare R2). Uploads and generated files; each one is public at\n * /files/<key> on the app\'s own address (the /files/* route calls serveFile). Don\'t keep files in the database.\n *\n *   const { key, url } = await upload(env.FILES, req.body, { contentType: "image/png" });   // url: /files/u/\u2026\n *   return serveFile(env.FILES, req);                                                        // GET /files/*\n *\n * Files are public to anyone with the URL: keep private documents behind your own route that checks who asks.\n * `npx ambasada files put|list|delete|url` manages them from the terminal.\n */\n\n/** What this file needs from an R2 binding (env.FILES satisfies it). */\nexport interface Bucket {\n  put(key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null, options?: { httpMetadata?: { contentType?: string } }): Promise<unknown>;\n  get(key: string, options?: { onlyIf?: Headers; range?: Headers }): Promise<StoredFile | null>;\n  delete(key: string): Promise<void>;\n}\n\nexport interface StoredFile {\n  httpEtag: string;\n  size: number;\n  httpMetadata?: { contentType?: string };\n  range?: { offset?: number; length?: number; suffix?: number };\n  body?: ReadableStream;\n}\n\nexport const FILES_PATH = "/files/";\n\n/** Stores `body` under a new random key (in `folder`) \u2192 `{ key, url }`, url relative to the app (/files/<key>). */\nexport async function upload(bucket: Bucket, body: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null, options: { contentType?: string; folder?: string } = {}): Promise<{ key: string; url: string }> {\n  const key = `${options.folder ?? "u"}/${crypto.randomUUID()}`;\n  await bucket.put(key, body, { httpMetadata: { contentType: options.contentType ?? "application/octet-stream" } });\n  return { key, url: fileUrl(key) };\n}\n\nexport const fileUrl = (key: string) => `${FILES_PATH}${key.split("/").map(encodeURIComponent).join("/")}`;\n\n/** GET/HEAD /files/<key>: the file with its type, an ETag (304 when unchanged), byte ranges, and a cache header. */\nexport async function serveFile(bucket: Bucket, req: Request): Promise<Response> {\n  if (req.method !== "GET" && req.method !== "HEAD") return new Response(null, { status: 405, headers: { allow: "GET, HEAD" } });\n  const path = new URL(req.url).pathname;\n  const key = decodeURIComponent(path.slice(path.indexOf(FILES_PATH) + FILES_PATH.length));\n  if (!key) return new Response("Not found", { status: 404 });\n  const file = await bucket.get(key, { onlyIf: req.headers, range: req.headers });\n  if (!file) return new Response("Not found", { status: 404 });\n  const headers = new Headers({ etag: file.httpEtag, "cache-control": "public, max-age=3600", "accept-ranges": "bytes" });\n  if (file.httpMetadata?.contentType) headers.set("content-type", file.httpMetadata.contentType);\n  if (!file.body) return new Response(null, { status: 304, headers }); // If-None-Match matched: nothing changed\n  const r = file.range;\n  if (r && req.headers.has("range")) {\n    const offset = r.suffix !== undefined ? file.size - r.suffix : (r.offset ?? 0);\n    const length = r.suffix ?? r.length ?? file.size - offset;\n    headers.set("content-range", `bytes ${offset}-${offset + length - 1}/${file.size}`);\n    headers.set("content-length", String(length));\n    return new Response(req.method === "HEAD" ? null : file.body, { status: 206, headers });\n  }\n  headers.set("content-length", String(file.size));\n  return new Response(req.method === "HEAD" ? null : file.body, { headers });\n}\n', "lib/kv.ts": '/**\n * env.KV: this app\'s key-value store (Cloudflare KV). Fast reads everywhere, writes visible within about a\n * minute, at most one write per second per key. Good for sessions, caches and feature flags; not for counters\n * or anything two people change at once (use env.DB, or a Durable Object for live state).\n *\n *   await putJson(env.KV, `session:${id}`, { user }, { ttl: 60 * 60 * 24 });\n *   const session = await getJson<{ user: string }>(env.KV, `session:${id}`);\n *   const page = await cached(env.KV, "home:stats", 60, () => computeStats());\n */\n\n/** What this file needs from a KV binding (env.KV satisfies it). */\nexport interface KeyValue {\n  get(key: string, type: "text"): Promise<string | null>;\n  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;\n  delete(key: string): Promise<void>;\n}\n\n/** The value saved under `key`, parsed; null when there is none (or it expired). */\nexport async function getJson<T>(kv: KeyValue, key: string): Promise<T | null> {\n  const text = await kv.get(key, "text");\n  return text === null ? null : (JSON.parse(text) as T);\n}\n\n/** Saves `value` as JSON. `ttl`: seconds until it disappears (at least 60). */\nexport function putJson(kv: KeyValue, key: string, value: unknown, options: { ttl?: number } = {}): Promise<void> {\n  return kv.put(key, JSON.stringify(value), options.ttl ? { expirationTtl: Math.max(60, options.ttl) } : undefined);\n}\n\nexport function remove(kv: KeyValue, key: string): Promise<void> {\n  return kv.delete(key);\n}\n\n/** `load()`\'s result, kept for `ttl` seconds: a cache in front of something slow. */\nexport async function cached<T>(kv: KeyValue, key: string, ttl: number, load: () => Promise<T>): Promise<T> {\n  const hit = await getJson<T>(kv, key);\n  if (hit !== null) return hit;\n  const value = await load();\n  await putJson(kv, key, value, { ttl });\n  return value;\n}\n', "lib/notifications.ts": '// Who turned notifications on, and how to reach them (docs/MINI-APPS.md \xA77). The hub sends a token per person\n// to the webhook route (api/ambasada-webhook.ts; app/api/ambasada/webhook/route.ts in Next); it lives in your\n// ambasada.store under the person\'s Ambasada user id.\nimport type { Ambasada, AppNotifyInput } from "@ambasada/sdk";\n\nconst key = (user: string) => `ambasada/notifications/${user}`;\n\nexport const saveToken = (app: Ambasada, user: string, token: string) => app.store.set(key(user), { token, enabled_at: new Date().toISOString() });\nexport const forgetToken = (app: Ambasada, user: string) => app.store.delete(key(user));\n\n/**\n * A push to one person (their Ambasada user id, e.g. `(await app.auth.user(req)).id`), if they turned\n * notifications on. False when they haven\'t, or the hub said the token is gone (then it is forgotten).\n *   await notifyUser(app, user.id, { notification_id: `order-${id}`, title: "Your translation is ready", body: "\u2026", url: `/orders/${id}` });\n */\nexport async function notifyUser(app: Ambasada, user: string, notification: Omit<AppNotifyInput, "tokens" | "users">): Promise<boolean> {\n  const saved = await app.store.get<{ token: string }>(key(user));\n  if (!saved) return false;\n  const result = await app.apps.notify({ ...notification, tokens: [saved.token] });\n  if (result.invalid.includes(saved.token)) await forgetToken(app, user);\n  return result.sent.includes(saved.token);\n}\n', "package.json": '{\n  "name": "@ambasada/template-worker",\n  "version": "0.1.0",\n  "private": true,\n  "description": "An Ambasada app: one bare Cloudflare Worker, web/ + api/*.ts fetch handlers.",\n  "type": "module",\n  "engines": {\n    "node": ">=22"\n  },\n  "scripts": {\n    "dev": "ambasada dev",\n    "preview": "wrangler dev --port 3000",\n    "typecheck": "tsc -p .",\n    "ambasada": "ambasada"\n  },\n  "dependencies": {\n    "@ambasada/sdk": "workspace:*"\n  },\n  "devDependencies": {\n    "@ambasada/cli": "workspace:*",\n    "@cloudflare/workers-types": "^5.20261102.1",\n    "typescript": "~5.9.3",\n    "wrangler": "^4.156.1"\n  },\n  "allowScripts": {\n    "esbuild": true,\n    "fsevents": true,\n    "workerd": true\n  }\n}\n', "src/realtime/room.ts": '/**\n * A live room (Durable Object `Room`, bound as env.ROOMS): everyone connected to the same room id shares it.\n *\n *   GET /api/rooms/<id>/ws  (WebSocket)  \u2192 env.ROOMS.getByName(id).fetch(req)\n *   client \u2192 { "text": "hi" }            server \u2192 { type: "history", messages } on join,\n *                                                 { type: "message", message } to everyone,\n *                                                 { type: "presence", online } when people come and go\n *\n * WebSocket hibernation: the object sleeps between messages and the connections stay open, so an idle room\n * costs nothing. Its own SQLite (`ctx.storage.sql`) keeps the last 50 messages, replayed to whoever joins.\n * The same shape fits presence, live counters, a game table, a queue or a rate limit: one object per thing.\n */\nimport { DurableObject } from "cloudflare:workers";\n\nconst KEEP = 50;\n\nexport type RoomMessage = { id: number; name: string; text: string; at: number };\nexport type RoomEvent = { type: "history"; messages: RoomMessage[] } | { type: "message"; message: RoomMessage } | { type: "presence"; online: number };\n\nexport class Room extends DurableObject<unknown> {\n  constructor(ctx: DurableObjectState, env: unknown) {\n    super(ctx, env);\n    ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS messages (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, text TEXT NOT NULL, at INTEGER NOT NULL)");\n  }\n\n  async fetch(req: Request): Promise<Response> {\n    if (req.headers.get("upgrade") !== "websocket") return Response.json({ online: this.ctx.getWebSockets().length, messages: this.history() });\n    // Who is talking: the client says. Behind Sign in with Ambasada, pass the signed-in name from your route instead.\n    const name = (new URL(req.url).searchParams.get("name") ?? "").trim().slice(0, 40) || "guest";\n    const { 0: client, 1: server } = new WebSocketPair();\n    this.ctx.acceptWebSocket(server);\n    server.serializeAttachment({ name });\n    server.send(JSON.stringify({ type: "history", messages: this.history() } satisfies RoomEvent));\n    this.broadcast({ type: "presence", online: this.ctx.getWebSockets().length });\n    return new Response(null, { status: 101, webSocket: client });\n  }\n\n  async webSocketMessage(ws: WebSocket, data: string | ArrayBuffer): Promise<void> {\n    let text = "";\n    try {\n      text = String((JSON.parse(typeof data === "string" ? data : new TextDecoder().decode(data)) as { text?: unknown }).text ?? "").trim().slice(0, 2000);\n    } catch {\n      return;\n    }\n    if (!text) return;\n    const { name } = ws.deserializeAttachment() as { name: string };\n    const at = Date.now();\n    const { id } = this.ctx.storage.sql.exec<{ id: number }>("INSERT INTO messages (name, text, at) VALUES (?, ?, ?) RETURNING id", name, text, at).one();\n    this.ctx.storage.sql.exec("DELETE FROM messages WHERE id <= ?", id - KEEP);\n    this.broadcast({ type: "message", message: { id, name, text, at } });\n  }\n\n  async webSocketClose(ws: WebSocket, code: number, reason: string): Promise<void> {\n    try {\n      ws.close(code, reason);\n    } catch {\n      // already closed\n    }\n    this.broadcast({ type: "presence", online: this.ctx.getWebSockets().filter((s) => s !== ws).length });\n  }\n\n  private history(): RoomMessage[] {\n    return this.ctx.storage.sql.exec<RoomMessage>("SELECT id, name, text, at FROM messages ORDER BY id").toArray();\n  }\n\n  private broadcast(event: RoomEvent): void {\n    const text = JSON.stringify(event);\n    for (const ws of this.ctx.getWebSockets()) {\n      try {\n        ws.send(text);\n      } catch {\n        // a closing socket: webSocketClose cleans up\n      }\n    }\n  }\n}\n', "src/worker.ts": '/**\n * The app: one Cloudflare Worker (`wrangler dev`, or `ambasada dev` with the mock API).\n *\n *   /api/<name>  \u2192 api/<name>.ts (fetch handlers; add yours to API below)\n *   /api/auth/*  \u2192 api/auth.ts: Sign in with Ambasada (login, callback, logout, me, shell)\n *   /api/ambasada/webhook \u2192 api/ambasada-webhook.ts: the Ambasada app\'s events (notifications on/off, ping)\n *   /api/notes, /api/files \u2192 api/notes.ts (env.DB + env.KV), api/files.ts (uploads to env.FILES)\n *   /api/rooms/<id>/ws \u2192 the live room <id> (src/realtime/room.ts, a Durable Object); demo at /room\n *   /files/*     \u2192 files from env.FILES (lib/files.ts)\n *   /            \u2192 web/index.html with who is signed in filled in\n *   the rest     \u2192 static files from web/ (wrangler.jsonc \u2192 assets)\n */\nimport appWebhook from "../api/ambasada-webhook.ts";\nimport auth from "../api/auth.ts";\nimport files from "../api/files.ts";\nimport notes from "../api/notes.ts";\nimport { ambasada, type Env } from "../lib/ambasada.ts";\nimport { FILES_PATH, serveFile } from "../lib/files.ts";\n\nexport { Room } from "./realtime/room.ts";\n\ntype Handler = (req: Request, env: Env) => Promise<Response>;\nconst API: Record<string, Handler> = { files, notes };\n\n/** The landing page, with the header\'s "Sign in with Ambasada" button or, once signed in, the person\'s name and avatar. */\nasync function landing(req: Request, env: Env): Promise<Response> {\n  const { auth } = ambasada(env);\n  const user = await auth.user(req);\n  return new HTMLRewriter()\n    .on("[data-auth-signin]", { element: (el) => void ((user || !auth.configured) && el.remove()) })\n    .on("[data-auth-user]", { element: (el) => void (user ? el.removeAttribute("hidden") : el.remove()) })\n    .on("[data-auth-avatar]", { element: (el) => void (user?.avatar_url ? el.setAttribute("src", user.avatar_url) : el.remove()) })\n    .on("[data-auth-name]", { element: (el) => void el.setInnerContent(user?.name ?? "Signed in") })\n    .transform(await env.ASSETS.fetch(req));\n}\n\nexport default {\n  async fetch(req, env) {\n    const { pathname } = new URL(req.url);\n    try {\n      if (pathname === "/health") return Response.json({ ok: true });\n      if (pathname.startsWith("/api/auth/")) return await auth(req, env);\n      if (pathname === "/api/ambasada/webhook") return await appWebhook(req, env);\n      const room = /^\\/api\\/rooms\\/([^/]+)\\/ws$/.exec(pathname);\n      if (room) return await env.ROOMS.getByName(decodeURIComponent(room[1]!)).fetch(req);\n      if (pathname.startsWith(FILES_PATH)) return await serveFile(env.FILES, req);\n      const api = /^\\/api\\/([^/]+)\\/?$/.exec(pathname);\n      if (api) {\n        const handler = API[api[1]!];\n        return handler ? await handler(req, env) : Response.json({ error: { code: "NOT_FOUND", message: "no such route" } }, { status: 404 });\n      }\n      if (pathname === "/") return await landing(req, env);\n      return env.ASSETS.fetch(req);\n    } catch (error) {\n      console.error(error);\n      return Response.json({ error: { code: "INTERNAL", message: "internal error" } }, { status: 500 });\n    }\n  },\n} satisfies ExportedHandler<Env>;\n', "tsconfig.json": '{\n  "compilerOptions": {\n    "target": "ES2022",\n    "module": "ESNext",\n    "moduleResolution": "Bundler",\n    "lib": ["ES2022"],\n    "types": ["@cloudflare/workers-types"],\n    "strict": true,\n    "noEmit": true,\n    "skipLibCheck": true,\n    "isolatedModules": true,\n    "verbatimModuleSyntax": true,\n    "allowImportingTsExtensions": true\n  },\n  "include": ["ambasada.config.ts", "src", "api", "lib"]\n}\n', "web/index.html": `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />
@@ -303,14 +297,11 @@ body { margin: 0; }
 .eyebrow::before { content: "// "; }
 h1 { margin: var(--space-2) 0 var(--space-3); font-size: clamp(2.2rem, 7vw, 3.4rem); font-weight: var(--weight-semibold); line-height: 1.05; letter-spacing: -0.03em; }
 .lead { margin: 0 0 var(--space-8); font-size: 1.125rem; color: var(--color-ink-2); }
-.checkout { display: grid; gap: var(--space-4); }
 textarea, select { font: inherit; font-size: var(--text-base); color: inherit; padding: 10px 12px; border: 1px solid var(--color-line); border-radius: var(--radius-sm); background: var(--color-surface); }
 textarea:focus, select:focus { outline: none; border-color: var(--color-accent); box-shadow: 0 0 0 3px var(--color-accent-soft); }
 textarea { resize: vertical; min-height: 7rem; }
 .row { display: flex; flex-wrap: wrap; gap: var(--space-3); align-items: center; justify-content: space-between; }
 label { display: flex; gap: var(--space-2); align-items: center; color: var(--color-ink-2); }
-.pay::before { content: "\u25C6 "; opacity: 0.8; }
-.tip { margin-top: var(--space-10); padding-top: var(--space-6); border-top: 1px solid var(--color-line); }
 .small, footer { color: var(--color-ink-3); font-size: var(--text-sm); }
 footer { margin-top: calc(var(--space-10) + var(--space-2)); }
 code { font-family: var(--font-mono); font-size: 0.9em; background: var(--color-surface-2); padding: 0.1em 0.35em; border-radius: var(--radius-xs); }
@@ -395,10 +386,10 @@ function aexists(instance, checkFinished = true) {
   if (checkFinished && instance.finished)
     throw new Error("digest() was already called");
 }
-function aoutput(out7, instance) {
-  abytes(out7, void 0, "output");
+function aoutput(out8, instance) {
+  abytes(out8, void 0, "output");
   const min = instance.outputLen;
-  if (!(out7.length >= min)) {
+  if (!(out8.length >= min)) {
     throw new RangeError('"output" expected length >= ' + min);
   }
 }
@@ -496,9 +487,9 @@ var HashMD = class {
       this.roundClean();
     return this;
   }
-  digestInto(out7) {
+  digestInto(out8) {
     aexists(this);
-    aoutput(out7, this);
+    aoutput(out8, this);
     this.finished = true;
     const { buffer, view, blockLen, isLE } = this;
     let { pos } = this;
@@ -511,7 +502,7 @@ var HashMD = class {
     setU64FromNum(view, blockLen - 8, this.length * 8, isLE);
     this.process(view, 0);
     this.roundClean();
-    const oview = out7 === buffer ? view : createView(out7);
+    const oview = out8 === buffer ? view : createView(out8);
     const len = this.outputLen;
     const outLen = len / 4;
     const state = this.get();
@@ -975,9 +966,9 @@ function checkIcon(bytes) {
 function metaTags(html) {
   const tags = [];
   for (const [, attrs] of html.matchAll(/<meta\b([^>]*)>/gi)) {
-    const out7 = {};
-    for (const [, key, dq, sq, bare] of attrs.matchAll(/([a-zA-Z-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/g)) out7[key.toLowerCase()] = (dq ?? sq ?? bare ?? "").trim();
-    tags.push(out7);
+    const out8 = {};
+    for (const [, key, dq, sq, bare] of attrs.matchAll(/([a-zA-Z-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/g)) out8[key.toLowerCase()] = (dq ?? sq ?? bare ?? "").trim();
+    tags.push(out8);
   }
   return tags;
 }
@@ -993,7 +984,7 @@ function checkHtml(html) {
   const darkStyle = [...html.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)].concat([...html.matchAll(/\bstyle\s*=\s*"([^"]*)"/gi)]).some(([, css]) => [...css.matchAll(/color-scheme\s*:\s*([^;}"]+)/gi)].some(([, v]) => /\bdark\b/i.test(v) && !/\blight\b/i.test(v)));
   if (darkMeta || darkStyle) f.problems.push({ code: "dark_only", message: "the entry page declares a dark-only color-scheme; the Ambasada app is light (use light, or light dark)" });
   if (!SDK_MARKERS.some((m) => html.includes(m))) {
-    f.warnings.push({ code: "no_miniapp_sdk", message: "no @ambasada/miniapp, miniapp.js or ambasadaShell in the entry HTML: a bundled import is fine too, the registry crawler confirms ready() is called at runtime" });
+    f.warnings.push({ code: "no_miniapp_sdk", message: "no @ambasada/miniapp, miniapp.js or ambasadaShell in the entry HTML or its scripts: the Ambasada app waits for ready() to drop the splash" });
   }
   return f;
 }
@@ -1001,6 +992,23 @@ var USER_AGENT = "ambasada-check/1 (+https://ambasada.id)";
 async function get(fetchImpl, url) {
   return fetchImpl(url, { redirect: "manual", signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), headers: { "user-agent": USER_AGENT, accept: "*/*" } });
 }
+var SDK_SCRIPT_LIMIT = 16;
+var BUNDLED_SDK = /ambasadaShell|@ambasada\/miniapp/;
+async function bundlesMiniappSdk(fetchImpl, pageUrl, html) {
+  const origin = new URL(pageUrl).origin;
+  const srcs = [...html.matchAll(/<script\b[^>]*\bsrc\s*=\s*["']([^"']+)["']/gi)].map(([, src]) => URL.canParse(src, pageUrl) ? new URL(src, pageUrl) : null).filter((u) => !!u && u.origin === origin).slice(0, SDK_SCRIPT_LIMIT);
+  const found = await Promise.all(
+    srcs.map(async (u) => {
+      try {
+        const res = await get(fetchImpl, u.toString());
+        return res.status === 200 && BUNDLED_SDK.test(await res.text());
+      } catch {
+        return false;
+      }
+    })
+  );
+  return found.includes(true);
+}
 async function checkPage(fetchImpl, url, report, html) {
   try {
     const started = Date.now();
@@ -1009,7 +1017,11 @@ async function checkPage(fetchImpl, url, report, html) {
     if (!html) await res.body?.cancel();
     const ms = Date.now() - started;
     if (res.status !== 200) report.problems.push({ code: "entry_status", message: `${url} answered ${res.status}${res.headers.get("location") ? ` \u2192 ${res.headers.get("location")}` : ""}; ${html ? "the entry" : "the app"} must answer 200 without redirects` });
-    else if (html) merge(report, checkHtml(text));
+    else if (html) {
+      const found = checkHtml(text);
+      if (found.warnings.some((w) => w.code === "no_miniapp_sdk") && await bundlesMiniappSdk(fetchImpl, url, text)) found.warnings = found.warnings.filter((w) => w.code !== "no_miniapp_sdk");
+      merge(report, found);
+    }
     if (ms > SLOW_ENTRY_MS) report.warnings.push({ code: "slow_entry", message: `${url} took ${ms} ms; aim for under ${SLOW_ENTRY_MS} ms${html ? " (the splash stays until ready())" : ""}` });
   } catch (error) {
     report.problems.push({ code: "entry_fetch", message: `could not fetch ${url}: ${error.message}` });
@@ -1114,10 +1126,13 @@ async function checkRemote(url, fetchImpl = fetch, options = {}) {
   report.ok = report.problems.length === 0;
   return report;
 }
-function listingLine(tier, check2) {
+var checkPending = (check2) => check2?.status === "pending";
+function listingLine(tier, check2, kind = "company") {
   if (check2?.miniapp === "off") return "Mini app: off";
+  const listed = kind === "project" ? "Listed" : "Listed for the event";
+  if (checkPending(check2)) return `${tier === "verified" ? "Verified" : tier === "listed" ? listed : tier === "unlisted" ? "Unlisted" : "Not registered yet"} \xB7 checking\u2026`;
   if (tier === "verified") return "Verified";
-  if (tier === "listed") return "Listed for the event";
+  if (tier === "listed") return listed;
   if (tier === "unlisted") return check2?.needs.length ? `Unlisted \xB7 needs: ${check2.needs.join(", ")}` : "Unlisted";
   return check2?.needs.length ? `Not registered yet \xB7 needs: ${check2.needs.join(", ")}` : "Not registered yet";
 }
@@ -1324,9 +1339,9 @@ function b64url(bytes) {
 }
 function fromB64url(text) {
   const s = atob(text.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((text.length + 3) % 4));
-  const out7 = new Uint8Array(s.length);
-  for (let i = 0; i < s.length; i++) out7[i] = s.charCodeAt(i);
-  return out7;
+  const out8 = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out8[i] = s.charCodeAt(i);
+  return out8;
 }
 var random = (n) => b64url(crypto.getRandomValues(new Uint8Array(n)));
 async function pkce() {
@@ -1591,6 +1606,7 @@ var AmbasadaAuth = class {
 
 // ../sdk/src/client.ts
 var DEFAULT_API_URL = "https://api.ambasada.dev";
+var isBinding = (v) => typeof v === "object" && v !== null && typeof v.fetch === "function";
 function processEnv() {
   const p = globalThis.process;
   return p?.env ?? {};
@@ -1606,6 +1622,22 @@ var Ambasada = class {
     const v = this.options.env?.[name];
     return typeof v === "string" ? v : processEnv()[name];
   }
+  /**
+   * How this client fetches: `options.fetch`; else, with an `AMBASADA_API` service binding in `env` (hosted on
+   * ambasada.dev), the API's own URLs go through it and everything else (the hub, the issuer) through `fetch`.
+   */
+  get fetcher() {
+    if (this.options.fetch) return this.options.fetch;
+    const binding = this.options.env?.AMBASADA_API;
+    if (!isBinding(binding)) return (input, init2) => fetch(input, init2);
+    const api2 = new Set(
+      [this.apiUrl, this.env("AMBASADA_API_URL"), this.env("AMBASADA_VILLAGE_API_URL")].filter((u) => !!u && URL.canParse(u)).map((u) => new URL(u).origin)
+    );
+    return (input, init2) => {
+      const request = new Request(input, init2);
+      return api2.has(new URL(request.url).origin) ? binding.fetch(request) : fetch(request);
+    };
+  }
   get apiUrl() {
     return (this.options.apiUrl ?? this.env("AMBASADA_API_URL") ?? this.env("VILLAGE_API_URL") ?? DEFAULT_API_URL).replace(/\/+$/, "");
   }
@@ -1627,7 +1659,7 @@ var Ambasada = class {
     // Silent sign-in: a shell token must be for this app, by id or origin.
     audiences: [this.appOrigin, this.options.app?.id ?? this.env("AMBASADA_APP_ID") ?? this.env("AMBASADA_COMPANY")].filter((a) => !!a),
     hubUrl: this.hubUrl,
-    fetch: this.options.fetch
+    fetch: this.fetcher
   }));
   get appOrigin() {
     const url = this.options.app?.origin ?? this.env("AMBASADA_APP_ORIGIN") ?? this.options.auth?.publicUrl ?? this.env("PUBLIC_URL");
@@ -1644,7 +1676,7 @@ var Ambasada = class {
     appSecret: this.options.app?.secret ?? this.env("AMBASADA_APP_SECRET"),
     hubUrl: this.hubUrl,
     origin: this.appOrigin,
-    fetch: this.options.fetch
+    fetch: this.fetcher
   }));
   // ── HTTP ──────────────────────────────────────────────────────────────────
   async send(method, path, opts = {}) {
@@ -1658,7 +1690,7 @@ var Ambasada = class {
       headers["content-type"] = "application/json";
     }
     for (const [k, v] of Object.entries(opts.headers ?? {})) if (v !== void 0) headers[k.toLowerCase()] = v;
-    const doFetch = this.options.fetch ?? fetch;
+    const doFetch = this.fetcher;
     const attempt = () => {
       const timeout = AbortSignal.timeout(this.options.timeoutMs ?? 45e3);
       const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
@@ -1816,7 +1848,11 @@ var APP_WEBHOOK_PATH = "/api/ambasada/webhook";
 var MINIAPP_DEFAULTS = { age_rating: "4+", kind: "tool" };
 var oneLine = (s, max) => {
   const line = s.replace(/\s+/g, " ").trim();
-  return line.length > max ? `${line.slice(0, max - 1).trimEnd()}\u2026` : line;
+  if (line.length <= max) return line;
+  const room = line.slice(0, max - 1);
+  const space = line[max - 1] === " " ? max - 1 : room.lastIndexOf(" ");
+  const cut = space > 0 ? room.slice(0, space) : room;
+  return `${cut.replace(/[\s,;:.\-–—]+$/, "")}\u2026`;
 };
 function appManifest(app, miniapp2 = { entry: "/" }) {
   const description = miniapp2.description || app.description || app.name;
@@ -1867,16 +1903,16 @@ function readMiniapp(configSource) {
   const str4 = (key) => new RegExp(`\\b${key}\\s*:\\s*(["'\`])((?:(?!\\1)[^\\\\]|\\\\.)*)\\1`).exec(text)?.[2];
   const entry2 = str4("entry");
   if (entry2 === void 0) return null;
-  const out7 = { entry: entry2 };
+  const out8 = { entry: entry2 };
   for (const key of ["icon", "category", "accent", "visibility", "age_rating", "kind", "support", "subtitle", "description"]) {
     const v = str4(key);
-    if (v !== void 0) out7[key] = v;
+    if (v !== void 0) out8[key] = v;
   }
   for (const key of ["tags", "scopes"]) {
     const list = new RegExp(`\\b${key}\\s*:\\s*\\[([^\\]]*)\\]`).exec(text);
-    if (list) out7[key] = [...list[1].matchAll(/(["'`])((?:(?!\1).)*)\1/g)].map((m) => m[2]);
+    if (list) out8[key] = [...list[1].matchAll(/(["'`])((?:(?!\1).)*)\1/g)].map((m) => m[2]);
   }
-  return out7;
+  return out8;
 }
 
 // src/project.ts
@@ -2312,8 +2348,8 @@ async function startMock(options = {}) {
     }
     if (path === "/dev/app/event" && method === "POST") {
       const b = await body();
-      const out7 = await appEvent(String(b.event ?? "ping"), { user: typeof b.user === "string" ? b.user : void 0, webhook: typeof b.webhook === "string" ? b.webhook : void 0 });
-      return json2(out7, out7.error ? 502 : 200);
+      const out8 = await appEvent(String(b.event ?? "ping"), { user: typeof b.user === "string" ? b.user : void 0, webhook: typeof b.webhook === "string" ? b.webhook : void 0 });
+      return json2(out8, out8.error ? 502 : 200);
     }
     if (path === "/dev/state") return json2(Object.assign({ company, notifications, events }, ...extensions.map((e) => e.state?.() ?? {})));
     if (!path.startsWith("/v1/")) throw fail("NOT_FOUND", "no such route");
@@ -2422,7 +2458,7 @@ import { createRequire } from "node:module";
 import { dirname as dirname2, isAbsolute, join as join4, resolve as resolvePath2 } from "node:path";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
 var PLATFORM_CONFIG_KEYS = ["id", "name", "product", "addons"];
-var VERSION = true ? "0.8.5" : "0.1.0-dev";
+var VERSION = true ? "0.8.6" : "0.1.0-dev";
 var shortName = (pkg) => pkg.replace(/^@ambasada\//, "").replace(/^ambasada-(addon-)?/, "");
 var KNOWN_ADDONS = { village: "@ambasada/village" };
 function readJson(file) {
@@ -2561,6 +2597,27 @@ function setAddons(a) {
 import { spawn } from "node:child_process";
 import { existsSync as existsSync5, readFileSync as readFileSync3 } from "node:fs";
 import { dirname as dirname3, join as join5 } from "node:path";
+var ANSI = /\x1b\[[0-9;?]*[A-Za-z]/g;
+function quietDurableObjects() {
+  let said = false;
+  let inBlock = false;
+  const once = () => {
+    if (said) return null;
+    said = true;
+    return "Durable Objects (the live rooms) don't run under next dev: `npm run preview` runs them; online they just work";
+  };
+  return (line) => {
+    const text = line.replace(ANSI, "");
+    if (/You have defined bindings to the following internal Durable Objects/.test(text)) {
+      inBlock = true;
+      return once();
+    }
+    if (inBlock && /^\s*\t/.test(text)) return null;
+    inBlock = false;
+    if (/A DurableObjectNamespace in the config referenced the class .* but no such Durable Object class is exported/.test(text)) return once();
+    return line;
+  };
+}
 var STACKS = [
   {
     files: ["next.config.ts", "next.config.mjs", "next.config.js", "open-next.config.ts"],
@@ -2570,7 +2627,8 @@ var STACKS = [
       bin: "next",
       label: "next dev",
       // Next loads .env without overriding what is already in process.env.
-      args: (host, port) => ["dev", "--hostname", host, "--port", String(port)]
+      args: (host, port) => ["dev", "--hostname", host, "--port", String(port)],
+      output: quietDurableObjects
     }
   },
   {
@@ -2622,12 +2680,16 @@ function startApp(root, stack, bin2, url, vars, print, prefix) {
     env: { ...process.env, ...stack.env, ...vars },
     stdio: ["ignore", "pipe", "pipe"]
   });
+  const filter = stack.output?.() ?? ((line) => line);
   for (const stream of [child.stdout, child.stderr]) {
     let rest = "";
     stream.on("data", (chunk) => {
       const lines = (rest + chunk.toString()).split("\n");
       rest = lines.pop() ?? "";
-      for (const line of lines) if (line.trim()) print(`${prefix} ${line}`);
+      for (const line of lines) {
+        const shown = line.trim() ? filter(line) : null;
+        if (shown) print(`${prefix} ${shown}`);
+      }
     });
   }
   const ready = (async () => {
@@ -2663,17 +2725,17 @@ var SKIP = /* @__PURE__ */ new Set(["node_modules", "dist", ".next", ".open-next
 var BINARY = /\.(png|ico|jpe?g|gif|webp|woff2?)$/i;
 var isBinary = (path) => BINARY.test(path);
 function readTemplateDir(dir) {
-  const out7 = {};
+  const out8 = {};
   const walk2 = (d) => {
     for (const name of readdirSync2(d)) {
       if (SKIP.has(name)) continue;
       const path = join6(d, name);
       if (statSync2(path).isDirectory()) walk2(path);
-      else out7[relative(dir, path).split("\\").join("/")] = readFileSync4(path, isBinary(name) ? "base64" : "utf8");
+      else out8[relative(dir, path).split("\\").join("/")] = readFileSync4(path, isBinary(name) ? "base64" : "utf8");
     }
   };
   walk2(dir);
-  return out7;
+  return out8;
 }
 function templateFiles(name) {
   if (typeof define_AMBASADA_TEMPLATES_default !== "undefined") return define_AMBASADA_TEMPLATES_default[name] ?? {};
@@ -2765,6 +2827,16 @@ function stateLine(state) {
   if (!state.on) return `mini app: off ${c.dim("(`ambasada miniapp enable` adds one)")}`;
   return `mini app: on at ${c.bold(state.entry ?? "/")}${state.source === "file" ? c.dim(` (manifest: ${state.file})`) : ""}`;
 }
+function removeMiniappKey(source) {
+  const key = /^([ \t]*)miniapp\s*:\s*\{[^{}]*\},?[ \t]*(\/\/[^\n]*)?\n/m.exec(source);
+  if (!key) return /\bminiapp\s*:/.test(source) ? null : source;
+  let start = key.index;
+  const before = source.slice(0, start);
+  const ours = COMMENT.map((l) => `${key[1]}${l}
+`).join("");
+  if (before.endsWith(ours)) start -= ours.length;
+  return source.slice(0, start) + source.slice(key.index + key[0].length);
+}
 var COMMENT = [
   "// The Ambasada mini app, at a path of this app: `ambasada dev` and `deploy` serve its manifest from this.",
   "// age_rating: 4+, 9+, 12+ or 17+. kind: tool, product, event or assistant. Also: support (an email or URL), tags, subtitle."
@@ -2948,11 +3020,11 @@ function entryPieces(template, entry2) {
 }
 function leftoverOf(root, template, from, to) {
   const old = entryPieces(template, from);
-  const now = entryPieces(template, to);
+  const now = to === null ? { files: [], hooks: [] } : entryPieces(template, to);
   const files2 = old.files.filter((f) => !now.files.includes(f) && existsSync6(join7(root, f)));
   const hooks = old.hooks.filter((h) => !now.hooks.some((n) => n.file === h.file && n.what === h.what)).filter((h) => existsSync6(join7(root, h.file)) && h.present(readFileSync5(join7(root, h.file), "utf8"))).map(({ file, what }) => ({ file, what }));
   const inApp = join7(root, "src/in-app/InApp.tsx");
-  const constant = template === "spa" && from !== "/" && to !== "/" && existsSync6(inApp) && readFileSync5(inApp, "utf8").includes(`export const IN_APP = "${from}";`) ? "src/in-app/InApp.tsx" : null;
+  const constant = template === "spa" && to !== null && from !== "/" && to !== "/" && existsSync6(inApp) && readFileSync5(inApp, "utf8").includes(`export const IN_APP = "${from}";`) ? "src/in-app/InApp.tsx" : null;
   return { files: files2, hooks, inAppConstant: constant };
 }
 async function removeLeftover(root, template, from, to, left) {
@@ -3038,11 +3110,70 @@ async function miniappCommand(args, flags, releaseLine) {
     else out(stateLine(state));
     return;
   }
-  if (sub !== "enable") throw new CliError("usage: ambasada miniapp [enable [--entry /app]]");
+  if (sub === "disable") return disableInFolder(root, flags);
+  if (sub !== "enable") throw new CliError("usage: ambasada miniapp [enable [--entry /app] | disable [--force]]");
+  return enableInFolder(root, flags, releaseLine);
+}
+async function disableInFolder(root, flags) {
+  const { miniapp: miniapp2 } = miniappOfSource(root);
+  const state = miniappState(root, miniapp2);
+  if (state.source === "file") throw new CliError(`the mini app is on from ${state.file} (yours, it wins): delete that file to turn it off`);
+  const entry2 = miniapp2?.entry ?? await movedFrom(root);
+  if (!entry2) return void out(stateLine(state));
+  const template = templateOf(root);
+  const changed = [];
+  if (miniapp2) {
+    const configFile = join7(root, CONFIG_FILE);
+    const next = removeMiniappKey(await readFile3(configFile, "utf8"));
+    if (next === null) throw new CliError(`could not take \`miniapp: { \u2026 }\` out of ${CONFIG_FILE}: delete it by hand, then run \`ambasada miniapp disable\` again`);
+    await writeFile3(configFile, next);
+    changed.push(CONFIG_FILE);
+    const manifest = join7(root, MANIFEST_FILES[template]);
+    if (isOurs(root, manifest)) {
+      await rm2(manifest, { force: true });
+      await rm2(join7(root, GENERATED_RECORD), { force: true });
+    }
+  }
+  const left = leftoverOf(root, template, entry2, null);
+  const keep = entry2 !== "/" && !flags.force;
+  const undone = keep ? { removed: [], changed: [], manual: [] } : await removeLeftover(root, template, entry2, null, left);
+  await rememberMove(root, keep && left.files.length + left.hooks.length ? entry2 : null);
+  out(`${c.green("\u2713")} mini app off ${c.dim(`(was at ${entry2}): from the next \`ambasada deploy\`, a website, not in the Ambasada app`)}`);
+  for (const f of [...changed, ...undone.changed]) out(`  ${c.dim("changed")} ${f}`);
+  for (const f of undone.removed) out(`  ${c.dim("removed")} ${f}`);
+  for (const m of undone.manual) out(c.yellow(`! by hand: ${m}`));
+  if (keep && left.files.length + left.hooks.length) {
+    out(c.yellow(`! the pages at ${entry2} stay (move what you built, then \`ambasada miniapp disable --force\` removes them):`));
+    for (const f of left.files) out(`    ${f}`);
+    for (const h of left.hooks) out(`    ${h.file}: ${h.what}`);
+  }
+  if (template !== "worker") out(c.dim("  @ambasada/miniapp stays in package.json (`npm uninstall @ambasada/miniapp` once nothing imports it)"));
+}
+var MOVED_FROM = "miniapp_moved_from";
+var projectFile = (root) => join7(root, ".ambasada", "project.json");
+async function movedFrom(root) {
+  try {
+    const v = JSON.parse(await readFile3(projectFile(root), "utf8"))[MOVED_FROM];
+    return typeof v === "string" ? v : null;
+  } catch {
+    return null;
+  }
+}
+async function rememberMove(root, from) {
+  if (!existsSync6(projectFile(root)) || await movedFrom(root) === from) return;
+  const info = JSON.parse(await readFile3(projectFile(root), "utf8"));
+  if (from) info[MOVED_FROM] = from;
+  else delete info[MOVED_FROM];
+  await writeFile3(projectFile(root), `${JSON.stringify(info, null, 2)}
+`);
+}
+async function enableInFolder(root, flags, releaseLine) {
+  const { miniapp: miniapp2 } = miniappOfSource(root);
   const current2 = miniappState(root, miniapp2);
   if (current2.source === "file") throw new CliError(`the mini app is on already, from ${current2.file} (yours, it wins): change its "entry" there`);
   const entry2 = typeof flags.entry === "string" ? flags.entry : miniapp2?.entry ?? DEFAULT_ENTRY;
-  const moved = miniapp2 && miniapp2.entry !== entry2 ? miniapp2.entry : null;
+  const recorded = await movedFrom(root);
+  const moved = miniapp2 && miniapp2.entry !== entry2 ? miniapp2.entry : recorded && recorded !== entry2 ? recorded : null;
   const done = await enableMiniapp(root, entry2, flags, { releaseLine });
   if (done.installNeeded && existsSync6(join7(root, "node_modules")) && !flags["no-install"]) {
     out(c.dim("npm install \u2026"));
@@ -3054,24 +3185,24 @@ async function miniappCommand(args, flags, releaseLine) {
     }
   }
   printEnabled(done, root);
-  if (moved) {
-    const template = templateOf(root);
-    const left = leftoverOf(root, template, moved, entry2);
-    const total = left.files.length + left.hooks.length + (left.inAppConstant ? 1 : 0);
-    if (!total) return;
-    if (flags.force) {
-      const undone = await removeLeftover(root, template, moved, entry2, left);
-      out(`${c.green("\u2713")} the old entry ${moved} is gone`);
-      for (const f of undone.removed) out(`  ${c.dim("removed")} ${f}`);
-      for (const f of undone.changed) out(`  ${c.dim("changed")} ${f}`);
-      for (const m of undone.manual) out(c.yellow(`! by hand: ${m}`));
-      return;
-    }
-    out(c.yellow(`! the entry moved from ${moved}; still there from it (move what you built, then \`ambasada miniapp enable --entry ${entry2} --force\` removes them):`));
-    for (const f of left.files) out(`    ${f}`);
-    for (const h of left.hooks) out(`    ${h.file}: ${h.what}`);
-    if (left.inAppConstant) out(`    ${left.inAppConstant}: IN_APP is still "${moved}"`);
-  }
+  if (!moved) return rememberMove(root, null);
+  const template = templateOf(root);
+  const left = leftoverOf(root, template, moved, entry2);
+  const total = left.files.length + left.hooks.length + (left.inAppConstant ? 1 : 0);
+  if (!total) return rememberMove(root, null);
+  if (flags.force) {
+    const undone = await removeLeftover(root, template, moved, entry2, left);
+    out(`${c.green("\u2713")} the old entry ${moved} is gone`);
+    for (const f of undone.removed) out(`  ${c.dim("removed")} ${f}`);
+    for (const f of undone.changed) out(`  ${c.dim("changed")} ${f}`);
+    for (const m of undone.manual) out(c.yellow(`! by hand: ${m}`));
+    return rememberMove(root, null);
+  }
+  await rememberMove(root, moved);
+  out(c.yellow(`! the entry moved from ${moved}; still there from it (move what you built, then \`ambasada miniapp enable --entry ${entry2} --force\` removes them):`));
+  for (const f of left.files) out(`    ${f}`);
+  for (const h of left.hooks) out(`    ${h.file}: ${h.what}`);
+  if (left.inAppConstant) out(`    ${left.inAppConstant}: IN_APP is still "${moved}"`);
 }
 function printEnabled(done, root) {
   out(`${c.green("\u2713")} mini app on at ${c.bold(done.entry)}`);
@@ -3131,6 +3262,23 @@ async function checkLocal(dir, opts) {
   report.ok = report.problems.length === 0;
   return report;
 }
+var out2 = (s = "") => process.stdout.write(`${s}
+`);
+function printListing(tier, check2, kind) {
+  out2(`  ${tier === "listed" || tier === "verified" ? c.green("\u2713") : c.yellow("!")} in the Ambasada app: ${listingLine(tier, check2, kind)}`);
+  if (checkPending(check2)) return;
+  for (const issue of check2?.issues.filter((i) => i.level === "problem") ?? []) out2(c.dim(`    ${issue.message}`));
+}
+async function platformCheck(apiUrl, apiKey) {
+  try {
+    const res = await fetch(`${apiUrl}/v1/product`, { headers: { authorization: `Bearer ${apiKey}`, accept: "application/json" }, signal: AbortSignal.timeout(1e4) });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return body.deployed === false || !body.tier ? null : { tier: body.tier, check: body.check ?? null, kind: body.kind };
+  } catch {
+    return null;
+  }
+}
 
 // src/storage.ts
 import { createHash } from "node:crypto";
@@ -3152,10 +3300,10 @@ import { execFileSync as execFileSync2 } from "node:child_process";
 import { existsSync as existsSync8, readdirSync as readdirSync3, statSync as statSync3 } from "node:fs";
 import { mkdir as mkdir3, readFile as readFile4, rm as rm3, writeFile as writeFile4 } from "node:fs/promises";
 import { join as join9, relative as relative3 } from "node:path";
-var VERSION2 = true ? "0.8.5" : "0.1.0-dev";
+var VERSION2 = true ? "0.8.6" : "0.1.0-dev";
 var RELEASE_SPEC = /^\d+\.\d+\.\d+$/.test(VERSION2) ? `^${VERSION2}` : "latest";
 var PROJECT_FILE = join9(".ambasada", "project.json");
-var out2 = (s = "") => process.stdout.write(`${s}
+var out3 = (s = "") => process.stdout.write(`${s}
 `);
 async function readProjectInfo(root) {
   try {
@@ -3364,12 +3512,12 @@ async function upgrade(_args, flags) {
   const from = info?.devkit ?? "0.7";
   if (checkOnly) {
     if (!uniqueChanges.length && !stale.length) {
-      out2(`${c.green("\u2713")} up to date with the devkit ${VERSION2}`);
+      out3(`${c.green("\u2713")} up to date with the devkit ${VERSION2}`);
       return;
     }
-    out2(`devkit ${from} \u2192 ${VERSION2}:`);
-    for (const line of uniqueChanges) out2(`  ${line}`);
-    for (const s of stale) out2(`  .claude/skills/${s}: removed`);
+    out3(`devkit ${from} \u2192 ${VERSION2}:`);
+    for (const line of uniqueChanges) out3(`  ${line}`);
+    for (const s of stale) out3(`  .claude/skills/${s}: removed`);
     throw new CliError("`ambasada upgrade` would change the above", 1);
   }
   for (const [file, text] of edits) await writeFile4(file, text);
@@ -3383,7 +3531,7 @@ async function upgrade(_args, flags) {
   }
   for (const s of stale) await rm3(join9(skillsDir, s), { recursive: true, force: true });
   if (!flags["no-install"]) {
-    out2(c.dim("npm install \u2026"));
+    out3(c.dim("npm install \u2026"));
     try {
       execFileSync2(process.platform === "win32" ? "npm.cmd" : "npm", ["install"], { cwd: root, stdio: "inherit" });
     } catch {
@@ -3399,29 +3547,29 @@ async function upgrade(_args, flags) {
       await writeFile4(file, text);
     }
   }
-  if (village && !addons2.get("village")) out2(c.yellow("! @ambasada/village is in package.json but not installed yet: run `npm install`, then `ambasada upgrade` again for its skill"));
+  if (village && !addons2.get("village")) out3(c.yellow("! @ambasada/village is in package.json but not installed yet: run `npm install`, then `ambasada upgrade` again for its skill"));
   await writeProjectInfo(root, nextInfo);
-  for (const line of uniqueChanges) out2(`${c.green("\u2713")} ${line}`);
-  for (const s of stale) out2(`${c.green("\u2713")} .claude/skills/${s}: removed (now ambasada-village)`);
+  for (const line of uniqueChanges) out3(`${c.green("\u2713")} ${line}`);
+  for (const s of stale) out3(`${c.green("\u2713")} .claude/skills/${s}: removed (now ambasada-village)`);
   const report = await checkLocal(root).catch(() => null);
-  for (const p of report?.problems ?? []) out2(`${c.yellow("!")} ${p.message} ${c.dim(`(${p.code}, \`ambasada check\`)`)}`);
-  out2(`${c.green("\u2713")} devkit ${from} \u2192 ${VERSION2}`);
+  for (const p of report?.problems ?? []) out3(`${c.yellow("!")} ${p.message} ${c.dim(`(${p.code}, \`ambasada check\`)`)}`);
+  out3(`${c.green("\u2713")} devkit ${from} \u2192 ${VERSION2}`);
   if (before08) {
-    out2("");
-    out2(`Then ask your coding agent: ${c.bold(`"run the Ambasada upgrade steps for 0.7 \u2192 0.8"`)} (.claude/skills/ambasada-product/reference/upgrading.md)`);
+    out3("");
+    out3(`Then ask your coding agent: ${c.bold(`"run the Ambasada upgrade steps for 0.7 \u2192 0.8"`)} (.claude/skills/ambasada-product/reference/upgrading.md)`);
   }
 }
 
 // src/deploy.ts
-var out3 = (s = "") => process.stdout.write(`${s}
+var out4 = (s = "") => process.stdout.write(`${s}
 `);
 var LIMITS = { assets: 1e3, assetBytes: 25 * 1024 * 1024 };
 var WEBHOOK_FILES = ["app/api/webhook/route.ts", "app/api/webhook/route.js", "src/app/api/webhook/route.ts", "api/webhook.ts", "src/api/webhook.ts", "functions/api/webhook.ts", "product/api/webhook.ts"];
 var PLATFORM_STORAGE = { d1: "DB", kv: "KV", r2: "FILES" };
 async function deploy(_args, flags) {
   const project = await loadProject();
-  await addons().beforeDeploy({ event: "deploy", project, url: project.config.product?.url, flags, out: out3 });
-  const hooks = (url = project.config.product?.url) => addons().afterDeploy({ event: "deploy", project, url, flags, out: out3 });
+  await addons().beforeDeploy({ event: "deploy", project, url: project.config.product?.url, flags, out: out4 });
+  const hooks = (url = project.config.product?.url) => addons().afterDeploy({ event: "deploy", project, url, flags, out: out4 });
   if (flags["agent-only"] || flags["offerings-only"]) {
     if (!addons().get("village")) throw new CliError("--agent-only and --offerings-only belong to the village add-on: `ambasada add village`");
     return hooks();
@@ -3429,56 +3577,70 @@ async function deploy(_args, flags) {
   const dir = findProductDir(project.root);
   if (!dir) {
     if (!project.config.product?.url || !addons().list.length) productDir(project.root);
-    out3(c.dim(`no wrangler.jsonc: not hosting ${project.config.product.url}`));
+    out4(c.dim(`no wrangler.jsonc: not hosting ${project.config.product.url}`));
     return hooks();
   }
   const template = detectTemplate(dir);
   if (!flags.own && await isMockApi((await resolve(flags)).apiUrl)) {
-    out3(c.dim("ambasada dev does not host apps (deploy without --api-url to go live)"));
+    out4(c.dim("ambasada dev does not host apps (deploy without --api-url to go live)"));
     return hooks();
   }
   const r = flags.own || flags["dry-run"] ? await resolve(flags) : await resolveForApp(flags, "deploy");
   if (!flags.own && !flags["dry-run"] && !r.apiKey) throw new CliError("not logged in: run `ambasada login` (or set AMBASADA_API_KEY)");
   const inApp = await syncManifest(project.root, project.config);
-  out3(stateLine(inApp));
+  out4(stateLine(inApp));
   if (!flags["no-build"]) await build(dir, template);
   if (flags.own) {
-    out3(c.bold("wrangler deploy (your Cloudflare account)"));
+    out4(c.bold("wrangler deploy (your Cloudflare account)"));
     const output = await run(bin(dir, "wrangler"), ["deploy"], dir, { capture: true });
     const url = /https:\/\/[^\s]+\.workers\.dev|https:\/\/[a-z0-9.-]+\.[a-z]{2,}(?=\s|$)/m.exec(output)?.[0];
     if (!url) throw new CliError("wrangler deployed, but I could not read the URL from its output: run `ambasada link https://\u2026` yourself");
     await link([url], flags);
-    return addons().afterDeploy({ event: "deploy", project: await loadProject(project.root), url, flags: { ...flags, "agent-only": true }, out: out3 });
+    return addons().afterDeploy({ event: "deploy", project: await loadProject(project.root), url, flags: { ...flags, "agent-only": true }, out: out4 });
   }
   const built = await bundle(dir, template);
   durableObjects(built.config);
-  for (const warning of storageWarnings(built.config)) out3(c.yellow(`! ${warning}`));
-  out3(`${c.green("\u2713")} built ${c.bold(template)}: ${built.modules.length} module(s), ${built.assets.length} static file(s)`);
+  for (const warning of storageWarnings(built.config)) out4(c.yellow(`! ${warning}`));
+  out4(`${c.green("\u2713")} built ${c.bold(template)}: ${built.modules.length} module(s), ${built.assets.length} static file(s)`);
   const smoked = flags["no-smoke"] ? { ok: false, skipped: true, checks: [], ms: null } : await smoke(built, project.config.id, project.root);
   const metadata = { ...deployMetadata(built, project.root), report: { template, devkit: devkitVersion(), smoke: smoked, git: gitInfo(project.root) } };
   if (flags["dry-run"]) {
-    out3(`would POST ${r.apiUrl}/v1/product/deploy ${JSON.stringify({ ...metadata, modules: built.modules.map((m) => m.name), assets: built.assets.length })}`);
+    out4(`would POST ${r.apiUrl}/v1/product/deploy ${JSON.stringify({ ...metadata, modules: built.modules.map((m) => m.name), assets: built.assets.length })}`);
     return hooks();
   }
   const deployment = await upload(r.apiUrl, r.apiKey, built, metadata);
-  out3(`${c.green("\u2713")} live at ${c.bold(c.cyan(deployment.url))} ${c.dim(`v${deployment.version}, ${kb(deployment.bundle_bytes)} gzipped`)}`);
-  for (const line of resourceLines(deployment.resources)) out3(line);
-  if (deployment.offerings_moved?.length) out3(`  offerings moved to it: ${deployment.offerings_moved.join(", ")}`);
-  if (deployment.webhook) out3(`  webhooks \u2192 ${deployment.webhook}`);
+  out4(`${c.green("\u2713")} live at ${c.bold(c.cyan(deployment.url))} ${c.dim(`v${deployment.version}, ${kb(deployment.bundle_bytes)} gzipped`)}`);
+  for (const line of resourceLines(deployment.resources)) out4(line);
+  if (deployment.offerings_moved?.length) out4(`  offerings moved to it: ${deployment.offerings_moved.join(", ")}`);
+  if (deployment.webhook) out4(`  webhooks \u2192 ${deployment.webhook}`);
   if (deployment.miniapp === false) {
-    out3(`  ${c.dim("mini app: off, not in the Ambasada app (`ambasada miniapp enable` adds one)")}`);
-    for (const issue of deployment.check?.issues.filter((i) => i.level === "problem") ?? []) out3(c.yellow(`! ${issue.message}`));
+    out4(`  ${c.dim("mini app: off, not in the Ambasada app (`ambasada miniapp enable` adds one)")}`);
+    for (const issue of deployment.check?.issues.filter((i) => i.level === "problem") ?? []) out4(c.yellow(`! ${issue.message}`));
   } else if (deployment.tier) {
-    const line = listingLine(deployment.tier, deployment.check);
-    out3(`  ${deployment.tier === "listed" || deployment.tier === "verified" ? c.green("\u2713") : c.yellow("!")} in the Ambasada app: ${line}`);
-    for (const issue of deployment.check?.issues.filter((i) => i.level === "problem") ?? []) out3(c.dim(`    ${issue.message}`));
+    printListing(deployment.tier, deployment.check, deployment.kind);
+    if (checkPending(deployment.check)) await waitForCheck(r.apiUrl, r.apiKey);
   }
   if (!await setProductUrl(project.root, deployment.url)) {
-    out3(c.yellow(`! add \`product: { url: "${deployment.url}" }\` to ambasada.config.ts`));
+    out4(c.yellow(`! add \`product: { url: "${deployment.url}" }\` to ambasada.config.ts`));
   }
   if (deployment.kind === "project") return;
   await hooks(deployment.url);
 }
+var CHECK_WAIT = { totalMs: 6e4, everyMs: 5e3 };
+async function waitForCheck(apiUrl, apiKey, wait = CHECK_WAIT) {
+  out4(`  checks: running (up to 5 min); ${c.bold("`ambasada check`")} shows the result`);
+  const deadline = Date.now() + wait.totalMs;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, wait.everyMs));
+    const state = await platformCheck(apiUrl, apiKey);
+    if (state && !checkPending(state.check)) {
+      printListing(state.tier, state.check, state.kind);
+      return state.check;
+    }
+  }
+  out4(c.dim("  still checking: run `ambasada check` in a few minutes"));
+  return null;
+}
 async function isMockApi(apiUrl) {
   try {
     const res = await fetch(`${apiUrl}/health`, { signal: AbortSignal.timeout(2e3) });
@@ -3504,19 +3666,27 @@ function detectTemplate(dir) {
   if (has("vite.config.ts", "vite.config.js", "vite.config.mjs", "vite.config.mts")) return "spa";
   return "worker";
 }
+var NEXT_BUILD_ENV = { __NEXT_PROCESSED_ENV: "true" };
+var EMPTY_NEXT_ENV = "export const production = {};\nexport const development = {};\nexport const test = {};\n";
+var VITE_BUILD = "const { createBuilder } = await import('vite'); const builder = await createBuilder({ envDir: false }, null); await builder.buildApp();";
 async function build(dir, template) {
   if (template === "next") {
-    out3(c.bold("opennextjs-cloudflare build"));
-    await run(bin(dir, "opennextjs-cloudflare", "@opennextjs/cloudflare"), ["build"], dir);
+    out4(c.bold("opennextjs-cloudflare build"));
+    await run(bin(dir, "opennextjs-cloudflare", "@opennextjs/cloudflare"), ["build"], dir, { env: NEXT_BUILD_ENV });
   } else if (template === "spa") {
-    out3(c.bold("vite build"));
-    await run(bin(dir, "vite"), ["build"], dir);
+    out4(c.bold("vite build"));
+    if (bin(dir, "vite").startsWith("npx ")) throw new CliError(`vite is not installed in ${dir}: run \`npm install\``);
+    await run([process.execPath, "--input-type=module", "-e", VITE_BUILD], [], dir);
+    const { file } = await readWranglerConfig(dir);
+    if (dirname6(file) !== dir) for (const local of [".dev.vars", ".env"]) await rm4(join10(dirname6(file), local), { force: true });
   }
 }
 async function bundle(dir, template) {
   const { file: configFile, config } = await readWranglerConfig(dir);
   const outdir = join10(dir, ".ambasada", "deploy");
   await rm4(outdir, { recursive: true, force: true });
+  const nextEnv = join10(dir, ".open-next", "cloudflare", "next-env.mjs");
+  if (template === "next" && existsSync9(nextEnv)) await writeFile5(nextEnv, EMPTY_NEXT_ENV);
   await run(bin(dir, "wrangler"), ["deploy", "--dry-run", "--outdir", outdir], dir, { capture: true });
   const modules = (await walk(outdir)).map((path) => ({ name: relative4(outdir, path).split(sep).join("/"), path })).filter((m) => !m.name.endsWith(".map") && m.name !== "README.md");
   const wanted = config.main ? `${basename(config.main, extname(config.main))}.js` : "index.js";
@@ -3547,9 +3717,9 @@ function deployMetadata(built, root) {
 }
 function durableObjects(config) {
   const bindings = config.durable_objects?.bindings ?? [];
-  const out7 = {};
+  const out8 = {};
   if (bindings.length) {
-    out7.durable_objects = bindings.map((b) => {
+    out8.durable_objects = bindings.map((b) => {
       if (!b.name || !b.class_name) throw new CliError("every durable_objects.bindings entry in wrangler.jsonc needs a name and a class_name");
       if (b.script_name) throw new CliError(`durable_objects binding ${b.name} points at another Worker (script_name ${b.script_name}): on ambasada.dev a Durable Object lives in its own app's Worker; export ${b.class_name} from this one and drop script_name`);
       return { name: b.name, class_name: b.class_name };
@@ -3557,13 +3727,13 @@ function durableObjects(config) {
   }
   const migrations = config.migrations ?? [];
   if (migrations.length) {
-    out7.migrations = migrations.map((m) => {
+    out8.migrations = migrations.map((m) => {
       if (!m || typeof m.tag !== "string" || !m.tag) throw new CliError("every entry of `migrations` in wrangler.jsonc needs a tag");
       const keep = ["tag", "new_sqlite_classes", "new_classes", "renamed_classes", "deleted_classes", "transferred_classes"];
       return Object.fromEntries(keep.filter((k) => m[k] !== void 0).map((k) => [k, m[k]]));
     });
   }
-  return out7;
+  return out8;
 }
 function storageWarnings(config) {
   const warnings = [];
@@ -3578,17 +3748,17 @@ function storageWarnings(config) {
   return warnings;
 }
 function localBindings(config) {
-  const out7 = {};
+  const out8 = {};
   const d1 = (config.d1_databases ?? []).filter((b) => b.binding);
-  if (d1.length) out7.d1_databases = d1.map((b) => ({ binding: b.binding, database_name: b.database_name ?? `local-${b.binding.toLowerCase()}`, database_id: b.database_id ?? `local-${b.binding.toLowerCase()}` }));
+  if (d1.length) out8.d1_databases = d1.map((b) => ({ binding: b.binding, database_name: b.database_name ?? `local-${b.binding.toLowerCase()}`, database_id: b.database_id ?? `local-${b.binding.toLowerCase()}` }));
   const kv2 = (config.kv_namespaces ?? []).filter((b) => b.binding);
-  if (kv2.length) out7.kv_namespaces = kv2.map((b) => ({ binding: b.binding, id: b.id ?? `local-${b.binding.toLowerCase()}` }));
+  if (kv2.length) out8.kv_namespaces = kv2.map((b) => ({ binding: b.binding, id: b.id ?? `local-${b.binding.toLowerCase()}` }));
   const r2 = (config.r2_buckets ?? []).filter((b) => b.binding);
-  if (r2.length) out7.r2_buckets = r2.map((b) => ({ binding: b.binding, bucket_name: b.bucket_name ?? `local-${b.binding.toLowerCase()}` }));
+  if (r2.length) out8.r2_buckets = r2.map((b) => ({ binding: b.binding, bucket_name: b.bucket_name ?? `local-${b.binding.toLowerCase()}` }));
   const dos = (config.durable_objects?.bindings ?? []).filter((b) => b.name && b.class_name && !b.script_name);
-  if (dos.length) out7.durable_objects = { bindings: dos.map((b) => ({ name: b.name, class_name: b.class_name })) };
-  if (config.migrations?.length) out7.migrations = config.migrations;
-  return out7;
+  if (dos.length) out8.durable_objects = { bindings: dos.map((b) => ({ name: b.name, class_name: b.class_name })) };
+  if (config.migrations?.length) out8.migrations = config.migrations;
+  return out8;
 }
 function resourceLines(r) {
   if (!r) return [];
@@ -3602,9 +3772,9 @@ function resourceLines(r) {
     if (created.has("FILES")) row("FILES", "R2", r.FILES?.name);
     lines.push(c.dim("    env.DB, env.KV, env.FILES in your Worker; `ambasada db migrate` creates your tables"));
   }
-  if (r.durable_objects?.length) {
-    lines.push(`  Durable Objects: ${r.durable_objects.map((d) => `${d.name} (${d.class_name})`).join(", ")}${r.migration_tag ? c.dim(` \xB7 migration ${r.migration_tag}`) : ""}`);
-  }
+  const bound = [r.DB && "DB", r.KV && "KV", r.FILES && "FILES"].filter((b) => !!b);
+  const objects = r.durable_objects?.length ? `DO: ${r.durable_objects.map((d) => `${d.name} (${d.class_name})`).join(", ")}${r.migration_tag ? c.dim(` \xB7 migration ${r.migration_tag}`) : ""}` : null;
+  if (bound.length || objects) lines.push(`  storage: ${[...bound, ...objects ? [objects] : []].join(" \xB7 ")}`);
   if (r.migrations_applied?.length) lines.push(`  Durable Object migrations applied: ${r.migrations_applied.join(", ")}`);
   if (r.missing_permissions?.length) {
     lines.push(c.yellow(`! storage not provisioned: the platform's Cloudflare token lacks ${r.missing_permissions.join(", ")}`));
@@ -3617,7 +3787,7 @@ async function upload(apiUrl, apiKey, built, metadata) {
   form.append("metadata", new Blob([JSON.stringify(metadata)], { type: "application/json" }));
   for (const m of built.modules) form.append(`module:${m.name}`, new Blob([await readFile5(m.path)], { type: /\.m?js$/.test(m.name) ? "application/javascript+module" : "" }), m.name);
   for (const a of built.assets) form.append(`asset:${a.path}`, new Blob([await readFile5(a.file)]), basename(a.file));
-  out3(c.dim(`uploading to ${apiUrl} \u2026`));
+  out4(c.dim(`uploading to ${apiUrl} \u2026`));
   let res;
   try {
     res = await fetch(`${apiUrl}/v1/product/deploy`, { method: "POST", headers: { authorization: `Bearer ${apiKey}`, accept: "application/json" }, body: form, signal: AbortSignal.timeout(3e5) });
@@ -3657,11 +3827,11 @@ async function smoke(built, company, root = built.dir) {
     try {
       await migrateLocal({ dir: built.dir, root: root2, config: configPath2, persistTo, wrangler: bin(built.dir, "wrangler") });
     } catch (error) {
-      out3(c.yellow(`! smoke test: could not apply db/migrations locally: ${error.message.split("\n")[0]}`));
+      out4(c.yellow(`! smoke test: could not apply db/migrations locally: ${error.message.split("\n")[0]}`));
     }
   }
   const port = await freePort();
-  out3(c.dim(`smoke test: wrangler dev on :${port} \u2026`));
+  out4(c.dim(`smoke test: wrangler dev on :${port} \u2026`));
   const child = spawn2(bin(built.dir, "wrangler"), ["dev", "--config", join10(smokeDir, "wrangler.json"), "--port", String(port), "--ip", "127.0.0.1", "--inspector-port", String(await freePort()), "--persist-to", persistTo, "--show-interactive-dev-session=false", "--log-level", "error"], {
     cwd: built.dir,
     stdio: ["ignore", "pipe", "pipe"],
@@ -3684,7 +3854,7 @@ ${(await res.text()).slice(0, 500)}`);
       await res.body?.cancel();
       checks.push({ method: check2.method, path: check2.path, status: res.status });
     }
-    out3(`${c.green("\u2713")} smoke test: ${checks.map((k) => `${k.method} ${k.path} ${k.status}`).join(", ")}`);
+    out4(`${c.green("\u2713")} smoke test: ${checks.map((k) => `${k.method} ${k.path} ${k.status}`).join(", ")}`);
     return { ok: true, skipped: false, checks, ms: Date.now() - started };
   } finally {
     child.kill("SIGTERM");
@@ -3791,7 +3961,7 @@ function bin(dir, name, pkg = name) {
   }
 }
 function run(command, args, cwd, opts = {}) {
-  const [file, ...pre] = command.split(" ");
+  const [file, ...pre] = typeof command === "string" ? command.split(" ") : command;
   return new Promise((resolveRun, reject) => {
     const child = spawn2(file, [...pre, ...args], { cwd, stdio: opts.capture ? ["ignore", "pipe", "pipe"] : "inherit", env: { ...process.env, WRANGLER_SEND_METRICS: "false", ...opts.env } });
     let output = "";
@@ -3808,7 +3978,7 @@ ${output.slice(-3e3)}` : ""}`));
 var kb = (n) => n > 1024 * 1024 ? `${(n / 1024 / 1024).toFixed(1)} MB` : `${Math.ceil(n / 1024)} KB`;
 
 // src/storage.ts
-var out4 = (s = "") => void process.stdout.write(`${s}
+var out5 = (s = "") => void process.stdout.write(`${s}
 `);
 var str2 = (v) => typeof v === "string" && v ? v : void 0;
 var MIGRATIONS_DIR = join11("db", "migrations");
@@ -3819,11 +3989,11 @@ async function target(flags) {
   const r = await resolve(flags);
   let local = flags.local === true;
   if (!local && await isMockApi(r.apiUrl)) {
-    out4(c.dim(`${r.apiUrl} is ambasada dev: using wrangler's local state (--local)`));
+    out5(c.dim(`${r.apiUrl} is ambasada dev: using wrangler's local state (--local)`));
     local = true;
   }
   if (!local && !r.apiKey && findProductDir(findRoot() ?? process.cwd())) {
-    out4(c.dim("not logged in: using wrangler's local state (--local); `ambasada login` for the hosted app"));
+    out5(c.dim("not logged in: using wrangler's local state (--local); `ambasada login` for the hosted app"));
     local = true;
   }
   if (local) {
@@ -3971,26 +4141,26 @@ async function migrateBeforeDev(root, print) {
 }
 function printMigrate(r, dryRun, where) {
   if (dryRun) {
-    out4(r.pending.length ? `would apply to ${where}: ${r.pending.join(", ")}` : `${where}: nothing to apply`);
+    out5(r.pending.length ? `would apply to ${where}: ${r.pending.join(", ")}` : `${where}: nothing to apply`);
   } else {
-    for (const name of r.applied) out4(`${c.green("\u2713")} applied ${c.bold(name)}`);
-    if (!r.applied.length) out4(`${c.green("\u2713")} ${where}: up to date`);
+    for (const name of r.applied) out5(`${c.green("\u2713")} applied ${c.bold(name)}`);
+    if (!r.applied.length) out5(`${c.green("\u2713")} ${where}: up to date`);
   }
-  if (r.skipped.length) out4(c.dim(`  already applied: ${r.skipped.join(", ")}`));
-  if (r.changed.length) out4(c.yellow(`! edited after they were applied (they don't run again; add a new migration instead): ${r.changed.join(", ")}`));
+  if (r.skipped.length) out5(c.dim(`  already applied: ${r.skipped.join(", ")}`));
+  if (r.changed.length) out5(c.yellow(`! edited after they were applied (they don't run again; add a new migration instead): ${r.changed.join(", ")}`));
 }
 function printResults(results) {
   results.forEach((r, i) => {
-    if (results.length > 1) out4(c.dim(`-- statement ${i + 1}`));
+    if (results.length > 1) out5(c.dim(`-- statement ${i + 1}`));
     if (r.columns.length) {
       const cols = r.columns.map((col, j) => r.columns.indexOf(col) === j ? col : `${col}:${j}`);
-      out4(table(r.rows.map((row) => Object.fromEntries(cols.map((col, j) => [col, row[j]]))), cols));
+      out5(table(r.rows.map((row) => Object.fromEntries(cols.map((col, j) => [col, row[j]]))), cols));
     }
     const m = r.meta ?? {};
     const parts = [`${r.rows.length} row${r.rows.length === 1 ? "" : "s"}`];
     if (m.changes) parts.push(`${m.changes} changed`);
     if (typeof m.duration_ms === "number") parts.push(`${Math.round(m.duration_ms * 100) / 100} ms`);
-    out4(c.dim(parts.join(" \xB7 ")));
+    out5(c.dim(parts.join(" \xB7 ")));
   });
 }
 async function query(t, sql) {
@@ -4007,7 +4177,7 @@ async function tables(t) {
 }
 async function shell(t, flags) {
   const where = t.local ? "local" : "ambasada.dev";
-  out4(`${c.bold("ambasada db shell")} ${c.dim(`(${where}) \xB7 end statements with ; \xB7 .tables \xB7 .schema [table] \xB7 .quit`)}`);
+  out5(`${c.bold("ambasada db shell")} ${c.dim(`(${where}) \xB7 end statements with ; \xB7 .tables \xB7 .schema [table] \xB7 .quit`)}`);
   const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: process.stdin.isTTY, historySize: 200, prompt: "db> " });
   let buffer = "";
   const run2 = async (line) => {
@@ -4015,19 +4185,19 @@ async function shell(t, flags) {
     if (!buffer && trimmed.startsWith(".")) {
       const [cmd, arg] = trimmed.split(/\s+/);
       if (cmd === ".quit" || cmd === ".exit") return rl.close();
-      if (cmd === ".tables") return out4(table((await tables(t)).map((x) => ({ table: x.name, rows: x.rows }))));
+      if (cmd === ".tables") return out5(table((await tables(t)).map((x) => ({ table: x.name, rows: x.rows }))));
       if (cmd === ".schema") {
-        for (const x of (await tables(t)).filter((x2) => !arg || x2.name === arg)) out4(`${x.sql ?? `-- ${x.name}`};`);
+        for (const x of (await tables(t)).filter((x2) => !arg || x2.name === arg)) out5(`${x.sql ?? `-- ${x.name}`};`);
         return;
       }
-      return out4(c.yellow(`unknown command ${cmd}: .tables, .schema [table], .quit`));
+      return out5(c.yellow(`unknown command ${cmd}: .tables, .schema [table], .quit`));
     }
     buffer += `${line}
 `;
     if (!/;\s*$/.test(trimmed)) return;
     const sql = buffer;
     buffer = "";
-    if (flags.json) out4(JSON.stringify(await query(t, sql), null, 2));
+    if (flags.json) out5(JSON.stringify(await query(t, sql), null, 2));
     else printResults(await query(t, sql));
   };
   rl.prompt();
@@ -4035,7 +4205,7 @@ async function shell(t, flags) {
     try {
       await run2(line);
     } catch (error) {
-      out4(c.red(`\u2717 ${error.message}`));
+      out5(c.red(`\u2717 ${error.message}`));
     }
     rl.setPrompt(buffer ? "  > " : "db> ");
     rl.prompt();
@@ -4052,11 +4222,11 @@ async function db(args, flags) {
       const dryRun = flags["dry-run"] === true;
       if (t.local) {
         const r2 = await migrateLocal({ dir: t.dir, root, wrangler: t.wrangler, dryRun });
-        if (flags.json) return out4(JSON.stringify(r2, null, 2));
+        if (flags.json) return out5(JSON.stringify(r2, null, 2));
         return printMigrate(r2, dryRun, "local DB");
       }
       const r = await api(t, "POST", "/v1/dev/db/migrate", { json: { migrations, dry_run: dryRun } });
-      if (flags.json) return out4(JSON.stringify(r, null, 2));
+      if (flags.json) return out5(JSON.stringify(r, null, 2));
       return printMigrate({ applied: names(r.applied), skipped: names(r.skipped), changed: names(r.changed), pending: names(r.pending) }, dryRun, "the app's DB");
     }
     case "shell":
@@ -4065,19 +4235,19 @@ async function db(args, flags) {
       const sql = rest.join(" ").trim();
       if (!sql) return shell(t, flags);
       const results = await query(t, sql);
-      if (flags.json) return out4(JSON.stringify({ results }, null, 2));
+      if (flags.json) return out5(JSON.stringify({ results }, null, 2));
       return printResults(results);
     }
     case "tables": {
       const list = await tables(t);
-      if (flags.json) return out4(JSON.stringify({ tables: list }, null, 2));
-      return out4(table(list.map((x) => ({ table: x.name, rows: x.rows, columns: x.columns.length ? x.columns.map((col) => col.name).join(", ") : "" }))));
+      if (flags.json) return out5(JSON.stringify({ tables: list }, null, 2));
+      return out5(table(list.map((x) => ({ table: x.name, rows: x.rows, columns: x.columns.length ? x.columns.map((col) => col.name).join(", ") : "" }))));
     }
     case "migrations": {
       const applied = t.local ? ((await localQuery(t, `${CREATE_MIGRATIONS}
 SELECT name, applied_at FROM ${MIGRATIONS_TABLE} ORDER BY id;`))[1]?.rows ?? []).map((r) => ({ name: r[0], applied_at: r[1] })) : (await api(t, "GET", "/v1/dev/db/migrations")).applied ?? [];
-      if (flags.json) return out4(JSON.stringify({ applied }, null, 2));
-      return out4(table(applied, ["name", "applied_at"]));
+      if (flags.json) return out5(JSON.stringify({ applied }, null, 2));
+      return out5(table(applied, ["name", "applied_at"]));
     }
     default:
       throw new CliError(`usage: ambasada db migrate [--dry-run] | shell ["<sql>"] | tables | migrations   (--local: wrangler's local DB)`);
@@ -4105,18 +4275,18 @@ async function kv(args, flags) {
           cursor = r.cursor;
         }
       }
-      if (flags.json) return out4(JSON.stringify({ keys: keys3 }, null, 2));
-      return out4(table(keys3.map((k) => ({ key: k.name, expires: k.expiration ? new Date(k.expiration * 1e3).toISOString() : "" })), ["key", "expires"]));
+      if (flags.json) return out5(JSON.stringify({ keys: keys3 }, null, 2));
+      return out5(table(keys3.map((k) => ({ key: k.name, expires: k.expiration ? new Date(k.expiration * 1e3).toISOString() : "" })), ["key", "expires"]));
     }
     case "get": {
       if (!key) throw new CliError("usage: ambasada kv get <key>");
       if (t.local) return void process.stdout.write(await wrangler(t, ["kv", "key", "get", key, "--binding", PLATFORM_STORAGE.kv, "--text"]));
       const r = await api(t, "GET", kvPath(key));
-      if (flags.json) return out4(JSON.stringify(r, null, 2));
+      if (flags.json) return out5(JSON.stringify(r, null, 2));
       if (r.binary) {
-        out4(c.dim(`(${r.size} bytes, binary; base64:)`));
+        out5(c.dim(`(${r.size} bytes, binary; base64:)`));
       }
-      return out4(r.value ?? "");
+      return out5(r.value ?? "");
     }
     case "put":
     case "set": {
@@ -4125,19 +4295,19 @@ async function kv(args, flags) {
       const fromFile = value.startsWith("@") ? value.slice(1) : null;
       if (t.local) {
         await wrangler(t, ["kv", "key", "put", key, ...fromFile ? ["--path", fromFile] : [value], "--binding", PLATFORM_STORAGE.kv, ...ttl ? ["--ttl", ttl] : []]);
-        return out4(`${c.green("\u2713")} ${key} (local)`);
+        return out5(`${c.green("\u2713")} ${key} (local)`);
       }
       const raw = fromFile ? new Uint8Array(await readFile6(fromFile)) : value;
       const r = await api(t, "PUT", `${kvPath(key)}${ttl ? `?ttl=${ttl}` : ""}`, { raw, type: fromFile ? "application/octet-stream" : "text/plain; charset=utf-8" });
-      if (flags.json) return out4(JSON.stringify(r, null, 2));
-      return out4(`${c.green("\u2713")} ${r.key} ${c.dim(`${r.size} bytes${ttl ? `, expires in ${ttl} s` : ""}`)}`);
+      if (flags.json) return out5(JSON.stringify(r, null, 2));
+      return out5(`${c.green("\u2713")} ${r.key} ${c.dim(`${r.size} bytes${ttl ? `, expires in ${ttl} s` : ""}`)}`);
     }
     case "delete":
     case "rm": {
       if (!key) throw new CliError("usage: ambasada kv delete <key>");
       if (t.local) await wrangler(t, ["kv", "key", "delete", key, "--binding", PLATFORM_STORAGE.kv]);
       else await api(t, "DELETE", kvPath(key));
-      return out4(`${c.green("\u2713")} deleted ${key}${t.local ? " (local)" : ""}`);
+      return out5(`${c.green("\u2713")} deleted ${key}${t.local ? " (local)" : ""}`);
     }
     default:
       throw new CliError("usage: ambasada kv list [prefix] | get <key> | put <key> <value | @file> [--ttl N] | delete <key>   (--local: wrangler's local KV)");
@@ -4204,8 +4374,8 @@ async function files(args, flags) {
         if (!r.truncated || !r.cursor) break;
         cursor = r.cursor;
       }
-      if (flags.json) return out4(JSON.stringify({ objects }, null, 2));
-      return out4(table(objects.map((o) => ({ key: o.key, size: size(o.size), type: o.content_type ?? "", uploaded: o.uploaded ?? "" })), ["key", "size", "type", "uploaded"]));
+      if (flags.json) return out5(JSON.stringify({ objects }, null, 2));
+      return out5(table(objects.map((o) => ({ key: o.key, size: size(o.size), type: o.content_type ?? "", uploaded: o.uploaded ?? "" })), ["key", "size", "type", "uploaded"]));
     }
     case "put":
     case "upload": {
@@ -4215,11 +4385,11 @@ async function files(args, flags) {
       const type = str2(flags["content-type"]) ?? contentTypeOf(a);
       if (t.local) {
         await wrangler(t, ["r2", "object", "put", `${await localBucket(t)}/${key}`, "--file", a, "--content-type", type]);
-        return out4(`${c.green("\u2713")} ${key} (local) \u2192 ${await fileUrl(t, key, flags)}`);
+        return out5(`${c.green("\u2713")} ${key} (local) \u2192 ${await fileUrl(t, key, flags)}`);
       }
       const r = await api(t, "PUT", `/v1/dev/files/${keyPath(key)}`, { raw: new Uint8Array(await readFile6(a)), type });
-      if (flags.json) return out4(JSON.stringify(r, null, 2));
-      return out4(`${c.green("\u2713")} ${r.key} ${c.dim(size(r.size))} \u2192 ${c.cyan(r.url ?? await fileUrl(t, key, flags))}`);
+      if (flags.json) return out5(JSON.stringify(r, null, 2));
+      return out5(`${c.green("\u2713")} ${r.key} ${c.dim(size(r.size))} \u2192 ${c.cyan(r.url ?? await fileUrl(t, key, flags))}`);
     }
     case "delete":
     case "rm": {
@@ -4227,11 +4397,11 @@ async function files(args, flags) {
       const key = checkKey(a);
       if (t.local) await wrangler(t, ["r2", "object", "delete", `${await localBucket(t)}/${key}`]);
       else await api(t, "DELETE", `/v1/dev/files/${keyPath(key)}`);
-      return out4(`${c.green("\u2713")} deleted ${key}${t.local ? " (local)" : ""}`);
+      return out5(`${c.green("\u2713")} deleted ${key}${t.local ? " (local)" : ""}`);
     }
     case "url": {
       if (!a) throw new CliError("usage: ambasada files url <key>");
-      return out4(await fileUrl(t, checkKey(a), flags));
+      return out5(await fileUrl(t, checkKey(a), flags));
     }
     default:
       throw new CliError("usage: ambasada files list [prefix] | put <path> [key] [--content-type T] | delete <key> | url <key>   (--local: wrangler's local bucket)");
@@ -4245,7 +4415,7 @@ import { existsSync as existsSync11 } from "node:fs";
 import { chmod as chmod2, mkdir as mkdir5, mkdtemp as mkdtemp2, readFile as readFile7, rename, rm as rm6, writeFile as writeFile7 } from "node:fs/promises";
 import { tmpdir as tmpdir2 } from "node:os";
 import { join as join12 } from "node:path";
-var out5 = (s = "") => process.stdout.write(`${s}
+var out6 = (s = "") => process.stdout.write(`${s}
 `);
 var CLOUDFLARED_VERSION = "2026.10.7";
 var CLOUDFLARED_ASSETS = {
@@ -4256,7 +4426,7 @@ var CLOUDFLARED_ASSETS = {
   "win32-x64": { file: "cloudflared-windows-amd64.exe", sha256: "2493dbc168923bb3e59e5e7716f71deced92992eea9acd6e9d74f84ac7751343" }
 };
 var RELEASES = "https://github.com/cloudflare/cloudflared/releases/download";
-async function cloudflaredBin(print = out5) {
+async function cloudflaredBin(print = out6) {
   if (process.env.AMBASADA_CLOUDFLARED) return process.env.AMBASADA_CLOUDFLARED;
   if (spawnSync("cloudflared", ["--version"], { stdio: "ignore" }).status === 0) return "cloudflared";
   const dest = join12(configDir(), "bin", `cloudflared-${CLOUDFLARED_VERSION}${process.platform === "win32" ? ".exe" : ""}`);
@@ -4313,7 +4483,7 @@ async function call(opts, method, path, body) {
   return { status: res.status, json: await res.json().catch(() => ({})) };
 }
 async function startTunnel(opts) {
-  const print = opts.print ?? out5;
+  const print = opts.print ?? out6;
   const bin2 = await cloudflaredBin(print);
   const opened = await call(opts, "POST", "/v1/product/tunnel", { port: opts.port, force: opts.force === true, register: opts.register !== false, ...opts.webhookPath ? { webhook_path: opts.webhookPath } : {} });
   if (opened.status !== 201) throw new CliError(`tunnel refused: ${opened.json.error?.code ?? opened.status}: ${opened.json.error?.message ?? "no answer"}`);
@@ -4394,7 +4564,7 @@ async function waitForPublic(url, timeoutMs = 18e4, streak = 1) {
   }
 }
 async function startTunnelAndWait(opts) {
-  const print = opts.print ?? out5;
+  const print = opts.print ?? out6;
   const session = await startTunnel(opts);
   const { info } = session;
   print(c.dim(info.dns_propagating ? `publishing ${info.hostname} on Cloudflare's edge (first time only, up to 2 minutes) \u2026` : `connecting ${info.hostname} \u2026`));
@@ -4424,7 +4594,7 @@ function untilStopped(ended) {
     });
   });
 }
-function printOpened(info, print = out5) {
+function printOpened(info, print = out6) {
   print(`${c.green("\u2713")} ${c.bold(c.cyan(info.url))} \u2192 ${info.local}  ${c.dim("(press Ctrl+C to stop)")}`);
   if (info.registered) {
     print(`  the village sends buyers, Checkout and webhooks here until you stop${info.previous_url ? c.dim(` (then back to ${info.previous_url})`) : ""}`);
@@ -4432,7 +4602,7 @@ function printOpened(info, print = out5) {
     if (info.webhook) print(`  webhooks \u2192 ${info.webhook.url}`);
   } else print(c.dim("  only exposed: the product URL, offerings and webhook stay where they are (--no-register)"));
 }
-function printClosed(closed, print = out5) {
+function printClosed(closed, print = out6) {
   if (!closed) print(c.yellow("! could not reach the village to close the tunnel: it closes itself within 5 minutes"));
   else print(`${c.green("\u2713")} tunnel closed${closed.url ? `; product URL back to ${closed.url}` : ""}`);
 }
@@ -4462,32 +4632,32 @@ async function tunnel(_args, flags) {
   try {
     await fetch(local, { signal: AbortSignal.timeout(2e3) });
   } catch {
-    out5(c.yellow(`! nothing answers on ${local} yet: start your dev server there (or pass --port)`));
+    out6(c.yellow(`! nothing answers on ${local} yet: start your dev server there (or pass --port)`));
   }
   const root = findRoot();
   if (root && existsSync11(join12(root, ".env")) && /AMBASADA_API_URL=http:\/\/(127\.0\.0\.1|localhost)/.test(await readFile7(join12(root, ".env"), "utf8"))) {
-    out5(c.yellow("! your .env points AMBASADA_API_URL at the mock: real buyers' receipts won't verify. `ambasada dev --tunnel` runs your dev server against the village instead"));
+    out6(c.yellow("! your .env points AMBASADA_API_URL at the mock: real buyers' receipts won't verify. `ambasada dev --tunnel` runs your dev server against the village instead"));
   }
   const register = flags["no-register"] !== true;
   const session = await startTunnelAndWait({ apiUrl: r.apiUrl, apiKey: r.apiKey, port, force: flags.force === true, register, webhookPath: register ? webhookPath(root) : void 0 });
-  if (flags.json) out5(JSON.stringify({ ...session.info, token: void 0 }, null, 2));
+  if (flags.json) out6(JSON.stringify({ ...session.info, token: void 0 }, null, 2));
   else printOpened(session.info);
   const reason = await untilStopped(session.ended);
-  if (reason) out5(c.yellow(`! ${reason}`));
-  else out5("\nclosing the tunnel");
+  if (reason) out6(c.yellow(`! ${reason}`));
+  else out6("\nclosing the tunnel");
   printClosed(await session.close());
   if (reason) throw new CliError(reason);
 }
 
 // src/commands.ts
-var SDK_VERSION = /^\d+\.\d+\.\d+$/.test("0.8.5") ? `^${"0.8.5"}` : "latest";
+var SDK_VERSION = /^\d+\.\d+\.\d+$/.test("0.8.6") ? `^${"0.8.6"}` : "latest";
 var DEV_PORT = 8788;
-var out6 = (s = "") => process.stdout.write(`${s}
+var out7 = (s = "") => process.stdout.write(`${s}
 `);
 var str3 = (v) => typeof v === "string" && v ? v : void 0;
 var json = (flags, value) => {
   if (!flags.json) return false;
-  out6(JSON.stringify(value, null, 2));
+  out7(JSON.stringify(value, null, 2));
   return true;
 };
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -4506,8 +4676,8 @@ async function deviceLogin(apiUrl) {
   if (res.status === 404 || res.status === 405 || !(res.headers.get("content-type") ?? "").includes("json")) return null;
   if (!res.ok) return null;
   const start = await res.json();
-  out6(`Open ${c.bold(start.verification_uri_complete ?? start.verification_uri)}`);
-  out6(`and confirm the code ${c.bold(c.cyan(start.user_code))} with your Ambasada ID.`);
+  out7(`Open ${c.bold(start.verification_uri_complete ?? start.verification_uri)}`);
+  out7(`and confirm the code ${c.bold(c.cyan(start.user_code))} with your Ambasada ID.`);
   let interval = Math.max(1, start.interval ?? 5) * 1e3;
   const deadline = Date.now() + (start.expires_in ?? 600) * 1e3;
   while (Date.now() < deadline) {
@@ -4545,15 +4715,15 @@ async function login(_args, flags) {
     if (device) key = device.token;
   }
   if (!key) {
-    out6(`Paste your app's key: ${c.bold("https://developer.ambasada.dev")} \u2192 New app (or Settings \u2192 New key).`);
+    out7(`Paste your app's key: ${c.bold("https://developer.ambasada.dev")} \u2192 New app (or Settings \u2192 New key).`);
     key = await prompt("API key: ");
   }
   if (!key) throw new CliError("no key given");
   const who = await whoseKey(apiUrl, key);
   const { company: _old, apps, ...stored } = await readConfig();
   await writeConfig({ ...stored, apiUrl, apiKey: key, project: who.id, apps: { ...apps, [who.id]: { apiKey: key, apiUrl } } });
-  out6(`${c.green("\u2713")} logged in as ${c.bold(who.id)} on ${apiUrl} ${c.dim(`(saved to ${configPath()})`)}`);
-  if (here && here !== who.id) out6(c.yellow(`! this folder is the app ${here}, and the key is ${who.id}'s: deploy and storage commands here will refuse it`));
+  out7(`${c.green("\u2713")} logged in as ${c.bold(who.id)} on ${apiUrl} ${c.dim(`(saved to ${configPath()})`)}`);
+  if (here && here !== who.id) out7(c.yellow(`! this folder is the app ${here}, and the key is ${who.id}'s: deploy and storage commands here will refuse it`));
 }
 async function logout(_args = [], flags = {}) {
   const { here } = await resolve(flags);
@@ -4561,15 +4731,15 @@ async function logout(_args = [], flags = {}) {
   const { [here ?? ""]: _here, ...others } = apps;
   const kept = flags.all ? {} : here ? others : apps;
   await writeConfig({ ...rest, ...Object.keys(kept).length ? { apps: kept } : {} });
-  out6(flags.all ? "logged out of every app" : here && _here ? `logged out of ${here}` : "logged out");
+  out7(flags.all ? "logged out of every app" : here && _here ? `logged out of ${here}` : "logged out");
 }
 async function whoami(_args, flags) {
   const r = await resolve(flags);
   if (!r.apiKey) throw new CliError("not logged in: run `ambasada login` (or set AMBASADA_API_KEY)");
   const who = await whoseKey(r.apiUrl, r.apiKey);
   if (json(flags, { apiUrl: r.apiUrl, project: who.id, kind: who.kind, folder: r.here ?? null })) return;
-  out6(`${c.bold(who.id)} on ${r.apiUrl}`);
-  if (r.here && r.here !== who.id) out6(c.yellow(`! this folder is the app ${r.here}: \`ambasada login --key \u2026\` here with its key`));
+  out7(`${c.bold(who.id)} on ${r.apiUrl}`);
+  if (r.here && r.here !== who.id) out7(c.yellow(`! this folder is the app ${r.here}: \`ambasada login --key \u2026\` here with its key`));
 }
 function addonFlag(flags) {
   if (flags.village || str3(flags.for) === "hackaton" || str3(flags.for) === "village") return "village";
@@ -4640,26 +4810,26 @@ async function init(args, flags) {
   let installed = existsSync12(join13(target2, "node_modules"));
   const missing = installed ? missingDependencies(target2) : [];
   if (missing.length && !flags["no-install"]) {
-    out6(c.dim(`npm install (${missing.join(", ")}) \u2026`));
+    out7(c.dim(`npm install (${missing.join(", ")}) \u2026`));
     try {
       npmInstall(target2);
     } catch {
-      out6(c.yellow(`! npm install failed: run it yourself (${missing.join(", ")})`));
+      out7(c.yellow(`! npm install failed: run it yourself (${missing.join(", ")})`));
       installed = false;
     }
   } else if (missing.length) installed = false;
   const rel = args[0] ?? ".";
-  out6(`${c.green("\u2713")} ${c.bold(name)} (${id}) scaffolded in ${target2} ${c.dim(`(template ${template}${addon ? `, ${addon.short}` : ""})`)}`);
-  out6(miniapp2 ? `  mini app: on at ${c.bold(miniapp2.entry)} ${c.dim(`(${miniapp2.entry === "/" ? "the in-app glue" : "the in-app layout"}, icon.png, the manifest from ambasada.config.ts)`)}` : `  ${stateLine({ on: false, entry: null, source: null, file: null })}`);
-  for (const m of miniapp2?.manual ?? []) out6(c.yellow(`! by hand: ${m}`));
-  out6("");
-  out6("Next:");
-  if (rel !== ".") out6(`  cd ${rel}`);
-  if (!installed) out6("  npm install");
-  out6(`  npm run dev             ${c.dim("# ambasada dev: the mock API on :8788 + your app on http://localhost:3000")}`);
-  for (const line of addon?.overlay?.next ?? []) out6(`  ${line}`);
-  out6("");
-  out6(`Then ${c.bold("ambasada login")} (a key from https://developer.ambasada.dev \u2192 New app) and ${c.bold("ambasada deploy")}. See README.md.`);
+  out7(`${c.green("\u2713")} ${c.bold(name)} (${id}) scaffolded in ${target2} ${c.dim(`(template ${template}${addon ? `, ${addon.short}` : ""})`)}`);
+  out7(miniapp2 ? `  mini app: on at ${c.bold(miniapp2.entry)} ${c.dim(`(${miniapp2.entry === "/" ? "the in-app glue" : "the in-app layout"}, icon.png, the manifest from ambasada.config.ts)`)}` : `  ${stateLine({ on: false, entry: null, source: null, file: null })}`);
+  for (const m of miniapp2?.manual ?? []) out7(c.yellow(`! by hand: ${m}`));
+  out7("");
+  out7("Next:");
+  if (rel !== ".") out7(`  cd ${rel}`);
+  if (!installed) out7("  npm install");
+  out7(`  npm run dev             ${c.dim("# ambasada dev: the mock API on :8788 + your app on http://localhost:3000")}`);
+  for (const line of addon?.overlay?.next ?? []) out7(`  ${line}`);
+  out7("");
+  out7(`Then ${c.bold("ambasada login")} (a key from https://developer.ambasada.dev \u2192 New app) and ${c.bold("ambasada deploy")}. See README.md.`);
 }
 async function applyAddon(root, template, short, flags, fresh) {
   const pkgName = KNOWN_ADDONS[short] ?? short;
@@ -4671,7 +4841,7 @@ async function applyAddon(root, template, short, flags, fresh) {
   const find = () => findAddons(root).find((dir2) => readJsonName(dir2) === pkgName) ?? besideCli(pkgName);
   let dir = find() ?? packageDir(pkgName, root);
   if (!dir && !flags["no-install"]) {
-    out6(c.dim(`npm install ${pkgName} \u2026`));
+    out7(c.dim(`npm install ${pkgName} \u2026`));
     try {
       npmInstall(root);
     } catch {
@@ -4733,9 +4903,9 @@ async function add(args, flags) {
   if (entry2 && !miniappState(root, miniappOfSource(root).miniapp).on) printEnabled(await enableMiniapp(root, entry2, flags, { template, releaseLine: SDK_VERSION }), root);
   const info = await readProjectInfo(root) ?? { template, devkit: devkitVersion(), addons: [] };
   await writeProjectInfo(root, { ...info, addons: [.../* @__PURE__ */ new Set([...info.addons, addon.short])] });
-  out6(`${c.green("\u2713")} ${c.bold(addon.name)} added ${c.dim(`(${CONFIG_FILE}, package.json, .env, .claude/skills; existing files kept, --force overwrites)`)}`);
-  for (const line of addon.overlay?.next ?? []) out6(`  ${line}`);
-  out6(`  ambasada ${addon.short} --help`);
+  out7(`${c.green("\u2713")} ${c.bold(addon.name)} added ${c.dim(`(${CONFIG_FILE}, package.json, .env, .claude/skills; existing files kept, --force overwrites)`)}`);
+  for (const line of addon.overlay?.next ?? []) out7(`  ${line}`);
+  out7(`  ambasada ${addon.short} --help`);
 }
 async function check(args, flags) {
   const target2 = args[0];
@@ -4753,15 +4923,25 @@ async function check(args, flags) {
   }
   if (!json(flags, report)) {
     const on = report.miniapp?.on !== false;
-    out6(on ? `mini app: on at ${c.bold(report.miniapp?.entry ?? "/")}` : stateLine({ on: false, entry: null, source: null, file: null }));
-    for (const p of report.problems) out6(`${c.red("\u2717")} ${p.message} ${c.dim(`(${p.code})`)}`);
-    for (const w of report.warnings) out6(`${c.yellow("!")} ${w.message} ${c.dim(`(${w.code})`)}`);
-    for (const n of report.notes.filter((n2) => !n2.startsWith("mini app: off"))) out6(`${c.dim("\xB7")} ${c.dim(n)}`);
+    out7(on ? `mini app: on at ${c.bold(report.miniapp?.entry ?? "/")}` : stateLine({ on: false, entry: null, source: null, file: null }));
+    for (const p of report.problems) out7(`${c.red("\u2717")} ${p.message} ${c.dim(`(${p.code})`)}`);
+    for (const w of report.warnings) out7(`${c.yellow("!")} ${w.message} ${c.dim(`(${w.code})`)}`);
+    for (const n of report.notes.filter((n2) => !n2.startsWith("mini app: off"))) out7(`${c.dim("\xB7")} ${c.dim(n)}`);
     const warnings = report.warnings.length ? c.dim(` (${report.warnings.length} warning${report.warnings.length === 1 ? "" : "s"})`) : "";
-    if (report.ok) out6(`${c.green("\u2713")} ${report.target} passes the ${on ? "mini-app" : "product"} checks${warnings}`);
+    if (report.ok) out7(`${c.green("\u2713")} ${report.target} passes the ${on ? "mini-app" : "product"} checks${warnings}`);
+    if (!target2 && on) await printPlatformCheck(flags);
   }
   if (!report.ok) throw new CliError(`${report.problems.length} problem${report.problems.length === 1 ? "" : "s"} in ${report.target}: fix them and run \`ambasada check\` again`);
 }
+async function printPlatformCheck(flags) {
+  const r = await resolve(flags).catch(() => null);
+  if (!r?.apiKey || !r.here || r.project !== r.here) return;
+  const state = await platformCheck(r.apiUrl, r.apiKey);
+  if (!state?.check) return;
+  out7(`on ambasada.dev ${c.dim(`(checked ${state.check.checked_at.slice(0, 16).replace("T", " ")} UTC)`)}:`);
+  printListing(state.tier, state.check, state.kind);
+  if (checkPending(state.check)) out7(c.dim(`    the webhook ping is retried until ${state.check.pending_until?.slice(11, 16) ?? "5 min after the deploy"} UTC: run \`ambasada check\` again`));
+}
 var miniapp = (args, flags) => miniappCommand(args, flags, SDK_VERSION);
 async function dev(_args, flags) {
   const port = Number(str3(flags.port) ?? DEV_PORT);
@@ -4782,12 +4962,12 @@ async function dev(_args, flags) {
     company,
     appWebhook: appWebhook ?? void 0,
     extensions: addons().mocks,
-    log: (line) => out6(`${c.dim((/* @__PURE__ */ new Date()).toISOString().slice(11, 19))} ${line}`)
+    log: (line) => out7(`${c.dim((/* @__PURE__ */ new Date()).toISOString().slice(11, 19))} ${line}`)
   });
-  out6(`${c.bold("ambasada dev")} \xB7 mock Ambasada API on ${c.cyan(mock.url)}  ${c.dim("(dashboard: open it in a browser)")}`);
-  out6(`  app ${c.bold(company)} \xB7 key ${c.bold(DEV_KEY)} \xB7 sign-in as a fake visitor \xB7 notifications to the mock hub`);
-  out6(`  in your app: AMBASADA_API_URL=${mock.url} AMBASADA_API_KEY=${DEV_KEY}`);
-  if (inApp) out6(`  ${stateLine(inApp)}`);
+  out7(`${c.bold("ambasada dev")} \xB7 mock Ambasada API on ${c.cyan(mock.url)}  ${c.dim("(dashboard: open it in a browser)")}`);
+  out7(`  app ${c.bold(company)} \xB7 key ${c.bold(DEV_KEY)} \xB7 sign-in as a fake visitor \xB7 notifications to the mock hub`);
+  out7(`  in your app: AMBASADA_API_URL=${mock.url} AMBASADA_API_KEY=${DEV_KEY}`);
+  if (inApp) out7(`  ${stateLine(inApp)}`);
   const env2 = {
     AMBASADA_API_URL: mock.url,
     AMBASADA_API_KEY: DEV_KEY,
@@ -4801,33 +4981,33 @@ async function dev(_args, flags) {
     AMBASADA_HUB_URL: mock.url,
     AMBASADA_APP_ORIGIN: new URL(productUrl).origin
   };
-  const ctx = { project, mockUrl: mock.url, productUrl, company, env: env2, hints: [], once: flags.once === true, out: out6 };
+  const ctx = { project, mockUrl: mock.url, productUrl, company, env: env2, hints: [], once: flags.once === true, out: out7 };
   await addons().dev(ctx);
-  if (!project) out6(c.dim(`  (no ${CONFIG_FILE} here: only the mock)`));
-  const hints = () => ctx.hints.forEach((h) => out6(h));
+  if (!project) out7(c.dim(`  (no ${CONFIG_FILE} here: only the mock)`));
+  const hints = () => ctx.hints.forEach((h) => out7(h));
   if (flags.once) {
     hints();
     await mock.close();
     return;
   }
-  if (stack && project) await migrateBeforeDev(project.root, out6);
-  const app = stack && bin2 ? startApp(project.root, stack, bin2, new URL(productUrl), env2, out6, c.dim(`${stack.pkg} \u2502`)) : null;
+  if (stack && project) await migrateBeforeDev(project.root, out7);
+  const app = stack && bin2 ? startApp(project.root, stack, bin2, new URL(productUrl), env2, out7, c.dim(`${stack.pkg} \u2502`)) : null;
   if (app) {
-    out6(`  starting ${c.bold(stack.label)} on ${productUrl} ${c.dim("(your app, with AMBASADA_* pointed at the mock)")}`);
+    out7(`  starting ${c.bold(stack.label)} on ${productUrl} ${c.dim("(your app, with AMBASADA_* pointed at the mock)")}`);
     void app.ready.then((ok) => {
       if (ok) {
-        out6(`${c.green("\u2713")} app on ${c.cyan(productUrl)}`);
-        if (inApp?.on) out6(`  inside the Ambasada app: ${c.cyan(new URL(`${inApp.entry ?? "/"}?ambasada_shell=mock`, productUrl).toString())} ${c.dim("(fake shell: host bar insets, silent sign-in)")}`);
+        out7(`${c.green("\u2713")} app on ${c.cyan(productUrl)}`);
+        if (inApp?.on) out7(`  inside the Ambasada app: ${c.cyan(new URL(`${inApp.entry ?? "/"}?ambasada_shell=mock`, productUrl).toString())} ${c.dim("(fake shell: host bar insets, silent sign-in)")}`);
         hints();
         if (appWebhook) void playHub(mock, appWebhook);
-      } else if (app.child.exitCode === null) out6(c.yellow(`! ${productUrl} does not answer yet`));
+      } else if (app.child.exitCode === null) out7(c.yellow(`! ${productUrl} does not answer yet`));
     });
   } else hints();
   let closing;
   const close = () => closing ??= mock.close();
   const code = await new Promise((resolveStop) => {
     const stop2 = () => {
-      out6("\nstopping ambasada dev");
+      out7("\nstopping ambasada dev");
       app?.child.kill("SIGTERM");
       void close().then(() => resolveStop(null));
     };
@@ -4858,18 +5038,18 @@ async function devTunnel(flags) {
     ...info.webhook ? { AMBASADA_WEBHOOK_SECRET: info.webhook.secret } : {},
     ...info.sign_in ? { AMBASADA_AUTH_CLIENT_ID: info.sign_in.client_id, AMBASADA_AUTH_CLIENT_SECRET: info.sign_in.client_secret, AMBASADA_AUTH_ISSUER: info.sign_in.issuer } : {}
   };
-  out6(`${c.bold("ambasada dev --tunnel")} \xB7 ${c.bold(company)} on ${r.apiUrl} ${c.dim("(the real API, no mock)")}`);
+  out7(`${c.bold("ambasada dev --tunnel")} \xB7 ${c.bold(company)} on ${r.apiUrl} ${c.dim("(the real API, no mock)")}`);
   printOpened(info);
-  if (!info.sign_in) out6(c.dim("  Sign in with Ambasada is not set up on this API: login keeps the .env values"));
-  const app = startApp(project.root, stack, bin2, productUrl, env2, out6, c.dim(`${stack.pkg} \u2502`));
-  out6(`  starting ${c.bold(stack.label)} on ${productUrl.origin}`);
+  if (!info.sign_in) out7(c.dim("  Sign in with Ambasada is not set up on this API: login keeps the .env values"));
+  const app = startApp(project.root, stack, bin2, productUrl, env2, out7, c.dim(`${stack.pkg} \u2502`));
+  out7(`  starting ${c.bold(stack.label)} on ${productUrl.origin}`);
   void app.ready.then((ok) => {
-    if (ok) out6(`${c.green("\u2713")} product on ${productUrl.origin}, live at ${c.cyan(info.url)}`);
-    else if (app.child.exitCode === null) out6(c.yellow(`! ${productUrl.origin} does not answer yet`));
+    if (ok) out7(`${c.green("\u2713")} product on ${productUrl.origin}, live at ${c.cyan(info.url)}`);
+    else if (app.child.exitCode === null) out7(c.yellow(`! ${productUrl.origin} does not answer yet`));
   });
   const appExit = new Promise((resolveExit) => app.child.once("exit", (code) => resolveExit(`${stack.label} exited${code ? ` with code ${code}` : ""}`)));
   const reason = await untilStopped(Promise.race([session.ended, appExit]));
-  out6(reason ? c.yellow(`! ${reason}`) : "\nstopping ambasada dev --tunnel");
+  out7(reason ? c.yellow(`! ${reason}`) : "\nstopping ambasada dev --tunnel");
   app.child.kill("SIGTERM");
   printClosed(await session.close());
   if (reason) throw new CliError(reason);
@@ -4888,12 +5068,12 @@ function manifestWebhook(root, productUrl) {
 async function playHub(mock, webhook) {
   const ping = await mock.appEvent("ping");
   if (ping.status !== 200) {
-    out6(c.yellow(`! ${webhook} answered the signed ping with ${ping.status || ping.error}: it must answer 200 (ambasada.apps.verifyWebhook)`));
+    out7(c.yellow(`! ${webhook} answered the signed ping with ${ping.status || ping.error}: it must answer 200 (ambasada.apps.verifyWebhook)`));
     return;
   }
   const enabled = await mock.appEvent("notifications_enabled");
-  if (enabled.status === 200) out6(`${c.green("\u2713")} app webhook: ping and notifications_enabled delivered to ${webhook} ${c.dim(`(token ${enabled.token})`)}`);
-  else out6(c.yellow(`! ${webhook} answered notifications_enabled with ${enabled.status || enabled.error}`));
+  if (enabled.status === 200) out7(`${c.green("\u2713")} app webhook: ping and notifications_enabled delivered to ${webhook} ${c.dim(`(token ${enabled.token})`)}`);
+  else out7(c.yellow(`! ${webhook} answered notifications_enabled with ${enabled.status || enabled.error}`));
 }
 async function link(args, flags) {
   const url = args[0];
@@ -4901,14 +5081,14 @@ async function link(args, flags) {
   const root = findRoot();
   if (!root) throw new CliError(`run \`ambasada link\` inside your app (no ${CONFIG_FILE} found)`);
   if (!await setProductUrl(root, url.replace(/\/$/, ""))) throw new CliError(`could not find \`product: { url: "\u2026" }\` in ${CONFIG_FILE}: set it by hand`);
-  out6(`${c.green("\u2713")} product.url = ${url}`);
+  out7(`${c.green("\u2713")} product.url = ${url}`);
   try {
     const res = await fetch(new URL("/health", url), { signal: AbortSignal.timeout(5e3) });
-    out6(res.ok ? `${c.green("\u2713")} ${url} answers` : c.yellow(`! ${url}/health answered ${res.status}`));
+    out7(res.ok ? `${c.green("\u2713")} ${url} answers` : c.yellow(`! ${url}/health answered ${res.status}`));
   } catch {
-    out6(c.yellow(`! ${url} is not reachable from here yet`));
+    out7(c.yellow(`! ${url} is not reachable from here yet`));
   }
-  await addons().afterDeploy({ event: "link", project: await loadProject(root), url, flags, out: out6 });
+  await addons().afterDeploy({ event: "link", project: await loadProject(root), url, flags, out: out7 });
 }
 async function hosted(flags) {
   const r = await resolveForApp(flags, "change it");
@@ -4916,14 +5096,14 @@ async function hosted(flags) {
   return { local: false, apiUrl: r.apiUrl, apiKey: r.apiKey };
 }
 var ENV_NAME = /^[A-Z_][A-Z0-9_]{0,63}$/;
-var PLATFORM_ENV = /^(AMBASADA_(API_KEY|API_URL|APP_|AUTH_|HUB_URL|COMPANY|WEBHOOK_SECRET|VILLAGE_API_URL)|VILLAGE_)/;
+var PLATFORM_ENV = /^(AMBASADA_(API$|API_KEY|API_URL|APP_|AUTH_|HUB_URL|COMPANY|WEBHOOK_SECRET|VILLAGE_API_URL)|VILLAGE_)/;
 async function env(args, flags) {
   const [sub = "list", name, ...value] = args;
   const t = await hosted(flags);
   if (sub === "list") {
     const res = await api(t, "GET", "/v1/product/env");
     if (json(flags, res)) return;
-    out6(table(res.vars.map((v) => ({ name: v.name, type: v.type, set_by: v.platform ? "ambasada" : "you", updated: v.updated_at?.slice(0, 19).replace("T", " ") ?? "" }))));
+    out7(table(res.vars.map((v) => ({ name: v.name, value: v.type === "secret_text" ? "set (hidden)" : "set", set_by: v.platform ? "ambasada" : "you", updated: v.updated_at?.slice(0, 19).replace("T", " ") ?? "" }))));
     return;
   }
   if ((sub === "set" || sub === "unset") && name) {
@@ -4931,14 +5111,14 @@ async function env(args, flags) {
     if (PLATFORM_ENV.test(name)) throw new CliError(`${name} is set by the platform at deploy`);
     if (sub === "unset") {
       const res2 = await api(t, "DELETE", `/v1/product/env/${name}`);
-      out6(res2.deleted ? `${c.green("\u2713")} ${name} removed${res2.worker_updated ? " from the live Worker" : ""}` : c.dim(`${name} was not set`));
+      out7(res2.deleted ? `${c.green("\u2713")} ${name} removed${res2.worker_updated ? " from the live Worker" : ""}` : c.dim(`${name} was not set`));
       return;
     }
     let text = value.join(" ");
     if (!text && !process.stdin.isTTY) text = (await new Response(process.stdin).text()).replace(/\n$/, "");
     if (!text) throw new CliError(`usage: ambasada env set ${name} <value>   (or pipe the value on stdin)`);
     const res = await api(t, "PUT", `/v1/product/env/${name}`, { json: { value: text } });
-    out6(`${c.green("\u2713")} ${name} set ${c.dim(res.worker_updated ? "(live within about 30 s, and on every deploy)" : "(on the next deploy)")}`);
+    out7(`${c.green("\u2713")} ${name} set ${c.dim(res.worker_updated ? "(live within about 30 s, and on every deploy)" : "(on the next deploy)")}`);
     return;
   }
   throw new CliError("usage: ambasada env list | set NAME <value> | unset NAME");
@@ -4950,14 +5130,14 @@ async function logs(_args, flags) {
     const res = await api(t, "GET", "/v1/product/logs");
     if (json(flags, res) && !flags.follow) return;
     if (first) {
-      out6(res.last_deploy ? `last deploy v${res.last_deploy.version} at ${res.last_deploy.deployed_at.slice(0, 19).replace("T", " ")}` : c.dim("not deployed yet: `ambasada deploy`"));
-      out6(c.dim(`${res.errors.total_24h} error${res.errors.total_24h === 1 ? "" : "s"} in the last 24 h`));
+      out7(res.last_deploy ? `last deploy v${res.last_deploy.version} at ${res.last_deploy.deployed_at.slice(0, 19).replace("T", " ")}` : c.dim("not deployed yet: `ambasada deploy`"));
+      out7(c.dim(`${res.errors.total_24h} error${res.errors.total_24h === 1 ? "" : "s"} in the last 24 h`));
     }
     for (const e of [...res.errors.recent].reverse()) {
       const key = `${e.at} ${e.message}`;
       if (seen.has(key)) continue;
       seen.add(key);
-      out6(`${c.dim(e.at.slice(0, 19).replace("T", " "))} ${c.red(String(e.status ?? "error"))} ${e.method ?? ""} ${e.path ?? ""} ${e.message ?? ""}`.trimEnd());
+      out7(`${c.dim(e.at.slice(0, 19).replace("T", " "))} ${c.red(String(e.status ?? "error"))} ${e.method ?? ""} ${e.path ?? ""} ${e.message ?? ""}`.trimEnd());
     }
     if (!flags.follow) return;
     await sleep(5e3);
@@ -4965,7 +5145,7 @@ async function logs(_args, flags) {
 }
 
 // src/main.ts
-var VERSION3 = true ? "0.8.5" : "0.1.0-dev";
+var VERSION3 = true ? "0.8.6" : "0.1.0-dev";
 var MAJOR_MINOR = VERSION3.split(".").slice(0, 2).join(".");
 var HELP = `${c.bold("ambasada")} ${MAJOR_MINOR}: build and host apps on Ambasada
 
@@ -4977,7 +5157,7 @@ var HELP = `${c.bold("ambasada")} ${MAJOR_MINOR}: build and host apps on Ambasad
   deploy [--own] [--no-smoke] [--dry-run]               host it at https://<slug>.ambasada.dev
   tunnel [--port] | link <url> | check [url|dir]        your laptop at https://<slug>-dev.ambasada.dev; hosted
                                                         elsewhere; the product (and mini-app) checks
-  miniapp [enable [--entry /app]]                       the Ambasada mini app at a path of your app: off by default
+  miniapp [enable [--entry /app] | disable [--force]]   the Ambasada mini app at a path of your app: off by default
   env list|set|unset | logs [--follow]                  the hosted Worker
   db migrate|shell|tables | kv \u2026 | files \u2026              storage (env.DB, env.KV, env.FILES); --local: wrangler's
   add <addon>                                           install an add-on (today: village)