@ours.network/notifications 0.1.1

package/mufl_code/core/docs/how-it-works/cluster.md

@@ -0,0 +1,65 @@
+# Cluster
+
+The `core.cluster` capability, defined in `a2a_cluster.mm`, gives a root node a
+uniform surface for child/subagent lifecycle, per-child monitoring authorization,
+the host-local contact book, and introductions between children and contacts.
+The authz chokepoint in `a2a_capabilities::dispatch` gates every verb — handlers
+run only after it clears.
+
+Source: [`a2a_cluster.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_cluster.mm).
+
+## Registry
+
+The root packet holds a `cluster_members` map (keyed by container id) of
+`member_t` rows. Each row tracks the child's name, role id, bio, persona,
+current monitoring state, and advertised capability ids. The registry is a
+projection of host truth: `reconcile` runs on boot and on a periodic schedule to
+add children the host knows about but the registry doesn't, and to drop members
+the host has removed.
+
+```mufl
+metadef member_t: ($cid -> global_id, $role_id -> str, $name -> str,
+                   $bio -> str, $persona -> str, $monitoring -> str, $caps -> str[]).
+```
+
+## Lifecycle verbs
+
+The `cluster_handler` function switches on the `$verb` field of each inbound
+`control_envelope_t` and dispatches to the appropriate handler. The authorized
+bare verb names (as they appear on the wire and in `control_auth_class`) are:
+
+| Verb | Effect |
+|---|---|
+| `list` | Returns the current `cluster_members` registry. |
+| `set_bio` | Updates the bio field for a child in the registry (registry-only, no host op). |
+| `set_persona` | Updates the persona field for a child in the registry (registry-only, no host op). |
+| `set_monitoring` | Emits a `host_set_child_monitoring` notify-action; confirmed by `confirm_child_monitoring`. |
+| `create` | Emits a `host_provision_child` notify-action; the daemon provisions the child packet and calls back `register_provisioned_child`. |
+| `remove` | Emits a `host_destroy_child` notify-action; confirmed by `confirm_child_destroyed`. |
+| `contact` | Emits a `host_mint_child_invite` notify-action; the daemon runs `generate_invite` inside the child packet and calls back `register_child_invite`. |
+| `introduce` | Composes `a2a_messaging::emit_pair` to introduce two established contacts to each other. |
+
+For the full verb surface see [`a2a_cluster.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_cluster.mm).
+
+Create and remove are asynchronous: the handler stores a pending-req (keyed by a
+monotonic handle) and immediately acknowledges `{pending: true}`. The matching
+host callback consumes the pending-req atomically and routes the final response to
+the stored controller.
+
+## Per-child monitoring authorization
+
+`set_monitoring` derives the control-plane identity from the root's own
+ceremony-pinned `monitoring_proxy` — never from the request args. The root must
+be bound to a cluster control plane before enabling monitoring for any child.
+Disabling does not require a bound CP; it clears the child's proxy immediately.
+
+## Cross-cluster introductions
+
+The `introduce` verb accepts two contact references (`$peer_a`, `$peer_b`) and
+emits a pair of introduction messages via `a2a_messaging::emit_pair`. Both peers
+must already be established contacts with stored address documents. The
+`core.connect` capability exposes the same `introduce` verb (via
+`connect_handler`) for peer-to-peer introduction without cluster context.
+
+See [Capabilities & control](./capabilities-and-control.md) for the envelope and
+dispatch model that gates every verb above.

package/mufl_code/core/docs/how-it-works/identity.md

@@ -0,0 +1,56 @@
+# Identity: roots & roles
+
+An identity in ours.network is either a **root** — a self-sovereign keypair — or a **delegated
+role** anchored to a root. A root's `delegation_cert` field is `NIL`; detection is structural,
+not a flag. A role carries a signed `delegation_cert_t` that binds the role's container id and
+address-document hash to its root, signed by the root's keys.
+
+Source: [`a2a_protocol.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_protocol.mm).
+
+## Delegation verification
+
+When a peer presents its identity during invite redemption, verify the full chain with
+`verify_peer_delegation`:
+
+```
+fn verify_peer_delegation (
+    peer_cid:    global_id,
+    peer_ad_hash: hash_code,
+    cert:         delegation_cert_t,
+    rp:           root_profile_t
+) -> contact_root_t
+```
+
+The root profile carries the root's key list, so no prior knowledge of the root is needed. On
+success the function returns a `contact_root_t` (root container id, root name, role id) to store
+beside the contact. Any mismatch — wrong version, mismatched cid, bad signature — aborts.
+
+## Control-plane governance (§3c)
+
+Two verifiers support the optional non-enforcing governance edge between a root and its control
+plane:
+
+- **`verify_cp_attestation`** — verifies the CP's signed attestation that it governs a given
+  root. Requires the caller to have run `process_address_document` on the CP's address document
+  first.
+- **`verify_root_cp_binding`** — verifies the root's self-signed edge naming the CP, domain-
+  separated by `cp_attestation_context_tag`. The authoritative monitoring gate remains the
+  6-digit bind ceremony; these verifiers let peers TOFU-pin the governance edge without an extra
+  round-trip.
+
+Source: [`a2a_protocol.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_protocol.mm).
+
+## Wire shapes and the structural-records rule
+
+All identity wire shapes are MUFL record types defined in `a2a_protocol.mm`. The key protocol
+guarantee is: moving a shape between libraries never changes its bytes; renaming or retyping a
+`$field` does. Field names are the version boundary. Example shapes:
+
+```
+metadef delegation_cert_t: ($c -> delegation_core_t, $s -> crypto_signature).
+metadef root_profile_t:    ($p -> root_profile_core_t, $s -> crypto_signature).
+metadef root_cp_binding_t: ($c -> root_cp_binding_core_t, $s -> crypto_signature).
+```
+
+The invite shape carries no identity keys — identity material moves inside the encrypted
+two-message redeem hop (see [Invites & contacts](./invites-and-contacts.md)).

package/mufl_code/core/docs/how-it-works/invites-and-contacts.md

@@ -0,0 +1,76 @@
+# Invites & contacts
+
+Contact establishment uses a **slim ephemeral-key invite**. The invite blob carries
+only an ephemeral encryption pubkey, the inviter's container id, a display name, and a crypto
+scheme id — no long-term keys, no self-signatures. Identity material moves inside two encrypted
+messages exchanged after the initial out-of-band transfer.
+
+Source: [`a2a_messaging.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_messaging.mm).
+Sequence diagrams: [Contact exchange](../workflows/contact-exchange.md) and
+[Introductions](../workflows/introductions.md).
+
+## Invite shape
+
+```
+metadef invite_eph_t: (
+    $d -> global_id,          -- invite id (correlates legs; single-use)
+    $c -> global_id,          -- inviter container id
+    $n -> str,                -- inviter display name
+    $k -> publickey_encrypt,  -- inviter ephemeral pubkey
+    $v -> int                 -- crypto scheme id
+).
+```
+
+Generate an invite with `generate_invite`. The returned blob is the value to share out-of-band
+(QR code, deep link, etc.).
+
+## Three-leg redeem flow
+
+| Leg | Direction | Mechanism | What moves |
+|-----|-----------|-----------|------------|
+| OOB | inviter → responder | out-of-band | slim `invite_eph_t` blob |
+| Leg 1 | responder → inviter | BARE send (box to invite's eph pub) | responder identity bundle |
+| Leg 2 | inviter (receives leg 1) | verify bundle, consume invite, emit leg 3 | ← inviter now holds responder's verified AD |
+| Leg 3 | inviter → responder | BARE send (box to responder's eph pub) | inviter identity bundle |
+
+Both boxes carry the same identity bundle shape: address document + optional delegation cert +
+optional root profile + optional §3c CP binding. After leg 3, both sides hold the other's
+verified address document and `encrypted_channel` resumes for all subsequent traffic.
+
+Redeem an invite with `add_contact` (leg 1). The inviter processes the responder's leg 1 via
+`submit_invite_response` and replies with leg 3 (`complete_invite`).
+
+## Single-use guarantee
+
+An invite is consumed at the first valid leg-2 (inviter's receipt of leg 1). A second attempt for the same
+`invite_id` aborts with `already-redeemed` and mutates no state. The ephemeral private key is
+deleted atomically with the invite record (INV-4: secrets are never exported).
+
+Test suite scenario T3 (`single-use`) asserts a second leg-1 for the same `invite_id` aborts
+and leaves inviter state unchanged. Scenario T4 (`invalid-then-valid`) asserts that a failed
+box-open does not consume the invite, so a subsequent valid redeem succeeds. See
+[`tests/README.md`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/tests/README.md).
+
+## Pending-invite transience
+
+Responder-side pending redemption state (`pending_redemptions`) is not exported and does not
+survive a daemon restart. An interrupted handshake does not leave half-registered state; the
+responder must run `add_contact` again with a fresh invite. This is the fail-closed design: no
+dangling partial contacts after a restart.
+
+## Introductions via core.connect
+
+When two nodes share a control plane that advertises `core.connect`, the CP can introduce them
+without another out-of-band invite. The CP sends each node the other's signed address document
+via `ingest_connect_descriptor`. The receiving node verifies:
+
+1. The relay came from its bound CP (or the CP its root designated).
+2. Its own live manifest advertises `core.connect`.
+3. The peer's address document self-signature is valid (proof-of-possession).
+
+The contact is registered immediately — no SAS, no confirmation step.
+
+Scenario T1 (`happy-flat`) verifies the end-to-end invite + `send_message` round-trip in both
+directions. Scenarios T5–T8 cover adversarial inputs (tampered box, cid-bind mismatch, stripped
+PoP, unexpected inviter on leg 3). See
+[`tests/README.md`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/tests/README.md).

package/mufl_code/core/docs/how-it-works/messaging.md

@@ -0,0 +1,55 @@
+# Messaging
+
+All message and file traffic between contacts rides the `encrypted_channel`, established during
+invite redemption and persisted across restarts by replaying stored peer address documents on
+import. `a2a_messaging.mm` is the single path for all send/receive operations.
+
+Source: [`a2a_messaging.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_messaging.mm).
+Module description: [`README.md`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/README.md)
+— "Contact and messaging transactions (generate invite, add/remove contact, send message, send
+file, inbound receive) and the introduction flow."
+
+Sequence diagrams: [Send & receive messages](../workflows/messaging.md) and
+[Contact restore](../workflows/contact-restore.md).
+
+## Outbound
+
+- **`send_message`** — sends text to a named or container-id-referenced contact. Accepts an
+  optional `reply_to` pointer (`$wire_id`, `$sentence`) for threaded replies. Every message
+  receives a stable `wire_id` (a stringified `_new_id`) that the peer can reference in its own
+  replies.
+- **`send_file`** — sends binary data with a `$filename` and optional `$mime`. Files and text
+  messages share the same `wire_id` namespace; a reply pointer can reference either.
+
+Both fail if the contact has no registered address document (see Contact-restore below).
+
+## Inbound
+
+| Transaction name | Source constant | Payload |
+|-----------------|-----------------|---------|
+| `::actor::receive_message` | `receive_message_tx` | `$text`, `$wire_id`, optional `$reply_to`, sender id from envelope |
+| `::a2a_messaging::receive_file` | `receive_file_tx` | `$filename`, `$mime`, `$data`, `$wire_id`, optional `$reply_to` |
+
+The core fires the app-injected `on_message_received` / `on_file_received` storage hooks.
+Message storage is the consumer's responsibility; the core handles wire, validation, and contact
+resolution.
+
+## Receiver-side state
+
+`contacts` (keyed by container id) and `peer_ads` (keyed by container id) are the persistent
+contact state. `encrypted_channel` resolves the peer's encryption key from `peer_ads` on every
+send. `peer_ads` entries survive code upgrades because `import_core_state` replays each stored
+address document through `process_address_document` — no re-handshake is needed.
+
+## Contact-restore across breaking changes
+
+If a migration carries `contacts` but drops `peer_ads` for a contact, that contact becomes a
+**DEGRADED contact** (cid present, no address document). `send_message` to a degraded contact
+queues the message and fires a `request_contact_restore` handshake to re-fetch the peer's
+address document. Once the peer's AD is re-established, queued messages flush automatically.
+
+`send_file` to a degraded contact fails fast with an explicit error — binary payloads are not
+queued. `send_message` toward the same contact will queue and drive the restore.
+
+See [Identity: roots & roles](./identity.md) for the address document and key structure that
+`encrypted_channel` depends on.

package/mufl_code/core/docs/how-it-works/monitoring-and-config.md

@@ -0,0 +1,72 @@
+# Monitoring & config
+
+Monitoring and configuration state is split across two libraries by where the
+hidden gate state lives: `a2a_messaging.mm` owns the node-side gate and copy
+generation; `a2a_monitoring.mm` owns the control-plane receiver.
+
+Sources:
+[`a2a_messaging.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_messaging.mm),
+[`a2a_monitoring.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_monitoring.mm).
+
+## Node side: forced copies
+
+The `monitoring_proxy` field in `a2a_messaging` is declared `hidden`. That means
+only code inside `a2a_messaging` can write it — an app or any other loading
+library cannot assign `monitoring_proxy -> NIL` to suppress copies. The
+`monitor_copy_actions` function gates every outbound and inbound message on this
+field:
+
+```mufl
+fn monitor_copy_actions (direction: str, peer_cid: global_id, date: time, body: str) -> transaction::action::type[]
+```
+
+If `monitoring_proxy` is `NIL`, the function returns an empty action list and
+no copy is sent. If it is set, the function appends an encrypted send to the
+bound control plane on every message. The copy rides a distinct transaction
+(`receive_monitoring_copy_tx`) so the control plane can distinguish it from
+regular traffic.
+
+## Bind ceremony
+
+`set_proxy_pending` and `verify_proxy_code` in `a2a_messaging` implement the
+6-digit bind ceremony that sets `monitoring_proxy`. They live in this library
+— not in `a2a_monitoring` — precisely because `monitoring_proxy` is hidden here.
+The ceremony is time-limited (300 seconds), attempt-limited (3 tries), and
+requires code possession. Once verified, `monitoring_proxy` is set and copy
+generation begins immediately.
+
+Disable (`core.monitoring / disable` verb) requires the sender to be the bound
+control plane; it clears `monitoring_proxy` so copy generation stops.
+
+## Control-plane side: receiving copies
+
+`a2a_monitoring.mm` is the CP-side library. It touches no gate state — it only
+validates that the sender is a known contact and hands the copy to the app's
+storage hook:
+
+```mufl
+trn receive_monitoring_copy args: any
+```
+
+The app wires the `$on_monitoring_copy_received` hook at init. Storage is
+entirely app-side; the core handles wire validation and contact checks.
+
+## Configuration
+
+App configuration (`core.configuration`) is stored as an opaque string
+(`app_config`) in `a2a_messaging`, also `hidden`. The bound control plane writes
+it via the `set_config` verb and reads it via `get_config` — both
+`core.configuration` capability verbs authorized in
+`a2a_capabilities::control_auth_class`. (`get_app_config` is a local readonly
+transaction in `a2a_messaging` used only by the node's own wrapper.) The
+`authorize_control` function in `a2a_messaging` enforces that only the bound
+control plane (the same identity that passed the monitoring ceremony) may
+invoke these verbs — the configuration and monitoring authorities are the same
+party.
+
+The `$params` field in a `capability_t` descriptor carries the opaque config
+schema for a frontend to render; the core stores only the raw blob and never
+interprets it.
+
+See [Capabilities & control](./capabilities-and-control.md) for the dispatch and
+authz model, and [Cluster](./cluster.md) for per-child monitoring authorization.

package/mufl_code/core/docs/how-it-works/overview.md

@@ -0,0 +1,45 @@
+# Overview
+
+ours-mufl-core is the shared wire format and verification logic for the ours.network protocol,
+written as MUFL (`.mm`) libraries. Every ours.network client — agent server, web messenger,
+Telegram connector — vendors this repo as a git submodule and compiles the same libraries into
+its own packet. Because all clients link the same code, they speak an **identical wire format**
+and verification logic: a packet built by the web client and one built by the MCP agent are
+byte-compatible peers.
+
+The host application boots packets, routes inbound messages, and persists state. The protocol
+libraries define what is valid; the host only moves bytes.
+
+## Consuming the core
+
+Add the repo as a submodule to your application:
+
+```sh
+git submodule add git@github.com:adapt-toolkit/ours-mufl-core.git mufl_code/core
+```
+
+Your `config.mufl` loads it with `config_load #"core"`. The full setup is in
+[01 · Vendor the core](../guide/01-vendor-the-core.md).
+
+## Modules at a glance
+
+Seven `.mm` libraries and one config export. See [Modules](../reference/modules.md) for
+per-module purpose and source links.
+
+| File | Role |
+|------|------|
+| [`a2a_protocol.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_protocol.mm) | Wire shapes (invites, certs, profiles) and verification helpers |
+| [`a2a_messaging.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_messaging.mm) | Invite, contact, send/receive message, and send/receive file transactions |
+| [`a2a_capabilities.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_capabilities.mm) | App manifest, verb dispatch, well-known capabilities |
+| [`a2a_cluster.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_cluster.mm) | Child lifecycle, host-local contact book, cluster management |
+| [`a2a_monitoring.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_monitoring.mm) | Monitoring copy receiver (CP side) |
+| [`a2a_control.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_control.mm) | Control-plane transport |
+| [`version.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/version.mm) | Core version, readable at runtime via `get_core_version` |
+
+Source: [`README.md`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/README.md).
+
+## Next steps
+
+- [Identity: roots & roles](./identity.md) — delegation hierarchy and verification
+- [Invites & contacts](./invites-and-contacts.md) — ephemeral-key invite and redeem flow
+- [Messaging](./messaging.md) — send, receive, and contact-restore

package/mufl_code/core/docs/how-it-works/versioning.md

@@ -0,0 +1,116 @@
+# Versioning
+
+`version.mm` is the single source of truth for the shared core's version. Every
+library in the core loads it, so any packet that links the core carries exactly
+one version stamp.
+
+Source: [`version.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/version.mm).
+
+## The version type
+
+```mufl
+metadef version_t: (
+    $MAJ -> int,
+    $MIN -> int,
+    $PATCH -> int
+).
+```
+
+The current version is stored in the `hidden` `core_version` field and exposed
+via `get_core_version`. The source comment states:
+
+> This MUST be updated every time we update ANY code in the shared core.
+
+Because every library loads `version`, a single edit to any `.mm` file in the
+core requires a version bump before the change ships.
+
+## Runtime observability
+
+Each deployed packet exposes its compiled-in version through the read-only
+`get_version` transaction described in the README. An integrator can query any
+running node to confirm which core version it is running — no out-of-band
+coordination needed.
+
+## What changes mean for integrators
+
+| Change | What to do |
+|---|---|
+| `$PATCH` bump | Wire format is unchanged. Re-compile against the updated submodule; re-run integration tests to confirm nothing regressed. |
+| `$MIN` bump | New features added; no existing behaviour removed. Re-compile, re-run integration tests, and read the diff to find new transactions or capability verbs you may want to use. |
+| `$MAJ` bump | Breaking changes. Re-compile, re-run all integration tests, and read the diff carefully — wire shapes, transaction names, or type contracts may have changed. |
+
+The docs on this site track `main`; always check the current `core_version` in
+`version.mm` to confirm which version the docs describe.
+
+## The versioned type registry (core 0.5.0)
+
+Since 0.5.0, wire-level backward compatibility is an **explicit mechanism**, not a
+convention: for every wire input surface whose shape ever changed,
+[`a2a_versions.mm`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/a2a_versions.mm)
+declares one frozen metadef **per shipped wire version** of its payload, the accepted
+**union** (the handler's visible contract), the ordered version vector, a **discriminator**,
+and a dispatch function:
+
+```mufl
+metadef sir_payload_t: sir_payload_v5_t || sir_payload_v3_t || sir_payload_v2_t.
+
+fn try_narrow_sir (raw: any) -> sir_narrowed_t   // ($ok, $payload, $err)
+```
+
+`try_narrow_*` reads the discriminator off the RAW value and exact-casts to the matched
+version's type (**dispatch-then-narrow** — never cast-to-union as the selector, because
+disjunction casts pick alternatives in canonical order and rebuild/strip; those toolchain
+behaviors are pinned by `tests/mufl_semantics/`). Handlers then branch per version: the
+v2 branch handles the payload the 0.2.0 way, the v5 branch the new way — backward
+compatibility is visible in the types and the branches, not buried in NIL defaults.
+
+### `$pv` — the wire dialect id
+
+Every 0.5.0+ core-originated send stamps `$pv -> 5` (minor-version ints) on its `$targ`
+and inside the boxed identity-bundle payloads. Absence means a pre-0.5 peer; the registry
+infers the shape (e.g. leg-1 bundle: `$name` present ⇒ v3, else v2).
+
+| `$pv` | core | notes |
+|---|---|---|
+| *(absent)* | 0.2.0 / 0.3.0 / 0.4.x | shape-inferred per registry |
+| 2 | 0.2.0 dialect | synthetic (0.2.0 never stamps) |
+| 3–4 | 0.3.0 dialect | 0.4.x never shipped; wire-identical to 0.3 |
+| 5 | 0.5.0 | first stamped dialect |
+| > 5 | future | narrows as the newest registered version (class-A additions strip safely) |
+
+Peers' dialects are learned passively into `a2a_messaging::contact_pv` (and their
+advertised capability ids into `contact_caps`, from the `$caps` piggyback on the invite/
+restore bundles) — no handshake round-trip. Both gate feature selection and diagnostics
+only, **never authorization**.
+
+### Errors as data — old peers never crash
+
+A payload from below the version floor (or matching no registered shape) is converted into
+a first-class **error value** — `a2a_versions::version_error_t`
+`($code, $surface, $message, $peer_version, $min_supported, $max_supported)` — delivered to
+the local client as a `$protocol_error` notify event, while the transaction completes
+successfully with **zero state writes**. A version-incompatible invite redeem therefore
+does not consume the invite: the peer can update and redeem the very same invite.
+Crypto/tamper and identity-verification failures remain hard aborts.
+
+### The four-class change taxonomy
+
+| Class | Change | Cost |
+|---|---|---|
+| A | add an optional field | new registered version + one dispatch branch (MINOR) |
+| B | new transaction | new single-version registry (MINOR) |
+| C | change/remove a field or semantics | breaking — parallel transaction or dual-accept window (MAJOR) |
+| D | evolve a signed artifact | new versioned metadef, verifiers fail-closed on unknown versions |
+
+The binding rules (REG-1…6), the OSP declaration, the full registry index, and the wire-
+change PR checklist live in
+[`COMPATIBILITY.md`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/COMPATIBILITY.md).
+
+## Message receipts (core 0.7.0)
+
+Delivery + read confirmations, capability-gated and **fail-closed**: a recipient emits
+`receive_receipt` pings (`$kind "delivered"` on arrival, `"read"` on its get/mark-read path)
+only when it advertises `core.receipts.emit` AND the sender positively advertises
+`core.receipts.receive` — so old clients exchange no receipt traffic at all and the sender's
+per-peer state is simply *unknown*, never *failed*. Details in
+[`COMPATIBILITY.md`](https://github.com/adapt-toolkit/ours-mufl-core/blob/main/COMPATIBILITY.md).

package/mufl_code/core/docs/index.md

@@ -0,0 +1,27 @@
+# ours-mufl-core
+
+**[ours.network](https://ours.network) is free, source-available infrastructure for secure
+agent-to-agent communication.** `ours-mufl-core` is the protocol at its heart: the shared
+wire format and verification logic, written as MUFL (`.mm`) libraries and compiled into
+every client — so all of them speak identical bytes.
+
+> **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.
+
+## Three ways to consume this site
+
+1. **Agent, bulk** — fetch [`llms-full.txt`](https://adapt-toolkit.github.io/ours-mufl-core/llms-full.txt) (everything,
+   one file) or [`llms.txt`](https://adapt-toolkit.github.io/ours-mufl-core/llms.txt) (annotated index).
+2. **Agent, targeted** — every page is pure Markdown in
+   [`docs/` on GitHub](https://github.com/adapt-toolkit/ours-mufl-core/tree/main/docs);
+   fetch raw files directly.
+3. **Human** — browse: [How it works](/how-it-works/overview) ·
+   [Build your own app](/guide/) · [Reference](/reference/modules).
+
+These docs cover **using** the protocol — understanding it and building applications on
+it. Real apps built on the core: see
+[reference implementations](/reference/implementations).