docs: Self review of doc pages

docs/operations/upgrading.md

@@ -5,7 +5,7 @@ sidebar_label: Upgrading
 ---
 
 Upgrading the control plane is a pull and a recreate. Agents are versioned and
-upgraded separately see [Agent updates](./agent-updates.md).
+upgraded separately. See [Agent updates](./agent-updates.md).
 
 :::info Cloud instances upgrade themselves
 This page is for self-hosted installs. If your instance is hosted by us, there
@@ -26,11 +26,11 @@ renamed or removed.
 
 ## What happens on boot
 
-1. **Migrations** run, recording markers so each runs once.
-2. **Indexes** are ensured. Auth and settings index builders are fatal on
-   failure; secret and workflow ones only warn.
-3. **Default steps** are reseeded from the image, overwriting the `default`
-   library which is why those steps are read-only.
+1. The database is brought up to date. Each change runs once.
+2. The built-in workflow steps are reinstalled, which is why those steps cannot
+   be edited.
+
+If Vantage cannot complete either safely, it stops rather than run half-prepared.
 
 Watch it:
 
@@ -46,6 +46,16 @@ docker compose logs -f server
 - **Check your `.env`** still supplies everything required. A newly required
   variable stops the boot rather than defaulting to something unsafe.
 
+## Single sign-on after an upgrade
+
+Each identity provider now has its own callback URL. If you configured single
+sign-on on an older version it was carried over, but its callback URL changed,
+and sign-in through it fails until you copy the new one from its card in
+**Settings** and register it with your identity provider. The card shows a
+reminder until you dismiss it.
+
+Password sign-in is unaffected, so you can always sign in locally to fix this.
+
 ## Downgrading
 
 There is no automatic downgrade. Migrations do not roll back, so returning to an
@@ -57,7 +67,7 @@ is the reason the backup is not optional.
 The stack is not designed for it. `docker compose up -d` recreates the server
 container, which is a short interruption:
 
-- Agents reconnect on their own they retry, and the poll loop is idempotent.
+- Agents reconnect on their own.
 - Workflow runs in progress lose their command stream. Steps already dispatched
   finish on the agent, but their results have nowhere to go. **Do not upgrade
   during a run.**
@@ -67,5 +77,4 @@ container, which is a short interruption:
 
 - Confirm every service is `running`.
 - Confirm servers return to `active` within a couple of poll intervals.
-- Open a page that touches encryption a secret group to confirm
-  `KEY_ENCRYPTION_KEY` came through.
+- Open a secret group, to confirm `KEY_ENCRYPTION_KEY` came through.