ConfigKit/docs/roadmap/overlays.md

Rename Configuration Profiles to Overlays

Status: approved target, not yet implemented.

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-profile 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.

Work required from the baseline

Public facade and engine

Update root lifecycle.go, records.go, and package/API comments along with their engine counterparts. Rename selection helpers, variables, and tests that refer to ConfigKit profiles. Preserve root-owned public types and inward-only dependencies; no facade redesign is needed.

The existing internal/engine/overlay.go owns merge mechanics. Keep that role distinct from selected-file acquisition: rename profile.go and its tests to selected_overlay.go and selected_overlay_test.go, with names such as loadSelectedOverlayDocument for acquisition. Do not combine unrelated code merely to resolve the filename collision. Update option validation, directive checks, input loading, and explanation rendering consistently.

Tests and maintained consumer examples

Migrate existing coverage and fixtures rather than duplicating the entire suite. Update assertions for layer/code values, labels, paths, and rendered output; retain all existing semantic assertions under the new terminology.

Add focused regression evidence that selection uses overlays/, never falls back to profiles/, and chooses only overlays/ when both exist. Preserve coverage for empty/default selection, invalid and missing names, root containment, version/directive rules, source budgets, CLI precedence, and provenance/history. Existing public-boundary and consumer tests must continue to pass after their API migration. A source/API review must confirm that old exported names were removed, not hidden behind aliases.

Move the maintained Narratio fixture from profiles/testing.yml to overlays/testing.yml, update the example helper and callers, and keep its application-owned ModelProfile / model_profile unchanged. This distinction is part of the motivation for the rename, not leftover work.

Documentation and consumer migration

Update the canonical configuration heading and inbound links, public Go reference comments, README, architecture policy terminology, development test map, consumer guide, and implemented-component descriptions as applicable. The architecture itself remains unchanged.

Do not globally replace every occurrence of "profile". Preserve immutable historical release notes and accepted ADR decision content. Preserve upstream symbol names and revision-specific evidence in the extraction inventory while updating its descriptions of the current ConfigKit implementation. Historical navigation links may be repaired when headings or files move.

At release preparation, the version-matched minor-release note must explicitly describe the breaking API, directory, provenance-layer, and diagnostic-code changes. Consumer instructions must cover updating Go identifiers, moving selected files to overlays/, and updating any downstream output/diagnostic handling. Applications own any corresponding CLI flag rename; ConfigKit does not define or modify downstream CLIs. Do not create a release note before an actual reviewed release candidate exists.

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.

Validate locally under the testing policy, including affected behavioral tests, examples, documentation links, facade boundaries, formatting, vet, and builds. Publication is a separate task governed by the release procedure; neither CI waiting nor additional release gates are introduced by this roadmap.

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