diff --git a/CLAUDE.md b/CLAUDE.md
index a586b2c2c5..d43f198b4f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -51,3 +51,51 @@ update the spec in the same commit.
   specs; if upstream has reimplemented something equivalent (e.g. unix
   socket support), prefer deleting the fork-local copy and documenting
   the change.
+
+## AI Workspace Required
+
+Both the local-test and Build System workflows below assume you are inside an [AI Workspace](https://gitlab.corp.cloudlinux.com/clos/ci-tools/cl-aiworkspaces) VM at `/root/ai-workspace/`. They depend on:
+
+- the workspace's CloudLinux OS toolchain and any project-specific runtime (Python venv, Node, Docker, …) — needed by the local-build and unit-test targets;
+- the workspace's `mcp-cli-wrapper.sh` and provisioned Build System / Jenkins tokens — needed by the BS payload helper.
+
+Outside an AI Workspace these commands will not work as documented. Spin up a workspace via `cl-aiworkspaces` first.
+
+## Local Tests
+
+Run from the repo root (`/root/ai-workspace/node_exporter/`):
+
+| Command | What it does |
+| --- | --- |
+| `make build` | Build the `node_exporter` binary |
+| `make test` | Run the upstream Go unit-test suite |
+| `make test-e2e` | Run the e2e harness (downloads collector fixtures on first run) |
+| `make checkmetrics && make checkrules` | Validate metric and rule schemas |
+
+## Build System
+
+This repo ships as an RPM/DEB package: `node_exporter`. **Use the `/build-create` skill to submit builds** — it runs `build-plan.py` and submits the payload via the Build System CLI. The tables below are the project-specific overrides on top of that generic flow.
+
+### Parameters
+
+Most fields come from `build-plan.py`; the table records what should end up in the final payload for a `node_exporter`-only build.
+
+| Field | Value |
+| --- | --- |
+| BS project name | `node_exporter` |
+| `build_type_id` | `5ac2787bdf7e526d4a5f0259` (CloudLinux OS packages) |
+| `build_platforms` | `CL7`, `CL8`, `CL9`, `CL10`, `ubuntu22_04_ext_cpanel` |
+| `build_flavors` | `alt-php-els` (id `68b1ad89aa0264b2618434c8`) |
+| `target_channel` | `beta` |
+| `build_ref.name` | **Branch (or tag) to build.** `build-plan.py` reads this from the current `git` checkout in the workspace — confirm you are on the intended branch (your feature branch, not `master`) before generating the plan. |
+| `build_ref.type` | `git_branch` or `git_tag`. |
+| `testing.qa_ref` (per project) and top-level `qa_ref` | **Branch checked out in the QA repo for Jenkins jobs.** `build-plan.py` defaults both to `"master"` regardless of `build_ref.name` — override to your feature branch if the QA side has matching changes. |
+
+### Jenkins jobs (node_exporter-relevant)
+
+`build-plan.py` emits the workspace-wide plan covering every project in the workspace. For a `node_exporter`-only build, filter `projects[]` down to `node_exporter` and keep **only** these jobs in `jenkins_jobs[]`:
+
+| Job name | Build System `_id` |
+| --- | --- |
+| `CMT-end-server-tools` | `635b962c2afd3e1feec603bd` |
+| `clpro-ubuntu-tests` | `677e40a2f1b69faa0d69baf6` |