dotagents-cli 0.3.0__tar.gz

dotagents_cli-0.3.0/.gitignore

@@ -0,0 +1,36 @@
+# Private agent config. No trailing slash: `dotagents link-project` makes .agents
+# a symlink, which git treats as a file, so a directory-only `.agents/` would not
+# match it. The design log lives INSIDE .agents/dotagents/ and is private like
+# every other project's (D61, reversing D56); CHANGELOG.md cites no D-numbers.
+.agents
+*.local.md
+CLAUDE.local.md
+.claude/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+src/*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.tox/
+.coverage
+htmlcov/
+
+# dotagents CLI package build artifacts (release artifacts, not committed)
+dist/
+*.pyz
+.venv/
+.venv-test/
+
+# MkDocs build output
+site/
+
+# OS/editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+_staging/

dotagents_cli-0.3.0/CHANGELOG.md

@@ -0,0 +1,212 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-07-24
+
+### Changed
+
+- **BREAKING** — `dotagents link` / `dotagents sync` are gone from the CLI. They are
+  the private-sync workflow's commands, not dotagents' core, so they moved — together
+  with the logic behind them (`src/dotagents/_link.py`) — into the opt-in
+  **`private-sync` overlay**, and were renamed to say what they act on:
+
+      dotagents link-project .            # was: dotagents link .
+      dotagents sync-project -m "msg"     # was: dotagents sync -m "msg"
+
+  Install the overlay to get them back: `dotagents overlays add private-sync --source
+  <overlays-checkout>`. A plain dotagents now ships no private-sync workflow at all;
+  its whole command surface is `init` / `build-pyz` / `context` / `env` / `overlays`,
+  and everything else is discovered from an overlay or from your own `cmds/` modules.
+  `tools/cloud-setup.sh` installs the overlay before linking, so the cloud bootstrap
+  is unaffected.
+- The bundled `dotagents/cmds/` directory now ships no command module of its own, but
+  `init` still creates it: it is the documented drop-in point for your own commands
+  (a `README.md` beside it explains the shape and the precedence rules).
+
+### Added
+
+- feat: `init` wires agent hooks and links the shared skills dir, for each active
+  agent with a published hook schema (today: Claude and Codex). `--no-hooks` skips it.
+
+  **Claude** (`~/.claude/settings.json`) gets `SessionStart`, which appends
+  `dotagents env --diff --format export` to `$CLAUDE_ENV_FILE` and then runs
+  `dotagents context` — Claude sources that file before each Bash command and injects
+  the hook's stdout into the session context, so both the env layers and the assembled
+  context reach the session automatically. It also gets `CwdChanged`, surfacing a
+  directory's `AGENTS.md`. The env redirect **appends** and is guarded against an
+  unset variable, both as the hooks docs require.
+
+  **Codex** (`~/.codex/hooks.json`, or `$CODEX_HOME`) gets `SessionStart` running
+  `dotagents context`; its hook JSON is structurally identical to Claude's. We write
+  `hooks.json` rather than touching your `config.toml` for hooks.
+
+  Codex's env arrives differently: it has no `$CLAUDE_ENV_FILE` equivalent, reads no
+  `.env` files, and has no event that fires before config load, so
+  `dotagents init --agents codex` writes a `# dotagents:begin/end` managed block
+  containing `[shell_environment_policy].set` into `config.toml`. **Only on an
+  explicit `--agents`** — this edits your main config with values that go stale, so
+  auto-detection never triggers it. The block is appended and refreshed in place
+  (everything outside the markers is untouched) and `set` merges rather than
+  replaces. **The values are a static snapshot: re-run `init` after changing your env
+  layers.** Identity vars describe the target agent, so initializing from Claude still
+  writes `AGENT = "codex"`; `PATH` is excluded, since `set` overrides per subprocess
+  and a baked-in `PATH` would replace the inherited one.
+
+  The merge is additive and idempotent: unrelated keys and hooks you wrote yourself
+  survive verbatim, malformed entries are dropped rather than raising, and re-running
+  writes nothing.
+
+  `init` also links `<scope>/skills/` into the agent's config dir, closing the last
+  mile for overlay-published skills — publishing only helps if the agent reads that
+  directory. Symlink where the OS permits, copy otherwise (a copy is a snapshot;
+  re-run `init` to refresh).
+
+- feat: `tools/leak_check.py` now also scans commit messages (current branch history)
+  for agent-session trailers/URLs — a `Claude-Session:` trailer or `claude.ai/code/session`
+  link — and exits 1 on any hit. The trailer is auto-added by the agent harness and
+  exposes a session id in public history if it slips through; the pre-existing tracked-file
+  scan didn't cover commit messages. `flows/REPO.md` release discipline documents the check
+  and the `git filter-branch --msg-filter` remediation for one that already landed.
+- feat: `tools/cloud-setup.sh` step 5 wires `hooks/settings.snippet.json` into the
+  user-level `~/.claude/settings.json` (idempotent JSON merge, preserves existing
+  settings/hooks). A fresh cloud container has no settings file and nothing else
+  created one, so the SessionStart pull/link and Stop sync-back hooks never ran —
+  the private repo went stale and session changes were silently never pushed back.
+  `kb/PRIVATE_SYNC.md` documents the auto-wiring (manual merge still applies on
+  local machines).
+
+### Fixed
+
+- fix: `dotagents link`/`sync` never adopt or copy back a `<project>/.agents` that is
+  itself a git checkout (`.git` present — dir, or file for worktrees). A hosted-runner
+  session that lists the agents repo as a *source* gets it cloned to
+  `<project>/.agents` by the harness; first-link adoption then moved that entire
+  checkout — `.git`, foreign proxy remote, session branch — into
+  `~/.agents/projects/<name>/`, nesting a repo inside the private repo, which a later
+  sync's `git add -A` would push as a bare gitlink (and `sync`'s copy-back had the same
+  swallow, with `overwrite=True`). Both paths now log a skip and leave the checkout in
+  place; `link --force` keeps an escape hatch that backs the checkout up to
+  `.agents.bak*` (git state intact) and links the store.
+
+- fix: `dotagents sync` now authenticates the private repo directly against github.com
+  when `DOTAGENTS_AGENTS_TOKEN` is set — and on a hosted runner that rewrites github
+  traffic to a scoped in-session proxy, bypasses the rewrite — so a **standalone**
+  `dotagents sync` no longer 403s. Previously only the private-sync Stop hook worked
+  (it sources `_agents-git-auth.sh`); a direct CLI run had no bypass, so its pull failed
+  (`could not read Password`) and its push returned HTTP 403 through the proxy. The CLI
+  now ports that logic: a per-command `-c` credential helper in a normal environment, or
+  an isolated `GIT_CONFIG_GLOBAL` (identity + CA bundle preserved) that skips the rewrite
+  when one is active. The token is still read from the environment at auth time and never
+  written to `.git/config`.
+- fix: `tools/cloud-setup.sh` no longer lets a single container-start clone failure
+  permanently disable the environment. The clone often loses a race with egress/proxy
+  readiness; previously it `exit 0`'d on the first failure, skipping the hook-wiring
+  step — so the SessionStart hook (which can itself re-clone) was never registered and
+  nothing ever recovered. Now the clone retries with backoff (5 attempts), and if it
+  still fails the script persists a copy of itself and wires a SessionStart **recovery
+  hook** that re-runs the bootstrap next session (egress is up by then); the first
+  successful run merges the private-sync hooks and removes the recovery hook.
+- fix: `tools/cloud-setup.sh` also wires that recovery hook when
+  `DOTAGENTS_AGENTS_REMOTE` is **unset at setup time**, not only on clone failure.
+  Hosted runners often expose the remote/token secrets to session processes but not
+  to the setup-script phase, so the first bootstrap had no remote to clone and its
+  no-remote branch just `exit 0`'d, leaving nothing to retry — the environment stayed
+  dead every session (observed: setup ran the correct one-liner and emitted only the
+  banner + `skipping` line, ~154 bytes, no clone). The branch now persists the recovery
+  hook like the exhausted-clone path, so the next session — where the secret is present
+  — clones and self-removes the hook. A genuinely remote-less environment just re-skips
+  each session (idempotent; the hook never duplicates). (Durable fix is still
+  to expose the secrets to the Setup Script phase so the first container succeeds.)
+- fix: `.gitignore` templates and `dotagents link` now use a slashless `.agents`
+  instead of `.agents/`. `link` creates `.agents` as a *symlink*, which git treats
+  as a file, so the directory-only `.agents/` pattern never actually ignored it —
+  the link showed up as untracked in every project. `_gitignore_excludes_agents`
+  is now symlink-aware (a bare `.agents/` no longer counts as excluding a symlinked
+  link, so the WARN fires), and the reference template, REPO.md guidance, and the
+  starter `_overlay/AGENTS.md` Leakage rule all recommend `.agents`.
+- docs: recommend `curl … -o file && sh file` over `curl … | sh` for the setup-script
+  field (README, `kb/PRIVATE_SYNC.md`, `tools/cloud-setup.sh` header). With a pipe the
+  field's exit code is `sh`'s (0 on empty stdin), so a failed fetch at container start
+  is silently reported as success; `&&` propagates the fetch failure to the setup log.
+
+### Changed
+
+- refactor: move the cloud bootstrap from `overlays/private-sync/hooks/cloud-setup.sh` to
+  top-level `tools/cloud-setup.sh` (public, required tooling) so a fresh cloud container
+  can fetch-and-run it from the public repo instead of pasting its contents — the web
+  environment setup-script field becomes a one-liner
+  (`curl -fsSL …/tools/cloud-setup.sh | sh`) that stays current on every container start.
+  Docs (README, `kb/PRIVATE_SYNC.md`) updated to the download bootstrap.
+- fix: `tools/cloud-setup.sh` prints `starting`/`done` banners (so a setup-script log
+  proves whether it executed — a blank log means the field never invoked it, a config
+  issue) and `mkdir -p "$HOME"` before `git config --global` (which fails if HOME isn't
+  created yet in some setup contexts).
+
+## [0.2.0] - 2026-07-19
+
+### Changed
+
+- chore: migrate the CLI to `duho>=0.3.3` (was `>=0.1.1`). duho's Plan-13 `Args`/`Cmd`
+  split means commands are now `class X(LoggingArgs, Cmd)` with a `__call__` entrypoint
+  (was a bare `LoggingArgs` with `__run__`) and the umbrella root is
+  `class Dotagents(LoggingArgs, Cli)`. Field declarations (annotation + help string +
+  flags tuple) are unchanged. Bumped the `build-pyz` vendored `duho` default to 0.3.3.
+- fix: restore full flag/help fidelity in the built `dotagents.pyz` under duho 0.3.3.
+  duho discovers each field's flags + help by AST-parsing its module source, and inside
+  a zipapp the zip-internal `__file__` isn't readable — degrading `--from` to `--from-`,
+  the `link` positional to `--path`, and dropping help text. `cli.main` now repoints the
+  affected module sources (`dotagents.cli`, `duho.presets`) to extracted temp files
+  before dispatch; a no-op for a plain install.
+
+### Added
+
+- feat: private-agents git sync — `dotagents link` symlinks a project's `.agents` to a
+  per-project store under the global `~/.agents/projects/<name>` (basename-keyed, so a
+  local and a cloud checkout converge on the same store), adopting an existing real
+  `.agents/` into an empty store on the first link; `--copy` mirrors it as a real dir
+  for no-symlink environments (with automatic fallback), `--force` handles conflicts.
+  `dotagents sync` runs `git pull --rebase`/commit/push on the private repo, copies a
+  copy-mode project's `.agents` back into its store first (`--project`), and bootstraps
+  a fresh repo in one command (`--remote`). Logic in `src/dotagents/_link.py`; the model
+  keeps per-user config and every project's private `.agents` in one private repo while
+  the public project repos track none of it (the Leakage rule already `.gitignore`s
+  `.agents/`).
+- feat: `overlays/private-sync/` overlay — `kb/PRIVATE_SYNC.md` (the model, commands,
+  first-time + cloud setup, auth, gotchas) plus `hooks/private-sync-{start,stop}.sh`
+  (SessionStart clone/pull + link, Stop sync-back) and a `settings.snippet.json` for
+  `~/.claude/settings.json`, so cloud sessions link and sync automatically. Cloud auth is
+  a fine-grained PAT via `DOTAGENTS_AGENTS_TOKEN`, wired through a git credential helper
+  that reads it from the environment (never persisted to `.git/config`);
+  `hooks/_agents-git-auth.sh` auto-detects a hosted-runner `github.com`→in-session-proxy
+  `insteadOf` rewrite and bypasses it (isolated git config) so token auth reaches the
+  real github.com for a private repo outside the session's scope. `hooks/cloud-setup.sh`
+  is a self-contained container-start bootstrap (inlines auth + bypass, so it runs before
+  `~/.agents` exists) that clones/pulls the repo, installs the CLI, and links the project
+  — for the web environment's setup-script field, solving the first-clone chicken-and-egg
+  the SessionStart hook can't.
+- feat: installable `dotagents` CLI package (`src/dotagents/`, built on `duho` for
+  the argument surface and `pathlib_next` for copy/URI handling) exposing `init`
+  (lay down the neutral base overlay), `install` (base plus opt-in overlays via
+  repeatable `--overlays <path>`, copied additively), `audit` (wraps
+  `tools/audit_config.py`), and `build-pyz` (vendors pinned `duho`/`pathlib_next`
+  via `pip install --target` + `zipapp` into a self-contained, downloadable
+  `dotagents.pyz`). `init`'s `AGENTS.md`/`CLAUDE.md` are merged as a
+  marker-delimited managed block so re-running never clobbers customizations
+  outside the block. `install --bin-dir` writes `dotagents`/`dotagents.cmd`
+  wrappers. `install.py` is a thin shim over `dotagents.cli.main()`.
+- Config content is a **neutral base overlay** (`src/dotagents/_overlay/` — the
+  `AGENTS.md` scaffolding + design-log convention `init` writes) plus **opt-in
+  overlays** (`overlays/<name>/`): `flows` (PLAN/EXEC/REVIEW/REPO + MODELS),
+  `recovery`, `references`, `python`/`node`/`rust`, `agents`, `tools`. Each carries
+  an `overlay.toml` manifest for a future `dotagents overlays` subcommand.
+- Repo layout: the CLI in `src/dotagents/`, config overlays in `overlays/`, required
+  tooling in top-level `tools/` (`audit_config.py`, `leak_check.py`); repo root holds
+  the installer, CI, repo-development directives, and the tracked, sanitized
+  `.agents/` design log (index + per-decision files) + plans. `audit_config.py` has
+  `--repo-hygiene` (scans tracked files for personal/machine-specific leftovers).

dotagents_cli-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose A.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dotagents_cli-0.3.0/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: dotagents-cli
+Version: 0.3.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
+Project-URL: Documentation, https://jose-pr.github.io/dotagents/
+Author: Jose A.
+License: MIT License
+        
+        Copyright (c) 2026 Jose A.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: duho>=0.4.0
+Requires-Dist: pathlib-next>=0.8.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: http
+Requires-Dist: pathlib-next[http]; extra == 'http'
+Provides-Extra: s3
+Requires-Dist: pathlib-next[s3]; extra == 's3'
+Provides-Extra: sftp
+Requires-Dist: pathlib-next[sftp]; extra == 'sftp'
+Provides-Extra: uri
+Requires-Dist: pathlib-next[uri]; extra == 'uri'
+Description-Content-Type: text/markdown
+
+# dotagents
+
+[![Test](https://img.shields.io/github/actions/workflow/status/jose-pr/dotagents/test.yml?branch=main&label=tests)](https://github.com/jose-pr/dotagents/actions/workflows/test.yml)
+[![Documentation](https://img.shields.io/badge/docs-online-blue.svg)](https://jose-pr.github.io/dotagents/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/jose-pr/dotagents/blob/main/LICENSE)
+
+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
+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.
+
+## Design
+
+- **Core + load-on-demand routing.** `AGENTS.md` is the only always-loaded file: a
+  handful of always-on rules plus a routing table. Task-specific detail lives in
+  `flows/` and `kb/` files that an agent reads only when the task matches. You pay for
+  what you use.
+- **A neutral base + opt-in overlays.** `init` lays down a minimal, opinion-free
+  **base overlay** (just the `AGENTS.md` scaffolding + design-log convention).
+  Everything opinionated — workflows, language `kb/` files, repo templates, tools —
+  lives in composable **overlays** you layer in explicitly
+  (`dotagents overlays add <name>`), each contributing its own routing lines, rules,
+  skills, and commands. Additive-only: overlays never overwrite something you've
+  already customized.
+- **Overlays carry the opinions, not the tool.** dotagents is the mechanism
+  (install, compose, discover); *what* your agents should do is an overlay concern.
+  The example overlays in this repo are a starting point — a planning/execution/review
+  workflow set, language conventions, a release helper — but they're payloads riding on
+  dotagents, swappable for your own. See the [docs](https://jose-pr.github.io/dotagents/)
+  for what each ships.
+
+## Layout
+
+The config is a **base overlay** plus opt-in **overlays**; the `dotagents` CLI applies
+them. Everything else is repo infrastructure.
+
+| Path | What |
+| --- | --- |
+| `src/dotagents/` | The installable `dotagents` CLI (`init`/`overlays`/`context`/`env`/`build-pyz`) — that is the whole shipped surface; commands beyond it come from overlays or your own `cmds/` modules |
+| `src/dotagents/_overlay/` | The **base overlay** `init` writes: `AGENTS.md` scaffolding, `CLAUDE.md`, `dotagents/DECISIONS.md` (empty design-log index), and an empty `dotagents/cmds/` dir — your drop-in point for your own command modules. Neutral — imposes no flows, ships no command |
+| `tools/` | Required tooling (not an overlay): `cloud-setup.sh` (`leak-check` moved to the opt-in `leak-check` overlay, D84) |
+| `install.py` | Thin shim over `dotagents.cli.main()`, kept at this filename for muscle memory |
+
+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
+tree: they are swappable payloads, not part of the tool. `dotagents overlays add <name>`
+resolves them from there (or from any `--source`). 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,
+…) just reads its own `~/.agents/<agent>.md` on top of the shared `AGENTS.md`, which the
+base overlay's routing already states. This config's own design log lives **privately**
+under its untracked `.agents/dotagents/` (`DECISIONS.md` + one file per decision) — like
+every project, `.agents/` is never tracked or pushed.
+
+Each overlay's `<name>/overlay.toml` carries a `name`/`description`/`requires`/`routing`
+manifest read by the `dotagents overlays` subcommand, which manages overlays by name
+(`add`/`remove`/`list`/`sync`) — see [Managing overlays](#managing-overlays) below.
+
+## Install
+
+**`dotagents init`** lays down the neutral base config; a self-contained downloadable
+`.pyz` needs no `pip install` at all.
+
+`init` writes the `.agents/` scaffolding — the `AGENTS.md` managed block, the per-agent
+`<CLAUDE|ANTIGRAVITY|...>.md → @AGENTS.md` pattern, the design-log convention — and
+wires each supporting agent's hooks so `dotagents context` reaches it automatically at
+session start (`--no-hooks` opts out) — but
+imposes no opinions (those come from `overlays add`). Its `AGENTS.md`/`CLAUDE.md` are a
+marker-delimited managed block, so re-running `init` never clobbers what you've added
+around it. **Scope**: project by default (`<cwd>/.agents`), or the user store with
+`-g`/`--global` (`~/.agents`).
+
+```bash
+dotagents init                          # project: <cwd>/.agents
+dotagents init -g                       # user store: ~/.agents
+dotagents init --bin-dir ~/.local/bin   # also write a `dotagents` command on PATH
+dotagents init --dry-run                # show what would happen
+dotagents init --force                  # replace AGENTS.md/CLAUDE.md wholesale (backed up)
+```
+
+`--from <path-or-uri>` selects the *base* source for a `pip install`-only environment
+(a git checkout dir, `file:`, `http(s):`, `zip:`, `sftp:`, or `s3:` URI via
+`pip install "dotagents-cli[uri]"`); `init`'s base ships inside the package, so it needs no
+`--from`.
+
+Overlays beyond the base are managed by name with `dotagents overlays add <name>` — it
+installs into `<scope>/.agents/overlays/<name>/` (discoverable) and publishes the
+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.
+
+```bash
+dotagents overlays add python flows        # install into the scope, publish skills, merge D59 rules/routing
+dotagents overlays list                    # installed (discovered) + available (from source)
+dotagents overlays sync 'py*'              # refresh installed overlays matching a glob, resync their skills
+dotagents overlays remove python           # delete the overlay dir + unpublish its skills
+```
+
+Scope is **project** by default (`<project>/.agents/`, when run inside one) or **user**
+with `-g`/`--global` (`~/.agents/`, the configurable store). Each overlay installs as a
+directory (kept, discoverable), its `routing`/`rules` merge additively into `AGENTS.md`'s
+managed block, and its `skills/<name>/` are symlinked (or `--copy`'d, for Windows /
+no-symlink) into the shared `<scope>/.agents/skills/` so every agent sees the same skills.
+`add`/`sync` are additive and never clobber a file you hand-edited inside an installed
+overlay. Removing an overlay deletes only its dir and unpublishes only the skills **it**
+published; its lines in `AGENTS.md`'s managed block are not auto-pruned (a warning points
+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
+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
+`--no-setup`. The contract for authors:
+
+- **Idempotent** — safe to run on every `add`/`sync`; check-then-act, never blindly append.
+- **cwd** is the installed overlay dir (`<scope>/.agents/overlays/<name>/`), so reference
+  your own files by relative path.
+- **Env** carries `AGENTS_HOME` (the resolved store path — never hardcode
+  `~/.agents`) and `AGENTS_OVERLAY_DIR` (your own installed dir).
+- A **non-zero exit fails the install** with a clear error (not a silent skip). For any
+  outward or irreversible action the *script* must confirm first — the runner invokes a
+  script you chose to install; it does not second-guess it.
+
+**Downloadable `dotagents.pyz`** — a self-contained zipapp with `duho`/
+`pathlib_next` and the required `tools/` bundled in, so it needs no `pip install`:
+
+```bash
+python -m dotagents build-pyz --out dist/dotagents.pyz   # build it (needs this repo checkout)
+python dist/dotagents.pyz init --bin-dir ~/.local/bin    # lay down the base + a `dotagents` command, offline
+```
+
+Then wire your runner to it — e.g. Claude Code: put `@AGENTS.md` in
+`~/.claude/CLAUDE.md`... which is exactly what the installed `CLAUDE.md` contains.
+
+**Or let your agent do it:** point it at this repo and say —
+> Read README.md, run `python install.py init && python install.py overlays add flows -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
+python tools/audit.py --root .                  # validate THIS REPO's layout (CI tooling)
+python tools/audit.py --check-templates --root .  # + template checks (needs 3.11+)
+```
+
+## Customize
+
+Fork it — that's the point. Keep the base `AGENTS.md` small (the audit warns past
+~2.5KB); put opinionated content in overlays. Your `~/.agents/dotagents/DECISIONS.md`
+is *your* private, per-install design log (index + `decisions/` files) — installed
+empty, edited directly, never distributed. This repo follows the same rule: its own
+design log and all working material live in an **untracked** `.agents/dotagents/`, never
+committed — so what's public here is only the CLI, the base overlay, and the opt-in
+overlays. If you fork, keep the tracked surface free of personal paths and private
+project names. `dotagents audit` validates config *structure* only; personal-leak
+scanning (machine paths, private plan names, session trailers) is a separate,
+personal `leak-check` tool you run locally before a push — it lives in your private
+`.agents/`, not shipped in this repo.
+
+## Documentation
+
+Full docs — install modes, the overlay model, the CLI command surface, private sync,
+authoring your own overlays and commands, and the API reference — are at
+[jose-pr.github.io/dotagents](https://jose-pr.github.io/dotagents/).
+
+## License
+
+MIT — see [LICENSE](LICENSE).