@ambasada/skills 0.1.0 → 0.3.0

package/README.md

@@ -1,10 +1,23 @@
-# ambasada-payments skill
+# @ambasada/skills
 
-`skill/` is the skill: `SKILL.md` (frontmatter `name`, `description`) plus `reference/` and `recipes/`.
-Install it in a project for Claude Code (`.claude/skills/ambasada-payments/`), Cursor or Codex
-(point the agent at `SKILL.md`). `ambasada init` vendors it into every new company.
+Skills for AI coding tools (Claude Code, Cursor, Codex) building products for the Hack A Ton Village.
 
-After editing, run `pnpm --filter @ambasada/skills sync` to update the template copy;
-`pnpm test` fails when they differ or a link is broken.
+| Skill | Use it to |
+|---|---|
+| [`ambasada-product`](skills/ambasada-product/SKILL.md) | build a product that sells in the Village: the Next.js-on-Cloudflare layout, allowed features, data and secrets, `ambasada dev` / `deploy` / `link`, design, a sellable checklist, prompts for ChatGPT and Lovable |
+| [`ambasada-payments`](skills/ambasada-payments/SKILL.md) | take and spend TON: Checkout, pay.js, webhooks, receipts, `buy` / `need`, LLM, images, tools, files; recipes for Next.js, static pages, Lovable/Bolt and self-hosted stacks |
+
+Each skill is a folder with `SKILL.md` (frontmatter `name`, `description`) plus `reference/`, `recipes/` or
+`checklists/`.
+
+Install:
+
+- New project: `npm create ambasada@latest my-shop` vendors both into `.claude/skills/`.
+- Existing project: `npx skills add centyso-dev/ambasada-skills` (public mirror), or copy `skills/*` into
+  `.claude/skills/`. Cursor and Codex: point the agent at the `SKILL.md` files.
+
+After editing, run `pnpm --filter @ambasada/skills sync`: it copies every skill into each
+`templates/*/.claude/skills/` (and the legacy `template/.claude/skills/` while it exists).
+`pnpm test` (`node scripts/sync.mjs --check`) fails on bad frontmatter, a broken relative link, or a stale copy.
 
 Built by [CENTYSO](https://centyso.com) for [Ambasada](https://ambasada.id). MIT.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ambasada/skills",
-  "version": "0.1.0",
-  "description": "The ambasada-payments skill (SKILL.md + reference docs + recipes) for Claude Code, Cursor and Codex.",
+  "version": "0.3.0",
+  "description": "Skills for Claude Code, Cursor and Codex: ambasada-product (build a product that sells in the Hack A Ton Village) and ambasada-payments (TON Checkout, receipts, webhooks).",
   "type": "module",
   "files": [
     "skills",

package/skills/ambasada-payments/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ambasada-payments
-description: Add TON payments to any app for the Hack A Ton village. Use when the user wants to accept TON from people (Checkout, pay.js button, webhooks), sell an HTTP endpoint that agents pay per call (verify the x-village-receipt), buy from other companies (village.buy / village.need), use the village LLM, images, tools or files, list offerings, or test all of it offline with `ambasada dev`. Covers Next.js, Express, FastAPI or any HTTP stack, Astro/static pages with pay.js, and Lovable/Bolt.
+description: Add TON payments to any app for the Hack A Ton village. Use when the user wants to accept TON from people (Checkout, pay.js button, webhooks), sell an HTTP endpoint that agents pay per call (verify the x-village-receipt), buy from other companies (village.buy / village.need), use the village LLM, images, tools or files, list offerings, or test all of it offline with `ambasada dev`. Covers Next.js on Cloudflare (the default template), static pages with pay.js, Lovable/Bolt, and self-hosted stacks (Express, FastAPI, Workers, Astro).
 ---
 
 # Village payments
@@ -19,14 +19,22 @@ Amounts are TON as decimal numbers. Errors are always `{ "error": { "code", "mes
 
 ## Decide what the user needs
 
-1. *"Let people pay on my site"* → [reference/checkout.md](reference/checkout.md). Static page without a backend → [recipes/astro-static-payjs.md](recipes/astro-static-payjs.md).
+1. *"Let people pay on my site"* → [reference/checkout.md](reference/checkout.md). Static page without a backend → [recipes/static-payjs.md](recipes/static-payjs.md).
 2. *"Let agents buy my service"* → [reference/receipts.md](reference/receipts.md), then list it as an offering ([reference/primitives.md](reference/primitives.md#listings)).
 3. *"My product needs something another team sells"* → [reference/need-vs-buy.md](reference/need-vs-buy.md).
 4. *"Use an LLM / generate images / search the web"* → [reference/primitives.md](reference/primitives.md#utilities) (paid in TON from the company wallet).
 5. Always set up **test mode** first → [reference/test-mode.md](reference/test-mode.md) (`ambasada dev`, no login, fake money).
 
-Stack recipes: [Next.js](recipes/nextjs.md) · [Express](recipes/express.md) · [FastAPI / plain HTTP](recipes/fastapi.md) ·
-[Astro / static + pay.js](recipes/astro-static-payjs.md) · [Lovable / Bolt / v0](recipes/lovable-bolt.md) · [Cloudflare Workers](recipes/workers.md).
+Stack recipes:
+
+- [Next.js on Cloudflare](recipes/nextjs.md): the default (`npm create ambasada@latest`), hosted by `ambasada deploy`.
+- [Static page + pay.js](recipes/static-payjs.md): no backend, a payment link and a button.
+- [Lovable / Bolt / v0](recipes/lovable-bolt.md): prompts to paste into the builder.
+- [Other stacks](recipes/other-stacks.md): Express, FastAPI, a bare Worker, Astro; power users who host
+  it themselves, then `ambasada link`.
+
+Building the whole product (layout, allowed Next.js features, data, deploy, design)? Use the
+**ambasada-product** skill as well.
 
 ## Rules that prevent real bugs
 
@@ -39,12 +47,17 @@ Stack recipes: [Next.js](recipes/nextjs.md) · [Express](recipes/express.md) ·
   schema) makes the Gateway refund the buyer. Throwing is the refund path.
 - **Idempotency.** Send `Idempotency-Key` on purchases and transfers; retries with the same key never charge twice.
 - **One receipt, one call.** Dedupe on `call_id` (the SDK does it per process; persist it if you run several instances).
-- TypeScript: use `@ambasada/sdk` (`npm i @ambasada/sdk`). Other languages: plain HTTP, shown in each recipe.
+- TypeScript: use `@ambasada/sdk` (`npm i @ambasada/sdk`). Other languages: plain HTTP ([recipes/other-stacks.md](recipes/other-stacks.md#fastapi-or-any-language-over-plain-http)).
 
 ## The SDK in 20 lines
 
+The examples call the client `village`. `import { village } from "@ambasada/sdk"` reads `process.env`
+(`AMBASADA_API_KEY`, `AMBASADA_API_URL`, `AMBASADA_COMPANY`, `AMBASADA_WEBHOOK_SECRET`); on Cloudflare make
+one with `createAmbasada({ env })`. In the Next template it is `ambasada()` from `lib/ambasada.ts`.
+The SDK still reads the old `VILLAGE_*` names as a fallback.
+
 ```ts
-import { village } from "@ambasada/sdk"; // reads AMBASADA_API_KEY, AMBASADA_API_URL
+import { village } from "@ambasada/sdk";
 
 // sell to agents: a fetch handler that verifies the receipt and answers JSON (402 if unpaid)
 export const POST = village.sell("translate", async ({ text, to }, call) => {

package/skills/ambasada-payments/recipes/lovable-bolt.md

@@ -1,9 +1,12 @@
 # Lovable, Bolt, v0 and other no-code builders
 
-These tools build from a prompt, so give them the docs instead of code.
+These tools build from a prompt, so give them the docs instead of code. Two options: keep hosting there
+(below), or export the code into the `spa` template and use `ambasada deploy` (the ambasada-product skill,
+`reference/build-elsewhere.md`). Either way, finish with `ambasada link https://your.app` or `ambasada deploy`.
 
 **1. Static "Pay with TON" button (works everywhere, no backend):** create a payment link with
-`ambasada links create …` (or in the village app → Payments), then paste this into the builder's chat:
+`ambasada links create --amount 3 --description "…" --success-url https://your.app/thanks`, then paste this
+into the builder's chat:
 
 > Add a "Pay 3 TON" button. Include `<script src="https://hackaton.ambasada.id/pay.js" defer></script>` in the
 > page head and render `<button data-village-pay="pl_XXXX">Pay 3 TON</button>` (add `data-mode="popup"` to
@@ -24,7 +27,7 @@ Supabase Edge Functions or similar; paste this:
 
 Then register the webhook URL: `ambasada webhook set https://…/functions/v1/village-webhook`.
 
-**3. Selling to agents** needs an endpoint that verifies `x-village-receipt` (reference/receipts.md). In an
+**3. Selling to agents** needs an endpoint that verifies `x-village-receipt` ([reference/receipts.md](../reference/receipts.md)). In an
 edge function with npm support: `import { village } from "npm:@ambasada/sdk"` and
 `Deno.serve(village.sell("translate", async (input) => ({ … })))`.
 

package/skills/ambasada-payments/recipes/nextjs.md

@@ -1,54 +1,150 @@
-# Next.js (App Router)
+# Next.js on Cloudflare (the default template)
 
-`npm i @ambasada/sdk` · `.env.local`: `AMBASADA_API_KEY=…` (`AMBASADA_API_URL=http://127.0.0.1:8788` while on `ambasada dev`), `AMBASADA_WEBHOOK_SECRET=whsec_…`
+`npm create ambasada@latest my-shop` gives you all of this already: Next.js 16.4 App Router, built into one
+Cloudflare Worker by `@opennextjs/cloudflare` 1.20 with `nodejs_compat`. Local secrets in `.env`
+(`AMBASADA_API_KEY`, `AMBASADA_API_URL`, `AMBASADA_COMPANY`, `AMBASADA_WEBHOOK_SECRET`); `.dev.vars` works too. What runs on
+Workers and what doesn't: the ambasada-product skill, `reference/stack.md`.
+
+## The client: `lib/ambasada.ts`
+
+Server code only. One client per Worker instance: it caches the receipt keys and remembers used receipts.
+
+```ts
+// lib/ambasada.ts (the template ships it; this is the core)
+import { createAmbasada, type Village } from "@ambasada/sdk";
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+
+function cloudflareEnv(): Record<string, unknown> | undefined {
+  try {
+    return getCloudflareContext().env as unknown as Record<string, unknown>;
+  } catch {
+    return undefined; // `next dev`: the SDK reads process.env
+  }
+}
+
+let client: Village | undefined;
+
+export function ambasada(): Village {
+  return (client ??= createAmbasada({ env: cloudflareEnv() }));
+}
+```
+
+It also exports `env(name)` (a variable from the Worker env, else `process.env`) and `villageUrl()`
+(the Village, or the mock under `ambasada dev`).
+
+## An offering agents pay for
 
 ```ts
-// app/api/translate/route.ts: an offering agents pay for (list it with endpoint https://your.app/api/translate)
-import { village } from "@ambasada/sdk";
-export const runtime = "nodejs";
+// app/api/translate/route.ts   (offering endpoint "/api/translate")
+import { ambasada } from "../../../lib/ambasada.ts";
 
-export const POST = village.sell<{ text: string; to: string }>("translate", async ({ text, to }) => ({
-  text: await village.llm(`Translate to ${to}. Reply with the translation only.\n\n${text}`),
-}));
+export const POST = (req: Request) =>
+  ambasada().sell<{ text: string; to: string }>("translate", async ({ text, to }) => ({
+    text: await ambasada().llm(`Translate to ${to}. Reply with the translation only.\n\n${text}`),
+  }))(req);
 ```
 
+`sell` answers `402` without a valid receipt, runs your handler, returns its JSON. Throw a `VillageError`
+(or let it fail) and the buyer is refunded.
+
+## People pay: Checkout
+
 ```ts
-// app/api/checkout/route.ts: people pay
-import { village } from "@ambasada/sdk";
+// app/api/checkout/route.ts   (the landing page: <form action="/api/checkout" method="post">)
+import { ambasada } from "../../../lib/ambasada.ts";
 
 export async function POST(req: Request) {
-  const { plan } = await req.json();
-  const session = await village.checkout({
-    amount: plan === "pro" ? 10 : 3,
-    description: plan === "pro" ? "Pro pack" : "Starter pack",
-    success_url: `${new URL(req.url).origin}/thanks?session={CHECKOUT_SESSION_ID}`,
-    client_reference_id: crypto.randomUUID(),
-  });
-  return Response.json({ url: session.url }); // client: location.href = url
+  const origin = new URL(req.url).origin;
+  const id = crypto.randomUUID();
+  const a = ambasada();
+  await a.store.set(`order:${id}`, { paid: false });
+  const session = await a.checkout(
+    {
+      amount: 2,
+      description: "Your name as a folk poem",            // public in the ledger: no personal data
+      success_url: `${origin}/thanks?session={CHECKOUT_SESSION_ID}`,
+      cancel_url: `${origin}/`,
+      client_reference_id: id,
+    },
+    { idempotencyKey: id },
+  );
+  return Response.redirect(session.url, 303);
 }
 ```
 
+Or as a server action:
+
 ```ts
-// app/api/village-webhook/route.ts
-import { village } from "@ambasada/sdk";
+"use server";
+import { redirect } from "next/navigation";
+import { ambasada } from "../../../lib/ambasada.ts";
+
+export async function buy() {
+  const session = await ambasada().checkout({ amount: 2, description: "Your name as a folk poem", success_url: "…" });
+  redirect(session.url);
+}
+```
+
+## Deliver: the webhook
+
+```ts
+// app/api/webhook/route.ts   (`ambasada webhook set https://<slug>.hackaton.ambasada.id/api/webhook`)
+import { ambasada } from "../../../lib/ambasada.ts";
 
 export async function POST(req: Request) {
+  const a = ambasada();
+  let event;
   try {
-    const event = await village.verifyWebhook(req); // reads the raw body itself
-    if (event.type === "checkout.paid") await fulfil(event.data.session.client_reference_id, event.id);
-    return new Response("ok");
+    event = await a.verifyWebhook(req);                    // reads the raw body itself
   } catch {
     return new Response("bad signature", { status: 400 });
   }
+  if (event.type === "checkout.paid") {
+    const key = `order:${event.data.session.client_reference_id}`;
+    const order = (await a.store.get(key)) as { paid: boolean } | null;
+    if (order && !order.paid) await a.store.set(key, { ...order, paid: true });   // retries reuse event.id
+  }
+  return new Response("ok");                               // 2xx within 10 s, or it is retried
 }
 ```
 
+## The thanks page: check on the server
+
 ```tsx
-// app/thanks/page.tsx: confirm on the server, not from the URL alone
-import { village } from "@ambasada/sdk";
+// app/thanks/page.tsx
+import { ambasada } from "../../lib/ambasada.ts";
+
 export default async function Thanks({ searchParams }: { searchParams: Promise<{ session?: string }> }) {
   const { session } = await searchParams;
-  const s = session ? await village.getCheckout(session) : null;
-  return <h1>{s?.status === "paid" ? "Thank you!" : "Payment pending…"}</h1>;
+  const s = session ? await ambasada().getCheckout(session) : null;
+  if (s?.status !== "paid") return <h1>Payment pending… refresh in a moment.</h1>;
+  return <h1>Thank you! Paid {s.amount} TON.</h1>;
 }
 ```
+
+## pay.js receipts from the browser
+
+```ts
+// app/api/receipt/route.ts   (POST { receipt } from a `village:paid` event)
+import { ambasada } from "../../../lib/ambasada.ts";
+import { isVillageError } from "@ambasada/sdk";
+
+export async function POST(req: Request) {
+  try {
+    const { receipt } = (await req.json()) as { receipt?: string };
+    const claims = await ambasada().verifyCheckoutReceipt(receipt);
+    return Response.json({ ok: true, amount: claims.amount, session: claims.session });
+  } catch (error) {
+    if (isVillageError(error)) return error.toResponse();
+    return Response.json({ error: { code: "INVALID_REQUEST", message: "body must be { receipt }" } }, { status: 400 });
+  }
+}
+```
+
+The button side is in [static-payjs.md](static-payjs.md). In Next, the template's `app/page.tsx` loads it
+with `<Script src={`${villageUrl()}/pay.js`} />` (`next/script`), so the same page works against the mock.
+
+## Not on Cloudflare
+
+Next on Vercel or a Node server works with the same route handlers: replace `ambasada()` with the
+default client, `import { village } from "@ambasada/sdk"`, which reads `process.env`. Then `ambasada link <url>`.

package/skills/ambasada-payments/recipes/other-stacks.md

@@ -0,0 +1,159 @@
+# Other stacks: host it yourself, then `ambasada link`
+
+For power users who already have a server. The Village does not host these: run them anywhere with a
+public HTTPS URL, then `ambasada link https://your.server` (it rewrites `product.url` in
+`ambasada.config.ts` and lists your offerings there). Agents and people pay the same way; only the code differs.
+
+Every stack needs the same four things: a paid endpoint that verifies `x-village-receipt` on the **raw
+body**, a Checkout route, a webhook route that verifies the signature on the **raw body**, and the env
+`AMBASADA_API_KEY`, `AMBASADA_COMPANY`, `AMBASADA_WEBHOOK_SECRET` (plus
+`AMBASADA_API_URL=http://127.0.0.1:8788` against `ambasada dev --mock-only`).
+
+## Express (Node)
+
+`npm i @ambasada/sdk express`. The default `village` client reads `process.env`.
+
+```ts
+import express from "express";
+import { isVillageError, village } from "@ambasada/sdk";
+
+const app = express();
+const raw = express.raw({ type: "*/*", limit: "1mb" }); // receipts and webhooks are signed over the raw bytes
+
+// An offering agents pay for.
+app.post("/api/translate", raw, async (req, res) => {
+  try {
+    const { input, buyer, amount } = await village.verifyReceipt(req, { offering: "translate" });
+    const text = await village.llm(`Translate to ${input.to}. Reply with the translation only.\n\n${input.text}`);
+    res.json({ text }); // 2xx = you get paid; any error status = buyer refunded
+  } catch (e) {
+    if (isVillageError(e)) return res.status(e.status || 500).json(e.toJSON()); // 402 when unpaid
+    throw e;
+  }
+});
+
+// People pay.
+app.post("/buy", express.json(), async (req, res) => {
+  const session = await village.checkout({
+    amount: 3,
+    description: "Coffee for the team",
+    success_url: "https://my.app/thanks?session={CHECKOUT_SESSION_ID}",
+  });
+  res.redirect(303, session.url);
+});
+
+app.post("/village-webhook", raw, async (req, res) => {
+  try {
+    const event = await village.verifyWebhook(req);
+    if (event.type === "checkout.paid") await fulfil(event.data.session, event.id);
+    res.sendStatus(200);
+  } catch {
+    res.sendStatus(400);
+  }
+});
+
+app.listen(3000);
+```
+
+Don't put `app.use(express.json())` in front of the paid routes: once the body is parsed the bytes are gone
+and `verifyReceipt` refuses with a `CONFIG` error. Full example: `examples/express-seller` in the village repo.
+
+## Cloudflare Worker without a framework
+
+The `worker` template (`npm create ambasada@latest my-shop -- --template worker`) is this, with Village
+hosting by `ambasada deploy`. By hand, in your own account (`wrangler secret put AMBASADA_API_KEY`, …):
+
+```ts
+import { createAmbasada, type Village } from "@ambasada/sdk";
+
+let village: Village | undefined; // one per isolate: it caches receipt keys and remembers used receipts
+
+export default {
+  async fetch(req: Request, env: Record<string, string>): Promise<Response> {
+    village ??= createAmbasada({ env }); // AMBASADA_API_KEY, AMBASADA_API_URL, AMBASADA_COMPANY, AMBASADA_WEBHOOK_SECRET
+    const { pathname } = new URL(req.url);
+    if (pathname === "/api/translate") {
+      return village.sell("translate", async ({ text, to }) => ({ text: await village.llm(`Translate to ${to}: ${text}`) }))(req);
+    }
+    if (pathname === "/village-webhook") {
+      const event = await village.verifyWebhook(req);
+      if (event.type === "checkout.paid") { /* fulfil event.data.session */ }
+      return new Response("ok");
+    }
+    return new Response("not found", { status: 404 });
+  },
+};
+```
+
+Workers have no `process.env` by default, hence `createAmbasada({ env })`. Bun, Deno, Hono, Astro endpoints
+(`output: "server"`) and SvelteKit use the same fetch-style handlers: `village.sell(name, handler)` is a
+`(req: Request) => Promise<Response>`.
+
+## FastAPI (or any language over plain HTTP)
+
+`pip install fastapi uvicorn httpx pyjwt[crypto] standardwebhooks`
+
+```python
+import hashlib, json, os, httpx, jwt
+from fastapi import FastAPI, Request, HTTPException
+from standardwebhooks.webhooks import Webhook
+
+API = os.environ.get("AMBASADA_API_URL", "https://hackaton.ambasada.id")
+KEY = os.environ["AMBASADA_API_KEY"]
+COMPANY = os.environ["AMBASADA_COMPANY"]          # your company id
+HEADERS = {"Authorization": f"Bearer {KEY}"}
+app = FastAPI()
+_keys = {k["kid"]: jwt.PyJWK(k) for k in httpx.get(f"{API}/.well-known/jwks.json").json()["keys"]}
+_seen: set[str] = set()
+
+def verify_receipt(token: str | None, body: bytes, offering: str) -> dict:
+    if not token:
+        raise HTTPException(402, "payment required")
+    key = _keys.get(jwt.get_unverified_header(token).get("kid"))
+    if not key:
+        raise HTTPException(402, "unknown village key")
+    try:
+        c = jwt.decode(token, key, algorithms=["EdDSA"], issuer="village")  # checks signature + exp
+    except jwt.PyJWTError as e:
+        raise HTTPException(402, f"bad receipt: {e}")
+    if c.get("kind") or c["seller"] != COMPANY or c["offering"] != f"{COMPANY}/{offering}":
+        raise HTTPException(402, "receipt is for another offering")
+    if hashlib.sha256(body).hexdigest() != c["body_sha256"] or c["call_id"] in _seen:
+        raise HTTPException(402, "receipt does not match this request")
+    _seen.add(c["call_id"])
+    return c
+
+def llm(prompt: str) -> str:
+    r = httpx.post(f"{API}/v1/llm/chat", headers=HEADERS, timeout=60,
+                   json={"model": "deepseek-v4.1-flash", "messages": [{"role": "user", "content": prompt}]})
+    r.raise_for_status()
+    return r.json()["choices"][0]["message"]["content"]
+
+@app.post("/api/translate")                       # offering endpoint agents pay for
+async def translate(request: Request):
+    body = await request.body()                   # raw bytes first
+    verify_receipt(request.headers.get("x-village-receipt"), body, "translate")
+    data = json.loads(body)
+    return {"text": llm(f"Translate to {data['to']}. Reply with the translation only.\n\n{data['text']}")}
+
+@app.post("/buy")                                 # people pay
+def buy():
+    s = httpx.post(f"{API}/v1/checkout/sessions", headers=HEADERS, json={
+        "amount": 3, "description": "Coffee for the team",
+        "success_url": "https://my.app/thanks?session={CHECKOUT_SESSION_ID}"}).json()
+    return {"url": s["url"]}
+
+@app.post("/village-webhook")
+async def webhook(request: Request):
+    body = await request.body()
+    try:
+        event = Webhook(os.environ["AMBASADA_WEBHOOK_SECRET"]).verify(body, dict(request.headers))
+    except Exception:
+        raise HTTPException(400, "bad signature")
+    if event["type"] == "checkout.paid":
+        fulfil(event["data"]["session"], request.headers["webhook-id"])
+    return "ok"
+```
+
+Buy from another company: `httpx.post(f"{API}/v1/pay/inkwell/poem", headers={**HEADERS, "Idempotency-Key": str(uuid4()), "x-village-max-price": "2"}, json=input)`.
+Errors come back as `{"error": {"code": …}}` with the HTTP status. Go, PHP, Ruby: same calls.

package/skills/ambasada-payments/recipes/{astro-static-payjs.md → static-payjs.md}

@@ -1,5 +1,6 @@
-# Astro, or any static page: pay.js (no backend)
+# A static page: pay.js (no backend)
 
+For plain HTML, Astro, a page built in Lovable, Bolt or v0, Carrd, anything that can include a script.
 pay.js is served by the village (`https://hackaton.ambasada.id/pay.js`; `ambasada dev` serves the same script at
 `http://127.0.0.1:8788/pay.js`, and it talks to whichever origin it was loaded from). It turns a button into
 "Pay with TON" using a **payment link**, so the page never needs your key.
@@ -11,7 +12,7 @@ ambasada links create --amount 3 --description "A coffee for the team" --success
 # → pl_… (or POST /v1/checkout/links with curl)
 ```
 
-2. On the page (`src/pages/index.astro` or plain HTML):
+2. On the page (plain HTML, `index.html`, or `src/pages/index.astro`):
 
 ```html
 <script src="https://hackaton.ambasada.id/pay.js" defer></script>
@@ -43,13 +44,15 @@ with `cancelled` or `closed`), and `await Village.session("cs_…")` → `{ stat
 purchase matters (a download, credits), send `e.detail.receipt` to a server or edge function and verify it:
 
 ```ts
-// e.g. an Astro endpoint src/pages/api/unlock.ts (output: "server"), or a Worker
-import { village } from "@ambasada/sdk";
-export const POST = async ({ request }: { request: Request }) => {
+// any fetch-style server route: the templates' /api/receipt, an Astro endpoint, a Worker
+import { village } from "@ambasada/sdk"; // reads process.env; on a Worker: createAmbasada({ env })
+export async function POST(request: Request) {
   const { receipt } = await request.json();
   const claims = await village.verifyCheckoutReceipt(receipt); // throws if forged / for another company
   return Response.json({ ok: true, amount: claims.amount });
-};
+}
 ```
 
-Or set up the `checkout.paid` webhook (see reference/checkout.md).
+Or set up the `checkout.paid` webhook ([reference/checkout.md](../reference/checkout.md)).
+
+Then tell the village where the page lives: `ambasada link https://your.page`.

package/skills/ambasada-payments/reference/primitives.md

@@ -30,8 +30,8 @@ await village.listings.put("translate", {
 ```
 
 Schema field types: `string`, `text`, `number`, `integer`, `boolean`, `object`, `array`, `json`,
-`image_url`, `file_url`; a trailing `?` makes a field optional. In the template, offerings live in
-`product/offerings.ts` and `ambasada offerings sync` pushes them.
+`image_url`, `file_url`; a trailing `?` makes a field optional. In a project, offerings live in the file
+that `ambasada.config.ts` points to (`offerings:`); `ambasada offerings sync` and `ambasada deploy` push them.
 
 ## Utilities
 
@@ -43,14 +43,31 @@ const res = await village.llm.chat({ model: "deepseek-v4-pro", messages });   //
 const { url } = await village.images.generate({ prompt: "a lighthouse", model: "nano_banana" });
 const tools = await village.tools.list();                                     // curated catalog, TON prices
 const { output } = await village.tools.call("web.search", { query: "Mamaia weather" });
-const file = await village.files.put(bytes, { contentType: "image/png" });     // public URL for other products
+const file = await village.files.put(bytes, { contentType: "image/png" });     // { id, url }: public URL, 0.1 TON
 ```
 
 HTTP: `POST /v1/llm/chat` (OpenAI body), `POST /v1/images { model, prompt }` → `{ url, cost }`,
-`GET /v1/tools`, `POST /v1/tools/:id` → `{ output, cost, call_id }`, `POST /v1/files`.
+`GET /v1/tools`, `POST /v1/tools/:id` → `{ output, cost, call_id }`, `POST /v1/files` (raw body +
+content-type, or `{ url }`) → `{ id, url, cost }`.
 LLM models: `deepseek-v4.1-flash` (default, cheap), `deepseek-v4-pro`, `glm-5.3-flash`.
 Images: `nano_banana` (2 TON), `gpt-image-2` (8 TON).
 
+## Store and hosting
+
+`village.store` is your company's JSON key-value store: free, 1 MB per company (keys + values), so a
+hosted product needs no database. `ambasada deploy` hosts the product at `https://<slug>.ambasada.dev`
+with `AMBASADA_API_KEY`, `AMBASADA_API_URL`, `AMBASADA_COMPANY` and `AMBASADA_WEBHOOK_SECRET` already set.
+
+```ts
+await village.store.set("cart:ana", { items: ["translate"] });   // any JSON value
+const cart = await village.store.get<{ items: string[] }>("cart:ana"); // null when not set
+await village.store.delete("cart:ana");
+const { keys, used_bytes } = await village.store.list("cart:");
+```
+
+HTTP: `GET|PUT|DELETE /v1/store/:key` (PUT body = the JSON value), `GET /v1/store?prefix=`;
+`POST /v1/product/deploy` (what `ambasada deploy` calls), `GET /v1/product`, `DELETE /v1/product`.
+
 ## Errors
 
 `{ "error": { "code", "message", call_id?, charged?: false, refunded?, approval_id? } }`. The SDK throws

package/skills/ambasada-payments/reference/receipts.md

@@ -48,7 +48,7 @@ export const POST = village.sell("post_kit", async ({ topic }, call) => {
 
 Any JWT library with EdDSA (Ed25519): fetch `GET /.well-known/jwks.json`, pick the key by `kid`, verify,
 then check `exp`, `iss == "village"`, `seller`, `offering`, and `sha256(raw body) == body_sha256` (hex).
-See the FastAPI recipe for a complete example.
+Complete example: [the FastAPI recipe](../recipes/other-stacks.md#fastapi-or-any-language-over-plain-http).
 
 ## Checkout receipts
 

package/skills/ambasada-payments/reference/test-mode.md

@@ -5,11 +5,14 @@ signatures as production, so your code does not change between test and live: on
 `AMBASADA_API_KEY` do.
 
 ```sh
-npx ambasada dev                      # in your project: registers offerings.ts pointing at product.url
-AMBASADA_API_URL=http://127.0.0.1:8788 AMBASADA_API_KEY=sk_test_dev npm run dev   # your product
+npx ambasada dev                      # in your project: the mock, your offerings registered, and your site's dev server
 npx ambasada dev buy translate '{"text":"Bună!","to":"en"}'                     # a fake agent pays you 1 TON
 ```
 
+A project made by `npm create ambasada@latest` already has `AMBASADA_API_URL=http://127.0.0.1:8788` and
+`AMBASADA_API_KEY=sk_test_dev` in its local env file. Running your site yourself? `npx ambasada dev --mock-only`,
+and start it with those two variables set.
+
 What it gives you:
 
 - **Fake bank**: your company starts with 500 TON; `fake-agent` (key `sk_test_agent`) has 100; the fake
@@ -17,7 +20,7 @@ What it gives you:
 - **Real Pay proxy**: holds, calls your endpoint with a signed `x-village-receipt` (keys at
   `/.well-known/jwks.json`), captures on 2xx, refunds on failure, checks `input`/`output` schemas.
 - **Checkout**: `village.checkout()` returns a `/pay/cs_…` page where the fake visitor approves; the signed
-  `checkout.paid` webhook goes to your webhook URL (secret `AMBASADA_WEBHOOK_SECRET` from `.env`).
+  `checkout.paid` webhook goes to your webhook URL (secret `AMBASADA_WEBHOOK_SECRET` from the local env file).
   `/pay.js` is the production script itself, so buttons, redirect and popup mode, `village:paid` /
   `village:cancelled` and `GET /v1/web/checkout/:id` behave as on the real site. Webhook test, retry and
   link / session management routes are there too.
@@ -28,5 +31,6 @@ What it gives you:
 - **Agent**: `/v1/agent/config`, `/v1/agent/steer` (canned reply), `/v1/agent/transcript`.
 - **Dashboard** at `http://127.0.0.1:8788/`: wallets, your offerings with a "Buy" button, recent calls.
 
-Any bearer key is accepted as your company except `sk_test_agent`. Going live: `ambasada login`, put your
-`sk_live_…` key in the host's env, remove `AMBASADA_API_URL`, `ambasada link https://your.product`, `ambasada deploy`.
+Any bearer key is accepted as your company except `sk_test_agent`. Going live: `ambasada login`, then
+`ambasada deploy` (Village hosting sets the real key and URL for you). Hosting it yourself: put your `sk_live_…`
+key in the host's env, leave `AMBASADA_API_URL` unset, then `ambasada link https://your.product`.

package/skills/ambasada-product/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: ambasada-product
+description: Build a digital product that sells in the Hack A Ton Village and put it online. Use when the user wants to make a shop, app, tool or website that people or agents pay for in TON (the Village play currency), start one with `npm create ambasada@latest`, run it with `ambasada dev`, publish it with `ambasada deploy`, check it is ready to sell, or bring a site built in ChatGPT, Lovable, Bolt or v0 into the Village with `ambasada link`. Default stack: Next.js on Cloudflare.
+---
+
+# Build a product that sells in the Village
+
+The Village is the Hack A Ton market. Everything is paid in **TON**: a play currency held by the Village
+bank, **not** the TON blockchain. Visitors spend TON from their Ambasada ID wallet; other teams' agents
+buy from you through the Gateway.
+
+A product is **one website** (one Cloudflare Worker) at `https://<your-slug>.hackaton.ambasada.id`, plus
+**your agent**, which runs the shop (prices, suppliers, deals) while you sleep.
+
+For payment details (Checkout, receipts, webhooks, `buy`/`need`, LLM and images) use the
+**ambasada-payments** skill. This skill is about the product around them.
+
+## Start
+
+```sh
+npm create ambasada@latest my-shop          # Next.js (default)
+cd my-shop && npm install
+npx ambasada dev                            # fake bank + your site, no login, fake money
+```
+
+Other templates: add `-- --template spa` (Vite + React; for code exported from Lovable or Bolt) or
+`-- --template worker` (plain HTML + small fetch handlers; the smallest possible product).
+All three have the same `ambasada.config.ts`, `agent/` folder and four endpoints: `checkout`, `webhook`,
+`receipt` and the paid offering `translate`.
+
+## What to read
+
+| The user wants to… | Read |
+|---|---|
+| know where files go, what Next.js features are allowed, where to keep data and secrets | [reference/stack.md](reference/stack.md) |
+| run it locally, put it online, use their own Cloudflare account | [reference/dev-and-deploy.md](reference/dev-and-deploy.md) |
+| make it look good and sell (one page, one offer) | [reference/design.md](reference/design.md) |
+| build in ChatGPT, Lovable, Bolt or v0 and sell from there | [reference/build-elsewhere.md](reference/build-elsewhere.md) |
+| know if it is ready | [checklists/sellable.md](checklists/sellable.md) |
+
+## Rules (break one and the product does not work in the Village)
+
+1. **One product = one Worker.** No separate backend, no own database, no Docker. Data goes in
+   `ambasada.store` (small JSON) or `ambasada.files` (images, PDFs). See [reference/stack.md](reference/stack.md#where-data-lives).
+2. **Only the allowed Next.js subset**: pages, server components, route handlers, server actions, `fetch`.
+   No `next/image` default loader, no ISR/`revalidate`, no `fs`/`child_process`/native packages, no custom
+   server, no `middleware.ts`/`proxy.ts`, no `runtime = "edge"`. See [reference/stack.md](reference/stack.md#nextjs-allowed-and-banned).
+3. **The API key never reaches the browser.** It lives in `.env` locally (or `.dev.vars`); only server code reads it.
+   Never prefix it with `NEXT_PUBLIC_`.
+4. **Deliver only after payment is proven on the server**: webhook, `getCheckout(id).status === "paid"`,
+   or a verified receipt. Never because the URL says `?session=…`.
+5. **Sellable means**: a landing page with the price and a Pay button above the fold, one offering
+   with a receipt-checked endpoint, a webhook that delivers, the agent configured. Run
+   [checklists/sellable.md](checklists/sellable.md) before saying "done".
+
+## When the user is not a developer
+
+Do the work; don't ask them to edit code. Ask at most: what they sell, to whom, for how many TON.
+Then build one page, run `npx ambasada dev`, open it, pay as the fake visitor, and show them it worked.
+Explain in one sentence per step, no jargon.

package/skills/ambasada-product/checklists/sellable.md

@@ -0,0 +1,51 @@
+# Sellable checklist
+
+Run it before saying "done". Check each line yourself; don't assume. Every line needs `npx ambasada dev`
+running, except the last section.
+
+## The page
+
+- [ ] `/` on a phone-sized window (375 px wide) shows, without scrolling: what it is, the price in TON, the Pay button.
+- [ ] The price on the page equals the price charged (the Checkout `amount`, or the offering's `price`).
+- [ ] One offer. Any second offer has its own price next to its own button.
+- [ ] No login, no signup, no "coming soon", no lorem ipsum, no broken images.
+
+## People can pay
+
+- [ ] Pressing Pay opens the Village approve page (`/pay/cs_…` or `/pay/pl_…`); approving as the fake visitor works.
+- [ ] After paying, `/thanks` shows the result, or "working on it" and then the result.
+- [ ] `/thanks?session=` with a made-up or unpaid session does **not** show the result.
+- [ ] The webhook route verifies the signature (`verifyWebhook`) and delivers on `checkout.paid`; a
+      repeated event (same `webhook-id`) does not deliver twice.
+- [ ] The Checkout `description` has no personal data (it is public in the ledger).
+
+## Agents can pay
+
+- [ ] At least one offering in the offerings list that `ambasada.config.ts` points to, with
+      `description`, `price`, `endpoint`, `input` and `output`.
+- [ ] Its route uses `sell(...)` or `verifyReceipt(...)`: a plain `curl -X POST` to it gets `402`.
+- [ ] `npx ambasada dev buy <offering> '<json input>'` succeeds and the output matches `output`.
+- [ ] On failure it answers non-2xx (the buyer is refunded), never 200 with an error inside.
+
+## Safe
+
+- [ ] `grep -rn "sk_live_\|sk_test_\|whsec_" app components lib public src web` finds nothing
+      (keys live only in `.env` / `.dev.vars`), and nothing is named `NEXT_PUBLIC_*KEY*`.
+- [ ] `.dev.vars` and `.env*` are in `.gitignore`.
+- [ ] No banned Next.js features: `grep -rn "next/image\|revalidate\|runtime = \"edge\"\|from \"fs\"\|child_process" app lib`
+      finds nothing (or only `images: { unoptimized: true }` in `next.config.ts`).
+
+## The agent
+
+- [ ] `agent/agent.md` says what you sell, your price range (minimum and maximum) and what the agent may buy.
+- [ ] `agent/settings.json` `limits` are sane for your wallet (defaults: 10 TON per payment, 100 per day,
+      5 automatic per payment).
+
+## Online (after `npx ambasada deploy`)
+
+- [ ] `https://<slug>.hackaton.ambasada.id` loads on a phone.
+- [ ] `npx ambasada offerings list`: every endpoint starts with your public URL, none with `localhost`.
+- [ ] `npx ambasada webhook test` prints `delivered`.
+- [ ] One real payment by someone outside your team (members can't buy from their own company) shows up
+      in `npx ambasada ledger`, and they got what they paid for.
+- [ ] `npx ambasada logs --agent` shows the agent woke up.

package/skills/ambasada-product/reference/build-elsewhere.md

@@ -0,0 +1,82 @@
+# Built in ChatGPT, Lovable, Bolt or v0
+
+Three ways, easiest first. Replace `pl_XXXX`, prices and names with yours.
+
+## A. Keep it hosted there, add a Pay button
+
+Good for: a page that sells something simple (a poster, a reading, a coffee for the team).
+
+1. On a laptop with Node 22+, once:
+
+   ```sh
+   npm create ambasada@latest my-shop      # you need its ambasada.config.ts and agent/ folder
+   cd my-shop && npm install
+   npx ambasada login
+   npx ambasada links create --amount 2 --description "Your name as a folk poem" --success-url https://YOUR-SITE/thanks
+   # → pl_XXXX
+   ```
+
+2. Paste this into the builder's chat:
+
+   > Add a "Pay 2 TON" button to the top of the home page, visible without scrolling on a phone.
+   > Load `<script src="https://hackaton.ambasada.id/pay.js" defer></script>` on every page (in the HTML head
+   > or index.html). Render the button as `<button data-village-pay="pl_XXXX">Pay 2 TON</button>`.
+   > Make a `/thanks` page that also loads pay.js. Listen for the `village:paid` event on `document`
+   > (`event.detail` has `session` and `receipt`): when it fires, show the result. On `village:cancelled`,
+   > do nothing. Do not add Stripe or any other payment provider. Do not add login.
+
+3. Register the site with the Village:
+
+   ```sh
+   npx ambasada link https://YOUR-SITE
+   ```
+
+   It warns if `https://YOUR-SITE/health` doesn't answer; for a page with only a Pay button that's fine.
+   It also lists the template's `translate` offering at your site, which has no such endpoint: delete it
+   from the offerings list first, or add `--no-sync`.
+
+Limit: anything unlocked only in the browser can be unlocked by anyone who reads the page's code. Fine for
+a thank-you and a small gift; for downloads, credits or paid AI work, use B or C.
+
+## B. Bring the code home (recommended for Lovable and Bolt)
+
+Good for: anything with real work behind the button. You get Village hosting and the full rules.
+
+1. Export the project to GitHub (Lovable: GitHub sync; Bolt: download or GitHub) and clone it.
+2. `npm create ambasada@latest my-shop -- --template spa` and copy the exported `src/` (components,
+   pages, styles) into the new project's `src/`, replacing the starter UI. Keep the template's `api/`,
+   `agent/`, `ambasada.config.ts`, `wrangler.jsonc` and `vite.config.ts`.
+3. Open the project in Claude Code, Cursor or Codex and say:
+
+   > This is a Village product (see .claude/skills/ambasada-product). Wire the Pay button in my UI to the
+   > template's checkout endpoint, remove Supabase/Firebase and any login, store data with ambasada.store,
+   > then run the sellable checklist.
+
+4. `npx ambasada dev`, test a payment, then `npx ambasada deploy`.
+
+## C. ChatGPT (or any chat) writes the code, you paste it
+
+1. `npm create ambasada@latest my-shop`, `cd my-shop && npm install`, `npx ambasada dev`.
+2. Paste this into ChatGPT, then the two files it mentions, then your idea:
+
+   > I have a Next.js 16 App Router project that runs on Cloudflare Workers (OpenNext). Rules: no
+   > database, no `fs`, no native packages, no `next/image` (use `<img>`), no middleware, no `revalidate`,
+   > no login. Server code gets the payments client from `lib/ambasada.ts`; it never runs in the browser.
+   > Below are my `app/page.tsx` and `app/api/checkout/route.ts`. Keep the checkout route and call it the
+   > way the current page does. Rewrite `app/page.tsx` for my idea: what I sell, the price in TON and
+   > the Pay button, all visible on a phone without scrolling. After paying, the buyer lands on
+   > `app/thanks/page.tsx`; keep its check that the session is `"paid"` before showing the result.
+   > Write complete files, one code block per file, with the file path above each.
+   > My idea: …
+
+3. Paste each file where ChatGPT says, keep `npx ambasada dev` running, check the page, pay as the fake
+   visitor. When it works: `npx ambasada deploy`.
+
+Use ChatGPT to write files, not to decide the stack: if its answer adds Prisma, Supabase, NextAuth,
+`next/image` or a `middleware.ts`, tell it "that's banned in my project, do it without".
+
+## Connect your AI tool to the Village (optional)
+
+The Village MCP server (`https://hackaton.ambasada.id/mcp`) lets Claude, ChatGPT, Cursor or Lovable read
+your wallet, create offerings and set up your agent while you build. Setup per tool: `docs/CONNECT.md`
+in the Village repo. It is for building only; your published site never uses it.

package/skills/ambasada-product/reference/design.md

@@ -0,0 +1,51 @@
+# Design for people who pay in 10 seconds
+
+Visitors open your product on a phone, inside the Village app, between two other stands. They decide
+in seconds. Build for that.
+
+## One page, one offer
+
+- **One page.** Everything a buyer needs fits on the landing page. Extra pages only for `/thanks` and
+  maybe one result page.
+- **One offer.** One thing, one price. "Your name as a Romanian folk poem, 2 TON". Not a menu of six.
+  Add a second offer only after the first one sells.
+- **Above the fold, on a phone (375 × 667):** what it is (one line), the price in TON, the Pay button.
+  Nothing to scroll past, no signup, no cookie banner.
+- **Few words.** A headline of up to 8 words, one sentence under it, the button. Cut every adjective
+  you can.
+- **Show the result.** One example of what the buyer gets (an image, a sample text) beats any description.
+
+## The button
+
+- Label it with the action and the price: **Pay 2 TON**, or **Get my poem: 2 TON**.
+- Big (at least 48 px tall), full width on phones, one strong colour, nothing else in that colour.
+- If the buyer must type something first (a name, a photo), put that one field right above the button.
+- After paying, land on `/thanks` with the result, or "Working on it…" and the result appearing when ready.
+  Never a blank page.
+
+## Look
+
+- Plain CSS is enough. One font (the system font is fine), two colours plus grey, generous spacing.
+- Large text: 18 px body on phones, a headline twice that.
+- Dark text on a light background unless your idea needs otherwise.
+- Works with one thumb: tap targets 48 px, no hover-only menus.
+- Loads fast: no video backgrounds, no 3 MB hero images, no animation libraries.
+
+## Words
+
+- Say what they get, not how it works. "A logo for your stand in 1 minute", not "AI-powered logo generation".
+- Prices are TON, written as `2 TON`. TON is the Village play currency; never call it crypto.
+- Write in the language of your buyers. At Hack A Ton that is often Romanian and English; one is fine.
+
+## Before and after
+
+```
+Bad:  Welcome to PoemForge™, the next-generation AI-powered creative writing platform
+      [Features] [Pricing] [About] [Sign up]   …scroll…   [Get started]
+
+Good: Your name as a folk poem
+      Type a name. Get a 4-line Romanian folk poem in 10 seconds.
+      [ Name: _________ ]
+      [   Get my poem: 2 TON   ]
+      "Ana, floare de la munte, / …"  ← one real example
+```

package/skills/ambasada-product/reference/dev-and-deploy.md

@@ -0,0 +1,105 @@
+# Run it, put it online
+
+## `ambasada dev`: everything on your laptop, fake money
+
+```sh
+npx ambasada dev
+```
+
+Starts two things:
+
+1. a **mock Village** on `http://127.0.0.1:8788`: same routes and signatures as the real one, a fake bank
+   (your company 500 TON, the fake visitor `p_visitor` 100, `fake-agent` 100), the real `pay.js`, and an
+   LLM that answers `[mock] …`. Open it in a browser for a dashboard: wallets, offerings, calls.
+2. **your site** with its normal dev server (`next dev` for the `next` template), pointed at the mock.
+
+It registers your offerings with the mock. No login, no real TON.
+
+Try a sale:
+
+- **as a person**: open your site, press Pay, approve as the fake visitor, land on `/thanks`.
+- **as an agent**: `npx ambasada dev buy translate '{"text":"Bună!","to":"en"}'` (the fake agent pays 1 TON).
+
+`npx ambasada dev --mock-only` starts only the mock, if you run your site yourself. The mock's keys:
+`AMBASADA_API_URL=http://127.0.0.1:8788`, `AMBASADA_API_KEY=sk_test_dev` (already in the project's `.env`).
+More on the mock: the ambasada-payments skill, `reference/test-mode.md`.
+
+## `ambasada deploy`: online at `<slug>.hackaton.ambasada.id`
+
+Once, per laptop:
+
+```sh
+npx ambasada login        # opens a page: sign in with Ambasada ID, pick your company
+```
+
+(If it asks for a key instead: the Village app → your team → Developers → Server keys, `sk_live_…`.)
+
+Then, every time you want the new version online:
+
+```sh
+npx ambasada deploy
+```
+
+It does, in order:
+
+1. **build**: `opennextjs-cloudflare build` (Next), `vite build` (spa) or a bundle of the Worker (worker);
+2. **smoke test**: runs the built Worker locally in workerd and requests `/` and `/api/receipt`;
+   a crash stops the deploy (skip with `--no-smoke` only if you know why it fails);
+3. **upload** to the Village's hosting: the URL is `https://<your-company-slug>.hackaton.ambasada.id`,
+   with `AMBASADA_API_KEY`, `AMBASADA_API_URL` and `AMBASADA_COMPANY` set for you;
+4. **agent and offerings**: pushes `agent/agent.md` + `agent/settings.json`, and lists your offerings at the new URL.
+
+No Cloudflare account needed. Options: `--agent-only` (push only `agent/`), `--offerings-only` (only the
+offerings list), `--dry-run` (print what it would push).
+
+After the first deploy, point the webhook at it and deploy again so the Worker gets the secret:
+
+```sh
+npx ambasada webhook set https://<slug>.hackaton.ambasada.id/api/webhook
+npx ambasada webhook test        # should print "delivered"
+```
+
+Limits on Village hosting: 10 MB compressed bundle, 1000 static files, short CPU time per request
+(waiting on `fetch` or the LLM does not count). Heavy work belongs in an API you call, not in the Worker.
+
+## `ambasada deploy --own`: your own Cloudflare account
+
+Runs `wrangler deploy` into your account (you need `npx wrangler login` first), then
+`ambasada link <your workers.dev URL>`. Set the secrets yourself:
+
+```sh
+npx wrangler secret put AMBASADA_API_KEY
+npx wrangler secret put AMBASADA_COMPANY
+npx wrangler secret put AMBASADA_WEBHOOK_SECRET
+```
+
+## `ambasada link`: the product is hosted somewhere else
+
+```sh
+npx ambasada link https://my-thing.lovable.app
+```
+
+Sets `product.url` in `ambasada.config.ts`, checks that `<url>/health` answers, and lists your offerings
+at that URL (relative endpoints like `/api/translate` become `<url>/api/translate`). Use it for Lovable,
+Bolt, v0, Vercel, your own server. See [build-elsewhere.md](build-elsewhere.md).
+
+## Watch it run
+
+```sh
+npx ambasada wallet                       # balance, held, available
+npx ambasada ledger                       # every TON in and out
+npx ambasada logs --agent --follow        # what your agent thinks and does
+npx ambasada steer "raise translate to 1.2 TON for 2 hours"
+```
+
+## When it goes wrong
+
+| Symptom | Fix |
+|---|---|
+| `deploy` prints "Product hosting is not part of `ambasada deploy` yet" | your CLI is old: `npm i -D @ambasada/cli@latest` |
+| build fails on `fs`, `child_process`, a `.node` file, `sharp` | a banned package: see [stack.md](stack.md#nextjs-allowed-and-banned) |
+| smoke test: `/` answers 500 | open `npx ambasada dev`, load `/`, read the terminal error |
+| `CONFIG: no API key` | missing `AMBASADA_API_KEY`: `.env` locally, `ambasada login` before deploying |
+| Pay works, nothing delivered | webhook not set or wrong secret: `ambasada webhook test`, then deploy again |
+| agents can't buy | `ambasada offerings list`: endpoint must be your public URL, not `localhost` |
+| `402` when you call your own offering | right: offerings only answer calls that come through the Gateway with a receipt; test with `ambasada dev buy` |

package/skills/ambasada-product/reference/stack.md

@@ -0,0 +1,109 @@
+# The stack: Next.js on Cloudflare
+
+Every Village product is one Cloudflare Worker. The default template builds it from **Next.js 16.4**
+with **@opennextjs/cloudflare 1.20** (the OpenNext adapter) and the `nodejs_compat` flag. You write a
+normal Next.js App Router app; `ambasada deploy` turns it into a Worker.
+
+## Folder layout (template `next`)
+
+```
+my-shop/
+  app/page.tsx                 the landing page: what you sell, the price, the Pay button
+  app/thanks/page.tsx          after paying: checks the session on the server, then delivers
+  app/api/checkout/route.ts    creates a Checkout session, redirects to the Village approve page
+  app/api/webhook/route.ts     checkout.paid arrives here, signed: deliver here
+  app/api/receipt/route.ts     verifies a pay.js receipt from the browser
+  app/api/translate/route.ts   the paid offering: agents call it with a receipt
+  lib/ambasada.ts              the Village client for server code (reads the Worker env)
+  offerings.ts                 what agents can buy: name, price, endpoint, input and output
+  agent/agent.md               your agent's instructions, in plain English
+  agent/settings.json          its model, how often it wakes, spending limits
+  ambasada.config.ts           company id and name, idea, product URL, where offerings and agent live
+  wrangler.jsonc               Worker settings (nodejs_compat, assets); no bindings needed
+  open-next.config.ts          OpenNext settings; leave as is
+  .env                         secrets for local runs (never commit, never send to the browser)
+  .claude/skills/              this skill and ambasada-payments
+```
+
+One more paid offering = one more `app/api/<name>/route.ts` plus one more entry in `offerings.ts`
+(the file `ambasada.config.ts` points to with `offerings:`). `ambasada deploy` and `ambasada offerings sync` push
+that list to the market. An offering name is a slug (`a-z`, `0-9`, `_`, `-`); price 0.1–500 TON.
+
+## Using the client
+
+Server code only (route handlers, server components, server actions):
+
+```ts
+// app/api/translate/route.ts
+import { ambasada } from "../../../lib/ambasada.ts";
+
+export const POST = (req: Request) =>
+  ambasada().sell<{ text: string; to: string }>("translate", async ({ text, to }) => ({
+    text: await ambasada().llm(`Translate to ${to}. Reply with the translation only.\n\n${text}`),
+  }))(req);
+```
+
+`lib/ambasada.ts` creates one client per Worker instance with `createAmbasada({ env })` from `@ambasada/sdk`,
+where `env` comes from `getCloudflareContext()` (deployed); under `next dev` the SDK reads `process.env`.
+It reads `AMBASADA_API_KEY`, `AMBASADA_API_URL`, `AMBASADA_COMPANY`, `AMBASADA_WEBHOOK_SECRET`.
+Everything the client can do is in the ambasada-payments skill.
+
+## Next.js: allowed and banned
+
+Allowed, and enough for any product here:
+
+- pages and layouts (`app/**/page.tsx`, `layout.tsx`), server components, client components (`"use client"`)
+- route handlers (`app/api/**/route.ts`), server actions (`"use server"`)
+- `fetch` to any HTTPS API, `next/link`, `next/font`, plain CSS / CSS modules / Tailwind
+
+Banned (they fail on Workers or break the deploy):
+
+| Don't | Do instead |
+|---|---|
+| `next/image` with the default loader | `<img>`, or `images: { unoptimized: true }` in `next.config.ts` |
+| ISR, `export const revalidate = …`, `revalidatePath`, `unstable_cache` | render on each request (`export const dynamic = "force-dynamic"`), or save results in `ambasada.store` |
+| `fs`, `child_process`, `sharp`, `bcrypt`, `sqlite3`, `puppeteer`, any native package | `fetch` an API; the Village sells LLM, images and web tools (`ambasada.llm`, `ambasada.images`, `ambasada.tools`) |
+| a custom server (`server.js`, Express inside Next) | route handlers |
+| `middleware.ts` / `proxy.ts`, `export const runtime = "edge"` | check inside the page or route handler; Next's default runtime is right |
+| Prisma, Drizzle with a database, Supabase, Firebase, Mongo | `ambasada.store` and `ambasada.files` |
+| writing files at runtime, global variables as storage | `ambasada.store` (each request can run on a different machine) |
+
+Keep the bundle small: the Worker limit is 10 MB compressed. Big UI kits and icon packs are the usual cause.
+
+## Where data lives
+
+No database of your own. Two primitives, free, scoped to your company:
+
+| | For | Calls |
+|---|---|---|
+| `ambasada.store` | orders, credits, settings, small results: JSON, 1 MB per company in total | `get(key)`, `set(key, value)`, `delete(key)`, `list()` |
+| `ambasada.files` | images, PDFs, audio you deliver | `files.put(bytes \| Blob \| url, { contentType })` → `{ url }` (public) |
+
+```ts
+const a = ambasada();
+await a.store.set(`order:${id}`, { item: "poster", paid: false });
+const order = await a.store.get(`order:${id}`);
+const { url } = await a.files.put(pngBytes, { contentType: "image/png" });
+```
+
+`ambasada.store` is new: if `store` is missing on the client, update `@ambasada/sdk`.
+File URLs are public: don't put private data in them.
+
+## Secrets
+
+- Local: `.env` in the project (Cloudflare's `.dev.vars` works too). The template writes it with test
+  values for `ambasada dev`. Both are in `.gitignore`; keep them there.
+- Deployed: `ambasada deploy` injects `AMBASADA_API_KEY`, `AMBASADA_API_URL` and `AMBASADA_COMPANY` for you.
+  With `--own`, set them yourself: `npx wrangler secret put AMBASADA_API_KEY`.
+- Other services' keys (an OpenAI key, say): same place, read on the server only.
+- Anything named `NEXT_PUBLIC_*` is copied into the browser. Never put a key there.
+- Never paste a key into a page, a client component, a prompt for a no-code builder, or a commit.
+
+## Variants
+
+- `spa`: Vite + React with `@cloudflare/vite-plugin`, for code exported from Lovable or Bolt. Same
+  `api/` endpoints as small fetch handlers; the React app calls them with `fetch("/api/…")`.
+- `worker`: `web/` (plain HTML/CSS) plus `api/*.ts` fetch handlers. Best when the product is one form
+  and one button.
+
+The rules on this page (state, secrets, no native packages) apply to all three.

package/skills/ambasada-payments/recipes/express.md

@@ -1,48 +0,0 @@
-# Express
-
-`npm i @ambasada/sdk express` · env: `AMBASADA_API_KEY`, `AMBASADA_WEBHOOK_SECRET` (+ `AMBASADA_API_URL=http://127.0.0.1:8788` on `ambasada dev`)
-
-```ts
-import express from "express";
-import { isVillageError, village } from "@ambasada/sdk";
-
-const app = express();
-const raw = express.raw({ type: "*/*", limit: "1mb" }); // receipts and webhooks are signed over the raw bytes
-
-// An offering agents pay for.
-app.post("/api/translate", raw, async (req, res) => {
-  try {
-    const { input, buyer, amount } = await village.verifyReceipt(req, { offering: "translate" });
-    const text = await village.llm(`Translate to ${input.to}. Reply with the translation only.\n\n${input.text}`);
-    res.json({ text }); // 2xx = you get paid; any error status = buyer refunded
-  } catch (e) {
-    if (isVillageError(e)) return res.status(e.status || 500).json(e.toJSON()); // 402 when unpaid
-    throw e;
-  }
-});
-
-// People pay.
-app.post("/buy", express.json(), async (req, res) => {
-  const session = await village.checkout({
-    amount: 3,
-    description: "Coffee for the team",
-    success_url: "https://my.app/thanks?session={CHECKOUT_SESSION_ID}",
-  });
-  res.redirect(303, session.url);
-});
-
-app.post("/village-webhook", raw, async (req, res) => {
-  try {
-    const event = await village.verifyWebhook(req);
-    if (event.type === "checkout.paid") await fulfil(event.data.session, event.id);
-    res.sendStatus(200);
-  } catch {
-    res.sendStatus(400);
-  }
-});
-
-app.listen(3000);
-```
-
-Don't put `app.use(express.json())` in front of the paid routes: once the body is parsed the bytes are gone
-and `verifyReceipt` refuses with a `CONFIG` error. Full example: `examples/express-seller` in the village repo.

package/skills/ambasada-payments/recipes/fastapi.md

@@ -1,68 +0,0 @@
-# FastAPI (or any language over plain HTTP)
-
-`pip install fastapi uvicorn httpx pyjwt[crypto] standardwebhooks`
-
-```python
-import hashlib, json, os, httpx, jwt
-from fastapi import FastAPI, Request, HTTPException
-from standardwebhooks.webhooks import Webhook
-
-API = os.environ.get("AMBASADA_API_URL", "https://hackaton.ambasada.id")
-KEY = os.environ["AMBASADA_API_KEY"]
-COMPANY = os.environ["AMBASADA_COMPANY"]          # your company id
-HEADERS = {"Authorization": f"Bearer {KEY}"}
-app = FastAPI()
-_keys = {k["kid"]: jwt.PyJWK(k) for k in httpx.get(f"{API}/.well-known/jwks.json").json()["keys"]}
-_seen: set[str] = set()
-
-def verify_receipt(token: str | None, body: bytes, offering: str) -> dict:
-    if not token:
-        raise HTTPException(402, "payment required")
-    key = _keys.get(jwt.get_unverified_header(token).get("kid"))
-    if not key:
-        raise HTTPException(402, "unknown village key")
-    try:
-        c = jwt.decode(token, key, algorithms=["EdDSA"], issuer="village")  # checks signature + exp
-    except jwt.PyJWTError as e:
-        raise HTTPException(402, f"bad receipt: {e}")
-    if c.get("kind") or c["seller"] != COMPANY or c["offering"] != f"{COMPANY}/{offering}":
-        raise HTTPException(402, "receipt is for another offering")
-    if hashlib.sha256(body).hexdigest() != c["body_sha256"] or c["call_id"] in _seen:
-        raise HTTPException(402, "receipt does not match this request")
-    _seen.add(c["call_id"])
-    return c
-
-def llm(prompt: str) -> str:
-    r = httpx.post(f"{API}/v1/llm/chat", headers=HEADERS, timeout=60,
-                   json={"model": "deepseek-v4.1-flash", "messages": [{"role": "user", "content": prompt}]})
-    r.raise_for_status()
-    return r.json()["choices"][0]["message"]["content"]
-
-@app.post("/api/translate")                       # offering endpoint agents pay for
-async def translate(request: Request):
-    body = await request.body()                   # raw bytes first
-    verify_receipt(request.headers.get("x-village-receipt"), body, "translate")
-    data = json.loads(body)
-    return {"text": llm(f"Translate to {data['to']}. Reply with the translation only.\n\n{data['text']}")}
-
-@app.post("/buy")                                 # people pay
-def buy():
-    s = httpx.post(f"{API}/v1/checkout/sessions", headers=HEADERS, json={
-        "amount": 3, "description": "Coffee for the team",
-        "success_url": "https://my.app/thanks?session={CHECKOUT_SESSION_ID}"}).json()
-    return {"url": s["url"]}
-
-@app.post("/village-webhook")
-async def webhook(request: Request):
-    body = await request.body()
-    try:
-        event = Webhook(os.environ["AMBASADA_WEBHOOK_SECRET"]).verify(body, dict(request.headers))
-    except Exception:
-        raise HTTPException(400, "bad signature")
-    if event["type"] == "checkout.paid":
-        fulfil(event["data"]["session"], request.headers["webhook-id"])
-    return "ok"
-```
-
-Buy from another company: `httpx.post(f"{API}/v1/pay/inkwell/poem", headers={**HEADERS, "Idempotency-Key": str(uuid4()), "x-village-max-price": "2"}, json=input)`.
-Errors come back as `{"error": {"code": …}}` with the HTTP status. Go, PHP, Ruby: same calls.

package/skills/ambasada-payments/recipes/workers.md

@@ -1,27 +0,0 @@
-# Cloudflare Workers
-
-`npm i @ambasada/sdk`, `wrangler secret put AMBASADA_API_KEY` (and `AMBASADA_WEBHOOK_SECRET`). Workers have no
-`process.env`, so create the client from `env`:
-
-```ts
-import { createAmbasada } from "@ambasada/sdk";
-
-export default {
-  async fetch(req: Request, env: Record<string, string>): Promise<Response> {
-    const village = createAmbasada({ env }); // AMBASADA_API_KEY, AMBASADA_API_URL, AMBASADA_COMPANY, AMBASADA_WEBHOOK_SECRET
-    const { pathname } = new URL(req.url);
-    if (pathname === "/api/translate") {
-      return village.sell("translate", async ({ text, to }) => ({ text: await village.llm(`Translate to ${to}: ${text}`) }))(req);
-    }
-    if (pathname === "/village-webhook") {
-      const event = await village.verifyWebhook(req);
-      if (event.type === "checkout.paid") { /* fulfil event.data.session */ }
-      return new Response("ok");
-    }
-    return new Response("not found", { status: 404 });
-  },
-};
-```
-
-Set `AMBASADA_COMPANY` to your company id to skip one API call per isolate for receipt checks. Receipt keys
-are cached per isolate for 10 minutes. Bun, Deno and Next.js route handlers use the same fetch-style code.