pluribus-context 0.2.0 → 0.3.3

package/CHANGELOG.md

@@ -1,7 +1,111 @@
 # Changelog
 
+## [Unreleased]
+
 All notable changes to Pluribus are documented here.
 
+## 0.3.3 — Publish-window rehearsal hardening
+
+### Changed
+
+- Make the guarded `release:publish -- --dry-run` rehearsal check the same Git tag/HEAD alignment before any live OTP window, so tag drift is caught without touching npm.
+- Carry the pending source-install documentation forward to the immutable GitHub `v0.3.3` tag while npm `latest` remains `0.3.0`.
+
+## 0.3.2 — Release artifact reconciliation
+
+### Changed
+
+- Reconcile the npm publish target after the GitHub `v0.3.1` tag drifted from `main`: bump the pending npm release to `0.3.2` so the next publish can map to a fresh immutable GitHub tag instead of reusing the older `v0.3.1` artifact.
+- Guard `release:publish` against publishing an npm package version from a different commit than its matching GitHub release tag.
+- Keep temporary source-install documentation pinned to the immutable GitHub release tag for the package version being prepared while npm `latest` remains `0.3.0`.
+
+## 0.3.1 — npm README cleanup
+
+### Changed
+
+- Pin temporary source-install documentation to the immutable GitHub release tag `v0.3.2` instead of `main` while npm `latest` remains `0.3.0`, and make the release verifier accept the versioned tag path for unreleased `0.3.2` commands.
+- Block moving GitHub source-install references in docs, examples, issue templates, and changelog while npm `latest` is behind the local package, so partial-release copy-paste paths stay tied to the immutable tag.
+- Clarify the npm 2FA publish path in the release checklist, including the guarded `npm run release:publish -- --otp <one-time-code>` command and the rule to pause distribution if a GitHub release exists before npm `latest` is updated.
+- Verify that `docs/pre-commit-audit.md` embeds the same hook body as `examples/git-hooks/pre-commit`, so the local copy-paste guard and packaged git-hook example cannot drift into different audit commands.
+- Verify that `docs/ci-audit-example.md` includes an exact copy of `examples/github-actions/pluribus-audit.yml`, so the copy-paste CI guide and packaged workflow example cannot drift into different audit commands.
+- Run the full `npm run release:verify` gate in CI, with CI-safe detached checkout handling, so local-only release guards for docs, package metadata, npm smoke, tarball smoke, and publish dry-run cannot drift behind the public pipeline.
+- Verify that docs and contributor-facing GitHub issue-template links point to existing `.github/ISSUE_TEMPLATE` files, and that every public feedback template is linked somewhere in the docs, so first-run feedback paths cannot silently 404 or disappear.
+- Make `npm run release:publish` require the public `latest` dist-tag and verify that `npm view pluribus-context version` matches the just-published package before running `published:smoke`, and verify the publish script syntax in `release:verify`, so a publish under the wrong tag cannot look successful.
+- Republish the post-0.3.0 README/docs cleanup so the npm package page no longer tells users that `audit` requires a source install or that npm latest may still be `0.2.0`.
+- Clarify first-run write safety in the README and quickstart: `audit`, `validate`, and `sync --dry-run` are read-only; `init` writes only `pluribus.md`; `sync` writes only generated AI context files; remote import cache/lock writes require explicit `--update-imports`.
+- Keep the published path explicit: `npx --yes pluribus-context@latest audit` is now the default first-run check.
+- Clarify when Pluribus complements dedicated context linters/drift auditors versus replacing one-way sync maintenance.
+- Expand package keywords for discoverability around `context-drift`, `AGENTS.md`, Cursor rules, and AI coding agents.
+- Add a dedicated GitHub issue template for read-only `pluribus audit` feedback from real repos, plus links to the audit guide and workflow discussion.
+- Make quickstart and audit feedback templates point to the current published `npx --yes pluribus-context@latest ...` commands so first-run reports are easier to reproduce.
+- Clarify that Pluribus detects file-level output drift, not runtime precedence issues where a tool deprioritizes a correct context file after compaction/summarization.
+- Add a lightweight runtime-loading sanity check for users who want to confirm a generated context file is actually loaded before relying on it.
+- Add a context drift taxonomy that separates file-level output drift, source-of-truth drift, runtime loading/precedence drift, and behavioral drift so users can choose the right check before adopting Pluribus.
+- Add `pluribus audit --json` so CI jobs, smoke scripts, and external tools can consume drift results without parsing emoji/text output.
+- Add `pluribus audit --github-annotations` for inline GitHub Actions check annotations when generated context files are missing or drifted.
+- Add `pluribus audit --ci` as a shortcut for `--strict --github-annotations` in GitHub Actions.
+- Add `schemas/audit-result.schema.json` to make the `pluribus audit --json` contract explicit for CI wrappers, dashboards, and migration tools.
+- Add `pluribus audit --json --output <file>` so CI jobs can save audit results as artifacts without shell redirection or noisy stdout.
+- Add a copy-paste CI audit guide and GitHub Actions example for enforcing generated context files in pull requests.
+- Add a pre-commit audit guide and sample git hook for catching context drift before commits leave a developer machine.
+- Make the README and quickstart choose between two safe first commands: read-only `audit` for existing repos and `init` for brand-new repos.
+- Normalize one-off `npx` examples to `npx --yes pluribus-context@latest ...` so copy-paste docs do not pause on npm's install prompt or rely on implicit latest resolution.
+- Add explicit version-availability notes while `main` documents `0.3.2` audit CI flags and `init --dry-run`, while npm latest remains `0.3.0`.
+- Use exact `github:caioribeiroclw-pixel/pluribus#v0.3.2` tag-install commands for `init --dry-run` previews so users do not accidentally run npm `0.3.0` commands that still write `pluribus.md`.
+- Use exact `github:caioribeiroclw-pixel/pluribus#v0.3.2` tag-install commands for `audit --ci`, `--json`, `--output`, and `--github-annotations` docs and examples until `0.3.2` is published to npm, so CI copy-paste paths do not imply those flags are available in npm `0.3.0`.
+- Use `audit --ci` in the copy-paste GitHub Actions example to reduce command length.
+- Clarify the README vision so the source of truth is `pluribus.md` plus optional `# @import` files, not an obsolete multi-file `pluribus/` directory layout.
+- Add `pluribus init --dry-run` so first-time users can preview the `pluribus.md` scaffold before writing files.
+- Add `npm run release:verify` to run the full release gate and report whether npm auth is the remaining publish blocker.
+- Expand `npm run release:smoke` to verify the first-run `init --dry-run` preview and the copy-paste `audit --ci --json --output` path from the packaged tarball.
+- Add `npm run published:smoke` to verify the currently published npm `latest` package still has a working public first-run path (`--version`, `--help`, read-only `audit`, `init`, `validate`, and `sync --dry-run`).
+- Run the published npm smoke from `npm run release:verify` whenever a published package exists, so release readiness checks also validate the package users can install today.
+- Extend the release verification guardrail to catch bare `pluribus ...` copy-paste examples with unreleased `init --dry-run` or CI/JSON audit flags while npm latest is still behind `main`.
+- Make `npm run release:verify` distinguish missing npm auth from invalid/stale configured tokens, so the 0.3.2 publish path points to the right remediation without exposing credentials.
+- Reject unknown CLI options per command before executing, so typoed or not-yet-published flags fail safely instead of being silently ignored.
+- Make the packaged release smoke verify that unknown init flags fail without creating `pluribus.md`, so fail-safe option parsing is tested from the installed tarball, not only unit tests.
+- Remove the unsupported `init --force` flag from the release smoke so release checks only exercise documented CLI behavior.
+- Remove the same unsupported `init --force` flag from the published npm smoke so post-publish validation stays compatible with fail-safe unknown-option parsing.
+- Make the published npm smoke verify fail-safe unknown-option parsing after `0.3.2` is published, so post-publish validation catches a regression back to silently ignored CLI flags.
+- Update the bug report issue template to use non-interactive `pluribus-context@latest` reproduction commands and a current version placeholder, reducing stale first-run reports.
+- Standardize README/docs/examples on `npx --yes pluribus-context@latest ...` for published commands and extend the release guard so unreleased flags are blocked with or without `@latest` while npm latest is behind `main`.
+- Make `npm run published:smoke` verify the npm package README after `0.3.2` is published, catching stale package-page copy like `npx pluribus-context init` before future distribution pushes.
+- Add `npm run release:publish` as the guarded publish path: it runs the full release verification before publishing, refuses credential-like CLI arguments, and runs the published npm smoke after a real publish.
+- Extend `npm run release:verify` to check docs, examples, and issue templates for reproducible published npm commands (`npx --yes pluribus-context@latest ...`) and unreleased flags while npm latest is still behind `main`.
+- Include `CONTRIBUTING.md` in the same release verification copy-paste scan, and update its audit feedback command to the reproducible `npx --yes pluribus-context@latest ...` form.
+- Link audit feedback directly from the README/npm package page and make the published README smoke guard the quickstart + audit feedback paths.
+- Link quickstart and audit docs directly to their issue templates, and verify those feedback paths in the release gate so first-run users do not have to choose a generic issue manually.
+- Expand npm discovery keywords around agent rules, AI context, Codex/Aider, and drift detection so the package metadata matches the searches that surface adjacent tools.
+- Rewrite the npm package description for search-result clarity and verify core discovery metadata in the release gate before publishing.
+- Make the published npm smoke verify discovery description/keywords after `0.3.2` is published, so post-publish validation catches stale registry metadata before distribution pushes.
+- Clarify the "When to use Pluribus" guide for users comparing adjacent rules-sync packages, with a sharper split between lightweight rules sync, tool-native prompt managers, one-way converters, and Pluribus' source-of-truth plus audit workflow.
+- Make the published npm smoke verify that the package README keeps a visible path to the "When to use Pluribus" comparison guide after `0.3.2` is published.
+- Run packaged CLI and published npm smoke checks in CI, so distribution regressions are caught on every push instead of only during local release prep.
+- Surface npm weekly downloads and CI status badges in the README/npm package page, and verify those trust/distribution badges in the release and published smoke gates.
+- Surface the audit feedback issue template directly from `pluribus audit` text and JSON output, so noisy first-run results can turn into structured reports without searching the docs.
+- Verify the audit feedback link in packaged and published smoke checks, so the CLI feedback loop cannot disappear from the installed artifact unnoticed.
+- Make global install examples explicit with `npm install -g pluribus-context@latest`, and have the release gate block ambiguous global install copy-paste commands.
+- Keep `pluribus --help` in sync with the actual built-in tool adapters, and verify that in release/published smoke checks, so first-run users see Copilot, Windsurf, Continue, and Zed as supported `--tools` values instead of the original three-tool default.
+- Add the full built-in adapter list to the quickstart and verify it in the release gate, so users can discover OpenClaw, Windsurf, Continue, and Zed before deciding which `--tools` values to try.
+- Make issue templates ask for the exact `--version` output instead of a hard-coded version placeholder, and verify that guard in the release gate so feedback stays accurate while npm latest and `main` differ.
+- Align `CONTRIBUTING.md` with the current built-in adapter list and integration request template, and verify that contributor-facing adapter guidance does not drift behind the CLI.
+- Verify all built-in adapter outputs in packaged and published smoke checks, so docs/help cannot claim OpenClaw, Windsurf, Continue, or Zed support while the installed artifact fails to generate their files.
+- Verify README/npm package-page adapter output copy in release and published smoke checks, so the top-of-funnel landing page cannot regress to the old three-tool story while the CLI supports more adapters.
+- Verify that relative links from the README/npm package page point to files included in the npm tarball, so published docs links do not break after packaging.
+- Extend packaged Markdown link verification beyond the README to docs/spec/examples in the npm tarball, so follow-on package-page navigation cannot drift to missing files.
+
+## 0.3.0 — Audit workflow and first-run docs alignment
+
+### Added
+
+- Add `pluribus audit`, a read-only command that compares generated tool files with `pluribus.md`, reports missing or drifted outputs, supports `--strict` for CI, and scans existing AI context files when a project has not adopted Pluribus yet.
+- Add first-run docs for quickstart, context drift audit, existing context migration, context-file review, when to use Pluribus versus one-way converters, and issue templates so early users can report install, adapter, security-review, and migration friction with concrete details.
+
+### Changed
+
+- Align the package README for the npm publish so the npm package page shows the real `npx --yes pluribus-context` install path, npm badge, 60-second smoke test, `audit` workflow, and published-status roadmap.
+- Replace temporary source-install notes with the published `pluribus-context@0.3.0` audit path.
+
 ## 0.2.0 — Package-ready CLI release
 
 Pluribus 0.2.0 is the first npm-ready release of the CLI for keeping intentional AI context in one versioned source and syncing it to the files each tool expects. It supersedes the earlier GitHub-only v0.1.0 alpha release from March.

package/README.md

@@ -1,5 +1,8 @@
 # Pluribus
 
+[![npm version](https://img.shields.io/npm/v/pluribus-context?style=flat-square)](https://www.npmjs.com/package/pluribus-context)
+[![npm downloads](https://img.shields.io/npm/dw/pluribus-context?style=flat-square)](https://www.npmjs.com/package/pluribus-context)
+[![CI](https://img.shields.io/github/actions/workflow/status/caioribeiroclw-pixel/pluribus/ci.yml?branch=main&style=flat-square&label=ci)](https://github.com/caioribeiroclw-pixel/pluribus/actions/workflows/ci.yml)
 [![Building in Public](https://img.shields.io/badge/building-in%20public-orange?style=flat-square)](https://x.com/RibeiroCaioCLW)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
 
@@ -32,20 +35,21 @@ You end up maintaining **5+ files** that say roughly the same thing — your pro
 
 **Pluribus** is a universal format for intentional context in AI-assisted development.
 
-Write your project context **once**, in simple `.md` files. Pluribus syncs it to every tool you use — formatted exactly how each tool expects it.
+Write your project context **once**, in `pluribus.md`. Keep it as a single file for small projects, or compose shared team/org Markdown with `# @import` when the context needs to be reused.
 
-```
-pluribus/
-├── context.md        # Your project: stack, architecture, conventions
-├── identity.md       # Who you are, your preferences, tone
-├── skills.md         # What your AI should be good at
-└── rules.md          # Guardrails and constraints
+```text
+your-project/
+├── pluribus.md                  # source of truth
+└── shared/
+    ├── team-context.md          # optional imported conventions
+    └── security-constraints.md  # optional imported guardrails
 ```
 
-Then:
+Then preview or sync:
 
 ```bash
-npx pluribus-context sync
+npx --yes pluribus-context@latest sync --dry-run
+npx --yes pluribus-context@latest sync
 ```
 
 And it generates the right files for each tool:
@@ -69,14 +73,46 @@ And it generates the right files for each tool:
 
 ## Getting Started
 
-### Install
+> **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:
+
+```bash
+npx --yes pluribus-context@latest audit
+```
+
+It does not write files. Without `pluribus.md`, it lists existing AI context surfaces so you can decide what to migrate. With `pluribus.md`, it reports generated files that are missing or drifted.
+
+If you are starting from scratch, preview the source-of-truth scaffold first, then create it when it looks right:
 
 ```bash
-# From npm (once published)
-npm install -g pluribus-context
+# 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
+
+# Published npm path; writes pluribus.md:
+npx --yes pluribus-context@latest init
+```
+
+### What Pluribus writes
+
+Pluribus is intentionally narrow about filesystem changes:
+
+- `audit`, `validate`, and `sync --dry-run` are read-only.
+- `init` writes `pluribus.md` only. If that file already exists, it refuses to overwrite it.
+- `sync` writes only the configured/generated AI context files such as `CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`, `AGENTS.md`, Windsurf/Continue rules, and `.rules`.
+- Generated files include a `Generated by Pluribus ... do not edit manually` header so drift is easy to spot in review.
+- Remote imports only touch `pluribus.lock.json` and `.pluribus/cache/remote/` when you explicitly pass `--update-imports`.
 
-# Or run directly with npx
-npx pluribus-context
+When in doubt, run `npx --yes pluribus-context@latest audit` or `npx --yes pluribus-context@latest sync --dry-run` first.
+
+### Install
+
+```bash
+# Install globally if you prefer a persistent `pluribus` command
+npm install -g pluribus-context@latest
+pluribus --help
 
 # Or clone and link locally
 git clone https://github.com/caioribeiroclw-pixel/pluribus.git
@@ -84,21 +120,48 @@ cd pluribus
 npm link
 ```
 
+### 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
+
+# Published npm path; writes pluribus.md:
+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
+```
+
+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.
+
 ### Usage
 
 **1. Initialize your context file**
 
 ```bash
 cd your-project/
-pluribus init
+# 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
+
+# Published npm path; writes pluribus.md:
+npx --yes pluribus-context@latest init
 ```
 
-This creates `pluribus.md` with all required sections scaffolded. Fill in your project context.
+The dry-run prints the scaffold without writing files. The second command creates `pluribus.md` with all required sections scaffolded. Fill in your project context.
 
-You can also use flags for non-interactive init:
+You can also use flags for non-interactive init, including the same dry-run preview:
 
 ```bash
-pluribus init --name "Ana" --description "A background job runner" --tools claude,cursor,openclaw
+# 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
+
+# Published npm path; writes pluribus.md:
+npx --yes pluribus-context@latest init --name "Ana" --description "A background job runner" --tools claude,cursor,openclaw
 ```
 
 **2. Edit `pluribus.md`**
@@ -156,7 +219,51 @@ If you use remote imports and want to refresh the lock/cache while validating:
 pluribus validate --update-imports
 ```
 
-**5. Sync to all your tools**
+**5. Audit generated files before syncing**
+
+```bash
+pluribus audit
+```
+
+This is read-only. It compares existing generated files with what `pluribus.md` would produce, reports missing or drifted outputs, and can run in CI with `--strict`:
+
+```bash
+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
+```
+
+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
+```
+
+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
+```
+
+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
+```
+
+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).
+
+If your project does not have `pluribus.md` yet, `pluribus audit` scans for known AI context files (`CLAUDE.md`, `.cursorrules`, Copilot instructions, `AGENTS.md`, Windsurf, Continue, Zed) so you know what to migrate.
+
+**6. Sync to all your tools**
 
 ```bash
 pluribus sync
@@ -253,7 +360,7 @@ See `spec/skills-format.md` for the skill file format.
 - [x] Remote composable contexts MVP (explicit `--update-imports`, public GitHub/HTTPS, safety limits)
 - [x] Remote imports hardening (lockfile/cache/digest offline mode, optional GitHub auth, and CI coverage)
 - [ ] CI/CD: auto-sync on commit
-- [ ] Published to npm
+- [x] Published to npm as [`pluribus-context`](https://www.npmjs.com/package/pluribus-context)
 
 ## Building in Public
 
@@ -261,10 +368,19 @@ I'm documenting every step of building Pluribus — the decisions, the trade-off
 
 Follow along: [@RibeiroCaioCLW](https://x.com/RibeiroCaioCLW)
 
-If you've felt this pain, [open an issue](https://github.com/caioribeiroclw-pixel/pluribus/issues) and tell me about your setup. What tools do you use? How do you manage context today? What's broken?
+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?
+
+- [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
+- [Tool integration request](https://github.com/caioribeiroclw-pixel/pluribus/issues/new?template=integration-request.yml) — if another AI tool should be supported
 
 ## Docs
 
+- [Quickstart](docs/quickstart.md) — first install, validation, dry-run preview, and common friction
+- [Migrate Existing AI Context Files](docs/migrate-existing-context.md) — move from `CLAUDE.md`, `.cursorrules`, Copilot instructions, or `AGENTS.md` to one source of truth
+- [When to use Pluribus](docs/when-to-use-pluribus.md) — choose between sync, one-way conversion, and tool-native context files
+- [Context File Review Checklist](docs/context-file-review.md) — review AI instructions as supply-chain artifacts before committing generated context
 - [OpenClaw Integration](docs/openclaw-integration.md) — how Pluribus generates `AGENTS.md` for OpenClaw
 - [Composable Contexts](docs/composable-contexts.md) — local/remote imports, merge behavior, and safety rules
 - [Remote Composable Context Imports](docs/remote-composable-context-imports.md) — design notes for lockfile/cache/auth hardening
@@ -279,11 +395,13 @@ If you've felt this pain, [open an issue](https://github.com/caioribeiroclw-pixe
 
 This project is just getting started. The best way to help right now:
 
-1. ⭐ Star the repo if the problem resonates
-2. 🗣️ [Open an issue](https://github.com/caioribeiroclw-pixel/pluribus/issues) describing your context management pain
-3. 📣 Share with someone who maintains 3+ AI context files
+1. Try the 60-second smoke test above in a throwaway directory
+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
 
-Looking for first contributions? Check out the [open issues](https://github.com/caioribeiroclw-pixel/pluribus/issues). The next good contributions are release polish, CI/CD workflow examples, and real-world adapter feedback.
+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.
 
 ## License
 

package/bin/pluribus.js

@@ -9,9 +9,13 @@ import { runInit } from '../src/commands/init.js'
 import { runSync } from '../src/commands/sync.js'
 import { runValidate } from '../src/commands/validate.js'
 import { runWatch } from '../src/commands/watch.js'
+import { runAudit } from '../src/commands/audit.js'
 import { parseArgs } from '../src/utils/args.js'
+import { SUPPORTED_TOOLS } from '../src/skills/built-in.js'
 import { VERSION } from '../src/utils/version.js'
 
+const supportedToolsList = SUPPORTED_TOOLS.join(',')
+
 const HELP = `
 Pluribus v${VERSION} — Write your AI context once. Sync it to every tool.
 
@@ -22,13 +26,15 @@ COMMANDS
   init      Create a pluribus.md file in the current directory
   sync      Read pluribus.md and generate tool-specific output files
   validate  Validate pluribus.md before syncing
+  audit     Compare generated tool files with pluribus.md without writing
   watch     Watch pluribus.md and auto-sync after changes
   help      Show this help message
 
 OPTIONS (init)
   --name          Project/author name
   --description   One-line project description
-  --tools         Comma-separated list of tools to enable (claude,cursor,openclaw)
+  --tools         Comma-separated list of tools to enable (${supportedToolsList})
+  --dry-run       Preview the scaffold without writing pluribus.md
 
 OPTIONS (sync)
   --dry-run       Preview output without writing files
@@ -40,6 +46,16 @@ OPTIONS (validate)
   --source        Path to pluribus.md (default: ./pluribus.md)
   --update-imports  Refresh remote github:/https:// imports before validating
 
+OPTIONS (audit)
+  --source        Path to pluribus.md (default: ./pluribus.md)
+  --tools         Override which tools to audit (comma-separated)
+  --update-imports  Refresh remote github:/https:// imports before auditing
+  --strict        Exit non-zero when generated files are missing or drifted
+  --ci            Shortcut for --strict --github-annotations
+  --json          Print machine-readable audit results
+  --output        Write --json results to a file instead of stdout
+  --github-annotations  Print GitHub Actions annotations for drift/missing outputs
+
 OPTIONS (watch)
   --source        Path to pluribus.md (default: ./pluribus.md)
   --tools         Override which tools to sync (comma-separated)
@@ -49,18 +65,56 @@ OPTIONS (watch)
 
 EXAMPLES
   pluribus init
+  pluribus init --dry-run
   pluribus init --name "Ana" --description "A task manager" --tools claude,cursor
   pluribus sync
   pluribus sync --dry-run
   pluribus sync --tools claude,openclaw
   pluribus sync --update-imports
   pluribus validate
+  pluribus audit
+  pluribus audit --strict
+  pluribus audit --ci
+  pluribus audit --json
+  pluribus audit --strict --json --output pluribus-audit.json
+  pluribus audit --strict --github-annotations
   pluribus watch --tools claude,cursor
 
 DOCS
   https://github.com/caioribeiroclw-pixel/pluribus
 `
 
+const COMMAND_FLAGS = {
+  init: new Set(['name', 'description', 'tools', 'dry-run']),
+  sync: new Set(['dry-run', 'tools', 'source', 'update-imports']),
+  validate: new Set(['source', 'update-imports']),
+  audit: new Set(['source', 'tools', 'update-imports', 'strict', 'ci', 'json', 'output', 'github-annotations']),
+  watch: new Set(['source', 'tools', 'update-imports', 'dry-run', 'once', 'debounce']),
+}
+
+function getFlagNames(argv) {
+  return argv
+    .filter((arg) => arg.startsWith('--') && arg.length > 2)
+    .map((arg) => {
+      const withoutPrefix = arg.slice(2)
+      const eqIdx = withoutPrefix.indexOf('=')
+      return eqIdx === -1 ? withoutPrefix : withoutPrefix.slice(0, eqIdx)
+    })
+}
+
+function validateFlags(command, argv) {
+  const allowed = COMMAND_FLAGS[command]
+  if (!allowed) return
+
+  const unknown = [...new Set(getFlagNames(argv).filter((flag) => !allowed.has(flag)))]
+  if (unknown.length === 0) return
+
+  console.error(`❌ Unknown option${unknown.length === 1 ? '' : 's'} for \`${command}\`: ${unknown.map((flag) => `--${flag}`).join(', ')}`)
+  console.error(`   Supported options: ${[...allowed].map((flag) => `--${flag}`).join(', ')}`)
+  console.error('   Run `pluribus help` for usage.')
+  process.exit(1)
+}
+
 async function main() {
   const args = process.argv.slice(2)
 
@@ -75,7 +129,9 @@ async function main() {
   }
 
   const command = args[0]
-  const parsedArgs = parseArgs(args.slice(1))
+  const commandArgs = args.slice(1)
+  validateFlags(command, commandArgs)
+  const parsedArgs = parseArgs(commandArgs)
 
   try {
     switch (command) {
@@ -91,6 +147,9 @@ async function main() {
       case 'watch':
         await runWatch(parsedArgs)
         break
+      case 'audit':
+        await runAudit(parsedArgs)
+        break
       default:
         console.error(`❌ Unknown command: "${command}"`)
         console.log(`Run \`pluribus help\` for usage.`)

package/docs/ci-audit-example.md

@@ -0,0 +1,80 @@
+# CI audit example
+
+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`.
+
+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).
+
+## GitHub Actions
+
+Create `.github/workflows/pluribus-audit.yml` in the repository that uses Pluribus:
+
+```yaml
+name: Pluribus context audit
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          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
+```
+
+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
+
+      - name: Upload Pluribus audit result
+        if: always()
+        uses: actions/upload-artifact@v5
+        with:
+          name: pluribus-audit
+          path: pluribus-audit.json
+```
+
+## Local repair loop
+
+When CI fails:
+
+```bash
+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
+```
+
+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.
+
+## Remote imports in CI
+
+Normal `audit`, `sync`, and `validate` runs do not fetch remote imports. They use the committed `pluribus.lock.json` plus the local cache. If CI fails because a remote import is unlocked or cache-missing, refresh it locally with:
+
+```bash
+npx --yes pluribus-context@latest sync --update-imports
+```
+
+Then review and commit the updated `pluribus.lock.json` with the generated outputs. Use `GH_TOKEN`/`GITHUB_TOKEN` only when refreshing private GitHub imports; Pluribus never writes tokens to the lockfile or cache.