---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-marker-workflows-team-guide"
title: "Agent Markers debugging workflows: team walkthrough"
---

# Agent Markers debugging workflows: team walkthrough

## Team Learning Goal

Teach markers as human-intent anchors in debugging workflows.

By the end of this section, the room should understand:

- why raw logs are not enough
- how `mark -> capture -> explain -> review/export` works
- what a `DebugSession`, `DebugMoment`, `CapturedEvent`, and `nearbyEventIds` are
- how to export marker JSON from browser/dev/test flows
- how privacy defaults prevent overcapture
- how marker exports become bounded debug packets
- how Section 9 can use the packet as a work unit

## Walkthrough Depth

### Essential Walkthrough

1. State: raw logs tell what emitted; markers tell why a moment mattered.
2. Draw `mark -> capture -> explain -> review/export`.
3. Show `createAgentMarkers`.
4. Show `window.__AGENT_MARKERS__.mark` and `export`.
5. Show the final agent prompt shape.

### Expanded Walkthrough

Add:

- capture types table
- privacy defaults
- `nearbyEventIds`
- Playwright export
- `stop()` cleanup

### Deep-Dive Walkthrough

Add:

- app-specific `Ctrl+M` flow
- bounded replay capsule
- smoke/test commands
- exercises

## Talking Points

Opening:

> Raw logs tell you what emitted. Agent markers tell you why a moment mattered.

On markers:

> A marker is a human-intent anchor, not another log line.

On privacy:

> Metadata first. Values only when deliberately enabled and safe.

On replay:

> This is a bounded debug packet, not a deterministic recorder.

Bridge from Section 7:

> Section 7 preserved evidence from video. Section 8 lets you create evidence while debugging.

Bridge to Section 9:

> A good marker export is small enough to become a work unit.

## Live Demo Script

### 1. Show Setup

```ts
import { createAgentMarkers } from "@agent-markers/client";

const markers = createAgentMarkers({
  appName: "checkout-app",
  exposeGlobal: true,
  capture: {
    console: true,
    fetch: true,
    errors: true,
  },
});
```

### 2. Create A Marker

```js
window.__AGENT_MARKERS__.mark({
  label: "saved payment selector empty after refresh",
  note: "Expected saved cards to stay visible after auth refresh; actual selector is empty.",
});
```

### 3. Export

```js
const session = window.__AGENT_MARKERS__.export();
({
  markerCount: session.markers.length,
  eventCount: session.events.length,
  hasNearbyIds: session.markers.some((marker) => marker.nearbyEventIds.length > 0),
});
```

### 4. Verify Project

```bash
npm test
npm run typecheck
npm run build
npm run smoke:demo
```

## Minimal Useful Path

If 5 minutes behind, cut:

- Cypress example
- app-specific `Ctrl+M`
- bounded replay capsule details
- screenshot/DOM hook implementation

Preserve:

- `mark -> capture -> explain -> review/export`
- `createAgentMarkers`
- `window.__AGENT_MARKERS__`
- `nearbyEventIds`
- privacy defaults
- export JSON
- Section 9 bridge

## Boundaries

### From Section 7

Section 7:

```text
source media -> evidence lanes -> verified prompt material
```

Section 8:

```text
marked moment -> nearby runtime evidence -> bounded debug packet
```

### To Section 9

Section 9 needs work units that are small, bounded, and verifiable.

Agent markers provide:

- one marker id
- human explanation
- nearby evidence
- privacy boundary
- verification command
- next action

## Failure Paths To Preserve

No note:

> A marker without a human explanation is just another timestamp.

Too many logs:

> Focus on one marker id and nearby events.

Sensitive storage:

> Redact and rebuild. Metadata first.

No nearby events:

> Mark closer to the failure or adjust the nearby window deliberately.

Patched APIs not restored:

> Call `stop()` and test cleanup.

No test export:

> Expose the global in dev/test and wait for app readiness.

## Team Checklist

Confirm the materials include:

```text
mark -> capture -> explain -> review/export
createAgentMarkers
DebugSession
DebugMoment
CapturedEvent
nearbyEventIds
console capture
fetch capture
error capture
manual evidence
DOM hook
screenshot hook
privacy defaults
storage metadata
window.__AGENT_MARKERS__
export JSON
download
stop()
npm test
npm run typecheck
npm run build
npm run smoke:demo
Playwright export
Cypress export
dev_marker
dev_marker_explanation
bounded replay capsule
Section 9 bridge
```

## Further References

- team-facing file: `cheatsheets/08-debugging-with-agent-markers.md`
- Exercises: `exercises/08-debugging-with-agent-markers.md`
- Agent marker client: `packages/client/src/index.ts`
- Collector: `packages/client/src/collector.ts`
- Demo: `apps/demo/src/main.ts`
- Smoke script: `scripts/smoke-demo.mjs`

## Related resources

- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
- [Resource directory and portable download](/topics/codex-resources/)

## Original references

- [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
