From e7c26a0f61d5fef1843eb3f30619d0d60423f7dd Mon Sep 17 00:00:00 2001
From: Munawarx <munawar304@gmail.com>
Date: Sun, 26 Jul 2026 16:17:38 +0530
Subject: [PATCH] docs(install): document local clone+link flow and CI install
 smoke

The only install path was 'npx github:Nazim22/leadline'; package.json is
private so npm publish is not yet available. Add a documented local-install
flow (git clone + npm install + npm link) and a CI 'install-smoke' job that
proves the CLI links and runs. Also notes Node >=18 and the Linux-only exam
harness caveat. Docs/infra only; no engine/contract changes.

Co-Authored-By: Hermes Agent <noreply@hermes.ai>
---
 .github/workflows/ci.yml | 24 ++++++++++++++++++++++++
 README.md                | 12 +++++++++++-
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ef4938c..bc85691 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -58,3 +58,27 @@ jobs:
 
       - name: Run frozen benchmark
         run: npm run bench
+
+  install-smoke:
+    name: install smoke (clone + link)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Link CLI and verify the documented install path
+        run: |
+          npm link
+          leadline --help || leadline init --claude-code --dry-run
+          echo "install smoke OK"
diff --git a/README.md b/README.md
index 7078306..d8d5170 100644
--- a/README.md
+++ b/README.md
@@ -93,7 +93,17 @@ npx github:Nazim22/leadline trace --project . --session <id>  # what WOULD have
 npx github:Nazim22/leadline init --claude-code             # flip to enforce
 ```
 
-(An npm package — plain `npx leadline` — is coming; the GitHub specifier above works today.)
+(An npm package — plain `npx leadline` — is on the roadmap; the GitHub specifier above works today. For a local checkout that is always current, clone and link:)
+
+```bash
+git clone https://github.com/Nazim22/leadline.git
+cd leadline
+npm install
+npm link            # makes `leadline` available on your PATH from this checkout
+leadline init --claude-code --dry-run
+```
+
+> **Node:** requires Node ≥ 18 (CI proves 18 / 20 / 22). The exam/replay harness is Linux-only today (see `docs/REPLAY.md`); the router, hooks, and `npm run bench` are platform-independent.
 
 Dry-run mode is the benchmark: it watches your own sessions and shows you your agent’s wrong-source calls, empty receipts, and unproven “done” claims — your data, your numbers — before a single call is ever denied.