pluribus-context 0.3.9 → 0.3.10

package/CHANGELOG.md

@@ -4,6 +4,37 @@
 
 All notable changes to Pluribus are documented here.
 
+### Changed
+
+- Make `discovery:smoke` report both the published npm package and the local `package.json` plus a `pendingNpmPublish` summary, so adoption/search evidence is not misread while `0.3.10` metadata is prepared but npm latest is still `0.3.9`.
+- Refresh package discovery metadata for the next npm publish by putting `CLAUDE.md`, `rules sync`, and `Copilot instructions` in the package description and guarding adjacent npm-search keywords in `release:verify`.
+- Link review/listing feedback from the README contribution CTA and CONTRIBUTING guide, and guard those links in `release:verify`, so directory maintainers and package reviewers can find the dedicated route even when they do not start from the Community Review Packet.
+- Add a dedicated review/listing feedback issue template and link it from the Community Review Packet, so directory maintainers and package reviewers can report categorization/copy/safety friction without forcing the feedback into audit or quickstart forms.
+- Replace stale current-facing `pluribus-context@0.3.3` availability claims in audit docs with `pluribus-context@latest` and guard public docs against future hard-coded package-version claims that look current.
+- Make `release:verify` detect stale local/remote `v<package version>` tags, so a prepared npm release cannot accidentally drift from its GitHub release artifact.
+- Add an exact awesome-list Markdown entry to the Community Review Packet and guard it in `release:verify`, so contextual list submissions can reuse one honest, tested line instead of rewriting category copy per channel.
+- Add a Fit and boundaries section to the Community Review Packet and guard it in `release:verify`, so reviewers can quickly distinguish Pluribus from one-tool rules managers, one-time converters, memory layers, retrieval, and agent orchestration.
+- Add license and install/run fields to the Community Review Packet's directory submission table and guard them in `release:verify`, so curators do not have to infer basic listing metadata before testing Pluribus.
+
+## 0.3.10 — discovery and reviewer routing refresh
+
+### Added
+
+- Add `npm run review:smoke` and wire it into `release:verify` so the Community Review Packet's public 60-second smoke test is exercised against `pluribus-context@latest` before release/distribution pushes.
+- Add the Community Review Packet to GitHub's issue/contact chooser and guard that link in `release:verify`, so reviewers who click “New issue” can still find directory copy, safety notes, feedback links, and the 60-second smoke test.
+- Track external distribution PRs in `discovery:smoke`, starting with the contextual `awesome-ai-coding-tools` submission, so manual listing experiments have state/mergeability/comment evidence in the adoption baseline.
+- Add explicit feedback links to the community review packet and guard them in `release:verify`, so reviewers can route audit feedback, quickstart confusion, or broader workflow notes without hunting through the repo.
+- Add recent discussion comment authors and an external-comment count to the discovery smoke report so maintainer-only discussion updates do not look like community feedback.
+- Add GitHub repo signals to the discovery smoke report so adoption/distribution checks track stars, forks, watchers, open issues, open pull requests, and discussions alongside npm search/download signals.
+- Add npm download counts to the discovery smoke report so adoption/distribution checks track search visibility and package activity together.
+- Add `npm run discovery:smoke` and `docs/discovery-smoke.md` so npm/GitHub search visibility can be measured repeatably after metadata, topic, README, or distribution-copy changes.
+
+### Changed
+
+- Surface the Community Review Packet near the top of the README and guard the reviewer shortcut copy in `release:verify`, so curators and package reviewers can find directory fields, safety notes, feedback links, and the 60-second smoke test before scanning the full docs.
+- Make the README intro say explicitly that `pluribus-context` is an AI context sync CLI and guard that positioning in `release:verify`, improving package-name/problem-query clarity for reviewers and search surfaces.
+- Extend the release smoke gate to install the packed CLI globally into a temporary prefix and verify `npm uninstall -g pluribus-context` removes the `pluribus` binary, protecting the first-run removability claim used in trust/review copy.
+
 ## 0.3.9 — npm discovery metadata refresh
 
 ### Added

package/README.md

@@ -8,10 +8,14 @@
 
 > Intentional context across every AI tool you use.
 
-Pluribus keeps project instructions, conventions, constraints, and team context in one versioned source of truth, then syncs that context into the formats each AI tool expects.
+Pluribus (`pluribus-context` on npm, `pluribus` on the command line) is an AI context sync CLI for teams and projects that use Claude Code, Cursor, GitHub Copilot, OpenClaw, Windsurf, Continue, or Zed.
+
+It keeps project instructions, conventions, constraints, and team context in one versioned source of truth, then syncs that context into the formats each AI tool expects.
 
 It is **not** a persistent memory layer, retrieval system, agent orchestrator, or agent-merging framework. Think `CLAUDE.md`, `.cursorrules`, `copilot-instructions.md`, `AGENTS.md` — one intentional context, multiple generated outputs.
 
+**Reviewer shortcut:** evaluating Pluribus for a list, newsletter, package roundup, or tool directory? Use the [Community Review Packet](docs/community-review-packet.md) for copy-paste directory submission fields, safety/removability notes, feedback links, and a disposable 60-second smoke test.
+
 ---
 
 ## The Problem
@@ -148,7 +152,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. If you are reviewing Pluribus for a list, newsletter, or tool directory, use the [Community Review Packet](docs/community-review-packet.md) for directory submission fields, a one-line description, safety notes, and a disposable 60-second smoke test.
+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 directory submission fields, a one-line description, safety notes, and a disposable 60-second smoke test. Maintainers can track package/repo discovery with the [Discovery Smoke Checks](docs/discovery-smoke.md).
 
 ### Usage
 
@@ -377,6 +381,7 @@ Follow along: [@RibeiroCaioCLW](https://x.com/RibeiroCaioCLW)
 
 If you've felt this pain, tell me about your setup. What tools do you use? How do you manage context today? What's broken?
 
+- [Review/listing feedback](https://github.com/caioribeiroclw-pixel/pluribus/issues/new?template=review-feedback.yml) — if Pluribus was hard to classify for a directory, awesome-list, newsletter, or package review
 - [Quickstart feedback](https://github.com/caioribeiroclw-pixel/pluribus/issues/new?template=quickstart-feedback.yml) — if install, validate, or dry-run felt confusing
 - [Audit feedback](https://github.com/caioribeiroclw-pixel/pluribus/issues/new?template=audit-feedback.yml) — if read-only `pluribus audit` missed drift, was noisy, or left the next step unclear
 - [Bug report](https://github.com/caioribeiroclw-pixel/pluribus/issues/new?template=bug-report.yml) — if a command failed or generated the wrong output
@@ -406,7 +411,8 @@ This project is just getting started. The best way to help right now:
 2. ⭐ Star the repo if the problem resonates
 3. 🗣️ [Open a quickstart feedback issue](https://github.com/caioribeiroclw-pixel/pluribus/issues/new?template=quickstart-feedback.yml) if anything felt confusing
 4. 🔎 [Open an audit feedback issue](https://github.com/caioribeiroclw-pixel/pluribus/issues/new?template=audit-feedback.yml) if the read-only audit missed drift or felt noisy
-5. 📣 Share with someone who maintains 3+ AI context files
+5. 🧭 [Open a review/listing feedback issue](https://github.com/caioribeiroclw-pixel/pluribus/issues/new?template=review-feedback.yml) if the category, listing copy, or safety/removability claims are unclear
+6. 📣 Share with someone who maintains 3+ AI context files
 
 Looking for first contributions? Check out the [open issues](https://github.com/caioribeiroclw-pixel/pluribus/issues). The next good contributions are CI/CD workflow examples, real-world adapter feedback, and install/quickstart friction reports.
 

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 `--github-annotations`, `--json`, `--output`, and `--ci` flags are published in `pluribus-context@0.3.3` and available through the npm `latest` tag.
+`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 available through the npm `latest` tag (`pluribus-context@latest`).
 
 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).
 

package/docs/community-review-packet.md

@@ -23,12 +23,22 @@ Use these fields for directories, awesome lists, or review forms that ask for a
 | Name | Pluribus |
 | URL | https://github.com/caioribeiroclw-pixel/pluribus |
 | npm | https://www.npmjs.com/package/pluribus-context |
+| License | MIT |
+| Install / run | `npx --yes pluribus-context@latest audit` or `npm install -g pluribus-context@latest` |
 | Category | AI coding tools / context management |
 | Tags | `claude-code`, `cursor`, `copilot`, `openclaw`, `windsurf`, `continue`, `zed`, `context-drift` |
 | One sentence | Keep one versioned AI coding context in `pluribus.md`, then audit or sync the generated files used by Claude Code, Cursor, Copilot, OpenClaw, Windsurf, Continue, and Zed. |
 | 280-char blurb | Pluribus is an open-source CLI for intentional AI coding context. It keeps project guidance in one `pluribus.md`, then audits or syncs `CLAUDE.md`, Cursor rules, Copilot instructions, `AGENTS.md`, Windsurf/Continue rules, and Zed rules. |
 | Safe first command | `npx --yes pluribus-context@latest audit` |
 
+### Awesome-list Markdown entry
+
+Use this exact line when a curated list accepts one Markdown bullet per tool:
+
+```markdown
+- [Pluribus](https://github.com/caioribeiroclw-pixel/pluribus) - Open-source CLI that keeps one versioned AI coding context in sync across Claude Code, Cursor, Copilot, OpenClaw, Windsurf, Continue, and Zed.
+```
+
 ## Why it may be useful
 
 - Reduces copy-paste drift between AI tool instruction files.
@@ -36,6 +46,19 @@ Use these fields for directories, awesome lists, or review forms that ask for a
 - 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.
 
+## Fit and boundaries
+
+Use this section when a directory, list maintainer, or reviewer asks how Pluribus differs from adjacent rules-sync or prompt-file tools.
+
+| Question | Short answer |
+| --- | --- |
+| What category is it? | AI coding context management / rules sync CLI. |
+| What is the source of truth? | `pluribus.md`, reviewed in git. |
+| What does it generate? | Tool-native context files for Claude Code, Cursor, Copilot, OpenClaw, Windsurf, Continue, and Zed. |
+| What is the safe first step? | Run `npx --yes pluribus-context@latest audit` to inspect existing context files without writing. |
+| When is another tool enough? | If you only need one tool's native rules format or a one-time converter, a smaller rules manager/converter may be enough. |
+| What is Pluribus not? | Not chat memory, retrieval, vector search, agent orchestration, or agent merging. |
+
 ## Safety and removability
 
 - `audit`, `validate`, and `sync --dry-run` are read-only.
@@ -77,6 +100,15 @@ Expected result:
 - 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 links
+
+Use the narrowest public path that matches what you tested:
+
+- Directory/listing/reviewer fit or copy feedback: <https://github.com/caioribeiroclw-pixel/pluribus/issues/new?template=review-feedback.yml>
+- Read-only audit result or unclear next step: <https://github.com/caioribeiroclw-pixel/pluribus/issues/new?template=audit-feedback.yml>
+- Quickstart/install/setup confusion: <https://github.com/caioribeiroclw-pixel/pluribus/issues/new?template=quickstart-feedback.yml>
+- Broader workflow notes about managing AI context across tools: <https://github.com/caioribeiroclw-pixel/pluribus/discussions/13>
+
 ## Feedback requested
 
 If you try it on a real repo, please do not paste secrets, private source code, credentials, customer data, or internal instructions that should not be public. Avoid pasting private context or full audit JSON from non-public projects. The most useful report is:

package/docs/context-drift-audit.md

@@ -18,7 +18,7 @@ Want to see the workflow before touching a real repo? Use the intentionally drif
 
 ## Version availability
 
-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.
+The read-only audit workflow, including `--json`, `--output <file>`, `--github-annotations`, and `--ci`, is available through the npm `latest` tag (`pluribus-context@latest`).
 
 ```bash
 npx --yes pluribus-context@latest audit --strict --json

package/docs/discovery-smoke.md

@@ -0,0 +1,40 @@
+# Discovery smoke checks
+
+Pluribus has two different discovery surfaces:
+
+1. **Registry metadata** (`npm view`) — updates quickly after publish.
+2. **Search indexes** (`npm search`, GitHub search) — update more slowly and rank results differently per query.
+
+Use this smoke when changing package keywords, repository topics, description copy, review packet copy, or distribution strategy:
+
+```bash
+npm run discovery:smoke
+```
+
+The script intentionally separates hard checks from observation:
+
+- hard check: `npm search pluribus-context` should rank `pluribus-context` at position `0`;
+- observation: `publicPackage` reports the currently published npm package, while `localPackage` reports the checked-out `package.json`, so release prep can tell whether search/download evidence is measuring the live package or an unpublished local version;
+- observation: `pendingNpmPublish`, `npmLatestMatchesLocal`, `localDescriptionPublished`, and `unpublishedKeywordCount` summarize the public-vs-local release gap before interpreting generic search visibility;
+- observation: npm download counts for `last-day`, `last-week`, and `last-month` are included so adoption signals can be logged alongside search visibility;
+- observation: generic queries such as `ai context sync`, `claude code context sync`, `context-sync ai-rules claude-md`, and `rules-sync context-files ai-agents` report rank/top results without failing;
+- observation: GitHub repository search reports whether `caioribeiroclw-pixel/pluribus` appears for package/problem queries;
+- observation: GitHub repo signals include stars, forks, watchers, latest release, open issues, open pull requests, and recent discussions so adoption loops can distinguish search visibility from real feedback;
+- observation: recent discussion comment authors and an `externalRecentDiscussionComments` summary separate maintainer-only updates from real external feedback.
+- observation: tracked external distribution PRs, such as contextual awesome-list submissions, report state/mergeability/comments so manual distribution experiments can be measured without opening multiple submissions blindly.
+
+The JSON output is meant to be pasted into activity logs without exposing secrets or local project context. Download counts can include local smoke/release installs, GitHub counts can lag indexing, and discussion comment author windows are capped to recent comments, so treat them as directional unless there is external corroboration such as new stars, issues, replies, or third-party mentions.
+
+## Current baseline
+
+As of 2026-05-17 01:01 UTC, public npm is still `pluribus-context@0.3.9` while the local checkout is preparing `0.3.10`:
+
+- `npm search pluribus-context` ranks Pluribus at position `0`.
+- `pendingNpmPublish` is expected to be `true` until npm auth/2FA allows publishing `0.3.10`; generic search results still measure the public `0.3.9` metadata, not the sharpened local `0.3.10` description/keywords.
+- npm downloads are visible through the same smoke report (`last-day`, `last-week`, `last-month`), but current values still include likely noise from release/publish/smoke activity.
+- GitHub adoption signals are visible in the same report: stars/forks/watchers, latest release, open issues, open pull requests, discussion activity, and recent external discussion-comment count.
+- External distribution tracking starts with the contextual `awesome-ai-coding-tools` PR and records whether it remains open, mergeable, commented on, or merged.
+- Generic npm queries still favor adjacent packages such as `sync-ai-context`, `ai-rules-sync`, `cursor2claude`, and `@intellectronica/ruler`.
+- That means exact-name discovery works, but problem-query discovery is still weak and should be treated as a lagging adoption metric, especially while `pendingNpmPublish` is true.
+
+Do not publish a new package only because a generic search index has not caught up. Recheck later, then change metadata or distribution copy only if the missing query is still strategically important. When `pendingNpmPublish` is true, publish/auth state must be resolved before treating local metadata changes as live discovery evidence.

package/docs/release-checklist.md

@@ -25,7 +25,7 @@ Run the consolidated release gate from the repo root:
 npm run release:verify
 ```
 
-The verifier requires a clean `main...origin/main` checkout, reports the local package version versus npm latest, classifies the npm auth state from `npm whoami` (logged in, missing auth, or invalid/stale token), smokes the currently published npm package when one exists, then runs `npm test`, `git diff --check`, `npm run release:smoke`, `npm pack --dry-run`, and `npm publish --dry-run`. If npm auth is missing or stale, the verifier still proves the package is technically ready and names the auth/2FA action left before publish.
+The verifier requires a clean `main...origin/main` checkout, reports the local package version versus npm latest, classifies the npm auth state from `npm whoami` (logged in, missing auth, or invalid/stale token), smokes the currently published npm package when one exists, then runs `npm test`, `git diff --check`, `npm run review:smoke`, `npm run release:smoke`, `npm pack --dry-run`, and `npm publish --dry-run`. If npm auth is missing or stale, the verifier still proves the package is technically ready and names the auth/2FA action left before publish.
 
 If you need to debug an individual step, run it directly:
 
@@ -33,6 +33,7 @@ If you need to debug an individual step, run it directly:
 npm run published:smoke
 npm test
 git diff --check
+npm run review:smoke
 npm run release:smoke
 npm pack --dry-run
 npm publish --dry-run

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pluribus-context",
-  "version": "0.3.9",
-  "description": "Sync intentional AI context and rules across Claude Code, Cursor, Copilot, OpenClaw, Windsurf, Continue, and Zed.",
+  "version": "0.3.10",
+  "description": "AI context/rules sync for CLAUDE.md, Cursor rules, Copilot instructions, OpenClaw, Windsurf, Continue, and Zed.",
   "type": "module",
   "homepage": "https://github.com/caioribeiroclw-pixel/pluribus#readme",
   "repository": {
@@ -30,7 +30,9 @@
     "release:smoke": "node scripts/release-smoke.js",
     "published:smoke": "node scripts/published-smoke.js",
     "release:verify": "node scripts/release-verify.js",
-    "release:publish": "node scripts/release-publish.js"
+    "release:publish": "node scripts/release-publish.js",
+    "discovery:smoke": "node scripts/discovery-smoke.js",
+    "review:smoke": "node scripts/review-smoke.js"
   },
   "keywords": [
     "agent-rules",
@@ -40,11 +42,13 @@
     "ai-agents",
     "ai-coding-agents",
     "ai-context",
+    "ai-context-sync",
     "ai-rules",
     "ai-tools",
     "aider",
     "claude",
     "claude-code",
+    "claude-context",
     "claude-md",
     "cli",
     "codex",
@@ -55,6 +59,7 @@
     "context-sync",
     "continue",
     "copilot",
+    "copilot-instructions",
     "cursor",
     "cursor-rules",
     "developer-tools",
@@ -63,7 +68,9 @@
     "rules",
     "rules-sync",
     "windsurf",
-    "zed"
+    "windsurf-rules",
+    "zed",
+    "zed-rules"
   ],
   "author": "Caio Ribeiro",
   "license": "MIT",

package/src/utils/version.js

@@ -1 +1 @@
-export const VERSION = '0.3.9'
+export const VERSION = '0.3.10'