RenewCMS/docs/design/screens/settings.md

Settings: Media cleanup

Settings area: /settings (parent), /settings/media/variants, /settings/media/cache (children under the "Media" group). A "Media" card above this card links to both: "Manage image variants" ("Named sizes requested with ?v="), "Cache usage" ("Generated images and disk space"). Same sidebar on all three routes; see "Settings navigation" in the Back-office board.

Route: /settings. Visual reference: RenewCMS Screens Back-office.dc.html, groups "Settings: Media cleanup", "Purge dialog", "Purge results" (frames: AppFrame.dc.html, MediaFrame.dc.html). API: GET/PATCH /v1/media/purge-settings (owner, admin), GET /v1/media/purge-preview, POST /v1/media/purge. 401 and 403 are global: no local copy.

Rule: a group is purged only if at least one copy is used in an article. All copies merge into the one used in the most articles (ties: oldest, then lowest id). Groups with no used copy are left alone. Automatic purge is off by default.

Card

Second card below Version, 20 px gap, same card styling. Page max width 720 px.

• Title: "Media cleanup". Description: "Merge identical images so your library stays tidy. Articles that use a copy are switched to the most used one."
• "Automatic purge" / helper "Runs in the background. Off by default." / USwitch.
• When on: "Every" / helper "Between 1 and 365 days." / number input, suffix "days", default 30.
• Read-only lines: "Last purge: 14 Jun 2026 · 3 copies merged · 5 articles updated" or "Never run". When on, also "Next purge: 14 Jul 2026".
• Divider, then "Purge now" / "Merge every group of duplicates that has an image in use, right away." / outline button "Purge duplicates" (merge).
• No Save button. Saves on toggle and on blur or Enter of the days field. "Saved" (check, success) sits in the card header and fades after 2 s; "Saving…" (loader-circle) while pending.
• Non-owner/admin: switch and input disabled, button and divider hidden, info alert "Only owners and admins can change this."

States (names matched exactly)

• Default: off, never run
• On: 30 days, last run
• Saving
• Saved
• Save failed: "Couldn't save. Try again in a moment." under the field; the control reverts.
• Validation error: "Enter a whole number of days between 1 and 365." Nothing is sent.
• Read-only (non-admin)
• Loading skeleton (after 150 ms)
• Offline: banner "You're offline. Changing automatic purge and purging duplicates need a connection." Switch, input and button disabled.

Dialog

UModal, sm:max-w-md, bottom sheet on mobile, cancel first.

• Title "Purge duplicates?". Description "Articles that use a duplicate will be switched to the most used copy of that image, and the other copies will be deleted. This can't be undone."
• Summary: "4 groups · 9 copies will be deleted · 12 articles will be updated". Singular: "1 group · 1 copy will be deleted · 2 articles will be updated".
• Bordered list of up to 5 groups: thumbnail, filename, "Kept · used in 4 articles", and "2 copies merged". More: "and 3 more groups".
• Link "Review in Duplicates" to /media?filter=duplicates.
• Buttons: "Cancel", danger "Purge 4 groups". Pending: "Purging…" with loader-circle, dialog can't be dismissed.
• Loading preview: skeleton rows, confirm disabled.
• Nothing to purge: icon copy, "Nothing to purge", "No duplicate is used in an article, so there is nothing to merge.", button "Close". No confirm.
• Error (stays open): "Couldn't purge the duplicates. Nothing was changed. Try again in a moment."
• Partial: "Some groups couldn't be merged. 3 of 4 groups were purged. Try again to finish." Buttons "Close", "Retry". Summary refreshes to the remaining groups.
• Conflict (409): "The library changed, so nothing was purged. Check the new summary and try again." Summary refreshes.

Results

• Toast (5 s): circle-check, "Duplicates purged" / "9 copies merged. 12 articles updated."
• "Last purge" updates in place; "Next purge" moves forward by the interval.
• An unattended run shows no toast. The next visit shows the updated line.

Media entry point

Duplicates tab: secondary "Purge duplicates" button (merge) next to the sort menu; stacked toolbar on mobile. Opens the same dialog. Hidden for non-owner/admin and when there are no groups. "Merge into this one" is unchanged.

Components (Nuxt UI v4)

UCard, USwitch, UInputNumber (min 1, max 365, suffix), UFormField, UAlert, UButton, UModal, USkeleton, useToast.

Copy per state (generated from the board source, pass 2)

Every state below is drawn in light and dark (theme switch on the board), at 1440×900 and 390×844 (both frames sit side by side). Board: RenewCMS Screens Back-office.dc.html. Copy is exact; where a cell is empty the state reuses the fixed copy.

Fixed copy in the frame

• Settings
• Workspace information.
• Version
• Updates
• Pending
• Read the full release notes
• For whoever manages the server
• Media
• Image sizes, cache and cleanup for your media library.
• Manage image variants
• Named sizes requested with ?v=
• Cache usage
• Generated images and disk space
• Media cleanup
• Merge identical images so your library stays tidy. Articles that use a copy are switched to the most used one.
• Saving…
• Saved
• Only owners and admins can change this.
• Automatic purge
• Runs in the background. Off by default.
• Every
• Between 1 and 365 days.
• days
• Purge now
• Merge every group of duplicates that has an image in use, right away.
• Purge duplicates
• Retention
• How long activity is kept, and how much log data to keep. Whichever limit is reached first removes the oldest events. Only owners can change it.
• Couldn't save the retention period
• Your previous setting is still in place.
• Try again
• Keep activity for
• or
• Keep at most
• Events older than 30 days will be removed
• This happens at the next cleanup on 7 Oct 2026, 03:00. It can't be undone.
• Apply 30 days
• Cancel
• Activity logs are append-only
• Events can't be edited or deleted from the app. Only the retention limits remove them.

Settings: Updates (group "Settings", 25 states)

Route: /settings. API: GET /v1/system/update · POST …/check · POST …/download · POST …/update/restart (all pending).

The page is one column of cards, top to bottom: Version, Updates, Media cleanup, Retention (owner only). The screens below are scrolled to the card they show. New Updates card under Version, owner only. Update downloads and checks the new version and changes nothing. Restart installs it and restarts the site (about 10 seconds). "Restart later" is simply leaving the card or the dialog. A plain Restart shows only when no update is waiting. Admins see the version and a note. When the server isn't prepared, the card shows the notice and a "How to update" link with no buttons. Progress is a progressbar with a value, announced at 25% steps and when each step changes. The card is a polite live region. After the restart the page reloads, focus lands on the "Updates" heading, and a toast confirms. Buttons are disabled while any step runs, and any owner on any device sees the same state from the server. Cue elsewhere: see Home. Out of scope: choosing versions, downgrades, automatic updates, update history.

#	State	Trigger	Copy
1	Up to date	Opened with no newer version. Restart is available but not emphasised.	"You're up to date" / "You have the latest version of RenewCMS." / "Check for updates" / "Restart"
2	Checking	Check for updates pressed, or the first open after 24 hours. Announced as "Checking for updates". Buttons are disabled.	"Checking for updates…" / "This usually takes a few seconds." / "Checking…"
3	Check failed	Offline, or the update server didn't answer (500, network). The last known result is kept.	"Couldn't check for updates" / "RenewCMS couldn't reach the update server. Check your connection and try again. Your site isn't affected." / "Last checked yesterday at 18:12" / "Try again" / "Restart"
4	Update available	A newer version exists. Release notes are collapsed. Update is the one primary button.	"Version 2.3.0 is available" / "You have v2.2.0-beta. Update downloads the new version and checks it. Nothing changes until you restart." / "Update" / "Takes about 2 minutes. Your site stays online."
5	Update available, notes open	"What's new in 2.3.0" expanded. It is a button with aria-expanded, and the list is plain text.	"Version 2.3.0 is available" / "You have v2.2.0-beta. Update downloads the new version and checks it. Nothing changes until you restart." / "Update" / "Takes about 2 minutes. Your site stays online."
6	Downloading	Update pressed (202). Progress polls every second. Announced as "Downloading, 25 percent" and so on, never every tick.	"Downloading version 2.3.0…" / "You can leave this page. The download continues and your site stays online." / "Downloading version 2.3.0" / "42% · 11 of 26 MB" / "Updating…"
7	Verifying	The download finished. No percentage, so the bar is indeterminate. Announced as "Checking the download".	"Checking the download…" / "Making sure the file is complete and safe to install. This takes a few seconds." / "Checking the download" / "Almost there" / "Updating…"
8	Ready to install	The file passed its checks. Restart becomes the primary action. "Restart later" is closing the dialog or leaving the page.	"Version 2.3.0 is ready to install" / "The download is checked. Restart to install it. Your site will be unavailable for about 10 seconds." / "Nothing has changed yet." / "Restart" / "Not now? Leave this page. The update waits here, and the banner on Home reminds you."
9	Restart: confirm	Restart pressed. Same dialog behaviour as the delete confirm: focus moves to the first button, Escape and "Restart later" close it, and focus returns to Restart. The confirm button is neutral, not red, because nothing is lost.	"Version 2.3.0 is ready to install" / "The download is checked. Restart to install it. Your site will be unavailable for about 10 seconds." / "Nothing has changed yet." / "Restart"
10	Restart: request failed	500 or network failure before the restart began. The site is still running.	"Version 2.3.0 is ready to install" / "The download is checked. Restart to install it. Your site will be unavailable for about 10 seconds." / "Nothing has changed yet." / "Restart" / "Couldn't start the restart. Nothing was changed and your site is still running. Try again in a moment."
11	Restarting to install	Full-page overlay, so it survives the server going away. The page polls until the site answers, then reloads. It is a live region announced once as "Installing version 2.3.0. Your site is restarting."	"Version 2.3.0 is ready to install" / "Installing version 2.3.0" / "Your site is restarting with the new version. This takes about 10 seconds. This page reloads on its own when the site is back." / "Started at 09:51"
12	Restarting, taking longer	No answer after 60 seconds. The copy changes and a manual reload appears. The overlay stays until the site is back.	"Still restarting" / "This is taking longer than usual. Keep this page open. It reloads on its own when the site is back, or you can reload it now." / "Started at 09:51 · 1 minute ago" / "Reload page"
13	Update done	The page reloaded on the new version. Focus lands on the "Updates" heading (ring shown), the toast is announced, and the version updates.	"You're on version 2.3.0" / "The update is installed and your site is running again." / "Updated today at 09:52" / "Check for updates" / "Restart" / "Read the release notes" / "Update installed" / "RenewCMS is now on version 2.3.0."
14	Update failed, rolled back	The site came back on v2.2.0-beta. The error toast stays until dismissed and the card keeps the explanation.	"The update didn't install" / "RenewCMS put the previous version back, so your site is running as before. Nothing was lost." / "What to do next: try again in a few minutes. If it fails again, ask whoever manages your server to check the update." / "Try again" / "Your site is back on v2.2.0-beta."
15	Download failed	A 500, or the connection dropped. Focus moves to the card heading. Try again restarts the download.	"The download didn't finish" / "The connection dropped before the file was complete. Nothing was changed and your site is running as before." / "Try again"
16	Verification failed	The downloaded file isn't trusted. The tone is a warning, and the file is thrown away. Technical detail goes to the server log, not the screen.	"We didn't use this update" / "The file didn't pass our safety check, so it was not installed. Nothing was changed. Try downloading it again. If this keeps happening, contact RenewCMS support." / "Try again"
17	Too many requests (429)	Retry-After counted down in the button. It re-enables at zero.	"Too many tries" / "Wait a moment before trying again." / "Try again in 0:42"
18	Not prepared	The server can't update from the browser. No buttons, not even Restart. The command is for the person who runs the server and is a single line. The placeholder command is subject to the real one.
19	Not prepared: command copied	Copy pressed. The button reads "Copied" for 2 s and it is announced.
20	Plain restart: confirm	Restart with no update waiting. Nothing is installed.	"You're up to date" / "You have the latest version of RenewCMS." / "Check for updates" / "Restart"
21	Plain restart: restarting	Same overlay as the update restart with shorter copy.	"Restarting your site" / "This takes about 10 seconds. This page reloads on its own when the site is back." / "Started at 09:51"
22	Plain restart: done	The page reloaded. Focus lands on the "Updates" heading.	"Your site is back" / "Site restarted" / "Your site is running again."
23	Admin view	Admins see the version and the note, with no buttons. Up to date: "You're up to date" and "Only the owner can update or restart the site." No Home banner or Settings pill.	"Version 2.3.0 is available" / "You have v2.2.0-beta. Only the owner can update RenewCMS. Ask the owner of this site."
24	Role changed (403)	An owner was changed to admin while the page was open and pressed a button. The card reloads in the admin view.	"Version 2.3.0 is available" / "You have v2.2.0-beta. Only the owner can update RenewCMS. Ask the owner of this site." / "Only the owner can do this" / "Ask the owner of this site to update RenewCMS."
25	Update already running (409)	Another owner started it. The card switches to that run's progress.	"Version 2.3.0 is available" / "You have v2.2.0-beta. Update downloads the new version and checks it. Nothing changes until you restart." / "Update" / "An update is already running" / "Another owner started it. Progress shows here."

Settings: Media cleanup (group "Settings: Media cleanup", 9 states)

Route: /settings. API: GET /v1/media/purge-settings · PATCH /v1/media/purge-settings (owner, admin).

A card below Updates, same card styling and 20 px gap. Automatic purge is off by default. Settings save immediately on toggle and on blur or Enter of the days field; there is no Save button. 401 and 403 are global (login redirect, /register/pending) and have no local copy.

#	State	Trigger	Copy
1	Default: off, never run	Owner or admin. Automatic purge is off, so the "Every" row and "Next purge" are hidden.
2	On: 30 days, last run	Switch on. "Every" appears with the default of 30 days. The last-run line and the next run are shown.
3	Saving	Brief state after toggling or leaving the field. "Saving…" with loader-circle sits in the card header; controls stay usable.
4	Saved	The save succeeded. A small "Saved" confirmation shows in the card header and fades after 2 s. It is announced politely.
5	Save failed	A 500 or network failure. The error sits under the field and the control reverts to its previous value (30).
6	Validation error	Empty, 0, above 365 or not a whole number, checked on blur or Enter. Nothing is sent. The field keeps what was typed until corrected.
7	Read-only (non-admin)	Other verified users. Switch and input are disabled, "Purge now" is hidden, and an info alert explains why.
8	Loading skeleton	The settings request is in flight. Skeleton shows only after 150 ms.
9	Offline	navigator.onLine is false. The banner matches Media. Switch, input and button are disabled.	"You're offline. Changing automatic purge and purging duplicates need a connection."

Purge duplicates: dialog (group "Purge dialog", 8 states)

Route: opens from "Purge now" (Settings) and "Purge duplicates" (Media, Duplicates tab). API: GET /v1/media/purge-preview · POST /v1/media/purge.

UModal, sm:max-w-md, bottom sheet on mobile. Cancel first, then the danger confirm. While the request runs, the confirm shows loader-circle and the dialog can't be dismissed. The preview is computed before confirming. A group is purged only if one of its copies is used in an article; the kept copy is the one used in the most articles (ties: oldest, then lowest id).

#	State	Trigger	Copy
1	loading	Loading preview	"The preview request is in flight. Skeleton rows show after 150 ms and the confirm is disabled."
2	confirm	Confirm	""Purge now" pressed. Summary, up to 5 groups, a link to the Duplicates tab."
3	confirm	Confirm: many groups	"More than 5 groups. The list stops at 5 and says how many more."
4	progress	In progress	"POST in flight. Confirm reads "Purging…" with loader-circle; Cancel is disabled and Esc, the overlay and swipe do nothing."
5	nothing	Nothing to purge	"The preview has no group with an image in use. No confirm; one Close button."
6	error	Error	"500 or network failure. The dialog stays open, nothing changed. Confirm retries."
7	partial	Partial failure	"Some groups failed. The summary refreshes to what is left. Buttons: Close, Retry."
8	conflict	Conflict (409)	"The library changed since the preview. Nothing was purged, the summary refreshes and the dialog stays open."

Purge: results and feedback (group "Purge results", 2 states)

Route: /settings. API: after POST /v1/media/purge.

An unattended run does not toast. The next visit to Settings shows the updated "Last purge" line.

#	State	Trigger	Copy
1	Success	The dialog closes, a toast shows for 5 s, and the "Last purge" line updates in place.	"Duplicates purged" / "9 copies merged. 12 articles updated."
2	Success, automatic purge on	Same, with the next run moved forward by the interval.	"4 Nov 2026" / "Duplicates purged" / "9 copies merged. 12 articles updated."

Settings: Retention (owner only) (group "Settings: Retention", 6 states)

Route: /settings. API: GET /v1/settings · PATCH /v1/settings.

The last card on the page, same card styling as Version, Updates and Media cleanup. Saves on change.

#	State	Trigger	Copy
1	Default, 90 days or 5 GB	Saves on change. Whichever limit is reached first removes the oldest events.
2	Age only (no size limit)	The size select reads "No size limit". Same as before this option.
3	Size only (forever)	Age is set to Forever, so only the size limit removes events.
4	Shortening the period	Confirms before older events are removed.
5	Forever	No cleanup scheduled.
6	Save error	The previous setting is still in place.