@intent-systems/nexus 2026.1.5-3 → 2026.1.5-5

package/dist/commands/status.js

@@ -1,109 +1,184 @@
 import fs from "node:fs";
-import path from "node:path";
+import { resolveIdentitySnapshot } from "../agents/identity-state.js";
+import { getAggregateStats } from "../agents/skill-usage.js";
 import { detectCapabilities } from "../capabilities/detector.js";
-import { listCredentials } from "./credential.js";
-import { resolveStateDir } from "../config/paths.js";
 import { defaultRuntime } from "../runtime.js";
-function readField(pathname, label) {
-    try {
-        const raw = fs.readFileSync(pathname, "utf-8");
-        const regex = new RegExp(`^[-*]?\\s*${label}\\s*:\\s*(.+)$`, "im");
-        const match = raw.match(regex);
-        return match?.[1]?.trim();
-    }
-    catch {
-        return undefined;
-    }
+import { listCredentials } from "./credential.js";
+import { resolveQuestState } from "./quest-state.js";
+const STATUS_BOX_WIDTH = 62;
+const POWER_BOX_WIDTH = 62;
+function clampText(text, width) {
+    if (text.length <= width)
+        return text;
+    return text.slice(0, width);
 }
-function getIdentitySnapshot() {
-    const stateDir = resolveStateDir();
-    const agentId = process.env.NEXUS_AGENT_ID?.trim() || "default";
-    const agentIdentityDir = path.join(stateDir, "agents", agentId, "identity");
-    const userIdentityDir = path.join(stateDir, "user", "identity");
-    const onboardingDir = path.join(stateDir, "nexus", "onboarding");
-    const agentIdentityPath = path.join(agentIdentityDir, "IDENTITY.md");
-    const agentSoulPath = path.join(agentIdentityDir, "SOUL.md");
-    const agentMemoryPath = path.join(agentIdentityDir, "MEMORY.md");
-    const userProfilePath = path.join(userIdentityDir, "PROFILE.md");
-    const bootstrapPath = path.join(onboardingDir, "BOOTSTRAP.md");
-    const hasIdentity = fs.existsSync(agentIdentityPath) && fs.existsSync(userProfilePath);
-    const agentName = readField(agentIdentityPath, "Name");
-    const userName = readField(userProfilePath, "Name");
-    return {
-        agentId,
-        agentName,
-        userName,
-        agentIdentityPath,
-        agentSoulPath,
-        agentMemoryPath,
-        userProfilePath,
-        bootstrapPath,
-        hasIdentity,
-    };
+function centerText(text, width) {
+    const clamped = clampText(text, width);
+    const pad = Math.max(0, width - clamped.length);
+    const left = Math.floor(pad / 2);
+    const right = pad - left;
+    return `${" ".repeat(left)}${clamped}${" ".repeat(right)}`;
+}
+function renderBox(lines, width) {
+    const top = `╔${"═".repeat(width)}╗`;
+    const bottom = `╚${"═".repeat(width)}╝`;
+    const body = lines.map((line) => `║${centerText(line, width)}║`);
+    return [top, ...body, bottom];
 }
+const FALLBACK_BOOTSTRAP_PROMPT = `# BOOTSTRAP.md - Welcome to Nexus
+
+Identity setup is required.
+
+For humans: start a short conversation and share your name, goals, and preferences.
+For agents: write PROFILE.md, IDENTITY.md, SOUL.md, and MEMORY.md as you learn them.
+`;
 function readBootstrapPrompt(pathname) {
     try {
         return fs.readFileSync(pathname, "utf-8");
     }
     catch {
-        return null;
+        return FALLBACK_BOOTSTRAP_PROMPT;
     }
 }
 function formatSuggestions(capabilities) {
     const picks = capabilities.filter((cap) => ["ready", "needs_setup", "needs_install", "broken"].includes(cap.status));
-    const sorted = picks.sort((a, b) => a.status.localeCompare(b.status));
-    return sorted.slice(0, 3).map((cap, idx) => ({
-        id: cap.id,
-        status: cap.status,
-        index: idx + 1,
-    }));
+    const priority = ["broken", "ready", "needs_setup", "needs_install"];
+    const sorted = picks.sort((a, b) => priority.indexOf(a.status) - priority.indexOf(b.status));
+    return sorted.slice(0, 3).map((cap, idx) => {
+        const action = cap.status === "broken"
+            ? "nexus credential list"
+            : `nexus capabilities --status ${cap.status.replace("_", "-")}`;
+        const title = cap.status === "ready"
+            ? `Try ${cap.id} (ready, never used)`
+            : cap.status === "needs_setup"
+                ? `Set up ${cap.id}`
+                : cap.status === "needs_install"
+                    ? `Install ${cap.id}`
+                    : `Fix ${cap.id}`;
+        return {
+            id: cap.id,
+            status: cap.status,
+            index: idx + 1,
+            title,
+            action,
+        };
+    });
 }
 export async function statusCommand(opts, runtime = defaultRuntime) {
-    const identity = getIdentitySnapshot();
+    const identityResolution = resolveIdentitySnapshot();
+    if (!identityResolution.ok) {
+        const payload = {
+            ok: false,
+            error: "multiple_agents",
+            agents: identityResolution.agentOptions,
+        };
+        if (opts.json) {
+            runtime.log(JSON.stringify(payload, null, 2));
+        }
+        else {
+            runtime.error("Multiple agents detected in state/agents.");
+            runtime.error(`Set NEXUS_AGENT_ID to one of: ${identityResolution.agentOptions.join(", ")}`);
+        }
+        runtime.exit(2);
+        return;
+    }
+    const identity = identityResolution.snapshot;
     const bootstrapPrompt = !identity.hasIdentity
         ? readBootstrapPrompt(identity.bootstrapPath)
         : null;
     const showBrief = opts.brief === true;
     const showCredentials = opts.credentials === true || (!opts.capabilities && !showBrief);
     const showCapabilities = opts.capabilities === true || (!opts.credentials && !showBrief);
-    const credentials = showCredentials ? await listCredentials() : null;
-    const capabilitySnapshot = showCapabilities ? detectCapabilities() : null;
-    const suggestions = capabilitySnapshot ? formatSuggestions(capabilitySnapshot.capabilities) : [];
+    const showUsage = opts.usage === true ||
+        (!showBrief && !opts.capabilities && !opts.credentials);
+    const shouldLoadCredentials = showCredentials || !showBrief;
+    const shouldLoadCapabilities = showCapabilities || !showBrief;
+    const credentials = shouldLoadCredentials ? await listCredentials() : null;
+    const capabilitySnapshot = shouldLoadCapabilities
+        ? detectCapabilities()
+        : null;
+    const suggestions = capabilitySnapshot
+        ? formatSuggestions(capabilitySnapshot.capabilities)
+        : [];
+    const usage = showUsage
+        ? await getAggregateStats({ windowDays: 7, limit: 3 })
+        : null;
+    const questState = showBrief
+        ? null
+        : await resolveQuestState({
+            identityConfigured: identity.hasIdentity,
+            capabilities: capabilitySnapshot?.capabilities ?? [],
+            credentials: credentials ?? {
+                version: 1,
+                lastUpdated: "",
+                services: {},
+            },
+            includeSecrets: true,
+        });
+    if (opts.quiet) {
+        runtime.exit(bootstrapPrompt ? 2 : 0);
+        return;
+    }
     if (opts.json) {
         runtime.log(JSON.stringify({
             platform: `${process.platform}/${process.arch}`,
             identity,
-            bootstrap: bootstrapPrompt ? { required: true, prompt: bootstrapPrompt } : undefined,
+            bootstrap: bootstrapPrompt
+                ? { required: true, prompt: bootstrapPrompt }
+                : undefined,
             credentials: credentials ?? undefined,
             capabilities: capabilitySnapshot ?? undefined,
             suggestions,
+            usage: usage ?? undefined,
+            power: questState?.power ?? undefined,
         }, null, 2));
         return;
     }
-    runtime.log(`\nNexus Status (${process.platform}/${process.arch})`);
+    for (const line of renderBox(["Nexus Status", `${process.platform}/${process.arch}`], STATUS_BOX_WIDTH)) {
+        runtime.log(line);
+    }
     if (bootstrapPrompt) {
-        runtime.log("\nBootstrap required (identity missing).");
+        runtime.log("");
+        for (const line of renderBox(["Welcome to Nexus!", "Identity setup required."], STATUS_BOX_WIDTH)) {
+            runtime.log(line);
+        }
         runtime.log(`\nBootstrap prompt (${identity.bootstrapPath}):\n`);
         runtime.log(bootstrapPrompt.trimEnd());
         return;
     }
-    runtime.log("\nIdentity");
+    runtime.log("\n👤 Identity");
     runtime.log(`  User: ${identity.userName ?? "(unknown)"} → ${identity.userProfilePath}`);
     runtime.log(`  Agent: ${identity.agentName ?? "(unknown)"} (${identity.agentId}) → ${identity.agentIdentityPath}`);
     runtime.log(`         → ${identity.agentSoulPath}`);
     runtime.log(`         → ${identity.agentMemoryPath}`);
     if (showCredentials && credentials) {
         const services = Object.entries(credentials.services ?? {});
-        runtime.log(`\nCredentials (${services.length} services)`);
+        const accountCount = services.reduce((sum, [, info]) => sum + (info.accounts?.length ?? 0), 0);
+        runtime.log(`\n🔑 Credentials (${accountCount} configured)`);
+        const statusIcon = {
+            active: "✅",
+            ready: "⭐",
+            broken: "❌",
+        };
         for (const [service, info] of services) {
             const accounts = info.accounts ?? [];
-            const summary = accounts.length > 0 ? `${accounts.length} account(s)` : "no accounts";
-            runtime.log(`  ${service}: ${summary}`);
+            if (accounts.length === 0) {
+                runtime.log(`  ${service}: none`);
+                continue;
+            }
+            runtime.log(`  ${service}`);
+            for (const account of accounts) {
+                const status = account.status ?? "ready";
+                const icon = statusIcon[status] ?? "•";
+                const suffix = account.lastError ? ` - ${account.lastError}` : "";
+                runtime.log(`    ${icon} ${account.id} (${status})${suffix}`);
+            }
         }
+        runtime.log(`  Run 'nexus credential list' for full details`);
     }
     if (showCapabilities && capabilitySnapshot) {
-        runtime.log(`\nCapabilities (${capabilitySnapshot.summary.active}/${capabilitySnapshot.summary.total} active)`);
-        for (const [category, entries] of Object.entries(capabilitySnapshot.registry.categories)) {
+        runtime.log(`\n🎯 Capabilities (${capabilitySnapshot.summary.active}/${capabilitySnapshot.summary.total} active)`);
+        for (const [category, _entries] of Object.entries(capabilitySnapshot.registry.categories)) {
             const categoryCaps = capabilitySnapshot.capabilities.filter((cap) => cap.category === category);
             const activeCount = categoryCaps.filter((cap) => cap.status === "active").length;
             if (categoryCaps.length === 0)
@@ -116,16 +191,59 @@ export async function statusCommand(opts, runtime = defaultRuntime) {
             }
         }
     }
+    if (showUsage && usage) {
+        runtime.log("\n📊 Usage (last 7 days)");
+        const mostUsed = usage.topUsed && usage.topUsed.length > 0
+            ? usage.topUsed
+                .map((item) => `${item.name} (${item.runs})`)
+                .join(", ")
+            : usage.mostUsed
+                ? `${usage.mostUsed.name} (${usage.mostUsed.runs})`
+                : "none";
+        const readyUnused = usage.readyButUnused && usage.readyButUnused.length > 0
+            ? usage.readyButUnused.join(", ")
+            : "none";
+        runtime.log(`  Most used: ${mostUsed}`);
+        runtime.log(`  Ready but unused: ${readyUnused}`);
+    }
     if (suggestions.length > 0) {
-        runtime.log("\nSuggestions");
+        runtime.log("\n🎯 Suggestions");
         for (const suggestion of suggestions) {
-            runtime.log(`  ${suggestion.index}. ${suggestion.id} (${suggestion.status})`);
+            runtime.log(`  ${suggestion.index}. ${suggestion.title}`);
+            runtime.log(`     → ${suggestion.action}`);
+        }
+    }
+    if (questState?.power) {
+        const width = 10;
+        const filled = Math.round((questState.power.percent / 100) * width);
+        const bar = `${"#".repeat(filled)}${"-".repeat(width - filled)}`;
+        const lines = [
+            `Power Level: ${bar} ${questState.power.percent}%`,
+            questState.power.nextQuest
+                ? `Next unlock: ${questState.power.nextQuest.title} (+${questState.power.nextQuest.weight}%)`
+                : "Next unlock: none",
+            "Complete the core path to reach 100%",
+        ];
+        runtime.log("");
+        for (const line of renderBox(lines, POWER_BOX_WIDTH)) {
+            runtime.log(line);
         }
     }
     runtime.log(`\nNext: run 'nexus capabilities' or 'nexus credential list' for details.`);
 }
 export async function getStatusSummary() {
-    const identity = getIdentitySnapshot();
+    const resolution = resolveIdentitySnapshot();
+    if (!resolution.ok) {
+        return {
+            ok: false,
+            platform: `${process.platform}/${process.arch}`,
+            identity: {
+                agentId: "unknown",
+                hasIdentity: false,
+            },
+        };
+    }
+    const identity = resolution.snapshot;
     return {
         ok: true,
         platform: `${process.platform}/${process.arch}`,

package/dist/commands/suggestions.js

@@ -1,5 +1,5 @@
-import { defaultRuntime } from "../runtime.js";
 import { buildUsageSuggestions } from "../infra/usage-suggestions.js";
+import { defaultRuntime } from "../runtime.js";
 function parseKinds(raw) {
     if (!raw)
         return undefined;

package/dist/commands/usage-tracking.js

@@ -0,0 +1,32 @@
+import { fetchUsageTrackingSettings, updateUsageTrackingSettings, } from "../infra/usage-settings.js";
+import { defaultRuntime } from "../runtime.js";
+export async function usageTrackingCommand(opts, runtime = defaultRuntime) {
+    if (opts.enable && opts.disable) {
+        runtime.error("Choose either --enable or --disable.");
+        runtime.exit(1);
+    }
+    const requestedOptOut = opts.disable ? true : opts.enable ? false : null;
+    const result = requestedOptOut === null
+        ? await fetchUsageTrackingSettings()
+        : await updateUsageTrackingSettings(requestedOptOut);
+    if (!result) {
+        runtime.error("Usage tracking settings are unavailable (missing URL or token).");
+        runtime.exit(1);
+    }
+    if (opts.json) {
+        runtime.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (!result.ok) {
+        const errorMessage = result.error === "not_allowed"
+            ? "Usage tracking is required for free accounts."
+            : result.error || "Failed to update usage tracking settings.";
+        runtime.error(errorMessage);
+        runtime.exit(1);
+    }
+    if (!result.canOptOut) {
+        runtime.log("Usage tracking is required for free accounts.");
+        return;
+    }
+    runtime.log(`Usage tracking ${result.optOut ? "disabled" : "enabled"}${result.planName ? ` (${result.planName})` : ""}`);
+}

package/dist/commands/usage-upload.js

@@ -1,5 +1,5 @@
-import { defaultRuntime } from "../runtime.js";
 import { runUsageUpload } from "../infra/usage-upload.js";
+import { defaultRuntime } from "../runtime.js";
 export async function usageUploadCommand(opts, runtime = defaultRuntime) {
     const result = await runUsageUpload({
         limit: opts.limit,
@@ -23,5 +23,10 @@ export async function usageUploadCommand(opts, runtime = defaultRuntime) {
         runtime.log(`  uploaded: ${result.uploaded ?? 0}`);
         return;
     }
+    if (result.status === "disabled") {
+        runtime.log(`\nUsage upload disabled`);
+        runtime.log(`  cleared_outbox: ${result.cleared ?? 0}`);
+        return;
+    }
     runtime.log("\nUsage upload complete");
 }

package/dist/config/defaults.js

@@ -99,9 +99,7 @@ export function applyModelDefaults(cfg) {
     if (Object.keys(existingModels).length === 0)
         return cfg;
     let mutated = false;
-    const nextModels = {
-        ...existingModels,
-    };
+    const nextModels = { ...existingModels };
     for (const [alias, target] of Object.entries(DEFAULT_MODEL_ALIASES)) {
         const entry = nextModels[target];
         if (!entry)

package/dist/config/includes.js

@@ -4,7 +4,7 @@
  * @example
  * ```json5
  * {
- *   "$include": "./base.json5",           // single file
+ *   "$include": "./base.json5",            // single file
  *   "$include": ["./a.json5", "./b.json5"] // merge multiple
  * }
  * ```
@@ -52,7 +52,8 @@ export function deepMerge(target, source) {
     if (isPlainObject(target) && isPlainObject(source)) {
         const result = { ...target };
         for (const key of Object.keys(source)) {
-            result[key] = key in result ? deepMerge(result[key], source[key]) : source[key];
+            result[key] =
+                key in result ? deepMerge(result[key], source[key]) : source[key];
         }
         return result;
     }
@@ -92,14 +93,11 @@ class IncludeProcessor {
     }
     processInclude(obj) {
         const includeValue = obj[INCLUDE_KEY];
-        const otherKeys = Object.keys(obj).filter((k) => k !== INCLUDE_KEY);
+        const otherKeys = Object.keys(obj).filter((key) => key !== INCLUDE_KEY);
         const included = this.resolveInclude(includeValue);
         if (otherKeys.length === 0) {
             return included;
         }
-        if (!isPlainObject(included)) {
-            throw new ConfigIncludeError("Sibling keys require included content to be an object", typeof includeValue === "string" ? includeValue : INCLUDE_KEY);
-        }
         // Merge included content with sibling keys
         const rest = {};
         for (const key of otherKeys) {
@@ -172,7 +170,7 @@ class IncludeProcessor {
 // Public API
 // ============================================================================
 const defaultResolver = {
-    readFile: (p) => fs.readFileSync(p, "utf-8"),
+    readFile: (filePath) => fs.readFileSync(filePath, "utf-8"),
     parseJson: (raw) => JSON5.parse(raw),
 };
 /**

package/dist/config/io.js

@@ -4,10 +4,12 @@ import path from "node:path";
 import JSON5 from "json5";
 import { loadShellEnvFallback, resolveShellEnvFallbackTimeoutMs, shouldEnableShellEnvFallback, } from "../infra/shell-env.js";
 import { applyIdentityDefaults, applyLoggingDefaults, applyMessageDefaults, applyModelDefaults, applySessionDefaults, applyTalkApiKey, } from "./defaults.js";
+import { ConfigIncludeError, resolveConfigIncludes } from "./includes.js";
 import { findLegacyConfigIssues } from "./legacy.js";
-import { CONFIG_PATH_NEXUS, resolveConfigPath, resolveStateDir, } from "./paths.js";
+import { migrateLegacyConfig } from "./legacy-migrate.js";
+import { resolveConfigPath, resolveStateDir } from "./paths.js";
 import { validateConfigObject } from "./validation.js";
-import { NexusSchema } from "./zod-schema.js";
+export { CircularIncludeError, ConfigIncludeError } from "./includes.js";
 const SHELL_ENV_EXPECTED_KEYS = [
     "OPENAI_API_KEY",
     "ANTHROPIC_API_KEY",
@@ -23,6 +25,22 @@ const SHELL_ENV_EXPECTED_KEYS = [
     "NEXUS_GATEWAY_TOKEN",
     "NEXUS_GATEWAY_PASSWORD",
 ];
+function attachChannelAliases(cfg) {
+    const channels = cfg.channels ?? {};
+    const nextChannels = {
+        ...channels,
+        whatsapp: channels.whatsapp ?? cfg.whatsapp,
+        telegram: channels.telegram ?? cfg.telegram,
+        discord: channels.discord ?? cfg.discord,
+        slack: channels.slack ?? cfg.slack,
+        signal: channels.signal ?? cfg.signal,
+        imessage: channels.imessage ?? cfg.imessage,
+    };
+    const hasAny = Object.values(nextChannels).some((value) => value !== undefined);
+    if (!hasAny)
+        return cfg;
+    return { ...cfg, channels: nextChannels };
+}
 function resolveConfigPathForDeps(deps) {
     if (deps.configPath)
         return deps.configPath;
@@ -48,8 +66,9 @@ export function parseConfigJson5(raw, json5 = JSON5) {
 }
 export function createConfigIO(overrides = {}) {
     const deps = normalizeDeps(overrides);
-    const configPath = resolveConfigPathForDeps(deps);
+    const resolveConfigPath = () => resolveConfigPathForDeps(deps);
     function loadConfig() {
+        const configPath = resolveConfigPath();
         try {
             if (!deps.fs.existsSync(configPath)) {
                 if (shouldEnableShellEnvFallback(deps.env)) {
@@ -65,17 +84,33 @@ export function createConfigIO(overrides = {}) {
             }
             const raw = deps.fs.readFileSync(configPath, "utf-8");
             const parsed = deps.json5.parse(raw);
-            if (typeof parsed !== "object" || parsed === null)
+            const resolved = resolveConfigIncludes(parsed, configPath, {
+                readFile: (p) => deps.fs.readFileSync(p, "utf-8"),
+                parseJson: (json) => deps.json5.parse(json),
+            });
+            if (typeof resolved !== "object" || resolved === null)
                 return {};
-            const validated = NexusSchema.safeParse(parsed);
-            if (!validated.success) {
+            const migrated = migrateLegacyConfig(resolved);
+            const candidate = migrated.config ?? resolved;
+            const validated = validateConfigObject(candidate);
+            if (!validated.ok) {
                 deps.logger.error("Invalid config:");
-                for (const iss of validated.error.issues) {
-                    deps.logger.error(`- ${iss.path.join(".")}: ${iss.message}`);
+                for (const iss of validated.issues) {
+                    deps.logger.error(`- ${iss.path}: ${iss.message}`);
                 }
                 return {};
             }
-            const cfg = applyModelDefaults(applySessionDefaults(applyLoggingDefaults(applyMessageDefaults(applyIdentityDefaults(validated.data)))));
+            if (migrated.config && migrated.changes.length > 0) {
+                deps.logger.warn(`Auto-migrated config: ${migrated.changes.join(" ")}`);
+                try {
+                    deps.fs.writeFileSync(configPath, `${JSON.stringify(migrated.config, null, 2)}\n`);
+                }
+                catch (err) {
+                    deps.logger.warn(`Failed to write migrated config: ${String(err)}`);
+                }
+            }
+            const cfg = applyModelDefaults(applySessionDefaults(applyLoggingDefaults(applyMessageDefaults(applyIdentityDefaults(validated.config)))));
+            const normalized = attachChannelAliases(cfg);
             const enabled = shouldEnableShellEnvFallback(deps.env) ||
                 cfg.env?.shellEnv?.enabled === true;
             if (enabled) {
@@ -88,7 +123,7 @@ export function createConfigIO(overrides = {}) {
                         resolveShellEnvFallbackTimeoutMs(deps.env),
                 });
             }
-            return cfg;
+            return normalized;
         }
         catch (err) {
             deps.logger.error(`Failed to read config at ${configPath}`, err);
@@ -96,9 +131,10 @@ export function createConfigIO(overrides = {}) {
         }
     }
     async function readConfigFileSnapshot() {
+        const configPath = resolveConfigPath();
         const exists = deps.fs.existsSync(configPath);
         if (!exists) {
-            const config = applyTalkApiKey(applyModelDefaults(applySessionDefaults(applyMessageDefaults({}))));
+            const config = attachChannelAliases(applyTalkApiKey(applyModelDefaults(applySessionDefaults(applyMessageDefaults({})))));
             const legacyIssues = [];
             return {
                 path: configPath,
@@ -128,8 +164,34 @@ export function createConfigIO(overrides = {}) {
                     legacyIssues: [],
                 };
             }
-            const legacyIssues = findLegacyConfigIssues(parsedRes.parsed);
-            const validated = validateConfigObject(parsedRes.parsed);
+            let resolved;
+            try {
+                resolved = resolveConfigIncludes(parsedRes.parsed, configPath, {
+                    readFile: (p) => deps.fs.readFileSync(p, "utf-8"),
+                    parseJson: (json) => deps.json5.parse(json),
+                });
+            }
+            catch (err) {
+                const message = err instanceof ConfigIncludeError
+                    ? err.message
+                    : `Include resolution failed: ${String(err)}`;
+                return {
+                    path: configPath,
+                    exists: true,
+                    raw,
+                    parsed: parsedRes.parsed,
+                    valid: false,
+                    config: {},
+                    issues: [{ path: "", message }],
+                    legacyIssues: [],
+                };
+            }
+            const migrated = migrateLegacyConfig(resolved);
+            const candidate = migrated.config ?? resolved;
+            const legacyIssues = migrated.config
+                ? []
+                : findLegacyConfigIssues(candidate);
+            const validated = validateConfigObject(candidate);
             if (!validated.ok) {
                 return {
                     path: configPath,
@@ -142,13 +204,22 @@ export function createConfigIO(overrides = {}) {
                     legacyIssues,
                 };
             }
+            if (migrated.config && migrated.changes.length > 0) {
+                deps.logger.warn(`Auto-migrated config: ${migrated.changes.join(" ")}`);
+                try {
+                    deps.fs.writeFileSync(configPath, `${JSON.stringify(migrated.config, null, 2)}\n`);
+                }
+                catch (err) {
+                    deps.logger.warn(`Failed to write migrated config: ${String(err)}`);
+                }
+            }
             return {
                 path: configPath,
                 exists: true,
                 raw,
                 parsed: parsedRes.parsed,
                 valid: true,
-                config: applyTalkApiKey(applyModelDefaults(applySessionDefaults(applyLoggingDefaults(applyMessageDefaults(validated.config))))),
+                config: attachChannelAliases(applyTalkApiKey(applyModelDefaults(applySessionDefaults(applyLoggingDefaults(applyMessageDefaults(validated.config)))))),
                 issues: [],
                 legacyIssues,
             };
@@ -167,6 +238,7 @@ export function createConfigIO(overrides = {}) {
         }
     }
     async function writeConfigFile(cfg) {
+        const configPath = resolveConfigPath();
         await deps.fs.promises.mkdir(path.dirname(configPath), {
             recursive: true,
         });
@@ -176,13 +248,13 @@ export function createConfigIO(overrides = {}) {
         await deps.fs.promises.writeFile(configPath, json, "utf-8");
     }
     return {
-        configPath,
+        configPath: resolveConfigPath(),
         loadConfig,
         readConfigFileSnapshot,
         writeConfigFile,
     };
 }
-const defaultIO = createConfigIO({ configPath: CONFIG_PATH_NEXUS });
+const defaultIO = createConfigIO();
 export const loadConfig = defaultIO.loadConfig;
 export const readConfigFileSnapshot = defaultIO.readConfigFileSnapshot;
 export const writeConfigFile = defaultIO.writeConfigFile;

package/dist/config/legacy.js

@@ -138,7 +138,8 @@ const LEGACY_CONFIG_MIGRATIONS = [
                 if (!match || typeof match !== "object")
                     continue;
                 const matchRecord = match;
-                if (matchRecord.channel === undefined && matchRecord.provider !== undefined) {
+                if (matchRecord.channel === undefined &&
+                    matchRecord.provider !== undefined) {
                     matchRecord.channel = matchRecord.provider;
                     delete matchRecord.provider;
                     touched = true;
@@ -202,7 +203,8 @@ const LEGACY_CONFIG_MIGRATIONS = [
                 if (!match || typeof match !== "object")
                     continue;
                 const matchRecord = match;
-                if (matchRecord.channel === undefined && matchRecord.provider !== undefined) {
+                if (matchRecord.channel === undefined &&
+                    matchRecord.provider !== undefined) {
                     matchRecord.channel = matchRecord.provider;
                     delete matchRecord.provider;
                     touched = true;

package/dist/config/paths.js

@@ -20,6 +20,12 @@ export function resolveStateDir(env = process.env, homedir = os.homedir) {
     const override = env.NEXUS_STATE_DIR?.trim();
     if (override)
         return resolveUserPath(override);
+    const envHome = env.HOME?.trim();
+    if (envHome)
+        return path.join(resolveUserPath(envHome), "nexus", "state");
+    const envProfile = env.USERPROFILE?.trim();
+    if (envProfile)
+        return path.join(resolveUserPath(envProfile), "nexus", "state");
     return path.join(homedir(), "nexus", "state");
 }
 function resolveUserPath(input) {
@@ -54,6 +60,16 @@ export function resolveCredentialsDir(env = process.env, stateDir = resolveState
         return resolveUserPath(override);
     return path.join(stateDir, "credentials");
 }
+/**
+ * Bootstrap prompt path (shared across agents).
+ * Default: $NEXUS_STATE_DIR/agents/BOOTSTRAP.md
+ */
+export function resolveBootstrapPath(env = process.env, stateDir = resolveStateDir(env, os.homedir)) {
+    const override = env.NEXUS_BOOTSTRAP_PATH?.trim();
+    if (override)
+        return resolveUserPath(override);
+    return path.join(stateDir, "agents", "BOOTSTRAP.md");
+}
 const OAUTH_FILENAME = "oauth.json";
 /** @deprecated Use resolveCredentialsDir. */
 export function resolveOAuthDir(env = process.env, stateDir = resolveStateDir(env, os.homedir)) {