ConfigKit/docs/roadmap/overlays.md

Rename Configuration Profiles to Overlays

Status: approved target, not yet implemented. Execution steps and stage status belong to the implementation plan.

Purpose and release scope

ConfigKit's name "profile" collides with application-owned model, pipeline, and execution profiles. The feature already applies a named configuration overlay; use that name directly instead of requiring consumers to distinguish another kind of profile.

The maintainer has approved a breaking rename for the next minor release, intended as v0.4.0. There will be no backward-compatibility aliases, deprecated fields, dual diagnostic names, or legacy-directory fallback. This roadmap does not authorize publication or changes to downstream repositories.

The baseline is ConfigKit at aead20f, following v0.3.1 and the release-workflow simplification. Current behavior is owned by the selected-overlay contract. This roadmap owns the unimplemented rename; it is not a new current API reference.

Target terminology and public surface

Use configuration overlay in introductory prose and selected overlay or overlay where context is clear. An overlay is the named configuration input; overlaying is also the merge operation. CLI overrides may use that operation without becoming named configuration overlays or changing their CLI provenance.

Current surface	Target surface
Options[T].Profile string	Options[T].Overlay string
<configuration-root>/profiles/<name>.yml	<configuration-root>/overlays/<name>.yml
Source label profiles/<name>.yml	Source label overlays/<name>.yml
LayerProfile, value "profile"	LayerOverlay, value "overlay"
CodeProfileInvalid, profile.invalid	CodeOverlayInvalid, overlay.invalid
CodeProfileMissing, profile.missing	CodeOverlayMissing, overlay.missing
CodeProfileOutsideRoot, profile.outside_root	CodeOverlayOutsideRoot, overlay.outside_root
CodeProfileRepeated, profile.repeated	CodeOverlayRepeated, overlay.repeated
CodeProfileDirective, profile.directive	CodeOverlayDirective, overlay.directive
CodeProfileVersion, profile.version	CodeOverlayVersion, overlay.version
CodeProfileLimitExceeded, profile.limit_exceeded	CodeOverlayLimitExceeded, overlay.limit_exceeded
Maintained example LoadNarratioProfile	LoadNarratioOverlay

Apply these changes to public declarations, engine counterparts, facade forwarding/conversion, diagnostics, source records, origin/history records, and rendered explanations. Messages describing this ConfigKit feature use "overlay". Serialization and output that carry the layer or diagnostic-code strings use the new values. No legacy values are emitted for compatibility.

Not every error during loading currently has a profile.* code: shared options, source, import, and parser classifications remain unchanged. This is not an opportunity to redesign error categories or add new diagnostic guarantees.

Behavior preserved

This is a naming migration, not a new layering model. Preserve the existing contract except for the explicitly renamed surfaces:

• Select at most one overlay by name, not a path or list. Preserve the current ASCII name grammar, case sensitivity, and lack of extension fallback.
• Empty selection and exact lowercase default continue to mean no selection. overlays/default.yml is not implicitly loaded. The sentinel is existing behavior, not a compatibility alias for the old feature name.
• Load the selected mapping after strict base composition and schema-version checks, before CLI overrides and defaults/typed decoding. Preserve existing precedence, replacement rules, explicit null/empty behavior, and error ordering.
• Preserve filesystem-context requirements, canonical containment and duplicate source checks, aggregate limits, directive/version-path rules, and NoSource option validation. Do not strengthen or relax them as part of this rename.
• Preserve source-ID ordering, detached metadata, history, provenance queries, callback lifetime, secret handling, and load independence. Only the named layer, selected-file labels/paths, and corresponding diagnostic terminology change where specified above.
• Keep CLI overrides and strict composition distinct. Do not add overlay stacks, inheritance, discovery, arbitrary file selection, or new merge options.

No backward compatibility

Old Go identifiers are removed rather than retained as aliases. Applications using them must update before they compile against the new minor version.

Selection searches only overlays/<name>.yml. A file present solely in profiles/ does not satisfy selection and produces the corresponding new overlay diagnostic. No automatic rename, migration, or search of both locations is performed. If both directories exist, only the selected path under overlays/ participates in this feature.

Do not introduce a prohibition against a directory named profiles, literal strings containing "profile", or application fields such as model_profile. Ordinary explicit imports retain their existing rules regardless of a file's directory name. Removing legacy selection support does not reserve or ban these names elsewhere.

Internal architecture and maintained examples

The public facade retains root-owned named types and inward-only dependencies. Selected-file acquisition and the existing overlay merge mechanism remain distinct responsibilities within the engine. Internal naming reflects the new terminology without a pipeline or merge-algorithm redesign.

Maintained examples use the new API and selected-file directory. The Narratio example still has an application-owned ModelProfile / model_profile; that concept is deliberately independent of ConfigKit overlay selection.

Documentation and migration contract

Current public comments, configuration documentation, consumer guidance, architecture terminology, and implementation descriptions consistently call the feature an overlay. Accepted ADR decisions and historical release notes retain their historical wording. The extraction inventory preserves literal upstream symbols and revision-specific evidence while distinguishing current ConfigKit implementation names. Historical navigation links may change when their targets move; historical decisions do not change.

Consumer migration consists of updating Go identifiers, moving selected files to overlays/, and updating any handling of the renamed provenance-layer and diagnostic-code strings. Applications own any corresponding CLI flag rename; ConfigKit does not define or modify downstream CLIs.

The future minor-release note must explain those four breaking surfaces. Release preparation and publication remain governed by the release procedure; this roadmap does not create a release candidate or introduce additional gates.

Completion criteria

The rename is complete when all maintained consumers compile against the new API, selection and reporting consistently use the new terminology, the legacy feature surface is absent, and regression coverage confirms unchanged semantics and no directory fallback. Remaining "profile" references must be intentional application data, migration explanation, or historical records, not active ConfigKit feature names.

Tests establish the new selection directory, absence of legacy fallback, and preservation of existing semantics. Existing coverage remains with its owning layer instead of being duplicated across the facade and engine.

After implementation, current contracts own the renamed behavior and this roadmap becomes a completion record for retirement during release preparation.