Seed AGENTS.md at the container root only, not in each worktree

[leogdion]

Problem

git trees add <branch> copied \$TREES_AGENTS_TEMPLATE into the new worktree:

[ -f "$TREES_AGENTS_TEMPLATE" ] && [ ! -f "$dir/AGENTS.md" ] \
  && cp "$TREES_AGENTS_TEMPLATE" "$dir/AGENTS.md"

But that template describes the bare-repo + worktree layout as a whole — where trees-bare.git lives, that sibling worktrees exist, not to cd above the repo root. It is container-level guidance addressed to an agent working inside a container, so it belongs beside the bare store and nowhere else.

Copying it per-worktree meant:

• a permanent untracked ?? AGENTS.md in every worktree's git status
• an invitation to commit container-level instructions into the project's own history, where they are wrong and out of place

Reported after git trees add beer-july-26-outline-update beer-july-26 dropped a copy into the new worktree, byte-identical to ~/.config/git-trees/AGENTS.md.

Changes

• Remove the copy from cmd_add. Worktrees are left alone.
• Add _seed_agents, next to the other _-prefixed internals — no-op when the template is unconfigured or the file already exists. The notice goes to stderr, since callers print paths on stdout.
• cmd_init uses the helper; behavior unchanged (it already refused to run against an existing directory).
• git trees root [dir] [--agents] — opt-in seeding for containers init did not create (hand-built or adopted). cmd_root gains an option parse loop in the style cmd_add already uses, replacing the hard $# -gt 1 rejection. Without the flag, root behaves exactly as before.
• Docs updated: header comment, usage(), README layout diagram / root section / env table, and the install.sh message.

Verification

No test framework; verified against a throwaway fixture per CLAUDE.md, plus bash -n and shellcheck (clean in the changed functions).

Core fix:

• add on an existing remote branch and on a new branch → no AGENTS.md, git status empty
• new-branch upstream is origin/brandnew, not origin/main — the --no-track regression stays fixed

--agents:

• root without the flag does not seed; with it, seeds and matches the template
• idempotent on a second run; exit 0
• $(git trees root --agents) returns exactly the root path — notice does not pollute stdout
• run from inside a worktree, seeds the container root and leaves the worktree untouched
• no template configured → silent no-op, exit 0

Arg parsing: --bogus and an extra positional both exit 1 with a message; root . --agents and root --agents . both work; nonexistent dir and non-trees dir still error as before.

init (needs network, so outside the usual recipe) verified over a file:// URL: seeds the root, and a subsequent add into it leaves the worktree clean.

Other regression checks from CLAUDE.md re-run and passing: --print-path stdout purity, list --json validity, a freshly cut branch not reported as merged, clean nonzero exit outside a repo.

Note for existing users

This does not clean up already-copied files. Any stray AGENTS.md in a worktree is untracked and safe to delete by hand; the one at the container root should stay.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added an optional --agents flag to git trees root to seed AGENTS.md at the project root.
  • Project initialization now seeds AGENTS.md at the container root when configured.

• Bug Fixes

  • Prevented automatic creation of AGENTS.md in every new worktree.
  • Preserved command output by sending seeding notices to stderr.

• Documentation

  • Updated configuration, command usage, and installation guidance for root-level AGENTS.md seeding.

[coderabbitai]

Warning

Review limit reached

@leogdion, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 36 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a7a990f2-e887-4dc8-a05e-9d25de495a30

📥 Commits

Reviewing files that changed from the base of the PR and between 4824753 and d3a8c39.

📒 Files selected for processing (2)

• git-trees
• install.sh

📝 Walkthrough

Walkthrough

The change adds conditional root-level AGENTS.md seeding through init and root --agents, removes automatic per-worktree seeding from add, and updates command usage, README documentation, and installer messaging.

Changes

AGENTS.md root seeding

Layer / File(s)	Summary
Seed helper and initialization lifecycle git-trees	Adds conditional template copying for root AGENTS.md, invokes it from init, and removes per-worktree copying from add.
Optional root command seeding git-trees	Adds --agents parsing to root, seeds the discovered project root, and reports writes on stderr.
Usage and configuration documentation git-trees, README.md, install.sh	Updates command usage, template semantics, layout documentation, and installer messaging for root-level seeding.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant cmd_root
  participant GitStore
  participant _seed_agents
  Caller->>cmd_root: invoke root [dir] --agents
  cmd_root->>GitStore: discover project root
  GitStore-->>cmd_root: return discovered root
  cmd_root->>_seed_agents: seed discovered root
  _seed_agents-->>Caller: write notice to stderr when copied

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: AGENTS.md is seeded at the container root instead of each worktree.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix-agents-template-root

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@git-trees`:
- Around line 108-119: The _seed_agents function must avoid TOCTOU races and
never overwrite an existing destination, including symlinks. Replace the
separate -f check and plain cp with an exclusive creation strategy that treats
any existing path (-e or -L) as occupied, and emit the stderr notice only after
this invocation successfully creates AGENTS.md.
- Line 192: Update cmd_init and both cmd_root branches to explicitly check the
status returned by _seed_agents and immediately propagate a nonzero result
instead of reporting success; apply the same guarded handling to the
worktree-enclosing root branch, preserving successful execution when seeding
completes.
- Around line 202-215: Update the argument-validation branches in cmd_root so
both unknown-option and unexpected-argument failures print the subcommand usage
to stderr before returning 1. Preserve the existing error messages and
successful parsing behavior.

In `@install.sh`:
- Line 33: Update the echo message in install.sh to describe $CFG/AGENTS.md as a
template used by init or root --agents to seed the container root, rather than
implying the installer creates the root-level file directly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 7bbf26d0-1e37-4d2e-8d0a-c5d5e2755ebe

📥 Commits

Reviewing files that changed from the base of the PR and between ba55d86 and 4824753.

📒 Files selected for processing (3)

• README.md
• git-trees
• install.sh