diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000000..f37313e1c77
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,173 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is **backpack-react-scripts**, a Skyscanner fork of Facebook's Create React App (specifically the `react-scripts` package). It provides a customized build toolchain for React applications that use Skyscanner's Backpack design system. The fork is based on Create React App v5+ and adds Skyscanner-specific configuration and build features.
+
+## Monorepo Structure
+
+This is a Lerna monorepo with workspaces defined in the root `package.json`. Key packages:
+
+- **`packages/react-scripts/`**: The main package containing webpack configs, build scripts, and the Backpack addons
+- **`packages/create-react-app/`**: Global CLI for bootstrapping new apps
+- **`packages/babel-preset-react-app/`**: Babel preset configuration
+- **`packages/eslint-config-react-app/`**: ESLint configuration
+- **`packages/react-dev-utils/`**: Shared utilities for development tooling
+- **`packages/react-error-overlay/`**: Development error overlay UI
+- **Other packages**: Templates, polyfills, and supporting packages
+
+## Build Commands
+
+### Root Level Commands
+
+```bash
+# Install dependencies (runs postinstall to build react-error-overlay)
+npm install
+
+# Run development server (uses template in packages/cra-template/template)
+npm start
+
+# Build production bundle
+npm run build
+
+# Run tests
+npm test
+
+# Run integration tests
+npm run test:integration
+
+# Run tests for backpack-addons specifically
+npm run test:addons
+
+# End-to-end tests (requires setup)
+npm run e2e
+
+# End-to-end tests in Docker
+npm run e2e:docker
+
+# Lint entire codebase
+npm run eslint
+
+# Format code with Prettier
+npm run format
+
+# Create a new app using local version
+npm run create-react-app
+```
+
+### Testing End-to-End
+
+To test locally without full e2e setup:
+
+```bash
+npx jest test/ --watchAll
+```
+
+To filter tests (e.g., webpack messages only):
+
+- Press `p`
+- Type pattern like `webpack-message`
+- Press enter
+
+## Architecture: Backpack Addons System
+
+The key architectural feature is the **backpack-addons** system located in `packages/react-scripts/backpack-addons/`. This provides customization points for webpack configuration without ejecting.
+
+### Adding New Backpack Addons
+
+1. Create the feature module in `packages/react-scripts/backpack-addons/`
+2. In webpack config files that use the addon (e.g., `webpack.config.js`, `webpack.config.ssr.js`):
+ - Add `// #backpack-addon {{featureName}}` comment on every modified line
+ - Require the addon module rather than writing inline code
+3. Document the addon in `packages/react-scripts/backpack-addons/README.md`
+
+### Available Backpack Addons
+
+Configuration is read from `"backpack-react-scripts"` field in consuming app's `package.json`:
+
+- **`babelIncludePrefixes`**: Module name prefixes to opt into Babel compilation (default: `["@skyscanner/bpk-", "bpk-"]`)
+- **`sriEnabled`**: Enable Subresource Integrity for security (default: `false`)
+- **`crossOriginLoading`**: Configure cross-origin loading for chunks (default: `false`)
+- **`ignoreCssWarnings`**: Suppress CSS ordering warnings (default: `false`)
+- **`cssModules`**: Enable CSS modules (default: `true`)
+- **`amdExcludes`**: Modules to exclude from AMD parsing (default: `["lodash"]`)
+- **`externals`**: Webpack externals configuration (default: `{}`)
+- **`ssrExternals`**: Externals for SSR bundle only (default: `{}`)
+- **`enableAutomaticChunking`**: Enable vendor/common chunk splitting (default: `false`)
+- **`vendorsChunkRegex`**: Regex for vendor chunk content (requires `enableAutomaticChunking`)
+- **`splitChunksConfig`**: Direct webpack splitChunks config (ignored if `enableAutomaticChunking` is true)
+- **`enableBpkStylesChunk`**: Create single chunk for all Backpack CSS (default: `false`)
+
+### Server-Side Rendering (SSR)
+
+The fork includes SSR support with a separate webpack config:
+
+- **`config/webpack.config.ssr.js`**: SSR-specific webpack configuration
+- **`scripts/start-ssr.js`**: Development script that runs both client and SSR builds
+- **`backpack-addons/ssr/`**: SSR-specific utilities including:
+ - `forkSsr.js`: Forking logic for parallel client/SSR builds
+ - `isSsr.js`: Detection of SSR environment
+ - `customWebpackUtils.js`: SSR webpack customization utilities
+ - `MultiCompilerUi.js`: UI for displaying parallel build status
+ - `statusFile.js`: Status reporting for multi-compiler setup
+
+## Key Webpack Configuration Files
+
+- **`config/webpack.config.js`**: Main client-side webpack config
+- **`config/webpack.config.ssr.js`**: Server-side rendering webpack config
+- **`config/webpackDevServer.config.js`**: Dev server configuration
+- **`config/paths.js`**: Path resolution and structure
+- **`config/env.js`**: Environment variable handling
+
+## Build Output Differences
+
+Beyond standard CRA output, this fork generates:
+
+- **`build/css.html`**: HTML partial with `` tags for all CSS files
+- **`build/js.html`**: HTML partial with `