Skip to content

Commit 3d9ad44

Browse files
emir-karabegemir-karabeg
committed
docs: record production readiness evidence and release requirements
1 parent 66faa48 commit 3d9ad44

16 files changed

Lines changed: 3003 additions & 0 deletions

‎apps/docs/migration/domain-move.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,22 @@ The requested canonical destination is the apex `https://sim.ai/docs`, so its ro
2727
3. Update search citations and outbound links, then permanently redirect `docs.sim.ai/:path*` to `https://sim.ai/docs/:path*` with status 308. Match the old hostname explicitly, preserve queries and methods, and test existing MCP clients. Do not redirect the upstream alias.
2828
4. Verify the apex robots sitemap entry, canonical URLs and old-host deep links. Keep the previous deployment and routing configuration available for rollback.
2929

30+
## Required cutover evidence
31+
32+
Record the docs source commit, deployment IDs, upstream alias, routing revision and index backup before changing the route. Parameterize the existing verification harnesses for the prefix first: their current root-relative URLs do not prove `/docs` support.
33+
34+
| Check through the actual routing layer | Required result |
35+
| --- | --- |
36+
| `/docs`, `/docs/`, `/docs/introduction`, an unknown page and a nested API page | One intended root redirect, real unknown-page 404, correct article and metadata; no login/interstitial or redirect loop |
37+
| Sidebar, history, search, code copy, media viewer and direct fragments | Native and framework links retain exactly one `/docs`; old heading bookmarks reveal the correct ancestor panels |
38+
| Static images, optimizer URLs, fonts, JavaScript and RSC navigation | No root-path 404s or HTML returned for assets; hashes and image variants remain correct |
39+
| `.md`, `.mdx`, `/docs/llms.mdx/...`, llms files, OpenAPI, discovery, search and MCP | Complete representations and pagination; MCP discovery/read/search remains public and read-only, with its Origin and Host checks intact |
40+
| HTML/Markdown in both request orders, mixed Accept values, HEAD and validators | Correct content type/status/body and combined `Vary`; no HTML/Markdown/RSC cache contamination |
41+
| Old-host requests with queries and MCP POST bodies | 308 preserves path, query and method/body; verify fragment inheritance in a browser because fragments are not sent to the server |
42+
| Proxy request/response headers | Strip platform `Cookie` and `Authorization` before forwarding to public docs; do not relay upstream `Set-Cookie`; retain required protocol, representation and routing headers |
43+
| Root robots, sitemap, canonicals and consumers | `sim.ai/robots.txt` advertises the prefixed sitemap; no old-origin canonical or missing/duplicated prefix; VFS identities remain unchanged |
44+
| Citation publication | Matching-source plan/check and URL-only publication retain vectors; search result → full read → public heading works through the new origin |
45+
46+
Keep explicit redirect cache policy in the routing change. A 308 can be cached, so rollback must continue serving a known-good docs build at the new destination for clients retaining that redirect; redirecting the new destination back to the old host can create a loop. Fragment inheritance and 308 cacheability follow [HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html#name-308-permanent-redirect). Rehearse rollback on an isolated route: hold publishers, restore the paired routing/deployment/index state, then repeat representation, citation and credential-isolation checks. No rollback rehearsal through the future production route has been completed.
47+
3048
No domain, deployment, redirect or infrastructure settings were changed during this review. The path-aware build remains follow-up implementation, not an environment-variable-only switch.

‎apps/docs/migration/production-readiness.md‎

Lines changed: 362 additions & 0 deletions
Large diffs are not rendered by default.

‎apps/docs/migration/readiness/artifact-costs.json‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
{
2+
"node": "v24.19.0",
3+
"zlib": "1.3.2.1-motley-3246f1b",
4+
"method": "Same htmlparser2 parser and Node gzipSync default options; scripts compressed separately. Artifact sizes are distinct from observed network transfers.",
5+
"observations": [
6+
{
7+
"revision": "f06b2d6d535b5cd0a4a80c851e54cbdd7aef189d",
8+
"route": "introduction",
9+
"htmlBytes": 478723,
10+
"htmlGzipBytes": 41397,
11+
"rscBytes": 146897,
12+
"rscGzipBytes": 21249,
13+
"elements": 2327,
14+
"tables": 1,
15+
"rows": 6,
16+
"cells": 10,
17+
"headerCells": 2,
18+
"modernScriptReferences": 14,
19+
"modernScriptBytes": 789582,
20+
"modernScriptGzipBytes": 241762
21+
},
22+
{
23+
"revision": "f06b2d6d535b5cd0a4a80c851e54cbdd7aef189d",
24+
"route": "integrations/cloudflare",
25+
"htmlBytes": 15473385,
26+
"htmlGzipBytes": 665457,
27+
"rscBytes": 7359146,
28+
"rscGzipBytes": 329899,
29+
"elements": 45101,
30+
"tables": 152,
31+
"rows": 7838,
32+
"cells": 23623,
33+
"headerCells": 532,
34+
"modernScriptReferences": 14,
35+
"modernScriptBytes": 789582,
36+
"modernScriptGzipBytes": 241762
37+
},
38+
{
39+
"revision": "66faa48d018adaa7ebf540968f029455557cfef1",
40+
"route": "introduction",
41+
"htmlBytes": 481254,
42+
"htmlGzipBytes": 42450,
43+
"rscBytes": 145653,
44+
"rscGzipBytes": 21545,
45+
"elements": 2327,
46+
"tables": 1,
47+
"rows": 6,
48+
"cells": 10,
49+
"headerCells": 2,
50+
"modernScriptReferences": 14,
51+
"modernScriptBytes": 790903,
52+
"modernScriptGzipBytes": 242170
53+
},
54+
{
55+
"revision": "66faa48d018adaa7ebf540968f029455557cfef1",
56+
"route": "integrations/cloudflare",
57+
"htmlBytes": 6417366,
58+
"htmlGzipBytes": 480826,
59+
"rscBytes": 3393957,
60+
"rscGzipBytes": 258815,
61+
"elements": 45041,
62+
"tables": 152,
63+
"rows": 7838,
64+
"cells": 23623,
65+
"headerCells": 532,
66+
"modernScriptReferences": 14,
67+
"modernScriptBytes": 790903,
68+
"modernScriptGzipBytes": 242170
69+
}
70+
]
71+
}

‎apps/docs/migration/readiness/captures/expanded-platform-1440.png‎

305 KB
Loading

‎apps/docs/migration/readiness/captures/image-hero-1440.png‎

186 KB
Loading

‎apps/docs/migration/readiness/captures/mobile-drawer-search-navigation.webm‎

215 KB
Binary file not shown.

‎apps/docs/migration/readiness/captures/no-javascript-api-reference-logs-getLog.png‎

192 KB
Loading

‎apps/docs/migration/readiness/captures/responsive-dark-390.png‎

54.2 KB
Loading

‎apps/docs/migration/readiness/chunk-regression.json‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
{
2+
"measuredSource": "b313fcc70a59fbe4de0b2920554090e1c63e2bdd",
3+
"catalogContentRevision": "179c340e8069b59d770cfc763dd42602d8c66c76",
4+
"sourceContentUnchangedSinceCatalog": true,
5+
"conditions": "Bun, compiled real documentation; no provider or database calls. Before and negative controls restore the faulty chunk behavior; the final source is restored.",
6+
"regressions": {
7+
"before": [
8+
{
9+
"name": "Compiled publication chunks preserve code, tables, context and bounded payloads",
10+
"status": "failed",
11+
"durationMs": 32,
12+
"error": "/api-reference/access-requests/cancelOrganizationAccessRequest:response-200:0: unclosed fenced code"
13+
}
14+
],
15+
"control-context": [
16+
{
17+
"name": "Compiled publication chunks preserve code, tables, context and bounded payloads",
18+
"status": "failed",
19+
"durationMs": 34,
20+
"error": "/api-reference/access-requests/cancelOrganizationAccessRequest:response-200:1: continuation lost its page/section context"
21+
}
22+
],
23+
"control-table-header": [
24+
{
25+
"name": "Compiled publication chunks preserve code, tables, context and bounded payloads",
26+
"status": "failed",
27+
"durationMs": 604,
28+
"error": "/integrations/buffer: fitting table row or repeated header lost"
29+
}
30+
],
31+
"control-oversized-cell": [
32+
{
33+
"name": "Compiled publication chunks preserve code, tables, context and bounded payloads",
34+
"status": "failed",
35+
"durationMs": 3815,
36+
"error": "/integrations/plane: oversized table cell lost content"
37+
}
38+
],
39+
"after": [
40+
{
41+
"name": "Compiled publication chunks preserve code, tables, context and bounded payloads",
42+
"status": "passed",
43+
"durationMs": 3943
44+
}
45+
]
46+
},
47+
"allCatalog": {
48+
"pages": 803,
49+
"totalChunks": 28131,
50+
"maxCharacters": 5996,
51+
"durationMs": 6442,
52+
"errors": []
53+
}
54+
}

‎apps/docs/migration/readiness/image-delivery.csv‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
sourceRevision,testedMergeRevision,image,viewport,dpr,sourceWidth,renderedWidth,requestedWidth,currentSrc,format,startMs,responseEndMs,transferSize,encodedBodySize,deliveryType
2+
66faa48d018adaa7ebf540968f029455557cfef1,4a9977a2c1ed434f8251f67cfa77ab78961f7f79,detail,1440,1,1036,651.21875,828,/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Flog-trace.38byz2e6e2nmg.webp&w=828&q=90,image/webp,78.2,82.6,20412,20112,
3+
66faa48d018adaa7ebf540968f029455557cfef1,4a9977a2c1ed434f8251f67cfa77ab78961f7f79,detail,390,3,1036,311,1080,/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Flog-trace.38byz2e6e2nmg.webp&w=1080&q=90,image/webp,35.2,84.9,28696,28396,
4+
66faa48d018adaa7ebf540968f029455557cfef1,4a9977a2c1ed434f8251f67cfa77ab78961f7f79,detail,768,2,1036,651.21875,1440,/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Flog-trace.38byz2e6e2nmg.webp&w=1440&q=90,image/webp,55.6,105.2,28696,28396,
5+
66faa48d018adaa7ebf540968f029455557cfef1,4a9977a2c1ed434f8251f67cfa77ab78961f7f79,hero,1440,1,2400,564.265625,640,/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fplatform.0_5pdtc3y55g0.webp&w=640&q=90,image/webp,12.7,18.7,15076,14776,
6+
66faa48d018adaa7ebf540968f029455557cfef1,4a9977a2c1ed434f8251f67cfa77ab78961f7f79,hero,390,3,2400,304.234375,1080,/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fplatform.0_5pdtc3y55g0.webp&w=1080&q=90,image/webp,9.2,64.3,33986,33686,
7+
66faa48d018adaa7ebf540968f029455557cfef1,4a9977a2c1ed434f8251f67cfa77ab78961f7f79,hero,768,2,2400,564.265625,1440,/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fplatform.0_5pdtc3y55g0.webp&w=1440&q=90,image/webp,10.8,95.8,49088,48788,
8+
66faa48d018adaa7ebf540968f029455557cfef1,4a9977a2c1ed434f8251f67cfa77ab78961f7f79,overview,1440,1,2400,622.09375,640,/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ffiles-markdown.0z2kmbeqkuuqt.webp&w=640&q=90,image/webp,70.4,106,19780,19480,
9+
66faa48d018adaa7ebf540968f029455557cfef1,4a9977a2c1ed434f8251f67cfa77ab78961f7f79,overview,390,3,2400,297,1080,/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ffiles-markdown.0z2kmbeqkuuqt.webp&w=1080&q=90,image/webp,67.3,127.1,42586,42286,
10+
66faa48d018adaa7ebf540968f029455557cfef1,4a9977a2c1ed434f8251f67cfa77ab78961f7f79,overview,768,2,2400,622.09375,1440,/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Ffiles-markdown.0z2kmbeqkuuqt.webp&w=1440&q=90,image/webp,40.1,128.3,61608,61308,
11+
66faa48d018adaa7ebf540968f029455557cfef1,4a9977a2c1ed434f8251f67cfa77ab78961f7f79,result,1440,1,1470,651.21875,828,/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Flaunch-update-draft.22mzpcer3azfz.webp&w=828&q=90,image/webp,217.8,262.3,48144,47844,
12+
66faa48d018adaa7ebf540968f029455557cfef1,4a9977a2c1ed434f8251f67cfa77ab78961f7f79,result,390,3,1470,311,1080,/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Flaunch-update-draft.22mzpcer3azfz.webp&w=1080&q=90,image/webp,232.1,307.7,66734,66434,
13+
66faa48d018adaa7ebf540968f029455557cfef1,4a9977a2c1ed434f8251f67cfa77ab78961f7f79,result,768,2,1470,651.21875,1440,/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Flaunch-update-draft.22mzpcer3azfz.webp&w=1440&q=90,image/webp,232.3,344.1,93394,93094,

0 commit comments

Comments
 (0)