diff --git a/README.md b/README.md
index 15b5d15..a6f9f93 100644
--- a/README.md
+++ b/README.md
@@ -15,9 +15,11 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/hookli"><img src="https://img.shields.io/npm/v/hookli?style=flat-square&color=0A0D12" alt="npm version" /></a>
+  <a href="https://hookli.vercel.app/docs"><img src="https://img.shields.io/badge/docs-hookli.vercel.app-61DAFB?style=flat-square" alt="Documentation" /></a>
+  <a href="https://github.com/saifmohamedsv/hookli/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/saifmohamedsv/hookli/ci.yml?branch=main&style=flat-square&color=0A0D12&label=CI" alt="CI build status" /></a>
   <a href="https://www.npmjs.com/package/hookli"><img src="https://img.shields.io/npm/dm/hookli?style=flat-square&color=61DAFB&label=downloads%2Fmonth" alt="npm downloads per month" /></a>
   <a href="https://www.npmjs.com/package/hookli"><img src="https://img.shields.io/npm/dt/hookli?style=flat-square&color=0A0D12&label=total%20downloads" alt="total npm downloads" /></a>
-  <a href="https://bundlephobia.com/package/hookli"><img src="https://img.shields.io/bundlephobia/minzip/hookli?style=flat-square&color=61DAFB" alt="minzipped size" /></a>
+  <a href="https://www.npmjs.com/package/hookli"><img src="https://img.shields.io/npm/types/hookli?style=flat-square&color=61DAFB" alt="TypeScript types included" /></a>
   <a href="https://github.com/saifmohamedsv/hookli"><img src="https://img.shields.io/github/stars/saifmohamedsv/hookli?style=flat-square&color=0A0D12" alt="GitHub stars" /></a>
   <a href="https://github.com/sponsors/saifmohamedsv"><img src="https://img.shields.io/badge/sponsor-61DAFB?style=flat-square&logo=githubsponsors&logoColor=0A0D12" alt="Sponsor" /></a>
   <img src="https://img.shields.io/npm/l/hookli?style=flat-square&color=354355" alt="license" />
@@ -86,6 +88,10 @@ function Component() {
 
 > 📚 Full docs with a **page per hook** and **live demos**: <https://hookli.vercel.app/docs>
 
+<!-- HOOKS:START — generated from hooks.manifest.json (run `node scripts/gen-readme.mjs`); do not edit by hand -->
+
+### State (19)
+
 - **[`useToggle`](https://hookli.vercel.app/docs/use-toggle)** — Boolean state with toggle and explicit set.
 - **[`useForm`](https://hookli.vercel.app/docs/use-form)** — Controlled form state with one change handler.
 - **[`useLocalStorage`](https://hookli.vercel.app/docs/use-local-storage)** — State persisted to localStorage.
@@ -99,6 +105,15 @@ function Component() {
 - **[`useStep`](https://hookli.vercel.app/docs/use-step)** — 1-indexed step counter for wizards and steppers.
 - **[`useCountdown`](https://hookli.vercel.app/docs/use-countdown)** — Self-stopping countdown or count-up timer.
 - **[`useMap`](https://hookli.vercel.app/docs/use-map)** — Manage a Map as immutable React state.
+- **[`usePrevious`](https://hookli.vercel.app/docs/use-previous)** — Track a value from the previous render.
+- **[`useList`](https://hookli.vercel.app/docs/use-list)** — Array state with push, insert, update, remove, and clear helpers.
+- **[`useSet`](https://hookli.vercel.app/docs/use-set)** — Set state with add, remove, toggle, has, and clear helpers.
+- **[`useQueue`](https://hookli.vercel.app/docs/use-queue)** — FIFO queue state with add, remove, clear, and first/last/size.
+- **[`useDefault`](https://hookli.vercel.app/docs/use-default)** — useState that falls back to a default when the value is nullish.
+- **[`useRafState`](https://hookli.vercel.app/docs/use-raf-state)** — useState whose updates are batched to the next animation frame.
+
+### Effects (16)
+
 - **[`useDebounce`](https://hookli.vercel.app/docs/use-debounce)** — Debounces a changing value.
 - **[`useDebounceValue`](https://hookli.vercel.app/docs/use-debounce-value)** — State whose debounced copy updates after a pause.
 - **[`useDebounceCallback`](https://hookli.vercel.app/docs/use-debounce-callback)** — Debounces a callback, with cancel, flush and isPending.
@@ -110,6 +125,14 @@ function Component() {
 - **[`useIsClient`](https://hookli.vercel.app/docs/use-is-client)** — Reports false on the server and true after hydration.
 - **[`useIsMounted`](https://hookli.vercel.app/docs/use-is-mounted)** — A stable getter for whether the component is still mounted.
 - **[`useDocumentTitle`](https://hookli.vercel.app/docs/use-document-title)** — Keeps document.title in sync with a value, SSR-safe.
+- **[`useThrottle`](https://hookli.vercel.app/docs/use-throttle)** — Throttle a fast-changing value to at most one update per interval.
+- **[`useUpdateEffect`](https://hookli.vercel.app/docs/use-update-effect)** — A useEffect that skips the initial mount and runs only on updates.
+- **[`useEffectOnce`](https://hookli.vercel.app/docs/use-effect-once)** — Run an effect exactly once, on mount.
+- **[`usePageVisibility`](https://hookli.vercel.app/docs/use-page-visibility)** — Track whether the page/tab is currently visible.
+- **[`useDeepCompareEffect`](https://hookli.vercel.app/docs/use-deep-compare-effect)** — useEffect that compares dependencies by deep structural equality.
+
+### DOM (22)
+
 - **[`useEventListener`](https://hookli.vercel.app/docs/use-event-listener)** — Subscribe to a window, document or element event with cleanup.
 - **[`useClickOutside`](https://hookli.vercel.app/docs/use-click-outside)** — Runs a callback on outside click.
 - **[`useMousePosition`](https://hookli.vercel.app/docs/use-mouse-position)** — Cursor coordinates within an element.
@@ -125,33 +148,27 @@ function Component() {
 - **[`useWindowSize`](https://hookli.vercel.app/docs/use-window-size)** — Tracks the viewport's { width, height }, updated on resize.
 - **[`useCopyToClipboard`](https://hookli.vercel.app/docs/use-copy-to-clipboard)** — Copy text to the clipboard, tracking the last copied value.
 - **[`useScript`](https://hookli.vercel.app/docs/use-script)** — Load an external script and report its load status.
-- **[`useFetch`](https://hookli.vercel.app/docs/use-fetch)** — Declarative fetch with loading and error status.
-- **[`useGeoLocation`](https://hookli.vercel.app/docs/use-geo-location)** — Browser geolocation state.
-- **[`usePrevious`](https://hookli.vercel.app/docs/use-previous)** — Track a value from the previous render.
-- **[`useList`](https://hookli.vercel.app/docs/use-list)** — Array state with push, insert, update, remove, and clear helpers.
-- **[`useSet`](https://hookli.vercel.app/docs/use-set)** — Set state with add, remove, toggle, has, and clear helpers.
-- **[`useThrottle`](https://hookli.vercel.app/docs/use-throttle)** — Throttle a fast-changing value to at most one update per interval.
-- **[`useUpdateEffect`](https://hookli.vercel.app/docs/use-update-effect)** — A useEffect that skips the initial mount and runs only on updates.
-- **[`useEffectOnce`](https://hookli.vercel.app/docs/use-effect-once)** — Run an effect exactly once, on mount.
 - **[`useKeyPress`](https://hookli.vercel.app/docs/use-key-press)** — Track whether a specific key is currently held down.
 - **[`useWindowScroll`](https://hookli.vercel.app/docs/use-window-scroll)** — Track the window scroll position reactively.
-- **[`useAsync`](https://hookli.vercel.app/docs/use-async)** — Run an async function and track its loading, error, and value state.
-- **[`useMutation`](https://hookli.vercel.app/docs/use-mutation)** — Run an async write action on demand and track status, data, and error.
-- **[`usePagination`](https://hookli.vercel.app/docs/use-pagination)** — Page, page size, total pages, navigation helpers, and the current item range.
-- **[`useNetworkState`](https://hookli.vercel.app/docs/use-network-state)** — Track online/offline status and connection details.
-- **[`usePageVisibility`](https://hookli.vercel.app/docs/use-page-visibility)** — Track whether the page/tab is currently visible.
 - **[`useIdle`](https://hookli.vercel.app/docs/use-idle)** — Detect user inactivity after a configurable threshold.
-- **[`useQueue`](https://hookli.vercel.app/docs/use-queue)** — FIFO queue state with add, remove, clear, and first/last/size.
-- **[`useDefault`](https://hookli.vercel.app/docs/use-default)** — useState that falls back to a default when the value is nullish.
-- **[`useRafState`](https://hookli.vercel.app/docs/use-raf-state)** — useState whose updates are batched to the next animation frame.
-- **[`useDeepCompareEffect`](https://hookli.vercel.app/docs/use-deep-compare-effect)** — useEffect that compares dependencies by deep structural equality.
 - **[`useTextSelection`](https://hookli.vercel.app/docs/use-text-selection)** — Track the text the user has currently selected on the page.
 - **[`useLongPress`](https://hookli.vercel.app/docs/use-long-press)** — Detect a long press (mouse or touch) via spreadable handlers.
 - **[`useHotkeys`](https://hookli.vercel.app/docs/use-hotkeys)** — Bind a keyboard shortcut combo (e.g. ctrl+k) to a callback.
 - **[`useFullscreen`](https://hookli.vercel.app/docs/use-fullscreen)** — Control the Fullscreen API for an element and track its state.
+
+### Data (8)
+
+- **[`useFetch`](https://hookli.vercel.app/docs/use-fetch)** — Declarative fetch with loading and error status.
+- **[`useGeoLocation`](https://hookli.vercel.app/docs/use-geo-location)** — Browser geolocation state.
+- **[`useAsync`](https://hookli.vercel.app/docs/use-async)** — Run an async function and track its loading, error, and value state.
+- **[`useMutation`](https://hookli.vercel.app/docs/use-mutation)** — Run an async write action on demand and track status, data, and error.
+- **[`usePagination`](https://hookli.vercel.app/docs/use-pagination)** — Page, page size, total pages, navigation helpers, and the current item range.
+- **[`useNetworkState`](https://hookli.vercel.app/docs/use-network-state)** — Track online/offline status and connection details.
 - **[`useBattery`](https://hookli.vercel.app/docs/use-battery)** — Read device battery level and charging state (where supported).
 - **[`usePermission`](https://hookli.vercel.app/docs/use-permission)** — Query a Permissions API permission and track its state.
 
+<!-- HOOKS:END -->
+
 ## 🧪 TypeScript
 
 Every hook ships its own declarations — no `@types/hookli` needed. Data hooks are generic,
diff --git a/packages/hookli/README.md b/packages/hookli/README.md
index 383f534..2fc5ae8 100644
--- a/packages/hookli/README.md
+++ b/packages/hookli/README.md
@@ -13,9 +13,11 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/hookli"><img src="https://img.shields.io/npm/v/hookli?style=flat-square&color=0A0D12" alt="npm version" /></a>
+  <a href="https://hookli.vercel.app/docs"><img src="https://img.shields.io/badge/docs-hookli.vercel.app-61DAFB?style=flat-square" alt="Documentation" /></a>
+  <a href="https://github.com/saifmohamedsv/hookli/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/saifmohamedsv/hookli/ci.yml?branch=main&style=flat-square&color=0A0D12&label=CI" alt="CI build status" /></a>
   <a href="https://www.npmjs.com/package/hookli"><img src="https://img.shields.io/npm/dm/hookli?style=flat-square&color=61DAFB&label=downloads%2Fmonth" alt="npm downloads per month" /></a>
   <a href="https://www.npmjs.com/package/hookli"><img src="https://img.shields.io/npm/dt/hookli?style=flat-square&color=0A0D12&label=total%20downloads" alt="total npm downloads" /></a>
-  <a href="https://bundlephobia.com/package/hookli"><img src="https://img.shields.io/bundlephobia/minzip/hookli?style=flat-square&color=61DAFB" alt="minzipped size" /></a>
+  <a href="https://www.npmjs.com/package/hookli"><img src="https://img.shields.io/npm/types/hookli?style=flat-square&color=61DAFB" alt="TypeScript types included" /></a>
   <a href="https://github.com/saifmohamedsv/hookli"><img src="https://img.shields.io/github/stars/saifmohamedsv/hookli?style=flat-square&color=0A0D12" alt="GitHub stars" /></a>
   <a href="https://github.com/sponsors/saifmohamedsv"><img src="https://img.shields.io/badge/sponsor-61DAFB?style=flat-square&logo=githubsponsors&logoColor=0A0D12" alt="Sponsor" /></a>
   <img src="https://img.shields.io/npm/l/hookli?style=flat-square&color=354355" alt="license" />
@@ -84,6 +86,10 @@ function Component() {
 
 > 📚 Full docs with a **page per hook** and **live demos**: <https://hookli.vercel.app/docs>
 
+<!-- HOOKS:START — generated from hooks.manifest.json (run `node scripts/gen-readme.mjs`); do not edit by hand -->
+
+### State (19)
+
 - **[`useToggle`](https://hookli.vercel.app/docs/use-toggle)** — Boolean state with toggle and explicit set.
 - **[`useForm`](https://hookli.vercel.app/docs/use-form)** — Controlled form state with one change handler.
 - **[`useLocalStorage`](https://hookli.vercel.app/docs/use-local-storage)** — State persisted to localStorage.
@@ -97,6 +103,15 @@ function Component() {
 - **[`useStep`](https://hookli.vercel.app/docs/use-step)** — 1-indexed step counter for wizards and steppers.
 - **[`useCountdown`](https://hookli.vercel.app/docs/use-countdown)** — Self-stopping countdown or count-up timer.
 - **[`useMap`](https://hookli.vercel.app/docs/use-map)** — Manage a Map as immutable React state.
+- **[`usePrevious`](https://hookli.vercel.app/docs/use-previous)** — Track a value from the previous render.
+- **[`useList`](https://hookli.vercel.app/docs/use-list)** — Array state with push, insert, update, remove, and clear helpers.
+- **[`useSet`](https://hookli.vercel.app/docs/use-set)** — Set state with add, remove, toggle, has, and clear helpers.
+- **[`useQueue`](https://hookli.vercel.app/docs/use-queue)** — FIFO queue state with add, remove, clear, and first/last/size.
+- **[`useDefault`](https://hookli.vercel.app/docs/use-default)** — useState that falls back to a default when the value is nullish.
+- **[`useRafState`](https://hookli.vercel.app/docs/use-raf-state)** — useState whose updates are batched to the next animation frame.
+
+### Effects (16)
+
 - **[`useDebounce`](https://hookli.vercel.app/docs/use-debounce)** — Debounces a changing value.
 - **[`useDebounceValue`](https://hookli.vercel.app/docs/use-debounce-value)** — State whose debounced copy updates after a pause.
 - **[`useDebounceCallback`](https://hookli.vercel.app/docs/use-debounce-callback)** — Debounces a callback, with cancel, flush and isPending.
@@ -108,6 +123,14 @@ function Component() {
 - **[`useIsClient`](https://hookli.vercel.app/docs/use-is-client)** — Reports false on the server and true after hydration.
 - **[`useIsMounted`](https://hookli.vercel.app/docs/use-is-mounted)** — A stable getter for whether the component is still mounted.
 - **[`useDocumentTitle`](https://hookli.vercel.app/docs/use-document-title)** — Keeps document.title in sync with a value, SSR-safe.
+- **[`useThrottle`](https://hookli.vercel.app/docs/use-throttle)** — Throttle a fast-changing value to at most one update per interval.
+- **[`useUpdateEffect`](https://hookli.vercel.app/docs/use-update-effect)** — A useEffect that skips the initial mount and runs only on updates.
+- **[`useEffectOnce`](https://hookli.vercel.app/docs/use-effect-once)** — Run an effect exactly once, on mount.
+- **[`usePageVisibility`](https://hookli.vercel.app/docs/use-page-visibility)** — Track whether the page/tab is currently visible.
+- **[`useDeepCompareEffect`](https://hookli.vercel.app/docs/use-deep-compare-effect)** — useEffect that compares dependencies by deep structural equality.
+
+### DOM (22)
+
 - **[`useEventListener`](https://hookli.vercel.app/docs/use-event-listener)** — Subscribe to a window, document or element event with cleanup.
 - **[`useClickOutside`](https://hookli.vercel.app/docs/use-click-outside)** — Runs a callback on outside click.
 - **[`useMousePosition`](https://hookli.vercel.app/docs/use-mouse-position)** — Cursor coordinates within an element.
@@ -123,33 +146,27 @@ function Component() {
 - **[`useWindowSize`](https://hookli.vercel.app/docs/use-window-size)** — Tracks the viewport's { width, height }, updated on resize.
 - **[`useCopyToClipboard`](https://hookli.vercel.app/docs/use-copy-to-clipboard)** — Copy text to the clipboard, tracking the last copied value.
 - **[`useScript`](https://hookli.vercel.app/docs/use-script)** — Load an external script and report its load status.
-- **[`useFetch`](https://hookli.vercel.app/docs/use-fetch)** — Declarative fetch with loading and error status.
-- **[`useGeoLocation`](https://hookli.vercel.app/docs/use-geo-location)** — Browser geolocation state.
-- **[`usePrevious`](https://hookli.vercel.app/docs/use-previous)** — Track a value from the previous render.
-- **[`useList`](https://hookli.vercel.app/docs/use-list)** — Array state with push, insert, update, remove, and clear helpers.
-- **[`useSet`](https://hookli.vercel.app/docs/use-set)** — Set state with add, remove, toggle, has, and clear helpers.
-- **[`useThrottle`](https://hookli.vercel.app/docs/use-throttle)** — Throttle a fast-changing value to at most one update per interval.
-- **[`useUpdateEffect`](https://hookli.vercel.app/docs/use-update-effect)** — A useEffect that skips the initial mount and runs only on updates.
-- **[`useEffectOnce`](https://hookli.vercel.app/docs/use-effect-once)** — Run an effect exactly once, on mount.
 - **[`useKeyPress`](https://hookli.vercel.app/docs/use-key-press)** — Track whether a specific key is currently held down.
 - **[`useWindowScroll`](https://hookli.vercel.app/docs/use-window-scroll)** — Track the window scroll position reactively.
-- **[`useAsync`](https://hookli.vercel.app/docs/use-async)** — Run an async function and track its loading, error, and value state.
-- **[`useMutation`](https://hookli.vercel.app/docs/use-mutation)** — Run an async write action on demand and track status, data, and error.
-- **[`usePagination`](https://hookli.vercel.app/docs/use-pagination)** — Page, page size, total pages, navigation helpers, and the current item range.
-- **[`useNetworkState`](https://hookli.vercel.app/docs/use-network-state)** — Track online/offline status and connection details.
-- **[`usePageVisibility`](https://hookli.vercel.app/docs/use-page-visibility)** — Track whether the page/tab is currently visible.
 - **[`useIdle`](https://hookli.vercel.app/docs/use-idle)** — Detect user inactivity after a configurable threshold.
-- **[`useQueue`](https://hookli.vercel.app/docs/use-queue)** — FIFO queue state with add, remove, clear, and first/last/size.
-- **[`useDefault`](https://hookli.vercel.app/docs/use-default)** — useState that falls back to a default when the value is nullish.
-- **[`useRafState`](https://hookli.vercel.app/docs/use-raf-state)** — useState whose updates are batched to the next animation frame.
-- **[`useDeepCompareEffect`](https://hookli.vercel.app/docs/use-deep-compare-effect)** — useEffect that compares dependencies by deep structural equality.
 - **[`useTextSelection`](https://hookli.vercel.app/docs/use-text-selection)** — Track the text the user has currently selected on the page.
 - **[`useLongPress`](https://hookli.vercel.app/docs/use-long-press)** — Detect a long press (mouse or touch) via spreadable handlers.
 - **[`useHotkeys`](https://hookli.vercel.app/docs/use-hotkeys)** — Bind a keyboard shortcut combo (e.g. ctrl+k) to a callback.
 - **[`useFullscreen`](https://hookli.vercel.app/docs/use-fullscreen)** — Control the Fullscreen API for an element and track its state.
+
+### Data (8)
+
+- **[`useFetch`](https://hookli.vercel.app/docs/use-fetch)** — Declarative fetch with loading and error status.
+- **[`useGeoLocation`](https://hookli.vercel.app/docs/use-geo-location)** — Browser geolocation state.
+- **[`useAsync`](https://hookli.vercel.app/docs/use-async)** — Run an async function and track its loading, error, and value state.
+- **[`useMutation`](https://hookli.vercel.app/docs/use-mutation)** — Run an async write action on demand and track status, data, and error.
+- **[`usePagination`](https://hookli.vercel.app/docs/use-pagination)** — Page, page size, total pages, navigation helpers, and the current item range.
+- **[`useNetworkState`](https://hookli.vercel.app/docs/use-network-state)** — Track online/offline status and connection details.
 - **[`useBattery`](https://hookli.vercel.app/docs/use-battery)** — Read device battery level and charging state (where supported).
 - **[`usePermission`](https://hookli.vercel.app/docs/use-permission)** — Query a Permissions API permission and track its state.
 
+<!-- HOOKS:END -->
+
 ## 🧪 TypeScript
 
 Every hook ships its own declarations — no `@types/hookli` needed. Data hooks are generic,
diff --git a/packages/hookli/scripts/gen-readme.mjs b/packages/hookli/scripts/gen-readme.mjs
index af2af74..58a29c4 100644
--- a/packages/hookli/scripts/gen-readme.mjs
+++ b/packages/hookli/scripts/gen-readme.mjs
@@ -1,6 +1,7 @@
-// Regenerate the README's "Available hooks" list + hook-count badge from the
+// Regenerate the README's category-grouped hook index + hook-count badge from the
 // single source of truth: hooks.manifest.json. Run via `pnpm --filter hookli gen:manifest`
-// (also runs on prepublishOnly). Do NOT hand-edit the generated list.
+// (also runs on prepublishOnly). Do NOT hand-edit the generated index — everything
+// between the HOOKS:START / HOOKS:END markers is overwritten.
 import { readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -9,6 +10,10 @@ const root = join(dirname(fileURLToPath(import.meta.url)), "..");
 const { hooks } = JSON.parse(readFileSync(join(root, "hooks.manifest.json"), "utf8"));
 const count = hooks.length;
 
+// Category order + labels mirror apps/docs/lib/hooks-registry.ts (CATEGORY_ORDER / CATEGORY_LABELS).
+const CATEGORY_ORDER = ["state", "effects", "dom", "data"];
+const CATEGORY_LABELS = { state: "State", effects: "Effects", dom: "DOM", data: "Data" };
+
 const readmePath = join(root, "README.md");
 let md = readFileSync(readmePath, "utf8");
 
@@ -16,13 +21,26 @@ let md = readFileSync(readmePath, "utf8");
 md = md.replace(/badge\/\d+_hooks-/g, `badge/${count}_hooks-`);
 md = md.replace(/alt="\d+ hooks"/g, `alt="${count} hooks"`);
 
-// 2) the "Available hooks" bullet block (a contiguous run of `- **[`useX`](…)** — …` lines)
-const list = hooks
-  .map((h) => `- **[\`${h.name}\`](https://hookli.vercel.app/docs/${h.slug})** — ${h.description}`)
-  .join("\n");
-const block = /(?:^- \*\*\[`use.*\r?\n?)+/m;
-if (!block.test(md)) throw new Error("gen-readme: could not find the hook bullet block in README.md");
-md = md.replace(block, list + "\n");
+// 2) the category-grouped hook index, between the HOOKS:START / HOOKS:END markers.
+//    A hook whose category is not one we know would be silently dropped — fail loudly.
+const known = new Set(CATEGORY_ORDER);
+const orphan = hooks.find((h) => !known.has(h.category));
+if (orphan) {
+  throw new Error(`gen-readme: hook "${orphan.name}" has unknown category "${orphan.category}"`);
+}
+
+const bullet = (h) =>
+  `- **[\`${h.name}\`](https://hookli.vercel.app/docs/${h.slug})** — ${h.description}`;
+const grouped = CATEGORY_ORDER.map((cat) => {
+  const items = hooks.filter((h) => h.category === cat);
+  return `### ${CATEGORY_LABELS[cat]} (${items.length})\n\n${items.map(bullet).join("\n")}`;
+}).join("\n\n");
+
+const region = /(<!-- HOOKS:START[\s\S]*?-->)[\s\S]*?(<!-- HOOKS:END -->)/;
+if (!region.test(md)) {
+  throw new Error("gen-readme: could not find the HOOKS:START / HOOKS:END markers in README.md");
+}
+md = md.replace(region, `$1\n\n${grouped}\n\n$2`);
 
 writeFileSync(readmePath, md);