docs: reframe project as the official pnpm rewrite (#308)

* docs: reframe project as the official pnpm rewrite

- rewrite the top-level README around the pnpm-rewrite framing and a
  two-phase roadmap, dropping the stale TODO list
- move debugging, testing, and benchmarking sections into CONTRIBUTING.md
- add a README to the `npm/pacquet` package and update its description
  and keywords
- update the `AGENTS.md` cross-reference for the relocated benchmark
  instructions

* docs: surface "not production-ready" warning at the top of READMEs

Per review feedback, lift the in-development warning into the first
paragraph of `npm/pacquet/README.md` (with bold emphasis so it stays
visible on the npm registry page) and add a matching admonition near
the top of the workspace `README.md`. The goal is to make the
project's status unmissable for anyone landing on either page.

* docs(npm): mark the npm package description as a preview

* docs(npm): note the package is not production-ready in its description

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.

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
+```

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.

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.

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"