Document catalog profile compatibility

README.md

@@ -33,6 +33,9 @@ boundary and constraints that framework work must preserve.
 
 ## Release Guidance
 
+Consumers preparing for the unreleased `v0.10.0` profile-policy transition
+should read the [v0.10.0 transition guide](docs/releases/v0.10.0.md).
+
 Consumers upgrading from `v0.8.0` to `v0.9.0` should read the
 [v0.9.0 changelog and migration guide](docs/releases/v0.9.0.md).
 

docs/consumers/pkg-promptkit.md

@@ -232,6 +232,29 @@ For programmatic profiles,
 [`OpenAICompatibleProfile`](../../profiles.go) converts ordinary
 OpenAI-compatible settings into a value accepted by `WithProfiles`.
 
+### Choose A Profile Ownership Model
+
+Choose the profile source that matches the application's continuity needs:
+
+- Select `promptkit-openrouter-standard` or `promptkit-openrouter-auto` when
+  the maintained literal name is the desired consumer contract. Their current
+  selections are in the [format reference](../formats.md#built-in-profile-catalog).
+- Select an external catalog profile directly when the application accepts that
+  profile's catalog volatility. The selected external inventories are linked
+  from the [format reference](../formats.md#external-profile-inventories).
+- Define a complete application-owned profile with an explicit backend or
+  endpoint, model, and settings when the application owns those choices.
+
+An application profile that inherits an external base follows later changes to
+that base and fails if the base disappears; it is not a frozen copy. Promptkit
+tests the catalog versions selected in its module graph. Independently advancing
+a catalog dependency can remove an inherited base and produce an untested
+combination. Pinning the resolved module graph preserves the embedded data for
+a build, but cannot preserve provider availability. Running binaries neither
+download catalog updates nor automatically replace withdrawn models. See the
+[release policy](../release.md#catalog-profile-compatibility) for the exact
+cross-version guarantees.
+
 ### Alias A Built-In Profile
 
 Give an application-owned profile ID a built-in base when prompts should select
@@ -250,7 +273,9 @@ Select `weather-light` in a prompt or `RunRequest.ProfileID`; it remains the
 reported selected profile. See the [profile inheritance format
 reference](../formats.md#profile-inheritance) and the
 [`Profile` GoDoc](../../types.go) for exact lookup, merging, and validation
-behavior.
+behavior. If the base is an external profile, apply the volatility guidance
+above when deciding whether to use an application-owned complete definition
+instead.
 
 ### Use The Rakestrawhome Built-In Profile
 

docs/development.md

@@ -34,7 +34,7 @@ Start with:
 | Root public API | The [architecture policy](policy/architecture.md), [consumer guide](consumers/pkg-promptkit.md), [testing policy](policy/testing.md), and existing GoDoc. |
 | Prompt, profile, or schema formats | The [framework format reference](formats.md), owning parser or validator package, and [documentation policy](policy/documentation.md). |
 | Source loading or validation | The [framework format reference](formats.md), [internal source document](internal/sources.md), and owning package tests. |
-| Maintained external catalogs or built-ins | The [internal source document](internal/sources.md), [framework format reference](formats.md), [testing policy](policy/testing.md), both catalog module repositories, and each catalog's release procedure. |
+| Maintained external catalogs or built-ins | The [internal source document](internal/sources.md), [framework format reference](formats.md), [testing policy](policy/testing.md), both catalog module repositories, each catalog's release procedure, and the selected module versions in `go.mod`. |
 | Model-client behavior | The [OpenAI-compatible integration contract](integrations/openai-compatible-chat.md), [internal model-client document](internal/llm.md), and owning package tests. |
 | Internal package implementation | The [architecture policy](policy/architecture.md), [internal component overview](internal/overview.md), and focused internal document listed for that package. |
 | Tests or test fixtures | The [testing policy](policy/testing.md), owning package, and focused internal document listed by the component overview. |

docs/formats.md

@@ -327,7 +327,7 @@ that backend's connection and credential metadata. Profile files do not repeat
 those values. A configured, application fallback, or in-memory profile with
 the same profile ID takes precedence.
 
-Promptkit owns two opt-in profiles. Their following definitions are current
+Promptkit owns two opt-in profiles. The following definitions are current
 selections, not automatic defaults:
 
 | ID | Current definition |
@@ -337,35 +337,22 @@ selections, not automatic defaults:
 
 Select either name through an existing request `profile_id` or prompt
 `default_profile`. Consumers can replace either definition or its inherited
-base through the ordinary profile-source precedence above.
+base through the ordinary profile-source precedence above. The
+[release policy](release.md#catalog-profile-compatibility) defines the
+cross-version guarantee for these names.
 
-| Provider | ID | Backend | Model |
+## External Profile Inventories
-| --- | --- | --- | --- |
+
-| aion-labs | `aion-2` | `openrouter` | `aion-labs/aion-2.0` |
+The external profile inventory is defined by the selected catalog modules, not
-| anthropic | `claude-fable-latest` | `openrouter` | `~anthropic/claude-fable-latest` |
+duplicated here. Browse the exact data selected by this Promptkit version:
-| anthropic | `claude-haiku-latest` | `openrouter` | `~anthropic/claude-haiku-latest` |
+
-| anthropic | `claude-opus-latest` | `openrouter` | `~anthropic/claude-opus-latest` |
+- [OpenRouter catalog v2.20260922.0 profiles](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/tag/v2.20260922.0/catalog/profiles)
-| anthropic | `claude-sonnet-latest` | `openrouter` | `~anthropic/claude-sonnet-latest` |
+- [Rakestrawhome catalog v2.20260922.0 profiles](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/tag/v2.20260922.0/catalog/profiles)
-| deepseek | `deepseek-3-2` | `openrouter` | `deepseek/deepseek-v3.2` |
+
-| deepseek | `deepseek-4-flash` | `openrouter` | `deepseek/deepseek-v4-flash` |
+External profile entries are volatile across catalog releases. The
-| deepseek | `deepseek-4-pro` | `openrouter` | `deepseek/deepseek-v4-pro` |
+[release policy](release.md#catalog-profile-compatibility) owns the precise
-| google | `gemini-2-flash` | `openrouter` | `google/gemini-2.5-flash` |
+compatibility boundary; a selected module version identifies tested local data,
-| google | `gemini-2-flash-lite` | `openrouter` | `google/gemini-2.5-flash-lite` |
+not live provider availability.
-| google | `gemini-2-pro` | `openrouter` | `google/gemini-2.5-pro` |
-| google | `gemini-3-flash-lite` | `openrouter` | `google/gemini-3.1-flash-lite` |
-| google | `gemini-flash-latest` | `openrouter` | `~google/gemini-flash-latest` |
-| google | `gemini-pro-latest` | `openrouter` | `~google/gemini-pro-latest` |
-| google | `gemma-4-31b` | `openrouter` | `google/gemma-4-31b-it:exacto` |
-| google | `rakestrawhome-gemma-4-31b` | `rakestrawhome` | `google/gemma-4-31b-it` |
-| minimax | `minimax-m2` | `openrouter` | `minimax/minimax-m2.5` |
-| minimax | `minimax-m3` | `openrouter` | `minimax/minimax-m3` |
-| mistral | `mistral-large-2512` | `openrouter` | `mistralai/mistral-large-2512` |
-| mistral | `mistral-medium-3-5` | `openrouter` | `mistralai/mistral-medium-3-5` |
-| mistral | `mistral-small-3` | `openrouter` | `mistralai/mistral-small-3.2-24b-instruct` |
-| mistral | `mistral-small-4` | `openrouter` | `mistralai/mistral-small-2603` |
-| nvidia | `nemotron-3-ultra` | `openrouter` | `nvidia/nemotron-3-ultra-550b-a55b` |
-| openai | `gpt-5-mini` | `openrouter` | `openai/gpt-5.4-mini` |
-| openai | `gpt-5-nano` | `openrouter` | `openai/gpt-5.4-nano` |
 
 ## Schemas
 

docs/policy/architecture.md

@@ -30,7 +30,8 @@ The implemented internal components consist of:
 - `internal/filecatalog`, which discovers YAML files and provides source-path
   helpers for filesystem and `fs.FS` consumers;
 - `internal/catalog`, which validates immutable external maintained-catalog
-  assets before they are eligible for engine assembly;
+  assets and their reserved profile namespace before they are eligible for
+  engine assembly;
 - `internal/jsonvalue`, which validates and defensively copies JSON-compatible
   extra-parameter trees;
 - `internal/promptdef`, which loads and validates prompt definitions from
@@ -63,11 +64,11 @@ policy snapshot, wraps the selected built-in or injected model client, and
 supplies bounded admission to the runner. The defaults and renderer depend on
 the domain model. Prompt-definition and profile repositories use the domain
 model, file catalog, and YAML decoder. The catalog adapter validates imported
-immutable maintained data before internal engine assembly supplies it to the profile
+immutable maintained data, including its reserved namespace, before internal
-package. Artifact reading uses the domain
+engine assembly supplies it to the profile package. Artifact reading uses the
-model and application-neutral defaults. Validation uses the domain model, file
+domain model and application-neutral defaults. Validation uses the domain model,
-catalog, and JSON Schema implementation. The model client uses the domain
+file catalog, and JSON Schema implementation. The model client uses the domain
-model, application-neutral defaults, and an injected or standard-library HTTP
+model and application-neutral defaults, and an injected or standard-library HTTP
 client. The use-case runner depends on the narrow interfaces owned by each
 internal component, including backend lookup and run admission.
 

docs/release.md

@@ -16,6 +16,32 @@ changes, and state any action required of consumers.
 Promptkit releases are source-only. The annotated tag message is the release
 note; there is no separate hosted release or binary packaging step.
 
+## Catalog Profile Compatibility
+
+External catalog profile data may be added, removed, renamed, or modified
+without deprecation or advance notice. This exception is limited to profile
+data imported from the maintained catalog modules. It does not weaken ordinary
+compatibility for Promptkit's public Go API, configuration and format semantics,
+runtime behavior, catalog-module APIs, manifest schema, backend definitions, or
+consumer-owned definitions.
+
+Within the catalog versions selected and tested by a Promptkit release, and
+unless a consumer overrides the name or its base, Promptkit keeps the literal
+profile IDs `promptkit-openrouter-standard` and
+`promptkit-openrouter-auto` available. The names do not promise a permanent
+model, backend, routing behavior, settings, cost, output, or upstream
+availability. The [framework format reference](formats.md#built-in-profile-catalog)
+owns their current definitions.
+
+`v0.10.0` is the initial minor release for this compatibility transition.
+Afterward, catalog-only updates and adjustments to the current selections may
+ship in a patch release when all other compatibility obligations remain intact.
+External profile removals can require consumer action; they are not automatic
+migrations.
+
+Catalog adoption and release validation remain local and offline. They do not
+probe provider endpoints, request model lists, or make inference calls.
+
 ## Establish The Candidate
 
 Choose a version that has not been published and export it as
@@ -147,11 +173,12 @@ Inspect the complete message and confirm that it accurately records the
 compatibility impact, public API changes, and required consumer action.
 
 When a release introduces or updates the maintained external catalogs, state
-that it selects two independently versioned data dependencies, preserves the
+the two independently versioned selected data dependencies and any resulting
-public API and configuration, requires no consumer migration, and guarantees
+consumer action. State that external profile additions, removals, renames, and
-only the catalog versions selected and tested by that Promptkit release. Link
+selection changes are covered by the catalog-profile policy, while the ordinary
-to the current architecture and format documentation rather than duplicating
+public API and configuration contracts remain in force. Link to the current
-catalog contracts in the release note.
+format and consumer documentation rather than duplicating catalog inventories
+or contracts in the release note.
 
 ## Create And Inspect The Tag
 

docs/releases/v0.10.0.md

@@ -0,0 +1,33 @@
+# Promptkit v0.10.0 (Unreleased)
+
+This supplemental transition guide describes the planned `v0.10.0` catalog
+profile-policy change. It is not a release record and does not claim that the
+version has been published. The annotated tag, when created, remains the
+authoritative release record.
+
+## Transition Summary
+
+`v0.10.0` adopts independently versioned OpenRouter and Rakestrawhome catalog
+modules whose external profile data can change between catalog releases. It
+also introduces the maintained literal names
+`promptkit-openrouter-standard` and `promptkit-openrouter-auto`.
+
+The maintained names provide continuity only within the catalog versions
+selected and tested by a Promptkit release and when consumers do not override
+the name or its base. Their current selections may change. External catalog
+profile IDs can be removed, renamed, or modified, so an application that
+selects one directly may need to update its configuration when upgrading.
+
+## Consumer Migration
+
+Before upgrading, review every profile ID used by prompts, requests, and
+application-owned inheritance. Choose a maintained name, accept an external
+catalog profile's volatility, or define a complete application-owned profile
+when the application must control its target and settings. An alias that
+inherits from an external base is not a frozen copy.
+
+See the [release policy](../release.md#catalog-profile-compatibility) for the
+compatibility boundary, the [format reference](../formats.md#built-in-profile-catalog)
+for current Promptkit-owned definitions and selected external inventories, and
+the [consumer guide](../consumers/pkg-promptkit.md#choose-a-profile-ownership-model)
+for configuration choices.

docs/roadmap/implementation.md

@@ -217,6 +217,8 @@ external inventory across releases.
 
 ## Stage 6: Publish Durable Policy And Consumer Guidance
 
+**Completed:** 2026-09-22
+
 1. Update `docs/release.md`, the release-policy owner: narrow external-profile
    exception, two-name continuity scope, initial minor transition, and later
    patch eligibility. Replace its blanket catalog-update instruction to claim