Bulk Select/Delete/Archive/Restore Quests, Adventures, Background Assets

Feature Owner: Christian Denzon
Module: Develop (Content Production)
Priority: Low
Date: September 30, 2026
Last Updated: September 30, 2026

Executive Summary

What is this feature?

Bulk Select / Delete / Archive / Restore (Bulk Actions) lets Creators and Agency Admins act on many quests, adventures, or background assets at once. Cards reveal a checkbox on hover; selecting any card opens a floating action bar with Select All, Deselect All, Archive, Restore, and Delete (permanent, protected by a typed DELETE confirmation). It replaces the old one-item-at-a-time clean-up flow where every deletion or archival needed its own click and its own modal.

Bulk Actions also completes the archive lifecycle that runs underneath the selection layer: archiving is recoverable for a fixed 120-day retention window with a visible "days left" countdown, WyzQuests emails the creator 30 days before an item is deleted, and a daily job permanently purges anything that reaches day 120 (database row plus stored media).

Why does it matter?

Creators accumulate drafts, abandoned experiments, and unused background assets. Cleaning those up one by one was slow and easy to get wrong, and archived content could silently pile up forever. Bulk selection turns minutes of clicking into a few seconds, the typed confirmation prevents accidental permanent deletion, the countdown plus warning email make the 120-day window transparent, and the automatic purge keeps the database and storage tidy without anyone remembering to do it.

What's the MVP scope?

Bulk selection on the Quests, Adventures, and Archive tabs of the Creator dashboard, on the Background Assets library and its Archive page, and — with folder permissions (MFPS) — on the folder-based Content Library pages.
Bulk Archive (quests, adventures, background assets).
Bulk Restore (archived quests, adventures, background assets).
Bulk Delete (permanent, requires typing DELETE).
Selection helpers: hover checkbox, click to enter selection mode, Shift+click range selection, Select All (respects the current search/filter), Deselect All, and an X to exit.
Archive rename (the old "Trash" surfaces are now "Archive") with a 120-day countdown per item.
Day-90 warning email (one grouped email per creator with a "Go to Archive" link) and the day-120 automatic purge.
Single-item actions (per-card Archive / Delete / Restore) remain available alongside bulk actions.
Not in scope: cross-page/whole-library Select All, undo after permanent deletion, configurable retention windows, and bulk actions on reviewer, learner, or admin surfaces.

1. User Pain Point & Solution

John is a Creator who has been building quests and adventures on WyzQuests for months. His library is now crowded with early drafts, duplicate experiments, and background assets he never used, and review cycles keep adding more. To clean up, John previously had to open each item, hunt for its own archive or delete button, and repeat — twenty items meant twenty clicks and twenty dialogs, so he kept postponing clean-up even though the clutter made finding real work harder.

Bulk Actions lets John hover any card, tick the checkbox, and keep ticking (or Shift+click to grab a whole range, or Select All within his current search). A floating bar appears with the number of selected items and exactly three ways to act on them. He archives a batch in one click and watches the items move to the Archive tab with a "112d left" countdown, restores one if he changes his mind, or permanently deletes a batch after typing DELETE. Thirty days before anything would be permanently purged, WyzQuests emails him a grouped reminder with a link straight to the Archive, so nothing disappears without warning.

Pain Points

Emotional: Tedious, repetitive clean-up creates frustration and makes creators avoid housekeeping; destructive actions felt risky because there was no single, explicit confirmation pattern.
Functional: No multi-select anywhere in the library; each archive/delete was its own click and modal; archived content had no visible expiry, so it never seemed urgent to clean up.
Business: Creators spend less time on library housekeeping and more time producing content; storage and database growth are automatically reclaimed after the retention window; fewer accidental deletions thanks to the typed confirmation.

2. 4D Framework Mapping

Diagnose: Gives creators a fast way to find and clear clutter across all three content types, with archive views that show exactly what is close to automatic deletion.

Design: A consistent selection pattern — hover checkbox, floating action bar, typed confirmation — applied across every library surface so users learn it once.

Develop: Unified bulk endpoints that accept one ID or many per request, per-item ownership verification, and a single archive lifecycle (archive → 120-day countdown → day-90 warning → day-120 purge).

Deliver: Faster day-to-day content management, safer destructive actions, and automatic storage hygiene that keeps long-term libraries healthy.

3. User Flows

Entry Points: Creator or Agency Admin signs in and opens the Creator dashboard (Quests / Adventures / Archive tabs), the Background Assets page, the Background Assets Archive page, or — when working inside folders — the folder-based Content Library.

Success Criteria: A user can select multiple quests, adventures, or background assets, archive them in one action, see them in the Archive with a 120-day countdown, restore them to the library, and permanently delete them after typing DELETE. Items that reach the end of the retention window are purged automatically after a warning email.

Main Path — Bulk Archive (Happy Path)

Sign in as a Creator or Agency Admin.
Open the Creator dashboard and the Quests tab (or Adventures, or the Background Assets page).
Hover a card: a checkbox appears in the top-left corner of its thumbnail.
Click the checkbox. The floating action bar appears at the bottom of the screen with "N item(s) selected".
Keep selecting: tick more checkboxes, Shift+click to select a range, or press Select All to select everything currently shown by the search and filters.
Click Archive.
The archived items leave the active tab and a toast confirms how many were archived.
Open the Archive tab (or the Background Assets Archive page): each item shows a "Nd left" countdown, and the list can be sorted by Days Left or Alphabetical.

Additional Flow — Bulk Restore

Open the Archive tab (archived quests and adventures are listed together) or the Background Assets Archive page.
Select one or more items.
Click Restore.
The items return to the library as drafts. Restored items are placed at the Root of the library — they do not return to the folder they were archived from.
The toast confirms how many items were restored.

Additional Flow — Bulk Delete (Permanent)

Select items in any library or archive view.
Click Delete in the floating bar.
The confirmation dialog lists the selected titles in a scrollable box and asks the user to type DELETE.
The delete button stays disabled until the token matches exactly; confirm to delete.
The items, their content, and their media are permanently deleted. A toast confirms how many were removed. This cannot be undone.

Additional Flow — Folder-Based Content Library (with Folder Permissions)

A folder owner, admin, or edit collaborator selects content inside a folder-based library or folder.
The same floating bar appears with Archive, Move, and Delete (Move is part of the folder permissions feature).
Folder owners/admins (including inherited authority) can act on content in their folders even when another creator owns the item. View-only users and the agency read view do not see selection checkboxes.

Archive Lifecycle (automatic)

Day 0 — Archived. The item leaves the library and appears in the Archive with a countdown ("112d left"). Items with 3 days or fewer remaining are highlighted.
Day 90 — Warning email. WyzQuests emails the creator one grouped message listing everything expiring in 30 days, with a "Go to Archive" button.
Day 120 — Automatic deletion. Items that are still archived are permanently deleted (database rows first, then their media). No further confirmation is required at this point.

No Data: Empty library and archive views show empty states ("No current content", "Archive is empty", "No content matches the selected filters"). If an item was already deleted elsewhere, the action reports it as "not found" instead of failing silently.

API Error: The action stops, the UI keeps the current list intact, and an error toast is shown. Items are removed from the screen only when the server confirms they were actually changed.

Permission Denied: Requests without the required ownership are rejected. If even one selected item is not permitted, the whole request is rejected (403) and nothing is changed — there are no partial unauthorized writes.

Decision Points:

IF at least one item is selected THEN show the floating action bar with its contextual actions ELSE keep the normal card layout.
IF all selected items are permitted THEN the bulk action proceeds ELSE the request is rejected (403) and no items are changed.
IF some selected items were already archived (or already restored) THEN they are skipped, and the toast reports the actual number changed.
IF a selected item no longer exists (deleted in another tab) THEN it is reported as missing and does not block the remaining items.
IF the typed confirmation does not match DELETE THEN permanent deletion cannot proceed (button stays disabled; a direct request is rejected and audit-logged).
IF an item is archived THEN it cannot be edited, previewed, or used as a template — it must be restored first.
IF an archived item reaches the end of the 120-day window THEN it is permanently purged automatically after the day-90 reminder.
IF a user restores an item THEN it returns to the library Root as a draft (the previous folder is not restored).
IF content is selected inside a folder THEN folder owners/admins (including inherited) may archive, restore, or delete it; view-only users see no selection UI.
IF a background asset is archived THEN it no longer appears in asset pickers for new content.

4. Information Architecture

Primary Information

Content type: Quest, Adventure, or Background Asset.
Item title or file name, with thumbnail.
Selection state: checkbox, highlighted card ring, and the "N item(s) selected" counter.
Archive countdown: days left before permanent deletion.
Available actions for the current view (Archive / Restore / Delete; Move inside folders).

Secondary Information

Content status (draft, published, submitted, in review, approved, changes requested), tags and skills, duration, and fees in grid/list cards.
Background asset file size and type (image, audio, video, document).
Archive toolbar: search, grid/list view toggle, status filter, skills filter, and sort (Days Left / Alphabetical).
Countdown urgency styling for items with 3 days or fewer remaining.
Confirmation messages after each action (toast with the affected count).
The scrollable list of selected titles inside the permanent-delete dialog.

Tertiary Information

Archived date and remaining days per item.
Asset source (uploaded file vs external link).
Default ordering by last update; archive ordering by days remaining on request.
Warning email delivery marker (whether the day-90 reminder was already sent for an item).

Actions

Primary CTA
- Card checkbox → floating Selection Action Bar.
Secondary Actions
- "Select All" / "Deselect All" / "Exit selection" (X).
- "Archive", "Restore", "Delete" (with typed DELETE confirmation), and "Move" inside folder libraries.
- Per-item actions: Edit, Archive, Delete, Restore.
- "Archive" button on the Background Assets page (opens the Background Assets Archive).
- Archive toolbar controls: search, view toggle, filters, and sort.

5. Data Requirements

Frontend Needs

The signed-in user's identity and role (Creator vs Agency Admin; folder role and view-only state on folder surfaces).
Selected item IDs and content type (quests vs adventures vs assets).
Item titles / file names for the confirmation dialog list.
Archive timestamps to compute and display days remaining (archived_at for quests and adventures; deleted_at for assets).
Owned and agency-scoped visibility for lists, plus folder roles for folder-based surfaces.
Server-confirmed result sets (archived, restored, deleted, skipped, missing) so the UI removes only what actually changed.

API Calls Frontend Will Make

PATCH /api/creator/archive-content (archive quests/adventures)
PATCH /api/creator/restore-content (restore archived quests/adventures)
DELETE /api/creator/permanent-delete (permanent quest/adventure delete)
DELETE /api/creator/delete-assets (archive background assets)
PATCH /api/creator/restore-assets (restore archived assets)
DELETE /api/creator/purge-assets (permanent asset delete)
GET /api/creator/list-archived (Archive tab data)
GET /api/creator/get-trash-assets (Background Assets Archive data)

Every endpoint accepts a single ID or an array of IDs. Request and response shapes are documented in the Internal Technical Guide for this feature.

6. Performance Considerations

Bulk endpoints accept ID arrays, so a selection of any size costs one request per content type instead of one request per item.
The UI updates from the server's returned ID sets instead of refetching the whole library, avoiding refresh storms after each action.
Archive lists and the warning/purge jobs use indexes on the archive timestamps (including partial indexes for "not yet warned" items), so they stay fast as archives grow.
The purge deletes database rows first and then cleans storage in parallel; storage failures are logged but do not roll back a completed deletion.
Archive-tab data is held by the parent view (sorting and filtering do not trigger refetches), and listing endpoints select only the needed columns.
Very large selections are still a single in-flight request per content type — there is no per-item progress indicator, and the action bar remains in a busy state until the requests finish.

7. Security & Authorization

Who Can Access This Feature?

Administrator: No access.
Reviewer: No access.
Creator: Full access to their own quests, adventures, and background assets.
Learner: No access.
Agency Admin: Full access to their own content; may also act on content created by members of the same agency.
Folder collaborators (MFPS): Folder owners and admins (including inherited authority) may archive, restore, or delete quests and adventures contained in their folders, even when another creator owns them. Edit collaborators manage only content they created. View-only collaborators see no selection UI.

Enforcement

Ownership is verified for every selected item before anything is written; one unauthorized item rejects the whole request.
Permanent deletion requires the typed DELETE token and is re-validated on the server independently of the browser dialog.
Background assets follow creator/same-agency rules only; they do not inherit folder permissions.
Archived content is excluded from libraries, asset pickers, previews, and "Use as Template"; archived quests cannot be edited until restored.
All checks run server-side in the API routes — the UI only hides and disables actions.

8. Error Handling

Invalid request payloads → schema validation error; nothing changes.
Items already in the target state (already archived, or not archived when restoring) → skipped and reported; the toaster shows the real count.
Items that no longer exist → reported as not found; the remaining selection still processes when at least one item exists.
A selection where nothing can be acted on → explicit "already archived" / "not archived" / "not found" message.
Unauthorized item in the selection → 403; the action stops with no partial changes.
Incorrect typed confirmation → the delete button stays disabled; a direct request is rejected (400) and recorded in the audit log.
Database failures → 500; the items stay visible in the UI because nothing was confirmed.
Media cleanup failure after a successful delete → logged as a warning; the deletion still completes and no broken references remain in the UI.
Warning email failures (day-90 job) → counted as errors and retried on the next run; items are marked as warned only after the email is sent.
Cron authentication failures → 401, and the scheduled workflow job fails so the issue is visible.

9. Testing Checklist

Happy Path

Sign in as a Creator.
Open the Creator dashboard and the Quests tab.
Hover a quest card: a checkbox appears.
Click the checkbox: the floating action bar appears with a count.
Select several quests, including a Shift+click range, then use Select All with a search filter applied.
Click Archive: the toast reports the archived count and the items leave the tab.
Open the Archive tab: the items are listed with a "Nd left" countdown; sort by Days Left and by Alphabetical.
Select archived items and click Restore: they return to the Quests tab (at Root, draft).
Select items and click Delete: the dialog lists them; typing DELETE enables the confirm button; confirming removes them permanently.
Repeat the same flow on the Adventures tab.
On Background Assets: archive and permanently delete from the library; restore and delete from the Archive page.
In a folder-based library (as owner/admin): select contained quests/adventures and verify Archive and Delete (and Move) are available.
Verify archived quests/adventures are gone from the library, cannot be edited, and archived assets no longer appear in asset pickers.
(Ops) Trigger the warning and purge jobs with the secret and confirm per-type results in the response.

Edge Cases

Select an item that was already archived in another tab: it is skipped and the toast count matches reality.
Select an item that was deleted in another tab: it is reported as missing; the rest still process.
Type the wrong confirmation token: the confirm button stays disabled; a direct API call is rejected and audit-logged.
Include an unauthorized item in the selection: 403, nothing changes.
Select items across content types on the Archive tab (quests + adventures mixed): both types are processed and both counts are reflected.
Change the search/filter after selecting: Select All applies to the currently shown list only.
Restore an item that lived in a folder: it returns to Root as a draft.
Open an archived item from an old link or the editor: access is blocked (404 / "restore it first").
Agency member acts on a colleague's content: allowed for same-agency content; assets still require same-agency ownership.
Archive view with filters that match nothing: "No content matches the selected filters".
Empty archive: "Archive is empty".
Purge/warning jobs run with an invalid secret: 401 and a failed workflow run.
Very large selection: one request per content type; the bar stays busy until completion.

10. OPEN QUESTIONS

Should Select All be able to span the entire library (all pages/tabs) instead of only the currently filtered view? — Still open. Selection is currently scoped to what is rendered.
Should the 120-day retention window be configurable (per agency or per content type)? — Still open. It is fixed at 120 days, with the warning at day 90.
Should the warning email be sent more than once (for example, again at day 110)? — Still open. Currently one warning per item, 30 days before deletion.
Should production also run the warning and purge schedules? — Still open (operations decision). The scheduled workflows currently target develop and staging only.
Should background assets inherit folder permissions like quests and adventures do? — Still open. Assets remain creator/agency-scoped only.
Should bulk Move be considered part of this feature? — Resolved (v1.0): Move shipped with the folder permissions work (#745) and is documented in the MFPS Hand-Off; the Bulk Actions bar is shared.
Should the archive offer a "Restore All" button? — Resolved (v1.0): the action is labeled Restore and applies to the current selection, where Select All covers everything in the filtered list.
Should archived items be permanently deletable before day 120? — Resolved (v1.0): yes, via Delete (permanent) from the library or the archive, guarded by the typed DELETE confirmation.

11. OUT OF SCOPE

Cross-page / whole-library Select All — still out of scope for this release.
Undo after permanent deletion — out of scope by design; the typed confirmation is the safeguard.
Configurable retention windows per agency or content type — not in this release.
Bulk actions for Reviewers, Learners, or Administrators — no access to creator libraries.
Restoring content back into its original folder — restored items always return to the library Root.
Previewing, editing, or using archived content as a template — archived content is excluded (restore it first).
Per-item progress reporting for very large selections — not implemented.
Sharing or transferring archived content between accounts — not supported.

12. SUCCESS METRICS

Quests, Adventures, and Background Assets can be bulk selected (issue #727 acceptance criterion 1).
Bulk delete is functional (acceptance criterion 2), protected by the typed DELETE confirmation.
Bulk archive is functional (acceptance criterion 3).
Bulk restore is functional (acceptance criterion 4).
Archived content is excluded from libraries and asset pickers and cannot be edited until restored.
Archived items show an accurate 120-day countdown; items at 3 days or fewer are highlighted.
The day-90 warning email is sent once per creator with all of their expiring items; the day-120 purge runs automatically.
Unauthorized items can never be acted on — a mixed selection changes nothing.
Counts shown to users (toasts) always match the server-reported results, including skipped and missing items.
Restored content is editable again and appears at the library Root.

18. DEPENDENCIES

This feature depends on

Supabase Auth (user identity).
Supabase Database — quests, adventures, and asset_metadata (archive columns and listing queries).
Supabase Storage — bucket public-assets (media cleanup during purge).
Email Service (day-90 warning emails).
GitHub Actions scheduled workflows and the CRON_SECRET configuration.
Folder Permissions (MFPS) — for the folder-based library surface and the folder-admin fallback on contained quests/adventures.
Existing single-item archive/delete/restore endpoints (extended to accept ID arrays rather than replaced).

This feature depends on this

Content Library and My Content (library clean-up and archive management).
Background Assets library and its Archive page.
Folder management bulk actions (Move and folder-aware Archive/Delete).
Storage and database hygiene (automatic purge after the retention window).

19. TIMELINE & OWNERSHIP

Backend: Christian Denzon.
Frontend: Christian Denzon.
QA: Internal development testing.
Estimated Completion: Delivered and merged August 2026 — bulk selection (#728) on top of the archive lifecycle (#711), completed by the auto-purge schedule (#770). Documentation updated September 30, 2026.

Note: API Endpoints and Schema — please refer to its Internal Technical Guide (Bulk Select / Delete / Archive / Restore).

Document version: 1.0 — Hand-Off for Bulk Select / Delete / Archive / Restore of Quests, Adventures, and Background Assets, including the 120-day archive lifecycle (countdown, day-90 warning email, day-120 purge), September 30, 2026. PRs: #728, #711, #725, #726, #770.