feat(site): consolidate API documentation into top-level API Docs section

[bryanfawcett]

Creates the API Docs section housing all API documentation, per Bryan's request.

What moved where

API docs previously lived in three places with two duplicate gateway overviews. Now one top-level api/ section:

Old	New
platform/api/{overview,authentication,security}	api/{overview,authentication,security}
integrations/nyuchi-api/{commerce,pay,logistics,lingo,news,weather}	api/{...} (unchanged content)
integrations/api-gateway + integrations/nyuchi-api/overview (duplicate overviews, the latter stale — Stytch-era)	consolidated into api/overview

Astro redirects cover every old slug, so existing links and AI Search citations keep resolving.

Content updates (reflecting current architecture)

• New api/api-keys page: API access is managed in the console as client ID + secret pairings (nyk_/nys_, X-Client-Id/X-Client-Secret or combined X-API-Key), scoped to public namespaces — verified against the gateway's api_key_middleware.
• Auth reframed as WorkOS-only: AuthKit is the sign-in method; the Stytch OTP section shrunk to a legacy retirement note. Stale bits removed (Supabase-fan-out claim, the 20260510_add_workos_user_id.sql migration aside).
• Sidebar gets the new API Docs section (Getting started + Namespaces); the API groups under Platform and Integrations are removed.
• README section list and llms.txt re-synced (per the repo's sidebar/README drift rule).

Verification

pnpm build passes: 52 pages, all 10 api/* pages emitted, redirect stubs confirmed (e.g. /platform/api/overview → /api/overview), Pagefind index builds.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HN4J2Brr46rQySBZb95bNy

---

Generated by Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	shamwari-docs-ai	3fa919b	Commit Preview URL Branch Preview URL	Jul 19 2026, 07:20 AM

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	nyuchi-docs-mcp	3fa919b	Commit Preview URL Branch Preview URL	Jul 19 2026, 07:20 AM

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	nyuchi-docs	3fa919b	Commit Preview URL Branch Preview URL	Jul 19 2026, 07:20 AM

[claude]

Approving — this is a straightforward docs consolidation (moving/renaming API pages into a new top-level section, adding redirects, resyncing README/llms.txt) with no changes to application logic. One inline nit was left about a stale cross-page claim in security.mdx; it's a documentation-consistency issue only and doesn't block merge.

Extended reasoning...

Overview

This PR consolidates API documentation (previously split across platform/api/*, integrations/api-gateway.mdx, and integrations/nyuchi-api/*) into a single top-level api/ section. It renames/moves files, adds a new api/api-keys.mdx page, rewrites the authentication/overview pages to reflect a WorkOS-only auth model, adds Astro redirects for every old slug, and resyncs the sidebar, README, and llms.txt. It also adds two LICENSE files for publishable packages.

Security risks

None. This is a content/documentation change — no application code, auth logic, or infrastructure config is touched. The rewritten authentication docs describe (rather than implement) the JWT/WorkOS flow, so there's no risk of introducing an actual auth bypass.

Level of scrutiny

Low-to-moderate is appropriate: this is docs-only with mechanical file moves (confirmed via git renames) and redirects covering every old slug, which the PR description says were verified with a full pnpm build. The main risk in a PR like this is cross-page factual consistency, which is exactly what the one inline finding flags — a leftover Supabase RLS claim in security.mdx that the rewritten authentication.mdx/overview.mdx no longer support. It's flagged as a nit because nothing builds or executes differently; a reader could still be misled, so it's worth fixing but doesn't rise to a blocking issue.

Other factors

No CODEOWNERS or security-sensitive paths are touched. The redirect map looks complete against the file moves in the diff, and the sidebar/README/llms.txt updates are consistent with each other. No outstanding unaddressed reviewer comments exist on this PR.

[claude]

🟡 This PR removes the Supabase-JWT/RLS framing from api/authentication.mdx and api/overview.mdx (per the PR description: "Stale bits removed (Supabase-fan-out claim...)"), but api/security.mdx — renamed by this PR and linked from both pages' "Next steps" — still asserts at line 68: "Per-user authorisation belongs in the platform JWT and Supabase RLS... Supabase resolves auth.uid() from it." A reader following the PR's own updated auth flow lands on a page reasserting the claim just called stale.

Extended reasoning...

The bug: api/security.mdx line 68 reads:

Per-user authorisation belongs in the platform JWT and Supabase RLS. Every /v1 request that touches user data carries the JWT, and Supabase resolves auth.uid() from it.

This is precisely the mechanism this PR removed from the sibling pages it consolidates alongside. authentication.mdx previously said the token was "signed with the Supabase JWT secret" and that both auth flows let auth.uid() resolve to identity.person.id "for Supabase row-level security" — both sentences are gone. overview.mdx changed "fans out across multiple Supabase-backed product databases" to "backed by its own product database." The PR description states the intent explicitly: "Stale bits removed (Supabase-fan-out claim...)".

Why this is reachable, not just a stray sentence: security.mdx isn't an untouched bystander file elsewhere in the tree — this PR moved it into the new top-level api/ section and both rewritten pages route readers straight to it. authentication.mdx's "Next steps" list ends with a link to /api/security for "security and rate limits before going live," and overview.mdx does the same. So the PR's own updated documentation funnel puts a reader who just read the WorkOS-only JWT explanation directly onto a page asserting that same JWT backs Supabase RLS via auth.uid().

Addressing the refutation: One reviewer argued this isn't a contradiction because the removed text was about a client-facing capability (hitting Supabase directly with the JWT) while security.mdx describes an internal enforcement path, and that WorkOS-for-sign-in and Supabase-for-RLS are orthogonal layers. That distinction doesn't hold up: Supabase's auth.uid() mechanism is not layer-agnostic — it works specifically because the JWT is signed with (or otherwise verifiable via) the Supabase JWT secret/JWKS, which is exactly the fact authentication.mdx dropped as "stale." If the JWT is no longer signed in a way Supabase can verify, security.mdx's claim that "Supabase resolves auth.uid() from it" is no longer true either — the two facts aren't independent, the second depends on the first. So either the removal in authentication.mdx/overview.mdx was correct and security.mdx is now stale, or Supabase RLS is genuinely still wired up and the removal from the other two pages was premature. Either way the three pages disagree with each other on a factual question a reader would reasonably expect a single consistent answer to.

Proof walkthrough:

1. Reader opens /api/authentication (per this PR): learns the platform JWT is HS256, minted via WorkOS AuthKit, and "works for every /v1/* namespace, because it carries the person id in sub" — no Supabase mentioned.
2. Reader clicks "Read security and rate limits before going live" in the Next steps section, landing on /api/security.
3. Line 68 tells them: "Per-user authorisation belongs in the platform JWT and Supabase RLS... Supabase resolves auth.uid() from it."
4. The reader now has two irreconcilable mental models of the same JWT from two pages in the same PR's own consolidated section, with no way to tell which is current.

Fix: Update security.mdx's "Where to enforce what" bullet to match whatever the actual current per-user authorization mechanism is (e.g. gateway-side authorization checks against the platform JWT's sub, with no Supabase RLS involvement) — or, if Supabase RLS genuinely is still in play, restore the signing detail in authentication.mdx/overview.mdx so the three pages agree.

This is a documentation-consistency issue only — nothing builds, runs, or crashes differently — so it shouldn't block merge, but it should be fixed in this PR since security.mdx is part of the same consolidation and is directly linked from the two rewritten pages.