dotagents-cli 0.6.2__tar.gz → 0.7.0__tar.gz

{dotagents_cli-0.6.2 → dotagents_cli-0.7.0}/CHANGELOG.md

@@ -7,6 +7,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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
+
+- `env --into FILE` writes the output into FILE as the one block `env` owns
+  there, replacing the block an earlier run wrote and keeping every other line.
+- With `--diff --format export`, a `PATH` that is the caller's own with entries
+  put in front is written as `export PATH='<entries>'"${PATH:+:$PATH}"`, so it
+  stays short and keeps what the sourcing shell has.
+- When `dotagents` runs from a `.pyz`, `env` exports `AGENTS_PYLIB`, the path
+  of that archive. The libraries it bundles (duho, pathlib_next) import from
+  it, so an overlay built on duho works even when the interpreter in
+  `AGENTS_PYTHON` has no duho installed. An installed `dotagents` sets nothing:
+  its libraries are already importable from `AGENTS_PYTHON`. The archive is
+  never put on `PYTHONPATH`, where it would shadow a project's own copy; a
+  consumer adds it to `sys.path` itself when its import fails.
+
+### Fixed
+
+- The Claude Code SessionStart hook no longer appends the whole environment to
+  `$CLAUDE_ENV_FILE` every time it runs (startup, resume, compact, clear). Claude
+  Code inlines that file into every Bash command, and once it passed about 8 KB,
+  Git for Windows' bash truncated the command and every Bash call failed with an
+  unterminated quote. The hook now uses `env --into`, which keeps one block.
+  Re-run `dotagents init -g` to update an installed hook.
+
 ## [0.6.2] - 2026-09-28
 
 ### Added
@@ -1308,7 +1362,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.2...HEAD
+[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.7.0...HEAD
+[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
 [0.6.0]: https://github.com/jose-pr/dotagents/compare/v0.5.1...v0.6.0

{dotagents_cli-0.6.2 → dotagents_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.6.2
+Version: 0.7.0
 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.2 → dotagents_cli-0.7.0}/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.2 → dotagents_cli-0.7.0}/docs/guide/commands.md

@@ -87,8 +87,8 @@ the store's, else `dotagents` on `PATH`.
 
 | Hook | Command | Why |
 | --- | --- | --- |
-| `SessionStart` | appends `dotagents env --diff --format export` to `$CLAUDE_ENV_FILE`, 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`. |
+| `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/`, 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
@@ -272,6 +281,11 @@ dotagents env --diff --format json   # only vars that differ from the caller's e
   environment, the working directory, the stores, the overlays, every env and `lib`
   file), for at most five minutes; the per-command env loaders use it. The cache is
   owner-only, under `<user store>/.cache/env/`.
+- `--into <file>` — write into `<file>` instead of stdout, as the one block this
+  command owns there (between `: dotagents-env-begin` / `: dotagents-env-end`):
+  an earlier block is replaced, anything else in the file is kept. The SessionStart
+  hook writes `$CLAUDE_ENV_FILE` this way, so the file stays one block however often
+  the hook runs. `export` format only.
 - `-g` / `--global` — skip the project-level env files (the store is unaffected).
 - `--agents-dir <dir>` — user store override for this run.
 
@@ -307,7 +321,12 @@ form and drop names that are not shell identifiers.
    overlay, where `NAME` is the overlay's name upper-cased with `-` turned into `_`
    (`my-ov` → `MY_OV_OVERLAY_ROOT`). That is the same name `context` expands as a
    `<NAME_OVERLAY_ROOT>` placeholder, so an env file and a context file refer to an
-   overlay's install dir by one name.
+   overlay's install dir by one name. When `dotagents` runs from a `.pyz`,
+   `AGENTS_PYLIB` names that archive: the libraries it bundles (duho,
+   pathlib_next) import from it, so an overlay built on them appends it to
+   `sys.path` when its own import fails. An installed `dotagents` sets nothing,
+   since those libraries are already in `AGENTS_PYTHON`'s site-packages. It is
+   never put on `PYTHONPATH`, where it would shadow a project's own copy.
 3. **`PATH`** — every level's `bin/` (each store's overlays, then the store) goes
    to the front in that order, including ones that do not exist yet, so an `env.py`
    and every subprocess can call an overlay's helpers by name. The order holds even

{dotagents_cli-0.6.2 → dotagents_cli-0.7.0}/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.2 → dotagents_cli-0.7.0}/docs/guide/overlays.md

@@ -73,10 +73,14 @@ 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: keep
+those in your own files (a `kb/` file, `AGENTS.local.md`).
 
 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.2 → dotagents_cli-0.7.0}/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.2 → dotagents_cli-0.7.0}/src/dotagents/AGENTS.md

@@ -31,14 +31,14 @@ 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. |
 | `path [-g] [--lib] [--format list\|native\|posix\|json]` | Print the bin dirs `env` puts on `PATH` (`--lib`: the existing lib dirs it puts on `PYTHONPATH`), highest precedence first; runs no env file. `posix` is `:`-joined, MSYS2 form on Windows. |
-| `env [-g] [--format F] [--diff] [--cache]` | Print the assembled environment (`--diff`: only what differs from the caller's; `--cache`: replay the previous output while `env_cache_key` holds, up to `ENV_CACHE_TTL`) in format `F`: `auto` (default: the calling shell), `export`/`posix`/`sh`/`bash`, `dotenv`/`env`, `powershell`/`pwsh`/`ps`, `cmd`/`bat`/`batch`, `fish`, `json`, `ini`, `yaml`. |
+| `env [-g] [--format F] [--diff] [--cache] [--into FILE]` | Print the assembled environment (`--diff`: only what differs from the caller's; `--cache`: replay the previous output while `env_cache_key` holds, up to `ENV_CACHE_TTL`; `--into FILE`: write it into FILE as the one block this command owns there) in format `F`: `auto` (default: the calling shell), `export`/`posix`/`sh`/`bash`, `dotenv`/`env`, `powershell`/`pwsh`/`ps`, `cmd`/`bat`/`batch`, `fish`, `json`, `ini`, `yaml`. |
 | `launch [AGENT] [-g] [--command PROG] [--no-context] [--inline] [--write-agent] [--dry-run] [-- ARGS...]` | Run the agent's CLI with the env applied and the context handed over; the exit code is the harness's (`128+N` on signal N). |
 | `findings add\|list\|show\|done\|reopen\|remove\|index\|path [-g] [--dir D]` | The findings queue at `<store>/findings/` (`--dir` overrides): one markdown file per finding, `done` moves it to `processed/` with a required resolution, `INDEX.md` regenerated on every change. |
 | `about [--json]` | `dotagents-cli <version>`, then `<distribution> <version>` per bundled (`.pyz`) or installed package. |
@@ -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`.
@@ -108,6 +130,10 @@ The package's own data; library code, importing nothing from `dotagents.cli`.
   store at `dest`: the project template for a project store when the base has one,
   else the user template, else `<src>/AGENTS.md`; `{{AGENTS_MD}}` rendered as the
   absolute POSIX path of `<dest>/AGENTS.md`.
+- `pyz_archive() -> str | None` — the `.pyz` this dotagents is imported from (the
+  ancestor of the module's `__file__` that is a file), or `None` for a plain
+  install. The archive also holds the vendored duho and pathlib_next; `env`
+  exports it as `AGENTS_PYLIB`.
 
 ## Commands — `dotagents.cli.init`, `dotagents.cli.overlays`, `dotagents.cli.context`, `dotagents.cli.env`, `dotagents.cli.path`, `dotagents.cli.about`, `dotagents.cli.build_pyz`
 
@@ -119,6 +145,13 @@ returns the exit code.
   ("markdown", "system-reminder", "json")`); `env.Env`; `path.PathCmd`
   (`PATH_FORMATS = ("list", "native", "posix", "json")`); `build_pyz.BuildPyz`;
   `about.About`.
+- `env`: `write_into(path, text, output_format)` — what `--into` does: the file
+  keeps ONE block between `INTO_BEGIN = ": dotagents-env-begin"` and
+  `INTO_END = ": dotagents-env-end"` (no-op commands, not comments, so a `; cmd`
+  appended to the last line still runs; earlier blocks removed, other lines kept,
+  the new block last), written atomically; `INTO_FORMATS = ("export",)`. With
+  `--diff --format export`, a `PATH` that is the caller's with entries in front is
+  written as `export PATH='<prefix>'"${PATH:+:$PATH}"`.
 - `about`: `DISTRIBUTION = "dotagents-cli"`, `BUNDLE_FILE = "_bundle.json"` (written
   by `build-pyz` into the package), `RUNTIME_PACKAGES = ("duho", "pathlib_next",
   "uritools", "netimps", "requests")` (the only packages a plain install reports);
@@ -187,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),
@@ -235,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`
@@ -322,7 +359,11 @@ proxy model.
   user-scope walk `AGENTS_PROJECT_ROOT` is set only when unset. Only when unset:
   `AGENTS_PYTHON` (`sys.executable`) and one `<NAME>_OVERLAY_ROOT` per
   `scope.overlays` (a value pinned to the user store's copy is re-pointed when a
-  project copy shadows it).
+  project copy shadows it). `AGENTS_PYLIB` (`_env.PYLIB_VAR`): the `.pyz` when
+  dotagents runs from one (`_resources.pyz_archive()`), else not set — where its
+  own libraries (duho, pathlib_next) import from by zipimport for an overlay
+  built on them. Never added to `PYTHONPATH`: a consumer appends it to
+  `sys.path` when its import fails.
 - `PATH`: every level's `bin` (contract A, not project-root, missing dirs included)
   at the front in that order, whatever the caller's `PATH` held; empty and
   cwd-relative inherited entries are dropped.
@@ -631,6 +672,8 @@ Read:
 - `AGENTS_HARNESS` — the running harness (registry name or harness id), for
   identity. `AGENTS_PYTHON` — the interpreter for `env.py`. `AGENTS_PYTHONPATH` —
   the overlay/store `lib` dirs `env` put on `PYTHONPATH`, highest precedence first.
+  `AGENTS_PYLIB` — the `.pyz` dotagents runs from (duho and pathlib_next import
+  from it), unset for an installed dotagents.
 - Harness config dirs: `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `PI_CODING_AGENT_DIR`.
   Harness markers: `CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT`, `GEMINI_CLI`,
   `CODEX_SANDBOX*`, `CURSOR_AGENT`, `PI_CODING_AGENT`. Model vars: `ANTHROPIC_MODEL`,
@@ -644,7 +687,7 @@ Read:
 
 Emitted by `env` (and applied by `launch`): `AGENTS_HARNESS`, `AGENTS_VENDOR`,
 `AGENT`, `AGENTS_MODEL`, `AGENTS_HOME`, `AGENTS_PROJECT_ROOT`, `AGENTS_PYTHON`,
-`<NAME>_OVERLAY_ROOT`, `PATH`, `AGENTS_PYTHONPATH`, `AGENTS_PROXY` and the mirrored
+`AGENTS_PYLIB` (from a `.pyz` only), `<NAME>_OVERLAY_ROOT`, `PATH`, `AGENTS_PYTHONPATH`, `AGENTS_PROXY` and the mirrored
 proxy vars, plus whatever the env files set. `AGENTS_AGENT` is never emitted.
 `launch` also exports `AGENTS_CONTEXT_FILE`.
 

{dotagents_cli-0.6.2 → dotagents_cli-0.7.0}/src/dotagents/__init__.py

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

{dotagents_cli-0.6.2 → dotagents_cli-0.7.0}/src/dotagents/_agents.py

@@ -500,14 +500,21 @@ class ClaudeAgent(Agent):
     # SessionStart does two things, in one `type: command` hook (SessionStart
     # supports only command/mcp_tool hooks, and env must run before context):
     #
-    # 1. `dotagents env --diff` output is appended to $CLAUDE_ENV_FILE
+    # 1. `dotagents env --diff` output goes into $CLAUDE_ENV_FILE
     #    (code.claude.com/docs/en/env-vars + hooks.md "Persist environment
     #    variables"): Claude sources that file before each Bash command. It is
     #    set only inside SessionStart/Setup/CwdChanged/FileChanged hook
     #    processes, never in the session's own environment.
-    #      * APPEND (`>>`), never truncate -- other hooks write to the same file.
+    #      * `--into`, not `>>`: the block a previous run wrote is REPLACED
+    #        and anything else in the file (another hook's lines) is kept.
+    #        SessionStart re-runs on resume, compact and clear; appending
+    #        grew the file by the whole env each time, and Claude Code inlines
+    #        it into every Bash command's `bash -c` argument, which Git for
+    #        Windows' bash truncates at about 8 KB -- every Bash call then
+    #        failed with an unterminated quote. PATH is written relative to
+    #        the shell's own ($PATH), which keeps the block small.
     #      * Guard on non-empty (`[ -n "$CLAUDE_ENV_FILE" ]`) -- when unset,
-    #        `>> ""` would create a file literally named "".
+    #        `--into ""` has nowhere to write.
     #
     # 2. `dotagents context`: Claude injects a SessionStart hook's stdout into
     #    the session context.
@@ -534,7 +541,7 @@ class ClaudeAgent(Agent):
     SESSION_START_COMMAND = (
         _HOOK_DOTAGENTS
         + 'if [ -n "$CLAUDE_ENV_FILE" ]; then '
-        '"$d" env --diff --format export >> "$CLAUDE_ENV_FILE"; '
+        '"$d" env --diff --format export --into "$CLAUDE_ENV_FILE"; '
         "fi; "
         '"$d" context'
     )
@@ -546,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.2 → dotagents_cli-0.7.0}/src/dotagents/_env.py

@@ -59,7 +59,10 @@ The identity/proxy model is wired into the output around the file chain:
     the same set :func:`get_overlay_roots` lists, named by
     :attr:`_overlays.Overlay.root_var` --
     the same name ``dotagents context`` expands as a placeholder), so an env
-    file can reference an overlay's install dir by name.
+    file can reference an overlay's install dir by name. ``AGENTS_PYLIB``
+    (:data:`PYLIB_VAR`) names the ``.pyz`` when dotagents runs from one --
+    where its own libraries (duho, pathlib_next) import from for an overlay
+    built on them; never put on ``PYTHONPATH``.
   * **Proxy** is normalized AFTER the file chain: ``AGENTS_PROXY`` is seeded if
     unset (from ``AGENTS_WEBFETCH_PROXY_URL`` else the global
     HTTPS/HTTP/ALL_PROXY, either case); any proxy var that *already exists* is
@@ -94,6 +97,11 @@ from typing import Iterable, Optional
 
 from dotagents._scope import Scope, project_root_default
 
+#: Names the ``.pyz`` dotagents runs from (unset for an installed dotagents,
+#: whose libraries are in ``AGENTS_PYTHON``'s site-packages): an overlay built
+#: on duho appends it to ``sys.path`` when ``import duho`` fails.
+PYLIB_VAR = "AGENTS_PYLIB"
+
 
 class EnvChanges(dict):
     """A change set: the vars set (``dict[str, str]``, as before) plus
@@ -1047,6 +1055,17 @@ def get_environment(
     # `sys.executable` is '' or None under an embedding host: then nothing is
     # exported rather than an empty command name.
     _seed("AGENTS_PYTHON", sys.executable)
+    # --- AGENTS_PYLIB --- where dotagents' own libraries (duho, pathlib_next)
+    # import from for an overlay that builds on them. Set only when dotagents
+    # runs from a .pyz: the archive, importable by zipimport. An installed
+    # dotagents has them in AGENTS_PYTHON's site-packages already. Never put on
+    # PYTHONPATH, which would shadow a project's own copy: a consumer appends
+    # it to sys.path when its import fails.
+    from dotagents._resources import pyz_archive
+
+    pylib = pyz_archive()
+    if pylib and osenv.get(PYLIB_VAR) != pylib:
+        _apply({PYLIB_VAR: pylib})
 
     # --- Overlay roots --- one `<NAME>_OVERLAY_ROOT` per installed overlay, the
     # same name `dotagents context` expands as a `<NAME_OVERLAY_ROOT>` placeholder
@@ -1208,10 +1227,11 @@ def env_cache_key(scope: Scope, base_env: "dict[str, str]", *parts: str) -> str:
     import hashlib
 
     from dotagents import __version__
+    from dotagents._resources import pyz_archive
 
     scope = _absolute_scope(scope)
     items = [
-        __version__, sys.executable or "", os.getcwd(), scope.level,
+        __version__, sys.executable or "", pyz_archive() or "", os.getcwd(), scope.level,
         str(scope.user_root), str(scope.agents_root), str(scope.project_root),
         str(scope.system_root), *parts,
     ]