direxio-deployer 0.1.0

package/references/deployment-workflow.md

@@ -0,0 +1,341 @@
+# Deployment Workflow
+
+## Preflight
+
+1. Confirm `DOMAIN`, `DOMAIN_MODE`, and `CONFIRM_DOMAIN_BINDING=1`.
+2. Confirm AWS region, credentials, billing, instance type, and costs.
+3. Check dependencies with the OS-specific commands in `tooling.md`.
+4. Check current DNS provider. Prefer `DOMAIN_MODE=route53` when the user
+   confirms AWS may manage the hosted zone and A record. Use `DOMAIN_MODE=user`
+   only as a fallback when no DNS provider automation is available.
+5. Check state:
+
+```bash
+bash scripts/orchestrate.sh status
+DOMAIN=__DOMAIN__ bash scripts/orchestrate.sh status
+```
+
+If state has resources, require one:
+
+```bash
+P2P_EXISTING_STATE_ACTION=continue
+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:
+
+```bash
+bash scripts/aws-credentials.sh import-csv /path/to/accessKeys.csv direxio-deployer <region>
+export AWS_PROFILE=direxio-deployer
+bash scripts/aws-credentials.sh verify direxio-deployer
+```
+
+Before the first mutating AWS phase, produce a monthly estimate for the selected
+region and instance size:
+
+```bash
+bash scripts/pricing-estimate.sh \
+  --region <region> \
+  --instance-type t3.small \
+  --disk-gb 8 \
+  --domain-mode user
+```
+
+When `state.json` already exists, refresh and persist the same estimate:
+
+```bash
+bash scripts/pricing-estimate.sh --state ~/.direxio/nodes/<service_id>/state.json --write-state
+```
+
+`scripts/orchestrate.sh` also writes `cost_estimate` automatically after region
+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.
+
+## Destroy
+
+From the repository root:
+
+```bash
+DOMAIN=__DOMAIN__ bash scripts/destroy.sh
+```
+
+On Windows, run destroy from PowerShell so local service paths stay in Windows
+form and the wrapper selects Git for Windows Bash instead of WSL:
+
+```powershell
+$env:DOMAIN = "__DOMAIN__"
+.\scripts\destroy.ps1
+```
+
+Destroy stops and uninstalls the local `direxio-connect` daemon only when `direxio-connect daemon status --service-name <service_id>` reports a `WorkDir` matching the current service directory, `~/.direxio/nodes/<service_id>/cc-connect`. It then terminates the recorded EC2 instance, verifies the recorded EBS root volume, releases the Elastic IP, deletes the security group and key pair, removes Route53 records/zones created by the deployer, records AWS read-back results under `destroy.evidence`, and removes the corresponding local service directory under `~/.direxio/nodes/<service_id>`. This prevents stale credentials, `state.json` files, and local service registrations from being treated as active deployments later while preserving an audit report for cleanup.
+
+Destroy allows root AWS access-key identity when the operator explicitly chose
+root credentials. Use the same deployment profile for teardown that was used
+for provisioning.
+
+Use `P2P_KEEP_WORKDIR=1 DOMAIN=__DOMAIN__ bash scripts/destroy.sh` on POSIX, or set `$env:P2P_KEEP_WORKDIR = "1"` before `.\scripts\destroy.ps1` on Windows, only when preserving local state files for debugging; if used, report that the service directory still exists.
+
+## Run
+
+From the repository root:
+
+```bash
+AWS_PROFILE=p2p-matrix \
+AWS_DEFAULT_REGION=us-east-1 \
+DOMAIN=__DOMAIN__ \
+DOMAIN_MODE=user \
+CONFIRM_DOMAIN_BINDING=1 \
+INSTANCE_TYPE=t3.small \
+MESSAGE_SERVER_IMAGE=direxio/message-server:latest \
+bash scripts/orchestrate.sh
+```
+
+Exit codes:
+
+- `0`: deployment complete.
+- `1`: phase failed; inspect logs and rerun or destroy.
+- `2`: waiting for user/external action, usually DNS or credentials.
+
+## Operation Report
+
+New deploys write a redacted machine-readable report to:
+
+```text
+~/.direxio/nodes/<service_id>/operation-report.json
+```
+
+Regenerate it from current state with:
+
+```bash
+DOMAIN=__DOMAIN__ bash scripts/orchestrate.sh report new_deploy
+```
+
+Destroy writes its audit report outside the service directory because the
+service directory is removed:
+
+```text
+~/.direxio/reports/<service_id>/operation-report.json
+```
+
+Reports include operation type, S0-S7 gate status, user-confirmation gates,
+credential/config paths, cc-connect/MCP metadata, AWS resource IDs, billing
+reminders, `billing.cost_estimate`, destroy read-back evidence under
+`destroy.evidence` when applicable, and redaction evidence. They must not
+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
+`credentials.status=refresh_pending`, `connect.install_status=refresh_pending`,
+and `mcp.status=refresh_pending` until S5/S6/S7 and runtime checks refresh
+local evidence.
+
+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. They are not the full runtime product gate:
+
+```bash
+DOMAIN=__DOMAIN__ bash scripts/orchestrate.sh verify runtime
+
+DOMAIN=__DOMAIN__ bash scripts/orchestrate.sh verify connect_daemon
+DOMAIN=__DOMAIN__ bash scripts/orchestrate.sh verify mcp_doctor
+DOMAIN=__DOMAIN__ bash scripts/orchestrate.sh verify mcp_tools
+DOMAIN=__DOMAIN__ bash scripts/orchestrate.sh verify mcp_smoke
+
+DIREXIO_CONFIRM_EVIDENCE="user completed app initialization" \
+DOMAIN=__DOMAIN__ bash scripts/orchestrate.sh confirm app_initialization
+
+DIREXIO_CONFIRM_EVIDENCE="user sent a message and saw the agent reply" \
+DOMAIN=__DOMAIN__ bash scripts/orchestrate.sh confirm real_chat
+
+DIREXIO_CONFIRM_RUNTIME_PROBE=1 \
+DIREXIO_CONFIRM_EVIDENCE="MCP doctor/tool discovery and runtime probe confirmed" \
+DOMAIN=__DOMAIN__ bash scripts/orchestrate.sh confirm agent_mcp_runtime
+
+DOMAIN=__DOMAIN__ bash scripts/orchestrate.sh report new_deploy
+```
+
+`confirm agent_mcp_runtime` refuses to write the gate until
+`runtime_checks.summary.status=passed` and `DIREXIO_CONFIRM_RUNTIME_PROBE=1`
+are both present. Use the flag only after the selected runtime/channel probe has
+actually loaded the service-scoped MCP tools; `verify runtime` alone is an
+internal non-polluting check, not the full product gate.
+All `confirm` commands require `DIREXIO_CONFIRM_EVIDENCE` with a concrete
+user/runtime evidence note; do not write user-confirmation gates with generic
+default evidence. The evidence note must be at least 12 characters; avoid
+placeholders such as `ok`, `yes`, or `done`.
+
+## Existing Node Update
+
+Update the running service image without recreating infrastructure or 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
+```
+
+`update.sh` SSHes to the recorded EC2 instance, runs Docker Compose pull/up,
+reruns `/opt/p2p/init-tokens.sh`, clears stale local secret fields, stops only
+the matching service-scoped direxio-connect daemon when its `WorkDir` matches
+this service, and marks S4-S7 pending so health, credential sync, local
+MCP/agent wiring, and final verification run again. It does not remove Docker
+volumes.
+
+## Existing Node App Data Reset
+
+Reset application data while preserving EC2, public IPv4/EIP, DNS, and Caddy
+TLS volumes:
+
+```bash
+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
+```
+
+`reset-app-data.sh` removes only `postgres-data`, `message-config`, and
+`message-data`. It must not remove `caddy-data` or `caddy-config`; losing those
+volumes can trigger certificate reissuance and Let's Encrypt rate limits. It
+stops only the matching service-scoped direxio-connect daemon when its `WorkDir`
+matches this service. After reset, treat old app users, rooms, messages,
+initialization code, access token, agent token, and agent room as stale until
+S5-S7 complete again.
+
+## S4 Bootstrap Timeout / Certificate Rate Limit Recovery
+
+When S4 fails with `healthz did not return 200 before timeout`, the most
+common cause is **Let's Encrypt certificate rate limiting** (max 5 certs per
+domain per 7 days). Caddy retries automatically with backoff, but the
+orchestration script may time out first.
+
+**How to check:**
+
+```bash
+ssh -i <keyfile> ubuntu@<public-ip> \
+  'sudo docker logs p2p-caddy-1 --tail 20 2>&1 | grep -i "rateLimit\|retry after\|429"'
+```
+
+If rate-limited, the log shows `retry after <timestamp> UTC`.
+
+**Recovery options:**
+
+1. **Wait for rate limit to expire** — Caddy retries in the background.
+   Check progress periodically:
+   ```bash
+   curl -skI https://<DOMAIN>/healthz  # returns 200 when cert is ready
+   ```
+   Once the endpoint returns 200, re-run orchestrate.sh to complete:
+   ```bash
+   P2P_EXISTING_STATE_ACTION=continue \
+   DNS_READY=1 \
+   AWS_PROFILE=p2p-matrix \
+   AWS_DEFAULT_REGION=us-east-1 \
+   DOMAIN=<DOMAIN> \
+   DOMAIN_MODE=route53 \
+   CONFIRM_DOMAIN_BINDING=1 \
+   INSTANCE_TYPE=t3.small \
+   bash scripts/orchestrate.sh
+   ```
+
+2. **Use a different domain** — If you have multiple domains, destroy the
+   current deployment and deploy on a domain without recent cert history:
+   ```bash
+   bash scripts/destroy.sh
+   ```
+   On Windows, use `.\scripts\destroy.ps1` from PowerShell.
+   Then start again with a fresh domain.
+
+3. **Force Caddy staging CA** (development only) — Set the environment
+   variable `CADDY_ACME_CA=https://acme-staging-v02.api.letsencrypt.org/directory`
+   in the compose file to get a staging certificate. Staging certs are **not
+   trusted by browsers** — use only for testing.
+
+## Route53 DNS Mode
+
+With `DOMAIN_MODE=route53`, S3 reuses a matching hosted zone or creates one,
+records the zone id and nameservers in `state.json`, upserts the A record, and
+waits for DNS to resolve.
+
+If the current Route53 A record already points to a different IP, S3 stops
+before changing DNS and records `route53_existing_a_value` plus
+`route53_pending_a_value` in state. Confirm the replacement only after checking
+that the old IP is safe to replace:
+
+```bash
+DIREXIO_CONFIRM_DNS_OVERWRITE=1 \
+P2P_EXISTING_STATE_ACTION=continue \
+DOMAIN=__DOMAIN__ \
+DOMAIN_MODE=route53 \
+CONFIRM_DOMAIN_BINDING=1 \
+bash scripts/orchestrate.sh
+```
+
+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
+```
+
+After authoritative DNS returns the new IP, continue with the same state:
+
+```bash
+P2P_EXISTING_STATE_ACTION=continue \
+DOMAIN=__DOMAIN__ \
+DOMAIN_MODE=route53 \
+CONFIRM_DOMAIN_BINDING=1 \
+bash scripts/orchestrate.sh
+```
+
+Destroy deletes deployer-created hosted zones when state records
+`route53_zone_created_by_deployer=true`; pre-existing or user-owned zones are
+left in place.
+
+## Manual DNS Mode
+
+Use manual DNS mode only when no DNS provider automation is available. When S3
+emits an Elastic IP, ask the user to set:
+
+```text
+<DOMAIN>  A  <PUBLIC_IP>
+```
+
+For Cloudflare, use DNS-only, not proxied. For Alibaba/HiChina, edit the A record in Alibaba Cloud DNS.
+
+After authoritative DNS returns the new IP:
+
+```bash
+DNS_READY=1 \
+AWS_PROFILE=p2p-matrix \
+AWS_DEFAULT_REGION=us-east-1 \
+DOMAIN=__DOMAIN__ \
+DOMAIN_MODE=user \
+CONFIRM_DOMAIN_BINDING=1 \
+INSTANCE_TYPE=t3.small \
+MESSAGE_SERVER_IMAGE=direxio/message-server:latest \
+P2P_EXISTING_STATE_ACTION=continue \
+bash scripts/orchestrate.sh
+```
+
+## Initialization Code Field
+
+Current backend delivery uses the `password` field for the user-facing eight-digit app initialization code, a unified user `access_token`, and an agent-only `agent_token`.
+
+State fields after S5:
+
+```text
+password
+agent_token
+access_token
+as_url
+```
+
+All fields are written to `~/.direxio/nodes/<service_id>/credentials.json` with mode `0600`.

package/references/iam-policy.json

@@ -0,0 +1,52 @@
+{
+  "Version": "2012-10-17",
+  "Comment": "p2p-matrix 一键部署所需的最小 IAM 权限。用户建 IAM 用户时附加此策略,再为其生成 AK/SK 交给 agent。比给 AdministratorAccess 安全得多。",
+  "Statement": [
+    {
+      "Sid": "Preflight",
+      "Effect": "Allow",
+      "Action": [
+        "sts:GetCallerIdentity",
+        "servicequotas:GetServiceQuota",
+        "ssm:GetParameters",
+        "ec2:DescribeVpcs"
+      ],
+      "Resource": "*"
+    },
+    {
+      "Sid": "EC2Deploy",
+      "Effect": "Allow",
+      "Action": [
+        "ec2:CreateKeyPair",
+        "ec2:DeleteKeyPair",
+        "ec2:CreateSecurityGroup",
+        "ec2:DeleteSecurityGroup",
+        "ec2:AuthorizeSecurityGroupIngress",
+        "ec2:RunInstances",
+        "ec2:TerminateInstances",
+        "ec2:DescribeInstances",
+        "ec2:DescribeImages",
+        "ec2:DescribeSecurityGroups",
+        "ec2:DescribeKeyPairs",
+        "ec2:CreateTags",
+        "ec2:AllocateAddress",
+        "ec2:AssociateAddress",
+        "ec2:ReleaseAddress",
+        "ec2:DescribeAddresses"
+      ],
+      "Resource": "*"
+    },
+    {
+      "Sid": "DnsOptional_仅当域名托管在Route53才需要",
+      "Effect": "Allow",
+      "Action": [
+        "route53:ListHostedZones",
+        "route53:CreateHostedZone",
+        "route53:DeleteHostedZone",
+        "route53:ChangeResourceRecordSets",
+        "route53:GetChange"
+      ],
+      "Resource": "*"
+    }
+  ]
+}

package/references/runtime-wiring.md

@@ -0,0 +1,209 @@
+# Runtime Wiring
+
+After deployment, S6 writes service-scoped files under:
+
+```text
+~/.direxio/nodes/<service_id>/
+```
+
+`service_id` is derived from the deployed service domain.
+
+## Credentials
+
+`credentials.json` keeps the backend `password` field, owner access token, agent token, and room identity. User-facing reports should call the `password` value the eight-digit app initialization code:
+
+```json
+{
+  "profiles": {
+    "default": {
+      "password": "<eight-digit-app-initialization-code>",
+      "access_token": "<owner-access-token>",
+      "agent_room_id": "__ROOM_ID__",
+      "direxio_domain": "https://__DOMAIN__",
+      "direxio_agent_token": "<agent-token>",
+      "direxio_agent_room_id": "__ROOM_ID__",
+      "direxio_agent_node_id": "__AGENT_NODE_ID__"
+    }
+  }
+}
+```
+
+Treat the synced `password` and owner `access_token` as one-time/volatile values. A successful App initialization or token exchange can reset them on the server. Before showing the eight-digit app initialization code or using an owner `access_token` for `/_p2p/command` or Matrix Client API calls, pull the current `/opt/p2p/bootstrap.json` from the server and refresh local credentials instead of using older local output.
+
+`env` contains the same service-scoped environment values for shell usage:
+
+```bash
+DIREXIO_DOMAIN=https://__DOMAIN__
+DIREXIO_AGENT_TOKEN=<agent_token>
+DIREXIO_AGENT_ROOM_ID=__ROOM_ID__
+DIREXIO_AGENT_NODE_ID=__AGENT_NODE_ID__
+```
+
+## MCP Tooling
+
+S6 writes MCP snippets under the same service directory:
+
+```text
+~/.direxio/nodes/<service_id>/mcp/
+```
+
+Generated files:
+
+- `codex.toml`: Codex TOML snippet using `[mcp_servers."<server-name>"]`.
+- `openclaw.md`: OpenClaw CLI setup note. It must use `openclaw mcp set`; do not paste MCP JSON into `~/.openclaw/openclaw.json`.
+- `openclaw-server.json`: one OpenClaw MCP server object consumed by `openclaw mcp set`.
+- `hermes.mcp.json`: Hermes JSON snippet using `mcpServers`.
+- `mcp-servers.json`: generic JSON snippet for other MCP clients.
+- `env`: shell exports for checking `direxio-mcp` manually.
+
+All snippets and setup artifacts run `direxio-mcp` over stdio and set:
+
+```bash
+DIREXIO_CREDENTIALS_FILE=~/.direxio/nodes/<service_id>/credentials.json
+DIREXIO_AGENT_NODE_ID=__AGENT_NODE_ID__
+```
+
+This is intentionally separate from the `direxio-connect` bridge. MCP uses the deployer credential file; cc-connect uses a direct Matrix Client-Server session in `cc-connect/config.toml`.
+
+Install and check the MCP package:
+
+```bash
+npm install -g direxio-mcp@latest
+DIREXIO_CREDENTIALS_FILE=~/.direxio/nodes/<service_id>/credentials.json direxio-mcp doctor --json
+```
+
+## cc-connect Matrix Bridge
+
+S6 calls `agent.matrix_session.create` with the owner token. Current message-server builds must return a Matrix session for `@agent:<server>`, not for `@owner:<server>`. The resulting session is stored at:
+
+```text
+~/.direxio/nodes/<service_id>/cc-connect/matrix-session.json
+```
+
+S6 then writes:
+
+```text
+~/.direxio/nodes/<service_id>/cc-connect/config.toml
+```
+
+The config uses:
+
+- `type = "matrix"` only.
+- `homeserver` from the deployed Direxio domain.
+- `access_token`, `device_id`, and `user_id` from `agent.matrix_session.create`.
+- `room_id` from the real backend-created `agent_room_id`.
+- `admin_from = "@owner:<server>"` at the project level, so only the portal owner can run privileged commands such as `/dir` and `/shell`.
+- `share_session_in_channel = true` and `group_reply_all = true` for agent-room conversation continuity.
+- `auto_join = false` and `auto_verify = false`; message-server creates and joins the real room.
+- `[speech]` is generated and enabled automatically when S6 can find a speech-to-text API key. Without a key, voice input is not enabled and `direxio-connect` will answer voice messages with its speech configuration warning.
+
+`/dir reset` is expected to restore the generated `work_dir` and remove the current project directory override from `cc-connect/data/projects/<project>.state.json`.
+
+## Install Parameters
+
+```bash
+DIREXIO_AGENT_PLATFORM=auto
+DIREXIO_CC_CONNECT_AGENT=<optional cc-connect agent>
+DIREXIO_AGENT_INSTALL=skip|recommend|auto
+DIREXIO_AGENT_INSTALL_MODE=recommended|cc-connect
+DIREXIO_LOCAL_PATH_STYLE=posix|windows
+DIREXIO_CC_CONNECT_AGENT_CMD=<optional agent executable path>
+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_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
+DIREXIO_CC_CONNECT_REPO=https://github.com/YingSuiAI/direxio-connect.git
+DIREXIO_MCP_NPM_PACKAGE=direxio-mcp@latest
+DIREXIO_MCP_COMMAND=direxio-mcp
+DIREXIO_SPEECH_PROVIDER=openai|groq|qwen|gemini
+DIREXIO_SPEECH_API_KEY=<optional generic STT key>
+DIREXIO_SPEECH_BASE_URL=<optional OpenAI-compatible STT base URL>
+DIREXIO_SPEECH_MODEL=<optional STT model>
+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_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.
+- `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`.
+- `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.
+
+Manual command:
+
+```bash
+npm install -g direxio-connent@latest
+direxio-connect daemon install --config ~/.direxio/nodes/<service_id>/cc-connect/config.toml --service-name <service_id> --force
+direxio-connect daemon status --service-name <service_id>
+```
+
+Source fallback:
+
+```bash
+git clone https://github.com/YingSuiAI/direxio-connect.git
+cd connect
+make build AGENTS=<cc-connect-agent> PLATFORMS_INCLUDE=matrix
+./direxio-connect daemon install --config ~/.direxio/nodes/<service_id>/cc-connect/config.toml --service-name <service_id> --force
+```
+
+## State Fields
+
+S6 records these bridge-related fields in `state.json`:
+
+```text
+agent_runtime
+agent_install_policy
+agent_install_mode
+agent_install_command
+agent_install_status
+agent_node_id
+agent_service_id
+agent_service_dir
+agent_credentials_file
+agent_env_file
+agent_workspace
+agent_skill_install_path
+agent_global_skill_install_path
+direxio_agent_bridge
+cc_connect_agent
+cc_connect_agent_cmd
+cc_connect_agent_options_toml_present
+cc_connect_npm_package
+cc_connect_repo
+cc_connect_ref
+cc_connect_source_dir
+cc_connect_runtime_dir
+cc_connect_config
+cc_connect_binary
+cc_connect_data_dir
+cc_connect_matrix_session_file
+cc_connect_matrix_user
+cc_connect_matrix_device
+cc_connect_matrix_homeserver
+mcp_npm_package
+mcp_command
+mcp_server_name
+mcp_config_dir
+mcp_credentials_file
+mcp_codex_config
+mcp_openclaw_config
+mcp_hermes_config
+mcp_json_config
+mcp_env_file
+mcp_readme
+mcp_install_command
+mcp_doctor_command
+```

package/references/state-machine.md

@@ -0,0 +1,46 @@
+# 部署状态机
+
+`scripts/orchestrate.sh` 是可续跑状态机。默认情况下，`DOMAIN=<domain>` 会把状态和本地桥接文件统一放在 `~/.direxio/nodes/<service_id>/`，状态机读取该目录下的 `state.json`，从第一个未完成阶段继续。不带 `DOMAIN` 运行 `bash scripts/orchestrate.sh status` 会扫描 `~/.direxio/nodes/*/state.json` 并列出所有本地服务。
+
+## 阶段
+
+- **S0_PREREQ_AWS**: 校验 AWS CLI、凭据和账号身份。
+- **S1_PREFLIGHT**: 校验 region、默认 VPC、vCPU 配额、Ubuntu amd64 AMI。
+- **S2_DOMAIN**: 确认正式长期域名和 Matrix `server_name` 不可逆绑定。
+- **S3_PROVISION**: 创建 EC2、密钥对、安全组、Elastic IP，按 DNS 模式处理 Route53 hosted zone/A 记录或等待外部 DNS，渲染 cloud-init。默认镜像 `MESSAGE_SERVER_IMAGE=direxio/message-server:latest`。
+- **S4_BOOTSTRAP_STACK**: 等 cloud-init 安装 Docker 并启动 `postgres:18 + message-server + caddy + coturn`，轮询 `https://<domain>/healthz`。
+- **S5_INIT_TOKENS**: SSH 读取云端 `init-tokens.sh` 生成的 `/opt/p2p/bootstrap.json`，归一化 `password`、`access_token`、`agent_token`、真实 `agent_room_id`。云端脚本会先调用 `portal.bootstrap`，并在服务端未返回房间时用 Matrix Client API 创建和回写真实 agent room。`password` 和 owner `access_token` 按一次性/易失凭据处理；需要登录或用 token 调接口前，必须重新从服务器拉取最新 `/opt/p2p/bootstrap.json`，不要复用旧输出。
+- **S6_WIRE_LOCAL**: 写本地凭据、创建 `@agent:<server>` Matrix session、写 `cc-connect/config.toml`，写 MCP 配置片段，并按策略安装或推荐 `direxio-connect`。
+- **S7_VERIFY_E2E**: 验证 `/_p2p`、Matrix versions、well-known、owner.json+CORS、TURN。
+
+## 云端 compose
+
+- `postgres`: PostgreSQL 18，数据卷 `/var/lib/postgresql`。
+- `message-init`: 生成 Direxio message-server 配置和 TURN 配置。
+- `message-server`: 运行 Matrix + P2P 统一后端，公开容器内 8008。
+- `caddy`: 对外 80/443，反代 `/_matrix/*` 和 `/_p2p/*`。
+- `coturn`: TURN relay。
+
+## 完成判据
+
+S7 自动验收通过后应交付:
+
+- App 域名: `<domain>`
+- 八位 App 初始化码: 后端 `password` 字段的当前值
+- 本地服务凭据: `~/.direxio/nodes/<service_id>/credentials.json`
+- 环境文件: `~/.direxio/nodes/<service_id>/env`
+- cc-connect 配置: `~/.direxio/nodes/<service_id>/cc-connect/config.toml`
+- MCP 配置目录: `~/.direxio/nodes/<service_id>/mcp/`
+- Matrix bridge 用户: `@agent:<server>`
+- 安装命令: `npm install -g direxio-connent@latest && direxio-connect daemon install --config <config> --service-name <service_id> --force`
+- MCP 检查命令: `DIREXIO_CREDENTIALS_FILE=<credentials.json> direxio-mcp doctor --json`
+- AWS 信息: region、instance id、Elastic IP、Route53 hosted zone、SSH 命令、state.json、destroy 命令
+- 用户确认 gates: App 初始化、消息闭环、Agent/MCP runtime 验证仍需单独记录。
+
+## 常见阻断
+
+- DNS 未指向 EIP: S3 返回 waiting。Route53 模式下先检查 hosted zone/NS 委托；manual DNS fallback 下用户或 DNS provider automation 设置 A 记录后用 `DNS_READY=1` 续跑。
+- `/healthz` 不通: 看 `/var/log/cloud-init-output.log` 和 `docker compose logs message-server`。
+- bootstrap 缺字段: 在实例上重跑 `sudo sh -lc 'cd /opt/p2p && DOMAIN=<domain> bash /opt/p2p/init-tokens.sh'`，再看宿主 `/opt/p2p/bootstrap.json` 和容器内 `/var/direxio-message-server/p2p/bootstrap.json`。
+- `agent_room_id` 缺失或是旧伪 ID: 确认 `.env` 有 `P2P_PORTAL_PASSWORD`，然后重跑 `/opt/p2p/init-tokens.sh`；脚本应创建真实 Matrix room 并回写。
+- TURN 为空: 检查 `TURN_SECRET`、coturn、安全组 3478 和 49160-49200/udp。