@alessandroraffa/tangyr 0.21.6 → 1.0.0

package/README.md

@@ -324,6 +324,45 @@ declared via `.option()`. Commander delivers the positional argument's
 value as the `.action()` callback's first parameter, ahead of any options
 object — the reverse of every option-only command's callback signature.
 
+## The kit's instructions file
+
+One resolution, used by `install`, `sync`, every adapter and `verify` alike:
+
+1. `source.instructions` in `tangyr.config.yaml`, when set to something other than the `./AGENTS.md` default. An explicit declaration naming a file the kit does not carry is an error, reported before anything is written.
+2. `entrypoint` in `tangyr-kit.yaml`.
+3. `ORIENTATION.md`, then `AGENTS.md`, then the legacy `CLAUDE.md` (which installs, with a notice naming the rename).
+
+A kit whose entrypoint is `ORIENTATION.md` therefore needs no `source.instructions`, and `verify` recognises it.
+
+## Configuration file
+
+`tangyr.config.yaml` declares `schema: 1`. A key this schema does not define is rejected, naming the key it was probably meant to be — an unrecognized key is never read, so whatever it was meant to set stays at its default, and `target:` for `targets:` silently reduced an install to one tool. Prefix a key with `x-` to keep it as an annotation.
+
+In `tangyr-kit.yaml`, `discipline` is optional: declare it to opt into the corpus-version check, omit it for a kit that is not derived from the shared corpus.
+
+## Conflict policy
+
+Before writing, each destination is classified and resolved according to `onConflict` in `tangyr.config.yaml`: `ask` (default; prompts, and resolves to backup-and-replace in a non-interactive run), `skip`, `backup`, or `overwrite`.
+
+`--yes` supplies the confirmation a non-interactive run needs; it does **not** override the posture. Under `--yes`, `skip` leaves conflicting destinations unchanged and says which, `overwrite` replaces without a backup, and `backup` copies the existing file — or the existing directory, recursively — into `.tangyr/backups/<timestamp>/` and records it in the manifest so `uninstall` can put it back. A symlink is replaced without a backup: what it points at is untouched.
+
+One decision is taken per destination, not per target, so a file several targets write — `AGENTS.md` is claimed by four — is backed up once.
+
+## Accepted loss
+
+Some losses are structural: OpenCode expresses hooks only as plugin code, Cline has no committable persona file. A kit with hooks installed for OpenCode therefore exits `3` on every run, however correct the kit is.
+
+`acceptedLoss` names those, so that a genuinely new error entry is still loud:
+
+```yaml
+acceptedLoss:
+  - opencode/hook-as-plugin # <target>/<entry-type>
+  - cline/* # every error entry for one target
+  - persona-not-representable # this entry type on any target
+```
+
+`--ignore-errors` remains the blunt instrument: it suppresses the exit code for every error entry, including ones nobody has looked at yet.
+
 ## Exit codes
 
 The full exit-code taxonomy, in numeric order. Every code below `5`
@@ -353,6 +392,7 @@ reaches them).
 | ---------------------------- | ----------------------------------------------------------------------------------------------------- |
 | `--config <path>`            | Use an explicit configuration file                                                                    |
 | `--kit-path <path>`          | Use an explicit operating kit root                                                                    |
+| `--project-root <path>`      | Directory a project-scope operation writes into (see [Scope](#scope))                                 |
 | `--dry-run`                  | Report actions without modifying files                                                                |
 | `--yes`                      | Skip confirmation prompts                                                                             |
 | `--non-interactive`          | Never prompt; fail closed when a required input is missing (`auth login`)                             |
@@ -394,6 +434,17 @@ Every write command accepts `--scope global` or `--scope project`. The CLI flag
 | `global`  | `~/.tangyr/manifest.json` | `~/.claude/`                        |
 | `project` | `.tangyr/manifest.json`   | repo root (`AGENTS.md`, `.claude/`) |
 
+### Which directory is the project
+
+A project-scope operation resolves its root in this order:
+
+1. `--project-root <path>`, when given.
+2. The directory of the `tangyr.config.yaml` this run **discovered** — one found in the working directory or an ancestor. That file sits at the project root by construction, and `kitPath` is already resolved against it.
+3. The working directory, when the config was named explicitly with `-c`. An explicit path may name a shared or CI config outside the tree and says nothing about where the project is.
+4. The nearest enclosing directory carrying `tangyr.config.yaml` or `.tangyr/`, for the commands that run without a config at all; failing that, the working directory.
+
+Running from a subdirectory therefore installs at the project root rather than in the subdirectory. Deliberately only Tangyr's own markers are searched in step 4: a `package.json` or `.git` above the working directory says where some project starts, not that this installation belongs there.
+
 ## Multiple Claude Code global roots
 
 If you maintain more than one Claude Code account (e.g. `~/.claude` and `~/.claude-work`), you can keep them identical with a single sync operation.