direxio-deployer 0.1.7 → 0.1.8

package/README.md

@@ -69,9 +69,10 @@ The CLI is implemented in Node and uses native paths for the host it runs on. On
 
 ## Minimal Command
 
-Import and verify an AWS deployment profile from an AWS CSV. A temporary
-`DirexioDeployer` IAM user is recommended, but root access keys are allowed
-when the operator explicitly chooses them:
+Import and verify an AWS deployment profile from an AWS CSV. Root access keys
+are the fastest first-deploy path but are highly privileged; save the CSV
+securely and rotate or delete the key after deployment. A temporary
+`DirexioDeployer` IAM user is safer but takes more AWS console steps:
 
 ```bash
 bash scripts/aws-credentials.sh import-csv /path/to/accessKeys.csv direxio-deployer us-east-1
@@ -111,16 +112,15 @@ $env:MESSAGE_SERVER_IMAGE = "direxio/message-server:latest"
 .\scripts\orchestrate.ps1
 ```
 
-Recommendation-only local bridge wiring:
+Recommendation-only local bridge and MCP wiring:
 
 ```bash
 DIREXIO_AGENT_INSTALL=recommend bash scripts/orchestrate.sh
 ```
 
-Automatic local bridge install:
+Automatic local bridge and MCP install is the default. Set runtime selectors only when auto-detection is ambiguous:
 
 ```bash
-DIREXIO_AGENT_INSTALL=auto \
 DIREXIO_AGENT_PLATFORM=auto \
 DIREXIO_CC_CONNECT_AGENT=claudecode \
 DIREXIO_AGENT_INSTALL_MODE=recommended \
@@ -158,9 +158,11 @@ Update an existing node without deleting data:
 
 ```bash
 DOMAIN=<domain> MESSAGE_SERVER_IMAGE=direxio/message-server:latest bash scripts/update.sh
-P2P_EXISTING_STATE_ACTION=continue DOMAIN=<domain> bash scripts/orchestrate.sh
 ```
 
+Image refresh restarts the remote service only. It leaves local credentials,
+`direxio-connect`, MCP artifacts, user confirmations, and runtime checks intact.
+
 Reset application data while preserving EC2, DNS, fixed IP, and Caddy TLS:
 
 ```bash
@@ -168,6 +170,11 @@ DIREXIO_RESET_APP_DATA_CONFIRM=1 DOMAIN=<domain> bash scripts/reset-app-data.sh
 P2P_EXISTING_STATE_ACTION=continue DOMAIN=<domain> bash scripts/orchestrate.sh
 ```
 
+Application data reset clears server-side app volumes, so the follow-up
+orchestrate run regenerates local credentials/MCP artifacts and automatically
+reinstalls/restarts `direxio-connect` plus `direxio-mcp` unless explicitly
+overridden with `DIREXIO_AGENT_INSTALL=recommend` or `skip`.
+
 ## Local Bridge
 
 S6 writes these service-scoped files under `~/.direxio/nodes/<service_id>/`:
@@ -193,7 +200,8 @@ direxio-connect daemon install --config ~/.direxio/nodes/<service_id>/cc-connect
 direxio-connect daemon status --service-name <service_id>
 ```
 
-MCP install and check:
+MCP is installed automatically during S6 when `DIREXIO_AGENT_INSTALL=auto`.
+Manual recovery command:
 
 ```bash
 npm install -g direxio-mcp@latest

package/README_zh.md

@@ -67,8 +67,9 @@ direxio-deployer skill update --agent codex
 
 ## 最小命令
 
-从 AWS CSV 导入并验证一个部署 profile。推荐使用临时 `DirexioDeployer` IAM
-用户；如果操作者明确选择 root access key，也允许继续：
+从 AWS CSV 导入并验证一个部署 profile。root access key 是首次部署最快路径，
+但权限极高；请安全保存 CSV，部署后轮换或删除密钥。临时
+`DirexioDeployer` IAM 用户更安全，但 AWS 控制台步骤更多：
 
 ```bash
 bash scripts/aws-credentials.sh import-csv /path/to/accessKeys.csv direxio-deployer us-east-1
@@ -108,16 +109,15 @@ $env:MESSAGE_SERVER_IMAGE = "direxio/message-server:latest"
 .\scripts\orchestrate.ps1
 ```
 
-仅写入并推荐本地 bridge：
+仅写入并推荐本地 bridge 和 MCP：
 
 ```bash
 DIREXIO_AGENT_INSTALL=recommend bash scripts/orchestrate.sh
 ```
 
-自动安装本地 bridge：
+默认会自动安装本地 bridge 和 MCP。只有自动检测不明确时才需要显式设置 runtime：
 
 ```bash
-DIREXIO_AGENT_INSTALL=auto \
 DIREXIO_AGENT_PLATFORM=auto \
 DIREXIO_CC_CONNECT_AGENT=claudecode \
 DIREXIO_AGENT_INSTALL_MODE=recommended \
@@ -155,9 +155,11 @@ service 目录。
 
 ```bash
 DOMAIN=<domain> MESSAGE_SERVER_IMAGE=direxio/message-server:latest bash scripts/update.sh
-P2P_EXISTING_STATE_ACTION=continue DOMAIN=<domain> bash scripts/orchestrate.sh
 ```
 
+镜像刷新只重启远端服务，不重置本地 credentials、`direxio-connect`、MCP
+配置、用户确认和 runtime checks。
+
 重置应用数据但保留 EC2、DNS、固定 IP 和 Caddy TLS：
 
 ```bash
@@ -165,6 +167,10 @@ DIREXIO_RESET_APP_DATA_CONFIRM=1 DOMAIN=<domain> bash scripts/reset-app-data.sh
 P2P_EXISTING_STATE_ACTION=continue DOMAIN=<domain> bash scripts/orchestrate.sh
 ```
 
+清理应用数据卷后，后续 orchestrate 会重新生成本地 credentials/MCP 配置，
+并默认自动重新安装/重启 `direxio-connect` 和 `direxio-mcp`；如需只写文件，
+显式设置 `DIREXIO_AGENT_INSTALL=recommend` 或 `skip`。
+
 ## 本地 Bridge
 
 S6 会在 `~/.direxio/nodes/<service_id>/` 下写入：
@@ -190,10 +196,10 @@ direxio-connect daemon install --config ~/.direxio/nodes/<service_id>/cc-connect
 direxio-connect daemon status --service-name <service_id>
 ```
 
-MCP 安装和检查：
+默认 `DIREXIO_AGENT_INSTALL=auto` 时，S6 会自动安装 MCP。手动恢复命令：
 
 ```bash
-npm install -g direxio-mcp
+npm install -g direxio-mcp@latest
 DIREXIO_CREDENTIALS_FILE=~/.direxio/nodes/<service_id>/credentials.json direxio-mcp doctor --json
 ```
 

package/SKILL.md

@@ -100,17 +100,28 @@ Step-by-step onboarding flow:
      deployment?"
    - If yes, ask only for the local CSV path or profile name, then verify it
      with `aws sts get-caller-identity`.
-   - If no, default to a temporary IAM administrator user for MVP deployment.
-     Explain in one sentence: "This temporary user lets the deployment tool
-     create and later destroy this Direxio node; delete or disable it after
-     deployment."
-   - Root access keys are allowed when the operator explicitly chooses them.
-     Prefer a temporary `DirexioDeployer` IAM user for routine deployments, but
-     do not block deployment only because `aws sts get-caller-identity` returns
-     an ARN ending in `:root`. Warn once that root credentials are highly
-     privileged and should be rotated or removed when no longer needed, then
-     continue if the user accepts that risk.
-   - Guide only one or two clicks at a time:
+   - If no, offer two credential paths and ask the user to choose:
+     1. **Root access key (default fastest path):** simpler to create for a
+        first deployment because it uses the account owner identity directly.
+        Explain that it is highly privileged, must be saved securely, must
+        never be pasted into chat or committed, and should be rotated or
+        deleted after deployment.
+     2. **Dedicated IAM deployment user:** safer because it avoids root keys,
+        but requires more AWS console steps. Explain in one sentence: "This
+        temporary user lets the deployment tool create and later destroy this
+        Direxio node; delete or disable it after deployment."
+   - If the user chooses the root path, guide only one or two clicks at a time:
+     1. Sign in to AWS as the root account owner.
+     2. Open the root user's **Security credentials** page.
+     3. In **Access keys**, choose **Create access key**.
+     4. Select **Command Line Interface (CLI)**, acknowledge AWS's root-key
+        warning, and create the key.
+     5. Download the `.csv` file, store it securely, and provide only the local
+        CSV path to the agent.
+     6. After deployment, rotate or delete the root access key unless the user
+        has a deliberate reason to keep it.
+   - If the user chooses the dedicated IAM deployment user path, guide only one
+     or two clicks at a time:
      1. Open `https://console.aws.amazon.com/iam/home#/users/create`.
      2. Create a user named `DirexioDeployer-YYYYMMDD` or `DirexioDeployer`.
      3. Attach the AWS managed policy `AdministratorAccess`. State plainly
@@ -122,6 +133,10 @@ Step-by-step onboarding flow:
         continue.
      7. Choose `Create access key`, download the `.csv` file, and provide only
         the local file path.
+   - Root access keys are allowed when the operator explicitly chooses them.
+     Do not block deployment only because `aws sts get-caller-identity` returns
+     an ARN ending in `:root`; report `root=true`, repeat the security warning
+     once, and continue if the user accepts that risk.
    - After credentials are configured, run `aws sts get-caller-identity`,
      report only the account, whether the identity is root, and the redacted
      ARN.
@@ -361,19 +376,19 @@ DIREXIO_CC_CONNECT_AGENT=<optional connect agent>
 DIREXIO_OPENCLAW_ACP_URL=<optional explicit OpenClaw gateway URL>
 DIREXIO_OPENCLAW_ACP_TOKEN_FILE=<optional explicit OpenClaw gateway token file>
 DIREXIO_OPENCLAW_ACP_SESSION=<optional OpenClaw ACP session; defaults to agent:main:main>
-DIREXIO_AGENT_INSTALL=recommend
+DIREXIO_AGENT_INSTALL=auto
 DIREXIO_AGENT_INSTALL_MODE=recommended
 ```
 
 The only supported local conversation bridge is `direxio-connect`, installed from `direxio-connent@latest` by default or built from `https://github.com/YingSuiAI/direxio-connect.git`. S6 creates a Matrix session for `@agent:<server>`, writes `~/.direxio/nodes/<service_id>/cc-connect/config.toml`, and restricts the bridge to the real `agent_room_id`.
 
-The local MCP tool surface is `direxio-mcp`, installed from `direxio-mcp@latest` by default. S6 writes `mcp/codex.toml`, `mcp/openclaw.md`, `mcp/openclaw-server.json`, `mcp/hermes.mcp.json`, `mcp/mcp-servers.json`, and `mcp/env`; these artifacts point to `credentials.json` by `DIREXIO_CREDENTIALS_FILE`. OpenClaw must be configured through the generated `openclaw mcp set` command in `mcp/openclaw.md`; do not paste MCP JSON into `~/.openclaw/openclaw.json`. Keep this separate from cc-connect: cc-connect must use its direct Matrix config and must not use `DIREXIO_CREDENTIALS_FILE`.
+The local MCP tool surface is `direxio-mcp`, installed from `direxio-mcp@latest` by default when `DIREXIO_AGENT_INSTALL=auto`. S6 writes `mcp/codex.toml`, `mcp/openclaw.md`, `mcp/openclaw-server.json`, `mcp/hermes.mcp.json`, `mcp/mcp-servers.json`, and `mcp/env`; these artifacts point to `credentials.json` by `DIREXIO_CREDENTIALS_FILE`. OpenClaw must be configured through the generated `openclaw mcp set` command in `mcp/openclaw.md`; do not paste MCP JSON into `~/.openclaw/openclaw.json`. Keep this separate from cc-connect: cc-connect must use its direct Matrix config and must not use `DIREXIO_CREDENTIALS_FILE`.
 
 `DIREXIO_CC_CONNECT_AGENT` is the preferred explicit selector. Supported values match connent/connect: `acp`, `antigravity`, `claudecode`, `codex`, `copilot`, `cursor`, `devin`, `gemini`, `iflow`, `kimi`, `opencode`, `pi`, `qoder`, `reasonix`, and `tmux`. Detected OpenClaw and Hermes runtimes map to `cc_connect_agent=acp`; they are not native connect agent types. OpenClaw uses `cmd = "openclaw"` with args `["acp", "--session", "agent:main:main"]` by default, letting `openclaw acp` auto-discover the Gateway from `~/.openclaw/openclaw.json`. If the operator needs to force explicit Gateway settings, S6 requires all three real values from the current OpenClaw runtime after pairing: `DIREXIO_OPENCLAW_ACP_URL`, `DIREXIO_OPENCLAW_ACP_TOKEN_FILE`, and `DIREXIO_OPENCLAW_ACP_SESSION`; do not guess these values or reuse old chat output. Hermes uses `cmd = "direxio-connect"` with `args = ["hermes-acp-adapter", "--", "hermes", "acp"]` so the Direxio compatibility layer can suppress Hermes reasoning text before it reaches the Matrix room. Use `DIREXIO_CC_CONNECT_AGENT_CMD`, `DIREXIO_<AGENT>_COMMAND`, and when needed `DIREXIO_CC_CONNECT_AGENT_OPTIONS_TOML` for agent-specific launch details. OpenClaw and Hermes also accept `DIREXIO_OPENCLAW_COMMAND`, `DIREXIO_HERMES_COMMAND`, `DIREXIO_HERMES_ACP_ADAPTER_COMMAND`, `DIREXIO_OPENCLAW_ACP_ARGS_TOML`, and `DIREXIO_HERMES_ACP_ARGS_TOML`; Hermes custom args are child Hermes args and S6 prefixes the adapter wrapper automatically.
 
 `DIREXIO_AGENT_PLATFORM` describes the host runtime following the skill, while `DIREXIO_CC_CONNECT_AGENT` describes the local agent backend that `direxio-connect` should launch. Host runtimes such as Hermes or OpenClaw are not native cc-connect backend types; S6 maps them to the generic ACP backend by default and records `cc_connect_agent=acp`. Override `DIREXIO_CC_CONNECT_AGENT` only when the operator intentionally wants a different local backend.
 
-`DIREXIO_AGENT_INSTALL` may be `skip`, `recommend`, or `auto`. Only `auto` attempts to run `npm install -g direxio-connent@latest` and `direxio-connect daemon install --config ~/.direxio/nodes/<service_id>/cc-connect/config.toml --service-name <service_id> --force`; the default `recommend` records and prints the command without mutating local daemon state. An automatic install is reported as installed only when `direxio-connect daemon status --service-name <service_id>` returns `Status: Running` and recent daemon logs do not show ACP session initialization failure; otherwise S6 records `agent_install_status=install_failed`. S6 calls `agent.matrix_session.create` with `agent_token` and retries transient HTTP 000/404/408/409/425/429/5xx responses before failing, because the Matrix action can become reachable after `/healthz`; defaults are 12 attempts with exponential backoff capped by `DIREXIO_MATRIX_SESSION_RETRY_MAX_INTERVAL`.
+`DIREXIO_AGENT_INSTALL` may be `skip`, `recommend`, or `auto`; the default is `auto`. `auto` attempts to run `npm install -g direxio-connent@latest`, `direxio-connect daemon install --config ~/.direxio/nodes/<service_id>/cc-connect/config.toml --service-name <service_id> --force`, and `npm install -g direxio-mcp@latest`. `recommend` records and prints commands without mutating local daemon/package state. A cc-connect automatic install is reported as installed only when `direxio-connect daemon status --service-name <service_id>` returns `Status: Running` and recent daemon logs do not show ACP session initialization failure; otherwise S6 records `agent_install_status=install_failed`. MCP automatic install records `mcp_install_status=installed` only when npm succeeds. S6 calls `agent.matrix_session.create` with `agent_token` and retries transient HTTP 000/404/408/409/425/429/5xx responses before failing, because the Matrix action can become reachable after `/healthz`; defaults are 12 attempts with exponential backoff capped by `DIREXIO_MATRIX_SESSION_RETRY_MAX_INTERVAL`.
 
 Voice input is supported through `direxio-connect` speech-to-text. When `DIREXIO_SPEECH_API_KEY` or a provider-specific key such as `DIREXIO_SPEECH_QWEN_API_KEY`, `OPENAI_API_KEY`, `GROQ_API_KEY`, `DASHSCOPE_API_KEY`, `GEMINI_API_KEY`, or `GOOGLE_API_KEY` is present, S6 writes `[speech] enabled = true` into the generated config. Without an STT key, do not claim voice input is enabled.
 
@@ -574,9 +589,9 @@ for the current service before giving advice. The status output includes a
 - Resume safety: whether rerunning the same command is safe, or whether the
   operator must preserve `state.json` and continue with
   `P2P_EXISTING_STATE_ACTION=continue`.
-- Local refresh: if `agent_install_status=refresh_pending`, update/reset
-  cleared old credentials, user confirmations, runtime checks, and bridge
-  install proof; the next action is to rerun the deployment workflow to refresh S4-S7, local credentials, MCP snippets, and runtime checks.
+- Local refresh: if `agent_install_status=refresh_pending`, reset/redeploy
+  cleared old credentials, user confirmations, runtime checks, bridge install
+  proof, and MCP install proof; the next action is to rerun the deployment workflow to refresh S4-S7, local credentials, MCP snippets, automatic installs, and runtime checks.
 - Next action: the concrete diagnostic or user action for the current phase.
 - Stop-loss: whether no cloud destroy is needed yet, or how to ask the agent to
   run destroy / run `scripts/destroy.sh` on POSIX or `.\scripts\destroy.ps1` on
@@ -623,8 +638,10 @@ reminders, `billing.cost_estimate`, destroy read-back evidence when applicable,
 `billing.destroy_cleanup_status`, `billing.possible_remaining_billable_resources`,
 and secret-redaction evidence. It also records local refresh state:
 `credentials.status`, `connect.install_status`, and `mcp.status` must show
-`refresh_pending` after update/reset until S5/S6/S7 and runtime verification
-write fresh evidence. User confirmation evidence is redacted before it is
+`refresh_pending` after reset/redeploy until S5/S6/S7 and runtime verification
+write fresh evidence. Image-only update keeps existing local refresh state and
+does not clear credentials, confirmations, runtime checks, or local install
+evidence. User confirmation evidence is redacted before it is
 written to the operation report, so initialization codes and tokens are not
 copied into handoff artifacts.
 If a destroy report lists possible remaining billable resources, tell the user
@@ -637,6 +654,33 @@ do next.
 
 Use `scripts/destroy.sh` for teardown on POSIX shells and `.\scripts\destroy.ps1` from PowerShell on Windows. The Windows wrapper selects Git for Windows Bash for the Bash state machine, sets Windows-compatible local path mode, and converts explicit Windows state paths before invoking `scripts/destroy.sh`. Destroy first checks `direxio-connect daemon status --service-name <service_id>` and stops plus uninstalls only that named daemon when the reported `WorkDir` matches the current service directory, `~/.direxio/nodes/<service_id>/cc-connect`. After AWS resources are terminated and released, destroy reads AWS back and records `destroy.evidence` before removing the corresponding local service directory under `~/.direxio/nodes/<service_id>`. This prevents stale state, credentials, bridge files, and stale local service registrations from blocking or misleading the next deployment while still preserving a reportable AWS cleanup audit trail. It leaves unrelated node credential directories intact.
 
+Before running destroy, warn the user that this is not merely "turning off the
+server." Destroy removes the recorded cloud node and its application data. The
+current app account, friends, channels, messages, Agent room/session, and login
+state will no longer be usable. If the user later deploys again, even with the
+same domain, treat it as a new Direxio node that needs a fresh app
+initialization code, new account setup, new friends, and new channels.
+
+For ordinary users, distinguish the available destructive levels before asking
+for confirmation:
+
+- Update deployment: keep accounts, friends, channels, messages, DNS, TLS, and
+  cloud resources; only refresh the service image and local credentials.
+- Reset app data: keep EC2, public IP, DNS, and TLS storage, but delete app
+  accounts, friends, channels, messages, and Agent room state.
+- Destroy resources: delete the recorded EC2/EBS/EIP/security group/key pair,
+  remove the deployer-managed DNS A record, stop the local bridge, and make the
+  current app data unavailable.
+
+Require an explicit destructive confirmation before destroy when the user has
+not already clearly confirmed this data loss. A suitable confirmation is:
+
+```text
+I confirm destroying this Direxio node and understand the current account,
+friends, channels, messages, and Agent conversation will be lost; redeploying
+later will create a new node/account.
+```
+
 Destroy uses the same AWS identity boundary as deployment: root AWS access-key
 identity is allowed when the operator explicitly chose root credentials. Prefer
 using the same temporary `DirexioDeployer` IAM user/profile for teardown when
@@ -657,15 +701,15 @@ When the user asks for a complete fresh start — "destroy everything", "start o
 
 ## Image Refresh And Data Reset
 
-When the user only asks to pull a newer image on an existing EC2 instance, do not destroy cloud resources and do not delete application or TLS storage. Run `scripts/update.sh` against the current state. It SSHes to the existing node, optionally updates `MESSAGE_SERVER_IMAGE`, runs Docker Compose pull/up, reruns `/opt/p2p/init-tokens.sh`, clears stale local secret fields, clears old user-confirmation/runtime-check evidence, marks `agent_install_status=refresh_pending`, stops only the matching service-scoped direxio-connect daemon when its `WorkDir` matches this service, marks S4-S7 pending, and writes a redacted `operation-report.json`.
+When the user only asks to pull a newer image on an existing EC2 instance, do not destroy cloud resources and do not delete application or TLS storage. Run `scripts/update.sh` against the current state. It SSHes to the existing node, optionally updates `MESSAGE_SERVER_IMAGE`, runs Docker Compose pull/up, reruns `/opt/p2p/init-tokens.sh` only when current bootstrap credentials are missing, leaves local credentials, user-confirmation/runtime-check evidence, cc-connect daemon state, MCP artifacts, and S4-S7 phase state unchanged, and writes a redacted `operation-report.json`.
 
-When the user asks to reset application data on an existing EC2 instance, do not destroy EC2, public IPv4/EIP, DNS, or Caddy TLS storage. Run `scripts/reset-app-data.sh` only after explicit destructive confirmation with `DIREXIO_RESET_APP_DATA_CONFIRM=1`. It clears only the application volumes (`postgres-data`, `message-config`, `message-data`), generates a new backend password/init-code field, restarts the stack, reruns `/opt/p2p/init-tokens.sh`, clears stale local secret fields, clears old user-confirmation/runtime-check evidence, marks `agent_install_status=refresh_pending`, stops only the matching service-scoped direxio-connect daemon when its `WorkDir` matches this service, marks S4-S7 pending, and writes a redacted `operation-report.json`.
+When the user asks to reset application data on an existing EC2 instance, do not destroy EC2, public IPv4/EIP, DNS, or Caddy TLS storage. Run `scripts/reset-app-data.sh` only after explicit destructive confirmation with `DIREXIO_RESET_APP_DATA_CONFIRM=1`. It clears only the application volumes (`postgres-data`, `message-config`, `message-data`), generates a new backend password/init-code field, restarts the stack, reruns `/opt/p2p/init-tokens.sh`, clears stale local secret fields, clears old user-confirmation/runtime-check evidence, marks `agent_install_status=refresh_pending` and `mcp_install_status=refresh_pending`, stops only the matching service-scoped direxio-connect daemon when its `WorkDir` matches this service, marks S4-S7 pending, and writes a redacted `operation-report.json`. The follow-up orchestrate run regenerates local credentials/MCP artifacts and, by default, reinstalls/restarts cc-connect plus direxio-mcp.
 
 Current message-server images require `P2P_PORTAL_PASSWORD` and an explicit `portal.bootstrap`; `init-tokens.sh` owns that cloud-side bootstrap and creates a real Matrix `agent_room_id` when the backend credentials file does not already include one.
 
 Do not delete caddy-data or caddy-config during an image-only refresh. Removing Caddy's ACME storage loses the existing production certificate and can trigger CA duplicate-certificate rate limits. Preserve `caddy-data` and `caddy-config`; clear only `postgres-data message-config message-data` when the requested reset needs a clean homeserver/database.
 
-For repeated test refreshes, rerun `scripts/orchestrate.sh` normally after update/reset. S4-S7 will re-run from state, and S6 only rewrites local credentials and environment files unless `DIREXIO_AGENT_INSTALL=auto` is explicitly set.
+For repeated data-reset refreshes, rerun `scripts/orchestrate.sh` normally after reset. S4-S7 will re-run from state, and S6 regenerates local credentials/MCP artifacts and automatically installs/restarts local packages unless `DIREXIO_AGENT_INSTALL=recommend` or `skip` is explicitly set. Image-only update does not require an orchestrate follow-up unless verification shows the service actually regenerated credentials.
 
 ## Minimal Invocation
 
@@ -679,7 +723,7 @@ MESSAGE_SERVER_IMAGE=direxio/message-server:latest \
 bash scripts/orchestrate.sh
 ```
 
-Use an `AWS_PROFILE` or temporary `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` for the selected AWS identity. Root access keys are allowed when the operator explicitly chooses them; a temporary `DirexioDeployer` IAM user remains the recommended routine path. Do not write AWS secrets, initialization codes, or agent tokens into skill files or the repository.
+Use an `AWS_PROFILE` or temporary `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` for the selected AWS identity. Root access keys are allowed when the operator explicitly chooses them; they are the fastest first-deploy path but highly privileged and must be saved securely, never pasted, and rotated or deleted after deployment. A temporary `DirexioDeployer` IAM user is the safer path but takes more setup steps. Do not write AWS secrets, initialization codes, or agent tokens into skill files or the repository.
 
 On Windows, prefer `.\scripts\orchestrate.ps1` and `.\scripts\destroy.ps1` from PowerShell. These wrappers select Git for Windows Bash for the Bash phases and write Windows-compatible local `direxio-connect` paths.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "direxio-deployer",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Versioned Direxio deployer agent skill and portable deployment orchestration tools.",
   "type": "module",
   "bin": {

package/references/agent-targets.md

@@ -127,7 +127,7 @@ Use `mcp/codex.toml` for Codex and `mcp/hermes.mcp.json` for Hermes. For OpenCla
 
 - `DIREXIO_AGENT_INSTALL=skip`: write credentials/env and cc-connect config only.
 - `DIREXIO_AGENT_INSTALL=recommend`: write files, record state, and print the install command.
-- `DIREXIO_AGENT_INSTALL=auto`: run `npm install -g direxio-connent@latest` and then `direxio-connect daemon install --config ~/.direxio/nodes/<service_id>/cc-connect/config.toml --service-name <service_id> --force`. S6 records this as installed only after `direxio-connect daemon status --service-name <service_id>` reports `Status: Running` and recent daemon logs do not show ACP session initialization failure; otherwise it records `agent_install_status=install_failed`.
+- `DIREXIO_AGENT_INSTALL=auto` (default): run `npm install -g direxio-connent@latest`, `direxio-connect daemon install --config ~/.direxio/nodes/<service_id>/cc-connect/config.toml --service-name <service_id> --force`, and `npm install -g direxio-mcp@latest`. S6 records cc-connect as installed only after `direxio-connect daemon status --service-name <service_id>` reports `Status: Running` and recent daemon logs do not show ACP session initialization failure; otherwise it records `agent_install_status=install_failed`. MCP records `mcp_install_status=installed` only when npm succeeds.
 
 Prefer `DIREXIO_CC_CONNECT_AGENT=<agent>` to choose the local agent that `direxio-connect` should run. Keep `DIREXIO_AGENT_PLATFORM=<runtime>` for auto-detection overrides and legacy host-runtime naming. Use `DIREXIO_AGENT_INSTALL_MODE=cc-connect` only when overriding the default `recommended` mapping explicitly.
 Use `DIREXIO_CC_CONNECT_AGENT_OPTIONS_TOML` for agent-specific options that cannot be represented by `work_dir` or `cmd`; for example `reasonix` requires `serve_url`, `tmux` requires `session`, and generic `acp` requires a command when `DIREXIO_CC_CONNECT_AGENT_CMD` is not enough.

package/references/deployment-lessons.md

@@ -102,10 +102,11 @@ reuse of an old deployment state.
 
 ## Credential Safety
 
-Prefer a temporary `DirexioDeployer` IAM user or dedicated IAM role for routine
-deployment. Root access keys are allowed when the operator explicitly chooses
-them; report that the identity is root and remind the operator to rotate or
-remove the key when it is no longer needed.
+Offer two credential paths for first-time deployment. Root access keys are the
+fastest path but are highly privileged; report that the identity is root,
+remind the operator to save the CSV securely, and rotate or remove the key when
+it is no longer needed. A temporary `DirexioDeployer` IAM user or dedicated IAM
+role is safer but requires more AWS console steps.
 
 Do not store AWS AK/SK in skill files, docs, or committed repo files. Treat
 `state.json`, `outputs.json`, and `~/.direxio/nodes/<service_id>/credentials.json` as local

package/references/deployment-optimization-audit.md

@@ -30,9 +30,10 @@ Current best plan is the stricter plan now encoded in this branch:
    whether to send a real message in the Agent chat box.
 6. Keep update/reset/destroy as separate operations with separate receipts;
    update/reset are now first-class scripts, not runbook-only manual actions.
-7. Treat update/reset follow-up as a Local refresh state: update/reset cleared
-   old credentials, user confirmations, runtime checks, and bridge install
-   proof, so the next action is to rerun S4-S7 and runtime checks.
+7. Treat reset/redeploy follow-up as a Local refresh state: reset/redeploy
+   clears old credentials, user confirmations, runtime checks, bridge install
+   proof, and MCP install proof, so the next action is to rerun S4-S7 and
+   runtime checks. Image-only update keeps local state intact.
 8. Keep Lightsail out of the current user-facing path. Lightsail remains
    deferred until it has an independent resource model, pricing, state,
    destroy, and test matrix.
@@ -132,14 +133,17 @@ Status: Deployer-side implemented.
 
 Current evidence:
 - `scripts/aws-credentials.sh import-csv|verify` imports local CSV credentials,
-  tightens file permissions, blocks root identity, and redacts identity output.
-- `SKILL.md` documents the temporary `DirexioDeployer` IAM user path with
+  tightens file permissions, allows root identity only with explicit operator
+  choice, and redacts identity output.
+- `SKILL.md` documents both the fast root access-key path with security
+  warnings and the safer temporary `DirexioDeployer` IAM user path with
   temporary `AdministratorAccess`, then cleanup.
 - Reports and tests assert secrets are redacted and not written to reports.
 
 Difference from the checklist:
-- The current branch chooses the practical MVP path: temporary IAM admin user,
-  no root access keys, and cleanup guidance after deployment.
+- The current branch chooses the practical MVP path: let the operator choose
+  fast root credentials or a safer temporary IAM admin user, with cleanup
+  guidance after deployment.
 
 Remaining evidence:
 - Long-term least-privilege IAM generation is still a future hardening task.
@@ -226,11 +230,11 @@ Current evidence:
 - S5 refreshes bootstrap credentials from the server.
 - S6 rewrites service-scoped `credentials.json`, `env`, cc-connect config, and
   MCP snippets.
-- Update/reset mark S4-S7 pending and report refresh-pending status.
-- Update/reset stops only the matching service-scoped direxio-connect daemon
+- Reset/redeploy mark S4-S7 pending and report refresh-pending status.
+- Reset/redeploy stops only the matching service-scoped direxio-connect daemon
   when its `WorkDir` matches the current service, so stale local bridge
   processes do not keep using old credentials.
-- `status` reports Local refresh when update/reset cleared old credentials, user confirmations, runtime checks, and bridge install proof.
+- `status` reports Local refresh when reset/redeploy cleared old credentials, user confirmations, runtime checks, bridge install proof, and MCP install proof.
 - Runtime checks fail closed when a stale service directory or wrong WorkDir is
   detected.
 

package/references/deployment-workflow.md

@@ -36,10 +36,14 @@ P2P_EXISTING_STATE_ACTION=destroy
 DOMAIN=<different-domain>
 ```
 
-For first-time credentials, import the selected AWS access-key CSV and verify
-the identity before provisioning. A temporary `DirexioDeployer` IAM user is the
-recommended routine path, but root access keys are allowed when the operator
-explicitly chose them:
+For first-time credentials, offer the operator two paths before provisioning:
+root access key or dedicated IAM deployment user. The root path is the fastest
+because it uses the account owner identity directly, but it is highly
+privileged; tell the operator to save the CSV securely, never paste or commit
+it, and rotate or delete the root key after deployment. The dedicated
+`DirexioDeployer` IAM user path is safer because it avoids root keys, but it
+requires more AWS console steps. Import the selected AWS access-key CSV and
+verify the identity before provisioning:
 
 ```bash
 bash scripts/aws-credentials.sh import-csv /path/to/accessKeys.csv direxio-deployer <region>
@@ -149,19 +153,22 @@ reminders, `billing.cost_estimate`, destroy read-back evidence under
 contain the initialization code, AWS secrets, access tokens, agent tokens, or
 Matrix session tokens. User/runtime evidence is also scrubbed for
 eight-or-more digit numeric strings because users may paste initialization
-codes into confirmation notes. After update/reset, the report must show
+codes into confirmation notes. After reset/redeploy, the report must show
 `credentials.status=refresh_pending`, `connect.install_status=refresh_pending`,
 and `mcp.status=refresh_pending` until S5/S6/S7 and runtime checks refresh
-local evidence.
+local evidence. Image-only update does not clear local credentials,
+confirmations, runtime checks, cc-connect state, or MCP artifacts.
 
 When the user or runtime evidence confirms a manual product gate, write it back
 to state before regenerating the report. Connect daemon status is a
 service-scoped local bridge check, MCP doctor is a non-polluting runtime check,
 MCP tools is stdio `tools/list` discovery, and MCP smoke is a read-only backend
-call. In the default `DIREXIO_AGENT_INSTALL=recommend` path, `verify runtime`
-records `connect_daemon=manual_pending` instead of failing the aggregate,
-because daemon installation is an explicit operator action. These checks are
-not the full runtime product gate:
+call. In the `DIREXIO_AGENT_INSTALL=recommend` path, `verify runtime` records
+`connect_daemon=manual_pending` instead of failing the aggregate, because
+daemon installation is an explicit operator action. The default
+`DIREXIO_AGENT_INSTALL=auto` path expects cc-connect and direxio-mcp to be
+installed automatically during S6. These checks are not the full runtime
+product gate:
 
 ```bash
 DOMAIN=__DOMAIN__ bash scripts/orchestrate.sh verify runtime

package/references/runtime-wiring.md

@@ -137,8 +137,8 @@ Defaults:
 - `DIREXIO_CC_CONNECT_AGENT_OPTIONS_TOML` appends agent-specific options under `[projects.agent.options]`; use it for agents with required non-command options such as `reasonix` (`serve_url`) or `tmux` (`session`).
 - OpenClaw Gateway ACP auto-detects the Gateway from `~/.openclaw/openclaw.json` when `DIREXIO_OPENCLAW_ACP_URL` and `DIREXIO_OPENCLAW_ACP_TOKEN_FILE` are unset. It uses `DIREXIO_OPENCLAW_ACP_SESSION` when provided, otherwise `agent:main:main`. To force explicit Gateway settings, complete OpenClaw pairing first and set all three real values: `DIREXIO_OPENCLAW_ACP_URL`, `DIREXIO_OPENCLAW_ACP_TOKEN_FILE`, and `DIREXIO_OPENCLAW_ACP_SESSION`.
 - `DIREXIO_OPENCLAW_ACP_ARGS_TOML` replaces the generated OpenClaw ACP args array, for example `["acp", "--url", "wss://gateway.example.test:18789", "--token-file", "$HOME/.openclaw/gateway.token", "--session", "agent:main:main"]`. `DIREXIO_HERMES_ACP_ARGS_TOML` supplies the child Hermes args; S6 prefixes `["hermes-acp-adapter", "--", "<hermes-command>"]` automatically.
-- `DIREXIO_AGENT_INSTALL=recommend` prints and records the command only. `verify runtime` records the daemon check as `manual_pending` in this mode and still verifies MCP doctor/tools/smoke.
-- `DIREXIO_AGENT_INSTALL=auto` runs `npm install -g direxio-connent@latest` and then installs the `direxio-connect` daemon with the generated config and `--service-name <service_id>`. It is recorded as installed only when `direxio-connect daemon status --service-name <service_id>` reports `Status: Running` and recent daemon logs do not show ACP session initialization failure; otherwise S6 records `agent_install_status=install_failed`.
+- `DIREXIO_AGENT_INSTALL=auto` is the default. It runs `npm install -g direxio-connent@latest`, installs the `direxio-connect` daemon with the generated config and `--service-name <service_id>`, and runs `npm install -g direxio-mcp@latest`. cc-connect is recorded as installed only when `direxio-connect daemon status --service-name <service_id>` reports `Status: Running` and recent daemon logs do not show ACP session initialization failure; otherwise S6 records `agent_install_status=install_failed`. MCP records `mcp_install_status=installed` only when npm succeeds.
+- `DIREXIO_AGENT_INSTALL=recommend` prints and records commands only. `verify runtime` records the daemon check as `manual_pending` in this mode and still verifies MCP doctor/tools/smoke when the MCP command is available.
 - `DIREXIO_AGENT_INSTALL_MODE=recommended` maps every supported local runtime to `cc-connect`.
 - Speech defaults to `DIREXIO_SPEECH_PROVIDER=openai` and `DIREXIO_SPEECH_LANGUAGE=zh`. Provider-specific keys are also accepted: `DIREXIO_SPEECH_OPENAI_API_KEY` or `OPENAI_API_KEY`, `DIREXIO_SPEECH_GROQ_API_KEY` or `GROQ_API_KEY`, `DIREXIO_SPEECH_QWEN_API_KEY` or `DASHSCOPE_API_KEY`, and `DIREXIO_SPEECH_GEMINI_API_KEY`, `GEMINI_API_KEY`, or `GOOGLE_API_KEY`. Set `DIREXIO_SPEECH_ENABLED=false` to suppress speech config generation even when a key exists.
 

package/references/token-refresh.md

@@ -4,7 +4,9 @@
 
 从服务端同步过来的 `password` 和 owner `access_token` 必须按一次性/易失凭据处理。`password` 是后端字段名，对用户展示时必须叫八位 App 初始化码。用户完成初始化或 token exchange 后，服务端可能立刻重置这些值；任何需要再次获取初始化码，或需要用 `access_token` 调 owner 身份 API/Matrix Client API，或需要用 `agent_token` 调 `agent.matrix_session.create` 的操作，都必须先重新从服务器拉取最新 `/opt/p2p/bootstrap.json`，再更新本地 `credentials.json`。不要复用聊天记录、旧 `state.json`、旧 `credentials.json` 或历史部署输出里的 password/access token。
 
-现有节点执行 `scripts/update.sh` 或 `scripts/reset-app-data.sh` 后，本地旧证据也必须作废。脚本会清掉旧 `password`、`access_token`、`agent_token`、`agent_room_id`、`user_confirmations` 和 `runtime_checks`，把 `agent_install_status` 标成 `refresh_pending`，并只在 `WorkDir` 匹配当前 service 时停止对应的本地 bridge（stops only the matching service-scoped direxio-connect daemon），再把 S4-S7 标回 pending。这样旧的用户确认、MCP discovery、Agent runtime probe 或旧 bridge 安装状态不会被误用到更新/重置后的节点。`status` 会显示 `Local refresh:`，提醒 update/reset 已经清掉旧 credentials、user confirmations、runtime checks 和 bridge install proof；下一步必须 rerun the deployment workflow to refresh S4-S7, local credentials, MCP snippets, and runtime checks。后续必须续跑 `scripts/orchestrate.sh`，让 S5/S6/S7 和 `verify runtime` 重新写入当前证据。
+现有节点执行 `scripts/update.sh` 只做镜像刷新和远端服务重启，不清理应用卷，也不重置本地 `password`、`access_token`、`agent_token`、`agent_room_id`、`user_confirmations`、`runtime_checks`、cc-connect daemon 状态或 MCP artifacts。除非验证发现远端确实重新生成了 bootstrap credentials，否则 update 后不要强制续跑 S4-S7。
+
+执行 `scripts/reset-app-data.sh`、清理应用挂载卷或重新部署服务后，本地旧证据必须作废。脚本会清掉旧 `password`、`access_token`、`agent_token`、`agent_room_id`、`user_confirmations` 和 `runtime_checks`，把 `agent_install_status` 和 `mcp_install_status` 标成 `refresh_pending`，并只在 `WorkDir` 匹配当前 service 时停止对应的本地 bridge（stops only the matching service-scoped direxio-connect daemon），再把 S4-S7 标回 pending。这样旧的用户确认、MCP discovery、Agent runtime probe、旧 bridge 安装状态或 MCP 安装状态不会被误用到重置后的节点。后续必须续跑 `scripts/orchestrate.sh`，让 S5/S6/S7 重新生成本地 credentials/MCP snippets，并默认自动重新安装/重启 cc-connect 和 direxio-mcp，再通过 `verify runtime` 写入当前证据。
 
 ## 远端凭据
 

package/references/tooling.md

@@ -82,7 +82,10 @@ If distro packages are too old or missing, ask before using the official AWS CLI
 
 ## Credentials
 
-Prefer a temporary `DirexioDeployer` IAM user or role. If the user provides an
+For first-time setup, offer a root access key as the fastest path and a
+temporary `DirexioDeployer` IAM user or role as the safer path. Root keys are
+highly privileged; the operator must save the CSV securely, never paste or
+commit it, and rotate or delete it after deployment. If the user provides an
 AWS access-key CSV, import it through the repository helper so command output
 stays redacted and the identity is marked as `root=true|false`:
 

package/references/verification-recovery.md

@@ -72,13 +72,19 @@ remain outside automatic destroy scope.
 
 ## Update / Reset Follow-Up
 
-After `scripts/update.sh` or `scripts/reset-app-data.sh`, rerun:
+After `scripts/reset-app-data.sh`, rerun:
 
 ```bash
 P2P_EXISTING_STATE_ACTION=continue DOMAIN=__DOMAIN__ bash scripts/orchestrate.sh
 ```
 
-The scripts intentionally mark S4-S7 pending and clear stale local secret
+The reset script intentionally marks S4-S7 pending and clears stale local secret
 fields. Do not copy old initialization codes or tokens from chat history,
 `state.json`, or `credentials.json`; S5 must fetch fresh bootstrap data and S6
-must rewrite service-scoped local credentials/MCP snippets.
+must rewrite service-scoped local credentials/MCP snippets and reinstall local
+packages by default.
+
+After `scripts/update.sh`, do not rerun S4-S7 just because the service was
+restarted. Image-only update preserves local credentials, cc-connect daemon
+state, MCP artifacts, confirmations, and runtime checks unless a separate
+verification shows the server regenerated bootstrap credentials.

package/scripts/json.mjs

@@ -373,6 +373,7 @@ function cmdMutate(args) {
         delete data[key];
       }
       data.agent_install_status = "refresh_pending";
+      data.mcp_install_status = "refresh_pending";
       data.phase = startPhase;
       if (!isObject(data.phases)) data.phases = {};
       if (startPhase === "S4_BOOTSTRAP_STACK") {
@@ -513,6 +514,7 @@ function buildOperationReport(operation, status, stateFile, generatedAt, st) {
     },
     mcp: {
       status: localRefreshStatus,
+      install_status: st.mcp_install_status || "",
       package: st.mcp_npm_package || "direxio-mcp@latest",
       server_name: st.mcp_server_name || "",
       config_dir: st.mcp_config_dir || "",

package/scripts/orchestrate.sh

@@ -196,7 +196,7 @@ local_refresh_pending() {
 
 status_local_refresh() {
   if local_refresh_pending; then
-    echo "update/reset cleared old credentials, user confirmations, runtime checks, and bridge install proof"
+    echo "reset/redeploy cleared old credentials, user confirmations, runtime checks, bridge install proof, and MCP install proof"
   fi
 }
 
@@ -204,7 +204,7 @@ status_next_action() {
   if local_refresh_pending; then
     case "$1" in
       S4_BOOTSTRAP_STACK|S5_INIT_TOKENS|S6_WIRE_LOCAL|S7_VERIFY_E2E|DONE)
-        echo "rerun the deployment workflow to refresh S4-S7, local credentials, MCP snippets, and runtime checks"
+        echo "rerun the deployment workflow to refresh S4-S7, local credentials, MCP snippets, automatic installs, and runtime checks"
         return 0
         ;;
     esac

package/scripts/phases/s6_wire_local.sh

@@ -362,7 +362,7 @@ _validate_agent_platform() {
 }
 
 _agent_install_policy() {
-  local policy=${DIREXIO_AGENT_INSTALL:-recommend}
+  local policy=${DIREXIO_AGENT_INSTALL:-auto}
   case "$policy" in
     skip|recommend|auto) printf '%s\n' "$policy" ;;
     *) fail "DIREXIO_AGENT_INSTALL must be skip, recommend, or auto." ;;
@@ -1125,6 +1125,26 @@ _maybe_auto_install_cc_connect() {
   fi
 }
 
+_maybe_auto_install_mcp() {
+  local policy=$1
+  if [ "$policy" != "auto" ]; then
+    state_set mcp_install_status "$policy" 2>/dev/null || true
+    return 0
+  fi
+  if ! command -v npm >/dev/null 2>&1; then
+    warn "DIREXIO_AGENT_INSTALL=auto requested, but npm is not on PATH. Install Node.js to install direxio-mcp automatically."
+    state_set mcp_install_status "npm_missing" 2>/dev/null || true
+    return 0
+  fi
+  if npm install -g "$(_mcp_npm_package)"; then
+    state_set mcp_install_status "installed" 2>/dev/null || true
+    ok "direxio-mcp installed from npm."
+  else
+    state_set mcp_install_status "install_failed" 2>/dev/null || true
+    warn "direxio-mcp npm install failed. MCP config artifacts and install command are available for manual recovery."
+  fi
+}
+
 _agent_skill_install_path() {
   local runtime=$1
   case "$runtime" in
@@ -1442,12 +1462,14 @@ run_phase() {
   state_set agent_install_policy "$install_policy" 2>/dev/null || true
   state_set agent_install_mode "$install_mode" 2>/dev/null || true
   state_set agent_install_command "$install_command" 2>/dev/null || true
+  state_set mcp_install_policy "$install_policy" 2>/dev/null || true
   state_set agent_skill_install_path "$skill_path" 2>/dev/null || true
   state_set agent_global_skill_install_path "$global_skill_path" 2>/dev/null || true
   state_set direxio_agent_bridge "cc-connect" 2>/dev/null || true
   _print_cc_connect_guidance "$runtime" "$asurl" "$node_cred" "$envfile" "$install_policy" "$install_mode" "$install_command" "$node_id" "$cc_config_local" "$cc_binary" "$cc_agent" "$cc_agent_cmd" "$service_id"
   _print_mcp_guidance "$runtime" "$service_id" "$mcp_server_name" "$node_cred_local" "$mcp_dir_local" "$mcp_codex_config_local" "$mcp_openclaw_config_local" "$mcp_hermes_config_local" "$mcp_install_command" "$mcp_doctor_command"
   _maybe_auto_install_agent "$install_policy" "$runtime" "$cc_agent" "$service_dir" "$cc_config" "$cc_binary" "$service_id"
+  _maybe_auto_install_mcp "$install_policy"
 
   phase_set S6_WIRE_LOCAL done "credentials.json written;node_id=$node_id;service_id=$service_id;env_file=$envfile;runtime=$runtime;install_policy=$install_policy;install_mode=$install_mode;cc_connect_config=$cc_config;mcp_config_dir=$mcp_dir;cc_connect_agent=$cc_agent"
   return 0

package/scripts/update.sh

@@ -15,16 +15,8 @@ ops_require_state "$STATE_JSON"
 
 remote_command=$(ops_update_remote_command "${MESSAGE_SERVER_IMAGE:-}")
 ops_ssh "$STATE_JSON" "$remote_command"
-ops_mark_refresh_pending "$STATE_JSON" S4_BOOTSTRAP_STACK
-if ops_stop_scoped_daemon "$STATE_JSON"; then
-  bridge_stop_message="Scoped local bridge daemon was stopped; rerun S6 to install fresh config."
-else
-  bridge_stop_message="Scoped local bridge daemon stop was skipped or not needed."
-fi
-report=$(ops_write_report update update_remote_restart_complete_refresh_pending "$STATE_JSON")
+report=$(ops_write_report update update_remote_restart_complete "$STATE_JSON")
 
 echo "Update remote restart complete."
-echo "Old user confirmations and runtime checks were cleared."
-echo "$bridge_stop_message"
-echo "Local S4-S7 gates were reset; rerun orchestrate with P2P_EXISTING_STATE_ACTION=continue to refresh credentials, MCP, and verification."
+echo "Local credentials, cc-connect daemon state, MCP artifacts, confirmations, and runtime checks were left unchanged."
 echo "operation report: $report"