Correct published package installation instructions

README.md

@@ -52,7 +52,7 @@ await assertChunkInvariant({
 });
 ```
 
-Return a **fresh parser on every factory call**. Emit complete semantic events and flush remaining output in `end()`. [Adapt your parser, install the tarball, and replay failures →](docs/USAGE.md)
+Return a **fresh parser on every factory call**. Emit complete semantic events and flush remaining output in `end()`. [Install the package, adapt your parser, and replay failures →](docs/USAGE.md)
 
 ## Know the limits
 
@@ -65,7 +65,7 @@ Fixtures contain exact input bytes and may contain secrets. The runtime has no t
 `npm run check` runs regression tests, strict API type checks, and a clean packed-package consumer. CI covers Node 20, 22, and 24.
 
 ```sh
-npm install @agent-axiom/streamsplit
+npm install --save-dev @agent-axiom/streamsplit
 ```
 
 Available on [npm](https://www.npmjs.com/package/@agent-axiom/streamsplit). You can also build an installable archive with `npm pack`; see [installation](docs/USAGE.md#try-it) and [release readiness](docs/RELEASING.md). Licensed under [MIT](LICENSE).

docs/USAGE.md

@@ -16,7 +16,15 @@ npm run check
 
 The demo detects a broken UTF-8 decoder, reduces the failure to two chunks, replays it, and checks the fixed SSE and NDJSON versions. The example parsers are intentionally small and are not production protocol implementations.
 
-This package is **not published to the npm registry yet**. To use the verified package in another project:
+Install the published package as a development dependency in your project:
+
+```sh
+npm install --save-dev @agent-axiom/streamsplit
+```
+
+The assertion below uses the package's public import and works outside this repository. The `examples/` directory and `example:*` commands belong to a source checkout; they are not included in the npm archive.
+
+To try unreleased repository changes before publication, build and install a local archive:
 
 ```sh
 # In this repository:

test/docs.test.mjs

@@ -49,3 +49,15 @@ for (const name of ['sse', 'ndjson', 'json']) {
     }
   });
 }
+
+
+test('installation guides use the published package as a development dependency', () => {
+  const { name } = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+  const usage = readFileSync(join(root, 'docs/USAGE.md'), 'utf8');
+  const readme = readFileSync(join(root, 'README.md'), 'utf8');
+  for (const document of [readme, usage]) {
+    assert.ok(document.includes(`npm install --save-dev ${name}`));
+  }
+  assert.doesNotMatch(usage, /not published to the npm registry yet/i);
+  assert.match(usage, /not included in the npm archive/);
+});