docs: add build instructions to CLAUDE.md

CLAUDE.md

@@ -51,3 +51,86 @@ 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.
+
+## Creating a Build
+
+This project ships as an RPM package (Build System name: `node_exporter`). Builds are submitted to the CloudLinux Build System via its CLI.
+
+### Step 1 — Generate the build plan
+
+```bash
+cd /root/ai-workspace/node_exporter
+git checkout <branch-or-tag>                # branch, tag, or detached HEAD
+uv run /root/ai-workspace/cl-aiworkspaces/workspace-side/scripts/build-plan.py
+```
+
+The script reads `cl-aiworkspaces/.agents/skills/build-create/projects-catalog.yaml` to map this workspace directory to its Build System name(s) and emits a JSON plan on stdout (warnings/errors on stderr; exit 1 on fatal errors such as uncommitted changes).
+
+The plan contains:
+- `build_type_id` — build-type for the payload
+- `build_platforms` — target platforms (e.g. CL7, CL8, CL9)
+- `build_flavors` — flavor IDs
+- `projects` — project names, build refs, testing config
+- `jenkins_jobs` — Jenkins job IDs and definitions
+
+### Step 2 — Filter the plan to this project only
+
+The plan may include unrelated workspace projects. **Strip all entries from `projects` except `node_exporter`**, and keep only the Jenkins jobs relevant to it. One project per build — do not submit a multi-project payload.
+
+### Step 3 — Submit the build
+
+```bash
+/root/ai-workspace/cl-aiworkspaces/workspace-side/mcps/mcp-cli-wrapper.sh build-system \
+  create-build --raw '<filtered-plan-json>'
+```
+
+Minimum payload shape:
+
+```json
+{
+  "build_type_id": "<from plan>",
+  "build_platforms": [<from plan>],
+  "build_flavors": ["<flavor_id>"],
+  "target_channel": "beta",
+  "projects": [
+    {
+      "name": "node_exporter",
+      "build_ref": { "name": "<branch-or-tag>", "type": "git_branch" },
+      "testing": { "qa_ref": "<branch-or-tag>" }
+    }
+  ],
+  "jenkins_jobs": [<from plan — only jobs relevant to this project>]
+}
+```
+
+`build_ref.type` options: `git_branch`, `git_tag`, or `gerrit_change` (for `refs/changes/XX/NNNNN/PS` refs — the `qa_ref` should then be `NNNNN/PS`).
+
+The CLI returns a build ID. Build URL: `https://build.cloudlinux.com/#/build/<build_id>`.
+
+### Step 4 — Monitor
+
+```bash
+/root/ai-workspace/cl-aiworkspaces/workspace-side/mcps/mcp-cli-wrapper.sh build-system \
+  get-build --build-id <build_id>
+```
+
+### Step 5 — Debug failures
+
+Search logs for errors:
+
+```bash
+/root/ai-workspace/cl-aiworkspaces/workspace-side/mcps/mcp-cli-wrapper.sh build-system \
+  search-build-logs --build-id <build_id> --query "error"
+```
+
+Common failure patterns:
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `FAILED` in test output | Test regression | Update the test — do not revert the code fix |
+| `ModuleNotFoundError` / `ImportError` | New dependency not declared | Add to the `.spec` `Requires`/`BuildRequires` (or equivalent) |
+| `SyntaxError` in build log | Source typo | Fix the source |
+| `%files`/`%install` mismatch | Spec file vs installed layout drift | Update the spec stanzas |
+| Dependency-resolution errors | `Requires` constraint wrong | Check spec file version constraints |
+
+After fixing, push to the same branch and re-run steps 1–3.