Fixed self-hosted provider API key handling (#811)

documentation/compatibility-shims/2026-06-self-hosted-secret-id.md

@@ -0,0 +1,31 @@
+# Self-Hosted Provider Secret ID
+
+- Status: Active
+- Introduced: 2026-06-19
+- Remove after: 2026-12-19
+- Code references:
+  - `app/MindWork AI Studio/Tools/Services/RustService.APIKeys.cs`
+  - `app/MindWork AI Studio/Provider/LLMProvidersExtensions.cs`
+
+## User Impact
+
+Some self-hosted provider API keys were stored under a localized OS keyring namespace. In German installations this could produce entries using `Selbst gehostet`, while the fixed canonical namespace is `Self-hosted`.
+
+Without this shim, affected users may see an invalid or missing API key warning until they manually enter the key again.
+
+## Compatibility Behavior
+
+AI Studio uses `Self-hosted` as the canonical secret namespace. For a limited time, API key reads, writes, and deletes also consider the known German legacy namespace `Selbst gehostet`.
+
+When a legacy entry is found, AI Studio stores the same encrypted API key under the canonical namespace and deletes the legacy entry. If the canonical entry already exists, AI Studio also attempts to delete the known legacy alias.
+
+This applies to LLM provider, embedding provider, and transcription provider API keys, including enterprise configuration plugin namespaces.
+
+## Removal Checklist
+
+- Remove `LEGACY_SELF_HOSTED_SECRET_ID_DE`.
+- Remove `LegacySelfHostedAPIKeys`.
+- Remove legacy lookup, migration, and cleanup calls from API key read, write, and delete paths.
+- Keep `LLMProvidersExtensions.ToSecretId()` and the canonical `Self-hosted` namespace.
+- Update this document's status to `Removed`.
+- Add a changelog entry only if removal is user-visible.

documentation/compatibility-shims/README.md

@@ -0,0 +1,44 @@
+# Compatibility Shims
+
+Compatibility shims are temporary fallback paths that keep older installations, settings, secrets, plugin data, or external integrations working while users move to a newer release.
+
+Use this folder for short-lived compatibility code such as legacy aliases, read-repair logic, temporary import fallbacks, or cleanup paths. Do not use it for permanent settings schema migrations; those belong in `app/MindWork AI Studio/Settings/SettingsMigrations.cs`.
+
+Every compatibility shim must have:
+
+- A Markdown file in this folder.
+- A clear status.
+- An introduced date.
+- A remove-after date.
+- Code references.
+- A short explanation of user impact.
+- The compatibility behavior.
+- A removal checklist.
+- A short code comment near the shim that references the Markdown file and remove-after date.
+
+## Template
+
+```md
+# Short Title
+
+- Status: Active
+- Introduced: YYYY-MM-DD
+- Remove after: YYYY-MM-DD
+- Code references:
+  - path/to/file.cs
+
+## User Impact
+
+Describe who needs this compatibility path and what breaks without it.
+
+## Compatibility Behavior
+
+Describe the temporary fallback, alias, read-repair, or cleanup behavior.
+
+## Removal Checklist
+
+- Remove the temporary constants, fallback branches, aliases, or cleanup paths.
+- Remove or update tests and static checks that mention the shim.
+- Update this document's status to `Removed`.
+- Add a changelog entry if removing the shim is user-visible.
+```