From 507295782257f8f93c0f41a1d5d9c9beba049e21 Mon Sep 17 00:00:00 2001
From: Roger Chappel <miscanalysis@gmail.com>
Date: Sun, 2 Aug 2026 00:59:12 +1000
Subject: [PATCH 1/3] docs: document source tarball installation

---
 README.md | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 5ab3f93..ce00779 100644
--- a/README.md
+++ b/README.md
@@ -32,10 +32,21 @@ What it does **not** promise yet:
 
 ## Install
 
+`@bargekit/core` is **not published to npm yet**. Install it from a source
+checkout and a locally built tarball:
+
 ```sh
-npm install @bargekit/core
+git clone https://github.com/rogerchappel/bargekit.git bargekit
+npm --prefix bargekit ci
+npm pack ./bargekit
+npm install ./bargekit-core-0.1.0.tgz
 ```
 
+The final command installs the same package contents that a future registry
+release will contain. Run it from the consumer project where you want to use
+BargeKit. Contributors working directly in the checkout can run commands with
+`npm --prefix bargekit run <script>` after `npm ci`.
+
 ## Quick start
 
 ```js

From 02eb27242ad5e9e4662a5d4f39f9844127a6dc81 Mon Sep 17 00:00:00 2001
From: Roger Chappel <miscanalysis@gmail.com>
Date: Sun, 2 Aug 2026 00:59:39 +1000
Subject: [PATCH 2/3] test: verify documented package installation

---
 scripts/verify-install-docs.mjs | 58 +++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 scripts/verify-install-docs.mjs

diff --git a/scripts/verify-install-docs.mjs b/scripts/verify-install-docs.mjs
new file mode 100644
index 0000000..6b70a23
--- /dev/null
+++ b/scripts/verify-install-docs.mjs
@@ -0,0 +1,58 @@
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const projectRoot = new URL('..', import.meta.url);
+const readme = readFileSync(new URL('../README.md', import.meta.url), 'utf8');
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const escapedName = pkg.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const registryInstall = new RegExp(`npm\\s+(?:i|install)\\s+${escapedName}(?:[@\\s]|$)`);
+const expectedTarball = `${pkg.name.replace(/^@/, '').replace('/', '-')}-${pkg.version}.tgz`;
+
+if (!readme.includes(`${pkg.name}\` is **not published to npm yet**`)) {
+  throw new Error(`README.md must prominently state that ${pkg.name} is not published`);
+}
+if (registryInstall.test(readme)) {
+  throw new Error(`README.md presents unavailable registry package ${pkg.name} as installable`);
+}
+for (const command of [
+  'npm --prefix bargekit ci',
+  'npm pack ./bargekit',
+  `npm install ./${expectedTarball}`
+]) {
+  if (!readme.includes(command)) {
+    throw new Error(`README.md is missing verified install command: ${command}`);
+  }
+}
+
+const consumerDir = mkdtempSync(join(tmpdir(), 'bargekit-install-docs-'));
+
+try {
+  const packResult = JSON.parse(execFileSync(
+    'npm',
+    ['pack', '--json', '--pack-destination', consumerDir],
+    { cwd: projectRoot, encoding: 'utf8' }
+  ));
+  const tarballPath = join(consumerDir, packResult[0].filename);
+
+  if (packResult[0].filename !== expectedTarball) {
+    throw new Error(`README tarball ${expectedTarball} does not match ${packResult[0].filename}`);
+  }
+
+  writeFileSync(join(consumerDir, 'package.json'), JSON.stringify({ private: true, type: 'module' }));
+  execFileSync(
+    'npm',
+    ['install', '--ignore-scripts', '--no-audit', '--no-fund', tarballPath],
+    { cwd: consumerDir, stdio: 'inherit' }
+  );
+  execFileSync(
+    'node',
+    ['--input-type=module', '--eval', `await import(${JSON.stringify(pkg.name)})`],
+    { cwd: consumerDir, stdio: 'inherit' }
+  );
+
+  console.log(`verified README installation from ${packResult[0].filename}`);
+} finally {
+  rmSync(consumerDir, { recursive: true, force: true });
+}

From 3e6bed36fba10000de2cdb309c70682f1f299008 Mon Sep 17 00:00:00 2001
From: Roger Chappel <miscanalysis@gmail.com>
Date: Sun, 2 Aug 2026 00:59:52 +1000
Subject: [PATCH 3/3] chore: gate releases on install documentation

---
 package.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 972001b..e5b251c 100644
--- a/package.json
+++ b/package.json
@@ -34,8 +34,9 @@
     "test": "node --test",
     "typecheck": "tsc --project tsconfig.json",
     "build": "node scripts/build.mjs",
+    "package:install-docs": "node scripts/verify-install-docs.mjs",
     "package:imports": "node scripts/verify-documented-imports.mjs",
-    "package:smoke": "node scripts/verify-package.mjs && npm run package:imports && npm pack --dry-run",
+    "package:smoke": "node scripts/verify-package.mjs && npm run package:install-docs && npm run package:imports && npm pack --dry-run",
     "release:check": "npm run check && npm test && npm run typecheck && npm run build && npm run smoke && npm run package:smoke",
     "smoke": "node test/fixtures.test.js",
     "lint": "npm run check"