ci: add npm publish workflow and document release process

Publish to npm on cli-v* tags via publish-cli.yml. The workflow runs
the full test suite (unit + E2E) before publishing. Access is controlled
via GitHub tag protection rules on the cli-v* pattern.

Author: nucliweb

.github/workflows/publish-cli.yml

@@ -0,0 +1,42 @@
+name: Publish CLI
+
+on:
+  push:
+    tags:
+      - 'cli-v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run unit tests
+        run: npm run test:unit --prefix cli
+
+      - name: Install Playwright Chromium
+        run: npx playwright install --with-deps chromium
+        working-directory: cli
+
+      - name: Run E2E tests
+        run: npm run test:e2e --prefix cli
+
+      - name: Publish to npm
+        run: npm publish
+        working-directory: cli
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

README.md

@@ -142,6 +142,16 @@ Skills are compatible with [Chrome DevTools MCP](https://github.com/modelcontext
 
 **Supported agents**: Claude Code, Cursor, OpenCode, Gemini CLI, VS Code extensions, and [many more](https://agentskills.io/).
 
+## CLI
+
+The repository includes a headless CLI (`cli/`) that runs WebPerf Snippets via Playwright — useful for CI pipelines and performance budgeting without copy-pasting into DevTools.
+
+```bash
+npx webperf-snippets https://example.com --budget-lcp 2500 --budget-cls 0.1
+```
+
+See [`cli/README.md`](./cli/README.md) for installation, usage, and CI integration. The CLI is published to npm as [`webperf-snippets`](https://www.npmjs.com/package/webperf-snippets) via a tag-based release workflow — pushing a `cli-v*` tag triggers the publish pipeline.
+
 ## Documentation
 
 Visit **[webperf-snippets.nucliweb.net](https://webperf-snippets.nucliweb.net)** for the full documentation with all snippets.

cli/README.md

@@ -85,6 +85,33 @@ GitHub Actions, fail the PR if LCP exceeds 2.5s:
     npx webperf-snippets https://staging.example.com --budget-lcp 2500 --budget-cls 0.1
 ```
 
+## Publishing
+
+The CLI package is published to npm via a tag-based workflow. Publishing is explicit and intentional — it only happens when a `cli-v*` tag is pushed.
+
+### Release steps
+
+1. Bump the version in `cli/package.json`.
+2. Commit the version change.
+3. Tag and push:
+   ```bash
+   git tag cli-v0.2.0
+   git push origin cli-v0.2.0
+   ```
+4. The `publish-cli` CI job runs, executes the full test suite, and publishes to npm.
+
+### Why tag-based and not path-based
+
+An alternative is to publish automatically on every push to `main` that touches `cli/`, using a version check to skip republishes. Tag-based publishing was chosen instead because it keeps releases deliberate — a passing CI on `main` does not mean the package is ready to ship, and a tag communicates that intent explicitly.
+
+### Access control
+
+Tag protection rules restrict who can push `cli-v*` tags. Configure them under **Settings → Rules → New ruleset** in the repository, targeting the `cli-v*` tag pattern and limiting push access to admins or maintainers. This ensures only authorized collaborators can trigger a publish.
+
+### Required secret
+
+The `NPM_TOKEN` secret must be set in the repository settings with publish access to the `webperf-snippets` npm package.
+
 ## Known limitations (v0.1)
 
 - **No INP**: INP requires real user interactions. v0.2 will support synthetic interaction scripts.