direxio-deployer 0.1.0

package/agents/README.md

@@ -0,0 +1,25 @@
+# Agent Runtime Notes
+
+This skill is runtime-neutral. Claude, Codex/OpenAI, Gemini, Cursor, Copilot, OpenClaw, Hermes, and other shell-capable agents should use the same root entrypoint:
+
+```text
+SKILL.md
+```
+
+When an agent runtime supports skill metadata, point it at `SKILL.md` and use `scripts/orchestrate.sh` as the deployment command. Read `references/agent-targets.md` before installing this skill or wiring MCP/plugin access for a runtime. S6 writes current Direxio MCP/plugin variables and records the detected runtime plus target paths. After deployment, ask the user before installing or configuring the runtime-specific plugin and MCP service.
+
+Recognition keywords:
+
+- deploy P2P-IM Matrix
+- resume P2P Matrix deployment
+- verify P2P Matrix server
+- destroy P2P Matrix AWS resources
+- wire Direxio MCP/plugin
+- refresh P2P agent token
+
+Required capabilities:
+
+- Read local files.
+- Run POSIX shell commands.
+- Use `aws`, `jq`, `ssh`, `scp`, and `curl` after the user approves any missing installs.
+- Preserve secrets outside the repository.

package/agents/openai.yaml

@@ -0,0 +1,12 @@
+display_name: Direxio Deployer
+short_description: Deploy, resume, verify, destroy, and wire Direxio MCP/plugin access for a production P2P-IM Matrix server on AWS.
+default_prompt: Deploy a P2P-IM Matrix server using my production domain, following SKILL.md and scripts/orchestrate.sh.
+entrypoint: ../SKILL.md
+runtime_notes:
+  - Read SKILL.md before running deployment commands.
+  - When installing or updating this skill itself, read references/agent-targets.md and use the runtime-specific project-local Git clone path before any global fallback.
+  - Use scripts/orchestrate.sh from the repository root.
+  - Use scripts/destroy.sh for teardown.
+  - S6 writes DIREXIO_DOMAIN, DIREXIO_AGENT_TOKEN, and DIREXIO_AGENT_ROOM_ID, then records runtime-specific skill and MCP/config targets for direxio-mcp and P2P-IM/direxio-agent-plugins.
+  - Ask before mutating the current agent runtime's plugin or MCP configuration.
+  - The instructions are compatible with Claude, Codex/OpenAI, Gemini, Cursor, Copilot, OpenClaw, Hermes, and other shell-capable agent runtimes.

package/bin/direxio-deployer.mjs

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const packageJson = JSON.parse(readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+const packageName = packageJson.name || "direxio-deployer";
+const packageVersion = packageJson.version || "0.0.0";
+
+const skillFiles = [
+  "AGENTS.md",
+  "LICENSE",
+  "README.md",
+  "README_zh.md",
+  "SKILL.md",
+  "agents",
+  "bin",
+  "package.json",
+  "references",
+  "scripts",
+  "tests"
+];
+
+const projectTargets = {
+  acp: [".agents", "skills", "direxio-deployer"],
+  antigravity: [".antigravity", "skills", "direxio-deployer"],
+  claudecode: [".claude", "skills", "direxio-deployer"],
+  codex: [".codex", "skills", "direxio-deployer"],
+  copilot: [".github", "copilot", "skills", "direxio-deployer"],
+  cursor: [".cursor", "skills", "direxio-deployer"],
+  devin: [".devin", "skills", "direxio-deployer"],
+  gemini: [".gemini", "skills", "direxio-deployer"],
+  hermes: [".hermes", "skills", "direxio-deployer"],
+  iflow: [".iflow", "skills", "direxio-deployer"],
+  kimi: [".kimi", "skills", "direxio-deployer"],
+  opencode: [".opencode", "skills", "direxio-deployer"],
+  openclaw: [".openclaw", "skills", "direxio-deployer"],
+  pi: [".pi", "agent", "skills", "direxio-deployer"],
+  qoder: [".qoder", "skills", "direxio-deployer"],
+  reasonix: [".reasonix", "skills", "direxio-deployer"],
+  tmux: [".agent", "skills", "direxio-deployer"],
+  generic: [".agent", "skills", "direxio-deployer"],
+  unknown: [".agent", "skills", "direxio-deployer"]
+};
+
+const globalTargets = {
+  acp: { env: null, defaultSegments: [".agents", "skills", "direxio-deployer"] },
+  antigravity: { env: "ANTIGRAVITY_HOME", defaultSegments: [".antigravity", "skills", "direxio-deployer"], envSuffix: ["skills", "direxio-deployer"] },
+  claudecode: { env: "CLAUDE_HOME", defaultSegments: [".claude", "skills", "direxio-deployer"], envSuffix: ["skills", "direxio-deployer"] },
+  codex: { env: "CODEX_HOME", defaultSegments: [".codex", "skills", "direxio-deployer"], envSuffix: ["skills", "direxio-deployer"] },
+  copilot: { env: null, defaultSegments: [".github", "copilot", "skills", "direxio-deployer"] },
+  cursor: { env: "CURSOR_HOME", defaultSegments: [".cursor", "skills", "direxio-deployer"], envSuffix: ["skills", "direxio-deployer"] },
+  devin: { env: "DEVIN_HOME", defaultSegments: [".devin", "skills", "direxio-deployer"], envSuffix: ["skills", "direxio-deployer"] },
+  gemini: { env: "GEMINI_HOME", defaultSegments: [".gemini", "skills", "direxio-deployer"], envSuffix: ["skills", "direxio-deployer"] },
+  hermes: { env: "HERMES_HOME", defaultSegments: [".hermes", "skills", "direxio-deployer"], envSuffix: ["skills", "direxio-deployer"] },
+  iflow: { env: "IFLOW_HOME", defaultSegments: [".iflow", "skills", "direxio-deployer"], envSuffix: ["skills", "direxio-deployer"] },
+  kimi: { env: "KIMI_HOME", defaultSegments: [".kimi", "skills", "direxio-deployer"], envSuffix: ["skills", "direxio-deployer"] },
+  opencode: { env: "OPENCODE_HOME", defaultSegments: [".opencode", "skills", "direxio-deployer"], envSuffix: ["skills", "direxio-deployer"] },
+  openclaw: { env: "OPENCLAW_HOME", defaultSegments: [".openclaw", "skills", "direxio-deployer"], envSuffix: ["skills", "direxio-deployer"] },
+  pi: { env: "PI_CODING_AGENT_DIR", defaultSegments: [".pi", "agent", "skills", "direxio-deployer"], envSuffix: ["skills", "direxio-deployer"] },
+  qoder: { env: "QODER_HOME", defaultSegments: [".qoder", "skills", "direxio-deployer"], envSuffix: ["skills", "direxio-deployer"] },
+  reasonix: { env: "REASONIX_HOME", defaultSegments: [".reasonix", "skills", "direxio-deployer"], envSuffix: ["skills", "direxio-deployer"] },
+  tmux: { env: null, defaultSegments: [".agent", "skills", "direxio-deployer"] },
+  generic: { env: null, defaultSegments: [".agent", "skills", "direxio-deployer"] },
+  unknown: { env: null, defaultSegments: [".agent", "skills", "direxio-deployer"] }
+};
+
+const aliases = {
+  "claude": "claudecode",
+  "claude-code": "claudecode",
+  "open-code": "opencode",
+  "qodercli": "qoder",
+  "agy": "antigravity"
+};
+
+main();
+
+function main() {
+  const [area, command, ...rawArgs] = process.argv.slice(2);
+  if (!area || area === "--help" || area === "-h") usage(0);
+  if (area === "--version" || area === "-v") {
+    console.log(packageVersion);
+    return;
+  }
+  if (area !== "skill") usage(1);
+  if (!["install", "update", "refresh"].includes(command)) usage(1);
+
+  const options = parseArgs(rawArgs);
+  const result = runSkillCommand(command, options);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+function usage(exitCode) {
+  const output = `Usage:
+  direxio-deployer skill install --agent <runtime> [--scope project|global] [--project <path>]
+  direxio-deployer skill update --agent <runtime> [--scope project|global] [--project <path>]
+  direxio-deployer skill refresh --agent <runtime> [--scope project|global] [--project <path>]
+
+Options:
+  --agent <runtime>   Target agent runtime. Default: codex
+  --scope <scope>     project or global. Default: project
+  --project <path>    Project root for project installs. Default: current directory
+  --target <path>     Explicit install target override
+  --home <path>       Home directory override for global installs
+  --dry-run           Resolve and print without writing
+  --force             Replace an unmanaged existing target
+`;
+  const stream = exitCode === 0 ? process.stdout : process.stderr;
+  stream.write(output);
+  process.exit(exitCode);
+}
+
+function parseArgs(args) {
+  const options = {
+    agent: "codex",
+    scope: "project",
+    project: process.cwd(),
+    home: homedir(),
+    target: null,
+    dryRun: false,
+    force: false,
+    skipNpmCheck: process.env.DIREXIO_DEPLOYER_REFRESH_CHILD === "1"
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    switch (arg) {
+      case "--agent":
+        options.agent = requiredValue(args, ++i, arg);
+        break;
+      case "--scope":
+        options.scope = requiredValue(args, ++i, arg);
+        break;
+      case "--project":
+        options.project = requiredValue(args, ++i, arg);
+        break;
+      case "--home":
+        options.home = requiredValue(args, ++i, arg);
+        break;
+      case "--target":
+        options.target = requiredValue(args, ++i, arg);
+        break;
+      case "--dry-run":
+        options.dryRun = true;
+        break;
+      case "--force":
+        options.force = true;
+        break;
+      case "--skip-npm-check":
+        options.skipNpmCheck = true;
+        break;
+      default:
+        throwUserError(`unknown option: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function requiredValue(args, index, flag) {
+  const value = args[index];
+  if (!value || value.startsWith("--")) throwUserError(`${flag} requires a value`);
+  return value;
+}
+
+function runSkillCommand(command, options) {
+  const agent = normalizeAgent(options.agent);
+  const scope = normalizeScope(options.scope);
+  const target = options.target
+    ? path.resolve(options.target)
+    : resolveTarget({ agent, scope, project: options.project, home: options.home });
+
+  const base = {
+    command,
+    package: packageName,
+    version: packageVersion,
+    agent,
+    scope,
+    target,
+    dryRun: options.dryRun
+  };
+
+  if (command === "refresh") {
+    const freshness = checkFreshness(options);
+    if (options.dryRun) return { ...base, freshness };
+    if (freshness.updateCommand) runNpmUpdateAndChildInstall({ agent, scope, target, options, freshness });
+    return { ...base, freshness, installed: installSkill({ agent, scope, target, dryRun: false, force: options.force }) };
+  }
+
+  return { ...base, installed: installSkill({ agent, scope, target, dryRun: options.dryRun, force: options.force }) };
+}
+
+function normalizeAgent(agent) {
+  const normalized = aliases[String(agent).toLowerCase()] || String(agent).toLowerCase();
+  if (!projectTargets[normalized]) {
+    const supported = Object.keys(projectTargets).filter((name) => name !== "unknown").join(", ");
+    throwUserError(`agent must be one of: ${supported}`);
+  }
+  return normalized;
+}
+
+function normalizeScope(scope) {
+  if (scope !== "project" && scope !== "global") throwUserError("scope must be project or global");
+  return scope;
+}
+
+function resolveTarget({ agent, scope, project, home }) {
+  if (scope === "project") return path.resolve(project, ...projectTargets[agent]);
+  const entry = globalTargets[agent];
+  const configuredHome = entry.env ? process.env[entry.env] : null;
+  if (configuredHome) {
+    const suffix = entry.envSuffix || entry.defaultSegments;
+    return path.resolve(configuredHome, ...suffix);
+  }
+  return path.resolve(home, ...entry.defaultSegments);
+}
+
+function installSkill({ agent, scope, target, dryRun, force }) {
+  if (dryRun) return { action: "would-install", fileCount: skillFiles.length };
+
+  if (existsSync(target)) {
+    const entries = readdirSync(target);
+    const managed = isManagedTarget(target);
+    if (entries.length > 0 && !managed && !force) {
+      throwUserError(`refusing to overwrite unmanaged target: ${target}. Re-run with --force if this is intentional.`);
+    }
+    rmSync(target, { recursive: true, force: true });
+  }
+
+  mkdirSync(target, { recursive: true });
+  for (const relative of skillFiles) {
+    const source = path.join(packageRoot, relative);
+    if (!existsSync(source)) continue;
+    copyRecursive(source, path.join(target, relative));
+  }
+
+  const manifest = {
+    package: packageName,
+    version: packageVersion,
+    agent,
+    scope,
+    source: packageRoot,
+    installedAt: new Date().toISOString()
+  };
+  writeFileSync(path.join(target, ".direxio-skill-install.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  return { action: "installed", manifest: path.join(target, ".direxio-skill-install.json") };
+}
+
+function isManagedTarget(target) {
+  const manifestPath = path.join(target, ".direxio-skill-install.json");
+  if (!existsSync(manifestPath)) return false;
+  try {
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    return manifest.package === packageName;
+  } catch {
+    return false;
+  }
+}
+
+function copyRecursive(source, destination) {
+  const stat = statSync(source);
+  if (stat.isDirectory()) {
+    mkdirSync(destination, { recursive: true });
+    for (const entry of readdirSync(source)) {
+      if (shouldSkip(entry)) continue;
+      copyRecursive(path.join(source, entry), path.join(destination, entry));
+    }
+    return;
+  }
+  mkdirSync(path.dirname(destination), { recursive: true });
+  copyFileSync(source, destination);
+}
+
+function shouldSkip(entry) {
+  return new Set([
+    ".cc-connect",
+    ".codegraph",
+    ".direxio-skill-install.json",
+    ".git",
+    ".idea",
+    "node_modules"
+  ]).has(entry);
+}
+
+function checkFreshness(options) {
+  if (options.skipNpmCheck) return { status: "skipped", reason: "child refresh install" };
+  if (options.dryRun) {
+    return {
+      status: "dry-run",
+      currentVersion: packageVersion,
+      latestVersion: null,
+      updateCommand: null
+    };
+  }
+  const npmView = spawnSync("npm", ["view", `${packageName}@latest`, "version"], {
+    encoding: "utf8",
+    shell: process.platform === "win32"
+  });
+  if (npmView.status !== 0) {
+    return {
+      status: "unavailable",
+      currentVersion: packageVersion,
+      latestVersion: null,
+      reason: (npmView.stderr || npmView.stdout || "npm view failed").trim()
+    };
+  }
+  const latestVersion = npmView.stdout.trim();
+  if (!isNewerVersion(latestVersion, packageVersion)) {
+    return { status: "current", currentVersion: packageVersion, latestVersion, updateCommand: null };
+  }
+  return {
+    status: "update-available",
+    currentVersion: packageVersion,
+    latestVersion,
+    updateCommand: `npm install -g ${packageName}@latest`
+  };
+}
+
+function runNpmUpdateAndChildInstall({ agent, scope, target, options, freshness }) {
+  const installResult = spawnSync("npm", ["install", "-g", `${packageName}@latest`], {
+    stdio: "inherit",
+    shell: process.platform === "win32"
+  });
+  if (installResult.status !== 0) {
+    throwUserError(`npm update failed for ${packageName}@latest`);
+  }
+
+  const childArgs = [
+    "skill",
+    "update",
+    "--agent",
+    agent,
+    "--scope",
+    scope,
+    "--target",
+    target,
+    "--skip-npm-check"
+  ];
+  if (options.force) childArgs.push("--force");
+  const child = spawnSync("direxio-deployer", childArgs, {
+    env: { ...process.env, DIREXIO_DEPLOYER_REFRESH_CHILD: "1" },
+    stdio: "inherit",
+    shell: process.platform === "win32"
+  });
+  if (child.status === 0) process.exit(0);
+  freshness.childRefresh = "failed; falling back to current package copy";
+}
+
+function isNewerVersion(candidate, current) {
+  const left = parseVersion(candidate);
+  const right = parseVersion(current);
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const a = left[i] || 0;
+    const b = right[i] || 0;
+    if (a > b) return true;
+    if (a < b) return false;
+  }
+  return false;
+}
+
+function parseVersion(version) {
+  return String(version)
+    .replace(/^v/, "")
+    .split(/[.-]/)
+    .map((part) => Number.parseInt(part, 10))
+    .filter((part) => Number.isFinite(part));
+}
+
+function throwUserError(message) {
+  console.error(message);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "direxio-deployer",
+  "version": "0.1.0",
+  "description": "Versioned Direxio deployer agent skill and portable deployment orchestration tools.",
+  "type": "module",
+  "bin": {
+    "direxio-deployer": "bin/direxio-deployer.mjs"
+  },
+  "files": [
+    "AGENTS.md",
+    "LICENSE",
+    "README.md",
+    "README_zh.md",
+    "SKILL.md",
+    "agents/",
+    "bin/",
+    "references/",
+    "scripts/",
+    "tests/"
+  ],
+  "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"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/references/agent-targets.md

@@ -0,0 +1,128 @@
+# Agent Targets
+
+Use this file when installing or updating this skill and when reviewing S6 local bridge output. Direxio no longer ships extra chat-platform adapters from this deployer; the only post-deploy local conversation bridge is `direxio-connect`. MCP-capable hosts can also use the generated `direxio-mcp` snippets.
+
+## Npm Skill Installation
+
+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:
+
+POSIX shells:
+
+```bash
+npm install -g direxio-deployer@latest
+direxio-deployer skill install --agent codex --scope project --project PROJECT_ROOT
+direxio-deployer skill update --agent codex --scope project --project PROJECT_ROOT
+```
+
+Windows PowerShell:
+
+```powershell
+npm install -g direxio-deployer@latest
+direxio-deployer skill install --agent codex --scope project --project PROJECT_ROOT
+direxio-deployer skill update --agent codex --scope project --project PROJECT_ROOT
+```
+
+Use `--scope global` only when the user explicitly asks for a global install or no project target exists. Use a Git clone only for deployer development or local patching, not as the normal end-user installation path. The npm installer writes `.direxio-skill-install.json` and refuses to overwrite unmanaged existing target directories unless `--force` is passed.
+
+| Runtime | Project-local skill target | Global fallback only when explicitly requested or no project exists |
+| --- | --- | --- |
+| Codex | `PROJECT_ROOT/.codex/skills/direxio-deployer` | `${CODEX_HOME:-$HOME/.codex}/skills/direxio-deployer` |
+| Claude Code | `PROJECT_ROOT/.claude/skills/direxio-deployer` | `${CLAUDE_HOME:-$HOME/.claude}/skills/direxio-deployer` |
+| Gemini | `PROJECT_ROOT/.gemini/skills/direxio-deployer` | `${GEMINI_HOME:-$HOME/.gemini}/skills/direxio-deployer` |
+| Cursor | `PROJECT_ROOT/.cursor/skills/direxio-deployer` | `${CURSOR_HOME:-$HOME/.cursor}/skills/direxio-deployer` |
+| GitHub Copilot | `PROJECT_ROOT/.github/copilot/skills/direxio-deployer` | `$HOME/.github/copilot/skills/direxio-deployer` |
+| OpenClaw | `PROJECT_ROOT/.openclaw/skills/direxio-deployer` | `${OPENCLAW_HOME:-$HOME/.openclaw}/skills/direxio-deployer` |
+| Hermes | `PROJECT_ROOT/.hermes/skills/direxio-deployer` | `${HERMES_HOME:-$HOME/.hermes}/skills/direxio-deployer` |
+| ACP-compatible | `PROJECT_ROOT/.agents/skills/direxio-deployer` | `$HOME/.agents/skills/direxio-deployer` |
+| Antigravity | `PROJECT_ROOT/.antigravity/skills/direxio-deployer` | `${ANTIGRAVITY_HOME:-$HOME/.antigravity}/skills/direxio-deployer` |
+| Devin | `PROJECT_ROOT/.devin/skills/direxio-deployer` | `${DEVIN_HOME:-$HOME/.devin}/skills/direxio-deployer` |
+| iFlow | `PROJECT_ROOT/.iflow/skills/direxio-deployer` | `${IFLOW_HOME:-$HOME/.iflow}/skills/direxio-deployer` |
+| Kimi | `PROJECT_ROOT/.kimi/skills/direxio-deployer` | `${KIMI_HOME:-$HOME/.kimi}/skills/direxio-deployer` |
+| OpenCode | `PROJECT_ROOT/.opencode/skills/direxio-deployer` | `${OPENCODE_HOME:-$HOME/.opencode}/skills/direxio-deployer` |
+| Pi | `PROJECT_ROOT/.pi/agent/skills/direxio-deployer` | `${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/skills/direxio-deployer` |
+| Qoder | `PROJECT_ROOT/.qoder/skills/direxio-deployer` | `${QODER_HOME:-$HOME/.qoder}/skills/direxio-deployer` |
+| Reasonix | `PROJECT_ROOT/.reasonix/skills/direxio-deployer` | `${REASONIX_HOME:-$HOME/.reasonix}/skills/direxio-deployer` |
+| tmux | `PROJECT_ROOT/.agent/skills/direxio-deployer` | `$HOME/.agent/skills/direxio-deployer` |
+| Generic or unknown | `PROJECT_ROOT/.agent/skills/direxio-deployer` | `$HOME/.agent/skills/direxio-deployer` |
+
+## Direxio Connect Target
+
+The bridge agent type is selected independently from the host operating system. `DIREXIO_CC_CONNECT_AGENT` may be any agent supported by connent/connect:
+
+```text
+acp antigravity claudecode codex copilot cursor devin gemini iflow kimi opencode pi qoder reasonix tmux
+```
+
+`DIREXIO_AGENT_PLATFORM=auto` is a convenience detector. If it detects OpenClaw or Hermes, S6 wires `direxio-connect` through the generic `acp` agent. OpenClaw writes `cmd = "openclaw"` and requires the current agent/operator to provide the real Gateway URL, token-file, and ACP session. Hermes writes `cmd = "direxio-connect"` with `args = ["hermes-acp-adapter", "--", "hermes", "acp"]` so the Direxio ACP compatibility layer can buffer and clean Hermes output before it reaches the Matrix room. OpenClaw and Hermes are not native connent/connect agent types. If detection is ambiguous or the detected host runtime should use a different connect backend, set `DIREXIO_CC_CONNECT_AGENT` explicitly.
+
+S6 writes service-specific files to `~/.direxio/nodes/<service_id>/`, where `service_id` is derived from the deployed domain:
+
+```text
+credentials.json
+env
+cc-connect/config.toml
+cc-connect/data/
+cc-connect/matrix-session.json
+mcp/codex.toml
+mcp/openclaw.md
+mcp/openclaw-server.json
+mcp/hermes.mcp.json
+mcp/mcp-servers.json
+```
+
+The generated `cc-connect/config.toml` contains exactly one Matrix platform and includes:
+
+```toml
+[speech]
+enabled = true
+provider = "openai"
+language = "zh"
+
+[speech.openai]
+api_key = "<optional speech-to-text key>"
+
+[[projects]]
+name = "<agent-node-id>"
+admin_from = "@owner:<server>"
+
+[projects.agent.options]
+work_dir = "<workspace>"
+cmd = "<optional explicit agent executable path>"
+
+[[projects.platforms]]
+type = "matrix"
+
+[projects.platforms.options]
+homeserver = "https://<domain>"
+user_id = "@agent:<server>"
+room_id = "!<real-agent-room>:<server>"
+share_session_in_channel = true
+group_reply_all = true
+auto_join = false
+auto_verify = false
+```
+
+The `[speech]` block is present only when S6 finds a speech-to-text API key from `DIREXIO_SPEECH_*` or supported provider environment variables. Voice input is not available without STT credentials.
+
+`admin_from` must stay at the `[[projects]]` level. `direxio-connect` uses the full Matrix sender ID, so S6 writes `@owner:<server>`; privileged commands such as `/dir`, `/shell`, `/show`, `/restart`, and `/upgrade` are blocked for other room members. `/dir reset` returns to the generated `work_dir` and clears the runtime override stored under `cc-connect/data/projects/<project>.state.json`.
+
+## MCP Targets
+
+S6 writes MCP artifacts for Codex, OpenClaw, and Hermes under `~/.direxio/nodes/<service_id>/mcp/`. These artifacts use `direxio-mcp` from `direxio-mcp@latest` by default and point to the service credential file through `DIREXIO_CREDENTIALS_FILE`.
+
+```bash
+npm install -g direxio-mcp@latest
+DIREXIO_CREDENTIALS_FILE=~/.direxio/nodes/<service_id>/credentials.json direxio-mcp doctor --json
+```
+
+Use `mcp/codex.toml` for Codex and `mcp/hermes.mcp.json` for Hermes. For OpenClaw, use `mcp/openclaw.md`; it runs `openclaw mcp set` with `mcp/openclaw-server.json` so OpenClaw validates and writes its own `mcp.servers` config. Do not paste MCP JSON into `~/.openclaw/openclaw.json`. The deployer writes local artifacts only; it does not mutate each host application's global MCP config.
+
+## Installation Policy
+
+- `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`.
+
+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.

package/references/architecture.md

@@ -0,0 +1,44 @@
+# 架构原理
+
+本部署器已经适配新版 Direxio message-server: AS 业务合并进 Dendrite 单体后端，不再部署独立 `asd` 服务。
+
+## 服务拓扑
+
+```text
+公网 443/80 -> Caddy
+  ├─ /_matrix/*, /_dendrite/*, /_synapse/* -> message-server:8008
+  ├─ /_p2p/*                              -> message-server:8008
+  ├─ /.well-known/matrix/*                -> Caddy 静态响应
+  ├─ /.well-known/portal/*                -> /opt/p2p/wellknown 静态文件
+  └─ /healthz                             -> /_p2p/health
+
+message-server -> PostgreSQL 18
+coturn         -> TURN 3478 + 49160-49200/udp
+```
+
+- **message-server**: `direxio/message-server:latest`，同时承载 Matrix homeserver 和 `/_p2p/query`/`/_p2p/command`。
+- **PostgreSQL 18**: Matrix 与 P2P 业务表共库持久化，compose 使用 `/var/lib/postgresql`。
+- **Caddy**: 唯一 HTTP/TLS 入口，自动签发 Let's Encrypt。
+- **coturn**: WebRTC TURN relay，Direxio message-server 通过 shared-secret 动态签发 TURN 凭证。
+
+## 启动顺序
+
+1. `postgres` healthy。
+2. `message-init` 生成 `/etc/direxio-message-server/message-server.yaml` 和 signing key，并写入 TURN 配置。
+3. `message-server` 启动，加载 Matrix + P2P 业务，读取 `P2P_PORTAL_PASSWORD` 和 `P2P_PORTAL_CREDENTIALS_FILE`。
+4. `init-tokens.sh` 调用 `portal.bootstrap`，从容器复制凭据到宿主 `/opt/p2p/bootstrap.json`。如果最新服务端没有写入 `agent_room_id`，脚本会通过 Matrix Client API 创建真实 agent room、邀请并加入 `@agent:<server>`，再把 `agent_room_id` 回写到宿主和容器凭据文件。
+5. `init-tokens.sh` 生成 `/opt/p2p/wellknown/owner.json`。
+6. `caddy` 对外服务 Matrix、P2P API 和 well-known。
+
+## 凭据模型
+
+`/opt/p2p/bootstrap.json` 会包含:
+
+- `password`: 后端字段名；对用户展示时是八位 App 初始化码。
+- `access_token`: 当前用户的统一 bearer token，可用于 Matrix `/_matrix/client/*` 和需要用户身份的 P2P 调用。
+- `agent_token`: 本地服务凭据中的 agent bearer token；`direxio-connect` 对话桥接使用 S6 创建的 `@agent:<server>` Matrix session。
+- `agent_room_id`: 真实 Matrix 房间 ID。部署脚本拒绝旧式 `!agent:<domain>` 伪房间。
+
+## 域名模型
+
+Matrix `server_name` 必须是长期真实域名。部署后更换 `DOMAIN` 等同创建新的 homeserver 身份，不要保留旧 PostgreSQL/message-server 数据卷后直接改域名。