docs: make pre-publication install path executable

README.md

@@ -4,8 +4,19 @@ 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
+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"
 pbpaste | clipcase add bug-login --source terminal --tag repro
@@ -138,3 +149,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.

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",

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"
+);

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