@compozy/skeeper 0.1.1 → 0.2.1

package/README.md

@@ -9,9 +9,6 @@
     <a href="https://pkg.go.dev/github.com/compozy/skeeper">
       <img src="https://pkg.go.dev/badge/github.com/compozy/skeeper.svg" alt="Go Reference">
     </a>
-    <a href="https://goreportcard.com/report/github.com/compozy/skeeper">
-      <img src="https://goreportcard.com/badge/github.com/compozy/skeeper" alt="Go Report Card">
-    </a>
     <a href="LICENSE">
       <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT">
     </a>
@@ -21,341 +18,318 @@
   </p>
 </div>
 
-Specs and code want to live together. Spec files (`SPEC.md`, `docs/specs/*`, `.claude/plans/*`, ADRs, RFCs) belong next to the code they describe — but committing them to your main repo bloats every PR with documentation noise, and ignoring them loses history. `skeeper` runs a sidecar Git repository that mirrors matched spec files on every commit. You edit specs at their natural paths, your main PRs stay focused on code, and a separate Git history keeps full `git log`, `git blame`, and branch-aware versioning of every spec change. One `skeeper init` and the post-commit hook does the rest — without ever blocking your `git commit`.
-
-## ✨ Highlights
+Spec docs drift from code, or they bloat every PR. Skeeper picks neither.
 
-- **One sidecar repo, full Git history.** Specs version normally — `git log`, `git blame`, branches, PRs — without touching your main repo's diff.
-- **Shared sidecars without collisions.** Named namespaces isolate stored paths and pushed branches inside one sidecar remote.
-- **Edit specs where they belong.** Spec files stay next to the code they describe. `skeeper` mirrors them into `.skeeper/` for you.
-- **A post-commit hook that never breaks your commit.** 750 ms foreground budget per namespace; on failure, the sync queues locally and retries on the next manual `skeeper sync`.
-- **Branch-aware mirroring.** Sidecar branches track main-tree branches, so feature work and `main` stay isolated.
-- **Fresh-clone hydration.** `skeeper hydrate` restores matched specs into a new clone so teammates start with full context.
-- **Glob-based pattern matching.** Doublestar globs (`**/SPEC.md`, `docs/specs/**`, `.claude/plans/**`) — match specs the way you actually organize them.
-- **Shells out to `git` and `gh`.** Reuses your existing GitHub auth. Every operation is debuggable with the same Git commands you already know.
-- **Single static binary, zero runtime deps.** Linux, macOS, Windows on amd64/arm64. CGO disabled.
-
-## 📦 Installation
+It mirrors `SPEC.md`, ADRs, RFCs, and AI plan files into a sidecar Git repository and commits a tiny `skeeper.lock` to your main repo that pins every commit to exact sidecar commits. PR diffs stay focused on code, spec history stays auditable, and nothing silently drifts because the managed Git hooks fail the commit if the sidecar state cannot be proven.
 
-#### Homebrew
+## ✨ Highlights
 
-```bash
-brew tap compozy/compozy
-brew install --cask skeeper
-```
+- **Lockfile-backed reliability.** `skeeper.lock` records sidecar URL, source branch, namespace branch, sidecar commit, per-namespace digest, file count, and byte count.
+- **Strict managed hooks.** The managed `pre-commit` and `pre-merge-commit` hooks sync staged content, push the sidecar, write and stage `skeeper.lock`, and fail closed. The managed `pre-push` hook verifies the lock against the sidecar remote.
+- **Specs stay local to their code.** Edit `SPEC.md`, `docs/specs/**`, `.claude/plans/**`, ADRs, RFCs, or custom globs where they naturally belong.
+- **Shared sidecars without collisions.** Namespaces isolate stored paths and sidecar branches inside one sidecar remote.
+- **Branch-aware history.** Namespace branches use `<namespace>/__branches__/<source-branch>`.
+- **Fresh-clone hydration.** `skeeper hydrate` restores files from the locked sidecar commits, not a best-effort latest branch.
+- **Safe reconciliation.** `hydrate`, `fsck`, `diff`, and `reconcile` classify per-path drift before any local managed document is overwritten or moved.
+- **Agent-friendly commands.** `status`, `sync`, `verify`, `fsck`, `diff`, `reconcile`, `update`, `hooks check`, `repair status`, `rescue`, `pattern`, `adopt`, and `untrack` all support deterministic output where needed.
+- **Skill for AI agents.** A bundled skill at [`.agents/skills/skeeper/SKILL.md`](.agents/skills/skeeper/SKILL.md) teaches coding agents the strict-sync workflow, namespaces, and recovery commands.
 
-#### NPM
+## 🎯 Who Is This For
 
-```bash
-npm install -g @compozy/skeeper
-```
+- Teams using AI coding agents that produce `SPEC.md`, PRD, TechSpec, and plan markdown next to code.
+- Engineering organizations running ADRs, RFCs, and design docs in-repo without making every PR a docs+code review.
+- Solo developers who want full spec history (`git log`, `git blame`, branches, PRs) without polluting their main repository's diff.
 
-#### Go
+## 📦 Installation
 
 ```bash
 go install github.com/compozy/skeeper/cmd/skeeper@latest
 ```
 
-#### From Source
-
-```bash
-git clone git@github.com:compozy/skeeper.git
-cd skeeper && make verify && go build -o bin/skeeper ./cmd/skeeper
-```
-
-#### Docker
-
-```bash
-git clone git@github.com:compozy/skeeper.git
-cd skeeper && make docker-build      # builds skeeper:dev (distroless, nonroot)
-docker run --rm -v "$PWD:/workspace" -w /workspace skeeper:dev status
-```
+Other release channels are available through GitHub Releases, Homebrew, NPM, and the distroless Docker image.
 
-#### Prerequisites
+Prerequisites:
 
 - `git` on `PATH`
-- `gh` (GitHub CLI) **only when `skeeper init` creates a new sidecar** — existing sidecars can be reused with `--sidecar`. Day-to-day commands need only `git`.
+- `gh` only when `skeeper init` creates a new GitHub sidecar repo
 
 ## 🔄 How It Works
 
-Spec files live at their natural paths next to code. Your main repo's `.gitignore` lists the effective namespace patterns plus `.skeeper/`, so neither owned specs nor the sidecar clone ever appear in a main-repo diff.
+Spec files live in the main worktree but are ignored by the main repository through a managed `.gitignore` block. The sidecar repository stores mirrored files under `<namespace>/<path>` and pushes them to `<namespace>/__branches__/<source-branch>`.
 
-On every `git commit`, the managed post-commit hook runs `skeeper sync --hook` with a 750 ms foreground budget per namespace. `skeeper` matches files against namespace patterns, copies them into `.skeeper/`, commits with a reference to the main commit SHA, and pushes to the sidecar remote.
-
-Each namespace stores files under `<namespace>/<path>` in the sidecar and pushes branch `<namespace>/__branches__/<source-branch>`. For example, namespace `skills` on source branch `main` stores `skills/review.md` as `skills/skills/review.md` and pushes sidecar branch `skills/__branches__/main`.
-
-If anything fails — network, auth, push rejection, timeout — `skeeper` writes a retry record to `.git/skeeper/queue.json` with the failing namespace when one is known, appends a one-line audit entry to `.git/skeeper/sync.log`, and exits 0 so your `git commit` always succeeds. Run `skeeper sync` later to drain the queue.
+On commit, the managed `pre-commit` block runs last. On automatic merge commits, the managed `pre-merge-commit` block runs the same strict sync path because Git does not run `pre-commit` for merge commits. Both hooks build a plan from the staged index plus explicitly owned ignored/untracked spec paths, fetch and rebase sidecar branches, mirror content into `.skeeper/`, commit and push the sidecar, write `skeeper.lock`, and stage that lock before Git creates the main commit.
 
 ```mermaid
-flowchart LR
-    A[Developer<br/>git commit] --> B[post-commit hook<br/>skeeper sync --hook]
-    B --> C{Namespace sync within<br/>750 ms?}
-    C -- yes --> D[Copy matched specs<br/>into .skeeper/]
-    D --> E[git commit<br/>in sidecar]
-    E --> F[git push<br/>to sidecar remote]
-    C -- no / error --> G[Write namespace retry record<br/>.git/skeeper/queue.json]
-    G --> H[Hook exits 0<br/>main commit succeeds]
-    H -. later .-> I[skeeper sync<br/>drains queue]
-    I --> D
+flowchart TD
+    Start([👤 git commit]):::user --> UserHook[🪝 Existing user hook content]:::user
+    UserHook --> Block
+
+    subgraph Block [📦 Skeeper pre-commit block]
+        direction TB
+        S1[🧮 Reconcile staged specs<br/>+ ownership] --> S2[🔄 Fetch &amp; rebase<br/>sidecar branch]
+        S2 --> S3[🪞 Mirror namespace files<br/>into .skeeper/]
+        S3 --> S4[📤 Commit &amp; push sidecar]
+        S4 --> S5[🔒 Write &amp; stage<br/>skeeper.lock]
+    end
+
+    Block --> Commit[✅ Main commit proceeds]:::ok
+    Commit --> Push([🚀 git push]):::user
+    Push --> Verify[🔍 Skeeper pre-push verify]:::skeeper
+    Verify --> Done([🎉 Sidecar verified]):::ok
+
+    classDef user fill:#dbeafe,stroke:#1d4ed8,color:#0c1e3e
+    classDef skeeper fill:#fef3c7,stroke:#b45309,color:#3b2c00
+    classDef ok fill:#dcfce7,stroke:#15803d,color:#052e16
+    class S1,S2,S3,S4,S5 skeeper
 ```
 
+If sync fails, the commit fails. This is intentional: a committed main change should not silently drift from the sidecar. The audited bypass is `SKEEPER_SKIP=1`; it records `.git/skeeper/bypass.json`, prints a warning, and `pre-push`, `status`, `fsck`, and `verify` continue to surface stale-lock diagnostics until `skeeper sync` repairs the state. `git commit --no-verify` is unsupported because Git skips all hook code and cannot record an audit trail.
+
 ## ⚙️ Configuration
 
-`skeeper init` writes `.skeeper.yml` at the repo root. Commit it — your teammates need it for `skeeper hydrate`.
+`skeeper init` writes `.skeeper.yml` at the repository root. Commit it.
 
 ```yaml
-# Required: sidecar repository URL
 sidecar: git@github.com:user/myproject-specs.git
 
-# Required: namespaces route files into sidecar paths and branches
 namespaces:
-  - name: skills
-    patterns:
-      - "skills/*.md"
-
-  - name: myproject
+  - name: project
     patterns:
       - "**/SPEC.md"
       - "docs/specs/**"
       - ".claude/plans/**"
       - "**/*.spec.md"
     exclude:
-      - "skills/*.md"
-
-# Optional: install one-liner shown to teammates after `skeeper hydrate`
-bootstrap: brew tap compozy/compozy && brew install --cask skeeper
+      - "docs/specs/private/**"
 ```
 
-Unknown keys are rejected — config errors fail loud, not silently.
-
-Every namespace needs a `name` and at least one `patterns` glob. `exclude` removes ownership from that namespace; if another namespace owns the excluded files, they stay tracked there. A file owned by more than one namespace is a configuration error because hidden precedence would make deletes unsafe.
+Advanced operational defaults are optional:
 
-`skeeper init` writes one namespace by default. Add more namespaces by editing `.skeeper.yml`.
-
-Local-only state lives under `.git/skeeper/` (already gitignored by Git's hooks directory):
+```yaml
+settings:
+  guardrails:
+    max_files: 100
+    max_bytes: 10485760
+  hooks:
+    pre_push_timeout: 30s
+    allow_skip_env: SKEEPER_SKIP
 
-| File         | Purpose                                                |
-| ------------ | ------------------------------------------------------ |
-| `queue.json` | Pending retries from failed hook runs                  |
-| `sync.log`   | Append-only audit log of sync attempts and error codes |
+namespaces:
+  - name: generated
+    patterns:
+      - "generated/specs/**"
+    respect_gitignore: false
+```
 
-## 🚀 Quick Start
+Rules:
 
-### 1. Install
+- Unknown keys are rejected.
+- Every namespace needs a `name` and at least one glob in `patterns`.
+- `exclude` is the only public exclusion mechanism. Negative globs in `patterns` are rejected.
+- Ownership must be unique. If two namespaces own the same file, the plan fails and asks for an `exclude` fix.
+- `respect_gitignore: false` bypasses root `.gitignore`, nested `.gitignore`, `.git/info/exclude`, and global excludes for that namespace. `.git/` and `.skeeper/` are always excluded.
 
-```bash
-go install github.com/compozy/skeeper/cmd/skeeper@latest
-```
+Local-only state lives under `.git/skeeper/`:
 
-### 2. Initialize the sidecar
+| File               | Purpose                                        |
+| ------------------ | ---------------------------------------------- |
+| `transaction.json` | Current resumable mutating operation and phase |
+| `bypass.json`      | Latest audited strict-hook bypass              |
+| `hydration.json`   | Last locked sidecar blobs hydrated locally     |
+| `rescue/`          | Local files moved aside before prune/overwrite |
 
-In a Git repo where you want to track specs:
+## 🚀 Quick Start
 
 ```bash
 skeeper init
 ```
 
-Interactive by default — opens a terminal form for the sidecar mode, repository name or URL, namespace, bootstrap command, and optional extra context globs. The interactive flow always includes the default spec globs (`**/SPEC.md`, `docs/specs/**`, `.claude/plans/**`, and `**/*.spec.md`) in the initial namespace; the extra context prompt starts empty and is only for additional folders or files you explicitly want in that namespace. Or pass values as flags:
+Interactive init asks for the sidecar mode, repository name or URL, namespace, bootstrap command, and optional extra context globs. With flags:
 
 ```bash
 skeeper init \
   --sidecar-name myproject-specs \
   --visibility private \
-  --namespace myproject \
+  --namespace project \
   --patterns "**/SPEC.md" \
-  --patterns ".claude/plans/**"
+  --patterns "docs/specs/**"
 ```
 
-To reuse one shared sidecar remote across multiple source repos:
+Use an existing shared sidecar:
 
 ```bash
 skeeper init \
   --sidecar git@github.com:user/shared-specs.git \
-  --namespace myproject \
+  --namespace project \
   --patterns "**/SPEC.md"
 ```
 
-`skeeper init` creates the GitHub repo with `gh repo create` unless `--sidecar` points to an existing remote. It clones the sidecar into `.skeeper/`, writes `.skeeper.yml`, updates `.gitignore`, and installs the post-commit hook. New init defaults the namespace to the source repo name.
-
-When using flags, repeated `--patterns` values are the complete pattern set written to `.skeeper.yml`; they do not append to the interactive defaults.
-
-### 3. Edit specs and commit normally
+Then edit specs and commit normally:
 
 ```bash
 $EDITOR src/auth/SPEC.md
-git add .
+git add src/auth/service.go src/auth/SPEC.md
 git commit -m "auth: design OAuth provider flow"
 ```
 
-The hook fires automatically. No extra step.
+The `pre-commit` and `pre-merge-commit` hooks mirror specs and stage `skeeper.lock`. If a hook stages a new lock, review it and include it in the commit.
+
+## 🛟 Failed Sync Recovery
 
-### 4. Inspect
+Inspect local repair state:
 
 ```bash
-skeeper status                       # sidecar URL, branch mapping, last sync, pending count
-skeeper log src/auth/SPEC.md         # sidecar Git history for one file
+skeeper repair status
 ```
 
-### 5. Onboard a teammate
+Resume the recorded operation when network/auth/sidecar contention has been fixed:
 
 ```bash
-git clone git@github.com:user/myproject.git
-cd myproject
-skeeper hydrate
+skeeper repair resume
 ```
 
-`hydrate` clones the sidecar into `.skeeper/`, restores matched specs into the working tree, and installs the hook.
-
-### 6. Recover from a failed sync
-
-If the hook ever queued work (network blip, push rejection):
+Abort only before the main index has been mutated:
 
 ```bash
-skeeper sync           # drain queued retries, then run a fresh sync
-skeeper sync --pull    # rebase the sidecar branch first — useful when teammates pushed
+skeeper repair abort
 ```
 
-## 🧰 How Sync Works
-
-The post-commit hook is a _managed block_ in `.git/hooks/post-commit`, installed idempotently. It runs `skeeper sync --hook` with a 750 ms foreground budget per namespace so your `git commit` stays bounded even on a slow network.
+Run a fresh repair sync when a bypass or stale lock is reported:
 
-On the success path, `skeeper` matches files with doublestar globs, copies them into `.skeeper/`, then runs `git add`, `git commit`, and `git push` against the sidecar remote. Each namespace copies to `.skeeper/<namespace>/<path>` and pushes `<namespace>/__branches__/<source-branch>`. Sidecar commits reference the main-repo SHA so you can correlate spec changes back to the code change that triggered them.
-
-On the failure path — timeout, auth failure, network failure, or push rejection — `skeeper` writes a retry record to `.git/skeeper/queue.json` with the failing namespace when one is known, appends to `.git/skeeper/sync.log`, prints a one-line note, and the hook exits 0. The next `skeeper sync` drains the queue before running a normal sync. Use `skeeper sync --pull` when a teammate pushed sidecar updates between your commits; it fetches and rebases before pushing.
-
-This design has two consequences worth knowing:
-
-- **`git commit` never fails because of `skeeper`.** Worst case, you have queued work to drain.
-- **Conflicts surface as Git conflicts.** `skeeper sync --pull` stops if the rebase reports unresolved conflicts; resolve them in `.skeeper/` with normal Git tooling, then re-run.
+```bash
+skeeper sync
+skeeper verify
+```
 
 ## 📖 CLI Reference
 
-<details>
-<summary><code>skeeper init</code> — Create and connect a sidecar specs repository</summary>
-
 ```bash
 skeeper init [flags]
+skeeper sync [--dry-run] [--json] [--commit --message <msg>] [--force]
+skeeper adopt <path-or-glob>... [--dry-run] [--json] [--force] [--commit --message <msg>]
+skeeper untrack <path-or-glob>... [--dry-run] [--json] [--force] [--commit --message <msg>]
+skeeper pattern test <glob> [--namespace <name>] [--json]
+skeeper pattern add <glob> [--namespace <name>] [--exclude <glob>]... [--adopt-existing] [--dry-run] [--json] [--force] [--commit --message <msg>]
+skeeper hydrate [--dry-run] [--json] [--keep-local|--adopt-local|--prune-local|--merge] [--ours|--theirs]
+skeeper reconcile [--dry-run] [--json] [--adopt-local|--prune-local|--merge] [--ours|--theirs]
+skeeper diff [--json] [--namespace <name>] [--class <class>] [--extra] [--missing] [--modified]
+skeeper rescue list [--json]
+skeeper rescue restore <id> [path...] [--json] [--overwrite]
+skeeper update [--json] [--no-git] [--reconcile <report|keep-local|adopt-local|prune-local|merge>] [--ours|--theirs]
+skeeper status [--json]
+skeeper log <path> [--latest]
+skeeper fsck [--json] [--source-branch <branch>]
+skeeper verify [--json] [--source-branch <branch>]
+skeeper hooks install [--json]
+skeeper hooks check [--json]
+skeeper merge-driver [--json]
+skeeper repair status|resume|abort [--json]
+skeeper version
 ```
 
-| Flag             | Default   | Description                                                  |
-| ---------------- | --------- | ------------------------------------------------------------ |
-| `--sidecar`      |           | Existing sidecar repository URL                              |
-| `--sidecar-name` |           | GitHub sidecar repository name or `OWNER/REPO`               |
-| `--visibility`   | `private` | GitHub visibility: `private`, `public`, or `internal`        |
-| `--namespace`    | repo slug | Initial sidecar namespace for this source repo               |
-| `--bootstrap`    |           | Optional install command stored in `.skeeper.yml`            |
-| `--patterns`     |           | Complete spec glob pattern set; repeat for multiple patterns |
+Command notes:
 
-When run interactively, `init` opens a terminal form. It includes the default spec globs automatically, then asks whether to add extra context globs such as `AGENTS.md`, `CLAUDE.md`, or `.codex/plans/**`. It runs `gh repo create` for `--sidecar-name` or the create mode, but skips GitHub creation when `--sidecar` is provided. `--sidecar` and `--sidecar-name` are mutually exclusive.
+- `sync` uses working-tree content and stages `skeeper.lock`. Hook mode uses staged index content.
+- `adopt` and `untrack` push sidecar coverage before removing main-index tracking.
+- `pattern add --adopt-existing` updates `.skeeper.yml`, updates the managed `.gitignore` block, then runs the same adoption transaction.
+- `verify` checks `skeeper.lock` against the sidecar remote and does not require hooks.
+- `fsck` compares current working-tree specs against locked sidecar content, reports exact drift paths, and does not mutate files or refs.
+- `hydrate` restores from locked sidecar commits by default, but fails closed if local managed files would be overwritten or orphaned.
+- `reconcile` is the explicit status/add/merge equivalent for managed documents. Use `--adopt-local` to publish local-only files, or `--prune-local` to move them to `.git/skeeper/rescue/<id>/` before restoring.
+- `diff` lists per-path drift classes such as `local_only`, `missing_local`, `local_modified`, and `both_modified_conflict`.
+- `update` is the high-level clone workflow for agents: safe fast-forward, verify, hydrate, fsck, and hook validation.
+- `log --latest` fetches the namespace branch and reads its latest history instead of the locked commit.
+- `hooks install` removes legacy Skeeper post-commit blocks, installs strict pre-commit/pre-merge-commit/pre-push blocks, writes `.gitattributes`, and configures the `skeeper.lock` merge driver.
 
-</details>
+## 🤖 CI Action
 
-<details>
-<summary><code>skeeper hydrate</code> — Restore spec files from the sidecar repository</summary>
+Use the same-repository Action to verify `skeeper.lock` in CI:
 
-```bash
-skeeper hydrate
+```yaml
+name: skeeper
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: compozy/skeeper@v0.1.1
+        with:
+          args: |
+            verify
+            --json
+          ssh-private-key: ${{ secrets.SKEEPER_SSH_PRIVATE_KEY }}
 ```
 
-Use after a fresh clone of the main repo. `hydrate` clones the sidecar into `.skeeper/`, copies matched spec files into the working tree, and installs the post-commit hook. No flags.
+Credential precedence:
 
-</details>
+1. `ssh-private-key` writes a temp key and sets `GIT_SSH_COMMAND`.
+2. `token` configures HTTPS GitHub credentials.
+3. Existing runner Git/SSH credentials are used when neither input is provided.
 
-<details>
-<summary><code>skeeper sync</code> — Mirror spec files into the sidecar repository</summary>
+Secrets are masked before configuration. The wrapper downloads the released Skeeper binary for the action ref/tag and delegates verification to the CLI.
 
-```bash
-skeeper sync [flags]
-```
+## 🩺 Troubleshooting
 
-| Flag     | Default | Description                                                                          |
-| -------- | ------- | ------------------------------------------------------------------------------------ |
-| `--pull` | `false` | Pull and rebase the sidecar branch before syncing                                    |
-| `--hook` | `false` | Run in post-commit hook mode: 750 ms foreground budget per namespace, always exits 0 |
+**`SKEEPER_SKIP=1` was used**
 
-Drains queued retries from `.git/skeeper/queue.json`, then mirrors spec files into `.skeeper/`, commits, and pushes. Use `--pull` when teammates may have pushed sidecar updates between your commits. `--hook` is what the installed post-commit hook calls — you rarely run it manually.
+Run `skeeper status`, then `skeeper sync`, then `skeeper verify`. The bypass journal remains visible until sync clears it.
 
-</details>
+**Sidecar push was rejected**
 
-<details>
-<summary><code>skeeper status</code> — Show sidecar sync status</summary>
-
-```bash
-skeeper status
-```
+Run `skeeper repair status`. If the failure happened before main-index mutation, fix network/auth or sidecar contention and run `skeeper repair resume`. If the main index was already mutated, inspect the listed files manually.
 
-Prints the sidecar URL, current source branch, one status block per namespace, last sync commit and age, remote state, tracked file counts, and pending queued syncs. No flags.
+**`skeeper.lock` conflicts during merge**
 
-</details>
+Run `skeeper hooks install` to ensure the merge driver is configured, then rerun the merge. Manual editing of scalar sidecar SHAs is unsupported; regenerate the lock through `skeeper merge-driver` or `skeeper sync`.
 
-<details>
-<summary><code>skeeper log &lt;path&gt;</code> — Show sidecar history for a spec file</summary>
+**`skeeper hydrate` is blocked by local managed files**
 
-```bash
-skeeper log <path>
-```
+Run `skeeper diff` to inspect exact paths. Use `skeeper reconcile --adopt-local` when the local files should be published into the sidecar, or `skeeper reconcile --prune-local` when they should be moved to rescue before restoring the locked content. Use `skeeper rescue list` and `skeeper rescue restore <id>` to recover pruned files.
 
-Runs `git log` against the sidecar for one spec file. The path is relative to the main repo root, e.g. `skeeper log src/auth/SPEC.md`. `skeeper` resolves the current owning namespace and reads `<namespace>/<path>` inside that namespace branch.
+**`verify` reports a lock mismatch**
 
-</details>
+The main commit and sidecar remote disagree. Run `skeeper sync`, include the updated `skeeper.lock`, and rerun `skeeper verify`.
 
-<details>
-<summary><code>skeeper version</code> — Print build metadata</summary>
+**A namespace overlaps another namespace**
 
-```bash
-skeeper version
-```
+Move shared files into exactly one namespace by adding `exclude:` entries. Skeeper does not use order-based precedence.
 
-Prints `Version`, `Commit`, and `BuildDate` injected at build time via ldflags.
+## 🚫 When Skeeper Is the Wrong Tool
 
-</details>
+- Repositories where specs already belong in the main diff and reviewers explicitly want them inline.
+- Teams that need PR review on the spec content itself before merge — Skeeper mirrors after the main commit succeeds, by design.
+- Repositories without a stable sidecar Git host: Skeeper fails the commit when the sidecar is unreachable (the audited `SKEEPER_SKIP=1` bypass exists, but it is not a substitute for a working remote).
+- Storing build artifacts, generated code, or large binaries. Default guardrails cap mutating plans at 100 files and 10 MiB on purpose.
 
 ## 🛠️ Development
 
 ```bash
-mise install      # provision Go 1.26.2, Bun 1.3.4, and CLI tools
+mise install
 bun install
 make hooks-install
-make verify       # fmt → lint → test → build (BLOCKING gate)
+make verify
 ```
 
 Common targets:
 
 ```bash
-make fmt          # gofmt every .go file
-make lint         # golangci-lint v2 + gopls modernize (zero tolerance)
-make test         # gotestsum + -race -parallel=4
-make build        # bin/skeeper with version ldflags
-make cover        # coverage.out + coverage.html
-```
-
-Releases are prepared through release pull requests and published with [GoReleaser Pro](.goreleaser.yml). A push to `main` creates or updates a release PR with `pr-release`; the release PR runs a GoReleaser dry run, and merging the release commit publishes GitHub release artifacts, the Homebrew cask, and the NPM package.
-
-Release publishing requires these GitHub Actions secrets:
-
-| Secret           | Purpose                                                       |
-| ---------------- | ------------------------------------------------------------- |
-| `RELEASE_TOKEN`  | Create/update release PRs, push release tags, update Homebrew |
-| `GORELEASER_KEY` | Run GoReleaser Pro                                            |
-| `NPM_TOKEN`      | Publish `@compozy/skeeper` and authenticate npm in release CI |
-
-Release notes are generated by `pr-release`. Add pending human-authored notes under `.release-notes/`; the release PR writes the current release body to `RELEASE_BODY.md` and prepends it to `RELEASE_NOTES.md`. The production workflow passes `RELEASE_BODY.md` to GoReleaser with the Skeeper release header and footer templates.
-
-Local release checks:
-
-```bash
-make release-snapshot  # requires GoReleaser Pro in PATH, or GORELEASER_KEY for the installer
+make fmt
+make lint
+make test
+make build
+make cover
+make release-snapshot
 ```
 
-Contributor guidance, commit conventions, and the agent skill dispatch protocol live in [`CLAUDE.md`](CLAUDE.md) and [`AGENTS.md`](AGENTS.md).
-
-## 🤖 Official Agent Skill
-
-`skeeper` ships its own first-party agent skill at [`skills/skeeper-project/SKILL.md`](skills/skeeper-project/SKILL.md). LLM agents working in this repository should load it before reading or modifying code — it captures the workflow, project rules, and verification gates that aren't obvious from the source alone, and points to `references/domain-map.md` and `references/repo-contract.md` for package boundaries and change rules.
-
-## 🤝 Contributing
-
-Contributions are welcome. Open an issue to discuss larger changes, or send a pull request for fixes and small improvements. All commits follow [Conventional Commits](https://www.conventionalcommits.org/) (`build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `test`), enforced by `commitlint`.
+Contributor guidance, commit conventions, and agent instructions live in [`CLAUDE.md`](CLAUDE.md) and [`AGENTS.md`](AGENTS.md).
 
 ## 📄 License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@compozy/skeeper",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Sidecar Git versioning for spec artifacts",
   "scripts": {
     "postinstall": "node install.js",
@@ -27,63 +27,63 @@
   },
   "archives": {
     "darwin-arm64": {
-      "name": "skeeper_0.1.1_darwin_arm64.tar.gz",
-      "url": "https://github.com/compozy/skeeper/releases/download/v0.1.1/skeeper_0.1.1_darwin_arm64.tar.gz",
+      "name": "skeeper_0.2.1_darwin_arm64.tar.gz",
+      "url": "https://github.com/compozy/skeeper/releases/download/v0.2.1/skeeper_0.2.1_darwin_arm64.tar.gz",
       "bins": [
         "skeeper"
       ],
       "format": "tar.gz",
       "checksum": {
         "algorithm": "sha256",
-        "digest": "8b1f41d35c843099df08c3f43b503fc2163dd0ffb77846be14f3b997e0742d9c"
+        "digest": "0ce0b122891566136533442e176b05decc990bbe4e17bf01b290065276104392"
       }
     },
     "darwin-x64": {
-      "name": "skeeper_0.1.1_darwin_x86_64.tar.gz",
-      "url": "https://github.com/compozy/skeeper/releases/download/v0.1.1/skeeper_0.1.1_darwin_x86_64.tar.gz",
+      "name": "skeeper_0.2.1_darwin_x86_64.tar.gz",
+      "url": "https://github.com/compozy/skeeper/releases/download/v0.2.1/skeeper_0.2.1_darwin_x86_64.tar.gz",
       "bins": [
         "skeeper"
       ],
       "format": "tar.gz",
       "checksum": {
         "algorithm": "sha256",
-        "digest": "f8e895b2a2206b15041dfd796d6c2df23e24f84a6272dae030ae929b62165a5a"
+        "digest": "5f7f2cf4ba83c3ed2f69eb388f04dce42b5e9f49009e307ede9b5200dcdc6621"
       }
     },
     "linux-arm64": {
-      "name": "skeeper_0.1.1_linux_arm64.tar.gz",
-      "url": "https://github.com/compozy/skeeper/releases/download/v0.1.1/skeeper_0.1.1_linux_arm64.tar.gz",
+      "name": "skeeper_0.2.1_linux_arm64.tar.gz",
+      "url": "https://github.com/compozy/skeeper/releases/download/v0.2.1/skeeper_0.2.1_linux_arm64.tar.gz",
       "bins": [
         "skeeper"
       ],
       "format": "tar.gz",
       "checksum": {
         "algorithm": "sha256",
-        "digest": "711dbee658801c1c388d7c87d5b0ab1e39035c872266768d4ddef6edfa7e2912"
+        "digest": "b10431032496f3091e2227ca2dd3fa660425f6224f1526b6086cb00a2f006396"
       }
     },
     "linux-x64": {
-      "name": "skeeper_0.1.1_linux_x86_64.tar.gz",
-      "url": "https://github.com/compozy/skeeper/releases/download/v0.1.1/skeeper_0.1.1_linux_x86_64.tar.gz",
+      "name": "skeeper_0.2.1_linux_x86_64.tar.gz",
+      "url": "https://github.com/compozy/skeeper/releases/download/v0.2.1/skeeper_0.2.1_linux_x86_64.tar.gz",
       "bins": [
         "skeeper"
       ],
       "format": "tar.gz",
       "checksum": {
         "algorithm": "sha256",
-        "digest": "76e72d20d8486e484b9789df69c19a327ad0307051554eaf7db078474a3cbbac"
+        "digest": "b913b1e145d0cb81f32c3b968e429810942237df0e3f93af2ebd10714409437d"
       }
     },
     "win32-x64": {
-      "name": "skeeper_0.1.1_windows_x86_64.zip",
-      "url": "https://github.com/compozy/skeeper/releases/download/v0.1.1/skeeper_0.1.1_windows_x86_64.zip",
+      "name": "skeeper_0.2.1_windows_x86_64.zip",
+      "url": "https://github.com/compozy/skeeper/releases/download/v0.2.1/skeeper_0.2.1_windows_x86_64.zip",
       "bins": [
         "skeeper.exe"
       ],
       "format": "zip",
       "checksum": {
         "algorithm": "sha256",
-        "digest": "b445168f2811e1a2948f434cc03c91fbe2bff9c0ae1bd64677dfec393ed02559"
+        "digest": "0dc47392a8427bf29242ee92e72971cb8b4020ee78c03e6477ee0467523f8dd3"
       }
     }
   }