dotagents-cli 0.5.0__tar.gz → 0.5.1__tar.gz

{dotagents_cli-0.5.0 → dotagents_cli-0.5.1}/.gitignore

@@ -36,6 +36,7 @@ Thumbs.db
 .vscode/
 _staging/
 
-# `overlays` branch, checked out here as a worktree/clone for local editing
-# (D77: example overlays split off this repo's main branch).
+# The `repo` branch (the example overlays, under overlays/<name>), checked out
+# here as a worktree/clone for local editing (D77: split off main).
+repo/
 overlays/

{dotagents_cli-0.5.0 → dotagents_cli-0.5.1}/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-09-12
+
+### Added
+
+- `dotagents about`: `dotagents-cli <version>` and then, one per line, every
+  package bundled with it and its version -- from a `.pyz` exactly what
+  `build-pyz` vendored (recorded in `dotagents/_bundle.json` at build time),
+  from a plain install the dependencies present. `--json` adds where it runs
+  from and the Python.
+- Overlay sources and repos can be any path `pathlib_next` speaks. With the
+  `uri` extra (`dotagents-cli[uri]`; `[http]`, `[sftp]`, `[s3]` add the schemes'
+  clients) an `http(s)://` directory listing, an `sftp`, `s3`, `dav` or
+  `github` tree is a directory of overlays or one overlay, a file is a
+  registry, an archive (`zip:<archive-uri>!/<inner>`, `tar:`, `archive:`, the
+  archive local or at a URL) is a tree too, and a relative registry entry resolves against the registry's
+  URL; remote content is materialized into `<user store>/.cache/overlays/uri/`
+  once per run. `file://` is a local path. Without the extra an `http(s)://`
+  registry file still works through the standard library, and anything else
+  names the extra it needs. `build-pyz --extras uri,http` vendors the extra
+  into the zipapp. `GitCache` is now `SourceCache`.
+
+### Changed
+
+- The base config's first line, "Startup: annotate that you read `…`", names
+  the actual path of the `AGENTS.md` it is in (`init` renders it per store, and
+  every `overlays add` / `remove` / `sync` recompose keeps it), not a literal
+  `~/.agents/AGENTS.md` that a relocated store or a project's own file never
+  was. The base overlay is `dotagents/` only: the block template is
+  `dotagents/templates/AGENTS.md`, `<store>/dotagents/AGENTS.md` is
+  the working notes for that directory (read when working in it, not by
+  default), `<store>/dotagents/README.md` the user-facing one, and `init` no
+  longer writes a `<store>/CLAUDE.md` or a store-root README (no harness read
+  the former; the include `init` writes into `~/.claude/CLAUDE.md` is the real
+  one). Existing stores keep the files they have.
+- The example overlays' branch is `repo` (was `overlays`); its layout is the
+  same, `overlays/<name>` at the branch root. Specs that named the branch
+  change one word: `https://github.com/jose-pr/dotagents.git@repo#overlays/net`.
+  The cloud bootstrap's `DOTAGENTS_OVERLAYS_REF` default follows.
+
 ## [0.5.0] - 2026-09-10
 
 ### Added

{dotagents_cli-0.5.0 → dotagents_cli-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.5.0
+Version: 0.5.1
 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
@@ -44,6 +44,7 @@ Requires-Python: >=3.9
 Requires-Dist: duho<0.6,>=0.5.0
 Requires-Dist: pathlib-next<0.10,>=0.9.0
 Provides-Extra: dev
+Requires-Dist: pathlib-next[http]; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
@@ -107,7 +108,7 @@ them. Everything else is repo infrastructure.
 
 The **example overlays** — the `flows` workflow set, per-language `kb/` + templates,
 `references`, `release`, `private-sync`, `net`, `recovery`, `tools` — live on a separate
-[`overlays` branch](https://github.com/jose-pr/dotagents/tree/overlays), not in `main`'s
+[`repo` branch](https://github.com/jose-pr/dotagents/tree/repo), not in `main`'s
 tree: they are swappable payloads, not part of the tool. `dotagents overlays add <name>`
 resolves them from there (or from any `--repo`). See the
 [docs](https://jose-pr.github.io/dotagents/) for what each ships.
@@ -163,7 +164,8 @@ overlay's skills into the shared skills dir. See below.
 `dotagents overlays` manages opt-in overlays **by name**, resolving each name against
 **repos** in order — the first that offers the name wins. A repo is always a
 **collection** of overlays: a directory (each subdirectory an overlay, e.g. a checkout of
-the [`overlays` branch](https://github.com/jose-pr/dotagents/tree/overlays)) or a
+the [`repo` branch](https://github.com/jose-pr/dotagents/tree/repo), whose overlays sit
+under `overlays/<name>`) or a
 JSON/TOML/YAML registry file mapping names to **sources**. It lives at a local path, an
 `http(s)://` URL (a registry file, fetched), or inside a git repository named
 `<repo>[@<branch|tag|commit>][#<path>]`, where the path picks the directory or registry

{dotagents_cli-0.5.0 → dotagents_cli-0.5.1}/README.md

@@ -46,7 +46,7 @@ them. Everything else is repo infrastructure.
 
 The **example overlays** — the `flows` workflow set, per-language `kb/` + templates,
 `references`, `release`, `private-sync`, `net`, `recovery`, `tools` — live on a separate
-[`overlays` branch](https://github.com/jose-pr/dotagents/tree/overlays), not in `main`'s
+[`repo` branch](https://github.com/jose-pr/dotagents/tree/repo), not in `main`'s
 tree: they are swappable payloads, not part of the tool. `dotagents overlays add <name>`
 resolves them from there (or from any `--repo`). See the
 [docs](https://jose-pr.github.io/dotagents/) for what each ships.
@@ -102,7 +102,8 @@ overlay's skills into the shared skills dir. See below.
 `dotagents overlays` manages opt-in overlays **by name**, resolving each name against
 **repos** in order — the first that offers the name wins. A repo is always a
 **collection** of overlays: a directory (each subdirectory an overlay, e.g. a checkout of
-the [`overlays` branch](https://github.com/jose-pr/dotagents/tree/overlays)) or a
+the [`repo` branch](https://github.com/jose-pr/dotagents/tree/repo), whose overlays sit
+under `overlays/<name>`) or a
 JSON/TOML/YAML registry file mapping names to **sources**. It lives at a local path, an
 `http(s)://` URL (a registry file, fetched), or inside a git repository named
 `<repo>[@<branch|tag|commit>][#<path>]`, where the path picks the directory or registry

{dotagents_cli-0.5.0 → dotagents_cli-0.5.1}/docs/guide/commands.md

@@ -11,13 +11,14 @@ by default (the `<cwd>/.agents` store, when run inside a project) or **user** wi
 
 | Command | What it does |
 | --- | --- |
-| `init` | Lay down the neutral base config; block-merge `AGENTS.md`/`CLAUDE.md`; `--bin-dir` also writes a PATH wrapper. |
+| `init` | Lay down the neutral base config; block-merge `AGENTS.md` (its first line names the file's own path); `--bin-dir` also writes a PATH wrapper. |
 | `overlays` | Manage opt-in overlays by name: `add` / `remove` / `list` / `sync` / `show`. |
 | `context` | Assemble the effective context for one or more agents. |
 | `env` | Assemble the chained env-file layers + identity vars, in a chosen format. |
 | `build-pyz` | Build the self-contained `dotagents.pyz` zipapp. |
 | `findings` | Per-scope findings queue: `add` / `list` / `show` / `done` / `reopen` / `remove` / `index` / `path`. |
 | `launch` | Start an agent's CLI with the `env` exported and the `context` handed over; everything after `--` goes to the agent. |
+| `about` | `dotagents-cli <version>`, then every package bundled in the `.pyz` (or installed beside a plain install) with its version. |
 
 That table is the **whole** shipped surface; `findings` and `launch` are the two bundled
 command modules (discovered from the package itself, overridable by a same-named module
@@ -355,6 +356,19 @@ project's `.agents` — and `sync-project` no longer reads like `overlays sync`.
 
 See [Private sync](private-sync.md) for the full walkthrough.
 
+## about
+
+```bash
+dotagents about          # dotagents-cli 0.5.0 / duho 0.5.0 / pathlib_next 0.9.0 ...
+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 the dependencies actually present.
+
 ## build-pyz
 
 ```bash

{dotagents_cli-0.5.0 → dotagents_cli-0.5.1}/docs/guide/overlays.md

@@ -19,7 +19,7 @@ an installed overlay — an already-present file is skipped.
 ## Example overlays
 
 The example overlays below live on this repo's separate
-[`overlays` branch](https://github.com/jose-pr/dotagents/tree/overlays), not in `main` —
+[`repo` branch](https://github.com/jose-pr/dotagents/tree/repo), not in `main` —
 they are **payloads riding on dotagents**, not part of the tool, so you swap them for
 your own. Name a checkout of that branch as a repo to install any with
 `dotagents overlays add <name> --repo <overlays-checkout>/overlays`.
@@ -67,7 +67,7 @@ first repo that offers the name wins. A repo is **always a collection** of overl
 in one of two shapes:
 
 - a **directory of overlays** — each subdirectory is an overlay, `<dir>/<name>/` (a
-  checkout of the `overlays` branch, any folder);
+  checkout of the `repo` branch has them under `overlays/`, any folder);
 - a **registry** — a JSON, TOML or YAML file mapping `<name-or-alias>` to the
   **source** of that one overlay (the whole document, or its `overlays` key).
 
@@ -78,17 +78,29 @@ force git); `<ref>` is a branch, tag or commit; `<path>` is inside it. The two d
 in what the path names:
 
 - for a **repo**, the collection: a directory (of overlays) or a registry file in the
-  checkout, the checkout root with no path; an `http(s)://` location is a registry
-  file, fetched;
+  checkout, the checkout root with no path;
 - for a **source**, the overlay: the path is the overlay's root directory, and with no
   path **the repository root is the overlay**.
 
+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)://`
+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
+itself local (`file:`) or at any URL: `zip:https://h/overlays.zip!/overlays`. Remote content is
+materialized into `<user store>/.cache/overlays/uri/`, synced once per run, and used
+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`.
+
 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,
 and for a registry inside a git checkout the **same repository at the same ref**, with
 the path joined onto the registry file's directory (`overlays/reg.toml` saying `./rust`
-means `<repo>@<ref>#overlays/rust`). A registry fetched over `http(s)` has no overlays
-beside it, so a relative entry there is an error.
+means `<repo>@<ref>#overlays/rust`), and for a registry at a URL the URL beside it
+(`https://h/cfg/reg.json` saying `./rust` means `https://h/cfg/rust`).
 
 Checkouts are cached under `<user store>/.cache/overlays/` and refreshed on every
 `add`/`sync`.
@@ -104,8 +116,8 @@ The repos, in order:
 ```toml
 # ~/.agents/dotagents.toml
 [overlays]
-engineering = "https://github.com/you/dotagents.git@overlays#overlays/engineering"
-python      = "https://github.com/you/dotagents.git@overlays#overlays/python"
+engineering = "https://github.com/you/dotagents.git@repo#overlays/engineering"
+python      = "https://github.com/you/dotagents.git@repo#overlays/python"
 mytool      = "git@github.com:you/mytool-overlay.git@v2"      # no path: the repo root is the overlay
 local       = "~/src/overlays/local"                           # a local overlay directory
 mine        = "./overlays/mine"                                # relative to this file: ~/.agents/overlays/mine
@@ -113,7 +125,7 @@ mine        = "./overlays/mine"                                # relative to thi
 
 ```bash
 dotagents overlays add engineering -g                                  # from the registry above
-dotagents overlays add net --repo https://github.com/you/dotagents.git@overlays#overlays/net
+dotagents overlays add net --repo https://github.com/you/dotagents.git@repo#overlays/net
 dotagents overlays sync -g                                             # refetches git-sourced overlays
 ```
 

{dotagents_cli-0.5.0 → dotagents_cli-0.5.1}/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.5.0"
+version = "0.5.1"
 authors = [{ name = "Jose A." }]
 description = "The dotagents CLI: install and manage a portable ~/.agents config for AI coding agents"
 readme = "README.md"
@@ -39,7 +39,7 @@ uri = ["pathlib_next[uri]"]
 http = ["pathlib_next[http]"]
 sftp = ["pathlib_next[sftp]"]
 s3 = ["pathlib_next[s3]"]
-dev = ["pytest"]
+dev = ["pytest", "pathlib_next[http]"]
 docs = [
     "mkdocs>=1.5",
     "mkdocs-material>=9.5",

{dotagents_cli-0.5.0 → dotagents_cli-0.5.1}/src/dotagents/AGENTS.md

@@ -27,7 +27,10 @@ can read it without the source. Full docs: https://jose-pr.github.io/dotagents/
   managed block over what remains — the un-merge), `list`, `sync` (`--copy`
   honoured, `--overwrite` replaces changed files), `show` (manifest, setup,
   skills, files, `--json`) — `context`, `env`, `build_pyz` (a checkout only:
-  a clear error elsewhere)); each is a `class X(LoggingArgs, Cmd)` — or
+  a clear error elsewhere), `about` (`dotagents-cli <version>` then one
+  `<distribution> <version>` per line: from a `.pyz` what `build-pyz` vendored,
+  recorded in `dotagents/_bundle.json` at build time since the zipapp carries
+  no dist-info; from a plain install the runtime packages present)); each is a `class X(LoggingArgs, Cmd)` — or
   `class X(DotAgentsArgs)`, which is that pair transitively — with a
   `__call__`. Plus TWO bundled command modules under
   `_overlay/dotagents/cmds/`: `findings.py` (`dotagents findings`: a per-scope
@@ -41,9 +44,9 @@ can read it without the source. Full docs: https://jose-pr.github.io/dotagents/
   means no append flag and the context is merged into `Agent.context_target`
   as `context --write-agent` does — then runs `Agent.launch_command` resolved
   on the exported PATH, or `--command`). `init` copies neither into the store —
-  the bundled dir is always a discovery source. `link` / `sync` left the package with their logic (D85): the
-  opt-in **private-sync** overlay ships them, renamed `link-project` /
-  `sync-project`, from its own `cmds/` + `lib/_link.py`. A personal command module
+  the bundled dir is always a discovery source. `link-project` / `sync-project`
+  are shipped by the opt-in **private-sync** overlay from its own `cmds/` +
+  `lib/_link.py` (D85), not by the package. A personal command module
   dropped into a scope's `dotagents/cmds/` is discovered like any other, so private
   tooling never has to live in the repo (D84). `audit` is repo CI tooling
   (`tools/audit.py`), not a command.
@@ -105,13 +108,12 @@ can read it without the source. Full docs: https://jose-pr.github.io/dotagents/
   default). `-g` resolves the store through `resolve_user_store`
   (`--agents-dir` → `$AGENTS_HOME` → `~/.agents`), never the literal
   home dir; `--agents-dir` overrides the store in EITHER scope. The library
-  functions take a `Scope` only — no keyword-triple compatibility form: the CLI
-  is the public surface, the package internals have one caller.
+  functions take a `Scope` only.
   Installed overlays are **discovered** by presence (`Overlay.discover(scope.overlay_root)`
   for one scope, `Overlay.installed(...)` for what a session uses), not tracked in
   a registry. Nothing overlay-only lives here (name rules and discovery are
   `Overlay`'s).
-- `_context` — assemble the effective per-agent context (Plan 04):
+- `_context` — assemble the effective per-agent context:
   `assemble_context(agent, scope, *, inline=False)` /
   `assemble_context_data(agent, scope, *, inline=False)`. Sources are the contract-A
   walk (overlay `CONTEXT.md`s first, sorted by manifest `priority`, lower
@@ -121,7 +123,7 @@ can read it without the source. Full docs: https://jose-pr.github.io/dotagents/
   and one `<NAME_OVERLAY_ROOT>` per installed overlay (user store + project)
   expand. **Inlining the on-demand `.md` files a source mentions is opt-in**
   (`inline=True` / `context --inline`): the base rules say to read them only
-  when a task needs them, and inlining every mention made a 100 KB session
+  when a task needs them, so inlining every mention would bloat the session
   payload. Skills are listed, never inlined.
 - `_env` — chained env-file assembly + `env.py` execution (frozen contract B):
   `get_environment(scope, *, base_env, explicit, logger)` / `get_diff(scope, ...)`
@@ -132,24 +134,24 @@ can read it without the source. Full docs: https://jose-pr.github.io/dotagents/
   `lib` onto PYTHONPATH the same way (`get_lib_paths`; not part of contract B), so
   an `env.py` and every subprocess can import an overlay's `lib/`; then two tiers
   (`pre.env*` then `env*`), later-overrides-earlier. Identity seeded before the
-  chain; proxy vars applied after. **Amended 2026-09-09:** the project-root level
+  chain; proxy vars applied after. The project-root level
   resolves only `pre.local.env` / `local.env` — a checkout's own top-level
-  `env.py` / `env` is never executed or sourced (it ran at every session start,
-  i.e. code execution from any cloned repo); only regular files count (a venv
+  `env.py` / `env` is never executed or sourced (that would be code execution
+  from any cloned repo at session start); only regular files count (a venv
   dir named `env` is not an env file); a plain file whose `source` fails
   contributes nothing (`source F || exit 1`, so the failure is visible); bash's
   own `PWD`/`OLDPWD`/`SHLVL`/`MSYSTEM*` are never reported as a file's changes.
 - **`Scope.paths(*names, include_missing=False)`** — the Contract-A precedence
-  walk / filename resolution (there is no `_resolve` module any more), store by
+  walk / filename resolution, store by
   store over `Scope.stores` — system (`Scope.system_root`, `/etc/agents` or
   `$AGENTS_SYSTEM_ROOT`), user, project — each store's overlays first, then the
   store itself; then project-root. The project store and project-root exist
   only in a project scope (`overlays add` installs into the project store by
-  default, since 2026-09-09 walked like any other). Each
+  default; it is walked like any other). Each
   tuple is `(level, path, root)`; an overlay entry's `level` is the overlay's
   dir name and `root` its dir (`root is None` for every other level — that is
   the overlay test). `LEVEL_NAMES` are reserved as overlay names.
-- `_merge` — managed-block merge for `init`'s `AGENTS.md` / `CLAUDE.md`, delimited by
+- `_merge` — managed-block merge for `init`'s `AGENTS.md`, delimited by
   `<!-- dotagents:begin -->` / `<!-- dotagents:end -->` marker LINES (a prose
   mention of a marker is not a marker; `find_block` returns the span). A begin
   with no end after it is refused; a base without markers is a usage error.
@@ -171,8 +173,14 @@ can read it without the source. Full docs: https://jose-pr.github.io/dotagents/
   `.github/copilot-instructions.md`, pi `.pi/APPEND_SYSTEM.md`, Antigravity
   `.agents/rules/dotagents.md`),
   `write_base_config(dest, ...)` (Claude also writes the `@` include into
-  `~/.claude/CLAUDE.md` or `<project>/.claude/CLAUDE.md` — THE last mile; the
-  store's own `CLAUDE.md` is kept for the skeleton but no harness reads it).
+  `~/.claude/CLAUDE.md` or `<project>/.claude/CLAUDE.md` — THE last mile; no
+  `<store>/CLAUDE.md` is written). The base overlay is
+  `_overlay/dotagents/` only: `templates/AGENTS.md` (the block
+  TEMPLATE, rendered by `cli._common.base_agents_text(src, dest)` —
+  `{{AGENTS_MD}}` becomes the actual path of the store's `AGENTS.md`, so
+  "annotate that you read `…`" names the real file; `init` and every recompose
+  use it), `AGENTS.md` (dev notes for that directory, read when working in it),
+  `README.md` (user-facing), `DECISIONS.md`, `cmds/`, `hooks/`.
   The user scope is whatever `resolve_user_store()` returns, never the literal
   `~/.agents`.
 - `_skills` — publish an overlay's `skills/<name>/` into a scope's shared skills dir
@@ -200,16 +208,15 @@ can read it without the source. Full docs: https://jose-pr.github.io/dotagents/
   PowerShell tool) and `CodexAgent.wire_hooks` (`<CODEX_HOME|~/.codex>/hooks.json`,
   never `config.toml`: `SessionStart` context-only, plus a `PreToolUse` env-loader
   matched on `matcher: "Bash"`). Codex's hook JSON is structurally identical to
-  Claude's, including the SAME `updatedInput.command` rewrite mechanism on
-  `PreToolUse` — confirmed directly against Codex's own docs
-  (learn.chatgpt.com/docs/hooks), not assumed from Claude parity.
-  Gemini/Cursor/Copilot keep the base no-op — Gemini CLI proper has no hook
-  mechanism documented at all (checked directly). **Antigravity is a separate
+  Claude's, including the same `updatedInput.command` rewrite mechanism on
+  `PreToolUse` (learn.chatgpt.com/docs/hooks).
+  Gemini/Cursor/Copilot keep the base no-op — Gemini CLI documents no hook
+  mechanism. **Antigravity is a separate
   product** from Gemini CLI (Antigravity CLI/IDE/SDK family, shares only the
   `~/.gemini/` namespace for some files) and DOES wire a hook: see
-  `AntigravityAgent.wire_hooks` below. `PreToolUse` there is still allow/deny/ask
+  `AntigravityAgent.wire_hooks` below. `PreToolUse` there is allow/deny/ask
   only — no `updatedInput`, so no command-rewrite/env-loader path exists to hang
-  on it, unlike Claude/Codex. Revisit both conclusions if either framework changes.
+  on it, unlike Claude/Codex. Revisit if either framework changes.
 - **`AntigravityAgent.wire_hooks`** (`<AGENTS_HOME_ANTIGRAVITY|~/.gemini/config>/hooks.json`,
   keyed under a `"dotagents"` name per the docs' own example shape — a named-entry
   object, not Claude/Codex's flat `hooks.<Event>`): wires a single `PreInvocation`
@@ -221,30 +228,28 @@ can read it without the source. Full docs: https://jose-pr.github.io/dotagents/
   `_overlay/dotagents/hooks/`) gates on `invocationNum == 0` to behave like a
   one-shot SessionStart rather than resending context every turn. Output shape is
   a bare `{"injectSteps": [{"ephemeralMessage": "..."}]}`, no `hookSpecificOutput`
-  wrapper — confirmed against the primary docs after an earlier pass here wrongly
-  concluded no useful injection was possible; `ephemeralMessage` is the one of the
+  wrapper; `ephemeralMessage` is the one of the
   three step types meant for free text (`toolCall` executes a tool,
-  `userMessage` impersonates the user). No detection marker exists anywhere in
-  Antigravity's docs, so `detect_env_vars = []` — explicit `--agents antigravity`
-  only, same posture as Codex's env-block precedent (writes touching an agent's
+  `userMessage` impersonates the user). Antigravity's docs define no detection
+  marker, so `detect_env_vars = []` — explicit `--agents antigravity`
+  only, as for Codex (writes touching an agent's
   own live config are opt-in, never inferred).
 - **`SessionStart`/`CwdChanged` register TWO handlers each ON WINDOWS**,
   bash-syntax (default shell) and a PowerShell-native equivalent (`shell:
   "powershell"`); **POSIX hosts get the bash handler only**, and `init` there
-  RETRACTS PowerShell entries an earlier install wrote (`_hooks.remove_hook`,
-  keyed by status message) — Claude Code on Linux ran such an entry through
-  bash, a syntax error every session (measured in WSL, 2026-09-10). The gate
+  REMOVES any PowerShell entries present (`_hooks.remove_hook`,
+  keyed by status message) — Claude Code on Linux runs such an entry through
+  bash, a syntax error every session. The gate
   is `ClaudeAgent._is_windows()` (`os.name == "nt"`, a seam tests patch; never
   "is pwsh installed"). hooks.md: `shell` "Defaults to bash, or to powershell
-  on Windows when Git Bash isn't installed" — verified directly that bash
-  syntax fed to `powershell -Command` on such a machine is a hard parse error,
+  on Windows when Git Bash isn't installed" — bash
+  syntax fed to `powershell -Command` is a hard parse error,
   not a soft failure, so every session there would silently get neither env
   nor context. Every handler in a matched group fires unconditionally
-  (hooks.md), so on Windows both always run —
-  and on a box with BOTH interpreters both used to succeed, injecting the same
-  context twice per session (two identical 100 KB payloads, measured
-  2026-09-09). The PowerShell variants therefore **select themselves: they run
-  only when `bash` is not on PATH** (`Get-Command bash`). The PowerShell
+  (hooks.md), so on Windows both always run; the PowerShell variants therefore
+  **select themselves: they run only when `bash` is not on PATH**
+  (`Get-Command bash`), otherwise a box with both interpreters would inject the
+  same context twice per session. The PowerShell
   `SessionStart` variant is context-only (`dotagents context`), not
   env+context: `$CLAUDE_ENV_FILE`'s documented effect is "subsequent BASH
   commands" regardless of which shell wrote it, so writing to it from a
@@ -252,28 +257,27 @@ can read it without the source. Full docs: https://jose-pr.github.io/dotagents/
   store as `$AGENTS_HOME`, else `~/.agents` (bash: `${AGENTS_HOME:-$HOME/.agents}`),
   and the bash `CwdChanged` handler re-pins `AGENTS_PROJECT_ROOT` into
   `$CLAUDE_ENV_FILE` when the new cwd carries a `.agents/` (the SessionStart pin
-  is only-if-unset, so without this a `cd` into another project kept the first
-  project's root for the rest of the session).
+  is only-if-unset, so without this a `cd` into another project would keep the
+  first project's root for the rest of the session).
 - **Windows only**: `ClaudeAgent._wire_powershell_pretooluse` additionally wires
   a no-matcher `PreToolUse` hook (fires on every tool call), `shell:
   "powershell"`, running `PRETOOLUSE_POWERSHELL_COMMAND` INLINE — deliberately
   not a `.ps1` file, since a script file is subject to PowerShell's execution
   policy (RemoteSigned/AllSigned/Restricted) and dotagents has no code-signing
-  certificate; verified directly that the inline form runs successfully even
-  under `Restricted`, which blocks every `.ps1` file outright. Closes a real
-  gap: `$CLAUDE_ENV_FILE` is Bash-tool-only (confirmed empirically that
-  `$env:CLAUDE_ENV_FILE` is empty inside a live PowerShell tool call), so the
+  certificate; the inline form runs even
+  under `Restricted`, which blocks every `.ps1` file outright. It is needed
+  because `$CLAUDE_ENV_FILE` is Bash-tool-only (`$env:CLAUDE_ENV_FILE` is
+  empty inside a PowerShell tool call), so the
   SessionStart env half never reaches the PowerShell tool. Uses `PreToolUse`'s
-  `updatedInput` to prepend a guarded env-loader (`AGENTS_RUNTIME_SET`,
-  matching the precursor's convention) to a `PowerShell` tool call's own
+  `updatedInput` to prepend a guarded env-loader (`AGENTS_RUNTIME_SET`)
+  to a `PowerShell` tool call's own
   command — not by trying to persist state across hook invocations, which are
   each their own fresh process and cannot. Each PowerShell TOOL call is a fresh
   process too, so the guard never carries over and the loader runs on every
   call: it therefore runs `env --diff` (the change set), not the whole
   environment through `Invoke-Expression`. Every literal `\` in the
   command constant must be a raw string — a bare `\b` in a normal Python string
-  literal silently becomes a backspace character, corrupting the emitted path;
-  caught once by testing a draft through a real PowerShell spawn.
+  literal silently becomes a backspace character, corrupting the emitted path.
 - **`CodexAgent._deploy_pretooluse_script`** covers the same env gap for Codex,
   which has NO env-persistence mechanism at any hook event (not Bash-only like
   Claude — none). Ships `pretooluse_codex_env.py` (`_overlay/dotagents/hooks/`),
@@ -283,10 +287,9 @@ can read it without the source. Full docs: https://jose-pr.github.io/dotagents/
   `tool_name` check needed in the script. A FILE, not inlined like Claude's:
   Codex's docs show every hook example as `python3 <path>`, and a `.py` file
   has no execution-policy/signing concern (PowerShell-specific). Sets
-  `commandWindows` to `python "<path>"` (not `python3`) — verified directly
-  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.
+  `commandWindows` to `python "<path>"` (not `python3`): on Windows `python3`
+  can resolve to the Microsoft Store app-execution-alias stub and fail
+  outright (exit 49).
 
 ## Environment variables
 
@@ -313,15 +316,21 @@ Config / path / sync vars (`AGENTS_*`, non-secret — read, and some emitted):
   before the default; both after `--repo` and before the stores'
   `dotagents.{json,toml,yaml}` registries and the bundled `overlays/`.
   `_sources` is the module; `resolve_source(repos, scope=)` the entry point.
+  A non-git `scheme://` location is a pathlib_next `UriPath` when the `uri`
+  extra is installed (`_sources.uri_path_class()`), materialized by
+  `SourceCache.materialize` into `<store>/.cache/overlays/uri/` (a directory
+  synced with `PathSyncer(remove_missing=True)`, a file copied, once per
+  process); `file://` is local; without the extra only an http(s) REGISTRY
+  works (stdlib fetch).
 - `AGENTS_CMDS_PATH` — extra command-module search paths (os.pathsep-split).
 - `AGENTS_OVERLAY_DIR` — set for an overlay's setup script (its own installed dir).
 - `AGENTS_REMOTE` / `AGENTS_SYNC_MESSAGE` — private-store sync (tokenless remote URL /
   commit message).
 
-The `DOTAGENTS_*` spellings of these are gone (0.5.0): readers take the `AGENTS_*`
-name only, and setters emit it only.
+Readers take the `AGENTS_*` name only, and setters emit it only; there is no
+`DOTAGENTS_*` spelling of any of these.
 
-Tool-internal / secret vars (`DOTAGENTS_*` — kept; read, **never printed**):
+Tool-internal / secret vars (`DOTAGENTS_*` — read, **never printed**):
 
 - `DOTAGENTS_AGENTS_TOKEN` — **secret** (fine-grained PAT) for private-store auth.
 - `DOTAGENTS_CLI_INSTALL` — pip spec to install the CLI itself (tool-specific).
@@ -352,8 +361,8 @@ with every level's existing `lib` prepended (both except project-root; the
 formatter treats any `*PATH` var as a path list for Windows/POSIX conversion).
 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
+nothing to emit) and `AGENTS_CODE_SESSION_ID`. 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`
@@ -381,7 +390,7 @@ the pinned root makes that cwd-independent. `-g/--global` on these two means
   zip-backed `Traversable` is extracted once), never `Path(__file__).exists()`
   (always False in a zipapp). Everything a `.pyz` run extracts — package data
   and the repointed module sources — lives under ONE per-process scratch dir
-  (`_common._scratch_dir()`), removed at interpreter exit; a `mkdtemp` per item
-  with no cleanup had littered a dev box's `%TEMP%` with 632 directories.
+  (`_common._scratch_dir()`), removed at interpreter exit, so a `.pyz` run
+  leaves nothing behind in `%TEMP%`.
 - **`pathlib_next` needs `typing_extensions` on Python < 3.10** (an upstream gap); a
   3.9 environment must `pip install typing_extensions`.

{dotagents_cli-0.5.0 → dotagents_cli-0.5.1}/src/dotagents/__init__.py

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