@biaoo/tiangong-wiki 0.3.6 → 0.3.8

package/README.md

@@ -86,6 +86,8 @@ tiangong-wiki sync                                    # index Markdown pages
 
 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`.
 
+For automatic vault processing, new setup runs default to `WIKI_AGENT_AUTH_MODE=codex-login`, the current user's standard Codex home (`~/.codex`, or the user profile `.codex` directory on Windows), and `WIKI_AGENT_MODEL=gpt-5.5`. If you want an isolated Codex home, set `WIKI_AGENT_CODEX_HOME=/absolute/path/to/.codex-tiangong-wiki` and first run `CODEX_HOME=/absolute/path/to/.codex-tiangong-wiki codex login`.
+
 ```bash
 tiangong-wiki find --type concept --status active     # structured query
 tiangong-wiki fts "Bayesian"                          # full-text search

package/README.zh-CN.md

@@ -86,6 +86,8 @@ tiangong-wiki sync                                    # 索引 Markdown 文件
 
 这意味着命令仍然最适合在 workspace 内执行；但 setup 之后，即使在 workspace 外运行，也可以通过默认配置正常工作，或者通过 `--env-file` 显式指定目标工作区。
 
+如果启用自动 vault 处理，新的 setup 默认使用 `WIKI_AGENT_AUTH_MODE=codex-login`、当前用户标准 Codex home（Linux/macOS 为 `~/.codex`，Windows 为用户目录下的 `.codex`）和 `WIKI_AGENT_MODEL=gpt-5.5`。如果需要隔离目录，可手动设置 `WIKI_AGENT_CODEX_HOME=/absolute/path/to/.codex-tiangong-wiki`，并先执行 `CODEX_HOME=/absolute/path/to/.codex-tiangong-wiki codex login`。
+
 ```bash
 tiangong-wiki find --type concept --status active     # 结构化查询
 tiangong-wiki fts "贝叶斯"                             # 全文搜索

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tiangong-wiki-skill
-description: "Use when you need to retrieve historically accumulated knowledge, methods, or behavioral patterns before answering or acting; when a conversation or workflow produces durable insights worth preserving for future reuse; or when you discover existing wiki content that is outdated or incorrect and needs correction."
+description: "Use when you need to retrieve historically accumulated knowledge, methods, or behavioral patterns before answering or acting; when a conversation or workflow produces durable insights worth preserving for future reuse; or when existing wiki content is outdated or incorrect. On Windows native shells or Codex automation, invoke the CLI as tiangong-wiki.cmd."
 ---
 
 # Wiki Skill
@@ -9,6 +9,20 @@ description: "Use when you need to retrieve historically accumulated knowledge,
 
 Use the local wiki as the **durable knowledge layer** — not just for the current conversation, but for all future work. Query first, then read or edit the Markdown files that remain the source of truth.
 
+## CLI Entrypoint
+
+Use `tiangong-wiki <command>` on macOS, Linux, WSL, and Git Bash.
+
+On Windows native shells such as PowerShell, Command Prompt, background daemon tasks, or Codex worker automation, use the npm command shim explicitly:
+
+```powershell
+tiangong-wiki.cmd doctor
+tiangong-wiki.cmd sync
+tiangong-wiki.cmd lint --format json
+```
+
+Do not invoke the suffixless `tiangong-wiki` executable from Windows native shells. npm also installs that shebang script for POSIX-like environments, but Windows may treat it as an unknown file and open the "choose an app" dialog instead of executing the CLI.
+
 ## When to Use
 
 Activate this skill in three scenarios:

package/assets/config.example.env

@@ -8,7 +8,23 @@ WIKI_SYNC_INTERVAL=86400
 EMBEDDING_BASE_URL=https://api.openai.com/v1
 EMBEDDING_API_KEY=your-embedding-api-key
 EMBEDDING_MODEL=text-embedding-3-small
-EMBEDDING_DIMENSIONS=384
+EMBEDDING_DIMENSIONS=1536
+
+WIKI_AGENT_ENABLED=false
+# For local Codex login auth, run `codex login` once as the same user.
+WIKI_AGENT_AUTH_MODE=codex-login
+# Optional. Leave unset to use the current user's standard Codex home: <home>/.codex
+# For an isolated directory, set this to an absolute path and first run:
+# CODEX_HOME=/absolute/path/to/.codex-tiangong-wiki codex login
+# WIKI_AGENT_CODEX_HOME=/absolute/path/to/.codex-tiangong-wiki
+#
+# To use an API key instead of Codex login:
+# WIKI_AGENT_AUTH_MODE=api-key
+# WIKI_AGENT_BASE_URL=https://api.openai.com/v1
+# WIKI_AGENT_API_KEY=sk-...
+WIKI_AGENT_MODEL=gpt-5.5
+WIKI_AGENT_BATCH_SIZE=5
+WIKI_AGENT_SANDBOX_MODE=danger-full-access
 
 VAULT_SOURCE=local
 # When VAULT_SOURCE=synology, also set:

package/dist/commands/check-config.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { inspectWikiAgentCodexLogin } from "../core/agent-auth.js";
 import { loadRuntimeConfig } from "../core/runtime.js";
 import { EmbeddingClient } from "../core/embedding.js";
 import { getWikiAgentStatus } from "../core/vault-processing.js";
@@ -20,6 +21,17 @@ export function registerCheckConfigCommand(program) {
         if (wikiAgent.enabled && wikiAgent.missing.length > 0) {
             throw new AppError(`WIKI_AGENT_ENABLED=true but missing required settings: ${wikiAgent.missing.join(", ")}`, "config");
         }
+        const agentCodexLogin = inspectWikiAgentCodexLogin(wikiAgent);
+        if (!agentCodexLogin.ready) {
+            throw new AppError([
+                agentCodexLogin.summary,
+                agentCodexLogin.recommendation,
+            ].filter(Boolean).join(" "), "config");
+        }
+        const safeWikiAgent = {
+            ...wikiAgent,
+            apiKey: wikiAgent.apiKey ? "<redacted>" : null,
+        };
         const templateChecks = Object.keys(config.templates).map((pageType) => {
             const templatePath = resolveTemplateFilePath(config, paths.wikiRoot, pageType);
             return {
@@ -44,7 +56,8 @@ export function registerCheckConfigCommand(program) {
             templatesPath: paths.templatesPath,
             configVersion: config.configVersion,
             embeddingConfigured: embeddingClient !== null,
-            agentProcessing: wikiAgent,
+            agentProcessing: safeWikiAgent,
+            agentCodexLogin,
             probe,
             templateChecks,
         };
@@ -63,11 +76,15 @@ export function registerCheckConfigCommand(program) {
                 embeddingConfigured: embeddingClient !== null,
                 agentEnabled: wikiAgent.enabled,
                 agentConfigured: wikiAgent.configured,
+                agentAuthMode: wikiAgent.authMode,
                 agentBaseUrl: wikiAgent.baseUrl ?? "",
+                agentCodexHome: wikiAgent.codexHome ?? "",
                 agentModel: wikiAgent.model ?? "",
                 agentBatchSize: wikiAgent.batchSize,
                 agentWorkflowTimeoutSeconds: wikiAgent.workflowTimeoutSeconds,
                 agentMissing: wikiAgent.missing.join(", "),
+                agentCodexLoginReady: agentCodexLogin.checked ? agentCodexLogin.ready : "",
+                agentCodexLoginAuthJson: agentCodexLogin.authJsonPath ?? "",
                 probe,
             }),
             "",

package/dist/core/agent-auth.js

@@ -0,0 +1,101 @@
+import { statSync } from "node:fs";
+import path from "node:path";
+function inspectPathKind(targetPath) {
+    try {
+        const stats = statSync(targetPath);
+        if (stats.isDirectory()) {
+            return { kind: "directory" };
+        }
+        if (stats.isFile()) {
+            return { kind: "file" };
+        }
+        return { kind: "other" };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ENOTDIR") {
+            return { kind: "missing" };
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return { kind: "inaccessible", errorMessage: message };
+    }
+}
+function codexLoginRecommendation(codexHome) {
+    return `Run \`CODEX_HOME=${codexHome} codex login\` before starting automatic vault processing.`;
+}
+export function inspectWikiAgentCodexLogin(settings) {
+    if (!settings.enabled || settings.authMode !== "codex-login") {
+        return {
+            checked: false,
+            ready: true,
+            codexHome: settings.codexHome,
+            authJsonPath: null,
+            summary: "Codex login auth is not enabled.",
+        };
+    }
+    if (!settings.codexHome) {
+        return {
+            checked: true,
+            ready: false,
+            codexHome: null,
+            authJsonPath: null,
+            summary: "WIKI_AGENT_CODEX_HOME is not configured for codex-login auth.",
+            recommendation: "Set WIKI_AGENT_CODEX_HOME or rerun `tiangong-wiki setup`.",
+        };
+    }
+    const codexHome = settings.codexHome;
+    const authJsonPath = path.join(codexHome, "auth.json");
+    const home = inspectPathKind(codexHome);
+    if (home.kind === "missing") {
+        return {
+            checked: true,
+            ready: false,
+            codexHome,
+            authJsonPath,
+            summary: `WIKI_AGENT_CODEX_HOME does not exist: ${codexHome}`,
+            recommendation: codexLoginRecommendation(codexHome),
+        };
+    }
+    if (home.kind !== "directory") {
+        return {
+            checked: true,
+            ready: false,
+            codexHome,
+            authJsonPath,
+            summary: home.kind === "inaccessible"
+                ? `WIKI_AGENT_CODEX_HOME cannot be inspected: ${codexHome} (${home.errorMessage})`
+                : `WIKI_AGENT_CODEX_HOME is not a directory: ${codexHome}`,
+            recommendation: codexLoginRecommendation(codexHome),
+        };
+    }
+    const authJson = inspectPathKind(authJsonPath);
+    if (authJson.kind === "missing") {
+        return {
+            checked: true,
+            ready: false,
+            codexHome,
+            authJsonPath,
+            summary: `Codex login auth.json was not found under WIKI_AGENT_CODEX_HOME: ${authJsonPath}`,
+            recommendation: codexLoginRecommendation(codexHome),
+        };
+    }
+    if (authJson.kind !== "file") {
+        return {
+            checked: true,
+            ready: false,
+            codexHome,
+            authJsonPath,
+            summary: authJson.kind === "inaccessible"
+                ? `Codex login auth.json cannot be inspected: ${authJsonPath} (${authJson.errorMessage})`
+                : `Codex login auth.json is not a file: ${authJsonPath}`,
+            recommendation: codexLoginRecommendation(codexHome),
+        };
+    }
+    return {
+        checked: true,
+        ready: true,
+        codexHome,
+        authJsonPath,
+        summary: `Codex login auth is available at ${codexHome}.`,
+    };
+}

package/dist/core/cli-env.js

@@ -27,7 +27,27 @@ function unquoteEnvValue(rawValue) {
         return value;
     }
     if (value.startsWith('"') && value.endsWith('"')) {
-        return value.slice(1, -1).replace(/\\n/g, "\n").replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+        const inner = value.slice(1, -1);
+        let output = "";
+        for (let index = 0; index < inner.length; index += 1) {
+            const current = inner[index];
+            if (current !== "\\" || index === inner.length - 1) {
+                output += current;
+                continue;
+            }
+            const next = inner[index + 1];
+            index += 1;
+            if (next === "n") {
+                output += "\n";
+            }
+            else if (next === '"' || next === "\\") {
+                output += next;
+            }
+            else {
+                output += `\\${next}`;
+            }
+        }
+        return output;
     }
     if (value.startsWith("'") && value.endsWith("'")) {
         return value.slice(1, -1);

package/dist/core/codex-workflow.js

@@ -1,28 +1,85 @@
 import path from "node:path";
-import { Codex } from "@openai/codex-sdk";
+import childProcess from "node:child_process";
+import { syncBuiltinESMExports } from "node:module";
 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";
+const hiddenWindowsSpawnPatch = Symbol.for("tiangong-wiki.hiddenWindowsSpawnPatch");
+function isSpawnOptions(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function addHiddenWindowDefault(options) {
+    if (!isSpawnOptions(options)) {
+        return { windowsHide: true };
+    }
+    return { ...options, windowsHide: options.windowsHide ?? true };
+}
+export function createHiddenWindowsSpawn(spawnFn) {
+    return ((command, argsOrOptions, options) => {
+        if (Array.isArray(argsOrOptions)) {
+            return spawnFn(command, argsOrOptions, addHiddenWindowDefault(options));
+        }
+        if (isSpawnOptions(argsOrOptions) && options === undefined) {
+            return spawnFn(command, addHiddenWindowDefault(argsOrOptions));
+        }
+        if (argsOrOptions === undefined && options === undefined) {
+            return spawnFn(command, addHiddenWindowDefault(undefined));
+        }
+        return spawnFn(command, argsOrOptions, addHiddenWindowDefault(options));
+    });
+}
+function installHiddenWindowsSpawnPatch(platform = process.platform) {
+    if (platform !== "win32") {
+        return;
+    }
+    const currentSpawn = childProcess.spawn;
+    if (currentSpawn[hiddenWindowsSpawnPatch]) {
+        return;
+    }
+    const patchedSpawn = createHiddenWindowsSpawn(childProcess.spawn);
+    patchedSpawn[hiddenWindowsSpawnPatch] = true;
+    childProcess.spawn = patchedSpawn;
+    syncBuiltinESMExports();
+}
+let codexSdkModulePromise = null;
+async function loadCodexSdk() {
+    // The SDK captures child_process.spawn during module import and currently
+    // does not expose windowsHide; install the Windows default before loading it.
+    installHiddenWindowsSpawnPatch();
+    codexSdkModulePromise ??= import("@openai/codex-sdk");
+    return codexSdkModulePromise;
+}
 function normalizeEnv(input) {
+    const agentSettings = resolveAgentSettings(input.env);
     const normalized = {};
     for (const [key, value] of Object.entries({
         ...process.env,
         ...input.env,
-        ...(input.env?.WIKI_AGENT_API_KEY && !input.env.OPENAI_API_KEY ? { OPENAI_API_KEY: input.env.WIKI_AGENT_API_KEY } : {}),
+        ...(agentSettings.authMode === "api-key" && agentSettings.apiKey && !input.env?.OPENAI_API_KEY
+            ? { OPENAI_API_KEY: agentSettings.apiKey }
+            : {}),
+        ...(agentSettings.authMode === "codex-login" && agentSettings.codexHome
+            ? { CODEX_HOME: agentSettings.codexHome }
+            : {}),
     })) {
         if (typeof value === "string") {
             normalized[key] = value;
         }
     }
+    if (agentSettings.authMode === "codex-login") {
+        delete normalized.OPENAI_API_KEY;
+        delete normalized.CODEX_API_KEY;
+    }
     normalized.PATH = [input.skillArtifactsPath, normalized.PATH].filter(Boolean).join(path.delimiter);
     return normalized;
 }
-function createCodexClient(input) {
+async function createCodexClient(input) {
+    const agentSettings = resolveAgentSettings(input.env);
     const env = normalizeEnv(input);
-    const baseUrl = input.env?.WIKI_AGENT_BASE_URL?.trim();
-    const apiKey = input.env?.WIKI_AGENT_API_KEY?.trim();
+    const baseUrl = agentSettings.authMode === "api-key" ? agentSettings.baseUrl : null;
+    const apiKey = agentSettings.authMode === "api-key" ? agentSettings.apiKey : null;
     const options = {
         apiKey: apiKey || undefined,
         env,
@@ -43,6 +100,7 @@ function createCodexClient(input) {
             },
         };
     }
+    const { Codex } = await loadCodexSdk();
     return new Codex(options);
 }
 function persistWorkflowThreadId(queueItemPath, threadId) {
@@ -117,7 +175,7 @@ export class CodexSdkWorkflowRunner {
     // 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) {
-        const codex = createCodexClient(input);
+        const codex = await createCodexClient(input);
         const thread = codex.startThread({
             model: input.model ?? undefined,
             modelReasoningEffort: "low",
@@ -133,7 +191,7 @@ export class CodexSdkWorkflowRunner {
         return { threadId, mode: "start" };
     }
     async resumeWorkflow(threadId, input) {
-        const codex = createCodexClient(input);
+        const codex = await createCodexClient(input);
         const thread = codex.resumeThread(threadId, {
             model: input.model ?? undefined,
             modelReasoningEffort: "low",

package/dist/core/embedding.js

@@ -1,5 +1,6 @@
 import { sha256Text } from "../utils/fs.js";
 import { AppError } from "../utils/errors.js";
+export const DEFAULT_EMBEDDING_DIMENSIONS = 1536;
 export class EmbeddingClient {
     settings;
     constructor(settings) {
@@ -9,7 +10,7 @@ export class EmbeddingClient {
         const baseUrl = env.EMBEDDING_BASE_URL ?? env.OPENROUTER_BASE_URL;
         const apiKey = env.EMBEDDING_API_KEY ?? env.OPENROUTER_API_KEY;
         const model = env.EMBEDDING_MODEL ?? env.OPENROUTER_EMBEDDING_MODEL;
-        const rawDimensions = env.EMBEDDING_DIMENSIONS ?? "384";
+        const rawDimensions = env.EMBEDDING_DIMENSIONS ?? String(DEFAULT_EMBEDDING_DIMENSIONS);
         if (!baseUrl || !apiKey || !model) {
             return null;
         }

package/dist/core/onboarding.js

@@ -2,11 +2,12 @@ import { accessSync, constants, readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { confirm, input, password, select } from "@inquirer/prompts";
+import { inspectWikiAgentCodexLogin } from "./agent-auth.js";
 import { DEFAULT_WIKI_ENV_FILE, getCliEnvironmentInfo, parseEnvFile, serializeEnvEntries } from "./cli-env.js";
 import { resolveTemplateFilePath, loadConfig } from "./config.js";
-import { EmbeddingClient } from "./embedding.js";
+import { DEFAULT_EMBEDDING_DIMENSIONS, EmbeddingClient } from "./embedding.js";
 import { writeGlobalConfig } from "./global-config.js";
-import { parseVaultHashMode, parseWikiAgentSandboxMode, resolveAgentSettings } from "./paths.js";
+import { DEFAULT_WIKI_AGENT_MODEL, defaultWikiAgentCodexHome, parseVaultHashMode, parseWikiAgentAuthMode, 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";
@@ -32,8 +33,10 @@ const MANAGED_ENV_KEYS = new Set([
     "EMBEDDING_MODEL",
     "EMBEDDING_DIMENSIONS",
     "WIKI_AGENT_ENABLED",
+    "WIKI_AGENT_AUTH_MODE",
     "WIKI_AGENT_BASE_URL",
     "WIKI_AGENT_API_KEY",
+    "WIKI_AGENT_CODEX_HOME",
     "WIKI_AGENT_MODEL",
     "WIKI_AGENT_BATCH_SIZE",
     "WIKI_AGENT_SANDBOX_MODE",
@@ -86,6 +89,17 @@ function safeAgentSandboxMode(rawValue) {
         return "danger-full-access";
     }
 }
+function safeAgentAuthMode(env) {
+    try {
+        if (env.WIKI_AGENT_AUTH_MODE && env.WIKI_AGENT_AUTH_MODE.trim()) {
+            return parseWikiAgentAuthMode(env.WIKI_AGENT_AUTH_MODE);
+        }
+    }
+    catch {
+        return env.WIKI_AGENT_API_KEY?.trim() ? "api-key" : "codex-login";
+    }
+    return env.WIKI_AGENT_API_KEY?.trim() ? "api-key" : "codex-login";
+}
 function safeBooleanFlag(rawValue, defaultValue) {
     if (rawValue === undefined || rawValue.trim().length === 0) {
         return defaultValue;
@@ -120,6 +134,12 @@ function validateWikiPath(rawValue) {
     }
     return null;
 }
+function validateAbsolutePath(rawValue, label) {
+    if (!path.isAbsolute(rawValue.trim())) {
+        return `${label} must be an absolute path.`;
+    }
+    return null;
+}
 class InquirerPromptDriver {
     inputStream;
     outputStream;
@@ -368,6 +388,7 @@ function getPathDefaults(env, cwd) {
     const configPath = env.WIKI_CONFIG_PATH ? path.resolve(env.WIKI_CONFIG_PATH) : path.join(wikiRoot, "wiki.config.json");
     const templatesPath = env.WIKI_TEMPLATES_PATH ? path.resolve(env.WIKI_TEMPLATES_PATH) : path.join(wikiRoot, "templates");
     const defaultHashMode = vaultSource === "synology" ? "mtime" : "content";
+    const agentAuthMode = safeAgentAuthMode(env);
     return {
         envFilePath: env.WIKI_ENV_FILE ? path.resolve(cwd, env.WIKI_ENV_FILE) : path.join(cwd, DEFAULT_WIKI_ENV_FILE),
         vaultSource,
@@ -388,11 +409,13 @@ function getPathDefaults(env, cwd) {
         embeddingBaseUrl: env.EMBEDDING_BASE_URL ?? env.OPENROUTER_BASE_URL ?? "https://api.openai.com/v1",
         embeddingApiKey: env.EMBEDDING_API_KEY ?? env.OPENROUTER_API_KEY ?? null,
         embeddingModel: env.EMBEDDING_MODEL ?? env.OPENROUTER_EMBEDDING_MODEL ?? "text-embedding-3-small",
-        embeddingDimensions: env.EMBEDDING_DIMENSIONS ?? "384",
+        embeddingDimensions: env.EMBEDDING_DIMENSIONS ?? String(DEFAULT_EMBEDDING_DIMENSIONS),
         agentEnabled: (env.WIKI_AGENT_ENABLED ?? "").trim().toLowerCase() === "true",
-        agentBaseUrl: env.WIKI_AGENT_BASE_URL ?? "https://api.openai.com/v1",
+        agentAuthMode,
+        agentBaseUrl: env.WIKI_AGENT_BASE_URL ?? (agentAuthMode === "api-key" ? "https://api.openai.com/v1" : null),
         agentApiKey: env.WIKI_AGENT_API_KEY ?? null,
-        agentModel: env.WIKI_AGENT_MODEL ?? null,
+        agentCodexHome: env.WIKI_AGENT_CODEX_HOME ?? defaultWikiAgentCodexHome(),
+        agentModel: env.WIKI_AGENT_MODEL ?? DEFAULT_WIKI_AGENT_MODEL,
         agentBatchSize: env.WIKI_AGENT_BATCH_SIZE ?? "5",
         agentSandboxMode: safeAgentSandboxMode(env.WIKI_AGENT_SANDBOX_MODE),
         parserSkills: parseParserSkills(env.WIKI_PARSER_SKILLS, { strict: false }),
@@ -417,7 +440,7 @@ async function collectEmbeddingSettings(driver, ctx, defaults, env) {
             required: true,
         });
         const embeddingModel = await promptText(driver, "EMBEDDING_MODEL", defaults.embeddingModel ?? "text-embedding-3-small", { required: true });
-        const embeddingDimensions = await promptText(driver, "EMBEDDING_DIMENSIONS", defaults.embeddingDimensions ?? "384", { validator: (value) => validateNonNegativeInteger(value, "EMBEDDING_DIMENSIONS") });
+        const embeddingDimensions = await promptText(driver, "EMBEDDING_DIMENSIONS", defaults.embeddingDimensions ?? String(DEFAULT_EMBEDDING_DIMENSIONS), { validator: (value) => validateNonNegativeInteger(value, "EMBEDDING_DIMENSIONS") });
         const shouldProbe = await promptYesNo(driver, "Probe the embedding endpoint now?", false);
         if (shouldProbe) {
             try {
@@ -457,19 +480,50 @@ async function collectAgentSettings(driver, ctx, defaults) {
     if (!enabled) {
         return {
             agentEnabled: false,
+            agentAuthMode: null,
             agentBaseUrl: null,
             agentApiKey: null,
+            agentCodexHome: null,
             agentModel: null,
             agentBatchSize: null,
             agentSandboxMode: null,
         };
     }
     writeWarning(ctx.output, "Warning: danger-full-access grants full access to the runtime workspace.");
+    const agentAuthMode = await driver.select({
+        message: "WIKI_AGENT_AUTH_MODE",
+        defaultValue: defaults.agentAuthMode ?? "codex-login",
+        choices: [
+            {
+                value: "codex-login",
+                label: "codex-login",
+                description: "Use the current user's Codex login by default (~/.codex); set WIKI_AGENT_CODEX_HOME for isolation.",
+            },
+            {
+                value: "api-key",
+                label: "api-key",
+                description: "Use WIKI_AGENT_API_KEY and optional WIKI_AGENT_BASE_URL.",
+            },
+        ],
+    });
+    const authSettings = agentAuthMode === "api-key"
+        ? {
+            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,
+            }),
+            agentCodexHome: null,
+        }
+        : {
+            agentBaseUrl: null,
+            agentApiKey: null,
+            agentCodexHome: await promptText(driver, "WIKI_AGENT_CODEX_HOME", defaults.agentCodexHome ?? defaultWikiAgentCodexHome(), { validator: (value) => validateAbsolutePath(value, "WIKI_AGENT_CODEX_HOME") }),
+        };
     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 }),
+        agentAuthMode,
+        ...authSettings,
+        agentModel: await promptText(driver, "WIKI_AGENT_MODEL", defaults.agentModel ?? DEFAULT_WIKI_AGENT_MODEL, { 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",
@@ -561,7 +615,13 @@ function buildSetupSummary(values) {
         lines.push(`  EMBEDDING_DIMENSIONS: ${values.embeddingDimensions}`);
     }
     if (values.agentEnabled) {
-        lines.push(`  WIKI_AGENT_BASE_URL: ${values.agentBaseUrl}`);
+        lines.push(`  WIKI_AGENT_AUTH_MODE: ${values.agentAuthMode}`);
+        if (values.agentAuthMode === "api-key") {
+            lines.push(`  WIKI_AGENT_BASE_URL: ${values.agentBaseUrl}`);
+        }
+        if (values.agentAuthMode === "codex-login") {
+            lines.push(`  WIKI_AGENT_CODEX_HOME: ${values.agentCodexHome}`);
+        }
         lines.push(`  WIKI_AGENT_MODEL: ${values.agentModel}`);
         lines.push(`  WIKI_AGENT_BATCH_SIZE: ${values.agentBatchSize}`);
         lines.push(`  WIKI_AGENT_SANDBOX_MODE: ${values.agentSandboxMode}`);
@@ -598,8 +658,10 @@ function writeSetupEnvFile(values) {
         ["EMBEDDING_MODEL", values.embeddingEnabled ? values.embeddingModel : null],
         ["EMBEDDING_DIMENSIONS", values.embeddingEnabled ? values.embeddingDimensions : null],
         ["WIKI_AGENT_ENABLED", values.agentEnabled ? "true" : "false"],
-        ["WIKI_AGENT_BASE_URL", values.agentEnabled ? values.agentBaseUrl : null],
-        ["WIKI_AGENT_API_KEY", values.agentEnabled ? values.agentApiKey : null],
+        ["WIKI_AGENT_AUTH_MODE", values.agentEnabled ? values.agentAuthMode : null],
+        ["WIKI_AGENT_BASE_URL", values.agentEnabled && values.agentAuthMode === "api-key" ? values.agentBaseUrl : null],
+        ["WIKI_AGENT_API_KEY", values.agentEnabled && values.agentAuthMode === "api-key" ? values.agentApiKey : null],
+        ["WIKI_AGENT_CODEX_HOME", values.agentEnabled && values.agentAuthMode === "codex-login" ? values.agentCodexHome : 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],
@@ -731,6 +793,11 @@ export async function runSetupWizard(env = process.env, options = {}) {
             `- 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.",
+            ...(values.agentEnabled && values.agentAuthMode === "codex-login" && values.agentCodexHome
+                ? [
+                    `- Codex login auth uses ${values.agentCodexHome}; if needed, run \`CODEX_HOME=${values.agentCodexHome} codex login\` before starting the daemon.`,
+                ]
+                : []),
             ...(values.vaultSource === "synology"
                 ? ["- Protect `.wiki.env` carefully because it now stores Synology credentials."]
                 : []),
@@ -908,7 +975,16 @@ function inspectAgent(checks, env) {
             collectDoctorCheck(checks, "error", "agent", `Automatic vault processing is enabled but missing: ${settings.missing.join(", ")}`, "Set the missing WIKI_AGENT_* values in `.wiki.env` or rerun `tiangong-wiki setup`.");
             return;
         }
-        collectDoctorCheck(checks, "ok", "agent", `Automatic vault processing is enabled with model ${settings.model}.`);
+        if (settings.authMode === "codex-login") {
+            const codexLogin = inspectWikiAgentCodexLogin(settings);
+            if (!codexLogin.ready) {
+                collectDoctorCheck(checks, "error", "agent", codexLogin.summary, codexLogin.recommendation);
+                return;
+            }
+        }
+        collectDoctorCheck(checks, "ok", "agent", settings.authMode === "codex-login"
+            ? `Automatic vault processing is enabled with model ${settings.model} via Codex login at ${settings.codexHome}.`
+            : `Automatic vault processing is enabled with model ${settings.model} via API key auth.`);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);

package/dist/core/paths.js

@@ -1,8 +1,10 @@
 import { fileURLToPath } from "node:url";
+import os from "node:os";
 import path from "node:path";
 import { AppError } from "../utils/errors.js";
 const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
 const FALSE_VALUES = new Set(["0", "false", "no", "off"]);
+export const DEFAULT_WIKI_AGENT_MODEL = "gpt-5.5";
 function parseBooleanFlag(label, rawValue, defaultValue) {
     if (rawValue === undefined) {
         return defaultValue;
@@ -75,6 +77,19 @@ function requireAbsolutePath(label, rawValue) {
     }
     return path.resolve(rawValue);
 }
+function normalizeOptionalAbsolutePath(label, rawValue) {
+    const value = rawValue?.trim();
+    if (!value) {
+        return null;
+    }
+    if (!path.isAbsolute(value)) {
+        throw new AppError(`${label} must be an absolute path: ${rawValue}`, "config");
+    }
+    return path.resolve(value);
+}
+export function defaultWikiAgentCodexHome() {
+    return path.join(os.homedir(), ".codex");
+}
 export function parseVaultHashMode(raw) {
     const value = (raw ?? "content").trim().toLowerCase();
     if (value === "content" || value === "mtime") {
@@ -89,6 +104,13 @@ export function parseWikiAgentBackend(raw) {
     }
     throw new AppError(`WIKI_AGENT_BACKEND must be "codex-workflow", got ${raw}`, "config");
 }
+export function parseWikiAgentAuthMode(raw) {
+    const value = (raw ?? "api-key").trim().toLowerCase();
+    if (value === "api-key" || value === "codex-login") {
+        return value;
+    }
+    throw new AppError(`WIKI_AGENT_AUTH_MODE must be "api-key" or "codex-login", got ${raw}`, "config");
+}
 export function parseWikiAgentSandboxMode(raw) {
     const value = (raw ?? "danger-full-access").trim().toLowerCase();
     if (value === "danger-full-access" || value === "workspace-write") {
@@ -98,28 +120,33 @@ export function parseWikiAgentSandboxMode(raw) {
 }
 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 authMode = parseWikiAgentAuthMode(env.WIKI_AGENT_AUTH_MODE);
+    const rawBaseUrl = normalizeOptionalUrl(env.WIKI_AGENT_BASE_URL);
+    const baseUrl = authMode === "api-key" ? rawBaseUrl : null;
+    const rawApiKey = env.WIKI_AGENT_API_KEY?.trim() || null;
+    const apiKey = authMode === "api-key" ? rawApiKey : null;
+    const codexHome = authMode === "codex-login"
+        ? normalizeOptionalAbsolutePath("WIKI_AGENT_CODEX_HOME", env.WIKI_AGENT_CODEX_HOME) ?? defaultWikiAgentCodexHome()
+        : null;
+    const model = env.WIKI_AGENT_MODEL?.trim() || DEFAULT_WIKI_AGENT_MODEL;
     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) {
-        if (!apiKey) {
+        if (authMode === "api-key" && !apiKey) {
             missing.push("WIKI_AGENT_API_KEY");
         }
-        if (!model) {
-            missing.push("WIKI_AGENT_MODEL");
-        }
     }
     if (options.strict && enabled && missing.length > 0) {
         throw new AppError(`WIKI_AGENT_ENABLED=true but missing required settings: ${missing.join(", ")}`, "config");
     }
     return {
         enabled,
+        authMode,
         baseUrl,
         apiKey,
+        codexHome,
         model,
         batchSize,
         sandboxMode,

package/dist/core/runtime.js

@@ -1,11 +1,11 @@
 import { loadConfig } from "./config.js";
 import { openDb } from "./db.js";
-import { EmbeddingClient } from "./embedding.js";
+import { DEFAULT_EMBEDDING_DIMENSIONS, EmbeddingClient } from "./embedding.js";
 import { resolveRuntimePaths } from "./paths.js";
 export function getEmbeddingDimensionFromEnv(env = process.env) {
-    const raw = env.EMBEDDING_DIMENSIONS ?? "384";
+    const raw = env.EMBEDDING_DIMENSIONS ?? String(DEFAULT_EMBEDDING_DIMENSIONS);
     const value = Number.parseInt(raw, 10);
-    return Number.isFinite(value) && value > 0 ? value : 384;
+    return Number.isFinite(value) && value > 0 ? value : DEFAULT_EMBEDDING_DIMENSIONS;
 }
 export function loadRuntimeConfig(env = process.env) {
     const paths = resolveRuntimePaths(env);

package/dist/core/sqlite-extensions.js

@@ -23,21 +23,25 @@ function getExistingFtsSql(db) {
         .get();
     return row?.sql ?? null;
 }
-function resolveBundledSimpleExtensionPath(packageRoot) {
-    const byArch = SIMPLE_ASSET_MAP[process.platform];
+export function resolveBundledSimpleExtensionRelativePath(platform = process.platform, arch = process.arch) {
+    const byArch = SIMPLE_ASSET_MAP[platform];
     if (!byArch) {
-        throw new AppError(`Bundled simple extension is not available for platform ${process.platform}-${process.arch}.`, "config", {
-            platform: process.platform,
-            arch: process.arch,
+        throw new AppError(`Bundled simple extension is not available for platform ${platform}-${arch}.`, "config", {
+            platform,
+            arch,
         });
     }
-    const relativePath = byArch[process.arch];
+    const relativePath = byArch[arch];
     if (!relativePath) {
-        throw new AppError(`Bundled simple extension is not available for platform ${process.platform}-${process.arch}.`, "config", {
-            platform: process.platform,
-            arch: process.arch,
+        throw new AppError(`Bundled simple extension is not available for platform ${platform}-${arch}.`, "config", {
+            platform,
+            arch,
         });
     }
+    return relativePath;
+}
+function resolveBundledSimpleExtensionPath(packageRoot) {
+    const relativePath = resolveBundledSimpleExtensionRelativePath();
     const extensionPath = path.join(packageRoot, relativePath);
     if (!pathExistsSync(extensionPath)) {
         throw new AppError(`Bundled simple extension not found: ${extensionPath}`, "runtime", {

package/dist/core/sync.js

@@ -1,6 +1,6 @@
 import { loadConfig } from "./config.js";
 import { clearAllIndexedData, getMeta, openDb, resetVectorTable, setMetaValues, } from "./db.js";
-import { EmbeddingClient } from "./embedding.js";
+import { DEFAULT_EMBEDDING_DIMENSIONS, EmbeddingClient } from "./embedding.js";
 import { applyChanges, scanPages, scanSpecificPages } from "./indexer.js";
 import { resolveRuntimePaths } from "./paths.js";
 import { collectVaultFiles, syncVaultIndex } from "./vault.js";
@@ -8,9 +8,9 @@ import { AppError } from "../utils/errors.js";
 import { pathExistsSync } from "../utils/fs.js";
 import { makeSyncId, toOffsetIso } from "../utils/time.js";
 function getEmbeddingDimension(env) {
-    const raw = env.EMBEDDING_DIMENSIONS ?? "384";
+    const raw = env.EMBEDDING_DIMENSIONS ?? String(DEFAULT_EMBEDDING_DIMENSIONS);
     const value = Number.parseInt(raw, 10);
-    return Number.isFinite(value) && value > 0 ? value : 384;
+    return Number.isFinite(value) && value > 0 ? value : DEFAULT_EMBEDDING_DIMENSIONS;
 }
 function getEmbeddingTargets(db, embedAll, insertedIds, summaryChangedIds) {
     const rows = db.prepare("SELECT rowid, id, summary_text AS summaryText, embedding_status AS embeddingStatus FROM pages").all();

package/dist/core/vault-processing.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { CODEX_WORKFLOW_VERSION, createDefaultWorkflowRunner, } from "./codex-workflow.js";
 import { loadConfig } from "./config.js";
 import { openDb } from "./db.js";
+import { DEFAULT_EMBEDDING_DIMENSIONS } from "./embedding.js";
 import { resolveAgentSettings, resolveRuntimePaths } from "./paths.js";
 import { assertTemplateEvolutionAllowed, resolveTemplateEvolutionSettings } from "./template-evolution.js";
 import { ensureLocalVaultFile } from "./vault.js";
@@ -817,7 +818,7 @@ function prepareCodexWorkflowInput(paths, item, file, localFilePath, env, allowT
             queueItemPath: artifacts.queueItemPath,
             resultPath: artifacts.resultPath,
             skillArtifactsPath: artifacts.skillArtifactsPath,
-            model: env.WIKI_AGENT_MODEL ?? null,
+            model: resolveAgentSettings(env).model,
             env,
         },
     };
@@ -1017,7 +1018,7 @@ async function processClaimedQueueItem(input) {
 export function getVaultQueueSnapshot(env = process.env, status) {
     const paths = resolveRuntimePaths(env);
     const config = loadConfig(paths.configPath);
-    const { db } = openDb(paths.dbPath, config, Number.parseInt(env.EMBEDDING_DIMENSIONS ?? "384", 10) || 384, paths.packageRoot);
+    const { db } = openDb(paths.dbPath, config, Number.parseInt(env.EMBEDDING_DIMENSIONS ?? String(DEFAULT_EMBEDDING_DIMENSIONS), 10) || DEFAULT_EMBEDDING_DIMENSIONS, paths.packageRoot);
     try {
         const items = fetchQueueItemsByStatus(db, status);
         const counts = db.prepare(`
@@ -1045,7 +1046,7 @@ export function getVaultQueueSnapshot(env = process.env, status) {
 export function getVaultQueueItem(env = process.env, fileId) {
     const paths = resolveRuntimePaths(env);
     const config = loadConfig(paths.configPath);
-    const { db } = openDb(paths.dbPath, config, Number.parseInt(env.EMBEDDING_DIMENSIONS ?? "384", 10) || 384, paths.packageRoot);
+    const { db } = openDb(paths.dbPath, config, Number.parseInt(env.EMBEDDING_DIMENSIONS ?? String(DEFAULT_EMBEDDING_DIMENSIONS), 10) || DEFAULT_EMBEDDING_DIMENSIONS, paths.packageRoot);
     try {
         return fetchQueueItemByFileId(db, fileId);
     }
@@ -1067,7 +1068,7 @@ export async function processVaultQueueBatch(env = process.env, options = {}) {
     }
     const paths = resolveRuntimePaths(env);
     const config = loadConfig(paths.configPath);
-    const { db } = openDb(paths.dbPath, config, Number.parseInt(env.EMBEDDING_DIMENSIONS ?? "384", 10) || 384, paths.packageRoot);
+    const { db } = openDb(paths.dbPath, config, Number.parseInt(env.EMBEDDING_DIMENSIONS ?? String(DEFAULT_EMBEDDING_DIMENSIONS), 10) || DEFAULT_EMBEDDING_DIMENSIONS, paths.packageRoot);
     try {
         const result = {
             enabled: true,

package/dist/core/vault.js

@@ -340,6 +340,7 @@ function extractPdfText(filePath) {
         const result = execFileSync("/usr/bin/mdls", ["-raw", "-name", "kMDItemTextContent", filePath], {
             encoding: "utf8",
             stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true,
         });
         const text = (result || "").trim();
         if (text && text !== "(null)")
@@ -350,6 +351,7 @@ function extractPdfText(filePath) {
         const result = execFileSync("/usr/bin/strings", ["-n", "6", filePath], {
             encoding: "utf8",
             stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true,
         });
         const lines = result.split("\n").map((l) => l.trim()).filter(Boolean).slice(0, 400);
         if (lines.length)

package/dist/core/workflow-context.js

@@ -5,6 +5,9 @@ import { sha256Text } from "../utils/fs.js";
 function shellSingleQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+function batchSetLiteral(value) {
+    return value.replace(/%/g, "%%").replace(/"/g, '""');
+}
 function resolveNodeExecutable() {
     const currentExec = path.basename(process.execPath).toLowerCase();
     if (currentExec === "node" || currentExec.startsWith("node")) {
@@ -59,6 +62,7 @@ export function buildVaultWorkflowPrompt(input) {
         "",
         "Workspace-local skills are available from WORKSPACE_ROOT through normal Codex skill discovery.",
         "A local tiangong-wiki CLI launcher is already available on PATH for this run.",
+        "On Windows native shells, use `tiangong-wiki.cmd` instead of the suffixless `tiangong-wiki` command.",
         "",
         "The tiangong-wiki CLI provides these discovery and search capabilities:",
         "- `tiangong-wiki type list` / `tiangong-wiki type show <type>` — discover registered page types and their purpose",
@@ -193,6 +197,7 @@ export function ensureWorkflowArtifactSet(paths, input) {
     ensureDirSync(artifacts.rootDir);
     ensureDirSync(artifacts.skillArtifactsPath);
     const wikiCliWrapperPath = path.join(artifacts.skillArtifactsPath, "tiangong-wiki");
+    const wikiCliCmdWrapperPath = path.join(artifacts.skillArtifactsPath, "tiangong-wiki.cmd");
     const nodeExecutable = resolveNodeExecutable();
     const cliEntrypoint = path.join(paths.packageRoot, "dist", "index.js");
     writeTextFileSync(artifacts.queueItemPath, `${JSON.stringify(input.queueItem, null, 2)}\n`);
@@ -214,6 +219,22 @@ export function ensureWorkflowArtifactSet(paths, input) {
         "",
     ].join("\n"));
     chmodSync(wikiCliWrapperPath, 0o755);
+    writeTextFileSync(wikiCliCmdWrapperPath, [
+        "@echo off",
+        "setlocal",
+        "if not defined WIKI_CLI_NODE set \"WIKI_CLI_NODE=%~dp0node.exe\"",
+        `if not exist "%WIKI_CLI_NODE%" set "WIKI_CLI_NODE=${batchSetLiteral(nodeExecutable)}"`,
+        "if not defined WIKI_CLI_ENTRYPOINT (",
+        `  set "WIKI_CLI_ENTRYPOINT=${batchSetLiteral(cliEntrypoint)}"`,
+        ")",
+        "if not exist \"%WIKI_CLI_ENTRYPOINT%\" (",
+        "  echo tiangong-wiki CLI entrypoint not found: %WIKI_CLI_ENTRYPOINT% 1>&2",
+        "  exit /b 127",
+        ")",
+        "\"%WIKI_CLI_NODE%\" \"%WIKI_CLI_ENTRYPOINT%\" %*",
+        "exit /b %ERRORLEVEL%",
+        "",
+    ].join("\r\n"));
     writeTextFileSync(artifacts.promptPath, input.promptMarkdown ??
         [
             "# Vault To Wiki Workflow",

package/dist/core/workspace-skills.js

@@ -25,8 +25,8 @@ function canRead(filePath) {
     accessSync(filePath, constants.R_OK);
     return true;
 }
-function getNpxCommand() {
-    return process.platform === "win32" ? "npx.cmd" : "npx";
+export function getNpxCommand(platform = process.platform) {
+    return platform === "win32" ? "npx.cmd" : "npx";
 }
 export function resolveWorkspaceRootFromWikiPath(wikiPath) {
     return path.resolve(wikiPath, "..", "..");
@@ -186,6 +186,9 @@ function replaceSkillDirectory(targetPath, sourcePath) {
     ensureDirSync(targetPath);
     copyDirectoryContentsSync(sourcePath, targetPath);
 }
+function linkWorkspaceSkill(sourcePath, targetPath) {
+    symlinkSync(sourcePath, targetPath, process.platform === "win32" ? "junction" : "dir");
+}
 function createManagedSkillMetadata(descriptor, baselineHash, command) {
     return {
         version: 1,
@@ -255,7 +258,7 @@ function createWikiDescriptor(wikiPath, packageRoot) {
 }
 function renderCommand(command, args) {
     return [command, ...args]
-        .map((part) => (/[A-Za-z0-9_./:@+-]+/.test(part) ? part : JSON.stringify(part)))
+        .map((part) => (/^[A-Za-z0-9_./:@+-]+$/.test(part) ? part : JSON.stringify(part)))
         .join(" ");
 }
 export function buildExternalSkillInstallInvocation(source, skillName) {
@@ -267,6 +270,18 @@ export function buildExternalSkillInstallInvocation(source, skillName) {
         rendered: renderCommand(command, args),
     };
 }
+export function buildExternalSkillInstallSpawnInvocation(invocation, platform = process.platform, env = process.env) {
+    if (platform !== "win32") {
+        return {
+            command: invocation.command,
+            args: invocation.args,
+        };
+    }
+    return {
+        command: env.ComSpec?.trim() || "cmd.exe",
+        args: ["/d", "/c", "call", invocation.command, ...invocation.args],
+    };
+}
 function installManagedExternalSkill(descriptor, options = {}) {
     if (descriptor.sourceKind === "workspace-package") {
         throw new AppError("Workspace package skills must be installed via ensureWikiSkillInstall.", "config");
@@ -285,10 +300,12 @@ function installManagedExternalSkill(descriptor, options = {}) {
     }
     const workspaceRoot = getWorkspaceRootForSkillPath(descriptor.skillPath);
     options.output?.write(`Installing skill ${descriptor.name} from ${descriptor.source}...\n`);
-    const result = spawnSync(invocation.command, invocation.args, {
+    const spawnInvocation = buildExternalSkillInstallSpawnInvocation(invocation);
+    const result = spawnSync(spawnInvocation.command, spawnInvocation.args, {
         cwd: workspaceRoot,
         env: options.env ?? process.env,
         encoding: "utf8",
+        windowsHide: true,
     });
     if (result.error) {
         throw new AppError(`failed to install skill ${descriptor.name}: ${result.error.message}`, "runtime", {
@@ -610,7 +627,7 @@ export function ensureWikiSkillInstall(wikiPath, packageRoot) {
                 };
             }
             unlinkSync(paths.wikiSkillPath);
-            symlinkSync(packageRoot, paths.wikiSkillPath, "dir");
+            linkWorkspaceSkill(packageRoot, paths.wikiSkillPath);
             return {
                 sourcePath: packageRoot,
                 skillPath: paths.wikiSkillPath,
@@ -619,7 +636,7 @@ export function ensureWikiSkillInstall(wikiPath, packageRoot) {
         }
         if (existing.readable) {
             rmSync(paths.wikiSkillPath, { recursive: true, force: true });
-            symlinkSync(packageRoot, paths.wikiSkillPath, "dir");
+            linkWorkspaceSkill(packageRoot, paths.wikiSkillPath);
             return {
                 sourcePath: packageRoot,
                 skillPath: paths.wikiSkillPath,
@@ -631,7 +648,7 @@ export function ensureWikiSkillInstall(wikiPath, packageRoot) {
             skillPath: paths.wikiSkillPath,
         });
     }
-    symlinkSync(packageRoot, paths.wikiSkillPath, "dir");
+    linkWorkspaceSkill(packageRoot, paths.wikiSkillPath);
     return {
         sourcePath: packageRoot,
         skillPath: paths.wikiSkillPath,

package/dist/daemon/git-journal.js

@@ -16,6 +16,7 @@ function runGit(paths, actor, args) {
     const result = spawnSync("git", ["-C", paths.wikiRoot, ...args], {
         encoding: "utf8",
         env: buildGitEnv(actor),
+        windowsHide: true,
     });
     return {
         status: result.status,

package/dist/utils/process.js

@@ -18,39 +18,40 @@ export function getCurrentInvocation() {
         args: [argv1],
     };
 }
-export function spawnDetachedCurrentProcess(extraArgs, options = {}) {
-    const invocation = getCurrentInvocation();
+export function buildDetachedSpawnOptions(options = {}) {
     const stdio = options.logFile
         ? ["ignore", openSync(options.logFile, "a"), openSync(options.logFile, "a")]
         : "ignore";
-    const child = spawn(invocation.command, [...invocation.args, ...extraArgs], {
+    return {
         detached: true,
         stdio,
         env: options.env ?? process.env,
-    });
+        windowsHide: true,
+    };
+}
+export function spawnDetachedCurrentProcess(extraArgs, options = {}) {
+    const invocation = getCurrentInvocation();
+    const child = spawn(invocation.command, [...invocation.args, ...extraArgs], buildDetachedSpawnOptions(options));
     child.unref();
     return child.pid;
 }
-export function openTarget(target) {
-    let command = "";
-    let args = [];
-    if (process.platform === "darwin") {
-        command = "open";
-        args = [target];
-    }
-    else if (process.platform === "win32") {
-        command = "cmd";
-        args = ["/c", "start", "", target];
+export function buildOpenTargetInvocation(target, platform = process.platform) {
+    if (platform === "darwin") {
+        return { command: "open", args: [target] };
     }
-    else {
-        command = "xdg-open";
-        args = [target];
+    if (platform === "win32") {
+        return { command: "rundll32.exe", args: ["url.dll,FileProtocolHandler", target] };
     }
+    return { command: "xdg-open", args: [target] };
+}
+export function openTarget(target) {
+    const { command, args } = buildOpenTargetInvocation(target);
     try {
         const child = spawn(command, args, {
             detached: true,
             stdio: "ignore",
             shell: false,
+            windowsHide: true,
         });
         child.unref();
     }

package/mcp-server/package.json

@@ -15,6 +15,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^4.3.6"
+    "zod": "^4.4.2"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biaoo/tiangong-wiki",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Local-first wiki index and query engine for Markdown knowledge pages (Tiangong Wiki).",
   "type": "module",
   "publishConfig": {
@@ -30,7 +30,7 @@
     "SKILL.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22.13.0"
   },
   "scripts": {
     "build": "npm run build:cli && npm run build:dashboard && npm run build:mcp-server",
@@ -48,25 +48,25 @@
     "@antv/g6": "^5.1.0",
     "@fontsource/jetbrains-mono": "^5.2.8",
     "@fontsource/space-grotesk": "^5.2.10",
-    "@inquirer/prompts": "^7.10.1",
+    "@inquirer/prompts": "^8.4.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@openai/codex-sdk": "^0.118.0",
+    "@openai/codex-sdk": "^0.128.0",
     "adm-zip": "^0.5.17",
-    "better-sqlite3": "^12.8.0",
+    "better-sqlite3": "^12.9.0",
     "commander": "^14.0.3",
     "gray-matter": "^4.0.3",
     "preact": "^10.29.1",
     "sqlite-vec": "^0.1.9",
-    "zod": "^4.3.6"
+    "zod": "^4.4.2"
   },
   "devDependencies": {
     "@preact/preset-vite": "^2.10.5",
     "@types/adm-zip": "^0.5.8",
     "@types/better-sqlite3": "^7.6.13",
-    "@types/node": "^24.5.2",
+    "@types/node": "^25.6.0",
     "tsx": "^4.21.0",
-    "typescript": "^6.0.2",
-    "vite": "^8.0.7",
-    "vitest": "^4.1.2"
+    "typescript": "^6.0.3",
+    "vite": "^8.0.10",
+    "vitest": "^4.1.5"
   }
 }

package/references/cli-interface.md

@@ -13,6 +13,14 @@ npx @biaoo/tiangong-wiki <command> [options]
 npm run dev -- <command> [options]
 ```
 
+On Windows native shells (PowerShell, Command Prompt, scheduled/background tasks, and Codex worker automation), use the npm `.cmd` shim explicitly:
+
+```powershell
+tiangong-wiki.cmd <command> [options]
+```
+
+Do not use the suffixless `tiangong-wiki` command in Windows native shells. npm installs it for POSIX-like environments such as macOS, Linux, WSL, and Git Bash; Windows may try to open it as an unknown file instead of executing it.
+
 Global workspace resolution priority:
 
 1. `--env-file <path>`

package/references/troubleshooting.md

@@ -75,24 +75,28 @@ For the full single-host deployment baseline, see [centralized-service-deploymen
 | `EMBEDDING_BASE_URL` | Yes | Embedding API base URL |
 | `EMBEDDING_API_KEY` | Yes | Embedding API key |
 | `EMBEDDING_MODEL` | Yes | Embedding model name |
-| `EMBEDDING_DIMENSIONS` | No | Vector dimensions (default: model-dependent) |
+| `EMBEDDING_DIMENSIONS` | No | Vector dimensions (default: `1536`, matching the default OpenAI `text-embedding-3-small`; set explicitly only when using a different dimension profile) |
 
 ### Agent (Agentic Workflow)
 
-The agent uses [Codex SDK](https://www.npmjs.com/package/@openai/codex-sdk) to process vault items. When `WIKI_AGENT_BASE_URL` is set, a custom `model_provider` is injected to override any global `~/.codex/config.toml` settings.
+The agent uses [Codex SDK](https://www.npmjs.com/package/@openai/codex-sdk) to process vault items. It supports API-key auth and local Codex login auth. In `api-key` mode, when `WIKI_AGENT_BASE_URL` is set, a custom `model_provider` is injected to override any global `~/.codex/config.toml` settings. In `codex-login` mode, the workflow uses `WIKI_AGENT_CODEX_HOME` as `CODEX_HOME` and does not pass API key environment variables to Codex.
 
 | Variable | Required | Description |
 | --- | --- | --- |
 | `WIKI_AGENT_ENABLED` | No | Enable agentic workflow (`true` / `false`, default: `false`) |
-| `WIKI_AGENT_BASE_URL` | No | LLM API base URL (e.g. `https://api.openai.com/v1`). When set, overrides global Codex config |
-| `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_AUTH_MODE` | No | Auth mode: `api-key` or `codex-login`. Runtime default is `api-key` for backwards compatibility; `tiangong-wiki setup` defaults new agent configs to `codex-login` |
+| `WIKI_AGENT_CODEX_HOME` | No | Codex home directory. Leave unset to use the current user's standard `${HOME}/.codex` (or the user profile `.codex` directory on Windows); if set in `.wiki.env`, use a real absolute path because shell variables are not expanded there |
+| `WIKI_AGENT_BASE_URL` | No | LLM API base URL for `api-key` mode (e.g. `https://api.openai.com/v1`). When set, overrides global Codex config |
+| `WIKI_AGENT_API_KEY` | In `api-key` mode | API key for the LLM provider |
+| `WIKI_AGENT_MODEL` | No | Model name (default: `gpt-5.5`; e.g. `Qwen/Qwen3.5-397B-A17B-GPTQ-Int4`) |
 | `WIKI_AGENT_BATCH_SIZE` | No | Max concurrent vault queue workers per cycle (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.
 
+When `WIKI_AGENT_ENABLED=true` and `WIKI_AGENT_AUTH_MODE=codex-login`, `tiangong-wiki doctor` and `tiangong-wiki check-config` verify that `WIKI_AGENT_CODEX_HOME` exists and contains `auth.json`. They report the path and remediation command, but never print token or auth file contents.
+
 Queue items that fail workflow execution are auto-retried up to 3 times. After that they remain in `error` until you manually retry them from the dashboard / queue tooling, or a later vault sync requeues the file because the source changed.
 
 ---
@@ -122,6 +126,20 @@ 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.
 
+### Windows opens "choose an app" instead of running tiangong-wiki
+
+In Windows native shells, invoke the npm command shim with the `.cmd` suffix:
+
+```powershell
+tiangong-wiki.cmd daemon status
+tiangong-wiki.cmd sync
+tiangong-wiki.cmd lint --format json
+```
+
+Avoid bare `tiangong-wiki` in PowerShell, Command Prompt, daemon scripts, and Codex worker automation. npm installs a suffixless shebang script for POSIX-like environments, but Windows native shells do not execute it the same way as macOS, Linux, WSL, or Git Bash.
+
+Vault workflow artifacts also include a workspace-local `tiangong-wiki.cmd` launcher. If a Windows agent opens a new command window or an app chooser while processing vault items, verify that it is calling `tiangong-wiki.cmd`, not the suffixless `tiangong-wiki` wrapper.
+
 ### 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.
@@ -130,12 +148,60 @@ If the agent workflow fails with `bwrap`, `unshare`, `uid_map`, or similar sandb
 
 ## LLM Provider Setup
 
-### OpenAI (default)
+### Codex login (recommended local setup)
+
+By default, use the current user's standard Codex home:
+
+macOS/Linux:
+
+```bash
+codex login
+codex login status
+```
+
+Windows PowerShell:
+
+```powershell
+codex login
+codex login status
+```
+
+For an isolated Codex home, set `WIKI_AGENT_CODEX_HOME` to an absolute path and log in there first:
+
+macOS/Linux:
+
+```bash
+mkdir -p "$HOME/.codex-tiangong-wiki"
+CODEX_HOME="$HOME/.codex-tiangong-wiki" codex login
+CODEX_HOME="$HOME/.codex-tiangong-wiki" codex login status
+```
+
+Windows PowerShell:
+
+```powershell
+New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex-tiangong-wiki" | Out-Null
+$env:CODEX_HOME = "$env:USERPROFILE\.codex-tiangong-wiki"
+codex login
+codex login status
+```
+
+Then configure the wiki agent:
+
+```env
+WIKI_AGENT_ENABLED=true
+WIKI_AGENT_AUTH_MODE=codex-login
+# Optional. Leave unset to use the current user's standard ~/.codex.
+# WIKI_AGENT_CODEX_HOME=/absolute/path/to/.codex-tiangong-wiki
+WIKI_AGENT_MODEL=gpt-5.5
+```
+
+### OpenAI API key
 
 ```env
 WIKI_AGENT_ENABLED=true
+WIKI_AGENT_AUTH_MODE=api-key
 WIKI_AGENT_API_KEY=sk-...
-WIKI_AGENT_MODEL=gpt-5.4
+WIKI_AGENT_MODEL=gpt-5.5
 ```
 
 ### vLLM (self-hosted)
@@ -144,6 +210,7 @@ Requires vLLM **v0.8.5+** for Responses API support (`/v1/responses`).
 
 ```env
 WIKI_AGENT_ENABLED=true
+WIKI_AGENT_AUTH_MODE=api-key
 WIKI_AGENT_BASE_URL=http://<host>:<port>/v1
 WIKI_AGENT_API_KEY=<your-token>
 WIKI_AGENT_MODEL=Qwen/Qwen3.5-397B-A17B-GPTQ-Int4