agent-skilltree 0.2.0__py3-none-any.whl

agent_skilltree-0.2.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: agent-skilltree
+Version: 0.2.0
+Summary: A coordinate-addressed tree of agent skill dirs wired by cat/Read breadcrumbs, with programmatic validation.
+Author: Isaac Wostrel-Rubin
+License: MIT
+Project-URL: Homepage, https://github.com/sancovp/skilltree
+Keywords: skills,agents,skill-tree,claude,progressive-disclosure,coordinate-addressing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click
+Dynamic: license-file
+
+# skilltree
+
+Turn a **flat** folder of skills (or any `.claude` directory) into a **navigable tree** that a model can walk one layer at a time — and keep it coherent.
+
+Claude Code auto-loads `~/.claude/skills` (and a project's `.claude/skills`) **one layer deep**: every skill directory loads at once, and a `.claude` nested inside another `.claude` never loads. At a handful of skills that is fine; at a hundred it is *melt* — the whole pile lands in context every turn, and tool selection degrades as the set grows. The substrate ships the nodes and forbids the edge.
+
+`skilltree` imposes the missing structure on that flat substrate, using the only three levers the platform leaves open:
+
+1. **placement** — each node is a plain directory carrying its own one-skill `.claude/`; the path *is* the coordinate (`0` → `0.1` → `0.1.1`);
+2. **the inert-nested-`.claude` boundary** — only the top layer auto-loads, so deeper nodes stay out of context until entered;
+3. **breadcrumbs** — each node's `SKILL.md` ends with an index summary of its subtree and explicit instructions to **Read** its children.
+
+You load one layer and *walk*; you never load the pile.
+
+## The load mechanism it exploits (verified against the runtime)
+
+The design rests on one fact about Claude Code, which `skilltree` verifies rather than assumes:
+
+> Your context + Skill-tool menu = `~/.claude` (always, one layer) **+ every project directory you _Read into_** (its `CLAUDE.md` + `.claude/rules` + `.claude/skills`, dynamically, one layer). Descendants don't load until Read; out-of-project directories don't trigger it; **the trigger is the Read tool, not `cat`** (a shell `cat` of the same file injects nothing).
+
+So descending the tree is a **Read into the next node** — which loads exactly that node's layer and no more. That is why the breadcrumbs say **Read**, not `cat`: a `cat` reads the bytes but loads nothing.
+
+## Install
+
+```bash
+pip install -e .          # from a clone
+# or: pip install skilltree
+```
+
+This installs the `skilltree` CLI.
+
+## Quickstart
+
+```bash
+# 1. See the tree that is actually on disk
+skilltree discover ~/my-skills
+
+# 2. Check coherence — is it a tree, or a bare forest with stale wiring?
+skilltree cohere ~/my-skills          # exits non-zero on drift
+
+# 3. Tree-ify a flat forest IN PLACE (lossless: whole dirs moved, baggage kept,
+#    symlinks de-symlinked; every move journaled to .emit-journal.json)
+skilltree emit ~/my-skills --root-forest --name my-skills
+
+# 4. ...and undo it exactly, byte-for-byte, any time
+skilltree unemit ~/my-skills
+
+# 5. Search the tree (BM25), scoped to a coordinate subtree
+skilltree search ~/my-skills "deploy rollback" --scope 0.1
+```
+
+Programmatic use mirrors the CLI:
+
+```python
+from skilltree import discover, cohere, emit, materialize, SkillTree, TreeNode
+
+findings = cohere("~/my-skills")              # list[Finding] — the drift report
+emit("~/my-skills", root_forest=True)         # tree-ify, journaled
+materialize(SkillTree(TreeNode("root", "sc", children=[...])), "out/", coords=True)
+```
+
+## Subcommands
+
+One CLI for the whole skill-substrate toolkit — `skilltree <command> …`:
+
+| Command | What it does |
+|---|---|
+| `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) |
+| `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 |
+| `discover` · `validate` · `build` · `notify` · `watch` | read a tree · gate breadcrumb-resolvability · materialize from a manifest · write the notification rule · run the decoherence cron |
+
+`map` and `search` **fold the former standalone `skillmap` / `foldersearch` / `skillsearch` seedlings into one product**: `map` uses skilltree's own coordinate code (`assign_coords` / `skill_name`, no vendored copy), and `search` is one FTS5/BM25 engine where `--scope` is the only difference between coordinate-free and tree-aware search. The `<coord>-<name>` frontmatter and the Read-breadcrumb format are preserved for backward compatibility.
+
+## Self-management (it keeps itself coherent)
+
+A structure the platform won't maintain decays back to the flat forest it replaced — so `skilltree` maintains itself:
+
+- **`discover`** reconstructs the on-disk tree from reality, independent of any manifest.
+- **`cohere`** reports drift between reality and the engineered shape — a bare (unrooted) forest, a stale breadcrumb, a coordinate that no longer matches, a skill dropped in flat.
+- **`emit`** re-coheres in place; given a flat forest it tree-ifies it, **moving each skill directory whole** (all of its files preserved — no body-only re-render, no `rmtree`) and **de-symlinking** any symlink'd skill, journaling every move so **`unemit`** restores the prior state byte-for-byte.
+- A scheduled check (`skilltree watch <root>`) writes its verdict into a single managed rule, so a decohered tree announces itself in every subsequent session.
+
+## How a tree looks on disk
+
+```
+domain/.claude/skills/0-domain/SKILL.md          # root menu — the only node that auto-loads
+domain/A/.claude/skills/0.1-A/SKILL.md            # child A   — loaded only when Read
+domain/A/A1/.claude/skills/0.1.1-A1/SKILL.md      # grandchild — one level deeper
+domain/B/.claude/skills/0.2-B/SKILL.md
+```
+
+The root menu carries an index summary (so a query about `A1` still finds the branch that leads to it) and the descend breadcrumbs (the out-edges, expressed as the Read that loads them). A coordinate stands in for identity; a breadcrumb stands in for an edge — emulations of what a graph would hold natively.
+
+## Roadmap
+
+- **v1 — Claude Code** *(shipping)* — the tree, the front half (`discover`/`cohere`/`emit`/`unemit`), the decoherence watch. The descent mechanic is Claude-Code-specific by design.
+- **v2 — Cross-format adapters** — per-format, **not** symlinks: the descent mechanic doesn't generalize (Codex resolves once at cwd; Gemini eager-loads the whole tree). `SKILL.md` + `.agents/skills` is the portable foundation.
+- **v3 — Chaining** — compose skills into validated chains over the tree.
+
+Full detail in **[ROADMAP.md](ROADMAP.md)** — generated from [`roadmap.json`](roadmap.json) (the single source); the [site](site/index.html) renders it live. Run `python3 scripts/update_site.py` after editing the roadmap or changelog.
+
+## Papers
+
+Two papers document the project:
+
+- **"Flat versus Tree: Why Agent Skills Need a Graph"** — *the why.* The structural argument: a flat skill substrate starves the faculty agents actually run on; the correction is a tree traversed in `O(depth)`, not loaded in `O(#tools)`. → [`papers/flat-vs-tree.md`](papers/flat-vs-tree.md)
+- **"Coordinate-Addressed Skill Trees: Progressive Disclosure on a Flat Filesystem"** — *the how.* The coordinate scheme, the Read-breadcrumb tree, the `discover`/`cohere`/`emit`/`unemit` self-coherence loop, and the runtime-verified load mechanic. → [`papers/skilltree-paper.md`](papers/skilltree-paper.md)
+
+> arXiv submission is **pending an endorser**.
+
+## Changelog
+
+### 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**.
+
+### v0.1.0 — 2026-06-18
+- Initial release. The Read-breadcrumb tree (`materialize` + the traversability `validate` gate); the front half — `discover` (fs→tree), `cohere` (drift report), `emit` (lossless, journaled tree-ify of a forest), `unemit` (exact undo); the decoherence `watch` writing a self-managed notification rule; the CLI; the site + Dev Log. The auto-load mechanic — Read-into-a-dir injects its layer, `cat` does not, nested doesn't load — was verified against the runtime, not asserted. 56 tests · Python 3.11+ · MIT.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

agent_skilltree-0.2.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+agent_skilltree-0.2.0.dist-info/licenses/LICENSE,sha256=ffOw8Kmv_QBeCF_DLeFnCZ-t36WSZJ7ePU8nsibXqZ8,1064
+skilltree/__init__.py,sha256=DMs2CMCKOdQVYkrlHw183WFU7xAvj1PaCc77fLFg4TM,2385
+skilltree/cli.py,sha256=v1GYpuOenm6aj76LIxJzg2zbYTcQMgRrYfVY6htjgxM,15143
+skilltree/cohere.py,sha256=MTE1ggPr5GMKYkakjWhb7v-bcibwjEJSsMqaiDr8F00,22259
+skilltree/exchange.py,sha256=TrDbP8z63GHv_w2OuUn4vEARdkzWNma9qCu9_QLc3lI,4775
+skilltree/federation.py,sha256=pyJvkq0RidJjUlVHg5NwGuI_NWL4GOHtqJ8Vzi9rvUg,4492
+skilltree/forest.py,sha256=c8soqP5M-hVYhDBFIC8v1A7NXKRS9xgrvrF0vk8HdY0,4316
+skilltree/mapper.py,sha256=tatXqx3zBpz3fiimUa7yUHvNTRpie0GwVH4c5lGDpB0,4929
+skilltree/marketplace.py,sha256=EXVm_dlH6wQnn_BX8PYon65prcBzygsiykLT6XaRg8w,3047
+skilltree/materialize.py,sha256=IpUsYqHpsSDmoD0_oVTBIgTUh4pDh8gnt806ZHs90Z0,4234
+skilltree/model.py,sha256=IhUXJor0FjdI7LLlnSnp2sVTVh3p94W6CjqcS28xAJo,4721
+skilltree/registry.py,sha256=vRvAgo24EClESdbB5Rxvbf3TDgx7MTQY6Z6_7u3YsMg,4996
+skilltree/reports.py,sha256=l_UwQM80IMq6mZfcz6NTC4NV6-t_XelXTpd-qVUH9tk,3755
+skilltree/search.py,sha256=VF-zS6H30Ead1oZORGluVk2d4YP19kpZrG4kmkWj7NM,7368
+skilltree/validate.py,sha256=AL_e-AAHKxhHFTA9nB1vC9ZUensUcIjXNMplDKYX_bM,3683
+agent_skilltree-0.2.0.dist-info/METADATA,sha256=Rt_JM8vEUPVqIAe3PPNOtarluIjAuXvdDitJYjctvcw,9531
+agent_skilltree-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agent_skilltree-0.2.0.dist-info/entry_points.txt,sha256=E9xX8lbuUs-o3GhRzvOeoAXi60P4Z1nmGMRqZCTjKpQ,49
+agent_skilltree-0.2.0.dist-info/top_level.txt,sha256=K8HsBfiKMS6rOxiBlrCIsHB7_VbWDhc-qGiutVY6D3o,10
+agent_skilltree-0.2.0.dist-info/RECORD,,

agent_skilltree-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_skilltree-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+skilltree = skilltree.cli:main

agent_skilltree-0.2.0.dist-info/licenses/LICENSE

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

agent_skilltree-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+skilltree

skilltree/__init__.py

@@ -0,0 +1,64 @@
+"""SkillTree — a tree of skill dirs wired by links, with programmatic validation.
+
+The substrate won't auto-traverse it (no nested-.claude auto-load), so the
+validator is the system. Nodes are skill dirs of any type (ac/cor/sc/skill);
+edges are symlinks; descending a level = redirecting the active skills root.
+"""
+from __future__ import annotations
+
+__version__ = "0.2.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 .registry import (
+    Entry,
+    load_registry,
+    promote,
+    validate_contribution,
+    validate_registry,
+)
+from .registry import search as registry_search
+from .forest import build_forest, link_tree, list_links, unlink
+from .reports import (
+    list_reports,
+    mark_problem,
+    report_missed,
+    resolve,
+    summary as reports_summary,
+)
+from .search import build_index, search, search_tree, search_folder, DEFAULT_EXTS
+from .mapper import build_map, write_map
+from .cohere import (
+    Finding, cohere, discover, emit, unemit,
+    render_notifications, write_notifications, watch, NOTIFY_RULE,
+)
+from .federation import (
+    flatten_federation,
+    local_resolver,
+    register_child,
+    validate_federation,
+    walk_federation,
+)
+from .validate import Violation, is_valid, validate
+
+__all__ = [
+    "SkillTree", "TreeNode", "materialize", "validate", "is_valid", "Violation",
+    "Exchange", "Member", "load_exchange", "build_exchange", "validate_exchange",
+    "exchange_is_valid",
+    "Entry", "load_registry", "validate_registry", "validate_contribution",
+    "promote", "registry_search",
+    "walk_federation", "flatten_federation", "validate_federation",
+    "register_child", "local_resolver",
+    "link_tree", "build_forest", "list_links", "unlink",
+    "assign_coords", "skill_name",
+    "build_index", "search", "search_tree", "search_folder", "DEFAULT_EXTS",
+    "build_map", "write_map",
+    "discover", "cohere", "emit", "unemit", "Finding",
+    "render_notifications", "write_notifications", "watch", "NOTIFY_RULE",
+    "report_missed", "mark_problem", "list_reports", "resolve", "reports_summary",
+    "__version__",
+]

skilltree/cli.py

@@ -0,0 +1,315 @@
+"""skilltree — build a `cat`-breadcrumb tree of skill dirs from JSON, and validate it."""
+from __future__ import annotations
+
+from pathlib import Path
+import tempfile
+
+import click
+
+from .materialize import materialize, node_skill_md
+from .model import SkillTree, TreeNode
+from .validate import validate
+
+
+@click.group()
+@click.version_option(message="skilltree %(version)s")
+def main() -> None:
+    """SkillTree — a nested tree of skill dirs wired by `cat`-breadcrumbs (validated)."""
+
+
+@main.command(name="discover")
+@click.argument("root", type=click.Path(exists=True, file_okay=False, path_type=Path))
+def discover_cmd(root: Path) -> None:
+    """Read the live filesystem and print the tree that is ACTUALLY there
+    (every dir with a .claude/skills, nested by plain-dir path)."""
+    from .cohere import discover
+    from .model import skill_name
+
+    tree = discover(root)
+
+    def show(node, depth=0):
+        click.echo("  " * depth + f"{skill_name(node)} ({node.kind})")
+        for c in node.children:
+            show(c, depth + 1)
+    show(tree.root)
+
+
+@main.command(name="cohere")
+@click.argument("root", type=click.Path(exists=True, file_okay=False, path_type=Path))
+def cohere_cmd(root: Path) -> None:
+    """Report DECOHERENCE: how the on-disk tree drifted from its engineered shape
+    (bare forest, stale breadcrumbs, coord drift, strays). Exit 1 if any drift —
+    so a cron can notify on a non-zero exit."""
+    from .cohere import cohere
+    findings = cohere(root)
+    if not findings:
+        click.echo("✓ coherent — the tree shape and the breadcrumbs agree")
+        return
+    click.echo(f"⚠ {len(findings)} decoherence finding(s):")
+    for f in findings:
+        click.echo(f"  - {f}")
+    raise SystemExit(1)
+
+
+@main.command(name="emit")
+@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:
+    """Re-cohere IN PLACE: reassign coords + rewrite breadcrumbs/index from the
+    canonical shape (non-destructive). With --root-forest, root a bare forest."""
+    from .cohere import emit
+    report = emit(root, root_forest=root_forest, forest_name=forest_name)
+    if not report.get("ok"):
+        click.echo(f"✗ {report.get('error')}")
+        raise SystemExit(1)
+    extra = " (synthesized root)" if report.get("synthesized_root") else ""
+    moves = f", {report.get('moves')} moved" if report.get("moves") else ""
+    click.echo(f"✓ emitted {report['nodes']} node(s) under {report['root']}{extra}{moves}")
+    if report.get("journal"):
+        click.echo(f"  journal: {report['journal']}  (reverse with `skilltree unemit`)")
+
+
+@main.command(name="unemit")
+@click.argument("root", type=click.Path(exists=True, file_okay=False, path_type=Path))
+def unemit_cmd(root: Path) -> None:
+    """Reverse the last tree-ifying `emit`: replay `.emit-journal.json` backwards —
+    move every relocated skill dir back, restore its SKILL.md, drop the synthesized
+    root + manifest. Lossless undo."""
+    from .cohere import unemit
+    rep = unemit(root)
+    if not rep.get("ok"):
+        click.echo(f"✗ {rep.get('error')}")
+        raise SystemExit(1)
+    click.echo(f"✓ reversed: {rep['moved_back']} dir(s) moved back, {rep['removed']} synthesized node(s) removed")
+
+
+_DEFAULT_RULES = Path.home() / ".claude" / "rules"
+
+
+@main.command(name="notify")
+@click.argument("root", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.option("--rules-dir", type=click.Path(path_type=Path), default=None,
+              help="where to write the managed rule (default ~/.claude/rules)")
+def notify_cmd(root: Path, rules_dir: Path | None) -> None:
+    """One decoherence check → (re)write the self-managed `system_notifications`
+    rule. READ-ONLY on the tree; only the rule file changes. Exit 1 on any drift."""
+    from .cohere import write_notifications
+    rep = write_notifications(root, rules_dir=rules_dir or _DEFAULT_RULES)
+    state = "nominal" if rep["nominal"] else f"{rep['errors']} error(s), {rep['warnings']} warning(s)"
+    wrote = "rewrote" if rep["changed"] else "unchanged"
+    click.echo(f"[SKILLTREE] {state} — {wrote} {rep['path']}")
+    raise SystemExit(0 if rep["nominal"] else 1)
+
+
+@main.command(name="watch")
+@click.argument("root", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.option("--rules-dir", type=click.Path(path_type=Path), default=None,
+              help="where to write the managed rule (default ~/.claude/rules)")
+@click.option("--interval", default=300, type=float, help="seconds between checks (default 300)")
+@click.option("--once", is_flag=True, help="run a single check and exit (for testing)")
+def watch_cmd(root: Path, rules_dir: Path | None, interval: float, once: bool) -> None:
+    """The decoherence cron: every --interval seconds, re-check the tree and refresh
+    the `system_notifications` rule. Start as a background process. READ-ONLY on the
+    tree (it only writes the rule); the FIX is agent-initiated via the skilltree skill."""
+    from .cohere import watch
+    rd = rules_dir or _DEFAULT_RULES
+    click.echo(f"[SKILLTREE] watching {root} every {interval:.0f}s → {rd}")
+    watch(root, rules_dir=rd, interval=interval, iterations=1 if once else None)
+
+
+@main.command(name="tree")
+@click.argument("root", type=click.Path(exists=True, file_okay=False, path_type=Path))
+def tree_cmd(root: Path) -> None:
+    """Show the coordinate tree on disk — every node with its `<coord>-<name>` address —
+    by reading the live filesystem (the materialized / skilltree-mapped structure)."""
+    from .cohere import discover
+    from .model import skill_name
+    root_node = discover(root).root
+
+    def show(node, depth: int = 0) -> None:
+        click.echo("  " * depth + f"{skill_name(node)} ({node.kind})")
+        for c in node.children:
+            show(c, depth + 1)
+    show(root_node)
+
+
+@main.command(name="map")
+@click.argument("folder", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.option("--write", is_flag=True, help="write CLAUDE.md into the folder (default: print to stdout)")
+def map_cmd(folder: Path, write: bool) -> None:
+    """Render a flat folder into ONE coordinate-addressed CLAUDE.md — a Folder Map + an
+    addressable Index + branch summaries — for progressive disclosure (open a branch, descend
+    to the coordinate you need). Uses skilltree's own coordinate scheme."""
+    from .mapper import build_map, write_map
+    if write:
+        click.echo(f"wrote {write_map(folder)}")
+    else:
+        click.echo(build_map(folder))
+
+
+@main.command(name="search")
+@click.argument("folder", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.argument("query")
+@click.option("--scope", "scope_coord", default=None,
+              help="restrict to a coordinate subtree, e.g. 0.1 (when the folder carries skilltree coordinates)")
+@click.option("--ext", default=None, help="comma-separated extensions (default: .md,.txt,.mdx,.rst)")
+@click.option("--limit", default=10, type=int)
+def search_cmd(folder: Path, query: str, scope_coord: str | None, ext: str | None, limit: int) -> None:
+    """FTS5/BM25 search over ANY folder. `--scope` restricts to a coordinate subtree when the
+    folder carries skilltree coordinates; on a plain folder it is coordinate-free search."""
+    from .search import search_folder, DEFAULT_EXTS
+    exts = (tuple(e if e.startswith(".") else "." + e for e in ext.split(",")) if ext else DEFAULT_EXTS)
+    hits = search_folder(folder, query, scope_coord=scope_coord, exts=exts, limit=limit)
+    where = f" in {scope_coord}" if scope_coord else ""
+    if not hits:
+        click.echo(f"(no matches{where} for: {query})")
+        return
+    click.echo(f"(top {len(hits)}{where} for: {query})\n")
+    for i, h in enumerate(hits, 1):
+        coord = f"[{h['coord']}] " if h["coord"] else ""
+        desc = f" — {h['description']}" if h["description"] else ""
+        click.echo(f"{i}. {coord}{h['name']}{desc}")
+        click.echo(f"   {h['path']}")
+
+
+@main.command(name="report-missed")
+@click.option("--needed", required=True, help="the skill/capability that was needed")
+@click.option("--happened", required=True, help="what you did instead / what went wrong")
+@click.option("--suggests", default=None, help="proposed skill name + one-line purpose")
+@click.option("--by", default="agent")
+@click.option("--reports", "reports_path", default=None, help="reports store (default ~/.claude/skill-reports.json)")
+def report_missed_cmd(needed, happened, suggests, by, reports_path):
+    """File a missed-skill report (a needed skill didn't exist)."""
+    from .reports import DEFAULT_REPORTS, report_missed
+    e = report_missed(reports_path or DEFAULT_REPORTS, needed=needed, happened=happened, suggests=suggests, by=by)
+    click.echo(f"✓ filed {e['id']} (missed_skill) — needed: {needed!r}")
+
+
+@main.command(name="mark-problem")
+@click.option("--skill", required=True, help="the skill that should have fired")
+@click.option("--expected", required=True, help="what you expected it to do")
+@click.option("--happened", required=True, help="what happened instead")
+@click.option("--by", default="user")
+@click.option("--reports", "reports_path", default=None)
+def mark_problem_cmd(skill, expected, happened, by, reports_path):
+    """Mark 'expected this skill to be used, but it wasn't'."""
+    from .reports import DEFAULT_REPORTS, mark_problem
+    e = mark_problem(reports_path or DEFAULT_REPORTS, skill=skill, expected=expected, happened=happened, by=by)
+    click.echo(f"✓ filed {e['id']} (expected_not_used) — skill: {skill!r}")
+
+
+@main.command(name="reports")
+@click.option("--reports", "reports_path", default=None)
+@click.option("--kind", default=None)
+def reports_cmd(reports_path, kind):
+    """Show the open skill reports (the improver's queue)."""
+    from .reports import DEFAULT_REPORTS, list_reports, summary
+    rp = reports_path or DEFAULT_REPORTS
+    s = summary(rp)
+    click.echo(f"reports: {s['open']} open / {s['total']} total  {s['open_by_kind']}")
+    for r in list_reports(rp, kind=kind):
+        head = r.get("needed") or r.get("skill") or "?"
+        click.echo(f"  {r['id']} [{r['kind']}] by {r['by']}: {head}")
+
+
+@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:
+    """Materialize a SkillTree from a JSON MANIFEST into ROOT, then validate."""
+    tree = SkillTree.load(manifest)
+    materialize(tree, root)
+    issues = validate(root)
+    errors = [v for v in issues if v.severity == "error"]
+    click.echo(f"built {len(tree.nodes())} nodes at {root}")
+    for v in issues:
+        click.echo(f"  {'✗' if v.severity == 'error' else '⚠'} [{v.where}] {v.message}")
+    if errors:
+        raise SystemExit(f"✗ INVALID — {len(errors)} error(s)")
+    click.echo(f"✓ valid — root: cat {node_skill_md(root, tree.root.name)}")
+
+
+@main.command(name="validate")
+@click.argument("root", type=click.Path(exists=True, file_okay=False, path_type=Path))
+def validate_cmd(root: Path) -> None:
+    """Validate a materialized SkillTree at ROOT."""
+    issues = validate(root)
+    for v in issues:
+        click.echo(f"  {'✗' if v.severity == 'error' else '⚠'} [{v.where}] {v.message}")
+    if any(v.severity == "error" for v in issues):
+        raise SystemExit("✗ INVALID")
+    click.echo("✓ valid — every breadcrumb resolves.")
+
+
+@main.group()
+def exchange() -> None:
+    """Many skill trees in one repo, under a master."""
+
+
+@exchange.command(name="build")
+@click.argument("manifest", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.argument("repo", type=click.Path(path_type=Path))
+def exchange_build(manifest: Path, repo: Path) -> None:
+    """Materialize every member tree + the master from an exchange MANIFEST."""
+    from .exchange import build, load_exchange, validate
+    ex = load_exchange(manifest)
+    master = build(ex, repo)
+    issues = validate(repo, ex)
+    click.echo(f"built exchange '{ex.name}' — {len(ex.trees)} tree(s) + master at {master}")
+    for v in issues:
+        click.echo(f"  {'✗' if v.severity == 'error' else '⚠'} [{v.where}] {v.message}")
+    if any(v.severity == "error" for v in issues):
+        raise SystemExit("✗ INVALID")
+    click.echo("✓ valid — master + every member tree resolve.")
+
+
+@exchange.command(name="validate")
+@click.argument("manifest", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.argument("repo", type=click.Path(exists=True, file_okay=False, path_type=Path))
+def exchange_validate(manifest: Path, repo: Path) -> None:
+    """Validate a built exchange REPO against its MANIFEST."""
+    from .exchange import load_exchange, validate
+    for v in validate(repo, load_exchange(manifest)):
+        click.echo(f"  {'✗' if v.severity == 'error' else '⚠'} [{v.where}] {v.message}")
+
+
+@main.command()
+def demo() -> None:
+    """Build a breadcrumb tree, walk it by `cat`, validate, then break a breadcrumb."""
+    tree = SkillTree(TreeNode("cc-skill-tree", "sc", description="root of the cognition skill tree", children=[
+        TreeNode("debug", "cor", description="how to debug", children=[
+            TreeNode("symptom-attn", "ac", description="attend to the symptom"),
+        ]),
+        TreeNode("explain", "cor", description="how to explain", children=[
+            TreeNode("simplify-attn", "ac", description="attend to the simplest form"),
+        ]),
+    ]))
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp) / "cc_tree_test"
+        materialize(tree, root)
+
+        click.echo("══ 1. only the ROOT auto-loads; everything else is reached by `cat` ══")
+        rootmd = node_skill_md(root, "cc-skill-tree")
+        click.echo(f"  auto-loaded: {rootmd}")
+        click.echo("  ── its body (the breadcrumbs) ──")
+        click.echo("\n".join("    " + l for l in rootmd.read_text().splitlines() if l.strip()))
+
+        click.echo("\n══ 2. follow a breadcrumb down to a leaf ══")
+        debugmd = node_skill_md(root / "debug", "debug")
+        leafmd = node_skill_md(root / "debug" / "symptom-attn", "symptom-attn")
+        click.echo(f"  cat {debugmd}  → then → cat {leafmd}")
+
+        click.echo("\n══ 3. validate (the harness) ══")
+        click.echo(f"  {'✓ valid' if not validate(root) else 'issues:'}")
+        for v in validate(root):
+            click.echo(f"    {v.severity}: [{v.where}] {v.message}")
+
+        click.echo("\n══ 4. corrupt a breadcrumb (rename a child dir); substrate stays silent ══")
+        (root / "debug" / "symptom-attn").rename(root / "debug" / "renamed-away")
+        for v in validate(root):
+            click.echo(f"    ✗ [{v.where}] {v.message}")
+
+
+if __name__ == "__main__":
+    main()