fhammerschmidt · Oct 10, 2026 · Oct 9, 2026 · Oct 9, 2026
diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml
@@ -84,6 +84,10 @@ jobs:
 
           for _ in {1..15}; do
             if curl --max-time 2 --fail --silent http://127.0.0.1:8789/ > /dev/null; then
+              curl --max-time 2 --fail --silent http://127.0.0.1:8789/robots.txt | cmp public/robots.txt -
+              for guide_icon in build/client/assets/*.avif; do
+                curl --max-time 2 --fail --silent "http://127.0.0.1:8789/${guide_icon#build/client/}" | cmp "$guide_icon" -
+              done
               exit 0
             fi
             sleep 1

diff --git a/.gitignore b/.gitignore
@@ -10,7 +10,6 @@ node_modules/
 .next/
 out/
 apps/docs/out/
-apps/guide/out/
 index_data/*.json
 apps/docs/index_data/*.json
 

diff --git a/.oxfmtrc.json b/.oxfmtrc.json
@@ -12,6 +12,7 @@
     "*.swo",
     "*.swp",
     "apps/docs/app/**/*.mjs",
+    "apps/guide/app/**/*.jsx",
     "build",
     "data/api/**/*.json",
     "apps/docs/data/api/**/*.json",

diff --git a/apps/guide/README.md b/apps/guide/README.md
@@ -16,6 +16,7 @@ contract only. Lesson copy belongs to the guide author.
 | `app/GuideHome.res`               | Guide workspace UI                               |
 | `app/GuideCompilerBridgeHook.res` | Browser compiler and execution integration       |
 | `styles/main.css`                 | Guide-only visual system and responsive behavior |
+| `public/`                         | Guide static assets, including `robots.txt`      |
 | `__tests__/`                      | Browser and unit coverage for the guide          |
 
 ## Lesson Contract
@@ -71,9 +72,12 @@ yarn build:guide
 yarn workspace @rescript-lang/guide ci:test
 ```
 
-`yarn build:guide` compiles ReScript, pre-renders `/`, and copies the client
-assets to `apps/guide/out/` for Wrangler. The guide fetches available compiler
-versions from `https://cdn.rescript-lang.org` during pre-rendering; the
+`yarn build:guide` compiles ReScript and pre-renders `/` into
+`apps/guide/build/client/`, the assets directory configured in `wrangler.toml`.
+Vite serves and copies the guide's `public/` directory, including `robots.txt`.
+The root route imports the shared docs favicons so Vite emits them with the
+guide's other assets. The guide fetches available compiler versions from
+`https://cdn.rescript-lang.org` during pre-rendering; the
 interactive compiler and runtime then run in the learner's browser.
 
 ## Current Capability
@@ -92,7 +96,7 @@ show a stop screen rather than a usable guide.
 
 ## Production Checklist
 
-Before launch, complete and verify the following:
+Track outstanding guide launch work in this checklist:
 
 - [ ] Author, review, and run every lesson using its real expected output.
 - [ ] Add a content-validation test for the complete lesson set, including
@@ -108,6 +112,7 @@ Before launch, complete and verify the following:
       compiler and checkpoint changes.
 - [ ] Choose mobile support or explicitly publish the desktop-only constraint
       with an alternate learning path.
+- [ ] Define the supported browsers and initial page-load performance budget.
 - [ ] Split or defer the initial compiler/editor code so the initial route is
       within the agreed performance budget.
 - [ ] Replace the deprecated Vite `envFile` configuration and resolve the
@@ -121,6 +126,6 @@ Before launch, complete and verify the following:
 ## Deployment
 
 The `deploy-guide` job in `.github/workflows/deploy.yml` builds the guide and
-deploys it with Wrangler. Pushes to `master` deploy the production Worker;
-non-Dependabot pull requests from this repository receive a preview Worker
+deploys its `build/client/` assets with Wrangler. Pushes to `master` deploy the
+production Worker; non-Dependabot pull requests from this repository receive a preview Worker
 version and a link in the pull request.
diff --git a/apps/guide/TODO.md b/apps/guide/TODO.md
diff --git a/apps/guide/app/root.jsx b/apps/guide/app/root.jsx
@@ -3,56 +3,80 @@
 import * as ReactRouter from "react-router";
 import * as JsxRuntime from "react/jsx-runtime";
 import MainCssurl from "../styles/main.css?url";
+import FaviconX16AvifurlnoInline from "../../docs/public/favicon/favicon-16x16.avif?url&no-inline";
+import FaviconX32AvifurlnoInline from "../../docs/public/favicon/favicon-32x32.avif?url&no-inline";
+import AppleTouchIconAvifurlnoInline from "../../docs/public/favicon/apple-touch-icon.avif?url&no-inline";
 
 let mainCss = MainCssurl;
 
+let appleTouchIcon = AppleTouchIconAvifurlnoInline;
+
+let favicon32 = FaviconX32AvifurlnoInline;
+
+let favicon16 = FaviconX16AvifurlnoInline;
+
 function Root$default(props) {
-  return (
-    <html lang={"en"}>
-      <head>
-        <link href={mainCss} rel={"stylesheet"} />
-        <ReactRouter.Links />
-        <ReactRouter.Meta />
-        <meta charSet={"UTF-8"} />
-        <meta
-          content={"width=device-width, initial-scale=1"}
-          name={"viewport"}
-        />
-        <meta content={"ReScript Guide"} name={"application-name"} />
-        <meta
-          content={"An interactive guide to learning ReScript."}
-          name={"description"}
-        />
-        <meta content={"#f6f4ef"} name={"theme-color"} />
-        <link
-          href={"/apple-touch-icon.avif"}
-          rel={"apple-touch-icon"}
-          sizes={"180x180"}
-        />
-        <link
-          href={"/favicon-32x32.avif"}
-          rel={"icon"}
-          sizes={"32x32"}
-          type={"image/avif"}
-        />
-        <link
-          href={"/favicon-16x16.avif"}
-          rel={"icon"}
-          sizes={"16x16"}
-          type={"image/avif"}
-        />
-        <title>{"ReScript Guide"}</title>
-      </head>
-      <body>
-        <ReactRouter.Outlet />
-        <ReactRouter.ScrollRestoration />
-        <ReactRouter.Scripts />
-      </body>
-    </html>
-  );
+  return <html
+    lang={"en"}
+  >
+    <head>
+      <link
+        href={mainCss}
+        rel={"stylesheet"}
+      />
+      <ReactRouter.Links />
+      <ReactRouter.Meta />
+      <meta
+        charSet={"UTF-8"}
+      />
+      <meta
+        content={"width=device-width, initial-scale=1"}
+        name={"viewport"}
+      />
+      <meta
+        content={"ReScript Guide"}
+        name={"application-name"}
+      />
+      <meta
+        content={"An interactive guide to learning ReScript."}
+        name={"description"}
+      />
+      <meta
+        content={"#f6f4ef"}
+        name={"theme-color"}
+      />
+      <link
+        href={appleTouchIcon}
+        rel={"apple-touch-icon"}
+        sizes={"180x180"}
+      />
+      <link
+        href={favicon32}
+        rel={"icon"}
+        sizes={"32x32"}
+        type={"image/avif"}
+      />
+      <link
+        href={favicon16}
+        rel={"icon"}
+        sizes={"16x16"}
+        type={"image/avif"}
+      />
+      <title>
+        {"ReScript Guide"}
+      </title>
+    </head>
+    <body>
+      <ReactRouter.Outlet />
+      <ReactRouter.ScrollRestoration />
+      <ReactRouter.Scripts />
+    </body>
+  </html>;
 }
 
 let $$default = Root$default;
 
-export { $$default as default };
+export {
+  $$default as default,
+}
 /* mainCss Not a pure module */
diff --git a/apps/guide/app/root.res b/apps/guide/app/root.res
@@ -1,6 +1,16 @@
 @module("../styles/main.css?url")
 external mainCss: string = "default"
 
+// Share the official icons while keeping the guide's own public directory.
+@module("../../docs/public/favicon/apple-touch-icon.avif?url&no-inline")
+external appleTouchIcon: string = "default"
+
+@module("../../docs/public/favicon/favicon-32x32.avif?url&no-inline")
+external favicon32: string = "default"
+
+@module("../../docs/public/favicon/favicon-16x16.avif?url&no-inline")
+external favicon16: string = "default"
+
 @react.component
 let default = () => {
   <html lang="en">
@@ -13,9 +23,9 @@ let default = () => {
       <meta name="application-name" content="ReScript Guide" />
       <meta name="description" content="An interactive guide to learning ReScript." />
       <meta name="theme-color" content="#f6f4ef" />
-      <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.avif" />
-      <link rel="icon" type_="image/avif" sizes="32x32" href="/favicon-32x32.avif" />
-      <link rel="icon" type_="image/avif" sizes="16x16" href="/favicon-16x16.avif" />
+      <link rel="apple-touch-icon" sizes="180x180" href=appleTouchIcon />
+      <link rel="icon" type_="image/avif" sizes="32x32" href=favicon32 />
+      <link rel="icon" type_="image/avif" sizes="16x16" href=favicon16 />
       <title> {React.string("ReScript Guide")} </title>
     </head>
     <body>

diff --git a/apps/guide/app/root.resi b/apps/guide/app/root.resi
@@ -1,2 +1,3 @@
+// Keep build asset bindings private; React Router consumes the root component.
 @react.component
 let default: unit => React.element
diff --git a/apps/guide/react-router.config.mjs b/apps/guide/react-router.config.mjs
@@ -1,9 +1,4 @@
-import * as fs from "node:fs";
-
 export default {
   ssr: false,
   prerender: ["/"],
-  buildEnd: async () => {
-    fs.cpSync("./build/client", "./out", { recursive: true });
-  },
 };
diff --git a/apps/guide/vite.config.mjs b/apps/guide/vite.config.mjs
@@ -42,8 +42,6 @@ export default defineConfig(({ mode }) => {
 
   return {
     envDir: "../..",
-    // Reuse the official favicon set without duplicating branding assets.
-    publicDir: "../docs/public/favicon",
     plugins: [
       env({ prefix: "PUBLIC_" }),
       ...(isTest ? [] : [reactRouter()]),