pluribus-context 0.3.4 → 0.3.6

package/CHANGELOG.md

@@ -4,6 +4,19 @@
 
 All notable changes to Pluribus are documented here.
 
+## 0.3.6 — community review packet package-page refresh
+
+### Added
+
+- Add a community review packet with listing copy, safety/removability notes, and a disposable 60-second smoke test for reviewers, curators, and small distribution opportunities.
+
+## 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

package/README.md

@@ -105,19 +105,32 @@ 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?
@@ -135,7 +148,7 @@ npx --yes pluribus-context@latest sync --dry-run
 
 If the preview looks right, run `npx --yes pluribus-context@latest sync` to write the tool-specific files.
 
-For a fuller walkthrough, see the [Quickstart](docs/quickstart.md). To enforce generated context files in pull requests, use the [CI audit example](docs/ci-audit-example.md); to catch drift before commits leave your machine, use the [Pre-commit Audit Hook](docs/pre-commit-audit.md). If your repo already has `CLAUDE.md`, `.cursorrules`, Copilot instructions, or `AGENTS.md`, run a [Context Drift Audit](docs/context-drift-audit.md) first, try the intentionally drifted [audit example](examples/context-drift-audit/), then follow [Migrate Existing AI Context Files](docs/migrate-existing-context.md). Before committing shared or generated AI instructions, use the [Context File Review Checklist](docs/context-file-review.md). If you're deciding between Pluribus and a one-way rules converter, see [When to use Pluribus](docs/when-to-use-pluribus.md). If you are debugging "context drift" after compaction or long sessions, start with the [Context Drift Taxonomy](docs/context-drift-taxonomy.md) to separate file drift from runtime precedence drift.
+For a fuller walkthrough, see the [Quickstart](docs/quickstart.md). To enforce generated context files in pull requests, use the [CI audit example](docs/ci-audit-example.md); to catch drift before commits leave your machine, use the [Pre-commit Audit Hook](docs/pre-commit-audit.md). If your repo already has `CLAUDE.md`, `.cursorrules`, Copilot instructions, or `AGENTS.md`, run a [Context Drift Audit](docs/context-drift-audit.md) first, try the intentionally drifted [audit example](examples/context-drift-audit/), then follow [Migrate Existing AI Context Files](docs/migrate-existing-context.md). Before committing shared or generated AI instructions, use the [Context File Review Checklist](docs/context-file-review.md). If you're deciding between Pluribus and a one-way rules converter, see [When to use Pluribus](docs/when-to-use-pluribus.md). If you are debugging "context drift" after compaction or long sessions, start with the [Context Drift Taxonomy](docs/context-drift-taxonomy.md) to separate file drift from runtime precedence drift. If you are reviewing Pluribus for a list, newsletter, or tool directory, use the [Community Review Packet](docs/community-review-packet.md) for a one-line description, safety notes, and a disposable 60-second smoke test.
 
 ### Usage
 

package/docs/community-review-packet.md

@@ -0,0 +1,72 @@
+# Community review packet
+
+Use this when reviewing Pluribus for a list, newsletter, package roundup, or tool directory. It is written to be copy-pasteable without requiring private project context.
+
+## One-line description
+
+Pluribus keeps intentional AI coding context in one `pluribus.md` source of truth, then syncs or audits the tool-specific files used by Claude Code, Cursor, Copilot, OpenClaw, Windsurf, Continue, and Zed.
+
+## Short listing copy
+
+Pluribus is an open-source CLI for teams and solo developers who use multiple AI coding tools. It treats project instructions, conventions, constraints, and shared team context as versioned Markdown, then generates each tool's expected context file (`CLAUDE.md`, `.cursorrules`, Copilot instructions, `AGENTS.md`, Windsurf/Continue rules, and Zed rules). The safest first command is a read-only audit:
+
+```bash
+npx --yes pluribus-context@latest audit
+```
+
+## Why it may be useful
+
+- Reduces copy-paste drift between AI tool instruction files.
+- Lets users preview generated files with `sync --dry-run` before writing anything.
+- Supports composable local context and explicit remote imports for shared team/org guidance.
+- Provides CI/pre-commit audit paths so generated context drift is visible in code review.
+
+## Safety and removability
+
+- `audit`, `validate`, and `sync --dry-run` are read-only.
+- `init` writes only `pluribus.md` and refuses to overwrite an existing file.
+- `sync` writes only generated AI context files for the selected tools.
+- Normal `audit`, `validate`, `sync`, and `sync --dry-run` runs do not make network requests.
+- Remote imports fetch only when the user explicitly passes `--update-imports`; fetched content is pinned in `pluribus.lock.json` and cached under `.pluribus/cache/remote/`.
+- A global install can be removed with `npm uninstall -g pluribus-context`; one-off `npx --yes pluribus-context@latest ...` does not create a persistent global `pluribus` command.
+
+## 60-second review smoke
+
+Run this in a disposable directory:
+
+```bash
+mkdir pluribus-review && cd pluribus-review
+npx --yes pluribus-context@latest --version
+npx --yes pluribus-context@latest init --dry-run --name "Review" --description "Disposable review project" --tools claude,cursor,copilot
+npx --yes pluribus-context@latest init --name "Review" --description "Disposable review project" --tools claude,cursor,copilot
+npx --yes pluribus-context@latest validate
+npx --yes pluribus-context@latest sync --dry-run
+npx --yes pluribus-context@latest audit --ci --json --output pluribus-audit.json || test $? -eq 1
+```
+
+Expected result:
+
+- `--version` prints the current npm release.
+- `init --dry-run` previews `pluribus.md` without writing.
+- `init` writes `pluribus.md`.
+- `validate` succeeds.
+- `sync --dry-run` previews generated context files without writing them.
+- `audit --ci` may exit `1` before generated files are synced; that is expected when outputs are missing or drifted.
+
+## Useful links
+
+- npm package: <https://www.npmjs.com/package/pluribus-context>
+- GitHub repo: <https://github.com/caioribeiroclw-pixel/pluribus>
+- Quickstart: <https://github.com/caioribeiroclw-pixel/pluribus/blob/main/docs/quickstart.md>
+- Context drift audit guide: <https://github.com/caioribeiroclw-pixel/pluribus/blob/main/docs/context-drift-audit.md>
+- When to use Pluribus: <https://github.com/caioribeiroclw-pixel/pluribus/blob/main/docs/when-to-use-pluribus.md>
+- First-run audit feedback: <https://github.com/caioribeiroclw-pixel/pluribus/issues/new?template=audit-feedback.yml>
+
+## Feedback requested
+
+If you try it on a real repo, please avoid pasting private context or full audit JSON from non-public projects. The most useful report is:
+
+1. OS/shell and exact Pluribus version.
+2. Which context files already existed (`CLAUDE.md`, `.cursorrules`, Copilot instructions, `AGENTS.md`, etc.).
+3. Whether `audit` identified the expected missing/drifted files.
+4. Whether the next safe step was obvious (`init`, edit `pluribus.md`, `sync --dry-run`, or `sync`).

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pluribus-context",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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",

package/src/utils/version.js

@@ -1 +1 @@
-export const VERSION = '0.3.4'
+export const VERSION = '0.3.6'