bearings 0.5.3 → 0.5.5

package/README.md

@@ -1,6 +1,6 @@
 # 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 every generated file in a manifest, and leaves project-specific tailoring to your AI agent via `/setup-repo`.
+`bearings` sets up repository maps, commands, and skills for AI coding agents. It saves the scaffold, then opens one interactive agent to tailor it with you.
 
 Requires Node >= 24.
 
@@ -8,13 +8,17 @@ Requires Node >= 24.
 
 ```sh
 npx bearings init
-/setup-repo
-bearings verify
+npx bearings verify
 ```
 
-1. `npx bearings init` writes the generic scaffold and prints the next step.
-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.
+1. Run `npx bearings init` in the target repository from a real terminal.
+2. Choose one setup runner. Answer its project questions and permission prompts. In OpenCode, press **Enter** to submit the prefilled task. Claude Code may first ask you to trust the folder.
+3. The agent fills the seed and maps, tailors starter skills, and resolves backups. It runs the printed `init --complete-setup` command to validate and record completion. Exit the harness when done.
+4. Run `npx bearings verify` to check files, exposures, and remaining warnings.
+
+**Interrupted?** Run `npx bearings init` again. It resumes pending tasks and keeps completed work.
+
+**First setup or resume inside an agent session?** Use `npx bearings init --no-agent`. Follow the one scoped handoff it prints. For pending setup, `--yes`, piped input/output, and an unavailable harness CLI also leave a handoff instead of opening an agent. Ordinary updates require a real terminal for your decisions.
 
 Re-run `npx bearings init` later to update an initialized repository. There is no separate `update` verb — `init` dispatches on manifest state (ADR-0001).
 
@@ -27,6 +31,8 @@ docs/
   DOMAIN.md
   ARCHITECTURE.md
   CODEBASE_MAP.md
+  diagrams/
+    c4-component.puml  # created during first setup; not a scaffold/manifest file
   adr/
     INDEX.md
     0000-template.md
@@ -36,7 +42,7 @@ docs/
   bearings.json
   commands/
     refresh-repo-map.md
-    setup-repo.md
+    update-bearings-setup.md
   skills/
     commit-convention/SKILL.md
     defer-work/SKILL.md
@@ -50,11 +56,11 @@ docs/
   skills/*
 ```
 
-Every file carries an `owner` in the manifest. `bearings`-owned files (`CLAUDE.md`, the ADR template, and commands) are package-maintained — the incoming template is their canonical update source. Starter skills begin bearings-owned, then `/setup-repo` adapts and claims them as agent-owned. `agent`-owned files (`AGENTS.md`, the three maps, the two indexes, and claimed starter skills) are yours; bearings never overwrites them without an explicit per-file decision except for the starter-skill update handling below.
+Every generated file has an `owner` in `.agents/bearings.json`. Package-maintained files include `CLAUDE.md`, the ADR template, commands, and generic skill bundles. Starter skills begin bearings-owned; setup tailors them, then the completion command claims them as agent-owned and records baselines. The seed, maps, indexes, and claimed starter skills are agent-owned. Updates preserve local work as described below.
 
-`/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.
+First setup routes all four map tasks through `/refresh-repo-map`, including creation of `docs/diagrams/c4-component.puml`. The C4 source is a known first-setup output, not a scaffold or manifest file. Later updates remain limited to exact named map tasks and never add C4 because of an unrelated change.
 
-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.
+Existing files that collide with a scaffold target are backed up as `<path>.bkp` (with a numeric suffix if needed). Setup reviews the recorded backups before the completion command cleans them up.
 
 ## The Model
 
@@ -73,32 +79,44 @@ user task
 
 ### `bearings init`
 
-State-aware entry point. With no manifest it scaffolds; with a manifest it runs an interactive update; with a corrupt manifest it enters reconstruction.
+One entry point: scaffold a new repository, resume pending setup, update a completed repository, or reconstruct an invalid manifest.
 
 | 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. Fresh init only. |
+| `--copy` | Copy exposures instead of symlinking them. Completion refreshes copies for authorized setup edits; `verify` detects copy drift. |
+| `--setup-harness <name>` | Select one setup runner: `claude` or `opencode`. Exposure to both still launches only one runner. |
+| `--no-agent` | Suppress launch and print the scoped handoff. Use inside an existing agent session. |
+| `-y`, `--yes` | Accept fresh-init defaults and suppress launch. Ordinary updates still require interactive decisions. |
+| `--complete-setup` | Validate pending outputs and record completion, including skill claims, baselines, copy refresh, and artifact cleanup. |
+| `--setup-path <path...>` | With `--complete-setup` only: checkpoint these completed tasks and leave the others pending. |
+| `--keep-local <skill-path...>` | With `--complete-setup` only: decline the incoming template for these selected `skill-update` tasks. Preserve the local or agreed freeform content. |
+
+**Fresh init** — scans the repo, resolves harness/exposure, checks adapter collisions, then writes the scaffold, exposures, and v2 manifest. `setupPending` records `kind: init`, tasks with paths and reasons (`tailor`, `map`, or `reconcile`), and protected skills. Only after that state is saved does the selected interactive harness open with a direct first-setup task.
 
-**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`.
+**Resume and completion** — pending setup resumes before the ordinary update terminal check, without regenerating files. Partial checkpoints record output hashes and validated reconciliation artifacts. Final completion keeps one replaceable `completedSetup` receipt, so a successful agent exit, deleted artifacts, or a missing pending marker cannot prove completion by itself. Use `--complete-setup` to record progress; the CLI owns the manifest.
 
-**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:
+**Update** — requires a TTY and your decisions, even with `--yes`. It refuses version downgrades. Each managed file is classified against its 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 changed locally **and** in the template | Choose **Replace**, **Merge** (back up your content for `/update-bearings-setup`), or **Skip** (decline this revision; it will not 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 |
 | Claimed starter skill unchanged locally, template changed | Replaced silently; its agent owner is retained and its baseline is refreshed |
-| Claimed starter skill and template both changed | No CLI prompt: local content is preserved with backup, base, and incoming artifacts; `/setup-repo` guides the developer through a three-way resolution when the base exists |
-| Legacy bearings-owned starter skill and template both changed, with no baseline | No CLI prompt and no auto-claim: local content is preserved with backup and incoming artifacts; `verify` warns about the missing base and `/setup-repo` offers Take new template, Keep local, or Freeform |
+| Customized skill, upstream template unchanged | Preserved byte-for-byte by both the CLI and unrelated agent follow-up; excluded from task scope |
+| Claimed starter skill and template both changed | Local content, backup, base, and incoming template are preserved. `/update-bearings-setup` guides resolution; no CLI merge prompt |
+| Legacy starter skill with no historical baseline and changes on both sides | Local content, backup, and incoming template are preserved. The agent offers Take new template, Keep local, or Freeform; it does not invent a base |
 
 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`.
 
+**Only real pending work opens an agent.** Clean generic skill/checklist updates, adapter changes, version changes, and lossless migrations finish in the CLI. A clean starter replacement that introduces placeholders needs scoped tailoring. A map added or restored, an accepted map-template change, or an explicit map-format migration creates a task for that named map. Unrelated maps and customized skills stay outside the task scope.
+
+`/update-bearings-setup` handles update and reconstruction tasks only. It replaces `/setup-repo`; first setup uses the direct task from `init`. Customized old command content uses the normal Remove / Keep-and-untrack decision.
+
 **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`
@@ -112,9 +130,9 @@ Check the manifest and harness exposures for mechanical breakage. Exit code `0`
 | `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 | an `owner: agent` file still contains a complete single-line agent placeholder marker (bearings-owned files are not checked) |
+| `copy-drift` | fail | copy mode: harness content differs from `.agents` source; the disposable checklist `data.generated.js` payload is excluded |
+| `setup-pending` | warn | first setup or update tasks remain unfinished |
+| `unfilled-placeholder` | warn | an agent-owned file or starter skill still contains a complete single-line agent placeholder marker |
 | `missing-skill-baseline` | warn | an agent-owned starter skill or pending `skill-update` reconciliation has no skill baseline file |
 | `unreviewed-backup` | warn | manifest `backup` path still exists on disk |
 | `pending-reconciliation` | warn | a reconciliation artifact, including a skill-update backup or incoming file, is still unresolved |
@@ -132,4 +150,4 @@ npm run build
 - `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.
+This repo is maintained by bearings itself; see `AGENTS.md` for the dogfooding ownership rules before editing any managed file. `templates/**` is product source for future scaffolds. Do not mirror template edits into this repo's managed copies; divergence is the dogfood signal.