@agentshouse/skills 0.1.0-c262ec29db5e3 → 0.1.0-c279efd7eb4df

package/agent-instructions.json

@@ -4,7 +4,7 @@
     "Work with House through the `house` CLI, `house <tool> '<arguments as JSON>'`: `house --help` lists the Tools and `house help <tool>` names a Tool's arguments."
   ],
   "routing": [
-    "Read with `shell` and `inspect`. Write with `files_batch` and `records_append`.",
+    "Read with `shell` and `inspect`. Write with `files_batch`; `records_append` adds a record from one of your Sources.",
     "For anything else, `find_command`, then `run_command`.",
     "Optional per-Room instructions: `/rooms/private/rooms/<handle>/AGENTS.md`."
   ],

package/guide/apps/build.md

@@ -2,7 +2,7 @@
 
 How to build an App over your User's Rooms and publish it, one page per step.
 
-An App is a web page over your User's Rooms, for your User and whom they share it with (`shares/create`). House serves the built files and gives the page the App runtime, which holds every bound Room in the browser and syncs it with House. There is no server, backend or House API of yours to call.
+An App is a web page over your User's Rooms, for your User and whom they share it with (`shares/create`). House serves the built files and gives the page the App runtime, which holds every bound Room but a Search-level one in the browser and syncs it with House. There is no server, backend or House API of yours to call.
 
 - [Design an App](apps/design)
 - [Start an App](apps/start)

package/guide/apps/chat.md

@@ -21,10 +21,9 @@ Or mount it as the Chat button, which takes no element:
 `const button = await houseBridge.chat.mountButton(options)` draws House's dot at the
 window's bottom-right corner, which counts what asks the User or, while nothing does, the chats
 that replied since the User opened them, and breathes while a turn runs; pressing it opens the
-Chat in a sheet above the page, and pressing it again hides it. With `agent` among the options
+Chat in a sheet above the page, and a second press hides it. With `agent` among the options
 the dot's first press opens it on a new chat with that Agent instead of a chat kept from an
-earlier visit, and later presses reopen the chat it last showed; the sheet stays hidden until
-the first press. The dot stays in view over the
+earlier visit, and later presses reopen the chat it last showed. The dot stays in view over the
 sheet, which the User moves, resizes up to the window's edges and lets fill the window, and
 whose list, closed at first, widens it to the left by the list's own width; the page under it
 never changes, so leave nothing of the page to make room for it.
@@ -32,7 +31,7 @@ never changes, so leave nothing of the page to make room for it.
 `{ agent }`, or as it was with no target, and with `docked: true` docked at full height along
 the window's right edge; `button.hide()` hides it, keeping its chat, scroll and typed text;
 `button.update(options)` and `button.unmount()` work as for a page, with `onOpen` and
-`onLink`. To open on text written in, write it as the chat's draft through the runtime's
+`onLink`, though a Room document's link opens House in a new tab with that chat. To open on text written in, write it as the chat's draft through the runtime's
 `chatDraft` first, keyed `new:<agent>` for a new chat. In the sheet the input's + holds This
 page, which attaches the page's Page metadata to one message: a new chat's first message starts
 with it ticked. Mount one button per page.

package/guide/apps/content-safety.md

@@ -16,4 +16,6 @@ from a 360 pixel wide viewport to a desktop.
 Its strings are English only, dates and numbers follow the browser locale, and content is
 never translated. Light and dark themes come from CSS custom properties, defaulting to the
 browser's preference and respecting an App's override. What an agent adds carries none of
-these promises by itself. Data lives only in the App Creator's browser and the Provider.
+these promises by itself. The App keeps no data of its own anywhere: its data lives in
+its Rooms, at the Provider and on every device that holds them, and the
+App's code sends it out only to the external origins its manifest declares.

package/guide/apps/design-functions.md

@@ -5,6 +5,6 @@ Which part of House does each kind of an App's work, and what each run costs.
 - **The page** reads and writes the bound Rooms on the device, offline too, and runs only while someone has it open ([Local first](apps/local-first)).
 - **An App function** runs on House's servers when a Trigger of its Room fires, with no page open and no model. It reads and writes that Room and calls the services `external_origins` lists, within <function-time> and <function-memory> a run. It does what a script can: computing, filing, copying, counting, scheduling, calling a service ([App functions](apps/functions)).
 - **An Environment function** is a script your User kept for one of their computers, which Kit runs there as them. It does work that needs that computer, its files or its logins. A Trigger of their Private Room, their Run now or `environments/functions/run` starts one; a Trigger of any other Room never does ([wizard](skills/wizard)).
-- **An Agent function** starts a conversation of one of your User's Agents, which reads, judges and writes in minutes rather than milliseconds. Every run spends your User's own provider budget, and nothing bounds how many a Room's Triggers start. It does what needs judgment: reading a message, answering it, deciding what a document means ([Agent function](reference/agent-function)).
+- **An Agent function** starts a conversation of one of your User's Agents, which reads, judges and writes in minutes rather than milliseconds. Every run spends your User's own provider budget, and House sets no allowance on these runs: one Trigger acts on at most <trigger-events-per-hour> Events in a UTC hour, so a Room's Triggers together can still start many. It does what needs judgment: reading a message, answering it, deciding what a document means ([Agent function](reference/agent-function)).
 - **A job that needs judgment in one step** splits: an App function does the rest, and an Agent function only that step, writing its answer into the Room, where a Trigger hands it on to the App function ([Agent function](reference/agent-function)).
-- **With no page open**, work happens only through a Trigger whose action notifies someone or runs one of these ([Triggers](reference/triggers)).
+- **With no page open**, nothing of the App runs by itself: a Trigger whose action notifies someone or runs one of these starts its work ([Triggers](reference/triggers)).

package/guide/apps/design-look.md

@@ -6,6 +6,6 @@ What House draws around an App's page, and what the App sets for its look.
 - **The Chat**, where the page mounts it, draws in the App's frame: the Chat button's dot in House's look, and the Chat in its own, which the `--chat-*` properties theme ([The Chat](apps/chat)).
 - **The design system's tokens**: mdui's `style.css` holds House's design tokens as CSS custom properties, light and dark: its greys, type sizes, spacing, radii and motion. An App built on them looks like House; changing them gives it a look of its own. The design system itself is not published, so mdui's tokens are how an App takes it.
 - **Light and dark**: House's screens around the page, such as its wait until the page shows its place, follow the device's light or dark setting, as `prefers-color-scheme` does.
-- **The top colour**: declare the page's top colour as `theme_colour` in `app.json`, and `theme_colour_dark` where the dark one differs ([App manifest](reference/app-manifest)). An installed App's title bar and a phone's top strip take it, and House's white or near-black ground without it.
+- **The top colour**: declare the page's top colour as `theme_colour` in `app.json`, and `theme_colour_dark` where the dark one differs ([App manifest](reference/app-manifest)). An installed App's title bar and a phone's top strip take it, and House's white or near-black ground without it. A page with its own light and dark switch calls `bridge.setTab({ scheme })` with `'light'` or `'dark'` when it shows one over the device's setting, and `null` when it follows the device, so they take that scheme's colour.
 - **The icon** is the owner's setting, never the release's: one image in the browser tab, the panel and on a home screen. It is the App cube in the App's colour until one is set, then a generated one from one to four colours or the owner's own square PNG or SVG, through `apps/tab-icon/set`; `bridge.setTab({ title, icon })` changes the open tab's title and icon until the next load.
 - **No focus mark**: House's own screens draw none, and [An App's page](apps/page) says how a page removes the browser's ring.

package/guide/apps/local-first.md

@@ -3,14 +3,14 @@
 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, but a Search-level Room, which an App shows only as the rows [`queryHouse`](apps/query-house) asks for, never offline. `query` and `observe` answer from the device and never wait on the network; `search` asks House ([Search rules](apps/search)).
-- Draw from `observe` at once, 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.
+- Draw from `observe` at once; an observation hears each later change by itself, so never poll, refetch or subscribe to House. An answer is `{ pending }` while a Room it reads has not reached this device or been prepared on it: draw the page without those documents; keep the empty state for a complete answer. `rooms` answers once the runtime knows the Rooms the page reaches. Offer binding a Room when it is empty while the sync status's `providerUnreachable` is false and `observe('connection-refusal')` answers `null`; any other empty list says only that nothing can be listed yet.
 - Show no loading state: draw the last state the device holds. A wait shows only after an act the User pressed whose answer comes from outside the stream, such as `bridge.callExternal`, until it arrives.
 - Write optimistically: write a Room Draft, then `save`. The change shows in every query at once as a Pending Change and reaches House when it can. `save` refuses at once, with its `code`, a change that is `stale`, `changed-underneath` or against the schema: say so and keep the form. After `changed-underneath`, draw the joined Room Draft and its `marks` ([Room Drafts](apps/room-drafts)).
 - Show what the runtime reports: `observe('queue', room)` lists changes House has not confirmed yet, and `observe('sync-status')`'s `attentionRequired` lists each change House refused, returned as a Room Draft with why, to save again or discard.
 - Keep what the User types in the Room Draft (`roomDraft.write`) as they type; it survives a new release, 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.
+- Offline, all of this works for held Rooms and saves wait; `bridge.onStatus` reports `offline`: say so quietly.
 - A Room your User holds at the Open level locks once the browser has been offline 2 minutes, and from the moment it opens until House confirms the access. While it is locked, `rooms` lists it `locked: true`, a query that does not name it leaves it out, one naming it answers `{ pending }` with `awaits: 'unlock'`, and every other read and write naming it, `save` included, answers the code `room-locked` and keeps nothing. Draw it locked until then and keep what the User types; what was saved before is sent then.
 - An outside service is reached only at the origins `app.json` lists in `external_origins`, directly or through `bridge.callExternal`, sent by House's server. A call whose `room_ref` names a Room bound in a `write` slot carries that Room's Service key for the origin, unseen by the page; any other carries none. Through a Room holding no key for the origin it is refused `not_found` naming the `origin`: tell the person its owner or a manager enters the key under Connected in the Room's Settings, which no App opens.
 - The page's own storage is a disposable cache, the Room the only durable home of the App's data; handle any code or value you do not know by its `code` ([Refusals](apps/runtime-refusals)).

package/guide/apps/local-query.md

@@ -7,9 +7,9 @@ hears it again only when it changes, keeping every unchanged Document the same o
 a component can tell what changed by identity. `{ documents, coverage }` or `{ groups,
 coverage }` is complete for the Rooms its `coverage` names, and `{ pending }` names each
 Room not yet acquired, prepared or unlocked, `[{ room, awaits }]`: never read it as empty,
-draw it as loading and observe the query to hear the complete answer. A query is data:
+draw them absent and observe the query to hear the complete answer. A query is data:
 
-- **Filter.** `rooms` names Room locators and defaults to every Room. `types` names MD
+- **Filter.** `rooms` names Room locators and defaults to every bound Room but a Search-level or locked one, which `pending` omits. `types` names MD
   Types, and `any` names untyped Markdown Documents. `pathPrefix` is a directory: `notes`
   keeps `notes/a.md` and not `notes2/a.md`; `outside` names directories whose contents stay
   out, `['house']` leaving `house/` out; `folder` keeps only what lies directly in it.

package/guide/index.md

@@ -4,6 +4,8 @@ Where House's guides and formats start: `guide/open` opens a page by its `path`
 
 House keeps Markdown files in Rooms, which your User shares with other people and their agents.
 
+With the Kit, each Room your Environment keeps is also a Local copy: a Git repository at `local-copies/rooms/<room_ref>` in its workspace, `~/.agents/house` unless moved. `house fetch` records House's changes on `refs/house/received` in each, and `house push`, run in one, sends its commits.
+
 - `apps/`, building an App over your User's Rooms: [Design an App](apps/design) first, then [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).
 - `agent-functions/`, the Agent function an Agent takes a plan's tickets by, written for the plan's Room and naming that Agent as [Agent function](reference/agent-function) says: [Work on ticket](agent-functions/work-on-ticket).

package/guide/reference/access-level.md

@@ -2,7 +2,7 @@
 
 How much of a Room a grant or a Share lets its holder do with its text, and where.
 
-Access level, `level` on a Room grant or a Share’s Room item, each level including the one before it: `search`, the Search level, reaches the Room through `shell` and `inspect` alone, each reply at most <mcp-read-size> of the Room’s text, with no copy anywhere; `open`, the Open level, also opens the Room in browser Apps while the browser is online, and acts as `search` everywhere else; `keep`, the Keep level, also copies the Room to the devices that keep it, offline included, and is the one `export` needs. Apps need `open` or `keep`.
+Access level, `level` on a Room grant or a Share’s Room item, each level including the one before it: `search`, the Search level, reaches the Room through `shell` and `inspect`, each reply at most <mcp-read-size> of the Room’s text, and for App code only through the pages of rows [`queryHouse`](apps/query-house) asks House for, which no agent reaches, with no copy anywhere; `open`, the Open level, also opens the Room in browser Apps while the browser is online, and acts as `search` everywhere else; `keep`, the Keep level, also copies the Room to the devices that keep it, offline included, and is the one `export` needs. An App that reads the Room on the device, through `query` and `observe`, needs `open` or `keep`.
 
 ```json
 { "room_ref": "r_ab12.1", "level": "open", "operations": ["write"] }

package/guide/reference/schema.md

@@ -2,7 +2,7 @@
 
 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 documents' values; `$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; `title` on a field, the label a document shows for it, its key when it has none; `contentMediaType: text/markdown` on a string, Markdown text under its own heading; and `member_document: true` on one type, whose documents name their member with `member`, a User Identifier from `rooms/members/list`. 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. `files_batch` creates or replaces the whole text, and may rewrite the documents a change breaks in the same call.
+Schema, `/rooms/<room>/settings/schema.yaml`: one JSON Schema in YAML. Each top-level key is an MD type holding the schema of its documents' values; `$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; `title` on a field, the label a document shows for it, its key when it has none; `contentMediaType: text/markdown` on a string, Markdown text under its own heading; and `member_document: true` on one type, whose documents name their member with `member`, a User Identifier from `rooms/members/list`. 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. `files_batch` creates, patches or replaces it, House checks the whole text it leaves, and the same call may rewrite the documents a change breaks.
 
 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. Every Room also knows the [Inbox types](reference/inbox-types) and the [Wayfinding types](reference/wayfinding-types) without declaring them.
 

package/guide/sites/first-load.md

@@ -13,3 +13,4 @@ A phone on a slow link pays for every byte before the first screen, so what the
 - **At most two font families**, the Site's own, their files in the release.
 - **The first view within the bound** the publish warns at. The first view is the entry document, its scripts and stylesheets and what they import statically, compressed as House stores them. A first view past the bound, or no Entry Page for `/`, never stops a publish: its answer and `sites/list` name each in `warnings` by its `code`, `first_view_heavy` with its `bytes` and `bound`, and `entry_page_missing`. Fix them before the next publish.
 - **Read `first_load` in `sites/list` after each publish.** House loads the Site once more, cold, as a phone on a slow link, and answers `{ first_content_ms, largest_content_ms, at }` for the release or publication it serves: `null` before that figure, when that load failed or where the Building times no Site. A figure that grew points at what that release added.
+- **A common Site from a Site Template**, built this way, where `templates/list` answers them: `site-landing`, one page whose form sends each lead as a Submission; `site-services`, a page that lists each document of its Room's `services/` folder as one service; and `site-shop`, a shop on the recipe of [Payments with Stripe](sites/payments-stripe). Make the Site with one `templates/use` of it, at the address `templates/list` answers, with a `site_name` and a `room_name`: the Site gets its own App and a new Room holding the Template's schema and Starter content, keeps no link to the Template, and you change its App as any other. It binds that Room in every slot but one that declares `intake: true`, which publishes it. `site-landing`'s one slot declares it, so the Room is the Site's Intake Room and none is published: turn on Notify me with `sites/notifications/set` and each lead reaches your User on the channels they chose. `site-shop`'s `orders` slot declares it: set up its Intake Room as that recipe says.

package/guide/sites/payments-stripe-3.md

@@ -6,6 +6,7 @@ The `paid` function, which marks an order paid once Stripe's signed webhook says
 
 ```js
 const STRIPE = 'https://api.stripe.com';
+// Stripe's libraries refuse a signature over five minutes old, which stops a replayed delivery
 const TOLERANCE_SECONDS = 300;
 
 export default async (event, house) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/skills",
-  "version": "0.1.0-c262ec29db5e3",
+  "version": "0.1.0-c279efd7eb4df",
   "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",