Expose a bootstrap plan/ledger for CI and agent-session audit

[caioribeiroclw-pixel]

Context

anywhere-agents is doing something useful and ambitious: one command refreshes repo-level agent config, skills, commands, project settings, user-level hooks/statusline, and even optional Codex CLI drift. Because the intended usage is to run bootstrap at the start of every agent session, the command is becoming an operational surface, not just an installer.

That makes one boundary worth exposing explicitly: what will this run write before it writes it, and what did it actually write after it starts?

Today the README/CLAUDE.md explain the behavior well, but machines/CI/agents do not have a compact object they can inspect to separate:

• repo files refreshed (AGENTS.md, generated CLAUDE.md, agents/codex.md, commands, skills, .claude/settings.json merge)
• user-level writes (~/.claude/hooks/*, ~/.claude/statusline.py, ~/.claude/settings.json merge)
• mutable upstream drift applied from packs
• auto-updates attempted for external CLIs (@openai/codex)
• skipped/preserved local files (hand-authored generated targets, project-only settings keys)
• failure point and whether writes had already started

Proposal

Add one of these low-friction surfaces:

1. anywhere-agents --plan-json / bootstrap --plan-json

   • computes proposed writes/merges/updates without changing files
   • includes file paths/scopes, action type, source ref, old/new hash when available, and whether the action is repo-level vs user-level

2. anywhere-agents --ledger-json <path>

   • emitted after a real run
   • records which writes started, which writes completed, what was skipped/preserved, backup paths if any, and external auto-update attempts/results

3. If flags are too much for the bootstrap scripts, a simpler sidecar under .agent-config/last-run.json would still help.

A minimal shape could be:

{
  "run_id": "...",
  "started_at": "...",
  "upstream": "yzhao062/anywhere-agents@<ref>",
  "mode": "plan|apply",
  "writes_started": true,
  "operations": [
    {
      "scope": "repo|user|external-cli",
      "target": "AGENTS.md",
      "action": "write|merge|preserve|skip|update_external",
      "source": ".agent-config/AGENTS.md",
      "before_hash": "...",
      "after_hash": "...",
      "status": "planned|applied|skipped|failed",
      "reason": "hand_authored_file_preserved"
    }
  ],
  "summary": {
    "repo_writes": 4,
    "user_writes": 3,
    "external_updates_attempted": 0,
    "skipped": 1,
    "failed": 0
  }
}

Why it matters

This is especially useful because anywhere-agents intentionally crosses several trust boundaries in one session-start path:

• project-local config vs fetched upstream config
• generated agent files vs hand-authored local files
• repo-level writes vs user-level Claude hooks/settings
• bootstrap refresh vs third-party pack drift
• config sync vs external CLI auto-update

For human users, the current stderr summaries may be enough. For CI and agent-driven bootstraps, a plan/ledger makes the command auditable without scraping terminal output or guessing whether a failed run mutated the workspace halfway through.

This would not claim that Claude/Codex later loaded or obeyed the config. It would only prove the bootstrap/apply boundary: proposed writes, actual writes, skips, preservation, and external update attempts.