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

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

@@ -24,6 +24,7 @@ dist/
 *.pyz
 .venv/
 .venv-test/
+.pyvenv/
 
 # MkDocs build output
 site/

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

@@ -7,6 +7,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.4.0
+Version: 0.5.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
@@ -68,7 +68,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.
@@ -109,7 +109,7 @@ The **example overlays** — the `flows` workflow set, per-language `kb/` + temp
 `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
 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 +160,20 @@ 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 [`overlays` branch](https://github.com/jose-pr/dotagents/tree/overlays)) 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 +194,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 +224,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.0}/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.
@@ -48,7 +48,7 @@ The **example overlays** — the `flows` workflow set, per-language `kb/` + temp
 `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
 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,20 @@ 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 [`overlays` branch](https://github.com/jose-pr/dotagents/tree/overlays)) 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 +133,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 +163,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.0}/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.0/docs/api/sources.md

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

{dotagents_cli-0.4.0 → dotagents_cli-0.5.0}/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.0}/docs/guide/commands.md

@@ -17,10 +17,11 @@ by default (the `<cwd>/.agents` store, when run inside a project) or **user** wi
 | `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. |
 
-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 +108,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 +143,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 +173,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 +214,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 +276,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 +342,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)

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

@@ -8,10 +8,10 @@ opinionated ships as a named overlay you add explicitly.
 
 An overlay is a directory (optionally carrying an `overlay.toml` manifest) whose files
 install to the same relative path in the destination scope. `dotagents overlays`
-resolves each overlay **by name** against a source directory you point it at with
-`--source <dir>` (or `$AGENTS_OVERLAYS_SRC`), and installs it into the scope's
-overlays directory. There is **no registry file**: installed overlays are *discovered*
-by their presence there.
+resolves each overlay **by name** against the repos you name (`--repo`,
+`$AGENTS_OVERLAYS_REPO`, a `dotagents.{json,toml,yaml}` in a store — see
+"Where overlays come from" below), and installs it into the scope's overlays
+directory. Installed overlays are then *discovered* by their presence there.
 
 Overlays are **additive**. `add` / `sync` never clobber a file you hand-edited inside
 an installed overlay — an already-present file is skipped.
@@ -21,8 +21,8 @@ an installed overlay — an already-present file is skipped.
 The example overlays below live on this repo's separate
 [`overlays` branch](https://github.com/jose-pr/dotagents/tree/overlays), not in `main` —
 they are **payloads riding on dotagents**, not part of the tool, so you swap them for
-your own. Point `--source` at a checkout of that branch to install any with
-`dotagents overlays add <name> --source <overlays-checkout>`.
+your own. Name a checkout of that branch as a repo to install any with
+`dotagents overlays add <name> --repo <overlays-checkout>/overlays`.
 
 | Overlay | What it carries |
 | --- | --- |
@@ -60,6 +60,63 @@ published (a copy the user edited is left alone). Its lines in `AGENTS.md`'s man
 block leave with it: the block is recomposed from the pristine base over the overlays
 that remain.
 
+## Where overlays come from: repos
+
+`add`, `sync`, `list` and `show` resolve a name against a list of **repos**, and the
+first repo that offers the name wins. A repo is **always a collection** of overlays,
+in one of two shapes:
+
+- a **directory of overlays** — each subdirectory is an overlay, `<dir>/<name>/` (a
+  checkout of the `overlays` branch, 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).
+
+Both the repo and each source are written as a spec, `<location>[@<ref>][#<path>]`:
+`<location>` is a local path, an `http(s)://` URL, or a git repository
+(`https://…/x.git`, `git@host:org/x.git`, `ssh://…`, a local `…/x.git`; prefix `git+` to
+force git); `<ref>` is a branch, tag or commit; `<path>` is inside it. The two differ
+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;
+- for a **source**, the overlay: the path is the overlay's root directory, and with no
+  path **the repository root is the overlay**.
+
+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.
+
+Checkouts are cached under `<user store>/.cache/overlays/` and refreshed on every
+`add`/`sync`.
+
+The repos, in order:
+
+1. `--repo <spec>` (repeatable);
+2. `$AGENTS_OVERLAYS_REPO_<KEY>=<spec>`, sorted by `KEY`, then `$AGENTS_OVERLAYS_REPO`
+   (the default repo);
+3. `<project store>/dotagents.{json,toml,yaml,yml}`, then the user store's;
+4. the `overlays/` bundled with this build, if any.
+
+```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"
+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
+```
+
+```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 sync -g                                             # refetches git-sourced overlays
+```
+
 ## What `dotagents env` wires for every overlay
 
 Nothing in an overlay has to set up its own paths. For every installed overlay,
@@ -98,9 +155,7 @@ only the skills it published, then sweeps any now-broken symlinks.
 
 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. An extensionless `setup` (a POSIX shell script) is still honored as a
-**legacy fallback**, but discouraged — a shell script isn't portable to Windows without
-a shell. When both are present, `setup.py` wins. After `add` / `sync` copies the overlay
+every platform. After `add` / `sync` copies the overlay
 in, dotagents runs the script automatically. Reserve it for real install-time work:
 PATH / PYTHONPATH / `$<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

{dotagents_cli-0.4.0 → dotagents_cli-0.5.0}/docs/guide/private-sync.md

@@ -24,7 +24,7 @@ entry.
 
 ```bash
 dotagents init                                            # base config
-dotagents overlays add private-sync --source <overlays-checkout>  # commands + kb + hooks
+dotagents overlays add private-sync --repo <overlays-checkout>/overlays  # commands + kb + hooks
 
 # link-project / sync-project come FROM that overlay -- run `overlays add` first.
 python -m dotagents link-project .   # symlink this project's .agents into its store

{dotagents_cli-0.4.0 → dotagents_cli-0.5.0}/docs/index.md

@@ -2,7 +2,7 @@
 
 **dotagents** is 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
+Copilot, 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.

{dotagents_cli-0.4.0 → dotagents_cli-0.5.0}/mkdocs.yml

@@ -40,6 +40,7 @@ nav:
       - Agents: api/agents.md
       - Overlays: api/overlays.md
       - Scope: api/scope.md
+      - Sources: api/sources.md
       - Context: api/context.md
       - Environment: api/env.md
       - Merge: api/merge.md

{dotagents_cli-0.4.0 → dotagents_cli-0.5.0}/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.4.0"
+version = "0.5.0"
 authors = [{ name = "Jose A." }]
 description = "The dotagents CLI: install and manage a portable ~/.agents config for AI coding agents"
 readme = "README.md"