pluribus-context 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to Pluribus are documented here.
 
+## 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 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.
+
 ## 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,6 @@
 # Pluribus
 
+[![npm version](https://img.shields.io/npm/v/pluribus-context?style=flat-square)](https://www.npmjs.com/package/pluribus-context)
 [![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)
 
@@ -72,11 +73,12 @@ And it generates the right files for each tool:
 ### Install
 
 ```bash
-# From npm (once published)
-npm install -g pluribus-context
+# Run directly from npm
+npx pluribus-context init
 
-# Or run directly with npx
-npx pluribus-context
+# Or install globally
+npm install -g pluribus-context
+pluribus --help
 
 # Or clone and link locally
 git clone https://github.com/caioribeiroclw-pixel/pluribus.git
@@ -84,8 +86,29 @@ 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
+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
+```
+
+If the preview looks right, run `npx pluribus-context 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).
+
 ### 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
@@ -156,7 +179,21 @@ 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
+```
+
+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 +290,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 +298,18 @@ 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
+- [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 +324,12 @@ 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. 📣 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,6 +9,7 @@ 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 { VERSION } from '../src/utils/version.js'
 
@@ -22,6 +23,7 @@ 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
 
@@ -40,6 +42,12 @@ 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
+
 OPTIONS (watch)
   --source        Path to pluribus.md (default: ./pluribus.md)
   --tools         Override which tools to sync (comma-separated)
@@ -55,6 +63,8 @@ EXAMPLES
   pluribus sync --tools claude,openclaw
   pluribus sync --update-imports
   pluribus validate
+  pluribus audit
+  pluribus audit --strict
   pluribus watch --tools claude,cursor
 
 DOCS
@@ -91,6 +101,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/context-drift-audit.md

@@ -0,0 +1,127 @@
+# Context Drift Audit
+
+Use this before adopting Pluribus when you are not sure whether your AI context files have already drifted.
+
+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
+> ```
+
+## 1. Find AI context surfaces
+
+From the project root:
+
+```bash
+find . -maxdepth 4 \( \
+  -name 'CLAUDE.md' -o \
+  -name '.cursorrules' -o \
+  -path './.cursor/rules/*.mdc' -o \
+  -path './.github/copilot-instructions.md' -o \
+  -name 'AGENTS.md' -o \
+  -path './.windsurf/rules/*.md' -o \
+  -path './.continue/rules/*.md' -o \
+  -name '.rules' \
+\) -print
+```
+
+If this returns zero or one file, Pluribus may still be useful for future portability, but context drift is probably not your immediate pain.
+
+## 2. Compare shared facts
+
+For each file, scan for facts that should be identical everywhere:
+
+- project purpose and product constraints;
+- stack, runtime versions, package manager, and framework choices;
+- test/lint/build commands;
+- architecture boundaries and ownership rules;
+- security or privacy constraints;
+- review expectations and generated-file warnings.
+
+Drift usually shows up as small contradictions: one file says Node 20, another says Node 22; one mentions Vitest, another mentions Jest; one has a security constraint the others never see.
+
+## 3. Split shared context from tool-specific context
+
+Move stable shared context into `pluribus.md`:
+
+```markdown
+# Identity
+This repo is <project>. Its goal is <goal>.
+
+# Stack
+- Runtime: Node.js 22
+- Package manager: npm
+- Tests: npm test
+
+# Conventions
+- Prefer small focused changes.
+- Run tests before publishing.
+
+# Goals
+- Keep AI tools aligned on the same project rules.
+
+# Constraints
+- Do not expose secrets, tokens, or private infrastructure details.
+```
+
+Keep tool-specific behavior outside the shared layer when it truly belongs to one tool: Cursor glob/frontmatter semantics, Claude-only slash-command notes, local MCP setup, or IDE-specific UI instructions.
+
+## 4. Audit and preview the regenerated files
+
+Run the read-only audit first:
+
+```bash
+npx pluribus-context 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.
+
+Then run a dry-run before writing anything:
+
+```bash
+npx pluribus-context validate
+npx pluribus-context sync --dry-run
+```
+
+Read the previews and ask two questions:
+
+1. Did every generated file receive the shared facts it needs?
+2. Did anything tool-specific get flattened into a place where it does not belong?
+
+If the answer to either question is no, edit `pluribus.md` or keep that behavior in a tool-native file before syncing.
+
+## 5. Add a lightweight drift check
+
+After adoption, the simplest check is:
+
+```bash
+npx pluribus-context audit --strict
+```
+
+That catches three common failure modes without writing files:
+
+- someone edited a generated file directly;
+- someone changed `pluribus.md` but forgot to regenerate outputs;
+- a configured output file is missing.
+
+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.
+
+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.
+
+Pluribus solves output drift across tools. It does not prove that the canonical context is correct.
+
+## Decision rule
+
+Adopt Pluribus if the audit finds repeated shared facts across two or more tools and at least one contradiction, stale command, or copy-paste maintenance burden.
+
+Do not adopt it just to replace one healthy context file. A single accurate `CLAUDE.md` or `AGENTS.md` is better than an unnecessary abstraction.

package/docs/context-file-review.md

@@ -0,0 +1,102 @@
+# Context File Review Checklist
+
+AI context files are part of the software supply chain.
+
+Files like `CLAUDE.md`, `.cursorrules`, Copilot instructions, `AGENTS.md`, Windsurf rules, Continue rules, and Zed rules are not just notes for humans. Agents read them before acting. Some teams also let agents edit them. Treat shared context with the same review discipline you apply to scripts, CI config, and dependency manifests.
+
+Use this checklist before adopting Pluribus, before committing generated context files, or before reviewing a PR that changes AI instructions.
+
+## 1. Separate public project context from private operating context
+
+Good shared context:
+
+- project purpose and architecture;
+- stack, package manager, and supported runtime versions;
+- build, test, lint, and release commands;
+- coding conventions and review expectations;
+- security and privacy constraints that are safe to publish.
+
+Do not put these in generated/shared context files:
+
+- API keys, tokens, cookies, passwords, recovery codes, or auth URLs;
+- private customer data or internal incident details;
+- unreleased strategy that should not leave the team;
+- local machine paths that reveal sensitive infrastructure;
+- instructions to bypass tests, reviews, permissions, or safety checks.
+
+If a rule needs private detail, store the detail somewhere else and reference the policy at a high level.
+
+## 2. Review instructions as executable influence
+
+A context file can change agent behavior as strongly as code can change runtime behavior. Review diffs for:
+
+- new commands agents are told to run;
+- new files or directories agents are told to read or write;
+- weakened test, lint, security, or review expectations;
+- tool-specific instructions copied into the wrong tool;
+- stale paths, package managers, or deployment commands;
+- broad instructions like "always", "never", or "ignore" that might have unintended scope.
+
+Prefer concrete, verifiable rules over taste statements. "Run `npm test` before release" is better than "be careful".
+
+## 3. Keep generated files visibly generated
+
+When Pluribus writes tool-specific files, it includes generated-file metadata. Keep that warning intact.
+
+The review rule is simple:
+
+- edit `pluribus.md` or imported source files for shared context;
+- regenerate outputs with `pluribus sync`;
+- avoid hand-editing generated files unless the file is intentionally tool-native and outside Pluribus.
+
+If someone edits a generated file directly, expect drift.
+
+## 4. Use dry-run before writing
+
+Preview generated outputs before changing a real repo:
+
+```bash
+npx pluribus-context validate
+npx pluribus-context sync --dry-run
+```
+
+Read the preview like a PR diff. Confirm that shared facts appear where they should and that private or tool-specific details did not get flattened into every output.
+
+## 5. Add a drift check to review or CI
+
+For repos that commit generated AI context files, add a lightweight check:
+
+```bash
+npx pluribus-context sync
+git diff --exit-code -- \
+  CLAUDE.md \
+  .cursorrules \
+  .github/copilot-instructions.md \
+  AGENTS.md \
+  .windsurf/rules/pluribus.md \
+  .continue/rules/pluribus.md \
+  .rules
+```
+
+This catches two risky cases:
+
+- `pluribus.md` changed but generated files were not updated;
+- generated files changed directly and no longer match the source of truth.
+
+## 6. Decide what should stay tool-native
+
+Not every instruction belongs in shared context. Keep tool-native files when a rule depends on one tool's semantics, such as:
+
+- Cursor `.mdc` glob/frontmatter behavior;
+- Claude-only slash command notes;
+- IDE UI preferences;
+- local MCP or extension setup that other tools cannot use;
+- experimental prompts that should not affect the whole team.
+
+Pluribus is for stable intentional context that should stay aligned across tools, not for forcing every tool to behave identically.
+
+## Decision rule
+
+Commit and sync shared context when it is safe, stable, reviewable, and useful across two or more tools.
+
+Keep it out of Pluribus when it is secret, local-only, highly experimental, or meaningful to just one tool.

package/docs/migrate-existing-context.md

@@ -0,0 +1,179 @@
+# Migrate Existing AI Context Files
+
+Use this guide when your project already has one or more AI instruction files and you want Pluribus to become the source of truth without losing working context.
+
+Typical starting point:
+
+```text
+CLAUDE.md
+.cursorrules
+.github/copilot-instructions.md
+AGENTS.md
+.windsurf/rules/pluribus.md
+.continue/rules/pluribus.md
+.rules
+```
+
+Goal:
+
+```text
+pluribus.md                 # edit this
+CLAUDE.md                   # generated
+.cursorrules                # generated
+.github/copilot-instructions.md
+AGENTS.md
+...
+```
+
+## 1. Inventory what exists
+
+From the project root:
+
+```bash
+find . -maxdepth 3 \( \
+  -name 'CLAUDE.md' -o \
+  -name '.cursorrules' -o \
+  -path './.github/copilot-instructions.md' -o \
+  -name 'AGENTS.md' -o \
+  -path './.windsurf/rules/pluribus.md' -o \
+  -path './.continue/rules/pluribus.md' -o \
+  -name '.rules' \
+\) -print
+```
+
+Read the files and separate three kinds of content:
+
+1. **Project facts** — stack, architecture, commands, deployment model.
+2. **Conventions** — style, testing expectations, review rules, naming patterns.
+3. **Tool-specific quirks** — instructions that only make sense for one tool.
+
+Move project facts and shared conventions into `pluribus.md`. Keep tool-specific quirks as adapter feedback or custom skill work, not as duplicated generic context.
+
+## 2. Scaffold `pluribus.md`
+
+```bash
+npx pluribus-context init \
+  --name "Your project" \
+  --description "What this repo does" \
+  --tools claude,cursor,copilot,openclaw
+```
+
+Edit `pluribus.md` and paste the shared context into the scaffolded sections.
+
+A practical first pass:
+
+```markdown
+# Identity
+I am working on <project>. The goal is <goal>.
+
+# Stack
+- Runtime: Node.js 22
+- Language: TypeScript
+- Test command: npm test
+
+# Conventions
+- Prefer small focused changes.
+- Add tests for behavior changes.
+- Keep generated files out of manual edits.
+
+# Goals
+- Keep AI tools aligned on the same project rules.
+
+# Constraints
+- Do not introduce new production dependencies without a clear reason.
+- Do not expose secrets, tokens, or private infrastructure details.
+```
+
+## 3. Preview before overwriting anything
+
+Run a dry-run first:
+
+```bash
+npx pluribus-context validate
+npx pluribus-context sync --dry-run
+```
+
+Check the preview for each target tool. If the generated files would lose important instructions, move that missing context into `pluribus.md` and run the dry-run again.
+
+## 4. Replace generated files deliberately
+
+When the preview looks right:
+
+```bash
+npx pluribus-context sync
+```
+
+Review the diff carefully:
+
+```bash
+git diff -- CLAUDE.md .cursorrules .github/copilot-instructions.md AGENTS.md
+```
+
+Recommended commit shape:
+
+1. Commit `pluribus.md` and generated files together.
+2. In the commit message, say that generated AI context files now come from Pluribus.
+3. Tell teammates to edit `pluribus.md`, not the generated outputs.
+
+## 5. Add a guardrail for drift
+
+For local work:
+
+```bash
+npx pluribus-context watch
+```
+
+For CI or pre-commit flows, use a dry-run/check pattern first. Pluribus does not ship a dedicated CI command yet, but you can still detect drift by syncing in CI and checking whether git changed:
+
+```bash
+npx pluribus-context sync
+git diff --exit-code -- CLAUDE.md .cursorrules .github/copilot-instructions.md AGENTS.md
+```
+
+If this fails, someone edited a generated file directly or changed `pluribus.md` without regenerating outputs.
+
+## 6. Use imports for team/org context
+
+If several repos share the same conventions, keep shared context in one file and import it:
+
+```markdown
+# @import ./shared/team-context.md
+# @import ./shared/security-constraints.md
+
+# Identity
+This repo is the billing service.
+```
+
+For cross-repo shared context, use explicit remote imports and pin them with `--update-imports`:
+
+```markdown
+# @import github:your-org/ai-context/shared/team-context.md@main
+```
+
+Then:
+
+```bash
+npx pluribus-context sync --update-imports
+```
+
+Commit `pluribus.lock.json` so future syncs are deterministic. Do not commit `.pluribus/cache/remote/`; it is a local regenerable cache.
+
+## Migration checklist
+
+- [ ] Existing AI context files inventoried.
+- [ ] Shared project facts and conventions moved into `pluribus.md`.
+- [ ] `validate` passes.
+- [ ] `sync --dry-run` preview reviewed.
+- [ ] Generated files written and reviewed with `git diff`.
+- [ ] Team knows to edit `pluribus.md`, not generated outputs.
+- [ ] Optional drift check added to CI/pre-commit.
+
+## Feedback wanted
+
+If migration from an existing `CLAUDE.md`, `.cursorrules`, or Copilot instructions file loses important semantics, open a [quickstart feedback issue](https://github.com/caioribeiroclw-pixel/pluribus/issues/new?template=quickstart-feedback.yml) with:
+
+1. which source file you migrated from;
+2. which generated target felt wrong;
+3. the smallest sanitized example of the missing instruction.
+
+That is the fastest path to improving the adapters.

package/docs/quickstart.md

@@ -0,0 +1,102 @@
+# Quickstart
+
+Use this when you want to try Pluribus without touching a real project yet.
+
+Pluribus takes one intentional context file (`pluribus.md`) and generates the tool-specific files your AI tools expect: `CLAUDE.md`, `.cursorrules`, Copilot instructions, `AGENTS.md`, Windsurf/Continue rules, and Zed `.rules`.
+
+Already have one or more of those files? See [Migrate Existing AI Context Files](migrate-existing-context.md) before replacing anything.
+
+## 1. Create a disposable demo project
+
+```bash
+mkdir pluribus-demo
+cd pluribus-demo
+```
+
+## 2. Scaffold context from npm
+
+```bash
+npx pluribus-context init \
+  --name "Ana" \
+  --description "A Node.js service" \
+  --tools claude,cursor,copilot
+```
+
+This creates `pluribus.md`. Open it and replace the scaffolded notes with real project context when you are ready.
+
+## 3. Validate before writing generated files
+
+```bash
+npx pluribus-context validate
+```
+
+Validation checks for missing required sections, duplicate top-level sections, broken imports, and unsupported tool names.
+
+## 4. Preview generated outputs
+
+```bash
+npx pluribus-context sync --dry-run
+```
+
+You should see previews for the selected tools. For the command above, Pluribus targets:
+
+| Tool | Generated file |
+| --- | --- |
+| Claude Code | `CLAUDE.md` |
+| Cursor | `.cursorrules` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+
+## 5. Audit before writing or in CI
+
+```bash
+npx pluribus-context audit
+```
+
+Before generated files exist, audit reports them as missing. After sync, it becomes a read-only drift check. Use `--strict` in CI when you want missing or drifted generated files to fail the build.
+
+## 6. Write the files when the preview looks right
+
+```bash
+npx pluribus-context sync
+```
+
+Commit `pluribus.md` as the source of truth. Commit generated files if your team wants each tool to work immediately after clone; otherwise regenerate them in local setup/CI.
+
+## 7. Keep files fresh while editing
+
+```bash
+npx pluribus-context watch
+```
+
+`watch` re-runs `sync` after edits to `pluribus.md` with a small debounce, so tool-specific files do not drift during normal work.
+
+## Using shared or org-level context
+
+For reusable team conventions, import shared Markdown before local project sections:
+
+```markdown
+# @import ./shared/team-context.md
+# @import ./shared/security-constraints.md
+
+# Identity
+I am Ana, building Conduit — a Node.js job runner.
+```
+
+Local sections apply after imports, so project-specific context can override shared context. See [Composable Contexts](composable-contexts.md) for local and remote import details.
+
+## Common friction
+
+- **`pluribus` command not found after `npx`:** use `npx pluribus-context ...` for one-off runs, or install globally with `npm install -g pluribus-context` and then run `pluribus ...`.
+- **Remote imports fail without `--update-imports`:** network refresh is explicit. Run `npx pluribus-context sync --update-imports` to refresh and pin remote content, then normal `sync` uses the lock/cache offline.
+- **Private GitHub imports fail:** set `GH_TOKEN`/`GITHUB_TOKEN` or log in with `gh auth login`. Pluribus never writes tokens to `pluribus.lock.json` or cache files.
+- **Generated files look wrong:** edit `pluribus.md`, run `validate`, then use `audit` and `sync --dry-run` before writing files.
+
+## Feedback wanted
+
+If the quickstart fails or the generated files do not match how your team actually uses AI tools, open an issue with:
+
+1. the command you ran;
+2. which tool file felt wrong;
+3. what you expected Pluribus to generate instead.
+
+That feedback is more useful than generic feature requests because it shows where the context format or adapters are not matching real workflows.

package/docs/release-checklist.md

@@ -47,14 +47,15 @@ Before publishing, install the exact tarball that `npm pack` creates into a temp
 npm run release:smoke
 ```
 
-The script packs the current checkout, installs that tarball into a temporary project, runs `pluribus --version`, `--help`, `init`, `validate`, `sync --dry-run`, and a real `sync`, then checks that generated output includes the package version from `package.json`. It also removes the temporary project and generated tarball on exit.
+The script packs the current checkout, installs that tarball into a temporary project, runs `pluribus --version`, `--help`, `init`, `validate`, `audit`, `sync --dry-run`, a real `sync`, and `audit --strict`, then checks that generated output includes the package version from `package.json`. It also removes the temporary project and generated tarball on exit.
 
 Expected results:
 
 - `pluribus --version` matches `package.json`.
 - `pluribus --help` shows the same version.
 - generated files mention the same Pluribus version.
-- `validate` and `sync --dry-run` work from the installed package, not the repo checkout.
+- `validate`, `audit`, and `sync --dry-run` work from the installed package, not the repo checkout.
+- `audit --strict` passes after generated files are written.
 
 ## 4. Publish
 
@@ -64,13 +65,16 @@ Only publish after npm auth is active and the dry run is clean:
 npm publish --access public
 ```
 
-Then verify:
+Then verify the registry entry and the install path users will see:
 
 ```bash
 npm view pluribus-context version dist.tarball
+npm view pluribus-context readme | grep -E 'npx pluribus-context|60-second smoke test|Published to npm'
 npx pluribus-context --help
 ```
 
+The npm README is captured at publish time. If the GitHub README changed after the previous publish, confirm the npm package page no longer contains stale pre-release markers such as `once published` before starting distribution.
+
 ## 5. GitHub release
 
 After npm publish succeeds:

package/docs/when-to-use-pluribus.md

@@ -0,0 +1,59 @@
+# When to use Pluribus
+
+Pluribus is for keeping intentional AI context in sync across tools.
+
+Use it when you already have, or expect to have, more than one context surface for the same project:
+
+- `CLAUDE.md` for Claude Code
+- `.cursorrules` or `.cursor/rules/*.mdc` for Cursor
+- `.github/copilot-instructions.md` for GitHub Copilot
+- `AGENTS.md` for OpenClaw or Codex-style agents
+- Windsurf, Continue, Zed, or other workspace rule files
+
+The core bet is simple: if multiple AI tools need the same project facts, conventions, and constraints, those facts should be reviewed once and generated many times.
+
+## Use Pluribus if
+
+- You use two or more AI coding tools in the same repo.
+- You maintain project conventions by copy-pasting between context files.
+- You want context changes to be visible in git review.
+- You want a dry-run before overwriting generated tool files.
+- Your team has shared conventions that should apply across many repos.
+- You want remote/shared context pinned with a lockfile before syncing.
+
+## You may not need it if
+
+- You only use one AI tool and one context file.
+- Your context is entirely tool-specific and should not be shared.
+- You need chat memory, retrieval, vector search, or agent orchestration.
+- You want a one-time migration and do not plan to keep files synchronized.
+
+## Pluribus vs one-way converters
+
+A one-way converter is useful when you want to translate one tool's rule format into another tool's file once.
+
+Pluribus is different: it treats `pluribus.md` as the source of truth and regenerates the tool files from that source whenever the context changes.
+
+| Need | Better fit |
+|---|---|
+| Convert existing Cursor rules into `CLAUDE.md` once | One-way converter |
+| Keep Claude, Cursor, Copilot, OpenClaw, Windsurf, Continue, and Zed context aligned over time | Pluribus |
+| Preserve tool-specific metadata exactly as-is | Tool-native files or a converter |
+| Review shared project context in PRs and regenerate generated files | Pluribus |
+| Share org/team conventions across repos with pinned imports | Pluribus |
+
+## Recommended migration path
+
+1. Inventory your existing context files.
+2. Move shared project facts and conventions into `pluribus.md`.
+3. Keep genuinely tool-specific behavior in tool-native files or custom skills.
+4. Run `pluribus sync --dry-run` and inspect the output.
+5. Commit `pluribus.md`, generated files, and `pluribus.lock.json` if remote imports are used.
+
+For the step-by-step version, see [Migrate Existing AI Context Files](migrate-existing-context.md).
+
+## Mental model
+
+Pluribus is not trying to make every AI tool identical.
+
+It is trying to keep the stable, intentional parts of your project context from drifting while still letting each tool keep its own interface and strengths.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pluribus-context",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Intentional context across every AI tool you use.",
   "type": "module",
   "homepage": "https://github.com/caioribeiroclw-pixel/pluribus#readme",

package/src/commands/audit.js

@@ -0,0 +1,239 @@
+/**
+ * pluribus audit — inspect AI context files and report sync drift.
+ *
+ * The command is intentionally read-only. With a pluribus.md source present it
+ * renders the expected tool files and compares them with what is on disk. When
+ * pluribus.md is not present, it scans for known context files to help users
+ * decide whether they need a migration pass before adopting Pluribus.
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import { parsePluribusFile, validateSections, REQUIRED_SECTIONS } from '../utils/parser.js'
+import { resolveImportsAsync } from '../utils/imports.js'
+import { renderTemplate, parseSkillFile } from '../utils/renderer.js'
+import { BUILT_IN_SKILLS, SUPPORTED_TOOLS } from '../skills/built-in.js'
+
+const TOOLS_COMMENT_RE = /<!--\s*pluribus:tools:\s*([^-]+)\s*-->/
+const KNOWN_CONTEXT_FILES = [
+  ...new Set([
+    ...Object.values(BUILT_IN_SKILLS).flatMap((skill) => skill.outputFiles),
+    '.cursor/rules',
+    '.github/instructions',
+    'AGENTS.md',
+    'CLAUDE.md',
+  ]),
+]
+
+/**
+ * @param {Record<string, string | boolean>} args
+ */
+export async function runAudit(args) {
+  const sourceArg = typeof args.source === 'string' ? args.source : null
+  const toolsArg = typeof args.tools === 'string' ? args.tools : null
+  const updateImports = Boolean(args['update-imports'])
+  const strict = Boolean(args.strict)
+  const cwd = process.cwd()
+  const sourcePath = sourceArg
+    ? path.resolve(cwd, sourceArg)
+    : path.join(cwd, 'pluribus.md')
+  const displaySource = path.relative(cwd, sourcePath) || 'pluribus.md'
+
+  if (!fs.existsSync(sourcePath)) {
+    const found = scanKnownContextFiles(cwd)
+    console.log(`ℹ️  No ${displaySource} found.`)
+
+    if (found.length > 0) {
+      console.log('')
+      console.log('Found existing AI context surface(s):')
+      for (const file of found) {
+        console.log(`   • ${file}`)
+      }
+      console.log('')
+      console.log('Use these as migration inputs for `pluribus init`, then run `pluribus audit` again.')
+    } else {
+      console.log('')
+      console.log('No known AI context files found in this directory.')
+      console.log('Run `pluribus init` to create a source file, then `pluribus sync --dry-run`.')
+    }
+
+    console.log('Docs: https://github.com/caioribeiroclw-pixel/pluribus/blob/main/docs/migrate-existing-context.md')
+    if (strict) process.exit(1)
+    return
+  }
+
+  let rawContent
+  try {
+    rawContent = fs.readFileSync(sourcePath, 'utf8')
+  } catch (err) {
+    console.error(`❌ Could not read ${sourcePath}: ${err.message}`)
+    process.exit(1)
+  }
+
+  const errors = []
+  let resolvedContent
+  try {
+    const projectDir = path.dirname(sourcePath)
+    const resolved = await resolveImportsAsync(sourcePath, {
+      rootDir: projectDir,
+      allowRemote: updateImports,
+      lockfilePath: path.join(projectDir, 'pluribus.lock.json'),
+      cacheDir: path.join(projectDir, '.pluribus', 'cache', 'remote'),
+      updateLockfile: updateImports,
+    })
+    resolvedContent = resolved.content
+  } catch (err) {
+    errors.push(`Could not resolve imports: ${err.message}`)
+  }
+
+  const sections = resolvedContent ? parsePluribusFile(resolvedContent) : {}
+  const validation = validateSections(sections)
+  for (const error of validation.errors) {
+    errors.push(error)
+  }
+
+  const tools = getTools(rawContent, toolsArg)
+  const unknownTools = tools.filter((tool) => !SUPPORTED_TOOLS.includes(tool))
+  if (unknownTools.length > 0) {
+    errors.push(`Unknown tool(s): ${unknownTools.join(', ')}. Supported: ${SUPPORTED_TOOLS.join(', ')}`)
+  }
+
+  if (errors.length > 0) {
+    console.error(`❌ Cannot audit ${displaySource}:`)
+    for (const error of errors) {
+      console.error(`   • ${error}`)
+    }
+    console.error(`\n   Complete required sections (${REQUIRED_SECTIONS.join(', ')}) and re-run.`)
+    process.exit(1)
+  }
+
+  console.log(`🔎 Auditing ${displaySource} → ${tools.join(', ')}`)
+  console.log('')
+
+  const results = []
+  for (const toolId of tools) {
+    const skill = loadSkill(cwd, toolId)
+    if (!skill) {
+      results.push({ toolId, status: 'error', file: '(skill)', message: 'Skill not found' })
+      continue
+    }
+
+    const missingRequired = skill.required.filter((required) => {
+      const sectionName = Object.keys(sections).find((name) => name.toLowerCase() === required.toLowerCase())
+      return !sectionName || !sections[sectionName]?.trim()
+    })
+
+    if (missingRequired.length > 0) {
+      results.push({
+        toolId,
+        status: 'error',
+        file: '(sections)',
+        message: `Missing required section(s) for ${toolId}: ${missingRequired.join(', ')}`,
+      })
+      continue
+    }
+
+    let rendered
+    try {
+      rendered = renderTemplate(skill.template, sections, path.relative(cwd, sourcePath) || 'pluribus.md')
+    } catch (err) {
+      results.push({ toolId, status: 'error', file: '(template)', message: err.message })
+      continue
+    }
+
+    for (const outputFile of skill.outputFiles) {
+      const outputPath = path.join(cwd, outputFile)
+      if (!fs.existsSync(outputPath)) {
+        results.push({ toolId, status: 'missing', file: outputFile })
+        continue
+      }
+
+      const existing = fs.readFileSync(outputPath, 'utf8')
+      if (normalizeGeneratedMetadata(existing) === normalizeGeneratedMetadata(rendered)) {
+        results.push({ toolId, status: 'current', file: outputFile })
+      } else {
+        results.push({ toolId, status: 'drift', file: outputFile })
+      }
+    }
+  }
+
+  for (const result of results) {
+    const label = `[${result.toolId}] ${result.file}`
+    if (result.status === 'current') {
+      console.log(`   ✅ ${label} is current`)
+    } else if (result.status === 'missing') {
+      console.log(`   ⚠️  ${label} is missing`)
+    } else if (result.status === 'drift') {
+      console.log(`   ⚠️  ${label} differs from generated output`)
+    } else {
+      console.log(`   ❌ ${label}: ${result.message}`)
+    }
+  }
+
+  const summary = results.reduce((acc, result) => {
+    acc[result.status] = (acc[result.status] || 0) + 1
+    return acc
+  }, {})
+
+  console.log('')
+  console.log(`Summary: ${summary.current || 0} current, ${summary.drift || 0} drifted, ${summary.missing || 0} missing, ${summary.error || 0} error(s).`)
+
+  const hasProblem = (summary.drift || 0) + (summary.missing || 0) + (summary.error || 0) > 0
+  if (hasProblem) {
+    console.log('Run `pluribus sync --dry-run` to preview fixes, then `pluribus sync` to update generated files.')
+  } else {
+    console.log('✅ Generated context files are in sync.')
+  }
+
+  if ((strict && hasProblem) || (summary.error || 0) > 0) {
+    process.exit(1)
+  }
+}
+
+function getTools(rawContent, toolsArg) {
+  if (toolsArg) {
+    return splitTools(toolsArg)
+  }
+
+  const match = rawContent.match(TOOLS_COMMENT_RE)
+  if (match) {
+    return splitTools(match[1])
+  }
+
+  return [...SUPPORTED_TOOLS]
+}
+
+function splitTools(value) {
+  return String(value)
+    .split(',')
+    .map((tool) => tool.trim().toLowerCase())
+    .filter(Boolean)
+}
+
+function loadSkill(cwd, toolId) {
+  const localSkillPath = path.join(cwd, 'pluribus', 'skills', `${toolId}.md`)
+  if (fs.existsSync(localSkillPath)) {
+    const parsed = parseSkillFile(fs.readFileSync(localSkillPath, 'utf8'))
+    return {
+      id: toolId,
+      outputFiles: parsed.output,
+      template: parsed.template,
+      required: parsed.sections.required,
+      optional: parsed.sections.optional,
+    }
+  }
+
+  return BUILT_IN_SKILLS[toolId]
+}
+
+function scanKnownContextFiles(cwd) {
+  return KNOWN_CONTEXT_FILES
+    .filter((relativePath) => fs.existsSync(path.join(cwd, relativePath)))
+    .sort()
+}
+
+function normalizeGeneratedMetadata(content) {
+  return content
+    .replace(/Generated by Pluribus ([^\s]+) on \d{4}-\d{2}-\d{2}/g, 'Generated by Pluribus $1 on <date>')
+    .replace(/generated by Pluribus ([^\s]+) on \d{4}-\d{2}-\d{2}/g, 'generated by Pluribus $1 on <date>')
+}

package/src/index.js

@@ -6,6 +6,7 @@ export { runInit } from './commands/init.js'
 export { runSync } from './commands/sync.js'
 export { runValidate } from './commands/validate.js'
 export { runWatch } from './commands/watch.js'
+export { runAudit } from './commands/audit.js'
 export { parsePluribusFile, validateSections } from './utils/parser.js'
 export { renderTemplate } from './utils/renderer.js'
 export { BUILT_IN_SKILLS, SUPPORTED_TOOLS } from './skills/built-in.js'

package/src/utils/version.js

@@ -1 +1 @@
-export const VERSION = '0.2.0'
+export const VERSION = '0.3.0'