diff --git a/bin/mcp-server.js b/bin/mcp-server.js
index 776e31d22..f80ea0bad 100644
--- a/bin/mcp-server.js
+++ b/bin/mcp-server.js
@@ -12,8 +12,11 @@ import {
   snapshotDirFor,
   artifactsToFileUrls,
   writeTraceMarkdown,
+  TraceReader,
+  ariaDiff,
 } from '../lib/utils/trace.js'
 import event from '../lib/event.js'
+import recorder from '../lib/recorder.js'
 import { setPauseHandler, pauseNow } from '../lib/pause.js'
 import { EventEmitter } from 'events'
 import { fileURLToPath, pathToFileURL } from 'url'
@@ -32,6 +35,93 @@ const __dirname = dirname(__filename)
 let codecept = null
 let containerInitialized = false
 let browserStarted = false
+let shellSessionActive = false
+let bootstrapDone = false
+let currentPluginsSig = ''
+let currentAiTraceDir = null  // mirrors the dir aiTrace plugin computes per test/session
+
+event.dispatcher.on(event.test.before, test => {
+  try {
+    const title = (test && (test.fullTitle ? test.fullTitle() : test.title)) || 'MCP Session'
+    currentAiTraceDir = traceDirFor(test?.file, title, outputBaseDir())
+  } catch {}
+})
+
+const SESSION_REQUIRED_ERROR = 'No active CodeceptJS session. Call `start_browser` to open a shell session, or `run_test` (use `pause()` in the test, or set `pauseAt`) to inspect during a test run.'
+
+async function ensureBootstrap() {
+  if (bootstrapDone) return
+  await codecept.bootstrap()
+  bootstrapDone = true
+}
+
+async function startShellSession() {
+  if (shellSessionActive) return
+  await ensureBootstrap()
+  recorder.start()
+  event.emit(event.suite.before, {
+    fullTitle: () => 'MCP Session',
+    tests: [],
+    retries: () => {},
+  })
+  event.emit(event.test.before, {
+    title: 'MCP Session',
+    artifacts: {},
+    retries: () => {},
+  })
+  shellSessionActive = true
+}
+
+async function endShellSession() {
+  if (!shellSessionActive) return
+  try { event.emit(event.test.after, {}) } catch {}
+  try { event.emit(event.suite.after, {}) } catch {}
+  try { event.emit(event.all.result, {}) } catch {}
+  shellSessionActive = false
+}
+
+function ensureSession() {
+  if (shellSessionActive || pausedController) return
+  throw new Error(SESSION_REQUIRED_ERROR)
+}
+
+function normalizePluginOverrides(plugins) {
+  if (!plugins || typeof plugins !== 'object') return {}
+  const out = {}
+  for (const [name, opts] of Object.entries(plugins)) {
+    if (opts === false) continue
+    out[name] = (opts === true || opts == null) ? {} : opts
+  }
+  return out
+}
+
+function applyPluginOverrides(config, plugins) {
+  config.plugins = config.plugins || {}
+  for (const [name, opts] of Object.entries(plugins)) {
+    config.plugins[name] = { ...(config.plugins[name] || {}), ...opts, enabled: true }
+  }
+}
+
+function pluginsSignature(plugins) {
+  const keys = Object.keys(plugins).sort()
+  return JSON.stringify(keys.map(k => [k, plugins[k]]))
+}
+
+async function teardownContainer() {
+  if (!containerInitialized) return
+  await endShellSession()
+  const helpers = container.helpers()
+  for (const helperName in helpers) {
+    const helper = helpers[helperName]
+    try { if (helper._finish) await helper._finish() } catch {}
+  }
+  try { if (codecept?.teardown) await codecept.teardown() } catch {}
+  containerInitialized = false
+  browserStarted = false
+  bootstrapDone = false
+  codecept = null
+  currentPluginsSig = ''
+}
 
 let runLock = Promise.resolve()
 async function withLock(fn) {
@@ -318,8 +408,14 @@ function pausedPayload() {
   }
 }
 
-async function initCodecept(configPath) {
-  if (containerInitialized) return
+async function initCodecept(configPath, pluginOverrides) {
+  const plugins = normalizePluginOverrides(pluginOverrides)
+  const sig = pluginsSignature(plugins)
+
+  if (containerInitialized) {
+    if (!Object.keys(plugins).length || sig === currentPluginsSig) return
+    await teardownContainer()
+  }
 
   const testRoot = process.env.CODECEPTJS_PROJECT_DIR || process.cwd()
 
@@ -344,6 +440,11 @@ async function initCodecept(configPath) {
   const { getConfig } = await import('../lib/command/utils.js')
   const config = await getConfig(configPath)
 
+  // aiTrace is the canonical per-step ARIA/HTML/screenshot capture for MCP.
+  // Always on so run_code / continue can read the latest snapshot from disk
+  // instead of double-capturing through grabAriaSnapshot etc.
+  applyPluginOverrides(config, { aiTrace: {}, ...plugins })
+
   codecept = new Codecept(config, {})
   await codecept.init(testRoot)
   await container.create(config, {})
@@ -351,8 +452,11 @@ async function initCodecept(configPath) {
 
   containerInitialized = true
   browserStarted = true
+  currentPluginsSig = sig
 }
 
+const PLUGINS_DESCRIPTION = 'Enable CodeceptJS plugins for this run, mirroring the CLI `-p` flag. Keys are plugin names (e.g. screencast, aiTrace, pause, pageInfo, heal, retryFailedStep, screenshotOnFail, autoDelay). Value `true` or `{}` enables with defaults; an object merges options, e.g. {"screencast": {"saveScreenshots": true}, "aiTrace": {"on": "fail"}}. Changing the plugin set tears down and re-initializes the container (closes the browser).'
+
 const server = new Server(
   { name: 'codeceptjs-mcp-server', version: '1.0.0' },
   { capabilities: { tools: {} } }
@@ -394,6 +498,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           timeout: { type: 'number' },
           config: { type: 'string' },
           pauseAt: { type: 'number', description: '1-based step index. Test will pause after the Nth step completes. Useful as a programmatic breakpoint without editing the test.' },
+          plugins: { type: 'object', description: PLUGINS_DESCRIPTION, additionalProperties: true },
         },
         required: ['test'],
       },
@@ -407,6 +512,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           test: { type: 'string' },
           timeout: { type: 'number' },
           config: { type: 'string' },
+          plugins: { type: 'object', description: PLUGINS_DESCRIPTION, additionalProperties: true },
         },
         required: ['test'],
       },
@@ -497,33 +603,26 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       case 'start_browser': {
         const configPath = args?.config
-        if (browserStarted) {
-          return { content: [{ type: 'text', text: JSON.stringify({ status: 'Browser already started' }, null, 2) }] }
+        if (browserStarted && shellSessionActive) {
+          return { content: [{ type: 'text', text: JSON.stringify({ status: 'Session already active' }, null, 2) }] }
         }
         await initCodecept(configPath)
-        return { content: [{ type: 'text', text: JSON.stringify({ status: 'Browser started successfully' }, null, 2) }] }
+        await startShellSession()
+        return { content: [{ type: 'text', text: JSON.stringify({ status: 'Session started — run_code and snapshot are now available' }, null, 2) }] }
       }
 
       case 'stop_browser': {
         if (!containerInitialized) {
           return { content: [{ type: 'text', text: JSON.stringify({ status: 'Browser not initialized' }, null, 2) }] }
         }
-
-        const helpers = container.helpers()
-        for (const helperName in helpers) {
-          const helper = helpers[helperName]
-          try { if (helper._finish) await helper._finish() } catch {}
-        }
-
-        browserStarted = false
-        containerInitialized = false
-
+        await teardownContainer()
         return { content: [{ type: 'text', text: JSON.stringify({ status: 'Browser stopped successfully' }, null, 2) }] }
       }
 
       case 'snapshot': {
         const { config: configPath, fullPage = false } = args || {}
         await initCodecept(configPath)
+        ensureSession()
 
         const helper = pickActingHelper(container.helpers())
         if (!helper) throw new Error('No supported acting helper available (Playwright, Puppeteer, WebDriver).')
@@ -588,6 +687,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'run_code': {
         const { code, timeout = 60000, config: configPath, saveArtifacts = true } = args
         await initCodecept(configPath)
+        ensureSession()
 
         const I = container.support('I')
         if (!I) throw new Error('I object not available. Make sure helpers are configured.')
@@ -604,6 +704,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         mkdirp.sync(traceDir)
         const startedAt = Date.now()
 
+        // Pin the latest aiTrace ARIA file before running the code, so we
+        // can diff after. aiTrace owns per-step capture; we just read it.
+        const reader = new TraceReader(currentAiTraceDir)
+        const ariaBefore = reader.last('aria')
+
         const MAX_LOG_ENTRIES = 100
         const MAX_LOG_MSG_BYTES = 2000
         const MAX_RETURN_BYTES = 20000
@@ -666,6 +771,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           }
         }
 
+        // Diff against the latest aiTrace ARIA file produced by the steps
+        // that just ran inside this run_code call.
+        const ariaAfter = reader.last('aria')
+        if (ariaBefore && ariaAfter && ariaBefore !== ariaAfter) {
+          const diff = ariaDiff(ariaBefore, ariaAfter)
+          if (diff) result.ariaDiff = diff
+        }
+
         const traceFile = writeTraceMarkdown({
           dir: traceDir,
           title: 'run_code',
@@ -686,8 +799,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           if (pausedController) {
             throw new Error('A previous run_test is still paused. Call "continue" first.')
           }
-          const { test, timeout = 60000, config: configPathArg, pauseAt } = args || {}
-          await initCodecept(configPathArg)
+          const { test, timeout = 60000, config: configPathArg, pauseAt, plugins } = args || {}
+          await initCodecept(configPathArg, plugins)
+          await endShellSession()
 
           return await withSilencedIO(async () => {
             codecept.loadTests()
@@ -740,7 +854,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             let runError = null
             const runPromise = (async () => {
               try {
-                await codecept.bootstrap()
+                await ensureBootstrap()
                 await codecept.run(testFile)
               } catch (err) {
                 runError = err
@@ -779,8 +893,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           if (pausedController) {
             throw new Error('A previous run is still paused. Call "continue" first.')
           }
-          const { test, timeout = 60000, config: configPath } = args || {}
-          await initCodecept(configPath)
+          const { test, timeout = 60000, config: configPath, plugins } = args || {}
+          await initCodecept(configPath, plugins)
+          await endShellSession()
 
           return await withSilencedIO(async () => {
             codecept.loadTests()
@@ -832,7 +947,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             let runError = null
             const runPromise = (async () => {
               try {
-                await codecept.bootstrap()
+                await ensureBootstrap()
                 await codecept.run(testFile)
               } catch (err) {
                 runError = err
diff --git a/docs/agents.md b/docs/agents.md
new file mode 100644
index 000000000..3358256bd
--- /dev/null
+++ b/docs/agents.md
@@ -0,0 +1,159 @@
+---
+permalink: /agents
+title: Agentic Testing
+---
+
+# Agentic Testing
+
+CodeceptJS ships an **MCP server and a skillset** that lets an AI agent (Claude Code, Cursor, Codex, others) write and fix tests by driving the real browser. The agent runs the same `I.*` commands the test does, reads how the page responds, and only commits the lines that succeeded.
+
+## Why MCP
+
+The traditional agent testing loop is test/fix/retry, where the agent executes a test, watches it fail, reads artifacts, performs code fixes, and reruns the test. The agent applies fixes by intelligent guess — looking at the ARIA tree, HTML, and screenshot — then assumes the fix is enough and reruns the test hoping it will pass. If the guess is wrong and the test runs for over a minute, it may take dozens of minutes of iteration and a lot of wasted tokens.
+
+To improve that flow, the agent can spawn a browser and open the page the way the test does. This lets it interact with the page more freely and perform multi-step actions. But putting that experience back into test code is not efficient either: actions executed in the browser may not be relevant in test context, so the agent ends up in another guess-and-try loop.
+
+The problem is that **the test runs in a different context than the agent**.
+
+The agent can launch a test but can't control it while it's running. It can't access the browser. It can't set a breakpoint.
+
+This is where CodeceptJS MCP steps in. Connected to the agent, it can:
+
+- run a test and pause it on failure
+- interact with the browser in a test context
+- test locators and perform actions live while the test is running
+- write successful actions to the test file
+
+This lets the agent get a test working in one iteration. The agent can live-write the test before your eyes by exploring the page and performing actions that eventually land in the CodeceptJS test file.
+
+**Live debugging of tests** is what CodeceptJS MCP provides. The agent receives feedback faster — not from a whole test execution but from specific actions on a specific page — so it can adjust and react faster, trying different approaches.
+
+The MCP server is the agent-facing equivalent of the `pause()` REPL — same access, driven by tool calls instead of keystrokes. Full tool reference at [/mcp](/mcp).
+
+## The loop
+
+Whether the agent is writing a new test or fixing an old one, it follows the same cycle.
+
+1. **Open the page.** Run a stub test (new work) or set a breakpoint at the failing step (fix). The browser lands at the right starting point and yields control to the agent.
+2. **Read the page.** MCP saves HTML, ARIA, and screenshot of the page to files (and the agent can call the `snapshot` tool to refresh them). The agent reads those files before deciding what to try next, controlling its token usage.
+3. **Run a CodeceptJS command.** The agent tries `I.*` commands like `I.click('Add to cart')`, `I.fillField('Email', secret(process.env.EMAIL))`, `I.see('Confirmed')`. On success, that line goes into the test — same syntax.
+4. **Check the result.** The response after each command shows the new page state. If the URL changed and the modal opened, the line goes into the verified sequence. If not, the agent reads the page again and tries a different locator or a wait.
+5. **Move forward.** The agent looks at the new state and chooses the next command. Steps 2–4 repeat until the scenario is whole.
+6. **Commit to the file.** The agent edits the test — replaces `pause()` (new tests) or the broken line (fixes) with the verified sequence — then reruns end-to-end and reads the trace to confirm.
+
+## How the agent reads the page
+
+MCP commands are token efficient — they don't stream large HTML pages back to the model. MCP writes artifacts to disk under `output/trace_*/` and returns file paths. The agent reads each artifact with its own bash tools — `cat`, `grep`, `jq`.
+
+A `run_code` response, for example, looks like this:
+
+```json
+{
+  "status": "success",
+  "artifacts": {
+    "url": "http://localhost:8000/",
+    "html": "file:///output/trace_run_code_.../mcp_page.html",
+    "aria": "file:///output/trace_run_code_.../mcp_aria.txt",
+    "screenshot": "file:///output/trace_run_code_.../mcp_screenshot.png",
+    "console": "file:///output/trace_run_code_.../mcp_console.json",
+    "storage": "file:///output/trace_run_code_.../mcp_storage.json"
+  }
+}
+```
+
+Only `url` is inline. The rest are paths the agent opens with the right tool:
+
+| Artifact | How the agent reads it |
+|----------|------------------------|
+| `*_screenshot.png` | As an image — most agents are multimodal |
+| `*_aria.txt` | Whole — small and structured |
+| `*_page.html` | With `grep` — too large for context, searchable for specific elements/attributes |
+| `*_console.json` | With `jq` — filter for errors, 4xx/5xx, deprecation warnings |
+| `*_storage.json` | Whole — cookies and `localStorage` snapshot |
+| `trace.md` | Whole — markdown index linking every step to its artifacts |
+
+Saved HTML is formatted, with non-semantic elements stripped out: `<style>`, `<script>`, Tailwind-style trash classes, and inline `style=""` attributes. `grep` can then effectively find the correct tree branch in raw page source. ARIA snapshots are smaller and more structured than HTML, which is why the agent prefers them when picking locators.
+
+## Setup
+
+When CodeceptJS is installed, the MCP server can be launched with this command:
+
+```bash
+npx codeceptjs-mcp
+```
+
+> See [/mcp](/mcp) for detailed client setup.
+
+We recommend pairing CodeceptJS MCP with the skills bundle.
+
+Install for any agent:
+
+```bash
+npx skills add codeceptjs/skills
+```
+
+Or, in Claude Code:
+
+```text
+/plugin marketplace add codeceptjs/skills
+/plugin install codeceptjs@codeceptjs-skills
+```
+
+## Usage Examples
+
+When MCP and skills are connected, the agent receives predefined workflows and can act effectively for testing purposes. Common scenarios it handles:
+
+### Writing a new test
+
+You ask: "Add a test for the checkout flow."
+
+The agent writes a stub:
+
+```javascript
+Scenario('checkout', ({ I }) => {
+  I.amOnPage('/cart')
+  pause()
+})
+```
+
+It runs the stub. The browser opens at `/cart` and yields control at `pause()`. The agent reads the ARIA tree, runs `I.click('Add to cart')`, sees the cart total update — that line goes into the verified sequence. It runs `I.fillField('Email', '...')`, sees the field accept the value, records it. Through `I.click('Continue to payment')`, `I.see('Payment')`, `I.fillField('Card', secret(process.env.TEST_CARD))`, `I.click('Pay')`, `I.see('Order confirmed')` — each command commits only after the response confirms it worked.
+
+When the scenario is whole, the agent edits the test file: replaces `pause()` with the verified sequence, renames the scenario, wraps credentials with `secret()`. It reruns the file end-to-end with `aiTrace` on and hands you the diff.
+
+### Fixing a failing test
+
+A test fails. You point the agent at the scenario.
+
+It opens `output/trace_<TestName>_*/trace.md` from the last run, reads the steps, and finds the one marked failed. Most of the time the screenshot and ARIA from that step explain the cause — "Save" is now "Save changes," or a spinner is gating the next action. The agent patches the line and reruns.
+
+When the trace doesn't say enough, the agent passes a step number to `run_test` so the test pauses right before the failing step. From the live page, it tries `I.click({ role: 'button', name: 'Save changes' })`, sees the modal close. Or `I.waitForInvisible('.spinner', 10)` followed by the original click — watches it pass. Whatever holds goes into the test.
+
+The fix lands with a one-line note explaining what changed.
+
+### Auto-fixing on CI
+
+After a failed run, the agent reads every trace under `output/`, clusters failures by signature, and patches what fits a small set of safe fixes (locator drift, missing waits, raw `I.wait(N)` replacement). It reruns only the failing scenarios, compares against the baseline, and writes a markdown report at `output/ci-fix.md`.
+
+If the fix held, the PR goes green. If it didn't, every edit is rolled back with `git checkout` and the report says which patterns the agent couldn't safely handle. No half-applied fixes left behind, no `retries: 3` masking the problem.
+
+## Skills bundle
+
+Skills teach the agent best practices for using CodeceptJS. Plug them in when you develop tests with agents, and update them regularly to ensure you use CodeceptJS in the most effective way.
+
+| Skill | Use case |
+|-------|----------|
+| `writing-codeceptjs-tests` | Author or extend a scenario. Runs the loop above with a stub-and-pause flow for greenfield work, incremental `run_code` for known flows. |
+| `debugging-codeceptjs-tests` | A test is failing or flaky. Reads the trace, decides whether to patch from the trace alone or set a breakpoint on the live page. |
+| `ci-fix-tests` | Conservative auto-repair on CI |
+| `refactoring-codeceptjs-tests` | Extract page objects, tame long locators, move raw browser code into helpers. Proposes in batches. |
+| `codeceptjs-fundamentals` | Obtain actual CodeceptJS knowledge. |
+| `codeceptjs-exploration` | Pick a stable locator from messy markup. |
+| `codeceptjs-run-analysis` | Read trace artifacts, cluster CI failures into root causes, verify a fix held across many traces. |
+| `codeceptjs-auth` | Authorize efficiently with `auth` plugin. |
+
+## Pointers
+
+- [/mcp](/mcp) — full MCP tool reference, client setup
+- [/aitrace](/aitrace) — trace plugin configuration and capture options
+- [/debugging](/debugging) — pause modes, IDE setup, the `pause` plugin
+- [skills repo](https://github.com/codeceptjs/skills) — source and install for non-Claude clients
diff --git a/lib/aria.js b/lib/aria.js
new file mode 100644
index 000000000..f4a05fe31
--- /dev/null
+++ b/lib/aria.js
@@ -0,0 +1,260 @@
+import yaml from 'js-yaml'
+
+// ─────────────────────────────────────────────────────────────────
+// Roles
+// ─────────────────────────────────────────────────────────────────
+
+const INTERACTIVE_ROLES = new Set([
+  'button',
+  'link',
+  'textbox',
+  'searchbox',
+  'checkbox',
+  'radio',
+  'switch',
+  'combobox',
+  'listbox',
+  'listitem',
+  'menu',
+  'menuitem',
+  'menuitemcheckbox',
+  'menuitemradio',
+  'option',
+  'tab',
+  'tabpanel',
+  'slider',
+  'spinbutton',
+  'treeitem',
+  'gridcell',
+])
+
+// Long groups of same-role siblings get summarised as: first N + "...M omitted..." + last N
+const SIBLING_COLLAPSE_THRESHOLD = 50
+const SIBLING_COLLAPSE_KEEP_EACH_SIDE = 5
+
+// ─────────────────────────────────────────────────────────────────
+// STEP 1 · Parse: YAML text → AriaNode[]
+// ─────────────────────────────────────────────────────────────────
+
+function unquote(value) {
+  const v = value.trim()
+  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+    return v.slice(1, -1)
+  }
+  return v
+}
+
+// Parse one YAML node label like:  `button "Save"`,  `textbox "Email" [focused]`,  `heading "Title" [level=2]`
+function parseLabel(label) {
+  if (!label) return null
+  const trimmed = label.trim()
+  const roleMatch = trimmed.match(/^(\w+)/)
+  if (!roleMatch) return null
+  const role = roleMatch[1].toLowerCase()
+  let rest = trimmed.slice(roleMatch[0].length)
+
+  let name
+  const nameMatch = rest.match(/^\s*"((?:[^"\\]|\\.)*)"/) || rest.match(/^\s*'((?:[^'\\]|\\.)*)'/)
+  if (nameMatch) {
+    name = nameMatch[1]
+    rest = rest.slice(nameMatch[0].length)
+  }
+
+  const attributes = {}
+  const attrMatch = rest.match(/\[([^\]]*)\]/)
+  if (attrMatch) {
+    for (const tok of attrMatch[1].split(/[\s,]+/).filter(Boolean)) {
+      const eq = tok.indexOf('=')
+      if (eq === -1) {
+        attributes[tok.toLowerCase()] = true
+        continue
+      }
+      attributes[tok.slice(0, eq).trim().toLowerCase()] = unquote(tok.slice(eq + 1))
+    }
+  }
+
+  return { role, name, attributes }
+}
+
+function yamlItemToNode(item) {
+  if (typeof item === 'string') {
+    const label = parseLabel(item)
+    if (!label) return null
+    const node = { role: label.role, name: label.name, attributes: label.attributes, children: [] }
+    return node
+  }
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return null
+
+  const entries = Object.entries(item)
+  if (entries.length === 0) return null
+  const [key, value] = entries[0]
+  const label = parseLabel(key)
+  if (!label) return null
+  const node = { role: label.role, name: label.name, attributes: label.attributes, children: [] }
+
+  if (Array.isArray(value)) {
+    node.children = value.map(yamlItemToNode).filter(n => n !== null)
+    return node
+  }
+  if (value !== null && value !== undefined) node.value = String(value)
+  return node
+}
+
+function parseSnapshot(snapshot) {
+  if (!snapshot) return []
+  let parsed
+  try {
+    parsed = yaml.load(snapshot)
+  } catch {
+    return []
+  }
+  if (!Array.isArray(parsed)) return []
+  return parsed.map(yamlItemToNode).filter(n => n !== null)
+}
+
+// ─────────────────────────────────────────────────────────────────
+// STEP 2 · Transform: drop containers that contribute nothing.
+// ─────────────────────────────────────────────────────────────────
+
+function dropEmpty(nodes) {
+  return nodes.flatMap(node => {
+    const children = dropEmpty(node.children)
+    if (INTERACTIVE_ROLES.has(node.role)) return [{ ...node, children }]
+    if (children.length > 0) return [{ ...node, children }]
+    return []
+  })
+}
+
+// ─────────────────────────────────────────────────────────────────
+// STEP 3 · Render: AriaNode[] → indented YAML text
+// ─────────────────────────────────────────────────────────────────
+
+// One-line representation of a node. Stable attr order so diff comparisons are deterministic.
+function formatNode(node) {
+  let line = node.role
+  if (node.name && node.name.trim()) line += ` "${node.name.trim()}"`
+  const attrParts = []
+  for (const k of Object.keys(node.attributes).sort()) {
+    const v = node.attributes[k]
+    if (v === undefined || v === null || v === '') continue
+    if (v === true) attrParts.push(k)
+    else attrParts.push(`${k}=${v}`)
+  }
+  if (attrParts.length > 0) line += ` [${attrParts.join(' ')}]`
+  if (node.value !== undefined && node.value !== null) {
+    const text = String(node.value).trim()
+    if (text) line += `: ${text}`
+  }
+  return line
+}
+
+// Group consecutive same-role siblings.  [a,a,b,a,a,a] → [[a,a],[b],[a,a,a]]
+function groupByConsecutiveRole(nodes) {
+  return nodes.reduce((groups, node) => {
+    const last = groups[groups.length - 1]
+    if (last && last[0].role === node.role) {
+      last.push(node)
+      return groups
+    }
+    groups.push([node])
+    return groups
+  }, [])
+}
+
+// Large group of same-role siblings → first N + placeholder line + last N.
+// Returns mix of AriaNode (to render) and pre-rendered placeholder strings.
+function collapseGroup(group, depth) {
+  if (group.length <= SIBLING_COLLAPSE_THRESHOLD) return group
+  const keep = SIBLING_COLLAPSE_KEEP_EACH_SIDE
+  const omitted = group.length - keep * 2
+  const placeholder = `${'  '.repeat(depth)}- ...${omitted} similar "${group[0].role}" items omitted...`
+  return [...group.slice(0, keep), placeholder, ...group.slice(-keep)]
+}
+
+function renderTree(nodes, depth = 0) {
+  const items = groupByConsecutiveRole(nodes).flatMap(group => collapseGroup(group, depth))
+  return items
+    .map(item => {
+      if (typeof item === 'string') return item
+      const indent = '  '.repeat(depth)
+      const head = `${indent}- ${formatNode(item)}`
+      if (item.children.length === 0) return head
+      return `${head}:\n${renderTree(item.children, depth + 1)}`
+    })
+    .join('\n')
+}
+
+// ─────────────────────────────────────────────────────────────────
+// STEP 4 · Diff: collect interactive summaries → bag diff → text
+// ─────────────────────────────────────────────────────────────────
+
+// Walk tree, emit one summary string per meaningful interactive node.
+function collectSummaries(nodes) {
+  return nodes.flatMap(node => {
+    const fromChildren = collectSummaries(node.children)
+    if (!INTERACTIVE_ROLES.has(node.role)) return fromChildren
+    const summary = formatNode(node)
+    if (summary === node.role) return fromChildren  // skip empty unnamed interactive nodes
+    return [summary, ...fromChildren]
+  })
+}
+
+function countBy(items) {
+  return items.reduce((map, item) => {
+    map.set(item, (map.get(item) ?? 0) + 1)
+    return map
+  }, new Map())
+}
+
+// Bag diff: any summary appearing more in one bag than the other becomes added/removed.
+function diffSummaries(prev, curr) {
+  const before = countBy(prev)
+  const after = countBy(curr)
+  const added = []
+  const removed = []
+  for (const summary of new Set([...before.keys(), ...after.keys()])) {
+    const b = before.get(summary) ?? 0
+    const a = after.get(summary) ?? 0
+    for (let i = 0; i < a - b; i += 1) added.push(summary)
+    for (let i = 0; i < b - a; i += 1) removed.push(summary)
+  }
+  return { added, removed }
+}
+
+function formatDiff(added, removed) {
+  if (added.length === 0 && removed.length === 0) return null
+  const lines = ['ariaDiff:']
+  if (added.length === 0) {
+    lines.push('  added: []')
+  } else {
+    lines.push('  added:')
+    for (const [item, count] of [...countBy(added).entries()].sort(([a], [b]) => a.localeCompare(b))) {
+      const suffix = count > 1 ? ` (x${count})` : ''
+      lines.push(`    - ${item}${suffix}`)
+    }
+  }
+  if (removed.length === 0) {
+    lines.push('  removed: []')
+  } else {
+    lines.push(`  removed: ${removed.length} interactive elements`)
+  }
+  return lines.join('\n')
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Public API — pipelines composed visibly, top-to-bottom
+// ─────────────────────────────────────────────────────────────────
+
+function compactAriaSnapshot(snapshot) {
+  if (!snapshot) return ''
+  const tree = dropEmpty(parseSnapshot(snapshot))
+  return renderTree(tree)
+}
+
+function diffAriaSnapshots(previous, current) {
+  const summariesOf = snap => collectSummaries(dropEmpty(parseSnapshot(snap)))
+  const { added, removed } = diffSummaries(summariesOf(previous), summariesOf(current))
+  return formatDiff(added, removed)
+}
+
+export { diffAriaSnapshots, compactAriaSnapshot }
diff --git a/lib/utils/trace.js b/lib/utils/trace.js
index af6f5863b..a62ded4b5 100644
--- a/lib/utils/trace.js
+++ b/lib/utils/trace.js
@@ -5,6 +5,7 @@ import { pathToFileURL } from 'url'
 import Container from '../container.js'
 import { clearString } from '../utils.js'
 import { formatHtml } from '../html.js'
+import { diffAriaSnapshots } from '../aria.js'
 
 // ---------------------------------------------------------------------------
 // Helper / directory naming
@@ -238,3 +239,59 @@ export async function captureSnapshot(helper, {
 
   return out
 }
+
+// ---------------------------------------------------------------------------
+// TraceReader — read artifacts already on disk (written by aiTrace, MCP, etc.)
+// ---------------------------------------------------------------------------
+
+const KIND_SUFFIX = {
+  aria: '_aria.txt',
+  html: '_page.html',
+  screenshot: '_screenshot.png',
+  console: '_console.json',
+  storage: '_storage.json',
+}
+
+export class TraceReader {
+  constructor(dir) {
+    this.dir = dir
+  }
+
+  // Filenames of a given kind, sorted in capture order. aiTrace prefixes with
+  // a zero-padded step index (`0000_`, `0001_`...), so a lexical sort is
+  // chronological.
+  list(kind) {
+    const suffix = KIND_SUFFIX[kind]
+    if (!suffix || !this.dir || !fs.existsSync(this.dir)) return []
+    let entries
+    try { entries = fs.readdirSync(this.dir) } catch { return [] }
+    return entries.filter(f => f.endsWith(suffix)).sort()
+  }
+
+  // Path of the n-th file of `kind`, or null. Python-style indexing:
+  // 0..N-1 from the start, -1..-N from the end.
+  pathAt(n, kind) {
+    const files = this.list(kind)
+    if (!files.length) return null
+    const i = n < 0 ? files.length + n : n
+    if (i < 0 || i >= files.length) return null
+    return path.join(this.dir, files[i])
+  }
+
+  // Read content of the n-th file of `kind`. Binary kinds (screenshot) are
+  // returned as Buffer; text kinds as utf8 string.
+  nth(n, kind) {
+    const p = this.pathAt(n, kind)
+    if (!p) return null
+    try {
+      if (kind === 'screenshot') return fs.readFileSync(p)
+      return fs.readFileSync(p, 'utf8')
+    } catch { return null }
+  }
+
+  first(kind) { return this.nth(0, kind) }
+  last(kind)  { return this.nth(-1, kind) }
+  count(kind) { return this.list(kind).length }
+}
+
+export const ariaDiff = diffAriaSnapshots
diff --git a/test/unit/utils/trace_test.js b/test/unit/utils/trace_test.js
index 573695f6f..393fcfd07 100644
--- a/test/unit/utils/trace_test.js
+++ b/test/unit/utils/trace_test.js
@@ -12,6 +12,8 @@ import {
   artifactsToFileUrls,
   writeTraceMarkdown,
   captureSnapshot,
+  TraceReader,
+  ariaDiff,
 } from '../../../lib/utils/trace.js'
 
 function makeTmpDir(prefix = 'trace-test') {
@@ -430,4 +432,70 @@ describe('lib/utils/trace.js', () => {
       expect(out.html).to.equal('snapshot_page.html')
     })
   })
+
+  describe('TraceReader', () => {
+    let dir
+
+    beforeEach(() => {
+      dir = makeTmpDir('trace-reader')
+      fs.writeFileSync(path.join(dir, '0000_amOnPage_aria.txt'), '- button "Login"')
+      fs.writeFileSync(path.join(dir, '0001_fillField_aria.txt'), '- button "Login"\n- textbox "Email"')
+      fs.writeFileSync(path.join(dir, '0002_click_aria.txt'), '- button "Logout"')
+      fs.writeFileSync(path.join(dir, '0000_amOnPage_page.html'), '<html>1</html>')
+      fs.writeFileSync(path.join(dir, '0002_click_page.html'), '<html>3</html>')
+    })
+
+    afterEach(() => rmDir(dir))
+
+    it('list returns files of a kind in capture order', () => {
+      const reader = new TraceReader(dir)
+      expect(reader.list('aria')).to.deep.equal([
+        '0000_amOnPage_aria.txt',
+        '0001_fillField_aria.txt',
+        '0002_click_aria.txt',
+      ])
+      expect(reader.list('html')).to.deep.equal([
+        '0000_amOnPage_page.html',
+        '0002_click_page.html',
+      ])
+    })
+
+    it('first / last / nth read content with python-style indexing', () => {
+      const reader = new TraceReader(dir)
+      expect(reader.first('aria')).to.equal('- button "Login"')
+      expect(reader.last('aria')).to.equal('- button "Logout"')
+      expect(reader.nth(0, 'aria')).to.equal('- button "Login"')
+      expect(reader.nth(1, 'aria')).to.equal('- button "Login"\n- textbox "Email"')
+      expect(reader.nth(-1, 'aria')).to.equal('- button "Logout"')
+      expect(reader.nth(-2, 'aria')).to.equal('- button "Login"\n- textbox "Email"')
+    })
+
+    it('returns null for out-of-range or missing kinds', () => {
+      const reader = new TraceReader(dir)
+      expect(reader.nth(99, 'aria')).to.be.null
+      expect(reader.nth(-99, 'aria')).to.be.null
+      expect(reader.first('storage')).to.be.null
+      expect(reader.first('bogus')).to.be.null
+    })
+
+    it('returns empty list for missing or non-existent dir', () => {
+      expect(new TraceReader(null).list('aria')).to.deep.equal([])
+      expect(new TraceReader('/no/such/path').list('aria')).to.deep.equal([])
+      expect(new TraceReader(null).last('aria')).to.be.null
+    })
+
+    it('count returns the number of files for a kind', () => {
+      const reader = new TraceReader(dir)
+      expect(reader.count('aria')).to.equal(3)
+      expect(reader.count('html')).to.equal(2)
+      expect(reader.count('storage')).to.equal(0)
+    })
+
+    it('ariaDiff(prev, last) reports what changed between two captures', () => {
+      const reader = new TraceReader(dir)
+      const diff = ariaDiff(reader.nth(-2, 'aria'), reader.last('aria'))
+      expect(diff).to.be.a('string')
+      expect(diff).to.match(/button "Logout"/)
+    })
+  })
 })