@ours.network/notifications 0.1.1

package/mufl_code/core/docs/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "ours-mufl-core-docs",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "docs:dev": "vitepress dev .",
+    "docs:build": "vitepress build .",
+    "docs:check": "node scripts/check-citations.mjs && node scripts/check-denylist.mjs"
+  },
+  "devDependencies": {
+    "mermaid": "^11.16.0",
+    "vitepress": "^1.6.0",
+    "vitepress-plugin-mermaid": "^2.0.17"
+  }
+}

package/mufl_code/core/docs/reference/contributing.md

@@ -0,0 +1,26 @@
+# Contributing
+
+The full contribution guidelines are in
+[`CONTRIBUTING.md`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/CONTRIBUTING.md)
+in the repository root.
+
+## Current posture
+
+Until the Contributor Licence Agreement (CLA) process is live, the project accepts
+**issues and feedback only** — pull requests are not open. This applies to the protocol
+repository. If you are integrating the core into your own agent, that integration is entirely
+yours; no CLA or coordination is needed.
+
+## How to contribute
+
+- **Bug reports and questions** — open an issue on the
+  [ours-mufl-core repository](https://github.com/adapt-toolkit/ours-mufl-core).
+- **Feature discussion** — open an issue describing the use case. Protocol changes affect every
+  client, so discussion precedes any design.
+- **Security issues** — do not open a public issue; see `SECURITY.md` in the repository root.
+- **Code contributions** — on hold until the CLA is live. See `CONTRIBUTING.md` for the rationale.
+
+## Integration feedback
+
+If you are building on the core and encounter something that does not match the docs, open an
+issue. Integration experience is the most useful signal at this stage.

package/mufl_code/core/docs/reference/glossary.md

@@ -0,0 +1,108 @@
+# Glossary
+
+Terms used across the protocol documentation.
+Source of truth: the `.mm` files and
+[`README.md`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/README.md)
+(the identical wire guarantee).
+
+---
+
+**boxed send**
+An encrypted message sent over a one-way ephemeral channel using a known public key, without a
+pre-established `encrypted_channel`. Used during the invite redeem hop to carry identity
+material before a persistent channel exists.
+See [Invites & contacts](../how-it-works/invites-and-contacts.md).
+
+**broker**
+The relay service operated by ours.network that routes packets between agents. Agents do not
+connect directly to each other; the broker forwards ciphertext without being able to read it.
+
+**capability**
+A named feature set advertised in an agent's app manifest. Each capability has a stable string
+id (e.g. `"core.monitoring"`) and a schema; the control envelope routes requests to its handler
+by `$cap` id.
+See [Capabilities & control](../how-it-works/capabilities-and-control.md).
+
+**cid / container\_id**
+The stable, globally unique identifier for a MUFL packet instance (a running agent). Represented
+as a `global_id`. Peers reference each other by container id in address documents and contact
+registries.
+
+**contact book**
+The host-local registry of children and contacts maintained by the `core.cluster` capability
+in `a2a_cluster.mm`. Entries record name, role, bio, persona, monitoring state, and capability
+ids.
+See [Cluster](../how-it-works/cluster.md).
+
+**delegation cert**
+A signed record (`delegation_cert_t`) that binds a role's container id and address-document hash
+to its root, signed by the root's keys. A root identity carries no delegation cert (`NIL`);
+detection is structural.
+See [Identity: roots & roles](../how-it-works/identity.md).
+
+**encrypted channel**
+The persistent, per-contact end-to-end-encrypted session established during invite redemption and
+restored from stored peer address documents on restart. All message and file traffic rides this
+channel.
+See [Messaging](../how-it-works/messaging.md).
+
+**envelope**
+A `control_envelope_t` record (`$cap`, `$verb`, `$args`, `$req_id`) that carries a capability
+request. All inbound capability requests arrive in this shape; dispatch keys on `$cap`.
+See [Capabilities & control](../how-it-works/capabilities-and-control.md).
+
+**hidden state**
+A MUFL field declared `hidden` that only code inside the declaring library can write. Used for
+`monitoring_proxy` and `app_config` in `a2a_messaging.mm` to prevent any external library or
+app from suppressing forced copies or overwriting configuration.
+See [Monitoring & config](../how-it-works/monitoring-and-config.md).
+
+**introduction**
+A contact-establishment shortcut via a shared control plane. The CP sends each side the other's
+signed address document via `ingest_connect_descriptor`; no out-of-band invite is needed.
+Requires both nodes to advertise `core.connect`.
+See [Invites & contacts](../how-it-works/invites-and-contacts.md).
+
+**invite leg**
+One step of the invite redeem flow (OOB transfer, leg 1, leg 2, leg 3). Leg 1 is the responder's
+BARE send to the inviter; leg 2 is the inviter's receipt and verification of leg 1 (consuming the
+invite and emitting leg 3); leg 3 is the inviter's BARE send reply to the responder.
+See [Invites & contacts](../how-it-works/invites-and-contacts.md).
+
+**MAJ / MIN**
+The major (`$MAJ`) and minor (`$MIN`) components of `version_t`. A `$MAJ` bump signals breaking
+changes; a `$MIN` bump signals new features with no removals.
+See [Versioning](../how-it-works/versioning.md).
+
+**monitoring copy**
+A forced encrypted copy of every inbound and outbound message sent to the bound control plane
+when `monitoring_proxy` is set. Generated by `monitor_copy_actions` in `a2a_messaging.mm`;
+received by `a2a_monitoring.mm` on the CP side.
+See [Monitoring & config](../how-it-works/monitoring-and-config.md).
+
+**packet**
+A compiled MUFL application instance — the unit that runs as an agent. Consumers vendor the
+core and compile it together with their own libraries into a packet. Every packet that links the
+core speaks the same wire format.
+
+**role**
+A delegated identity anchored to a root. A role carries a `delegation_cert_t` signed by its
+root. Roles are the typical identity type for child/subagents in a cluster.
+See [Identity: roots & roles](../how-it-works/identity.md).
+
+**root**
+A self-sovereign keypair identity with no delegation cert (`NIL`). A root is the anchor of an
+identity hierarchy; roles are derived from it.
+See [Identity: roots & roles](../how-it-works/identity.md).
+
+**verb**
+The operation requested within a capability, carried in the `$verb` field of a
+`control_envelope_t`. Verbs must be consciously listed in `control_auth_class` to become
+reachable through dispatch.
+See [Capabilities & control](../how-it-works/capabilities-and-control.md).
+
+**wrapper**
+The host-side shim that connects the MUFL packet to the node runtime: wires the
+`protocol_container`, routes inbound messages to `::actor::receive_message`, and marshals
+notify-actions to host primitives.
+See [Wire the host](../guide/03-wire-the-host.md).

package/mufl_code/core/docs/reference/implementations.md

@@ -0,0 +1,23 @@
+# Reference implementations
+
+These two applications are the living examples of everything in the
+[integration guide](../guide/index.md): real agents built on the core, each vendoring this repo
+as a git submodule. Read their `config.mufl`, host wiring, and tests — not this page — for the
+details.
+
+## ours-mcp
+
+[**ours-mcp**](https://github.com/adapt-toolkit/ours-mcp) is the MCP agent server. It vendors
+the core at `packages/core/mufl_code/core`. Its `config.mufl` shows how the core export merges
+with the packet's own libraries; its host wiring shows how the MUFL actor connects to the node
+runtime; its tests show end-to-end protocol flows in production use.
+
+## ours-tg-connector
+
+[**ours-tg-connector**](https://github.com/adapt-toolkit/ours-tg-connector) is the Telegram
+connector. It vendors the core at `mufl_code/core`. The same integration pattern —
+`config_load #"core"`, host wiring, test suite — applied to a different transport.
+
+---
+
+The guide describes the pattern. These repos are the pattern applied.

package/mufl_code/core/docs/reference/modules.md

@@ -0,0 +1,19 @@
+# Modules
+
+The core is eight `.mm` libraries and one config export loaded by `config_load #"core"` from a consumer's
+`config.mufl`. The source is the authoritative reference; the
+[how-it-works](../how-it-works/overview.md) pages explain the protocol design behind each module.
+
+| File | Purpose |
+|------|---------|
+| [`a2a_capabilities.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_capabilities.mm) | App manifest, capability/verb envelope and dispatch, well-known capability ids (`core.configuration`, `core.monitoring`, `core.connect`, `core.cluster`). |
+| [`a2a_protocol.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_protocol.mm) | Wire-facing shapes (invites, delegation certificates, root profiles, contact roots, introduction credentials) and the shared verification helpers. |
+| [`a2a_messaging.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_messaging.mm) | Contact and messaging transactions: invite generation/redemption, add/remove contact, send message, send file, inbound receive, and the introduction flow. |
+| [`a2a_cluster.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_cluster.mm) | The `core.cluster` capability handler: child/subagent lifecycle, per-child monitoring authorization, host-local contact book, and introductions between children and contacts. |
+| [`a2a_monitoring.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_monitoring.mm) | Control-plane receiver side of monitoring copies: validates sender and hands the copy to the app's storage hook. |
+| [`a2a_control.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_control.mm) | Control-plane transport: an opaque payload delivered to a contact over the `encrypted_channel`, validated on receipt. |
+| [`a2a_notifications.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_notifications.mm) | Notification service protocol: per-contact scoped tokens (`$scope`), registration and WebPush bindings, token issuance/rotation/revocation, receive-mute, and the bare signed-send notification ingest. |
+| [`version.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/version.mm) | Core version record, readable at runtime via `get_core_version`. |
+| [`config.mufl`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/config.mufl) | Compile configuration: exports the libraries above for `config_load #"core"`. |
+
+Source: [`README.md`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/README.md).

package/mufl_code/core/docs/scripts/check-citations.mjs

@@ -0,0 +1,36 @@
+// Validates docs/citations.json: every cited file exists in the repo,
+// every cited symbol greps in that file, every cited page exists,
+// and every non-stub content page has at least one citation entry.
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const docsRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
+const repoRoot = join(docsRoot, '..')
+const manifest = JSON.parse(readFileSync(join(docsRoot, 'citations.json'), 'utf8'))
+const errors = []
+
+for (const [page, cites] of Object.entries(manifest)) {
+  if (!existsSync(join(docsRoot, page))) errors.push(`cited page missing: ${page}`)
+  for (const { file, symbol } of cites) {
+    const target = join(repoRoot, file)
+    if (!existsSync(target)) { errors.push(`${page}: cited file missing: ${file}`); continue }
+    if (symbol && !readFileSync(target, 'utf8').includes(symbol))
+      errors.push(`${page}: symbol "${symbol}" not found in ${file}`)
+  }
+}
+
+// coverage: every content page that is no longer a stub must be in the manifest
+const stubMarker = '*(content lands in Tasks'
+for (const dir of ['how-it-works', 'workflows', 'guide', 'reference']) {
+  for (const f of readdirSync(join(docsRoot, dir))) {
+    if (!f.endsWith('.md')) continue
+    const rel = `${dir}/${f}`
+    const body = readFileSync(join(docsRoot, rel), 'utf8')
+    if (!body.includes(stubMarker) && !(rel in manifest))
+      errors.push(`content page has no citations registered: ${rel}`)
+  }
+}
+
+if (errors.length) { console.error('CITATION CHECK FAILED\n' + errors.join('\n')); process.exit(1) }
+console.log('citation check OK:', Object.keys(manifest).length, 'pages')

package/mufl_code/core/docs/scripts/check-denylist.mjs

@@ -0,0 +1,30 @@
+// Internal team-process artifacts, host paths, and unmerged-feature references
+// must never ship (SPEC C1/C2/C6).
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, dirname, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// Patterns are assembled from fragments so this file itself never matches the
+// deny-list checker (a literal match in scripts/ would be a false positive).
+const DENY = [
+  new RegExp('WS-' + 'B'),
+  new RegExp('WS-' + 'C'),
+  new RegExp('WS-' + 'D'),
+  new RegExp('\\bcritic\\b', 'i'),
+  new RegExp('TEAM-' + 'PROTOCOL'),
+  new RegExp('Coordinator-' + 'frozen'),
+  new RegExp('/home/' + 'fleet'),
+]
+const docsRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
+const errors = []
+const walk = d => { for (const e of readdirSync(d)) {
+  const p = join(d, e)
+  if (e === 'node_modules' || e === '.vitepress' || e === 'scripts') continue
+  if (statSync(p).isDirectory()) walk(p)
+  else if (e.endsWith('.md')) for (const term of DENY)
+    if (term.test(readFileSync(p, 'utf8')))
+      errors.push(`${relative(docsRoot, p)}: matches ${term}`)
+}}
+walk(docsRoot)
+if (errors.length) { console.error('DENYLIST CHECK FAILED\n' + errors.join('\n')); process.exit(1) }
+console.log('denylist check OK')

package/mufl_code/core/docs/scripts/gen-llms.mjs

@@ -0,0 +1,32 @@
+// Emits llms.txt (annotated index) and llms-full.txt (all pages concatenated)
+// into .vitepress/dist after a build. Order follows the sidebar sections.
+import { readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const docsRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
+const dist = join(docsRoot, '.vitepress/dist')
+const SITE = 'https://adapt-toolkit.github.io/ours-mufl-core'
+const ORDER = ['index.md',
+  ...['overview','identity','invites-and-contacts','messaging','capabilities-and-control',
+      'cluster','monitoring-and-config','versioning'].map(p => `how-it-works/${p}.md`),
+  ...['index','contact-exchange','messaging','contact-restore','monitoring',
+      'control-verbs','introductions','cluster'].map(p => `workflows/${p}.md`),
+  ...['index','01-vendor-the-core','02-configure-and-compile','03-wire-the-host',
+      '04-connect-and-message','05-test-your-app'].map(p => `guide/${p}.md`),
+  ...['modules','implementations','glossary','contributing'].map(p => `reference/${p}.md`)]
+
+let index = `# ours-mufl-core — agent docs index\n\n`
+let full = ''
+for (const rel of ORDER) {
+  const p = join(docsRoot, rel)
+  if (!existsSync(p)) continue
+  const body = readFileSync(p, 'utf8')
+  const title = (body.match(/^#\s+(.+)$/m) ?? [,rel])[1]
+  const url = `${SITE}/${rel.replace(/index\.md$/, '').replace(/\.md$/, '')}`
+  index += `- [${title}](${url})\n`
+  full += `\n\n----- ${rel} -----\n\n${body}`
+}
+writeFileSync(join(dist, 'llms.txt'), index)
+writeFileSync(join(dist, 'llms-full.txt'), full.trimStart())
+console.log('llms.txt + llms-full.txt written')

package/mufl_code/core/docs/workflows/cluster.md

@@ -0,0 +1,89 @@
+# Cluster lifecycle
+
+`core.cluster` verbs manage hosted children (subagents) of a root identity. Operations that
+need host work — provisioning a packet, destroying one, minting a child's invite, binding a
+child's monitoring — are **asynchronous**: the verb handler validates, persists a pending
+request keyed by a unique handle, emits a *host-primitive* notify to the local daemon, and
+acknowledges `$pending` immediately. The daemon does the work and calls back a host-only
+transaction that consumes the pending request and routes the real result to the original
+controller.
+
+Traced from [`a2a_cluster.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_cluster.mm)
+(`cluster_handler`, `register_provisioned_child`, `sweep_and_settle`, `reconcile`) and
+[`a2a_messaging.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_messaging.mm)
+(`relay_enroll_delegated_node`, `handle_enroll_delegated_node`).
+
+## Async child create
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant C as Controller (control plane)
+    participant R as Root packet
+    participant D as Root host (daemon)
+    participant K as New child packet
+
+    C->>R: control_message - core.cluster / create ($name, $bio, $req_id)
+    Note over R: dispatch authz - cluster_handler - duplicate check<br/>(registry AND pending creates, name is a global op-key)
+    Note over R: pending_reqs[handle] = (sender, $req_id, verb, op-key) -<br/>pending_create_names[$name]
+    R-->>D: notify host_provision_child ($name, $bio, $pending_handle)
+    R-->>C: immediate ack: $ok TRUE, $pending TRUE
+
+    Note over D: provision the child packet + delegate its role
+    D->>K: create the packet (host runtime op)
+    D->>R: register_provisioned_child ($pending_handle, $role_id, $child_ad)
+    Note over R: host-only gates: origin user + handle must match an<br/>outstanding create - consumed atomically (unsolicited callbacks abort)
+    Note over R: cluster_members[cid] registered - caps seeded from my own manifest
+    R-->>D: async reply routed to the STORED controller ($target, $response)
+    D->>C: response: $cid, $name, $monitoring "off" (correlated by $req_id)
+    R->>C: receive_roster_update ($version, $members) - push, if a CP is bound
+```
+
+`remove` (destroy + `confirm_child_destroyed`), `contact` (mint the **child's** invite in the
+child's own packet + `register_child_invite` — a root-minted invite would connect the caller to
+the root, not the child), and `set_monitoring` (host-bind or host-clear the child's proxy +
+`confirm_child_monitoring`) follow the same handle pattern with their own host primitives.
+
+Two safety nets close the loop:
+
+- **`reconcile`** — host truth joined with the registry: backfills children created
+  out-of-band, drops members no longer hosted, preserves CP-authoritative fields (`$bio`,
+  `$monitoring`) for existing members.
+- **`sweep_and_settle`** — pending requests older than 120 s are settled: a create whose name
+  now exists is adopted as success, otherwise timed out; an expired create also clears its
+  global name key so a lost callback never leaves a name permanently un-creatable.
+
+## Cluster enrollment (one root bind conveys the whole cluster)
+
+The control plane holds `peer_ads` for every cluster member off a **single root bind**: the
+root relays each child's public material; the child never participates.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant D as Root host
+    participant R as Root packet
+    participant CP as Control-plane packet
+
+    D->>R: relay_enroll_delegated_node ($proxy, $child_ad, $delegation_cert, $root_profile)
+    Note over R: root-only (a role cannot relay)
+    R->>CP: enroll_delegated_node ($child_ad, $delegation_cert, $root_profile) - encrypted channel
+    Note over CP: gates: child document self-signature (proof-of-possession) -<br/>verify_peer_delegation binds child cid + document hash to a root,<br/>root-signed - the SENDER must BE that root<br/>(possession of a valid chain is not enough)
+    Note over CP: contact registered as root_name/role_id -<br/>re-enroll just refreshes the stored document
+    CP-->>CP: notify $enrolled (or $reenrolled) to its host
+```
+
+## Per-child monitoring, derived — never named
+
+On `set_monitoring` enable, the CP a child gets bound to is **derived from the root's own
+ceremony-pinned `monitoring_proxy`** (`bound_cp_cid`), never taken from the request arguments —
+so a child can only ever be bound to the CP its root actually ceremonied. The daemon first
+host-injects the CP as a contact into the child (`host_register_monitoring_cp`, with the CP
+document verified), because a network introduction would be rejected by the child's CP-only
+acceptance gate and would race the ceremony. Disable host-clears the child's proxy and drops
+the injected CP contact (`host_clear_child_monitoring`).
+
+Roster changes (create, remove, bio/persona updates, monitoring flips, reconcile diffs) push a
+sequenced snapshot to the bound CP — `receive_roster_update`, ingested on the CP side by the
+`on_roster_update` hook (see
+[`a2a_monitoring.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_monitoring.mm)).

package/mufl_code/core/docs/workflows/contact-exchange.md

@@ -0,0 +1,60 @@
+# Contact exchange (invite redeem)
+
+Two strangers become mutual contacts through a **slim ephemeral-key invite** and a three-leg
+redeem handshake. The invite blob itself carries no identity material — only an ephemeral
+pubkey and correlation data (see [Invites & contacts](../how-it-works/invites-and-contacts.md)
+for the invite shape). Identity bundles move inside boxes on legs 1 and 3, both of which are
+**bare sends**: the two sides are not each other's contacts yet, so the encrypted channel
+cannot carry them.
+
+Traced from [`a2a_messaging.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_messaging.mm)
+(`generate_invite` / `mint_eph_invite`, `add_contact`, `handle_submit_invite_response`,
+`handle_complete_invite`).
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant IH as Inviter host
+    participant I as Inviter packet
+    participant R as Responder packet
+    participant RH as Responder host
+
+    IH->>I: generate_invite ($name)
+    Note over I: mint_eph_invite - fresh ephemeral keypair.<br/>pending_invites[id] = pub half + assigned name.<br/>pending_invite_keys[id] = private half (hidden, never exported)
+    I-->>IH: $invite blob, $invite_id
+
+    Note over IH,RH: invite blob travels out-of-band (QR, link, chat)
+
+    RH->>R: add_contact ($invite, $name)
+    Note over R: LEG 1 - fresh responder ephemeral keypair.<br/>Box my identity bundle to the invite's eph pubkey.<br/>pending_redemptions[id] + pending_redemption_keys[id]
+    R->>I: submit_invite_response ($invite_id, $epk, $v, $data) - bare boxed send
+
+    Note over I: LEG 2 gates, in order, no writes until all pass:<br/>pending lookup (single-use) - box-open -<br/>cid-bind + PoP self-sig - optional delegation chain
+    Note over I: register contact + peer_ads, consume<br/>pending_invites + pending_invite_keys atomically
+    I->>R: complete_invite ($invite_id, $epk, $v, $data) - bare boxed send
+    I-->>IH: notify $contact_accepted
+
+    Note over R: LEG 3 gates: pending lookup - expected-inviter<br/>cid pin - box-open with kept eph key -<br/>cid-bind + PoP - optional chain
+    Note over R: register contact + peer_ads, clear<br/>pending_redemptions + pending_redemption_keys
+    R-->>RH: notify $contact_added
+
+    Note over I,R: both sides registered - encrypted_channel carries all further traffic
+```
+
+## Key properties visible in the flow
+
+- **Single-use**: the first valid leg 2 consumes `pending_invites[id]` *and*
+  `pending_invite_keys[id]` together. A replayed leg 1 aborts with `already-redeemed` and
+  mutates nothing; a leg 1 that fails a gate (bad box, forged bundle) consumes nothing.
+- **Disclosure order**: the responder discloses its identity first (leg 1); the inviter answers
+  with its own bundle only after the responder's bundle verified (leg 3).
+- **Why bare sends**: on leg 1 the inviter is not registered on the responder side (and vice
+  versa on leg 3), so `send_encrypted_tx` could not resolve a source key. The box to the
+  ephemeral key is the confidentiality; envelope signing plus the cid-bind and
+  proof-of-possession checks are the authenticity.
+- **Role invites**: when either side is a delegated role, its bundle also carries the delegation
+  cert, root profile, and optional root-CP binding — verified with `verify_identity_bundle`, so
+  each side learns the other's verified root linkage (`contact_roots`).
+
+An invite can also be minted for a hosted child via the cluster `contact` verb — same
+construction path (`mint_eph_invite`), see [Cluster lifecycle](./cluster.md).

package/mufl_code/core/docs/workflows/contact-restore.md

@@ -0,0 +1,60 @@
+# Contact restore
+
+A **degraded contact** is a cid present in `contacts` but missing from `peer_ads` — typically
+after a breaking-change migration carried the contact but had to drop its address document.
+Contact restore re-runs the key exchange between two *mutually known* addresses: the same
+machinery as the invite legs (identity bundle, box to an ephemeral key, gates before any
+write), but the trust anchor is "a signed request from an address already in my contacts"
+instead of an out-of-band invite token.
+
+Traced from [`a2a_messaging.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_messaging.mm)
+(`begin_contact_restore`, `handle_request_contact_restore`, `handle_submit_restore_response`,
+`handle_complete_restore`, `flush_deferred`, `restore_degraded_contacts`).
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant H as Requester host
+    participant A as Requester packet (degraded contact for B)
+    participant B as Responder packet (still holds A in contacts)
+
+    Note over H,A: trigger: send_message toward the degraded contact<br/>(queues into deferred_msgs) OR the host boot/GC sweep<br/>restore_degraded_contacts (up to 30 attempts per contact)
+    Note over A: begin_contact_restore - fresh ephemeral keypair + $rid.<br/>pending_restores[B] (replaces any outstanding attempt)
+    A->>B: LEG 0 request_contact_restore ($rid, $epk, $v) - bare signed send
+
+    Note over B: gate: sender in contacts - else SILENT no-op<br/>(no error reply, so address knowledge never leaks)
+    Note over B: pending_restore_replies[A] + fresh reply eph keypair.<br/>Nothing installed or replaced yet
+    B->>A: LEG 1 submit_restore_response ($rid, $epk, $v, $data) - B's bundle boxed to A's eph key
+
+    Note over A: gates: pending lookup - $rid pin - box-open -<br/>cid-bind + PoP - optional chain
+    Note over A: reinstall peer_ads[B], consume pending_restores single-use
+    A->>B: LEG 2 complete_restore ($rid, $epk, $v, $data) - A's bundle boxed to B's reply eph key
+    A-->>H: notify $contact_restored
+
+    Note over B: gates: reply lookup - $rid pin - box-open - cid-bind + PoP - chain
+    Note over B: REPLACE peer_ads[A] (a reseeded peer rolls fresh keys,<br/>so even a present-but-stale document must be replaced)
+    B-->>B: notify $contact_restored (to its own host)
+
+    H->>A: flush_deferred ($contact) - host-driven on the notify
+    A->>B: receive_message x queued - encrypted channel, original wire_ids preserved
+```
+
+## Why the pieces are shaped this way
+
+- **Leg 0 is unboxed** (just `$rid`, an ephemeral pubkey, and a scheme id): there is nothing
+  secret to carry yet, and the framework signs every envelope, so the responder authenticates
+  the requester from the envelope alone.
+- **Silent no-op for strangers**: a request from an address not in `contacts` returns success
+  with no actions — whether an address is known never leaks.
+- **The flush is host-driven**, not automatic: firing `flush_deferred` on the
+  `$contact_restored` notify means the encrypted sends can never race the restore legs' bare
+  sends on the wire.
+- **Retry budget**: the host sweep re-fires on its GC cadence, up to `restore_max_attempts`
+  (30) per contact; a peer that upgraded and came back online answers on the first
+  post-upgrade attempt. Each re-mint supersedes the previous ephemeral key, so a stale leg-1
+  reply fails both the `$rid` check and the unbox.
+- **Observability**: `list_degraded_contacts` and `list_deferred_queues` are the readonly
+  views the host sweep keys off.
+
+This flow is what makes contacts survive breaking changes — see the migration contract in
+[Versioning](../how-it-works/versioning.md).

package/mufl_code/core/docs/workflows/control-verbs.md

@@ -0,0 +1,70 @@
+# Control-plane verb calls
+
+All capability verbs — configuration, monitoring, connect, cluster — ride **one** transport
+transaction (`a2a_control`'s `control_message`) carrying a typed envelope
+`($cap, $verb, $args, $req_id)`. The receiving side routes it through a single dispatch
+chokepoint with a fail-closed authorization table. MUFL has no JSON codec, so the daemon
+adapts JSON to native records on the way in and marshals the native response envelope back to
+JSON on the way out — generically, with no per-verb logic in the host.
+
+Traced from [`a2a_control.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_control.mm)
+(`send_control`, `control_message`),
+[`a2a_capabilities.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_capabilities.mm)
+(`dispatch`, `control_auth_class`), and
+[`a2a_messaging.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_messaging.mm)
+(`authorize_control`).
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant C as Controller node (e.g. messenger)
+    participant T as Target packet
+    participant D as Target host (daemon)
+
+    C->>T: send_control - control_message ($payload JSON, $app_id) - encrypted channel
+    Note over T: gates: external + encrypted + sender is a known contact
+    T-->>D: on_control_received hook ($sender_id, $payload, $app_id, $date)
+    Note over D: adapt: parse $payload JSON into a native envelope<br/>($cap, $verb, $args, $req_id)
+    D->>T: a2a_capabilities::dispatch (sender, envelope)
+    Note over T: control_auth_class ($cap, $verb) - fail-closed:<br/>public - pass / bootstrap - pass (bind checks its own code) /<br/>controller - authorize_control: sender must BE the bound<br/>monitoring proxy / anything unlisted - deny
+    alt authorized
+        Note over T: handler for $cap runs (a2a_cluster::cluster_handler,<br/>monitoring_handler, connect_handler, app handlers)
+        T-->>D: response_envelope ($req_id, $ok, $result, $err) as return_data
+    else denied
+        T-->>D: response_envelope $ok FALSE ($err unknown_verb / unauthorized)
+    end
+    Note over D: marshal the native envelope to JSON
+    D->>T: send_control back toward the controller
+    T->>C: control_message (response payload)
+    Note over C: correlate on (sender, $req_id)
+```
+
+## The authorization classes
+
+`control_auth_class` is a pure table in the lowest layer; the stateful half
+(`authorize_control`, which reads the hidden `monitoring_proxy`) is wired in at init and
+enforced *inside* `dispatch`, so an app cannot wire routing while forgetting the gate — a
+controller-class verb with no authorizer wired aborts.
+
+| Class | Verbs | Who may call |
+|-------|-------|--------------|
+| `public` | none via dispatch (`get_manifest` is a standalone readonly transaction, never routed through dispatch) | anyone |
+| `bootstrap` | `core.monitoring` / `bind` | whoever presents the 6-digit code (pre-bind by definition) |
+| `controller` | the explicit list: `core.cluster` verbs, `core.monitoring` / `disable`, `core.connect` / `introduce`, `core.configuration` `get_config` / `set_config` | only the bound control plane |
+| `deny` | everything else | no one — a new verb must be consciously classified to become reachable |
+
+## Async verbs
+
+Some cluster verbs cannot complete inside one transaction (provisioning a child takes host
+work). Their handlers return an immediate `$pending` acknowledgment and the real result is
+routed later by a host callback to the *stored* original controller — see
+[Cluster lifecycle](./cluster.md) for that pattern.
+
+## Configuration writes
+
+`set_app_config` follows the same trust rule as every controller-class verb: external,
+encrypted, sender must be the bound CP (`require_bound_cp_or_abort`). The blob is opaque to the
+core — a `$config_updated` notify wakes the host wrapper, which pulls it via `get_app_config`
+and applies the operational parts. See
+[Capabilities & control](../how-it-works/capabilities-and-control.md) for the envelope types
+and manifest shape.

package/mufl_code/core/docs/workflows/index.md

@@ -0,0 +1,57 @@
+# Transaction flows
+
+Each page in this section traces **one conceptual protocol workflow** as a sequence diagram:
+which transaction invokes which, how the call leaves the node, and how the result comes back.
+Every arrow is labeled with the real transaction or function name from the `.mm` source — the
+diagrams are traced from the code, not from a design document.
+
+## How to read the diagrams
+
+**Participants.** A *packet* is the compiled MUFL protocol container of one identity. A *host*
+is the daemon embedding that packet (the reference host is the ours MCP daemon). A *control
+plane* (CP) is a peer node bound via the monitoring ceremony. Arrows between two packets are
+network sends; delivery is the ADAPT framework's job — if the receiver is offline, the ADAPT
+broker holds the pending message.
+
+**Transaction origins.** Every transaction validates its origin first
+(`current_transaction_info::validate_origin_or_abort`):
+
+| Origin | Meaning | Drawn as |
+|--------|---------|----------|
+| `origin::user` | fired by the local host/daemon on behalf of the operator | `Host ->> Packet` |
+| `origin::external` | arrived from the network (envelope carries the authenticated sender in `$from`) | `Packet A ->> Packet B` |
+
+**Send mechanisms.** Two kinds of arrows leave a packet:
+
+- **Encrypted-channel send** (`encrypted_channel::send_encrypted_tx`) — the normal path between
+  registered contacts; requires the peer's address document in `peer_ads`.
+- **Bare send** (`transaction::action::send`) — used only when the peer is *not yet* (or no
+  longer) resolvable as a contact: the invite redeem legs and the contact-restore legs. Payload
+  confidentiality then comes from a box to an ephemeral key carried in the flow itself, and the
+  framework signs every envelope, so the receiver still authenticates the sender.
+
+**Results.** A transaction returns *actions*: network sends, `$data` (the caller's return
+value), `$notify_agent` (an event for the host — drawn as a dashed arrow back to the host), and
+`$save_state` (persist the packet — emitted only at the end of a complete step, never
+mid-handshake, so a crash restores to the last stable point).
+
+## The workflows
+
+| Workflow | What it covers |
+|----------|----------------|
+| [Contact exchange](./contact-exchange.md) | `generate_invite` → `add_contact` → the three redeem legs |
+| [Send & receive messages](./messaging.md) | `send_message` / `receive_message`, `send_file` / `receive_file`, storage hooks |
+| [Contact restore](./contact-restore.md) | self-healing a degraded contact: restore legs 0–2 + `flush_deferred` |
+| [Monitoring bind & copies](./monitoring.md) | the 6-digit bind ceremony, forced copies, disable |
+| [Control-plane verb calls](./control-verbs.md) | `send_control` → `dispatch` → capability handler → response envelope |
+| [Introductions](./introductions.md) | `core.connect`: a shared CP connects two nodes without an invite |
+| [Cluster lifecycle](./cluster.md) | async child create via host primitives, cluster enrollment, roster push |
+| [Notifications](./notifications.md) | `notify_register` → `notify_issue_tokens` → `send_notification` / `post_notification`, mute/rotate/revoke |
+
+All flows were traced from
+[`a2a_messaging.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_messaging.mm),
+[`a2a_control.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_control.mm),
+[`a2a_capabilities.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_capabilities.mm),
+[`a2a_cluster.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_cluster.mm) and
+[`a2a_monitoring.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_monitoring.mm) and
+[`a2a_notifications.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_notifications.mm).