docs(e2e): add settings maintenance guidance

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 2 people

.claude/rules/sim-settings-e2e.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "apps/sim/**"
+  - "packages/platform-authz/src/workspace.ts"
+  - "packages/platform-authz/src/predicates.ts"
+---
+
+# Settings E2E Maintenance
+
+When a change can affect observable settings routes, copy, visibility,
+authorization, entitlements, mutations, or persisted workflows, read
+`apps/sim/e2e/MAINTENANCE.md` before finishing and assess every applicable
+literal Playwright contract.
+
+Keep acceptance expectations independent of production navigation and
+authorization implementations. Behavior-preserving refactors need focused
+verification, not artificial contract edits.

.claude/rules/sim-settings-pages.md

@@ -1,20 +1,29 @@
 ---
 paths:
+  - "apps/sim/app/account/settings/**"
+  - "apps/sim/app/organization/*/settings/**"
   - "apps/sim/app/workspace/*/settings/**"
+  - "apps/sim/components/settings/**"
   - "apps/sim/ee/**/components/**"
 ---
 
 # Settings Pages
 
-The Next.js `settings/[section]/layout.tsx` owns all settings page chrome via
-`SettingsHeaderShell` — a fixed header bar (a left back chip + right-aligned
-action chips), a scroll region, and a centered `max-w-[48rem]` content column led
-by a **title + description from navigation metadata**. The chrome stays mounted
-across section navigation (it never re-renders or re-lays-out). Each section
-renders through the **`SettingsPanel`** registrar
-(`@/app/workspace/[workspaceId]/settings/components/settings-panel`), which feeds
-the shell its header data and renders only the section body. Sections supply
-**data**, never chrome.
+All three settings planes share `SettingsHeaderShell` and the canonical
+`SettingsPanel` implementation in `@/components/settings/settings-panel`, but
+their chrome is mounted at different boundaries:
+
+- Account and organization `settings/layout.tsx` mount
+  `StandaloneSettingsShell`, which owns their sidebar, header shell, section
+  provider, and unload guard.
+- Workspace `settings/[section]/layout.tsx` mounts the persistent header shell;
+  the outer workspace `settings/layout.tsx` owns its unload guard.
+
+The active shell owns the fixed header bar (a left back chip + right-aligned
+action chips), scroll region, and centered `max-w-[48rem]` content column led by
+a **title + description from the shared settings registry**. Each section
+renders only its body through `SettingsPanel`; sections supply **data**, never
+chrome.
 
 Do NOT hand-roll any of these in a settings page — they are owned by the layout
 shell (fed through `SettingsPanel`):
@@ -29,6 +38,8 @@ shell (fed through `SettingsPanel`):
 ## Canonical page shape
 
 ```tsx
+// Established section-component import; this compatibility barrel re-exports
+// the canonical @/components/settings/settings-panel implementation.
 import { SettingsPanel } from '@/app/workspace/[workspaceId]/settings/components/settings-panel'
 
 return (
@@ -80,21 +91,29 @@ return (
 - `scrollContainerRef?: React.Ref<HTMLDivElement>` — forwards a ref to the scroll
   region (e.g. programmatic scroll-to-bottom).
 
-## Title + description live in navigation metadata
+## Title + description live in the shared settings registry
 
-`apps/sim/app/workspace/[workspaceId]/settings/navigation.ts` is the single source
-of truth. Every `NavigationItem` carries a one-line `description`; `SettingsPanel`
-resolves both via `getSettingsSectionMeta(section)` and the
-`SettingsSectionProvider` the settings shell wraps around the active section.
+`apps/sim/components/settings/navigation.ts` is the single source of truth.
+Each `SettingsSectionRegistryEntry` owns a `unified` projection with the default
+description and gating metadata plus optional account, organization, and
+workspace plane projections. Account and organization shells provide `plane`
+and `section`, so the shared `SettingsPanel` resolves metadata with
+`getSettingsSectionMeta(plane, section)`. The workspace adapter at
+`app/workspace/[workspaceId]/settings/navigation.ts` resolves the mandatory
+unified projection with its one-argument `getSettingsSectionMeta(section)` and
+the workspace renderer passes that metadata to `SettingsSectionProvider`.
 
 Adding a new settings page:
 
-1. Add the `SettingsSection` id + a `NavigationItem` (with `label` **and**
-   `description`) in `navigation.ts`. Keep descriptions verb-first, one line,
-   ~40–55 chars, in the product voice (see `.claude/rules/constitution.md`).
-2. Render the component inside the shell's `effectiveSection` switch in
-   `settings/[section]/settings.tsx`.
-3. Build the component body inside `<SettingsPanel>` — no shell, no title block.
+Follow the procedure in `.claude/skills/add-settings-page/SKILL.md`. The
+non-negotiable architecture invariants are:
+
+- Every registry entry has a mandatory unified projection, workspace renderer,
+  and server-side direct-route outcome.
+- Every optional account, organization, or workspace plane projection has its
+  corresponding renderer and access/feature gate.
+- The component body uses `SettingsPanel`; associated unit tests and every
+  applicable literal browser contract change in the same PR.
 
 ## Text-scale tokens (no literal pixel sizes)
 
@@ -187,8 +206,9 @@ changes" modal:
     (from `@/app/workspace/[workspaceId]/components/credential-detail`). The
     in-view header **Discard** chip (via `SaveDiscardActions onDiscard`) is a
     *reset to original* — distinct from the back-confirm's discard, which leaves.
-- **`useSettingsBeforeUnload`** is mounted **once** in the settings shell
-  (`settings/[section]/settings.tsx`) — never add a per-page `beforeunload`.
+- **`useSettingsBeforeUnload`** is mounted once per active shell boundary:
+  workspace `settings/layout.tsx` and `StandaloneSettingsShell` for account or
+  organization. Never add a per-page `beforeunload`.
 - **Dirty *computation* stays local** (shapes differ: field-compare vs
   normalize+stringify) — only how dirty is *consumed* is shared. Derive it (a
   `const`/`useMemo`), never store it in `useState`.
@@ -218,9 +238,9 @@ exception — it lives outside `[section]` and keeps its own `CredentialDetailLa
 A settings page is design-system-clean when:
 
 - [ ] Its main return is a `<SettingsPanel>` (or `<>…<SettingsPanel>…</>` with modal siblings) — no hand-rolled shell/header/scroll/column.
-- [ ] It renders **no** hand-rolled `<h1>`/description title block — the title comes from nav metadata.
+- [ ] It renders **no** hand-rolled `<h1>`/description title block — the title comes from the shared settings registry.
 - [ ] Header chips are in `actions`; a standalone search is in the `search` prop.
-- [ ] Its `NavigationItem` has an accurate, consistent-length `description`.
+- [ ] Its `SettingsSectionRegistryEntry` has an accurate, consistent-length `unified.description` and only the plane projections it supports.
 - [ ] Detail sub-views and entitlement/loading gates keep their own chrome (intentional).
 - [ ] If it has editable state: Save/Discard go through `SaveDiscardActions`, dirty is wired via `useSettingsUnsavedGuard` (called before any early-return gate), and there is **no** hand-rolled Save button / `beforeunload` / "Unsaved changes" modal.
 - [ ] No business logic, handlers, or conditional rendering changed by the migration.

.claude/skills/add-settings-page/SKILL.md

@@ -5,39 +5,79 @@ description: Add a new Sim settings page, or audit existing settings pages for d
 
 # Settings Page (add / audit)
 
-Sim settings pages all render through the shared **`SettingsPanel`** primitive,
-which owns the page chrome and renders a nav-driven title + description. The full
-convention lives in `.claude/rules/sim-settings-pages.md` — read it first; this
-skill is the procedure.
+Sim settings pages render their bodies through the shared **`SettingsPanel`**
+registrar, which publishes header metadata and actions to the active
+`SettingsHeaderShell`. The shell owns and renders the page chrome, including the
+registry-driven title and description. The full convention lives in
+`.claude/rules/sim-settings-pages.md` — read it first; this skill is the
+procedure.
 
 Key paths:
-- Layout primitive: `apps/sim/app/workspace/[workspaceId]/settings/components/settings-panel/settings-panel.tsx`
-- Nav metadata (titles + descriptions): `apps/sim/app/workspace/[workspaceId]/settings/navigation.ts`
-- Section switch + provider: `apps/sim/app/workspace/[workspaceId]/settings/[section]/settings.tsx`
+- Panel registrar implementation: `apps/sim/components/settings/settings-panel.tsx`
+- Established section-component import: `@/app/workspace/[workspaceId]/settings/components/settings-panel` (compatibility barrel)
+- Section types + registry: `apps/sim/components/settings/navigation.ts`
+- Account renderer: `apps/sim/components/settings/account-settings-renderer.tsx`
+- Account route gate: `apps/sim/app/account/settings/[section]/page.tsx`
+- Organization renderer: `apps/sim/components/settings/organization-settings-renderer.tsx`
+- Organization route gate: `apps/sim/app/organization/[organizationId]/settings/[section]/page.tsx`
+- Workspace metadata adapter: `apps/sim/app/workspace/[workspaceId]/settings/navigation.ts`
+- Workspace renderer + provider: `apps/sim/app/workspace/[workspaceId]/settings/[section]/settings.tsx`
+- Workspace route gate: `apps/sim/app/workspace/[workspaceId]/settings/[section]/page.tsx`
 - Pages: `apps/sim/app/workspace/[workspaceId]/settings/components/<name>/<name>.tsx` and EE pages under `apps/sim/ee/<feature>/components/`
+- Browser acceptance maintenance: `apps/sim/e2e/MAINTENANCE.md`
 
 ## Mode A — Add a new settings page
 
-1. **Navigation.** In `navigation.ts`: add the id to the `SettingsSection` union,
-   then a `NavigationItem` with `label` AND a one-line `description` (verb-first,
-   ~40–55 chars, product voice per `.claude/rules/constitution.md`). Place it in
-   the right `section` group and set any gating flags (`requiresHosted`,
-   `requiresEnterprise`, etc.).
-2. **Wire the switch.** Add the component to the `effectiveSection` render switch
-   in `settings/[section]/settings.tsx` (lazy `dynamic(...)` like its siblings).
-3. **Build the body inside `SettingsPanel`.** Never hand-roll the shell, header
+1. **Registry.** In `apps/sim/components/settings/navigation.ts`, add the id to
+   `UnifiedSettingsSection` and add a `SettingsSectionRegistryEntry` to
+   `SETTINGS_SECTION_REGISTRY`. Its mandatory `unified` projection owns the
+   default description and workspace gating flags (`requiresHosted`,
+   `requiresEnterprise`, etc.). For each plane-specific projection the page
+   needs, also add the id to `AccountSettingsSection`,
+   `OrganizationSettingsSection`, or `WorkspaceSettingsSection` and add that
+   optional projection. Use plane-specific copy only when its scope genuinely
+   differs. Keep descriptions verb-first, one line, ~40–55 chars, in the product
+   voice (see `.claude/rules/constitution.md`).
+2. **Always wire the unified workspace surface.** Every registry entry
+   participates in unified workspace navigation before its gates are applied,
+   whether or not it has `planes.workspace`. Render the `unified.id` in the
+   workspace `settings/[section]/settings.tsx` switch so an allowed route cannot
+   resolve to a blank page.
+3. **Wire optional standalone planes.** If the entry declares `planes.account`
+   or `planes.organization`, add the component to
+   `account-settings-renderer.tsx` or `organization-settings-renderer.tsx`.
+   Never declare a standalone projection whose renderer cannot render it.
+4. **Preserve every route gate.** In the workspace
+   `settings/[section]/page.tsx`, classify the unified section in
+   `WORKSPACE_SECTION_MAP` or `ORGANIZATION_SECTION_MAP` when it belongs to
+   either access plane; otherwise add an explicit direct gate when needed or
+   verify that host-context membership is the intended boundary. Enforce the
+   section's permission, deployment, plan, and entitlement outcome. For
+   standalone account or organization projections, also update their
+   `[section]/page.tsx` gate and the shared organization access/feature helpers
+   when applicable. Sidebar gating never replaces server authorization.
+5. **Build the body inside `SettingsPanel`.** Never hand-roll the shell, header
    bar, scroll region, content column, or title block. Put header buttons in
    `actions`, a standalone search in `search={{ value, onChange, placeholder }}`,
    and the page content as `children`. Modals go beside the panel inside a `<>`.
-4. **If the page has editable state**, wire the shared save/discard stack — put
+6. **If the page has editable state**, wire the shared save/discard stack — put
    `SaveDiscardActions` (dirty-gated Discard+Save chips) in `actions`, and call
    `useSettingsUnsavedGuard({ isDirty })` **before any early-return gate**.
    Detail sub-views additionally route the back chip through
    `guard.guardBack(closeFn)` and render the shared `UnsavedChangesModal`. Never
    hand-roll a Save button, a `beforeunload`, or an "Unsaved changes" modal —
    they're centralized. See the "Save / Discard + unsaved-changes guard" section
    in `.claude/rules/sim-settings-pages.md`.
-5. **Verify:** `cd apps/sim && bunx tsc --noEmit`; `bunx biome check --write <file>`.
+7. **Update tests and browser contracts.** Update the shared navigation,
+   workspace route/navigation, and access unit tests affected by the new
+   projection or gate. Then follow `apps/sim/e2e/MAINTENANCE.md`: intended
+   observable changes require paired literal Playwright contracts, while
+   behavior-preserving refactors require focused verification without
+   expectation churn.
+8. **Verify:** From `apps/sim`, run `bunx tsc --noEmit` and
+   `bunx biome check --write <file>` on changed source files. Then run the
+   affected unit tests and the focused orchestrated E2E project from
+   `e2e/README.md`.
 
 ## Mode B — Audit existing settings pages
 
@@ -54,8 +94,10 @@ For each page component, confirm the checklist in `.claude/rules/sim-settings-pa
    `.claude/rules/sim-settings-pages.md` for the token map and the row
    title/subtitle pairing convention):
    `git grep -n "text-\[1[0-8]px\]" -- 'apps/sim/**/settings/' 'apps/sim/ee/'`
-4. Confirm each page imports `SettingsPanel` and that its `NavigationItem` has an
-   accurate `description` of consistent length with its peers.
+4. Confirm each page imports `SettingsPanel` and that its
+   `SettingsSectionRegistryEntry` has an accurate `unified.description` of
+   consistent length with its peers, plus only the plane projections it
+   supports.
    - Editable pages: confirm Save/Discard go through `SaveDiscardActions` and
      dirty is wired via `useSettingsUnsavedGuard` (called before early-return
      gates) — flag any hand-rolled Save button, `beforeunload`, or unsaved modal.

.cursor/rules/sim-settings-e2e.mdc

@@ -0,0 +1,15 @@
+---
+description: Keep settings browser acceptance contracts aligned with observable behavior
+globs: ["apps/sim/**", "packages/platform-authz/src/workspace.ts", "packages/platform-authz/src/predicates.ts"]
+---
+
+# Settings E2E Maintenance
+
+When a change can affect observable settings routes, copy, visibility,
+authorization, entitlements, mutations, or persisted workflows, read
+`apps/sim/e2e/MAINTENANCE.md` before finishing and assess every applicable
+literal Playwright contract.
+
+Keep acceptance expectations independent of production navigation and
+authorization implementations. Behavior-preserving refactors need focused
+verification, not artificial contract edits.

apps/sim/AGENTS.md

@@ -221,6 +221,7 @@ export function useEntityList(workspaceId?: string) {
 - Use `vi.hoisted()` + `vi.mock()` + static imports; do not use `vi.resetModules()` + `vi.doMock()` + dynamic imports except for true module-scope singletons.
 - Do not use `vi.importActual()`.
 - Prefer mocks and factories from `@sim/testing`.
+- Before finishing a change that can affect observable settings routes, copy, visibility, authorization, entitlements, mutations, or persisted workflows, follow [`e2e/MAINTENANCE.md`](e2e/MAINTENANCE.md) and assess every applicable literal Playwright contract. Behavior-preserving refactors need focused verification, not artificial expectation edits.
 
 ## Utils Rules