[jbeda]

Summary

Closes #2578. Unify static API-key handling while keeping LLM, search, and MCP credentials in separate auth.yaml namespaces.

• Use search.<id>.api_key and mcp.<id>.api_key; preserve LLM/OAuth formats and provider writes. Allow websearch as a custom LLM ID without sharing its search credential.
• Accept any search/MCP ID matching [a-z0-9_]+. Resolve MECATL_{SEARCH,MCP}_TOKEN_<UPPERCASE_ID> first, then registered search aliases, then the matching file entry. Arbitrary search credentials do not register search backends.
• Retain EXA_API_KEY, BRAVE_API_KEY, and WEBSEARCH_API_KEY as search aliases. Present-empty canonical variables block fallback; empty aliases act as absent.
• Share source-failure policy: reject file fallback on any warning/error; return empty for absent conventional files or keys. Search permits empty credentials; MCP validates required bearer values at the caller. Propagate cached search source errors.
• Centralize naming, aliases, and precedence in the credential source. Preserve startup snapshots for canonical variables, resolution-time aliases, batch snapshots before file acquisition, and settings-driven file selection.

Compatibility

The operator approved a breaking operator configuration/storage schema cleanup: move search keys out of providers into search, and rename MCP's file field from token to api_key. Obsolete forms receive ordinary validation; there are no old-schema lookups or automatic rewrites. Explicitly configured custom LLM IDs remain valid under providers.

API compatibility: no gRPC/HTTP/SDK contract, API major, feature identifier, public Go API, or session-data migration changes. Existing clients remain compatible. Rollback requires restoring the previous credential-file schema. MCP selectors, flag-server token variables, and OAuth field names are unchanged. General secret management (#2585) remains out of scope.

Validation

Passed: task test, task test:race, task lint, task docs, task site:build, and the offline demo (tool call, approval, and result). No live providers exercised.

Regression coverage includes schema validation and preserving writes; namespace isolation; arbitrary IDs; canonical/alias/file precedence; strict source failures; cached/reselected paths; snapshot timing and concurrency; MCP header safety; and search request delivery/non-forwarding. Independent model-provider startup validation remains separate from individual search/MCP lookup policy.

[jbeda]

Approved review decisions

This concise record supersedes the earlier detailed plan archive and incorporates the follow-up review decisions:

• Use a clean credential-file schema break, with ordinary validation rather than migration-specific diagnostics or compatibility code. Keep upgrade instructions in this PR, not current-behavior user guides.
• Generalize search/MCP credential IDs and environment naming; use explicit search aliases and one source-failure policy. Requiredness and format checks belong to consumers.
• Preserve canonical startup snapshots and resolution-time search aliases. Provider batches capture aliases before file acquisition; preliminary discovery must not finalize settings-driven file selection.
• Keep resolution inside the existing credential source, using one environment-lookup callback and no caller-supplied fallback values. Do not expand this into the general secret-management work in Design a shared Mecatl-wide secret-management capability #2585.

The PR description contains the current behavior, compatibility assessment, and validation summary.