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](implementation.md).

## 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](../config.md#selected-overlays). 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](../release.md);
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.