@agentshouse/skills 0.1.0-ccce31cfa5fec → 0.1.0-cdd2bd42c3fbd

package/README.md

@@ -5,22 +5,27 @@ The Skills agents.house serves its agents, and the texts its agents read.
 - `set/` holds one directory per Skill, each with its `SKILL.md`: every engineering and
   productivity skill of [mattpocock/skills](https://github.com/mattpocock/skills) but its setup
   skill and `wizard`, file for file beside upstream's `LICENSE`. `upstream.json` names the
-  upstream commit, its date and the skills taken from it. Beside them stand agents.house's own
-  `prototype-app`, `build-app` and `wizard`.
-- `how-we-work.md` is the How-we-work document's text, and `how-we-work-earlier.json` the
-  SHA-256 of every earlier text.
-- `app-guide.json` is the guide to building an App or a Site, and `agent-instructions.json` the
-  lines that open an agent's first prompt.
+  upstream commit, its date and the skills taken from it.
+- `guide/` is the Guide, the pages agents.house serves its agents by path: `index` is its root, and
+  each page opens with its title and one line on what it is for. `apps/` is the guide to building
+  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
+  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.
 
 ```ts
-import { HOW_WE_WORK, listSkills, readSkill } from '@agentshouse/skills';
+import { OWNER_RULES, listSkills, readSkill } from '@agentshouse/skills';
 
 for (const { name } of listSkills()) console.log(name, readSkill(name).length);
-console.log(HOW_WE_WORK);
+console.log(OWNER_RULES);
 ```
 
-`agentInstructions(houseRef, copies)` returns the first prompt's lines, `APP_GUIDE` the guide's
-lines and `EARLIER_HOW_WE_WORK_SHA256` the earlier texts' digests.
+`agentInstructions(houseRef, copies)` returns the first prompt's lines, `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,8 +1,8 @@
 {
   "lines": [
     "From House:",
-    "Work with House through the `house` CLI: run `house --help`, and `house find_command` for 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 `house find_command '{\"query\":\"app\"}'`. Never start a server.",
+    "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.",
     "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."
   ],

package/dist/index.d.ts

@@ -1,14 +1,3 @@
-export type GuideLine = string | {
-    readonly act: string;
-    readonly text: string;
-    readonly without?: string;
-};
-export interface Guide {
-    readonly name: string;
-    readonly aliases: readonly GuideLine[];
-    readonly words: readonly GuideLine[];
-    readonly text: readonly GuideLine[];
-}
 export interface Skill {
     readonly name: string;
     readonly directory: string;
@@ -17,9 +6,16 @@ export interface SkillFile {
     readonly path: string;
     readonly content: string;
 }
-export declare const HOW_WE_WORK: string;
-export declare const EARLIER_HOW_WE_WORK_SHA256: readonly string[];
-export declare const APP_GUIDE: Guide;
+export interface GuidePage {
+    readonly path: string;
+    readonly title: string;
+    readonly line: string;
+    readonly text: string;
+}
+export declare const GUIDE_ROOT = "index";
+export declare const GUIDE: readonly GuidePage[];
+export declare const OWNER_RULES: string;
+export declare const EARLIER_OWNER_RULES_SHA256: readonly 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

@@ -5,12 +5,34 @@ 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';
 function packaged(name) {
     return readFileSync(join(PACKAGE, name), 'utf8');
 }
-export const HOW_WE_WORK = packaged('how-we-work.md');
-export const EARLIER_HOW_WE_WORK_SHA256 = JSON.parse(packaged('how-we-work-earlier.json'));
-export const APP_GUIDE = JSON.parse(packaged('app-guide.json'));
+function guidePage(file) {
+    const text = readFileSync(join(TREE, file), 'utf8');
+    const [heading = '', , line = ''] = text.replace(FRONTMATTER, '').split('\n');
+    return {
+        path: file.slice(0, -PAGE.length).split(sep).join('/'),
+        title: heading.replace(HEADING, ''),
+        line,
+        text,
+    };
+}
+export const GUIDE = readdirSync(TREE, {
+    recursive: true,
+    withFileTypes: true,
+})
+    .filter((entry) => entry.isFile() && entry.name.endsWith(PAGE))
+    .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 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)

package/guide/apps/build.md

@@ -0,0 +1,14 @@
+# Build an App
+
+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.
+
+- [Start an App](apps/start)
+- [An App's data](apps/data)
+- [Local first](apps/local-first)
+- [Example: tasks](apps/example-tasks)
+- [An App's page](apps/page)
+- [Verify an App](apps/verify)
+- [The App runtime](apps/runtime)
+- [App functions](apps/functions)

package/guide/apps/chat.md

@@ -0,0 +1,23 @@
+# The Chat
+
+How an App mounts House's Chat through its bridge and themes it.
+
+In House the page's bridge places the Chat, one data layer for every App, which House
+serves with the page and keeps current: install, import and bundle nothing for it, and add
+no dependency. `const chat = await houseBridge.chat.mount(element, options)`, on the bridge
+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. `conversation` opens one, `null` for a
+new chat, `agent` is the Agent a new chat goes to, `showChats` adds its conversation list,
+`width` is `full` (the element), or `3/4`, `1/2` or `1/3` of the window docked at its right
+edge, whole on a narrow window, `onOpen` hears each conversation it opens as `{
+conversation, agent }`, and `onLink` takes a link without a scheme in place of the browser.
+Theme its own styles with CSS custom properties on the element or an ancestor:
+`--chat-background`, `--chat-surface`, `--chat-text`, `--chat-text-muted`,
+`--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. 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:…`: leave them.

package/guide/apps/client.md

@@ -0,0 +1,21 @@
+# App code takes the client its host hands it and never constructs a Runtime
+
+Which runtime entries App code takes, and which it never imports.
+
+No module outside an Adapter package imports, names, or special-cases a Provider, and
+every App and MD UI reach data only through the client entry. In House,
+`houseBridge().runtime` from `@agentshouse/app-bridge` resolves to the client House built
+into the page. App code imports only types from `@agentshouse/mdruntime/client`, never
+calls `connectMdRuntime` or `serveMdRuntime`, and never imports the package main, the host
+entry or the Adapter package; the in-memory Adapter at `@agentshouse/mdruntime/memory` is
+for tests and ships in no bundle.
+
+A React App may observe and save through `@agentshouse/mdruntime/react`, with React as a
+peer dependency. `useObserve(client, topic, ...input)` takes the arguments of `observe`
+and returns `{ state: 'loading' }` until the topic's first value arrives, then `{ state:
+'ready', value }`, re-rendering on each change; a `null` client stays loading.
+`useSave(client)` returns `busy`, the last `outcome` or `failure`, and `save(room,
+parts)`, which saves through `saveParts` and rejects with a recorded failure.
+`saveWritten(room, roomDrafts)` saves Room Drafts the App wrote, each named with the
+revision its last write returned: one another tab wrote since is refused as `stale`, and
+nothing is saved. React-admin and Refine Apps use `@agentshouse/mdruntime-families`.

package/guide/apps/content-safety.md

@@ -0,0 +1,18 @@
+# Content safety and launch promises
+
+What the runtime keeps from App code, and what MD UI promises.
+
+The Provider authorization belongs to the Runtime host and is never readable by the App's
+code. The App's code reaches the network only at the external origins its manifest
+declares, empty by default, and the Provider enforces that set. Rendered Markdown never
+executes scripts, renders raw HTML only for the details and summary elements, and loads
+images and other resources only from origins the Provider's policy allows. An agent must
+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
+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

@@ -0,0 +1,13 @@
+# An App's data
+
+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.
+- House's own facts, such as your User's Rooms, come from House acts: name each in `app.json` `house_acts` and call it with `runtime.call('<act>', input)`, such as `runtime.call('rooms/read', {})`. 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/`.
+- What no browser can do, such as acting when documents change or at a set time, is a Trigger (`create_trigger`) 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 a [Routine](reference/routine) on an Agent of your User.

package/guide/apps/example-function.md

@@ -0,0 +1,67 @@
+# 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 (`create_push_address`) 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",
+  "address": "<push address>",
+  "match": { "path": "/json/event", "eq": "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 and tells the Room's owner; the next lead still runs.

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

@@ -0,0 +1,101 @@
+# Example: tasks, the forms
+
+The forms of the tasks example's `main.ts`, after its start.
+
+`main.ts`, continued:
+
+```ts
+function taskCreation(draft: Draft) {
+  const creation = draft?.parts.creation;
+  return creation !== undefined && 'type' in creation && creation.type === 'task'
+    ? creation
+    : undefined;
+}
+
+function titleOf(draft: Draft): unknown {
+  return draft?.parts.fields?.title?.value ?? taskCreation(draft)?.fields.title;
+}
+
+function el<K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  props: object,
+  ...children: (Node | string)[]
+) {
+  const node = Object.assign(document.createElement(tag), props);
+  node.append(...children);
+  return node;
+}
+
+function titleForm(
+  action: string,
+  room: string,
+  path: () => string,
+  shown: unknown,
+  parts: (title: string, held: Draft) => Parts,
+  done: (title: HTMLInputElement) => void,
+) {
+  let held = drafts.current().find((draft) => draft.room === room && draft.path === path()) ?? null;
+  const title = el('input', {
+    value: String(titleOf(held) ?? shown),
+    required: true,
+    ariaLabel: 'Title',
+  });
+  const keep = () =>
+    queued(async () => {
+      const written = await write(room, path(), held, parts(title.value, held));
+      held = written.draft;
+      if (written.stale) title.value = String(titleOf(held) ?? shown);
+      return written.stale;
+    });
+  title.oninput = () => void keep();
+  const form = el('form', {}, title, el('button', {}, action));
+  form.onsubmit = async (event) => {
+    event.preventDefault();
+    const stale = await keep();
+    if (stale === null) return;
+    if (stale) return void (note.textContent = 'Not saved: stale.');
+    if (!(await save(room, held))) return;
+    held = null;
+    done(title);
+  };
+  return form;
+}
+
+function editForm(room: string, path: string, shown: unknown) {
+  const parts = (title: string): Parts => ({
+    fields: { title: { value: title, base: { value: shown } } },
+  });
+  return titleForm(
+    'Save',
+    room,
+    () => path,
+    shown,
+    parts,
+    () => void bridge.push('/'),
+  );
+}
+
+function addForm(room: string) {
+  const parts = (title: string, held: Draft): Parts => {
+    const kept = taskCreation(held) ?? { type: 'task', fields: { done: false }, sections: {} };
+    return { creation: { ...kept, fields: { ...kept.fields, title } } };
+  };
+  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(
+    'Add',
+    room,
+    () => path,
+    '',
+    parts,
+    (title) => {
+      title.value = '';
+      path = `tasks/${crypto.randomUUID()}.md`;
+    },
+  );
+}
+```
+
+Next: [Example: tasks, the list](apps/example-tasks-3)

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

@@ -0,0 +1,52 @@
+# Example: tasks, the list
+
+The list that ends the tasks example's `main.ts`.
+
+`main.ts`, continued:
+
+```ts
+async function toggle(room: string, path: string, done: boolean): Promise<void> {
+  const parts = { fields: { done: { value: !done, base: { value: done } } } };
+  const saved = await runtime.saveParts(room, [{ path, parts }]);
+  note.textContent = saved.outcome === 'saved' ? '' : `Not saved: ${saved.code}.`;
+  draw();
+}
+
+function draw(): void {
+  const room = rooms.current()[0];
+  const answer = tasks.current();
+  const held = 'pending' in answer ? [] : answer.documents;
+  const open = held.find((task) => `/${task.path}` === bridge.address());
+  const page = room === undefined ? '' : `${room.locator}/${open?.path ?? ''}`;
+  if (page !== drawn) {
+    drawn = page;
+    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);
+    else main.replaceChildren(list, addForm(room.locator), note);
+  }
+  if (!('pending' in answer)) shown();
+  if (room === undefined) return;
+  const refused = new Set(
+    sync.current().attentionRequired.flatMap((entry) => ('path' in entry ? [entry.path] : [])),
+  );
+  const rows = held.map((task) => {
+    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));
+    link.onclick = (event) => {
+      event.preventDefault();
+      void bridge.push(`/${task.path}`);
+    };
+    return el('li', {}, box, link, refused.has(task.path) ? ' (refused)' : '');
+  });
+  const empty = 'pending' in answer ? '' : 'No tasks yet. Add the first one.';
+  list.replaceChildren(rows.length > 0 ? el('ul', {}, ...rows) : empty);
+}
+
+for (const observed of [rooms, sync, tasks]) observed.subscribe(draw);
+bridge.onAddress(draw);
+draw();
+```

package/guide/apps/example-tasks.md

@@ -0,0 +1,75 @@
+# Example: tasks
+
+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`:
+
+```yaml
+task:
+  properties:
+    title: { type: string }
+    done: { type: boolean }
+  required: [title, done]
+```
+
+`app.json`, then `set_app_bindings` with slot `tasks`:
+
+```json
+{ "entry": "index.html", "room_slots": [{ "name": "tasks", "access": "write", "types": ["task"] }] }
+```
+
+`main.ts`: a list at `/` and a form at each task's own address, keeping every rule of the App pages.
+
+```ts
+import { houseBridge } from '@agentshouse/app-bridge';
+
+const bridge = houseBridge();
+let shown!: () => void;
+const showing = new Promise<void>((resolve) => (shown = resolve));
+let writing: Promise<unknown> = Promise.resolve();
+bridge.cooperate({ placed: () => showing });
+const runtime = await bridge.runtime;
+const rooms = await runtime.observe('rooms');
+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' } }],
+});
+const main = document.querySelector('main')!;
+const list = document.createElement('div');
+const note = document.createElement('p');
+type Parts = Parameters<typeof runtime.roomDraft.write>[3];
+type Draft = Awaited<ReturnType<typeof runtime.roomDraft.read>>;
+let drawn: string | undefined;
+
+async function write(room: string, path: string, held: Draft, parts: Parts) {
+  const { file: _file, ...kept } = { ...held?.parts };
+  const onto = { ...kept, ...parts, fields: { ...kept.fields, ...parts.fields } };
+  const written = await runtime.roomDraft.write(room, path, held?.revision ?? null, onto);
+  return written.outcome === 'written'
+    ? { draft: written.roomDraft, stale: false }
+    : { draft: written.current, stale: true };
+}
+
+async function save(room: string, draft: Draft): Promise<boolean> {
+  const saved =
+    draft === null
+      ? null
+      : await runtime.save(room, [{ path: draft.path, revision: draft.revision }]);
+  note.textContent = saved?.outcome === 'saved' ? '' : `Not saved: ${saved?.code ?? 'stale'}.`;
+  return saved?.outcome === 'saved';
+}
+
+function queued<T>(work: () => Promise<T>): Promise<T | null> {
+  const done = writing.then(work).catch((error: { code?: unknown }) => {
+    note.textContent = `Not saved: ${String(error.code)}.`;
+    return null;
+  });
+  writing = done;
+  return done;
+}
+```
+
+Next: [Example: tasks, the forms](apps/example-tasks-2)

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.
+- **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`, or a delivered notification's `notification`, the facts of its web document. `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)), `saveParts(room, parts)`, `call(name, input)` for the Room acts such as `record.list` and `member.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 `service_key_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 `list_trigger_events` shows and House tells the Room's owner; 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

@@ -0,0 +1,16 @@
+# Local first
+
+How an App reads and writes its Rooms on the device, offline included.
+
+- 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.
+- 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. A call through a Room that holds no key for the origin is refused `service_key_not_found` naming the `origin`: tell the person that the Room's owner or a manager enters the key on the Room's Service keys, in its Info, 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 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).

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

@@ -0,0 +1,27 @@
+# Local Query changes, order and results
+
+How a Local Query answers each change, orders, groups and pages its result, and fails.
+
+- **Change, file ID and revision.** `change` is `{ author, time }` of the Document's head revision
+  as the Provider last delivered it: `author` is `{ kind: 'user' | 'inbox', id, name }`, or
+  `null` for a write the Provider made itself, and `time` its ISO 8601 change time, or the
+  whole change `null` where it delivered no time. `fileId` is the Provider's
+  Stable File ID of the file at the Path, or `null`. An unsent edit keeps both, an unsent
+  move keeps the change and carries the file ID to the new Path, so a file ID that leaves
+  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
+  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
+  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
+  observed window hears rows entering, leaving or changing, and `next`, `total`.
+- **Results and errors.** A result carries no Room Version: read freshness from Rooms and
+  Sync Status. `coverage` names each Room read as `{ room, generation, current }`,
+  `current` false while a newer copy of that Room is being fetched, and the queued changes
+  it includes as `overlay`, which a Save in the Room changes. An invalid query fails with
+  `invalid-query`, `unknown-type`, `unknown-field` or `wrong-kind`, never an empty answer.

package/guide/apps/local-query.md

@@ -0,0 +1,44 @@
+# Local Query rules
+
+How `query` and `observe('query', q)` filter and select Documents on the device.
+
+`query(q)` answers once from local state; `observe('query', q)` holds the whole result and
+hears it again only when it changes, keeping every unchanged Document the same object, so
+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:
+
+- **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.
+  `paths` keeps only the Paths it names: read named Documents so, never from a list.
+- **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
+  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
+  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.
+- **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
+  link or a `cross_room` reference may name another Room's `/rooms/<handle>/<path>`:
+  `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'`
+  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
+  that selects the Markdown hears every edit of it.
+
+Next: [Local Query changes, order and results](apps/local-query-results)