@rness/cli 0.6.2 → 0.8.0

package/README.md

@@ -20,10 +20,10 @@ Inside a workspace, every `rness` delegates to the copy pinned in
 
 ## Commands
 
-    rness create [<org>] [--repos a,b] [--pm npm|pnpm|yarn|bun] [--ssh|--https] [--skip-install] -y
-    rness create <name> --blank [--pm npm|pnpm|yarn|bun] [--skip-install] -y
+    rness create [<org>] [--repos a,b] [--agent claude] [--pm npm|pnpm|yarn|bun] [--ssh|--https] [--skip-install] -y
+    rness create <name> --blank [--agent claude] [--pm npm|pnpm|yarn|bun] [--skip-install] -y
     rness add <repo> [--scopes apps/web,packages/ui] [--ssh|--https] -y
-    rness sync [--all] [--scope <name>] [--check] [--pull] -y
+    rness sync [--all] [--scope <name>] [--check] [--pull] [--agent <name>] -y
     rness upgrade [<version>] -y
     rness login [--setup-git|--no-setup-git]
     rness logout
@@ -40,6 +40,35 @@ writes nothing and exits 1 when a block is out of date — use it in CI.
 `.rness/` goes to the network. Bring repositories in with
 `rness add <owner>/<repo>` or a git URL — a bare name needs an `"org"`.
 
+### Agent targets
+
+The `AGENTS.md` block is what every agent reads. On top of it, rness writes
+the files a given agent needs, for the agents the team declares in
+`rness.json`:
+
+    rness sync --agent claude     # declare claude, then write its files
+    rness sync                    # in a terminal, with nothing declared, asks once
+
+```json
+{ "contract": 1, "org": "acme", "agents": ["claude"], "repos": { … }, "scopes": { … } }
+```
+
+- `agents` is the team's: the files it produces are committed in each
+  repository. `[]` means none; without the key, `sync` asks in a terminal and
+  never in scripts (`-y`, `--check`). A new workspace asks with `create`'s
+  other questions, or takes `--agent`.
+- **Claude Code** (`claude`): each clone gets `.claude/settings.json` with
+  `../../.rness` in `permissions.additionalDirectories`, so a session in the
+  repository reads the context repository without a prompt. Claude Code
+  applies it once the repository has been trusted interactively. Verified
+  with Claude Code 2.1.284 on 2026-09-29.
+- rness owns values, not files: what is missing is added, nothing else is
+  touched, and a file it cannot parse is reported, never rewritten.
+  `sync --check` and `validate` report a missing value. Removing an agent
+  from `agents` leaves its values in place; `sync` says where.
+- Other agents (Codex, Cursor, GitHub Copilot) read the `AGENTS.md` block;
+  `sync` refuses an agent it has no target for.
+
 ### Log in
 
     rness login     # shows a code and https://github.com/login/device
@@ -109,7 +138,8 @@ dependency does this: `util.styleText`, and a banner kept as a constant.
 ### Upgrade
 
     rness upgrade            # the latest release; `rness upgrade 0.5.0` for another
-    npx @rness/cli@latest upgrade     # from a workspace pinned below 0.5.0
+    npx @rness/cli@latest upgrade     # your global rness is older than the pin, or the pin is below 0.5.0
+    pnpm rness upgrade       # inside .rness: the pinned copy merges its own scaffold
 
 The version is written in one place, `.rness/package.json`. `upgrade` pins it
 there (exact, the rest of the file untouched), installs with the workspace's
@@ -127,18 +157,44 @@ or later, which checks for itself whatever launched it. With an older global
 and a workspace below 0.5.3, a pin that moved is neither installed nor
 announced: `npm i -g @rness/cli@latest` once.
 
-Usually nobody runs `upgrade` at all. A workspace ships
-`.github/dependabot.yml`, so each release opens a pull request on the
-organization's `.rness`: the pin and the lockfile in the diff, `validate`
-running on the new version, review, merge. `upgrade` writes that file into
-workspaces created before 0.5.1. The pull request arrives 3 to 10 days after
-a release: the check is weekly, and Dependabot holds any new version back for
-3 days by default, a guard against a compromised release. The file's header
-says how to lift that delay for `@rness/cli`.
+A workspace ships `.github/dependabot.yml`, so each release opens a pull
+request on the organization's `.rness`: the pin and the lockfile in the diff,
+`validate` running on the new version, review, merge. The pull request
+arrives 3 to 10 days after a release: the check is weekly, and Dependabot
+holds any new version back for 3 days by default, a guard against a
+compromised release. The file's header says how to lift that delay for
+`@rness/cli`.
+
+`upgrade` also merges the scaffold of the target version into `.rness`, with
+git: the CI workflow, the hooks, the starter documents. After a Dependabot
+pull request, run it once more to merge the scaffold of the version the pin
+now names; `rness validate` warns while it is behind.
+
+    rness upgrade
+    merging  the @rness/cli 0.8.0 scaffold
+    added    .github/workflows/validate.yml
+    updated  .githooks/pre-commit
+    merged   AGENTS.md
+
+- The base is the last scaffold commit of `.rness`: the commit `create` made,
+  or the previous `chore: rness scaffold <version>`. A file the team never
+  touched takes the new version; an edited one keeps its edits where the
+  scaffold did not change; overlapping lines conflict, and `upgrade` stops
+  before installing — resolve with git (`git checkout --ours <file>` keeps
+  yours, `--theirs` takes the scaffold's), commit, run `upgrade` again.
+- `.rness` must be a clean git repository. The merge is staged, not
+  committed: the next steps end in one commit.
+- A workspace with no scaffold commit (made by hand, or older than
+  `create`) is adopted: identical files merge silently, a differing one
+  conflicts once.
+- Merge an upgrade pull request with a merge commit, not a squash: a squash
+  drops the scaffold commit, and the next upgrade falls back to an older base.
 
 `upgrade` is never delegated to the pinned copy, which is what it replaces
-— so a workspace pinned below 0.5.0, whose copy has no such command, starts
-with the `npx` form.
+— so it runs the copy you typed. A global `rness` older than the pin answers
+"already at" and merges no scaffold: use the `npx` form, or the pinned copy
+from inside `.rness`. A workspace pinned below 0.5.0, whose copy has no such
+command, starts with the `npx` form.
 
 An upgrade touches `.rness` only: a generated block is current when its hash
 is, whatever wrote it, so no `AGENTS.md` of the organization changes unless
@@ -147,6 +203,33 @@ its content does.
 Exit codes: 0 success, 1 failure, 2 usage — or a refusal without a TTY.
 `RNESS_DEBUG=1` adds stack traces; `RNESS_NO_DELEGATE=1` skips the delegation.
 
+## 0.8.0 — upgrade merges the scaffold
+
+- `rness upgrade` merges the target version's scaffold into `.rness` with
+  git, three-way, from the last scaffold commit: files the team never
+  touched are updated, edits are kept, overlaps conflict and stop the
+  upgrade before the install. See "Upgrade". After a Dependabot pull request,
+  run `rness upgrade` once to merge the scaffold; nothing is installed.
+- `rness validate` warns while the merged scaffold is behind the pin.
+- The commit `create` makes carries `Rness-Scaffold: <version>`.
+- Breaking: `upgrade` refuses a `.rness` that is not a clean git repository.
+  The two migrations it carried (an old `validate.yml` line, a missing
+  `dependabot.yml`) are what the merge does now.
+- Blocks are unchanged: no `rness sync` is needed after upgrading.
+
+## 0.7.0 — agent targets: Claude Code
+
+- `rness.json` may declare the team's agents: `"agents": ["claude"]`. It is
+  an optional key of contract 1; no block changes. A CLI older than 0.7.0
+  refuses the key: move the pin before declaring an agent.
+- `rness sync --agent claude` declares it and writes each clone's
+  `.claude/settings.json` (`../../.rness` in
+  `permissions.additionalDirectories`). In a terminal with nothing declared,
+  `sync` asks once which agents the team uses; `create` asks for a new
+  workspace, or takes `--agent`.
+- `sync --check` and `validate` cover the agent files, and `sync --pull`
+  does not count them as local changes. See "Agent targets".
+
 ## 0.6.2 — no dialog for the root CLAUDE.md
 
 - Opening Claude Code in a repository of the workspace no longer asks "Allow

package/dist/bin/rness.js

@@ -6,7 +6,7 @@ import {
   findDelegate,
   reportError,
   run
-} from "../chunk-7TOHFPW6.js";
+} from "../chunk-VQMX52HT.js";
 
 // src/bin/rness.ts
 import { pathToFileURL } from "url";