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

package/docs/releasing.md

@@ -3,7 +3,9 @@
 Use the same checks for maintainer and external changes. Each repository versions
 independently with SemVer: patch for compatible fixes, minor for new capabilities;
 before 1.0, breaking CLI/state changes require a minor bump and migration notes.
-No automatic dependency updates, release bot or credentials in pull-request CI.
+No automatic dependency updates or credentials in pull-request CI. The agent
+operates this process under the authorization rules in CONTRIBUTING.md; a
+separate release bot is not required.
 
 1. In an isolated release worktree/PR, finalize package version and CHANGELOG.md;
    update plugin manifest version when present. After lockfile changes, copy
@@ -32,14 +34,20 @@ No automatic dependency updates, release bot or credentials in pull-request CI.
    fill package.json repository, homepage and bugs with the actual public URLs.
    Enable GitHub private vulnerability reporting; verify the route. Protect main
    with CI and independent PR review. Maintainers use the same process.
-7. Record independent review and green CI for the final release PR, then obtain
-   maintainer merge/release authorization for the exact commit, tarball SHA-256,
-   license/third-party obligations and known limits. Merge the release PR and
+7. Record independent review and green CI for the final release PR. The
+   maintainer's release request supplies authorization: do not ask for a second
+   approval. Record the prepared commit, tarball SHA-256, third-party obligations
+   and known limits. If release is outside the request, report readiness without
+   publishing. For an authorized release, merge the release PR and
    verify its tree matches the reviewed source before tagging `v<version>` and
    publishing that tarball:
-   `npm publish /absolute/candidate.tgz --access public --tag beta --registry https://registry.npmjs.org/`
-   for prereleases (use `--tag latest` only for an approved stable release).
-   Use interactive npm authentication with 2FA; never paste tokens into CI or docs.
+   `npm publish /absolute/candidate.tgz --access public --tag latest --registry https://registry.npmjs.org/`
+   for approved beta releases as well: `latest` is the default distribution tag,
+   not a claim that a SemVer prerelease is stable.
+   For unattended beta publication use the [shared trusted publisher](trusted-publishing.md)
+   and its exact-artifact staging/readback contract. Initial package publication
+   requires authenticated npm with 2FA before trust can be enrolled; never paste
+   tokens into CI or docs.
 8. Create the GitHub release from CHANGELOG.md, attach artifact/checksum, and
    install the registry version on a clean host. Verify metadata and the same
    onboarding path before posting launch copy. Stop rollout on failure; publish
@@ -53,13 +61,16 @@ credential revocation; do not delete volumes as a routine rollback.
 ## Beta channel
 
 Use SemVer prereleases (`0.1.0-beta.1`), GitHub's prerelease flag and npm's
-`--tag beta`; never mark a beta latest/stable. For this first beta the maintainer
+`--tag latest` so default installs and the package page advance automatically.
+The version and GitHub release remain prereleases; stable-only update policies
+still exclude them. The legacy npm beta tag is no longer advanced. For this first beta the maintainer
 explicitly deferred real account/reboot acceptance. Keep that limitation in the
 README and release notes. Source/tarball publication is permitted after the
 automated gates; deferred live checks remain required for stable release.
 GitHub repositories use `jdorado`; npm packages use `jc_stack`. Verify
 `npm whoami --registry https://registry.npmjs.org/` returns `jc_stack` before
-publishing. Never infer npm scope ownership from a GitHub login. After publishing,
+interactive publication. OIDC publication instead requires package-owner trust
+enrollment for the exact caller workflow; `whoami` is not its publication gate. Never infer npm scope ownership from a GitHub login. After publishing,
 read back `npm view @jc_stack/ez-agents@0.1.0-beta.12 name version dist-tags --json`
 (using the release being published), download it with `npm pack`, and verify its
 contents/checksum against the reviewed artifact. Keep the npm artifact and

package/docs/repair.md

@@ -0,0 +1,41 @@
+# Native repair ownership
+
+Every deployed agent is a repairer by default. When an agent finds a core or
+plugin defect, it keeps the context and pursues a tested contribution PR. The
+core injects the same mandate into CLI/native and desktop execution, including
+existing workspaces; it does not replace the agent's mind or implement a repair
+workflow engine. Use native Git/GitHub CLI or the installed GitHub plugin.
+
+The agent searches for the same cause, registers a sanitized issue, requests a
+claim, then works in an isolated contribution checkout after the coordinator's
+grant. It resumes the same issue/branch/PR after interruption. The installed
+runtime is never the repair checkout. Missing credentials or coordination remain
+recorded blockers; the default does not invent repository access. Public reports
+must exclude private runtime data and use the security reporting route when needed.
+
+One coordinator grants claims sequentially per repository. Assignment alone is
+not a lock. All participating agents must use that coordinator; this convention
+cannot prevent an unrelated public contributor from opening a competing PR.
+The discovering agent remains the repairer, including when its work moves to a
+background task. The coordinator reconciles duplicates and stalled claims. The
+maintainer independently reviews and tests, then merges/publishes only within
+separate owner-approved policies. Start from templates/maintainer-purpose.md.
+
+## Disable
+
+Set `EZ_REPAIR_ENABLED=false` in the deployment's Docker environment and recreate
+the relay. The resolved setting crosses the host transport and is included in
+every new execution prompt; the default is true and invalid values fail startup.
+This changes the automatic mandate, not filesystem/GitHub permissions, and does
+not cancel an already running task. Explicitly stop active repair work when needed.
+An owner can also disable repairs globally or for a repository in the agent's
+saved USER.md preferences; carry those restrictions into background task context.
+
+## Setup boundary
+
+The shipped mandate and maintainer purpose do not provision a GitHub account,
+coordinator service or publishing token. Enroll the allowed repositories and
+configure one maintainer execution lane on the owner's host before unattended
+claims. Reuse authenticated GitHub CLI where authorized. Repository push and PR
+permissions are distinct from package-registry publication and protected-branch
+approval. Never put credentials in prompts, issues or test environments.

package/docs/scheduling.md

@@ -0,0 +1,153 @@
+# Scheduling and background work
+
+Ask the agent naturally: “Remind me on September 9 next year at 09:00 Dubai time”
+or “Every Tuesday at 09:00, prepare the report.” The agent translates this into a
+core CLI request. No plugin, database or operating-system cron setup is required.
+
+```sh
+ezenciel-agents-schedule create --name Reminder \
+  --at 2027-09-09T09:00:00+04:00 --text 'Remind the owner about the renewal.'
+ezenciel-agents-schedule create --name Weekdays \
+  --cron '0 9 * * 1-5' --timezone Asia/Dubai --text 'Prepare the daily report.'
+ezenciel-agents-schedule create --name Research --now \
+  --text '/goal Complete the authorized research objective. Save evidence, verify the outcome, and send the owner the result.'
+ezenciel-agents-schedule list
+ezenciel-agents-schedule runs
+ezenciel-agents-schedule pause SCHEDULE_ID
+ezenciel-agents-schedule resume SCHEDULE_ID
+ezenciel-agents-schedule remove SCHEDULE_ID
+ezenciel-agents-schedule cancel RUN_ID
+```
+
+Use `--text-file` for longer instructions. `edit ID` replaces the complete schedule
+with a new revision; use the same trigger/name/text flags as `create`.
+Intervals use `--every-seconds` (minimum 60), optional `--start`, and optional
+`--until`. Cron also supports start/end bounds. All absolute timestamps require
+an explicit offset. `--now` starts on the next relay tick, not synchronously.
+
+Cron accepts five numeric fields, comma lists, ranges and steps; Sunday is 0 or 7.
+Restricted day-of-month and weekday fields use standard OR semantics. Set just
+weekday for “Tuesdays.” Calendar jobs retain their explicit IANA timezone when
+the host changes zones. Nonexistent DST wall times are skipped; repeated wall
+times fire once, at the earlier instant. Search is bounded to eight years.
+Public-holiday calendars and arbitrary RRULE syntax are not implemented.
+
+New tasks, including work deferred by a busy reply session, default to Codex
+`gpt-5.6-terra` with `high` reasoning independently of the creating chat.
+Use `--cli`, `--model`, and `--effort` to specify another choice; reasoning
+explicitly selected above `high` is rejected for every model. Non-Codex adapters
+inherit native effort when unset. Editing preserves the existing AI
+choice unless those flags override it. Stored choices are checked again at
+launch, including schedules saved before the cap.
+
+## Execution and authority
+
+The relay checks due work once per second. Each occurrence enters the durable
+run queue with a stable ID. Background work runs in a fresh native CLI session
+and `work/tasks/RUN_ID/`, with snapshots of the agent's SOUL, USER and TOOLS files.
+Instructions must include any needed context or source paths; full chat history
+is not copied. Task folders remain for inspection and artifact delivery.
+
+One writer runs per task directory. Up to four background tasks can run alongside
+the main conversation. When a Codex owner message arrives while work is busy, a separate restricted session reads recent messages and run progress and answers through the normal outbox. It can queue requested work through the scheduler, but cannot run shell commands, access plugins, or edit the agent workspace. Only one reply session runs at a time and it releases its slot after a 60-second reply deadline; this deadline does not apply to writer jobs. Its context is a bounded snapshot, not a shared native transcript. Delivered parallel replies are included as historical context in the next normal conversation turn. Codex 0.153.4 and 0.154.0 are supported for this restricted adapter. Other versions fail closed pending tool-surface validation. A recurring schedule has at most one pending
+or active occurrence. Agents should delegate long work with `create --now`, return
+to chat, and inspect `runs` or task progress when asked. Native subagents can be
+used inside the worker. Sharing provider profiles does not make concurrent CRM,
+file or browser writes safe: the agent must coordinate those resources.
+
+Production relay/host execution has no wall-clock timeout. The old
+`EZ_EXECUTOR_TIMEOUT_SECONDS` setting is ignored. Individual network/tool waits
+still have their own limits; those are not overall task deadlines. Native goals
+are an executor capability, configured through instructions. Ez has no goal API,
+continuation loop or rule equating a process exit with goal achievement.
+
+Scheduled Codex CLI tasks use a dedicated native app-server session, tested with
+CLI 0.153.4. A leading `/goal` in the instruction text maps to the same native
+goal command used by the interactive CLI. Codex automatically starts subsequent
+turns; the transport stays connected until the native goal is complete or stops
+for attention. It sends no continuation prompts and stores no Ez goal state.
+Goals created by the agent's native tools also keep the session alive. Ordinary
+tasks finish after their turn. A blocked, paused or limited goal is not reported
+as successful. Native RPC requests have a response deadline; running tasks do not.
+Each scheduled task has its own Codex state under `control/cli/codex/tasks/RUN_ID`,
+with a snapshot of the agent's Codex configuration and the existing auth link.
+Foreground chat and background tasks do not initialize or migrate one shared
+native database concurrently.
+
+The foreground chat still uses `codex exec`. That invocation exits after one
+requested turn even if a goal is active, so delegate persistent work to the
+scheduler. Desktop and other executor goal lifecycles need separate validation.
+
+The CLI binds jobs to the paired owner and the task AI choice. Queued/scheduled
+work retains that choice after the chat switches AI. Revoking/re-pairing an
+owner invalidates their old schedules, including re-pairing the same Telegram ID.
+External event turns cannot use the scheduling CLI. Credentials still pass only
+through the existing whitelist and installed host binding.
+
+## Restart, pause and cancellation
+
+Schedule definitions and cursors use protected atomic JSON files. A restart
+between queue creation and cursor persistence does not duplicate an occurrence.
+An overdue one-time job runs on return. Missed recurring occurrences coalesce into
+one pending run; future runs resume at the next eligible time. A paused queued
+occurrence waits for resume. Editing/removing a schedule invalidates its old
+queued occurrence; already-running work continues until explicitly cancelled.
+
+`/stop` stops all active work; `cancel RUN_ID` stops one background task. `/cancel`
+clears queued work. Pause/remove a recurring schedule to prevent future runs.
+Stopping the relay also stops its workers. A crashed or interrupted execution is
+not automatically replayed. Status labels failed runs as history and shows recent reasons; new failures retain their exit code or interruption cause. Typing indicators stop after 30 seconds even when work continues. Runs found active at startup are marked failed with
+`interrupted: true`; their schedule revision stays held until the agent inspects
+the evidence and explicitly edits the schedule. Inspect the task's files, native session and delivery
+receipts before deciding whether to resume. A clock cannot reconstruct an
+in-flight process or prove whether an external side effect happened.
+
+The host and relay must be online. Paused/completed schedule definitions and task
+artifacts are retained. The agent sends through the normal Telegram outbox;
+`completed` means executor exit, while provider delivery is recorded separately.
+A timeout or ambiguous send must not cause blind replay of the whole task.
+
+## QA
+
+`pnpm verify` covers recurrence/DST, restart deduplication, authority revocation,
+corrupt state, paths, cancellation and a chat response while a synthetic worker
+is active. Docker tests exercise the packaged host transport and isolation.
+
+For an opt-in real CLI probe (consumes model usage):
+
+```sh
+pnpm smoke:scheduler -- 1860 codex
+# Native goal must finish a first turn and continue without another prompt:
+pnpm smoke:scheduler -- 45 codex goal
+```
+
+This uses temporary workspaces and a synthetic Telegram provider, never live
+contacts. A real CLI waits 31 minutes while a second invocation answers 17 × 19.
+It checks responsiveness again after six minutes and requires the worker's final
+message. Evidence is saved in the printed temporary directory. Use `75 codex`
+for a shorter iteration; it does not prove the full duration.
+
+Before enabling on a real installation, repeat through its Telegram bot: request
+the 31-minute task, ask the arithmetic question and request status after six
+minutes. Verify `finished.txt` and exactly one completion in Telegram. Separately
+exercise cancellation, downtime catch-up and an explicitly requested native goal
+that needs more than one turn. Synthetic provider evidence does not prove real
+Telegram delivery, and a sleep test does not prove native goal persistence.
+
+Busy-chat regression probe (real Codex, synthetic Telegram):
+
+```sh
+pnpm exec tsx scripts/smoke-busy-reply.ts --transport
+```
+
+The probe holds a writer on a shared workspace, asks an owner question through
+the relay and host transport, and requires the restricted reply to complete
+while the writer remains active. It sends no real Telegram messages.
+
+## Optional failure review
+
+Create a normal recurring schedule with `--every-seconds 900 --when unreviewed-failures --text-file templates/failure-review.md`. The condition advances empty occurrences without launching an executor. It considers only failures belonging to the paired owner. No separate monitor or automatic retry is introduced.
+
+`failures [--all] [--limit N]` returns failedAt, reason, exit code, native session, captured error and runtime versions. Capture keeps at most 4 KiB of redacted stderr; historical failures are not backfilled. `run RUN_ID` reads an owned run. `review RUN_ID --failed-at ISO --status resolved|attention --diagnosis TEXT --recovery TEXT --outcome TEXT` records the investigation without rewriting execution history. A stale timestamp is rejected; a later failure needs a new review. Restricted reply, external and isolated-task callers cannot review failures. An attention review is handed off, not repeatedly relaunched; another new failure wakes the next review.
+
+The prompt controls diagnosis, authorized recovery and quiet notification behavior. Inspect prior effects and receipts before retrying anything. A failed review run itself remains visible as a new failure for the next occurrence.

package/docs/selective-monitoring.md

@@ -0,0 +1,114 @@
+# Selective monitoring and replies
+
+An owner saying “monitor and answer messages from CONTACT” has selected that
+contact and authorized ordinary replies within the stated scope. Do not ask
+whether they meant selected contacts or demand a special phrase. “If they send,
+reply” means wait for incoming messages; it does not authorize an opening send.
+Resolve only missing identity or disclosure scope. A saved Markdown instruction
+is a reminder, never an activated source, watch or reply permission.
+
+## Speak in jobs, not modes
+
+Keep mode names internal. Linking/syncing an account defaults to quiet capture;
+finish connection verification, then at most one short optional prompt such as
+“WhatsApp is connected. Want me to follow up with anyone?” Do not present a
+technical three-mode menu or suggest blanket autonomous replies that v1 cannot
+safely authorize. If the owner already gave a job, continue it without this prompt.
+
+Infer the complete job from ordinary language:
+
+- “Find out whether they have a table” or “Book me a restaurant”: send the inquiry,
+  watch replies from that contact, continue the multi-turn negotiation and report
+  the outcome. A send receipt is not completion. Do not ask if follow-up is wanted.
+- Twelve inquiries mean twelve task-scoped contacts, not all-inbox monitoring.
+  Maintain one scoped task per correspondent; the same core checks apply to each.
+- “Just send this; I will reply”: one-off send under the explicit owner instruction,
+  no new watch or conversational mandate. Use the provider's ordinary send and
+  receipt interface; do not create a messaging task that would auto-follow up.
+- “Monitor this person and answer if they message”: incoming-only reply task;
+  no opening message and no unrelated contact attention.
+- “Keep these messages for me”: quiet capture/read-on-request. If “monitor” alone
+  leaves action intent unclear, ask one plain question: “Should I reply for you,
+  or just keep the messages for you to review?” Do not ask when the job resolves it.
+
+Apply the required core confirmation to the concrete proposal, not an extra
+questionnaire. Use the owner's existing contact, purpose and disclosure limits.
+For an ongoing incoming-only conversation, use `--until-revoked`; finite tasks remain bounded. Explain the expiry only
+when it matters to that proposed job; never silently expand or renew permission.
+
+## Three capture modes, separate reply authority
+
+- Manual: capture for explicit reads, with no general wake-up subscription.
+- Selected: wake for named contacts only. Never turn on all-inbox mode to satisfy
+  a one-contact request.
+- All: attention for all eligible incoming contacts; requires that broader
+  owner request. Attention alone never grants autonomous reply permission.
+
+For an approved core reply task, the provider's task-watch supplies expiring
+selected attention even if its general policy remains manual. That is expected:
+verify the actual task watch and core grant, not only the general policy label.
+Monitoring-only requests grant no sends. Unsupported wake-only reasoning modes
+must be reported as unsupported, not run with owner authority.
+
+## Complete the setup under the owner's request
+
+Use the current installed plugin skill and `ez plugins list`/`status`/provider
+doctor to confirm the existing linked account. Installation, source plumbing,
+contact attention and permission are separate checks. A missing source is
+technical work for the agent, not a reason to stop at “saved your instruction.”
+Do not request a second provider instance or re-pair an already linked account.
+
+The relay must be able to reach the registered provider service socket. Inspect
+the registered deployment/compose, actual named IPC volume, and relay mounts.
+For the supplied WhatsApp adapter the socket is /plugins/whatsapp/service.sock;
+main compose.whatsapp.yaml supplies a read-only IPC/client override. Use the
+registered plugin's real volume names, preserve existing docker.env/Compose
+settings, and attach only its declared IPC/client volumes (never its profile or
+credentials). Recreate the relay with the existing deployment after a required
+mount change; verify it comes back. Do not expose the Docker socket to it.
+
+Register the source INSIDE that relay container using the installed
+`ezenciel-agents-source --name NAME --socket ABSOLUTE_SOCKET` command. Read back
+registration and provider events-head account identity. A socket inside a
+provider command container is not proof the relay can reach it. Do not edit core
+source/grant JSON directly. Other adapters use their declared socket paths;
+provider names do not change authority checks.
+
+## Propose, confirm, verify
+
+For an outbound job such as a booking, use `ezenciel-agents-task propose` WITHOUT
+`--incoming-only`: it starts the inquiry and then watches replies. For “answer if
+they message,” use `ezenciel-agents-task propose --incoming-only` with the
+registered source, canonical contact, purpose, explicitly shareable context file
+and expiry. No need to invent a booking objective: “conversational replies to
+this contact, no private disclosures or commitments” is a legitimate purpose.
+If no private facts may be shared, say so in the context file; do not include
+owner memory. Finite jobs support at most 72 hours. For an ongoing conversation requested by
+the owner, add `--incoming-only --until-revoked`. This authorizes that exact
+conversation until owner revocation, without a total reply quota. Do not silently
+convert a finite job into an ongoing permission.
+
+For Telegram groups, the relay registers source `telegram` automatically when
+paired. Use the exact negative group ID from discovery, never its display name.
+Keep the shared context limited to what every group member may know. All human
+members of that approved group may converse; this does not grant owner tools.
+The group runs with the existing restricted messaging runner, and its notes are
+separate from private PA memory. Group text is supported; media is not yet.
+
+The core presents the exact proposal for owner confirmation. Ordinary messages
+inside that grant need no repeated confirmations. Incoming-only grants create
+no initial run or opening message. They remain active across replies until expiry
+or owner revocation; the worker cannot close a watch by calling `complete`.
+After handling a message, save a task note and finish the run. After approval, verify active core state,
+contact and expiry, source reachability, and the provider's task watch. With
+`--incoming-only`, an empty conversation is correctly idle until a new message.
+If approval is still pending, say pending; if setup failed, name the actual
+failure and continue repair within scope. Never report “active” based on notes,
+installation, connected status or subscription alone.
+
+After an authorized test message, inspect the corresponding task run and send
+receipt and compare recipient readback. An accepted send is not proof of delivery.
+After revocation/expiry no subsequent reply may dispatch. Keep these checks
+agent-owned: the owner supplies only necessary confirmation, QR scan if needed,
+and the test contact/message. Do not bypass a missing grant by polling the inbox
+in an unrestricted scheduled owner session or sending through the raw CLI.

package/docs/setup.md

@@ -1,5 +1,34 @@
 # Agent-led setup
 
+## A group as owner
+
+An installer can explicitly approve one Telegram group as the agent's owner.
+Every human member in that group then has owner access, including settings,
+approvals and scheduling. The conversation and replies are shared in that group.
+New members inherit this access. Bots and anonymous sender-chat posts are ignored.
+
+Add the bot to the intended group and send it a message addressed to its username.
+`ezenciel-agents-owner status` shows the pending group title and negative chat ID;
+verify the exact group with the installer, then run
+`ezenciel-agents-owner approve-group <negative-chat-id>`. Pairing never happens
+automatically. The existing `approve <user-id>` command approves DMs only.
+An existing owner must be explicitly revoked before replacement; use a fresh
+deployment when its existing workspace contains information unsuitable for the group.
+
+Make the bot a group admin so Telegram delivers ordinary member messages and
+allows membership verification for approval and control buttons. Group ownership only authorizes
+the exact approved chat, not other groups or members' private DMs. Telegram group
+migration to a new chat ID requires a new explicit binding. Verify a real group
+reply before considering setup complete. All other groups retain their existing
+restricted conversation-grant behavior.
+
+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.
+
 The user starts in their existing CLI and says “install Ezenciel”, then “create
 an agent as my family shopper”. The installing agent does the technical work.
 Keep that host CLI and login for every agent; do not request another CLI login.
@@ -23,6 +52,23 @@ owner request for standalone plugin development is a separate workflow.
 
 ## Defaults and host prerequisites
 
+New agents using `codex` or `codex-gui` start with `gpt-5.6-terra` and `high`
+reasoning, including when initialized with `ezenciel-agents-setup init`. This
+Ez default takes precedence over discovered host client defaults. Saved agent
+selections at or below high are preserved; use the AI settings to choose another model or effort.
+Ez rejects explicit reasoning above `high` for every model at selection and execution,
+including old saved or queued choices. Unset Codex model/effort resolves to
+Terra/high at launch. This governs Ez-managed launches; it is not an account-wide
+limit on independently launched native clients or executor-created native subagents.
+Other adapters inherit their native effort when none is selected in Ez. That
+inherited configuration is not capped by Ez; explicit above-high Ez selections
+are still rejected. Only Codex adapters receive the default `high` effort.
+
+New scheduled and one-off background tasks default to Codex Terra/high independently
+of the creating chat. Use scheduler `--cli`, `--model`, and `--effort` flags for
+explicit overrides. Editing a schedule preserves its settings unless overridden.
+Restricted messaging tasks also use Terra/high when no settings are supplied.
+
 Use the existing owner's host account. Unless a layout was supplied, use
 `${XDG_DATA_HOME:-$HOME/.local/share}/ez/packages/<version>/` for extracted main
 packages and `${XDG_DATA_HOME:-$HOME/.local/share}/ez/agents/` for private deployments.

package/docs/standalone-cli.md

@@ -0,0 +1,62 @@
+# Use Ez from your existing executor
+
+The plugin manager and its Docker plugins work independently of the Telegram
+relay. Use the same absolute launcher from any local executor to share a chosen
+workspace's tools and accounts. The executor owns reasoning and conversation;
+Ez owns the plugin registry and command transport. No provider-specific adapter,
+new model login or GUI plugin installation is involved.
+
+## Setup
+
+Install the main package and its dependencies in a permanent location using the
+artifact steps in [setup](setup.md). Node 22+ is needed for the manager; Docker
+and Compose are needed for executable plugins. Do not build/start the relay,
+create a bot, pair an owner or configure a host executor for CLI-only use.
+Create a private tools directory and select the existing company/project workspace:
+
+```sh
+node /absolute/package/bin/ezenciel-agents-tools.mjs init --standalone \
+  --home /absolute/private/company-tools --workspace /absolute/company-workspace
+/absolute/private/company-tools/bin/ez --help
+/absolute/private/company-tools/bin/ez status
+/absolute/private/company-tools/bin/ez plugins list
+```
+
+Init starts nothing, uses an empty catalog by default, preserves existing
+TOOLS.md notes and appends the registry's discovery instructions. A registry
+cannot be replaced by rerunning init. Keep the package at its original path:
+the launcher imports it. Status reports `main: null` without a relay binding;
+automated software upgrades currently require a relay deployment.
+
+Have each executor read the workspace's TOOLS.md and the installed plugin skills.
+Add that instruction to its existing project instructions without replacing them.
+Use the absolute launcher, or prepend its bin directory to that session's PATH.
+Never overwrite another global `ez`; it may belong to a different installation.
+A company registry remains explicit even when invoked from a different directory.
+Other projects/accounts should use separate registries and private plugin state.
+
+## Install and verify a capability
+
+The current conversation owns authorized plugin onboarding. Follow the
+[plugin contract](plugins.md#installation-completion-contract), using the bound
+launcher for `plugins inspect <id> --source /absolute/package`, then
+`plugins install <id> --source /absolute/package --revision <inspected-hash>`.
+Read the skill, start the plugin, complete its provider authentication and verify
+the intended account with a supported operation. Deliver any necessary consent
+link or QR in the current client. No Telegram handoff is required.
+
+Run `tools list`, the registered alias's help and a harmless account operation
+from each actual executor. Host-shell access alone does not prove a sandboxed
+session can access Docker or the registry. Client permissions still apply.
+Native client plugins/connectors are not converted into Ez plugins automatically.
+
+## Combine with an autonomous agent
+
+A relay can coexist with CLI-only registries on the same machine. It retains its
+own pairing, single-writer queue, mind and plugin registry. Calling its existing
+bound launcher explicitly reuses that registry and its accounts; never initialize
+over it or silently select it from another workspace. Coordinate writes with its
+active jobs. Separate registries do not automatically share credentials or data.
+
+Continuous monitoring requires a configured event consumer/relay and the plugin's
+supported watcher. CLI-only installation does not create background agent turns.

package/docs/trusted-publishing.md

@@ -0,0 +1,140 @@
+# Verified beta publication
+
+The Mac prepares and independently tests the release. GitHub-hosted Actions
+publishes the exact approved tarball using npm OIDC. The shared implementation
+is `.github/workflows/npm-beta-shared.yml` in this repository; each package has a
+small manually dispatched `publish-beta.yml` caller. This setup does not grant
+release authority or establish npm trust automatically.
+
+## Enroll a repository once
+
+1. Verify the source is public and explicitly registered in the current
+   [public catalog](plugin-catalog.md), or is core itself. Registration does not
+   prove a registry release exists. Excluded or private repositories cannot use
+   this publisher.
+2. Review and merge the shared publisher first. Generate the caller using its
+   full immutable commit SHA and the repository's required CI check names:
+
+   ```sh
+   node scripts/generate-publish-caller.mjs jdorado/ez-whatsapp \
+     @jc_stack/ez-whatsapp FULL_SHARED_COMMIT_SHA \
+     '["test (ubuntu-latest, 22)","test (ubuntu-latest, 24)","test (macos-latest, 22)","test (macos-latest, 24)","docker"]' > publish-beta.yml
+   ```
+
+   Put that file in the plugin's `.github/workflows/` through its own reviewed
+   PR. Inspect the actual CI names; the example does not establish the policy.
+   Keep the reusable workflow reference and `publisher-sha` on the same reviewed
+   commit. Core uses a local reusable workflow at the dispatch commit. The
+   generator writes stdout only; it never grants repository scope or edits npm.
+3. The npm package owner authenticates separately and enrolls the exact caller
+   repository and filename `publish-beta.yml` as a trusted publisher. Enable
+   **direct publication** explicitly; new trust configurations can default to
+   staged publication only. If an environment is configured on npm, add that
+   exact environment to the shared publishing job through review before use.
+   This workflow currently uses no environment.
+4. Verify enrollment through npm settings or `npm trust list PACKAGE`. npm
+   validates the **calling** workflow for reusable workflows. Both caller and
+   publishing job need `id-token: write`; test/validation jobs do not receive it. GitHub requires `contents: write`
+   to read unpublished draft assets: only the validation job receives that
+   capability and makes GET requests only. The separate OIDC job has
+   `contents: read`. No package code or lifecycle scripts run in validation.
+   Do not add `NODE_AUTH_TOKEN`, npm tokens, or private profiles to these jobs.
+
+An npm package must already exist before trust enrollment. If a registered
+plugin has no registry package, the owner must perform a real, approved initial
+beta publication using authenticated npm, with all release checks and exact
+artifact readback. Then enroll trust. Do not create a dummy release to test
+login. A missing GitHub release likewise remains missing until actually created
+and read back; a catalog link or workflow PR is not publication evidence.
+
+Current npm requirements and enrollment fields are documented in
+[npm trusted publishers](https://docs.npmjs.com/trusted-publishers/) and
+[npm trust](https://docs.npmjs.com/cli/v11/commands/npm-trust/).
+The workflow uses Node 24 and npm 11.19.1 on GitHub-hosted Ubuntu runners.
+
+## Prepare and dispatch one beta
+
+Follow [releasing](releasing.md), including isolated Mac tests, packed artifact
+inspection, independent review, required CI and authorized merge. The source
+must be the exact current `main` commit; after a merge, verify that its tree
+matches the tested source and renew invalidated evidence. Wait for that commit's
+CI from `.github/workflows/ci.yml`, triggered by a push on `main`. The caller's reviewed list of required checks is a fail-closed minimum;
+update it when repository policy adds checks. The validator selects the newest
+main-push CI run for that source before checking success, then requires the named
+jobs from its latest attempt. Tag, PR and other workflow runs cannot shadow it;
+failed, pending or incomplete main CI cannot fall back to an older success.
+
+Create the `vVERSION` tag at that exact source commit and a **draft prerelease**
+with these assets, using native `gh release create --draft --prerelease` and
+`gh release upload` under existing release authority:
+
+- `candidate.tgz`: the exact Mac-tested bytes from `npm pack --ignore-scripts`.
+  Do not rebuild it on Actions.
+- `release-receipt.json`: a sanitized record with this shape:
+
+  ```json
+  {
+    "repository": "jdorado/ez-agents",
+    "package": "@jc_stack/ez-agents",
+    "version": "0.1.0-beta.14",
+    "sourceSha": "FULL_TESTED_MAIN_COMMIT_SHA",
+    "sha256": "SHA256_OF_CANDIDATE_TGZ",
+    "independentReviewUrl": "https://github.com/jdorado/ez-agents/pull/PR_NUMBER#issuecomment-ID",
+    "testEvidenceUrls": ["https://github.com/jdorado/ez-agents/actions/runs/RUN_ID"]
+  }
+  ```
+
+The maintainer verifies those evidence links substantiate independent final-diff
+review, artifact tests and accepted beta limitations before dispatch. The receipt
+binds that attestation to the commit and digest; a syntactically valid URL alone
+cannot prove review quality or release authority.
+
+Read the draft's numeric `id` with `gh api repos/OWNER/REPO/releases` (the
+release-by-tag API only returns published releases). Dispatch `publish-beta.yml`
+on `main` with `release-id`, `version`, `source-sha` and
+`artifact-sha256`. Copy the digest from the independently verified Mac receipt,
+not an unreviewed replacement release asset. The validator checks current public
+scope, source/tag identity, required GitHub Actions checks, receipt identity,
+package metadata and tarball hash. It transfers the validated bytes using an
+immutable Actions artifact ID. A fresh job revalidates before publication and
+runs npm from a clean directory without package lifecycle scripts.
+
+Only `X.Y.Z-beta.N` versions are supported. Publish to npm `latest` so the
+package page and default installs show the newest approved release. Manifests
+must use `publishConfig.tag: "latest"` (or omit the tag). The version remains a
+SemVer prerelease and the GitHub release remains a prerelease. Private
+packages, wrong package/repository identities and stable versions fail before
+publication. No npm login smoke publication or stable-version release occurs.
+
+## Readback, failure and release completion
+
+The publisher reads registry metadata, checks that `latest` identifies the released version and downloads the
+published tarball to compare its SHA-256. Preserve the workflow's readback receipt, run URL and source/artifact
+identity on the release PR. A failed command after the publish call may mean npm
+accepted it: inspect registry state first. A rerun may verify an existing exact
+version; if the version is absent it refuses a second write. Reconcile first,
+then create a fresh authorized dispatch if appropriate. Never repeat or overwrite that version or silently repair tags.
+Missing trust or registry access is an external dependency, not a reason to use
+a token workaround.
+
+After successful registry readback, finish the GitHub prerelease with the tested
+artifact/checksum and verify its public availability. Perform the clean-host
+installation and runtime/provider checks required by the package's release
+rules. Actions success proves registry delivery only; it does not prove a
+running agent was upgraded. Respect each installation's saved update policy.
+
+## Migration from the legacy beta tag
+
+Existing plugin callers are SHA-pinned: regenerate each caller against the merged
+shared-publisher revision and update its package publishConfig together through
+review. Old pins retain the old behavior. Do not mutate an already staged or
+published artifact; prepare a new version when package metadata changes.
+
+The publisher uses one native npm publish operation with OIDC and `--tag latest`.
+It does not synchronize the legacy `beta` tag: npm trusted publishing does not
+support standalone dist-tag changes. No extra registry token is needed. Ez beta
+update discovery considers both latest and legacy beta during migration; stable-only
+policies select non-deprecated stable versions and cannot automatically install a
+prerelease. Older installed updaters still following only beta require an explicit
+exact-version update to a core release containing this discovery change. Existing
+registry versions/tags are not changed by merging the publisher.