docs: v1 docs refresh (batch 5) (#1395)

* docs(introduction): refresh for the redesigned UI and replace screenshots

Bring the Getting Started Introduction page in line with the current
product:

- Add the Security top-level view to the navigation list and a
  dedicated Security section with a new screenshot.
- Correct the Fleet tab names (Snapshots, Status, Map, Deployments,
  Routing, Federation, Actions, Secrets).
- Split Settings out from security and list the current nine setting
  groups (Security graduated to its own view).
- Refine the navigation paragraph so role, tier, and local-vs-remote
  context read accurately.

Replace all four existing screenshots (Home, stack workspace, Fleet,
Resources) with fresh captures of the redesigned UI and add a Security
overview screenshot.

* docs(configuration): document advanced env vars and clarify deployment vs runtime config

Add an Advanced environment variables section (TRIVY_BIN, SENCHO_MESH_SUBNET,
GITSOURCE_MAX_CLONE_BYTES, SENCHO_PUBLIC_URL, SENCHO_COMPOSE_STALL_TIMEOUT_MS) and
reframe the intro to separate deployment-time configuration from the runtime
settings that live in the in-app Settings Hub. Cross-link the pilot-agent
variables to the Pilot Agent page instead of duplicating them.

* docs(sso): refresh SSO Setup Guide and SSO & LDAP reference for the redesigned UI

Refresh both SSO documentation pages against the current product and the
redesigned settings UI.

- Correct the navigation path to Settings -> Access -> SSO on both pages.
- Fix the "Require 2FA on SSO sign-in" toggle location to
  Settings -> Personal -> Account.
- Describe the login-page experience (the Local / LDAP toggle and the
  branded OIDC buttons under the "Or continue with" divider) and the SSO
  panel masthead (SCOPE, PROVIDERS, ENABLED).
- Replace all six SSO screenshots with fresh captures of the redesigned UI.

* docs(features): refresh the Features Overview page for the redesigned UI

Rewrite docs/features/overview.mdx to mirror the current Features
navigation grouping (Stacks, Deployment, Resources, Observability,
Fleet, Automation, Security & Identity) and add the recently shipped
capabilities surfaced in the redesign: Stack Dossier, Drift Detection,
Compose Doctor, Compose Networking, Environment & secrets guardrails,
Storage portability, Health-Gated Updates, Fleet Dossier, and the
dedicated Security page.

Correct stale claims (the file explorer now gates writes on stack edit
permission, not an admin role; downloads are a read action; bulk label
assign now spans nodes) and standardize the tier callouts so partly
paid features read as "Admiral adds X". Replace the three pre-redesign
screenshots and add a Security overview banner, all captured from a
populated fleet.

* docs(features): refresh the Appearance page for the redesigned UI

Add fresh screenshots and a troubleshooting section to the Appearance
page, verified against the live product.

- Add four screenshots: the Theme card (live preview, mode, accent, and
  fine-tune sliders), the top-bar quick switcher, the Typography card,
  and the Display card.
- Refresh the Density screenshot used by the Settings reference page.
- State that the quick switcher also covers text size, and that the
  contrast, border, and glow sliders stay in Settings.
- Add a Troubleshooting accordion covering per-browser persistence,
  resets to defaults, cross-operator scope, and the quick-switcher
  versus full-Settings split.

* docs(introduction): refresh screenshots and correct stale content

* docs(reference): refresh the Settings Reference page for the redesigned UI

Replace all seven stale screenshots with fresh 1920x1080 captures.
Add five new screenshots for the sections that previously had none.

Content changes:
- Sidebar table: rename Infrastructure "Fleet Mesh" entry to "Fleet";
  add "Image update checks" to the Automation group list
- Fleet section: rename heading to match registry label; add the
  Documentation snapshots subsection (snapshot_documentation toggle)
- Container Alerts: add screenshot
- Image update checks: add the full section (Registry checks table,
  scheduling mode, interval presets, cron expression support)
- Stacks / Deploy Guardrails: add screenshot
- Recovery: add the full section (System health snapshot, Environment
  preflight checks, Safe actions, Command-line recovery table)

* docs(sso): refresh screenshots for SSO quickstart and feature pages

* docs: refresh Features Overview screenshots and content

Replace all 4 hero screenshots with fresh 1920x1080 production captures.
Correct security posture state names (Action needed / Monitoring / Secure),
add the Policies tab to the Security section tab list, mention the Simple
mode in Scheduled operations, and update all alt text to match the new
screenshots.

* docs: refresh Appearance page screenshots and correct quick-switcher scope

Replace all four Appearance screenshots with fresh production captures.
Fix the quick-switcher control list: remove fonts (not present in the
popover), add visual style and readability which are. Add Log chip color
to the Display section. Update all screenshot alt text to match new
captures.

* docs: refresh stack management page with current UI and anatomy tabs

* docs: fix convert-tab-error screenshot with fully visible error toast

* docs: convert troubleshooting section to AccordionGroup format

* docs(quickstart): refresh screenshots and align dashboard description

Replace all three first-boot and dashboard screenshots with current UI.
Add Security to the top navigation list, update gauge and Stack health
descriptions to reflect sparklines and column detail, and align
Configuration Status wording with the Introduction page.

* docs(editor): rewrite anatomy panel, replace all screenshots

- Correct the anatomy panel tab inventory: the panel has eight tabs
  (Anatomy, Activity, Dossier, Drift always; Environment, Networking,
  Doctor, Storage when the node advertises the matching capability), not
  three as previously documented
- Add table describing all eight tabs with capability gates and links to
  dedicated feature pages
- Add anatomy-tabs.png screenshot showing the scrollable tab row
- Note the Doctor severity dot (red for blocker, amber for high-risk)
- Remove the stale Markdown-export subsection; Dossier and Activity are
  now covered in the tab table
- Replace all six stale screenshots with fresh 1920x1080 captures
- Replace the compose diff preview screenshot

* docs(files): refresh Files & Volumes screenshots and fix context-menu alt text

Replace all 9 stale screenshots on the Files & Volumes page with fresh
captures from the production node. Fix three alt-text strings that did
not match the live UI: removed hardcoded octal value 644, and added the
Duplicate, Copy to, and Move to entries missing from the context-menu
alt text.

* docs: rewrite Stack Activity page with full event categories and fresh screenshots

Expands the event category table from 5 to 10 entries to cover drift
detected, drift resolved, update started, health gate passed, and health
gate failed. Adds a live-disconnected-state section, a background-actor
attribution table, and a corrected troubleshooting accordion covering the
WebSocket reconnect case. Replaces both stale screenshots with fresh
1920x1080 captures from the production node.

* docs(drift): rewrite drift detection page with screenshots and full coverage

Full rewrite of the Drift Detection feature page. Adds two previously
undocumented finding types (network-undeclared, network-missing), expands
the temporal section to distinguish the raw-file hash from the parsed-model
hash, documents the two-layer spatial-engine and ledger architecture,
explains when the ledger is reconciled (post-deploy vs manual re-check vs
tab open), adds Activity timeline integration note, introduces a Limitations
section (no background scanner, port-range caveat, history cap, advisory-only
enforcement), expands Troubleshooting from five entries to seven using the
AccordionGroup convention, and adds four production screenshots.

* docs(drift): use CardGroup for Related section

* docs(dossier): rewrite Stack Dossier page with full feature coverage

* docs(networking): rewrite Compose Networking page with full feature coverage

* docs(doctor): rewrite Compose Doctor with full 30-rule reference, screenshots, and cross-links

* docs(networking): add production screenshots and correct alt text

Adds 7 production screenshots for all sections of the Compose Networking
page and updates the four placeholder alt texts written before screenshots
were taken to match what the actual images show (arr-net external badge,
swag service with 443/tcp and 80/tcp, single-service exposure intent row).
Also adds the full-panel overview image at the top of the page.

* docs(environment-guardrails): rewrite with project env file, env file status, and screenshots

* docs(storage): rewrite Storage Portability page with screenshots and full coverage

Rewrites compose-storage.mdx from a 61-line sketch into a complete
reference page. Key additions: Where to find it section with screenshot,
full storage inventory section documenting all mount type/access/status
chips and the Linux owner display, expanded portability verdict section
with per-reason detail and edge-case caveats (read-only binds, symlink
escapes, anonymous volume risks), snapshot coverage section with admin
scope and remote-node behavior, Findings in Doctor cross-reference, and
six troubleshooting accordions covering tab visibility, bind status,
external named volumes, render errors, and snapshot coverage states.
Adds two production screenshots: storage-tab.png and storage-node-bound.png.

* docs(stack-labels): rewrite with accurate permissions, capability gate, dry run, live preview, and color conflict docs

* docs: rewrite Stack Sidebar page with accurate feature coverage

Rewrites the Stack Sidebar documentation page to match the current UI.

Key changes:
- Fix branding header description (shows logo + version, not just version)
- Fix bulk mode icon description (stacked-rows, not square)
- Add cross-node search section (fan-out behavior, Other nodes section,
  unreachable-node warnings, click-to-switch navigation)
- Update Labels submenu description (inline New label creation, Manage labels link)
- Note that Delete only appears when the user has delete permission
- Remove the auto-update implication from Schedule task description
- Rewrite the Activity ticker section with the full 6-state priority cascade
  table; remove the non-existent IDLE state; correct pulsing-dot behavior
- Replace all 7 stale screenshots with fresh production screenshots
- Add new sidebar-cross-node-search.png screenshot

* docs(atomic-deployments): refresh screenshot and document project env files, rollback readiness, and recovery actions

* docs(atomic-deployments): fix rollback permission visibility and banner string accuracy

The Rollback menu entry is hidden by the frontend when the user lacks
stack:deploy; it never appears and does not 403. Fixed the step-4
narrative and troubleshooting accordion to match.

The rollback-failure banner emitted by ComposeService is
'=== Rollback failed. Manual intervention may be required ==='
(period, capital M). Fixed both occurrences in the page.

Updated the Settings navigation path from the nonexistent
'Roles & Access' to the real 'Access'.

* docs(deploy-progress): rewrite with health gate, inline style, and 9 fresh screenshots

Add health gate section covering all four states (observing, passed, failed,
unknown) with exact UI banner text and the configurable observation window.
Expand the inline style section with full band content, 4s auto-dismiss, and
pill handoff. Add Scanning as a supported entry point. Replace all 6 existing
screenshots and add 3 new ones (modal-health-gate, inline-banner, setting-style).
Add two health gate troubleshooting accordions. Add Related CardGroup linking to
health-gated-updates, stack-activity, deploy-enforcement, and atomic-deployments.

* docs(health-gated-updates): refresh screenshots and correct signal row order and label

* docs(deploy-enforcement): rewrite with fleet replication, honor suppressions location, scan-failed dialog state, and fresh screenshots

Adds the Fleet policy replication section covering control/replica behavior,
Managed by control node banner, and Demote to control. Documents the exact
location of the Honor suppressions toggle (bottom of Policies tab). Expands
the block dialog section with the scan-failed row state. Updates all three
screenshots to the current visual design. Restores the Admiral license note
and corrects the policy-card scope description.

* docs(app-store): rewrite with mobile layout, fresh screenshots, and registry admin note

- Replace all 5 stale screenshots with 1920x1080 production captures
- Add app-store-mobile.png showing the status masthead layout
- Document mobile single-column layout in a new Mobile subsection
- Note that the featured hero has its own Deploy button
- Mark the category rail as desktop only with a cross-link to Mobile
- Add admin-account requirement to the custom registry section
- Add Related CardGroup linking vulnerability scanning, deploy progress, deploy enforcement, and resources

docs/getting-started/configuration.mdx

@@ -3,7 +3,9 @@ title: Configuration
 description: Environment variables, volume mounts, and the 1:1 path rule.
 ---
 
-Sencho is configured entirely through environment variables and Docker volume mounts. There is no config file to edit inside the container.
+Sencho's deployment is configured through environment variables and Docker volume mounts set on the Sencho container itself: there is no config file to edit inside the container. This page covers that deployment layer.
+
+Operational settings (host alerts, data retention, image-update automation, mesh networking, registries, notifications, and more) are configured in the app after first boot, in the Settings Hub. See the [Settings Reference](/reference/settings) for that runtime layer.
 
 ## Required environment variables
 
@@ -29,7 +31,20 @@ When you point `COMPOSE_DIR` at a directory, Sencho expects each stack to live i
 | `SENCHO_USER` | *(unset)* | When set to a username present inside the container (`sencho` is pre-created for this purpose), the entrypoint drops privileges to that user at startup instead of running as `root`. See [Running as a non-root user](#running-as-a-non-root-user) below. |
 | `API_RATE_LIMIT` | `200` | Global API requests per minute per user session. Applies in production only; development uses a fixed higher cap. Authenticated requests are keyed by user ID, unauthenticated by IP. Internal node-to-node traffic bypasses this limit. |
 | `API_POLLING_RATE_LIMIT` | `300` | Rate limit for dashboard polling endpoints, in requests per minute. Applies in production only; development uses a fixed higher cap. Raise it for environments with many concurrent browser sessions behind shared NAT. |
-| `SENCHO_COMPOSE_STALL_TIMEOUT_MS` | `600000` | Idle-output backstop for deploy and update compose steps (pull and recreate). If a step produces no output for this long while still running, Sencho treats it as stalled and stops it, so a hung image pull surfaces a clear failure and the in-app recovery actions instead of spinning. Raise it on slow links or for heavy local image builds. |
+
+## Advanced environment variables
+
+These tune optional subsystems. Most deployments never set them; the defaults are sensible.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TRIVY_BIN` | *(unset)* | Path to a host-installed [Trivy](/operations/trivy-setup) binary for image vulnerability scanning. Sencho prefers a managed install under `DATA_DIR/bin/trivy`, then this path, then `trivy` on `PATH`. |
+| `SENCHO_MESH_SUBNET` | *(auto)* | CIDR for this node's `sencho_mesh` network. When unset, Sencho picks the first free `/24` from its candidate list or adopts an existing mesh subnet. Set one only to avoid an overlap with another network on the host. See [Sencho Mesh](/features/sencho-mesh). |
+| `GITSOURCE_MAX_CLONE_BYTES` | `104857600` | Maximum bytes a single [Git Source](/features/git-sources) clone may download before it is aborted (100 MB). A shallow Compose clone is tiny; raise it only if you track Compose files in a legitimately large repository. |
+| `SENCHO_PUBLIC_URL` | *(request host)* | Set on the primary instance. Its externally reachable `http(s)://` URL, no trailing slash, baked into pilot enrollment so remote agents dial the public hostname rather than the address the admin used at setup. |
+| `SENCHO_COMPOSE_STALL_TIMEOUT_MS` | `600000` | Idle-output backstop for deploy and update Compose steps (pull and recreate). If a step produces no output for this long while still running, Sencho stops it so a hung image pull surfaces a clear failure and the in-app recovery actions instead of spinning. Raise it on slow links or for heavy local image builds. |
+
+Running a remote host as a pilot agent uses four more variables (`SENCHO_MODE`, `SENCHO_PRIMARY_URL`, `SENCHO_ENROLL_TOKEN`, and `SENCHO_PILOT_CA_FILE`), set only on the remote agent container. Sencho bakes them into the enrollment Compose file it generates, so you rarely write them by hand. See [Pilot Agent](/features/pilot-agent) for the full enrollment walkthrough.
 
 ## Listen port
 

docs/getting-started/introduction.mdx

@@ -34,7 +34,7 @@ The **Home** view is the default landing page. It is designed for a fast operati
 - The activity panel shows **Fleet Heartbeat** when remote nodes exist, or **Stack Restarts (7d)** on a local-only install.
 - **Recent Alerts** shows the latest notification feed and includes **Clear All Notifications** when there is anything to clear.
 
-The top navigation includes **Home**, **Fleet**, **Resources**, **App Store**, and **Logs** on the standard dashboard surface. Depending on license, role, and node context, it can also include **Update**, **Schedules**, **Console**, and **Audit**.
+The top navigation strip starts with **Home**, **Fleet**, **Resources**, **Security**, and **App Store**. Additional operator views (**Logs**, **Update**, **Schedules**, **Console**, and **Audit**) appear based on your role and license tier. Fleet-wide views describe the control instance, so they are hidden while a remote node is active.
 
 ## Stack workspace
 
@@ -52,7 +52,7 @@ Opening a stack gives you the day-to-day workspace:
 - Running stacks expose **Restart**, **Stop**, and **Update**; stopped stacks expose **Start** and **Update**. The overflow menu holds less frequent actions such as rollback, config scan, and delete.
 - Container rows show health, uptime, published ports, live CPU and memory, network activity, logs, and service actions.
 - The logs panel can run in **Structured** mode or **Raw terminal** mode.
-- The right panel switches between **Anatomy** and **Activity**, with **Files** and **Edit** controls for browsing stack files and editing compose or env content.
+- The right panel provides tabs for **Anatomy**, **Activity**, **Dossier**, **Drift**, **Environment**, **Networking**, **Doctor**, and **Storage**, with **Files** and **Edit** controls for browsing stack files and editing compose or env content.
 
 ## Fleet operations
 
@@ -64,7 +64,7 @@ The **Fleet** view is the multi-node command center. The masthead summarizes onl
 
 The Fleet toolbar includes **Check Updates**, **Refresh**, and **Add node** for admins. The **Overview** tab supports search, sort, status filters, label filters, and a Grid or Topology view. Node cards show online state, resource use, container counts, version state, update actions, and direct drill-down into stacks on that node.
 
-Fleet also provides dedicated tabs for snapshots, node status, blueprint deployments, traffic management, federation, fleet actions, and secrets. Some fleet features require Admiral. See [Licensing](/features/licensing) for the full tier breakdown.
+Beyond **Overview**, Fleet provides tabs for **Snapshots**, node **Status**, a dependency **Map**, blueprint **Deployments**, mesh **Routing**, **Federation**, fleet **Actions**, and **Secrets**. Some fleet tabs require Admiral. See [Licensing](/features/licensing) for the full tier breakdown.
 
 ## Resources, templates, and logs
 
@@ -78,11 +78,21 @@ The **App Store** lets you search templates, filter by category, open a deploy s
 
 The **Logs** view aggregates logs across stacks on the active node. It includes a live masthead, event counters, search, stack filters, stream filters, level filters, pause and resume controls, and download support for the filtered buffer.
 
-## Settings and security
+## Security
 
-Settings are grouped by **Personal**, **Access**, **Infrastructure**, **Monitoring**, **Notifications**, **Automation**, **Organization**, **Security**, **Operations**, and **Help**. Some sections are global to the control instance, while others are scoped to the active node.
+The **Security** view is a node-scoped review surface for the container images on the active node. The masthead reports the overall posture, how many images have been scanned, and whether the scanner is installed.
 
-Use Settings to manage account security, licensing, users, SSO, API tokens, host thresholds, node registration, alert delivery, security scanning, template registry settings, diagnostics, and build metadata. The [Configuration](/getting-started/configuration) guide covers the host and environment settings that matter before first deploy.
+<Frame>
+  <img src="/images/introduction/security-overview.png" alt="Sencho Security view with the posture masthead, action summary, review queue, risk trend chart, and the tab strip" />
+</Frame>
+
+Tabs cover the **Overview** charts, per-image findings under **Images**, **Compose risks** read from your Compose files, embedded **Secrets** detection, deploy-blocking **Policies**, **Suppressions** for findings you have accepted, scan **History**, and **Scanner setup**. Scanning is powered by Trivy and installs from **Scanner setup** in one step. See [Vulnerability Scanning](/features/vulnerability-scanning) for the full workflow.
+
+## Settings
+
+Settings are grouped by **Personal**, **Access**, **Infrastructure**, **Monitoring**, **Notifications**, **Automation**, **Organization**, **Operations**, and **Help**. Some groups are global to the control instance, while others, such as **Monitoring**, are scoped to the active node.
+
+Use Settings to manage account security, licensing, users, SSO, API tokens, host thresholds, node registration, alert delivery, template registry settings, diagnostics, and build metadata. The [Configuration](/getting-started/configuration) guide covers the host and environment settings that matter before first deploy.
 
 ## Typical workflow
 

docs/getting-started/quickstart.mdx

@@ -82,7 +82,7 @@ The Compose directory must be mounted at the **same path** inside and outside th
 Open `http://localhost:1852` in a browser. On a fresh install you land on the **Cold start** card, where Sencho asks you to create the first admin account.
 
 <Frame>
-  <img src="/images/quickstart/setup-cold-start.png" alt="Sencho first-boot Cold start card with Username, Password, and Confirm password fields, and an Initialize console button" />
+  <img src="/images/quickstart/setup-cold-start.png" alt="Sencho first-boot Cold start card with Username, Password, and Confirm password fields, a password strength indicator, and an Initialize console button" />
 </Frame>
 
 Pick a username, choose a password, confirm it, and click **Initialize console**. The username placeholder shows `admin`. The password must be at least eight characters, and the strength indicator labels the password **Weak**, **Fair**, or **Strong** as you type.
@@ -90,7 +90,7 @@ Pick a username, choose a password, confirm it, and click **Initialize console**
 Sencho then runs a short **environment preflight**: it confirms the Docker engine and Compose plugin are reachable, the compose directory is writable and mounted at a matching host path, the dashboard is behind TLS, and there is disk headroom. Anything that needs attention shows an inline fix. The checks never block you, so click **Enter Sencho** to continue; you can re-run them anytime from **Settings · Recovery**.
 
 <Frame>
-  <img src="/images/quickstart/setup-environment.png" alt="Sencho first-boot environment preflight with check rows for Docker engine, Docker Compose, Compose directory, path mapping, TLS, and disk space, each showing an OK or warning result, a Re-run button, and an Enter Sencho button" />
+  <img src="/images/quickstart/setup-environment.png" alt="Sencho first-boot environment preflight with check rows for Docker engine, Docker Compose, Compose directory, path mapping, TLS, and disk space, each showing a pass or warning status with inline remediation text, a Re-run button, and an Enter Sencho button" />
 </Frame>
 
 <Note>
@@ -99,15 +99,15 @@ Sencho then runs a short **environment preflight**: it confirms the Docker engin
 
 ## After signing in
 
-You land on **Home**, the default operational view. The health masthead reports **Healthy**, **Degraded**, or **Critical**, names the active node, shows how many nodes are registered, and lists any signals that need attention. The resource gauge strip tracks **CPU**, **Memory**, **Disk**, and **Network**. **Stack health** lists discovered stacks on the active node, sorted so exited or high-load stacks rise to the top.
+You land on **Home**, the default operational view. The health masthead reports **Healthy**, **Degraded**, or **Critical**, names the active node, shows how many nodes are registered, and lists any signals that need attention. The resource gauge strip tracks **CPU**, **Memory**, **Disk**, and **Network** with sparklines and threshold coloring. **Stack health** lists the active node's stacks, sorted by state then load, with uptime, CPU, memory, and a 10-minute CPU sparkline per row.
 
 <Frame>
-  <img src="/images/quickstart/dashboard.png" alt="Sencho Home view with the health masthead, CPU, Memory, Disk, and Network gauges, Stack health, Configuration Status, an activity panel, and Recent Alerts" />
+  <img src="/images/quickstart/dashboard.png" alt="Sencho Home view with the health masthead, resource gauges with sparklines, Stack health table, Configuration Status, Fleet Heartbeat panel, and Recent Alerts" />
 </Frame>
 
-Below the stack table, **Configuration Status** summarizes notification delivery, alert rules, automation, account security, backups, host thresholds, and crash detection. The neighboring activity card shows **Fleet Heartbeat** when remote nodes exist, or **Stack Restarts (7d)** on a local-only install. **Recent Alerts** shows the latest notification feed and includes **Clear All Notifications** when there is anything to clear.
+Below the stack table, **Configuration Status** summarizes notifications, alerts, automation, security, backups, thresholds, and crash detection. The neighboring activity card shows **Fleet Heartbeat** when remote nodes exist, or **Stack Restarts (7d)** on a local-only install. **Recent Alerts** shows the latest notification feed and includes **Clear All Notifications** when there is anything to clear.
 
-On the local node, the top navigation includes **Home**, **Fleet**, **Resources**, **App Store**, and **Logs**. Depending on license, role, and node context, it can also include **Update**, **Schedules**, **Console**, and **Audit**; hub-only views are hidden when a remote node is active. The right side of the top bar holds global search, notifications, and the profile menu entries **Settings**, **Documentation**, **Feedback**, **Appearance**, and **Log Out**.
+On the local node, the top navigation includes **Home**, **Fleet**, **Resources**, **Security**, **App Store**, and **Logs**. Depending on license, role, and node context, it can also include **Update**, **Schedules**, **Console**, and **Audit**; hub-only views are hidden when a remote node is active. The right side of the top bar holds global search, notifications, and the profile menu entries **Settings**, **Documentation**, **Feedback**, **Appearance**, and **Log Out**.
 
 The left sidebar is the stack workspace. Below the Sencho brand, it starts with the node switcher, then **Create Stack**, a bulk-mode toggle, and **Scan stacks folder** for importing Compose projects added outside Sencho. Use **Search stacks...** with the **All**, **Up**, **Down**, and **Updates** chips to narrow the list. On a fresh install the stack list is empty until you create a stack or scan a populated `COMPOSE_DIR`.
 

docs/getting-started/sso-quickstart.mdx

@@ -3,22 +3,28 @@ title: SSO Setup Guide
 description: Step-by-step instructions for connecting Sencho to your identity provider.
 ---
 
-SSO can be configured from the Settings UI or seeded via environment variables (shown below).
+SSO is configured from the dashboard at **Settings → Access → SSO** (admin only) or seeded via environment variables (shown below).
 
 <Note>
   **Tier availability.** Custom OIDC and the Google, GitHub, and Okta preset providers are available on every tier, including Community. LDAP / Active Directory requires Admiral. See [Licensing & Billing](/features/licensing#feature-breakdown) for the full breakdown.
 </Note>
 
 <Frame>
-  <img src="/images/sso/sso-quickstart-overview.png" alt="Settings > SSO panel showing all five provider cards with PROVIDERS and ENABLED stats in the masthead" />
+  <img src="/images/sso/sso-quickstart-overview.png" alt="Settings → Access → SSO panel: five provider cards (Custom OIDC, Google, GitHub, Okta, LDAP / Active Directory) with PROVIDERS and ENABLED counts in the masthead" />
 </Frame>
 
+Each provider is a collapsible card you switch on, fill in, and test in place. The masthead tracks how many providers are configured (**PROVIDERS**) and how many are switched on (**ENABLED**).
+
+<Note>
+  **What your users see.** Once a provider is enabled, it appears on the login page. The OIDC providers (Custom OIDC, Google, GitHub, Okta) show up as buttons under an **Or continue with** divider; LDAP adds a **Local / LDAP** toggle beside the **Sign in** heading. Password sign-in stays available alongside the SSO options.
+</Note>
+
 ## How to configure
 
 You can wire SSO two ways. Both reach the same database row, and you can mix and match.
 
 - **Environment variables** seed the SSO configuration the first time Sencho boots with that variable set. They are useful for infrastructure-as-code, fresh deployments, and disaster recovery. After a configuration row exists in the database, the database is authoritative; subsequent restarts do not re-read the env vars or overwrite changes you made in the UI.
-- **Settings > SSO** in the dashboard lets admins enable, edit, save, and remove providers without restarting. Changes apply immediately. Each provider card has a **Test Connection** button that validates connectivity before you commit (LDAP bind plus search for LDAP, OIDC discovery plus token endpoint reachability for OIDC).
+- **Settings → Access → SSO** in the dashboard lets admins enable, edit, save, and remove providers without restarting. Changes apply immediately. Each provider card has a **Test Connection** button that validates connectivity before you commit (LDAP bind plus search for LDAP, OIDC discovery plus token endpoint reachability for OIDC).
 
 If you want a guided UI walkthrough rather than the env-var path below, jump to the [SSO feature page](/features/sso#configuration).
 
@@ -141,10 +147,10 @@ If your provider uses non-standard claim names, add claim mapping:
       - SSO_LDAP_DEFAULT_ROLE=viewer
 ```
 
-Once Sencho is running, open **Settings > SSO**, expand the LDAP card, and click **Test Connection**. Sencho binds with the service account, runs the search filter, and reports the result inline.
+Once Sencho is running, open **Settings → Access → SSO**, expand the LDAP card, and click **Test Connection**. Sencho binds with the service account, runs the search filter, and reports the result inline.
 
 <Frame>
-  <img src="/images/sso/sso-quickstart-ldap-test.png" alt="LDAP provider card expanded showing the configuration form with example values, the Verify TLS certificate toggle, and Save and Test Connection buttons" />
+  <img src="/images/sso/sso-quickstart-ldap-test.png" alt="LDAP / Active Directory card expanded in the SSO panel, showing the configuration form with example values, the Verify TLS certificate toggle, the Save and Test Connection buttons, and an inline error indicator after a failed test" />
 </Frame>
 
 <Warning>
@@ -172,7 +178,7 @@ By default, all SSO users are assigned the **Viewer** role. To grant Admin to sp
 This tells Sencho to check the `groups` claim in the OIDC ID token. If it contains `sencho-admins`, the user gets Admin. Roles are synced on every login, so removing a user from the admin group will demote them on their next sign-in.
 
 <Note>
-  Some providers (e.g., Okta, Zitadel) require custom scopes to include group claims in the ID token. You can configure additional scopes in the **Scopes** field in Settings > SSO, or via environment variable. The default is `openid email profile`.
+  Some providers (e.g., Okta, Zitadel) require custom scopes to include group claims in the ID token. You can configure additional scopes in the **Scopes** field in Settings → Access → SSO, or via environment variable. The default is `openid email profile`.
 </Note>
 
 ## Full docker-compose.yml example with SSO