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

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

@@ -7,6 +7,63 @@ 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
@@ -1470,7 +1527,8 @@ 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.6...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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.7.6
+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
@@ -215,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**

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

@@ -160,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**

{dotagents_cli-0.7.6 → 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
@@ -590,6 +606,7 @@ is not listed.
 ```bash
 python -m dotagents build-pyz --out dist/dotagents.pyz
 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 `pathapi`
@@ -608,6 +625,9 @@ vendored (plus what the dotagents-cli extras named by `--extras` install), so it
   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.6 → dotagents_cli-0.8.0}/docs/guide/overlays.md

@@ -226,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.
@@ -242,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.6 → 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.6 → dotagents_cli-0.8.0}/src/dotagents/AGENTS.md

@@ -30,10 +30,10 @@ and an error saying a command is required, and exits 2.
 
 | Command | Contract |
 | --- | --- |
-| `init [-g] [--dest D] [--from SRC] [--bin-dir D] [--agents a,b] [--no-hooks] [--powershell-env-hook] [--force] [--dry-run]` | Merge the base block into `<store>/AGENTS.md`, write `<store>/bin/dotagents[.cmd]`, and per active agent (`--agents`, else detected + `claude`) write its include and hooks. `--force` replaces `AGENTS.md`'s content, backed up under `<store>/install_backup/<timestamp>/`. `--from` records its base in `<store>/dotagents/config.toml`. |
-| `overlays add NAME... [-g] [--repo SPEC]... [--copy] [--no-setup] [--setup-timeout S] [--no-requires] [--prune] [--dry-run]` | Install each overlay and its `requires` into `<store>/overlays/<name>/` (an installed one is made to match its source again, as `sync` does; `--prune` clears its ignored files too), publish its skills, run its `setup.py`, recompose the managed block. Every name is resolved before anything is written; a source inside `<store>/overlays/` is refused; a fresh install whose setup fails is rolled back. No name: exit 2. |
-| `overlays remove NAME... [-g] [--force] [--dry-run]` | Delete the overlay dirs, unpublish the skills they published, recompose the block. Refuses an overlay another installed overlay requires unless `--force`. No name: exit 2. |
-| `overlays sync [GLOB] [-g] [--repo SPEC]... [--copy] [--prune] [--no-setup] [--setup-timeout S] [--dry-run]` | Refresh installed overlays from the repo recorded at install (`--repo` replaces it): the install is made to match the source exactly: new and changed files land, `overlay.toml` is refreshed, files the source does not ship are removed; a file edited here is backed up first under `<store>/install_backup/<timestamp>/overlays/<name>/`. What the `.gitignore` / `.ignore` at the overlay's root match (setup output, local state) and tool caches are left alone; `--prune` clears them too. Installs new `requires`. Exits 1 when an overlay's repo cannot be loaded, its source lies inside `<store>/overlays/`, or its setup fails. |
+| `init [-g] [--dest D] [--from SRC] [--bin-dir D] [--agents a,b] [--no-hooks] [--powershell-env-hook] [--no-venv] [--force] [--dry-run]` | Merge the base block into `<store>/AGENTS.md`, write `<store>/bin/dotagents[.cmd]`, and per active agent (`--agents`, else detected + `claude`) write its include and hooks. Then bring the scope's Python venvs up to date (`_pyvenv.sync_venvs`; a failure is a warning; not with `--dest` or `--no-venv`). `--force` replaces `AGENTS.md`'s content, backed up under `<store>/install_backup/<timestamp>/`. `--from` records its base in `<store>/dotagents/config.toml`. |
+| `overlays add NAME\|GLOB... [-g] [--repo SPEC]... [--copy] [--no-setup] [--setup-timeout S] [--no-requires] [--no-venv] [--prune] [--dry-run]` | Install each overlay and its `requires` into `<store>/overlays/<name>/` (an installed one is made to match its source again, as `sync` does; `--prune` clears its ignored files too), publish its skills, install every overlay's `requirements.txt` into the scope venv (`_pyvenv`; not with `--no-venv`), run its `setup.py`, recompose the managed block. A glob (`'*'`, `'py*'`) stands for every name the repos offer that matches it; one matching nothing is an error. Every name is resolved before anything is written; a source inside `<store>/overlays/` is refused. An overlay whose copy, requirements or setup fail is logged and skipped, along with what requires it; the others still install, and the command exits 1 naming each failure. One this run was installing for the first time is removed again; one already installed stays. No name: exit 2. |
+| `overlays remove NAME... [-g] [--force] [--no-venv] [--dry-run]` | Delete the overlay dirs, unpublish the skills they published, recompose the block, rewrite the venv layering (installed requirements stay). Refuses an overlay another installed overlay requires unless `--force`. No name: exit 2. |
+| `overlays sync [GLOB] [-g] [--repo SPEC]... [--copy] [--prune] [--no-setup] [--setup-timeout S] [--no-venv] [--dry-run]` | Refresh installed overlays from the repo recorded at install (`--repo` replaces it): the install is made to match the source exactly: new and changed files land, `overlay.toml` is refreshed, files the source does not ship are removed; a file edited here is backed up first under `<store>/install_backup/<timestamp>/overlays/<name>/`. What the `.gitignore` / `.ignore` at the overlay's root match (setup output, local state) and tool caches are left alone; `--prune` clears them too. Installs new `requires`, then the venv requirements (when they changed) before each setup. Exits 1 when an overlay's repo cannot be loaded, its source lies inside `<store>/overlays/`, or its requirements or setup fail. |
 | `overlays list [-g] [--repo SPEC]... [--json]` | Installed overlays per store (shadowed copies marked, unmet `requires` flagged) and what the repos offer. |
 | `overlays show NAME [-g] [--repo SPEC]... [--json]` | One overlay: the copy a session would use, else the source's; manifest, setup, skills, file count, recorded source. No name: exit 2. |
 | `context [OUT] [-g] [--agents a,b] [--format markdown\|system-reminder\|json] [--write-agent] [--inline]` | Print (or write to `OUT`) the assembled context. `--write-agent` merges it into each agent's `context_target` under the project root (not with `-g`). Exits 2 when `--agents` names no known agent. |
@@ -42,7 +42,7 @@ and an error saying a command is required, and exits 2.
 | `launch [AGENT] [-g] [--command PROG] [--no-context] [--inline] [--write-agent] [--dry-run] [-- ARGS...]` | Run the agent's CLI with the env applied and the context handed over; the exit code is the harness's (`128+N` on signal N). |
 | `findings add\|list\|show\|done\|reopen\|remove\|index\|path [-g] [--dir D]` | The findings queue at `<store>/findings/` (`--dir` overrides): one markdown file per finding, `done` moves it to `processed/` with a required resolution, `INDEX.md` regenerated on every change. The frontmatter is valid YAML (a value is double-quoted when it must be); `index --requote` fixes values written bare in existing files, touching nothing else. |
 | `about [--json]` | `dotagents-cli <version>`, then `<distribution> <version>` per bundled (`.pyz`) or installed package. |
-| `build-pyz [--out P] [--python SHEBANG] [--duho-version V] [--pathapi-version V] [--extras a,b]` | Build a zipapp from a source checkout; errors elsewhere. |
+| `build-pyz [--out P] [--python SHEBANG] [--duho-version V] [--pathapi-version V] [--extras a,b] [--with-pip]` | Build a zipapp from a source checkout; errors elsewhere. `--with-pip` vendors the pinned pip wheel (`_pipwheel`) as `dotagents/_vendor/`. |
 
 **Every command but `env` is also an MCP tool.** With `DOTAGENTS_MCP=stdio` in its
 environment, `dotagents` serves the command set — built-in, bundled and discovered —
@@ -142,8 +142,11 @@ The package's own data; library code, importing nothing from `dotagents.cli`.
   `AGENTS_MD_PLACEHOLDER = "{{AGENTS_MD}}"`.
 - `base_agents_text(src, dest, *, project=False) -> str` — the base block for the
   store at `dest`: the project template for a project store when the base has one,
-  else the user template, else `<src>/AGENTS.md`; `{{AGENTS_MD}}` rendered as the
-  absolute POSIX path of `<dest>/AGENTS.md`.
+  else the user template, else `<src>/AGENTS.md`; `{{AGENTS_MD}}` rendered as
+  `home_relative(<dest>/AGENTS.md)`, so a store synced between machines whose home
+  directories differ renders the same block.
+- `home_relative(path) -> str` — `path` as POSIX text, `~/<rest>` when it is under
+  `Path.home()`, absolute otherwise.
 - `pyz_archive() -> str | None` — the `.pyz` this dotagents is imported from (the
   ancestor of the module's `__file__` that is a file), or `None` for a plain
   install. The archive also holds the vendored duho and pathapi; `env`
@@ -384,8 +387,12 @@ proxy model.
 
 - Roots: `AGENTS_HOME` and `AGENTS_PROJECT_ROOT` name the stores walked, absolute —
   an inherited value naming the same directory holds, another is replaced; in a
-  user-scope walk `AGENTS_PROJECT_ROOT` is set only when unset. Only when unset:
-  `AGENTS_PYTHON` (`sys.executable`) and one `<NAME>_OVERLAY_ROOT` per
+  user-scope walk `AGENTS_PROJECT_ROOT` is set only when unset. `AGENTS_PYTHON`:
+  the active scope venv's interpreter (`_pyvenv.active_venv`), else
+  `sys.executable`; it replaces an inherited value equal to `sys.executable` or
+  naming another `.pyvenv` interpreter, and any other pin holds. `AGENTS_PYVENV`:
+  that venv's dir, removed when there is none. Only when unset: one
+  `<NAME>_OVERLAY_ROOT` per
   `scope.overlays` (a value pinned to the user store's copy is re-pointed when a
   project copy shadows it). `AGENTS_PYLIB` (`_env.PYLIB_VAR`): the `.pyz` when
   dotagents runs from one (`_resources.pyz_archive()`), else not set — where its
@@ -395,10 +402,11 @@ proxy model.
 - `PATH`: every level's `bin` (contract A, not project-root, missing dirs included)
   at the front in that order, whatever the caller's `PATH` held; empty and
   cwd-relative inherited entries are dropped.
-- `PYTHONPATH`: every existing level's `lib` at the front, highest precedence
-  first; the entries an inherited `AGENTS_PYTHONPATH` named (another scope's libs)
-  are removed first. `AGENTS_PYTHONPATH`: the same list, `os.pathsep`-joined;
-  removed when there are none.
+- `PYTHONPATH`: every existing level's `lib` the active venv's `.pth` does not
+  already layer, at the front, highest precedence first (with a venv synced for the
+  scope, none); the entries an inherited `AGENTS_PYTHONPATH` named (another scope's
+  libs) are removed first. `AGENTS_PYTHONPATH`: every existing `lib`,
+  `os.pathsep`-joined, layered or not; removed when there are none.
 - Env files: all `pre.env.py` / `pre.env` (+ the project store's `pre.local.env`),
   then all `env.py` / `env` (+ `local.env`), contract-A order, regular files only,
   each evaluated against everything before it. The project root contributes none.
@@ -444,7 +452,8 @@ API:
 - `ENV_CACHE_TTL = 300.0` (seconds). `env_cache_key(scope, base_env, *parts) -> str`
   — a digest of what an assembly reads without running it: roots, cwd, interpreter,
   package version, installed overlays, each env-file candidate's
-  existence/mtime/size, every file under an existing `lib`, the whole `base_env`,
+  existence/mtime/size, every file under an existing `lib`, each store's venv state
+  file, the whole `base_env`,
   and `parts` (format, mode). `read_env_cache(scope, key, *, now=None) ->
   Optional[str]` (None when absent or older than the TTL); `write_env_cache(scope,
   key, text) -> None` (owner-only, under `<user store>/.cache/env/`; never raises).
@@ -462,7 +471,9 @@ API:
   and `AGENTS.local.md` (project store and project root), each prefixed
   `<!-- Source: <path> -->`. Then a skills listing (`- **name** (`<SKILL.md>`):
   description`, from each skill's leading frontmatter; a project skill wins), then
-  a "Local additions to overlay files" section when `local_additions` finds any.
+  a "Local additions to overlay files" section when `local_additions` finds any,
+  then, with `expand_vars`, the line ``Python for skills (`$AGENTS_PYTHON`): `<path>` ``
+  (`skills_python`).
   `<PROJECT_ROOT>` and `<NAME_OVERLAY_ROOT>` placeholders expand; with
   `expand_vars` so do `$NAME_OVERLAY_ROOT` / `${NAME_OVERLAY_ROOT}`. `inline`
   appends the on-demand `.md` files the sources reference, each resolved against
@@ -470,8 +481,10 @@ API:
   system source never into the project).
 - `assemble_context_data(agent, scope, *, inline=False, expand_vars=True) -> dict`
   — `{"agent", "harness", "sources", "context", "skills": [{"name",
-  "description", "path"}], "local_additions": [{"overlay_file", "local": [...]}]}`;
-  `context` without the skills and local-additions listings.
+  "description", "path"}], "local_additions": [{"overlay_file", "local": [...]}],
+  "python"}`; `context` without the skills and local-additions listings.
+- `skills_python(scope) -> str` — the active scope venv's interpreter, else
+  `sys.executable`.
 - `local_additions(scope) -> list[tuple[Path, list[Path]]]` — the user's own
   additions to installed overlay files: for each `.md` an overlay in `scope.overlays`
   ships in a subdirectory other than `skills/`, every store's file at the same
@@ -675,6 +688,62 @@ objects `{"matcher"?: str, "hooks": [{"type": "command", "command": str, ...}]}`
 - `check_path_warning(bin_dir) -> Optional[str]` — a warning with the PATH line to
   add, or `None` when `bin_dir` is on `PATH`.
 
+## `dotagents._pyvenv`
+
+One venv per store, `<store>/.pyvenv/<X.Y.Z>-<os>-<arch>/`, made from the running
+interpreter; layered project > user > system through a `.pth`. `.pyvenv/` holds the
+agents' venvs only (skills, overlay helpers, setup scripts), never a project's own
+code. `AGENTS_NO_PYVENV=1` (or `true`/`yes`/`on`) turns it all off.
+
+- `BASE_REQUIREMENTS = ("duho>=0.7.5,<0.8",)` — always in the user venv; dotagents'
+  own duho range. `REQUIREMENTS_FILE = "requirements.txt"` (at an overlay's root),
+  `PYVENV_DIR = ".pyvenv"`, `STATE_FILE = ".dotagents-venv.json"` (in the venv:
+  `{"digest", "requirements", "pth"}`), `PTH_FILE = "dotagents-layers.pth"` (in its
+  site-packages), `DISABLE_ENV = "AGENTS_NO_PYVENV"`.
+- `sync_venvs(scope, *, dry_run=False, logger=None) -> list[Path]` — the user venv
+  (base requirements + the user store's overlays' `requirements.txt`), then the
+  project's when `wants_venv` (its own overlays' requirements only). pip runs only
+  when the requirements' digest changed, in one `pip install -r ... -r ...` per
+  venv, with `--find-links` from `AGENTS_PIP_SOURCE`. The `.pth` is rewritten when
+  it differs: the store's own libs, then each lower store's venv site-packages and
+  libs, then `runtime_entry()`. Raises `VenvError` (a `SystemExit`) on failure.
+- `wants_venv(scope, level, store, libs) -> bool` — always for `user`; for `project`
+  when it has overlay requirements or libs; never for `system` (a venv an
+  administrator made there is still layered).
+- `ensure_venv(target, python=None, *, with_pip=None, dry_run=False, logger=None)
+  -> Optional[Path]` — the venv's interpreter, created when missing; `with_pip=None`
+  tries ensurepip and falls back to `--without-pip`, `False` never uses it.
+- `pip_command(vpy, *, cache_dir, logger=None) -> list[str]` — the venv's own
+  `-m pip`, else `[sys.executable, <pip wheel>/pip, "--python", <vpy>]`.
+- `active_venv(scope, environ=None) -> Optional[Path]` — the highest store's venv
+  for the running interpreter that a sync completed (its `STATE_FILE` exists); a
+  venv made there any other way is never an agents venv.
+- `layers(scope) -> list[tuple[str, Path, list[Path]]]` — `(level, store, libs)`,
+  highest first. `requirement_files(scope, store) -> list[Path]`.
+  `runtime_entry() -> str` (the `.pyz`, else the dir holding `dotagents`).
+  `venv_dir(store)`, `venv_python(venv)`, `site_packages(venv)`, `triplet()`,
+  `os_bucket()`, `read_state(venv)`, `disabled(environ=None)`,
+  `is_pyvenv_python(path)`.
+
+## `dotagents._pipwheel`
+
+The pip wheel for a venv with no pip of its own.
+
+- `PIP_VERSION = "25.3"` (the last pip for Python 3.9), `PIP_WHEEL`, `PIP_SHA256` —
+  every source must match the hash. `PIP_SOURCE_ENV = "AGENTS_PIP_SOURCE"`.
+  `VENDORED = ("_vendor", PIP_WHEEL)` (inside the package),
+  `DEFAULT_INDEX = "https://pypi.org/simple"`.
+- `pip_wheel(cache_dir, *, logger=None, environ=None) -> Path` — from, in order: the
+  cache file, the vendored copy (`build-pyz --with-pip`), `AGENTS_PIP_SOURCE` and pip's
+  `find-links` (a dir, `file:`/`http(s):`, or a pathapi-uri URI), then the index
+  (`PIP_INDEX_URL`, else pip's config `index-url`, else PyPI; PEP 691 JSON, else PEP
+  503 HTML), honouring pip's `cert`, `trusted-host`, `proxy` and credentials in the
+  URL. Raises `PipUnavailable` (a `SystemExit`) naming every source, redacted.
+- `find_links(environ=None, *, cache_dir, logger=None) -> list[str]` —
+  `AGENTS_PIP_SOURCE` for pip's `--find-links`, a URI pip cannot read copied locally.
+- `pip_config(environ=None) -> dict[str, str]` — `index-url`, `find-links`, `cert`,
+  `trusted-host`, `proxy` from `PIP_*` over pip's config files.
+
 ## `dotagents._fs`
 
 - `write_text_lf(path, text, *, atomic=False) -> Path` — UTF-8, LF line endings on
@@ -705,8 +774,12 @@ Read:
 - `AGENTS_OVERLAYS_REPO`, `AGENTS_OVERLAYS_REPO_<KEY>` — overlay repos (after
   `--repo`). `AGENTS_CMDS_PATH` — extra command dirs.
 - `AGENTS_HARNESS` — the running harness (registry name or harness id), for
-  identity. `AGENTS_PYTHON` — the interpreter for `env.py`. `AGENTS_PYTHONPATH` —
-  the overlay/store `lib` dirs `env` put on `PYTHONPATH`, highest precedence first.
+  identity. `AGENTS_PYTHON` — the interpreter for `env.py` and `setup.py`.
+  `AGENTS_PYTHONPATH` — the overlay/store `lib` dirs, highest precedence first.
+  `AGENTS_NO_PYVENV` — turns the scope venvs off. `AGENTS_PIP_SOURCE` — a directory
+  of wheels (or a URI to one) for pip, before the index. `PIP_INDEX_URL`,
+  `PIP_CONFIG_FILE`, `PIP_FIND_LINKS`, `PIP_CERT`, `PIP_TRUSTED_HOST`, `PIP_PROXY` and
+  pip's config files — read to fetch the pip wheel.
   `AGENTS_PYLIB` — the `.pyz` dotagents runs from (duho and pathapi import
   from it), unset for an installed dotagents.
 - Harness config dirs: `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `PI_CODING_AGENT_DIR`.
@@ -722,7 +795,7 @@ Read:
 
 Emitted by `env` (and applied by `launch`): `AGENTS_HARNESS`, `AGENTS_VENDOR`,
 `AGENT`, `AGENTS_MODEL`, `AGENTS_HOME`, `AGENTS_PROJECT_ROOT`, `AGENTS_PYTHON`,
-`AGENTS_PYLIB` (from a `.pyz` only), `<NAME>_OVERLAY_ROOT`, `PATH`, `AGENTS_PYTHONPATH`, `AGENTS_PROXY` and the mirrored
+`AGENTS_PYVENV` (with a scope venv), `AGENTS_PYLIB` (from a `.pyz` only), `<NAME>_OVERLAY_ROOT`, `PATH`, `AGENTS_PYTHONPATH`, `AGENTS_PROXY` and the mirrored
 proxy vars, plus whatever the env files set. `AGENTS_AGENT` is never emitted.
 `launch` also exports `AGENTS_CONTEXT_FILE`.
 
@@ -739,6 +812,9 @@ Set for an overlay's `setup.py`: `AGENTS_HOME` (user store), `AGENTS_SCOPE_ROOT`
   scratch dir removed at exit); `duho` reads the command modules' flags and help
   through the zip importer.
 - **Writes are LF-only.** Use `_fs.write_text_lf`, never `Path.write_text`.
+- **Skills run under `AGENTS_PYTHON`**, the scope venv: duho, every overlay's
+  requirements and libs, and dotagents import there. Its site-packages is never put
+  on `PYTHONPATH`, which every other Python in the session would read first.
 - **`env` output is sensitive**: it prints resolved values. Nothing in the package
   logs a value, only names.
 - **Credentials in a repo URL** are removed from every log line, cache dir name and

{dotagents_cli-0.7.6 → dotagents_cli-0.8.0}/src/dotagents/__init__.py

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

{dotagents_cli-0.7.6 → dotagents_cli-0.8.0}/src/dotagents/_context.py

@@ -463,9 +463,23 @@ def assemble_context(
         return ""
     text += _get_skills_listing(scope)
     text += _get_local_additions_listing(scope)
+    if expand_vars:  # a machine path: never into a file that may be committed
+        text += "\n\nPython for skills (`$AGENTS_PYTHON`): `%s`\n" % skills_python(scope)
     return text
 
 
+def skills_python(scope: _scope.Scope) -> str:
+    """The interpreter skills run with: the scope venv's (`dotagents._pyvenv`),
+    which imports duho, every overlay's requirements and every overlay lib;
+    else the one running dotagents."""
+    import sys
+
+    from dotagents import _pyvenv
+
+    venv = _pyvenv.active_venv(scope)
+    return str(_pyvenv.venv_python(venv)) if venv is not None else sys.executable
+
+
 def assemble_context_data(
     agent: _agents.Agent, scope: _scope.Scope, *, inline: bool = False,
     expand_vars: bool = True,
@@ -480,6 +494,7 @@ def assemble_context_data(
           "context": <assembled markdown text, minus the skills listing>,
           "skills": [{"name": ..., "description": ..., "path": <SKILL.md>}, ...],
           "local_additions": [{"overlay_file": ..., "local": [<path>, ...]}, ...],
+          "python": <the interpreter skills run with, see skills_python>,
         }
     ``context`` is the same assembled(+inlined, with ``inline=True``) text the
     markdown format emits, but WITHOUT the skills and local-additions listings
@@ -501,4 +516,5 @@ def assemble_context_data(
             {"overlay_file": str(path), "local": [str(p) for p in found]}
             for path, found in local_additions(scope)
         ],
+        "python": skills_python(scope),
     }

{dotagents_cli-0.7.6 → dotagents_cli-0.8.0}/src/dotagents/_env.py

@@ -1054,7 +1054,24 @@ def get_environment(
     # a venv's, or absent, while this one demonstrably runs the CLI.
     # `sys.executable` is '' or None under an embedding host: then nothing is
     # exported rather than an empty command name.
-    _seed("AGENTS_PYTHON", sys.executable)
+    # With a scope venv (`_pyvenv`) it is that venv's interpreter instead: it
+    # sees every overlay lib and requirement through its .pth layering. It
+    # replaces an inherited value this code would have set (the bare
+    # interpreter, or another scope's venv); any other pin holds.
+    from dotagents import _pyvenv
+
+    venv = _pyvenv.active_venv(scope, osenv)
+    python = str(_pyvenv.venv_python(venv)) if venv is not None else sys.executable
+    pinned = osenv.get("AGENTS_PYTHON")
+    if python and pinned != python and (
+        not pinned or pinned == sys.executable or _pyvenv.is_pyvenv_python(pinned)
+    ):
+        _apply({"AGENTS_PYTHON": python})
+    if venv is not None:
+        if osenv.get("AGENTS_PYVENV") != str(venv):
+            _apply({"AGENTS_PYVENV": str(venv)})
+    elif "AGENTS_PYVENV" in osenv:
+        _apply(EnvChanges(removed=["AGENTS_PYVENV"]))
     # --- AGENTS_PYLIB --- where dotagents' own libraries (duho, pathapi)
     # import from for an overlay that builds on them. Set only when dotagents
     # runs from a .pyz: the archive, importable by zipimport. An installed
@@ -1117,8 +1134,15 @@ def get_environment(
         e for e in inherited.split(os.pathsep)
         if e and os.path.normcase(e) not in stale
     ]
+    # A lib the scope venv's .pth already layers stays off PYTHONPATH: the
+    # venv's interpreter (AGENTS_PYTHON) imports it anyway, and no other
+    # Python in the session should. AGENTS_PYTHONPATH still names them all.
+    layered = {
+        os.path.normcase(e) for e in (_pyvenv.read_state(venv).get("pth") or [] if venv else [])
+    }
+    on_path = [p for p in lib_paths if os.path.normcase(p) not in layered]
     pythonpath = _prepended_path_var({"PYTHONPATH": os.pathsep.join(kept)}, "PYTHONPATH",
-                                     list(reversed(lib_paths)))
+                                     list(reversed(on_path)))
     if pythonpath is None:
         pythonpath = os.pathsep.join(kept)
     if pythonpath != inherited:
@@ -1187,6 +1211,12 @@ def get_diff(
 #: store, the clock), so its output is re-derived at least this often.
 ENV_CACHE_TTL = 300.0
 
+#: How far in the future a cache file's mtime may be and still count as fresh.
+#: On Windows before Python 3.13 ``time.time()`` reads a clock that ticks every
+#: ~15.6 ms while NTFS stamps files from a precise one, so a file read back at
+#: once can be dated slightly after "now". Beyond this, the clock moved back.
+_ENV_CACHE_CLOCK_SLACK = 2.0
+
 #: Every env-file name the two tiers resolve (see :func:`resolve_env_files`).
 _ENV_FILE_NAMES = (
     {"default": "pre.env.py", "project-root": ""},
@@ -1244,6 +1274,13 @@ def env_cache_key(scope: Scope, base_env: "dict[str, str]", *parts: str) -> str:
         items.append("lib %s %s" % (path, _stat_sig(path)))
         if path.is_dir():
             items += _tree_sig(path)
+    # A venv sync (`_pyvenv`) changes AGENTS_PYTHON and what stays off PYTHONPATH.
+    from dotagents import _pyvenv
+
+    items += [
+        "venv %s %s" % (store, _stat_sig(_pyvenv.venv_dir(store) / _pyvenv.STATE_FILE))
+        for store in scope.stores
+    ]
     items += sorted("%s=%s" % kv for kv in base_env.items())
     h = hashlib.sha256()
     for item in items:
@@ -1263,7 +1300,7 @@ def read_env_cache(scope: Scope, key: str, *, now: "Optional[float]" = None) ->
     path = _env_cache_dir(scope) / key
     try:
         age = (time.time() if now is None else now) - os.stat(str(path)).st_mtime
-        if age < 0 or age >= ENV_CACHE_TTL:
+        if age < -_ENV_CACHE_CLOCK_SLACK or age >= ENV_CACHE_TTL:
             return None
         with open(str(path), encoding="utf-8", newline="") as fh:
             return fh.read()

{dotagents_cli-0.7.6 → dotagents_cli-0.8.0}/src/dotagents/_overlay/dotagents/templates/AGENTS.md

@@ -30,6 +30,13 @@ Startup: annotate that you read `{{AGENTS_MD}}`.
   `kb/` file routed from "Load on demand"), or decide no change is needed — and
   closes it with `dotagents findings done -g <name> -r "<resolution>"` (moved,
   never deleted; the resolution is the record).
+- **Python for skills**: run every skill script, overlay `bin/` helper and anything
+  importing an overlay's `lib/` with `$AGENTS_PYTHON` (PowerShell
+  `& $env:AGENTS_PYTHON`), never a bare `python`, `python3` or `py`. It is the scope's
+  venv: duho, every overlay's requirements and every overlay `lib/` (project, then
+  user, then system) import there and nowhere else. When the variable is unset, use
+  the interpreter `dotagents context` prints. `.agents/.pyvenv/` holds only these
+  agents' venvs: never create, install into or test a project in one.
 - **This file**: everything between the `dotagents:begin`/`dotagents:end` markers is
   managed — `dotagents init` refreshes it and leaves anything outside untouched. Add
   your own rules and routing below the end marker, not inside.