hubkit-cli 0.1.0__py3-none-any.whl

hubcore/data/hub/scripts/hubcore/store.py

@@ -0,0 +1,172 @@
+"""Append-only JSONL, flock, atomic replace, human-prompt test, time helpers."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import re
+import time
+import unicodedata
+from collections.abc import Iterator
+from datetime import datetime
+from datetime import tzinfo as TzInfo
+from pathlib import Path
+
+from . import compat, config
+from .redact import redact_obj
+
+# Harness and peer wrappers. The test is a denylist on the whole normalised text, plus: any text
+# that starts with a tag is not a typed prompt, and a payload origin other than "human" is rejected.
+HARNESS_PREFIXES = ("caveat", "this session is being continued", "/compact", "[artifact", "[system", "[cross-session")
+HARNESS_MARKERS = (
+    "cross-session-message",
+    "another-claude-session-sent-a-message",
+    "system-notification",
+    "task-notification",
+    "system-reminder",
+    "teammate-message",
+    "local-command-stdout",
+    "command-name",
+    "bash-input",
+    "bash-stdout",
+    "artifact-content-authored-by",
+)
+
+
+class StateError(RuntimeError):
+    pass
+
+
+def _normalise(text: str) -> str:
+    """NFKC, all dash look-alikes to '-', zero-width and format characters removed, lower case."""
+    out = []
+    for ch in unicodedata.normalize("NFKC", text):
+        cat = unicodedata.category(ch)
+        if cat == "Cf":
+            continue
+        out.append("-" if cat == "Pd" else ch)
+    return "".join(out).lower()
+
+
+def is_human(text: str, origin: str | None = None) -> bool:
+    """True only for a typed prompt. origin, when the payload has it, must be 'human'."""
+    if origin is not None and origin != "human":
+        return False
+    t = re.sub(r"</?pasted_content[^>]*>", " ", _normalise(text)).lstrip()  # a typed paste is human
+    if not t or t.startswith(HARNESS_PREFIXES) or re.match(r"<[a-z/!?]", t):
+        return False
+    squashed = re.sub(r"[\s_]+", "-", t)
+    return not any(m in squashed for m in HARNESS_MARKERS)
+
+
+def _inside_git(path: Path) -> bool:
+    p = path.resolve()
+    return any((q / ".git").exists() for q in [p, *p.parents])
+
+
+def state(cfg: dict, create: bool = True) -> Path:
+    """The state directory (created on demand); refuses one inside a git repository or the skill dir."""
+    d = config.state_dir(cfg)
+    if d.resolve().is_relative_to(config.SKILL_DIR):
+        raise StateError(f"state dir {d} is inside the skill dir")
+    if _inside_git(d):
+        raise StateError(f"state dir {d} is inside a git repository")
+    if create:
+        for sub in ("", "seen", "archive", "eod", "payload-samples"):
+            (d / sub).mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def tzinfo(cfg: dict) -> TzInfo | None:
+    """The configured timezone, else the system one."""
+    name = cfg["user"].get("timezone", "")
+    if name:
+        from zoneinfo import ZoneInfo
+
+        return ZoneInfo(name)
+    return datetime.now().astimezone().tzinfo
+
+
+def day_of(cfg: dict, epoch: float) -> str:
+    """YYYY-MM-DD of an epoch in the configured timezone."""
+    return datetime.fromtimestamp(epoch, tzinfo(cfg)).strftime("%Y-%m-%d")
+
+
+def clock(cfg: dict, epoch: float) -> str:
+    """HH:MM of an epoch in the configured timezone."""
+    return datetime.fromtimestamp(epoch, tzinfo(cfg)).strftime("%H:%M")
+
+
+def append_row(path: Path, row: dict) -> None:
+    """Redact, then one os.write on an O_APPEND fd. No lock needed for a pure append."""
+    row = redact_obj(row)
+    row.setdefault("ts", time.time())
+    data = (json.dumps(row, ensure_ascii=False, separators=(",", ":")) + "\n").encode()
+    fd = os.open(path, os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o600)
+    try:
+        os.write(fd, data)
+    finally:
+        os.close(fd)
+
+
+def read_rows(path: Path) -> tuple[list[dict], int]:
+    """Return (rows, bad_lines). A torn or corrupt line is skipped and counted."""
+    rows: list[dict] = []
+    bad = 0
+    if not path.exists():
+        return rows, bad
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        if not line.strip():
+            continue
+        try:
+            obj = json.loads(line)
+        except ValueError:
+            bad += 1
+            continue
+        if isinstance(obj, dict):
+            rows.append(obj)
+        else:
+            bad += 1
+    return rows, bad
+
+
+@contextlib.contextmanager
+def locked(path: Path, blocking: bool = True, retries: int = 3) -> Iterator[bool]:
+    """flock on a lock file. Yields True when held. Non-blocking mode retries then yields False."""
+    fd = os.open(path, os.O_RDWR | os.O_CREAT, 0o600)
+    got = False
+    try:
+        for _ in range(retries if not blocking else 1):
+            got = compat.lock_exclusive(fd, wait=blocking)
+            if got:
+                break
+            time.sleep(0.05)
+        yield got
+    finally:
+        os.close(fd)
+
+
+def write_atomic(path: Path, text: str) -> None:
+    """Write text via a temp file and rename."""
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    tmp.write_text(text, encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def write_json_atomic(path: Path, obj: object, indent: int | None = 1) -> None:
+    """Redact every string, then write atomically (status.json, work.json)."""
+    write_atomic(path, json.dumps(redact_obj(obj, 2000), indent=indent, ensure_ascii=False) + "\n")
+
+
+def safe(text: str, n: int = 300) -> str:
+    """Redact first, then truncate, so a cut secret cannot leak a prefix."""
+    from .redact import redact
+
+    return redact(text)[0][:n]
+
+
+def touch_seen(sd: Path, name: str) -> None:
+    """Touch a heartbeat file under seen/."""
+    (sd / "seen").mkdir(exist_ok=True)
+    (sd / "seen" / name).touch()

hubcore/data/hub/scripts/hubcore/watcher.py

@@ -0,0 +1,167 @@
+"""Checks that run in every tick (cron or watch), outside the hub session: the hub itself, peers stuck on a prompt,
+the watch and cron checking each other, and the user notification."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+import time
+
+from . import hooks, routed, slow, store
+from .orders import Orders
+
+USER_KEYS = ("hub:", "peer:")  # alerts that go to the user's desktop when no notify_cmd is configured
+WAITING_STATES = ("waiting", "blocked", "needs_input", "permission")
+HUB_SEEN = ("prompt", "stop", "routed", "answer", "session")
+
+
+def live_jobs(cfg: dict, orders: Orders) -> int:
+    """Routed items plus open orders: the work that needs a hub."""
+    return len(routed.items(cfg)) + sum(o["state"] == "open" for o in orders.live())
+
+
+def _last_hub_activity(sd: store.Path) -> float:
+    """Latest heartbeat the hub's own hooks touched."""
+    return max([(sd / "seen" / n).stat().st_mtime for n in HUB_SEEN if (sd / "seen" / n).exists()] or [0.0])
+
+
+def hub_checks(cfg: dict, orders: Orders, now: float) -> list[dict]:
+    """The hub is gone, stuck on one status, or has not acted on an alert, while jobs are live."""
+    n = live_jobs(cfg, orders)
+    if not n:
+        return []
+    w = cfg["watcher"]
+    b = hooks.read_bind(cfg)
+    if not hooks.bind_alive(b):
+        return [{"key": "hub:dead", "msg": f"hub session is not running and {n} job{'s' if n > 1 else ''} are live. "
+                 "NEXT: start the hub session and run hubkit bind"}]
+    out: list[dict] = []
+    sess = hooks.session_file(cfg, int(b["pid"])) or {}
+    since = float(sess.get("statusUpdatedAt", 0)) / 1000
+    if sess.get("status") == "busy" and since and now - since > float(w["stuck_min"]) * 60:
+        out.append({"key": "hub:stuck", "msg": f"hub session has been busy for {int((now - since) / 60)} min with {n} live jobs; "
+                    "check it is not stuck on a prompt"})
+    act = _last_hub_activity(store.state(cfg))
+    old = [r for r in store.read_rows(store.state(cfg) / "alerts.jsonl")[0]
+           if r["ts"] > act and now - r["ts"] > float(w["unhandled_min"]) * 60 and not str(r.get("key", "")).startswith("hub:")]
+    if old:
+        first = min(old, key=lambda r: r["ts"])
+        out.append({"key": "hub:unhandled", "msg": f"alert unhandled for {int((now - first['ts']) / 60)} min and the hub has not acted since "
+                    f"({str(first.get('msg', ''))[:70]})"})
+    return out
+
+
+def peer_checks(cfg: dict, now: float) -> list[dict]:
+    """A peer holding a live item sits on a permission prompt or waits for input (session status / waitingFor)."""
+    out = []
+    for owner in dict.fromkeys(i["owner"] for i in routed.items(cfg)):
+        sess = slow.holder_session(cfg, owner)
+        if not sess or not (sess.get("waitingFor") or str(sess.get("status")) in WAITING_STATES):
+            continue
+        mins = int((now - float(sess.get("statusUpdatedAt", 0)) / 1000) / 60)
+        if mins >= int(cfg["watcher"]["waiting_min"]):
+            ids = ",".join(i["id"] for i in routed.items(cfg) if i["owner"] == owner)
+            what = store.safe(str(sess.get("waitingFor") or sess.get("status")), 40)
+            out.append({"key": f"peer:{owner}:waiting", "msg": f"{owner} has waited {mins} min on {what} (holds {ids}). "
+                        f"NEXT: ask the user to answer it in that session, or re-brief"})
+    return out
+
+
+def liveness_checks(cfg: dict, orders: Orders) -> list[dict]:
+    """Watch and cron check each other: work is live and no watch runs, or cron is configured but has gone stale."""
+    from . import cli, gate
+
+    out = []
+    started = [routed.started_at(cfg, i) for i in routed.items(cfg)] + [o["opened"] for o in orders.live() if o["state"] == "open"]
+    grace = float(cfg["watcher"]["watch_grace_min"]) * 60  # the stop gate makes the hub arm a watch; give it a moment
+    if started and time.time() - min(started) > grace and not gate.watch_live(cfg):
+        out.append({"key": "watch:dead", "msg": f"hubkit watch is not running and work is live. NEXT: start in the background: {gate.WATCH_CMD}"})
+    f = store.state(cfg) / "seen" / "cron"
+    limit = float(cfg["watchdog"]["cron_stale_min"])
+    quiet_min = (time.time() - f.stat().st_mtime) / 60 if f.exists() else (time.time() - min(started)) / 60 if started else 0.0
+    if quiet_min > limit and cli.cron_configured():  # never written counts from the oldest live job
+        out.append({"key": "cron:dead", "msg": f"cron has not run hubkit for over {int(limit)} min. NEXT: check the crontab line and cron's mail"})
+    return out
+
+
+def checks(cfg: dict, orders: Orders, now: float) -> list[dict]:
+    """Every watcher alert that holds now."""
+    return [*hub_checks(cfg, orders, now), *peer_checks(cfg, now), *liveness_checks(cfg, orders), *stale_agent_checks(cfg, now)]
+
+
+def stale_agent_checks(cfg: dict, now: float) -> list[dict]:
+    """A background agent reported finished long ago and its item is still listed (a review item waits on its PR)."""
+    limit = float(cfg["watcher"]["stale_agent_min"])
+    return [
+        {"key": f"agent:{i['owner']}:stale", "msg": f"agent {i['owner']} finished {int((now - i['reported']) / 60)} min ago and {i['id']} is still listed. "
+         "NEXT: close the item (hubkit work done) or act on the PR it waits for"}
+        for i in routed.items(cfg)
+        if i.get("tool_use_id") and i.get("reported") and (now - float(i["reported"])) / 60 > limit
+    ]
+
+
+def desktop_argv(msg: str, platform: str = sys.platform) -> list[str] | None:
+    """The default desktop notification command for this platform, or None when no tool is installed."""
+    if platform.startswith("linux") and shutil.which("notify-send"):
+        return ["notify-send", "-u", "critical", "-a", "hubkit", "hubkit", msg]
+    if platform == "darwin" and shutil.which("osascript"):
+        safe = msg.replace("\\", " ").replace('"', "'")
+        return ["osascript", "-e", f'display notification "{safe}" with title "hubkit"']
+    return None
+
+
+def notify(cfg: dict, new: list[dict]) -> None:
+    """Tell the user's desktop about new alerts. `tools.notify_cmd` (every alert) wins; with none set, the platform's
+    default is used for the alerts that are about the hub or a stuck peer. Never posts to chat."""
+    cmd = cfg["tools"]["notify_cmd"]
+    if cmd:
+        argv: list[str] | None = [*shlex.split(cmd), "hubkit: " + "; ".join(a["msg"] for a in new)]
+    else:
+        mine = [a["msg"] for a in new if str(a["key"]).startswith(USER_KEYS)]
+        argv = desktop_argv("; ".join(mine)) if mine else None
+    if not argv or (not cmd and not cfg["watcher"]["notify_user"]):
+        return
+    try:
+        subprocess.run(argv, timeout=5, check=False)
+    except OSError, subprocess.SubprocessError:
+        pass
+
+
+def excused(cfg: dict, item: dict, now: float) -> str | None:
+    """Why a silent item is not a stall: it is blocked on another live job, or its holder is visibly working
+    (session busy and its transcript growing). An active holder is excused for 3x the limit only."""
+    live = {i["id"] for i in routed.items(cfg)}
+    if item.get("blocked_on") in live:
+        return f"blocked on {item['blocked_on']}"
+    if (now - routed.base(cfg, item)) / 60 > 3 * routed.limit(cfg, item):
+        return None
+    owner = item["owner"]
+    sess = slow.holder_session(cfg, owner)
+    path = slow.holder_transcript(cfg, owner, sess)
+    if sess and str(sess.get("status")) == "busy" and path:
+        try:
+            if now - os.path.getmtime(path) < float(cfg["watcher"]["active_s"]):
+                return "holder is working"
+        except OSError:
+            return None
+    return None
+
+
+def set_blocked(cfg: dict, wid: str, on: str) -> str:
+    """Link a routed item to the job it waits on (empty `on` clears it)."""
+    sd = store.state(cfg)
+    with store.locked(sd / "work.lock"):
+        items = routed.work_load(sd)
+        hit = next((i for i in items if i["id"] == wid and i.get("kind") == "routed"), None)
+        if hit is None:
+            raise KeyError(f"no live routed item {wid}")
+        if on and on == wid:
+            raise ValueError("an item cannot block on itself")
+        if on and not any(i["id"] == on for i in items):
+            raise KeyError(f"no live item {on}")
+        hit["blocked_on"] = on
+        routed.work_save(sd, items)
+    return f"{wid} blocked on {on}" if on else f"{wid} no longer blocked"

hubcore/data/hub/scripts/hubkit

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""hubkit entry point: python3 hubkit <command>.
+
+For `hook` runs, an import failure must never exit non-zero in any session: it is logged to a
+single import-errors.log in the state dir (a failure here cannot be classified as hub or not) and
+the process exits 0.
+"""
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+try:
+    from hubcore.cli import main
+except BaseException as exc:  # noqa: BLE001 - the hook contract is exit 0
+    if len(sys.argv) > 1 and sys.argv[1] == "hook":
+        try:
+            import os
+            import time
+
+            base = os.environ.get("HUBKIT_STATE") or os.path.join(
+                os.environ.get("XDG_STATE_HOME") or os.path.expanduser("~/.local/state"), "hubkit"
+            )
+            os.makedirs(base, exist_ok=True)
+            with open(os.path.join(base, "import-errors.log"), "a", encoding="utf-8") as fh:
+                msg = str(exc)
+                try:
+                    from hubcore.redact import redact
+
+                    msg = redact(msg)[0]
+                except BaseException:  # the redactor may be what failed to import
+                    msg = "(message withheld: redaction unavailable)"
+                fh.write(f"{time.time():.0f} {type(exc).__name__}: {msg[:200]}\n")
+        except BaseException:
+            pass
+        sys.exit(0)
+    raise
+sys.exit(main())

hubcore/data/hub/scripts/learn.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Hub learnings log: add, list, promote-candidates, address, review. Stdlib only.
+
+Entry format: see hubcore/learnings.py. The file is state (default: <state dir>/learnings.md),
+edited under a lock with an atomic replace, and every field is redacted before it is written.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import date
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from hubcore import config, learnings  # noqa: E402
+
+
+def main() -> int:
+    """Run one learn.py verb. Returns the exit code."""
+    p = argparse.ArgumentParser(description="Hub learnings log")
+    p.add_argument("--file", help="learnings file (default: from config)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    a = sub.add_parser("add", help="append an entry or a repeat of a class")
+    a.add_argument("--class", dest="cls", required=True)
+    a.add_argument("--gate", default="?")
+    a.add_argument("--quote", required=True, help="the user's own words")
+    a.add_argument("--date", default=date.today().isoformat())
+    for f in ("situation", "wrong", "right", "evidence"):
+        a.add_argument(f"--{f}", default="")
+    ls = sub.add_parser("list")
+    ls.add_argument("--last", type=int, default=30)
+    pc = sub.add_parser("promote-candidates")
+    pc.add_argument("--min", type=int, default=2)
+    ad = sub.add_parser("address", help="mark a class as fixed (rule promoted, hook added)")
+    ad.add_argument("--class", dest="cls", required=True)
+    ad.add_argument("--how", required=True)
+    ad.add_argument("--date", default=date.today().isoformat())
+    pm = sub.add_parser("promote", help="write a short rule into the overlay under its gate")
+    pm.add_argument("cls")
+    pm.add_argument("--gate", required=True)
+    pm.add_argument("--rule", required=True)
+    rv = sub.add_parser("review", help="new, repeated and addressed status for a day")
+    rv.add_argument("--day", default=date.today().isoformat())
+    args = p.parse_args()
+
+    cfg = config.load()
+    path = Path(args.file) if args.file else learnings.default_file(cfg)
+    try:
+        if args.cmd == "add":
+            print(learnings.add(path, args.cls, args.quote, args.date, args.gate,
+                                situation=args.situation, wrong=args.wrong,
+                                right=args.right, evidence=args.evidence,
+                                basis=learnings.rules_hash(cfg)))
+        elif args.cmd == "list":
+            for b in learnings.recent(path, args.last):
+                print("\n".join(b).rstrip() + "\n")
+        elif args.cmd == "promote-candidates":
+            _, blocks = learnings.read_blocks(path)
+            hits = sorted(((len(learnings.seen_lines(b)), b) for b in blocks
+                           if len(learnings.seen_lines(b)) >= args.min), key=lambda r: -r[0])
+            if not hits:
+                print(f"none seen >= {args.min}x")
+            for n, b in hits:
+                m = learnings.HEADER_RE.match(b[0])
+                print(f"{n}x  {m['cls']}  (gate {m['gate']})" if m else f"{n}x ?")
+        elif args.cmd == "address":
+            ov = [f for f in (learnings.overlay_path(cfg), config.SKILL_DIR / "SKILL.md") if f.exists()]
+            print(learnings.mark_addressed(path, args.cls, args.date, args.how, learnings.rules_hash(cfg),
+                                           max(f.stat().st_mtime for f in ov),
+                                           "\n".join(f.read_text(encoding="utf-8", errors="replace") for f in ov)))
+        elif args.cmd == "promote":
+            print(learnings.promote(path, learnings.overlay_path(cfg), args.cls, args.gate, args.rule))
+        elif args.cmd == "review":
+            for k, v in learnings.review(path, args.day).items():
+                print(f"{k}: {', '.join(v) or '-'}")
+    except (ValueError, KeyError) as e:
+        print(f"error: {e.args[0]}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hubcore/data/hub-mep/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: hub-mep
+description: Optional companion to the hub skill for users of the `mep` (miseenplace) task-list CLI. Use when the hub needs the user's open items, wants to put one batched decision to the user, watches the user's chat while away, or closes the day. Needs `mep` installed; without it, ignore this skill. Thin: mep's own skills own the verbs, this says only what the hub does with them.
+---
+
+# hub-mep
+
+`mep` is the user's list, inbox and journal (PyPI package `miseenplace-cli`). The hub reads it and fills its queues. It never edits mep's data files, never writes into the mep data root, and calls only the CLI, with a timeout, as an argument list.
+
+| Hub need | mep verb | Who owns the loop |
+|---|---|---|
+| Watch the user's chat while away | `mep watch --cursor <name>`, run by a background agent; its exit wakes the hub | the inbox-watch skill; the hub picks the cursor name and decides what each line triggers |
+| Classify an inbox line | `mep triage` | the inbox-triage skill |
+| What is on the user, what waits on others | `mep status --json` (also in the hubkit block, labelled UNVERIFIED when mep is slow or absent) | the journal skill; the hub only reads |
+| A decision the user must make | `mep ask --recommend --default --by` | mep owns the queue; the hub fills it with one batched ask |
+| A message to a person | `mep draft`, then `mep send` only on a typed yes (hub gate G3) | the hub's messaging rules (overlay) |
+| Replies to review asks | the review-reply skill named in the overlay | that skill |
+| Daily close | the user's own end-of-day skill for the list; `hubkit eod` for the hub's orders and learnings | both, in that order |
+| Lessons about hub behaviour | `learn.py` today; `mep lessons` is the planned single store (field map: situation->when, right->do, wrong->not, evidence->evidence, seen count->votes) | the hub, until the migration is approved |
+
+Rules
+1. Before listing a mep item as pending on the user, re-read it now (hub section 5). Items older than the status build are `UNVERIFIED`.
+2. A mep call that fails or times out is reported as `unreachable`, never as "nothing pending".
+3. Orders (clocks, evidence) live in hubkit, not in mep: mep models the user's asks, hubkit models what the hub owes while an order is open.
+4. The adapter reads the `on_you` key of `mep status --json` and checks it; a missing key shows as UNVERIFIED. Re-check with `hubkit status` after a mep upgrade.
+5. Never paste mep output that contains tokens into state or reports; hubkit redacts what it stores, but report key names only.
+6. No `mep`? Set `[mep] enabled = false` in `~/.config/hubkit/config.toml`; the hub then ignores this skill.
+
+## Example
+
+The user is away and says "tell me when anyone needs a review."
+
+1. The hub launches a background agent: `mep watch --cursor hub-away`; Done-when: exits on a line that asks for a review; Output: that line only.
+2. The agent exits with `review asked: PR 41`. The exit wakes the hub, which routes the review to the reviewer peer (hub gate G5 applies) and records an item with `hubkit work add --kind routed --owner reviewer --title "review PR 41" --pr https://github.com/acme/repo/pull/41`.
+3. At the next report, `hubkit status` shows `on the user (mep): N`; the hub re-reads anything it lists as pending (rule 1).

hubcore/data/hubkit-setup/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: hubkit-setup
+description: Set up hubkit for the user end to end: check the install, write the config from facts found on the machine, register the hooks in Claude Code settings, bind the hub session and prove it works. Use right after `hubkit skills --install`, or for "set up hubkit", "install the hub", "hubkit doctor shows problems". Ask the user only for what cannot be found out.
+---
+
+# hubkit-setup
+
+Goal: a working hub in one pass. Find out; do not ask. Ask once, batched, and only for what no command or file can tell you. Never print tokens or secrets. Never edit a file without a dated backup beside it.
+
+`hubkit` below is the command on the PATH (from `uv tool install hubkit-cli`), or `python3 <skills dir>/hub/scripts/hubkit` when the tool is not on the PATH.
+
+## 1. Check the install
+
+1. `hubkit --help` works and `python3 --version` (or the interpreter hubkit runs under) is 3.14 or newer. If not, say so and stop: hubkit needs 3.14.
+2. The hub skill is in the skills directory: `<skills dir>/hub/SKILL.md` exists. If not, run `hubkit skills --install <skills dir>` (Claude Code user level is `~/.claude/skills`).
+3. `hubkit doctor` runs. Note what it says; it is the baseline.
+
+## 2. Find the facts (do not ask for these)
+
+| Fact | How to find it |
+|---|---|
+| The user's name | `git config user.name`, else the OS account's full name |
+| Time zone | `/etc/timezone`, `timedatectl show -p Timezone`, or `python3 -c "import tzlocal"` is not needed: `readlink /etc/localtime` (macOS and Linux); on Windows `tzutil /g` |
+| GitHub login | `gh api user -q .login` when `gh` is logged in, else leave it empty |
+| Notification command | Linux `notify-send`, macOS `osascript`: leave `notify_cmd` empty to use the platform default; on Windows set `tools.notify_cmd` to a command the user already has, else leave it empty |
+| Sessions directory | `~/.claude/sessions` exists and holds `<pid>.json` files |
+| `mep` | `command -v mep`; set `[mep] enabled = false` when absent |
+
+## 3. Write the config
+
+Copy `<skills dir>/hub/config.example.toml` to `~/.config/hubkit/config.toml` (the directory `$XDG_CONFIG_HOME/hubkit` when set) unless one exists; if one exists, edit only missing keys and say what you changed. Fill the facts from section 2. Add the user's real names, handles and project words to `[private] terms` only if the user wants a clean check; `hubkit doctor --check-clean` lists files that contain them.
+
+Copy `intents.example.toml` to `intents.toml` only when the user wants to change order words or clocks; the example is used by default.
+
+## 4. Register the hooks
+
+1. `hubkit hooks --skills-dir <skills dir>` prints the `hooks` block for `~/.claude/settings.json` (SessionStart, UserPromptSubmit, PostToolUse for questions and routed work, Stop). Add `--merge-guard` for the warn-only PreToolUse merge check.
+2. Back up `~/.claude/settings.json` to `settings.json.bak-<date>`, merge the block in (keep every existing hook; a hubkit entry already there is replaced, not duplicated), and write valid JSON.
+3. Tell the user that hooks load at the next session start.
+
+## 5. Bind and prove it
+
+1. In the session that will be the hub: `hubkit bind`. It binds only an interactive session.
+2. `hubkit doctor` must show `bind: live`, `hook-errors.jsonl: 0 rows`, and no `secret-shaped strings`.
+3. Open a throwaway order and close it to prove the loop: `hubkit order open --kind merge --quote "test order"`, then `hubkit order ls`, then `hubkit order cancel <id> --quote "setup test"`.
+4. Optional watchdog: on Linux or macOS add the crontab line from the README (name the Python 3.14 interpreter); on Windows create a Task Scheduler task that runs `hubkit tick --if-bound` every 5 minutes. `hubkit doctor` then reports `cron: ok` after the first run.
+
+## 6. Report
+
+At most 6 lines: what you found, what you wrote (paths), what the user must do (restart the session; nothing else), and the one command to check later: `hubkit doctor`.