notegraph 0.2.0__tar.gz

notegraph-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 송재훈 (Jaehoon Song)
+
+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.

notegraph-0.2.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: notegraph
+Version: 0.2.0
+Summary: Decision-graph and goal notebook for a git repo, shared across every worktree
+Author-email: 송재훈 <sjh030504@i-screammedia.com>
+License: MIT
+Project-URL: Homepage, https://github.com/sjh354/note-cli
+Project-URL: Source, https://github.com/sjh354/note-cli
+Project-URL: Issues, https://github.com/sjh354/note-cli/issues
+Project-URL: Changelog, https://github.com/sjh354/note-cli/blob/main/CHANGELOG.md
+Keywords: git,worktree,notebook,decision-graph,agent,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# notegraph
+
+A decision-graph and goal notebook for a git repo. One store per repo, shared
+by every worktree, kept in `<repo>/.git/notes/` — so it never appears in the
+working tree and needs no `.gitignore` entry.
+
+    pipx install notegraph    # once published; for a checkout: pipx install -e .
+    note init
+    note goal --set "ship an education image generator" \
+      --criterion "consistency:3:the reference style holds across seeds" \
+      --criterion "legibility:1:rendered text is readable at 512px"
+
+    note add "legible text at 512px" --type goal          # -> 1
+    note add "arm B1_P2" --type attempt --tags p2         # -> 2
+    note link 2 1 --rel targets
+    note score 2 consistency=1.0 legibility=0.8 --note "best so far"
+    note goals
+
+    note status                                           # everything at a glance
+    note check                                            # exit 1 if the loop is open
+    note supersede 2 "arm B1_P2, corrected"               # append-only correction
+
+Three names, deliberately: the PyPI distribution is **notegraph**, the git repo
+is **note-cli**, and the command you type is **note**. `note-cli` was taken on
+PyPI by similarity to an existing `notecli`.
+
+Requires a POSIX system (Linux, macOS, WSL) — the store is locked with
+`fcntl.flock`. MIT licensed.
+
+Design: [`docs/superpowers/specs/2026-09-17-note-cli-design.md`](docs/superpowers/specs/2026-09-17-note-cli-design.md)
+
+For an agent working in this repo: `note skill --install`, then follow the
+`note` skill.

notegraph-0.2.0/README.md

@@ -0,0 +1,33 @@
+# notegraph
+
+A decision-graph and goal notebook for a git repo. One store per repo, shared
+by every worktree, kept in `<repo>/.git/notes/` — so it never appears in the
+working tree and needs no `.gitignore` entry.
+
+    pipx install notegraph    # once published; for a checkout: pipx install -e .
+    note init
+    note goal --set "ship an education image generator" \
+      --criterion "consistency:3:the reference style holds across seeds" \
+      --criterion "legibility:1:rendered text is readable at 512px"
+
+    note add "legible text at 512px" --type goal          # -> 1
+    note add "arm B1_P2" --type attempt --tags p2         # -> 2
+    note link 2 1 --rel targets
+    note score 2 consistency=1.0 legibility=0.8 --note "best so far"
+    note goals
+
+    note status                                           # everything at a glance
+    note check                                            # exit 1 if the loop is open
+    note supersede 2 "arm B1_P2, corrected"               # append-only correction
+
+Three names, deliberately: the PyPI distribution is **notegraph**, the git repo
+is **note-cli**, and the command you type is **note**. `note-cli` was taken on
+PyPI by similarity to an existing `notecli`.
+
+Requires a POSIX system (Linux, macOS, WSL) — the store is locked with
+`fcntl.flock`. MIT licensed.
+
+Design: [`docs/superpowers/specs/2026-09-17-note-cli-design.md`](docs/superpowers/specs/2026-09-17-note-cli-design.md)
+
+For an agent working in this repo: `note skill --install`, then follow the
+`note` skill.

notegraph-0.2.0/note_cli/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: note
+description: Use when working on a repo that has a note store — record each attempt in the decision graph and score it against the project's goal criteria before moving on.
+---
+
+# note
+
+`note` keeps one decision graph and one goal per repo, in `<repo>/.git/notes/`.
+Every git worktree of the repo shares that store, so what you record is visible
+to agents working other branches in parallel.
+
+## The loop
+
+1. **Read the standard.** `note goal` prints the final goal and its weighted
+   criteria, each with a one-line rubric. Score against those rubrics, never
+   against a standard you invent.
+2. **Do the work.**
+3. **Record the attempt.** `note add "what you tried" --type attempt --tags arm-b1`
+   prints its id. The current branch is tagged automatically.
+4. **Point it at a goal.** `note link <attempt> <goal> --rel targets`. A scored
+   attempt that targets nothing shows up under `(unassigned)` in `note goals` —
+   that is a linking mistake, not a category of work.
+5. **Score it.** `note score <attempt> consistency=0.8 legibility=0.6 --note "why"`.
+   Each criterion is 0.0–1.0. The `--note` is where the justification goes;
+   a score with no stated reason cannot be argued with later.
+
+6. **Confirm the loop closed.** `note check` exits nonzero while any attempt
+   targets no goal or carries no score, and names them. Run it before you
+   consider a piece of work done.
+
+## Rules
+
+- **Never score a goal node.** Scores go on attempts. A goal's score is derived
+  as the maximum over the attempts that target it.
+- **Re-scoring replaces wholesale.** A criterion left out of a new score line
+  counts as 0, not as its previous value. Submit the full set every time.
+- **Only criteria named in the current goal are accepted.** If a rubric no
+  longer fits the work, change the goal (`note goal --set ... --criterion ...`)
+  rather than inventing a criterion at score time.
+- **Totals are recomputed against the current goal.** When the goal moves, old
+  attempts visibly drop until they are re-judged. That is correct.
+
+## Correcting a node
+
+Nothing is ever edited in place. `note supersede <id> "corrected content"`
+appends a new node and an edge `old -superseded_by-> new`, which moves the
+frontier to the new node and takes the old one out of `note tails`. Type and
+tags are inherited unless you pass new ones.
+
+## Orientation
+
+- `note status` — goal, criteria, per-goal best and the frontier, in one screen
+- `note check` — what still breaks the loop (exit 1 if anything does)
+- `note goals` — per-goal best attempt and which one set it
+- `note tails` — the working frontier (goal nodes excluded)
+- `note trace <id>` — what an attempt ultimately feeds
+- `note trace <goal-id> --up` — which attempts feed a goal
+- `note search <keyword>` — find a node to start from

notegraph-0.2.0/note_cli/__init__.py

@@ -0,0 +1,7 @@
+"""note — a decision-graph and goal notebook for a git repo."""
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("notegraph")
+except PackageNotFoundError:          # running from a source tree, not installed
+    __version__ = "0+unknown"

notegraph-0.2.0/note_cli/_cli_check.py

@@ -0,0 +1,103 @@
+"""End-to-end drive of every command. Run: python -m note_cli._cli_check"""
+import os
+import subprocess
+import tempfile
+
+from note_cli.cli import main
+
+
+def run(*args):
+    main(list(args))
+
+
+def main_check():
+    os.chdir(tempfile.mkdtemp())
+    subprocess.run(["git", "init", "-q"], check=True)
+
+    try:
+        run("heads")
+        raise AssertionError("expected SystemExit before init")
+    except SystemExit as e:
+        assert "note init" in str(e), e
+
+    run("init")
+    run("init")                                   # idempotent, must not raise
+    run("goal", "--set", "ship it",
+        "--criterion", "consistency:3:style holds: across seeds",
+        "--criterion", "legibility:1:readable")
+    run("goal")
+    run("goal", "--history")
+
+    run("add", "legible text", "--type", "goal")           # id 1
+    run("add", "arm B1_P1", "--type", "attempt", "--tags", "p1,ref")   # id 2
+    run("add", "arm B1_P2", "--type", "attempt")           # id 3
+    run("link", "2", "1", "--rel", "targets")
+    run("link", "3", "1", "--rel", "targets")
+    run("link", "2", "3", "--rel", "leads_to")
+    run("score", "2", "consistency=0.4")
+    run("score", "3", "consistency=1.0", "legibility=0.8", "--note", "best so far")
+    run("goals")
+    run("show", "3")        # 2 -leads_to-> 3 and nothing else: not yet a merge
+    run("add", "arm B1_P3", "--type", "attempt")           # id 4
+    run("link", "4", "3", "--rel", "leads_to")
+    run("show", "3")        # now in-degree 2: must print the merge-point line
+    run("search", "B1")
+    run("trace", "2")
+    run("trace", "1", "--up")
+    run("heads")
+    run("tails")
+    run("graph")
+    run("graph", "--from", "2", "--depth", "1")
+
+    from note_cli import store
+    assert (store.store_dir() / "graph.dot").exists()
+
+    # `check` must exit nonzero while an attempt is untargeted or unscored
+    run("add", "unlinked try", "--type", "attempt")         # id 5
+    try:
+        run("check")
+        raise AssertionError("expected SystemExit(1) with a loose attempt")
+    except SystemExit as e:
+        assert e.code == 1, e.code
+    run("link", "5", "1", "--rel", "targets")
+    try:
+        run("check")
+        raise AssertionError("expected SystemExit(1) with an unscored attempt")
+    except SystemExit as e:
+        assert e.code == 1, e.code
+    run("score", "5", "consistency=0.1")
+    # node 4 was added earlier as a merge-point helper and never targeted a
+    # goal — `check` caught that, which is the point of the command
+    run("link", "4", "1", "--rel", "targets")
+    run("score", "4", "consistency=0.5")
+    run("check")                                            # now clean: must not raise
+
+    # supersede: the new node becomes the frontier, the old drops out
+    before = {n["id"] for n in graphtails()}
+    run("supersede", "5", "unlinked try, corrected")         # id 6
+    after = {n["id"] for n in graphtails()}
+    assert 5 not in after and 6 in after, (before, after)
+
+    run("status")
+
+    # --version must report what the package metadata says, so a bug report
+    # names a real release
+    from note_cli import __version__
+    try:
+        run("--version")
+        raise AssertionError("argparse should exit after --version")
+    except SystemExit as e:
+        assert e.code == 0, e.code
+    import importlib.metadata as md
+    assert __version__ == md.version("notegraph"), (__version__, md.version("notegraph"))
+
+    print("cli: ok")
+
+
+def graphtails():
+    from note_cli import graph as g, store
+    return g.tails(store.read("nodes.jsonl"), store.read("edges.jsonl"))
+
+
+if __name__ == "__main__":
+    main_check()

notegraph-0.2.0/note_cli/_concurrency_check.py

@@ -0,0 +1,40 @@
+"""Two processes adding under the lock must produce two distinct ids.
+
+Separate from store.demo() because it forks; run it directly:
+    python -m note_cli._concurrency_check
+"""
+import os
+import subprocess
+import tempfile
+
+from note_cli import store
+
+
+def main():
+    d = tempfile.mkdtemp()
+    os.chdir(d)
+    subprocess.run(["git", "init", "-q"], check=True)
+    store.init()
+
+    reads, writes = zip(*(os.pipe() for _ in range(8)))
+    for i, w in enumerate(writes):
+        if os.fork() == 0:
+            nid = store.add_node(f"child {i}")
+            os.write(w, str(nid).encode())
+            os._exit(0)
+    for w in writes:
+        os.close(w)
+    ids = []
+    for r in reads:
+        ids.append(int(os.read(r, 16)))
+        os.close(r)
+    for _ in writes:
+        os.wait()
+
+    assert len(set(ids)) == len(ids), f"duplicate ids under concurrency: {sorted(ids)}"
+    assert sorted(ids) == list(range(1, len(ids) + 1)), sorted(ids)
+    print("concurrency: ok")
+
+
+if __name__ == "__main__":
+    main()

notegraph-0.2.0/note_cli/cli.py

@@ -0,0 +1,306 @@
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+if not hasattr(__import__("os"), "fork"):
+    # store.py locks with fcntl.flock, which Windows has no equivalent of.
+    # pip installs regardless of the POSIX classifier, so say so plainly
+    # instead of letting `import fcntl` raise ModuleNotFoundError.
+    sys.exit("note requires a POSIX system (Linux, macOS, WSL): it locks the "
+             "store with fcntl.flock, which Windows does not provide.")
+
+from note_cli import __version__
+from note_cli import goal as goalmod
+from note_cli import graph as graphmod
+from note_cli import render, store
+
+
+def _nodes_edges():
+    return store.read("nodes.jsonl"), store.read("edges.jsonl")
+
+
+def _line(n):
+    tags = f" [{','.join(n['tags'])}]" if n.get("tags") else ""
+    return f"  {n['id']:>4}  {n['type']:<10} {n['content']}{tags}  ({n.get('branch')})"
+
+
+def _print_nodes(title, nodes):
+    print(title)
+    for n in nodes:
+        print(_line(n))
+    if not nodes:
+        print("  (none)")
+
+
+def cmd_init(args):
+    path, created = store.init()
+    print(f"store: {path}")
+    print(f"created: {', '.join(created)}" if created else "already initialized")
+
+
+def cmd_goal(args):
+    if args.history:
+        for i, g in enumerate(goalmod.history(), 1):
+            print(f"{i}. [{g['timestamp']}] {g['goal']}")
+            for c in g["criteria"]:
+                print(f"     {c['weight']:<5} {c['name']}: {c['rubric']}")
+        return
+    if args.set is not None:
+        criteria = [goalmod.parse_criterion(c) for c in (args.criterion or [])]
+        if not criteria:
+            raise SystemExit("--set needs at least one --criterion name:weight:rubric")
+        goalmod.set_goal(args.set, criteria)
+        print(f"goal set, {len(criteria)} criteria")
+        return
+    g = goalmod.current_goal()
+    if not g:
+        raise SystemExit("no goal set — run `note goal --set ... --criterion ...`")
+    print(g["goal"])
+    denom = sum(c["weight"] for c in g["criteria"])
+    for c in g["criteria"]:
+        print(f"  {c['weight'] / denom:>5.0%}  {c['name']}: {c['rubric']}")
+
+
+def cmd_add(args):
+    tags = args.tags.split(",") if args.tags else []
+    print(store.add_node(args.content, type=args.type, tags=tags))
+
+
+def cmd_link(args):
+    store.add_edge(args.src, args.dst, args.rel)
+    print(f"{args.src} -{args.rel}-> {args.dst}")
+
+
+def cmd_score(args):
+    scores = {}
+    for pair in args.pairs:
+        if "=" not in pair:
+            raise SystemExit(f"want name=value, got {pair!r}")
+        k, v = pair.split("=", 1)
+        try:
+            scores[k] = float(v)
+        except ValueError:
+            raise SystemExit(f"{k}: {v!r} is not a number")
+        if not 0.0 <= scores[k] <= 1.0:
+            raise SystemExit(f"{k}: scores are 0.0-1.0, got {scores[k]}")
+    print(f"{goalmod.add_score(args.id, scores, args.note):.3f}")
+
+
+def cmd_goals(args):
+    rows, unassigned = goalmod.rollup()
+    for n, best in rows:
+        if best:
+            total, aid, ts = best
+            print(f"{n['id']:>4}  {n['content']}\n        best {total:.3f} from #{aid} ({ts})")
+        else:
+            print(f"{n['id']:>4}  {n['content']}\n        (no scored attempts)")
+    if unassigned:
+        print("\n(unassigned) — scored but targeting no goal:")
+        for n, total, ts in unassigned:
+            print(f"{n['id']:>4}  {total:.3f}  {n['content']} ({ts})")
+
+
+def cmd_supersede(args):
+    tags = args.tags.split(",") if args.tags else []
+    print(store.supersede(args.id, args.content, type=args.type, tags=tags))
+
+
+def cmd_check(args):
+    """Exit nonzero while any attempt is loose, so a hook or an agent can gate
+    on it rather than trusting itself to remember the loop."""
+    untargeted, unscored = goalmod.unfinished()
+    if not untargeted and not unscored:
+        print("clean: every attempt targets a goal and carries a score")
+        return
+    if untargeted:
+        print("attempts targeting no goal — `note link <id> <goal> --rel targets`:")
+        for n in untargeted:
+            print(_line(n))
+    if unscored:
+        print("attempts with no score — `note score <id> name=0.0-1.0`:")
+        for n in unscored:
+            print(_line(n))
+    raise SystemExit(1)
+
+
+def cmd_status(args):
+    g = goalmod.current_goal()
+    if not g:
+        print("no goal set — run `note goal --set ... --criterion ...`")
+    else:
+        print(g["goal"])
+        denom = sum(c["weight"] for c in g["criteria"])
+        for c in g["criteria"]:
+            print(f"  {c['weight'] / denom:>5.0%}  {c['name']}: {c['rubric']}")
+    print()
+    cmd_goals(args)
+    nodes, edges = _nodes_edges()
+    _print_nodes("\nfrontier:", graphmod.tails(nodes, edges))
+
+
+def cmd_show(args):
+    nodes, edges = _nodes_edges()
+    by_id = {n["id"]: n for n in nodes}
+    if args.id not in by_id:
+        raise SystemExit(f"no node {args.id}")
+    n = by_id[args.id]
+    print(f"#{n['id']} [{n['type']}] {n['content']}")
+    print(f"  tags: {', '.join(n.get('tags') or []) or '-'}")
+    print(f"  branch: {n.get('branch')}   {n['timestamp']}")
+    s = goalmod.latest_scores().get(args.id)
+    if s:
+        g = goalmod.current_goal()
+        total = goalmod.weighted_total(s["scores"], g["criteria"] if g else [])
+        print(f"  score: {total:.3f}  {s['scores']}  ({s['timestamp']})")
+        if s.get("note"):
+            print(f"         {s['note']}")
+    if args.id in {m["id"] for m in graphmod.merges(nodes, edges)}:
+        print("  (merge point: two or more lines of work converge here)")
+    for e in edges:
+        if e["from"] == args.id:
+            print(f"  -> {e['to']:<4} {e['relation']}")
+        if e["to"] == args.id:
+            print(f"  <- {e['from']:<4} {e['relation']}")
+
+
+def cmd_search(args):
+    k = args.keyword.lower()
+    nodes, _ = _nodes_edges()
+    _print_nodes(f"matches for {args.keyword!r}:",
+                 [n for n in nodes
+                  if k in n["content"].lower()
+                  or any(k in t.lower() for t in n.get("tags") or [])])
+
+
+def cmd_trace(args):
+    nodes, edges = _nodes_edges()
+    by_id = {n["id"]: n for n in nodes}
+    if args.id not in by_id:
+        raise SystemExit(f"no node {args.id}")
+
+    def show(tree, depth, rel=None):
+        nid, kids = tree
+        n = by_id.get(nid)
+        arrow = f"-{rel}-> " if rel else ""
+        print("  " * depth + f"{arrow}#{nid} {n['content'] if n else '?'}")
+        for r, kid in kids:
+            show(kid, depth + 1, r)
+
+    show(graphmod.trace(args.id, edges, args.direction), 0)
+
+
+def cmd_heads(args):
+    nodes, edges = _nodes_edges()
+    _print_nodes("heads:", graphmod.heads(nodes, edges))
+
+
+def cmd_tails(args):
+    nodes, edges = _nodes_edges()
+    _print_nodes("tails:", graphmod.tails(nodes, edges))
+
+
+def cmd_graph(args):
+    nodes, edges = _nodes_edges()
+    if args.frm is not None:
+        keep = graphmod.subgraph(args.frm, edges, args.depth)
+        nodes = [n for n in nodes if n["id"] in keep]
+        edges = [e for e in edges if e["from"] in keep and e["to"] in keep]
+    src = render.dot_source(nodes, edges, goalmod.current_goal())
+    dot_file, svg = render.write_graph(store.require_store(), src)
+    print(f"wrote {dot_file}")
+    if svg:
+        print(f"wrote {svg}")
+    else:
+        print("graphviz `dot` not found — install it to also render an .svg")
+
+
+def cmd_skill(args):
+    src = Path(__file__).parent / "SKILL.md"
+    dst = Path.home() / ".claude" / "skills" / "note" / "SKILL.md"
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(src, dst)
+    print(f"wrote {dst}")
+
+
+def build_parser():
+    p = argparse.ArgumentParser(prog="note", description=__doc__)
+    p.add_argument("--version", action="version", version=f"note {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("init", help="create the store").set_defaults(fn=cmd_init)
+
+    g = sub.add_parser("goal", help="show or set the final goal")
+    g.add_argument("--set")
+    g.add_argument("--criterion", action="append", metavar="name:weight:rubric")
+    g.add_argument("--history", action="store_true")
+    g.set_defaults(fn=cmd_goal)
+
+    a = sub.add_parser("add", help="append a node")
+    a.add_argument("content")
+    a.add_argument("--type", default="note")
+    a.add_argument("--tags")
+    a.set_defaults(fn=cmd_add)
+
+    ln = sub.add_parser("link", help="append an edge")
+    ln.add_argument("src", type=int)
+    ln.add_argument("dst", type=int)
+    ln.add_argument("--rel", required=True)
+    ln.set_defaults(fn=cmd_link)
+
+    sc = sub.add_parser("score", help="score an attempt against the goal criteria")
+    sc.add_argument("id", type=int)
+    sc.add_argument("pairs", nargs="+", metavar="name=0.0-1.0")
+    sc.add_argument("--note")
+    sc.set_defaults(fn=cmd_score)
+
+    sub.add_parser("goals", help="per-goal best attempt").set_defaults(fn=cmd_goals)
+    sub.add_parser("status", help="goal, criteria, best attempts and frontier"
+                   ).set_defaults(fn=cmd_status)
+    sub.add_parser("check", help="exit 1 if any attempt is untargeted or unscored"
+                   ).set_defaults(fn=cmd_check)
+
+    sp = sub.add_parser("supersede", help="correct a node with a new one")
+    sp.add_argument("id", type=int)
+    sp.add_argument("content")
+    sp.add_argument("--type")
+    sp.add_argument("--tags")
+    sp.set_defaults(fn=cmd_supersede)
+
+    sh = sub.add_parser("show", help="one node in full")
+    sh.add_argument("id", type=int)
+    sh.set_defaults(fn=cmd_show)
+
+    se = sub.add_parser("search", help="substring match over content and tags")
+    se.add_argument("keyword")
+    se.set_defaults(fn=cmd_search)
+
+    tr = sub.add_parser("trace", help="DFS from a node")
+    tr.add_argument("id", type=int)
+    tr.add_argument("--up", dest="direction", action="store_const", const="up")
+    tr.add_argument("--down", dest="direction", action="store_const", const="down")
+    tr.add_argument("--both", dest="direction", action="store_const", const="both")
+    tr.set_defaults(fn=cmd_trace, direction="down")
+
+    sub.add_parser("heads", help="in-degree-0 work nodes").set_defaults(fn=cmd_heads)
+    sub.add_parser("tails", help="the working frontier").set_defaults(fn=cmd_tails)
+
+    gr = sub.add_parser("graph", help="emit Graphviz DOT")
+    gr.add_argument("--from", dest="frm", type=int)
+    gr.add_argument("--depth", type=int)
+    gr.set_defaults(fn=cmd_graph)
+
+    sk = sub.add_parser("skill", help="install the agent skill")
+    sk.add_argument("--install", action="store_true", required=True)
+    sk.set_defaults(fn=cmd_skill)
+
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    args.fn(args)
+
+
+if __name__ == "__main__":
+    main()