diff --git a/docs/telegram-ux.md b/docs/telegram-ux.md
index f487566..2fc87ff 100644
--- a/docs/telegram-ux.md
+++ b/docs/telegram-ux.md
@@ -186,3 +186,81 @@ backend call, complete a slow route, inspect recent trace events, or export the
 complete JSONL trace. The trace contains callback and filter inputs, session
 state transitions, exact message/keyboard renders, backend results/errors, and
 job transitions, so a UI report can be reproduced without live storage nodes.
+
+### `/actest` operator guide
+
+Run `/actest` only in a private chat as an authorized bot manager. The test UI
+must be enabled, and all commands affect only the isolated dummy database.
+Sending `/actest` without arguments is equivalent to `/actest status`.
+
+| Command | Effect |
+| --- | --- |
+| `/actest status` | Show the current scenario, route flags, synthetic job count, trace count, and test database path. |
+| `/actest reset [scenario]` | Clear dummy sessions, jobs, faults, and traces, then load `comprehensive`, `empty`, or `route_slow`. The configured scenario is used when omitted. |
+| `/actest scenario [scenario]` | Alias of `reset`; it does not preserve the previous dummy jobs or sessions. |
+| `/actest advance <job-id> <state>` | Move one synthetic job directly to a display state and persist the transition. |
+| `/actest fail-next <method> [message]` | Make exactly the next matching dummy backend call fail with the supplied message, then disarm the fault. |
+| `/actest route-ready` | Complete the pending dummy route used by `route_slow`. |
+| `/actest trace [limit]` | Show the most recent trace events in chronological order; the limit defaults to 10 and is bounded to 1–500. |
+| `/actest export` | Send the complete append-only trace as `archive-control-telegram-trace.jsonl`. |
+
+Valid `advance` states are:
+
+```text
+queued preparing running waiting stalled cancelling
+cleanup_required succeeded failed cancelled
+```
+
+The internal job ID is shown on the final line of a Remove One confirmation.
+Press Cancel after copying it if the purpose is only to drive the job with
+`advance`. It is also present in `trace` backend results and the JSONL export.
+
+Valid `fail-next` methods are:
+
+```text
+list_operation_resources
+list_clients
+get_resource_tree
+preview_transfer
+preview_eviction
+create_job
+list_jobs
+clear_finished_jobs
+hide_job
+cancel_job
+```
+
+For example:
+
+```text
+/actest reset comprehensive
+/actest fail-next preview_transfer simulated planning failure
+```
+
+The next archive or unarchive preview fails visibly with that reason; a later
+preview proceeds normally. To exercise slow route provisioning:
+
+```text
+/actest reset route_slow
+# Start an archive flow and choose a source/target.
+# The preview reports that route provisioning has started.
+/actest route-ready
+# Reopen/retry the archive flow; the preview can now complete.
+```
+
+A useful review sequence is:
+
+1. Run `/actest reset comprehensive`, then reopen `Archive Control (Test)`;
+   reset intentionally makes pre-reset inline buttons stale.
+2. Walk through Archive, Unarchive, Evict Cache, filtering, selective entry,
+   pagination, Job Status, Remove One, and cancellation without confirming
+   destructive-looking choices unless that behavior is under review.
+3. Copy a job ID from Remove One and use `/actest advance` to inspect waiting,
+   stalled, failed, cleanup-required, and terminal rendering.
+4. Arm one `fail-next` point and repeat its matching UI action.
+5. Run `/actest trace 50` for a quick diagnosis or `/actest export` when
+   reporting a reproducible UI problem.
+
+Scenario state, synthetic jobs, and traces survive bot restarts. Only `reset`
+clears them. None of these commands starts the production control daemon,
+contacts storage nodes, or mutates production jobs or placements.
diff --git a/docs/testing.md b/docs/testing.md
index 4603a34..c47e306 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -195,7 +195,9 @@ The SQLite trace records callback receipt and validated callback state before
 and after handling, text filters, complete rendered text and inline keyboards,
 backend calls/results/errors, test-control commands, and job transitions.
 `trace` shows a bounded recent view in chat; `export` sends the complete trace
-as JSON Lines for offline diagnosis.
+as JSON Lines for offline diagnosis. See the
+[`/actest` operator guide](telegram-ux.md#actest-operator-guide) for complete
+syntax, valid states/failure points, and a recommended review sequence.
 
 ## Fixture matrix