pluribus-context 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -4,6 +4,22 @@
 
 All notable changes to Pluribus are documented here.
 
+## 0.3.5 — trust copy package-page refresh
+
+### Changed
+
+- Clarify installation, uninstallation, and network behavior in the README and quickstart so first-run reviewers can verify the CLI without guessing what persists or when remote imports make network requests.
+- Add release-gate checks for uninstall/network transparency copy before future docs or package-page updates.
+
+## 0.3.4 — npm package page README refresh prep
+
+### Changed
+
+- Replace pre-publish GitHub-tag workaround commands in README, quickstart, migration, CI audit, and drift-audit docs with the published `pluribus-context@0.3.3` npm path now that `latest` is current.
+- Let `release:verify` run as a post-publish verification gate when npm `latest` already matches `package.json`, while preserving unreleased-copy checks when `main` is ahead of npm.
+- Mark this docs-only patch as copy-paste compatible with `pluribus-context@0.3.3`, so the release gate can prepare a package-page README refresh without forcing temporary GitHub-tag workaround commands back into docs that already work on the current npm package.
+- Extend `published:smoke` to reject the stale `github:caioribeiroclw-pixel/pluribus#v0.3.3` package-page workaround once npm `latest` reaches `0.3.4`.
+
 ## 0.3.3 — Publish-window rehearsal hardening
 
 ### Changed

package/README.md

@@ -73,8 +73,6 @@ And it generates the right files for each tool:
 
 ## Getting Started
 
-> **Version note:** `pluribus audit` is published in `pluribus-context@0.3.0`. The CI-oriented audit flags and read-only init preview documented in the GitHub release tag `v0.3.3` (`--json`, `--output`, `--github-annotations`, `--ci`, `init --dry-run`) are prepared for the next npm patch release `0.3.3`; until that patch is published, use `@0.3.0` for the basic read-only audit, or use the explicit `github:...#v0.3.3` source command shown below when testing the tagged read-only preview flags.
-
 ### Pick the safe first command
 
 If your repo already has AI context files such as `CLAUDE.md`, `.cursorrules`, Copilot instructions, or `AGENTS.md`, start with the read-only audit:
@@ -88,10 +86,10 @@ It does not write files. Without `pluribus.md`, it lists existing AI context sur
 If you are starting from scratch, preview the source-of-truth scaffold first, then create it when it looks right:
 
 ```bash
-# Tagged v0.3.3 path until pluribus-context@0.3.3 is published to npm:
-npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus init --dry-run
+# Preview only; does not write files:
+npx --yes pluribus-context@latest init --dry-run
 
-# Published npm path; writes pluribus.md:
+# Write pluribus.md when the preview looks right:
 npx --yes pluribus-context@latest init
 ```
 
@@ -107,29 +105,42 @@ Pluribus is intentionally narrow about filesystem changes:
 
 When in doubt, run `npx --yes pluribus-context@latest audit` or `npx --yes pluribus-context@latest sync --dry-run` first.
 
-### Install
+### Install, uninstall, and network behavior
 
 ```bash
 # Install globally if you prefer a persistent `pluribus` command
 npm install -g pluribus-context@latest
 pluribus --help
 
-# Or clone and link locally
+# Remove the global CLI later
+npm uninstall -g pluribus-context
+```
+
+For local development:
+
+```bash
 git clone https://github.com/caioribeiroclw-pixel/pluribus.git
 cd pluribus
 npm link
+
+# Remove the local global link later
+npm unlink -g pluribus-context
 ```
 
+One-off `npx --yes pluribus-context@latest ...` commands install into npm's normal temporary cache and do not create a persistent global `pluribus` command.
+
+Pluribus does **not** make network requests during normal `audit`, `validate`, `sync`, or `sync --dry-run` runs. Network access is opt-in for remote imports only when you explicitly pass `--update-imports`; those fetches are limited to `github:`/HTTPS imports, then pinned in `pluribus.lock.json` and cached locally for deterministic offline syncs. Private GitHub imports may use `GH_TOKEN`/`GITHUB_TOKEN` or `gh auth token` during that explicit refresh, but tokens are never written to the lockfile or cache.
+
 ### 60-second smoke test
 
 Want to see exactly what gets generated before adding it to a real project?
 
 ```bash
 mkdir pluribus-demo && cd pluribus-demo
-# Tagged v0.3.3 path until pluribus-context@0.3.3 is published to npm:
-npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus init --dry-run --name "Ana" --description "A Node.js service" --tools claude,cursor,copilot
+# Preview only; does not write files:
+npx --yes pluribus-context@latest init --dry-run --name "Ana" --description "A Node.js service" --tools claude,cursor,copilot
 
-# Published npm path; writes pluribus.md:
+# Write pluribus.md when the preview looks right:
 npx --yes pluribus-context@latest init --name "Ana" --description "A Node.js service" --tools claude,cursor,copilot
 npx --yes pluribus-context@latest validate
 npx --yes pluribus-context@latest sync --dry-run
@@ -145,10 +156,10 @@ For a fuller walkthrough, see the [Quickstart](docs/quickstart.md). To enforce g
 
 ```bash
 cd your-project/
-# Tagged v0.3.3 path until pluribus-context@0.3.3 is published to npm:
-npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus init --dry-run
+# Preview only; does not write files:
+npx --yes pluribus-context@latest init --dry-run
 
-# Published npm path; writes pluribus.md:
+# Write pluribus.md when the preview looks right:
 npx --yes pluribus-context@latest init
 ```
 
@@ -157,10 +168,10 @@ The dry-run prints the scaffold without writing files. The second command create
 You can also use flags for non-interactive init, including the same dry-run preview:
 
 ```bash
-# Tagged v0.3.3 path until pluribus-context@0.3.3 is published to npm:
-npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus init --dry-run --name "Ana" --description "A background job runner" --tools claude,cursor,openclaw
+# Preview only; does not write files:
+npx --yes pluribus-context@latest init --dry-run --name "Ana" --description "A background job runner" --tools claude,cursor,openclaw
 
-# Published npm path; writes pluribus.md:
+# Write pluribus.md when the preview looks right:
 npx --yes pluribus-context@latest init --name "Ana" --description "A background job runner" --tools claude,cursor,openclaw
 ```
 
@@ -234,29 +245,25 @@ pluribus audit --strict
 In GitHub Actions, add annotations so drift appears inline in the check UI:
 
 ```bash
-# Tagged v0.3.3 path until pluribus-context@0.3.3 is published to npm:
-npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus audit --strict --github-annotations
+npx --yes pluribus-context@latest audit --strict --github-annotations
 ```
 
 For GitHub Actions, `--ci` is the shorter equivalent of `--strict --github-annotations`:
 
 ```bash
-# Tagged v0.3.3 path until pluribus-context@0.3.3 is published to npm:
-npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus audit --ci
+npx --yes pluribus-context@latest audit --ci
 ```
 
 For CI scripts, dashboards, or migration tooling, use machine-readable output:
 
 ```bash
-# Tagged v0.3.3 path until pluribus-context@0.3.3 is published to npm:
-npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus audit --strict --json
+npx --yes pluribus-context@latest audit --strict --json
 ```
 
 To save the JSON as a CI artifact while keeping stdout quiet, add `--output`:
 
 ```bash
-# Tagged v0.3.3 path until pluribus-context@0.3.3 is published to npm:
-npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus audit --strict --json --output pluribus-audit.json
+npx --yes pluribus-context@latest audit --strict --json --output pluribus-audit.json
 ```
 
 The JSON shape is documented in [`schemas/audit-result.schema.json`](schemas/audit-result.schema.json) so CI wrappers and dashboards can validate integrations without scraping human output. For copy-paste enforcement, see the [CI audit example](docs/ci-audit-example.md) and the [Pre-commit Audit Hook](docs/pre-commit-audit.md).

package/docs/ci-audit-example.md

@@ -2,7 +2,7 @@
 
 Use this when `pluribus.md` is the source of truth and generated context files should stay current in pull requests.
 
-`pluribus audit --strict` is read-only: it fails when a generated file is missing or drifted, but it does not rewrite anything in CI. The basic audit command is published in `pluribus-context@0.3.0`; the `--github-annotations`, `--json`, `--output`, and `--ci` flags below are available in the GitHub release tag `v0.3.3` while npm latest waits for the `0.3.3` publish. Until that patch is published, pin CI to `pluribus-context@0.3.0` for the strict text check, or test the new flags from the immutable GitHub tag with `--package github:caioribeiroclw-pixel/pluribus#v0.3.3`.
+`pluribus audit --strict` is read-only: it fails when a generated file is missing or drifted, but it does not rewrite anything in CI. The `--github-annotations`, `--json`, `--output`, and `--ci` flags are published in `pluribus-context@0.3.3` and available through the npm `latest` tag.
 
 Use `--ci` in GitHub Actions when you want the shortest path: it is equivalent to `--strict --github-annotations`, so drift appears inline in the check UI and the job fails on drift. Use the explicit flags when composing custom outputs; pair annotations with `--json --output pluribus-audit.json` when you want a machine-readable artifact for dashboards or review comments. The output contract is documented in [`schemas/audit-result.schema.json`](../schemas/audit-result.schema.json).
 
@@ -35,16 +35,14 @@ jobs:
           node-version: 22.x
 
       - name: Audit AI context drift
-        # Tagged v0.3.3 path until pluribus-context@0.3.3 is published to npm.
-        run: npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus audit --ci
+        run: npx --yes pluribus-context@latest audit --ci
 ```
 
 If you want JSON output as an artifact, use this variant:
 
 ```yaml
       - name: Audit AI context drift as JSON
-        # Tagged v0.3.3 path until pluribus-context@0.3.3 is published to npm.
-        run: npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus audit --ci --json --output pluribus-audit.json
+        run: npx --yes pluribus-context@latest audit --ci --json --output pluribus-audit.json
 
       - name: Upload Pluribus audit result
         if: always()
@@ -63,8 +61,8 @@ npx --yes pluribus-context@latest audit
 npx --yes pluribus-context@latest sync --dry-run
 npx --yes pluribus-context@latest sync
 npx --yes pluribus-context@latest audit --strict
-# In GitHub Actions with the tagged 0.3.3 CI flags, use:
-npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus audit --ci
+# In GitHub Actions, use the CI shorthand:
+npx --yes pluribus-context@latest audit --ci
 ```
 
 Commit `pluribus.md` and the generated files together, or document that your team regenerates generated files during setup. Do not commit `.pluribus/cache/remote/`; commit `pluribus.lock.json` when you use remote imports.

package/docs/context-drift-audit.md

@@ -18,19 +18,10 @@ Want to see the workflow before touching a real repo? Use the intentionally drif
 
 ## Version availability
 
-The basic read-only `audit` command is published in `pluribus-context@0.3.0`.
-
-The CI-oriented flags in this guide are available in the GitHub release tag `v0.3.3` while npm latest waits for the `0.3.3` publish:
-
-- `--json`
-- `--output <file>`
-- `--github-annotations`
-- `--ci`
-
-Until `0.3.3` is published to npm, use `npx --yes pluribus-context@0.3.0 audit` for the stable published audit, or run the immutable GitHub tag when you specifically want to test the new CI flags:
+The read-only audit workflow, including `--json`, `--output <file>`, `--github-annotations`, and `--ci`, is published in `pluribus-context@0.3.3` and available through the npm `latest` tag.
 
 ```bash
-npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus audit --strict --json
+npx --yes pluribus-context@latest audit --strict --json
 ```
 
 ## 1. Find AI context surfaces
@@ -123,28 +114,28 @@ After adoption, the simplest check is:
 npx --yes pluribus-context@latest audit --strict
 ```
 
-If you want GitHub Actions to show drift inline in the check UI, add `--github-annotations` from the GitHub tag install until `pluribus-context@0.3.3` is published to npm:
+If you want GitHub Actions to show drift inline in the check UI, add `--github-annotations`:
 
 ```bash
-npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus audit --strict --github-annotations
+npx --yes pluribus-context@latest audit --strict --github-annotations
 ```
 
 For GitHub Actions, `--ci` is the shorter equivalent of `--strict --github-annotations`:
 
 ```bash
-npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus audit --ci
+npx --yes pluribus-context@latest audit --ci
 ```
 
 If you want machine-readable results for CI, dashboards, or a migration script, add `--json`:
 
 ```bash
-npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus audit --strict --json
+npx --yes pluribus-context@latest audit --strict --json
 ```
 
 To save that JSON as an artifact without relying on shell redirection, add `--output`:
 
 ```bash
-npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus audit --strict --json --output pluribus-audit.json
+npx --yes pluribus-context@latest audit --strict --json --output pluribus-audit.json
 ```
 
 The JSON output includes `ok`, `source`, `results`, `summary`, and `nextStep`, so callers can fail on drift without parsing the human emoji output. The schema lives at [`schemas/audit-result.schema.json`](../schemas/audit-result.schema.json) for CI wrappers, dashboards, and migration tools that want a stable contract. `--output` writes the same JSON payload to disk and keeps stdout quiet. `--ci` is a shorthand for `--strict --github-annotations`. `--github-annotations` writes annotations to stderr, so it can be combined with `--json`/`--output` while preserving a clean artifact. See the [CI audit example](ci-audit-example.md) for a copy-paste GitHub Actions workflow and JSON artifact variant. If you want the same guard before commits leave a developer machine, use the [Pre-commit Audit Hook](pre-commit-audit.md).

package/docs/migrate-existing-context.md

@@ -51,16 +51,16 @@ Move project facts and shared conventions into `pluribus.md`. Keep tool-specific
 
 ## 2. Preview and scaffold `pluribus.md`
 
-Preview the scaffold before writing a new source file. `init --dry-run` is prepared for `pluribus-context@0.3.3`; until that patch is published, use the GitHub tag install command for the preview:
+Preview the scaffold before writing a new source file:
 
 ```bash
-npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus init --dry-run \
+npx --yes pluribus-context@latest init --dry-run \
   --name "Your project" \
   --description "What this repo does" \
   --tools claude,cursor,copilot,openclaw
 ```
 
-When the preview looks right, create `pluribus.md` from the published npm package:
+When the preview looks right, create `pluribus.md`:
 
 ```bash
 npx --yes pluribus-context@latest init \

package/docs/quickstart.md

@@ -18,6 +18,20 @@ The safest path is audit → validate → `sync --dry-run` → `sync`. The first
 
 Remote imports do not refresh silently; Pluribus writes `pluribus.lock.json` and `.pluribus/cache/remote/` only when you explicitly pass `--update-imports`.
 
+## Install, uninstall, and network behavior
+
+For one-off use, keep using `npx --yes pluribus-context@latest ...`; npm stores that in its normal temporary cache and does not create a persistent global `pluribus` command.
+
+If you want a persistent CLI:
+
+```bash
+npm install -g pluribus-context@latest
+pluribus --help
+npm uninstall -g pluribus-context
+```
+
+Normal `audit`, `validate`, `sync`, and `sync --dry-run` runs do not make network requests. Network access only happens when remote imports are present and you explicitly pass `--update-imports`; Pluribus then fetches `github:`/HTTPS imports, pins them in `pluribus.lock.json`, and uses the local cache for later offline syncs. Private GitHub imports can use `GH_TOKEN`/`GITHUB_TOKEN` or `gh auth token` during that explicit refresh, but tokens are never stored in the lockfile or cache.
+
 ## 1. Create a disposable demo project
 
 ```bash
@@ -27,16 +41,16 @@ cd pluribus-demo
 
 ## 2. Preview and scaffold context
 
-Start read-only so you can see the template before writing a file. `init --dry-run` is prepared for `pluribus-context@0.3.3`; until that patch is published, use the GitHub tag install command for the preview:
+Start read-only so you can see the template before writing a file:
 
 ```bash
-npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus init --dry-run \
+npx --yes pluribus-context@latest init --dry-run \
   --name "Ana" \
   --description "A Node.js service" \
   --tools claude,cursor,copilot
 ```
 
-When the scaffold looks right, create it from the published npm package:
+When the scaffold looks right, create it:
 
 ```bash
 npx --yes pluribus-context@latest init \

package/examples/github-actions/pluribus-audit.yml

@@ -22,5 +22,4 @@ jobs:
           node-version: 22.x
 
       - name: Audit AI context drift
-        # Tagged v0.3.3 path until pluribus-context@0.3.3 is published to npm.
-        run: npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus audit --ci
+        run: npx --yes pluribus-context@latest audit --ci

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pluribus-context",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Sync intentional AI context and rules across Claude Code, Cursor, Copilot, OpenClaw, Windsurf, Continue, and Zed.",
   "type": "module",
   "homepage": "https://github.com/caioribeiroclw-pixel/pluribus#readme",
@@ -63,5 +63,8 @@
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"
+  },
+  "pluribusRelease": {
+    "publishedCommandMinimumVersion": "0.3.3"
   }
 }

package/src/utils/version.js

@@ -1 +1 @@
-export const VERSION = '0.3.3'
+export const VERSION = '0.3.5'