{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-marker-workflows-team-guide",
  "slug": "marker-workflows-team-guide",
  "title": "Agent Markers debugging workflows: team walkthrough",
  "summary": "Marker-centered debugging using createAgentMarkers, browser-global marking and export, nearby-event association, privacy boundaries, cleanup, and project verification. Preserves the bounded debug-packet model, downstream work-unit bridge, failure recovery,…",
  "category": "Team practice",
  "tags": [
    "agent-markers",
    "debugging",
    "privacy",
    "team-guide"
  ],
  "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!/instructor-notes/08-debugging-with-agent-markers.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Presenter Goal",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Timing Options",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Timing Options/10-Minute Version",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Timing Options/20-Minute Version",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Timing Options/35-Minute Version",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Things To Say",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Live Demo Script",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Live Demo Script/1. Show Setup",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Live Demo Script/2. Create A Marker",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Live Demo Script/3. Export",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Live Demo Script/4. Verify Project",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Cut Path",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Boundaries",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Boundaries/From Section 7",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Boundaries/To Section 9",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Failure Paths To Preserve",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Presenter Checklist",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Presenter References",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "team-practice",
  "wordCount": 662,
  "url": "/topics/codex-marker-workflows-team-guide/",
  "markdownUrl": "/markdown/codex-marker-workflows-team-guide.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-marker-workflows-team-guide.json",
  "headings": [
    {
      "id": "team-learning-goal",
      "text": "Team Learning Goal",
      "level": 2
    },
    {
      "id": "walkthrough-depth",
      "text": "Walkthrough Depth",
      "level": 2
    },
    {
      "id": "essential-walkthrough",
      "text": "Essential Walkthrough",
      "level": 3
    },
    {
      "id": "expanded-walkthrough",
      "text": "Expanded Walkthrough",
      "level": 3
    },
    {
      "id": "deep-dive-walkthrough",
      "text": "Deep-Dive Walkthrough",
      "level": 3
    },
    {
      "id": "talking-points",
      "text": "Talking Points",
      "level": 2
    },
    {
      "id": "live-demo-script",
      "text": "Live Demo Script",
      "level": 2
    },
    {
      "id": "1-show-setup",
      "text": "1. Show Setup",
      "level": 3
    },
    {
      "id": "2-create-a-marker",
      "text": "2. Create A Marker",
      "level": 3
    },
    {
      "id": "3-export",
      "text": "3. Export",
      "level": 3
    },
    {
      "id": "4-verify-project",
      "text": "4. Verify Project",
      "level": 3
    },
    {
      "id": "minimal-useful-path",
      "text": "Minimal Useful Path",
      "level": 2
    },
    {
      "id": "boundaries",
      "text": "Boundaries",
      "level": 2
    },
    {
      "id": "from-section-7",
      "text": "From Section 7",
      "level": 3
    },
    {
      "id": "to-section-9",
      "text": "To Section 9",
      "level": 3
    },
    {
      "id": "failure-paths-to-preserve",
      "text": "Failure Paths To Preserve",
      "level": 2
    },
    {
      "id": "team-checklist",
      "text": "Team Checklist",
      "level": 2
    },
    {
      "id": "further-references",
      "text": "Further References",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Agent Markers debugging workflows: team walkthrough\n\n## Team Learning Goal\n\nTeach markers as human-intent anchors in debugging workflows.\n\nBy the end of this section, the room should understand:\n\n- why raw logs are not enough\n- how `mark -> capture -> explain -> review/export` works\n- what a `DebugSession`, `DebugMoment`, `CapturedEvent`, and `nearbyEventIds` are\n- how to export marker JSON from browser/dev/test flows\n- how privacy defaults prevent overcapture\n- how marker exports become bounded debug packets\n- how Section 9 can use the packet as a work unit\n\n## Walkthrough Depth\n\n### Essential Walkthrough\n\n1. State: raw logs tell what emitted; markers tell why a moment mattered.\n2. Draw `mark -> capture -> explain -> review/export`.\n3. Show `createAgentMarkers`.\n4. Show `window.__AGENT_MARKERS__.mark` and `export`.\n5. Show the final agent prompt shape.\n\n### Expanded Walkthrough\n\nAdd:\n\n- capture types table\n- privacy defaults\n- `nearbyEventIds`\n- Playwright export\n- `stop()` cleanup\n\n### Deep-Dive Walkthrough\n\nAdd:\n\n- app-specific `Ctrl+M` flow\n- bounded replay capsule\n- smoke/test commands\n- exercises\n\n## Talking Points\n\nOpening:\n\n> Raw logs tell you what emitted. Agent markers tell you why a moment mattered.\n\nOn markers:\n\n> A marker is a human-intent anchor, not another log line.\n\nOn privacy:\n\n> Metadata first. Values only when deliberately enabled and safe.\n\nOn replay:\n\n> This is a bounded debug packet, not a deterministic recorder.\n\nBridge from Section 7:\n\n> Section 7 preserved evidence from video. Section 8 lets you create evidence while debugging.\n\nBridge to Section 9:\n\n> A good marker export is small enough to become a work unit.\n\n## Live Demo Script\n\n### 1. Show Setup\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\n### 2. Create A Marker\n\n```js\nwindow.__AGENT_MARKERS__.mark({\n  label: \"saved payment selector empty after refresh\",\n  note: \"Expected saved cards to stay visible after auth refresh; actual selector is empty.\",\n});\n```\n\n### 3. Export\n\n```js\nconst session = window.__AGENT_MARKERS__.export();\n({\n  markerCount: session.markers.length,\n  eventCount: session.events.length,\n  hasNearbyIds: session.markers.some((marker) => marker.nearbyEventIds.length > 0),\n});\n```\n\n### 4. Verify Project\n\n```bash\nnpm test\nnpm run typecheck\nnpm run build\nnpm run smoke:demo\n```\n\n## Minimal Useful Path\n\nIf 5 minutes behind, cut:\n\n- Cypress example\n- app-specific `Ctrl+M`\n- bounded replay capsule details\n- screenshot/DOM hook implementation\n\nPreserve:\n\n- `mark -> capture -> explain -> review/export`\n- `createAgentMarkers`\n- `window.__AGENT_MARKERS__`\n- `nearbyEventIds`\n- privacy defaults\n- export JSON\n- Section 9 bridge\n\n## Boundaries\n\n### From Section 7\n\nSection 7:\n\n```text\nsource media -> evidence lanes -> verified prompt material\n```\n\nSection 8:\n\n```text\nmarked moment -> nearby runtime evidence -> bounded debug packet\n```\n\n### To Section 9\n\nSection 9 needs work units that are small, bounded, and verifiable.\n\nAgent markers provide:\n\n- one marker id\n- human explanation\n- nearby evidence\n- privacy boundary\n- verification command\n- next action\n\n## Failure Paths To Preserve\n\nNo note:\n\n> A marker without a human explanation is just another timestamp.\n\nToo many logs:\n\n> Focus on one marker id and nearby events.\n\nSensitive storage:\n\n> Redact and rebuild. Metadata first.\n\nNo nearby events:\n\n> Mark closer to the failure or adjust the nearby window deliberately.\n\nPatched APIs not restored:\n\n> Call `stop()` and test cleanup.\n\nNo test export:\n\n> Expose the global in dev/test and wait for app readiness.\n\n## Team Checklist\n\nConfirm the materials include:\n\n```text\nmark -> capture -> explain -> review/export\ncreateAgentMarkers\nDebugSession\nDebugMoment\nCapturedEvent\nnearbyEventIds\nconsole capture\nfetch capture\nerror capture\nmanual evidence\nDOM hook\nscreenshot hook\nprivacy defaults\nstorage metadata\nwindow.__AGENT_MARKERS__\nexport JSON\ndownload\nstop()\nnpm test\nnpm run typecheck\nnpm run build\nnpm run smoke:demo\nPlaywright export\nCypress export\ndev_marker\ndev_marker_explanation\nbounded replay capsule\nSection 9 bridge\n```\n\n## Further References\n\n- team-facing file: `cheatsheets/08-debugging-with-agent-markers.md`\n- Exercises: `exercises/08-debugging-with-agent-markers.md`\n- Agent marker client: `packages/client/src/index.ts`\n- Collector: `packages/client/src/collector.ts`\n- Demo: `apps/demo/src/main.ts`\n- Smoke script: `scripts/smoke-demo.mjs`\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/)"
}
