bearings 0.3.1 → 0.3.2

package/README.md

@@ -1,6 +1,8 @@
 # bearings
 
-`bearings` is a small TypeScript CLI that helps you give your agents their bearings: it scaffolds an agent-friendly repository setup, exposes shared skills and commands to supported harnesses, records the generated files in a manifest, and leaves project-specific tailoring to your AI agent via `/setup-repo`.
+`bearings` is a small TypeScript CLI that helps you give your agents their bearings: it scaffolds an agent-friendly repository setup, exposes shared skills and commands to supported harnesses, records every generated file in a manifest, and leaves project-specific tailoring to your AI agent via `/setup-repo`.
+
+Requires Node >= 24.
 
 ## Quick Start
 
@@ -11,9 +13,11 @@ bearings verify
 ```
 
 1. `npx bearings init` writes the generic scaffold and prints the next step.
-2. `/setup-repo` runs inside your AI agent to merge backups, fill placeholders, seed docs, and tailor skills.
+2. `/setup-repo` runs inside your AI agent to review backups, fill placeholders, seed docs, and tailor the setup.
 3. `bearings verify` checks the scaffold for drift, missing files, broken exposures, and unresolved setup warnings.
 
+Re-run `npx bearings init` later to update an initialized repository. There is no separate `update` verb — `init` dispatches on manifest state (ADR-0001).
+
 ## What Gets Generated
 
 ```text
@@ -46,9 +50,11 @@ docs/
   skills/*
 ```
 
+Every file carries an `owner` in the manifest. `bearings`-owned files (`CLAUDE.md`, the ADR template, commands, skills) are package-maintained — the incoming template is their canonical update source. `agent`-owned files (`AGENTS.md`, the three maps, the two indexes) are yours; bearings never overwrites them without an explicit per-file decision.
+
 `/setup-repo` creates `docs/diagrams/c4-component.puml` (via `/refresh-repo-map`) once the repo is tailored; it is not part of the generated scaffold or the manifest.
 
-Existing scaffold targets are backed up as `<path>.bkp` before replacement. Re-running `init` skips unchanged managed files.
+Existing files that collide with a scaffold target are backed up as `<path>.bkp` before replacement, and the backup is recorded as a pending reconciliation for `/setup-repo` to resolve.
 
 ## The Model
 
@@ -67,24 +73,59 @@ user task
 
 ### `bearings init`
 
-Scaffold the agent-friendly setup in the current repository.
+State-aware entry point. With no manifest it scaffolds; with a manifest it runs an interactive update; with a corrupt manifest it enters reconstruction.
 
 | Flag | Meaning |
 |---|---|
 | `--harness <name...>` | Expose to `claude` and/or `opencode`. Defaults to detected harness dirs, or both in a fresh repo. |
 | `--copy` | Copy exposures instead of symlinking them. `verify` checks copy drift. |
-| `-y`, `--yes` | Accept defaults and do not prompt. |
+| `-y`, `--yes` | Accept defaults and do not prompt. Fresh init only. |
+
+**Fresh init** — scans the repo, resolves harness/exposure, aborts on unmanaged adapter collisions before writing anything, generates the scaffold, exposes `.agents/{commands,skills}/*` per harness, writes the v2 manifest, and hands off to `/setup-repo`.
+
+**Update** — interactive only (requires a TTY; `--yes` has no effect). It refuses to downgrade the recorded bearings version and refuses to start while a prior update's `/setup-repo` handoff is still pending. Each managed file is classified against its manifest baseline:
+
+| Situation | What happens |
+|---|---|
+| Content matches baseline | Kept silently |
+| Template changed, file unchanged locally | Replaced |
+| File changed locally **and** in the template | Conflict — you choose **Replace**, **Merge** (back up your content for `/setup-repo`), or **Skip** (decline this revision; it won't re-prompt) |
+| File no longer shipped, unchanged locally | Removed |
+| File no longer shipped, changed locally | You choose **Remove** or **Keep and untrack** |
+| New scaffold path already occupied | Conflict, resolved the same way |
+
+Adapter changes (harness added/removed, symlink↔copy switch) are planned alongside. The full plan is shown and confirmed before any mutation, then applied as a single transaction — the manifest is written last, and any failure restores the exact prior state. A run that changes nothing reports `already up to date`.
+
+**Reconstruction** — when the manifest is missing fields, hash-broken, or otherwise invalid, harness and exposure config is detected from the adapters on disk, confirmed with you, and a fresh v2 manifest is rebuilt.
 
 ### `bearings verify`
 
-Check the manifest and harness exposures for mechanical breakage. Exit code `0` means no failures; exit code `1` means one or more failures.
+Check the manifest and harness exposures for mechanical breakage. Exit code `0` means no failures; exit code `1` means one or more failures. Warnings never affect the exit code.
 
 | Code | Severity | Condition |
 |---|---|---|
 | `no-manifest` | fail | `.agents/bearings.json` missing |
+| `invalid-manifest` | fail | manifest fails structural validation |
 | `missing-file` | fail | manifest entry path doesn't exist |
 | `missing-exposure` | fail | a child of `.agents/skills` or `.agents/commands` absent from a configured harness dir |
 | `broken-symlink` | fail | harness entry is a symlink whose target doesn't resolve |
 | `copy-drift` | fail | copy mode: harness file content differs from `.agents` source content |
+| `setup-pending` | warn | an update finished but `/setup-repo` hasn't run yet |
 | `unfilled-placeholder` | warn | a bearings-generated file still contains `<agent:` |
 | `unreviewed-backup` | warn | manifest `backup` path still exists on disk |
+| `pending-reconciliation` | warn | a recorded backup from a collision or Merge is still unresolved |
+
+## Development
+
+```sh
+npm test     # rebuilds dist/ via pretest, then runs the full Vitest suite
+npm run build
+```
+
+- `docs/ARCHITECTURE.md` — components, dependency direction, build shape.
+- `docs/CODEBASE_MAP.md` — capability-to-source routing with `path#symbol` anchors.
+- `docs/DOMAIN.md` — terminology, workflows, and domain rules.
+- `docs/adr/INDEX.md` — consequential decisions.
+- `docs/qa/RELEASE_QA.md` — manual pre-release tiers, staged by `node scripts/qa.ts setup`.
+
+This repo is maintained by bearings itself; see `AGENTS.md` for the dogfooding ownership rules before editing any managed file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bearings",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Give your AI agents their bearings — scaffold an agent-friendly setup in any repository.",
   "type": "module",
   "engines": {