@hraness/message-like-me 0.8.11 → 0.8.12

package/docs/textbutler/getting-started.md

@@ -0,0 +1,277 @@
+# Start using Textbutler
+
+Textbutler is a local Mac assistant for selected conversations. Start with its
+inbox and replies you write yourself. Automatic replies stay paused until you
+choose a ready agent and explicitly enable a contact.
+
+AI replies require a verified Textbutler bundle with reviewed composition
+admission and use a separately installed [xcb](https://github.com/hraness/xcb)
+native runtime and an explicitly connected subscription account. This local
+pilot requires current xcb admission and a successful account check. Installation
+does not enable replies, and live messaging still needs verification with your
+chosen recipient. Claude API retains a separate trusted runtime admission gate.
+
+## Open the guided terminal
+
+From your Textbutler checkout, with Bun 1.3.14:
+
+```sh
+bun install --frozen-lockfile --ignore-scripts
+bun run textbutler tui
+```
+
+For daily use, you can install a local command that works outside the checkout:
+
+```sh
+bun run textbutler:install
+~/.local/bin/textbutler
+```
+
+The installer builds a self-contained local pilot, checks the reviewed
+composition receipt against current source and contact profiles, and verifies
+its contents and exact Bun runtime before use. Missing or stale composition
+evidence blocks the build. Source daemon startup carries no such admission and
+keeps subscription inference unavailable. It starts no services and connects no accounts.
+An existing, different `textbutler` command is preserved. This is a local build,
+not a signed public release. Connect xcb separately for AI replies. Keep the same
+Bun runtime installed. To upgrade a verified existing installation, stop its
+services and run `bun run textbutler:install --upgrade`. The installer checks
+the existing launcher and complete installed version, preserves them for
+rollback, and atomically switches the command. It never replaces an unrelated
+command or changes your settings. Restart the installed daemon afterward.
+
+The terminal has numbered actions for setup, app connections, conversations,
+replies, contacts, pause and the menu bar. Enter goes back from a selection;
+`q` or Ctrl-C closes the terminal. It does not stop an installed background
+service. Commands below use `bun run textbutler`; the help abbreviates that
+prefix to `textbutler`. You can use `~/.local/bin/textbutler` for these commands.
+Use the installed terminal when setting up daemon startup for AI replies.
+
+Choose **Setup & readiness** first. It creates private settings and points you
+to messaging setup. After saving your connections, return to **Setup & readiness**
+to start the service at login. Repeating setup preserves existing settings and
+contact activation. Use `doctor` at any time to see connection status, remaining
+setup steps and whether reply generation is actually available.
+
+## Connect your messaging apps
+
+Textbutler uses an existing Ghostget installation for account sign-in, permissions
+and messaging access. You need its physical executable path and the exact account
+ID; Textbutler does not guess an identity. Native iMessage can use the app setup
+flow below. Set up other messaging accounts in Ghostget first.
+
+Choose **Connect messaging apps** in the terminal:
+
+- **iMessage:** the native Mac Messages connection.
+- **WhatsApp:** a native linked device; connecting explicitly starts sync.
+- **Beeper:** linked apps such as Signal, Telegram, Instagram, WhatsApp and
+  iMessage. Keep Beeper Desktop open with its local API enabled. The current
+  Ghostget automation adapter supports direct conversations and text replies.
+
+Beeper automation requires Ghostget 0.18.14 or later with the
+`ghostget.messaging-automation/1` protocol. A connection being configured does
+not prove that it is connected. Check it before selecting conversations.
+
+Initial setup can also be scripted. Replace the paths and IDs with your own:
+
+```sh
+bun run textbutler setup \
+  --ghostget /absolute/path/to/ghostget \
+  --account imessage:messages \
+  --account beeper:beeper-main
+```
+
+If Ghostget's entrypoint is a TypeScript file, also pass
+`--runtime /absolute/path/to/bun`. An optional `--state-home` selects its existing
+state directory. Configuration is additive: this command preserves existing accounts and agent
+settings and refuses to replace an account identity. Stop the service before
+adding a connection, then run setup with the same connector paths and the new
+account ID. To change existing bindings, stop the
+foreground service or uninstall its login entry, review private
+`state/host.json`, then restart or reinstall the service. Uninstall retains your
+settings, contact memory and activity.
+
+For foreground use with AI, run `~/.local/bin/textbutler daemon run` in another
+terminal. For login startup, use `~/.local/bin/textbutler daemon install`. Use
+your chosen installation prefix if different. Source daemon commands remain
+available for the manual pilot; keep that checkout at its current path while a
+source service is installed.
+
+See [messaging app support](messaging-apps.md) for Beeper limitations and native
+alternatives, including requirements that affect Telegram AI processing.
+
+## Give TextButler access to iMessage
+
+Use the native app when you want macOS Full Disk Access to belong to TextButler.
+The app supervises its pinned runtime and background service. Build it from an
+already installed, verified payload on your Mac:
+
+```sh
+bun run textbutler:app build \
+  --from /absolute/installed/textbutler/version \
+  --output /absolute/new/app-build-directory
+bun run textbutler:app install --from /absolute/new/app-build-directory
+```
+
+The default destination is `~/Applications/TextButler.app`. Building and
+installing the app does not start replies or change macOS permissions. In
+**System Settings → Privacy & Security → Full Disk Access**, click **+**, press
+**Command-Shift-G**, enter `~/Applications/TextButler.app`, and choose **Open**.
+Enable its switch. macOS may require your password in its own dialog.
+
+Configure the exact Ghostget `src/cli.ts`, Bun runtime, private state directory
+and `imessage:ACCOUNT` binding using `setup` above. This development version pins
+Ghostget 0.18.21 and its reviewed `imsg` helper artifact. Native setup provisions
+that pinned helper into the connector state directory (`imessage transport install`)
+before linking; a missing or mismatched artifact stops setup instead of reaching
+messaging. Setup links only
+that account to this Mac's Messages store and
+enables Ghostget's account-specific automation read, text and attachment-send capabilities.
+Contact selection and automatic replies remain separate choices.
+
+With the background service stopped, run the setup role through its verified
+app launch:
+
+```sh
+bun run textbutler:app imessage-setup \
+  --data-dir "$HOME/Library/Application Support/Textbutler"
+```
+
+After app setup completes, use the installed `daemon install` command to
+register its background service. If an older service is installed, first use
+`daemon uninstall`; this preserves your settings and contacts. Startup verifies
+the native app receipt and all pinned artifacts. A changed app or runtime
+requires a verified rebuild and reinstall. Local apps use ad-hoc signatures,
+so macOS may require permission again after a rebuild. Check `doctor` and the
+messaging connection before enabling a contact.
+
+To upgrade an installed app, stop the service and finish or reconcile any
+pending setup attempt, then build from the new installed payload. Install it
+with the following command:
+
+```sh
+bun run textbutler:app install --from /absolute/new/app-build-directory --upgrade
+```
+
+The upgrade verifies both versions and retains the previous signed
+app and receipt. If it reports an uncertain transition, preserve its records
+and reconcile that transition before retrying. Recheck Full Disk Access and
+Messages Automation after the upgrade.
+
+See [local data](local-data.md) for retained setup records and installation data
+removal. Repeating setup preserves an already linked account and its identity.
+
+For JSON commands to read, summarize, compose and send messages from another
+agent, see the [agent CLI guide](agent-cli.md).
+
+## Connect your AI subscription
+
+Install an xcb native build with `generate` support and follow its
+[account setup](https://github.com/hraness/xcb#native-xcb). Sign in through xcb,
+then use `xcb accounts` and `xcb models` to obtain the exact account ID and full
+model key. Credentials remain in xcb's private state.
+
+With the Textbutler daemon stopped, connect that installation:
+
+```sh
+bun run textbutler setup \
+  --xcb /absolute/path/to/xcb \
+  --xcb-state /absolute/path/to/xcb-state \
+  --xcb-account claude:ACCOUNT_ID \
+  --xcb-model FULL_MODEL_KEY
+```
+
+For Codex, use `--xcb-account codex:ACCOUNT_ID` and a matching observed model.
+Repeat setup to add a second account. The command pins the executable bytes and
+explicit routing; it does not activate a contact. Setup refuses changes to an
+existing binary or account/model binding. After an xcb upgrade, stop the daemon
+and review its private `state/host.json` binding before updating the executable
+digest. Retain account and custody state.
+
+Start or restart the installed daemon, then check the account:
+
+```sh
+bun run textbutler providers list
+bun run textbutler providers check TEXTBUTLER_ACCOUNT_ID
+bun run textbutler doctor
+```
+
+Use the account ID returned by `providers list`. This checks xcb's current
+capabilities and admission without making a model turn. Resolve any unavailable
+or recovery status before asking for an unsent suggestion. See the
+[subscription connection](native-subscription.md) for the execution and custody
+contract. Source and bundle integrity checks alone do not qualify an AI provider.
+
+## Add one conversation and try the inbox
+
+Choose **Add a conversation**, select the exact person and app, and choose
+whether to import recent text history. Importing history never sends anything.
+The new contact has automatic replies off.
+
+Choose **Inbox & replies**. Textbutler lists unanswered incoming messages in your
+selected conversations. Choose **Type a reply**, review the recipient and the
+complete disclosed text, then type `send` if you want to send it. This path does
+not require an AI account. Leaving the review sends nothing.
+
+After the connected agent passes its readiness check, choose it under **Manage a contact**.
+A suggestion is an unsent draft. Review every action before sending. The CLI
+supports the same review:
+
+```sh
+bun run textbutler inbox
+bun run textbutler replies suggest CONTACT
+bun run textbutler replies show DRAFT
+bun run textbutler replies send DRAFT DIGEST
+```
+
+Use the exact digest shown by `replies show`. Changes to a draft or its attachment
+bytes invalidate that review. A result of `submitted` means the transport
+accepted the action; it is not proof that the recipient received or read it.
+
+A pending command prints a job ID. Use `jobs show JOB_ID` with the same data
+directory. Do not repeat an uncertain send or grant operation. Recovery fences
+remain until the operation can be reconciled; restarting does not erase them.
+
+## Use the menu bar
+
+Choose **Menu bar companion** in the terminal, or run:
+
+```sh
+bun run textbutler menubar start
+bun run textbutler menubar install
+```
+
+`start` opens it now; `install` registers login startup. The first start retrieves
+and verifies the pinned shared native companion. No local Rust build is needed.
+
+The menu gives you pause, connection checks, conversation selection, per-contact
+activation, agent selection, the reply inbox and recent activity. Draft previews
+are intentionally labeled: use the terminal to review complete outgoing actions
+before sending. The menu cannot send hidden or truncated draft content.
+
+Menu startup and daemon startup are separate. Quitting the menu leaves the
+installed daemon running. `menubar stop` closes the menu; `daemon uninstall`
+unregisters the background service and retains your data.
+
+## Turn on automatic replies only when ready
+
+Once a qualified agent and messaging connection are ready, select the agent,
+choose the contact's response mode, enable that contact, then resume. These are
+separate choices. The readiness view must show actual engine and transport
+availability; successful setup alone is insufficient.
+
+```sh
+bun run textbutler contacts account CONTACT ACCOUNT
+bun run textbutler contacts mode CONTACT keyword --keyword butler
+bun run textbutler contacts enable CONTACT
+bun run textbutler resume
+```
+
+`pause` stops automatic replies globally. `contacts disable CONTACT` also revokes
+that contact's grant. Owner-confirmed replies remain a separate explicit action
+while automatic replies are paused.
+
+Your Mac must be awake and signed in. Begin with one conversation and confirm
+behavior on an agreed test recipient before relying on automation. See
+[agent setup](../../packages/textbutler/PROVIDERS.md) for the current engine
+qualification requirements.

package/docs/textbutler/ghostget-contract.md

@@ -6,10 +6,18 @@ actions. Textbutler communicates with its own Ghostget owner process through
 `ghostget messaging automation serve --stdio`; it does not share the Ghostget
 menu companion's private helper or open provider databases.
 
-[Ghostget 0.18.2](https://github.com/hraness/ghostget/releases/tag/v0.18.2) is the
-verified published dependency for this contract. Its package includes both
-private messaging runtimes; installation is explicit and starts no provider.
-Older generic CLI routes do not become automation grants.
+The automation contract was first admitted with
+[Ghostget 0.18.2](https://github.com/hraness/ghostget/releases/tag/v0.18.2).
+This development version of native TextButler iMessage setup pins Ghostget
+0.18.21. Its matching artifact and live conversation checks remain pending.
+The required contract preserves the native helper's resource bundle, avoids
+opening unrelated protected folders during state validation, and exposes bounded
+discovery diagnostics without message bodies. Valid native chat rows without
+usable participant metadata are omitted from partial discovery results; they
+cannot become sending targets. Follow the
+[current setup guide](getting-started.md#give-textbutler-access-to-imessage).
+Installation is explicit and starts no provider. Older generic CLI routes do
+not become automation grants.
 
 ## Owner process
 
@@ -66,8 +74,12 @@ account and managed permission admit them. Message targets must belong to the
 enrolled conversation. Attachment and sticker paths are resolved by Textbutler's
 contact file broker; Ghostget receives admitted bytes, not arbitrary paths.
 
-Every response starts with disclosed text. For a nontext response, Textbutler
-inserts a companion such as `🤖{ … }` before the rich actions. Execution stops
+Every response starts with disclosed text while disclosure markers remain
+configured. For a nontext response, Textbutler inserts a companion such as
+`🤖{ … }` before the rich actions; when the owner clears all three disclosure
+fields no companion is added and butler authorship is carried by the accepted
+message IDs the run receipt returns to Textbutler's journal instead of by
+visible text. Execution stops
 when a preceding action fails or the conversation changes. An accepted receipt
 does not claim delivery.
 

package/docs/textbutler/local-data.md

@@ -0,0 +1,50 @@
+# Local data
+
+Textbutler keeps settings, contact memory, reply journals and setup records in
+`~/Library/Application Support/Textbutler`, unless you select another data
+directory. These files are private to the Mac user. XCB and Ghostget keep their
+own accounts and credentials in their separately configured state directories.
+
+Explicit CLI media imports live in the selected contact's private `outbox`.
+Each file is limited to 16 MiB and shares the contact workspace's 500-file
+budget. Repeating an import of the same bytes and extension reuses its content
+identity. Imports remain after a draft expires so the owner can review or reuse
+them. A complete installation data erasure removes these copies without
+changing their original source files.
+
+iMessage setup retains one small account binding so a repeated setup cannot
+silently authorize a different account under the same name. Failed attempts do
+not replace that binding. Setup results contain bounded progress and digests;
+they contain no message bodies or credentials.
+
+An app upgrade retains the previous signed app and its receipt under
+`~/Applications/.textbutler-app-upgrades`. Up to 32 transitions are retained.
+A pending transition also keeps `state/macos-app-upgrade.json` in the data
+directory until completion or rollback is proven. Keep both locations intact
+while an upgrade is unresolved.
+
+The explicit legacy iMessage crash reconciliation script accepts a private
+witness for the Ghostget 0.18.16 startup failure. It checks the original crash,
+app, connector, account and process state, then archives a bounded settlement
+record before releasing that attempt's setup marker. It never retries setup or
+changes accounts, permissions or messages. It refuses other failure types.
+
+## Remove Textbutler data
+
+Use `textbutler daemon uninstall` and stop the menu companion before removing
+local data. Confirm that Textbutler and its connector operations have stopped.
+If an operation has an uncertain outcome, reconcile it and retain the evidence
+needed to settle that operation first.
+
+To erase an installation, the owner can then delete its complete Textbutler
+data directory. This removes settings, contact memory, journals, setup results
+and the iMessage account binding. It does not delete Messages history, Ghostget
+or XCB accounts, or macOS permission grants. Removing individual binding or
+custody records is not a supported way to replace an account or retry a failed
+operation. Reinstalling the command and uninstalling the background service
+both preserve data by default.
+
+After all app transitions are settled and the installation has stopped, the
+owner may also delete retained app upgrade directories when their rollback
+copies are no longer needed. These directories contain app artifacts and
+upgrade receipts; they do not contain message history or provider credentials.

package/docs/textbutler/messaging-apps.md

@@ -0,0 +1,121 @@
+# Messaging apps
+
+Textbutler can use native iMessage and WhatsApp connections through Ghostget,
+or a Beeper connection for several messaging apps at once. For a Mac with
+iMessage, WhatsApp, Signal, Telegram and Instagram, Beeper is the simplest
+shared connection. Each conversation still needs its own enrollment and reply
+settings. An available connection does not by itself enable automatic replies.
+
+## Choose a connection
+
+| App | Current route | Other options |
+| --- | --- | --- |
+| iMessage | Ghostget's native Mac connection, or Beeper on that Mac | Keep the native connection for users who do not use Beeper. Apple's Messages framework creates iOS conversation extensions; it is not a Mac inbox API. |
+| WhatsApp | Ghostget's reviewed linked-device connection, or Beeper | The official WhatsApp Business Platform is a separate business integration, not a connection to an ordinary personal inbox. |
+| Signal | Beeper | A future `signal-cli` connection is possible, but it is unofficial and needs separate maintenance and qualification. |
+| Telegram | Beeper, subject to the content-use limits below | Telegram's official TDLib supports personal client sessions. A direct connector is a future option, not currently implemented in Textbutler. |
+| Instagram | Beeper | Meta's official messaging API supports professional accounts. It does not cover the same personal-inbox use case. |
+
+Beeper documents support for these networks, with iMessage limited to macOS.
+Its Desktop API runs locally while Beeper Desktop is open. Beeper recommends
+on-device connections for this API; initial history can be incomplete.
+See [Beeper's Desktop API overview](https://developers.beeper.com/desktop-api/)
+and [connection types](https://help.beeper.com/chat-networks/using-on-device-chat-network-connections-in-beeper).
+Beeper labels the API a [public beta](https://www.beeper.com/desktop-api).
+Apple describes its [Messages framework](https://developer.apple.com/documentation/messages/)
+as a way to create sticker packs and iOS conversation extensions.
+
+## Connect Beeper
+
+1. Install Beeper Desktop and connect the messaging accounts you want to use.
+   Prefer on-device connections when using this Mac as your messaging host.
+2. Enable Beeper's local API. Its current authentication guide places approved
+   connections under **Settings → Integrations**; some releases use
+   **Settings → Developers**. Authorize Ghostget using its supported Beeper
+   account setup. Keep credentials out of contact folders.
+3. Use a Ghostget release that includes Beeper owner automation. This support
+   entered Ghostget's 0.18.14 source. It requires the reviewed Beeper adapter
+   and pinned Beeper CLI; an older read-only export setup is insufficient.
+4. Allow Ghostget's exact Beeper automation read and text-send operations for
+   that account. Then select its account ID in Textbutler setup.
+5. Enroll a single conversation, inspect its identity, and start with a reviewed
+   reply. Enable automatic replies separately after the connection and selected
+   agent account pass their checks.
+
+The current Ghostget automation route supports Beeper text sends and bounded
+conversation history. Beeper's wider API also offers attachments and other
+actions, but those are not yet admitted through this Textbutler route. The
+connection requires Beeper Desktop to remain open. Restart and reconnect should
+finish catching up before new messages can trigger a reply.
+See the [Ghostget owner contract](ghostget-contract.md) and
+[Beeper authentication](https://developers.beeper.com/desktop-api/auth/).
+
+iMessage in Beeper requires the Mac's Messages data, Automation, Accessibility
+and Contacts permissions. Beeper may briefly bring Messages into view. That
+connection remains on the Mac where it was configured.
+See [Beeper's iMessage setup guide](https://help.beeper.com/en_US/chat-networks/new-imessage-on-macos-getting-started-guide).
+
+## What “sent” means
+
+Beeper returns a pending message ID when it accepts a send request. That is not
+proof of delivery. The API can resolve that ID through a subsequent message
+read; delivery status is available only when the network reports it. Textbutler
+must preserve an uncertain result without sending the message again.
+See [Beeper's send contract](https://developers.beeper.com/desktop-api-reference/resources/messages/methods/send/).
+
+The optional Beeper WebSocket stream is experimental. Its sequence numbers
+apply to one connection, so they are not durable restart cursors. A production
+connector needs bounded catch-up reads after reconnection. Ghostget currently
+owns the durable observation boundary for Textbutler.
+See [Beeper's event stream](https://developers.beeper.com/desktop-api/websocket-experimental/).
+
+## Expansion without Beeper
+
+**iMessage and WhatsApp:** Improve the existing Ghostget setup and recovery
+paths first. Text and file support on iMessage should work with ordinary Mac
+permissions; advanced native actions depend on separately configured support.
+The current WhatsApp connection uses a reviewed private build of
+[wacli](https://github.com/openclaw/wacli), an unofficial linked-device client.
+Its pairing and update requirements are part of the integration.
+
+**Telegram:** TDLib is the strongest documented route to a direct personal
+client. It supplies login state changes, local storage, `getChatHistory`, and
+`sendMessage`. A shipped client needs its own application ID and hash, a user
+login flow, and protected local session storage.
+See [Telegram's TDLib guide](https://core.telegram.org/tdlib/getting-started)
+and [application registration](https://core.telegram.org/api/obtaining_api_id).
+
+Telegram's current terms restrict using platform content with AI. The content
+license describes exceptions only when all relevant users provide explicit,
+informed, affirmative and continued consent for the specific content and chat
+context. A Beeper connection does not remove that restriction. Do not treat
+owner login alone as authorization for unrestricted Telegram AI processing;
+resolve the applicable consent requirements before enabling that workflow.
+See [Telegram's API terms](https://core.telegram.org/api/terms) and
+[content license](https://telegram.org/tos/content-licensing).
+
+**Signal:** A future Ghostget adapter could link `signal-cli` to an existing
+account, receive messages through its daemon, and submit exact recipient-bound
+sends. The project explicitly calls itself unofficial and warns that versions
+older than three months may stop working. This adds a linked device and a
+maintenance obligation; it is not an official Signal integration.
+See [the signal-cli project](https://github.com/AsamK/signal-cli).
+
+**WhatsApp Business and Instagram professional accounts:** These are viable
+future business connectors with their own setup. WhatsApp uses a business
+account, registered business number, access tokens and webhook subscriptions.
+Instagram requires a professional account and messaging permission; its Send
+API generally replies after a person initiates contact and does not support
+group messaging. Neither route should be offered as a replacement for a
+personal inbox. See Meta's [WhatsApp Cloud API collection](https://www.postman.com/meta/whatsapp-business-platform/documentation/wlk6lh4/whatsapp-cloud-api)
+and [Instagram Send API](https://www.postman.com/meta/instagram/folder/uxudqu0/send-api).
+
+For personal Instagram, keep Beeper as the supported connection path. Avoid
+adding an independent private-API or browser-session connector until it has a
+maintained provider contract and reliable account recovery.
+
+These recommendations reflect documentation checked on September 19, 2026.
+Synthetic tests establish parser, permission and recovery behavior. A live
+acceptance check still needs the intended account, one exact recipient and an
+authorized message; it must verify reconnect and uncertain-send behavior as
+well as the first successful request.

package/docs/textbutler/native-process-plan.md

@@ -1,13 +1,14 @@
-# Agentrouter native process boundary
+# AgentMixer native process boundary
 
-Agentrouter owns provider policy and account leases. A shared native process
+AgentMixer owns provider policy and account leases. A shared native process
 transport owns an exact admitted process scope and byte streams. Applications
 own durable custody records, credentials, workspaces, artifact admission and
 recovery. Sharing the process implementation must preserve those owners.
 
-This plan starts from `a878d72d37ed86fd0cb3a3b78924a1221ce0135a`. Agentrouter is
-currently a private package under `packages/agentrouter`; this change does not
-publish it or activate a provider backend.
+This plan starts from `a878d72d37ed86fd0cb3a3b78924a1221ce0135a`. AgentMixer now
+lives in the standalone `hraness/agentmixer` repository as the published
+`@hraness/agentmixer` package; `agentmixer/` paths below refer to that
+repository's layout. This change does not activate a provider backend.
 
 ## Invariants
 
@@ -36,12 +37,12 @@ publish it or activate a provider backend.
 Implemented and independently reviewed source; repository integration remains
 pending:
 
-- `packages/agentrouter/src/process-port.ts` declares an in-memory
+- `agentmixer/src/process-port.ts` declares an in-memory
   `ProviderProcessPort`: readiness, root observation, exact native settlement,
   operation completion, bounded backend byte streams, explicit write outcomes,
   input closure and synchronous stop fences. It is not another wire protocol,
   launch API, runtime qualification or saved-PID signaling API.
-- `packages/agentrouter/src/codex-account-process.ts` binds that port to the
+- `agentmixer/src/codex-account-process.ts` binds that port to the
   existing account controller. It preserves native settlement independently of
   delivery success and joins delivery before reporting successful operation
   completion. Matching native `not-started` evidence needs no invented root
@@ -51,12 +52,12 @@ pending:
   each host write. An immutable binding alone cannot establish current authority.
   Rejected or asynchronous checks admit no bytes; any accidentally started
   promise remains owned until settlement. Late readiness after stop rejects.
-- `packages/agentrouter/src/codex-account-transport.ts` consumes explicit byte
+- `agentmixer/src/codex-account-transport.ts` consumes explicit byte
   outcomes instead of Node writable callbacks. RPC success requires both the
   matched response and full write acceptance within the caller's deadline.
   Failed or uncertain writes close admission. Node `end`/`close` settle local
   consumer work; only the injected host receipt proves native EOF.
-- `packages/agentrouter/src/codex-account.ts` publishes its shared close attempt
+- `agentmixer/src/codex-account.ts` publishes its shared close attempt
   before synchronously aborting the active request. Reentrant cleanup remains
   single-owned and an already queued write cannot run before that invalidation.
 - Synthetic tests cover pre-readiness cancellation, stale invocation and account
@@ -200,8 +201,8 @@ not establish shared artifact installation or live runtime qualification.
 Worker checks for phase 1 use synthetic streams only:
 
 ```sh
-bun test packages/agentrouter/test/codex-account-process.test.ts packages/agentrouter/test/codex-account-transport.test.ts packages/agentrouter/test/codex-account.test.ts
-bun x --no-install tsc --noEmit -p packages/agentrouter/tsconfig.json
+bun test agentmixer/test/codex-account-process.test.ts agentmixer/test/codex-account-transport.test.ts agentmixer/test/codex-account.test.ts
+bun x --no-install tsc --noEmit -p agentmixer/tsconfig.json
 git diff --check
 ```
 

package/docs/textbutler/native-subscription.md

@@ -0,0 +1,111 @@
+# AI subscriptions through xcb
+
+Textbutler uses [xcb (Excalibur)](https://github.com/hraness/xcb) to draft replies
+through an explicitly connected Claude Code or Codex subscription. xcb owns
+provider sign-in, runtime admission, operating-system confinement and account
+custody. Textbutler owns contact context, response policy and every message send.
+Textbutler is an MIT-licensed reference application for this separation.
+
+The connection requires a verified Textbutler bundle with reviewed composition
+admission and an xcb build with the native `generate` command. A source daemon
+has no embedded Textbutler admission and keeps subscription inference unavailable.
+A configured path, matching executable hash or signed-in account alone does not
+establish readiness. Check the exact provider through Textbutler and verify the
+selected messaging account before enabling replies. Synthetic tests do not
+prove live inference, delivery or unattended operation on another installation.
+
+## Connect an account
+
+Install xcb and connect the subscription account using its
+[native setup guide](https://github.com/hraness/xcb#native-xcb). xcb keeps its own
+private state; the native default is `~/.local/share/xcb`. Copy the exact account
+ID and full observed model key from `xcb accounts` and `xcb models`.
+
+Build and install Textbutler with `bun run textbutler:install`. Start its daemon
+through the installed command for AI replies. The build refuses absent or stale
+composition evidence; source startup cannot waive that check.
+
+Stop the Textbutler daemon before changing host configuration. Supply physical
+absolute paths and replace the example account and model with your observations:
+
+```sh
+bun run textbutler setup \
+  --xcb /absolute/path/to/xcb \
+  --xcb-state /absolute/path/to/xcb-state \
+  --xcb-account claude:ACCOUNT_ID \
+  --xcb-model FULL_MODEL_KEY
+```
+
+Repeat setup with `--xcb-account codex:ACCOUNT_ID` and its full model key to add
+a Codex account. Setup records the xcb executable's SHA-256 and the explicit
+account/model binding. It does not copy subscription credentials, create a
+provider sign-in or enable a contact. Restart the installed daemon, run `providers list`,
+and use the returned Textbutler account ID with `providers check ACCOUNT_ID`.
+This reads current xcb capabilities and admission; it does not make a model turn
+or prove reply quality. An unsent suggestion is the next inference check.
+
+Setup preserves existing bindings and refuses a changed executable, hash, state
+root, account or model. After upgrading xcb, stop the daemon and review the
+private `state/host.json` xcb binding before updating its executable digest.
+Retain account and custody state, then restart and check the account again.
+
+Native subscription routing never substitutes Claude API or another account.
+An unavailable, busy, stale or unsettled route remains unavailable until its
+specific condition is resolved. See [getting started](getting-started.md) for
+contact selection, reply review and explicit activation.
+
+## The application boundary
+
+Each inference step invokes the pinned native `xcb generate` process with a
+bounded JSON request on stdin. Private prompt content does not enter command
+arguments. This application command supplies no provider tools, workspace
+access, inherited coding session or executable hooks. Textbutler does not invoke
+`xcb run`, which is the workspace-oriented coding interface.
+
+The model returns a final JSON result or a proposal naming one advertised
+Textbutler operation. The contact-scoped broker validates proposals and performs
+only admitted operations: conditional contact-memory edits, bounded public web
+reads and staged reply actions. Classification advertises no operations. The
+provider cannot choose another contact, file root, recipient or credential.
+
+The next step contains only the bounded operation history Textbutler supplies.
+The native step loop permits at most 16 steps, 12 operations, 512 KiB of prompt,
+256 KiB per step and 1 MiB of transcript. Exceeding a bound stops the run. Failed
+operations are not replayed because an effect may already have committed.
+
+A proposed message never sends itself. Trusted Textbutler code applies
+disclosure, human takeover, current enrollment, review or automation authority,
+idempotency and the durable send journal immediately before dispatch.
+
+## Custody and recovery
+
+xcb retains subscription credentials and provider state outside Textbutler's
+contact folders. It serializes use of an account and releases custody only after
+its provider process and controllers have joined. Textbutler validates the
+generation result and its settlement facts before accepting output. Cancelling
+a request or observing the xcb parent exit alone does not prove provider cleanup.
+
+Textbutler also preserves an uncertain application invocation for recovery.
+Restarting, reinstalling or repeating setup must not clear that record. Inspect
+the exact xcb run and Textbutler diagnostic before recovery; never delete
+custody state simply to make the account appear ready.
+
+## Evidence and distribution
+
+The local Textbutler bundle contains its application code and pinned library
+dependencies. Its build validates a separately reviewed composition receipt
+against the exact source inventory and both contact capability profiles, then
+embeds that admission. Missing evidence or source/profile drift rejects the
+build; hashes and xcb sign-in cannot create this evidence. xcb and provider executables are installed separately. Its
+`external-xcb` manifest value identifies this connection capability; it is not
+a provider qualification, a signed release or a live messaging receipt.
+
+xcb independently checks the selected provider's exact runtime and confinement
+on each invocation. Its provider-specific readiness may differ by build and
+host; consult the [xcb readiness table](https://github.com/hraness/xcb#readiness).
+Textbutler must also prove its classifier/reply parsing, cancellation and broker
+boundaries. Before relying on automatic replies, exercise one agreed recipient,
+pause, owner takeover, transport loss, restart and grant expiry. The
+[readiness page](readiness.md) separates these acceptance requirements from
+source tests. The separately billed Claude API route retains its own trusted
+runtime admission requirement in [provider setup](../../packages/textbutler/PROVIDERS.md).