@agentshouse/skills 0.1.0-ce8a631ec1d4b → 0.1.0-cf4fc47c6da39

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 `info`. 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,8 +2,9 @@
 
 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)
 - [An App's data](apps/data)
 - [Local first](apps/local-first)

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/data.md

@@ -6,7 +6,7 @@ How an App keeps what it shows as typed documents in the Rooms bound to it.
 - Keep each type in its own folder, such as `tasks/`, and read it by `pathPrefix`. A query naming `types` fails with `unknown-type` over bound Rooms none of which declares them, and answers `{ pending }` instead while the App reaches no bound Room yet; an observed query that has already answered answers `{ pending }` while its bound Rooms refuse it, and answers again once they declare what it names.
 - Link types with `reference` fields instead of copying values; a query follows them with `hop` and `backlinks`.
 - `app.json` `room_slots` names the Rooms the App needs, each with `access` `read` or `write` and the `types` it uses ([App manifest](reference/app-manifest)). Bind Rooms with `apps/bindings/set`; App code cannot bind and reaches only bound Rooms, so it opens `bridge.ceremony('/bind/<app_ref>?slot=<name>')`, the House page where your User binds Rooms, which returns to the App.
-- A bound Room must hold each slot type identically in its own `settings/schema.yaml`, beside any other types, or its binding warns the User who bound it, and `apps/bindings/list` names that release and slot in its `mismatch` line, to the App's owner too. Write it with `files_batch` before binding; `rooms/create` makes a new Room.
+- A bound Room must hold each slot type identically in its own `settings/schema.yaml`, beside any other types, or its binding warns the User who bound it, and `apps/bindings/list` names that release and slot in a line of its `mismatches`, to the App's owner too. Only `indexed`, rule keywords and `title`s may differ, and a type whose `indexed` leaves out a field the App's names still fits, with a warning there naming the fields to index. Write it with `files_batch` before binding; `rooms/create` makes a new Room.
 - A slot may hold a Space instead (`apps/bindings/set` with `space_ref`): every Room of it your User holds, now and later. An App its owner puts into a Space (`apps/space/set`) uses that Space's schema instead of its own `schema.yaml`, and every member of the Space uses it, each slot holding the Space's Rooms.
 - Read an existing Room's `settings/schema.yaml` before inventing types. Two Apps over one schema are two interfaces over the same data, and your User's agents read and write those documents too.
 - House's own facts, such as your User's Rooms and the Space each is in, come from House acts: name each in `app.json` `house_acts` and call it with `runtime.call('<act>', input)`, such as `runtime.call('rooms/list', {})`. A call needs a connection, so offline show what the bound Rooms hold. A slot holding the Private Room brings its Triggers and none of the other documents House writes under its `house/`.

package/guide/apps/design-functions.md

@@ -0,0 +1,10 @@
+# Which function does what
+
+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 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**, 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-load.md

@@ -0,0 +1,14 @@
+# Designs that load House
+
+What an App's saves, Triggers and functions cost House's servers and every device holding its Rooms.
+
+- **A save** stores the document's whole new text as a revision, tests it against every Trigger of its Room inside the write, streams the whole text to every device holding the Room and counts once against the saver's Write limit, whatever its size. A log or a state kept in one growing document costs its whole size on every change: keep one small document per thing.
+- **Saving as someone types**, or on a timer, writes each time; the Room Draft keeps what they type until they save ([Room Drafts](apps/room-drafts)).
+- **Every device** holding a Room at the Keep or Open level holds all of its text ([Access level](reference/access-level)), so records written by the thousand fill every holder's device; a file goes in as a file ([files](apps/runtime-files)), never as text in a document.
+- **A Trigger** whose change test is any edit, `changes: "text"`, acts on every save of a document it matches, while a field's change, or the default firing as a document starts to match, acts once per change that matters ([Triggers](reference/triggers)).
+- **A function's writes** fire Triggers, its own included: one whose write matches its own Trigger runs again on each run until that Trigger's <trigger-events-per-hour> Events in the hour are spent, so write what it writes so that its Trigger does not match it ([App functions](apps/functions)).
+- **A function run** reads, on every Event, every document of the types, folders and paths its query names from House's database, within <function-memory>, and one Room owner's runs take at most <function-owner-slots> slots on a server at once: name the narrowest folder or paths, or read a summary document the function keeps ([App functions](apps/functions)).
+- **One Trigger's Events** run one after another, so a busy Trigger builds a queue ([App functions](apps/functions)).
+- **An Agent function run** spends your User's provider budget each time ([Agent function](reference/agent-function)).
+- **Changing a field's `title`** relabels every document of its type in one write ([Schema](reference/schema)).
+- **A query naming no `types`, `pathPrefix` or `paths`** reads every document of its Rooms on the device: name the narrowest and select only what a screen shows ([Local Query](apps/local-query)).

package/guide/apps/design-look.md

@@ -0,0 +1,11 @@
+# An App's look
+
+What House draws around an App's page, and what the App sets for its look.
+
+- **The page is the App's own**, drawn and run by the App ([An App's page](apps/page)). Over it House draws only its wait until the page shows its place, and the dialog asking a User who does not own the App to allow a browser feature or House act the App uses for the first time.
+- **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. 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/design-schema.md

@@ -0,0 +1,13 @@
+# Schemas that read well
+
+How an App's types make documents that read well as Markdown, to people and agents alike.
+
+A typed document writes its values as Markdown, so its schema decides how it reads; [Schema](reference/schema) holds the format.
+
+- A field named `name` is the document's `#` line, and a type with none writes documents with no title line.
+- `title` on a field is the label its line shows, and a field with none shows its key.
+- Each field takes one JSON type. A short value is one line, a yes or no a checkbox line and a `reference` a link; Markdown text (`contentMediaType: text/markdown`) and a value that may hold a line break take a heading of their own; a value of no single type is written as a fenced `json` block.
+- Rows of short values read as a table, and a list of groups that is no table takes one heading per item, named by its `name`.
+- Nest values at most five levels deep, each list's items counting as a level. A value that takes a heading goes one heading level deeper per level, from `##` to `######`, so a schema that places one deeper is refused `heading-depth`, and a deeper plain string that holds a line break is refused `malformed-value` when it is written.
+- One document is one thing, such as a task, a lead or an order: link others by `reference` rather than copying or nesting them, and keep a growing list of records as a folder of documents.
+- A type whose Room your User holds at the Search level, which the App asks through a [House query](apps/query-house), names in `indexed` the fields that query orders, totals or groups by, a list of its own top-level keys, and House keeps an index of their values. A field there holds one plain value, `null` allowed: a number, an integer, a yes or no, or a string that is a choice, a `date`, a `date-time`, a `time` or bounded by a `maxLength` of at most <indexed-text-length> characters; a list, a group, a value of no single type, Markdown text, a `reference` and a House key such as `member` or `submitted` are not. A type names at most <indexed-fields>, and House refuses a schema naming more, an unknown field or one it cannot index with the rule `indexed` and its place. Naming one changes no document and checks none again, so whoever writes the schema may change it.

package/guide/apps/design.md

@@ -0,0 +1,12 @@
+# Design an App
+
+What an App's design settles before its code, one page per question House answers.
+
+- [Which function does what](apps/design-functions): which part of House does each piece of the App's work, and what it costs.
+- [Schemas that read well](apps/design-schema): how its types make documents that people and agents read.
+- [Designs that load House](apps/design-load): what its saves, Triggers and functions cost, and the designs that cost less.
+- [An App's look](apps/design-look): what House draws around its page, and what the App sets.
+
+Keep a Room for the App where you write how it is developed: its decisions, its plan and tickets, and what its Triggers and functions do. Name that Room in the App's README, so the next agent working on the App finds it. House reads nothing there.
+
+[Example: tasks](apps/example-tasks) follows these pages.

package/guide/apps/example-tasks-2.md

@@ -12,8 +12,8 @@ function taskCreation(draft: Draft) {
     : undefined;
 }
 
-function titleOf(draft: Draft): unknown {
-  return draft?.parts.fields?.title?.value ?? taskCreation(draft)?.fields.title;
+function nameOf(draft: Draft): unknown {
+  return draft?.parts.fields?.name?.value ?? taskCreation(draft)?.fields.name;
 }
 
 function el<K extends keyof HTMLElementTagNameMap>(
@@ -26,29 +26,29 @@ function el<K extends keyof HTMLElementTagNameMap>(
   return node;
 }
 
-function titleForm(
+function nameForm(
   action: string,
   room: string,
   path: () => string,
   shown: unknown,
-  parts: (title: string, held: Draft) => Parts,
-  done: (title: HTMLInputElement) => void,
+  parts: (name: string, held: Draft) => Parts,
+  done: (name: HTMLInputElement) => void,
 ) {
   let held = drafts.current().find((draft) => draft.room === room && draft.path === path()) ?? null;
-  const title = el('input', {
-    value: String(titleOf(held) ?? shown),
+  const name = el('input', {
+    value: String(nameOf(held) ?? shown),
     required: true,
-    ariaLabel: 'Title',
+    ariaLabel: 'Name',
   });
   const keep = () =>
     queued(async () => {
-      const written = await write(room, path(), held, parts(title.value, held));
+      const written = await write(room, path(), held, parts(name.value, held));
       held = written.draft;
-      if (written.stale) title.value = String(titleOf(held) ?? shown);
+      if (written.stale) name.value = String(nameOf(held) ?? shown);
       return written.stale;
     });
-  title.oninput = () => void keep();
-  const form = el('form', {}, title, el('button', {}, action));
+  name.oninput = () => void keep();
+  const form = el('form', {}, name, el('button', {}, action));
   form.onsubmit = async (event) => {
     event.preventDefault();
     const stale = await keep();
@@ -56,16 +56,16 @@ function titleForm(
     if (stale) return void (note.textContent = 'Not saved: stale.');
     if (!(await save(room, held))) return;
     held = null;
-    done(title);
+    done(name);
   };
   return form;
 }
 
 function editForm(room: string, path: string, shown: unknown) {
-  const parts = (title: string): Parts => ({
-    fields: { title: { value: title, base: { value: shown } } },
+  const parts = (name: string): Parts => ({
+    fields: { name: { value: name, base: { value: shown } } },
   });
-  return titleForm(
+  return nameForm(
     'Save',
     room,
     () => path,
@@ -76,22 +76,22 @@ function editForm(room: string, path: string, shown: unknown) {
 }
 
 function addForm(room: string) {
-  const parts = (title: string, held: Draft): Parts => {
+  const parts = (name: string, held: Draft): Parts => {
     const kept = taskCreation(held) ?? { type: 'task', fields: { done: false }, sections: {} };
-    return { creation: { ...kept, fields: { ...kept.fields, title } } };
+    return { creation: { ...kept, fields: { ...kept.fields, name } } };
   };
   const adding = drafts
     .current()
     .find((draft) => draft.room === room && draft.path.startsWith('tasks/') && taskCreation(draft));
   let path = adding?.path ?? `tasks/${crypto.randomUUID()}.md`;
-  return titleForm(
+  return nameForm(
     'Add',
     room,
     () => path,
     '',
     parts,
-    (title) => {
-      title.value = '';
+    (name) => {
+      name.value = '';
       path = `tasks/${crypto.randomUUID()}.md`;
     },
   );

package/guide/apps/example-tasks-3.md

@@ -23,7 +23,7 @@ function draw(): void {
     note.textContent = '';
     if (room === undefined) main.replaceChildren('This App has no Room yet.');
     else if (open !== undefined)
-      main.replaceChildren(editForm(open.room, open.path, open.fields!.title), note);
+      main.replaceChildren(editForm(open.room, open.path, open.fields!.name), note);
     else main.replaceChildren(list, addForm(room.locator), note);
   }
   if (!('pending' in answer)) shown();
@@ -35,7 +35,7 @@ function draw(): void {
     const done = task.fields!.done === true;
     const box = el('input', { type: 'checkbox', checked: done, ariaLabel: 'Done' });
     box.onchange = () => void queued(() => toggle(task.room, task.path, done));
-    const link = el('a', { href: task.path }, String(task.fields!.title));
+    const link = el('a', { href: task.path }, String(task.fields!.name));
     link.onclick = (event) => {
       event.preventDefault();
       void bridge.push(`/${task.path}`);

package/guide/apps/example-tasks.md

@@ -2,14 +2,14 @@
 
 A whole tasks App over one Room, keeping every rule of the App pages; its `main.ts` goes on over two more pages.
 
-`schema.yaml`, also written into the Room's `settings/schema.yaml`:
+`schema.yaml`, also written into the Room's `settings/schema.yaml`, so a task reads as its `# Buy milk` line over a `- [ ] Done` line:
 
 ```yaml
 task:
   properties:
-    title: { type: string }
-    done: { type: boolean }
-  required: [title, done]
+    name: { type: string }
+    done: { type: boolean, title: Done }
+  required: [name, done]
 ```
 
 `app.json`, then `apps/bindings/set` with slot `tasks`:
@@ -34,8 +34,8 @@ const sync = await runtime.observe('sync-status');
 const drafts = await runtime.observe('room-drafts');
 const tasks = await runtime.observe('query', {
   pathPrefix: 'tasks',
-  select: { fields: ['/title', '/done'] },
-  orderBy: [{ by: { field: '/title' } }],
+  select: { fields: ['/name', '/done'] },
+  orderBy: [{ by: { field: '/name' } }],
 });
 const main = document.querySelector('main')!;
 const list = document.createElement('div');

package/guide/apps/functions.md

@@ -2,12 +2,12 @@
 
 How an App declares a function that House runs on its servers when a Trigger fires, with no page open and no model.
 
-- **Declare.** `app.json` lists `functions`, each `{"name": "assign lead", "entry": "functions/assign.js"}` ([App manifest](reference/app-manifest)). The entry is one ES module whose default export is the function and which imports nothing, so your build bundles each function, with all it imports, into `dist/`, such as `esbuild src/assign.ts --bundle --format=esm --outfile=dist/functions/assign.js`. A publish is refused whole for an entry that is missing, imports, has no default export or is over <function-size>, for a name used twice, and for more than <release-functions> functions.
-- **Run.** A Trigger's `function` action names the App and one of its functions ([Triggers](reference/triggers)). House runs the App's latest release when the Event's turn comes, one Event of a Trigger after another, so a run reads what the run before it wrote. Runs share a fixed number of slots on each server, one Room owner's at most <function-owner-slots>, and a run waits, its action `waiting`, until it may take one.
-- **The event.** `export default async (event, house) => {}` receives `kind`, the condition's `on`, with `room`, `trigger`, `id`, `moment`, the Room's `time_zone`, `date` and `time` ([Times](apps/function-times)) and what matched: `path` and `reference`, a document change's `transition`, an arriving item's `item` with its `headers` and raw `body` text, a dated document's `document`, a delivered notification's `notification`, the facts of its web document, or a message's `message`, its `sender` and its request's `agent_function`, never its words, with the document that request was started for as `path` and `reference`. `Date` reads `moment`. The return value is ignored, so write what you keep into the Room.
-- **The App API.** `house` is the page's App API over the Trigger's Room alone: `query(q)` ([Local Query](apps/local-query)), which reads only the documents of the `types`, folders (`folder`, `pathPrefix`) and `paths` it names and answers over them alone, so the rest of a large Room is never read: name the `types` or `pathPrefix` of its `hop` and `backlinks` too, and select its parts, since a query or `hop` or `backlinks` naming none, or selecting `backlinks` or `'all'`, is refused `invalid-query`, `saveParts(room, parts)`, `call(name, input)` for the Room acts, each by its House act name, such as `rooms/members/list` and `triggers/fired/list`, and `callExternal(request)`. `call` answers a refusal as a result whose `kind` is `rejected` and `saveParts` as `outcome: 'refused'`, as on the page, and the others reject it with its `code`. Its writes are the App's, by `App <App> (function <function>)`, fire Triggers, its own included, and count against the Room owner's Write limit.
-- **Reach.** A run holds no `fetch`, timer, file, `console` or `Intl`: convert times by `house.toMoment` and `house.toLocal`, which a page lacks. `callExternal` takes the request `bridge.callExternal` takes and is the one way out, to an origin the release's `external_origins` lists; naming its Room, `room_ref: event.room`, carries that Room's Service key, which the function never sees, or is refused `not_found` naming the `origin`. Its calls count against the Room owner's `external_calls` limit.
-- **Never repeated.** A run that started is never run again, even when it failed after a call reached the service. Send `event.id` as the service's idempotency key where it takes one, and name what you write by what the event carries, so a second delivery of the same thing finds it.
-- **Failure and limits.** A throw settles the run `failed` with `function_failed` and its text, which `triggers/fired/list` shows and the panel shows the Room's owner, with no notification; the next Event still runs. A run ends `failed` at <function-time>, at <function-memory> or past <function-calls> external calls: `time_cap_reached`, `memory_cap_reached` or `external_call_cap_reached`.
+- **Declare.** `app.json` lists `functions`, each `{"name": "assign lead", "entry": "functions/assign.js"}` ([App manifest](reference/app-manifest)). The entry is one ES module that imports nothing and default-exports the function, so your build bundles each function with its imports into `dist/`, such as `esbuild src/assign.ts --bundle --format=esm --outfile=dist/functions/assign.js`. A publish is refused whole for an entry that is missing, imports, has no default export or is over <function-size>, for a name used twice, and for more than <release-functions> functions.
+- **Run.** A Trigger's `function` action names the App and one of its functions ([Triggers](reference/triggers)). House runs the App's latest release when the Event's turn comes, one Event of a Trigger at a time, so a run reads what the one before wrote. Runs share a fixed number of slots on each server, one Room owner's at most <function-owner-slots>, and a run waits, its action `waiting`, until it may take one.
+- **The event.** `export default async (event, house) => {}` receives `kind`, the condition's `on`, with `room`, `trigger`, `id`, `moment`, the Room's `time_zone`, `date` and `time` ([Times](apps/function-times)) and what matched: `path` and `reference`, a document change's `transition`, an arriving item's `item` with its `headers` and raw `body` text, a dated document's `document`, a delivered notification's `notification`, the facts of its web document, or a message's `message`, its `sender` and its request's `agent_function`, never its words, with the document that request was started for as `path` and `reference`. `Date` reads `moment`. The return value is ignored: write what you keep into the Room.
+- **The App API.** `house` is the page's App API over the Trigger's Room alone: `query(q)` ([Local Query](apps/local-query)), which reads only the documents of the `types`, folders (`folder`, `pathPrefix`) and `paths` it names: name the `types` or `pathPrefix` of its `hop` and `backlinks` too and select its parts, since naming none, or selecting `backlinks` or `'all'`, is refused `invalid-query`, `saveParts(room, parts)`, `call(name, input)` for the Room acts by House act name and `callExternal(request)`. `call` answers a refusal as `kind: 'rejected'` and `saveParts` as `outcome: 'refused'`, as on the page; the others reject with its `code`. Its writes are the App's, by `App <App> (function <function>)`, fire Triggers, its own included, and count against the Room owner's Write limit.
+- **Reach.** A run holds no `fetch`, timer, file, `console` or `Intl`: convert times by `house.toMoment` and `house.toLocal`, which a page lacks. `callExternal` takes the request `bridge.callExternal` takes and is the one way out; naming its Room, `room_ref: event.room`, carries that Room's Service key, which the function never sees; calls count against the Room owner's `external_calls` limit. Its webhook signing secret goes nowhere: `call('service-keys/signatures/check', { room_ref, origin, text, signature })` answers `matched`, whether `signature` is `text`'s HMAC-SHA256 under it, lowercase hex or base64. Both take only an origin the release's `external_origins` lists and are refused `not_found` naming the `origin` where the Room holds none.
+- **Never repeated.** A run that started is never run again, even when it failed after a call reached the service. Send `event.id` as the service's idempotency key where it takes one, and name what you write by what the event carries, so a second delivery finds it.
+- **Failure and limits.** A throw settles the run `failed` with `function_failed` and its text, which `triggers/fired/list` and the Room owner's panel show, with no notification; the next Event still runs. A run ends `failed` at <function-time>, at <function-memory> or past <function-calls> external calls: `time_cap_reached`, `memory_cap_reached` or `external_call_cap_reached`.
 
 Next: [Example: assign a lead](apps/example-function)

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)).
-- 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.
+- 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; 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 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.
+- 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)).
 - React: `useObserve` and `useSave` from `@agentshouse/mdruntime/react`. The whole client: [The App runtime](apps/runtime).

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

@@ -2,13 +2,12 @@
 
 What an App's page draws and how it behaves in the browser.
 
-- The App draws everything; House draws nothing around it. Set the tab's title with `bridge.setTab({ title })`.
-- The address bar is the shell's, not your page's: read your place from `bridge.address()` and `bridge.onAddress`, and move with `bridge.push` or `bridge.replace`, so Back, Forward, reload and a shared link keep it; a push to the address already shown replaces it, so a double click adds no history entry. After an act that ends what the page shows, and when a dialog closes, `bridge.replace` the next address; a replace with the address this page was opened from goes back to it, so Back returns to where the person came from. Keep the open item, tab, filter and search in the address. Addresses under `/render` and `/info` are House's.
+- The App draws everything on its page; [An App's look](apps/design-look) says what House draws around it. Set the tab's title with `bridge.setTab({ title })`.
+- The address bar is the shell's, not your page's: read your place from `bridge.address()` and `bridge.onAddress`, and move with `bridge.push` or `bridge.replace`, so Back, Forward, reload and a shared link keep it; a push to the address already shown replaces it, so a double click adds no history entry. After an act that ends what the page shows, and when a dialog closes, `bridge.replace` the next address; a replace with the address this page was opened from goes back to it, so Back returns to where the person came from. Keep the open item, tab, filter and search in the address. Addresses under `/render`, `/info` and `/home-screen` are House's.
 - Files: take one in with `binaryFile.attach` the moment it is chosen and keep the Path it answers, hand one out with `binaryFile.download`, and show an image or video in `<room-media>` naming its width and height, so nothing waits for media and nothing moves when it arrives; never read a file whole to show or download it ([files](apps/runtime-files)).
 - Mobile first: lay out from 360 pixels wide up, with no action behind hover alone.
 - Every control works from the keyboard and has a label. Draw no focus mark: give nothing a focus style, and remove the browser's own ring with `* { outline: none; }`, the reset House's base carries, since that base does not reach your page. Nothing takes focus by itself: no `autofocus`, and no `focus()` that runs because a page or dialog opened.
 - 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 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/apps/query-house.md

@@ -0,0 +1,48 @@
+# 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 or group 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 unless
+  it orders by an indexed field, 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.
+- **Ordering.** A query may order by a field each of its `types` names in its schema's
+  `indexed`, as `orderBy: [{ by: { field: '/price' }, direction: 'desc', nulls: 'last' }]`, a
+  text field with `stringSort: 'lexical'`, by code point. Ties order by Path, and `next` is the
+  continuation a Local Query names, passed as `after` the same way. In Path order, an equality or
+  `$in` on such a field reads only its documents, and every other test still filters each page.
+  A Room on the device still orders, totals and groups by any field through a Local Query.
+- **Totals.** `total: true` adds `total` where every field the query tests is indexed so and it
+  tests no `text`. House counts at most its count cap of documents: past it, `total` counts those
+  it read and `totalCapped: true` marks it as a floor, so show it as at least that many.
+- **Groups.** `groupBy: [{ field: '/brand' }]` on one such field answers
+  `{ kind: 'groups', groups, next }`, each group its `key` and `count`, at most 100 a page in key
+  order or with `orderBy: [{ by: 'count', direction: 'desc' }]`; pass `next` as `after`.
+  `capped: true` marks counts past the cap as floors.
+- **Refusals.** House answers `{ kind: 'rejected', code, fields }` for a part that would read the
+  whole Room, as `invalid-query` with a `message` naming the part: an order by more than one term
+  or by anything but Path or such a field, an order, total or group without `types` or on a field
+  a named type does not index, a total or group testing `text` or a field not indexed, a total
+  beside `groupBy`, a group's `size`, `updated` or `greatest`, `hop`, `backlinks`, `fileIds`,
+  `select: 'all'` or a `limit` of 0. A query over 8,000 bytes is `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, totals and groups 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.
 
@@ -26,8 +27,9 @@ not, each with its `cli` and `environment` `{ identity, name, state }`, `state`
 `offline`; offline every Agent a conversation names. Each conversation the Provider lists is held
 complete in the browser. `conversation.list()` and `observe('conversations')` answer each
 with its Agent's identity and name, its name, created and finished times, last outcome,
-live `state` (`asking` while a question waits, `working` while a turn runs, else `idle`)
-and `started`, when the running turn began, or `null`. `observe('conversation', id, {
+live `state` (`asking` while a question waits, `working` while a turn runs, else `idle`),
+`started`, when the running turn began, or `null`, `jobs`, the kinds and counts of what a turn
+left running, and `deliveryWaiting`, the messages no turn has taken yet. `observe('conversation', id, {
 limit, total: true })` holds its latest `limit` messages, at most 1,000, oldest first,
 `total` their count, and `next` while older ones exist, which `after` takes, there or in
 `conversation.read(id, { limit, after })`, for the window before; its chat draft; and,

package/guide/apps/runtime-files.md

@@ -6,16 +6,16 @@ Presentation State is one value per App, kept in the browser and shared by its t
 `presentation.read()` answers it, `null` before anything is kept,
 `observe('presentation')` hears it whole, `presentation.write(value)` replaces it whole,
 and `presentation.edit(members)` sets each member named, or removes one named `null`, in
-the state as it stands, so tabs changing different members never lose each other's change:
+the state as it stands, so tabs editing different members keep each other's change:
 never write back a value read before. Each rejects when the browser does not keep the
 change, and no tab sees it then.
 
 A binary file at a Path is a binary Path entry. Query lists it by `path`, and History each
 of its revisions, with its `binaryFile` record and never its bytes: `{ state: 'accepted',
-revision, path, byteLength, mediaType, sha256 }`, or `{ state: 'pending', localId, path,
-byteLength, mediaType, sha256 }` while an upload the panel saved waits for the Provider.
-Text names a file only by a link to its Path, and a field by a `reference: attachment`. Move
-or remove one as a Document, its bytes following.
+revision, path, byteLength, mediaType, sha256, width, height }`, or with `state: 'pending'`
+and a `localId` for `revision` while an upload the panel saved waits for the Provider.
+House's pages keep an image's proportions by them, an Entry Page `srcset` and `picture`.
+Text names a file only by a link to its Path, a field by a `reference: attachment`. Move or remove one as a Document, its bytes following.
 
 - `binaryFile.attach(room, file)` writes the `File` into the Room at
   `attachments/<YYYY-MM-DD>/<name>`, a free name, and answers `{ kind: 'attached', path }`,
@@ -26,27 +26,27 @@ or remove one as a Document, its bytes following.
   own download of the Provider's address at once, or of a pending file's saved bytes, and
   answers `{ kind: 'started' }`, `blocked` where the browser refused the tab an `.html`
   page opens in, or a refusal or failure.
-- `<room-media room path width height alt>` draws an image, video or audio file of the
-  Room. It reserves the box `width` and `height` set, in the file's own pixels, or a 16:9
-  one, before any byte; asks for the file only as it nears the view; draws a file the
-  browser keeps from its bytes, offline too, and reads and keeps an image; shows a video's
-  first frame with a play mark and plays it only in House's full-screen viewer, which a
-  press on it opens, and plays an audio file, loading only either's metadata from the
-  Provider's address; asks again when a shown file's address lapses; asks again while the
-  file cannot be shown yet, such as
-  while the Room does not hold it or House did not answer, until House refuses it for
-  good; and shows its children where the file cannot be read.
+- `<room-media room path width height alt>` draws an image, video or audio file. Before
+  any byte it reserves the box `width` and `height` set in the file's pixels, else an
+  image's own by its Query record, else 16:9; asks for it only near the view; draws
+  `binaryFile.show`'s answer, an image's copies as `srcset`; shows a video's first frame
+  with a play mark, played only in House's full-screen viewer a press opens, and plays
+  audio, loading only metadata; asks again when a shown file's address lapses or it is not
+  shown yet, until House refuses it for good; and shows its children where it cannot be
+  read.
 - `binaryFile.read(room, path, revision?)` answers `{ kind: 'binary', stream, byteLength,
-  mediaType }`, the bytes a `ReadableStream` of parts of at most a mebibyte, which the
-  browser keeps for later reads, offline too.
+  mediaType }`, a `ReadableStream` of parts of at most 1 MiB, kept for later reads, offline
+  too; `binaryFile.show` the same for a kept file, or `{ kind: 'link', url, name,
+  mediaType, copies }`, each copy House holds of an image as `{ url, width }` for `srcset`
+  and `picture`, keeping the image.
 
-Rooms, Query, Observe, Types, Room Draft, Save, and Reached never touch the network;
-Search, History, a binary file's attach and download, a file shown or read that the
+Rooms, Query, Observe, Types, Room Draft, Save and Reached never touch the network;
+Search, History, a file's attach and download, a file shown or read the
 browser does not keep, and Call go to the Provider through the Adapter.
 Call takes the Action names the Adapter declares, any other answering `undeclared`. A Call
 result whose effect the Provider places in a Room carries `at`, that Room and Room
 Version: `reached(room, roomVersion)` answers whether the Room's confirmed state has
-reached it, which the Room's next changes bring, and `reached(room, roomVersion, path)`
+reached it, and `reached(room, roomVersion, path)`
 whether the held copy of that document was written later. A History revision names its
 author, `{ kind: 'user', id }` or `{ kind: 'inbox', id, name }`; History of a Path no
 document holds answers the removed document's revisions, newest first, with `deleted:

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)