publish: move constitution-cli off GitHub Packages to public npm

.github/workflows/publish.yml

@@ -1,10 +1,14 @@
 name: publish
 
-# Every merge to main publishes @chinmaygit/constitution-cli to GitHub Packages —
-# IF the version is new. A merge that doesn't bump cli/package.json (kept equal to
-# the CONSTITUTION.md header version by statute) publishes nothing and still passes.
-# This mechanizes two cli/AGENTS.md statutes: "don't bump without publishing" and
-# "one version number for the whole repo" — both formerly prompt-only, now GATED.
+# Every merge to main publishes constitution-cli to the public npm
+# registry — IF the version is new. A merge that doesn't bump cli/package.json
+# (kept equal to the CONSTITUTION.md header version by statute) publishes
+# nothing and still passes. This mechanizes two cli/AGENTS.md statutes: "don't
+# bump without publishing" and "one version number for the whole repo" — both
+# formerly prompt-only, now GATED.
+#
+# Requires an NPM_TOKEN repo secret (npmjs.org automation token with publish
+# rights on @chinmaygit) — GitHub's own GITHUB_TOKEN can't publish to npmjs.org.
 
 on:
   push:
@@ -15,7 +19,6 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      packages: write
     defaults:
       run:
         working-directory: cli
@@ -25,8 +28,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-          registry-url: https://npm.pkg.github.com
-          scope: '@chinmaygit'
+          registry-url: https://registry.npmjs.org
 
       - name: Install
         run: npm ci
@@ -50,7 +52,7 @@ jobs:
 
       - name: Publish (skipped if this version is already on the registry)
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
           PKG=$(node -p "require('./package.json').name")
           V=$(node -p "require('./package.json').version")
@@ -62,16 +64,12 @@ jobs:
           echo "published $PKG@$V"
 
       - name: Verify the published tarball actually scaffolds
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         working-directory: .
         run: |
           V=$(node -p "require('./cli/package.json').version")
           mkdir -p /tmp/consumer && cd /tmp/consumer
           npm init -y >/dev/null
-          echo "@chinmaygit:registry=https://npm.pkg.github.com" > .npmrc
-          echo "//npm.pkg.github.com/:_authToken=\${NODE_AUTH_TOKEN}" >> .npmrc
-          npm install "@chinmaygit/constitution-cli@$V"
+          npm install "constitution-cli@$V"
           ./node_modules/.bin/constitution init --name CiSmoke --ratifier "CI Smoke" --agents claude
           ./node_modules/.bin/constitution audit
           test -f CONSTITUTION.md && test -d .constitution

README.md

@@ -10,8 +10,8 @@ gap between what a human intended and what the agent actually shipped, and make
 gap **checkable**.
 
 ```bash
-npm install -g @chinmaygit/constitution-cli
-cd your-product && constitution init
+npm install --save-dev constitution-cli
+cd your-product && npx constitution init
 ```
 
 → **[docs/quickstart.md](docs/quickstart.md)** for the ten-minute path.
@@ -88,7 +88,7 @@ anything.
 - `templates/` — copy-me templates (Article, Statute, ADR, experiment, compiled prompt)
 - `decisions/` — the framework's own L3 case law
 - `skills/` — the LLM-judgment skills (`define-preamble`, `harvest-articles`, `compile-prompt`, …)
-- `cli/` — the engine + installer (`@chinmaygit/constitution-cli`; see `cli/README.md`)
+- `cli/` — the engine + installer (`constitution-cli`; see `cli/README.md`)
 - `docs/` — architecture, quickstart, firewall, tone, ops
 - `registry.md` — consumers + promoted mechanisms · `BUILDLOG.md` — the overhaul's running log
 

cli/AGENTS.md

@@ -21,10 +21,11 @@ package-managed distribution mechanism, per
     distribution-mechanism change (another ADR-0001-style ruling) doesn't require
     touching prompt UX and vice versa.
 
-- **Published to GitHub Packages as `@chinmaygit/constitution-cli`** (not public npm — the
-  scope is mandatory for GitHub's npm registry, not a naming choice). A version bump in
-  `package.json` with no matching `npm publish` is a lie the registry can catch — don't
-  bump without publishing, and don't publish without bumping past what's already live.
+- **Published to the public npm registry as `constitution-cli`** (moved off GitHub
+  Packages, which required a token to install even for a public package — a platform
+  limitation, not a visibility choice). A version bump in `package.json` with no
+  matching `npm publish` is a lie the registry can catch — don't bump without
+  publishing, and don't publish without bumping past what's already live.
   · serves: general craft (documentation must not outrun reality)
   · enforced-by: CI (`.github/workflows/publish.yml` — every merge to main publishes
     any not-yet-published version automatically, then smoke-tests the published

cli/README.md

@@ -13,26 +13,16 @@ conventions for this package's own code are in [AGENTS.md](AGENTS.md), not here.
 
 ## Status
 
-Published to **GitHub Packages** as `@chinmaygit/constitution-cli` (repo:
+Published to the public **npm registry** as `constitution-cli` (repo:
 [chinmaygit/constitution_project](https://github.com/chinmaygit/constitution_project)).
-GitHub Packages requires a GitHub token (`read:packages` scope) to install — even for a
-public package, that's a GitHub platform limitation, not a visibility choice here.
+No token needed to install — GitHub Packages required one even for public packages
+(a platform limitation), which is why this moved to npmjs.org.
 
 ## Usage
 
-Add a `.npmrc` in the consuming repo (or `~/.npmrc` for a global install) pointing scoped
-installs at GitHub's registry:
-
-```
-@chinmaygit:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
-```
-
-Then, from the target product repo:
-
 ```bash
-npm install -g @chinmaygit/constitution-cli
-constitution init
+npm install --save-dev constitution-cli
+npx constitution init
 ```
 
 `constitution` with no command, `--help`, or an unrecognized command prints usage and does

cli/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@chinmaygit/constitution-cli",
+  "name": "constitution-cli",
   "version": "0.17.5",
   "description": "The constitution governance engine: scaffold, audit, firewall-gate, compile, render, and track AI-native product development",
   "license": "MIT",
@@ -23,9 +23,6 @@
   "bugs": {
     "url": "https://github.com/chinmaygit/constitution_project/issues"
   },
-  "publishConfig": {
-    "registry": "https://npm.pkg.github.com"
-  },
   "scripts": {
     "vendor": "node scripts/vendor.js",
     "prebuild": "npm run vendor",

docs/quickstart.md

@@ -5,11 +5,17 @@ Ten minutes from install to a governed task loop.
 ## 1. Install and scaffold
 
 ```bash
-npm install -g @chinmaygit/constitution-cli   # GitHub Packages; see cli/README.md for registry setup
+npm install --save-dev constitution-cli
 cd your-product
-constitution init
+npx constitution init
 ```
 
+Installed locally, pinned in `package.json`/the lockfile, rather than global — keeps the
+engine version that scaffolded and audits a repo reproducible across machines and CI. The
+commands below are shown as bare `constitution ...` for brevity; run them as
+`npx constitution ...` (or add a `package.json` script) unless `./node_modules/.bin` is on
+your `PATH`.
+
 `init` writes the law-plane skeleton (`CONSTITUTION.md`, a Governance Map in
 `AGENTS.md`, `decisions/`), the spec + templates under `.constitution/`, compiled
 skills for the agents you pick, and the ops scaffold (`.constitution/events.jsonl`