diff --git a/pacquet/AGENTS.md b/pacquet/AGENTS.md
index dc225afc2e..ab4246943c 100644
--- a/pacquet/AGENTS.md
+++ b/pacquet/AGENTS.md
@@ -84,7 +84,7 @@ by crate or name — see below).
 - `just cli -- <args>` — run the pacquet binary.
 - `just registry-mock <args>` — manage the mock registry used by tests.
 - `just integrated-benchmark <args>` — compare revisions or compare against
-  pnpm itself (see `README.md`).
+  pnpm itself (see `CONTRIBUTING.md`).
 
 Warnings are errors (`--deny warnings` in lint). Do not silence them with
 `#[allow(...)]` unless there is a specific, justified reason.
diff --git a/pacquet/CONTRIBUTING.md b/pacquet/CONTRIBUTING.md
index 960444ed17..7f989ab157 100644
--- a/pacquet/CONTRIBUTING.md
+++ b/pacquet/CONTRIBUTING.md
@@ -61,3 +61,54 @@ This runs `typos`, `cargo fmt`, `just check` (which is `cargo check --locked`),
 
 > [!NOTE]
 > Some integration tests require the local registry mock. Start it with `just registry-mock launch` before running `just test` if a test needs it.
+
+## Debugging
+
+Set the `TRACE` environment variable to enable trace-level logging for a given module:
+
+```sh
+TRACE=pacquet_tarball just cli add fastify
+```
+
+## Testing
+
+```sh
+just install              # install necessary dependencies
+just registry-mock launch # start a mocked registry server (optional)
+just test                 # run tests
+```
+
+## Benchmarking
+
+First, start a local registry server, such as [verdaccio](https://verdaccio.org/):
+
+```sh
+verdaccio
+```
+
+Then use the `integrated-benchmark` task to run benchmarks. For example:
+
+```sh
+# Compare the branch you are working on against main
+just integrated-benchmark --scenario=frozen-lockfile my-branch main
+```
+
+```sh
+# Compare the current commit against the previous commit
+just integrated-benchmark --scenario=frozen-lockfile HEAD HEAD~
+```
+
+```sh
+# Compare pacquet of the current commit against pnpm
+just integrated-benchmark --scenario=frozen-lockfile --with-pnpm HEAD
+```
+
+```sh
+# Compare pacquet of the current commit, pacquet of main, and pnpm against each other
+just integrated-benchmark --scenario=frozen-lockfile --with-pnpm HEAD main
+```
+
+```sh
+# See more options
+just integrated-benchmark --help
+```
diff --git a/pacquet/README.md b/pacquet/README.md
index 4aad6e231a..363528b6c1 100644
--- a/pacquet/README.md
+++ b/pacquet/README.md
@@ -1,73 +1,22 @@
 # pacquet
 
-Experimental package manager for node.js written in rust.
+> [!WARNING]
+> **pacquet is under active development and not yet ready for production use.**
 
-### TODO
+The official pnpm rewrite in Rust.
 
-- [x] `.npmrc` support (for supported features [readme.md](./crates/npmrc/README.md))
-- [x] CLI commands (for supported features [readme.md](./crates/cli/README.md))
-- [x] Content addressable file store support
-- [ ] Shrink-file support in sync with `pnpm-lock.yml`
-  - [x] Frozen lockfile
-  - [ ] Update outdated lockfile
-  - [ ] Creating lockfile
-- [ ] Workspace support
-- [ ] Full sync with [pnpm error codes](https://pnpm.io/errors)
-- [ ] Generate a `node_modules/.bin` folder
-- [ ] Add CLI report
+pacquet is a port of the [pnpm](https://github.com/pnpm/pnpm) CLI from TypeScript to Rust. It is not a new package manager and not a reimagining of pnpm. Its behavior, flags, defaults, error codes, file formats, and directory layout will match pnpm exactly.
 
-## Debugging
+## Roadmap
 
-```shell
-TRACE=pacquet_tarball just cli add fastify
-```
+pacquet will become the installation engine of pnpm. The transition will happen in two phases.
 
-## Testing
+### Phase 1: fetching and linking
 
-```sh
-# Install necessary dependencies
-just install
+pacquet replaces fetching and linking only. pnpm continues to create the lockfile, and pacquet does the rest. We expect this alone to make pnpm at least twice as fast in most scenarios. Shipping this phase is the current focus.
 
-# Start a mocked registry server (optional)
-just registry-mock launch
+### Phase 2: resolution
 
-# Run test
-just test
-```
+pacquet also takes over dependency resolution.
 
-## Benchmarking
-
-### Install between multiple revisions
-
-First, you to start a local registry server, such as [verdaccio](https://verdaccio.org/):
-
-```sh
-verdaccio
-```
-
-Then, you can use the script named `integrated-benchmark` to run the various benchmark, For example:
-
-```sh
-# Comparing the branch you're working on against main
-just integrated-benchmark --scenario=frozen-lockfile my-branch main
-```
-
-```sh
-# Comparing current commit against the previous commit
-just integrated-benchmark --scenario=frozen-lockfile HEAD HEAD~
-```
-
-```sh
-# Comparing pacquet of current commit against pnpm
-just integrated-benchmark --scenario=frozen-lockfile --with-pnpm HEAD
-```
-
-```sh
-# Comparing pacquet of current commit, pacquet of main, and pnpm against each other
-just integrated-benchmark --scenario=frozen-lockfile --with-pnpm HEAD main
-```
-
-```sh
-# See more options
-just integrated-benchmark --help
-```
+See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for development setup, debugging, testing, and benchmarking.
diff --git a/pacquet/npm/pacquet/README.md b/pacquet/npm/pacquet/README.md
new file mode 100644
index 0000000000..abcc34f1d3
--- /dev/null
+++ b/pacquet/npm/pacquet/README.md
@@ -0,0 +1,15 @@
+# pacquet
+
+> **pacquet is under active development and not yet ready for production use.** See the [project roadmap](https://github.com/pnpm/pacquet/issues/299).
+
+The official pnpm rewrite in Rust.
+
+pacquet is a port of the [pnpm](https://github.com/pnpm/pnpm) CLI from TypeScript to Rust. It is not a new package manager and not a reimagining of pnpm. Its behavior, flags, defaults, error codes, file formats, and directory layout will match pnpm exactly.
+
+## Installation
+
+```sh
+pnpm add -g pacquet
+```
+
+This package is a thin Node.js wrapper that dispatches to a platform-specific native binary for your operating system and architecture.
diff --git a/pacquet/npm/pacquet/package.json b/pacquet/npm/pacquet/package.json
index 3d916cb0bc..c55f4f66c0 100644
--- a/pacquet/npm/pacquet/package.json
+++ b/pacquet/npm/pacquet/package.json
@@ -1,8 +1,10 @@
 {
   "name": "pacquet",
   "version": "0.2.1",
-  "description": "experimental package manager for node.js",
-  "keywords": [],
+  "description": "The official pnpm rewrite in Rust (preview, not production-ready)",
+  "keywords": [
+    "pnpm"
+  ],
   "author": {
     "name": "Yagiz Nizipli",
     "email": "yagiz@nizipli.com"