nodmix 2026.5.25

package/docs/concepts/dreaming.md

@@ -0,0 +1,261 @@
+---
+summary: "Background memory consolidation with light, deep, and REM phases plus a Dream Diary"
+title: "Dreaming"
+sidebarTitle: "Dreaming"
+read_when:
+  - You want memory promotion to run automatically
+  - You want to understand what each dreaming phase does
+  - You want to tune consolidation without polluting MEMORY.md
+---
+
+Dreaming is the background memory consolidation system in `memory-core`. It helps Nodmix move strong short-term signals into durable memory while keeping the process explainable and reviewable.
+
+<Note>
+Dreaming is **opt-in** and disabled by default.
+</Note>
+
+## What dreaming writes
+
+Dreaming keeps two kinds of output:
+
+- **Machine state** in `memory/.dreams/` (recall store, phase signals, ingestion checkpoints, locks).
+- **Human-readable output** in `DREAMS.md` (or existing `dreams.md`) and optional phase report files under `memory/dreaming/<phase>/YYYY-MM-DD.md`.
+
+Long-term promotion still writes only to `MEMORY.md`.
+
+## Phase model
+
+Dreaming uses three cooperative phases:
+
+| Phase | Purpose                                   | Durable write     |
+| ----- | ----------------------------------------- | ----------------- |
+| Light | Sort and stage recent short-term material | No                |
+| Deep  | Score and promote durable candidates      | Yes (`MEMORY.md`) |
+| REM   | Reflect on themes and recurring ideas     | No                |
+
+These phases are internal implementation details, not separate user-configured "modes."
+
+<AccordionGroup>
+  <Accordion title="Light phase">
+    Light phase ingests recent daily memory signals and recall traces, dedupes them, and stages candidate lines.
+
+    - Reads from short-term recall state, recent daily memory files, and redacted session transcripts when available.
+    - Writes a managed `## Light Sleep` block when storage includes inline output.
+    - Records reinforcement signals for later deep ranking.
+    - Never writes to `MEMORY.md`.
+
+  </Accordion>
+  <Accordion title="Deep phase">
+    Deep phase decides what becomes long-term memory.
+
+    - Ranks candidates using weighted scoring and threshold gates.
+    - Requires `minScore`, `minRecallCount`, and `minUniqueQueries` to pass.
+    - Rehydrates snippets from live daily files before writing, so stale/deleted snippets are skipped.
+    - Appends promoted entries to `MEMORY.md`.
+    - Writes a `## Deep Sleep` summary into `DREAMS.md` and optionally writes `memory/dreaming/deep/YYYY-MM-DD.md`.
+
+  </Accordion>
+  <Accordion title="REM phase">
+    REM phase extracts patterns and reflective signals.
+
+    - Builds theme and reflection summaries from recent short-term traces.
+    - Writes a managed `## REM Sleep` block when storage includes inline output.
+    - Records REM reinforcement signals used by deep ranking.
+    - Never writes to `MEMORY.md`.
+
+  </Accordion>
+</AccordionGroup>
+
+## Session transcript ingestion
+
+Dreaming can ingest redacted session transcripts into the dreaming corpus. When transcripts are available, they are fed into the light phase alongside daily memory signals and recall traces. Personal and sensitive content is redacted before ingestion.
+
+## Dream Diary
+
+Dreaming also keeps a narrative **Dream Diary** in `DREAMS.md`. After each phase has enough material, `memory-core` runs a best-effort background subagent turn and appends a short diary entry. It uses the default runtime model unless `dreaming.model` is configured. If the configured model is unavailable, Dream Diary retries once with the session default model.
+
+<Note>
+This diary is for human reading in the Dreams UI, not a promotion source. Dreaming-generated diary/report artifacts are excluded from short-term promotion. Only grounded memory snippets are eligible to promote into `MEMORY.md`.
+</Note>
+
+There is also a grounded historical backfill lane for review and recovery work:
+
+<AccordionGroup>
+  <Accordion title="Backfill commands">
+    - `memory rem-harness --path ... --grounded` previews grounded diary output from historical `YYYY-MM-DD.md` notes.
+    - `memory rem-backfill --path ...` writes reversible grounded diary entries into `DREAMS.md`.
+    - `memory rem-backfill --path ... --stage-short-term` stages grounded durable candidates into the same short-term evidence store the normal deep phase already uses.
+    - `memory rem-backfill --rollback` and `--rollback-short-term` remove those staged backfill artifacts without touching ordinary diary entries or live short-term recall.
+
+  </Accordion>
+</AccordionGroup>
+
+The Control UI exposes the same diary backfill/reset flow so you can inspect results in the Dreams scene before deciding whether the grounded candidates deserve promotion. The Scene also shows a distinct grounded lane so you can see which staged short-term entries came from historical replay, which promoted items were grounded-led, and clear only grounded-only staged entries without touching ordinary live short-term state.
+
+## Deep ranking signals
+
+Deep ranking uses six weighted base signals plus phase reinforcement:
+
+| Signal              | Weight | Description                                       |
+| ------------------- | ------ | ------------------------------------------------- |
+| Frequency           | 0.24   | How many short-term signals the entry accumulated |
+| Relevance           | 0.30   | Average retrieval quality for the entry           |
+| Query diversity     | 0.15   | Distinct query/day contexts that surfaced it      |
+| Recency             | 0.15   | Time-decayed freshness score                      |
+| Consolidation       | 0.10   | Multi-day recurrence strength                     |
+| Conceptual richness | 0.06   | Concept-tag density from snippet/path             |
+
+Light and REM phase hits add a small recency-decayed boost from `memory/.dreams/phase-signals.json`.
+
+## QA shadow trial report coverage
+
+QA Lab includes a report-only scenario for exploring how a future dreaming
+shadow trial could review a candidate memory before promotion. The scenario asks
+an agent to compare a baseline answer with an answer that can use the candidate
+memory, then write a local report with a verdict, reason, and risk flags.
+
+This coverage is intentionally scoped to QA. It verifies that the report artifact
+stays separate from `MEMORY.md` and that the agent does not claim the candidate
+was promoted. It does not add production shadow-trial behavior or change the
+deep-phase promotion engine.
+
+## Scheduling
+
+When enabled, `memory-core` auto-manages one cron job for a full dreaming sweep. Each sweep runs phases in order: light → REM → deep.
+
+The sweep includes the primary runtime workspace and any configured agent workspaces, deduped by path, so subagent workspace fan-out does not exclude the main agent's `DREAMS.md` and memory state.
+
+Default cadence behavior:
+
+| Setting              | Default       |
+| -------------------- | ------------- |
+| `dreaming.frequency` | `0 3 * * *`   |
+| `dreaming.model`     | default model |
+
+## Quick start
+
+<Tabs>
+  <Tab title="Enable dreaming">
+    ```json
+    {
+      "plugins": {
+        "entries": {
+          "memory-core": {
+            "config": {
+              "dreaming": {
+                "enabled": true
+              }
+            }
+          }
+        }
+      }
+    }
+    ```
+  </Tab>
+  <Tab title="Custom sweep cadence">
+    ```json
+    {
+      "plugins": {
+        "entries": {
+          "memory-core": {
+            "config": {
+              "dreaming": {
+                "enabled": true,
+                "timezone": "America/Los_Angeles",
+                "frequency": "0 */6 * * *"
+              }
+            }
+          }
+        }
+      }
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## Slash command
+
+```
+/dreaming status
+/dreaming on
+/dreaming off
+/dreaming help
+```
+
+## CLI workflow
+
+<Tabs>
+  <Tab title="Promotion preview / apply">
+    ```bash
+    nodmix memory promote
+    nodmix memory promote --apply
+    nodmix memory promote --limit 5
+    nodmix memory status --deep
+    ```
+
+    Manual `memory promote` uses deep-phase thresholds by default unless overridden with CLI flags.
+
+  </Tab>
+  <Tab title="Explain promotion">
+    Explain why a specific candidate would or would not promote:
+
+    ```bash
+    nodmix memory promote-explain "router vlan"
+    nodmix memory promote-explain "router vlan" --json
+    ```
+
+  </Tab>
+  <Tab title="REM harness preview">
+    Preview REM reflections, candidate truths, and deep promotion output without writing anything:
+
+    ```bash
+    nodmix memory rem-harness
+    nodmix memory rem-harness --json
+    ```
+
+  </Tab>
+</Tabs>
+
+## Key defaults
+
+All settings live under `plugins.entries.memory-core.config.dreaming`.
+
+<ParamField path="enabled" type="boolean" default="false">
+  Enable or disable the dreaming sweep.
+</ParamField>
+<ParamField path="frequency" type="string" default="0 3 * * *">
+  Cron cadence for the full dreaming sweep.
+</ParamField>
+<ParamField path="model" type="string">
+  Optional Dream Diary subagent model override. Use a canonical `provider/model` value when also setting a subagent `allowedModels` allowlist.
+</ParamField>
+
+<Warning>
+`dreaming.model` requires `plugins.entries.memory-core.subagent.allowModelOverride: true`. To restrict it, also set `plugins.entries.memory-core.subagent.allowedModels`. Trust or allowlist failures stay visible instead of falling back silently; the retry only covers model-unavailable errors.
+</Warning>
+
+<Note>
+Phase policy, thresholds, and storage behavior are internal implementation details (not user-facing config). See [Memory configuration reference](/reference/memory-config#dreaming) for the full key list.
+</Note>
+
+## Dreams UI
+
+When enabled, the Gateway **Dreams** tab shows:
+
+- current dreaming enabled state
+- phase-level status and managed-sweep presence
+- short-term, grounded, signal, and promoted-today counts
+- next scheduled run timing
+- a distinct grounded Scene lane for staged historical replay entries
+- an expandable Dream Diary reader backed by `doctor.memory.dreamDiary`
+
+## Dreaming never runs: status shows blocked
+
+If `nodmix memory status` reports `Dreaming status: blocked`, the managed cron exists but the default agent heartbeat is not firing. Check that heartbeat is enabled for the default agent and that its target is not `none`, then run `nodmix memory status --deep` again after the next heartbeat interval.
+
+## Related
+
+- [Memory](/concepts/memory)
+- [Memory CLI](/cli/memory)
+- [Memory configuration reference](/reference/memory-config)
+- [Memory search](/concepts/memory-search)

package/docs/concepts/experimental-features.md

@@ -0,0 +1,108 @@
+---
+summary: "What experimental flags mean in Nodmix and which ones are currently documented"
+title: "Experimental features"
+read_when:
+  - You see an `.experimental` config key and want to know whether it is stable
+  - You want to try preview runtime features without confusing them with normal defaults
+  - You want one place to find the currently documented experimental flags
+---
+
+Experimental features in Nodmix are **opt-in preview surfaces**. They are
+behind explicit flags because they still need real-world mileage before they
+deserve a stable default or a long-lived public contract.
+
+Treat them differently from normal config:
+
+- Keep them **off by default** unless the related doc tells you to try one.
+- Expect **shape and behavior to change** faster than stable config.
+- Prefer the stable path first when one already exists.
+- If you are rolling Nodmix out broadly, test experimental flags in a smaller
+  environment before baking them into a shared baseline.
+
+## Currently documented flags
+
+| Surface                  | Key                                                                                        | Use it when                                                                                                    | More                                                                                          |
+| ------------------------ | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Local model runtime      | `agents.defaults.experimental.localModelLean`, `agents.list[].experimental.localModelLean` | A smaller or stricter local backend chokes on Nodmix's full default tool surface                             | [Local Models](/gateway/local-models)                                                         |
+| Memory search            | `agents.defaults.memorySearch.experimental.sessionMemory`                                  | You want `memory_search` to index prior session transcripts and accept the extra storage/indexing cost         | [Memory configuration reference](/reference/memory-config#session-memory-search-experimental) |
+| Structured planning tool | `tools.experimental.planTool`                                                              | You want the structured `update_plan` tool exposed for multi-step work tracking in compatible runtimes and UIs | [Gateway configuration reference](/gateway/config-tools#toolsexperimental)                    |
+
+## Local model lean mode
+
+`agents.defaults.experimental.localModelLean: true` is a pressure-release valve for weaker local-model setups. When it is on, Nodmix drops three default tools — `browser`, `cron`, and `message` — from the agent's tool surface for every turn. Nothing else changes. Use `agents.list[].experimental.localModelLean` to enable or disable the same behavior for one configured agent.
+
+### Why these three tools
+
+These three tools have the largest descriptions and the most parameter shapes in the default Nodmix runtime. On a small-context or stricter OpenAI-compatible backend that is the difference between:
+
+- Tool schemas fitting cleanly in the prompt vs. crowding out conversation history.
+- The model picking the right tool vs. emitting malformed tool calls because there are too many similar-looking schemas.
+- The Chat Completions adapter staying inside the server's structured-output limits vs. tripping a 400 on tool-call payload size.
+
+Removing them does not silently rewire Nodmix — it just makes the tool list shorter. The model still has `read`, `write`, `edit`, `exec`, `apply_patch`, web search/fetch (when configured), memory, and session/agent tools available.
+
+### When to turn it on
+
+Enable lean mode when you have already proved the model can talk to the Gateway but full agent turns misbehave. The typical signal chain is:
+
+1. `nodmix infer model run --gateway --model <ref> --prompt "Reply with exactly: pong"` succeeds.
+2. A normal agent turn fails with malformed tool calls, oversized prompts, or the model ignoring its tools.
+3. Toggling `localModelLean: true` clears the failure.
+
+### When to leave it off
+
+If your backend handles the full default runtime cleanly, leave this off. Lean mode is a workaround, not a default. It exists because some local stacks need a smaller tool surface to behave; hosted models and well-resourced local rigs do not.
+
+Lean mode also does not replace `tools.profile`, `tools.allow`/`tools.deny`, or the model `compat.supportsTools: false` escape hatch. If you need a permanent narrower tool surface for a specific agent, prefer those stable knobs over the experimental flag.
+
+### Enable
+
+```json5
+{
+  agents: {
+    defaults: {
+      experimental: {
+        localModelLean: true,
+      },
+    },
+  },
+}
+```
+
+For one agent only:
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "local",
+        model: "lmstudio/gemma-4-e4b-it",
+        experimental: {
+          localModelLean: true,
+        },
+      },
+    ],
+  },
+}
+```
+
+Restart the Gateway after changing the flag, then confirm the trimmed tool list with:
+
+```bash
+nodmix status --deep
+```
+
+The deep status output lists the active agent tools; `browser`, `cron`, and `message` should be absent when lean mode is on.
+
+## Experimental does not mean hidden
+
+If a feature is experimental, Nodmix should say so plainly in docs and in the
+config path itself. What it should **not** do is smuggle preview behavior into a
+stable-looking default knob and pretend that is normal. That's how config
+surfaces get messy.
+
+## Related
+
+- [Features](/concepts/features)
+- [Release channels](/install/development-channels)

package/docs/concepts/features.md

@@ -0,0 +1,91 @@
+---
+summary: "Nodmix capabilities across channels, routing, media, and UX."
+read_when:
+  - You want a full list of what Nodmix supports
+title: "Features"
+---
+
+## Highlights
+
+<Columns>
+  <Card title="Channels" icon="message-square" href="/channels">
+    Discord, iMessage, Signal, Slack, Telegram, WhatsApp, WebChat, and more with a single Gateway.
+  </Card>
+  <Card title="Plugins" icon="plug" href="/tools/plugin">
+    Bundled plugins add Matrix, Nextcloud Talk, Nostr, Twitch, Zalo, and more without separate installs in normal current releases.
+  </Card>
+  <Card title="Routing" icon="route" href="/concepts/multi-agent">
+    Multi-agent routing with isolated sessions.
+  </Card>
+  <Card title="Media" icon="image" href="/nodes/images">
+    Images, audio, video, documents, and image/video generation.
+  </Card>
+  <Card title="Apps and UI" icon="monitor" href="/web/control-ui">
+    Web Control UI and macOS companion app.
+  </Card>
+  <Card title="Mobile nodes" icon="smartphone" href="/nodes">
+    iOS and Android nodes with pairing, voice/chat, and rich device commands.
+  </Card>
+</Columns>
+
+## Full list
+
+**Channels:**
+
+- Built-in channels include Discord, Google Chat, iMessage, IRC, Signal, Slack, Telegram, WebChat, and WhatsApp
+- Bundled plugin channels include Feishu, LINE, Matrix, Mattermost, Microsoft Teams, Nextcloud Talk, Nostr, QQ Bot, Synology Chat, Tlon, Twitch, Zalo, and Zalo Personal
+- Optional separately installed channel plugins include Voice Call and third-party packages such as WeChat
+- Third-party channel plugins can extend the Gateway further, such as WeChat
+- Group chat support with mention-based activation
+- DM safety with allowlists and pairing
+
+**Agent:**
+
+- Embedded agent runtime with tool streaming
+- Multi-agent routing with isolated sessions per workspace or sender
+- Sessions: direct chats collapse into shared `main`; groups are isolated
+- Streaming and chunking for long responses
+
+**Auth and providers:**
+
+- 35+ model providers (Anthropic, OpenAI, Google, and more)
+- Subscription auth via OAuth (e.g. OpenAI Codex)
+- Custom and self-hosted provider support (vLLM, SGLang, Ollama, and any OpenAI-compatible or Anthropic-compatible endpoint)
+
+**Media:**
+
+- Images, audio, video, and documents in and out
+- Shared image generation and video generation capability surfaces
+- Voice note transcription
+- Text-to-speech with multiple providers
+
+**Apps and interfaces:**
+
+- WebChat and browser Control UI
+- macOS menu bar companion app
+- iOS node with pairing, Canvas, camera, screen recording, location, and voice
+- Android node with pairing, chat, voice, Canvas, camera, and device commands
+
+**Tools and automation:**
+
+- Browser automation, exec, sandboxing
+- Web search (Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG, Tavily)
+- Cron jobs and heartbeat scheduling
+- Skills, plugins, and workflow pipelines (Lobster)
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Experimental features" href="/concepts/experimental-features" icon="flask">
+    Opt-in features that have not yet shipped to the default surface.
+  </Card>
+  <Card title="Agent runtime" href="/concepts/agent" icon="robot">
+    Agent runtime model and how runs are dispatched.
+  </Card>
+  <Card title="Channels" href="/channels" icon="message-square">
+    Connect Telegram, WhatsApp, Discord, Slack, and more from one Gateway.
+  </Card>
+  <Card title="Plugins" href="/tools/plugin" icon="plug">
+    Bundled and third-party plugins that extend Nodmix.
+  </Card>
+</CardGroup>

package/docs/concepts/mantis-slack-desktop-runbook.md

@@ -0,0 +1,202 @@
+---
+summary: "Operator runbook for Mantis Slack desktop QA: GitHub dispatch, local CLI, warm VNC leases, hydrate modes, timing interpretation, artifacts, and failure handling."
+read_when:
+  - Running Mantis Slack desktop QA from GitHub or locally
+  - Debugging slow Mantis Slack desktop runs
+  - Choosing source, prehydrated, or warm-lease mode
+  - Posting screenshot and video evidence to a PR
+title: "Mantis Slack desktop runbook"
+---
+
+Mantis Slack desktop QA is the real-UI lane for Slack-class bugs that need a
+Linux desktop, VNC rescue, Slack Web, a real Nodmix gateway, screenshots,
+videos, and a PR evidence comment.
+
+Use it when unit tests or the headless Slack live lane cannot prove the bug.
+
+## Storage model
+
+Mantis uses three different storage layers:
+
+- Provider image: owned by Crabbox and stored in the cloud provider account.
+  It contains machine capabilities such as Chrome/Chromium, ffmpeg, scrot,
+  Node/corepack/pnpm, native build tools, and empty cache directories.
+- Warm lease state: owned by the current operator session. It can contain a
+  logged-in browser profile, `/var/cache/crabbox/pnpm`, and a prepared source
+  checkout while the lease is alive.
+- Mantis artifacts: owned by the Nodmix run. They live under
+  `.artifacts/qa-e2e/mantis/...`, then GitHub Actions uploads them and the
+  Mantis GitHub App comments inline evidence on the PR.
+
+Never put secrets, browser cookies, Slack login state, repository checkouts,
+`node_modules`, or `dist/` into a prebaked provider image.
+
+## GitHub dispatch
+
+Run the workflow from `main`:
+
+```bash
+gh workflow run mantis-slack-desktop-smoke.yml \
+  --ref main \
+  -f candidate_ref=<trusted-ref-or-sha> \
+  -f pr_number=<pr-number> \
+  -f scenario_id=slack-canary \
+  -f crabbox_provider=aws \
+  -f keep_vm=false \
+  -f hydrate_mode=source
+```
+
+Allowed `candidate_ref` values are intentionally narrow because the workflow
+uses live credentials: current `main` ancestry, release tags, or an open PR head
+from `nodmix/nodmix`.
+
+The workflow writes:
+
+- uploaded artifact: `mantis-slack-desktop-smoke-<run-id>-<attempt>`;
+- inline PR comment from the Mantis GitHub App;
+- `slack-desktop-smoke.png`;
+- `slack-desktop-smoke.mp4`;
+- `slack-desktop-smoke-preview.gif`;
+- `slack-desktop-smoke-change.mp4`;
+- `mantis-slack-desktop-smoke-summary.json`;
+- `mantis-slack-desktop-smoke-report.md`;
+- remote logs such as `slack-desktop-command.log`, `nodmix-gateway.log`,
+  `chrome.log`, and `ffmpeg.log`.
+
+The PR comment is updated in place by the hidden
+`<!-- mantis-slack-desktop-smoke -->` marker.
+
+## Local CLI
+
+Cold source proof:
+
+```bash
+pnpm nodmix qa mantis slack-desktop-smoke \
+  --provider aws \
+  --class standard \
+  --gateway-setup \
+  --credential-source convex \
+  --credential-role maintainer \
+  --provider-mode live-frontier \
+  --model openai/gpt-5.4 \
+  --alt-model openai/gpt-5.4 \
+  --scenario slack-canary \
+  --hydrate-mode source
+```
+
+Keep the VM for VNC rescue:
+
+```bash
+pnpm nodmix qa mantis slack-desktop-smoke \
+  --provider aws \
+  --class standard \
+  --gateway-setup \
+  --scenario slack-canary \
+  --keep-lease
+```
+
+Open VNC:
+
+```bash
+crabbox vnc --provider aws --id <cbx_id> --open
+```
+
+Reuse a warm lease:
+
+```bash
+pnpm nodmix qa mantis slack-desktop-smoke \
+  --provider aws \
+  --lease-id <cbx_id-or-slug> \
+  --gateway-setup \
+  --scenario slack-canary \
+  --hydrate-mode source
+```
+
+Use `--hydrate-mode prehydrated` only when the reused remote workspace already
+has `node_modules` and a built `dist/`. Mantis fails closed if those are
+missing.
+
+## Hydrate modes
+
+| Mode          | Use when                                  | Remote behavior                                                                       | Tradeoff                                                 |
+| ------------- | ----------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| `source`      | Normal PR proof, cold machines, CI        | Runs `pnpm install --frozen-lockfile --prefer-offline` and `pnpm build` inside the VM | Slowest, strongest source-checkout proof                 |
+| `prehydrated` | You intentionally prepared a reused lease | Requires existing `node_modules` and `dist/`; skips install/build                     | Fast, but only valid for operator-controlled warm leases |
+
+GitHub Actions always prepares the candidate checkout before the VM run. Its
+pnpm store is cached by OS, Node version, and lockfile. The VM source run also
+uses `/var/cache/crabbox/pnpm` when present.
+
+## Timing interpretation
+
+`mantis-slack-desktop-smoke-report.md` includes phase timings:
+
+- `crabbox.warmup`: cloud provider boot, desktop/browser readiness, and SSH.
+- `crabbox.inspect`: lease metadata lookup.
+- `credentials.prepare`: Convex credential lease acquisition.
+- `crabbox.remote_run`: sync, browser launch, Nodmix install/build or
+  hydrate validation, gateway startup, screenshot, and video capture.
+- `artifacts.copy`: rsync back from the VM.
+
+`crabbox.remote_run` can be marked `accepted` when Crabbox returns a non-zero
+remote status after Mantis has copied metadata proving that the Nodmix gateway
+is alive and the setup completed. Treat `accepted` as pass-with-explanation,
+not a failed scenario.
+
+If the run is slow:
+
+- warmup dominates: prebake or promote a better Crabbox provider image;
+- remote_run dominates in `source`: use a warm lease, improve pnpm store reuse,
+  or move machine prerequisites into the provider image;
+- remote_run dominates in `prehydrated`: the remote workspace was not actually
+  ready, or the gateway/browser/Slack setup is slow;
+- artifact copy dominates: inspect video size and artifact directory contents.
+
+## Evidence checklist
+
+A good PR comment should show:
+
+- scenario id and candidate SHA;
+- GitHub Actions run URL;
+- artifact URL;
+- inline screenshot;
+- inline animated preview when available;
+- full MP4 and trimmed MP4 links;
+- pass/fail status;
+- timing summary in the attached report.
+
+Do not commit screenshots or videos into the repository. Keep them in GitHub
+Actions artifacts or the PR comment.
+
+## Failure handling
+
+If the workflow fails before the VM run, inspect the Actions job first. Typical
+causes are untrusted `candidate_ref`, missing environment secrets, or candidate
+install/build failure.
+
+If the VM run fails but screenshots were copied back, inspect:
+
+```bash
+cat mantis-slack-desktop-smoke-report.md
+cat mantis-slack-desktop-smoke-summary.json
+cat slack-desktop-command.log
+cat nodmix-gateway.log
+cat chrome.log
+cat ffmpeg.log
+```
+
+If the run kept the lease, open VNC with the report's `crabbox vnc ...` command.
+Stop the lease when done:
+
+```bash
+crabbox stop --provider aws <cbx_id-or-slug>
+```
+
+If Slack login expired, repair it in VNC on a kept lease and rerun with
+`--lease-id`. Do not bake that browser profile into a provider image.
+
+## Related
+
+- [QA overview](/concepts/qa-e2e-automation)
+- [Slack channel](/channels/slack)
+- [Testing](/help/testing)