@biaoo/tiangong-wiki 0.2.0 → 0.2.2

package/dist/core/onboarding.js

@@ -1,10 +1,11 @@
 import { accessSync, constants, readFileSync } from "node:fs";
 import path from "node:path";
-import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
+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 { writeGlobalConfig } from "./global-config.js";
 import { parseVaultHashMode, 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";
@@ -106,16 +107,62 @@ function validateWikiPath(rawValue) {
     }
     return null;
 }
-class ReadlinePromptDriver {
-    rl;
-    constructor(rl) {
-        this.rl = rl;
-    }
-    ask(prompt) {
-        return this.rl.question(prompt);
+class InquirerPromptDriver {
+    inputStream;
+    outputStream;
+    constructor(inputStream, outputStream) {
+        this.inputStream = inputStream;
+        this.outputStream = outputStream;
+    }
+    input(options) {
+        return input({
+            message: options.message,
+            default: options.defaultValue,
+            required: options.required !== false,
+            validate: (value) => options.validator?.(value) ?? true,
+        }, this.getContext());
+    }
+    password(options) {
+        const defaultValue = options.defaultValue ?? "";
+        const hasDefault = defaultValue.length > 0;
+        return password({
+            message: hasDefault ? `${options.message} (press enter to keep current value)` : options.message,
+            mask: "*",
+            validate: (value) => {
+                const candidate = value.length === 0 && hasDefault ? defaultValue : value;
+                if (options.required !== false && candidate.length === 0) {
+                    return `${options.message} is required.`;
+                }
+                return options.validator?.(candidate) ?? true;
+            },
+        }, this.getContext()).then((value) => (value.length === 0 && hasDefault ? defaultValue : value));
+    }
+    confirm(options) {
+        return confirm({
+            message: options.message,
+            default: options.defaultValue,
+        }, this.getContext());
+    }
+    select(options) {
+        return select({
+            message: options.message,
+            default: options.defaultValue,
+            choices: options.choices.map((choice) => ({
+                value: choice.value,
+                name: choice.label,
+                description: choice.description,
+            })),
+        }, this.getContext());
+    }
+    getContext() {
+        return {
+            input: this.inputStream,
+            output: this.outputStream,
+            clearPromptOnDone: false,
+        };
     }
     close() {
-        this.rl.close();
+        // Inquirer manages prompt lifecycle; no explicit teardown needed here.
     }
 }
 class BufferedPromptDriver {
@@ -126,13 +173,87 @@ class BufferedPromptDriver {
         this.answers = answers;
         this.output = output;
     }
-    async ask(prompt) {
+    async input(options) {
+        const defaultValue = options.defaultValue ?? "";
+        const label = formatBufferedPromptLabel(options.message, defaultValue);
+        while (true) {
+            const answer = this.readAnswer(label);
+            const candidate = (answer.trim() || defaultValue).trim();
+            if (options.required !== false && candidate.length === 0) {
+                this.output.write(`${options.message} is required.\n`);
+                continue;
+            }
+            const error = options.validator?.(candidate);
+            if (error) {
+                this.output.write(`${error}\n`);
+                continue;
+            }
+            return candidate;
+        }
+    }
+    async password(options) {
+        const defaultValue = options.defaultValue ?? "";
+        const label = formatBufferedPromptLabel(options.message, defaultValue, {
+            defaultDisplay: defaultValue.length > 0 ? "(saved)" : "",
+        });
+        while (true) {
+            const answer = this.readAnswer(label);
+            const candidate = answer.length === 0 ? defaultValue : answer;
+            if (options.required !== false && candidate.length === 0) {
+                this.output.write(`${options.message} is required.\n`);
+                continue;
+            }
+            const error = options.validator?.(candidate);
+            if (error) {
+                this.output.write(`${error}\n`);
+                continue;
+            }
+            return candidate;
+        }
+    }
+    async confirm(options) {
+        const suffix = options.defaultValue ? "Y/n" : "y/N";
+        while (true) {
+            const answer = this.readAnswer(`${options.message} [${suffix}]: `).trim().toLowerCase();
+            if (!answer) {
+                return options.defaultValue;
+            }
+            if (["y", "yes"].includes(answer)) {
+                return true;
+            }
+            if (["n", "no"].includes(answer)) {
+                return false;
+            }
+            this.output.write("Please answer yes or no.\n");
+        }
+    }
+    async select(options) {
+        const choiceList = options.choices.map((choice) => choice.value).join("/");
+        while (true) {
+            const answer = this.readAnswer(`${options.message} [${choiceList}] (${options.defaultValue}): `).trim().toLowerCase();
+            if (!answer) {
+                return options.defaultValue;
+            }
+            const match = options.choices.find((choice) => {
+                return choice.value.toLowerCase() === answer || choice.label.trim().toLowerCase() === answer;
+            });
+            if (match) {
+                return match.value;
+            }
+            this.output.write(`Please choose one of: ${choiceList}.\n`);
+        }
+    }
+    close() { }
+    readAnswer(prompt) {
         const answer = this.answers[this.index] ?? "";
         this.index += 1;
         this.output.write(`${prompt}${answer}\n`);
         return answer;
     }
-    close() { }
+}
+function formatBufferedPromptLabel(message, defaultValue, options = {}) {
+    const display = options.defaultDisplay ?? defaultValue;
+    return display ? `${message} [${display}]: ` : `${message}: `;
 }
 async function readBufferedAnswers(input) {
     const chunks = [];
@@ -147,77 +268,72 @@ async function readBufferedAnswers(input) {
 }
 async function createPromptDriver(input, output) {
     if ("isTTY" in input && input.isTTY) {
-        return new ReadlinePromptDriver(createInterface({
-            input,
-            output,
-        }));
+        return new InquirerPromptDriver(input, output);
     }
     return new BufferedPromptDriver(await readBufferedAnswers(input), output);
 }
-async function promptText(driver, ctx, label, defaultValue, options = {}) {
-    while (true) {
-        const answer = await driver.ask(`${label} [${defaultValue}]: `);
-        const candidate = (answer.trim() || defaultValue).trim();
-        if (options.required !== false && candidate.length === 0) {
-            ctx.output.write(`${label} is required.\n`);
-            continue;
-        }
-        const error = options.validator?.(candidate);
-        if (error) {
-            ctx.output.write(`${error}\n`);
-            continue;
-        }
-        return options.normalize ? options.normalize(candidate) : candidate;
-    }
+async function promptText(driver, label, defaultValue, options = {}) {
+    const candidate = await driver.input({
+        message: label,
+        defaultValue,
+        required: options.required,
+        validator: options.validator,
+    });
+    return options.normalize ? options.normalize(candidate) : candidate;
 }
-async function promptYesNo(driver, ctx, label, defaultValue) {
-    const suffix = defaultValue ? "Y/n" : "y/N";
-    while (true) {
-        const answer = (await driver.ask(`${label} [${suffix}]: `)).trim().toLowerCase();
-        if (!answer) {
-            return defaultValue;
-        }
-        if (["y", "yes"].includes(answer)) {
-            return true;
-        }
-        if (["n", "no"].includes(answer)) {
-            return false;
-        }
-        ctx.output.write("Please answer yes or no.\n");
-    }
+async function promptPassword(driver, label, defaultValue, options = {}) {
+    const candidate = await driver.password({
+        message: label,
+        defaultValue,
+        required: options.required,
+        validator: options.validator,
+    });
+    return options.normalize ? options.normalize(candidate) : candidate;
+}
+async function promptYesNo(driver, label, defaultValue) {
+    return driver.confirm({
+        message: label,
+        defaultValue,
+    });
 }
 function formatStep(index, total, title) {
     return `Step ${index}/${total}: ${title}`;
 }
-async function promptVaultSource(driver, ctx, defaultValue) {
-    const value = await promptText(driver, ctx, "VAULT_SOURCE (local/synology)", defaultValue, {
-        validator: (candidate) => {
-            try {
-                normalizeVaultSource(candidate);
-                return null;
-            }
-            catch (error) {
-                return error instanceof Error ? error.message : String(error);
-            }
-        },
-        normalize: (candidate) => normalizeVaultSource(candidate),
+async function promptVaultSource(driver, defaultValue) {
+    return driver.select({
+        message: "VAULT_SOURCE",
+        defaultValue,
+        choices: [
+            {
+                value: "local",
+                label: "local",
+                description: "Read the vault directly from the local filesystem.",
+            },
+            {
+                value: "synology",
+                label: "synology",
+                description: "Download the vault from Synology NAS into a local cache.",
+            },
+        ],
     });
-    return value;
 }
-async function promptVaultHashMode(driver, ctx, defaultValue) {
-    const value = await promptText(driver, ctx, "VAULT_HASH_MODE", defaultValue, {
-        validator: (candidate) => {
-            try {
-                parseVaultHashMode(candidate);
-                return null;
-            }
-            catch (error) {
-                return error instanceof Error ? error.message : String(error);
-            }
-        },
-        normalize: (candidate) => parseVaultHashMode(candidate),
+async function promptVaultHashMode(driver, defaultValue) {
+    return driver.select({
+        message: "VAULT_HASH_MODE",
+        defaultValue,
+        choices: [
+            {
+                value: "content",
+                label: "content",
+                description: "Hash file content to detect changes.",
+            },
+            {
+                value: "mtime",
+                label: "mtime",
+                description: "Use modification time, recommended for remote Synology sync.",
+            },
+        ],
     });
-    return value;
 }
 function canReadWrite(targetPath) {
     accessSync(targetPath, constants.R_OK | constants.W_OK);
@@ -269,7 +385,7 @@ function getPathDefaults(env, cwd) {
     };
 }
 async function collectEmbeddingSettings(driver, ctx, defaults, env) {
-    const enabled = await promptYesNo(driver, ctx, "Enable semantic search with embeddings?", defaults.embeddingEnabled);
+    const enabled = await promptYesNo(driver, "Enable semantic search with embeddings?", defaults.embeddingEnabled);
     if (!enabled) {
         return {
             embeddingEnabled: false,
@@ -280,11 +396,15 @@ async function collectEmbeddingSettings(driver, ctx, defaults, env) {
         };
     }
     while (true) {
-        const embeddingBaseUrl = await promptText(driver, ctx, "EMBEDDING_BASE_URL", defaults.embeddingBaseUrl ?? "https://api.openai.com/v1", { validator: (value) => validateUrl(value, "EMBEDDING_BASE_URL") });
-        const embeddingApiKey = await promptText(driver, ctx, "EMBEDDING_API_KEY", defaults.embeddingApiKey ?? "", { required: true });
-        const embeddingModel = await promptText(driver, ctx, "EMBEDDING_MODEL", defaults.embeddingModel ?? "text-embedding-3-small", { required: true });
-        const embeddingDimensions = await promptText(driver, ctx, "EMBEDDING_DIMENSIONS", defaults.embeddingDimensions ?? "384", { validator: (value) => validateNonNegativeInteger(value, "EMBEDDING_DIMENSIONS") });
-        const shouldProbe = await promptYesNo(driver, ctx, "Probe the embedding endpoint now?", false);
+        const embeddingBaseUrl = await promptText(driver, "EMBEDDING_BASE_URL", defaults.embeddingBaseUrl ?? "https://api.openai.com/v1", {
+            validator: (value) => validateUrl(value, "EMBEDDING_BASE_URL"),
+        });
+        const embeddingApiKey = await promptPassword(driver, "EMBEDDING_API_KEY", defaults.embeddingApiKey ?? "", {
+            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 shouldProbe = await promptYesNo(driver, "Probe the embedding endpoint now?", false);
         if (shouldProbe) {
             try {
                 const probeEnv = {
@@ -304,7 +424,7 @@ async function collectEmbeddingSettings(driver, ctx, defaults, env) {
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 ctx.output.write(`Embedding probe failed: ${message}\n`);
-                if (await promptYesNo(driver, ctx, "Re-enter embedding settings?", true)) {
+                if (await promptYesNo(driver, "Re-enter embedding settings?", true)) {
                     continue;
                 }
             }
@@ -319,7 +439,7 @@ async function collectEmbeddingSettings(driver, ctx, defaults, env) {
     }
 }
 async function collectAgentSettings(driver, ctx, defaults) {
-    const enabled = await promptYesNo(driver, ctx, "Enable automatic vault-to-wiki processing?", defaults.agentEnabled);
+    const enabled = await promptYesNo(driver, "Enable automatic vault-to-wiki processing?", defaults.agentEnabled);
     if (!enabled) {
         return {
             agentEnabled: false,
@@ -331,17 +451,19 @@ async function collectAgentSettings(driver, ctx, defaults) {
     }
     return {
         agentEnabled: true,
-        agentBaseUrl: await promptText(driver, ctx, "WIKI_AGENT_BASE_URL", defaults.agentBaseUrl ?? "https://api.openai.com/v1", { validator: (value) => validateUrl(value, "WIKI_AGENT_BASE_URL") }),
-        agentApiKey: await promptText(driver, ctx, "WIKI_AGENT_API_KEY", defaults.agentApiKey ?? "", { required: true }),
-        agentModel: await promptText(driver, ctx, "WIKI_AGENT_MODEL", defaults.agentModel ?? "", { required: true }),
-        agentBatchSize: await promptText(driver, ctx, "WIKI_AGENT_BATCH_SIZE", defaults.agentBatchSize ?? "5", { validator: (value) => validateNonNegativeInteger(value, "WIKI_AGENT_BATCH_SIZE") }),
+        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") }),
     };
 }
 async function collectSynologySettings(driver, ctx, defaults) {
-    const synologyBaseUrl = await promptText(driver, ctx, "SYNOLOGY_BASE_URL", defaults.synologyBaseUrl ?? "https://nas.example.com:5001", { validator: (value) => validateUrl(value, "SYNOLOGY_BASE_URL") });
-    const synologyUsername = await promptText(driver, ctx, "SYNOLOGY_USERNAME", defaults.synologyUsername ?? "", { required: true });
-    const synologyPassword = await promptText(driver, ctx, "SYNOLOGY_PASSWORD", defaults.synologyPassword ?? "", { required: true });
-    const synologyRemotePath = await promptText(driver, ctx, "VAULT_SYNOLOGY_REMOTE_PATH", defaults.synologyRemotePath ?? "/homes/user/wiki-vault", {
+    const synologyBaseUrl = await promptText(driver, "SYNOLOGY_BASE_URL", defaults.synologyBaseUrl ?? "https://nas.example.com:5001", { validator: (value) => validateUrl(value, "SYNOLOGY_BASE_URL") });
+    const synologyUsername = await promptText(driver, "SYNOLOGY_USERNAME", defaults.synologyUsername ?? "", { required: true });
+    const synologyPassword = await promptPassword(driver, "SYNOLOGY_PASSWORD", defaults.synologyPassword ?? "", {
+        required: true,
+    });
+    const synologyRemotePath = await promptText(driver, "VAULT_SYNOLOGY_REMOTE_PATH", defaults.synologyRemotePath ?? "/homes/user/wiki-vault", {
         validator: (value) => {
             try {
                 normalizeSynologyRemotePath(value);
@@ -353,9 +475,9 @@ async function collectSynologySettings(driver, ctx, defaults) {
         },
         normalize: (value) => normalizeSynologyRemotePath(value),
     });
-    const vaultHashMode = await promptVaultHashMode(driver, ctx, "mtime");
-    const synologyVerifySsl = await promptYesNo(driver, ctx, "SYNOLOGY_VERIFY_SSL", defaults.synologyVerifySsl);
-    const synologyReadonly = await promptYesNo(driver, ctx, "SYNOLOGY_READONLY", defaults.synologyReadonly);
+    const vaultHashMode = await promptVaultHashMode(driver, "mtime");
+    const synologyVerifySsl = await promptYesNo(driver, "SYNOLOGY_VERIFY_SSL", defaults.synologyVerifySsl);
+    const synologyReadonly = await promptYesNo(driver, "SYNOLOGY_READONLY", defaults.synologyReadonly);
     return {
         vaultHashMode,
         synologyBaseUrl,
@@ -371,7 +493,7 @@ async function collectParserSkillSettings(driver, ctx, defaults, wikiPath) {
     ctx.output.write(`tiangong-wiki-skill is required and will be installed at ${path.join(skillsRoot, "tiangong-wiki-skill")}.\n`);
     const selected = new Set(defaults.parserSkills);
     for (const skill of OPTIONAL_PARSER_SKILLS) {
-        const enabled = await promptYesNo(driver, ctx, `Install parser skill ${skill.name} (${skill.summary})?`, selected.has(skill.name));
+        const enabled = await promptYesNo(driver, `Install parser skill ${skill.name} (${skill.summary})?`, selected.has(skill.name));
         if (enabled) {
             selected.add(skill.name);
         }
@@ -465,27 +587,27 @@ export async function runSetupWizard(env = process.env, options = {}) {
     const ctx = { cwd, output };
     try {
         writeSection(output, "Step 1: Configuration file");
-        const envFilePath = await promptText(driver, ctx, "Path for the generated .wiki.env file", defaults.envFilePath, {
+        const envFilePath = await promptText(driver, "Path for the generated .wiki.env file", defaults.envFilePath, {
             normalize: (value) => resolveInputPath(value, cwd),
         });
         writeSection(output, "Step 2: Vault source");
-        const vaultSource = await promptVaultSource(driver, ctx, defaults.vaultSource);
+        const vaultSource = await promptVaultSource(driver, defaults.vaultSource);
         const totalSteps = vaultSource === "synology" ? 9 : 8;
         writeSection(output, formatStep(3, totalSteps, "Core paths"));
-        const wikiPath = await promptText(driver, ctx, "WIKI_PATH", defaults.wikiPath, {
+        const wikiPath = await promptText(driver, "WIKI_PATH", defaults.wikiPath, {
             normalize: (value) => resolveInputPath(value, cwd),
             validator: (value) => validateWikiPath(resolveInputPath(value, cwd)),
         });
-        const vaultPath = await promptText(driver, ctx, vaultSource === "synology" ? "VAULT_PATH (local cache directory)" : "VAULT_PATH", defaults.vaultPath, {
+        const vaultPath = await promptText(driver, vaultSource === "synology" ? "VAULT_PATH (local cache directory)" : "VAULT_PATH", defaults.vaultPath, {
             normalize: (value) => resolveInputPath(value, cwd),
         });
-        const dbPath = await promptText(driver, ctx, "WIKI_DB_PATH", defaults.dbPath, {
+        const dbPath = await promptText(driver, "WIKI_DB_PATH", defaults.dbPath, {
             normalize: (value) => resolveInputPath(value, cwd),
         });
-        const configPath = await promptText(driver, ctx, "WIKI_CONFIG_PATH", defaults.configPath, {
+        const configPath = await promptText(driver, "WIKI_CONFIG_PATH", defaults.configPath, {
             normalize: (value) => resolveInputPath(value, cwd),
         });
-        const templatesPath = await promptText(driver, ctx, "WIKI_TEMPLATES_PATH", defaults.templatesPath, {
+        const templatesPath = await promptText(driver, "WIKI_TEMPLATES_PATH", defaults.templatesPath, {
             normalize: (value) => resolveInputPath(value, cwd),
         });
         let synologyValues;
@@ -506,7 +628,7 @@ export async function runSetupWizard(env = process.env, options = {}) {
             };
         }
         writeSection(output, formatStep(vaultSource === "synology" ? 5 : 4, totalSteps, "Sync schedule"));
-        const syncInterval = await promptText(driver, ctx, "WIKI_SYNC_INTERVAL (seconds)", defaults.syncInterval, {
+        const syncInterval = await promptText(driver, "WIKI_SYNC_INTERVAL (seconds)", defaults.syncInterval, {
             validator: (value) => validateNonNegativeInteger(value, "WIKI_SYNC_INTERVAL"),
         });
         writeSection(output, formatStep(vaultSource === "synology" ? 6 : 5, totalSteps, "Embedding configuration"));
@@ -531,7 +653,7 @@ export async function runSetupWizard(env = process.env, options = {}) {
         };
         writeSection(output, formatStep(totalSteps, totalSteps, "Confirm"));
         output.write(`${buildSetupSummary(values)}\n`);
-        const confirmed = await promptYesNo(driver, ctx, "Write configuration and scaffold workspace assets?", true);
+        const confirmed = await promptYesNo(driver, "Write configuration and scaffold workspace assets?", true);
         if (!confirmed) {
             throw new AppError("Setup aborted before writing any files.", "runtime");
         }
@@ -551,9 +673,12 @@ 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}`,
             `parser skills: ${values.parserSkills.length > 0 ? values.parserSkills.join(", ") : "(none)"}`,
@@ -565,6 +690,11 @@ export async function runSetupWizard(env = process.env, options = {}) {
                 : []),
             "",
             "Next steps:",
+            `- 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.",
             ...(values.vaultSource === "synology"
@@ -576,6 +706,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,
@@ -892,11 +1023,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;
@@ -930,6 +1076,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,