direxio-deployer 0.1.0 → 0.1.2

package/README.md

@@ -21,6 +21,14 @@
 
 Install the deployer skill from npm, then place it into the current agent runtime's skill directory. Project-local installs are preferred because they keep the deployment skill scoped to the workspace that uses it.
 
+The GitHub repository keeps tests for maintainers and CI, but the published npm package and installed skill copy exclude `tests/` to keep user installs small.
+
+If you want Codex to install and deploy in one instruction, do not say "install skills <GitHub URL>". That triggers GitHub skill installation and can place the skill in the global `~/.codex` directory. Say this instead:
+
+```text
+Install the Direxio deployer skill in the current project via npm: run npm install -g direxio-deployer@latest, then run direxio-deployer skill install --agent codex --scope project --project .; do not install the skill from GitHub and do not install it globally under ~/.codex. After installation, use that skill to deploy Direxio with domain __DOMAIN__.
+```
+
 POSIX shells:
 
 ```bash
@@ -51,7 +59,7 @@ direxio-deployer skill install --agent codex --scope global
 The installer writes `.direxio-skill-install.json` into the target directory and refuses to overwrite unmanaged existing content unless `--force` is provided. To pin a version, install that package version first:
 
 ```bash
-npm install -g direxio-deployer@0.1.0
+npm install -g direxio-deployer@0.1.2
 direxio-deployer skill update --agent codex --scope project --project .
 ```
 
@@ -118,7 +126,7 @@ bash scripts/orchestrate.sh
 ```
 
 Supported install modes: `recommended` and `cc-connect`.
-If `DIREXIO_AGENT_PLATFORM=auto` cannot identify a single supported runtime, set `DIREXIO_CC_CONNECT_AGENT` explicitly. For OpenClaw or Hermes defaults, force the host runtime with `DIREXIO_AGENT_PLATFORM=openclaw` or `DIREXIO_AGENT_PLATFORM=hermes`; setting only `DIREXIO_CC_CONNECT_AGENT=acp` selects generic ACP and requires manual options. For OpenClaw Gateway ACP, set `DIREXIO_OPENCLAW_ACP_URL`, `DIREXIO_OPENCLAW_ACP_TOKEN_FILE`, and `DIREXIO_OPENCLAW_ACP_SESSION` from the current OpenClaw runtime after pairing. Use `DIREXIO_OPENCLAW_ACP_ARGS_TOML` only when you need to provide the complete OpenClaw ACP args array yourself. Use `DIREXIO_HERMES_ACP_ARGS_TOML` for the child Hermes args; S6 prefixes the `hermes-acp-adapter -- <hermes-command>` wrapper automatically.
+If `DIREXIO_AGENT_PLATFORM=auto` cannot identify a single supported runtime, set `DIREXIO_CC_CONNECT_AGENT` explicitly. For OpenClaw or Hermes defaults, force the host runtime with `DIREXIO_AGENT_PLATFORM=openclaw` or `DIREXIO_AGENT_PLATFORM=hermes`; setting only `DIREXIO_CC_CONNECT_AGENT=acp` selects generic ACP and requires manual options. OpenClaw Gateway ACP defaults to `["acp", "--session", "agent:main:main"]` and lets `openclaw acp` auto-detect the Gateway from `~/.openclaw/openclaw.json`. To force explicit Gateway settings, set all of `DIREXIO_OPENCLAW_ACP_URL`, `DIREXIO_OPENCLAW_ACP_TOKEN_FILE`, and `DIREXIO_OPENCLAW_ACP_SESSION` from the current OpenClaw runtime after pairing. Use `DIREXIO_OPENCLAW_ACP_ARGS_TOML` only when you need to provide the complete OpenClaw ACP args array yourself. Use `DIREXIO_HERMES_ACP_ARGS_TOML` for the child Hermes args; S6 prefixes the `hermes-acp-adapter -- <hermes-command>` wrapper automatically.
 
 Check status:
 

package/README_zh.md

@@ -19,6 +19,14 @@
 
 通过 npm 安装 deployer skill，再把它写入当前智能体运行时的 skill 目录。默认推荐 project-local 安装，让部署 skill 跟随当前 workspace。
 
+GitHub 仓库保留测试用于维护和 CI，但发布到 npm 的包以及安装到智能体 skill 目录的副本不包含 `tests/`，以减小用户安装体积。
+
+如果你想让 Codex 一句话安装并开始部署，不要说“安装 skills <GitHub 链接>”。那会触发 GitHub skill 安装器，容易安装到全局 `~/.codex`。推荐这样说：
+
+```text
+请在当前项目用 npm 安装 Direxio deployer skill：运行 npm install -g direxio-deployer@latest，然后运行 direxio-deployer skill install --agent codex --scope project --project .；不要从 GitHub 安装 skill，不要安装到全局 ~/.codex。安装后使用该 skill 部署 Direxio 服务，域名使用 __DOMAIN__。
+```
+
 POSIX shell：
 
 ```bash
@@ -49,7 +57,7 @@ direxio-deployer skill install --agent codex --scope global
 安装器会在目标目录写入 `.direxio-skill-install.json`，并拒绝覆盖没有该 manifest 的既有目录，除非显式传入 `--force`。如需固定版本，先安装指定 npm 版本：
 
 ```bash
-npm install -g direxio-deployer@0.1.0
+npm install -g direxio-deployer@0.1.2
 direxio-deployer skill update --agent codex --scope project --project .
 ```
 
@@ -115,7 +123,7 @@ bash scripts/orchestrate.sh
 ```
 
 可选安装模式：`recommended`、`cc-connect`。
-如果 `DIREXIO_AGENT_PLATFORM=auto` 无法唯一识别当前运行时，显式设置 `DIREXIO_CC_CONNECT_AGENT`。需要触发 OpenClaw 或 Hermes 默认配置时，设置 `DIREXIO_AGENT_PLATFORM=openclaw` 或 `DIREXIO_AGENT_PLATFORM=hermes`；只设置 `DIREXIO_CC_CONNECT_AGENT=acp` 会进入通用 ACP，需要手动提供 options。OpenClaw Gateway ACP 必须在完成 pairing 后，从当前 OpenClaw runtime 填写 `DIREXIO_OPENCLAW_ACP_URL`、`DIREXIO_OPENCLAW_ACP_TOKEN_FILE` 和 `DIREXIO_OPENCLAW_ACP_SESSION`。只有需要完整覆盖 OpenClaw ACP args 数组时才使用 `DIREXIO_OPENCLAW_ACP_ARGS_TOML`；Hermes 自定义参数用 `DIREXIO_HERMES_ACP_ARGS_TOML`，S6 会自动在前面加上 `hermes-acp-adapter -- <hermes-command>`。
+如果 `DIREXIO_AGENT_PLATFORM=auto` 无法唯一识别当前运行时，显式设置 `DIREXIO_CC_CONNECT_AGENT`。需要触发 OpenClaw 或 Hermes 默认配置时，设置 `DIREXIO_AGENT_PLATFORM=openclaw` 或 `DIREXIO_AGENT_PLATFORM=hermes`；只设置 `DIREXIO_CC_CONNECT_AGENT=acp` 会进入通用 ACP，需要手动提供 options。OpenClaw Gateway ACP 默认写入 `["acp", "--session", "agent:main:main"]`，让 `openclaw acp` 从 `~/.openclaw/openclaw.json` 自动发现 Gateway。需要强制指定 Gateway 时，完成 pairing 后从当前 OpenClaw runtime 同时填写 `DIREXIO_OPENCLAW_ACP_URL`、`DIREXIO_OPENCLAW_ACP_TOKEN_FILE` 和 `DIREXIO_OPENCLAW_ACP_SESSION`。只有需要完整覆盖 OpenClaw ACP args 数组时才使用 `DIREXIO_OPENCLAW_ACP_ARGS_TOML`；Hermes 自定义参数用 `DIREXIO_HERMES_ACP_ARGS_TOML`，S6 会自动在前面加上 `hermes-acp-adapter -- <hermes-command>`。
 
 查看状态：
 

package/SKILL.md

@@ -207,6 +207,18 @@ Step-by-step onboarding flow:
    - Give a short billing warning before the first mutating AWS command:
      "This will create paid AWS resources for the server. They keep billing
      until destroyed."
+   - When AWS CLI is available after credentials are verified, make a best
+     effort Free Tier account-plan check:
+     ```bash
+     aws freetier get-account-plan-state --output json
+     ```
+     If it returns `accountPlanRemainingCredits`, mention the remaining credit
+     amount and expiration without treating it as a guarantee. If the command
+     is unavailable or fails, use the fixed wording: "AWS currently advertises
+     100 USD initial credits for new customer accounts, plus possible
+     additional credits after completing Free Tier activities. These credits
+     may cover a small trial deployment, but coverage is account-specific and
+     must be verified in AWS Billing Console."
    - **Provide an upfront monthly cost estimate** based on the selected
      region and instance type, so the user can decide whether to proceed.
      `scripts/orchestrate.sh` records `cost_estimate` in state before the
@@ -252,10 +264,15 @@ Step-by-step onboarding flow:
    - If the user asks what is billed, mention EC2/server, fixed public IPv4 or
      Elastic IP, storage, DNS, network traffic, and call relay traffic.
 
-Required first-time deployment confirmation:
+Required first-time deployment confirmation. Fill in the concrete domain,
+profile, and region, and include the Free Tier sentence immediately before the
+confirmation line:
 
 ```text
-I confirm that I have an active AWS account, a real long-lived domain, and an AWS access key CSV or AWS profile for this deployment. I understand this can create billable AWS resources and that they keep billing until destroyed.
+Please confirm before I deploy. AWS new customer accounts may have Free Tier credits, currently advertised as 100 USD initial credits plus possible additional credits; these credits may cover a small trial deployment, but actual coverage must be verified in AWS Billing Console.
+
+Reply with this exact sentence:
+I confirm that I have an active AWS account, the long-lived domain <domain>, and authorize the current <profile-or-identity> AWS profile in <region> to create the Direxio service. I understand this can create billable AWS resources, credits are not guaranteed to cover all usage, and resources keep billing until destroyed.
 ```
 
 If any prerequisite is missing, stop deployment and guide the user through that
@@ -280,6 +297,13 @@ Lightsail is a future deployment mode, not a current automatic option. Lightsail
 
 When the user asks to install or update this skill itself, or asks to wire Direxio into a local agent runtime, read `references/agent-targets.md` first. It is the source of truth for connent/connect agent targets, legacy host-runtime aliases, generic targets, and unknown targets.
 
+If the user says "install skills" and includes the GitHub repository URL
+`YingSuiAI/direxio-deployer`, do not use a generic GitHub skill installer for
+normal deployment use. First install the npm package and then run
+`direxio-deployer skill install --agent <runtime> --scope project --project
+<project-root>`. Use a Git clone only when the user explicitly asks for
+deployer development or local patching.
+
 For this skill repository itself, first determine whether the current working directory belongs to a project or workspace. Treat an explicit workspace root, project files, or an existing agent-specific directory such as `.codex/`, `.claude/`, `.gemini/`, `.cursor/`, `.github/copilot/`, `.devin/`, `.opencode/`, `.qoder/`, `.pi/`, `.openclaw/`, or `.hermes/` as a project target.
 
 If a project target exists, install or update this skill with the versioned npm CLI at the runtime-specific project-local path from `references/agent-targets.md`:
@@ -316,9 +340,9 @@ Post-deploy agent wiring is controlled by:
 ```bash
 DIREXIO_AGENT_PLATFORM=auto
 DIREXIO_CC_CONNECT_AGENT=<optional connect agent>
-DIREXIO_OPENCLAW_ACP_URL=<required for OpenClaw gateway URL>
-DIREXIO_OPENCLAW_ACP_TOKEN_FILE=<required for OpenClaw gateway token file>
-DIREXIO_OPENCLAW_ACP_SESSION=<required for OpenClaw ACP session>
+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_MODE=recommended
 ```
@@ -327,7 +351,7 @@ The only supported local conversation bridge is `direxio-connect`, installed fro
 
 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`.
 
-`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"` but S6 requires the current agent/operator to supply the real `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_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.
 
@@ -439,7 +463,7 @@ NS nameservers before authoritative DNS can resolve. Never use temporary
 ## Deployment Flow
 
 1. Complete the Cloud Account And Domain Onboarding gate above for first-time users or whenever AWS credentials, domain ownership, or DNS authority are unclear.
-2. Read `references/tooling.md`; inspect the user OS and install or prepare missing `bash`, `aws`, `jq`, `ssh`, `scp`, `curl`, and DNS lookup capability only after approval.
+2. Read `references/tooling.md`; inspect the user OS and install or prepare missing `bash`, `node`, `aws`, `ssh`, `scp`, `curl`, and DNS lookup capability only after approval.
 3. Inspect DNS, AWS credentials, region defaults, local tooling, and existing deployment state before asking the user anything that can be discovered automatically.
    **DNS tool preflight:** Before any DNS propagation or Route53 delegation
    check, confirm the environment has at least one working DNS lookup path:
@@ -649,7 +673,7 @@ Ask once, plainly and in the user's language. The confirmation message must summ
 - AWS credentials source, including whether root access keys are being used.
 - AWS/domain onboarding status: active AWS account, real long-lived domain, access key CSV or AWS profile, DNS authority, and billing/deletion acknowledgement.
 - Existing state action: `continue`, `destroy`, or different `DOMAIN`/service directory.
-- Network/system installs: package managers, AWS CLI, jq, Git Bash/MSYS2/WSL, Homebrew, apt/dnf/yum/pacman/zypper.
+- Network/system installs: package managers, Node.js, AWS CLI, Git Bash/MSYS2/WSL, Homebrew, apt/dnf/yum/pacman/zypper.
 
 After the user confirms the summary, proceed without re-confirming individual fields. Ask again only when the configuration materially changes, an unapproved destructive action becomes necessary, or an external action such as DNS must be completed by the user.
 

package/bin/direxio-deployer.mjs

@@ -20,8 +20,7 @@ const skillFiles = [
   "bin",
   "package.json",
   "references",
-  "scripts",
-  "tests"
+  "scripts"
 ];
 
 const projectTargets = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "direxio-deployer",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Versioned Direxio deployer agent skill and portable deployment orchestration tools.",
   "type": "module",
   "bin": {
@@ -15,8 +15,7 @@
     "agents/",
     "bin/",
     "references/",
-    "scripts/",
-    "tests/"
+    "scripts/"
   ],
   "scripts": {
     "test": "bash tests/npm_skill_distribution_test.sh && bash tests/skill_structure_test.sh && bash tests/s6_wire_local_test.sh && bash tests/render_userdata_remote_nodes_test.sh"

package/references/agent-targets.md

@@ -6,6 +6,12 @@ Use this file when installing or updating this skill and when reviewing S6 local
 
 Prefer a project-local npm-managed install when a project or workspace exists. Install the versioned package, then let the CLI copy the skill bundle into the runtime-specific target:
 
+Do not use a generic "install skills <GitHub URL>" instruction for normal users. That can invoke a host's GitHub skill installer and place this repository under the global runtime directory before the npm-managed installer runs. For Codex, the project-local instruction is:
+
+```text
+Install the Direxio deployer skill in the current project via npm: run npm install -g direxio-deployer@latest, then run direxio-deployer skill install --agent codex --scope project --project .; do not install the skill from GitHub and do not install it globally under ~/.codex.
+```
+
 POSIX shells:
 
 ```bash
@@ -125,4 +131,4 @@ Use `mcp/codex.toml` for Codex and `mcp/hermes.mcp.json` for Hermes. For OpenCla
 
 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.
-For OpenClaw Gateway ACP, complete OpenClaw pairing first, then set `DIREXIO_OPENCLAW_ACP_URL`, `DIREXIO_OPENCLAW_ACP_TOKEN_FILE`, and `DIREXIO_OPENCLAW_ACP_SESSION` from the current OpenClaw runtime. S6 writes `["acp", "--url", <url>, "--token-file", <local path>, "--session", <session>]` and converts the token-file with `DIREXIO_LOCAL_PATH_STYLE`. `DIREXIO_OPENCLAW_ACP_ARGS_TOML` replaces the OpenClaw ACP args array only when the runtime needs a fully custom argument list. `DIREXIO_HERMES_ACP_ARGS_TOML` supplies the child Hermes args and keeps the Direxio adapter prefix.
+For OpenClaw Gateway ACP, S6 defaults to `["acp", "--session", "agent:main:main"]` and lets `openclaw acp` auto-discover the Gateway from `~/.openclaw/openclaw.json`. To force an explicit Gateway, complete OpenClaw pairing first, then set all of `DIREXIO_OPENCLAW_ACP_URL`, `DIREXIO_OPENCLAW_ACP_TOKEN_FILE`, and `DIREXIO_OPENCLAW_ACP_SESSION` from the current OpenClaw runtime. S6 writes `["acp", "--url", <url>, "--token-file", <local path>, "--session", <session>]` and converts the token-file with `DIREXIO_LOCAL_PATH_STYLE`. `DIREXIO_OPENCLAW_ACP_ARGS_TOML` replaces the OpenClaw ACP args array only when the runtime needs a fully custom argument list. `DIREXIO_HERMES_ACP_ARGS_TOML` supplies the child Hermes args and keeps the Direxio adapter prefix.

package/references/deployment-lessons.md

@@ -39,7 +39,7 @@ Use a POSIX shell that actually runs the deployment scripts:
 
 ```powershell
 Get-Command bash.exe -All
-bash -lc 'echo ok; command -v aws; command -v jq; command -v ssh; command -v scp; command -v curl'
+bash -lc 'echo ok; command -v node; command -v aws; command -v ssh; command -v scp; command -v curl'
 ```
 
 If `bash` prints the Windows Subsystem for Linux installation prompt or exits
@@ -47,11 +47,9 @@ before running `echo ok`, it is only the Windows WSL launcher and cannot run ops
 until a WSL distro is installed. Use another POSIX shell such as Git Bash, MSYS2,
 Cygwin, or a working WSL distro.
 
-The orchestrator now prepends workspace-local `.tools/bin` when present. This
-directory is an optional local tool cache that may be downloaded by the operator
-or system; it is not assumed to come from the original repo or from the skill.
-When `.tools/bin/jq.exe` exists, compatible Windows POSIX shells can discover it
-without manual PATH surgery.
+The orchestrator uses the repository's Node.js JSON helper for local JSON
+processing, so the POSIX shell that runs deployment scripts must be able to run
+`node` against the same path style it passes to the scripts.
 
 Prefer the `ssh`/`scp` that belongs to the same POSIX environment used for
 `bash`. Windows OpenSSH can reject EC2 private keys because inherited ACLs make
@@ -132,7 +130,7 @@ Fix procedure:
 
 1. Read the created or reused zone details from `state.json`:
    ```bash
-   jq '.resources | {route53_zone_id, route53_zone_name, route53_name_servers}' ~/.direxio/nodes/<service_id>/state.json
+   node scripts/json.mjs get ~/.direxio/nodes/<service_id>/state.json resources
    ```
 2. Delegate those NS servers at the current registrar, or use the provider API
    if credentials are available.

package/references/deployment-workflow.md

@@ -55,9 +55,13 @@ bash scripts/pricing-estimate.sh --state ~/.direxio/nodes/<service_id>/state.jso
 selection and refreshes it in S3 after the final EC2 instance type is known.
 The estimate includes EC2, gp3 storage, public IPv4, and Route53 hosted-zone
 cost when applicable. It excludes data transfer, TURN relay traffic, domain
-registration, taxes, and AWS credits. Credit coverage is not guaranteed; verify
-credits and actual charges in AWS Billing Console, and set an AWS Budget or
-billing alert before leaving the node running.
+registration, taxes, and AWS credits. When available, check the Free Tier
+account plan with `aws freetier get-account-plan-state --output json`;
+otherwise tell the user that AWS currently advertises 100 USD initial credits
+for new customer accounts plus possible additional credits after Free Tier
+activities. Credit coverage is not guaranteed; verify credits and actual
+charges in AWS Billing Console, and set an AWS Budget or billing alert before
+leaving the node running.
 
 ## Destroy
 
@@ -282,7 +286,7 @@ If the domain is registered outside Route53, delegate the recorded nameservers
 at the current registrar or through a provider API:
 
 ```bash
-jq '.resources | {route53_zone_id, route53_zone_name, route53_name_servers}' ~/.direxio/nodes/<service_id>/state.json
+node scripts/json.mjs get ~/.direxio/nodes/<service_id>/state.json resources
 ```
 
 After authoritative DNS returns the new IP, continue with the same state:

package/references/runtime-wiring.md

@@ -112,9 +112,9 @@ DIREXIO_<AGENT>_COMMAND=<optional agent-specific executable path>
 DIREXIO_CC_CONNECT_AGENT_OPTIONS_TOML=<optional extra TOML under projects.agent.options>
 DIREXIO_OPENCLAW_COMMAND=<optional OpenClaw executable path>
 DIREXIO_HERMES_COMMAND=<optional Hermes executable path>
-DIREXIO_OPENCLAW_ACP_URL=<required OpenClaw gateway URL>
-DIREXIO_OPENCLAW_ACP_TOKEN_FILE=<required OpenClaw ACP token file>
-DIREXIO_OPENCLAW_ACP_SESSION=<required OpenClaw ACP session>
+DIREXIO_OPENCLAW_ACP_URL=<optional explicit OpenClaw gateway URL>
+DIREXIO_OPENCLAW_ACP_TOKEN_FILE=<optional explicit OpenClaw ACP token file>
+DIREXIO_OPENCLAW_ACP_SESSION=<optional OpenClaw ACP session; defaults to agent:main:main>
 DIREXIO_OPENCLAW_ACP_ARGS_TOML=<optional OpenClaw ACP TOML array>
 DIREXIO_HERMES_ACP_ARGS_TOML=<optional Hermes ACP TOML array>
 DIREXIO_CC_CONNECT_NPM_PACKAGE=direxio-connent@latest
@@ -131,11 +131,11 @@ DIREXIO_SPEECH_LANGUAGE=zh
 Defaults:
 
 - `DIREXIO_CC_CONNECT_AGENT` is the preferred explicit selector. It accepts every connent/connect agent: `acp`, `antigravity`, `claudecode`, `codex`, `copilot`, `cursor`, `devin`, `gemini`, `iflow`, `kimi`, `opencode`, `pi`, `qoder`, `reasonix`, and `tmux`.
-- `DIREXIO_AGENT_PLATFORM=auto` detects the local agent runtime and maps it to a `direxio-connect` agent type only when it can identify one unambiguously. OpenClaw and Hermes map to the generic `acp` connect agent. OpenClaw requires explicit real ACP Gateway settings from the current runtime; Hermes uses the `direxio-connect hermes-acp-adapter -- hermes acp` compatibility wrapper by default.
+- `DIREXIO_AGENT_PLATFORM=auto` detects the local agent runtime and maps it to a `direxio-connect` agent type only when it can identify one unambiguously. OpenClaw and Hermes map to the generic `acp` connect agent. OpenClaw uses `openclaw acp --session agent:main:main` by default and lets OpenClaw discover its Gateway config; Hermes uses the `direxio-connect hermes-acp-adapter -- hermes acp` compatibility wrapper by default.
 - `DIREXIO_LOCAL_PATH_STYLE=windows` writes Windows-compatible `data_dir`, `work_dir`, config paths, and install commands. `scripts/orchestrate.ps1` sets this automatically. Linux, macOS, and WSL Bash runs should leave the default `posix` style. Windows Git Bash/MSYS2 users who run `scripts/orchestrate.sh` directly must set `DIREXIO_LOCAL_PATH_STYLE=windows` when the local bridge is a Windows process.
 - `DIREXIO_CC_CONNECT_AGENT_CMD` writes `cmd = "<path>"` into `[projects.agent.options]`. Agent-specific forms such as `DIREXIO_CODEX_COMMAND`, `DIREXIO_CLAUDE_CODE_COMMAND`, `DIREXIO_GEMINI_COMMAND`, `DIREXIO_OPENCODE_COMMAND`, `DIREXIO_QODERCLI_COMMAND`, and `DIREXIO_OPENCLAW_COMMAND` are also accepted. For Hermes, `DIREXIO_HERMES_COMMAND` selects the child Hermes executable behind the adapter, while `DIREXIO_HERMES_ACP_ADAPTER_COMMAND` overrides the adapter command itself.
 - `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 uses `DIREXIO_OPENCLAW_ACP_URL`, `DIREXIO_OPENCLAW_ACP_TOKEN_FILE`, and `DIREXIO_OPENCLAW_ACP_SESSION` to write `--url`, `--token-file`, and `--session`. Complete OpenClaw pairing first and use the real session that should receive Direxio messages; do not guess a default session or reuse old chat output.
+- 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.
 - `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`.

package/references/tooling.md

@@ -1,21 +1,21 @@
 # Tooling By OS
 
-Prepare `bash`, `aws`, `jq`, `ssh`, `scp`, `curl`, and at least one DNS lookup
+Prepare `bash`, `node`, `aws`, `ssh`, `scp`, `curl`, and at least one DNS lookup
 tool. Always inspect first, then ask before installing or downloading.
 
 ## Detect
 
 ```bash
-command -v bash aws jq ssh scp curl
+command -v bash node aws ssh scp curl
 command -v dig nslookup getent
+node --version
 aws --version
-jq --version
 ```
 
 On Windows PowerShell:
 
 ```powershell
-Get-Command "C:\Program Files\Git\bin\bash.exe","C:\Program Files\Git\usr\bin\bash.exe",aws,jq,ssh,scp,curl,nslookup,Resolve-DnsName -ErrorAction SilentlyContinue
+Get-Command "C:\Program Files\Git\bin\bash.exe","C:\Program Files\Git\usr\bin\bash.exe",node,aws,ssh,scp,curl,nslookup,Resolve-DnsName -ErrorAction SilentlyContinue
 ```
 
 ## Windows
@@ -29,15 +29,14 @@ Common system installs:
 
 ```powershell
 winget install --id Git.Git --exact
+winget install --id OpenJS.NodeJS.LTS --exact
 winget install --id Amazon.AWSCLI --exact
-winget install --id jqlang.jq --exact
 ```
 
 Workspace-local fallback when package managers are unavailable:
 
 ```powershell
 New-Item -ItemType Directory -Force -Path .tools\bin | Out-Null
-Invoke-WebRequest -Uri https://github.com/jqlang/jq/releases/download/jq-1.7.1/jq-windows-amd64.exe -OutFile .tools\bin\jq.exe
 python -m venv .tools\awscli-venv
 .\.tools\awscli-venv\Scripts\python.exe -m pip install --upgrade pip awscli
 ```
@@ -61,7 +60,7 @@ Run ops from Git Bash:
 Preferred installs:
 
 ```bash
-brew install awscli jq
+brew install node awscli
 ```
 
 If Homebrew is unavailable, ask before using the official AWS CLI pkg installer.
@@ -72,11 +71,11 @@ macOS already includes `ssh`, `scp`, `curl`, and `dig`.
 Choose the detected package manager:
 
 ```bash
-sudo apt-get update && sudo apt-get install -y awscli jq openssh-client curl dnsutils
-sudo dnf install -y awscli jq openssh-clients curl bind-utils
-sudo yum install -y awscli jq openssh-clients curl bind-utils
-sudo pacman -Sy --needed aws-cli jq openssh curl bind-tools
-sudo zypper install -y aws-cli jq openssh-clients curl bind-utils
+sudo apt-get update && sudo apt-get install -y nodejs awscli openssh-client curl dnsutils
+sudo dnf install -y nodejs awscli openssh-clients curl bind-utils
+sudo yum install -y nodejs awscli openssh-clients curl bind-utils
+sudo pacman -Sy --needed nodejs aws-cli openssh curl bind-tools
+sudo zypper install -y nodejs aws-cli openssh-clients curl bind-utils
 ```
 
 If distro packages are too old or missing, ask before using the official AWS CLI zip installer.

package/references/user-journey.md

@@ -13,7 +13,7 @@ Confirm these items before calling `scripts/orchestrate.sh`:
 1. The final Matrix domain is selected, for example `__DOMAIN__`.
 2. The user understands that Matrix `server_name` is bound to that domain.
 3. The user has confirmed `CONFIRM_DOMAIN_BINDING=1`.
-4. AWS CLI v2, `jq`, `ssh`, `scp`, and `curl` are available.
+4. Node.js, AWS CLI v2, `ssh`, `scp`, and `curl` are available.
 5. AWS credentials are configured through `AWS_PROFILE` or environment variables.
 6. `AWS_DEFAULT_REGION` is explicit.
 7. `MESSAGE_SERVER_IMAGE` is selected, or the default `direxio/message-server:latest` is accepted.
@@ -23,7 +23,7 @@ On Windows, first verify that `bash` is a usable POSIX shell:
 
 ```powershell
 Get-Command bash.exe -All
-bash -lc 'echo ok; command -v aws; command -v jq; command -v ssh; command -v scp; command -v curl'
+bash -lc 'echo ok; command -v node; command -v aws; command -v ssh; command -v scp; command -v curl'
 ```
 
 ## Domain Modes

package/references/voip-turn-runbook.md

@@ -118,10 +118,10 @@ TURN 端口直连 coturn,Caddyfile **不加** TURN 反代。仅在文件头注
 新增一项(用 password/agent_token 换 access_token 后查 turnServer):
 ```bash
 # 换统一 access_token
-at=$(curl -sk -X POST "https://$domain/_p2p/command" -H 'Content-Type: application/json' -d "{\"action\":\"portal.auth\",\"params\":{\"password\":\"$password\"}}" | jq -r '.access_token')
+at=$(curl -sk -X POST "https://$domain/_p2p/command" -H 'Content-Type: application/json' -d "{\"action\":\"portal.auth\",\"params\":{\"password\":\"$password\"}}" | node scripts/json.mjs stdin-get access_token)
 # 查 turnServer 必须非空、有 turn: uris、有 username/password、ttl>0
 turn=$(curl -sk "https://$domain/_matrix/client/v3/voip/turnServer" -H "Authorization: Bearer $at")
-echo "$turn" | jq -e '.uris and (.uris|length>0) and (.uris[]|test("^turns?:")) and (.username!="") and (.password!="") and (.ttl>0)' >/dev/null \
+echo "$turn" | node scripts/json.mjs stdin-assert turn-credentials >/dev/null \
   && ok "  ✓ TURN turnServer 非空且有效" || { warn "  ✗ TURN turnServer 无效:$turn"; fails=$((fails+1)); }
 ```
 

package/references/windows-deployment-notes.md

@@ -30,7 +30,8 @@ When running `orchestrate.sh` as a background process, bash may buffer stdout be
 Poll progress with:
 
 ```bash
-cat ~/.direxio/nodes/<service_id>/state.json | jq '{phase, phases}'
+node scripts/json.mjs get ~/.direxio/nodes/<service_id>/state.json phase
+node scripts/json.mjs get ~/.direxio/nodes/<service_id>/state.json phases
 ```
 
 For real-time tailing, use `stdbuf` when available:

package/scripts/destroy.sh

@@ -27,20 +27,8 @@ destroy_now() {
 }
 
 destroy_evidence_set() {
-  local key=$1 status=$2 detail=${3:-} tmp
-  tmp="$SRC.tmp.destroy.$$"
-  if jq --arg key "$key" \
-        --arg status "$status" \
-        --arg detail "$detail" \
-        --arg checked_at "$(destroy_now)" \
-        '.destroy_evidence[$key] = {
-          status: $status,
-          detail: $detail,
-          checked_at: $checked_at
-        }' "$SRC" > "$tmp"; then
-    mv "$tmp" "$SRC"
-  else
-    rm -f "$tmp"
+  local key=$1 status=$2 detail=${3:-}
+  if ! json_mutate "$SRC" destroy-evidence "$key" "$status" "$detail" "$(destroy_now)"; then
     log "  (failed to record destroy evidence for $key)"
   fi
 }
@@ -48,13 +36,7 @@ destroy_evidence_set() {
 route53_a_record_present() {
   local zone_id=$1 domain=$2 public_ip=$3 rrsets present
   rrsets=$(aws route53 list-resource-record-sets --hosted-zone-id "$zone_id" --output json 2>/dev/null) || return 2
-  present=$(printf '%s\n' "$rrsets" | jq -r --arg name "$domain." --arg ip "$public_ip" '
-    any(.ResourceRecordSets[]?;
-      .Name == $name
-      and .Type == "A"
-      and any(.ResourceRecords[]?; .Value == $ip)
-    )
-  ' 2>/dev/null) || return 2
+  present=$(printf '%s\n' "$rrsets" | json_stdin_route53_a_present "$domain." "$public_ip" 2>/dev/null) || return 2
   [ "$present" = "true" ]
 }
 
@@ -187,26 +169,25 @@ fi
 [ -f "$SRC" ] || { echo "$SRC not found."; exit 1; }
 P2P_ROOT=$(cd "${DIREXIO_HOME:-$HOME/.direxio}" 2>/dev/null && pwd -P || printf '%s' "${DIREXIO_HOME:-$HOME/.direxio}")
 
-command -v jq >/dev/null 2>&1 || { echo "jq is required to parse state.json."; exit 1; }
-REGION=$(jq -r '.region // empty' "$SRC")
-INSTANCE_ID=$(jq -r '.resources.instance_id // empty' "$SRC")
-ROOT_VOLUME_ID=$(jq -r '.resources.root_volume_id // empty' "$SRC")
-EIP_ID=$(jq -r '.resources.eip_id // empty' "$SRC")
-SG_ID=$(jq -r '.resources.sg_id // empty' "$SRC")
-KEY_NAME=$(jq -r '.resources.key_name // empty' "$SRC")
-KEY_FILE=$(jq -r '.resources.key_file // empty' "$SRC")
-DOMAIN_MODE=$(jq -r '.domain_mode // empty' "$SRC")
-DOMAIN=$(jq -r '.domain // empty' "$SRC")
-AS_URL=$(jq -r '.as_url // empty' "$SRC")
-PUBLIC_IP=$(jq -r '.resources.public_ip // empty' "$SRC")
-ROUTE53_ZONE_ID=$(jq -r '.resources.route53_zone_id // empty' "$SRC")
-ROUTE53_ZONE_NAME=$(jq -r '.resources.route53_zone_name // empty' "$SRC")
-ROUTE53_ZONE_CREATED_BY_DEPLOYER=$(jq -r '.resources.route53_zone_created_by_deployer // empty' "$SRC")
-CC_CONNECT_CONFIG=$(jq -r '.cc_connect_config // empty' "$SRC")
-CC_CONNECT_BINARY=$(jq -r '.cc_connect_binary // empty' "$SRC")
-CC_CONNECT_RUNTIME_DIR=$(jq -r '.cc_connect_runtime_dir // empty' "$SRC")
-AGENT_SERVICE_DIR=$(jq -r '.agent_service_dir // empty' "$SRC")
-AGENT_SERVICE_ID=$(jq -r '.agent_service_id // empty' "$SRC")
+REGION=$(json_get "$SRC" region)
+INSTANCE_ID=$(json_get "$SRC" resources.instance_id)
+ROOT_VOLUME_ID=$(json_get "$SRC" resources.root_volume_id)
+EIP_ID=$(json_get "$SRC" resources.eip_id)
+SG_ID=$(json_get "$SRC" resources.sg_id)
+KEY_NAME=$(json_get "$SRC" resources.key_name)
+KEY_FILE=$(json_get "$SRC" resources.key_file)
+DOMAIN_MODE=$(json_get "$SRC" domain_mode)
+DOMAIN=$(json_get "$SRC" domain)
+AS_URL=$(json_get "$SRC" as_url)
+PUBLIC_IP=$(json_get "$SRC" resources.public_ip)
+ROUTE53_ZONE_ID=$(json_get "$SRC" resources.route53_zone_id)
+ROUTE53_ZONE_NAME=$(json_get "$SRC" resources.route53_zone_name)
+ROUTE53_ZONE_CREATED_BY_DEPLOYER=$(json_get "$SRC" resources.route53_zone_created_by_deployer)
+CC_CONNECT_CONFIG=$(json_get "$SRC" cc_connect_config)
+CC_CONNECT_BINARY=$(json_get "$SRC" cc_connect_binary)
+CC_CONNECT_RUNTIME_DIR=$(json_get "$SRC" cc_connect_runtime_dir)
+AGENT_SERVICE_DIR=$(json_get "$SRC" agent_service_dir)
+AGENT_SERVICE_ID=$(json_get "$SRC" agent_service_id)
 
 export NO_PROXY="*"; export no_proxy="*"
 unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy 2>/dev/null || true
@@ -240,7 +221,7 @@ find_route53_zone() {
         fi
         ;;
     esac
-  done < <(aws route53 list-hosted-zones --output json 2>/dev/null | jq -r '.HostedZones[] | [.Id, .Name] | @tsv')
+  done < <(aws route53 list-hosted-zones --output json 2>/dev/null | json_stdin_tsv HostedZones Id Name)
   [ -n "$best_id" ] && printf '%s\t%s\n' "$best_id" "$best_name"
 }
 
@@ -289,7 +270,7 @@ EOF
     || log "  (Route53 A record may already be absent or changed; check DNS manually)"
   rm -f "$change_file"
   if [ -n "${change_json:-}" ]; then
-    change_id=$(printf '%s\n' "$change_json" | jq -r '.ChangeInfo.Id // empty' 2>/dev/null)
+    change_id=$(printf '%s\n' "$change_json" | json_stdin_get ChangeInfo.Id 2>/dev/null)
     [ -n "$change_id" ] && aws route53 wait resource-record-sets-changed --id "$change_id" 2>/dev/null || true
   fi
   verify_route53_a_record_deleted "$zone_id" "$domain" "$public_ip"