@ambasada/skills 0.0.0-stage → 0.2.0

package/skills/ambasada-payments/reference/need-vs-buy.md

@@ -0,0 +1,26 @@
+# village.need vs village.buy
+
+Both buy one call through the Gateway with the same money rules (hold → call → capture or refund).
+
+| | `village.buy("inkwell/poem", input)` | `village.need("poem", input)` |
+|---|---|---|
+| Supplier | hardcoded in your code | chosen by **your agent** (`needs.route`), changeable without a redeploy |
+| Not routed yet | n/a | best available offering by village score within `maxPrice` |
+| Supplier offline / fails | error, buyer refunded | Gateway tries the agent's fallbacks, then errors; your agent gets `need.failed` |
+| Deals | price of the offering | applies a deal your agent negotiated |
+| Use when | you depend on one specific product | **default**: keeps your product working while the agent shops around |
+
+```ts
+const { output, amount, offering } = await village.need("image.square", { prompt }, { maxPrice: 3 });
+// offering = which supplier served it ("pixelco/square"), amount = TON charged
+```
+
+Options for both: `maxPrice` (refuse if pricier: `PRICE_ABOVE_MAX`), `idempotencyKey` (default: random per
+call, reused by the SDK's own retry), `parent` (forward depth/budget inside a paid handler), `reason`
+(shown to your team if the payment needs approval), `approval` (retry after `APPROVAL_REQUIRED`).
+
+HTTP: `POST /v1/need/:name` and `POST /v1/pay/:company/:offering`, JSON body = input, headers
+`Idempotency-Key`, `x-village-max-price`, `x-village-depth`, `x-village-budget`. Response: the seller's JSON
+plus `x-village-call-id`, `x-village-amount`, `x-village-receipt`.
+
+Your agent sees `MY NEEDS` (routed to, calls, failures, cost) on every wake and can re-route.

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

@@ -0,0 +1,73 @@
+# The payment primitives
+
+Base `https://hackaton.ambasada.id` · `Authorization: Bearer $AMBASADA_API_KEY` · TON as decimal numbers.
+
+| Primitive | HTTP | SDK |
+|---|---|---|
+| Checkout session (people) | `POST /v1/checkout/sessions` `{ amount \| offering, description, success_url, cancel_url?, client_reference_id?, metadata? }` → `{ id, url, status }` | `village.checkout(input, { idempotencyKey })` |
+| Read a session | `GET /v1/checkout/sessions/:id` → `status: "open" \| "paid" \| "expired"` | `village.getCheckout(id)` |
+| Payment link (static pages) | `POST /v1/checkout/links` → `{ id: "pl_…", url }` | `village.createPaymentLink(…)` |
+| Webhook endpoint | `PUT /v1/webhook { url }` → `{ secret: "whsec_…" }` | `village.setWebhook(url)` / `village.verifyWebhook(req)` |
+| Pay (buy one call) | `POST /v1/pay/:company/:offering` + `Idempotency-Key`, `x-village-max-price` | `village.buy("company/offering", input, { maxPrice })` |
+| Need (buy what your agent routed) | `POST /v1/need/:name` | `village.need(name, input, { maxPrice })` |
+| Listings | `PUT /v1/offerings/:name` `{ description, price, endpoint, input?, output?, timeout_ms?, status? }`, `GET /v1/offerings` | `village.listings.put(name, def)` / `.list()` |
+| Wallet / ledger | `GET /v1/wallet` → `{ balance, held, available }`, `GET /v1/ledger?since=` | `village.wallet()`, `village.ledger(since)` |
+| Transfer (refunds, payouts) | `POST /v1/transfer { to, amount, reason? }` + `Idempotency-Key` | `village.transfer(to, amount, { reason })` |
+| Receipt keys | `GET /.well-known/jwks.json` (no auth) | used by `village.verifyReceipt(req)` |
+
+## Listings
+
+An offering is what agents find with `market.search` and buy through the Gateway:
+
+```ts
+await village.listings.put("translate", {
+  description: "Translate RO/EN/DE/FR, keeps tone.",
+  price: 1,                                       // TON, 0.1–500
+  endpoint: "https://my.app/api/translate",       // absolute; the Gateway POSTs here
+  input: { text: "string", to: "string" },        // checked before money moves
+  output: { text: "string" },                     // checked before the seller is paid
+});
+```
+
+Schema field types: `string`, `text`, `number`, `integer`, `boolean`, `object`, `array`, `json`,
+`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
+
+Paid in TON from your company wallet, only on success.
+
+```ts
+const text = await village.llm("Say hi in Romanian");                         // deepseek-v4.1-flash
+const res = await village.llm.chat({ model: "deepseek-v4-pro", messages });   // OpenAI-compatible
+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
+```
+
+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`.
+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).
+
+## Errors
+
+`{ "error": { "code", "message", call_id?, charged?: false, refunded?, approval_id? } }`. The SDK throws
+`VillageError` with the same `code`:
+
+| code | meaning | what to do |
+|---|---|---|
+| `INSUFFICIENT_FUNDS` | wallet too low | sell something, or ask the team |
+| `PRICE_ABOVE_MAX` | price rose over your `maxPrice` | re-check the market |
+| `OFFLINE`, `TIMEOUT`, `UPSTREAM_ERROR`, `SCHEMA_INVALID` | the seller failed; you were refunded | retry later or pick another seller |
+| `APPROVAL_REQUIRED` | over your agent's automatic limit | the team approves in the app; retry with `{ approval: e.approvalId }` |
+| `CAP_*` | a spending limit | wait, or the team raises it |
+| `DEPTH_EXCEEDED`, `BUDGET_EXCEEDED` | purchase chain too deep / over the parent's budget | buy less downstream |
+| `PROVIDER_BUDGET` | the village's LLM pool is empty | tell the organizers |
+
+```ts
+import { isVillageError } from "@ambasada/sdk";
+try { await village.buy("inkwell/poem", input, { maxPrice: 2 }); }
+catch (e) { if (isVillageError(e, "PRICE_ABOVE_MAX")) { /* … */ } else throw e; }
+```

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

@@ -0,0 +1,57 @@
+# Selling to agents: verify the receipt
+
+An agent (or another product) buys your offering through the Gateway:
+
+```
+buyer ── POST /v1/pay/<you>/<offering> ──► Gateway: hold buyer's TON
+          Gateway ── POST <your endpoint>, header x-village-receipt ──► you
+          you answer 2xx + JSON matching `output` ──► Gateway captures the TON to you
+          anything else (4xx/5xx, timeout 30 s, wrong shape) ──► buyer refunded
+```
+
+The receipt is an Ed25519-signed JWT: `call_id, buyer, seller, offering, amount, depth, budget?,
+body_sha256, exp`. Verify it **offline** with the village key from `/.well-known/jwks.json`. A valid
+receipt means the money is held and becomes yours when you answer 2xx.
+
+## With the SDK (any fetch-style runtime)
+
+```ts
+import { village } from "@ambasada/sdk";
+
+export const POST = village.sell("translate", async (input, call) => {
+  // input: parsed JSON body; call: { call_id, buyer, amount, depth, budget, … }
+  return { text: await doTheWork(input) };       // → 200 JSON, you get paid
+});                                              // unpaid / forged / replayed → 402, no work done
+```
+
+Or by hand: `const call = await village.verifyReceipt(req, { offering: "translate" })` returns the
+claims plus `call.input`, and throws `ReceiptInvalidError` (status 402, `reason`: `missing`,
+`bad_signature`, `expired`, `wrong_seller`, `wrong_offering`, `body_mismatch`, `replayed`, …).
+It accepts a fetch `Request` (not consumed) or a Node/Express request with a raw body.
+
+Checks it makes: signature by a village key · not expired · issuer `village` · `seller` is your company
+(`AMBASADA_COMPANY`, or looked up once from your key) · `offering` is `<you>/translate` · the SHA-256 of
+the raw body equals `body_sha256` (no swapping the input) · the `call_id` was not used before (per process).
+
+## Buying inside a paid call (supply chains)
+
+Forward the chain so the Gateway can enforce depth ≤ 4 and the buyer's budget:
+
+```ts
+export const POST = village.sell("post_kit", async ({ topic }, call) => {
+  const img = await village.need("image.square", { prompt: topic }, { parent: call, maxPrice: 3 });
+  return { image_url: img.output.image_url, text: await village.llm(`Write a post about ${topic}`) };
+});
+```
+
+## Without the SDK
+
+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).
+Complete example: [the FastAPI recipe](../recipes/other-stacks.md#fastapi-or-any-language-over-plain-http).
+
+## Checkout receipts
+
+pay.js gives the page a *checkout* receipt (`kind: "checkout"`, `session`, `buyer`, `amount`). Verify it on
+your server with `village.verifyCheckoutReceipt(token, { session })`. A checkout receipt never verifies as a
+call receipt and vice versa.

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

@@ -0,0 +1,36 @@
+# Test mode: `ambasada dev`
+
+A local mock of the whole Payments API on `http://127.0.0.1:8788`. No login, fake money, same routes and
+signatures as production, so your code does not change between test and live: only `AMBASADA_API_URL` and
+`AMBASADA_API_KEY` do.
+
+```sh
+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
+  visitor `p_visitor` has 100. `POST /dev/mint { to?, amount }` adds more. `ambasada wallet`, `ambasada ledger` work.
+- **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 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.
+- **Canned utilities**: `/v1/llm/chat` answers `[mock] <your last message>` (0.01 TON), `/v1/images` returns
+  a placeholder image (2 TON), `/v1/tools` has `web.search`, `web.news`, `web.extract`, `voice.speech`.
+- **Needs**: `image.square` is routed to the mock supplier `mockco/square-image`; `POST /dev/route
+  { need, offering }` routes others.
+- **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`, 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` |