docs(manual): agents-cleanup nested repos, link edge cases, non-git root

2026-09-30 17:29:07 -04:00
parent 5e4d0fa4c8
commit 88b43d582f
2 changed files with 52 additions and 32 deletions
@@ -2482,8 +2482,10 @@ functions). They are active in all interactive sessions.
    Every symlink that resolves into AGENTS/ is replaced by the real file
    or directory it points to. When two links share a target (docs/plans
    and docs/superpowers/plans), the shallower one receives the content
-    and the other is removed; a link to a target holding only .gitkeep is
+    and the other is removed; a link to a target holding only .gitkeep, a
-    removed with nothing put in its place. An AGENTS.md that is exactly
+    dangling link, or a link to AGENTS/ itself is removed with nothing put
    in its place. Dangling links are removed even when AGENTS/ is already
    gone. An AGENTS.md that is exactly
    the stub agents-init writes is deleted; any other AGENTS.md loses only
    the SYSTEM DIRECTIVE blockquote that pointed agents at AGENTS/AGENTS.md.
    No CLAUDE.md is recreated.
@@ -2498,14 +2500,17 @@ functions). They are active in all interactive sessions.
    Files inside AGENTS/ that no project symlink points to -- other than
    agents-init's own .version, .agents-tools/ and .gitkeep files -- stop
    the cleanup before anything changes. They are listed; --drop-extras
-    discards them instead.
+    discards them instead. A nested git repository inside AGENTS/ is always
    refused, --drop-extras or not: the bundle keeps only a pointer to it, so
    move it out first.
    The disabled marker is the per-clone git config key
    agents-init.disabled, set on every run. --marker-file also writes
    .agents-disabled in the project root, which agents-init honors too and
    which may be committed to opt every clone out; it is the only marker
-    available outside a git repository. In a project with no AGENTS/, only
+    available outside a git repository, where the project root is taken to
-    the marker is set -- a pre-emptive opt-out. agents-init --enable
+    be the current directory -- run it from there. In a project with no
    AGENTS/, only the marker is set -- a pre-emptive opt-out. agents-init --enable
    clears the git key again.
    Re-running is safe: an interrupted cleanup resumes where it stopped,
@@ -2523,7 +2528,8 @@ functions). They are active in all interactive sessions.
    Exit Status:
      0  Cleanup finished, or nothing was left to do
      1  Refused (outside git without --marker-file, unresolved rebase in
-         AGENTS/, unlinked files in AGENTS/) or a step failed
+         AGENTS/, unlinked files or a nested repository in AGENTS/) or a step
         failed
    Notes:
      Restore an archived AGENTS/ with: git clone <bundle> AGENTS, then
@@ -5565,7 +5571,8 @@ project that never used them.
 ## Opting a project out: agents-cleanup
 `agents-cleanup` reverses everything `agents-init` did in a project and
-stops it from happening again. Run it from anywhere inside the project:
+stops it from happening again. Run it from anywhere inside the project
 (from the project root when it is not a git repository):
    agents-cleanup --dry-run
    agents-cleanup
@@ -5575,33 +5582,39 @@ directory it points to, so the project ends up with ordinary files where
 the links were. Where two links shared one directory (`docs/plans` and
 `docs/superpowers/plans`), the shallower one — the location that existed
 before `agents-init` — gets the content and the other link is removed. A
-link to a directory holding nothing but `.gitkeep` is simply removed. No
+link to a directory holding nothing but `.gitkeep`, a dangling link, and a
-`CLAUDE.md` is recreated.
+link to `AGENTS/` itself are simply removed; dangling links go even if you
 already deleted `AGENTS/` by hand. No `CLAUDE.md` is recreated.
 A root `AGENTS.md` that is exactly the seed file `agents-init` writes for
 a fresh project is deleted, since it never held anything of yours. Any
 other `AGENTS.md` keeps its content and loses only the "SYSTEM DIRECTIVE"
 blockquote telling agents to edit `AGENTS/AGENTS.md` — a directory that no
-longer exists.
+longer exists. If the directive was all it held, the file is deleted.
 Before anything moves, pending changes in `AGENTS/` are committed and the
 whole history is written to a verified git bundle under
 `~/.local/state/agents-cleanup/` (or `$XDG_STATE_HOME/agents-cleanup/`).
 An `AGENTS/` that is not a git repository has no bundle, so `--drop-extras`
 there deletes the files for good.
 Then `AGENTS/` is removed, along with `docs/superpowers/` and `docs/` if
 they are left empty, and every `Added by agents-init` block is stripped
-from `.gitignore`. Nothing is committed to the project itself: the
+from `.gitignore`. A `.gitignore` that held only those blocks is deleted,
-restored files show up as ordinary changes for you to commit or not.
+unless it is tracked, in which case it is emptied and the change shows in
 `git status`. Nothing is committed to the project itself: the restored
 files show up as ordinary changes for you to commit or not.
 WARNING: Files inside `AGENTS/` that no project link points to — notes,
 scratch files, anything you put there by hand — stop the cleanup before
 it changes anything, and are listed. Move them out yourself, or pass
-`--drop-extras` to discard them. `agents-cleanup` refuses to run when
+`--drop-extras` to discard them. `--dry-run` refuses the same way, unless
-`AGENTS/` is itself a symlink to a directory elsewhere, since removing it
+you also give it `--drop-extras`. A git repository nested inside `AGENTS/`
-would remove that directory; replace the link with a real directory first.
+is always refused, even with `--drop-extras`: the bundle records only a
-Discarded files survive only in the bundle, and files `AGENTS/.gitignore`
+pointer to it, so move it out first. `agents-cleanup` also refuses to run
-ignores are not in the bundle at all; the listing marks those.
+when `AGENTS/` is itself a symlink to a directory elsewhere, since removing
 it would remove that directory; replace the link with a real directory
 first. Discarded files survive only in the bundle, and files
 `AGENTS/.gitignore` ignores are not in the bundle at all; the listing marks
 those. An `AGENTS/` that is not a git repository has no bundle, so
 `--drop-extras` there deletes the files for good.
 ### The disabled marker
@@ -286,7 +286,8 @@ project that never used them.
 ## Opting a project out: agents-cleanup
 `agents-cleanup` reverses everything `agents-init` did in a project and
-stops it from happening again. Run it from anywhere inside the project:
+stops it from happening again. Run it from anywhere inside the project
 (from the project root when it is not a git repository):
    agents-cleanup --dry-run
    agents-cleanup
@@ -296,33 +297,39 @@ directory it points to, so the project ends up with ordinary files where
 the links were. Where two links shared one directory (`docs/plans` and
 `docs/superpowers/plans`), the shallower one — the location that existed
 before `agents-init` — gets the content and the other link is removed. A
-link to a directory holding nothing but `.gitkeep` is simply removed. No
+link to a directory holding nothing but `.gitkeep`, a dangling link, and a
-`CLAUDE.md` is recreated.
+link to `AGENTS/` itself are simply removed; dangling links go even if you
 already deleted `AGENTS/` by hand. No `CLAUDE.md` is recreated.
 A root `AGENTS.md` that is exactly the seed file `agents-init` writes for
 a fresh project is deleted, since it never held anything of yours. Any
 other `AGENTS.md` keeps its content and loses only the "SYSTEM DIRECTIVE"
 blockquote telling agents to edit `AGENTS/AGENTS.md` — a directory that no
-longer exists.
+longer exists. If the directive was all it held, the file is deleted.
 Before anything moves, pending changes in `AGENTS/` are committed and the
 whole history is written to a verified git bundle under
 `~/.local/state/agents-cleanup/` (or `$XDG_STATE_HOME/agents-cleanup/`).
 An `AGENTS/` that is not a git repository has no bundle, so `--drop-extras`
 there deletes the files for good.
 Then `AGENTS/` is removed, along with `docs/superpowers/` and `docs/` if
 they are left empty, and every `Added by agents-init` block is stripped
-from `.gitignore`. Nothing is committed to the project itself: the
+from `.gitignore`. A `.gitignore` that held only those blocks is deleted,
-restored files show up as ordinary changes for you to commit or not.
+unless it is tracked, in which case it is emptied and the change shows in
 `git status`. Nothing is committed to the project itself: the restored
 files show up as ordinary changes for you to commit or not.
 WARNING: Files inside `AGENTS/` that no project link points to — notes,
 scratch files, anything you put there by hand — stop the cleanup before
 it changes anything, and are listed. Move them out yourself, or pass
-`--drop-extras` to discard them. `agents-cleanup` refuses to run when
+`--drop-extras` to discard them. `--dry-run` refuses the same way, unless
-`AGENTS/` is itself a symlink to a directory elsewhere, since removing it
+you also give it `--drop-extras`. A git repository nested inside `AGENTS/`
-would remove that directory; replace the link with a real directory first.
+is always refused, even with `--drop-extras`: the bundle records only a
-Discarded files survive only in the bundle, and files `AGENTS/.gitignore`
+pointer to it, so move it out first. `agents-cleanup` also refuses to run
-ignores are not in the bundle at all; the listing marks those.
+when `AGENTS/` is itself a symlink to a directory elsewhere, since removing
 it would remove that directory; replace the link with a real directory
 first. Discarded files survive only in the bundle, and files
 `AGENTS/.gitignore` ignores are not in the bundle at all; the listing marks
 those. An `AGENTS/` that is not a git repository has no bundle, so
 `--drop-extras` there deletes the files for good.
 ### The disabled marker