agent-skilltree 0.2.1__tar.gz → 0.3.0__tar.gz

{agent_skilltree-0.2.1/src/agent_skilltree.egg-info → agent_skilltree-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-skilltree
-Version: 0.2.1
+Version: 0.3.0
 Summary: A coordinate-addressed tree of agent skill dirs wired by Read-tool breadcrumbs, with programmatic validation.
 Author: Isaac Wostrel-Rubin
 License: MIT
@@ -82,6 +82,8 @@ One CLI for the whole skill-substrate toolkit — `skilltree <command> …`:
 | `tree <root>` | show the coordinate tree on disk (every node by its `<coord>-<name>` address) |
 | `map <folder> [--write]` | render a flat folder into **one** coordinate-addressed `CLAUDE.md` (Folder Map + addressable Index + branch summaries) — progressive disclosure over a flat pile |
 | `search <folder> <query> [--scope <coord>]` | FTS5/BM25 over **any** folder; `--scope` restricts to a coordinate subtree when the folder carries skilltree coordinates (a plain folder = coordinate-free search) |
+| `fold <framework_dir> --into <node> --tree <root>` | **bind** a framework (its skill dir) into a volume node's `## Frameworks` tome table — idempotent, one row per framework; the manifest is the source of truth and the node's SKILL.md is regenerated from it |
+| `project <root> <target> [--policy flat\|progressive] [--link absolute\|relative] [--node N]` | **deploy** a tree into a skills dir as symlinks: `progressive` surfaces root + first-layer branches (the former `link_tree`); `flat` projects a volume's tome rows + holder so every held framework auto-discovers top-level (the former nomicon-atomize) |
 | `cohere <root>` | report drift between the on-disk tree and its coherent shape |
 | `emit <root> [--root-forest]` | re-cohere in place; `--root-forest` tree-ifies a bare forest (lossless, journaled) |
 | `unemit <root>` | reverse the last `emit`, byte-for-byte |
@@ -128,6 +130,26 @@ Two papers document the project:
 
 ## Changelog
 
+### v0.3.0 — 2026-07-09
+- **The tome bind ops (SkillVolume/SkillTome).** A node can now HOLD frameworks: `TreeNode.frameworks`
+  rows live in the manifest and render as a generated `## Frameworks` pointer-table (`| Framework |
+  What it's for | Framework skill |`) on the node's SKILL.md — regenerated by both `materialize` and
+  the in-place re-cohere (`emit`), so a folded table can never be wiped or drift. New ops:
+  **`fold(framework_dir, into=..., tree_root=...)`** (bind a framework into a volume — idempotent, one
+  row per framework, surgical single-node rewrite) and **`project(tree, target, policy={progressive,flat},
+  link={absolute,relative}, node=...)`** — ONE deployment op unifying the top-level symlink surfacing
+  (`link_tree` is now a thin wrapper) with the flat auto-discoverable projection of a volume's held
+  frameworks (tome rows + holder, self-clobber-guarded, relative-link-capable). `validate` grew the
+  **tome-table round-trip**: manifest rows must appear in the table, every row's target must resolve,
+  undeclared table rows warn. CLI: `skilltree fold [--relative]`, `skilltree project`. **Repo-portable
+  tomes:** `fold(relative=True)` stores rows relative to the holder dir, so a committed tome validates
+  and projects from ANY checkout — the CI flow is `emit` (localize the breadcrumbs) then `validate`.
+  Fixed `--version` (the click probe needed the `agent-skilltree` distribution name). Suite →
+  **70 passing** (+11 tome tests).
+- Vocabulary: a branch holding frameworks is a **SkillVolume**; the overall corpus is a **SkillTome**
+  ("nomicon" is the legacy alias). The table heading stays `## Frameworks` — existing table parsers
+  keep working (verified against the reference atomizer end-to-end).
+
 ### v0.2.0 — 2026-06-18
 - **Folded the `skillmap` / `foldersearch` / `skillsearch` seedlings into skilltree as subcommands — one product.** `skilltree map <folder> [--write]` renders a flat folder into one coordinate-addressed `CLAUDE.md`, using skilltree's **own** coordinate code (`assign_coords`/`skill_name` from `model.py`; the vendored copy is gone). `skilltree search <folder> <query> [--scope <coord>]` is **one** FTS5/BM25 engine over any folder — coordinate-free on a plain folder, coordinate-subtree-scoped when the folder carries skilltree coordinates (`foldersearch` + `skillsearch` unified; the `--scope` flag is the only difference). Added the `tree` view command. The `<coord>-<name>` frontmatter and the Read-breadcrumb format are preserved (backward compatible). Suite grew 56 → **62 tests**.
 

{agent_skilltree-0.2.1 → agent_skilltree-0.3.0}/README.md

@@ -68,6 +68,8 @@ One CLI for the whole skill-substrate toolkit — `skilltree <command> …`:
 | `tree <root>` | show the coordinate tree on disk (every node by its `<coord>-<name>` address) |
 | `map <folder> [--write]` | render a flat folder into **one** coordinate-addressed `CLAUDE.md` (Folder Map + addressable Index + branch summaries) — progressive disclosure over a flat pile |
 | `search <folder> <query> [--scope <coord>]` | FTS5/BM25 over **any** folder; `--scope` restricts to a coordinate subtree when the folder carries skilltree coordinates (a plain folder = coordinate-free search) |
+| `fold <framework_dir> --into <node> --tree <root>` | **bind** a framework (its skill dir) into a volume node's `## Frameworks` tome table — idempotent, one row per framework; the manifest is the source of truth and the node's SKILL.md is regenerated from it |
+| `project <root> <target> [--policy flat\|progressive] [--link absolute\|relative] [--node N]` | **deploy** a tree into a skills dir as symlinks: `progressive` surfaces root + first-layer branches (the former `link_tree`); `flat` projects a volume's tome rows + holder so every held framework auto-discovers top-level (the former nomicon-atomize) |
 | `cohere <root>` | report drift between the on-disk tree and its coherent shape |
 | `emit <root> [--root-forest]` | re-cohere in place; `--root-forest` tree-ifies a bare forest (lossless, journaled) |
 | `unemit <root>` | reverse the last `emit`, byte-for-byte |
@@ -114,6 +116,26 @@ Two papers document the project:
 
 ## Changelog
 
+### v0.3.0 — 2026-07-09
+- **The tome bind ops (SkillVolume/SkillTome).** A node can now HOLD frameworks: `TreeNode.frameworks`
+  rows live in the manifest and render as a generated `## Frameworks` pointer-table (`| Framework |
+  What it's for | Framework skill |`) on the node's SKILL.md — regenerated by both `materialize` and
+  the in-place re-cohere (`emit`), so a folded table can never be wiped or drift. New ops:
+  **`fold(framework_dir, into=..., tree_root=...)`** (bind a framework into a volume — idempotent, one
+  row per framework, surgical single-node rewrite) and **`project(tree, target, policy={progressive,flat},
+  link={absolute,relative}, node=...)`** — ONE deployment op unifying the top-level symlink surfacing
+  (`link_tree` is now a thin wrapper) with the flat auto-discoverable projection of a volume's held
+  frameworks (tome rows + holder, self-clobber-guarded, relative-link-capable). `validate` grew the
+  **tome-table round-trip**: manifest rows must appear in the table, every row's target must resolve,
+  undeclared table rows warn. CLI: `skilltree fold [--relative]`, `skilltree project`. **Repo-portable
+  tomes:** `fold(relative=True)` stores rows relative to the holder dir, so a committed tome validates
+  and projects from ANY checkout — the CI flow is `emit` (localize the breadcrumbs) then `validate`.
+  Fixed `--version` (the click probe needed the `agent-skilltree` distribution name). Suite →
+  **70 passing** (+11 tome tests).
+- Vocabulary: a branch holding frameworks is a **SkillVolume**; the overall corpus is a **SkillTome**
+  ("nomicon" is the legacy alias). The table heading stays `## Frameworks` — existing table parsers
+  keep working (verified against the reference atomizer end-to-end).
+
 ### v0.2.0 — 2026-06-18
 - **Folded the `skillmap` / `foldersearch` / `skillsearch` seedlings into skilltree as subcommands — one product.** `skilltree map <folder> [--write]` renders a flat folder into one coordinate-addressed `CLAUDE.md`, using skilltree's **own** coordinate code (`assign_coords`/`skill_name` from `model.py`; the vendored copy is gone). `skilltree search <folder> <query> [--scope <coord>]` is **one** FTS5/BM25 engine over any folder — coordinate-free on a plain folder, coordinate-subtree-scoped when the folder carries skilltree coordinates (`foldersearch` + `skillsearch` unified; the `--scope` flag is the only difference). Added the `tree` view command. The `<coord>-<name>` frontmatter and the Read-breadcrumb format are preserved (backward compatible). Suite grew 56 → **62 tests**.
 

{agent_skilltree-0.2.1 → agent_skilltree-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-skilltree"
-version = "0.2.1"
+version = "0.3.0"
 description = "A coordinate-addressed tree of agent skill dirs wired by Read-tool breadcrumbs, with programmatic validation."
 readme = "README.md"
 license = { text = "MIT" }

{agent_skilltree-0.2.1 → agent_skilltree-0.3.0/src/agent_skilltree.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-skilltree
-Version: 0.2.1
+Version: 0.3.0
 Summary: A coordinate-addressed tree of agent skill dirs wired by Read-tool breadcrumbs, with programmatic validation.
 Author: Isaac Wostrel-Rubin
 License: MIT
@@ -82,6 +82,8 @@ One CLI for the whole skill-substrate toolkit — `skilltree <command> …`:
 | `tree <root>` | show the coordinate tree on disk (every node by its `<coord>-<name>` address) |
 | `map <folder> [--write]` | render a flat folder into **one** coordinate-addressed `CLAUDE.md` (Folder Map + addressable Index + branch summaries) — progressive disclosure over a flat pile |
 | `search <folder> <query> [--scope <coord>]` | FTS5/BM25 over **any** folder; `--scope` restricts to a coordinate subtree when the folder carries skilltree coordinates (a plain folder = coordinate-free search) |
+| `fold <framework_dir> --into <node> --tree <root>` | **bind** a framework (its skill dir) into a volume node's `## Frameworks` tome table — idempotent, one row per framework; the manifest is the source of truth and the node's SKILL.md is regenerated from it |
+| `project <root> <target> [--policy flat\|progressive] [--link absolute\|relative] [--node N]` | **deploy** a tree into a skills dir as symlinks: `progressive` surfaces root + first-layer branches (the former `link_tree`); `flat` projects a volume's tome rows + holder so every held framework auto-discovers top-level (the former nomicon-atomize) |
 | `cohere <root>` | report drift between the on-disk tree and its coherent shape |
 | `emit <root> [--root-forest]` | re-cohere in place; `--root-forest` tree-ifies a bare forest (lossless, journaled) |
 | `unemit <root>` | reverse the last `emit`, byte-for-byte |
@@ -128,6 +130,26 @@ Two papers document the project:
 
 ## Changelog
 
+### v0.3.0 — 2026-07-09
+- **The tome bind ops (SkillVolume/SkillTome).** A node can now HOLD frameworks: `TreeNode.frameworks`
+  rows live in the manifest and render as a generated `## Frameworks` pointer-table (`| Framework |
+  What it's for | Framework skill |`) on the node's SKILL.md — regenerated by both `materialize` and
+  the in-place re-cohere (`emit`), so a folded table can never be wiped or drift. New ops:
+  **`fold(framework_dir, into=..., tree_root=...)`** (bind a framework into a volume — idempotent, one
+  row per framework, surgical single-node rewrite) and **`project(tree, target, policy={progressive,flat},
+  link={absolute,relative}, node=...)`** — ONE deployment op unifying the top-level symlink surfacing
+  (`link_tree` is now a thin wrapper) with the flat auto-discoverable projection of a volume's held
+  frameworks (tome rows + holder, self-clobber-guarded, relative-link-capable). `validate` grew the
+  **tome-table round-trip**: manifest rows must appear in the table, every row's target must resolve,
+  undeclared table rows warn. CLI: `skilltree fold [--relative]`, `skilltree project`. **Repo-portable
+  tomes:** `fold(relative=True)` stores rows relative to the holder dir, so a committed tome validates
+  and projects from ANY checkout — the CI flow is `emit` (localize the breadcrumbs) then `validate`.
+  Fixed `--version` (the click probe needed the `agent-skilltree` distribution name). Suite →
+  **70 passing** (+11 tome tests).
+- Vocabulary: a branch holding frameworks is a **SkillVolume**; the overall corpus is a **SkillTome**
+  ("nomicon" is the legacy alias). The table heading stays `## Frameworks` — existing table parsers
+  keep working (verified against the reference atomizer end-to-end).
+
 ### v0.2.0 — 2026-06-18
 - **Folded the `skillmap` / `foldersearch` / `skillsearch` seedlings into skilltree as subcommands — one product.** `skilltree map <folder> [--write]` renders a flat folder into one coordinate-addressed `CLAUDE.md`, using skilltree's **own** coordinate code (`assign_coords`/`skill_name` from `model.py`; the vendored copy is gone). `skilltree search <folder> <query> [--scope <coord>]` is **one** FTS5/BM25 engine over any folder — coordinate-free on a plain folder, coordinate-subtree-scoped when the folder carries skilltree coordinates (`foldersearch` + `skillsearch` unified; the `--scope` flag is the only difference). Added the `tree` view command. The `<coord>-<name>` frontmatter and the Read-breadcrumb format are preserved (backward compatible). Suite grew 56 → **62 tests**.
 

{agent_skilltree-0.2.1 → agent_skilltree-0.3.0}/src/agent_skilltree.egg-info/SOURCES.txt

@@ -20,6 +20,7 @@ src/skilltree/model.py
 src/skilltree/registry.py
 src/skilltree/reports.py
 src/skilltree/search.py
+src/skilltree/tome.py
 src/skilltree/validate.py
 tests/test_cohere.py
 tests/test_coords.py
@@ -36,4 +37,5 @@ tests/test_registry.py
 tests/test_reports.py
 tests/test_search.py
 tests/test_skilltree.py
-tests/test_summaries.py
+tests/test_summaries.py
+tests/test_tome.py

{agent_skilltree-0.2.1 → agent_skilltree-0.3.0}/src/skilltree/__init__.py

@@ -6,14 +6,28 @@ edges are symlinks; descending a level = redirecting the active skills root.
 """
 from __future__ import annotations
 
-__version__ = "0.2.0"
+# single source of truth = the installed dist (pyproject); can't drift from a literal again
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+try:
+    __version__ = _pkg_version("agent-skilltree")
+except PackageNotFoundError:        # running from a source checkout that isn't pip-installed
+    __version__ = "0.3.0"
 
 from .exchange import Exchange, Member, load_exchange
 from .exchange import build as build_exchange
 from .exchange import is_valid as exchange_is_valid
 from .exchange import validate as validate_exchange
 from .materialize import materialize
-from .model import SkillTree, TreeNode, assign_coords, compose_summary, skill_name, assign_coords, skill_name
+from .model import (
+    TOME_HEADING,
+    SkillTree,
+    TreeNode,
+    assign_coords,
+    compose_summary,
+    find_node,
+    skill_name,
+    tome_table,
+)
 from .registry import (
     Entry,
     load_registry,
@@ -22,7 +36,8 @@ from .registry import (
     validate_registry,
 )
 from .registry import search as registry_search
-from .forest import build_forest, link_tree, list_links, unlink
+from .forest import build_forest, link_tree, list_links, project, unlink
+from .tome import fold
 from .reports import (
     list_reports,
     mark_problem,
@@ -53,7 +68,8 @@ __all__ = [
     "promote", "registry_search",
     "walk_federation", "flatten_federation", "validate_federation",
     "register_child", "local_resolver",
-    "link_tree", "build_forest", "list_links", "unlink",
+    "link_tree", "build_forest", "list_links", "unlink", "project",
+    "fold", "tome_table", "find_node", "TOME_HEADING",
     "assign_coords", "skill_name",
     "build_index", "search", "search_tree", "search_folder", "DEFAULT_EXTS",
     "build_map", "write_map",

{agent_skilltree-0.2.1 → agent_skilltree-0.3.0}/src/skilltree/cli.py

@@ -12,7 +12,7 @@ from .validate import validate
 
 
 @click.group()
-@click.version_option(message="skilltree %(version)s")
+@click.version_option(package_name="agent-skilltree", message="skilltree %(version)s")
 def main() -> None:
     """SkillTree — a nested tree of skill dirs wired by `cat`-breadcrumbs (validated)."""
 
@@ -242,6 +242,48 @@ def validate_cmd(root: Path) -> None:
     click.echo("✓ valid — every breadcrumb resolves.")
 
 
+@main.command(name="fold")
+@click.argument("framework_dir", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.option("--into", required=True, help="the volume node to bind into (name or coord)")
+@click.option("--tree", "tree_root", required=True,
+              type=click.Path(exists=True, file_okay=False, path_type=Path),
+              help="the materialized tree root (holds skilltree.json)")
+@click.option("--what-for", default=None, help="the row's purpose text (default: the framework's description)")
+@click.option("--name", default=None, help="the row name (default: the framework's frontmatter name)")
+@click.option("--relative", is_flag=True,
+              help="store the row path relative to the volume node (repo-portable: validates/projects from any checkout)")
+def fold_cmd(framework_dir: Path, into: str, tree_root: Path, what_for: str | None,
+             name: str | None, relative: bool) -> None:
+    """Fold a FRAMEWORK_DIR into a volume node's tome table (idempotent, one row
+    per framework). The manifest is updated and the node's SKILL.md regenerated."""
+    from .tome import fold
+    rep = fold(framework_dir, into=into, tree_root=tree_root, what_for=what_for, name=name,
+               relative=relative)
+    if not rep.get("ok"):
+        click.echo(f"✗ {rep.get('error')}")
+        raise SystemExit(1)
+    verb = "updated" if rep["updated"] else "added"
+    click.echo(f"✓ {verb} row {rep['row']['name']!r} on node {rep['node']!r} "
+               f"({rep['rows']} framework(s) held)")
+
+
+@main.command(name="project")
+@click.argument("tree_root", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.argument("target", type=click.Path(path_type=Path))
+@click.option("--policy", type=click.Choice(["progressive", "flat"]), default="progressive",
+              help="progressive = root + first-layer branches; flat = a volume's tome rows + holder")
+@click.option("--link", type=click.Choice(["absolute", "relative"]), default="absolute")
+@click.option("--node", default=None, help="(flat) the volume node to project (name or coord; default root)")
+def project_cmd(tree_root: Path, target: Path, policy: str, link: str, node: str | None) -> None:
+    """Project TREE_ROOT into TARGET (a skills dir) as symlinks — progressive
+    disclosure, or a volume's flat auto-discoverable deployment."""
+    from .forest import project
+    links = project(tree_root, target, policy=policy, link=link, node=node)
+    click.echo(f"✓ projected {len(links)} link(s) ({policy}, {link}) into {target}")
+    for p in links:
+        click.echo(f"  - {p.name} -> {p.readlink()}")
+
+
 @main.group()
 def exchange() -> None:
     """Many skill trees in one repo, under a master."""

{agent_skilltree-0.2.1 → agent_skilltree-0.3.0}/src/skilltree/cohere.py

@@ -24,14 +24,17 @@ import shutil
 from dataclasses import dataclass, field
 from pathlib import Path
 
-from .model import SkillTree, TreeNode, assign_coords, compose_summary, skill_name
+from .model import SkillTree, TreeNode, assign_coords, compose_summary, skill_name, tome_table
 
 # dirs that are never tree nodes
 _SKIP = {".claude", "kb", "__pycache__", ".git", "node_modules", ".aios.src"}
 # a coord-prefixed skill identity: "0.1.2-some-name" → ("0.1.2", "some-name")
 _COORD_RE = re.compile(r"^(\d+(?:\.\d+)*)-(.+)$")
-# everything from the first generated section to EOF (materialize appends them last)
-_SECT_RE = re.compile(r"\n+## Index summary\b.*\Z", re.S)
+# everything from the first generated section to EOF (materialize appends them last).
+# Generated sections, in emit order: Index summary → Descend (branches), then the
+# `## Frameworks` tome table (any node with frameworks rows) — leftmost heading wins,
+# so a leaf-with-table strips from Frameworks and a branch strips from Index summary.
+_SECT_RE = re.compile(r"\n+## (?:Index summary|Frameworks)\b.*\Z", re.S)
 _CRUMB_RE = re.compile(r"`([^`]+?)/SKILL\.md`")     # the path-before-SKILL.md, verb-agnostic
 _CRUMB = "- {name} ({kind}): Read `{path}`"          # the verb is the Read TOOL, never `cat`
 
@@ -251,6 +254,8 @@ def _rewrite_node_md(smd: Path, node: TreeNode, node_dir: Path) -> None:
                 "nothing; you must use the Read tool:\n\n" + "\n".join(crumbs))
     else:
         tail = ""
+    if node.frameworks:                     # regenerate the tome table from the model rows
+        tail += f"\n\n{tome_table(node)}"
     out = f"---\nname: {sname}\ndescription: {desc}\n---\n\n{base}{tail}\n"
     smd.write_text(out, encoding="utf-8")
 

agent_skilltree-0.3.0/src/skilltree/forest.py

@@ -0,0 +1,170 @@
+"""Make a SkillTree (or a forest of them) visible from the TOP — `~/.claude/skills`.
+
+The top-level user `.claude/skills` is scanned in every session, but the scan is
+non-recursive WITHIN a `.claude/skills` (a skill can't contain auto-loadable
+sub-skills). So to surface a tree from the top you SYMLINK its entry skill dirs
+into `~/.claude/skills`, and the `cat`-breadcrumbs carry you down from there.
+
+ONE projector, two policies (`project`):
+  - **progressive** → symlink the root (and its first-layer branches) up; deeper
+    levels stay behind Read-breadcrumbs (progressive disclosure). `link_tree` is
+    the thin compatibility wrapper.
+  - **flat** → project a volume node's tome-table rows (its held frameworks) +
+    the holder node itself as top-level skill dirs, so agents auto-discover every
+    framework (the nomicon-atomize semantics: the organized tree stays the source
+    of truth; the flat dir is only symlinks — edits propagate, nothing duplicates).
+  - many trees → `build_forest`: one forest-root skill that breadcrumbs to each
+    tree's root, symlinked up — a forest view over the top.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .model import SkillTree, find_node, skill_name
+
+_CRUMB = "- {name} ({kind}): Read `{path}`"     # the Read TOOL injects the layer, not `cat`
+
+
+def _skill_dir(node_dir: Path, name: str) -> Path:
+    return Path(node_dir) / ".claude" / "skills" / name
+
+
+def _symlink(link: Path, target: Path, *, relative: bool = False) -> Path | None:
+    """Idempotently (re)create `link` → `target` (a dir). Self-clobber guard: if the
+    link path IS the target (same path, symlinks not followed), do nothing and return
+    None — never unlink the source onto itself. `relative` makes the pair portable
+    when moved together (the doc-mirror vision-hyperedge pattern)."""
+    target_abs = Path(os.path.abspath(target))
+    if Path(os.path.abspath(link)) == target_abs:
+        return None
+    link.parent.mkdir(parents=True, exist_ok=True)
+    if link.is_symlink() or link.exists():
+        link.unlink()
+    dst = os.path.relpath(target_abs, os.path.abspath(link.parent)) if relative else target_abs
+    link.symlink_to(dst, target_is_directory=True)
+    return link
+
+
+def project(tree_dir: str | Path, target: str | Path, *,
+            policy: str = "progressive", link: str = "absolute",
+            node: str | None = None, manifest: str | Path | None = None,
+            include_root: bool = True, branches: bool = True) -> list[Path]:
+    """Project a tree into a skills dir — the ONE deployment op (Move 1).
+
+    policy="progressive"  surface the root (+ first-layer branches) as symlinks;
+                          deeper levels stay behind Read-breadcrumbs.
+    policy="flat"         project the selected node's tome-table rows (each held
+                          framework's skill dir) + the holder node itself, flat —
+                          every framework auto-discovers as a top-level skill
+                          (née nomicon-atomize). `node` selects the volume node by
+                          name or coord (default: the root).
+    link="absolute"|"relative"  symlink form (relative = portable-if-moved-together).
+
+    The tree stays the source of truth; the target holds only symlinks. Re-running
+    overwrites cleanly (idempotent). Self-clobber-guarded skips return no link.
+    """
+    tree_dir = Path(tree_dir)
+    tree = SkillTree.load(manifest or tree_dir / "skilltree.json")
+    target = Path(target)
+    rel = link == "relative"
+    links: list[Path] = []
+
+    if policy == "progressive":
+        if include_root:
+            rn = skill_name(tree.root)
+            p = _symlink(target / rn, _skill_dir(tree_dir, rn), relative=rel)
+            if p:
+                links.append(p)
+        if branches:
+            for child in tree.root.children:
+                cn = skill_name(child)
+                p = _symlink(target / cn, _skill_dir(tree_dir / child.name, cn), relative=rel)
+                if p:
+                    links.append(p)
+        return links
+
+    if policy != "flat":
+        raise ValueError(f"unknown policy {policy!r} (use 'flat' or 'progressive')")
+
+    hit = find_node(tree.root, node or tree.root.name)
+    if hit is None:
+        raise ValueError(f"no node named/coord {node!r} in the tree")
+    vol, path = hit
+    node_dir = tree_dir
+    for nm in path[1:]:
+        node_dir = node_dir / nm
+
+    holder = _skill_dir(node_dir, skill_name(vol))
+    for row in vol.frameworks:              # each held framework, flat
+        rp = Path(row["skill_path"])
+        if not rp.is_absolute():            # relative rows resolve against the holder dir
+            rp = holder / rp
+        p = _symlink(target / row["name"], rp.parent, relative=rel)
+        if p:
+            links.append(p)
+    # the holder itself (the volume's search/router skill) — skip when the target
+    # sits inside the holder's own dir (a symlink loop; the atomize guard)
+    if not os.path.abspath(target).startswith(os.path.abspath(node_dir) + os.sep):
+        p = _symlink(target / skill_name(vol), _skill_dir(node_dir, skill_name(vol)),
+                     relative=rel)
+        if p:
+            links.append(p)
+    return links
+
+
+def link_tree(tree_dir: str | Path, *, user_skills_dir: str | Path,
+              manifest: str | Path | None = None,
+              include_root: bool = True, branches: bool = True) -> list[Path]:
+    """Symlink a single tree's entry points into the top-level user skills dir.
+    (Thin wrapper over `project(policy="progressive", link="absolute")`.)"""
+    return project(tree_dir, user_skills_dir, policy="progressive", link="absolute",
+                   manifest=manifest, include_root=include_root, branches=branches)
+
+
+def build_forest(name: str, members: list[str | Path], *, user_skills_dir: str | Path,
+                 forest_dir: str | Path, description: str | None = None) -> Path:
+    """Build a forest-root skill over several trees and symlink it to the top.
+
+    `members` = tree dirs (each with a skilltree.json). The forest root's body
+    breadcrumbs to each tree's root; one top-level entry, progressive descent.
+    """
+    fdir = _skill_dir(Path(forest_dir), name)
+    fdir.mkdir(parents=True, exist_ok=True)
+    crumbs, roots = [], []
+    for tdir in members:
+        tdir = Path(tdir)
+        tree = SkillTree.load(tdir / "skilltree.json")
+        rn = skill_name(tree.root)
+        md = _skill_dir(tdir, rn) / "SKILL.md"
+        crumbs.append(_CRUMB.format(name=rn, kind=tree.root.kind, path=md.resolve()))
+        roots.append(rn)
+    desc = description or f"Forest of {len(members)} skill tree(s): {', '.join(roots)}."
+    body = (f"Forest **{name}** — {len(members)} skill tree(s). "
+            "Pick one and **Read** (the Read tool) into its root to load it, then follow its "
+            "breadcrumbs down (`cat` won't load it — only the Read tool does):\n\n" + "\n".join(crumbs))
+    (fdir / "SKILL.md").write_text(f"---\nname: {name}\ndescription: {desc}\n---\n\n{body}\n", encoding="utf-8")
+    return _symlink(Path(user_skills_dir) / name, fdir)
+
+
+def list_links(user_skills_dir: str | Path) -> list[dict]:
+    """List symlinks in the user skills dir and whether they still resolve."""
+    user = Path(user_skills_dir)
+    out: list[dict] = []
+    if user.exists():
+        for p in sorted(user.iterdir()):
+            if p.is_symlink():
+                out.append({"name": p.name, "target": str(p.readlink()), "resolves": p.exists()})
+    return out
+
+
+def unlink(user_skills_dir: str | Path, *names: str) -> list[str]:
+    """Remove named symlinks (only if they are symlinks — never deletes real dirs)."""
+    user = Path(user_skills_dir)
+    removed: list[str] = []
+    for n in names:
+        p = user / n
+        if p.is_symlink():
+            p.unlink()
+            removed.append(n)
+    return removed

{agent_skilltree-0.2.1 → agent_skilltree-0.3.0}/src/skilltree/materialize.py

@@ -17,7 +17,7 @@ from __future__ import annotations
 from pathlib import Path
 import shutil
 
-from .model import SkillTree, TreeNode, assign_coords, compose_summary, skill_name
+from .model import SkillTree, TreeNode, assign_coords, compose_summary, skill_name, tome_table
 
 # A breadcrumb line is parseable by validate.py: `- <name> (<kind>): Read `<abspath>``
 # The verb is **Read** (the Read tool), NOT `cat`: only the Read tool injects a dir's
@@ -65,6 +65,12 @@ def _write_node(node: TreeNode, node_dir: Path, root: Path) -> None:
     else:
         body = base + "\n\n_(leaf — this is an actual skill.)_"
 
+    # tome pointer-table (SkillVolume binding): generated LAST from the model rows, so
+    # cohere's in-place rewrite (which regenerates from the first generated heading to
+    # EOF) re-emits it instead of wiping it. See model.tome_table / tome.fold.
+    if node.frameworks:
+        body += f"\n\n{tome_table(node)}"
+
     if node.coord:
         desc = f"[{node.coord}] {desc}"
 

{agent_skilltree-0.2.1 → agent_skilltree-0.3.0}/src/skilltree/model.py

@@ -26,6 +26,10 @@ class TreeNode:
     description: str | None = None   # SKILL.md description (so it auto-loads / is searchable)
     coord: str | None = None         # hierarchical address (e.g. "0.1.2"); set by assign_coords
     children: list["TreeNode"] = field(default_factory=list)
+    # tome pointer-table rows (the SkillVolume binding): each row registers a framework
+    # this node HOLDS — {"name", "what_for", "skill_path" (abs path to its SKILL.md)}.
+    # Rendered as the `## Frameworks` table by tome_table(); added by tome.fold().
+    frameworks: list[dict] = field(default_factory=list)
 
     def walk(self):
         yield self
@@ -67,6 +71,39 @@ def compose_summary(node: "TreeNode", *, full: bool = False) -> str:
             f"Reachable below: {', '.join(reachable)}.")
 
 
+TOME_HEADING = "## Frameworks"
+
+
+def tome_table(node: "TreeNode") -> str:
+    """Render a node's tome pointer-table (the `## Frameworks` registry) from the model.
+
+    The table is GENERATED — the manifest's `frameworks` rows are the source of truth,
+    and both materialize and cohere's in-place rewrite re-emit it (so a re-cohere can
+    never wipe or drift a folded row). The 'Framework skill' cell is `name (<abs path
+    to SKILL.md>)` — the exact shape the flat projector (`project(policy="flat")`, née
+    nomicon-atomize) parses. Columns grow Plugin/Chapter in Move 2.
+    """
+    lines = [TOME_HEADING, "",
+             "| Framework | What it's for | Framework skill |",
+             "|---|---|---|"]
+    for r in node.frameworks:
+        lines.append(f"| {r['name']} | {r.get('what_for', '')} | {r['name']} ({r['skill_path']}) |")
+    return "\n".join(lines)
+
+
+def find_node(root: "TreeNode", selector: str) -> tuple["TreeNode", list[str]] | None:
+    """Locate a node by NAME or COORD; returns (node, tree-path names root→node)."""
+    def walk(n: "TreeNode", path: list[str]):
+        if n.name == selector or (n.coord and n.coord == selector):
+            return n, path
+        for c in n.children:
+            hit = walk(c, path + [c.name])
+            if hit:
+                return hit
+        return None
+    return walk(root, [root.name])
+
+
 def assign_coords(root: "TreeNode", base: str = "0") -> "TreeNode":
     """Give every node a hierarchical coordinate: root=base, child i (1-based)=parent.i."""
     def walk(n: "TreeNode", coord: str) -> None:
@@ -86,6 +123,7 @@ class SkillTree:
         def enc(n: TreeNode) -> dict:
             return {"name": n.name, "kind": n.kind, "skill_src": n.skill_src,
                     "description": n.description, "coord": n.coord,
+                    "frameworks": [dict(r) for r in n.frameworks],
                     "children": [enc(c) for c in n.children]}
         return {"skilltree": enc(self.root)}
 
@@ -95,6 +133,7 @@ class SkillTree:
             return TreeNode(name=d["name"], kind=d.get("kind", "skill"),
                             skill_src=d.get("skill_src"), description=d.get("description"),
                             coord=d.get("coord"),
+                            frameworks=[dict(r) for r in d.get("frameworks", [])],
                             children=[dec(c) for c in d.get("children", [])])
         return SkillTree(dec(data["skilltree"]))
 

agent_skilltree-0.3.0/src/skilltree/tome.py

@@ -0,0 +1,86 @@
+"""tome.py — the SkillVolume/SkillTome bind ops (fold a framework into a volume).
+
+A **SkillVolume** is a SkillTree branch that HOLDS frameworks: its node carries
+`frameworks` rows in the manifest, rendered as the `## Frameworks` pointer-table
+(see model.tome_table). A **SkillTome** is the overall corpus — the set of volumes
++ everything made with them. ("nomicon" is the legacy alias for both.)
+
+`fold(framework_dir, into=...)` is the bind operator: register ONE framework
+(a chapter — its skill dir) as a row on a volume node. Idempotent — one row per
+framework name; re-folding the same framework updates its row in place. The
+manifest is the source of truth; the node's SKILL.md table is regenerated from it
+surgically (only that node is rewritten — never a destructive re-materialize).
+
+The flat deployment of a folded volume is `forest.project(policy="flat")`.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .model import SkillTree, find_node, skill_name
+
+
+def fold(framework_dir: str | Path, *, into: str, tree_root: str | Path,
+         what_for: str | None = None, name: str | None = None,
+         relative: bool = False) -> dict:
+    """Fold a framework's skill dir into a volume node's tome table — one row,
+    idempotent by row name. Returns a report dict ({"ok": False, "error": ...} on
+    a bad target — no partial writes happen in that case).
+
+    framework_dir  the framework's skill dir (must contain SKILL.md)
+    into           the volume node, by name or coordinate
+    tree_root      the materialized tree root (holds skilltree.json)
+    what_for       the row's purpose text (default: the framework's description)
+    name           the row name (default: the framework's frontmatter name, else dir name)
+    relative       store the row's skill_path RELATIVE to the volume node's skill dir
+                   (the holder SKILL.md's dir — the base every table parser normalizes
+                   against). Use for a repo-committed tome: the tree then validates and
+                   projects from ANY checkout location, not just this machine.
+    """
+    from .cohere import _front, _rewrite_node_md   # frontmatter parse + surgical rewrite
+
+    tree_root = Path(tree_root)
+    manifest = tree_root / "skilltree.json"
+    if not manifest.is_file():
+        return {"ok": False, "error": f"no skilltree.json manifest at {tree_root}"}
+    fdir = Path(framework_dir)
+    smd = fdir / "SKILL.md"
+    if not smd.is_file():
+        return {"ok": False, "error": f"framework dir has no SKILL.md: {fdir}"}
+
+    tree = SkillTree.load(manifest)
+    hit = find_node(tree.root, into)
+    if hit is None:
+        return {"ok": False, "error": f"no node named/coord {into!r} in {manifest}"}
+    node, path = hit
+
+    node_dir = tree_root
+    for nm in path[1:]:
+        node_dir = node_dir / nm
+    holder_dir = node_dir / ".claude" / "skills" / skill_name(node)
+
+    front = _front(smd)
+    row_name = name or front.get("name") or fdir.name
+    skill_path = (os.path.relpath(smd.resolve(), holder_dir.resolve()) if relative
+                  else str(smd.resolve()))
+    row = {"name": row_name,
+           "what_for": what_for or front.get("description", ""),
+           "skill_path": skill_path}
+    updated = False
+    for i, r in enumerate(node.frameworks):
+        if r.get("name") == row_name:       # idempotent: one row per framework
+            node.frameworks[i] = row
+            updated = True
+            break
+    if not updated:
+        node.frameworks.append(row)
+
+    tree.save(manifest)
+
+    # Surgical in-place rewrite of ONLY the folded node's SKILL.md (regenerates its
+    # generated tail — table included — from the model; hand-written body preserved).
+    _rewrite_node_md(holder_dir / "SKILL.md", node, node_dir)
+
+    return {"ok": True, "node": node.name, "coord": node.coord, "row": row,
+            "updated": updated, "rows": len(node.frameworks)}

{agent_skilltree-0.2.1 → agent_skilltree-0.3.0}/src/skilltree/validate.py

@@ -8,6 +8,9 @@ the things the filesystem won't:
   - every non-leaf node's body has a Read breadcrumb for EACH of its children
   - every breadcrumb path actually resolves to a file (no dead ends)
   - sibling names are unique (their dirs collide otherwise)
+  - tome-table round-trip: a node with `frameworks` rows carries the `## Frameworks`
+    table, every manifest row appears in it, and every row's target SKILL.md resolves
+    (an undeclared table row is a warning — the manifest is the source of truth)
 
 A non-empty error list is a kill-criterion: someone walking the tree hits a dead
 end the platform would never warn about.
@@ -18,11 +21,13 @@ from dataclasses import dataclass
 from pathlib import Path
 import re
 
-from .model import KINDS, SkillTree, TreeNode, skill_name
+from .model import KINDS, TOME_HEADING, SkillTree, TreeNode, skill_name
 
 # a breadcrumb is `- <name> (<kind>): Read `<abspath>`` — match the backticked SKILL.md path
 # (verb-agnostic, so it survives wording tweaks; the verb is the Read tool, never `cat`)
 _CRUMB_RE = re.compile(r"`([^`]+/SKILL\.md)`")
+# a tome-table data row: `| name | what-for | name (path) |` (skip header/separator rows)
+_TOME_ROW_RE = re.compile(r"^\|\s*([^|]+?)\s*\|[^|]*\|[^|]*\|\s*$", re.M)
 
 
 @dataclass
@@ -69,10 +74,40 @@ def _walk(node: TreeNode, node_dir: Path, out: list[Violation]) -> None:
             elif p not in expected:
                 out.append(Violation("warning", node.name, f"breadcrumb `{p}` is not a declared child"))
 
+    if node.frameworks:
+        _check_tome(node, skill_md, out)
+
     for child in node.children:
         _walk(child, node_dir / child.name, out)
 
 
+def _check_tome(node: TreeNode, skill_md: Path, out: list[Violation]) -> None:
+    """Tome-table round-trip: the manifest rows are the source of truth; the table
+    in SKILL.md must carry every one, and every row's target must resolve. An
+    undeclared table row is only a warning (fix by folding it or re-emitting)."""
+    text = skill_md.read_text(encoding="utf-8")
+    if TOME_HEADING not in text:
+        out.append(Violation("error", node.name,
+            "frameworks rows declared but no ## Frameworks table in SKILL.md (re-emit the node)"))
+        return
+    section = re.split(r"\n#{1,6} ", text.split(TOME_HEADING, 1)[1])[0]
+    in_table = {n for n in _TOME_ROW_RE.findall(section)
+                if n != "Framework" and not re.fullmatch(r":?-+:?", n)}
+    for row in node.frameworks:
+        if row["name"] not in in_table:
+            out.append(Violation("error", node.name,
+                f"tome row {row['name']!r} declared in manifest but missing from the ## Frameworks table"))
+        target = Path(row.get("skill_path", ""))
+        if not target.is_absolute():          # relative rows resolve against the holder dir
+            target = skill_md.parent / target
+        if not target.is_file():
+            out.append(Violation("error", node.name,
+                f"tome row {row['name']!r}: target does not resolve ({target})"))
+    for extra in sorted(in_table - {r["name"] for r in node.frameworks}):
+        out.append(Violation("warning", node.name,
+            f"table row {extra!r} is not declared in the manifest"))
+
+
 def validate(root: str | Path, tree: SkillTree | None = None) -> list[Violation]:
     root = Path(root)
     if tree is None:

agent_skilltree-0.3.0/tests/test_tome.py

@@ -0,0 +1,185 @@
+"""Tome bind-op tests (Move 1): fold, the generated ## Frameworks table, the
+validate round-trip, and project(policy="flat"/"progressive")."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from skilltree import (
+    SkillTree,
+    TreeNode,
+    fold,
+    is_valid,
+    link_tree,
+    materialize,
+    project,
+    validate,
+)
+from skilltree.cohere import emit
+from skilltree.materialize import node_skill_md
+
+
+def _framework(tmp_path: Path, name: str, desc: str = "does the thing") -> Path:
+    d = tmp_path / f"fw-{name}"
+    d.mkdir()
+    (d / "SKILL.md").write_text(
+        f"---\nname: {name}\ndescription: {desc}\n---\n\nThe {name} framework.\n")
+    return d
+
+
+def _volume_tree(tmp_path: Path) -> Path:
+    tree = SkillTree(TreeNode("my-tome", "sc", description="the tome root", children=[
+        TreeNode("patterns", "sc", description="the pattern volume"),
+    ]))
+    root = tmp_path / "tome_tree"
+    materialize(tree, root)
+    return root
+
+
+def test_fold_adds_row_and_emits_table(tmp_path: Path):
+    root = _volume_tree(tmp_path)
+    fw = _framework(tmp_path, "alpha", "greek things")
+    rep = fold(fw, into="patterns", tree_root=root)
+    assert rep["ok"] and not rep["updated"] and rep["rows"] == 1
+    # manifest carries the row
+    tree = SkillTree.load(root / "skilltree.json")
+    node = next(n for n in tree.nodes() if n.name == "patterns")
+    assert node.frameworks[0]["name"] == "alpha"
+    assert node.frameworks[0]["skill_path"].endswith("SKILL.md")
+    # SKILL.md carries the generated table with the nomicon-atomize-parseable cell
+    body = node_skill_md(root / "patterns", "patterns").read_text()
+    assert "## Frameworks" in body
+    assert "| Framework | What it's for | Framework skill |" in body
+    assert re.search(r"\| alpha \| greek things \| alpha \(/.*?/SKILL\.md\) \|", body)
+    assert is_valid(root)
+
+
+def test_fold_is_idempotent_one_row_per_framework(tmp_path: Path):
+    root = _volume_tree(tmp_path)
+    fw = _framework(tmp_path, "alpha")
+    assert fold(fw, into="patterns", tree_root=root)["rows"] == 1
+    rep = fold(fw, into="patterns", tree_root=root, what_for="updated purpose")
+    assert rep["updated"] and rep["rows"] == 1          # updated in place, not duplicated
+    body = node_skill_md(root / "patterns", "patterns").read_text()
+    assert body.count("| alpha |") == 1
+    assert "updated purpose" in body
+
+
+def test_fold_bad_targets_are_reported(tmp_path: Path):
+    root = _volume_tree(tmp_path)
+    fw = _framework(tmp_path, "alpha")
+    assert not fold(fw, into="nope", tree_root=root)["ok"]
+    empty = tmp_path / "not-a-framework"
+    empty.mkdir()
+    assert not fold(empty, into="patterns", tree_root=root)["ok"]
+
+
+def test_emit_regenerates_table_from_model(tmp_path: Path):
+    # a re-cohere (emit) must RE-EMIT the folded table, never wipe it
+    root = _volume_tree(tmp_path)
+    fold(_framework(tmp_path, "alpha"), into="patterns", tree_root=root)
+    rep = emit(root)
+    assert rep["ok"]
+    tree = SkillTree.load(root / "skilltree.json")
+    node = next(n for n in tree.nodes() if n.name == "patterns")
+    smd = root / "patterns" / ".claude" / "skills" / f"{node.coord}-patterns" / "SKILL.md"
+    body = smd.read_text()
+    assert body.count("## Frameworks") == 1             # regenerated once, not doubled
+    assert "| alpha |" in body
+
+
+def test_validate_round_trip_catches_drift(tmp_path: Path):
+    root = _volume_tree(tmp_path)
+    fw = _framework(tmp_path, "alpha")
+    fold(fw, into="patterns", tree_root=root)
+    assert is_valid(root)
+    # dead target: the framework dir vanishes → error
+    (fw / "SKILL.md").rename(fw / "GONE.md")
+    errs = [v for v in validate(root) if v.severity == "error"]
+    assert any("does not resolve" in v.message for v in errs)
+    (fw / "GONE.md").rename(fw / "SKILL.md")
+    # missing table: SKILL.md hand-stripped of the section → error
+    smd = node_skill_md(root / "patterns", "patterns")
+    smd.write_text(re.sub(r"\n+## Frameworks\b.*\Z", "\n", smd.read_text(), flags=re.S))
+    errs = [v for v in validate(root) if v.severity == "error"]
+    assert any("no ## Frameworks table" in v.message for v in errs)
+
+
+def test_validate_warns_on_undeclared_table_row(tmp_path: Path):
+    root = _volume_tree(tmp_path)
+    fold(_framework(tmp_path, "alpha"), into="patterns", tree_root=root)
+    smd = node_skill_md(root / "patterns", "patterns")
+    smd.write_text(smd.read_text() + "| ghost | not in manifest | ghost (/nowhere/SKILL.md) |\n")
+    warns = [v for v in validate(root) if v.severity == "warning"]
+    assert any("ghost" in v.message and "not declared" in v.message for v in warns)
+
+
+def test_project_flat_symlinks_rows_and_holder(tmp_path: Path):
+    root = _volume_tree(tmp_path)
+    fw_a = _framework(tmp_path, "alpha")
+    fw_b = _framework(tmp_path, "beta")
+    fold(fw_a, into="patterns", tree_root=root)
+    fold(fw_b, into="patterns", tree_root=root)
+    target = tmp_path / "flat_skills"
+    links = project(root, target, policy="flat", node="patterns")
+    names = {p.name for p in links}
+    assert names == {"alpha", "beta", "patterns"}       # every row + the holder
+    for p in links:
+        assert p.is_symlink() and (p / "SKILL.md").is_file()
+    # the originals stay the source of truth (symlinks, not copies)
+    assert (target / "alpha").resolve() == fw_a.resolve()
+
+
+def test_project_flat_relative_links_and_reruns_cleanly(tmp_path: Path):
+    root = _volume_tree(tmp_path)
+    fold(_framework(tmp_path, "alpha"), into="patterns", tree_root=root)
+    target = tmp_path / "flat_skills"
+    project(root, target, policy="flat", node="patterns", link="relative")
+    raw = (target / "alpha").readlink()
+    assert not raw.is_absolute()                        # relative = portable together
+    # idempotent re-run
+    links = project(root, target, policy="flat", node="patterns", link="relative")
+    assert {p.name for p in links} == {"alpha", "patterns"}
+
+
+def test_project_flat_self_clobber_guard(tmp_path: Path):
+    # projecting INTO the holder's own dir must never destroy the source
+    root = _volume_tree(tmp_path)
+    fold(_framework(tmp_path, "alpha"), into="patterns", tree_root=root)
+    inside = root / "patterns" / ".claude" / "skills"
+    links = project(root, inside, policy="flat", node="patterns")
+    assert "patterns" not in {p.name for p in links}    # holder self-link skipped
+    assert node_skill_md(root / "patterns", "patterns").is_file()   # source intact
+
+
+def test_relative_fold_survives_relocation(tmp_path: Path):
+    # a repo-committed tome: relative rows must validate + project from ANY checkout path
+    site_a = tmp_path / "checkout_a"
+    site_a.mkdir()
+    root = _volume_tree(site_a)
+    fw = _framework(site_a, "alpha")
+    rep = fold(fw, into="patterns", tree_root=root, relative=True)
+    assert rep["ok"] and not Path(rep["row"]["skill_path"]).is_absolute()
+    assert is_valid(root)
+    # relocate the WHOLE checkout (tree + framework move together, like a fresh CI clone)
+    site_b = tmp_path / "checkout_b"
+    site_a.rename(site_b)
+    root_b = site_b / "tome_tree"
+    # breadcrumbs are absolute by design → a moved tree needs the localize step first:
+    # emit re-coheres at the NEW location from the manifest (the portable canon). The
+    # relative tome rows need no rewrite — that is the point of --relative.
+    assert emit(root_b)["ok"]
+    assert is_valid(root_b)                             # emit + validate = the CI gate flow
+    links = project(root_b, tmp_path / "flat_b", policy="flat", node="patterns")
+    assert (tmp_path / "flat_b" / "alpha").resolve() == (site_b / "fw-alpha").resolve()
+    # emit coordinatized the tree, so the holder projects under its coord identity
+    assert {p.name for p in links} == {"alpha", "0.1-patterns"}
+
+
+def test_project_progressive_matches_link_tree(tmp_path: Path):
+    root = _volume_tree(tmp_path)
+    a = tmp_path / "user_a"
+    b = tmp_path / "user_b"
+    via_project = {p.name for p in project(root, a, policy="progressive")}
+    via_link_tree = {p.name for p in link_tree(root, user_skills_dir=b)}
+    assert via_project == via_link_tree == {"my-tome", "patterns"}

agent_skilltree-0.2.1/src/skilltree/forest.py

@@ -1,101 +0,0 @@
-"""Make a SkillTree (or a forest of them) visible from the TOP — `~/.claude/skills`.
-
-The top-level user `.claude/skills` is scanned in every session, but the scan is
-non-recursive WITHIN a `.claude/skills` (a skill can't contain auto-loadable
-sub-skills). So to surface a tree from the top you SYMLINK its entry skill dirs
-into `~/.claude/skills`, and the `cat`-breadcrumbs carry you down from there.
-
-  - single tree  → `link_tree`: symlink the root (and its first-layer branches) up
-  - many trees   → `build_forest`: one forest-root skill that breadcrumbs to each
-                   tree's root, symlinked up — a forest view over the top.
-"""
-from __future__ import annotations
-
-from pathlib import Path
-
-from .model import SkillTree, skill_name
-
-_CRUMB = "- {name} ({kind}): Read `{path}`"     # the Read TOOL injects the layer, not `cat`
-
-
-def _skill_dir(node_dir: Path, name: str) -> Path:
-    return Path(node_dir) / ".claude" / "skills" / name
-
-
-def _symlink(link: Path, target: Path) -> Path:
-    link.parent.mkdir(parents=True, exist_ok=True)
-    if link.is_symlink() or link.exists():
-        link.unlink()
-    link.symlink_to(Path(target).resolve(), target_is_directory=True)
-    return link
-
-
-def link_tree(tree_dir: str | Path, *, user_skills_dir: str | Path,
-              manifest: str | Path | None = None,
-              include_root: bool = True, branches: bool = True) -> list[Path]:
-    """Symlink a single tree's entry points into the top-level user skills dir.
-
-    The root gives the overview + breadcrumbs; the branches (root's direct
-    children) are surfaced too so the first layer is reachable from the top.
-    Deeper levels stay behind `cat` (progressive disclosure).
-    """
-    tree_dir = Path(tree_dir)
-    tree = SkillTree.load(manifest or tree_dir / "skilltree.json")
-    user = Path(user_skills_dir)
-    links: list[Path] = []
-    if include_root:
-        rn = skill_name(tree.root)
-        links.append(_symlink(user / rn, _skill_dir(tree_dir, rn)))
-    if branches:
-        for child in tree.root.children:
-            cn = skill_name(child)
-            links.append(_symlink(user / cn, _skill_dir(tree_dir / child.name, cn)))
-    return links
-
-
-def build_forest(name: str, members: list[str | Path], *, user_skills_dir: str | Path,
-                 forest_dir: str | Path, description: str | None = None) -> Path:
-    """Build a forest-root skill over several trees and symlink it to the top.
-
-    `members` = tree dirs (each with a skilltree.json). The forest root's body
-    breadcrumbs to each tree's root; one top-level entry, progressive descent.
-    """
-    fdir = _skill_dir(Path(forest_dir), name)
-    fdir.mkdir(parents=True, exist_ok=True)
-    crumbs, roots = [], []
-    for tdir in members:
-        tdir = Path(tdir)
-        tree = SkillTree.load(tdir / "skilltree.json")
-        rn = skill_name(tree.root)
-        md = _skill_dir(tdir, rn) / "SKILL.md"
-        crumbs.append(_CRUMB.format(name=rn, kind=tree.root.kind, path=md.resolve()))
-        roots.append(rn)
-    desc = description or f"Forest of {len(members)} skill tree(s): {', '.join(roots)}."
-    body = (f"Forest **{name}** — {len(members)} skill tree(s). "
-            "Pick one and **Read** (the Read tool) into its root to load it, then follow its "
-            "breadcrumbs down (`cat` won't load it — only the Read tool does):\n\n" + "\n".join(crumbs))
-    (fdir / "SKILL.md").write_text(f"---\nname: {name}\ndescription: {desc}\n---\n\n{body}\n", encoding="utf-8")
-    return _symlink(Path(user_skills_dir) / name, fdir)
-
-
-def list_links(user_skills_dir: str | Path) -> list[dict]:
-    """List symlinks in the user skills dir and whether they still resolve."""
-    user = Path(user_skills_dir)
-    out: list[dict] = []
-    if user.exists():
-        for p in sorted(user.iterdir()):
-            if p.is_symlink():
-                out.append({"name": p.name, "target": str(p.readlink()), "resolves": p.exists()})
-    return out
-
-
-def unlink(user_skills_dir: str | Path, *names: str) -> list[str]:
-    """Remove named symlinks (only if they are symlinks — never deletes real dirs)."""
-    user = Path(user_skills_dir)
-    removed: list[str] = []
-    for n in names:
-        p = user / n
-        if p.is_symlink():
-            p.unlink()
-            removed.append(n)
-    return removed