@malloydata/malloyyo 0.2.27 → 0.2.29

package/dist/index.js

@@ -99,8 +99,8 @@ function resolveTarget(dir, name) {
 }
 function resolveInstance(dir, arg) {
   if (arg && /^https?:\/\//i.test(arg)) {
-    const url5 = normalizeUrl(arg);
-    return { name: url5, url: url5 };
+    const url6 = normalizeUrl(arg);
+    return { name: url6, url: url6 };
   }
   const targets = readTargetMap(dir);
   const entries = Object.entries(targets);
@@ -125,9 +125,9 @@ import { join as join2, relative, sep } from "node:path";
 import { execFileSync } from "node:child_process";
 
 // src/host.ts
-import fs from "node:fs";
-import path2 from "node:path";
-import url2 from "node:url";
+import fs2 from "node:fs";
+import path3 from "node:path";
+import url3 from "node:url";
 import {
   MalloyConfig,
   Runtime,
@@ -152,8 +152,8 @@ var contentFiles = {
   "dashboards/custom-components.md": '---\ndescription: Custom dashboard UI \u2014 a flat dashboards/<name>.jsx|tsx sibling composing @malloyyo/dashboard widgets/hooks/helpers with your own React\n---\n\n# Custom dashboard components (`dashboards/<name>.jsx`)\n\nThe default UI (auto-rendered controls + panel) covers most dashboards. When it\nisn\'t enough, add ONE file \u2014 a **flat sibling** `dashboards/<name>.jsx` (or\n`.tsx`) next to the dashboard\'s `dashboards/<name>.malloy` (same basename) \u2014 that\ncomposes the runtime\'s widgets/hooks with your own React. You own layout, copy,\nand theming; the `.malloy` file still owns every query and filter. See also\n`yo_help dashboards/authoring` and `dashboards/vega-charts`.\n\n```tsx\nimport React from "react";\nimport { Controls, Given, Search, Select, TimeRange, Panel, filters, useGiven } from "@malloyyo/dashboard";\n\nexport default function Dashboard({ dashboard, givens }) {\n  return (\n    <div style={{ maxWidth: 860, margin: "0 auto", padding: 24 }}>\n      <h1>{dashboard.title}</h1>\n      <Controls>\n        <Given name="STATE" />          {/* picks the control from the declaration */}\n        <Search given="NAME" />         {/* committing input + typeahead + validation */}\n        <TimeRange given="PERIOD" presets={[\n          { value: "", text: "All time" },\n          { value: filters.lastN(1, "day"), text: "Last day" },\n          { value: filters.lastN(1, "week"), text: "Last week" },\n          { value: filters.lastN(1, "month"), text: "Last month" },\n        ]} />                            {/* "Custom range\u2026" is always appended */}\n        <Select given="MIN_SAMPLE"\n          options={[10, 200, 1000].map(n => ({ value: filters.greaterThan(n), text: `> ${n}` }))} />\n      </Controls>\n      <Panel givens={givens} />         {/* the dashboard itself (its tiles/query) */}\n      <Panel query="baby_names -> births_by_decade" givens={givens} />  {/* a specific query */}\n    </div>\n  );\n}\n```\n\nFrom `@malloyyo/dashboard` (also handed to the component as props):\n- **Widgets** (headless-ish; restyle via className/style or the `--dash-*` CSS\n  vars \u2014 see Theming below): `<Controls/>` (all givens, or compose children;\n  grows Apply/Reset under `autorun=false`), `<Given name/>`,\n  `<Select given [options]/>`, `<Search given/>` (committing input + typeahead +\n  inline \u2715 clear), `<MultiSelect given [options]/>` (chip multi-select for a\n  `filter<string>` \u2014 commits an exact-match list via `filters.oneOf`),\n  `<Range given [min max]/>`, `<TimeRange given [presets]/>` (temporal presets +\n  custom range), `<Checkbox given/>` (bound to a boolean given),\n  `<VegaChart spec query|malloy|data givens/>` (a Vega-Lite chart over query\n  rows \u2014 see `yo_help dashboards/vega-charts`)\n- **Hooks**: `useGiven(name)` \u2192 {value, set, spec};\n  `useOptions(name, typed?)` \u2192 {options, loading} (typeahead);\n  `useQuery({query|malloy, givens})` \u2192 {rows, loading, error} \u2014 plain rows\n  for your own visuals;\n  `useUrlState(key, initial)` \u2192 [value, setValue] \u2014 shareable view-state (below)\n- **Helpers**: `filters.oneOf/contains/between/atLeast/\u2026` build\n  filter-expression strings with correct escaping; temporal:\n  `filters.lastN(7, "day")` \u2192 `\'7 days\'`, `filters.dateRange("2026-01-01",\n  "2026-07-01")`, `filters.afterDate/beforeDate`; read back with\n  `filters.values/numberRange/threshold/inLast/temporalRange`;\n  `filters.isValid(type, src)` checks typed input.\n  Never hand-concatenate a filter string.\n  **Escaping rule for custom controls:** a filter given\'s value is an\n  EXPRESSION, so committing a raw column value is wrong the moment it contains\n  a comma/percent/dash (\'Tesla, Inc.\' parses as two alternatives and matches\n  nothing). Commit `filters.oneOf(value)` (exact) or\n  `filters.contains(term)` (substring), and unwrap for display with\n  `filters.values(src)`. The stock `<Select/>` does this automatically;\n  `<Search/>` deliberately commits raw text (its input IS a filter\n  expression).\n- `<Panel/>` runs against the DASHBOARD\'s own file: a bare `<Panel/>` renders\n  the whole dashboard (its tiles); `<Panel query="\u2026"/>` runs a query defined in\n  the dashboard file (by name) or a `source -> view`; `<Panel malloy="\u2026"/>` and\n  `runData(text, givens)` run arbitrary Malloy as a RESTRICTED query (no import /\n  given: / connection.* / raw SQL / ##! flags \u2014 the model\'s governed surface\n  only). `lint` checks each hard-coded `query="\u2026"` still resolves.\n\n## Shareable view-state: `useUrlState`\n\n`useState` is invisible to the page that owns the URL, so a component built on\nit has an address bar that never changes \u2014 the result can\'t be shared or\nbookmarked. **`useUrlState(key, initial)` is a `useState` twin whose value lives\nin the URL**, under a `~key` param:\n\n```jsx\nimport { useUrlState } from "@malloyyo/dashboard";\n\nconst [rack,  setRack]  = useUrlState("rack", "");          // string\nconst [reuse, setReuse] = useUrlState("reuse", false);      // boolean\nconst [board, setBoard] = useUrlState("board", "........"); // string\nconst [topN,  setTopN]  = useUrlState("n", 20);             // number\n```\n\n- Same shape as `useState`: `[value, setValue]`, and `setValue` takes a value\n  **or** an updater fn (`setBoard(b => \u2026)`).\n- The value comes from the URL on load, else `initial`. Every change is written\n  back (debounced, `replaceState` \u2014 no history spam), so the address bar is\n  always a shareable link.\n- Typed by `initial`: string / number / boolean / any JSON-serializable value.\n  Strings stay readable in the URL (`~rack=retinas`); objects and arrays are\n  JSON. A value equal to `initial` is dropped from the URL, so defaults never\n  clutter it, and a malformed value falls back to `initial` instead of throwing.\n- Works identically in `malloyyo dashboard dev`, on a bundled static site, and\n  on a hosted instance \u2014 including inside the sandboxed iframe, which cannot\n  reach the top-level URL on its own. That\'s why this is a hook and not\n  something a component can do with `history.replaceState`.\n\n**Use it for view-state, not query parameters.** A `given:` is the governed,\nfilter-typed query contract: it\'s declared in the model, drives the default\ncontrols, and is visible over MCP \u2014 bind those with `useGiven` and they already\nround-trip through the URL as `$NAME`. `useUrlState` is for everything else a\ncustom component needs to make shareable: a letter rack whose real query inputs\n(allowed letters, min/max length) are computed from it in JS, a board layout, a\nmode toggle. The two namespaces (`$NAME` vs `~key`) never collide.\n\n## Theming\n\nEvery widget is styled by the runtime\'s **default Malloyyo theme** (system\nfont, neutral grays, blue accent, auto light/dark following the viewer\'s OS) \u2014\na bare component looks styled with zero effort, so DON\'T hand-hardcode\n`fontFamily`/colors. The theme is CSS custom properties; override any subset by\nsetting them on a wrapper element (more specific than the runtime\'s `:root`):\n\n```tsx\n<div style={{ "--dash-accent": "#e11d48", "--dash-controls-bg": "#faf5ff" }}>\n  <Controls /> \u2026\n</div>\n```\n\nVars: `--dash-font`, `--dash-bg`, `--dash-fg`, `--dash-muted`, `--dash-border`,\n`--dash-accent`, `--dash-accent-fg`, `--dash-control-bg`, `--dash-controls-bg`,\n`--dash-chip-bg`, `--dash-chip-fg`, `--dash-panel-bg`, `--dash-radius`,\n`--dash-danger`. `DefaultDashboard` also takes a `theme={{ accent, controlsBg }}`\nprop (camelCase keys \u2192 `--dash-*`). The results `<Panel>` keeps a light surface\nin both light/dark (the Malloy renderer has no dark theme) \u2014 override\n`--dash-panel-bg` if your renderer output is dark-safe.\n\n**Use `--dash-*` and nothing else.** A custom component renders in its own\n**iframe**, so CSS variables defined by the surrounding page \u2014 including the\nbundled site\'s `--line` / `--card` / `--muted` \u2014 are NOT in scope inside it. A\ncomponent styled against those still renders, but every rule referencing them\nresolves to nothing: borders, dividers and panel backgrounds vanish silently\nwhile text and layout survive, so the page looks *almost* right and the cause\nisn\'t obvious. If you\'re porting CSS that has to work both inside the frame and\non a bundled page, resolve each colour once through the chain and use the alias:\n\n```css\n.my-card {\n  --edge: var(--dash-border, var(--line, #e4e6eb));\n  --surface: var(--dash-panel-bg, var(--card, #fff));\n  border: 1px solid var(--edge);\n  background: var(--surface);\n}\n```\n\nThis is a class of bug `lint` cannot see and a screenshot can \u2014 look at custom\ncomponents in `malloyyo dashboard dev` before shipping them.\n\nFor charts beyond the Malloy renderer\'s `#` tags, use `<VegaChart>` \u2014\n`yo_help dashboards/vega-charts`.\n',
   "dashboards/givens-and-controls.md": "---\ndescription: Dashboard filter controls \u2014 declare filter<T> givens with # label / suggest / control tags; faceted (related) suggestions\n---\n\n# Dashboard givens & controls\n\nA dashboard's filters are `filter<T>` **givens** declared in the model; the\n`#` tags on each declaration drive its control. This is part of authoring a\ndashboard \u2014 see also `yo_help dashboards/authoring`.\n\n**Declare the filters as `filter<T>` givens** \u2014 never raw strings/numbers.\nA `filter<string>` value accepts one value ('NY'), alternatives ('NY, CA'),\nwildcards ('Ann%'), negation ('-NY'); a `filter<number>` accepts ranges\n('[1910 to 1930]') and comparisons ('> 200'); a `filter<timestamp>` /\n`filter<date>` accepts relative windows ('7 days' = the last 7 days, 'today',\n'last month') and literal ranges ('2026-01-01 to 2026-07-01' \u2014 NO `@` in\nfilter literals). Apply with `~`; `f''` = empty = no filter (the natural\n\"All\"/\"all time\" \u2014 just `col ~ $X`, no `$X = '' or \u2026` dance):\n\n```malloy\n##! experimental { givens }\ngiven:\n  # label=\"State\" control=select suggest { source=baby_names dimension=state }\n  STATE :: filter<string> is f'NY'\n  # label=\"Brand\" suggest { query=brand_suggest dimension=product_brand }\n  BRAND :: filter<string> is f''\n  # label=\"Names\" control=multiselect suggest { query=name_suggest dimension=name }\n  NAMES :: filter<string> is f''\n  # label=\"Years\" range_min=1910 range_max=2025\n  YEAR_RANGE :: filter<number> is f'[1910 to 1930]'\n  # label=\"Time period\"\n  PERIOD :: filter<timestamp> is f''\n  # label=\"Include rare names\"\n  INCLUDE_RARE :: boolean is false\n```\n\nTags on the declaration drive the control (tag syntax is `key=\"value\"` \u2014\nequals, not colon):\n- `label` \u2014 control caption (defaults to the given's name)\n- `suggest { \u2026 }` \u2014 where the control's options come from. NO Malloy code in\n  strings \u2014 just names:\n  - `suggest { query=brand_suggest dimension=product_brand }` \u2014 the FIRST\n    COLUMN of a named query (declare the query in the model \u2014 governed and\n    reviewable). PREFER THIS FORM. The query must be in scope where the dashboard\n    runs (bring it in with the dashboard file's bare `import`).\n  - `suggest { source=baby_names dimension=state }` \u2014 the DISTINCT VALUES of\n    a dimension on a source (the source must be in the dashboard's scope)\n  A `dimension` (in either form) is what enables SERVER-SIDE TYPEAHEAD: the\n  runtime refines the base query with what the user has typed\n  (`\u2026 + { where: lower(field) ~ f'll%'; limit: 50 }`, case-insensitive,\n  escaped). Without a dimension the fetched list is filtered client-side.\n  Runs as a restricted query; lint checks the declaration compiles.\n\n  **RELATED (faceted) filters** \u2014 query-form only: a suggest query may\n  reference the OTHER givens, and the runtime runs it with the dashboard's\n  current values (the suggested given itself is excluded, so the list never\n  collapses to the current pick). Brand suggestions narrow when Category is\n  set:\n\n  ```malloy\n  query: brand_suggest is inventory_items -> product_brand + {\n    where:\n      product_category ~ $CATEGORY,      // NOT product_brand ~ $BRAND\n      product_department ~ $DEPARTMENT\n    limit: 500\n  }\n  ```\n\n  Declare one `*_suggest` per filter, each referencing the others; `f''`\n  defaults mean unset filters don't constrain. `source=` suggests can't do\n  this (no place for a `where:`) \u2014 another reason to prefer `query=`.\n- `control=select` \u2014 a fixed dropdown instead of a typeahead search box\n- `control=multiselect` \u2014 a tokenized multi-select for a `filter<string>`:\n  each pick is a removable chip, the committed value is an exact-match list\n  (`Emma, Olivia, Sophia`). Ideal for \"pick several\" filters (names, brands).\n  Suggestions come from the given's `suggest {\u2026}` (server-side typeahead when\n  it names a dimension). Empty (start from `f''`) = no filter (all).\n- `range_min` / `range_max` \u2014 bounds; makes a filter<number> given a\n  dual-thumb range slider\n- anything else passes through in `spec.tags` for custom components\n\nControl picked from the declaration automatically: numeric range tags \u2192\ndual-thumb slider; `filter<timestamp|timestamptz|date>` \u2192 the TimeRange\nwidget (relative presets: Today / Last 7 days / Last 30 days / \u2026 plus a\n\"Custom range\u2026\" from/to date picker); `control=multiselect` \u2192 chip\nmulti-select; suggest + control=select \u2192 dropdown; boolean \u2192 checkbox;\nanything else \u2192 committing search box with typeahead (an inline \u2715 clears it;\na \"Press \u21B5 to apply\" hint shows while the typed draft differs from what's\nrunning \u2014 free text can't safely re-run per keystroke).\nThe suggest-driven options are DATA VALUES only \u2014 options that aren't column\nvalues (custom time presets, threshold buckets) need a custom component\n(`yo_help dashboards/custom-components`) with explicit `{value, text}` options\nwhere value is a filter expression built with `filters.*`.\n\n## When the query re-runs: live (default) vs. Apply\n\nBy default a dashboard is **live** \u2014 every control change re-runs the query\nimmediately (the committing search box is the exception: free text commits on\nEnter/blur, since a half-typed filter is invalid). To batch changes behind an\n**Apply** button instead, set `autorun=false` on the `# artifact` tag:\n\n```malloy\n# artifact { name=\"births-by-name\" title=\"Births by name\" autorun=false }\n```\n\n`autorun=false` makes `<Controls>` grow an Apply/Reset pair \u2014 controls edit a\ndraft and nothing re-runs until Apply. Reach for it when the query is expensive\nor several filters are usually changed together; leave it off (live) otherwise.\n",
   "dashboards/grid-layout.md": "---\ndescription: Dashboard grid layout \u2014 # dashboard {columns=N} with # colspan and # break to place KPI tiles and charts\n---\n\n# Dashboard grid layout (`# dashboard {columns=N}`)\n\nBy default a `# dashboard` result flows its KPI tiles and cards and wraps.\nAdd `{columns=N}` to place them on a fixed **N-column grid** instead \u2014 use\n`columns=6`, which divides evenly into 2- and 3-wide cards.\n\n**Key mechanic:** a tag placed ABOVE `aggregate:` or `nest:` applies to EVERY\nitem declared in that block. So you set card widths once per block, not per\nfield.\n\n```malloy\n# artifact { title=\"Customer Insights\" } dashboard {columns=6}\nview: customer_insights is {\n  where: created_at ~ $PERIOD\n  # colspan=2\n  aggregate: total_sales, user_count, order_count, average_order_value\n  # colspan=3\n  nest:\n    # break\n    # bar_chart\n    users_by_spend_tier\n    sales_by_traffic_source\n    # shape_map\n    sales_by_state\n    # colspan=6\n    recent_orders                      // wide detail table \u2192 full width\n}\n```\n\n## The conventions\n\n- **`# colspan=2` above `aggregate:`** \u2014 each KPI / measure tile spans 2 of 6\n  columns \u2192 3 tiles per row.\n- **`# colspan=3` above `nest:`** \u2014 each graph or small table spans 3 \u2192 2 per\n  row. Per-item render tags (`# line_chart`, `# bar_chart`, `# shape_map`) still\n  go on the individual nested items.\n- **`# colspan=6`** \u2014 a single wide / many-column table gets its own full-width\n  line. Tag that one item; a per-item `# colspan` overrides the block default.\n- **`# break` on the FIRST nest item** \u2014 starts the graphs on a fresh row, so\n  KPI tiles and charts never share one. The renderer splits fields into a new\n  grid at each `# break`. Just always add it: it's a no-op when the tiles\n  already fill complete rows, and the fix when they don't (e.g. 4 measures\n  leave a lone tile a colspan-3 chart would otherwise pack in beside).\n\n`# colspan` only does anything in columns mode \u2014 without `{columns=N}` the\nlayout is free-flow wrap and colspan is ignored. Clamp colspans to `1..N`.\n\nSee also `yo_help dashboards/vega-charts` for custom charts, and the fuller\nauthoring guide surfaced by the local `malloyyo mcp` server.\n",
-  "dashboards/vega-charts.md": '---\ndescription: Custom dashboard charts with Vega-Lite \u2014 the <VegaChart> component, for charts the # renderer tags can\'t do\n---\n\n# Custom charts with Vega-Lite (`<VegaChart>`)\n\nWhen Malloy\'s renderer tags (`# bar_chart`, `# line_chart`, `# shape_map`, \u2026)\ndon\'t cover the chart you want, a dashboard can draw a **Vega-Lite** spec with\nthe `<VegaChart>` component. The chart engine ships in the dashboard runtime, so\nyou author only a JSON spec + a Malloy query \u2014 no library to load.\n\n**It is a COMPONENT, not a `#` tag.** There is no `# vega_lite` or\n`# scatter_chart` tag. `<VegaChart>` lives in a custom component \u2014 a flat sibling\n`dashboards/<name>.jsx` (or `.tsx`) next to the dashboard\'s\n`dashboards/<name>.malloy` \u2014 a different layer from the `#` renderer tags. (The\ndashboard\'s query is declared in the `.malloy` file; the component only\ncustomizes presentation. Preview with `malloyyo dashboard dev`, validate with\n`malloyyo lint`.)\n\n## The recipe\n\n```tsx\nimport { VegaChart } from "@malloyyo/dashboard";\n\n// Encodings point at the query\'s OUTPUT COLUMN NAMES (here: name, births).\nconst spec = {\n  mark: { type: "bar", tooltip: true },\n  encoding: {\n    y: { field: "name", type: "nominal", sort: "-x" },\n    x: { field: "births", type: "quantitative" },\n  },\n};\n\nexport default function Dashboard({ givens }) {\n  return <VegaChart spec={spec} query="births_by_name" givens={givens} />;\n}\n```\n\nThree ways to feed it data:\n- `<VegaChart spec={spec} query="births_by_name" givens={givens}/>` \u2014 a query\n  defined in the dashboard\'s `.malloy` file (by name), or a `source -> view`\n- `<VegaChart spec={spec} malloy="source -> view" givens={givens}/>` \u2014 restricted\n  Malloy text (same governance as the explore surface: no import / given: /\n  connection.* / raw SQL / ##! flags)\n- `<VegaChart spec={spec} data={rows}/>` \u2014 rows you already have from `useQuery`\n\n## Gotchas (the ones that actually bite)\n\n- **Shape the data in Malloy; return FLAT rows.** Do ranking, share/percent\n  (`all(x, dim)`), and label lookups (a `pick` for month names) in the QUERY.\n  The spec just encodes columns \u2014 it is not the place to reshape data.\n- **Match column names character-for-character.** Run the query once with\n  `query(execute:true)` and read the exact output column names; the spec\'s\n  `field` values must match them exactly.\n- **The spec\'s `data` is ignored / any `url` is stripped.** The frame has no\n  network \u2014 remote data URLs, transform lookups, and remote `image` marks are\n  removed. Adapting a Vega-Lite gallery example = delete its\n  `"data": {"url": \u2026}` and repoint the encodings; the query rows are inlined for\n  you as the dataset.\n- **Nests come back as arrays.** Flatten to plottable rows in the query, or bind\n  a nest to its own chart: `<VegaChart data={row.my_nest}/>`.\n- **Interactivity = setting given values**, never rewriting query text per\n  interaction. Client-side chart interactions (tooltip, zoom, brush) work;\n  anything that calls a server does not.\n- **Reads well:** for normalized/share data use a diverging color scale with\n  `domainMid` (e.g. `1/12` for month-share), and sort a discrete axis by a\n  companion numeric field (`month_name` sorted by `month_num`) rather than\n  alphabetically.\n\n## Validate\n\n`malloyyo lint` checks the query, the givens, AND the component (it compiles,\nand each `query="\u2026"` it references resolves) \u2014 your only pre-browser check. Then\n`malloyyo dashboard dev` to see it render.\n',
-  "develop/connection-setup.md": '---\ndescription: Setting up a data connection (malloy-config.json)\n---\n\n# Setting up a data connection\n\nA model reaches its data through a **connection** declared in\n`malloy-config.json` at the **root of the model** (next to `index.malloy`). This\nis Malloy\'s standard connection config \u2014 the full reference, with every\nconnector\'s properties, is at\n<https://docs.malloydata.dev/documentation/setup/config>. The essentials:\n\n## The file\n\n```json\n{\n  "connections": {\n    "mydb": { "is": "duckdb" }\n  }\n}\n```\n\n- A connection has a **name** (the key) and a type (`is`). Sources refer to it by\n  that name \u2014 `source: x is mydb.table("orders")` or `mydb.sql("SELECT \u2026")` \u2014 so\n  the name in the config must match the name in the model.\n- Supported types (`is`): `duckdb` (incl. MotherDuck), `bigquery`, `postgres`,\n  `mysql`, `snowflake`, `databricks`, `trino`, `presto`. Each has its own\n  properties \u2014 see the full docs.\n\n## Default connections (and when they apply)\n\nSetting `"includeDefaultConnections": true` makes one connection available for\n**each registered database type, named by the type** \u2014 a `duckdb` connection\nnamed `duckdb`, a `postgres` named `postgres`, and so on. Each uses that\nconnector\'s default settings, which for several backends means picking up\ncredentials from the environment (e.g. BigQuery\'s application-default\ncredentials \u2014 see the per-connector setup docs). Connections you name explicitly\nin `connections` always win; the defaults only fill in types you didn\'t list.\n\n```json\n{\n  "includeDefaultConnections": true,\n  "connections": { "warehouse": { "is": "postgres", "host": "\u2026" } }\n}\n```\n\nmalloyyo has one rule worth knowing:\n\n- **No `malloy-config.json` at all \u2192 defaults are ON.** `duckdb` just works with\n  zero setup.\n- **Write a `malloy-config.json` and they turn OFF** unless you add\n  `"includeDefaultConnections": true`. A config that only defines, say, a\n  `postgres` connection will report *No connection named "duckdb"* if a source\n  still references `duckdb`.\n\nThis is deliberate \u2014 your local connections then resolve exactly the way the\npublished server\'s will, rather than silently leaning on a default that would not\nexist in production. (It differs from `malloy-cli`, which forces the defaults on\nunconditionally.)\n\nGive a connection a **custom name** \u2014 not the bare type default \u2014 whenever you\nhave more than one connection of the same type, or need non-default parameters.\n\n## DuckDB and local files (the common case)\n\nDuckDB can either open a **DuckDB database file** or read **local data files**\n(CSV, Parquet, \u2026) directly.\n\n**A pre-loaded database file** \u2014 point `databasePath` at a `.duckdb` file and\nreference its tables by name (an absolute path is safest):\n\n```json\n{ "connections": { "warehouse": { "is": "duckdb", "databasePath": "/data/warehouse.duckdb" } } }\n```\n\n**Local files, by path** \u2014 read a CSV or Parquet file straight into a source.\nThese paths are **project-relative** \u2014 resolved against the model root, so they\nsurvive publishing:\n\n    source: my_csv     is duckdb.table(\'data/my_file.csv\')\n    source: my_parquet is duckdb.table(\'data/my_file.parquet\')\n\n`.table()` names a single file. When you need something it can\'t express \u2014 a\nglob, a union, any SQL \u2014 wrap it in `.sql()` (its paths are project-relative too):\n\n    source: payments is duckdb.sql(\n      "SELECT * FROM read_parquet(\'data/payments-*.parquet\')"\n    )\n\nThe default `duckdb` connection is **in-memory** \u2014 nothing persists between runs;\nyour data lives in the files (or the `databasePath` database) you read.\n\n**MotherDuck:** a DuckDB connection against an `md:` database; set the\n`MOTHERDUCK_TOKEN` environment variable.\n\n## Secrets \u2014 keep them out of the file\n\nAny property value may be written as `{ "env": "VAR_NAME" }`. It resolves from\n`process.env.VAR_NAME` when the connection opens, so passwords and tokens never\nget committed:\n\n```json\n{\n  "connections": {\n    "analytics": {\n      "is": "postgres",\n      "host": "db.internal",\n      "databaseName": "analytics",\n      "username": "reader",\n      "password": { "env": "PG_PASSWORD" }\n    }\n  }\n}\n```\n\n(The non-secret property names here are illustrative \u2014 each connector\'s exact\nproperties are in the full docs. The `{ "env": \u2026 }` form is the part that\nmatters: it works for any value.)\n\n## malloyyo specifics\n\n- **One file, one place.** Only the `malloy-config.json` at the model root is\n  read \u2014 there is no walk-up to parent directories.\n- **Local override:** a `malloy-config-local.json` (do **not** commit it)\n  **replaces** `malloy-config.json` entirely when present \u2014 your private variant\n  for local credentials or a different database.\n- **The same file ships to production.** Publishing uploads this exact\n  `malloy-config.json`, so it must resolve the same way locally and on the\n  server \u2014 put anything environment-specific behind `{ "env": \u2026 }` rather than\n  hard-coding it. That is what makes the local test window faithful to\n  production.\n- Edits are picked up **without a restart** \u2014 the server re-reads the file when\n  it changes.\n\n## When a connection will not resolve\n\nFix the connection **first**: a broken connection yields an empty schema and then\na cascade of misleading `field-not-found` errors \u2014 ignore those and fix the\nconnection. A fast check is to compile a probe and see if it alone compiles:\n\n    source: _probe is mydb.sql("SELECT 1 AS one")\n',
+  "dashboards/vega-charts.md": '---\ndescription: Custom dashboard charts with Vega-Lite \u2014 the <VegaChart> component, for charts the # renderer tags can\'t do\n---\n\n# Custom charts with Vega-Lite (`<VegaChart>`)\n\nWhen Malloy\'s renderer tags (`# bar_chart`, `# line_chart`, `# shape_map`, \u2026)\ndon\'t cover the chart you want, a dashboard can draw a **Vega-Lite** spec with\nthe `<VegaChart>` component. The chart engine ships in the dashboard runtime, so\nyou author only a JSON spec + a Malloy query \u2014 no library to load.\n\n**It is a COMPONENT, not a `#` tag.** There is no `# vega_lite` or\n`# scatter_chart` tag. `<VegaChart>` lives in a custom component \u2014 a flat sibling\n`dashboards/<name>.jsx` (or `.tsx`) next to the dashboard\'s\n`dashboards/<name>.malloy` \u2014 a different layer from the `#` renderer tags. (The\ndashboard\'s query is declared in the `.malloy` file; the component only\ncustomizes presentation. Preview with `malloyyo dashboard dev`, validate with\n`malloyyo lint`.)\n\n## The recipe\n\n```tsx\nimport { VegaChart } from "@malloyyo/dashboard";\n\n// Encodings point at the query\'s OUTPUT COLUMN NAMES (here: name, births).\nconst spec = {\n  mark: { type: "bar", tooltip: true },\n  encoding: {\n    y: { field: "name", type: "nominal", sort: "-x" },\n    x: { field: "births", type: "quantitative" },\n  },\n};\n\nexport default function Dashboard({ givens }) {\n  return <VegaChart spec={spec} query="births_by_name" givens={givens} />;\n}\n```\n\nThree ways to feed it data:\n- `<VegaChart spec={spec} query="births_by_name" givens={givens}/>` \u2014 a query\n  defined in the dashboard\'s `.malloy` file (by name), or a `source -> view`\n- `<VegaChart spec={spec} malloy="source -> view" givens={givens}/>` \u2014 restricted\n  Malloy text (same governance as the explore surface: no import / given: /\n  connection.* / raw SQL / ##! flags)\n- `<VegaChart spec={spec} data={rows}/>` \u2014 rows you already have from `useQuery`\n\n## Gotchas (the ones that actually bite)\n\n- **Shape the data in Malloy; return FLAT rows.** Do ranking, share/percent\n  (`all(x, dim)`), and label lookups (a `pick` for month names) in the QUERY.\n  The spec just encodes columns \u2014 it is not the place to reshape data.\n- **Match column names character-for-character.** Run the query once with\n  `query(execute:true)` and read the exact output column names; the spec\'s\n  `field` values must match them exactly.\n- **The spec\'s `data` is ignored / any `url` is stripped.** The frame has no\n  network \u2014 remote data URLs, transform lookups, and remote `image` marks are\n  removed. Adapting a Vega-Lite gallery example = delete its\n  `"data": {"url": \u2026}` and repoint the encodings; the query rows are inlined for\n  you as the dataset.\n- **Nests come back as arrays.** Flatten to plottable rows in the query, or bind\n  a nest to its own chart: `<VegaChart data={row.my_nest}/>`.\n- **Huge integers arrive as strings, on purpose.** Integers serialize as JSON\n  numbers, but a value beyond \xB12^53 (a snowflake ID, a 64-bit hash) keeps its\n  full precision by staying a string \u2014 JSON has no int64. Bound to a\n  `quantitative` or `temporal` channel, Vega-Lite would sort such a column\n  lexicographically (`"1","10","11","2"`). If a column can get that big and you\n  need to plot it, narrow it in the QUERY \u2014 bucket it, rank it, or emit the\n  value you actually want on the axis.\n- **Interactivity = setting given values**, never rewriting query text per\n  interaction. Client-side chart interactions (tooltip, zoom, brush) work;\n  anything that calls a server does not.\n- **Reads well:** for normalized/share data use a diverging color scale with\n  `domainMid` (e.g. `1/12` for month-share), and sort a discrete axis by a\n  companion numeric field (`month_name` sorted by `month_num`) rather than\n  alphabetically.\n\n## Validate\n\n`malloyyo lint` checks the query, the givens, AND the component (it compiles,\nand each `query="\u2026"` it references resolves) \u2014 your only pre-browser check. Then\n`malloyyo dashboard dev` to see it render.\n',
+  "develop/connection-setup.md": '---\ndescription: Setting up a data connection (malloy-config.json)\n---\n\n# Setting up a data connection\n\nA model reaches its data through a **connection** declared in\n`malloy-config.json` at the **root of the model** (next to `index.malloy`). This\nis Malloy\'s standard connection config \u2014 the full reference, with every\nconnector\'s properties, is at\n<https://docs.malloydata.dev/documentation/setup/config>. The essentials:\n\n## The file\n\n```json\n{\n  "connections": {\n    "mydb": { "is": "duckdb" }\n  }\n}\n```\n\n- A connection has a **name** (the key) and a type (`is`). Sources refer to it by\n  that name \u2014 `source: x is mydb.table("orders")` or `mydb.sql("SELECT \u2026")` \u2014 so\n  the name in the config must match the name in the model.\n- Supported types (`is`): `duckdb` (incl. MotherDuck), `bigquery`, `postgres`,\n  `mysql`, `snowflake`, `databricks`, `trino`, `presto`. Each has its own\n  properties \u2014 see the full docs.\n\n## Default connections (and when they apply)\n\nSetting `"includeDefaultConnections": true` makes one connection available for\n**each registered database type, named by the type** \u2014 a `duckdb` connection\nnamed `duckdb`, a `postgres` named `postgres`, and so on. Each uses that\nconnector\'s default settings, which for several backends means picking up\ncredentials from the environment (e.g. BigQuery\'s application-default\ncredentials \u2014 see the per-connector setup docs). Connections you name explicitly\nin `connections` always win; the defaults only fill in types you didn\'t list.\n\n```json\n{\n  "includeDefaultConnections": true,\n  "connections": { "warehouse": { "is": "postgres", "host": "\u2026" } }\n}\n```\n\nmalloyyo has one rule worth knowing:\n\n- **No `malloy-config.json` at all \u2192 defaults are ON.** `duckdb` just works with\n  zero setup.\n- **Write a `malloy-config.json` and they turn OFF** unless you add\n  `"includeDefaultConnections": true`. A config that only defines, say, a\n  `postgres` connection will report *No connection named "duckdb"* if a source\n  still references `duckdb`.\n\nThis is deliberate \u2014 your local connections then resolve exactly the way the\npublished server\'s will, rather than silently leaning on a default that would not\nexist in production. (It differs from `malloy-cli`, which forces the defaults on\nunconditionally.)\n\n*No connection named* has one cause that is **not** about your config: if more\nthan one copy of `@malloydata/malloy` is installed, the connectors register with\none copy and malloyyo reads another, and every connection looks missing. malloyyo\ndetects that and says so instead \u2014 if it doesn\'t mention duplicate copies, the\nproblem really is the config. To check by hand: `npm ls @malloydata/malloy`.\n\nGive a connection a **custom name** \u2014 not the bare type default \u2014 whenever you\nhave more than one connection of the same type, or need non-default parameters.\n\n## DuckDB and local files (the common case)\n\nDuckDB can either open a **DuckDB database file** or read **local data files**\n(CSV, Parquet, \u2026) directly.\n\n**A pre-loaded database file** \u2014 point `databasePath` at a `.duckdb` file and\nreference its tables by name (an absolute path is safest):\n\n```json\n{ "connections": { "warehouse": { "is": "duckdb", "databasePath": "/data/warehouse.duckdb" } } }\n```\n\n**Local files, by path** \u2014 read a CSV or Parquet file straight into a source.\nThese paths are **project-relative** \u2014 resolved against the model root, so they\nsurvive publishing:\n\n    source: my_csv     is duckdb.table(\'data/my_file.csv\')\n    source: my_parquet is duckdb.table(\'data/my_file.parquet\')\n\n`.table()` names a single file. When you need something it can\'t express \u2014 a\nglob, a union, any SQL \u2014 wrap it in `.sql()` (its paths are project-relative too):\n\n    source: payments is duckdb.sql(\n      "SELECT * FROM read_parquet(\'data/payments-*.parquet\')"\n    )\n\nThe default `duckdb` connection is **in-memory** \u2014 nothing persists between runs;\nyour data lives in the files (or the `databasePath` database) you read.\n\n**MotherDuck:** a DuckDB connection against an `md:` database; set the\n`MOTHERDUCK_TOKEN` environment variable.\n\n## Secrets \u2014 keep them out of the file\n\nAny property value may be written as `{ "env": "VAR_NAME" }`. It resolves from\n`process.env.VAR_NAME` when the connection opens, so passwords and tokens never\nget committed:\n\n```json\n{\n  "connections": {\n    "analytics": {\n      "is": "postgres",\n      "host": "db.internal",\n      "databaseName": "analytics",\n      "username": "reader",\n      "password": { "env": "PG_PASSWORD" }\n    }\n  }\n}\n```\n\n(The non-secret property names here are illustrative \u2014 each connector\'s exact\nproperties are in the full docs. The `{ "env": \u2026 }` form is the part that\nmatters: it works for any value.)\n\n## malloyyo specifics\n\n- **One file, one place.** Only the `malloy-config.json` at the model root is\n  read \u2014 there is no walk-up to parent directories.\n- **Local override:** a `malloy-config-local.json` (do **not** commit it)\n  **replaces** `malloy-config.json` entirely when present \u2014 your private variant\n  for local credentials or a different database.\n- **The same file ships to production.** Publishing uploads this exact\n  `malloy-config.json`, so it must resolve the same way locally and on the\n  server \u2014 put anything environment-specific behind `{ "env": \u2026 }` rather than\n  hard-coding it. That is what makes the local test window faithful to\n  production.\n- Edits are picked up **without a restart** \u2014 the server re-reads the file when\n  it changes.\n\n## When a connection will not resolve\n\nFix the connection **first**: a broken connection yields an empty schema and then\na cascade of misleading `field-not-found` errors \u2014 ignore those and fix the\nconnection. A fast check is to compile a probe and see if it alone compiles:\n\n    source: _probe is mydb.sql("SELECT 1 AS one")\n',
   "develop/getting-started.md": '---\ndescription: Getting started \u2014 build a Malloy model step by step\n---\n\n# Building a Malloy model, step by step\n\nA model is a `malloy-config.json` (the connection to the data) and an\n`index.malloy` (the published query surface), optionally with other `.malloy`\nfiles that `index.malloy` imports. You edit these with your own file tools; the\nMCP tools compile, inspect, and test what you wrote. Never read `.malloy` as\ntext \u2014 compiling a bare source is how you read a table\'s schema.\n\n## 1. Verify the connection first\n\nConfirm the connection named in `malloy-config.json` resolves \u2014 compile a\nthrowaway probe inline with `compile` (no file needed):\n\n    source: _probe is CONN.sql("SELECT 1 AS one")\n\nIf it compiles, the connection is good. If not, fix the connection / config\nbefore going further \u2014 a broken connection produces an empty schema and then a\ncascade of misleading `field-not-found` errors; ignore the cascade and fix the\nconnection. Call `yo_help("develop/connection-setup")` for how to set up or repair a connection.\n\n## 2. Identify the tables the model needs\n\nIf you are unsure which tables matter, ask the fox \u2014 they own the data and know\nwhere it lives.\n\n## 3. Get a base source per table\n\nA base is "what\'s in the table and what\'s computable from it" \u2014 no joins.\nDiscover the schema by compiling a bare stub inline with `compile`:\n\n    source: users_base is CONN.table("users")\n\n`compile` returns the full column list + types \u2014 that is your schema browser.\nThen write the base into its own file and iterate with `compile_file`, adding\nonly the dimensions and measures intrinsic to that one table:\n\n    // users_base.malloy\n    source: users_base is CONN.table("users") extend {\n      measure: user_count is count()\n    }\n\nIf the data lives in files rather than database tables \u2014 common when the\nconnection is DuckDB \u2014 DuckDB lets you name a file path as the table (a\nproject-relative path):\n\n    source: users_base is CONN.table(\'data/users.parquet\')\n\nOnly drop to a `.sql()` block when a single file-as-table can\'t express what you\nneed \u2014 e.g. globbing or unioning several files:\n\n    source: users_base is CONN.sql("SELECT * FROM read_parquet(\'data/users-*.parquet\')")\n\n(`read_parquet` there is DuckDB SQL, not Malloy \u2014 see `yo_help("develop/connection-setup")`.)\n\n## 4. Assemble index.malloy \u2014 the published surface\n\nImport the bases, join them into the consumer-facing sources, and explicitly\nexport what consumers may query:\n\n    import "users_base.malloy"\n    import "orders_base.malloy"\n\n    source: users is users_base extend {\n      join_many: orders is orders_base on id = orders.user_id\n    }\n    source: orders is orders_base extend { }\n\n    export { users, orders }\n\n**Export discipline** \u2014 the model is a published artifact, so be deliberate about\nits public surface:\n\n- Imported names are private. Base sources stay internal scaffolding unless you\n  export them.\n- Without an `export` statement, everything you define is public. Add one and the\n  surface becomes explicit: only the names you list \u2014 defined or imported \u2014 are\n  public.\n- Hide intermediates. A staging source you define only so other sources can build\n  on it should not be exported.\n- The export list is the consumer\'s menu \u2014 exactly what the test window and real\n  consumers can query, nothing more.\n\n## The loop\n\nEdit a file \u2192 `compile_file` \u2192 fix `problems[]` \u2192 `query` (pass the model file\'s\npath as `ref`; `execute: false` validates first and reports the givens the query\nneeds, supplied via `givens`). Query text is restricted \u2014 `import`, `given:`\ndeclarations, `connection.table`/`connection.sql`, raw SQL, and `##!` flags\nbelong in the model file, not the query. When `compile`/`compile_file` returns\n`formatted: false`, call `prettify` and save its output. Use project-relative\ndata paths, not absolute \u2014 they resolve against the project root and survive\npublishing the model.\n',
   "develop/working-with-models.md": "---\ndescription: Working with an existing Malloy model\n---\n\n# Working with an existing model\n\nAn existing model is an `index.malloy` (plus any `.malloy` files it imports) and\na `malloy-config.json`.\n\n## Understand the model\n\n- **Read `malloy-config.json` directly** \u2014 it is JSON, so read it as text. It\n  lists the connection(s) the model queries against; `yo_help(\"develop/connection-setup\")` explains\n  the format (and how to set one up or repair it).\n- **Do NOT read `.malloy` as text \u2014 compile it.** `compile_file` returns the\n  structured model: each source with its fields, joins, views, and named queries,\n  plus `problems[]`. That is how you describe what is in the model. (Compiling a\n  bare source \u2014 no `extend` block \u2014 likewise reads a raw table's schema.)\n\n## The loop\n\nEdit a file \u2192 `compile_file` \u2192 fix `problems[]` \u2192 `query`. Pass the model file's\npath as `ref`; `execute: false` validates first and reports the givens the query\nneeds (supplied via `givens`). Query text is restricted \u2014 `import`, `given:`\ndeclarations, `connection.table`/`connection.sql`, raw SQL, and `##!` flags\nbelong in the model file, not the query. When `compile`/`compile_file` returns\n`formatted: false`, run `prettify` and save its output. Use project-relative data\npaths, not absolute.\n",
   "explore/how-to.md": '---\ndescription: Extended instructions working with this MCP server\n---\n# General Notes\nMalloy is a combined semantic layer/query language. It describes data and analysis, and it can generate and execute SQL.\n\nYou answer questions from published Malloy semantic models. A model publishes sources and queries.\n\n* Some tools return problems[] to indicate invalid Malloy.  problems may have a `help_topic` field \u2014 call `yo_help(help_topic)` for detailed guidance.\n* `yo_help()` with no topic will show an index which include error explanations, examples of Malloy syntax for common patterns, and a language reference manual (Malloy syntax is still evolving).\n* Tools that inspect Malloy code return objects with schemas, among other things.  An entry with a name which requires `back-tick-quoting` (reserved word, special characters), will have `must_quote: true`\n* When limiting queries, do ranking, top-N, and member selection in Malloy, not in client code.  Results are byte-budgeted: oversized results are truncated (the response says so and may link the full result). Reading aggregated rows is better analysis and the only way to see everything.\n* Compose your answer from what the model publishes. When composing a query, you can make new sources, extending existing sources with measures dimensions and joins. If the model\'s surface genuinely cannot answer a question, that is useful signal about the model.\n\n# Answering A Question\nTo answer a question you need to see what sources are available which pertain to the question.\n\n`list_sources` (when available) \u2014 see the sources you can query, grouped by model, with each model\'s named queries. If you already know the source, go straight to describe_source.\n\n# Build the Query\n* New to a pattern? `yo_help("explore/query-examples")` \u2014 the handful of Malloy query shapes (views, the workhorse group_by/aggregate, filtered aggregates, `all()`, `extend:`, `select:`, `nest:`) that cover almost every question, with the SQL habits that are wrong in Malloy.\n* `describe_source(source, model_ref)` \u2014 always describe a source before querying it (`model_ref` optional when the name is unique). Returns:\n  * `described_source` \u2014 the source\'s `dimensions` (columns), `measures`, and `views` (the author\'s saved queries). A dimension\'s `type` is a scalar or a nested record (`origin.city`); an array column has no `type` \u2014 it shows up as a `joins` entry at its `path`.\n  * `joins` \u2014 keyed by path, the arrays and source-joins this source reaches. `fans_out` marks a path that fans out. Each entry is one of: `{ source }` (fields in `join_source_map`), `{ source_def }` (an anonymous source\'s fields, inline), or an array `{ is_array, source_def }` \u2014 a record array\'s fields are used directly (`parcels.sku`), a scalar array\'s element is `each` (`tags.each`). To write a reference, use the entry\'s `quoted_path` if it has one, else the key.\n  * `join_source_map` \u2014 the named sources those `{ source }` joins resolve to, deduped.\n  * In its own content block, the source\'s raw Malloy, for anything the structured output above doesn\'t cover.\n* `query(source: "...", malloy: "run: source -> { ... }", execute: false)` \u2014 validate without running; it returns the SQL. Iterate until clean. (`model_ref` optional, needed only when the source name is ambiguous.)\n* Some queries accept parameters (givens). More info if needed: yo_help("language/givens-model-level-parameters")\n\n# Run the query\n* Pass a plain-English question with EVERY query, describing what that specific query answers. Queries are recorded/shared independently. Don\'t try to group related queries.\n* query(source: "...", malloy: "run: source -> { ... }", question: "...") \u2014 run it; get the rows.\n\n# Displaying Results\n* Lead with a natural-language restatement of the query \u2014 a short heading works well.\n* A successful query comes back with an ltool_link \u2014 {text, url}, already assembled. It opens this exact query so the user can keep exploring, or share the insight. Follow the data with a markdown link, [\u2197 text](url).\n* When it helps the reader add a short note on how you got the answer: the Malloy logic (filters, grouping, aggregation, ordering, pipeline stages), and any post-processing done outside Malloy.',
@@ -330,8 +330,8 @@ function errorProblem(e, uri) {
     uri
   };
 }
-function codeProblem(code, message, uri) {
-  const out = { severity: "error", code, message, uri };
+function codeProblem(code, message2, uri) {
+  const out = { severity: "error", code, message: message2, uri };
   const topic = helpTopicForCode(code);
   if (topic) out.help_topic = topic;
   return out;
@@ -959,6 +959,28 @@ function modelCatalogEntry(model_ref, model) {
   if (sources.length) entry.sources = sources;
   return entry;
 }
+var MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+var MIN_SAFE = -MAX_SAFE;
+function narrowBigint(value) {
+  return value <= MAX_SAFE && value >= MIN_SAFE ? Number(value) : value.toString();
+}
+function jsonValue(value) {
+  if (typeof value === "bigint") return narrowBigint(value);
+  if (value instanceof Date) return value.toISOString();
+  if (Array.isArray(value)) return value.map(jsonValue);
+  if (value !== null && typeof value === "object" && value.constructor === Object) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = jsonValue(v);
+    return out;
+  }
+  return value;
+}
+function jsonRows(result) {
+  if (!result.hasSchema) {
+    return result.toJSON().queryResult.result;
+  }
+  return result.data.toObject().map((row) => jsonValue(row));
+}
 var DEFAULT_ROW_LIMIT = 1e4;
 async function executeMaterialized(query, opts, loadProblems, decorate = (p) => p, uri) {
   const rowLimit = opts.rowLimit ?? DEFAULT_ROW_LIMIT;
@@ -970,7 +992,7 @@ async function executeMaterialized(query, opts, loadProblems, decorate = (p) =>
     const t1 = Date.now();
     const results = await retry(() => query.run({ rowLimit, ...compileOpts }));
     const t2 = Date.now();
-    const rows = results.toJSON().queryResult.result;
+    const rows = jsonRows(results);
     const out = {
       ok: true,
       sql,
@@ -1967,6 +1989,239 @@ function developSurface(host, opts = {}) {
   };
 }
 
+// src/connections.ts
+import fs from "node:fs";
+import path2 from "node:path";
+import url2 from "node:url";
+import { createRequire } from "node:module";
+import { getRegisteredConnectionTypes } from "@malloydata/malloy";
+var CONNECTIONS_PKG = "@malloydata/malloy-connections";
+var CONNECTOR_IMPORTS = [
+  "@malloydata/db-bigquery",
+  "@malloydata/db-duckdb/native",
+  "@malloydata/db-mysql",
+  "@malloydata/db-databricks",
+  "@malloydata/db-postgres",
+  "@malloydata/db-snowflake",
+  "@malloydata/db-trino"
+];
+var REGISTRY_WRITERS = [
+  CONNECTIONS_PKG,
+  "@malloydata/db-bigquery",
+  "@malloydata/db-databricks",
+  "@malloydata/db-duckdb",
+  "@malloydata/db-mysql",
+  "@malloydata/db-postgres",
+  "@malloydata/db-snowflake",
+  "@malloydata/db-trino"
+];
+function message(e) {
+  return e instanceof Error ? e.message : String(e);
+}
+function oneLine(text) {
+  return text.split("\n")[0];
+}
+function indent(text, by = "  ") {
+  return text.split("\n").map((l) => l ? by + l : l).join("\n");
+}
+function requireFrom(dir) {
+  return createRequire(path2.join(dir, "__resolve__.cjs"));
+}
+function packageRootOf(entry) {
+  let dir = path2.dirname(entry);
+  for (; ; ) {
+    if (fs.existsSync(path2.join(dir, "package.json"))) return dir;
+    const up = path2.dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}
+function packageDir(spec, from) {
+  const req = requireFrom(from);
+  try {
+    return fs.realpathSync(path2.dirname(req.resolve(`${spec}/package.json`)));
+  } catch {
+  }
+  try {
+    const root = packageRootOf(req.resolve(spec));
+    return root ? fs.realpathSync(root) : null;
+  } catch {
+    return null;
+  }
+}
+function readVersion(pkgDir) {
+  try {
+    const raw = fs.readFileSync(path2.join(pkgDir, "package.json"), "utf8");
+    return String(JSON.parse(raw).version ?? "?");
+  } catch {
+    return "?";
+  }
+}
+function selfDir() {
+  return path2.dirname(url2.fileURLToPath(import.meta.url));
+}
+function malloyCopies(from = selfDir()) {
+  const here = from;
+  const byDir = /* @__PURE__ */ new Map();
+  const note = (from2, importer) => {
+    if (!from2) return;
+    const dir = packageDir("@malloydata/malloy", from2);
+    if (!dir) return;
+    const found = byDir.get(dir);
+    if (found) {
+      if (!found.importers.includes(importer)) found.importers.push(importer);
+      return;
+    }
+    byDir.set(dir, { dir, version: readVersion(dir), importers: [importer] });
+  };
+  note(here, "malloyyo");
+  const connectionsDir = packageDir(CONNECTIONS_PKG, here);
+  for (const spec of REGISTRY_WRITERS) {
+    note(packageDir(spec, connectionsDir ?? here) ?? packageDir(spec, here), spec);
+  }
+  return [...byDir.values()];
+}
+function duplicateMalloyReport(from) {
+  const copies = malloyCopies(from);
+  if (copies.length < 2) return null;
+  const listing = copies.map((c) => `${c.version.padEnd(9)} ${c.dir}
+${" ".repeat(10)}\u21B3 ${c.importers.join(", ")}`).join("\n");
+  return `${copies.length} copies of @malloydata/malloy are installed. The connection
+registry is module-level state, so each copy has its own: the connectors
+register with the copy THEY resolve, malloyyo reads the copy IT resolves,
+and when those differ every connection looks missing.
+
+${indent(listing)}
+
+This is about paths, not versions \u2014 two copies of the same version are still
+two registries. Collapse the tree to one copy:
+
+  npm ls @malloydata/malloy    # show who pulls in the extra copy
+  npm dedupe                   # often enough on its own
+
+Or run malloyyo somewhere that has no @malloydata/* dependencies of its own
+(a global install, or \`npx @malloydata/malloyyo\` from an empty directory).`;
+}
+async function importConnector(spec, from) {
+  let target = spec;
+  try {
+    target = url2.pathToFileURL(requireFrom(from).resolve(spec)).href;
+  } catch {
+  }
+  await import(target);
+}
+var pending = null;
+function loadConnectionTypes() {
+  return pending ??= register();
+}
+async function register() {
+  const here = selfDir();
+  const failures = [];
+  try {
+    await import(CONNECTIONS_PKG);
+  } catch (bulk) {
+    failures.push({ pkg: CONNECTIONS_PKG, error: message(bulk) });
+    const from = packageDir(CONNECTIONS_PKG, here) ?? here;
+    for (const spec of CONNECTOR_IMPORTS) {
+      try {
+        await importConnector(spec, from);
+      } catch (e) {
+        failures.push({ pkg: spec, error: message(e) });
+      }
+    }
+  }
+  const types = getRegisteredConnectionTypes();
+  const duplicates = malloyCopies();
+  const split = duplicates.length > 1 ? duplicates : null;
+  if (types.length === 0) {
+    throw new Error(noTypesRegistered(failures));
+  }
+  return { types, failures, duplicates: split };
+}
+function noTypesRegistered(failures) {
+  const dup = duplicateMalloyReport();
+  const head = `0 connection types registered after loading ${CONNECTIONS_PKG} \u2014 no database connection can be created.
+`;
+  const why = dup ? `
+${dup}
+` : `
+Only one @malloydata/malloy was found from here, so the connector packages
+themselves did not load or did not register. Check the install:
+
+  npm ls @malloydata/malloy ${CONNECTIONS_PKG}
+`;
+  return head + why + failureDetail(failures) + `
+Nothing is wrong with your malloy-config.json.`;
+}
+function failureDetail(failures) {
+  if (failures.length === 0) return "";
+  return `
+Connector packages that failed to load:
+` + failures.map((f) => indent(`${f.pkg}: ${f.error}`)).join("\n") + `
+`;
+}
+var warned2 = false;
+var warnedAboutDuplicates = false;
+function warnConnectionIssues(result) {
+  if (warned2) return;
+  warned2 = true;
+  if (result.duplicates) {
+    warnedAboutDuplicates = true;
+    console.error(
+      `warning: ${duplicateMalloyReport()}
+Registered so far: ${result.types.join(", ")}
+`
+    );
+  }
+  const backends = result.failures.filter((f) => f.pkg !== CONNECTIONS_PKG);
+  for (const f of backends) {
+    console.error(`warning: connection backend ${f.pkg} unavailable \u2014 ${oneLine(f.error)}`);
+  }
+  const bulk = backends.length === 0 && result.failures.find((f) => f.pkg === CONNECTIONS_PKG);
+  if (bulk) {
+    console.error(
+      `warning: ${CONNECTIONS_PKG} failed to load (${oneLine(bulk.error)}); loaded each backend directly instead \u2014 connections are available.`
+    );
+  }
+}
+async function initConnections() {
+  const result = await loadConnectionTypes();
+  warnConnectionIssues(result);
+  return result;
+}
+var MISSING_CONNECTION = /No connection named ".*" found in config/;
+function annotateConnectionError(text) {
+  if (!MISSING_CONNECTION.test(text)) return text;
+  const registered = getRegisteredConnectionTypes();
+  const dup = duplicateMalloyReport();
+  const parts = [text, ""];
+  if (dup) {
+    parts.push(
+      warnedAboutDuplicates ? `This is very likely the split @malloydata/malloy install warned about above.
+` : `This is very likely the cause:
+
+${indent(dup)}
+`
+    );
+  }
+  parts.push(
+    `Connection types registered: ${registered.length ? registered.join(", ") : "(none)"}`,
+    `Connections come from malloy-config.json, e.g.`,
+    indent(`{ "connections": { "duckdb": { "is": "duckdb" } } }`)
+  );
+  return parts.join("\n");
+}
+async function withConnectionDiagnostics(fn) {
+  try {
+    return await fn();
+  } catch (e) {
+    const text = message(e);
+    const annotated = annotateConnectionError(text);
+    if (annotated === text) throw e;
+    throw new Error(annotated, { cause: e });
+  }
+}
+
 // src/host.ts
 var ENTRY = "index.malloy";
 var IDLE_SHUTDOWN_MS = 6e4;
@@ -1996,7 +2251,7 @@ function fsReader() {
       if (u.protocol !== "file:") {
         throw new Error(`unsupported URL scheme for import: ${u.href}`);
       }
-      return fs.promises.readFile(u, "utf8");
+      return fs2.promises.readFile(u, "utf8");
     }
   };
 }
@@ -2007,9 +2262,9 @@ async function loadConfig(rootUrl, reader) {
   });
 }
 async function makeRunner(root) {
-  await import("@malloydata/malloy-connections");
-  const abs = path2.resolve(root);
-  const rootUrl = url2.pathToFileURL(abs + path2.sep);
+  await initConnections();
+  const abs = path3.resolve(root);
+  const rootUrl = url3.pathToFileURL(abs + path3.sep);
   const reader = fsReader();
   let configPromise = null;
   const getConfig = () => configPromise ??= loadConfig(rootUrl, reader);
@@ -2032,12 +2287,12 @@ async function makeRunner(root) {
   };
   async function leaseIn(entryFile, fn) {
     const config = await getConfig();
-    const { reader: prepared, entry } = prepareSource(reader, { url: path2.join(abs, entryFile) });
+    const { reader: prepared, entry } = prepareSource(reader, { url: path3.join(abs, entryFile) });
     const runtime = new Runtime({ config, urlReader: prepared });
     inFlight++;
     clearIdleTimer();
     try {
-      return await fn(runtime, entry);
+      return await withConnectionDiagnostics(() => fn(runtime, entry));
     } finally {
       inFlight--;
       if (inFlight === 0) scheduleIdleShutdown();
@@ -2046,7 +2301,7 @@ async function makeRunner(root) {
   const lease = (fn) => leaseIn(ENTRY, fn);
   return {
     root: abs,
-    entryExists: () => fs.existsSync(path2.join(abs, ENTRY)),
+    entryExists: () => fs2.existsSync(path3.join(abs, ENTRY)),
     async dispose() {
       clearIdleTimer();
       if (!configPromise) return;
@@ -2375,24 +2630,24 @@ function readAll() {
     return {};
   }
 }
-function loadCreds(url5) {
-  return readAll()[url5];
+function loadCreds(url6) {
+  return readAll()[url6];
 }
-function saveCreds(url5, creds) {
+function saveCreds(url6, creds) {
   const p = credsPath();
   mkdirSync(dirname(p), { recursive: true });
   const all = readAll();
-  all[url5] = creds;
+  all[url6] = creds;
   writeFileSync(p, JSON.stringify(all, null, 2) + "\n", { mode: 384 });
   try {
     chmodSync(p, 384);
   } catch {
   }
 }
-function clearCreds(url5) {
+function clearCreds(url6) {
   const all = readAll();
-  if (!(url5 in all)) return false;
-  delete all[url5];
+  if (!(url6 in all)) return false;
+  delete all[url6];
   writeFileSync(credsPath(), JSON.stringify(all, null, 2) + "\n", { mode: 384 });
   return true;
 }
@@ -2425,8 +2680,8 @@ async function registerClient(registrationEndpoint, redirectUri) {
   if (!res.ok) throw new Error(`client registration failed: ${res.status} ${await res.text()}`);
   return (await res.json()).client_id;
 }
-function openBrowser(url5) {
-  const [cmd, args] = process.platform === "darwin" ? ["open", [url5]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url5]] : ["xdg-open", [url5]];
+function openBrowser(url6) {
+  const [cmd, args] = process.platform === "darwin" ? ["open", [url6]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url6]] : ["xdg-open", [url6]];
   try {
     spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
   } catch {
@@ -2555,9 +2810,9 @@ Run:  malloyyo login ${target.name}`);
 }
 
 // src/mcp.ts
-import fs2 from "node:fs";
-import path3 from "node:path";
-import url3 from "node:url";
+import fs3 from "node:fs";
+import path4 from "node:path";
+import url4 from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -2645,7 +2900,7 @@ function defaultConfig(rootUrl) {
   });
 }
 async function loadConfig2(root, reader) {
-  const rootUrl = url3.pathToFileURL(root + path3.sep);
+  const rootUrl = url4.pathToFileURL(root + path4.sep);
   let discovered;
   try {
     discovered = await discoverConfig2(rootUrl, rootUrl, reader);
@@ -2667,13 +2922,13 @@ function fsReader2() {
       if (u.protocol !== "file:") {
         throw new Error(`unsupported URL scheme for import: ${u.href}`);
       }
-      return fs2.promises.readFile(u, "utf8");
+      return fs3.promises.readFile(u, "utf8");
     }
   };
 }
 function resolveUnderRoot(root, p) {
-  const abs = p.includes("://") ? path3.resolve(decodeURIComponent(new URL(p).pathname)) : path3.resolve(root, p);
-  if (abs !== root && !abs.startsWith(root + path3.sep)) {
+  const abs = p.includes("://") ? path4.resolve(decodeURIComponent(new URL(p).pathname)) : path4.resolve(root, p);
+  if (abs !== root && !abs.startsWith(root + path4.sep)) {
     throw new Error(`path is outside the project root: ${p}`);
   }
   return abs;
@@ -2682,7 +2937,7 @@ function makeConfigSource(root) {
   let cached;
   const signature = () => ["malloy-config.json", "malloy-config-local.json"].map((name) => {
     try {
-      const st = fs2.statSync(path3.join(root, name));
+      const st = fs3.statSync(path4.join(root, name));
       return `${name}:${st.mtimeMs}:${st.size}`;
     } catch {
       return `${name}:absent`;
@@ -2702,12 +2957,12 @@ function makeWithRuntime(root, currentConfig) {
     return gateConfigProblems(problems, async () => {
       const resolved = "url" in input ? { url: resolveUnderRoot(root, input.url) } : {
         source: input.source,
-        baseUrl: input.baseUrl ? resolveUnderRoot(root, input.baseUrl) : root + path3.sep
+        baseUrl: input.baseUrl ? resolveUnderRoot(root, input.baseUrl) : root + path4.sep
       };
       const { reader, entry, readSource } = prepareSource(fsReader2(), resolved);
       const runtime = new Runtime2({ config, urlReader: reader });
       try {
-        return await fn({ runtime, entry, readSource });
+        return await withConnectionDiagnostics(() => fn({ runtime, entry, readSource }));
       } finally {
         await config.shutdown("idle");
       }
@@ -2716,7 +2971,7 @@ function makeWithRuntime(root, currentConfig) {
 }
 function makeExploreHost(root, currentConfig) {
   const withRuntime = makeWithRuntime(root, currentConfig);
-  const published = (ref) => ref === ENTRY2 && fs2.existsSync(path3.join(root, ENTRY2));
+  const published = (ref) => ref === ENTRY2 && fs3.existsSync(path4.join(root, ENTRY2));
   return {
     withModel: (ref, fn) => {
       if (!published(ref)) throw new Error(`no published model '${ref}'`);
@@ -2736,8 +2991,8 @@ function makeDevelopHost(root, currentConfig) {
   return { withRuntime: makeWithRuntime(root, currentConfig) };
 }
 async function serveMcp(opts) {
-  await import("@malloydata/malloy-connections");
-  const root = path3.resolve(opts.root ?? process.cwd());
+  await initConnections();
+  const root = path4.resolve(opts.root ?? process.cwd());
   const mode = opts.mode ?? "explore";
   const currentConfig = makeConfigSource(root);
   const surface = mode === "develop" ? developSurface(makeDevelopHost(root, currentConfig)) : exploreSurface(makeExploreHost(root, currentConfig));
@@ -2761,8 +3016,8 @@ async function serveMcp(opts) {
 
 // src/dashboard.ts
 import http2 from "node:http";
-import fs4 from "node:fs";
-import path5 from "node:path";
+import fs5 from "node:fs";
+import path6 from "node:path";
 import * as esbuild2 from "esbuild";
 
 // src/shared/givens-url.ts
@@ -2807,11 +3062,11 @@ function navHtml(active, all, href, homeHref = "./") {
 }
 
 // src/discover.ts
-import fs3 from "node:fs";
-import path4 from "node:path";
+import fs4 from "node:fs";
+import path5 from "node:path";
 import { fileURLToPath } from "node:url";
-import { createRequire } from "node:module";
-var require2 = createRequire(import.meta.url);
+import { createRequire as createRequire2 } from "node:module";
+var require2 = createRequire2(import.meta.url);
 var HOST_LIBS = [
   "react",
   "react-dom",
@@ -2835,7 +3090,7 @@ function resolveRuntimeDir() {
     new URL("../src/frame-runtime/", import.meta.url)
     // built dist/ next to sibling src/ (checkout)
   ].map((u) => fileURLToPath(u));
-  const found = candidates.find((c) => fs3.existsSync(c));
+  const found = candidates.find((c) => fs4.existsSync(c));
   if (!found) {
     throw new Error(
       "frame-runtime/ not found next to the CLI (looked in ./frame-runtime and ../src/frame-runtime). A published install should ship it in dist/; reinstall the CLI, or rebuild with `npm run build`."
@@ -2853,31 +3108,31 @@ var hostAliasPlugin = {
   }
 };
 async function discoverDashboards(root, runner) {
-  const dir = path4.join(root, "dashboards");
-  if (!fs3.existsSync(dir)) return [];
-  const files = fs3.readdirSync(dir).filter((f) => f.endsWith(".malloy")).sort();
+  const dir = path5.join(root, "dashboards");
+  if (!fs4.existsSync(dir)) return [];
+  const files = fs4.readdirSync(dir).filter((f) => f.endsWith(".malloy")).sort();
   const dashboards = [];
   for (const file of files) {
     const base = file.slice(0, -".malloy".length);
-    const entryFile = path4.join("dashboards", file);
+    const entryFile = path5.join("dashboards", file);
     const res = await runner.artifactForFile(entryFile, base);
     if (!res.ok) throw new Error(`dashboard ${file}: ${res.error}`);
     if (!res.artifact) continue;
-    const component = ["jsx", "tsx"].map((ext) => path4.join(dir, `${base}.${ext}`)).find((p) => fs3.existsSync(p));
+    const component = ["jsx", "tsx"].map((ext) => path5.join(dir, `${base}.${ext}`)).find((p) => fs4.existsSync(p));
     dashboards.push({ ...res.artifact, name: res.artifact.name || base, entryFile, tsxPath: component });
   }
   return dashboards;
 }
 function browserBuildBase() {
-  const shims = path4.join(resolveRuntimeDir(), "..", "shims");
+  const shims = path5.join(resolveRuntimeDir(), "..", "shims");
   return {
     platform: "browser",
     jsx: "automatic",
     loader: { ".css": "empty" },
     define: { "process.env.NODE_ENV": '"production"' },
     alias: {
-      assert: path4.join(shims, "assert.cjs"),
-      util: path4.join(shims, "util.cjs")
+      assert: path5.join(shims, "assert.cjs"),
+      util: path5.join(shims, "util.cjs")
     },
     banner: {
       js: "globalThis.process||={env:{},platform:'browser',versions:{},argv:[],cwd:()=>'/'};"
@@ -2886,17 +3141,17 @@ function browserBuildBase() {
 }
 
 // src/dashboard.ts
-var resolveFrameEntry = () => path5.join(resolveRuntimeDir(), "..", "frame-entry.tsx");
-var resolveInPageEntry = () => path5.join(resolveRuntimeDir(), "..", "frame-inpage-entry.tsx");
+var resolveFrameEntry = () => path6.join(resolveRuntimeDir(), "..", "frame-entry.tsx");
+var resolveInPageEntry = () => path6.join(resolveRuntimeDir(), "..", "frame-inpage-entry.tsx");
 var esc2 = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 function makeBundler() {
   const cache = /* @__PURE__ */ new Map();
   const frameEntry = resolveFrameEntry();
   const runtimeDir = resolveRuntimeDir();
-  const runtimeIndex = path5.join(runtimeDir, "index.ts");
-  const runtimeStamp = () => fs4.statSync(frameEntry).mtimeMs + fs4.readdirSync(runtimeDir).map((f) => fs4.statSync(path5.join(runtimeDir, f)).mtimeMs).reduce((a, b) => a + b, 0);
+  const runtimeIndex = path6.join(runtimeDir, "index.ts");
+  const runtimeStamp = () => fs5.statSync(frameEntry).mtimeMs + fs5.readdirSync(runtimeDir).map((f) => fs5.statSync(path6.join(runtimeDir, f)).mtimeMs).reduce((a, b) => a + b, 0);
   return async function bundle(dash) {
-    const stamp = runtimeStamp() + (dash.tsxPath ? fs4.statSync(dash.tsxPath).mtimeMs : 0);
+    const stamp = runtimeStamp() + (dash.tsxPath ? fs5.statSync(dash.tsxPath).mtimeMs : 0);
     const hit = cache.get(dash.name);
     if (hit && hit.stamp === stamp) return hit.js;
     const result = await esbuild2.build({
@@ -2941,7 +3196,7 @@ function makeInPageBundler() {
   let cached;
   const entry = resolveInPageEntry();
   const runtimeDir = resolveRuntimeDir();
-  const stampOf = () => fs4.statSync(entry).mtimeMs + fs4.readdirSync(runtimeDir).map((f) => fs4.statSync(path5.join(runtimeDir, f)).mtimeMs).reduce((a, b) => a + b, 0);
+  const stampOf = () => fs5.statSync(entry).mtimeMs + fs5.readdirSync(runtimeDir).map((f) => fs5.statSync(path6.join(runtimeDir, f)).mtimeMs).reduce((a, b) => a + b, 0);
   return async function bundle() {
     const stamp = stampOf();
     if (cached && cached.stamp === stamp) return cached.js;
@@ -3040,11 +3295,11 @@ window.addEventListener('message',async(e)=>{
     dash.title
   );
 }
-function givensFromUrl(url5) {
-  return givensFromSearch(url5.search);
+function givensFromUrl(url6) {
+  return givensFromSearch(url6.search);
 }
-function urlStateFromUrl(url5) {
-  return urlStateFromSearch(url5.search);
+function urlStateFromUrl(url6) {
+  return urlStateFromSearch(url6.search);
 }
 function frameDoc(dash, givenSpecs, initialGivens, initialUrlState, tileSpecs) {
   const info = {
@@ -3071,8 +3326,8 @@ async function readBody(req) {
   return Buffer.concat(chunks).toString("utf8");
 }
 async function serveDashboard(opts) {
-  await import("@malloydata/malloy-connections");
-  const root = path5.resolve(opts.root ?? process.cwd());
+  await initConnections();
+  const root = path6.resolve(opts.root ?? process.cwd());
   const port = opts.port ?? 4173;
   const framePort = port + 1;
   const frameBase = `http://localhost:${framePort}`;
@@ -3089,7 +3344,7 @@ async function serveDashboard(opts) {
   let byName = new Map(dashboards.map((d) => [d.name, d]));
   const bundle = makeBundler();
   const inPageBundle = makeInPageBundler();
-  const pick = (url5) => byName.get(url5.searchParams.get("d") ?? dashboards[0].name) ?? dashboards[0];
+  const pick = (url6) => byName.get(url6.searchParams.get("d") ?? dashboards[0].name) ?? dashboards[0];
   async function resolveGivens(dash) {
     if (dash.tiles && dash.entryFile) {
       const t = await runner.dashboardTiles(dash.entryFile, dash.tiles);
@@ -3105,7 +3360,7 @@ async function serveDashboard(opts) {
   };
   let debounce;
   try {
-    fs4.watch(root, { recursive: true }, (_evt, filename) => {
+    fs5.watch(root, { recursive: true }, (_evt, filename) => {
       const f = filename?.toString() ?? "";
       if (!f.endsWith(".malloy") && !f.includes("dashboards")) return;
       clearTimeout(debounce);
@@ -3123,15 +3378,15 @@ async function serveDashboard(opts) {
   }
   const handler = async (req, res) => {
     const onFramePort = (req.socket.localPort ?? port) === framePort;
-    const url5 = new URL(req.url ?? "/", `http://localhost:${onFramePort ? framePort : port}`);
+    const url6 = new URL(req.url ?? "/", `http://localhost:${onFramePort ? framePort : port}`);
     const send = (code, type, body, extra = {}) => {
       res.writeHead(code, { "content-type": type, ...extra });
       res.end(body);
     };
     try {
       if (onFramePort) {
-        if (url5.pathname === "/frame") {
-          const dash = pick(url5);
+        if (url6.pathname === "/frame") {
+          const dash = pick(url6);
           const g = await resolveGivens(dash);
           if (!g.ok) {
             return send(
@@ -3143,23 +3398,23 @@ async function serveDashboard(opts) {
           return send(
             200,
             "text/html; charset=utf-8",
-            frameDoc(dash, g.union, givensFromUrl(url5), urlStateFromUrl(url5), g.tiles)
+            frameDoc(dash, g.union, givensFromUrl(url6), urlStateFromUrl(url6), g.tiles)
           );
         }
-        if (url5.pathname === "/bundle.js") {
-          return send(200, "application/javascript; charset=utf-8", await bundle(pick(url5)));
+        if (url6.pathname === "/bundle.js") {
+          return send(200, "application/javascript; charset=utf-8", await bundle(pick(url6)));
         }
         return send(404, "text/plain", "not found");
       }
-      if (url5.pathname === "/events") {
+      if (url6.pathname === "/events") {
         res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" });
         res.write("retry: 1000\n\n");
         sseClients.add(res);
         req.on("close", () => sseClients.delete(res));
         return;
       }
-      if (url5.pathname === "/") {
-        const dash = pick(url5);
+      if (url6.pathname === "/") {
+        const dash = pick(url6);
         if (!dash.tsxPath) {
           const g = await resolveGivens(dash);
           if (!g.ok) {
@@ -3172,19 +3427,19 @@ async function serveDashboard(opts) {
           return send(
             200,
             "text/html; charset=utf-8",
-            inPageShell(dash, dashboards, g.union, givensFromUrl(url5), urlStateFromUrl(url5), g.tiles)
+            inPageShell(dash, dashboards, g.union, givensFromUrl(url6), urlStateFromUrl(url6), g.tiles)
           );
         }
         return send(
           200,
           "text/html; charset=utf-8",
-          parentShell(dash, frameBase, dashboards, givensFromUrl(url5), urlStateFromUrl(url5))
+          parentShell(dash, frameBase, dashboards, givensFromUrl(url6), urlStateFromUrl(url6))
         );
       }
-      if (url5.pathname === "/inpage.js") {
+      if (url6.pathname === "/inpage.js") {
         return send(200, "application/javascript; charset=utf-8", await inPageBundle());
       }
-      if (url5.pathname === "/api/run" && req.method === "POST") {
+      if (url6.pathname === "/api/run" && req.method === "POST") {
         const { d, query, malloy, givens } = JSON.parse(await readBody(req));
         const dash = byName.get(d);
         if (!dash) return send(404, "application/json", JSON.stringify({ ok: false, problems: [{ message: `no dashboard '${d}'` }] }));
@@ -3215,15 +3470,15 @@ async function serveDashboard(opts) {
 }
 
 // src/bundle.ts
-import fs6 from "node:fs";
-import path7 from "node:path";
-import { createRequire as createRequire2 } from "node:module";
+import fs7 from "node:fs";
+import path8 from "node:path";
+import { createRequire as createRequire3 } from "node:module";
 import * as esbuild3 from "esbuild";
 
 // src/static-server.ts
-import fs5 from "node:fs";
+import fs6 from "node:fs";
 import http3 from "node:http";
-import path6 from "node:path";
+import path7 from "node:path";
 var MIME = {
   ".html": "text/html; charset=utf-8",
   ".js": "text/javascript; charset=utf-8",
@@ -3238,12 +3493,12 @@ var MIME = {
 function serveStatic(dir, port) {
   const server = http3.createServer((req, res) => {
     const rel = decodeURIComponent((req.url ?? "/").split("?")[0]);
-    let file = path6.join(dir, rel === "/" ? "index.html" : rel);
+    let file = path7.join(dir, rel === "/" ? "index.html" : rel);
     if (!file.startsWith(dir)) return void res.writeHead(403).end();
-    if (fs5.existsSync(file) && fs5.statSync(file).isDirectory()) file = path6.join(file, "index.html");
-    if (!fs5.existsSync(file)) return void res.writeHead(404).end("not found");
-    const st = fs5.statSync(file);
-    const type = MIME[path6.extname(file)] ?? "application/octet-stream";
+    if (fs6.existsSync(file) && fs6.statSync(file).isDirectory()) file = path7.join(file, "index.html");
+    if (!fs6.existsSync(file)) return void res.writeHead(404).end("not found");
+    const st = fs6.statSync(file);
+    const type = MIME[path7.extname(file)] ?? "application/octet-stream";
     const range = req.headers.range;
     if (range) {
       const m = /bytes=(\d*)-(\d*)/.exec(range);
@@ -3255,10 +3510,10 @@ function serveStatic(dir, port) {
         "Accept-Ranges": "bytes",
         "Content-Length": end - start + 1
       });
-      return void fs5.createReadStream(file, { start, end }).pipe(res);
+      return void fs6.createReadStream(file, { start, end }).pipe(res);
     }
     res.writeHead(200, { "Content-Type": type, "Content-Length": st.size, "Accept-Ranges": "bytes" });
-    fs5.createReadStream(file).pipe(res);
+    fs6.createReadStream(file).pipe(res);
   });
   return new Promise((resolve3, reject) => {
     let attempt = 0;
@@ -3275,7 +3530,7 @@ function serveStatic(dir, port) {
         if (p !== port) console.log(`
 (port ${port} busy \u2014 using ${p})`);
         console.log(`
-serving ${path6.basename(dir)}/ on http://localhost:${p}  (ctrl-c to stop)`);
+serving ${path7.basename(dir)}/ on http://localhost:${p}  (ctrl-c to stop)`);
         resolve3();
       });
     };
@@ -3284,19 +3539,19 @@ serving ${path6.basename(dir)}/ on http://localhost:${p}  (ctrl-c to stop)`);
 }
 
 // src/bundle.ts
-var require3 = createRequire2(import.meta.url);
+var require3 = createRequire3(import.meta.url);
 var esc3 = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 function inlineModelFiles(root) {
   const files = {};
   const skip = /* @__PURE__ */ new Set(["node_modules", ".git", "docs", "dist"]);
   const walk = (dir) => {
-    for (const entry of fs6.readdirSync(dir, { withFileTypes: true })) {
+    for (const entry of fs7.readdirSync(dir, { withFileTypes: true })) {
       if (entry.name.startsWith(".") || skip.has(entry.name)) continue;
-      const abs = path7.join(dir, entry.name);
+      const abs = path8.join(dir, entry.name);
       if (entry.isDirectory()) walk(abs);
       else if (entry.name.endsWith(".malloy")) {
-        const rel = path7.relative(root, abs).split(path7.sep).join("/");
-        files[`file:///${rel}`] = fs6.readFileSync(abs, "utf8");
+        const rel = path8.relative(root, abs).split(path8.sep).join("/");
+        files[`file:///${rel}`] = fs7.readFileSync(abs, "utf8");
       }
     }
   };
@@ -3359,12 +3614,12 @@ function copyDuckDBAssets(outDir) {
     "duckdb-browser-mvp.worker.js",
     "duckdb-browser-eh.worker.js"
   ];
-  const dir = path7.join(outDir, "duckdb");
-  fs6.mkdirSync(dir, { recursive: true });
+  const dir = path8.join(outDir, "duckdb");
+  fs7.mkdirSync(dir, { recursive: true });
   const copied = [];
   for (const n of names) {
     const src = require3.resolve(`@duckdb/duckdb-wasm/dist/${n}`);
-    fs6.copyFileSync(src, path7.join(dir, n));
+    fs7.copyFileSync(src, path8.join(dir, n));
     copied.push(n);
   }
   return copied;
@@ -3463,37 +3718,37 @@ body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.5 -apple-system,B
 .index span{font-size:13px;color:var(--muted)}
 ` + NAV_CSS;
 async function bundleDashboards(opts = {}) {
-  const root = path7.resolve(opts.root ?? process.cwd());
-  const outDir = path7.resolve(root, opts.out ?? "docs");
-  const title = opts.title ?? path7.basename(root);
+  const root = path8.resolve(opts.root ?? process.cwd());
+  const outDir = path8.resolve(root, opts.out ?? "docs");
+  const title = opts.title ?? path8.basename(root);
   const target = opts.target ?? "pages";
   const analytics = opts.analytics ?? readSiteConfig(root).analytics;
   const cleanUrls = target === "vercel";
   const selfHostDuckdb = opts.duckdb === "bundled";
   const runner = await makeRunner(root);
   const dashboards = await discoverDashboards(root, runner);
-  if (dashboards.length === 0) throw new Error(`no dashboards found in ${path7.join(root, "dashboards")}`);
-  const manifestPath = path7.join(outDir, ".bundle-manifest.json");
+  if (dashboards.length === 0) throw new Error(`no dashboards found in ${path8.join(root, "dashboards")}`);
+  const manifestPath = path8.join(outDir, ".bundle-manifest.json");
   let priorData = [];
   try {
-    priorData = JSON.parse(fs6.readFileSync(manifestPath, "utf8")).dataFiles ?? [];
+    priorData = JSON.parse(fs7.readFileSync(manifestPath, "utf8")).dataFiles ?? [];
   } catch {
   }
   for (const sub of ["assets", "duckdb"]) {
-    fs6.rmSync(path7.join(outDir, sub), { recursive: true, force: true });
+    fs7.rmSync(path8.join(outDir, sub), { recursive: true, force: true });
   }
-  if (fs6.existsSync(outDir)) {
-    for (const f of fs6.readdirSync(outDir)) {
-      if (f.endsWith(".html")) fs6.rmSync(path7.join(outDir, f), { force: true });
+  if (fs7.existsSync(outDir)) {
+    for (const f of fs7.readdirSync(outDir)) {
+      if (f.endsWith(".html")) fs7.rmSync(path8.join(outDir, f), { force: true });
     }
   }
-  fs6.mkdirSync(path7.join(outDir, "assets"), { recursive: true });
+  fs7.mkdirSync(path8.join(outDir, "assets"), { recursive: true });
   if (target === "pages") {
-    fs6.writeFileSync(path7.join(outDir, ".nojekyll"), "");
+    fs7.writeFileSync(path8.join(outDir, ".nojekyll"), "");
   } else {
-    fs6.rmSync(path7.join(outDir, ".nojekyll"), { force: true });
-    fs6.writeFileSync(
-      path7.join(outDir, "vercel.json"),
+    fs7.rmSync(path8.join(outDir, ".nojekyll"), { force: true });
+    fs7.writeFileSync(
+      path8.join(outDir, "vercel.json"),
       JSON.stringify(
         {
           $schema: "https://openapi.vercel.sh/vercel.json",
@@ -3515,53 +3770,53 @@ async function bundleDashboards(opts = {}) {
     );
   }
   const modelFiles = inlineModelFiles(root);
-  const outRel = path7.relative(root, outDir).split(path7.sep).join("/");
+  const outRel = path8.relative(root, outDir).split(path8.sep).join("/");
   const usedFiles = reachableModelFiles(
     modelFiles,
     dashboards.map((d) => d.entryFile).filter((f) => !!f)
   );
   const { map: tableFiles, copies } = tableFilePlan(usedFiles, outRel);
   for (const rel of copies) {
-    const from = path7.join(root, rel);
-    if (!fs6.existsSync(from)) {
+    const from = path8.join(root, rel);
+    if (!fs7.existsSync(from)) {
       throw new Error(
         `model reads '${rel}' but ${from} does not exist.
 Data files are referenced by a path relative to the project root.`
       );
     }
-    const to = path7.join(outDir, rel);
-    fs6.mkdirSync(path7.dirname(to), { recursive: true });
-    fs6.copyFileSync(from, to);
+    const to = path8.join(outDir, rel);
+    fs7.mkdirSync(path8.dirname(to), { recursive: true });
+    fs7.copyFileSync(from, to);
   }
   const copiedData = copies;
   for (const stale of priorData) {
     if (copies.includes(stale)) continue;
-    fs6.rmSync(path7.join(outDir, stale), { force: true });
+    fs7.rmSync(path8.join(outDir, stale), { force: true });
     try {
-      fs6.rmdirSync(path7.dirname(path7.join(outDir, stale)));
+      fs7.rmdirSync(path8.dirname(path8.join(outDir, stale)));
     } catch {
     }
     console.log(`  removed stale ${stale}`);
   }
-  fs6.writeFileSync(manifestPath, JSON.stringify({ dataFiles: copies }, null, 2) + "\n");
-  fs6.writeFileSync(
-    path7.join(outDir, "assets", "model-files.js"),
+  fs7.writeFileSync(manifestPath, JSON.stringify({ dataFiles: copies }, null, 2) + "\n");
+  fs7.writeFileSync(
+    path8.join(outDir, "assets", "model-files.js"),
     `window.__MODEL_FILES__ = ${JSON.stringify(modelFiles)};
 window.__TABLE_FILES__ = ${JSON.stringify(tableFiles)};
 ` + (selfHostDuckdb ? `window.__DUCKDB_BASE__ = "./duckdb/";
 ` : "")
   );
-  const landing = ["jsx", "tsx"].map((ext) => path7.join(root, "dashboards", `index.${ext}`)).find((f) => fs6.existsSync(f));
+  const landing = ["jsx", "tsx"].map((ext) => path8.join(root, "dashboards", `index.${ext}`)).find((f) => fs7.existsSync(f));
   const runtimeDir = resolveRuntimeDir();
-  const runtimeIndex = path7.join(runtimeDir, "index.ts");
-  const wasmEntry = path7.join(runtimeDir, "..", "frame-wasm-entry.tsx");
+  const runtimeIndex = path8.join(runtimeDir, "index.ts");
+  const wasmEntry = path8.join(runtimeDir, "..", "frame-wasm-entry.tsx");
   const byEntry = new Map(dashboards.map((d) => [`vdash:${d.name}`, d]));
   await esbuild3.build({
     entryPoints: Object.fromEntries(dashboards.map((d) => [d.name, `vdash:${d.name}`])),
     bundle: true,
     splitting: true,
     format: "esm",
-    outdir: path7.join(outDir, "assets"),
+    outdir: path8.join(outDir, "assets"),
     minify: true,
     logLevel: "warning",
     ...browserBuildBase(),
@@ -3582,7 +3837,7 @@ boot(Dashboard);
               loader: "js",
               // Resolve the component's own imports (react, @malloyyo/dashboard)
               // from the model repo's directory, matching `dashboard dev`.
-              resolveDir: path7.dirname(dash.tsxPath ?? path7.join(root, "dashboards", "x"))
+              resolveDir: path8.dirname(dash.tsxPath ?? path8.join(root, "dashboards", "x"))
             };
           });
           b.onResolve({ filter: /^@malloyyo\/dashboard$/ }, () => ({ path: runtimeIndex }));
@@ -3591,7 +3846,7 @@ boot(Dashboard);
       hostAliasPlugin
     ]
   });
-  fs6.writeFileSync(path7.join(outDir, "assets", "site.css"), SITE_CSS);
+  fs7.writeFileSync(path8.join(outDir, "assets", "site.css"), SITE_CSS);
   for (const d of dashboards) {
     let specs = [];
     let tileSpecs;
@@ -3604,9 +3859,9 @@ boot(Dashboard);
       if (!got.ok) throw new Error(`dashboard ${d.name}: ${got.error}`);
       specs = got.givens;
     }
-    fs6.writeFileSync(path7.join(outDir, `${d.name}.html`), page(d, dashboards, title, specs, tileSpecs, cleanUrls, analytics));
+    fs7.writeFileSync(path8.join(outDir, `${d.name}.html`), page(d, dashboards, title, specs, tileSpecs, cleanUrls, analytics));
   }
-  fs6.writeFileSync(path7.join(outDir, "index.html"), indexPage(dashboards, title, !!landing, cleanUrls, analytics));
+  fs7.writeFileSync(path8.join(outDir, "index.html"), indexPage(dashboards, title, !!landing, cleanUrls, analytics));
   if (landing) {
     await esbuild3.build({
       stdin: {
@@ -3615,13 +3870,13 @@ import { createRoot } from "react-dom/client";
 import Landing from ${JSON.stringify(landing)};
 createRoot(document.getElementById("root")).render(React.createElement(Landing, { dashboards: window.__DASHBOARDS__ || [] }));
 `,
-        resolveDir: path7.dirname(landing),
+        resolveDir: path8.dirname(landing),
         loader: "js"
       },
       bundle: true,
       format: "esm",
       minify: true,
-      outfile: path7.join(outDir, "assets", "index.js"),
+      outfile: path8.join(outDir, "assets", "index.js"),
       logLevel: "warning",
       // Same base as the dashboard pass. A landing page needs no Malloy today,
       // but one that imported anything reaching antlr4ts would otherwise die at
@@ -3631,12 +3886,12 @@ createRoot(document.getElementById("root")).render(React.createElement(Landing,
     });
   }
   const duck = selfHostDuckdb ? copyDuckDBAssets(outDir) : [];
-  if (!selfHostDuckdb) fs6.rmSync(path7.join(outDir, "duckdb"), { recursive: true, force: true });
-  const bytes = (p) => fs6.statSync(p).size;
-  const assetDir = path7.join(outDir, "assets");
-  const jsTotal = fs6.readdirSync(assetDir).filter((f) => f.endsWith(".js")).reduce((a, f) => a + bytes(path7.join(assetDir, f)), 0);
+  if (!selfHostDuckdb) fs7.rmSync(path8.join(outDir, "duckdb"), { recursive: true, force: true });
+  const bytes = (p) => fs7.statSync(p).size;
+  const assetDir = path8.join(outDir, "assets");
+  const jsTotal = fs7.readdirSync(assetDir).filter((f) => f.endsWith(".js")).reduce((a, f) => a + bytes(path8.join(assetDir, f)), 0);
   console.log(`
-bundled ${dashboards.length} dashboard(s) \u2192 ${path7.relative(process.cwd(), outDir) || "."}/`);
+bundled ${dashboards.length} dashboard(s) \u2192 ${path8.relative(process.cwd(), outDir) || "."}/`);
   for (const d of dashboards) console.log(`  ${d.name}.html   ${d.title ?? ""}`);
   console.log(`
   js         ${(jsTotal / 1048576).toFixed(2)} MB`);
@@ -3646,13 +3901,13 @@ bundled ${dashboards.length} dashboard(s) \u2192 ${path7.relative(process.cwd(),
   console.log(`  model      ${Object.keys(modelFiles).length} .malloy files inlined`);
   if (analytics) console.log(`  analytics  ${analytics}`);
   if (copiedData.length) {
-    const mb = copiedData.reduce((a, r) => a + fs6.statSync(path7.join(root, r)).size, 0) / 1048576;
+    const mb = copiedData.reduce((a, r) => a + fs7.statSync(path8.join(root, r)).size, 0) / 1048576;
     console.log(`  data       ${copiedData.length} file(s) copied, ${mb.toFixed(1)} MB (same-origin)`);
   }
   console.log(
     target === "pages" ? `
-Publish: commit ${path7.basename(outDir)}/ and point GitHub Pages at it.` : `
-Publish: deploy ${path7.basename(outDir)}/ to Vercel (vercel.json written: clean URLs + asset caching).`
+Publish: commit ${path8.basename(outDir)}/ and point GitHub Pages at it.` : `
+Publish: deploy ${path8.basename(outDir)}/ to Vercel (vercel.json written: clean URLs + asset caching).`
   );
   if (opts.serve !== false) {
     await serveStatic(outDir, opts.port ?? 4180);
@@ -3662,8 +3917,8 @@ Publish: deploy ${path7.basename(outDir)}/ to Vercel (vercel.json written: clean
 }
 
 // src/init.ts
-import fs7 from "node:fs";
-import path8 from "node:path";
+import fs8 from "node:fs";
+import path9 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 var AUTHOR_SERVER = "malloyyo_author";
 var AUTHOR_MCP = {
@@ -3698,11 +3953,11 @@ function withAuthorPermissions(input) {
   return { settings, added };
 }
 function allowAuthorTools(root) {
-  const file = path8.join(root, ".claude", "settings.json");
+  const file = path9.join(root, ".claude", "settings.json");
   let existing;
-  if (fs7.existsSync(file)) {
+  if (fs8.existsSync(file)) {
     try {
-      existing = JSON.parse(fs7.readFileSync(file, "utf8"));
+      existing = JSON.parse(fs8.readFileSync(file, "utf8"));
     } catch {
       return { added: [], note: ".claude/settings.json isn't valid JSON \u2014 left as-is" };
     }
@@ -3710,8 +3965,8 @@ function allowAuthorTools(root) {
   const merged = withAuthorPermissions(existing);
   if ("error" in merged) return { added: [], note: `${merged.error} \u2014 left as-is` };
   if (merged.added.length === 0) return { added: [] };
-  fs7.mkdirSync(path8.dirname(file), { recursive: true });
-  fs7.writeFileSync(file, JSON.stringify(merged.settings, null, 2) + "\n");
+  fs8.mkdirSync(path9.dirname(file), { recursive: true });
+  fs8.writeFileSync(file, JSON.stringify(merged.settings, null, 2) + "\n");
   return { added: merged.added };
 }
 function exportableNames(src) {
@@ -3726,11 +3981,11 @@ function exportableNames(src) {
   return [...names];
 }
 function scaffoldIndex(root) {
-  const indexPath = path8.join(root, "index.malloy");
-  if (fs7.existsSync(indexPath)) {
+  const indexPath = path9.join(root, "index.malloy");
+  if (fs8.existsSync(indexPath)) {
     return { wrote: false, note: "index.malloy already exists \u2014 left as-is" };
   }
-  const models = fs7.readdirSync(root).filter((f) => f.endsWith(".malloy") && f !== "index.malloy").sort();
+  const models = fs8.readdirSync(root).filter((f) => f.endsWith(".malloy") && f !== "index.malloy").sort();
   if (models.length === 0) {
     return { wrote: false, note: "no .malloy files found \u2014 skipped index.malloy" };
   }
@@ -3743,7 +3998,7 @@ function scaffoldIndex(root) {
   ];
   let anyNames = false;
   for (const file of models) {
-    const names = exportableNames(fs7.readFileSync(path8.join(root, file), "utf8"));
+    const names = exportableNames(fs8.readFileSync(path9.join(root, file), "utf8"));
     if (names.length === 0) {
       blocks.push(`// ${file}: no top-level source/query/given detected \u2014 add exports by hand`);
       continue;
@@ -3754,49 +4009,49 @@ function scaffoldIndex(root) {
     blocks.push(`export { ${list} }`);
     blocks.push("");
   }
-  fs7.writeFileSync(indexPath, blocks.join("\n") + "\n");
+  fs8.writeFileSync(indexPath, blocks.join("\n") + "\n");
   return {
     wrote: true,
     note: anyNames ? `wrote index.malloy re-exporting ${models.length} model file(s) \u2014 REVIEW it` : "wrote index.malloy skeleton \u2014 no exports detected, fill them in by hand"
   };
 }
 function installSkills(root) {
-  const distDir = path8.dirname(fileURLToPath2(import.meta.url));
+  const distDir = path9.dirname(fileURLToPath2(import.meta.url));
   const candidates = [
-    path8.join(distDir, "templates", "skills"),
-    path8.join(distDir, "..", "src", "templates", "skills")
+    path9.join(distDir, "templates", "skills"),
+    path9.join(distDir, "..", "src", "templates", "skills")
   ];
-  const srcSkills = candidates.find((p) => fs7.existsSync(p));
+  const srcSkills = candidates.find((p) => fs8.existsSync(p));
   if (!srcSkills) return { wrote: [], skipped: [], note: "no skill templates found \u2014 skipped" };
-  const destSkills = path8.join(root, ".claude", "skills");
-  fs7.mkdirSync(destSkills, { recursive: true });
+  const destSkills = path9.join(root, ".claude", "skills");
+  fs8.mkdirSync(destSkills, { recursive: true });
   const wrote = [];
   const skipped = [];
-  for (const name of fs7.readdirSync(srcSkills)) {
-    const from = path8.join(srcSkills, name);
-    if (!fs7.statSync(from).isDirectory()) continue;
-    const to = path8.join(destSkills, name);
-    if (fs7.existsSync(to)) {
+  for (const name of fs8.readdirSync(srcSkills)) {
+    const from = path9.join(srcSkills, name);
+    if (!fs8.statSync(from).isDirectory()) continue;
+    const to = path9.join(destSkills, name);
+    if (fs8.existsSync(to)) {
       skipped.push(name);
       continue;
     }
-    fs7.cpSync(from, to, { recursive: true });
+    fs8.cpSync(from, to, { recursive: true });
     wrote.push(name);
   }
   return { wrote, skipped };
 }
 async function initCmd(dir) {
-  const root = path8.resolve(dir);
-  if (!fs7.existsSync(root) || !fs7.statSync(root).isDirectory()) {
+  const root = path9.resolve(dir);
+  if (!fs8.existsSync(root) || !fs8.statSync(root).isDirectory()) {
     throw new Error(`not a directory: ${root}`);
   }
-  const mcpPath = path8.join(root, ".mcp.json");
-  if (fs7.existsSync(mcpPath)) {
+  const mcpPath = path9.join(root, ".mcp.json");
+  if (fs8.existsSync(mcpPath)) {
     console.log(`\u2022 .mcp.json exists \u2014 leaving it. For author-by-default it should be:`);
     console.log(`    ${JSON.stringify(AUTHOR_MCP.mcpServers.malloyyo_author)}`);
     console.log(`  (server key "malloyyo_author", command "malloyyo mcp --develop").`);
   } else {
-    fs7.writeFileSync(mcpPath, JSON.stringify(AUTHOR_MCP, null, 2) + "\n");
+    fs8.writeFileSync(mcpPath, JSON.stringify(AUTHOR_MCP, null, 2) + "\n");
     console.log(`\u2713 wrote .mcp.json \u2014 \`cd ${dir} && claude\` now opens in AUTHOR mode`);
   }
   const idx = scaffoldIndex(root);
@@ -3830,27 +4085,45 @@ async function initCmd(dir) {
 }
 
 // src/sql.ts
-import fs8 from "node:fs";
-import path9 from "node:path";
-import url4 from "node:url";
-import { MalloyConfig as MalloyConfig3, discoverConfig as discoverConfig3 } from "@malloydata/malloy";
+import fs9 from "node:fs";
+import path10 from "node:path";
+import url5 from "node:url";
+import { MalloyConfig as MalloyConfig3, Runtime as Runtime3, discoverConfig as discoverConfig3 } from "@malloydata/malloy";
 function fileReader() {
   return {
     readURL: async (u) => {
       if (u.protocol !== "file:") {
         throw new Error(`unsupported URL scheme for import: ${u.href}`);
       }
-      return fs8.promises.readFile(u, "utf8");
+      return fs9.promises.readFile(u, "utf8");
     }
   };
 }
 async function loadConfig3(rootDir) {
-  const rootUrl = url4.pathToFileURL(rootDir.endsWith(path9.sep) ? rootDir : rootDir + path9.sep);
+  const rootUrl = url5.pathToFileURL(rootDir.endsWith(path10.sep) ? rootDir : rootDir + path10.sep);
   const discovered = await discoverConfig3(rootUrl, rootUrl, fileReader()).catch(() => null);
   return discovered ?? new MalloyConfig3({ includeDefaultConnections: true }, {
     rootDirectory: rootUrl.toString()
   });
 }
+var TYPED_ROW_CAP = 1e6;
+function malloyStringLiteral(sql) {
+  const body = sql.trim().replace(/;\s*$/, "") + "\n";
+  const escaped = body.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\r/g, "\\r").replace(/\n/g, "\\n").replace(/\t/g, "\\t");
+  return `"${escaped}"`;
+}
+async function runTyped(cfg, name, sql) {
+  if (name.includes("`")) return null;
+  try {
+    const runtime = new Runtime3({ config: cfg, urlReader: fileReader() });
+    const query = `run: \`${name}\`.sql(${malloyStringLiteral(sql)})`;
+    const result = await runtime.loadQuery(query).run({ rowLimit: TYPED_ROW_CAP });
+    const rows = jsonRows(result);
+    return rows.length >= TYPED_ROW_CAP ? null : rows;
+  } catch {
+    return null;
+  }
+}
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) chunks.push(chunk);
@@ -3858,22 +4131,25 @@ async function readStdin() {
 }
 async function resolveSql(opts) {
   if (opts.execute != null) return opts.execute;
-  if (opts.file) return fs8.promises.readFile(opts.file, "utf8");
+  if (opts.file) return fs9.promises.readFile(opts.file, "utf8");
   return readStdin();
 }
 async function sqlCmd(connection, opts) {
   const name = connection ?? "duckdb";
-  const rootDir = path9.resolve(opts.root ?? ".");
+  const rootDir = path10.resolve(opts.root ?? ".");
   const sql = (await resolveSql(opts)).trim();
   if (!sql) {
     throw new Error("no SQL provided \u2014 pass -e <sql>, -f <file>, or pipe it via stdin");
   }
-  await import("@malloydata/malloy-connections");
+  await initConnections();
   const cfg = await loadConfig3(rootDir);
   try {
-    const conn = await cfg.connections.lookupConnection(name);
-    const result = await conn.runSQL(sql);
-    const rows = result?.rows ?? [];
+    let rows = await runTyped(cfg, name, sql);
+    if (rows === null) {
+      const conn = await withConnectionDiagnostics(() => cfg.connections.lookupConnection(name));
+      const result = await conn.runSQL(sql);
+      rows = result?.rows ?? [];
+    }
     if (opts.json) {
       process.stdout.write(JSON.stringify(rows, null, 2) + "\n");
     } else if (rows.length === 0) {
@@ -3888,22 +4164,22 @@ async function sqlCmd(connection, opts) {
 
 // src/launch.ts
 import { spawn as spawn2 } from "node:child_process";
-import fs9 from "node:fs";
+import fs10 from "node:fs";
 import os from "node:os";
-import path10 from "node:path";
+import path11 from "node:path";
 var SURFACE_FLAG = { author: "--develop", test: "--explore" };
 var SERVER_KEY = { author: "malloyyo_author", test: "malloyyo_test" };
 async function launchCmd(mode, opts) {
-  const root = path10.resolve(opts.root ?? process.cwd());
-  const tmpDir = fs9.mkdtempSync(path10.join(os.tmpdir(), "malloyyo-launch-"));
-  const cfgPath = path10.join(tmpDir, "mcp.json");
+  const root = path11.resolve(opts.root ?? process.cwd());
+  const tmpDir = fs10.mkdtempSync(path11.join(os.tmpdir(), "malloyyo-launch-"));
+  const cfgPath = path11.join(tmpDir, "mcp.json");
   const cfg = {
     mcpServers: {
       // Absolute -C: an ephemeral config, so pinning the root is robust.
       [SERVER_KEY[mode]]: { command: "malloyyo", args: ["mcp", SURFACE_FLAG[mode], "-C", root] }
     }
   };
-  fs9.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2));
+  fs10.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2));
   const label = mode === "author" ? "AUTHOR (compile/edit)" : "TEST (claude.ai web preview)";
   process.stderr.write(`\u25B6 launching Claude in ${label} mode over ${root}
 `);
@@ -3922,11 +4198,11 @@ async function launchCmd(mode, opts) {
     });
     child.on("exit", () => resolve3());
   });
-  fs9.rmSync(tmpDir, { recursive: true, force: true });
+  fs10.rmSync(tmpDir, { recursive: true, force: true });
 }
 
 // package.json
-var version = "0.2.27";
+var version = "0.2.29";
 
 // src/index.ts
 function shortSha(sha) {