rhei init writes its agent note to the enclosing repo root, not the host dir

[vjovanov]

Filed by an agent triaging a local usability report.

Environment

• rhei-cli 0.3.1 (rhei version)
• rhei/main at commit 12a431c907fb4a85a8feb5f9160b506197cedd04

Reproduction

I created a Git repository at /tmp/rhei1-repro-20260830 with a tracked,
hand-written AGENTS.md. Its ordinary child directory
/tmp/rhei1-repro-20260830/host had no AGENTS.md of its own. I then ran:

/home/vjovanov/.cargo/bin/rhei init /tmp/rhei1-repro-20260830/host --here

The command exited 0 and printed:

Initialized Panta project "Host" with no rheis yet.
Also changed in the host directory: .gitignore
Wrote the agent-discovery note to rhei1-repro-20260830/AGENTS.md (the repository root).

It created host/index.panta.md and host/.gitignore, but did not create
host/AGENTS.md. Instead, it appended the agent-discovery note to the
enclosing repository root's tracked AGENTS.md, as confirmed by git diff.

Expected behavior

When --here is given a host directory, the agent-discovery note should be
written within that supplied host directory, or rhei should clearly identify
the file it is about to modify and ask for confirmation. Walking up past the
host and changing an enclosing repository's hand-written, tracked
AGENTS.md is surprising and can modify unrelated project instructions.

In this setup the impact was avoided because a scratch run exposed the
behavior and the actual invocation used --no-agents. The workaround is to
always pass --no-agents, which also prevents the automatic note from being
written.

[vjovanov]

Proposed plan — please confirm before I implement

This ticket looks like a change to the API or the workflow, so the plan
goes to you before any code is written. Reply on this issue and the
fix will continue from what you say; it is on hold until then.

If the plan is right as it stands, a 👍 on this comment is enough —
it is read as "as proposed" and releases the step. A 👎 rejects it and
sends the supervisor back to re-plan. Words beat a reaction where both
are present.

Proposed fix for this ticket — one design decision needs your call, because
the current behavior is what §FS-rhei-init.4 deliberately specifies (the note
"exists to be read by coding agents, which read the repository root").

Proposal: rhei init never writes above the host directory.

• The agent-discovery note is written in the host — the directory you named
  (or the current directory) — into its AGENTS.md, or its CLAUDE.md under
  the existing selection rule. Both --here and default mode.
• An enclosing repository's tracked AGENTS.md/CLAUDE.md is never touched.
• When the host sits inside an enclosing git repository, init prints a
  one-line hint naming that root's instruction file, so you can add a pointer
  there yourself if you want the project discovered from the root. A
  suggestion, never a write.
• The note is then always inside the host, so it simply joins the
  "Also changed in the host directory: …" report.

Why this shape. Your ticket named two remedies: write within the host, or
identify the file and ask for confirmation. An interactive prompt sits badly
in an agent-driven CLI (a run that hangs on a TTY question, or a flag to
suppress it, makes init unpredictable), so I propose the first: writes stay
confined to the directory you named, and discoverability from an enclosing
root becomes an explicit, suggested step instead of a silent edit.

What it breaks. The case §4's rationale was written for: rhei init <subdir> --here adopting a plans directory inside the repository agents work
in will no longer refresh the note at that repository's root — you get the
printed hint instead, and any note a previous version already wrote at the
root stays until you delete it (one marker-delimited block). Anyone relying
on the root write must add the root pointer by hand once.

If you'd rather keep the root write available: the alternative is to
default to the host and add an explicit opt-in flag (e.g. --agents-at-root)
that restores today's behavior — still no prompt, still no silent edit. Say
so and I'll implement that instead.

---

Posted by an agent fixing this ticket. It is waiting for your reply.