Audit: complete the Fumadocs migration, correct the docs, repo hygiene

[arturict]

Context

A full multi-agent audit of the repo ran across six dimensions (public API design, provider-adapter consistency, internal cleanliness, package/repo hygiene, docs accuracy, docs-stack choice), with every finding adversarially verified against the source. This PR ships the docs and hygiene outcomes; the SDK behavior findings are listed below as follow-ups so they can be reviewed on their own.

Note: this branch builds on codex/fumadocs-docs (the "Use Fumadocs for documentation UI" commit), so that commit is included here.

Questioning the docs choice: verdict

Fumadocs is the right tool — but the previous commit adopted it as a UI skin only. For a small TS SDK with docs inside an existing Next.js app on Vercel, Docusaurus/Starlight (second framework) and Mintlify (hosted) are worse fits, and Fumadocs is the best-maintained Next-native option. However, the migration had kept hand-written TSX content, a hand-built page tree, hand-maintained per-page TOCs, title-only search over 14 hardcoded links, and no syntax highlighting — full dependency cost, none of the content-tooling benefit. The audit's verdict: either complete the migration or revert; the half-adopted state was strictly worse than both. This PR completes it.

What this PR does

Docs stack — real Fumadocs content pipeline

• All 14 docs pages move to content/docs/*.mdx sourced via fumadocs-mdx (source.config.ts + loader() + catch-all route); original URLs and anchor ids are preserved
• Navigation tree, TOCs, and sitemap are generated from the content source (previously three hand-maintained copies)
• Full-text search over headings and body text via createFromSource + the default search dialog (was: title-only filter over 14 links, with dead links config)
• Syntax highlighting via shiki for every code sample (was: monochrome)
• llms.txt / llms-full.txt are generated from the MDX source instead of hand-maintained strings that could silently drift
• RootProvider moves to the root layout with a static dark class on <html> (portaled UI now inherits the theme); explicit heading/list defaults in globals.css so non-docs pages render identically whether or not Tailwind's preflight has loaded
• Source-grep tests replaced with checks against the content source; deleted: docs-shell.tsx, docs-search.tsx, lib/docs.ts, 14 TSX pages

Docs content corrections (each verified against the SDK source)

• GitHub: the claim "unknown labels are rejected instead of silently created" was false — labels are forwarded unchecked; documented truthfully. Issue-type (kind) read/write support was understated; apiBaseUrl (GitHub Enterprise Server) and fetch options were undocumented
• Linear: "creates need a team from the adapter or input.project" was false — teamId is required, input.project only assigns a project; accessToken/endpoint options and the canceled state mapping documented
• Jira: accessToken, issueType, priorityNameByCanonical options documented
• Testing guide: the recording/inspection API (calls, seed, clearCalls, workCommentFixture, fullWorkCapabilities, capability overrides) documented
• Reference pages: gitlab added to provider enumerations; error.code documented as the discriminator that stays reliable in CJS/mixed module graphs
• Guide article: Linear/Jira concurrency descriptions corrected (both use a revision-fingerprint preflight; Jira has no provider version checks)

Repo hygiene

• Root CHANGELOG.md: missing 0.5.0 and 0.3.1 entries added; docs/idempotency.md no longer pinned to v0.4
• Dead 26-line minimumReleaseAgeExclude list removed (no minimumReleaseAge is set); duplicate .vercel gitignore entry removed; private example/app packages ignored in changesets; unused WorkItemPriority import removed

Verification

• pnpm --filter work-sdk build && test: 186/186 pass
• apps/web: tsc --noEmit clean, next build clean (all 14 docs paths SSG), 11/11 site tests pass
• Manually verified against a running production build: sidebar tree + separators, generated TOCs, preserved anchors, search hits on body text, shiki output, callouts, all corrections present in rendered HTML, llms.txt/llms-full.txt generated

Follow-ups from the audit (not in this PR — SDK behavior changes)

High severity:

1. CJS build duplicates the error class hierarchy per entry (tsup.config.ts): instanceof WorkConflictError silently fails for CJS/mixed consumers because every dist/*.cjs inlines its own WorkError copy. Fix: share one errors chunk in CJS or export type guards
2. Prepared changes bind to the provider name, not the adapter instance (client.ts:200): a plan prepared against GitHub repo A commits through repo B's client; the idempotency store key has the same gap. Fix: add a scope identity to WorkAdapter, verify it in commit(), include it in store keys
3. list({state}) post-filter uses states the read mapping can never produce on GitHub/GitLab/Jira → permanently empty pages for some filters
4. acceptWarnings contract broken for GitHub/GitLab: adapters hard-throw on fields the client only warns about
5. retryAfterMs reported as 0 when the rate-limit header is absent (Jira/Linear/Azure) — callers that sleep retryAfterMs busy-loop

Medium: memory adapter update() maps every state to "unknown" (breaks parity with real adapters); requestJson in http.ts is dead code while five adapters hand-duplicate error translation with drift; write types accept priority "unknown" that every adapter rejects; five divergent auth option shapes; verifyApplied exists in only 3/5 adapters; GitLab silently collapses canceled→completed on write; two divergent npm publish workflows (tag-triggered one bypasses the protected npm environment); MemoryIdempotencyStore shares mutable receipt references; Azure stateForWrite self-defeating lowercase map lookup.

🤖 Generated with Claude Code

[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, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.