Clarify .netrc content for JS library docs

content/chainguard/libraries/access.md

@@ -239,6 +239,10 @@ Chainguard Libraries for
 Java](/chainguard/libraries/java/build-configuration/#bazel) or for manual
 testing with curl.
 
+> Note: `.netrc` authentication is not supported by npm, pnpm, or Yarn. For
+direct access to Chainguard Libraries for JavaScript, use the .npmrc-based
+authentication described in the [JavaScript build configuration](/chainguard/libraries/javascript/build-configuration/#direct-access) instead. 
+
 The following example shows a suitable setup for a repo manager available at
 `repo.example.com`:
 
@@ -248,15 +252,15 @@ login YOUR_USERNAME_FOR_REPOSITORY_MANAGER
 password YOUR_PASSWORD
 ```
 
-For a direct connection to Chainguard Libraries, for example for testing with
+For a direct connection to Chainguard Libraries for Java or Python, for example for testing with
 curl, use the following example with the username
-`CHAINGUARD_PYTHON_IDENTITY_ID` and password `CHAINGUARD_PYTHON_TOKEN` value for
+`CHAINGUARD_JAVA_IDENTITY_ID` and password `CHAINGUARD_JAVA_TOKEN` value for
 the pull token for the desired language ecosystem:
 
 ```
 machine libraries.cgr.dev
-login CHAINGUARD_PYTHON_IDENTITY_ID
-password CHAINGUARD_PYTHON_TOKEN
+login CHAINGUARD_JAVA_IDENTITY_ID
+password CHAINGUARD_JAVA_TOKEN
 ```
 
 Note that the long string for the password value must use only one line.

content/chainguard/libraries/chainguard-repository.md

@@ -13,41 +13,88 @@ menu:
 weight: 005
 toc: true
 ---
-Chainguard Repository is a unified Chainguard-managed experience for pulling secure-by-default open source artifacts. Chainguard Libraries for JavaScript is the first artifact type available through it, with configurable policies that control how both Chainguard-built packages and upstream npm packages are consumed. Upstream packages are subject to additional security controls, including malware scanning and an optional cooldown period.
-
-Pointing your existing build tools or repository manager tools at the Chainguard Repository gives you:
-* Access to both Chainguard-built packages and upstream npm packages (when fallback is enabled), so you don't need to maintain a parallel npm fallback configuration.
-* Malware scanning and a cooldown period applied to all packages the repository serves, including those proxied from npm.
+Chainguard Repository is a unified Chainguard-managed experience for pulling
+secure-by-default open source artifacts. Chainguard Libraries for JavaScript is
+the first artifact type available through it, with configurable policies that
+control how both Chainguard-built packages and upstream npm packages are
+consumed. Upstream packages are subject to additional security controls,
+including malware scanning and an optional cooldown period.
+
+Pointing your existing build tools or repository manager tools at the Chainguard
+Repository gives you:
+* Access to both Chainguard-built packages and upstream npm packages (when
+  fallback is enabled), so you don't need to maintain a parallel npm fallback
+  configuration.
+* Malware scanning and a cooldown period applied to all packages the repository
+  serves, including those proxied from npm.
 * One endpoint to configure, whether or not you use an artifact manager.
 
 ## Using the Chainguard Repository endpoint for JavaScript
-The Chainguard Repository for Javascript uses the same endpoint and authentication as Chainguard Libraries for JavaScript: `https://libraries.cgr.dev/javascript/`.
+The Chainguard Repository for Javascript uses the same endpoint and
+authentication as Chainguard Libraries for JavaScript:
+`https://libraries.cgr.dev/javascript/`.
 
-See [Technical Details](/chainguard/libraries/javascript/overview/#technical-details) for instructions for retrieving credentials with `chainctl`. No additional token setup is required.
+You can use your existing `chainctl` token. See [Chainguard Libraries
+Access](/chainguard/libraries/access/) for instructions for retrieving
+credentials with `chainctl`. 
 
-Learn about [fallback configuration](#configuring-upstream-fallback) and [cooldown periods](#cooldown-period) later on this page.
+Learn about [fallback configuration](#configuring-upstream-fallback) and
+[cooldown periods](#cooldown-period) later on this page.
 
 ### Use Chainguard Repository with build tools
-If you don’t use an artifact manager, you can point your build tools directly at the Chainguard Libraries for JavaScript endpoint:
+If you don’t use an artifact manager, you can point your build tools directly at
+the Chainguard Libraries for JavaScript endpoint. The Chainguard Repository
+handles fallback, so no additional registry configuration is needed alongside
+it.
+
+#### Step 1: Generate credentials and set them in your project
+
+Authentication is required. The recommended way to set up credentials for direct
+npm access is using `chainctl`:
 
 ```bash
-# npm
-npm config set registry https://libraries.cgr.dev/javascript/
+# Generate credentials and set them in your project .npmrc in one step
+eval $(chainctl auth pull-token --output env --repository=javascript --parent=<your-org>)
+export token=$(echo -n "${CHAINGUARD_JAVASCRIPT_IDENTITY_ID}:${CHAINGUARD_JAVASCRIPT_TOKEN}" | base64 -w 0)
+npm config set registry https://libraries.cgr.dev/javascript/ --location=project
+npm config set //libraries.cgr.dev/javascript/:_auth "${token}" --location=project
+```
+
+Note that npm requires credentials as a base64-encoded token in `.npmrc` — the
+`.netrc` credential format used for other Chainguard Libraries ecosystems does
+not work with npm.
+
+#### Step 2: Configure your tool to use the Chainguard endpoint
 
+Next, configure your tool of choice to use the Chainguard endpoint as its
+registry:
+
+```bash
 # pnpm
 pnpm config set registry https://libraries.cgr.dev/javascript/
 
 # Yarn
 yarn config set npmRegistryServer https://libraries.cgr.dev/javascript/
 ```
-For full setup instructions including authentication, see [Build Configuration: Direct Access](/chainguard/libraries/javascript/build-configuration/#direct-access/).
 
-### Use Chainguard Repository with a repository manager
-If you use Cloudsmith, JFrog Artifactory, Sonatype Nexus, or a similar repository manager, you can point it to the Chainguard Repository endpoint directly. This replaces the previous pattern of configuring Chainguard Libraries and npm as separate upstreams with a priority ordering.
+For full setup instructions including authentication, see [Build Configuration:
+Direct
+Access](/chainguard/libraries/javascript/build-configuration/#direct-access/).
 
-Point your repository manager's virtual or group repository at `libraries.cgr.dev/javascript` as the single upstream. The Chainguard Repository handles fallback and policy; your repo manager handles local caching and access control for your organization.
-
-See [Global configuration](/chainguard/libraries/javascript/global-configuration/) for setup guides per repository manager.
+### Use Chainguard Repository with a repository manager
+If you use JFrog Artifactory, Sonatype Nexus, or a similar repository manager,
+you can point it to the Chainguard Repository endpoint as your single upstream
+npm source. This replaces the previous pattern of configuring Chainguard
+Libraries and npm as separate upstreams with a priority ordering.
+
+Point your repository manager's virtual or group repository at
+`libraries.cgr.dev/javascript` as the single upstream. The Chainguard Repository
+handles fallback and policy; your repo manager handles local caching and access
+control for your organization.
+
+See [Global
+configuration](/chainguard/libraries/javascript/global-configuration/) for setup
+guides per repository manager.
 
 ### Configuring upstream fallback
 By default, the Chainguard Repository serves only Chainguard-built packages. You can contact your Chainguard account team or customer support to enable the built-in fallback to the upstream npm registry, which allows the repository to serve packages not yet built by Chainguard. All upstream packages are subject to additional [security controls](#security-controls) before they are served.

content/chainguard/libraries/javascript/build-configuration.md

@@ -59,8 +59,17 @@ to determine URL and authentication details.
 
 Build configuration to retrieve artifacts **directly** from the Chainguard
 Libraries for JavaScript repository at `https://libraries.cgr.dev/javascript/`
-requires authentication with username and password from a pull token as detailed
-in [access documentation](/chainguard/libraries/access/#pull-token).
+requires authentication with a pull token as detailed
+in the [access documentation](/chainguard/libraries/access/#pull-token).
+
+>Note: Direct access requires per-project and per-workstation configuration. For organizations with multiple teams, proxying through an artifact manager is recommended. See [global configuration](/chainguard/libraries/javascript/global-configuration/) for setup guides.
+
+For authentication setup with each build tool, see the "Minimal example project"
+sections on this page:
+- [npm](#npm-minimal)
+- [pnpm](#pnm-minimal)
+- [Yarn](#yarn-berry-minimal)
+- [Yarn Classic](#yarn-classic-minimal)
 
 <a id="npm"></a>
 
@@ -160,7 +169,8 @@ the environment variables are set, the following steps configure registry
 access with authentication in the `.npmrc` file in the current project
 directory:
 
-```shell
+```bash
+eval $(chainctl auth pull-token --output env --repository=javascript --parent=<your-org>)
 export token=$(echo -n "${CHAINGUARD_JAVASCRIPT_IDENTITY_ID}:${CHAINGUARD_JAVASCRIPT_TOKEN}" | base64 -w 0)
 
 npm config set registry https://libraries.cgr.dev/javascript/ --location=project