Make the README a front door instead of a specification cover page

.github/CODEOWNERS

@@ -9,17 +9,24 @@
 # catch-all.
 
 #
-# WHY THESE PATHS NAME TWO OWNERS AND NOT ONE.
+# WHY THESE PATHS NAME TWO ACCOUNTS AND NOT ONE.
 #
 # They named only @0j0bit until 2026-09-12. That deadlocks: GitHub does not let
 # anyone approve their own pull request, and the branch ruleset grants no
 # bypass to administrators, so a pull request touching one of these paths and
 # authored by its sole code owner could never be merged by anyone.
 #
-# Both named accounts have write access, which a code owner must have to count.
-# These lines currently resolve to the same two people as the catch-all, so
-# their present effect is documentary: they record which paths are authorities.
-# If the catch-all ever widens, they narrow again on their own.
+# @0j0bit and @sed-boi are two GitHub accounts controlled by the SAME project
+# owner. Either account may satisfy the code-owner review requirement for a
+# change it did not author -- in practice, changes proposed by the
+# mcl-release-governor App and reviewed as @0j0bit. This is account redundancy,
+# NOT independent two-person review, and nothing here claims separation of
+# duties.
+#
+# Both accounts have write access, which a code owner must have to count. The
+# path lines below name the same accounts as the catch-all, so their present
+# effect is documentary: they record which paths are authorities. If the
+# catch-all ever widens, they narrow again on their own.
 
 * @0j0bit @sed-boi
 

README.md

@@ -1,11 +1,105 @@
-# MCL SDK
-
-Product-facing reference SDK for the **Machine Contact Layer**. The default
-integration is `mcl/machine.h`: the application supplies platform operations
-and receives contact events; MCL owns contact/session state, negotiation,
-validation, migration, retries, and cleanup. In MCL Base 1 the peers already
-share a bearer and discovery is not required. Optional Stranger-Contact adds
-zero-prior rendezvous when no bearer is shared.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/machine-contact-layer/.github/main/profile/banner.png" alt="OJOBIT" width="100%">
+</p>
+
+<h1 align="center">MCL SDK</h1>
+
+<p align="center"><strong>Build a machine that can meet another machine. Freestanding C99: no heap, no libc.</strong></p>
+
+<p align="center">
+  <a href="https://github.com/machine-contact-layer/mcl-sdk/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/machine-contact-layer/mcl-sdk/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/machine-contact-layer/mcl-sdk/blob/main/LICENSE"><img alt="License Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
+  <img alt="C99 freestanding" src="https://img.shields.io/badge/C99-freestanding-informational">
+  <img alt="status" src="https://img.shields.io/badge/status-Public%20Candidate-orange">
+</p>
+
+<p align="center">
+  <a href="https://github.com/machine-contact-layer/mcl-sdk/blob/main/QUICKSTART.md"><b>Quickstart</b></a> ·
+  <a href="https://github.com/machine-contact-layer/mcl-sdk/tree/main/examples"><b>Examples</b></a> ·
+  <a href="https://github.com/machine-contact-layer/mcl-core"><b>Specifications</b></a> ·
+  <a href="https://github.com/machine-contact-layer/mcl-core/blob/main/REPORTING.md"><b>Report a defect</b></a>
+</p>
+
+---
+
+> **This is the repository to start from.** Everything else in the
+> organization is the specification MCL is defined by; this is the code you
+> link against.
+
+## Run it
+
+**From the release's developer SDK** — one CMake project, no sibling checkout:
+
+```sh
+curl -LO https://github.com/machine-contact-layer/mcl-core/raw/main/releases/v1.0.0/mcl-developer-sdk.tar.gz
+tar -xzf mcl-developer-sdk.tar.gz
+cmake -S mcl-developer-sdk -B build
+cmake --build build
+./build/mcl_base_arranged_bearer
+```
+
+**From the repositories** — `mcl-sdk` builds against its sibling
+specifications, so clone them side by side:
+
+```sh
+for r in mcl-core mcl-wire mcl-link mcl-sdk mcl-ap mcl-ip mcl-ble mcl-uwb; do
+  git clone https://github.com/machine-contact-layer/$r
+done
+cmake -S mcl-sdk -B build
+cmake --build build
+./build/mcl_sdk_base_arranged_bearer
+```
+
+Either way, two machines meet over a bearer they already share, exchange
+presence, admit each other by local policy, and refuse an object they are not
+willing to carry — `MCL Base 1`, end to end, with no network, no microphone and
+no pairing step.
+
+## What using it looks like
+
+```c
+#include "mcl/machine.h"
+
+mcl_machine_t        machine;
+mcl_machine_config_t cfg;
+mcl_platform_t       platform = {0};
+
+/* The porting interface: a clock, and a way to put bytes on your bearer. */
+platform.clock_ms       = my_clock_ms;
+platform.transport_send = my_send;
+platform.user           = &my_bearer;
+
+/* Base 1: a bearer you already have. No discovery, no rendezvous. */
+mcl_machine_config_deployment(&cfg, MCL_DEPLOYMENT_BASE_ARRANGED_1,
+                              0xA1A1A1A1u, MCL_CONTACT_ROLE_INITIATOR);
+mcl_machine_init(&machine, &cfg, &platform);
+mcl_machine_start(&machine);
+
+/* Bytes that arrive on your bearer go in... */
+mcl_machine_receive(&machine, transport_id, data, size);
+
+/* ...and a regular poll reports what happened. */
+mcl_machine_event_t ev;
+if (mcl_machine_poll(&machine, &ev) == MCL_MACHINE_OK &&
+    ev.kind == MCL_MACHINE_EVENT_POLICY_REQUIRED) {
+    mcl_machine_admit(&machine);   /* your policy decides, never MCL */
+}
+```
+
+For Base 1 you supply a monotonic clock and a send function, and hand
+received bytes to `mcl_machine_receive()` — over whatever bearer you already
+have: a socket, a UART, a BLE characteristic, a test harness. MCL never
+allocates; every buffer is yours.
+
+## Where to go next
+
+| You want to | Go to |
+| --- | --- |
+| A guided walkthrough | [`QUICKSTART.md`](QUICKSTART.md) |
+| More examples | [`examples/`](examples/) |
+| Port it to your platform | `QUICKSTART.md` section 07 |
+| Know what a byte means | [mcl-wire](https://github.com/machine-contact-layer/mcl-wire) |
+| Know what is claimed | [conformance/ICS.md](https://github.com/machine-contact-layer/mcl-core/blob/main/conformance/ICS.md) |
 
 The primary reference SDK is a portable C99 implementation designed to run from resource-constrained microcontrollers through embedded systems and hosted applications without changing the protocol contract.