From 900dc68083509462951e493a4eef17830c2ea1f4 Mon Sep 17 00:00:00 2001
From: dKosarevsky <36589322+dKosarevsky@users.noreply.github.com>
Date: Thu, 8 Oct 2026 16:40:34 -0700
Subject: [PATCH] docs: correct published installation and distinguish checkout
 examples

---
 README.md          |  4 ++--
 docs/USAGE.md      | 10 +++++++++-
 test/docs.test.mjs | 12 ++++++++++++
 3 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 304eb02..0448089 100644
--- a/README.md
+++ b/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).
diff --git a/docs/USAGE.md b/docs/USAGE.md
index 7560e60..e16508e 100644
--- a/docs/USAGE.md
+++ b/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:
diff --git a/test/docs.test.mjs b/test/docs.test.mjs
index b4d3497..5193606 100644
--- a/test/docs.test.mjs
+++ b/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/);
+});