@agentshouse/skills 0.0.0-stage → 0.1.0-c24b2d26daab4

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# `@agentshouse/skills`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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`.
+- `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.
+- `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.
+
+```ts
+import { HOW_WE_WORK, listSkills, readSkill } from '@agentshouse/skills';
+
+for (const { name } of listSkills()) console.log(name, readSkill(name).length);
+console.log(HOW_WE_WORK);
+```
+
+`agentInstructions(houseRef, copies)` returns the first prompt's lines, `GUIDE` every Guide page
+with its path, title, first line and text, `APP_GUIDE` the App guide's lines and
+`EARLIER_HOW_WE_WORK_SHA256` the earlier texts' digests.
+
+The skills come from [mattpocock/skills](https://github.com/mattpocock/skills); thank you, Matt
+Pocock.
+
+MIT.

package/agent-instructions.json

@@ -0,0 +1,10 @@
+{
+  "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 `house find_command '{\"query\":\"app\"}'`. 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."
+  ],
+  "copies": "House Local copies; before work run `house fetch` and rebase onto `<house-ref>`; after it commit, then `house push`:"
+}

package/app-guide.json

@@ -0,0 +1,346 @@
+{
+  "name": "App",
+  "aliases": [
+    {
+      "act": "sites/create",
+      "text": "site"
+    }
+  ],
+  "words": [
+    "app",
+    "apps",
+    {
+      "act": "sites/create",
+      "text": "site"
+    },
+    {
+      "act": "sites/create",
+      "text": "website"
+    },
+    "web",
+    "ui",
+    "frontend",
+    "html",
+    "build",
+    "create",
+    "new",
+    "make",
+    "deploy",
+    "publish"
+  ],
+  "text": [
+    {
+      "act": "sites/create",
+      "text": "# Build an App or a Site",
+      "without": "# Build an App"
+    },
+    "",
+    {
+      "act": "sites/create",
+      "text": "An App is a web page over your User's Rooms, for your User and whom they share it with (`create_share`); a Site is one at a public address anyone opens without signing in. 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.",
+      "without": "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 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`.",
+    "- 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`.",
+    {
+      "act": "sites/create",
+      "text": "- A Site starts with `create_site`: `name` is its address name, and the answer's `source_url` is its App's `.git` address to clone the same way. Anything private is an App."
+    },
+    {
+      "act": "sites/create",
+      "text": "- A Site shows the Rooms it published, as `published` names them: creating it publishes its bound Rooms, a release keeps the published data, and later Room edits stay private until `publish_site_data`. A publication whose `state` is `preparing` replaces the shown one once its screenshot is taken; `list_sites` names each Site's newest publication and its `state`, and `publish_site_data` with nothing changed since answers that publication. `unpublish_site` stops serving a Site and keeps it; `republish_site` or `publish_site_data` serves it again."
+    },
+    "- 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 below 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.",
+    "",
+    "## Data",
+    "",
+    "- 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 (`open_guide` `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`.",
+    {
+      "act": "sites/create",
+      "text": "- `app.json` `room_slots` names the Rooms the App needs, each with `access` `read` or `write` and the `types` it uses (`open_guide` `reference/app-manifest`). Bind Rooms with `set_app_bindings`, a Site's with `set_site_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 and connects account slots, which returns to the App.",
+      "without": "- `app.json` `room_slots` names the Rooms the App needs, each with `access` `read` or `write` and the `types` it uses (`open_guide` `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 and connects account slots, 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 or starts a Routine on an Agent; what it writes reaches the App at once.",
+    "",
+    "## Local first",
+    "",
+    "- 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.",
+    "- 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 reads by Online Read 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`; a keyed one through an `account_slots` entry and `bridge.callExternal` naming the slot and a bound Room that connects it, where House adds the key the page never sees.",
+    "- 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 `node_modules/@agentshouse/mdruntime/AGENTS.md`.",
+    "",
+    "## Example: tasks",
+    "",
+    "`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 above.",
+    "",
+    "```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() {},",
+    "});",
+    "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;",
+    "}",
+    "",
+    "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 () => {",
+    "      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;",
+    "    });",
+    "  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`;",
+    "  });",
+    "}",
+    "",
+    "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();",
+    "```",
+    "",
+    "## The page",
+    "",
+    "- 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. Keep the open item, tab, filter and search in the address. Addresses under `/render`, `/info` and `/tab-icon` are House's.",
+    "- 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.",
+    "- 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.",
+    "",
+    {
+      "act": "sites/create",
+      "text": "## Sites"
+    },
+    {
+      "act": "sites/create",
+      "text": ""
+    },
+    {
+      "act": "sites/create",
+      "text": "- A Site is public: anyone opens it, nobody signs in, and every visitor reads its bound Rooms, which must be your User's own and never the Private Room."
+    },
+    {
+      "act": "sites/create",
+      "text": "- Everything it shows lives as documents in its Room; put its demo data there, never in code."
+    },
+    {
+      "act": "sites/create",
+      "text": "- A visitor's edits stay in their browser and never reach House: write them with `save` as an App does."
+    },
+    {
+      "act": "sites/create",
+      "text": "- To receive messages from visitors, name an Intake Room with `set_site_intake_room` and send each with `runtime.call('submit', { content })`, online only."
+    },
+    {
+      "act": "sites/create",
+      "text": "- `describe_site` sets the title and description search engines show."
+    },
+    {
+      "act": "sites/create",
+      "text": ""
+    },
+    "## Verify",
+    "",
+    "Before `npm run publish`:",
+    "",
+    "- `npm test` passes against the newest `@agentshouse/app-bridge` and `@agentshouse/mdruntime` (`npm install --ignore-scripts <name>@latest`), since every page gets House's newest runtime. Keep mdui's test: it runs the built page on `createMemoryAdapter` from `@agentshouse/mdruntime/memory` and `createHouseBridgeTestHost` from `@agentshouse/app-bridge/test-host`, with no House.",
+    "- Every slot type is in `schema.yaml` exactly as in the bound Room's `settings/schema.yaml`.",
+    "- The entry script registers `bridge.cooperate` before its first draw.",
+    "- The page works 360 pixels wide, offline, and reloaded at a deep address.",
+    "",
+    "After it:",
+    "",
+    "- `list_apps` names the App's `published_release`, whose `revision` is the `main` commit it was built from; a clone, a fetch and `git ls-remote` see `main` alone.",
+    "- Bind the Room once with `set_app_bindings`.",
+    {
+      "act": "sites/create",
+      "text": "- See it yourself: sign your own browser in with `create_sign_in_code`, then open the App's url. A Site needs none.",
+      "without": "- See it yourself: sign your own browser in with `create_sign_in_code`, then open the App's url."
+    },
+    "- Give your User its address. An open page that registers `bridge.cooperate` takes each release by itself; nothing asks them to update."
+  ]
+}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+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;
+}
+export interface SkillFile {
+    readonly path: string;
+    readonly content: string;
+}
+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 HOW_WE_WORK: string;
+export declare const EARLIER_HOW_WE_WORK_SHA256: readonly string[];
+export declare const APP_GUIDE: Guide;
+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

@@ -0,0 +1,68 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+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/u;
+const HEADING = /^# /u;
+export const GUIDE_ROOT = 'index';
+function packaged(name) {
+    return readFileSync(join(PACKAGE, name), 'utf8');
+}
+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 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'));
+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 listSkills() {
+    return readdirSync(SET, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort()
+        .map((name) => ({ name, directory: join(SET, name) }));
+}
+function entryFirst(left, right) {
+    if (left === ENTRY || right === ENTRY)
+        return left === ENTRY ? -1 : 1;
+    return left < right ? -1 : 1;
+}
+export function readSkill(name) {
+    const skill = listSkills().find((listed) => listed.name === name);
+    if (skill === undefined)
+        throw new Error(`no Skill is named ${name}`);
+    return readdirSync(skill.directory, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => relative(skill.directory, join(entry.parentPath, entry.name)))
+        .map((path) => path.split(sep).join('/'))
+        .sort(entryFirst)
+        .map((path) => ({ path, content: readFileSync(join(skill.directory, path), 'utf8') }));
+}

package/guide/get-started.md

@@ -0,0 +1,9 @@
+# Get started
+
+How your User signs up for House and connects you.
+
+House keeps Markdown files in Rooms, which your User shares with other people and their agents.
+
+Sign-up page: <origin>/sign-up
+
+Unless this client already reads your User's Rooms, register there and connect it; then find out what your User wants, keep the plan with `edit` as documents in their First Room, which `list_rooms` names, and make the Rooms yourself with `create_room` through `run_command`.

package/guide/index.md

@@ -0,0 +1,7 @@
+# House
+
+Where House's guides and formats start: `open_guide` opens a page by its `path` or finds pages by `words`.
+
+House keeps Markdown files in Rooms, which your User shares with other people and their agents.
+
+- `reference/`, the formats House reads: [Read level](reference/read-level), [App manifest](reference/app-manifest), [Routine](reference/routine), [Schema](reference/schema) and [Triggers](reference/triggers).

package/guide/reference/app-manifest.md

@@ -0,0 +1,12 @@
+# App manifest
+
+What an App's `app.json` declares.
+
+App manifest, `app.json` at an App’s root: `entry`, its HTML page, and `room_slots`, each with a `name`, `access` `read` or `write`, and `types` from the `schema.yaml` beside it, written like a Room schema; `set_app_bindings` fills a slot with Rooms. Where needed it adds `external_origins`, the https origins its page may reach; `account_slots`, each a `name`, the service’s `origin` and its key `form`, `{kind: bearer}`, `{kind: basic}`, `{kind: header, name}`, `{kind: query, name}` or `{kind: path, prefix}`; `conversations: true` to read your User’s conversations; `local_search: true` to call `search`; `inboxes: true` to show and answer customer chats, naming `inbox-chat` and `inbox-message` in `room_slots`; and `theme_colour`, `#rrggbb`. `find_command` "app" shows how its page works.
+
+```json
+{
+  "entry": "index.html",
+  "room_slots": [{ "name": "tasks", "access": "write", "types": ["task"] }]
+}
+```

package/guide/reference/read-level.md

@@ -0,0 +1,9 @@
+# Read level
+
+How much of a Room a grant or a Share lets its holder read, and where.
+
+Read level, `read` on a Room grant or a Share’s Room item, each level including the one before it: `mcp`, MCP Read, reads through `search`, `shell` and `inspect` alone, each reply at most <mcp-read-size> of the Room’s text, with no copy anywhere; `online`, Online Read, also opens the Room in browser Apps while the browser is online, and reads as `mcp` everywhere else; `local`, Local Read, copies the Room to the browser and the Environments, offline included, and is the one `export` needs. Apps need `online` or `local`.
+
+```json
+{ "room_ref": "r_ab12.1", "read": "online", "operations": ["write"] }
+```

package/guide/reference/routine.md

@@ -0,0 +1,14 @@
+# Routine
+
+How a Routine document in the Private Room is written.
+
+Routine, `/rooms/private/collaboration/routines/<name>.md`: `description` and `input`, a text saying what to send, empty if nothing; the body is the instruction. A Routine Request's input is text the Agent reads, and House checks no shape.
+
+```markdown
+---
+description: Summarize a thread in five bullets.
+input: The thread to summarize, as a ref or pasted text.
+---
+
+Read the thread and write five bullets under summaries/.
+```

package/guide/reference/schema.md

@@ -0,0 +1,28 @@
+# Schema
+
+How a Room's `settings/schema.yaml` declares its document types.
+
+Schema, `/rooms/<room>/settings/schema.yaml`: one JSON Schema in YAML. Each top-level key is an MD type holding the schema of its frontmatter; `$defs` holds shapes reused through `$ref: '#/$defs/<name>'`. An object setting neither `additionalProperties` nor `unevaluatedProperties` refuses other keys. House adds `reference` on a string at any depth, naming the types, or `attachment`, its value links to, and `cross_room: true` beside it, letting that be another Room's document of those types; a link or reference written as its `/rooms/<room>/` path is stored relative to the document; `sections`, a type's `##` headings, each `{ kind: text }` or `{ kind: list, items }`; and `member_document: true` on one type, whose documents name their member with `member`, a User Identifier from `list_members`. On a type, `create_roles` lists the Schema Roles that may create its documents and `delete_roles` those that may delete them, and changing a document's `type` needs both; on a field of a type's own `properties`, `change_roles` lists those that may change it, `initial_roles` those that may set it on a new document, and `transitions` the `{from, to, roles}` changes it may make, `null` standing for absent; `owner` and `member` are built in, `[]` allows nobody, and only someone who manages the Room's access changes them. `edit` creates or replaces the whole text, and may rewrite the documents a change breaks in the same call. A Room may use a Shared schema instead, which `use_shared_schema` chooses: its `settings/schema.yaml` is then a read-only copy of it.
+
+```yaml
+person:
+  member_document: true
+  properties:
+    role: { type: string }
+task:
+  properties:
+    title: { type: string }
+    status: { enum: [open, done] }
+    owner: { type: string, reference: person }
+  required: [title]
+  sections:
+    Notes: { kind: text }
+```
+
+```markdown
+---
+type: person
+member: <User Identifier from list_members>
+role: Designer
+---
+```

package/guide/reference/triggers.md

@@ -0,0 +1,7 @@
+# Triggers
+
+How a Trigger's `condition` and `actions` are written for `create_trigger` and `edit_trigger`.
+
+`condition`: When it fires, e.g. `{on: "documents", scope: {type: "task"}, mode: "starts_matching", new_documents: false, match: {all: [{path: "/fields/status", eq: "review"}, {path: "/members/assignee", eq: "<User id>"}]}}`; for a new document in a folder, `{on: "documents", scope: {folder: "/answers"}, mode: "starts_matching", new_documents: true, match: {all: []}}`; on documents, `moved_between_rooms: true` fires only on a document moved in from or out to another Room, `false` only on any other change; for arriving items, `{on: "items", address: "<push address>", match: {path: "/json/ref", eq: "refs/heads/main"}}`. A clock is `{on: "clock", cron: "0 9 * * 1", time_zone: "Europe/Berlin"}`, or a day before each task is due: `{on: "clock", scope: {type: "task"}, date: "/fields/due", days: -1, at: "09:00", time_zone: "Europe/Berlin", match: <test>}`.
+
+`actions`: What it does; a `notify` action names whom it reaches, e.g. `{kind: "notify", title: "Ready to test", text: "A task waits.", to: {users: ["<User id>"], fields: ["/members/assignee"], roles: ["owner"]}}`, Users by id, the member a field of the matched document names, and every holder of a Schema Role; a `routine` action names a Routine Access.

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

@@ -0,0 +1,25 @@
+# Entry Data Contract
+
+How a Site App's `entry_data` has House serve each route as HTML from Rooms.
+
+Entry Data Contract, `entry_data` in a Site App’s `app.json`: House serves each route as HTML from your Rooms before the App starts, running none of your code. Each of `routes` has a `path` (`/`, `/posts/:slug`), optional `query` (functional `?name` parameters with defaults), `queries` (Local Query objects with `types` and a `pathPrefix` at each scope, no `rooms`; `{"$param": "slug"}` takes an argument, `"as": "integer"` converts it; `boundQuery` from `@agentshouse/mdruntime/entry` fills the same query in your page), `interaction` (the queries its first interaction needs), `title`, `description` and `body`. A body node is text, `{text: v}`, `{markdown: v}` of a document, `{tag, attrs, children}`, `{each: v, as, children}` or `{if: v, then, else}`; a value `v` is a literal, `{param}`, `{at, pointer}` into a query result or `each` item, `{join: [v]}`, `{count: v}` or `{stem: v}`. `styles` lists release CSS files. A route that fails starts the App as usual, and the Site document names why.
+
+```json
+{
+  "routes": [
+    {
+      "path": "/posts/:slug",
+      "queries": {
+        "post": {
+          "types": ["post"],
+          "pathPrefix": "posts",
+          "where": { "/slug": { "$param": "slug" } },
+          "select": { "fields": ["/title"], "markdown": true }
+        }
+      },
+      "title": { "at": "post", "pointer": "/documents/0/fields/title" },
+      "body": [{ "markdown": { "at": "post", "pointer": "/documents/0" } }]
+    }
+  ]
+}
+```

package/how-we-work-earlier.json

@@ -0,0 +1,6 @@
+[
+  "ae4dda60da7b174f22dc5fa9bf07fc27c25864932a74230de4f9f509ddd91f41",
+  "0bdcd43e1603ba6673a3cae56d70bbf90657cbeefd124e91a47be2ca1cbd6c93",
+  "4106a87ec66da6f7b2a10e74d18e6559d68d5f4fe7415dae68f5c7bdb9081968",
+  "ac814a2197038f037b657bb719340395f89f319ac9fcdd386629c3fe2cec68f1"
+]