docs: add Synthetic provider reference

[kiranmagic7]

Summary

• add docs/synthetic.md with Synthetic setup, quota endpoint, display mapping, CLI usage, and source-file pointers
• link the Synthetic detail page from README.md and docs/providers.md

Proof

• node Scripts/check-documentation-links.mjs
• node Scripts/check-site-locales.mjs
• node Scripts/generate-llms.mjs --check
• bash Scripts/lint.sh lint-linux
• git diff --check

Compatibility

Docs-only; no runtime behavior changes.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 6, 2026, 8:45 PM ET / 00:45 UTC.

Summary
The branch adds a Synthetic provider detail page and links it from the README provider list and providers overview.

Reproducibility: not applicable. this is a docs-only PR. The review path is source comparison against current Synthetic provider code/tests rather than reproducing a runtime bug.

Review metrics: 1 noteworthy metric.

• Docs surface: 3 files changed, 70 additions, 0 deletions. The diff is limited to README.md, docs/providers.md, and a new provider detail page, with no runtime or release-script surface.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• none.

Next step before merge

• [P1] No automated repair is needed; this clean docs-only PR can proceed through normal maintainer and CI review.

Security
Cleared: The diff only changes documentation files and does not alter dependencies, workflows, scripts, secrets handling, or runtime code.

Review details

Best possible solution:

Merge the Synthetic reference after normal maintainer and CI review, keeping the docs aligned with the existing provider implementation.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this is a docs-only PR. The review path is source comparison against current Synthetic provider code/tests rather than reproducing a runtime bug.

Is this the best way to solve the issue?

Yes; adding a provider detail page and overview links is the narrowest maintainable way to fill the missing Synthetic reference.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 46edb383c0ac.

Label changes

Label changes:

• add P3: This is low-risk provider documentation polish with no runtime behavior change.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Documentation-only changes to README.md and docs files do not need real runtime proof; the PR body lists documentation/link/lint checks instead.

Label justifications:

• P3: This is low-risk provider documentation polish with no runtime behavior change.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Documentation-only changes to README.md and docs files do not need real runtime proof; the PR body lists documentation/link/lint checks instead.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully before review; its guidance kept this to read-only inspection and avoided live provider probes for documentation review. (AGENTS.md:1, 46edb383c0ac)
• Current main lacks the detail page: Current main does not contain docs/synthetic.md, so the PR is not redundant with an existing Synthetic detail page. (docs/synthetic.md, 46edb383c0ac)
• PR documentation content: The added page documents authentication, the quota endpoint, known quota keys, fallback parsing, display mapping, CLI usage, and source-file pointers. (docs/synthetic.md:30, d71b8fa6cfe8)
• Endpoint and headers match source: Current main fetches GET https://api.synthetic.new/v2/quotas with Bearer authorization and Accept: application/json, matching the new docs. (Sources/CodexBarCore/Providers/Synthetic/SyntheticUsageStats.swift:95, 46edb383c0ac)
• Quota shape matches parser: Current main maps rollingFiveHourLimit, weeklyTokenLimit, and search.hourly before falling back through generic quota containers, matching the added reference. (Sources/CodexBarCore/Providers/Synthetic/SyntheticUsageStats.swift:192, 46edb383c0ac)
• CLI alias and labels match descriptor: The descriptor names the Synthetic provider, uses five-hour/weekly/search labels, and exposes the synthetic.new CLI alias documented by the PR. (Sources/CodexBarCore/Providers/Synthetic/SyntheticProviderDescriptor.swift:11, 46edb383c0ac)

Likely related people:

• monotykamary: GitHub PR history shows the Synthetic provider was introduced through the merged provider-support PR, covering the source and tests this documentation describes. (role: introduced behavior; confidence: high; commits: 8799099bed11, 9198251e96c3; files: Sources/CodexBarCore/Providers/Synthetic/SyntheticUsageStats.swift, Sources/CodexBarCore/Providers/Synthetic/SyntheticProviderDescriptor.swift, Tests/CodexBarTests/SyntheticProviderTests.swift)
• Aanish Bhirud: Recent Synthetic commits handled the rolling, weekly, search quota shape and tickPercent regen parsing that the new detail page documents. (role: recent parser contributor; confidence: high; commits: ea02e5fad770, 45f040fb5902; files: Sources/CodexBarCore/Providers/Synthetic/SyntheticUsageStats.swift, Tests/CodexBarTests/SyntheticProviderTests.swift, Tests/CodexBarTests/SyntheticMenuCardTests.swift)
• steipete: Recent provider-infra and documentation history touches docs/providers and current Synthetic provider source, making this a likely review route for provider docs alignment. (role: recent area contributor; confidence: medium; commits: fa1a03840ce1, a83a83fa4131; files: docs/providers.md, Sources/CodexBarCore/Providers/Synthetic/SyntheticUsageStats.swift, Sources/CodexBarCore/Providers/Synthetic/SyntheticProviderDescriptor.swift)
• kiranmagic7: Beyond this PR, current-main history includes prior provider-detail docs and provider Details-link work from this contributor. (role: recent provider-doc contributor; confidence: medium; commits: 18fc600f2481, ba97bc8134dd; files: docs/providers.md, docs/t3chat.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.