@jc_stack/ez-agents 0.1.0-beta.26 → 0.1.0-beta.28

package/docs/plugins.md

@@ -28,7 +28,7 @@ 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
+managed AGENTS.md registry locator, 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
@@ -263,10 +263,10 @@ Shared workers have a hard Docker CPU quota of half a core by default, across al
 
 ## Existing local folders
 
-Use operator-owned read-only folder bindings when a plugin needs files that
+Use operator-owned folder bindings when a plugin needs files that
 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. File edits remain with the host's existing tools.
+starts no provider sync. Read-only is the default.
 
 Stop the plugin before changing a binding:
 
@@ -288,9 +288,58 @@ volume contents; inspect those before restarting to avoid using stale files.
 Never enable another sync writer for an already synchronized host folder.
 
 For Library, create/select the library name first and retain its QMD state while
-binding the host tree at that library's `files` directory. Keep provider bindings
-disabled for that source. Enable the normal shared embedding worker through
+binding the host tree at that library's `files` directory. Enable provider bindings
+only when that plugin supports the selected host folder and owns its sync. Enable the normal shared embedding worker through
 `plugins shared-enable library embeddings`. Verify `library sources`, real search,
 and original readback from the actual executor. Document any differences between
 indexed snapshots and current originals; do not replace Library with private
 QMD runtimes or edit installed Compose/package files to bypass missing support.
+
+## Generated capability discovery
+
+`ez tools list --details` generates a compact index directly from installed
+`ez-plugin.json` manifests: each plugin supplies its `description`, command aliases
+and `skills`. Descriptions are limited to 200 characters in this view; full
+instructions stay in the skill. Installation, replacement and removal are reflected
+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.
+
+Folder bindings default to read-only. For an explicitly authorized plugin that
+updates the existing source, add `--writable` to `folder-bind` while the plugin
+is stopped. The grant applies only to that folder and survives compatible
+upgrades. Rebind without `--writable` to return it to read-only. Package
+descriptors cannot request this grant. Keep one synchronization owner for each
+source; a writable mount alone does not configure synchronization.
+
+## Browser endpoints for connected plugins
+
+`ez tools serve HOST_PORT:CONTAINER_PORT ALIAS ARGS...` runs a plugin's web command
+inside its command container while core handles the existing persistent tool
+protocol. Both ports must be 1024–65535. Publication is always on host 127.0.0.1;
+no plugin manifest can request public ingress. Run the foreground command under
+the host's normal service supervisor if it must survive terminal closure. SIGINT
+or SIGTERM cancels the connection and removes its command container.
+
+The plugin owns HTTP, browser authentication, sessions and static assets. HTTPS
+termination, DNS and forwarding are explicit operator configuration. Plugins may
+use the read-only `tools.owner` core request to check the current paired private
+Telegram user and opaque pairing epoch. This is identity data, not an access grant;
+the plugin must authenticate the requester and recheck identity on protected requests.
+No owner returns null, and no bot token is exposed. Standard plugin CLI operations
+still enforce their normal permissions. See the Voice plugin's README for a client.
+
+To add an optional launcher without replacing Telegram's command menu, set the
+relay Compose environment or `.env` (then recreate the relay container):
+
+```dotenv
+EZ_TELEGRAM_WEB_APP={"command":"voice","label":"Voice","url":"https://voice.example.com/"}
+```
+
+The command returns a Mini App button to the authenticated owner in private chat;
+`/menu` includes the same button. Reserved commands cannot be replaced. The HTTPS
+URL must not contain credentials, query parameters or a fragment. This setting
+only registers a launcher; it does not expose a port or authenticate web requests.

package/docs/repair.md

@@ -1,41 +1,42 @@
 # 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.
+Repair is a capability used by an explicit owner request or owner-saved maintenance
+mandate. Discovering a defect alone does not enroll an ordinary conversation in
+an issue/claim/PR workflow. Preserve useful evidence and continue the requested
+task. The current execution guidance supersedes older default-repair text in
+existing workspaces without rewriting the agent's mind.
 
-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.
+For an authorized repair, use the selected engine with native Git/GitHub tools
+and follow the target repository's CONTRIBUTING.md. Check existing work for the
+same cause and use an isolated contribution checkout; never edit the installed
+runtime as the repair checkout. Resume the same branch/PR after interruption.
+A separate issue, claim service or coordinator grant is not an ez prerequisite.
+Use coordination only where the repository or owner explicitly requires it.
 
-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.
+Question the failing wrapper before adding code. Removing behavior or correcting
+existing instructions/tool contracts can fully resolve the defect. Preserve
+useful evidence and verified outcomes, with normal independent review and CI.
+Missing credentials block only operations requiring them; continue useful local
+work and report the precise remaining dependency. Public reports must exclude
+private runtime data and use the security reporting route where appropriate.
+Do not repeatedly check an unchanged dependency.
 
 ## 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
+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.
 
 ## 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.
+Reuse existing authenticated access within the owner's request or saved mandate.
+ez does not provision a coordinator, GitHub identity or publishing token, and
+none is an implicit prerequisite for local diagnosis or an authorized local fix.
+Repository push/PR access, protected-branch review and package publication are
+separate capabilities and permissions. Follow existing release authority; never
+put credentials in prompts, issues or test environments.

package/docs/responsive-channels.md

@@ -1,57 +1,15 @@
 # Responsive channels
 
-Ez treats conversational channels as places to answer, clarify and hand off
-work. A simple question uses the current conversation; a small authorized action
-uses its canonical receipt. Substantial work gets a durable task with enough
-context to finish and verify the job. The agent returns to conversation after
-the handoff is saved, instead of waiting for the worker. This is agent guidance,
-not a keyword classifier, automatic acknowledgement, or latency guarantee.
-
-New Codex agents use Sol / medium for chat. Scheduled work defaults independently
-to Luna / max; the agent can choose another model and effort for complex work.
-`ezenciel-agents-schedule create --now --text-file FILE --model MODEL --effort max`
-uses the existing scheduler (include `--name` for a useful task label). Busy owner
-reply sessions expose the same independent model/effort choice through `defer`.
-Its retry returns the first saved schedule; changing arguments does not revise
-an accepted job. `xhigh` and `max` are available only for Luna; other models remain capped at high.
-
-A handoff includes the objective, relevant context and paths, constraints,
-authorized actions, acceptance checks and delivery destination. Background
-sessions own verification and final delivery, and may use native subagents.
-One writer per workspace still applies. Shared external resources require
-coordination even when task directories differ. Status must distinguish a saved
-schedule from actual execution and a verified result from a process exit.
-
-The package loads `templates/chat-guidance.md` at each turn for CLI, desktop,
-busy owner replies and approved plugin messaging tasks. Upgrades refresh this
-behavior without rewriting the agent's personal files. Existing model choices
-remain pinned; an upgrade adds Responsive chat as an available selection.
-
-## Channel and authority boundaries
-
-Telegram owner conversations can schedule work under the owner's authority.
-The existing restricted busy-reply session keeps Codex chat available while a
-writer is active. Other executors retain their existing concurrency behavior.
-
-WhatsApp and other plugin contacts use the approved messaging task's isolated
-context and tools. They receive the conversational guidance and Sol / medium
-selection, but cannot invoke owner schedules, shell tools or native subagents.
-They report work outside their capabilities to the owner; that report is not
-an instruction or permission to execute. Full delegation from a plugin contact
-needs an explicitly scoped worker capability and return route; this update does
-not grant one. The plugin name alone never confers owner authority.
-
-An application using `channelBackendUrl` owns its conversation, model and job
-lifecycle. The relay does not inject prompts or override the app's model. Such
-backends (including AI Fit) must adopt the same handoff policy in their own
-runtime to benefit. Reuse their canonical job system; do not create a second
-agent in the transport. Telegram polling and app-side queue waits still count
-toward user-visible latency.
-
-## Verification
-
-Tests cover independent worker settings, preserved selections across upgrades,
-idempotent handoffs, invalid settings, revocation and restricted tool boundaries.
-Existing scheduler/host tests cover a conversational reply while work remains
-active. Measure time to the first useful reply and verified task completion
-separately on the deployed provider before claiming a performance improvement.
+Owner input passes unchanged to the selected engine. The agent decides when to
+delegate or schedule long work to remain available. ez queues foreground input
+while a foreground run is active; it does not create a separate busy-reply agent.
+Independent scheduled task directories retain deterministic writer isolation.
+
+Background tasks receive literal task text. Their directories contain no generated
+role instructions or copied identity files; native workspace instructions and
+existing Markdown provide context. The agent chooses what to read and when to use
+the message CLI. Native final text is not automatically delivered to Telegram.
+
+Restricted correspondence receives a typed activation event and scoped tools.
+Authorization, sandboxing and tool handlers enforce contact and lifecycle limits.
+Maintenance and group notifications carry event data; CLI help owns operations.

package/docs/scheduling.md

@@ -32,30 +32,26 @@ 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-luna` with `max` reasoning independently of the creating chat.
-New chats use the separate Sol/medium preset. Busy reply `defer` accepts optional
-`model` and `effort` fields; retries preserve the first saved task choice.
-Use `--cli`, `--model`, and `--effort` to specify another choice. `xhigh` and
-`max` are available only with Codex `gpt-5.6-luna`; every other model remains capped at
-`high`. 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 a policy change.
+New tasks inherit selected engine settings. Explicit `--cli`, `--model` and
+`--effort` override those choices; omitted values use native defaults. Edits
+preserve existing choices. Historical deferred tasks keep their source context
+available through `ezenciel-agents-schedule context`.
 
 ## 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.
+Due occurrences enter the durable queue with stable IDs and literal task text.
+Background runs use fresh native sessions in `work/tasks/RUN_ID/`. No identity
+files or role instructions are generated there. Existing workspace Markdown
+provides context; the engine chooses what to read. Codex uses `AGENTS.md` or `.git`
+as its native project-root marker, so a nested task sees the existing agent scope. 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.
+the main conversation. Foreground inputs queue while a foreground turn runs;
+ez does not create another reply agent. The agent can delegate or schedule long
+work and return to chat. It decides when to send through the message CLI.
+A recurring schedule has at most one pending or active occurrence. Shared
+provider resources still need writer coordination.
 
 Production relay/host execution has no wall-clock timeout. The old
 `EZ_EXECUTOR_TIMEOUT_SECONDS` setting is ignored. Individual network/tool waits
@@ -64,13 +60,14 @@ 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.
+CLI 0.153.4. Ez forwards the full task as ordinary input without interpreting
+`/goal` or constructing a native goal objective. The engine handles the request,
+context and native goal creation. Codex owns continuation; the transport stays
+connected while a native goal is active and verifies its terminal state. It sends
+no continuation prompts and stores no Ez goal state. Ordinary tasks finish when
+the engine completes its turn without an active goal. 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
@@ -109,6 +106,15 @@ 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.
 
+## Failure-review stop
+
+A schedule using `--when unreviewed-failures` stops dispatching its current
+revision after one of its own runs fails. The failed receipt remains available
+through `runs`/`run`; no new retry queue or automatic repair task is created.
+The paired owner or authorized maintainer diagnoses it and explicitly edits the
+schedule to resume. Marking the failure reviewed or pause/resume alone does not
+clear the stop. Ordinary recurring tasks retain their existing failure behavior.
+
 ## QA
 
 `pnpm verify` covers recurrence/DST, restart deduplication, authority revocation,
@@ -136,16 +142,6 @@ 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.
@@ -153,3 +149,11 @@ Create a normal recurring schedule with `--every-seconds 900 --when unreviewed-f
 `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.
+
+The Telegram Scheduled tasks menu lists enabled schedules that still have a pending
+occurrence or a queued/running occurrence. Finished one-time tasks, paused
+schedules and revisions stopped for review are hidden. Each entry shows the
+effective engine/model/effort, next occurrence in UTC (or queued/running state),
+and the first sentence of its saved invocation
+prompt, limited to 140 characters. This is a read-only view; history and full
+prompts remain available through the scheduling CLI.

package/docs/setup.md

@@ -52,26 +52,16 @@ 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-sol` and `medium`
-reasoning, including when initialized with `ezenciel-agents-setup init`. This
-Ez default takes precedence over discovered host client defaults. Saved agent
-selections permitted by the current policy are preserved; use the AI settings to choose another model or effort.
-Ez accepts `xhigh` and `max` only for `gpt-5.6-luna`; every other model rejects explicit
-reasoning above `high` at selection and execution, including old saved or queued choices.
-Unset Codex model/effort resolves to
-Luna/max 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 rejected unless they are Codex Luna/xhigh or Luna/max. Conversation presets pin Sol/medium; the lower-level
-Codex fallback is Luna/max for work without an explicit choice.
-
-New scheduled and one-off background tasks default to Codex Luna/max 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 use Sol/medium while retaining their approved tool
-and context boundaries. Upgrades add Responsive chat to saved choices without
-replacing the selected/default preset. See [responsive channels](responsive-channels.md).
+New agents use the selected engine's native model and effort unless a choice is
+explicitly saved. Scheduling inherits the selected engine settings; `--cli`,
+`--model` and `--effort` provide explicit overrides. Edits preserve saved choices.
+The installed client's catalog supplies supported choices; ez imposes no model-specific
+reasoning cap. Optional compaction settings are passed only when explicitly configured.
+
+Restricted correspondence and busy replies retain their audited Codex adapter and
+isolated tool permissions. They honor explicit model/effort choices; unset values
+use that isolated client's native defaults. Unrestricted user configuration is
+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
@@ -199,7 +189,7 @@ node /absolute/ezenciel_agents/bin/ezenciel-agents-tools.mjs init \
 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
+adds discovery instructions to the mind's AGENTS.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

package/docs/standalone-cli.md

@@ -23,12 +23,12 @@ node /absolute/package/bin/ezenciel-agents-tools.mjs init --standalone \
 ```
 
 Init starts nothing, uses an empty catalog by default, preserves existing
-TOOLS.md notes and appends the registry's discovery instructions. A registry
+workspace notes and adds a managed registry locator to AGENTS.md. 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.
+Use `ez tools list --details` for generated installed-plugin descriptions, help shortcuts and absolute skill paths. Read only the relevant skill.
 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.

package/docs/upgrades.md

@@ -1,5 +1,10 @@
 # Agent-owned software upgrades
 
+For an application's independently deployed frontend, backend or embedded gateway,
+see [managed applications](managed-applications.md). They use their existing
+deployment tools and a saved maintenance mandate; this package updater inventories
+only core and registered plugins.
+
 Available in this beta. Earlier main upgrade/rollback VM QA passed; final-release
 fresh-host/reboot and live plugin upgrade acceptance remain pending. npm
 publication is not required to test this feature. The beta channel is the default
@@ -14,13 +19,18 @@ runs the normal CLI transport. It checks npm every six hours while running and
 queues an owner-bound maintenance turn only when an automatic channel changes.
 No owner means no maintenance executor. Normal user work and maintenance share
 one serial queue. Checks use the installed scoped npm identity; failures are
-visible in `updates check` and private `tools/updates/available.json`.
+visible in `updates check` and private `tools/updates/available.json`. Plugins marked
+`private: true` in their package metadata are reported as local-source updates
+only, without querying public npm; this does not mean they are up to date.
+Explicit local-file updates retain the existing release-contract checks; plugins
+without that contract use their reviewed local-source installation procedure.
+Public packages still receive discovery checks under a manual policy.
 
 ## Installation and scope
 
 Use normal setup and initialize the registry with this deployment's
 `host-executor.json`. This binds `ez updates`, the active package root and the
-Software updates guidance in TOOLS.md. Start `ezenciel-agents-host` using the
+native registry discovery guidance in AGENTS.md. Start `ezenciel-agents-host` using the
 normal OS service template. The host service must use the existing user's Node,
 pnpm (or Corepack) and Docker access. Never put tokens in its environment. Keep the original
 package directory: its small bootstrap remains the service entry point and loads
@@ -185,11 +195,9 @@ written by the new one. Increment it for incompatible writes; this updater will
 refuse that migration. `mainProtocol` identifies the supported updater/registry
 contract, currently 1. Plugin package and manifest versions must match.
 
-The Luna/max durable default keeps this contract: persisted Codex Luna presets
-omit the effort field so older runtimes can read and fail over to their native
-safe default, while the current launcher resolves an omitted Luna effort to
-`max`. The execution choice, rather than the storage encoding, is the policy
-surface.
+Explicit model/effort fields remain stored as selected. Unset values are no longer
+filled by router policy; legacy records with omitted effort use native defaults.
+Upgrading does not invent an explicit setting for an omitted field.
 
 Verify upgrade from the previous supported artifact, retained identity/state,
 failed-health rollback, and rejection of incompatible candidates. Main runtime
@@ -206,14 +214,31 @@ updaters need an exact-version core update to adopt this discovery behavior.
 
 ## Shared agent guidance
 
-Ez includes `templates/agent-guidance.md` from the running package in every
-owner-worker prompt, including resumed CLI and desktop conversations and scheduled
-owner work. After the runtime upgrades, the next turn receives the new guidance.
-An already running turn keeps its original prompt. Restricted contact tasks and
-reply-only workers retain their separate, bounded instructions.
-
-Keep general operating defaults in this package-owned file. Keep agent purpose,
-preferences and local conventions in the workspace's `AGENTS.md`, `SOUL.md`,
-`USER.md` and memory files; upgrades preserve them. Shared guidance does not
-grant permissions, and explicit owner instructions take precedence over its
-defaults within existing execution permissions.
+Setup and runtime startup install `templates/agent-guidance.md` into a marked
+section of the workspace's native `AGENTS.md` (and existing `AGENTS.override.md`).
+Upgrade refreshes only that section; personal content outside it is preserved
+byte-for-byte. New scheduled task workspaces receive the same shared guidance.
+Malformed markers and symlinks fail visibly rather than overwriting personal work.
+
+Codex, agy, Grok and OpenCode discover workspace instructions natively. Claude
+receives the native `--append-system-prompt-file` binding to `AGENTS.md`, alongside
+its own normal instructions. Fresh and resumed owner input is literal; ez does
+not surround it with policies, tool recipes, repair instructions or history.
+The native engine owns instruction loading and its context/token overhead.
+Already running sessions retain their current context until native reload.
+
+Desktop start/resume configuration binds the current run's sanitized environment;
+message commands no longer require a prose environment prefix. Existing
+credentials, permissions, queues, busy replies, scheduling and monitoring are
+preserved. Restricted contact tasks retain their separate
+bounded instruction scopes. For delivered busy replies absent from the native
+conversation, the owner engine can call `ezenciel-agents-schedule context`.
+
+Keep general defaults in the shipped shared file and identity/preferences in
+workspace personal files. Instructions cannot grant permissions; explicit owner
+requests take precedence within existing execution authority.
+
+Update discovery runs independently of active host work. A discovery failure is
+logged locally and retried at the next regular six-hour check; it does not stop
+the host or create a repair task. Inspect `ez updates check` for target diagnostics.
+Actual update transactions retain their existing admission, drain and rollback rules.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jc_stack/ez-agents",
-  "version": "0.1.0-beta.26",
+  "version": "0.1.0-beta.28",
   "private": false,
   "type": "module",
   "description": "A lightweight foundation for persistent business AI assistants using existing AI harnesses, workspaces and plugins.",
@@ -21,7 +21,8 @@
     "ezenciel-agents-host": "bin/ezenciel-agents-host",
     "ezenciel-agents-tools": "bin/ezenciel-agents-tools.mjs",
     "ezenciel-agents-ai": "bin/ezenciel-agents-ai.mjs",
-    "ezenciel-agents-watch": "bin/ezenciel-agents-watch.mjs"
+    "ezenciel-agents-watch": "bin/ezenciel-agents-watch.mjs",
+    "ezenciel-agents-application": "bin/ezenciel-agents-application.mjs"
   },
   "files": [
     "default-plugins.json",
@@ -51,8 +52,7 @@
     "scripts/assert-local-registry.mjs",
     ".dockerignore",
     "scripts/trusted-beta.mjs",
-    "scripts/generate-publish-caller.mjs",
-    "scripts/smoke-busy-reply.ts"
+    "scripts/generate-publish-caller.mjs"
   ],
   "publishConfig": {
     "access": "public",
@@ -112,5 +112,9 @@
     "kind": "main",
     "stateSchema": 1,
     "mainProtocol": 1
+  },
+  "exports": {
+    "./application-client": "./src/application-client.mjs",
+    "./*": "./*"
   }
 }

package/src/agent-guidance.ts

@@ -1,9 +1,38 @@
+import { lstat, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import path from 'node:path'
 import { readFileSync } from 'node:fs'
 
 // Resolve against the installed package, never the agent's editable workspace.
 export const agentGuidance = (): string =>
   readFileSync(new URL('../templates/agent-guidance.md', import.meta.url), 'utf8').trim()
 
-// Channel behavior is shared without exposing owner workspace guidance to contacts.
-export const chatGuidance = (): string =>
-  readFileSync(new URL('../templates/chat-guidance.md', import.meta.url), 'utf8').trim()
+const start = '<!-- ez shared guidance: begin -->'
+const end = '<!-- ez shared guidance: end -->'
+
+// Native instruction installation, refreshed at setup/runtime upgrade, not per turn.
+// Personal instructions outside this one managed block remain byte-for-byte intact.
+export async function installAgentGuidance(workspace: string): Promise<void> {
+  for (const name of ['AGENTS.md', 'AGENTS.override.md']) {
+    const file = path.join(workspace, name)
+    let original: string
+    try {
+      if (!(await lstat(file)).isFile()) throw new Error(`Native instructions must be a regular file: ${file}`)
+      original = await readFile(file, 'utf8')
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue
+      throw error
+    }
+    const block = `${start}\n${agentGuidance()}\n${end}\n\n`
+    const from = original.indexOf(start), to = original.indexOf(end)
+    if ((from < 0) !== (to < 0) || (from >= 0 && (to < from || original.indexOf(start, from + start.length) >= 0 || original.indexOf(end, to + end.length) >= 0)))
+      throw new Error(`Malformed shared guidance block: ${file}`)
+    const updated = from < 0 ? block + original : original.slice(0, from) + block.trimEnd() + original.slice(to + end.length)
+    if (updated === original) continue
+    const temporary = `${file}.${randomUUID()}.tmp`
+    try {
+      await writeFile(temporary, updated, { mode: 0o600, flag: 'wx' })
+      await rename(temporary, file)
+    } finally { await rm(temporary, { force: true }) }
+  }
+}

package/src/ai-cli.ts

@@ -4,7 +4,11 @@ import { join } from 'node:path'
 import { readModels, validateSelection, type AiPreset } from './ai.js'
 import { ControlStore } from './control-state.js'
 
-const {values,positionals}=parseArgs({allowPositionals:true,options:{cli:{type:'string'},model:{type:'string'},effort:{type:'string'}}})
+const {values,positionals}=parseArgs({allowPositionals:true,options:{help:{type:'boolean'},cli:{type:'string'},model:{type:'string'},effort:{type:'string'}}})
+if(values.help){
+  console.log('Usage: ezenciel-agents-ai list | select --cli <installed-cli> [--model <model>] [--effort <effort>]\nChoose only values returned by list. Selection affects subsequent messages; queued work and the installation default are unchanged.')
+  process.exit(0)
+}
 if (!process.env.EZ_CONTROL_DIR) throw new Error('Use this agent’s bound control directory')
 const catalog=await readModels(undefined,undefined,join(process.env.EZ_CONTROL_DIR,'cli','codex'))
 if(positionals[0]==='list')console.log(JSON.stringify(catalog))