diff --git a/.claude/commands/expose-option.md b/.claude/commands/expose-option.md
new file mode 100644
index 0000000000..7601e7a56e
--- /dev/null
+++ b/.claude/commands/expose-option.md
@@ -0,0 +1,49 @@
+---
+description: Thread a new option on an existing connector through all three flavors (JS, React, Vue) + common tests
+argument-hint: <connector> <optionName> [short description of what it does]
+---
+
+You are exposing a new option through the InstantSearch fan-out. The architecture is **connector (logic) → flavor wrapper → shared UI**, so the option is defined once in the connector and surfaced by each flavor.
+
+**Input:** `$ARGUMENTS`
+- First token = the connector (e.g. `connectRefinementList` or just `refinementList`).
+- Second token = the new option name (e.g. `clearOnChange`).
+- Remaining text = a short description of the behavior, if given.
+
+If the connector or option name is missing or ambiguous, ask before changing files. If the behavior isn't specified, ask what the option should do — do **not** guess at semantics.
+
+This is a checklist for a cross-flavor option rollout. The connector is the single source of truth; React and Vue only *wrap* it, so do the connector first, then the wrappers.
+
+## Steps
+
+1. **Scope the contract first.** Read the connector `packages/instantsearch.js/src/connectors/<name>/connect<Pascal>.ts` and its JS widget `packages/instantsearch.js/src/widgets/<name>/<name>.tsx`. Confirm the option doesn't already exist and settle the exact semantics + the option's type signature. This is the contract every flavor must match.
+
+2. **Connector first** (in `packages/instantsearch.js`):
+   - Add the option to the connector's widget-params type with a TSDoc comment.
+   - Implement the behavior in the lifecycle (`init`/`render`/`getWidgetSearchParameters`/etc.).
+   - Surface it on the **typed render state** if consumers need it (untyped render state is an oxlint error).
+   - Thread it through the JS widget. Keep it framework-agnostic — no React/Vue/DOM-framework code in the connector.
+
+   For a presentational-only variant, **reuse the existing connector** with a distinct `$$widgetType` — never fork connector logic.
+
+3. **If the option changes shared markup/layout** (not just behavior), update the shared `create<Name>Component` in `packages/instantsearch-ui-components` *before* wiring the flavors — its output is the contract they consume.
+
+4. **Thread it through the wrappers** (independent of each other once the connector is settled):
+   - **React** — the hook `packages/react-instantsearch-core/src/connectors/use<Pascal>.ts` and the component `packages/react-instantsearch/src/widgets/<Pascal>.tsx`, kept in sync and typed.
+   - **Vue** — `packages/vue-instantsearch/src/components/<Pascal>.{vue,js}` (and `src/mixins/` if wiring lives there), working for **both Vue 2 and Vue 3**.
+
+5. **Tests.** Cross-flavor behavior → add/extend `tests/common/connectors/<name>/` (or `.../widgets/<name>/`) and register it in each flavor's `common-*.test.*` (see `tests/common/README.md`); flavor-specific assertions stay in each package's co-located `__tests__/`. If browser-level behavior is affected, add an e2e spec (see `.claude/rules/e2e.md`).
+
+6. **Verify.** Confirm all three flavors expose the same option with consistent naming/types, then:
+   ```bash
+   yarn jest packages/instantsearch.js/src/connectors/<name>
+   yarn jest <the react/vue paths you touched>
+   yarn type-check
+   yarn lint:changed
+   ```
+   (Or run `/preflight`.)
+
+## Notes
+
+- Why this order: the connector is the contract; React and Vue only *wrap* it, so they're independent of each other and safe to do once the connector is settled.
+- Don't hand-edit changelogs (Ship.js generates them). Commit message: `feat(<widget>): add <optionName> option`.
diff --git a/.claude/commands/preflight.md b/.claude/commands/preflight.md
new file mode 100644
index 0000000000..b54556a7f1
--- /dev/null
+++ b/.claude/commands/preflight.md
@@ -0,0 +1,30 @@
+---
+description: Run the pre-push checklist — lint, types, relevant tests, and a Conventional-Commit sanity check
+allowed-tools: Bash(yarn lint:changed), Bash(yarn lint:fix), Bash(yarn type-check), Bash(yarn type-check:*), Bash(yarn jest:*), Bash(git status:*), Bash(git diff:*), Bash(git log:*)
+---
+
+Run the InstantSearch pre-push checks against the **current changes** and report a concise pass/fail summary. Don't fix anything silently — surface failures and propose fixes.
+
+## Steps
+
+1. **Scope the change.** `git status` + `git diff --name-only` (and vs. the base branch if on a feature branch) to see which packages/files are touched.
+
+2. **Lint the changed files:** `yarn lint:changed`. If it fails, show the violations; offer `yarn lint:fix` for auto-fixable ones (note that oxlint bans `for-in`/`for-of`/`async` and implicit `any` in library code — those need manual fixes).
+
+3. **Type-check:** `yarn type-check`. If any touched code interacts with the legacy algoliasearch versions, also run `yarn type-check:v3` / `yarn type-check:v4`.
+
+4. **Run the relevant tests** — not the whole suite. Map changed files to their `yarn jest <path>` (e.g. a connector → `yarn jest packages/instantsearch.js/src/connectors/<name>`; a React widget → its `__tests__` path). If a connector's cross-flavor behavior changed, include the matching `tests/common/` path.
+
+5. **Conventional-Commit sanity check.** Look at staged changes / recent commits and confirm the message fits `type(scope): description` (scope = widget/connector or topic like `deps`/`ci`). Flag if it doesn't; suggest a corrected message. Reference issues with `fix #1234` in the body when applicable.
+
+## Output
+
+Report a short checklist:
+- ✅/❌ lint:changed
+- ✅/❌ type-check (+ v3/v4 if run)
+- ✅/❌ tests (list the paths run)
+- ✅/❌ commit message
+
+For any ❌, show the failing output and the smallest fix. Don't run the full `yarn test` or `yarn build` unless asked — this is the fast pre-push loop.
+
+Run the checks directly. If a check fails, fix it in the package that owns the failing file before re-running.
diff --git a/AGENTS.md b/AGENTS.md
new file mode 120000
index 0000000000..681311eb9c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1 @@
+CLAUDE.md
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000000..a16d60a9d7
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,80 @@
+# InstantSearch monorepo
+
+Search UI libraries for Algolia across three flavors (vanilla JS, React, Vue), sharing one connector + UI-component core. Yarn 1 workspaces + Lerna (independent versioning).
+
+## Repo map
+
+| Package | What it is |
+|---|---|
+| `packages/instantsearch.js` | **Core.** Vanilla JS library. **All connectors live here** (`src/connectors/`) and are shared by every flavor. |
+| `packages/react-instantsearch-core` | Headless React: hooks (`useSearchBox`, …) that wrap connectors. Framework-agnostic (web/RN). |
+| `packages/react-instantsearch` | React DOM widgets = hooks + UI from `instantsearch-ui-components`. |
+| `packages/vue-instantsearch` | Vue 2/3 components wrapping connectors. |
+| `packages/instantsearch-ui-components` | **Shared UI layer.** Framework-agnostic widget markup + `ais-*` classes via factory components (`create<Name>Component({ createElement, Fragment })`); reused by React directly, Vue via `renderCompat`, JS via the Preact renderer. Newer widgets get their layout here; older ones still define it in `instantsearch.js/src/components/`. |
+| `packages/algoliasearch-helper` | Low-level search-parameter/state manager underneath connectors. Mature, separately-versioned; **rarely the place for a change** — fix the connector instead. See its `CLAUDE.md`. |
+| `packages/instantsearch.css` | Default themes. |
+| `packages/react-instantsearch-nextjs` / `-router-nextjs` | Next.js App Router / Pages Router integrations. |
+| `packages/create-instantsearch-app`, `instantsearch-cli`, `instantsearch-codemods` | Scaffolding / CLI / migration tooling. |
+
+Architecture in one line: **connector (logic, in instantsearch.js) → flavor wrapper (JS widget / React hook+component / Vue component) → shared UI components**. Change behavior in the connector; change markup in the UI layer.
+
+## Where work goes (per layer)
+
+Because behavior lives in the connector and the flavors only wrap it, most changes have a natural home — and the per-package `CLAUDE.md` files carry each layer's conventions:
+
+| Work in… | Package |
+|---|---|
+| Connectors, JS widgets, runtime (`src/lib`), legacy Preact components (`src/components`), types | `packages/instantsearch.js` |
+| Shared framework-agnostic markup / `ais-*` classes | `packages/instantsearch-ui-components` |
+| React widgets/hooks + Next.js integrations | `react-instantsearch` / `react-instantsearch-core` / `*-nextjs` |
+| Vue components (Vue 2 **and** 3) | `vue-instantsearch` |
+
+For a **cross-flavor change**, settle the contract in the connector first, then update the React and Vue wrappers, then the common tests. If the change is to **shared markup/layout** (not behavior), it lives in `instantsearch-ui-components` and the flavors consume the result — a class/structure change there ripples to all flavors and `instantsearch.css` at once.
+
+**Adding or surfacing a connector option is always cross-flavor work** — settle the contract in the connector first, then thread it through React **and** Vue, then add/extend common tests. Don't wire one flavor and stop. The **`/expose-option <connector> <option>`** command walks this recipe; **`/preflight`** runs the pre-push lint/types/tests/commit check; the `/port-widget` skill adds a brand-new widget across flavors.
+
+## Commands
+
+Node `20.19.0` (`.nvmrc`). Use Yarn (v1).
+
+```bash
+# Build
+yarn build                      # all packages (lerna)
+yarn workspace <pkg> build      # single package, e.g. yarn workspace instantsearch.js build
+
+# Unit tests (Jest, jsdom)
+yarn jest <path-or-pattern>     # fastest loop: run one file/pattern at root
+yarn jest packages/<pkg>        # one package's suite (flavor pkgs have no `test` script — scope jest by path)
+yarn jest common-widgets        # shared cross-flavor widget suites (JS+React+Vue); -connectors for connectors
+yarn jest common-widgets -t "Chat widget common tests"   # scope to one widget (label = "<Widget> widget common tests")
+yarn test                       # everything (slow)
+
+# Lint (oxlint) + format (prettier) + types
+yarn lint:changed               # lint only changed files — use this while iterating
+yarn lint:fix                   # auto-fix
+yarn type-check                 # tsc + per-package (also :v3 / :v4 for legacy algoliasearch)
+
+# E2E — see .claude/rules/e2e.md (Playwright). Examples must be built first:
+yarn website:examples && E2E_FLAVOR=react E2E_BROWSER=chromium yarn test:e2e
+```
+
+## Conventions
+
+- **TypeScript strict.** No implicit any; unused vars/params error. Avoid `for-in`/`for-of` and `async` in library code (oxlint enforces).
+- **Tests** co-locate in `__tests__/` next to source — Jest picks up *any* file under `__tests__/` (the default `testMatch`), so some legacy tests are plain `*.js`; name new ones `*.test.ts(x)`. Prefer focused assertions; use inline snapshots sparingly (initial render only). Mocks/helpers come from `@instantsearch/mocks` and `@instantsearch/testutils`.
+- **Cross-flavor tests** live in `tests/common/{widgets,connectors}/<name>/` and each flavor registers them in its `common-widgets.test.*` / `common-connectors.test.*`. Run with `yarn jest common-widgets` (all three flavors) and scope to one widget via `-t "<Widget> widget common tests"`. This is the primary test surface for newer widgets like Autocomplete and Chat. See `tests/common/README.md`.
+- **Commits: Conventional Commits** — `type(scope): description`, scope = widget/connector or topic (`deps`, `ci`). e.g. `fix(searchbox): increase magnifying glass size`, `feat(hits): add custom rendering`. Reference issues with `fix #1234` in the body.
+- **Branches:** target `master`; `vX` branches are critical-fix-only. Branch names: `fix/<issue>`, `feat/<name>`.
+- **Releases** are automated via Ship.js (`yarn release`); changelogs are generated from commits — don't hand-edit them.
+
+## Keep these docs alive
+
+If you discover something durable and non-obvious while working — a gotcha that cost you a debugging detour, a convention, a non-obvious file location, a cross-flavor constraint — **propose** adding it to the right doc (package `CLAUDE.md` if package-specific, this file if repo-wide, `.claude/rules/e2e.md` for e2e). Surface the proposed edit for the user to approve rather than editing silently. Bar: it must generalize beyond the current task (same bar as a good code comment) and not already be documented.
+
+## Reference docs (read before relevant work — don't duplicate here)
+
+- `CONTRIBUTING.md` — full process, commit/branch rules, package-import flow.
+- `.claude/rules/e2e.md` — E2E testing (Playwright helpers, flavors, debugging).
+- `.claude/skills/port-widget/` — adding a widget across all three flavors (the `/port-widget` skill).
+- `tests/common/README.md` — shared cross-flavor test architecture.
+- Per-package `CLAUDE.md` in `instantsearch.js`, `instantsearch-ui-components`, `react-instantsearch`, `vue-instantsearch` for package-specific layout.
diff --git a/packages/algoliasearch-helper/CLAUDE.md b/packages/algoliasearch-helper/CLAUDE.md
new file mode 100644
index 0000000000..51d2ce4712
--- /dev/null
+++ b/packages/algoliasearch-helper/CLAUDE.md
@@ -0,0 +1,23 @@
+# algoliasearch-helper
+
+The **low-level search-state manager** that sits *underneath* InstantSearch connectors. It's a separately-published, long-stable npm package (`algoliasearch-helper`, own semver — currently 3.x) that wraps the `algoliasearch` JS client with a higher-level, stateful API: it tracks search parameters, builds the actual Algolia queries, parses responses, and emits events. Every connector in `instantsearch.js` reads and writes this helper's state — but the connector is the layer you change, not this one.
+
+> **⚠️ Rarely the right place for a change/fix/update.** This package is mature and broadly depended on — InstantSearch (all flavors) plus other Algolia front-end libraries build on it. Almost all widget/connector behavior is implemented *on top of* the helper, not in it. Touch it **only** for a genuine state-manager or response-parsing bug, or to add a real new search-parameter primitive. Any change here is a **public-API, independently-versioned** change with a blast radius far beyond this repo — flag it explicitly and prefer fixing the connector instead.
+
+## What's in it
+
+Entry: `algoliasearchHelper(client, index, opts)` → an `AlgoliaSearchHelper` (an `EventEmitter`). Core pieces under `src/`:
+
+- **`SearchParameters/`** — the **immutable** query state (query, `facets`/`disjunctiveFacets`/`hierarchicalFacets`, numeric & tag refinements, `page`, etc.). Setters return a *new* instance; never mutate in place. This is the object connectors mutate via `getWidgetSearchParameters`.
+- **`SearchResults/`** — parses the raw Algolia response into a richer structure: facet values, `facets_stats`, and hierarchical facet trees (`generate-hierarchical-tree.js`).
+- **`requestBuilder.js`** — turns `SearchParameters` into the actual query payload(s); notably **splits disjunctive faceting into multiple queries**.
+- **`DerivedHelper/`** — sub-requests derived from a main helper (federated / multi-index search); this is what powers the `index` widget.
+- **`RecommendParameters/` + `RecommendResults/`** — the equivalent state/results pair for the Recommend API.
+- **`functions/`** — small internal lodash-style utilities (`merge`, `omit`, `orderBy`, …).
+
+Events emitted by the helper (what InstantSearch's lifecycle listens to): `change`, `search`, `result`, `error`, `fetch`, `searchOnce`, `searchForFacetValues`, `searchQueueEmpty`, `recommendQueueEmpty`.
+
+## Conventions that differ from the rest of the monorepo
+
+- **Plain CommonJS JavaScript**, not the TS-strict source the other packages use. Public types are **hand-written** in `index.d.ts` — update them by hand if you change the surface.
+- Has its own **`README.md` + `CHANGELOG.md`** (don't fold into the monorepo's). Build is Rollup (`yarn workspace algoliasearch-helper build`); tests run via its own `scripts/test.sh` (`yarn workspace algoliasearch-helper test`).
diff --git a/packages/instantsearch-ui-components/CLAUDE.md b/packages/instantsearch-ui-components/CLAUDE.md
new file mode 100644
index 0000000000..98c6687747
--- /dev/null
+++ b/packages/instantsearch-ui-components/CLAUDE.md
@@ -0,0 +1,46 @@
+# instantsearch-ui-components
+
+The **framework-agnostic UI layer** — the shared markup/layout for widgets, reused by every flavor. This is where a widget's DOM structure and `ais-*` CSS classes live for **newer** widgets. (Older widgets still define their layout per-flavor; see "Old vs new" below.)
+
+## The factory + renderer pattern
+
+Components are **not** React/Preact/Vue components directly. Each is a factory that takes a renderer and returns a component:
+
+```tsx
+/** @jsx createElement */
+import { cx } from '../lib';
+import type { Renderer, ComponentProps } from '../types';
+
+export function createHitsComponent({ createElement, Fragment }: Renderer) {
+  return function Hits(props) {
+    return <div className={cx('ais-Hits', props.classNames.root)}>…</div>;
+  };
+}
+```
+
+- **`Renderer` = `{ createElement, Fragment }`** is *injected* by the consumer (`src/types/Renderer.ts`). Defaults are Preact's, but React passes `react`'s `createElement` and Vue passes its own `h` (wired up via the `renderCompat` helper in `vue-instantsearch`). **Never import `preact`/`react`/`vue` directly** — go through the injected renderer. The `/** @jsx createElement */` pragma at the top of each file is what wires JSX to the injected function.
+- Class names go through **`cx`** (`src/lib/cx.ts`) and follow the `ais-<Widget>-<element>` contract that `instantsearch.css` themes — treat those class names as a public API.
+- Props are typed with `ComponentProps<'div'>`-style helpers from `src/types`; expose a `classNames` partial so consumers can extend styling.
+
+## Layout
+
+- `src/components/<Name>.tsx` — a `create<Name>Component` factory. Exported from `src/components/index.ts` → `src/index.ts`.
+- Grouped families: `src/components/autocomplete/`, `src/components/chat/`, `src/components/recommend-shared/` (+ the recommend widgets `RelatedProducts`, `FrequentlyBoughtTogether`, `LookingSimilar`, `TrendingItems`, `TrendingFacets`).
+- `src/lib/` — `cx`, `stickToBottom`, shared `utils`. `src/types/` — `Renderer`, `ComponentProps`, `Hooks`, `Recommend`, `shared`.
+- Runtime deps are minimal on purpose (`markdown-to-jsx`, `@swc/helpers`); **no framework as a dependency**.
+
+## Old vs new (important)
+
+- **New widgets:** layout lives here and is consumed by all flavors — React via `import { create<Name>Component } from 'instantsearch-ui-components'`, Vue via the `renderCompat` helper, JS via the Preact renderer.
+- **Older widgets:** layout was defined per-flavor — JS in `packages/instantsearch.js/src/components/` (Preact), React in `packages/react-instantsearch/src/ui/`. The migration direction is to consolidate that markup here; some JS-package components are now thin wrappers that import from this package.
+- When adding/changing **shared** layout, do it here. When touching a widget that still defines its own markup, check whether it should be migrated rather than forked.
+
+## Working here
+
+```bash
+yarn workspace instantsearch-ui-components build       # tsc/rollup + build:types
+yarn jest packages/instantsearch-ui-components/src/components/__tests__/<Name>   # from repo root
+```
+
+- Tests are co-located in `src/components/__tests__/`. Test the component by passing a concrete renderer (e.g. Preact's) — assert rendered structure and class names, not implementation.
+- A markup or class-name change here **ripples to React, Vue, and JS at once** — verify consumers and keep the `ais-*` contract stable (a class rename is a breaking change that also touches `instantsearch.css`).
diff --git a/packages/instantsearch.js/CLAUDE.md b/packages/instantsearch.js/CLAUDE.md
new file mode 100644
index 0000000000..4b27327d7b
--- /dev/null
+++ b/packages/instantsearch.js/CLAUDE.md
@@ -0,0 +1,22 @@
+# instantsearch.js (core / vanilla JS)
+
+The core package. **Every connector lives here and is consumed by all flavors** — React hooks and Vue components wrap these. A behavior change usually belongs in a connector here, not in a flavor package.
+
+## Layout
+
+- `src/connectors/<name>/connect<Pascal>.ts` — framework-agnostic logic. Signature: `connect<Widget>(renderFn, unmountFn)` returns a widget factory. Owns state, lifecycle, and search-param mutations. Exported from `src/connectors/index.ts`.
+- `src/widgets/<name>/<name>.tsx` — vanilla JS widget = connector + default template/rendering. Exported from `src/widgets/index.ts`.
+- `src/components/` — the **JS flavor's Preact components** (the widgets' markup). This is the *legacy* home for widget layout; newer widgets pull their layout from the shared `instantsearch-ui-components` package instead, and some components here are now thin wrappers that import from it. Add **new shared** markup to `instantsearch-ui-components`, not here.
+- `src/lib/` — the InstantSearch runtime: lifecycle orchestration, routing, helper integration.
+- `src/types/` — public type definitions.
+
+## Working here
+
+```bash
+yarn workspace instantsearch.js build      # rollup → esm + cjs + umd + .d.ts
+yarn jest packages/instantsearch.js/src/connectors/<name>   # run one connector's tests (from repo root)
+```
+
+- Connectors return a typed render state — don't return untyped state (oxlint rule).
+- A new widget that only varies presentation should **reuse an existing connector** (e.g. `menuSelect` reuses `connectMenu`) and set a distinct `$$widgetType`; don't fork the connector.
+- Cross-flavor behavior is covered by `tests/common/connectors/<name>/`; flavor-agnostic logic tests go there, JS-specific ones stay in `__tests__/`.
diff --git a/packages/react-instantsearch-nextjs/CLAUDE.md b/packages/react-instantsearch-nextjs/CLAUDE.md
new file mode 100644
index 0000000000..916b1f2004
--- /dev/null
+++ b/packages/react-instantsearch-nextjs/CLAUDE.md
@@ -0,0 +1,25 @@
+# react-instantsearch-nextjs (Next.js App Router)
+
+SSR integration for the **App Router** (RSC + streaming). Peer-deps `next` + `react-instantsearch` — it **composes** react-instantsearch, never reimplements search. This is the non-trivial Next.js package; the subtle part is server-render + hydration.
+
+## Public surface
+
+- `InstantSearchNext` (`src/InstantSearchNext.tsx`) — the entry component, a drop-in for `<InstantSearch>` inside the App Router. It does SSR **for you**, so you don't hand-wire the plain-react-instantsearch `getServerState` + `InstantSearchSSRProvider` dance. Props: `routing` (boolean | object) and an optional `instance`.
+
+## How the SSR machinery fits together
+
+- `InitializePromise.ts` + `TriggerSearch.ts` — run the search **during the server (RSC) render** so results are available before HTML is sent.
+- `createInsertHTML.tsx` + `htmlEscape.ts` — serialize that initial server state and **inject it into the streamed HTML** for hydration. `htmlEscape` is a **safety boundary** (escapes the injected payload so it can't break out of the script/HTML context) — don't bypass it when touching the insert path.
+- `useInstantSearchRouting.ts`, `useNextHeaders.tsx`, `useDynamicRouteWarning.ts` — routing via `next/navigation` (not `next/router`). Dynamic routes are warned about (`useDynamicRouteWarning`) because they interact poorly with InstantSearch URL sync.
+
+## Working here
+
+```bash
+yarn workspace react-instantsearch-nextjs build
+yarn jest packages/react-instantsearch-nextjs/src/__tests__/<name>   # unit tests, from repo root
+yarn workspace react-instantsearch-nextjs test:e2e                   # Playwright (App Router)
+```
+
+- **Hydration is the failure mode.** A change to the initialize/trigger/insert path can produce server/client markup mismatch — verify there's no hydration warning and that the first paint already reflects server results.
+- e2e lives in `__tests__/e2e/` (Playwright). Browser back/forward on dynamic App Router routes needs file-level `slowMo` in headless mode — see `.claude/rules/e2e.md`.
+- Treat SSR/RSC/hydration work here as **reasoning-heavy** — it's the one corner of the React surface that isn't bounded widget wiring.
diff --git a/packages/react-instantsearch-router-nextjs/CLAUDE.md b/packages/react-instantsearch-router-nextjs/CLAUDE.md
new file mode 100644
index 0000000000..3f35daceb4
--- /dev/null
+++ b/packages/react-instantsearch-router-nextjs/CLAUDE.md
@@ -0,0 +1,24 @@
+# react-instantsearch-router-nextjs (Next.js Pages Router)
+
+A **thin routing adapter** for the **Pages Router** — not a full SSR layer. It wraps InstantSearch's history router so URL sync plays well with `next/router`. The actual SSR is the standard react-instantsearch `getServerState` + `InstantSearchSSRProvider` pattern in your app, **not** here.
+
+## Public surface
+
+- `createInstantSearchRouterNext({ singletonRouter, serverUrl?, ... })` (`src/index.ts`) — returns a `Router` you pass to `<InstantSearch routing={{ router }}>`. Tagged `$$type: 'ais.nextjs'`.
+
+## What it actually does (and why)
+
+- Builds on `instantsearch.js/es/lib/routers/history`; on the server (`typeof window === 'undefined'`) it returns a simpler router reading from `serverUrl`.
+- `push` uses **`shallow: true`** so refinements don't re-run `getServerSideProps`, and strips the locale (`stripLocaleFromUrl`) to avoid Next i18n path errors.
+- Hooks `routeChangeComplete` + `beforePopState` to trigger SSR **only** on real page changes (back/forward to a different page), not on every refinement. `beforePopState`/`beforeStart`/`beforeDispose`/`routerOptions` let consumers compose their own logic.
+- `stripLocaleFromUrl` (`src/utils/`) handles i18n locale prefixes in the URL.
+
+## Working here
+
+```bash
+yarn workspace react-instantsearch-router-nextjs build
+yarn workspace react-instantsearch-router-nextjs test:e2e   # Playwright (Pages Router)
+```
+
+- Surface is small — most behavior lives in the shared history router (`instantsearch.js`) and react-instantsearch SSR core. Keep this package to the **Next-specific routing glue**.
+- The tricky cases are i18n/locale paths and back/forward navigation deciding whether to re-SSR. e2e in `__tests__/e2e/` (Playwright); see `.claude/rules/e2e.md`.
diff --git a/packages/react-instantsearch/CLAUDE.md b/packages/react-instantsearch/CLAUDE.md
new file mode 100644
index 0000000000..4bd57f202b
--- /dev/null
+++ b/packages/react-instantsearch/CLAUDE.md
@@ -0,0 +1,23 @@
+# react-instantsearch
+
+React DOM bindings. This package = **hooks (from `react-instantsearch-core`) + UI markup (from `instantsearch-ui-components`)**. The search logic itself is the connector in `instantsearch.js`; don't reimplement it here.
+
+## Layer split (where each thing goes)
+
+- `packages/react-instantsearch-core/src/connectors/use<Pascal>.ts` — the **hook** that wraps the `instantsearch.js` connector. Headless, no DOM. Exported from that package's `src/index.ts`.
+- `packages/react-instantsearch/src/widgets/<Pascal>.tsx` — the **component**: calls the hook, renders UI. Exported from `src/widgets/index.ts`.
+- `packages/react-instantsearch/src/ui/<Pascal>.tsx` — local presentational component, only when the markup isn't already in the shared `instantsearch-ui-components` package.
+
+So adding/changing a React widget often touches `react-instantsearch-core` (hook) **and** `react-instantsearch` (component) — keep them in sync.
+
+## Working here
+
+```bash
+yarn workspace react-instantsearch build
+yarn workspace react-instantsearch-core build
+yarn jest packages/react-instantsearch/src/widgets/__tests__/<Pascal>   # from repo root
+```
+
+- Uses React 19 / `@testing-library/react` for tests, co-located in `__tests__/`.
+- Cross-flavor behavior lives in `tests/common/widgets/<name>/`; register it in this package's `common-widgets.test.*`.
+- Prefer shared UI from `instantsearch-ui-components` (consume `create<Name>Component` with React's `createElement`) over new local `ui/` components. **Creating or changing a shared component is the `instantsearch-ui-components` package's job** — do that there, then consume it here. Add a local `src/ui/` component only when the markup truly isn't shareable.
diff --git a/packages/vue-instantsearch/CLAUDE.md b/packages/vue-instantsearch/CLAUDE.md
new file mode 100644
index 0000000000..f6be0d6c9d
--- /dev/null
+++ b/packages/vue-instantsearch/CLAUDE.md
@@ -0,0 +1,19 @@
+# vue-instantsearch
+
+Vue 2 **and** Vue 3 bindings (single source, built for both). Components wrap the `instantsearch.js` connectors — the logic isn't reimplemented here.
+
+## Layout
+
+- `src/components/<Pascal>.vue` (SFC) or `.js` (render function) — the component wrapping a connector. Exported from `src/widgets.js`.
+- `src/mixins/` — shared connector-wiring logic reused across components.
+- To reuse shared markup, import the `create<Name>Component` factory from `instantsearch-ui-components` and render it inside a **`renderCompat`** render function, passing Vue's `h` as `createElement` — e.g. `render: renderCompat((h) => h(createHitsComponent({ createElement: h }), { … }))` (see `src/components/Hits.js`). `renderCompat` (`src/util/vue-compat/`) is the Vue 2/3 render-fn shim. **Creating or changing the shared component itself is the `instantsearch-ui-components` package's job** — do that there, then consume the factory here.
+
+## Working here
+
+```bash
+yarn workspace vue-instantsearch build
+yarn jest packages/vue-instantsearch/src/components/__tests__/<Pascal>   # from repo root
+```
+
+- Vue 2/3 dual support: run `./scripts/prepare-vue3.js` (root `yarn prepare-vue3`) when switching the working tree to Vue 3. Don't assume one Vue version — changes must work for both.
+- Cross-flavor behavior lives in `tests/common/widgets/<name>/`; register it in this package's `common-widgets.test.*`.