docs(learning): add A2B hands-on lab module — Testing Your First Agent

[bokelley]

Closes #2571

Adds a free hands-on lab module (A2B: Testing Your First Agent) as a supplement to A2. Addresses the gap Addie's weekly insights surfaced: ~75 learners/week complete A2 conceptually but lack "operational muscle memory" for actual agent calls. The module provides copy-paste curl examples for every step of the buy flow, explicit handling of all three create_media_buy response shapes, dry-run creative validation, tasks/get async polling, and a five-entry common-errors table.

Non-breaking justification: Additive only — new MDX doc page, new DB migration row (with ON CONFLICT DO UPDATE for idempotency), two new entries in TypeScript object literals, one nav item, one changeset file. No schema changes, no protocol changes, no existing content modified except the sort_order bump for A3 (3→4) and the free-modules string in certification-tools.ts.

Files changed:

• docs/learning/foundations/a2b-testing-your-first-agent.mdx — new module page with curl reference, error table, assessment rubric
• server/src/db/migrations/448_a2b_testing_lab.sql — inserts A2B (sort_order=3, is_free=true, prerequisites={A2}); bumps A3 sort_order 3→4
• server/src/addie/mcp/certification-tools.ts — adds A2B to MODULE_ILLUSTRATION_TOPICS and MODULE_RESOURCES; updates free-modules list string
• docs.json — adds A2B to the "Basics (free)" nav group between A2 and A3
• .changeset/a2b-testing-lab.md — --empty changeset (non-protocol change)

Companion issue: #2570 (Media Buy Lifecycle doc) is still open. The reading-list card "Media buy lifecycle" currently links to /docs/media-buy/media-buys (the existing page covering all status states). Update the link once #2570 ships.

Nit (noted for reviewer): The curl example uses idempotency_key: "mb-lab-20260428-001" with a hardcoded date as a concrete placeholder. A reader following the guide should use a fresh value — this is clear from the surrounding prose but could be made more explicit with a <date> placeholder form if desired.

Pre-PR review:

• education-expert: approved — two blockers found and fixed (tasks/get method form; Media Buy Lifecycle link label); assessment rubric dimensions verified orthogonal; content completeness confirmed against all acceptance criteria
• code-reviewer: approved — no blockers after fixes; nits noted above

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

• Push fixup commits directly: gh pr checkout <num> →
  fix → push.
• Or re-trigger: comment /triage execute on the source
  issue.

See #3121
for context.

Session: https://claude.ai/code/session_01PFHFqGU1pQdxswb7xswSwY

---

Generated by Claude Code

[bokelley]

Server integration tests failing. Likely: test setup needs DB init or mocks. Check failure detail and either mock the missing dep or update test setup.

[bokelley]

Fixed. Root cause: digest-email-recipients.test.ts had expect(r.cert_total_modules).toBe(3) hardcoded for track A — written when track A had three modules (A1, A2, A3). Migration 448 adds A2B, so track A now has four, and the assertion failed.

Fix in 51ad809: replaced the hardcoded 3 with a live SELECT COUNT(*) FROM certification_modules WHERE track_id = 'A' query, consistent with the pattern already used for the track-B and tie-break tests in the same file. No logic changes — test-only.

---

Generated by Claude Code

[bokelley]

Noted — 51ad809 looks good. Replacing the hardcoded 3 with a live COUNT(*) against certification_modules is the right approach and consistent with the existing track-B and tie-break patterns. No further action needed here.

---

Generated by Claude Code

[bokelley]

Acknowledged — no further action from triage on this thread.

---

Generated by Claude Code

[bokelley]

Routine: this PR has 4 CI failures driven by two root causes — fix both in one rebase pass:

1. Migration renumber (448 → 451)

Main now has:

448_backfill_primary_organization_id.sql
449_auto_provision_brand_hierarchy_children.sql
450_auto_provision_hierarchy_enabled_at.sql

Rename 448_a2b_testing_lab.sql → 451_a2b_testing_lab.sql to clear the dup-prefix check.

2. Rebase + TypeScript / integration test conflicts

server/src/addie/mcp/certification-tools.ts and server/tests/integration/digest-email-recipients.test.ts likely conflict with recent cert and digest PRs that landed (#3405-related work, #3395 cert rubric, etc.). Rebase against origin/main and resolve — keep this PR's A2B-specific additions, take main's other changes.

Once both are resolved:

• No duplicate migration numbers should pass (no more 448 dup)
• Built migrations against Postgres should pass (renamed migration applies cleanly)
• TypeScript Build should pass (post-rebase imports/types align)
• Server integration tests should pass (test conflicts resolved)

Push the rebased branch and CI should clear all four.

[bokelley]

Held back from docs automerge bundle. CI failures: TypeScript Build, integration tests, migration number conflicts (branch is stale vs main migrations).

Failure logs are 6+ days old; a rebase onto current main (which absorbed the IA Phase 2/3 doc moves in #4022 and #4031) would either fix link/build drift or surface real issues. Once CI is green, this is automerge-eligible.

[bokelley]

Rebased onto current main and pushed.

What changed:

• Rebased 3 PR commits cleanly on top of 2e6f896 (main as of today — includes IA Phase 2/3 doc moves from docs(building): IA Phase 2 — relocate pages by layer (#41 moves, 43 redirects) #4022 and docs(building): IA Phase 3 — split schemas-and-sdks, add build-a-caller #4031). No content conflicts.
• Renumbered migration 448_a2b_testing_lab.sql → 466_a2b_testing_lab.sql. Migration 448 was claimed by 448_backfill_primary_organization_id.sql while this branch was open; 466 is next after 465.

Build + test result:

• npm run build && npm run typecheck — clean.
• npm test — 1 pre-existing failure in lint-storyboard-context-output-paths (sales-guaranteed/create_media_buy — task_completion.media_buy_id (path_not_in_schema)). That storyboard is identical to main; the failure exists on main independently of this PR.

Should be CI-green (or fail only on the pre-existing lint) after this push.

---

Generated by Claude Code

[bokelley]

Got it — rebase clean, migration renumber to 466 noted. The lint-storyboard-context-output-paths failure on sales-guaranteed/create_media_buy is pre-existing on main and unrelated to this PR's diff.

PR looks ready for CI green + human review.

---

Generated by Claude Code

---

Generated by Claude Code

[bokelley]

Confirmed — lint-storyboard-context-output-paths failure on sales-guaranteed/create_media_buy is pre-existing on main and outside this PR's diff. No action needed here. PR is ready for CI green + human review to proceed.

---

Generated by Claude Code