dotagents-cli 0.7.5__tar.gz → 0.8.0__tar.gz

{dotagents_cli-0.7.5 → dotagents_cli-0.8.0}/CHANGELOG.md

@@ -7,6 +7,92 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-16
+
+### Added
+
+- `overlays add` takes globs: `overlays add '*' -g` installs every overlay the repos
+  offer, which for a store with a registry (`<store>/dotagents.toml`) is everything
+  it names. A glob matching nothing is an error.
+- `tools/cloud-setup.sh` installs every overlay the store's registry names
+  (`overlays add '*'`) before falling back to installing `private-sync` alone.
+
+- Each store has a Python venv, `<store>/.pyvenv/<X.Y.Z>-<os>-<arch>/`, made from
+  the Python that runs dotagents, where skills run. `init` and `overlays add` /
+  `sync` / `remove` keep it current: the user venv always has duho, and every
+  overlay's `requirements.txt` is installed (in one pip run, only when a file
+  changed, before the overlay's `setup.py`). A project gets its own venv when one of
+  its overlays ships requirements or a `lib/`. `--no-venv` skips it for a run;
+  `AGENTS_NO_PYVENV=1` turns it off. `.pyvenv/` holds the agents' venvs only: a
+  venv there that no sync completed is never used, and a project's own code keeps
+  its venvs in the project tree.
+- The venvs layer project > user > system through a `.pth` file in each: the store's
+  own overlay libs, then each lower store's venv packages and libs, then dotagents
+  itself. A project venv imports the project's packages first, then the user's.
+- `env` points `AGENTS_PYTHON` at the active venv and names it in `AGENTS_PYVENV`;
+  overlay `setup.py` scripts run under it. `context` prints it ("Python for
+  skills"), and its JSON form carries it as `python`. The managed block tells
+  agents to run skill scripts with `$AGENTS_PYTHON`.
+- pip without ensurepip: a venv where the interpreter has no ensurepip is created
+  without pip, and pip runs from its wheel (25.3, the last for Python 3.9, checked
+  against a pinned sha256). The wheel is found in the store's cache, in a `.pyz`
+  built with the new `build-pyz --with-pip`, in `AGENTS_PIP_SOURCE` (a directory of
+  wheels, or any URI pathapi-uri reads) or pip's `find-links`, or on your index
+  (`PIP_INDEX_URL`, or the mirror in `pip.ini` / `pip.conf`). `AGENTS_PIP_SOURCE`
+  is also passed to pip as `--find-links` for the requirements.
+
+### Changed
+
+- `overlays add` no longer stops at the first overlay that fails. Each failure is
+  logged, the overlays that require the failed one are skipped, every other overlay
+  is installed, and the command exits 1 naming each failure. A failed overlay this
+  run was installing for the first time is removed again, as before; the ones that
+  installed stay.
+- With a scope venv, `env` no longer puts the overlay libs it layers on
+  `PYTHONPATH`: the venv's interpreter imports them, and no other Python in the
+  session should. Without a venv, `PYTHONPATH` carries them as before.
+  `AGENTS_PYTHONPATH` still lists every lib.
+- The base block's "Startup: annotate that you read `…`" line names a store under
+  the home directory from there (`~/.agents/AGENTS.md`), and any other store by its
+  absolute path as before. A store kept in git and used on machines whose home
+  directories differ no longer shows `AGENTS.md` modified on all but one of them.
+
+### Fixed
+
+- `env --cache` on Windows with Python before 3.13 could miss a cache it had just
+  written: `time.time()` there lags the file's own timestamp by up to one clock
+  tick, and a cache file dated after "now" was treated as stale. A cache file
+  dated up to 2 s in the future now counts as fresh.
+
+## [0.7.6] - 2026-10-15
+
+### Added
+
+- A `repo` extra (`repopath[uri]`) for overlay sources at `github:`, `gitlab:` and
+  `repo:` URIs, which the `uri` extra no longer brings.
+
+### Changed
+
+- dotagents depends on `pathapi` (`>=0.1.0,<0.2`), the new name of `pathlib_next`,
+  instead of `pathlib_next`. The `.pyz` vendors it; `build-pyz --pathapi-version`
+  names its pin, and `--pathlib-next-version` still works. On Python 3.9 nothing
+  else has to be installed for it.
+- The extras install pathapi's own distributions: `uri` and `http` install
+  `pathapi-uri` (the URI layer, imported as `uripath`, with `file:`, `http(s):`,
+  `dav:`, `ftp:`, `zip:` and `tar:` on the standard library); `sftp` adds
+  `sftppath[paramiko]` and `s3` adds `objpath[s3]`. Overlay sources are read as
+  before. A `git:` URI is not a scheme any more; a repository tree is a `repo:` URI.
+- `build-pyz --extras` vendors what the named extras install, each distribution at
+  its floor, and refuses an extra it does not know.
+- `about` lists `pathapi`, `pathapi-uri`, `netimps` and the plugin distributions in
+  place of `pathlib_next`, `uritools` and `requests`.
+
+### Removed
+
+- The `.pyz` no longer extracts the built-in command modules' sources to temporary
+  files at startup: duho reads a command's flags and help through the zip importer
+  when the module has no file on disk.
+
 ## [0.7.5] - 2026-10-14
 
 ### Changed
@@ -1441,7 +1527,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.7.5...HEAD
+[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/jose-pr/dotagents/compare/v0.7.6...v0.8.0
+[0.7.6]: https://github.com/jose-pr/dotagents/compare/v0.7.5...v0.7.6
 [0.7.5]: https://github.com/jose-pr/dotagents/compare/v0.7.4...v0.7.5
 [0.7.4]: https://github.com/jose-pr/dotagents/compare/v0.7.3...v0.7.4
 [0.7.3]: https://github.com/jose-pr/dotagents/compare/v0.7.2...v0.7.3

{dotagents_cli-0.7.5 → dotagents_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.7.5
+Version: 0.8.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
@@ -24,12 +24,12 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Requires-Dist: duho<0.8,>=0.7.5
-Requires-Dist: pathlib-next<0.10,>=0.9.0
+Requires-Dist: pathapi<0.2,>=0.1.0
 Requires-Dist: tomli>=1.1.0; python_version < '3.11'
 Provides-Extra: dev
 Requires-Dist: build; extra == 'dev'
 Requires-Dist: hatchling>=1.27; extra == 'dev'
-Requires-Dist: pathlib-next[http]; extra == 'dev'
+Requires-Dist: pathapi-uri<0.2,>=0.1.0; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pyyaml; extra == 'dev'
 Provides-Extra: docs
@@ -37,13 +37,18 @@ Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
 Requires-Dist: mkdocs>=1.5; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
 Provides-Extra: http
-Requires-Dist: pathlib-next[http]; extra == 'http'
+Requires-Dist: pathapi-uri<0.2,>=0.1.0; extra == 'http'
+Provides-Extra: repo
+Requires-Dist: pathapi-uri<0.2,>=0.1.0; extra == 'repo'
+Requires-Dist: repopath[uri]<0.2,>=0.1.0; extra == 'repo'
 Provides-Extra: s3
-Requires-Dist: pathlib-next[s3]; extra == 's3'
+Requires-Dist: objpath[s3]<0.2,>=0.1.0; extra == 's3'
+Requires-Dist: pathapi-uri<0.2,>=0.1.0; extra == 's3'
 Provides-Extra: sftp
-Requires-Dist: pathlib-next[sftp]; extra == 'sftp'
+Requires-Dist: pathapi-uri<0.2,>=0.1.0; extra == 'sftp'
+Requires-Dist: sftppath[paramiko]<0.2,>=0.1.0; extra == 'sftp'
 Provides-Extra: uri
-Requires-Dist: pathlib-next[uri]; extra == 'uri'
+Requires-Dist: pathapi-uri<0.2,>=0.1.0; extra == 'uri'
 Provides-Extra: yaml
 Requires-Dist: pyyaml; extra == 'yaml'
 Description-Content-Type: text/markdown
@@ -156,7 +161,8 @@ dotagents init --force                  # replace AGENTS.md's content wholesale
 
 `--from <source>` selects another *base*: a base overlay directory, a dotagents
 checkout (its `src/dotagents/_overlay`), a `file:`, `http(s):`, `zip:`, `sftp:` or `s3:`
-URI (`pip install "dotagents-cli[uri]"` for all but `file:`), or a git repository
+URI (`pip install "dotagents-cli[uri]"` for all but `file:`, plus `[sftp]` or `[s3]`
+for those schemes), or a git repository
 (`repo[@ref][#path]`). A remote one is fetched into `<user store>/.cache/overlays/`.
 The bundled base ships inside the package, so `--from` is only for a base of your own.
 `init` records it (without any credentials in the URL), and later `init` and
@@ -209,6 +215,11 @@ store's shared `skills/` so every agent sees the same skills.
   `.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.
+- Each store has a Python venv, `<store>/.pyvenv/<version>-<os>-<arch>/`, where skills
+  run (`$AGENTS_PYTHON`): duho, every overlay's `requirements.txt` and every overlay
+  `lib/` import there, layered project > user > system. pip comes from the
+  interpreter, else its pinned wheel (cache, `AGENTS_PIP_SOURCE`, your index mirror,
+  or a `.pyz` built `--with-pip`).
 - `sync` refreshes each overlay from the repo it was installed from (`--repo` replaces
   that source), installs a `requires` added upstream, and re-merges the managed block.
 - `remove` deletes the overlay's directory, unpublishes only the skills **it**
@@ -239,7 +250,7 @@ authors:
 
 ### Downloadable `dotagents.pyz`
 
-A self-contained zipapp with `duho`, `pathlib_next` and `tomli` bundled in (pure
+A self-contained zipapp with `duho`, `pathapi` and `tomli` bundled in (pure
 Python, so one file runs on any OS and on Python 3.9+), so it needs no
 `pip install`. Each release attaches one:
 <https://github.com/jose-pr/dotagents/releases/latest/download/dotagents.pyz>.

{dotagents_cli-0.7.5 → dotagents_cli-0.8.0}/README.md

@@ -106,7 +106,8 @@ dotagents init --force                  # replace AGENTS.md's content wholesale
 
 `--from <source>` selects another *base*: a base overlay directory, a dotagents
 checkout (its `src/dotagents/_overlay`), a `file:`, `http(s):`, `zip:`, `sftp:` or `s3:`
-URI (`pip install "dotagents-cli[uri]"` for all but `file:`), or a git repository
+URI (`pip install "dotagents-cli[uri]"` for all but `file:`, plus `[sftp]` or `[s3]`
+for those schemes), or a git repository
 (`repo[@ref][#path]`). A remote one is fetched into `<user store>/.cache/overlays/`.
 The bundled base ships inside the package, so `--from` is only for a base of your own.
 `init` records it (without any credentials in the URL), and later `init` and
@@ -159,6 +160,11 @@ store's shared `skills/` so every agent sees the same skills.
   `.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.
+- Each store has a Python venv, `<store>/.pyvenv/<version>-<os>-<arch>/`, where skills
+  run (`$AGENTS_PYTHON`): duho, every overlay's `requirements.txt` and every overlay
+  `lib/` import there, layered project > user > system. pip comes from the
+  interpreter, else its pinned wheel (cache, `AGENTS_PIP_SOURCE`, your index mirror,
+  or a `.pyz` built `--with-pip`).
 - `sync` refreshes each overlay from the repo it was installed from (`--repo` replaces
   that source), installs a `requires` added upstream, and re-merges the managed block.
 - `remove` deletes the overlay's directory, unpublishes only the skills **it**
@@ -189,7 +195,7 @@ authors:
 
 ### Downloadable `dotagents.pyz`
 
-A self-contained zipapp with `duho`, `pathlib_next` and `tomli` bundled in (pure
+A self-contained zipapp with `duho`, `pathapi` and `tomli` bundled in (pure
 Python, so one file runs on any OS and on Python 3.9+), so it needs no
 `pip install`. Each release attaches one:
 <https://github.com/jose-pr/dotagents/releases/latest/download/dotagents.pyz>.

{dotagents_cli-0.7.5 → dotagents_cli-0.8.0}/docs/guide/commands.md

@@ -100,10 +100,15 @@ dotagents init                          # base config into ./.agents (project sc
 dotagents init -g                       # ...into ~/.agents (user scope)
 dotagents init --bin-dir ~/.local/bin   # also write a `dotagents` command on PATH
 dotagents init --no-hooks               # skip agent hook wiring + the skills links
+dotagents init --no-venv                # skip the store's Python venv (duho for skills)
 dotagents init --agents claude,codex    # exactly these agents (default: detected + claude)
 dotagents init --dry-run
 ```
 
+`init` also creates or updates the store's Python venv, where skills run (see
+[the scope venv](overlays.md#python-dependencies-and-the-scope-venv)). Offline, or
+with no pip to be had, that is a warning; `overlays sync` retries.
+
 ### Hook wiring
 
 For each active agent, `init` adds what that harness needs to load the config, and
@@ -198,6 +203,7 @@ Manages opt-in overlays **by name**. See [Overlays](overlays.md) for the full mo
 
 ```bash
 dotagents overlays add python engineering  # install into the scope, publish skills, merge rules/routing
+dotagents overlays add '*' -g              # everything the repos offer (a store registry: all it names)
 dotagents overlays list                    # installed (discovered) + available from the repos
 dotagents overlays sync 'py*'              # refresh installed overlays matching a glob
 dotagents overlays sync --prune            # also clear what .gitignore/.ignore protect: exactly upstream
@@ -205,7 +211,14 @@ dotagents overlays remove python           # delete the overlay dir, unpublish i
 dotagents overlays show python             # describe one: manifest, requires, setup, skills, source (--json)
 ```
 
-- **`add`** installs what each manifest's `requires` names first, each requirement
+- **`add`** takes names or globs: `'*'` is every overlay the repos offer, so with
+  a store registry it installs everything the registry names, and `'py*'` the ones
+  starting with `py`; a glob that matches nothing is an error. One overlay failing
+  (its copy, requirements or setup) does not stop the rest: it is logged, what
+  requires it is skipped, everything else installs, and the command exits 1 naming
+  each failure. A failed overlay this run was installing for the first time is
+  removed again; one that was already installed is left in place, not set up.
+  `add` installs what each manifest's `requires` names first, each requirement
   installed and set up before the overlay that needs it (`--no-requires` to skip); a
   requirement the scope already has, in its own store or the user store for a project,
   is satisfied and left alone, while a name you ask for explicitly is always
@@ -213,8 +226,11 @@ dotagents overlays show python             # describe one: manifest, requires, s
   before touching anything — the first repo that offers a name wins — records where
   each overlay came from, and publishes skills from the installed copy, never
   replacing a skill already in the shared `skills/` dir (and links them into
-  Claude's skills dir when `init` wired Claude for the store). A fresh install whose setup
-  script fails is rolled back. A source inside the store's own `overlays/` directory
+  Claude's skills dir when `init` wired Claude for the store). Each overlay's
+  `requirements.txt` is installed into the scope venv before its setup script runs
+  (`--no-venv` skips it; see
+  [the scope venv](overlays.md#python-dependencies-and-the-scope-venv)). A fresh install
+  whose requirements or setup script fail is rolled back. A source inside the store's own `overlays/` directory
   is refused (by `sync` too): `remove` would delete the only copy.
 - `add`, `remove` and `show` without an overlay name are usage errors (exit 2), and
   a `--dry-run` says what it would write (`would recompose ...`) instead of reporting
@@ -359,7 +375,7 @@ form and drop names that are not shell identifiers.
    `<NAME_OVERLAY_ROOT>` placeholder, so an env file and a context file refer to an
    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
+   pathapi) 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.
@@ -572,39 +588,46 @@ See [Private sync](private-sync.md) for the full walkthrough.
 ## about
 
 ```bash
-dotagents about          # dotagents-cli <version>, then duho, pathlib_next, ...
+dotagents about          # dotagents-cli <version>, then duho, pathapi, ...
 dotagents about --json   # the same, plus where it runs from and the Python
 ```
 
 One `<distribution> <version>` per line, the CLI first. From a built `.pyz` the
 list is exactly what `build-pyz` vendored (it records the names and versions in
 `dotagents/_bundle.json` before stripping the `dist-info` dirs the zipapp would
-otherwise carry, so `--extras uri,http` shows up here as `uritools`, `requests`
-and friends). From a plain install it is whichever of a fixed set is installed:
-`duho`, `pathlib_next`, `uritools`, `netimps` and `requests`. A package outside that
-set, such as a client the `sftp` or `s3` extra pulls in, is not listed.
+otherwise carry, so `--extras uri` shows up here as `pathapi-uri` and `netimps`).
+From a plain install it is whichever of a fixed set is installed: `duho`, `pathapi`,
+`pathapi-uri`, `netimps`, `sftppath`, `objpath` and `repopath`. A package outside
+that set, such as a client the `sftp` or `s3` extra pulls in (`paramiko`, `boto3`),
+is not listed.
 
 ## build-pyz
 
 ```bash
 python -m dotagents build-pyz --out dist/dotagents.pyz
-python -m dotagents build-pyz --extras uri,http     # also vendor pathlib_next's extras
+python -m dotagents build-pyz --extras uri,repo     # also vendor what those extras install
+python -m dotagents build-pyz --with-pip            # also carry pip, for machines without it
 ```
 
-Builds a self-contained zipapp from a source checkout, with `duho` and `pathlib_next`
-vendored (plus the `pathlib_next` extras named by `--extras`), so it runs with no
+Builds a self-contained zipapp from a source checkout, with `duho` and `pathapi`
+vendored (plus what the dotagents-cli extras named by `--extras` install), so it runs with no
 `pip install`. The repo's `tools/` never ships in it. Flags:
 
 - `--out <path>` — where to write it (default `dist/dotagents.pyz`).
 - `--python <shebang>` — the interpreter line embedded in it (default
   `/usr/bin/env python3`).
-- `--duho-version`, `--pathlib-next-version` — the versions vendored (defaults: the
-  floors the package declares).
-- `--extras <a,b>` — `pathlib_next` extras to vendor too (`uri`, `http`, `s3`),
+- `--duho-version`, `--pathapi-version` — the versions vendored (defaults: the
+  floors the package declares). `--pathlib-next-version` is the old name of the
+  second.
+- `--extras <a,b>` — dotagents-cli extras to vendor too (`uri`, `http`, `s3`, `repo`),
+  each distribution they install at its floor,
   so the `.pyz` can read those overlay sources; none by default. Everything is
   vendored as pure-Python wheels resolved for Python 3.9, so the file does not
   depend on the machine that built it; `sftp` needs native modules and fails the
   build with a message saying so. The archive is compressed.
+- `--with-pip` — also vendor the pinned pip wheel (about 1.8 MB), so the `.pyz` can
+  set up the scope venv where Python has no ensurepip and no index is reachable
+  (see [the scope venv](overlays.md#python-dependencies-and-the-scope-venv)).
 
 Each release attaches a built one:
 <https://github.com/jose-pr/dotagents/releases/latest/download/dotagents.pyz>.

{dotagents_cli-0.7.5 → dotagents_cli-0.8.0}/docs/guide/install.md

@@ -5,7 +5,9 @@ pip install dotagents-cli              # the `dotagents` command and `import dot
 pip install "dotagents-cli[uri]"       # + remote overlay sources beyond git and http(s) registries
 ```
 
-The `http`, `sftp` and `s3` extras add those schemes' own clients to `uri`. With no
+`uri` installs `pathapi-uri`: `file:`, `http(s):`, `dav:`, `ftp:`, `zip:` and `tar:` on
+the standard library. `sftp`, `s3` and `repo` add `sftp:`, `s3:` and `github:` /
+`gitlab:` / `repo:` to it; `http` installs the same as `uri`. With no
 `pip` at all, use the [downloadable `dotagents.pyz`](#downloadable-dotagentspyz).
 
 `dotagents init` then lays down the neutral **base config**. Opinionated content is
@@ -49,7 +51,8 @@ dotagents init --force                  # replace AGENTS.md's content wholesale
 
 `--from <source>` selects another *base*: a base overlay directory, a dotagents
 checkout (its `src/dotagents/_overlay`), a `file:`, `http(s):`, `zip:`, `sftp:` or `s3:`
-URI (`pip install "dotagents-cli[uri]"` for all but `file:`), or a git repository
+URI (`pip install "dotagents-cli[uri]"` for all but `file:`, plus `[sftp]` or `[s3]`
+for those schemes), or a git repository
 (`repo[@ref][#path]`). A remote one is fetched into `<user store>/.cache/overlays/`.
 The bundled base ships inside the package, so `--from` is only for a base of your own.
 `init` records it in
@@ -58,7 +61,7 @@ The bundled base ships inside the package, so `--from` is only for a base of you
 
 ## Downloadable `dotagents.pyz`
 
-A self-contained zipapp with `duho`, `pathlib_next` and `tomli` bundled in as
+A self-contained zipapp with `duho`, `pathapi` and `tomli` bundled in as
 pure-Python wheels (plus whatever `build-pyz --extras` added), so it needs no
 `pip install` and runs on any OS with Python 3.9+. Each release attaches one:
 <https://github.com/jose-pr/dotagents/releases/latest/download/dotagents.pyz>.

{dotagents_cli-0.7.5 → dotagents_cli-0.8.0}/docs/guide/overlays.md

@@ -124,9 +124,10 @@ in what the path names:
   `…/dotagents.git@repo#overlays/net` is the `net` overlay itself. Given as `--repo`,
   that form would list `net`'s own subdirectories as overlays.
 
-A `scheme://` location that is not git is a **pathlib_next path**. With the `uri`
-extra (`pip install 'dotagents-cli[uri]'`; `[http]`, `[sftp]`, `[s3]` add the schemes'
-own clients) any scheme pathlib_next speaks works like a local path: an `http(s)://`
+A `scheme://` location that is not git is a **uripath path** (pathapi's URI layer, the
+`pathapi-uri` distribution). With the `uri` extra (`pip install 'dotagents-cli[uri]'`;
+`[sftp]`, `[s3]` and `[repo]` add `sftp:`, `s3:` and `github:` / `gitlab:` / `repo:`)
+any scheme uripath speaks works like a local path: an `http(s)://`
 directory listing, an `sftp`, `s3`, `dav` or `github` tree is a directory of overlays
 as a repo or one overlay as a source, a file is a registry; an archive is a tree too —
 `zip:<archive-uri>!/<inner path>` (`tar:`, or `archive:` to auto-detect), the archive
@@ -135,7 +136,7 @@ materialized into `<user store>/.cache/overlays/uri/`, synced once per run, and
 from there; `file://` is a local path, no copy. Without the extra, an `http(s)://`
 location can still be a registry file (fetched with the standard library), and
 anything else says which extra it needs. The `.pyz` vendors none of this unless built
-with `build-pyz --extras uri,http`.
+with `build-pyz --extras uri`.
 
 A source written as a **relative path** (`./python`, `../shared/net`, `overlays/rust`)
 is relative to the registry it is in: the registry file's directory for a local file,
@@ -225,12 +226,49 @@ copies, where symlinks are unavailable) into the scope's shared skills dir, so e
 agent that reads that dir picks up the same skills. Removing the overlay unpublishes
 only the skills it published, then sweeps any now-broken symlinks.
 
+## Python dependencies and the scope venv
+
+Every store has a Python venv, `<store>/.pyvenv/<X.Y.Z>-<os>-<arch>/` (for example
+`~/.agents/.pyvenv/3.14.7-nt-arm64`), made from the Python that runs dotagents.
+A store's `.pyvenv/` holds these **agents' venvs only**: skills, overlay helpers and
+setup scripts run there. A project's own code gets its venvs beside the store, in
+the project root's `.pyvenv/` (`<project>/.pyvenv/<version>-<os>-<arch>/`, which the
+python overlay's `dotagents pyvenv` creates); only a venv dotagents itself synced is
+ever used as an agents' venv. `init` and every
+`overlays add` / `sync` / `remove` keep it current:
+
+- The user store's venv always has **duho**, so any skill can build a command line
+  on it, plus the packages each overlay installed there lists in a
+  **`requirements.txt`** at its root (pip's format). They are installed in one pip
+  run, so pip sees every constraint at once, and only when a file changed.
+- A project gets its own venv only when one of its overlays ships a
+  `requirements.txt` or a `lib/`; otherwise a project session uses the user venv.
+- The venvs **layer like everything else**. A `.pth` file in each venv lists, highest
+  precedence first: the store's own overlay libs, then the user venv's packages and
+  libs, then the system store's. dotagents itself comes last. So in a project venv,
+  the project's packages and libs win, then the user's, then the system's.
+- `dotagents env` points **`AGENTS_PYTHON`** at the active venv (and names it in
+  `AGENTS_PYVENV`). Overlay `setup.py` and `env.py` run under it, and the managed
+  block tells agents to run skill scripts with it. Libs the venv layers stay off
+  `PYTHONPATH`, so no other Python in the session, such as a project's own venv,
+  imports them by accident.
+
+**No ensurepip, no network?** pip runs from its wheel, pinned by version (25.3, the
+last for Python 3.9) and hash, found in this order: the store's cache, a copy
+vendored into the `.pyz` (`build-pyz --with-pip`), `AGENTS_PIP_SOURCE` (a directory
+of wheels, or any URI pathapi-uri reads: `file:`, `s3:`, `sftp:`, ...), pip's own
+`find-links`, then your index (`PIP_INDEX_URL` or the mirror in `pip.ini` /
+`pip.conf`). `AGENTS_PIP_SOURCE` is also handed to pip as `--find-links` for the
+requirements themselves.
+
+Opt out per run with `--no-venv`, or for good with `AGENTS_NO_PYVENV=1`.
+
 ## Setup scripts
 
 An overlay may ship an **idempotent** `setup.py` at its root — the recommended,
-OS-agnostic form: it runs under the same Python that runs dotagents, so it works on
-every platform. After `add` / `sync` copies the overlay
-in, dotagents runs the script automatically. Reserve it for real install-time work:
+OS-agnostic form: it runs under `AGENTS_PYTHON` (the scope venv above, with the
+overlay's requirements installed first), so it works on every platform. After
+`add` / `sync` copies the overlay in, dotagents runs the script automatically. Reserve it for real install-time work:
 `PATH`, `PYTHONPATH` and `$<NAME>_OVERLAY_ROOT` are `dotagents env`'s job
 (above), and an overlay's own env vars belong in its `env.py`, not in a script that
 writes one into the store — none of the example overlays ship a setup script any more.
@@ -241,8 +279,9 @@ Presence of a script is the opt-in; skip it with `--no-setup`. The author contra
 - **Environment** carries `AGENTS_HOME` (the user store), `AGENTS_SCOPE_ROOT` (the
   store the overlay is installed into), `AGENTS_SCOPE` (`user` or `project`) and
   `AGENTS_OVERLAY_DIR` (the overlay's own installed dir) — never hardcode a home path.
-- **Environment** is also the scope's assembled `dotagents env`: every overlay's `lib/`
-  on `PYTHONPATH`, its `bin/` on `PATH`.
+- **Environment** is also the scope's assembled `dotagents env`: every overlay's `bin/`
+  on `PATH`, and every overlay's `lib/` importable (through the venv's layering, or
+  `PYTHONPATH` without a venv).
 - **Time limit**: 300 seconds, or the manifest's `setup_timeout`, or the command's
   `--setup-timeout` (which wins); `0` means no limit. A script still running then is
   stopped, and that counts as a failure (exit 124).

{dotagents_cli-0.7.5 → dotagents_cli-0.8.0}/docs/guide/private-sync.md

@@ -19,6 +19,16 @@ never lands in the public repo). `<name>` defaults to the project's basename, so
 local checkout and a cloud checkout of the same project resolve to the same store
 entry.
 
+The store's installed overlays can travel two ways:
+
+- **Tracked copies**: `overlays/` is committed. Every machine and cloud session has
+  them with the clone, offline; every `overlays sync` is a diff in the private repo.
+- **A registry**: `<store>/dotagents.toml` names one source per overlay and
+  `overlays/` is left out of the repo. `dotagents overlays add '*' -g` installs
+  everything it names, keeping going past one that fails; the bootstrap below runs
+  it in a cloud session. The repo stays small; each new machine fetches the
+  overlays once.
+
 ## Commands
 
 The overlay goes into the user store, since the store is what it syncs:
@@ -82,7 +92,8 @@ curl -fsSL https://raw.githubusercontent.com/<you>/dotagents/main/tools/cloud-se
     success. `&&` propagates the curl failure instead.
 
 The bootstrap authenticates (bypassing a hosted-runner `github.com` → proxy git
-rewrite), clones/pulls the store, installs the CLI, links the project, and wires the
+rewrite), clones/pulls the store, installs the CLI, installs every overlay the store's
+registry names (`overlays add '*'`, when it has one), links the project, and wires the
 hooks into `~/.claude/settings.json` — driven by `AGENTS_REMOTE` /
 `DOTAGENTS_AGENTS_TOKEN` / `DOTAGENTS_CLI_INSTALL` environment variables (the token is
 never committed). `AGENTS_OVERLAYS_REMOTE` / `AGENTS_OVERLAYS_REF` choose where it

{dotagents_cli-0.7.5 → dotagents_cli-0.8.0}/install.py

@@ -5,7 +5,7 @@ Thin front over ``dotagents.cli.main()``, kept at this filename so existing
 muscle-memory/docs pointing at ``python install.py`` still work.
 
 Self-bootstrapping, inside a virtual environment: the CLI needs the
-``dotagents`` package and its ``duho``/``pathlib_next`` dependencies
+``dotagents`` package and its ``duho``/``pathapi`` dependencies
 importable. If they aren't -- e.g. a fresh venv with nothing installed yet --
 this shim installs this checkout **into the interpreter that is running it**
 (``sys.executable -m pip install -e .``) and retries, exactly once. When
@@ -49,7 +49,7 @@ def _import_main():
     """Return ``dotagents.cli.main`` if importable, else None.
 
     The ``src/`` fallback lets an un-pip-installed checkout resolve its
-    ``src/`` layout directly, provided ``duho``/``pathlib_next`` are importable
+    ``src/`` layout directly, provided ``duho``/``pathapi`` are importable
     some other way. A plain editable install makes all three importable without
     the fallback.
     """

{dotagents_cli-0.7.5 → dotagents_cli-0.8.0}/pyproject.toml

@@ -36,19 +36,26 @@ classifiers = [
 # raise a floor and move its pin there in the same change.
 dependencies = [
     "duho>=0.7.5,<0.8",
-    "pathlib_next>=0.9.0,<0.10",
+    "pathapi>=0.1.0,<0.2",
     # overlay.toml manifests and TOML registries; tomllib is stdlib from 3.11.
     'tomli>=1.1.0; python_version < "3.11"',
 ]
 
+# Overlay sources at a URI. `pathapi-uri` (import name `uripath`) gives the
+# file:, http(s):, dav:, ftp:, zip: and tar: schemes on the standard library;
+# the other distributions add their schemes to it. `build-pyz --extras` vendors
+# the floor of each (EXTRA_REQUIREMENTS in src/dotagents/cli/build_pyz.py).
 [project.optional-dependencies]
-uri = ["pathlib_next[uri]"]
-http = ["pathlib_next[http]"]
-sftp = ["pathlib_next[sftp]"]
-s3 = ["pathlib_next[s3]"]
+uri = ["pathapi-uri>=0.1.0,<0.2"]
+# http(s) is part of `uri` now; kept so `dotagents-cli[http]` still installs.
+http = ["pathapi-uri>=0.1.0,<0.2"]
+sftp = ["pathapi-uri>=0.1.0,<0.2", "sftppath[paramiko]>=0.1.0,<0.2"]
+s3 = ["pathapi-uri>=0.1.0,<0.2", "objpath[s3]>=0.1.0,<0.2"]
+# github:, gitlab: and repo: (a repository's tree at a ref).
+repo = ["pathapi-uri>=0.1.0,<0.2", "repopath[uri]>=0.1.0,<0.2"]
 # YAML overlay-repo registries (dotagents.yaml / *.yml).
 yaml = ["pyyaml"]
-dev = ["build", "hatchling>=1.27", "pytest", "pyyaml", "pathlib_next[http]"]
+dev = ["build", "hatchling>=1.27", "pytest", "pyyaml", "pathapi-uri>=0.1.0,<0.2"]
 docs = [
     "mkdocs>=1.5",
     "mkdocs-material>=9.5",