@joe-broadhead/opencode-messaging 0.0.0-stage → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,129 @@
+# Changelog
+
+All notable changes to `@joe-broadhead/opencode-messaging`. Versions follow
+[Semantic Versioning](https://semver.org). The plugin requires the `messagingd` of its own release
+(the IPC hello); each release names the `@joe-broadhead/messaging` it was built against.
+
+## [Unreleased]
+
+## [0.4.0] - 2026-11-07
+
+Published on npm (public). Built against `@joe-broadhead/messaging` **0.4.0** (vendored, release commit `da50b5d`:
+the release `172a6ba` plus a docs commit), and ships with the 0.4.0 daemon: the five platform packages
+`@joe-broadhead/messaging-bin-{darwin-arm64,darwin-x64,linux-arm64-gnu,linux-x64-gnu,win32-x64}` are pinned at exactly
+0.4.0, each by the registry's integrity in the lockfile and by its executable's sha256 in the launcher, both equal to the
+release's `SHA256SUMS` and provenance. A 0.3.x daemon is refused at the IPC hello (`daemon_mismatch`).
+
+- **Sign in with Jelly** in `/messaging`. In a hosted realm, a device that is no one's yet (the managed
+  realm right after "Use Messaging by Jelly" too) is offered **Sign in with Jelly** first and **Link this
+  device** second. Sign-in shows Jelly ID's link (with a QR code), the user code and this key's
+  fingerprint, with the instruction to approve only if the page shows the same; it opens the browser on
+  request (never over SSH), waits with `device.login.status`, can be cancelled (closing the waiting screen
+  cancels too), and shows the outcome in fixed text. `login_unsupported` (Jelly ID without contract v1.2,
+  production today) is one plain sentence pointing to Link this device, never retried. New console text
+  for `login_unsupported` and `login_denied`.
+- **Devices** shows how a Jelly-vouched device signed in (`via`: through the browser, or on a Jelly host).
+  A device that signed in through the browser removes another device with a fresh sign-in (`device.login`
+  with `remove`); one approved by QR says to do it from Jelly.
+- **`/messaging-status`** shows the binding with `via`, and a sign-in still waiting in the browser.
+- **Tasks name their authors** (core): each text of a task in `tasks` and `read` has `author`
+  (`titleAuthor`, `statusAuthor`): `ours`, unfenced and cleaned, or `peer`, fenced. The plugin's
+  provenance stopgap of 0.3.0 is gone; its test stays as the guard of core's contract. The skill
+  explains the field. Goldens follow.
+- Agent tools never sign in.
+
+## [0.3.0] - 2026-11-06
+
+The first published release (npm, public). It ships with messaging 0.3.0 and pins the five
+`@joe-broadhead/messaging-bin-*@0.3.0` platform binaries.
+
+- **Messaging by Jelly:** the managed deployment's realm is built into the release (relay URL, Jelly ID
+  issuer, resource and the directory's epoch key; realm id `I2dIKOtS…`), never fetched. On a fresh home,
+  `/messaging` asks first: "Use Messaging by Jelly", then "Create or join a team (self-host)". Using it checks
+  `msg.toqanjelly.ai/.well-known/messaging.json` when reachable (a different key, issuer, resource, relay URL
+  or realm id is refused and nothing is written), writes the pinned `realm` into `config.json`, starts the
+  daemon, and opens Devices to link this computer from a device that has Jelly. Never offered to a home with
+  an identity, a realm, a team or a pending join; never writes over a realm. `/messaging-status` names it.
+  The hand-written `config.json` block for CLI users is in docs/configuration.md.
+- **Fixes from the 0.3.0 live run:** the `/messaging` TUI takes its home and daemon options from the
+  plugin's server part (`config` over the plugin's RPC) and never falls back to `$MESSAGING_HOME` or
+  `~/.messaging`; an open room updates delivery states live; "Finish join" on a joined machine says so;
+  each wake prompt says which rules hold for that turn; and a task request this side sent is labelled as
+  ours, not the peer's (corrected in the plugin until messaging's core is fixed).
+
+Built against `@joe-broadhead/messaging` **0.3.0** (vendored, release commit `408e816`), and ships with the 0.3.0
+daemon: the platform packages are pinned at exactly 0.3.0 (each executable's sha256 pinned in the launcher, equal
+to the release's `SHA256SUMS`). A 0.2.x daemon is refused at the IPC hello (`daemon_mismatch`). Messaging 0.3.0's
+new request class is a wire change: a 0.2.x peer refuses message requests and cards.
+
+- **Tools:** a person's `can` in `contacts` is what their contact card says (`source: "card"`, `card`: when it
+  was signed) or the default; `ask` is `request` in one org by default. `send {to: "me", request: {contact}}`
+  suggests a contact to the person (only to `me`; the email is shown in the approval). An agent never sends or
+  answers a message request. `request_required`'s next step says so. Goldens follow.
+- **`/messaging` Requests:** message requests (the sender's verified name, email and org, then their text as
+  their words; Accept, Decline, Block, with a confirm for Accept and Block; Accept opens the DM) and an agent's
+  suggestions (Send request, which composes with the email and passes `suggestion`, or Dismiss), beside the asks.
+- **`/messaging` People:** each person's card (`reach`) in fixed words, with Refresh (`card.get`, once a day);
+  in a hosted realm, "Write to someone outside your org": a message request to an exact email after
+  `contact.request.preview` finds them, at most 500 characters, behind a confirm, with fixed texts for its
+  refusals. A team realm hides it. Your waiting request reads "waiting for them to accept" in the DM.
+
+## [0.2.0] - 2026-11-06 (not published)
+
+The people-and-consent release, built against `@joe-broadhead/messaging` **0.2.0** (vendored, release
+commit `344e8fb`; `vendor/messaging.json` names it). It ships with the 0.2.0 daemon: the platform packages
+`@joe-broadhead/messaging-bin-*` are pinned at exactly 0.2.0 (each executable's sha256 pinned in the
+launcher, equal to the release's `SHA256SUMS`), and `dist/messagingd.js` is the 0.2.0 daemon. A 0.1.x daemon
+is refused at the IPC hello (`daemon_mismatch`): stop it with `messaging daemon stop`; the 0.2.0 daemon opens a 0.1 home
+(its store only grows).
+
+- **Breaking: the 0.2 IPC, no aliases.** `conv.*`, `person.send`, `search`, `contacts.list`,
+  `msg.send`, `item.read`; `agent` and `device` for `session` and `machine`; group addresses are
+  `invalid_request` everywhere; `me` is your person's own conversation (`dm:<you>`).
+- **Breaking: trust is a grant.** The `inbound.trusted` option is removed (a configuration that sets
+  it is refused). A wake whose every item the daemon marks `consent: "trusted"` (the person's trust
+  grant) runs unguarded in its peer session; any other wake guards it again. Tools report the
+  daemon's `consent`; a send held for consent says `held` with `expect: "on_consent"`.
+- **Errors in house style:** a tool error's `message` starts with its code and its `remedy` is one
+  next step (`Next: …`); the console shows `<code>: <what happened>. Next: <step>.`
+- **Permissions:** a line to `me` does not ask (`messaging.send me allow`, after the send ask).
+- **Peer sessions** of a hosted person (`p_…`) keep their marker, and so their guard.
+- **`/messaging`:** People (search, a person's page, switches and trust through `grant.set` after
+  `grant.set.preview`, block, mute, the review list), Requests (allow once, always, decline,
+  block), Chats (DMs, Me, channels, search), Devices (link this device by QR and code, approve a
+  new device by typing the code it shows, remove this device), Notices; toasts from
+  `notice.subscribe` in fixed text; and **`/messaging-status`**.
+
+## [0.1.0] - Unreleased
+
+The first release: the OpenCode plugin for Messaging. Built against `@joe-broadhead/messaging`
+0.1.1 (vendored, from the 0.1 line at `fe1cec8`; `vendor/messaging.json` names the commit).
+
+- **Split out of the messaging repository** with its history (`git subtree split` of
+  `packages/opencode`). The repository root is the plugin package. It builds against
+  `@joe-broadhead/messaging` from a vendored, checksum-pinned tarball, bumped with
+  `npm run messaging:bump`; `npm run check:vendor` proves the pin, since npm does not check a
+  `file:` tarball's integrity.
+- **Tools**: the eight agent tools of spec §11 in the `messaging` namespace, the same as
+  `messaging-mcp`'s, with permissions on every send and every read of a person's conversation.
+- **Inbound**: framed transcript notes, mid-turn notes, wake prompts for idle sessions within a
+  per-teammate budget, task notes; peer turns in per-peer sessions under a guard.
+- **Daemon**: connects on first use; starts the `messagingd` it ships when none runs and the machine
+  has joined a team; refuses another release's daemon.
+- **`/messaging` TUI**: DMs, channels, people and team admin.
+- **Distribution**: plugin files only (no dependencies but the platform packages, no install
+  scripts, no `node_modules`): three bundles, and the daemon and CLI copied byte for byte from
+  `@joe-broadhead/messaging`. `npm run smoke:pack` installs it as OpenCode does and unpacks it as Jelly
+  does, and runs it end to end. Nothing is published to a registry.
+- **The platform daemon**: the self-contained `messagingd` executables
+  `@joe-broadhead/messaging-bin-{darwin-arm64,darwin-x64,linux-arm64-gnu,linux-x64-gnu,win32-x64}@0.1.1` are
+  exact optional dependencies (integrity in the lockfile). Autostart runs this platform's executable,
+  admitted by version, file type, mode and pinned sha256, with no `BUN_*` variable in its environment;
+  else `dist/messagingd.js` on Node 22.15 or later; else a `daemon_unavailable` that names the platform
+  and the remedy. `daemon.bin` may now name an executable. Smoke proves the installed and the unpacked
+  plugin start the executable, offline; the real-host suite autostarts it for a tool call.
+- **Windows**: the client libraries speak the Windows daemon's named-pipe endpoints (and, from
+  messaging 0.1.1, report `daemon_unavailable` rather than `forbidden` while a daemon stops or
+  restarts); the plugin skips the POSIX uid and mode checks there, registers `C:\…` directories as
+  wake locations, runs `messagingd.exe` from the `win32-x64` package (not code-signed), and the shell
+  asks before `messaging.exe` and `messagingd.exe`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Broadhead
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,12 @@
+Messaging: the OpenCode plugin (@joe-broadhead/opencode-messaging)
+Copyright (c) 2026 Joe Broadhead. Licensed under the MIT License (see LICENSE).
+
+The design was informed by concepts in reason-machines/reason-network (MIT OR Apache-2.0):
+a team session directory, delivery tiers, idempotent sends, staged receipts and framed peer input.
+No code, wire format or names were copied from it.
+
+The data model follows the A2A protocol v1 specification (Apache-2.0, Agentic AI Foundation).
+
+The LOOKALIKES and WIDE tables in @joe-broadhead/messaging (core, peer-text), bundled into dist/, are derived from Unicode 17.0.0 data
+files (confusables.txt from UTS #39 and EastAsianWidth.txt from the Unicode Character Database),
+Copyright Unicode, Inc., used under the Unicode License v3 (https://www.unicode.org/license.txt).

package/README.md

@@ -1,3 +1,282 @@
-# Temporary Holding Version
+# @joe-broadhead/opencode-messaging
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The OpenCode plugin for [Messaging](https://github.com/joe-broadhead/messaging) (spec:
+`docs/spec/messaging-v1.md` there, and shipped in `@joe-broadhead/messaging` as `./spec/messaging-v1.md`). With it, an OpenCode session can
+reach teammates and their coding-agent sessions, and delegate A2A tasks to them, through the local
+`messagingd` daemon. It also receives their messages as framed notes, or as a wake prompt when the session is
+idle. Its `/messaging` console is the person's own: people and what they and their agents may do,
+requests waiting for an answer, DMs and channels, devices, and notices.
+
+- **Tools** in the `messaging` namespace (Code Mode), the eight agent tools of spec §11, the same
+  as `messaging-mcp`'s: `contacts`, `send` (a line to a person, mail or a task to an agent, a post
+  to a channel), `inbox`, `read` (an item, or a page of a conversation), `search`, `tasks`,
+  `task_update` and `task_cancel`.
+- **Permissions:** the first send to each address (`person/agent`, `person` or `#channel`) asks
+  you (a line to `me`, your own conversation, does not), and so does the first read of each
+  conversation with a person. "Always" remembers that one
+  address or conversation. Configured `allow` and `deny` rules apply; a deny on `bob/*` also blocks
+  a line to bob. The agent's
+  shell also asks before any `messaging` or `messagingd` command (`.exe` on Windows too) and any command that names the Messaging
+  home, and the file tools are denied there. See [docs/security.md](docs/security.md).
+- **Untrusted content:** everything a peer wrote reaches the model inside a
+  `<messaging-peer-data-…>` fence, as data, never as instructions.
+- **Inbound:** a framed transcript note for new mail, the same note after the next tool output
+  while the session is working, a wake prompt for idle sessions when the sender asks for it (at most 6 per teammate per hour by default), and notes when delegated tasks
+  finish or need input.
+- **Daemon:** connects on first use, starts `messagingd` when it is not running and this machine has
+  joined a team (optional), and reconnects.
+- **Skill** `opencode-messaging`: tools, safety rules, the task lifecycle, Code Mode recipes and errors.
+- **RPC** `messaging.opencode` (`./rpc`): `wake`, which the daemon calls to load this plugin again
+  for wake mail, and `config`, which the plugin's own `/messaging` TUI calls for the home and daemon
+  options set in `opencode.json(c)` (OpenCode 2.2 gives the TUI part none).
+
+## Requirements
+
+- **OpenCode 2.2.5 or a later 2.2 release.** The package's peer range is `@opencode/plugin
+  >=2.2.5 <2.3` (and `@opentui/solid >=0.8.0 <0.9` for the TUI); in any other OpenCode the plugin
+  refuses to load with one line naming both versions, and adds nothing.
+- **The daemon, by platform.** npm installs the plugin with its platform package, the
+  self-contained `messagingd` executable (no Node, no install script), as an optional dependency:
+
+  | Platform | Daemon |
+  |---|---|
+  | macOS arm64, macOS x64 | `@joe-broadhead/messaging-bin-darwin-arm64`, `-darwin-x64` |
+  | Linux arm64, Linux x64 (glibc) | `@joe-broadhead/messaging-bin-linux-arm64-gnu`, `-linux-x64-gnu` |
+  | Windows x64 | `@joe-broadhead/messaging-bin-win32-x64` (`messagingd.exe`, not code-signed: see [Windows](docs/configuration.md#windows)) |
+  | anything else (musl, …) | `dist/messagingd.js` under Node 22.15 or later |
+
+  The **Node fallback**: without its platform package (another platform, `--omit=optional`, or a
+  tarball unpacked alone), the plugin runs the bundled `dist/messagingd.js` on Node 22.15 or later (it
+  stores its state with `node:sqlite`). OpenCode itself runs on Bun, so that needs a separate Node on
+  `PATH`, or `daemon.node`. See [which daemon runs](docs/configuration.md#which-daemon-runs).
+- **One Messaging daemon per home.** The plugin brings its own (the platform executable, or
+  `dist/messagingd.js`, with the `messaging` CLI as `dist/messaging.js`) and starts it only when none
+  answers. A daemon of another Messaging version is reported (`daemon_mismatch`), never replaced: stop
+  it with `messaging daemon stop`.
+
+The package is plugin files only: no dependencies but the platform packages (optional, each at
+exactly the messaging release, one installed per machine), no install scripts, no `node_modules`.
+
+Requires a Messaging daemon on the same machine. The machine must
+have created or joined a team (`messaging daemon start`, then `messaging team create` or
+`messaging team join`). Until it has, the plugin starts no daemon and adds nothing to your sessions.
+Messaging tools fail with `no_identity`, and the first one in a session leaves one note with the
+setup commands. A team you join later is picked up by the next tool call, without a reload. See
+[before a team](docs/configuration.md#before-the-machine-has-joined-a-team).
+
+## Install from a tarball
+
+`npm run pack:tarball` (or `npm run smoke:pack -- --artifacts <dir>`) builds
+`joe-broadhead-opencode-messaging-<version>.tgz`. Unpack it and point `plugins` at the folder; nothing
+needs to run. Unpack this machine's platform package under its `node_modules` too, so the plugin finds
+the executable (without it, the plugin uses the Node fallback):
+
+```bash
+mkdir -p ~/.local/share/opencode-messaging
+tar -xzf joe-broadhead-opencode-messaging-0.4.0.tgz -C ~/.local/share/opencode-messaging --strip-components=1
+npm pack @joe-broadhead/messaging-bin-darwin-arm64@0.4.0           # your platform's package
+mkdir -p ~/.local/share/opencode-messaging/node_modules/@joe-broadhead/messaging-bin-darwin-arm64
+tar -xzf joe-broadhead-messaging-bin-darwin-arm64-0.4.0.tgz \
+  -C ~/.local/share/opencode-messaging/node_modules/@joe-broadhead/messaging-bin-darwin-arm64 --strip-components=1
+node ~/.local/share/opencode-messaging/dist/messaging.js --help    # the messaging CLI of this version
+```
+
+```jsonc
+{ "plugins": [{ "package": "/Users/you/.local/share/opencode-messaging" }] }
+```
+
+`npm install ./joe-broadhead-opencode-messaging-0.4.0.tgz` into a folder OpenCode loads works too: it
+adds the package and this machine's platform package, nothing else.
+
+## Install from a local path
+
+Compile this repository, then add its directory to `plugins` in `opencode.json(c)`. Use your
+global `~/.config/opencode/opencode.json` to enable it everywhere, or a project config for one
+repository.
+
+```bash
+cd ~/opencode-messaging && npm ci && npm run compile
+```
+
+The `messaging` command is `dist/messaging.js` (the CLI of the vendored `@joe-broadhead/messaging`,
+copied as is); `node dist/messaging.js --help`, or install `@joe-broadhead/messaging`'s tarball (see
+the messaging repository) to put `messaging` on your `PATH`.
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "/Users/you/opencode-messaging",
+      "options": {
+        // all optional; see docs/configuration.md
+        "daemon": { "autostart": true },
+        "inbound": { "wake": true, "notify": true, "wakeBudget": { "perPeer": 6, "windowMs": 3600000 } },
+      },
+    },
+  ],
+}
+```
+
+OpenCode reloads plugins when the config is saved. The same package's TUI part (`./tui`) loads
+with it. In the terminal, `/messaging` is the human console. On a home with nothing in it yet, it
+first asks how to set up: **Use Messaging by Jelly** (see [below](#messaging-by-jelly)) or **Create
+or join a team (self-host)**; nothing is written until you pick. Then:
+
+- **People:** find someone (name or handle), see their org, vouch and devices, and set what they
+  and their agents may do: chat (open, muted, blocked), "agents may message me", "may ask my agents"
+  (open, ask first, no), trust for 30 days, block and mute. Each switch shows its value, or the
+  default. A change shows the daemon's own sentence for it and asks first. Permissions that lapsed
+  with a removed device are offered again. Each person's contact card (what they accept) shows with
+  Refresh. In a hosted realm, "Write to someone outside your org" sends a message request to an exact
+  email (at most 500 characters); it waits until they accept.
+- **Requests:** an agent asking one of yours, waiting for you: Allow once, Always (opens their
+  asks), Decline, or Block, for one request or all from that person. A message request from someone
+  outside your org (their verified name, email and org, then their text): Accept, Decline or Block.
+  A suggestion from one of your agents to contact someone: Send request (you write it) or Dismiss.
+- **Chats:** your DMs with unread counts, **Me** (what your agents tell you), channels and search.
+  Open a DM to read it (which marks it read on this device), page back, write a line, or reply in a
+  thread. A line of yours that was not delivered can be sent again; a failed send offers Try again
+  and is filed once. Channels: create, open, invite or remove people, leave; a channel held under a
+  local name shows both, for example `#eng-2 (eng)`. Search: every word must match.
+- **Devices:** your devices with their vouch, and for a Jelly-vouched one how it signed in (through
+  the browser, or on a Jelly host). In a hosted realm, a device that is no one's yet is offered
+  **Sign in with Jelly** first ([below](#sign-in-with-jelly)) and **Link this device** second (a QR
+  code and a six-digit code, approved from a device that already has Jelly). A bound device offers
+  **Approve a new device** (paste its link, then type the code the new device shows; the approving
+  device never shows it) and Remove this device. A device that signed in through the browser removes
+  another of yours with a fresh sign-in.
+- **Notices:** new lines, requests and this device's alarms, with the counts; mark them seen.
+- **Team** (a team realm): prepare to create (shows this machine's id for a relay that lets only
+  known machines create teams), create, join, ask to join and finish joining, discard pending keys,
+  invite, admit, list and remove members. Pending keys serve one purpose at a time.
+- **This device**, and the command **`/messaging-status`**: who you are, the realm and binding (the
+  managed realm by name, "Messaging by Jelly"; how this device signed in; a sign-in still waiting in
+  the browser), the relay, the directory, and any alarm with its
+  next step.
+
+Every error the console shows reads `<code>: <what happened>. Next: <step>.`
+
+A chat line never wakes anyone's coding agent. Your own lines show whether they arrived (`sent`,
+`delivered`, or not delivered to whom), updated while the room is open, and the daemon's notices about channel changes show as
+system lines. Once this device has an identity, the TUI keeps one connection to the daemon and
+follows its notices: a new line from someone else or from your own agents, a request waiting for
+you, or an alarm shows as a toast and, when the terminal is in the background, a notification.
+Toasts carry fixed text and a cleaned name, never a line. There is no footer badge. The connection never starts the daemon
+and reconnects by itself when the daemon restarts. The console registers no session. It starts the
+daemon only to create, join or ask to join a team once you have typed everything it needs, to use
+Messaging by Jelly once you have confirmed it, and for
+other actions only on a machine that has joined a team; with `daemon.autostart: false` it never
+starts it. Invite tickets stay in their own dialog. They are copied to the clipboard only when you
+choose that, and they are never written into a session. A device link and its code show only in
+their own dialog on the new device.
+
+To check that the plugin is loaded, ask the agent to run `tools.messaging.contacts({})`. Its `me`
+holds this session's address, for example `joe/messaging@laptop`; before the machine has joined a
+team, the call fails with a `no_identity` error.
+
+Optional permission rules (see [docs/security.md](docs/security.md)):
+
+```jsonc
+{
+  "permissions": [
+    { "action": "messaging.send", "resource": "alice/*", "effect": "allow" },
+    { "action": "messaging.send", "resource": "mallory/*", "effect": "deny" },
+  ],
+}
+```
+
+## Messaging by Jelly
+
+Messaging by Jelly is the managed Messaging deployment (`msg.toqanjelly.ai`), where people sign in
+with Jelly. Its realm is built into this release: the relay URL, the Jelly ID issuer, the resource
+and the directory's epoch key are pinned in the plugin (`src/domain/managed.ts`), never fetched and
+trusted on first use. In `/messaging`, on a fresh home:
+
+1. **Use Messaging by Jelly**, and confirm. The console reads
+   `https://msg.toqanjelly.ai/.well-known/messaging.json` when it can; if it describes a different key,
+   issuer, resource, relay URL or realm id, it refuses, says so, and writes nothing. If it cannot be
+   reached, the pinned values stand on their own.
+2. It writes the pinned realm into the home's `config.json` and starts the daemon, which makes this
+   computer's keys.
+3. **Devices** opens next: **Sign in with Jelly** approves this computer in your browser; **Link this
+   device** shows a QR code and a six-digit code to approve from a device that already has Jelly.
+   Once it is approved, this computer is one of your devices. A hosted person's first device is
+   always Jelly-rooted: signed in through Jelly ID, or enrolled by Jelly.
+
+It is offered only to a home with no identity, no realm, no team and no pending join, and it never
+writes over a realm a `config.json` already has. A home in Messaging by Jelly has no `team.*`: it
+cannot create or join a self-hosted team later. Agent tools never join a realm. Without the TUI, write
+the block by hand; [configuration.md](docs/configuration.md#messaging-by-jelly) has it, and
+[security.md](docs/security.md#messaging-by-jelly-the-pinned-realm) says how to check the key.
+
+## Sign in with Jelly
+
+In a hosted realm, a device signs in through the browser at Jelly ID, without another device
+(messaging 0.4.0's `device.login`). In `/messaging`, Devices, **Sign in with Jelly**:
+
+1. Choose to open Jelly ID in your browser, or to show the link (with a QR code, for another device),
+   copied if you ask. Over SSH the console opens nothing and says to open the link elsewhere.
+2. The console shows Jelly ID's link, a user code such as `WDJBM-XQ7KP`, and this device's key
+   fingerprint such as `3fa9-1c07-e2b4`. Sign in at Jelly ID; approve only if the page shows the same
+   code and the same key, else deny it.
+3. The console waits for the outcome and closes by itself: signed in, denied, expired or cancelled.
+   From the waiting screen you can show the link again or cancel; closing it cancels too.
+
+A device that signed in this way is Jelly-rooted (vouched by Jelly, `via: browser`). It can remove
+another of your devices with a fresh sign-in (Devices, pick the device). A device approved by QR
+cannot. **Until Jelly ID offers browser sign-in** (Jelly's contract v1.2), the daemon answers
+`login_unsupported`, and the console says so in one sentence and points to Link this device; it never
+retries. Agent tools never sign in: `device.login` is on the daemon's admin socket only.
+
+## Docs
+
+- [Configuration](docs/configuration.md): every option and its default.
+- [Security](docs/security.md): permission actions and resources, framing, and what is never logged.
+- [Architecture](docs/architecture.md): layers, the daemon link, registration and inbound flows.
+
+## Development
+
+This repository is the plugin package itself (its root is the package). It builds against
+`@joe-broadhead/messaging` (the client libraries, the daemon, the CLI and the spec), which comes from a
+vendored tarball, `vendor/messaging-<version>.tgz`, pinned in `package-lock.json` until that package is
+published. See [AGENTS.md](AGENTS.md) for the rules.
+
+```bash
+npm ci
+npm run gates                          # every gate, in order: the merge gate
+npm run compile                        # tsc -b into build/, src/tui.tsx with Babel, then scripts/bundle.mjs into dist/
+npm test                               # unit, fake-host and fake-daemon suites
+
+# Real-host suite (embedded OpenCode 2.2.5, Node >= 24, separate install)
+npm ci --prefix test/host
+PATH=/path/to/node24/bin:$PATH npm run test:host
+
+# A new messaging build: pack a messaging checkout, replace the vendored tarball, update the lockfile
+npm run messaging:bump -- ~/messaging
+```
+
+The real-host suite has its own `package.json` and lockfile under `test/host/`. `npm test`
+excludes it.
+
+The package is plugin files only: no dependencies but the platform packages, no install scripts, no
+`node_modules`. `npm ci` installs this machine's platform package, which the unit and real-host suites
+run (`test/daemon-resolve.test.ts`, `test/host/binary.test.ts`). `npm run
+compile` runs `tsc -b` into `build/`, compiles `src/tui.tsx` with Babel (`babel-preset-solid` for
+`@opentui/solid`, because OpenCode compiles TSX only outside `node_modules`) to `build/tui.js`, and
+then `scripts/bundle.mjs` bundles `index.js`, `rpc.js` and `tui.js`, with what they use of
+`@joe-broadhead/messaging` and `uqr`, into one file each in `dist/`, and copies the daemon and CLI
+from `@joe-broadhead/messaging` byte for byte as `messagingd.js` and `messaging.js`. The host
+supplies `@opencode/plugin`, `@opentui/solid` and `solid-js` (optional peers). `npm run
+check:package` checks what `npm pack` would ship; `npm run check:vendor` that the vendored messaging
+package is the pinned one. `npm run smoke:pack` imports the installed `./tui` entry under Bun, the
+TUI's runtime, so it needs Bun 1.3 or later; it installs the platform package offline from the
+npm cache (`MESSAGING_BIN_TARBALLS=<dir>` adds the release's platform tarballs to the cache first)
+and checks that the installed and the unpacked plugin both start its executable. (There is no `build` script on purpose: a plugin
+installed from git must not have one.)
+
+After `npm run compile`, or after installing a new tarball, restart OpenCode, both the server and the
+TUI. A reload also starts the wake budget again.
+
+`MESSAGING_PLUGIN_DEBUG=1` writes to stderr. When the server runs inside the TUI process, that paints
+over the terminal UI, so set it only for `opencode serve` or the host suite.