morphdb 0.1.2__tar.gz → 0.1.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: morphdb
-Version: 0.1.2
+Version: 0.1.4
 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
@@ -30,21 +30,123 @@ Dynamic: license-file
 **A coding-agent-friendly, multi-tenant backend for vibe-coded websites.**
 
 Reshape the data model as fast as your coding agent iterates — the frontend
-keeps calling the same small set of generic, deterministic endpoints.
+keeps calling the same small set of generic, deterministic endpoints. One
+process hosts many isolated apps (one per site), zero dependencies, backed by
+SQLite.
 
+📖 **[Visual explainer → morphdb.pages.dev](https://morphdb.pages.dev)** — the whole idea (schema-fluid, API-stable), the agent/frontend split, relations, and how Claude plugs in over MCP, on one page.
+
+## Install
+
+```bash
+pip install morphdb
 ```
-   you (the coding agent)              the frontend you build
-   ──────────────────────             ──────────────────────
-   reshape the schema freely    │     calls fixed generic endpoints
-   PUT    /schema/{type}        │     POST /objects/{type}
-   GET    /schema               │     GET  /objects/{type}?field=…
-   DELETE /schema/{type}        │     PATCH /objects/{type}/{guid}
-            │                                    │
-            └──────────────  MorphDB  ───────────┘
-            (one process · many apps · SQLite)
-                every call: X-App-Key: <app>
+
+Manage the local server with the `morphdb` CLI:
+
+```bash
+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)
+```
+
+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`.
+
+To upgrade later: `pip install -U morphdb`, then `morphdb stop && morphdb start`
+to reload the new code (data in `~/.morphdb` is preserved across `0.1.x`).
+
+**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.
+
+## Use it
+
+With the server running (`morphdb start`):
+
+```bash
+BASE=http://127.0.0.1:8787
+
+# 0. register an app; send its key as X-App-Key on every schema/object call
+curl -X POST $BASE/app -d '{"key":"my-site"}'
+H="X-App-Key: my-site"
+
+# 1. define types + a relation
+curl -X PUT $BASE/schema/user -H "$H" -d '{"fields":{"name":"string"}}'
+curl -X PUT $BASE/schema/task -H "$H" -d '{
+  "fields": {"title":"string",
+             "done":{"type":"boolean","index":true},
+             "priority":{"type":"number","index":true}},
+  "relations": {"assignee":{"to":"user","cardinality":"many_to_one","inverse":"tasks"}}}'
+
+# 2. create + read + query
+U=$(curl -s -X POST $BASE/objects/user -H "$H" -d '{"name":"Ann"}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["_guid"])')
+curl -X POST $BASE/objects/task -H "$H" -d "{\"title\":\"buy milk\",\"priority\":2,\"assignee\":\"$U\"}"
+curl -H "$H" "$BASE/objects/task?done=false&sort=priority&order=desc"
+curl -H "$H" "$BASE/objects/user/$U"          # → includes "tasks":[…]
+
+# 3. morph the schema later — existing rows just gain the new field as null
+curl -X PUT $BASE/schema/task -H "$H" -d '{"merge":true,"fields":{"due":"datetime"}}'
+```
+
+See `examples/todo/index.html` for a complete single-file frontend backed by MorphDB.
+
+## Command-line interface
+
+`morphdb` runs the server as a **background service** — `start` launches it
+detached and hands your terminal straight back; `status` / `stop` find it again
+via a pid file under the state dir.
+
+| Command | What it does |
+| --- | --- |
+| `morphdb` or `morphdb start` | Start the server in the background (returns immediately). |
+| `morphdb status` | Is it running? URL, pid, health, and app count. |
+| `morphdb stop` | Stop the background server. |
+| `morphdb logs` | Show the background server's log (`-n N` lines, `-f` to follow). |
+| `morphdb run` | Run in the **foreground** (blocking) instead. |
+| `morphdb dashboard` | Open a read-only web view of every app and its tables. |
+| `morphdb install-skill` | Install the bundled Claude Code skill (below). |
+| `morphdb --version` | Print the version. |
+
+`start` / `run` accept `--host` (default `127.0.0.1`), `--port` (default `8787`),
+and `--db` (a SQLite path or `:memory:`; default `~/.morphdb/data.sqlite3`).
+`dashboard` accepts `--port` (default `8788`), `--db`, and `--no-open`. Service
+state (pid, log, the default db) lives under `~/.morphdb` — relocate it with
+`$MORPHDB_HOME`.
+
+```bash
+morphdb start                          # background, default 127.0.0.1:8787
+morphdb start --port 9000 --db ./my.sqlite3
+morphdb status                         # -> running (pid …) at http://… [healthy]
+morphdb dashboard                      # opens http://127.0.0.1:8788
+morphdb stop
+morphdb run                            # foreground instead (Ctrl-C to quit)
 ```
 
+### Install the Claude Code skill
+
+`install-skill` writes the bundled MorphDB skill into a Claude skills directory,
+so a coding agent automatically reaches for MorphDB when building a data-backed
+site:
+
+```bash
+morphdb install-skill                  # -> ~/.claude/skills/morphdb (all projects)
+morphdb install-skill --project        # -> ./.claude/skills/morphdb (current project)
+morphdb install-skill --project DIR    # -> DIR/.claude/skills/morphdb
+```
+
+It installs the skill **bundled in the installed package** (not live from
+GitHub) and is **idempotent** — re-running overwrites with the current version.
+To get the newest skill, `pip install -U morphdb` first, then re-run. Restart
+Claude Code afterward to pick it up.
+
 ## Why
 
 AI coding agents are great at building HTML/CSS/JS frontends but thrash hard on
@@ -58,6 +160,19 @@ invalidation). Adding, removing, or retyping a field is an O(1) metadata edit
 **no migration, no row rewrite, no downtime** — regardless of how much data
 exists. Meanwhile the frontend talks to generic endpoints that never change.
 
+```
+   you (the coding agent)              the frontend you build
+   ──────────────────────             ──────────────────────
+   reshape the schema freely    │     calls fixed generic endpoints
+   PUT    /schema/{type}        │     POST /objects/{type}
+   GET    /schema               │     GET  /objects/{type}?field=…
+   DELETE /schema/{type}        │     PATCH /objects/{type}/{guid}
+            │                                    │
+            └──────────────  MorphDB  ───────────┘
+            (one process · many apps · SQLite)
+                every call: X-App-Key: <app>
+```
+
 ## The shape of it
 
 One MorphDB process hosts **many apps** (one per website), fully isolated from
@@ -126,63 +241,6 @@ curl -X PATCH $BASE/objects/user/<u> -d '{"tasks":["<t1>","<t2>"]}'
 > Scope: a localhost-scale developer tool. Not built for multi-tenant auth,
 > horizontal scale, or production durability guarantees.
 
-## Install / run
-
-```bash
-pip install morphdb
-```
-
-Manage the local server with the `morphdb` CLI:
-
-```bash
-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)
-```
-
-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
-BASE=http://127.0.0.1:8787
-
-# 0. register an app; send its key as X-App-Key on every schema/object call
-curl -X POST $BASE/app -d '{"key":"my-site"}'
-H="X-App-Key: my-site"
-
-# 1. define types + a relation
-curl -X PUT $BASE/schema/user -H "$H" -d '{"fields":{"name":"string"}}'
-curl -X PUT $BASE/schema/task -H "$H" -d '{
-  "fields": {"title":"string","done":"boolean","priority":"number"},
-  "relations": {"assignee":{"to":"user","cardinality":"many_to_one","inverse":"tasks"}}}'
-
-# 2. create + read + query
-U=$(curl -s -X POST $BASE/objects/user -H "$H" -d '{"name":"Ann"}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["_guid"])')
-curl -X POST $BASE/objects/task -H "$H" -d "{\"title\":\"buy milk\",\"priority\":2,\"assignee\":\"$U\"}"
-curl -H "$H" "$BASE/objects/task?done=false&sort=priority&order=desc"
-curl -H "$H" "$BASE/objects/user/$U"          # → includes "tasks":[…]
-
-# 3. morph the schema later — existing rows just gain the new field as null
-curl -X PUT $BASE/schema/task -H "$H" -d '{"merge":true,"fields":{"due":"datetime"}}'
-```
-
-See `examples/todo/index.html` for a complete single-file frontend backed by MorphDB.
-
 ## Data model
 
 | Concept | What it is |
@@ -267,15 +325,58 @@ Every schema and object request must send the app key as the `X-App-Key` header
 
 ### Query operators
 
-Append `__op` to a field name: `eq` (default), `ne`, `gt`, `gte`, `lt`, `lte`,
-`contains` (substring), `in` (comma-separated), `exists` (`true`/`false`).
-Filtering is on **fields**, not relations.
+A field is filterable/sortable only if its schema marks it **`"index": true`**
+(opt-in, default off). Filtering or sorting an un-indexed field returns a 400
+telling you to index it; turning the flag on backfills existing objects
+automatically, turning it off is instant. `json` fields can't be indexed.
+
+Append `__op` to an **indexed field** name: `eq` (default), `ne`, `gt`, `gte`,
+`lt`, `lte`, `contains` (substring), `in` (comma-separated), `exists`
+(`true`/`false`).
 
 ```
+# priority, title, done, status all declared with "index": true
 GET /objects/task?priority__gte=3&title__contains=buy&done=false
-GET /objects/task?status__in=open,blocked&sort=_created_at&order=desc&limit=50
+GET /objects/task?status__in=open,blocked&sort=priority&order=desc&limit=50
 ```
 
+You can also filter by a **relation** — treat it like an ORM foreign key, not a
+manual join. Filtering by a relation matches objects linked to a given neighbor,
+and resolves through the indexed edge table (so it is index-backed):
+
+| Query | Meaning |
+| --- | --- |
+| `?assignee=<guid>` | objects whose `assignee` is / includes that neighbor |
+| `?assignee__in=<g1>,<g2>` | linked to any of those neighbors |
+| `?assignee__ne=<guid>` | not linked to that neighbor (includes unlinked) |
+| `?assignee__exists=true` | has any `assignee` (`false` → has none) |
+
+```
+# "stages of business X that are still in build" — relation + field, one query
+GET /objects/stage?business=<bizguid>&status=build&sort=_created_at
+```
+
+Relation filters compose with field filters, `sort`, and pagination. Scalar
+comparisons (`gt`/`lt`/`contains`) are field-only; relations support
+`eq`/`ne`/`in`/`exists`. So **model a foreign key as a relation, not a string
+field** — you keep one-read traversal *and* get filtering, indexed, for free.
+
+### Including related objects
+
+By default a relation reads back as a guid (to-one) or list of guids (to-many).
+Add `?include=` with comma-separated relation paths (dots nest) to hydrate them
+into the full neighbor objects, nested Prisma-style:
+
+```
+GET /objects/post?include=author,comments,comments.author
+# each post.author becomes a full user; post.comments a list of full comments,
+# and each comment.author a full user too.
+```
+
+Works on the list endpoint and both single-object reads. Read-only, depth ≤ 4,
+and batched (one query per relation per level — no N+1). Writes stay flat: create
+and update with guids, never nested objects.
+
 ## Errors
 
 JSON shape: `{"error": {"code": "...", "message": "...", ...extra}}`.
@@ -310,8 +411,10 @@ allowed, `413` body too large, `500` internal.
   old type simply reads as unset (the field's default, or null) until it's
   written again; reads and queries apply this rule identically, so they always
   agree. Re-adding a dropped field at the same type recovers its values.
-- **Filtering is field-only.** Query operators apply to raw fields; relations
-  are read/written on the object body but not filtered server-side (yet).
+- **Filtering/sorting is opt-in per field.** Only a field marked `"index": true`
+  can be filtered or sorted (it gets a row in the indexed `field_index` table);
+  an un-indexed field is storage-only and a filter/sort on it is a 400. Relations
+  are always filterable via the indexed edge table — no flag needed.
 - **Integer magnitude.** Numbers are stored and read back exactly at any size.
   Filtering/sorting on integers beyond ±2⁶³ uses floating-point comparison (a
   SQLite limitation), so equality/range queries on such huge integers may be

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

@@ -3,21 +3,123 @@
 **A coding-agent-friendly, multi-tenant backend for vibe-coded websites.**
 
 Reshape the data model as fast as your coding agent iterates — the frontend
-keeps calling the same small set of generic, deterministic endpoints.
+keeps calling the same small set of generic, deterministic endpoints. One
+process hosts many isolated apps (one per site), zero dependencies, backed by
+SQLite.
 
+📖 **[Visual explainer → morphdb.pages.dev](https://morphdb.pages.dev)** — the whole idea (schema-fluid, API-stable), the agent/frontend split, relations, and how Claude plugs in over MCP, on one page.
+
+## Install
+
+```bash
+pip install morphdb
 ```
-   you (the coding agent)              the frontend you build
-   ──────────────────────             ──────────────────────
-   reshape the schema freely    │     calls fixed generic endpoints
-   PUT    /schema/{type}        │     POST /objects/{type}
-   GET    /schema               │     GET  /objects/{type}?field=…
-   DELETE /schema/{type}        │     PATCH /objects/{type}/{guid}
-            │                                    │
-            └──────────────  MorphDB  ───────────┘
-            (one process · many apps · SQLite)
-                every call: X-App-Key: <app>
+
+Manage the local server with the `morphdb` CLI:
+
+```bash
+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)
+```
+
+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`.
+
+To upgrade later: `pip install -U morphdb`, then `morphdb stop && morphdb start`
+to reload the new code (data in `~/.morphdb` is preserved across `0.1.x`).
+
+**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.
+
+## Use it
+
+With the server running (`morphdb start`):
+
+```bash
+BASE=http://127.0.0.1:8787
+
+# 0. register an app; send its key as X-App-Key on every schema/object call
+curl -X POST $BASE/app -d '{"key":"my-site"}'
+H="X-App-Key: my-site"
+
+# 1. define types + a relation
+curl -X PUT $BASE/schema/user -H "$H" -d '{"fields":{"name":"string"}}'
+curl -X PUT $BASE/schema/task -H "$H" -d '{
+  "fields": {"title":"string",
+             "done":{"type":"boolean","index":true},
+             "priority":{"type":"number","index":true}},
+  "relations": {"assignee":{"to":"user","cardinality":"many_to_one","inverse":"tasks"}}}'
+
+# 2. create + read + query
+U=$(curl -s -X POST $BASE/objects/user -H "$H" -d '{"name":"Ann"}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["_guid"])')
+curl -X POST $BASE/objects/task -H "$H" -d "{\"title\":\"buy milk\",\"priority\":2,\"assignee\":\"$U\"}"
+curl -H "$H" "$BASE/objects/task?done=false&sort=priority&order=desc"
+curl -H "$H" "$BASE/objects/user/$U"          # → includes "tasks":[…]
+
+# 3. morph the schema later — existing rows just gain the new field as null
+curl -X PUT $BASE/schema/task -H "$H" -d '{"merge":true,"fields":{"due":"datetime"}}'
+```
+
+See `examples/todo/index.html` for a complete single-file frontend backed by MorphDB.
+
+## Command-line interface
+
+`morphdb` runs the server as a **background service** — `start` launches it
+detached and hands your terminal straight back; `status` / `stop` find it again
+via a pid file under the state dir.
+
+| Command | What it does |
+| --- | --- |
+| `morphdb` or `morphdb start` | Start the server in the background (returns immediately). |
+| `morphdb status` | Is it running? URL, pid, health, and app count. |
+| `morphdb stop` | Stop the background server. |
+| `morphdb logs` | Show the background server's log (`-n N` lines, `-f` to follow). |
+| `morphdb run` | Run in the **foreground** (blocking) instead. |
+| `morphdb dashboard` | Open a read-only web view of every app and its tables. |
+| `morphdb install-skill` | Install the bundled Claude Code skill (below). |
+| `morphdb --version` | Print the version. |
+
+`start` / `run` accept `--host` (default `127.0.0.1`), `--port` (default `8787`),
+and `--db` (a SQLite path or `:memory:`; default `~/.morphdb/data.sqlite3`).
+`dashboard` accepts `--port` (default `8788`), `--db`, and `--no-open`. Service
+state (pid, log, the default db) lives under `~/.morphdb` — relocate it with
+`$MORPHDB_HOME`.
+
+```bash
+morphdb start                          # background, default 127.0.0.1:8787
+morphdb start --port 9000 --db ./my.sqlite3
+morphdb status                         # -> running (pid …) at http://… [healthy]
+morphdb dashboard                      # opens http://127.0.0.1:8788
+morphdb stop
+morphdb run                            # foreground instead (Ctrl-C to quit)
 ```
 
+### Install the Claude Code skill
+
+`install-skill` writes the bundled MorphDB skill into a Claude skills directory,
+so a coding agent automatically reaches for MorphDB when building a data-backed
+site:
+
+```bash
+morphdb install-skill                  # -> ~/.claude/skills/morphdb (all projects)
+morphdb install-skill --project        # -> ./.claude/skills/morphdb (current project)
+morphdb install-skill --project DIR    # -> DIR/.claude/skills/morphdb
+```
+
+It installs the skill **bundled in the installed package** (not live from
+GitHub) and is **idempotent** — re-running overwrites with the current version.
+To get the newest skill, `pip install -U morphdb` first, then re-run. Restart
+Claude Code afterward to pick it up.
+
 ## Why
 
 AI coding agents are great at building HTML/CSS/JS frontends but thrash hard on
@@ -31,6 +133,19 @@ invalidation). Adding, removing, or retyping a field is an O(1) metadata edit
 **no migration, no row rewrite, no downtime** — regardless of how much data
 exists. Meanwhile the frontend talks to generic endpoints that never change.
 
+```
+   you (the coding agent)              the frontend you build
+   ──────────────────────             ──────────────────────
+   reshape the schema freely    │     calls fixed generic endpoints
+   PUT    /schema/{type}        │     POST /objects/{type}
+   GET    /schema               │     GET  /objects/{type}?field=…
+   DELETE /schema/{type}        │     PATCH /objects/{type}/{guid}
+            │                                    │
+            └──────────────  MorphDB  ───────────┘
+            (one process · many apps · SQLite)
+                every call: X-App-Key: <app>
+```
+
 ## The shape of it
 
 One MorphDB process hosts **many apps** (one per website), fully isolated from
@@ -99,63 +214,6 @@ curl -X PATCH $BASE/objects/user/<u> -d '{"tasks":["<t1>","<t2>"]}'
 > Scope: a localhost-scale developer tool. Not built for multi-tenant auth,
 > horizontal scale, or production durability guarantees.
 
-## Install / run
-
-```bash
-pip install morphdb
-```
-
-Manage the local server with the `morphdb` CLI:
-
-```bash
-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)
-```
-
-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
-BASE=http://127.0.0.1:8787
-
-# 0. register an app; send its key as X-App-Key on every schema/object call
-curl -X POST $BASE/app -d '{"key":"my-site"}'
-H="X-App-Key: my-site"
-
-# 1. define types + a relation
-curl -X PUT $BASE/schema/user -H "$H" -d '{"fields":{"name":"string"}}'
-curl -X PUT $BASE/schema/task -H "$H" -d '{
-  "fields": {"title":"string","done":"boolean","priority":"number"},
-  "relations": {"assignee":{"to":"user","cardinality":"many_to_one","inverse":"tasks"}}}'
-
-# 2. create + read + query
-U=$(curl -s -X POST $BASE/objects/user -H "$H" -d '{"name":"Ann"}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["_guid"])')
-curl -X POST $BASE/objects/task -H "$H" -d "{\"title\":\"buy milk\",\"priority\":2,\"assignee\":\"$U\"}"
-curl -H "$H" "$BASE/objects/task?done=false&sort=priority&order=desc"
-curl -H "$H" "$BASE/objects/user/$U"          # → includes "tasks":[…]
-
-# 3. morph the schema later — existing rows just gain the new field as null
-curl -X PUT $BASE/schema/task -H "$H" -d '{"merge":true,"fields":{"due":"datetime"}}'
-```
-
-See `examples/todo/index.html` for a complete single-file frontend backed by MorphDB.
-
 ## Data model
 
 | Concept | What it is |
@@ -240,15 +298,58 @@ Every schema and object request must send the app key as the `X-App-Key` header
 
 ### Query operators
 
-Append `__op` to a field name: `eq` (default), `ne`, `gt`, `gte`, `lt`, `lte`,
-`contains` (substring), `in` (comma-separated), `exists` (`true`/`false`).
-Filtering is on **fields**, not relations.
+A field is filterable/sortable only if its schema marks it **`"index": true`**
+(opt-in, default off). Filtering or sorting an un-indexed field returns a 400
+telling you to index it; turning the flag on backfills existing objects
+automatically, turning it off is instant. `json` fields can't be indexed.
+
+Append `__op` to an **indexed field** name: `eq` (default), `ne`, `gt`, `gte`,
+`lt`, `lte`, `contains` (substring), `in` (comma-separated), `exists`
+(`true`/`false`).
 
 ```
+# priority, title, done, status all declared with "index": true
 GET /objects/task?priority__gte=3&title__contains=buy&done=false
-GET /objects/task?status__in=open,blocked&sort=_created_at&order=desc&limit=50
+GET /objects/task?status__in=open,blocked&sort=priority&order=desc&limit=50
 ```
 
+You can also filter by a **relation** — treat it like an ORM foreign key, not a
+manual join. Filtering by a relation matches objects linked to a given neighbor,
+and resolves through the indexed edge table (so it is index-backed):
+
+| Query | Meaning |
+| --- | --- |
+| `?assignee=<guid>` | objects whose `assignee` is / includes that neighbor |
+| `?assignee__in=<g1>,<g2>` | linked to any of those neighbors |
+| `?assignee__ne=<guid>` | not linked to that neighbor (includes unlinked) |
+| `?assignee__exists=true` | has any `assignee` (`false` → has none) |
+
+```
+# "stages of business X that are still in build" — relation + field, one query
+GET /objects/stage?business=<bizguid>&status=build&sort=_created_at
+```
+
+Relation filters compose with field filters, `sort`, and pagination. Scalar
+comparisons (`gt`/`lt`/`contains`) are field-only; relations support
+`eq`/`ne`/`in`/`exists`. So **model a foreign key as a relation, not a string
+field** — you keep one-read traversal *and* get filtering, indexed, for free.
+
+### Including related objects
+
+By default a relation reads back as a guid (to-one) or list of guids (to-many).
+Add `?include=` with comma-separated relation paths (dots nest) to hydrate them
+into the full neighbor objects, nested Prisma-style:
+
+```
+GET /objects/post?include=author,comments,comments.author
+# each post.author becomes a full user; post.comments a list of full comments,
+# and each comment.author a full user too.
+```
+
+Works on the list endpoint and both single-object reads. Read-only, depth ≤ 4,
+and batched (one query per relation per level — no N+1). Writes stay flat: create
+and update with guids, never nested objects.
+
 ## Errors
 
 JSON shape: `{"error": {"code": "...", "message": "...", ...extra}}`.
@@ -283,8 +384,10 @@ allowed, `413` body too large, `500` internal.
   old type simply reads as unset (the field's default, or null) until it's
   written again; reads and queries apply this rule identically, so they always
   agree. Re-adding a dropped field at the same type recovers its values.
-- **Filtering is field-only.** Query operators apply to raw fields; relations
-  are read/written on the object body but not filtered server-side (yet).
+- **Filtering/sorting is opt-in per field.** Only a field marked `"index": true`
+  can be filtered or sorted (it gets a row in the indexed `field_index` table);
+  an un-indexed field is storage-only and a filter/sort on it is a 400. Relations
+  are always filterable via the indexed edge table — no flag needed.
 - **Integer magnitude.** Numbers are stored and read back exactly at any size.
   Filtering/sorting on integers beyond ±2⁶³ uses floating-point comparison (a
   SQLite limitation), so equality/range queries on such huge integers may be

{morphdb-0.1.2 → morphdb-0.1.4}/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.2"
+__version__ = "0.1.4"

morphdb-0.1.4/morphdb/cli/__init__.py

@@ -0,0 +1,31 @@
+"""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 logs          show the server log (-f to follow)
+    morphdb run           run in the foreground (blocking; for dev)
+    morphdb dashboard     open a read-only web view of every app + its tables
+    morphdb mcp           run the MCP server (stdio; spawned by Claude Code, not you)
+    morphdb install-skill install/update the bundled Claude Code skill
+
+The ``mcp`` command is a thin HTTP *client* of the running backend daemon (it
+auto-starts the daemon if needed). It exposes schema + app operations to a coding
+agent as MCP tools, so the agent calls real tools instead of shelling out to the
+bundled schema script. It is pure stdlib — no MCP SDK — so the package stays
+dependency-free.
+
+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.
+"""