Add feature flag system with rollouts, plan gating, and back-office admin

.claude/rules/backend/feature-flags.md

@@ -0,0 +1,65 @@
+---
+description: Non-obvious behaviour of the feature flag system on the backend (declaration, evaluation, lifecycle, ownership)
+---
+
+# Feature Flags (backend)
+
+Load this when adding, removing, or changing how a feature flag is evaluated or stored. The obvious parts (declare a field, read `executionContext.UserInfo.FeatureFlags`) are not repeated.
+
+## Subtype Is the Contract
+
+The `FeatureFlagDefinition` subtype on a field is not just a permissions tag — it rewires database-row ownership and validator behaviour at runtime. The subtype hierarchy replaced what used to be runtime checks (see the comment above the registry in `application/shared-kernel/SharedKernel/FeatureFlags/FeatureFlags.cs`).
+
+- `PlanGatedTenantFlag` makes `PlanBasedFeatureFlagEvaluator` the exclusive writer of tenant overrides on every JWT refresh; the reconciler stamps `Source=Plan` on the base row and the Set/Remove validators block manual edits.
+- `SystemFeatureFlag` skips the database entirely — config + frontend env var only. There is no per-tenant override.
+- `TenantAbTestFlag` / `UserAbTestFlag` enable rollout buckets; `IsAbTestEligible` and `ConfigurableBy*` are mutually exclusive by construction (the disjoint subtype branches), and `BucketStart/End` are ignored if you pick a non-AB subtype.
+- `TenantOwnerConfigurableFlag` requires `AdminLevel.TenantOwner` and `Scope.Tenant`; handlers check both. If those ever drift you get a silent 403.
+
+Switching subtypes on an existing flag changes the row owner on the next reconcile — confirm that's what you want before flipping a `TenantAbTestFlag` to `PlanGatedTenantFlag`.
+
+## `IsKillSwitchEnabled` Defaults the Row to Inactive
+
+`isKillSwitchEnabled: true` causes the reconciler to create the base row with `EnabledAt = null` — an admin must click Activate before anyone sees the flag. `ActivateFeatureFlag` / `DeactivateFeatureFlag` only operate on kill-switch flags; default-false flags (e.g. `TenantOwnerConfigurableFlag`) are globally un-killable by design — only per-tenant overrides can turn them off.
+
+## Soft-Delete Burns the Key
+
+The startup reconciler marks orphaned rows (`OrphanedAt`), and re-adding the same key restores them — including any orphaned tenant/user overrides. **But** once a row is `DeletedAt`-stamped (back-office hard-delete), re-adding the same key in C# throws on startup and aborts deployment. Don't re-use a name; pick a new one.
+
+## The Four BackOffice Query Mirrors Drift Silently
+
+`FeatureFlagEvaluator` is the canonical runtime path. The four BackOffice query handlers (`GetUserFeatureFlags`, `GetTenantFeatureFlags`, `GetFeatureFlagUsers`, `GetFeatureFlagTenants`) each carry their own copy of `EvaluateAbRollout`, `ComputeInclusionThresholdPercentage`, and `ComputeDefaultEnabled`. They agree today by construction, not by tests — if you change evaluation math, update all five and rely on `FeatureFlagEvaluatorTests` for the canonical contract.
+
+Known divergences worth being aware of: the mirrors do NOT consult parent-dependency, and `EvaluateOverride` in the bulk-list mirrors returns `IsEnabled=true` without checking `baseRow.IsActive`. BackOffice display can therefore report a flag as enabled while runtime evaluation excludes it.
+
+## Disable Semantics Are Asymmetric
+
+The four "disable this flag for this entity" paths look symmetric but aren't:
+
+- `SetTenantFeatureFlagInternal(Enabled=false)` (admin) creates a new override row with `EnabledAt == DisabledAt` if none exists. This is required: without it, the entity would stay enabled-by-rollout. Same applies to `SetUserFeatureFlagInternal`.
+- `SetTenantFeatureFlagOwner(Enabled=false)` (tenant owner) no-ops if no override exists — owners can't yank themselves out of a rollout they were never explicitly in.
+- `RemoveTenantFeatureFlagOverride` (admin only) is a hard `Remove`; the row is dropped.
+- `SetTenantFeatureFlagInternal(Enabled=false)` is a soft `Deactivate`; the row is kept with `DisabledAt` set.
+
+Both removal paths emit `FeatureFlagTenantOverrideRemoved`, but they produce different `OverrideCount` results in bulk admin lists because the list counts `Source=Manual` rows — `Remove` drops them, `Deactivate` keeps them.
+
+`SetTenantFeatureFlagOwner` is NOT a back-office mutation. It lives under `/api/account/feature-flags/{key}/tenant-override` and self-validates `Role == Owner`. Plan-gated flags are explicitly blocked at the validator level for both manual paths.
+
+## Rollout Math Is Deterministic by Flag
+
+`RolloutBucketHasher` is a van der Corput low-discrepancy sequence offset by a per-flag FNV-1a hash of the key. Two flags at the same percentage do NOT cover the same tenants, and ramping up never reshuffles existing members — a tenant included at 10% stays included at 20%. Don't replace this with a random or modulo strategy.
+
+`ComputeInclusionThresholdPercentage` returns the percentage at which an entity would join the rollout, but it's special-cased for pins (`AlwaysOn` → 0, `NeverOn` → null). After the pin-trumps-rollout change, pins are unconditional, so the "joins at N%" column in BackOffice lists is meaningless for pinned rows.
+
+## Reading vs Writing
+
+- Handlers: read `executionContext.UserInfo.FeatureFlags` (already populated from the JWT claim). Re-querying the DB at request time means you've stepped outside the JWT-claim contract.
+- The `FeatureFlagEvaluator` runs at JWT refresh, not per request. Flag changes take up to the 5-minute access-token TTL to propagate.
+- Mutations that change the actor's own claim must chain `AddRefreshAuthenticationTokens()` so the gateway refreshes the JWT in-flight; without that the user waits up to 5 minutes. Plain mutations of other users' flags don't need this — they'll see it on their next refresh.
+
+## Architecture Test Guards
+
+Every new back-office mutation belongs in `EndpointMetadataTests.AdminPolicyBackOfficeRoutes` if admin-only, and gets a paired `_WhenNonAdminBackOfficeIdentity_ShouldReturnForbidden` test. The architecture test fails if a route's declared `RequireAuthorization` policy doesn't match the allowlist.
+
+## Telemetry
+
+Override events (`FeatureFlagTenantOverrideSet/Removed`, `FeatureFlagUserOverrideSet/Removed`) carry a `FeatureFlagOverrideTrigger` axis: `Internal` (back-office staff), `Owner` (tenant owner), `Self` (end-user preference). Plan-source transitions emit their own `FeatureFlagPlanOverrideActivated/Deactivated` events — they're not in the trigger enum. Per-flag telemetry tags are emitted as a single comma-separated `user.feature_flags` dimension; `feature_flag.*` is reserved by the OTel semantic-conventions registry, do not reintroduce it.

.claude/rules/frontend/feature-flags.md

@@ -0,0 +1,37 @@
+---
+description: Non-obvious behaviour of the feature flag system on the frontend (hook, codegen, propagation timing)
+---
+
+# Feature Flags (frontend)
+
+Load this when gating UI on a feature flag, displaying a flag, or wondering why a toggle isn't reflecting in the SPA. The obvious parts (`useFeatureFlag(<key>)` returns `{ enabled }`) are not repeated.
+
+## `FeatureFlagKey` Is a Type-Level Contract
+
+`<key>` is typed against `FeatureFlagKey`, a codegen string-literal union built from `SharedKernel.FeatureFlags.FeatureFlags.cs`. Never cast a string to `FeatureFlagKey`; never accept a `string` parameter where `FeatureFlagKey` would do. Removing or renaming a flag in C# turns every stale callsite into a TS compile error after the next backend build — that compile error is the safety net.
+
+The codegen also enforces backend-before-frontend deploy order: the frontend build cannot reference a flag the backend hasn't shipped because the union is regenerated from the C# manifest.
+
+## The Hook Doesn't Subscribe — `AuthenticationProvider` Does
+
+`useFeatureFlag` reads `useUserInfo().featureFlags`. The bridge that turns the `x-user-feature-flags` response header into a re-render lives in `AuthenticationProvider` and short-circuits on identical flag sets, so re-renders are cheap. **Every authenticated response is the eventing channel** — there is no push, no SSE, no polling, and there is no flag-specific TanStack query to invalidate. Don't call `queryClient.invalidateQueries` for flag changes.
+
+## System Flags Bypass the User Path
+
+For `Scope: "system"` flags the hook reads `import.meta.runtime_env[envVar]` and ignores `userInfo` entirely. The hook handles this transparently — just call `useFeatureFlag(<key>)` regardless of scope. There is no per-tenant or per-user override for a system flag; if you need that, the flag is the wrong subtype on the backend.
+
+## Propagation Has a 5-Minute Floor
+
+Flag state lags behind a back-office or self-service toggle by up to the 5-minute access-token TTL. The mutation response carries `x-user-feature-flags` only when the mutating endpoint chains `AddRefreshAuthenticationTokens()` AND the gateway's endpoint-triggered refresh succeeds. Don't optimistically update for flag-driven UI; the response is the source of truth. If the backend was transiently unavailable during the refresh, the gateway suppresses `x-user-feature-flags` rather than emit the stale claim — so a "no change visible after toggle" outcome is a possible (rare) UI state.
+
+## Labels Are Codegen Too
+
+Display copy lives in `@repo/ui/featureFlags/labels` (`labels.generated.ts`), sourced from each `FeatureFlagDefinition.Label` / `Description`. Don't write parallel Lingui strings for flag names in components — call `getFeatureFlagLabel(key)`. The labels participate in the shared Lingui catalog under `shared-webapp/ui/translations/locale/`; translate there, not in the per-system catalog.
+
+## Where the Surfaces Live
+
+- Owner self-service: `/account/settings` (Features section) — `TenantOwnerConfigurableFlag` only.
+- User preferences: same area — `UserConfigurableFlag` only.
+- Back-office admin: `/feature-flags/{key}` — every scope.
+
+Orphaned and soft-deleted flags surface read-only in the back-office. They never reach `useFeatureFlag` (the codegen union drops them on the next backend build), so call sites don't need a "deleted flag" branch.

.claude/skills/db-query/SKILL.md

@@ -5,6 +5,8 @@ description: Query the local Postgres database of the active Aspire worktree via
 
 # Database Query
 
+**Port = `.workspace/port.txt` base + 2. Never trust Aspire MCP for the port — a common critical failure that silently runs SQL on another worktree's database.**
+
 **Read-only. Every write needs explicit user approval for that exact statement, every time — prior approvals never carry over.**
 
 **For destructive operations (DROP, TRUNCATE, DELETE, ALTER, or anything that loses data), take extreme care. If anything in the request is even slightly unclear about the scope, target, or intent, stop and ask for clarification before executing. Always assume the most conservative interpretation.**

.gitignore

@@ -132,6 +132,7 @@ $tf/
 
 # Visual Studio Code
 .vscode
+*.lscache
 
 # ReSharper is a .NET coding add-in
 _ReSharper*/
@@ -392,6 +393,7 @@ FodyWeavers.xsd
 **/package.g.props
 **/*.generated.d.ts
 **/*.generated.ts
+**/*.generated.json
 **/Api/swagger.json
 **/lib/api/*.Api.json
 **/lib/api/*.Api_*.json

AGENTS.md

@@ -18,7 +18,7 @@ Run `build` first, then `format`, `lint`, `test` in parallel with `--no-build`.
 
 **Slow:** Aspire restart, backend format, backend lint, end-to-end tests. **Fast:** frontend format/lint, backend test.
 
-**Aspire**: The `aspire-restart` skill manages the AppHost - always use it; never `aspire run`, `aspire restart`, or the developer CLI's `run` command. Use the Aspire MCP `list_resources` tool to look up service URLs (or read `.workspace/port.txt` if you only need the base port). In the agentic workflow, only the Guardian agent restarts Aspire. All other agents must notify the Guardian if they need it restarted.
+**Aspire**: The `aspire-restart` skill manages the AppHost - always use it; never `aspire run`, `aspire restart`, or the developer CLI's `run` command. Port = `.workspace/port.txt` base + 2. Never trust Aspire MCP for the port — a common critical failure that silently runs SQL on another worktree's database. If you need other Aspire MCP data, call `mcp__aspire__select_apphost` with the cwd path first. In the agentic workflow, only the Guardian agent restarts Aspire. All other agents must notify the Guardian if they need it restarted.
 
 Never commit, amend, or revert without explicit user instruction each time. Commit messages: one descriptive line in imperative form, no description body.
 

README.md

@@ -22,37 +22,56 @@
 
 Kick-start building top-tier B2B & B2C cloud SaaS products with sleek design, fully localized and accessible, vertical slice architecture, automated and fast DevOps, and top-notch security.
 
+Ships with signup and login via Google or email one-time password, Stripe-powered subscription and payment management with plan upgrades, downgrades, and invoicing, feature flags with A/B-rollout, plan-gating, and per-user/tenant overrides, and a back-office dashboard with MRR and revenue trends, plan distribution, and tenant growth.
+
 Built to demonstrate seamless flow: backend contracts feed a fully-typed React UI, pipelines make fully automated deployments to Azure, and a multi-agent workflow built on Claude Code's native [Agent Teams](https://code.claude.com/docs/en/agent-teams) where PlatformPlatform-expert agents collaborate to deliver complete features following the opinionated architecture. Think of it as a ready-made blueprint, not a pile of parts to assemble.
 
 ## What's inside
 
-* **Backend** - .NET 10 and C# 14 adhering to the principles of vertical slice architecture, DDD, CQRS, and clean code
+* **Backend** - .NET 10 and C# 14 following the principles of vertical slice architecture, DDD, CQRS, and clean code
 * **Frontend** - React 19, TypeScript, TanStack Router & Query, ShadCN 2.0 with Base UI for accessible UI
 * **CI/CD** - GitHub actions for fast passwordless deployments of docker containers and infrastructure (Bicep)
-* **Infrastructure** - Cost efficient and scalable Azure PaaS services like Azure Container Apps, Azure PostgreSQL, etc.
+* **Infrastructure** - Cost efficient and scalable Azure PaaS like Azure Container Apps and PostgreSQL
 * **Developer CLI** - Extendable .NET CLI for DevEx - set up CI/CD is one command and a couple of questions
-* **AI rules** - 30+ rules & workflows for Claude Code - sync to other editors can be enabled via `.gitignore`
+* **AI rules** - 30+ rules & skills, refined and battle-tested over a year of daily use, capturing our opinionated patterns
 * **Multi-agent development** - Agent Teams workflow where specialized Claude Code agents with deep PlatformPlatform expertise collaborate end-to-end
 
-Follow our [up-to-date roadmap](https://github.com/orgs/PlatformPlatform/projects/2/views/2) with core SaaS features like SSO, monitoring, alerts, multi-region, feature flags, back office for support, etc.
+Follow our [up-to-date roadmap](https://github.com/orgs/PlatformPlatform/projects/2/views/2).
 
 Show your support for our project - give us a star on GitHub! It truly means a lot! ⭐
 
 ### Back office
 
-Operate the platform: manage account signups, users, and logins, and monitor revenue, MRR, churn, invoices, and Stripe drift.
+Operate the platform from a dedicated SPA on its own hostname, secured by Entra ID Easy Auth:
+
+* **Dashboard** - KPI tiles for total accounts, blended MRR, all-time revenue, active users, and live sessions; trend cards for MRR, revenue, tenant growth, plan distribution, user logins; activity feeds for recent signups, payments, logins, and Stripe webhook events
+* **Accounts** - Search and filter every tenant; drill into detail with owner, plan, and signup activity
+* **Users** - Cross-tenant user list with role and last-seen filters; drill into per-user profile and tenant
+* **Invoices** - Paginated invoice ledger across every account with Stripe drift detection so finance can reconcile what's in Stripe vs. what landed in the database
+* **Billing events** - Authoritative event log of subscription, payment, and billing transitions, filterable by event type and account, with deep-link from dashboard cards
+* **Feature flags** - Four levers (System / Subscription plan / Account / User) plus A/B-rollout with rich telemetry; declared in C# and surfaced as a strongly-typed React hook; back-office UI for rollouts and overrides
 
 <img src="https://platformplatformgithub.blob.core.windows.net/BackOffice.gif" alt="PlatformPlatform Back Office" title="PlatformPlatform Back Office" />
 
-### Product demo
+### User-facing SaaS product
 
-End-user flows: tenant signup, account settings, Google login, welcome flow, accessibility and localization, and Stripe-powered subscription signup and management.
+Production-ready end-user surfaces — fully localized, accessible, and ready to brand as your own product:
+
+* **Signup** - Tenant signup with email one-time password or Google OAuth (OpenID Connect with PKCE)
+* **Login** - Same OTP and Google sign-in flows, with `UNLOCK` shortcut on localhost so dev mail is optional
+* **Welcome** - First-run guided flow for naming the account, uploading a logo, and inviting colleagues
+* **Account settings** - Owner-editable account name, logo, and danger-zone account deletion
+* **User management** - Invite users, change roles (Owner/Admin/Member), bulk delete, and recycle-bin restore
+* **Subscription & billing** - Embedded Stripe Checkout & Payment Element, prorated upgrades/downgrades, billing-info editing, scheduled-downgrade banner, dunning, and payment history with invoices and credit notes
+* **User profile** - Personal profile with avatar upload (Gravatar fallback), first/last name, email, and job title
+* **User preferences** - Theme (light/dark/system) and zoom per device, language per profile
+* **Sessions** - Active session list with device type, browser, and OS, plus one-click revocation of any session
 
 <img src="https://platformplatformgithub.blob.core.windows.net/$root/PlatformPlatformDemo.gif" alt="PlatformPlatform Demo" title="PlatformPlatform Demo" />
 
 # Getting Started
 
-TL;DR: Open the [PlatformPlatform](./application/PlatformPlatform.slnx) solution in Rider or Visual Studio and run the [Aspire AppHost](./application/AppHost/AppHost.csproj) project.
+TL;DR: Requires .NET 10, Node, and Docker. Clone the repo and `dotnet run` from `developer-cli/` to start Aspire.
 
 ### Prerequisites
 
@@ -283,8 +302,6 @@ cd application/AppHost
 dotnet run
 ```
 
-Alternatively, open the [PlatformPlatform](./application/PlatformPlatform.slnx) solution in Rider or Visual Studio and run the [Aspire AppHost](./application/AppHost/AppHost.csproj) project.
-
 On first startup, Aspire will prompt for `stripe-enabled` -- enter `true` to configure Stripe integration (see the optional Stripe setup section below) or `false` to skip.
 
 Once the Aspire dashboard fully loads, click to the WebApp and sign up for a new account (https://app.dev.localhost:9000/signup). A one-time password (OTP) will be sent to the development mail server, but for local development, you can always use the code `UNLOCK` instead of checking the mail server.