overscore-cli 0.1.0__py3-none-any.whl

overscore_cli/ovs.py

@@ -0,0 +1,1766 @@
+"""ovs: the customer-side command line. Talks only HTTP, so it can ship on its own.
+
+Built for agents as much as people:
+  - every command takes `-o json`; when stdout is not a terminal, json is the default
+  - failures print {"success": false, "error": "...", "status": N} and exit 1
+  - the key comes from OVERSCORE_KEY (or --key), the address from OVERSCORE_URL (or --url)
+  - `ovs guide` prints the short reference an agent should read before doing anything
+
+  ovs whoami
+  ovs tables                      ovs describe sales orders
+  ovs query "select 1"            echo "select 1" | ovs query
+  ovs insert sales orders rows.json
+  ovs load sales prices prices.csv [--tab Sheet1 --skip 2]
+  ovs notes sales                 ovs note sales refunds "A refund counts when issued."
+  ovs search refund
+  ovs models sales                ovs run sales [--only m1]      ovs test sales
+  ovs runs [-n 20]                ovs run-log <id>
+  ovs signoff sales orders_clean "One row per order"
+  ovs export sales paid "select * from sales.orders_clean where status='paid'"
+  ovs connectors                  ovs connect stripe key=rk_live_...     ovs connect shopify shop=acme token=shpat_...
+  ovs link mydb "host=... user=... password=... dbname=..." [--copy] [--tables a b] [--schema public]
+  ovs links                       ovs copy mydb                ovs unlink mydb
+  ovs guide
+
+The laptop side (CLAUDE_CODE_PLAN.md): a project folder an agent can read and write, run-it-here before push-it-there.
+  ovs init [dir] --dish sales [--for claude|codex|cursor|gemini|agents|all]
+  ovs pull sales.leads [--rows 10000] [--where "..."]      a sample as Parquet into .overscore/, for local runs
+  ovs model run lead_scores --local                         models/lead_scores/model.py here, on the pulled samples
+  ovs model push lead_scores      ovs model run lead_scores      ovs model log lead_scores
+  ovs uploads                     ovs upload put lead_model files/lead_model.pkl    ovs upload live lead_model 1
+  ovs destinations                ovs destination add webhook "Their CRM" https://...   ovs destination add hubspot HubSpot --source sales.hubspot
+  ovs syncs                       ovs sync add scores_out --from lead_scores --key lead_id --to "Their CRM"    ovs sync run scores_out
+
+Shipped on its own as overscore-cli (cli/pyproject.toml): this file, model_helper.py (the overscore_model a script imports)
+and the skills ovs init writes. Nothing here imports the server.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import pathlib
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+
+import requests
+
+GUIDE = """ovs: talk to Overscore.
+
+Setup: ovs login              (approve this computer in the browser; the key goes in the keychain)
+       or export OVERSCORE_KEY=ovs_... (a key from the Agents screen) and OVERSCORE_URL=https://<you>.overscore.tech
+Check: ovs whoami            (your dishes and levels: pour=add rows, read=read only, hot=read+write, masked=stand-ins)
+
+Find things:   ovs tables | ovs index | ovs search <word> | ovs describe <dish> <table> | ovs notes <dish>
+Ask:           ovs query "select ..."   (DuckDB SQL; tables are dish.table; webhook rows keep JSON in payload)
+Load:          ovs insert <dish> <table> rows.json | ovs load <dish> <table> file.csv|xlsx|parquet
+Remember:      ovs note <dish> <name> "what you learned"   (confirmed if your key is hot, else heard)
+Model:         ovs models <dish> | ovs run <dish> | ovs test <dish> | ovs signoff <dish> <table> "description"
+Watch:         ovs runs | ovs run-log <id>
+Share:         ovs export <dish> <name> "select ..."   -> a live link, no key needed by the reader
+Sources:       ovs connectors | ovs how <name> | ovs connect <name> k=v ...   (Stripe, Shopify, QuickBooks; hourly)
+Work:          ovs fields <dish> <table> | ovs field <dish> <table> status one_of "what it means" --allowed new done
+               ovs mark <dish> <table> <id,id> done=true note="shipped"   | ovs marks <dish> <table> [id]   (the <table>_work view has it all)
+Plan:          ovs plan                today's meters and ceilings;   ovs claim <code>  pull a trial conversation into your Overscore
+Watch:         ovs issues [--sweep]   what failed or went quiet, what looks wrong, the proposed fix;  ovs fix <id> = "yeah, go for it"
+Research:      ovs research acme.com     read the website first: systems seen, what it sells, who is named
+Interview:     ovs interview [area] [--person Dana]   a consultant's first conversation; 'done' saves what was heard as confirmed
+               ovs map                                 how much is known per area
+Inbox:         open <your Overscore address>/inbox in a browser with a hot key: the same cards, with buttons
+Context:       ovs context "<question>"   one search over facts, notes and tables; then SQL on the table it names
+               ovs propose "Dana owns Shopify now" | ovs cards | ovs approve <id> | ovs ignore <id> | ovs facts people
+Webhooks:      ovs hook <dish> <table> [--provider stripe --secret whsec_...]  -> an address to paste into the other app
+               ovs hooks | ovs hook-log <token> | ovs unhook <token>
+Your Postgres: ovs link <dish> "<dsn>"          live: queries hit your database in place (use a read replica)
+               ovs link <dish> "<dsn>" --copy   copy: snapshot into the lake every hour
+               ovs links | ovs copy <dish> | ovs unlink <dish>
+Project:       ovs init --dish <dish> [--for claude|codex|cursor|gemini|agents|all]   overscore.toml, models/, files/, syncs.toml, the rules and skills
+Python models: ovs pull <dish.table>            a sample (10,000 rows at most) into .overscore/ for local runs
+               ovs model run <name> --local     models/<name>/model.py here, on the samples and files/; nothing leaves the laptop
+               ovs model push <name>            save model.py, its reads, uploads and requirements (model.toml), and run it in Overscore
+               ovs model run <name> | ovs model log <name>
+Files:         ovs uploads | ovs upload put <name> <file> [--note ...] | ovs upload live <name> <version> | ovs upload rm <name>
+Destinations:  ovs destinations | ovs destination add webhook "<title>" <https-url> | ovs destination add hubspot "<title>" --source <dish.source>
+               ovs destination check <dest> | ovs destination rm <dest>
+Syncs:         ovs sync add <name> --from <table> --key <id column> --to <dest> [--columns a b=field] [--after-change | --every 5m | --manual]
+               ovs syncs | ovs sync run <name> | ovs sync show <name> | ovs sync pause|resume|rm <name>
+
+Rules: read notes before writing SQL; prefer signed_off tables, then models, then raw, and say which you used.
+Every command: -o json for machine output. Failures exit 1 with {"success": false, "error": ...}.
+"""
+
+
+class Fail(Exception):
+    """A failure the person (or agent) can act on. `data` rides along in the JSON (a run's log, say)."""
+    def __init__(self, msg: str, status: int | None = None, data: dict | None = None):
+        super().__init__(msg); self.status = status; self.data = data or {}
+
+
+class Client:
+    def __init__(self, url: str, key: str | None):
+        self.url = url.rstrip("/"); self.h = {"Authorization": f"Bearer {key}"} if key else {}
+
+    def call(self, method: str, path: str, **kw):
+        headers = {**self.h, **(kw.pop("headers", None) or {})}
+        try:
+            r = requests.request(method, self.url + path, headers=headers, timeout=kw.pop("timeout", 120), **kw)
+        except requests.RequestException as e:
+            raise Fail(f"cannot reach {self.url}: {e}")
+        if r.status_code >= 400:
+            try:
+                j = r.json()
+                detail = (j.get("error") or j.get("detail") or r.text) if isinstance(j, dict) else r.text
+            except ValueError:
+                detail = r.text
+            raise Fail(str(detail)[:500], r.status_code)
+        return r.json() if r.headers.get("content-type", "").startswith("application/json") else r.text
+
+
+def _table(rows: list[dict] | list[list], columns: list[str] | None = None) -> str:
+    if not rows:
+        return "(no rows)"
+    if isinstance(rows[0], dict):
+        columns = columns or list(rows[0].keys())
+        rows = [[r.get(c) for c in columns] for r in rows]
+    cells = [[("" if v is None else str(v))[:60] for v in r] for r in rows]
+    widths = [max(len(c), *(len(r[i]) for r in cells)) for i, c in enumerate(columns)]
+    line = "  ".join(c.ljust(w) for c, w in zip(columns, widths))
+    out = [line, "  ".join("-" * w for w in widths)]
+    out += ["  ".join(v.ljust(w) for v, w in zip(r, widths)) for r in cells]
+    return "\n".join(out)
+
+
+def run(a, c: Client):
+    """Returns (json_value, human_text)."""
+    if a.cmd in LAPTOP:
+        return LAPTOP[a.cmd](a, c)
+    if a.cmd == "guide":
+        return {"guide": GUIDE}, GUIDE
+    if a.cmd == "whoami":
+        d = c.call("GET", "/whoami"); return d, json.dumps(d, indent=1)
+    if a.cmd == "tables":
+        d = c.call("GET", "/tables")
+        rows = d if isinstance(d, list) else d.get("tables", d)
+        return d, _table(rows) if isinstance(rows, list) else json.dumps(d, indent=1)
+    if a.cmd == "index":
+        d = c.call("GET", "/index")
+        lines = []
+        for dish, ts in d.get("dishes", {}).items():
+            for t in ts:
+                lines.append({"table": f"{dish}.{t['table']}", "tier": t["tier"], "rows": t["rows"],
+                              "description": t["description"]})
+        for dish, ns in d.get("notes", {}).items():
+            for n in ns:
+                lines.append({"table": f"{dish} note: {n['name']}", "tier": n["trust"], "rows": "", "description": n["title"]})
+        return d, _table(lines, ["table", "tier", "rows", "description"])
+    if a.cmd == "describe":
+        d = c.call("GET", f"/index/{a.dish}/{a.table}")
+        cols = [{"column": x["name"], "type": x["type"], "null_rate": x.get("null_rate"),
+                 "sample": ", ".join(str(v) for v in (x.get("samples") or [v["value"] for v in x.get("values", [])])[:3])}
+                for x in d.get("columns", [])]
+        head = f"{a.dish}.{a.table}  tier={d.get('tier')}  rows={d.get('rows')}  {d.get('description') or ''}\n"
+        return d, head + _table(cols, ["column", "type", "null_rate", "sample"])
+    if a.cmd == "search":
+        d = c.call("GET", "/search", params={"q": a.text})
+        t = [{"kind": "table", "name": f"{x['dish']}.{x['table']}", "tier": x["tier"], "hit": ",".join(x["matched"])} for x in d["tables"]]
+        t += [{"kind": "note", "name": f"{x['dish']}/{x['note']}", "tier": x["trust"], "hit": x["snippet"][:60]} for x in d["notes"]]
+        return d, _table(t, ["kind", "name", "tier", "hit"])
+    if a.cmd == "query":
+        sql = a.sql if a.sql and a.sql != "-" else sys.stdin.read()
+        d = c.call("POST", "/query", json={"sql": sql, "max_rows": a.max_rows})
+        note = f"\n({d['row_count']} rows, {d['ms']:.0f} ms{', truncated' if d.get('truncated') else ''})"
+        return d, _table(d["rows"], d["columns"]) + note
+    if a.cmd == "insert":
+        rows = json.load(open(a.file)) if a.file != "-" else json.load(sys.stdin)
+        d = c.call("POST", f"/in/{a.dish}/{a.table}", json=rows); return d, f"inserted {d.get('rows')} rows into {a.dish}.{a.table}"
+    if a.cmd == "load":
+        params = {"name": os.path.basename(a.file)}
+        if a.tab: params["tab"] = a.tab
+        if a.skip: params["skip"] = a.skip
+        with open(a.file, "rb") as f:
+            d = c.call("POST", f"/files/{a.dish}/{a.table}", params=params, data=f, timeout=600)
+        return d, f"loaded {a.dish}.{a.table}: {json.dumps(d)}"
+    if a.cmd == "notes":
+        d = c.call("GET", f"/notes/{a.dish}", params={"full": "true"})
+        text = "\n\n".join(f"## {n['title']}  [{n['trust']}, {n['name']}, by {n['written_by']}]\n{n['body']}" for n in d["notes"]) or "(no notes)"
+        return d, text
+    if a.cmd == "note":
+        body = a.body if a.body and a.body != "-" else sys.stdin.read()
+        d = c.call("PUT", f"/notes/{a.dish}/{a.name}", json={"body": body, "title": a.title}); return d, f"saved note {a.dish}/{a.name} as {d['trust']} v{d['version']}"
+    if a.cmd == "models":
+        d = c.call("GET", f"/models/{a.dish}")
+        rows = [{"model": m["name"], "depends_on": ",".join(m.get("depends_on", [])), "description": m.get("description", "")} for m in d.get("detail", [])]
+        return d, _table(rows, ["model", "depends_on", "description"])
+    if a.cmd == "run":
+        d = c.call("POST", f"/run/{a.dish}", json={"only": a.only} if a.only else None, headers={"x-overscore-trigger": "cli"}, timeout=3600)
+        rows = [{"model": r.get("model") or r.get("name"), "ok": r["ok"], "rows": r.get("rows"), "error": (r.get("error") or "")[:60]} for r in d["results"]]
+        return d, _table(rows, ["model", "ok", "rows", "error"]) + ("\nall ok" if d["ok"] else "\nSOME FAILED")
+    if a.cmd == "test":
+        d = c.call("POST", f"/tests/{a.dish}", timeout=3600)
+        rows = [{"test": r.get("test") or r.get("name"), "ok": r["ok"], "failing_rows": r.get("rows"), "error": (r.get("error") or "")[:60]} for r in d["results"]]
+        return d, _table(rows, ["test", "ok", "failing_rows", "error"]) + ("\nall ok" if d["ok"] else "\nSOME FAILED")
+    if a.cmd == "signoff":
+        d = c.call("POST", f"/index/{a.dish}/{a.table}/signoff", json={"on": not a.off, "description": a.description}); return d, json.dumps(d)
+    if a.cmd == "runs":
+        d = c.call("GET", "/runs", params={"limit": a.n})
+        runs = d if isinstance(d, list) else d.get("runs", [])
+        rows = [{k: r.get(k) for k in ("id", "kind", "dish", "name", "status", "ms", "started_at")} for r in runs]
+        return d, _table(rows, ["id", "kind", "dish", "name", "status", "ms", "started_at"])
+    if a.cmd == "run-log":
+        d = c.call("GET", f"/runs/{a.id}"); return d, json.dumps(d, indent=1, default=str)
+    if a.cmd == "export":
+        d = c.call("POST", "/exports", json={"dish": a.dish, "name": a.name, "sql": a.sql, "format": a.format})
+        return d, f"live link: {c.url}{d.get('path') or '/x/' + str(d.get('token'))}"
+    if a.cmd == "connectors":
+        d = c.call("GET", "/connectors")
+        rows = [{"name": x["name"], "needs": ", ".join(x["needs"]), "dish": x["dish"], "every": x["every"], "how": x["how"][:70]} for x in d["connectors"]]
+        return d, _table(rows, ["name", "needs", "dish", "every", "how"])
+    if a.cmd == "how":
+        d = c.call("GET", f"/connectors/{a.name}/guide"); return {"guide": d}, d
+    if a.cmd == "connect":
+        secrets = {}
+        for kv in a.secrets:
+            if "=" not in kv:
+                raise Fail(f"expected key=value, got {kv}")
+            k, v = kv.split("=", 1); secrets[k] = v
+        body = {"secrets": secrets, "dish": a.dish, "resources": a.only or None, "run_now": not a.no_run}
+        d = c.call("POST", f"/connectors/{a.name}", json=body, headers={"x-overscore-trigger": "cli"}, timeout=3600)
+        fr = d.get("first_run") or {}
+        text = f"connected {a.name} into {d['dish']}, {d['schedule']}"
+        if fr:
+            text += "\nlanded: " + ", ".join(f"{k} {v}" for k, v in fr.get("landed", {}).items())
+            text += "\nviews: " + ", ".join(d.get("views") or []) if d.get("views") else ""
+        return d, text
+    if a.cmd == "link":
+        body = {"dsn": a.dsn, "mode": "copy" if a.copy else "live", "tables": a.tables or None, "source_schema": a.schema, "every": a.every}
+        d = c.call("PUT", f"/links/{a.dish}", json=body, timeout=3600)
+        text = f"linked {a.dish} ({d['mode']}, schema {d['source_schema']}, tables {d['tables']})"
+        if d.get("first_copy"):
+            text += "\ncopied: " + ", ".join(f"{k} {v}" for k, v in d["first_copy"]["copied"].items())
+        return d, text
+    if a.cmd == "links":
+        d = c.call("GET", "/links")
+        rows = [{k: x.get(k) for k in ("dish", "mode", "host", "source_schema", "tables", "last_copied_at")} for x in d["links"]]
+        return d, _table(rows, ["dish", "mode", "host", "source_schema", "tables", "last_copied_at"])
+    if a.cmd == "context":
+        d = c.call("GET", "/context", params={"q": a.q})
+        rows = [{"kind": h["kind"], "ref": h["ref"], "trust": h.get("trust") or "", "sentence": (h.get("sentence") or "")[:90], "look_in": h.get("table") or ""} for h in d["hits"]]
+        return d, _table(rows, ["kind", "ref", "trust", "sentence", "look_in"])
+    if a.cmd == "propose":
+        d = c.call("POST", "/context/cards", json={"text": a.text, "source": a.source})
+        return d, f"card {d['id']}: {d.get('bin') or 'unsorted'} -> {d.get('target') or 'note'}  {d.get('claim') or ''}\nstatus {d['status']}" + (", sorted by the model" if d.get("sorted") else ", waiting for a person to sort")
+    if a.cmd == "cards":
+        d = c.call("GET", "/context/cards", params={"status": a.status})
+        rows = [{"id": x["id"], "bin": x.get("bin") or "", "target": x.get("target") or "", "claim": (x.get("claim") or x["text"])[:80], "source": x["source"]} for x in d["cards"]]
+        return d, _table(rows, ["id", "bin", "target", "claim", "source"])
+    if a.cmd in ("approve", "ignore"):
+        body = {}
+        if a.cmd == "approve":
+            body = {"target": a.target, "key": a.card_key, "values": dict(kv.split("=", 1) for kv in (a.set or [])) or None}
+        d = c.call("POST", f"/context/cards/{a.id}/{a.cmd}", json=body)
+        return d, f"{d['status']}" + (f": wrote {d['written']}" if d.get("written") else "")
+    if a.cmd == "issues":
+        if a.sweep:
+            c.call("POST", "/watch/sweep", timeout=300)
+        d = c.call("GET", "/watch")
+        if not d["issues"]:
+            return d, "nothing wrong that I can see"
+        text = "\n\n".join(f"[{i['id']}] {i['what']}\n{i['text']}\n-> ovs fix {i['id']} to {i['fix']}" for i in d["issues"])
+        return d, text
+    if a.cmd == "fix":
+        d = c.call("POST", f"/context/cards/{a.id}/approve", json={}, timeout=3600)
+        return d, f"{d['status']}: {json.dumps(d.get('written'))}"
+    if a.cmd == "research":
+        d = c.call("POST", "/research", json={"site": a.site}, timeout=600)
+        f = d.get("found") or {}
+        lines = [f"read {len(d['pages'])} pages of {d['site']} in {d['ms']/1000:.0f}s",
+                 "systems seen: " + (", ".join(s["name"] for s in d["systems"]) or "none"),
+                 f"sells: {f.get('sells')}", f"to: {f.get('to_whom')}", f"money: {f.get('makes_money')}",
+                 "people: " + (", ".join(f"{p['name']} ({p.get('title')})" for p in f.get("people", [])) or "none named"),
+                 "products: " + (", ".join(p["name"] for p in f.get("products", [])) or "none"),
+                 f"wrote {len(d['written'])} rows (heard/seen); web search " + ("done" if d["searched_web"] else "skipped (no TAVILY_KEY)")]
+        return d, "\n".join(lines)
+    if a.cmd == "fields":
+        d = c.call("GET", f"/work/{a.dish}/{a.table}/fields")
+        rows = [{"field": f["field"], "type": f["type"] + (" of " + ", ".join(map(str, f["allowed"])) if f.get("allowed") else ""), "meaning": f["description"]} for f in d["fields"]]
+        return d, (f"row id: {d.get('key_column') or '(none; table-level marks only)'}\n" + (_table(rows, ["field", "type", "meaning"]) if rows else "(no fields yet; ovs field <dish> <table> <name> <type> \"meaning\")"))
+    if a.cmd == "field":
+        d = c.call("PUT", f"/work/{a.dish}/{a.table}/fields", json={"field": a.name, "type": a.type, "description": a.description, "allowed": a.allowed})
+        return d, f"{'exists' if d.get('existing') else 'defined'}: {d['field']} ({d['type']}): {d['description']}"
+    if a.cmd == "mark":
+        vals = {}
+        for kv in a.values:
+            k, _, v = kv.partition("="); vals[k] = v
+        keys = None if a.keys == "-" else [k for k in a.keys.split(",") if k]
+        d = c.call("POST", f"/work/{a.dish}/{a.table}/mark", json={"keys": keys, "values": vals})
+        return d, f"marked {d['rows']} row(s) with {', '.join(d['fields'])}"
+    if a.cmd == "marks":
+        d = c.call("GET", f"/work/{a.dish}/{a.table}/history", params={"key": a.row_key} if a.row_key else None)
+        return d, _table([{"at": h["at"], "field": h["field"], "value": h["value"], "by": h.get("person") or h["who"]} for h in d["history"]], ["at", "field", "value", "by"])
+    if a.cmd == "plan":
+        d = c.call("GET", "/plan")
+        gb = lambda v: f"{(v or 0) / 2**30:.2f} GB"
+        t = d["today"]
+        lines = [f"plan: {d['plan']}",
+                 f"storage: {gb(d['storage']['used'])} of {gb(d['storage']['cap'])}",
+                 f"today: uploads {gb(t['upload_bytes']['used'])}/{gb(t['upload_bytes']['cap'])}, egress {gb(t['egress_bytes']['used'])}/{gb(t['egress_bytes']['cap'])}, "
+                 f"pipeline rows {int(t['pipeline_rows']['used']):,}/{int(t['pipeline_rows']['cap']):,}, compute {t['run_ms']['used']/60000:.0f}/{t['run_ms']['cap']/60000:.0f} min",
+                 f"AI today: ${d['ai']['customer_usd']:.2f} of ${d['ai_usd_day']:.2f} (this key); schedules at most every {d['schedule_min_minutes']} min"]
+        return d, "\n".join(lines)
+    if a.cmd == "claim":
+        d = c.call("POST", f"/try/{a.code}/claim", timeout=300)
+        return d, f"claimed: {len(d['written'])} facts landed as confirmed"
+    if a.cmd == "map":
+        d = c.call("GET", "/interview/coverage")
+        return d, _table([{k: x[k] for k in ("area", "state", "known", "confirmed", "weight")} for x in d["areas"]], ["area", "state", "known", "confirmed", "weight"])
+    if a.cmd == "interview":
+        return _interview(a, c)
+    if a.cmd == "facts":
+        d = c.call("GET", f"/context/facts/{a.table}")
+        rows = d["rows"]
+        cols = [k for k in (rows[0].keys() if rows else []) if k not in ("detail", "superseded_at")]
+        return d, _table(rows, cols) if rows else "(no rows)"
+    if a.cmd == "hook":
+        d = c.call("POST", "/hooks", json={"dish": a.dish, "table": a.table, "provider": a.provider, "secret": a.secret})
+        return d, f"hook address: {d['url']}\nlands in {d['dish']}.{d['table']}" + (f", signed by {d['provider']}" if d.get("provider") else ", unsigned")
+    if a.cmd == "hooks":
+        d = c.call("GET", "/hooks")
+        rows = [{"token": x["token"], "lands_in": f"{x['dish']}.{x['table']}", "provider": x.get("provider") or "", "received": x["received"],
+                 "rejected": x["rejected"], "url": x["url"]} for x in d["hooks"]]
+        return d, _table(rows, ["token", "lands_in", "provider", "received", "rejected", "url"])
+    if a.cmd == "hook-log":
+        d = c.call("GET", f"/hooks/{a.token}", params={"n": a.n})
+        rows = [{"when": x["received_at"], "ok": "landed", "ip": x.get("ip"), "detail": x["payload"][:60]} for x in d["deliveries"]]
+        rows += [{"when": x["at"], "ok": "REJECTED", "ip": x.get("ip"), "detail": x["reason"]} for x in d["rejections"]]
+        rows.sort(key=lambda r: str(r["when"]), reverse=True)
+        head = f"{d['dish']}.{d['table']}  received={d['received']} rejected={d['rejected']}\n"
+        return d, head + _table(rows, ["when", "ok", "ip", "detail"])
+    if a.cmd == "unhook":
+        d = c.call("DELETE", f"/hooks/{a.token}"); return d, f"removed ({d['deleted']})"
+    if a.cmd == "copy":
+        d = c.call("POST", f"/links/{a.dish}/copy", headers={"x-overscore-trigger": "cli"}, timeout=3600)
+        return d, "copied: " + ", ".join(f"{k} {v}" for k, v in d["copied"].items())
+    if a.cmd == "unlink":
+        d = c.call("DELETE", f"/links/{a.dish}"); return d, f"unlinked {a.dish}"
+    raise Fail(f"unknown command {a.cmd}")
+
+
+def _interview(a, c: Client):
+    """A back-and-forth in the terminal. Type 'done' to wrap up, 'skip' to move on, 'quit' to leave it open."""
+    if a.resume:
+        conv = a.resume
+        t = c.call("GET", f"/interview/{conv}")
+        q = next((m["text"] for m in reversed(t["messages"]) if m["role"] == "assistant"), "Where were we?")
+    else:
+        d = c.call("POST", "/interview", json={"area": a.area, "person": a.person})
+        conv, q = d["conversation"], d["question"]
+        print(f"(interview {conv}, area {d['area']}; say 'done' when it looks right, 'quit' to leave it open)\n")
+    while True:
+        print(f"> {q}\n")
+        try:
+            text = input("you: ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print(f"\nleft open; resume with: ovs interview --resume {conv}"); return {"conversation": conv}, ""
+        if not text:
+            continue
+        if text.lower() == "quit":
+            print(f"left open; resume with: ovs interview --resume {conv}"); return {"conversation": conv}, ""
+        if text.lower() == "done":
+            w = c.call("POST", f"/interview/{conv}/wrap", json={}, timeout=300)
+            lines = [f"saved {len(w['written'])} facts" + (f", set aside {w['ignored']}" if w["ignored"] else "")]
+            if w.get("first_read"):
+                lines += ["", "First read:", w["first_read"]]
+            lines += ["", "The map now: " + ", ".join(f"{x['area']} {x['state']}" for x in w["coverage"])]
+            return w, "\n".join(lines)
+        r = c.call("POST", f"/interview/{conv}", json={"text": text}, timeout=300)
+        for h in r["heard"]:
+            where = f" -> {h['target']}" if h.get("target") else ""
+            flag = "  [disagrees with what is written]" if h.get("conflict") else ""
+            print(f"  heard: {h['claim']}{where}{flag}")
+        if r["heard"]:
+            print()
+        q = r["question"]
+
+
+# --- the laptop side: a project folder, files, Python models, destinations, syncs (CLAUDE_CODE_PLAN.md) --------------
+#
+# Every command here calls a door the server already has; nothing is decided here that the server would decide.
+# The project folder:
+#   overscore.toml            url, dish (never the key)
+#   models/<name>/model.py    a Python model; model.toml beside it: reads, uploads, requirements, description, refresh
+#   files/<name>.<ext>        local copies of uploads
+#   syncs.toml                what goes where, written by ovs sync add
+#   .overscore/               pulled samples (data/), local outputs (out/), work dirs, environments; never committed
+
+PROJECT_FILE = "overscore.toml"
+LOCAL = ".overscore"
+DEFAULT_URL = "https://app.overscore.tech"
+PULL_MAX = 10_000              # what the query door answers at most
+SYNC_EVERY = ("5m", "15m", "60m", "6h", "24h")
+SHIPPED_SKILLS = ("overscore", "overscore-model", "overscore-sync")
+AGENTS = ("claude", "codex", "cursor", "gemini", "agents", "all")
+BLOCK_OPEN = "<!-- overscore:start"          # matched on this much, so a reworded start line is still found
+BLOCK_START = BLOCK_OPEN + " (written by ovs init, which rewrites this block; edit outside it) -->"
+BLOCK_END = "<!-- overscore:end -->"
+REWRITTEN = "<!-- Written by ovs init, which rewrites this file; put your own steps in another file. -->"
+
+
+def _find_project(start: str | os.PathLike | None = None) -> pathlib.Path | None:
+    """The nearest folder at or above `start` with an overscore.toml, like git finds .git."""
+    d = pathlib.Path(start or os.getcwd()).resolve()
+    for p in (d, *d.parents):
+        if (p / PROJECT_FILE).is_file():
+            return p
+    return None
+
+
+def _read_toml(path: pathlib.Path) -> dict:
+    import tomllib
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except tomllib.TOMLDecodeError as e:
+        raise Fail(f"{path.name} does not parse: {e}")
+    except UnicodeDecodeError:
+        raise Fail(f"{path.name} is not UTF-8 text; save it as UTF-8") from None
+
+
+def _project(a, required: bool = True) -> pathlib.Path | None:
+    root = getattr(a, "project", None) or _find_project()
+    if root is None and required:
+        raise Fail("this folder is not an Overscore project: run ovs init --dish <dish> here first")
+    return root
+
+
+def _config(root: pathlib.Path | None) -> dict:
+    return _read_toml(root / PROJECT_FILE) if root and (root / PROJECT_FILE).is_file() else {}
+
+
+NAME_RE = re.compile(r"^[a-z][a-z0-9_]{0,62}$")    # the server's rule for dishes, tables, models, uploads and syncs
+
+
+def _name(n: str, what: str) -> str:
+    """Names go into paths on this machine and into door URLs: hold them to the server's rule first."""
+    if not NAME_RE.match(n or ""):
+        raise Fail(f"a {what} name is lowercase letters, digits and underscores, starting with a letter: {n!r}")
+    return n
+
+
+def _dish(a, *more: str | None) -> str:
+    for d in (getattr(a, "dish", None), *more, _config(_project(a, False)).get("dish")):
+        if d:
+            return _name(d, "dish")
+    raise Fail("which dish? pass --dish, or write it into overscore.toml with ovs init --dish <dish>")
+
+
+def _split(ref: str, dish: str | None) -> tuple[str, str]:
+    d, _, t = ref.strip().rpartition(".")
+    if not (d or dish):
+        raise Fail(f"say which dish {ref} is in: dish.{ref}")
+    return _name(d or dish, "dish"), _name(t, "table")
+
+
+def _sq(s: str | os.PathLike) -> str:
+    return str(s).replace("'", "''")
+
+
+def _plain(v):
+    """A value from DuckDB as something JSON can carry, the way the server's query door does it (NaN and infinity as text)."""
+    if isinstance(v, float) and (v != v or v in (float("inf"), float("-inf"))):
+        return str(v)
+    if isinstance(v, (bytes, bytearray)):
+        return v.hex()
+    if hasattr(v, "isoformat"):
+        return v.isoformat()
+    if isinstance(v, (list, tuple)):
+        return [_plain(x) for x in v]
+    if isinstance(v, dict):
+        return {k: _plain(x) for k, x in v.items()}
+    try:
+        json.dumps(v)
+        return v
+    except TypeError:
+        return str(v)
+
+
+def _when(ts) -> str:
+    try:
+        return time.strftime("%Y-%m-%d %H:%M", time.localtime(float(ts)))
+    except (TypeError, ValueError):
+        return str(ts or "")
+
+
+def _sha256(path: pathlib.Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+# --- files (uploads) ----------------------------------------------------------------------------------------------
+
+def _uploads_list(c: Client) -> list[dict]:
+    return c.call("GET", "/uploads")["uploads"]
+
+
+def _uploads(a, c: Client):
+    d = {"uploads": _uploads_list(c)}
+    rows = []
+    for u in d["uploads"]:
+        live = next((v for v in u["versions"] if v["version"] == u["live"]), None) or {}
+        rows.append({"name": u["name"], "live": f"v{u['live']}" if u["live"] else "none", "versions": len(u["versions"]),
+                     "file": live.get("filename", ""), "bytes": live.get("size", ""), "by": live.get("uploaded_by", ""),
+                     "when": _when(live.get("uploaded_at")), "note": live.get("note", "")})
+    return d, _table(rows, ["name", "live", "versions", "file", "bytes", "by", "when", "note"]) if rows else "(no files yet: ovs upload put <name> <file>)"
+
+
+def _upload(a, c: Client):
+    if a.sub == "list":
+        return _uploads(a, c)
+    _name(a.name, "file")
+    if a.sub == "put":
+        path = pathlib.Path(a.file)
+        if not path.is_file():
+            raise Fail(f"no file at {a.file}")
+        with open(path, "rb") as f:
+            d = c.call("POST", f"/uploads/{a.name}", params={"filename": path.name, "note": a.note or ""}, data=f,
+                       headers={"Content-Type": "application/octet-stream"}, timeout=900)
+        return d, f"uploaded {a.name} v{d['version']} ({d['filename']}, {d['size']:,} bytes), live now"
+    if a.sub == "live":
+        d = c.call("POST", f"/uploads/{a.name}/live", json={"version": a.version})
+        return d, f"{a.name}: v{d['live']} is live; models that read it use it from their next run"
+    if a.sub == "rm":
+        d = c.call("DELETE", f"/uploads/{a.name}")
+        return d, f"removed {a.name} and every version of it" if d["removed"] else f"there was no file called {a.name}"
+    raise Fail(f"unknown upload command {a.sub}")
+
+
+def _local_file(root: pathlib.Path, name: str) -> pathlib.Path | None:
+    """files/<name>.<ext> (or files/<name>): the local copy of an upload."""
+    folder = root / "files"
+    if not folder.is_dir():
+        return None
+    hits = sorted(p for p in folder.iterdir() if p.is_file() and (p.name == name or p.name.startswith(name + ".")))
+    if len(hits) > 1:
+        raise Fail(f"more than one local file for {name} in files/: {', '.join(p.name for p in hits)}; keep one")
+    return hits[0] if hits else None
+
+
+# --- python models --------------------------------------------------------------------------------------------------
+
+def _model(a, name: str) -> tuple[pathlib.Path, pathlib.Path, dict, str]:
+    """(project root, the model's folder, model.toml, model.py) for models/<name>."""
+    root = _project(a)
+    folder = root / "models" / _name(name, "model")
+    if not (folder / "model.py").is_file():
+        raise Fail(f"no models/{name}/model.py in {root}")
+    cfg = _read_toml(folder / "model.toml") if (folder / "model.toml").is_file() else {}
+    for k in ("reads", "uploads"):
+        v = cfg.get(k, [])
+        if isinstance(v, str):
+            v = [v]
+        if not isinstance(v, list) or not all(isinstance(x, str) for x in v):
+            raise Fail(f"models/{name}/model.toml: {k} is a list of names, like {k} = [\"a\", \"b\"]")
+        cfg[k] = [x.strip() for x in v if x.strip()]
+    req = cfg.get("requirements", "")
+    cfg["requirements"] = "\n".join(req) if isinstance(req, list) else str(req or "")
+    if not cfg["reads"]:
+        raise Fail(f"models/{name}/model.toml: say which tables the model reads, like reads = [\"dish.table\"]")
+    return root, folder, cfg, (folder / "model.py").read_text(encoding="utf-8")
+
+
+def _check_script(script: str) -> None:
+    """What the server checks when the script is saved, checked here first."""
+    if "overscore_model" not in script:
+        raise Fail("model.py should import from overscore_model (inputs, read, rows, file, output, log)")
+    if "output(" not in script:
+        raise Fail("model.py never calls output(rows); nothing would become the table")
+    try:
+        compile(script, "model.py", "exec")
+    except SyntaxError as e:
+        raise Fail(f"model.py does not parse: line {e.lineno}: {e.msg}") from None
+
+
+def _last_run(c: Client, dish: str, name: str, run_id: int | None = None) -> dict | None:
+    if run_id is None:
+        rs = c.call("GET", "/runs", params={"kind": "model", "dish": dish, "limit": 500})["runs"]     # the door's most; it has no name filter
+        mine = next((r for r in rs if r["name"] == name), None)
+        if not mine:
+            return None
+        run_id = mine["id"]
+    return c.call("GET", f"/runs/{run_id}")
+
+
+def _run_there(c: Client, dish: str, name: str) -> tuple[dict, str]:
+    """Run the model in Overscore and read its log: the receipt."""
+    d = c.call("POST", f"/models/{dish}/{name}/run", timeout=3600)
+    res = next((r for r in reversed(d.get("results") or []) if (r.get("model") or r.get("name")) == name), None) or {}
+    run = _last_run(c, dish, name, res.get("run_id")) if res.get("run_id") else None
+    log = (run or {}).get("log") or ""
+    out = {"model": f"{dish}.{name}", "ok": bool(res.get("ok")), "rows": res.get("rows"), "ms": res.get("ms"),
+           "run_id": res.get("run_id"), "error": res.get("error"), "log": log, "results": d.get("results")}
+    head = (f"ran {dish}.{name} in Overscore: {'ok' if out['ok'] else 'FAILED'}"
+            + (f", {out['rows']:,} rows" if out["rows"] is not None else "") + (f", {out['ms'] / 1000:.1f}s" if out["ms"] else "")
+            + (f" (run {out['run_id']})" if out["run_id"] else ""))
+    text = head + ("\n" + log.rstrip() if log else "") + (f"\nerror: {out['error']}" if out["error"] else "")
+    if not out["ok"]:
+        raise Fail(out["error"] or f"{dish}.{name} did not build", data={k: v for k, v in out.items() if k != "results"})
+    return out, text
+
+
+def _model_cmd(a, c: Client):
+    if a.sub == "run" and a.local:
+        return _run_local(a)
+    if a.sub == "run":
+        dish = _dish(a, _model_dish_hint(a, a.name))
+        return _run_there(c, dish, a.name)
+    if a.sub == "push":
+        return _push(a, c)
+    if a.sub == "log":
+        dish = _dish(a, _model_dish_hint(a, a.name))
+        run = _last_run(c, dish, a.name)
+        if not run:
+            raise Fail(f"no run of {dish}.{a.name} among the last 500 model runs in {dish}; ovs runs lists them")
+        text = (f"run {run['id']}: {run['status']}, {run.get('trigger') or ''}, {_when(run.get('started_at'))}"
+                + (f", {run['rows']:,} rows" if run.get("rows") is not None else "") + "\n" + (run.get("log") or "(no log)").rstrip())
+        if run.get("error"):
+            text += f"\nerror: {run['error']}"
+        return run, text
+    raise Fail(f"unknown model command {a.sub}")
+
+
+def _model_dish_hint(a, name: str) -> str | None:
+    """model.toml may name the dish, when the folder exists."""
+    root = _project(a, False)
+    p = root / "models" / _name(name, "model") / "model.toml" if root else None
+    return _read_toml(p).get("dish") if p and p.is_file() else None
+
+
+def _push(a, c: Client):
+    root, folder, cfg, script = _model(a, a.name)
+    dish = _dish(a, cfg.get("dish"))
+    _check_script(script)
+    notes = []
+    if cfg["uploads"]:
+        have = {u["name"]: u for u in _uploads_list(c)}
+        for u in cfg["uploads"]:
+            local = _local_file(root, u)
+            there = have.get(u)
+            if not there or there["live"] is None:
+                hint = f"ovs upload put {u} {os.path.relpath(local)}" if local else f"ovs upload put {u} <file>"
+                raise Fail(f"the file {u} is not in Overscore yet: {hint}")
+            live = next(v for v in there["versions"] if v["version"] == there["live"])
+            if local and _sha256(local) != live["sha256"]:
+                notes.append(f"{local.relative_to(root)} is not the live {u} in Overscore (v{there['live']}, {live['filename']}); "
+                             f"the run there uses v{there['live']}. To send yours: ovs upload put {u} {os.path.relpath(local)}")
+    body = {"script": script, "reads": cfg["reads"], "uploads": cfg["uploads"], "requirements": cfg["requirements"],
+            "description": cfg.get("description", ""), "refresh": cfg.get("refresh")}
+    saved = c.call("PUT", f"/models/{dish}/{a.name}/python", json=body)
+    out = {"saved": saved, "model": f"{dish}.{a.name}", "notes": notes}
+    text = (f"saved {dish}.{a.name}: reads {', '.join(saved.get('reads') or cfg['reads'])}"
+            + (f"; files {', '.join(cfg['uploads'])}" if cfg["uploads"] else "") + f"; refresh {saved.get('refresh')}")
+    text += "".join(f"\nnote: {n}" for n in notes)
+    if a.no_run:
+        return out, text + f"\nnot run; ovs model run {a.name} runs it"
+    try:
+        ran, ran_text = _run_there(c, dish, a.name)
+    except Fail as e:
+        e.data = {**out, **e.data}
+        raise
+    return {**out, "run": ran}, text + "\n" + ran_text
+
+
+# --- pull: a sample of a table as Parquet, for local runs -----------------------------------------------------------
+
+def _data_path(root: pathlib.Path, dish: str, table: str) -> pathlib.Path:
+    return root / LOCAL / "data" / dish / f"{table}.parquet"
+
+
+def _ident(col: str) -> str:
+    return '"' + col.replace('"', '""') + '"'
+
+
+def _pull_plan(types: dict) -> tuple[list[str], dict, set]:
+    """How each column crosses the query door and comes back typed.
+
+    The door hands JSON as text, bytes as hex, and cannot carry NaN or infinity at all (a 500); an interval comes as
+    Python's text, which DuckDB will not read back. So those are asked for as DuckDB's own text and cast back here,
+    and JSON nested in a list or struct is asked for as one JSON text and parsed back before reading.
+    Returns (the select's replace list, {column: (read as, pick expression)}, columns to parse from JSON text)."""
+    reps, how, nested = [], {}, set()
+    for col, t in types.items():
+        i, T = _ident(col), t.upper()
+        if T in ("DOUBLE", "FLOAT", "REAL") or T.startswith("INTERVAL"):
+            reps.append(f"{i}::VARCHAR as {i}")
+            how[col] = ("VARCHAR", f"{i}::{'INTERVAL' if T.startswith('INTERVAL') else T} as {i}")    # never the server's text in SQL
+        elif T == "JSON":
+            how[col] = ("VARCHAR", f"{i}::JSON as {i}")
+        elif T == "BLOB":
+            how[col] = ("VARCHAR", f"unhex({i}) as {i}")
+        elif "JSON" in T or any(x in T for x in ("DOUBLE", "FLOAT", "REAL")):
+            reps.append(f"to_json({i}) as {i}")
+            nested.add(col)
+            how[col] = (t, i)
+        else:
+            how[col] = (t, i)
+    return reps, how, nested
+
+
+def _pull(a, c: Client):
+    import duckdb
+    root = _project(a)
+    n = max(1, min(a.rows or PULL_MAX, PULL_MAX))
+    out, lines = {"pulled": []}, []
+    for ref in a.tables:
+        dish, table = _split(ref, _dish(a) if "." not in ref else None)
+        types = {x["column"]: x["type"] for x in c.call("GET", f"/tables/{dish}/{table}")["columns"]}
+        where = f" where {a.where}" if a.where else ""
+        reps, how, nested = _pull_plan(types)
+        total = c.call("POST", "/query", json={"sql": f"select count(*) from {dish}.{table}{where}", "max_rows": 1})["rows"][0][0]
+        star = "select * replace (" + ", ".join(reps) + ")" if reps else "select *"
+        q = c.call("POST", "/query", json={"sql": f"{star} from {dish}.{table}{where} limit {n}", "max_rows": n}, timeout=900)
+        cols = q["columns"]
+        dest = _data_path(root, dish, table)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        raw = dest.with_name(f".{table}.rows.jsonl")
+        with open(raw, "w", encoding="utf-8") as f:
+            for r in q["rows"]:
+                row = dict(zip(cols, r))
+                for col in nested:
+                    if isinstance(row.get(col), str):
+                        row[col] = json.loads(row[col])
+                f.write(json.dumps(row) + "\n")
+        spec = lambda cs: ", ".join(f"'{_sq(col)}': '{_sq(how.get(col, ('VARCHAR', ''))[0])}'" for col in cs)
+        src = lambda cs: f"read_json('{_sq(raw)}', format='newline_delimited', columns={{{spec(cs)}}})"
+        pick = lambda col: how.get(col, ("VARCHAR", _ident(col)))[1] or _ident(col)
+        guessed: list[str] = []
+        con = duckdb.connect()
+        try:
+            con.execute("set TimeZone='UTC'")      # Overscore's machines run in UTC; moments are written the way they write them
+            try:
+                con.execute(f"create table t as select {', '.join(pick(col) for col in cols)} from {src(cols)}")
+            except duckdb.Error:
+                # one column that will not come back typed keeps its text; the others keep their types
+                for col in cols:
+                    try:
+                        con.execute(f"select {pick(col)} from {src([col])}").fetchall()
+                    except duckdb.Error:
+                        how[col] = ("VARCHAR", _ident(col))
+                        guessed.append(col)
+                con.execute(f"create table t as select {', '.join(pick(col) for col in cols)} from {src(cols)}")
+            con.execute(f"copy t to '{_sq(dest)}' (format parquet)")
+            con.execute(f"copy t to '{_sq(dest.with_suffix('.jsonl'))}' (format json)")    # what rows() reads, written as the server writes it
+            kept = [{"column": r[0], "type": r[1]} for r in con.execute("describe t").fetchall()]
+        finally:
+            con.close()
+            raw.unlink(missing_ok=True)
+        meta = {"table": f"{dish}.{table}", "rows": len(q["rows"]), "of": total, "where": a.where or None,
+                "pulled_at": time.time(), "columns": kept, "kept_as_text": guessed}
+        dest.with_suffix(".json").write_text(json.dumps(meta, indent=1), encoding="utf-8")
+        out["pulled"].append({**meta, "path": str(dest.relative_to(root))})
+        lines.append(f"pulled {dish}.{table}: {len(q['rows']):,} of {total:,} rows{' (' + a.where + ')' if a.where else ''} -> {dest.relative_to(root)}"
+                     + (f"\n  kept as text, not as their types in Overscore: {', '.join(guessed)}" if guessed else ""))
+    return out, "\n".join(lines)
+
+
+# --- local run: model.py on this machine, the way Overscore runs it ----------------------------------------------
+
+def _helper_source() -> pathlib.Path:
+    here = pathlib.Path(__file__).with_name("model_helper.py")
+    if here.is_file():
+        return here
+    import overscore_model   # the installed package carries it at the top level
+    return pathlib.Path(overscore_model.__file__)
+
+
+SERVER_PYTHON = "3.12"      # what Overscore runs scripts on
+
+
+def _real_python(py: str) -> str:
+    """The interpreter a shim (pyenv, asdf, mise) stands for: the script runs with its own HOME, where no shim works."""
+    try:
+        r = subprocess.run([py, "-c", "import sys; print(sys.executable)"], capture_output=True, text=True, timeout=60)
+    except (OSError, subprocess.TimeoutExpired) as e:
+        raise Fail(f"could not start {py}: {e}") from None
+    return r.stdout.strip() if r.returncode == 0 and r.stdout.strip() else py
+
+
+def _local_python(a, requirements: str, root: pathlib.Path, log) -> str:
+    """--python; else a Python 3.12 environment built with uv from the requirements, empty when there are none, so a
+    library the script forgets to list fails here and not only there; else python3 from PATH, said so in the log."""
+    if getattr(a, "python", None):
+        py = os.path.abspath(a.python) if (os.sep in a.python or a.python.startswith(".")) else shutil.which(a.python)
+        if not py or not os.path.isfile(py) or not os.access(py, os.X_OK):
+            raise Fail(f"no interpreter at {a.python}")
+        return _real_python(py)
+    req = "\n".join(l.strip() for l in requirements.splitlines() if l.strip() and not l.strip().startswith("#"))
+    uv = shutil.which("uv")
+    if not uv:
+        if req:
+            raise Fail("model.toml lists requirements; install uv (https://docs.astral.sh/uv/) so ovs can build an environment from them, or pass --python")
+        real = _real_python(shutil.which("python3") or sys.executable)
+        log(f"no uv here: ran with {real}, whose libraries Overscore does not have; install uv to run as Overscore does")
+        return real
+    d = root / LOCAL / "venvs" / hashlib.sha256(f"{SERVER_PYTHON}\n{req}".encode()).hexdigest()[:16]
+    py = d / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+    d.parent.mkdir(parents=True, exist_ok=True)
+    with open(d.parent / f"{d.name}.lock", "w") as lock:
+        try:
+            import fcntl
+            fcntl.flock(lock, fcntl.LOCK_EX)       # released when the file closes, or the process ends
+        except ImportError:
+            pass
+        if (d / ".ready").is_file() and py.exists():
+            return str(py)
+        shutil.rmtree(d, ignore_errors=True)       # a half-built one from a run that was stopped
+        t0 = time.time()
+        rf = d.parent / f"{d.name}.requirements.txt"
+        try:
+            r = subprocess.run([uv, "venv", "--quiet", "--python", SERVER_PYTHON, str(d)], capture_output=True, text=True, timeout=600)
+            if r.returncode != 0:                  # no 3.12 to be had (offline, downloads off): the nearest Python, said so
+                shutil.rmtree(d, ignore_errors=True)
+                r = subprocess.run([uv, "venv", "--quiet", str(d)], capture_output=True, text=True, timeout=600)
+                if r.returncode == 0:
+                    log(f"Overscore runs Python {SERVER_PYTHON}; none here, so this ran on {_real_python(str(py))}")
+            if r.returncode == 0 and req:
+                rf.write_text(req + "\n", encoding="utf-8")
+                r = subprocess.run([uv, "pip", "install", "--quiet", "--python", str(py), "-r", str(rf)], capture_output=True, text=True, timeout=1800)
+            if r.returncode != 0:
+                raise Fail(("requirements did not install: " if req else "could not make a Python environment: ")
+                           + ((r.stderr or r.stdout).strip().splitlines() or ["uv failed"])[-1][:300])
+            (d / ".ready").write_text(req + "\n", encoding="utf-8")
+        except subprocess.TimeoutExpired:
+            shutil.rmtree(d, ignore_errors=True)
+            raise Fail("installing the requirements took too long (30 minutes); try again, or pass --python") from None
+        except BaseException:
+            shutil.rmtree(d, ignore_errors=True)
+            raise
+        finally:
+            rf.unlink(missing_ok=True)
+    if req:
+        log(f"installed requirements in {time.time() - t0:.1f}s")
+    return str(py)
+
+
+def _run_local(a):
+    import duckdb
+    root, folder, cfg, script = _model(a, a.name)
+    dish = _dish(a, cfg.get("dish"))
+    _check_script(script)
+    echo = getattr(a, "echo", False)
+    logs: list[str] = []
+
+    def log(line: str) -> None:
+        logs.append(line)
+        if echo:
+            print("  " + line, flush=True)
+
+    inputs, samples, missing = {}, {}, []
+    for rd in cfg["reads"]:
+        d, t = _split(rd, dish)
+        p = _data_path(root, d, t)
+        if not p.is_file():
+            missing.append(f"{d}.{t}")
+            continue
+        inputs[f"{d}.{t}"] = str(p)
+        meta = json.loads(p.with_suffix(".json").read_text(encoding="utf-8")) if p.with_suffix(".json").is_file() else {}
+        samples[f"{d}.{t}"] = {"rows": meta.get("rows"), "of": meta.get("of"), "pulled_at": meta.get("pulled_at")}
+    if missing:
+        raise Fail("pull the tables it reads first: " + " && ".join(f"ovs pull {m}" for m in missing))
+    files = {}
+    for u in cfg["uploads"]:
+        lf = _local_file(root, u)
+        if not lf:
+            raise Fail(f"model.toml needs the file {u}; put a copy at files/{u}.<ext> (Overscore never hands uploads back)")
+        files[u] = str(lf)
+    python = _local_python(a, cfg["requirements"], root, log)
+    (root / LOCAL / "work").mkdir(parents=True, exist_ok=True)
+    work = pathlib.Path(tempfile.mkdtemp(prefix=f"{a.name}-", dir=root / LOCAL / "work"))
+    try:
+        # only model.py and the helper sit beside each other, as in Overscore: a second file imported locally would not be there
+        shutil.copy(folder / "model.py", work / "model.py")
+        shutil.copy(_helper_source(), work / "overscore_model.py")
+        out_path = work / "output.jsonl"
+        # the environment Overscore gives a script, built from nothing: no key, no PYTHONPATH, no caches in a home folder,
+        # and every proxy pointed at a closed port, so a download that works on a laptop fails here as it would there
+        closed = "http://127.0.0.1:9"
+        env = {"PATH": os.environ.get("PATH", "/usr/bin:/bin"), "HOME": str(work), "LANG": "C.UTF-8", "TZ": "UTC",
+               "PYTHONUNBUFFERED": "1", "PYTHONDONTWRITEBYTECODE": "1", "OVERSCORE_DISH": dish, "OVERSCORE_MODEL": a.name,
+               "OVERSCORE_INPUTS": json.dumps(inputs), "OVERSCORE_FILES": json.dumps(files), "OVERSCORE_OUTPUT": str(out_path),
+               **{k: closed for k in ("HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "http_proxy", "https_proxy", "all_proxy")}, "NO_PROXY": "", "no_proxy": ""}
+        if os.name == "nt":
+            env["SYSTEMROOT"] = os.environ.get("SYSTEMROOT", "")
+        shown = f"models/{a.name}/model.py"
+        fix = lambda s: s.replace(f'File "{work / "model.py"}"', f'File "{shown}"').replace('File "model.py"', f'File "{shown}"')
+        for full, s in samples.items():
+            log(f"input {full}" + (f": {s['rows']:,} rows" if s.get("rows") is not None else "")
+                + (f" (a sample of {s['of']:,})" if s.get("of") is not None and s.get("rows") is not None and s["of"] != s["rows"] else ""))
+        rows_out: list[int | None] = [None]
+        err: list[str] = []
+        t0 = time.time()
+        try:
+            proc = subprocess.Popen([python, "model.py"], cwd=work, env=env, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, bufsize=1)
+        except OSError as e:
+            raise Fail(f"could not start {python}: {e}") from None
+
+        def drain() -> None:
+            for line in proc.stderr:
+                err.append(fix(line.rstrip("\n")))
+        t_err = threading.Thread(target=drain, daemon=True)
+        t_err.start()
+        for line in proc.stdout:
+            line = line.rstrip("\n")
+            msg = {"log": line}
+            if line.startswith("@overscore "):
+                try:
+                    msg = json.loads(line[len("@overscore "):])
+                except ValueError:
+                    pass
+            if "output" in msg:
+                rows_out[0] = int((msg["output"] or {}).get("rows") or 0)
+            elif "log" in msg:
+                log(str(msg["log"]))
+        proc.wait()
+        t_err.join(timeout=5)
+        ms = round((time.time() - t0) * 1000)
+        base = {"model": f"{dish}.{a.name}", "where": "local", "log": logs, "stderr": err[-30:], "inputs": samples, "files": files, "ms": ms}
+        if proc.returncode != 0:
+            last = next((l for l in reversed(err) if l.strip()), f"exit {proc.returncode}")
+            raise Fail(f"model.py failed: {last[:300]}", data=base)
+        if rows_out[0] is None or not out_path.exists():
+            raise Fail("model.py finished without calling output(rows)", data=base)
+        if rows_out[0] == 0:
+            raise Fail("model.py returned no rows; in Overscore the table would be left as it was", data=base)
+        # land it the way the server lands it, so the types shown are the types the table gets
+        result = root / LOCAL / "out" / f"{a.name}.parquet"
+        result.parent.mkdir(parents=True, exist_ok=True)
+        con = duckdb.connect()
+        try:
+            con.execute("set TimeZone='UTC'")
+            con.execute(f"create table t as select * from read_json_auto('{_sq(out_path)}', maximum_object_size=67108864)")
+            n = con.execute("select count(*) from t").fetchone()[0]
+            types = [{"column": r[0], "type": r[1]} for r in con.execute("describe t").fetchall()]
+            cur = con.execute("select * from t limit 10")
+            names = [x[0] for x in cur.description]
+            preview = [{k: _plain(v) for k, v in zip(names, r)} for r in cur.fetchall()]
+            con.execute(f"copy t to '{_sq(result)}' (format parquet)")
+        finally:
+            con.close()
+        out = {**base, "ok": True, "rows": n, "columns": types, "preview": preview, "output": str(result.relative_to(root))}
+        sampled = [f"{k} {v['rows']:,} of {v['of']:,}" for k, v in samples.items() if v.get("of") is not None and v.get("rows") is not None and v["of"] != v["rows"]]
+        text = "\n".join([
+            *([] if echo else ["log:", *("  " + l for l in logs)]),
+            *(["stderr (Overscore keeps these only when the script fails):", *("  " + l for l in err[-30:])] if err else []),
+            f"{n:,} rows in {ms / 1000:.1f}s -> {result.relative_to(root)}" + (f"  (ran on samples: {', '.join(sampled)})" if sampled else ""),
+            "columns: " + ", ".join(f"{t['column']} {t['type']}" for t in types),
+            _table(preview, names),
+            f"next: ovs model push {a.name}"])
+        return out, text
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+
+
+# --- destinations and syncs -----------------------------------------------------------------------------------------
+
+def _destinations_list(c: Client) -> list[dict]:
+    return c.call("GET", "/destinations")["destinations"]
+
+
+def _destination(c: Client, ref: str) -> dict:
+    ds = _destinations_list(c)
+    hit = [d for d in ds if d["id"] == ref] or [d for d in ds if d["title"].strip().lower() == ref.strip().lower()]
+    if not hit:
+        raise Fail(f"no destination {ref}; ovs destinations lists them")
+    if len(hit) > 1:
+        raise Fail(f"{len(hit)} destinations are called {ref}; use the id: {', '.join(d['id'] for d in hit)}")
+    return hit[0]
+
+
+def _target(d: dict) -> str:
+    cfg = d.get("config") or {}
+    if d["kind"] == "webhook":
+        return cfg.get("url", "")
+    return f"{cfg.get('object')}" + (f" by {cfg['id_property']}" if cfg.get("id_property") else " by record id") + (f", key of {cfg['source']}" if cfg.get("source") else "")
+
+
+def _destinations(a, c: Client):
+    ds = _destinations_list(c)
+    rows = [{"id": d["id"], "kind": d["kind"], "title": d["title"], "goes_to": _target(d), "syncs": len(d.get("syncs") or [])} for d in ds]
+    return {"destinations": ds}, _table(rows, ["id", "kind", "title", "goes_to", "syncs"]) if rows else "(no destinations yet)"
+
+
+def _destination_cmd(a, c: Client):
+    if a.sub == "list":
+        return _destinations(a, c)
+    if a.sub == "add":
+        if a.kind == "webhook":
+            if not a.webhook_url:
+                raise Fail('a webhook destination needs its URL: ovs destination add webhook "<title>" https://...')
+            d = c.call("POST", "/destinations", json={"kind": "webhook", "title": a.title, "config": {"url": a.webhook_url}})
+            return d, (f"added {d['title']} ({d['id']}): every batch of changed rows is POSTed to {a.webhook_url} as JSON\n"
+                       f"signing secret (shown once, keep it where their side can check X-Overscore-Signature): {d['signing_secret']}")
+        if a.kind == "hubspot":
+            token = sys.stdin.readline().strip() if a.token == "-" else (a.token or "")
+            if not token and not a.source:
+                raise Fail("say whose HubSpot key to use: --source <dish.source> (the HubSpot source's own key), or --token - to read one from stdin")
+            d = c.call("POST", "/destinations", json={"kind": "hubspot", "title": a.title,
+                                                       "config": {"object": a.object, "id_property": a.id_property, "source": a.source},
+                                                       "secrets": {"hubspot_token": token} if token else {}})
+            return d, f"added {d['title']} ({d['id']}): rows become properties on HubSpot {_target(d)}\ncheck the key can write: ovs destination check {d['id']}"
+        raise Fail("a destination is webhook or hubspot")
+    dest = _destination(c, a.dest)
+    if a.sub == "check":
+        d = c.call("POST", f"/destinations/{dest['id']}/check", timeout=120)
+        return d, f"{dest['title']}: ok in {d.get('ms')} ms" + (f", {d['properties']} properties on {d['object']}" if d.get("object") else f", answered {d.get('status')}")
+    if a.sub == "rm":
+        # the destination door leaves a scheduled sync's clock behind, failing every interval; the sync door clears it
+        root = _project(a, False)
+        syncs = _read_syncs(root)
+        gone = []
+        for sy in dest.get("syncs") or []:
+            c.call("DELETE", f"/syncs/{sy['id']}")
+            gone.append(sy["name"])
+            for k in [k for k, e in syncs.items() if e.get("id") == sy["id"]]:
+                del syncs[k]
+        d = c.call("DELETE", f"/destinations/{dest['id']}")
+        if root and (root / "syncs.toml").is_file():
+            _write_syncs(root, syncs)
+        return {**d, "syncs_removed": gone}, f"removed {dest['title']}" + (f" and its syncs: {', '.join(gone)}" if gone else "")
+    raise Fail(f"unknown destination command {a.sub}")
+
+
+def _all_syncs(c: Client) -> list[dict]:
+    return [{**s, "to": d["title"], "to_kind": d["kind"]} for d in _destinations_list(c) for s in (d.get("syncs") or [])]
+
+
+def _sync_ref(a, c: Client, ref: str) -> dict:
+    ss = _all_syncs(c)
+    hit = [s for s in ss if s["id"] == ref] or [s for s in ss if s["name"] == ref]
+    if len(hit) > 1:
+        dish = getattr(a, "dish", None) or _config(_project(a, False)).get("dish")
+        hit = [s for s in hit if s["dish"] == dish] or hit
+    if not hit:
+        raise Fail(f"no sync {ref}; ovs syncs lists them")
+    if len(hit) > 1:
+        raise Fail(f"{len(hit)} syncs are called {ref}; use the id: {', '.join(s['id'] + ' (' + s['dish'] + ')' for s in hit)}")
+    return hit[0]
+
+
+def _when_text(s: dict) -> str:
+    return {"after_change": "after the table changes", "manual": "by hand"}.get(s["trigger"], f"every {s.get('every')}")
+
+
+def _syncs(a, c: Client):
+    ss = _all_syncs(c)
+    rows = [{"name": s["name"], "dish": s["dish"], "from": s["source"][:40], "key": s["key"], "to": s["to"], "when": _when_text(s),
+             "on": "yes" if s["enabled"] else "paused", "last": f"{s.get('last_status') or '-'} {_when(s['last_run_at']) if s.get('last_run_at') else ''}".strip(),
+             "sent": s.get("sent_total") or 0, "refused": s.get("failures") or 0} for s in ss]
+    return {"syncs": ss}, _table(rows, ["name", "dish", "from", "key", "to", "when", "on", "last", "sent", "refused"]) if rows else "(no syncs yet)"
+
+
+SYNCS_HEADER = """# syncs.toml: what goes where, one [name] per sync.
+# `ovs sync add <name> --from <table> --key <column> --to <destination>` sets one up in Overscore and writes it here.
+# Edit an entry, then run `ovs sync add <name>` to apply it; editing this file alone changes nothing in Overscore.
+# ovs rewrites this file when it adds or removes a sync: comments below this header are not kept.
+#   from     the table in the dish (or sql = "select ..." in its place)
+#   key      the column that identifies the record at the destination
+#   to       the destination's name or id (ovs destinations)
+#   columns  column = "field at the destination"; leave it out to send every column but the key, as the table
+#            has them when `ovs sync add` runs (run it again to pick up a new column)
+#   when     after_change | manual | every 5m | every 15m | every 60m | every 6h | every 24h
+#   id       filled in by ovs
+"""
+SYNC_KEYS = ("dish", "from", "sql", "key", "to", "columns", "when", "id")
+
+
+def _toml_key(k: str) -> str:
+    return k if re.fullmatch(r"[A-Za-z0-9_-]+", k) else _toml_str(k)
+
+
+def _toml_value(v) -> str:
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, (int, float)):
+        return str(v)
+    if isinstance(v, list):
+        return "[" + ", ".join(_toml_value(x) for x in v) + "]"
+    if isinstance(v, dict):
+        return "{ " + ", ".join(f"{_toml_key(k)} = {_toml_value(x)}" for k, x in v.items()) + " }"
+    return _toml_str(str(v))
+
+
+def _toml_str(v: str) -> str:
+    """A TOML basic string: JSON's escapes, but characters beyond the first plane kept as themselves (TOML refuses
+    JSON's surrogate pairs) and DEL escaped (TOML refuses it bare)."""
+    return json.dumps(v, ensure_ascii=False).replace("\x7f", "\\u007f")
+
+
+def _read_syncs(root: pathlib.Path | None) -> dict:
+    p = root / "syncs.toml" if root else None
+    return _read_toml(p) if p and p.is_file() else {}
+
+
+def _write_syncs(root: pathlib.Path, syncs: dict) -> None:
+    parts = [SYNCS_HEADER.rstrip("\n")]
+    for name, e in syncs.items():
+        lines = [f"[{_toml_key(name)}]"]
+        lines += [f"{k} = {_toml_value(e[k])}" for k in (*SYNC_KEYS, *(k for k in e if k not in SYNC_KEYS)) if e.get(k) not in (None, "", [], {})]
+        parts.append("\n".join(lines))
+    text = "\n\n".join(parts) + "\n"
+    import tomllib
+    tomllib.loads(text)     # never leave a file that will not read back
+    (root / "syncs.toml").write_text(text, encoding="utf-8")
+
+
+def _columns(items: list[str]) -> dict:
+    out = {}
+    for it in items:
+        col, _, field = it.partition("=")
+        out[col.strip()] = field.strip() or col.strip()
+    return out
+
+
+def _sync_add(a, c: Client):
+    _name(a.name, "sync")
+    root = _project(a, False)
+    syncs = _read_syncs(root)
+    e = dict(syncs.get(a.name) or {})
+    if a.source:
+        e["from"] = a.source; e.pop("sql", None)
+    if a.sql:
+        e["sql"] = a.sql; e.pop("from", None)
+    if a.id_column:
+        e["key"] = a.id_column
+    if a.to:
+        e["to"] = a.to
+    if a.columns:
+        e["columns"] = _columns(a.columns)
+    if a.after_change:
+        e["when"] = "after_change"
+    elif a.every:
+        e["when"] = f"every {a.every}"
+    elif a.manual:
+        e["when"] = "manual"
+    if a.dish:
+        e["dish"] = a.dish
+    lacking = [f for f, k in (("--from <table> (or --sql)", "from" if "sql" not in e else "sql"), ("--key <id column>", "key"), ("--to <destination>", "to")) if not e.get(k)]
+    if lacking:
+        raise Fail(f"sync {a.name} needs " + ", ".join(lacking) + (" (nor is it in syncs.toml)" if root else ""))
+    dish = e.get("dish")
+    if e.get("from"):
+        d, _, source = e["from"].rpartition(".")
+        if d and dish and d != dish:
+            raise Fail(f"{e['from']} is not in the dish {dish}; a sync sends a table from its own dish")
+        dish = d or dish
+    else:
+        source = e["sql"]
+    dish = _dish(a, dish)
+    when = e.get("when") or "after_change"
+    if when in ("after_change", "manual"):
+        trigger, every = when, None
+    elif when.startswith("every ") and when.split(" ", 1)[1] in SYNC_EVERY:
+        trigger, every = "schedule", when.split(" ", 1)[1]
+    else:
+        raise Fail(f"when is after_change, manual, or every {'/'.join(SYNC_EVERY)}; syncs.toml has {when!r}")
+    cols = e.get("columns")
+    if isinstance(cols, list):
+        cols = {x: x for x in cols}
+    if not cols:   # every column but the key, as the source has them now
+        src = f"select * from {dish}.{source}" if e.get("from") else source
+        found = c.call("POST", "/query", json={"sql": f"select * from ({src}) limit 0", "dish": dish, "max_rows": 1})["columns"]
+        if e["key"] not in found:
+            raise Fail(f"the key column {e['key']} is not in {e.get('from') or 'the query'}; it has {', '.join(found)}")
+        cols = {x: x for x in found if x != e["key"]}
+    dest = _destination(c, e["to"])
+    body = {"dish": dish, "name": a.name, "source": source, "key": e["key"], "columns": cols, "trigger": trigger, "every": every}
+    ss = _all_syncs(c)
+    cur = next((s for s in ss if e.get("id") and s["id"] == e["id"]), None) or next((s for s in ss if s["name"] == a.name and s["dish"] == dish), None)
+    # What went is remembered by the rows' values, per sync. Another destination, or a column going to a field of another
+    # name, needs a sync that remembers nothing, or unchanged rows would never reach the new place: make the new one,
+    # then remove the old (in that order, so a refusal leaves the old one as it was).
+    fresh = bool(cur) and (cur["destination_id"] != dest["id"] or any(cur["columns"].get(k) not in (None, v) for k, v in cols.items()))
+    left = None
+    if cur and not fresh:
+        s = c.call("PUT", f"/syncs/{cur['id']}", json=body)
+    else:
+        s = c.call("POST", f"/destinations/{dest['id']}/syncs", json=body)
+        if fresh and not cur["enabled"]:
+            s = c.call("POST", f"/syncs/{s['id']}/enable", json={"on": False})
+    if root:
+        e["id"] = s["id"]
+        syncs[a.name] = e
+        _write_syncs(root, syncs)      # before the old one goes, so a retry finds the new one and makes no third
+    if fresh:
+        try:
+            c.call("DELETE", f"/syncs/{cur['id']}")
+        except Fail as x:
+            left = f"the old sync {cur['id']} is still there ({x}); remove it: ovs sync rm {cur['id']}"
+    what = f"{dish}.{source}" if e.get("from") else "the query"
+    fields = ", ".join(c_ if f == c_ else f"{c_} as {f}" for c_, f in s["columns"].items())
+    verb = ("made again (a new place or field: every row goes on the next send" + ("; still paused" if fresh and not cur["enabled"] else "") + ")"
+            if fresh else "updated" if cur else "added")
+    text = (f"{verb} sync {a.name} ({s['id']}): {what} to {dest['title']}, keyed by {s['key']}, "
+            f"columns {fields}, {_when_text(s)}" + ("; written to syncs.toml" if root else "")
+            + f"\nonly rows that changed since they last went are sent. To send now: ovs sync run {a.name}"
+            + (f"\nwarning: {left}" if left else ""))
+    return {"sync": s, "updated": bool(cur) and not fresh, "made_again": fresh, **({"warning": left} if left else {})}, text
+
+
+def _sync_cmd(a, c: Client):
+    if a.sub == "list":
+        return _syncs(a, c)
+    if a.sub == "add":
+        return _sync_add(a, c)
+    s = _sync_ref(a, c, a.name)
+    if a.sub == "run":
+        try:
+            d = c.call("POST", f"/syncs/{s['id']}/run", headers={"x-overscore-trigger": "cli"}, timeout=3600)
+        except Fail as e:
+            if e.status != 400 or "rows were refused" not in str(e):
+                raise
+            shown = c.call("GET", f"/syncs/{s['id']}")
+            raise Fail(f"{e} (ovs sync show {s['name']} lists what was refused; they go again next run)", 400,
+                       data={"sync": s["id"], "refused": shown["failures"][:20]}) from None
+        text = f"{s['name']} to {s['to']}: sent {d['sent']:,} rows" + (f", {d['failed']:,} refused (ovs sync show {s['name']} says why)" if d.get("failed") else "")
+        return d, text + f" (run {d.get('run_id')})"
+    if a.sub == "show":
+        d = c.call("GET", f"/syncs/{s['id']}")
+        me = d["sync"]
+        every = c.call("GET", "/runs", params={"kind": "sync", "dish": me["dish"], "limit": 500})["runs"]
+        runs = [r for r in every if r.get("name") == f"{me['name']} to {s['to']}"][:10]
+        text = (f"{me['name']} ({me['id']}): {me['dish']}.{me['source'] if len(me['source']) < 60 else 'query'} to {s['to']}, keyed by {me['key']}, "
+                f"{_when_text(me)}, {'on' if me['enabled'] else 'paused'}; {me.get('sent_total') or 0:,} rows sent in all\n")
+        text += "runs:\n" + (_table([{"id": r["id"], "status": r["status"], "when": _when(r.get("started_at")), "rows": r.get("rows"), "error": (r.get("error") or "")[:70]} for r in runs],
+                                    ["id", "status", "when", "rows", "error"]) if runs else "(none yet)")
+        if d["failures"]:
+            text += "\nrefused (they go again next run):\n" + _table([{"key": f["key"], "when": _when(f["at"]), "reason": f["reason"][:90]} for f in d["failures"][:20]], ["key", "when", "reason"])
+        return {**d, "runs": runs}, text
+    if a.sub in ("pause", "resume"):
+        d = c.call("POST", f"/syncs/{s['id']}/enable", json={"on": a.sub == "resume"})
+        return d, f"{s['name']}: {'paused' if a.sub == 'pause' else 'on again'}"
+    if a.sub == "rm":
+        root = _project(a, False)
+        syncs = _read_syncs(root)
+        d = c.call("DELETE", f"/syncs/{s['id']}")
+        if root and s["name"] in syncs and syncs[s["name"]].get("id") in (None, s["id"]):
+            del syncs[s["name"]]
+            _write_syncs(root, syncs)
+        return d, f"removed {s['name']}" + (" (and its entry in syncs.toml)" if root else "")
+    raise Fail(f"unknown sync command {a.sub}")
+
+
+# --- ovs login: the key in this computer's keychain, the address beside it (CLI_LOGIN_PLAN.md) --------------
+#
+# The laptop asks the front desk for a code, the person approves it in the browser, and the laptop collects a key of
+# its own and its Overscore's address (https://<customer>.overscore.tech). The key goes in the OS keychain (the
+# keyring library: macOS Keychain, Windows Credential Locker, the Secret Service on Linux); the address, who and
+# which laptop go in ~/.config/overscore/login.json. No key is ever written to a file.
+
+KEYCHAIN = "overscore"
+
+
+def _login_file() -> pathlib.Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or os.path.join(os.path.expanduser("~"), ".config")
+    return pathlib.Path(base) / "overscore" / "login.json"
+
+
+def _saved_login() -> dict:
+    try:
+        return json.loads(_login_file().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def _keychain():
+    try:
+        import keyring
+    except ImportError:
+        raise Fail("this ovs cannot reach a keychain (the keyring library is missing); reinstall overscore-cli, or export OVERSCORE_KEY")
+    return keyring
+
+
+def _saved_key(address: str) -> str | None:
+    try:
+        return _keychain().get_password(KEYCHAIN, address.rstrip("/"))
+    except Exception:  # noqa: BLE001  (no keychain on this machine: then there is no saved key)
+        return None
+
+
+def _device_id() -> str:
+    """This computer's own random id (not a secret), kept beside the login so logging in again replaces its key."""
+    f = _login_file().with_name("device")
+    try:
+        d = f.read_text(encoding="utf-8").strip()
+        if d:
+            return d
+    except OSError:
+        pass
+    import secrets as _s
+    d = _s.token_hex(8)
+    f.parent.mkdir(parents=True, exist_ok=True)
+    f.write_text(d, encoding="utf-8")
+    return d
+
+
+def _open_browser(url: str) -> None:
+    try:
+        import webbrowser
+        webbrowser.open(url)
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def _login(a, c):
+    import socket
+    front = _check_address((getattr(a, "url_given", None) or DEFAULT_URL).rstrip("/"), given=bool(getattr(a, "url_given", None)))
+    kc = _keychain()
+    try:                                   # the keychain must take a key before a key is asked for
+        kc.set_password(KEYCHAIN, "overscore-probe", "probe")
+        kc.delete_password(KEYCHAIN, "overscore-probe")
+    except Exception as e:  # noqa: BLE001
+        raise Fail(f"this computer's keychain would not keep a key ({type(e).__name__}), so ovs login cannot work here. "
+                   "Make a key on the Agents screen instead and export OVERSCORE_KEY=ovs_... in the shell") from None
+    desk = Client(front, None)
+    st = desk.call("POST", "/cli/login/start", json={"machine": socket.gethostname(), "device_id": _device_id()})
+    say = f"Open {st['url']} and type the code {st['code']}, then approve. Waiting..."
+    print(say, file=sys.stderr, flush=True)
+    if not getattr(a, "echo", True):       # an agent reading JSON sees it too, before the wait
+        print(json.dumps({"status": "waiting", "url": st["url"], "code": st["code"], "say": "ask the person to open the page and type the code"}), flush=True)
+    if not getattr(a, "no_browser", False):
+        _open_browser(st["url"])
+    deadline = time.time() + st.get("expires_in", 600) + 30
+    wait = st.get("interval", 2)
+    while time.time() < deadline:
+        time.sleep(wait)
+        try:
+            r = desk.call("POST", "/cli/login/poll", json={"device": st["device"]})
+        except Fail as e:                  # a blip (a redeploy, a busy office network): keep asking, a little slower
+            if e.status is not None and e.status < 500 and e.status != 429:
+                raise
+            wait = min(wait * 2, 15)
+            continue
+        wait = st.get("interval", 2)
+        if r["status"] == "approved":
+            address = r["address"].rstrip("/")
+            try:
+                kc.set_password(KEYCHAIN, address, r["key"])
+            except Exception as e:  # noqa: BLE001  (the key was handed over once: turn it off rather than lose it)
+                try:
+                    Client(address, r["key"]).call("POST", "/cli/logout")
+                except Fail:
+                    pass
+                raise Fail(f"the keychain refused the key ({type(e).__name__}); it has been turned off. Unlock the keychain and run ovs login again") from None
+            f = _login_file()
+            f.parent.mkdir(parents=True, exist_ok=True)
+            f.write_text(json.dumps({"address": address, "customer": r.get("customer"), "email": r.get("email"),
+                                     "machine": r.get("machine"), "at": time.time()}, indent=1), encoding="utf-8")
+            out = {"logged_in": True, "address": address, "customer": r.get("customer"), "email": r.get("email")}
+            return out, (f"logged in as {r.get('email')} to {r.get('customer')} ({address}); the key is in this computer's keychain.\n"
+                         f"next: ovs init --dish <dish> in a project folder (ovs tables lists what you can reach)")
+        if r["status"] in ("cancelled", "expired"):
+            raise Fail(f"the login was {r['status']}; run ovs login again")
+    raise Fail("nobody approved the login in ten minutes; run ovs login again")
+
+
+def _logout(a, c):
+    saved = _saved_login()
+    toml = _config(_project(a, False)).get("url")
+    address = (getattr(a, "url_given", None) or (toml if toml and toml != DEFAULT_URL else None) or saved.get("address") or DEFAULT_URL).rstrip("/")
+    key = _saved_key(address)
+    revoked = 0
+    if key:
+        try:
+            revoked = Client(address, key).call("POST", "/cli/logout").get("revoked", 0)
+        except Fail as e:
+            print(f"(could not turn the key off in Overscore: {e}; it ends by itself after 90 days unused, or on the Agents screen)", file=sys.stderr)
+        try:
+            _keychain().delete_password(KEYCHAIN, address)
+        except Exception:  # noqa: BLE001
+            pass
+    if (saved.get("address") or "").rstrip("/") == address:
+        _login_file().unlink(missing_ok=True)
+    return {"logged_out": True, "address": address, "revoked": revoked}, (
+        f"logged out of {address}" + ("; the key is off" if revoked else "") if key or saved else "not logged in here")
+
+
+# --- init: the project folder, and the rules and skills rendered for the agent that will work in it (SKILLS_PLAN.md) ---
+
+def _skills_root() -> pathlib.Path:
+    here = pathlib.Path(__file__).resolve().parent
+    for d in (here / "skills", here.parent / "skills"):      # inside the package, or the repo's skills/ beside overscore/
+        if all((d / n / "SKILL.md").is_file() for n in SHIPPED_SKILLS):
+            return d
+    raise Fail("the skills are missing from this install of ovs; reinstall overscore-cli")
+
+
+def _frontmatter(text: str) -> tuple[dict, str]:
+    if text.startswith("---\n"):
+        end = text.find("\n---", 4)
+        if end != -1:
+            meta = {}
+            for line in text[4:end].splitlines():
+                k, sep, v = line.partition(":")
+                if sep:
+                    v = v.strip()
+                    meta[k.strip()] = json.loads(v) if v.startswith('"') else v
+            return meta, text[end + 4:].lstrip("\n")
+    return {}, text
+
+
+def _skill(name: str) -> dict:
+    d = _skills_root() / name
+    meta, body = _frontmatter((d / "SKILL.md").read_text(encoding="utf-8"))
+    extras = {p.name: p.read_text(encoding="utf-8") for p in sorted(d.iterdir()) if p.is_file() and p.name != "SKILL.md" and not p.name.startswith(".")}
+    return {"name": name, "description": meta.get("description", ""), "body": body, "extras": extras, "dir": d}
+
+
+def _demote(md: str, by: int) -> str:
+    """Push every heading down `by` levels, leaving code blocks alone."""
+    out, fenced = [], False
+    for line in md.splitlines():
+        if line.startswith("```"):
+            fenced = not fenced
+        out.append("#" * by + line if not fenced and re.match(r"#{1,6} ", line) else line)
+    return "\n".join(out)
+
+
+def _with_extras(s: dict) -> str:
+    """The skill's body with its templates written out, for layouts that hold one file per skill."""
+    parts = [s["body"].rstrip()]
+    for fname, content in s["extras"].items():
+        lang = "python" if fname.endswith(".py") else "toml" if fname.endswith(".toml") else ""
+        parts.append(f"### {fname} (template)\n\n```{lang}\n{content.rstrip()}\n```")
+    return "\n\n".join(parts)
+
+
+RULES = """# Overscore
+
+This folder builds things that run on Overscore: Python models that score or reshape a company's data, and syncs that send the results to the systems people work in. The `ovs` command does all of it (`ovs guide` lists every command). {where}
+
+## The folder
+- `overscore.toml`: the Overscore address and the dish (the dataset) this project works in. Never the key.
+- `models/<name>/model.py` and `model.toml`: one Python model per folder. The folder's name is the model's name and the name of the table it builds.
+- `files/<name>.<ext>`: local copies of the files a model needs (a fitted model, a lookup). `ovs upload put <name> files/<name>.<ext>` sends one to Overscore.
+- `syncs.toml`: what goes where, written by `ovs sync add`.
+- `.overscore/`: pulled samples, local outputs, environments. It is the company's data: never commit it, never paste it into a message.
+
+## Rules
+- Tables are `dish.table`; a model's output is `dish.model`. Names are lowercase letters, digits and underscores.
+- `ovs login` keeps this computer's key in its keychain (`OVERSCORE_KEY` in the environment works too). A key never goes in a file, a commit or a message.
+- Run a model here (`ovs model run <name> --local`) before pushing it. Call `output()` once. The script gets no network in Overscore, and only model.py goes up: keep the model in that one file.
+- List every library the script imports in model.toml `requirements`; both this machine and Overscore build the environment from it.
+- After `ovs model push`, read the run's result and log before saying it worked. A run is the receipt.
+- Don't write to `sent`, `control` or any schema that is Overscore's own.
+- Say what changed in the words of the business, not the column names.
+- Every `ovs` command prints JSON when its output is not a terminal: `{"success": true, ...}`, or `{"success": false, "error": "..."}` with exit code 1. The error says what to do next."""
+
+WHERE = {
+    "claude": "The steps for each job are skills in `.claude/skills/`: `overscore` (start here), `overscore-model` (build and deploy a Python model), `overscore-sync` (send a table to another system).",
+    "cursor": "The steps for each job are rules in `.cursor/rules/`: `overscore` (start here), `overscore-model` (build and deploy a Python model), `overscore-sync` (send a table to another system).",
+    "inline": "The steps for each job follow below: Overscore itself (start here), building and deploying a Python model, and sending a table to another system.",
+}
+
+
+def _block(path: pathlib.Path, body: str) -> None:
+    """Write our block into a rules file: replace it if there, append it if not, and leave the rest alone."""
+    block = f"{BLOCK_START}\n{body.rstrip()}\n{BLOCK_END}\n"
+    text = path.read_text(encoding="utf-8") if path.is_file() else ""
+    i = text.find(BLOCK_OPEN)
+    if i != -1:
+        j = text.find(BLOCK_END, i)
+        if j == -1:
+            raise Fail(f"{path.name} has the start of the Overscore block but not its end ({BLOCK_END}); put the end back, or delete the start line")
+        text = text[:i] + block + text[j + len(BLOCK_END):].lstrip("\n")
+    else:
+        text = (text.rstrip() + "\n\n" if text.strip() else "") + block
+    path.write_text(text, encoding="utf-8")
+
+
+def _render(root: pathlib.Path, target: str) -> list[str]:
+    """The one source (skills/) in one agent's layout. Returns what was written, relative to root."""
+    skills = [_skill(n) for n in SHIPPED_SKILLS]
+    written = []
+    if target == "claude":
+        _block(root / "CLAUDE.md", RULES.replace("{where}", WHERE["claude"]))
+        written.append("CLAUDE.md")
+        for s in skills:
+            dest = root / ".claude" / "skills" / s["name"]
+            # the shipped files are refreshed; anything else a team put in the folder stays
+            shutil.copytree(s["dir"], dest, dirs_exist_ok=True, ignore=shutil.ignore_patterns("__pycache__", ".*", "*.pyc"))
+            text = (dest / "SKILL.md").read_text(encoding="utf-8")
+            head, sep, body = text.partition("\n---\n")       # the notice goes under the frontmatter
+            (dest / "SKILL.md").write_text(head + sep + REWRITTEN + "\n\n" + body.lstrip("\n"), encoding="utf-8")
+            written.append(f".claude/skills/{s['name']}/")
+    elif target in ("codex", "agents", "gemini"):
+        name = "GEMINI.md" if target == "gemini" else "AGENTS.md"
+        inline = "\n\n".join(f"## {s['name']}\n\n_{s['description']}_\n\n" + _demote(_with_extras(s), 2) for s in skills)
+        _block(root / name, RULES.replace("{where}", WHERE["inline"]) + "\n\n" + inline)
+        written.append(name)
+    elif target == "cursor":
+        rules = root / ".cursor" / "rules"
+        rules.mkdir(parents=True, exist_ok=True)
+        (rules / "overscore-rules.mdc").write_text("---\ndescription: How this project works with Overscore; always on.\nglobs:\nalwaysApply: true\n---\n\n"
+                                                   + REWRITTEN + "\n\n" + RULES.replace("{where}", WHERE["cursor"]) + "\n", encoding="utf-8")
+        written.append(".cursor/rules/overscore-rules.mdc")
+        for s in skills:
+            (rules / f"{s['name']}.mdc").write_text(f"---\ndescription: {json.dumps(s['description'], ensure_ascii=False)}\nglobs:\nalwaysApply: false\n---\n\n"
+                                                   + REWRITTEN + "\n\n" + _with_extras(s) + "\n", encoding="utf-8")
+            written.append(f".cursor/rules/{s['name']}.mdc")
+    return written
+
+
+def _init(a, c: Client | None):
+    root = pathlib.Path(a.path or ".").resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    cur = _config(root)
+    url = getattr(a, "url_given", None) or (cur.get("url") if cur.get("url") != DEFAULT_URL else None) or _saved_login().get("address") or DEFAULT_URL
+    dish, seen, check = a.dish or cur.get("dish"), None, None
+    if c is not None:
+        c.url = url.rstrip("/")
+        try:
+            c.url = _check_address(c.url, given=bool(getattr(a, "url_given", None)) or c.url == (_saved_login().get("address") or "").rstrip("/"))
+            seen = c.call("GET", "/whoami")
+        except Fail as e:
+            check = f"did not check the key against {url}: {e}"
+    if not dish:
+        scopes = (seen or {}).get("scopes") or {}
+        hot = sorted(d for d, v in scopes.items() if d != "*" and (v == "hot" or (isinstance(v, dict) and v.get("level") == "hot")))
+        if len(hot) != 1:
+            reach = "the key reaches every dish" if "*" in scopes else f"the key writes to: {', '.join(hot)}" if hot else ""
+            raise Fail("which dish does this project work in? ovs init --dish <dish>" + (f" ({reach}; ovs tables lists them)" if reach else ""))
+        dish = hot[0]
+    _name(dish, "dish")
+    targets = ["claude", "agents", "cursor", "gemini"] if a.agent == "all" else [a.agent or "claude"]
+    (root / PROJECT_FILE).write_text("# This folder is an Overscore project; ovs reads the address and the dish from here.\n"
+                                     "# The key is never written here: ovs login keeps it in the keychain.\n"
+                                     + (f"url = {_toml_value(url)}\n" if url != DEFAULT_URL else "# url: the address ovs login gives, when there is one\n")
+                                     + f"dish = {_toml_value(dish)}\n", encoding="utf-8")
+    for d in ("models", "files"):
+        (root / d).mkdir(exist_ok=True)
+    if not (root / "syncs.toml").exists():
+        _write_syncs(root, {})
+    gi = root / ".gitignore"
+    lines = gi.read_text(encoding="utf-8").splitlines() if gi.is_file() else []
+    if not any(l.strip().rstrip("/") in (LOCAL, "/" + LOCAL) for l in lines):
+        gi.write_text("\n".join([*lines, "# pulled samples and local outputs: the company's data", LOCAL + "/"]) + "\n", encoding="utf-8")
+    written = [PROJECT_FILE, "models/", "files/", "syncs.toml", ".gitignore"]
+    for t in dict.fromkeys("agents" if t == "codex" else t for t in targets):
+        written += _render(root, t)
+    if seen is not None:
+        level = (seen.get("scopes") or {}).get(dish) or (seen.get("scopes") or {}).get("*")
+        level = level.get("level") if isinstance(level, dict) else level
+        check = f"the key ({seen.get('hand')}) reaches {dish} at level {level}" if level else f"the key ({seen.get('hand')}) does not reach {dish}; ovs whoami lists what it does reach"
+    elif check is None:
+        check = "not logged in yet: run ovs login (or export OVERSCORE_KEY=ovs_...), then ovs whoami"
+    out = {"project": str(root), "url": url, "dish": dish, "for": targets, "written": written, "key": check}
+    return out, (f"{root}: an Overscore project on {url}, dish {dish}\nwrote {', '.join(written)}\n{check}\n"
+                 f"next: ovs pull {dish}.<table>, then write models/<name>/model.py and model.toml (the overscore-model skill has the steps)")
+
+
+LAPTOP = {"login": _login, "logout": _logout, "init": _init, "pull": _pull, "model": _model_cmd, "uploads": _uploads, "upload": _upload,
+          "destinations": _destinations, "destination": _destination_cmd, "syncs": _syncs, "sync": _sync_cmd}
+
+
+class _Parser(argparse.ArgumentParser):
+    """A usage mistake is a failure like any other: JSON for an agent, exit 1."""
+    def error(self, message):
+        raise Fail(f"{self.prog}: {message}", data={"usage": self.format_usage().strip()})
+
+
+def _version_number(v: str) -> int:
+    try:
+        return int(v.strip().lstrip("vV"))
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"a version is a number, like 3 or v3: {v!r}") from None
+
+
+def _check_address(url: str, *, given: bool) -> str:
+    """Where the key may go. Only over https (localhost aside), and to an address a project file names only when it
+    is Overscore's own: a cloned repo's overscore.toml must not be able to send the key somewhere else.
+    Returns the address rebuilt from what was checked, so the request goes where the check looked."""
+    from urllib.parse import urlparse
+    u = urlparse(url.strip())
+    if not u.netloc or any(ch in u.netloc for ch in "\\@ \t") or u.query or u.fragment or "\\" in u.path:
+        raise Fail(f"{url!r} is not a plain address like https://app.overscore.tech")
+    try:
+        port = u.port
+    except ValueError:
+        raise Fail(f"{url!r} has a port that is not a number") from None
+    host = (u.hostname or "").lower()
+    local = host in ("localhost", "127.0.0.1", "::1")
+    if u.scheme != "https" and not (u.scheme == "http" and local):
+        raise Fail(f"the key only goes over https (or to localhost); {url} is not")
+    if not given and not local and host != "overscore.tech" and not host.endswith(".overscore.tech"):
+        raise Fail(f"overscore.toml says to send the key to {url}, which is not an Overscore address. "
+                   f"If it is yours, say so for this shell: export OVERSCORE_URL={url}")
+    return f"{u.scheme}://{host if ':' not in host else '[' + host + ']'}{f':{port}' if port else ''}{u.path.rstrip('/')}"
+
+
+def _version() -> str:
+    try:
+        from importlib.metadata import version
+        return version("overscore-cli")
+    except Exception:  # noqa: BLE001
+        return "dev"
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = _Parser(prog="ovs", description="Overscore command line")
+    p.add_argument("--url", default=None, help=f"default: OVERSCORE_URL, else the url in overscore.toml, else {DEFAULT_URL}")
+    p.add_argument("--key", default=os.environ.get("OVERSCORE_KEY"))
+    p.add_argument("-o", "--output", choices=["json", "text"], default=None, help="default: text on a terminal, json otherwise")
+    p.add_argument("--version", action="version", version=f"ovs {_version()}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("guide"); sub.add_parser("whoami"); sub.add_parser("tables"); sub.add_parser("index")
+    x = sub.add_parser("describe"); x.add_argument("dish"); x.add_argument("table")
+    x = sub.add_parser("search"); x.add_argument("text")
+    x = sub.add_parser("query"); x.add_argument("sql", nargs="?"); x.add_argument("--max-rows", type=int, default=200)
+    x = sub.add_parser("insert"); x.add_argument("dish"); x.add_argument("table"); x.add_argument("file", help="json file, or - for stdin")
+    x = sub.add_parser("load"); x.add_argument("dish"); x.add_argument("table"); x.add_argument("file"); x.add_argument("--tab"); x.add_argument("--skip", type=int)
+    x = sub.add_parser("notes"); x.add_argument("dish")
+    x = sub.add_parser("note"); x.add_argument("dish"); x.add_argument("name"); x.add_argument("body", nargs="?"); x.add_argument("--title")
+    x = sub.add_parser("models"); x.add_argument("dish")
+    x = sub.add_parser("run"); x.add_argument("dish"); x.add_argument("--only", nargs="*")
+    x = sub.add_parser("test"); x.add_argument("dish")
+    x = sub.add_parser("signoff"); x.add_argument("dish"); x.add_argument("table"); x.add_argument("description", nargs="?"); x.add_argument("--off", action="store_true")
+    x = sub.add_parser("runs"); x.add_argument("-n", type=int, default=20)
+    x = sub.add_parser("run-log"); x.add_argument("id", type=int)
+    x = sub.add_parser("export"); x.add_argument("dish"); x.add_argument("name"); x.add_argument("sql"); x.add_argument("--format", default="csv")
+    sub.add_parser("connectors")
+    x = sub.add_parser("how"); x.add_argument("name", help="stripe, shopify, quickbooks, postgres")
+    x = sub.add_parser("connect"); x.add_argument("name"); x.add_argument("secrets", nargs="*", help="key=value, see ovs connectors")
+    x.add_argument("--dish"); x.add_argument("--only", nargs="*"); x.add_argument("--no-run", action="store_true")
+    x = sub.add_parser("link"); x.add_argument("dish"); x.add_argument("dsn"); x.add_argument("--copy", action="store_true")
+    x.add_argument("--tables", nargs="*"); x.add_argument("--schema", default="public"); x.add_argument("--every", default="every 60m")
+    sub.add_parser("links")
+    x = sub.add_parser("hook"); x.add_argument("dish"); x.add_argument("table"); x.add_argument("--provider"); x.add_argument("--secret")
+    sub.add_parser("hooks")
+    x = sub.add_parser("context"); x.add_argument("q")
+    x = sub.add_parser("propose"); x.add_argument("text"); x.add_argument("--source", default="cli")
+    x = sub.add_parser("cards"); x.add_argument("--status", default="waiting")
+    x = sub.add_parser("approve"); x.add_argument("id"); x.add_argument("--target"); x.add_argument("--key", dest="card_key"); x.add_argument("--set", nargs="*", help="column=value")
+    x = sub.add_parser("ignore"); x.add_argument("id")
+    x = sub.add_parser("facts"); x.add_argument("table")
+    x = sub.add_parser("interview"); x.add_argument("area", nargs="?"); x.add_argument("--person"); x.add_argument("--resume")
+    sub.add_parser("map")
+    sub.add_parser("plan")
+    x = sub.add_parser("fields"); x.add_argument("dish"); x.add_argument("table")
+    x = sub.add_parser("field"); x.add_argument("dish"); x.add_argument("table"); x.add_argument("name"); x.add_argument("type"); x.add_argument("description"); x.add_argument("--allowed", nargs="*")
+    x = sub.add_parser("mark"); x.add_argument("dish"); x.add_argument("table"); x.add_argument("keys", help="id, or id,id,id, or - for the table itself"); x.add_argument("values", nargs="+", help="field=value")
+    x = sub.add_parser("marks"); x.add_argument("dish"); x.add_argument("table"); x.add_argument("row_key", nargs="?", metavar="key")
+    x = sub.add_parser("claim"); x.add_argument("code", help="the claim code from the trial conversation")
+    x = sub.add_parser("research"); x.add_argument("site")
+    x = sub.add_parser("issues"); x.add_argument("--sweep", action="store_true")
+    x = sub.add_parser("fix"); x.add_argument("id")
+    x = sub.add_parser("hook-log"); x.add_argument("token"); x.add_argument("-n", type=int, default=20)
+    x = sub.add_parser("unhook"); x.add_argument("token")
+    x = sub.add_parser("copy"); x.add_argument("dish")
+    x = sub.add_parser("unlink"); x.add_argument("dish")
+    # the laptop side (CLAUDE_CODE_PLAN.md)
+    x = sub.add_parser("login", help="approve this computer in the browser; the key goes in the keychain"); x.add_argument("--no-browser", action="store_true")
+    sub.add_parser("logout", help="turn this computer's key off and forget it")
+    x = sub.add_parser("init", help="make this folder an Overscore project"); x.add_argument("path", nargs="?", default=".")
+    x.add_argument("--dish"); x.add_argument("--for", dest="agent", choices=AGENTS, default="claude", help="which agent's layout the rules and skills are written in")
+    x = sub.add_parser("pull", help="a sample of a table as Parquet into .overscore/data/"); x.add_argument("tables", nargs="+", help="dish.table")
+    x.add_argument("--rows", type=int, default=PULL_MAX); x.add_argument("--where", help="a SQL condition, to pull the rows that matter"); x.add_argument("--dish")
+    m = sub.add_parser("model", help="a Python model in models/<name>/").add_subparsers(dest="sub", required=True)
+    x = m.add_parser("push"); x.add_argument("name"); x.add_argument("--dish"); x.add_argument("--no-run", action="store_true")
+    x = m.add_parser("run"); x.add_argument("name"); x.add_argument("--dish"); x.add_argument("--local", action="store_true", help="here, on the pulled samples")
+    x.add_argument("--python", help="the interpreter for a local run (default: one built from requirements, else python3)")
+    x = m.add_parser("log"); x.add_argument("name"); x.add_argument("--dish")
+    sub.add_parser("uploads")
+    u = sub.add_parser("upload", help="files a model needs, versioned").add_subparsers(dest="sub", required=True)
+    u.add_parser("list")
+    x = u.add_parser("put"); x.add_argument("name"); x.add_argument("file"); x.add_argument("--note")
+    x = u.add_parser("live"); x.add_argument("name"); x.add_argument("version", type=_version_number, help="3, or v3")
+    x = u.add_parser("rm"); x.add_argument("name")
+    sub.add_parser("destinations")
+    d = sub.add_parser("destination", help="where data goes").add_subparsers(dest="sub", required=True)
+    d.add_parser("list")
+    x = d.add_parser("add"); x.add_argument("kind", choices=["webhook", "hubspot"]); x.add_argument("title"); x.add_argument("webhook_url", nargs="?", metavar="url", help="webhook: their https:// URL")
+    x.add_argument("--object", default="contacts", choices=["contacts", "companies", "deals", "tickets"]); x.add_argument("--id-property", help="hubspot: a unique property to match on (default: HubSpot's record id)")
+    x.add_argument("--source", help="hubspot: the HubSpot source whose key to use, dish.name"); x.add_argument("--token", help="hubspot: - to read a key from stdin")
+    for verb in ("check", "rm"):
+        x = d.add_parser(verb); x.add_argument("dest", help="its name or id")
+    sub.add_parser("syncs")
+    s = sub.add_parser("sync", help="a table sent to a destination").add_subparsers(dest="sub", required=True)
+    s.add_parser("list")
+    x = s.add_parser("add"); x.add_argument("name"); x.add_argument("--from", dest="source", help="a table in the dish"); x.add_argument("--sql", help="a query, in place of --from")
+    x.add_argument("--key", dest="id_column", help="the column that identifies the record"); x.add_argument("--to", help="the destination's name or id")
+    x.add_argument("--columns", nargs="+", help="column or column=field; default every column but the key"); x.add_argument("--dish")
+    g = x.add_mutually_exclusive_group(); g.add_argument("--after-change", action="store_true"); g.add_argument("--every", choices=SYNC_EVERY); g.add_argument("--manual", action="store_true")
+    for verb in ("run", "show", "pause", "resume", "rm"):
+        x = s.add_parser(verb); x.add_argument("name"); x.add_argument("--dish")
+    # Accept -o / --url / --key anywhere on the line, not only before the command. Two commands have a --key of their
+    # own (the id column of `sync add`, the row of `approve`): there it is theirs.
+    argv = list(sys.argv[1:] if argv is None else argv)
+    front, rest, i, words = [], [], 0, []
+    while i < len(argv):
+        t = argv[i]
+        flag = t.split("=", 1)[0]
+        theirs = flag == "--key" and (words[:2] == ["sync", "add"] or words[:1] == ["approve"])
+        if flag in ("-o", "--output", "--url", "--key") and not theirs and ("=" in t or i + 1 < len(argv)):
+            n = 1 if "=" in t else 2
+            front += argv[i:i + n]; i += n
+        else:
+            if not t.startswith("-"):
+                words.append(t)
+            rest.append(t); i += 1
+    wants = next((front[k + 1] for k in range(len(front) - 1) if front[k] in ("-o", "--output")), None) \
+        or next((f.split("=", 1)[1] for f in front if f.startswith("--output=")), None)
+    as_json = wants == "json" or (wants != "text" and not sys.stdout.isatty())
+    try:
+        a = p.parse_args(front + rest)
+        as_json = a.output == "json" or (a.output is None and not sys.stdout.isatty())
+        a.echo = not as_json
+        a.url_given = a.url or os.environ.get("OVERSCORE_URL")
+        a.project = _find_project()
+        saved = _saved_login().get("address", "").rstrip("/")
+        toml = _config(a.project).get("url")
+        url = (a.url_given or (toml if toml and toml.rstrip("/") != DEFAULT_URL else None) or saved or DEFAULT_URL).rstrip("/")
+        if not a.key and a.cmd not in ("login", "logout"):
+            a.key = _saved_key(url)          # the key ovs login kept for this address, if any
+        keyless = a.cmd in ("guide", "init", "login", "logout") or (a.cmd == "model" and a.sub == "run" and a.local)
+        if not a.key and not keyless:
+            raise Fail("not logged in: run ovs login (or export OVERSCORE_KEY=ovs_..., never written into a file)")
+        talks = a.key and a.cmd not in ("guide", "login", "logout") and not (a.cmd == "model" and a.sub == "run" and a.local)
+        if talks and a.cmd != "init":        # init checks the address it will write
+            url = _check_address(url, given=bool(a.url_given) or (bool(saved) and url == saved))
+        data, text = run(a, Client(url, a.key) if talks else None)
+    except Fail as e:
+        err = {"success": False, "error": str(e), "status": e.status, **e.data}
+        if as_json:
+            print(json.dumps(err, default=str))
+        else:
+            if e.data.get("saved"):
+                print(f"saved {e.data.get('model')}")
+            for n in e.data.get("notes") or []:
+                print(f"note: {n}")
+            log = e.data.get("log")
+            if isinstance(log, str) and log:
+                print((f"run {e.data['run_id']}:\n" if e.data.get("run_id") else "") + log.rstrip())
+            elif log and e.data.get("where") != "local":     # a local run's log was shown as it came
+                print("\n".join("  " + l for l in log))
+            for l in e.data.get("stderr") or []:
+                print("  " + l)
+            if e.data.get("usage"):
+                print(e.data["usage"])
+            print(f"error: {e}" + (f" (HTTP {e.status})" if e.status else ""))
+        return 1
+    if as_json:
+        out = data if isinstance(data, dict) else {"result": data}
+        print(json.dumps({"success": True, **out}, default=str))
+    else:
+        print(text)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())