PRD: Document manual Keycloak-to-Dex migration

Nobody has claimed this yet.

## Problem Statement

New installations use Dex. Existing clusters keep Keycloak and are deliberately not migrated by an upgrade, as decided in ADR-2026-08-06. Some operators will nonetheless want to move, to drop the Java application and the replicated database that Keycloak requires.

There is nothing to guide them. The migration is not difficult but it is unforgiving: several of its consequences are invisible until someone has already committed to it, and one of them cannot be undone by reverting the configuration.

## Solution

Write a migration guide that states the consequences before the steps, and gives the operator enough to decide whether to proceed at all.

The guide must be honest about what does not survive. Every user's token subject changes, because Dex derives it from its own connector identity and cannot pass an upstream subject through. Applications that key a local account on the subject — Harbor and Gitea — orphan their accounts as a result. Nothing in the migration avoids this; the guide's job is to make it a known cost rather than a surprise, and to describe the cleanup.

It must also cover moving the users themselves, since their Keycloak passwords cannot be carried across. Two routes exist: recreate them in Dex through `apl-api` (#3541) with newly issued credentials, or adopt an external identity provider and let it hold them. It must also state the two separate switches involved: `otomi.issuer: dex` selects the issuer, and `apps.keycloak.enabled: false` turns off Keycloak itself — flipping the issuer does not disable Keycloak on its own, and vice versa (#3537, #3538).

## Acceptance Criteria

1. **GIVEN** the guide, **WHEN** an operator reads it, **THEN** the consequences appear before the procedure, so the decision can be made before any change.
2. **GIVEN** the guide, **WHEN** an operator reads the consequences, **THEN** it states that every user's token subject changes and explains why it cannot be preserved.
3. **GIVEN** the guide, **WHEN** an operator reads about affected applications, **THEN** it names the ones that orphan accounts, describes how the failure appears, and gives the cleanup.
4. **GIVEN** the guide, **WHEN** an operator plans user migration, **THEN** both routes are described with their trade-offs, including that Keycloak passwords cannot be reused.
5. **GIVEN** the guide, **WHEN** an operator reaches the procedure, **THEN** the steps are ordered, each states its expected result, and the verification for each is given.
6. **GIVEN** the guide, **WHEN** an operator wants to check progress, **THEN** it describes how to confirm the issuer changed, that a token carries the expected claims, and that each application accepts the new issuer.
7. **GIVEN** the guide, **WHEN** something fails midway, **THEN** it states what can be reverted by changing configuration back, and what cannot.
8. **GIVEN** the guide, **WHEN** it is published, **THEN** it links the decision records that explain why the migration is manual.

## Testing

- The guide must be followed end to end on a test cluster that starts on Keycloak with users and at least one team, and the result recorded. A migration guide that has not been executed is a draft.
- The verification steps in the guide are themselves the test: each should be run as written and produce the stated result.

## Out of Scope

- Tooling to perform the migration.
- A job to remap subjects in the affected applications. If that is built later the guide should reference it; it is not assumed here.
- Migrating in the other direction.
- Any change to product defaults.

## Further Notes

- The platform administrator password hash is derived at bootstrap and does not follow a later password change. A cluster that has rotated it will need the hash regenerated, and the resulting failure is an unhelpful "invalid credentials" that names neither value.
- Clusters that already federate to an external identity provider have by far the cheapest path, since Keycloak is only brokering for them and the equivalent Dex connector replaces it directly. Worth calling out early so those operators do not read the whole user-migration section.

## Dependencies

Depends on #3538 — the procedure turns on disabling Keycloak, which is not possible until that change lands.

Start with ADR-2026-08-06 and the linked issues #3537, #3538, and #3541 to understand the manual migration constraints and available user-migration paths. Execute the guide end to end on a test cluster starting with Keycloak users and at least one team, recording each verification result. Done means the published guide explains consequences, ordered steps, checks, rollback limits, affected applications, and decision-record links.

Written by the indexing model from the issue text.