diff --git a/AGENTS.md b/AGENTS.md
index 14a7396f..a1e01410 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,9 +4,70 @@ Owns the Angular public website, operator dashboard and embeddable authenticatio
Start with the canonical [work state](../user-proxy/docs/WORK-STATE.md), [architecture](../user-proxy/docs/ARCHITECTURE.md), [capabilities](../user-proxy/docs/CAPABILITIES.md), [development](../user-proxy/docs/DEVELOPMENT.md), [security](../user-proxy/docs/SECURITY-OPERATIONS.md) and [design](../user-proxy/docs/DESIGN.md). Preserve existing README contribution rules and DESIGNGUIDE.md. Read widget integration/event guides before changing the custom element contract.
-- Branch workflow: use `production` as the frontend base and PR target. Before pushing a feature branch or opening its PR, fetch and merge the latest `origin/production` into that feature branch. Keep release branches unchanged until PR review.
-- Inspect status/diff; preserve unrelated changes. New application code uses TypeScript and existing standalone Angular patterns. Use Angular CLI scaffolding when practical; never change architecture solely to satisfy scaffolding.
-- Install from lock using `npm ci --ignore-scripts --legacy-peer-deps`; generate ignored env modules with `node tools/set-env`. Review environment base URLs before starting: local config defaults to a remote test API.
-- Run `node --test tools/tests/*.test.cjs`, affected builds and `git diff --check`. Existing Nx/Jest targets have known gaps: report exact commands and limitations in canonical work state.
-- Keep error, denied, empty and loading states distinct; provide retry. Never render request data as HTML or log/store tokens. Client visibility does not replace server authorization.
-- Update the single backend-owned capability matrix and work state alongside changes. Product/architecture guidance is linked, not duplicated here. Public claims require evidence; do not invent SLAs, guarantees or future functional controls.
+## Commands
+
+| Task | Command |
+|---|---|
+| Install | `npm ci --legacy-peer-deps` (Node 20; peer deps conflict without the flag) |
+| Env setup | `cp .env.example .env` and fill in the values. `tools/set-env.js` generates the git-ignored env-variables.ts for each app ([docs/environment.md](docs/environment.md)) |
+| Run dashboard | `npm start` (port 4200) |
+| Run widget alone | `npm run start:proxy-auth` (also port 4200) |
+| Build widget into dashboard assets | `npm run build:proxy-auth` |
+| Full build | `npm run build:test`, `npm run build:stage` or `npm run build:prod`. Plain `npm run build` mixes a prod widget with a local dashboard |
+| Format | `npm run format:code`. Prettier also runs on pre-commit through husky and lint-staged |
+
+`npm test` and `npm run lint` are not reliable at this commit: there is no test target on the dashboard, and `nx workspace-lint` is gone in Nx 21. Check a change by building the affected app: `npx nx build 36-blocks` or `npx nx build 36-blocks-widget` (run `node tools/set-env` first). The CI "Build check" workflow fails on every PR today because it never runs `set-env`, so a red check there says nothing about your change ([docs/environment.md](docs/environment.md#ci-githubworkflowsmainyml-build-check)).
+
+## Read before you change
+
+- Anything → [docs/architecture.md](docs/architecture.md), then [docs/conventions.md](docs/conventions.md); why things are shaped this way → [docs/decisions.md](docs/decisions.md)
+- The widget's public API, events or build → [docs/modules/widget-embed.md](docs/modules/widget-embed.md) and [docs/api.md](docs/api.md#widget-public-api-host-page--widget)
+- Widget login, register or OTP → [docs/modules/widget-auth.md](docs/modules/widget-auth.md), [docs/flows/widget-verification.md](docs/flows/widget-verification.md)
+- Widget account screens → [docs/modules/widget-account.md](docs/modules/widget-account.md)
+- Dashboard login, token or guards → [docs/modules/app-shell.md](docs/modules/app-shell.md), [docs/flows/dashboard-login.md](docs/flows/dashboard-login.md)
+- Blocks (features) wizard, OAuth clients, client secrets, redirect response mode → [docs/modules/panel-features.md](docs/modules/panel-features.md), [docs/flows/feature-configuration.md](docs/flows/feature-configuration.md)
+- Users, logs, billing, dashboard, layout → [docs/modules/panel-ops.md](docs/modules/panel-ops.md)
+- `libs/**`, HTTP, the interceptor → [docs/modules/shared-libs.md](docs/modules/shared-libs.md)
+- Routes, state, components, styling → [docs/ui/](docs/README.md#ui)
+- A common change (page, backend call, block tab, widget key or screen, env value, lib, release) → [docs/recipes.md](docs/recipes.md)
+
+## Rules
+
+1. Never rename or remove any part of the widget's public contract:
+ - `window.initVerification` and the `proxy-auth` tag
+ - `window.__proxyAuth` and the `openAddUserDialog` event
+ - the `userProxyContainer` id and the assets/proxy-auth/proxy-auth.js path
+ - any value in `libs/constant/src/verification/verification.ts`
+
+ Customer sites depend on all of these. Add new values instead ([docs/api.md](docs/api.md)).
+2. No dynamic `import()` in `apps/36-blocks-widget`. `build-elements.js` leaves the `chunk-*` file it creates out of the single-file bundle, so the bundle breaks on host pages.
+3. A new `initVerification` config key that must not be sent to the backend goes into `RESERVED_KEYS` in `apps/36-blocks-widget/src/app/init-verification.ts`. Every other key is POSTed as `otherData` ([recipe](docs/recipes.md#add-an-initverification-config-key)).
+4. Put widget CSS in component styles. `apps/36-blocks-widget/src/styles.scss` is also injected into the host page's `
`. Build overlays with `WidgetPortalService` / `WidgetDialogService`.
+5. Set and clear the dashboard token only through `AuthService.setTokenSync` / `clearTokenSync`. They keep the `authToken` cookie and the in-memory `IToken` in sync. Guards read both, HttpWrapper reads memory, and ErrorInterceptor reads only the cookie ([docs/modules/app-shell.md](docs/modules/app-shell.md)).
+6. A dashboard endpoint called without a session must be on the ErrorInterceptor allow-list. Otherwise it is silently dropped (`EMPTY`) ([docs/modules/shared-libs.md](docs/modules/shared-libs.md)).
+7. A 200 can still be an error. Check `res.hasError` (dashboard) or the per-endpoint success field (widget) as well as using `catchError` ([docs/conventions.md](docs/conventions.md#http-and-errors)).
+8. A block has two ids: numeric `id` for feature CRUD, OAuth, scopes and client secrets, and string `reference_id` for the widget, billing and the Users/roles screens. Passing the wrong one fails silently ([docs/glossary.md](docs/glossary.md)).
+9. In the widget, copy `OtpService.options` before adding per-call headers. It is one shared mutable object, and its headers leak into later calls.
+10. The widget must not import `@proxy/services/proxy/*`, `@proxy/services/httpWrapper` or the login service. They need `AngularFireAuth` and `IToken`, which only the dashboard provides.
+11. Add dashboard pages to `apps/36-blocks/src/app/panel/panel.routes.ts`. `apps/36-blocks/src/app/panel/layout/layout.routes.ts` is dead (nothing imports it).
+12. Never send a client id. The current client is stored on the server against the token, and switching client is `POST switchclient` followed by a full page reload.
+13. Everything `tools/set-env.js` writes ends up in a public browser bundle. Never add a real server-side secret there. When you add a key, also add it to `.env.example`.
+14. Keep the `setTimeout(…, 100)` before block create/update in `create-feature.component.ts`. The payload is filled in by promises (file reads, chip lists) ([docs/modules/panel-features.md](docs/modules/panel-features.md)).
+15. Branch flow is `-clean` → `stage` → `production`; the README's `development`/`main` flow is stale. PRs into `stage` get **no CI build**, so build locally first. Land any revert on `stage` too ([docs/conventions.md](docs/conventions.md#branching-and-release)).
+
+## Where things are
+
+- `apps/36-blocks/src/app/website/`: public marketing pages, login and register
+- `apps/36-blocks/src/app/panel/`: the logged-in `/app` dashboard pages, each with a `.store.ts` ComponentStore
+- `apps/36-blocks/src/app/core/`: the root NgRx store, the auth initializer, client registration
+- `apps/36-blocks-widget/src/app/init-verification.ts`: the widget's global API
+- `apps/36-blocks-widget/src/app/otp/`: widget screens, the `otp` store, `OtpService`
+- `apps/36-blocks-widget/build-elements.js`: post-build step that produces the single proxy-auth.js
+- `libs/`: shared code, imported only through the `@proxy/...` aliases in `tsconfig.base.json`
+- `tools/set-env.js`, `tools/postbuild.js`: env generation and the version.json writer
+- `apps/shared/scss/`: global SCSS and Tailwind entry shared by both apps
+
+## Docs map
+
+See [docs/README.md](docs/README.md) for every doc and when to read it. What the code can't answer is listed in [docs/open-questions.md](docs/open-questions.md); don't guess at those, ask.
+When you change behaviour that a doc describes, update that doc in the same change and run `/ai-docs update`.
diff --git a/docs/.ai-docs.json b/docs/.ai-docs.json
index f954fef0..be4debd3 100644
--- a/docs/.ai-docs.json
+++ b/docs/.ai-docs.json
@@ -2,7 +2,7 @@
"skill": "ai-docs",
"skill_version": "0.1.0",
"created": "2026-10-14",
- "last_run": { "mode": "init", "commit": "76f26ae5", "date": "2026-10-14" },
+ "last_run": { "mode": "update", "commit": "395659d5", "date": "2026-10-29" },
"superseded": [
"docs/widget-window-events.md",
"docs/widget-script-loading.md",
diff --git a/docs/README.md b/docs/README.md
index 6da603f1..fafce903 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,6 +1,6 @@
---
-verified_at: 76f26ae5
-verified_on: 2026-10-14
+verified_at: 395659d5
+verified_on: 2026-10-29
---
# Docs index
@@ -16,6 +16,8 @@ Start with [../AGENTS.md](../AGENTS.md), then read the doc for the area you're c
| [api.md](api.md) | You're touching the widget's public JS API (`initVerification`, callbacks, window events) or any backend call |
| [environment.md](environment.md) | You're running or building locally, adding an env key, or touching CI or `tools/` |
| [recipes.md](recipes.md) | You're making a common change: a page, a backend call, a block tab, a widget config key or screen, an env value, a lib, a release |
+| [decisions.md](decisions.md) | You want to know why something is built the way it is before changing it: the single-file widget, two HTTP wrappers, build-time config, per-page stores, no Nx Cloud |
+| [open-questions.md](open-questions.md) | You hit something the code can't explain. Every open question for a human, linked to the doc that holds the detail |
## Modules
@@ -52,23 +54,16 @@ The older notes (docs/widget-*.md, docs/build-modernization.md, docs/angular-*.m
## Needs a human
-Open questions the code can't answer. Answer them in the doc that asks, then delete the TODO.
-
-- **Branching:** which branch to cut `-clean` from, and whether `main` and `development` are retired ([conventions.md](conventions.md#branching-and-release)).
-- **Deploy and CI:**
- - the deploy target and the branch-to-environment mapping ([architecture.md](architecture.md#build), [environment.md](environment.md))
- - whether CI "Build check" passes ([environment.md](environment.md))
- - whether the `postbuild.js` hash regex matches upper-case hashes ([environment.md](environment.md))
- - whether stage `production: false` is intended ([environment.md](environment.md))
-- **SSR:** why it was removed, and whether the leftover files can be deleted ([modules/app-shell.md](modules/app-shell.md)).
-- **Auth:**
- - whether the backend rejects `Bearer` ([modules/shared-libs.md](modules/shared-libs.md))
- - the missing redirect after email login, and whether `/login` can return 401 ([flows/dashboard-login.md](flows/dashboard-login.md))
-- **Widget:**
- - client-side AES with static keys ([modules/widget-auth.md](modules/widget-auth.md))
- - whether MSG91 and callback errors should reach the host's `failure` ([modules/widget-auth.md](modules/widget-auth.md), [flows/widget-verification.md](flows/widget-verification.md))
- - whether Tailwind preflight leaks into host pages, and whether `webpack.config.js` is dead ([modules/widget-embed.md](modules/widget-embed.md))
- - which backend permissions guard the role/permission endpoints, and the future of the `subscription` type ([modules/widget-account.md](modules/widget-account.md))
-- **Blocks:** whether `feature_id` 1/2 are stable, and the dead Lago helpers ([modules/panel-features.md](modules/panel-features.md)).
-- **Panel:** whether Logs is still a supported product, and which payment provider sits behind checkout ([modules/panel-ops.md](modules/panel-ops.md)).
-- **UI:** the rule for where state goes ([ui/state.md](ui/state.md)) and the `@apply` opacity limit ([ui/design-system.md](ui/design-system.md)).
+Open questions the code can't answer are collected in [open-questions.md](open-questions.md), and each one is also a `[!TODO]` in the doc it concerns. Answer it in that doc, then delete the TODO and the line in open-questions.md.
+
+## Where the standard doc names live
+
+Some agent guides expect files named ARCHITECTURE, FLOWS, CONFIGURATION, DECISIONS and OPEN_QUESTIONS. In this repo they map to the existing lower-case files, so there is one source of truth per topic and no case-only name clashes on case-insensitive file systems:
+
+| Expected | Here |
+|---|---|
+| ARCHITECTURE.md (modules, data, who calls whom) | [architecture.md](architecture.md), with per-module detail in [modules/](#modules) |
+| FLOWS.md (main flows step by step) | [flows/](#flows): [dashboard-login](flows/dashboard-login.md), [feature-configuration](flows/feature-configuration.md), [widget-verification](flows/widget-verification.md) |
+| CONFIGURATION.md (every setting and env var) | [environment.md](environment.md) |
+| DECISIONS.md | [decisions.md](decisions.md) |
+| OPEN_QUESTIONS.md | [open-questions.md](open-questions.md) |
diff --git a/docs/api.md b/docs/api.md
index be4c2797..f764bc8b 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1,7 +1,7 @@
---
covers: ["apps/36-blocks-widget/src/app/init-verification.ts", "apps/36-blocks-widget/src/main.ts", "apps/36-blocks-widget/src/app/otp/service/otp.service.ts", "apps/36-blocks-widget/src/app/otp/service/urls/**", "apps/36-blocks-widget/src/app/otp/service/user-management-bridge.service.ts", "libs/constant/src/widget-events.ts", "libs/urls/**", "libs/services/proxy/**", "libs/services/login/**", "apps/36-blocks/src/app/panel/billing/billing.urls.ts", "apps/36-blocks/src/app/panel/billing/billing.service.ts", "apps/36-blocks/src/app/app.config.ts"]
-verified_at: 76f26ae5
-verified_on: 2026-10-14
+verified_at: 395659d5
+verified_on: 2026-10-29
---
# API
@@ -150,7 +150,7 @@ Base `environment.baseUrl`; all with the JWT `Authorization` header.
| PUT / DELETE | `/:referenceId/cPermission/:id` | `updatePermission` / `deletePermission` |
## Dashboard: features (blocks) configuration
-`FeaturesService` (`libs/services/proxy/features/src/lib/services-proxy-features.module.ts`), JWT auth, base `environment.baseUrl`. Callers: `apps/36-blocks/src/app/panel/features/create-feature/create-feature.store.ts`, `apps/36-blocks/src/app/panel/features/feature/feature.store.ts`, `apps/36-blocks/src/app/panel/features/oauth-config/oauth-config.store.ts`, plus `LayoutComponent`, `DashboardComponent` and the users store (feature lists). Field-level details are in [panel-features](./modules/panel-features.md).
+`FeaturesService` (`libs/services/proxy/features/src/lib/services-proxy-features.module.ts`), JWT auth, base `environment.baseUrl`. Callers: `apps/36-blocks/src/app/panel/features/create-feature/create-feature.store.ts`, `apps/36-blocks/src/app/panel/features/feature/feature.store.ts`, `apps/36-blocks/src/app/panel/features/oauth-config/oauth-config.store.ts`, `apps/36-blocks/src/app/panel/features/client-secrets/client-secrets.store.ts`, plus `LayoutComponent`, `DashboardComponent` and the users store (feature lists). Field-level details are in [panel-features](./modules/panel-features.md).
| Method | Path | Service method |
@@ -165,6 +165,8 @@ Base `environment.baseUrl`; all with the JWT `Authorization` header.
| GET / PUT / DELETE | /features/:featureId/oauthConfigs/:oauthConfigId | `getOauthConfig` / `updateOauthConfig` / `deleteOauthConfig` |
| POST | /features/:featureId/oauthConfigs/:oauthConfigId/regenerateSecret | `regenerateOauthSecret` |
| POST | /features/:featureId/oauthConfigs/:oauthConfigId/disable | `disableOauthConfig` |
+| GET / POST | /features/:featureId/clientSecrets | `getClientSecrets` / `createClientSecret` (plaintext `client_secret` only in this response) |
+| DELETE | /features/:featureId/clientSecrets/:secretId | `revokeClientSecret` (revokes; the secret stays listed with `revoked_at`) |
| GET / POST | /features/:featureId/blockScopes | `getBlockScopes` / `createBlockScope` |
| PUT / DELETE | /features/:featureId/blockScopes/:blockScopeId | `updateBlockScope` / `deleteBlockScope` |
| GET / POST | /subscription/:refId/billableMetrics | `getAllBillableMetrics` / `createBillableMetric` |
diff --git a/docs/architecture.md b/docs/architecture.md
index 69435d5a..2ac0c9cf 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,7 +1,7 @@
---
covers: ["apps/36-blocks/src/main.ts", "apps/36-blocks/src/app/app.config.ts", "apps/36-blocks/src/app/app.routes.ts", "apps/36-blocks-widget/src/main.ts", "apps/36-blocks-widget/src/app/init-verification.ts", "apps/36-blocks-widget/build-elements.js", "apps/*/project.json", "tsconfig.base.json", "nx.json", "tools/*.js"]
-verified_at: 76f26ae5
-verified_on: 2026-10-14
+verified_at: 395659d5
+verified_on: 2026-10-29
---
# Architecture
@@ -121,6 +121,8 @@ flowchart LR
## Decisions and history
+The full list, with evidence for each, is in [decisions.md](decisions.md). The ones that shape this page:
+
- **One file for the widget.** Customers paste one `