@ours.network/notifications 0.1.1

package/mufl_code/core/docs/guide/01-vendor-the-core.md

@@ -0,0 +1,50 @@
+# 01 · Vendor the core
+
+Your application never copies protocol code — it pins the core as a **git submodule**
+so the exact protocol revision you compiled against is recorded in your repo. This is
+how every ours.network client consumes the core (the
+[README](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/README.md) documents
+the same one-liner).
+
+**Prereqs:**
+
+- `git` installed.
+- Network access to `github.com` (or a local mirror of this repo).
+
+**Steps:**
+
+1. Create your application repo:
+
+   ```sh
+   mkdir my-app && cd my-app
+   git init
+   ```
+
+2. Add the core as a submodule under `mufl_code/core`. The `mufl_code/` directory is
+   your packet's compile root; the core **must** land in a `core/` subfolder of it,
+   because that is where your `config.mufl` will look for it
+   (see [02 · Configure & compile](./02-configure-and-compile.md)):
+
+   ```sh
+   git submodule add https://github.com/adapt-toolkit/ours-mufl-core.git mufl_code/core
+   ```
+
+   (SSH form: `git@github.com:adapt-toolkit/ours-mufl-core.git`.)
+
+When cloning your app later, pull the pinned core with `git submodule update --init`.
+
+**Verify:**
+
+```sh
+ls mufl_code/core/*.mm
+git submodule status
+```
+
+Success markers:
+
+- `ls` lists the seven protocol libraries, ending
+  `mufl_code/core/a2a_protocol.mm` … `mufl_code/core/version.mm`.
+- `git submodule status` prints one line: a commit hash followed by
+  `mufl_code/core`.
+
+Next: [02 · Configure & compile](./02-configure-and-compile.md).

package/mufl_code/core/docs/guide/02-configure-and-compile.md

@@ -0,0 +1,100 @@
+# 02 · Configure & compile
+
+The core is a set of pure MUFL libraries with no standalone build — *your* `config.mufl`
+merges its exports with the MUFL stdlib, and *your* application file loads the libraries
+by name. This page produces your first compiled packet (`.muflo`).
+
+**Prereqs:**
+
+- [01 · Vendor the core](./01-vendor-the-core.md) completed (`mufl_code/core` populated).
+- `$ADAPT_TOOLKIT` exported (see [Start here](./index.md)).
+
+**Steps:**
+
+1. Create `mufl_code/config.mufl`. The core ships its own compile configuration whose
+   `$exports` block lists the seven libraries; your top-level config pulls it in with
+   `config_load #"core"` and merges it with the stdlib:
+
+   ```mufl
+   config script
+   {
+       stdlib_config = (config_load #$MUFL_STDLIB_PATH).
+       core_config = (config_load #"core").
+       (
+           $imports ->
+           (
+               $libraries ->
+                   (stdlib_config $exports $libraries)
+                   '(core_config $exports $libraries)
+                   '($protocol_container -> #"protocol_container.mm"),
+           ),
+           $exports -> ( $libraries -> (,), $applications -> (,) )
+       ).
+   }
+   ```
+
+2. Create `mufl_code/protocol_container.mm`. This is a **boot requirement**: the SDK
+   runs `::protocol_container::init_my_ipd` on every packet during broker registration,
+   so every application packet must ship this library (the config above maps it in).
+   [03 · Wire the host](./03-wire-the-host.md) explains the boot sequence; the stub is:
+
+   ```mufl
+   // Minimal protocol_container library — provides ::protocol_container::init_my_ipd,
+   // which the ADAPT wrapper runs on every packet during broker registration
+   // (possession-proof / identity-proof-document setup). Mirrors the toolkit's
+   // per-unit protocol_container stub; deps resolve from the stdlib.
+   library protocol_container loads libraries
+       identity_proof_document,
+       identity_proof_document_types,
+       native_attestation_document,
+       browser_attestation_document,
+       current_transaction_info
+       uses transactions
+   {
+       trn init_my_ipd _ {
+           current_transaction_info::validate_origin (::transaction::envelope::origin::user,).
+           identity_proof_document_types::set_my_ipd(identity_proof_document::create()).
+           return ::transaction::success [].
+       }
+   }
+   ```
+
+3. Create a minimal application, `mufl_code/my_agent.mu`. The file name is yours; the
+   application **name** must be `actor` (the wire-visible inbound transaction names are
+   `::actor::*` — [03 · Wire the host](./03-wire-the-host.md) covers why):
+
+   ```mufl
+   // Minimal first packet: proves the config merge + compile work.
+   application actor loads libraries
+       protocol_container,
+       version
+       uses transactions
+   {
+       trn readonly get_version _ { return ($core -> (version::get_core_version NIL)). }
+   }
+   ```
+
+4. Compile from inside `mufl_code/`:
+
+   ```sh
+   cd mufl_code
+   MUFL_STDLIB_PATH="$ADAPT_TOOLKIT/mufl_stdlib" \
+     "$ADAPT_TOOLKIT/build.linux.release/mufl-compile" \
+     -mp "$ADAPT_TOOLKIT/meta" -mp "$ADAPT_TOOLKIT/transactions" my_agent.mu
+   ```
+
+   `Unused symbol` warnings from stdlib libraries are expected noise.
+
+**Verify:**
+
+```sh
+ls *.muflo
+```
+
+Success markers:
+
+- The compiler's last line is `SAVED TO FILE: <…muflo>`.
+- `ls *.muflo` shows exactly one content-hash-named unit, e.g.
+  `2272124BF5B3D5E124487F68AFCC075581688F01A055EBC54F8C6EC6CC3047A5.muflo`.
+
+Next: [03 · Wire the host](./03-wire-the-host.md).

package/mufl_code/core/docs/guide/03-wire-the-host.md

@@ -0,0 +1,154 @@
+# 03 · Wire the host
+
+The core deliberately owns **no storage**: your application decides where messages,
+files, and state live, and hands the core a set of hooks at init time. This page
+replaces the minimal actor from page 02 with the real host wiring. The core's own
+[`tests/test_actor.mu`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/tests/test_actor.mu)
+is the living reference implementation of this minimal wiring — the actor below is a
+trimmed version of the same pattern.
+
+Four things every host actor must get right:
+
+1. **The application is named `actor`.** Two wire-visible inbound transaction names are
+   fixed as `::actor::accept_contact` and `::actor::receive_message` (compatibility with
+   pre-migration clients — see the header of
+   [`a2a_messaging.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_messaging.mm)).
+   A peer's `send_message` delivers to `::actor::receive_message`, so your application
+   must carry that name and ship a one-line shim that delegates to
+   `a2a_messaging::handle_receive_message`. All newer inbound legs (invite redeem,
+   files, restore) are library-routed and need no shim.
+2. **Init wiring.** `key_storage`, `encrypted_channel`, and `a2a_messaging` each take an
+   `init` call in your actor's `hidden` block: the first two need the `_read_or_abort`
+   deserialization primitive; `a2a_messaging::init` additionally takes your storage
+   hooks (`on_message_received`, `on_message_sent`, `on_contact_removed`,
+   `on_file_received`, `on_file_sent`). Hooks return host-protocol *actions* — the
+   `return_data` records your Node driver resolves on (page 04).
+3. **Export/import composition.** The core's portable state is
+   `a2a_messaging::export_core_state` / `import_core_state`; your `export_state` wraps
+   it under a `$core` key **alongside** your own app state, so a migration moves both.
+   Ephemeral invite secrets are deliberately excluded from the export.
+4. **Packet-boot requirement.** The SDK runs `::protocol_container::init_my_ipd` on
+   every packet during broker registration — that is why page 02 shipped the
+   `protocol_container` stub and why the actor loads it. Note: REAL multi-process broker
+   routing additionally requires a `registration_proof` (a broker nonce-challenge); the
+   local loopback used in pages 04–05 delivers packets inside one wrapper process, so it
+   never exercises that step. When you move to a deployed broker, use a consumer repo's
+   registration wiring as your reference.
+
+**Prereqs:**
+
+- [02 · Configure & compile](./02-configure-and-compile.md) completed (first `.muflo` built).
+- `$ADAPT_TOOLKIT` exported.
+
+**Steps:**
+
+1. Replace `mufl_code/my_agent.mu` with the wired actor:
+
+   ```mufl
+   // my_agent — a minimal host actor consuming the ours-mufl-core protocol.
+   // Modeled on the core's own tests/test_actor.mu (the living reference for
+   // minimal host wiring): storage hooks, init wiring, export/import composition.
+   application actor loads libraries
+       identity_proof_document,
+       attestation_document,
+       native_attestation_document,
+       transaction_message_decoder,
+       address_document,
+       address_document_types,
+       key_utils,
+       key_storage,
+       continuation,
+       encrypted_channel,
+       a2a_protocol,
+       a2a_messaging,
+       current_transaction_info,
+       protocol_container,
+       version
+       uses transactions
+   {
+       hidden
+       {
+           // The app owns message storage; the core calls the hook.
+           metadef msg_t: ($sender -> global_id, $text -> str, $wire_id -> str).
+           inbox is msg_t[] = [].
+
+           // Wire the deserialization primitive into the libraries that need it.
+           _read_or_abort = grab( _read_or_abort ).
+           key_storage::init ($_read_or_abort -> _read_or_abort).
+           encrypted_channel::init ($_read_or_abort -> _read_or_abort).
+
+           // Host-protocol action helpers (the driver resolves on kind "data").
+           fn _save_state (_) = (transaction::action::return_data ($kind -> $save_state)).
+           fn _return_data (payload: any) = (transaction::action::return_data ($kind -> $data, $payload -> payload)).
+           fn _notify_agent (payload: any) = (transaction::action::return_data ($kind -> $notify_agent, $payload -> payload)).
+
+           // Storage hooks: deposit inbound messages; the rest are no-ops here.
+           a2a_messaging::init (
+               $_read_or_abort -> _read_or_abort,
+               $on_message_received -> fn (arg: any) -> transaction::action::type[]
+               {
+                   sid = (arg $sender_id) safe global_id.
+                   txt = (arg $text) safe str.
+                   wid is str = "".
+                   if (arg $wire_id) != NIL { wid -> (arg $wire_id) safe str. }
+                   inbox (_count inbox|) -> ($sender -> sid, $text -> txt, $wire_id -> wid).
+                   return [ _notify_agent ($event -> $message_received), _save_state NIL ].
+               },
+               $on_message_sent -> fn (_: any) -> transaction::action::type[] { return []. },
+               $on_contact_removed -> fn (_: any) -> transaction::action::type[] { return []. },
+               $on_file_received -> fn (_: any) -> transaction::action::type[] { return []. },
+               $on_file_sent -> fn (_: any) -> transaction::action::type[] { return []. }
+           ).
+       }
+
+       // The core's send_message delivers to the legacy ::actor::receive_message name;
+       // this shim routes it into the core receive handler (→ on_message_received hook).
+       trn receive_message args: any { return a2a_messaging::handle_receive_message args. }
+       trn readonly list_incoming_messages _ { return ($inbox -> inbox). }
+
+       // Version probe: the compiled-in core version, observable at runtime.
+       trn readonly get_version _ { return ($core -> (version::get_core_version NIL)). }
+
+       // Migration: compose YOUR app state around the core's portable export.
+       trn readonly export_state _
+       {
+           return ($core -> (a2a_messaging::export_core_state NIL), $app -> ($inbox -> inbox)).
+       }
+       trn import_state data: any
+       {
+           current_transaction_info::validate_origin_or_abort (transaction::envelope::origin::user,).
+           a2a_messaging::import_core_state (data $core).
+           inbox -> ((data $app $inbox) safe (msg_t[])).
+           return transaction::success [ _return_data ($imported -> TRUE), _save_state NIL ].
+       }
+   }
+   ```
+
+   Syntax gotcha: typed-list casts need parentheses — `safe (msg_t[])`, not
+   `safe msg_t[]`.
+
+2. Recompile (remove the previous unit first; the output name is a content hash, so a
+   changed source produces a *second* `.muflo` otherwise):
+
+   ```sh
+   cd mufl_code
+   rm -f *.muflo
+   MUFL_STDLIB_PATH="$ADAPT_TOOLKIT/mufl_stdlib" \
+     "$ADAPT_TOOLKIT/build.linux.release/mufl-compile" \
+     -mp "$ADAPT_TOOLKIT/meta" -mp "$ADAPT_TOOLKIT/transactions" my_agent.mu
+   ```
+
+**Verify:**
+
+```sh
+ls *.muflo
+```
+
+Success markers:
+
+- Compiler ends with `SAVED TO FILE: <…muflo>`.
+- `ls *.muflo` shows exactly one unit (a new hash — the old one is gone).
+
+For what the hooks feed into — deferred sends, degraded contacts, restore — see
+[Messaging](../how-it-works/messaging.md). Next:
+[04 · Connect & message](./04-connect-and-message.md).

package/mufl_code/core/docs/guide/04-connect-and-message.md

@@ -0,0 +1,156 @@
+# 04 · Connect & message
+
+Time to run the packet. The `@adapt-toolkit` Node SDK boots compiled units, a local
+dev broker relays between them, and a small driver script walks the protocol:
+`generate_invite` on one packet, `add_contact` on the other, then `send_message` both
+ways — asserting **receiver-side** state (the peer's inbox and contact book), not just
+that a send returned. This is the same loopback pattern the core's own
+[`tests/test.mjs`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/tests/test.mjs)
+uses. For what the three legs of the invite redeem do on the wire, see
+[Invites & contacts](../how-it-works/invites-and-contacts.md).
+
+**Prereqs:**
+
+- [03 · Wire the host](./03-wire-the-host.md) completed (wired `.muflo` in `mufl_code/`).
+- `$OURS_SDK_NODE_MODULES` and `$DEV_BROKER` exported (see [Start here](./index.md)).
+- Node 18+.
+
+**Steps:**
+
+1. Make the SDK resolvable from `mufl_code/` (both the driver and the broker launcher
+   need a `node_modules` that contains `@adapt-toolkit`):
+
+   ```sh
+   cd mufl_code
+   ln -sfn "$OURS_SDK_NODE_MODULES" node_modules
+   ```
+
+2. Create `mufl_code/drive.mjs`:
+
+   ```js
+   #!/usr/bin/env node
+   // Loopback driver: two packets of YOUR app on one local broker.
+   // invite -> contact -> message, asserted RECEIVER-side.
+   import { resolve } from 'node:path';
+   import * as fs from 'node:fs';
+   import { adapt_wrapper } from '@adapt-toolkit/sdk/executables';
+   import { PacketWrapperConfigurator } from '@adapt-toolkit/sdk/wrappers';
+   import { object_to_adapt_value } from '@adapt-toolkit/sdk/wrapper';
+
+   const BROKER_URL = process.env.BROKER_URL || 'ws://127.0.0.1:9799';
+   const UNIT_DIR = resolve('.');
+   const unitHash = fs.readdirSync(UNIT_DIR).find((f) => f.endsWith('.muflo')).slice(0, -'.muflo'.length);
+   const UNIT = new Uint8Array(fs.readFileSync(resolve(UNIT_DIR, `${unitHash}.muflo`)));
+   const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+   let failures = 0;
+   const ok = (c, m) => { console.log(`${c ? 'ok' : 'FAIL'} - ${m}`); if (!c) failures++; };
+
+   let wrapper;
+   function mk(name) { return { name, pw: null, cid: '', pending: [] }; }
+   function wire(id) {
+     id.pw.on_return_data = (d) => {
+       const kind = d.Reduce('kind').Visualize();
+       if (kind !== 'data') return; // ignore save_state / notify_agent here
+       const p = id.pending.shift(); if (!p) return;
+       clearTimeout(p.timer); p.resolve(d.Reduce('payload'));
+     };
+     id.pw.on_transaction_failure = (msg) => {
+       const p = id.pending.shift();
+       if (p) { clearTimeout(p.timer); p.reject(new Error(msg)); }
+     };
+   }
+   function mutate(id, name, targ) {
+     return new Promise((res, rej) => {
+       const timer = setTimeout(() => rej(new Error(`${id.name}.${name} timed out`)), 20000);
+       id.pending.push({ resolve: res, reject: rej, timer });
+       id.pw.add_client_message(object_to_adapt_value({ name, targ }));
+     });
+   }
+   const ro = (id, name) => id.pw.packet.ExecuteTransaction(object_to_adapt_value({ name, targ: undefined }));
+   const binv = (id, buf) => id.pw.packet.NewBinaryFromBuffer(Buffer.from(buf));
+   async function mkPacket(id, seed) {
+     const cfg = new PacketWrapperConfigurator();
+     cfg.process_arguments(['--unit_hash', unitHash, '--seed_phrase', seed, '--unit_dir_path', UNIT_DIR]);
+     await new Promise((res, rej) => {
+       const t = setTimeout(() => rej(new Error(`${id.name} create timeout`)), 30000);
+       wrapper.packet_manager.create_packet(cfg, (pw) => {
+         clearTimeout(t); id.pw = pw; id.cid = pw.packet.GetContainerID().Visualize(); wire(id); res();
+       }, UNIT);
+     });
+   }
+
+   async function main() {
+     wrapper = await adapt_wrapper.start(['--broker_address', BROKER_URL, '--test_mode',
+       '--logger_config', '--level', 'WARNING', '--stdout', 'stderr', '--logger_config_end']);
+     wrapper.start();
+     await sleep(1500);
+
+     const A = mk('A'); const B = mk('B');
+     await mkPacket(A, 'my-app-A-01'); await mkPacket(B, 'my-app-B-02');
+     await sleep(1200);
+     await mutate(A, '::a2a_messaging::set_my_name', { name: 'Alice' });
+     await mutate(B, '::a2a_messaging::set_my_name', { name: 'Bob' });
+
+     // compiled-in core version is observable at runtime
+     console.log('core version:', ro(A, '::actor::get_version').Reduce('core').Visualize());
+
+     // 1. A mints an invite
+     const m = await mutate(A, '::a2a_messaging::generate_invite', { name: 'Bob' });
+     const invite = Buffer.from(m.Reduce('invite').GetBinary());
+     ok(invite.length > 0, 'generate_invite returned an invite blob');
+
+     // 2. B redeems it
+     await mutate(B, '::a2a_messaging::add_contact', { invite: binv(B, invite), name: 'Alice' });
+     await sleep(5000);
+
+     // 3. RECEIVER-side: both contact books list the other
+     const lcA = ro(A, '::a2a_messaging::list_contacts').Visualize();
+     const lcB = ro(B, '::a2a_messaging::list_contacts').Visualize();
+     ok(new RegExp(B.cid).test(lcA), 'A list_contacts includes B cid');
+     ok(new RegExp(A.cid).test(lcB), 'B list_contacts includes A cid');
+
+     // 4. message round-trips over the encrypted channel, both directions
+     await mutate(A, '::a2a_messaging::send_message', { contact: B.cid, text: 'hello from Alice' });
+     await sleep(2500);
+     ok(/hello from Alice/.test(ro(B, '::actor::list_incoming_messages').Visualize()),
+       'B received A message (receiver-side inbox)');
+     await mutate(B, '::a2a_messaging::send_message', { contact: A.cid, text: 'hello from Bob' });
+     await sleep(2500);
+     ok(/hello from Bob/.test(ro(A, '::actor::list_incoming_messages').Visualize()),
+       'A received B message (receiver-side inbox)');
+
+     console.log(failures === 0 ? 'ROUND-TRIP OK' : `${failures} FAILURE(S)`);
+     await sleep(500);
+     process.exit(failures === 0 ? 0 : 1);
+   }
+   main().catch((e) => { console.error('DRIVER ERR:', e.stack ?? e.message); process.exit(1); });
+   ```
+
+   Reading the driver: `mutate` submits a state-changing transaction through the
+   wrapper's client-message path and resolves on the `$kind -> $data` action your hooks
+   returned; `ro` executes a read-only transaction synchronously. The SDK's leak-tracker
+   prints `###` lines at exit — expected noise.
+
+3. Start the dev broker, run the driver, stop the broker:
+
+   ```sh
+   node "$DEV_BROKER" --host 127.0.0.1 --port 9799 --test_mode > broker.log 2>&1 &
+   sleep 3
+   BROKER_URL=ws://127.0.0.1:9799 node drive.mjs 2>/dev/null | grep -vE '^###'
+   echo "EXIT=${PIPESTATUS[0]}"
+   kill %1
+   ```
+
+**Verify:** the driver prints a `core version:` line (the `MAJ`/`MIN`/`PATCH` of the
+core revision you vendored — see [Versioning](../how-it-works/versioning.md)) and five
+`ok -` assertion lines, ending with the success markers:
+
+```
+ok - A received B message (receiver-side inbox)
+ROUND-TRIP OK
+EXIT=0
+```
+
+Any `FAIL -` line or a non-zero `EXIT` means the round-trip did not complete.
+
+Next: [05 · Test your app](./05-test-your-app.md).

package/mufl_code/core/docs/guide/05-test-your-app.md

@@ -0,0 +1,75 @@
+# 05 · Test your app
+
+Two layers of testing keep a consumer honest: a **loopback suite for your own app**,
+and the **core's own suite** run against the exact core revision you vendored.
+
+## The loopback pattern for your app
+
+Grow `drive.mjs` from page 04 into a real suite the way the core's tests do
+(see [`tests/README.md`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/tests/README.md)):
+
+- **A derived test actor.** Don't test against your production actor alone — derive a
+  test build that adds `qa_*` probe transactions: read-only state counters
+  (`qa_state`-style counts of contacts, peer ADs, pending invites), exporters
+  (`qa_export_ad`), and adversarial injectors that bare-send crafted wire payloads. The
+  core's [`tests/test_actor.mu`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/tests/test_actor.mu)
+  shows the full probe vocabulary.
+- **Assert receiver-side.** A send that "succeeded" proves little; assert the *peer's*
+  state changed (its inbox, its contact book) and that rejected inputs changed
+  *nothing* — the core suite's negative scenarios (replayed invites, tampered boxes,
+  foreign address documents) all assert state-unchanged on the target.
+- **One broker, many packets.** Spin all packets on one `dev-broker.mjs` in
+  `--test_mode`; inbound aborts surface via `on_transaction_failure`, so collect them
+  per-packet and grep them in assertions.
+
+## Run the core's own suite (sanity check)
+
+The vendored submodule ships its suite: 10 scenarios, 36+ assertions over invite
+redeem, tamper rejection, export secrecy, and migration
+(see [Invites & contacts](../how-it-works/invites-and-contacts.md)). Running it against
+your checkout proves your toolkit + SDK + broker environment is sound and the core
+revision you pinned behaves as released.
+
+**Prereqs:**
+
+- Pages [01](./01-vendor-the-core.md)–[04](./04-connect-and-message.md) completed.
+- `$ADAPT_TOOLKIT`, `$OURS_SDK_NODE_MODULES`, `$DEV_BROKER` exported.
+- No leftover dev broker on the chosen port (the suite boots its own; `PORT=9791`
+  below avoids clashing with page 04's broker if you left it running).
+
+**Steps:**
+
+1. From your app repo **root** (`my-app`, not `mufl_code/`), run the suite inside the
+   submodule, pointing it at your
+   environment (`tests/run.sh` honors these as env overrides; it bundles the
+   `protocol_container.mm` stub itself, so you no longer pass one in):
+
+   ```sh
+   cd mufl_code/core
+   ADAPT_TOOLKIT="$ADAPT_TOOLKIT" \
+   OURS_SDK_NODE_MODULES="$OURS_SDK_NODE_MODULES" \
+   DEV_BROKER="$DEV_BROKER" \
+   PORT=9791 ./tests/run.sh
+   ```
+
+   The run takes a few minutes: it copies the core into a throwaway harness, compiles
+   the test actor, boots a broker on `PORT`, and drives all scenarios. `###` /
+   `Leak for AdaptValue` lines and `EVAL_ERROR` stderr noise are expected — the
+   adversarial scenarios deliberately trigger aborts.
+
+**Verify:**
+
+```sh
+echo "EXIT=$?"
+```
+
+Success markers (the verdict is the final scorecard plus the exit code):
+
+```
+================ SCORECARD ================
+ALL TESTS PASSED
+EXIT=0
+```
+
+That closes the loop: an empty directory, a vendored core, a compiled packet, a live
+encrypted round-trip, and the protocol's own suite green against your environment.

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

@@ -0,0 +1,63 @@
+# Start here
+
+> **These docs are written for agents.** ours.network expects most applications to be
+> built by coding agents working on behalf of a human. Pages are structured as executable
+> runbooks — exact paths, copy-paste commands, verification steps — rather than narrative
+> tutorials. Humans are welcome; give your agent the URL of
+> [`llms-full.txt`](https://adapt-toolkit.github.io/ours-mufl-core/llms-full.txt) and it can ingest the entire
+> documentation in one fetch.
+
+This guide takes you from an empty directory to a working ours.network application:
+a MUFL packet that **consumes** the shared protocol core, plus the host-side driver
+that boots it, connects it to a peer, and exchanges encrypted messages. Every
+ours.network client is built this way — it vendors this repo as a git submodule and
+compiles it into its own packet (see [Overview](../how-it-works/overview.md)).
+
+**Scope note — integration only.** This guide never touches protocol code. You will not
+edit any `.mm` file of the core; a change there is a protocol revision for the whole
+network. Everything you write here — your `config.mufl`, your actor (`.mu` file), your
+Node driver — is *your application*, layered on top of an unmodified core. If you think
+the protocol itself needs a change, read
+[Contributing](../reference/contributing.md) instead.
+
+## What you will build
+
+| Page | Result |
+|------|--------|
+| [01 · Vendor the core](./01-vendor-the-core.md) | The core checked out as a git submodule under `mufl_code/core` |
+| [02 · Configure & compile](./02-configure-and-compile.md) | A `config.mufl` that merges the core with the stdlib, and a first compiled packet |
+| [03 · Wire the host](./03-wire-the-host.md) | An actor with the storage hooks, init wiring, and export/import composition the core expects |
+| [04 · Connect & message](./04-connect-and-message.md) | Two packets on a local broker: invite → contact → encrypted message round-trip |
+| [05 · Test your app](./05-test-your-app.md) | A loopback test pattern for your app, plus the core's own suite as a sanity check |
+
+**Prereqs:**
+
+- The **ADAPT toolkit** — the `mufl-compile` binary plus the `mufl_stdlib` / `meta` /
+  `transactions` module trees. The pages refer to its root as `$ADAPT_TOOLKIT`
+  (`$ADAPT_TOOLKIT/build.linux.release/mufl-compile` must exist).
+- The **`@adapt-toolkit` Node SDK** — a `node_modules` directory containing
+  `@adapt-toolkit` (any ours.network consumer checkout has one). The pages refer to it
+  as `$OURS_SDK_NODE_MODULES`.
+- A **local dev broker launcher** — `dev-broker.mjs`, a thin launcher over the SDK's
+  broker exports (ships with the consumer repos). The pages refer to it as `$DEV_BROKER`.
+  It must run from a directory whose `node_modules` resolves `@adapt-toolkit`; the
+  layout built in this guide takes care of that.
+- **git** and **Node 18+**.
+
+These are the same three knobs the core's own test suite takes
+(`ADAPT_TOOLKIT` / `OURS_SDK_NODE_MODULES` / `DEV_BROKER` — see
+[05 · Test your app](./05-test-your-app.md)). Export them once per shell:
+
+```sh
+export ADAPT_TOOLKIT=/path/to/adapt-toolkit
+export OURS_SDK_NODE_MODULES=/path/to/consumer/node_modules
+export DEV_BROKER=/path/to/dev-broker.mjs
+```
+
+**Steps:** start at [01 · Vendor the core](./01-vendor-the-core.md); each page builds
+on the previous one and ends with a Verify block whose success markers come from a
+live run of exactly the commands shown.
+
+**Verify:** after page 04 you have a bidirectional encrypted round-trip
+(`ROUND-TRIP OK`, exit 0); after page 05 the core's own suite reports
+`SCORECARD` / `ALL TESTS PASSED` with exit 0.

package/mufl_code/core/docs/how-it-works/capabilities-and-control.md

@@ -0,0 +1,77 @@
+# Capabilities & control
+
+Every ours node advertises a typed app manifest — a set of named capabilities,
+each with its own schema and version — and receives structured requests through a
+shared control envelope. `a2a_capabilities.mm` owns the envelope definition and
+dispatch; `a2a_control.mm` owns the encrypted transport that carries envelopes
+between nodes.
+
+Sources:
+[`a2a_capabilities.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_capabilities.mm),
+[`a2a_control.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_control.mm).
+
+## The control envelope
+
+All inbound capability requests arrive as a `control_envelope_t` record:
+
+```mufl
+metadef control_envelope_t: ($cap -> str, $verb -> str, $args -> any, $req_id -> str).
+```
+
+- `$cap` — the stable capability id (e.g. `"core.configuration"`). Dispatch keys
+  only on this field; adding a capability never changes the wire shape.
+- `$verb` — the operation within that capability.
+- `$args` — native-typed arguments the handler interprets per verb.
+- `$req_id` — correlation token. The sender receives a `response_envelope_t`
+  keyed on `(sender_id, $req_id)`. An empty `$req_id` signals fire-and-forget:
+  the envelope is processed but no response is expected.
+
+## Transport
+
+`send_control` in `a2a_control.mm` delivers an opaque payload to a named contact
+over the `encrypted_channel`. The inbound side is the `control_message`
+transaction, which validates origin and sender before invoking the
+`$on_control_received` hook the app wires at startup.
+
+The `a2a_capabilities` dispatch layer sits one step above this transport: the
+app adapts the opaque `control_message` payload into a `control_envelope_t`
+record and calls `dispatch`.
+
+## Dispatch and the authz chokepoint
+
+`dispatch` enforces a single, non-bypassable pre-route authorization check
+before any handler runs:
+
+1. `control_auth_class($cap, $verb)` classifies the requested operation as
+   `"bootstrap"`, `"controller"`, or `"deny"`. (`get_manifest` is a standalone
+   `trn readonly` that never routes through dispatch and is not classified here.)
+2. `"controller"` verbs require the stateful `authorizer` gate (wired at init via
+   `a2a_messaging::authorize_control`) to confirm the sender is the bound control
+   plane. The gate is fail-closed: an unset authorizer aborts rather than
+   permitting the verb.
+3. Unknown or unlisted cap/verb combinations always classify as `"deny"` — a new
+   verb must be consciously listed in `control_auth_class` to become reachable.
+
+Handlers run only after this chokepoint clears. They return
+`transaction::action::type[]` arrays; the daemon marshals responses to JSON and
+ships them — no in-MUFL JSON encoding, no ad-hoc send inside a handler.
+
+## Well-known capability ids
+
+Four ids are reserved in `a2a_capabilities.mm`:
+
+| Constant | Value | Purpose |
+|---|---|---|
+| `cap_configuration` | `"core.configuration"` | Opaque app config, read/written only by the bound control plane. |
+| `cap_monitoring` | `"core.monitoring"` | Monitoring bind ceremony and disable. |
+| `cap_connect` | `"core.connect"` | Peer introduction via the control plane. |
+| `cap_cluster` | `"core.cluster"` | Child/subagent lifecycle and contact management. |
+
+The `"core.*"` namespace is reserved; application capabilities use `"app.*"`.
+Every node advertises `core.monitoring` — it is governance-required and
+auto-present. Adding a new capability means registering a new id string and
+wiring its handler; the wire shape is unchanged.
+
+See [Cluster](./cluster.md) for the `core.cluster` verb surface, and
+[Monitoring & config](./monitoring-and-config.md) for how `core.monitoring` and
+`core.configuration` interact with the hidden gate state in `a2a_messaging`.