feat: pivot to Cursor for Data — dataset-understanding CLI + web verification

.github/workflows/ci.yml

@@ -6,12 +6,19 @@ on:
   pull_request:
     branches: [main]
 
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
 permissions:
   contents: read
 
 jobs:
   verify:
     runs-on: ubuntu-latest
+    container:
+      image: mcr.microsoft.com/playwright:v1.58.2-noble
+    timeout-minutes: 20
 
     steps:
       - name: Checkout
@@ -38,8 +45,9 @@ jobs:
       - name: Build
         run: npm run build
 
-      - name: Install Playwright browser
-        run: npx playwright install --with-deps chromium
+      - name: Run CLI tests
+        run: npm run test:cli
 
       - name: Run e2e tests
+        timeout-minutes: 10
         run: npm test -- --reporter=line

.gitignore

@@ -36,6 +36,9 @@ yarn-error.log*
 # generated wasm files
 /public/duckdb/
 
+# querypad CLI inspection artifacts
+.querypad/
+
 # vercel
 .vercel
 
@@ -51,7 +54,6 @@ yarn-error.log*
 
 # internal docs
 FEEDBACK.md
-ROADMAP-PHASE4.md
 DEMO.md
 docs/SHOW-HN.md
 

AGENTS.md

@@ -4,8 +4,27 @@
 This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
 <!-- END:nextjs-agent-rules -->
 
+## Product direction
+
+QueryPad is pivoting from "AI-powered SQL editor" to **Cursor for Data** — a
+local-first AI workspace that understands datasets (discovers relationships, builds
+semantic models) before generating SQL. See `ROADMAP.md` for the layered plan.
+
+## Two surfaces, one core
+
+- **Web app** (`src/app`, `src/components`) runs DuckDB-Wasm in the browser.
+- **CLI** (`src/cli`, `src/lib/duckdb-node`) runs native `@duckdb/node-api` in Node.
+- **Shared, engine-agnostic core** (`src/lib/discovery`, `src/lib/duckdb/sql-utils.ts`)
+  is consumed by both via a `QueryRunner` abstraction.
+- Node-only code (`src/lib/duckdb-node`, `src/cli`) must never be imported by app code,
+  or the native addon leaks into the browser bundle. `npm run check`'s build step
+  verifies this.
+
 ## Release and verification
 
 - Keep `package.json`, `package-lock.json`, and the latest `CHANGELOG.md` release version in sync.
-- Run `npm run check` after code/config changes, and `npm test` when UI behavior or e2e-covered flows change.
-- Do not commit demo video artifacts; use them as release/README upload assets.
+- Run `npm run check` after code/config changes.
+- Run `npm test` when UI behavior or e2e-covered flows change.
+- Run `npm run test:cli` when discovery/CLI logic changes.
+- Do not commit demo video artifacts or `.querypad/` inspection output; use the videos
+  as release/README upload assets.

CHANGELOG.md

@@ -3,6 +3,47 @@
 QueryPad is a web app, not an npm package. Version numbers mark GitHub release
 milestones and public product updates.
 
+## Unreleased
+
+### Web: Relationship Verification
+
+- New Relationships panel in the sidebar: runs the same discovery engine in the browser
+  (DuckDB-Wasm) and lists inferred joins with confidence and a per-signal "why"
+- Accept / Reject / Edit each relationship to curate the AI's assumptions; verdicts and
+  edits persist across refresh (IndexedDB)
+- Reuses the engine-agnostic `src/lib/discovery` core (no logic duplicated between CLI and web)
+
+### CLI: Dataset Understanding
+
+- New `querypad inspect <folder>` command that profiles a folder of data files and
+  infers foreign-key relationships with confidence scores
+- New `querypad ask "<question>" <folder>` command (AI Analyst): generates SQL using the
+  inferred relationships as context, runs it on DuckDB, and explains the result
+- `inspect` now builds a semantic model (named business entities with belongs_to/has_many)
+  and writes `.querypad/semantic-model.yaml`; `ask` feeds those entities as context too
+- New `querypad explain <folder>` command: justifies each inferred relationship from its
+  signals (value overlap, name match, type, cardinality) and lists caveats to verify
+- Generated SQL is read-only-gated (only SELECT/WITH/EXPLAIN/… execute) and code-fence stripped
+- CLI AI keys come from `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`; provider via `--provider`
+- Writes `.querypad/` artifacts (`schema.json`, `relationships.json`, `inspect-summary.md`)
+  for AI agents such as Claude Code to reason about the dataset
+- Engine-agnostic discovery core shared between the browser app and the Node CLI
+- Runs on a native Node DuckDB engine (`@duckdb/node-api`), separate from the browser Wasm engine
+
+### Multi-Provider BYOK
+
+- OpenAI BYOK support for the Cmd+K AI SQL assistant via the Responses API
+- Provider selector for Claude and OpenAI with independent browser-local keys
+- Updated the default Claude model to `claude-sonnet-4-6`
+- Added `gpt-5.5` as the default OpenAI model
+
+### Data Profile & Agent Context
+
+- On-demand data profile drawer for loaded tables
+- Column-level nulls, distinct counts, numeric ranges, averages, and top values
+- Copy Agent Context action for Codex, Claude Code, or other coding agents
+- README positioning updated around local-first OSS and the hosted demo
+
 ## v0.6 — Open-Source Release
 
 - Vercel Analytics integration

CONTRIBUTING.md

@@ -13,15 +13,38 @@ npm run dev
 
 The app will be available at `http://localhost:3000`.
 
+QueryPad has two surfaces sharing one engine-agnostic understanding core: a **web
+app** (DuckDB-Wasm in the browser) and a **CLI** (native `@duckdb/node-api` in Node).
+The product direction is **Cursor for Data** — understanding datasets (discovering
+relationships, building semantic models) before generating SQL. See
+[ROADMAP.md](ROADMAP.md).
+
 ## Project Structure
 
 ```
 src/
-  app/        # Next.js app router pages and API routes
-  components/ # React components
-  lib/        # Core logic (DuckDB, AI, utilities)
-  stores/     # Zustand state management
-  types/      # TypeScript type definitions
+  app/             # Next.js app router pages
+  components/      # React components (web app)
+  cli/             # querypad CLI: index.ts (dispatch), inspect.ts, artifacts.ts
+  lib/
+    discovery/     # engine-agnostic core: signals.ts (pure), relationships.ts
+    duckdb/        # browser DuckDB-Wasm: profile.ts, sql-utils.ts (shared)
+    duckdb-node/   # Node DuckDB: connection.ts, load.ts, profile.ts
+    ai/            # SQL generation, providers, BYOK key storage
+  stores/          # Zustand state management
+  types/           # TypeScript type definitions (incl. discovery.ts)
+test/              # Node test runner specs for discovery/CLI
+fixtures/data/     # sample related files for CLI inspection
+```
+
+> Node-only code (`src/cli`, `src/lib/duckdb-node`) must not be imported by app code —
+> it would pull the native DuckDB addon into the browser bundle.
+
+## Running the CLI
+
+```bash
+npm run querypad -- inspect ./fixtures/data
+# writes ./fixtures/data/.querypad/ (gitignored)
 ```
 
 ## How to Contribute
@@ -30,7 +53,7 @@ src/
 2. Create a feature branch (`git checkout -b feat/my-feature`)
 3. Make your changes
 4. Run the local checks (`npm run check`)
-5. Run the e2e tests (`npm test`)
+5. Run the e2e tests (`npm test`) for UI changes, and `npm run test:cli` for discovery/CLI changes
 6. Commit your changes
 7. Push to your fork and open a Pull Request