RenewCMS/docs/design/states.md

# State matrix and error copy

Every state is drawn at desktop and mobile on the screen boards, with final copy. Each screen's file in `screens/` has the full copy per state.

| Screen | Route | State | Trigger | Spec |
|---|---|---|---|---|
| App boot | `any verified route` | Checking session | First navigation, while GET /v1/auth/me is pending | [boot](screens/boot.md) |
| App boot | `any verified route` | Verified | 200 with is_verified: the route renders | [boot](screens/boot.md) |
| App boot | `any verified route` | Unverified | 200 with is_verified false: goes to /register/pending | [boot](screens/boot.md) |
| App boot | `any verified route` | No session | 401: goes to /login?redirect= | [boot](screens/boot.md) |
| Log in | `/login` | Default | Registration closed | [log-in](screens/log-in.md) |
| Log in | `/login` | Fresh install | registration.open is true | [log-in](screens/log-in.md) |
| Log in | `/login` | Validation errors | Client rules fail on submit | [log-in](screens/log-in.md) |
| Log in | `/login` | Submitting | Request in flight | [log-in](screens/log-in.md) |
| Log in | `/login` | Wrong credentials | 403 | [log-in](screens/log-in.md) |
| Log in | `/login` | Too many attempts | 429 with Retry-After | [log-in](screens/log-in.md) |
| Log in | `/login` | Session expired | ?reason=expired from a 401 | [log-in](screens/log-in.md) |
| Log in | `/login` | Password changed | ?reason=password-changed | [log-in](screens/log-in.md) |
| Log in | `/login` | Server error | 500 or network | [log-in](screens/log-in.md) |
| Register | `/register` | Default | Open instance | [register](screens/register.md) |
| Register | `/register` | Validation errors | Client rules fail | [register](screens/register.md) |
| Register | `/register` | Submitting | In flight | [register](screens/register.md) |
| Register | `/register` | Registration closed | 403 | [register](screens/register.md) |
| Register | `/register` | Server error | 500 or network | [register](screens/register.md) |
| Pending | `/register/pending` | Default | After registering (email known) | [pending](screens/pending.md) |
| Pending | `/register/pending` | Email unknown | After logging in unverified | [pending](screens/pending.md) |
| Pending | `/register/pending` | Confirm cancel | Cancel registration clicked | [pending](screens/pending.md) |
| Pending | `/register/pending` | Cancelling | DELETE in flight | [pending](screens/pending.md) |
| Pending | `/register/pending` | Cancelled | 200: /register with toast | [pending](screens/pending.md) |
| Pending | `/register/pending` | Already verified | 403: /home with toast | [pending](screens/pending.md) |
| Verify | `/register/validate?c=` | Verifying | On load | [verify](screens/verify.md) |
| Verify | `/register/validate?c=` | Success | 200: /home with toast | [verify](screens/verify.md) |
| Verify | `/register/validate?c=` | Invalid or expired | 403 | [verify](screens/verify.md) |
| Verify | `/register/validate?c=` | No session | 401: inline log in, then retry | [verify](screens/verify.md) |
| Verify | `/register/validate?c=` | Missing code | No c parameter | [verify](screens/verify.md) |
| Forgot password | `/register/reset/request` | Default | Page load | [forgot-password](screens/forgot-password.md) |
| Forgot password | `/register/reset/request` | Validation | Invalid email | [forgot-password](screens/forgot-password.md) |
| Forgot password | `/register/reset/request` | Submitting | In flight | [forgot-password](screens/forgot-password.md) |
| Forgot password | `/register/reset/request` | Sent | Any 200 (neutral copy) | [forgot-password](screens/forgot-password.md) |
| Forgot password | `/register/reset/request` | Too many attempts | 429 | [forgot-password](screens/forgot-password.md) |
| Forgot password | `/register/reset/request` | Server error | 500 or network | [forgot-password](screens/forgot-password.md) |
| Reset password | `/register/reset/validate` | Default | c and email present | [reset-password](screens/reset-password.md) |
| Reset password | `/register/reset/validate` | Too short | Under 8 characters | [reset-password](screens/reset-password.md) |
| Reset password | `/register/reset/validate` | Mismatch | Confirm field differs | [reset-password](screens/reset-password.md) |
| Reset password | `/register/reset/validate` | Submitting | In flight | [reset-password](screens/reset-password.md) |
| Reset password | `/register/reset/validate` | Success | 200: /login?reason=password-changed | [reset-password](screens/reset-password.md) |
| Reset password | `/register/reset/validate` | Invalid or expired | 403 | [reset-password](screens/reset-password.md) |
| Reset password | `/register/reset/validate` | Missing parameters | No c or no email | [reset-password](screens/reset-password.md) |
| Home | `/home` | Loading | List in flight (after 150 ms) | [home](screens/home.md) |
| Home | `/home` | Default | List loaded | [home](screens/home.md) |
| Home | `/home` | Empty | Zero articles | [home](screens/home.md) |
| Home | `/home` | Error | 500 or network | [home](screens/home.md) |
| Articles | `/article` | Loading | List in flight | [articles](screens/articles.md) |
| Articles | `/article` | Default | Loaded | [articles](screens/articles.md) |
| Articles | `/article` | Empty | Zero articles | [articles](screens/articles.md) |
| Articles | `/article` | No results | Search matches nothing | [articles](screens/articles.md) |
| Articles | `/article` | Empty tab | No drafts, or nothing online | [articles](screens/articles.md) |
| Articles | `/article` | Row busy | Publish or unpublish in flight | [articles](screens/articles.md) |
| Articles | `/article` | Action failed | 500 or network: toast with Retry | [articles](screens/articles.md) |
| Articles | `/article` | Row vanished | 404 on any row action | [articles](screens/articles.md) |
| Articles | `/article` | Delete confirm, in progress, failed, done | ConfirmDialog, then DELETE: 204 or 500 | [articles](screens/articles.md) |
| New article | `modal · /article/new` | Default | Opened | [new-article](screens/new-article.md) |
| New article | `modal · /article/new` | Validation | Title under 3 or body empty | [new-article](screens/new-article.md) |
| New article | `modal · /article/new` | Submitting | POST in flight | [new-article](screens/new-article.md) |
| New article | `modal · /article/new` | Title rejected | Server 400 | [new-article](screens/new-article.md) |
| New article | `modal · /article/new` | Error | 500 or network | [new-article](screens/new-article.md) |
| New article | `modal · /article/new` | Created | 201: editor, with a toast | [new-article](screens/new-article.md) |
| Editor | `/article/:id/edit` | Loading | GET in flight | [editor](screens/editor.md) |
| Editor | `/article/:id/edit` | Not found | 404 | [editor](screens/editor.md) |
| Editor | `/article/:id/edit` | Saved | Clean | [editor](screens/editor.md) |
| Editor | `/article/:id/edit` | Unsaved | Any edit | [editor](screens/editor.md) |
| Editor | `/article/:id/edit` | Saving | PATCH in flight | [editor](screens/editor.md) |
| Editor | `/article/:id/edit` | Save failed | 500 or network | [editor](screens/editor.md) |
| Editor | `/article/:id/edit` | Near the limit | At least 9 000 HTML characters | [editor](screens/editor.md) |
| Editor | `/article/:id/edit` | Too long | Over 10 000: Save and Publish disabled | [editor](screens/editor.md) |
| Editor | `/article/:id/edit` | Preview | Switch on | [editor](screens/editor.md) |
| Editor | `/article/:id/edit` | Choose, crop and resize, uploading, rejected, inserted | ImageUploader | [editor](screens/editor.md) |
| Editor | `/article/:id/edit` | Publishing, unpublishing | PATCH publish or unpublish | [editor](screens/editor.md) |
| Editor | `/article/:id/edit` | Leave guard | Navigating away while dirty | [editor](screens/editor.md) |
| Editor | `/article/:id/edit` | Offline | navigator.onLine is false | [editor](screens/editor.md) |
| Editor | `/article/:id/edit` | Deleted | 204: /article with toast | [editor](screens/editor.md) |
| Editor | `/article/:id/edit` | Session expired | 401: draft kept in sessionStorage, then /login | [editor](screens/editor.md) |
| Media | `/media` | Grid, many images | Default view | [media](screens/media.md) |
| Media | `/media` | Grid, few images | Three images | [media](screens/media.md) |
| Media | `/media` | List view | The list icon in the toggle | [media](screens/media.md) |
| Media | `/media` | Loading | The first load, a retry, or a change of search or filter | [media](screens/media.md) |
| Media | `/media` | Empty library, first run | Zero images | [media](screens/media.md) |
| Media | `/media` | No results | Search or filter matched nothing | [media](screens/media.md) |
| Media | `/media` | Hover, focus and keyboard | Hover (second item) darkens the border, adds the pop shadow and reveals the checkbox | [media](screens/media.md) |
| Media | `/media` | Selection and bulk bar | Checkbox on any item, or Space | [media](screens/media.md) |
| Media | `/media` | Bulk delete: confirm | Delete in the bulk bar | [media](screens/media.md) |
| Media | `/media` | Bulk delete: in progress | Requests in flight | [media](screens/media.md) |
| Media | `/media` | Bulk delete: partly failed | Some requests failed | [media](screens/media.md) |
| Media | `/media` | Bulk delete: done | 204 for all | [media](screens/media.md) |
| Media | `/media` | Detail panel: in use | Click or Enter on an item | [media](screens/media.md) |
| Media | `/media` | Detail panel: unused | Used in nothing | [media](screens/media.md) |
| Media | `/media` | Detail panel: duplicate | The image has identical copies | [media](screens/media.md) |
| Media | `/media` | Copy URL | Copy URL | [media](screens/media.md) |
| Media | `/media` | Rename: dialog | Rename in the panel | [media](screens/media.md) |
| Media | `/media` | Rename: saving | PATCH in flight | [media](screens/media.md) |
| Media | `/media` | Rename: validation | Empty or only symbols, on submit or blur | [media](screens/media.md) |
| Media | `/media` | Rename: failed | 500 or network failure | [media](screens/media.md) |
| Media | `/media` | Rename: done | 200: the panel title and list update in place | [media](screens/media.md) |
| Media | `/media` | Delete: unused image | Delete in the panel | [media](screens/media.md) |
| Media | `/media` | Delete: image in use | Stronger confirm | [media](screens/media.md) |
| Media | `/media` | Delete: in progress | DELETE in flight | [media](screens/media.md) |
| Media | `/media` | Delete: failed | 500 or network failure | [media](screens/media.md) |
| Media | `/media` | Delete: done | 204: the panel closes, the item leaves the grid and focus moves to the next item | [media](screens/media.md) |
| Media | `/media` | Image already gone (404) | Any action on an image that was deleted elsewhere | [media](screens/media.md) |
| Media | `/media` | Upload: drag over the page | Files dragged onto the page | [media](screens/media.md) |
| Media | `/media` | Upload: several files, mixed | Upload button or drop, several files | [media](screens/media.md) |
| Media | `/media` | Upload: summary | All rows settled | [media](screens/media.md) |
| Media | `/media` | Upload: rejected files (413, 400) | Type and size are checked in the browser first, so nothing is sent | [media](screens/media.md) |
| Media | `/media` | Upload: too many requests (429) | Rate limited | [media](screens/media.md) |
| Media | `/media` | Duplicates: groups | The Duplicates tab | [media](screens/media.md) |
| Media | `/media` | Duplicates: empty | No groups | [media](screens/media.md) |
| Media | `/media` | Merge: confirm | "Merge into this one" on floorboards.jpg | [media](screens/media.md) |
| Media | `/media` | Merge: in progress | Request in flight | [media](screens/media.md) |
| Media | `/media` | Merge: failed | 500 or network failure | [media](screens/media.md) |
| Media | `/media` | Merge: conflict (409) | A copy was deleted, or a new copy appeared, since the page loaded | [media](screens/media.md) |
| Media | `/media` | Merge: done | 200: the group leaves the list | [media](screens/media.md) |
| Media | `/media` | List failed to load | A 500 or network failure on the list request | [media](screens/media.md) |
| Media | `/media` | Offline | navigator.onLine is false | [media](screens/media.md) |
| Media picker | `/article/:id/edit` | Upload tab | The image button in the toolbar | [media-picker](screens/media-picker.md) |
| Media picker | `/article/:id/edit` | Upload tab: already in your library | A chosen file has the same content as an existing image | [media-picker](screens/media-picker.md) |
| Media picker | `/article/:id/edit` | Library: loading | The Library tab was opened, or a search changed | [media-picker](screens/media-picker.md) |
| Media picker | `/article/:id/edit` | Library: nothing selected | Newest first | [media-picker](screens/media-picker.md) |
| Media picker | `/article/:id/edit` | Library: selected | One image selected (single selection) | [media-picker](screens/media-picker.md) |
| Media picker | `/article/:id/edit` | Library: alt text entered | Alt text is optional | [media-picker](screens/media-picker.md) |
| Media picker | `/article/:id/edit` | Library: loading more | "Load more" pressed | [media-picker](screens/media-picker.md) |
| Media picker | `/article/:id/edit` | Library: empty | Zero images | [media-picker](screens/media-picker.md) |
| Media picker | `/article/:id/edit` | Library: no results | Search matched nothing | [media-picker](screens/media-picker.md) |
| Media picker | `/article/:id/edit` | Library: failed to load | A 500 or network failure | [media-picker](screens/media-picker.md) |
| Media picker | `/article/:id/edit` | Inserted | Insert image from either tab | [media-picker](screens/media-picker.md) |
| Media picker | `/article/:id/edit` | Remove image: confirm | Remove image on an image in the article | [media-picker](screens/media-picker.md) |
| Media picker | `/article/:id/edit` | Removed | Confirmed | [media-picker](screens/media-picker.md) |
| Integration | `/integration` | Default | Page load, every endpoint card collapsed | [integration](screens/integration.md) |
| Integration | `/integration` | Group scrolled, one card expanded | A card opened, one example visible | [integration](screens/integration.md) |
| Integration | `/integration` | Copied: base URL | Copy clicked (2 s) | [integration](screens/integration.md) |
| Integration | `/integration` | Copied: CodeBlock | Copy clicked in a code block (2 s) | [integration](screens/integration.md) |
| Integration | `/integration` | Authentication | API key card, link and notes | [integration](screens/integration.md) |
| Integration | `/integration` | Session only | Routes API keys cannot call | [integration](screens/integration.md) |
| Integration | `/integration` | Errors | Status table and plain-text error shape | [integration](screens/integration.md) |
| Integration | `/integration` | Navigation | Section index active item; mobile Jump to open | [integration](screens/integration.md) |
| API keys | `/integration/api-keys` | Owner: list | Owner sees every key, with Created by | [integration-api-keys](screens/integration-api-keys.md) |
| API keys | `/integration/api-keys` | Admin: own keys only | Admin sees only their own keys | [integration-api-keys](screens/integration-api-keys.md) |
| API keys | `/integration/api-keys` | Loading | First load or retry | [integration-api-keys](screens/integration-api-keys.md) |
| API keys | `/integration/api-keys` | Empty | No keys yet | [integration-api-keys](screens/integration-api-keys.md) |
| API keys | `/integration/api-keys` | Error | 500 or network | [integration-api-keys](screens/integration-api-keys.md) |
| API keys | `/integration/api-keys` | Create key | Modal opened | [integration-api-keys](screens/integration-api-keys.md) |
| API keys | `/integration/api-keys` | Create key: validation | Name empty or expiry not in the future | [integration-api-keys](screens/integration-api-keys.md) |
| API keys | `/integration/api-keys` | Create key: name too long | More than 60 characters | [integration-api-keys](screens/integration-api-keys.md) |
| API keys | `/integration/api-keys` | One-time reveal | Key created, shown once | [integration-api-keys](screens/integration-api-keys.md) |
| API keys | `/integration/api-keys` | One-time reveal: copied | Copy clicked (2 s) | [integration-api-keys](screens/integration-api-keys.md) |
| API keys | `/integration/api-keys` | Revoke: confirm | Revoke pressed on a key | [integration-api-keys](screens/integration-api-keys.md) |
| API keys | `/integration/api-keys` | Revoked | Confirmed, key stays listed as revoked | [integration-api-keys](screens/integration-api-keys.md) |
| Users | `/users` | Default | List loaded, newest first | [users](screens/users.md) |
| Users | `/users` | Loading | First load or retry | [users](screens/users.md) |
| Users | `/users` | Only you | Nobody invited yet | [users](screens/users.md) |
| Users | `/users` | Error | 500 or network | [users](screens/users.md) |
| Users | `/users` | Invite: default, validation, sending | Invite modal opened, invalid email, POST in flight | [users](screens/users.md) |
| Users | `/users` | Invite: already a user | 409 | [users](screens/users.md) |
| Users | `/users` | Invite: failed | 500, network or mail failure | [users](screens/users.md) |
| Users | `/users` | Invite sent | 201: dialog closes, Pending row on top, toast | [users](screens/users.md) |
| Users | `/users` | Cancel invite: confirm, sending, failed | "Cancel invite" on a Pending row; DELETE in flight; 500 or network | [users](screens/users.md) |
| Users | `/users` | Cancel invite: done | 204: row removed, toast | [users](screens/users.md) |
| Users | `/users` | Renew invite: sending | "Renew invite" on an Expired row; POST in flight | [users](screens/users.md) |
| Users | `/users` | Renew invite: done | 200: row Pending on top, toast | [users](screens/users.md) |
| Users | `/users` | Renew invite: failed | 500 or network: toast, row stays Expired | [users](screens/users.md) |
| Settings | `/settings` | Up to date | Opened with no newer version | [settings](screens/settings.md) |
| Settings | `/settings` | Checking | Check for updates pressed, or the first open after 24 hours | [settings](screens/settings.md) |
| Settings | `/settings` | Check failed | Offline, or the update server didn't answer (500, network) | [settings](screens/settings.md) |
| Settings | `/settings` | Update available | A newer version exists | [settings](screens/settings.md) |
| Settings | `/settings` | Update available, notes open | "What's new in 2.3.0" expanded | [settings](screens/settings.md) |
| Settings | `/settings` | Downloading | Update pressed (202) | [settings](screens/settings.md) |
| Settings | `/settings` | Verifying | The download finished | [settings](screens/settings.md) |
| Settings | `/settings` | Ready to install | The file passed its checks | [settings](screens/settings.md) |
| Settings | `/settings` | Restart: confirm | Restart pressed | [settings](screens/settings.md) |
| Settings | `/settings` | Restart: request failed | 500 or network failure before the restart began | [settings](screens/settings.md) |
| Settings | `/settings` | Restarting to install | Full-page overlay, so it survives the server going away | [settings](screens/settings.md) |
| Settings | `/settings` | Restarting, taking longer | No answer after 60 seconds | [settings](screens/settings.md) |
| Settings | `/settings` | Update done | The page reloaded on the new version | [settings](screens/settings.md) |
| Settings | `/settings` | Update failed, rolled back | The site came back on v2.2.0-beta | [settings](screens/settings.md) |
| Settings | `/settings` | Download failed | A 500, or the connection dropped | [settings](screens/settings.md) |
| Settings | `/settings` | Verification failed | The downloaded file isn't trusted | [settings](screens/settings.md) |
| Settings | `/settings` | Too many requests (429) | Retry-After counted down in the button | [settings](screens/settings.md) |
| Settings | `/settings` | Not prepared | The server can't update from the browser | [settings](screens/settings.md) |
| Settings | `/settings` | Not prepared: command copied | Copy pressed | [settings](screens/settings.md) |
| Settings | `/settings` | Plain restart: confirm | Restart with no update waiting | [settings](screens/settings.md) |
| Settings | `/settings` | Plain restart: restarting | Same overlay as the update restart with shorter copy | [settings](screens/settings.md) |
| Settings | `/settings` | Plain restart: done | The page reloaded | [settings](screens/settings.md) |
| Settings | `/settings` | Admin view | Admins see the version and the note, with no buttons | [settings](screens/settings.md) |
| Settings | `/settings` | Role changed (403) | An owner was changed to admin while the page was open and pressed a button | [settings](screens/settings.md) |
| Settings | `/settings` | Update already running (409) | Another owner started it | [settings](screens/settings.md) |
| Home | `/home` | Update available (owner) | Owner only: quiet banner and Settings pill | [home](screens/home.md) |
| Home | `/home` | Update ready to install (owner) | Download checked: banner copy changes | [home](screens/home.md) |
| Profile | `/profile` | Account menu | Account chip clicked | [profile](screens/profile.md) |
| Profile | `/profile` | Loading | Opened by URL before /auth/me returns | [profile](screens/profile.md) |
| Profile | `/profile` | Default, no display name | First visit | [profile](screens/profile.md) |
| Profile | `/profile` | Editing, too long | Typing; over 60 characters | [profile](screens/profile.md) |
| Profile | `/profile` | Saving, saved, save failed | PATCH in flight, 200, 500 or network | [profile](screens/profile.md) |
| Profile | `/profile` | Reset: sending, sent, 429, failed | POST /v1/auth/password-reset | [profile](screens/profile.md) |
| Profile | `/profile` | Display names in the Users list | Accounts with a display name | [profile](screens/profile.md) |
| Accept invite | `/invite/accept?c=` | Checking the link | On load: GET invite | [accept-invite](screens/accept-invite.md) |
| Accept invite | `/invite/accept?c=` | Default, validation errors, filled, submitting | Valid, unused code; email read-only | [accept-invite](screens/accept-invite.md) |
| Accept invite | `/invite/accept?c=` | Username taken | 409 | [accept-invite](screens/accept-invite.md) |
| Accept invite | `/invite/accept?c=` | Invalid or used, expired | 404 or no c parameter, 410 | [accept-invite](screens/accept-invite.md) |
| Accept invite | `/invite/accept?c=` | Server error | 500 or network | [accept-invite](screens/accept-invite.md) |
| Accept invite | `/invite/accept?c=` | Success | 200: logged in, /home with toast | [accept-invite](screens/accept-invite.md) |

## HTTP status to copy

Response bodies are plain text and are never shown. `useApi` throws an `ApiError` with the status and a context key, and each screen maps them to this copy.

| Status | Where | Copy | Surface |
|---|---|---|---|
| 400 | Any form | The field error from the client rules. A server 400 that got through: "Something in the form isn't valid. Check the highlighted fields." | Field + alert |
| 401 | Any back-office call | Goes to /login?redirect=<path>&reason=expired. "Your session expired. Log in again to pick up where you left off." | Redirect + alert |
| 401 | Verify | "Log in to finish verifying." Inline log in, then retry | Inline form |
| 403 | Log in | "That username and password don't match. Check both and try again." | Alert |
| 403 | Register | "This site already has an owner. Log in instead." | ResultPanel |
| 403 | Any back-office call | Unverified: goes to /register/pending | Redirect |
| 403 | Verify | "This verification link doesn't work." Offers Cancel registration and start over | ResultPanel |
| 403 | Cancel registration | "Your account is already verified." Goes to /home | Toast |
| 403 | Reset confirm | "This reset link has expired." Offers Request a new link | ResultPanel |
| 409 | Invite | "This address already has an account." or, for a live invite, "There's already a pending invite for this address." | Field error |
| 404 | Accept invite | "This invite link doesn't work." Offers Go to log in | ResultPanel |
| 409 | Accept invite | "That username is taken. Try another." | Field |
| 410 | Accept invite | "This invite has expired. Ask the person who invited you to send a new one." | ResultPanel |
| 404 | Editor load | "This article doesn't exist." Offers All articles | ErrorView |
| 404 | Row or editor action | "That article no longer exists." The row is removed | Toast |
| 404 | Unknown route | "Page not found" | ErrorView |
| 429 | Profile, reset link | "Too many requests. You've asked for several links recently. Wait a few minutes, then try again." Button disabled | Note |
| 429 | Log in, reset request | "Too many attempts. For your security, wait a moment before trying again." With a countdown | Alert + disabled button |
| 500 | Save | "Save failed" + Retry. Changes are kept | SaveStatus |
| 500 | Publish / unpublish | "Couldn't publish" / "Couldn't unpublish" + Retry | Toast |
| 500 | Load users | "Couldn't load users. Check your connection and try again." + Try again | Alert |
| 500 | Cancel invite | "Couldn't cancel the invite. Try again in a moment." The dialog stays open | Notice in dialog |
| 500 | Renew invite | "Couldn't renew the invite. Try again in a moment." The row stays Expired | Toast |
| 500 | Invite | "Couldn't send the invite. Try again in a moment." The address stays | Alert in dialog |
| 500 | Save display name | "Couldn't save your display name. Your text is still here. Try again in a moment." | Alert in card |
| 500 | Send reset link (profile) | "Couldn't send the link. Check your connection and try again." | Note |
| 500 | Delete | "Couldn't delete the article, so it's still there. Try again in a moment." | Inline in dialog |
| 500 | Upload | "Upload failed. The server didn't accept the file. Your article hasn't changed." | ImageUploader |
| network | Anywhere | "Couldn't reach RenewCMS. Check your connection and try again." Offline: banner | Alert / toast / banner |

## API the design marked pending

Existing: `GET /v1/auth/me`, `GET /v1/auth/registration`, `429` with `Retry-After` on `/v1/auth/login` and `/v1/auth/password-reset`, and `/static/uploadedImages/*`.

Added by the Users and Profile screens, none of which exist yet:

- `GET /v1/user/`: the users and their invites, newest first.
- `POST /v1/user/invite`: sends an invitation email. 201, 409 for an existing account or a live pending invite.
- `DELETE /v1/user/invite/:id`: cancels a Pending invite. 204. Owner only.
- `POST /v1/user/invite/:id/renew`: replaces the code, resets the 3 days and created date, and resends the email. 200 with the invite. Owner only.
- `GET /v1/user/` and `GET /v1/auth/me` gain a `role` ("owner" or "admin"); the list gains `email` on accepted users.
- `POST /v1/user/invite` becomes owner only, and always creates an admin.
- `GET /v1/settings`: `{ "version": "..." }`.
- `PATCH /v1/user/me`: saves the display name. `GET /v1/auth/me` returns it.
- `GET /v1/auth/invite?c=CODE`: looks up the invite on load, returns `{ email }`, 404 or 410. `POST /v1/auth/invite/accept` takes `{ code, username, password }` and returns 200 with the session cookie, 409 for a taken username, 404 or 410.

Still not supported, so shown disabled or omitted:

Renaming a title (shown read-only, with an explanation in Details), resending the verification email (the pending page explains how to start over), changing the email or username, removing users, promoting or demoting anyone, and any role other than owner and admin. Changing the password while logged in works only through the emailed reset link on the Profile page.

Added by the Updates card, none of which exists yet (owner only unless noted, see [settings](screens/settings.md)):

- `GET /v1/system/update` (any verified user): `{ current, latest, available, notes: { version, released_at, items }, checked_at, can_apply, state, progress, error, started_at }`. `state` is `idle`, `downloading`, `verifying`, `ready`, `restarting`, `succeeded` or `failed`. `can_apply` is false when the server hasn't been prepared, or for admins.
- `POST /v1/system/update/check`: asks the release feed. 200, 429 with `Retry-After`, 500 when the feed can't be reached.
- `POST /v1/system/update/download`: 202 starts the download and verification, 400 when there is nothing to update, 403, 409 when one is already running or the server isn't prepared, 422 when the file fails verification, 429.
- `POST /v1/system/update/restart`: 202 starts the install and restart (or only a restart when no update is ready), 403, 409, 500.
- A restart must survive the server going away: the SPA polls `/healthz` and `GET /v1/system/update` until they answer.

Added by the Media screens, none of which exist yet:

- `GET /v1/media/?q=&filter=&sort=&limit=&cursor=&hash=`: the library, newest first by default. `hash` (SHA-256 hex) returns only the images with that content, which is how the browser checks for a duplicate before uploading. Each item carries `id`, `filename`, `url`, `size`, `content_type`, `width`, `height` (null for SVG), `uploaded_by`, `created_at`, `used_in` (count) and `duplicate` (bool). The response also carries the counts for the Unused and Duplicates tabs.
- `POST /v1/media/`: multipart `file`, no article id. 201 with the item. It always stores the file: the duplicate check happens in the browser (hash with `crypto.subtle`, then `GET /v1/media/?hash=`), and when `crypto.subtle` is unavailable the check is skipped and any duplicate shows up under Duplicates. The server keeps each image's SHA-256. 413 for over 10 MB, 415 for another type, 400 for an unreadable image, 429 with `Retry-After`.
- `PATCH /v1/media/{id}`: `{ filename }`, the extension is kept and the URL does not change. 200, 404.
- `DELETE /v1/media/{id}`: 204, 404. Deleting an image that is in use is allowed.
- `POST /v1/media/merge`: `{ keep_id, merge_ids }`. Rewrites article bodies from the merged copies' URLs to the kept image's URL, then deletes the copies. 200 with `{ articles_updated, merged }`, 404, 409 when a listed copy is gone or the group changed.
- `GET /v1/media/{id}/usage`: `[{ id, title, published }]`, read from article bodies.
- Images no longer belong to an article, and deleting an article no longer deletes images. `POST /v1/article/{id}/image` and `DELETE /v1/article/{id}/image/{imageId}` are replaced by the endpoints above.

## Added with Media cleanup
### Media cleanup
| State | Surface | Behaviour |
|---|---|---|
| Default | Settings card | Off, "Never run", no "Every" row |
| On | Settings card | "Every" 30 days, last and next run |
| Saving / Saved | Settings card header | "Saving…" then "Saved" for 2 s, polite live region |
| Save failed | Under the field | "Couldn't save. Try again in a moment." Control reverts |
| Validation | Under the field | "Enter a whole number of days between 1 and 365." Nothing sent |
| Read-only | Settings card | Controls disabled, button hidden, info alert |
| Loading | Settings card | Skeleton after 150 ms |
| Offline | Settings and Media | Banner as on Media. Controls and buttons disabled |
| Preview loading | Dialog | Skeleton rows, confirm disabled |
| Confirm | Dialog | Summary, up to 5 groups, link to Duplicates |
| In progress | Dialog | "Purging…", loader-circle, not dismissible |
| Nothing to purge | Dialog | Info state, "Close" only |
| Error | Dialog | Notice, stays open, confirm retries |
| Partial | Dialog | Warning, summary refreshes, "Close" and "Retry" |
| Conflict (409) | Dialog | Warning, summary refreshes |
| Success | Toast, 5 s | "Duplicates purged" / "9 copies merged. 12 articles updated." "Last purge" updates in place |
| Unattended run | Settings | No toast. Updated on next visit |

401 and 403 are global and have no local copy.

## Added with Activity
### Activity
| State | Surface | Behaviour |
|---|---|---|
| Default | `/activity` | Strip, filters, day-grouped table, pagination |
| Loading | `/activity` | Skeleton strip and rows after 150 ms |
| Zero-value strip | `/activity` | Failed and Security show a calm 0 |
| Filtered | `/activity` | Chips and "Clear all"; a strip card applies its filter |
| Empty, no activity | `/activity` | "No activity yet"; Export disabled |
| Empty, no match | `/activity` | "No activity matches these filters" with "Clear filters" |
| Error | `/activity` | "Couldn't load activity" with "Try again"; the strip may still show |
| Forbidden (403) | `/activity` | "You can't view this activity." with "Back to home" |
| Details | Slide-over / bottom sheet | Sentence, time, actor, source, target, reason, changes, previous and next |
| My activity | `/activity` | No strip, Person filter or Export; own events only |
| Export | Header button, toasts | "Preparing file…", then "Export started. Your file will download shortly." or "Couldn't export activity. Try again." |
| Home card | `/home` | Owner or admin, regular user, loading, error, empty |
| Retention | `/settings` | Default (90 days or 5 GB), age only, size only (Forever), shortening (confirm), save error |

401 is global. The 403 on `/activity` has local copy because the page itself is refused; the 403 on the summary or export of a non-admin is never shown, since the controls are hidden.