agent-skilltree 0.2.2__tar.gz → 0.4.0__tar.gz

{agent_skilltree-0.2.2/src/agent_skilltree.egg-info → agent_skilltree-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-skilltree
-Version: 0.2.2
+Version: 0.4.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,8 +82,11 @@ 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). Projecting is an install, so it localizes the tree's breadcrumbs first |
+| `relink <root> [--localize]` | rewrite only the breadcrumb paths: **portable** (the default and the shipped form — relative to each node's folder, no machine's path in any file) or `--localize` (absolute for this machine — the install-time step) |
 | `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) |
+| `emit <root> [--root-forest] [--localize]` | re-cohere in place; `--root-forest` tree-ifies a bare forest (lossless, journaled); breadcrumbs portable unless `--localize` |
 | `unemit <root>` | reverse the last `emit`, byte-for-byte |
 | `discover` · `validate` · `build` · `notify` · `watch` | read a tree · gate breadcrumb-resolvability · materialize from a manifest · write the notification rule · run the decoherence cron |
 
@@ -128,6 +131,32 @@ Two papers document the project:
 
 ## Changelog
 
+### v0.4.0 — 2026-10-23
+- **Trees ship portable.** Every breadcrumb names its child relative to the node's folder (the folder holding the SKILL.md's `.claude/`), and the manifest stores `skill_src` relative to itself, so a materialized tree carries no machine's path and validates wherever it is copied — with no step. `materialize`, `emit` and `exchange build` take `localize=True` (`--localize`) to write absolute paths for one machine; the new `relink` rewrites only the paths, either way; `project` localizes the tree it projects (a projected tree is read through a symlink, where only an absolute path resolves). `validate` accepts both forms. 80 tests (7 new, in `tests/test_portable.py`).
+- **Developed in one source home and published here.** This repository and PyPI `agent-skilltree` are the published output of SkillTree's source home; changes arrive as releases, each with a version and an entry here.
+- Frontmatter quotes YAML-unsafe scalars (#1), merged after 0.3.0 and not yet released.
+- The figure script writes beside itself instead of to a fixed folder; a test comment names the author by role.
+
+### 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.2 → agent_skilltree-0.4.0}/README.md

@@ -68,8 +68,11 @@ 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). Projecting is an install, so it localizes the tree's breadcrumbs first |
+| `relink <root> [--localize]` | rewrite only the breadcrumb paths: **portable** (the default and the shipped form — relative to each node's folder, no machine's path in any file) or `--localize` (absolute for this machine — the install-time step) |
 | `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) |
+| `emit <root> [--root-forest] [--localize]` | re-cohere in place; `--root-forest` tree-ifies a bare forest (lossless, journaled); breadcrumbs portable unless `--localize` |
 | `unemit <root>` | reverse the last `emit`, byte-for-byte |
 | `discover` · `validate` · `build` · `notify` · `watch` | read a tree · gate breadcrumb-resolvability · materialize from a manifest · write the notification rule · run the decoherence cron |
 
@@ -114,6 +117,32 @@ Two papers document the project:
 
 ## Changelog
 
+### v0.4.0 — 2026-10-23
+- **Trees ship portable.** Every breadcrumb names its child relative to the node's folder (the folder holding the SKILL.md's `.claude/`), and the manifest stores `skill_src` relative to itself, so a materialized tree carries no machine's path and validates wherever it is copied — with no step. `materialize`, `emit` and `exchange build` take `localize=True` (`--localize`) to write absolute paths for one machine; the new `relink` rewrites only the paths, either way; `project` localizes the tree it projects (a projected tree is read through a symlink, where only an absolute path resolves). `validate` accepts both forms. 80 tests (7 new, in `tests/test_portable.py`).
+- **Developed in one source home and published here.** This repository and PyPI `agent-skilltree` are the published output of SkillTree's source home; changes arrive as releases, each with a version and an entry here.
+- Frontmatter quotes YAML-unsafe scalars (#1), merged after 0.3.0 and not yet released.
+- The figure script writes beside itself instead of to a fixed folder; a test comment names the author by role.
+
+### 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.2 → agent_skilltree-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-skilltree"
-version = "0.2.2"
+version = "0.4.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.2 → agent_skilltree-0.4.0/src/agent_skilltree.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-skilltree
-Version: 0.2.2
+Version: 0.4.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,8 +82,11 @@ 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). Projecting is an install, so it localizes the tree's breadcrumbs first |
+| `relink <root> [--localize]` | rewrite only the breadcrumb paths: **portable** (the default and the shipped form — relative to each node's folder, no machine's path in any file) or `--localize` (absolute for this machine — the install-time step) |
 | `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) |
+| `emit <root> [--root-forest] [--localize]` | re-cohere in place; `--root-forest` tree-ifies a bare forest (lossless, journaled); breadcrumbs portable unless `--localize` |
 | `unemit <root>` | reverse the last `emit`, byte-for-byte |
 | `discover` · `validate` · `build` · `notify` · `watch` | read a tree · gate breadcrumb-resolvability · materialize from a manifest · write the notification rule · run the decoherence cron |
 
@@ -128,6 +131,32 @@ Two papers document the project:
 
 ## Changelog
 
+### v0.4.0 — 2026-10-23
+- **Trees ship portable.** Every breadcrumb names its child relative to the node's folder (the folder holding the SKILL.md's `.claude/`), and the manifest stores `skill_src` relative to itself, so a materialized tree carries no machine's path and validates wherever it is copied — with no step. `materialize`, `emit` and `exchange build` take `localize=True` (`--localize`) to write absolute paths for one machine; the new `relink` rewrites only the paths, either way; `project` localizes the tree it projects (a projected tree is read through a symlink, where only an absolute path resolves). `validate` accepts both forms. 80 tests (7 new, in `tests/test_portable.py`).
+- **Developed in one source home and published here.** This repository and PyPI `agent-skilltree` are the published output of SkillTree's source home; changes arrive as releases, each with a version and an entry here.
+- Frontmatter quotes YAML-unsafe scalars (#1), merged after 0.3.0 and not yet released.
+- The figure script writes beside itself instead of to a fixed folder; a test comment names the author by role.
+
+### 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.2 → agent_skilltree-0.4.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
@@ -32,8 +33,10 @@ tests/test_glyph_search.py
 tests/test_mapper.py
 tests/test_marketplace.py
 tests/test_notifications.py
+tests/test_portable.py
 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.2 → agent_skilltree-0.4.0}/src/skilltree/__init__.py

@@ -11,14 +11,23 @@ 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.2.2"
+    __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,
@@ -27,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,
@@ -58,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.2 → agent_skilltree-0.4.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)."""
 
@@ -55,11 +55,14 @@ def cohere_cmd(root: Path) -> None:
 @click.argument("root", type=click.Path(exists=True, file_okay=False, path_type=Path))
 @click.option("--root-forest", is_flag=True, help="tree-ify a bare forest (synthesize + save a root)")
 @click.option("--name", "forest_name", default=None, help="name for the synthesized root")
-def emit_cmd(root: Path, root_forest: bool, forest_name: str | None) -> None:
+@click.option("--localize", is_flag=True,
+              help="write breadcrumbs absolute for THIS machine (install time); default is portable")
+def emit_cmd(root: Path, root_forest: bool, forest_name: str | None, localize: bool) -> None:
     """Re-cohere IN PLACE: reassign coords + rewrite breadcrumbs/index from the
-    canonical shape (non-destructive). With --root-forest, root a bare forest."""
+    canonical shape (non-destructive). With --root-forest, root a bare forest.
+    Breadcrumbs are portable (relative to each node's folder) unless --localize."""
     from .cohere import emit
-    report = emit(root, root_forest=root_forest, forest_name=forest_name)
+    report = emit(root, root_forest=root_forest, forest_name=forest_name, localize=localize)
     if not report.get("ok"):
         click.echo(f"✗ {report.get('error')}")
         raise SystemExit(1)
@@ -70,6 +73,21 @@ def emit_cmd(root: Path, root_forest: bool, forest_name: str | None) -> None:
         click.echo(f"  journal: {report['journal']}  (reverse with `skilltree unemit`)")
 
 
+@main.command(name="relink")
+@click.argument("root", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.option("--localize", is_flag=True, help="absolute paths for THIS machine (install time)")
+def relink_cmd(root: Path, localize: bool) -> None:
+    """Rewrite only the breadcrumb paths, in place: portable (the shipped form, relative to
+    each node's folder) or --localize (absolute, the install-time step). Nothing else moves."""
+    from .cohere import relink
+    report = relink(root, localize=localize)
+    if not report.get("ok"):
+        click.echo(f"✗ {report.get('error')}")
+        raise SystemExit(1)
+    form = "localized (absolute)" if localize else "portable (relative)"
+    click.echo(f"✓ relinked {report['nodes']} node(s): {form}")
+
+
 @main.command(name="unemit")
 @click.argument("root", type=click.Path(exists=True, file_okay=False, path_type=Path))
 def unemit_cmd(root: Path) -> None:
@@ -216,10 +234,12 @@ def reports_cmd(reports_path, kind):
 @main.command(name="build")
 @click.argument("manifest", type=click.Path(exists=True, dir_okay=False, path_type=Path))
 @click.argument("root", type=click.Path(path_type=Path))
-def build_cmd(manifest: Path, root: Path) -> None:
+@click.option("--localize", is_flag=True,
+              help="write breadcrumbs absolute for THIS machine; default is portable")
+def build_cmd(manifest: Path, root: Path, localize: bool) -> None:
     """Materialize a SkillTree from a JSON MANIFEST into ROOT, then validate."""
     tree = SkillTree.load(manifest)
-    materialize(tree, root)
+    materialize(tree, root, localize=localize)
     issues = validate(root)
     errors = [v for v in issues if v.severity == "error"]
     click.echo(f"built {len(tree.nodes())} nodes at {root}")
@@ -242,6 +262,49 @@ 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. Projecting is an install:
+    TREE_ROOT's breadcrumbs are localized (absolute) for this machine first."""
+    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.2 → agent_skilltree-0.4.0}/src/skilltree/cohere.py

@@ -24,14 +24,18 @@ 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 (PORTABLE_NOTE, SkillTree, TreeNode, assign_coords, compose_summary, crumb_path,
+                    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`
 
@@ -214,7 +218,7 @@ def cohere(root: str | Path) -> list[Finding]:
 
 
 # ── emit: rewrite coords + breadcrumbs + index IN PLACE (non-destructive) ─────
-def _rewrite_node_md(smd: Path, node: TreeNode, node_dir: Path) -> None:
+def _rewrite_node_md(smd: Path, node: TreeNode, node_dir: Path, localize: bool = False) -> None:
     """Refresh ONLY the coord prefix + Index/Descend sections of an existing
     SKILL.md, preserving the hand-written body above them. Creates the file (a
     stub) if absent (e.g. a freshly synthesized forest root)."""
@@ -242,24 +246,64 @@ def _rewrite_node_md(smd: Path, node: TreeNode, node_dir: Path) -> None:
     if node.children:
         crumbs = [_CRUMB.format(
             name=skill_name(c), kind=c.kind,
-            path=(node_dir / c.name / ".claude" / "skills" / skill_name(c) / "SKILL.md").resolve())
+            path=crumb_path(node_dir / c.name / ".claude" / "skills" / skill_name(c) / "SKILL.md",
+                            node_dir, localize=localize))
             for c in node.children]
         tail = (f"\n\n## Index summary\n{compose_summary(node, full=True)}\n\n"
                 f"## Descend — the next layer ({len(node.children)})\n"
                 "Only this layer is loaded now. To descend, use the **Read tool** on a child "
                 "below — that injects the child's layer. A Bash `cat` reads the bytes but loads "
-                "nothing; you must use the Read tool:\n\n" + "\n".join(crumbs))
+                "nothing; you must use the Read tool."
+                + ("" if localize else f" {PORTABLE_NOTE}") + "\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")
 
 
+def relink(root: str | Path, *, localize: bool = False) -> dict:
+    """Rewrite ONLY the breadcrumb paths of a materialized tree, in place: PORTABLE (relative
+    to each node's folder — the shipped form) or LOCALIZED (absolute for this machine — the
+    install-time step). Coords, names, bodies and tome tables are untouched."""
+    root = Path(root)
+    manifest = root / "skilltree.json"
+    if not manifest.is_file():
+        return {"ok": False, "error": f"no skilltree.json manifest at {root}"}
+    tree = SkillTree.load(manifest)
+    n = 0
+
+    def walk(node: TreeNode, node_dir: Path) -> None:
+        nonlocal n
+        smd = node_dir / ".claude" / "skills" / skill_name(node) / "SKILL.md"
+        if node.children and smd.is_file():
+            text = smd.read_text(encoding="utf-8")
+            for c in node.children:
+                child_md = node_dir / c.name / ".claude" / "skills" / skill_name(c) / "SKILL.md"
+                pat = re.compile(r"^(- " + re.escape(skill_name(c)) + r" \(" + re.escape(c.kind)
+                                 + r"\): Read `)[^`]+(`)", re.M)
+                path = crumb_path(child_md, node_dir, localize=localize)
+                text = pat.sub(lambda m: m.group(1) + path + m.group(2), text)
+            text = text.replace("you must use the Read tool:", "you must use the Read tool.")
+            text = text.replace(" " + PORTABLE_NOTE, "")
+            if not localize:
+                text = text.replace("you must use the Read tool.",
+                                    "you must use the Read tool. " + PORTABLE_NOTE, 1)
+            smd.write_text(text, encoding="utf-8")
+            n += 1
+        for c in node.children:
+            walk(c, node_dir / c.name)
+
+    walk(tree.root, root)
+    return {"ok": True, "nodes": n, "localized": localize}
+
+
 JOURNAL = ".emit-journal.json"   # the reversibility receipt written by a tree-ifying emit
 
 
 def emit(root: str | Path, *, root_forest: bool = False,
-         forest_name: str | None = None) -> dict:
+         forest_name: str | None = None, localize: bool = False) -> dict:
     """Re-cohere the tree IN PLACE: assign coords + rewrite every node's
     breadcrumbs/index from the canonical shape, without destroying content.
 
@@ -267,7 +311,10 @@ def emit(root: str | Path, *, root_forest: bool = False,
     a root, and **tree-ify it**: each flat leaf is MOVED WHOLESALE into its nested
     node-dir (all its files preserved — *not* a body-only re-render), so it stops
     auto-loading. Every move is JOURNALED to `.emit-journal.json` so `unemit` can
-    reverse it exactly (your cache-for-reversibility requirement)."""
+    reverse it exactly (your cache-for-reversibility requirement).
+
+    Breadcrumbs are written PORTABLE (relative to each node's folder) unless `localize=True`,
+    which writes them absolute for the place the tree is installed — the install-time step."""
     root = Path(root)
     manifest = root / "skilltree.json"
     synthesized = False
@@ -306,10 +353,10 @@ def emit(root: str | Path, *, root_forest: bool = False,
                 journal.append({"op": "move", "from": str(old_src), "to": str(target_dir),
                                 "skill_md": orig})
                 shutil.move(str(old_src), str(target_dir))
-            _rewrite_node_md(target_dir / "SKILL.md", node, node_dir)
+            _rewrite_node_md(target_dir / "SKILL.md", node, node_dir, localize)
         else:
             existed = (target_dir / "SKILL.md").exists()
-            _rewrite_node_md(target_dir / "SKILL.md", node, node_dir)
+            _rewrite_node_md(target_dir / "SKILL.md", node, node_dir, localize)
             if synthesized and not existed:        # a freshly-created node (the synth root)
                 journal.append({"op": "create", "path": str(target_dir)})
         n += 1

{agent_skilltree-0.2.2 → agent_skilltree-0.4.0}/src/skilltree/exchange.py

@@ -63,30 +63,35 @@ def _front(name: str, description: str, body: str) -> str:
     return f"---\nname: {name}\ndescription: {description}\n---\n\n{body.rstrip()}\n"
 
 
-def build(exchange: Exchange, repo_dir: str | Path) -> Path:
-    """Materialize every member tree + the master. Returns the master SKILL.md path."""
+def build(exchange: Exchange, repo_dir: str | Path, *, localize: bool = False) -> Path:
+    """Materialize every member tree + the master. Returns the master SKILL.md path.
+    Breadcrumbs are portable (relative to the repo) unless `localize=True`."""
     repo = Path(repo_dir)
     members: list[tuple[str, Path]] = []   # (member name, member root SKILL.md)
     for m in exchange.trees:
         tree = SkillTree.load((exchange.base / m.manifest).resolve())
         tree_dir = repo / "trees" / m.name
-        materialize(tree, tree_dir)
+        materialize(tree, tree_dir, localize=localize)
         members.append((m.name, node_skill_md(tree_dir, tree.root.name).resolve()))
 
     master_md = node_skill_md(repo, exchange.master)
     master_md.parent.mkdir(parents=True, exist_ok=True)
-    crumbs = [f"- {name} (tree): Read `{root_md}`" for name, root_md in members]
+    from .model import PORTABLE_NOTE, crumb_path
+    crumbs = [f"- {name} (tree): Read `{crumb_path(root_md, repo, localize=localize)}`"
+              for name, root_md in members]
     body = (f"Master of the **{exchange.name}** exchange — {len(members)} skill tree(s).\n\n"
             "## Trees — pick one and **Read** (the Read tool) into its root\n"
             "Only this master is loaded. Read a tree's root below to load it (a Bash `cat` won't); "
-            "each tree then walks its own breadcrumbs:\n\n"
+            "each tree then walks its own breadcrumbs." + ("" if localize else f" {PORTABLE_NOTE}")
+            + "\n\n"
             + "\n".join(crumbs))
     master_md.write_text(_front(exchange.master, f"master of the {exchange.name} exchange", body),
                          encoding="utf-8")
 
     (repo / "exchange.lock.json").write_text(json.dumps(
         {"name": exchange.name, "master": exchange.master,
-         "trees": [{"name": n, "root": str(r)} for n, r in members]}, indent=2), encoding="utf-8")
+         "trees": [{"name": n, "root": crumb_path(r, repo, localize=localize)} for n, r in members]},
+        indent=2), encoding="utf-8")
     return master_md
 
 
@@ -104,7 +109,8 @@ def validate(repo_dir: str | Path, exchange: Exchange) -> list[Violation]:
         return out
     if not _has_frontmatter(master_md):
         out.append(Violation("error", exchange.master, "master SKILL.md lacks frontmatter"))
-    found = {Path(p).resolve() for p in _CRUMB_RE.findall(master_md.read_text(encoding="utf-8"))}
+    found = {(Path(p) if Path(p).is_absolute() else repo / p).resolve()
+             for p in _CRUMB_RE.findall(master_md.read_text(encoding="utf-8"))}
     expected = {
         node_skill_md(repo / "trees" / m.name, SkillTree.load((exchange.base / m.manifest).resolve()).root.name).resolve()
         for m in exchange.trees