@agentshouse/skills 0.1.0-c2653a0a4ef70 → 0.1.0-c279efd7eb4df

package/agent-instructions.json

@@ -4,7 +4,7 @@
     "Work with House through the `house` CLI, `house <tool> '<arguments as JSON>'`: `house --help` lists the Tools and `house help <tool>` names a Tool's arguments."
   ],
   "routing": [
-    "Read with `shell` and `inspect`. Write with `files_batch` and `records_append`.",
+    "Read with `shell` and `inspect`. Write with `files_batch`; `records_append` adds a record from one of your Sources.",
     "For anything else, `find_command`, then `run_command`.",
     "Optional per-Room instructions: `/rooms/private/rooms/<handle>/AGENTS.md`."
   ],

package/guide/apps/build.md

@@ -2,7 +2,7 @@
 
 How to build an App over your User's Rooms and publish it, one page per step.
 
-An App is a web page over your User's Rooms, for your User and whom they share it with (`shares/create`). House serves the built files and gives the page the App runtime, which holds every bound Room in the browser and syncs it with House. There is no server, backend or House API of yours to call.
+An App is a web page over your User's Rooms, for your User and whom they share it with (`shares/create`). House serves the built files and gives the page the App runtime, which holds every bound Room but a Search-level one in the browser and syncs it with House. There is no server, backend or House API of yours to call.
 
 - [Design an App](apps/design)
 - [Start an App](apps/start)

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
@@ -20,17 +21,17 @@ Or mount it as the Chat button, which takes no element:
 `const button = await houseBridge.chat.mountButton(options)` draws House's dot at the
 window's bottom-right corner, which counts what asks the User or, while nothing does, the chats
 that replied since the User opened them, and breathes while a turn runs; pressing it opens the
-Chat in a sheet above the page, and pressing it again hides it. With `agent` among the options
+Chat in a sheet above the page, and a second press hides it. With `agent` among the options
 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.
+earlier visit, and later presses reopen the chat it last showed. 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
+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;
 `button.update(options)` and `button.unmount()` work as for a page, with `onOpen` and
-`onLink`. To open on text written in, write it as the chat's draft through the runtime's
+`onLink`, though a Room document's link opens House in a new tab with that chat. To open on text written in, write it as the chat's draft through the runtime's
 `chatDraft` first, keyed `new:<agent>` for a new chat. In the sheet the input's + holds This
 page, which attaches the page's Page metadata to one message: a new chat's first message starts
 with it ticked. Mount one button per page.
@@ -42,9 +43,10 @@ Theme its own styles with CSS custom properties on the element or an ancestor:
 `--chat-accent`, `--chat-line`, `--chat-attention`, `--chat-danger`, `--chat-font`,
 `--chat-font-mono`, `--chat-font-size`, `--chat-radius` and `--chat-density` (a factor for
 spacing); an unset one keeps House's light or dark look. For the Chat button, which takes no
-element, set them on the document's root element. Its dot is House's and takes none of them.
+element, set them on the document's root element. Its dot keeps House's colours and type, and
+stays level with the sheet's input.
 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/content-safety.md

@@ -16,4 +16,6 @@ from a 360 pixel wide viewport to a desktop.
 Its strings are English only, dates and numbers follow the browser locale, and content is
 never translated. Light and dark themes come from CSS custom properties, defaulting to the
 browser's preference and respecting an App's override. What an agent adds carries none of
-these promises by itself. Data lives only in the App Creator's browser and the Provider.
+these promises by itself. The App keeps no data of its own anywhere: its data lives in
+its Rooms, at the Provider and on every device that holds them, and the
+App's code sends it out only to the external origins its manifest declares.

package/guide/apps/design-functions.md

@@ -5,6 +5,6 @@ Which part of House does each kind of an App's work, and what each run costs.
 - **The page** reads and writes the bound Rooms on the device, offline too, and runs only while someone has it open ([Local first](apps/local-first)).
 - **An App function** runs on House's servers when a Trigger of its Room fires, with no page open and no model. It reads and writes that Room and calls the services `external_origins` lists, within <function-time> and <function-memory> a run. It does what a script can: computing, filing, copying, counting, scheduling, calling a service ([App functions](apps/functions)).
 - **An Environment function** is a script your User kept for one of their computers, which Kit runs there as them. It does work that needs that computer, its files or its logins. A Trigger of their Private Room, their Run now or `environments/functions/run` starts one; a Trigger of any other Room never does ([wizard](skills/wizard)).
-- **An Agent function** starts a conversation of one of your User's Agents, which reads, judges and writes in minutes rather than milliseconds. Every run spends your User's own provider budget, and nothing bounds how many a Room's Triggers start. It does what needs judgment: reading a message, answering it, deciding what a document means ([Agent function](reference/agent-function)).
+- **An Agent function** starts a conversation of one of your User's Agents, which reads, judges and writes in minutes rather than milliseconds. Every run spends your User's own provider budget, and House sets no allowance on these runs: one Trigger acts on at most <trigger-events-per-hour> Events in a UTC hour, so a Room's Triggers together can still start many. It does what needs judgment: reading a message, answering it, deciding what a document means ([Agent function](reference/agent-function)).
 - **A job that needs judgment in one step** splits: an App function does the rest, and an Agent function only that step, writing its answer into the Room, where a Trigger hands it on to the App function ([Agent function](reference/agent-function)).
-- **With no page open**, work happens only through a Trigger whose action notifies someone or runs one of these ([Triggers](reference/triggers)).
+- **With no page open**, nothing of the App runs by itself: a Trigger whose action notifies someone or runs one of these starts its work ([Triggers](reference/triggers)).

package/guide/apps/design-look.md

@@ -6,6 +6,6 @@ What House draws around an App's page, and what the App sets for its look.
 - **The Chat**, where the page mounts it, draws in the App's frame: the Chat button's dot in House's look, and the Chat in its own, which the `--chat-*` properties theme ([The Chat](apps/chat)).
 - **The design system's tokens**: mdui's `style.css` holds House's design tokens as CSS custom properties, light and dark: its greys, type sizes, spacing, radii and motion. An App built on them looks like House; changing them gives it a look of its own. The design system itself is not published, so mdui's tokens are how an App takes it.
 - **Light and dark**: House's screens around the page, such as its wait until the page shows its place, follow the device's light or dark setting, as `prefers-color-scheme` does.
-- **The top colour**: declare the page's top colour as `theme_colour` in `app.json`, and `theme_colour_dark` where the dark one differs ([App manifest](reference/app-manifest)). An installed App's title bar and a phone's top strip take it, and House's white or near-black ground without it.
+- **The top colour**: declare the page's top colour as `theme_colour` in `app.json`, and `theme_colour_dark` where the dark one differs ([App manifest](reference/app-manifest)). An installed App's title bar and a phone's top strip take it, and House's white or near-black ground without it. A page with its own light and dark switch calls `bridge.setTab({ scheme })` with `'light'` or `'dark'` when it shows one over the device's setting, and `null` when it follows the device, so they take that scheme's colour.
 - **The icon** is the owner's setting, never the release's: one image in the browser tab, the panel and on a home screen. It is the App cube in the App's colour until one is set, then a generated one from one to four colours or the owner's own square PNG or SVG, through `apps/tab-icon/set`; `bridge.setTab({ title, icon })` changes the open tab's title and icon until the next load.
 - **No focus mark**: House's own screens draw none, and [An App's page](apps/page) says how a page removes the browser's ring.

package/guide/apps/local-first.md

@@ -3,14 +3,14 @@
 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, 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.
+- Draw from `observe` at once; an observation hears each later change by itself, so never poll, refetch or subscribe to House. 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, 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.
+- Offline, all of this works for held Rooms 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 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)).

package/guide/apps/local-query.md

@@ -7,9 +7,9 @@ hears it again only when it changes, keeping every unchanged Document the same o
 a component can tell what changed by identity. `{ documents, coverage }` or `{ groups,
 coverage }` is complete for the Rooms its `coverage` names, and `{ pending }` names each
 Room not yet acquired, prepared or unlocked, `[{ room, awaits }]`: never read it as empty,
-draw it as loading and observe the query to hear the complete answer. A query is data:
+draw them absent and observe the query to hear the complete answer. A query is data:
 
-- **Filter.** `rooms` names Room locators and defaults to every Room. `types` names MD
+- **Filter.** `rooms` names Room locators and defaults to every bound Room but a Search-level or locked one, which `pending` omits. `types` names MD
   Types, and `any` names untyped Markdown Documents. `pathPrefix` is a directory: `notes`
   keeps `notes/a.md` and not `notes2/a.md`; `outside` names directories whose contents stay
   out, `['house']` leaving `house/` out; `folder` keeps only what lies directly in it.

package/guide/apps/page.md

@@ -10,5 +10,4 @@ What an App's page draws and how it behaves in the browser.
 - An empty list says what it will hold and invites the first document.
 - Long names truncate with an ellipsis and show in full on hover.
 - The element is the link: a row, card or name opens its item; no "Open" buttons.
-- Offer installation yourself: `bridge.install()` from a click starts the install or shows the browser's prompt, or answers `manual` where you show how.
 - Offer a way out where your User expects one: `bridge.ceremony('/sign-out')` signs them out of House and opens sign-in.

package/guide/index.md

@@ -4,6 +4,8 @@ Where House's guides and formats start: `guide/open` opens a page by its `path`
 
 House keeps Markdown files in Rooms, which your User shares with other people and their agents.
 
+With the Kit, each Room your Environment keeps is also a Local copy: a Git repository at `local-copies/rooms/<room_ref>` in its workspace, `~/.agents/house` unless moved. `house fetch` records House's changes on `refs/house/received` in each, and `house push`, run in one, sends its commits.
+
 - `apps/`, building an App over your User's Rooms: [Design an App](apps/design) first, then [Build an App](apps/build), and the functions House runs for it when a Trigger fires: [App functions](apps/functions).
 - `reference/`, the formats House reads: [Access level](reference/access-level), [App manifest](reference/app-manifest), [Schema](reference/schema) and [Triggers](reference/triggers).
 - `agent-functions/`, the Agent function an Agent takes a plan's tickets by, written for the plan's Room and naming that Agent as [Agent function](reference/agent-function) says: [Work on ticket](agent-functions/work-on-ticket).

package/guide/reference/access-level.md

@@ -2,7 +2,7 @@
 
 How much of a Room a grant or a Share lets its holder do with its text, and where.
 
-Access level, `level` on a Room grant or a Share’s Room item, each level including the one before it: `search`, the Search level, reaches the Room through `shell` and `inspect` alone, each reply at most <mcp-read-size> of the Room’s text, with no copy anywhere; `open`, the Open level, also opens the Room in browser Apps while the browser is online, and acts as `search` everywhere else; `keep`, the Keep level, also copies the Room to the devices that keep it, offline included, and is the one `export` needs. Apps need `open` or `keep`.
+Access level, `level` on a Room grant or a Share’s Room item, each level including the one before it: `search`, the Search level, reaches the Room through `shell` and `inspect`, each reply at most <mcp-read-size> of the Room’s text, and for App code only through the pages of rows [`queryHouse`](apps/query-house) asks House for, which no agent reaches, with no copy anywhere; `open`, the Open level, also opens the Room in browser Apps while the browser is online, and acts as `search` everywhere else; `keep`, the Keep level, also copies the Room to the devices that keep it, offline included, and is the one `export` needs. An App that reads the Room on the device, through `query` and `observe`, needs `open` or `keep`.
 
 ```json
 { "room_ref": "r_ab12.1", "level": "open", "operations": ["write"] }

package/guide/reference/schema.md

@@ -2,7 +2,7 @@
 
 How a Room's `settings/schema.yaml` declares its document types.
 
-Schema, `/rooms/<room>/settings/schema.yaml`: one JSON Schema in YAML. Each top-level key is an MD type holding the schema of its documents' values; `$defs` holds shapes reused through `$ref: '#/$defs/<name>'`. An object setting neither `additionalProperties` nor `unevaluatedProperties` refuses other keys. House adds `reference` on a string at any depth, naming the types, or `attachment`, its value links to, and `cross_room: true` beside it, letting that be another Room's document of those types; a link or reference written as its `/rooms/<room>/` path is stored relative to the document; `title` on a field, the label a document shows for it, its key when it has none; `contentMediaType: text/markdown` on a string, Markdown text under its own heading; and `member_document: true` on one type, whose documents name their member with `member`, a User Identifier from `rooms/members/list`. On a type, `create_roles` lists the Schema Roles that may create its documents and `delete_roles` those that may delete them, and changing a document's `type` needs both; on a field of a type's own `properties`, `change_roles` lists those that may change it, `initial_roles` those that may set it on a new document, and `transitions` the `{from, to, roles}` changes it may make, `null` standing for absent; `owner` and `member` are built in, `[]` allows nobody, and only someone who manages the Room's access changes them. `files_batch` creates or replaces the whole text, and may rewrite the documents a change breaks in the same call.
+Schema, `/rooms/<room>/settings/schema.yaml`: one JSON Schema in YAML. Each top-level key is an MD type holding the schema of its documents' values; `$defs` holds shapes reused through `$ref: '#/$defs/<name>'`. An object setting neither `additionalProperties` nor `unevaluatedProperties` refuses other keys. House adds `reference` on a string at any depth, naming the types, or `attachment`, its value links to, and `cross_room: true` beside it, letting that be another Room's document of those types; a link or reference written as its `/rooms/<room>/` path is stored relative to the document; `title` on a field, the label a document shows for it, its key when it has none; `contentMediaType: text/markdown` on a string, Markdown text under its own heading; and `member_document: true` on one type, whose documents name their member with `member`, a User Identifier from `rooms/members/list`. On a type, `create_roles` lists the Schema Roles that may create its documents and `delete_roles` those that may delete them, and changing a document's `type` needs both; on a field of a type's own `properties`, `change_roles` lists those that may change it, `initial_roles` those that may set it on a new document, and `transitions` the `{from, to, roles}` changes it may make, `null` standing for absent; `owner` and `member` are built in, `[]` allows nobody, and only someone who manages the Room's access changes them. `files_batch` creates, patches or replaces it, House checks the whole text it leaves, and the same call may rewrite the documents a change breaks.
 
 A Room in a Space shows its Space's schema at that path and keeps none of its own: its owner and a member who can write in the Space change it there, a rule keyword only someone who manages the Space, in an edit holding that change alone, checked against every document of every Room of the Space; a change that would break any document is refused naming it, so change that document in its own edit first. A Room taken out of its Space keeps the last version as its own. Every Room also knows the [Inbox types](reference/inbox-types) and the [Wayfinding types](reference/wayfinding-types) without declaring them.
 

package/guide/sites/build.md

@@ -13,9 +13,9 @@ Build it as [Build an App](apps/build) says, with what follows. Anything private
 - 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).
-- `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.
+- 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 `google_analytics_id` and the title and description search engines show. With an ID, 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 `'decline'`, and keep a way on every page to decline later, which reloads the page unmeasured. A counter of its own: [A Site's own counter](sites/counter).
+- A Site moved from another builder keeps its old links with `redirects` in `app.json`, `[{ "from": "/old", "to": "/new" }]`: each old path, as a browser asks for it, answers a permanent redirect to its new path, query included. No old path is under `/_house/`, a root file such as `/robots.txt` or an entry route's; none repeats or is a new path. A document published at an old path takes it over.
 - See it yourself: open its url, which needs no sign-in.
 
 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/counter.md

@@ -0,0 +1,26 @@
+# A Site's own counter
+
+How a Site counts its visitors in a counter of its own, such as a web analytics counter or an ad pixel, beside `google_analytics_id` or instead of it.
+
+- **Its script in the release.** A page runs only its release's scripts, so copy the counter's script into your source and bundle it, rather than load it from the counter's server as its snippet does. A script the counter loads from there later is refused too.
+- **Its origins.** List every https origin the counter sends to in `app.json`'s `external_origins`. The browser console names each origin the page refused.
+- **The page's address and referrer.** Your page runs in a frame of the Site's page at the Site's own origin, so the counter sees the frame's address and no referrer of the visitor's. Turn off its own page view and send each through `countPages` below, which gives the page's address and where the visitor came from: first the Site page's referrer, then the page they left.
+- **Consent, as for `google_analytics_id`.** Start the counter only after the visitor accepts, never after Decline. Ask on the Site unless their answer is kept. While `bridge.onStatus` reports `analytics.measures`, the answer is `analytics.choice`, kept with `bridge.analyticsConsent`, so one banner asks once for both; otherwise keep it in local storage, and a browser that keeps none is never counted. Keep a way on every page to decline later, which reloads the page without the counter: `bridge.analyticsConsent('decline')` does that while `analytics.measures` holds, `parent.location.reload()` otherwise.
+- **Hits arrive.** Publish, open the Site's url in a browser, accept and open a second page: the network log shows a request to the counter for each page, answered, and the counter's real-time report, which your User reads, shows both pages at the Site's address, the second with the first as its referrer.
+
+`src/counter.ts`, which your entry script calls once the visitor accepted, with the counter's call that sends one page view:
+
+```ts
+import { houseBridge } from '@agentshouse/app-bridge';
+
+export function countPages(pageView: (page: string, referrer: string) => void): void {
+  let referrer = parent.document.referrer;
+  let counted = '';
+  houseBridge().onAddress((address) => {
+    const page = location.origin + address;
+    if (page === counted) return;
+    pageView(page, referrer);
+    referrer = counted = page;
+  });
+}
+```

package/guide/sites/first-load.md

@@ -13,3 +13,4 @@ A phone on a slow link pays for every byte before the first screen, so what the
 - **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.
+- **A common Site from a Site Template**, built this way, where `templates/list` answers them: `site-landing`, one page whose form sends each lead as a Submission; `site-services`, a page that lists each document of its Room's `services/` folder as one service; and `site-shop`, a shop on the recipe of [Payments with Stripe](sites/payments-stripe). Make the Site with one `templates/use` of it, at the address `templates/list` answers, with a `site_name` and a `room_name`: the Site gets its own App and a new Room holding the Template's schema and Starter content, keeps no link to the Template, and you change its App as any other. It binds that Room in every slot but one that declares `intake: true`, which publishes it. `site-landing`'s one slot declares it, so the Room is the Site's Intake Room and none is published: turn on Notify me with `sites/notifications/set` and each lead reaches your User on the channels they chose. `site-shop`'s `orders` slot declares it: set up its Intake Room as that recipe says.

package/guide/sites/functions.md

@@ -9,3 +9,5 @@ How a Site's page calls a function its App declares and gets its answer, so code
 - **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,68 @@
+# 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';
+// Stripe's libraries refuse a signature over five minutes old, which stops a replayed delivery
+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

@@ -2,6 +2,13 @@
 
 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 Room the Site binds for queries only never reaches a visitor's browser: `rooms` lists it
+with `queriesOnly: true` and nothing held, and its rows come a page at a time through
+`queryHouse`, as [House query rules](apps/query-house) say, except that a query of more than
+about 9,000 bytes, too long for the Site's address, answers `query_too_large` with no `cap`
+before it is sent. Every visitor asking the same query gets the same page, which the edge keeps
+for a few minutes, so a change to the Room shows within them.
+
 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.
 
 On a Site, every Save stays in the visitor's browser: write grants and revisions do not refuse it,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/skills",
-  "version": "0.1.0-c2653a0a4ef70",
+  "version": "0.1.0-c279efd7eb4df",
   "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",