diff --git a/content/chainguard/libraries/javascript/build-configuration.md b/content/chainguard/libraries/javascript/build-configuration.md
index aa06d98bc2..4d1941a4a5 100644
--- a/content/chainguard/libraries/javascript/build-configuration.md
+++ b/content/chainguard/libraries/javascript/build-configuration.md
@@ -4,7 +4,7 @@ linktitle: "Configure build tools"
 description: "Configuring Chainguard Libraries for JavaScript on your workstation"
 type: "article"
 date: 2025-06-05T09:00:00+00:00
-lastmod: 2026-10-07T14:49:03+00:00
+lastmod: 2026-10-20T16:02:37+00:00
 draft: false
 tags: ["Chainguard Libraries", "JavaScript"]
 menu:
@@ -413,6 +413,35 @@ chainctl auth configure-npm
 
 [This command](/platform/chainctl/chainctl-docs/chainctl_auth_configure-npm/) writes a project-level `.npmrc` with the registry URL and base64-encoded credentials. It also prints the equivalent `npm config set` commands for use in CI or other environments where you need to configure `.npmrc` manually. If this command returns an error, ensure that you are using the [latest version of `chainctl`](/platform/chainctl-usage/how-to-install-chainctl/#updating-chainctl).
 
+For CI/CD, prefer an assumable identity when using this command. Expand the following to learn more:
+
+{{< details "Configure npm in CI and headless environments" >}}
+
+Do not use `--headless` as a CI option. It starts a device-code login and waits for someone to complete authentication in a browser. For CI/CD, Chainguard recommends using an assumable identity. Authenticate the workload first, then run a job similar to the following:
+
+```yaml
+permissions:
+  id-token: write
+
+steps:
+  - uses: chainguard-dev/setup-chainctl@<pinned-version>
+    with:
+      identity: <identity-id>
+  - run: chainctl auth configure-npm
+```
+
+If the runner already has a valid session scoped to `libraries.cgr.dev`, run `chainctl auth configure-npm` without `--headless`; the command can reuse that session. A session scoped only to `console-api.enforce.dev` is not sufficient.
+
+If the environment has neither an assumable identity nor a reusable libraries-scoped session, use a pull token:
+
+```bash
+chainctl auth configure-npm --pull-token
+```
+
+`--pull-token` produces credentials suitable for non-interactive CI, but token creation is not an unauthenticated CI bootstrap step. Pre-create the token and store its credentials securely.
+
+{{< /details >}}
+
 Alternatively, you can configure the `.npmrc` file manually:
 
 {{< details "Configure .npmrc manually" >}}