diff --git a/.oxfmtrc.json b/.oxfmtrc.json
index 85a79c701..1bb91247a 100644
--- a/.oxfmtrc.json
+++ b/.oxfmtrc.json
@@ -37,6 +37,6 @@
     "apps/docs/public/llms/react/**/llm*.txt",
     "apps/docs/markdown-pages/docs/**/**/llms.mdx",
     "apps/docs/markdown-pages/docs/manual/installation.mdx",
-    ".yarn/releases/yarn-4.12.0.cjs"
+    ".yarn/releases/*.cjs"
   ]
 }
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
index 241f2c935..9cf683216 100644
--- a/.vscode/extensions.json
+++ b/.vscode/extensions.json
@@ -1,3 +1,3 @@
 {
-  "recommendations": ["esbenp.prettier-vscode", "chenglou92.rescript-vscode"]
+  "recommendations": ["oxc.oxc-vscode", "chenglou92.rescript-vscode"]
 }
diff --git a/AGENTS.md b/AGENTS.md
index 20a6c4e85..cbf94c8d9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,47 +2,64 @@
 
 ## Project Overview
 
-This is the official documentation website for the [ReScript](https://rescript-lang.org) programming language. It is primarily pre-rendered at build time, with runtime server-side rendering for `/try` through Cloudflare Pages Functions. It is built with **ReScript v12 + React 19 + React Router v8 + Vite 8 + Tailwind CSS v4**, deployed to **Cloudflare Pages**.
+This monorepo contains the official documentation website for the [ReScript](https://rescript-lang.org) programming language and the interactive guide. Both use **ReScript v12 + React 19 + React Router v8 + Vite 8**. The docs site uses Tailwind CSS v4 and is primarily pre-rendered at build time, with runtime server-side rendering for `/try` through Cloudflare Pages Functions. The guide pre-renders its entry page and runs its interactive lessons in the browser, with assets served by a Cloudflare Worker.
 
 ## System Requirements
 
 - Node.js ≥ 26
-- Yarn 4.12.0 (via Corepack)
+- Yarn 4.13.0 (via Corepack, pinned in `package.json` and `.yarnrc.yml`)
 
 ## Project Structure
 
 ```
-app/              → React Router app shell (root layout, route definitions, route modules)
-  routes/         → Route components with loaders (e.g. BlogRoute.res, MdxRoute.res)
-src/              → Core ReScript source code
-  bindings/       → Zero-cost bindings to JS libraries (@module externals)
-  common/         → Shared utilities, hooks, helpers (non-component modules)
-  components/     → Reusable React components (e.g. SidebarNav, Breadcrumbs)
-  ffi/            → Plain JS interop files (prefer %raw over adding new files here)
-  layouts/        → Page layout components (DocsLayout, SidebarPageLayout, etc.)
-markdown-pages/   → MDX content (blog posts, docs, community pages, syntax-lookup)
-data/             → Hand-curated data (API docs JSON, sidebar ordering)
-styles/           → CSS files (Tailwind v4 config in main.css, custom utilities)
-scripts/          → Build/codegen scripts (ReScript + JS)
-functions/        → Cloudflare Pages Functions (e.g. OG image generation)
-compilers/        → Bundled ReScript compiler versions (for the playground)
-plugins/          → HighlightJS & CodeMirror plugins
-public/           → Static assets (images, fonts, favicons)
-__tests__/        → Vitest browser-mode tests (Playwright)
+apps/docs/                 → Documentation website workspace (@rescript-lang/docs)
+  app/                     → React Router shell, layouts, and route modules
+    routes/                → Page components and loaders (e.g. BlogRoute.res)
+  src/                     → Website ReScript code
+    bindings/              → App-specific bindings to JS libraries
+    common/                → Shared website utilities and hooks
+    components/            → Reusable React components
+    ffi/                   → Legacy plain JS interop
+    layouts/               → Page layout components
+    markdown/              → MDX loading, compilation, and frontmatter parsing
+  markdown-pages/          → Blog, docs, community, and syntax-lookup MDX
+  data/                    → Sidebar ordering and content metadata
+  styles/                  → Tailwind v4 entry points, theme, and custom CSS
+  scripts/                 → Build, code generation, and validation scripts
+  functions/               → Pages Functions for /try, /try.data, and OG images
+  server/                  → React Router request handler for Pages Functions
+  public/                  → Static assets (images, fonts, favicons)
+  __tests__/               → Vitest browser and visual tests
+  e2e/                     → Cypress browser tests
+apps/guide/                → Interactive guide workspace (@rescript-lang/guide)
+packages/playground/       → Shared browser playground (@rescript-lang/playground)
+packages/shared/           → Shared bindings and utilities (@rescript-lang/shared)
+  src/                     → ReactRouter, Vitest, CodeMirror, highlighting, etc.
+  plugins/                 → CodeMirror 6 ReScript/Reason grammar
+data/api/                  → Compiler-published API JSON snapshots
+.github/                   → CI, deployment, and screenshot workflows
 ```
 
+Paths in these guidelines are relative to the repository root. Run the commands
+below from there; use `yarn workspace <name> <command>` for workspace commands.
+The playground loads published browser compiler bundles. Markdown example checks
+use the installed `rescript` package, not a separate compiler installation.
+
 ## Key Commands
 
-| Command          | Purpose                                                        |
-| ---------------- | -------------------------------------------------------------- |
-| `yarn dev`       | Run ReScript watcher + Vite dev server + Wrangler (parallel)   |
-| `yarn build`     | Full production build (ReScript → scripts → Vite/React Router) |
-| `yarn build:res` | ReScript compilation only                                      |
-| `yarn dev:res`   | ReScript watch mode only                                       |
-| `yarn format`    | Run Prettier + ReScript formatter                              |
-| `yarn test`      | Run example and href validation scripts                        |
-| `yarn vitest`    | Run Vitest browser tests with Playwright                       |
-| `make`           | Build (install deps + ReScript compile + update index)         |
+| Command             | Purpose                                                      |
+| ------------------- | ------------------------------------------------------------ |
+| `yarn dev`          | Run ReScript watcher + Vite dev server + Wrangler (parallel) |
+| `yarn build`        | Build and pre-render the docs site                           |
+| `yarn build:guide`  | Build and pre-render the interactive guide                   |
+| `yarn build:res`    | Compile ReScript across all four workspaces                  |
+| `yarn dev:res`      | ReScript watch mode only                                     |
+| `yarn format`       | Run Oxfmt and format ReScript across all four workspaces     |
+| `yarn test`         | Run example, href, and redirect validation scripts           |
+| `yarn vitest`       | Run docs Vitest browser tests in watch mode                  |
+| `yarn vitest:guide` | Run guide Vitest browser tests in watch mode                 |
+| `yarn ci:test`      | Run docs and guide Vitest browser tests headlessly           |
+| `make`              | Build (install deps + ReScript compile + update index)       |
 
 ## Coding Best Practices
 
@@ -52,11 +69,11 @@ __tests__/        → Vitest browser-mode tests (Playwright)
 - `.res` files must always be capitalized (PascalCase), matching ReScript module conventions.
 - Use the pipe-first operator (`->`) for chaining, which is idiomatic ReScript.
 - Resolve all warnings and treat them as errors. The project has `"error": "+8"` in `rescript.json`.
-- Never directly edit an `.jsx` files, you must edit the corresponding `.res` file. The `.jsx` files are generated by the ReScript compiler and will be overwritten on the next compile.
+- Never directly edit generated `.jsx` files; edit the corresponding `.res` file and rebuild. Most compiler output is ignored by Git; the guide's `apps/guide/app/root.jsx` and `apps/guide/app/routes.jsx` are tracked and must be regenerated with their sources.
 
 ## ReScript Rules
 
-- You use **ReScript v12** (latest). Ensure all suggestions match this version.
+- This branch uses **ReScript v12**. Ensure all suggestions match this version.
 - Ensure any produced JSX matches ReScript JSX v4 syntax (configured with `"preserve": true`).
 - **Never use the `Belt` or `Js` modules** — these are legacy. Use the modern `Stdlib` / core modules instead.
 - Always use the `JSON.t` type for JSON values.
@@ -78,7 +95,7 @@ __tests__/        → Vitest browser-mode tests (Playwright)
 
 The project uses several patterns for JavaScript interop. Follow the existing conventions:
 
-- **`@module` externals** for binding to npm packages (see `src/bindings/` for examples):
+- **`@module` externals** for binding to npm packages (see `apps/docs/src/bindings/` and `packages/shared/src/` for examples):
   ```
   @module("react-router") external useNavigate: unit => string => unit = "useNavigate"
   ```
@@ -87,21 +104,17 @@ The project uses several patterns for JavaScript interop. Follow the existing co
   @module("react-router") @react.component
   external make: (~children: React.element) => React.element = "Outlet"
   ```
-- **`%raw()`** for inline JS when no clean binding is possible:
-  ```
-  let copyToClipboard: string => bool = %raw(`function(str) { ... }`)
-  ```
-- **`%%raw()`** (double percent) for top-level side-effectful JS imports.
+- `%raw` and `%%raw` embed JavaScript; use them only when specifically requested.
 - **`@scope`** for binding to object properties like `process.env`.
 - **`external ... = "%identity"`** for zero-cost type coercions.
-- Put new bindings in `src/bindings/` as a dedicated module (e.g. `Fuse.res`, `DocSearch.res`).
+- Put app-specific bindings in `apps/docs/src/bindings/` as a dedicated module (e.g. `Fuse.res`, `DocSearch.res`). Bindings shared with the guide or playground belong in `packages/shared/src/`.
 
 ## ReScript React
 
 - This project uses **React 19** and **React Router v8** (framework mode).
 - The site uses hybrid rendering: most routes are pre-rendered during the build, while `/try` is server-rendered by Cloudflare Pages Functions at runtime.
 - Loaders for pre-rendered routes can access the filesystem during the build. Runtime SSR loaders, including shared loader code reachable from `/try`, execute in Cloudflare and must not depend on Node-only filesystem APIs or other build-time-only operations.
-- Route modules live in `app/routes/` and export a `loader` and a `default` component.
+- Docs route modules live in `apps/docs/app/routes/`; the guide's route modules live in `apps/guide/app/`. Routes can export a `loader`, `links`, and a `default` component as needed.
 - Route modules **require** both a `.res` and a `.resi` (interface) file for Vite HMR to work.
 - Only a single React component can be exposed from a module's JS output.
 
@@ -153,21 +166,21 @@ let default: unit => React.element
 
 ## Styling
 
-- **Tailwind CSS v4** configured via the Vite plugin (`@tailwindcss/vite`). There is no `tailwind.config.js`.
-- Tailwind design tokens and custom utilities live in `styles/_theme.css`. It is imported by `styles/main.css` and referenced by route-specific stylesheets.
+- The docs site uses **Tailwind CSS v4**, configured via the Vite plugin (`@tailwindcss/vite`). Design tokens and custom utilities live in `apps/docs/styles/_theme.css`, imported by `apps/docs/styles/main.css` and referenced by route-specific stylesheets.
+- The guide uses its own plain CSS in `apps/guide/styles/main.css`.
 - **LightningCSS** is used as the CSS transformer.
-- The project defines custom design tokens in `styles/_theme.css`:
+- The project defines custom design tokens in `apps/docs/styles/_theme.css`:
   - Custom colors: `gray-*`, `fire-*`, `sky-*`, `berry-*`, `water`, `turtle`, `orange-*`
   - Custom font sizes: `text-11` through `text-68`
   - Custom utility classes: `hl-title`, `hl-1`–`hl-5`, `body-lg`, `body-md`, `body-sm`, `captions`
   - Fonts: Inter (sans), Roboto Mono (mono)
-- Use existing custom utilities and design tokens. Check `styles/_theme.css` before creating new ones.
+- Use existing custom utilities and design tokens. Check `apps/docs/styles/_theme.css` before creating new ones.
 
 ## Testing
 
 - Tests use **Vitest 5** in browser mode with **Playwright** (Chromium).
-- Test files live in `__tests__/` and are named `ComponentName_.test.res` (compiled to `.test.jsx`).
-- Tests use custom ReScript bindings in `src/bindings/Vitest.res`.
+- Browser tests live in `apps/docs/__tests__/` and `apps/guide/__tests__/`. Docs visual tests live in `apps/docs/__tests__/visual/`. Test modules are named `ComponentName_.test.res` (compiled to `.test.jsx`).
+- Tests use custom ReScript bindings in `packages/shared/src/Vitest.res`.
 - Tests are visual/integration tests that render components and assert visibility, interactions, and screenshots.
 - Test pattern:
 
@@ -185,22 +198,25 @@ let default: unit => React.element
 
 - Components requiring React Router context must be wrapped in `<MemoryRouter>`.
 - Do not use `<BrowserRouter>` in tests.
-- Run tests with `yarn vitest --browser.headless --run`.
-- Do not update snapshots without asking for confirmation.
+- Run `yarn build:res` first so the tests use current compiler output. Run `yarn vitest --browser.headless --run` for docs tests or `yarn vitest:guide --browser.headless --run` for guide tests. Run `yarn ci:test` to check both suites.
+- Do not update snapshots without asking for confirmation. Approved docs visual baseline changes use the `Update Visual Regression Screenshots` GitHub Actions workflow against the feature branch; pull and review the generated commit. Local screenshot updates are blocked by the Vitest configuration.
 
 ## MDX Content
 
-- Documentation content is in `markdown-pages/` organized by section (blog, docs, community, syntax-lookup).
-- MDX is processed by `react-router-mdx` with remark/rehype plugins.
-- Custom MDX components are mapped in `app/routes/MdxRoute.res` (e.g. `<Info>`, `<Warn>`, `<CodeTab>`, `<Video>`).
+- Documentation content is in `apps/docs/markdown-pages/`, organized by section (blog, docs, community, syntax-lookup).
+- `apps/docs/src/markdown/MdxFile.res` loads frontmatter and compiles MDX with `@mdx-js/mdx` and remark plugins. Route loaders pass the compiled content to `MdxContent`.
+- `apps/docs/src/components/MdxContent.res` evaluates compiled MDX with `runSync` and maps custom components (e.g. `<Info>`, `<Warn>`, `<CodeTab>`, `<Video>`).
 - Code examples in markdown use ` ```res ` (runnable), ` ```res sig ` (signature), and ` ```res prelude ` (shared context).
+- `yarn test` validates examples, relative links, and redirects. For matching CI's link-check failure behavior locally, run `CI=1 yarn test`; the link checker reports findings locally but only exits unsuccessfully for them when `CI` is set. It scans the full MDX tree and does not accept a glob filter.
 
 ## Formatting & Git Hooks
 
-- **Prettier** with the `@prettier/plugin-oxc` parser for JS formatting.
-- **ReScript formatter** (`rescript format`) for `.res` files.
-- **Lefthook** runs `yarn format` on pre-commit (auto-stages fixed files).
-- Generated `.mjs`/`.jsx` output files from ReScript are git-tracked but excluded from Prettier.
+- **Oxfmt** formats JavaScript, JSON, Markdown/MDX, CSS, and YAML, using `.oxfmtrc.json`.
+- **ReScript formatter** (`rescript format`) formats `.res` and `.resi` files.
+- `yarn format` runs both formatters from the repository root, covering all four workspaces. The docs workspace's `format` command delegates to the root command.
+- **Lefthook** runs Oxfmt and the ReScript formatter on matching staged files in parallel, then auto-stages formatting fixes. See `lefthook.yml` for the file patterns and commands.
+- Most generated `.jsx` output is ignored by Git. The two tracked guide entry modules are excluded from Oxfmt; regenerate them with the compiler.
+- `.vscode/extensions.json` recommends the Oxc formatter integration and the ReScript extension.
 
 ## Pull Requests and Commits
 
@@ -212,6 +228,5 @@ let default: unit => React.element
 
 - Do **not** modify generated `.jsx` / `.mjs` files directly — they are ReScript compiler output.
 - Do **not** use `@genType` — the project does not use it.
-- The `src/ffi/` directory is legacy; prefer `%raw` statements for new JS interop.
-- The README references some outdated structures (Next.js, `pages/` directory) — ignore those references. The project has migrated to React Router v8.
+- The `apps/docs/src/ffi/` directory is legacy; prefer bindings in `apps/docs/src/bindings/` or `packages/shared/src/` for new JS interop.
 - When editing route files, always update both the `.res` and `.resi` files.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 52911a232..c45f32bf3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -55,7 +55,21 @@ We try to keep our contribution guidelines to a minimum. Please keep following r
 
 The less code we write, the better. If there's a way to do rendering on the server, or enhance existing markdown files, we prefer that over client-side rendering and external loading.
 
-We also try to keep our third-party dependencies to a minimum. We use specific frameworks to make things work (`unified`, `remark`, `mdx`, `bs-platform`, etc). Please try to keep a small JS footprint, especially for client side code (to keep the bundle size small).
+We also try to keep our third-party dependencies to a minimum. The site uses ReScript v12, React, React Router, `@mdx-js/mdx`, and `remark`. Please try to keep a small JS footprint, especially for client side code (to keep the bundle size small).
+
+### Repository layout and tooling
+
+This is a Yarn workspace monorepo. The main website and its MDX content live in
+`apps/docs/`, the interactive guide lives in `apps/guide/`, and shared code lives
+in `packages/playground/` and `packages/shared/`. Run the root commands from the
+repository root; use `yarn workspace <name> <command>` to target one workspace.
+See the [README](README.md#project-structure-overview) for the directory map.
+
+Use Node.js 26 or newer and the Yarn 4.13.0 release pinned by the repository via
+Corepack. `yarn format` runs Oxfmt and formats ReScript across all four workspaces.
+The pre-commit hook formats matching staged files and stages its fixes. Edit
+ReScript sources rather than generated JavaScript; include regenerated guide
+entry modules when their sources change.
 
 ### Think about the target audience & UX
 
@@ -72,9 +86,9 @@ Always check if there are any designs for certain UI components and think about
 
 ### Tailwind for CSS Development
 
-We use [TailwindCSS](https://tailwindcss.com) for our component styling. Check out the [tailwind.config.js](tailwind.config.js) file for configured tailwind features, colors, border-radius values etc.. If you are not familiar with Tailwind, check out existing components for inspiration.
+The docs site uses [Tailwind CSS v4](https://tailwindcss.com) through the Vite plugin for component styling. Design tokens and custom utilities live in [apps/docs/styles/\_theme.css](apps/docs/styles/_theme.css). If you are not familiar with Tailwind, check out existing components for inspiration.
 
-We sometimes also need to fall back to common css (with tailwind `@apply` directives to enforce our style system). You can find the CSS main entrypoint in [styles/main.css](styles/main.css).
+We sometimes also need to fall back to common CSS (with Tailwind `@apply` directives to enforce our style system). The docs entry point is [apps/docs/styles/main.css](apps/docs/styles/main.css). The guide uses its own plain CSS in [apps/guide/styles/main.css](apps/guide/styles/main.css).
 
 **Only fall back to plain CSS if absolutely necessary**
 
@@ -84,6 +98,6 @@ Most of the stuff we want to build can be built as components with Tailwind clas
 
 - Clone the project and follow the [README](README.md) instructions
 - Always run the page locally and verify your changes (especially when working on code examples)
-- When writing markdown with code examples, always run `yarn test` to prevent broken code
+- When writing markdown with code examples, run `CI=1 yarn test` to check examples, relative links, and redirects with CI's link-check failure behavior. See the [README](README.md#markdown-example-and-link-checks) for targeted example checks and script working directories.
 - Feel free to open `Draft PRs` when you are working on bigger features (good for visibility and asking for feedback)
 - Improve code based on last feedback until the code is ready to be merged
diff --git a/README.md b/README.md
index bbd6c6718..151e313d8 100644
--- a/README.md
+++ b/README.md
@@ -4,9 +4,9 @@
 
 This is the official documentation platform for the [ReScript](https://rescript-lang.org) programming language.
 
-The site is a fully pre-rendered static app built with ReScript, React 19, React Router, Vite, and Tailwind CSS, and deployed to Cloudflare Pages.
+The docs site uses ReScript v12, React 19, React Router v8, Vite 8, and Tailwind CSS v4. Most routes are pre-rendered at build time; `/try` is server-rendered at runtime through Cloudflare Pages Functions.
 
-Route modules live in `app/routes/`, shared ReScript UI code lives in `src/`, and MDX content lives in `markdown-pages/`.
+This is a monorepo: the docs site lives in `apps/docs/`, the interactive guide in `apps/guide/`, and shared playground and library code in `packages/`. The guide pre-renders its entry page and runs its interactive lessons in the browser, with assets served by a Cloudflare Worker.
 
 **Please report any technical issues with ReScript to the [compiler repository](https://github.com/rescript-lang/rescript).**
 
@@ -71,36 +71,51 @@ Production crawler start URLs, ranking, and crawler schedules live in the Algoli
 
 ## Project Structure Overview
 
-- `app/`: React Router app shell, layouts, route definitions, and route modules
-- `src/`: ReScript source code for bindings, shared logic, components, and layouts
-- `markdown-pages/`: MDX content for docs, blog, community pages, and syntax lookup
-- `data/`: Hand-curated data such as sidebar ordering and content metadata
-- `scripts/`: Build, code generation, and validation scripts
-- `functions/`: Cloudflare Pages Functions
-- `styles/`: Tailwind v4 theme and custom CSS
-- `public/`: Static assets such as images, fonts, and favicons
-- `plugins/`: HighlightJS, CodeMirror, and other content/build plugins
-- `compilers/`: Bundled ReScript compiler versions for playground and example validation
-- `__tests__/`: Vitest browser tests written in ReScript
+- `apps/docs/app/`: React Router app shell, layouts, route definitions, and route modules
+- `apps/docs/src/`: Website bindings, utilities, components, layouts, and MDX compilation
+- `apps/docs/markdown-pages/`: MDX content for docs, blog, community pages, and syntax lookup
+- `apps/docs/data/`: Sidebar ordering and content metadata
+- `apps/docs/scripts/`: Build, code generation, and validation scripts
+- `apps/docs/functions/`: Cloudflare Pages Functions for `/try`, `/try.data`, and OG images
+- `apps/docs/styles/`: Tailwind v4 theme and custom CSS
+- `apps/docs/public/`: Static assets such as images, fonts, and favicons
+- `apps/docs/__tests__/`: Vitest browser tests; visual tests live in its `visual/` directory
+- `apps/docs/e2e/`: Cypress browser tests
+- `apps/guide/`: Interactive guide, lesson content, tests, and Worker configuration; see its [README](apps/guide/README.md)
+- `packages/playground/`: Shared browser playground components and compiler integration
+- `packages/shared/`: Shared bindings, utilities, highlighting, and the CodeMirror grammar in `plugins/`
+- `data/api/`: Compiler-published API JSON snapshots
 
-Tailwind is configured in [`styles/main.css`](styles/main.css). There is no `tailwind.config.js`.
+The playground loads published browser compiler bundles; `yarn build:sync-bundles` downloads them into the ignored `apps/docs/public/playground-bundles/` directory for deployment. Markdown example validation uses the installed `rescript` package.
+
+MDX is compiled by [`MdxFile.res`](apps/docs/src/markdown/MdxFile.res) using `@mdx-js/mdx` and remark plugins. [`MdxContent.res`](apps/docs/src/components/MdxContent.res) renders compiled content and maps custom components such as `Info`, `Warn`, and `CodeTab`.
+
+Tailwind v4 uses the Vite plugin and [`apps/docs/styles/main.css`](apps/docs/styles/main.css). Design tokens and custom utilities live in [`apps/docs/styles/_theme.css`](apps/docs/styles/_theme.css).
+
+The [recommended VS Code extensions](.vscode/extensions.json) provide ReScript support and [Oxfmt editor integration](https://oxc.rs/docs/guide/usage/formatter/editors.html). Oxfmt configuration lives in [`.oxfmtrc.json`](.oxfmtrc.json).
 
 ## Common Commands
 
-| Command              | Purpose                                                           |
-| -------------------- | ----------------------------------------------------------------- |
-| `yarn dev`           | Prepare generated files and run the local development environment |
-| `yarn build`         | Run the full production build                                     |
-| `yarn preview`       | Build and serve the generated static client locally               |
-| `yarn build:res`     | Generate route types and compile ReScript                         |
-| `yarn build:routes`  | Regenerate the shared ReScript route type                         |
-| `yarn check:routes`  | Check that the shared route type matches the current routes       |
-| `yarn dev:res`       | Run the ReScript compiler in watch mode                           |
-| `yarn format`        | Run Prettier and the ReScript formatter                           |
-| `yarn test`          | Run markdown example and href validation                          |
-| `yarn ci:test`       | Run Vitest browser tests headlessly                               |
-| `yarn vitest`        | Run Vitest directly                                               |
-| `yarn vitest:update` | Update screenshot baselines headlessly                            |
+Run these commands from the repository root. To target a workspace, use
+`yarn workspace <name> <command>`; the workspace names are `@rescript-lang/docs`,
+`@rescript-lang/guide`, `@rescript-lang/playground`, and `@rescript-lang/shared`.
+
+| Command              | Purpose                                                          |
+| -------------------- | ---------------------------------------------------------------- |
+| `yarn dev`           | Prepare generated files and run the docs development environment |
+| `yarn build`         | Build and pre-render the docs site                               |
+| `yarn build:guide`   | Build and pre-render the interactive guide                       |
+| `yarn preview`       | Build and serve the generated docs client locally                |
+| `yarn build:res`     | Generate route types and compile all four workspaces             |
+| `yarn build:routes`  | Regenerate the shared ReScript route type                        |
+| `yarn check:routes`  | Check that the shared route type matches the current routes      |
+| `yarn dev:res`       | Run the ReScript compiler in watch mode                          |
+| `yarn format`        | Run Oxfmt and format ReScript across all four workspaces         |
+| `yarn test`          | Run docs markdown example, href, and redirect validation         |
+| `yarn ci:test`       | Run docs and guide Vitest browser tests headlessly               |
+| `yarn vitest`        | Run docs Vitest browser tests in watch mode                      |
+| `yarn vitest:guide`  | Run guide Vitest browser tests in watch mode                     |
+| `yarn vitest:update` | Update screenshot baselines headlessly                           |
 
 ## Testing
 
@@ -113,16 +128,24 @@ adding or removing MDX pages, or updating API data during a watch session, run
 
 ### Vitest Browser Tests
 
-We use [Vitest](https://vitest.dev/) in browser mode with Playwright for component-level tests. Test files live in `__tests__/` and are written in ReScript.
+We use [Vitest](https://vitest.dev/) in browser mode with Playwright for component-level tests. ReScript test files live in `apps/docs/__tests__/` and `apps/guide/__tests__/`. Compile them before running Vitest:
 
 ```sh
-# Watch mode
+yarn build:res
+
+# Docs watch mode
 yarn vitest
 
-# Headless run (same mode used in CI)
+# Guide watch mode
+yarn vitest:guide
+
+# Headless docs and guide run (same mode used in CI)
 yarn ci:test
 ```
 
+For a headless run of a single suite, use `yarn vitest --browser.headless --run`
+for docs or `yarn vitest:guide --browser.headless --run` for the guide.
+
 To update screenshot baselines, run:
 
 ```sh
@@ -136,7 +159,7 @@ Only update screenshots that are intentionally affected by your change.
 `yarn test` runs the following:
 
 - `apps/docs/scripts/test-examples.mjs` to compile examples in the manual, React docs, guides and syntax lookup, and compare shown JS and JSX output with the installed compiler
-- `apps/docs/scripts/test-hrefs.mjs` to validate relative markdown links under `markdown-pages/`
+- `apps/docs/scripts/test-hrefs.mjs` to validate relative markdown links under `apps/docs/markdown-pages/`
 - `apps/docs/scripts/test-redirects.mjs` to validate redirect rules
 
 Supported ReScript markdown code fences:
@@ -163,19 +186,22 @@ Refresh generated JS output fences with the installed compiler and format the re
 yarn test --update
 ```
 
-You can also run the scripts directly:
+You can also run the scripts directly from the docs workspace:
 
 ```sh
-node apps/docs/scripts/test-examples.mjs
-node apps/docs/scripts/test-examples.mjs --update
-node apps/docs/scripts/test-examples.mjs "manual/module-functions.mdx"
-node apps/docs/scripts/test-examples.mjs --include-blog
-node apps/docs/scripts/test-hrefs.mjs
+cd apps/docs
+node scripts/test-examples.mjs
+node scripts/test-examples.mjs --update
+node scripts/test-examples.mjs "manual/module-functions.mdx"
+node scripts/test-examples.mjs --include-blog
+CI=1 node scripts/test-hrefs.mjs
 ```
 
 Example-checker patterns are relative to `apps/docs/markdown-pages/docs`. Historical blog posts describe earlier compiler versions, so the default run reports them as skipped. `--include-blog` audits them with the installed compiler; reported differences need review against the original version. Blog files are never rewritten, even with `--update`.
 
-Run `yarn test` before pushing content changes so CI does not fail on markdown regressions.
+The link checker scans the full MDX tree and does not accept a glob filter. It reports findings locally but only exits unsuccessfully for them when `CI` is set.
+
+From the repository root, run `CI=1 yarn test` before pushing content changes to match CI's link-check failure behavior as well as checking examples and redirects.
 
 ## Writing Blog Posts
 
diff --git a/apps/docs/package.json b/apps/docs/package.json
index 22b6ccdf6..761b69db1 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -26,7 +26,7 @@
     "dev:vite": "react-router dev --host",
     "dev:wrangler": "yarn build:vite && yarn wrangler pages dev build/client",
     "dev": "yarn prepare && yarn dev:res & yarn dev:vite & yarn dev:wrangler",
-    "format": "cd ../.. && oxfmt && cd apps/docs && rescript format",
+    "format": "cd ../.. && yarn format",
     "prepare": "yarn build:res && yarn build:scripts && yarn check:algolia-public-env && yarn build:update-index",
     "preview": "yarn build && static-server build/client",
     "serve:build": "static-server --host 127.0.0.1 --port 4173 build/client",
diff --git a/package.json b/package.json
index bd5bcbe2a..85ff9f9b8 100644
--- a/package.json
+++ b/package.json
@@ -27,7 +27,7 @@
     "dev:res": "yarn build:routes && rescript watch",
     "dev:guide": "yarn workspace @rescript-lang/guide dev:vite",
     "dev": "yarn workspace @rescript-lang/docs dev",
-    "format": "yarn workspace @rescript-lang/docs format",
+    "format": "oxfmt && rescript format",
     "preview": "yarn workspace @rescript-lang/docs preview",
     "reanalyze": "yarn workspace @rescript-lang/docs reanalyze",
     "test": "yarn workspace @rescript-lang/docs test",