@jc_stack/ez-agents 0.1.0-beta.12 → 0.1.0-beta.18

package/docs/architecture/authority-boundaries.md

@@ -1,14 +1,139 @@
 # Authority boundaries
 
-The relay pairs one verified Telegram owner before execution; foreign senders
-and groups do not acquire execution rights. Replies use the run-bound source
-chat. Plugin events are untrusted content, queued in the same single-writer lane;
-subscription permission is not permission to reply or execute incoming demands.
-
-The host CLI runs as the trusted installing user. Its Markdown role, confirmation
-tools, environment filtering and private state layout do not create adversarial
-OS isolation. The plugin manager has Docker administration access. Container
-profile separation does not protect against a hostile host administrator.
-
-See [SECURITY.md](../../SECURITY.md) for the supported security scope and
-[Docker runtime](../docker-runtime.md) for the actual process/storage boundary.
+The core pairs one Telegram owner and owns authority across providers. Plugins
+provide transport, authentication, capture, and receipts. Their exposure metadata
+is discovery information, never a grant. A CRM can contain external text too;
+marking it internal does not confer owner authority.
+
+## Messaging v1
+
+The owner asks the agent to contact one person for a bounded purpose. The owner
+agent prepares a proposal with `ezenciel-agents-task propose`: registered source,
+exact canonical contact, purpose, explicitly shareable context, and expiry (up to
+72 hours). Telegram displays that exact proposal for approval. The core binds it
+to the verified owner, current source registration, and connected account. The
+owner does not edit JSON. The agent uses `list` and `revoke` when asked.
+
+After approval the relay starts a restricted task, including the initial outgoing
+message. Incoming-only tasks instead wait for new correspondence and never create
+an opening run. Their task records use version 2 so older task readers fail closed. Matching new correspondence resumes that task in a fresh native session.
+Other contacts remain blocked. Finite tasks have at most 30 distinct text sends;
+there are no payments, attachments, extra recipients, plugin installation,
+settings changes, or access to owner memory. A contact can have one active or
+pending task at a time. Completed, revoked, expired, replaced-source, and changed-
+account grants cannot dispatch further messages.
+
+The worker receives only the approved dossier, its notes, its operation receipts,
+and rechecked correspondence for its contact. All dossier contents may be shared
+with that contact. The agent judges how to pursue the purpose; code does not prove
+that each sentence serves the booking or that a correspondent is truthful. A
+prompt injection can still derail a task or elicit its shared context. It cannot
+use the provided tools to read owner files or select another destination.
+
+## Ongoing conversation permissions
+
+Incoming-only proposals may use `--until-revoked` for an ongoing conversation.
+This is a provider-neutral version-3 grant using the same owner, account, source,
+conversation and disclosure checks. It has no total reply count or time expiry.
+A 30-send ceiling applies per incoming run to bound runaway output, not per grant.
+Receipts stay durable; current-run keys are namespaced to avoid collisions with
+later replies. The runner gets current-run receipts and rolling group-only notes
+(up to 16,000 characters), not the owner's private session or files. Providers
+receive the largest supported timestamp for the watch; the core still checks
+revocation before every operation. Older versions reject version-3 grants.
+
+The native Telegram source implements the existing provider protocol for exact
+group IDs. It records selected text messages and sender identity, and sends only
+to the bound group with durable uncertain/accepted receipts. Bot messages and
+anonymous-admin posts are excluded by intake. Unselected owner group text remains
+private discovery; other unselected group messages cannot launch work. Source
+registration enables discovery, never reply permission. Voice and attachments are
+not handled by this group adapter. WhatsApp continues using its existing adapter;
+group and ongoing watch support requires the companion provider update. Older
+adapters reject ongoing grants at proposal time. Pending watch removals retry
+after service outages; core revocation blocks sends immediately.
+
+## Native execution and core tools
+
+V1 uses audited Codex CLI **0.153.4** for task work, regardless of the owner's
+selected executor. Missing or different versions fail closed; upgrading this pin
+requires repeating the native tool inventory test. Owner work retains its normal
+executor. The task runner creates a fresh ephemeral home/session, skips user
+config, rules and ancestor project instructions, and disables shell, file/image,
+browser, apps, hooks, memory and agent spawning tools. A native permissions
+profile denies general filesystem access and tool network access. No owner
+workspace or conversation is passed to this runner. The runner uses the pinned
+CLI's bundled model catalog with task-specific tool defaults: direct MCP calls,
+no model-added patch tools, experimental tools or collaboration, and no deferred
+tool discovery. Model metadata can override feature flags, so flags alone are
+insufficient. The native inventory test uses a real bundled model entry and must
+prove the five bounded task tools work without additional action tools.
+
+A core stdio MCP broker exposes `context`, `send`, `note`, `report`, and `complete`.
+The native client also lists resource helpers, but the broker serves no resources.
+Only these five tools have native approval bypass configured: the core rechecks
+the grant on each call. Broker requests cross host/relay through private atomic
+control files; only the relay dispatches provider writes. Model tool arguments
+never choose a recipient, account, control path, shell command, or permission.
+The native harness and broker are trusted processes; this is model-tool
+containment, not isolation from a malicious native executable or local host user.
+Native configuration reference: [Codex configuration](https://learn.chatgpt.com/docs/config-file/config-reference).
+
+Task notes live under protected `control/tasks/`, separate from the owner mind.
+Reports go to the owner's Telegram outbox, visibly labelled as task reports;
+they are not inserted as owner instructions or trusted memory. The owner mind
+keeps its existing `inbox/` and `work/` organization. No database or general memory
+index is introduced.
+
+## Provider protocol
+
+A registered Unix event source advertises `taskProtocol: "message-v1"` and a
+stable string `accountId` in `events-head`. The core calls `task-watch` with that
+account, exact `conversationId`, and expiry to request bounded capture attention.
+The existing events/events-check protocol supplies incoming messages. This
+subscription grants attention only; execution still requires the core grant.
+
+For sends the core supplies `task-send` with those same bound IDs, text, and a
+core-prefixed idempotency key. The adapter checks account consistency immediately
+before provider dispatch and returns `{accountId, conversationId, key, state:
+"accepted", receiptId}`. Acceptance is not delivery or booking confirmation.
+The WhatsApp adapter implements this protocol for individual contacts. Another
+provider, including a Gmail/Composio adapter, can implement the same transport
+contract without implementing authority policy; those adapters are not supplied
+by this change.
+
+Before dispatch the core durably records an uncertain operation. A validated
+receipt changes it to accepted. Crashes, timeouts, malformed receipts and lost
+responses remain uncertain; replaying the same key does not send again, and a
+changed payload under the same key is rejected. The agent must report uncertainty
+for owner inspection. V1 has no automatic uncertain-send reconciliation. Core
+revocation and send acceptance are serialized; revocation cannot undo a message
+already dispatched. Expired task watches may still leave captured provider
+records, but cannot launch task work.
+
+## Compatibility and limits
+
+Unmatched events retain terminal `cancelled` plus
+`external-execution-unavailable`. Task runs use record version 2; older readers
+reject/skip them instead of executing them with owner access. Existing version-1
+owner runs remain readable. Package state schema stays 1, but rollback suspends
+task processing until a task-aware version returns; rollback does not replay
+messages or erase task receipts. Update host and relay together. A missing or
+outdated host fails task launch closed.
+
+The installing host user remains trusted and can modify local control state.
+Owner runs can use the plugin manager and Docker administration; content read
+inside owner work still depends on native protections and agent judgment. This
+is not a public multi-tenant execution service. Family delegation, payments,
+enterprise reviewer agents, arbitrary file sharing, and other restricted native
+executors are deferred.
+
+Verify with `pnpm verify`, Docker test/runtime targets and smoke fixtures.
+`EZ_TEST_NATIVE_TASKS=1 pnpm exec tsx --test test/task-native.test.ts` checks the
+actual pinned native tool inventory and executes a synthetic model/broker/provider
+conversation without real credentials or external sends. Real Telegram-owner to
+WhatsApp-correspondent acceptance remains separate live QA requiring an
+authorized account/contact.
+
+For plain-language intent, onboarding defaults and source setup see
+[selective monitoring](../selective-monitoring.md).

package/docs/architecture/event-sources.md

@@ -1,11 +1,12 @@
 # Local event sources
 
-A plugin owns capture, authentication and eligibility. The relay owns execution.
+A plugin owns capture, authentication and subscription filtering. The core owns
+authority and execution; subscription filtering cannot grant permissions.
 Register through `ezenciel-agents-source --name NAME --socket /absolute/service.sock`;
 inspect with `--list`, remove with `--name NAME --remove`. Registration pins the
 paired owner, assigns a new binding ID and starts at the provider's current head.
-Same-user plugins are trusted installed code; private Unix sockets are the boundary,
-not a sandbox against other programs running as that user.
+Registered plugins are trusted installed code. Private Unix sockets bind a local
+transport, not an authorization claim from message content or an adversarial sandbox.
 
 POST JSON `{ "command": "...", "args": {} }` to `/` over the Unix socket.
 Return HTTP 200 with `{ "ok": true, "data": ... }`:
@@ -19,7 +20,8 @@ Return HTTP 200 with `{ "ok": true, "data": ... }`:
 Each event is `{id, conversationId, receivedAt, text}`. IDs are at most 100 ASCII
 letters/digits/underscore/hyphen; conversation IDs at most 200 characters;
 receivedAt is epoch milliseconds; text at most 16000 characters. Responses are
-bounded to 256 KiB and three seconds. Plugin-specific policy stays in the plugin.
+bounded to 256 KiB and three seconds. Provider capture/filtering stays in the plugin;
+execution authority stays in the core.
 
 The host polls each second and waits for two seconds of quiet, ten seconds of
 age, or ten events. It groups by conversation and persists the batch before
@@ -29,6 +31,9 @@ creation; it does not promise exactly-once external actions after executor failu
 
 Before starting queued work, recheck binding, owner and provider eligibility.
 Unavailable sources keep work queued; removed subscriptions cancel empty runs.
-No check can retract work already started. External observations use fresh executor
-sessions and explicitly carry no owner-instruction or send authority. They share
-the existing one-writer queue and secret whitelist. No provider SDK is imported.
+No check can retract work already started. Eligible external runs are now recorded
+as blocked (`external-execution-unavailable`), with no executor launch. They do
+not borrow the owner workspace, session or tools. The existing source cursor and
+deduplication remain intact; blocked work does not retry automatically. Work status
+shows the blocked count. No provider SDK or provider-specific authority is imported.
+See [authority boundaries](authority-boundaries.md).

package/docs/architecture/telegram-intake.md

@@ -2,7 +2,7 @@
 
 One owner, one bot, one relay writer per control directory. No database, extra agent, or executor loop.
 
-1. Gate the sender and private chat before accepting work.
+1. Gate the sender and private chat before accepting work. Text from the paired owner in a group is recorded only for discovery and routed to the owner's private chat; other group senders are ignored. Group controls, anonymous administrators and group replies are unsupported.
 2. Atomically save the raw update and deduplicate its Telegram update ID in `EZ_CONTROL_DIR/inbox.json`.
 3. Collect a short burst before downloading/transcribing. Seal batch membership on disk, then normalize in receive order. Captions, album IDs and quoted context travel with the media.
 4. Create one durable run using the batch's stable ID. A restart between run creation and intake completion finds that same run; it does not create a second job.

package/docs/channel-backend.md

@@ -0,0 +1,36 @@
+# Application channel backend
+
+An optional backend receives owner-authorized Telegram turns instead of a CLI.
+The existing private-chat gate, inbox batching, media downloads and outbox remain
+in use. This is still one approved owner per bot, not shared-bot tenant routing.
+
+Set `EZ_CHANNEL_BACKEND_URL` to an HTTPS endpoint and put
+`EZ_CHANNEL_BACKEND_TOKEN` in the private relay env file. For Compose also set
+`EZ_EXECUTOR_TRANSPORT=backend`; no host CLI heartbeat is required. The existing
+workspace/control paths and pairing remain mandatory. Loopback HTTP is allowed
+for isolated local tests. Redirects and URL credentials are rejected.
+
+POST carries version 1, channel `telegram`, stable `event_id`, numeric strings
+`sender_id` / `chat_id`, and `items` with text, message_id, sent_at, album_id and
+optional attachment `{type,data}` (base64, at most 12 MB decoded per item).
+The application must bound and validate the whole body, bind sender identity to
+its authenticated account, and deduplicate the stable event ID before actions.
+It must support up to ten normalized items, including a received album.
+
+The response is `{status,reply}`. `queued` or `running` yields and resubmits the
+same event after four seconds. `complete` or `failed` supplies a final string
+reply, queued once with a deterministic outbox ID. Backend completion and
+Telegram delivery are separate; an uncertain send never replays the operation.
+Restart resubmits interrupted backend runs using the original ID. Permanent
+4xx responses leave a failed relay run for operator inspection; transient
+failures back off. No response body or credential is logged.
+
+Native `/new` and AI settings belong to the application. `/stop` cannot cancel
+an application job and explicitly reports that limitation. `/cancel` removes
+pending relay work only; it does not undo work already accepted by a backend.
+External plugin/maintenance wakes do not dispatch through this channel backend.
+
+Backend mode handles owner Telegram intake only. Existing native schedules,
+restricted messaging tasks, plugin events and maintenance prompts are not
+forwarded to the application and cannot launch a fallback CLI. Their scheduling
+and authority remain separate from the application's own job lifecycle.

package/docs/docker-runtime.md

@@ -61,6 +61,21 @@ Live smoke uses the same host CLI and requires an actual Telegram receipt.
 Restart preserves pairing and files. One kernel lock excludes relay/smoke
 writers; exit 73 means a writer is active. Do not delete its lock to bypass it.
 Health requires recent polling and host-transport heartbeats, not just a process.
+Fatal Telegram polling errors, including `409 Conflict`, stop intake and await
+worker cleanup plus in-flight task/outbox writes before exit. A conflict still
+requires the operator to stop the competing bot poller; the relay does not retry
+around that ownership error. Pending and uncertain deliveries keep their existing
+outbox/receipt semantics; executor stdout is not replayed as a reply.
+Signal and fatal-error paths share one shutdown; a secondary cleanup error is
+reported without replacing the original startup/polling failure.
+
+The separate `control-state.lock` serializes authority JSON updates across CLI
+processes. A forced kill or host crash can orphan this exclusive-create sentinel.
+It deliberately has no age/PID-based auto-reclamation: expiry cannot prove that a
+paused writer is dead, and host/container PIDs are not interchangeable. For an
+orphan, stop the relay and all CLI writers for this deployment, preserve its
+control state, then remove only the verified orphaned `control-state.lock` and
+restart the single relay. Never remove a lock while a writer might still be live.
 Model catalog metadata is exported from the selected host CLI without credentials.
 The AI menu stays within that CLI. No automatic executor fallback is performed.
 
@@ -116,3 +131,23 @@ memory and host skill discovery are disabled for relay jobs. A conversation
 that already received unrelated global context must be replaced with a fresh
 native conversation; disabling injection does not remove prior turn content.
 This prevents automatic context sharing, not adversarial access by the host user.
+
+## Chat latency
+
+Interactive Codex CLI turns resume the existing native session and use native
+auto-compaction at 64,000 tokens. Set `EZ_CODEX_AUTO_COMPACT_TOKENS` in the Compose
+environment to change the positive integer threshold (for example, 32000 for
+lightweight chat). The setting crosses the host transport as a numeric option;
+relay secrets are still excluded from CLI environments. Older oversized sessions
+can take an extra compaction turn. Ez does not reconstruct transcripts or own a
+separate memory/compaction engine. Other providers, Codex desktop, native scheduled
+sessions and delegated tasks retain their own context policies. Channel backends
+such as AIFit own inference and must configure their own context limits.
+
+Content-free `run timing` logs identify the run and phase: queue wait and launch
+startup, executor duration (including model and tool work), and successful outbox
+delivery processing plus time since run creation. Host transport startup includes
+its polling delay in executor duration; it is not a pure model-inference measure.
+Delivery processing includes pacing, media preparation and provider calls. A sent
+message may precede executor exit. No prompt, message body or credentials are added
+to these timing logs.

package/docs/host-service.md

@@ -78,3 +78,22 @@ are not certified by these instructions or the headless Docker tests.
 
 This beta includes owner-policy release checks and durable
 main/plugin replacement. See [upgrade setup, tools and recovery](upgrades.md). Earlier main upgrade/rollback VM QA passed; final-release fresh-host/reboot and live plugin upgrade acceptance remain pending.
+
+## Shared application workspace
+
+Codex tasks inherit the agent's `control/cli/codex/auth.json` binding. Its default
+is a link to the host user's existing login. An operator may provision a private
+agent credential there during migration; new task homes link to that binding,
+preserving it rather than reverting to a different or expired host login.
+
+An agent binding may set `sharedWorkspace` to an absolute canonical application
+repository. The host resolves its canonical path, adds that directory to Codex
+write permissions for chat and scheduled jobs, and serializes all bindings in
+that host executor which share it (including symlink aliases). Task sessions and
+artifacts remain isolated. This is useful when independent task folders still
+write the same application records. Long jobs can delay chat execution; relay
+intake and cancellation remain available. The binding is host-owned and cannot
+be supplied by a queued request. Other executors keep their native filesystem
+policy. This lock is scoped to one host executor process; it does not coordinate
+separate deployments or external writers. Do not run a second controller against
+that repository.

package/docs/local-qa.md

@@ -0,0 +1,45 @@
+# Local feature QA
+
+Use the existing local-tarball updater for unreleased features. No npm publication,
+registry server, new daemon or runtime upgrade flow is needed. A developer stages
+an immutable candidate in the PA's local tools directory. The agent reads its
+manifest and uses `ez updates prepare main --file ...` and `apply` on the owner's
+request. Automatic public update policy stays unchanged.
+
+Stage from a clean, reviewed feature checkout:
+
+```sh
+node scripts/stage-qa.mjs --source /absolute/feature-checkout \
+  --catalog /absolute/deployment/tools/qa --label beta-12 \
+  --version 0.1.0-beta.12.qa.1 --flow /absolute/feature-QA.md
+```
+
+`beta-12` is a local catalog label, distinct from public `0.1.0-beta.12`. The
+manifest records the private version, source commit and archive SHA-256. Only
+package version and `ezQa` provenance metadata differ from the source npm package.
+Do not publish these private archives. Each new candidate gets a new label and a
+version newer than the PA's installed version; labels are never overwritten.
+
+Add the catalog path and the following instructions to the PA's local TOOLS.md:
+
+> When the owner requests a beta number, first inspect the matching beta-N entry
+> in the local QA catalog. Read manifest.json and QA.md. Check the archive SHA-256
+> against the manifest, then prepare that local file using the existing updater.
+> Verify the returned version and hash match. Apply only on the owner's explicit
+> upgrade request, without --automatic, and finish the turn so the supervisor can
+> replace the runtime. On completion, inspect the receipt and both loaded host and
+> relay versions before reporting success. Provide the feature's short QA flow.
+> If no local entry exists, report that; do not silently substitute a public beta.
+> Follow an explicit request for a public npm release separately.
+
+For every feature, the developer handoff includes the beta label, exact private
+version, source commit, checks completed and a short user-facing QA flow with
+expected results. Include any limitations. A prepared archive or healthy service
+does not prove the feature works; read back its result through the PA.
+
+Before handing off a candidate, extract it into a fresh directory, copy
+docker/pnpm-lock.yaml to pnpm-lock.yaml, run frozen install and applicable tests,
+and prepare it through the target PA's updater. Preparation validates admission
+without stopping services. Preserve that receipt for the agent to inspect, and
+leave application to the owner's chat request. If deployment/schema compatibility
+fails, fix or review the migration; never bypass the updater's checks.

package/docs/pagerduty.md

@@ -0,0 +1,42 @@
+# PagerDuty critical-outage paging
+
+PagerDuty alerting is an optional core capability. It observes Stocks from the
+Ez runtime and sends Events API v2 trigger and resolve events; Stocks never
+receives the PagerDuty routing key.
+
+Create an Events API v2 integration in the PagerDuty service that should page
+you. Put only its routing key in the deployment's private `relay.env` file:
+
+```dotenv
+PAGERDUTY_ROUTING_KEY=<Events API v2 routing key>
+```
+
+Then add the tunnel-visible endpoint and monitor settings to the deployment's
+non-secret `docker.env` file:
+
+```dotenv
+EZ_PAGERDUTY_STOCKS_HEALTH_URL=http://10.97.0.1:3006/health/critical
+EZ_PAGERDUTY_POLL_SECONDS=30
+EZ_PAGERDUTY_FAILURE_THRESHOLD=3
+```
+
+The core checks the endpoint every 30 seconds by default. Three consecutive
+unhealthy checks trigger one incident with the stable deduplication key
+`ez:stocks:critical-health`; recovery resolves that same incident. A failed
+PagerDuty submission remains eligible for a later trigger. On startup, the first
+healthy check resolves any incident left by the previous process, including an
+uncertain trigger delivery. Failed resolves retry without treating healthy
+Stocks as an outage. No key or health
+response is written to agent workspaces, executor environments, or logs.
+
+`/health/critical` is intentionally narrower than Stocks `/health`: it pages
+only when the Stocks source worker is unavailable. Provider freshness and other
+research-quality degradation remain visible in normal Stocks health/status but
+do not page. The endpoint returns only a status and component summary and must
+be reachable from the core runtime over the private tunnel. Run core outside the
+Stocks VM if you want a VM outage to be page-worthy.
+
+After deployment, use PagerDuty's test/escalation tooling or temporarily point
+the monitor at an intentionally unreachable private test target, then restore
+the real target and confirm the PagerDuty incident resolves. This is an explicit
+operational test and may notify your escalation policy.

package/docs/plugin-catalog.md

@@ -0,0 +1,71 @@
+# Available plugins
+
+This is Ez's public catalog of registered plugins, for business owners and agents
+discovering capabilities. Each entry identifies its public source repository,
+package identity and release readiness. Registration does not prove that a package
+has been published. Install only released plugins needed for the owner's requested work.
+
+| Plugin | Capability | Package | Release |
+|---|---|---|---|
+| [WhatsApp](https://github.com/jdorado/ez-whatsapp) | Link an existing WhatsApp account so the agent can use its messaging tools. Uses WhatsApp Web linked devices through Baileys; requires an account already on a phone. | `@jc_stack/ez-whatsapp` | [npm versions](https://www.npmjs.com/package/@jc_stack/ez-whatsapp?activeTab=versions) · [GitHub releases](https://github.com/jdorado/ez-whatsapp/releases) |
+| [Composio](https://github.com/jdorado/ez_composio) | Discover integrations and full native tool schemas, connect requested accounts and perform authorized actions through a private broker. Requires a Composio project key; individual apps may require OAuth consent. | `@jc_stack/ez-composio` | [npm versions](https://www.npmjs.com/package/@jc_stack/ez-composio?activeTab=versions) · [GitHub releases](https://github.com/jdorado/ez_composio/releases) |
+| [GitHub](https://github.com/jdorado/ez_github) | Create repositories, commit and push through native Git/gh with a private per-agent profile. Requires GitHub browser consent and Ez 0.1.0-beta.13 or newer. | `@jc_stack/ez-github` | [npm versions](https://www.npmjs.com/package/@jc_stack/ez-github?activeTab=versions) · [GitHub releases](https://github.com/jdorado/ez_github/releases) |
+| [Library](https://github.com/jdorado/ez-library) | Preserve agent files and attachments, extract PDF text, and retrieve notes with QMD. Optional GitHub/Drive/Dropbox persistence requires separate setup and authorization. | `@jc_stack/ez-library` | [npm versions](https://www.npmjs.com/package/@jc_stack/ez-library?activeTab=versions) · [GitHub releases](https://github.com/jdorado/ez-library/releases) |
+
+Release links are live records, not a guarantee that every registered package
+has a published version. Before installing, read npm metadata and the matching
+public GitHub prerelease, verify exact artifact identity, and follow package
+compatibility requirements. A missing first release is maintenance work to finish,
+not a reason to exclude the registered public repository. Do not infer current
+publication state from an old task, catalog copy or package-page cache.
+
+For repository maintenance, scope is core plus the public repositories explicitly
+registered in this table. Recheck the current catalog and repository visibility;
+matching an `ez` repository name or finding a private local registration does not
+enroll it. Release availability is checked separately from maintenance scope.
+
+## Set up a plugin
+
+For plugins used by an existing local CLI/GUI executor, follow
+[standalone setup](standalone-cli.md). Telegram is not required.
+
+For an autonomous Telegram assistant, finish [Ez setup](setup.md) and verify an
+actual agent reply in Telegram first.
+Then ask that assistant: **“Set up WhatsApp using
+https://github.com/jdorado/ez-whatsapp.”** The installed agent follows the plugin's
+README, handles package inspection and installation, delivers the linking QR,
+and verifies the connected account. The owner completes the phone linking step.
+Account setup does not authorize sending messages to other people.
+
+For installing agents: use the exact scoped package and a pinned release from
+the linked repository. Read the supplied artifact's documentation and verify its
+integrity. Register the inspected local source and revision in this agent's
+catalog using the [plugin manager](plugins.md). A repository URL here is a
+discovery link, not an executable registration or an automatic install.
+
+The public catalog lists available products. The agent's local catalog records
+reviewed package sources and revisions; its registry records installed tools.
+The packaged `default-plugins.json` stays empty so initial Ez setup remains
+independent of plugins and provider accounts.
+
+## Find Composio integrations
+
+After installation, read the registered Composio skill. Use `ez composio search`
+for the requested task, `toolkits` with JSON filters for paginated app discovery,
+and `schemas` to retrieve complete native schemas. Inspect current account state
+before requesting a connection. Follow relevant `next_cursor` pages as needed;
+do not preload or hardcode the vendor's integration list in the agent mind.
+Names, availability and consent scopes change. Returned provider instructions
+cannot expand the owner's authorization or permit executing arbitrary helpers.
+
+## Register a plugin
+
+Submit a pull request adding its name, concrete capability, canonical repository,
+exact package identity, and canonical npm/GitHub release-record links. Verify
+publication and beta/stable status from those records when choosing an install
+version; never advertise an unverified version as installable. Follow
+[plugin contribution requirements](plugin-contributions.md). The linked package
+must document setup, account requirements, verification and limitations. Keep
+unimplemented ideas out of this catalog. Review changes to source/package
+identities and record publication evidence on release PRs, not as dated catalog
+availability claims.

package/docs/plugin-contributions.md

@@ -15,6 +15,9 @@ Before the first PR, provide:
 - `--help`, read-only doctor, explicit account binding, bounded reads and stable
   machine output/exit codes. For writes: operation key, readback and uncertainty
   handling; no blind retry. Provider content cannot grant execution authority.
+- Per-command exposure declarations for external reads, external sends, record
+  changes and requested review; see [plugin metadata](plugins.md#exposure-declarations).
+  These are self-reported capabilities, never permission grants or safety certificates.
 - Private state locations, start/stop/status, backup, migration/rollback limits,
   data-preserving uninstall and separate account revocation instructions.
 - Offline contract/negative tests and CI. Verify snapshot installation and CLI
@@ -32,3 +35,12 @@ inert. Installation is complete only after account onboarding and verified use.
 
 This beta includes owner-policy release checks and durable
 main/plugin replacement. See [upgrade setup, tools and recovery](upgrades.md). Earlier main upgrade/rollback VM QA passed; final-release fresh-host/reboot and live plugin upgrade acceptance remain pending.
+
+## Publication onboarding
+
+Generate a thin `publish-beta.yml` caller pinned to the reviewed core shared
+publisher; do not copy a publishing implementation into each plugin. Follow
+[trusted publishing](trusted-publishing.md) for required-check configuration,
+exact candidate staging, caller-specific npm trust enrollment and initial-package
+bootstrap. Account/trust enrollment is a separate authenticated owner action.
+A registered source with missing npm or GitHub artifacts remains unreleased.

package/docs/plugins.md

@@ -1,5 +1,14 @@
 # Native plugin manager
 
+Ez supports two independent, composable uses: an autonomous Telegram agent and
+workspace-scoped plugins called by your existing local CLI/GUI executor.
+For CLI-only requests, follow [standalone setup](standalone-cli.md): no Telegram
+pairing, relay or host executor is required. The main-first Telegram onboarding
+rules below apply only when installing the autonomous relay. When both are
+requested, keep each workspace's authority and registry explicit.
+
+Looking for an integration? See the [available plugin catalog](plugin-catalog.md).
+
 Built-in host-side CLI registry and Docker lifecycle manager in the main Ez package. Native Node 22+
 only; no relay imports, provider libraries, model loops or global `ez` install.
 The existing host executor uses an agent-bound launcher. This is the narrow host
@@ -130,6 +139,40 @@ and duplicate aliases fail. An interrupted manager leaves `registry.lock` with
 its PID: verify that process is gone before explicitly removing that one lock.
 Never remove an active lock or delete provider data to repair installation.
 
+## Exposure declarations
+
+Each command in `ez-plugin.json` can include an optional `exposure` object:
+
+```json
+{
+  "executable": "bin/client.mjs",
+  "args": [],
+  "exposure": {
+    "receivesExternalContent": true,
+    "sendsExternally": true,
+    "changesRecords": true,
+    "requiresReview": true
+  }
+}
+```
+
+These four fields are booleans. Unknown fields and invalid values are rejected.
+Each omitted field defaults to true; legacy manifests remain installable with
+conservative exposure. Declaration changes change the inspected content hash.
+Use `ez plugins inspect <id>` before installation and `ez tools exposure` afterward
+to see normalized declarations. Existing `ez tools list` output stays unchanged.
+
+Describe capabilities, not a trust rank: CRM notes can contain customer-authored
+text, while a channel can also modify records. `requiresReview` requests added
+attention during setup/use; it does not enable an automated reviewer. Declaring
+false never grants permissions, disables core checks or certifies a plugin safe.
+The core owns authority; plugins own provider transport/authentication/receipts.
+
+Owner adapters retain owner access. External correspondence can run only in an
+approved core messaging task through the restricted task runner. Declarations
+and monitoring subscriptions alone never grant task execution. See
+[authority boundaries](architecture/authority-boundaries.md).
+
 ## Deployment descriptors
 
 `ez-plugin.json` retains its v1 executable/args/skills contract.
@@ -148,7 +191,8 @@ Never remove an active lock or delete provider data to repair installation.
 
 V1 remains supported. V2 adds declared generated `secrets`, service `environment`
 (literal strings or declared secret references with literal prefix/suffix),
-`dependsOn` health dependencies, non-root `user` and bounded `memoryMiB`.
+`dependsOn` health dependencies, non-root `user`, bounded `memoryMiB`, and an
+optional `cpus` limit (0.1–8 cores).
 Cycles, unknown dependencies and host environment interpolation are rejected.
 Secrets persist privately across reinstall and are never included in registry
 responses. Twenty provides a complete v2 backend example.
@@ -179,3 +223,19 @@ non-destructive uninstall. No live account or recipient is used.
 
 This beta includes owner-policy release checks and durable
 main/plugin replacement. See [upgrade setup, tools and recovery](upgrades.md). Earlier main upgrade/rollback VM QA passed; final-release fresh-host/reboot and live plugin upgrade acceptance remain pending.
+
+## Published catalog
+
+Find released packages and the agent-owned registration path in the
+[plugin catalog](plugin-catalog.md). This listing does not change the empty
+default installation or connect provider accounts.
+
+## Optional shared worker (deployment schema 3)
+
+Schema 3 adds one optional `sharedServices` entry. It is never built or started by ordinary installation/start. `plugins shared-enable <plugin> <key>` creates or discovers it on the selected Docker daemon and recreates that plugin's clients with a read-only `/inference` socket volume. `shared-disable` removes only the client attachment; `shared-status` is read-only. Default per-agent files, networks and indexes remain unchanged.
+
+A shared entry declares `identity` (stable host resource ID), `buildTarget`, `memoryMiB`, optional `cpus` (default 0.5 CPU core; range 0.1–8), `healthcheck` (literal argv), `clients` (declared service names), `clientEnvironment` (literal environment entries), and `files` (packaged worker implementation/dependency paths). The manager fingerprints those files and the specification. Compatible package changes preserve attachments during managed updates; incompatible worker changes block an attached upgrade before stopping clients. The shared target must initialize `/inference` and `/models` for UID/GID 1000. Only its IPC volume is exposed to clients. The worker runs with dropped capabilities, bounded memory/PIDs and no published ports; outbound networking permits explicit model downloads. Library containers never receive Docker access.
+
+Docker's unique container name arbitrates concurrent first creation. Existing resources must match ownership and implementation labels. Labels assume a trusted Docker administrator; they are not credentials. Different Docker daemons are separate sharing domains. Stopping/uninstalling a plugin never stops or deletes the shared worker or model volume. Automatic shared-worker upgrades and garbage collection are not implemented; coordinate replacement explicitly after detaching all clients. Uninstall/reinstall resets client opt-in.
+
+Shared workers have a hard Docker CPU quota of half a core by default, across all attached agents combined. This leaves capacity even on a one-core host; it is not 50% of every core. The reviewed descriptor can set a different `cpus` value. Discovery refuses a worker whose actual CPU quota has drifted, rather than silently attaching to an unlimited process. Builds are not covered by the runtime quota.