docs(upgrades): align Upgrades page with feature spec

content/docs/en/upgrades.mdx

@@ -10,7 +10,7 @@ import { FiExternalLink } from "react-icons/fi";
 
 # Upgrades
 
-Upgrades lets you schedule and monitor infrastructure version upgrades across all your accounts from a single place. View pending and completed upgrades, track execution dates, and keep your environments up to date without losing visibility.
+Upgrades is where SleakOps surfaces infrastructure changes the platform plans to apply to your accounts — version bumps, configuration updates, resource reorganizations. You can review what's scheduled for your company, read the manual steps each one requires, trigger an upgrade ahead of its scheduled date, or move it inside the allowed window.
 
 <Zoom overlayBgColorEnd="rgba(255, 255, 255, 0.8)">
   <img
@@ -19,65 +19,176 @@ Upgrades lets you schedule and monitor infrastructure version upgrades across al
   />
 </Zoom>
 
-:::info Beta
-Upgrades is currently in **Beta**. Core scheduling and monitoring are stable; advanced configuration options are still being added.
+:::info
+Upgrades are created by SleakOps. Customers cannot create upgrade types or schedule new upgrades from the panel — you act on the ones SleakOps queues for your accounts.
 :::
 
+## Where to find Upgrades
+
+Upgrades live at `/upgrades/` and have a dedicated entry in the sidebar footer, next to the notifications button. The entry is visible to **Admin** and **Editor** users; Viewers can still reach the page directly via URL when their company has the feature enabled.
+
+When at least one upgrade is **Pending** for your company, the sidebar icon turns red, animates briefly, and displays a counter with the number of pending upgrades across every account.
+
+## Reading the Upgrades list
+
+The list always shows upgrades across **every account you can access**, regardless of the account currently selected in the top bar. Admins see the whole company; Editors and Viewers see the upgrades for the accounts they've been assigned to.
+
+| **Column** | **Description** |
+|---|---|
+| **Upgrade** | The upgrade title and its current state. When the upgrade targets a specific resource (a Cluster, a NodePool, a Service), its model icon and name are shown directly under the title. |
+| **Account** | The account the upgrade will run against. |
+| **Execution Date** | Relative time — **scheduled date** while the upgrade is Pending, **actual execution time** for every other state. Hover the value to see the exact timestamp. |
+| **Actions** | View details, Execute, and (when applicable) Review instructions. |
+
+Pending rows are tinted a subtle red to make outstanding work easier to scan at a glance. The same red is reused on the state pill and the sidebar badge — it's the single visual cue SleakOps uses for "deadline-bound action required".
+
+Filter the list by **State** (Pending, In Progress, Completed, Error), **Account**, or **Model** (the type of resource the upgrade targets) from the toolbar at the top of the table. Deep links from other sections (for example, from a specific Cluster) arrive with the relevant filter pre-applied.
+
+## States
+
+| **State** | **Meaning** |
+|---|---|
+| **Pending** | Scheduled but not yet started. You can execute it now or move its scheduled date. |
+| **Running** | Execution is in progress. The upgrade can't be cancelled or rescheduled. |
+| **Completed** | Finished successfully. No further action needed. |
+| **Error** | Execution failed. The error is shown in the drawer and you can retry from the panel without waiting for SleakOps. |
+
+Transitions: `Pending → Running → Completed`. From `Running`, on failure, the upgrade lands in `Error`; from `Error` you can retry, which moves it back to `Running`.
+
+## Executing an upgrade
+
+You can execute a Pending or Error upgrade in two ways:
+
+1. **From the list** — click the green play icon in the row's Actions column.
+2. **From the drawer** — open the upgrade and click the **Execute** button in the header. A popover lets you pick **Execute Now** or update the schedule.
+
+<Zoom overlayBgColorEnd="rgba(255, 255, 255, 0.8)">
+  <img
+    src={require("./upgrades/upgrades-execute-popover.png").default}
+    alt="execute-popover"
+  />
+</Zoom>
+
+Choosing **Execute Now** opens a confirmation modal. When the upgrade has prerequisites, they appear as a warning banner inside the modal — finish those manual steps before confirming.
+
+{/* TODO: screenshot - execute confirmation modal with the prerequisites warning banner. Requires a MigrationType with prerequisites set. */}
+
+The Execute button is disabled when any of the following applies:
+
+- Your role isn't authorized for this upgrade type.
+- The upgrade is already Running or Completed.
+- An **older Pending upgrade of a different type** exists on the same account — that one needs to clear first.
+- Your company's subscription is not active (the upgrade is locked).
+
+Once Execute Now is confirmed, the upgrade is queued immediately and can't be stopped.
+
+## Rescheduling an upgrade
+
+Admins and Editors can move the scheduled date for a Pending or Error upgrade. Open the drawer, click **Execute** in the header, and use the **Schedule** section of the popover — or click the schedule block inside the **Details** tab.
+
+<Zoom overlayBgColorEnd="rgba(255, 255, 255, 0.8)">
+  <img
+    src={require("./upgrades/upgrades-drawer.png").default}
+    alt="upgrades-drawer-details"
+  />
+</Zoom>
+
+The new date must fall inside `[now + 1 hour, deadline]`. The deadline is the **Limit Date** of the upgrade type — the day after which SleakOps considers the upgrade overdue. The picker disables anything outside that window.
+
+Cross-type ordering is enforced when you reschedule:
+
+- You can't push the date **before** another older Pending upgrade of a different type on the same account.
+- You can't push the date **after** a newer Pending upgrade of a different type on the same account.
+
+Upgrades **of the same type** on the same account don't constrain each other — you can reorder them freely.
+
+## The Upgrade drawer
+
+Click any row to open the drawer. It has two tabs:
+
+### Details
+
+- **Basic Information** — entity name (when the upgrade targets a specific resource), upgrade type, account, description, state.
+- **Schedule** — Execution Date and Deadline (Limit Date). Click the section to edit the schedule inline when your role allows it.
+- **Metadata** — creation date and any parameters attached to the upgrade.
+- **Activity Logs** — the audit trail for this upgrade (executions, schedule changes), with the user and timestamp of each action.
+
+### Instructions
+
+Only present when the upgrade type ships prerequisites or postrequisites:
+
+- **Prerequisites** — numbered steps to complete before executing.
+- **Post-Execution Steps** — steps to verify after the upgrade completes.
+
+While the upgrade is Pending, the **Instructions** tab label turns orange to remind you to read it before clicking Execute. From the list, a list icon next to the Execute button in the Actions column jumps straight into this tab.
+
+{/* TODO: screenshot - drawer with Instructions tab open showing numbered prerequisites and post-execution steps. Requires a MigrationType with prerequisites/postrequisites set. */}
+
+## Permissions
+
+| **Action** | **Admin** | **Editor** (assigned accounts) | **Viewer** (assigned accounts) |
+|---|---|---|---|
+| See upgrades | Yes | Yes | Yes |
+| Execute an upgrade | Yes | Yes | No |
+| Reschedule an upgrade | Yes | Yes | No |
+
+Each upgrade type can further restrict who's allowed to execute or reschedule it — Viewers are never permitted. When your role isn't authorized for a given upgrade, the action controls are disabled and a tooltip explains why.
+
+## When an upgrade fails
+
+When the SleakOps team rolls out an upgrade, every notable event — start, completion, failure — drops a notification in your in-app inbox. On failure, the upgrade enters the **Error** state, the drawer shows the error message at the top of the Details tab, and the SleakOps team is paged automatically.
+
+You don't have to wait for SleakOps to act. Open the upgrade, read the error, and click **Execute** again from the drawer. The retry runs the same upgrade with the same parameters. Once the underlying issue is fixed, the retry will succeed.
+
+SleakOps doesn't perform automatic rollbacks. If an upgrade needs to be undone, contact support.
+
 ## FAQs
 
 <details>
 <summary>
-### Where do I find Upgrades?
+### Why can't I create an upgrade?
 </summary>
-Upgrades is accessible directly from the main sidebar under **Upgrades** (`/migrations/`). It is also reachable from **Settings → Upgrades**.
-
-The page shows a table with all scheduled and completed upgrades, filtered by account.
+SleakOps defines and schedules upgrades centrally. You see the upgrades the platform queues for your accounts and decide **when** within the allowed window — execute immediately or push the date inside `[now, deadline]`. Creating upgrade types is reserved for the SleakOps team.
 </details>
 
 <details>
 <summary>
-### What information does the Upgrades table show?
+### Can I cancel a scheduled upgrade?
 </summary>
-Each row in the table shows:
-
-| **Column** | **Description** |
-|---|---|
-| **Upgrade** | The type of upgrade being applied |
-| **Account** | The account the upgrade targets |
-| **Execution Date** | When the upgrade is scheduled to run |
-| **Actions** | Available actions for that upgrade |
-
-Use the **Select an account** filter at the top left to narrow results to a specific account.
+No. Cancellation isn't available — every queued upgrade will eventually run. What you can do is reschedule it inside the allowed window or, once the deadline approaches, execute it ahead of time at a moment that fits your maintenance window. If a specific change is no longer relevant for your account, contact the SleakOps team.
 </details>
 
 <details>
 <summary>
-### How do I schedule an upgrade?
+### What's the difference between "Pending" and "Running"?
 </summary>
-Use the search bar (⌘K) or the **Upgrade** button at the top of the list to create a new scheduled upgrade. Select the target account and set the execution date.
-
-{/* TODO: screenshot - New upgrade form showing account selection and execution date picker */}
+**Pending** means the upgrade is queued but hasn't started yet — you still have control over the timing. **Running** means execution has begun and the platform owns the operation; it can't be cancelled or rescheduled from this point on.
 </details>
 
 <details>
 <summary>
-### Can I upgrade multiple environments at once?
+### My upgrade is locked — what does "scheduling locked" mean?
 </summary>
-You can schedule upgrades across multiple accounts and environments, but upgrades run sequentially by default to reduce blast radius. The recommended flow is to upgrade staging first, validate the result, and then schedule production.
+When a company doesn't have an active SleakOps subscription, its upgrades are kept in the list for audit but cannot be executed or rescheduled. A warning banner is shown inside the drawer. Reactivate the subscription to unlock them.
 </details>
 
 <details>
 <summary>
-### What happens during an upgrade?
+### Why is Execute disabled even though the upgrade is Pending?
 </summary>
-SleakOps upgrades resources in a controlled sequence to minimize downtime. If a step fails, the upgrade halts and the console surfaces the error with context on what to do next.
+A few reasons can disable the Execute button: your role isn't authorized for this upgrade type, the company subscription isn't active, or there's an **older Pending upgrade of a different type** on the same account that needs to complete first. Hover the button to see which case applies.
+</details>
 
-For cluster upgrades the sequence is: control plane first, then node groups one at a time — existing workloads are drained and rescheduled before each node is replaced.
+<details>
+<summary>
+### How do I see who executed or rescheduled an upgrade?
+</summary>
+Open the drawer's **Details** tab and scroll to **Activity Logs**. Every execution and every schedule change is recorded with the acting user and timestamp.
 </details>
 
 <details>
 <summary>
-### Can I cancel a scheduled upgrade?
+### Are upgrades the same as Django database migrations?
 </summary>
-Yes. Scheduled upgrades that have not yet started can be cancelled from the Actions column in the Upgrades table. Once an upgrade is in progress it cannot be rolled back automatically — contact support if you need to stop an active upgrade.
+No. "Upgrades" here refers to **infrastructure changes** SleakOps applies to your AWS/Kubernetes resources — version bumps, configuration updates, resource reorganizations. Application-level database migrations belong to your codebase and run as part of your deployments.
 </details>