@tiangong-ai/cli 0.0.30 → 0.0.32

package/dist/research/workspace/setup.js

@@ -8,10 +8,10 @@ import { CliError } from "../../errors.js";
 import { loadCapabilityDeclarations } from "./capabilities.js";
 import { inspectResearchContext } from "./context.js";
 import { inspectCapabilityCredentialEnvironment, loadCapabilityCredentialMapForIds, reconcileCapabilityCredentialEnvironment, setCapabilityCredentialValue, } from "./credentials.js";
-import { configureExternalSkillProfile, configureTiangongSciCapability, doctorExternalCapabilities, EXTERNAL_SKILL_CONTEXT_PROFILE, EXTERNAL_SKILL_MEDIA_PROFILE, EXTERNAL_SKILL_PROFILE, reconcileSetupManagedCapabilities, } from "./external-skills.js";
+import { configureExternalSkillProfile, configureTiangongDatabaseCapability, doctorExternalCapabilities, EXTERNAL_SKILL_CONTEXT_PROFILE, EXTERNAL_SKILL_MEDIA_PROFILE, EXTERNAL_SKILL_PROFILE, reconcileSetupManagedCapabilities, } from "./external-skills.js";
 import { appendJournalEvent } from "./journal.js";
 import { configuredResearchSecrets, isSensitiveEnvironmentName, sanitizeResearchRecord, sanitizeResearchText, } from "./sanitization.js";
-import { inspectResearchSetupCatalog, RESEARCH_SETUP_CREDENTIALS, RESEARCH_SETUP_INSTALLER, RESEARCH_SETUP_SETTINGS, RESEARCH_SETUP_SKILLS, resolveSetupSkills, setupSkill, setupSource, setupTargetRoot, } from "./setup-catalog.js";
+import { inspectResearchSetupCatalog, RESEARCH_SETUP_CREDENTIALS, RESEARCH_SETUP_INSTALLER, RESEARCH_SETUP_SETTINGS, RESEARCH_SETUP_SKILLS, resolveSetupSkills, setupSkill, setupSource, setupTargetRoot, verifyResearchSetupRuntimeContract, } from "./setup-catalog.js";
 import { acquireFileLock, canonicalJson, ensureDirectory, fileSize, hashRegularTree, isObject, pathExists, REGULAR_TREE_HASH_ALGORITHM, readJsonFile, sha256File, sha256Text, workspacePaths, writeJsonAtomic, writeTextAtomic, } from "./storage.js";
 import { packageVersion } from "./constants.js";
 import { doctorResearchWorkspace, initializeResearchWorkspace, loadWorkspaceConfig, } from "./workspace.js";
@@ -34,6 +34,7 @@ export async function createResearchSetupPlan(input) {
     await assertWorkspaceDirectory(root);
     const scope = input.scope ?? "project";
     const agents = normalizeAgents(input.agents ?? ["codex"]);
+    const agentRoutes = normalizeAgentRoutes(input.agentRoutes);
     if (!input.confirmNetworkDownloads &&
         input.skillIds.length + BRAVE_PROFILE_SKILLS[input.evidenceProfile].length) {
         throw setupError({
@@ -88,6 +89,18 @@ export async function createResearchSetupPlan(input) {
     const selected = resolveSetupSkills([
         ...new Set([...BRAVE_PROFILE_SKILLS[input.evidenceProfile], ...input.skillIds]),
     ]);
+    const producerInstallTarget = agentRoutes.producerAgent === "codex" ? "codex" : "claude-code";
+    if (selected.some((skill) => skill.role === "orchestrator") &&
+        !agents.includes(producerInstallTarget)) {
+        throw setupError({
+            code: "RESEARCH_SETUP_SELECTION_INVALID",
+            step: "selection",
+            reason: `The native ${agentRoutes.producerAgent} producer requires the orchestrator Skill in its project Skill root.`,
+            minimumAction: `Include ${producerInstallTarget} in --agents, or choose the other native producer.`,
+            retryCommand: "tiangong-ai research setup plan --help",
+            exitCode: 2,
+        });
+    }
     if (selected.some((skill) => skill.role === "evidence-capability") && !agents.includes("codex")) {
         throw setupError({
             code: "RESEARCH_SETUP_SELECTION_INVALID",
@@ -102,7 +115,6 @@ export async function createResearchSetupPlan(input) {
     validateLicenseAcceptances(selected, input.acceptedLicenseIds);
     const settings = normalizedSettings(selected, input.settings ?? {});
     const credentialSources = normalizedCredentialSources(selected, input.credentialEnvironment ?? {});
-    const agentRoutes = normalizeAgentRoutes(input.agentRoutes);
     const targets = plannedInstallTargets(root, scope, agents, input.environment ?? process.env, input.targetRoots);
     const selectedSources = [...new Set(selected.map((skill) => skill.sourceId))]
         .map(setupSource)
@@ -433,11 +445,11 @@ export async function applyResearchSetupPlan(planPath, options = {}) {
         });
         state = await updateSetupState(root, {
             ...state,
-            status: report.readiness === "READY"
-                ? "ready"
-                : report.readiness === "PARTIALLY_READY"
+            status: report.researchReadiness === "BLOCKED"
+                ? "blocked"
+                : report.overallReadiness === "PARTIALLY_READY"
                     ? "partially-ready"
-                    : "blocked",
+                    : "ready",
             currentStep: null,
             completedSteps: [...new Set([...state.completedSteps, "doctor"])],
         });
@@ -691,41 +703,85 @@ export async function doctorResearchSetup(workspace, options = {}) {
             return `${command} is executable (${sanitizeResearchText(result.stdout.trim()).slice(0, 120)}).`;
         });
     }
-    await setupDoctorCheck(checks, "platform-sandbox", "runtime", async () => {
-        if (platform() === "darwin") {
-            const info = await lstat("/usr/bin/sandbox-exec").catch(() => undefined);
-            if (!info?.isFile())
-                throw new Error("/usr/bin/sandbox-exec is unavailable");
-            return "macOS sandbox-exec is available.";
+    if (platform() === "win32") {
+        const production = plan.workspace.mode === "production-research";
+        checks.push({
+            id: "platform-sandbox",
+            category: "runtime",
+            scope: "research-core",
+            status: production ? "fail" : "warn",
+            detail: production
+                ? "Production research execution is unsupported on Windows because no approved capsule sandbox is available."
+                : "Windows can inspect and smoke-test setup state, but native research execution requires an approved macOS or Linux capsule sandbox.",
+            minimumAction: production
+                ? "Run production research on macOS with sandbox-exec or Linux with Bubblewrap."
+                : "Use macOS or Linux before switching this workspace to production-research mode.",
+            blocking: production,
+            requiredFor: production ? ["setup", "research-core"] : [],
+        });
+    }
+    else {
+        await setupDoctorCheck(checks, "platform-sandbox", "runtime", async () => {
+            if (platform() === "darwin") {
+                const info = await lstat("/usr/bin/sandbox-exec").catch(() => undefined);
+                if (!info?.isFile())
+                    throw new Error("/usr/bin/sandbox-exec is unavailable");
+                return "macOS sandbox-exec is available.";
+            }
+            if (platform() === "linux") {
+                const result = await runner({
+                    command: "bwrap",
+                    args: ["--version"],
+                    cwd: root,
+                    environment: installerEnvironment(environment),
+                    timeoutMs: 15_000,
+                });
+                if (result.exitCode !== 0)
+                    throw new Error("Bubblewrap is unavailable");
+                return "Linux Bubblewrap is available.";
+            }
+            throw new Error("Research execution is unsupported on this platform");
+        });
+    }
+    checks.push({
+        id: "agent.native-producer",
+        category: "agent",
+        scope: "research-core",
+        status: "pass",
+        detail: `Producer work is bound to the current interactive ${plan.agentRoutes.producerAgent} host; setup will not launch it as a child process.`,
+        minimumAction: null,
+        blocking: true,
+        requiredFor: ["setup", "research-core"],
+    });
+    const reviewerCommand = plan.agentRoutes.reviewerAgent;
+    await setupDoctorCheck(checks, `agent.${reviewerCommand}.reviewer`, "agent", async () => {
+        const result = await runner({
+            command: reviewerCommand,
+            args: ["--version"],
+            cwd: root,
+            environment: agentDoctorEnvironment(environment),
+            timeoutMs: 30_000,
+        });
+        if (result.exitCode !== 0)
+            throw new Error(`${reviewerCommand} is not executable`);
+        return `${reviewerCommand} reviewer CLI is executable (${sanitizeResearchText(result.stdout.trim()).slice(0, 160)}).`;
+    });
+    await setupDoctorCheck(checks, "agent-route-config", "agent", async () => {
+        const config = await loadWorkspaceConfig(root);
+        if (config.producer.executionMode !== "native-host" ||
+            config.reviewer.executionMode !== "headless-cli" ||
+            config.producer.agent === config.reviewer.agent) {
+            throw new Error("Workspace must bind producer=native-host and reviewer=headless-cli on different agent families.");
         }
-        if (platform() === "linux") {
-            const result = await runner({
-                command: "bwrap",
-                args: ["--version"],
-                cwd: root,
-                environment: installerEnvironment(environment),
-                timeoutMs: 15_000,
-            });
-            if (result.exitCode !== 0)
-                throw new Error("Bubblewrap is unavailable");
-            return "Linux Bubblewrap is available.";
+        if (config.mode === "production-research" &&
+            (!config.producer.model ||
+                !config.reviewer.model ||
+                !config.producer.pricing ||
+                !config.reviewer.pricing)) {
+            throw new Error("Production agent models and reviewed pricing are incomplete.");
         }
-        throw new Error("Research execution is unsupported on this platform");
+        return `${config.producer.agent}(native-host) -> ${config.reviewer.agent}(headless-cli).`;
     });
-    for (const command of ["codex", "claude"]) {
-        await setupDoctorCheck(checks, `agent.${command}`, "agent", async () => {
-            const result = await runner({
-                command,
-                args: ["--version"],
-                cwd: root,
-                environment: agentDoctorEnvironment(environment),
-                timeoutMs: 30_000,
-            });
-            if (result.exitCode !== 0)
-                throw new Error(`${command} is not executable`);
-            return `${command} is executable (${sanitizeResearchText(result.stdout.trim()).slice(0, 160)}).`;
-        });
-    }
     const selected = plan.selection.skillIds.map(setupSkill);
     const installations = await inspectSelectedInstallations(plan, selected, environment);
     for (const installation of installations) {
@@ -802,10 +858,15 @@ export async function doctorResearchSetup(workspace, options = {}) {
     }
     await appendDependencyChecks(checks, selected, runner, root, environment);
     let capabilityDoctor = null;
+    const blockingBeforeLive = checks
+        .map((check) => normalizeSetupDoctorCheck(check, selected))
+        .filter((check) => check.blocking && check.status === "fail")
+        .map((check) => check.id);
+    const runRequiredLive = options.live === true && blockingBeforeLive.length === 0;
     if (selected.some((skill) => skill.role === "evidence-capability")) {
         try {
             capabilityDoctor = await doctorExternalCapabilities(root, {
-                live: options.live === true,
+                live: runRequiredLive,
                 fetcher,
                 sleeper,
             });
@@ -829,7 +890,20 @@ export async function doctorResearchSetup(workspace, options = {}) {
             });
         }
     }
-    if (options.live) {
+    if (options.live === true && !runRequiredLive) {
+        checks.push({
+            id: "live.required-capabilities.skipped",
+            category: "live-check",
+            scope: "evidence",
+            status: "fail",
+            detail: "Required live capability probes were not started because a static blocking prerequisite failed.",
+            minimumAction: "Resolve the static blocking prerequisites, then rerun live doctor checks.",
+            blocking: true,
+            requiredFor: ["setup", "research-core"],
+            skippedBecause: blockingBeforeLive.join(", "),
+        });
+    }
+    if (runRequiredLive) {
         await appendCompanionLiveChecks(checks, {
             plan,
             selected,
@@ -839,13 +913,45 @@ export async function doctorResearchSetup(workspace, options = {}) {
             allowSyntheticUnstructureUpload: options.allowSyntheticUnstructureUpload === true,
         });
     }
+    else if (options.live === true &&
+        selected.some((skill) => ["input-preprocessor", "acquisition-adapter", "post-closure-authoring"].includes(skill.role))) {
+        checks.push({
+            id: "live.optional-components.skipped",
+            category: "live-check",
+            status: "warn",
+            detail: "Optional component diagnostics were skipped after a static blocking prerequisite failed.",
+            minimumAction: "Resolve the blocking prerequisites before retrying optional diagnostics.",
+            blocking: false,
+            requiredFor: [],
+            skippedBecause: blockingBeforeLive.join(", "),
+        });
+    }
     let workspaceDoctor = null;
+    const blockingPrerequisiteFailures = checks
+        .map((check) => normalizeSetupDoctorCheck(check, selected))
+        .filter((check) => check.blocking && check.status === "fail")
+        .map((check) => check.id);
+    const runAgentSmoke = options.agentSmoke === true && blockingPrerequisiteFailures.length === 0;
+    if (options.agentSmoke === true && !runAgentSmoke) {
+        checks.push({
+            id: "agent-reviewer-smoke.skipped",
+            category: "agent",
+            scope: "review",
+            status: "fail",
+            detail: "The paid reviewer smoke was not started because a zero/low-cost blocking prerequisite failed.",
+            minimumAction: "Resolve the listed blocking prerequisites, then rerun the explicitly confirmed reviewer smoke.",
+            blocking: true,
+            requiredFor: ["setup", "research-core"],
+            skippedBecause: blockingPrerequisiteFailures.join(", "),
+        });
+    }
     try {
         workspaceDoctor = await doctorResearchWorkspace(root, {
-            agentSmoke: options.agentSmoke === true,
-            capabilitySmoke: options.live === true,
+            agentSmoke: runAgentSmoke,
+            capabilitySmoke: runRequiredLive,
             environment,
             capabilityFetcher: fetcher,
+            ...(capabilityDoctor === null ? {} : { capabilityDoctorResult: capabilityDoctor }),
             ...(options.executor === undefined ? {} : { executor: options.executor }),
         });
         const requiredRuntimeChecks = options.agentSmoke === true || options.live === true;
@@ -888,9 +994,16 @@ export async function doctorResearchSetup(workspace, options = {}) {
                 : `Run tiangong-ai research setup doctor --live --workspace ${root} --json after reviewing quota impact.`,
         });
     }
-    const readiness = checks.some((check) => check.status === "fail")
+    const scopedChecks = checks.map((check) => normalizeSetupDoctorCheck(check, selected));
+    const researchReadiness = scopedChecks.some((check) => check.blocking && check.status === "fail")
+        ? "BLOCKED"
+        : "READY";
+    const preprocessingReadiness = setupDomainReadiness(scopedChecks, "preprocessing");
+    const acquisitionReadiness = setupDomainReadiness(scopedChecks, "acquisition");
+    const authoringReadiness = setupDomainReadiness(scopedChecks, "authoring");
+    const overallReadiness = researchReadiness === "BLOCKED"
         ? "BLOCKED"
-        : checks.some((check) => check.status === "warn")
+        : scopedChecks.some((check) => check.status !== "pass")
             ? "PARTIALLY_READY"
             : "READY";
     const setupSecrets = [
@@ -908,14 +1021,19 @@ export async function doctorResearchSetup(workspace, options = {}) {
         planSha256: plan.planSha256,
         checkedAt: new Date().toISOString(),
         mode: options.live ? "live" : "static",
-        readiness,
-        checks,
+        readiness: researchReadiness,
+        researchReadiness,
+        preprocessingReadiness,
+        acquisitionReadiness,
+        authoringReadiness,
+        overallReadiness,
+        checks: scopedChecks,
         capabilityDoctor,
         workspaceDoctor,
         summary: {
-            pass: checks.filter((check) => check.status === "pass").length,
-            warn: checks.filter((check) => check.status === "warn").length,
-            fail: checks.filter((check) => check.status === "fail").length,
+            pass: scopedChecks.filter((check) => check.status === "pass").length,
+            warn: scopedChecks.filter((check) => check.status === "warn").length,
+            fail: scopedChecks.filter((check) => check.status === "fail").length,
         },
     }, setupSecrets);
     await writeJsonAtomic(paths.setupReport, report);
@@ -969,22 +1087,24 @@ export async function checkResearchSetupUpdates(workspace, environment = process
             });
         }
     }
+    const cliVersionDrift = plan.cli.version === packageVersion()
+        ? null
+        : { planned: plan.cli.version, active: packageVersion() };
+    const updateAvailable = drift.length > 0 || cliVersionDrift !== null;
     return {
         schemaVersion: 1,
         workspace: root,
         checkedAt: new Date().toISOString(),
-        updateAvailable: drift.length > 0 || plan.cli.version !== packageVersion(),
-        cliVersionDrift: plan.cli.version === packageVersion()
-            ? null
-            : { planned: plan.cli.version, active: packageVersion() },
+        updateAvailable,
+        cliVersionDrift,
         drift,
         currentInstaller: RESEARCH_SETUP_INSTALLER,
         catalog,
         policy: {
             automaticUpdate: false,
             floatingUpdate: false,
-            minimumAction: drift.length
-                ? "Use the newer CLI to create and review a replacement immutable plan; upgrade never runs a floating skills update."
+            minimumAction: updateAvailable
+                ? "Use the active exact CLI release to create, review, and apply a replacement immutable plan; upgrade never runs a floating CLI or Skills update."
                 : "No catalog migration is required. Installed tree drift is reported separately by setup status/doctor.",
         },
     };
@@ -1204,10 +1324,20 @@ function assertPlanMatchesCatalog(plan) {
     }
 }
 function validAgentRoutes(value) {
-    const allowed = new Set(["producerModel", "reviewerModel", "producerPricing", "reviewerPricing"]);
+    const allowed = new Set([
+        "producerAgent",
+        "reviewerAgent",
+        "producerModel",
+        "reviewerModel",
+        "producerPricing",
+        "reviewerPricing",
+    ]);
     if (Object.keys(value).some((key) => !allowed.has(key)))
         return false;
-    if (!(value.producerModel === null || typeof value.producerModel === "string") ||
+    if ((value.producerAgent !== "codex" && value.producerAgent !== "claude") ||
+        (value.reviewerAgent !== "codex" && value.reviewerAgent !== "claude") ||
+        value.producerAgent === value.reviewerAgent ||
+        !(value.producerModel === null || typeof value.producerModel === "string") ||
         !(value.reviewerModel === null || typeof value.reviewerModel === "string")) {
         return false;
     }
@@ -1316,13 +1446,39 @@ function normalizedCredentialSources(selected, supplied) {
         .sort((left, right) => left.id.localeCompare(right.id));
 }
 function normalizeAgentRoutes(value) {
+    const producerAgent = normalizeAgentKind(value?.producerAgent ?? "codex", "producer");
+    const reviewerAgent = normalizeAgentKind(value?.reviewerAgent ?? (producerAgent === "codex" ? "claude" : "codex"), "reviewer");
+    if (producerAgent === reviewerAgent) {
+        throw setupError({
+            code: "RESEARCH_SETUP_AGENT_ROUTE_INVALID",
+            step: "agent-route",
+            reason: "The native producer and independent reviewer must use different agent families.",
+            minimumAction: "Choose Codex + Claude Code in either producer/reviewer order.",
+            retryCommand: "tiangong-ai research setup plan --help",
+            exitCode: 2,
+        });
+    }
     return {
+        producerAgent,
+        reviewerAgent,
         producerModel: normalizeNullableIdentifier(value?.producerModel),
         reviewerModel: normalizeNullableIdentifier(value?.reviewerModel),
         producerPricing: normalizePricing(value?.producerPricing),
         reviewerPricing: normalizePricing(value?.reviewerPricing),
     };
 }
+function normalizeAgentKind(value, label) {
+    if (value === "codex" || value === "claude")
+        return value;
+    throw setupError({
+        code: "RESEARCH_SETUP_AGENT_ROUTE_INVALID",
+        step: "agent-route",
+        reason: `${label} agent must be codex or claude.`,
+        minimumAction: "Choose Codex or Claude Code and keep the reviewer on the other family.",
+        retryCommand: "tiangong-ai research setup plan --help",
+        exitCode: 2,
+    });
+}
 function normalizePricing(value) {
     if (value === undefined || value === null)
         return null;
@@ -1472,33 +1628,29 @@ async function ensureSetupWorkspace(plan) {
     await initializeResearchWorkspace(plan.workspace.path, plan.workspace.name, plan.workspace.mode);
 }
 async function configureAgentRoutes(plan) {
-    if (!plan.agentRoutes.producerModel &&
-        !plan.agentRoutes.reviewerModel &&
-        !plan.agentRoutes.producerPricing &&
-        !plan.agentRoutes.reviewerPricing) {
-        return;
-    }
     const paths = workspacePaths(plan.workspace.path);
     const config = await loadWorkspaceConfig(plan.workspace.path);
     const updated = {
         ...config,
-        producer: {
-            ...config.producer,
-            ...(plan.agentRoutes.producerModel === null ? {} : { model: plan.agentRoutes.producerModel }),
-            ...(plan.agentRoutes.producerPricing === null
-                ? {}
-                : { pricing: plan.agentRoutes.producerPricing }),
-        },
-        reviewer: {
-            ...config.reviewer,
-            ...(plan.agentRoutes.reviewerModel === null ? {} : { model: plan.agentRoutes.reviewerModel }),
-            ...(plan.agentRoutes.reviewerPricing === null
-                ? {}
-                : { pricing: plan.agentRoutes.reviewerPricing }),
-        },
+        producer: setupAgentRoute(config.producer, plan.agentRoutes.producerAgent, "native-host", plan.agentRoutes.producerModel, plan.agentRoutes.producerPricing),
+        reviewer: setupAgentRoute(config.reviewer, plan.agentRoutes.reviewerAgent, "headless-cli", plan.agentRoutes.reviewerModel, plan.agentRoutes.reviewerPricing),
     };
     await writeJsonAtomic(paths.config, updated);
 }
+function setupAgentRoute(current, agent, executionMode, plannedModel, plannedPricing) {
+    const sameAgent = current.agent === agent;
+    return {
+        agent,
+        executionMode,
+        binary: agent === "codex" ? "codex" : "claude",
+        model: plannedModel ?? (sameAgent ? current.model : null),
+        effort: sameAgent ? (current.effort ?? "low") : "low",
+        ...(agent === "codex" ? { verbosity: sameAgent ? (current.verbosity ?? "low") : "low" } : {}),
+        ...((plannedPricing ?? (sameAgent ? current.pricing : undefined)) === undefined
+            ? {}
+            : { pricing: plannedPricing ?? current.pricing }),
+    };
+}
 async function inspectSelectedInstallations(plan, selected, _environment) {
     const results = [];
     for (const agent of plan.install.agents) {
@@ -1719,6 +1871,7 @@ async function ensureSetupSourceCheckout(plan, sourceId, runner, environment) {
                 },
             });
         }
+        await verifyResearchSetupRuntimeContract(sourcePath, setupSkill(skill.id));
     }
     return checkout;
 }
@@ -1759,8 +1912,30 @@ async function installSetupSkills(input) {
 }
 async function configureSelectedCapabilities(plan, _environment) {
     const hasBraveProfile = plan.selection.evidenceProfile !== "none";
-    const hasTiangongSci = plan.selection.skillIds.includes("tiangong.kb-sci-search");
-    const codexRoot = hasBraveProfile || hasTiangongSci ? plannedTargetRoot(plan, "codex") : null;
+    const tiangongDatabases = [
+        {
+            kind: "sci",
+            skillId: "tiangong.kb-sci-search",
+            settingPrefix: "tiangong.sci",
+            catalogId: "first-party.tiangong.kb-sci-search",
+            capabilityId: "database.tiangong.sci-search",
+        },
+        {
+            kind: "report",
+            skillId: "tiangong.kb-report-search",
+            settingPrefix: "tiangong.report",
+            catalogId: "first-party.tiangong.kb-report-search",
+            capabilityId: "database.tiangong.report-search",
+        },
+        {
+            kind: "patent",
+            skillId: "tiangong.kb-patent-search",
+            settingPrefix: "tiangong.patent",
+            catalogId: "first-party.tiangong.kb-patent-search",
+            capabilityId: "database.tiangong.patent-search",
+        },
+    ].filter((entry) => plan.selection.skillIds.includes(entry.skillId));
+    const codexRoot = hasBraveProfile || tiangongDatabases.length ? plannedTargetRoot(plan, "codex") : null;
     if (plan.selection.evidenceProfile !== "none") {
         await configureExternalSkillProfile({
             workspace: plan.workspace.path,
@@ -1768,10 +1943,11 @@ async function configureSelectedCapabilities(plan, _environment) {
             skillRoot: codexRoot,
         });
     }
-    if (hasTiangongSci) {
-        const skill = setupSkill("tiangong.kb-sci-search");
+    for (const database of tiangongDatabases) {
+        const skill = setupSkill(database.skillId);
         const source = setupSource(skill.sourceId);
-        await configureTiangongSciCapability({
+        await configureTiangongDatabaseCapability({
+            kind: database.kind,
             workspace: plan.workspace.path,
             skillPath: join(codexRoot, skill.skillName),
             source: {
@@ -1780,19 +1956,19 @@ async function configureSelectedCapabilities(plan, _environment) {
                 immutableRef: source.immutableRef,
                 expectedTreeSha256: skill.expectedTreeSha256,
                 license: "MIT",
-                catalogId: "first-party.tiangong.kb-sci-search",
+                catalogId: database.catalogId,
             },
-            endpoint: plan.settings["tiangong.sci.endpoint"],
-            ...(plan.settings["tiangong.sci.region"] === undefined
+            endpoint: plan.settings[`${database.settingPrefix}.endpoint`],
+            ...(plan.settings[`${database.settingPrefix}.region`] === undefined
                 ? {}
-                : { region: plan.settings["tiangong.sci.region"] }),
+                : { region: plan.settings[`${database.settingPrefix}.region`] }),
         });
     }
     await reconcileSetupManagedCapabilities({
         workspace: plan.workspace.path,
         selectedCapabilityIds: [
             ...BRAVE_PROFILE_SKILLS[plan.selection.evidenceProfile].map(setupManagedCapabilityId),
-            ...(hasTiangongSci ? ["database.tiangong.sci-search"] : []),
+            ...tiangongDatabases.map((database) => database.capabilityId),
         ],
     });
 }
@@ -1887,6 +2063,14 @@ async function assertRequiredCredentialPreflight(plan, environment) {
                 .join(", ")}), then retry this exact step.`,
             retryCommand: `tiangong-ai research setup retry --step credential-preflight --workspace ${plan.workspace.path} --json`,
             exitCode: 3,
+            diagnostics: {
+                executionMode: "setup-preflight",
+                credentialScope: [
+                    ...new Set(failures.map((failure) => definitions.find((definition) => definition.id === failure.id).storage)),
+                ].join("+"),
+                networkAttempted: false,
+                missingCredentialIds: failures.map((failure) => failure.id),
+            },
         });
     }
 }
@@ -2531,6 +2715,84 @@ async function archiveSetupGeneration(root) {
     }
     return prior.planSha256;
 }
+function normalizeSetupDoctorCheck(check, selected) {
+    const componentIds = check.componentIds ?? setupCheckComponentIds(check, selected);
+    const scope = check.scope ?? setupCheckScope(check, selected, componentIds);
+    const blocking = check.blocking ?? ["research-core", "evidence", "review"].includes(scope);
+    return {
+        ...check,
+        scope,
+        componentIds,
+        requiredFor: check.requiredFor ??
+            (blocking
+                ? ["setup", "research-core"]
+                : componentIds.map((componentId) => `component:${componentId}`)),
+        blocking,
+        componentGate: check.componentGate ?? check.id !== "live.semantic-scholar",
+    };
+}
+function setupCheckComponentIds(check, selected) {
+    if (check.id === "live.semantic-scholar")
+        return ["tiangong.academic-paper-download"];
+    if (check.id === "live.tiangong-unstructure") {
+        return ["tiangong.document-granular-decompose"];
+    }
+    if (check.id.startsWith("skill.")) {
+        return selected.filter((skill) => check.id.endsWith(`.${skill.id}`)).map((skill) => skill.id);
+    }
+    if (check.id.startsWith("setting.")) {
+        const id = check.id.slice("setting.".length);
+        const setting = RESEARCH_SETUP_SETTINGS.find((candidate) => candidate.id === id);
+        return selected
+            .filter((skill) => setting?.requiredBy.includes(skill.id))
+            .map((skill) => skill.id);
+    }
+    if (check.id.startsWith("credential.")) {
+        const id = check.id.slice("credential.".length);
+        const credential = RESEARCH_SETUP_CREDENTIALS.find((candidate) => candidate.id === id);
+        return selected
+            .filter((skill) => credential?.requiredBy.includes(skill.id))
+            .map((skill) => skill.id);
+    }
+    if (check.id.startsWith("dependency.")) {
+        const id = check.id.slice("dependency.".length);
+        return selected
+            .filter((skill) => skill.dependencies.some((item) => item.id === id))
+            .map((skill) => skill.id);
+    }
+    return [];
+}
+function setupCheckScope(check, selected, componentIds) {
+    if (check.id === "live.semantic-scholar")
+        return "acquisition";
+    if (check.id === "live.tiangong-unstructure")
+        return "preprocessing";
+    if (check.category === "evidence-capability" || check.id.includes("capability")) {
+        return "evidence";
+    }
+    if (check.category === "agent" || check.id.includes("attestation"))
+        return "review";
+    const roles = componentIds
+        .map((id) => selected.find((skill) => skill.id === id)?.role)
+        .filter((role) => Boolean(role));
+    if (roles.includes("evidence-capability"))
+        return "evidence";
+    if (roles.includes("input-preprocessor"))
+        return "preprocessing";
+    if (roles.includes("acquisition-adapter"))
+        return "acquisition";
+    if (roles.includes("post-closure-authoring"))
+        return "authoring";
+    return "research-core";
+}
+function setupDomainReadiness(checks, scope) {
+    const matching = checks.filter((check) => check.scope === scope);
+    if (matching.length === 0)
+        return "NOT_REQUIRED";
+    if (matching.some((check) => check.blocking && check.status === "fail"))
+        return "BLOCKED";
+    return matching.some((check) => check.status !== "pass") ? "DEGRADED" : "READY";
+}
 function requireAbsoluteWorkspace(value) {
     if (!value || !isAbsolute(value) || /[\0\r\n]/.test(value)) {
         throw setupError({
@@ -2885,7 +3147,7 @@ function commandFailure(step, command, result, root, environment) {
         exitCode: 3,
     });
 }
-async function setupDoctorCheck(checks, id, category, callback) {
+async function setupDoctorCheck(checks, id, category, callback, failureMinimumAction = `Resolve ${id}, then rerun research setup doctor.`) {
     try {
         checks.push({
             id,
@@ -2901,7 +3163,7 @@ async function setupDoctorCheck(checks, id, category, callback) {
             category,
             status: "fail",
             detail: sanitizeResearchText(error instanceof Error ? error.message : String(error)),
-            minimumAction: `Resolve ${id}, then rerun research setup doctor.`,
+            minimumAction: failureMinimumAction,
         });
     }
 }
@@ -2955,34 +3217,28 @@ async function appendDependencyChecks(checks, selected, runner, root, environmen
                 return `${dependency.requirement} is active.`;
             }
             throw new Error(`No automatic dependency check is declared for ${dependency.id}. ${dependency.minimumAction}`);
-        });
+        }, dependency.minimumAction);
     }
 }
 async function appendCompanionLiveChecks(checks, input) {
-    void input.sleeper;
     if (input.selected.some((skill) => skill.id === "tiangong.academic-paper-download")) {
-        await setupDoctorCheck(checks, "live.semantic-scholar", "live-check", async () => {
-            const apiKey = input.adapterCredentials.get("semantic-scholar.api-key");
-            const headers = new Headers({ Accept: "application/json" });
-            if (apiKey)
-                headers.set("x-api-key", apiKey);
-            const response = await input.fetcher("https://api.semanticscholar.org/graph/v1/paper/search?query=reproducible%20research&limit=1&fields=paperId", {
-                method: "GET",
-                headers,
-                redirect: "manual",
-                signal: AbortSignal.timeout(30_000),
-            });
-            if (response.status >= 300 && response.status < 400) {
-                throw new Error("Semantic Scholar returned a redirect; credential-bearing redirects are not followed.");
-            }
-            if (!response.ok) {
-                const detail = await boundedResponseText(response, 2_000, apiKey ? [apiKey] : []);
-                throw new Error(`Semantic Scholar live check returned HTTP ${response.status}${detail ? `: ${detail}` : ""}.`);
-            }
-            await response.body?.cancel().catch(() => undefined);
-            return apiKey
-                ? "Semantic Scholar accepted the configured optional API key."
-                : "Semantic Scholar public API is reachable without an optional API key.";
+        await appendSemanticScholarLiveCheck(checks, input);
+        const semanticScholar = checks.findLast((check) => check.id === "live.semantic-scholar");
+        checks.push({
+            id: "companion.tiangong.academic-paper-download",
+            category: "live-check",
+            scope: "acquisition",
+            componentIds: ["tiangong.academic-paper-download"],
+            status: semanticScholar?.status === "pass" ? "pass" : "warn",
+            detail: semanticScholar?.status === "pass"
+                ? "OA resolver diagnostics: Unpaywall=unknown, Semantic Scholar=ready, arXiv=unknown; the deterministic resolver order is unchanged."
+                : "OA resolver diagnostics: Unpaywall=unknown, Semantic Scholar=degraded, arXiv=unknown. The adapter remains available and actual acquisition will stop or request explicit browser handoff only after its ordered OA sources are exhausted.",
+            minimumAction: semanticScholar?.status === "pass"
+                ? null
+                : "Retry the resolver diagnostic later or configure its optional key; unrelated research remains authorized and no standalone evidence fallback is permitted.",
+            blocking: false,
+            componentGate: false,
+            requiredFor: ["component:tiangong.academic-paper-download"],
         });
     }
     if (input.selected.some((skill) => skill.id === "tiangong.document-granular-decompose")) {
@@ -2990,9 +3246,13 @@ async function appendCompanionLiveChecks(checks, input) {
             checks.push({
                 id: "live.tiangong-unstructure",
                 category: "live-check",
+                scope: "preprocessing",
+                componentIds: ["tiangong.document-granular-decompose"],
                 status: "warn",
                 detail: "Synthetic document upload was not explicitly authorized, so no document was sent.",
                 minimumAction: "Rerun setup doctor with the separate synthetic-upload confirmation after reviewing service cost and data policy.",
+                blocking: false,
+                componentGate: true,
             });
         }
         else {
@@ -3029,6 +3289,132 @@ async function appendCompanionLiveChecks(checks, input) {
         }
     }
 }
+async function appendSemanticScholarLiveCheck(checks, input) {
+    const apiKey = input.adapterCredentials.get("semantic-scholar.api-key");
+    const headers = new Headers({ Accept: "application/json" });
+    if (apiKey)
+        headers.set("x-api-key", apiKey);
+    const url = "https://api.semanticscholar.org/graph/v1/paper/search?query=reproducible%20research&limit=1&fields=paperId";
+    try {
+        let response;
+        let retryAfterSeconds = null;
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            response = await input.fetcher(url, {
+                method: "GET",
+                headers,
+                redirect: "manual",
+                signal: AbortSignal.timeout(30_000),
+            });
+            if (response.status !== 429 || attempt === 1)
+                break;
+            retryAfterSeconds = setupRetryAfterSeconds(response.headers.get("retry-after"));
+            await response.body?.cancel().catch(() => undefined);
+            await input.sleeper(Math.min(5, retryAfterSeconds ?? 1) * 1_000);
+        }
+        retryAfterSeconds ??= setupRetryAfterSeconds(response.headers.get("retry-after"));
+        if (response.status >= 300 && response.status < 400) {
+            await response.body?.cancel().catch(() => undefined);
+            checks.push({
+                id: "live.semantic-scholar",
+                category: "live-check",
+                scope: "acquisition",
+                componentIds: ["tiangong.academic-paper-download"],
+                status: "fail",
+                detail: "Semantic Scholar returned a redirect; credential-bearing redirects are not followed.",
+                minimumAction: "Verify the fixed Semantic Scholar endpoint and network policy before relying on that resolver; do not fall back to a standalone evidence wrapper.",
+                blocking: false,
+                componentGate: false,
+                diagnostics: {
+                    code: "PROVIDER_REDIRECT_REJECTED",
+                    executionMode: "setup-doctor",
+                    credentialScope: "adapter",
+                    networkAttempted: true,
+                    httpStatus: response.status,
+                },
+            });
+            return;
+        }
+        if (!response.ok) {
+            const authenticationFailure = response.status === 401 || response.status === 403;
+            const rateLimited = response.status === 429;
+            const detail = authenticationFailure
+                ? ""
+                : await boundedResponseText(response, 2_000, apiKey ? [apiKey] : []);
+            checks.push({
+                id: "live.semantic-scholar",
+                category: "live-check",
+                scope: "acquisition",
+                componentIds: ["tiangong.academic-paper-download"],
+                status: "fail",
+                detail: sanitizeResearchText(`Semantic Scholar live check returned HTTP ${response.status}${detail ? `: ${detail}` : ""}.`, apiKey ? [apiKey] : []),
+                minimumAction: rateLimited
+                    ? `Wait for the provider quota window${retryAfterSeconds === null ? "" : ` (Retry-After ${retryAfterSeconds}s)`}, then rerun this optional resolver diagnostic. Unrelated research remains available and must not downgrade to standalone search.`
+                    : authenticationFailure
+                        ? "Replace or remove the optional Semantic Scholar API key, verify provider entitlement, and rerun setup doctor; do not expose the key in output."
+                        : "Verify Semantic Scholar availability and the fixed API contract before relying on that resolver; do not downgrade the research workflow.",
+                blocking: false,
+                componentGate: false,
+                diagnostics: {
+                    code: authenticationFailure
+                        ? "PROVIDER_AUTHENTICATION_FAILED"
+                        : rateLimited
+                            ? "PROVIDER_RATE_LIMITED"
+                            : "PROVIDER_REQUEST_FAILED",
+                    executionMode: "setup-doctor",
+                    credentialScope: "adapter",
+                    networkAttempted: true,
+                    httpStatus: response.status,
+                    retryAfterSeconds,
+                },
+            });
+            return;
+        }
+        await response.body?.cancel().catch(() => undefined);
+        checks.push({
+            id: "live.semantic-scholar",
+            category: "live-check",
+            scope: "acquisition",
+            componentIds: ["tiangong.academic-paper-download"],
+            status: "pass",
+            detail: apiKey
+                ? "Semantic Scholar accepted the configured optional API key."
+                : "Semantic Scholar public API is reachable without an optional API key.",
+            minimumAction: null,
+            blocking: false,
+            componentGate: false,
+        });
+    }
+    catch (error) {
+        checks.push({
+            id: "live.semantic-scholar",
+            category: "live-check",
+            scope: "acquisition",
+            componentIds: ["tiangong.academic-paper-download"],
+            status: "fail",
+            detail: sanitizeResearchText(error instanceof Error ? error.message : String(error), apiKey ? [apiKey] : []),
+            minimumAction: "Restore provider connectivity before relying on Semantic Scholar; unrelated research remains available and no standalone fallback is authorized.",
+            blocking: false,
+            componentGate: false,
+            diagnostics: {
+                code: "PROVIDER_TRANSPORT_FAILED",
+                executionMode: "setup-doctor",
+                credentialScope: "adapter",
+                networkAttempted: true,
+            },
+        });
+    }
+}
+function setupRetryAfterSeconds(value) {
+    if (!value)
+        return null;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return Math.ceil(seconds);
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp))
+        return null;
+    return Math.max(0, Math.ceil((timestamp - Date.now()) / 1_000));
+}
 async function boundedResponseText(response, maximumBytes, secrets) {
     if (!response.body)
         return "";