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

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

@@ -7,6 +7,87 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.4] - 2026-08-16
+
+### Changed
+
+- chore: raise the dependency floors and scope them to a minor series —
+  `duho>=0.5.0,<0.6` (was `>=0.4.0`) and `pathlib_next>=0.9.0,<0.10` (was
+  `>=0.8.0`). Both are pre-1.0, where a minor bump is the signal that the
+  documented API broke, so the ceiling is what keeps the next one from arriving
+  unannounced. Neither floor sits above its `.0` patch: the suite and a CLI
+  smoke pass at exactly duho 0.5.0 and pathlib_next 0.9.0, so nothing here needs
+  an API added later in either series. The one 0.5.0 behavior change that
+  reaches this CLI's surface is list-typed *option* fields taking one value per
+  occurrence instead of `nargs="*"` — `--agents` and `--cmdspath` are unaffected,
+  since the documented forms are the comma list (`--agents a,b`, split by the
+  command itself) and the repeated flag, both of which behave the same either
+  way. Exercised end to end against duho 0.5.4 / pathlib_next 0.9.2 on Python
+  3.9 and 3.14. The `[uri]`/`[http]`/`[sftp]`/`[s3]` extras stay unversioned
+  passthroughs to `pathlib_next`'s own extras.
+- chore: `build-pyz`'s vendored pins moved with those floors — the `.pyz` now
+  bundles duho 0.5.0 and pathlib_next 0.9.0 (was 0.4.0 / 0.8.0), the minimum the
+  package claims to support rather than the latest patch. These pins are a
+  second copy of the dependency versions and had drifted a full minor series
+  behind, so the shipped zipapp bundled versions `pip install dotagents-cli`
+  would have refused. The rebuilt `.pyz` keeps full flag/help/positional
+  fidelity through the zipapp shim.
+
+## [0.3.3] - 2026-08-16
+
+### Added
+
+- feat: `env` and `context` gained **`--agents-dir`** (from the shared
+  `DotAgentsArgs` base) to override the store for one run. Their `-g/--global`
+  keeps its existing, narrower meaning here — *skip the project-level files* —
+  and now says so in `--help`.
+
+### Removed
+
+- **`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
+  `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
+  in 0.3.x; the module has had no callers since, no tests, and a return
+  annotation that disagreed with what it returned. `pathlib_next` remains a
+  dependency (duho, and `--from` URI support). Its API-reference page went with
+  it.
+
+### Fixed
+
+- docs: a cluster of "docs say X, tree does Y" corrections — `tools/audit.py`
+  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
+  (`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*
+  its marker lines, which is what it has always done and what callers rely on.
+- fix: **`stamp_identity` no longer pretends to emit `AGENTS_AGENT`.** The line
+  sourced the value from `$AGENTS_AGENT` and only assigned when that same key
+  was unset, so it could never emit anything — while the docstring and the
+  shipped API header both advertised the var. Line removed; the API header's
+  "emitted by the identity/env layer" list now drops both `AGENTS_AGENT` and
+  `AGENTS_CODE_SESSION_ID` (the latter was deliberately never emitted) and says
+  so explicitly, so nothing branches on a var that never arrives.
+- fix: **`dotagents env` and `dotagents context` now resolve their roots instead
+  of hardcoding them.** Both took `Path.cwd()` as the project root and
+  `~/.agents` as the user store, so `$AGENTS_PROJECT_ROOT` (or the agent-native
+  `$CLAUDE_PROJECT_DIR`) and `$AGENTS_HOME` were ignored by the two commands
+  that most needed them — a `SessionStart` hook runs `dotagents context` from
+  wherever the session happens to start, so a pinned project root was silently
+  dropped and a relocated store was never read. They now use
+  `_scope.project_root_default()` and the new
+  `dotagents.cli.resolve_user_store()` (`--agents-dir` → `$AGENTS_HOME` →
+  legacy `$DOTAGENTS_AGENTS_DIR` → `~/.agents`), matching what the package's own
+  `resolve_scope` docstring and command discovery already promised. Behavior is
+  unchanged when none of the vars are set.
+
 ## [0.3.2] - 2026-07-25
 
 ### Added

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.3.2
+Version: 0.3.4
 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
@@ -41,8 +41,8 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
-Requires-Dist: duho>=0.4.0
-Requires-Dist: pathlib-next>=0.8.0
+Requires-Dist: duho<0.6,>=0.5.0
+Requires-Dist: pathlib-next<0.10,>=0.9.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == 'dev'
 Provides-Extra: docs
@@ -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/` | Required tooling (not an overlay): `cloud-setup.sh` (`leak-check` moved to the opt-in `leak-check` overlay, D84) |
+| `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/` |
 | `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,

{dotagents_cli-0.3.2 → dotagents_cli-0.3.4}/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/` | Required tooling (not an overlay): `cloud-setup.sh` (`leak-check` moved to the opt-in `leak-check` overlay, D84) |
+| `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/` |
 | `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,

{dotagents_cli-0.3.2 → dotagents_cli-0.3.4}/build.py

@@ -3,9 +3,9 @@
 
 Thin root-level wrapper over ``dotagents build-pyz`` (``dotagents.cli.build_pyz``):
 it vendors ``duho`` + ``pathlib_next`` into the archive (via ``pip install --target``,
-using **the Python that runs this script**), copies the ``dotagents`` package and the
-required ``tools/``, strips caches/metadata, and packages a runnable zipapp. The result
-needs no ``pip install`` on the target machine.
+using **the Python that runs this script**), copies the ``dotagents`` package, strips
+caches/metadata, and packages a runnable zipapp. The result needs no ``pip install``
+on the target machine. The repo's ``tools/`` is CI tooling and is NOT bundled.
 
 Usage:
     python build.py                      # -> dist/dotagents.pyz

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

@@ -21,4 +21,3 @@ form its API. Generated from docstrings, organized by module:
 - **[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.
-- **[Sync](sync.md)** — the `PathSyncer` backup/copy wrapper for `install`.

{dotagents_cli-0.3.2 → dotagents_cli-0.3.4}/docs/guide/commands.md

@@ -155,7 +155,14 @@ dotagents context --write-agent                # write each agent's native confi
 - `--write-agent` — write each agent's native config file instead of `[output]`.
 - `--agents <a,b>` — which agents to generate for (default: the active agent).
 - `--format markdown|system-reminder|json` — output shape.
-- `-g` / `--global` — user scope.
+- `-g` / `--global` — skip the project-level context files (the store is unaffected).
+- `--agents-dir <dir>` — user store override for this run.
+
+Roots: the store is `--agents-dir` → `$AGENTS_HOME` → `~/.agents`, and the project
+root is `$AGENTS_PROJECT_ROOT` → `$CLAUDE_PROJECT_DIR` → the cwd. A `SessionStart`
+hook runs this from wherever the session started, so pinning
+`AGENTS_PROJECT_ROOT` is what keeps the assembled context the same in every
+subdirectory.
 
 ## env
 
@@ -174,7 +181,12 @@ python -m dotagents env --diff --format json   # only vars that differ from the
   (`bat`/`batch`, `set "KEY=value"`), `fish` (`set -gx KEY value`). Data forms:
   `json`, `ini`, `yaml`. An explicit `--format` always wins.
 - `--diff` — emit only the change set vs. the caller's environment.
-- `-g` / `--global` — user scope.
+- `-g` / `--global` — skip the project-level env files (the store is unaffected).
+- `--agents-dir <dir>` — user store override for this run.
+
+Roots resolve exactly as for `context` above (`$AGENTS_HOME` /
+`$AGENTS_PROJECT_ROOT`, both of which `env` also emits — so a subprocess reading
+them agrees with the parent that wrote them).
 
 !!! warning
     `env` output is sensitive by design — it prints resolved values. Treat the

{dotagents_cli-0.3.2 → dotagents_cli-0.3.4}/install.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Entry point for the dotagents CLI (init / install / overlays / build-pyz / ...).
+"""Entry point for the dotagents CLI (init / overlays / context / env / build-pyz).
 
 Thin front over ``dotagents.cli.main()``, kept at this filename so existing
 muscle-memory/docs pointing at ``python install.py`` still work.
@@ -14,7 +14,7 @@ bare ``pip`` off PATH) guarantees the install lands in *this* Python, so the
 import that follows actually sees it. When everything is already importable it
 just dispatches -- no pip is ever run.
 
-Usage: python install.py <init|install|overlays|audit|build-pyz|...> [options]
+Usage: python install.py <init|overlays|context|env|build-pyz|...> [options]
 Run `python install.py --help` for the full subcommand/flag reference.
 """
 import os

{dotagents_cli-0.3.2 → dotagents_cli-0.3.4}/mkdocs.yml

@@ -46,7 +46,6 @@ nav:
       - Merge: api/merge.md
       - Hooks: api/hooks.md
       - Skills: api/skills.md
-      - Sync: api/sync.md
   - Changelog: changelog.md
 
 plugins:

{dotagents_cli-0.3.2 → dotagents_cli-0.3.4}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "hatchling.build"
 # redirect/placeholder before someone else does, but the CLI ships under -cli.
 [project]
 name = "dotagents-cli"
-version = "0.3.2"
+version = "0.3.4"
 authors = [{ name = "Jose A." }]
 description = "The dotagents CLI: install and manage a portable ~/.agents config for AI coding agents"
 readme = "README.md"
@@ -30,8 +30,8 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
-    "duho>=0.4.0",
-    "pathlib_next>=0.8.0",
+    "duho>=0.5.0,<0.6",
+    "pathlib_next>=0.9.0,<0.10",
 ]
 
 [project.optional-dependencies]

{dotagents_cli-0.3.2 → dotagents_cli-0.3.4}/src/dotagents/AGENTS.md

@@ -11,8 +11,17 @@ can read it without the source. Full docs: https://jose-pr.github.io/dotagents/
   `duho.app` with the discovered command set. Also the `dotagents` console script
   (`[project.scripts]`).
 - `dotagents.cli.Dotagents(LoggingArgs, Cli)` — the umbrella CLI class.
+- `dotagents.cli.DotAgentsArgs` — mix-in base carrying the shared `-g/--global` +
+  `--agents-dir` pair and `resolve_scope()`; an overlay-shipped command module
+  should inherit it (as the FIRST base) rather than redeclare the flags.
+- `dotagents.cli.resolve_user_store(agents_dir=None) -> Path` — the USER store
+  root: `agents_dir` (`--agents-dir`) → `$AGENTS_HOME` → legacy
+  `$DOTAGENTS_AGENTS_DIR` → `~/.agents`. Use it (not `resolve_scope`) when the
+  store is always the user store and the project scope only adds/removes tiers,
+  as in `env` / `context`.
 - Compiled command classes live in `dotagents.cli.<name>` (`init`, `overlays`,
-  `context`, `env`, `build_pyz`); each is a `class X(LoggingArgs, Cmd)` with a
+  `context`, `env`, `build_pyz`); each is a `class X(LoggingArgs, Cmd)` — or
+  `class X(DotAgentsArgs)`, which is that pair transitively — with a
   `__call__`. That is the WHOLE shipped surface — dotagents bundles no command
   module of its own. `link` / `sync` left the package with their logic (D85): the
   opt-in **private-sync** overlay ships them, renamed `link-project` /
@@ -30,8 +39,9 @@ can read it without the source. Full docs: https://jose-pr.github.io/dotagents/
 
 - `_agents` — `Agent` base type + per-agent adapters; `stamp_identity(...)` emits the
   standardized `AGENTS_*` / `AGENT` identity vars.
-- `_overlays` — `install_overlay` / `read_manifest` / `find_setup_script` /
-  `run_setup_script`; installs an overlay's files and collects its `routing` / `rules`
+- `_overlays` — `install_overlay_dir` (copy an overlay into a scope, self-describing)
+  / `apply_overlay` (lay its files down) / `read_manifest` / `find_setup_script` /
+  `run_overlay_setup`; installs an overlay's files and collects its `routing` / `rules`
   contributions to the managed `AGENTS.md` block. `DEFAULT_PRIORITY = 500`.
 - `_scope` — `resolve_scope(global_scope, agents_dir=None)` and `resolve_source(...)`;
   scope = *where installed overlays live* (user = the configurable store, project =
@@ -139,8 +149,6 @@ can read it without the source. Full docs: https://jose-pr.github.io/dotagents/
   that `python3` resolves to the Microsoft Store app-execution-alias stub and
   fails outright on this dev machine (exit 49), the same trap noted elsewhere
   for `py`/venv creation.
-- `_sync` — `PathSyncer` wrapper reproducing `install`'s backup/copy/report; requires
-  `pathlib_next.Path` instances (not plain `pathlib.Path`) and a pre-created parent dir.
 
 ## Environment variables
 
@@ -174,13 +182,25 @@ Tool-internal / secret vars (`DOTAGENTS_*` — kept; read, **never printed**):
 - `DOTAGENTS_AUDIT_PATTERNS` — path to the machine-local audit-pattern file (tooling).
 
 Emitted by the identity/env layer (safe to branch on in env files):
-`AGENTS_HARNESS`, `AGENTS_VENDOR`, `AGENTS_MODEL`, `AGENTS_AGENT` / `AGENT`,
-`AGENTS_CODE_SESSION_ID`, `AGENTS_PROXY`, `AGENTS_WEBFETCH_PROXY_URL`, plus the two
+`AGENTS_HARNESS`, `AGENTS_VENDOR`, `AGENTS_MODEL`, `AGENT`, `AGENTS_PROXY`,
+`AGENTS_WEBFETCH_PROXY_URL`, plus the two
 scope roots — `AGENTS_HOME` (the user store, `agents_dir`/`~/.agents`) and
 `AGENTS_PROJECT_ROOT` (this project's root). Both are seeded only if unset, so a
-harness/env can pin them. `resolve_scope` READS `AGENTS_PROJECT_ROOT` (then the
+harness/env can pin them. Deliberately NOT emitted, despite looking like they
+would be: `AGENTS_AGENT` (a named persona — nothing derives one, so there is
+nothing to emit) and `AGENTS_CODE_SESSION_ID` (dropped with the precursor's
+blanket `CLAUDE_*`→`AGENTS_*` rewrite). Do not branch on either. `resolve_scope` READS `AGENTS_PROJECT_ROOT` (then the
 agent-native `CLAUDE_PROJECT_DIR`, then cwd) for the project scope's root.
 
+Every command READS both back, so the pin actually holds: `env` and `context`
+resolve their user store through `cli.resolve_user_store()` (`--agents-dir` →
+`$AGENTS_HOME` → legacy `$DOTAGENTS_AGENTS_DIR` → `~/.agents`) and their project
+root through `_scope.project_root_default()` — neither is taken from the cwd or a
+hardcoded home. This matters for hook-invoked runs: a `SessionStart` hook runs
+`dotagents context` / `dotagents env` from wherever the session started, and only
+the pinned root makes that cwd-independent. `-g/--global` on these two means
+*skip the project tier*, not *use a different store*.
+
 ## Gotchas
 
 - **Python 3.9 floor.** Files using bare `X | Y` unions in runtime-evaluated positions
@@ -191,8 +211,10 @@ agent-native `CLAUDE_PROJECT_DIR`, then cwd) for the project scope's root.
   `cli.main()` calls `_repoint_zipapp_sources()` first, extracting the built-in command
   modules to real temp files. Discovered `cmds` modules are extracted by
   `_package_data_dir` before import, so they need no repoint.
-- **Package data in a `.pyz`.** `_package_data_dir()` resolves `skeleton/` and the
-  bundled payload via `importlib.resources` (a zip-backed `Traversable` is extracted to
-  a temp dir once), never `Path(__file__).exists()` (always False in a zipapp).
+- **Package data in a `.pyz`.** `_package_data_dir(name)` resolves a package-data dir
+  by name — `_overlay` (the base overlay `init` writes) and `_overlays_src` (bundled
+  example overlays, when a build includes them) — via `importlib.resources` (a
+  zip-backed `Traversable` is extracted to a temp dir once), never
+  `Path(__file__).exists()` (always False in a zipapp).
 - **`pathlib_next` needs `typing_extensions` on Python < 3.10** (an upstream gap); a
   3.9 environment must `pip install typing_extensions`.

{dotagents_cli-0.3.2 → dotagents_cli-0.3.4}/src/dotagents/__init__.py

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

{dotagents_cli-0.3.2 → dotagents_cli-0.3.4}/src/dotagents/_agents.py

@@ -490,10 +490,18 @@ class AntigravityAgent(Agent):
     # PreToolUse hooks do.
     #
     # No `shell`/`commandWindows`-equivalent field is documented for Antigravity
-    # hook commands at all (checked directly, absent) -- the emitted command
-    # must therefore work via a bare interpreter invocation with no shell
-    # assumptions, `python "<path>"` exactly as Codex's does, no dual-platform
-    # variant possible/needed here since nothing platform-specific is offered.
+    # hook commands at all (checked directly, absent) -- the emitted command must
+    # therefore work via a bare interpreter invocation with no shell assumptions,
+    # and there is exactly ONE string to get right for every platform.
+    #
+    # It emits `python "<path>"`. That is NOT what Codex does, despite the
+    # similar shape: Codex emits `python3` and overrides it to `python` through
+    # its `commandWindows` field, precisely because `python3` is the POSIX name
+    # and `python3` on Windows hits the Store app-execution-alias stub. With no
+    # second field available here, one name has to cover both, and `python` is
+    # the one that works on Windows -- but a POSIX box that ships only `python3`
+    # (still common) gets a hook that cannot start. Known gap, no fix available
+    # inside the hook entry itself; see `.agents/plans/` for the follow-up.
     PRETOOLUSE_HOOK_SCRIPT = "preinvocation_antigravity_context.py"
 
     def wire_hooks(
@@ -964,13 +972,19 @@ def stamp_identity(
     Emits ``AGENTS_HARNESS`` (the harness_id, e.g. ``claude-code`` -- NOT the
     short name), ``AGENTS_VENDOR``, ``AGENT`` (= AGENTS_HARNESS, aligning with
     the emerging ecosystem marker used by Goose/Amp; agentsmd/agents.md#136),
-    and, when derivable, ``AGENTS_MODEL`` (from the adapter's vendor model var)
-    and ``AGENTS_AGENT`` (a named persona, from $AGENTS_AGENT if already set).
+    and, when derivable, ``AGENTS_MODEL`` (from the adapter's vendor model var).
 
     Never emits a var it cannot source (no empty ``AGENTS_MODEL=``). Does NOT
     clobber a value already set in ``environ`` -- an explicit user/harness value
     wins. The deliberate curated mapping replaces the precursor's blanket
     ``CLAUDE_*``->``AGENTS_*`` rewrite (no ``AGENTS_CODE_SESSION_ID`` junk).
+
+    ``AGENTS_AGENT`` (a named persona) is NOT emitted and never was: the line
+    that claimed to "surface an already-selected persona" read the value from
+    the same key its own not-already-set guard required to be absent, so it was
+    unreachable in both directions. A persona would have to be DERIVED from
+    something (e.g. a ``<store>/<agent>.md``), which was never ported -- until
+    it is, nothing may branch on this var.
     """
     active = resolve_active_agent(environ, explicit=explicit, root=root)
 
@@ -984,7 +998,5 @@ def stamp_identity(
     _set("AGENTS_VENDOR", active.vendor)
     _set("AGENT", active.harness_id or active.name)
     _set("AGENTS_MODEL", active.resolve_model(environ))
-    # A named persona (~/.agents/<agent>.md); only surface one already selected.
-    _set("AGENTS_AGENT", environ.get("AGENTS_AGENT"))
 
     return identity

{dotagents_cli-0.3.2 → dotagents_cli-0.3.4}/src/dotagents/_merge.py

@@ -18,8 +18,12 @@ END_MARKER = "<!-- dotagents:end -->"
 def _extract_block(
     text: str, begin_marker: str = BEGIN_MARKER, end_marker: str = END_MARKER
 ) -> str:
-    """Return the managed block's inner text (without the marker lines) from
-    a skeleton/template file that is itself fully marker-wrapped."""
+    """Return the managed block from a base-overlay/template file that is itself
+    fully marker-wrapped -- the inner text INCLUDING both marker lines.
+
+    The markers are part of the returned string on purpose: callers write this
+    straight into a target file, and the block has to stay detectable there (the
+    merge finds an existing block by marker presence alone)."""
     start = text.index(begin_marker)
     end = text.index(end_marker)
     return text[start : end + len(end_marker)]

{dotagents_cli-0.3.2 → dotagents_cli-0.3.4}/src/dotagents/_scope.py

@@ -1,7 +1,7 @@
 """Scope and overlay-source resolution for ``dotagents overlays``.
 
 Two orthogonal axes the ``overlays`` command needs, kept out of ``cli.py`` (which
-only wires args) to match ``_overlays.py`` / ``_skills.py`` / ``_sync.py``:
+only wires args) to match ``_overlays.py`` / ``_skills.py``:
 
 * **Scope** -- *where installed overlays live*. ``user`` is ``<agents_dir>/`` (the
   configurable store, default ``~/.agents``); ``project`` is ``<project>/.agents/``.

{dotagents_cli-0.3.2 → dotagents_cli-0.3.4}/src/dotagents/cli/__init__.py

@@ -51,6 +51,8 @@ from dotagents import __version__
 # Re-export shared helpers so `dotagents.cli.<name>` keeps resolving for both the
 # command modules and external importers (`dotagents._overlays`, `dotagents._scope`).
 from dotagents.cli._common import (  # noqa: F401
+    AGENTS_DIR_ENV,
+    AGENTS_DIR_ENV_LEGACY,
     BASE_PLAIN_FILES,
     BASE_ROOT,
     DotAgentsArgs,
@@ -60,6 +62,7 @@ from dotagents.cli._common import (  # noqa: F401
     _package_data_dir,
     _resolve_from,
     _run_overlay_setup,
+    resolve_user_store,
 )
 
 # Import each built-in command class to register it as a compiled subcommand.
@@ -128,13 +131,6 @@ CMDS_PATH_ENV = "AGENTS_CMDS_PATH"
 #: back-compat: DOTAGENTS_CMDS_PATH is deprecated, removable next release.
 CMDS_PATH_ENV_LEGACY = "DOTAGENTS_CMDS_PATH"
 
-#: The configurable user-scope store (D58). Discovery resolves the user scope's
-#: cmds dir through this, not a hardcoded ~/.agents, when set. This is the same
-#: var `dotagents env` emits (D79).
-AGENTS_DIR_ENV = "AGENTS_HOME"
-#: back-compat: DOTAGENTS_AGENTS_DIR is deprecated, removable next release.
-AGENTS_DIR_ENV_LEGACY = "DOTAGENTS_AGENTS_DIR"
-
 
 class Dotagents(LoggingArgs, Cli):
     """Umbrella CLI for installing and building the dotagents config."""
@@ -225,20 +221,16 @@ def _cmds_dirs() -> "list[Path]":
     (an overlay may SHIP a command; a user/project can still override it).
 
     The store location is configurable (D58/D79): the user scope resolves through
-    `$AGENTS_HOME` (default `~/.agents`); the project scope is `<cwd>/.agents`.
+    `resolve_user_store()` (`$AGENTS_HOME`, legacy `$DOTAGENTS_AGENTS_DIR`, default
+    `~/.agents`) -- the same resolver `env`/`context` use, so every user-store
+    reader agrees; the project scope is `<cwd>/.agents`.
     `include_missing=True` (precursor semantics): every level's cmds dir is offered
     and the caller's `_discover_dir` skips the ones that don't exist."""
     from dotagents import _resolve, _scope
 
-    agents_dir = (
-        os.environ.get(AGENTS_DIR_ENV)
-        or os.environ.get(AGENTS_DIR_ENV_LEGACY)
-        or None
-    )
-    user = _scope.resolve_scope(global_scope=True, agents_dir=agents_dir)
     resolved = _resolve.get_file_paths(
         {"default": "dotagents/cmds", "overlay": "cmds"},
-        agents_dir=user.agents_root,
+        agents_dir=resolve_user_store(),
         project_root=_scope.project_root_default(),
         global_scope=False,
         include_missing=True,

{dotagents_cli-0.3.2 → dotagents_cli-0.3.4}/src/dotagents/cli/_common.py

@@ -21,6 +21,38 @@ from duho import Cmd, LoggingArgs
 
 _extracted_dirs_cache: "dict[str, Path]" = {}
 
+#: The configurable user-scope store (D58). Every reader of the user store
+#: resolves it through this var (default `~/.agents`) rather than hardcoding the
+#: home path -- this is the same var `dotagents env` emits (D79). Defined HERE
+#: rather than in `cli/__init__` so command modules can use it without importing
+#: the umbrella (import cycle); `cli/__init__` re-exports both names.
+AGENTS_DIR_ENV = "AGENTS_HOME"
+#: back-compat: DOTAGENTS_AGENTS_DIR is deprecated, removable next release.
+AGENTS_DIR_ENV_LEGACY = "DOTAGENTS_AGENTS_DIR"
+
+
+def resolve_user_store(agents_dir: "Optional[Path]" = None) -> Path:
+    """The USER store root, in precedence order: an explicit ``agents_dir``
+    (``--agents-dir``) -> ``$AGENTS_HOME`` -> the legacy
+    ``$DOTAGENTS_AGENTS_DIR`` -> ``~/.agents`` (D58/D79/D80).
+
+    Distinct from :meth:`DotAgentsArgs.resolve_scope`, which answers "which scope
+    do I install INTO" and returns ``<project>/.agents`` for the project scope.
+    Commands that always walk from the user store and merely *include or skip*
+    project-level files -- ``env`` and ``context``, whose Contract-A walk takes
+    the user store as ``agents_dir`` and the project root separately -- want this
+    instead: the store never becomes the project dir, whatever ``-g`` says.
+
+    Never logs or prints the raw env value (Leakage rule); only the resolved path
+    is ever reported.
+    """
+    if agents_dir:
+        return Path(agents_dir).expanduser()
+    value = os.environ.get(AGENTS_DIR_ENV) or os.environ.get(AGENTS_DIR_ENV_LEGACY)
+    if value:
+        return Path(value).expanduser()
+    return Path.home() / ".agents"
+
 
 class DotAgentsArgs(LoggingArgs, Cmd):
     """Shared ``-g/--global`` + ``--agents-dir`` fields for any command whose scope

{dotagents_cli-0.3.2 → dotagents_cli-0.3.4}/src/dotagents/cli/build_pyz.py

@@ -6,7 +6,6 @@ import subprocess
 import sys
 import tempfile
 from pathlib import Path
-from typing import Optional
 
 from duho import Cmd, LoggingArgs
 
@@ -29,28 +28,34 @@ class BuildPyz(LoggingArgs, Cmd):
     "Shebang line to embed in the pyz."
     ("--python",)
 
-    duho_version: str = "0.4.0"
+    # These two are a SECOND copy of the dependency versions declared in
+    # `pyproject.toml`'s `[project] dependencies`, and the two must move
+    # together: the zipapp bundles what the package claims to support, so a
+    # stale pin here ships an artifact `pip install dotagents-cli` would refuse.
+    # Pin the FLOOR of each declared range, not the latest patch -- the .pyz then
+    # exercises the minimum the metadata promises.
+    duho_version: str = "0.5.0"
     "Pinned duho version to vendor."
     ("--duho-version",)
 
-    pathlib_next_version: str = "0.8.0"
+    pathlib_next_version: str = "0.9.0"
     "Pinned pathlib_next version to vendor."
     ("--pathlib-next-version",)
 
-    tools_dir: Optional[Path] = None
-    "Repo tools/ dir (required tooling) to bundle as _tools (default: autodetected)."
-    ("--tools-dir",)
-
     def __call__(self) -> int:
         import zipapp
 
         # This module lives at src/dotagents/cli/build_pyz.py, so the repo root
         # is parents[3] (cli -> dotagents -> src -> repo) and the dotagents
         # package dir is parents[1].
+        #
+        # The repo's `tools/` is NOT bundled. It used to ride along as
+        # `dotagents/_tools` for compiled `audit`/`leak-check` wrappers that
+        # shelled out to it; both wrappers are gone (audit is repo CI tooling,
+        # leak-check is a personal command module), nothing reads `_tools`, and
+        # `tools/audit.py`'s own docstring says it is not shipped in the .pyz --
+        # which is only true now that this stopped copying it.
         repo_root = Path(__file__).resolve().parents[3]
-        tools_src = Path(self.tools_dir) if self.tools_dir else (repo_root / "tools")
-        if not tools_src.exists():
-            raise SystemExit("error: repo tools/ not found at %s (pass --tools-dir)" % tools_src)
 
         with tempfile.TemporaryDirectory(prefix="dotagents-pyz-") as tmp:
             stage = Path(tmp) / "stage"
@@ -109,13 +114,6 @@ class BuildPyz(LoggingArgs, Cmd):
                 )
                 self._logger_.info("stamped __version__ = %s (from pyproject.toml)", version)
 
-            tools_dest = dotagents_pkg_dest / "_tools"
-            shutil.copytree(
-                tools_src,
-                tools_dest,
-                ignore=shutil.ignore_patterns("__pycache__", "*.pyc"),
-            )
-
             for path in stage.rglob("*.dist-info"):
                 shutil.rmtree(path, ignore_errors=True)
             for path in stage.rglob("__pycache__"):

{dotagents_cli-0.3.2 → dotagents_cli-0.3.4}/src/dotagents/cli/context.py

@@ -4,7 +4,7 @@ import sys
 from pathlib import Path
 from typing import Optional
 
-from duho import Cmd, LoggingArgs
+from dotagents.cli._common import DotAgentsArgs, resolve_user_store
 
 
 def _write_stdout(text: str) -> None:
@@ -27,8 +27,21 @@ def _write_stdout(text: str) -> None:
     buffer.flush()
 
 
-class Context(LoggingArgs, Cmd):
-    """Assemble the effective context for agents (Plan 04)."""
+class Context(DotAgentsArgs):
+    """Assemble the effective context for agents (Plan 04).
+
+    Roots (both configurable, never hardcoded -- D58/D79/D80): the user store is
+    ``--agents-dir`` -> ``$AGENTS_HOME`` -> legacy ``$DOTAGENTS_AGENTS_DIR`` ->
+    ``~/.agents`` (:func:`~dotagents.cli._common.resolve_user_store`), and the
+    project root is ``$AGENTS_PROJECT_ROOT`` -> ``$CLAUDE_PROJECT_DIR`` -> the cwd
+    (:func:`~dotagents._scope.project_root_default`). This matters most here: the
+    SessionStart hook runs ``dotagents context`` from wherever the session happens
+    to start, so a pinned project root is the only thing that keeps the assembled
+    context stable across subdirectories.
+
+    ``-g/--global`` means **skip the project-level context files**, NOT "resolve a
+    different store" -- same narrowed meaning as ``dotagents env``'s (and unlike
+    ``DotAgentsArgs.resolve_scope``, which is deliberately not used here)."""
 
     _parsername_ = "context"
 
@@ -36,10 +49,17 @@ class Context(LoggingArgs, Cmd):
     "Output format: markdown, system-reminder, or json."
     ("--format",)
 
+    # Inherited from `DotAgentsArgs`; help restated because this command's `-g` is
+    # narrower than the base's and its store is always the user store (see the
+    # matching comment in `cli/env.py`).
     global_scope: bool = False
-    "Use global scope."
+    "Skip project-level context files (the store root is unaffected)."
     ("--global", "-g")
 
+    agents_dir: "Optional[Path]" = None
+    "User store root override (default: $AGENTS_HOME, else ~/.agents)."
+    ("--agents-dir",)
+
     agents: "list[str]" = []
     "List of agents to generate context for (e.g. claude,gemini). Default: active agent."
     ("--agents",)
@@ -56,11 +76,12 @@ class Context(LoggingArgs, Cmd):
     def __call__(self) -> int:
         from dotagents import _agents
         from dotagents import _context
+        from dotagents import _scope
         import json
         import os
 
-        project_root = Path.cwd()
-        agents_dir = Path.home() / ".agents"
+        project_root = _scope.project_root_default()
+        agents_dir = resolve_user_store(self.agents_dir)
 
         agent_names = []
         if self.agents: