dotagents-cli 0.7.0__tar.gz → 0.7.1__tar.gz

{dotagents_cli-0.7.0 → dotagents_cli-0.7.1}/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-10-01
+
+### Added
+
+- Your own additions to an installed overlay's file live at the same path under the
+  store root (`~/.agents/kb/RUST.md` for the rust overlay's `kb/RUST.md`, or
+  `<project>/.agents/kb/RUST.md`), where `overlays sync` never touches them. The
+  base `AGENTS.md` tells agents to read them alongside the overlay's file, and
+  `dotagents context` lists the ones it finds (JSON: `local_additions`).
+
 ## [0.7.0] - 2026-10-01
 
 ### Changed
@@ -1362,7 +1372,8 @@ Patch release: the PATH/POSIX-conversion fix above (the only change since 0.3.0)
   affected module sources (`dotagents.cli`, `duho.presets`) to extracted temp files
   before dispatch; a no-op for a plain install.
 
-[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.7.1...HEAD
+[0.7.1]: https://github.com/jose-pr/dotagents/compare/v0.7.0...v0.7.1
 [0.7.0]: https://github.com/jose-pr/dotagents/compare/v0.6.3...v0.7.0
 [0.6.3]: https://github.com/jose-pr/dotagents/compare/v0.6.2...v0.6.3
 [0.6.2]: https://github.com/jose-pr/dotagents/compare/v0.6.1...v0.6.2

{dotagents_cli-0.7.0 → dotagents_cli-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.7.0
+Version: 0.7.1
 Summary: The dotagents CLI: install and manage a portable ~/.agents config for AI coding agents
 Project-URL: Homepage, https://github.com/jose-pr/dotagents/
 Project-URL: Repository, https://github.com/jose-pr/dotagents

{dotagents_cli-0.7.0 → dotagents_cli-0.7.1}/docs/guide/commands.md

@@ -216,7 +216,11 @@ Assembles the effective context an agent should load — the overlay `CONTEXT.md
 and the project root's own `AGENTS.md` / `AGENTS.local.md` — minus whatever the harness already loads by itself (for Claude Code, whatever its
 `CLAUDE.md` files really `@`-include) — and prints it to **stdout** by default
 (POSIX convention); pass a path to write a file, or `--write-agent` to merge it into
-each agent's own instruction file.
+each agent's own instruction file. It ends with the skills on offer and, when there are
+any, your **local additions to overlay files** — a store file at the same path as an
+overlay's (`~/.agents/kb/RUST.md` for the rust overlay's `kb/RUST.md`; see
+[Overlays](overlays.md)); `--format json` carries both as their own keys (`skills`,
+`local_additions`).
 
 ```bash
 dotagents context                              # print the active agent's context to stdout

{dotagents_cli-0.7.0 → dotagents_cli-0.7.1}/docs/guide/overlays.md

@@ -79,8 +79,17 @@ up under `<store>/install_backup/` first. What the `.gitignore` / `.ignore` at t
 overlay's root match (an ignore file in a subdirectory is just a file it ships), and
 tool caches, belong to the install (a setup script's output, local
 state) and are left alone; `--prune` clears them too. A `requires` added upstream is
-installed. An installed overlay is upstream's copy, not a place for your edits: keep
-those in your own files (a `kb/` file, `AGENTS.local.md`).
+installed. An installed overlay is upstream's copy, not a place for your edits.
+
+### Your additions to an overlay's files
+
+Put your own text for an overlay file at the **same path under the store root**: an
+addition to the rust overlay's `kb/RUST.md` goes in `~/.agents/kb/RUST.md` (or
+`<project>/.agents/kb/RUST.md` for one project). `sync` never touches it, and agents
+read it alongside the overlay's file, winning on conflict: the base `AGENTS.md` tells
+them to, and `dotagents context` lists every addition it finds (for each `.md` an
+overlay ships in a subdirectory other than `skills/`). Private names, local tool paths
+and links into your own notes belong there, never in the overlay.
 
 Removing an overlay deletes only its directory and unpublishes only the skills **it**
 published (a copy the user edited is left alone). Its lines in `AGENTS.md`'s managed

{dotagents_cli-0.7.0 → dotagents_cli-0.7.1}/src/dotagents/AGENTS.md

@@ -433,7 +433,8 @@ API:
   `Overlay.sort_key`, then contract-A `AGENTS.md` (every store and the project root)
   and `AGENTS.local.md` (project store and project root), each prefixed
   `<!-- Source: <path> -->`. Then a skills listing (`- **name** (`<SKILL.md>`):
-  description`, from each skill's leading frontmatter; a project skill wins).
+  description`, from each skill's leading frontmatter; a project skill wins), then
+  a "Local additions to overlay files" section when `local_additions` finds any.
   `<PROJECT_ROOT>` and `<NAME_OVERLAY_ROOT>` placeholders expand; with
   `expand_vars` so do `$NAME_OVERLAY_ROOT` / `${NAME_OVERLAY_ROOT}`. `inline`
   appends the on-demand `.md` files the sources reference, each resolved against
@@ -441,7 +442,13 @@ API:
   system source never into the project).
 - `assemble_context_data(agent, scope, *, inline=False, expand_vars=True) -> dict`
   — `{"agent", "harness", "sources", "context", "skills": [{"name",
-  "description", "path"}]}`; `context` without the skills listing.
+  "description", "path"}], "local_additions": [{"overlay_file", "local": [...]}]}`;
+  `context` without the skills and local-additions listings.
+- `local_additions(scope) -> list[tuple[Path, list[Path]]]` — the user's own
+  additions to installed overlay files: for each `.md` an overlay in `scope.overlays`
+  ships in a subdirectory other than `skills/`, every store's file at the same
+  relative path (`<store>/kb/RUST.md` for the overlay's `kb/RUST.md`), in
+  `scope.stores` order. A store's root files never match.
 
 ## `dotagents._agents`
 

{dotagents_cli-0.7.0 → dotagents_cli-0.7.1}/src/dotagents/__init__.py

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

{dotagents_cli-0.7.0 → dotagents_cli-0.7.1}/src/dotagents/_context.py

@@ -309,6 +309,44 @@ def _get_skills_listing(scope: _scope.Scope) -> str:
     return "\n\n## Available Skills (Opt-in)\n" + "\n".join(lines) + "\n"
 
 
+def local_additions(scope: _scope.Scope) -> "list[tuple[Path, list[Path]]]":
+    """The user's own additions to installed overlay files: for each ``.md``
+    an overlay ships in a subdirectory (``kb/``, ``flows/``, ``rules/`` ... --
+    not ``skills/``, whose published copies sit at the same path in a store),
+    every store's file at the same relative path (``~/.agents/kb/RUST.md`` for
+    an overlay's ``kb/RUST.md``), in store order. An overlay file is upstream's
+    copy, replaced by ``overlays sync``; the addition is where the user's own
+    text lives. A store's root files (``AGENTS.md``, ``env.py``) never match:
+    only a file in a subdirectory counts."""
+    stores = list(scope.stores)
+    out: "list[tuple[Path, list[Path]]]" = []
+    for overlay in scope.overlays:
+        for path in overlay.files():
+            rel = path.relative_to(overlay.path)
+            if path.suffix.lower() != ".md" or len(rel.parts) < 2 or rel.parts[0] == "skills":
+                continue
+            found = [store / rel for store in stores if (store / rel).is_file()]
+            if found:
+                out.append((path, found))
+    return out
+
+
+def _get_local_additions_listing(scope: _scope.Scope) -> str:
+    """The local additions (:func:`local_additions`) as a markdown section, or ''."""
+    additions = local_additions(scope)
+    if not additions:
+        return ""
+    lines = [
+        "- `%s` -- also read %s" % (path, ", ".join("`%s`" % p for p in found))
+        for path, found in additions
+    ]
+    return (
+        "\n\n## Local additions to overlay files\n"
+        "The user's own additions: read each with the overlay file it extends; it wins on conflict.\n"
+        + "\n".join(lines) + "\n"
+    )
+
+
 def _resolve_and_filter_sources(
     agent: _agents.Agent, scope: _scope.Scope
 ) -> "tuple[list[tuple[str, Path, Path | None]], list[Path]]":
@@ -424,6 +462,7 @@ def assemble_context(
     if not source_paths:
         return ""
     text += _get_skills_listing(scope)
+    text += _get_local_additions_listing(scope)
     return text
 
 
@@ -440,11 +479,12 @@ def assemble_context_data(
           "sources": [<absolute source path>, ...],  # after harness subtraction
           "context": <assembled markdown text, minus the skills listing>,
           "skills": [{"name": ..., "description": ..., "path": <SKILL.md>}, ...],
+          "local_additions": [{"overlay_file": ..., "local": [<path>, ...]}, ...],
         }
     ``context`` is the same assembled(+inlined, with ``inline=True``) text the
-    markdown format emits, but WITHOUT the skills listing appended -- skills are
-    their own structured field so a consumer can render them separately and
-    keep the opt-in distinction."""
+    markdown format emits, but WITHOUT the skills and local-additions listings
+    appended -- both are their own structured fields so a consumer can render
+    them separately."""
     text, source_paths = _assemble(agent, scope, inline, expand_vars)
 
     skills = [
@@ -457,4 +497,8 @@ def assemble_context_data(
         "sources": source_paths,
         "context": text,
         "skills": skills,
+        "local_additions": [
+            {"overlay_file": str(path), "local": [str(p) for p in found]}
+            for path, found in local_additions(scope)
+        ],
     }

{dotagents_cli-0.7.0 → dotagents_cli-0.7.1}/src/dotagents/_overlay/dotagents/templates/AGENTS.md

@@ -16,6 +16,12 @@ Startup: annotate that you read `{{AGENTS_MD}}`.
   config). These files say what lives there and how to work in it, so reading them
   first is cheaper than rediscovering it from the source. How `.agents/` is
   populated — real directory, symlink, committed or not — is yours to decide.
+- **Local additions to overlay files**: an overlay file (`$<NAME>_OVERLAY_ROOT/<path>`)
+  is upstream's copy, and `dotagents overlays sync` replaces it. The user's own
+  additions live at the same `<path>` under this config directory and the project's
+  `.agents/`: when you read an overlay file, read those too — they extend it and win on
+  conflict (`dotagents context` lists the ones it finds). Never write user-specific text
+  into an overlay file; put it there.
 - **Global-config misses**: if these instructions caused a mistake or rework, or you
   have an improvement idea, record it and move on — don't edit the config:
   `dotagents findings add -g "<one line>" -b "<what happened, evidence>"`. Read the

dotagents_cli-0.7.1/tests/test_local_additions.py

@@ -0,0 +1,86 @@
+"""The user's own additions to installed overlay files: a store file at the
+same relative path as an overlay's (``~/.agents/kb/RUST.md`` for the rust
+overlay's ``kb/RUST.md``). `overlays sync` replaces the overlay's copy, so this
+is where the user's text lives; `dotagents context` lists what it finds, and
+the base AGENTS.md tells every agent to read them."""
+import json
+
+from dotagents import _agents, _context
+from dotagents._resources import BASE_PROJECT_TEMPLATE, BASE_ROOT, base_agents_text
+from dotagents._scope import Scope
+
+
+def _write(path, text="x\n"):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+
+
+def _world(tmp_path):
+    user = tmp_path / "user"
+    project = tmp_path / "proj"
+    rust = user / "overlays" / "rust"
+    _write(rust / "overlay.toml", 'name = "rust"\n')
+    _write(rust / "CONTEXT.md", "RUST-CONTEXT\n")
+    _write(rust / "kb" / "RUST.md", "upstream rust\n")
+    _write(rust / "kb" / "NOTES.md", "no addition for this one\n")
+    _write(rust / "flows" / "deep" / "STEP.md", "upstream step\n")
+    _write(rust / "skills" / "rs" / "SKILL.md", "---\nname: rs\ndescription: d\n---\n")
+    _write(rust / "kb" / "data.json", "{}\n")
+    _write(rust / "AGENTS.md", "an overlay-root file\n")
+    _write(user / "AGENTS.md", "# user\n")
+    _write(user / "kb" / "RUST.md", "my own note\n")
+    _write(user / "flows" / "deep" / "STEP.md", "my step\n")
+    _write(user / "skills" / "rs" / "SKILL.md", "---\nname: rs\ndescription: d\n---\n")  # a published copy
+    _write(user / "kb" / "data.json", "{}\n")
+    _write(project / ".agents" / "kb" / "RUST.md", "a project note\n")
+    return user, project
+
+
+def _scope(user, project, global_scope=False):
+    return Scope.of(agents_dir=user, project_root=project, global_scope=global_scope)
+
+
+def test_additions_are_matched_by_relative_path_in_every_store(tmp_path):
+    user, project = _world(tmp_path)
+    found = {p.relative_to(user / "overlays" / "rust").as_posix(): [q for q in qs]
+             for p, qs in _context.local_additions(_scope(user, project))}
+    assert sorted(found) == ["flows/deep/STEP.md", "kb/RUST.md"], (
+        "only .md files in a subdirectory, never skills/ (published copies) or the root"
+    )
+    assert found["kb/RUST.md"] == [user / "kb" / "RUST.md", project / ".agents" / "kb" / "RUST.md"]
+    user_only = {p.name for p, _ in _context.local_additions(_scope(user, project, True))}
+    assert user_only == {"RUST.md", "STEP.md"}
+
+
+def test_context_lists_them_and_json_carries_them(tmp_path):
+    user, project = _world(tmp_path)
+    codex = _agents.CodexAgent()
+    text = _context.assemble_context(codex, _scope(user, project))
+    assert "## Local additions to overlay files" in text
+    assert str(user / "kb" / "RUST.md") in text and str(project / ".agents" / "kb" / "RUST.md") in text
+    assert "my own note" not in text, "listed, not inlined"
+    data = _context.assemble_context_data(codex, _scope(user, project))
+    assert "Local additions" not in data["context"]
+    entries = {e["overlay_file"]: e["local"] for e in data["local_additions"]}
+    assert entries[str(user / "overlays" / "rust" / "kb" / "RUST.md")] == [
+        str(user / "kb" / "RUST.md"), str(project / ".agents" / "kb" / "RUST.md"),
+    ]
+    json.dumps(data)
+
+
+def test_no_section_without_additions(tmp_path):
+    user = tmp_path / "user"
+    _write(user / "overlays" / "rust" / "overlay.toml", 'name = "rust"\n')
+    _write(user / "overlays" / "rust" / "CONTEXT.md", "RUST-CONTEXT\n")
+    _write(user / "overlays" / "rust" / "kb" / "RUST.md", "upstream\n")
+    _write(user / "AGENTS.md", "# user\n")
+    text = _context.assemble_context(_agents.CodexAgent(), Scope.of(agents_dir=user, global_scope=True))
+    assert "RUST-CONTEXT" in text and "Local additions" not in text
+
+
+def test_the_base_rule_is_in_the_user_block_only(tmp_path):
+    user_block = base_agents_text(BASE_ROOT, tmp_path)
+    assert "**Local additions to overlay files**" in user_block
+    assert "`dotagents context` lists the ones it finds" in user_block
+    project = (BASE_ROOT / BASE_PROJECT_TEMPLATE).read_text(encoding="utf-8")
+    assert "Local additions" not in project, "a project session reads the user block too"