Library update-hashes command (#3267)

[ ] Check if this is a typo or other quick fix and ignore the rest :)

## Type of change
Update to existing pages

### What should this PR do?
- Add how to use the new `chainctl libraries update-hashes` command in:
Quick start, JavaScript Build configuration, Python Build configuration,
Python Overview

### Why are we making this change?
This information will make it easier to migrate existing projects to
Chainguard

### What are the acceptance criteria? 
- Content should appear in the expected locations
- Content should be clear and accurate

### How should this PR be tested?
Review the deploy preview

---------

Signed-off-by: s-stumbo <sally.stumbo@chainguard.dev>

Author: s-stumbo

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

@@ -70,6 +70,34 @@ recommended. See the [global
 configuration](/chainguard/libraries/javascript/global-configuration/) for setup
 guides.
 
+## Updating lockfile hashes for existing projects
+
+> **Note**: `chainctl libraries update-hashes` does not currently support authentication through a repository manager. You will need to configure [direct access](#direct-access) credentials before running the command.
+
+If you are migrating an existing JavaScript project to Chainguard Libraries,
+your lockfile likely contains integrity hashes generated against the npm
+registry. Because Chainguard rebuilds packages in a secured build environment rather than distributing upstream artifacts directly, the resulting checksums differ even for identical package versions; they must be updated before reinstalling.
+
+Use the following command, in the directory containing the lockfile, to update hashes in place across all supported lockfile formats (`package-lock.json`, `yarn.lock`,
+`pnpm-lock.yaml`, `bun.lock`) without regenerating the lockfile from scratch:
+
+```bash
+chainctl libraries update-hashes
+```
+
+After running the command, ensure your `.npmrc` is configured with Chainguard
+credentials, then reinstall to apply the updated hashes. The `chainctl libraries update-hashes` command will output
+a "Next steps" section that includes the tool-specific command for reinstalling.
+
+> **Note:** If your organization uses the [Chainguard Repository with upstream
+> npm fallback
+> enabled](/chainguard/libraries/javascript/overview/#upstream-fallback-policy-and-controls),
+> packages that resolve through the upstream registry may still point to
+> `registry.npmjs.org` in your lockfile after running `chainctl libraries
+> update-hashes`. These packages are not automatically redirected to route
+> through Chainguard. To fully migrate these packages, update their resolved
+> URLs to use `libraries.cgr.dev/javascript-upstream/` manually.
+
 <a id="npm"></a>
 
 ## npm
@@ -144,8 +172,13 @@ Example URLs:
 * Sonatype Nexus: https://repo.example.com:8443/repository/javascript-all/
 * Direct access: https://libraries.cgr.dev/javascript/
 
-To change the packages, remove the `node_modules` directory and the
-`package-lock.json` file and run the `npm install` command again. 
+To apply the registry changes, remove the `node_modules` directory and the
+`package-lock.json` file and run the `npm install` command again. This re-fetches all
+packages from Chainguard and regenerates the lockfile with updated hashes.
+
+If you are migrating an existing project and want to preserve your current
+lockfile, use [`chainctl libraries update-hashes`](#updating-lockfile-hashes-for-existing-projects)
+to update only the integrity hashes in place instead.
 
 Now you can proceed with your development and testing. 
 
@@ -323,8 +356,13 @@ Example URLs:
 * Sonatype Nexus: https://repo.example.com:8443/repository/javascript-all/
 * Direct access: https://libraries.cgr.dev/javascript/
 
-To change the packages, remove the `node_modules` directory and the
-`pnpm-lock.yaml` file and run the `pnpm install` command again. 
+To apply the registry change, remove the `node_modules` directory and the
+`pnpm-lock.yaml` file and run the `pnpm install` command again. This re-fetches all
+packages from Chainguard and regenerates the lockfile with updated hashes.
+
+If you are migrating an existing project and want to preserve your current
+lockfile, use [`chainctl libraries update-hashes`](#updating-lockfile-hashes-for-existing-projects)
+to update only the integrity hashes in place instead.
 
 Now you can proceed with your development and testing. 
 
@@ -444,9 +482,14 @@ Example URLs:
 * Sonatype Nexus: https://repo.example.com:8443/repository/javascript-all
 * Direct access: https://libraries.cgr.dev/javascript
 
-To change the packages, run the `yarn` command again. This forces an update of
+To apply the registry change, run the `yarn` command again. This forces an update of
 all packages from the new registry and regeneration of the lock file.
 
+If you are migrating an existing project and want to preserve your current
+lockfile, use [`chainctl libraries update-hashes`](#updating-lockfile-hashes-for-existing-projects)
+to update only the integrity hashes in place instead.
+
+
 Now you can proceed with your development and testing. 
 
 <a id="yarn-berry-minimal"></a>
@@ -572,12 +615,16 @@ Refer to the [`.yarnrc`
 documentation](https://classic.yarnpkg.com/lang/en/docs/yarnrc/) for more
 details.
 
-To change the packages, remove the `node_modules` directory and the `yarn.lock`
+To apply the registry change, remove the `node_modules` directory and the `yarn.lock`
 file and run the `yarn` command again. This forces a new download of all
 packages from the new registry and regeneration of the lock file. Alternatively,
 you can run `yarn upgrade` to update all dependencies to their latest allowed
 versions and regenerate the lock file.
 
+If you are migrating an existing project and want to preserve your current
+lockfile, use [`chainctl libraries update-hashes`](#updating-lockfile-hashes-for-existing-projects)
+to update only the integrity hashes in place instead.
+
 Now you can proceed with your development and testing. 
 
 <a id="yarn-classic-minimal"></a>

content/chainguard/libraries/javascript/overview.md

@@ -93,6 +93,61 @@ You can continue to use additional registries alongside Chainguard for needs out
 
 Configure this endpoint [globally through a repository manager](/chainguard/libraries/javascript/global-configuration/) for centralized access control across your organization, or use it for [direct access](/chainguard/libraries/javascript/build-configuration/) from individual build tools. If you prefer to manage your own npm fallback rather than using the built-in upstream fallback, see the [global configuration documentation](/chainguard/libraries/javascript/global-configuration/) for setup guides per repository manager.
 
+## Updating lockfile hashes
+
+When migrating an existing JavaScript project to Chainguard Libraries, your
+lockfile contains integrity hashes generated against npm registry artifacts.
+Because Chainguard rebuilds packages in a secured build environment rather than
+distributing upstream artifacts directly, the resulting checksums differ even
+for identical package versions. These hashes must be updated before your package
+manager will accept packages from Chainguard.
+
+> **Note:** `chainctl libraries update-hashes` does not currently support
+> authentication through a repository manager. You will need to
+> [configure direct access](/chainguard/libraries/javascript/build-configuration/#direct-access)
+> credentials before running the command, or update the lockfiles manually.
+
+The `chainctl libraries update-hashes` command automates lockfile hash updates
+for all supported JavaScript lockfile formats. Rather than deleting your
+lockfile and reinstalling from scratch, you can run the command directly against
+your existing lockfile to update integrity hashes and resolved URLs to use
+Chainguard, while preserving the file's format and structure.
+
+Supported formats include `package-lock.json` (npm v2/v3), `yarn.lock` (Yarn
+Classic and Berry), `pnpm-lock.yaml`, and `bun.lock`.
+
+Run the command in the directory containing the lockfile:
+
+```bash
+chainctl libraries update-hashes
+```
+
+Or specify a lockfile path directly:
+
+```bash
+chainctl libraries update-hashes path/to/lockfile
+```
+
+By default, Chainguard hashes are appended alongside existing upstream hashes
+and resolved URLs are updated to point to Chainguard. After updating the
+lockfile, ensure your `.npmrc` or equivalent is configured with Chainguard
+credentials, then reinstall to apply the changes. The `chainctl libraries update-hashes` command will output
+a "Next steps" section that includes the tool-specific command for reinstalling.
+
+> **Note:** Packages that resolve through the Chainguard Repository's upstream
+> npm fallback may still point to `registry.npmjs.org` in your lockfile after
+> running the command. See [Upstream packages](#upstream-packages) for
+> details.
+
+#### Upstream packages
+
+If your organization uses the Chainguard Repository with upstream npm fallback
+enabled, packages that resolve through the upstream registry may still point to
+`registry.npmjs.org` in your lockfile after running `chainctl libraries
+update-hashes`. These packages are not automatically redirected to route through
+Chainguard. Once Chainguard has rebuilt the package from source, a subsequent
+run of `update-hashes` will update it automatically.
+
 ## Provenance and attestations
 Chainguard Libraries for JavaScript include SLSA provenance with signed attestations. 
 These attestations cryptographically link each package to the Chainguard 

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

@@ -491,6 +491,10 @@ Chainguard Libraries for Python. For testing purposes, you can use direct access
 and environment variables as detailed in the [access
 documentation](/chainguard/libraries/access/#use-environment-variables-for-pull-token-credentials). 
 
+> **Migrating an existing project?** If you have an existing uv lockfile with
+> upstream hashes, use [`chainctl libraries update-hashes`](/chainguard/libraries/python/overview/#updating-lockfile-hashes)
+> to update hashes in place rather than starting from scratch.
+
 **1. Configure credentials**
 
 Once the environment variables are set, configure credentials in `~/.netrc`:
@@ -613,6 +617,9 @@ Use the following steps to create a minimal example project for pip with Chaingu
 For testing purposes, you can use direct access and environment variables as detailed in the [access
 documentation](/chainguard/libraries/access/#use-environment-variables-for-pull-token-credentials).  
 
+> **Migrating an existing project?** If you have an existing pip lockfile with
+> upstream hashes, use [`chainctl libraries update-hashes`](/chainguard/libraries/python/overview/#updating-lockfile-hashes)
+> to update hashes in place rather than starting from scratch.
 
 **1. Update your configuration to point to Chainguard**
 

content/chainguard/libraries/python/overview.md

@@ -321,7 +321,7 @@ Because Chainguard rebuilds Python packages from source rather than mirroring up
 - Tools such as `pip`, `Poetry`, and `uv` generate lock files that include SHA-256 hashes
 - Repository managers such as JFrog Artifactory or Sonatype Nexus may have cached upstream PyPI wheels and continue serving them instead of Chainguard versions, even after you have reconfigured to use Chainguard Libraries
 
-Resolving these issues requires two steps: [clearing cached artifacts](#clearing-caches-before-migration) at every layer of your build pipeline, and [regenerating lock files or requirements files](#resolving-checksum-mismatches) so they reflect Chainguard's checksums.
+Resolving these issues requires two steps: [clearing cached artifacts](#clearing-caches-before-migration) at every layer of your build pipeline, and [updating lock files or requirements files](#updating-lockfile-hashes) so they reflect Chainguard's checksums.
 
 ### Clearing caches before migration
 
@@ -357,7 +357,34 @@ Cached Docker image layers may reuse upstream dependencies even after reconfigur
 docker build --no-cache
 ```
 
-### Resolving checksum mismatches
+### Updating lockfile hashes
+
+> Note: `chainctl libraries update-hashes` does not currently support authentication through a repository manager. You will need to [configure direct access](/chainguard/libraries/python/build-configuration/#direct-access) credentials before running the command, or [update the lockfiles manually](#update-lockfiles-manually).
+
+The `chainctl libraries update-hashes` command automates lockfile hash updates for all supported Python lockfile formats. Rather than manually regenerating lock files with each tool, you can run the command directly against your existing lockfile to update hashes to Chainguard checksums while preserving your locked dependency versions, without re-resolving your dependency graph.
+
+Supported formats include `requirements.txt` (pip-tools `--hash` style), `poetry.lock`, `uv.lock`, `pdm.lock`, `Pipfile.lock`, and `pylock.toml`.
+
+Run the command in your project directory to auto-detect the lockfile:
+
+```bash
+chainctl libraries update-hashes
+```
+
+Or specify a lockfile path directly:
+
+```bash
+chainctl libraries update-hashes path/to/requirements.txt
+```
+
+By default, Chainguard hashes are appended alongside existing upstream hashes. After updating the lockfiles, to switch your environment to use Chainguard packages, configure your tool to use the Chainguard index and reinstall. The `chainctl libraries update-hashes` command will output
+a "Next steps" section that includes the tool-specific command for reinstalling. 
+
+#### Update lockfiles manually
+
+If you are using a repository manager, and do not want to use direct access temporarily while updating lockfiles, you can use the following instructions to update your lockfiles: 
+
+{{< details "Manually updating lockfiles" >}}
 
 Before regenerating lock files, ensure your tool is configured to use Chainguard as the package index by following the [global configuration](/chainguard/libraries/python/global-configuration/) or [direct access](/chainguard/libraries/python/build-configuration/#direct-access) documentation.
 
@@ -411,6 +438,8 @@ Repository managers such as JFrog Artifactory or Sonatype Nexus may continue ser
 
 Before regenerating lock files, ensure your tool is configured to use Chainguard as the package index by following the [global configuration](/chainguard/libraries/python/global-configuration/) or [direct access](/chainguard/libraries/python/build-configuration/#direct-access) documentation.
 
+{{< /details >}}
+
 >**Note:** While hash mismatches are expected for some tooling and
 configurations while migrating to Chainguard, you can verify the authenticity and provenance of Chainguard
 packages using SBOM and SLSA attestation files as described in the next section.

content/chainguard/libraries/quickstart.md

@@ -207,6 +207,11 @@ Classic](/chainguard/libraries/javascript/build-configuration/#minimal-example-p
 and
 [Bun](/chainguard/libraries/javascript/build-configuration/#minimal-example-project-4) to understand how to use these repositories.
 
+> **Migrating an existing Python or JavaScript project?** If you have an
+> existing lockfile with upstream hashes, use `chainctl libraries update-hashes`
+> to update checksums to Chainguard's automatically, without regenerating your
+> lockfile from scratch.
+
 ## Step 4: Verify your libraries
 
 After setup, you can verify that your dependencies are sourced from Chainguard using: