@biaoo/tiangong-wiki 0.2.1 → 0.2.3

package/README.md

@@ -24,6 +24,21 @@
 npm install -g @biaoo/tiangong-wiki
 ```
 
+## Update
+
+Upgrade the npm package itself:
+
+```bash
+npm install -g @biaoo/tiangong-wiki@latest
+```
+
+Refresh workspace-local managed skills after upgrading the CLI or when upstream skill content changes:
+
+```bash
+tiangong-wiki skill status
+tiangong-wiki skill update --all
+```
+
 <details>
 <summary><strong>Use as an AI Agent Skill</strong></summary>
 
@@ -47,6 +62,7 @@ To manage workspace-local skills from arbitrary repo/path sources after setup:
 tiangong-wiki skill add ../my-skills --skill notes
 tiangong-wiki skill status
 tiangong-wiki skill update notes
+tiangong-wiki skill update --all
 ```
 
 </details>
@@ -61,7 +77,14 @@ tiangong-wiki init                                    # initialize workspace
 tiangong-wiki sync                                    # index Markdown pages
 ```
 
-`tiangong-wiki setup` creates `.wiki.env`. Subsequent commands such as `doctor`, `init`, and `sync` should be run from the workspace root containing that `.wiki.env`, or with `WIKI_ENV_FILE` pointing to it explicitly.
+`tiangong-wiki setup` creates a workspace-local `.wiki.env` and records it as your default workspace config. Command resolution now follows this order:
+
+1. `--env-file <path>`
+2. `WIKI_ENV_FILE`
+3. The nearest `.wiki.env` found by walking upward from your current directory
+4. The global default workspace config written by `tiangong-wiki setup`
+
+That means commands still work best from inside a workspace, but they can also run from outside the workspace after setup, or target a specific workspace explicitly with `--env-file`.
 
 ```bash
 tiangong-wiki find --type concept --status active     # structured query
@@ -71,11 +94,12 @@ tiangong-wiki graph bayes-theorem --depth 2           # graph traversal
 ```
 
 ```bash
-tiangong-wiki daemon run                              # start dashboard & HTTP API
+tiangong-wiki daemon start                            # start the daemon in the background
 tiangong-wiki dashboard                               # open dashboard in browser
+# or: tiangong-wiki daemon run                        # run the daemon in the foreground for debugging
 ```
 
-> Environment variables are managed via `.wiki.env` (created by `tiangong-wiki setup`). The CLI auto-discovers the nearest `.wiki.env` by walking upward from your current directory. See [references/troubleshooting.md](./references/troubleshooting.md) for the full reference.
+> Environment variables are managed via `.wiki.env` (created by `tiangong-wiki setup`). The CLI prefers the nearest local `.wiki.env`, then falls back to the global default workspace config. See [references/troubleshooting.md](./references/troubleshooting.md) for the full reference.
 
 ## CLI
 

package/README.zh-CN.md

@@ -24,6 +24,21 @@
 npm install -g @biaoo/tiangong-wiki
 ```
 
+## 更新
+
+升级 npm 包本身：
+
+```bash
+npm install -g @biaoo/tiangong-wiki@latest
+```
+
+升级 CLI 后，或上游 skill 内容有更新时，刷新工作区本地 managed skills：
+
+```bash
+tiangong-wiki skill status
+tiangong-wiki skill update --all
+```
+
 <details>
 <summary><strong>作为 AI Agent Skill 使用</strong></summary>
 
@@ -47,6 +62,7 @@ tiangong-wiki setup
 tiangong-wiki skill add ../my-skills --skill notes
 tiangong-wiki skill status
 tiangong-wiki skill update notes
+tiangong-wiki skill update --all
 ```
 
 </details>
@@ -61,7 +77,14 @@ tiangong-wiki init                                    # 初始化工作区
 tiangong-wiki sync                                    # 索引 Markdown 文件
 ```
 
-`tiangong-wiki setup` 会创建 `.wiki.env`。后续的 `doctor`、`init`、`sync` 等命令应在包含该 `.wiki.env` 的工作区根目录执行；如果不在该目录执行，则需要显式设置 `WIKI_ENV_FILE` 指向它。
+`tiangong-wiki setup` 会创建工作区本地 `.wiki.env`，并将其记录为默认工作区配置。CLI 的配置解析优先级如下：
+
+1. `--env-file <path>`
+2. `WIKI_ENV_FILE`
+3. 从当前目录向上查找最近的 `.wiki.env`
+4. `tiangong-wiki setup` 写入的全局默认工作区配置
+
+这意味着命令仍然最适合在 workspace 内执行；但 setup 之后，即使在 workspace 外运行，也可以通过默认配置正常工作，或者通过 `--env-file` 显式指定目标工作区。
 
 ```bash
 tiangong-wiki find --type concept --status active     # 结构化查询
@@ -71,11 +94,12 @@ tiangong-wiki graph bayes-theorem --depth 2           # 图遍历
 ```
 
 ```bash
-tiangong-wiki daemon run                              # 启动仪表盘和 HTTP API
+tiangong-wiki daemon start                            # 后台启动 daemon
 tiangong-wiki dashboard                               # 在浏览器中打开仪表盘
+# 或者：tiangong-wiki daemon run                      # 前台运行 daemon，适合调试
 ```
 
-> 环境变量通过 `.wiki.env` 管理（由 `tiangong-wiki setup` 创建）。CLI 会从当前目录开始向上自动发现最近的 `.wiki.env`。完整参考见 [references/troubleshooting.md](./references/troubleshooting.md)。
+> 环境变量通过 `.wiki.env` 管理（由 `tiangong-wiki setup` 创建）。CLI 会优先使用最近的本地 `.wiki.env`，找不到时再 fallback 到全局默认工作区配置。完整参考见 [references/troubleshooting.md](./references/troubleshooting.md)。
 
 ## CLI
 

package/dist/core/cli-env.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { readGlobalConfig } from "./global-config.js";
 import { pathExistsSync, readTextFileSync } from "../utils/fs.js";
 export const DEFAULT_WIKI_ENV_FILE = ".wiki.env";
 const EMPTY_INFO = {
@@ -6,6 +7,10 @@ const EMPTY_INFO = {
     loadedPath: null,
     autoDiscovered: false,
     missingRequestedPath: false,
+    missingDefaultPath: false,
+    source: "none",
+    globalConfigPath: null,
+    defaultPath: null,
     loadedKeys: [],
 };
 let lastCliEnvInfo = EMPTY_INFO;
@@ -86,20 +91,40 @@ export function applyCliEnvironment(targetEnv = process.env, cwd = process.cwd()
     const requestedEnvFile = targetEnv.WIKI_ENV_FILE?.trim();
     const requestedPath = requestedEnvFile ? path.resolve(cwd, requestedEnvFile) : null;
     if (!requestedPath && hasExplicitCoreRuntimeEnv(targetEnv)) {
-        lastCliEnvInfo = { ...EMPTY_INFO };
+        lastCliEnvInfo = { ...EMPTY_INFO, source: "process-env" };
         return lastCliEnvInfo;
     }
-    const candidatePath = requestedPath ?? findNearestEnvFile(cwd);
+    const nearestPath = requestedPath ? null : findNearestEnvFile(cwd);
+    const globalConfig = requestedPath || nearestPath ? null : readGlobalConfig(targetEnv);
+    const defaultPath = globalConfig ? path.resolve(globalConfig.defaultEnvFile) : null;
+    const candidatePath = requestedPath ?? nearestPath ?? defaultPath;
+    const source = requestedPath
+        ? "explicit-env-file"
+        : nearestPath
+            ? "nearest-env-file"
+            : defaultPath
+                ? "global-default-env-file"
+                : "none";
     if (!candidatePath) {
-        lastCliEnvInfo = { ...EMPTY_INFO, requestedPath };
+        lastCliEnvInfo = {
+            ...EMPTY_INFO,
+            requestedPath,
+            source,
+            globalConfigPath: globalConfig?.configPath ?? null,
+            defaultPath,
+        };
         return lastCliEnvInfo;
     }
     if (!pathExistsSync(candidatePath)) {
         lastCliEnvInfo = {
             requestedPath: candidatePath,
             loadedPath: null,
-            autoDiscovered: false,
+            autoDiscovered: source === "nearest-env-file",
             missingRequestedPath: requestedPath !== null,
+            missingDefaultPath: requestedPath === null && source === "global-default-env-file",
+            source,
+            globalConfigPath: globalConfig?.configPath ?? null,
+            defaultPath,
             loadedKeys: [],
         };
         return lastCliEnvInfo;
@@ -118,8 +143,12 @@ export function applyCliEnvironment(targetEnv = process.env, cwd = process.cwd()
     lastCliEnvInfo = {
         requestedPath,
         loadedPath: candidatePath,
-        autoDiscovered: requestedPath === null,
+        autoDiscovered: source === "nearest-env-file",
         missingRequestedPath: false,
+        missingDefaultPath: false,
+        source,
+        globalConfigPath: globalConfig?.configPath ?? null,
+        defaultPath,
         loadedKeys,
     };
     return lastCliEnvInfo;

package/dist/core/codex-workflow.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { Codex } from "@openai/codex-sdk";
 import { readWorkflowResult } from "./workflow-result.js";
+import { resolveAgentSettings } from "./paths.js";
 import { readTextFileSync, writeTextFileSync } from "../utils/fs.js";
 import { AppError } from "../utils/errors.js";
 export const CODEX_WORKFLOW_VERSION = "2026-04-07";
@@ -85,16 +86,10 @@ async function runThread(thread, input) {
                 continue;
             }
             if (event.type === "turn.failed") {
-                throw new AppError("Codex workflow turn failed", "runtime", {
-                    cause: event.error.message,
-                    threadId: activeThreadId,
-                });
+                throw classifyWorkflowRuntimeError("Codex workflow turn failed", event.error.message, activeThreadId);
             }
             if (event.type === "error") {
-                throw new AppError("Codex workflow stream failed", "runtime", {
-                    cause: event.message,
-                    threadId: activeThreadId,
-                });
+                throw classifyWorkflowRuntimeError("Codex workflow stream failed", event.message, activeThreadId);
             }
         }
     }
@@ -103,10 +98,7 @@ async function runThread(thread, input) {
             throw error;
         }
         const message = error instanceof Error ? error.message : String(error);
-        throw new AppError("Codex workflow turn failed", "runtime", {
-            cause: message,
-            threadId: activeThreadId,
-        });
+        throw classifyWorkflowRuntimeError("Codex workflow turn failed", message, activeThreadId);
     }
     if (!activeThreadId && thread.id) {
         activeThreadId = thread.id;
@@ -118,6 +110,10 @@ async function runThread(thread, input) {
     return activeThreadId;
 }
 export class CodexSdkWorkflowRunner {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
     // The SDK can only continue a thread by sending a new input, so queue retries
     // must not automatically resume real workflow threads inline.
     async startWorkflow(input) {
@@ -127,7 +123,7 @@ export class CodexSdkWorkflowRunner {
             modelReasoningEffort: "low",
             workingDirectory: input.workspaceRoot,
             skipGitRepoCheck: true,
-            sandboxMode: "workspace-write",
+            sandboxMode: this.options.sandboxMode ?? "danger-full-access",
             networkAccessEnabled: true,
             approvalPolicy: "never",
             webSearchMode: "disabled",
@@ -143,7 +139,7 @@ export class CodexSdkWorkflowRunner {
             modelReasoningEffort: "low",
             workingDirectory: input.workspaceRoot,
             skipGitRepoCheck: true,
-            sandboxMode: "workspace-write",
+            sandboxMode: this.options.sandboxMode ?? "danger-full-access",
             networkAccessEnabled: true,
             approvalPolicy: "never",
             webSearchMode: "disabled",
@@ -229,5 +225,31 @@ export function createDefaultWorkflowRunner(env = process.env) {
         const delayMs = Number.parseInt(env.WIKI_TEST_FAKE_WORKFLOW_DELAY_MS ?? "0", 10) || 0;
         return createSkipOnlyTestWorkflowRunner({ delayMs, mode: "delay-skip" });
     }
-    return new CodexSdkWorkflowRunner();
+    return new CodexSdkWorkflowRunner({
+        sandboxMode: resolveAgentSettings(env).sandboxMode,
+    });
+}
+function isSandboxStartupFailure(message) {
+    const normalized = message.toLowerCase();
+    return (normalized.includes("bwrap") ||
+        normalized.includes("bubblewrap") ||
+        normalized.includes("uid map") ||
+        normalized.includes("uid_map") ||
+        normalized.includes("gid map") ||
+        normalized.includes("gid_map") ||
+        normalized.includes("unshare") ||
+        normalized.includes("operation not permitted"));
+}
+function classifyWorkflowRuntimeError(baseMessage, cause, threadId) {
+    if (isSandboxStartupFailure(cause)) {
+        return new AppError("Codex workflow sandbox failed to initialize", "runtime", {
+            cause,
+            threadId,
+            phase: "sandbox",
+        });
+    }
+    return new AppError(baseMessage, "runtime", {
+        cause,
+        threadId,
+    });
 }

package/dist/core/global-config.js

@@ -0,0 +1,61 @@
+import os from "node:os";
+import path from "node:path";
+import { AppError } from "../utils/errors.js";
+import { ensureDirSync, pathExistsSync, readTextFileSync, writeTextFileSync } from "../utils/fs.js";
+export const GLOBAL_CONFIG_DIRNAME = "tiangong-wiki";
+export const GLOBAL_CONFIG_FILENAME = "config.json";
+function resolveConfigBaseDir(env = process.env) {
+    const xdgConfigHome = env.XDG_CONFIG_HOME?.trim();
+    if (xdgConfigHome) {
+        return path.resolve(xdgConfigHome);
+    }
+    const homeDir = env.HOME?.trim() || os.homedir();
+    return path.join(homeDir, ".config");
+}
+export function resolveGlobalConfigPath(env = process.env) {
+    return path.join(resolveConfigBaseDir(env), GLOBAL_CONFIG_DIRNAME, GLOBAL_CONFIG_FILENAME);
+}
+export function readGlobalConfig(env = process.env) {
+    const configPath = resolveGlobalConfigPath(env);
+    if (!pathExistsSync(configPath)) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readTextFileSync(configPath));
+    }
+    catch (error) {
+        throw new AppError(`Failed to parse global CLI config JSON: ${configPath}`, "config", {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new AppError(`Global CLI config must be an object: ${configPath}`, "config");
+    }
+    const schemaVersion = parsed.schemaVersion;
+    if (!Number.isInteger(schemaVersion) || Number(schemaVersion) < 1) {
+        throw new AppError(`Global CLI config schemaVersion must be a positive integer: ${configPath}`, "config");
+    }
+    const defaultEnvFile = parsed.defaultEnvFile;
+    if (typeof defaultEnvFile !== "string" || defaultEnvFile.trim().length === 0) {
+        throw new AppError(`Global CLI config defaultEnvFile must be a non-empty string: ${configPath}`, "config");
+    }
+    return {
+        configPath,
+        defaultEnvFile: path.resolve(defaultEnvFile),
+    };
+}
+export function writeGlobalConfig(defaultEnvFile, env = process.env) {
+    const configPath = resolveGlobalConfigPath(env);
+    const normalizedEnvFile = path.resolve(defaultEnvFile);
+    const payload = {
+        schemaVersion: 1,
+        defaultEnvFile: normalizedEnvFile,
+    };
+    ensureDirSync(path.dirname(configPath));
+    writeTextFileSync(configPath, `${JSON.stringify(payload, null, 2)}\n`);
+    return {
+        configPath,
+        defaultEnvFile: normalizedEnvFile,
+    };
+}

package/dist/core/onboarding.js

@@ -5,7 +5,8 @@ import { confirm, input, password, select } from "@inquirer/prompts";
 import { DEFAULT_WIKI_ENV_FILE, getCliEnvironmentInfo, parseEnvFile, serializeEnvEntries } from "./cli-env.js";
 import { resolveTemplateFilePath, loadConfig } from "./config.js";
 import { EmbeddingClient } from "./embedding.js";
-import { parseVaultHashMode, resolveAgentSettings } from "./paths.js";
+import { writeGlobalConfig } from "./global-config.js";
+import { parseVaultHashMode, parseWikiAgentSandboxMode, resolveAgentSettings } from "./paths.js";
 import { loadSynologyConfigFromEnv, normalizeSynologyRemotePath, withSynologyClient } from "./synology.js";
 import { ensureWikiSkillInstall, formatParserSkills, inspectSkillInstall, installParserSkill, OPTIONAL_PARSER_SKILLS, parseParserSkillSelection, parseParserSkills, resolveWorkspaceRootFromWikiPath, resolveWorkspaceSkillPath, resolveWorkspaceSkillPaths, } from "./workspace-skills.js";
 import { scaffoldWorkspaceAssets } from "./workspace-bootstrap.js";
@@ -35,11 +36,16 @@ const MANAGED_ENV_KEYS = new Set([
     "WIKI_AGENT_API_KEY",
     "WIKI_AGENT_MODEL",
     "WIKI_AGENT_BATCH_SIZE",
+    "WIKI_AGENT_SANDBOX_MODE",
     "WIKI_PARSER_SKILLS",
 ]);
 function writeSection(output, title) {
     output.write(`\n${title}\n`);
 }
+function writeWarning(output, message) {
+    const isTty = "isTTY" in output && output.isTTY;
+    output.write(isTty ? `\x1b[31m${message}\x1b[0m\n` : `${message}\n`);
+}
 function resolvePackageRoot(packageRoot) {
     return packageRoot ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 }
@@ -72,6 +78,14 @@ function safeVaultHashMode(rawValue, defaultValue) {
         return defaultValue;
     }
 }
+function safeAgentSandboxMode(rawValue) {
+    try {
+        return parseWikiAgentSandboxMode(rawValue);
+    }
+    catch {
+        return "danger-full-access";
+    }
+}
 function safeBooleanFlag(rawValue, defaultValue) {
     if (rawValue === undefined || rawValue.trim().length === 0) {
         return defaultValue;
@@ -380,6 +394,7 @@ function getPathDefaults(env, cwd) {
         agentApiKey: env.WIKI_AGENT_API_KEY ?? null,
         agentModel: env.WIKI_AGENT_MODEL ?? null,
         agentBatchSize: env.WIKI_AGENT_BATCH_SIZE ?? "5",
+        agentSandboxMode: safeAgentSandboxMode(env.WIKI_AGENT_SANDBOX_MODE),
         parserSkills: parseParserSkills(env.WIKI_PARSER_SKILLS, { strict: false }),
     };
 }
@@ -446,14 +461,32 @@ async function collectAgentSettings(driver, ctx, defaults) {
             agentApiKey: null,
             agentModel: null,
             agentBatchSize: null,
+            agentSandboxMode: null,
         };
     }
+    writeWarning(ctx.output, "Warning: danger-full-access grants full access to the runtime workspace.");
     return {
         agentEnabled: true,
         agentBaseUrl: await promptText(driver, "WIKI_AGENT_BASE_URL", defaults.agentBaseUrl ?? "https://api.openai.com/v1", { validator: (value) => validateUrl(value, "WIKI_AGENT_BASE_URL") }),
         agentApiKey: await promptPassword(driver, "WIKI_AGENT_API_KEY", defaults.agentApiKey ?? "", { required: true }),
         agentModel: await promptText(driver, "WIKI_AGENT_MODEL", defaults.agentModel ?? "", { required: true }),
         agentBatchSize: await promptText(driver, "WIKI_AGENT_BATCH_SIZE", defaults.agentBatchSize ?? "5", { validator: (value) => validateNonNegativeInteger(value, "WIKI_AGENT_BATCH_SIZE") }),
+        agentSandboxMode: await driver.select({
+            message: "WIKI_AGENT_SANDBOX_MODE",
+            defaultValue: defaults.agentSandboxMode ?? "danger-full-access",
+            choices: [
+                {
+                    value: "danger-full-access",
+                    label: "danger-full-access",
+                    description: "Full access to the runtime workspace. Default.",
+                },
+                {
+                    value: "workspace-write",
+                    label: "workspace-write",
+                    description: "Use Codex workspace-write sandbox when the host supports it.",
+                },
+            ],
+        }),
     };
 }
 async function collectSynologySettings(driver, ctx, defaults) {
@@ -531,6 +564,7 @@ function buildSetupSummary(values) {
         lines.push(`  WIKI_AGENT_BASE_URL: ${values.agentBaseUrl}`);
         lines.push(`  WIKI_AGENT_MODEL: ${values.agentModel}`);
         lines.push(`  WIKI_AGENT_BATCH_SIZE: ${values.agentBatchSize}`);
+        lines.push(`  WIKI_AGENT_SANDBOX_MODE: ${values.agentSandboxMode}`);
     }
     if (values.vaultSource === "synology") {
         lines.push(`  SYNOLOGY_BASE_URL: ${values.synologyBaseUrl}`);
@@ -568,6 +602,7 @@ function writeSetupEnvFile(values) {
         ["WIKI_AGENT_API_KEY", values.agentEnabled ? values.agentApiKey : null],
         ["WIKI_AGENT_MODEL", values.agentEnabled ? values.agentModel : null],
         ["WIKI_AGENT_BATCH_SIZE", values.agentEnabled ? values.agentBatchSize : null],
+        ["WIKI_AGENT_SANDBOX_MODE", values.agentEnabled ? values.agentSandboxMode : null],
         ["WIKI_PARSER_SKILLS", formatParserSkills(values.parserSkills)],
     ];
     const body = [
@@ -672,9 +707,11 @@ export async function runSetupWizard(env = process.env, options = {}) {
             output,
         }));
         writeSetupEnvFile(values);
+        const globalConfig = writeGlobalConfig(values.envFilePath, env);
         output.write([
             "\ntiangong-wiki setup complete",
             `configuration file: ${values.envFilePath}`,
+            `default workspace config: ${globalConfig.configPath}`,
             `workspace root: ${workspaceRoot}`,
             `skills root: ${skillsRoot}`,
             `tiangong-wiki-skill: ${wikiSkillInstall.status}`,
@@ -687,8 +724,10 @@ export async function runSetupWizard(env = process.env, options = {}) {
                 : []),
             "",
             "Next steps:",
-            `- Run subsequent commands from the workspace root that contains .wiki.env: ${workspaceRoot}`,
+            `- Commands inside ${JSON.stringify(workspaceRoot)} will auto-discover the local .wiki.env first.`,
+            `- Commands outside the workspace will fall back to the default workspace config at ${globalConfig.configPath}.`,
             `- Example: cd ${JSON.stringify(workspaceRoot)} && tiangong-wiki doctor`,
+            `- Example: tiangong-wiki --env-file ${JSON.stringify(values.envFilePath)} doctor`,
             `- Example: cd ${JSON.stringify(workspaceRoot)} && tiangong-wiki init`,
             "- Run `tiangong-wiki doctor` to validate the generated configuration.",
             "- Run `tiangong-wiki init` to create index.db and perform the first sync.",
@@ -701,6 +740,7 @@ export async function runSetupWizard(env = process.env, options = {}) {
         ].join("\n"));
         return {
             envFilePath: values.envFilePath,
+            globalConfigPath: globalConfig.configPath,
             createdDirectories: bootstrap.createdDirectories,
             copiedConfig: bootstrap.copiedConfig,
             copiedTemplates: bootstrap.copiedTemplates,
@@ -1017,11 +1057,26 @@ export async function buildDoctorReport(env = process.env, options = {}) {
     if (envFile.missingRequestedPath && envFile.requestedPath) {
         collectDoctorCheck(checks, "error", "env-file", `Requested env file does not exist: ${envFile.requestedPath}`, "Create the env file or rerun `tiangong-wiki setup`.");
     }
+    else if (envFile.missingDefaultPath && envFile.defaultPath) {
+        collectDoctorCheck(checks, "error", "env-file", `The default workspace config points to a missing env file: ${envFile.defaultPath}`, envFile.globalConfigPath
+            ? `Fix or remove ${envFile.globalConfigPath}, rerun \`tiangong-wiki setup\`, or pass \`--env-file\` explicitly.`
+            : "Fix the default workspace config, rerun `tiangong-wiki setup`, or pass `--env-file` explicitly.");
+    }
     else if (envFile.loadedPath) {
-        collectDoctorCheck(checks, "ok", "env-file", `Loaded configuration from ${envFile.loadedPath}${envFile.autoDiscovered ? " (auto-discovered)." : "."}`);
+        const sourceLabel = envFile.source === "explicit-env-file"
+            ? "from --env-file or WIKI_ENV_FILE."
+            : envFile.source === "nearest-env-file"
+                ? "from the current workspace (auto-discovered)."
+                : envFile.source === "global-default-env-file"
+                    ? "from the global default workspace config."
+                    : ".";
+        collectDoctorCheck(checks, "ok", "env-file", `Loaded configuration from ${envFile.loadedPath} ${sourceLabel}`);
+    }
+    else if (envFile.source === "process-env") {
+        collectDoctorCheck(checks, "ok", "env-file", "Using runtime paths provided directly via process.env; no .wiki.env file was loaded.");
     }
     else {
-        collectDoctorCheck(checks, "warn", "env-file", "No .wiki.env file was loaded; using process.env only.", "Run `tiangong-wiki setup` to generate a portable `.wiki.env` file.");
+        collectDoctorCheck(checks, "warn", "env-file", "No workspace configuration was found from --env-file, WIKI_ENV_FILE, the current directory, or the global default workspace config.", "Run `tiangong-wiki setup`, set `WIKI_ENV_FILE`, or pass `--env-file` to point at a workspace explicitly.");
     }
     const wikiPath = env.WIKI_PATH ? path.resolve(env.WIKI_PATH) : null;
     const wikiRoot = wikiPath ? path.resolve(wikiPath, "..") : null;
@@ -1055,6 +1110,10 @@ export async function buildDoctorReport(env = process.env, options = {}) {
             loadedPath: envFile.loadedPath,
             autoDiscovered: envFile.autoDiscovered,
             missingRequestedPath: envFile.missingRequestedPath,
+            missingDefaultPath: envFile.missingDefaultPath,
+            source: envFile.source,
+            globalConfigPath: envFile.globalConfigPath,
+            defaultPath: envFile.defaultPath,
         },
         effectivePaths: {
             wikiPath,

package/dist/core/paths.js

@@ -89,12 +89,20 @@ export function parseWikiAgentBackend(raw) {
     }
     throw new AppError(`WIKI_AGENT_BACKEND must be "codex-workflow", got ${raw}`, "config");
 }
+export function parseWikiAgentSandboxMode(raw) {
+    const value = (raw ?? "danger-full-access").trim().toLowerCase();
+    if (value === "danger-full-access" || value === "workspace-write") {
+        return value;
+    }
+    throw new AppError(`WIKI_AGENT_SANDBOX_MODE must be "danger-full-access" or "workspace-write", got ${raw}`, "config");
+}
 export function resolveAgentSettings(env = process.env, options = {}) {
     const enabled = parseBooleanFlag("WIKI_AGENT_ENABLED", env.WIKI_AGENT_ENABLED, false);
     const baseUrl = normalizeOptionalUrl(env.WIKI_AGENT_BASE_URL);
     const apiKey = env.WIKI_AGENT_API_KEY?.trim() || null;
     const model = env.WIKI_AGENT_MODEL?.trim() || null;
     const batchSize = parseNonNegativeInteger(env.WIKI_AGENT_BATCH_SIZE, 5, "WIKI_AGENT_BATCH_SIZE");
+    const sandboxMode = parseWikiAgentSandboxMode(env.WIKI_AGENT_SANDBOX_MODE);
     const workflowTimeoutSeconds = parsePositiveInteger(env.WIKI_WORKFLOW_TIMEOUT, 600, "WIKI_WORKFLOW_TIMEOUT");
     const missing = [];
     if (enabled) {
@@ -114,6 +122,7 @@ export function resolveAgentSettings(env = process.env, options = {}) {
         apiKey,
         model,
         batchSize,
+        sandboxMode,
         workflowTimeoutSeconds,
         configured: enabled && missing.length === 0,
         missing,

package/dist/core/workflow-result.js

@@ -148,6 +148,11 @@ export function readWorkflowResult(resultPath) {
         fail(`Workflow result not found: ${resultPath}`);
     }
     const rawText = readTextFileSync(resultPath);
+    if (!rawText.trim()) {
+        fail("Workflow result is empty", {
+            resultPath,
+        });
+    }
     let parsed;
     try {
         parsed = JSON.parse(rawText);

package/dist/index.js

@@ -29,12 +29,39 @@ import { loadRuntimeConfig } from "./core/runtime.js";
 import { embedPendingPages } from "./core/sync.js";
 import { processVaultQueueBatch } from "./core/vault-processing.js";
 import { handleCliError, writeJson } from "./utils/output.js";
+function extractEnvFileOption(argv) {
+    const nextArgv = argv.slice(0, 2);
+    let envFile = null;
+    for (let index = 2; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--env-file") {
+            const value = argv[index + 1];
+            if (!value || value.startsWith("-")) {
+                throw new Error("--env-file requires a value");
+            }
+            envFile = value;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--env-file=")) {
+            const value = arg.slice("--env-file=".length);
+            if (!value) {
+                throw new Error("--env-file requires a value");
+            }
+            envFile = value;
+            continue;
+        }
+        nextArgv.push(arg);
+    }
+    return { envFile, argv: nextArgv };
+}
 function buildProgram() {
     const program = new Command();
     program
         .name("tiangong-wiki")
         .description("Tiangong Wiki — local-first indexing and query CLI")
         .version(packageJson.version)
+        .option("--env-file <path>", "Load runtime environment from a specific .wiki.env file")
         .showHelpAfterError();
     let runtimeConfig;
     try {
@@ -81,9 +108,13 @@ function buildProgram() {
     return program;
 }
 try {
+    const { envFile, argv } = extractEnvFileOption(process.argv);
+    if (envFile) {
+        process.env.WIKI_ENV_FILE = envFile;
+    }
     applyCliEnvironment(process.env, process.cwd());
     const program = buildProgram();
-    await program.parseAsync(process.argv);
+    await program.parseAsync(argv);
 }
 catch (error) {
     handleCliError(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biaoo/tiangong-wiki",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Local-first wiki index and query engine for Markdown knowledge pages (Tiangong Wiki).",
   "type": "module",
   "publishConfig": {

package/references/cli-interface.md

@@ -13,6 +13,13 @@ npx @biaoo/tiangong-wiki <command> [options]
 npm run dev -- <command> [options]
 ```
 
+Global workspace resolution priority:
+
+1. `--env-file <path>`
+2. `WIKI_ENV_FILE`
+3. nearest `.wiki.env` found by walking upward from the current directory
+4. the global default workspace config written by `tiangong-wiki setup`
+
 ---
 
 ## Command Overview
@@ -57,6 +64,7 @@ Interactive step-by-step wizard that:
 - Records `WIKI_PATH`, `VAULT_PATH`, `WIKI_DB_PATH`, `WIKI_CONFIG_PATH`, `WIKI_TEMPLATES_PATH`
 - Optionally configures `EMBEDDING_*` and Synology vault settings
 - Writes `.wiki.env` in the current working directory
+- Writes a global default workspace config pointing to that `.wiki.env`
 - Scaffolds `wiki/pages/`, `vault/`, `wiki.config.json`, and `templates/`
 
 After setup, run `tiangong-wiki doctor` then `tiangong-wiki init` to complete initialization.
@@ -64,11 +72,12 @@ After setup, run `tiangong-wiki doctor` then `tiangong-wiki init` to complete in
 ### doctor
 
 ```
-tiangong-wiki doctor [--probe] [--format text|json]
+tiangong-wiki doctor [--env-file <path>] [--probe] [--format text|json]
 ```
 
 | Option | Description |
 | --- | --- |
+| `--env-file` | Load a specific `.wiki.env` before running the command |
 | `--probe` | Additionally test remote services (embedding endpoint, Synology NAS) |
 | `--format` | Output format: `text` (default) or `json` |
 

package/references/troubleshooting.md

@@ -73,8 +73,11 @@ The agent uses [Codex SDK](https://www.npmjs.com/package/@openai/codex-sdk) to p
 | `WIKI_AGENT_API_KEY` | If enabled | API key for the LLM provider |
 | `WIKI_AGENT_MODEL` | No | Model name (e.g. `gpt-5.4`, `Qwen/Qwen3.5-397B-A17B-GPTQ-Int4`) |
 | `WIKI_AGENT_BATCH_SIZE` | No | Max concurrent vault items per batch (default: `5`) |
+| `WIKI_AGENT_SANDBOX_MODE` | No | Codex sandbox mode: `danger-full-access` (default) or `workspace-write` |
 | `WIKI_PARSER_SKILLS` | No | Comma-separated parser skill list (e.g. `pdf,docx,pptx,xlsx`) |
 
+`tiangong-wiki setup` now prompts for `WIKI_AGENT_SANDBOX_MODE` when automatic vault processing is enabled. The default is `danger-full-access`, and the setup wizard highlights that this mode grants full runtime access.
+
 ---
 
 ## Common Issues
@@ -102,6 +105,10 @@ Always run `tiangong-wiki lint --path <page-id> --format json` after mutations.
 
 Parser skills must be installed under `<workspace-root>/.agents/skills/`. Run `tiangong-wiki skill` to inspect installed skills. Use `tiangong-wiki skill update --all` to update.
 
+### Codex workflow sandbox fails to initialize
+
+If the agent workflow fails with `bwrap`, `unshare`, `uid_map`, or similar sandbox startup errors, switch `WIKI_AGENT_SANDBOX_MODE` to `danger-full-access`. Use `workspace-write` only when you explicitly want that sandbox mode and know the host supports it.
+
 ---
 
 ## LLM Provider Setup