Add annotated-trace discovery and dataset export workflows

[johnnygreco]

Objective

Make annotated traces easy to find and gather into dataset-friendly JSON without scraping the UI, so annotations can support self-improvement, skill development, evaluation, and fine-tuning workflows.

Context

• Tracker: GitHub goal delivery: trace and session annotations #301
• Depends on: Add annotation storage, domain model, and JSON API foundation #302, Build human transcript annotation UI #303, Add MCP annotation tools for agents #304
• Self-contained context: Annotation storage/API comes from Add annotation storage, domain model, and JSON API foundation #302, human UI from Build human transcript annotation UI #303, and MCP annotation access from Add MCP annotation tools for agents #304. Beacon already has session/event search and listing APIs; this issue makes annotations first-class in discovery/export workflows instead of hidden side data.

Scope

• In scope: annotation-aware session/event discovery, filters or API query parameters for annotated sessions/events, and an export path that returns annotated traces with session/event context and annotation metadata in stable JSON/JSONL.
• Non-goals: final screenshot QA report and broad visual artifact collection are separate issue Complete annotation QA, docs, and final polish #306-equivalent final QA work once created.
• Backward compatibility: do not add legacy shims or old export formats unless explicitly required.
• Dependencies: Add annotation storage, domain model, and JSON API foundation #302, Build human transcript annotation UI #303, and Add MCP annotation tools for agents #304 merged into feature/trace-annotations.
• Sequencing: fourth implementation issue.

Implementation Notes

The export workflow should include enough context to be useful outside Beacon:

• session metadata;
• ordered events/messages used by the annotation target;
• annotation records with structured fields and note text;
• source/runtime/provider/model/project fields where available;
• stable schema version marker.

Possible surfaces include JSON API endpoints, CLI subcommands, and/or MCP read tools. Choose the smallest cohesive surface that satisfies dataset collection without duplicating logic. If a CLI command is added, keep it local and deterministic.

Dashboard/session lists should expose annotation counts or filters where practical so users can discover annotated sessions. The transcript UI should remain the primary authoring surface from #303.

Acceptance Criteria

• Beacon can list annotated sessions/events through a documented API or command.
• Users/agents can filter or query for sessions/events with annotations.
• Beacon can export annotated traces in stable dataset-friendly JSON or JSONL.
• Export includes session context, ordered event context, annotation metadata, and a schema marker.
• Export behavior is tested for session-level annotations, event-level annotations, mixed annotations, deleted annotations, and empty results.
• README or docs explain how to collect annotated trace datasets.

Required Validation

• make generate-check
• make fmt-check
• make test
• npm run test:frontend if frontend discovery controls change
• targeted API/CLI/MCP export tests depending on chosen surface

PR Expectations

Open a focused PR against feature/trace-annotations. Include example export output, documented schema notes, and exact validation results. If UI discovery controls are added, include screenshots.

[johnnygreco]

Starting #305 on branch issue-305-annotation-export from feature/trace-annotations at 65c3ff9d335ac504896cb9a84eac5d1453dfbc13.

Planned surface: typed JSON API endpoints for annotation discovery/export plus README documentation. This satisfies dataset collection without adding a separate CLI layer or duplicating annotation contracts.

[johnnygreco]

PR #310 is open for #305: https://github.com/johnnygreco/beacon/pull/310\n\nHead SHA: 9fbfd21; base SHA: 65c3ff9d335ac504896cb9a84eac5d1453dfbc13. Local validation passed: make generate-check, make fmt-check, make test, make build, make lint, npm run test:frontend, targeted export/API tests, and git diff --check. Independent review and GitHub CI are pending.

[johnnygreco]

Status update for #305: PR #310 is updated at head 0823247 and all GitHub CI checks are green. Local validation passed: make generate-check, make fmt-check, make test, make build, make lint, npm run test:frontend, targeted annotation/export tests, and git diff --check. Local review found and fixed one concrete export issue: traces with more than maxAnnotationsAPILimit annotations now page through all matching annotation records instead of silently exporting only the first store page; regression coverage was added. The installed review server is running from this branch at http://localhost:4600 using /tmp/beacon-trace-annotations-dev.toml, and /api/annotations/traces plus /api/annotations/export smoke tests passed. Pending: independent panel review/Review Record and merge, blocked on explicit approval to use subagent reviewers.

[johnnygreco]

#305 is complete. PR #310 merged into feature/trace-annotations at a6ae886 after Review Record #310 (comment) and green CI on reviewed head bee86e6. Accepted review fixes included scope-visible annotated trace ordering/pagination, removal of the fixed 5,000 candidate scan cap, annotated-trace offset capping, and README pagination/truncation guidance.

[johnnygreco]

Completed by PR #310 merged into feature/trace-annotations at a6ae886.