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

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

@@ -24,6 +24,7 @@ dist/
 *.pyz
 .venv/
 .venv-test/
+.pyvenv/
 
 # MkDocs build output
 site/
@@ -35,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.4.0 → dotagents_cli-0.5.1}/CHANGELOG.md

@@ -7,6 +7,128 @@ 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
+
+- Overlays can come from git repositories and registries. `overlays add` /
+  `sync` / `list` / `show` resolve a name against **repos** in order, the first
+  that offers it winning: `--repo <spec>` (repeatable), `$AGENTS_OVERLAYS_REPO_<KEY>`
+  (one repo per variable, by KEY), `$AGENTS_OVERLAYS_REPO` (the default repo),
+  the project store's `dotagents.{json,toml,yaml,yml}`, the user store's, then
+  the bundled `overlays/`. A repo is always a collection of overlays: a
+  directory (each subdirectory an overlay) or a registry file mapping names
+  (or aliases) to sources; it lives at a local path, an `http(s)://` URL (a
+  registry, fetched) or inside a git repository named
+  `<repo>[@<branch|tag|commit>][#<path>]`, the path picking the directory or
+  registry file in the checkout. A source is one overlay: a local directory,
+  or a git spec whose path is the overlay's root (no path: the repository root
+  is the overlay); a relative path is relative to the registry file, and for a
+  registry inside a git checkout it names the same repository at the same
+  ref. Checkouts are cached under `<user store>/.cache/overlays/`
+  and refreshed on every use; credentials in a repo URL never reach a log line.
+- `dotagents launch [<agent>] [-- <the agent's arguments>]`, a bundled command
+  module like `findings`: starts an agent's CLI (`claude`, `codex`, `gemini`,
+  `cursor-agent`, `copilot`, `pi`, or `--command <program>`) with the full `env`
+  assembly exported to the process and the child, and the assembled `context`
+  written to a file (exported as `AGENTS_CONTEXT_FILE`) and handed over as
+  appended system-prompt text where the harness takes one (Claude Code:
+  `--append-system-prompt-file`), or merged into the harness's own instruction
+  file as the managed `dotagents:context` block otherwise. The program is
+  resolved on the exported PATH, so a harness an overlay's `bin/` provides is
+  found; `--dry-run` prints the command line and the exported names;
+  `--no-context` and `--inline` shape the context step; the exit code is the
+  harness's. Adapters gained `launch_command` and `launch_context_args()`.
+- The `pi` agent (pi.dev, `@earendil-works/pi-coding-agent`): detected by its
+  documented `PI_CODING_AGENT` marker, model from `PI_MODEL`, no vendor (it is
+  multi-provider). Its config dir (`$PI_CODING_AGENT_DIR`, else `~/.pi/agent`)
+  and the project's `AGENTS.md` / `CLAUDE.md` count as loaded by the harness;
+  `context --write-agent` and `launch` hand the context over through
+  `.pi/APPEND_SYSTEM.md`, the file pi appends to its system prompt, and
+  `launch` uses `--append-system-prompt` directly on POSIX. `init -g` puts a
+  managed pointer to the store's `AGENTS.md` into the config dir's `AGENTS.md`
+  (pi has no include syntax), never a copy of the block.
+- `env` exports `AGENTS_PYTHON`: the interpreter `dotagents` itself is running
+  under (`sys.executable`), seeded only if unset like the scope roots. Shims
+  and helper scripts now have a default Python they can trust, where a bare
+  `python`/`python3` on PATH may be a Store alias stub, an emulated build, a
+  venv's, or missing.
+
+### Changed
+
+- `overlays add` no longer re-installs and re-runs the setup of a requirement
+  the scope already has (in its own store, or the user store when adding to a
+  project): it is satisfied and left alone, and the log says so. Each missing
+  requirement is still installed and set up before the overlay that needs it;
+  a name asked for explicitly is (re)installed and set up as before.
+
+### Removed
+
+- `overlays --source` and `$AGENTS_OVERLAYS_SRC`: a source directory is just a
+  repo now — `--repo <dir>` / `$AGENTS_OVERLAYS_REPO=<dir>`.
+- The one-release `DOTAGENTS_*` fallbacks: `DOTAGENTS_AGENTS_DIR`,
+  `DOTAGENTS_OVERLAYS_SRC`, `DOTAGENTS_CMDS_PATH`, and the duplicate
+  `DOTAGENTS_AGENTS_DIR` / `DOTAGENTS_OVERLAY_DIR` an overlay's setup script
+  received. Only the `AGENTS_*` names are read or set.
+- The extensionless POSIX `setup` script an overlay could ship: `setup.py` is
+  the one form, run under the interpreter running dotagents on every platform.
+- The precursor's lowercase `session_start` hook key is no longer migrated.
+
+### Fixed
+
+- `init` no longer registers the PowerShell hook variants on POSIX hosts, and
+  removes the ones an earlier `init` wrote there. A `shell: powershell` entry
+  on Linux or macOS is not harmless: Claude Code runs the text as bash and it
+  fails with a syntax error on every session (measured in WSL). Linux and
+  macOS get the bash handler only; Windows keeps both, and the PowerShell one
+  still selects itself only when `bash` is absent. Re-running `init -g` on an
+  existing POSIX install converges.
+- Command discovery is resilient per module, not per directory: one broken
+  file in a `cmds/` dir (a syntax error, an import-time exception, or a
+  `sys.exit()` — which is not an `Exception` and used to escape the guard and
+  kill every invocation, `init -g` for a store that did not exist yet
+  included) is skipped with a warning that names the file, and its siblings
+  still load.
+
 ## [0.4.0] - 2026-09-09
 
 ### Security

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.4.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'
@@ -68,7 +69,7 @@ Description-Content-Type: text/markdown
 
 Like dotfiles, but for AI coding agents: a portable, token-budgeted `~/.agents`
 configuration that works across agent runners (Claude Code, Antigravity, Copilot,
-Codex, ...). dotagents is the **mechanism** — install a neutral base, then layer in
+Codex, pi, ...). dotagents is the **mechanism** — install a neutral base, then layer in
 opt-in **overlays** that carry your standards (repo structure, CI/release discipline,
 whatever workflows you want) — so you record them once instead of restating them every
 session.
@@ -107,9 +108,9 @@ 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 `--source`). See the
+resolves them from there (or from any `--repo`). See the
 [docs](https://jose-pr.github.io/dotagents/) for what each ships.
 
 Named-agent directives aren't a shipped overlay — a named agent (Claude, Antigravity,
@@ -160,11 +161,21 @@ overlay's skills into the shared skills dir. See below.
 
 ### Managing overlays
 
-`dotagents overlays` manages opt-in overlays **by name**, resolving each name against a
-source directory of overlays — point `--source <dir>` (or `$AGENTS_OVERLAYS_SRC`) at
-one, e.g. a checkout of the [`overlays` branch](https://github.com/jose-pr/dotagents/tree/overlays)
-where the example overlays live. Installed overlays are *discovered* by their presence
-under `<scope>/.agents/overlays/` — there is no registry file.
+`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 [`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
+file in the checkout (no path: the checkout root). A source names **one** overlay: a
+local directory, or a git spec whose path is the overlay's root directory (no path: the
+repository root is the overlay); a relative path is relative to the registry file, and
+inside a git checkout stays in the same repository at the same ref. Name repos with `--repo`,
+`$AGENTS_OVERLAYS_REPO_<KEY>` / `$AGENTS_OVERLAYS_REPO`, or a `dotagents.{json,toml,yaml}`
+in the project or user store.
+Installed overlays are *discovered* by their presence under `<scope>/.agents/overlays/`.
 
 ```bash
 dotagents overlays add python engineering  # install into the scope, publish skills, merge D59 rules/routing
@@ -185,9 +196,7 @@ at the manual edit, or re-run `install`).
 
 **Overlay setup scripts.** An overlay may ship an **idempotent** `setup.py` at its root
 (the recommended form: it runs under the same Python that runs dotagents, so it works on
-every OS — the bundled `net` overlay is the model). An extensionless `setup` (a POSIX
-shell script) is still honored as a legacy fallback, but it is discouraged: a shell
-script isn't portable to Windows without a shell. After `add`/`sync` copies the overlay
+every OS). After `add`/`sync` copies the overlay
 in, dotagents runs the script automatically — so anything a human would otherwise
 hand-follow (PATH/lib wiring, self-registration) is one script the tool runs, not a doc.
 When both are present, `setup.py` wins. Presence of a script is the opt-in; skip it with
@@ -217,54 +226,6 @@ Then wire your runner to it — e.g. Claude Code: put `@AGENTS.md` in
 > Read README.md, run `python install.py init && python install.py overlays add engineering -g`,
 > and confirm `~/.agents/overlays/flows/flows/PLAN.md` exists.
 
-## Private sync (per-user + per-project, one private repo)
-
-Keep your global config **and** every project's private `.agents` (plans, kb, findings)
-in a single private git repo — synced across machines and cloud sessions — without ever
-committing any of it into the (often public) project repos.
-
-The idea: your global `~/.agents` **is** a private git repo. Its root is the per-user
-config; a `projects/<name>/` tree holds each project's private `.agents` payload. For a
-checked-out project, `<project>/.agents` is a **symlink** to `~/.agents/projects/<name>`
-(the project's `.gitignore` already excludes `.agents/` per the Leakage rule, so the
-link never lands in the public repo). `<name>` defaults to the project's basename, so a
-local `~/code/app` and a cloud `/home/user/app` resolve to the same store.
-
-The `link-project` / `sync-project` commands are **supplied by the `private-sync`
-overlay**, not by dotagents itself — installing the overlay is what makes them exist
-(it ships the commands, their logic, the `kb/` walkthrough and the cloud hooks
-together). So `overlays add private-sync` comes first:
-
-```bash
-dotagents init                                       # base
-dotagents overlays add private-sync --source <overlays-checkout> # commands + kb + hooks
-dotagents link-project .   # symlink this project's .agents into the private repo
-                           #   (an existing .agents/ is adopted in on the first link;
-                           #    --copy mirrors it as a real dir for no-symlink systems)
-dotagents sync-project -m msg   # git pull --rebase / commit / push the private repo
-dotagents sync-project --remote git@github.com:<you>/.agents.git -m init   # one-command bootstrap
-```
-
-In cloud sessions, the installed `~/.agents/hooks/private-sync-{start,stop}.sh` clone/pull
-the private repo and link/sync the project per session — register them in
-`~/.claude/settings.json` (see `~/.agents/hooks/settings.snippet.json`). For a **fresh
-container** (no `~/.agents` yet), point the web environment's **setup-script** field at the
-self-contained bootstrap in this repo — it fetches the latest each start, so there's
-nothing to re-paste:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/<you>/dotagents/main/tools/cloud-setup.sh -o /tmp/dg-cloud-setup.sh && sh /tmp/dg-cloud-setup.sh
-```
-
-Use `curl … -o file && sh file`, not `curl … | sh`: with a pipe the setup field's exit
-code is `sh`'s (0 on empty stdin), so a failed fetch is silently logged as success; `&&`
-propagates the curl failure instead.
-
-It authenticates (bypassing a hosted-runner `github.com`→proxy git rewrite), clones/pulls
-`~/.agents`, installs the CLI, and links the project — driven by `AGENTS_REMOTE`
-/ `DOTAGENTS_AGENTS_TOKEN` / `DOTAGENTS_CLI_INSTALL` env vars (token never committed). Full
-walkthrough: `~/.agents/kb/PRIVATE_SYNC.md`.
-
 ## Validate
 
 ```bash

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

@@ -7,7 +7,7 @@
 
 Like dotfiles, but for AI coding agents: a portable, token-budgeted `~/.agents`
 configuration that works across agent runners (Claude Code, Antigravity, Copilot,
-Codex, ...). dotagents is the **mechanism** — install a neutral base, then layer in
+Codex, pi, ...). dotagents is the **mechanism** — install a neutral base, then layer in
 opt-in **overlays** that carry your standards (repo structure, CI/release discipline,
 whatever workflows you want) — so you record them once instead of restating them every
 session.
@@ -46,9 +46,9 @@ 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 `--source`). See the
+resolves them from there (or from any `--repo`). See the
 [docs](https://jose-pr.github.io/dotagents/) for what each ships.
 
 Named-agent directives aren't a shipped overlay — a named agent (Claude, Antigravity,
@@ -99,11 +99,21 @@ overlay's skills into the shared skills dir. See below.
 
 ### Managing overlays
 
-`dotagents overlays` manages opt-in overlays **by name**, resolving each name against a
-source directory of overlays — point `--source <dir>` (or `$AGENTS_OVERLAYS_SRC`) at
-one, e.g. a checkout of the [`overlays` branch](https://github.com/jose-pr/dotagents/tree/overlays)
-where the example overlays live. Installed overlays are *discovered* by their presence
-under `<scope>/.agents/overlays/` — there is no registry file.
+`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 [`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
+file in the checkout (no path: the checkout root). A source names **one** overlay: a
+local directory, or a git spec whose path is the overlay's root directory (no path: the
+repository root is the overlay); a relative path is relative to the registry file, and
+inside a git checkout stays in the same repository at the same ref. Name repos with `--repo`,
+`$AGENTS_OVERLAYS_REPO_<KEY>` / `$AGENTS_OVERLAYS_REPO`, or a `dotagents.{json,toml,yaml}`
+in the project or user store.
+Installed overlays are *discovered* by their presence under `<scope>/.agents/overlays/`.
 
 ```bash
 dotagents overlays add python engineering  # install into the scope, publish skills, merge D59 rules/routing
@@ -124,9 +134,7 @@ at the manual edit, or re-run `install`).
 
 **Overlay setup scripts.** An overlay may ship an **idempotent** `setup.py` at its root
 (the recommended form: it runs under the same Python that runs dotagents, so it works on
-every OS — the bundled `net` overlay is the model). An extensionless `setup` (a POSIX
-shell script) is still honored as a legacy fallback, but it is discouraged: a shell
-script isn't portable to Windows without a shell. After `add`/`sync` copies the overlay
+every OS). After `add`/`sync` copies the overlay
 in, dotagents runs the script automatically — so anything a human would otherwise
 hand-follow (PATH/lib wiring, self-registration) is one script the tool runs, not a doc.
 When both are present, `setup.py` wins. Presence of a script is the opt-in; skip it with
@@ -156,54 +164,6 @@ Then wire your runner to it — e.g. Claude Code: put `@AGENTS.md` in
 > Read README.md, run `python install.py init && python install.py overlays add engineering -g`,
 > and confirm `~/.agents/overlays/flows/flows/PLAN.md` exists.
 
-## Private sync (per-user + per-project, one private repo)
-
-Keep your global config **and** every project's private `.agents` (plans, kb, findings)
-in a single private git repo — synced across machines and cloud sessions — without ever
-committing any of it into the (often public) project repos.
-
-The idea: your global `~/.agents` **is** a private git repo. Its root is the per-user
-config; a `projects/<name>/` tree holds each project's private `.agents` payload. For a
-checked-out project, `<project>/.agents` is a **symlink** to `~/.agents/projects/<name>`
-(the project's `.gitignore` already excludes `.agents/` per the Leakage rule, so the
-link never lands in the public repo). `<name>` defaults to the project's basename, so a
-local `~/code/app` and a cloud `/home/user/app` resolve to the same store.
-
-The `link-project` / `sync-project` commands are **supplied by the `private-sync`
-overlay**, not by dotagents itself — installing the overlay is what makes them exist
-(it ships the commands, their logic, the `kb/` walkthrough and the cloud hooks
-together). So `overlays add private-sync` comes first:
-
-```bash
-dotagents init                                       # base
-dotagents overlays add private-sync --source <overlays-checkout> # commands + kb + hooks
-dotagents link-project .   # symlink this project's .agents into the private repo
-                           #   (an existing .agents/ is adopted in on the first link;
-                           #    --copy mirrors it as a real dir for no-symlink systems)
-dotagents sync-project -m msg   # git pull --rebase / commit / push the private repo
-dotagents sync-project --remote git@github.com:<you>/.agents.git -m init   # one-command bootstrap
-```
-
-In cloud sessions, the installed `~/.agents/hooks/private-sync-{start,stop}.sh` clone/pull
-the private repo and link/sync the project per session — register them in
-`~/.claude/settings.json` (see `~/.agents/hooks/settings.snippet.json`). For a **fresh
-container** (no `~/.agents` yet), point the web environment's **setup-script** field at the
-self-contained bootstrap in this repo — it fetches the latest each start, so there's
-nothing to re-paste:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/<you>/dotagents/main/tools/cloud-setup.sh -o /tmp/dg-cloud-setup.sh && sh /tmp/dg-cloud-setup.sh
-```
-
-Use `curl … -o file && sh file`, not `curl … | sh`: with a pipe the setup field's exit
-code is `sh`'s (0 on empty stdin), so a failed fetch is silently logged as success; `&&`
-propagates the curl failure instead.
-
-It authenticates (bypassing a hosted-runner `github.com`→proxy git rewrite), clones/pulls
-`~/.agents`, installs the CLI, and links the project — driven by `AGENTS_REMOTE`
-/ `DOTAGENTS_AGENTS_TOKEN` / `DOTAGENTS_CLI_INSTALL` env vars (token never committed). Full
-walkthrough: `~/.agents/kb/PRIVATE_SYNC.md`.
-
 ## Validate
 
 ```bash

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

@@ -11,6 +11,8 @@ form its API. Generated from docstrings, organized by module:
   `AGENTS.md` contributions; setup-script discovery and the manifest reader.
 - **[Scope](scope.md)** — scope and overlay-source resolution for the `overlays`
   command.
+- **[Sources](sources.md)** — overlay repos: directories of overlays, registry
+  files, git specs, and the precedence the `overlays` commands resolve names through.
 - **[Context](context.md)** — assembling the effective context for agents.
 - **[Environment](env.md)** — chained env-file assembly and `env.py` execution.
 - **[Merge](merge.md)** — the managed-block merge for `init`'s `AGENTS.md` /

dotagents_cli-0.5.1/docs/api/sources.md

@@ -0,0 +1,3 @@
+# Sources
+
+::: dotagents._sources

{dotagents_cli-0.4.0 → dotagents_cli-0.5.1}/docs/guide/authoring.md

@@ -1,8 +1,8 @@
 # Authoring an overlay
 
 An overlay is just a directory with the files you want laid into a scope, plus an
-optional `overlay.toml` manifest. Anyone can write one; point `dotagents overlays` at
-its parent directory with `--source`.
+optional `overlay.toml` manifest. Anyone can write one; name its parent directory (a
+directory of overlays), a registry, or a git repo with `--repo` — see the overlays guide.
 
 ## Minimal overlay
 
@@ -24,7 +24,7 @@ routing = [
 Install it:
 
 ```bash
-python -m dotagents overlays add my-overlay --source /path/to/parent -g
+python -m dotagents overlays add my-overlay --repo /path/to/parent -g
 ```
 
 The overlay's files land at the same relative path in the scope, and each `routing`
@@ -54,10 +54,7 @@ matters.
 
 Ship an idempotent `setup.py` at the overlay root to run install-time wiring
 automatically — the recommended, OS-agnostic form (it runs under the same Python as
-dotagents, so it works on every platform; the bundled `net` overlay is the model). An
-extensionless `setup` (a POSIX shell script) still works as a legacy fallback but is
-discouraged — it needs a shell, so it isn't portable to Windows. When both are present,
-`setup.py` wins. See the contract in
+dotagents, so it works on every platform). See the contract in
 [Overlays → Setup scripts](overlays.md#setup-scripts). The essentials:
 
 - idempotent, check-then-act;

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

@@ -11,16 +11,18 @@ 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` is the one bundled command
-module (discovered from the package itself, overridable by a same-named module in a
-scope's `cmds/`). Everything else is **discovered**, from each **installed overlay's** `cmds/`
+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
+in a scope's `cmds/`). Everything else is **discovered**, from each **installed overlay's** `cmds/`
 dir, each scope's command dir, `$AGENTS_CMDS_PATH` entries, and `--cmdspath` — one
 Contract-A resolver walk covers the overlay + scope tiers (D84). Two consequences
 worth knowing:
@@ -107,7 +109,7 @@ managed block into `config.toml`:
 ```toml
 # dotagents:begin
 [shell_environment_policy]
-set = {AGENT = "codex", AGENTS_HARNESS = "codex", AGENTS_VENDOR = "openai", AGENTS_HOME = "...", AGENTS_PROJECT_ROOT = "..."}
+set = {AGENT = "codex", AGENTS_HARNESS = "codex", AGENTS_VENDOR = "openai", AGENTS_HOME = "...", AGENTS_PROJECT_ROOT = "...", AGENTS_PYTHON = "..."}
 # dotagents:end
 ```
 
@@ -142,9 +144,12 @@ dotagents overlays sync --overwrite        # also replace installed files whose
 dotagents overlays show python             # describe one: manifest, requires, setup, skills (--json)
 ```
 
-`add` installs what each manifest's `requires` names first (`--no-requires` to skip),
-validates every name before touching anything, and publishes skills from the installed
-copy. `remove` recomposes `AGENTS.md`'s managed block over the overlays that remain, so
+`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 (re)installed and set up.
+It validates every name before touching anything, and publishes skills from the
+installed copy. `remove` recomposes `AGENTS.md`'s managed block over the overlays that remain, so
 an overlay's rules and routing leave with it. `sync` never clobbers an installed file
 unless `--overwrite`.
 
@@ -169,7 +174,8 @@ dotagents context --write-agent --agents codex # merge a managed block into <pro
 - `--write-agent` — merge the context into each agent's own instruction file under
   the project root, as a managed `dotagents:context` block refreshed in place:
   Claude `.claude/CLAUDE.md`, Codex `AGENTS.md`, Gemini `GEMINI.md`, Cursor
-  `.cursorrules`, Copilot `.github/copilot-instructions.md`, Antigravity
+  `.cursorrules`, Copilot `.github/copilot-instructions.md`, pi
+  `.pi/APPEND_SYSTEM.md` (the file pi appends to its system prompt), Antigravity
   `.agents/rules/dotagents.md`. Prefer the hook where the harness has one; this is
   the static alternative. Mutually exclusive with `[output]` and `--format json`.
 - `--inline` — also append the on-demand `.md` files the sources reference (bare or
@@ -209,7 +215,11 @@ python -m dotagents env --diff --format json   # only vars that differ from the
 
 Roots resolve exactly as for `context` above (`$AGENTS_HOME` /
 `$AGENTS_PROJECT_ROOT`, both of which `env` also emits — so a subprocess reading
-them agrees with the parent that wrote them). `env` also emits one
+them agrees with the parent that wrote them). `env` also emits `AGENTS_PYTHON`,
+the interpreter `dotagents` itself is running under — the Python a shim or helper
+script should run with, since a bare `python`/`python3` on `PATH` may be a Store
+stub, an emulated build, a venv's, or missing (only if unset, so a pin holds;
+the env-layer `env.py` scripts run under a valid pin too). And `env` emits one
 `<NAME>_OVERLAY_ROOT` per installed overlay, where `NAME` is the overlay's
 directory name upper-cased with `-`/`.` turned into `_` (`my-ov` →
 `MY_OV_OVERLAY_ROOT`). It is the same name `context` expands as a
@@ -267,6 +277,48 @@ dotagents findings path                     # where this scope's queue lives
 - The command is bundled with dotagents and discovered from the package itself;
   a same-named `findings.py` in a scope's `dotagents/cmds/` overrides it.
 
+## launch
+
+Start an agent's command-line harness the way a session wired by `init` would
+find the world already: the full `env` exported, and the `context` handed over
+up front.
+
+```bash
+dotagents launch claude -- --model sonnet   # everything after `--` is the agent's
+dotagents launch                            # the active agent, as `context` picks it
+dotagents launch codex --dry-run            # print the command line and the exported names
+dotagents launch -g gemini                  # user-store tiers only (the env/context meaning of -g)
+```
+
+What happens, in order:
+
+1. **Environment** — the same assembly as `dotagents env` for this scope (identity
+   vars, `AGENTS_HOME` / `AGENTS_PROJECT_ROOT` / `AGENTS_PYTHON`, every
+   `<NAME>_OVERLAY_ROOT`, the `PATH` / `PYTHONPATH` prepends, the env-file chain)
+   is applied to the `dotagents` process and handed to the child, so the harness
+   and everything it spawns see it.
+2. **Context** — `dotagents context` for that agent (what its harness does not
+   already load) is written to a file, exported as `AGENTS_CONTEXT_FILE`, and
+   passed the way the harness takes appended system-prompt text: Claude Code gets
+   `--append-system-prompt-file`, pi gets `--append-system-prompt` (on POSIX; on
+   Windows its npm `.cmd` shim cannot carry a multi-line argument, so it takes the
+   static route below). A harness with no append flag (Codex, Gemini,
+   Cursor, Copilot — their prompt-file options *replace* the built-in prompt, which
+   is not the same thing) gets it the static way instead: merged as the managed
+   `dotagents:context` block into its own instruction file in the project, exactly
+   what `context --write-agent` does. `--no-context` skips this; `--inline` also
+   inlines the on-demand files the sources reference.
+3. **The harness** — the agent's program (`claude`, `codex`, `gemini`,
+   `cursor-agent`, `copilot`, `pi`), resolved on the PATH from step 1 so a harness an
+   overlay's `bin/` provides is found, or `--command <program>` for one under
+   another name. dotagents' flags come first and the passthrough after, so yours
+   win where the harness takes the last value. The exit code is the harness's.
+
+`--dry-run` prints the command line and the names of the exported changes (never
+their values) and runs nothing. Like `findings`, the command is bundled and
+discovered from the package; a same-named `launch.py` in a scope's
+`dotagents/cmds/` overrides it.
+
 ## audit — not a dotagents command
 
 There is no `dotagents audit`. The dotagents source repo has its own
@@ -291,7 +343,7 @@ behind them, so a plain install carries no private-sync workflow at all. Install
 overlay first and they become available like any other subcommand:
 
 ```bash
-python -m dotagents overlays add private-sync --source <overlays-checkout>
+python -m dotagents overlays add private-sync --repo <overlays-checkout>/overlays
 
 python -m dotagents link-project .                       # symlink this project's .agents into its store
 python -m dotagents link-project . --copy                # real-dir copy (no-symlink systems)
@@ -304,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