@hilbras/omninode 2.0.0-alpha.14 → 2.0.0-alpha.16

package/dist/index.d.ts

@@ -1502,6 +1502,10 @@ declare const projectConfigSchema: z.ZodObject<{
     } | undefined;
 }>;
 declare const appConfigSchema: z.ZodObject<{
+    /** Active profile; overlays live under `profiles` (§16). */
+    profile: z.ZodOptional<z.ZodString>;
+    /** Named partial overlays, e.g. development/production/testing. */
+    profiles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     project: z.ZodObject<{
         name: z.ZodString;
         providers: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -1924,6 +1928,8 @@ declare const appConfigSchema: z.ZodObject<{
             required?: boolean | undefined;
         } | undefined;
     };
+    profile?: string | undefined;
+    profiles?: Record<string, unknown> | undefined;
     logging?: {
         level: "info" | "error" | "debug" | "warn";
         format?: "text" | "json" | undefined;
@@ -1997,6 +2003,8 @@ declare const appConfigSchema: z.ZodObject<{
             required?: boolean | undefined;
         } | undefined;
     };
+    profile?: string | undefined;
+    profiles?: Record<string, unknown> | undefined;
     logging?: {
         level: "info" | "error" | "debug" | "warn";
         format?: "text" | "json" | undefined;
@@ -2055,11 +2063,13 @@ interface AppConfig {
     };
 }
 interface LoadConfigOptions {
-    /** Explicit path; otherwise omninode.yaml/yml/json is looked up in the given directory. */
+    /** Explicit path (CLI --config); otherwise the project file is discovered. */
     path?: string;
     directory?: string;
-    /** Environment used for ${VAR} expansion; defaults to process.env. */
+    /** Environment used for ${VAR} expansion and OMNINODE_* overrides; defaults to process.env. */
     env?: Record<string, string | undefined>;
+    /** Profile override (CLI --profile), above environment and file selection. */
+    profile?: string;
 }
 declare function findConfigFile(directory?: string): string | undefined;
 /**
@@ -2068,7 +2078,58 @@ declare function findConfigFile(directory?: string): string | undefined;
  * authentication.
  */
 declare function expandEnvRefs(text: string, env: Record<string, string | undefined>, source?: string): string;
+interface LoadConfigResult {
+    config: AppConfig;
+    sources: ConfigSources;
+}
+/**
+ * Composes configuration from every source with the documented precedence
+ * (roadmap §16): CLI → environment → project file → user file → profile
+ * overlay → defaults.
+ */
+declare function loadConfigDetailed(options?: LoadConfigOptions): LoadConfigResult;
+/** Backwards-compatible wrapper: the composed configuration. */
 declare function loadConfig(options?: LoadConfigOptions): AppConfig;
+/**
+ * Actionable configuration diagnostics (roadmap §16) — the kind of message a
+ * user can act on, rather than a generic schema failure.
+ */
+declare function configDiagnostics(config: AppConfig): string[];
+
+/** Loose input shape: composition happens before strict validation. */
+type AppConfigInput = Record<string, unknown>;
+declare const KNOWN_PROFILES: readonly ["default", "development", "production", "testing"];
+type ProfileName = (typeof KNOWN_PROFILES)[number];
+interface ConfigSources {
+    /** Project-level configuration file, if any. */
+    projectFile?: string;
+    /** User-level configuration file, if any. */
+    userFile?: string;
+    /** Active profile. */
+    profile: string;
+    /** Environment variables that overrode configuration. */
+    envOverrides: string[];
+    /** Values that came from built-in defaults. */
+    defaults: string[];
+}
+/** Default user-level configuration locations, most portable first. */
+declare function userConfigPath(env?: Record<string, string | undefined>): string;
+/** Picks the profile: CLI (applied by the loader) > environment > file > default. */
+declare function resolveProfile(input: {
+    profile?: unknown;
+}, env: Record<string, string | undefined>): string;
+/** Deep-merges configuration overlays (objects merge, scalars/arrays replace). */
+declare function mergeConfig<T>(base: T, overlay: unknown): T;
+/** Environment overrides applied above every file source. */
+declare function applyEnvOverrides(input: AppConfigInput, env: Record<string, string | undefined>): {
+    config: AppConfigInput;
+    applied: string[];
+};
+/** Built-in defaults, applied last. */
+declare function applyDefaults(input: AppConfigInput): {
+    config: AppConfigInput;
+    applied: string[];
+};
 
 /** Template written by `omninode init` (§22, §23). */
 declare function defaultProjectConfigYaml(projectName?: string): string;
@@ -3151,6 +3212,6 @@ declare function migrateProjectStores(directory?: string, options?: {
     checkOnly?: boolean;
 }): Promise<MigrationReport[]>;
 
-declare const OMNINODE_VERSION = "2.0.0-alpha.14";
+declare const OMNINODE_VERSION = "2.0.0-alpha.16";
 
-export { AgentAdapterRegistry, type AgentConfig, type AgentConfigYaml, type AgentDescriptor, AgentError, type AgentInfo, type AgentInputMode, type AgentIntegrationType, AgentRegistry, type AgentStatus, type AgentTaskInput, type AgentTaskOutput, type AgentToNodeMessage, type AggregateOptions, type AggregatedFinding, type AggregatedRecommendation, type AppConfig, type AppConfigYaml, type ArtifactKind, type ArtifactPayload, type AskedQuestion, type AuditAction, type AuditEvent, type AuditSink, type AuditSink as AuditStore, type ChatFn, type ChatMessage, type ChatRequest, type ChatResponse, type ChatRole, type ChatStreamChunk, type ChatUsage, type CollectionDiagnostics, type CombinedMeta, type CombinedReport, type CombinedReportFilter, type Confidence, ConfigError, type ConflictPosition, ConsoleLogSink, type CreateTaskInput, type CwdValidation, DEFAULT_MAX_OUTPUT_BYTES, type DecodeResult, type DefaultChatOptions, type DiscoveryResult, type DocumentState, type Durability, type EnvPolicy, type EnvelopeMeta, type Evidence, type EvidenceInput, type EvidenceKind, type ExecutionRecord, type ExtractionMeta, FileAuditLog, FilePipelineRunStore, FilePlanStore, FileReportStore, FileTaskStore, type Finding, type FindingOrigin, type FindingSeverity, type FindingSource, type HelloResult, HeuristicPlanner, type HttpRequestOptions, type HttpResponse, type IAgent, type IAgentAdapter, type IChatProvider, type IMemoryProvider, type IPipelineExecutor, type IPlanner, type IProvider, type JsonDocument, JsonFileStore, type JsonFileStoreOptions, type LoadConfigOptions, LocalMemoryProvider, type LogFormat, type LogLevel, type LogSink, Logger, type LoggerOptions, MAX_CONTEXT_CHARS, MAX_MESSAGE_BYTES, MAX_REPORT_BYTES, type MemoryCategory, type MemoryContextQuery, type MemoryEntry, MemoryError, type MemoryProviderConfig, type MemoryProviderMetadata, type MemoryQuery, type MemoryScope, MemoryService, type MemoryServiceOptions, LocalMemoryProvider as MemoryStore, type MemoryTaskContext, type MessageEnvelope, type MigrationReport, type Modality, type ModelCapabilities, type ModelFilter, type ModelInfo, ModelPlanner, ModelRegistry, type ModelStatus, type NodeToAgentMessage, OMNINODE_VERSION, OPENAI_COMPATIBLE_TYPES, type OmniHilbrasConnectionResult, OmniHilbrasProvider, OmniNodeError, type OmniNodeErrorCode, type OmniNodeErrorOptions, OpenAICompatibleProvider, PROTOCOL_V2, type PipelineConfigYaml, type PipelineDefinition, PipelineEngine, type PipelineEngineOptions, PipelineError, type PipelineRun, type PipelineRunAttempt, type PipelineRunFilter, type PipelineRunOptions, type PipelineRunStatus, type PipelineRunStore, type PipelineStep, type PipelineStepCondition, type PipelineStepConfigYaml, type PipelineStepKind, type PipelineStepRun, type PipelineRunStore as PipelineStore, type Plan, type PlanFilter, type PlanJsonResult, type PlanRequest, type PlanStep, type PlanStore, type PlanValidationIssue, type PlanValidationResult, type PlannerConfigYaml, PlannerError, ProcessAgent, ProcessAgentAdapter, type Project, type ProjectConfigYaml, ProjectStores, type ProtocolAgentToNodeType, ProtocolDecoder, type ProtocolEnvelope, ProtocolError, type ProtocolMessageType, type ProtocolNodeToAgentType, ProtocolSession, type ProtocolViolation, type ProtocolViolationCode, type ProviderAuthentication, type ProviderCapability, type ProviderConfig, type ProviderConfigYaml, ProviderError, type ProviderErrorKind, type ProviderHealth, type ProviderStatus, type ProviderType, type QuestionPayload, type QuestionResponder, type RememberaConfig, RememberaMemoryProvider, type Report, type ReportArtifact, type ReportConflict, type ReportFilter, type ReportPayload, ReportService, type ReportStore, type ReportValidationIssue, type ReportValidationResult, type RoleConfigYaml, type RoleDefinition, RoleRegistry, type RunPipelineOptions, SCHEMA_VERSION, STORE_FILES, SUPPORTED_PROTOCOL_VERSIONS, type SecretFinding, type SessionIds, TERMINAL_TASK_STATUSES, type Task, type TaskContext, TaskEngine, type TaskEngineOptions, TaskError, type TaskPayload, type TaskResult, type TaskStatus, type TaskStore, type TaskStoreFilter, type WritableLike, agentConfigSchema, aggregateReports, appConfigSchema, authHeaders, buildAgentRegistry, buildChildEnv, buildHello, buildHelloAck, buildPipelineEngine, buildPlanner, buildPlannerContext, buildRoleRegistry, composeTaskText, configureLogger, createAgent, createDefaultChatFn, createMemoryProvider, createProvider, createTaskEngine, decodeMessage, decodeStream, defaultMetadata, defaultProjectConfigYaml, defaultSearch, describeExit, describeSecretFindings, detectConflicts, encodeMessage, envelope, expandEnvRefs, extractMessage, extractReportFromText, findConfigFile, inspectDocument, isNetworkError, isOmniNodeError, isRetryable, isSupportedProtocol, isTimeoutError, keywords, killTree, kindFromStatus, loadConfig, logger, migrateProjectStores, newMessageId, normalizeEvidence, normalizeFinding, parseHello, parsePlanJson, parseRetryAfter, pipelineConfigSchema, pipelineStepConfigSchema, planJsonSchema, plannerConfigSchema, projectConfigSchema, providerConfigSchema, providerHttpError, providerTransportError, readDocument, registryKey, requestJson, requireCompletion, resolveApiKey, resolveEnvPolicy, roleConfigSchema, sanitizeChunk, scanForInlineSecrets, similar, validateEnvelope, validatePlan, validateReport, validateWorkingDirectory, writeFileAtomic };
+export { AgentAdapterRegistry, type AgentConfig, type AgentConfigYaml, type AgentDescriptor, AgentError, type AgentInfo, type AgentInputMode, type AgentIntegrationType, AgentRegistry, type AgentStatus, type AgentTaskInput, type AgentTaskOutput, type AgentToNodeMessage, type AggregateOptions, type AggregatedFinding, type AggregatedRecommendation, type AppConfig, type AppConfigInput, type AppConfigYaml, type ArtifactKind, type ArtifactPayload, type AskedQuestion, type AuditAction, type AuditEvent, type AuditSink, type AuditSink as AuditStore, type ChatFn, type ChatMessage, type ChatRequest, type ChatResponse, type ChatRole, type ChatStreamChunk, type ChatUsage, type CollectionDiagnostics, type CombinedMeta, type CombinedReport, type CombinedReportFilter, type Confidence, ConfigError, type ConfigSources, type ConflictPosition, ConsoleLogSink, type CreateTaskInput, type CwdValidation, DEFAULT_MAX_OUTPUT_BYTES, type DecodeResult, type DefaultChatOptions, type DiscoveryResult, type DocumentState, type Durability, type EnvPolicy, type EnvelopeMeta, type Evidence, type EvidenceInput, type EvidenceKind, type ExecutionRecord, type ExtractionMeta, FileAuditLog, FilePipelineRunStore, FilePlanStore, FileReportStore, FileTaskStore, type Finding, type FindingOrigin, type FindingSeverity, type FindingSource, type HelloResult, HeuristicPlanner, type HttpRequestOptions, type HttpResponse, type IAgent, type IAgentAdapter, type IChatProvider, type IMemoryProvider, type IPipelineExecutor, type IPlanner, type IProvider, type JsonDocument, JsonFileStore, type JsonFileStoreOptions, KNOWN_PROFILES, type LoadConfigOptions, type LoadConfigResult, LocalMemoryProvider, type LogFormat, type LogLevel, type LogSink, Logger, type LoggerOptions, MAX_CONTEXT_CHARS, MAX_MESSAGE_BYTES, MAX_REPORT_BYTES, type MemoryCategory, type MemoryContextQuery, type MemoryEntry, MemoryError, type MemoryProviderConfig, type MemoryProviderMetadata, type MemoryQuery, type MemoryScope, MemoryService, type MemoryServiceOptions, LocalMemoryProvider as MemoryStore, type MemoryTaskContext, type MessageEnvelope, type MigrationReport, type Modality, type ModelCapabilities, type ModelFilter, type ModelInfo, ModelPlanner, ModelRegistry, type ModelStatus, type NodeToAgentMessage, OMNINODE_VERSION, OPENAI_COMPATIBLE_TYPES, type OmniHilbrasConnectionResult, OmniHilbrasProvider, OmniNodeError, type OmniNodeErrorCode, type OmniNodeErrorOptions, OpenAICompatibleProvider, PROTOCOL_V2, type PipelineConfigYaml, type PipelineDefinition, PipelineEngine, type PipelineEngineOptions, PipelineError, type PipelineRun, type PipelineRunAttempt, type PipelineRunFilter, type PipelineRunOptions, type PipelineRunStatus, type PipelineRunStore, type PipelineStep, type PipelineStepCondition, type PipelineStepConfigYaml, type PipelineStepKind, type PipelineStepRun, type PipelineRunStore as PipelineStore, type Plan, type PlanFilter, type PlanJsonResult, type PlanRequest, type PlanStep, type PlanStore, type PlanValidationIssue, type PlanValidationResult, type PlannerConfigYaml, PlannerError, ProcessAgent, ProcessAgentAdapter, type ProfileName, type Project, type ProjectConfigYaml, ProjectStores, type ProtocolAgentToNodeType, ProtocolDecoder, type ProtocolEnvelope, ProtocolError, type ProtocolMessageType, type ProtocolNodeToAgentType, ProtocolSession, type ProtocolViolation, type ProtocolViolationCode, type ProviderAuthentication, type ProviderCapability, type ProviderConfig, type ProviderConfigYaml, ProviderError, type ProviderErrorKind, type ProviderHealth, type ProviderStatus, type ProviderType, type QuestionPayload, type QuestionResponder, type RememberaConfig, RememberaMemoryProvider, type Report, type ReportArtifact, type ReportConflict, type ReportFilter, type ReportPayload, ReportService, type ReportStore, type ReportValidationIssue, type ReportValidationResult, type RoleConfigYaml, type RoleDefinition, RoleRegistry, type RunPipelineOptions, SCHEMA_VERSION, STORE_FILES, SUPPORTED_PROTOCOL_VERSIONS, type SecretFinding, type SessionIds, TERMINAL_TASK_STATUSES, type Task, type TaskContext, TaskEngine, type TaskEngineOptions, TaskError, type TaskPayload, type TaskResult, type TaskStatus, type TaskStore, type TaskStoreFilter, type WritableLike, agentConfigSchema, aggregateReports, appConfigSchema, applyDefaults, applyEnvOverrides, authHeaders, buildAgentRegistry, buildChildEnv, buildHello, buildHelloAck, buildPipelineEngine, buildPlanner, buildPlannerContext, buildRoleRegistry, composeTaskText, configDiagnostics, configureLogger, createAgent, createDefaultChatFn, createMemoryProvider, createProvider, createTaskEngine, decodeMessage, decodeStream, defaultMetadata, defaultProjectConfigYaml, defaultSearch, describeExit, describeSecretFindings, detectConflicts, encodeMessage, envelope, expandEnvRefs, extractMessage, extractReportFromText, findConfigFile, inspectDocument, isNetworkError, isOmniNodeError, isRetryable, isSupportedProtocol, isTimeoutError, keywords, killTree, kindFromStatus, loadConfig, loadConfigDetailed, logger, mergeConfig, migrateProjectStores, newMessageId, normalizeEvidence, normalizeFinding, parseHello, parsePlanJson, parseRetryAfter, pipelineConfigSchema, pipelineStepConfigSchema, planJsonSchema, plannerConfigSchema, projectConfigSchema, providerConfigSchema, providerHttpError, providerTransportError, readDocument, registryKey, requestJson, requireCompletion, resolveApiKey, resolveEnvPolicy, resolveProfile, roleConfigSchema, sanitizeChunk, scanForInlineSecrets, similar, userConfigPath, validateEnvelope, validatePlan, validateReport, validateWorkingDirectory, writeFileAtomic };

package/dist/index.js

@@ -210,6 +210,10 @@ var projectConfigSchema = z.object({
   }).strict().optional()
 }).strict();
 var appConfigSchema = z.object({
+  /** Active profile; overlays live under `profiles` (§16). */
+  profile: z.string().min(1).optional(),
+  /** Named partial overlays, e.g. development/production/testing. */
+  profiles: z.record(z.unknown()).optional(),
   project: projectConfigSchema,
   logging: z.object({
     level: z.enum(["debug", "info", "warn", "error"]),
@@ -250,6 +254,86 @@ ${lines}
 OmniNode never stores credentials in configuration. Replace each value with an environment-variable reference, e.g. api_key_env_var: MY_API_KEY.`;
 }
 
+// src/config/profiles.ts
+import { homedir } from "os";
+import path from "path";
+var KNOWN_PROFILES = ["default", "development", "production", "testing"];
+function userConfigPath(env = process.env) {
+  if (env.OMNINODE_USER_CONFIG) return env.OMNINODE_USER_CONFIG;
+  const home = env.HOME ?? homedir();
+  return path.join(home, ".omninode", "config.yaml");
+}
+function resolveProfile(input, env) {
+  if (env.OMNINODE_PROFILE) return env.OMNINODE_PROFILE;
+  if (typeof input.profile === "string" && input.profile.length > 0) return input.profile;
+  return "default";
+}
+function mergeConfig(base, overlay) {
+  if (!isPlainObject(base) || !isPlainObject(overlay)) {
+    return overlay === void 0 ? base : overlay;
+  }
+  const result = { ...base };
+  for (const [key, value] of Object.entries(overlay)) {
+    const existing = result[key];
+    if (Array.isArray(value)) {
+      result[key] = value;
+    } else if (isPlainObject(value) && isPlainObject(existing)) {
+      result[key] = mergeConfig(existing, value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asObject(value) {
+  return isPlainObject(value) ? value : {};
+}
+function applyEnvOverrides(input, env) {
+  const applied = [];
+  const config = mergeConfig(input, {});
+  if (env.OMNINODE_LOG_LEVEL) {
+    config.logging = { ...asObject(config.logging), level: env.OMNINODE_LOG_LEVEL };
+    applied.push("OMNINODE_LOG_LEVEL");
+  }
+  if (env.OMNINODE_LOG_FORMAT) {
+    config.logging = { ...asObject(config.logging), format: env.OMNINODE_LOG_FORMAT };
+    applied.push("OMNINODE_LOG_FORMAT");
+  }
+  const memoryProvider = env.OMNINODE_MEMORY_PROVIDER;
+  const memoryRequired = env.OMNINODE_MEMORY_REQUIRED;
+  if (memoryProvider || memoryRequired) {
+    const project = asObject(config.project);
+    config.project = {
+      ...project,
+      memory: {
+        ...asObject(project.memory ?? { provider: "local" }),
+        ...memoryProvider ? { provider: memoryProvider } : {},
+        ...memoryRequired ? { required: memoryRequired !== "false" } : {}
+      }
+    };
+    if (memoryProvider) applied.push("OMNINODE_MEMORY_PROVIDER");
+    if (memoryRequired) applied.push("OMNINODE_MEMORY_REQUIRED");
+  }
+  return { config, applied };
+}
+function applyDefaults(input) {
+  const applied = [];
+  const config = mergeConfig(input, {});
+  const logging = asObject(config.logging);
+  if (logging.level === void 0) {
+    config.logging = { ...logging, level: "info" };
+    applied.push("logging.level");
+  }
+  if (logging.format === void 0) {
+    config.logging = { ...asObject(config.logging), format: "text" };
+    applied.push("logging.format");
+  }
+  return { config, applied };
+}
+
 // src/config/loader.ts
 import { existsSync, readFileSync } from "fs";
 import { parse as parseYaml } from "yaml";
@@ -276,38 +360,111 @@ function expandEnvRefs(text, env, source = "config") {
     }
   );
 }
-function loadConfig(options = {}) {
+function loadConfigDetailed(options = {}) {
   const env = options.env ?? process.env;
-  const path = options.path ?? (options.directory ? findConfigFile(options.directory) : findConfigFile());
-  if (!path) {
+  const explicitPath = options.path;
+  let input = {};
+  let projectFile;
+  let userFile;
+  if (!explicitPath) {
+    const candidate = userConfigPath(env);
+    if (existsSync(candidate)) {
+      input = mergeConfig(input, readConfigDocument(candidate, env));
+      userFile = candidate;
+    }
+  }
+  const resolvedProject = explicitPath ?? (options.directory ? findConfigFile(options.directory) : findConfigFile());
+  if (resolvedProject) {
+    input = mergeConfig(input, readConfigDocument(resolvedProject, env));
+    projectFile = resolvedProject;
+  }
+  if (!projectFile && !userFile) {
     throw new ConfigError(
       "CONFIG_NOT_FOUND",
       "No omninode.yaml found. Run `omninode init` to create one, or pass an explicit path."
     );
   }
-  const raw = readFileSync(path, "utf8");
+  const profile = options.profile ?? resolveProfile(input, env);
+  const overlay = input.profiles?.[profile];
+  if (overlay !== void 0) {
+    const { profiles: _drop, ...base } = input;
+    input = mergeConfig(base, overlay);
+  } else if (profile !== "default" && profile !== "") {
+    throw new ConfigError(
+      "CONFIG_INVALID",
+      `Profile "${profile}" is not defined in this configuration (known: ${Object.keys(input.profiles ?? {}).join(", ") || "none"}).`
+    );
+  }
+  const withEnv = applyEnvOverrides(input, env);
+  const withDefaults = applyDefaults(withEnv.config);
+  const parsed = appConfigSchema.safeParse(withDefaults.config);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((issue) => {
+      const location = issue.path.join(".") || "(root)";
+      return `${location}: ${issue.message}`;
+    });
+    throw new ConfigError(
+      "CONFIG_INVALID",
+      `Invalid configuration:
+  ${issues.join("\n  ")}`,
+      { details: { issues } }
+    );
+  }
+  return {
+    config: toAppConfig(parsed.data),
+    sources: {
+      ...projectFile !== void 0 ? { projectFile } : {},
+      ...userFile !== void 0 ? { userFile } : {},
+      profile,
+      envOverrides: withEnv.applied,
+      defaults: withDefaults.applied
+    }
+  };
+}
+function readConfigDocument(path2, optionsEnv) {
+  const raw = readFileSync(path2, "utf8");
   const secretFindings = scanForInlineSecrets(raw);
   if (secretFindings.length > 0) {
-    throw new ConfigError("CONFIG_INVALID", describeSecretFindings(path, secretFindings));
+    throw new ConfigError("CONFIG_INVALID", describeSecretFindings(path2, secretFindings));
   }
-  const expanded = expandEnvRefs(raw, env, path);
-  let data;
+  const expanded = expandEnvRefs(raw, optionsEnv, path2);
   try {
-    data = parseYaml(expanded);
+    return parseYaml(expanded);
   } catch (error) {
-    throw new ConfigError("CONFIG_INVALID", `Failed to parse ${path}.`, { cause: error });
+    throw new ConfigError("CONFIG_INVALID", `Failed to parse ${path2}.`, { cause: error });
   }
-  const parsed = appConfigSchema.safeParse(data);
-  if (!parsed.success) {
-    const issues = parsed.error.issues.map((issue) => {
-      const location = issue.path.length > 0 ? issue.path.join(".") : "(root)";
-      return `${location}: ${issue.message}`;
-    });
-    throw new ConfigError("CONFIG_INVALID", `Invalid configuration in ${path}.`, {
-      details: { issues }
-    });
+}
+function loadConfig(options = {}) {
+  return loadConfigDetailed(options).config;
+}
+function configDiagnostics(config) {
+  const notes = [];
+  for (const provider of config.project.providers) {
+    if (!provider.apiKeyEnvVar && provider.baseUrl.startsWith("https://")) {
+      notes.push(
+        `Provider "${provider.name}": API key reference is missing \u2014 add api_key_env_var: <ENV_VAR> unless this endpoint is intentionally keyless.`
+      );
+    }
+  }
+  for (const agent of config.project.agents) {
+    if (!agent.command && agent.integration !== "custom") {
+      notes.push(`Agent "${agent.name}": no command configured \u2014 the process adapter needs one.`);
+    }
+    if (agent.allowExternalCwd) {
+      notes.push(`Agent "${agent.name}": may run outside the project root (allow_external_cwd).`);
+    }
+  }
+  for (const pipeline of config.project.pipelines) {
+    const ids = new Set(pipeline.steps.map((s) => s.id));
+    for (const step of pipeline.steps) {
+      for (const dep of step.dependsOn ?? []) {
+        if (!ids.has(dep)) {
+          notes.push(`Pipeline "${pipeline.id}": step "${step.id}" depends on unknown step "${dep}".`);
+        }
+      }
+    }
   }
-  return toAppConfig(parsed.data);
+  return notes;
 }
 function toAppConfig(yaml) {
   return {
@@ -1942,15 +2099,15 @@ async function writeFileAtomic(target, contents, durability = "rename") {
     }
   }
 }
-async function inspectDocument(path) {
+async function inspectDocument(path2) {
   let raw;
   try {
-    await stat(path);
+    await stat(path2);
   } catch {
     return { status: "missing" };
   }
   try {
-    raw = await readFile(path, "utf8");
+    raw = await readFile(path2, "utf8");
   } catch (error) {
     return { status: "corrupt", detail: `unreadable: ${error instanceof Error ? error.message : String(error)}` };
   }
@@ -1970,21 +2127,21 @@ async function inspectDocument(path) {
   if (version < SCHEMA_VERSION) return { status: "v1-legacy" };
   return { status: "current", schemaVersion: version, count: doc.items.length };
 }
-async function readDocument(path, onCorrupt, quarantine = true) {
-  const state = await inspectDocument(path);
+async function readDocument(path2, onCorrupt, quarantine = true) {
+  const state = await inspectDocument(path2);
   if (state.status === "missing" || state.status === "empty") return [];
   if (state.status === "future") {
     const error = new Error(
-      `${path} was written by a newer OmniNode (schema v${state.schemaVersion} > v${SCHEMA_VERSION})`
+      `${path2} was written by a newer OmniNode (schema v${state.schemaVersion} > v${SCHEMA_VERSION})`
     );
-    onCorrupt?.(path, error);
+    onCorrupt?.(path2, error);
     return [];
   }
   let raw;
   try {
-    raw = await readFile(path, "utf8");
+    raw = await readFile(path2, "utf8");
   } catch (error) {
-    onCorrupt?.(path, error);
+    onCorrupt?.(path2, error);
     return [];
   }
   try {
@@ -1993,16 +2150,16 @@ async function readDocument(path, onCorrupt, quarantine = true) {
     return parsed.items ?? [];
   } catch (error) {
     if (quarantine) {
-      const quarantinePath = `${path}.corrupt-${Date.now()}`;
+      const quarantinePath = `${path2}.corrupt-${Date.now()}`;
       try {
-        await rename(path, quarantinePath);
+        await rename(path2, quarantinePath);
         logger.child({ component: "persistence" }).warn(
-          `Quarantined unreadable store file ${path} \u2192 ${quarantinePath}`
+          `Quarantined unreadable store file ${path2} \u2192 ${quarantinePath}`
         );
       } catch {
       }
     }
-    onCorrupt?.(path, error);
+    onCorrupt?.(path2, error);
     return [];
   }
 }
@@ -4208,8 +4365,8 @@ var STORE_FILES = [
 async function migrateProjectStores(directory = `${process.cwd()}/.omninode`, options = {}) {
   const reports = [];
   for (const file of STORE_FILES) {
-    const path = `${directory}/${file}`;
-    const state = await inspectDocument(path);
+    const path2 = `${directory}/${file}`;
+    const state = await inspectDocument(path2);
     if (state.status === "missing") {
       reports.push({ file, state: state.status, migrated: false });
       continue;
@@ -4231,9 +4388,9 @@ async function migrateProjectStores(directory = `${process.cwd()}/.omninode`, op
       reports.push({ file, state: state.status, migrated: false, note: state.detail });
       continue;
     }
-    const items = await readDocument(path, void 0, false);
+    const items = await readDocument(path2, void 0, false);
     if (!options.checkOnly) {
-      await writeFileAtomic(path, `${JSON.stringify({ schemaVersion: SCHEMA_VERSION, items }, null, 2)}
+      await writeFileAtomic(path2, `${JSON.stringify({ schemaVersion: SCHEMA_VERSION, items }, null, 2)}
 `);
     }
     const beforeCount = items.length;
@@ -4250,7 +4407,7 @@ async function migrateProjectStores(directory = `${process.cwd()}/.omninode`, op
 }
 
 // src/version.ts
-var OMNINODE_VERSION = "2.0.0-alpha.14";
+var OMNINODE_VERSION = "2.0.0-alpha.16";
 export {
   AgentAdapterRegistry,
   AgentError,
@@ -4265,6 +4422,7 @@ export {
   FileTaskStore,
   HeuristicPlanner,
   JsonFileStore,
+  KNOWN_PROFILES,
   LocalMemoryProvider,
   Logger,
   MAX_CONTEXT_CHARS,
@@ -4302,6 +4460,8 @@ export {
   agentConfigSchema,
   aggregateReports,
   appConfigSchema,
+  applyDefaults,
+  applyEnvOverrides,
   authHeaders,
   buildAgentRegistry,
   buildChildEnv,
@@ -4312,6 +4472,7 @@ export {
   buildPlannerContext,
   buildRoleRegistry,
   composeTaskText,
+  configDiagnostics,
   configureLogger,
   createAgent,
   createDefaultChatFn,
@@ -4342,7 +4503,9 @@ export {
   killTree,
   kindFromStatus,
   loadConfig,
+  loadConfigDetailed,
   logger,
+  mergeConfig,
   migrateProjectStores,
   newMessageId,
   normalizeEvidence,
@@ -4364,10 +4527,12 @@ export {
   requireCompletion,
   resolveApiKey,
   resolveEnvPolicy,
+  resolveProfile,
   roleConfigSchema,
   sanitizeChunk,
   scanForInlineSecrets,
   similar,
+  userConfigPath,
   validateEnvelope,
   validatePlan,
   validateReport,