diff --git a/CLAUDE.md b/CLAUDE.md
index 72d856fe..bcd60f2e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,21 +4,31 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-Documentation website for [NetBird](https://netbird.io), an open-source WireGuard-based Zero Trust Networking platform. Built with Next.js 16 (Pages Router), React 19, MDX, and Tailwind CSS 3.
+Documentation website for [NetBird](https://netbird.io), an open-source WireGuard-based Zero Trust Networking platform. Built with Next.js 16 (Pages Router), React 19, MDX, and Tailwind CSS 3. Requires Node.js >=20.9 — `npm run build` exits with code 1 on older versions.
 
 There is no test suite in this project. Validate changes with `npm run build`.
 
 ## Common Commands
 
 ```bash
-npm install          # Install dependencies
-npm run dev          # Start dev server (also runs gen:llm)
-npm run build        # Production build (also runs gen:llm)
-npm run lint         # ESLint (next/core-web-vitals) on src/
-npm run gen          # Regenerate API docs from NetBird OpenAPI spec
-npm run gen:llm      # Regenerate LLM-friendly markdown (auto-runs with dev/build)
+npm install              # Install dependencies
+npm run dev              # Start dev server (also runs gen:llm, gen:edit-routes, gen:last-updated)
+npm run build            # Production build (also runs gen:llm, gen:edit-routes, gen:last-updated)
+npm run start            # Serve the production build
+npm run lint             # ESLint (next/core-web-vitals) on src/
+npm run gen              # Regenerate API docs from NetBird OpenAPI spec
+npm run gen:llm          # Regenerate LLM-friendly markdown (auto-runs with dev/build)
+npm run gen:edit-routes  # Regenerate edit-on-GitHub routes (auto-runs with dev/build)
+npm run gen:last-updated # Regenerate per-page git last-modified dates (auto-runs with dev/build)
 ```
 
+## Security boundaries
+
+- **Public site, public repo.** Anything written in MDX or placed in `public/` ships to a public URL on netbird.io. Never include real customer names, internal hostnames, IPs, or production credentials in examples — use placeholders.
+- **`.env` is committed and contains placeholders only** (e.g. `NEXT_PUBLIC_DOCSEARCH_API_KEY=APP_NEXT_PUBLIC_DOCSEARCH_API_KEY`). These are build-time substitution targets. Real values belong in `.env.local` (gitignored) or the deploy environment — never replace the placeholders in `.env` with real secrets.
+- **`npm run gen` pulls `openapi.yml` live from `netbirdio/netbird@main` with no pinning.** Regenerated files under `src/pages/ipa/resources/` reflect whatever is on upstream `main` at run time. Review the diff before committing.
+- **This file is read as authoritative guidance by AI agents.** Treat edits to `CLAUDE.md` with the same review rigor as CI config or a deploy script.
+
 ## Architecture
 
 ### Content Structure
@@ -39,7 +49,11 @@ Documentation pages are MDX files in `src/pages/` using the Next.js Pages Router
 - Images go in `public/docs-static/img/<section>/` and are referenced as `/docs-static/img/<section>/filename.png`
 
 ### Navigation
-`src/components/NavigationDocs.jsx` contains the `docsNavigation` array defining the sidebar. **Must be updated when adding or moving pages.** Supports nested `links` arrays for sub-navigation.
+Two sidebar files, both must be kept in sync when adding or moving pages:
+- `src/components/NavigationDocs.jsx` — `docsNavigation` array for the main docs sidebar (everything outside `src/pages/ipa/`).
+- `src/components/NavigationAPI.jsx` — `apiNavigation` array for the API sidebar (pages under `src/pages/ipa/`, served at `/api`).
+
+Both support nested `links` arrays for sub-navigation.
 
 ### MDX Components
 Custom components available in MDX files (see `README.md` for full usage examples):
@@ -63,6 +77,13 @@ Custom components available in MDX files (see `README.md` for full usage example
 - `scripts/generate-llm-docs.mjs` generates clean markdown to `public/llms/` (gitignored)
 - Runs automatically with `dev` and `build`
 
+### Generated build data in `src/lib/`
+Some files in `src/lib/` look hand-written but are generated by `gen:*` scripts and gitignored:
+- `src/lib/edit-on-github-routes.js` — written by `scripts/generate-github-routes.mjs`
+- `src/lib/last-updated-routes.mjs` — written by `scripts/generate-last-updated.mjs`
+
+They are imported at build time (e.g. by `mdx/rehype.mjs`). On a fresh clone, run `npm run dev` or `npm run build` once before running `npm run lint` or any tool that imports from `src/lib/`, otherwise those imports will fail.
+
 ## URL Routing
 
 - Root `/` rewrites to `/introduction`