feat(docs): rebuild documentation with the shared Sim design system
Summary
Replaces Fumadocs with a Sim-owned Next.js documentation site, one compiled catalog, and centrally managed reading/navigation components. Preserves the approved light/dark design, platform screenshot backgrounds and rounding, persistent sidebar, existing routes and machine interfaces. The catalog supplies HTML, Markdown, navigation, search, metadata, JSON discovery and public read-only MCP.
The production-readiness pass independently compared main and staging, audited the Fumadocs responsibility transfer, traced platform consumers, reproduced defects, implemented fixes, ran /cleanup, and measured immutable production builds in CI. Full audit, parity/consumer matrices, measurements, captures and release checklist.
Corrections
- Preserve Markdown structure on 26 screenshot-rich pages and restore the Google OAuth scope table. All 495 authored documents, 22,012 staging headings, 1,236 fences, 308 API operations, seven specifications and 187 public assets are accounted for.
- Restore six API request languages and shared language preference; handle downloads/streams correctly; expose root streaming schemas and all labeled panels without JavaScript.
- Preserve complete code lines/fences, table headers and continuation context in bounded search chunks. Harden publication freshness, URL-only vector reuse, per-page atomic replacement, retirement ordering, retry bounds and cooperating-writer serialization. Exercise actual platform direct-table search → document read → citation with isolated Postgres and a provider transport fixture.
- Serve responsive, hashed screenshot/background variants with originals on expansion. Retain the original public assets and intended framing.
- Remove repeated table classes and synchronous scroll-region layout reads. Use client footer navigation and intent-gated full prefetch; a real pending-prefetch regression proves a large destination is transferred once.
- Correct inline-link/GET-label accessibility, absolute Markdown canonicals, cached Git modification dates, clean-checkout generated types and obsolete publisher workflow references.
Main baseline: a52fc509b5b8a18df519ff0781f00c8d45711164. Latest incorporated staging: 3175daab84bfc2d7dfc8d924d55313190c280476. Intentional newer product content is retained. The 489 platform VFS identities remain compatible. Ordinary builds do not regenerate historical migration evidence.
Measured results
Comparison: audit-start f06b2d6d535b5cd0a4a80c851e54cbdd7aef189d → final source f54d9f5a69cb0b3f79dd8503eccacbbc3459694e. Three trials per profile/route; medians below, with final-head ranges below and the earlier source 66faa48 raw observations retained in the report. Production builds, pinned Chromium/Playwright/Lighthouse; mobile network and CPU are throttled.
| Measurement | Before | Final |
|---|---|---|
| Cloudflare decoded HTML | 15.47 MB | 6.42 MB, same table content |
| Cloudflare desktop intent navigation | 519 ms | 146 ms |
| Cloudflare throttled mobile intent navigation | 3,450 ms | 1,881 ms |
| Introduction desktop initial image bodies | 215,372 B | 43,334 B |
| Cloudflare mobile Lighthouse performance | 62 | 87 |
All 300 navigation/interaction observations and 42 Lighthouse runs completed. All 84 ordinary navigations preserved the shared shell without document reloads; all six history checks restored scroll. Accessibility/best practices scored 100 throughout. Performance ≥90 in 35/42; Workflow SEO 92 in six runs because genuine product links read “Start.” Heavy mobile navigation has a 1.88 s median but a 2.28 s slow trial; mobile LCP/performance targets remain partially unmet. Ordinary JavaScript is roughly flat; Workflow renderer code remains absent from ordinary-page requests. These are lab results, not field CWV or a universal speed claim.
Validation
Final head f54d9f5a69cb0b3f79dd8503eccacbbc3459694e incorporates staging 3175daab84bfc2d7dfc8d924d55313190c280476. The preceding check caught seven expected-asset mismatches after staging changed three Search screenshots and the account-connection guide. Independent Git/Fumadocs reconstruction confirms unchanged page/heading/fence/operation counts; exact byte-preservation assertions remain intact. Failure/refresh evidence.
Final-head confirmation
Exact source: f54d9f5a69cb0b3f79dd8503eccacbbc3459694e. Production benchmark 41122450924: 300/300 interaction observations, 42/42 Lighthouse reports. Same pinned profiles and three repetitions as the retained earlier comparison; Node 24.22.1/Bun 1.4.4. Times below are medians (min–max) in milliseconds, n=3.
| Profile / route | Cold article paint | Repeat | Uncached navigation | Intent navigation |
|---|---|---|---|---|
desktop /introduction | 85 (84–108) | 66 (58–70) | 98 (98–99) | 79 (78–81) |
desktop /getting-started | 99 (88–102) | 76 (64–79) | 97 (94–98) | 79 (76–80) |
desktop /files/editor | 108 (81–120) | 66 (63–71) | 99 (99–99) | 80 (80–80) |
desktop /search/find-content | 98 (97–100) | 69 (68–79) | 99 (96–102) | 79 (79–80) |
desktop /integrations/cloudflare | 194 (186–209) | 151 (144–177) | 172 (171–184) | 146 (138–210) |
desktop /api-reference/logs/getLog | 124 (120–124) | 86 (85–113) | 116 (115–183) | 80 (73–169) |
desktop /workflows | 100 (95–159) | 109 (74–136) | 113 (107–132) | 86 (82–94) |
mobile /introduction | 997 (991–1004) | 392 (317–402) | 414 (396–430) | 150 (107–153) |
mobile /getting-started | 969 (944–995) | 390 (312–411) | 505 (397–948) | 132 (123–940) |
mobile /files/editor | 969 (950–1066) | 345 (295–649) | 495 (431–907) | 255 (168–773) |
mobile /search/find-content | 961 (946–1037) | 319 (297–591) | 446 (437–720) | 186 (167–518) |
mobile /integrations/cloudflare | 1013 (999–1101) | 513 (466–705) | 1913 (1736–2166) | 1881 (1868–2284) |
mobile /api-reference/logs/getLog | 1008 (995–1063) | 352 (344–435) | 580 (580–726) | 591 (588–623) |
mobile /workflows | 931 (920–943) | 316 (313–362) | 413 (413–433) | 370 (350–395) |
| Profile / route | Performance raw trials | LCP ms | TBT ms |
|---|---|---|---|
desktop /introduction | 100/100/100 | 76 (52–111) | 0 (0–0) |
desktop /getting-started | 100/100/100 | 58 (58–100) | 0 (0–0) |
desktop /files/editor | 100/100/100 | 82 (63–131) | 0 (0–0) |
desktop /search/find-content | 100/100/100 | 93 (75–140) | 0 (0–0) |
desktop /integrations/cloudflare | 100/100/100 | 96 (89–98) | 0 (0–0) |
desktop /api-reference/logs/getLog | 98/98/98 | 73 (67–90) | 0 (0–0) |
desktop /workflows | 100/100/100 | 63 (52–118) | 0 (0–0) |
mobile /introduction | 95/91/91 | 3440 (3006–3442) | 6 (6–13) |
mobile /getting-started | 100/100/100 | 904 (904–904) | 3 (1–5) |
mobile /files/editor | 88/100/88 | 3905 (1054–3907) | 6 (4–6) |
mobile /search/find-content | 100/100/89 | 904 (904–3761) | 6 (5–20) |
mobile /integrations/cloudflare | 87/87/87 | 3155 (3154–3155) | 46 (26–61) |
mobile /api-reference/logs/getLog | 100/100/100 | 1205 (1204–1205) | 39 (34–42) |
mobile /workflows | 100/86/100 | 1205 (1204–4210) | 18 (12–21) |
| Control / timing boundary | Desktop ms | Throttled mobile ms |
|---|---|---|
| Search opens | 76 (48–89) | 89 (86–162) |
| Query → visible results | 335 (322–2324) | 867 (855–911) |
| Result selection → article | 167 (150–184) | 787 (770–882) |
| Media dialog feedback | 98 (48–122) | 124 (110–155) |
| Theme change | 70 (69–72) | 81 (81–145) |
| Request language | 82 (82–83) | 118 (115–183) |
| Response status | 67 (66–83) | 99 (83–166) |
| Schema disclosure | 63 (58–64) | 90 (76–104) |
| Copy selected request | 83 (83–84) | 83 (83–117) |
| Response format | 83 (66–100) | 182 (132–194) |
| Workflow inspector | 155 (146–210) | 161 (128–175) |
These are medians/ranges, n=3. Most normal desktop controls meet the approximate 100 ms median target; Workflow inspector does not. First query startup remains visible in the 2,324 ms desktop outlier. The cold pre-hydration shortcut remains unavailable in the three mobile observations; readiness-gated controls passed.
All 42 accessibility/best-practice scores are 100; SEO is 100 in 36 and 92 in six Workflow runs. Performance ≥90 in 35/42. Mobile misses are Cloudflare (3), Files (2), Search (1) and Workflow (1). Maximum CLS remains 0.08676. The Files/Search/Workflow reports show large simulated-LCP swings with the same reported paragraph insight node; observed FCP/LCP boundaries differ by microseconds or a few milliseconds in some trials. This suggests simulation timing/dependency sensitivity, but does not establish the exact cause or dismiss the budget misses. No new reproducible source defect was demonstrated. These are not field measurements.
All 84 ordinary navigations preserved the shell without reloading; all 30 consecutive moves avoided reloads; all six history trials restored 500→500px. Introduction image bodies remain 43,334B desktop/76,340B phone. The updated Search screenshot increases its 1080w/q90 body 8,956→18,436B, and mobile Search image bodies 57,084→66,564B. That increase is real; the reports do not prove it caused the score variation. Ordinary JS remains 790,903 decoded bytes (14 requests; 246,370 transferred including headers); Workflow remains 1,848,583 decoded (18 requests; 641,074 transferred). Cloudflare retains all 152 tables/7,838 rows and 6,417,366 decoded HTML bytes (480,825 gzip).
The final docs run 41122392480 tested merge 844b118a34d3e328b941f0aa56034ecee572f61d: all 2,996 corpus, 12 negotiation, 18 interface, 16 header, 20 PostgreSQL, 2 platform-fixture, 40 sample and 22 generator checks passed. Chromium 74 passed; WebKit 71 passed/3 unsupported. Both generator passes left zero changed files. The in-flight navigation transferred one 258,967B page body plus 348B tree metadata. Final root CI 41122392658 passed all 39 required jobs. The non-blocking security audit still reports 42 advisories (1 critical/15 high/19 moderate/7 low).
Raw reports and captures are in those CI artifacts (14-day retention; preview build 3 days). The earlier source 66faa48 observations remain committed in the audit report with their original provenance. This confirmation preserves current-head medians, ranges, individual performance scores and validation provenance in the PR without rewriting historical measurements.
Release assessment
Ready for staging review; not cleared for production release or first index publication. The following production release requirements remain separate from the staging merge:
- One isolated live embedding attempt returned 401. Successful real-provider verification and fixed-query semantic relevance remain required; fixture vectors do not establish ranking quality.
- Preview SSO remains enabled. Live production returned 403 during the initial audit, so further automated traffic stopped. Candidate HTML/Markdown/RSC cache separation still needs verification through the real CDN. PSI returned 429; no usable field data was obtained.
- Native Safari, browser Find/zoom/text scaling and a screen-reader session remain unverified. WebKit automation and emulation are labeled accordingly.
- Shared non-blocking dependency audit still reports 42 advisories. An intermediate CI run also exposed an intermittent platform React 419 recovery failure; subsequent passes do not prove it fixed. Neither was hidden or suppressed.
Hold the automatic main index publisher before production promotion until the matching docs deployment and explicit index backup are verified. Publication is atomic per page, not across the entire catalog. The workflow does not create a backup and checks out moving main. Rollback requires the paired docs deployment/index snapshot; legacy snapshots need legacy reader/citation checks rather than the new freshness checker.
Current canonicals remain https://docs.sim.ai. The sim.ai/docs cutover is deferred; the exact routing/asset/protocol/citation/rollback checklist is maintained. No production index, routing, domain, deployment settings or security protections were changed. The exact final production artifact is running locally on port 3001; the updated Search screenshot was inspected in the shared expanded viewer, preserving its scenery and rounded frame.
Captures
Expanded image · API without JavaScript ·
Final interaction QA
Revision d7ae1ebd7a insets the mobile search hover surface while retaining its 44px target, aligns API example pickers with the shared docs menus, preserves keyboard selection and focus restoration, removes dark-mode TOC overflow, protects IME composition in search, and refreshes the index when serialized workflow examples change.
Three independent cleanup passes reviewed the changes; the picker accessibility ID relationship was corrected before push. Focused Biome and whitespace checks pass. Full builds, repository gates, Chromium/WebKit regression checks and production benchmarks run in CI; this revision is not considered cleared until those checks and both review bots finish. All cofounder commits are preserved.