@hraness/message-like-me 0.8.9 → 0.8.11

package/docs/publishing.md

@@ -1,5 +1,99 @@
 # Publish Message Like Me
 
+## Textbutler informational-site delivery
+
+The following explicit site-subject route supersedes the package-publication
+prerequisite below for the informational Textbutler website only. It grants no
+package publication, native app release, provider qualification, or live message
+authority. The legacy tagged package route and its exact-byte/npm checks remain
+unchanged. Source repository identity is the canonical `hraness/textbutler`
+with unchanged numeric repository ID `1342143606`.
+
+Use the existing `Promote website production` workflow with `site_sha` set to
+the exact reviewed current `main` commit, `site_ci_run_id` and
+`site_ci_run_attempt` set to its successful `CI` run, and `release_tag` empty.
+Do not rerun a promotion attempt; make a fresh attempt-1 dispatch. The route
+requires exactly the current standalone/site job and macOS fixture/native job,
+rejects an older attempt after CI is rerun, rebuilds the site, and admits a
+bounded immutable Actions build-manifest artifact by exact run, attempt, source
+tree, site subtree, lockfile digest, artifact ID/digest, and manifest bytes.
+
+An advancing site target uses the same `website-production` ref, shared
+promotion concurrency, existing status-only App, environment, rulesets, and
+ordinary GitHub Actions ref writer as the legacy route. Before the App key is
+available, complete governed Git histories and all ordered workflow-tree
+changes must pass the site control-epoch admission. A changed workflow range
+requires the independently reviewed exact digest emitted by preflight in
+`control_epoch_digest`; unchanged ranges reject a supplied digest. Site epochs
+use domain `textbutler/control-epoch/site/v1`, bind target and workflow source to
+the same current `main` commit, and carry `tag: null`. They cannot authorize a
+legacy package release. Both routes retain checked helper hashes and code-owner
+review for the complete authority implementation.
+
+Preserve the environment's actual protection rules. If the existing key
+environment requires a reviewer, satisfy that exact run's review through
+GitHub's normal environment approval interface after source admission and
+independent control review. The site redesign does not remove reviewers, wait
+timers or other runtime gates; the legacy setup policy below is not permission
+to bypass an existing protection.
+
+The site writer consumes prior status, proves that the ordinary writer is
+denied by the exact required App status, attests one target, revokes the App
+token, verifies current rules/status/source again, and makes one sterile
+fast-forward push with the expected-old lease. App-only steps receive no ref
+token; writer/admission steps receive no App key. The terminal consumption step
+runs even after failure or cancellation when admission completed. The final
+read-only jobs verify status consumption, revocations, unchanged rules, and
+twice-confirmed REST/GraphQL Vercel Production identity for the exact source.
+
+`textbutler-site-attempt` retains the explicitly listed public phase receipts
+for 30 days when the runner can upload them. Hard termination may prevent this
+upload; remote ref/status/provider readback and the existing interrupted
+authority cleanup remain authoritative. Never blindly repeat an uncertain
+write. If the ref already equals the site source, a fresh dispatch takes a
+read-only qualification route with no App key or ref token. It requires the
+status already consumed by the exact App bot (including its numeric actor
+identity), the unchanged App-pinned rules, and the matching Production
+deployment after the original successful CI completion. The retry's newly
+built manifest is not treated as that existing deployment's publication time.
+Leave `control_epoch_digest` empty for this already-exact route. An outstanding
+success status must first pass the documented custody cleanup, not be silently
+cleared by read-only qualification.
+
+After provider success, verify `textbutler.app` serves the exact intended
+deployment, truthful development status, canonical metadata and legacy links.
+The current Vercel project/production branch remain the target; domain or
+repository renaming is a separate inspected provider mutation.
+
+## Repository identity migration
+
+The repository rename keeps numeric GitHub repository ID `1342143606` and the
+existing GitHub Apps, rulesets, protected refs, status contexts, environment
+reviewers, workflow IDs, Vercel project, and production branch unchanged. The
+canonical source identity for new release and promotion runs is
+`hraness/textbutler`; an old-name redirect is not authority for a new run.
+The npm names `@hraness/message-like-me` and `@hraness/agentrouter`, their tag
+namespaces, the `messagelikeme` command, wire schemas, and historical release
+receipts remain unchanged. Do not rewrite an existing tag, npm version, or
+provenance statement.
+
+Merge this version-neutral control migration independently before the next
+product/version change. Refresh the complete administrative controls census
+and independently review the exact helper/workflow changes. Before tagging,
+read back each applicable npm trusted publisher and require canonical repository
+`hraness/textbutler`, its existing exact workflow filename and permission set.
+An old publisher identity blocks publication; do not fall back to a personal
+token or weaken its policy. Any needed provider reconciliation is a separate
+inspected operation. Historical versions retain their original provenance and
+are not evidence for a new canonical-repository publication.
+
+Before production promotion, follow the existing no-digest preflight and exact
+reviewed control-epoch transition below. Preserve the actual key-environment
+review and satisfy it through GitHub's normal interface. Neither the rename nor
+this source migration permits an out-of-band ref move or a protection change.
+
+## Legacy package publication
+
 Message Like Me builds one exact public package tarball, validates those bytes
 on macOS and Linux, and publishes the same tarball plus `SHA256SUMS` to an
 immutable GitHub Release. Only then does it publish that tarball to npm through
@@ -20,6 +114,33 @@ denial, expected-old lease, and provider readback are machine gates. An agent
 may perform the independent review and exact dispatch required for a changed
 workflow-control epoch; that review precedes dispatch.
 
+## AgentRouter package publication
+
+`@hraness/agentrouter` publishes through its own tag namespace and its own
+tag-triggered workflow, `release-agentrouter.yml`, mirroring the root Release
+contract. An annotated `agentrouter-v<version>` tag on a reviewed `main`
+ancestor runs the same verify → exact-artifact → immutable GitHub Release →
+read-only retry admission → OIDC-only npm writer → final public admission
+chain, with the AgentRouter package manifest, tarball name, tag prefix, and
+workflow path bound through the shared closed release-package descriptor. Both
+release workflows share concurrency group `stable-release`, so a root and an
+AgentRouter release can never interleave their GitHub Latest assertions. The
+AgentRouter channel has no site or production-promotion coupling; its releases
+distribute the package only.
+
+Owner-side controls required once before the first AgentRouter tag:
+
+- Extend the immutable-tag ruleset coverage to `refs/tags/agentrouter-v*` with
+  the same update and deletion restrictions and no bypass actors as the
+  existing `refs/tags/v*` scope.
+- Ensure `@hraness/agentrouter` exists publicly under the Hraness npm scope,
+  then configure its sole trusted publisher as GitHub Actions repository
+  `hraness/textbutler`, workflow file `release-agentrouter.yml`. Require
+  the exact permission set `createPackage` plus npm's provider-imposed
+  `createStagedPackage`, and keep the staged-package inventory exactly empty.
+  Once trusted publishing is proven, disallow traditional token publication
+  for the package.
+
 ## Establish the production controls once
 
 Apply these controls in order. Record the exact readbacks in the change review.
@@ -59,7 +180,7 @@ for this rollout and do not create a replacement Sites project.
    production authorization. Give the App exactly repository permissions
    `Commit statuses: Read and write` and implicit `Metadata: Read`, with no
    organization permission. Install it on `hraness` with selected-repository
-   access to exactly `hraness/message-like-me`. Record its numeric App ID,
+   access to exactly `hraness/textbutler`. Record its numeric App ID,
    client ID, numeric installation ID, App slug, and the repository's numeric
    ID `1342143606`. These are distinct identities. Read the repository ID from
    GitHub's authenticated repository API and do not substitute a name at the
@@ -107,7 +228,7 @@ for this rollout and do not create a replacement Sites project.
    published Release reports `immutable=true` before npm can run.
 10. Ensure `@hraness/message-like-me` exists publicly under the Hraness npm
    scope, then configure its sole trusted publisher as GitHub Actions repository
-   `hraness/message-like-me`, workflow file `release.yml`. Require its exact
+   `hraness/textbutler`, workflow file `release.yml`. Require its exact
    permission set to be `createPackage` plus npm's provider-imposed
    `createStagedPackage`. The checked Release workflow uses only its reviewed
    direct `npm publish` path, never `npm stage` or `stage publish`, and release
@@ -156,7 +277,7 @@ assertions together:
   `hraness`, exactly `statuses:write` plus `metadata:read`, no `contents` or
   `workflows` authority, and an exhaustive
   `/installation/repositories` set of exactly
-  `{hraness/message-like-me}` with repository ID `1342143606`;
+  `{hraness/textbutler}` with repository ID `1342143606`;
 - `production-ref-writer-key` admits only `main`, has no required reviewers,
   wait timer, or custom deployment-protection rules, disables administrator
   bypass, and exposes only the expected key and checked variables;
@@ -273,7 +394,7 @@ When an established protected ref predates reviewed workflow-control changes:
        mode: process.env.MODE,
        previousSha: process.env.PREVIOUS_SHA,
        protectedRef: process.env.PROTECTED_REF,
-       repository: "hraness/message-like-me",
+       repository: "hraness/textbutler",
        repositoryId: 1342143606,
        tag: process.env.VERIFIED_TAG,
        targetSha: process.env.TARGET_SHA,
@@ -322,7 +443,7 @@ When an established protected ref predates reviewed workflow-control changes:
    treat that target's `.github/workflows` tree OID as the baseline for the next
    routine range. Re-read the permanent App's exact `statuses:write` plus
    `metadata:read` permissions, absence of `contents` and `workflows` authority,
-   singleton `{hraness/message-like-me}` repository selection, and the terminal
+   singleton `{hraness/textbutler}` repository selection, and the terminal
    non-success status. A completed epoch requires no key rotation because it
    created or replaced no credential and every short-lived App token was revoked;
    an interrupted run still follows the separate quarantine and cleanup
@@ -629,7 +750,7 @@ missed slot is skipped rather than retried or shifted, and request, body, and
 sleep latency all consume the same window. App identity, installation, mint,
 DELETE, and observation bodies are streamed under a 1 MiB cap and scrubbed
 after parsing. Every HTTP 200 must still describe the exact singleton selected
-`hraness/message-like-me` repository with ID `1342143606`. Acceptance requires
+`hraness/textbutler` repository with ID `1342143606`. Acceptance requires
 two distinct scheduled HTTP 401 authorization-denial reads. An HTTP 403 is
 indeterminate because GitHub can use it for rate limiting or policy denial; it
 never proves revocation. A 200 after either denial, only one denial, any other

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/architecture.md

@@ -0,0 +1,154 @@
+# 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.
+
+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
+  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]
+  Tools --> Memory[One contact workspace]
+  Tools --> Web[Public web broker]
+  Tools --> Intents[Proposed actions]
+  Intents --> Butler
+  Butler --> Transport[Versioned transport adapter]
+  Transport --> Ghostget[Ghostget]
+  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 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 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 temporary live launchd install/start/uninstall test passed while preserving synthetic owner data. The CLI companion is the supported release path; desktop app packaging has been removed; the CLI companion is the only local runtime surface.
+
+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.
+
+## Contact data
+
+The intended application-support tree is:
+
+```text
+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
+    runs.sqlite                private run and send journal
+    daemon-custody.sqlite      exclusive process/socket ownership
+    launch-agent-custody.sqlite lifecycle serialization
+    launch-agent.json          exact LaunchAgent installation receipt
+    ghostget-automation-custody.json exact supervised messaging process claim
+  plugins/
+    extensions.json            explicit owner-installed hook manifest
+    quiet-hours.ts             example trusted executable extension
+  contacts/
+    <opaque-contact-id>/       the only model-visible workspace for one run
+      AGENTS.md                editable response guidance; never authority
+      ABOUT.md                 relationship context and owner instructions
+      MEMORY.md                concise, dated, source-attributed working notes
+      STYLE.md                 owner-style evidence and response preferences
+      history/                 bounded, attributed conversation excerpts
+      notes/                   task-specific notes and outstanding questions
+      attachments/             broker-admitted incoming files
+      outbox/                  files proposed for this conversation
+```
+
+Directory names use opaque identifiers, not contact names or phone numbers. Files are private to the Mac user. Models cannot traverse parent paths, links, other contact folders, or host configuration. The file broker supports reads, conditional writes, and exact edits. It exposes no symlink, directory, delete-tree, shell, or executable permission operations. Atomic replacement preserves the preceding file if a write fails. A stale memory revision produces a conflict instead of overwriting an owner's correction.
+
+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 menu companion.
+
+## Reply admission
+
+Default contact mode is smart, but a new contact starts disabled. Activating more than the configured limit fails atomically; no existing contact is displaced. The initial limit is five, with owner settings from one to fifty.
+
+An inbound event must identify one activated direct conversation. Historical, outgoing, butler-authored, unknown-author, group, reaction-only, and delivery events do not start reply runs. Persisted event identity prevents a duplicate send. One run may own a contact at a time.
+
+The daemon waits eight seconds after an incoming message to collect a burst. Newer messages supersede older candidates. Owner typing suppresses a reply when that signal exists. Any recent owner message causes a five-minute cooldown. The runtime checks current messages and settings again after composition. Disabling a contact or pressing global pause cancels pending runs and invalidates their grants.
+
+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.
+
+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.
+
+## Send transaction and disclosure
+
+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 }`.
+
+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.
+
+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
+
+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.
+
+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 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.
+
+## Agentrouter
+
+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.
+
+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.
+
+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).
+
+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.
+
+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.
+
+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.
+
+## 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.
+
+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.
+
+Text and file sending use the native helper's AppleScript path. The upstream rich-action bridge injects into Messages and requires SIP to be disabled. Textbutler and Ghostget never change that security setting or install the injection automatically. Rich actions therefore remain unavailable unless the required bridge is already working. This is a significant installation constraint, not a completed rich-messaging experience on a stock Mac.
+
+Ghostget 0.18.2 includes the admitted imsg `0.14.1+private-transport.3` helper. Automated rich links use `send.rich` with `fetch_metadata: false`, constructing the URL and host-title card without helper metadata or image fetching. Availability still requires current managed permission and a compatible native bridge; this does not claim network isolation for Messages itself. The host never falls back to fetching an agent-provided URL.
+
+The [Ghostget integration contract](ghostget-contract.md) documents the implemented binding, grant, event, action and receipt semantics.
+
+The Textbutler transport supports capability negotiation, conversations, bounded history, cursor-based events, exact preparation, authorization and receipts. File paths become admitted bytes before crossing the boundary. Per-action permission and context checks stop a rich batch when conversation activity changes. Private database access stays inside Ghostget's provider implementation.
+
+Linq's documented iMessage API includes attachments, reactions, stickers, rich links, App Clips, and experiences. App cards and rich links are standalone messages. Those hosted capabilities do not establish availability through native macOS Messages. Optional Linq would be a separate transport with explicit account setup, sender identity, webhook signature verification, replay protection, and the same Textbutler policy gates. It is not a way to silently route an owner's personal conversation through a different phone number.
+
+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.
+
+## macOS menu companion
+
+The supported local surface is an unbundled status-item companion launched by the CLI. It exposes daemon state, contact and account readiness, capabilities, recent activity, pause/resume and status refresh. The website action opens the informational textbutler.app page. Contact enrollment, account setup and other settings remain daemon protocol capabilities without a current menu or web interface. 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 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. 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
+
+- [Codex App Server](https://learn.chatgpt.com/docs/app-server): programmatic threads, turns, tool requests, account operations, and sandbox configuration.
+- [Codex security](https://learn.chatgpt.com/docs/security): sandbox and approval boundaries.
+- [Claude Agent SDK permissions](https://platform.claude.com/docs/en/agent-sdk/permissions): tool permission controls.
+- [Linq messages](https://docs.linqapp.com/channel/imessage/api/resources/chats/subresources/messages/): transport-specific rich message behavior.
+- [Linq reactions](https://docs.linqapp.com/channel/imessage/api/resources/messages/methods/add_reaction/): emoji and sticker reactions.

package/docs/textbutler/ghostget-contract.md

@@ -0,0 +1,88 @@
+# Ghostget integration contract
+
+Textbutler owns reply policy and contact memory. Ghostget owns messaging
+accounts, native permissions, synchronization, event storage and outward
+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.
+
+## Owner process
+
+The private protocol is `ghostget.messaging-automation/1`. Every bounded JSON
+request has an ID, method and parameters; every response repeats its protocol
+and ID and carries either a checked result or a typed error. Initialization
+selects up to two explicit accounts, one per network, through stdin. Contact
+memory and model tools cannot configure that process or invoke its control API.
+
+Textbutler records process custody before launch, bounds its streams and queue,
+and removes custody only after a successful close response and verified clean
+process exit. Cancellation and revocation can interrupt an active submission.
+A malformed response, crash or uncertain cleanup retains the recovery fence.
+Restarting Textbutler does not silently clear it.
+
+## Contacts, events and grants
+
+| Surface | Implemented contract |
+| --- | --- |
+| `status`, `start` | Observe capabilities; explicitly start supported synchronization. |
+| `conversations`, `enroll`, `enrollments` | Exact account generation and direct participant-bound conversation enrollment. |
+| `poll`, `history`, `events` | Bounded history, durable observation cursors, revisions, catch-up and gap detection. |
+| `grant`, `grant.get`, `grant.by-intent`, `revoke` | Recipient, action, expiry and quota limits; idempotent issuance lookup and immediate revocation. |
+| `asset`, `prepare` | Admit exact attachment bytes and bind the ordered action list to a context revision and expiry. |
+| `submit`, `cancel`, `run` | Journal an action claim before dispatch and retain accepted, failed, partial or indeterminate results. |
+| `close` | Wait for owned provider cleanup before acknowledging shutdown. |
+
+Enrollment records contain the provider account incarnation, source generation,
+implementation identity, exact conversation coordinate and participants. Display
+titles are labels, not authority. Account or participant replacement invalidates
+the binding. Existing Textbutler version 1 read bindings remain readable;
+automation requires explicit version 2 enrollment.
+
+Ghostget's managed permissions must explicitly allow each requested operation.
+A broad capability advertisement does not create a grant. Textbutler activation
+issues a bounded grant only after checking the selected agent account and
+conversation. It renews standing enabled-contact grants within their limits,
+and persists grant intent before issuance so a lost response can be resolved
+without blindly creating another grant. Disabled and uncommitted grants are
+reconciled through revocation.
+
+Startup, re-enablement and recovery drain old events silently. An unresolved gap
+pauses automation. Textbutler waits for a new eligible inbound event and applies
+debounce, owner cooldown, classification and rate limits. Ghostget rechecks
+identity, permission, context and grant before dispatch, and observes intervening
+conversation changes between actions. Neither component retries an uncertain
+send automatically.
+
+## Rich actions
+
+Attachments, reactions, stickers, rich links and native polls are separate
+capabilities. They become available only when the installed provider, current
+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
+when a preceding action fails or the conversation changes. An accepted receipt
+does not claim delivery.
+
+Native iMessage exposes text and files through the pinned helper and its
+currently usable rich methods for six standard tapbacks, stickers, links and
+polls. Rich methods require the owner's separately configured native bridge.
+App Clips and arbitrary mini-app experiences remain unavailable: no reviewed
+native executor exists. Linq's hosted APIs are a design reference and cannot
+silently substitute another sender for the owner's personal conversation.
+
+## Verification boundary
+
+The source tests cover account changes, cursor restart and gaps, grant revocation
+and lost responses, exact byte admission, ordered actions, cancellation and
+uncertain results using synthetic accounts. They do not establish live provider
+delivery. A bounded live acceptance test needs explicit account, recipient and
+message authorization and must record the exact provider/runtime versions.
+See [WhatsApp](whatsapp.md) and [the architecture](architecture.md).