codeharbor 0.1.23 → 0.1.25

package/README.md

@@ -200,6 +200,8 @@ PLAYWRIGHT_USE_SYSTEM_CHROME=false npm run test:e2e
 
 - `REQUIREMENTS.md`: current baseline + next-stage requirements
 - `TASK_LIST.md`: implementation task breakdown and status
+- `docs/USER_MANUAL_ZH.md`: Chinese user manual (installation, configuration, verification)
+- `docs/COMPLETE_CONFIGURATION_GUIDE.md`: end-to-end setup flow + full feature-to-config mapping
 - `docs/CONFIG_UI_DESIGN.md`: configuration UI MVP design
 - `docs/CONFIG_CATALOG.md`: consolidated configuration matrix (required/runtime/UI/effective timing)
 - `docs/ADMIN_STANDALONE_DEPLOY.md`: standalone admin deployment and Cloudflare Tunnel exposure guide
@@ -249,6 +251,7 @@ node dist/cli.js start
 Use this layered reference to avoid mixing boot-only and runtime tuning items:
 
 - [`docs/CONFIG_CATALOG.md`](docs/CONFIG_CATALOG.md)
+- [`docs/COMPLETE_CONFIGURATION_GUIDE.md`](docs/COMPLETE_CONFIGURATION_GUIDE.md)
 
 It documents:
 
@@ -256,6 +259,7 @@ It documents:
 - which keys can be edited in Admin UI
 - whether changes are immediate or restart-scoped
 - recommended profiles for local/internal/public deployment
+- a complete setup sequence from install to production operations
 
 ## Commands
 
@@ -418,7 +422,7 @@ If any check fails, it prints actionable fix commands (for example `codeharbor i
   - each accepted request activates the sender's conversation in that room
   - activation TTL: `SESSION_ACTIVE_WINDOW_MINUTES` (default: `20`)
 - Control commands
-  - `/status` show session + limiter + metrics + runtime worker status
+  - `/status` show session + limiter + metrics + runtime worker status, current version, and update hint
   - `/reset` clear bound Codex session and keep conversation active
   - `/stop` cancel in-flight execution (if running) and reset session context
   - `/agents status` show multi-agent workflow status for current session (when enabled)

package/dist/cli.js

@@ -25,8 +25,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 // src/cli.ts
 var import_node_child_process8 = require("child_process");
-var import_node_fs11 = __toESM(require("fs"));
-var import_node_path15 = __toESM(require("path"));
+var import_node_fs12 = __toESM(require("fs"));
+var import_node_path16 = __toESM(require("path"));
 var import_commander = require("commander");
 
 // src/app.ts
@@ -4463,6 +4463,163 @@ var CodexSessionRuntime = class {
   }
 };
 
+// src/package-update-checker.ts
+var import_node_fs7 = __toESM(require("fs"));
+var import_node_path10 = __toESM(require("path"));
+var NpmRegistryUpdateChecker = class {
+  packageName;
+  currentVersion;
+  ttlMs;
+  timeoutMs;
+  fetchImpl;
+  enabled;
+  upgradeCommand;
+  cachedStatus = null;
+  cacheExpiresAt = 0;
+  constructor(options) {
+    this.packageName = options?.packageName?.trim() || "codeharbor";
+    this.currentVersion = options?.currentVersion?.trim() || resolvePackageVersion();
+    this.ttlMs = options?.ttlMs ?? 6 * 60 * 60 * 1e3;
+    this.timeoutMs = options?.timeoutMs ?? 3e3;
+    this.fetchImpl = options?.fetchImpl ?? fetch;
+    this.enabled = options?.enabled ?? process.env.NODE_ENV !== "test";
+    this.upgradeCommand = `npm install -g ${this.packageName}@latest`;
+  }
+  async getStatus() {
+    const now = Date.now();
+    if (this.cachedStatus && now < this.cacheExpiresAt) {
+      return this.cachedStatus;
+    }
+    let nextStatus;
+    if (!this.enabled) {
+      nextStatus = this.buildStatus({
+        latestVersion: null,
+        state: "unknown",
+        error: "update check disabled"
+      });
+    } else {
+      nextStatus = await this.fetchLatestStatus();
+    }
+    this.cachedStatus = nextStatus;
+    this.cacheExpiresAt = now + this.ttlMs;
+    return nextStatus;
+  }
+  async fetchLatestStatus() {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    timer.unref?.();
+    try {
+      const response = await this.fetchImpl(`https://registry.npmjs.org/${this.packageName}/latest`, {
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        return this.buildStatus({
+          latestVersion: null,
+          state: "unknown",
+          error: `HTTP ${response.status}`
+        });
+      }
+      const payload = await response.json();
+      const latest = typeof payload.version === "string" ? payload.version.trim() : "";
+      if (!latest) {
+        return this.buildStatus({
+          latestVersion: null,
+          state: "unknown",
+          error: "invalid npm response"
+        });
+      }
+      const comparison = compareSemver(this.currentVersion, latest);
+      if (comparison === null) {
+        return this.buildStatus({
+          latestVersion: latest,
+          state: "unknown",
+          error: "version compare unavailable"
+        });
+      }
+      return this.buildStatus({
+        latestVersion: latest,
+        state: comparison < 0 ? "update_available" : "up_to_date",
+        error: null
+      });
+    } catch (error) {
+      return this.buildStatus({
+        latestVersion: null,
+        state: "unknown",
+        error: normalizeError(error)
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  buildStatus(input) {
+    return {
+      packageName: this.packageName,
+      currentVersion: this.currentVersion,
+      latestVersion: input.latestVersion,
+      state: input.state,
+      checkedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      error: input.error,
+      upgradeCommand: this.upgradeCommand
+    };
+  }
+};
+function formatPackageUpdateHint(status) {
+  if (status.state === "update_available" && status.latestVersion) {
+    return `\u53D1\u73B0\u65B0\u7248\u672C ${status.latestVersion}\uFF0C\u5EFA\u8BAE\u6267\u884C\uFF1A${status.upgradeCommand}`;
+  }
+  if (status.state === "up_to_date") {
+    return `\u5DF2\u662F\u6700\u65B0\u7248\u672C${status.latestVersion ? `\uFF08${status.latestVersion}\uFF09` : ""}`;
+  }
+  return `\u6682\u65F6\u65E0\u6CD5\u68C0\u67E5\u66F4\u65B0${status.error ? `\uFF08${status.error}\uFF09` : ""}`;
+}
+function resolvePackageVersion(packagePath) {
+  const resolvedPath = packagePath ?? import_node_path10.default.resolve(__dirname, "..", "package.json");
+  try {
+    const raw = import_node_fs7.default.readFileSync(resolvedPath, "utf8");
+    const payload = JSON.parse(raw);
+    if (typeof payload.version === "string" && payload.version.trim()) {
+      return payload.version.trim();
+    }
+  } catch {
+  }
+  return "0.0.0";
+}
+function compareSemver(current, latest) {
+  const currentParts = parseSemver(current);
+  const latestParts = parseSemver(latest);
+  if (!currentParts || !latestParts) {
+    return null;
+  }
+  for (let i = 0; i < 3; i += 1) {
+    if (currentParts[i] < latestParts[i]) {
+      return -1;
+    }
+    if (currentParts[i] > latestParts[i]) {
+      return 1;
+    }
+  }
+  return 0;
+}
+function parseSemver(raw) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(raw.trim());
+  if (!match) {
+    return null;
+  }
+  const major = Number.parseInt(match[1], 10);
+  const minor = Number.parseInt(match[2], 10);
+  const patch = Number.parseInt(match[3], 10);
+  if (!Number.isFinite(major) || !Number.isFinite(minor) || !Number.isFinite(patch)) {
+    return null;
+  }
+  return [major, minor, patch];
+}
+function normalizeError(error) {
+  if (error instanceof Error && error.message.trim()) {
+    return error.message.trim();
+  }
+  return String(error);
+}
+
 // src/rate-limiter.ts
 var RateLimiter = class {
   options;
@@ -4846,7 +5003,7 @@ function createIdleWorkflowSnapshot() {
 
 // src/workflow/autodev.ts
 var import_promises4 = __toESM(require("fs/promises"));
-var import_node_path10 = __toESM(require("path"));
+var import_node_path11 = __toESM(require("path"));
 function parseAutoDevCommand(text) {
   const normalized = text.trim();
   if (!/^\/autodev(?:\s|$)/i.test(normalized)) {
@@ -4866,8 +5023,8 @@ function parseAutoDevCommand(text) {
   };
 }
 async function loadAutoDevContext(workdir) {
-  const requirementsPath = import_node_path10.default.join(workdir, "REQUIREMENTS.md");
-  const taskListPath = import_node_path10.default.join(workdir, "TASK_LIST.md");
+  const requirementsPath = import_node_path11.default.join(workdir, "REQUIREMENTS.md");
+  const taskListPath = import_node_path11.default.join(workdir, "TASK_LIST.md");
   const requirementsContent = await readOptionalFile(requirementsPath);
   const taskListContent = await readOptionalFile(taskListPath);
   return {
@@ -5225,6 +5382,7 @@ var Orchestrator = class {
   cliCompatRecorder;
   audioTranscriber;
   workflowRunner;
+  packageUpdateChecker;
   workflowSnapshots = /* @__PURE__ */ new Map();
   autoDevSnapshots = /* @__PURE__ */ new Map();
   metrics = new RequestMetrics();
@@ -5298,6 +5456,9 @@ var Orchestrator = class {
       enabled: options?.multiAgentWorkflow?.enabled ?? false,
       autoRepairMaxRounds: options?.multiAgentWorkflow?.autoRepairMaxRounds ?? 1
     });
+    this.packageUpdateChecker = options?.packageUpdateChecker ?? new NpmRegistryUpdateChecker({
+      packageName: "codeharbor"
+    });
     this.sessionRuntime = new CodexSessionRuntime(this.executor);
   }
   async handleMessage(message) {
@@ -5661,6 +5822,7 @@ var Orchestrator = class {
     const runtime = this.sessionRuntime.getRuntimeStats();
     const workflow = this.workflowSnapshots.get(sessionKey) ?? createIdleWorkflowSnapshot();
     const autoDev = this.autoDevSnapshots.get(sessionKey) ?? createIdleAutoDevSnapshot();
+    const packageUpdate = await this.packageUpdateChecker.getStatus();
     await this.channel.sendNotice(
       message.conversationId,
       `[CodeHarbor] \u5F53\u524D\u72B6\u6001
@@ -5669,6 +5831,8 @@ var Orchestrator = class {
 - activeUntil: ${activeUntil}
 - \u5DF2\u7ED1\u5B9A Codex \u4F1A\u8BDD: ${status.hasCodexSession ? "\u662F" : "\u5426"}
 - \u5F53\u524D\u5DE5\u4F5C\u76EE\u5F55: ${roomConfig.workdir}
+- \u5F53\u524D\u7248\u672C: ${packageUpdate.currentVersion}
+- \u66F4\u65B0\u68C0\u67E5: ${formatPackageUpdateHint(packageUpdate)}
 - \u8FD0\u884C\u4E2D\u4EFB\u52A1: ${metrics.activeExecutions}
 - \u6307\u6807: total=${metrics.total}, success=${metrics.success}, failed=${metrics.failed}, timeout=${metrics.timeout}, cancelled=${metrics.cancelled}, rate_limited=${metrics.rateLimited}
 - \u5E73\u5747\u8017\u65F6: queue=${metrics.avgQueueMs}ms, exec=${metrics.avgExecMs}ms, send=${metrics.avgSendMs}ms
@@ -6466,8 +6630,8 @@ ${result.review}
 }
 
 // src/store/state-store.ts
-var import_node_fs7 = __toESM(require("fs"));
-var import_node_path11 = __toESM(require("path"));
+var import_node_fs8 = __toESM(require("fs"));
+var import_node_path12 = __toESM(require("path"));
 var ONE_DAY_MS = 24 * 60 * 60 * 1e3;
 var PRUNE_INTERVAL_MS = 5 * 60 * 1e3;
 var SQLITE_MODULE_ID = `node:${"sqlite"}`;
@@ -6493,7 +6657,7 @@ var StateStore = class {
     this.maxProcessedEventsPerSession = maxProcessedEventsPerSession;
     this.maxSessionAgeMs = maxSessionAgeDays * ONE_DAY_MS;
     this.maxSessions = maxSessions;
-    import_node_fs7.default.mkdirSync(import_node_path11.default.dirname(this.dbPath), { recursive: true });
+    import_node_fs8.default.mkdirSync(import_node_path12.default.dirname(this.dbPath), { recursive: true });
     this.db = new DatabaseSync(this.dbPath);
     this.initializeSchema();
     this.importLegacyStateIfNeeded();
@@ -6738,7 +6902,7 @@ var StateStore = class {
     `);
   }
   importLegacyStateIfNeeded() {
-    if (!this.legacyJsonPath || !import_node_fs7.default.existsSync(this.legacyJsonPath)) {
+    if (!this.legacyJsonPath || !import_node_fs8.default.existsSync(this.legacyJsonPath)) {
       return;
     }
     const countRow = this.db.prepare("SELECT COUNT(*) AS count FROM sessions").get();
@@ -6821,7 +6985,7 @@ var StateStore = class {
 };
 function loadLegacyState(filePath) {
   try {
-    const raw = import_node_fs7.default.readFileSync(filePath, "utf8");
+    const raw = import_node_fs8.default.readFileSync(filePath, "utf8");
     const parsed = JSON.parse(raw);
     if (!parsed.sessions || typeof parsed.sessions !== "object") {
       return null;
@@ -7015,8 +7179,8 @@ function isNonLoopbackHost(host) {
 }
 
 // src/config.ts
-var import_node_fs8 = __toESM(require("fs"));
-var import_node_path12 = __toESM(require("path"));
+var import_node_fs9 = __toESM(require("fs"));
+var import_node_path13 = __toESM(require("path"));
 var import_dotenv2 = __toESM(require("dotenv"));
 var import_zod = require("zod");
 var configSchema = import_zod.z.object({
@@ -7088,7 +7252,7 @@ var configSchema = import_zod.z.object({
   matrixCommandPrefix: v.MATRIX_COMMAND_PREFIX,
   codexBin: v.CODEX_BIN,
   codexModel: v.CODEX_MODEL?.trim() || null,
-  codexWorkdir: import_node_path12.default.resolve(v.CODEX_WORKDIR),
+  codexWorkdir: import_node_path13.default.resolve(v.CODEX_WORKDIR),
   codexDangerousBypass: v.CODEX_DANGEROUS_BYPASS,
   codexExecTimeoutMs: v.CODEX_EXEC_TIMEOUT_MS,
   codexSandboxMode: v.CODEX_SANDBOX_MODE?.trim() || null,
@@ -7099,8 +7263,8 @@ var configSchema = import_zod.z.object({
     enabled: v.AGENT_WORKFLOW_ENABLED,
     autoRepairMaxRounds: v.AGENT_WORKFLOW_AUTO_REPAIR_MAX_ROUNDS
   },
-  stateDbPath: import_node_path12.default.resolve(v.STATE_DB_PATH),
-  legacyStateJsonPath: v.STATE_PATH.trim() ? import_node_path12.default.resolve(v.STATE_PATH) : null,
+  stateDbPath: import_node_path13.default.resolve(v.STATE_DB_PATH),
+  legacyStateJsonPath: v.STATE_PATH.trim() ? import_node_path13.default.resolve(v.STATE_PATH) : null,
   maxProcessedEventsPerSession: v.MAX_PROCESSED_EVENTS_PER_SESSION,
   maxSessionAgeDays: v.MAX_SESSION_AGE_DAYS,
   maxSessions: v.MAX_SESSIONS,
@@ -7141,7 +7305,7 @@ var configSchema = import_zod.z.object({
     audioTranscribeMaxBytes: v.CLI_COMPAT_AUDIO_TRANSCRIBE_MAX_BYTES,
     audioLocalWhisperCommand: v.CLI_COMPAT_AUDIO_LOCAL_WHISPER_COMMAND.trim() ? v.CLI_COMPAT_AUDIO_LOCAL_WHISPER_COMMAND.trim() : null,
     audioLocalWhisperTimeoutMs: v.CLI_COMPAT_AUDIO_LOCAL_WHISPER_TIMEOUT_MS,
-    recordPath: v.CLI_COMPAT_RECORD_PATH.trim() ? import_node_path12.default.resolve(v.CLI_COMPAT_RECORD_PATH) : null
+    recordPath: v.CLI_COMPAT_RECORD_PATH.trim() ? import_node_path13.default.resolve(v.CLI_COMPAT_RECORD_PATH) : null
   },
   doctorHttpTimeoutMs: v.DOCTOR_HTTP_TIMEOUT_MS,
   adminBindHost: v.ADMIN_BIND_HOST.trim() || "127.0.0.1",
@@ -7152,7 +7316,7 @@ var configSchema = import_zod.z.object({
   adminAllowedOrigins: parseCsvList(v.ADMIN_ALLOWED_ORIGINS),
   logLevel: v.LOG_LEVEL
 }));
-function loadEnvFromFile(filePath = import_node_path12.default.resolve(process.cwd(), ".env"), env = process.env) {
+function loadEnvFromFile(filePath = import_node_path13.default.resolve(process.cwd(), ".env"), env = process.env) {
   import_dotenv2.default.config({
     path: filePath,
     processEnv: env,
@@ -7165,9 +7329,9 @@ function loadConfig(env = process.env) {
     const message = parsed.error.issues.map((issue) => `${issue.path.join(".") || "config"}: ${issue.message}`).join("; ");
     throw new Error(`Invalid configuration: ${message}`);
   }
-  import_node_fs8.default.mkdirSync(import_node_path12.default.dirname(parsed.data.stateDbPath), { recursive: true });
+  import_node_fs9.default.mkdirSync(import_node_path13.default.dirname(parsed.data.stateDbPath), { recursive: true });
   if (parsed.data.legacyStateJsonPath) {
-    import_node_fs8.default.mkdirSync(import_node_path12.default.dirname(parsed.data.legacyStateJsonPath), { recursive: true });
+    import_node_fs9.default.mkdirSync(import_node_path13.default.dirname(parsed.data.legacyStateJsonPath), { recursive: true });
   }
   return parsed.data;
 }
@@ -7334,8 +7498,8 @@ function parseAdminTokens(raw) {
 }
 
 // src/config-snapshot.ts
-var import_node_fs9 = __toESM(require("fs"));
-var import_node_path13 = __toESM(require("path"));
+var import_node_fs10 = __toESM(require("fs"));
+var import_node_path14 = __toESM(require("path"));
 var import_zod2 = require("zod");
 var CONFIG_SNAPSHOT_SCHEMA_VERSION = 1;
 var CONFIG_SNAPSHOT_ENV_KEYS = [
@@ -7558,9 +7722,9 @@ async function runConfigExportCommand(options = {}) {
     const snapshot = buildConfigSnapshot(config, stateStore.listRoomSettings(), options.now ?? /* @__PURE__ */ new Date());
     const serialized = serializeConfigSnapshot(snapshot);
     if (options.outputPath) {
-      const targetPath = import_node_path13.default.resolve(cwd, options.outputPath);
-      import_node_fs9.default.mkdirSync(import_node_path13.default.dirname(targetPath), { recursive: true });
-      import_node_fs9.default.writeFileSync(targetPath, serialized, "utf8");
+      const targetPath = import_node_path14.default.resolve(cwd, options.outputPath);
+      import_node_fs10.default.mkdirSync(import_node_path14.default.dirname(targetPath), { recursive: true });
+      import_node_fs10.default.writeFileSync(targetPath, serialized, "utf8");
       output.write(`Exported config snapshot to ${targetPath}
 `);
       return;
@@ -7574,8 +7738,8 @@ async function runConfigImportCommand(options) {
   const cwd = options.cwd ?? process.cwd();
   const output = options.output ?? process.stdout;
   const actor = options.actor?.trim() || "cli:config-import";
-  const sourcePath = import_node_path13.default.resolve(cwd, options.filePath);
-  if (!import_node_fs9.default.existsSync(sourcePath)) {
+  const sourcePath = import_node_path14.default.resolve(cwd, options.filePath);
+  if (!import_node_fs10.default.existsSync(sourcePath)) {
     throw new Error(`Config snapshot file not found: ${sourcePath}`);
   }
   const snapshot = parseConfigSnapshot(parseJsonFile(sourcePath));
@@ -7605,7 +7769,7 @@ async function runConfigImportCommand(options) {
     synchronizeRoomSettings(stateStore, normalizedRooms);
     stateStore.appendConfigRevision(
       actor,
-      `import config snapshot from ${import_node_path13.default.basename(sourcePath)}`,
+      `import config snapshot from ${import_node_path14.default.basename(sourcePath)}`,
       JSON.stringify({
         type: "config_snapshot_import",
         sourcePath,
@@ -7619,7 +7783,7 @@ async function runConfigImportCommand(options) {
   output.write(
     [
       `Imported config snapshot from ${sourcePath}`,
-      `- updated .env in ${import_node_path13.default.resolve(cwd, ".env")}`,
+      `- updated .env in ${import_node_path14.default.resolve(cwd, ".env")}`,
       `- synchronized room settings: ${normalizedRooms.length}`,
       "- restart required: yes (global env settings are restart-scoped)"
     ].join("\n") + "\n"
@@ -7692,7 +7856,7 @@ function buildSnapshotEnv(config) {
 }
 function parseJsonFile(filePath) {
   try {
-    const raw = import_node_fs9.default.readFileSync(filePath, "utf8");
+    const raw = import_node_fs10.default.readFileSync(filePath, "utf8");
     return JSON.parse(raw);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -7704,10 +7868,10 @@ function parseJsonFile(filePath) {
 function normalizeSnapshotEnv(env, cwd) {
   return {
     ...env,
-    CODEX_WORKDIR: import_node_path13.default.resolve(cwd, env.CODEX_WORKDIR),
-    STATE_DB_PATH: import_node_path13.default.resolve(cwd, env.STATE_DB_PATH),
-    STATE_PATH: env.STATE_PATH.trim() ? import_node_path13.default.resolve(cwd, env.STATE_PATH) : "",
-    CLI_COMPAT_RECORD_PATH: env.CLI_COMPAT_RECORD_PATH.trim() ? import_node_path13.default.resolve(cwd, env.CLI_COMPAT_RECORD_PATH) : ""
+    CODEX_WORKDIR: import_node_path14.default.resolve(cwd, env.CODEX_WORKDIR),
+    STATE_DB_PATH: import_node_path14.default.resolve(cwd, env.STATE_DB_PATH),
+    STATE_PATH: env.STATE_PATH.trim() ? import_node_path14.default.resolve(cwd, env.STATE_PATH) : "",
+    CLI_COMPAT_RECORD_PATH: env.CLI_COMPAT_RECORD_PATH.trim() ? import_node_path14.default.resolve(cwd, env.CLI_COMPAT_RECORD_PATH) : ""
   };
 }
 function normalizeSnapshotRooms(rooms, cwd) {
@@ -7722,7 +7886,7 @@ function normalizeSnapshotRooms(rooms, cwd) {
       throw new Error(`Duplicate roomId in snapshot: ${roomId}`);
     }
     seen.add(roomId);
-    const workdir = import_node_path13.default.resolve(cwd, room.workdir);
+    const workdir = import_node_path14.default.resolve(cwd, room.workdir);
     ensureDirectory2(workdir, `room workdir (${roomId})`);
     normalized.push({
       roomId,
@@ -7749,18 +7913,18 @@ function synchronizeRoomSettings(stateStore, rooms) {
   }
 }
 function persistEnvSnapshot(cwd, env) {
-  const envPath = import_node_path13.default.resolve(cwd, ".env");
-  const examplePath = import_node_path13.default.resolve(cwd, ".env.example");
-  const template = import_node_fs9.default.existsSync(envPath) ? import_node_fs9.default.readFileSync(envPath, "utf8") : import_node_fs9.default.existsSync(examplePath) ? import_node_fs9.default.readFileSync(examplePath, "utf8") : "";
+  const envPath = import_node_path14.default.resolve(cwd, ".env");
+  const examplePath = import_node_path14.default.resolve(cwd, ".env.example");
+  const template = import_node_fs10.default.existsSync(envPath) ? import_node_fs10.default.readFileSync(envPath, "utf8") : import_node_fs10.default.existsSync(examplePath) ? import_node_fs10.default.readFileSync(examplePath, "utf8") : "";
   const overrides = {};
   for (const key of CONFIG_SNAPSHOT_ENV_KEYS) {
     overrides[key] = env[key];
   }
   const next = applyEnvOverrides(template, overrides);
-  import_node_fs9.default.writeFileSync(envPath, next, "utf8");
+  import_node_fs10.default.writeFileSync(envPath, next, "utf8");
 }
 function ensureDirectory2(dirPath, label) {
-  if (!import_node_fs9.default.existsSync(dirPath) || !import_node_fs9.default.statSync(dirPath).isDirectory()) {
+  if (!import_node_fs10.default.existsSync(dirPath) || !import_node_fs10.default.statSync(dirPath).isDirectory()) {
     throw new Error(`${label} does not exist or is not a directory: ${dirPath}`);
   }
 }
@@ -7834,8 +7998,8 @@ function jsonArrayStringSchema(key, allowEmpty) {
 
 // src/preflight.ts
 var import_node_child_process7 = require("child_process");
-var import_node_fs10 = __toESM(require("fs"));
-var import_node_path14 = __toESM(require("path"));
+var import_node_fs11 = __toESM(require("fs"));
+var import_node_path15 = __toESM(require("path"));
 var import_node_util5 = require("util");
 var execFileAsync4 = (0, import_node_util5.promisify)(import_node_child_process7.execFile);
 var REQUIRED_ENV_KEYS = ["MATRIX_HOMESERVER", "MATRIX_USER_ID", "MATRIX_ACCESS_TOKEN"];
@@ -7843,10 +8007,10 @@ async function runStartupPreflight(options = {}) {
   const env = options.env ?? process.env;
   const cwd = options.cwd ?? process.cwd();
   const checkCodexBinary = options.checkCodexBinary ?? defaultCheckCodexBinary;
-  const fileExists = options.fileExists ?? import_node_fs10.default.existsSync;
+  const fileExists = options.fileExists ?? import_node_fs11.default.existsSync;
   const isDirectory = options.isDirectory ?? defaultIsDirectory;
   const issues = [];
-  const envPath = import_node_path14.default.resolve(cwd, ".env");
+  const envPath = import_node_path15.default.resolve(cwd, ".env");
   let resolvedCodexBin = null;
   let usedCodexFallback = false;
   if (!fileExists(envPath)) {
@@ -7923,7 +8087,7 @@ async function runStartupPreflight(options = {}) {
     }
   }
   const configuredWorkdir = readEnv(env, "CODEX_WORKDIR");
-  const workdir = import_node_path14.default.resolve(cwd, configuredWorkdir || cwd);
+  const workdir = import_node_path15.default.resolve(cwd, configuredWorkdir || cwd);
   if (!fileExists(workdir) || !isDirectory(workdir)) {
     issues.push({
       level: "error",
@@ -7964,7 +8128,7 @@ async function defaultCheckCodexBinary(bin) {
 }
 function defaultIsDirectory(targetPath) {
   try {
-    return import_node_fs10.default.statSync(targetPath).isDirectory();
+    return import_node_fs11.default.statSync(targetPath).isDirectory();
   } catch {
     return false;
   }
@@ -7978,6 +8142,25 @@ var runtimeHome = null;
 var cliVersion = resolveCliVersion();
 var program = new import_commander.Command();
 program.name("codeharbor").description("Instant-messaging bridge for Codex CLI sessions").version(cliVersion);
+program.addHelpText(
+  "after",
+  [
+    "",
+    "Prerequisites:",
+    "  - codex CLI installed and authenticated (run: codex login)",
+    "  - Matrix bot credentials in .env: MATRIX_HOMESERVER, MATRIX_USER_ID, MATRIX_ACCESS_TOKEN",
+    "",
+    "Runtime:",
+    "  - default CODEHARBOR_HOME: ~/.codeharbor (legacy /opt/codeharbor/.env is auto-detected)",
+    "  - running without subcommand defaults to: codeharbor start",
+    "",
+    "Common commands:",
+    "  - codeharbor init",
+    "  - codeharbor doctor",
+    "  - codeharbor service install --with-admin",
+    "  - codeharbor admin serve --host 127.0.0.1 --port 8787"
+  ].join("\n")
+);
 program.command("init").description("Create or update .env via guided prompts").option("-f, --force", "overwrite existing .env without confirmation").action(async (options) => {
   const home = ensureRuntimeHomeOrExit();
   await runInitCommand({ force: options.force ?? false, cwd: home });
@@ -8014,6 +8197,33 @@ program.command("doctor").description("Check codex and matrix connectivity").act
 var admin = program.command("admin").description("Admin utilities");
 var configCommand = program.command("config").description("Config snapshot utilities");
 var serviceCommand = program.command("service").description("Systemd service management");
+admin.addHelpText(
+  "after",
+  [
+    "",
+    "Notes:",
+    "  - For non-loopback host binding, set ADMIN_TOKEN or ADMIN_TOKENS_JSON.",
+    "  - Admin UI routes: /settings/global, /settings/rooms, /health, /audit."
+  ].join("\n")
+);
+configCommand.addHelpText(
+  "after",
+  [
+    "",
+    "Examples:",
+    "  - codeharbor config export -o backup.json",
+    "  - codeharbor config import backup.json --dry-run"
+  ].join("\n")
+);
+serviceCommand.addHelpText(
+  "after",
+  [
+    "",
+    "Notes:",
+    "  - Service subcommands auto-elevate with sudo when required.",
+    "  - Use --with-admin to manage both main and admin services together."
+  ].join("\n")
+);
 admin.command("serve").description("Start admin config API server").option("--host <host>", "override admin bind host").option("--port <port>", "override admin bind port").option(
   "--allow-insecure-no-token",
   "allow serving admin API without ADMIN_TOKEN on non-loopback host (not recommended)"
@@ -8177,7 +8387,7 @@ function ensureRuntimeHomeOrExit() {
   }
   const home = resolveRuntimeHome();
   try {
-    import_node_fs11.default.mkdirSync(home, { recursive: true });
+    import_node_fs12.default.mkdirSync(home, { recursive: true });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     process.stderr.write(`Runtime setup failed: cannot create ${home}. ${message}
@@ -8192,7 +8402,7 @@ function ensureRuntimeHomeOrExit() {
 `);
     process.exit(1);
   }
-  loadEnvFromFile(import_node_path15.default.resolve(home, ".env"));
+  loadEnvFromFile(import_node_path16.default.resolve(home, ".env"));
   runtimeHome = home;
   return runtimeHome;
 }
@@ -8207,8 +8417,8 @@ function parsePortOption(raw, fallback) {
 }
 function resolveCliVersion() {
   try {
-    const packagePath = import_node_path15.default.resolve(__dirname, "..", "package.json");
-    const content = import_node_fs11.default.readFileSync(packagePath, "utf8");
+    const packagePath = import_node_path16.default.resolve(__dirname, "..", "package.json");
+    const content = import_node_fs12.default.readFileSync(packagePath, "utf8");
     const parsed = JSON.parse(content);
     return typeof parsed.version === "string" && parsed.version.trim() ? parsed.version : "0.0.0";
   } catch {
@@ -8218,9 +8428,9 @@ function resolveCliVersion() {
 function resolveCliScriptPath() {
   const argvPath = process.argv[1];
   if (argvPath && argvPath.trim()) {
-    return import_node_path15.default.resolve(argvPath);
+    return import_node_path16.default.resolve(argvPath);
   }
-  return import_node_path15.default.resolve(__dirname, "cli.js");
+  return import_node_path16.default.resolve(__dirname, "cli.js");
 }
 function maybeReexecServiceCommandWithSudo() {
   if (typeof process.getuid !== "function" || process.getuid() === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeharbor",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "Instant-messaging bridge for Codex CLI sessions",
   "license": "MIT",
   "main": "dist/cli.js",