@jc_stack/ez-agents 0.1.0-beta.12

package/docs/plugins.md

@@ -0,0 +1,181 @@
+# Native plugin manager
+
+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
+administrative tool, not another executable provider plugin or Docker daemon.
+
+## Initial agent installation
+
+The installing agent provisions this once. Use explicit absolute paths:
+
+```sh
+node /absolute/ezenciel_agents/bin/ezenciel-agents-tools.mjs init \
+  --home /private/agent/tools --workspace /private/agent/mind \
+  --host-config /private/agent/host-executor.json
+```
+
+Without `--catalog`, init loads an empty packaged catalog. Keep it empty for
+initial main onboarding; no sibling repository, broker or provider account is
+needed. Finish owner pairing and verify an actual Telegram agent reply first.
+Init creates a private registry and `tools/bin/ez`, adds a
+TOOLS.md discovery entry, and binds the matching host executor to that bin
+folder. Native binaries are linked through; an existing `ez` collision fails.
+Run before starting the host executor. For an already running installation,
+place a symlink to the returned launcher in that agent's existing private bin
+directory and set that binding's `toolsHome` to the absolute registry directory.
+Restart the host executor between jobs so it loads the binding. Init with
+`--host-config` sets `toolsHome` automatically. Never overwrite global ez.
+
+The host validates that `toolsHome` belongs to the bound workspace. For Codex,
+it adds that registry to writable roots and enables network access for Docker.
+Docker Buildx metadata uses `toolsHome/buildx` through `BUILDX_CONFIG`, so builds
+do not need write access to the host's shared Docker configuration.
+The GUI adapter also sets `sandboxPolicy.networkAccess` when `toolsHome` is
+bound, on both new and resumed turns; omitting it blocks Docker socket access.
+Verify status and a harmless plugin command inside the actual executor turn.
+Host-shell success alone does not establish worker access.
+Job requests cannot override this host binding. Filesystem access remains
+`workspace-write`; other agents' directories are not added. Docker access is
+host administration under the existing trusted-host model, not OS isolation.
+
+## Installation completion contract
+
+For initial Ez onboarding, plugin requests happen in the working Telegram
+conversation after the main owner exchange is verified. The original host CLI
+must not perform plugin setup instead. The installed agent inspects the supplied
+tarball/checksum, extracts it inside its writable tools directory, and uses
+`ez plugins inspect <id> --source <path>` and `catalog-add` with the returned hash.
+It then handles install/start and QR onboarding in that same conversation. A
+plugin tarball supplied with the main artifact is deferred input, not permission
+to skip the main-first handoff.
+
+When the user says install or set up a plugin, the agent owns completion through
+usable capability, unless the user explicitly requests package files only.
+Inspect the package, read its skill, install, start, complete provider onboarding,
+and verify the intended identity and a real supported operation. Reuse existing
+working connections. Registration, container health and setup artifacts alone
+are not completion. Low-level install/start/connect commands remain separate;
+the agent invokes them within the original request without repeated permission.
+
+Use the agent's known identity and authorized context. Choose routine technical
+labels, generate credentials into plugin-owned private storage, and select
+permissions appropriate to the requested capability. Ask only for genuinely
+missing inputs or actions requiring the human or external provider, such as a QR
+scan, OAuth consent, verification code, or access to an existing account. Do all
+technical setup yourself, including administrative setup for the owner. When an
+API key is required, ask the owner to provide it with the exact provider link and
+location; handle storage privately and never echo it. Do not assume a separate
+administrator exists or hand the owner internal configuration terminology. Do all
+independent preparation first. Deliver the actual image or exact authorization
+link privately with one concrete action; never hand the user CLI setup chores.
+Keep setup pending, resume after that step, and verify the provider result.
+Reuse the original installation authority; do not invent identity or expand it
+to purchases, unrelated accounts, outbound messages or destructive changes.
+
+Each plugin skill must explain required inputs, which can come from agent
+context or be generated, private credential handling, external handoffs,
+resumption/recovery and evidence of readiness. Record non-secret connection
+and maintenance details for future turns. The generic manager remains plumbing;
+provider setup decisions and conversation belong to the agent.
+
+## From the agent conversation
+
+```sh
+ez plugins available
+ez plugins inspect whatsapp
+ez plugins install whatsapp
+ez plugins start whatsapp
+ez tools list
+ez whatsapp doctor --json
+```
+
+The agent reads the installed WhatsApp skill and guides its QR onboarding. Fetch
+the declared QR into the bound workspace with:
+
+```sh
+ez plugins export whatsapp qr --output /private/agent/mind/work/pairing.png
+```
+
+The output file must not exist and its parent must already exist. Deliver it
+through the agent's existing messaging tool, then delete that temporary private
+image. Never publish the profile. `doctor` must confirm the intended identity.
+The manager does not send messages, link accounts, or implement onboarding flows.
+
+Other commands: `plugins list`, `status <id>`, `logs <id>` (last 100 lines),
+`stop <id>`, `uninstall <id>`. Uninstall stops/removes only that Compose deployment
+and unregisters its aliases; it retains named data volumes and reviewed source
+snapshots. Reinstallation reuses that data. Plain install does not replace a different release. Use `ez updates` for
+compatible upgrades under saved policy; see [upgrades](upgrades.md). Manual
+uninstall/reinstall remains available but does not promise schema rollback.
+
+For another reviewed local package, inspect with `plugins inspect <id> --source
+/absolute/source`, then install with that source and the returned `--revision
+sha256:...`. Changed contents fail. To make a reviewed package discoverable without installing,
+use `ez plugins catalog-add <id> --source /absolute/source --revision sha256:...`.
+Inspection is read-only: its returned revision does not replace the saved catalog
+pin. After reviewing changed source, pass the returned `--source` and `--revision`
+to `catalog-add` to update that entry, then install. Alternatively, pass them
+directly to install for that invocation. Do not retry a plain install against a
+stale catalog pin. A mismatch after passing the inspected revision means the
+source changed again; finish edits and inspect the stable source before pinning.
+Catalog updates preserve other entries. No remote package marketplace or arbitrary
+package-manager proxy is implemented.
+
+Installation snapshots only `package.json.files` plus required manifests and
+Docker inputs, validates the descriptor, builds/pulls, then atomically registers.
+It does not start services. Repeated installs report existing state; interrupted
+builds can reuse a matching snapshot. Unknown fields, symlinks, reserved aliases
+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.
+
+## Deployment descriptors
+
+`ez-plugin.json` retains its v1 executable/args/skills contract.
+`ez-deployment.json` is a separate strict descriptor:
+
+- `schemaVersion: 1`.
+- `services`: named services, each with exactly one `buildTarget` (from the
+  snapshotted Dockerfile) or digest-pinned `image`; a nonempty `healthcheck` argv;
+  optional literal `command`, `volumes` mapping named private volumes to container
+  paths, and `workspace: true` for the owning mind mounted read-only.
+- `commands`: the same aliases as the plugin manifest; each names its `service`,
+  executable `argv` and optional literal `suffix`. Dispatch is argv + manifest
+  args + user args + suffix. No parsing or provider parameter translation.
+- Optional `exports`: named artifacts with an exact service and file path.
+  Review these paths: declaring a secret as an export would expose it.
+
+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`.
+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.
+
+Compose JSON is generated, not accepted from untrusted arbitrary Compose input.
+No ports, host network, privileged services, host env inheritance, arbitrary bind mounts,
+Docker socket or raw Compose args can be supplied. Project names include a hash
+of the canonical registry path; networks and volumes inherit that namespace.
+Images use release-specific names. All containers drop capabilities and run as
+UID 1000 by default; v2 can declare another non-root UID:GID. Plugins sharing a profile remain in the same owning deployment.
+
+Commands run in one-shot client containers against their own service's volumes;
+stdin, stdout, stderr, literal arguments and exit codes are preserved. SIGINT/
+SIGTERM cancel the Docker call and remove its unique client container. The manager
+never retries a provider operation. Service startup/restart is explicit; commands
+never implicitly start a stopped provider service. Plugin data does not enter the
+relay. The manager sends only a whitelist of Docker client environment variables.
+
+## Verification
+
+`npm run verify` runs offline negative/contract tests. Explicit Docker integration:
+`node docker/plugin-smoke.mjs`. It builds the actual WhatsApp package with the
+synthetic transport in an isolated snapshot and tests installation, start,
+registered CLI, literal file paths, idempotency, restart persistence and
+non-destructive uninstall. No live account or recipient is used.
+
+## Agent-owned upgrades
+
+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.

package/docs/releasing.md

@@ -0,0 +1,71 @@
+# Releasing
+
+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.
+
+1. In an isolated release worktree/PR, finalize package version and CHANGELOG.md;
+   update plugin manifest version when present. After lockfile changes, copy
+   `pnpm-lock.yaml` to `docker/pnpm-lock.yaml` (npm omits the root lockfile; CI
+   checks this shipping copy is identical). Never overwrite a published version.
+2. Run `pnpm install --frozen-lockfile`, `pnpm verify`, `npm run release:check`,
+   `git diff --check`. Review `npm audit --omit=dev` and dependency licenses.
+   Record accepted risks with a reason; never run an unreviewed audit fix.
+3. Build both Docker targets from a clean checkout:
+   `docker build --target test -t ez-release-tests .` and
+   `docker build --target runtime -t ez-release-runtime .`.
+   Main: `EZ_RELAY_IMAGE=ez-release-runtime node docker/smoke.mjs`.
+   WhatsApp: `EZ_WHATSAPP_IMAGE=ez-release-runtime node docker/smoke.mjs`.
+4. Create an artifact with `npm pack --ignore-scripts`. Inspect its file list,
+   hash it, extract into a fresh directory, copy `docker/pnpm-lock.yaml` to
+   `pnpm-lock.yaml`, and run `pnpm install --frozen-lockfile`.
+   Repeat CLI help and runtime build there. GitHub publication includes the Git
+   tree/history; npm's files list does not sanitize Git history. Review both.
+5. For initial release or onboarding changes, install the exact candidate on a
+   disposable clean host. Follow setup without sibling checkouts or personal
+   state. Verify owner pairing, real reply, service restart/boot and the first
+   plugin through the actual executor. A fixture proves plumbing only. Use an
+   authorized test account, record receipts privately, publish only a sanitized
+   result. Document any unsupported platform/executor explicitly.
+6. Confirm repository owner/URLs, package-name availability and publisher access;
+   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
+   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.
+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
+   a new patch or deprecate the bad version, never silently replace an artifact.
+
+Container images are built locally in this initial release. Public image
+publication is a separate decision and requires the corresponding source and
+third-party notices. Back up private state before upgrades. Uninstall is not
+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
+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,
+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
+GitHub tag on the same reviewed commit. Do not create a new token to bypass 2FA.
+
+## Agent-owned upgrades
+
+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.

package/docs/setup.md

@@ -0,0 +1,234 @@
+# Agent-led setup
+
+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.
+
+## Main first, then plugins through Telegram
+
+Complete the main installation, verified owner pairing and an actual agent reply
+in Telegram before installing or onboarding any plugin. A supplied WhatsApp
+tarball is optional follow-up input, not a prerequisite. Do not open its setup
+flow, build it, create its catalog entry or ask for a QR scan during main setup.
+Initialize the main registry with the packaged empty catalog only.
+
+After the main agent replies successfully, ask the owner to continue in that
+Telegram conversation: “Install WhatsApp from <exact supplied tarball path>.”
+The installed agent owns artifact inspection, extraction into its writable tools
+directory, catalog registration, install/start and QR delivery in Telegram. The
+original installing CLI must not take over plugin onboarding. If Telegram cannot
+complete a required tool action, diagnose that boundary and report the failure;
+do not finish it externally and call the Telegram workflow successful. An explicit
+owner request for standalone plugin development is a separate workflow.
+
+## Defaults and host prerequisites
+
+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.
+Never overwrite an existing package/deployment or extract over its state. Infer
+the agent name and purpose from the owner's request; ask only when missing.
+
+Before running Node commands, check `command -v node` and `node --version`.
+If Node 22+ or this package's pinned pnpm is missing, provision it using the
+host OS's supported installation method and official distribution instructions,
+then verify the version and service PATH yourself. This is installer work, like
+Docker setup below; do not ask the owner to execute a dependency checklist.
+Only an actual OS consent, admin credential or account-access boundary needs the
+owner. Do not bundle runtimes or change the host's unrelated default toolchain.
+
+Once Node is available, the dependency-free diagnostic works before pnpm install:
+
+```sh
+node /absolute/package/bin/ezenciel-agents-install preflight --executor /absolute/path/to/codex
+```
+
+It reports Node/pnpm, Docker daemon access, Compose, host disk space and the selected
+executor path/version. Disk availability is advisory: inspect Docker's own storage
+too. For an executor path, inspect its identity/version and use the corresponding
+supported key (for example, a verified `/path/to/codex` becomes `codex`). Ensure its
+directory is in the service PATH; a similarly named file is not identity proof.
+The preflight does not prove CLI authentication or sandbox execution; perform the
+harmless tool-call check below. Retry preflight after fixing failed checks.
+
+## Install the supplied release artifact
+
+Use `npm pack @jc_stack/ez-agents@0.1.0-beta.12` or the exact GitHub release
+tarball. Verify its SHA-256 against the release receipt when using GitHub.
+Do not guess an npm name or substitute an unscoped package.
+Choose a permanent package directory and a separate private deployment directory.
+
+```sh
+mkdir -p /absolute/ez-package
+# Inspect before extracting; the archive should contain only package/ entries.
+tar -tzf /absolute/jc_stack-ez-agents-0.1.0-beta.12.tgz
+tar -xzf /absolute/jc_stack-ez-agents-0.1.0-beta.12.tgz -C /absolute/ez-package
+cd /absolute/ez-package/package
+cp docker/pnpm-lock.yaml pnpm-lock.yaml
+pnpm install --frozen-lockfile
+export PATH="$PWD/bin:$PATH"
+export EZ_AGENTS_HOME=/absolute/private/agents
+node bin/ezenciel-agents-install build
+# Set EZ_RELAY_IMAGE to the exact image returned by build for create/start.
+export EZ_RELAY_IMAGE='<returned-image>'
+```
+
+Node 22+ and pnpm 10.30.3 are needed by the host transport. The tarball carries
+its lockfile under docker/ because npm excludes the root pnpm lockfile. Do not
+move this package directory after binding a service to its absolute paths.
+For a source checkout the root lockfile is already present. Do not run a second
+copy of an existing bot token. Continue with the per-agent configuration below.
+
+Verify the tarball against its adjacent `.sha256` or the kit's `SHA256SUMS` before
+extracting. The build tool uses a content-specific image and exclusive build lock,
+with details in the returned private log. A repeated request reports an existing
+build or reuses its verified completed image. If a build was interrupted, inspect
+the log and owning process before recovering its lock; never start duplicates.
+The creator persists the selected EZ_RELAY_IMAGE in the deployment's `docker.env`,
+so later service starts use the same build without depending on shell environment.
+
+## Create, start and verify
+
+1. Make the host ready yourself. Check Docker Engine, Docker Compose, host
+   Node 22+, this package and the current CLI. If Docker or Compose is absent,
+   not running, or unusable by the current user, install the official supported
+   Docker distribution for this operating system, start it, and complete its
+   normal user-access setup. Verify with `docker version`, `docker compose
+   version`, and a harmless disposable container before continuing. Do not
+   hand Docker installation, daemon startup, image building, or Compose
+   commands to the owner. An administrator password, operating-system consent,
+   or Docker Desktop sign-in that the installer cannot approve is the only
+   reason to ask the owner for one concrete action; resume immediately after.
+   Build the relay image once. Record the installing CLI immediately with
+   `ezenciel-agents-create --register-cli <current-cli>`. This is installer metadata,
+   not a question for the user. Do not assume an unpublished npm package exists.
+   Before requesting a bot token, verify a real harmless command through the
+   selected CLI's execution sandbox under the same host user and service
+   environment. A CLI version check, successful model response, or zero exit
+   code does not prove shell tools work. Inspect the tool result itself.
+   On Ubuntu, `bwrap: setting up uid map: Permission denied` can indicate
+   AppArmor's unprivileged-user-namespace restriction. Confirm this with the
+   kernel audit log before changing anything. Explain and obtain authorization
+   for any required host security-policy change; prefer an executable-specific
+   policy reviewed for the installed CLI path. Do not globally disable AppArmor
+   or user-namespace restrictions, or disable the CLI sandbox as a fallback.
+   Repeat the actual sandbox command after remediation. If blocked, report
+   the precise prerequisite and keep installation pending.
+2. Obtain a separate BotFather token for the new agent. Pass it through stdin
+   to the creator; keep it out of argv, logs, images and Markdown.
+   `ezenciel-agents-create` reads the token from stdin by default and does not
+   accept `--token-stdin`. That flag belongs to `ezenciel-agents-setup configure`.
+3. Create its deployment with the host installation's selected CLI:
+
+```sh
+export EZ_AGENTS_HOME=/absolute/private/agents
+bin/ezenciel-agents-create --name family-shopper --purpose 'Help my family plan shopping.' < /private/bot-token
+export EZ_DEPLOYMENT_DIR="$EZ_AGENTS_HOME/family-shopper"
+```
+
+Agent creation defaults to the CLI recorded when the initial package was
+installed. It needs no `--cli` argument. A later shell or different available CLI
+does not change that saved default. No installed-binary ranking or Grok fallback
+is used.
+The creator writes `host-executor.json`, private secrets, mind/control paths,
+purpose and unique plugin volume names. Duplicate names fail without overwriting.
+`ezenciel-agents-create --list` lists deployments without secrets.
+
+Before starting that host transport, initialize the main package’s built-in plugin manager. It runs on the host
+for Docker access and adds no separate package or provider library. The packaged catalog is empty so the relay installs independently.
+Use its empty default catalog. Plugin preparation follows the verified Telegram
+handoff, not this step. Run:
+
+```sh
+node /absolute/ezenciel_agents/bin/ezenciel-agents-tools.mjs init \
+  --home "$EZ_DEPLOYMENT_DIR/tools" \
+  --workspace "$EZ_DEPLOYMENT_DIR/mind" \
+  --host-config "$EZ_DEPLOYMENT_DIR/host-executor.json"
+```
+
+This binds a private `ez` and preserves native command access. The default catalog
+is empty. Do not supply a plugin catalog during first-time main onboarding.
+Initialization
+adds discovery instructions to the mind's TOOLS.md. Verify `tools/bin/ez plugins
+available` before the first agent turn. Also execute the agent-bound
+`ezenciel-agents-message --help` through the selected CLI sandbox and verify
+its actual tool output, so absent launchers or blocked execution are detected
+before asking the owner to test Telegram. Only after a real owner exchange has
+succeeded, the owner requests plugin installation in that Telegram conversation;
+the installed agent registers the supplied source, invokes install/start and follows
+the plugin skill through onboarding and verified use under that same request.
+   Follow the [installation completion contract](plugins.md#installation-completion-contract).
+   Registry initialization itself does not connect accounts or start plugins.
+Never silently reuse a global `ez` from the old sandbox runtime.
+
+4. Follow [host startup templates](host-service.md). Register `bin/ezenciel-agents-host` with the host's native service manager,
+   binding `EZ_DEPLOYMENT_DIR` and the user's existing CLI PATH/HOME. On macOS use
+   a LaunchAgent; on Linux use a user service. Use the absolute Node/package
+   paths. This generic transport is the only host execution bridge. Do not start
+   another host relay or install another CLI. Verify its heartbeat, then run
+   `bin/ezenciel-agents-docker up -d --wait`.
+
+   `ezenciel-agents-setup service` is Docker-only startup: run it from the
+   deployment directory containing `docker.env`. It starts the relay and does
+   not install or start the host-executor user service. Complete the host
+   registration above separately.
+
+5. Ask the owner to message the exact bot. Verify the pending numeric identity,
+   approve it, and verify a real CLI-produced Telegram reply. Check restart
+   persistence and two agents running concurrently with separate state.
+   A healthy container and completed CLI run are insufficient: require a
+   Telegram receipt from the CLI-produced reply. If absent, inspect the native
+   CLI transcript and outbox before claiming success or asking the owner to
+   repeat a message. Use the supplied outbound smoke test with the poller
+   stopped to verify repairs, then restore the poller; never replay uncertain
+   user actions merely to test delivery.
+
+The main runtime is fully installer-owned: build it, register its host
+transport, bring its Compose project up, and verify restart persistence. Plugins
+are installed by the working Telegram agent when the owner requests their
+capability there; account onboarding and provider confirmation follow that request.
+Never use a missing plugin as a reason
+to defer the main relay.
+
+Check progress with `ezenciel-agents-install status --deployment /absolute/deployment`.
+It distinguishes missing configuration, runtime offline, awaiting owner, awaiting
+a verified Telegram reply and readiness for a Telegram plugin request. It inspects
+current heartbeats and owner-bound completed-run delivery receipts without sending
+messages or exposing tokens. Receipt evidence is historical: separately verify
+the current conversation and restart persistence before declaring setup complete.
+
+Purpose seeds SOUL.md once; future customization survives restart. Conversations,
+pairing, files and plugin accounts are separate. The existing host CLI login is
+shared, so this is not a security sandbox against other agents under that user.
+Plugins run in their own containers and own their authentication. Install and
+register them only for the requested agent. Never clone another agent's plugin
+credentials. See [runtime, migration and QA](docker-runtime.md).
+
+The installing CLI is an initial default, not a permanent restriction. An explicit
+owner selection may use any supported CLI/model installed on the host. Native
+`ezenciel-agents-ai list` and `select` expose this choice. A cross-CLI switch
+starts a fresh native conversation and preserves the mind and installation
+default. Existing queued jobs retain their captured execution choice.
+
+## Troubleshooting
+
+| Symptom | Inspect and recover |
+|---|---|
+| Docker unavailable | Check engine and Compose, start the supported installation; complete any required OS consent. |
+| Bot stays silent | Check pending owner identity, relay health, host heartbeat and outbox; approve only the verified owner. |
+| CLI exits without reply | Inspect the actual tool result and delivery receipt; stdout is not Telegram output. |
+| Exit 73 | An existing writer holds this deployment; stop the exact duplicate, never delete the kernel lock. |
+| Plugin absent | Check the bound catalog and install/start the reviewed package explicitly; no plugin ships by default. |
+| Plugin revision mismatch | Reinspect stable source, review the changed hash and explicitly update its catalog pin. |
+| Interrupted CLI cannot resume | Use the explicit new-conversation command after inspecting the failure; no automatic fallback. |
+
+Use `ezenciel-agents-docker logs --tail 100 relay` with EZ_DEPLOYMENT_DIR bound.
+Sanitize logs before sharing. Back up mind/control and private profiles before
+upgrades. Stop the exact Compose project and host service to remove execution;
+retain state unless deletion was requested. Revoke a Telegram bot token through
+BotFather and a WhatsApp device on the phone separately from removing software.
+
+## Agent-owned upgrades
+
+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.