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 9, 2026, 5:20 AM ET / 09:20 UTC.

Summary
The branch adds a Synthetic provider detail page and updates README.md, docs/providers.md, and docs/index.html to link to it.

Reproducibility: not applicable. this is a docs-only PR. The review path is source and diff comparison against the current Synthetic provider implementation rather than reproducing a runtime bug.

Review metrics: 1 noteworthy metric.

• Docs surface: 4 files changed; 78 additions, 3 deletions. The diff is limited to provider documentation and website/README links, 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 docs-only branch has no concrete code defect for ClawSweeper to fix.

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 after normal maintainer and CI review, keeping the provider reference aligned with the current Synthetic 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 and diff comparison against the current Synthetic provider implementation rather than reproducing a runtime bug.

Is this the best way to solve the issue?

Yes; adding a dedicated provider reference and updating the existing overview links is the narrowest maintainable way to document the existing Synthetic support.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 5f1ce581d3c4.

Label changes

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 do not require 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 supported read-only source/docs inspection and avoiding live provider probes for this docs-only change. (AGENTS.md:1, 5f1ce581d3c4)
• PR diff scope: The PR changes only documentation: README.md, docs/index.html, docs/providers.md, and a new docs/synthetic.md, with 78 additions and 3 deletions. (0c985bafb498)
• Not redundant on main: Current main has no docs/synthetic.md entry, so the central documentation addition is not already implemented on main. (docs/synthetic.md, 5f1ce581d3c4)
• Added Synthetic reference: The PR documents the Synthetic quota API request, known quota keys, fallback quota containers, display behavior, CLI aliases, and key source files. (docs/synthetic.md:31, 0c985bafb498)
• README link added: The PR adds Synthetic to the README provider list with a link to docs/synthetic.md. (README.md:104, 0c985bafb498)
• Current implementation matches endpoint docs: Current main fetches GET https://api.synthetic.new/v2/quotas with Bearer authorization and Accept: application/json, matching the added reference. (Sources/CodexBarCore/Providers/Synthetic/SyntheticUsageStats.swift:95, 5f1ce581d3c4)

Likely related people:

• monotykamary: GitHub commit metadata maps the original Synthetic provider commit to monotykamary, covering the provider source this documentation describes. (role: introduced behavior; confidence: high; commits: 8799099bed11; files: Sources/CodexBarCore/Providers/Synthetic/SyntheticProviderDescriptor.swift, Sources/CodexBarCore/Providers/Synthetic/SyntheticUsageStats.swift, Tests/CodexBarTests/SyntheticProviderTests.swift)
• baanish: Recent Synthetic commits from baanish implemented the rolling, weekly, search quota shape and tickPercent regeneration behavior documented by the PR. (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: Current-main blame and commit metadata show steipete on the current Synthetic source/docs snapshot and this PR also includes a steipete correction commit. (role: recent area contributor; confidence: medium; commits: a83a83fa4131, 3bec6bf43594; files: docs/providers.md, Sources/CodexBarCore/Providers/Synthetic/SyntheticUsageStats.swift, Sources/CodexBarCore/Providers/Synthetic/SyntheticProviderDescriptor.swift)
• kiranmagic7: Beyond this PR, current-main history includes provider detail docs and provider Details-link work from kiranmagic7. (role: recent provider-doc contributor; confidence: medium; commits: 18fc600f2481, ba97bc8134dd, e2d95cca0fef; files: docs/providers.md, docs/t3chat.md, README.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.

Review history (1 earlier review cycle)

• reviewed 2026-07-07T00:45:04.268Z sha d71b8fa :: needs real behavior proof before merge. :: none

[steipete]

Maintainer proof for exact head 0c985bafb498d502635ec8c69dac7f33af072c06:

• Deep source-to-doc review corrected three user-visible claims before landing: Synthetic has no separate cost/credit lane, Search hourly appears in the menu card but is not a compact menu-bar metric, and the official status site is external rather than wired into CodexBar.
• Added official API-key, quota, and status references; the website provider card now opens the dedicated Synthetic guide. Reset fallback wording matches the parser's actual duration behavior.
• Exact documentation gates pass: 159 local links, all 23 site locales / 139 messages, current docs/llms.txt, and git diff --check.
• Repository gates pass: make check, all 49 make test shards, and clean autoreview.
• Exact CI is green: changes, lint, both Linux builds, docs lint/build/test, and GitGuardian; macOS correctly skipped for a docs-only diff.
• Runtime/provider credential proof is not applicable to this documentation-only change; source-path, generated-site, official-link, and parser/display contract validation are the direct behavior proof.
• Public Model Identifier Gate: PASS. Dependency freshness: unchanged; no dependency added or updated.

Thanks for adding the missing provider reference, @kiranmagic7!