morphdb 0.1.1__tar.gz → 0.1.2__tar.gz

{morphdb-0.1.1 → morphdb-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: morphdb
-Version: 0.1.1
+Version: 0.1.2
 Summary: A coding-agent-friendly, multi-tenant backend for vibe-coded websites. One process hosts many isolated apps; reshape each app's schema as fast as your agent iterates while the frontend keeps calling the same generic endpoints.
 Author: morphdb contributors
 License: MIT
@@ -120,31 +120,42 @@ curl -X PATCH $BASE/objects/user/<u> -d '{"tasks":["<t1>","<t2>"]}'
 - **Query layer**: filter operators, sorting, pagination — all generic.
 - **Multi-tenant by app** — one process backs many isolated sites; every call is scoped by an `X-App-Key`, and deleting an app cascades away all its data.
 - **Wide-open CORS** so any frontend origin can call it in dev.
-- **A Claude Code skill** (`skill/SKILL.md`) with a schema CLI so the agent edits the model without hand-writing curl.
+- **A management CLI** — `morphdb start/status/stop`, a read-only admin dashboard, and one-command skill install.
+- **A Claude Code skill** (`morphdb/skill/SKILL.md`, install with `morphdb install-skill`) with a schema CLI so the agent edits the model without hand-writing curl.
 
 > Scope: a localhost-scale developer tool. Not built for multi-tenant auth,
 > horizontal scale, or production durability guarantees.
 
 ## Install / run
 
-No install required:
-
 ```bash
-python3 -m morphdb --port 8787 --db ./app.sqlite3
+pip install morphdb
 ```
 
-Or install the console script:
+Manage the local server with the `morphdb` CLI:
 
 ```bash
-pip install -e .
-morphdb --port 8787 --db ./app.sqlite3
+morphdb start          # run in the background (default 127.0.0.1:8787)
+morphdb status         # running? where? how many apps?
+morphdb stop           # stop it
+morphdb run            # run in the foreground instead (blocking)
+morphdb dashboard      # read-only web view of every app + its tables
+morphdb install-skill  # install the MorphDB Claude Code skill (into ~/.claude)
 ```
 
-Flags: `--host` (default `127.0.0.1`), `--port` (default `8787`),
-`--db` (default `morphdb.sqlite3`; use `:memory:` for ephemeral).
+Data lives in `~/.morphdb/data.sqlite3` (change it with `--db PATH` or
+`--db :memory:`; move the state dir with `$MORPHDB_HOME`). Server flags:
+`--host`, `--port`, `--db`. From a source checkout with no install, the
+foreground server is `python3 -m morphdb --port 8787 --db ./app.sqlite3`.
 
 Then: `curl http://127.0.0.1:8787/help` for a live reference.
 
+**Pointing clients at a hosted MorphDB.** Set `MORPHDB_HOST` to a full URL (e.g.
+`https://db.example.com`) and the schema CLI — plus any frontend that reads
+`window.MORPHDB_HOST` — calls that hosted server (running this same code) instead
+of localhost. It's a client-side setting that names a *backend*, not a database
+connection string.
+
 ## Quickstart
 
 ```bash

{morphdb-0.1.1 → morphdb-0.1.2}/README.md

@@ -93,31 +93,42 @@ curl -X PATCH $BASE/objects/user/<u> -d '{"tasks":["<t1>","<t2>"]}'
 - **Query layer**: filter operators, sorting, pagination — all generic.
 - **Multi-tenant by app** — one process backs many isolated sites; every call is scoped by an `X-App-Key`, and deleting an app cascades away all its data.
 - **Wide-open CORS** so any frontend origin can call it in dev.
-- **A Claude Code skill** (`skill/SKILL.md`) with a schema CLI so the agent edits the model without hand-writing curl.
+- **A management CLI** — `morphdb start/status/stop`, a read-only admin dashboard, and one-command skill install.
+- **A Claude Code skill** (`morphdb/skill/SKILL.md`, install with `morphdb install-skill`) with a schema CLI so the agent edits the model without hand-writing curl.
 
 > Scope: a localhost-scale developer tool. Not built for multi-tenant auth,
 > horizontal scale, or production durability guarantees.
 
 ## Install / run
 
-No install required:
-
 ```bash
-python3 -m morphdb --port 8787 --db ./app.sqlite3
+pip install morphdb
 ```
 
-Or install the console script:
+Manage the local server with the `morphdb` CLI:
 
 ```bash
-pip install -e .
-morphdb --port 8787 --db ./app.sqlite3
+morphdb start          # run in the background (default 127.0.0.1:8787)
+morphdb status         # running? where? how many apps?
+morphdb stop           # stop it
+morphdb run            # run in the foreground instead (blocking)
+morphdb dashboard      # read-only web view of every app + its tables
+morphdb install-skill  # install the MorphDB Claude Code skill (into ~/.claude)
 ```
 
-Flags: `--host` (default `127.0.0.1`), `--port` (default `8787`),
-`--db` (default `morphdb.sqlite3`; use `:memory:` for ephemeral).
+Data lives in `~/.morphdb/data.sqlite3` (change it with `--db PATH` or
+`--db :memory:`; move the state dir with `$MORPHDB_HOME`). Server flags:
+`--host`, `--port`, `--db`. From a source checkout with no install, the
+foreground server is `python3 -m morphdb --port 8787 --db ./app.sqlite3`.
 
 Then: `curl http://127.0.0.1:8787/help` for a live reference.
 
+**Pointing clients at a hosted MorphDB.** Set `MORPHDB_HOST` to a full URL (e.g.
+`https://db.example.com`) and the schema CLI — plus any frontend that reads
+`window.MORPHDB_HOST` — calls that hosted server (running this same code) instead
+of localhost. It's a client-side setting that names a *backend*, not a database
+connection string.
+
 ## Quickstart
 
 ```bash

{morphdb-0.1.1 → morphdb-0.1.2}/morphdb/__init__.py

@@ -5,4 +5,4 @@ coding agent iterates, while the frontend keeps calling the same small set of
 generic, deterministic endpoints.
 """
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"

morphdb-0.1.2/morphdb/cli/__init__.py

@@ -0,0 +1,22 @@
+"""MorphDB command-line interface — process management + admin dashboard.
+
+Intentionally separate from the core engine (db / schema / objects / server):
+this package only *orchestrates* a server process and offers a read-only admin
+view. It never changes how the core stores or serves data.
+
+Commands (see :mod:`morphdb.cli.main`):
+
+    morphdb              start the server in the background (alias of `start`)
+    morphdb start        same, explicit
+    morphdb status       is it running? where? how many apps?
+    morphdb stop         stop the background server
+    morphdb run          run in the foreground (blocking; for dev)
+    morphdb dashboard    open a read-only web view of every app + its tables
+
+Storage: the local server keeps data in a per-user SQLite file at
+``~/.morphdb/data.sqlite3`` (override the file with ``--db``, or move the state
+dir with ``$MORPHDB_HOME``). To talk to a MorphDB hosted somewhere else instead
+of a local one, point *clients* at it with ``$MORPHDB_HOST`` (a full URL) — that
+is a client-side setting, not a database connection string; the engine is always
+SQLite.
+"""

morphdb-0.1.2/morphdb/cli/dashboard.py

@@ -0,0 +1,134 @@
+"""Read-only admin dashboard: every app and its tables, in one local page.
+
+Operator-facing and local-only — it opens the SQLite file directly (read-only)
+rather than going through the HTTP API, so it can list apps without adding a
+"list apps" endpoint to the public surface (which is intentionally absent).
+"""
+
+import html
+import json
+import sqlite3
+import webbrowser
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+
+def gather(db):
+    """A read-only snapshot: {apps: [{app, types:[{name,fields,count}], relations, edges}]}.
+
+    Tolerates a missing/empty/locked database by returning an ``error`` string.
+    """
+    try:
+        c = sqlite3.connect(f"file:{db}?mode=ro", uri=True, timeout=2)
+        c.row_factory = sqlite3.Row
+    except Exception as e:
+        return {"error": f"cannot open database: {e}", "apps": []}
+    try:
+        try:
+            apps = [r["key"] for r in c.execute("SELECT key FROM apps ORDER BY key")]
+        except sqlite3.OperationalError:
+            return {"error": "no MorphDB schema in this database yet", "apps": []}
+        out = []
+        for app in apps:
+            types = []
+            for r in c.execute(
+                    "SELECT name, fields FROM object_schemas WHERE app=? ORDER BY name",
+                    (app,)):
+                try:
+                    fields = list(json.loads(r["fields"]).keys())
+                except Exception:
+                    fields = []
+                count = c.execute(
+                    "SELECT COUNT(*) FROM objects WHERE app=? AND object_type=?",
+                    (app, r["name"])).fetchone()[0]
+                types.append({"name": r["name"], "fields": fields, "count": count})
+            relations = c.execute(
+                "SELECT COUNT(*) FROM association_schemas WHERE app=?", (app,)).fetchone()[0]
+            edges = c.execute(
+                "SELECT COUNT(*) FROM associations WHERE app=?", (app,)).fetchone()[0]
+            out.append({"app": app, "types": types,
+                        "relations": relations, "edges": edges})
+        return {"apps": out}
+    finally:
+        c.close()
+
+
+_CSS = """
+  :root { color-scheme: light dark; }
+  body { font: 15px/1.5 system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+         max-width: 900px; margin: 32px auto; padding: 0 16px; }
+  header { display:flex; align-items:baseline; justify-content:space-between; gap:12px;
+           border-bottom:1px solid #8884; padding-bottom:12px; margin-bottom:20px; }
+  h1 { font-size:1.3rem; margin:0; }
+  .db { color:#888; font-size:12px; font-family:ui-monospace,Menlo,monospace; }
+  .card { border:1px solid #8884; border-radius:10px; padding:14px 16px; margin-bottom:16px; }
+  .card h2 { font-size:1.05rem; margin:0 0 2px; }
+  .meta { color:#888; font-size:12px; margin-bottom:10px; }
+  table { width:100%; border-collapse:collapse; font-size:14px; }
+  th, td { text-align:left; padding:6px 8px; border-bottom:1px solid #8882; }
+  th { color:#888; font-weight:600; font-size:12px; text-transform:uppercase; letter-spacing:.04em; }
+  td.n { text-align:right; font-variant-numeric:tabular-nums; }
+  .muted { color:#999; } .err { color:#ef4444; }
+  code { font-family:ui-monospace,Menlo,monospace; background:#8881; padding:1px 5px; border-radius:5px; }
+  footer { color:#999; font-size:12px; margin-top:24px; }
+"""
+
+
+def render(data, db):
+    esc = html.escape
+    if data.get("error"):
+        body = f"<p class='err'>{esc(data['error'])}</p>"
+    elif not data["apps"]:
+        body = "<p class='muted'>No apps registered yet. Create one with <code>POST /app</code>.</p>"
+    else:
+        cards = []
+        for a in data["apps"]:
+            if a["types"]:
+                trows = "".join(
+                    f"<tr><td><b>{esc(t['name'])}</b></td>"
+                    f"<td>{esc(', '.join(t['fields']) or '—')}</td>"
+                    f"<td class='n'>{t['count']}</td></tr>"
+                    for t in a["types"])
+            else:
+                trows = "<tr><td colspan='3' class='muted'>no types yet</td></tr>"
+            cards.append(
+                f"<section class='card'><h2>{esc(a['app'])}</h2>"
+                f"<div class='meta'>{len(a['types'])} types · "
+                f"{a['relations']} relations · {a['edges']} edges</div>"
+                "<table><thead><tr><th>type</th><th>fields</th><th>objects</th></tr></thead>"
+                f"<tbody>{trows}</tbody></table></section>")
+        body = "\n".join(cards)
+    return (
+        "<!doctype html><html><head><meta charset='utf-8'>"
+        "<meta name='viewport' content='width=device-width, initial-scale=1'>"
+        f"<title>MorphDB admin</title><style>{_CSS}</style></head><body>"
+        f"<header><h1>MorphDB admin</h1><div class='db'>{esc(str(db))}</div></header>"
+        f"{body}<footer>read-only view · refresh to update</footer></body></html>")
+
+
+def serve(db, host="127.0.0.1", port=8788, open_browser=True):
+    class Handler(BaseHTTPRequestHandler):
+        def do_GET(self):
+            body = render(gather(db), db).encode("utf-8")
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def log_message(self, *a):
+            pass
+
+    httpd = ThreadingHTTPServer((host, port), Handler)
+    url = f"http://{host}:{port}"
+    print(f"MorphDB admin dashboard: {url}\n  reading: {db}\n  Ctrl-C to stop.")
+    if open_browser:
+        try:
+            webbrowser.open(url)
+        except Exception:
+            pass
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        httpd.server_close()

morphdb-0.1.2/morphdb/cli/main.py

@@ -0,0 +1,145 @@
+"""``morphdb`` console-script entry point: a small process/admin CLI.
+
+    morphdb            start the server in the background (alias of `start`)
+    morphdb start      start the server in the background
+    morphdb status     show whether it is running, where, and how many apps
+    morphdb stop       stop the background server
+    morphdb run        run the server in the foreground (blocking)
+    morphdb dashboard  open the read-only admin dashboard
+
+``python -m morphdb`` remains the plain foreground server (what `start` and the
+skill spawn under the hood); this CLI only wraps it.
+"""
+
+import argparse
+import sys
+
+from . import dashboard, service
+from . import skill as skill_mod
+
+
+def _fmt_status(st):
+    if not st.get("running"):
+        msg = "MorphDB is not running."
+        if st.get("stale"):
+            msg += "  (cleared a stale pid file)"
+        return msg
+    health = "healthy" if st.get("healthy") else "starting / not responding yet"
+    lines = [
+        f"MorphDB is running (pid {st['pid']}) at http://{st['host']}:{st['port']}  [{health}]",
+        f"  db:   {st['db']}",
+    ]
+    n = service.app_count(st.get("db"))
+    if n is not None:
+        lines.append(f"  apps: {n}")
+    return "\n".join(lines)
+
+
+def cmd_start(args):
+    st, _ = service.start(args.host, args.port, args.db)
+    print(_fmt_status(st))
+    if not st.get("running"):
+        print(f"  (server exited on startup — check the log: {service.log_file()})")
+        return 1
+    return 0
+
+
+def cmd_run(args):
+    from ..server import serve as serve_fg
+    serve_fg(host=args.host, port=args.port, db_path=args.db or service.default_db())
+    return 0
+
+
+def cmd_status(args):
+    print(_fmt_status(service.status()))
+    return 0
+
+
+def cmd_stop(args):
+    print("MorphDB stopped." if service.stop() else "MorphDB was not running.")
+    return 0
+
+
+def cmd_dashboard(args):
+    dashboard.serve(args.db or service.default_db(), port=args.port,
+                    open_browser=not args.no_open)
+    return 0
+
+
+def cmd_install_skill(args):
+    try:
+        dest = skill_mod.install_skill(project=args.project, force=args.force)
+    except FileExistsError as e:
+        print(f"Skill already installed at {e}. Re-run with --force to overwrite.")
+        return 1
+    except (FileNotFoundError, OSError) as e:
+        print(f"Could not install skill: {e}")
+        return 1
+    where = "this project" if args.project else "your home (~/.claude)"
+    print(f"Installed the 'morphdb' Claude skill to {dest}\n"
+          f"  ({where}). Restart Claude Code (or reload skills) to pick it up.")
+    return 0
+
+
+def _add_server_opts(sp):
+    sp.add_argument("--host", default=service.DEFAULT_HOST,
+                    help=f"bind host (default {service.DEFAULT_HOST})")
+    sp.add_argument("--port", type=int, default=service.DEFAULT_PORT,
+                    help=f"bind port (default {service.DEFAULT_PORT})")
+    sp.add_argument("--db", default=None,
+                    help="SQLite path or :memory: (default ~/.morphdb/data.sqlite3)")
+
+
+def build_parser():
+    from .. import __version__
+    p = argparse.ArgumentParser(
+        prog="morphdb",
+        description="MorphDB — a multi-tenant backend for vibe-coded sites. "
+                    "Manage the local server and view your apps.")
+    p.add_argument("--version", action="version", version=f"morphdb {__version__}")
+    sub = p.add_subparsers(dest="command")
+
+    sp = sub.add_parser("start", help="start the server in the background")
+    _add_server_opts(sp)
+    sp.set_defaults(func=cmd_start)
+
+    sp = sub.add_parser("run", help="run the server in the foreground (blocking)")
+    _add_server_opts(sp)
+    sp.set_defaults(func=cmd_run)
+
+    sub.add_parser("status", help="show whether the server is running"
+                   ).set_defaults(func=cmd_status)
+    sub.add_parser("stop", help="stop the background server"
+                   ).set_defaults(func=cmd_stop)
+
+    sp = sub.add_parser("dashboard", help="open the read-only admin dashboard")
+    sp.add_argument("--port", type=int, default=8788, help="dashboard port (default 8788)")
+    sp.add_argument("--db", default=None, help="database to inspect (default the server's)")
+    sp.add_argument("--no-open", action="store_true", help="don't auto-open a browser")
+    sp.set_defaults(func=cmd_dashboard)
+
+    sp = sub.add_parser("install-skill",
+                        help="install the MorphDB skill into Claude Code")
+    sp.add_argument("--project", nargs="?", const=".", default=None,
+                    metavar="DIR",
+                    help="install into a project's .claude (DIR, default cwd) "
+                         "instead of ~/.claude")
+    sp.add_argument("--force", action="store_true", help="overwrite if it exists")
+    sp.set_defaults(func=cmd_install_skill)
+
+    return p
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv:                      # bare `morphdb` => start in the background
+        argv = ["start"]
+    args = build_parser().parse_args(argv)
+    if not getattr(args, "func", None):
+        build_parser().print_help()
+        return 1
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

morphdb-0.1.2/morphdb/cli/service.py

@@ -0,0 +1,169 @@
+"""Background-service management for the MorphDB server.
+
+Starts ``python -m morphdb`` as a detached child process (its own session, so
+it survives the terminal closing — the zero-dependency equivalent of a tmux
+session), and records pid + bind info under the state dir so ``status``/``stop``
+can find it later. Pure stdlib.
+"""
+
+import json
+import os
+import signal
+import sqlite3
+import subprocess
+import sys
+import time
+import urllib.request
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8787
+
+
+def _home():
+    """The MorphDB state dir: ``$MORPHDB_HOME`` or ``~/.morphdb``."""
+    return os.environ.get("MORPHDB_HOME") or os.path.join(
+        os.path.expanduser("~"), ".morphdb")
+
+
+def state_dir():
+    d = _home()
+    os.makedirs(d, exist_ok=True)
+    return d
+
+
+def _path(name):
+    return os.path.join(state_dir(), name)
+
+
+def meta_file():
+    return _path("service.json")
+
+
+def log_file():
+    return _path("server.log")
+
+
+def default_db():
+    """Where the local server keeps data: a per-user SQLite file.
+
+    Override the file with ``--db`` (any path, or ``:memory:``) or move the whole
+    state dir with ``$MORPHDB_HOME``. To use a MorphDB hosted elsewhere instead of
+    a local one, you don't change this — you point *clients* at that server's URL
+    with ``$MORPHDB_HOST`` (see the skill); the engine itself is always SQLite.
+    """
+    return _path("data.sqlite3")
+
+
+def read_meta():
+    try:
+        with open(meta_file()) as f:
+            return json.load(f)
+    except (OSError, ValueError):
+        return None
+
+
+def write_meta(meta):
+    with open(meta_file(), "w") as f:
+        json.dump(meta, f)
+
+
+def clear_meta():
+    try:
+        os.remove(meta_file())
+    except OSError:
+        pass
+
+
+def _alive(pid):
+    if not pid:
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def _health(host, port, timeout=1.0):
+    try:
+        with urllib.request.urlopen(
+                f"http://{host}:{port}/health", timeout=timeout) as r:
+            return r.status == 200
+    except Exception:
+        return False
+
+
+def status():
+    """Snapshot: {running, [pid, host, port, db, healthy] | [stale]}."""
+    meta = read_meta()
+    if not meta:
+        return {"running": False}
+    if not _alive(meta.get("pid")):
+        return {"running": False, "stale": True, **meta}
+    return {
+        "running": True,
+        **meta,
+        "healthy": _health(meta.get("host", DEFAULT_HOST),
+                           meta.get("port", DEFAULT_PORT)),
+    }
+
+
+def app_count(db):
+    """Read-only count of registered apps (for status). None if unreadable."""
+    try:
+        c = sqlite3.connect(f"file:{db}?mode=ro", uri=True, timeout=1)
+        try:
+            return c.execute("SELECT COUNT(*) FROM apps").fetchone()[0]
+        finally:
+            c.close()
+    except Exception:
+        return None
+
+
+def start(host=DEFAULT_HOST, port=DEFAULT_PORT, db=None, wait=6.0):
+    """Start the server detached. Returns (status_dict, attempted_start_bool)."""
+    if status().get("running"):
+        return status(), False
+    db = db or default_db()
+    log = open(log_file(), "ab")
+    proc = subprocess.Popen(
+        [sys.executable, "-m", "morphdb",
+         "--host", host, "--port", str(port), "--db", db],
+        stdout=log, stderr=log, stdin=subprocess.DEVNULL,
+        start_new_session=True,            # detach from the controlling terminal
+    )
+    write_meta({"pid": proc.pid, "host": host, "port": port, "db": db})
+    deadline = time.time() + wait
+    while time.time() < deadline:
+        if proc.poll() is not None:        # died on startup (e.g. port in use)
+            break
+        if _health(host, port):
+            break
+        time.sleep(0.2)
+    return status(), True
+
+
+def stop(timeout=5.0):
+    """Stop the background server. Returns True if a live process was killed."""
+    meta = read_meta()
+    if not meta or not _alive(meta.get("pid")):
+        clear_meta()
+        return False
+    pid = meta["pid"]
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        clear_meta()
+        return False
+    deadline = time.time() + timeout
+    while time.time() < deadline and _alive(pid):
+        time.sleep(0.15)
+    if _alive(pid):
+        try:
+            os.kill(pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+    clear_meta()
+    return True

morphdb-0.1.2/morphdb/cli/skill.py

@@ -0,0 +1,54 @@
+"""Install the bundled MorphDB Claude skill into a `.claude/skills` directory.
+
+The skill (SKILL.md + the schema CLI) ships as package data inside ``morphdb``,
+so this works the same whether MorphDB was pip/brew-installed or run from a
+source checkout. It copies the skill tree to ``~/.claude/skills/morphdb`` (or a
+project's ``.claude/skills/morphdb``), where Claude Code auto-discovers it.
+"""
+
+import os
+from importlib import resources
+
+SKILL_NAME = "morphdb"
+
+
+def _copy_tree(src, dst):
+    """Recursively copy an importlib.resources Traversable tree to a real dir."""
+    if src.is_dir():
+        os.makedirs(dst, exist_ok=True)
+        for child in src.iterdir():
+            if child.name == "__pycache__":
+                continue
+            _copy_tree(child, os.path.join(dst, child.name))
+    else:
+        with open(dst, "wb") as f:
+            f.write(src.read_bytes())
+
+
+def install_skill(claude_dir=None, project=None, force=False):
+    """Copy the packaged skill into a `.claude/skills/morphdb` directory.
+
+    ``project`` (a path, or "." for cwd) installs into that project's
+    ``.claude``; otherwise it installs into ``~/.claude`` (all projects).
+    ``claude_dir`` overrides the `.claude` location outright (used by tests).
+    Returns the destination path. Raises FileExistsError if it already exists
+    and ``force`` is false.
+    """
+    if claude_dir is None:
+        base = os.path.abspath(project) if project else os.path.expanduser("~")
+        claude_dir = os.path.join(base, ".claude")
+    dest = os.path.join(claude_dir, "skills", SKILL_NAME)
+
+    if os.path.exists(dest) and not force:
+        raise FileExistsError(dest)
+
+    src = resources.files("morphdb") / "skill"
+    if not src.is_dir():
+        raise FileNotFoundError(
+            "packaged skill not found (morphdb/skill missing from the install).")
+
+    if os.path.exists(dest) and force:
+        import shutil
+        shutil.rmtree(dest)
+    _copy_tree(src, dest)
+    return dest