dotagents-cli 0.6.3__tar.gz → 0.7.1__tar.gz

{dotagents_cli-0.6.3 → dotagents_cli-0.7.1}/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-10-01
+
+### Added
+
+- Your own additions to an installed overlay's file live at the same path under the
+  store root (`~/.agents/kb/RUST.md` for the rust overlay's `kb/RUST.md`, or
+  `<project>/.agents/kb/RUST.md`), where `overlays sync` never touches them. The
+  base `AGENTS.md` tells agents to read them alongside the overlay's file, and
+  `dotagents context` lists the ones it finds (JSON: `local_additions`).
+
+## [0.7.0] - 2026-10-01
+
+### Changed
+
+- `overlays sync`, and `overlays add` of an overlay already installed, make the
+  install exactly what the source ships: changed files are replaced and files the
+  source does not ship are removed, including ones edited or added in the install
+  (each backed up under `<store>/install_backup/` first). What the `.gitignore` /
+  `.ignore` at the overlay's root match (read as git reads a `.gitignore`; one in a
+  subdirectory is an ordinary file), and tool caches, are the install's own and left
+  alone. Previously an edited file was kept unless `--overwrite`.
+- `--prune` (on `sync`, and now on `add`) clears what `.gitignore` / `.ignore`
+  protect and the tool caches too, leaving exactly the upstream files.
+
+### Fixed
+
+- A command module whose class declares no `_parsername_` is named by its
+  class in kebab case again (`LeakCheck` -> `dotagents leak-check`). Since 0.6.2
+  (duho 0.6.0) such a command was only reachable as `dotagents LeakCheck`.
+- The Claude Code CwdChanged hook keeps one `AGENTS_PROJECT_ROOT` pin in
+  `$CLAUDE_ENV_FILE`, replacing the previous one, instead of appending a line on
+  every `cd` (the file is inlined into every Bash command). Other lines in the file
+  are kept. Re-run `dotagents init -g` to update an installed hook.
+
+### Removed
+
+- `overlays sync --overwrite`: replacing is what `sync` always does now.
+
 ## [0.6.3] - 2026-09-30
 
 ### Added
@@ -1334,7 +1372,9 @@ Patch release: the PATH/POSIX-conversion fix above (the only change since 0.3.0)
   affected module sources (`dotagents.cli`, `duho.presets`) to extracted temp files
   before dispatch; a no-op for a plain install.
 
-[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.6.3...HEAD
+[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.7.1...HEAD
+[0.7.1]: https://github.com/jose-pr/dotagents/compare/v0.7.0...v0.7.1
+[0.7.0]: https://github.com/jose-pr/dotagents/compare/v0.6.3...v0.7.0
 [0.6.3]: https://github.com/jose-pr/dotagents/compare/v0.6.2...v0.6.3
 [0.6.2]: https://github.com/jose-pr/dotagents/compare/v0.6.1...v0.6.2
 [0.6.1]: https://github.com/jose-pr/dotagents/compare/v0.6.0...v0.6.1

{dotagents_cli-0.6.3 → dotagents_cli-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.6.3
+Version: 0.7.1
 Summary: The dotagents CLI: install and manage a portable ~/.agents config for AI coding agents
 Project-URL: Homepage, https://github.com/jose-pr/dotagents/
 Project-URL: Repository, https://github.com/jose-pr/dotagents
@@ -203,14 +203,14 @@ installed first, its `routing`/`rules` merge into `AGENTS.md`'s managed block, a
 `skills/<name>/` are symlinked (or `--copy`'d, for Windows / no-symlink) into the
 store's shared `skills/` so every agent sees the same skills.
 
-- `add` and `sync` never clobber a file you hand-edited inside an installed overlay:
-  a file that differs from the source is kept and reported. A fresh `add` whose setup
-  script fails is rolled back.
+- `add` and `sync` keep an installed overlay exactly as its source ships it: changed
+  files are replaced and files the source does not ship are removed, anything edited
+  there backed up under `<store>/install_backup/` first. What the `.gitignore` /
+  `.ignore` at the overlay's root match (setup output, local state) and tool caches are left
+  alone; `--prune` clears them too. A fresh `add` whose setup script fails is rolled
+  back.
 - `sync` refreshes each overlay from the repo it was installed from (`--repo` replaces
-  that source), removes files the source dropped that you never edited, installs a
-  `requires` added upstream, and re-merges the managed block. `--overwrite` also
-  replaces edited files and `--prune` removes edited files the source dropped; both
-  back each file up under `<store>/install_backup/` first.
+  that source), installs a `requires` added upstream, and re-merges the managed block.
 - `remove` deletes the overlay's directory, unpublishes only the skills **it**
   published, and recomposes `AGENTS.md`'s managed block over the overlays that remain,
   so its rules and routing leave with it. It refuses an overlay another installed

{dotagents_cli-0.6.3 → dotagents_cli-0.7.1}/README.md

@@ -153,14 +153,14 @@ installed first, its `routing`/`rules` merge into `AGENTS.md`'s managed block, a
 `skills/<name>/` are symlinked (or `--copy`'d, for Windows / no-symlink) into the
 store's shared `skills/` so every agent sees the same skills.
 
-- `add` and `sync` never clobber a file you hand-edited inside an installed overlay:
-  a file that differs from the source is kept and reported. A fresh `add` whose setup
-  script fails is rolled back.
+- `add` and `sync` keep an installed overlay exactly as its source ships it: changed
+  files are replaced and files the source does not ship are removed, anything edited
+  there backed up under `<store>/install_backup/` first. What the `.gitignore` /
+  `.ignore` at the overlay's root match (setup output, local state) and tool caches are left
+  alone; `--prune` clears them too. A fresh `add` whose setup script fails is rolled
+  back.
 - `sync` refreshes each overlay from the repo it was installed from (`--repo` replaces
-  that source), removes files the source dropped that you never edited, installs a
-  `requires` added upstream, and re-merges the managed block. `--overwrite` also
-  replaces edited files and `--prune` removes edited files the source dropped; both
-  back each file up under `<store>/install_backup/` first.
+  that source), installs a `requires` added upstream, and re-merges the managed block.
 - `remove` deletes the overlay's directory, unpublishes only the skills **it**
   published, and recomposes `AGENTS.md`'s managed block over the overlays that remain,
   so its rules and routing leave with it. It refuses an overlay another installed

{dotagents_cli-0.6.3 → dotagents_cli-0.7.1}/docs/guide/commands.md

@@ -88,7 +88,7 @@ the store's, else `dotagents` on `PATH`.
 | Hook | Command | Why |
 | --- | --- | --- |
 | `SessionStart` | writes `dotagents env --diff --format export` into `$CLAUDE_ENV_FILE` (`--into`: one block, replaced on every run; `PATH` as a prefix on the shell's own), then runs `dotagents context` | Claude sources `$CLAUDE_ENV_FILE` before each Bash command, so the env layers reach every command in the session; and it injects the hook's **stdout into the session context**, which is how the assembled context reaches the model. |
-| `CwdChanged` | when the new directory has a `.agents/`, appends `export AGENTS_PROJECT_ROOT=<it>` to `$CLAUDE_ENV_FILE`; then prints the directory's `AGENTS.md` if there is one | Re-pins the project root after a `cd` into another project, and surfaces that directory's `AGENTS.md`. |
+| `CwdChanged` | when the new directory has a `.agents/`, writes `export AGENTS_PROJECT_ROOT=<it>` into `$CLAUDE_ENV_FILE`, replacing the pin an earlier `cd` wrote; then prints the directory's `AGENTS.md` if there is one | Re-pins the project root after a `cd` into another project, and surfaces that directory's `AGENTS.md`. |
 
 On Windows each event gets a second, PowerShell-native handler (`shell:
 "powershell"`) that runs only when Claude Code would find no Git Bash, so a machine
@@ -105,11 +105,16 @@ without a prompt on each one requires `permissionDecision: "allow"`, which skips
 approval prompt (your deny and ask rules still apply). It is off by default, and a
 plain `init` removes one an earlier release wired.
 
-The env half **appends** (`>>`) and is guarded by `[ -n "$CLAUDE_ENV_FILE" ]`, both
-per the [hooks docs](https://code.claude.com/docs/en/hooks#persist-environment-variables):
-other hooks write to the same file, so `>` would discard their variables, and an
-unguarded redirect would create a file literally named `""` where the variable is
-unset. `$CLAUDE_ENV_FILE` exists only inside SessionStart/Setup/CwdChanged/FileChanged
+The env half never truncates the file and is guarded by `[ -n "$CLAUDE_ENV_FILE" ]`
+(see the [hooks docs](https://code.claude.com/docs/en/hooks#persist-environment-variables)):
+another hook may write to the same file, so each hook replaces only its own part --
+SessionStart its `env --into` block, CwdChanged its one `AGENTS_PROJECT_ROOT` line --
+and keeps every other line. Appending instead grew the file on every re-run (resume,
+compact, clear) and every `cd`, and Claude Code inlines it into each Bash command, which
+Git for Windows' bash cuts off at about 8 KB. Each run starts from a fresh environment
+(the hooks docs: previously sourced env files are not loaded in the hook's process), so
+SessionStart recomputes the whole diff: a value changed since the last run is updated,
+and one no env layer sets any more drops out. `$CLAUDE_ENV_FILE` exists only inside SessionStart/Setup/CwdChanged/FileChanged
 hook processes — it is absent from the session's own shell, so checking for it with
 `env | grep` proves nothing.
 
@@ -163,7 +168,7 @@ Manages opt-in overlays **by name**. See [Overlays](overlays.md) for the full mo
 dotagents overlays add python engineering  # install into the scope, publish skills, merge rules/routing
 dotagents overlays list                    # installed (discovered) + available from the repos
 dotagents overlays sync 'py*'              # refresh installed overlays matching a glob
-dotagents overlays sync --overwrite        # also replace installed files you edited (backed up)
+dotagents overlays sync --prune            # also clear what .gitignore/.ignore protect: exactly upstream
 dotagents overlays remove python           # delete the overlay dir, unpublish its skills, un-merge its rules
 dotagents overlays show python             # describe one: manifest, requires, setup, skills, source (--json)
 ```
@@ -184,13 +189,17 @@ dotagents overlays show python             # describe one: manifest, requires, s
   it as done.
 - **`sync`** refreshes each installed overlay from the repo it was installed from
   (recorded in `<overlay>/.dotagents-install.json`); `--repo` replaces that recorded
-  source for the run. New files land and `overlay.toml` is refreshed; a file that
-  differs from the source is kept and reported, and `--overwrite` replaces it. A file
-  the source no longer ships is removed when you never edited it, and kept (reported)
-  when you did, unless `--prune`. `--overwrite` and `--prune` copy each file to
-  `<store>/install_backup/<timestamp>/overlays/<name>/` first. A `requires` added
-  upstream is installed, and a published skill copy you edited is kept unless
-  `--overwrite`.
+  source for the run. The install is made to match the source exactly: new and changed
+  files land, `overlay.toml` is refreshed, and files the source does not ship are
+  removed. A file you edited (or added) there is copied to
+  `<store>/install_backup/<timestamp>/overlays/<name>/` before it is replaced or
+  removed. What the `.gitignore` / `.ignore` at the overlay's root match — setup
+  output, local state — and tool caches (`__pycache__`, `.venv`, …) are the install's own and
+  left alone; `--prune` clears them too, leaving exactly the upstream files. A
+  `requires` added upstream is installed, and published skill copies are refreshed.
+  `add` of an overlay already installed does the same (with `--prune` too). Keep your
+  own additions outside `<store>/overlays/` — a `kb/` file of your own, an
+  `AGENTS.local.md` — where a sync never touches them.
 - **`remove`** deletes the overlay's directory, unpublishes the skills it published
   (and their links in Claude's skills dir), and recomposes `AGENTS.md`'s managed block over the overlays that remain, so its
   rules and routing leave with it. It refuses an overlay another installed overlay
@@ -207,7 +216,11 @@ Assembles the effective context an agent should load — the overlay `CONTEXT.md
 and the project root's own `AGENTS.md` / `AGENTS.local.md` — minus whatever the harness already loads by itself (for Claude Code, whatever its
 `CLAUDE.md` files really `@`-include) — and prints it to **stdout** by default
 (POSIX convention); pass a path to write a file, or `--write-agent` to merge it into
-each agent's own instruction file.
+each agent's own instruction file. It ends with the skills on offer and, when there are
+any, your **local additions to overlay files** — a store file at the same path as an
+overlay's (`~/.agents/kb/RUST.md` for the rust overlay's `kb/RUST.md`; see
+[Overlays](overlays.md)); `--format json` carries both as their own keys (`skills`,
+`local_additions`).
 
 ```bash
 dotagents context                              # print the active agent's context to stdout

{dotagents_cli-0.6.3 → dotagents_cli-0.7.1}/docs/guide/install.md

@@ -96,7 +96,7 @@ python -m dotagents build-pyz --out dist/dotagents.pyz   # or build it (needs a
   holds the git checkouts and remote sources the repos materialize (the directory carries a
   `.gitignore` of `*`, so a store kept in git never records them).
 - `install_backup/<timestamp>/` — what `init --force` replaced, and what
-  `overlays sync --overwrite` / `--prune` replaced or removed.
+  `overlays add` / `sync` replaced or removed that had been edited in an installed overlay.
 - `dotagents/cmds/` — only if you create it: your own command modules (see
   [Authoring → Custom commands](authoring.md#custom-commands)).
 - `dotagents/config.toml` — only after `init --from`: records that base, so a later

{dotagents_cli-0.6.3 → dotagents_cli-0.7.1}/docs/guide/overlays.md

@@ -73,10 +73,23 @@ store). Each overlay:
   reads that dir sees the same skills.
 
 `sync` refreshes each overlay from the repo it was installed from (`--repo` replaces
-that source for the run), removes files the source dropped that you never edited,
-installs a `requires` added upstream, and reports files that differ from the source
-instead of replacing them — `--overwrite` replaces them and `--prune` also removes
-edited files the source dropped, each backed up under `<store>/install_backup/` first.
+that source for the run) and makes the install exactly the source: changed files are
+replaced and files the source does not ship are removed, anything edited there backed
+up under `<store>/install_backup/` first. What the `.gitignore` / `.ignore` at the
+overlay's root match (an ignore file in a subdirectory is just a file it ships), and
+tool caches, belong to the install (a setup script's output, local
+state) and are left alone; `--prune` clears them too. A `requires` added upstream is
+installed. An installed overlay is upstream's copy, not a place for your edits.
+
+### Your additions to an overlay's files
+
+Put your own text for an overlay file at the **same path under the store root**: an
+addition to the rust overlay's `kb/RUST.md` goes in `~/.agents/kb/RUST.md` (or
+`<project>/.agents/kb/RUST.md` for one project). `sync` never touches it, and agents
+read it alongside the overlay's file, winning on conflict: the base `AGENTS.md` tells
+them to, and `dotagents context` lists every addition it finds (for each `.md` an
+overlay ships in a subdirectory other than `skills/`). Private names, local tool paths
+and links into your own notes belong there, never in the overlay.
 
 Removing an overlay deletes only its directory and unpublishes only the skills **it**
 published (a copy the user edited is left alone). Its lines in `AGENTS.md`'s managed

{dotagents_cli-0.6.3 → dotagents_cli-0.7.1}/docs/index.md

@@ -23,7 +23,8 @@ carry the opinions.
   composable **overlays** you layer in explicitly with `dotagents overlays add
   <name>`. The overlays in this repo are examples — payloads riding on dotagents,
   swappable for your own; see [Overlays](guide/overlays.md) for what each ships.
-  Overlays are additive: they never overwrite a file you have already customized.
+  An installed overlay is kept exactly as upstream ships it (what the `.gitignore` /
+  `.ignore` at its root protect stays yours), so your own changes live in your own files.
 - **Two scopes.** Config installs into a **user** store (`~/.agents`, configurable)
   or a **project** store (`<project>/.agents`). Overlays, skills, commands, and env
   files all resolve across the same scope precedence.

{dotagents_cli-0.6.3 → dotagents_cli-0.7.1}/src/dotagents/AGENTS.md

@@ -31,9 +31,9 @@ and an error saying a command is required, and exits 2.
 | Command | Contract |
 | --- | --- |
 | `init [-g] [--dest D] [--from SRC] [--bin-dir D] [--agents a,b] [--no-hooks] [--powershell-env-hook] [--force] [--dry-run]` | Merge the base block into `<store>/AGENTS.md`, write `<store>/bin/dotagents[.cmd]`, and per active agent (`--agents`, else detected + `claude`) write its include and hooks. `--force` replaces `AGENTS.md`'s content, backed up under `<store>/install_backup/<timestamp>/`. `--from` records its base in `<store>/dotagents/config.toml`. |
-| `overlays add NAME... [-g] [--repo SPEC]... [--copy] [--no-setup] [--setup-timeout S] [--no-requires] [--dry-run]` | Install each overlay and its `requires` into `<store>/overlays/<name>/`, publish its skills, run its `setup.py`, recompose the managed block. Every name is resolved before anything is written; a source inside `<store>/overlays/` is refused; a fresh install whose setup fails is rolled back. No name: exit 2. |
+| `overlays add NAME... [-g] [--repo SPEC]... [--copy] [--no-setup] [--setup-timeout S] [--no-requires] [--prune] [--dry-run]` | Install each overlay and its `requires` into `<store>/overlays/<name>/` (an installed one is made to match its source again, as `sync` does; `--prune` clears its ignored files too), publish its skills, run its `setup.py`, recompose the managed block. Every name is resolved before anything is written; a source inside `<store>/overlays/` is refused; a fresh install whose setup fails is rolled back. No name: exit 2. |
 | `overlays remove NAME... [-g] [--force] [--dry-run]` | Delete the overlay dirs, unpublish the skills they published, recompose the block. Refuses an overlay another installed overlay requires unless `--force`. No name: exit 2. |
-| `overlays sync [GLOB] [-g] [--repo SPEC]... [--copy] [--overwrite] [--prune] [--no-setup] [--setup-timeout S] [--dry-run]` | Refresh installed overlays from the repo recorded at install (`--repo` replaces it). Files that differ from the source are kept unless `--overwrite`; files the source dropped are removed if unedited, else kept unless `--prune`; replaced/pruned files are backed up under `<store>/install_backup/<timestamp>/overlays/<name>/`. Installs new `requires`. Exits 1 when an overlay's repo cannot be loaded, its source lies inside `<store>/overlays/`, or its setup fails. |
+| `overlays sync [GLOB] [-g] [--repo SPEC]... [--copy] [--prune] [--no-setup] [--setup-timeout S] [--dry-run]` | Refresh installed overlays from the repo recorded at install (`--repo` replaces it): the install is made to match the source exactly: new and changed files land, `overlay.toml` is refreshed, files the source does not ship are removed; a file edited here is backed up first under `<store>/install_backup/<timestamp>/overlays/<name>/`. What the `.gitignore` / `.ignore` at the overlay's root match (setup output, local state) and tool caches are left alone; `--prune` clears them too. Installs new `requires`. Exits 1 when an overlay's repo cannot be loaded, its source lies inside `<store>/overlays/`, or its setup fails. |
 | `overlays list [-g] [--repo SPEC]... [--json]` | Installed overlays per store (shadowed copies marked, unmet `requires` flagged) and what the repos offer. |
 | `overlays show NAME [-g] [--repo SPEC]... [--json]` | One overlay: the copy a session would use, else the source's; manifest, setup, skills, file count, recorded source. No name: exit 2. |
 | `context [OUT] [-g] [--agents a,b] [--format markdown\|system-reminder\|json] [--write-agent] [--inline]` | Print (or write to `OUT`) the assembled context. `--write-agent` merges it into each agent's `context_target` under the project root (not with `-g`). Exits 2 when `--agents` names no known agent. |
@@ -68,6 +68,10 @@ are skipped.
 - `class Dotagents(LoggingArgs, Cli)` — the umbrella; field `cmdspath: list[str]`.
 - `CMDS_PATH_ENV = "AGENTS_CMDS_PATH"`.
 - Re-exported for command modules: `DotAgentsArgs`, `_write_stdout` (see below).
+- `kebab_name(class_name) -> str` — a discovered command's default name when its
+  class declares no `_parsername_`: `LeakCheck` -> `leak-check`, `HTTPServer` ->
+  `http-server`, `my_cmd` -> `my-cmd`. `_parsername_` is optional in a command
+  module; an explicit one always wins.
 
 ## `dotagents.cli._common`
 
@@ -75,7 +79,8 @@ are skipped.
   `global_scope: bool = False` (`--global`, `-g`) and
   `agents_dir: Optional[Path] = None` (`--agents-dir`); `resolve_scope(*,
   project_root=None) -> Scope` (via `_scope.resolve_scope`). Subclass it alone
-  (`class X(DotAgentsArgs)`), define `_parsername_` and `__call__(self) -> int`. A
+  (`class X(DotAgentsArgs)`), define `__call__(self) -> int` and optionally
+  `_parsername_` (default: `kebab_name` of the class, for a discovered module). A
   subclass may redeclare a field with the same type and default to change its help.
 - `_write_stdout(text) -> None` — write to stdout as UTF-8 whatever the console's
   encoding (a bare `print` fails on a non-Latin-1 character under cp1252).
@@ -95,6 +100,23 @@ are skipped.
   `OVERLAY_ROOT_NOTE` (`dotagents._overlays`), `resolve_user_store`
   (`dotagents._scope`).
 
+## `dotagents._ignore`
+
+The `.gitignore` / `.ignore` at the ROOT of a directory, read as git reads a
+`.gitignore` (pure stdlib) -- what an installed overlay keeps as its own when `add`
+/ `sync` mirror its source. An ignore file in a subdirectory is an ordinary file;
+nothing above the root is read.
+
+- `IGNORE_FILES = (".gitignore", ".ignore")` — read at the root in that order, so
+  `.ignore` wins (ripgrep's precedence).
+- `parse(text, base="") -> list` — one file's rules (`base`: its directory):
+  comments, `\#` / `\!` escapes, `!` negation, leading/middle `/` anchoring,
+  trailing `/` directory-only, `*`, `?`, `[...]`, `**`.
+- `class IgnoreRules(rules=())` — `for_root(root)` reads `root`'s two files;
+  `ignored(rel, is_dir=False) -> bool` decides a `/`-joined path (a pattern without
+  a slash matches at any depth), a path under an ignored directory staying ignored
+  whatever a later `!` says, as in git.
+
 ## `dotagents._resources`
 
 The package's own data; library code, importing nothing from `dotagents.cli`.
@@ -198,9 +220,9 @@ returns the exit code.
   string arrays including multi-line strings, an integer); `None` plus one warning
   when it is not valid TOML.
 - `class InstallResult` — what `install_to` did: `written`, `unchanged`,
-  `kept` (differ from source), `removed` (dropped by the source), `orphans_kept`
-  (dropped but edited), `backed_up`, `lines`; property `skipped` (= unchanged +
-  kept). Unpacks as `(written, skipped, lines)`.
+  `replaced` (edited here, replaced by the source's file), `removed` (not in the
+  source, or cleared by `prune`), `backed_up`, `lines`; property `skipped`
+  (= unchanged). Unpacks as `(written, skipped, lines)`.
 - `class Overlay(path, store=None)` — one overlay directory; `os.PathLike`; equal
   and hashed by `path`; nothing read at construction.
   - Class data: `NAME_RE`, `RESERVED_NAMES` (Windows device names),
@@ -246,12 +268,16 @@ returns the exit code.
   - `rule_blocks(rel_paths) -> tuple[list[str], list[str]]` — `(blocks, warnings)`:
     each file's leading `- **` bullets up to its next `## ` heading; a path outside
     the overlay, missing or unreadable is a warning.
-  - `install_to(dest_overlay_dir, dry_run, overwrite=False, *, prune=False,
-    backup_root=None, source=None) -> InstallResult` — copy `files()` in; a file
-    that differs is kept unless `overwrite`; `overlay.toml` always refreshed; a
-    recorded file the source dropped is removed when unedited, kept unless `prune`
-    when edited; replaced/pruned files copied under `backup_root` first; writes the
-    install record (`source`, or the previous one when `None`).
+  - `ignore_rules() -> IgnoreRules` — the rules of the `.gitignore` / `.ignore`
+    at the overlay's root (`dotagents._ignore`).
+  - `install_to(dest_overlay_dir, dry_run, *, prune=False, backup_root=None,
+    source=None) -> InstallResult` — make the install exactly the overlay:
+    `files()` installed or replaced, `overlay.toml` refreshed, every other file
+    removed; what `ignore_rules()` matches, the install record and `SKIP_PARTS`
+    caches are never copied, replaced or removed unless `prune` (which clears
+    them, without backup); a replaced or removed file that is not what dotagents
+    installed is copied under `backup_root` first; writes the install record
+    (`source`, or the previous one when `None`).
 - `OVERLAY_ROOT_NOTE: str` — the line emitted once above overlay routing lines that
   use `$<NAME>_OVERLAY_ROOT`.
 - `recompose_overlay_block(agents_md, base_block, overlays, dry_run, logger) -> bool`
@@ -407,7 +433,8 @@ API:
   `Overlay.sort_key`, then contract-A `AGENTS.md` (every store and the project root)
   and `AGENTS.local.md` (project store and project root), each prefixed
   `<!-- Source: <path> -->`. Then a skills listing (`- **name** (`<SKILL.md>`):
-  description`, from each skill's leading frontmatter; a project skill wins).
+  description`, from each skill's leading frontmatter; a project skill wins), then
+  a "Local additions to overlay files" section when `local_additions` finds any.
   `<PROJECT_ROOT>` and `<NAME_OVERLAY_ROOT>` placeholders expand; with
   `expand_vars` so do `$NAME_OVERLAY_ROOT` / `${NAME_OVERLAY_ROOT}`. `inline`
   appends the on-demand `.md` files the sources reference, each resolved against
@@ -415,7 +442,13 @@ API:
   system source never into the project).
 - `assemble_context_data(agent, scope, *, inline=False, expand_vars=True) -> dict`
   — `{"agent", "harness", "sources", "context", "skills": [{"name",
-  "description", "path"}]}`; `context` without the skills listing.
+  "description", "path"}], "local_additions": [{"overlay_file", "local": [...]}]}`;
+  `context` without the skills and local-additions listings.
+- `local_additions(scope) -> list[tuple[Path, list[Path]]]` — the user's own
+  additions to installed overlay files: for each `.md` an overlay in `scope.overlays`
+  ships in a subdirectory other than `skills/`, every store's file at the same
+  relative path (`<store>/kb/RUST.md` for the overlay's `kb/RUST.md`), in
+  `scope.stores` order. A store's root files never match.
 
 ## `dotagents._agents`
 

{dotagents_cli-0.6.3 → dotagents_cli-0.7.1}/src/dotagents/__init__.py

@@ -1,3 +1,3 @@
 """dotagents: installable CLI for the dotagents agent-config payload."""
 
-__version__ = "0.6.3"
+__version__ = "0.7.1"

{dotagents_cli-0.6.3 → dotagents_cli-0.7.1}/src/dotagents/_agents.py

@@ -553,10 +553,22 @@ class ClaudeAgent(Agent):
     # `%q` quotes the path for the bash that sources the file: a `'` in a
     # directory name used to leave an unterminated quote that broke every
     # later source of $CLAUDE_ENV_FILE (and a crafted name ran commands).
+    # The file keeps ONE pin, the latest: an earlier `export
+    # AGENTS_PROJECT_ROOT=` line is dropped and every other line (another
+    # hook's) kept. Appending grew the file by a line per `cd`, and Claude Code
+    # inlines it into every Bash command (see SESSION_START_COMMAND). Pure bash,
+    # 3.2-compatible (macOS): no mapfile, no external command, so a `cd` stays
+    # instant.
     CWD_CHANGED_COMMAND = (
         'if [ -n "$CLAUDE_ENV_FILE" ] && [ -d .agents ]; then '
-        "printf 'export AGENTS_PROJECT_ROOT=%q\\n' \"$(pwd -W 2>/dev/null || pwd)\" "
-        '>> "$CLAUDE_ENV_FILE"; fi; '
+        "kept=(); "
+        'if [ -f "$CLAUDE_ENV_FILE" ]; then '
+        'while IFS= read -r line || [ -n "$line" ]; do '
+        'case "$line" in "export AGENTS_PROJECT_ROOT="*) ;; *) kept+=("$line") ;; esac; '
+        'done < "$CLAUDE_ENV_FILE"; fi; '
+        '{ for line in ${kept[@]+"${kept[@]}"}; do printf \'%s\\n\' "$line"; done; '
+        "printf 'export AGENTS_PROJECT_ROOT=%q\\n' \"$(pwd -W 2>/dev/null || pwd)\"; "
+        '} > "$CLAUDE_ENV_FILE"; fi; '
         "[ -f AGENTS.md ] && cat AGENTS.md || true"
     )
 

{dotagents_cli-0.6.3 → dotagents_cli-0.7.1}/src/dotagents/_context.py

@@ -309,6 +309,44 @@ def _get_skills_listing(scope: _scope.Scope) -> str:
     return "\n\n## Available Skills (Opt-in)\n" + "\n".join(lines) + "\n"
 
 
+def local_additions(scope: _scope.Scope) -> "list[tuple[Path, list[Path]]]":
+    """The user's own additions to installed overlay files: for each ``.md``
+    an overlay ships in a subdirectory (``kb/``, ``flows/``, ``rules/`` ... --
+    not ``skills/``, whose published copies sit at the same path in a store),
+    every store's file at the same relative path (``~/.agents/kb/RUST.md`` for
+    an overlay's ``kb/RUST.md``), in store order. An overlay file is upstream's
+    copy, replaced by ``overlays sync``; the addition is where the user's own
+    text lives. A store's root files (``AGENTS.md``, ``env.py``) never match:
+    only a file in a subdirectory counts."""
+    stores = list(scope.stores)
+    out: "list[tuple[Path, list[Path]]]" = []
+    for overlay in scope.overlays:
+        for path in overlay.files():
+            rel = path.relative_to(overlay.path)
+            if path.suffix.lower() != ".md" or len(rel.parts) < 2 or rel.parts[0] == "skills":
+                continue
+            found = [store / rel for store in stores if (store / rel).is_file()]
+            if found:
+                out.append((path, found))
+    return out
+
+
+def _get_local_additions_listing(scope: _scope.Scope) -> str:
+    """The local additions (:func:`local_additions`) as a markdown section, or ''."""
+    additions = local_additions(scope)
+    if not additions:
+        return ""
+    lines = [
+        "- `%s` -- also read %s" % (path, ", ".join("`%s`" % p for p in found))
+        for path, found in additions
+    ]
+    return (
+        "\n\n## Local additions to overlay files\n"
+        "The user's own additions: read each with the overlay file it extends; it wins on conflict.\n"
+        + "\n".join(lines) + "\n"
+    )
+
+
 def _resolve_and_filter_sources(
     agent: _agents.Agent, scope: _scope.Scope
 ) -> "tuple[list[tuple[str, Path, Path | None]], list[Path]]":
@@ -424,6 +462,7 @@ def assemble_context(
     if not source_paths:
         return ""
     text += _get_skills_listing(scope)
+    text += _get_local_additions_listing(scope)
     return text
 
 
@@ -440,11 +479,12 @@ def assemble_context_data(
           "sources": [<absolute source path>, ...],  # after harness subtraction
           "context": <assembled markdown text, minus the skills listing>,
           "skills": [{"name": ..., "description": ..., "path": <SKILL.md>}, ...],
+          "local_additions": [{"overlay_file": ..., "local": [<path>, ...]}, ...],
         }
     ``context`` is the same assembled(+inlined, with ``inline=True``) text the
-    markdown format emits, but WITHOUT the skills listing appended -- skills are
-    their own structured field so a consumer can render them separately and
-    keep the opt-in distinction."""
+    markdown format emits, but WITHOUT the skills and local-additions listings
+    appended -- both are their own structured fields so a consumer can render
+    them separately."""
     text, source_paths = _assemble(agent, scope, inline, expand_vars)
 
     skills = [
@@ -457,4 +497,8 @@ def assemble_context_data(
         "sources": source_paths,
         "context": text,
         "skills": skills,
+        "local_additions": [
+            {"overlay_file": str(path), "local": [str(p) for p in found]}
+            for path, found in local_additions(scope)
+        ],
     }

dotagents_cli-0.7.1/src/dotagents/_ignore.py

@@ -0,0 +1,146 @@
+"""The ``.gitignore`` / ``.ignore`` at the ROOT of a directory, read as git
+reads a ``.gitignore`` -- what an installed overlay keeps as its own (setup
+output, caches, local state) when ``overlays add`` / ``sync`` make the rest
+of it match upstream.
+
+Only the root's two files count: an ignore file in a subdirectory is an
+ordinary file (the engineering overlay ships a ``references/.gitignore``
+template), and nothing above the root is read. ``.ignore`` is the ripgrep /
+fd convention, same syntax, read after ``.gitignore`` so its rules win.
+
+Pure stdlib. Supported: blank lines and ``#`` comments, ``\\#`` / ``\\!``
+escapes, ``!`` negation, a leading or middle ``/`` anchoring the pattern to
+the root, a trailing ``/`` matching directories only, ``*``, ``?``,
+``[...]`` and ``**``; a pattern without a slash matches at any depth. As in
+git, a file under an ignored directory stays ignored whatever a later ``!``
+says.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Iterable, List, Optional
+
+#: The ignore files read at the root, in order: a later one's rules win.
+IGNORE_FILES = (".gitignore", ".ignore")
+
+
+def _translate(pattern: str) -> str:
+    """A gitignore glob (without anchoring) as a regex for a ``/``-joined path."""
+    out, i, n = [], 0, len(pattern)
+    while i < n:
+        c = pattern[i]
+        if c == "*":
+            if pattern[i:i + 2] == "**":
+                i += 2
+                if i < n and pattern[i] == "/":  # "**/": zero or more directories
+                    out.append("(?:.*/)?")
+                    i += 1
+                else:  # a trailing "**": everything below
+                    out.append(".*")
+                continue
+            out.append("[^/]*")
+        elif c == "?":
+            out.append("[^/]")
+        elif c == "[":
+            j = pattern.find("]", i + 1)
+            if j < 0:
+                out.append(re.escape(c))
+            else:
+                body = pattern[i + 1:j]
+                if body.startswith("!"):
+                    body = "^" + body[1:]
+                out.append("[%s]" % body.replace("\\", "\\\\"))
+                i = j
+        elif c == "\\" and i + 1 < n:
+            i += 1
+            out.append(re.escape(pattern[i]))
+        else:
+            out.append(re.escape(c))
+        i += 1
+    return "".join(out)
+
+
+class _Rule:
+    __slots__ = ("base", "regex", "negate", "dir_only")
+
+    def __init__(self, base: str, regex: "re.Pattern[str]", negate: bool, dir_only: bool) -> None:
+        self.base = base          # the .gitignore's directory, "" or "a/b"
+        self.regex = regex
+        self.negate = negate
+        self.dir_only = dir_only
+
+    def matches(self, rel: str, is_dir: bool) -> bool:
+        if self.dir_only and not is_dir:
+            return False
+        if self.base:
+            if not rel.startswith(self.base + "/"):
+                return False
+            rel = rel[len(self.base) + 1:]
+        return bool(self.regex.fullmatch(rel))
+
+
+def parse(text: str, base: str = "") -> "List[_Rule]":
+    """The rules of one ``.gitignore`` whose directory is ``base``."""
+    rules: "List[_Rule]" = []
+    for raw in text.splitlines():
+        line = raw.rstrip("\r")
+        # Trailing spaces are ignored unless escaped.
+        stripped = line.rstrip(" ")
+        if stripped.endswith("\\") and len(line) > len(stripped):
+            stripped += " "
+        line = stripped
+        if not line or line.startswith("#"):
+            continue
+        negate = line.startswith("!")
+        if negate:
+            line = line[1:]
+        if line.startswith(("\\#", "\\!")):
+            line = line[1:]
+        dir_only = line.endswith("/")
+        line = line.rstrip("/")
+        if not line:
+            continue
+        anchored = "/" in line
+        line = line.lstrip("/")
+        body = _translate(line)
+        regex = re.compile(body if anchored else "(?:.*/)?" + body)
+        rules.append(_Rule(base, regex, negate, dir_only))
+    return rules
+
+
+class IgnoreRules:
+    """The root ``.gitignore`` / ``.ignore`` rules of a directory, applied as
+    git applies a ``.gitignore``."""
+
+    def __init__(self, rules: "Iterable[_Rule]" = ()) -> None:
+        self.rules = list(rules)
+
+    @classmethod
+    def for_root(cls, root: Path) -> "IgnoreRules":
+        """The rules of ``root/.gitignore`` then ``root/.ignore`` (absent
+        files contribute nothing); subdirectories' ignore files are not read."""
+        rules: "List[_Rule]" = []
+        for name in IGNORE_FILES:
+            try:
+                rules.extend(parse((Path(root) / name).read_text(encoding="utf-8", errors="replace")))
+            except OSError:
+                continue
+        return cls(rules)
+
+    def _decide(self, rel: str, is_dir: bool) -> Optional[bool]:
+        verdict = None
+        for rule in self.rules:
+            if rule.matches(rel, is_dir):
+                verdict = not rule.negate
+        return verdict
+
+    def ignored(self, rel: str, is_dir: bool = False) -> bool:
+        """Is ``rel`` (``/``-separated, relative to the root) ignored? A path
+        under an ignored directory is, whatever a later ``!`` says."""
+        parts = rel.strip("/").split("/")
+        for depth in range(1, len(parts)):
+            if self._decide("/".join(parts[:depth]), True):
+                return True
+        return bool(self._decide("/".join(parts), is_dir))