{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-marker-workflows-reference",
  "slug": "marker-workflows-reference",
  "title": "Agent Markers debugging workflows: practical reference",
  "summary": "Browser-debugging reference covering the agent-markers setup prompt, perspective-based exploratory QA, bounded event capture and marker schemas, browser/global APIs, privacy and cleanup, JSON and test-artifact exports, replay capsules, app-specific…",
  "category": "Verification",
  "tags": [
    "agent-markers",
    "debugging",
    "privacy"
  ],
  "sources": [
    {
      "label": "Portable Codex workflow resources",
      "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
    }
  ],
  "sourceUnits": [
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Agent Setup Prompt",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Big Idea",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Try This Now",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Start With 5 Monkeys",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Files To Inspect",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/When To Reach For This",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/How This Used To Work",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/The Mental Model",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Basic Browser Setup",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Global Test Surface",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Capture Types",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Marker Shape",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Export A Debug Packet",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Verify The Project",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Turn A Marker Export Into An Agent Prompt",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Bounded Replay Capsule",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/App-Specific Marker Flow",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Ask The Agent This",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/What To Confirm / How To Know It Worked",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/If It Goes Wrong",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/If It Goes Wrong/Marker Has No Note",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/If It Goes Wrong/Export Has Too Many Raw Logs",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/If It Goes Wrong/`nearbyEventIds` Is Empty",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/If It Goes Wrong/Sensitive Storage Values Were Captured",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/If It Goes Wrong/Console/Fetch Remains Patched",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/If It Goes Wrong/Test Runner Cannot Export",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/If It Goes Wrong/Screenshot Or DOM Hook Is Missing",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/References And Resources",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "verification",
  "wordCount": 2700,
  "url": "/topics/codex-marker-workflows-reference/",
  "markdownUrl": "/markdown/codex-marker-workflows-reference.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-marker-workflows-reference.json",
  "headings": [
    {
      "id": "agent-setup-prompt",
      "text": "Agent Setup Prompt",
      "level": 2
    },
    {
      "id": "big-idea",
      "text": "Big Idea",
      "level": 2
    },
    {
      "id": "try-this-now",
      "text": "Try This Now",
      "level": 2
    },
    {
      "id": "start-with-5-monkeys",
      "text": "Start With 5 Monkeys",
      "level": 2
    },
    {
      "id": "files-to-inspect",
      "text": "Files To Inspect",
      "level": 2
    },
    {
      "id": "when-to-reach-for-this",
      "text": "When To Reach For This",
      "level": 2
    },
    {
      "id": "how-this-used-to-work",
      "text": "How This Used To Work",
      "level": 2
    },
    {
      "id": "the-mental-model",
      "text": "The Mental Model",
      "level": 2
    },
    {
      "id": "basic-browser-setup",
      "text": "Basic Browser Setup",
      "level": 2
    },
    {
      "id": "global-test-surface",
      "text": "Global Test Surface",
      "level": 2
    },
    {
      "id": "capture-types",
      "text": "Capture Types",
      "level": 2
    },
    {
      "id": "marker-shape",
      "text": "Marker Shape",
      "level": 2
    },
    {
      "id": "export-a-debug-packet",
      "text": "Export A Debug Packet",
      "level": 2
    },
    {
      "id": "verify-the-project",
      "text": "Verify The Project",
      "level": 2
    },
    {
      "id": "turn-a-marker-export-into-an-agent-prompt",
      "text": "Turn A Marker Export Into An Agent Prompt",
      "level": 2
    },
    {
      "id": "bounded-replay-capsule",
      "text": "Bounded Replay Capsule",
      "level": 2
    },
    {
      "id": "app-specific-marker-flow",
      "text": "App-Specific Marker Flow",
      "level": 2
    },
    {
      "id": "ask-the-agent-this",
      "text": "Ask The Agent This",
      "level": 2
    },
    {
      "id": "what-to-confirm-how-to-know-it-worked",
      "text": "What To Confirm / How To Know It Worked",
      "level": 2
    },
    {
      "id": "if-it-goes-wrong",
      "text": "If It Goes Wrong",
      "level": 2
    },
    {
      "id": "marker-has-no-note",
      "text": "Marker Has No Note",
      "level": 3
    },
    {
      "id": "export-has-too-many-raw-logs",
      "text": "Export Has Too Many Raw Logs",
      "level": 3
    },
    {
      "id": "nearbyeventids-is-empty",
      "text": "`nearbyEventIds` Is Empty",
      "level": 3
    },
    {
      "id": "sensitive-storage-values-were-captured",
      "text": "Sensitive Storage Values Were Captured",
      "level": 3
    },
    {
      "id": "console-fetch-remains-patched",
      "text": "Console/Fetch Remains Patched",
      "level": 3
    },
    {
      "id": "test-runner-cannot-export",
      "text": "Test Runner Cannot Export",
      "level": 3
    },
    {
      "id": "screenshot-or-dom-hook-is-missing",
      "text": "Screenshot Or DOM Hook Is Missing",
      "level": 3
    },
    {
      "id": "references-and-resources",
      "text": "References And Resources",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Agent Markers debugging workflows: practical reference\n\n## Agent Setup Prompt\n\n```text\nSet up the agent-markers files and configuration for this browser project, then verify the setup before investigating any specific bug.\n\n1. Inspect the existing agent-markers package and demo files first:\n   - packages/client/src/index.ts\n   - packages/client/src/collector.ts\n   - packages/client/src/types.ts\n   - packages/client/src/capture/console.ts\n   - packages/client/src/capture/fetch.ts\n   - packages/client/src/capture/errors.ts\n   - packages/client/src/serialize.ts\n   - apps/demo/src/main.ts\n   - apps/demo/src/viewer.ts\n   - scripts/smoke-demo.mjs\n   - docs/WORKSHOP.md\n\n2. If the package or demo is missing, scaffold the smallest matching structure. If files already exist, preserve the current API where possible and extend it only as needed.\n\n3. Define or confirm the core schema:\n   - DebugSession: one bounded run with sessionId, appName, schemaVersion, CapturedEvent[], and DebugMoment[]\n   - CapturedEvent: id, sequence, timestamp, type, and metadata for console, fetch, error, manual, DOM, screenshot, or app events\n   - DebugMoment: id, label, note, optional nextAction, timestamp, and nearbyEventIds that reference CapturedEvent ids\n   - export JSON: a JSON-serializable packet that can be saved, attached to a test run, or passed to another agent\n\n4. Implement or confirm createAgentMarkers in packages/client/src/index.ts. It should accept appName, exposeGlobal, and capture options for console, fetch, and errors. It should return mark(...), export(), and stop().\n\n5. Implement console, fetch, error, and manual capture:\n   - console capture records log/warn/error metadata without creating recursive logging loops\n   - fetch capture records URL, method, status, timing, and failure metadata\n   - error capture records thrown errors and unhandled rejections\n   - manual capture records marker labels, notes, nextAction, and timing\n   - all captured events should receive stable ids and sequence numbers\n\n6. Add privacy-safe defaults:\n   - capture metadata by default\n   - do not export storage values, cookies, tokens, request bodies, response bodies, private DOM text, or screenshots unless deliberately enabled and reviewed\n   - redact sensitive query params, headers, stack paths, and visible private text before saving export JSON\n   - include redaction notes in the exported packet\n\n7. Implement the collector in packages/client/src/collector.ts. Store events in order, enforce a maximum event count, and calculate nearbyEventIds for each DebugMoment using sequence or timestamp proximity.\n\n8. Implement serialize.ts so export() always returns valid JSON without circular references. Optional DOM or screenshot fields should be marked unavailable when no hook is configured.\n\n9. Wire createAgentMarkers into the demo app in apps/demo/src/main.ts with exposeGlobal: true for dev/test and capture enabled for console, fetch, and errors. Add a manual marker entrypoint such as a debug button or keyboard shortcut that calls markers.mark({ label, note, nextAction }).\n\n10. Wire apps/demo/src/viewer.ts so the current session can be exported, displayed, copied, or downloaded as JSON.\n\n11. Expose the dev/test global surface when configured:\n   - window.__AGENT_MARKERS__.mark(...)\n   - window.__AGENT_MARKERS__.export()\n   - window.__AGENT_MARKERS__.stop()\n\n12. Add test-runner export. In a Playwright-style test or equivalent, wait until the app is ready, call window.__AGENT_MARKERS__.mark(...), export the session with page.evaluate, and attach or save agent-markers.json. Assert markers.length > 0, a non-empty note exists, nearbyEventIds is present, and console/fetch/error/manual events appear when enabled.\n\n13. Add bounded replay packet setup for one marker. The packet should include schemaVersion, sessionId, markerId, markerCutoffSeq, nearbyEventIds, filtered console/fetch/error/manual evidence, optional DOM/screenshot availability, included and excluded boundaries, maximum event count, redaction status, and the first verification command. Do not build a full recorder.\n\n14. Update scripts/smoke-demo.mjs so it can launch or exercise the demo, create one marker, trigger at least one console event, fetch event, and error event where practical, export JSON, parse it, and confirm the packet is non-empty.\n\n15. Verify with the available project commands:\n   - npm test\n   - npm run typecheck\n   - npm run build\n   - npm run smoke:demo\n\n16. Confirm setup worked:\n   - createAgentMarkers imports and initializes\n   - mark() creates a DebugMoment with a specific note\n   - nearbyEventIds is non-empty after nearby capture activity\n   - exported events include console, fetch, error, and manual types when enabled\n   - export JSON parses cleanly\n   - window.__AGENT_MARKERS__ is available in dev/test only\n   - stop() restores patched console, fetch, and error listeners\n   - test-runner export saves or attaches agent-markers.json\n   - privacy defaults exclude sensitive values\n\nReport the files changed, setup choices, verification commands and results, sample export path, privacy boundaries, unavailable hooks, and any failed checks. If setup checks fail, stop and report the blocker. Do not debug a specific product bug until the setup and verification pass.\n```\n\n## Big Idea\n\nStart by sending cheap perspective-based agents through weird paths. Then use\nagent markers to capture the exact moment that should become a bounded debug\npacket.\n\nCore pattern:\n\n```text\n5 Monkeys QA -> mark -> capture -> explain -> review/export\n```\n\nThe 5 Monkeys pattern finds strange states a happy-path check would miss. Agent\nmarkers turn one of those strange states into evidence another agent can use.\n\nAn agent marker is a human-intent anchor inside a debugging workflow.\n\nIt answers:\n\n- why this moment mattered\n- what evidence was nearby\n- what should be inspected next\n- what the next human or agent should not waste time guessing\n\nAgent markers are not full replay systems. They are bounded debug packets.\n\n## Try This Now\n\nCreate one marker for a checkout UI bug:\n`window.__AGENT_MARKERS__.mark({ label: \"checkout disabled unexpectedly\", note: \"Expected submit to enable after terms and shipping were selected.\" })`\nExport the session and check that the marker has nearby evidence, not just a label.\n\n## Start With 5 Monkeys\n\nUse 5 Monkeys before marker capture when the bug is vague, stateful, or hidden\nbehind normal user behavior.\n\nAssign one lens per pass:\n\n| Lens | What It Tries |\n| --- | --- |\n| expert power user | shortcuts, fast navigation, hidden affordances |\n| brand-new first-time user | confusion, missing affordances, unclear copy |\n| inexperienced user | accidental clicks, mistaken paths, recovery failures |\n| impatient returning user | rapid clicks, skipped steps, partial flows |\n\nMake each pass explore weird paths:\n\n- keyboard shortcut sequences\n- back/forward navigation mid-flow\n- repeated or rapid clicks on one control\n- toggling modes back and forth\n- starting a flow, then bailing out\n- refreshing or re-entering with partial state\n\nWrite each pass to a discardable QA note such as `.notes/qa-01.md`. Collate the\nfindings, keep only useful bugs, and mark the one moment that best captures the\nstate failure.\n\nThen capture that moment with agent markers:\n\n```text\nweird state found -> human marks the decisive moment -> export nearby evidence\n```\n\nDo not replace stable business-logic tests with 5 Monkeys. Use it to discover\nUI and state failures that tests and logs did not already isolate.\n\n## Files To Inspect\n\nAgent markers project references:\n\n```text\npackages/client/src/index.ts\npackages/client/src/collector.ts\npackages/client/src/types.ts\npackages/client/src/capture/console.ts\npackages/client/src/capture/fetch.ts\npackages/client/src/capture/errors.ts\npackages/client/src/serialize.ts\napps/demo/src/main.ts\napps/demo/src/viewer.ts\nscripts/smoke-demo.mjs\ndocs/WORKSHOP.md\n```\n\n## When To Reach For This\n\nUse markers when logs are real but the important moment still needs human context.\n\n| Use Markers For | Why |\n| --- | --- |\n| checkout bug | mark the exact UI state where expected and actual diverge |\n| auth/session refresh issue | capture nearby fetch/error/console evidence around the failure |\n| billing admin UI failure | attach human expectation to the visible broken state |\n| flaky browser test | export a debug packet from the test runner |\n| design/debug review | pair screenshot/DOM hooks with a human explanation |\n| long agent debugging session | leave explicit breadcrumbs for the next pass |\n\nSkip markers when:\n\n- one failing unit test already isolates the bug\n- a stack trace points to one obvious line\n- no one can explain why the moment matters\n- the capture would expose sensitive data without redaction\n- the task needs full deterministic replay rather than a bounded debug packet\n\n## How This Used To Work\n\nWhat you used to expect:\n\n```text\nIf enough logs are captured, the agent can infer the important moment.\n```\n\nWhat the workflow gives you now:\n\n```text\nLogs show events. A marker ties a specific moment to human intent, nearby\nevidence, and the next debugging question.\n```\n\nWhat you used to expect:\n\n```text\nA screenshot or console dump is enough context.\n```\n\nWhat the workflow gives you now:\n\n```text\nThe useful packet combines the marker note, nearby console/fetch/error/manual\nevents, optional DOM or screenshot capture, privacy boundaries, and an export.\n```\n\n## The Mental Model\n\n```text\nDebugSession\n-> CapturedEvent[]\n-> DebugMoment[]\n-> export JSON\n-> agent prompt / test artifact / work unit\n```\n\n| Concept | Meaning |\n| --- | --- |\n| `DebugSession` | one bounded debugging run |\n| `CapturedEvent` | console, fetch, error, manual, DOM, screenshot, or app event |\n| `DebugMoment` | the human marker: label, note, timestamp, nearby evidence |\n| `nearbyEventIds` | event ids around the marked moment |\n| export JSON | portable debug packet |\n| `stop()` | cleanup that restores patched browser APIs |\n\n## Basic Browser Setup\n\nCreate markers in a browser app:\n\n```ts\nimport { createAgentMarkers } from \"@agent-markers/client\";\n\nconst markers = createAgentMarkers({\n  appName: \"checkout-app\",\n  exposeGlobal: true,\n  capture: {\n    console: true,\n    fetch: true,\n    errors: true,\n  },\n});\n```\n\nExpose a manual marker action:\n\n```ts\ndocument.querySelector(\"#mark-debug\")?.addEventListener(\"click\", () => {\n  markers.mark({\n    label: \"checkout payment method disappeared\",\n    note: \"Expected saved payment selector to stay visible after refresh.\",\n  });\n});\n```\n\nExport:\n\n```ts\nconst session = markers.export();\nconsole.log(JSON.stringify(session, null, 2));\n```\n\nClean up patched APIs:\n\n```ts\nmarkers.stop();\n```\n\n## Global Test Surface\n\nIn dev/test, expose the marker surface:\n\n```ts\ncreateAgentMarkers({\n  appName: \"checkout-app\",\n  exposeGlobal: true,\n});\n```\n\nThen inspect from the browser console or a test runner:\n\n```js\nwindow.__AGENT_MARKERS__.mark({\n  label: \"checkout failure\",\n  note: \"Expected saved cards to render before submit.\",\n});\n\nconst session = window.__AGENT_MARKERS__.export();\nsession.markers.length;\n```\n\nUse the global for test export, not as the only application API.\n\n## Capture Types\n\n| Capture | What It Adds | Watch For |\n| --- | --- | --- |\n| console | logs, warnings, errors | noisy output |\n| fetch | request URL, method, status, timing | request/response bodies may be sensitive |\n| errors | thrown errors and unhandled rejections | stack traces may include private paths |\n| manual | human-entered labels and notes | must be specific |\n| DOM hook | optional host-provided DOM snapshot | avoid private text |\n| screenshot hook | optional host-provided image capture | unavailable in some environments |\n| storage metadata | keys/counts, not full values by default | never dump secrets by accident |\n\nPrivacy rule:\n\n```text\nCapture metadata by default. Capture values only when deliberately enabled and safe.\n```\n\n## Marker Shape\n\nA useful marker has:\n\n```json\n{\n  \"label\": \"checkout saved card missing\",\n  \"note\": \"Expected saved payment methods to appear after login refresh; actual UI shows empty selector.\",\n  \"nextAction\": \"Inspect auth refresh state, checkout payment query, and recent fetch events.\"\n}\n```\n\nWeak marker:\n\n```json\n{\n  \"label\": \"broken\"\n}\n```\n\nBetter marker:\n\n```json\n{\n  \"label\": \"saved payment selector empty after refresh\",\n  \"note\": \"At this moment the user is logged in, the account menu shows the correct user, but checkout has no saved cards.\",\n  \"nextAction\": \"Compare account payment fetch response with checkout payment state.\"\n}\n```\n\n## Export A Debug Packet\n\nExport from browser:\n\n```js\nconst session = window.__AGENT_MARKERS__.export();\nconsole.log(JSON.stringify(session, null, 2));\n```\n\nSave in a test:\n\n```ts\nconst session = await page.evaluate(() => window.__AGENT_MARKERS__.export());\nawait testInfo.attach(\"agent-markers.json\", {\n  body: JSON.stringify(session, null, 2),\n  contentType: \"application/json\",\n});\n```\n\nOr write to disk in a local script:\n\n```js\nconst session = await page.evaluate(() => window.__AGENT_MARKERS__.export());\nawait fs.promises.writeFile(\n  \"artifacts/agent-markers/checkout-session.json\",\n  JSON.stringify(session, null, 2)\n);\n```\n\n## Verify The Project\n\nCommon checks:\n\n```bash\nnpm test\nnpm run typecheck\nnpm run build\nnpm run smoke:demo\n```\n\nWhat to look for:\n\n- marker can be created\n- marker has a human explanation\n- nearby events are linked with `nearbyEventIds`\n- console/fetch/error/manual events appear when enabled\n- storage values are not dumped by default\n- export JSON is valid\n- `stop()` restores patched browser APIs\n- test runner can access `window.__AGENT_MARKERS__`\n\n## Turn A Marker Export Into An Agent Prompt\n\nPrompt shape:\n\n```markdown\n# Debug Prompt From Agent Marker\n\n## Source Artifact\n\n- marker export:\n- schema version:\n- marker id:\n- marker label:\n\n## Human Explanation\n\n- expected:\n- actual:\n- why this moment matters:\n- next action:\n\n## Nearby Evidence\n\n- console:\n- fetch:\n- error:\n- manual:\n- screenshot:\n- DOM:\n\n## Privacy Boundary\n\n- storage values exported? no\n- request bodies exported? no\n- response bodies exported? no\n- private text removed:\n\n## Task\n\nFind the smallest likely bug path and propose the first verification command.\nDo not invent app state that is not in the marker packet.\n```\n\n## Bounded Replay Capsule\n\nDo not build a full recorder. Design the smallest packet that makes the marked moment inspectable.\n\n```markdown\n# Bounded Replay Capsule\n\n- schemaVersion:\n- markerId:\n- sessionId:\n- markerCutoffSeq:\n- nearbyEventIds:\n- console:\n- fetch:\n- errors:\n- manual:\n- screenshot:\n- dom:\n- redaction:\n\n## Boundaries\n\n- included:\n- excluded:\n- maximum event count:\n- privacy rules:\n\n## How To Use It\n\n- agent prompt:\n- human review:\n- verification command:\n```\n\n## App-Specific Marker Flow\n\nAn app may wire a shortcut such as `Ctrl+M` to create durable marker evidence.\n\nConceptual flow:\n\n```text\nCtrl+M\n-> create marker id\n-> capture screenshot if available\n-> open note/explanation UI\n-> save human explanation\n-> write durable app logs\n```\n\nExpected log strings:\n\n```text\ndev_marker\ndev_marker_explanation\n```\n\nInspection shape:\n\n```bash\nrg -n \"dev_marker|dev_marker_explanation\" <app-log-path>/latest-session.jsonl\n```\n\nKeep this generic:\n\n- one marker id shared across marker and explanation\n- screenshot optional\n- explanation required\n- bounded nearby evidence\n- clear next action\n\n## Ask The Agent This\n\nAdd markers to a browser bug investigation:\n\n```text\nAdd agent markers to the checkout browser flow.\n\nCapture console, fetch, errors, and manual markers. Expose\n`window.__AGENT_MARKERS__` in dev/test. Add a marker for the moment saved\npayment methods disappear after auth refresh. Export JSON and show how to\nconfirm nearbyEventIds, privacy defaults, and marker explanation.\n```\n\nTurn export into a debug prompt:\n\n```text\nUse this agent-marker export as the bounded debug packet.\n\nFocus on the marked checkout failure. Summarize the human explanation, nearby\nconsole/fetch/error/manual evidence, privacy boundaries, and the first\nverification command. Do not infer app state that is not in the packet.\n```\n\nWrite a test export:\n\n```text\nCreate a Playwright-style test path that triggers the checkout bug, calls\n`window.__AGENT_MARKERS__.mark(...)`, exports the session JSON, and attaches it\nas a test artifact. Include the checks that prove marker count, nearbyEventIds,\nand event types are present.\n```\n\n## What To Confirm / How To Know It Worked\n\n| Goal | Confirmation |\n| --- | --- |\n| marker client installed | app imports `createAgentMarkers` |\n| marker created | export has `markers.length > 0` |\n| explanation present | marker has a specific `note` |\n| nearby evidence linked | marker has non-empty `nearbyEventIds` |\n| console captured | exported events include console type |\n| fetch captured | exported events include fetch type |\n| errors captured | exported events include error type |\n| privacy default safe | storage values are absent unless deliberately enabled |\n| global test surface works | `window.__AGENT_MARKERS__.export()` returns session |\n| export saved | JSON artifact exists and is non-empty |\n| cleanup handled | `stop()` called when patching should end |\n| project verifies | `npm test`, `npm run typecheck`, `npm run build`, `npm run smoke:demo` |\n\n## If It Goes Wrong\n\n### Marker Has No Note\n\nAdd expected/actual context.\n\n```text\nWhat should have happened:\nWhat happened:\nWhy this moment matters:\nNext action:\n```\n\n### Export Has Too Many Raw Logs\n\nFocus on one marker id and its nearby events. Increase event limits deliberately, not by default.\n\n### `nearbyEventIds` Is Empty\n\nMark closer to the failure or adjust the nearby event window.\n\n### Sensitive Storage Values Were Captured\n\nRedact and rebuild the export. Capture storage metadata, not values, unless safe and intentional.\n\n### Console/Fetch Remains Patched\n\nCall:\n\n```ts\nmarkers.stop();\n```\n\n### Test Runner Cannot Export\n\nConfirm `exposeGlobal: true` in dev/test and wait for app readiness before reading `window.__AGENT_MARKERS__`.\n\n### Screenshot Or DOM Hook Is Missing\n\nMark it unavailable. Do not pretend a screenshot or DOM snapshot exists.\n\n## References And Resources\n\n- Agent marker client entry: `packages/client/src/index.ts`\n- Collector source: `packages/client/src/collector.ts`\n- Types: `packages/client/src/types.ts`\n- Demo app: `apps/demo/src/main.ts`\n- Viewer/export UI: `apps/demo/src/viewer.ts`\n- Smoke script: `scripts/smoke-demo.mjs`\n- Playwright docs: https://playwright.dev/docs/test-assertions\n- Cypress docs: https://docs.cypress.io/\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
}
