fix(dx): verify quickstarts and correct evaluation guidance

[drewstone]

The documented first run could fail before generated declarations existed, several guides overstated statistical and execution guarantees, and the existing-agent example could make paid calls while displaying zero cost. The README now has a verified package-consumer quickstart, guides describe the actual controls and limitations, and the existing-agent example focuses on an offline adapter with separate metered-call guidance.

The optimizer examples share one parser for endpoint token rates. The single-optimizer worker now passes those rates to its transport, charge reservation, and receipts. The package check compares the quickstart output with the README while retaining assertions on complete score distributions.

This also fixes a reporting defect found during the audit: failure-cluster percentages used the five displayed exemplars as their numerator. They now count every affected failed run once per cluster, with regression coverage for seven failures, duplicate findings, and overlapping clusters.

Validation:

• 6,124 TypeScript tests passed; three skipped. Build, lint, all three typechecks, and package verification passed.
• Isolated packed-package README execution and existing-agent fixture matched the documented output. The paid adapter typechecked and recorded complete usage through a mocked HTTP transport.
• Python client reached the built CLI through a real subprocess; version, rubric discovery, and missing-model errors behaved as documented. All eight Python snippets parsed. Locked GEPA release suite: 44 passed, one expected skip.
• 320 local links and 116 public named imports resolved. Six additional standalone guide snippets typechecked. Independent review found the usage-default error, which is corrected.

No paid provider calls were made. The 29 external links were inventoried but not refreshed. Fixture results do not establish optimizer effectiveness or population-level release evidence.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.