AI Implementation feature(903): Admin Area Challenges: List, Import/Export and Add/Edit Modal 1.03 (#44)

docs/guides/admin-challenges.md

@@ -3,7 +3,7 @@ type: guide
 title: Admin — Challenges
 description: How an admin lists, searches, creates, edits, deletes, imports, and exports challenges from the /admin/challenges page.
 tags: [guide, admin, challenges, import, export, files, tester]
-timestamp: 2026-07-22T21:25:29Z
+timestamp: 2026-07-22T22:17:11Z
 ---
 
 # When this view is available
@@ -104,8 +104,10 @@ The form modal has three sections (tabs): General, Connection, Files. Fields mar
 
 1. Click **Import challenges** → a file picker accepts `.json`. The client reads it and posts it to `POST /api/v1/admin/challenges/import`.
 2. On validation success the import modal opens with the preview (`total`, `conflicts`, `unknownCategories`, `warnings`) and the standard copy: *"Import N challenges. Existing challenges with matching names will be overwritten. New categories referenced but missing locally will be skipped with a warning. Continue?"*
-3. Click **Overwrite & Import** → the client posts the same document with `?confirm=overwrite`. The server stages every file up front (rolling back any FS failure), then upserts challenges inside one transaction by case-insensitive name.
-4. The response renders imported/skipped/warning counts; the list refreshes automatically.
+3. Click **Overwrite & Import** → the client posts the same document with `?confirm=overwrite`. The server stages every file up front (rolling back any FS failure), then **wipes every existing challenge (cascade-deleting their `challenge_file` and `solve` rows and best-effort unlinking their disk files) and inserts the archive's challenges** inside one transaction.
+4. The modal auto-closes on success and the list refreshes automatically; the page-level status banner shows imported/skipped/warning counts.
+
+See [Admin — Challenges Full-Replace Import](/guides/admin-challenges-import.md) for the full transactional semantics, side effects, and the auto-close contract.
 
 # Validation & error codes (server)
 
@@ -127,7 +129,7 @@ The form modal has three sections (tabs): General, Connection, Files. Fields mar
 | 3    | `frontend/src/app/core/services/admin.service.ts`                                    | Typed `listChallenges`, `getChallengeDetail`, `createChallenge`, `updateChallenge`, `deleteChallenge`, `exportChallenges`, `previewChallengeImport`, `confirmChallengeImport`, `stageChallengeFile`, `discardChallengeFile`. |
 | 4    | `frontend/src/app/features/admin/challenges/challenge-form.pure.ts`                  | Defaults/prefill, points/port validation, first-invalid-tab selection, file-size partitioning, payload mapping. |
 | 5    | `backend/src/modules/admin/admin-challenges.controller.ts`                           | `AdminGuard` + `@Roles('admin')` on every handler. |
-| 6    | `backend/src/modules/admin/challenges.service.ts`                                    | CRUD, list aggregates, transactional deletion, export, import orchestration. |
+| 6    | `backend/src/modules/admin/challenges.service.ts`                                    | CRUD, list aggregates, transactional deletion, export, full-replace import orchestration. |
 | 7    | `backend/src/modules/admin/challenge-files.service.ts`                               | Staging, commit, discard, read for export, limits. |
 | 8    | `backend/src/modules/admin/dto/challenges.dto.ts`                                    | Zod schemas for IDs, list query, create/update, staged-file manifest, import document with field paths. |
 
@@ -136,4 +138,4 @@ The form modal has three sections (tabs): General, Connection, Files. Fields mar
 * The flag is never present in any non-admin DTO. The player-facing challenges route and scoreboard remain unchanged; only admin endpoints can fetch the plaintext.
 * All mutating endpoints require the standard CSRF cookie + header pair; the existing `csrfInterceptor` handles the headers automatically.
 * The list query enforces a deterministic `LOWER(name), name` order so the UI sort is reproducible.
-* Importing the same document twice is idempotent: every incoming challenge either replaces an existing row by lowercased name or inserts a new one.
+* Importing the same document twice is idempotent: every existing challenge (matching or not) is replaced by the archive contents.