feat(identity): reconcile development realm and prove real issuance

.claude/skills/add-ef-migration/SKILL.md

@@ -326,10 +326,15 @@ dotnet ef migrations script \
 # FORCE ROW LEVEL SECURITY exists to defeat. ConnectionStrings:Migration must never
 # appear in API or worker runtime configuration
 # (docs/standards/05-database.md § Database roles).
-dotnet ef database update \
-  --project backend/src/Modules/<Module>/LearnStack.Modules.<Module>.Infrastructure \
-  --startup-project backend/src/LearnStack.Api \
-  --connection "$ConnectionStrings__Migration"
+(
+  migration_cs="$ConnectionStrings__Migration"
+  unset ConnectionStrings__Migration
+  dotnet build backend/src/LearnStack.Api --configuration Release --nologo || exit "$?"
+  ConnectionStrings__Migration="$migration_cs" dotnet ef database update \
+    --project backend/src/Modules/<Module>/LearnStack.Modules.<Module>.Infrastructure \
+    --startup-project backend/src/LearnStack.Api \
+    --configuration Release --no-build
+)
 ```
 
 `ConnectionStrings__Migration` is the environment spelling of

.claude/skills/add-integration-test/SKILL.md

@@ -57,7 +57,7 @@ architecture test) plus any other invariant the change touches. See
 |-------|----------|-------------|
 | Scenario | Yes | A short name + setup + act + assert. |
 | Seed | Yes | Minimum tenants / orgs / users / customization data the scenario needs. |
-| Required containers | Yes | **Postgres, always and only.** Not Valkey, not Kafka — nothing the backend runs calls them. Meilisearch / LiveKit / SeaweedFS only for a provider-contract test, and only from the phase that ships the adapter. |
+| Required containers | Yes | PostgreSQL for application data; pinned Keycloak with its separate PostgreSQL for actual identity-provider proofs. Other providers require a shipping adapter consumer under ADR-0035. |
 | Tenant context | Yes | Which tenant + org the act phase runs as. |
 
 ## Workflow
@@ -85,9 +85,29 @@ architecture test) plus any other invariant the change touches. See
 > Anything touching either carries `[Trait(RequiresDocker.Key, RequiresDocker.Value)]`,
 > which is how CI routes it to `backend-integration` rather than `backend`.
 
-What the fixtures do today:
-
-- Spin **Postgres only** via Testcontainers. Not Valkey, not Kafka — nothing the
+**P02b-6 provider fixture.** Real issuance uses
+[`TenancyIdentity/KeycloakFixture`](../../../backend/tests/LearnStack.Tests.Integration/TenancyIdentity/KeycloakFixture.cs)
+with pinned Keycloak and its own PostgreSQL database. Share read-only provider
+state through `SharedKeycloakRealm`; mutating classes and variants own separate
+providers and restore case-owned changes before returning.
+Its generated CA is trusted only by the fixture's HTTPS clients, with normal
+hostname validation and a wrong-root refusal control. Never install a fixture CA
+in the host trust store or bypass TLS/cookie rules to get a passing login.
+Use real code/S256 authentication, keep credentials/tokens out of assertions and
+logs, and never follow the unimplemented BFF callback to claim session coverage.
+This fixture does not replace application-role isolation proofs. Every consuming
+test class has the Docker trait, including classes outside `Database/`.
+Real-token API qualification uses the separate nonparallel
+`TenantRealmApiTestGroup`, combining this provider with `PublicReadFixture` while
+retaining the existing physical read-only/application-role observer. Do not add
+an application database to the provider-only collection. Profile protection uses
+a separate class fixture, with serialized cases and owned restoration. Do not
+mutate the shared read-only provider. No fixture-only grant or mapper may supply
+a delivered self-service baseline that the committed import/reconciler lacks.
+
+What the database fixtures do today:
+
+- Spin **Postgres** via Testcontainers. Not Valkey, not Kafka — nothing the
   backend runs today calls either, and both sit behind the `gated` compose profile
   per [ADR-0035](../../../docs/decisions/0035-demand-gated-infrastructure.md).
 - Provision the **four database roles** by running the same script the compose

.claude/skills/local-dev-setup/SKILL.md

@@ -54,7 +54,7 @@ the backend runs today calls them, so `make dev` starts 7 services and
 | OpenSSL CLI | Yes for frontend tests | Isolated TLS fixtures generate temporary certificates without installing trust. |
 | Node >=22.23.1 + pnpm | Yes | For the frontend; `frontend/package.json` sets the floor and CI pins `22.23.1`. |
 | Deployment mode | Yes | `Development` (default) / `SaaS` / `Dedicated` / `SelfHostedOnline` / `SelfHostedAirGapped` (per [Standards 12 § Deployment Modes](../../../docs/standards/12-infrastructure.md)). |
-| `.env` (gitignored) | Optional | Local overrides; `.env.example` is the source of truth. |
+| Selected private `.env` (gitignored) | Yes before stack startup | `.env.example` is the template; preserve existing secrets and private file permissions. |
 
 ## Workflow
 
@@ -81,13 +81,21 @@ If any of these is missing, install:
 git clone <repo> learnstack
 cd learnstack
 
-cp .env.example .env       # creates the local-only file (gitignored)
-# Edit .env to override any defaults; for first-run, leave as-is.
+make .env                 # creates a missing local-only file with private permissions
+# Before make dev, prepare KEYCLOAK_WEB_CLIENT_SECRET in that private file.
 
 (cd backend && dotnet restore LearnStack.slnx --locked-mode)
 (cd frontend && pnpm install --frozen-lockfile)
 ```
 
+Never overwrite an existing private source or regenerate its BFF secret on a
+routine rerun. For a legacy source, first verify it is your regular, nonsymlink,
+single-link file, then explicitly set `chmod 600 .env` and add a missing key.
+The tool refuses shared permissions; Makefile creation does not repair them.
+Follow [secret continuity and recovery](../../../infra/keycloak/README.md#secret-continuity-and-recovery)
+if the selected source disagrees with an existing confidential client. Keep its
+contents out of tool output, command arguments and committed files.
+
 ### Step 3: Bring up the stack
 
 ```bash
@@ -178,12 +186,15 @@ Three properties of that inventory matter while you are setting up:
   loopback HTTP through `make public-api` (5080), and the native web listener runs
   on loopback HTTPS through `make public-web` (3000).
 
-To read the resolved truth rather than any document, ask the stack:
+To inspect selected services without printing resolved credentials, ask the stack:
 
 ```bash
-docker compose --env-file .env -f infra/compose/dev.yml config --format json
+docker compose --env-file .env -f infra/compose/dev.yml config --services
 ```
 
+Do not publish complete resolved Compose configuration: it contains private
+environment values.
+
 ### Step 4: First-run bootstrap
 
 `make seed` starts the selected stack, waits for PostgreSQL before migrations,
@@ -283,7 +294,9 @@ make public-api
 | `Bind for 127.0.0.1:5432 failed: port is already allocated` | Stop your local Postgres, or stop the other compose project holding the port — host ports are fixed in `dev.yml`, so two projects cannot both bind them. |
 | `relation "tenants" does not exist` | The owning Tenancy migrations have not landed or were not applied; check the active phase plan before adding an ad-hoc target. |
 | `unable to read app.tenant_id` | The `DbCommandInterceptor` tenant-context guard is unwired, or `TransactionBehavior` did not issue the `SET LOCAL` pair. It is deliberately **not** a connection-checkout interceptor — checkout precedes `BEGIN`. |
-| Keycloak realm not found | Recreate local data with destructive `make clean`, then `make seed`. The realms are imported at compose boot from `infra/keycloak/realms/`, not by the seeder. |
+| Keycloak realm not found | Verify the selected project, private source and Keycloak health/import. Fresh realms import on provider startup; a populated realm needs the shared bounded reconciliation from `make seed`. Follow the [realm guide](../../../infra/keycloak/README.md#fresh-import-and-warm-upgrade); do not wipe data as upgrade recovery. |
+| `missing_web_secret` / `secret_conflict` | Follow [secret continuity and recovery](../../../infra/keycloak/README.md#secret-continuity-and-recovery); preserve the confidential client and existing accounts. |
+| `lock_busy` | Follow [lock recovery](../../../infra/keycloak/README.md#lock-recovery); never delete a lock solely because it is old. |
 | A non-Development mode fails startup | Check that mode's required Sentry/telemetry configuration and [current readiness](../../../docs/architecture/25-deployment-models.md#supported-today-versus-prepared-seam). Every mode currently uses `NullEntitlementProvider`; starting Hub does not supply the Phase 02c adapter. |
 | LiveKit join fails with TURN error | coturn not reachable from the browser; check firewall + container network. |
 

.claude/skills/run-tests-locally/SKILL.md

@@ -35,7 +35,7 @@ flags, and a triage map for the most common failure shapes.
 |-------|----------|-------------|
 | Suite | Yes | `unit` / `integration` / `architecture` / `contract` / `frontend` / `public-demo` (P02d-7). Phase 06 owns the broader Playwright Test/axe suite. |
 | Filter | No | `--filter <expr>` to run a subset. |
-| Docker available? | Integration (`Requires=Docker`) | A running daemon. Postgres only — no Valkey, no Kafka. |
+| Docker available? | Integration (`Requires=Docker`) | A running daemon for PostgreSQL and the pinned Keycloak/PostgreSQL provider fixture. Other adapters retain their named triggers. |
 
 ## Workflow
 
@@ -55,7 +55,7 @@ pnpm --version
 (cd backend && dotnet restore LearnStack.slnx)
 (cd frontend && pnpm install --frozen-lockfile)
 
-# Docker must be running for the integration suite's Database/ cases
+# Docker must be running for Database/ and TenancyIdentity/ provider cases
 docker info >/dev/null && echo "docker OK"
 ```
 
@@ -66,8 +66,8 @@ backend/tests/
   LearnStack.Tests.Unit/           # No DB, no Docker. Pure unit tests.
   LearnStack.Tests.Architecture/   # Reflection + Roslyn + migration-scan rules.
   LearnStack.Tests.Integration/    # WebApplicationFactory HTTP tests (no Docker) AND the
-                                   # Testcontainers Postgres suite under Database/ (as
-                                   # learnstack_app), split by [Trait("Requires","Docker")].
+                                   # Postgres (learnstack_app) and TenancyIdentity/
+                                   # Keycloak/Postgres, split by [Trait("Requires","Docker")].
   LearnStack.Tests.Contract/       # OpenAPI / SDK contract assertions.
 
 frontend/apps/web/                 # Guarded Vitest unit/component/control suites.
@@ -118,15 +118,16 @@ before concluding a net is under you.
 | `MediatR_Pipeline_Order_Matches_Canonical_Sequence` | A behavior moved; the eight-step order is fixed by [ADR-0032](../../../docs/decisions/0032-exception-handling-logging-and-observability.md). |
 | `Integration_Event_TopicNames_FollowConvention` | Topic isn't `learnstack.{module}.{aggregate}`. |
 | `No_Source_Folder_Named_Verticals` | A `Verticals/` folder exists; ADR-0018 forbids it. |
-| `Every_Database_Test_Carries_The_Docker_Trait` | A test class under `Database/`, or one anywhere that takes a database fixture, is missing `[Trait(RequiresDocker.Key, RequiresDocker.Value)]` and would run in the wrong CI job. |
+| `Every_Database_Test_Carries_The_Docker_Trait` | A test class under `Database/`, or one anywhere referencing a database/Keycloak fixture or collection, is missing `[Trait(RequiresDocker.Key, RequiresDocker.Value)]` and would run in the wrong CI job. |
 | `Migrate_Target_Covers_Every_Migration_Chain` | A new chain exists that `make migrate` does not apply. |
 
 ### Step 5: Run integration tests
 
-The assembly holds two kinds. The `WebApplicationFactory` HTTP tests need no
-Docker; everything under `Database/` does, and **a running Docker daemon is
-required** for it — Postgres only, no Valkey and no Kafka, because nothing the
-backend runs calls either
+The assembly holds Docker-free HTTP/offline tests and Docker-backed proofs.
+Everything under `Database/` requires PostgreSQL; `TenancyIdentity/` also includes
+the pinned Keycloak fixture with its separate PostgreSQL database. **A running
+Docker daemon is required** for both provider populations. Neither needs Valkey
+or Kafka, because nothing the backend runs calls either
 ([ADR-0035](../../../docs/decisions/0035-demand-gated-infrastructure.md)). The two
 are split by `[Trait("Requires","Docker")]`; CI further partitions Docker tests
 into native/ordinary execution jobs behind the required integration aggregate. Locally

.claude/skills/seed-tenant/SKILL.md

@@ -6,7 +6,7 @@ description: >
   fixtures and data-only showcases. P02d-2 includes enabled locales, built-in and
   tenant-specific definitions, complete branding and scoped Course/Lesson content.
   DO NOT USE FOR: production provisioning, production reseeding, Hub licensing,
-  identity setup or domain-specific application branches.
+  production identity provisioning or domain-specific application branches.
 ---
 
 # Seeding a tenant
@@ -56,20 +56,38 @@ to a BYPASSRLS/superuser role on every physical connection.
 
 ### 1. Check the environment and migrations
 
+Prepare the selected private source before `make dev` or `make seed`: it must
+include `KEYCLOAK_WEB_CLIENT_SECRET`, retain an existing confidential secret,
+and be a current-user-owned regular, nonsymlink, single-link file without
+group/other permissions. For a verified legacy file, explicitly run
+`chmod 600 .env` (or the selected path); Makefile creation does not repair it.
+Follow [secret continuity and recovery](../../../infra/keycloak/README.md#secret-continuity-and-recovery)
+on mismatch. Do not read secrets into an agent transcript or place them on argv.
+
 ```bash
 make seed
 ```
 
 This target starts the selected stack and waits for PostgreSQL before migration.
 `scripts/seed.sh` then checks full Compose health and both realm issuers before
-running the .NET tool. `scripts/compose.mjs` shares project/files/env selection
-with the demo lifecycle; inherited Compose profiles cannot widen its default set.
+running the fresh Release Seeder DLL and then the shared development-only realm
+reconciler. Both combined entries reject an incomplete selected private realm
+source before infrastructure work; older files must explicitly add the BFF
+secret key. The [realm guide](../../../infra/keycloak/README.md) owns the exact
+contract and delivery status. `scripts/compose.mjs` shares project/files/env
+selection with the demo lifecycle; inherited Compose profiles cannot widen its
+default set.
+It verifies the effective Docker context before starting the selected stack.
+Seed preparation reports fixed stage progress and closed failure reasons rather
+than forwarding potentially sensitive child output. On cancellation/failure,
+wait for owned cleanup; follow [lock recovery](../../../infra/keycloak/README.md#lock-recovery)
+if the previous realm owner left its exclusive lock.
 The direct tool runs
 from `backend/`, where `global.json` pins the SDK:
 
 ```bash
 (cd backend && ConnectionStrings__Default="<learnstack_app connection string>" \
-    dotnet run --project src/LearnStack.Tools.Seeder --nologo)
+    dotnet run --project src/LearnStack.Tools.Seeder --configuration Release)
 ```
 
 Do not put a real connection string on `argv` or print it. The script reads the
@@ -223,4 +241,12 @@ localized schemas/bodies/pins supported by shipped contracts. Derive inventory a
 test expectations from the declaration. A new locale must be enabled before its
 translation is written. Domain-specific application behavior requires the owning
 phase's platform-feature decision; it cannot be hidden inside seed orchestration.
-Keycloak users still come from compose realm imports, not this tool.
+P02b-6 Step 1 declares development authentication personas in `SeedData.IdentityUsers`
+and exposes credential-free `--identity-manifest`; that mode opens no data source.
+Fresh Keycloak accounts come from the checked realm import. The accepted
+[P02b-6 package](../../../docs/roadmap/phase-02b-events-auth.md#p02b-6-decision-package-2026-10-20)
+owns the separate development reconciler, awaited by both combined seed/demo
+entries after application seed convergence. Its
+[Step 4 record](../../../docs/roadmap/phase-02b-events-auth.md#p02b-6-step-4--real-identity-qualification-and-closeout-2026-10-21)
+owns real account/API qualification and the completed independent reviews.
+Direct .NET seeding creates no provider account or application membership.

.env.example

@@ -69,6 +69,10 @@ ConnectionStrings__OutboxDispatcher='Host=localhost;Port=5432;Database=learnstac
 # Authentication__Tenant__Issuer=https://identity.example/realms/learnstack
 KEYCLOAK_ADMIN=admin
 KEYCLOAK_ADMIN_PASSWORD=admin-dev-secret
+# Server-only BFF client source. Old local .env files must add it explicitly;
+# reconciliation verifies an existing confidential secret and never rotates it.
+# Never pass this value to the API, public renderer or .NET Seeder.
+KEYCLOAK_WEB_CLIENT_SECRET=learnstack-web-dev-secret
 
 # ─── Vault (-dev mode; token shared with Dapr secret-store component) ────
 # Boots the `vault` compose service via `-dev-root-token-id` AND is passed

.github/workflows/ci.yml

@@ -289,6 +289,10 @@ jobs:
         working-directory: frontend
         run: pnpm install --frozen-lockfile
 
+      - name: Prepare pinned provider fixture images within the whole-job budget
+        timeout-minutes: 2
+        run: python3 scripts/ci-test-shards.py prepare-fixtures
+
       - name: Verify stock browser for admission navigation proof
         run: |
           test -x /usr/bin/google-chrome
@@ -656,7 +660,7 @@ jobs:
         if: always()
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
-          name: openapi-comparison
+          name: openapi-comparison-${{ github.run_id }}-${{ github.run_attempt }}
           path: artifacts/openapi
           if-no-files-found: error
 
@@ -763,7 +767,7 @@ jobs:
         timeout-minutes: 1
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
-          name: public-demo-lighthouse
+          name: public-demo-lighthouse-${{ github.run_id }}-${{ github.run_attempt }}
           path: |
             artifacts/public-demo/receipt.json
             artifacts/public-demo/audit-*.json
@@ -785,6 +789,16 @@ jobs:
           fetch-depth: 0   # link audit walks the full tree
           persist-credentials: false
 
+      - name: Set up pinned Node.js for offline realm controls
+        timeout-minutes: 1
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Development realm transport, ownership and convergence controls
+        timeout-minutes: 1
+        run: python3 scripts/run-realm-node-tests.py
+
       - name: Compose stack validates, with and without the gated profile
         run: |
           # Nothing validated these files before, and the profile they now carry
@@ -796,6 +810,7 @@ jobs:
           # local development loop stops, for every developer, on a one-line edit.
           # The default projection is therefore the one that must be checked; the
           # gated one is checked too, since a broken edge there is invisible to it.
+          trap 'rm -f .env' EXIT
           cp .env.example .env
           for profile in "" "gated"; do
               label="${profile:-<default>}"
@@ -955,6 +970,9 @@ jobs:
       - name: CI supply-chain controls
         run: python3 scripts/test-ci-supply-chain.py
 
+      - name: Realm Node executed-case and JUnit gate controls
+        run: python3 scripts/test-realm-node-gate.py
+
       - name: Read-only native environment and duration logging controls
         run: python3 scripts/test-ci-native-environment.py
 
@@ -1108,6 +1126,6 @@ jobs:
         if: always()
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
-          name: leakwatch-results
+          name: leakwatch-results-${{ github.run_id }}-${{ github.run_attempt }}
           path: results.sarif
           if-no-files-found: error