From 5193359bd812944809e2d2661f80000463dad962 Mon Sep 17 00:00:00 2001
From: Roger Chappel <miscanalysis@gmail.com>
Date: Thu, 6 Aug 2026 01:28:12 +1000
Subject: [PATCH 1/3] docs: document pre-publication install path

---
 README.md | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 3d89785..35f3cd0 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,18 @@ ClipCase is a local-first TypeScript CLI for turning copied context, terminal ou
 
 ## Quick start
 
+ClipCase is not published to the npm registry yet. Until it is, build and
+install the package tarball from a clean checkout:
+
 ```sh
-npm install -g clipcase
+git clone https://github.com/rogerchappel/clipcase.git
+cd clipcase
+npm ci
+npm run build
+npm pack --pack-destination /tmp
+npm install --global --prefix /tmp/clipcase-install /tmp/clipcase-0.1.0.tgz
+export PATH="/tmp/clipcase-install/bin:$PATH"
+
 clipcase init
 clipcase new bug-login --title "Login redirect bug"
 pbpaste | clipcase add bug-login --source terminal --tag repro
@@ -138,3 +148,8 @@ npm run release:check
 ```
 
 `npm run package:smoke` verifies required package files and the installed `clipcase` CLI help.
+
+Version tags currently build a package tarball and attach it to a GitHub
+release. They do not publish ClipCase to the npm registry. The release workflow
+and this installation guidance must be updated together when registry
+publication is enabled.

From 0dd3a993defe6638b5bd280656e2d1f04940d3ce Mon Sep 17 00:00:00 2001
From: Roger Chappel <miscanalysis@gmail.com>
Date: Thu, 6 Aug 2026 01:28:40 +1000
Subject: [PATCH 2/3] ci: enforce installation release contract

---
 package.json                 |  3 ++-
 scripts/release-contract.mjs | 38 ++++++++++++++++++++++++++++++++++++
 scripts/validate.sh          |  1 +
 3 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 scripts/release-contract.mjs

diff --git a/package.json b/package.json
index e06acc5..70a1a09 100644
--- a/package.json
+++ b/package.json
@@ -29,7 +29,8 @@
     "pretest": "npm run build",
     "smoke": "npm run build && bash scripts/smoke.sh",
     "package:smoke": "node scripts/pack-smoke.mjs",
-    "release:check": "npm test && npm run check && npm run build && npm run smoke && npm run package:smoke"
+    "release:contract": "node scripts/release-contract.mjs",
+    "release:check": "npm test && npm run check && npm run build && npm run smoke && npm run package:smoke && npm run release:contract"
   },
   "keywords": [
     "cli",
diff --git a/scripts/release-contract.mjs b/scripts/release-contract.mjs
new file mode 100644
index 0000000..65babc5
--- /dev/null
+++ b/scripts/release-contract.mjs
@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+
+const readme = await readFile(new URL("../README.md", import.meta.url), "utf8");
+const releaseWorkflow = await readFile(
+  new URL("../.github/workflows/release.yml", import.meta.url),
+  "utf8"
+);
+
+const claimsRegistryInstall = /npm\s+(?:i|install)\s+(?:--global|-g)\s+clipcase(?:@\S+)?(?:\s|$)/m.test(
+  readme
+);
+const publishesToRegistry = /(?:^|\s)npm\s+publish(?:\s|$)/m.test(releaseWorkflow);
+
+if (claimsRegistryInstall && !publishesToRegistry) {
+  console.error(
+    "release contract failed: README claims a registry install, but the release workflow does not publish to npm"
+  );
+  process.exit(1);
+}
+
+const documentsTarballRelease =
+  /attach(?:es|ed|ing)? it to a GitHub\s+release/i.test(readme) &&
+  /do(?:es)? not publish ClipCase to the npm registry/i.test(readme);
+
+if (!publishesToRegistry && !documentsTarballRelease) {
+  console.error(
+    "release contract failed: README must explain that tags create GitHub tarball releases without npm publication"
+  );
+  process.exit(1);
+}
+
+console.log(
+  publishesToRegistry
+    ? "release contract passed with npm publication enabled"
+    : "release contract passed for GitHub tarball releases"
+);
diff --git a/scripts/validate.sh b/scripts/validate.sh
index 3c6a1e9..3739bf4 100755
--- a/scripts/validate.sh
+++ b/scripts/validate.sh
@@ -5,4 +5,5 @@ npm run check
 npm run build
 npm run smoke
 npm run package:smoke
+npm run release:contract
 if command -v agent-qc >/dev/null 2>&1; then agent-qc ready; else echo "agent-qc not installed; skipping"; fi

From b32edd0113f31acb701a94fa09155e1cdef5fd1d Mon Sep 17 00:00:00 2001
From: Roger Chappel <miscanalysis@gmail.com>
Date: Thu, 6 Aug 2026 01:28:57 +1000
Subject: [PATCH 3/3] docs: make tarball install disposable

---
 README.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 35f3cd0..315e9c8 100644
--- a/README.md
+++ b/README.md
@@ -12,9 +12,10 @@ git clone https://github.com/rogerchappel/clipcase.git
 cd clipcase
 npm ci
 npm run build
-npm pack --pack-destination /tmp
-npm install --global --prefix /tmp/clipcase-install /tmp/clipcase-0.1.0.tgz
-export PATH="/tmp/clipcase-install/bin:$PATH"
+CLIPCASE_TMP="$(mktemp -d)"
+CLIPCASE_TARBALL="$(npm pack --pack-destination "$CLIPCASE_TMP")"
+npm install --global --prefix "$CLIPCASE_TMP/install" "$CLIPCASE_TMP/$CLIPCASE_TARBALL"
+export PATH="$CLIPCASE_TMP/install/bin:$PATH"
 
 clipcase init
 clipcase new bug-login --title "Login redirect bug"