@jc_stack/ez-agents 0.1.0-beta.33 → 0.1.0-beta.36

package/docs/plugin-guide.md

@@ -0,0 +1,202 @@
+# Build, install, and publish an Ez plugin
+
+This is the shareable guide for open-source Ez plugin authors. It covers the
+smallest path from a plugin checkout to a working private installation, and
+the separate path for publishing and listing a public product.
+
+The detailed documents linked below remain the normative references for release
+and security edge cases. This page is the front door.
+
+## The important distinction
+
+An Ez plugin can be useful before it is published. These are separate states:
+
+| State | What it means | What is required |
+| --- | --- | --- |
+| Local-only | You install your own reviewed checkout or tarball on your agent. | A valid package, an inspected content hash, and real executor verification. No npm publication or catalog entry. |
+| Catalog-listed | Ez publicly records the plugin as a product capability. | A catalog PR with the canonical repository, package identity, capability, and release links. Registration does not prove that a release exists. |
+| Released | Other users can install an immutable package from npm/GitHub. | Release checks, exact artifact/hash readback, a tagged GitHub release, registry publication, and clean-host verification. |
+
+Do not treat a catalog entry, a GitHub workflow, or a package name as proof that
+an artifact was published. Read back the actual npm and GitHub release records.
+
+## 1. Define the plugin boundary
+
+Use a plugin when the capability needs provider or domain authentication,
+deterministic validation, private state, or provider receipts. The native AI
+engine owns inference, sessions, context, reasoning, tool choice, and
+continuation. Ez core owns authorization, transport, scheduling, cancellation,
+session binding, and delivery receipts.
+
+Keep provider behavior out of the relay and do not add another agent runner,
+model router, conversation engine, prompt-history store, or competing queue.
+General plugins live in the Ez plugin repositories; a product-specific plugin
+stays with the product that owns its canonical data and policy. See the
+[plugin architecture](../../planning/docs/architecture-plugins.md).
+
+## 2. Build the smallest valid package
+
+At minimum, provide:
+
+- `package.json` with a unique scoped package name, SemVer version, repository
+  URLs, `files` allowlist, and supported Node/package-manager versions.
+- A frozen lockfile, `LICENSE`, and `THIRD_PARTY_NOTICES.md`.
+- `README.md` explaining purpose, requirements, exact install/start/onboarding
+  commands, one working read example, identity/account binding, limitations,
+  and troubleshooting.
+- `Dockerfile` and `.dockerignore` when the plugin has a managed service.
+- `ez-plugin.json` with the stable plugin id, matching version, commands, and
+  skill paths. Declare command exposure for external content, external sends,
+  record changes, and requested review.
+- `ez-deployment.json` when the plugin has managed services, volumes,
+  healthchecks, exports, or deployment dependencies.
+- A skill such as `skills/<plugin>/SKILL.md` covering required inputs, private
+  credential handling, external handoffs, resumption/recovery, and readiness
+  evidence.
+- Offline contract/negative tests, `--help`, a read-only doctor, bounded
+  machine-readable commands, stable exit codes, and readback for writes.
+
+The manager snapshots the package according to `package.json.files` plus the
+required manifests and Docker inputs. Keep one canonical checkout; do not keep
+permanent packaged copies or a second registry. See the full
+[plugin contribution requirements](plugin-contributions.md) and the
+[plugin manager contract](plugins.md#deployment-descriptors).
+
+A typical package layout is:
+
+```text
+plugin/
+├── bin/                    # executable entry points
+├── skills/<plugin>/SKILL.md
+├── src/
+├── test/
+├── Dockerfile              # if a service is managed
+├── ez-plugin.json
+├── ez-deployment.json      # if a service is managed
+├── package.json
+├── pnpm-lock.yaml
+├── README.md
+├── LICENSE
+└── THIRD_PARTY_NOTICES.md
+```
+
+## 3. Test and install it before publishing
+
+From the plugin checkout, run the package's documented checks. The standard
+baseline is:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm verify
+npm run release:check
+git diff --check
+```
+
+Run the plugin's Docker/manager smoke test when it has a managed service.
+Verify installation, start/stop, the registered command, restart persistence,
+and non-destructive uninstall using synthetic data. Then run one authorized,
+supported operation through the actual bound executor and verify its canonical
+result or provider receipt.
+
+### Install from local source or an unpublished tarball
+
+Publication is not required. Inspect the exact source first:
+
+```sh
+ez plugins inspect <id> --source /absolute/plugin
+```
+
+Use the returned revision for either a one-off install:
+
+```sh
+ez plugins install <id> --source /absolute/plugin --revision sha256:<inspected-hash>
+ez plugins start <id>
+```
+
+Or save the reviewed source in the agent's local catalog, then install it by
+the catalog entry:
+
+```sh
+ez plugins catalog-add <id> --source /absolute/plugin --revision sha256:<inspected-hash>
+ez plugins install <id>
+ez plugins start <id>
+```
+
+After startup, verify the installed command from the actual executor:
+
+```sh
+ez plugins status <id>
+ez tools list
+ez <command> doctor --json
+```
+
+Use the plugin's real supported operation as the acceptance test. Health,
+registration, or a successful `--help` command alone is not completion. A
+changed source must be inspected again; never install a stale catalog hash.
+
+## 4. Prepare a public release
+
+Use an isolated release worktree and reviewed PR. Then:
+
+1. Bump the package and plugin manifest to the same new SemVer version. Add
+   changelog and migration notes for breaking CLI or state changes.
+2. Run frozen dependency installation, package tests, release checks, Docker
+   checks, `git diff --check`, dependency/license review, and the actual manager
+   smoke test.
+3. Create the candidate with `npm pack --ignore-scripts`. Inspect its file list,
+   compute and record its SHA-256, extract it into a fresh directory, reinstall
+   from the artifact, and repeat the CLI/runtime checks there.
+4. For a first release or onboarding change, install that exact candidate on a
+   disposable clean host and verify the real executor, restart/boot behavior,
+   account binding, and first supported operation.
+5. With explicit release authorization, tag the reviewed source, publish the
+   exact tested artifact, create the matching GitHub prerelease/release, and
+   read back npm metadata, the downloaded tarball hash, release assets, and
+   source/tag identity.
+6. Install the published version on a clean host and repeat the relevant
+   verification before calling the release complete.
+
+For the complete release checklist, use [Releasing](releasing.md). For
+unattended beta publication, use [Verified beta publication](trusted-publishing.md);
+it defines the immutable GitHub asset, sanitized receipt, OIDC trust, dispatch,
+and failure-reconciliation rules. Do not put npm tokens in CI or publish merely
+to test authentication.
+
+## 5. List it as a public product
+
+Catalog registration is a discovery and product step, not installation
+authority. Open a PR updating [Available plugins](plugin-catalog.md) with:
+
+- the product name and one concrete capability description;
+- the canonical public source repository;
+- the exact npm package identity; and
+- canonical npm and GitHub release links.
+
+Only advertise a version as installable after verifying that it exists in the
+registry and in the matching GitHub release. A public catalog entry may exist
+while its first release is still pending; label that state clearly and do not
+present it as an installable version. Keep local/private plugins out of the
+public catalog; they can still be installed by reviewed source and an inspected
+hash.
+
+## The short checklist
+
+### Own agent / unpublished
+
+- [ ] Package, manifests, skill, README, license/notices, and tests exist.
+- [ ] `pnpm verify`, release checks, and the manager/Docker smoke pass.
+- [ ] Source or tarball is inspected and installed with its returned hash.
+- [ ] The actual bound executor performs a real supported operation.
+
+### Public product
+
+- [ ] The exact candidate is packed, inspected, hashed, and clean-host tested.
+- [ ] Release authorization, tag, GitHub asset, npm publication, and readback
+      all refer to the same source and bytes.
+- [ ] A clean installation of the published version is verified.
+- [ ] The public catalog is updated only with verified repository/package/release
+      records.
+
+For contribution, security, and removal details, follow the links above and the
+plugin's own `CONTRIBUTING.md`, `SECURITY.md`, and README.
+

package/docs/plugins.md

@@ -48,6 +48,31 @@ 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.
 
+For an isolated Codex agent, this binding is consumed by the per-agent
+`plugin-broker` service, not by a host executor. Start the deployment only after
+initialization with `COMPOSE_PROFILES=isolated`; Compose then starts the relay
+and broker together. The relay-side `ez` command has no tools-home or Docker
+socket mount. It sends a declared alias, literal arguments, bounded stdin and
+the active run ID over the private control-directory Unix socket. The broker
+revalidates the exact registry/host/workspace ownership, pinned revision and
+owner-authorized run before launching the plugin container.
+
+The broker writes bounded invocation metadata to
+`control/plugin-receipts/<run-id>/`. Plugin stdout/stderr and exit status remain
+available to the native command, including provider/API receipts. Application
+context is narrowed to the installed plugin ID and forwarded as opaque
+`EZ_PLUGIN_CONTEXT`; it is absent from ordinary native commands. No registry,
+plugin container, shared worker, Library index or embedding store is shared
+across agents unless an operator adds an explicit reviewed binding.
+
+The same broker accepts source-based `plugins inspect`, `catalog-add`, and
+`install` only when the source is an existing path under the bound workspace and
+the revision is literal and pinned. It also exposes data-preserving
+`plugins uninstall` and the local-file `updates prepare/apply/recover` lifecycle.
+Candidate archives must be staged inside the bound workspace; public registry
+discovery remains host-supervisor work because the broker has no network. Paths
+outside that workspace are rejected.
+
 ## Installation completion contract
 
 For initial Ez onboarding, plugin requests happen in the working Telegram
@@ -255,6 +280,26 @@ never retries a provider operation. Service startup/restart is explicit; command
 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.
 
+### Application plugin context
+
+An authenticated application can attach opaque domain data under
+`context.plugins.<plugin-id>` when it submits a run. During that active,
+authorized application run, the matching plugin command container receives only
+that object as JSON in `EZ_PLUGIN_CONTEXT`. No other plugin context, core control
+state, owner identity, or application context is forwarded. Ordinary native runs
+and commands launched outside an application run receive no such environment
+variable. The manager authorizes the active run and application binding at command
+admission (prepare time) and rejects revoked authority there; revocation between
+admission and container start is a documented residual window. Transport is a
+`0o600` one-shot compose override consumed via `--file` that sets the command
+service environment directly, never process arguments; the value remains
+visible in `docker inspect` while the container runs.
+
+Use this for a short-lived, domain-scoped capability or an application service
+address. It is not prompt text, a general secret channel, or an environment
+override. Plugin code must validate the object, avoid printing it, and send it
+only to its authoritative service over the reviewed transport.
+
 ## Verification
 
 `npm run verify` runs offline negative/contract tests. Explicit Docker integration:
@@ -291,6 +336,21 @@ already exist on the host. Keep indexes and writable metadata in the plugin's
 normal volume. This uses Docker bind mounts; it copies no source bytes and
 starts no provider sync. Read-only is the default.
 
+For a relay-bound agent, the source must be inside its workspace/shared workspace
+or under a plugin-specific root granted in the agent's external host configuration:
+
+```json
+{
+  "pluginFolderRoots": {
+    "library": ["/absolute/existing/notes"]
+  }
+}
+```
+
+The agent cannot add this grant through its registry. A missing grant fails before
+Compose or registry state changes. Standalone registries remain operator-owned and
+do not use a relay host allowlist.
+
 Stop the plugin before changing a binding:
 
 ```sh
@@ -328,8 +388,9 @@ on the next read, without hooks, LLM calls or a cached inventory file.
 
 `ez tools list` retains its alias mapping for existing clients. Native AGENTS.md
 contains only the agent-bound discovery shortcut. New workspaces do not seed
-TOOLS.md; upgrades preserve legacy notes without rewriting them. Keep owner/account
-policies in agent instructions or linked policy files, separate from plugin metadata.
+TOOLS.md, SOUL.md, USER.md, or an `inbox/`/`work/` layout; upgrades preserve
+legacy notes without rewriting them. Keep owner/account policies in agent
+instructions or linked policy files, separate from plugin metadata.
 
 Folder bindings default to read-only. For an explicitly authorized plugin that
 updates the existing source, add `--writable` to `folder-bind` while the plugin

package/docs/releasing.md

@@ -77,7 +77,20 @@ read back `npm view @jc_stack/ez-agents@0.1.0-beta.12 name version dist-tags --j
 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.
 
+Source-checkout images for a deployment are RC builds of the unreleased commit:
+`ezenciel-agents-install build --label X.Y.Z-beta.N.rc.M` (increasing `.rc.N`)
+from the clean reviewed commit after the PR is open. The label and commit SHA are
+baked into the image; `/status` shows the RC tag first. Never install an
+unlabeled source build or reuse an RC label for different contents.
+
 ## 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.
+
+Automatic main upgrades are gated on deployment compatibility: the candidate's
+`compose.yaml` and `compose.whatsapp.yaml` must match the release the agent
+already runs, or that installed release must carry the reviewed migration.
+Before publishing a release, confirm no compose change slipped in since the
+previous tag; otherwise bootstrap the agents or ship the migration in the
+release they already run.

package/docs/repair.md

@@ -30,7 +30,7 @@ True makes the capability available; it does not itself grant a repair mandate.
 The setting does not change 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.
+saved AGENTS.md preferences; carry those restrictions into background task context.
 
 ## Setup boundary
 

package/docs/responsive-channels.md

@@ -15,4 +15,4 @@ Authorization, sandboxing and tool handlers enforce contact and lifecycle limits
 An owner-approved channel capability adds only a fixed installed alias declared
 as a read-only channel query; it does not expose the workspace, shell, owner
 session or other installed tools.
-Maintenance and group notifications carry event data; CLI help owns operations.
+Group notifications carry event data; CLI help owns operations.

package/docs/scheduling.md

@@ -94,10 +94,10 @@ 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
+Stopping the relay also stops its workers. Run and delivery records are relay
+memory: a process restart drops in-flight runs and queued deliveries by design,
+so the next eligible occurrence dispatches normally and nothing is replayed from
+disk. 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. A failed run that cannot prove whether an external side effect happened stays visible 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.
 

package/docs/setup.md

@@ -67,8 +67,23 @@ not imported into restricted sessions. No workflow prompt is added to input.
 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.
+Never overwrite an existing package/deployment or extract over its state.
+
+Before creation, use your own reasoning and the context already available from
+the owner to write the agent's initial brief. This is not a label or a copy of
+the request. Describe, in concrete language, who the agent serves, what product
+or environment it works in, the outcomes it should help produce, the capabilities
+currently available to it, and important scope boundaries. Include material facts
+you already know about the application; do not invent unknown facts. Omit generic
+personality prose and sections irrelevant to this agent. Keep the result compact
+enough to read on every turn. Ask the owner only when a missing fact would
+materially change the agent being installed.
+
+Pass that generated brief as the purpose. For example, a request to create a
+personal assistant should produce a brief tailored to that person's stated work,
+preferences and connected capabilities—not merely `Personal assistant`. A product
+agent should identify the product, user, current product scope and available
+actions without embedding product-specific behavior in Ez Core.
 
 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
@@ -110,6 +125,8 @@ pnpm install --frozen-lockfile
 export PATH="$PWD/bin:$PATH"
 export EZ_AGENTS_HOME=/absolute/private/agents
 node bin/ezenciel-agents-install build
+# Source checkout only: commit, open the PR, then build
+# node bin/ezenciel-agents-install build --label X.Y.Z-beta.N.rc.M
 # Set EZ_RELAY_IMAGE to the exact image returned by build for create/start.
 export EZ_RELAY_IMAGE='<returned-image>'
 ```
@@ -117,7 +134,10 @@ 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
+For a source checkout the root lockfile is already present. A source checkout is
+an RC: commit and open the PR first, then `build --label X.Y.Z-beta.N.rc.M`; the
+command refuses a dirty tree and bakes the RC tag and commit into the image so
+`/status` never reports the bare package version. 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
@@ -163,20 +183,72 @@ so later service starts use the same build without depending on shell environmen
 
 ```sh
 export EZ_AGENTS_HOME=/absolute/private/agents
-bin/ezenciel-agents-create --name family-shopper --purpose 'Help my family plan shopping.' < /private/bot-token
+bin/ezenciel-agents-create --name family-shopper --purpose 'You are the shopping assistant for the owner and their family. Help plan shared shopping, organize confirmed requests, and use only the installed shopping and messaging capabilities. Do not purchase, message others, or infer household preferences without owner authority.' < /private/bot-token
 export EZ_DEPLOYMENT_DIR="$EZ_AGENTS_HOME/family-shopper"
 ```
 
+Creation records an isolation class. Packaged Codex defaults to `isolated`: the
+native CLI runs inside the relay, which only has that agent's workspace and control mounts.
+Sibling host paths are absent (`ENOENT`), not merely unreadable. Pass
+`--isolation host-capable` only when the owner needs the installer UID (host
+browser, local git, host files). Other installed CLIs default to `host-capable`
+because they are not packaged in the relay; requesting isolated execution for
+them fails closed. Host-capable reuses the host CLI login and is not an OS tenant
+boundary. The class cannot be changed later by flipping Compose; recreate the agent.
+
+Isolated Codex uses the pinned CLI in the relay image and
+`EZ_CODEX_SANDBOX=external` so Codex does not nest a sandbox inside the
+container. Provision that agent's `control/cli/codex/auth.json`; do not bind-mount
+the operator `~/.codex`. The host LaunchAgent is not started. Host-capable agents
+still need [host startup](host-service.md).
+
 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.
+
+Custom Codex providers such as OpenRouter currently require an explicitly
+host-capable agent: their keys are supplied by the private host-service
+environment. The isolated relay has no custom-provider key injection path.
+Register the provider and initial model set as non-secret installation metadata;
+repeat `--codex-model` for every model the agent may select:
+
+```sh
+bin/ezenciel-agents-create \
+  --name family-shopper \
+  --purpose 'Help my family plan shopping.' \
+  --isolation host-capable \
+  --codex-provider openrouter \
+  --codex-provider-name OpenRouter \
+  --codex-base-url https://openrouter.ai/api/v1 \
+  --codex-env-key OPENROUTER_API_KEY \
+  --codex-model google/gemini-3.8-flash \
+  --codex-model deepseek/deepseek-v4.1-flash \
+  < /private/bot-token
+```
+
+This stores provider configuration and model IDs in `host-executor.json`, never
+the API key. The key belongs only in the private host-service environment. The
+agent or owner can later change the active provider/model through the existing
+runtime control without reinstalling or editing an environment file:
+
+```sh
+ezenciel-agents-ai list
+ezenciel-agents-ai select --cli codex --provider openrouter \
+  --model google/gemini-3.8-flash
+```
+
+Changing provider starts a fresh native session so a session is never resumed
+against a different backend. Queued work retains the provider/model captured
+when it was admitted.
 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
+Before starting a host-capable 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.
+Isolated agents still initialize this registry for plugin discovery; they do not
+start `ezenciel-agents-host`.
 Use its empty default catalog. Plugin preparation follows the verified Telegram
 handoff, not this step. Run:
 
@@ -202,16 +274,22 @@ the plugin skill through onboarding and verified use under that same request.
    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
+4. Isolated agents skip host transport. Run `bin/ezenciel-agents-docker up -d --wait`
+   from the deployment directory. This starts the local relay and its per-agent
+   isolated plugin broker; do not narrow the command to `relay`. Do not register
+   `ezenciel-agents-host` for them; starting it fails closed.
+
+   Host-capable agents 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
+   not install or start the host-executor user service. Complete host-capable
    registration above separately.
 
 5. Ask the owner to message the exact bot. Verify the pending numeric identity,
@@ -224,8 +302,8 @@ Never silently reuse a global `ez` from the old sandbox runtime.
    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
+The main runtime is fully installer-owned: build it, register host transport
+only for host-capable agents, 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
@@ -238,9 +316,11 @@ current heartbeats and owner-bound completed-run delivery receipts without sendi
 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.
+Purpose scopes AGENTS.md once; future customization survives restart. Conversations,
+pairing, files and plugin accounts are separate. Isolated agents use the relay
+mount namespace as the filesystem boundary. Host-capable agents share the
+installer UID and CLI login; that class 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).
@@ -256,9 +336,9 @@ default. Existing queued jobs retain their captured execution choice.
 | 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. |
+| Bot stays silent | Check pending owner identity, relay health, host heartbeat (host-capable only) and delivery receipts; 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. |
+| Second relay refuses to start | A live relay already owns this deployment's delivery socket; stop the exact duplicate, never remove a live socket. |
 | 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. |

package/docs/standalone-cli.md

@@ -32,8 +32,9 @@ Use `ez tools list --details` for generated installed-plugin descriptions, help
 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.
+A standalone company registry remains explicit even when invoked from a different
+directory. A relay-bound registry rejects calls from outside its workspace. Other
+projects/accounts must use separate registries and private plugin state.
 
 ## Install and verify a capability
 
@@ -54,9 +55,9 @@ Native client plugins/connectors are not converted into Ez plugins automatically
 
 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.
+bound launcher must be run from the owning agent workspace. Never initialize over
+it or 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.