@agentshouse/skills 0.1.0-c8c6b89992ea2 → 0.1.0-c8d3aff1d8c5b

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.

package/agent-instructions.json

@@ -4,6 +4,6 @@
     "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` naming one of the Room's Routine cards under `house/routines/`, or the Agent and what you ask, as its Trust level there allows; its mail comes back into this conversation."
+    "For another Agent's help, `send_agent_function_request` 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/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/data.md

@@ -6,9 +6,9 @@ How an App keeps what it shows as typed documents in the Rooms bound to it.
 - Keep each type in its own folder, such as `tasks/`, and read it by `pathPrefix`: a query naming `types` fails with `unknown-type` 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.
+- 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 House tells the App's owner once for that release and slot. 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 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/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/`.
 - `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 (`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.
+- A Trigger may also start an [Agent function](reference/agent-function) on an Agent of your User.

package/guide/apps/example-function.md

@@ -7,8 +7,7 @@ A CRM posts each new lead to the Room's push address (`create_push_address`) as
 ```json
 {
   "on": "items",
-  "address": "<push address>",
-  "match": { "path": "/json/event", "eq": "lead.created" }
+  "query": { "where": { "/address": "<push address>", "/json/event": "lead.created" } }
 }
 ```
 
@@ -64,4 +63,4 @@ export default async (event, house) => {
 };
 ```
 
-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.
+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/functions.md

@@ -4,10 +4,10 @@ How an App declares a function that House runs on its servers when a Trigger fir
 
 - **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 `routine`, 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 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/read` and `rooms/members`, 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`.
+- **Failure and limits.** A throw settles the run `failed` with `function_failed` and its text, which `list_trigger_events` 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. 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.
+- 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 `service_key_not_found` naming the `origin`: tell the person that the Room's owner or a manager enters the key under Service keys in the Room's 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).
+- 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

@@ -12,7 +12,7 @@ How a Local Query answers each change, orders, groups and pages its result, and
   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
+  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

package/guide/apps/local-query.md

@@ -13,17 +13,24 @@ draw it as loading and observe the query to hear the complete answer. A query is
   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.
+  `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
@@ -38,7 +45,7 @@ draw it as loading and observe the query to hear the complete answer. A query is
   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
+  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/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-files.md

@@ -38,8 +38,8 @@ 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

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

@@ -13,4 +13,4 @@ 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`.
 - 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 keeps the release it loaded and takes the next one at its next load, offline too; nothing asks them to update.
+- Give your User its address. An open page keeps the release it loaded, and its next load made online runs the release you published; nothing asks them to update.

package/guide/index.md

@@ -8,5 +8,5 @@ While your User's My Room, which `list_rooms` marks, holds no `wayfinding-map`,
 
 - `apps/`, building an App over your User's Rooms: [Build an App](apps/build), and the functions House runs for it when a Trigger fires: [App functions](apps/functions).
 - `reference/`, the formats House reads: [Access level](reference/access-level), [App manifest](reference/app-manifest), [Schema](reference/schema) and [Triggers](reference/triggers).
-- `routines/`, the Routine the panel writes for My Room for each Agent it makes, naming that Agent, written as [Routine](reference/routine) says: [Work on ticket](routines/work-on-ticket).
+- `agent-functions/`, the Agent function the panel writes for My Room for each Agent it makes, naming that Agent, written as [Agent function](reference/agent-function) says: [Work on ticket](agent-functions/work-on-ticket).
 - `skills/`, House's Skills: [Prototype an App](skills/prototype-app).

package/guide/owner-rules.md

@@ -23,9 +23,11 @@ The skills are already set up; never run `setup-matt-pocock-skills`.
 - Rejected requests (triage): `out-of-scope/<concept>.md`
 - Implementation notes (implement-spec): `projects/<name>/notes/`
 - PR bodies (pr): `projects/<name>/prs/<branch>.md`
-- Wayfinding map: one `wayfinding-map` document, `projects/<name>/map.md`,
-  and its tickets, `wayfinding-ticket` documents in order as
-  `projects/<name>/map/NN-<slug>.md`: a ticket carries its `title`, its
+- Wayfinding map: one `wayfinding-map` document, `projects/<name>/map.md`
+  with `type: wayfinding-map` in its frontmatter, and its tickets,
+  `wayfinding-ticket` documents in order as `projects/<name>/map/NN-<slug>.md`
+  with `type: wayfinding-ticket`, since House knows a map or a ticket only by
+  its `type`: a ticket carries its `title`, its
   `map` (the map's path), its `kind` (its type) and `blocked_by` (its
   blockers); a claim sets `status: in-progress` and the
   `assignee`, and a resolution writes the Answer and sets `done`, or

package/guide/reference/agent-function.md

@@ -0,0 +1,17 @@
+# Agent function
+
+How an Agent function document in the Private Room is written, one for each Room it serves.
+
+Agent function, `/rooms/private/rooms/<room-handle>/agent-functions/<name>.md`, serving the Room `<room-handle>` names: `description`; `input`, a text saying what to send, empty if nothing; and `agent`, the identifier of the one of your User's current Agents it starts. The body is the instruction, which never leaves the Private Room. Writing it needs your User's write in that Room. House writes its card, the description, input and Agent, at `/rooms/<room-handle>/house/agent-functions/<name>.md`, where every member reads it, and refuses a name a card there already holds as `agent_function_name_taken`. An Agent function a second Room needs is a copy under that Room's handle. Anyone who writes that Room asks it with `send_agent_function_request` naming the card, or names the `agent` with their own words, as the Agent's Trust level in that Room allows: under Any request, the default, either starts at once; under Agent functions only the card starts at once and own words are refused `own_text_not_admitted`; under Approve each either waits for the Agent's owner to approve it. Its owner sets the level on the Agent's House page; the owner, their own agents and their Private Room's Triggers start it at once at every level, a Trigger of any other Room asks as that Room's writers do, and `inspect` on a Room root names the Agents you may ask there with their levels. An Agent function request's input is text the Agent reads, and House checks no shape. Mail your conversation sends with `send_mail` and a request it sent reaches the conversation that request started at once under Any request; below it, `send_mail` answers `waiting: true` and the mail waits for that Agent's owner, and a declined one comes back to you as House's message saying so. That conversation's mail always comes back to yours. A request's run is the first turn of the conversation it starts: during that turn the Agent names the document it wrote in the request's Room as the request's result with `set_request_result`, and the turn's end finishes the request. The conversation stays active until it is Done, which `mark_done` sets at the end of a turn and which nothing undoes, so mail reaches it after its run.
+
+A Trigger's `message` action puts its `text`, a link to what matched and its files into the active conversation, one not Done, its Agent function started from that Room for what the Event is about: the chat of a customer's `chat-message`, the matched document or item, or the Trigger for a `cron` clock. Its Event shows `continued` with that `request`; with none, it starts the Agent function as a `agent_function` action does, `requested`. A conversation waiting for approval refuses it, `refused` with `conversation_waiting`. The Agent reads a customer's message as a customer's words, one from a Trigger of its owner's Private Room as the owner's instruction, and any other as what matched, never an instruction. A `agent_function` action starts a new request on every Event. A `done` action marks Done every active conversation a request of its Trigger's Room started for the Event's document, whoever owns its Agent, but one waiting for approval, which stays for its owner to approve or decline; its Event shows `marked` with their number, `conversations`, 0 when there are none, as on a `cron` clock, whose Event names no document.
+
+```markdown
+---
+description: Summarize a thread in five bullets.
+input: The thread to summarize, as a ref or pasted text.
+agent: 019a0000-0000-7000-8000-000000000001
+---
+
+Read the thread and write five bullets under summaries/.
+```

package/guide/reference/app-manifest.md

@@ -2,7 +2,7 @@
 
 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; `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`; `house_acts`, the House acts it calls by their act names, such as `rooms/read` for your User’s Rooms or `rooms/rename`, never one only a person takes or one that changes what an App reaches, except that a Self-hosted Building's App may declare its administrators' acts, `building/people/read`, `building/people/add`, `building/people/remove`, `building/administrators/name`, `building/administrators/take`, `building/factor/require`, `building/factor/stop-requiring` and `building/factor/reset`, which its page calls in an administrator's browser once it has asked them to confirm each, `building/people/read` refusing anyone else `not_building_administrator`; `functions`, each a `name` and the `entry` file a Trigger runs on House's servers ([App functions](apps/functions)); and `theme_colour`, `#rrggbb`. A User who does not own the App is asked once to allow the House acts it declares, and again only for those a later release adds; a declined one is refused. [Build an App](apps/build) shows how its page works.
+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; `conversations: true` to read your User’s conversations; `inboxes: true` to show customer chats, naming `chat` and `chat-message` in `room_slots`, and answer them through `chats/reply`, since only House writes a chat's documents; `house_acts`, the House acts it calls by their act names, such as `rooms/read` for your User’s Rooms or `rooms/rename`, never one only a person takes or one that changes what an App reaches, except that a Self-hosted Building's App may declare its administrators' acts, `building/people/read`, `building/people/add`, `building/people/remove`, `building/administrators/name`, `building/administrators/take`, `building/factor/require`, `building/factor/stop-requiring` and `building/factor/reset`, which its page calls in an administrator's browser once it has asked them to confirm each; `functions`, each a `name` and the `entry` file a Trigger runs on House's servers ([App functions](apps/functions)); and `theme_colour`, `#rrggbb`. A User who does not own the App is asked once to allow the House acts it declares, and again only for those a later release adds; a declined one is refused. Nobody is asked about an act they have no right to use, and it is refused them unasked, the App's owner included: the administrators' acts `not_building_administrator` to anyone who is no administrator, and `shares/create`, `rooms/create` and the `rooms/access/` acts `operation_denied` to anyone who manages no Room but their Private Room. [Build an App](apps/build) shows how its page works.
 
 ```json
 {

package/guide/reference/schema.md

@@ -2,7 +2,9 @@
 
 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.
+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 in a Space shows its Space's schema at that path and keeps none of its own: its owner and a member who can write in the Space change it there, a rule keyword only someone who manages the Space, in an edit holding that change alone, checked against every document of every Room of the Space; a change that would break any document is refused naming it, so change that document in its own edit first. A Room taken out of its Space keeps the last version as its own.
 
 ```yaml
 person:

package/guide/reference/triggers.md

@@ -2,14 +2,14 @@
 
 How a Trigger's `condition` and `actions` are written for `create_trigger` and `edit_trigger`; House writes a Room's Triggers as read-only `house-trigger` documents at `house/triggers/<trigger>.md`.
 
-`condition`: When it fires, e.g. `{on: "documents", scope: {type: "task"}, mode: "starts_matching", new_documents: false, match: {path: "/fields/status", eq: "review"}}`; for a new document in a folder, `{on: "documents", scope: {folder: "/answers"}, mode: "starts_matching", new_documents: true, match: {all: []}}`; for any edit of one document, `{on: "documents", scope: {document: "/plan.md"}, mode: "field_changes", field: "/text"}`; `moved_between_rooms: true` fires only on a document moved from or to another Room, `false` on any other change; for items, `{on: "items", address: "<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>}`. In your Private Room alone, a notification to you: `{on: "notifications", match: {path: "/fields/kind", eq: "share-offer"}}`, testing its `house-notification` document's `/fields/kind` and its value fields, `match` optional; such a Trigger holds no `notify` action. A `/fields/…` or `/members/…` path reads only what the document's own type declares: a document with no `type` has no fields, whatever its front matter holds, so give it a `type` naming one in `settings/schema.yaml` that declares the field.
+`condition`: When it fires: `on`, a `query` in the [Local Query](apps/local-query) language, at most one of `types`, `pathPrefix` or `paths` (one document, followed when it moves) and a `where`, naming a member by their member document's path, then the change tests. A task becoming ready: `{on: "documents", query: {types: ["task"], where: {"/status": "review"}}}`, firing as it starts to match, a new one only with `new_documents: true`. A field moving: `changes: {field: "/status", from: ["open"], to: ["done"]}`, or `from: "new"`, `to: "deleted"`; a section `{section: "Notes"}`; any edit `"text"`. `by: {"/door": "browser", "/user": "<User id>"}` tests who changed it and how; `moved_between_rooms: true` only a move between Rooms. Items: `{on: "items", query: {where: {"/address": "<address>", "/json/ref": "refs/heads/main"}}}`, also `/source`, `/delivery`, `/headers/<name>`. A clock is `{on: "clock", cron: "0 9 * * 1", time_zone: "Europe/Berlin"}`, or a day before each task is due: `{on: "clock", query: {types: ["task"], where: …}, date: "/due", days: -1, at: "09:00", time_zone: "Europe/Berlin"}`. In your Private Room alone, a notification to you: `{on: "notifications", query: {where: {"/kind": "share-offer"}}}` over its `house-notification` document; such a Trigger holds no `notify` action. A refusal names the test and what it takes.
 
-A message into a conversation a [Routine Request](reference/routine) of the Room started: `{on: "messages", match: {path: "/sender", eq: "requester"}}`, testing `/sender`, `/routine` and `/path`, the request's document, never its words.
+A message into a conversation the Room's [Agent function request](reference/agent-function) started: `{on: "messages", query: {where: {"/sender": "requester"}}}`, testing `/sender`, `/agent_function` and `/path`, the request's document, never its words.
 
-`actions`: a `notify` action names whom it reaches, e.g. `{kind: "notify", title: "Ready", 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 `function` action names an App and one function its latest release declares, e.g. `{kind: "function", app: "a_…", function: "assign lead"}`, which you may add only for an App you hold that has this Room in a write slot of your bindings; [App functions](apps/functions) says how House runs it. `list_trigger_events` shows each run `ran` with its `release`, or `failed` with `function_failed` and its `error`, never run again, or `function_not_started` while House tries to start it, `final` after its last try.
+`actions`: a `notify` action names whom it reaches, e.g. `{kind: "notify", title: "Ready", 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 `function` action names an App and one function its latest release declares, e.g. `{kind: "function", app: "a_…", function: "assign lead"}`, which you may add only for an App you hold with this Room in a write slot of your bindings; [App functions](apps/functions) says how House runs it. `list_trigger_events` shows each run `ran` with its `release`, or `failed` (`function_failed`, its `error`), never run again, or `function_not_started` while House tries, `final` after its last try.
 
-In your Private Room alone, a `function` action naming no `app` runs one of your Environment functions ([wizard](skills/wizard)), e.g. `{kind: "function", function: "nightly backup"}`; elsewhere, or for a name you do not hold, it is refused `environment_function_not_found`. Kit runs its script with no terminal, the Event as JSON in the file `HOUSE_INPUT` names, one Event after another. `list_trigger_events` shows each run `ran`, or `failed` with `function_failed` and its `error`, never run again, with its `run`, `exit_code` and `output`; a Kit not connected at its turn reads `no_target` with `environment_offline`, never run later.
+In your Private Room alone, a `function` action naming no `app` runs one of your Environment functions ([wizard](skills/wizard)), e.g. `{kind: "function", function: "nightly backup"}`; elsewhere, or for one you do not hold, it is refused `environment_function_not_found`. Kit runs its script with no terminal, the Event as JSON in the file `HOUSE_INPUT` names, one Event at a time. `list_trigger_events` shows each run `ran` or `failed` (`function_failed`, its `error`), never run again, with its `run`, `exit_code` and `output`; a Kit not connected at its turn reads `no_target` with `environment_offline`, never run later.
 
-A Trigger acts on at most <trigger-events-per-hour> Events in each UTC hour, across its versions, skipped and failed ones not counted; `list_trigger_events` shows the first past the number `missed: "skipped"` with `code: "cap_reached"`, which starts nothing, and none later that hour; its creator is told once per version. A Trigger whose own actions make what it fires on stops there, so narrow its condition.
+A Trigger acts on at most <trigger-events-per-hour> Events in each UTC hour, across its versions, skipped and failed ones not counted; `list_trigger_events` shows the first past the number `missed: "skipped"` with `code: "cap_reached"`, which starts nothing, and none later that hour; the Trigger shows as failing. A Trigger whose own actions make what it fires on stops there, so narrow its condition.
 
-`{kind: "routine", card: "<name>", payload: "<input>"}` starts a [Routine](reference/routine) and `{kind: "message", card: "<name>", text: "<text>"}` messages it; no such card is refused `routine_not_found`, a retired one `routine_retired`. `{kind: "done"}` marks Done each active conversation any Routine Request of the Room started for the Event's document, `marked` with their number.
+`{kind: "agent_function", card: "<name>", payload: "<input>"}` starts an [Agent function](reference/agent-function) and `{kind: "message", card: "<name>", text: "<text>"}` messages it; no such card is refused `agent_function_not_found`, a retired one `agent_function_retired`. `{kind: "done"}` marks Done each active conversation the Room's Agent function requests started for the Event's document, `marked` with their number.

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

@@ -2,7 +2,7 @@
 
 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}`. An `img`, a document's images among them, loads lazily in the box its `width` and `height` name, 16:9 without them. `styles` lists release CSS files. A route that fails starts the App as usual, and the Site document names why.
+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` or `fileIds`; `{"$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}`. An `img`, a document's images among them, loads lazily in the box its `width` and `height` name, 16:9 without them. `styles` lists release CSS files. A route that fails starts the App as usual, and the Site document names why.
 
 ```json
 {

package/guide/sites/runtime.md

@@ -1,6 +1,6 @@
 # The App runtime on a Site
 
-What the App runtime does differently on a Site's page.
+What the App runtime does differently on a Site's page. Everything else is as in an App, [Local first](apps/local-first) included: House serves a Site's first screen as HTML from its [Entry Data Contract](sites/entry-data-contract) before the App starts, so a Site's page draws no loading state either.
 
 A History revision or a Document's `change` written by a Site gives its `author` as `{ kind: 'site', id, name }`. `observe('member')` answers `null` on a Site, and a Document's `change` is `null` there, since the Provider delivers no time.
 

package/guide/skills/house-onboarding.md

@@ -16,7 +16,7 @@ Run `wayfinder` to chart the map; this page adds only what is House's. `wayfinde
 
 ## Keep the plan
 
-- Keep the map as one `wayfinding-map` and its tickets as `wayfinding-ticket` documents in My Room, which `list_rooms` marks with `my_room: true`. Chart the map even when the way looks clear: My Room's map is how House knows onboarding ran.
+- Keep the map as one `wayfinding-map` and its tickets as `wayfinding-ticket` documents in My Room, which `list_rooms` marks with `my_room: true`, each declaring `type: wayfinding-map` or `type: wayfinding-ticket` in its frontmatter: a field named for the type makes no map. Chart the map even when the way looks clear: My Room's map is how House knows onboarding ran.
 - Keep decisions about the account, billing, runtime or credentials in the Private Room, `/rooms/private`.
 - Make the App for your User's goal a ticket.
 

package/guide/skills/prototype-app.md

@@ -16,13 +16,13 @@ In the Room the User names, or My Room when they name none, which `list_rooms` m
 - **Destination:** the App the User asked for, built and published.
 - **Notes:** this map's tickets do the work they name; the App's address and `a_` reference once the prototype is published.
 - **Tickets**, each blocked by the one before:
-  1. Prototype, `kind: task`: build a prototype and publish it as the App's first release.
-  2. Design decision, `kind: grilling`: the User's decision on the prototype's design.
+  1. Prototype, `kind: task`: three design variants in one prototype, published as the App's first release.
+  2. Design decision, `kind: grilling`: the variant the User picks, with their edits.
   3. Build, `kind: task`: run [`build-app`](skills/build-app).
 
 ## 2. Publish the prototype
 
-Claim the first ticket. Build the prototype as [Build an App](apps/build) says: its pages, their look and their flow, just enough for the User to judge the design.
+Claim the first ticket. Build three variants as [Build an App](apps/build) says, each a distinct visual direction (type, colour, layout, tone), not three shades of one. Each draws every main page with real-looking content, and a switcher on the page moves between them. Build only pages, their look and their flow: no tests, no data model, no reviews. Before publishing, look at each variant at phone and desktop width and redo any that looks generic or broken.
 
 Publish it as a new App, which creates it:
 
@@ -33,7 +33,7 @@ Write the App's address and reference into the map's Notes, resolve the ticket w
 
 ## 3. Record the User's decision
 
-Claim the second ticket and ask the User to open the prototype and decide on its design: keep it, or what to change. A change they ask for before deciding is a new prototype release in the same App: `npm run publish` without `--name`, or `publish_app_zip` naming the App. Resolve the ticket with their decision in their words; never decide for them.
+Claim the second ticket and ask the User to open the prototype and pick one variant, naming any edits or pieces to take from the others. Publish the chosen variant with those edits, without the switcher, as the next release of the same App: `npm run publish` without `--name`, or `publish_app_zip` naming the App. Repeat with each round of edits until the User keeps it. Resolve the ticket with their decision in their words; never decide for them.
 
 ## 4. Build
 

package/owner-rules-earlier.json

@@ -5,5 +5,6 @@
   "ac814a2197038f037b657bb719340395f89f319ac9fcdd386629c3fe2cec68f1",
   "29951ee394aad9979eecfed3e5dc32c2c86e2226b6a380db5dbd4f305f4d1156",
   "b99799a2fcddcb99e6ac14acc8d7a92a9f8f69b53f6b41edbc6f8e978256c71a",
-  "d14166e300ce35455ca51ec4959c2bc77668e5cb7f890d2b89c4d2c1e02af6b5"
+  "d14166e300ce35455ca51ec4959c2bc77668e5cb7f890d2b89c4d2c1e02af6b5",
+  "e612bbaa90e41d60b9bcd0367a074b9735b9239c287e56fa1becc8364562a422"
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/skills",
-  "version": "0.1.0-c8c6b89992ea2",
+  "version": "0.1.0-c8d3aff1d8c5b",
   "description": "The upstream Skills agents.house serves its agents, verbatim, and the texts it writes for them: the Guide, its own Skills among the pages, and the Agent instructions",
   "license": "MIT",
   "type": "module",

package/set/code-review/SKILL.md

@@ -8,7 +8,7 @@ Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
 - **Standards**: does the code conform to this repo's documented coding standards?
 - **Spec**: does the code faithfully implement the originating issue / spec?
 
-Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings. Start every sub-agent with a fresh context window.
 
 The issue tracker should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`.
 

package/set/codebase-design/DESIGN-IT-TWICE.md

@@ -18,7 +18,7 @@ Show this to the user, then immediately proceed to Step 2. The user reads and th
 
 ### 2. Spawn sub-agents
 
-Spawn 3+ sub-agents in parallel. Each must produce a **radically different** interface for the deepened module.
+Spawn 3+ sub-agents in parallel, each with a fresh context window. Each must produce a **radically different** interface for the deepened module.
 
 Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
 

package/set/grilling/SKILL.md

@@ -25,6 +25,6 @@ Word each question so "yes" accepts your recommended answer.
 
 Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
 
-Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
+Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent with a fresh context window to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
 
 The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.

package/set/implement-spec/SKILL.md

@@ -12,6 +12,8 @@ The goal is the entire spec implemented on a single **integration branch**, with
 
 The tickets are not a list of steps. They are a **task graph** with blocking relationships between them. This means there is always a **frontier** of tickets which are ready to be grabbed.
 
+Start every subagent with a fresh context window.
+
 Communication to and from subagents should be sparse. Communicate primarily through **context pointers**: to the spec, tickets, research notes, and previous commits. Don't duplicate information already available via pointers.
 
 **Implementer subagents** should be run in the background where possible for maximum concurrency.
@@ -24,7 +26,7 @@ Communication to and from subagents should be sparse. Communicate primarily thro
 
 3. Create the integration branch. If the issue tracker closes work through PRs, or the user asks for one, open a draft PR after the first merge in step 5 (a branch with no commits ahead of main can't open one), marked as closing the spec and tickets.
 
-4. Use **implementer subagents** to implement each ticket, each in its own worktree on its own branch. Each implementer subagent:
+4. Use a fresh **implementer subagent** for each ticket, each in its own worktree on its own branch. Each implementer subagent:
    - confirms its worktree is based on the integration branch before starting, and resets onto it if not;
    - calls the Skill tool with `tdd` to build the ticket;
    - merges the integration branch tip into its own branch before reporting done
@@ -33,7 +35,7 @@ Communication to and from subagents should be sparse. Communicate primarily thro
 
 6. If this changes the **frontier** of available tickets, kick off more **implementer subagents** to work on the new tickets. This allows for maximum concurrency.
 
-7. Once all tickets are complete, call the Skill tool with `code-review` on the integration branch. Fix all issues raised by the code review in a single **implementer subagent**.
+7. Once all tickets are complete, call the Skill tool with `code-review` on the integration branch. Fix all issues raised by the code review in a single fresh **implementer subagent**.
 
 8. If a draft PR exists, mark it ready for review. Otherwise, resolve each ticket the way the issue tracker closes work, and report the integration branch.
 

package/set/improve-codebase-architecture/SKILL.md

@@ -24,7 +24,7 @@ This command is _informed_ by the project's domain model and built on a shared d
 
 Read the project's domain glossary (`GLOSSARY.md`) and any ADRs in the area you're touching first.
 
-Then spawn a sub-agent to walk the codebase. Don't follow rigid heuristics; explore organically and note where you experience friction:
+Then spawn a sub-agent with a fresh context window to walk the codebase. Don't follow rigid heuristics; explore organically and note where you experience friction:
 
 - Where does understanding one concept require bouncing between many small modules?
 - Where are modules **shallow**, with an interface nearly as complex as the implementation?

package/set/research/SKILL.md

@@ -3,7 +3,7 @@ name: research
 description: Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent.
 ---
 
-Spin up a **background agent** to do the research, so you keep working while it reads.
+Spin up a **background agent** to do the research, so you keep working while it reads. Start it with a fresh context window.
 
 Its job:
 

package/set/wayfinder/SKILL.md

@@ -112,7 +112,7 @@ User invokes with a loose idea.
 2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** (the way to the destination is already clear, the whole journey small enough for one session), you don't need a map. Stop and ask the user how they'd like to proceed.
 3. **Create the map** (label `wayfinder:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**.
 4. **Create the tickets you can specify now** as child issues of the map, then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Write cross-references in that pass too, with real ids: a placeholder `#<n>` auto-links to an unrelated issue. Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog: the **Not yet specified** section.
-5. **Fire the research subagents.** For each `research` ticket you just created, spin up a subagent that calls the Skill tool with "research" to resolve it in parallel, capturing its findings on a throwaway `research/<name>` branch with a context pointer from the ticket. Push the branch but open no PR: it is never merged.
+5. **Fire the research subagents.** For each `research` ticket you just created, spin up a subagent with a fresh context window that calls the Skill tool with "research" to resolve it in parallel, capturing its findings on a throwaway `research/<name>` branch with a context pointer from the ticket. Push the branch but open no PR: it is never merged.
 6. Stop: charting is one session's work; it hand-resolves nothing.
 
 ### Work through the map

package/upstream.json

@@ -1,7 +1,7 @@
 {
   "repository": "https://github.com/mattpocock/skills",
-  "commit": "59db609eb1e18aaf59b63284d0e52255aff0c63c",
-  "date": "2026-10-27",
+  "commit": "a496f5513d4a4cf889bc48e189e579f4b0bdf6aa",
+  "date": "2026-10-29",
   "skills": [
     "ask-matt",
     "code-review",

package/guide/apps/local-search.md

@@ -1,35 +0,0 @@
-# Local Search rules
-
-How `search` finds Documents and messages by words on the device.
-
-`search({ text, documents, collection, conversations, limit, after, total })` answers
-once, by words, from the full-text index the browser keeps with its local state, so it
-answers at once after a reload. There is no observed search.
-
-- **Declaration.** Only an App whose release declares Local Search searches; any other
-  App's `search` answers the never retryable `undeclared` refusal `search-undeclared`, its
-  `fields` naming `local_search`.
-- **What is found.** A Document by its field values, its sections' headings and text, its
-  preamble and its Path, and a message by its text, never a frontmatter key, a Room Draft,
-  a chat draft or a running turn's parts. Any word found ranks a hit, more found rank it
-  higher, and adjacent words higher still; case and the marks of Latin, Greek and
-  Cyrillic letters fold, English word forms stem, the last word also matches as the start
-  of a word unless the text ends with a space, and Chinese, Japanese, Korean and Thai text
-  matches by character pairs. There is no typo tolerance and no operator syntax.
-- **Narrowing.** `documents` is a Local Query filter, and `collection: true` leaves out
-  what each Room's `typedSelection` roots hold; `conversations` names conversations. All
-  apply before `limit`, which bounds each list, at most 1,000 whatever a search names. A
-  complete answer it cuts short names `next`, which `after` takes for the next window of
-  both lists. `total: true` adds `total`, each list's count. A word in very many Documents
-  ranks among a bounded set of them, the Documents of a rarer word of the search always
-  among them.
-- **Results.** `{ documents, messages, coverage }`, or the same with `pending` naming each
-  Room the search still waits for: show its hits, ask again, and never read pending as no
-  hits. `coverage` names the Rooms and conversations searched. Each list is ranked by
-  `score`, comparable only within it; ties come by `room`, then `path`, or by
-  `conversation`, then `identity`. A Document hit names its `room`, `path` and `type`, a
-  message hit its `conversation` and `identity`; `matches` maps each word of the search
-  to the parts it was found in: `fields`, `sections`, `preamble`, `path` or `text`. A hit
-  whose words were found carries `snippet: { part, text, at }`: the part's text around
-  the first word found, at most 80 characters on either side, and `at` that word's start
-  and end in `text`. Mark the words you show. A bad filter fails as a query does.

package/guide/reference/routine.md

@@ -1,17 +0,0 @@
-# Routine
-
-How a Routine document in the Private Room is written, one for each Room it serves.
-
-Routine, `/rooms/private/rooms/<room-handle>/routines/<name>.md`, serving the Room `<room-handle>` names: `description`; `input`, a text saying what to send, empty if nothing; and `agent`, the identifier of the one of your User's current Agents it starts. The body is the instruction, which never leaves the Private Room. Writing it needs your User's write in that Room. House writes its card, the description, input and Agent, at `/rooms/<room-handle>/house/routines/<name>.md`, where every member reads it, and refuses a name a card there already holds as `routine_name_taken`. A Routine a second Room needs is a copy under that Room's handle. Anyone who writes that Room asks it with `send_routine_request` naming the card, or names the `agent` with their own words, as the Agent's Trust level in that Room allows: under Any request, the default, either starts at once; under Routines only the card starts at once and own words are refused `own_text_not_admitted`; under Approve each either waits for the Agent's owner to approve it. Its owner sets the level on the Agent's House page; the owner, their own agents and their Private Room's Triggers start it at once at every level, a Trigger of any other Room asks as that Room's writers do, and `inspect` on a Room root names the Agents you may ask there with their levels. A Routine Request's input is text the Agent reads, and House checks no shape. Mail your conversation sends with `send_mail` and a request it sent reaches the conversation that request started at once under Any request; below it, `send_mail` answers `waiting: true` and the mail waits for that Agent's owner, and a declined one comes back to you as House's message saying so. That conversation's mail always comes back to yours. A request's run is the first turn of the conversation it starts: during that turn the Agent names the document it wrote in the request's Room as the request's result with `set_request_result`, and the turn's end finishes the request. The conversation stays active until it is Done, which `mark_done` sets at the end of a turn and which nothing undoes, so mail reaches it after its run.
-
-A Trigger's `message` action puts its `text`, a link to what matched and its files into the active conversation, one not Done, its Routine started from that Room for what the Event is about: the chat of a customer's `inbox-message`, the matched document or item, or the Trigger for a `cron` clock. Its Event shows `continued` with that `request`; with none, it starts the Routine as a `routine` action does, `requested`. A conversation waiting for approval refuses it, `refused` with `conversation_waiting`. The Agent reads a customer's message as a customer's words, one from a Trigger of its owner's Private Room as the owner's instruction, and any other as what matched, never an instruction. A `routine` action starts a new request on every Event. A `done` action marks Done every active conversation a request of its Trigger's Room started for the Event's document, whoever owns its Agent, but one waiting for approval, which stays for its owner to approve or decline; its Event shows `marked` with their number, `conversations`, 0 when there are none, as on a `cron` clock, whose Event names no document.
-
-```markdown
----
-description: Summarize a thread in five bullets.
-input: The thread to summarize, as a ref or pasted text.
-agent: 019a0000-0000-7000-8000-000000000001
----
-
-Read the thread and write five bullets under summaries/.
-```