tablewalk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Baljinder Randhawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,553 @@
+# tablewalk
+
+**Follow the data.**
+
+Most database tools are SQL clients that happen to render a grid. tablewalk
+starts somewhere else: a foreign key is a place you can go.
+
+```bash
+npx tablewalk                                          # asks in the browser
+npx tablewalk mydata.sqlite
+npx tablewalk postgres://user:pass@localhost/appdb
+npx tablewalk mydata.sqlite --export md >> CLAUDE.md   # the schema, as a committed brief
+npx tablewalk postgres://… --lint --fail-on high        # what the shape costs, for CI
+npx tablewalk --config ./tablewalk.json --diff staging # is staging the same shape?
+```
+
+No config file, no saved connection, no schema to define first. Point it at a
+database and it reads the catalog on connect.
+
+Or point it at nothing. `npx tablewalk` on its own starts the server and the
+page asks for a connection — a form that takes either a URL or its parts, tests
+it before keeping it, and can read the password from an environment variable or
+the keychain instead of the string. A connection added that way lasts for the
+session; "Save to file…" writes it down, with any typed password moved to the
+keychain rather than into the file.
+
+The commands that print and exit still need a target, because there is nothing
+for `--export`, `--lint` or `--diff` to read without one, and `--mcp` does too:
+an agent on stdio has no dialog to fill in.
+
+## The idea
+
+Every database client shows you tables. The interesting structure is the
+edges — and specifically the direction almost nothing surfaces well:
+
+> I am looking at this customer. **What points at it?**
+
+Foreign keys are stored once and readable in both directions, so the answer is
+already sitting in `information_schema`. tablewalk computes it for the row you
+are looking at, counts the referring rows in each table, and lets you click
+through to them.
+
+That turns a database from a list into something you can walk:
+
+```
+customer › Harbour Freight › invoice customer_id = 1 › 1001 › invoice_line …
+```
+
+Each step is a real filter you can see and edit, and walking back restores the
+filter you walked away from — which is the detail most browsers lose.
+
+## The query language
+
+The bar at the top takes a small language. The table comes first, because that
+is how people say it out loud; everything else is optional.
+
+```
+customer active = true sort credit_limit desc
+invoice invoice_date = last 30 days
+employee title contains manager show first_name, last_name
+customer country_code in (AU, NZ) and email is not empty
+invoice where total >= 500 order by total desc limit 20
+```
+
+| | |
+|---|---|
+| Operators | `= != < <= > >=`, `contains`, `startswith`, `endswith` (all three ignore case, on every engine), `in`, `not in` |
+| Null checks | `is empty`, `is not empty` |
+| Combining | `and`, `or`, parentheses |
+| Dates | `today`, `yesterday`, `this week`, `last month`, `last 30 days`, `next 7 days` |
+| Clauses | `filter` / `where`, `show` / `select`, `sort` / `order by`, `limit` |
+| Projection | `show a, b, c` — or `select`, if that reads better to you |
+
+Press **SQL** to see exactly what your query compiled to. The tool teaches the
+database rather than hiding it.
+
+### Counting things by something
+
+`by` turns a query into a breakdown — the GROUP BY question, in the same
+language and with the same guarantees. Measures first, then `by`, then what to
+group by:
+
+```
+invoice count by status
+invoice count, sum total as billed by month invoice_date sort billed desc limit 12
+invoice where total > 100 count by customer_id.country_code.name as country
+customer count distinct country_code as countries by active
+```
+
+| | |
+|---|---|
+| Measures | `count`, `count <column>` (skips its nulls), `count distinct <column>`, `sum`, `avg`, `min`, `max` |
+| Group keys | any column, or a reference path — up to three of them |
+| Periods | `by day \| month \| quarter \| year <date column>` |
+| Sorting | `sort <name>` names a column of the *answer*, key or measure |
+
+A period comes back as a label — `2026-08`, `2026-Q3` — spelled identically on
+SQLite, Postgres and MySQL, so it sorts correctly as text and means the same
+thing wherever you point the tool. Agents get this as the `breakdown` tool,
+which is the one to reach for before `sql`: every value is bound and every
+path is checked against the catalog.
+
+### Why not just let people type SQL?
+
+Because this language compiles to a *structure*, never to SQL text:
+
+```
+customer name = "O'Brien"
+        ↓
+{ groups: [[{ column: 'name', op: '=', value: "O'Brien" }]] }
+        ↓
+SELECT * FROM "customer" WHERE "name" = ?     ["O'Brien"]
+```
+
+There is no path from what you type to what the database parses as syntax.
+Every value arrives as a bound parameter. A tool that accepted raw SQL would
+have to either trust the input or write a SQL parser to distrust it; this
+sidesteps both by making the dangerous shape unrepresentable.
+
+Two things fall out of that for free:
+
+- **The compiler holds the schema.** `customer contry_code = AU` is an error
+  with a suggestion, not a database exception — and not, worse, an empty
+  result that looks like an empty table.
+- **Dates resolve to real timestamps.** `last 30 days` becomes two bound
+  values, identical in both dialects, visible in the explain panel.
+
+## One row, and everything about it
+
+Click a row and you get a record page: the fields, and — in a rail beside
+them — every table that points at this row, counted, ranked by how much there
+is to read. An empty relationship is shown as a zero rather than hidden,
+because "nothing points here through this" is an answer, and a rail that
+quietly dropped it could not be trusted to be the whole list.
+
+Records are named like a person would name them. A table with a `name`-like
+column uses it; a table whose name lives one-to-one away — `employee` carrying
+`party_id`, with the name on `party.display_name` — walks the reference and
+says `employee · Maeve Lindqvist` instead of `employee · 30`. The walk is the
+tool's whole idea, so it applies to headings and breadcrumbs too, and it
+deliberately stops at ownership: an invoice is never named after its customer,
+because forty invoices share that name and a label that identifies nothing is
+worse than a key.
+
+**Pages** go one step further: a composed view of one record — its fields,
+counts of what points at it, and lists of the rows themselves — laid out in
+sections you arrange. Every table gets a suggested page for free; **Layout**
+opens a builder where sections are added, hidden, filtered, resized and
+dragged into order, fields dragged into groups, and a to-one reference pulled
+in as its own block of fields. Values on a page render through the same module
+the record view uses, so a page you build never reads worse than the record it
+was built from.
+
+Related lists sit in a tab strip rather than stacked down the page, and only
+the tab you open is fetched — six things pointing at a record is otherwise six
+queries and a scroll. A run of lists is one strip and anything between two
+lists splits them, so dragging sections is how you decide what is a tab of
+what; the builder's "Lists as tabs" is the way out of it.
+
+Page view is sticky: from a page, a child row and a followed reference open as
+pages too, using whichever page you built for that table. In write mode the
+record's own fields become editors in place, through the same staging,
+statement preview and undo as the record view. Pin a page with the star beside
+its name and the home screen offers it — along with the records you were last
+looking at, and every page there is.
+
+**Check the shape** (⌘K, or the `···` menu) runs the same `lint` an agent and
+a build get, for the person who can actually add the index: keyless tables,
+foreign keys with nothing behind them, references with no delete rule,
+timestamps with no zone — grouped by table, each cost said once, and every
+heading opens the table it is about.
+
+**Find a value** (⌘K, or the `···` menu) answers the question you have when a
+string arrives from somewhere else and you cannot yet name the table it
+belongs to: it sweeps the text columns of every table — and uuid columns when
+the value is a whole uuid — grouped by table, with each match a row you can
+open. Bounded, and honest about it: it says which tables it could not read and
+where it stopped. It is the same `find` the MCP server offers, through the
+same endpoint, so the two cannot disagree about what a match is.
+
+Everything is a link. The URL carries the whole trail — connection, queries,
+rows, page — so a walk can be pasted into a ticket and arrive intact. A page
+is named in the link rather than identified: `/app/@customer-desk~1885`. The
+grammar is documented in the `?` help panel.
+
+## For coding agents: MCP
+
+The same machinery, offered to an agent:
+
+```bash
+npx tablewalk --mcp --config ./tablewalk.json   # speaks MCP on stdio
+```
+
+```json
+{ "mcpServers": { "tablewalk": { "command": "npx", "args": ["tablewalk", "--mcp", "--config", "./tablewalk.json"] } } }
+```
+
+Twenty-three tools. Reading everywhere: `refresh` (re-read the catalog after a migration — the schema is cached per open, and the error for an unknown table says when to call it), `schema_summary` (orientation in a few hundred
+tokens — hubs, event tables, the deepest reference chain), `tables`, `table`
+(columns, DDL, and foreign keys in **both** directions), `find` (where a name
+lives, across tables and columns), `query` (the query language, whose errors
+carry suggestions and the table's real columns — what lets an agent fix a
+mistake in one retry), `breakdown` (counts and sums grouped by something —
+`invoice count by month invoice_date`), `sql` (read-only, for whatever the
+language still cannot say), `record`
+(one row, its human name, and everything that points at it), `explain` (the
+planner's account of a statement without running it — feed a `query` answer's
+`sql` back verbatim), `profile` (what a column actually holds: null share,
+distinct count, range, the values that repeat), `lint` (what the shape will
+cost: keyless tables, unindexed references, naive timestamps),
+`change_impact` (what breaks if you change this table or column — asked
+*before* the migration is written: what points at it under which delete rule,
+whether those columns are NOT NULL, whether an index leads on them, and how
+many rows actually hold null, which is the fact that decides whether an
+`ALTER` succeeds), `diff` (whether
+two connections are still the same shape), `order` (what has to exist before
+what, and the reverse for teardown), `fixture` (a real row and the graph it belongs to, ready to replay into a test database), and `connections`. Every result carries a deep link the human beside the agent
+can open in the UI, and says what it cost: wall time and rows read.
+
+Writing only where your config says so. `insert`, `update`, `delete`,
+`insert_graph`, `delete_graph` and `revert` are offered only when a connection
+is marked `"writable": true` — a read-only server does not list tools it would
+refuse. `revert` undoes the last write behind the same two-call `confirm` gate
+`delete` uses; a `sql` write is recorded but marked unrevertible, because
+arbitrary SQL has no general inverse.
+`insert` answers with the row as the database stored it, defaults filled and
+key assigned; `delete` answers with its impact first — every table pointing at
+the row, counts, and `ON DELETE` rules — removing nothing until called again
+with `confirm: true`. Write answers carry `rowsInserted` / `rowsWritten` /
+`rowsDeleted`.
+
+A fixture is a graph, so `insert_graph` takes one: several related rows in one
+transaction, where either all of them land or none does. A row that cannot
+know its parent's key names it by label —
+
+```json
+[{"table": "country",  "as": "au", "values": {"code": "AU", "name": "Australia"}},
+ {"table": "customer", "as": "c1", "values": {"name": "Dry Creek", "country_code": {"ref": "au", "column": "code"}}},
+ {"table": "invoice",                "values": {"customer_id": {"ref": "c1"}, "total": 99.5}}]
+```
+
+— and `{"ref": "c1"}` resolves to that row's key *as the database assigned it*.
+The answer carries a `teardown` list, reversed, for `delete_graph`, which
+removes it the same way: one transaction, all or nothing. `fixture`'s output
+can be passed straight in as `tables`, which is the loop worth having — take a
+real row out of development, put it into a test database, tear it down after.
+
+Rows entering an agent's context leave the machine — point it at development
+databases. Where you want that enforced rather than remembered, mark a
+connection `"rows": false`: the catalog, row counts, null fractions, plans and
+`lint` still answer, and everything that would return a value out of a row
+refuses — at the adapter, so every endpoint and every tool at once. A server
+whose connections are all shape-only does not list `query`, `sql` or `record`
+at all.
+
+The shelf your team already keeps is readable too. Named queries and page
+definitions from your `tablewalk.json`, and pages saved from the browser, are
+served as MCP **resources** — `tablewalk://{connection}/queries` and
+`tablewalk://{connection}/pages` — beside the schema brief. Reading them does
+not run them; they are the questions your team decided were worth asking, in
+front of an agent that would otherwise re-derive them badly.
+
+And you can watch all of it: the **Agent console** (⌘K → "Agent console")
+drives the same tools by hand through the same code path, showing each
+answer exactly as an agent receives it — stats, token cost, and the deep
+links back into the UI.
+
+## A config file, and a team's surfaces
+
+Everything above works with no config at all. A `tablewalk.json` earns its keep
+when you want several databases to hand, and when the interface a team agrees
+on should live in version control rather than in one person's browser.
+
+```json
+{
+  "connections": [
+    { "name": "app (local)", "url": "postgres://localhost/app", "schemas": ["public"] },
+    { "name": "production",  "url": "postgres://reader@prod/app", "rows": false },
+    { "name": "analytics",   "url": "postgres://user:pass@warehouse/an" },
+    { "name": "cache",       "url": "./var/cache.sqlite" }
+  ]
+}
+```
+
+The same file can name SQL statements your team should have to hand:
+
+```json
+{
+  "queries": [
+    {
+      "name": "Customers over their limit",
+      "sql": "select c.name, sum(i.total) as invoiced from customer c join invoice i on i.customer_id = c.id group by c.id having sum(i.total) > c.credit_limit",
+      "description": "Where invoiced value has passed the agreed credit limit",
+      "connection": "app (local)"
+    }
+  ]
+}
+```
+
+They appear above the SQL editor and in ⌘K. Leaving `connection` out offers the
+statement on every database, which is right for one about a schema several of
+them share and wrong for one about a table only production has. Statements you
+save in the browser sit in the same list; the only difference is that a
+committed one is not yours to delete.
+
+It can also carry the built surfaces, so the interface a team agrees on lives
+in version control rather than in one person's browser. Four sections, all
+optional:
+
+```json
+{
+  "views":   [{ "name": "Unpaid, biggest first", "connection": "app (local)",
+                "text": "invoice show id, total, status, customer_id.name as customer where status != paid sort total desc limit 50" }],
+
+  "pages":   [{ "name": "Customer desk", "base": "customer",
+                "sections": [
+                  { "kind": "fields", "title": "Account", "paths": ["name", "email", "country_code.name"], "columns": 2 },
+                  { "kind": "metric", "title": "Billed", "fn": "sum", "from": "invoice", "path": "customer_id", "column": "total", "width": "third" },
+                  { "kind": "list",   "title": "Invoices", "from": "invoice", "path": "customer_id", "limit": 10 }
+                ] }],
+
+  "layouts": [{ "table": "customer", "name": "Account desk",
+                "sections": [
+                  { "kind": "fields", "title": "Account", "paths": ["name", "email", "credit_limit"] },
+                  { "kind": "list",   "title": "Invoices", "from": "invoice", "path": "customer_id", "limit": 5,
+                    "orderBy": [{ "column": "invoice_date", "direction": "desc" }] }
+                ] }]
+}
+```
+
+A **view** is a saved filter in the query language. A **page** is a composed
+record — fields, counts and related lists — reached at `/{connection}/@page~id`.
+A **layout** is how the record view itself arranges one table, which used to be
+buildable only by clicking.
+
+A list section names its relationship as `from` and `path` — the child table
+and the column of it pointing back — or as `via`, the foreign key's constraint
+name. `via` is the real key, because a child can point at a parent twice and
+the column alone would not say which; the pair is resolved to it against the
+schema, and a pair that matches no relationship keeps its section and carries
+an error saying so rather than quietly disappearing.
+
+Committed layouts fill in for tables nobody has laid out here, and never over
+one somebody saved: a committed layout is the default a team starts from, and
+the copy in your browser is what you chose afterwards. A malformed entry in any
+of these stops the server and names the entry and the fix — a page that
+silently did not appear is a bug report that starts "I definitely wrote it".
+
+Looked for in `./tablewalk.json`, `./.tablewalk.json`, then
+`$XDG_CONFIG_HOME/tablewalk/connections.json`. They appear in a picker in the
+sidebar and are **opened lazily** — naming eight databases does not mean
+dialling eight databases. Connection strings stay on the server: the browser
+is sent an id, a name, a dialect and a redacted detail, never a password.
+
+## Credentials
+
+A connection string is a credential, so tablewalk tries hard not to hold one.
+The password can come from four places, tried in this order:
+
+| | |
+|---|---|
+| **Environment** | `"url": "postgres://app:${PROD_PASSWORD}@db/app"` — nothing is stored anywhere |
+| **OS keychain** | macOS, via the built-in `security` tool, addressed by connection name |
+| **Credentials file** | `$XDG_CONFIG_HOME/tablewalk/credentials.json`, **refused unless mode 0600** |
+| **Inline in the URL** | Works, and is reported in the UI, because it ends up in shell history |
+
+An unset `${VAR}` is an error rather than an empty expansion — otherwise you
+get an authentication failure that says nothing about the real cause.
+
+tablewalk deliberately does **not** encrypt its own secrets. Rolling
+encryption for a local tool means inventing key management, and a key stored
+next to the ciphertext it protects is obfuscation with extra steps. Every
+option above either delegates to something that already solves the problem or
+is explicit about being plaintext-on-disk with the permission discipline `ssh`
+and `psql` use.
+
+Connections added through the UI keep their password out of the stored URL:
+the secret goes to the keychain (or the 0600 file) and the URL that persists
+has no password in it. A connection list can be shared or committed without
+thinking about it.
+
+## Read-only, and meant
+
+- The SQLite handle is opened `readOnly`. Reaching past the query API entirely
+  still fails.
+- Postgres connections `SET default_transaction_read_only = on` and a 30s
+  statement timeout.
+- Writes exist only behind a per-connection `"writable": true` opt-in;
+  adding a row is a form the schema writes, and deleting one leads with its
+  impact. A write opens a *second* connection, so the one every read uses
+  stays read-only for the life of the process however much gets edited.
+- An update or a delete has to name the whole primary key, and the row is
+  counted on the read-only handle before anything is written: a key matching
+  anything other than exactly one row is refused rather than applied. The
+  danger in a cell editor was never injection.
+- Table names cannot be bound as parameters, so they are checked against the
+  catalog before being quoted into a statement.
+- Every read is bounded. There is no code path to an unlimited query: a
+  caller that omits a limit gets 20, one that asks for too many gets 100,000,
+  and one that sends nonsense gets 20 rather than `LIMIT NaN`.
+- Request bodies are capped at 256 KB.
+- The server binds `127.0.0.1` only. Listening on every interface would put
+  your database one shared network away from someone else's browser; `--host`
+  overrides it and says so at startup.
+- Connection strings never reach the client, in any response.
+
+There is a test asserting that `name = "'; DROP TABLE customer; --"` returns
+zero rows *and leaves the table standing*.
+
+## Databases
+
+| Dialect | Status | Notes |
+|---|---|---|
+| SQLite | Built in | Uses Node's own `node:sqlite`. No native module to compile. Reads and writes. |
+| Postgres | Supported | Needs `pg` (`npm install pg`). Reads `pg_catalog` for keys and row estimates. Reads and writes. |
+| MySQL / MariaDB | Supported | Needs `mysql2` (`npm install mysql2`). Reads `information_schema`. Reads and writes. |
+
+Adding a third is one file implementing `Adapter` — `introspect`, `query`,
+`count`, `close` — plus a case in `src/adapters/connect.ts`. The shared
+`buildWhere` handles the dangerous part, so an adapter never builds a
+predicate itself.
+
+## Options
+
+```
+tablewalk                     no target: serve, and ask for one in the browser
+tablewalk <target>            a SQLite file path, sqlite:<path>, or postgres:// URL
+  -d, --db <target>           the same thing, explicitly (or set DATABASE_URL)
+  -p, --port <n>              default 4111
+      --schema <name>         Postgres only; repeatable. Defaults to all user schemas.
+      --host <addr>           interface to bind (default 127.0.0.1)
+      --allowed-host <name>   also answer for this Host header; repeatable
+      --config <path>         read connections from this file
+      --no-config             ignore any config file
+      --open                  open a browser once the server is up
+      --mcp                   speak MCP on stdio instead of serving HTTP
+      --tools <name>          explore, migrate, seed, or full (the default)
+      --output-schema         advertise each tool's output shape in tools/list
+  -h, --help                  print this and stop
+  -v, --version               print the version and stop
+```
+
+An option it does not recognise is an error, not a shrug: `tablewalk --prot
+4111` says so rather than quietly serving the default port.
+
+`--tools` offers one job's worth of tools instead of all twenty-two. Most
+sessions are one job — an agent reading a schema does not need the graph
+writers, one seeding a fixture does not need `explain` — and the listing is a
+fixed cost paid on connect, before anything is asked. `connections` and
+`refresh` are in every profile: the first is the call to start with, the second
+is how an agent recovers from a schema that changed underneath it. A profile
+only ever *removes*, so a read-only connection given `seed` still lists no
+write tools.
+
+    full 5,579 · explore 2,737 · migrate 2,210 · seed 2,909 tokens
+
+`--output-schema` is off by default, and that default is a measurement. The
+tool listing is what every agent pays for on connect, before it has asked
+anything, and on a 66-table schema `outputSchema` was exactly half of it —
+about 4,300 tokens, of which one byte-identical `stats` block repeated across
+every tool is 1,200. It is optional in MCP and it is a contract rather than a
+prompt: most agents never read it, and the answers carry the same fields
+whether or not the shape was declared in advance. Turn it on for a client that
+validates `structuredContent` against the declaration.
+
+## What it will and will not answer
+
+Browsing is read-only unless a connection is marked writable, and the server
+enforces that — the padlock in the toolbar is the interface for a decision the
+server makes, not the decision itself.
+
+Every request is checked against the `Host` it arrived for, reads included.
+That is the defence against DNS rebinding: a page on a name an attacker
+controls, pointed at your loopback, is *same-origin* as far as the browser is
+concerned, so it can read what it asks for. tablewalk answers only on
+`localhost`, on the address it was bound to, and on any name given with
+`--allowed-host` — everything else gets a 403, including the page itself, so
+the attempt fails at the door rather than one fetch later.
+
+Requests that change something are checked twice more: the `Origin`, when the
+browser sends one, and the content type, because a form post is the one shape
+a cross-origin page can make without asking permission.
+
+Nothing here is authentication. Anyone who can reach the port and send the
+right `Host` can read the database. Bind to loopback — the default — and that
+is your own machine; bind wider and it is whoever else can reach you.
+
+## Docker, and a desktop app
+
+There is a Dockerfile and an Electron app in `desktop/`. Both are covered in
+[DEPLOY.md](DEPLOY.md), including the two things a container changes about the
+security model — binding `0.0.0.0` inside while publishing only to the host's
+loopback, and `--allowed-host` for reaching it by any name but `localhost`.
+
+## Keyboard
+
+The same table is in the app under `?` → **Keys the page listens for**, so it
+cannot drift out of reach of the person who needs it.
+
+| Key | |
+|---|---|
+| `h` | home — the schema, your work, the diagram |
+| `/` | focus the query bar |
+| `⌘/` | the query bar as a panel, with room to write in |
+
+The `···` menu carries **Theme** — match the system, always light, always
+dark — and the rows-per-page control lives with the pager.
+| `t` | focus the table filter |
+| `⌘K` | command palette: tables, pages, actions, recent queries |
+| `⌘B` | show or hide the table list |
+| `Backspace` or `⌘[` | walk back one step |
+| `?` | the query-language panel |
+| `Esc` | leave the field, or close what is open |
+
+Single keys work when the caret is not in a text field, and never through a
+dialog: the page under a modal is not taking keys.
+
+In a result grid: arrows move a cell cursor, `Enter` opens that row's record,
+`⌘C` copies the cell, `Home`/`End` jump to the first and last column.
+
+## Development
+
+```bash
+npm install
+npm test          # typecheck + import check + the unit suite, against real SQLite files
+npm run demo      # build a demo database and open it
+npm run build     # emit dist/, runnable by plain node
+```
+
+The demo database is generated from source in `test/make-demo-db.ts` rather
+than committed as a binary, so you can read what you are browsing. Its shape
+deliberately covers the things that are easy to get wrong: a self-referencing
+key, a composite key, a view, and a nullable reference.
+
+For something with weight to it, seed bulk data:
+
+```bash
+npx tsx test/make-demo-db.ts .demo/big.db --scale 2000   # ~87,000 rows, <1s
+```
+
+Seeding is deterministic — the same scale and seed always produce the same
+database, so a screenshot or a reported bug can be reproduced exactly. The
+small fixture is left untouched by default because the test suite asserts
+exact counts against it.
+
+The client is hand-written ES modules with no build step and no framework,
+because the promise is `npx tablewalk mydb.sqlite` and nothing else. A bundler
+in the pipeline would mean a `dist/` to keep current and a reason for the
+published package to drift from the source.
+
+## Licence
+
+MIT.