@agentshouse/mdruntime 0.1.0-cec6690d5712e → 0.1.0-cedb03eaa48b6

package/AGENTS.md

@@ -1,299 +1,305 @@
 # Instructions for the App Creator's agent
 
-These instructions address an agent in an environment with Git. Obtain the
-App Repository, change it, build, and push. They are documentation, not enforcement.
+These instructions address an agent in an environment with Git: obtain the App Repository,
+change it, build, and push. They are documentation, not enforcement.
 
 ## The MD Runtime API
 
-App code reaches the MD Runtime through the remote client. The surfaces are
-Rooms, Query, Search, Observe, Types, Room Draft, Save, History, Call, Reached, Log,
-the reported persistence answer, reauthorization, conversation, the chat draft,
-and Presentation State. Sync Status, the Service Mode, the storage-loss
+App code reaches the MD Runtime through the remote client. The surfaces are Rooms,
+Query, Search, Observe, Types, Room Draft, Save, History, the binary file reads, Call,
+Reached, Log, the reported persistence answer, reauthorization, conversation, the chat
+draft, and Presentation State. Sync Status, readiness, the Service Mode, the storage-loss
 statement, the deployment facts and the signed-in member are observations only.
 
-The host attaches each port with its reach, and every member and observation
-answers within it: a Room outside it answers as one the replica does not hold,
-Rooms lists only the Rooms reached whole, a Room reached for single Documents
-shows only those Documents and the Types of the models that govern them, and
-without conversations the conversation members, the chat draft and the
-conversation observation hold none.
-A change of the reach reaches every open observation as its new value, a query
-keeping every unchanged Document the same object.
-
-Every `observe` resolves, once its first value has arrived, to a handle:
-`current()` is the latest complete value, `subscribe(listener)` hears each later
-value whole and returns its unsubscribe, and `close()` ends the observation.
-Closing the port ends every handle and rejects every pending call and
-observation; a client that reconnects observes again.
-
-`observe('agents')` answers every Agent a new conversation can go to, each
-`{ identity, name }`, whether or not it has a conversation yet.
-Each conversation the Provider's conversation list names is held complete in the
-browser. `conversation.list()` and `observe('conversations')` answer each with its
-Agent's identity and name, its name, created and finished times, last outcome and live
-`state`: `asking` while a question waits, `working` while a turn runs, else `idle`,
-and `started`, when the running turn began, or `null`.
-Observe one with `observe('conversation', id, { limit })`: the view
-holds its latest `limit` messages, or all of them, oldest first, its chat
-draft, and what the Provider streams for it whether or not anything views it:
-the running `turn` with its message parts and its context in use and window, the
-open questions, the process state, and the CLI's commands and options. These live
-only in memory: the message accepted under the turn's id replaces the running turn,
-and none of them is stored or searchable.
-`chatDraft.write` and `chatDraft.discard` keep what the App Creator composes;
-sending it is a Provider Action that needs the Provider reachable and is never
-queued.
-
-Each Room in Rooms lists its `attachments`, the files the Provider holds for it
-that its Documents link by the Provider's reference, ordered by `reference`,
-each with `name`, `byteLength`, `mediaType` and the Provider's own entry as
-`entry`. They are as the Provider last declared them and hold no bytes;
-open one through the Provider Action that serves it.
-
-Rooms, Query, Search, Observe, Types, Room Draft, Save, and Reached never
-touch the network.
-History and Call go to the Provider through the Adapter. Call takes the Action names
-the Adapter declares; any other name answers `undeclared` without reaching the
-Provider. A Call result whose
-effect the Provider places in a Room carries `at`, that Room and Room Version;
-`reached(room, roomVersion)` answers whether the Room's confirmed state has
-reached it, and the MD Runtime keeps refreshing that Room until it has;
-`reached(room, roomVersion, path)` answers whether the held confirmed copy of
-that document was written at a later Room Version. Each History revision
-names its author, `{ kind: 'user', id }` or `{ kind: 'site', id, name }`.
-History of a Path no current document holds answers the removed document's
-revisions with `deleted: true`, newest first; that revision is what a link to
-the Path opens. Every
-member of the
-client is asynchronous. Results are detached snapshots. Nothing in this
-surface returns the authorization, performs a request the App's code
+The host attaches each port with its reach, and every member and observation answers
+within it: a Room outside it answers as one the replica does not hold, Rooms lists only
+the Rooms reached whole, a Room reached for single Documents shows only them and their
+models' Types, and without conversations the conversation members, chat draft and
+observation hold none. A changed reach reaches every open observation as its new value.
+
+Every `observe` resolves, once its first value arrived, to a handle: `current()` is the
+latest complete value, `subscribe(listener)` hears each later value whole and returns its
+unsubscribe, and `close()` ends it. Closing the port ends every handle and rejects every
+pending call and observation; a reconnected client observes again.
+
+`observe('agents')` answers every Agent a new conversation can go to, each `{ identity,
+name }`, with a conversation yet or not. Each conversation the Provider lists is held
+complete in the browser. `conversation.list()` and `observe('conversations')` answer each
+with its Agent's identity and name, its name, created and finished times, last outcome,
+live `state` (`asking` while a question waits, `working` while a turn runs, else `idle`)
+and `started`, when the running turn began, or `null`. `observe('conversation', id, {
+limit, total: true })` holds its latest `limit` messages, at most 1,000, oldest first,
+`total` their count, and `next` while older ones exist, which `after` takes, there or in
+`conversation.read(id, { limit, after })`, for the window before; its chat draft; and,
+only in memory, what the Provider streams whether or not anything views it: the running
+`turn` with its parts and its context in use and window, which the message accepted under
+the turn's id replaces, the open questions, the process state, and the CLI's commands and
+options, none stored or searchable. `chatDraft.write` and `chatDraft.discard` keep what
+the App Creator composes, and `chatDraft.prepend(conversation, draft)` puts a message that
+came back ahead of the chat draft as it stands, its text on a line before and its files
+first, so what another tab typed meanwhile stays: never write back a draft read before; sending it is a Provider Action that needs the Provider
+reachable and is never queued. A new conversation's chat draft is keyed `new:<Agent
+identity>`: no conversation list removes it, a retired Agent's goes, and the first answer
+to `conversation.create({ agent_id, operation_id })` moves it to the created conversation,
+where `conversation.send(conversation)` sends it; a replay of that create moves nothing.
+
+Presentation State is one value per App, kept in the browser and shared by its tabs:
+`presentation.read()` answers it, `null` before anything is kept,
+`observe('presentation')` hears it whole, `presentation.write(value)` replaces it whole,
+and `presentation.edit(members)` sets each member named, or removes one named `null`, in
+the state as it stands, so tabs changing different members never lose each other's change:
+never write back a value read before. Each rejects when the browser does not keep the
+change, and no tab sees it then.
+
+A binary file at a Path is a binary Path entry. Query lists it by `path`, and History each
+of its revisions, with its `binaryFile` record and never its bytes: `{ state: 'accepted',
+revision, path, fileRef, byteLength, mediaType, sha256 }`, or, from a Save until the
+Provider accepts it, `{ state: 'pending', localId, path, byteLength, mediaType, sha256 }`.
+Write one with a Room Draft whose only part is `file: { blob }`, the `Blob`'s `type` its
+media type: Save keeps the bytes in its Pending Change, offline too, and acceptance gives
+the record the Provider's revision. Move or remove one as a Document, a pending one too,
+its bytes following; once its Pending Change has gone to the Provider, Save refuses that
+as `unknown-revision` until it is accepted. `binaryFile.read(room, path, revision?)`
+answers a pending record's saved bytes, or asks the Provider on every read of an accepted
+one or a History revision, a removed file's last included, keeping nothing. Text, a Record
+attachment or a conversation message may name a file by its `fileRef`; read it with
+`binaryFile.readReference({ fileRef, referrer })`, the `referrer` the Provider gave beside
+it, or `{ room, path }` of the document whose text names it. Both answer
+`{ kind: 'binary', blob }` or a refusal or failure.
+
+Rooms, Query, Search, Observe, Types, Room Draft, Save, and Reached never touch the
+network; History, the binary file reads and Call go to the Provider through the Adapter.
+Call takes the Action names the Adapter declares, any other answering `undeclared`. A Call
+result whose effect the Provider places in a Room carries `at`, that Room and Room
+Version: `reached(room, roomVersion)` answers whether the Room's confirmed state has
+reached it, refreshing the Room until it has, and `reached(room, roomVersion, path)`
+whether the held copy of that document was written later. A History revision names its
+author, `{ kind: 'user', id }` or `{ kind: 'site', id, name }`; History of a Path no
+document holds answers the removed document's revisions, newest first, with `deleted:
+true`, which a link to the Path opens. Every member is asynchronous and every result a
+detached snapshot; nothing returns the authorization, performs a request the App's code
 composes, or exposes the browser store.
 
 Every refusal and failure carries `code` and `retryable`: each Call and History answer
-other than its result, a refused Save or Room Draft write, a returned Room Draft's
-reason, a Room's refusal and the Connection Refusal, and every error a member rejects
-with, beside its message. A Provider refusal carries the Provider's own `retryable`.
-Every code and every value the API answers is open: handle one you do not know by its
-`code` and `retryable`.
-
-Read the deployment facts with `observe('deployment-facts')`. Interpret the
-opaque value using the host's contract.
-
-`observe('member')` answers who uses the App: the User the Provider signed in,
-`{ kind: 'user', id, name }` in the shape of a change's `author`, so a Document
-whose `change.author.id` equals its `id` is that User's own. It is `null` until
-the Provider first names one, and where it names none, such as a Site. The
-MD Runtime keeps it with the Local Replicas, so it answers offline once known,
-and every port hears the next member the Provider names; signing out answers
-`null`, then ends the observation with the authorization. It is the only way App code learns who
-uses it.
-
-The in-memory Adapter at `@agentshouse/mdruntime/memory` is for tests and
-ships in no bundle.
+other than its result, a refused Save or Room Draft write, a returned Room Draft's reason,
+a Room's refusal, the Connection Refusal and every error a member rejects with, beside its
+message, a Provider refusal with the Provider's own `retryable`. Every code and value is
+open: handle one you do not know by its `code` and `retryable`. Only a tag telling which
+fields a value carries, such as `kind`, is closed: keep a branch for one you do not know.
+A model with no usable types answers `types: null`.
+
+Read the deployment facts with `observe('deployment-facts')`, an opaque value the host's
+contract interprets. `observe('member')` answers who uses the App, the only way App code
+learns it: the User the Provider signed in, `{ kind: 'user', id, name }` like a change's
+`author`, so a Document whose `change.author.id` is its `id` is that User's own; `null`
+until the Provider first names one, and where it names none, such as a Site. It is kept
+with the Local Replicas, answers offline once known, and every port hears the next member
+named; signing out answers `null`, then ends the observation with the authorization.
 
 ## Local Query rules
 
-`query(q)` answers once from local state; `observe('query', q)` holds the whole
-result and hears it again only when it changes, keeping every unchanged Document
-the same object, so a component can tell what changed by identity. A query is
-data:
-
-- **Filter.** `rooms` names Room locators and defaults to every Room. `types`
-  names MD Types, and `any` names untyped Markdown Documents. `pathPrefix` is a
-  directory: `notes` keeps `notes/a.md` and not `notes2/a.md`.
+`query(q)` answers once from local state; `observe('query', q)` holds the whole result and
+hears it again only when it changes, keeping every unchanged Document the same object, so
+a component can tell what changed by identity. `{ documents, coverage }` or `{ groups,
+coverage }` is complete for the Rooms its `coverage` names, and `{ pending }` names each
+Room not yet acquired or prepared, `[{ room, awaits }]`: never read it as empty, draw it
+as loading and observe the query to hear the complete answer. A query is data:
+
+- **Filter.** `rooms` names Room locators and defaults to every Room. `types` names MD
+  Types, and `any` names untyped Markdown Documents. `pathPrefix` is a directory: `notes`
+  keeps `notes/a.md` and not `notes2/a.md`; `folder` keeps only what lies directly in it.
+  `paths` keeps only the Paths it names: read named Documents so, never from a list.
 - **Fields.** Every frontmatter value is named by JSON Pointer: `/status`,
-  `/shipping/city`, `~1` for a `/` and `~0` for a `~` in a key. A segment that
-  meets a list applies to every item and a number names one item. `where` names
-  pointers, ANDs them, and nests `$and` and `$or`; a pointer through a list holds
-  when 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 whether it contains the value. Missing, null and empty differ:
-  `$exists: false` keeps a missing field, `null` an explicit null, `''` empty
-  text and `$size: 0` an empty list. A date compares in calendar order and never
-  with a date-time. A reference compares by the Room Path it resolves to.
-  Untyped frontmatter, and a value under `oneOf` or a conditional, is plain
-  values. There is no text containment or regular
-  expression.
+  `/shipping/city`, `~1` for a `/` and `~0` for a `~` in a key. A segment that meets a
+  list applies to every item and a number names one item. `where` names pointers, ANDs
+  them, and nests `$and` and `$or`; a pointer through a list holds if any item satisfies
+  it. A bare value is equality; the operators are `$eq`, `$ne`, `$in`, `$nin`, `$gt`,
+  `$gte`, `$lt`, `$lte`, `$all`, `$size` and `$exists`. Equality on a list asks if it
+  contains the value. Missing, null and empty differ: `$exists: false` keeps a missing
+  field, `null` an explicit null, `''` empty text and `$size: 0` an empty list. A date
+  compares in calendar order and never with a date-time. A reference compares by the
+  Room Path it resolves to. Untyped frontmatter, and a value under `oneOf` or a
+  conditional, is plain values. There is no text containment or regular expression.
 - **Relations.** `hop: { field, types, where, pathPrefix }` keeps Documents whose
-  reference at pointer `field`, at any depth, points to a matching Document of the
-  same Room. `backlinks: { field, types, where, pathPrefix }` keeps Documents that a
-  matching Document of the same Room references. Each keeps a Document once.
+  reference at pointer `field`, at any depth, points to a matching Document of the same
+  Room. `backlinks: { field, types, where, pathPrefix }` keeps Documents that a matching
+  Document of the same Room references. Each keeps a Document once.
 - **Parts.** A Document query must `select`: `'all'`, or `fields`, `sections`,
-  `preamble`, `markdown`, `backlinks` and `change`, where `fields` is `'all'` or a
-  list of pointers and `sections` `'all'` or a list of names. Selected pointers
-  return the frontmatter holding only them, nested as written. A backlink names
-  the referring Path, MD Type and the pointer it came from as `field`. Room and Path always return; a Markdown
-  Document also returns its MD Type. A non-Markdown Document or binary link
-  target returns only Room and Path. An unselected part is absent. Select only
-  what a screen shows: a list that selects the Markdown hears every edit of it.
-- **Change.** `change` is `{ author, time }` of the Document's head revision as
-  the Provider last delivered it: `author` is `{ kind: 'user' | 'site', id, name }`
-  or `null` for a write the Provider made itself, and `time` is the Provider's
-  ISO 8601 change time. It is `null` where the Provider delivered no time, as at
-  a Site. An unsent edit or move keeps it, an unsent creation has none, and a
-  saved write takes the Provider's own once it is Accepted. A
-  Room's last change is its Document with the latest `time`.
-- **Order and groups.** `orderBy` sorts by `room`, `path`, `type` or `{ field }`
-  with TanStack DB's own options, and ties end with Room, then Path. `groupBy` by
-  `room`, `type` or `{ field }` answers `{ groups: [{ key, count }] }`, counted
-  over every match and ordered by `count` or a key. A sort or group takes only a
-  pointer that holds one value. `limit` bounds the Documents or the groups.
-- **Results and errors.** A result carries no Room Version: read freshness from
-  Rooms and Sync Status. An invalid query fails with the `code`
-  `invalid-query`, `unknown-type`, `unknown-field` or `wrong-kind`, naming where,
-  and never answers an empty result in its place.
+  `preamble`, `markdown`, `backlinks`, `change` and `fileId`, where `fields` is `'all'`
+  or a list of pointers and `sections` `'all'` or a list of names. Selected pointers
+  return the frontmatter holding only them, nested as written. A backlink names the
+  referring Path, MD Type and the pointer it came from as `field`. Room and Path always
+  return; a Markdown Document also returns its MD Type, and at most its first 1,000
+  backlinks: a query on the referring field reads the rest. A non-Markdown Document
+  returns only Room, Path and a selected `fileId`, and a binary Path entry its
+  `binaryFile` record too. An unselected part is absent. Select only what a screen shows:
+  a list that selects the Markdown hears every edit of it.
+- **Change and file ID.** `change` is `{ author, time }` of the Document's head revision
+  as the Provider last delivered it: `author` is `{ kind: 'user' | 'site', id, name }`, or
+  `null` for a write the Provider made itself, and `time` its ISO 8601 change time, or the
+  whole change `null` where it delivered no time, as at a Site. `fileId` is the Provider's
+  Stable File ID of the file at the Path, or `null`. An unsent edit keeps both, an unsent
+  move keeps the change and carries the file ID to the new Path, so a file ID that leaves
+  one Path for another is the same file moved, and an unsent creation has neither until it
+  is Accepted. A Room's last change is its Document with the latest `time`.
+- **Order and groups.** `orderBy` sorts by `room`, `path`, `type`, `folder` or `{ field }`
+  with TanStack DB's own options; ties end with Room, then Path. `groupBy` by `room`,
+  `type`, `folder` or `{ field }` answers `{ groups: [{ key, count }] }`, counted over every
+  match and ordered by `count` or a key. A sort or group takes only a single-value pointer.
+  `limit`, at most 1,000 whatever a query names, bounds the Documents or the groups, and a
+  result it cuts short names `next`: the same query with it as `after` reads the next
+  window, in the same order, ties included. `total: true` adds `total`, every match's
+  count. An observed window hears rows entering, leaving or changing, and `next`, `total`.
+- **Results and errors.** A result carries no Room Version: read freshness from Rooms and
+  Sync Status. `coverage` names each Room read as `{ room, generation, current }`,
+  `current` false while a newer copy of that Room is being fetched, and the queued changes
+  it includes as `overlay`, which a Save in the Room changes. An invalid query fails with
+  `invalid-query`, `unknown-type`, `unknown-field` or `wrong-kind`, never an empty answer.
 
 ## Local Search rules
 
-`search({ text, documents, conversations, limit })` answers once, by words, from
-local state, with MiniSearch at its default configuration. There is no observed
-search.
-
-- **What is found.** A Document by its field values, its sections' headings and
-  text, its preamble and its Path; a message by its text. Frontmatter keys, Room
-  Drafts, chat drafts and a running turn's parts are never found. There are no phrases,
-  word forms, typo tolerance or prefix matching.
-- **Narrowing.** `documents` is a Local Query filter: `rooms`, `types`, `where`,
-  `pathPrefix`, `hop` and `backlinks`. `conversations` names conversations. Both
-  apply before `limit`, which bounds each list; without it every hit returns.
-- **Results.** `{ documents, messages }`, each ranked by `score`, which compares
-  hits of one list of one search. A Document hit names its `room`, `path` and
-  `type`, a message hit its `conversation` and `identity`, and `matches` maps each
-  matched word to the parts it matched in: `fields`, `sections`, `preamble` or
-  `path`, or `text`. A hit carries no position; mark the words in the text you
-  show. An invalid filter fails with its Local Query error.
+`search({ text, documents, collection, conversations, limit, after, total })` answers
+once, by words, from local state, with MiniSearch's defaults. There is no observed search.
+
+- **Declaration.** Only an App whose release declares Local Search searches, its first
+  readiness waiting for its index; 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, with no phrases, word forms, typo tolerance or
+  prefix matching.
+- **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.
+- **Results.** `{ documents, messages, coverage }`, or the same with `pending` naming each
+  Room or conversation 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 matched
+  word to the parts it matched in: `fields`, `sections`, `preamble`, `path` or `text`. A
+  hit carries no position: mark the words you show. A bad filter fails as a query does.
 
 ## Room Draft, Save, and outcome rules
 
-The MD Runtime owns one Room Draft per Room and Path, shared by every App and
-tab. It is durable: it survives reload and navigation. A Room that Discovery
-stops listing takes its Room Drafts and its queue with it.
-Write a Room Draft with `roomDraft.write(room, path, revision, parts)`, naming
-the revision you read, or `null` when there was none, and every part it should
-now change: fields, sections and the preamble, or the whole Markdown, a
-creation, a move, or a removal. A part new to the Room Draft names its base,
-the value you showed when it was opened; the MD Runtime keeps a part's first
-base. A binary link target has a Room Draft too, for a move or a removal, with
-`null` as its base. A write or a discard from an older revision is refused as `stale` with
-the current Room Draft; read it and write again.
-
-Save takes one Room and the Room Drafts of it to save, each with its revision,
-validates locally, and on success appends one Change Batch to that Room's
-queue and removes those Room Drafts. It is refused with the `code` `stale`,
-`changed-underneath` naming each part whose base no longer matches the visible
-state, or a local validation rule, and then creates nothing and leaves every
-Room Draft in place. A directory move or removal is a move or removal part on
-each Document and binary link target beneath it, saved together.
-
-Outcomes follow the Provider's answer. An Accepted Change Batch stays in the
-queue, drawn over the confirmed layer, until the confirmed layer reaches the
-Room Version it was accepted at, and then leaves it. Conflicted and Rejected, an expired operation, and a change that no
-longer applies over the Room each leave the queue and return as Room Drafts on
-the Documents they changed, 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 attention
-until each returned Room Draft is saved again or discarded. A Change Batch
-keeps no outcome once it leaves the queue; `observe('queue', room)` shows each
-Pending one, and a returned Room Draft says why it returned. Transport
-failure and Provider unavailability keep work Pending and do not infer a
-rejection. A refusal the Provider marks retryable stays Pending until the reset
-it names; the MD Runtime retries the same Change Batch identity and payload and
-never infers an outcome from transport uncertainty. The MD Runtime never
-combines, reorders, or rebases.
-
-On a Site, every Save stays in the visitor's browser. Write grants and
-revisions do not refuse it, and its Pending Change shows in every query and
-across reloads until the browser's storage is cleared. It is never sent:
-`observe('queue', room)` shows it `local`, and Sync Status never waits on it.
-Once the Room changes so that it no longer applies, it leaves the queue and
-returns no Room Draft.
-
-`observe('service-mode')` answers the Provider's Service
-Mode, `open` or `write-halted`. While writes are halted, Save still succeeds,
-its Change Batch waits unsent, and the queue is submitted in order once the
-Provider reopens writes. An Action is never held: a write the Provider refuses
-for the halt returns that refusal to its caller. Show the Provider as read-only
-instead of retrying.
-
-## The neutrality rule
-
-No module outside an Adapter package imports, names, or special-cases a
-Provider. MD UI and every App reach data only through the client entry.
-
-## Content-safety rules
-
-The Provider authorization belongs to the Runtime host and is never readable
-by the App's code. The App's code reaches the network only at the external
-origins its manifest declares, empty by default, and the Provider enforces
-that set. Every request to the Provider itself goes through the MD Runtime.
-Rendered Markdown never executes scripts, renders raw HTML only for the
-details and summary elements, and loads images and other resources only from
-origins the Provider's policy allows.
-
-## Launch promises MD UI keeps
-
-MD UI uses semantic HTML, is fully operable from a keyboard with visible
-focus and labelled controls, and lays out from a 360 pixel wide viewport to
-a desktop. Its strings are English only, dates and numbers follow the
-browser locale, and content is never translated. Light and dark themes come
-from CSS custom properties with the browser's preference as the default and
-an App's override respected. What an App Creator's agent adds carries none
-of these promises by itself. Reading, querying and searching never wait for
-the network. Data lives only in the App Creator's browser and with the Provider.
+The MD Runtime owns one durable Room Draft per Room and Path, shared by every App and tab
+across reloads; a Room the Provider reports lost takes its Room Drafts and queue with it.
+Write one with `roomDraft.write(room, path, revision, parts)`, naming the revision you
+read or `null`, and every part it now changes: fields, sections and the preamble, or the
+whole Markdown, a creation, a move or a removal. A new part names its base, the value you
+showed when it was opened, a field's as `{ value }` or `null` for no such field, and keeps
+its first base; a binary Path entry's move or removal takes `null`. A write or discard
+from an older revision is refused as `stale` with the current Room Draft.
+
+Save takes one Room and the Room Drafts of it to save, each with its revision, validates
+locally, and on success appends one Change Batch to that Room's queue and removes those
+Room Drafts. Refused as `stale`, `changed-underneath` naming each part whose base no
+longer matches the visible state, or a local validation rule, it creates nothing and
+leaves every Room Draft. A directory move or removal is that part on each Document and
+binary Path entry beneath it, saved together. `saveParts(room, [{ path, parts }])` saves
+parts, each Path once and each new part with its base, the same way without any Room
+Draft: one held at a saved Path stays as it is, and one held at a Path it moves moves with
+it to a destination that holds none. Save a change that is not a Room Draft with it, never
+by reading the Room Draft at that Path and writing it back.
+
+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
+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
+attention until each returned Room Draft is saved or discarded. `observe('queue', room)`
+shows each Pending Change Batch, which keeps no outcome once it leaves. Transport failure,
+Provider unavailability and a refusal the Provider marks retryable, until the reset it
+names, keep work Pending; the MD Runtime retries the same Change Batch identity and
+payload, never infers an outcome from transport uncertainty, and never combines,
+reorders, or rebases.
+
+On a Site, every Save stays in the visitor's browser: write grants and revisions do not
+refuse it, and its Pending Change shows in every query and across reloads until the
+browser's storage is cleared. It is never sent: `observe('queue', room)` shows it `local`,
+Sync Status never waits on it, and once the Room no longer lets it apply it leaves the
+queue and returns no Room Draft.
+
+`observe('service-mode')` answers the Provider's Service Mode, `open` or `write-halted`.
+While writes are halted, Save succeeds, its Change Batch waits unsent and the queue is
+submitted in order once writes reopen; an Action is never held, and one the halt refuses
+returns that refusal: show the Provider as read-only instead of retrying.
+`observe('readiness')` tells whether the App's code and bound Rooms are held locally
+(`ready`), each Room's state, each refused Room's file and rule, the persistence answer
+and a paused preparation's `capacity` cause; `retry()` resumes a paused preparation.
+
+## Content safety and launch promises
+
+The Provider authorization belongs to the Runtime host and is never readable by the App's
+code. The App's code reaches the network only at the external origins its manifest
+declares, empty by default, and the Provider enforces that set. Rendered Markdown never
+executes scripts, renders raw HTML only for the details and summary elements, and loads
+images and other resources only from origins the Provider's policy allows. An agent must
+never read the authorization, load code from a Room, call the Provider directly, or rebase
+a refused Change Batch.
+
+MD UI uses semantic HTML, is fully operable from a keyboard with visible focus and
+labelled controls, and lays out from a 360 pixel wide viewport to a desktop. Its strings
+are English only, dates and numbers follow the browser locale, and content is never
+translated. Light and dark themes come from CSS custom properties, defaulting to the
+browser's preference and respecting an App's override. What an agent adds carries none of
+these promises by itself. Data lives only in the App Creator's browser and the Provider.
 
 ## App code takes the client its host hands it and never constructs a Runtime
 
-App code takes the client its host hands it: in House, `houseBridge().runtime`
-from `@agentshouse/app-bridge` resolves to the client House built into the page.
-It never constructs a Runtime or a client. It imports only types from
-`@agentshouse/mdruntime/client`, does not call `connectMdRuntime` or
-`serveMdRuntime`, and does not import the package main, the host entry, or the
-Adapter package. Hosts and tests use those entries; the served App does not.
-
-A React App may observe and save through `@agentshouse/mdruntime/react`, which
-names React as a peer dependency. `useObserve(client, topic, ...input)` takes
-the arguments of `observe` and returns `{ state: 'loading' }` until the topic's
-first value arrives, then `{ state: 'ready', value }`, re-rendering on each
-change; a `null` client observes nothing and stays loading. `useSave(client)`
-returns `busy`, the last `outcome` or `failure`, and `save(room, roomDrafts)`,
-which writes each Path's parts onto the Room Draft already there, keeping the
-bases its parts have, or onto a new one, and saves them together. A refused
-Save leaves the Room Drafts for the App to save again or discard; a failure is
-recorded and rejects. `saveRoomDrafts(client, room, roomDrafts)` is that save
-outside a component. A react-admin or Refine App reads and writes its Rooms
-through the data providers of `@agentshouse/mdruntime-families`.
+No module outside an Adapter package imports, names, or special-cases a Provider, and
+every App and MD UI reach data only through the client entry. In House,
+`houseBridge().runtime` from `@agentshouse/app-bridge` resolves to the client House built
+into the page. App code imports only types from `@agentshouse/mdruntime/client`, never
+calls `connectMdRuntime` or `serveMdRuntime`, and never imports the package main, the host
+entry or the Adapter package; the in-memory Adapter at `@agentshouse/mdruntime/memory` is
+for tests and ships in no bundle. A Site's page fills its Entry Data Contract's
+`{"$param": name}` arguments with `boundQuery` from `@agentshouse/mdruntime/entry`, as
+House did for its HTML. While the Site prepares, a query a route's `interaction` names
+answers from the entry's result when the page observes that descriptor, and every other
+stays pending. House replaces its HTML with the page once its document changed after those
+answers, or readiness is `ready`, and then held still for two animation frames, unless the
+visitor uses the HTML: draw the route at once, never behind a placeholder. Before
+readiness is `ready`, `push` loads a new page.
+
+A React App may observe and save through `@agentshouse/mdruntime/react`, with React as a
+peer dependency. `useObserve(client, topic, ...input)` takes the arguments of `observe`
+and returns `{ state: 'loading' }` until the topic's first value arrives, then `{ state:
+'ready', value }`, re-rendering on each change; a `null` client stays loading.
+`useSave(client)` returns `busy`, the last `outcome` or `failure`, and `save(room,
+parts)`, which saves each Path's parts, each new part naming its base, through
+`saveParts(room, [{ path, parts }])`: it writes no Room Draft, so one another tab holds
+at that Path stays as it is and one at a Path it moves moves with it, a refused Save
+changes nothing, and a failure is recorded and rejects. `saveWritten(room, roomDrafts)`
+saves Room Drafts the App wrote itself, each named with the revision its last write returned: one another tab wrote since
+is refused as `stale`, and nothing is saved. A react-admin or Refine App uses the data
+providers of `@agentshouse/mdruntime-families`.
 
 ## The Chat
 
-`@agentshouse/mdruntime/chat` holds the Chat, one data layer for every App.
-Its required peers are React, React DOM and `@assistant-ui/react`: add React as
-a dependency, also in an App not written in React.
-
-Place the ready chat with `<Chat client={runtime} conversation={id}
-agent={agent} width="1/3" showChats />`: `conversation` opens one, `null` for a
-new chat, `agent` is the Agent a new chat goes to, `onOpen` hears each one it
-opens, and `width` is `full` (the place you give it), or `3/4`, `1/2` or `1/3`
-of the window docked at its right edge, whole on a narrow window. `showChats`
-adds its conversation list; or draw your own inside a `ChatProvider` around a
-`<Chat />` with no `client`. It carries its own styles; theme it with CSS custom
-properties on it or an ancestor: `--chat-background`, `--chat-surface`,
-`--chat-text`, `--chat-text-muted`, `--chat-accent`, `--chat-line`,
-`--chat-attention`, `--chat-danger`, `--chat-font`, `--chat-font-mono`,
-`--chat-font-size`, `--chat-radius` and `--chat-density` (a factor for spacing);
-an unset one keeps House's light or dark look. `mountChat(element, { client })`
-places it outside React and returns `update(props)` and `unmount()`.
-
-Mix `ChatMessageList` (`components` takes your `UserMessage` and
-`AssistantMessage`), `ChatInput` and `ChatQuestionCard` with your own design
-inside a `ChatProvider`, or compose assistant-ui's primitives there; `useChat()`
-gives `send`, the conversations, the Agents, questions to `answer`, `options`
-to `choose`, `commands`, the queue to `edit` or `unqueue`, `stop`, `kill` and
-outcomes; never replace its messages, sending or store. A secret question is
-never answered here; typed answers live in Presentation State's `typed` key:
-keep it, and change Presentation State only inside `inTurn(client, work)` from
-`@agentshouse/mdruntime/client`. `Markdown` draws Markdown safely.
-
-## What an agent must never do
-
-An agent must never read the authorization, load code from a Room, call the
-Provider directly, or rebase a refused Change Batch.
+`@agentshouse/mdruntime/chat` holds the Chat, one data layer for every App; add React as a
+dependency in any App, with React DOM and `@assistant-ui/react`. Place the ready chat with
+`<Chat client={runtime} conversation={id} agent={agent} width="1/3" showChats />`:
+`conversation` opens one, `null` for a new chat, `agent` is the Agent a new chat goes to,
+`onOpen` hears each one it opens, and `width` is `full` (the place you give it), or `3/4`,
+`1/2` or `1/3` of the window docked at its right edge, whole on a narrow window.
+`showChats` adds its conversation list; or draw your own inside a `ChatProvider` around a
+`<Chat />` with no `client`. Theme its own styles with CSS custom properties on it or an
+ancestor: `--chat-background`, `--chat-surface`, `--chat-text`, `--chat-text-muted`,
+`--chat-accent`, `--chat-line`, `--chat-attention`, `--chat-danger`, `--chat-font`,
+`--chat-font-mono`, `--chat-font-size`, `--chat-radius` and `--chat-density` (a factor for
+spacing); an unset one keeps House's light or dark look. `mountChat(element, { client })`
+places it outside React, with `update(props)` and `unmount()`.
+
+Mix `ChatMessageList` (`components` takes your `UserMessage` and `AssistantMessage`),
+`ChatInput` and `ChatQuestionCard` with your own design inside a `ChatProvider`, or
+compose assistant-ui's primitives there; `useChat()` gives `send`, the conversations, the
+Agents, questions to `answer`, `options` to `choose`, `commands`, the queue to `edit` or
+`unqueue`, `stop`, `kill` and outcomes; never replace its messages, sending or store. It
+shows a conversation's latest 50 messages, and assistant-ui's `loadEarlier()` the 50
+before, which `ChatMessageList` calls as the reader scrolls back. A secret question is
+never answered here; typed answers live in the Presentation State members named `typed:…`:
+leave them. `Markdown` draws Markdown safely.