From 45f70ec662dc25fb5c44733f7f2bfb7d6b001138 Mon Sep 17 00:00:00 2001
From: kayvink <kayvink@users.noreply.github.com>
Date: Tue, 26 May 2026 18:14:34 +0200
Subject: [PATCH 1/4] Update .gitignore

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index 4baea79..02455f1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,6 +10,7 @@ dist/
 .claude/
 .cursor/
 .obsidian/
+CLAUDE.md
 ---
 # Keep lockfile out of the repo — biome's optionalDependencies need to
 # resolve at install time per platform, and a macOS-generated lockfile

From b36c75770ca87ea0bd5a584c12f4c3f2b0bb2103 Mon Sep 17 00:00:00 2001
From: kayvink <kayvink@users.noreply.github.com>
Date: Wed, 15 Jul 2026 14:26:24 +0200
Subject: [PATCH 2/4] feat: semantic dataset commands; retire raw `buron query`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace ad-hoc GAQL/SQL with pick-based querying against the app's semantic
datasets:
- buron datasets list|describe|query (-m/-d/-f field:op:value/--from/--to/
  --granularity/--sort/--limit/--spec)
- buron sql <select> — read-only warehouse escape hatch
- buron queries create --spec (structured SemanticQuery, replaces -s/-q raw
  strings); queries list --dataset; run returns the QueryResult envelope
- buron dashboards add <dashboardId> <queryId>
- --json everywhere for scripting
- DELETE buron query (raw GAQL) — targets the retired /api/v1/query
Types mirror the app's SemanticQuery contract; server validates. tsc 0, biome
clean, build green. Bumped to 0.3.0 (breaking).
---
 README.md            |  30 ++++-
 package.json         |   2 +-
 src/bin.ts           |  72 +++++++++--
 src/commands/data.ts | 283 +++++++++++++++++++++++++++++++++++++------
 src/lib/api.ts       | 106 +++++++++++++---
 5 files changed, 420 insertions(+), 73 deletions(-)

diff --git a/README.md b/README.md
index 7f0563c..589bd67 100644
--- a/README.md
+++ b/README.md
@@ -94,6 +94,24 @@ Installed by `buron setup` into every editor folder you select.
 | `buron file move <from> <to>` | Move or rename a file |
 | `buron file replace <path>` | Find and replace text in a file |
 
+#### Data
+
+You query by picking metrics, dimensions, and filters from a dataset — there is no query language. Add `--json` to any read command for pipeable output.
+
+| Command | Purpose |
+|---------|---------|
+| `buron datasets list` | List datasets this team can query, with availability |
+| `buron datasets describe <id>` | Show a dataset's metrics, dimensions, and filter operators |
+| `buron datasets query <id>` | Run a query (`-m` measures, `-d` dimensions, `-f field:op:value`, `--from/--to/--granularity`, `--sort`, `--limit`, or `--spec <file\|->`) |
+| `buron sql <statement>` | Read-only SELECT against your warehouse (escape hatch; prefer `datasets query`) |
+| `buron queries list` | List saved queries (`--dataset <id>` to filter) |
+| `buron queries create <name> --spec <file\|->` | Save a structured query from a SemanticQuery spec |
+| `buron queries run <id>` | Run a saved query and return fresh results |
+| `buron dashboards list` | List available dashboards |
+| `buron dashboards run <id> --from --to` | Run a dashboard for a date range |
+| `buron dashboards add <dashboardId> <queryId>` | Add a saved query as a tile on a custom dashboard |
+| `buron integration <provider>` | Check an integration's connection status |
+
 #### Skills
 
 | Command | Purpose |
@@ -113,10 +131,14 @@ buron file read /wiki/launches/2025-05-onboarding-flow/blog.md \
 buron file read /wiki/launches/2025-05-onboarding-flow/changelog.md \
   > CHANGELOG.md
 
-# Check which ad creatives are performing best before a redesign
-buron query "SELECT ad_group_ad.ad.name, metrics.conversions, metrics.cost_micros
-  FROM ad_group_ad WHERE segments.date DURING LAST_30_DAYS
-  ORDER BY metrics.conversions DESC LIMIT 10" --source gaql
+# Discover what data you can query, then pick fields — no query language
+buron datasets list
+buron datasets describe cross-channel-ads
+
+# Which ad creatives are performing best before a redesign
+buron datasets query cross-channel-ads \
+  -m cost,conversions -d ad_name \
+  --from 2026-06-01 --to 2026-06-30 --sort conversions:desc --limit 10
 
 # See what competitors are doing
 buron file grep "positioning" --directory /wiki/entities/competitors/
diff --git a/package.json b/package.json
index 5f2201e..cdf5586 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@buron/cli",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Turn code changes into launch-ready marketing. Capture what you ship, and let Buron's agents generate content, update campaigns, and track performance.",
   "type": "module",
   "bin": {
diff --git a/src/bin.ts b/src/bin.ts
index 9b55095..f5422d1 100644
--- a/src/bin.ts
+++ b/src/bin.ts
@@ -1,12 +1,16 @@
 import { Command } from "commander";
 import {
+  dashboardsAddCommand,
   dashboardsListCommand,
   dashboardsRunCommand,
+  datasetsDescribeCommand,
+  datasetsListCommand,
+  datasetsQueryCommand,
   integrationCommand,
   queriesCreateCommand,
   queriesListCommand,
   queriesRunCommand,
-  queryCommand,
+  sqlCommand,
 } from "./commands/data.js";
 import {
   fileAppendCommand,
@@ -107,15 +111,47 @@ file
   .option("-a, --all", "Replace all occurrences (default: first only)")
   .action(fileReplaceCommand);
 
-// ── query ───────────────────────────────────────────────────────────
+// ── datasets ────────────────────────────────────────────────────────
 
-program
-  .command("query <queryString>")
-  .description("Execute an ad-hoc query against a connected data source")
-  .requiredOption("-s, --source <source>", "Query source (e.g. gaql)")
+function collect(value: string, previous: string[]): string[] {
+  return previous.concat([value]);
+}
+
+const datasets = program.command("datasets").description("Discover and query your data");
+
+datasets
+  .command("list")
+  .description("List datasets this team can query, with availability")
+  .option("--json", "Output raw JSON")
+  .action(datasetsListCommand);
+
+datasets
+  .command("describe <id>")
+  .description("Show a dataset's metrics, dimensions, and filter operators")
+  .action(datasetsDescribeCommand);
+
+datasets
+  .command("query <id>")
+  .description("Run a query by picking measures, dimensions, and filters — no SQL")
+  .option("-m, --measures <a,b>", "Metric field keys (comma-separated)")
+  .option("-d, --dimensions <x,y>", "Dimension field keys (comma-separated)")
+  .option("-f, --filter <field:op:value>", "Filter (repeatable)", collect, [])
   .option("--from <date>", "Start date (YYYY-MM-DD)")
   .option("--to <date>", "End date (YYYY-MM-DD)")
-  .action(queryCommand);
+  .option("--granularity <grain>", "day|week|month|quarter|year")
+  .option("--sort <field:dir>", "Sort (repeatable)", collect, [])
+  .option("--limit <n>", "Max rows")
+  .option("--spec <file|->", "Full SemanticQuery JSON (overrides flags)")
+  .option("--json", "Output raw JSON")
+  .action(datasetsQueryCommand);
+
+// ── sql (warehouse escape hatch) ────────────────────────────────────
+
+program
+  .command("sql <statement>")
+  .description("Run a read-only SELECT against your warehouse (prefer datasets query)")
+  .option("--json", "Output raw JSON")
+  .action(sqlCommand);
 
 // ── queries ─────────────────────────────────────────────────────────
 
@@ -124,27 +160,32 @@ const queries = program.command("queries").description("Manage saved queries");
 queries
   .command("list")
   .description("List saved queries")
-  .option("-s, --source <source>", "Filter by source")
+  .option("--dataset <id>", "Filter by dataset id")
+  .option("--json", "Output raw JSON")
   .action(queriesListCommand);
 
 queries
   .command("create <name>")
-  .description("Create a saved query")
-  .requiredOption("-s, --source <source>", "Query source (e.g. gaql)")
-  .requiredOption("-q, --query <queryString>", "The query string")
-  .option("--config <json>", "Chart/display config as JSON")
+  .description("Save a structured query from a SemanticQuery spec")
+  .requiredOption("--spec <file|->", "SemanticQuery JSON (dataset + picks)")
+  .option("--chart <kind>", "table|line|bar|area|donut")
   .action(queriesCreateCommand);
 
 queries
   .command("run <id>")
   .description("Execute a saved query and return fresh results")
+  .option("--json", "Output raw JSON")
   .action(queriesRunCommand);
 
 // ── dashboards ──────────────────────────────────────────────────────
 
 const dashboards = program.command("dashboards").description("View and run dashboards");
 
-dashboards.command("list").description("List available dashboards").action(dashboardsListCommand);
+dashboards
+  .command("list")
+  .description("List available dashboards")
+  .option("--json", "Output raw JSON")
+  .action(dashboardsListCommand);
 
 dashboards
   .command("run <id>")
@@ -154,6 +195,11 @@ dashboards
   .option("--fresh", "Bypass cache")
   .action(dashboardsRunCommand);
 
+dashboards
+  .command("add <dashboardId> <queryId>")
+  .description("Add a saved query as a tile on a custom dashboard")
+  .action(dashboardsAddCommand);
+
 // ── integration ─────────────────────────────────────────────────────
 
 program
diff --git a/src/commands/data.ts b/src/commands/data.ts
index e29820e..391431a 100644
--- a/src/commands/data.ts
+++ b/src/commands/data.ts
@@ -1,4 +1,4 @@
-import { api } from "../lib/api.js";
+import { api, type SemanticQuery } from "../lib/api.js";
 import { requireAuth } from "../lib/auth.js";
 import { requireConfig } from "../lib/config.js";
 import { blank, error, info, success } from "../lib/ui.js";
@@ -9,33 +9,212 @@ function fail(message: string): never {
   process.exit(1);
 }
 
-// ── query ───────────────────────────────────────────────────────────
+function printJson(value: unknown): void {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+/** Read a --spec value: a JSON string, a file path, or `-` for stdin. */
+async function readSpec(value: string): Promise<SemanticQuery> {
+  let raw = value;
+  if (value === "-") {
+    raw = await readStdin();
+  } else if (!value.trim().startsWith("{")) {
+    const { readFile } = await import("node:fs/promises");
+    raw = await readFile(value, "utf8");
+  }
+  try {
+    return JSON.parse(raw) as SemanticQuery;
+  } catch {
+    return fail("--spec must be a JSON object, a path to one, or - for stdin");
+  }
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", reject);
+  });
+}
+
+function splitList(value?: string): string[] | undefined {
+  if (!value) return undefined;
+  const items = value
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return items.length ? items : undefined;
+}
+
+/** Parse repeatable `-f field:op:value` (value comma-split for one_of). */
+function parseFilters(raw?: string[]): SemanticQuery["filters"] {
+  if (!raw || raw.length === 0) return undefined;
+  return raw.map((item) => {
+    const first = item.indexOf(":");
+    const second = item.indexOf(":", first + 1);
+    if (first === -1 || second === -1) {
+      fail(`Bad filter "${item}". Use field:op:value (e.g. device:equals:MOBILE)`);
+    }
+    const field = item.slice(0, first);
+    const op = item.slice(first + 1, second);
+    const values = item
+      .slice(second + 1)
+      .split(",")
+      .map((v) => v.trim());
+    return { field, op, value: values.length > 1 ? values : values[0] };
+  });
+}
+
+/** Parse repeatable `--sort field:dir`. */
+function parseSort(raw?: string[]): SemanticQuery["orderBy"] {
+  if (!raw || raw.length === 0) return undefined;
+  return raw.map((item) => {
+    const [field, dir] = item.split(":");
+    return { field, dir: dir === "desc" ? "desc" : "asc" };
+  });
+}
+
+/** Render a wire QueryResult ({columns, rows} or {notReady}/{error}) as text. */
+function printResult(result: unknown): void {
+  const r = result as {
+    columns?: Array<{ label: string }>;
+    rows?: unknown[][];
+    rowCount?: number;
+    truncated?: boolean;
+    notReady?: { reason: string; action: string };
+    error?: { message: string; suggestions?: string[] };
+  };
+  if (r.error) {
+    const hint = r.error.suggestions?.length ? `\n  try: ${r.error.suggestions.join(", ")}` : "";
+    fail(`${r.error.message}${hint}`);
+  }
+  if (r.notReady) {
+    blank();
+    info(`Not ready (${r.notReady.reason}): ${r.notReady.action}`);
+    return;
+  }
+  if (!(r.columns && r.rows)) {
+    printJson(result);
+    return;
+  }
+  const rows = r.rows;
+  const header = r.columns.map((c) => c.label);
+  const widths = header.map((h, i) =>
+    Math.max(h.length, ...rows.map((row) => String(row[i] ?? "").length)),
+  );
+  const line = (cells: unknown[]) =>
+    cells.map((c, i) => String(c ?? "").padEnd(widths[i])).join("  ");
+  blank();
+  process.stdout.write(`${line(header)}\n`);
+  for (const row of rows) process.stdout.write(`${line(row)}\n`);
+  blank();
+  const note = r.truncated ? " (truncated — narrow the range or lower the limit)" : "";
+  info(`${r.rowCount ?? rows.length} rows${note}`);
+}
+
+// ── datasets list ───────────────────────────────────────────────────
+
+export async function datasetsListCommand(options: { json?: boolean }): Promise<void> {
+  try {
+    const auth = requireAuth();
+    const config = requireConfig();
+    const { datasets } = await api.data.listDatasets(config.orgId, config.teamId, auth.token);
+    if (options.json) {
+      printJson(datasets);
+      return;
+    }
+    if (datasets.length === 0) {
+      blank();
+      info("No datasets");
+      return;
+    }
+    blank();
+    for (const d of datasets) {
+      const tier = d.live ? "live" : "warehouse";
+      const avail = d.availability.available
+        ? "ready"
+        : `unavailable — ${d.availability.reason ?? "not ready"}`;
+      process.stdout.write(
+        `${d.id.padEnd(28)} ${d.family.padEnd(14)} ${tier.padEnd(10)} ${avail}\n`,
+      );
+    }
+  } catch (err) {
+    fail(err instanceof Error ? err.message : "Unknown error");
+  }
+}
+
+// ── datasets describe ───────────────────────────────────────────────
 
-export async function queryCommand(
-  queryString: string,
+export async function datasetsDescribeCommand(id: string): Promise<void> {
+  try {
+    const auth = requireAuth();
+    const result = await api.data.describeDataset(id, auth.token);
+    printJson(result);
+  } catch (err) {
+    fail(err instanceof Error ? err.message : "Unknown error");
+  }
+}
+
+// ── datasets query ──────────────────────────────────────────────────
+
+export async function datasetsQueryCommand(
+  id: string,
   options: {
-    source: string;
+    measures?: string;
+    dimensions?: string;
+    filter?: string[];
     from?: string;
     to?: string;
+    granularity?: string;
+    sort?: string[];
+    limit?: string;
+    spec?: string;
+    json?: boolean;
   },
 ): Promise<void> {
   try {
     const auth = requireAuth();
     const config = requireConfig();
+    const query: SemanticQuery = options.spec
+      ? await readSpec(options.spec)
+      : {
+          measures: splitList(options.measures),
+          dimensions: splitList(options.dimensions),
+          filters: parseFilters(options.filter),
+          dateRange:
+            options.from && options.to
+              ? { from: options.from, to: options.to, granularity: options.granularity }
+              : undefined,
+          orderBy: parseSort(options.sort),
+          limit: options.limit ? Number(options.limit) : undefined,
+        };
+    const result = await api.data.queryDataset(config.orgId, config.teamId, id, query, auth.token);
+    if (options.json) {
+      printJson(result);
+      return;
+    }
+    printResult(result);
+  } catch (err) {
+    fail(err instanceof Error ? err.message : "Unknown error");
+  }
+}
 
-    const dateRange =
-      options.from && options.to ? { from: options.from, to: options.to } : undefined;
+// ── sql (warehouse escape hatch) ────────────────────────────────────
 
-    const result = await api.data.query(
-      config.orgId,
-      config.teamId,
-      options.source,
-      queryString,
-      auth.token,
-      dateRange,
-    );
-    process.stdout.write(JSON.stringify(result, null, 2));
-    process.stdout.write("\n");
+export async function sqlCommand(sql: string, options: { json?: boolean }): Promise<void> {
+  try {
+    const auth = requireAuth();
+    const config = requireConfig();
+    const result = await api.data.warehouseSql(config.orgId, config.teamId, sql, auth.token);
+    if (options.json) {
+      printJson(result);
+      return;
+    }
+    printResult(result);
   } catch (err) {
     fail(err instanceof Error ? err.message : "Unknown error");
   }
@@ -43,23 +222,30 @@ export async function queryCommand(
 
 // ── queries list ────────────────────────────────────────────────────
 
-export async function queriesListCommand(options: { source?: string }): Promise<void> {
+export async function queriesListCommand(options: {
+  dataset?: string;
+  json?: boolean;
+}): Promise<void> {
   try {
     const auth = requireAuth();
     const config = requireConfig();
-    const result = await api.data.listQueries(
+    const { queries } = await api.data.listQueries(
       config.orgId,
       config.teamId,
       auth.token,
-      options.source,
+      options.dataset,
     );
-    if (result.queries.length === 0) {
+    if (options.json) {
+      printJson(queries);
+      return;
+    }
+    if (queries.length === 0) {
       blank();
       info("No saved queries");
       return;
     }
-    for (const q of result.queries) {
-      process.stdout.write(`${q.id}  ${q.source}  ${q.name}\n`);
+    for (const q of queries) {
+      process.stdout.write(`${q.id}  ${(q.dataset ?? q.kind).padEnd(24)}  ${q.name}\n`);
     }
   } catch (err) {
     fail(err instanceof Error ? err.message : "Unknown error");
@@ -70,25 +256,25 @@ export async function queriesListCommand(options: { source?: string }): Promise<
 
 export async function queriesCreateCommand(
   name: string,
-  options: { source: string; query: string; config?: string },
+  options: { spec: string; chart?: string },
 ): Promise<void> {
   try {
     const auth = requireAuth();
     const config = requireConfig();
-    const parsedConfig = options.config
-      ? (JSON.parse(options.config) as Record<string, unknown>)
-      : undefined;
+    const query = await readSpec(options.spec);
+    const viz = options.chart ? { chart: options.chart } : undefined;
     const result = await api.data.createQuery(
       config.orgId,
       config.teamId,
       name,
-      options.source,
-      options.query,
+      query,
       auth.token,
-      parsedConfig,
+      viz,
     );
+    const created = result as { id?: string; name?: string; error?: { message: string } };
+    if (created.error) fail(created.error.message);
     blank();
-    success(`Created query: ${result.name} (${result.id})`);
+    success(`Created query: ${created.name} (${created.id})`);
   } catch (err) {
     fail(err instanceof Error ? err.message : "Unknown error");
   }
@@ -96,13 +282,16 @@ export async function queriesCreateCommand(
 
 // ── queries run ─────────────────────────────────────────────────────
 
-export async function queriesRunCommand(id: string): Promise<void> {
+export async function queriesRunCommand(id: string, options: { json?: boolean }): Promise<void> {
   try {
     const auth = requireAuth();
     const config = requireConfig();
     const result = await api.data.runQuery(config.orgId, config.teamId, id, auth.token);
-    process.stdout.write(JSON.stringify(result, null, 2));
-    process.stdout.write("\n");
+    if (options.json) {
+      printJson(result);
+      return;
+    }
+    printResult(result);
   } catch (err) {
     fail(err instanceof Error ? err.message : "Unknown error");
   }
@@ -110,11 +299,15 @@ export async function queriesRunCommand(id: string): Promise<void> {
 
 // ── dashboards list ─────────────────────────────────────────────────
 
-export async function dashboardsListCommand(): Promise<void> {
+export async function dashboardsListCommand(options: { json?: boolean }): Promise<void> {
   try {
     const auth = requireAuth();
     const config = requireConfig();
     const result = await api.data.listDashboards(config.orgId, config.teamId, auth.token);
+    if (options.json) {
+      printJson(result.dashboards);
+      return;
+    }
     if (result.dashboards.length === 0) {
       blank();
       info("No dashboards");
@@ -147,8 +340,21 @@ export async function dashboardsRunCommand(
       auth.token,
       options.fresh,
     );
-    process.stdout.write(JSON.stringify(result, null, 2));
-    process.stdout.write("\n");
+    printJson(result);
+  } catch (err) {
+    fail(err instanceof Error ? err.message : "Unknown error");
+  }
+}
+
+// ── dashboards add ──────────────────────────────────────────────────
+
+export async function dashboardsAddCommand(dashboardId: string, queryId: string): Promise<void> {
+  try {
+    const auth = requireAuth();
+    const config = requireConfig();
+    await api.data.addDashboardPanel(config.orgId, config.teamId, dashboardId, queryId, auth.token);
+    blank();
+    success(`Added query ${queryId} to dashboard ${dashboardId}`);
   } catch (err) {
     fail(err instanceof Error ? err.message : "Unknown error");
   }
@@ -161,8 +367,7 @@ export async function integrationCommand(provider: string): Promise<void> {
     const auth = requireAuth();
     const config = requireConfig();
     const result = await api.data.getIntegration(config.orgId, config.teamId, provider, auth.token);
-    process.stdout.write(JSON.stringify(result, null, 2));
-    process.stdout.write("\n");
+    printJson(result);
   } catch (err) {
     fail(err instanceof Error ? err.message : "Unknown error");
   }
diff --git a/src/lib/api.ts b/src/lib/api.ts
index a3f18a9..1ad4b7d 100644
--- a/src/lib/api.ts
+++ b/src/lib/api.ts
@@ -386,16 +386,36 @@ export const api = {
   // ── Data API ──
 
   data: {
-    async query(
+    async listDatasets(orgId: string, teamId: string, token: string): Promise<DatasetListResponse> {
+      const params = new URLSearchParams({ teamId, orgId });
+      return request<DatasetListResponse>("GET", `/api/v1/datasets?${params}`, { token });
+    },
+
+    async describeDataset(id: string, token: string): Promise<unknown> {
+      return request<unknown>("GET", `/api/v1/datasets/${encodeURIComponent(id)}`, { token });
+    },
+
+    async queryDataset(
       orgId: string,
       teamId: string,
-      source: string,
-      query: string,
+      id: string,
+      query: SemanticQuery,
       token: string,
-      dateRange?: { from: string; to: string },
     ): Promise<unknown> {
-      return request<unknown>("POST", "/api/v1/query", {
-        body: { orgId, teamId, source, query, dateRange },
+      return request<unknown>("POST", `/api/v1/datasets/${encodeURIComponent(id)}/query`, {
+        body: { orgId, teamId, ...query },
+        token,
+      });
+    },
+
+    async warehouseSql(
+      orgId: string,
+      teamId: string,
+      sql: string,
+      token: string,
+    ): Promise<unknown> {
+      return request<unknown>("POST", "/api/v1/warehouse/sql", {
+        body: { orgId, teamId, sql },
         token,
       });
     },
@@ -404,10 +424,10 @@ export const api = {
       orgId: string,
       teamId: string,
       token: string,
-      source?: string,
+      dataset?: string,
     ): Promise<QueryListResponse> {
       const params = new URLSearchParams({ teamId, orgId });
-      if (source) params.set("source", source);
+      if (dataset) params.set("dataset", dataset);
       return request<QueryListResponse>("GET", `/api/v1/queries?${params}`, { token });
     },
 
@@ -415,13 +435,12 @@ export const api = {
       orgId: string,
       teamId: string,
       name: string,
-      source: string,
-      query: string,
+      query: SemanticQuery,
       token: string,
-      config?: Record<string, unknown>,
+      viz?: Record<string, unknown>,
     ): Promise<SavedQueryResponse> {
       return request<SavedQueryResponse>("POST", "/api/v1/queries", {
-        body: { orgId, teamId, name, source, query, config },
+        body: { orgId, teamId, name, query, viz },
         token,
       });
     },
@@ -431,6 +450,20 @@ export const api = {
       return request<unknown>("POST", `/api/v1/queries/${id}/run?${params}`, { token });
     },
 
+    async addDashboardPanel(
+      orgId: string,
+      teamId: string,
+      dashboardId: string,
+      queryId: string,
+      token: string,
+    ): Promise<unknown> {
+      return request<unknown>(
+        "POST",
+        `/api/v1/dashboards/${encodeURIComponent(dashboardId)}/panels`,
+        { body: { orgId, teamId, queryId }, token },
+      );
+    },
+
     async listDashboards(
       orgId: string,
       teamId: string,
@@ -472,13 +505,54 @@ export const api = {
 
 // ── Data API response types ──
 
+/**
+ * A semantic query — dataset + field picks. Mirrors the app's SemanticQuery
+ * wire contract (specs/2026-07-10-agent-semantic-datasets/contracts). The
+ * server validates; these types are display-level only.
+ */
+export interface SemanticQuery {
+  dataset?: string;
+  measures?: string[];
+  dimensions?: string[];
+  filters?: Array<{
+    field: string;
+    op: string;
+    value?: string | number | (string | number)[];
+    valueEnd?: string | number;
+    negated?: boolean;
+    logic?: "and" | "or";
+  }>;
+  dateRange?: { from: string; to: string; granularity?: string };
+  orderBy?: Array<{ field: string; dir: "asc" | "desc" }>;
+  limit?: number;
+}
+
+export interface DatasetSummary {
+  id: string;
+  name: string;
+  description: string;
+  family: string;
+  live: boolean;
+  availability: {
+    available: boolean;
+    reason?: string;
+    action?: string;
+    connectUrl?: string;
+  };
+}
+
+export interface DatasetListResponse {
+  datasets: DatasetSummary[];
+}
+
 export interface SavedQueryResponse {
   id: string;
   name: string;
-  source: string;
-  query: string;
-  config?: Record<string, unknown>;
-  createdAt?: string;
+  dataset: string | null;
+  kind: "structured" | "raw-sql";
+  query: SemanticQuery | null;
+  uri: string;
+  updatedAt?: string;
 }
 
 export interface QueryListResponse {

From 03e271009edc323a70a2cea42c158b439f90a2b0 Mon Sep 17 00:00:00 2001
From: kayvink <kayvink@users.noreply.github.com>
Date: Wed, 5 Aug 2026 18:07:09 +0200
Subject: [PATCH 3/4] fix: stop sending orgId on file and token calls

The server now derives the organization from the Team row and verifies the
caller's membership (requireCliTeamAccess), so orgId in the request body is
ignored. Sending it was never authorization - before the guard landed it was
the value the server trusted, which is what made a spoofed orgId a
cross-tenant read.

Drops the parameter from api.files.* and generateToken plus their call sites;
teamId alone identifies the target now. No behaviour change against a current
server, and older servers still accept these payloads because they read
orgId from the session first.

Leaves data.* (datasets, warehouse SQL) untouched: those endpoints do not
exist server-side yet, so their payload contract is still undecided.
---
 src/commands/file.ts | 16 +++++++---------
 src/lib/api.ts       | 35 +++++++++++------------------------
 2 files changed, 18 insertions(+), 33 deletions(-)

diff --git a/src/commands/file.ts b/src/commands/file.ts
index c779cdb..1e23456 100644
--- a/src/commands/file.ts
+++ b/src/commands/file.ts
@@ -40,7 +40,7 @@ export async function fileReadCommand(path: string): Promise<void> {
   try {
     const auth = requireAuth();
     const config = requireConfig();
-    const result = await api.files.read(config.orgId, config.teamId, path, auth.token);
+    const result = await api.files.read(config.teamId, path, auth.token);
     if (!result.found) {
       fail(`File not found: ${path}`);
     }
@@ -60,7 +60,7 @@ export async function fileWriteCommand(
     const auth = requireAuth();
     const config = requireConfig();
     const content = await resolveContent(options);
-    const result = await api.files.write(config.orgId, config.teamId, path, content, auth.token);
+    const result = await api.files.write(config.teamId, path, content, auth.token);
     blank();
     success(`Wrote ${result.bytes} bytes → ${result.path}`);
   } catch (err) {
@@ -78,7 +78,7 @@ export async function fileAppendCommand(
     const auth = requireAuth();
     const config = requireConfig();
     const content = await resolveContent(options);
-    const result = await api.files.append(config.orgId, config.teamId, path, content, auth.token);
+    const result = await api.files.append(config.teamId, path, content, auth.token);
     blank();
     success(`Appended → ${result.path} (${result.bytes} bytes total)`);
   } catch (err) {
@@ -92,7 +92,7 @@ export async function fileListCommand(directory?: string): Promise<void> {
   try {
     const auth = requireAuth();
     const config = requireConfig();
-    const result = await api.files.list(config.orgId, config.teamId, auth.token, directory);
+    const result = await api.files.list(config.teamId, auth.token, directory);
     if (result.files.length === 0) {
       blank();
       info(directory ? `No files in ${directory}` : "No files");
@@ -112,7 +112,7 @@ export async function fileGlobCommand(pattern: string): Promise<void> {
   try {
     const auth = requireAuth();
     const config = requireConfig();
-    const result = await api.files.glob(config.orgId, config.teamId, pattern, auth.token);
+    const result = await api.files.glob(config.teamId, pattern, auth.token);
     if (result.files.length === 0) {
       blank();
       info(`No files match ${pattern}`);
@@ -136,7 +136,6 @@ export async function fileGrepCommand(
     const auth = requireAuth();
     const config = requireConfig();
     const result = await api.files.grep(
-      config.orgId,
       config.teamId,
       pattern,
       auth.token,
@@ -162,7 +161,7 @@ export async function fileDeleteCommand(path: string): Promise<void> {
   try {
     const auth = requireAuth();
     const config = requireConfig();
-    const result = await api.files.delete(config.orgId, config.teamId, path, auth.token);
+    const result = await api.files.delete(config.teamId, path, auth.token);
     blank();
     success(`Deleted: ${result.path}`);
   } catch (err) {
@@ -176,7 +175,7 @@ export async function fileMoveCommand(from: string, to: string): Promise<void> {
   try {
     const auth = requireAuth();
     const config = requireConfig();
-    const result = await api.files.move(config.orgId, config.teamId, from, to, auth.token);
+    const result = await api.files.move(config.teamId, from, to, auth.token);
     blank();
     success(`Moved: ${from} → ${result.path}`);
   } catch (err) {
@@ -194,7 +193,6 @@ export async function fileReplaceCommand(
     const auth = requireAuth();
     const config = requireConfig();
     const result = await api.files.replace(
-      config.orgId,
       config.teamId,
       path,
       options.old,
diff --git a/src/lib/api.ts b/src/lib/api.ts
index 1ad4b7d..0d3c1a1 100644
--- a/src/lib/api.ts
+++ b/src/lib/api.ts
@@ -239,14 +239,10 @@ export const api = {
     });
   },
 
-  async generateToken(
-    orgId: string,
-    teamId: string,
-    token: string,
-  ): Promise<GenerateTokenResponse> {
+  async generateToken(teamId: string, token: string): Promise<GenerateTokenResponse> {
     if (isMockMode()) return mock.generateToken();
     return request<GenerateTokenResponse>("POST", "/api/v1/tokens", {
-      body: { orgId, teamId },
+      body: { teamId },
       token,
     });
   },
@@ -266,19 +262,17 @@ export const api = {
 
   files: {
     async read(
-      orgId: string,
       teamId: string,
       path: string,
       token: string,
     ): Promise<FileReadResponse> {
       return request<FileReadResponse>("POST", `/api/v1/teams/${teamId}/files/read`, {
-        body: { orgId, path },
+        body: { path },
         token,
       });
     },
 
     async write(
-      orgId: string,
       teamId: string,
       path: string,
       content: string,
@@ -286,63 +280,58 @@ export const api = {
       metadata?: Record<string, unknown>,
     ): Promise<FileWriteResponse> {
       return request<FileWriteResponse>("POST", `/api/v1/teams/${teamId}/files/write`, {
-        body: { orgId, path, content, metadata },
+        body: { path, content, metadata },
         token,
       });
     },
 
     async append(
-      orgId: string,
       teamId: string,
       path: string,
       content: string,
       token: string,
     ): Promise<FileWriteResponse> {
       return request<FileWriteResponse>("POST", `/api/v1/teams/${teamId}/files/append`, {
-        body: { orgId, path, content },
+        body: { path, content },
         token,
       });
     },
 
     async list(
-      orgId: string,
       teamId: string,
       token: string,
       directory?: string,
     ): Promise<FileListResponse> {
       return request<FileListResponse>("POST", `/api/v1/teams/${teamId}/files/list`, {
-        body: { orgId, directory },
+        body: { directory },
         token,
       });
     },
 
     async glob(
-      orgId: string,
       teamId: string,
       pattern: string,
       token: string,
     ): Promise<FileListResponse> {
       return request<FileListResponse>("POST", `/api/v1/teams/${teamId}/files/glob`, {
-        body: { orgId, pattern },
+        body: { pattern },
         token,
       });
     },
 
     async grep(
-      orgId: string,
       teamId: string,
       pattern: string,
       token: string,
       directory?: string,
     ): Promise<FileGrepResponse> {
       return request<FileGrepResponse>("POST", `/api/v1/teams/${teamId}/files/grep`, {
-        body: { orgId, pattern, directory },
+        body: { pattern, directory },
         token,
       });
     },
 
     async delete(
-      orgId: string,
       teamId: string,
       path: string,
       token: string,
@@ -350,25 +339,23 @@ export const api = {
       return request<{ deleted: boolean; path: string }>(
         "POST",
         `/api/v1/teams/${teamId}/files/delete`,
-        { body: { orgId, path }, token },
+        { body: { path }, token },
       );
     },
 
     async move(
-      orgId: string,
       teamId: string,
       from: string,
       to: string,
       token: string,
     ): Promise<{ path: string }> {
       return request<{ path: string }>("POST", `/api/v1/teams/${teamId}/files/move`, {
-        body: { orgId, from, to },
+        body: { from, to },
         token,
       });
     },
 
     async replace(
-      orgId: string,
       teamId: string,
       path: string,
       oldString: string,
@@ -377,7 +364,7 @@ export const api = {
       replaceAll?: boolean,
     ): Promise<FileWriteResponse> {
       return request<FileWriteResponse>("POST", `/api/v1/teams/${teamId}/files/replace`, {
-        body: { orgId, path, oldString, newString, replaceAll },
+        body: { path, oldString, newString, replaceAll },
         token,
       });
     },

From 682fb6847889f294339eeb81070839828c647515 Mon Sep 17 00:00:00 2001
From: kayvink <kayvink@users.noreply.github.com>
Date: Wed, 5 Aug 2026 18:12:17 +0200
Subject: [PATCH 4/4] style: collapse signatures left short by the orgId
 removal (biome)

---
 src/commands/file.ts |  7 +------
 src/lib/api.ts       | 25 ++++---------------------
 2 files changed, 5 insertions(+), 27 deletions(-)

diff --git a/src/commands/file.ts b/src/commands/file.ts
index 1e23456..4a848e8 100644
--- a/src/commands/file.ts
+++ b/src/commands/file.ts
@@ -135,12 +135,7 @@ export async function fileGrepCommand(
   try {
     const auth = requireAuth();
     const config = requireConfig();
-    const result = await api.files.grep(
-      config.teamId,
-      pattern,
-      auth.token,
-      options.directory,
-    );
+    const result = await api.files.grep(config.teamId, pattern, auth.token, options.directory);
     if (result.matches.length === 0) {
       blank();
       info("No matches");
diff --git a/src/lib/api.ts b/src/lib/api.ts
index 0d3c1a1..7df878b 100644
--- a/src/lib/api.ts
+++ b/src/lib/api.ts
@@ -261,11 +261,7 @@ export const api = {
   },
 
   files: {
-    async read(
-      teamId: string,
-      path: string,
-      token: string,
-    ): Promise<FileReadResponse> {
+    async read(teamId: string, path: string, token: string): Promise<FileReadResponse> {
       return request<FileReadResponse>("POST", `/api/v1/teams/${teamId}/files/read`, {
         body: { path },
         token,
@@ -297,22 +293,14 @@ export const api = {
       });
     },
 
-    async list(
-      teamId: string,
-      token: string,
-      directory?: string,
-    ): Promise<FileListResponse> {
+    async list(teamId: string, token: string, directory?: string): Promise<FileListResponse> {
       return request<FileListResponse>("POST", `/api/v1/teams/${teamId}/files/list`, {
         body: { directory },
         token,
       });
     },
 
-    async glob(
-      teamId: string,
-      pattern: string,
-      token: string,
-    ): Promise<FileListResponse> {
+    async glob(teamId: string, pattern: string, token: string): Promise<FileListResponse> {
       return request<FileListResponse>("POST", `/api/v1/teams/${teamId}/files/glob`, {
         body: { pattern },
         token,
@@ -343,12 +331,7 @@ export const api = {
       );
     },
 
-    async move(
-      teamId: string,
-      from: string,
-      to: string,
-      token: string,
-    ): Promise<{ path: string }> {
+    async move(teamId: string, from: string, to: string, token: string): Promise<{ path: string }> {
       return request<{ path: string }>("POST", `/api/v1/teams/${teamId}/files/move`, {
         body: { from, to },
         token,