@agentshouse/skills 0.1.0-ccb87a93006a1 → 0.1.0-cce3e02ef389b

package/README.md

@@ -11,7 +11,7 @@ The Skills agents.house serves its agents, and the texts its agents read.
   an App, `sites/` what a Site adds, and `skills/` agents.house's own Skills, `house-onboarding`,
   `prototype-app`, `build-app` and `wizard`, each page carrying the `name` and `description` a
   `SKILL.md` carries.
-  `routines/` holds the Routines agents.house writes into every Private Room, frontmatter and
+  `agent-functions/` holds the Agent functions agents.house writes into every Private Room, frontmatter and
   all. `owner-rules` is the Owner rules' text, and `owner-rules-earlier.json` the SHA-256 of every
   earlier text.
 - `agent-instructions.json` is the lines that open an agent's first prompt.
@@ -23,9 +23,9 @@ for (const { name } of listSkills()) console.log(name, readSkill(name).length);
 console.log(OWNER_RULES);
 ```
 
-`agentInstructions(houseRef, copies)` returns the first prompt's lines, `GUIDE` every Guide page
-with its path, title, first line and text, `WORK_ON_TICKET` the `routines/work-on-ticket` page's
-text and `EARLIER_OWNER_RULES_SHA256` the earlier texts' digests.
+`agentInstructions(houseRef, copies)` returns the first prompt's lines, which name no Local copy,
+`GUIDE` every Guide page with its path, title, first line and text and
+`EARLIER_OWNER_RULES_SHA256` the earlier texts' digests.
 
 The skills come from [mattpocock/skills](https://github.com/mattpocock/skills); thank you, Matt
 Pocock.

package/agent-instructions.json

@@ -1,10 +1,9 @@
 {
   "lines": [
     "From House:",
-    "Work with House through the `house` CLI: run `house --help`, and `house open_guide` opens `index`, the root page of House's guides and formats.",
-    "To give the User a file, upload it with `house upload` and link it; for an App, a Site or a website, follow the Guide from `index` with `house open_guide`. Never start a server.",
+    "Work with House through the `house` CLI: run `house --help`, and `house run_command '{\"command\":\"guide/open\"}'` opens `index`, the root page of House's guides and formats.",
+    "A file reaches the User as a Room Path written with `house upload` and linked in the answer. House serves an App, a Site or a website built by the Guide from `index` (`guide/open`), with no server of your own.",
     "Optional per-Room instructions: `/rooms/private/rooms/<handle>/AGENTS.md`.",
-    "For another Agent's help, `send_routine_request`; its mail comes back into this conversation. If an Agent of your User has no Routine to call, write one in the Private Room and `create_routine_access` with your User as its only caller."
-  ],
-  "copies": "House Local copies; before work run `house fetch` and rebase onto `<house-ref>`; after it commit, then `house push`:"
+    "For another Agent's help, `agent-functions/send` naming one of the Room's Agent function cards under `house/agent-functions/`, or the Agent and what you ask, as its Trust level there allows; its mail comes back into this conversation."
+  ]
 }

package/dist/index.d.ts

@@ -15,8 +15,7 @@ export interface GuidePage {
 export declare const GUIDE_ROOT = "index";
 export declare const GUIDE: readonly GuidePage[];
 export declare const OWNER_RULES: string;
-export declare const WORK_ON_TICKET: string;
 export declare const EARLIER_OWNER_RULES_SHA256: readonly string[];
-export declare function agentInstructions(houseRef: string, copies: readonly string[]): string[];
+export declare function agentInstructions(_houseRef: string, _copies: readonly string[]): string[];
 export declare function listSkills(): readonly Skill[];
 export declare function readSkill(name: string): readonly SkillFile[];

package/dist/index.js

@@ -4,14 +4,12 @@ import { fileURLToPath } from 'node:url';
 const PACKAGE = fileURLToPath(new URL('..', import.meta.url));
 const SET = join(PACKAGE, 'set');
 const ENTRY = 'SKILL.md';
-const REF_PLACEHOLDER = '<house-ref>';
 const TREE = join(PACKAGE, 'guide');
 const PAGE = '.md';
 const FRONTMATTER = /^---\n[\s\S]*?\n---\n\n?/u;
 const HEADING = /^# /u;
 export const GUIDE_ROOT = 'index';
 const OWNER_RULES_PAGE = 'owner-rules';
-const WORK_ON_TICKET_PAGE = 'routines/work-on-ticket';
 function packaged(name) {
     return readFileSync(join(PACKAGE, name), 'utf8');
 }
@@ -33,17 +31,10 @@ export const GUIDE = readdirSync(TREE, {
     .map((entry) => guidePage(relative(TREE, join(entry.parentPath, entry.name))))
     .sort((left, right) => (left.path < right.path ? -1 : 1));
 export const OWNER_RULES = GUIDE.find((page) => page.path === OWNER_RULES_PAGE).text;
-export const WORK_ON_TICKET = GUIDE.find((page) => page.path === WORK_ON_TICKET_PAGE).text;
 export const EARLIER_OWNER_RULES_SHA256 = JSON.parse(packaged('owner-rules-earlier.json'));
 const INSTRUCTIONS = JSON.parse(packaged('agent-instructions.json'));
-export function agentInstructions(houseRef, copies) {
-    if (copies.length === 0)
-        return [...INSTRUCTIONS.lines];
-    return [
-        ...INSTRUCTIONS.lines,
-        INSTRUCTIONS.copies.replaceAll(REF_PLACEHOLDER, houseRef),
-        ...copies,
-    ];
+export function agentInstructions(_houseRef, _copies) {
+    return [...INSTRUCTIONS.lines];
 }
 export function listSkills() {
     return readdirSync(SET, { withFileTypes: true })

package/guide/{routines → agent-functions}/work-on-ticket.md

@@ -5,11 +5,11 @@ input: The ticket to work on.
 
 # Work on ticket
 
-The Routine an Agent runs when a person sets a Wayfinding ticket in progress with that Agent as its assignee.
+The Agent function an Agent runs when a person sets a Wayfinding ticket in progress with that Agent as its assignee.
 
 Work the one ticket this request names, then stop:
 
-1. Open the `wayfinding-ticket` the request names and set its `conversation` to this conversation.
+1. Open the `wayfinding-ticket` the request names and set its `conversation` to the id of this conversation, which House's first message names.
 2. Work it by its `kind`: for `research`, find out and say where you found it; for `prototype`, build the smallest thing that answers its Question; for `grilling`, ask your User until its Question is settled; for `task`, do what it asks.
 3. Write what you found or made in its Answer section and set its `status` to `done`.
 4. Start no other ticket, not even one this ticket unblocks.

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 (`create_share`). 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 in the browser and syncs it with House. There is no server, backend or House API of yours to call.
 
 - [Start an App](apps/start)
 - [An App's data](apps/data)
@@ -11,3 +11,4 @@ An App is a web page over your User's Rooms, for your User and whom they share i
 - [An App's page](apps/page)
 - [Verify an App](apps/verify)
 - [The App runtime](apps/runtime)
+- [App functions](apps/functions)

package/guide/apps/content-safety.md

@@ -10,9 +10,9 @@ images and other resources only from origins the Provider's policy allows. An ag
 never read the authorization, load code from a Room, call the Provider directly, or rebase
 a refused Change Batch.
 
-MD UI uses semantic HTML, is fully operable from a keyboard with visible focus and
-labelled controls, and lays out 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
+MD UI uses semantic HTML, is fully operable from a keyboard with labelled controls and
+the browser's own focus mark, and lays out 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.

package/guide/apps/data.md

@@ -5,8 +5,11 @@ How an App keeps what it shows as typed documents in the Rooms bound to it.
 - Design the Room schema first. Each thing the App shows is one Markdown document in a Room: its frontmatter `type` names its MD type, the rest of its frontmatter holds the fields, and long text goes in `##` sections. `schema.yaml` declares the types ([Schema](reference/schema)).
 - Keep each type in its own folder, such as `tasks/`, and read it by `pathPrefix`: a query naming `types` fails with `unknown-type` while no bound Room declares them.
 - 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 `set_app_bindings`; 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 your User is warned. Write it with `edit` before binding; `create_room` makes a new Room.
-- 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.
-- What no browser can do, such as acting when documents change or at a set time, is a Trigger (`create_trigger`) that notifies, starts a Routine on an Agent, or runs one of the App's functions on House's servers; what it writes reaches the App at once.
-- A function reaches an outside service only through `house.callExternal(request)`, with the request `bridge.callExternal` takes, at an origin its release's `external_origins` lists; naming its own Room with `room_ref` carries that Room's Service key, which the function never sees, and a refusal, `service_key_not_found` naming the `origin` among them, rejects with its `code` for the function to catch. Its calls count against the Room owner's `external_calls` limit, a run that calls past its cap fails, and a started run is never repeated though its calls may have reached the service, so derive the service's idempotence from the event's `occurrence`.
+- `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 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/`.
+- `shares/create` lets a person into Rooms and Apps: its answer's `added` is `true` when their _Who can add me_ setting admits your User, so they are in at once, and `false` when the Share waits for their Accept.
+- What no browser can do, such as acting when documents change or at a set time, is a Trigger (`triggers/create`) that notifies or runs one of the App's [functions](apps/functions) on House's servers; what it writes reaches the App at once.
+- A Trigger may also start an [Agent function](reference/agent-function) on an Agent of your User.

package/guide/apps/example-function.md

@@ -0,0 +1,66 @@
+# Example: assign a lead
+
+How a function hands each new lead to the manager on shift with the fewest leads since their shift began, records its decision and calls the CRM.
+
+A CRM posts each new lead to the Room's push address (`capture/push-addresses/create`) as `{"event": "lead.created", "card": {"id": 101}}`. The Room holds three types: `staff/<key>.md` with `manager_id`, the manager's id at the CRM; `shifts/<key>.md` with `staff`, the key, and `starts` and `ends` as ISO instants; and `decisions/<card>.md` with `card`, `staff` and `decided_at`. The App's `external_origins` lists the CRM's origin, the Room holds a Service key for it, and a Trigger runs the function for each lead:
+
+```json
+{
+  "on": "items",
+  "query": { "where": { "/address": "<push address>", "/json/event": "lead.created" } }
+}
+```
+
+```js
+export default async (event, house) => {
+  const lead = JSON.parse(event.item.body);
+  const now = event.moment;
+  const card = lead.card.id;
+  const read = async (query) => house.query({ select: { fields: 'all' }, ...query });
+  const [held] = (await read({ types: ['decision'], paths: [`decisions/${card}.md`] })).documents;
+  if (held !== undefined) return;
+  const { documents: shifts } = await read({
+    types: ['shift'],
+    where: { '/starts': { $lte: now }, '/ends': { $gt: now } },
+  });
+  if (shifts.length === 0) throw new Error('no manager is on shift');
+  const leads = async (shift) =>
+    (
+      await read({
+        types: ['decision'],
+        where: { '/staff': shift.fields.staff, '/decided_at': { $gte: shift.fields.starts } },
+        limit: 1,
+        total: true,
+      })
+    ).total;
+  const counted = await Promise.all(
+    shifts.map(async (shift) => ({ shift, leads: await leads(shift) })),
+  );
+  const [{ shift: chosen }] = counted.sort((left, right) => left.leads - right.leads);
+  const [manager] = (await read({ types: ['staff'], paths: [`staff/${chosen.fields.staff}.md`] }))
+    .documents;
+  const answer = await house.callExternal({
+    url: `https://crm.example/cards/${card}`,
+    method: 'PUT',
+    headers: { 'content-type': 'application/json', 'idempotency-key': event.id },
+    body: JSON.stringify({ status: 'assigned', manager: manager.fields.manager_id }),
+    room_ref: event.room,
+  });
+  if (answer.status !== 200) throw new Error(`the CRM answered ${answer.status}: ${answer.body}`);
+  const saved = await house.saveParts(event.room, [
+    {
+      path: `decisions/${card}.md`,
+      parts: {
+        creation: {
+          type: 'decision',
+          fields: { card, staff: chosen.fields.staff, decided_at: now },
+          sections: {},
+        },
+      },
+    },
+  ]);
+  if (saved.outcome !== 'saved') throw new Error(JSON.stringify(saved));
+};
+```
+
+A lead the CRM delivers again finds its decision and calls nothing. Two leads that arrive together run one after another, so the second counts the first's decision and goes to another manager when two are tied. Each count is a query's `total`, so a long shift is never cut at a page. A failed call fails the run with the CRM's answer; the next lead still runs.

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

@@ -42,9 +42,7 @@ function titleForm(
   });
   const keep = () =>
     queued(async () => {
-      unsaved.add(title);
       const written = await write(room, path(), held, parts(title.value, held));
-      unsaved.delete(title);
       held = written.draft;
       if (written.stale) title.value = String(titleOf(held) ?? shown);
       return written.stale;

package/guide/apps/example-tasks.md

@@ -12,7 +12,7 @@ task:
   required: [title, done]
 ```
 
-`app.json`, then `set_app_bindings` with slot `tasks`:
+`app.json`, then `apps/bindings/set` with slot `tasks`:
 
 ```json
 { "entry": "index.html", "room_slots": [{ "name": "tasks", "access": "write", "types": ["task"] }] }
@@ -23,43 +23,11 @@ task:
 ```ts
 import { houseBridge } from '@agentshouse/app-bridge';
 
-type Task = { top: number; field: string | null; start: number | null; end: number | null };
-
 const bridge = houseBridge();
 let shown!: () => void;
 const showing = new Promise<void>((resolve) => (shown = resolve));
 let writing: Promise<unknown> = Promise.resolve();
-const unsaved = new Set<HTMLInputElement>();
-bridge.cooperate({
-  checkpoint: () => showing,
-  async persist() {
-    await writing;
-    if ([...unsaved].some((title) => title.isConnected)) throw new Error('unsaved');
-  },
-  capture(): Task {
-    const at = document.activeElement;
-    const field = at instanceof HTMLInputElement && at.selectionStart !== null ? at : null;
-    return {
-      top: scrollY,
-      field: field?.ariaLabel ?? null,
-      start: field?.selectionStart ?? null,
-      end: field?.selectionEnd ?? null,
-    };
-  },
-  async restore(task) {
-    await showing;
-    const held = task as Task | null;
-    if (held === null) return;
-    const field = Array.from(document.querySelectorAll('input')).find(
-      (input) => held.field !== null && input.ariaLabel === held.field,
-    );
-    field?.focus({ preventScroll: true });
-    field?.setSelectionRange(held.start, held.end);
-    scrollTo(0, held.top);
-  },
-  ready: () => true,
-  settle() {},
-});
+bridge.cooperate({ placed: () => showing });
 const runtime = await bridge.runtime;
 const rooms = await runtime.observe('rooms');
 const sync = await runtime.observe('sync-status');

package/guide/apps/functions.md

@@ -0,0 +1,13 @@
+# App functions
+
+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 House's servers, and a run waits, its action `waiting`, until one is free.
+- **The event.** `export default async (event, house) => {}` receives `kind`, the condition's `on`, with `room`, `trigger`, `id`, `moment` 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 `records/list` and `rooms/members/list`, and `callExternal(request)`. `query` and `callExternal` reject a refusal with its `code` for the function to catch, while `call` answers it as a result whose `kind` is `rejected` and `saveParts` as `outcome: 'refused'`, as on the page, so check what they answer. 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`: keep times as ISO instants, or convert a local time by its UTC offset yourself. `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`.
+
+Next: [Example: assign a lead](apps/example-function)

package/guide/apps/local-first.md

@@ -1,16 +1,17 @@
 # Local first
 
-How an App reads and writes its Rooms on the device, offline included.
+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`, `search` and `observe` answer from the device and never wait on the network.
-- Draw from `observe` at once, with no loading spinner for Room data and no request of your own; 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, or the search index has not: draw the page without those documents, and keep the empty state for a complete answer that has none. `rooms` answers once the runtime knows the Rooms the page reaches. Offer binding a Room when it is empty while the sync status names House reachable (`providerUnreachable` false) and `observe('connection-refusal')` answers `null`; an empty list at any other moment 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. `query` and `observe` answer from the device and never wait on the network; `search` asks House ([Search rules](apps/search)).
+- Draw from `observe` at once, with no request of your own; an observation hears each later change by itself, so never poll, refetch or subscribe. An answer is `{ pending }` while a Room it reads has not reached this device or been prepared on it: draw the page without those documents; keep the empty state for a complete answer. `rooms` answers once the runtime knows the Rooms the page reaches. Offer binding a Room when it is empty while the sync status's `providerUnreachable` is false and `observe('connection-refusal')` answers `null`; any other empty list says only that nothing can be listed yet.
+- Show no loading state: draw the last state the device holds. A wait shows only after an act the User pressed whose answer comes from outside the stream, such as `bridge.callExternal`, until it arrives.
 - Write optimistically: write a Room Draft, then `save`. The change shows in every query at once as a Pending Change and reaches House when it can. `save` refuses at once, with its `code`, a change that is `stale`, `changed-underneath` or against the schema: say so and keep the form.
 - 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.
 - 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 or search 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 as 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`, which House's server sends. 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.
-- 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 through `code` and `retryable`, which every refusal and failure carries.
-- React: `useObserve` and `useSave` from `@agentshouse/mdruntime/react`. react-admin and Refine: the data providers of `@agentshouse/mdruntime-families`. The whole client is described in [The App runtime](apps/runtime).
+- 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.
+- 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`. react-admin and Refine: the data providers of `@agentshouse/mdruntime-families`. The whole client: [The App runtime](apps/runtime).

package/guide/apps/local-query-results.md

@@ -11,11 +11,20 @@ How a Local Query answers each change, orders, groups and pages its result, and
   one Path for another is the same file moved, and an unsent creation has neither until it
   is Accepted. `revision` is the Provider's head revision, `null` for an unsent creation or edit,
   and moves with an unsent move. A Room's last change is its Document with the latest `time`.
-- **Order and groups.** `orderBy` sorts by `room`, `path`, `type`, `folder` or `{ field }`: missing
-  and null first, last with `nulls: 'last'`, then numbers and booleans, then text by `locale` or
+- **Size and Created.** `size` is the bytes a row holds, a text's UTF-8 length or a file's
+  `byteLength`, and `created` the ISO 8601 time its file was created, or `null` where the
+  Provider names none; an unsent creation takes the time it was saved.
+- **Order and groups.** `orderBy` sorts by `room`, `path`, `type`, `folder`, `size`, `created`,
+  `updated`, which is its change's `time`, or `{ field }`: missing
+  and null first, last with `nulls: 'last'`, then numbers and booleans, then date-times as instants, then text by `locale` or
   code point with `stringSort: 'lexical'`, then lists item by item; ties end with Room, then Path.
-  `groupBy` by `room`, `type`, `folder` or `{ field }` answers `{ groups: [{ key, count }] }`,
-  counted over every match and ordered by `count` or a key. A sort or group takes only a
+  `groupBy` by `room`, `type`, `folder`, `subfolder` or `{ field }` answers `{ groups: [{ key, count }] }`,
+  counted over every match. `subfolder` is the child folder of `pathPrefix`, or of the Room's root,
+  that holds a row, `null` for a row directly in it, so one query totals every child folder. A
+  group's `select: { size: true }` adds `documents` and `files`, each `{ count, size }`,
+  `updated: true` its latest `updated`, and `greatest: { field }` that field's greatest value. A
+  group orders by `count`, `size`, `updated`, `greatest` or a key, each with `nulls`. Grouped by
+  `folder` or `subfolder` alone, a folder holding no match answers a count of 0. A sort or group takes only a
   single-value pointer. `limit`, at most 1,000 whatever a query names, bounds the Documents or the
   groups, and a result it cuts short names `next`: the same query with it as `after` reads the next
   window, in the same order, ties included. `total: true` adds `total`, every match's count. An

package/guide/apps/local-query.md

@@ -11,19 +11,27 @@ draw it as loading and observe the query to hear the complete answer. A query is
 
 - **Filter.** `rooms` names Room locators and defaults to every Room. `types` names MD
   Types, and `any` names untyped Markdown Documents. `pathPrefix` is a directory: `notes`
-  keeps `notes/a.md` and not `notes2/a.md`; `folder` keeps only what lies directly in it.
+  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.
   `paths` keeps only the Paths it names: read named Documents so, never from a list.
+  `fileIds` keeps only the Documents of the `fileId`s it names, wherever they moved, on
+  the device alone: an App function refuses it.
+  `text` keeps the Documents whose text contains that phrase, ignoring case, ranking
+  nothing.
 - **Fields.** Every frontmatter value is named by JSON Pointer: `/status`,
   `/shipping/city`, `~1` for a `/` and `~0` for a `~` in a key. A segment that meets a
   list applies to every item and a number names one item. `where` names pointers, ANDs
   them, and nests `$and` and `$or`; a pointer through a list holds if any item satisfies
   it. A bare value is equality; the operators are `$eq`, `$ne`, `$in`, `$nin`, `$gt`,
-  `$gte`, `$lt`, `$lte`, `$all`, `$size` and `$exists`. Equality on a list asks if it
+  `$gte`, `$lt`, `$lte`, `$all`, `$size`, `$exists` and `$prefix`, which keeps text starting
+  with it, case kept. Equality on a list asks if it
   contains the value. Missing, null and empty differ: `$exists: false` keeps a missing
-  field, `null` an explicit null, `''` empty text and `$size: 0` an empty list. A date
-  compares in calendar order and never with a date-time. A reference compares by the
+  field, `null` an explicit null, `''` empty text and `$size: 0` an empty list. A test on a
+  missing value is false and `$ne`, `$nin` and `$exists: false` true. A date
+  compares in calendar order and never with a date-time. A date-time compares as an instant,
+  whatever offset it is written in. A reference compares by the
   Room Path it resolves to. Untyped frontmatter, and a value under `oneOf` or a
-  conditional, is plain values. There is no text containment or regular expression.
+  conditional, is plain values. There is no regular expression.
 - **Relations.** Within one Room, `hop: { field, types, where, pathPrefix }` keeps Documents
   whose reference at pointer `field`, at any depth, points to a matching Document, and
   `backlinks` with the same keys those a matching Document references, each once. A body
@@ -31,14 +39,14 @@ draw it as loading and observe the query to hear the complete answer. A query is
   `resolve(room, path, destination)` answers its `document`, the `deleted` one's last
   `revision`, or `unreadable` where the App does not bind it or it is locked.
 - **Parts.** A Document query must `select`: `'all'`, or `fields`, `sections`,
-  `preamble`, `markdown`, `backlinks`, `change`, `fileId` and `revision`, where `fields` is `'all'`
+  `preamble`, `markdown`, `backlinks`, `change`, `fileId`, `revision`, `size` and `created`, where `fields` is `'all'`
   or a list of pointers and `sections` `'all'` or a list of names. Selected pointers
   return the frontmatter holding only them, nested as written. A backlink names the
   referring Path, MD Type and the pointer it came from as `field`. Room and Path always
   return; a Markdown Document also returns its MD Type, and at most its first 1,000
   backlinks: a query on the referring field reads the rest. A non-Markdown Document
-  returns only Room, Path and a selected `fileId` and `revision`, a binary Path entry its `binaryFile`
-  record too, and a text file its text as a selected `markdown`, kept out of Search. An unselected part is absent. Select only what a screen shows: a list
+  returns only Room, Path and a selected `change`, `fileId`, `revision`, `size` and `created`, a binary Path entry its `binaryFile`
+  record too, and a text file its text as a selected `markdown`. An unselected part is absent. Select only what a screen shows: a list
   that selects the Markdown hears every edit of it.
 
 Next: [Local Query changes, order and results](apps/local-query-results)

package/guide/apps/page.md

@@ -3,11 +3,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`, `/info` and `/tab-icon` are House's.
+- 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.
 - 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, with visible focus and a label.
+- Every control works from the keyboard and has a label; give it no focus style of your own and never remove the browser's focus mark.
 - 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/room-drafts.md

@@ -25,7 +25,7 @@ writing back a Room Draft read before.
 
 Outcomes follow the Provider's answer. An Accepted Change Batch stays in the queue, drawn
 over the confirmed layer, until that layer reaches the Room Version it was accepted at.
-Conflicted and Rejected, an expired operation, and a change that no longer applies each
+Conflicted and Rejected, and a change that no longer applies, each
 leave the queue and return as Room Drafts on their Documents, marked with why: the
 Provider's structured refusal code and fields as returned, not known to have applied, or
 withdrawn locally. The rest of the queue keeps synchronizing, and Sync Status requires

package/guide/apps/runtime-api.md

@@ -6,7 +6,8 @@ App code reaches the MD Runtime through the remote client. The surfaces are Room
 Search, Observe, Types, Room Draft, Save, History, Resolve, binary files, Call,
 Reached, Log, 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 and the signed-in member are observations only.
+statement, the deployment facts, the signed-in member and the count of authority changes
+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
@@ -20,7 +21,8 @@ unsubscribe, and `close()` ends it. Closing the port ends every handle and rejec
 pending call and observation; a reconnected client observes again.
 
 `observe('agents')` answers every Agent a new conversation can go to, each `{ identity,
-name }`, with a conversation yet or not. Each conversation the Provider lists is held
+name }`, a retired one left out: online every Agent of the User, with a conversation yet or
+not, 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`)
@@ -29,9 +31,10 @@ limit, total: true })` holds its latest `limit` messages, at most 1,000, oldest
 `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,
 only in memory, what the Provider streams whether or not anything views it: the running
-`turn` with its parts and its context in use and window, which the message accepted under
-the turn's id replaces, the open questions, the process state, and the CLI's commands and
-options, none stored or searchable. `chatDraft.write` and `chatDraft.discard` keep what
+`turn` with its Session content parts, which the message accepted under the turn's id
+replaces, the session's `state` with its context, limits, cost and what still runs, the open
+questions, the process state, and the CLI's commands and options, none stored or
+searchable. A saved message's `content` holds its turn's parts, tokens and state. `chatDraft.write` and `chatDraft.discard` keep what
 the App Creator composes, and `chatDraft.prepend(conversation, draft)` puts a returned
 message ahead of it as it stands. Sending it is a Provider Action that needs the Provider
 reachable and is never queued. A new conversation's chat draft is keyed `new:<Agent

package/guide/apps/runtime-files.md

@@ -38,13 +38,13 @@ or remove one as a Document, its bytes following.
   mediaType }`, the bytes a `ReadableStream` of parts of at most a mebibyte, which the
   browser keeps for later reads, offline too.
 
-Rooms, Query, Search, Observe, Types, Room Draft, Save, and Reached never touch the
-network; 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 binary file's attach and download, a file shown or read that 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, refreshing the Room until it has, and `reached(room, roomVersion, path)`
+reached it, which the Room's next changes bring, 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-refusals.md

@@ -2,11 +2,12 @@
 
 How the MD Runtime API refuses and fails, and how App code reads the deployment facts and who uses it.
 
-Every refusal and failure carries `code` and `retryable`: each Call and History answer
-other than its result, a refused Save or Room Draft write, a returned Room Draft's reason,
-a Room's refusal, the Connection Refusal and every error a member rejects with, beside its
-message, a Provider refusal with the Provider's own `retryable`. Every code and value is
-open: handle one you do not know by its `code` and `retryable`. Only a tag telling which
+A refusal or failure carries `code` and `retryable`: each Call and History answer other
+than its result, a refused Save, a returned Room Draft's reason, a Room's refusal and every
+error a member rejects with, beside its message, a Provider refusal with the Provider's own
+`retryable`. The Connection Refusal carries a `code` and no `retryable`, and a Room Draft
+write from an older revision answers `{ outcome: 'stale', current }`. Every code and value
+is open: handle one you do not know by its `code`. Only a tag telling which
 fields a value carries, such as `kind`, is closed: keep a branch for one you do not know.
 A model with no usable types answers `types: null`.
 
@@ -17,3 +18,7 @@ learns it: the User the Provider signed in, `{ kind: 'user', id, name }` like a
 until the Provider first names one, and where it names none. It is kept
 with the Local Replicas, answers offline once known, and every port hears the next member
 named; signing out answers `null`, then ends the observation with the authorization.
+`observe('authority-changes')` answers how many times House told the runtime that what its
+User may see changed, a Room's members, a Share or an offer among them, and hears each next
+one, never a reconnection, so a view that read such a fact through Call reads it again when
+the count moves.

package/guide/apps/runtime.md

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

package/guide/apps/search.md

@@ -0,0 +1,21 @@
+# Search rules
+
+How `search` finds Documents by words through House, and how a page finds them offline.
+
+`search({ text, rooms })` asks House's search, the one Agents use, once and online: there
+is no observed search and the device keeps no full-text index. `rooms` names Room locators
+and defaults to every Room the page binds; the search never leaves those Rooms, and finds
+words in every Document there.
+
+- **Results.** `{ kind: 'found', documents }`, ranked by House, at most 20 hits. A hit names
+  its `room` and `path`, and a text hit its first `line` and a short `snippet` of it. Read a
+  hit's Document with `query` naming its `paths`.
+- **Offline.** Without a connection `search` answers `{ kind: 'offline' }`, and where no
+  House search is reached, `{ kind: 'undeclared' }`. Find Documents then with a
+  [Local Query](apps/local-query): by Path, name, field values and `text`, a phrase its text
+  contains. That filter ranks nothing.
+- **Refusals.** House's refusal answers as `kind: 'rejected'` with its `code`, and a lost
+  answer as `transport-uncertainty`: say the search failed and keep what the page shows.
+- **Conversations.** `search` finds no message. Inside one conversation
+  `conversation.read(conversation, { text })` answers its messages that contain a phrase,
+  in windows as any read of it.

package/guide/apps/start.md

@@ -2,9 +2,11 @@
 
 How to get an App's repository, build it and publish every change.
 
-- An App with an `a_` reference already exists, even with no release yet, as every App your User makes in the panel does. Clone its `.git` address, `<origin>/app/<app_ref>.git` or its `source_url` in `list_apps`, with `git clone -c 'credential.helper=!kit git-credential' -c user.name=<agent-git-name> -c user.email=<agent-git-email> <address>`, so Git signs in as you and can commit, in every later step too. Run `npm ci --ignore-scripts`, then publish with `npm run publish`, never with `--name`.
+- An App with an `a_` reference already exists, even with no release yet, as every App your User makes in the panel does. Clone its `.git` address, `<origin>/app/<app_ref>.git` or its `source_url` in `apps/list`, with `git clone -c user.name=<agent-git-name> -c user.email=<agent-git-email> <address>`, so Git commits as you in every later step too. Run `npm ci --ignore-scripts`, then publish with `npm run publish`, never with `--name`.
+- Git signs in as you with a credential your User makes for you on `<origin>/connections`, given as its password.
+- When the Kit runs you, add `-c 'credential.helper=!kit git-credential'` to the clone instead, so the Kit signs Git in.
 - Only when no App exists yet, clone `<origin>/app/new.git` the same way: it gives mdui, a minimal App in plain TypeScript with its test and `npm run publish`. Run `npm ci --ignore-scripts`, then `npm run publish -- --name "<display name>"`, which creates the App and prints its address and its `.git` address. Then `git remote set-url origin <that .git address>`; every later `npm run publish` goes there, without `--name`.
 - Use any framework and build tool. `npm run build` leaves the whole release in `dist/`: the entry HTML, every file it loads, `app.json` and `schema.yaml`. The entry names files by relative paths (Vite: `base: './'`), carries no inline script and loads nothing from outside the release, so bundle fonts and libraries. A release holds at most <release-files> files and <release-size>.
 - Your User sees a change only once it is published, so an ask to change an App is an ask to publish it: end every change with a commit and `npm run publish`, which builds, pushes `main` and the build, and prints `published` or the reason House refused. A `git push` of `main` alone publishes nothing and says so. A refused push changes nothing and the previous release keeps running.
-- Without Git, zip the project folder after the build, without `node_modules` and `.env`, `upload` the ZIP to a Room and publish it with `publish_app_zip`.
-- Every page registers `bridge.cooperate` in its entry script before its first draw, as mdui's `main.ts` does, even a page that reads no Room: only then does a page your User has open take each release by itself, with no reload. A page that registers none keeps the release it opened on until it is opened again. A page that draws everything at once and has nothing to type or select registers `bridge.cooperate({ checkpoint() {}, persist() {}, capture: () => scrollY, restore(top) { scrollTo(0, Number(top)); }, ready: () => true, settle() {} })` after `const bridge = houseBridge()`, which keeps its scroll position. Every other page keeps its User's task through the release as [the example](apps/example-tasks) does: `checkpoint` waits until the page has drawn, `persist` until its Room Draft writes are done, failing while a field it shows was refused its last write so the release waits, `capture` answers the focused field with its cursor and selection, the scroll position and whatever else it holds outside the address, and `restore` puts them back once the page has drawn again; `node_modules/@agentshouse/app-bridge/docs/families.md` describes each member.
+- Without Git, zip the project folder after the build, without `node_modules` and `.env`, `upload` the ZIP to a Room and publish it with `apps/publish-zip`.
+- A page whose first draw is not yet the place it opened on, as one that draws its Room's documents once `observe` answers, registers `bridge.cooperate({ placed })` in its entry script before its first draw, where `placed` resolves once that place shows what it holds, as [the example](apps/example-tasks) does: House keeps its preparation surface over the page until then, and shows a page that registers none at its first draw. An open page keeps the release it loaded and runs the next one at its next load, so it needs no update code; `node_modules/@agentshouse/app-bridge/docs/families.md` describes each bridge member.