# Application Fallback Profiles Status: Selected for implementation. ## Purpose Promptkit will allow a consuming application to supply an embedded fallback profile source below operator-configured profiles and above Promptkit's built-in profile catalog. This gives consumers stable, application-owned profile IDs with useful packaged defaults while preserving the existing ability for an operator to replace those definitions. Promptkit will own the reusable source layer and lookup semantics without owning downstream profile names, model assignments, or application configuration policy. ## Consumer Outcome A consumer such as Weatherreporter can embed profiles named for application workloads or execution tiers, such as `weather-light`, `weather-balanced`, and `weather-deep`. Prompts can select those logical IDs without coupling the application to a particular provider or model. An operator can define the same profile ID in the application's ordinary configured profile source to replace the packaged default. If no operator definition exists, Promptkit resolves the application's embedded definition. If neither source contains the ID, Promptkit retains access to its own built-in profile catalog. ## Scope Promptkit will add one optional `fs.FS`-backed application fallback profile source to engine construction. The intended public surface is: ```go promptkit.WithFallbackProfileFS(profileFS, ".") ``` The source will use the existing profile YAML format, discovery behavior, strict decoding, validation rules, and credential restrictions. The option will accept a non-nil filesystem and nonblank root. Repeating the option will follow Promptkit's same-category convention: the last valid value replaces the earlier fallback source, while an invalid option still fails construction when it is applied. No programmatic fallback-profile option is included. Consumers that need the new precedence relationship can embed YAML assets, while `WithProfiles` continues to serve the distinct highest-precedence in-memory use case. ## Profile Selection And Source Precedence Profile ID selection remains separate from profile definition lookup. An explicit request profile ID continues to take precedence over a prompt's `default_profile`. After an ID has been selected, matching definitions resolve in this order: 1. in-memory profiles supplied through `WithProfiles`; 2. the ordinary configured profile source selected through `WithProfileFile`, `WithProfileFS`, or `Config.ProfileDir`; 3. the application fallback profile source; and 4. Promptkit's embedded built-in profiles. A higher-precedence source falls through only when the requested profile ID is absent. An unreadable, malformed, duplicate, ambiguous, or otherwise invalid matching definition is an error and does not permit lookup in a lower layer. Profiles are selected as complete values; sources do not merge fields or inherit from one another. The fallback source remains lazily read and validated when a requested ID reaches that layer. This feature does not introduce engine-wide eager source validation, and an unrelated malformed asset does not acquire stronger validation guarantees than it has in an ordinary profile source. ## Consistent Engine Behavior The engine will assemble one profile repository with the complete precedence chain. Exact profile inspection, ordinary preparation, prepared execution, and ordinary execution will all use that same repository and therefore observe the same definition for a given profile ID. Exact profile inspection remains side-effect free and does not contact a model provider. Existing public error identities remain applicable to cancellation, profile-not-found and profile-load failures, invalid fallback definitions, credential resolution, and unknown backends. The feature does not add a new fallback-specific public error category. Internally, the root facade will own composition of all profile-source layers. The application fallback is another use of the profile repository's existing error-preserving overlay semantics; it is not a separate profile-loading or validation implementation. ## Compatibility The feature is additive. An engine that does not configure an application fallback source retains its current behavior and profile precedence. Existing uses of `Config.ProfileDir`, `WithProfileFile`, `WithProfileFS`, and `WithProfiles` keep their meanings. The application fallback is deliberately below every existing consumer-configured profile source. An ordinary configured profile therefore continues to override any packaged definition with the same ID. A missing or invalid configured source also retains its current behavior; the new layer does not turn configuration failures into silent fallthrough. ## Ownership Boundaries Promptkit owns: - the additional source layer and its construction option; - deterministic lookup and fallthrough semantics; - use of the existing profile format, validation, and public error mapping; - consistent repository use across inspection, preparation, and execution; and - canonical public, format, consumer, and contributor documentation for the implemented capability. The consuming application owns: - whether to supply a fallback source; - application-specific profile IDs and their domain meaning; - embedded profile contents, backend selections, and model choices; - application configuration discovery and operator override policy; - assignment of profiles to reports or other workloads; and - credential policy and operator-facing error presentation beyond Promptkit's public contract. ## Non-Goals This scope does not add: - downstream-specific profiles to Promptkit's built-in catalog; - profile inheritance, aliases, or field-level merging; - provider failover after a selected profile or generation attempt fails; - automatic endpoint discovery, probing, benchmarking, or tier selection; - application configuration discovery; - eager validation of every profile in every source; - source-provenance fields in profile inspection or preparation results; or - an in-memory companion to `WithFallbackProfileFS`. ## Target End State The feature is complete when a consumer can embed an application fallback profile source through the root facade and rely on the documented four-layer precedence everywhere profiles are resolved. Operator definitions override application defaults, application defaults override Promptkit built-ins, invalid matching definitions never silently fall through, and engines that do not use the new option remain behaviorally compatible. The implemented public option and precedence contract will be owned by GoDoc and the framework format reference. Consumer guidance will show the embedded application-default workflow without making this temporary roadmap a second current-state reference.