@agentshouse/skills 0.1.0-c221fe4e31976 → 0.1.0-c22b29c83d792

package/guide/apps/chat.md

@@ -9,9 +9,10 @@ object House hands the page as `window.houseBridge`, which `houseBridge()` of
 `@agentshouse/app-bridge` returns, draws it in `element` over the App's own client and
 resolves to a handle: `chat.update(options)` replaces its options and `chat.unmount()`
 removes it. It fills the element and lays itself out by the width it gives: the list of the
-User's Agents and their chats or one chat on a narrow element, the list beside the chat on a
-wider one once the User shows it or the element passes 1000 px, and the chat's details beside
-both on a wide one. With no chat open it shows what
+User's Agents and their chats or one chat on a narrow element, and on a wider one the list
+beside the chat while the User shows it by its toggle, closed at first beside an open chat and
+open where none is, the conversation keeping its width where the element has room for both.
+With no chat open it shows what
 asks the User and what works now. `conversation` opens one chat, and with it `null` the Chat
 opens a new chat with `agent`, the Agent it goes to, or the list with neither. `onOpen` hears
 each chat it opens as `{ conversation, agent }`, and both `null` when the User goes back to the
@@ -24,8 +25,9 @@ Chat in a sheet above the page, and pressing it again hides it. With `agent` amo
 the dot's first press opens it on a new chat with that Agent instead of a chat kept from an
 earlier visit, and later presses reopen the chat it last showed; the sheet stays hidden until
 the first press. The dot stays in view over the
-sheet, which the User moves, resizes up to the window's edges and lets fill the window, and the
-page under it never changes, so leave nothing of the page to make room for it.
+sheet, which the User moves, resizes up to the window's edges and lets fill the window, and
+whose list, closed at first, widens it to the left by the list's own width; the page under it
+never changes, so leave nothing of the page to make room for it.
 `button.open(target)` opens the sheet, on `{ conversation }` or on a new chat with
 `{ agent }`, or as it was with no target, and with `docked: true` docked at full height along
 the window's right edge; `button.hide()` hides it, keeping its chat, scroll and typed text;
@@ -46,5 +48,5 @@ element, set them on the document's root element. Its dot is House's and takes n
 It shows conversations only where the release declares them;
 otherwise it lists no conversation and no Agent. A secret
 question is never answered here; typed answers live in the Presentation State members named
-`typed:…`, whether the list shows in `chat:page-list`, and the sheet's size, place, list and
-open chat in `chat:sheet`: leave them.
+`typed:…`, and the sheet's size, place, whether it fills the window and its open chat in
+`chat:sheet`: leave them.

package/guide/apps/local-first.md

@@ -2,16 +2,16 @@
 
 How an App reads and writes its Rooms on the device, offline too.
 
-- The runtime holds every bound Room on the device and streams in every change from any device, App or agent. `query` and `observe` answer from the device and never wait on the network; `search` asks House ([Search rules](apps/search)).
+- The runtime holds every bound Room on the device and streams in every change from any device, App or agent, but a Search-level Room, which an App shows only as the rows [`queryHouse`](apps/query-house) asks for, never offline. `query` and `observe` answer from the device and never wait on the network; `search` asks House ([Search rules](apps/search)).
 - Draw from `observe` at once, with no request of your own; an observation hears each later change by itself, so never poll, refetch or subscribe. An answer is `{ pending }` while a Room it reads has not reached this device or been prepared on it: draw the page without those documents; keep the empty state for a complete answer. `rooms` answers once the runtime knows the Rooms the page reaches. Offer binding a Room when it is empty while the sync status's `providerUnreachable` is false and `observe('connection-refusal')` answers `null`; any other empty list says only that nothing can be listed yet.
 - Show no loading state: draw the last state the device holds. A wait shows only after an act the User pressed whose answer comes from outside the stream, such as `bridge.callExternal`, until it arrives.
 - Write optimistically: write a Room Draft, then `save`. The change shows in every query at once as a Pending Change and reaches House when it can. `save` refuses at once, with its `code`, a change that is `stale`, `changed-underneath` or against the schema: say so and keep the form. After `changed-underneath`, draw the joined Room Draft and its `marks` ([Room Drafts](apps/room-drafts)).
 - Show what the runtime reports: `observe('queue', room)` lists changes House has not confirmed yet, and `observe('sync-status')`'s `attentionRequired` lists each change House refused, returned as a Room Draft with why, to save again or discard.
-- Keep what the User types in the Room Draft (`roomDraft.write`) as they type; it survives a new release replacing the page, a reload and another tab. Draw a form again only when its page changes, never on a streamed change.
+- Keep what the User types in the Room Draft (`roomDraft.write`) as they type; it survives a new release, a reload and another tab. Draw a form again only when its page changes, never on a streamed change.
 - A document has one Room Draft, shared by every tab and App, and `save` takes all of it. A write replaces every part and names the revision it read, so write onto the parts it holds; one from an older revision answers `stale` with the current Room Draft: show that one. A field part names as its `base` the value the page showed, `{ value }`, or `null` when the document has no such field.
 - Save a change the User does not type, such as a checkbox, with `saveParts(room, [{ path, parts }])`: it writes no Room Draft, so the one another tab holds stays.
 - Offline, all of this works and saves wait; `bridge.onStatus` reports `offline`: say so quietly.
-- A Room your User holds at the Open level locks once the browser has been offline 2 minutes, and from the moment it opens until House confirms the access. While it is locked, `rooms` lists it `locked: true`, a query that does not name it leaves it out, one naming it answers `{ pending }` with `awaits: 'unlock'`, and every other read and write naming it, `save` included, answers the code `room-locked` and keeps nothing. Draw it locked until it unlocks and keep what the User types in the page; what was saved before stays and is sent then.
-- An outside service is reached only at the origins `app.json` lists in `external_origins`, directly or through `bridge.callExternal`, sent by House's server. A call that names a Room bound to the App in a `write` slot with `room_ref` carries that Room's Service key for the origin, which the page never sees; any other call carries no key. A call through a Room that holds no key for the origin is refused `not_found` naming the `origin`: tell the person that the Room's owner or a manager enters the key under Connected on the Room's Settings page, since no App opens that page.
+- A Room your User holds at the Open level locks once the browser has been offline 2 minutes, and from the moment it opens until House confirms the access. While it is locked, `rooms` lists it `locked: true`, a query that does not name it leaves it out, one naming it answers `{ pending }` with `awaits: 'unlock'`, and every other read and write naming it, `save` included, answers the code `room-locked` and keeps nothing. Draw it locked until then and keep what the User types; what was saved before is sent then.
+- An outside service is reached only at the origins `app.json` lists in `external_origins`, directly or through `bridge.callExternal`, sent by House's server. A call whose `room_ref` names a Room bound in a `write` slot carries that Room's Service key for the origin, unseen by the page; any other carries none. Through a Room holding no key for the origin it is refused `not_found` naming the `origin`: tell the person its owner or a manager enters the key under Connected in the Room's Settings, which no App opens.
 - The page's own storage is a disposable cache, the Room the only durable home of the App's data; handle any code or value you do not know by its `code` ([Refusals](apps/runtime-refusals)).
 - React: `useObserve` and `useSave` from `@agentshouse/mdruntime/react`. The whole client: [The App runtime](apps/runtime).

package/guide/apps/query-house.md

@@ -0,0 +1,31 @@
+# House query rules
+
+How `queryHouse` asks House for pages of rows of a Room the device never holds.
+
+A Room your User holds at the Search level never reaches the device. `rooms` lists it with
+`queriesOnly: true` and nothing held, a [Local Query](apps/local-query) naming it fails with
+the code `queries-only`, and one naming no Room leaves it out; its writes, history, files and
+`resolve` answer as for a Room the App does not bind.
+
+- **Asking.** `queryHouse(query)` takes a Document query in the language of a Local Query
+  whose `rooms` names that one Room, and asks House once, online. Nothing observes it: no
+  `observe`, hook or `readAgain` asks it again, so ask again when the page needs the rows
+  again, such as when the person scrolls, opens it again or presses refresh. `call` reaches no
+  `rooms/query`.
+- **A page.** `{ kind: 'rows', documents, next }`: at most 100 rows, read in Path order,
+  ascending or with `orderBy: [{ by: 'path', direction: 'desc', stringSort: 'lexical' }]`.
+  Pass `next` as `after` for the next page. A page may hold fewer rows than `limit`, or none,
+  and still name `next`: only an answer without `next` is the end.
+- **Refusals.** House answers `{ kind: 'rejected', code, fields }` for a part that would read
+  the whole Room, such as another order, `groupBy`, `total`, `hop`, `backlinks`, `fileIds`,
+  `select: 'all'` or a `limit` of 0, as `invalid-query` with a `message` naming the part, and
+  for a query over 8,000 bytes as `query_too_large` with its `cap`: fix the query.
+- **Offline.** Without a connection `queryHouse` answers `{ kind: 'offline' }` at once: show
+  nothing of that Room and say it needs a connection. A lost answer is
+  `transport-uncertainty`, which the page may ask again, and where no House query is reached,
+  `{ kind: 'undeclared' }`.
+- **Other Rooms.** A Room the device holds answers `rejected` with the code
+  `held-on-device`: read it with a Local Query. A Room the App does not reach answers
+  `room-not-readable`.
+- **Nothing kept.** The rows reach the page alone: the device keeps none of them, so they are
+  gone once the page closes, and asking again shows what the Room holds then.

package/guide/apps/runtime-api.md

@@ -3,7 +3,7 @@
 What App code reaches through the runtime's client: its surfaces, its reach, observations, Agents and conversations.
 
 App code reaches the MD Runtime through the remote client. The surfaces are Rooms, Query,
-Search, Observe, Types, Room Draft, Save, History, Resolve, binary files, Call,
+Search, House query, Observe, Types, Room Draft, Save, History, Resolve, binary files, Call,
 Reached, the reported persistence answer, reauthorization, conversation, the chat
 draft, and Presentation State. Sync Status, readiness, the Service Mode, the storage-loss
 statement, the deployment facts, the signed-in member and the count of authority changes
@@ -11,7 +11,8 @@ are observations only.
 
 The host attaches each port with its reach, and every member and observation answers
 within it: a Room outside it answers as one the replica does not hold, Rooms lists only
-the Rooms reached whole, a Room reached for single Documents shows only them and their
+the Rooms reached whole and, after them with `queriesOnly: true`, those its User holds at the
+Search level, which only `queryHouse` reads ([House query rules](apps/query-house)), a Room reached for single Documents shows only them and their
 models' Types, and without conversations the conversation members, chat draft and
 observation hold none. A changed reach reaches every open observation as its new value.
 

package/guide/apps/runtime.md

@@ -8,6 +8,7 @@ change it, build, and push. They are documentation, not enforcement.
 - [The MD Runtime API](apps/runtime-api)
 - [Local Query rules](apps/local-query)
 - [Search rules](apps/search)
+- [House query rules](apps/query-house)
 - [Room Draft, Save, and outcome rules](apps/room-drafts)
 - [Content safety and launch promises](apps/content-safety)
 - [App code takes the client its host hands it and never constructs a Runtime](apps/client)

package/guide/sites/build.md

@@ -12,8 +12,10 @@ Build it as [Build an App](apps/build) says, with what follows. Anything private
 - Everything it shows lives as documents in its Room; put its demo data there, never in code.
 - A visitor's edits stay in their browser and never reach House: write them with `save` as an App does.
 - To receive messages from visitors, name an Intake Room with `sites/intake-room/set` and send each with `runtime.call('sites/submissions/create', { content })`, online only. `content` is one Markdown document the Intake Room's `settings/schema.yaml` accepts, and House adds its `site` and `submitted` fields. The call answers `{ kind: 'action', result: { submitted: true } }` once House stored it. Anything else stored nothing: `{ kind: 'rejected', code }` says why, such as `bot_check_failed` for a browser that failed the bot check, as automated test browsers do, `site_intake_room_absent`, `invalid_documents` with the `path`, `rule` and `field` it broke, `submission_reserved_key`, `submission_too_large`, `limit_reached` or `cap_reached`. So thank the visitor only for `submitted`, and otherwise show that nothing was sent.
+- A Site loads House's servers when it is bound to a Room that changes often, or when it writes once per visitor, such as a Submission sent on every visit: send one only when a visitor asks to.
+- Code that holds a key, such as one opening a checkout, runs in one of the App's functions, which the page calls: [A Site's function calls](sites/functions). [A Site's payments](sites/payments) takes payments with them.
 - `sites/describe` sets the title and description search engines show.
 - With `google_analytics_id` set by `sites/describe`, House measures a visitor only after they accept. While `bridge.onStatus` reports `analytics.measures`, ask them on the Site unless `analytics.choice` holds their answer, report it with `bridge.analyticsConsent('accept')` or `bridge.analyticsConsent('decline')`, and keep a way on every page to decline later, which reloads the page unmeasured.
 - See it yourself: open its url, which needs no sign-in.
 
-House serves each route as HTML by the [Entry Data Contract](sites/entry-data-contract), and [The App runtime on a Site](sites/runtime) says what the runtime does differently there.
+Build its first screen as [A Site's first load](sites/first-load) says. House serves a route as HTML only where the [Entry Data Contract](sites/entry-data-contract) declares it, and [The App runtime on a Site](sites/runtime) says what the runtime does differently there.

package/guide/sites/entry-data-contract.md

@@ -1,12 +1,20 @@
 # Entry Data Contract
 
-How a Site App's `entry_data` has House serve each route as HTML from Rooms.
+How a Site App's `entry_data` has House serve each route as HTML before the App starts.
 
-Entry Data Contract, `entry_data` in a Site App’s `app.json`: House serves each route as HTML from your Rooms before the App starts, running none of your code. Each of `routes` has a `path` (`/`, `/posts/:slug`), optional `query` (functional `?name` parameters with defaults), `queries` (Local Query objects with `types` and a `pathPrefix` at each scope, no `rooms` or `fileIds`; `{"$param": "slug"}` takes an argument, `"as": "integer"` converts it; `boundQuery` from `@agentshouse/mdruntime/entry` fills the same query in your page), `interaction` (the queries its first interaction needs), `title`, `description` and `body`. A body node is text, `{text: v}`, `{markdown: v}` of a document, `{tag, attrs, children}`, `{each: v, as, children}` or `{if: v, then, else}`; a value `v` is a literal, `{param}`, `{at, pointer}` into a query result or `each` item, `{join: [v]}`, `{count: v}` or `{stem: v}`. An `img`, a document's images among them, loads lazily in the box its `width` and `height` name, 16:9 without them. `styles` lists release CSS files. A route that fails starts the App as usual, and the Site document names why.
+Entry Data Contract, `entry_data` in a Site App’s `app.json`: House serves each route in its `routes` list as HTML before the App starts, running none of your code. A Site has an Entry Page only for a route you list; any other address starts the App as usual.
+
+A static route, one with no `queries` and no parameter, names only its `path`. Its Entry Page is your release's own HTML for that path: the `entry` document for `/`, `about/index.html` for `/about`. Write the route's first screen into that HTML. The push reads it without running it: it keeps the body's text and its plain elements (headings, paragraphs, lists, tables, links, images and the like), drops scripts, `on…` attributes and every other element (`button`, `form`, `svg`, `picture` among them) with its content, resolves relative addresses, drops an image the release lacks, and takes the head's `<title>`, `<meta name="description">` and each release stylesheet it links for every screen (no `media` but `all` or `screen`, not `alternate`). A static route that declares `body`, `title`, `description` or `styles`, whose HTML the release lacks, that links more than 8 stylesheets, or whose body passes 2000 nodes, 24 levels or, with every other route, 64 kB, refuses the push.
+
+A route that reads Rooms or takes a parameter declares its Entry Page: a `path` (`/`, `/posts/:slug`), optional `query` (functional `?name` parameters with defaults), `queries` (Local Query objects with `types` and a `pathPrefix` at each scope, no `rooms` or `fileIds`; `{"$param": "slug"}` takes an argument, `"as": "integer"` converts it; `boundQuery` from `@agentshouse/mdruntime/entry` fills the same query in your page), `interaction` (the queries its first interaction needs), `title`, `description`, `styles` (release CSS files) and `body`. A body node is text, `{text: v}`, `{markdown: v}` of a document, `{tag, attrs, children}`, `{each: v, as, children}` or `{if: v, then, else}`; a value `v` is a literal, `{param}`, `{at, pointer}` into a query result or `each` item, `{join: [v]}`, `{count: v}` or `{stem: v}`.
+
+On every Entry Page an `img` keeps the `loading` and `fetchpriority` it names and loads lazily where it names no `loading`; a document's images always load lazily. Each takes the box its `width` and `height` name, 16:9 without them, and an `img` whose `src` is relative (`images/hero.webp`) shows that file of your release. House puts each stylesheet into the page itself, its relative `url()`s pointing into your release, so the page draws in your fonts and styles from its first byte. A route that fails starts the App as usual, and the Site document names why.
 
 ```json
 {
   "routes": [
+    { "path": "/" },
+    { "path": "/about" },
     {
       "path": "/posts/:slug",
       "queries": {
@@ -18,6 +26,7 @@ Entry Data Contract, `entry_data` in a Site App’s `app.json`: House serves eac
         }
       },
       "title": { "at": "post", "pointer": "/documents/0/fields/title" },
+      "styles": ["assets/site.css"],
       "body": [{ "markdown": { "at": "post", "pointer": "/documents/0" } }]
     }
   ]

package/guide/sites/first-load.md

@@ -0,0 +1,15 @@
+# A Site's first load
+
+How to build a Site whose first screen reaches a visitor's phone within about a second, and how to see that it does.
+
+A phone on a slow link pays for every byte before the first screen, so what the release puts first decides how soon it shows. Build every Site this way by default:
+
+- **An Entry Page for every entry route.** House draws a route as HTML before the App starts only where the release declares it in `entry_data` ([Entry Data Contract](sites/entry-data-contract)); any other route shows once the App has run. A route with no queries and no parameter names only its `path`, and its Entry Page is the release's own HTML for that path: the entry document for `/`, and `about/index.html` in the release for `/about`. House reads that HTML and never runs it, keeping its text and plain elements and taking its title, description and stylesheets from its head, so prerender each such route's first screen into it at build, its main image a plain `img`, since a `picture`, an `svg` and a script are dropped. A route that reads Rooms or takes a parameter declares its queries and its body. An Entry Page draws in the Site's own fonts, styles and images, so nothing moves when the App takes over.
+- **Images at the size the App draws them**, each with its `width` and `height`: a larger file costs bytes nobody sees, and the box stays still while it loads.
+- **The first image at once**: the first screen's main image names `loading="eager"` and `fetchpriority="high"`, in the release's HTML and in the App, since an Entry image that names no `loading` loads lazily. Every image below the first screen loads lazily.
+- **No entrance animation on the first screen**: draw it in its final place, since content that fades or slides in counts as shown only once it stops.
+- **Heavy libraries after the first draw**, behind a poster: load a 3D scene, a map or a video player with `import()` once the first screen has drawn, and show a still image of it until it runs.
+- **Built minified and split**: minification on, and each route and heavy part a chunk of its own loaded by `import()`, so the first screen loads only its own code.
+- **At most two font families**, the Site's own, their files in the release.
+- **The first view within the bound** the publish warns at. The first view is the entry document, its scripts and stylesheets and what they import statically, compressed as House stores them. A first view past the bound, or no Entry Page for `/`, never stops a publish: its answer and `sites/list` name each in `warnings` by its `code`, `first_view_heavy` with its `bytes` and `bound`, and `entry_page_missing`. Fix them before the next publish.
+- **Read `first_load` in `sites/list` after each publish.** House loads the Site once more, cold, as a phone on a slow link, and answers `{ first_content_ms, largest_content_ms, at }` for the release or publication it serves: `null` before that figure, when that load failed or where the Building times no Site. A figure that grew points at what that release added.

package/guide/sites/functions.md

@@ -0,0 +1,13 @@
+# A Site's function calls
+
+How a Site's page calls a function its App declares and gets its answer, so code that holds a key, such as one opening a checkout, runs on House's servers and never on the page.
+
+- **The call.** `runtime.call('sites/functions/call', { function, input })`, online only, calls any function the App's latest release declares ([App functions](apps/functions)), with `input` any JSON up to <function-input-size>, `null` when left out. It answers `{ kind: 'action', result: { answer } }`, `answer` being the function's return value as JSON, `null` when it returns nothing. Offline it answers `transport-uncertainty` at once and sends nothing later, and a Site House does not serve answers it too.
+- **Open to every visitor.** Anyone at the Site calls any declared function with any input, signed in or not, and no bot check stands before it: check `call.kind` and `call.input` in every function, and look up a price, total or order by its id rather than taking it from the input.
+- **What a function receives.** `export default async (call, house) => {}` receives `{ kind: 'site', id, site, moment, input, rooms, intake_room }`. `kind` is `site`, which no Trigger's event carries, so a function written for a Trigger refuses a visitor; `id` is new for each call; `site` is the Site's address; `moment` is when the call started, which `Date` reads; `input` is the call's input, whole; `rooms` lists under each slot of the release the Room references the Site binds there; and `intake_room` is the Intake Room's reference or `null`.
+- **Its Rooms.** A call reads and writes every Room the Site binds and its Intake Room, with the Site owner's authority and those Rooms' Service keys, and no other Room. It has no Room of its own, so each method names one: `query` one Room in `rooms`, `saveParts(room, parts)` its first argument, `call` and `callExternal` their `room_ref`, and `toMoment` and `toLocal` their `room_ref` ([Times](apps/function-times)). Its writes are the App's, by `App <App> (function <function>)`, and count against the owner's Write limit.
+- **Refused before it runs.** `{ kind: 'rejected', code }` with `not_found` for a function the latest release does not declare, `function_input_too_large`, or `limit_reached` with `limit: 'site_function_calls'` and its `retry_at` once the Site's calls pass their rate, which Full House raises.
+- **Refused after it was taken.** A call runs in its Site owner's run slots, which their Triggers' runs share, at most <function-owner-slots> at once on each server. `function_not_started` says it found no slot within <function-start-wait> and never ran: send it again. `function_failed` with `error` says it ran and failed: its thrown text, `time_cap_reached` at <function-time>, `memory_cap_reached`, `external_call_cap_reached`, `answer_not_json` for an answer JSON cannot hold, or `answer_too_large` past <function-answer-size>. `function_unanswered` says House lost the answer after it may have started, so it may have run: a function that charges or orders names what it writes by an id the page sends, so a second call finds it.
+- **Nothing kept.** House keeps nothing of a call once it has answered but its figure among the App's function runs.
+
+Next: [A Site's payments](sites/payments)

package/guide/sites/payments-stripe-2.md

@@ -0,0 +1,78 @@
+# Payments with Stripe: checkout
+
+The `checkout` function, which opens one Stripe Checkout Session for each order and answers `{ url }`, its page.
+
+`functions/checkout.js`:
+
+```js
+const STRIPE = 'https://api.stripe.com';
+const CURRENCY = 'usd';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const KEY = /^[a-z0-9-]{1,64}$/;
+
+const form = (fields) =>
+  Object.entries(fields)
+    .map(([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(value)}`)
+    .join('&');
+
+export default async (call, house) => {
+  if (call.kind !== 'site') throw new Error('checkout serves a Site');
+  const { order, cart } = call.input ?? {};
+  if (typeof order !== 'string' || !UUID.test(order)) throw new Error('the order is no UUID');
+  const orders = call.intake_room;
+  const path = `orders/${order}.md`;
+  const read = async (room, query) =>
+    (await house.query({ rooms: [room], select: { fields: 'all' }, ...query })).documents;
+  const [held] = await read(orders, { types: ['order'], paths: [path] });
+  if (held !== undefined) return { url: held.fields.checkout_url };
+  if (!Array.isArray(cart) || cart.length === 0 || cart.length > 20)
+    throw new Error('the cart holds 1 to 20 lines');
+  const wanted = cart.map((line) => {
+    const { product, quantity } = line ?? {};
+    if (!KEY.test(String(product)) || !Number.isInteger(quantity) || quantity < 1 || quantity > 99)
+      throw new Error('a line names no product and count');
+    return { path: `products/${product}.md`, quantity };
+  });
+  const products = await read(call.rooms.products[0], {
+    types: ['product'],
+    paths: wanted.map((line) => line.path),
+  });
+  const lines = wanted.map(({ path: at, quantity }) => {
+    const product = products.find((found) => found.path === at);
+    if (product === undefined) throw new Error(`the shop sells nothing at ${at}`);
+    return { name: product.fields.name, price: product.fields.price, quantity };
+  });
+  const session = {
+    mode: 'payment',
+    client_reference_id: order,
+    success_url: `${call.site}/paid/${order}`,
+    cancel_url: `${call.site}/`,
+  };
+  lines.forEach((line, at) => {
+    session[`line_items[${at}][quantity]`] = line.quantity;
+    session[`line_items[${at}][price_data][currency]`] = CURRENCY;
+    session[`line_items[${at}][price_data][unit_amount]`] = line.price;
+    session[`line_items[${at}][price_data][product_data][name]`] = line.name;
+  });
+  const answer = await house.callExternal({
+    url: `${STRIPE}/v1/checkout/sessions`,
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: form(session),
+    room_ref: orders,
+  });
+  if (answer.status !== 200) throw new Error(`Stripe answered ${answer.status}`);
+  const { url } = JSON.parse(answer.body);
+  const items = lines.map((line) => `${line.quantity} × ${line.name}`).join(', ');
+  const total = lines.reduce((sum, line) => sum + line.price * line.quantity, 0);
+  const fields = { state: 'pending', items, total, checkout_url: url };
+  const creation = { type: 'order', fields, sections: {} };
+  const saved = await house.saveParts(orders, [{ path, parts: { creation } }]);
+  if (saved.outcome !== 'saved') throw new Error(`the order was not saved: ${saved.code}`);
+  return { url };
+};
+```
+
+A call for an order that exists answers its address. Otherwise `checkout` opens a session and writes the order with its address only after, so every order holds the checkout that charges what it says. A call that Stripe refused, or whose order was not written, leaves no order and answers no address, and the visitor's next call prices the cart again and opens a session of its own. The call sends no `Idempotency-Key`: a session no order holds is never shown and lapses unpaid, and a key would hold a repriced retry to its first lines. A visitor sees Stripe's refusal as its status alone. The secret key goes with the call because it names the Intake Room.
+
+Next: [Payments with Stripe: paid and order](sites/payments-stripe-3)

package/guide/sites/payments-stripe-3.md

@@ -0,0 +1,67 @@
+# Payments with Stripe: paid and order
+
+The `paid` function, which marks an order paid once Stripe's signed webhook says so, and the `order` function, which answers an order's state.
+
+`functions/paid.js`, run by the Trigger on each delivery. Stripe signs `t`, a dot and the body with the endpoint's secret, and its `Stripe-Signature` header carries `t` and one `v1` signature or more:
+
+```js
+const STRIPE = 'https://api.stripe.com';
+const TOLERANCE_SECONDS = 300;
+
+export default async (event, house) => {
+  if (event.kind !== 'items') throw new Error('paid runs on a delivery');
+  const header = [event.item.headers['stripe-signature'] ?? ''].flat().join(',');
+  const pairs = header.split(',').map((pair) => pair.split('='));
+  const [, stamp = ''] = pairs.find(([name]) => name === 't') ?? [];
+  if (!/^\d+$/.test(stamp) || Math.abs(Date.now() / 1000 - Number(stamp)) > TOLERANCE_SECONDS)
+    throw new Error('the delivery was not signed in the last five minutes');
+  const text = `${stamp}.${event.item.body}`;
+  let matched = false;
+  for (const [name, signature] of pairs) {
+    if (name !== 'v1' || matched) continue;
+    const checked = await house.call('service-keys/signatures/check', {
+      room_ref: event.room,
+      origin: STRIPE,
+      text,
+      signature,
+    });
+    if (checked.kind !== 'action') throw new Error(`the check was refused: ${checked.code}`);
+    matched = checked.result.matched;
+  }
+  if (!matched) throw new Error('the signature does not match');
+  const session = JSON.parse(event.item.body).data.object;
+  if (session.payment_status !== 'paid') return;
+  const path = `orders/${session.client_reference_id}.md`;
+  const query = { types: ['order'], paths: [path], select: { fields: ['/state'] } };
+  const [order] = (await house.query(query)).documents;
+  if (order === undefined) throw new Error(`no order at ${path}`);
+  if (order.fields.state === 'paid') return;
+  const fields = { state: { value: 'paid', base: { value: 'pending' } } };
+  const email = session.customer_details?.email;
+  if (typeof email === 'string') fields.email = { value: email, base: null };
+  const saved = await house.saveParts(event.room, [{ path, parts: { fields } }]);
+  if (saved.outcome !== 'saved') throw new Error(`the order was not saved: ${saved.code}`);
+};
+```
+
+`Date` reads the moment House stored the delivery, and a `base` of `null` sets a field the order lacks. A session paid by a method that settles later arrives `unpaid` with `checkout.session.completed` and marks nothing until `checkout.session.async_payment_succeeded`.
+
+`functions/order.js`, which answers `pending`, `paid`, or `null` for an id that names no order:
+
+```js
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+export default async (call, house) => {
+  const order = call.input?.order;
+  if (call.kind !== 'site' || typeof order !== 'string' || !UUID.test(order)) return null;
+  const { documents } = await house.query({
+    rooms: [call.intake_room],
+    types: ['order'],
+    paths: [`orders/${order}.md`],
+    select: { fields: ['/state'] },
+  });
+  return documents[0]?.fields.state ?? null;
+};
+```
+
+Next: [Payments with Stripe: the Site's page](sites/payments-stripe-4)

package/guide/sites/payments-stripe-4.md

@@ -0,0 +1,96 @@
+# Payments with Stripe: the Site's page
+
+The Site's page, which sells the products, calls `checkout` and opens Stripe's page, and at `/paid/<order>`, where Stripe sends the buyer back, calls `order`.
+
+`index.html`:
+
+```html
+<!doctype html>
+<html lang="en">
+  <title>Shop</title>
+  <main></main>
+  <script type="module" src="main.js"></script>
+</html>
+```
+
+`src/main.ts`, which `npm run build` bundles into `main.js` as [Start an App](apps/start) says:
+
+```ts
+import { houseBridge, type HouseParams } from '@agentshouse/app-bridge';
+
+const bridge = houseBridge();
+const runtime = await bridge.runtime;
+const main = document.querySelector('main')!;
+const cart: Record<string, number> = {};
+let order: string | null = null;
+
+async function called(
+  name: string,
+  input: HouseParams<'sites/functions/call'>['input'],
+): Promise<unknown> {
+  const answered = await runtime.call('sites/functions/call', { function: name, input });
+  if (answered.kind !== 'action') throw new Error(answered.code);
+  return answered.result.answer;
+}
+
+async function shop(): Promise<void> {
+  const products = await runtime.observe('query', {
+    types: ['product'],
+    select: { fields: ['/name', '/price'] },
+    orderBy: [{ by: { field: '/name' } }],
+  });
+  const pay = Object.assign(document.createElement('a'), { textContent: 'Pay with Stripe' });
+  const note = document.createElement('p');
+  const button = Object.assign(document.createElement('button'), { textContent: 'Check out' });
+  pay.hidden = true;
+  button.onclick = async () => {
+    order ??= crypto.randomUUID();
+    const lines = Object.entries(cart).filter(([, quantity]) => quantity > 0);
+    try {
+      const answer = await called('checkout', {
+        order,
+        cart: lines.map(([product, quantity]) => ({ product, quantity })),
+      });
+      pay.href = (answer as { url: string }).url;
+      pay.hidden = false;
+      note.textContent = '';
+    } catch (error) {
+      note.textContent = `Not opened: ${(error as Error).message}.`;
+    }
+  };
+  const draw = (answer: ReturnType<typeof products.current>) => {
+    if ('pending' in answer) return;
+    const rows = answer.documents.map((product) => {
+      const key = product.path.slice('products/'.length, -'.md'.length);
+      const price = (Number(product.fields!.price) / 100).toFixed(2);
+      const count = Object.assign(document.createElement('input'), {
+        type: 'number',
+        min: '0',
+        max: '99',
+        value: String(cart[key] ?? 0),
+      });
+      count.onchange = () => {
+        cart[key] = Number(count.value);
+        order = null;
+        pay.hidden = true;
+      };
+      const row = document.createElement('label');
+      row.append(`${String(product.fields!.name)}, $${price} `, count);
+      return row;
+    });
+    main.replaceChildren(...rows, button, pay, note);
+  };
+  draw(products.current());
+  products.subscribe(draw);
+}
+
+async function paid(id: string): Promise<void> {
+  const state = await called('order', { order: id }).catch(() => null);
+  main.replaceChildren(state === 'paid' ? 'Paid, thank you.' : 'Not paid yet: reload soon.');
+}
+
+const back = /^\/paid\/([0-9a-f-]{36})$/.exec(bridge.address() ?? '');
+await (back === null ? shop() : paid(back[1]!));
+```
+
+A changed cart draws a new order, since an order's checkout holds the lines it was opened with. Stripe's page is another origin, so its link opens in a new tab.

package/guide/sites/payments-stripe.md

@@ -0,0 +1,63 @@
+# Payments with Stripe
+
+How a Site takes card payments with Stripe end to end: the App, its two Rooms, the keys, the webhook and the Trigger here, and the code over the next pages.
+
+It builds [A Site's payments](sites/payments). Build and try it in a Stripe sandbox, whose secret key starts `sk_test_` and whose test cards, such as `4242 4242 4242 4242`, charge nothing.
+
+`schema.yaml`, also written into both Rooms' `settings/schema.yaml`; a `price` and a `total` are in cents:
+
+```yaml
+product:
+  properties:
+    name: { type: string }
+    price: { type: integer }
+  required: [name, price]
+order:
+  properties:
+    state: { type: string, enum: [pending, paid] }
+    items: { type: string }
+    total: { type: integer }
+    checkout_url: { type: string }
+    email: { type: string }
+  required: [state, items, total]
+```
+
+`app.json`:
+
+```json
+{
+  "entry": "index.html",
+  "external_origins": ["https://api.stripe.com"],
+  "room_slots": [
+    { "name": "products", "access": "read", "types": ["product"] },
+    { "name": "orders", "access": "write", "types": ["order"] }
+  ],
+  "functions": [
+    { "name": "checkout", "entry": "functions/checkout.js" },
+    { "name": "paid", "entry": "functions/paid.js" },
+    { "name": "order", "entry": "functions/order.js" }
+  ]
+}
+```
+
+- **Products.** One Room holds each `product` at `products/<key>.md`, its `# Name` line over a `- **price**: 1200` line. The Site binds it in `products` with `sites/bindings/set` and shows it with `sites/publish`.
+- **Orders.** Another Room is the Site's Intake Room (`sites/intake-room/set`), bound to the App in `orders` with `apps/bindings/set`. The Site binds no Room in `orders`.
+- **The keys.** Your User enters two keys in the Intake Room for `https://api.stripe.com`: Stripe's secret key as `bearer`, and the webhook endpoint's signing secret, `whsec_` and the rest, as `signing`.
+- **The webhook.** `capture/push-addresses/create` in the Intake Room with `event_id` `{"json": "/id"}`, where Stripe carries its event id. In Stripe your User adds a webhook endpoint at the push address's `address` that sends `checkout.session.completed` and `checkout.session.async_payment_succeeded`, then copies its signing secret into the key above.
+- **The Trigger.** `triggers/create` in the Intake Room with one action, `{"kind": "function", "app": "<App>", "function": "paid", "enabled": true}`, and this `condition`:
+
+```json
+{
+  "on": "items",
+  "query": {
+    "where": {
+      "/address": "<push address>",
+      "/json/type": {
+        "$in": ["checkout.session.completed", "checkout.session.async_payment_succeeded"]
+      }
+    }
+  }
+}
+```
+
+Next: [Payments with Stripe: checkout](sites/payments-stripe-2)

package/guide/sites/payments.md

@@ -0,0 +1,13 @@
+# A Site's payments
+
+How a Site takes payments into its owner's own account at a payment provider, with House never holding the money.
+
+House has no payments of its own: a Site's App takes them with [its function calls](sites/functions), a Room's Service keys, a push address and a Trigger, the same way for any provider that fits. [Payments with Stripe](sites/payments-stripe) does it end to end.
+
+- **Where things live.** The Site's Published Rooms hold what it sells and its prices. Its Intake Room holds its orders and buyers, the provider's keys, the push address and its Trigger: no visitor reads it, and a Site's call reaches it. Bind it to the App in a write slot with `apps/bindings/set`, so the Trigger runs the App's function there and the App shows its owner the orders at its App address; the Site binds no Room in that slot.
+- **The keys.** Your User enters both in the Intake Room on the House page for the provider's API origin, which the release's `external_origins` lists: the API key in the form the provider takes it, such as `bearer`, and the webhook's signing secret as `signing`. A function sends the first with `callExternal` and checks a delivery against the second with `service-keys/signatures/check`, and never sees either.
+- **One checkout per order.** The page draws the order's id with `crypto.randomUUID()`, keeps it, and calls `checkout` with it and the cart. `checkout` refuses an id that is no UUID and answers the checkout's address for an order that exists. For one that does not, it prices the cart from the Published Rooms and never from the input, opens the provider's checkout with the order's id as its reference for the order, then writes the order `pending` with that address and answers the address once the order is written. So each order holds the checkout that charges what it says, and a checkout that failed leaves no order, so the next call prices the cart again and opens a checkout of its own. The order's id is never the provider's idempotency key, which would hold that call to the first call's lines. The page opens the address.
+- **Paid.** The provider's webhook reaches the Intake Room's push address (`capture/push-addresses/create`), whose `event_id` names where the provider carries its event id, so a resent delivery writes nothing, and whose `reply`, `{ body, type }`, names a fixed answer every `200` carries, for a provider that resends until it reads its own answer. A Trigger on that address's items runs `paid`, which checks the delivery's signature and throws when it does not match, so the run fails and the owner sees it in `triggers/fired/list`. When it matches, `paid` marks the order paid, and a delivery for a paid order changes nothing.
+- **Read.** The page the provider sends the buyer back to calls `order` with the id it kept, and `order` answers only the order's state, since the id is the buyer's only key to it.
+- **Which provider fits.** One whose API takes a key in a form the House page offers and whose webhook is a POST it counts delivered on any `2xx`, which the push address answers once it stored the delivery, with its `reply` when the provider waits for a fixed answer of its own. One that signs its webhook with HMAC-SHA256 is checked as above. One that signs nothing is checked by reading the payment back through its API with the key, and its `paid` refuses a payment that read does not show paid. One whose API needs each request signed, or whose webhook waits for an answer that depends on the delivery or is signed, cannot be used.
+- **The money.** It goes from the buyer to the owner's account at the provider. House holds, charges and settles none of it, and refunds, payouts, receipts and taxes stay between the owner and the provider.

package/guide/sites/runtime.md

@@ -1,6 +1,6 @@
 # The App runtime on a Site
 
-What the App runtime does differently on a Site's page. Everything else is as in an App, [Local first](apps/local-first) included: House serves a Site's first screen as HTML from its [Entry Data Contract](sites/entry-data-contract) before the App starts, so a Site's page draws no loading state either.
+What the App runtime does differently on a Site's page. Everything else is as in an App, [Local first](apps/local-first) included, so a Site's page draws no loading state either. A route has an Entry Page, House's HTML of it before the App starts, only where the release declares one in its [Entry Data Contract](sites/entry-data-contract).
 
 A History revision or a Document's `change` written by a Site gives its `author` as `{ kind: 'site', id, name }`. `observe('member')` answers `null` on a Site, and a Document's `change` is `null` there, since the Provider delivers no time.
 
@@ -9,7 +9,7 @@ and its Pending Change shows in every query and across reloads until the browser
 cleared. It is never sent: `observe('queue', room)` shows it `local`, Sync Status never waits on
 it, and once the Room no longer lets it apply it leaves the queue and returns no Room Draft.
 
-A Site's page fills its [Entry Data Contract](sites/entry-data-contract)'s
+Where House served a route's Entry Page, the page fills that route's
 `{"$param": name}` arguments with `boundQuery` from `@agentshouse/mdruntime/entry`, as
 House did for its HTML. While the Site prepares, a query a route's `interaction` names
 answers from the entry's result when the page observes that descriptor, and every other

package/guide/skills/build-app.md

@@ -11,9 +11,20 @@ Build the App a prototype made, once the User has decided on its design, and pub
 
 Read the map `prototype-app` opened for this App. Start only when its design-decision ticket is resolved with the User's decision. Until then do nothing else: tell the User their decision on the prototype's design is missing, give them the prototype's address, and stop. Without such a map there is no decision: say so and offer [`prototype-app`](skills/prototype-app).
 
+## Design
+
+Claim the build ticket. Read [Design an App](apps/design) and each page it links, then draft from the User's decision:
+
+- the App's types and fields, as its `schema.yaml` will declare them;
+- each piece of work no page does, the function that does it and the Trigger that starts it;
+- for each design on [Designs that load House](apps/design-load) the App comes near, how it keeps that load down;
+- its top colours, light and dark, from the decided prototype, and its icon.
+
+The draft is no document of its own: the grilling takes it in.
+
 ## Build
 
-Claim the build ticket. Starting from the User's decision, run `grill-with-docs`, then `to-spec`, then `implement`. Keep what they write where the Owner rules, `/rooms/private/owner-rules.md`, say. Each Skill named here is also a Command of its name, or the Guide page it links, for a client that has not installed it.
+Run `grill-with-docs` on that draft, then `to-spec`, then `to-tickets`, then `implement` for each ticket in order. Keep what they write in the map's Room, where the Owner rules, `/rooms/private/owner-rules.md`, say, and name that Room in the App's README as the Room where the App is developed. Each Skill named here is also a Command of its name, or the Guide page it links, for a client that has not installed it.
 
 ## Publish into the same App
 

package/guide/skills/prototype-app.md

@@ -11,7 +11,7 @@ Keep everything where the Owner rules, `/rooms/private/owner-rules.md`, say. Eac
 
 ## 1. Open the map
 
-In the Room the work belongs to, the one the User names or else one you make with `rooms/create`, chart a map as `wayfinder` does, but skip its grilling: the way is set here.
+In the Room where the App is developed ([Design an App](apps/design)), the one the User names or else one you make with `rooms/create`, chart a map as `wayfinder` does, but skip its grilling: the way is set here.
 
 - **Destination:** the App the User asked for, built and published.
 - **Notes:** this map's tickets do the work they name; the App's address and `a_` reference once the prototype is published.
@@ -24,6 +24,8 @@ In the Room the work belongs to, the one the User names or else one you make wit
 
 Claim the first ticket. Build three variants as [Build an App](apps/build) says, each a distinct visual direction (type, colour, layout, tone), not three shades of one. Each draws every main page with real-looking content, and a switcher on the page moves between them. Build only pages, their look and their flow: no tests, no data model, no reviews. Before publishing, look at each variant at phone and desktop width and redo any that looks generic or broken.
 
+Write the App's first screen as static HTML in its entry document, which its script takes over once it runs, so the screen shows before any script has loaded; every release keeps it so.
+
 Publish it as a new App, which creates it:
 
 - where you run Git, with `npm run publish -- --name "<display name>"`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/skills",
-  "version": "0.1.0-c221fe4e31976",
+  "version": "0.1.0-c22b29c83d792",
   "description": "The upstream Skills agents.house serves its agents, verbatim, and the texts it writes for them: the Guide, its own Skills among the pages, and the Agent instructions",
   "license": "MIT",
   "type": "module",