Repair setup admin branding and action routes

docs/implplan/SPRINT_20260311_005_FE_setup_admin_truthful_branding_and_notifications_routes.md

@@ -0,0 +1,69 @@
+# Sprint 20260311_005 - FE Setup Admin Truthful Branding And Notifications Routes
+
+## Topic & Scope
+- Repair setup/admin pages that looked valid in route sweeps but failed as a first-time operator once actions were exercised.
+- Restore truthful branding behavior on `/setup/tenant-branding`, including correct Authority contracts, reliable hydration, and honest read-only semantics when the session lacks write scope.
+- Repair setup notifications, usage, and system action handoffs so setup pages lead to the intended working surfaces instead of dead or fallback routes.
+- Working directory: `src/Web/StellaOps.Web`.
+- Allowed coordination edits: `docs/ui-analysis/01_SHELL_AND_NAVIGATION.md`, `docs/ui-analysis/04_ADMIN_CONFIG_RELEASE_EVIDENCE_SCREENS.md`, `docs/ui-analysis/05_ROUTE_SUMMARY_AND_OBSERVATIONS.md`, `docs/features/checked/web/settings-ia-rationalization-ui.md`, `docs/implplan/SPRINT_20260311_005_FE_setup_admin_truthful_branding_and_notifications_routes.md`.
+- Expected evidence: focused Angular specs, rebuilt web bundle synced into `compose_console-dist`, a passing live setup/admin Playwright sweep, and a passing live canonical route sweep.
+
+## Dependencies & Concurrency
+- Depends on the live compose stack at `https://stella-ops.local`.
+- Safe parallelism: stay inside setup/admin route ownership, branding contracts, and related route tests. Do not broaden this slice into Authority backend contract changes beyond the already-shipped endpoints.
+
+## Documentation Prerequisites
+- `AGENTS.md`
+- `docs/qa/feature-checks/FLOW.md`
+- `docs/technical/architecture/console-branding.md`
+- `docs/implplan/SPRINT_20260306_003_FE_playwright_setup_reset_iteration_loop.md`
+
+## Delivery Tracker
+
+### FE-SETUP-ADMIN-001 - Make setup branding truthful and tenant-aware
+Status: DONE
+Dependency: none
+Owners: QA, 3rd Line Support, Product Manager, Architect, Developer
+Task description:
+- Live Playwright verification showed `/setup/tenant-branding` was not a truthful setup/admin surface. The page rendered a facade that suggested inline editing, while the real Authority contracts required tenant-aware reads and admin writes through `/console/admin/branding`. Direct probes confirmed the setup route was triggering `GET /console/branding` without a tenant and surfacing `tenantId query parameter is required`.
+- The clean fix is to make the canonical setup route host the real branding editor, centralize tenant resolution and admin update contracts inside the shared branding service, and expose honest read-only UX when the current session has branding read scope but not write scope.
+
+Completion criteria:
+- [x] `/setup/tenant-branding` hosts the real branding editor instead of a facade.
+- [x] Branding reads and writes use the correct tenant-aware Authority contracts.
+- [x] Async branding hydration reliably clears loading state on the live shell.
+- [x] Read-only sessions show explicit non-editable controls and a truthful permission message.
+- [x] Focused branding service and route tests pass.
+
+### FE-SETUP-ADMIN-002 - Repair setup notifications, usage, and system action handoffs
+Status: DONE
+Dependency: FE-SETUP-ADMIN-001
+Owners: QA, 3rd Line Support, Product Manager, Architect, Developer
+Task description:
+- Manual Playwright action testing found `/setup/notifications` navigating `Create Rule` into a broken `/setup/notifications/new` path, while `/setup/usage` and `/setup/system` exposed inert buttons that did not carry operators into the actual working pages.
+- The correct product behavior is to keep setup pages as navigational truth surfaces: notification actions must land on canonical rule/simulator children, and usage/system actions must link directly into the corresponding operational pages.
+
+Completion criteria:
+- [x] `Create Rule`, edit, and simulator handoffs under setup notifications use canonical child routes.
+- [x] Usage and system CTA buttons are real links to the operational surfaces they advertise.
+- [x] Route ownership regression coverage protects the setup/admin aliases.
+- [x] Live setup/admin Playwright sweep passes with zero runtime issues.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-03-11 | Sprint created after live Playwright action testing found that `/setup/tenant-branding` failed to load branding under the real session, `/setup/notifications` misrouted `Create Rule`, and `/setup/usage` plus `/setup/system` exposed inert buttons. | Developer |
+| 2026-03-11 | Replaced the setup branding facade with the real branding editor, centralized tenant-aware admin branding reads/writes in `BrandingService`, converted async editor state to signals so the live shell clears loading reliably, and made read-only branding sessions truthful instead of deceptively editable. | Developer |
+| 2026-03-11 | Repaired setup notifications child navigation, rewired usage/system CTAs to canonical operational pages, refreshed route ownership coverage, and updated stale user-facing docs to point at `/setup/tenant-branding` as the canonical route. | Developer |
+| 2026-03-11 | `npx ng test --watch=false --progress=false --ts-config tsconfig.spec.features.json --include=src/app/core/branding/branding.service.spec.ts` passed `9/9`; `npx ng test --watch=false --progress=false --ts-config tsconfig.spec.features.json --include=src/app/features/admin-notifications/components/notification-rule-list.component.spec.ts` passed `49/49`; `npx ng test --watch=false --progress=false --include=src/app/routes/route-surface-ownership.spec.ts` passed `7/7`; `npm run build` passed; the rebuilt bundle was synced into `compose_console-dist`, `stellaops-router-gateway` was restarted, `node ./scripts/live-setup-admin-action-sweep.mjs` passed with `failedActionCount=0` and `runtimeIssueCount=0`, and `node ./scripts/live-frontdoor-canonical-route-sweep.mjs` returned `111/111` against `https://stella-ops.local`. | QA |
+
+## Decisions & Risks
+- Decision: `/setup/tenant-branding` is the canonical user-facing branding route. Legacy settings/admin aliases may remain, but the setup route must host the truthful experience.
+- Decision: branding contract knowledge belongs in `BrandingService`, not scattered raw HTTP calls inside the editor component. This keeps tenant resolution and Authority headers consistent across reads and writes.
+- Decision: when the session lacks branding write scope, the UI must be explicitly read-only. Disabled saves with still-editable inputs are deceptive and fail the zero-tolerance QA bar.
+- Risk: `docs/ui-analysis/**` contains broad analytical snapshots of the UI. This sprint updated the specific canonical-route references touched by the fix, but those analysis docs may still contain other stale historical entries outside this slice.
+
+## Next Checkpoints
+- Commit the setup/admin truth-surface repair.
+- Clean transient Playwright output from the working tree.
+- Start the next deep page-action sweep from the freshly rebuilt stack and take the next failing page family through the same fix loop.