Docs accuracy + register sweep: 45 pages verified against source

[DrAlexHarrison]

MERGE-WARDEN-HOLD (2026-07-25): adversarial review found ~34 code-cited defects, 4/4 spot-confirmed, plus STEALTH feature detail committed to a PUBLIC repo. Needs your call on the stealth disclosure. Awaiting Alex.

Six Opus agents swept every page on docs.saturday.fit for two things at once: factual accuracy against the shipped code, and compliance with the AI-writing ruleset captured 2026-07-23.

The coaching tab had one light register pass in #26. The API Guides tab, 25 pages and ~4,700 lines, had never had an accuracy pass at all.

What a partner hit before this

Every code sample sent a literal sk_test_abc123def456 to api.saturday.fit, which returns 401. Sandbox keys only work against a base URL issued with the key, so the copy-paste path failed for both audiences at once. The quickstart's worked totals were also 33% high, so a partner checking the math against their own output would have concluded the engine was wrong. That is the first ninety seconds of every partner evaluation. All 33 occurrences across eight pages now use an environment variable, and every Python block is syntax-checked.

Invented API surface, removed

The AI coach SSE format did not exist: real events are message_start, text_delta, tool_call, tool_result, safety_warning, error, message_end, all JSON, with no [DONE] sentinel. The tool-budget table named three tools that do not exist. batch-operations documented a metadata wrapper, a scenario label, and a top-level athlete_id, none of which exist, and promised external_id deduplication that is not implemented, so a partner retrying a failed import duplicates their roster.

Corrections with direct customer impact

• The Coach API gate is Pro Coach and above, not Business. The docs were telling paying subscribers to upgrade for access they already had. Both SDKs already had it right; the docs were the outlier.
• Coach webhook registration succeeds on any tier but only delivers on Business and Enterprise. Now stated, including that nothing on the endpoint object says so.
• Rate limits apply per account, not per key. X-RateLimit-Reset is delta seconds, not a Unix timestamp.
• X-Saturday-Data-Training does not exist and is removed from two pages. X-Saturday-Data-License is now quoted exactly.
• deployment.mdx said the docs site is hosted at api.saturday.fit, making every llms.txt, openapi.yaml, and mcp URL on it wrong.
• Both attribution.mdx examples used the dark-background asset on a light page, so the copy-paste example rendered invisible.

Coaching docs

The pages described a Coach Portal that has since moved. ?view=manage deep-links are inert, /admin/billing redirects to Stripe Connect payouts, roles live on Access & Roles. Assistants start at Pro Coach, not Head Coach. A "senior assistant" preset role was documented and does not exist. Org-paid coverage has no tier gate at all. Assignment does not grant visibility: a newly activated assistant sees the head coach's whole roster read-only immediately.

Nutrition: eco-mode is a five-position spectrum, not a toggle; there is no concentration dial; and the gluc:fruc ratio sets the blend rather than raising the carb ceiling.

AI coach guide

The endpoint returns a 404 byte-identical to an unknown route so its existence cannot be detected, while a public guide announced it. Moved to drafts/, which .mintignore excludes wholesale, and removed from nav and from the introduction feature table. Content preserved for whenever the stage moves.

Verification

Nav matches disk in both directions, every internal link resolves, 24 Python and 32 JSON blocks parse, zero em dashes, zero dead brand, no secrets or internal paths.

Not included, needs your ruling

data-policy.mdx promises a 30-day retention grace and GDPR export window that nothing implements, and DELETE is an immediate hard delete so the export window cannot exist. Left unedited: you ruled to build the purge instead. safety.mdx drops a worked example whose numbers are not producible; the teaching intent is sound and it needs real values.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Y9Yok49jHDcx2DvirP6EXT

[DrAlexHarrison]

merge-warden: HOLD, not merged

I re-verified this PR's own claims independently and they held up well (rate limits, tier gates, SSE names, batch dedup, quickstart arithmetic, eco-mode positions, live DNS/API, cross-repo portal routes, all 67 /v1 paths real). Mechanically it is clean: nav resolves, 176/176 internal links, 0 em dashes, no leaked keys.

Then the mandated second adversarial lens (codex, max effort, reading fuel-backend@69747154) found a large set of defects that my pass missed. I spot-checked four and all four confirmed, so I am treating the rest as credible and not merging.

Confirmed by me directly

1. SaturdayInc/docs is a public repo (private: false). .mintignore stops Mintlify rendering drafts/ai-coach.draft.mdx, it does not stop GitHub serving it. So moving the STEALTH AI-coach guide into drafts/ publishes its SSE events, tool budgets, concurrency and body limits to anyone reading the repo. This one is your call, which is why this is a HOLD rather than a fix.
2. authentication.mdx:38-40 runs curl -H ... https://api.saturday.fit/v1/nutrition/calculate with no -X POST and no body. Only POST /v1/nutrition/calculate is registered (cmd/partner-api/main.go:106), so the sample 405s.
3. error-handling.mdx over-deletion. The PR removed the correct not_found_error row and the "branch on type, not code" note, replacing them with a claim that a 404's type is resource_not_found. Per pkg/gateway/middleware.go:803-813 the canonical 404 is type: not_found_error, code: resource_not_found. This replaced correct guidance with incorrect guidance.
4. Six Python fences call modules they never import (requests in batch-operations.mdx:157,269, organizations.mdx:72,175, oauth2.mdx:197; os in mcp-integration.mdx:119). Every one raises NameError as printed. Note the PR's own "24 Python blocks parse" check, and mine, both used ast.parse, which validates syntax and structurally cannot catch this.

Not yet verified by me, reported as-is

Codex also reports STEALTH names still in the public corpus (llms.txt:26, feature-gates.mdx:83-85,100, oauth2.mdx:243,248, introduction.mdx:25) which would contradict feature-gates.mdx:121's own statement that STEALTH features are omitted from docs; wrong coach-key scopes in authentication.mdx:36; GET /v1/ described as key-aware when it is unauthenticated and global; rate headers described as per-caller when built from global defaults; a 14-day BETA notice promise the backend contradicts; requires_human_review documented as conditional when nutrition_service.go:149-155 sets it unconditionally false; warnings: [] shown where the API emits null; several impossible batch response bodies and field shapes; end_date marked optional where the handler rejects its absence; DELETE /v1/athletes/{id} labelled cascading when cascade is POST .../delete; four documentation_url anchors that do not exist; a missing /guides/ai-coach redirect; and dead assets including saturday.fit/logo.png (404), which the backend also ships at nutrition_service.go:309,328,345.

Full findings with file:line and backend evidence are in the run log. Nothing here is a criticism of the sweep's direction, which corrected a lot of genuinely broken partner-facing content. It just is not ready to publish.

No changes pushed. The branch is exactly as its author left it.