@akira-tl/forgerelay 1.1.2 → 1.2.0

package/dist/cli/init.js

@@ -4,14 +4,16 @@ import { publicEndpointUrl } from "../mcp/oauth/public-url.js";
 import { expandHomePath } from "../mcp/filesystem/roots.js";
 import { detectLauncherCommandShell, } from "../runtime/shell/command-shell-runtime.js";
 import { seedShellInstructionFiles, shellInstructionFamiliesToSeed, } from "../runtime/instructions/shell-instructions.js";
-import { seedPowerShellSkill, } from "../runtime/instructions/powershell-skill.js";
 import { installManagedLanguageServers, installedManagedLanguageServers, managedLanguageServerOptions, } from "../lsp/runtime/managed-language-servers.js";
-import { generateInstanceId, generateOwnerToken, loadForgeRelayFiles, resolveSubagentsFlag, writeForgeRelayAuth, writeForgeRelayConfig, } from "../runtime/config/user-config.js";
-import { classifyClientFacingBaseUrl, compactPublicBaseUrlConfig, hasInsecureLanBaseUrl, isLoopbackBindAddress, normalizePublicBaseUrlsInput, setupBindAddress, SetupCancelledError, textPrompt, validateHttpsProxyBaseUrls, validateLanClientFacingBaseUrls, validatePort, } from "./setup-support.js";
+import { generateInstanceId, generateOwnerToken, loadForgeRelayFiles, writeForgeRelayAuth, writeForgeRelayConfig, } from "../runtime/config/user-config.js";
+import { generalConfigDefinition } from "../runtime/config/definition/general-config.js";
+import { configSchemaId } from "../runtime/config/definition/schema.js";
+import { classifyClientFacingBaseUrl, compactPublicBaseUrlConfig, hasInsecureLanBaseUrl, isLoopbackBindAddress, normalizePublicBaseUrlsInput, SetupCancelledError, textPrompt, validateHttpsProxyBaseUrls, validateLanClientFacingBaseUrls, validatePort, } from "./setup-support.js";
 import { commandShellCompatibilityWarning, commandShellSetupOptions, customPinnedPreference, defaultCommandShellSetupChoice, followLauncherPreference, pinnedFamilyPreference, preservePinnedPreference, shellFamiliesForCustomSelection, } from "./shell/setup.js";
-export async function runInit({ force, version }) {
+import { applySetupConfig } from "./init/setup-config.js";
+export async function runInit({ force, advanced, version }) {
     const files = loadForgeRelayFiles();
-    if (!force && files.configExists && files.authExists) {
+    if (!force && !advanced && files.configExists && files.authExists) {
         prompts.log.info(`ForgeRelay is already configured at ${files.dir}`);
         prompts.log.info("Run `forgerelay init --force` to update it.");
         return;
@@ -30,13 +32,14 @@ export async function runInit({ force, version }) {
             .map((root) => resolve(expandHomePath(root.trim())))
             .filter(Boolean);
         const defaultPort = String(files.config.port ?? 7676);
-        const portAnswer = await textPrompt({
-            message: `Which local port should ForgeRelay use? Press Enter to use ${defaultPort}`,
-            placeholder: defaultPort,
-            defaultValue: defaultPort,
-            validate: validatePort,
-        });
-        const port = Number(portAnswer);
+        const port = advanced
+            ? Number(await textPrompt({
+                message: `Which local port should ForgeRelay use? Press Enter to use ${defaultPort}`,
+                placeholder: defaultPort,
+                defaultValue: defaultPort,
+                validate: validatePort,
+            }))
+            : Number(defaultPort);
         const existingPublicBaseUrls = Array.isArray(files.config.publicBaseUrl)
             ? files.config.publicBaseUrl
             : files.config.publicBaseUrl ? [files.config.publicBaseUrl] : [];
@@ -74,10 +77,8 @@ export async function runInit({ force, version }) {
         if (prompts.isCancel(selectedMode))
             throw new SetupCancelledError();
         const networkMode = selectedMode;
-        const host = setupBindAddress(networkMode);
-        let publicBaseUrl = null;
+        let publicBaseUrl;
         let clientFacingBaseUrls = [`http://127.0.0.1:${port}`];
-        const trustedProxies = networkMode === "proxy" ? ["loopback"] : undefined;
         if (networkMode === "lan" || networkMode === "proxy") {
             const validateBaseUrls = networkMode === "lan"
                 ? validateLanClientFacingBaseUrls
@@ -120,123 +121,118 @@ export async function runInit({ force, version }) {
             }
             publicBaseUrl = compactPublicBaseUrlConfig(clientFacingBaseUrls);
         }
-        const launcherShell = detectLauncherCommandShell();
-        const selectedShellChoice = await prompts.select({
-            message: "Which command shell should Agent commands and Hooks use?",
-            initialValue: defaultCommandShellSetupChoice(files.config.commandShell),
-            options: commandShellSetupOptions(process.platform, files.config.commandShell, launcherShell),
-        });
-        if (prompts.isCancel(selectedShellChoice))
-            throw new SetupCancelledError();
-        let commandShell;
-        const shellChoice = selectedShellChoice;
-        if (shellChoice === "follow-launcher") {
-            commandShell = followLauncherPreference(files.config.commandShell, launcherShell);
-        }
-        else if (shellChoice === "keep-pinned") {
-            commandShell = preservePinnedPreference(files.config.commandShell);
-        }
-        else if (shellChoice === "custom") {
-            const customFamily = await prompts.select({
-                message: "Which command language does the custom executable implement?",
-                options: shellFamiliesForCustomSelection(),
-            });
-            if (prompts.isCancel(customFamily))
-                throw new SetupCancelledError();
-            const executable = await textPrompt({
-                message: "What is the command-shell executable path?",
-                placeholder: process.platform === "win32" ? "D:\\Portable\\PowerShell\\pwsh.exe" : "/opt/custom/bin/zsh",
-                defaultValue: "",
-                validate: (value) => value?.trim() ? undefined : "Enter an executable path.",
-            });
-            commandShell = customPinnedPreference(customFamily, executable);
-        }
-        else {
-            commandShell = pinnedFamilyPreference(shellChoice);
-        }
-        const shellWarning = commandShellCompatibilityWarning(commandShell.family);
-        if (shellWarning)
-            prompts.note(shellWarning, "Command shell compatibility");
-        const shellInstructionFamilies = shellInstructionFamiliesToSeed(process.platform, commandShell.family);
-        let shellInstructions = files.config.shellInstructions;
+        let advancedSelection;
+        let commandShell = files.config.commandShell;
+        let shellInstructionFamilies = [];
+        let shellInstructions = files.config.shellInstructions ?? false;
         let shellInstructionSeedResults = [];
-        let powerShellSkillSeedResult;
-        if (shellInstructionFamilies.length > 0) {
-            const shellInstructionsAnswer = await prompts.confirm({
-                message: "Load ForgeRelay-provided extra Instructions for this command shell?",
-                initialValue: files.config.shellInstructions !== false,
+        if (advanced) {
+            const launcherShell = detectLauncherCommandShell();
+            const selectedShellChoice = await prompts.select({
+                message: "Which command shell should Agent commands and Hooks use?",
+                initialValue: defaultCommandShellSetupChoice(files.config.commandShell),
+                options: commandShellSetupOptions(process.platform, files.config.commandShell, launcherShell),
             });
-            if (prompts.isCancel(shellInstructionsAnswer))
+            if (prompts.isCancel(selectedShellChoice))
                 throw new SetupCancelledError();
-            shellInstructions = shellInstructionsAnswer === true;
-            shellInstructionSeedResults = await seedShellInstructionFiles({
-                configDir: files.dir,
-                version,
-                families: shellInstructionFamilies,
-            });
-            const failedShellInstructions = shellInstructionSeedResults.filter((result) => result.status === "failed");
-            if (failedShellInstructions.length > 0) {
-                prompts.note(failedShellInstructions.map((result) => `${result.family}: ${result.error ?? "download failed"}\n${result.sourceUrl}`).join("\n\n"), "Shell Instructions unavailable");
+            const shellChoice = selectedShellChoice;
+            if (shellChoice === "follow-launcher") {
+                commandShell = followLauncherPreference(files.config.commandShell, launcherShell);
             }
-        }
-        if (commandShell.family === "pwsh") {
-            powerShellSkillSeedResult = await seedPowerShellSkill({
-                configDir: files.dir,
-                version,
-            });
-            if (powerShellSkillSeedResult.status === "failed") {
-                prompts.note(`${powerShellSkillSeedResult.error ?? "download failed"}\n${powerShellSkillSeedResult.sourceUrl}`, "PowerShell Skill unavailable");
+            else if (shellChoice === "keep-pinned") {
+                commandShell = preservePinnedPreference(files.config.commandShell);
             }
-        }
-        const installedManaged = installedManagedLanguageServers(files.dir);
-        const selectedManaged = await prompts.multiselect({
-            message: "Which Language Servers should ForgeRelay manage with npm?",
-            options: managedLanguageServerOptions(),
-            initialValues: installedManaged,
-            required: false,
-        });
-        if (prompts.isCancel(selectedManaged))
-            throw new SetupCancelledError();
-        const managedIds = selectedManaged;
-        const allowAgentInstallAnswer = await prompts.confirm({
-            message: "Allow Agents to install or update ForgeRelay-managed Language Servers on demand?",
-            initialValue: files.config.allowAgentLanguageServerInstall === true,
-        });
-        if (prompts.isCancel(allowAgentInstallAnswer))
-            throw new SetupCancelledError();
-        const allowAgentLanguageServerInstall = allowAgentInstallAnswer === true;
-        if (managedIds.length > 0) {
-            prompts.note([
-                "ForgeRelay installs these optional Language Servers into its private config directory, not global npm.",
-                "Rust Analyzer, gopls, and clangd remain external toolchain/system installations and are auto-detected when available.",
-            ].join("\n"), "Managed Language Servers");
-            const spinner = prompts.spinner();
-            spinner.start("Installing managed Language Servers with npm");
-            try {
-                const installed = await installManagedLanguageServers(managedIds, files.dir);
-                spinner.stop(`Installed ${installed.installed.join(", ")} under ${installed.root}`);
+            else if (shellChoice === "custom") {
+                const customFamily = await prompts.select({
+                    message: "Which command language does the custom executable implement?",
+                    options: shellFamiliesForCustomSelection(),
+                });
+                if (prompts.isCancel(customFamily))
+                    throw new SetupCancelledError();
+                const executable = await textPrompt({
+                    message: "What is the command-shell executable path?",
+                    placeholder: process.platform === "win32" ? "D:\\Portable\\PowerShell\\pwsh.exe" : "/opt/custom/bin/zsh",
+                    defaultValue: "",
+                    validate: (value) => value?.trim() ? undefined : "Enter an executable path.",
+                });
+                commandShell = customPinnedPreference(customFamily, executable);
             }
-            catch (error) {
-                spinner.stop("Managed Language Server installation failed");
-                throw error;
+            else {
+                commandShell = pinnedFamilyPreference(shellChoice);
             }
+            const shellWarning = commandShellCompatibilityWarning(commandShell.family);
+            if (shellWarning)
+                prompts.note(shellWarning, "Command shell compatibility");
+            shellInstructionFamilies = shellInstructionFamiliesToSeed(process.platform, commandShell.family);
+            if (shellInstructionFamilies.length > 0) {
+                const shellInstructionsAnswer = await prompts.confirm({
+                    message: "Enable ForgeRelay Runtime Shell Instructions for this command shell?",
+                    initialValue: files.config.shellInstructions === true,
+                });
+                if (prompts.isCancel(shellInstructionsAnswer))
+                    throw new SetupCancelledError();
+                shellInstructions = shellInstructionsAnswer === true;
+                if (shellInstructions) {
+                    shellInstructionSeedResults = await seedShellInstructionFiles({
+                        configDir: files.dir,
+                        version,
+                        families: shellInstructionFamilies,
+                    });
+                    const failedShellInstructions = shellInstructionSeedResults.filter((result) => result.status === "failed");
+                    if (failedShellInstructions.length > 0) {
+                        prompts.note(failedShellInstructions.map((result) => `${result.family}: ${result.error ?? "download failed"}\n${result.sourceUrl}`).join("\n\n"), "Shell Instructions unavailable");
+                    }
+                }
+            }
+            const installedManaged = installedManagedLanguageServers(files.dir);
+            const selectedManaged = await prompts.multiselect({
+                message: "Which Language Servers should ForgeRelay manage with npm?",
+                options: managedLanguageServerOptions(),
+                initialValues: installedManaged,
+                required: false,
+            });
+            if (prompts.isCancel(selectedManaged))
+                throw new SetupCancelledError();
+            const managedIds = selectedManaged;
+            const allowAgentInstallAnswer = await prompts.confirm({
+                message: "Allow Agents to install or update ForgeRelay-managed Language Servers on demand?",
+                initialValue: files.config.allowAgentLanguageServerInstall === true,
+            });
+            if (prompts.isCancel(allowAgentInstallAnswer))
+                throw new SetupCancelledError();
+            const allowAgentLanguageServerInstall = allowAgentInstallAnswer === true;
+            if (managedIds.length > 0) {
+                prompts.note([
+                    "ForgeRelay installs these optional Language Servers into its private config directory, not global npm.",
+                    "Rust Analyzer, gopls, and clangd remain external toolchain/system installations and are auto-detected when available.",
+                ].join("\n"), "Managed Language Servers");
+                const spinner = prompts.spinner();
+                spinner.start("Installing managed Language Servers with npm");
+                try {
+                    const installed = await installManagedLanguageServers(managedIds, files.dir);
+                    spinner.stop(`Installed ${installed.installed.join(", ")} under ${installed.root}`);
+                }
+                catch (error) {
+                    spinner.stop("Managed Language Server installation failed");
+                    throw error;
+                }
+            }
+            advancedSelection = {
+                port,
+                commandShell,
+                shellInstructions,
+                allowAgentLanguageServerInstall,
+            };
         }
-        const config = {
-            ...files.config,
-            host,
-            port,
+        const config = applySetupConfig(files.config, {
+            schema: configSchemaId(generalConfigDefinition, "user"),
             allowedRoots,
-            publicBaseUrl,
-            allowedHosts: files.config.allowedHosts,
-            trustedProxies,
-            workflowInstructions: files.config.workflowInstructions,
-            appendInstructions: files.config.appendInstructions,
-            commandShell,
-            shellInstructions,
-            subagents: resolveSubagentsFlag(files.config),
-            languageServers: files.config.languageServers,
-            allowAgentLanguageServerInstall,
-        };
+            network: {
+                mode: networkMode,
+                ...(publicBaseUrl === undefined ? {} : { publicBaseUrl }),
+            },
+            ...(advancedSelection ? { advanced: advancedSelection } : {}),
+        });
         const auth = {
             ...files.auth,
             ownerToken: files.auth.ownerToken ?? generateOwnerToken(),
@@ -244,24 +240,26 @@ export async function runInit({ force, version }) {
         };
         const configPath = writeForgeRelayConfig(config);
         const authPath = await writeForgeRelayAuth(auth);
+        const bindHost = config.host ?? "127.0.0.1";
+        const bindPort = config.port ?? 7676;
         const lines = [
             `Config: ${configPath}`,
             `Auth: ${authPath}`,
-            `Bind: http://${config.host}:${config.port}`,
-            `Command shell: ${commandShell.mode} ${commandShell.family} (${commandShell.executable})`,
-            ...(shellInstructionFamilies.length > 0
+            `Bind: http://${bindHost}:${bindPort}`,
+            "OAuth mode: Owner-password approval",
+            ...(advancedSelection && commandShell
+                ? [`Command shell: ${commandShell.mode} ${commandShell.family} (${commandShell.executable})`]
+                : []),
+            ...(advancedSelection && shellInstructionFamilies.length > 0
                 ? [
                     `Shell Instructions: ${shellInstructions ? "enabled" : "disabled"}`,
                     ...shellInstructionSeedResults.map((result) => `Shell Instructions ${result.family}: ${result.status} (${result.path})`),
                 ]
                 : []),
-            ...(powerShellSkillSeedResult
-                ? [`PowerShell Skill: ${powerShellSkillSeedResult.status} (${powerShellSkillSeedResult.path})`]
-                : []),
             ...clientFacingBaseUrls.map((baseUrl, index) => `${index === 0 ? "Client-facing MCP URL" : "Client-facing MCP alias"}: ${publicEndpointUrl(baseUrl, "mcp").toString()}`),
         ];
         if (networkMode === "ssh") {
-            lines.push(`SSH relay: forgerelay auth -J <ssh-host> 127.0.0.1:${port} --ssh-auth`);
+            lines.push(`SSH relay: forgerelay auth -J <ssh-host> 127.0.0.1:${bindPort} --ssh-auth`);
         }
         prompts.note(lines.join("\n"), "ForgeRelay configured");
         prompts.note([

package/dist/cli/maintenance.js

@@ -8,6 +8,8 @@ import { databasePath } from "../runtime/state/db/client.js";
 import { bashBytesExpression, columnExists, eligibleActivityCte, tableExists, } from "./maintenance-retention.js";
 import { printMaintenancePruneReport, pruneMaintenanceState, } from "./maintenance-prune.js";
 import { forgerelayConfigPath, } from "../runtime/config/user-config.js";
+import { resolveGeneralConfig } from "../runtime/config/resolution/general.js";
+import { assertConfigResolutionValid } from "../runtime/config/resolution/resolver.js";
 const DAY_MS = 24 * 60 * 60 * 1_000;
 const MAX_RETENTION_DAYS = 36_500;
 const MAX_CHECKPOINT_STATE_BYTES = 1024 * 1024;
@@ -44,9 +46,17 @@ export function runMaintenanceCommand(args, env = process.env) {
     printMaintenancePruneReport(report);
 }
 export function inspectMaintenanceState(env = process.env, now = new Date()) {
-    const config = readMaintenanceConfig(env);
-    const stateDir = resolveMaintenanceStateDir(config, env);
-    const policy = resolveMaintenanceRetentionPolicy(config.retention, env);
+    const configPath = forgerelayConfigPath(env);
+    const persistedConfig = readMaintenanceConfig(env);
+    const resolution = resolveGeneralConfig({
+        env,
+        user: persistedConfig,
+        userSourcePath: configPath,
+    });
+    assertConfigResolutionValid(resolution);
+    const config = resolution.values;
+    const stateDir = resolveMaintenanceStateDir(config);
+    const policy = resolveMaintenanceRetentionPolicy(config.retention, {});
     const cutoff = policy.historyDays === null
         ? null
         : new Date(now.getTime() - policy.historyDays * DAY_MS).toISOString();
@@ -113,8 +123,8 @@ function readMaintenanceConfig(env) {
         throw new Error(`Unable to read ForgeRelay maintenance config ${path}: ${errorMessage(error)}`);
     }
 }
-function resolveMaintenanceStateDir(config, env) {
-    const configured = env.FORGERELAY_STATE_DIR ?? config.stateDir ?? join(homedir(), ".local", "share", "forgerelay");
+function resolveMaintenanceStateDir(config) {
+    const configured = config.stateDir ?? join(homedir(), ".local", "share", "forgerelay");
     return resolve(expandHomePath(String(configured)));
 }
 function openReadOnlyDatabaseSnapshot(stateDir) {

package/dist/cli/mcp/external-mcp.js

@@ -77,7 +77,7 @@ async function runExternalMcpList(options, dependencies) {
     if (options.rest.length > 0) {
         throw new Error("Usage: forgerelay mcp list [--project <path>|--global]");
     }
-    const scope = resolveExternalMcpScope(options, dependencies);
+    const scope = await resolveExternalMcpScope(options, dependencies);
     const status = inspectExternalMcpStatus(scope);
     console.log(formatExternalMcpList(status));
     if (status.configIssues > 0) {
@@ -85,7 +85,7 @@ async function runExternalMcpList(options, dependencies) {
     }
 }
 async function runExternalMcpTest(options, dependencies) {
-    const scope = resolveExternalMcpScope(options, dependencies);
+    const scope = await resolveExternalMcpScope(options, dependencies);
     const initialStatus = inspectExternalMcpStatus(scope);
     const serverStatus = findExternalMcpServerStatus(initialStatus, options.server);
     if (!serverStatus)
@@ -99,7 +99,10 @@ async function runExternalMcpTest(options, dependencies) {
     printTestTarget(scope, serverStatus);
     const gateway = new ExternalMcpGateway(scope.config.mediaMaxBytes, scope.store);
     try {
-        const probe = await gateway.probe(scope.snapshot.servers, options.server, undefined, { workspaceRoot: scope.projectRoot, origins: scope.snapshot.origins });
+        const probe = await gateway.probe(scope.snapshot.servers, options.server, undefined, {
+            ...(scope.project ? { project: { id: scope.project.id, projectRoot: scope.project.projectRoot } } : {}),
+            origins: scope.snapshot.origins,
+        });
         console.log("Connection: ok");
         console.log(`Protocol: ${probe.protocolEra}` +
             (probe.protocolVersion ? ` · ${probe.protocolVersion}` : ""));
@@ -148,11 +151,11 @@ function cliArgument(value) {
     return /^[A-Za-z0-9_./:\\-]+$/.test(value) ? value : JSON.stringify(value);
 }
 function formatCredentialScope(source, projectRoot) {
-    return source === "project" ? `project · ${projectRoot}` : "global";
+    return source === "project" || source === "project-local" ? `project · ${projectRoot}` : "global";
 }
 async function runExternalMcpAuth(options, dependencies) {
     assertInteractive(dependencies);
-    const target = resolveExternalMcpCliTarget(options, dependencies);
+    const target = await resolveExternalMcpCliTarget(options, dependencies);
     if (hasStaticAuthorizationHeader(target.serverConfig.headers)) {
         throw new Error(`External MCP ${target.server} uses a static Authorization header; remove that header before using OAuth authentication.`);
     }
@@ -160,7 +163,7 @@ async function runExternalMcpAuth(options, dependencies) {
     console.log(`Source: ${target.source}`);
     console.log(`Transport: ${target.serverConfig.transport}`);
     console.log(`Credential scope: ${formatCredentialScope(target.source, target.projectRoot)}`);
-    const identity = externalMcpCredentialIdentity(target.source, target.server, target.projectRoot);
+    const identity = externalMcpCredentialIdentity(target.source, target.server, target.project);
     const existing = target.store.read(identity);
     const receiver = await (dependencies.createLoopbackReceiver ?? createLoopbackReceiver)(target.serverConfig.oauth?.callbackPort);
     let authorizationUrl;
@@ -224,11 +227,11 @@ async function runExternalMcpAuth(options, dependencies) {
     }
 }
 async function runExternalMcpLogout(options, dependencies) {
-    const target = resolveExternalMcpCliTarget(options, dependencies);
+    const target = await resolveExternalMcpCliTarget(options, dependencies);
     console.log(`Logging out External MCP ${target.server}`);
     console.log(`Source: ${target.source}`);
     console.log(`Credential scope: ${formatCredentialScope(target.source, target.projectRoot)}`);
-    const identity = externalMcpCredentialIdentity(target.source, target.server, target.projectRoot);
+    const identity = externalMcpCredentialIdentity(target.source, target.server, target.project);
     let existing;
     await target.store.withIdentityLock(identity, async () => {
         existing = target.store.read(identity);
@@ -254,8 +257,8 @@ async function runExternalMcpLogout(options, dependencies) {
     else
         console.log("Remote revocation: failed; the local credential was still removed.");
 }
-function resolveExternalMcpCliTarget(options, dependencies) {
-    const scope = resolveExternalMcpScope(options, dependencies);
+async function resolveExternalMcpCliTarget(options, dependencies) {
+    const scope = await resolveExternalMcpScope(options, dependencies);
     const serverConfig = scope.snapshot.servers[options.server];
     const source = scope.snapshot.origins[options.server];
     if (!serverConfig || !source) {
@@ -271,6 +274,7 @@ function resolveExternalMcpCliTarget(options, dependencies) {
     return {
         store: scope.store,
         projectRoot: scope.projectRoot,
+        ...(scope.project ? { project: { id: scope.project.id, projectRoot: scope.project.projectRoot } } : {}),
         server: options.server,
         source,
         serverConfig,

package/dist/cli/mcp/status.js

@@ -1,9 +1,10 @@
 import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { ProjectContextResolver } from "../../workspaces/state/project-context.js";
 import { loadConfig } from "../../runtime/config/config.js";
 import { ExternalMcpCredentialStore, externalMcpCredentialIdentity, } from "../../runtime/config/external-mcp-auth-store.js";
 import { ExternalMcpConfigRegistry, } from "../../runtime/config/external-mcp-registry.js";
-export function resolveExternalMcpScope(request, dependencies = {}) {
+export async function resolveExternalMcpScope(request, dependencies = {}) {
     if (request.global && request.projectRoot) {
         throw new Error("--global and --project cannot be used together.");
     }
@@ -12,7 +13,7 @@ export function resolveExternalMcpScope(request, dependencies = {}) {
     const cwd = resolve(dependencies.cwd ?? process.cwd());
     const registry = new ExternalMcpConfigRegistry({
         configDir: config.configDir,
-        legacyServers: config.mcpServers,
+        sourceRuntime: config.configRuntime.sources,
     });
     const store = new ExternalMcpCredentialStore({ configDir: config.configDir });
     if (request.global) {
@@ -27,13 +28,15 @@ export function resolveExternalMcpScope(request, dependencies = {}) {
         };
     }
     const selected = selectProjectRoot(request.projectRoot, cwd, env);
+    const project = await new ProjectContextResolver(config.configDir).resolve(selected.root);
     return {
         mode: "project",
-        projectRoot: selected.root,
+        projectRoot: project.projectRoot,
+        project,
         projectSelection: selected.selection,
         config,
         registry,
-        snapshot: registry.resolve(selected.root),
+        snapshot: registry.resolve(project),
         store,
     };
 }
@@ -79,7 +82,7 @@ export function formatExternalMcpList(status) {
     }
     lines.push("", "Config:");
     for (const source of status.scope.snapshot.sources) {
-        lines.push(`  ${source.source.padEnd(7)} ${source.path} · ${formatConfigSourceState(source, status)}`);
+        lines.push(`  ${source.source.padEnd(13)} ${source.path} · ${formatConfigSourceState(source, status)}`);
     }
     if (status.credentialStore === "invalid") {
         lines.push(`  auth    ${status.scope.store.filePath} · invalid`);
@@ -111,6 +114,8 @@ export function formatExternalMcpList(status) {
         for (const diagnostic of status.scope.snapshot.diagnostics) {
             const source = status.scope.snapshot.sources.find((candidate) => candidate.source === diagnostic.source);
             lines.push(`  ${diagnostic.source}: ${diagnostic.message}`);
+            if (diagnostic.severity !== "error")
+                continue;
             if (source?.usingLastKnownGood) {
                 lines.push("    Using this process's last-known-good configuration.");
             }
@@ -195,7 +200,7 @@ function serverStatus(scope, name, source, config, credentialStoreInvalid) {
             authState: "not-detected",
         };
     }
-    const identity = externalMcpCredentialIdentity(source, name, scope.projectRoot);
+    const identity = externalMcpCredentialIdentity(source, name, scope.project ? { id: scope.project.id, projectRoot: scope.project.projectRoot } : undefined);
     let record;
     try {
         record = scope.store.read(identity);

package/dist/cli.js

@@ -11,6 +11,8 @@ import * as prompts from "@clack/prompts";
 import { loadConfig } from "./runtime/config/config.js";
 import { acquireRuntimeLease } from "./runtime/state/runtime-lease.js";
 import { runInit } from "./cli/init.js";
+import { runConfigMigration } from "./cli/config/migrate.js";
+import { runConfigInspection } from "./cli/config/inspect.js";
 import { runMaintenanceCommand } from "./cli/maintenance.js";
 import { runExternalMcpCommand } from "./cli/mcp/external-mcp.js";
 import { formatExternalMcpDoctor, inspectExternalMcpStatus, resolveExternalMcpScope, } from "./cli/mcp/status.js";
@@ -47,14 +49,16 @@ async function main(argv) {
             await serve(runtimePrivilege);
             return;
         }
-        case "init":
-            await runInit({ force: args.includes("--force"), version: installedForgeRelayVersion() });
+        case "init": {
+            const initOptions = parseInitCommandArgs(args);
+            await runInit({ ...initOptions, version: installedForgeRelayVersion() });
             return;
+        }
         case "doctor":
             await runDoctor();
             return;
         case "config":
-            runConfigCommand(args);
+            await runConfigCommand(args);
             return;
         case "hooks":
             await runHooksCommand(args);
@@ -90,6 +94,21 @@ function normalizeCommand(command) {
         return "version";
     throw new Error(`Unknown command: ${command}`);
 }
+function parseInitCommandArgs(args) {
+    let force = false;
+    let advanced = false;
+    for (const arg of args) {
+        if (arg === "--force" && !force)
+            force = true;
+        else if (arg === "--advanced" && !advanced)
+            advanced = true;
+        else if (arg === "--force" || arg === "--advanced")
+            throw new Error(`${arg} may only be supplied once.`);
+        else
+            throw new Error(`Unknown init option: ${arg}`);
+    }
+    return { force, advanced };
+}
 function parseServeCommandArgs(args) {
     let allowElevated = false;
     for (const arg of args) {
@@ -123,7 +142,7 @@ async function ensureConfigured() {
             "Or provide FORGERELAY_OAUTH_OWNER_TOKEN and FORGERELAY_ALLOWED_ROOTS.",
         ].join("\n"));
     }
-    await runInit({ force: false, version: installedForgeRelayVersion() });
+    await runInit({ force: false, advanced: false, version: installedForgeRelayVersion() });
 }
 async function serve(runtimePrivilege) {
     const sqliteStatus = checkSqliteNative();
@@ -384,7 +403,7 @@ async function runDoctor() {
         console.log(`Agent-managed Language Server install: ${config.allowAgentLanguageServerInstall ? "enabled" : "disabled"}`);
         console.log(`Allowed roots: ${config.allowedRoots.join(", ")}`);
         console.log(`Allowed hosts: ${config.allowedHosts.join(", ")}`);
-        console.log(formatExternalMcpDoctor(inspectExternalMcpStatus(resolveExternalMcpScope({}, {
+        console.log(formatExternalMcpDoctor(inspectExternalMcpStatus(await resolveExternalMcpScope({}, {
             env: process.env,
             cwd: process.cwd(),
         }))));
@@ -393,8 +412,16 @@ async function runDoctor() {
         console.log(`Config status: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
-function runConfigCommand(args) {
+async function runConfigCommand(args) {
     const [subcommand, key, ...rest] = args;
+    if (subcommand === "migrate") {
+        await runConfigMigration(args.slice(1));
+        return;
+    }
+    if (subcommand === "check" || subcommand === "sources" || subcommand === "explain") {
+        process.exitCode = await runConfigInspection(args);
+        return;
+    }
     const files = loadForgeRelayFiles();
     if (!subcommand || subcommand === "get") {
         console.log(JSON.stringify(files.config, null, 2));
@@ -424,10 +451,16 @@ function printHelp() {
         "  forgerelay serve           Start the server",
         "  forgerelay serve --allow-elevated",
         "                            Explicitly allow this invocation to run with elevated/unknown OS privilege",
-        "  forgerelay init            Create or update ~/.forgerelay/config.json and auth.json",
+        "  forgerelay init            Run minimal first-time setup",
+        "  forgerelay init --advanced Configure common advanced runtime options",
+        "  forgerelay init --force     Update setup-owned fields without migrating legacy config",
         "  forgerelay doctor          Show config, runtime, and native dependency status",
         "  forgerelay config get      Print persisted config",
         "  forgerelay config set publicBaseUrl <url[,url...]|null>",
+        "  forgerelay config check [--global|--project <path>] [--json]",
+        "  forgerelay config sources [--global|--project <path>] [--json]",
+        "  forgerelay config explain <logical-path> [--global|--project <path>] [--json]",
+        "  forgerelay config migrate [--dry-run] [--global|--project <path>]",
         "  forgerelay hooks list [--project <path>]",
         "  forgerelay hooks check [--project <path>]",
         "  forgerelay agents ls       List subagent sessions",