pluribus-context 0.3.0 → 0.3.3

package/docs/context-drift-taxonomy.md

@@ -0,0 +1,83 @@
+# Context Drift Taxonomy
+
+"Context drift" is overloaded. Different teams use the same phrase for different failure modes, so the fix depends on which layer is drifting.
+
+Pluribus is intentionally focused on one layer: keeping generated AI context files aligned with an intentional source of truth. It can help you see and prevent file-level drift, but it cannot prove that a model will prioritize a correct file at runtime.
+
+## 1. Output drift: generated files no longer match the source
+
+**Symptom:** `pluribus.md` says one thing, but `CLAUDE.md`, `.cursorrules`, Copilot instructions, `AGENTS.md`, Windsurf, Continue, or Zed outputs are missing or stale.
+
+**Common cause:** someone edited a generated file directly, changed the source without regenerating outputs, or forgot to commit a generated file.
+
+**Best check:**
+
+```bash
+npx --yes pluribus-context@latest audit --strict
+```
+
+**Best fix:** regenerate outputs from the reviewed source:
+
+```bash
+npx --yes pluribus-context@latest sync --dry-run
+npx --yes pluribus-context@latest sync
+```
+
+This is Pluribus' core job.
+
+## 2. Source-of-truth drift: the canonical file is wrong
+
+**Symptom:** all generated files match `pluribus.md`, but the shared instructions are outdated: stale test commands, dead paths, old architecture notes, or constraints that no longer match the codebase.
+
+**Common cause:** the team treats AI context as documentation, but does not review it when code or process changes.
+
+**Best check:** repo-specific review, tests, docs review, or a dedicated context linter that can detect dead paths, stale commands, token bloat, unsafe instructions, and conflicting guidance.
+
+**Best fix:** update `pluribus.md` in the same PR as the code/process change, then run `pluribus audit --strict` after syncing.
+
+Pluribus can make the canonical context reviewable, but it cannot know whether every statement is semantically true for your repo.
+
+## 3. Runtime loading drift: the file exists, but the tool does not load or prioritize it
+
+**Symptom:** `CLAUDE.md` or another generated file is correct on disk, but the model behaves as if older, summarized, or lower-priority instructions are more authoritative. This often appears after compaction, summarization, long sessions, or subagent handoffs.
+
+**Common cause:** runtime load order, context-window ordering, summary precedence, missing diagnostics, or a tool-specific rule about when files are read.
+
+**Best check:** tool-specific diagnostics, hooks, load traces, or a fresh-session sanity check:
+
+1. Open a fresh session in the target tool.
+2. Ask it to summarize the project rules or list the instruction files it loaded.
+3. If available, inspect hook output or context-load traces.
+
+A lightweight canary near the top of a generated file can show that the file was noticed, but it does not prove priority after compaction or summarization.
+
+**Best fix:** tool-specific load-order or hook configuration. Pluribus can keep the file aligned; the tool must prove that it loaded and prioritized the file.
+
+## 4. Behavioral drift: the model changes behavior across turns despite correct files
+
+**Symptom:** the same instructions are loaded, but compliance degrades across long sessions or repeated tasks.
+
+**Common cause:** accumulated conversation state, ambiguous instructions, too many soft preferences, or summaries that preserve the spirit of a rule while losing exact constraints.
+
+**Best check:** reproduce in a fresh session versus a long/resumed session. If fresh sessions comply and long sessions drift, the issue is runtime/session behavior, not file sync.
+
+**Best fix:** tighten critical rules into explicit constraints, split large instruction files, use tool-specific hooks where available, and keep hard requirements near the top of the runtime-loaded context.
+
+## Decision table
+
+| Drift type | Fastest check | Pluribus role |
+|---|---|---|
+| Generated files stale or missing | `pluribus audit --strict` | Core fit |
+| Canonical context outdated | repo/context linter + review | Makes source reviewable, but does not validate truth |
+| Correct file ignored after compaction | tool diagnostics/hooks/load trace | Boundary: Pluribus cannot control runtime priority |
+| Long-session behavior degrades | fresh-session repro + runtime checks | Boundary: sync can help, but runtime must enforce priority |
+
+## Practical adoption path
+
+1. Run `npx --yes pluribus-context@latest audit` to learn which files exist and whether generated outputs are current.
+2. If multiple tools share the same facts, move those stable facts into `pluribus.md`.
+3. Run `npx --yes pluribus-context@latest sync --dry-run` and review the generated files.
+4. Add `npx --yes pluribus-context@latest audit --strict` to CI or pre-commit if generated files should stay current.
+5. Separately verify that each AI tool actually loads and prioritizes its generated file at runtime.
+
+That separation keeps the promise honest: Pluribus prevents file-level context drift. It complements, rather than replaces, runtime diagnostics and context linters.

package/docs/context-file-review.md

@@ -56,8 +56,8 @@ If someone edits a generated file directly, expect drift.
 Preview generated outputs before changing a real repo:
 
 ```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 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.
@@ -67,7 +67,7 @@ Read the preview like a PR diff. Confirm that shared facts appear where they sho
 For repos that commit generated AI context files, add a lightweight check:
 
 ```bash
-npx pluribus-context sync
+npx --yes pluribus-context@latest sync
 git diff --exit-code -- \
   CLAUDE.md \
   .cursorrules \

package/docs/migrate-existing-context.md

@@ -49,10 +49,21 @@ Read the files and separate three kinds of content:
 
 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`
+## 2. Preview and scaffold `pluribus.md`
+
+Preview the scaffold before writing a new source file. `init --dry-run` is prepared for `pluribus-context@0.3.3`; until that patch is published, use the GitHub tag install command for the preview:
+
+```bash
+npx --yes --package github:caioribeiroclw-pixel/pluribus#v0.3.3 pluribus init --dry-run \
+  --name "Your project" \
+  --description "What this repo does" \
+  --tools claude,cursor,copilot,openclaw
+```
+
+When the preview looks right, create `pluribus.md` from the published npm package:
 
 ```bash
-npx pluribus-context init \
+npx --yes pluribus-context@latest init \
   --name "Your project" \
   --description "What this repo does" \
   --tools claude,cursor,copilot,openclaw
@@ -89,8 +100,8 @@ I am working on <project>. The goal is <goal>.
 Run a dry-run first:
 
 ```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
 ```
 
 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.
@@ -100,7 +111,7 @@ Check the preview for each target tool. If the generated files would lose import
 When the preview looks right:
 
 ```bash
-npx pluribus-context sync
+npx --yes pluribus-context@latest sync
 ```
 
 Review the diff carefully:
@@ -120,17 +131,16 @@ Recommended commit shape:
 For local work:
 
 ```bash
-npx pluribus-context watch
+npx --yes pluribus-context@latest 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:
+For CI or pre-commit flows, use the read-only audit command in strict mode:
 
 ```bash
-npx pluribus-context sync
-git diff --exit-code -- CLAUDE.md .cursorrules .github/copilot-instructions.md AGENTS.md
+npx --yes pluribus-context@latest audit --strict
 ```
 
-If this fails, someone edited a generated file directly or changed `pluribus.md` without regenerating outputs.
+If this fails, someone edited a generated file directly or changed `pluribus.md` without regenerating outputs. Use `npx --yes pluribus-context@latest sync --dry-run` to preview the fix before writing files.
 
 ## 6. Use imports for team/org context
 
@@ -153,7 +163,7 @@ For cross-repo shared context, use explicit remote imports and pin them with `--
 Then:
 
 ```bash
-npx pluribus-context sync --update-imports
+npx --yes pluribus-context@latest sync --update-imports
 ```
 
 Commit `pluribus.lock.json` so future syncs are deterministic. Do not commit `.pluribus/cache/remote/`; it is a local regenerable cache.

package/docs/pre-commit-audit.md

@@ -0,0 +1,67 @@
+# Pre-commit Audit Hook
+
+Use this when you want a local guard before CI, but do not want Pluribus to write files automatically.
+
+The hook runs `pluribus audit --strict` and fails the commit when generated context files are missing or drifted from `pluribus.md`.
+
+## Copy-paste hook
+
+From your project root:
+
+```bash
+mkdir -p .git/hooks
+cat > .git/hooks/pre-commit <<'EOF'
+#!/usr/bin/env sh
+set -eu
+
+# Keep generated AI context files aligned with pluribus.md before committing.
+# Install by copying this file to .git/hooks/pre-commit and running chmod +x.
+
+if [ ! -f pluribus.md ]; then
+  exit 0
+fi
+
+npx --yes pluribus-context@latest audit --strict
+EOF
+chmod +x .git/hooks/pre-commit
+```
+
+Now commits fail if `CLAUDE.md`, `.cursorrules`, Copilot instructions, `AGENTS.md`, or other generated outputs are stale.
+
+To fix drift:
+
+```bash
+npx --yes pluribus-context@latest sync --dry-run
+npx --yes pluribus-context@latest sync
+```
+
+Review the generated files, then commit `pluribus.md` and the regenerated outputs together.
+
+## With Husky
+
+If your repo already uses Husky:
+
+```bash
+npx husky init
+cat > .husky/pre-commit <<'EOF'
+#!/usr/bin/env sh
+set -eu
+
+if [ ! -f pluribus.md ]; then
+  exit 0
+fi
+
+npx --yes pluribus-context@latest audit --strict
+EOF
+chmod +x .husky/pre-commit
+```
+
+## When not to use this
+
+Do not add the hook before the team agrees that generated context files should be kept in sync. For early evaluation, run the read-only command manually first:
+
+```bash
+npx --yes pluribus-context@latest audit
+```
+
+If your team prefers server-side enforcement only, use the [CI audit example](ci-audit-example.md) instead.

package/docs/quickstart.md

@@ -4,7 +4,19 @@ 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.
+Already have one or more of those files? Start with a read-only inventory before replacing anything:
+
+```bash
+npx --yes pluribus-context@latest audit
+```
+
+Without `pluribus.md`, audit lists existing AI context surfaces so you can decide what to migrate. Then see [Migrate Existing AI Context Files](migrate-existing-context.md).
+
+## What Pluribus writes
+
+The safest path is audit → validate → `sync --dry-run` → `sync`. The first three steps are read-only. `init` writes only `pluribus.md`, and `sync` writes only generated AI context files for the tools you selected (`CLAUDE.md`, `.cursorrules`, Copilot instructions, `AGENTS.md`, Windsurf/Continue rules, or Zed `.rules`). Generated files include a `Generated by Pluribus ... do not edit manually` header, so direct edits show up as drift in `pluribus audit`.
+
+Remote imports do not refresh silently; Pluribus writes `pluribus.lock.json` and `.pluribus/cache/remote/` only when you explicitly pass `--update-imports`.
 
 ## 1. Create a disposable demo project
 
@@ -13,21 +25,46 @@ mkdir pluribus-demo
 cd pluribus-demo
 ```
 
-## 2. Scaffold context from npm
+## 2. Preview and scaffold context
+
+Start read-only so you can see the template before writing a file. `init --dry-run` is prepared for `pluribus-context@0.3.3`; until that patch is published, use the GitHub tag install command for the preview:
+
+```bash
+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
+```
+
+When the scaffold looks right, create it from the published npm package:
 
 ```bash
-npx pluribus-context init \
+npx --yes pluribus-context@latest 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.
+This creates `pluribus.md`, the single source-of-truth file Pluribus reads. Open it and replace the scaffolded notes with real project context when you are ready. If you later need team/org reuse, keep the local project sections in `pluribus.md` and import shared Markdown with `# @import ./shared/team-context.md`.
+
+Choose the comma-separated `--tools` list that matches your repo. The built-in adapters are:
+
+| Tool id | Generated file |
+| --- | --- |
+| `claude` | `CLAUDE.md` |
+| `cursor` | `.cursorrules` |
+| `copilot` | `.github/copilot-instructions.md` |
+| `openclaw` | `AGENTS.md` |
+| `windsurf` | `.windsurf/rules/pluribus.md` |
+| `continue` | `.continue/rules/pluribus.md` |
+| `zed` | `.rules` |
+
+You can also run `npx --yes pluribus-context@latest --help` to see the current supported tool ids from the CLI itself.
 
 ## 3. Validate before writing generated files
 
 ```bash
-npx pluribus-context validate
+npx --yes pluribus-context@latest validate
 ```
 
 Validation checks for missing required sections, duplicate top-level sections, broken imports, and unsupported tool names.
@@ -35,7 +72,7 @@ Validation checks for missing required sections, duplicate top-level sections, b
 ## 4. Preview generated outputs
 
 ```bash
-npx pluribus-context sync --dry-run
+npx --yes pluribus-context@latest sync --dry-run
 ```
 
 You should see previews for the selected tools. For the command above, Pluribus targets:
@@ -49,7 +86,7 @@ You should see previews for the selected tools. For the command above, Pluribus
 ## 5. Audit before writing or in CI
 
 ```bash
-npx pluribus-context audit
+npx --yes pluribus-context@latest 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.
@@ -57,7 +94,7 @@ Before generated files exist, audit reports them as missing. After sync, it beco
 ## 6. Write the files when the preview looks right
 
 ```bash
-npx pluribus-context sync
+npx --yes pluribus-context@latest 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.
@@ -65,7 +102,7 @@ Commit `pluribus.md` as the source of truth. Commit generated files if your team
 ## 7. Keep files fresh while editing
 
 ```bash
-npx pluribus-context watch
+npx --yes pluribus-context@latest watch
 ```
 
 `watch` re-runs `sync` after edits to `pluribus.md` with a small debounce, so tool-specific files do not drift during normal work.
@@ -86,17 +123,19 @@ Local sections apply after imports, so project-specific context can override sha
 
 ## 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.
+- **`pluribus` command not found after `npx`:** use `npx --yes pluribus-context@latest ...` for one-off runs, or install globally with `npm install -g pluribus-context@latest` and then run `pluribus ...`.
+- **Remote imports fail without `--update-imports`:** network refresh is explicit. Run `npx --yes pluribus-context@latest 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:
+If the quickstart fails or the generated files do not match how your team actually uses AI tools, open a [quickstart feedback issue](https://github.com/caioribeiroclw-pixel/pluribus/issues/new?template=quickstart-feedback.yml) with:
 
 1. the command you ran;
 2. which tool file felt wrong;
 3. what you expected Pluribus to generate instead.
 
+If the read-only audit was the confusing step, open an [audit feedback issue](https://github.com/caioribeiroclw-pixel/pluribus/issues/new?template=audit-feedback.yml) instead and summarize what it missed, flagged, or made unclear.
+
 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

@@ -17,13 +17,23 @@ This checklist keeps Pluribus releases reproducible and avoids accidentally publ
 - Update `CHANGELOG.md` with user-facing changes, migration notes, and verification commands.
 - Confirm README install commands use the package name `pluribus-context` and that the binary remains `pluribus`.
 
-## 2. Local checks
+## 2. Local release gate
 
-Run from the repo root:
+Run the consolidated release gate from the repo root:
 
 ```bash
+npm run release:verify
+```
+
+The verifier requires a clean `main...origin/main` checkout, reports the local package version versus npm latest, classifies the npm auth state from `npm whoami` (logged in, missing auth, or invalid/stale token), smokes the currently published npm package when one exists, then runs `npm test`, `git diff --check`, `npm run release:smoke`, `npm pack --dry-run`, and `npm publish --dry-run`. If npm auth is missing or stale, the verifier still proves the package is technically ready and names the auth/2FA action left before publish.
+
+If you need to debug an individual step, run it directly:
+
+```bash
+npm run published:smoke
 npm test
 git diff --check
+npm run release:smoke
 npm pack --dry-run
 npm publish --dry-run
 ```
@@ -59,18 +69,38 @@ Expected results:
 
 ## 4. Publish
 
-Only publish after npm auth is active and the dry run is clean:
+Only publish after npm auth is active and the dry run is clean. If `npm run release:verify` reports an invalid/stale token, clear it with `npm logout` before logging in again or using a fresh temporary publish token; do not paste tokens into the repo, docs, logs, or shell history.
+
+Use the guarded publish command so the same release gate runs immediately before publishing, then the published npm smoke runs immediately after:
+
+```bash
+npm run release:publish
+```
+
+For a no-publish rehearsal, run:
 
 ```bash
-npm publish --access public
+npm run release:publish -- --dry-run
 ```
 
+This rehearsal runs the full release verifier and confirms `HEAD` matches the local Git tag `v<package.json version>` before the OTP window. Use it before asking for or entering a live OTP so tag drift is caught without touching npm.
+
+If npm asks for OTP, use a short live OTP window and pass it through npm's normal `--otp` flag; do not paste tokens into the repo, docs, logs, or shell history. Avoid raw `_authToken`/token arguments — the guarded script refuses credential-like CLI arguments.
+
+```bash
+npm run release:publish -- --otp <one-time-code>
+```
+
+If a GitHub release or tag was created before npm publish succeeds, pause distribution. If `HEAD` still matches `v<package.json version>`, finish the npm publish with OTP/token and verify that npm `latest` matches the tagged version before posting publicly. If commits landed after the GitHub release/tag while npm was blocked, do **not** publish the same version from the newer commit. Reconcile first by publishing from the tagged commit, cutting a new patch version/tag, or intentionally updating the GitHub release/tag, then rerun the guarded publish.
+
+Before any real npm publish, `release:publish` verifies that `HEAD` matches `v<package.json version>`; the dry-run rehearsal verifies the same alignment without publishing.
+
 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
+npm view pluribus-context readme | grep -E 'npx --yes pluribus-context|60-second smoke test|Published to npm'
+npm run published:smoke
 ```
 
 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.

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

@@ -28,6 +28,21 @@ The core bet is simple: if multiple AI tools need the same project facts, conven
 - 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 rules sync tools
+
+There are useful adjacent tools for applying or managing AI rules across editors and agents. If you are comparing packages such as Ruler, vibe-rules, or ai-rules-sync, start with the workflow you want rather than the package name.
+
+Pluribus is a good fit when the source of truth should be reviewed as project context in git, regenerated into several tool-native files, and audited later for drift. It is less useful when you only need to push prompts into one tool's own rules format.
+
+| Need | Better fit |
+|---|---|
+| Apply the same simple rules to several coding agents with minimal ceremony | A rules sync tool may be enough |
+| Manage Cursor/Windsurf prompt snippets without adopting a shared source file | A tool-native rules manager may be enough |
+| Keep Claude, Cursor, Copilot, OpenClaw, Windsurf, Continue, Zed, and AGENTS-style context aligned over time | Pluribus |
+| Review shared project context in PRs and regenerate generated files | Pluribus |
+| Share org/team conventions across repos with pinned imports and a lockfile | Pluribus |
+| Fail CI when generated context files drift from the reviewed source | Pluribus `audit --strict` |
+
 ## 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.
@@ -42,6 +57,23 @@ Pluribus is different: it treats `pluribus.md` as the source of truth and regene
 | Review shared project context in PRs and regenerate generated files | Pluribus |
 | Share org/team conventions across repos with pinned imports | Pluribus |
 
+## Pluribus vs context linters and drift auditors
+
+A context linter or drift auditor is useful when you want to inspect existing files and catch stale paths, dead commands, oversized instructions, risky content, or conflicting guidance.
+
+Pluribus now includes a small read-only `pluribus audit` command, but its main job is not to be the deepest possible linter. Its main job is to prevent one specific class of drift: generated AI context files no longer matching the intentional source in `pluribus.md`.
+
+Use both layers when they help:
+
+| Need | Better fit |
+|---|---|
+| Find dead file references, stale commands, token bloat, or unsafe instructions inside context files | Dedicated context linter |
+| Check whether `CLAUDE.md`, `.cursorrules`, Copilot instructions, and `AGENTS.md` match the same source of truth | `pluribus audit` |
+| Auto-slim or rewrite arbitrary existing context files | Dedicated linter/fixer |
+| Diagnose why a correct `CLAUDE.md` is ignored after compaction or summarization | Tool-specific runtime diagnostics/hooks |
+| Generate aligned context files after review | `pluribus sync` |
+| Enforce “generated files are up to date” in CI | `pluribus audit --strict` |
+
 ## Recommended migration path
 
 1. Inventory your existing context files.
@@ -57,3 +89,7 @@ For the step-by-step version, see [Migrate Existing AI Context Files](migrate-ex
 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.
+
+That means Pluribus handles file-level alignment. Runtime precedence problems — for example, a tool loading a compacted summary above a correct context file — are real, but they belong in the tool's load-order, hooks, or context-priority settings rather than in Pluribus' sync layer.
+
+For a sharper split of the overloaded term "context drift", see the [Context Drift Taxonomy](context-drift-taxonomy.md).

package/examples/context-drift-audit/.cursorrules

@@ -0,0 +1,30 @@
+# Cursor Rules — generated by Pluribus 0.3.3 on 2026-05-13
+# Source: pluribus.md
+# Do not edit manually.
+
+
+## Project
+I am Mina, maintaining **RelayKit** — a small TypeScript SDK for webhook delivery.
+
+
+
+## Stack
+- TypeScript 5.4
+- Node.js 22 LTS
+- Node's built-in test runner
+
+
+## Conventions
+- Prefer explicit return types for exported SDK functions
+- Keep public API examples copy-pasteable
+- Use small modules with clear error boundaries
+
+## Goals
+1. Keep webhook retries deterministic
+2. Preserve backwards compatibility for public SDK APIs
+3. Make production failure modes visible in logs and tests
+
+## Constraints
+- Do not add external queue infrastructure
+- Do not break existing webhook payload shapes
+- Do not hide delivery failures behind silent retries

package/examples/context-drift-audit/.github/copilot-instructions.md

@@ -0,0 +1,28 @@
+<!-- Generated by Pluribus 0.3.3 on 2026-05-13 — do not edit manually -->
+<!-- Source: pluribus.md -->
+
+
+## Project
+I am Mina, maintaining **RelayKit** — a small TypeScript SDK for webhook delivery.
+
+
+## Stack
+- TypeScript 5.4
+- Node.js 22 LTS
+- Node's built-in test runner
+
+## Conventions
+- Prefer explicit return types for exported SDK functions
+- Keep public API examples copy-pasteable
+- Use small modules with clear error boundaries
+
+## Constraints
+- Do not add external queue infrastructure
+- Do not break existing webhook payload shapes
+- Do not hide delivery failures behind silent retries
+
+
+## Goals
+1. Keep webhook retries deterministic
+2. Preserve backwards compatibility for public SDK APIs
+3. Make production failure modes visible in logs and tests

package/examples/context-drift-audit/CLAUDE.md

@@ -0,0 +1,55 @@
+<!-- Generated by Pluribus 0.3.3 on 2026-05-13 — do not edit manually -->
+<!-- Source: pluribus.md -->
+
+# Project Context for Claude
+
+## Identity
+
+I am Mina, maintaining **RelayKit** — a small TypeScript SDK for webhook delivery.
+
+---
+
+## Tech Stack
+
+- TypeScript 5.4
+- Node.js 20 LTS
+- Node's built-in test runner
+
+---
+
+## Conventions
+
+- Prefer explicit return types for exported SDK functions
+- Keep public API examples copy-pasteable
+- Use small modules with clear error boundaries
+
+---
+
+## Goals
+
+1. Keep webhook retries deterministic
+2. Preserve backwards compatibility for public SDK APIs
+3. Make production failure modes visible in logs and tests
+
+---
+
+## Constraints
+
+> These are non-negotiable. Do not deviate from these under any circumstances.
+
+- Do not add external queue infrastructure
+- Do not break existing webhook payload shapes
+- Do not hide delivery failures behind silent retries
+
+
+
+
+
+
+---
+
+## Workflow
+
+- Run `npm test` before committing
+- Keep generated AI context files in sync with `pluribus.md`
+- Review context changes like code changes

package/examples/context-drift-audit/README.md

@@ -0,0 +1,31 @@
+# Context drift audit example
+
+This fixture shows the safest first Pluribus workflow for an existing repo: audit generated AI context before writing anything.
+
+`pluribus.md` is the source of truth. `CLAUDE.md` is intentionally drifted: it says `Node.js 20 LTS` while `pluribus.md` says `Node.js 22 LTS`. Cursor and Copilot outputs are current.
+
+Run from this directory:
+
+```bash
+npx --yes --package ../.. pluribus audit --strict
+```
+
+Expected result:
+
+```text
+⚠️  [claude] CLAUDE.md differs from generated output
+✅ [cursor] .cursorrules is current
+✅ [copilot] .github/copilot-instructions.md is current
+```
+
+Preview the fix without writing files:
+
+```bash
+npx --yes --package ../.. pluribus sync --dry-run
+```
+
+Then apply it when the diff is acceptable:
+
+```bash
+npx --yes --package ../.. pluribus sync
+```