@malloydata/malloyyo 0.2.0

package/dist/index.js

@@ -0,0 +1,1895 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+import { resolve } from "node:path";
+
+// src/config.ts
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+function readTargetMap(dir) {
+  const malloyConfig = join(dir, "malloy-config.json");
+  if (existsSync(malloyConfig)) {
+    const json = JSON.parse(readFileSync(malloyConfig, "utf8"));
+    if (json.malloyyo && typeof json.malloyyo === "object") return json.malloyyo;
+  }
+  const standalone = join(dir, "malloyyo.json");
+  if (existsSync(standalone)) {
+    return JSON.parse(readFileSync(standalone, "utf8"));
+  }
+  throw new Error(
+    `No \`malloyyo\` config found in ${dir} (looked for a "malloyyo" block in malloy-config.json, then malloyyo.json).`
+  );
+}
+var normalizeUrl = (u) => u.replace(/\/+$/, "");
+function resolveTarget(dir, name) {
+  const targets = readTargetMap(dir);
+  const cfg = targets[name];
+  if (!cfg) {
+    const available = Object.keys(targets).join(", ") || "(none defined)";
+    throw new Error(`Unknown target "${name}". Available: ${available}`);
+  }
+  return {
+    name,
+    url: normalizeUrl(cfg.url),
+    dataset: cfg.dataset,
+    tokenEnv: cfg.malloyyo_token?.env
+  };
+}
+function resolveInstance(dir, arg) {
+  if (arg && /^https?:\/\//i.test(arg)) {
+    const url3 = normalizeUrl(arg);
+    return { name: url3, url: url3 };
+  }
+  const targets = readTargetMap(dir);
+  const entries = Object.entries(targets);
+  if (arg) {
+    const cfg = targets[arg];
+    if (!cfg) {
+      const available = entries.map(([n]) => n).join(", ") || "(none defined)";
+      throw new Error(`Unknown target "${arg}". Pass a target name, a URL, or one of: ${available}`);
+    }
+    return { name: arg, url: normalizeUrl(cfg.url) };
+  }
+  if (entries.length === 0) throw new Error("No targets defined. Pass a target name or a URL.");
+  if (entries.length === 1) return { name: entries[0][0], url: normalizeUrl(entries[0][1].url) };
+  const urls = new Set(entries.map(([, c]) => normalizeUrl(c.url)));
+  if (urls.size === 1) return { name: entries.map(([n]) => n).join("/"), url: [...urls][0] };
+  throw new Error(`Multiple targets \u2014 specify which: ${entries.map(([n]) => n).join(", ")} (or a URL).`);
+}
+
+// src/gather.ts
+import { readFileSync as readFileSync2, existsSync as existsSync2, readdirSync, statSync } from "node:fs";
+import { join as join2, relative, sep } from "node:path";
+import { execFileSync } from "node:child_process";
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git"]);
+function gatherDirectory(dir) {
+  const files = [];
+  const walk = (cur) => {
+    for (const entry of readdirSync(cur)) {
+      if (entry.startsWith(".") || SKIP_DIRS.has(entry)) continue;
+      const full = join2(cur, entry);
+      if (statSync(full).isDirectory()) {
+        walk(full);
+      } else if (entry.endsWith(".malloy")) {
+        files.push({
+          path: relative(dir, full).split(sep).join("/"),
+          content: readFileSync2(full, "utf8")
+        });
+      }
+    }
+  };
+  walk(dir);
+  const configPath = join2(dir, "malloy-config.json");
+  const config = existsSync2(configPath) ? readFileSync2(configPath, "utf8") : void 0;
+  return { files, config };
+}
+function gitInfo(dir) {
+  const git = (args) => execFileSync("git", args, {
+    cwd: dir,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+    // suppress git's own stderr (e.g. "no remote 'origin'")
+  }).trim();
+  try {
+    let repo;
+    try {
+      repo = git(["remote", "get-url", "origin"]).replace(
+        /^.*[:/]([^/]+\/[^/]+?)(?:\.git)?$/,
+        "$1"
+      );
+    } catch {
+    }
+    return {
+      repo,
+      branch: git(["rev-parse", "--abbrev-ref", "HEAD"]),
+      sha: git(["rev-parse", "HEAD"]),
+      dirty: git(["status", "--porcelain"]).length > 0
+    };
+  } catch {
+    return {};
+  }
+}
+
+// src/oauth.ts
+import http from "node:http";
+import crypto from "node:crypto";
+import { spawn } from "node:child_process";
+
+// src/store.ts
+import { homedir } from "node:os";
+import { dirname, join as join3 } from "node:path";
+import { mkdirSync, readFileSync as readFileSync3, writeFileSync, existsSync as existsSync3, chmodSync } from "node:fs";
+function credsPath() {
+  const base = process.env.XDG_CONFIG_HOME || join3(homedir(), ".config");
+  return join3(base, "malloyyo", "credentials.json");
+}
+function readAll() {
+  const p = credsPath();
+  if (!existsSync3(p)) return {};
+  try {
+    return JSON.parse(readFileSync3(p, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function loadCreds(url3) {
+  return readAll()[url3];
+}
+function saveCreds(url3, creds) {
+  const p = credsPath();
+  mkdirSync(dirname(p), { recursive: true });
+  const all = readAll();
+  all[url3] = creds;
+  writeFileSync(p, JSON.stringify(all, null, 2) + "\n", { mode: 384 });
+  try {
+    chmodSync(p, 384);
+  } catch {
+  }
+}
+function clearCreds(url3) {
+  const all = readAll();
+  if (!(url3 in all)) return false;
+  delete all[url3];
+  writeFileSync(credsPath(), JSON.stringify(all, null, 2) + "\n", { mode: 384 });
+  return true;
+}
+
+// src/oauth.ts
+var LOGIN_TIMEOUT_MS = 5 * 60 * 1e3;
+async function discover(baseUrl) {
+  const res = await fetch(`${baseUrl}/api/oauth/discovery/authorization-server`);
+  if (!res.ok) throw new Error(`OAuth discovery failed at ${baseUrl}: ${res.status} ${res.statusText}`);
+  return await res.json();
+}
+function pkce() {
+  const verifier = crypto.randomBytes(32).toString("base64url");
+  const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+async function registerClient(registrationEndpoint, redirectUri) {
+  const res = await fetch(registrationEndpoint, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      client_name: "malloyyo CLI",
+      redirect_uris: [redirectUri],
+      token_endpoint_auth_method: "none",
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      scope: "mcp"
+    })
+  });
+  if (!res.ok) throw new Error(`client registration failed: ${res.status} ${await res.text()}`);
+  return (await res.json()).client_id;
+}
+function openBrowser(url3) {
+  const [cmd, args] = process.platform === "darwin" ? ["open", [url3]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url3]] : ["xdg-open", [url3]];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+  } catch {
+  }
+}
+function awaitRedirect(state) {
+  return new Promise((resolveServer) => {
+    let resolveCode;
+    let rejectCode;
+    const code = new Promise((res, rej) => {
+      resolveCode = res;
+      rejectCode = rej;
+    });
+    const timer = setTimeout(() => rejectCode(new Error("timed out waiting for browser sign-in")), LOGIN_TIMEOUT_MS);
+    const server = http.createServer((req, res) => {
+      const u = new URL(req.url ?? "/", "http://localhost");
+      if (u.pathname !== "/callback") {
+        res.writeHead(404).end();
+        return;
+      }
+      const err = u.searchParams.get("error");
+      const got = u.searchParams.get("code");
+      const ok = !err && !!got && u.searchParams.get("state") === state;
+      res.writeHead(ok ? 200 : 400, { "content-type": "text/html" });
+      res.end(
+        `<!doctype html><meta charset="utf-8"><body style="font-family:system-ui;padding:3rem;text-align:center"><h2>${ok ? "\u2713 Signed in to malloyyo" : "Sign-in failed"}</h2><p>${ok ? "You can close this tab and return to the terminal." : err ?? "state mismatch"}</p></body>`
+      );
+      clearTimeout(timer);
+      if (ok) resolveCode(got);
+      else rejectCode(new Error(err ?? "state mismatch or missing code"));
+    });
+    server.listen(0, "127.0.0.1", () => {
+      const port = server.address().port;
+      resolveServer({ port, code, close: () => server.close() });
+    });
+  });
+}
+async function login(baseUrl) {
+  const ep = await discover(baseUrl);
+  const { verifier, challenge } = pkce();
+  const state = crypto.randomBytes(16).toString("base64url");
+  const { port, code, close } = await awaitRedirect(state);
+  try {
+    const redirectUri = `http://localhost:${port}/callback`;
+    const clientId = await registerClient(ep.registration_endpoint, redirectUri);
+    const authUrl = new URL(ep.authorization_endpoint);
+    authUrl.search = new URLSearchParams({
+      response_type: "code",
+      client_id: clientId,
+      redirect_uri: redirectUri,
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+      scope: "mcp",
+      state
+    }).toString();
+    console.log("Opening your browser to sign in\u2026");
+    console.log(`If it doesn't open, visit:
+  ${authUrl.toString()}
+`);
+    openBrowser(authUrl.toString());
+    const authCode = await code;
+    const res = await fetch(ep.token_endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        code: authCode,
+        redirect_uri: redirectUri,
+        client_id: clientId,
+        code_verifier: verifier
+      })
+    });
+    if (!res.ok) throw new Error(`token exchange failed: ${res.status} ${await res.text()}`);
+    const grant = await res.json();
+    const creds = {
+      clientId,
+      accessToken: grant.access_token,
+      refreshToken: grant.refresh_token,
+      expiresAt: Date.now() + (grant.expires_in ?? 86400) * 1e3
+    };
+    saveCreds(baseUrl, creds);
+    return creds;
+  } finally {
+    close();
+  }
+}
+async function refresh(baseUrl, creds) {
+  const ep = await discover(baseUrl);
+  const res = await fetch(ep.token_endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: creds.refreshToken,
+      client_id: creds.clientId
+    })
+  });
+  if (!res.ok) throw new Error(`refresh failed: ${res.status}`);
+  const grant = await res.json();
+  const updated = {
+    clientId: creds.clientId,
+    accessToken: grant.access_token,
+    refreshToken: grant.refresh_token,
+    expiresAt: Date.now() + (grant.expires_in ?? 86400) * 1e3
+  };
+  saveCreds(baseUrl, updated);
+  return updated;
+}
+async function getAccessToken(target, opts) {
+  if (opts.tokenFlag) return opts.tokenFlag;
+  if (target.tokenEnv && process.env[target.tokenEnv]) return process.env[target.tokenEnv];
+  let creds = loadCreds(target.url);
+  if (!creds) {
+    throw new Error(`Not authenticated for ${target.url}.
+Run:  malloyyo login ${target.name}`);
+  }
+  if (creds.expiresAt - Date.now() < 6e4) {
+    try {
+      creds = await refresh(target.url, creds);
+    } catch {
+      throw new Error(`Session expired for ${target.url}.
+Run:  malloyyo login ${target.name}`);
+    }
+  }
+  return creds.accessToken;
+}
+
+// src/mcp.ts
+import fs from "node:fs";
+import path2 from "node:path";
+import url2 from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  MalloyConfig,
+  Runtime,
+  discoverConfig
+} from "@malloydata/malloy";
+
+// ../mcp-engine/dist/index.js
+import {
+  MalloyError,
+  expressionIsAggregate,
+  expressionIsAnalytic
+} from "@malloydata/malloy";
+import { prettify as internalPrettify } from "@malloydata/malloy/internal";
+import { API, MalloyError as MalloyError2 } from "@malloydata/malloy";
+import { MalloyError as MalloyError3 } from "@malloydata/malloy";
+import path from "node:path";
+import url from "node:url";
+var HOST_ONLY = "host_only";
+var contentFiles = {
+  "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',
+  "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* `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.",
+  "explore/restricted-queries.md": "# Restricted Query Explanation\n\nThe `query` tool runs your Malloy against a **published model**. You have that\nmodel's entire published surface to work with \u2014 and you can build on it. The\nmodel is an inentionally curated subset of the data available in the\ndatabase.\n\n## You can\n\n- Use everything the model defines: its **sources, dimensions, measures, views,\n  joins, and named queries**. `describe_source` shows exactly what's there.\n- **Run a named query and refine it** \u2014\n  `run: top_carriers + { where: dep_year = 2024 }`.\n- **Define your own** dimensions, measures, and **your own sources and joins** \u2014\n  as long as they are *derived from the model's sources*. You are not limited to\n  the author's fields; compose new ones from them.\n- Reference the model's `$NAME` givens and supply values via the `givens` map on\n  the `query` call (use `execute: false` to discover which a query needs).\n- Use a model field that was itself defined with raw SQL \u2014 the author vouched\n  for the model's own definitions.\n\n## What is \"Restricted\"\n\nIf you see `restricted-construct-forbidden`, the query used something that\nreaches *outside* the published model: pulling in another file (`import`),\nopening a raw connection (`connection.table(...)` / `connection.sql(...)`),\nwriting raw SQL (`name!type(...)` or the `sql_*` functions), declaring new\n`given:`s, or setting `##!` compiler flags.\n\nThe fix is never to work around it \u2014 express the answer in terms of what the\nmodel publishes (define derived sources, joins, dimensions, and measures from\nthe model's sources). If something fundamental is missing, that's feedback for\nthe model's author.\n",
+  "language/malloy-language-reference.md": '<!-- Copied from malloy-cli (jrtipton/malloy-cli) skills/malloy-language-reference.md on 2026-06-11.\n     Deliberate temporary fork \u2014 converge when the engine is extracted to @malloydata. -->\n---\ndescription: Malloy language reference \u2014 concepts, syntax, compilation model. Load this before writing or reviewing Malloy code.\n---\n# Malloy Language Reference\n\nMalloy is a semantic data modeling and query language. It compiles to SQL and runs against existing database engines (DuckDB, BigQuery, Snowflake, PostgreSQL, MySQL, Trino, Presto). It is not a SQL wrapper or abstraction layer \u2014 it has its own type system, scoping rules, expression semantics, and compilation pipeline.\n\nMalloy is designed around how humans think about data, not how data computations are mechanically accomplished. SQL is oriented around the machine \u2014 you specify joins, group-by columns, subqueries, and window functions in terms of what the database needs to do. Malloy is oriented around the analyst \u2014 you describe relationships, name computations, and compose questions in terms of what the data means. Malloy bridges the gap between these two by compiling the human-oriented description into correct, efficient SQL.\n\nA core design principle is that **most queries are themselves designing a new semantic model.** Formulating a question about data \u2014 choosing what to group by, what to aggregate, what to nest \u2014 is inherently an act of defining a new way to look at that data. Malloy is built around this idea: the output of every query is not just a result set but a new source with its own schema, and data comprehension is an ongoing iterative process where later stages want not only the data from a previous stage but how that data came into being. This is why query output carries metadata, why queries can be used as sources, and why views and pipelines compose naturally.\n\n## Documents and Statements\n\nA Malloy file (`.malloy`) is a sequence of statements, optionally separated by semicolons. There are five statement types:\n\n- **`import`** \u2014 import sources and queries from another `.malloy` file\n- **`source:`** \u2014 define a named, reusable data source with its schema and extensions\n- **`query:`** \u2014 define a named query (source + view) for reuse\n- **`run:`** \u2014 execute a query (the "do it now" statement)\n- **`given:`** \u2014 declare model-level parameters supplied at run time (experimental, see Givens)\n\n```malloy\nimport "shared_model.malloy"\n\nsource: flights is duckdb.table(\'flights.parquet\') extend {\n  measure: flight_count is count()\n}\n\nquery: carrier_summary is flights -> {\n  group_by: carrier\n  aggregate: flight_count\n}\n\nrun: carrier_summary\n```\n\nComments use `//` or `--` (both are line comments).\n\n## Sources\n\nA **source** is anything you can hand a SQL database and get a schema back \u2014 a table name, a SQL SELECT, or the output of another Malloy query. The columns in that schema become the source\'s initial fields (all dimensions).\n\n```malloy\nsource: flights is duckdb.table(\'flights.parquet\')\nsource: limited is duckdb.sql("""SELECT * FROM flights LIMIT 100""")\nsource: carrier_facts is carrier_summary   -- a query used as a source\n```\n\nWhat makes sources central to Malloy is **extension**. The `extend` block lets you layer on dimensions, measures, views, joins, filters, primary keys, field restrictions, and renames. These extensions travel with the source \u2014 any query against it gets them for free.\n\n```malloy\nsource: flights is duckdb.table(\'flights.parquet\') extend {\n  primary_key: id\n\n  dimension: distance_km is distance * 1.609344\n\n  measure:\n    flight_count is count()\n    total_distance is sum(distance)\n\n  join_one: carriers with carrier\n  join_one: origin_airport is airports on origin_airport.code = origin\n\n  where: dep_time > @2001\n\n  view: by_carrier is {\n    group_by: carrier\n    aggregate: flight_count, total_distance\n  }\n}\n```\n\nSources can extend other sources, creating a refinement chain:\n\n```malloy\nsource: ca_flights is flights extend {\n  where: origin.state = \'CA\'\n}\n```\n\nField access control uses `accept:` (allowlist) or `except:` (denylist) to restrict which inherited columns are visible. Fields can be renamed with `rename: new_name is old_name`.\n\n## Joins\n\nJoins are declared in the source, not reconstructed in every query. This is a fundamental design difference from SQL: the graph structure of your data is a property of the model.\n\n```malloy\njoin_one: carriers with carrier                          -- FK \u2192 PK shorthand\njoin_one: origin_airport is airports on origin_airport.code = origin  -- explicit ON\njoin_many: line_items on line_items.order_id = id        -- one-to-many\njoin_cross: other_table on other_table.key = key         -- cross join\n```\n\n- `join_one` \u2014 the joined source has at most one row per source row (many-to-one or one-to-one)\n- `join_many` \u2014 the joined source has potentially many rows per source row\n- `join_cross` \u2014 a full cross product\n\nThe `with` shorthand requires the joined source to have a declared `primary_key`. All joins are left outer by default. There is no right join \u2014 Malloy\'s graph model doesn\'t need one.\n\n**Choosing `join_one` vs `join_many`:** Ask "for a single row in the base source, can the joined source match more than one row?" If yes \u2192 `join_many`. If no (or at most one) \u2192 `join_one`. The common mistake is reaching for `join_many` when joining a *lookup or summary table* (e.g., joining an inventory snapshot to a purchase history on a wine key). Even though the joined table may have many rows overall, if each base row resolves to *at most one* joined row, use `join_one`. Use `join_many` only when the join genuinely fans out the base rows \u2014 e.g., joining line items to orders, or notes to a wine catalog.\n\nWhen you reference a joined source\'s fields, you use dot notation: `carriers.nickname`, `origin_airport.state`. This is one of Malloy\'s most important abstractions: **the access path to nested data is identical regardless of how the nesting is physically stored.** An array of records embedded in a column, a `join_many` to a separate table, a record-typed column \u2014 all are navigated with the same dot notation. The SQL required to traverse these different physical arrangements varies wildly (unnesting arrays, LEFT JOINs, correlated subqueries, ARRAY_AGG), but Malloy hides all of that. You think about the logical shape of your data \u2014 "flights have carriers, carriers have a nickname" \u2014 and write `carriers.nickname`. The compiler figures out what SQL is needed to get there. This means you can restructure your physical schema (normalize a nested array into a separate table, or denormalize a joined table into a record column) without changing any of the Malloy that references that data.\n\n## Fields\n\nMalloy has four kinds of fields: **dimensions**, **measures**, **views**, and **calculations**.\n\n### Dimensions\n\nScalar expressions \u2014 they compute a value per row. All columns inherited from a table are dimensions. Computed dimensions reference other dimensions or columns:\n\n```malloy\ndimension: full_name is concat(first_name, \' \', last_name)\ndimension: is_long_haul is distance > 1000\n```\n\n### Measures\n\nAggregate expressions \u2014 they compute a value across a set of rows. A field is a measure when its defining expression contains an aggregate function (`count`, `sum`, `avg`, `min`, `max`):\n\n```malloy\nmeasure:\n  flight_count is count()\n  total_distance is sum(distance)\n  avg_distance is avg(distance)\n  pct_delayed is count() { where: dep_delay > 30 } / count()\n```\n\n**`count(expr)` counts distinct values.** Unlike SQL\'s `COUNT(DISTINCT expr)`, Malloy uses `count(expr)` for distinct counting. The `count(distinct expr)` form is a deprecated syntax that will produce an error. Use `count()` for total row count, `count(field)` for distinct values of that field:\n\n```malloy\naggregate:\n  total_rows is count()               -- all rows\n  unique_carriers is count(carrier)   -- distinct carriers\n```\n\nMeasures can be filtered inline with `{ where: ... }`, which is how you build things like "percent of flights delayed" without subqueries.\n\n### Views\n\nA view is a query saved into the source \u2014 a reusable transformation:\n\n```malloy\nview: by_carrier is {\n  group_by: carrier\n  aggregate: flight_count, total_distance\n  limit: 10\n}\n```\n\nViews can reference other views from the same source as a starting point, and can be extended with `+`.\n\n### Calculations\n\nWindow functions over the grouped result. Calculations can only be defined in a query stage with `calculate:`, never in a source definition, because they depend on the output columns of the query:\n\n```malloy\nrun: flights -> {\n  group_by: carrier\n  aggregate: flight_count\n  calculate: carrier_rank is rank()\n}\n```\n\n## Queries and Views\n\nA query pairs a source with a view (the transformation). Everything after the first `->` is the view.\n\n```malloy\nrun: flights -> {\n  group_by: carrier\n  aggregate: flight_count\n}\n```\n\n### Reduction vs. Projection\n\nEach stage of a view performs exactly one of:\n\n- **Reduction** \u2014 uses `group_by:` and/or `aggregate:` to reduce grain. Analogous to `SELECT ... GROUP BY` in SQL.\n- **Projection** \u2014 uses `select:` to pick fields without aggregation. Analogous to `SELECT` without `GROUP BY`.\n\nThese cannot be mixed in a single stage. A stage with `group_by:` cannot have `select:`, and vice versa.\n\n### Source-level definitions vs. query-level operations\n\nThe same `name is expression` syntax defines fields in both sources and queries:\n\n```malloy\n-- In a source (reusable):\nsource: flights is ... extend {\n  measure: flight_count is count()          -- defines a measure in the model\n}\n\n-- In a query (ad hoc):\nrun: flights -> {\n  aggregate: flight_count is count()        -- defines the same measure inline\n}\n```\n\nWhen used in a source, `measure:` and `dimension:` are **definition statements** \u2014 they add named fields to the source\'s schema. When used in a query, `group_by:`, `aggregate:`, `select:`, `nest:`, and `calculate:` are **query operations** \u2014 they specify what the query does. The field definitions are syntactically identical in both contexts, but the enclosing keyword determines the role:\n\n| Source keyword | Query keyword | What it holds |\n|---|---|---|\n| `dimension:` | `group_by:` or `select:` | scalar expressions |\n| `measure:` | `aggregate:` | aggregate expressions |\n| `view:` | `nest:` | sub-queries |\n| _(n/a)_ | `calculate:` | window functions |\n\nThis is why `measure` and `aggregate` are separate keywords. `measure:` is a *modeling* statement \u2014 "this source has a reusable aggregate computation called X." `aggregate:` is a *query* statement \u2014 "in this query, include these aggregate values in the output." A query\'s `aggregate:` can reference a previously defined measure by name, or define one inline. The distinction parallels the separation between defining a dimension in a source and using it via `group_by:` in a query.\n\n### Multi-stage Pipelines\n\nStages chain with `->`. Each stage\'s output becomes the next stage\'s source:\n\n```malloy\nrun: flights -> {\n  group_by: carrier\n  aggregate: flight_count is count()\n} -> {\n  where: flight_count > 1000\n  select: *\n}\n```\n\n### Refinement with `+`\n\nThe refinement operator `+` merges query operations together. It works both within a view and at the top level on a named query:\n\n```malloy\n-- Refining a view within a query:\nrun: flights -> by_carrier + { limit: 5 } + { nest: by_destination }\n\n-- Refining a named query at the top level:\nrun: carrier_summary + { group_by: origin }   -- add origin grouping to existing query\n```\n\nWhen a dimension name appears as a bare reference, it expands to `{ group_by: name }`. A measure name expands to `{ aggregate: name }`:\n\n```malloy\nrun: flights -> carrier + flight_count + { limit: 10 }\n-- equivalent to: flights -> { group_by: carrier; aggregate: flight_count; limit: 10 }\n```\n\nFor multi-stage queries, refinement semantics get more complex \u2014 but for single-stage queries, `+` straightforwardly merges operations into the stage.\n\n### Nesting\n\n`nest:` embeds an aggregating subquery inside a reduction. Each row of the outer query gets a subtable from the nested query. Nests can nest arbitrarily deep:\n\n```malloy\nrun: flights -> {\n  group_by: carrier\n  aggregate: flight_count\n  nest: top_routes is {\n    group_by: origin, destination\n    aggregate: flight_count\n    limit: 3\n  }\n}\n```\n\n### Other query operations\n\n- **`where:`** \u2014 filter rows (pre-aggregation). Comma-separated filters are ANDed.\n- **`having:`** \u2014 filter groups (post-aggregation), like SQL\'s HAVING.\n- **`limit:`** / **`order_by:`** \u2014 limit and sort output.\n- **`extend`** \u2014 add fields or joins to a source inline within a query expression.\n\n## Aggregate Locality (Symmetric Aggregates)\n\nThis is one of Malloy\'s most important features. In SQL, when you join tables and aggregate, you risk double-counting (the "fan trap"). Malloy solves this with **aggregate locality** \u2014 you specify *where in the join graph* an aggregation should be computed.\n\n```malloy\nrun: flights -> {\n  aggregate:\n    -- avg seats weighted by number of flights (locality: source, i.e. flights)\n    avg_seats_per_flight is source.avg(aircraft.aircraft_models.seats)\n    -- avg seats per aircraft model (locality: aircraft_models)\n    avg_seats_per_model is aircraft.aircraft_models.seats.avg()\n}\n```\n\nThree syntactic forms:\n\n- `avg(expr)` \u2014 aggregate at the current source (implicit locality)\n- `joined_source.avg(expr)` \u2014 aggregate at the specified join point (explicit locality)\n- `joined_source.field.avg()` \u2014 shorthand for aggregating the field at its parent source\n\nFor `sum` and `avg` (asymmetric aggregates), when the expression crosses a join boundary, Malloy *requires* explicit locality \u2014 it won\'t silently give you a wrong answer. For `min`, `max`, and `count` (symmetric), locality doesn\'t change the result, so implicit is always fine.\n\nMalloy implements this with a technique called **symmetric aggregates** \u2014 it internally de-duplicates rows based on primary keys at the appropriate join level, so aggregations are always mathematically correct regardless of join fan-out.\n\n## Ungrouped Aggregates\n\n`all()` and `exclude()` allow computing aggregates at different grouping levels within a single query:\n\n```malloy\nrun: airports -> {\n  group_by: state, faa_region\n  aggregate:\n    airport_count is count()\n    total_airports is all(count())                   -- ungrouped: total across all rows\n    region_airports is all(count(), faa_region)       -- grouped only by faa_region\n    pct_of_total is count() / all(count())\n}\n```\n\n`all(expr)` removes all grouping. `all(expr, dim1, dim2)` keeps only the specified grouping dimensions. `exclude(expr, dim)` removes the specified dimension from grouping.\n\n**Important:** `all(expr, dim)` takes the **local alias name** as defined in the query\'s `group_by:`, not a dotted path. If you want to partition by a joined field, alias it first:\n\n```malloy\n-- WRONG: all(count(), director.primaryName)  -- dot paths don\'t work here\n-- RIGHT:\nrun: movies -> {\n  group_by: director is director.primaryName   -- alias it\n  aggregate:\n    movies is count()\n    director_total is all(count(), director)   -- reference the alias\n    pct is count() / all(count(), director)\n}\n```\n\n## Expressions\n\nMalloy expressions include arithmetic, comparison, logical operators, function calls, type casts, and several Malloy-specific forms.\n\n### Evaluation Spaces\n\nEvery expression has an evaluation space: **literal**, **constant**, **input**, or **output**. Input expressions reference source columns/dimensions. Output expressions reference the results of the current query stage (used in `calculate:`). Some functions constrain their arguments \u2014 e.g., `lag(expr)` requires an output expression, `avg(expr)` requires an input expression.\n\n### Application and Partial Comparison\n\nThe `?` operator applies a condition to a value. Partial comparisons are conditions without a left-hand side:\n\n```malloy\nwhere: state ? \'CA\' | \'NY\'         -- state is \'CA\' or \'NY\'\nwhere: distance ? > 500 & < 2000   -- distance between 500 and 2000\n```\n\n`|` is alternation (OR), `&` is conjunction (AND) within partials.\n\n### Pick Expressions\n\nMalloy\'s equivalent of CASE:\n\n```malloy\ndimension: size_bucket is\n  pick \'short\' when distance < 500\n  pick \'medium\' when distance < 1500\n  else \'long\'\n```\n\n### Filtered Aggregate Expressions\n\nAny aggregate can be filtered inline:\n\n```malloy\nmeasure: ca_flights is count() { where: origin.state = \'CA\' }\n```\n\n### Type Casting\n\n```malloy\ntotal_distance::string       -- Malloy type cast\nname::"VARCHAR(32)"          -- database-native type cast\n```\n\n### Time Literals and Ranges\n\n```malloy\n@2003                       -- the year 2003\n@2003-Q2                    -- second quarter of 2003\n@2024-01-15 10:30:00        -- timestamp literal\ndep_time ? @2003 to @2005   -- range comparison\nnow                         -- current timestamp\n```\n\n## Data Types\n\nMalloy\'s type system: `string`, `number`, `boolean`, `date`, `timestamp`, `timestamptz`, `json`, and `sql native` (for unsupported database types). Compound types: `type[]` for arrays, `{ name :: type, ... }` for records, nesting arbitrarily: `{ x :: number, tags :: string[] }[]`.\n\n## Annotations and Tags\n\nThese are related but distinct concepts.\n\n### Annotations\n\nAnnotations are **text strings** attached to objects during compilation. They are metadata \u2014 they never affect query execution or SQL generation. An annotation starts with `#` and continues to end of line:\n\n```malloy\n# bar_chart\nview: by_carrier is { ... }\n```\n\n- `#` annotations attach to the next object defined below them\n- `##` annotations attach to the model (the file)\n- Block annotations use `#|` ... `|#` for multi-line content (closing delimiter must match the column position of the opener)\n\nAnnotations distribute over definition lists:\n\n```malloy\n# currency\nmeasure:           -- all three measures get the # currency annotation\n  revenue is sum(amount)\n  # percent          -- this measure also gets # percent\n  margin is revenue / cost\n  cost is sum(amount)\n```\n\n### Tags (a use of annotations)\n\nTags are the primary *consumer* of annotation strings. They interpret annotation text using a structured property language (MOTLY). The key distinction: **annotations are the transport mechanism (raw strings attached to objects), tags are the interpretation layer (parsed key-value properties).**\n\nNot all annotations are tags. An annotation is just text. Tags are annotations that happen to be written in the tag property language and parsed by an application.\n\n### Annotation prefixes (routing)\n\nThe character(s) immediately after `#` route the annotation to different consumers:\n\n- `# ` (hash-space) \u2014 renderer tags, parsed by the Malloy VS Code extension for visualization\n- `##!` \u2014 compiler directives (e.g., `##! experimental.parameters`, `##! experimental.givens`)\n- `#"` \u2014 reserved for documentation strings\n- `#(appName)` \u2014 application-specific tags (e.g., `#(docs) hidden`)\n\n```malloy\n# bar_chart size=large        -- renderer tag: tells VS Code how to render\n##! experimental.parameters   -- compiler tag: enables a feature flag\n#(myApp) priority=high        -- custom app tag: ignored by renderer/compiler\n```\n\n### Tag property syntax\n\n```\ntName                         -- boolean flag (exists = true)\ntName=value                   -- set property value\ntName=[a, b, c]               -- array value\ntName: { p1=v1 p2=v2 }       -- nested properties (replaces)\ntName { p1=v1 }               -- nested properties (merges)\n-tName                        -- delete a property\ntName.sub.path=value          -- deep path assignment\n```\n\nValues can be unquoted identifiers, quoted strings, numbers, or typed values prefixed with `@` (`@true`, `@false`, `@2024-01-15`).\n\n## Givens (Model-Level Parameters)\n\n**Status: experimental, gated by `##! experimental.givens`.** Naming is provisional.\n\nGivens are values supplied at run time that the model can reference in any expression. The motivating use case is row-level access control \u2014 a model written once with `where: x.tenant_id = $TENANT` and the tenant supplied per API call \u2014 but they also fit configuration values, session context, and any "one compiled model, many invocations with varying context" pattern.\n\nGivens are model-wide: a single namespace, one value per name per compilation. They are *complementary to* source/query parameters (`source: foo(x :: string) is ...`), not a replacement. Use a parameter when you want two differently-bound copies of the same source side-by-side in one model; use a given when you want one value visible everywhere in the compilation.\n\n### Declaration\n\nThe `given:` top-level statement introduces givens, with a name, a type, and an optional default:\n\n```malloy\ngiven:\n  TENANT :: string\n  MAX_ROWS :: number is 1000\n  CUTOFF_DATE :: date is @2024-01-01\n```\n\nType can be any Malloy atomic type or compound type, including `filter<T>`:\n\n```malloy\ngiven:\n  ROLE :: string\n  ALLOWED_ROLES :: string[]\n  SESSION :: { user_id :: string, tenant :: string }\n  TENANT_FILTER :: filter<string>\n```\n\nDefaults are expressions over constants and other givens. Annotations attach to given declarations the same way they attach to sources or measures.\n\n### Reference: the `$` sigil\n\nInside any expression, a given is referenced with a leading `$`:\n\n```malloy\nsource: orders_for_user is orders extend {\n  where: orders.tenant_id = $TENANT\n}\n\nquery: recent_orders is orders_for_user -> {\n  where: order_date >= $CUTOFF_DATE\n  limit: $MAX_ROWS\n}\n```\n\n`$` appears *only* at expression references. The other three sites where a given\'s name appears \u2014 declaration, import, and supply (caller side) \u2014 use the bare name, because syntactic position already disambiguates. Givens share the top-level declaration namespace with sources/queries/views, so `source: x is ...` plus `given: x :: string` is a name-conflict error.\n\n### Set membership: `expr in $arrayGiven`\n\nThe RHS of `in` is either a parenthesized list of expressions (`in (1, 2, x, y * 7)`, same as SQL) or a given with an array value (`in $ARR`). A bare array-typed expression \u2014 a dimension, a joined array field, an inline `[a, b, c]` literal \u2014 is *not* legal on the RHS; arrays only reach the RHS via the given form.\n\nWhen a given has array type, `expr in $ARR` tests `expr` against the runtime-bound array; `not in $ARR` is the negation. The left-hand side must match the array\'s element type (`string in $string[]`, `number in $number[]`, etc.); mismatches are translate-time errors. Records and nested arrays are out of scope.\n\n```malloy\ngiven:\n  ALLOWED_STATES :: string[]\n  URGENT_STATUSES :: string[]\n\nsource: orders extend {\n  where: state in $ALLOWED_STATES\n  dimension: is_urgent is order_status in $URGENT_STATUSES\n}\n```\n\nAt SQL emit, the array\'s contents land in a generated `IN (...)` clause. Empty or `null` arrays collapse to the obvious result (`IN` \u2192 `FALSE`, `NOT IN` \u2192 `TRUE`). NULL elements inside a non-empty array follow standard SQL `IN` semantics.\n\nTo derive a value from an array \u2014 typically a boolean gate \u2014 *without* the array itself reaching row-position SQL, use an inline given (below).\n\n### Inline givens\n\nAn `inline` given is evaluated at **bind time**, before SQL is emitted: its default expression runs against the resolved given values and reduces to a literal, and that literal is what reaches SQL.\n\n```malloy\ngiven:\n  CAPABILITIES :: string[]\n  inline CAN_READ_ORDERS :: boolean is \'read_orders\' in $CAPABILITIES\n  inline CAN_MUTATE :: boolean\n    is \'write_orders\' in $CAPABILITIES or \'admin\' in $CAPABILITIES\n\nsource: orders extend {\n  where: $CAN_READ_ORDERS   -- SQL sees: WHERE ... AND TRUE  (or FALSE)\n}\n```\n\nThis is the **row-level access-control gate** pattern: the host supplies a capability list as a regular given, an inline given derives a boolean from it, and only the boolean \u2014 not the list \u2014 crosses into row-position SQL. The query planner sees a constant predicate.\n\nRules:\n\n- An inline given **must** have a default. `inline FOO :: number` with no `is` clause is a translate-time error.\n- The default may use:\n  - Boolean and comparison operators: `and`, `or`, `not`, `=`, `!=`, `<`, `<=`, `>`, `>=`\n  - The `in $array` test against another given\n  - Literals (string, number, boolean, null, array) and references to other givens\n- The default cannot call SQL functions, reference fields, or use any operator outside that list. Disallowed operators are reported at translate time with the offending operator names.\n- Inline givens are filtered out of `Model.givens` and `PreparedQuery.givens` \u2014 they\'re computed, not supplied \u2014 so introspection-driven UIs don\'t render editors for them. A caller can still shadow one by binding it explicitly (useful in tests).\n- `inline` is a context-sensitive modifier, not a reserved keyword: fields, sources, views, dimensions, and joins can still be named `inline`.\n\n### Imports\n\nGivens behave like every other top-level named thing under import:\n\n- **Bare import** (`import "b.malloy"`) brings B\'s full export surface in, including all of B\'s givens, under their original names.\n- **Selective import** (`import { source1 } from "b.malloy"`) brings in only what\'s listed. To surface a given to your callers, list it: `import { source1, MAX_ROWS } from "b.malloy"`.\n- **Rename** uses the existing `LOCAL is REMOTE` form: `import { CAP is MAX_ROWS } from "b.malloy"`.\n\nSurfacing controls *who can supply a value*, not whether internal references work. An imported source can reference a given the importer didn\'t surface; the reference still resolves internally, and at run time the unsurfaced given relies on its declaration-site default.\n\nA common project convention is a shared `tenant_givens.malloy` (declaring `$TENANT`, `$USER_ROLE`, etc.) that every root file bare-imports on line 1, so the project\'s given contract is visible at the top of any model.\n\n### Satisfiability\n\nA query referencing `$X` is satisfiable if either `$X` is in the model\'s namespace (so a caller can supply a value) or `$X` has a default at its declaration site. Otherwise the query is unsatisfiable and errors. Latent definitions (views, dimensions, measures) that reference `$X` are fine if no query actually invokes them \u2014 satisfiability is a property of running queries.\n\n### Supplying values\n\nValues can be supplied at two layers, which compose (per-query overrides per-runtime):\n\n**Per-runtime** \u2014 bound to a `Runtime`, applied as defaults to every query through it. Two paths:\n\n1. **`givensPath` in `malloy-config.json`** points at a JSON file of `name \u2192 value`:\n   ```jsonc\n   { "givensPath": "./local-givens.json" }\n   // or env-var indirection (resolved at config load):\n   { "givensPath": { "env": "GAME_STORE_GIVENS" } }\n   ```\n   The values file is a flat JSON map, keys are caller-facing surface names:\n   ```jsonc\n   { "TENANT": "acme", "USER_ROLE": "admin", "CUTOFF_DATE": "2024-01-01" }\n   ```\n\n2. **Direct on the Runtime constructor** (for per-request multi-tenant servers, tests, scripts):\n   ```typescript\n   const runtime = new Runtime({\n     config,\n     givens: { TENANT: claims.tenant_id, USER_ROLE: claims.role },\n     urlReader,\n   });\n   ```\n   Constructor values *merge over* the file at `givensPath` per-key.\n\n**Per-query** \u2014 supplied on a single `.run({ givens: ... })` call:\n```typescript\nawait query.run({ givens: { STATE_FILTER: "CA", LIMIT_OVERRIDE: 50 } })\n```\nAvailable on every compile-or-run entry point (`runtime.loadQuery(...).run(options)`, `preparedQuery.getPreparedResult(options)`, `preparedQuery.getSQL(options)`).\n\nThe resolved per-runtime values are exposed on `runtime.givens` (read-only) for diagnostics.\n\n### Finalized givens (security primitive)\n\nA multi-tenant deployment usually wants `TENANT`/`USER_ROLE`/`REGION` to be runtime-bound and **un-overridable per-query** \u2014 otherwise a downstream endpoint that accidentally accepts user-controlled query params and plumbs them into `.run({ givens: ... })` becomes a tenant-leak vulnerability.\n\n`finalizeGivens` in the config locks names at the API surface:\n\n```jsonc\n{\n  "givensPath": { "env": "GAME_STORE_GIVENS" },\n  "finalizeGivens": ["TENANT", "USER_ROLE", "REGION"]\n}\n```\n\nFinalize doesn\'t change *what* a given resolves to \u2014 only *who* can supply it. A `.run({ givens: { TENANT: ... } })` for a finalized name throws at API entry (named, not silently dropped). Finalized givens are filtered out of `Model.givens` and `PreparedQuery.givens` so introspection-driven UIs don\'t render editors for locked names.\n\n### JS shapes for supplied values\n\nBoth the JSON values file and per-query `givens` maps accept the same per-type shapes:\n\n| Malloy type | JS |\n|---|---|\n| `string` | string |\n| `number` | `number`, `bigint`, or string (precision escape hatch) |\n| `boolean` | boolean |\n| `date` | ISO date string `"2024-01-15"` |\n| `timestamp` (naive) | ISO string without offset \u2014 *not* a JS `Date` |\n| `timestamptz` | JS `Date` or ISO string with offset (string preferred \u2014 makes TZ choice visible) |\n| `T[]` | JS array |\n| `{ name :: T, ... }` | JS object |\n| `filter<T>` | JS string (Malloy filter expression source) |\n\nNaive timestamp givens reject `Date` because `Date` represents a UTC instant, not a wall-clock value, and `new Date("2001-01-01T00:00:00")` silently picks up the system\'s local TZ. Type mismatches throw at the boundary with a path that points at the offending location (e.g., `givens.SESSION.user_id: expected string, got number`). `null` is legal for any given type.\n\n### Introspection\n\n`Model.givens` and `PreparedQuery.givens` expose, to the host, the supplyable givens \u2014 for whole-model parameter editors and per-query "run this" forms respectively. Each entry carries name, type, default expression (or undefined if the caller must supply), location, and access to declaration-site annotations via `tagParse`/`getTaglines`.\n\n## How a Malloy Query Becomes SQL\n\nThe compilation pipeline has two phases:\n\n### Phase 1: Translation (source code \u2192 IR)\n\n```\nMalloy source \u2192 ANTLR lexer/parser \u2192 parse tree \u2192 AST builder \u2192 AST \u2192 IR generator \u2192 IR\n```\n\nThe **Intermediate Representation (IR)** is a plain, serializable data structure (JSON-compatible) that fully describes the semantic model and query. Note that IR is *not* dialect-agnostic \u2014 the same Malloy source compiled against different databases can produce different IR, because schema information, type mappings, and available functions vary by backend. It can be cached, transmitted, and reused. Key IR types:\n\n- **`SourceDef`** \u2014 a source\'s complete definition: schema, fields, joins, filters\n- **`Query`** \u2014 a source paired with a pipeline of operations\n- **`FieldDef`** \u2014 definition of any field (dimension, measure, join, calculation)\n- **`Expr`** \u2014 expression tree (arithmetic, comparisons, aggregates, function calls, field references)\n\nThe translator handles all language-level semantics: scoping, name resolution, type checking, evaluation space validation.\n\n### Phase 2: Compilation (IR \u2192 SQL)\n\n```\nIR \u2192 query compiler \u2192 expression compiler \u2192 dialect-specific SQL generator \u2192 SQL + metadata\n```\n\nThe compiler walks the IR query pipeline, translating each stage into SQL constructs (CTEs, subqueries, GROUP BY, window functions). A **Dialect** layer handles database-specific SQL generation.\n\nThe compiler also produces **metadata** alongside the SQL \u2014 structural information needed to interpret the result set (column types, nesting structure, annotation data). This metadata is what allows Malloy renderers to reconstruct nested/hierarchical results from the flat SQL result set and apply visualization tags.\n\n### Key architectural consequences\n\n- Because the IR is serializable, it can be cached and reused across compilations (though IR is database-specific \u2014 the same source compiled against different backends may produce different IR).\n- Because joins are declared in the source (not the query), the compiler knows the full join graph and can compute symmetric aggregates correctly.\n- Because nested queries are first-class, the compiler generates the appropriate SQL (correlated subqueries or ARRAY_AGG patterns depending on dialect) automatically.\n- Because measures are typed as aggregates in the IR, the compiler can validate that they only appear in aggregate context and enforce locality rules.\n\n## Where to Go Deeper\n\nThis document is a conceptual reference \u2014 enough to reason about the language and its design, but not exhaustive. Here\'s where to find more detail.\n\n### Language Documentation\n\nThe full docs live at [https://docs.malloydata.dev](https://docs.malloydata.dev). Key pages by topic:\n\n| Topic | URL |\n|---|---|\n| Sources, extensions, joins, primary keys | [documentation/language/source](https://docs.malloydata.dev/documentation/language/source) |\n| Queries, views, reduction vs projection | [documentation/language/query](https://docs.malloydata.dev/documentation/language/query), [views](https://docs.malloydata.dev/documentation/language/views) |\n| Fields: dimensions, measures, views, calculations | [documentation/language/fields](https://docs.malloydata.dev/documentation/language/fields) |\n| Aggregate functions and aggregate locality | [documentation/language/aggregates](https://docs.malloydata.dev/documentation/language/aggregates) |\n| Ungrouped aggregates (`all`, `exclude`) | [documentation/language/ungrouped-aggregates](https://docs.malloydata.dev/documentation/language/ungrouped-aggregates) |\n| Nested views / aggregating subqueries | [documentation/language/nesting](https://docs.malloydata.dev/documentation/language/nesting) |\n| Joins | [documentation/language/join](https://docs.malloydata.dev/documentation/language/join) |\n| Expressions, operators, pick, apply | [documentation/language/expressions](https://docs.malloydata.dev/documentation/language/expressions) |\n| Evaluation spaces (literal, constant, input, output) | [documentation/language/eval_space](https://docs.malloydata.dev/documentation/language/eval_space) |\n| Filters and filter placement | [documentation/language/filters](https://docs.malloydata.dev/documentation/language/filters) |\n| Annotations and tags | [documentation/language/tags](https://docs.malloydata.dev/documentation/language/tags) |\n| Calculations and window functions | [documentation/language/calculations_windows](https://docs.malloydata.dev/documentation/language/calculations_windows) |\n| Data types | [documentation/language/datatypes](https://docs.malloydata.dev/documentation/language/datatypes) |\n| Time operations, ranges, timezones | [documentation/language/timestamp-operations](https://docs.malloydata.dev/documentation/language/timestamp-operations), [time-ranges](https://docs.malloydata.dev/documentation/language/time-ranges), [timezones](https://docs.malloydata.dev/documentation/language/timezones) |\n| Imports | [documentation/language/imports](https://docs.malloydata.dev/documentation/language/imports) |\n| Top-level statements and model structure | [documentation/language/statement](https://docs.malloydata.dev/documentation/language/statement) |\n| Functions reference | [documentation/language/functions](https://docs.malloydata.dev/documentation/language/functions) |\n\n### Examples and Patterns\n\nThe docs site includes worked examples of common analytical patterns at [documentation/patterns](https://docs.malloydata.dev/documentation/patterns/): percent-of-total, year-over-year, cohort analysis, sessionization, moving averages, nested subtotals, and more.\n\nEnd-to-end guides are at [documentation/user_guides](https://docs.malloydata.dev/documentation/user_guides/), including [Malloy by Example](https://docs.malloydata.dev/documentation/user_guides/malloy_by_example) (a comprehensive walkthrough) and a three-part series for SQL users ([part 1](https://docs.malloydata.dev/documentation/user_guides/sql_experts1), [part 2](https://docs.malloydata.dev/documentation/user_guides/sql_experts2), [part 3](https://docs.malloydata.dev/documentation/user_guides/sql_experts3)).\n\n### Source Code\n\nThe Malloy implementation lives at [github.com/malloydata/malloy](https://github.com/malloydata/malloy). Key entry points:\n\n| What | Where |\n|---|---|\n| ANTLR grammar (lexer + parser) | `packages/malloy/src/lang/grammar/` |\n| AST node hierarchy | `packages/malloy/src/lang/ast/` |\n| Parse tree \u2192 AST builder | `packages/malloy/src/lang/malloy-to-ast.ts` |\n| IR type definitions | `packages/malloy/src/model/malloy_types.ts` |\n| IR \u2192 SQL compiler | `packages/malloy/src/model/` |\n| Dialect-specific SQL generation | `packages/malloy/src/dialect/` |\n| Tag/annotation parsing (MOTLY) | `packages/malloy-tag/` |\n| Renderer | `packages/malloy-render/` |\n| Architecture overview | `CONTEXT.md` (root and in each package) |\n',
+  "language/pick.md": "---\ndescription: pick expressions \u2014 Malloy's CASE/if-then-else\n---\n\n`pick` is Malloy's equivalent of SQL `CASE WHEN`. Each branch is its own\n`pick` keyword; the `else` clause catches the remainder.\n\nThere are two forms of pick. In the first the `when` expression is any\nboolean expression.\n\n```malloy\n    pick 'Female' when upper(first_name) in ('JENNIFER', 'ELIZABETH', 'AMY', 'JESSICA')\n    pick 'Male'   when upper(first_name) in ('JAMES', 'JOHN', 'ROBERT', 'MICHAEL')\n    else 'Unknown'\n```\n\n## Example usage in a query\n\n```malloy\nrun: payments -> {\n  group_by: tier is\n    pick 'high'   when total_amount > 10000\n    pick 'medium' when total_amount > 1000\n    else 'low'\n  aggregate: payment_count is count()\n}\n```\n\n## Common mistakes\n\n- **Every branch needs its own `pick` keyword** \u2014 there is no `when \u2026 then`:\n  ```malloy\n  -- WRONG:\n  pick 'a' when x = 1 'b' when x = 2 else 'c'\n\n  -- RIGHT:\n  pick 'a' when x = 1\n  pick 'b' when x = 2\n  else 'c'\n  ```\n\n- **`else` is required** when the branches don't cover all cases \u2014 omitting it\n  returns `null` for unmatched rows.\n",
+  "writing-malloy-with-mcp.md": "---\ndescription: How to write Malloy over an MCP surface \u2014 the compiler-in-the-loop discipline, common errors, and givens. Tool-agnostic; read once.\n---\n# Writing Malloy over MCP\n\nMalloy is a semantic language: a source already carries measures, dimensions,\nviews, and joins, and the compiler typechecks every query against them. The\nsingle most useful habit is **let the compiler be ground truth** \u2014 don't guess\nsyntax or field names. Read the source's shape first, validate before you run,\nand read the `problems[]` the surface returns.\n\nThe exact tools differ by surface (an explore surface exposes describe + query;\nan authoring surface adds compile/prettify), but the loop is the same:\n\n1. **Read the shape.** Describe the source you're querying \u2014 its measures,\n   dimensions, views, and joins. The model usually already defines the\n   aggregation you want; reuse it instead of re-deriving it.\n2. **Validate, then run.** Compile/validate the query first (no execution) to\n   confirm it typechecks and to see the generated SQL or the givens it needs;\n   fix any `problems[]`, then execute to get rows.\n3. **Recover from problems[].** Every failure \u2014 parse, field-not-found,\n   aggregate-locality, runtime \u2014 comes back as a uniform `problems[]` with a\n   `code` and (when known) a `help_topic`. Pull that topic with `yo_help`.\n\n## Common errors and how to read them\n\n- **Unknown field** \u2014 describe the source and check its dimensions / measures /\n  views / joins for what actually exists. A join rendered by `source_ref` is\n  described under that name in the same response.\n- **Aggregate locality** \u2014 `sum(joined.x)` across a join needs explicit\n  locality: `source.sum(joined.x)` or `joined.x.sum()`.\n- **Mixed reduction / projection** \u2014 one query stage is either\n  `group_by:`/`aggregate:` OR `select:`, never both.\n- **Calculation in a source** \u2014 `calculate:` (window functions) lives in\n  queries, not in source definitions.\n\n## Givens (`$NAME` parameters)\n\nSome models declare given parameters (`$TENANT`, `$MAX_ROWS`, \u2026). Validate a\nquery with execution off to learn which givens it references (with their types\nand whether a default exists), then supply values keyed by surface name (no\n`$`). A given with a default is optional; one without must be supplied. For the\nper-type value shapes (dates as ISO strings, records as objects, `filter<T>` as\na Malloy filter string, \u2026) pull `yo_help(\"givens\")` \u2014 don't guess; the compiler\nvalidates and points at the offending field.\n\n## Before writing non-trivial Malloy\n\nBrowse the `language/*` topics first (start with `yo_help(\"language/overview\")`).\nThe language has real scoping and typing rules the compiler enforces \u2014 reading\nthe reference beats guessing.\n"
+};
+var prompts = {
+  "core": {
+    "instructions": ""
+  },
+  "develop": {
+    "instructions": 'You are helping someone publish a Malloy model for their data. The model will be\nserved through an MCP query tool like yours.\n\nA working model is an `index.malloy` (the published query surface) and a\n`malloy-config.json`, plus any `.malloy` files `index.malloy` imports.\nYou edit these with your file tools; the MCP tools compile, inspect, and test them.\n\nWhen interacting with a .malloy file, use the compile() or compile_file() tools,\ndon\'t read the file. The tools can both inspect and diagnose problems in a file.\n\nYou are probably doing one of these two things; read the guidance for the\nappropriate one with `yo_help`.\n\n- New model (no `index.malloy` / `malloy-config.json` yet)? -> yo_help("develop/getting-started")\n- Existing model (or setup complete) -> yo_help("develop/working-with-models")',
+    "tools": {
+      "compile": {
+        "description": 'Compile inline Malloy text (no file needed). Good for PROBING data: compiling `source: x is conn.sql("SELECT \u2026")` or `run: conn.sql("SELECT \u2026")` resolves and returns the schema \u2014 column names and types \u2014 without writing a file or fetching rows. Also checks a throwaway draft before it lands in a file. Same output shape as compile_file.',
+        "title": "Compile inline Malloy \u2014 probe data or check a draft"
+      },
+      "compile_file": {
+        "description": "Compile a .malloy file and return the structured model \u2014 sources, queries, runs, givens \u2014 plus problems[]. PREFER THIS over reading the file as text: reading shows syntax, compiling shows semantics.",
+        "title": "Compile and inspect a Malloy file"
+      },
+      "prettify": {
+        "description": "Reformat Malloy source to canonical form. Returns formatted text + parse problems (best-effort when problems is non-empty).",
+        "title": "Pretty-print Malloy source"
+      }
+    }
+  },
+  "explore": {
+    "guidance": 'Workflow: describe_source a source \u2014 learn its real dimensions, measures, and joins \u2014 before you query it. Validate with query(execute:false) and iterate until clean, then run with a plain-English question describing what that query answers. A successful run returns a shareable link; present results by restating the question, then the rows, then the link. Do ranking, top-N, and member selection in Malloy, not in client code. Full detail: yo_help("explore/how-to").',
+    "instructions": "Malloy semantic-layer analytics for {{INSTANCE_NAME}}. Start with `list_sources` or `describe_source` \u2014 every tool result carries the workflow and points you to `yo_help`.",
+    "tools": {
+      "describe_source": {
+        "description": "Get a source's queryable surface before writing a query: `dimensions` (its columns \u2014 scalars, records, and arrays), `measures`, `views`, the `joins` it reaches (keyed by path; `fans_out` flags paths that multiply rows), and a deduped `join_source_map` of the named sources those joins resolve to. `source` is required; `model_ref` is optional when the source name is unique across the catalog.",
+        "title": "Inspect a published source"
+      },
+      "list_sources": {
+        "description": "List the sources you can query, grouped by the model that publishes them, with each model's named queries. Drill into a source with describe_source before writing a query.",
+        "title": "List sources"
+      }
+    }
+  },
+  "shared": {
+    "errors": {
+      "no-model-ref": "No model_ref provided. Use `list_sources` to discover sources and the `model_ref` each lives in, then pass `model_ref` + `source`. (On a local develop server, `model_ref` is the path to a .malloy file, e.g. `index.malloy`.)"
+    },
+    "tools": {
+      "query": {
+        "description": "Run Malloy text against a model: `model_ref` is the model, `malloy` is the Malloy text (e.g. `run: source -> { ... }`). Set `execute:false` to validate only. Inspect the model first.",
+        "title": "Query a Malloy model"
+      },
+      "yo_help": {
+        "description": "Malloy guidance by topic: the language reference, how-to topics (setup, connections, querying), and error explanations. No topic \u2192 list topics. Use before guessing syntax and after a compile error (problems[] carry a help_topic pointer).",
+        "title": "Malloy reference and how-to guidance (by topic)"
+      }
+    }
+  }
+};
+function slugify(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+function nameFromKey(key) {
+  return key.replace(/\.md$/, "").split("/").map(slugify).join("/");
+}
+function parseFrontMatter(name, raw) {
+  const withoutProvenance = raw.replace(/^<!--[\s\S]*?-->\s*\n/, "");
+  const m = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(withoutProvenance);
+  if (!m) return { name, description: name, body: withoutProvenance };
+  const d = /^description:\s*(.+)$/m.exec(m[1] ?? "");
+  return {
+    name,
+    description: d?.[1]?.trim() ?? name,
+    body: m[2] ?? ""
+  };
+}
+var LANGUAGE_REFERENCE = "language/malloy-language-reference.md";
+function splitReference(ns, raw, out) {
+  let name = `${ns}/overview`;
+  const bodyLines = [];
+  const flush = () => {
+    const body = bodyLines.join("\n").trim();
+    if (body) out.push({ name, body });
+    bodyLines.length = 0;
+  };
+  for (const line of raw.split("\n")) {
+    const m = /^## (?!# )(.+)$/.exec(line);
+    if (m) {
+      flush();
+      name = `${ns}/${slugify((m[1] ?? "").trim())}`;
+      continue;
+    }
+    if (line.startsWith("---")) continue;
+    if (/^<!--/.test(line) || /-->\s*$/.test(line)) continue;
+    bodyLines.push(line);
+  }
+  flush();
+}
+function buildIndex() {
+  const topics = [];
+  for (const [key, raw] of Object.entries(contentFiles)) {
+    if (key === LANGUAGE_REFERENCE) {
+      const ns = nameFromKey(key.replace(/\/[^/]+$/, ""));
+      splitReference(ns, raw, topics);
+    } else {
+      topics.push({ name: nameFromKey(key), body: parseFrontMatter(key, raw).body.trim() });
+    }
+  }
+  return topics;
+}
+var cachedIndex = null;
+function index() {
+  if (!cachedIndex) cachedIndex = buildIndex();
+  return cachedIndex;
+}
+function listHelpTopics() {
+  return index().map((t) => t.name);
+}
+function getHelpTopic(query) {
+  const q = query.toLowerCase().trim();
+  const all = index();
+  const direct = all.find((t) => t.name === q) ?? all.find((t) => t.name.includes(q));
+  if (direct) return direct;
+  const tokens = q.split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) return void 0;
+  return all.find((t) => {
+    const body = t.body.toLowerCase();
+    return tokens.every((tok) => body.includes(tok));
+  });
+}
+var ERROR_TOPIC_MAP = {
+  "field-not-found": "language/fields",
+  "aggregate-in-calculate": "language/expressions",
+  "not-an-aggregate": "language/fields",
+  "mixed-reduction-projection": "language/queries-and-views",
+  "calculation-in-source": "language/fields",
+  "missing-aggregate-locality": "language/aggregate-locality-symmetric-aggregates",
+  "asymmetric-aggregate-needs-locality": "language/aggregate-locality-symmetric-aggregates",
+  "restricted-construct-forbidden": "explore/restricted-queries"
+};
+function helpTopicForCode(code) {
+  return ERROR_TOPIC_MAP[code];
+}
+function engineSkills() {
+  const raw = contentFiles["writing-malloy-with-mcp.md"];
+  if (!raw) return [];
+  return [parseFrontMatter("writing-malloy-with-mcp", raw)];
+}
+function mapProblems(problems) {
+  return problems.map((p) => {
+    const out = {
+      severity: p.severity,
+      message: p.message,
+      code: p.code,
+      uri: p.at?.url,
+      line: p.at?.range.start.line,
+      column: p.at?.range.start.character,
+      end_line: p.at?.range.end.line,
+      end_column: p.at?.range.end.character
+    };
+    const topic = helpTopicForCode(p.code);
+    if (topic) out.help_topic = topic;
+    return out;
+  });
+}
+function errorProblem(e, uri) {
+  return {
+    severity: "error",
+    message: e instanceof Error ? e.message : String(e),
+    code: "internal-error",
+    uri
+  };
+}
+function codeProblem(code, message, uri) {
+  const out = { severity: "error", code, message, uri };
+  const topic = helpTopicForCode(code);
+  if (topic) out.help_topic = topic;
+  return out;
+}
+function hasError(problems) {
+  return problems.some((p) => p.severity === "error");
+}
+async function gateConfigProblems(configProblems, run2) {
+  if (hasError(configProblems)) {
+    return { ok: false, problems: configProblems };
+  }
+  const result = await run2();
+  if (configProblems.length === 0) return result;
+  const r = result;
+  if (Array.isArray(r.problems)) {
+    return { ...result, problems: [...configProblems, ...r.problems] };
+  }
+  return result;
+}
+function prettify(source) {
+  const { result, errors } = internalPrettify(source);
+  const problems = errors.map((e) => ({
+    severity: "error",
+    code: "parse-error",
+    message: e.message,
+    line: e.line,
+    column: e.column
+  }));
+  return { formatted: result, problems };
+}
+var RESERVED_WORDS = /* @__PURE__ */ new Set([
+  "all",
+  "and",
+  "as",
+  "asc",
+  "avg",
+  "boolean",
+  "by",
+  "case",
+  "cast",
+  "compose",
+  "count",
+  "date",
+  "day",
+  "days",
+  "desc",
+  "distinct",
+  "else",
+  "end",
+  "exclude",
+  "export",
+  "extend",
+  "false",
+  "filter",
+  "for",
+  "from",
+  "full",
+  "has",
+  "hour",
+  "hours",
+  "import",
+  "in",
+  "include",
+  "inner",
+  "internal",
+  "is",
+  "json",
+  "left",
+  "like",
+  "max",
+  "min",
+  "minute",
+  "minutes",
+  "month",
+  "months",
+  "not",
+  "now",
+  "null",
+  "number",
+  "on",
+  "or",
+  "pick",
+  "private",
+  "public",
+  "quarter",
+  "quarters",
+  "right",
+  "second",
+  "seconds",
+  "source",
+  "sql",
+  "string",
+  "sum",
+  "table",
+  "then",
+  "this",
+  "timestamp",
+  "timestamptz",
+  "to",
+  "true",
+  "virtual",
+  "week",
+  "weeks",
+  "when",
+  "with",
+  "year",
+  "years"
+]);
+var BARE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function needsQuote(name) {
+  return !BARE_IDENTIFIER.test(name) || RESERVED_WORDS.has(name.toLowerCase());
+}
+var MAX_JOIN_DEPTH = 4;
+function toLoc(loc) {
+  if (!loc) return void 0;
+  return [loc.range.start.line, loc.range.start.character];
+}
+function annotationList(a) {
+  if (!a) return [];
+  return a.forRoute().map((n) => ({ route: n.route, text: n.content }));
+}
+function descriptionOf(a) {
+  const docs = (a?.forRoute('"') ?? []).map((n) => n.content.trim()).filter(Boolean);
+  return docs.length ? docs.join("\n") : void 0;
+}
+function agentNotesOf(a) {
+  const notes = (a?.forRoute("agent") ?? []).map((n) => n.content.trim()).filter(Boolean);
+  return notes.length ? notes.join("\n") : void 0;
+}
+function applyDocs(obj, a) {
+  const d = descriptionOf(a);
+  if (d) obj.description = d;
+  const i = agentNotesOf(a);
+  if (i) obj.instructions = i;
+  return obj;
+}
+function isLocal(loc, rootUri) {
+  return !!loc && loc.url === rootUri;
+}
+function sliceSource(src, loc) {
+  if (!src || !loc) return void 0;
+  const lines = src.split("\n");
+  const { start, end } = loc.range;
+  if (start.line < 0 || start.line >= lines.length) return void 0;
+  if (end.line < 0 || end.line >= lines.length) return void 0;
+  if (start.line === end.line) {
+    return lines[start.line]?.slice(start.character, end.character);
+  }
+  const out = [lines[start.line]?.slice(start.character) ?? ""];
+  for (let i = start.line + 1; i < end.line; i++) out.push(lines[i] ?? "");
+  out.push(lines[end.line]?.slice(0, end.character) ?? "");
+  return out.join("\n");
+}
+function joinRel(ef) {
+  const j = ef.structDef.join;
+  if (j === "many") return "one_to_many";
+  if (j === "cross") return "cross";
+  return "many_to_one";
+}
+function isScalarArray(parent) {
+  const sd = parent.structDef;
+  return sd.type === "array" && sd.elementTypeDef?.type !== "record_element";
+}
+function isRepeatedRecord(parent) {
+  const sd = parent.structDef;
+  return sd.type === "array" && sd.elementTypeDef?.type === "record_element";
+}
+function isAnonymousRecord(parent) {
+  return parent.structDef.type === "record";
+}
+function stripScalarArrayValue(parent, groups) {
+  if (!isScalarArray(parent)) return groups;
+  return { ...groups, dimensions: groups.dimensions.filter((f) => f.name !== "value") };
+}
+function fieldKind(af, structDefFields) {
+  const raw = structDefFields.find((x) => x.name === af.name);
+  const et = raw?.expressionType;
+  if (et && (expressionIsAggregate(et) || expressionIsAnalytic(et))) {
+    return "measure";
+  }
+  return "dimension";
+}
+function safeReferencedSource(ef) {
+  try {
+    return ef.referencedSource?.();
+  } catch {
+    return void 0;
+  }
+}
+function classifyJoinTarget(ef, knownSources) {
+  const refId = ef.referenceSourceID;
+  if (refId === void 0) return { kind: "own" };
+  const ref = safeReferencedSource(ef);
+  if (ref) {
+    if (knownSources.has(ref.name)) return { kind: "ref", name: ref.name };
+    return { kind: "own" };
+  }
+  return { kind: "anon", refId };
+}
+function emptyGroups() {
+  return { dimensions: [], measures: [], views: [], joins: [] };
+}
+function allocAnon(ef, refId, depth, ctx, anon) {
+  const existing = anon.byId.get(refId);
+  if (existing !== void 0) return existing;
+  const idx = anon.srcs.length;
+  anon.byId.set(refId, idx);
+  anon.srcs.push(void 0);
+  anon.srcs[idx] = buildAnonSource(ef, refId, depth, ctx, anon);
+  return idx;
+}
+function buildAnonSource(ef, refId, depth, ctx, anon) {
+  const structDefFields = ef.structDef.fields ?? [];
+  const groups = walkFields(ef.allFields, structDefFields, depth, ctx, anon);
+  const name = refId.split("@")[0] || ef.name;
+  const out = {
+    name,
+    primary_key: ef.primaryKey ?? null,
+    ...groups
+  };
+  applyDocs(out, ef.annotations);
+  if (needsQuote(name)) out.must_quote = true;
+  const annotations = annotationList(ef.annotations);
+  if (annotations.length > 0) out.annotations = annotations;
+  return out;
+}
+function walkFields(fields, structDefFields, depth, ctx, anon) {
+  const groups = emptyGroups();
+  for (const f of fields) {
+    const annotations = annotationList(f.annotations);
+    const mLoc = f.location;
+    const local = isLocal(mLoc, ctx.rootUri);
+    const loc = local ? toLoc(mLoc) : void 0;
+    if (f.isExploreField()) {
+      const ef = f;
+      const cls = classifyJoinTarget(ef, ctx.knownSources);
+      const inlineMode = ctx.opts.expand === "inline";
+      const join4 = { name: f.name, relationship: joinRel(ef) };
+      applyDocs(join4, f.annotations);
+      if (cls.kind === "ref") join4.source_ref = cls.name;
+      else if (cls.kind === "anon" && !inlineMode) {
+        join4.anon_src_index = allocAnon(ef, cls.refId, depth + 1, ctx, anon);
+      }
+      if (needsQuote(f.name)) join4.must_quote = true;
+      if (annotations.length > 0) join4.annotations = annotations;
+      if (loc) join4.location = loc;
+      const synthetic = isScalarArray(ef) || isRepeatedRecord(ef) || isAnonymousRecord(ef);
+      if (isScalarArray(ef)) join4.column_shape = "scalar_array";
+      else if (isRepeatedRecord(ef)) join4.column_shape = "record_array";
+      else if (isAnonymousRecord(ef)) join4.column_shape = "record";
+      if (!synthetic && mLoc) {
+        const body = sliceSource(ctx.readSource(mLoc.url), mLoc);
+        if (body) join4.body = body;
+      }
+      const shouldInline = inlineMode || cls.kind === "own";
+      if (shouldInline && depth < MAX_JOIN_DEPTH) {
+        const childStructFields = ef.structDef.fields ?? [];
+        const sub = walkFields(ef.allFields, childStructFields, depth + 1, ctx, anon);
+        join4.fields = stripScalarArrayValue(ef, sub);
+      }
+      groups.joins.push(join4);
+      continue;
+    }
+    if (f.isQueryField()) {
+      const view = { name: f.name };
+      applyDocs(view, f.annotations);
+      if (needsQuote(f.name)) view.must_quote = true;
+      if (annotations.length > 0) view.annotations = annotations;
+      if (loc) view.location = loc;
+      if (mLoc) {
+        const body = sliceSource(ctx.readSource(mLoc.url), mLoc);
+        if (body) view.body = body;
+      }
+      groups.views.push(view);
+      continue;
+    }
+    const af = f;
+    const info = { name: f.name, type: af.type };
+    applyDocs(info, f.annotations);
+    if (needsQuote(f.name)) info.must_quote = true;
+    const raw = structDefFields.find((x) => x.name === f.name);
+    const expr = raw?.code?.trim() || void 0;
+    if (expr && expr !== f.name) info.expression = expr;
+    if (annotations.length > 0) info.annotations = annotations;
+    if (loc) info.location = loc;
+    if (fieldKind(af, structDefFields) === "measure") groups.measures.push(info);
+    else groups.dimensions.push(info);
+  }
+  return groups;
+}
+function walkExplore(e, ctx) {
+  const structDefFields = e.structDef.fields ?? [];
+  const anon = { byId: /* @__PURE__ */ new Map(), srcs: [] };
+  const groups = walkFields(e.allFields, structDefFields, 0, ctx, anon);
+  const annotations = annotationList(e.annotations);
+  const out = {
+    name: e.name,
+    primary_key: e.primaryKey ?? null,
+    ...groups
+  };
+  applyDocs(out, e.annotations);
+  if (needsQuote(e.name)) out.must_quote = true;
+  if (annotations.length > 0) out.annotations = annotations;
+  const mLoc = e.location;
+  if (isLocal(mLoc, ctx.rootUri)) {
+    const loc = toLoc(mLoc);
+    if (loc) out.location = loc;
+  }
+  if (mLoc) {
+    const body = sliceSource(ctx.readSource(mLoc.url), mLoc);
+    if (body) out.body = body;
+  }
+  if (anon.srcs.length > 0) out.anon_srcs = anon.srcs;
+  return out;
+}
+function renderGivenType(t) {
+  if (t.type === "filter expression") {
+    return t.filterType ? `filter<${t.filterType}>` : "filter";
+  }
+  if (t.type === "array") {
+    const elem = t.elementTypeDef;
+    if (!elem) return "array";
+    if (elem.type === "record_element") return "record[]";
+    return `${renderGivenType(elem)}[]`;
+  }
+  return t.type;
+}
+function describeGiven(g, surfaceName, ctx) {
+  const annotations = annotationList(g.annotations);
+  const info = {
+    name: surfaceName,
+    type: renderGivenType(g.type),
+    has_default: g.default !== void 0
+  };
+  applyDocs(info, g.annotations);
+  if (annotations.length > 0) info.annotations = annotations;
+  const loc = g.location;
+  if (ctx && loc) {
+    if (isLocal(loc, ctx.rootUri)) {
+      const l = toLoc(loc);
+      if (l) info.location = l;
+    }
+    const body = sliceSource(ctx.readSource(loc.url), loc);
+    if (body) info.body = body;
+  }
+  return info;
+}
+function readQueryGivens(getPq) {
+  try {
+    return [...getPq().givens.keys()];
+  } catch {
+    return [];
+  }
+}
+function walkModel(model, rootUri, opts, readSource) {
+  const modelQueries = model.queries();
+  const topLevel = (opts.exportedOnly ? model.exportedExplores : void 0) ?? model.explores;
+  const knownSources = /* @__PURE__ */ new Set([
+    ...topLevel.map((e) => e.name),
+    ...modelQueries.named
+  ]);
+  const ctx = { rootUri, knownSources, opts, readSource };
+  const sources = {};
+  for (const e of topLevel) {
+    sources[e.name] = walkExplore(e, ctx);
+  }
+  const queries = [];
+  for (const queryName of modelQueries.named) {
+    const pq = model.getPreparedQueryByName(queryName);
+    const annotations = annotationList(pq.annotations);
+    const info = { name: queryName };
+    applyDocs(info, pq.annotations);
+    if (needsQuote(queryName)) info.must_quote = true;
+    if (annotations.length > 0) info.annotations = annotations;
+    const loc = pq.location;
+    if (isLocal(loc, rootUri)) {
+      const l = toLoc(loc);
+      if (l) info.location = l;
+    }
+    if (loc) {
+      const body = sliceSource(readSource(loc.url), loc);
+      if (body) info.body = body;
+    }
+    const givenNames = readQueryGivens(() => pq);
+    if (givenNames.length > 0) info.givens = givenNames;
+    queries.push(info);
+  }
+  const runs = [];
+  for (let idx = 0; idx < modelQueries.unnamed; idx++) {
+    const pq = model.getPreparedQueryByIndex(idx);
+    const info = { index: idx };
+    const annotations = annotationList(pq.annotations);
+    if (annotations.length > 0) info.annotations = annotations;
+    const l = toLoc(pq.location);
+    if (l) info.location = l;
+    try {
+      const givenNames = [...pq.givens.keys()];
+      if (givenNames.length > 0) info.givens = givenNames;
+      if (opts.emitRunSql) info.sql = pq.preparedResult.sql.trim();
+    } catch (e) {
+      if (opts.emitRunSql) info.error = e instanceof Error ? e.message : String(e);
+    }
+    runs.push(info);
+  }
+  const out = { entry: rootUri, sources, queries, runs };
+  const modelAnnotations = annotationList(model.annotations);
+  if (modelAnnotations.length > 0) out.annotations = modelAnnotations;
+  const givens = [];
+  for (const [surfaceName, g] of model.givens) {
+    givens.push(describeGiven(
+      g,
+      surfaceName,
+      { rootUri, readSource }
+    ));
+  }
+  if (givens.length > 0) out.givens = givens;
+  return out;
+}
+function isCanonicalForm(source) {
+  const { formatted, problems } = prettify(source);
+  if (problems.length > 0) return void 0;
+  const norm = (s) => s.replace(/\r\n/g, "\n").trimEnd();
+  return norm(formatted) === norm(source);
+}
+async function compile(runtime, entry, opts = {}) {
+  const readSource = opts.readSource ?? (() => void 0);
+  try {
+    const model = await runtime.loadModel(entry).getModel();
+    try {
+      const info = walkModel(model, entry.href, {
+        expand: opts.expand ?? "ref",
+        emitRunSql: opts.emitRunSql ?? false,
+        exportedOnly: opts.exportedOnly ?? false,
+        readSource
+      }, readSource);
+      const out = {
+        ok: true,
+        model: info,
+        problems: mapProblems(model.problems)
+      };
+      const entryText = readSource(entry.href);
+      if (entryText !== void 0) {
+        const canonical = isCanonicalForm(entryText);
+        if (canonical !== void 0) out.formatted = canonical;
+      }
+      return out;
+    } catch (e) {
+      return { ok: false, problems: [...mapProblems(model.problems), errorProblem(e, entry.href)] };
+    }
+  } catch (e) {
+    if (e instanceof MalloyError) {
+      return { ok: false, problems: mapProblems(e.problems) };
+    }
+    return { ok: false, problems: [errorProblem(e, entry.href)] };
+  }
+}
+var EMPTY_GROUPS = { dimensions: [], measures: [], views: [], joins: [] };
+var seg = (m) => m.must_quote ? `\`${m.name}\`` : m.name;
+var barePath = (prefix, j) => prefix ? `${prefix}.${j.name}` : j.name;
+function joinCode(j) {
+  if (!j.body) return void 0;
+  const kw = j.relationship === "one_to_many" ? "join_many" : j.relationship === "cross" ? "join_cross" : "join_one";
+  return `${kw}: ${j.body}`;
+}
+function fieldDescriptor(f) {
+  const d = { type: f.type };
+  if (f.must_quote) d.must_quote = true;
+  if (f.expression) d.expression = f.expression;
+  if (f.description) d.description = f.description;
+  if (f.instructions) d.instructions = f.instructions;
+  return d;
+}
+function buildColumns(groups, pathPrefix) {
+  const out = /* @__PURE__ */ Object.create(null);
+  for (const f of groups.dimensions) out[f.name] = fieldDescriptor(f);
+  for (const j of groups.joins) {
+    if (j.column_shape === "record") {
+      const childPath = pathPrefix === null ? null : barePath(pathPrefix, j);
+      const rec = { type: buildColumns(j.fields ?? EMPTY_GROUPS, childPath) };
+      if (j.must_quote) rec.must_quote = true;
+      if (j.description) rec.description = j.description;
+      if (j.instructions) rec.instructions = j.instructions;
+      out[j.name] = rec;
+    } else if (j.column_shape === "scalar_array" || j.column_shape === "record_array") {
+      const stub = { is_array: true, fans_out: true };
+      if (pathPrefix !== null) stub.path = barePath(pathPrefix, j);
+      if (j.must_quote) stub.must_quote = true;
+      out[j.name] = stub;
+    }
+  }
+  return out;
+}
+function measuresMap(measures) {
+  const out = /* @__PURE__ */ Object.create(null);
+  for (const m of measures) out[m.name] = fieldDescriptor(m);
+  return out;
+}
+function buildSchema(groups, pathPrefix, meta) {
+  const s = {};
+  if (meta?.primary_key) s.primary_key = meta.primary_key;
+  if (meta?.description) s.description = meta.description;
+  if (meta?.instructions) s.instructions = meta.instructions;
+  s.dimensions = buildColumns(groups, pathPrefix);
+  s.measures = measuresMap(groups.measures);
+  return s;
+}
+function viewsMap(views) {
+  const out = /* @__PURE__ */ Object.create(null);
+  for (const v of views) out[seg(v)] = v.description ?? null;
+  return out;
+}
+function emitJoins(groups, anonScope, bare, quoted, fans, namedOnPath, anonOnPath, ctx) {
+  for (const j of groups.joins) {
+    const cBare = barePath(bare, j);
+    const cQuoted = quoted ? `${quoted}.${seg(j)}` : seg(j);
+    if (j.column_shape === "record") {
+      emitJoins(j.fields ?? EMPTY_GROUPS, anonScope, cBare, cQuoted, fans, namedOnPath, anonOnPath, ctx);
+    } else if (j.column_shape === "scalar_array" || j.column_shape === "record_array") {
+      emitArray(j, cBare, cQuoted, anonScope, namedOnPath, anonOnPath, ctx);
+    } else {
+      emitSourceJoin(j, cBare, cQuoted, anonScope, fans, namedOnPath, anonOnPath, ctx);
+    }
+  }
+}
+function withQuoted(entry, bare, quoted) {
+  if (quoted !== bare) entry.quoted_path = quoted;
+  return entry;
+}
+function emitArray(j, bare, quoted, anonScope, namedOnPath, anonOnPath, ctx) {
+  const fields = j.fields ?? EMPTY_GROUPS;
+  ctx.joins[bare] = withQuoted({ is_array: true, fans_out: true, source_def: buildSchema(fields, bare) }, bare, quoted);
+  emitJoins(fields, anonScope, bare, quoted, true, namedOnPath, anonOnPath, ctx);
+}
+function emitSourceJoin(j, bare, quoted, anonScope, fans, namedOnPath, anonOnPath, ctx) {
+  const entryFans = fans || j.relationship !== "many_to_one";
+  const entry = {};
+  if (entryFans) entry.fans_out = true;
+  withQuoted(entry, bare, quoted);
+  if (j.source_ref) {
+    entry.source = j.source_ref;
+    const namedCode = joinCode(j);
+    if (namedCode) entry.code = namedCode;
+    const target = ctx.model.sources[j.source_ref];
+    if (target && !(j.source_ref in ctx.map)) {
+      ctx.map[j.source_ref] = buildSchema(target, null, target);
+    }
+    if (namedOnPath.has(j.source_ref)) {
+      entry.cycle = true;
+      ctx.joins[bare] = entry;
+      return;
+    }
+    ctx.joins[bare] = entry;
+    if (target) {
+      emitJoins(
+        target,
+        target.anon_srcs ?? [],
+        bare,
+        quoted,
+        entryFans,
+        /* @__PURE__ */ new Set([...namedOnPath, j.source_ref]),
+        /* @__PURE__ */ new Set(),
+        ctx
+      );
+    }
+    return;
+  }
+  let fields;
+  let meta;
+  let anonIdx;
+  if (j.anon_src_index !== void 0) {
+    anonIdx = j.anon_src_index;
+    const a = anonScope[anonIdx];
+    if (a) {
+      fields = a;
+      meta = a;
+    }
+  } else if (j.fields) {
+    fields = j.fields;
+    meta = { description: j.description, instructions: j.instructions };
+  }
+  if (fields) entry.source_def = buildSchema(fields, bare, meta);
+  const anonCode = joinCode(j);
+  if (anonCode) entry.code = anonCode;
+  if (anonIdx !== void 0 && anonOnPath.has(anonIdx)) {
+    entry.cycle = true;
+    ctx.joins[bare] = entry;
+    return;
+  }
+  ctx.joins[bare] = entry;
+  if (fields) {
+    emitJoins(
+      fields,
+      anonScope,
+      bare,
+      quoted,
+      entryFans,
+      namedOnPath,
+      anonIdx !== void 0 ? /* @__PURE__ */ new Set([...anonOnPath, anonIdx]) : anonOnPath,
+      ctx
+    );
+  }
+}
+function buildSourceDescribe(model, name) {
+  const root = model.sources[name];
+  if (!root) return void 0;
+  const ctx = { model, joins: /* @__PURE__ */ Object.create(null), map: /* @__PURE__ */ Object.create(null) };
+  const described_source = {
+    name,
+    ...buildSchema(root, "", root),
+    views: viewsMap(root.views)
+  };
+  emitJoins(root, root.anon_srcs ?? [], "", "", false, /* @__PURE__ */ new Set([name]), /* @__PURE__ */ new Set(), ctx);
+  return { described_source, joins: ctx.joins, join_source_map: ctx.map };
+}
+function sourceEntryOf(s) {
+  const e = { source_ref: s.name };
+  if (s.description) e.description = s.description;
+  if (s.instructions) e.instructions = s.instructions;
+  if (s.must_quote) e.must_quote = true;
+  return e;
+}
+function modelCatalogEntry(model_ref, model) {
+  const entry = { model_ref };
+  const sources = Object.values(model.sources).map(sourceEntryOf);
+  if (sources.length) entry.sources = sources;
+  return entry;
+}
+var DEFAULT_ROW_LIMIT = 1e4;
+async function executeMaterialized(query, opts, loadProblems, decorate = (p) => p, uri) {
+  const rowLimit = opts.rowLimit ?? DEFAULT_ROW_LIMIT;
+  const retry = opts.retry ?? ((op) => op());
+  const compileOpts = opts.givens ? { givens: opts.givens } : void 0;
+  try {
+    const t0 = Date.now();
+    const sql = (await query.getSQL(compileOpts)).trim();
+    const t1 = Date.now();
+    const results = await retry(() => query.run({ rowLimit, ...compileOpts }));
+    const t2 = Date.now();
+    const rows = results.toJSON().queryResult.result;
+    const out = {
+      ok: true,
+      sql,
+      rows,
+      row_count: rows.length,
+      rows_returned: rows.length,
+      compile_time_ms: t1 - t0,
+      total_time_ms: t2 - t0,
+      problems: loadProblems
+    };
+    if (rows.length === rowLimit) {
+      out.truncated = {
+        reason: "row_limit",
+        hint: `Result hit the ${rowLimit}-row limit; more rows may exist. Aggregate, filter, or do top-N in Malloy rather than fetching rows to post-process.`
+      };
+    }
+    if (opts.stableResult) out.stable_result = API.util.wrapResult(results);
+    return out;
+  } catch (e) {
+    if (e instanceof MalloyError2) {
+      return { ok: false, problems: [...loadProblems, ...mapProblems(e.problems).map(decorate)] };
+    }
+    return { ok: false, problems: [...loadProblems, errorProblem(e, uri)] };
+  }
+}
+async function queryGivens(q) {
+  try {
+    const pq = await q.getPreparedQuery();
+    const out = [];
+    for (const [name, g] of pq.givens) {
+      out.push(describeGiven(g, name));
+    }
+    return out.length > 0 ? out : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function validateRestricted(runtime, entry, query) {
+  let loadProblems;
+  let materializer;
+  try {
+    materializer = runtime.loadModel(entry);
+    const model = await materializer.getModel();
+    loadProblems = mapProblems(model.problems);
+  } catch (e) {
+    if (e instanceof MalloyError3) {
+      return { ok: false, problems: mapProblems(e.problems) };
+    }
+    return { ok: false, problems: [errorProblem(e, entry.href)] };
+  }
+  try {
+    const q = materializer.loadRestrictedQuery(query);
+    const problems = [...loadProblems, ...mapProblems(await q.validate())];
+    const ok = !hasError(problems);
+    const out = { ok, problems };
+    if (ok) {
+      try {
+        out.sql = (await q.getSQL()).trim();
+      } catch {
+      }
+      const givens = await queryGivens(q);
+      if (givens) out.givens = givens;
+    }
+    return out;
+  } catch (e) {
+    if (e instanceof MalloyError3) {
+      return { ok: false, problems: [...loadProblems, ...mapProblems(e.problems)] };
+    }
+    return { ok: false, problems: [...loadProblems, errorProblem(e, entry.href)] };
+  }
+}
+async function runRestricted(runtime, entry, query, opts = {}) {
+  let loadProblems;
+  let materializer;
+  try {
+    materializer = runtime.loadModel(entry);
+    const model = await materializer.getModel();
+    loadProblems = mapProblems(model.problems);
+  } catch (e) {
+    if (e instanceof MalloyError3) {
+      return { ok: false, problems: mapProblems(e.problems) };
+    }
+    return { ok: false, problems: [errorProblem(e, entry.href)] };
+  }
+  try {
+    const q = materializer.loadRestrictedQuery(query);
+    return await executeMaterialized(q, opts, loadProblems, (p) => p, entry.href);
+  } catch (e) {
+    if (e instanceof MalloyError3) {
+      return { ok: false, problems: [...loadProblems, ...mapProblems(e.problems)] };
+    }
+    return { ok: false, problems: [...loadProblems, errorProblem(e, entry.href)] };
+  }
+}
+var INSTANCE_PLACEHOLDER = "{{INSTANCE_NAME}}";
+function renderInstructions(text, instanceName) {
+  return text.replaceAll(INSTANCE_PLACEHOLDER, instanceName);
+}
+var VIRTUAL_BASE = "memory://mcp-engine/";
+function normalizeUrl2(u) {
+  if (u.includes("://")) return new URL(u);
+  return url.pathToFileURL(path.resolve(u));
+}
+function inlineVirtualUrl(baseUrl) {
+  if (baseUrl) return new URL("__inline__.malloy", normalizeUrl2(baseUrl));
+  return new URL(VIRTUAL_BASE + "__inline__.malloy");
+}
+function prepareSource(base, input) {
+  const inline = "source" in input;
+  const entry = inline ? inlineVirtualUrl(input.baseUrl) : normalizeUrl2(input.url);
+  const cache = /* @__PURE__ */ new Map();
+  if (inline) cache.set(entry.href, input.source);
+  const reader = {
+    readURL: async (u) => {
+      const cached = cache.get(u.href);
+      if (cached !== void 0) return cached;
+      const text = await base.readURL(u);
+      const str = typeof text === "string" ? text : String(text);
+      cache.set(u.href, str);
+      return str;
+    }
+  };
+  return { reader, entry, readSource: (href) => cache.get(href) };
+}
+var DEFAULT_RESULT_BYTES = 25e3;
+function argString(args, key) {
+  const v = args[key];
+  return v === void 0 || v === null ? "" : String(v);
+}
+function argOptString(args, key) {
+  const v = args[key];
+  return v === void 0 || v === null || v === "" ? void 0 : String(v);
+}
+function argOptNumber(args, key) {
+  const v = args[key];
+  if (v === void 0 || v === null) return void 0;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : void 0;
+}
+function argOptBool(args, key) {
+  const v = args[key];
+  if (v === void 0 || v === null) return void 0;
+  return v === true || v === "true";
+}
+function argRecord(args, key) {
+  const v = args[key];
+  if (v && typeof v === "object" && !Array.isArray(v)) {
+    return v;
+  }
+  return void 0;
+}
+function yoHelpTool() {
+  return {
+    name: "yo_help",
+    title: prompts.shared.tools.yo_help.title,
+    description: prompts.shared.tools.yo_help.description,
+    inputSchema: {
+      type: "object",
+      properties: {
+        topic: {
+          type: "string",
+          description: 'A topic name from the index, e.g. "explore/how-to" or "language/joins" (case-insensitive). Omit to list all topic names.'
+        }
+      },
+      additionalProperties: false
+    },
+    handler: async (args) => {
+      const topic = argOptString(args, "topic");
+      if (!topic) return { topics: listHelpTopics() };
+      const hit = getHelpTopic(topic);
+      if (!hit) {
+        return { error: `No topic matches '${topic}'.`, topics: listHelpTopics() };
+      }
+      return { name: hit.name, body: hit.body };
+    }
+  };
+}
+function sharedSkills() {
+  return engineSkills();
+}
+function attachHelp(result) {
+  const problems = result.problems;
+  if (!Array.isArray(problems) || problems.length === 0) return result;
+  const help = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const p of problems) {
+    if (!p.help_topic || seen.has(p.help_topic)) continue;
+    seen.add(p.help_topic);
+    const hit = getHelpTopic(p.help_topic);
+    if (hit) help.push(hit);
+  }
+  return help.length ? { ...result, help } : result;
+}
+function withHelp(tool) {
+  return { ...tool, handler: async (args) => attachHelp(await tool.handler(args)) };
+}
+var REFINE_HINT = "Aggregate, filter, or do top-N in Malloy rather than fetching rows to post-process; select fewer columns if rows are wide.";
+function fittingPrefix(rows, maxBytes) {
+  let bytes = 2;
+  for (let i = 0; i < rows.length; i++) {
+    const rowBytes = Buffer.byteLength(JSON.stringify(rows[i]) ?? "null", "utf8");
+    if (bytes + rowBytes + 1 > maxBytes) return i;
+    bytes += rowBytes + 1;
+  }
+  return rows.length;
+}
+async function applyResultBudget(full, policy, ctx) {
+  const { stable_result, ...wire } = full;
+  if (!wire.ok || !wire.rows) return wire;
+  const maxBytes = policy?.maxResultBytes ?? DEFAULT_RESULT_BYTES;
+  const keep = fittingPrefix(wire.rows, maxBytes);
+  if (keep >= wire.rows.length) return wire;
+  let fullResultUri;
+  if (policy?.spill) {
+    try {
+      fullResultUri = (await policy.spill(full, ctx))?.uri;
+    } catch {
+    }
+  }
+  const out = {
+    ...wire,
+    rows: wire.rows.slice(0, keep),
+    rows_returned: keep,
+    truncated: {
+      reason: "byte_budget",
+      hint: keep === 0 ? "A single row exceeds the response byte budget \u2014 project fewer columns or un-nest the result. " + REFINE_HINT : `Result truncated to ${keep} of ${wire.row_count} rows to fit the response byte budget. ` + REFINE_HINT,
+      ...fullResultUri ? { full_result: fullResultUri } : {}
+    }
+  };
+  return out;
+}
+var guidance = {
+  core: prompts.core.instructions,
+  develop: prompts.develop.instructions,
+  explore: prompts.explore.instructions
+};
+function assembleInstructions(kind) {
+  const surface = kind === "develop" ? guidance.develop : guidance.explore;
+  return [surface, guidance.core].filter(Boolean).join("\n\n");
+}
+function refModelProblem(ref, e) {
+  const msg = e instanceof Error ? e.message : String(e);
+  return codeProblem("model-not-found", `Cannot use model '${ref}': ${msg}`);
+}
+async function executeQuery(m, args, fix, result) {
+  const malloy = argString(args, "malloy");
+  const execute = argOptBool(args, "execute") ?? true;
+  const givens = argRecord(args, "givens");
+  const rowLimit = Math.max(1, Math.min(1e4, argOptNumber(args, "max_rows") ?? DEFAULT_ROW_LIMIT));
+  if (!execute) {
+    const v = await validateRestricted(m.runtime, m.entry, malloy);
+    return { ...v, problems: v.problems.map(fix) };
+  }
+  const full = await runRestricted(m.runtime, m.entry, malloy, { rowLimit, givens });
+  const budgeted = await applyResultBudget(full, result, { toolName: "query", args });
+  return { ...budgeted, problems: budgeted.problems.map(fix) };
+}
+async function resolveModel(host, source, modelRef) {
+  if (modelRef) return { model_ref: modelRef };
+  if (!host.list) {
+    return {
+      problem: codeProblem(
+        "model-ref-required",
+        "Pass model_ref + source. Use list_sources to see which model a source lives in."
+      )
+    };
+  }
+  const entries = (await host.list()).entries;
+  const hits = entries.filter((e) => e.sources?.some((s) => s.source_ref === source));
+  if (hits.length === 1) return { model_ref: hits[0].model_ref };
+  if (hits.length === 0) {
+    return {
+      problem: codeProblem(
+        "source-not-found",
+        `No exported source named '${source}' in any model you can see. Call list_sources, or pass model_ref if it is an internal source.`
+      )
+    };
+  }
+  return {
+    problem: codeProblem(
+      "source-ambiguous",
+      `Source '${source}' exists in more than one model: ${hits.map((h) => h.model_ref).join(", ")}. Pass model_ref to pick one.`
+    )
+  };
+}
+function srcNudge(modelRef, source) {
+  return (p) => {
+    if (p.code !== "field-not-found") return p;
+    return {
+      ...p,
+      message: `${p.message} \u2014 call describe_source with source="${source}"` + (modelRef ? ` model_ref="${modelRef}"` : "") + " to see what fields, measures, views, and joins exist.",
+      help_topic: p.help_topic ?? "language/fields"
+    };
+  };
+}
+function sourceAsMalloy(s) {
+  return s?.body ? `source: ${s.body}` : "";
+}
+function listSourcesTool(host) {
+  return {
+    name: "list_sources",
+    title: prompts.explore.tools.list_sources.title,
+    description: prompts.explore.tools.list_sources.description,
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    handler: async () => {
+      const { entries } = await host.list();
+      const models = /* @__PURE__ */ Object.create(null);
+      for (const e of entries) {
+        const m = {};
+        if (e.description) m.description = e.description;
+        if (e.instructions) m.instructions = e.instructions;
+        if (e.sources?.length) {
+          const sources = /* @__PURE__ */ Object.create(null);
+          for (const s of e.sources) {
+            const o = {};
+            if (s.description) o.description = s.description;
+            if (s.instructions) o.instructions = s.instructions;
+            if (s.must_quote) o.must_quote = true;
+            sources[s.source_ref] = o;
+          }
+          m.sources = sources;
+        }
+        models[e.model_ref] = m;
+      }
+      return { ok: true, guidance: prompts.explore.guidance, models };
+    }
+  };
+}
+function describeSourceTool(host) {
+  return {
+    name: "describe_source",
+    title: prompts.explore.tools.describe_source.title,
+    description: prompts.explore.tools.describe_source.description,
+    inputSchema: {
+      type: "object",
+      properties: {
+        source: { type: "string", description: "The source to describe (a source the model publishes)." },
+        model_ref: {
+          type: "string",
+          description: "The model the source lives in (the model_ref from list_sources). Optional when the source name is unique across the catalog."
+        }
+      },
+      required: ["source"],
+      additionalProperties: false
+    },
+    handler: async (args) => {
+      const source = argString(args, "source");
+      const modelRefArg = argOptString(args, "model_ref");
+      if (!source.trim()) {
+        return {
+          ok: false,
+          model_ref: modelRefArg ?? "",
+          source,
+          problems: [codeProblem("source-required", "A source name is required. Use list_sources to see them.")]
+        };
+      }
+      const r = await resolveModel(host, source, modelRefArg);
+      if ("problem" in r) {
+        return { ok: false, model_ref: modelRefArg ?? "", source, problems: [r.problem] };
+      }
+      const modelRef = r.model_ref;
+      try {
+        return await host.withModel(modelRef, async (m) => {
+          const compiled = await compile(m.runtime, m.entry, { readSource: m.readSource });
+          if (!compiled.ok || !compiled.model) {
+            return { ok: false, model_ref: modelRef, source, problems: compiled.problems };
+          }
+          const built = buildSourceDescribe(compiled.model, source);
+          if (!built) {
+            const available = Object.keys(compiled.model.sources);
+            return {
+              ok: false,
+              model_ref: modelRef,
+              source,
+              problems: [
+                ...compiled.problems,
+                codeProblem(
+                  "source-not-found",
+                  `No source named '${source}' in '${modelRef}'. Sources: ${available.join(", ") || "(none)"}.`
+                )
+              ]
+            };
+          }
+          const malloy_text = sourceAsMalloy(compiled.model.sources[source]);
+          const base = {
+            ok: true,
+            model_ref: modelRef,
+            source,
+            guidance: prompts.explore.guidance,
+            described_source: built.described_source,
+            problems: compiled.problems
+          };
+          if (Object.keys(built.joins).length) base.joins = built.joins;
+          if (Object.keys(built.join_source_map).length) base.join_source_map = built.join_source_map;
+          return malloy_text ? { ...base, malloy_text } : base;
+        });
+      } catch (e) {
+        return { ok: false, model_ref: modelRef, source, problems: [refModelProblem(modelRef, e)] };
+      }
+    }
+  };
+}
+function exploreQueryTool(host, opts) {
+  return {
+    name: "query",
+    title: prompts.shared.tools.query.title,
+    description: prompts.shared.tools.query.description,
+    inputSchema: {
+      type: "object",
+      properties: {
+        source: { type: "string", description: "The source the query runs against." },
+        malloy: { type: "string", description: "Malloy query text, e.g. `run: orders -> { ... }`." },
+        model_ref: {
+          type: "string",
+          description: "The model the source lives in (optional when the source name is unique)."
+        },
+        question: {
+          type: "string",
+          description: "Plain-English description of what this query answers; hosts may record or share it."
+        },
+        givens: {
+          type: "object",
+          description: "Values for $NAME givens, keyed by name (no $). Discover which a query needs with execute:false."
+        },
+        execute: {
+          type: "boolean",
+          description: "Default true. false \u2192 compile/validate only (returns SQL + the givens the query references)."
+        },
+        max_rows: { type: "integer", minimum: 1, maximum: 1e4, description: `Row cap (default ${DEFAULT_ROW_LIMIT}).` }
+      },
+      required: ["source", "malloy"],
+      additionalProperties: false
+    },
+    handler: async (args) => {
+      const source = argString(args, "source");
+      const modelRefArg = argOptString(args, "model_ref");
+      const execute = argOptBool(args, "execute") ?? true;
+      const r = await resolveModel(host, source, modelRefArg);
+      if ("problem" in r) return { ok: false, problems: [r.problem] };
+      const modelRef = r.model_ref;
+      if (modelRefArg && host.list) {
+        const entries = (await host.list()).entries;
+        const here = entries.find((e) => e.model_ref === modelRef);
+        const inModel = here?.sources?.some((s) => s.source_ref === source) ?? false;
+        const elsewhere = entries.filter((e) => e.model_ref !== modelRef && e.sources?.some((s) => s.source_ref === source)).map((e) => e.model_ref);
+        if (here && !inModel && elsewhere.length > 0) {
+          return {
+            ok: false,
+            problems: [
+              codeProblem(
+                "source-not-in-model",
+                `Model '${modelRef}' has no source '${source}' \u2014 it's in: ${elsewhere.join(", ")}. Pass that model_ref, or fix the source name.`
+              )
+            ]
+          };
+        }
+      }
+      try {
+        return await host.withModel(modelRef, async (m) => {
+          const res = await executeQuery(m, args, srcNudge(modelRef, source), opts.result);
+          if (!execute) return { ...res, model_ref: modelRef };
+          const { sql, ...rest } = res;
+          const out = { ...rest, model_ref: modelRef };
+          if (sql !== void 0) out[HOST_ONLY] = { sql };
+          return out;
+        });
+      } catch (e) {
+        return { ok: false, problems: [refModelProblem(modelRef, e)] };
+      }
+    }
+  };
+}
+function exploreSurface(host, opts = {}) {
+  const tools = [];
+  if (host.list) tools.push(listSourcesTool(host));
+  tools.push(describeSourceTool(host));
+  tools.push(exploreQueryTool(host, opts));
+  tools.push(yoHelpTool());
+  return {
+    tools: tools.map(withHelp),
+    instructions: assembleInstructions("explore"),
+    skills: sharedSkills()
+  };
+}
+
+// ../mcp-engine/dist/mcp-sdk.js
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+var HOST_ONLY2 = "host_only";
+function toContent(result) {
+  const { malloy_text, [HOST_ONLY2]: _hostOnly, ...rest } = result;
+  const content = [
+    { type: "text", text: JSON.stringify(rest, null, 2) }
+  ];
+  if (typeof malloy_text === "string" && malloy_text.length > 0) {
+    content.push({ type: "text", text: malloy_text });
+  }
+  return { content, structuredContent: { ...rest } };
+}
+function lowLevel(server) {
+  return "server" in server ? server.server : server;
+}
+function attachSurface(server, surface, opts = {}) {
+  const s = lowLevel(server);
+  const byName = new Map(surface.tools.map((t) => [t.name, t]));
+  s.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: surface.tools.map((t) => ({
+      name: t.name,
+      title: t.title,
+      description: t.description,
+      inputSchema: t.inputSchema
+    }))
+  }));
+  s.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const tool = byName.get(req.params.name);
+    if (!tool) {
+      return {
+        content: [{ type: "text", text: `unknown tool: ${req.params.name}` }],
+        isError: true
+      };
+    }
+    const result = await tool.handler(
+      req.params.arguments ?? {}
+    );
+    return toContent(result);
+  });
+  if (opts.registerSkillsAsPrompts && "registerPrompt" in server) {
+    const mcp = server;
+    for (const skill of surface.skills) {
+      mcp.registerPrompt(
+        skill.name,
+        { title: skill.name, description: skill.description },
+        () => ({
+          messages: [
+            { role: "user", content: { type: "text", text: skill.body } }
+          ]
+        })
+      );
+      mcp.registerResource(
+        skill.name,
+        `malloy-skill://${skill.name}`,
+        { title: skill.name, description: skill.description, mimeType: "text/markdown" },
+        async (uri) => ({
+          contents: [{ uri: uri.href, mimeType: "text/markdown", text: skill.body }]
+        })
+      );
+    }
+  }
+}
+
+// src/mcp.ts
+var ENTRY = "index.malloy";
+function defaultConfig(rootUrl) {
+  return new MalloyConfig({ includeDefaultConnections: true }, {
+    rootDirectory: rootUrl.toString()
+  });
+}
+async function loadConfig(root, reader) {
+  const rootUrl = url2.pathToFileURL(root + path2.sep);
+  let discovered;
+  try {
+    discovered = await discoverConfig(rootUrl, rootUrl, reader);
+  } catch (e) {
+    return {
+      config: defaultConfig(rootUrl),
+      problems: [codeProblem("config-validation", e instanceof Error ? e.message : String(e))]
+    };
+  }
+  if (discovered) {
+    const log = discovered.log ?? [];
+    return { config: discovered, problems: mapProblems([...log]) };
+  }
+  return { config: defaultConfig(rootUrl), problems: [] };
+}
+function fsReader() {
+  return {
+    readURL: async (u) => {
+      if (u.protocol !== "file:") {
+        throw new Error(`unsupported URL scheme for import: ${u.href}`);
+      }
+      return fs.promises.readFile(u, "utf8");
+    }
+  };
+}
+function resolveUnderRoot(root, p) {
+  const abs = p.includes("://") ? path2.resolve(decodeURIComponent(new URL(p).pathname)) : path2.resolve(root, p);
+  if (abs !== root && !abs.startsWith(root + path2.sep)) {
+    throw new Error(`path is outside the project root: ${p}`);
+  }
+  return abs;
+}
+function makeConfigSource(root) {
+  let cached;
+  const signature = () => ["malloy-config.json", "malloy-config-local.json"].map((name) => {
+    try {
+      const st = fs.statSync(path2.join(root, name));
+      return `${name}:${st.mtimeMs}:${st.size}`;
+    } catch {
+      return `${name}:absent`;
+    }
+  }).join("|");
+  return async () => {
+    const sig = signature();
+    if (cached?.sig !== sig) {
+      cached = { sig, loaded: await loadConfig(root, fsReader()) };
+    }
+    return cached.loaded;
+  };
+}
+function makeWithRuntime(root, currentConfig) {
+  return async function withRuntime(input, fn) {
+    const { config, problems } = await 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 + path2.sep
+      };
+      const { reader, entry, readSource } = prepareSource(fsReader(), resolved);
+      const runtime = new Runtime({ config, urlReader: reader });
+      try {
+        return await fn({ runtime, entry, readSource });
+      } finally {
+        await config.shutdown("idle");
+      }
+    });
+  };
+}
+function makeExploreHost(root, currentConfig) {
+  const withRuntime = makeWithRuntime(root, currentConfig);
+  const published = (ref) => ref === ENTRY && fs.existsSync(path2.join(root, ENTRY));
+  return {
+    withModel: (ref, fn) => {
+      if (!published(ref)) throw new Error(`no published model '${ref}'`);
+      return withRuntime({ url: ENTRY }, fn);
+    },
+    list: async () => {
+      if (!published(ENTRY)) return { entries: [] };
+      const entry = await withRuntime({ url: ENTRY }, async (m) => {
+        const compiled = await compile(m.runtime, m.entry, { exportedOnly: true });
+        return compiled.ok && compiled.model ? modelCatalogEntry(ENTRY, compiled.model) : { model_ref: ENTRY };
+      });
+      return { entries: [entry] };
+    }
+  };
+}
+async function serveMcp(opts) {
+  await import("@malloydata/malloy-connections");
+  const root = path2.resolve(opts.root ?? process.cwd());
+  const currentConfig = makeConfigSource(root);
+  const surface = exploreSurface(makeExploreHost(root, currentConfig));
+  const instanceName = process.env.INSTANCE_NAME || "Malloyyo";
+  const server = new McpServer(
+    { name: "malloyyo-explore", version: opts.version },
+    {
+      instructions: renderInstructions(surface.instructions, instanceName),
+      capabilities: { tools: {}, prompts: {}, resources: {} }
+    }
+  );
+  attachSurface(server, surface, { registerSkillsAsPrompts: true });
+  await server.connect(new StdioServerTransport());
+  await new Promise((resolveDone) => {
+    server.server.onclose = () => resolveDone();
+  });
+  await (await currentConfig()).config.shutdown("close").catch(() => {
+  });
+}
+
+// src/index.ts
+var VERSION = "0.2.0";
+function shortSha(sha) {
+  return sha ? sha.slice(0, 7) : "";
+}
+async function publish(target, dir, opts) {
+  const root = resolve(dir);
+  const t = resolveTarget(root, target);
+  const bearer = await getAccessToken(t, { tokenFlag: opts.token });
+  const { files, config } = gatherDirectory(root);
+  if (files.length === 0) {
+    throw new Error(`No .malloy files found under ${root}`);
+  }
+  const git = gitInfo(root);
+  const body = { files, config, git };
+  const provenance = git.sha ? `${git.branch}@${shortSha(git.sha)}${git.dirty ? " (dirty)" : ""}` : "(no git)";
+  console.log(`\u2192 ${t.url}  dataset=${t.dataset}`);
+  console.log(`  ${files.length} file(s)  ${provenance}`);
+  if (opts.dryRun) {
+    console.log("dry run \u2014 not sending");
+    return;
+  }
+  const res = await fetch(`${t.url}/api/datasets/${t.dataset}/model/push`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${bearer}` },
+    body: JSON.stringify(body)
+  });
+  const out = await res.json().catch(() => ({}));
+  if (!res.ok || !out.ok) {
+    throw new Error(`publish failed: ${out.error ?? `${res.status} ${res.statusText}`}`);
+  }
+  console.log(`\u2713 published version ${out.version} \u2014 ${out.sources?.length ?? 0} source(s)`);
+}
+async function status(target, opts) {
+  const t = resolveTarget(resolve("."), target);
+  const bearer = await getAccessToken(t, { tokenFlag: opts.token });
+  const res = await fetch(`${t.url}/api/datasets/${t.dataset}/model/status`, {
+    headers: { authorization: `Bearer ${bearer}` }
+  });
+  if (!res.ok) {
+    throw new Error(`status failed: ${res.status} ${res.statusText}`);
+  }
+  const s = await res.json();
+  const git = s.git;
+  console.log(`${t.name}: ${t.url}  dataset=${t.dataset}`);
+  console.log(`  version ${s.version ?? "?"}` + (git?.sha ? `  ${git.branch}@${shortSha(git.sha)}` : ""));
+  console.log(`  ${s.compileError ? `\u2717 ${s.compileError}` : `\u2713 compiled ${s.compiledAt ?? ""}`}`);
+}
+async function loginCmd(target) {
+  const inst = resolveInstance(resolve("."), target);
+  await login(inst.url);
+  console.log(`\u2713 logged in to ${inst.name} (${inst.url})`);
+}
+async function logoutCmd(target) {
+  const inst = resolveInstance(resolve("."), target);
+  console.log(clearCreds(inst.url) ? `\u2713 logged out of ${inst.url}` : `not logged in to ${inst.url}`);
+}
+var program = new Command();
+program.name("malloyyo").description("Publish Malloy models to a Malloyyo instance").version(VERSION);
+program.command("login").argument("[target]", "target name or instance URL (optional if the config has one target)").description("sign in to an instance in your browser (stores a token)").action(loginCmd);
+program.command("logout").argument("[target]", "target name or instance URL (optional if the config has one target)").description("forget the stored token for an instance").action(logoutCmd);
+program.command("publish").argument("<target>", "named target from the `malloyyo` config block").argument("[dir]", "directory to publish", ".").option("--token <token>", "bearer token (overrides login/env)").option("--dry-run", "gather and report what would be sent, but don't POST").description('push the Malloy model in <dir> (default ".") to <target>').action(publish);
+program.command("status").argument("<target>", "named target from the `malloyyo` config block").option("--token <token>", "bearer token (overrides login/env)").description("show what's live on <target>: version, commit, compile state").action(status);
+program.command("mcp").option("-C, --root <dir>", "project root (default: current directory)").description(
+  "run a local stdio MCP server (the explore / test-window surface) over the Malloy model in the current directory"
+).action(async (opts) => {
+  await serveMcp({ root: opts.root, version: VERSION });
+});
+program.parseAsync().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});