From a581da5f9f3f5b887ca7e05e682340126f6292a5 Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Mon, 4 May 2026 14:37:28 +0200 Subject: [PATCH 1/3] docs: refresh CLAUDE.md for Next.js 16 toolchain and API sidebar - Note Node.js >=20.9 requirement (Next 16 fails the build below this) - Update dev/build descriptions to mention gen:edit-routes; add start and gen:edit-routes to the common commands list - Document the second sidebar file (NavigationAPI.jsx) alongside NavigationDocs.jsx so the API sidebar is discoverable --- CLAUDE.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 72d856fec..8fa47b446 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,19 +4,21 @@ 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 and gen:edit-routes) +npm run build # Production build (also runs gen:llm and gen:edit-routes) +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) ``` ## Architecture @@ -39,7 +41,11 @@ Documentation pages are MDX files in `src/pages/` using the Next.js Pages Router - Images go in `public/docs-static/img/
/` and are referenced as `/docs-static/img/
/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): From 3a6f2276bdc4a77bd4fe501b9713b6e8cb26cc7f Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Mon, 4 May 2026 14:41:28 +0200 Subject: [PATCH 2/3] docs: add Security boundaries section to CLAUDE.md Calls out four posture items relevant to AI-assisted contributions: the repo is public, .env is committed and must hold placeholders only, npm run gen pulls upstream main without pinning, and CLAUDE.md itself is authoritative input to AI sessions and should be reviewed accordingly. --- CLAUDE.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 8fa47b446..8f0620ef1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,6 +21,13 @@ npm run gen:llm # Regenerate LLM-friendly markdown (auto-runs with dev/ npm run gen:edit-routes # Regenerate edit-on-GitHub routes (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 From a15534fe5b1e499b87eeac7471f1419d521fdb99 Mon Sep 17 00:00:00 2001 From: TechHutTV Date: Mon, 4 May 2026 10:04:02 -0700 Subject: [PATCH 3/3] Documented gen:last-updated and generated src/lib/ files --- CLAUDE.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8f0620ef1..bcd60f2e4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,13 +12,14 @@ There is no test suite in this project. Validate changes with `npm run build`. ```bash npm install # Install dependencies -npm run dev # Start dev server (also runs gen:llm and gen:edit-routes) -npm run build # Production build (also runs gen:llm and gen:edit-routes) +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 @@ -76,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`