clarify rhachet role setup, lifecycle, and verification in readme

[caseybrookes]

Clarify Rhachet role setup, lifecycle, and verification in README

Problem

The README does not clearly explain how Rhachet roles are installed, activated, verified, or kept up to date when using Claude. It’s unclear which commands must be run, what “linked” vs “initialized” means, and how to tell what role or hooks are currently active. This causes confusion and makes debugging difficult.

What the README needs to clarify

1. Installation & updates

• Which packages need to be installed or upgraded to @latest
• When users should re-run npm install vs reuse existing installs
• auth: how to allow claude to run integration tests (aws permissions)

2. Role lifecycle

• The exact step-by-step commands required before using a role
• Clear explanations of:
  • npx rhachet init
  • npx rhachet roles link --role <role>
  • npx rhachet roles init --role <role>
• What “linked” vs “initialized” means
• When each command needs to be re-run

3. What is “live”

• How to tell which role(s), versions, and hooks are currently active
• What the source of truth is (command output, debug mode, or config file)

4. Hooks

• What hooks are, when they run, and where they are loaded from
• How to verify hooks are actually being loaded/executed

5. Examples

• A few concrete, step-by-step examples (e.g. using a role, updating a role, testing a new behavior)

Commands that need explanation

npm install rhachet@latest rhachet-roles-ehmpathy@latest
npx rhachet init
npx rhachet roles link --role mechanic
npx rhachet roles init --role mechanic

acceptance criteria

• README clearly documents the role lifecycle from install → active → verified
• Users can determine, without guesswork, which role and hooks are currently active
• All required commands are explained in plain language
• Includes at least 2–3 real-world, step-by-step usage examples
• A user unfamiliar with the system can successfully use a role with Claude without external guidance