dotagents-cli 0.3.0__py3-none-any.whl

dotagents/cli/overlays.py

@@ -0,0 +1,366 @@
+"""`dotagents overlays` -- add / remove / list / sync, with skills sync.
+
+Self-contained block (own module deps in `_scope.py` / `_skills.py` /
+`_overlays.py`); the only umbrella touch is registering `Overlays` on
+`Dotagents._subcommands_` (in `cli/__init__.py`). Discover-not-track: installed
+overlays are the dirs under `<scope>/overlays/`.
+"""
+
+import shutil
+from pathlib import Path
+from typing import Optional
+
+from duho import Cli, Cmd, LoggingArgs
+
+from dotagents.cli._common import (
+    BASE_ROOT,
+    _installed_overlay_dirs,
+    _run_overlay_setup,
+)
+
+
+class OverlayAdd(LoggingArgs, Cmd):
+    """Install overlay(s) by name into a scope, and publish their skills.
+
+    Resolves each ``<name>`` against the source (``--source`` /
+    ``$AGENTS_OVERLAYS_SRC``, default the bundled ``overlays/``), copies it into
+    ``<scope>/.agents/overlays/<name>/`` (discoverable), merges its D59
+    routing/rules into the installed ``AGENTS.md`` managed block (additive), and
+    publishes its ``skills/`` into the shared ``<scope>/.agents/skills/`` so every
+    agent sees them. ``--copy`` mirrors skills as real dirs instead of symlinks
+    (Windows / no-symlink)."""
+
+    _parsername_ = "add"
+
+    name: "list[str]" = []
+    "Overlay name(s) to install (resolved against the source)."
+    ("name",)
+
+    source: Optional[str] = None
+    "Overlay source directory (default: $AGENTS_OVERLAYS_SRC or the bundled overlays/)."
+    ("--source",)
+
+    global_scope: bool = False
+    "Install into the user scope (~/.agents) instead of the project scope."
+    ("--global", "-g")
+
+    agents_dir: Path = Path.home() / ".agents"
+    "User-scope agents dir (default: ~/.agents)."
+    ("--agents-dir",)
+
+    copy: bool = False
+    "Copy skills into the shared dir instead of symlinking (no-symlink fallback)."
+    ("--copy",)
+
+    no_setup: bool = False
+    "Skip running an overlay's idempotent `setup` script after install."
+    ("--no-setup",)
+
+    dry_run: bool = False
+    "Show what would happen without touching anything."
+    ("--dry-run",)
+
+    def __call__(self) -> int:
+        from dotagents import _overlays, _scope, _skills
+
+        if not self.name:
+            self._logger_.warning("no overlay name given; nothing to add")
+            return 0
+        # Validate + normalize each requested name with the shared overlay-name
+        # rule (D84), so `add My_Overlay` and `add my-overlay` resolve the same
+        # overlay and a bad name (`.git`, `README.md`, `2fast`) is rejected up
+        # front rather than creating a junk dir under overlays/.
+        names = []
+        for raw in self.name:
+            if not _scope.is_valid_overlay_name(raw):
+                raise SystemExit(
+                    "error: %r is not a valid overlay name (must start with a "
+                    "letter, then letters/digits/_/-)" % raw
+                )
+            names.append(_scope.normalize_overlay_name(raw))
+
+        source = _scope.resolve_source(self.source)
+        scope = _scope.resolve_scope(self.global_scope, agents_dir=self.agents_dir)
+        self._logger_.info("scope: %s (%s)", scope.level, scope.agents_root)
+        agents_md = scope.agents_root / "AGENTS.md"
+
+        for name in names:
+            overlay_src = source.overlay_dir(name)
+            dest_dir = scope.overlay_dir(name)
+            copied, skipped, lines = _overlays.install_overlay_dir(
+                overlay_src, dest_dir, self.dry_run
+            )
+            for line in lines:
+                self._logger_.info(line)
+            self._logger_.info(
+                "overlay %s: %d file(s) installed, %d skipped%s",
+                name, copied, skipped, " [dry-run]" if self.dry_run else "",
+            )
+            if not self.dry_run:
+                published = _skills.publish_overlay_skills(
+                    overlay_src, scope.shared_skills_dir, copy=self.copy,
+                    logger=self._logger_,
+                )
+                if published:
+                    self._logger_.info("published %d skill(s) from %s", published, name)
+            rc = _run_overlay_setup(
+                dest_dir, name, scope=scope, no_setup=self.no_setup,
+                dry_run=self.dry_run, logger=self._logger_,
+            )
+            if rc:
+                raise SystemExit(
+                    "error: setup for overlay %r failed (exit %d)" % (name, rc)
+                )
+
+        # Recompose the whole managed block from the pristine base over ALL installed
+        # overlays in (priority, name) order (plan 02 / D68), so a high-priority overlay
+        # lands last regardless of when it was added -- not merely appended after
+        # whatever was already in the block.
+        overlay_dirs = _installed_overlay_dirs(
+            scope, source, adding=names, dry_run=self.dry_run
+        )
+        base_block = (BASE_ROOT / "AGENTS.md").read_text(encoding="utf-8")
+        if _overlays.recompose_overlay_block(
+            agents_md, base_block, overlay_dirs, self.dry_run, self._logger_
+        ):
+            self._logger_.info("recomposed overlay rules/routing in AGENTS.md")
+
+        if self.dry_run:
+            self._logger_.info("dry-run: no files were written")
+        return 0
+
+
+class OverlayRemove(LoggingArgs, Cmd):
+    """Remove installed overlay(s): delete the overlay dir + unpublish its skills.
+
+    Deletes only ``<scope>/.agents/overlays/<name>/`` and unpublishes only the
+    skills that overlay published (matched to its own ``skills/`` source) -- never a
+    file outside the overlay dir, never another overlay's skill. Broken skill
+    symlinks are then swept. The overlay's D59 rules/routing in ``AGENTS.md`` are
+    **not** auto-unmerged (a clean managed-block un-merge is deferred, see the
+    decision); a warning points at the manual prune when the overlay carried any."""
+
+    _parsername_ = "remove"
+
+    name: "list[str]" = []
+    "Overlay name(s) to remove."
+    ("name",)
+
+    global_scope: bool = False
+    "Operate on the user scope (~/.agents) instead of the project scope."
+    ("--global", "-g")
+
+    agents_dir: Path = Path.home() / ".agents"
+    "User-scope agents dir (default: ~/.agents)."
+    ("--agents-dir",)
+
+    dry_run: bool = False
+    "Show what would happen without touching anything."
+    ("--dry-run",)
+
+    def __call__(self) -> int:
+        from dotagents import _overlays, _scope, _skills
+
+        if not self.name:
+            self._logger_.warning("no overlay name given; nothing to remove")
+            return 0
+        scope = _scope.resolve_scope(self.global_scope, agents_dir=self.agents_dir)
+        self._logger_.info("scope: %s (%s)", scope.level, scope.agents_root)
+
+        for name in self.name:
+            overlay_dir = scope.overlay_dir(name)
+            if not overlay_dir.is_dir():
+                self._logger_.warning("overlay %r not installed at %s", name, overlay_dir)
+                continue
+            manifest = _overlays.read_manifest(overlay_dir)
+            has_rules = bool(manifest["routing"] or manifest["rules"])
+            if not self.dry_run:
+                removed = _skills.remove_overlay_skills(
+                    overlay_dir, scope.shared_skills_dir, logger=self._logger_
+                )
+                if removed:
+                    self._logger_.info("unpublished %d skill(s) from %s", removed, name)
+                shutil.rmtree(str(overlay_dir))
+            self._logger_.info(
+                "removed overlay %s (%s)%s",
+                name, overlay_dir, " [dry-run]" if self.dry_run else "",
+            )
+            if has_rules:
+                self._logger_.warning(
+                    "overlay %s contributed rules/routing to AGENTS.md; those are "
+                    "NOT auto-removed -- prune its lines from the managed block by "
+                    "hand (or re-run `dotagents install` to regenerate it).", name,
+                )
+
+        if self.dry_run:
+            self._logger_.info("dry-run: no files were written")
+        return 0
+
+
+class OverlayList(LoggingArgs, Cmd):
+    """List overlays: those installed in the scope, and those available from source.
+
+    ``installed`` is discovered by presence under ``<scope>/.agents/overlays/``; no
+    registry file. ``available`` is what the source offers. ``--json`` emits both as
+    a machine-readable object."""
+
+    _parsername_ = "list"
+
+    source: Optional[str] = None
+    "Overlay source directory (default: $AGENTS_OVERLAYS_SRC or the bundled overlays/)."
+    ("--source",)
+
+    global_scope: bool = False
+    "List the user scope (~/.agents) instead of the project scope."
+    ("--global", "-g")
+
+    agents_dir: Path = Path.home() / ".agents"
+    "User-scope agents dir (default: ~/.agents)."
+    ("--agents-dir",)
+
+    json: bool = False
+    "Emit JSON instead of plain text."
+    ("--json",)
+
+    def __call__(self) -> int:
+        import json as _json
+
+        from dotagents import _scope
+
+        scope = _scope.resolve_scope(self.global_scope, agents_dir=self.agents_dir)
+        installed = _scope.discover_overlays(scope)
+        try:
+            available = _scope.resolve_source(self.source).available()
+        except SystemExit:
+            available = []
+
+        if self.json:
+            print(_json.dumps({
+                "scope": scope.level,
+                "root": str(scope.overlay_root),
+                "installed": installed,
+                "available": available,
+            }, indent=2))
+            return 0
+
+        self._logger_.info("scope: %s (%s)", scope.level, scope.overlay_root)
+        print("installed (%s):" % scope.level)
+        if installed:
+            for n in installed:
+                print("  %s" % n)
+        else:
+            print("  (none)")
+        print("available (source):")
+        if available:
+            for n in available:
+                mark = " *" if n in installed else ""
+                print("  %s%s" % (n, mark))
+        else:
+            print("  (none)")
+        return 0
+
+
+class OverlaySync(LoggingArgs, Cmd):
+    """Refresh installed overlays from source, and resync their skills.
+
+    Re-applies each installed overlay (additive: new files land, hand-edits stay),
+    re-merges its rules/routing, and refreshes its published skills. An optional
+    ``<glob>`` filters which installed overlays to sync (``sync 'py*'``)."""
+
+    _parsername_ = "sync"
+
+    pattern: Optional[str] = None
+    "Glob over installed overlay names to sync (default: all)."
+    ("pattern",)
+
+    source: Optional[str] = None
+    "Overlay source directory (default: $AGENTS_OVERLAYS_SRC or the bundled overlays/)."
+    ("--source",)
+
+    global_scope: bool = False
+    "Sync the user scope (~/.agents) instead of the project scope."
+    ("--global", "-g")
+
+    agents_dir: Path = Path.home() / ".agents"
+    "User-scope agents dir (default: ~/.agents)."
+    ("--agents-dir",)
+
+    copy: bool = False
+    "Copy skills into the shared dir instead of symlinking (no-symlink fallback)."
+    ("--copy",)
+
+    no_setup: bool = False
+    "Skip running each overlay's idempotent `setup` script after sync."
+    ("--no-setup",)
+
+    dry_run: bool = False
+    "Show what would happen without touching anything."
+    ("--dry-run",)
+
+    def __call__(self) -> int:
+        from dotagents import _overlays, _scope, _skills
+
+        scope = _scope.resolve_scope(self.global_scope, agents_dir=self.agents_dir)
+        source = _scope.resolve_source(self.source)
+        installed = _scope.discover_overlays(scope)
+        names = _scope.filter_names(installed, self.pattern)
+        if not names:
+            self._logger_.info(
+                "no installed overlays%s to sync",
+                "" if self.pattern in (None, "*") else " matching %r" % self.pattern,
+            )
+            return 0
+        self._logger_.info("scope: %s (%s)", scope.level, scope.agents_root)
+        agents_md = scope.agents_root / "AGENTS.md"
+
+        for name in names:
+            try:
+                overlay_src = source.overlay_dir(name)
+            except SystemExit:
+                self._logger_.warning("overlay %r not in source; skipping", name)
+                continue
+            dest_dir = scope.overlay_dir(name)
+            copied, skipped, lines = _overlays.install_overlay_dir(
+                overlay_src, dest_dir, self.dry_run
+            )
+            self._logger_.info(
+                "synced %s: %d new file(s), %d unchanged%s",
+                name, copied, skipped, " [dry-run]" if self.dry_run else "",
+            )
+            if not self.dry_run:
+                _skills.resync_overlay_skills(
+                    overlay_src, scope.shared_skills_dir, logger=self._logger_
+                )
+            rc = _run_overlay_setup(
+                dest_dir, name, scope=scope, no_setup=self.no_setup,
+                dry_run=self.dry_run, logger=self._logger_,
+            )
+            if rc:
+                raise SystemExit(
+                    "error: setup for overlay %r failed (exit %d)" % (name, rc)
+                )
+
+        # Recompose the managed block over ALL installed overlays in (priority, name)
+        # order (plan 02 / D68) -- not just the pattern-matched subset synced above, so
+        # priority ordering holds across the full installed set.
+        overlay_dirs = _installed_overlay_dirs(scope, source, dry_run=self.dry_run)
+        base_block = (BASE_ROOT / "AGENTS.md").read_text(encoding="utf-8")
+        if _overlays.recompose_overlay_block(
+            agents_md, base_block, overlay_dirs, self.dry_run, self._logger_
+        ):
+            self._logger_.info("recomposed overlay rules/routing in AGENTS.md")
+
+        if self.dry_run:
+            self._logger_.info("dry-run: no files were written")
+        return 0
+
+
+class Overlays(LoggingArgs, Cli):
+    """Manage opt-in overlays by name: add / remove / list / sync (+ skills sync)."""
+
+    _parsername_ = "overlays"
+    _subcommands_ = [OverlayAdd, OverlayRemove, OverlayList, OverlaySync]
+
+    def __call__(self) -> int:
+        self._logger_.info("pick an overlays subcommand: add, remove, list, sync")
+        return 0

dotagents_cli-0.3.0.dist-info/METADATA

@@ -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).