@evertonferreira96/agents 0.1.1 → 0.1.3

package/README.md

@@ -1,15 +1,504 @@
+<div align="center">
+
 # agents
 
-Personal agent and subagent configuration for Claude Code, portable to Cursor and Codex through `AGENTS.md`.
+**Agents, rules, hooks and skills for Claude Code, installed into any project with one command.**
+
+[![npm](https://img.shields.io/npm/v/@evertonferreira96/agents?label=npm&color=cb3837)](https://www.npmjs.com/package/@evertonferreira96/agents)
+[![node](https://img.shields.io/node/v/@evertonferreira96/agents?color=339933)](package.json)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-agents%20%C2%B7%20rules%20%C2%B7%20hooks%20%C2%B7%20skills-d97757)](docs/README.md)
+[![Cursor and Codex](https://img.shields.io/badge/Cursor%20%26%20Codex-AGENTS.md-555555)](AGENTS.md)
+
+</div>
+
+---
+
+## Contents
+
+- [What it is](#what-it-is)
+- [Quick start](#quick-start)
+- [How it works](#how-it-works)
+  - [The big picture](#the-big-picture)
+  - [What `setup:pull` does, step by step](#what-setuppull-does-step-by-step)
+  - [How each file is decided](#how-each-file-is-decided)
+  - [Projects that already have an AGENTS.md](#projects-that-already-have-an-agentsmd)
+  - [What lands in your project](#what-lands-in-your-project)
+- [Working in a configured project](#working-in-a-configured-project)
+- [Command reference](#command-reference)
+- [Release pipeline](#release-pipeline)
+- [Maintaining this repo](#maintaining-this-repo)
+- [Troubleshooting](#troubleshooting)
+- [Further reading](#further-reading)
+
+---
+
+## What it is
+
+A complete working setup for Claude Code, kept in one repo and shipped as the npm package `@evertonferreira96/agents`. Install it once per machine, run one command in a project, and the project gets the same team of agents, the same guardrails and the same architecture playbooks as every other project.
+
+| Piece | What you get |
+|---|---|
+| **Agents** (10) | An orchestrator flow plus specialists: `quick`, `product`, `architect`, `api`, `web`, `app`, `infra`, `ui`, `verifier`, `security` |
+| **Skills** (37) | Workflow (orchestrate, triage, brief, review, grilling, handoff, retro), architecture (`arch-api`, `arch-web`, `arch-app`, `arch-db`), quality (tdd, diagnosing-bugs, ponytail), design and motion |
+| **Rules** (9) | Loaded always or by path glob: git, tickets, api, web, mobile, db, ui, graphify, delivery diagram |
+| **Hooks** (8) | Deterministic guards that block what rules can only ask for: `git push`, `git add -A`, staging `.env`, the orchestrator editing code, lint and tests on Stop |
+| **AGENTS.md** | The shared base that Cursor and Codex read too |
+| **Updates** | A manifest of every installed file, so updates refresh what you did not touch and never overwrite what you changed |
+
+---
+
+## Quick start
+
+**Requirements:** Node.js 18 or newer, npm, and Claude Code.
+
+```bash
+# 1. once per machine
+npm install -g @evertonferreira96/agents
+
+# 2. in the root of any project, new or already configured
+cd path/to/your-project
+chew agents setup:pull
+```
+
+3. Fill in the project's purpose and commands in the generated `CLAUDE.md`.
+4. Open Claude Code in the project and describe the task.
+
+To update later, run `chew agents setup:pull` again. Every run downloads the latest published version, so the global install does not need to be current.
+
+<details>
+<summary>Without a global install</summary>
+
+```bash
+npx @evertonferreira96/agents init            # first time
+npx @evertonferreira96/agents@latest update   # later
+npx @evertonferreira96/agents check           # drift report
+```
+
+</details>
+
+---
+
+## How it works
+
+### The big picture
+
+The config lives in this repo. Every push to `main` that changes a shipped file is checked, versioned and published. On your machine, `chew` pulls the newest published version into the project you are in.
+
+```mermaid
+flowchart LR
+    subgraph REPO["This repo on GitHub"]
+        SRC[".claude/ agents, rules, skills, hooks<br/>AGENTS.md, templates, scripts"]
+    end
+
+    subgraph CI["GitHub Actions"]
+        CHECK["check.yml<br/>parse, catalog, tests"]
+        REL["release.yml<br/>version, publish, tag, release"]
+        CHECK --> REL
+    end
+
+    subgraph REG["Registries"]
+        NPM[("npmjs.com<br/>public")]
+        GHP[("GitHub Packages<br/>private")]
+    end
+
+    subgraph DEV["Your machine"]
+        CHEW["chew<br/>global CLI"]
+        PROJ["your-project/<br/>.claude/ AGENTS.md CLAUDE.md"]
+    end
+
+    SRC -- "git push main" --> CHECK
+    REL -- "npm publish" --> NPM
+    REL -- "npm publish" --> GHP
+    NPM -- "latest tarball" --> CHEW
+    CHEW -- "chew agents setup:pull" --> PROJ
+```
+
+### What `setup:pull` does, step by step
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor You
+    participant Chew as chew (global)
+    participant Npm as npmjs.com
+    participant Tmp as Temp folder
+    participant Engine as Install engine (downloaded)
+    participant Proj as Your project
+
+    You->>Chew: chew agents setup:pull
+    alt registry reachable
+        Chew->>Npm: npm pack @evertonferreira96/agents@latest
+        Npm-->>Chew: agents-X.Y.Z.tgz
+        Chew->>Tmp: extract the package
+        Chew->>Engine: load scripts/bootstrap.mjs from version X.Y.Z
+    else offline or blocked
+        Chew-->>You: warning, using the version installed with chew
+    end
+    Engine->>Proj: read .claude/config-manifest.json (if any)
+    Engine->>Proj: add, update or remove files, one decision per file
+    Engine->>Proj: write manifest, config-source.json, CLAUDE.md (once), .gitignore lines
+    Chew->>Tmp: delete the temp folder
+    Chew-->>You: report: added, updated, removed, kept
+```
+
+1. **Download.** `chew` asks npm for the latest version, always against the public registry (also for the `@evertonferreira96` scope), so a user `.npmrc` that points to another feed does not interfere.
+2. **Extract.** The tarball is unpacked into a temporary folder.
+3. **Use the new engine.** The install runs with the `bootstrap.mjs` of the downloaded version, not the one installed with `chew`. An old global `chew` still applies the newest config and only prints a hint to update itself.
+4. **Decide file by file.** Each shipped file is compared with the project copy and with the manifest of the last install (next section).
+5. **Record.** `.claude/config-manifest.json` stores the hash of every installed file; `.claude/config-source.json` stores the package and version.
+6. **First run only.** `CLAUDE.md` is created from `templates/CLAUDE.project.md`, and the `.gitignore` entries are appended.
+7. **Clean up and report.** The temp folder is deleted and the result is printed.
+
+### How each file is decided
+
+The manifest is what makes updates safe. It records the hash each file had when the config installed it, so the engine can tell a file that is only **outdated** (safe to refresh) from one you **edited** (kept).
+
+```mermaid
+flowchart TD
+    A["File shipped by the latest version"] --> B{"Exists in<br/>the project?"}
+    B -- no --> ADD["added"]
+    B -- yes --> C{"Same content?"}
+    C -- yes --> SAME["unchanged"]
+    C -- no --> D{"Project copy matches<br/>the manifest hash?"}
+    D -- "yes: untouched,<br/>only outdated" --> UPD["updated"]
+    D -- "no: edited here" --> F{"run with<br/>force flag?"}
+    F -- yes --> UPD
+    F -- no --> KEPT["kept<br/>listed as edited"]
+
+    O["File in the manifest that the<br/>latest version no longer ships"] --> G{"Untouched?"}
+    G -- yes --> DEL["removed"]
+    G -- no --> OBS["kept<br/>listed as obsolete"]
+
+    classDef add fill:#dcfce7,stroke:#16a34a,color:#14532d
+    classDef upd fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
+    classDef keep fill:#fef3c7,stroke:#d97706,color:#78350f
+    classDef del fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
+    classDef same fill:#f3f4f6,stroke:#9ca3af,color:#374151
+    class ADD add
+    class UPD upd
+    class KEPT,OBS keep
+    class DEL del
+    class SAME same
+```
+
+**Never touched, not even with `--force`:** `CLAUDE.md`, `.claude/settings.local.json` and `.claude/agent-memory/**`.
+
+| Situation | Result |
+|---|---|
+| New project, nothing installed | Everything added, `CLAUDE.md` created, `.gitignore` extended |
+| Configured project, nothing edited | New files added, changed files updated, removed files deleted |
+| You edited a shipped file | Kept and listed; `--force` replaces it with the config version |
+| Project configured before the manifest existed | Differing files count as edited; review them, then run `--force` once |
+| The project has its own `AGENTS.md` | You choose: keep, overwrite, append or print ([next section](#projects-that-already-have-an-agentsmd)) |
+
+### Projects that already have an AGENTS.md
+
+Many projects already carry an `AGENTS.md` with their own rules. When the project copy differs from the config, `setup:pull` asks what to do. Press Enter to keep yours; outside a terminal (CI, scripts) it keeps yours and lists the options.
+
+```text
+AGENTS.md already exists in this project and differs from the config. What should happen to it?
+  [k] keep yours as it is (default)
+  [o] overwrite it with the config version
+  [a] append the config version at the end, in a managed block that later pulls keep current
+  [p] print the config version here, to concatenate it yourself
+Choice [k/o/a/p]:
+```
+
+```mermaid
+flowchart TD
+    A["Project AGENTS.md differs<br/>from the config"] --> B{"Has a managed block?"}
+    B -- yes --> RB["Refresh only the block<br/>no question asked"]
+    B -- no --> Q{"Your choice<br/>prompt or --agents-md"}
+    Q -- keep --> K["Yours stays as it is"]
+    Q -- overwrite --> O["Replaced by the config version<br/>later pulls keep it current"]
+    Q -- append --> AP["Config version added at the end<br/>inside the managed block"]
+    Q -- print --> P["Config version printed<br/>you paste it where you want"]
+    AP -. "next pull" .-> RB
+    P -. "pasted with the markers" .-> RB
+
+    classDef keep fill:#f3f4f6,stroke:#9ca3af,color:#374151
+    classDef upd fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
+    classDef add fill:#dcfce7,stroke:#16a34a,color:#14532d
+    classDef out fill:#fef3c7,stroke:#d97706,color:#78350f
+    class K keep
+    class O,RB upd
+    class AP add
+    class P out
+```
+
+The managed block is plain Markdown between two comments. Everything outside the markers is yours; later pulls replace only what is inside them:
+
+```markdown
+# My project
+Rules that belong to this project.
+
+<!-- agents-config:start -->
+<!-- Managed by @evertonferreira96/agents: `chew agents setup:pull` refreshes this block. Edit outside the markers. -->
+...the config AGENTS.md...
+<!-- agents-config:end -->
+```
+
+| Want | Command |
+|---|---|
+| Decide without the question | `chew agents setup:pull --agents-md=keep` (or `overwrite`, `append`, `print`) |
+| Just see the config version | `chew agents setup:print` (in the managed block) or `chew agents setup:print --raw` (file alone) |
+| Concatenate from the shell | `chew agents setup:print >> AGENTS.md` (bash, zsh, cmd; in Windows PowerShell 5, `>>` writes UTF-16, so use `--agents-md=append`) |
+
+### What lands in your project
+
+```text
+your-project/
+├── AGENTS.md                  shared base (Claude Code, Cursor, Codex)
+├── CLAUDE.md                  created once from the template, then yours
+├── .worktreeinclude           files copied into each task worktree
+├── .gitignore                 + worktrees, handoffs, local settings, graphify-out
+├── skills-lock.json           origin and hash of every vendored skill
+├── docs/
+│   ├── plans/README.md        plan template, one plan per task
+│   ├── adr/README.md          ADR template
+│   └── brief-template.md
+├── scripts/                   bootstrap, check-catalog, skills-update
+└── .claude/
+    ├── agents/                10 agents
+    ├── skills/                37 skills
+    ├── rules/                 9 rules
+    ├── hooks/                 8 hooks
+    ├── settings.json          hook wiring, worktree base, context limits
+    ├── config-manifest.json   hash of every installed file (commit it)
+    └── config-source.json     installed package and version
+```
+
+---
+
+## Working in a configured project
+
+Open Claude Code and describe the task, paste the ticket or paste the error. The main session acts as the orchestrator: it sizes the work, plans it with you and delegates it. It never edits code itself (a hook enforces this).
+
+```mermaid
+flowchart TD
+    REQ["Task, ticket or error"] --> RAW{"Raw report?"}
+    RAW -- yes --> TRI["triage<br/>classify, reproduce, brief"]
+    RAW -- no --> CLS{"Size"}
+    TRI --> CLS
+
+    CLS -- "S: one file,<br/>one-sentence diff" --> QK["quick agent"]
+    QK --> STOP["Stop hook<br/>lint and tests"]
+
+    CLS -- "M or L" --> WT["Task worktree<br/>.claude/worktrees/slug"]
+    WT --> GRL["Grill with you<br/>L always, M on open decisions"]
+    GRL --> PRD["product agent<br/>scope, AC, test seams, tickets"]
+    PRD -- "L or architecture trigger" --> ARC["architect agent"]
+    PRD -- M --> GATE
+    ARC --> GATE{"You approve<br/>the tickets"}
+    GATE --> IMP["One implementer per ticket<br/>api, web, app, infra, ui<br/>test-first with tdd"]
+    IMP --> INT["Integrate"]
+    INT --> VER["verifier agent<br/>Spec axis, then Standards axis"]
+    VER -- "auth, secrets, PII, payments" --> SEC["security agent"]
+    VER --> CMT["Commit and report"]
+    SEC --> CMT
+    CMT -- L --> RET["retro<br/>lessons become hooks or rules"]
+
+    classDef you fill:#fef3c7,stroke:#d97706,color:#78350f
+    classDef agent fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
+    classDef guard fill:#dcfce7,stroke:#16a34a,color:#14532d
+    class GRL,GATE you
+    class QK,PRD,ARC,IMP,VER,SEC agent
+    class STOP guard
+```
+
+<sub>Amber: steps with you. Blue: agents. Green: hooks.</sub>
+
+| Agent | Does | Mode |
+|---|---|---|
+| `quick` | S work: one file, one-sentence diff | writes |
+| `product` | Plan: scope, stories, acceptance criteria, test seams, tickets | read-only |
+| `architect` | Boundaries, contracts, failure modes; verdict and ADR proposal | read-only |
+| `api` | Server side: APIs, domain, persistence, workers (`arch-api`, `arch-db`, `tdd`) | writes |
+| `web` | Next.js app (`arch-web`, `tdd`) | writes |
+| `app` | React Native / Expo app (`arch-app`, `tdd`) | writes |
+| `infra` | Terraform, CI, deploy, observability; never applies | writes |
+| `ui` | Design system, tokens, components, motion, accessibility | writes |
+| `verifier` | Fresh-context check of the diff against the plan; runs lint, build, tests | no edits |
+| `security` | Auth, secrets, PII, payments, public routes; severity report | read-only |
+
+**Guardrails enforced by hooks**
+
+| Hook | Effect |
+|---|---|
+| `guard-bash` | Blocks `git push`, `git add -A` / `.`, staging `.env*`, `--no-verify`, `reset --hard`, `clean -f`, PR and issue writes |
+| `orchestrator-guard` | The main session can edit plans, ADRs and docs, never code |
+| `readonly-guard` | Read-only agents can only write their own memory |
+| `stop-verify` | Lint and tests on Stop when the tree changed |
+| `context-budget` | Warns at 60k, 90k and 110k tokens; compaction at 120k |
+| `post-compact` | Re-injects the active plan after compaction |
+| `graphify-update` | Refreshes the code graph after edits, when one exists |
+| `config-update-check` | One line at session start when a local-clone install has a newer version |
+
+The full flow, with every section of the playbook, is in [`.claude/skills/orchestrate/SKILL.md`](.claude/skills/orchestrate/SKILL.md). A five-minute walkthrough is in [docs/quickstart.md](docs/quickstart.md).
+
+---
+
+## Command reference
+
+### `chew` (global)
+
+| Command | What it does |
+|---|---|
+| `chew agents setup:pull [dir]` | Download the latest version and install or refresh it in `dir` (default: current folder) |
+| `chew agents setup:check [dir]` | Compare the project with the latest version; exit code 1 on drift |
+| `chew agents setup:print` | Print the latest config `AGENTS.md` in its managed block, to concatenate into yours (`--raw`: the file alone) |
+| `chew --version` | Version of the installed `chew` |
+
+| Flag | Effect |
+|---|---|
+| `--force` | Also overwrite files edited in the project (protected files excepted) |
+| `--dry-run` | Show what would change, write nothing |
+| `--local` | Use the version installed with `chew` instead of downloading |
+| `--agents-md=<choice>` | When the project has its own `AGENTS.md`: `keep` (default), `overwrite`, `append` or `print`; skips the question |
+
+### `agents` (same package, via `npx` or global)
+
+| Command | What it does |
+|---|---|
+| `agents init [dir]` | Copy what is missing; never overwrites |
+| `agents update [dir]` | Same rules as `setup:pull`, using this installed version |
+| `agents check [dir]` | Report missing, outdated, edited and obsolete files; exit 1 on drift |
+| `agents print-agents-md` | Same as `chew agents setup:print`, for this installed version |
+
+`init` and `update` accept `--force`, `--dry-run` and `--agents-md=<choice>`, like `chew`.
+
+### Legacy, from a local clone
+
+```bash
+node <agents-repo>/scripts/bootstrap.mjs <project>          # init
+node <agents-repo>/scripts/bootstrap.mjs <project> --check  # drift report
+node scripts/bootstrap.mjs --sync                           # inside the project: pull the clone, then update
+```
+
+---
+
+## Release pipeline
+
+Every push to `main` that changes a shipped file (`.claude/**`, `AGENTS.md`, `bin/`, `scripts/`, `templates/`, `package.json`, `VERSION`, the workflow itself) publishes a new version. Pushes that change only files the package does not ship (this README, the CHANGELOG, most of `docs/`) do not.
+
+```mermaid
+flowchart LR
+    PUSH["push to main"] --> CHK["check.yml<br/>hooks and scripts parse<br/>JSON, catalog, em-dash scan<br/>npm test, npm pack"]
+    CHK --> VER["release-version.mjs<br/>picks X.Y.Z"]
+    VER --> PUB["npm publish<br/>npmjs.com"]
+    PUB --> TAG["git tag vX.Y.Z"]
+    TAG --> GHR["GitHub release<br/>notes from commits"]
+    GHR --> GPK["GitHub Packages<br/>same version"]
+```
+
+**Versioning**
+
+| You want | Do |
+|---|---|
+| A patch | Nothing. The pipeline publishes the next free patch after the highest published version |
+| A minor or major | Set the new base in `package.json` and `VERSION` (they must match) and push |
+
+The bumped version exists only in the published package and the tag; the repo keeps the base.
+
+**Credentials**
+
+| Target | Auth |
+|---|---|
+| npmjs.com | npm trusted publishing (OIDC, no secret), or the `NPM_TOKEN` repository secret until it is configured |
+| GitHub Packages | The workflow's own `GITHUB_TOKEN`; nothing to set up |
+
+`.npmrc` pins the public registry and reads the token only from the `NPM_TOKEN` environment variable. Never write a token into it: the file is committed.
+
+---
+
+## Maintaining this repo
+
+```bash
+npm test                          # CLI round trip: init, check, update, force, obsolete files, chew from a tarball
+npm run check                     # skills on disk vs catalog vs lock vs agents vs hooks
+node scripts/skills-update.mjs    # vendored skills that changed upstream
+```
+
+- Every change that ships gets an entry in [CHANGELOG.md](CHANGELOG.md) in the same commit.
+- Decisions about the config itself go to [docs/adr/](docs/adr/).
+- Adding a skill: [docs/skills.md](docs/skills.md), section "Adding a skill"; `npm run check` lists what is missing.
+- CI rejects em dashes in our own prose (`AGENTS.md`, docs, agents, rules, own skills).
+
+```text
+agents/
+├── .claude/              the config that ships (agents, hooks, rules, skills, settings.json)
+├── .github/workflows/    check.yml (CI) and release.yml (publish)
+├── bin/                  chew.mjs (global CLI), agents.mjs (package CLI)
+├── scripts/              bootstrap.mjs (install engine), release-version.mjs, tests, catalog and skills checks
+├── templates/            CLAUDE.project.md for new projects
+├── docs/                 quickstart, catalog, ADRs, plan and brief templates
+├── AGENTS.md             shared base
+└── CHANGELOG.md
+```
+
+---
+
+## Troubleshooting
+
+<details>
+<summary><b><code>chew: command not found</code> after the global install</b></summary>
+
+The npm global bin folder is not on your `PATH`. `npm prefix -g` shows the prefix; on Windows the binaries live in `%AppData%\npm`, on macOS and Linux in `<prefix>/bin`. Add it to `PATH` and open a new terminal.
+
+</details>
+
+<details>
+<summary><b>The global install fails with E401 or asks for another registry</b></summary>
+
+Your user `.npmrc` points to a private feed (for example Azure Artifacts). Install from the public registry:
+
+```bash
+npm install -g @evertonferreira96/agents --registry https://registry.npmjs.org/
+# or, once:
+npm config set @evertonferreira96:registry https://registry.npmjs.org/
+```
+
+`chew` itself already pins the public registry when it downloads updates.
+
+</details>
+
+<details>
+<summary><b>A file I changed was not updated</b></summary>
+
+By design: files edited in the project are kept and listed as `edited`. `chew agents setup:check` shows them. To adopt the config version, run `chew agents setup:pull --force` (try `--dry-run` first).
+
+</details>
+
+<details>
+<summary><b>My project's AGENTS.md was not touched</b></summary>
+
+Keeping it is the default when no choice is given, including every run outside a terminal. Run `chew agents setup:pull --agents-md=append` to add the config in a managed block below your content, or `--agents-md=overwrite` to replace it. See [Projects that already have an AGENTS.md](#projects-that-already-have-an-agentsmd).
+
+</details>
+
+<details>
+<summary><b>"no manifest from a previous install"</b></summary>
+
+The project was configured by copy before the manifest existed, so every differing file looks edited. Review the list, then run `chew agents setup:pull --force` once. From then on, updates are automatic.
+
+</details>
+
+<details>
+<summary><b>No internet, or npm is blocked</b></summary>
+
+`setup:pull` warns and installs the version that came with `chew`. Use `--local` to do that on purpose.
+
+</details>
 
-- Orchestrator playbook: `.claude/skills/orchestrate/SKILL.md`
-- Roster: `.claude/agents/` (quick, product, architect, api, web, app, infra, ui, verifier, security)
-- Deterministic guards: `.claude/hooks/` wired in `.claude/settings.json`
-- `skills-lock.json` records origin, hash and adaptation of every vendored skill; `node scripts/skills-update.mjs` checks them against upstream; catalog in [docs/skills.md](docs/skills.md)
-- Decisions about this config: [docs/adr/](docs/adr/); history: [CHANGELOG.md](CHANGELOG.md)
-- Put it in a project: `npx @evertonferreira96/agents init` in the project root (or `npx github:EvertonFerreira96/agents init` straight from the repo); keep it current with `npx @evertonferreira96/agents@latest update` and look for drift with `npx @evertonferreira96/agents check`. A local clone still works: `node scripts/bootstrap.mjs <project-root>`. First task: [docs/quickstart.md](docs/quickstart.md)
-- Release: every push to `main` that changes what the package ships runs `.github/workflows/release.yml`: the full check, then `npm publish`, the `vX.Y.Z` tag and the GitHub release. Patches are automatic; for a minor or major, bump `version` in `package.json` and `VERSION` together. Add the CHANGELOG entry in the same commit
+---
 
-## Docs
+## Further reading
 
-How to bootstrap a project with this config, and what each piece does: [docs/](docs/README.md)
+| Document | Covers |
+|---|---|
+| [docs/quickstart.md](docs/quickstart.md) | First task in five minutes |
+| [docs/README.md](docs/README.md) | Every file in the config, bootstrap details, common questions |
+| [docs/skills.md](docs/skills.md) | Skill catalog: invocation and who uses each one |
+| [docs/adr/](docs/adr/) | Why the config is the way it is |
+| [AGENTS.md](AGENTS.md) | The shared base every agent reads |
+| [CHANGELOG.md](CHANGELOG.md) | What changed, by version |

package/VERSION

@@ -1 +1 @@
-0.1.1
+0.1.3

package/bin/agents.mjs

@@ -3,43 +3,67 @@
 //   agents init   [dir]  copy the config into the project (default: current directory); never overwrites
 //   agents update [dir]  refresh files the project did not edit, add new ones, delete untouched ones that left the config
 //   agents check  [dir]  report missing, outdated, edited and obsolete files; exit 1 on drift
+//   agents print-agents-md  print this version's AGENTS.md in its managed block (--raw: the file alone)
 // Flags: --force (update also overwrites files edited in the project, except CLAUDE.md, settings.local.json and agent memory),
-//        --dry-run (init/update: show what would change, write nothing).
-import { resolve } from "node:path";
-import { DEFAULT_SRC, drift, install, readPackage, report } from "../scripts/bootstrap.mjs";
+//        --dry-run (init/update: show what would change, write nothing),
+//        --agents-md=keep|overwrite|append|print (a project AGENTS.md that differs; asked in a terminal, default keep).
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { AGENTS_MD_CHOICES, DEFAULT_SRC, agentsBlock, drift, install, readPackage, report, settleAgentsMd } from "../scripts/bootstrap.mjs";
 
-const HELP = `Usage: agents <command> [dir] [--force] [--dry-run]
+const HELP = `Usage: agents <command> [dir] [flags]
 
 Commands:
-  init     copy the config into the project (never overwrites existing files)
-  update   refresh untouched files, add new ones, delete untouched files that left the config
-  check    report missing, outdated, edited and obsolete files (exit 1 on drift)
+  init             copy the config into the project (never overwrites existing files)
+  update           refresh untouched files, add new ones, delete untouched files that left the config
+  check            report missing, outdated, edited and obsolete files (exit 1 on drift)
+  print-agents-md  print the config AGENTS.md inside its managed block (--raw: the file alone)
 
 Flags:
-  --force    update also overwrites files edited in the project
-             (CLAUDE.md, .claude/settings.local.json and .claude/agent-memory/** are never touched)
-  --dry-run  show what init/update would change without writing
+  --force      update also overwrites files edited in the project
+               (CLAUDE.md, .claude/settings.local.json and .claude/agent-memory/** are never touched)
+  --dry-run    show what init/update would change without writing
+  --agents-md=<choice>
+               when the project already has its own AGENTS.md (asked in a terminal; default keep):
+               keep, overwrite, append (managed block refreshed by later updates) or print
 
 dir defaults to the current directory.`;
 
 const args = process.argv.slice(2);
-const flags = new Set(args.filter((a) => a.startsWith("-")));
-const [command, dir] = args.filter((a) => !a.startsWith("-"));
+const flags = new Set(), opts = {}, pos = [];
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === "--agents-md") opts["agents-md"] = args[++i] ?? "";
+  else if (a.startsWith("--") && a.includes("=")) opts[a.slice(2, a.indexOf("="))] = a.slice(a.indexOf("=") + 1);
+  else if (a.startsWith("-")) flags.add(a);
+  else pos.push(a);
+}
+const [command, dir] = pos;
 const pkg = readPackage(DEFAULT_SRC);
 
-if (flags.has("--version") || flags.has("-v")) { console.log(pkg.version); process.exit(0); }
-if (!command || command === "help" || flags.has("--help") || flags.has("-h")) { console.log(`${pkg.name} ${pkg.version}\n\n${HELP}`); process.exit(command ? 0 : 2); }
-if (!["init", "update", "check"].includes(command)) { console.error(`unknown command: ${command}\n\n${HELP}`); process.exit(2); }
+async function main() {
+  if (flags.has("--version") || flags.has("-v")) { console.log(pkg.version); return 0; }
+  if (!command || command === "help" || flags.has("--help") || flags.has("-h")) { console.log(`${pkg.name} ${pkg.version}\n\n${HELP}`); return command ? 0 : 2; }
+  if (!["init", "update", "check", "print-agents-md"].includes(command)) { console.error(`unknown command: ${command}\n\n${HELP}`); return 2; }
+  const agentsMd = opts["agents-md"];
+  if (agentsMd !== undefined && !AGENTS_MD_CHOICES.includes(agentsMd)) { console.error(`--agents-md must be one of: ${AGENTS_MD_CHOICES.join(", ")}`); return 2; }
+
+  if (command === "print-agents-md") {
+    process.stdout.write(flags.has("--raw") ? readFileSync(join(DEFAULT_SRC, "AGENTS.md"), "utf8") : agentsBlock(DEFAULT_SRC));
+    return 0;
+  }
 
-try {
   const target = resolve(dir ?? process.cwd());
-  const r = install({ target, mode: command, force: flags.has("--force"), dryRun: flags.has("--dry-run") });
+  const dryRun = flags.has("--dry-run");
+  const r = install({ target, mode: command, force: flags.has("--force"), dryRun });
   report(r);
-  if (command === "init" && !flags.has("--dry-run")) {
+  if (command !== "check") {
+    await settleAgentsMd({ target, r, choice: agentsMd, dryRun, interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY) });
+  }
+  if (command === "init" && !dryRun) {
     console.log("\nnext: fill in purpose and commands in CLAUDE.md; optional: `npx impeccable install` (for /ui) and `/graphify .`");
   }
-  process.exit(command === "check" && drift(r) ? 1 : 0);
-} catch (e) {
-  console.error(e.message);
-  process.exit(2);
+  return command === "check" && drift(r) ? 1 : 0;
 }
+
+main().then((code) => { process.exitCode = code; }, (e) => { console.error(e.message); process.exitCode = 2; });

package/bin/chew.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// chew: the global CLI. Install once with `npm install -g @evertonferreira96/agents`, then, in any project:
+//   chew agents setup:pull [dir]   download the latest published config and install it (fresh project: everything;
+//                                  configured project: refresh what was not edited there, add new files, drop obsolete ones)
+//   chew agents setup:check [dir]  compare the project with the latest published config; exit 1 on drift
+//   chew agents setup:print        print the latest config AGENTS.md in its managed block (--raw: the file alone)
+// Flags: --force (also overwrite files edited in the project), --dry-run (show, write nothing),
+//        --local (use the version installed with chew instead of downloading the latest),
+//        --agents-md=keep|overwrite|append|print (a project AGENTS.md that differs; asked in a terminal, default keep).
+// The install runs with the engine of the downloaded version, so an old global chew still applies the newest setup.
+// Test hook: CHEW_TARBALL=<path to a .tgz from `npm pack`> replaces the registry download.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { gunzipSync } from "node:zlib";
+
+const ROOT = fileURLToPath(new URL("..", import.meta.url));
+const SELF = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"));
+const REGISTRY = SELF.publishConfig?.registry || "https://registry.npmjs.org/";
+const SCOPE = SELF.name.startsWith("@") ? SELF.name.split("/")[0] : null;
+
+const HELP = `chew ${SELF.version}
+
+Usage: chew agents <command> [dir] [flags]
+
+Commands:
+  setup:pull   download the latest ${SELF.name} and install it into the project
+               (fresh project: everything; configured project: refresh what was not edited there)
+  setup:check  compare the project with the latest published config (exit 1 on drift)
+  setup:print  print the latest config AGENTS.md inside its managed block, to concatenate into yours
+               (--raw: the file alone, without the markers)
+
+Flags:
+  --force      also overwrite files edited in the project
+               (CLAUDE.md, .claude/settings.local.json and .claude/agent-memory/** are never touched)
+  --dry-run    show what would change without writing
+  --local      use the version installed with chew (${SELF.version}) instead of downloading
+  --agents-md=<choice>
+               when the project already has its own AGENTS.md (asked in a terminal; default keep):
+                 keep       leave yours as it is
+                 overwrite  replace it with the config version
+                 append     add the config version at the end, in a managed block that later pulls refresh
+                 print      print the config version to concatenate yourself
+
+dir defaults to the current directory.`;
+
+// npm pinned to the public registry, also for the package scope, so a user npmrc pointing elsewhere (Azure feed) does not matter.
+function npm(args, cwd) {
+  const full = [...args, "--registry", REGISTRY, ...(SCOPE ? [`--${SCOPE}:registry=${REGISTRY}`] : [])];
+  const win = process.platform === "win32";
+  const r = spawnSync(win ? "npm.cmd" : "npm", full, { cwd, encoding: "utf8", shell: win });
+  if (r.status !== 0) throw new Error((r.stderr || r.stdout || r.error?.message || "npm failed").trim().split("\n").slice(-3).join(" | "));
+  return r.stdout;
+}
+
+// Minimal reader for an npm tarball (ustar, GNU long names, pax paths); strips the leading "package/" and keeps file modes.
+function untar(gz, dest) {
+  const buf = gunzipSync(gz);
+  const root = resolve(dest);
+  let off = 0, longName = null;
+  while (off + 512 <= buf.length) {
+    const h = buf.subarray(off, off + 512);
+    if (h.every((b) => b === 0)) break;
+    const field = (start, len) => h.subarray(start, start + len).toString("utf8").replace(/\0[\s\S]*$/, "");
+    let name = field(0, 100);
+    const prefix = field(345, 155);
+    if (prefix) name = `${prefix}/${name}`;
+    const size = parseInt(field(124, 12).trim() || "0", 8);
+    const mode = parseInt(field(100, 8).trim() || "644", 8) & 0o777;
+    const type = String.fromCharCode(h[156] || 48);
+    off += 512;
+    const data = buf.subarray(off, off + size);
+    off += Math.ceil(size / 512) * 512;
+    if (type === "L") { longName = data.toString("utf8").replace(/\0[\s\S]*$/, ""); continue; }
+    if (type === "x") { const m = /\d+ path=([^\n]+)\n/.exec(data.toString("utf8")); if (m) longName = m[1]; continue; }
+    if (longName) { name = longName; longName = null; }
+    if (type !== "0" && type !== "7") continue; // directories are created on demand; npm tarballs carry no links
+    const out = resolve(root, name.replace(/^package\//, ""));
+    if (!out.startsWith(root + sep)) throw new Error(`unsafe path in tarball: ${name}`);
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, data, { mode: mode || 0o644 });
+  }
+}
+
+// Directory with the config to install: the latest published version, or the one installed with chew.
+function fetchConfig(local) {
+  const installed = { dir: ROOT, version: SELF.version, cleanup() {} };
+  if (local) return installed;
+  const tmp = mkdtempSync(join(tmpdir(), "chew-"));
+  const cleanup = () => rmSync(tmp, { recursive: true, force: true });
+  try {
+    let tarball = process.env.CHEW_TARBALL;
+    if (!tarball) {
+      const packed = JSON.parse(npm(["pack", `${SELF.name}@latest`, "--pack-destination", ".", "--json"], tmp));
+      tarball = join(tmp, packed[0].filename);
+    }
+    const dir = join(tmp, "package");
+    untar(readFileSync(tarball), dir);
+    const version = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version;
+    return { dir, version, cleanup };
+  } catch (e) {
+    cleanup();
+    console.warn(`could not download the latest ${SELF.name} (${e.message}); using the installed ${SELF.version}`);
+    return installed;
+  }
+}
+
+const newer = (a, b) => { const x = a.split(".").map(Number), y = b.split(".").map(Number); for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i]; return false; };
+
+const COMMANDS = ["setup:pull", "setup:check", "setup:print"];
+const AGENTS_MD = ["keep", "overwrite", "append", "print"];
+
+// Flags, `--name=value` / `--name value` options and positionals.
+function parseArgs(argv) {
+  const flags = new Set(), opts = {}, pos = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--agents-md") opts["agents-md"] = argv[++i] ?? "";
+    else if (a.startsWith("--") && a.includes("=")) { const k = a.slice(2, a.indexOf("=")); opts[k] = a.slice(a.indexOf("=") + 1); }
+    else if (a.startsWith("-")) flags.add(a);
+    else pos.push(a);
+  }
+  return { flags, opts, pos };
+}
+
+async function main(argv) {
+  const { flags, opts, pos } = parseArgs(argv);
+  const [ns, command, dir] = pos;
+  if (flags.has("--version") || flags.has("-v")) { console.log(SELF.version); return 0; }
+  if (!ns || ns === "help" || flags.has("--help") || flags.has("-h")) { console.log(HELP); return ns ? 0 : 2; }
+  const agentsMd = opts["agents-md"];
+  if (agentsMd !== undefined && !AGENTS_MD.includes(agentsMd)) { console.error(`--agents-md must be one of: ${AGENTS_MD.join(", ")}`); return 2; }
+  if (ns !== "agents" || !COMMANDS.includes(command)) {
+    console.error(`unknown command: chew ${[ns, command].filter(Boolean).join(" ")}\n\n${HELP}`);
+    return 2;
+  }
+
+  if (command === "setup:print") { // stdout carries only the content, so it can be redirected or piped
+    const config = fetchConfig(flags.has("--local"));
+    try {
+      const engine = await import(pathToFileURL(join(config.dir, "scripts", "bootstrap.mjs")).href);
+      const raw = readFileSync(join(config.dir, "AGENTS.md"), "utf8");
+      process.stdout.write(flags.has("--raw") || !engine.agentsBlock ? raw : engine.agentsBlock(config.dir));
+      return 0;
+    } finally {
+      config.cleanup();
+    }
+  }
+
+  const target = resolve(dir ?? process.cwd());
+  if (!existsSync(target)) throw new Error(`target is not a directory: ${target}`);
+  try { if (JSON.parse(readFileSync(join(target, "package.json"), "utf8")).name === SELF.name) throw new Error("this is the config repo itself; run chew inside a project"); }
+  catch (e) { if (e.message.startsWith("this is the config repo")) throw e; }
+
+  const config = fetchConfig(flags.has("--local"));
+  try {
+    const engine = await import(pathToFileURL(join(config.dir, "scripts", "bootstrap.mjs")).href);
+    const mode = command === "setup:check" ? "check" : "update";
+    const r = engine.install({ src: config.dir, target, mode, force: flags.has("--force"), dryRun: flags.has("--dry-run") });
+    engine.report(r);
+    if (mode === "update" && engine.settleAgentsMd) {
+      const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+      await engine.settleAgentsMd({ src: config.dir, target, r, choice: agentsMd, dryRun: flags.has("--dry-run"), interactive });
+    }
+    if (mode === "update" && !flags.has("--dry-run") && r.written.some((w) => w.startsWith("CLAUDE.md"))) {
+      console.log("\nnext: fill in purpose and commands in CLAUDE.md; optional: `npx impeccable install` (for /ui) and `/graphify .`");
+    }
+    if (newer(config.version, SELF.version)) console.log(`\nchew itself is ${SELF.version} (latest ${config.version}); update it with: npm install -g ${SELF.name}@latest`);
+    return mode === "check" && engine.drift(r) ? 1 : 0;
+  } finally {
+    config.cleanup();
+  }
+}
+
+main(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (e) => { console.error(e.message); process.exitCode = 2; });

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@evertonferreira96/agents",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Personal agents, rules, hooks and skills for Claude Code (portable to Cursor and Codex through AGENTS.md), installable into any project.",
   "type": "module",
   "bin": {
-    "agents": "bin/agents.mjs"
+    "agents": "bin/agents.mjs",
+    "chew": "bin/chew.mjs"
   },
   "files": [
     "bin/",

package/scripts/bootstrap.mjs

@@ -25,6 +25,12 @@ export const GITIGNORE = [".claude/worktrees/", ".claude/handoffs/", ".claude/.c
 export const MANIFEST = ".claude/config-manifest.json";
 export const SOURCE_FILE = ".claude/config-source.json";
 export const DEFAULT_SRC = fileURLToPath(new URL("..", import.meta.url));
+// AGENTS.md of a project that already had its own: the config version can live inside it as a managed block,
+// which `update` refreshes in place without touching the rest of the file.
+export const AGENTS_FILE = "AGENTS.md";
+export const BLOCK_START = "<!-- agents-config:start -->";
+export const BLOCK_END = "<!-- agents-config:end -->";
+export const AGENTS_MD_CHOICES = ["keep", "overwrite", "append", "print"];
 
 const sha = (p) => createHash("sha256").update(readFileSync(p)).digest("hex");
 const readJson = (p) => { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; } };
@@ -61,6 +67,82 @@ function removeEmptyParents(target, rel) {
   }
 }
 
+// The config's AGENTS.md wrapped in the managed-block markers (LF line endings, trailing newline).
+export function agentsBlock(src = DEFAULT_SRC) {
+  const body = readFileSync(join(src, AGENTS_FILE), "utf8").replace(/\r\n/g, "\n").trimEnd();
+  const note = `<!-- Managed by ${readPackage(src).name}: \`chew agents setup:pull\` refreshes this block. Edit outside the markers. -->`;
+  return `${BLOCK_START}\n${note}\n${body}\n${BLOCK_END}\n`;
+}
+
+// Position of the managed block in `text` (normalized to LF), or null when the file has none.
+function findBlock(text) {
+  const t = text.replace(/\r\n/g, "\n");
+  const start = t.indexOf(BLOCK_START);
+  const end = start < 0 ? -1 : t.indexOf(BLOCK_END, start + BLOCK_START.length);
+  return end < 0 ? null : { text: t, start, end: end + BLOCK_END.length, eol: text.includes("\r\n") ? "\r\n" : "\n" };
+}
+
+function recordHash(target, rel, hash) {
+  const p = join(target, MANIFEST);
+  const m = readJson(p);
+  if (!m?.files) return;
+  m.files[rel] = hash;
+  writeFileSync(p, JSON.stringify(m, null, 2) + "\n");
+}
+
+// What to do with a project AGENTS.md that differs from the config and has no managed block:
+//   keep (nothing), overwrite (config version, refreshed by later updates), append (managed block at the end, refreshed by
+//   later updates), print (returns the managed block for the user to paste). The manifest records the config hash, so a
+//   file with a block never counts as untouched and is never overwritten whole.
+export function applyAgentsMd({ src = DEFAULT_SRC, target, choice, dryRun = false }) {
+  if (!AGENTS_MD_CHOICES.includes(choice)) throw new Error(`unknown AGENTS.md choice: ${choice} (${AGENTS_MD_CHOICES.join(", ")})`);
+  const abs = join(src, AGENTS_FILE);
+  const dst = join(target, AGENTS_FILE);
+  if (choice === "print") return { choice, text: agentsBlock(src) };
+  if (choice === "keep" || dryRun) return { choice };
+  if (choice === "overwrite") copyFileSync(abs, dst);
+  if (choice === "append") {
+    const cur = existsSync(dst) ? readFileSync(dst, "utf8") : "";
+    const eol = cur.includes("\r\n") ? "\r\n" : "\n";
+    const block = agentsBlock(src).replace(/\n/g, eol);
+    const found = findBlock(cur);
+    if (found) writeFileSync(dst, (found.text.slice(0, found.start) + agentsBlock(src).trimEnd() + found.text.slice(found.end)).replace(/\n/g, eol));
+    else writeFileSync(dst, cur + (cur === "" || cur.endsWith(eol + eol) ? "" : cur.endsWith(eol) ? eol : eol + eol) + block);
+  }
+  recordHash(target, AGENTS_FILE, sha(abs));
+  return { choice };
+}
+
+// Ask once in a terminal (default keep).
+export async function askAgentsMd({ input = process.stdin, output = process.stdout } = {}) {
+  const { createInterface } = await import("node:readline/promises");
+  output.write(`\nAGENTS.md already exists in this project and differs from the config. What should happen to it?
+  [k] keep yours as it is (default)
+  [o] overwrite it with the config version
+  [a] append the config version at the end, in a managed block that later pulls keep current
+  [p] print the config version here, to concatenate it yourself\n`);
+  const rl = createInterface({ input, output });
+  try {
+    const answer = (await rl.question("Choice [k/o/a/p]: ")).trim().toLowerCase();
+    return { o: "overwrite", a: "append", p: "print" }[answer[0]] ?? "keep";
+  } finally {
+    rl.close();
+  }
+}
+
+// After init/update: settle an AGENTS.md conflict with `choice`, or ask when interactive, or keep and say how to choose.
+export async function settleAgentsMd({ src = DEFAULT_SRC, target, r, choice, dryRun = false, interactive = false, log = console.log }) {
+  if (!r.agentsMdConflict) return null;
+  const picked = choice || (interactive ? await askAgentsMd() : "keep");
+  const out = applyAgentsMd({ src, target, choice: picked, dryRun });
+  const dry = dryRun ? " (dry run: nothing written)" : "";
+  if (picked === "keep") log(`\nAGENTS.md: kept yours. To change that: --agents-md=overwrite, --agents-md=append or --agents-md=print`);
+  if (picked === "overwrite") log(`\nAGENTS.md: overwritten with the config version${dry}`);
+  if (picked === "append") log(`\nAGENTS.md: config version appended at the end in a managed block${dry}; later pulls refresh only that block`);
+  if (picked === "print") log(`\nAGENTS.md: the config version is below. Paste it into yours with the markers, so later pulls refresh it:\n\n${out.text}`);
+  return picked;
+}
+
 // mode: "init" (copy what is missing), "update" (also refresh untouched files and drop obsolete ones), "check" (report only).
 export function install({ src = DEFAULT_SRC, target, mode = "init", force = false, dryRun = false }) {
   if (!["init", "update", "check"].includes(mode)) throw new Error(`unknown mode: ${mode}`);
@@ -86,6 +168,20 @@ export function install({ src = DEFAULT_SRC, target, mode = "init", force = fals
     }
     const have = sha(dst);
     if (have === want) { r.same++; next[rel] = want; continue; }
+    if (rel === AGENTS_FILE) {
+      const cur = readFileSync(dst, "utf8");
+      const found = findBlock(cur);
+      if (found) { // the project's own AGENTS.md carrying the config in a managed block: only the block is ours
+        next[rel] = want; // never the project file's hash, so no engine treats the file as untouched and replaces it whole
+        const block = agentsBlock(src).trimEnd();
+        if (found.text.slice(found.start, found.end) === block) { r.same++; continue; }
+        if (mode === "check") { r.outdated.push(`${rel} (managed block)`); continue; }
+        if (mode === "init") { r.kept.push(`${rel} (managed block outdated; run update)`); continue; }
+        if (write) writeFileSync(dst, (found.text.slice(0, found.start) + block + found.text.slice(found.end)).replace(/\n/g, found.eol));
+        r.updated.push(`${rel} (managed block)`);
+        continue;
+      }
+    }
     const untouched = installed?.[rel] === have;
     if (mode === "check") { (untouched ? r.outdated : r.edited).push(rel); continue; }
     if (mode === "update" && (untouched || force) && !PROTECTED.test(rel)) {
@@ -94,6 +190,7 @@ export function install({ src = DEFAULT_SRC, target, mode = "init", force = fals
       continue;
     }
     r.kept.push(rel);
+    if (rel === AGENTS_FILE) r.agentsMdConflict = true; // the CLI offers keep / overwrite / append / print
     if (installed?.[rel]) next[rel] = installed[rel];
   }
 
@@ -155,9 +252,10 @@ export function report(r, log = console.log) {
   list("kept", r.kept, r.mode === "init" ? "  (differs; init never overwrites)" : "  (edited here)");
   list("kept", r.obsoleteKept, "  (left the config, but edited here)");
   if (r.written.length) { log("written:"); for (const w of r.written) log(`  ${w}`); }
-  if (r.mode === "update" && !r.hadManifest && r.kept.length) log("no manifest from a previous install, so differing files count as edited; review them and run `update --force` once to adopt the config versions");
-  else if (r.kept.length && r.mode === "update") log("`update --force` overwrites the files kept above (protected files excepted)");
-  else if (r.kept.length) log("run `update` to refresh differing files");
+  const others = r.kept.filter((k) => !(r.agentsMdConflict && k === AGENTS_FILE)); // AGENTS.md gets its own choice (settleAgentsMd)
+  if (r.mode === "update" && !r.hadManifest && others.length) log("no manifest from a previous install, so differing files count as edited; review them and run `update --force` once to adopt the config versions");
+  else if (others.length && r.mode === "update") log("`update --force` overwrites the files kept above (protected files excepted)");
+  else if (others.length) log("run `update` to refresh differing files");
 }
 
 // Legacy CLI (scripts/bootstrap.mjs <target> [--check|--force] | --sync).
@@ -168,7 +266,7 @@ function legacy(argv) {
     const info = readJson(join(process.cwd(), SOURCE_FILE));
     if (!info) { console.error(`--sync needs ${SOURCE_FILE} (written by a previous install)`); return 2; }
     if (!info.source || !existsSync(info.source)) {
-      console.log(`This project was installed from the ${info.package || "config"} package. Update it with: npx ${info.package || "<package>"}@latest update`);
+      console.log(`This project was installed from the ${info.package || "config"} package. Update it with: chew agents setup:pull (global CLI) or npx ${info.package || "<package>"}@latest update`);
       return 0;
     }
     src = info.source; target = process.cwd();