dotagents-cli 0.3.4__tar.gz → 0.4.0__tar.gz

{dotagents_cli-0.3.4 → dotagents_cli-0.4.0}/CHANGELOG.md

@@ -7,6 +7,339 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-09
+
+### Security
+
+- `env --format export` (the form the SessionStart hook writes into
+  `$CLAUDE_ENV_FILE`) now single-quotes every value (`'` → `'\''`, control
+  characters via bash's `$'...'`). Values were JSON-quoted, i.e. inside DOUBLE
+  quotes, so `$(...)`, backticks and `$VAR` in any env value were executed or
+  expanded when the file was sourced, while `\n` and non-ASCII (`\u00e9`)
+  arrived as literal escape text.
+- The env chain no longer executes or sources a project's own top-level
+  `env.py` / `env`: only `<project>/.agents/*` and the user-local
+  `local.env` / `pre.local.env` run at the project levels. Every session start
+  ran the chain, so opening a session in a cloned repository with a top-level
+  `env.py` was code execution from that checkout.
+
+### Added
+
+- feat: **`dotagents findings`** — a per-scope findings queue, shipped as the
+  one bundled command module (`_overlay/dotagents/cmds/findings.py`). A
+  finding is one markdown file shaped like an agent memory (frontmatter
+  `name`/`description`/`status`/`created` for the index line, details in the
+  body) under `<scope-root>/findings/`: the project's `.agents/findings/` by
+  default, the user store's with `-g`, anywhere with `--dir`. `add` records
+  one (`--body`/`--body-file`, `-` = stdin), `list` prints the active ones
+  (`--all`, `--processed`, `--json`), `show` prints one (`--json`), `done`
+  appends a required `## Resolution` and MOVES the file to `processed/`
+  (never deletes), `reopen` moves it back, `remove` deletes a mistaken one,
+  `index` regenerates `INDEX.md` (active first, then processed — every
+  mutating command rewrites it), `path` prints the queue's location.
+  Hand-written notes without a frontmatter are listed too and gain one when
+  first rewritten. Files are written LF-only on every platform.
+- chore: `init` no longer copies bundled command modules (`*.py`) from the
+  package's `dotagents/cmds/` into the store — only the README. The bundled
+  dir is always a discovery source, so a copy added nothing, and being
+  create-if-absent it would have pinned the first-installed version of
+  `findings` and shadowed every later one. A same-named module dropped into a
+  scope's `dotagents/cmds/` still overrides the bundled one.
+- feat: `env` prepends every level's existing **`lib/`** dir to `PYTHONPATH`,
+  the way it already prepends every level's `bin/` to `PATH` — overlays first,
+  then the store, then the project's `.agents/`, never the project root — and
+  does so before the env-file chain, so an `env.py` (and every subprocess that
+  inherits the env) can `import` an overlay's `lib/` module. Only dirs that
+  exist are added, and `PYTHONPATH` is untouched when there are none. The
+  formatter already converts any `*PATH` variable between Windows and POSIX
+  forms, so `PYTHONPATH` gets the same treatment as `PATH`.
+- feat: `env` emits one **`<NAME>_OVERLAY_ROOT`** per installed overlay (the
+  overlay's install dir), seeded before the env-file chain like the two scope
+  roots and, like them, only if unset. `NAME` is the overlay's directory name
+  upper-cased with every non-alphanumeric character turned into `_`
+  (`my-ov.v2` → `MY_OV_V2_OVERLAY_ROOT`). This is the same name `context`
+  already expanded as a `<NAME_OVERLAY_ROOT>` placeholder; the two now share
+  one naming function, so an env file and a context file name an overlay's
+  install dir identically. The variable is derived from the same normalized
+  name `overlays add` installs under (`Overlay.normalize_name`), so the var
+  for `overlays/<n>/` is always `Overlay.root_var_for(n)`.
+
+### Changed
+
+- The overlay-root note `overlays add` writes above routing lines cites
+  `$ENGINEERING_OVERLAY_ROOT` as its example; the docs and CI install the
+  `engineering` overlay, which now carries the flows, references, and tools that
+  were separate overlays (each is a category dir under it, never `<name>/<name>/`).
+- The contract-A walk is `Scope.paths(*names, include_missing=False)`; the
+  `_resolve` module (and its API docs page) is gone, its `LEVEL_NAMES` live in
+  `_scope`.
+- The system store is a store like the others. `Scope.system_root`
+  (`/etc/agents`, or `$AGENTS_SYSTEM_ROOT`) heads `Scope.stores`, and the
+  contract-A walk goes store by store -- system, user, project -- each store's
+  overlays first, then the store itself, then the project root; the hardcoded
+  `/etc/agents` tier and its odd position (after the user store's overlays,
+  before the user store) are gone. A system overlay is shadowed by a same-named
+  user or project one. `overlays list` prints one `installed (<level>)` block
+  per store that has anything, most specific first.
+- The library walk takes one object. `Scope` now carries the whole picture
+  (`user_root`, `project_root`, `stores`, `overlays`, `files(*names)`), and
+  `get_file_paths`, `get_environment`, `get_diff`, `resolve_env_files`,
+  `get_bin_paths`, `get_lib_paths`, `get_overlay_roots`, `assemble_context` and
+  `assemble_context_data` take a `Scope` instead of the
+  `(agents_dir, project_root, global_scope)` keyword triple ported from the
+  precursor. `Scope.of(agents_dir=, project_root=, global_scope=)` builds one
+  from resolved parts. No compatibility form: the CLI is the public surface.
+- **One overlay name, two scopes = one overlay, the project's.** A project
+  session uses the user store's overlays AND the project's (`<project>/.agents/
+  overlays/`); an overlay installed in both under the same name is the
+  project's copy only, which shadows the store's for bin, lib, env files,
+  cmds, `CONTEXT.md` and the `<NAME>_OVERLAY_ROOT` var (a store root the
+  session had already pinned is re-pointed). `-g` sees the user store alone.
+  `Overlay.installed(*stores)` is the one discovery behind the contract-A
+  walk, `env`, `context` and `overlays list` / `show`; the `_scope`
+  `discover_overlays` pass-through is gone (`Overlay.discover(root)` is the
+  single-root form). `overlays list` in a project scope prints both
+  `installed (project)` and `installed (user)`, marking shadowed store copies;
+  `overlays show` falls back to the user store's copy before the source.
+- Overlay routing lines refer to overlay files through `$<NAME>_OVERLAY_ROOT`
+  (the variable `env` exports per installed overlay), not a hard `~/.agents/`
+  path; when a merged block carries such lines, `AGENTS.md` gets one line
+  above them saying what the token is and how to resolve it. The example
+  overlays on the `overlays` branch follow this convention and ship no setup
+  scripts any more (PATH, PYTHONPATH and the root var are `env`'s job; an
+  overlay's own env belongs in its `env.py`). `tools/cloud-setup.sh` finds
+  the private-sync settings snippet inside the installed overlay.
+- The base overlay's findings workflow now goes through the command. The
+  managed `AGENTS.md` rule ("Global-config misses"), `dotagents/DECISIONS.md`
+  ("How findings become config") and the skeleton README say
+  `dotagents findings add -g ...` to record a miss, `list -g` / `show -g` to
+  triage and `done -g <name> -r ...` to close one, instead of "drop a note in
+  `~/.agents/dotagents/findings/`". With that, the user store's queue is
+  **`~/.agents/findings/`** (the command's `-g` default), no longer
+  `~/.agents/dotagents/findings/`. An existing queue at the old path keeps
+  working with `--dir ~/.agents/dotagents/findings`, or move it once:
+  `mv ~/.agents/dotagents/findings ~/.agents/findings`. Re-run `dotagents init`
+  to refresh the managed block.
+- refactor: `dotagents._overlays` is now built around an **`Overlay`** class —
+  one overlay is one directory, and everything that depends on a single
+  overlay is a method or property on it: `.path` / `.name` / `.normalized_name`
+  / `.root_var` / `.is_valid` / `.manifest_path`, `.read_manifest()` /
+  `.priority` / `.sort_key`, `.find_setup_script()` / `.run_setup(...)`,
+  `.files()` / `.rule_blocks(...)` / `.apply_to(...)` / `.install_to(...)` /
+  `.merge_rules_into(...)`. The name rules are static methods
+  (`Overlay.is_valid_name` / `.normalize_name` / `.root_var_for`), so a caller
+  holding only a name uses the same rule as one holding a directory;
+  `Overlay.discover(root)` is the single discovery routine that `_scope`,
+  the contract-A resolver and `env` all share, and `Overlay.sort_by_priority`
+  the single merge order. The module-level functions they replace
+  (`read_manifest`, `find_setup_script`, `run_overlay_setup`, `overlay_files`,
+  `rule_blocks`, `apply_overlay`, `install_overlay_dir`, `merge_overlay_rules`,
+  `overlay_sort_key`, `sort_overlays_by_priority`, `normalize_name`,
+  `overlay_root_var`) are gone, as are `_scope.is_valid_overlay_name` and
+  `_scope.normalize_overlay_name`. `recompose_overlay_block` stays a module
+  function (it works over a set of overlays) and now accepts `Overlay`
+  instances or directories. `_overlays` is a private module, so no public
+  version signal.
+
+- fix: an `env.py` may now print its changes as one JSON object **per line**,
+  merged in order (a later line wins), as well as a single object. Each
+  overlay's `setup.py` appends its own managed block to the store's `env.py`
+  and each block prints its own object, so a store with two such overlays
+  (e.g. `net` + `private-sync`) emitted two lines — and the single-object
+  reader rejected the whole output, silently dropping both overlays' vars. A
+  line that is not a JSON object still voids the whole script's contribution,
+  so a half-applied change set is impossible.
+- fix: `init --agents codex` run from a session whose environment already
+  carried dotagents' identity vars (which its own env-loader hook exports —
+  `AGENT=claude-code` and friends in every command a Claude session runs)
+  wrote a Codex env block with no identity at all: the identity stamp never
+  overrides a value already present, so every key counted as "already set",
+  to Claude's values. When the agent is named explicitly the identity is now
+  that agent's, overriding the base env; without an explicit agent a pinned
+  value is respected as before.
+- fix: the built `.pyz` lost the help text of the umbrella's own `--cmdspath`
+  flag (every subcommand's help survived). The zipapp source-repoint shim
+  covered each `dotagents.cli.<x>` command module but not the `dotagents.cli`
+  package itself, and it resolved a package's source as `cli.py` instead of
+  `cli/__init__.py`, so the umbrella kept its zip-internal `__file__` and duho
+  fell back to a bare flag. Both fixed; the top-level help in a `.pyz` now
+  matches a plain install.
+- fix: `context`'s `<NAME_OVERLAY_ROOT>` placeholder now also maps `.` (and any
+  other non-alphanumeric character) in an overlay name to `_`, not only `-` —
+  the name has to be a legal shell variable to be emitted by `env`, and the
+  placeholder follows the same rule. Overlays whose names contain only letters,
+  digits, `_` and `-` are unaffected.
+
+### Fixed
+
+- **One broken command module no longer breaks every `dotagents` call.**
+  Discovery skips a source that fails to import for any reason (a
+  `SyntaxError`, an exception at import time) with a warning naming it. It
+  caught `ImportError` only, and duho propagates the rest on purpose, so a
+  typo in `~/.agents/dotagents/cmds/foo.py` made `env`, `context`, `init` and
+  even `--version` traceback, i.e. the hooks delivered nothing.
+- **No more temp-directory litter from the `.pyz`.** Everything a zipapp run
+  extracts (package data, the repointed module sources) lives under one
+  per-process scratch directory removed at exit; a `mkdtemp` per item with no
+  cleanup had left 632 `dotagents-*` directories in one machine's `%TEMP%`.
+- `overlays add` installs a source dir spelled `my_overlay` (it normalized to
+  `my-overlay` and looked only that up), validates and resolves EVERY name
+  against the source before touching anything (`add good bad` used to install
+  `good`, run its setup, then fail), installs each manifest's `requires`
+  first (transitively; `--no-requires` to skip; a missing requirement warns, a
+  cycle errors), publishes skills from the INSTALLED copy (a symlink into the
+  source dies with a temporary checkout and could never be matched by
+  `remove`), and reports the setup script on a dry run.
+- `overlays remove` normalizes names (`add My_Ov` + `remove My_Ov` said "not
+  installed") and recomposes the managed block over the overlays that remain,
+  so an overlay's rules and routing leave `AGENTS.md` with it; the warning
+  that pointed at the removed `dotagents install` is gone.
+- `overlays sync` honours `--copy` (declared and ignored) and gains
+  `--overwrite`, which replaces installed files whose content differs from the
+  source; without it a sync never updated an upstream change to an existing
+  file.
+- New `overlays show <name>` describes an overlay (installed copy first, else
+  the source): description, priority, requires, routing, rules, setup script,
+  skills, file count, root var; `--json`.
+- The manifest reader strips trailing `#` comments quote-aware and finds an
+  array's closing `]` by scanning, so `routing = ["a"] # note` no longer
+  swallows the NEXT array (a rules path became a routing line), an indented
+  `]` no longer yields `[]`, `'single-quoted'` strings parse, and
+  `priority = 5 # low` is 5, not 500. `description` and `requires` are read.
+- `_compose_block` with a base that has no `## Load on demand` heading appends
+  the overlay rules at the end of the block, as its warning always claimed;
+  they were dropped.
+- `build-pyz` outside a source checkout is a clear error instead of a
+  `FileNotFoundError`.
+- `dotagents`, `overlays` and `findings` invoked with no subcommand print
+  their help and exit 2 instead of logging a hint and exiting 0.
+- `--agents-dir X` on the command line is honoured by command discovery, so
+  the store the command is about to use is the one whose `cmds/` are found.
+- `findings add` rejects a name already carried by another note's frontmatter
+  (`get` matches frontmatter names first, so `done` would have processed the
+  wrong file).
+- Two overlay dirs with the same manifest `name` sort deterministically (dir
+  name is the final tiebreaker).
+- **SessionStart context is no longer injected twice.** The PowerShell
+  variants of Claude's `SessionStart` / `CwdChanged` handlers run only when
+  `bash` is not on PATH. Both handlers fire on every session, and on a Windows
+  box that has both Git Bash and PowerShell both succeeded, so the same
+  payload landed twice at every session start (two identical 100 KB
+  payloads, measured).
+- The Codex `PreToolUse` env-loader prefix is quoted correctly: inside
+  `"$(...)"` its `\"` were literal quote characters, so `PATH` became
+  `".agents/bin:...:<last>"` with the quotes, the project `.agents/bin` was
+  never found and the last original entry was broken. The rewritten command
+  is now executed in bash by a test.
+- Hook merging keeps a user's hook that shares a matcher-object with an older
+  shape of ours (the whole object used to be dropped), and a revised `shell`
+  / `matcher` / `commandWindows` / status on an unchanged command text now
+  reaches existing users instead of being kept as-is.
+- Claude's skills link is per skill into `<config>/skills/<name>`: linking the
+  whole directory failed with "conflict" for anyone who already had their own
+  `~/.claude/skills`, so overlay skills never reached them. A same-named skill
+  the user placed there stays.
+- Every hook command resolves the store as `$AGENTS_HOME` when set (bash:
+  `${AGENTS_HOME:-$HOME/.agents}`), so a custom store gets hooks that can find
+  `dotagents`; the PowerShell SessionStart variant prefers the project's own
+  `.agents\bin` like the bash one. The PowerShell tool env-loader runs
+  `env --diff` instead of re-assigning the whole environment on every call.
+- The bash `CwdChanged` handler re-pins `AGENTS_PROJECT_ROOT` into
+  `$CLAUDE_ENV_FILE` when the new directory carries a `.agents/`; the
+  SessionStart pin is only-if-unset, so a `cd` into another project used to
+  keep the first project's root for the rest of the session.
+- The Antigravity hook pins the project root from `workspacePaths` (cwd and
+  `AGENTS_PROJECT_ROOT` of the `dotagents context` spawn), as its docstring
+  already claimed, honours `$AGENTS_HOME` when locating `dotagents`, and
+  injects nothing when the assembly exits non-zero. Its constant is
+  `PREINVOCATION_HOOK_SCRIPT` (it wires a `PreInvocation` hook).
+- Unpublishing an overlay's skills compares file CONTENT, not just names: a
+  copy the user had edited (same file set, different bytes) was deleted as
+  the overlay's.
+- **The store's rules now reach Claude on a fresh install.** `init` writes the
+  `@` include where Claude Code reads it -- `~/.claude/CLAUDE.md` for the user
+  store, `<project>/.claude/CLAUDE.md` for a project -- as an appended managed
+  block, skipped when the include line is already there by hand. Before, it
+  wrote `<store>/CLAUDE.md` (which Claude never reads) while `context`
+  subtracted `~/.agents/AGENTS.md` as "already loaded" on a static assumption,
+  so nothing delivered the base rules. `context` now subtracts exactly what
+  the harness's entry files actually `@`-include (`Agent.loaded_paths`),
+  recursively, on this machine.
+- `context` no longer inlines every `.md` file the sources mention. Inlining is
+  opt-in (`--inline` / `inline=True`): the base rules say to read those files
+  only when a task needs them, and inlining every mention made a 100 KB
+  SessionStart payload, most of it a changelog and an API header that
+  happened to be named in prose. With `--inline`, sources and harness-loaded
+  files are never inlined a second time, and placeholders inside inlined
+  files expand.
+- Overlay priority ordering and `<NAME_OVERLAY_ROOT>` placeholder expansion in
+  `context` never worked: the resolver labels an overlay entry with the
+  overlay's name and the code compared it to the literal `"overlay"`. Every
+  installed overlay now gets a placeholder (matching `env`), not only one that
+  ships a `CONTEXT.md`.
+- `context --write-agent` merges the context into the harness's own
+  instruction file under the PROJECT root -- Claude `.claude/CLAUDE.md`, Codex
+  `AGENTS.md`, Gemini `GEMINI.md`, Cursor `.cursorrules`, Copilot
+  `.github/copilot-instructions.md`, Antigravity `.agents/rules/dotagents.md`
+  -- as a managed `dotagents:context` block that is refreshed in place. It
+  used to overwrite a file under the user STORE; for Codex that was
+  `<store>/AGENTS.md`, a context source, so every run re-inlined the previous
+  run's output. `--format` is validated, and `--write-agent` refuses `--format
+  json` or an output path instead of silently ignoring one.
+- Project-scope overlays (`<project>/.agents/overlays/`, where `overlays add`
+  installs by default) are now part of the contract-A walk: their `bin`,
+  `lib`, env files, `cmds` and `CONTEXT.md` resolve, after the user store's,
+  and each gets a `<NAME>_OVERLAY_ROOT` (a project overlay wins a name clash).
+  Nothing consumed them before except the `AGENTS.md` recompose.
+- Managed-block markers must be a line of their own: a prose MENTION of the
+  markers (the base `AGENTS.md` carries one) was matched as the block, so the
+  sentence around it was replaced and a second block appeared. A begin marker
+  with no end after it is refused with a clear error instead of gaining a
+  second block; a `--from` base without markers is a usage error, not a
+  traceback.
+- Every managed file (`AGENTS.md`, the includes, `settings.json`, `hooks.json`,
+  context targets) is written LF-only on every platform; `settings.json` /
+  `hooks.json` are written atomically and keep non-ASCII values as-is.
+- The user scope is recognized by the configurable store (`$AGENTS_HOME`), not
+  the literal `~/.agents`: `init -g` with a custom store used to wire Claude's
+  hooks into `<store-parent>/.claude/settings.local.json`, which nothing reads.
+- `CODEX_HOME` no longer marks a running Codex session (it is the user's
+  persistent state-dir override, exported from a shell profile); the
+  `CODEX_SANDBOX*` vars still do, and `CODEX_HOME` still locates the config.
+- An unknown `--agents` name no longer overrides a pinned identity in `env`.
+- An overlay cannot be named like a contract-A level (`user`, `project`,
+  `system`, `project-root`, `default`, `overlay`); its dir name is its level
+  label in the walk and would collide with the per-level filename keys.
+- A directory named `env` (a common virtualenv name) is no longer "sourced" as
+  an env file; only regular files resolve.
+- Sourcing a plain env file that fails (missing, a directory, a syntax error)
+  now contributes nothing and warns, as documented. The bash command was a
+  `;` list, so `env -0` ran regardless and reported rc 0 with whatever had
+  been assigned before the error.
+- Bash's own `PWD` (in `/c/...` form), `OLDPWD`, `SHLVL` and `MSYSTEM*` are no
+  longer reported as a sourced file's changes; a non-UTF-8 byte in a sourced
+  value no longer aborts the whole assembly.
+- `env --format auto` returned `cmd` when invoked through the `dotagents.cmd`
+  wrapper from PowerShell (the wrapper cannot exec, so `cmd.exe` sits between
+  Python and the shell); a `cmd` whose own parent is a shell is now skipped.
+- `env` formats: `fish` escapes backslashes; `cmd` doubles `%` and flattens
+  newlines; `yaml` quotes values a reader would type (`true`, `123`, `null`,
+  `1e3`, leading indicators); `powershell`/`cmd` no longer mangle a
+  forward-slash native path (`C:/a/tools` became `C;A:\tools`); output is
+  written as UTF-8 bytes so a non-Latin-1 value cannot crash on a cp1252
+  console.
+- `init -g`, `overlays ... -g` and every other `resolve_scope` caller honour
+  `$AGENTS_HOME` (the var `env` itself emits) instead of the literal `~/.agents`,
+  and `--agents-dir` overrides the store in the project scope too (it was
+  silently ignored without `-g`). `resolve_user_store` moved to `_scope`
+  (still re-exported from `dotagents.cli`); the `findings` command's local
+  workaround is gone.
+- `overlays list` / `overlays add` apply the one overlay-name rule when listing
+  a source (`__pycache__`, `2fast`, dotdirs are no longer "available"), and a
+  bad source path names whether it came from `--source` or the env var.
+- `findings list` / `show` write UTF-8 bytes, so a description with a
+  non-Latin-1 character no longer raises on a cp1252 console.
+
 ## [0.3.4] - 2026-08-16
 
 ### Changed
@@ -46,8 +379,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 - **`build-pyz` no longer bundles the repo's `tools/`** as `dotagents/_tools`
   inside the built `.pyz`, and the `--tools-dir` flag is gone with it. Nothing
-  read `_tools`: the compiled `audit`/`leak-check` wrappers that shelled out to
-  it no longer exist. Every shipped artifact carried the dead weight while
+  read `_tools`: the compiled `audit` wrapper and a personal scanner's wrapper that
+  shelled out to it no longer exist. Every shipped artifact carried the dead weight while
   `tools/audit.py` claimed it was "not shipped in the `.pyz`" — now true.
 - **`dotagents._sync`** — a `pathlib_next.PathSyncer` wrapper that existed only
   to back the `install` subcommand's backup/copy report. `install` was removed
@@ -62,8 +395,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   no longer claims to ship as a bundled `audit` command module (it is repo CI
   tooling and there is no `dotagents audit`) and its `--root` help names the
   real default; `install.py`'s usage line drops the removed `install` and the
-  never-existing `audit`; the README's `tools/` row says where `leak-check`
-  actually lives; the API header names the real `_overlays` exports
+  never-existing `audit`; the README's `tools/` row says where a personal
+  command module actually lives; the API header names the real `_overlays` exports
   (`install_overlay_dir` / `apply_overlay` / `run_overlay_setup`) and the real
   package-data dirs (`_overlay` / `_overlays_src`, never a `skeleton/`); and
   `_merge._extract_block`'s docstring now says it returns the block *including*
@@ -248,7 +581,7 @@ Patch release: the PATH/POSIX-conversion fix above (the only change since 0.3.0)
   directory. Symlink where the OS permits, copy otherwise (a copy is a snapshot;
   re-run `init` to refresh).
 
-- feat: `tools/leak_check.py` now also scans commit messages (current branch history)
+- feat: the personal leak scanner (then in `tools/`) now also scans commit messages (current branch history)
   for agent-session trailers/URLs — a `Claude-Session:` trailer or `claude.ai/code/session`
   link — and exits 1 on any hit. The trailer is auto-added by the agent harness and
   exposes a session id in public history if it slips through; the pre-existing tracked-file
@@ -387,7 +720,7 @@ Patch release: the PATH/POSIX-conversion fix above (the only change since 0.3.0)
   `recovery`, `references`, `python`/`node`/`rust`, `agents`, `tools`. Each carries
   an `overlay.toml` manifest for a future `dotagents overlays` subcommand.
 - Repo layout: the CLI in `src/dotagents/`, config overlays in `overlays/`, required
-  tooling in top-level `tools/` (`audit_config.py`, `leak_check.py`); repo root holds
+  tooling in top-level `tools/` (`audit_config.py` and a personal leak scanner); repo root holds
   the installer, CI, repo-development directives, and the tracked, sanitized
   `.agents/` design log (index + per-decision files) + plans. `audit_config.py` has
   `--repo-hygiene` (scans tracked files for personal/machine-specific leftovers).

{dotagents_cli-0.3.4 → dotagents_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.3.4
+Version: 0.4.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
@@ -102,7 +102,7 @@ them. Everything else is repo infrastructure.
 | --- | --- |
 | `src/dotagents/` | The installable `dotagents` CLI (`init`/`overlays`/`context`/`env`/`build-pyz`) — that is the whole shipped surface; commands beyond it come from overlays or your own `cmds/` modules |
 | `src/dotagents/_overlay/` | The **base overlay** `init` writes: `AGENTS.md` scaffolding, `CLAUDE.md`, `dotagents/DECISIONS.md` (empty design-log index), and an empty `dotagents/cmds/` dir — your drop-in point for your own command modules. Neutral — imposes no flows, ships no command |
-| `tools/` | Repo tooling, not shipped: `audit.py` (CI structure check) and `cloud-setup.sh`. `leak-check` is not here either — it is a personal command module you keep in your own private `.agents/dotagents/cmds/` |
+| `tools/` | Repo tooling, not shipped: `audit.py` (CI structure check) and `cloud-setup.sh`. Personal scanning tools are not here either — keep them as command modules in your own private `.agents/dotagents/cmds/` |
 | `install.py` | Thin shim over `dotagents.cli.main()`, kept at this filename for muscle memory |
 
 The **example overlays** — the `flows` workflow set, per-language `kb/` + templates,
@@ -167,7 +167,7 @@ where the example overlays live. Installed overlays are *discovered* by their pr
 under `<scope>/.agents/overlays/` — there is no registry file.
 
 ```bash
-dotagents overlays add python flows        # install into the scope, publish skills, merge D59 rules/routing
+dotagents overlays add python engineering  # install into the scope, publish skills, merge D59 rules/routing
 dotagents overlays list                    # installed (discovered) + available (from source)
 dotagents overlays sync 'py*'              # refresh installed overlays matching a glob, resync their skills
 dotagents overlays remove python           # delete the overlay dir + unpublish its skills
@@ -214,7 +214,7 @@ Then wire your runner to it — e.g. Claude Code: put `@AGENTS.md` in
 `~/.claude/CLAUDE.md`... which is exactly what the installed `CLAUDE.md` contains.
 
 **Or let your agent do it:** point it at this repo and say —
-> Read README.md, run `python install.py init && python install.py overlays add flows -g`,
+> Read README.md, run `python install.py init && python install.py overlays add engineering -g`,
 > and confirm `~/.agents/overlays/flows/flows/PLAN.md` exists.
 
 ## Private sync (per-user + per-project, one private repo)
@@ -283,8 +283,8 @@ committed — so what's public here is only the CLI, the base overlay, and the o
 overlays. If you fork, keep the tracked surface free of personal paths and private
 project names. `dotagents audit` validates config *structure* only; personal-leak
 scanning (machine paths, private plan names, session trailers) is a separate,
-personal `leak-check` tool you run locally before a push — it lives in your private
-`.agents/`, not shipped in this repo.
+personal tool you run locally before a push — it lives in your private `.agents/`,
+not shipped in this repo.
 
 ## Documentation
 

{dotagents_cli-0.3.4 → dotagents_cli-0.4.0}/README.md

@@ -41,7 +41,7 @@ them. Everything else is repo infrastructure.
 | --- | --- |
 | `src/dotagents/` | The installable `dotagents` CLI (`init`/`overlays`/`context`/`env`/`build-pyz`) — that is the whole shipped surface; commands beyond it come from overlays or your own `cmds/` modules |
 | `src/dotagents/_overlay/` | The **base overlay** `init` writes: `AGENTS.md` scaffolding, `CLAUDE.md`, `dotagents/DECISIONS.md` (empty design-log index), and an empty `dotagents/cmds/` dir — your drop-in point for your own command modules. Neutral — imposes no flows, ships no command |
-| `tools/` | Repo tooling, not shipped: `audit.py` (CI structure check) and `cloud-setup.sh`. `leak-check` is not here either — it is a personal command module you keep in your own private `.agents/dotagents/cmds/` |
+| `tools/` | Repo tooling, not shipped: `audit.py` (CI structure check) and `cloud-setup.sh`. Personal scanning tools are not here either — keep them as command modules in your own private `.agents/dotagents/cmds/` |
 | `install.py` | Thin shim over `dotagents.cli.main()`, kept at this filename for muscle memory |
 
 The **example overlays** — the `flows` workflow set, per-language `kb/` + templates,
@@ -106,7 +106,7 @@ where the example overlays live. Installed overlays are *discovered* by their pr
 under `<scope>/.agents/overlays/` — there is no registry file.
 
 ```bash
-dotagents overlays add python flows        # install into the scope, publish skills, merge D59 rules/routing
+dotagents overlays add python engineering  # install into the scope, publish skills, merge D59 rules/routing
 dotagents overlays list                    # installed (discovered) + available (from source)
 dotagents overlays sync 'py*'              # refresh installed overlays matching a glob, resync their skills
 dotagents overlays remove python           # delete the overlay dir + unpublish its skills
@@ -153,7 +153,7 @@ Then wire your runner to it — e.g. Claude Code: put `@AGENTS.md` in
 `~/.claude/CLAUDE.md`... which is exactly what the installed `CLAUDE.md` contains.
 
 **Or let your agent do it:** point it at this repo and say —
-> Read README.md, run `python install.py init && python install.py overlays add flows -g`,
+> Read README.md, run `python install.py init && python install.py overlays add engineering -g`,
 > and confirm `~/.agents/overlays/flows/flows/PLAN.md` exists.
 
 ## Private sync (per-user + per-project, one private repo)
@@ -222,8 +222,8 @@ committed — so what's public here is only the CLI, the base overlay, and the o
 overlays. If you fork, keep the tracked surface free of personal paths and private
 project names. `dotagents audit` validates config *structure* only; personal-leak
 scanning (machine paths, private plan names, session trailers) is a separate,
-personal `leak-check` tool you run locally before a push — it lives in your private
-`.agents/`, not shipped in this repo.
+personal tool you run locally before a push — it lives in your private `.agents/`,
+not shipped in this repo.
 
 ## Documentation
 

dotagents_cli-0.4.0/docs/api/fs.md

@@ -0,0 +1,3 @@
+# Filesystem
+
+::: dotagents._fs

{dotagents_cli-0.3.4 → dotagents_cli-0.4.0}/docs/api/reference.md

@@ -13,11 +13,12 @@ form its API. Generated from docstrings, organized by module:
   command.
 - **[Context](context.md)** — assembling the effective context for agents.
 - **[Environment](env.md)** — chained env-file assembly and `env.py` execution.
-- **[Resolution](resolve.md)** — the precedence walk / filename resolution
-  (Contract A).
 - **[Merge](merge.md)** — the managed-block merge for `init`'s `AGENTS.md` /
-  `CLAUDE.md`, and for other comment syntaxes (e.g. TOML) via `begin_marker`/
+  `CLAUDE.md`, the harness-entry `@` include, the `context --write-agent`
+  block, and other comment syntaxes (e.g. TOML) via `begin_marker`/
   `end_marker`/`append`.
+- **[Filesystem](fs.md)** — the one text-file writer every module uses:
+  LF-only on every platform, optionally atomic.
 - **[Hooks](hooks.md)** — additive, idempotent merge of dotagents' hooks into an
   agent's own settings/config file.
 - **[Skills](skills.md)** — publishing an overlay's skills into a scope's shared dir.