direxio-deployer 0.1.0

package/references/token-refresh.md

@@ -0,0 +1,81 @@
+# Token Refresh
+
+每次重部署或清空数据卷后，`password`、owner `access_token`、`agent_token` 和 cc-connect Matrix session 都会变化。状态机 S6 会自动回填；手动恢复时按这里检查。
+
+从服务端同步过来的 `password` 和 owner `access_token` 必须按一次性/易失凭据处理。`password` 是后端字段名，对用户展示时必须叫八位 App 初始化码。用户完成初始化或 token exchange 后，服务端可能立刻重置这些值；任何需要再次获取初始化码，或需要用 `access_token` 调 `/_p2p/command`、Matrix Client API 等接口的操作，都必须先重新从服务器拉取最新 `/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` 重新写入当前证据。
+
+## 远端凭据
+
+EC2 机器内 `/opt/p2p/bootstrap.json`:
+
+```json
+{
+  "version": 1,
+  "owner_user_id": "__OWNER_USER_ID__",
+  "user_id": "__OWNER_USER_ID__",
+  "homeserver": "https://__DOMAIN__",
+  "access_token": "<ACCESS_TOKEN>",
+  "agent_token": "<AGENT_TOKEN>",
+  "password": "<APP_INITIALIZATION_CODE>",
+  "agent_room_id": "__ROOM_ID__"
+}
+```
+
+取回:
+
+```bash
+ssh -i <key.pem> ubuntu@<ip> 'sudo cat /opt/p2p/bootstrap.json' > bootstrap.json
+```
+
+如果刚执行过 App 初始化、`portal.auth`、手动接口调用、S5/S6 重跑，或者不确定本地凭据是否最新，先执行上面的取回命令，再读取 `password` 字段对应的八位初始化码或 `access_token`。
+
+## 本地服务凭据
+
+`~/.direxio/nodes/<service_id>/credentials.json`:
+
+```json
+{
+  "profiles": {
+    "default": {
+      "password": "<APP_INITIALIZATION_CODE>",
+      "access_token": "<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>"
+    }
+  }
+}
+```
+
+权限必须是 `0600`:
+
+```bash
+chmod 600 ~/.direxio/nodes/<service_id>/credentials.json
+```
+
+S6 也会写：
+
+```text
+~/.direxio/nodes/<service_id>/env
+~/.direxio/nodes/<service_id>/cc-connect/matrix-session.json
+~/.direxio/nodes/<service_id>/cc-connect/config.toml
+```
+
+刷新后重新安装或重启本地 bridge：
+
+```bash
+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>
+```
+
+## 验证
+
+```bash
+curl -skf https://<domain>/healthz && echo OK
+curl -sk https://<domain>/.well-known/portal/owner.json
+curl -sk https://<domain>/_matrix/client/versions
+```

package/references/tooling.md

@@ -0,0 +1,106 @@
+# Tooling By OS
+
+Prepare `bash`, `aws`, `jq`, `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 dig nslookup getent
+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
+```
+
+## Windows
+
+Preferred shell: Git Bash, MSYS2, Cygwin, or a working WSL distro. Do not use `C:\Windows\System32\bash.exe` unless `bash -lc 'echo ok'` succeeds.
+
+Standard Git Bash usually does not include `dig`. Use Windows `Resolve-DnsName`
+or `nslookup` for DNS checks instead of blocking deployment on `dig`.
+
+Common system installs:
+
+```powershell
+winget install --id Git.Git --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
+```
+
+Create `.tools/bin/aws` for Git Bash:
+
+```bash
+#!/usr/bin/env bash
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+exec "$SCRIPT_DIR/../awscli-venv/Scripts/python.exe" -m awscli "$@"
+```
+
+Run ops from Git Bash:
+
+```powershell
+& "C:\Program Files\Git\bin\bash.exe" -lc 'PATH="$PWD/.tools/bin:$PATH"; bash scripts/orchestrate.sh'
+```
+
+## macOS
+
+Preferred installs:
+
+```bash
+brew install awscli jq
+```
+
+If Homebrew is unavailable, ask before using the official AWS CLI pkg installer.
+macOS already includes `ssh`, `scp`, `curl`, and `dig`.
+
+## Linux
+
+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
+```
+
+If distro packages are too old or missing, ask before using the official AWS CLI zip installer.
+
+## Credentials
+
+Prefer a temporary `DirexioDeployer` IAM user or role. 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`:
+
+```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
+```
+
+Existing profiles can still be used, including root profiles when the operator
+explicitly chooses root credentials:
+
+```bash
+aws configure --profile p2p-matrix
+export AWS_PROFILE=p2p-matrix
+export AWS_DEFAULT_REGION=us-east-1
+aws sts get-caller-identity
+```
+
+Never print secrets or commit them.

package/references/troubleshooting.md

@@ -0,0 +1,26 @@
+# Troubleshooting
+
+## cc-connect Bridge
+
+- `agent_room_id` must be a real Matrix room id beginning with `!`. Values like `!agent:<domain>` are legacy pseudo ids and must be fixed by redeploying or restarting a current message-server build.
+- Current message-server images require `P2P_PORTAL_PASSWORD` and an explicit `portal.bootstrap` call. The cloud `init-tokens.sh` script is responsible for that call and for creating a real Matrix agent room when the backend credentials file does not already include `agent_room_id`.
+- `agent.matrix_session.create` must return `@agent:<server>`. If it returns `@owner:<server>`, deploy a message-server build that includes agent Matrix session support.
+- `cc-connect/config.toml` must contain one Matrix platform and the same `room_id` as S5/S6 state.
+- `direxio-connect daemon status --service-name <service_id>` checks the local bridge process for the current Direxio node. If no daemon is installed, run the command printed in S6 state `agent_install_command`.
+- If npm install fails, verify `npm view direxio-connent` and that the GitHub release contains the matching `direxio-connect` binary asset.
+
+## Matrix Checks
+
+The deployed homeserver should answer:
+
+```bash
+curl -k https://<domain>/_matrix/client/versions
+```
+
+The local bridge should use the Matrix session file at:
+
+```text
+~/.direxio/nodes/<service_id>/cc-connect/matrix-session.json
+```
+
+Do not hand-edit the access token unless S6 cannot create a session; rerun S6 after refreshing server credentials.

package/references/user-journey.md

@@ -0,0 +1,75 @@
+# Operator Journey
+
+This document is the operator-facing reference for the deployment journey described in the root `SKILL.md`.
+
+The important policy is simple:
+
+> Direxio deployments require a real, long-lived domain before infrastructure is created.
+
+## Before Running Ops
+
+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.
+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.
+8. Existing state handling is explicit: continue, destroy, or new workdir.
+
+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'
+```
+
+## Domain Modes
+
+| Mode | Meaning | DNS behavior |
+|---|---|---|
+| `route53` | User authorizes AWS Route53 automation | S3 reuses or creates the hosted zone, records NS, upserts the A record, and waits for DNS to resolve |
+| `user` | Fallback when no DNS provider automation is available | S3 emits the EIP and waits until the domain A record resolves to it |
+
+## Minimal Command
+
+```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
+```
+
+## Token Initialization
+
+S5 reads `/opt/p2p/bootstrap.json` from the instance. Current message-server builds initialize on startup and write the backend `password` field plus owner, Matrix, and agent tokens. User-facing delivery should call `password` the eight-digit app initialization code.
+
+## Delivery
+
+When all phases complete, report:
+
+- App domain
+- eight-digit app initialization code, sourced from the backend `password` field
+- `access_token`, `agent_token`, and real `agent_room_id` in local credentials
+- local node credential file status
+- persisted `DIREXIO_DOMAIN`, `DIREXIO_AGENT_TOKEN`, `DIREXIO_AGENT_ROOM_ID`, `DIREXIO_AGENT_NODE_ID`
+- `cc_connect_config`, `cc_connect_matrix_user`, `cc_connect_matrix_device`, and `cc_connect_matrix_homeserver`
+- install policy/mode/status from `DIREXIO_AGENT_INSTALL` and `DIREXIO_AGENT_INSTALL_MODE`
+- manual command: `npm install -g direxio-connent@latest && direxio-connect daemon install --config <cc_connect_config> --service-name <service_id> --force`
+- region, instance ID, public IP, and `state.json` path
+- SSH command
+- stop-billing guidance: ask the agent to destroy this node when finished
+- which gates are automated and which still need user confirmation, because S7 green is not the final product-complete state
+
+After delivery, verify the local bridge by checking `direxio-connect daemon status --service-name <service_id>` when installed, or by running the recorded `agent_install_command` if the policy was `recommend`.
+
+Destroying AWS resources removes deployer-created Route53 A records and
+attempts to delete hosted zones that state marks as deployer-created. It does
+not remove registered domains, third-party DNS records, or user-owned hosted
+zones.

package/references/verification-recovery.md

@@ -0,0 +1,84 @@
+# Verification And Recovery
+
+## Fresh Verification
+
+Run the built-in acceptance phase through the state machine:
+
+```bash
+bash scripts/orchestrate.sh status
+```
+
+Complete state shows `current: DONE` and S0-S7 as `done`.
+
+The status command also prints a `Recovery summary`. When `current` is not
+`DONE`, use that summary as the user-facing explanation instead of exposing only
+raw phase names. It covers:
+
+- where the deployment is blocked;
+- whether recorded EC2, public IPv4/EIP, or EBS resources may still be billing;
+- whether it is safe to rerun or must continue with preserved `state.json`;
+- the next action for the current phase;
+- stop-loss guidance through destroy when resources exist.
+
+Independent checks:
+
+```bash
+curl -fsS https://<DOMAIN>/healthz
+curl -fsS https://<DOMAIN>/_matrix/client/versions
+curl -fsS https://<DOMAIN>/.well-known/matrix/server
+curl -fsS https://<DOMAIN>/.well-known/portal/owner.json
+```
+
+If local DNS lags but authoritative DNS is correct, use:
+
+```bash
+curl --resolve <DOMAIN>:443:<PUBLIC_IP> -fsS https://<DOMAIN>/healthz
+```
+
+## Common Waiting Points
+
+- S0 waits for valid AWS credentials.
+- S1 waits for default VPC, EC2 quota, or AMI availability.
+- S3 waits for DNS A record.
+- S4 waits for Docker/image pulls/Caddy certificate issuance.
+- S5 waits for `/opt/p2p/bootstrap.json` and password/agent_token extraction.
+
+Rerun the same command after fixing the blocker; state resumes from the first unfinished phase.
+
+After S3, do not reset or delete state just to silence an error. If EC2, public
+IPv4/EIP, or other AWS resources are recorded, preserve `state.json`, repair the
+blocker, and rerun with `P2P_EXISTING_STATE_ACTION=continue`; or destroy first
+if the user wants to stop billing.
+
+## Destroy
+
+Destroy recorded AWS resources while state exists:
+
+```bash
+DOMAIN=__DOMAIN__ bash scripts/destroy.sh
+```
+
+Destroy stops and uninstalls the local `direxio-connect` daemon only when its reported `WorkDir` matches the current service's `~/.direxio/nodes/<service_id>/cc-connect` directory. It then cleans recorded EC2, EBS root volume, EIP, key pair, security group, Route53 records/zones created by the deployer, and current service directory best-effort. Before removing local state, it records AWS read-back cleanup evidence under `destroy.evidence`. User-managed DNS records and purchased domains remain the user's responsibility.
+
+After destroy, read the redacted audit report at:
+
+```text
+~/.direxio/reports/<service_id>/operation-report.json
+```
+
+Use it to report which recorded AWS resources were processed, which AWS
+read-back checks show released or deleted resources, and which external items
+remain outside automatic destroy scope.
+
+## Update / Reset Follow-Up
+
+After `scripts/update.sh` or `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
+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.

package/references/voip-turn-runbook.md

@@ -0,0 +1,154 @@
+# VoIP / TURN relay 部署方案(已落地)
+
+> 来源:飞书《20260603 - VoIP 通话连接缺口》。**已按决策实现**:方案 A 自建 coturn、第一版仅明文 `turn:3478`(udp+tcp,不上 TLS)、UDP relay 收窄 `49160-49200`。代码见 PR `feat/voip-turn-coturn`。
+> ⚠️ VoIP 专项验收的硬标准:真机互拨一通,WebRTC internals 看到 **relay** ICE candidate(S7 的 turnServer 非空只是必要条件)。基础部署验收只要求 S7 `turnServer` 自动检测通过,不要求用户每次真实打电话。
+>
+> 缺口结论:Matrix 通话信令(`m.call.*`)已互通,但 `/_matrix/client/v3/voip/turnServer` 返回 `{}`,
+> ICE 只有 host/srflx 没有 relay → 跨 NAT/防火墙通话必失败。**纯后端缺口,非前端。**
+> 责任方:**只有 ops 部署 skill**(agent / AS / client 都不涉及 TURN)。
+
+---
+
+## 一、TURN 方案决策(已采用 A)
+
+### 方案 A:VPS 上自建 coturn(已落地)
+compose 加一个 `coturn` 容器;Dendrite 用 **shared-secret 模式**让 `/voip/turnServer` 动态签发短期 credentials。
+
+| 维度 | 说明 |
+|---|---|
+| 自包含 | ✅ 只给一把 AWS key 就能起,零外部账号、零额外月费 —— 契合 skill 定位 |
+| 动态凭证 | ✅ shared-secret 模式 = homeserver 按 ttl 现签,满足文档"短期有效/动态签发"要求 |
+| 成本 | ✅ 不额外花钱(复用同一台 EC2;TURN relay 流量走该机带宽) |
+| 代价 | ⚠️ 要在安全组开 TURN 端口(含一段 UDP relay 范围);coturn 容器要拿公网 IP 作 external-ip |
+| 改动量 | 8 处(见第三节) |
+
+### 备选方案 B:接外部 TURN 服务商(未采用)
+skill 不部署 coturn,只把服务商给的 `uris + username/password` 写进 Dendrite turn 段。
+
+| 维度 | 说明 |
+|---|---|
+| 运维 | ✅ 最省心,relay 由服务商扛,不用开 UDP 端口 |
+| 自包含 | ❌ 破坏"只给一把 AWS key"——需额外注册服务商、拿密钥 |
+| 成本 | ⚠️ 可能按流量计费(Twilio)或有额度上限(Cloudflare 免费档) |
+| 动态凭证 | ⚠️ 多数服务商也支持短期凭证,但要 skill 去调它的签发 API,反而更复杂 |
+| 改动量 | 少(只改 Dendrite turn 段 + S7 验收),但多一份"用户要准备的外部凭证" |
+
+**最终采用方案 A**。理由:这个 skill 的核心卖点是 AWS 内自包含部署;B 会引入新的外部服务商注册和密钥准备。A 的唯一代价是多开几个端口,并已通过收窄 UDP relay 范围把暴露面压到最小。
+
+---
+
+## 二、端口规划(按你的选择:收窄固定 UDP 范围)
+
+| 端口 | 协议 | 用途 | 是否对公网 |
+|---|---|---|---|
+| 3478 | udp + tcp | TURN/STUN 主端口 | ✅ 安全组放行 |
+| **49160–49200** | udp | relay 媒体端口(**收窄固定范围**,~40 个) | ✅ 放行这一段 |
+
+> 收窄范围够小规模 1:1 通话用;并发高时再调宽。coturn 用 `min-port/max-port` 锁这段,安全组只开这段。
+> Caddy **不**代理 TURN(UDP 走不了 Caddy);coturn 端口直接暴露在主机网络。
+
+---
+
+## 三、8 处改动(具体代码片段,方案 A)
+
+### 1. `scripts/cloud-init/docker-compose.yml` — 加 coturn 服务
+```yaml
+  # ── coturn (TURN relay,WebRTC 通话必需) ──────────────────────────
+  # 用 host 网络以正确处理 UDP relay 与 external-ip(容器 NAT 会破坏 relay)。
+  # DOMAIN/PUBLIC_IP/TURN_SECRET 由 .env 注入(user-data 写)。
+  coturn:
+    image: coturn/coturn:latest
+    network_mode: host          # relay 必须;不要放进 p2p-net 桥接网络
+    restart: unless-stopped
+    command:
+      - -n
+      - --realm=${DOMAIN}
+      - --listening-port=3478
+      - --min-port=49160
+      - --max-port=49200
+      - --external-ip=${PUBLIC_IP}
+      - --use-auth-secret
+      - --static-auth-secret=${TURN_SECRET}
+      - --no-cli
+      - --no-multicast-peers
+      - --no-tls
+      - --no-dtls
+```
+> 注:`network_mode: host` 与现有 `networks: [p2p-net]` 不兼容,coturn 单独用 host 网络。
+> 其余服务不变。
+
+### 2. `phases/s3_provision.sh` — 安全组加 TURN 端口
+把现有 `for p in 22 80 443` 段扩展:
+```bash
+# 基础:SSH/HTTP/HTTPS
+for p in 22 80 443; do
+  aws ec2 authorize-security-group-ingress --group-id "$sg" --protocol tcp --port "$p" --cidr 0.0.0.0/0 >/dev/null
+done
+# TURN:3478 udp+tcp
+aws ec2 authorize-security-group-ingress --group-id "$sg" --protocol tcp --port 3478 --cidr 0.0.0.0/0 >/dev/null
+aws ec2 authorize-security-group-ingress --group-id "$sg" --protocol udp --port 3478 --cidr 0.0.0.0/0 >/dev/null
+# TURN relay UDP 收窄范围 49160-49200
+aws ec2 authorize-security-group-ingress --group-id "$sg" --protocol udp --port 49160-49200 --cidr 0.0.0.0/0 >/dev/null
+```
+注释同步从"仅 22/80/443"改成"22/80/443 + TURN(3478 + 49160-49200/udp)"。
+
+### 3. `scripts/cloud-init/user-data.yaml` — 注入 PUBLIC_IP / TURN_SECRET 到 .env
+在 cloud-init 的 IMDS 取公网 IP 那步顺便落 `PUBLIC_IP`;再生成一个随机 `TURN_SECRET`:
+```bash
+# 已有:IP=$(curl ... public-ipv4)
+echo "PUBLIC_IP=$IP" >> /opt/p2p/.env
+# TURN 共享密钥(随机,homeserver 与 coturn 共用)
+echo "TURN_SECRET=$(head -c 32 /dev/urandom | base64 | tr -d '/+=' | head -c 40)" >> /opt/p2p/.env
+```
+> 注:custom 域名模式下 PUBLIC_IP 取不到 IMDS 也能用 `curl ifconfig.me` 兜底;或由 deploy 端注入。
+
+### 4. compose 的 message-server init — 追加 turn 段(让 turnServer 非空)
+照现有 `printf ... >> $$CFG` 的模式,在 app_service_api 之后再追加:
+```sh
+        # TURN:与 coturn 共用 static-auth-secret,Dendrite 按 ttl 动态签 credentials
+        printf '\nclient_api:\n  turn:\n    turn_shared_secret: "%s"\n    turn_user_lifetime: "24h"\n    turn_uris:\n      - "turn:%s:3478?transport=udp"\n      - "turn:%s:3478?transport=tcp"\n' "$$TURN_SECRET" "${DOMAIN}" "${DOMAIN}" >> "$$CFG"
+```
+> message-server init 需要 `TURN_SECRET` 环境变量(从 .env 传入 `environment:`)。
+> turn_uris 用 `${DOMAIN}`(正式域名),解析到公网 IP,coturn 在那监听。
+
+### 5. `scripts/cloud-init/Caddyfile` — 不动(确认 TURN 不走 Caddy)
+TURN 端口直连 coturn,Caddyfile **不加** TURN 反代。仅在文件头注释说明"TURN 由 coturn 直接暴露,不经 Caddy"。
+
+### 6. `phases/s7_verify_e2e.sh` — 加 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')
+# 查 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 \
+  && ok "  ✓ TURN turnServer 非空且有效" || { warn "  ✗ TURN turnServer 无效:$turn"; fails=$((fails+1)); }
+```
+
+### 7. `references/troubleshooting.md` — 加 TURN 排查
+新增条目:
+- **症状**:通话一直"正在连接"→"连接失败"。
+- **查**:`/_matrix/client/v3/voip/turnServer` 是否返回 `{}`;coturn 容器是否在跑(`docker compose ps`);安全组 3478/49160-49200 是否放行;`docker logs coturn` 看有没有 relay 分配。
+- **修**:turn 段没追加 → 看 message-server init;端口没开 → 看 s3 安全组;external-ip 错 → 看 .env PUBLIC_IP。
+
+### 8. `references/bug-history.md` + root `SKILL.md` — 记一笔"别再丢 VoIP"
+- bug-history 加:"VoIP 通话连不上 = 没 TURN relay。已加 coturn + Dendrite shared-secret turn 段 + 安全组 TURN 端口。重部署勿删。"
+- deployer skill 关键设计加一行:"**TURN/coturn 是通话必需**,compose 含 coturn、安全组开 3478/49160-49200,别为简化删掉。"
+
+---
+
+## 四、验收(文档给的标准,落到 S7 + 人工)
+
+**自动(S7)**:`/_matrix/client/v3/voip/turnServer` 返回非空 + uris 含 `turn:` + username/password 非空 + ttl>0。
+
+**人工(浏览器)**:Alice/Bob 互拨语音/视频 → 从"正在连接"进"通话中" → WebRTC internals 看到 **relay** ICE candidate → 挂断后 timeline 有通话系统消息(`m.call.candidates` 等技术信令不应当普通聊天显示)。
+
+---
+
+## 五、当前状态与剩余验收
+
+1. 方案 A 已落地到部署 skill,第一版只跑明文 `turn:3478`(udp+tcp),不上 `turns:5349`。
+2. 自动验收已进入 S7:能防止重部署后 `turnServer` 再次变成 `{}`。
+3. 基础部署验收只阻塞在 S7 `turnServer` 非空/有效;真正的媒体链路属于 VoIP 专项验收,仍需 Alice/Bob 真机互拨,并在 WebRTC internals 看到 `relay` ICE candidate。
+
+> agent 项目:**这件事无需改动**(已核实它与 TURN/通话无关)。

package/references/windows-deployment-notes.md

@@ -0,0 +1,119 @@
+# Windows Deployment Notes
+
+Tested on Windows 10+ with Git Bash / MSYS2. These notes capture quirks that differ from Linux/macOS deployments.
+
+## Entry Point
+
+Use the PowerShell wrapper from the repository root:
+
+```powershell
+.\scripts\orchestrate.ps1 status
+.\scripts\orchestrate.ps1
+.\scripts\destroy.ps1
+```
+
+The wrappers find Git for Windows Bash and use it for the Bash state machine, but set `DIREXIO_LOCAL_PATH_STYLE=windows` so S6 writes Windows-compatible `direxio-connect` config paths and daemon install commands. Use these PowerShell entrypoints on Windows instead of WSL Bash unless you intentionally deployed from WSL and want WSL-owned local paths.
+
+Destroy can use `DOMAIN` or an explicit Windows state path:
+
+```powershell
+$env:DOMAIN = "__DOMAIN__"
+.\scripts\destroy.ps1
+
+.\scripts\destroy.ps1 "$env:USERPROFILE\.direxio\nodes\<service_id>\state.json"
+```
+
+## Background Process Output Buffering
+
+When running `orchestrate.sh` as a background process, bash may buffer stdout because it is not connected to a terminal. The process still writes state to `~/.direxio/nodes/<service_id>/state.json`.
+
+Poll progress with:
+
+```bash
+cat ~/.direxio/nodes/<service_id>/state.json | jq '{phase, phases}'
+```
+
+For real-time tailing, use `stdbuf` when available:
+
+```bash
+stdbuf -oL bash scripts/orchestrate.sh 2>&1
+```
+
+## DNS Diagnostics
+
+- `dig` is not always available in Git Bash. Use `nslookup` or Route53 API output.
+- Chinese locale can garble `nslookup` text; DNS resolution still works.
+- When local DNS cache is stale but the record is correct, pin the IP:
+
+```bash
+curl -sk --resolve __DOMAIN__:443:__EIP__ https://__DOMAIN__/healthz
+```
+
+## AWS Proxy Bypass
+
+`lib/aws.sh` sets `NO_PROXY=*` and unsets proxy variables for AWS CLI calls. If AWS still fails with proxy errors, check:
+
+```bash
+echo "HTTP_PROXY=$HTTP_PROXY"
+echo "HTTPS_PROXY=$HTTPS_PROXY"
+cat ~/.aws/config
+```
+
+## Reading AWS Credential CSVs
+
+Windows terminal output may redact AWS keys. If a CSV appears truncated in output, read it without printing secrets and configure AWS CLI directly. Never print or log credential values.
+
+## Runtime Detection
+
+S6 checks active runtime signals before historical config directories. If detection is ambiguous on Windows, set:
+
+```bash
+DIREXIO_CC_CONNECT_AGENT=claudecode
+```
+
+or another supported connent/connect agent before running `scripts/orchestrate.sh`. Supported bridge agents are `acp`, `antigravity`, `claudecode`, `codex`, `copilot`, `cursor`, `devin`, `gemini`, `iflow`, `kimi`, `opencode`, `pi`, `qoder`, `reasonix`, and `tmux`.
+
+## direxio-connect
+
+The npm path is the default local install:
+
+```bash
+npm install -g direxio-connent@latest
+direxio-connect daemon install --config "$HOME/.direxio/nodes/<service_id>/cc-connect/config.toml" --service-name <service_id> --force
+direxio-connect daemon status --service-name <service_id>
+```
+
+If the command is not found after install, check the npm global bin directory:
+
+```bash
+npm bin -g
+```
+
+If an agent executable cannot be spawned from PATH, set a generic or agent-specific command before running S6:
+
+```powershell
+$env:DIREXIO_CC_CONNECT_AGENT = "gemini"
+$env:DIREXIO_GEMINI_COMMAND = "C:\Tools\gemini.cmd"
+```
+
+For Codex Desktop, the wrapper also tries to find the real bundled `codex.exe` because WindowsApps aliases cannot always be spawned by child processes:
+
+```powershell
+$codex = Get-ChildItem (Join-Path $env:LOCALAPPDATA 'OpenAI\Codex\bin') -Filter codex.exe -Recurse |
+  Select-Object -First 1 -ExpandProperty FullName
+$env:DIREXIO_CODEX_COMMAND = $codex
+```
+
+Use the Git Bash `$HOME` path for files generated by the deployer. If running `direxio-connect` from PowerShell, translate the config path to the Windows user profile path.
+
+## EC2 SSH Key Paths
+
+SSH key files are written with Windows-compatible paths such as `C:/Users/.../.direxio/deploy/p2p-*.pem`. The SSH command printed in the delivery summary works in Git Bash. If using PowerShell or cmd, convert forward slashes to backslashes.
+
+## Verifying Deployment
+
+The Matrix endpoint returns HTTP 200 when the service is healthy:
+
+```bash
+curl -sk https://<domain>/_matrix/client/versions
+```