pluribus-context 0.3.0 → 0.3.3

package/CHANGELOG.md

@@ -1,7 +1,99 @@
 # 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
@@ -11,8 +103,8 @@ All notable changes to Pluribus are documented here.
 
 ### Changed
 
-- Align the package README for the npm publish so the npm package page shows the real `npx pluribus-context` install path, npm badge, 60-second smoke test, `audit` workflow, and published-status roadmap.
-- Clarify the temporary source-install path for `pluribus audit` while npm `latest` remains on 0.2.0.
+- 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
 

package/README.md

@@ -1,6 +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)
 
@@ -33,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:
@@ -70,14 +73,45 @@ 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
-# Run directly from npm
-npx pluribus-context 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
+```
+
+### 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`.
+
+When in doubt, run `npx --yes pluribus-context@latest audit` or `npx --yes pluribus-context@latest sync --dry-run` first.
 
-# Or install globally
-npm install -g pluribus-context
+### Install
+
+```bash
+# Install globally if you prefer a persistent `pluribus` command
+npm install -g pluribus-context@latest
 pluribus --help
 
 # Or clone and link locally
@@ -92,36 +126,42 @@ Want to see exactly what gets generated before adding it to a real project?
 
 ```bash
 mkdir pluribus-demo && cd pluribus-demo
-npx pluribus-context init --name "Ana" --description "A Node.js service" --tools claude,cursor,copilot
-npx pluribus-context validate
-npx pluribus-context sync --dry-run
+# 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 pluribus-context sync` to write the tool-specific files.
+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). If your repo already has `CLAUDE.md`, `.cursorrules`, Copilot instructions, or `AGENTS.md`, run a [Context Drift Audit](docs/context-drift-audit.md) first, 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).
+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
 
-> **Version note:** `pluribus audit` requires Pluribus 0.3.0 or newer. If npm still shows `pluribus-context@0.2.0`, use the audit guide manually or run the source install until the npm publish is complete:
->
-> ```bash
-> npx --package github:caioribeiroclw-pixel/pluribus#main pluribus audit
-> ```
-
 **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`**
@@ -191,6 +231,36 @@ This is read-only. It compares existing generated files with what `pluribus.md`
 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**
@@ -301,6 +371,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?
 
 - [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
 
@@ -327,7 +398,8 @@ This project is just getting started. The best way to help right now:
 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. 📣 Share with someone who maintains 3+ AI context files
+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 CI/CD workflow examples, real-world adapter feedback, and install/quickstart friction reports.
 

package/bin/pluribus.js

@@ -11,8 +11,11 @@ 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.
 
@@ -30,7 +33,8 @@ COMMANDS
 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
@@ -47,6 +51,10 @@ OPTIONS (audit)
   --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)
@@ -57,6 +65,7 @@ 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
@@ -65,12 +74,47 @@ EXAMPLES
   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)
 
@@ -85,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) {

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.

package/docs/context-drift-audit.md

@@ -4,11 +4,34 @@ Use this before adopting Pluribus when you are not sure whether your AI context
 
 The goal is not to make every tool identical. The goal is to separate shared project facts from tool-specific behavior so the shared parts can live in `pluribus.md` and be regenerated deliberately.
 
-> **Version note:** the `pluribus audit` command requires Pluribus 0.3.0 or newer. If npm still serves `pluribus-context@0.2.0`, follow the manual checklist below or run from the GitHub source until the npm publish is complete:
->
-> ```bash
-> npx --package github:caioribeiroclw-pixel/pluribus#main pluribus audit
-> ```
+If you are using "drift" to mean compaction, summarization, load-order, or long-session behavior, read the [Context Drift Taxonomy](context-drift-taxonomy.md) first. Pluribus audits file-level output drift; runtime precedence drift needs tool-specific diagnostics too.
+
+Start with the read-only command when you want a quick signal:
+
+```bash
+npx --yes pluribus-context@latest audit
+```
+
+If `pluribus.md` exists, this reports generated files that are current, missing, or drifted. If `pluribus.md` does not exist yet, it scans for known AI context files so you can decide what to migrate.
+
+Want to see the workflow before touching a real repo? Use the intentionally drifted fixture in [`examples/context-drift-audit`](../examples/context-drift-audit/): it has a `CLAUDE.md` that says Node 20 while `pluribus.md` says Node 22, so `audit --strict` has a concrete mismatch to report.
+
+## 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:
+
+```bash
+npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus audit --strict --json
+```
 
 ## 1. Find AI context surfaces
 
@@ -73,7 +96,7 @@ Keep tool-specific behavior outside the shared layer when it truly belongs to on
 Run the read-only audit first:
 
 ```bash
-npx pluribus-context audit
+npx --yes pluribus-context@latest audit
 ```
 
 If `pluribus.md` exists, this compares generated tool files with the source and reports anything missing or drifted. If `pluribus.md` does not exist yet, it scans for known AI context files so you know what to migrate.
@@ -81,8 +104,8 @@ If `pluribus.md` exists, this compares generated tool files with the source and
 Then run a dry-run before writing anything:
 
 ```bash
-npx pluribus-context validate
-npx pluribus-context sync --dry-run
+npx --yes pluribus-context@latest validate
+npx --yes pluribus-context@latest sync --dry-run
 ```
 
 Read the previews and ask two questions:
@@ -97,9 +120,35 @@ If the answer to either question is no, edit `pluribus.md` or keep that behavior
 After adoption, the simplest check is:
 
 ```bash
-npx pluribus-context audit --strict
+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:
+
+```bash
+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
+npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus 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
 ```
 
+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
+```
+
+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).
+
 That catches three common failure modes without writing files:
 
 - someone edited a generated file directly;
@@ -110,15 +159,32 @@ Use `sync --dry-run` to inspect the fix, then `sync` to update generated files.
 
 ## What this does not check
 
-`pluribus audit` is intentionally narrow: it checks whether the files generated from `pluribus.md` are current, missing, or drifted. It is not a general-purpose linter for whether your instructions still match the repository.
+`pluribus audit` is intentionally narrow: it checks whether the files generated from `pluribus.md` are current, missing, or drifted. It is not a general-purpose linter for whether your instructions still match the repository, and it cannot prove how a specific AI tool prioritizes those instructions at runtime.
 
 That distinction matters:
 
 - use `pluribus audit` when you want to know whether `CLAUDE.md`, Cursor rules, Copilot instructions, `AGENTS.md`, Windsurf, Continue, or Zed outputs are still in sync with the same source of truth;
 - use repo-specific checks, tests, or AI-context linters when you want to find stale commands, dead paths, outdated architecture notes, or conflicting nested instruction files;
-- use both if your risk is bigger than copy-paste drift: first keep generated files aligned, then validate that the shared instructions are still true.
+- use tool-specific diagnostics or hooks when the file is correct but the model drifts after compaction, summarization, or context-window reordering;
+- use both if your risk is bigger than copy-paste drift: first keep generated files aligned, then validate that the shared instructions are still true and loaded with the right precedence.
+
+Pluribus solves output drift across tools. It does not prove that the canonical context is correct or that every tool will give the generated file the same runtime priority. For a fuller split between output drift, source-of-truth drift, runtime loading drift, and behavioral drift, see the [Context Drift Taxonomy](context-drift-taxonomy.md).
+
+## Verify runtime loading separately
+
+After `pluribus sync`, do one tool-specific sanity check before trusting a new workflow:
+
+1. Open a fresh session in the tool you care about.
+2. Ask it to summarize the project rules or list the files it loaded.
+3. If the tool supports hooks, diagnostics, or load traces, check those too.
+
+Some teams add a short loading canary near the top of their generated context, for example: "Before acting, confirm that you read the project AI instructions." Keep this lightweight. A canary can prove the file was noticed, but it does not prove every instruction will keep priority after compaction, summarization, or a long session.
+
+Use Pluribus to keep the files aligned. Use the tool's own diagnostics to confirm the runtime actually loaded and prioritized them.
+
+## Feedback wanted
 
-Pluribus solves output drift across tools. It does not prove that the canonical context is correct.
+If the read-only audit misses drift, reports noise, or leaves the next step unclear, open an [audit feedback issue](https://github.com/caioribeiroclw-pixel/pluribus/issues/new?template=audit-feedback.yml). Summaries are enough; do not paste secrets, private source code, credentials, customer data, or internal instructions that should not be public.
 
 ## Decision rule