@hraness/message-like-me 0.8.10 → 0.8.12

package/docs/support-foundation-notice.md

@@ -0,0 +1,28 @@
+# Shared support protocol notice
+
+The CLI includes `@hraness/support-foundation` 0.3.0 from reviewed commit
+`2d034b357680353574411217d68b02b6755b07ed` of
+[Hraness Support Foundation](https://github.com/hraness/support-foundation).
+Its code is bundled only for the command-line support flow; public SDK exports do not include it.
+
+MIT License
+
+Copyright (c) 2026 Hraness
+
+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/docs/textbutler/agent-cli.md

@@ -0,0 +1,123 @@
+# Use TextButler from an agent
+
+TextButler's CLI returns JSON for conversation reads, summaries, drafts and
+sends. Run it as the signed-in Mac user with the TextButler daemon running.
+Connect iMessage and your AI subscription using the [setup guide](getting-started.md).
+Explicit owner commands work while automatic replies are paused and the
+selected contact is disabled.
+
+## Select a conversation
+
+```sh
+textbutler conversations list
+textbutler contacts add CANDIDATE_ID
+textbutler contacts list
+textbutler messages capabilities CONTACT_ID
+```
+
+Use the exact IDs returned by the preceding commands. A unique contact name
+also works; ambiguous names fail. Adding a contact keeps automatic replies off.
+Add `--history` to `contacts add` only when you want a retained history import.
+Reading current history does not require that import.
+
+## Read and summarize
+
+```sh
+textbutler messages history CONTACT_ID --limit 100
+textbutler contacts account CONTACT_ID native-claude-code
+textbutler messages summarize CONTACT_ID --limit 100
+```
+
+History includes message IDs, authorship, time, text, related message IDs and
+attachment metadata when the provider exposes it. Attachment metadata contains
+names, media types and sizes; local file paths and contents are excluded.
+Limits range from 1 to 200 messages. The response reports
+shortened text and omitted records; it is a recent sample, not a complete
+archive. It does not download or interpret attachment contents.
+
+Summaries use the contact's selected, qualified subscription account. The
+response includes source message IDs and the size of the sample used. Review
+the generated interpretation against those messages. A calling agent can also
+summarize the history JSON itself without starting another inference request.
+
+## Compose, review and send
+
+Choose one way to create an unsent draft. For an AI suggestion:
+
+```sh
+textbutler replies suggest CONTACT_ID
+```
+
+Suggestions read the current conversation without requiring a history import.
+If there is no unanswered incoming message, the command returns no draft.
+To provide the content yourself instead:
+
+```sh
+textbutler messages compose CONTACT_ID --text 'Tuesday works for me.'
+```
+
+Use the returned draft ID to review it, then send only when instructed:
+
+```sh
+textbutler replies show DRAFT_ID
+textbutler replies send DRAFT_ID DIGEST
+```
+
+Use the digest returned by the complete draft review. It binds the recipient,
+content and imported media. Changed conversations or media can invalidate a
+draft. Disclosure settings apply to the reviewed and sent content.
+There is one active draft per contact; creating another replaces it. Drafts
+expire after 15 minutes and are cleared when the daemon restarts. Use
+`textbutler replies discard DRAFT_ID` to discard one explicitly.
+
+An explicitly authorized literal text can be sent in one command:
+
+```sh
+textbutler messages send CONTACT_ID --text 'I have arrived.'
+```
+
+Treat that command as an outward action. A CLI's availability is not permission
+for an agent to message someone without its user's instruction.
+
+## Media and reactions
+
+Inspect `messages capabilities CONTACT_ID` before requesting an action.
+These commands create unsent drafts for the same review and send flow:
+
+```sh
+textbutler messages attach CONTACT_ID /absolute/photo.jpg --caption 'Our view today'
+textbutler messages react CONTACT_ID MESSAGE_ID '👍'
+textbutler messages react CONTACT_ID MESSAGE_ID '👍' --remove
+```
+
+Media imports accept owned regular files up to 16 MiB and copy them into the
+selected contact's private outbox. The draft records the imported bytes; later
+changes to the original source file do not change that copy. Common image,
+audio, video and document types are recognized. Transport support and current
+account permissions still determine whether an attachment can be sent.
+
+For an ordered batch, put 1–7 supported action objects in a JSON array and use
+`messages compose CONTACT_ID --actions /absolute/actions.json`. The supported
+shapes are defined by the [action types](../../packages/transport/src/types.ts).
+Attachment and sticker paths in an action object are relative to that contact's
+workspace. The daemon validates targets, capabilities and imported media.
+
+The current connector supports ordinary text and media on a Mac with the
+required permissions. Standard reactions, stickers, rich links and polls
+require its separately configured Messages bridge and the corresponding
+advertised capability. TextButler does not install that bridge or change macOS
+security settings. Outgoing threaded reply targeting, App Clips and experiences
+are unsupported by the iMessage connector. The CLI does not turn a requested
+thread reply into an ordinary message. Incoming reply relationships remain
+visible in history.
+
+## Read uncertain results
+
+Long operations may return a job ID. Read that exact job with
+`textbutler jobs show JOB_ID`; do not repeat the original send. A successful
+transport receipt reports `submitted`. A `partial` or `indeterminate` outcome
+needs reconciliation before another attempt. Commands return a nonzero exit
+code for pending or unsuccessful sends.
+
+Append `--data-dir /absolute/private/path` to use another installation.
+`textbutler messages --help` lists the agent commands.

package/docs/textbutler/architecture.md

@@ -1,18 +1,20 @@
 # Textbutler architecture
 
-Textbutler is a personal message butler for macOS. An owner activates a bounded set of contacts. Each contact gets a private workspace that a coding agent can read and evolve. A separate daemon decides when to invoke that agent and controls every outward action.
+Textbutler is a personal message butler for macOS. An owner activates a bounded set of contacts. Each contact gets a private workspace that a model can read and evolve through Textbutler's broker. A separate daemon decides when to invoke that agent and controls every outward action.
 
-The source includes the owner daemon, contact reply loop, versioned Ghostget automation protocol and Mac application. Synthetic tests establish their control and recovery behavior. Live provider delivery and signed distribution have separate acceptance requirements below.
+The source includes the owner daemon, contact reply loop, versioned Ghostget automation protocol and macOS menu companion. Synthetic tests establish their control and recovery behavior. Live provider delivery has separate acceptance requirements below; the companion is a CLI artifact and has no signing or notarization gate.
 
 ## Ownership
 
 ```mermaid
 flowchart LR
-  App[Mac settings app] --> Control[Owner-only control socket]
+  Menu[Menu companion] --> Control[Owner-only control socket]
   Control --> Butler[Textbutler daemon]
-  Butler --> Router[Agentrouter]
-  Router --> Provider[Admitted agent provider]
-  Provider --> Tools[Contact-bound tool broker]
+  Butler --> Xcb[xcb zero-tool generate]
+  Xcb --> Provider[Admitted subscription provider]
+  Provider --> Proposal[Structured result or proposal]
+  Proposal --> Butler
+  Butler --> Tools[Contact-bound tool broker]
   Tools --> Memory[One contact workspace]
   Tools --> Web[Public web broker]
   Tools --> Intents[Proposed actions]
@@ -22,9 +24,9 @@ flowchart LR
   Ghostget --> Messages[iMessage and WhatsApp]
 ```
 
-Ghostget owns native permissions, message and contact acquisition, provider actions, and receipts. Textbutler does not open chat.db or automate Messages directly. Agentrouter owns provider selection, shared-account leases, cancellation, model catalogs, qualification evidence, and a bounded tool interface. Textbutler owns conversation policy and the durable send transaction. The Mac app changes owner settings through a small local protocol; it never gives a model arbitrary Tauri commands.
+Ghostget owns native permissions, message and contact acquisition, provider actions, and receipts. Textbutler does not open chat.db or automate Messages directly. xcb owns subscription credentials, provider admission, model catalogs, confinement, cancellation and account custody. Textbutler invokes its native zero-tool generation API and interprets returned operation proposals through its own contact broker. Textbutler owns conversation policy and the durable send transaction. The menu companion changes owner settings through a small local protocol; it never gives a model arbitrary local commands.
 
-The background lifecycle uses a user LaunchAgent: native messaging belongs to the signed-in Mac user, and login persistence is independent of the settings window. Installation records the exact runtime, entrypoint, data directory and generation; removal verifies its private receipt and loaded service identity. Uninstall preserves contact data. New settings start paused. A private SQLite custody lock prevents duplicate daemon ownership and permits recovery only for a dead recorded process and its exact unserved socket. A temporary live launchd install/start/uninstall test passed while preserving synthetic owner data. Signed distribution remains a separate gate.
+The background lifecycle uses a user LaunchAgent: native messaging belongs to the signed-in Mac user, and login persistence is independent of the menu companion. Installation records the exact runtime, entrypoint, data directory and generation; removal verifies its private receipt and loaded service identity. Uninstall preserves contact data. New settings start paused. A private SQLite custody lock prevents duplicate daemon ownership and permits recovery only for a dead recorded process and its exact unserved socket. A minimal native TextButler.app can supervise the verified daemon so Full Disk Access belongs to the app. Its private installation receipt pins the runtime, payload, native executable and signature resources; a changed identity blocks startup. The app accepts fixed daemon, menu and iMessage setup roles, with no arbitrary command passthrough. Local builds use an ad-hoc signature, so a rebuilt app may require a fresh macOS permission grant.
 
 The daemon serves owner controls, enrollment jobs and a reply loop through its own supervised Ghostget process. Startup, enablement and recovery establish a silent event boundary, refresh bounded history and admit only subsequent eligible inbound messages. A failed catch-up pauses the affected conversation. No provider work starts without explicit owner account configuration.
 
@@ -37,7 +39,7 @@ Textbutler/
   daemon.sock                  owner-only native control socket
   state/
     settings.json              owner configuration and contact bindings
-    host.json                  optional private installed Ghostget CLI/account binding
+    host.json                  private Ghostget and xcb executable/account bindings
     runs.sqlite                private run and send journal
     daemon-custody.sqlite      exclusive process/socket ownership
     launch-agent-custody.sqlite lifecycle serialization
@@ -62,7 +64,7 @@ Directory names use opaque identifiers, not contact names or phone numbers. File
 
 The owner chooses one verified direct conversation from a bounded Ghostget list. Enrollment rechecks the account incarnation and participant identity and creates a disabled contact. History import is a separate opt-in, limited to 200 recent, explicitly scoped messages, with message ID, time, and author preserved. The import records shortening and omissions; it does not fetch media. These records are context only, and historical automation may be unobservable. A later qualified initialization run may summarize preferences, conversational style, open tasks, and useful context into memory. It must distinguish evidence from inference and retain uncertainty. Later runs correct outdated notes and record sources. Proven butler output never becomes owner-style training evidence. No global person model or cross-contact retrieval is supplied by default.
 
-The original Message Like Me corpus and profile tools remain an optional bounded bootstrap source. They do not become the live message transport. Old databases are not reset or silently migrated. There is no need to carry every previous archive/source feature into the new UI.
+The original Message Like Me corpus and profile tools remain an optional bounded bootstrap source. They do not become the live message transport. Old databases are not reset or silently migrated. There is no need to carry every previous archive/source feature into the menu companion.
 
 ## Reply admission
 
@@ -74,7 +76,7 @@ The daemon waits eight seconds after an incoming message to collect a burst. New
 
 A whole-word, case-insensitive `butler` invocation permits a response after those deterministic gates. In keyword mode, other messages stay silent. In smart mode, a tool-free cheap model returns a strict structured classification. It should answer useful assistance requests, and stay silent during ordinary conversation, acknowledgments, emotional exchanges, or uncertain intent. Confidence below 0.85 stays silent. Malformed results, exhausted accounts, stale model catalogs, or timeouts never escalate to a more expensive agent automatically.
 
-Classifier choice comes from the selected provider's fresh available-model catalog, with explicit cost metadata and structured-output capability. No permanently hard-coded "cheap" model alias is assumed. An owner can pin a classifier or reply model after availability validation. Classifier and responder share the chosen provider/account policy; one classifier gets no tool authority.
+The xcb subscription route uses the owner-selected full model key for classification and replies; a subscription model is not assigned invented API prices. The separately billed API route selects its classifier from fresh availability and explicit cost metadata. Classifier and responder share the chosen provider/account policy, and classification receives no operation authority.
 
 No typing signal can prove the owner is absent. The current adapters expose no typing signal; the daemon retains its message-based cooldown and final revision checks. The selected provider/account must independently qualify before smart mode can invoke a model.
 
@@ -82,41 +84,86 @@ No typing signal can prove the owner is absent. The current adapters expose no t
 
 The model proposes actions. It does not dispatch them. Owner-installed hooks may shape the work or veto a reply, but all action validation, contact binding, limits, and disclosure run afterwards.
 
-Every text action is wrapped by trusted code with the contact's three symbols. Each field must be one visible grapheme; an empty or invisible disclosure is rejected. Default rendering is `🤖{ hello this is my response }`.
+Every text action is wrapped by trusted code with the contact's three symbols. Each field is either cleared (empty) or exactly one visible grapheme; invisible or multi-grapheme fields are rejected. Default rendering is `🤖{ hello this is my response }`. Clearing all three fields removes the visible wrap entirely and sends plain text.
 
-Reactions, stickers, link previews, and app cards cannot literally carry that text prefix. A disclosed text companion is therefore the first action in a nontext response, and counts toward the eight-action maximum. The provider must execute in order and stop if that companion fails. App-specific cards may additionally identify Textbutler in their content, but never remove the companion requirement.
+Clearing disclosure never makes butler output indistinguishable internally. The transport reports the provider-accepted message IDs for every submitted action, and the daemon records them in a private `sent_messages` journal table. History and attribution classify an outgoing message as butler-authored through that journal first, and through the configured visible wrap for sends that predate it. A cleared wrap simply has no visible form; provenance stays exact.
+
+Reactions, stickers, link previews, and app cards cannot literally carry that text prefix. When visible markers remain configured, a disclosed text companion is therefore the first action in a nontext response, and counts toward the eight-action maximum. With disclosure fully cleared the companion would be unexplained extra text and is not added. The provider must execute in order and stop if that companion fails. App-specific cards may additionally identify Textbutler in their content, but never remove the companion requirement.
 
 Before send, the runtime rechecks owner activity, conversation revision, current settings, capability availability, cancellation, attachment ownership, target message membership, and the contact grant. It asks the transport to prepare an exact plan with an expiry and digest. Immediately before submission, it journals the dispatch intent. The transport must atomically validate the grant, contact route, context revision, and plan digest at its own effect boundary.
 
 `submitted` is not `delivered`. Partial and indeterminate outcomes pause further automated activity for that contact until explicit reconciliation. A crash while dispatching becomes indeterminate on recovery; it never causes a blind retry. A crash before dispatch abandons the run without sending. Provider failover cannot replay a possibly submitted action.
 
-## Hooks and plugins
+## Owner reply triage
 
-The initial lifecycle is `message.received`, `reply.decide`, `reply.compose`, `reply.before-send`, `reply.sent`, `memory.updated`, and `run.failed`. Hooks have a named/versioned owner-installed extension, deterministic registration order, a deadline, and a cancellation signal. Failure before dispatch closes admission. A notification-hook failure after a receipt cannot change that receipt or trigger resend.
+The same machinery serves an explicit owner workflow that is distinct from automatic replies. `textbutler inbox` (or the menu's **Replies → Check for replies**) runs a bounded read-only pass over every enrolled conversation and reports each trailing run of unanswered inbound messages: the contact, a bounded sanitized preview, the pending count, whether a send is currently possible, and why not when it is not. The automatic loop's live observations feed the same view, so the inbox reflects what the daemon already saw between scans.
 
-Executable extensions are application code with the daemon's trust. They are installed outside contact folders; the agent cannot write them or turn message text into imports. Agent self-evolution means revising guidance and memory, not installing executable code. A future untrusted plugin mode needs its own process or language sandbox and explicit capabilities. In-process hooks are never described as a plugin security boundary.
+`textbutler replies suggest CONTACT` asks the contact's configured agent to draft a reply for that pending run. A suggestion is a bounded draft with a fifteen-minute expiry: summary, exact proposed actions, and the disclosed preview the send would carry. It never dispatches. Drafts bind the conversation revision and disclosure settings they were created against; a stale context, changed disclosure, or expired draft is rejected rather than silently sent.
 
-The daemon reads a bounded private `plugins/extensions.json` manifest and preflights its complete inventory before importing listed TypeScript/JavaScript entry modules. Each default export must match the manifest ID/version and known hook names. Source digests appear in the loaded extension metadata. No directory scanning, package installation or hot reload occurs; changes require a full daemon process restart. The routed agent emits `memory.updated` only after a successful conditional write, with its path and committed revision. A notification failure does not undo that write or replay it.
+`textbutler replies show DRAFT` exposes every ordered disclosed action, exact recipient, attachment hash and review digest. `textbutler replies send DRAFT DIGEST` sends only that exact reviewed draft, and `textbutler replies send CONTACT TEXT...` sends literal owner text through the identical grant, plan, journal, disclosure and reconciliation discipline as an automatic reply. `textbutler replies discard DRAFT` drops a suggestion. The menu bar exposes scan, per-conversation suggestion, labeled draft previews and discard. Complete review and digest-bound sending happen in the terminal or CLI; a truncated preview cannot authorize a send.
 
-## Agentrouter
+An owner send reuses the contact's live standing grant when it covers the needed action kinds with remaining quota. Otherwise the daemon issues a tightly scoped grant: only the specific action kinds, ten-minute expiry, quota equal to the action count. The scoped grant is journaled with intent and pending state, published to the conversation, and revoked after the send when the contact is disabled. One serialized work registration covers grant issuance and dispatch together so delegated renewal and disable-revocation cannot race an in-flight send. The agent never sees this surface; it has no send authority in either direction.
 
-Agentrouter begins as an MIT-licensed source package independent of Textbutler's product model. Its account lease coordinates the selected provider account without embedding credentials in a contact workspace. Credential resolvers remain trusted host services. A lease cannot be stolen merely because its time elapsed while a process might still be alive.
+`replies.send` returns `submitted`, `failed`, `partial`, `cancelled`, or `indeterminate`. An indeterminate owner send blocks the next reply for that contact — automatic or owner-initiated — until the journaled intent is reconciled, exactly like an automatic send.
 
-Provider adapters declare observed, exact-version qualification. A launch plan is not proof of a sandbox. Codex's shell-disable setting and Claude's exact tool list are useful inputs, but an adapter is not admitted until attempted shell/process calls, host file reads, inherited MCP/plugin configuration, auth-file access, alternate agents, and additional workspaces are demonstrably blocked. No bypass-permissions mode is acceptable.
+## Hooks and plugins
 
-The source implements a pinned Claude Agent SDK adapter with explicit API-key account binding, a private verified executable snapshot, isolated runtime directories, no built-in tools or inherited settings, broker-only MCP, bounded raw output, and joined process-group termination. Its production gate requires independent qualification of the exact executable and SDK identity. Synthetic protocol and native-runtime fixtures do not activate it. The experimental Codex app-server driver verifies each model request's tool inventory through a host relay and keeps contact storage outside native scratch. It has no live account transport or production registration; native confinement and adversarial custody qualification remain incomplete. See the [Agentrouter implementation and evidence](../../packages/agentrouter/README.md).
+The initial lifecycle is `message.received`, `reply.decide`, `reply.compose`, `reply.before-send`, `reply.sent`, `memory.updated`, and `run.failed`. Hooks have a named/versioned owner-installed extension, deterministic registration order, a deadline, and a cancellation signal. Failure before dispatch closes admission. A notification-hook failure after a receipt cannot change that receipt or trigger resend.
 
-A separately selected Claude API adapter executes the bounded tool loop in the trusted host. It exposes only the six broker tools and never starts a model-selected process. Account checks bind the actual packaged runtime and private credential generation; replacing a credential invalidates old discovery and running account work. Fresh model availability and price metadata select a cheap classifier. This explicit API choice does not silently replace Claude Code or Codex and does not use their subscription authentication.
+Executable extensions are application code with the daemon's trust. They are installed outside contact folders; the agent cannot write them or turn message text into imports. Agent self-evolution means revising guidance and memory, not installing executable code. A future untrusted plugin mode needs its own process or language sandbox and explicit capabilities. In-process hooks are never described as a plugin security boundary.
 
-The model receives a fixed contact/workspace identity and a fixed run ID. File operations are brokered and conditional. Public web requests are separately bounded and must not reach loopback, private networks, local sockets, or cloud metadata through DNS or redirects. Message tools stage recipient-free intents for the one conversation. Unknown tool names and unknown input fields fail. Credential/account services are never model tools.
+The daemon reads a bounded private `plugins/extensions.json` manifest and preflights its complete inventory before importing listed TypeScript/JavaScript entry modules. Each default export must match the manifest ID/version and known hook names. Source digests appear in the loaded extension metadata. No directory scanning, package installation or hot reload occurs; changes require a full daemon process restart. The routed agent emits `memory.updated` only after a successful conditional write, with its path and committed revision. A notification failure does not undo that write or replay it.
 
-Oompa's existing runtime provider port and account/process-custody patterns are source references. Its ordinary workspace-write execution profile is not the requested contact-only sandbox. AI Charts is a prospective second consumer. Do not migrate either product to Agentrouter until an adapter has equivalent feature and recovery evidence; avoid changing their active work in this redesign.
+## xcb application contract
+
+Textbutler is an MIT-licensed reference application for
+[xcb](https://github.com/hraness/xcb). AI execution requires a verified Textbutler
+bundle whose build validates independently reviewed composition evidence against
+current source bytes and both contact capability profiles. The build embeds
+this application admission separately from xcb's provider admission. Source
+daemon startup carries no composition admission and cannot enable this route. The native `generate` process provides a
+bounded application request/result interface over stdin and stdout. The owner
+pins the physical xcb executable and selects an explicit private state root,
+subscription account and full model key. xcb and the provider executables are
+separate installations; contact memory cannot edit their configuration.
+
+xcb generates with zero provider tools and no inherited coding session. It owns
+provider credentials, runtime admission, operating-system confinement and
+process cleanup. Textbutler sends bounded contact context, validates the
+structured response and accepts output only with a settled execution receipt.
+A hash match or a root process exit alone cannot establish this receipt.
+Uncertain cleanup preserves custody and blocks another invocation.
+
+For replies, the model can propose a Textbutler operation. The application
+validates the exact operation and closed input, calls its contact-bound broker,
+and includes a bounded result in the next inference step. Classification
+advertises no operations. The native provider never receives a filesystem or
+messaging tool. The [subscription guide](native-subscription.md) documents setup,
+limits and recovery. Credentials remain in xcb; grant and send authority remain
+in Textbutler and Ghostget.
+
+The retained AgentMixer compatibility library supplies shared application types
+and broker helpers. Its historical package identity remains pinned for
+reproducible builds; applications need not import private xcb internals or share
+a source checkout. The native process contract is the subscription boundary.
+
+A separately selected Claude API adapter executes a bounded tool loop in the
+trusted host. That route still requires independent packaged-runtime admission,
+an explicit API credential and current model/price evidence. Neither source
+startup nor local distribution integrity provides this admission, and an xcb
+subscription failure cannot switch to API billing.
+
+The model receives a fixed contact/workspace identity and run ID. File
+operations are brokered and conditional. Public web requests are bounded and
+cannot reach private networks, local sockets or cloud metadata through DNS or
+redirects. Messaging operations stage recipient-bound intents. Credential and
+account controls are never model tools.
 
 ## Ghostget contract and rich features
 
 WhatsApp follows the same Ghostget ownership boundary. Its private wacli-backed transport provides durable observations and recipient-bound actions; pairing, session state and synchronization stay in Ghostget. The [WhatsApp guide](whatsapp.md) describes setup and action support. Textbutler does not embed WPPConnect or invoke wacli directly.
 
-Current source inspection found Ghostget's Tauri 2 webview with a packaged Bun helper. That helper lives with the app, and its private socket handles approvals/control, not a public messaging subscription service. Textbutler must not couple to it.
+Ghostget owns its provider process and private control socket; Textbutler consumes only Ghostget's documented CLI and automation contracts.
 
 The older generic messaging APIs retain expiring route references and owner-confirmed previews. Automation uses a separate explicit owner protocol with durable enrollment, revocable grants and event observations. The iMessage provider negotiates attachments, reactions, stickers, rich links and polls separately; unsupported App Clips and arbitrary experiences remain unavailable. Native Contacts directory discovery is not implemented in this protocol.
 
@@ -132,17 +179,17 @@ Linq's documented iMessage API includes attachments, reactions, stickers, rich l
 
 Ghostget currently imports published Message Like Me bundle contracts. Keep that immutable package a leaf. Do not repoint it at the Textbutler runtime. Extract the neutral bundle contracts before reversing a live package dependency, or consume Ghostget's installed CLI contract without a package import in the interim. Preserve historical wire-format identifiers.
 
-## Mac application
+## macOS menu companion
 
-The app has an explicit conversation picker, optional history initialization, a contact list, per-contact activation and mode settings, disclosure preview, memory editing, activity, provider status, and global pause. Long provider reads use bounded asynchronous jobs; Pause stays available and preserves unsaved choices. Unsupported capabilities show their actual setup or transport limitation. A separate synthetic demo is clearly labeled and is not included in the native app's live data graph.
+The status-item companion can be launched by the CLI or the native app. It exposes daemon state, contact and account readiness, capabilities, recent activity, pause/resume, conversation selection and the reply inbox. The terminal supports complete draft review and setup. The website action opens the informational textbutler.app page. The companion is not required to run the daemon.
 
-One narrow native command accepts the versioned control request. It connects to the private user socket, bounds requests/responses, applies timeouts, and verifies same-user ownership. The webview has no generic shell, filesystem, opener, or network plugin. The app does not inherit access to arbitrary Ghostget operations.
+One narrow native command accepts the versioned control request. It connects to the private user socket, bounds requests/responses, applies timeouts, and verifies same-user ownership. The companion has no generic shell, filesystem, opener, or network plugin and does not inherit access to arbitrary Ghostget operations.
 
 ## Admission still required
 
-1. Use the verified Ghostget 0.18.2 package, which includes the reviewed automation source and native helpers. Real account synchronization, recipient identity, rich actions and revocation still require a bounded owner-authorized live test; artifact admission and synthetic fixtures do not prove delivery.
-2. Independently qualify the native Claude SDK and Codex adapters for the requested no-shell, contact-only profile before enabling those choices. The separate Claude API path requires explicit account setup and packaged-runtime admission.
-3. Sign and notarize the exact Mac artifact with an available Apple Developer identity, then verify the final downloaded bytes and installation lifecycle. The unsigned local package and successful launchd test are not a signed release.
+1. This development version pins Ghostget 0.18.21 for native TextButler iMessage setup; matching artifact admission and live conversation checks remain pending. Preserve its native helper resource bundle, protected-folder startup fix, partial discovery that excludes chats without usable participant metadata, and bounded discovery diagnostics without message bodies. Real account synchronization, recipient identity, rich actions and revocation still require a bounded owner-authorized live test; artifact admission and synthetic fixtures do not prove delivery.
+2. Use a verified Textbutler bundle with reviewed composition admission and connect an admitted native xcb build through its zero-tool generation contract. Verify the exact provider/account, both classifier and reply behavior, cancellation and uncertain-custody recovery before enabling automatic replies. The separate Claude API path retains explicit account setup and packaged-runtime admission.
+3. Publish the CLI package with its pinned desktop-foundation SDK dependency. Verify the package bytes, the verified pinned runner download, singleton behavior, and the shared autostart install/uninstall lifecycle. A source checkout or missing companion must never trigger a build at launch.
 4. Keep historical repository and published package identities as compatibility and provenance anchors. The Textbutler site is assigned to `textbutler.app`; later identity migrations must preserve immutable artifacts and existing release protections.
 
 ## Sources