@malloy-publisher/server 0.0.248 → 0.0.249

package/dist/server.mjs

@@ -156501,6 +156501,8 @@ function internalErrorToHttpError(error) {
     return httpError(404, error.message);
   } else if (error instanceof ModelNotFoundError) {
     return httpError(404, error.message);
+  } else if (error instanceof DashboardNotFoundError) {
+    return httpError(404, error.message);
   } else if (error instanceof NotQueryableError) {
     return httpError(404, error.message);
   } else if (error instanceof MalloyError) {
@@ -156546,7 +156548,7 @@ function httpError(code, message) {
     }
   };
 }
-var NotImplementedError, BadRequestError, InvalidArgumentError, EnvironmentNotFoundError, PackageNotFoundError, ModelNotFoundError, ConnectionNotFoundError, ConnectionError, DestinationNotFoundError, ConnectionAuthError, UnsupportedCatalogFormatError, ModelCompilationError, MaterializationEligibilityError, FrozenConfigError, AccessDeniedError, NotQueryableError, MaterializationNotFoundError, MaterializationConflictError, InvalidStateTransitionError, ServiceUnavailableError, PayloadTooLargeError, ResponseUnserializableError, QueryTimeoutError;
+var NotImplementedError, BadRequestError, InvalidArgumentError, EnvironmentNotFoundError, PackageNotFoundError, ModelNotFoundError, DashboardNotFoundError, ConnectionNotFoundError, ConnectionError, DestinationNotFoundError, ConnectionAuthError, UnsupportedCatalogFormatError, ModelCompilationError, MaterializationEligibilityError, FrozenConfigError, AccessDeniedError, NotQueryableError, MaterializationNotFoundError, MaterializationConflictError, InvalidStateTransitionError, ServiceUnavailableError, PayloadTooLargeError, ResponseUnserializableError, QueryTimeoutError;
 var init_errors = __esm(() => {
   init_constants();
   NotImplementedError = class NotImplementedError extends Error {
@@ -156576,6 +156578,11 @@ var init_errors = __esm(() => {
       super(message);
     }
   };
+  DashboardNotFoundError = class DashboardNotFoundError extends Error {
+    constructor(message) {
+      super(message);
+    }
+  };
   ConnectionNotFoundError = class ConnectionNotFoundError extends Error {
     constructor(message) {
       super(message);
@@ -179835,6 +179842,11 @@ var require_utils74 = __commonJS((exports, module) => {
   };
 });
 
+// ../../node_modules/ssh2/lib/protocol/crypto/build/Release/sshcrypto.node
+var require_sshcrypto = __commonJS((exports, module) => {
+  module.exports = __require("./sshcrypto-vd2k5hq9.node");
+});
+
 // ../../node_modules/ssh2/lib/protocol/crypto/poly1305.js
 var require_poly1305 = __commonJS((exports, module) => {
   var __dirname = "/home/runner/work/publisher/publisher/node_modules/ssh2/lib/protocol/crypto", __filename = "/home/runner/work/publisher/publisher/node_modules/ssh2/lib/protocol/crypto/poly1305.js";
@@ -180321,7 +180333,7 @@ var require_crypto = __commonJS((exports, module) => {
   var ChaChaPolyDecipher;
   var GenericDecipher;
   try {
-    binding = (()=>{throw new Error("Cannot require module "+"./crypto/build/Release/sshcrypto.node");})();
+    binding = require_sshcrypto();
     ({
       AESGCMCipher,
       ChaChaPolyCipher,
@@ -244754,6 +244766,835 @@ var require_dist11 = __commonJS((exports) => {
   }
 });
 
+// src/service/annotations.ts
+import { Annotations } from "@malloydata/malloy";
+function isReservedRoute(route) {
+  return route === "" || !/[\p{L}\p{N}]/u.test(route);
+}
+function ownModelAnnotations(modelDef) {
+  return foldModelAnnotations(modelDef, (id) => id === modelDef.modelID || id.startsWith("internal://"));
+}
+function modelAnnotations(modelDef) {
+  return foldModelAnnotations(modelDef, () => true);
+}
+function foldModelAnnotations(modelDef, admits) {
+  const registry = modelDef.modelAnnotations ?? {};
+  const visited = new Set;
+  const order = [];
+  const visit = (id) => {
+    if (!admits(id))
+      return;
+    if (visited.has(id))
+      return;
+    visited.add(id);
+    const entry = registry[id];
+    if (!entry)
+      return;
+    for (const dep of entry.inheritsFrom)
+      visit(dep);
+    order.push(id);
+  };
+  visit(modelDef.modelID);
+  let folded;
+  for (const id of order) {
+    const own = registry[id].ownNotes;
+    if (!own.notes?.length && !own.blockNotes?.length)
+      continue;
+    folded = {
+      notes: own.notes,
+      blockNotes: own.blockNotes,
+      inherits: folded
+    };
+  }
+  return folded ?? {};
+}
+function ownModelNotes(modelDef) {
+  const registry = modelDef.modelAnnotations ?? {};
+  const isSameDocument = (id) => id === modelDef.modelID || id.startsWith("internal://");
+  const seen = new Set;
+  const texts = [];
+  const visit = (id) => {
+    if (seen.has(id) || !isSameDocument(id))
+      return;
+    seen.add(id);
+    const entry = registry[id];
+    if (!entry)
+      return;
+    for (const dep of entry.inheritsFrom)
+      visit(dep);
+    texts.push(...ownLevelNoteTexts(entry.ownNotes));
+  };
+  visit(modelDef.modelID);
+  return texts;
+}
+function annotationTexts(annote) {
+  const texts = new Annotations(annote).texts();
+  return texts.length > 0 ? texts : undefined;
+}
+function ownLevelNoteTexts(annote) {
+  return ownLevelNotes(annote).map((note) => note.text);
+}
+function ownLevelNotes(annote) {
+  return [...annote?.blockNotes ?? [], ...annote?.notes ?? []];
+}
+var init_annotations = () => {};
+
+// src/service/motly.ts
+import { parseAnnotation } from "@malloydata/malloy-tag";
+function onMotlyRoute(text) {
+  const afterSigil = text.replace(/^##?\|?/, "");
+  return afterSigil === "" || /^[ \t\r\n]/.test(afterSigil);
+}
+function hasEnvReference(annotation) {
+  return annotation.includes("@env.");
+}
+function pollutionTargets() {
+  const targets = [Object.prototype];
+  for (const key of Object.getOwnPropertyNames(Object.prototype)) {
+    const descriptor = Object.getOwnPropertyDescriptor(Object.prototype, key);
+    if (!descriptor)
+      continue;
+    let value;
+    if ("value" in descriptor) {
+      value = descriptor.value;
+    } else {
+      if (BUILT_IN_PROTO_GETTER === undefined || descriptor.get !== BUILT_IN_PROTO_GETTER) {
+        return;
+      }
+      continue;
+    }
+    if ((typeof value === "object" || typeof value === "function") && value !== null && !targets.includes(value)) {
+      targets.push(value);
+    }
+  }
+  return targets;
+}
+function parseGuarded(texts) {
+  const targets = pollutionTargets();
+  if (targets === undefined) {
+    return { tag: undefined, messages: [UNSAFE_TO_PARSE] };
+  }
+  let unreadable = false;
+  const ownNames = (target) => {
+    try {
+      return Object.getOwnPropertyNames(target);
+    } catch {
+      unreadable = true;
+      return [];
+    }
+  };
+  const before = targets.map(ownNames);
+  if (unreadable)
+    return { tag: undefined, messages: [UNSAFE_TO_PARSE] };
+  const undoPollution = () => {
+    let polluted = false;
+    targets.forEach((target, index) => {
+      for (const key of ownNames(target)) {
+        if (before[index].includes(key))
+          continue;
+        polluted = true;
+        try {
+          delete target[key];
+        } catch {}
+      }
+    });
+    return polluted || unreadable;
+  };
+  if (texts.some((text) => text.length > MAX_ANNOTATION_CHARS)) {
+    return { tag: undefined, messages: [ANNOTATION_TOO_LONG] };
+  }
+  try {
+    const result = parseAnnotation([...texts]);
+    if (undoPollution())
+      return { tag: undefined, messages: [UNSAFE_TO_PARSE] };
+    return {
+      tag: result.tag,
+      messages: result.log.map((error) => error.message)
+    };
+  } catch {
+    undoPollution();
+    return { tag: undefined, messages: [UNSAFE_TO_PARSE] };
+  }
+}
+function docCommentText(texts) {
+  const lines = texts.filter((text) => /^##?\|?"([ \t\r\n]|$)/.test(text)).map((text) => text.replace(/^##?\|?"[ \t\r\n]?/, "").trimEnd());
+  return lines.some((text) => text.trim().length > 0) ? lines.join(`
+`) : undefined;
+}
+function splitDocComment(texts) {
+  const text = docCommentText(texts);
+  if (text === undefined)
+    return {};
+  const lines = text.split(`
+`);
+  const titleLine = lines.findIndex((line) => line.trim().length > 0);
+  if (titleLine === -1)
+    return {};
+  const body = lines.slice(titleLine + 1).join(`
+`).replace(/^[ \t\r\n]+/, "").trimEnd();
+  return {
+    title: lines[titleLine].trim(),
+    body: body.length > 0 ? body : undefined
+  };
+}
+function docCommentTitleAndDescription(texts, explicitTitle) {
+  if (explicitTitle !== undefined) {
+    return { title: explicitTitle, description: docCommentText(texts) };
+  }
+  const { title, body } = splitDocComment(texts);
+  return { title, description: body };
+}
+function quoteFilterLiterals(annotation) {
+  const VALUE_START = /[=[,]/;
+  const BARE_FILTER_LITERAL = /^([ \t]*)f(['"])((?:\\.|(?!\2)[^\\])*)\2/;
+  let out = "";
+  let i = 0;
+  while (i < annotation.length) {
+    const char = annotation[i];
+    const delimited = endOfDelimited(annotation, i);
+    if (delimited > i) {
+      out += annotation.slice(i, delimited);
+      i = delimited;
+      continue;
+    }
+    if (VALUE_START.test(char)) {
+      const match = BARE_FILTER_LITERAL.exec(annotation.slice(i + 1));
+      if (match) {
+        const body = match[3].replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+        out += `${char}${match[1]}"f'${body}'"`;
+        i += 1 + match[0].length;
+        continue;
+      }
+    }
+    out += char;
+    i += 1;
+  }
+  return out;
+}
+function endOfDelimited(text, start) {
+  const char = text[start];
+  if (char === "`") {
+    let i = start + 1;
+    while (i < text.length) {
+      if (text[i] === "\\") {
+        i += 2;
+        continue;
+      }
+      if (text[i] === "`")
+        return i + 1;
+      if (text[i] === `
+`)
+        return text.length;
+      i += 1;
+    }
+    return text.length;
+  }
+  if (text.startsWith("<<<", start)) {
+    let lineStart = start + 3;
+    for (;; ) {
+      const newline = text.indexOf(`
+`, lineStart);
+      const lineEnd = newline === -1 ? text.length : newline;
+      if (text.slice(lineStart, lineEnd).trim() === ">>>")
+        return lineEnd;
+      if (newline === -1)
+        return text.length;
+      lineStart = newline + 1;
+    }
+  }
+  if (char === '"' || char === "'") {
+    const triple = char.repeat(3);
+    if (text.startsWith(triple, start)) {
+      let i2 = start + triple.length;
+      while (i2 < text.length) {
+        if (text[i2] === "\\") {
+          i2 += 2;
+          continue;
+        }
+        if (text.startsWith(triple, i2))
+          return i2 + triple.length;
+        i2 += 1;
+      }
+      return text.length;
+    }
+    let i = start + 1;
+    while (i < text.length) {
+      if (text[i] === "\\") {
+        i += 2;
+        continue;
+      }
+      if (text[i] === char)
+        return i + 1;
+      if (text[i] === `
+`)
+        return i;
+      i += 1;
+    }
+    return text.length;
+  }
+  return start;
+}
+function unwrapFilterLiteral(value) {
+  const match = /^f(['"])([\s\S]*)\1$/.exec(value);
+  return match ? match[2] : value;
+}
+function parseMotly(texts) {
+  const onRoute = texts.filter(onMotlyRoute);
+  const motly = onRoute.filter((text) => !hasEnvReference(text));
+  const envDropped = onRoute.length - motly.length;
+  const envErrors = envDropped > 0 ? [ENV_REFERENCE_DROPPED] : [];
+  if (motly.length === 0)
+    return { tag: undefined, errors: envErrors };
+  const direct = parseGuarded(motly);
+  if (direct.messages.length === 0)
+    return { tag: direct.tag, errors: envErrors };
+  const rescued = motly.map((text) => {
+    if (parseGuarded([text]).messages.length === 0)
+      return text;
+    const rewritten = quoteFilterLiterals(text);
+    return parseGuarded([rewritten]).messages.length === 0 ? rewritten : text;
+  });
+  const after = parseGuarded(rescued);
+  return { tag: after.tag, errors: [...envErrors, ...after.messages] };
+}
+function tagText(tag, ...path5) {
+  try {
+    return tag?.text(...path5);
+  } catch {
+    return;
+  }
+}
+function tagNumeric(tag, ...path5) {
+  try {
+    const raw = tagText(tag, ...path5);
+    if (raw === undefined)
+      return;
+    const DECIMAL = /^[-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][-+]?\d+)?$/;
+    const text = raw.trim();
+    if (!DECIMAL.test(text))
+      return;
+    const value = Number(text);
+    return Number.isFinite(value) ? value : undefined;
+  } catch {
+    return;
+  }
+}
+function motlyTag(texts) {
+  return parseMotly(texts).tag;
+}
+function motlyParseErrors(texts) {
+  return parseMotly(texts).errors;
+}
+function readAutorun(tag) {
+  return tagText(tag, "autorun") !== "false";
+}
+function scalarTypeOf(tag) {
+  try {
+    return tag?.scalarType();
+  } catch {
+    return;
+  }
+}
+function authoredDay(isoText) {
+  const value = new Date(isoText);
+  if (Number.isNaN(value.getTime()))
+    return isoText.slice(0, 10);
+  const atUtcMidnight = value.getUTCHours() === 0 && value.getUTCMinutes() === 0 && value.getUTCSeconds() === 0 && value.getUTCMilliseconds() === 0;
+  const year = atUtcMidnight ? value.getUTCFullYear() : value.getFullYear();
+  const month = atUtcMidnight ? value.getUTCMonth() : value.getMonth();
+  const day = atUtcMidnight ? value.getUTCDate() : value.getDate();
+  return `${year}-${String(month + 1).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+}
+function readStartingGivens(tag, declaredType) {
+  const entries = tag?.tag("givens");
+  if (!entries)
+    return;
+  const collected = {};
+  for (const [name, value] of entries.entries()) {
+    const tag2 = value;
+    const text = tagText(tag2);
+    if (text === undefined)
+      continue;
+    const declared = declaredType(name);
+    collected[name] = scalarTypeOf(tag2) === "date" && declared !== "timestamp" && declared !== "timestamptz" ? authoredDay(text) : declared?.startsWith("filter<") ? unwrapFilterLiteral(text) : text;
+  }
+  return Object.keys(collected).length > 0 ? collected : undefined;
+}
+var BUILT_IN_PROTO_GETTER, MAX_ANNOTATION_CHARS = 8192, ANNOTATION_TOO_LONG, ENV_REFERENCE_DROPPED = "annotation dropped for carrying an @env. reference", UNSAFE_TO_PARSE = "annotation could not be parsed safely";
+var init_motly = __esm(() => {
+  BUILT_IN_PROTO_GETTER = Object.getOwnPropertyDescriptor(Object.prototype, "__proto__")?.get;
+  ANNOTATION_TOO_LONG = `annotation exceeds ${MAX_ANNOTATION_CHARS} characters and was not parsed`;
+});
+
+// src/service/given.ts
+function presentText(tag, ...path5) {
+  const raw = tagText(tag, ...path5);
+  return raw !== undefined && raw.trim() !== "" ? raw : undefined;
+}
+function readGivenControlSpec(annotationTexts2) {
+  const spec = {};
+  const tag = motlyTag(annotationTexts2);
+  if (!tag)
+    return spec;
+  const label = presentText(tag, "label");
+  if (label !== undefined)
+    spec.label = label;
+  const description = presentText(tag, "description");
+  if (description !== undefined)
+    spec.description = description;
+  const control = tagText(tag, "control");
+  if (control === "select" || control === "multiselect") {
+    spec.control = control;
+  }
+  const rangeMin = tagNumeric(tag, "range_min");
+  if (rangeMin !== undefined)
+    spec.rangeMin = rangeMin;
+  const rangeMax = tagNumeric(tag, "range_max");
+  if (rangeMax !== undefined)
+    spec.rangeMax = rangeMax;
+  const suggest = tag.tag("suggest");
+  if (suggest) {
+    const parsed = {};
+    const query = presentText(suggest, "query");
+    if (query !== undefined)
+      parsed.query = query;
+    const source = presentText(suggest, "source");
+    if (source !== undefined)
+      parsed.source = source;
+    const dimension = presentText(suggest, "dimension");
+    if (dimension !== undefined)
+      parsed.dimension = dimension;
+    const runnable = parsed.query !== undefined || parsed.source !== undefined && parsed.dimension !== undefined;
+    if (runnable)
+      spec.suggest = parsed;
+  }
+  return spec;
+}
+function malloyGivenToApi(given) {
+  const type = given.type;
+  const renderedType = type.type === "filter expression" ? `filter<${type.filterType}>` : type.type;
+  const allNotes = given.annotations.forRoute(undefined);
+  return {
+    name: given.name,
+    type: renderedType,
+    annotations: allNotes.filter((note) => !isReservedRoute(note.route)).map((note) => note.text),
+    ...readGivenControlSpec(allNotes.map((note) => note.text)),
+    default: given._internal?.defaultText
+  };
+}
+var init_given = __esm(() => {
+  init_annotations();
+  init_motly();
+});
+
+// src/service/dashboard.ts
+import { isSourceDef } from "@malloydata/malloy";
+function filterPublisherOwnedRenderLogs(logs) {
+  return logs.filter((log) => {
+    const match = UNKNOWN_RENDER_TAG.exec(log.message ?? "");
+    if (!match)
+      return true;
+    return !PUBLISHER_OWNED_TAGS.includes(match[1].split(".")[0]);
+  });
+}
+function isDashboardModelPath(modelPath) {
+  if (!modelPath.endsWith(MODEL_FILE_SUFFIX2))
+    return false;
+  const segments = modelPath.split("/");
+  return segments.length === 2 && segments[0] === DASHBOARDS_DIR;
+}
+function dashboardSlug(modelPath) {
+  const basename = modelPath.slice(modelPath.lastIndexOf("/") + 1);
+  return basename.slice(0, -MODEL_FILE_SUFFIX2.length);
+}
+function matchesDocumentedDashboardName(slug) {
+  return /^[a-zA-Z0-9_-]+$/.test(slug);
+}
+function readArtifactTag(tag, declaredType) {
+  const artifact = tag.tag("artifact");
+  if (!artifact)
+    return;
+  const givens = readStartingGivens(artifact, declaredType);
+  const autorun = readAutorun(artifact);
+  return {
+    title: tagText(artifact, "title"),
+    tiles: artifact.array("tiles")?.map((tile) => tagText(tile)).filter((tile) => tile !== undefined),
+    dashboardColumns: positiveInteger(tagNumeric(artifact, "dashboard_columns")) ?? positiveInteger(tagNumeric(tag.tag("dashboard"), "columns")),
+    givens,
+    autorun
+  };
+}
+function positiveInteger(value) {
+  return value !== undefined && Number.isInteger(value) && value >= 1 ? value : undefined;
+}
+function normalizeTileExpression(tile) {
+  return tile.split("->").map((part) => part.trim().replace(/\s+/g, " ")).join(" -> ").replace(/\s+/g, " ");
+}
+function collectGivenRefs(value, into) {
+  if (Array.isArray(value)) {
+    for (const item of value)
+      collectGivenRefs(item, into);
+    return;
+  }
+  if (value === null || typeof value !== "object")
+    return;
+  const node = value;
+  if (node.node === "given" && typeof node.refName === "string") {
+    into.add(node.refName);
+  }
+  for (const child of Object.values(node))
+    collectGivenRefs(child, into);
+}
+function readDashboardModelFacts(modelPath, modelDef, surfacedGivenNames) {
+  const registry = modelDef.givens ?? {};
+  const surfaced = new Set(surfacedGivenNames);
+  const givens = new Map;
+  for (const given of Object.values(registry)) {
+    if (!surfaced.has(given.name))
+      continue;
+    const type = given.type;
+    const isFilter = type.type === "filter expression";
+    givens.set(given.name, {
+      name: given.name,
+      type: isFilter ? `filter<${type.filterType}>` : type.type,
+      default: given.defaultText,
+      annotations: (given.annotations?.blockNotes ?? []).concat(given.annotations?.notes ?? []).map((note) => note.text)
+    });
+  }
+  const isNamedQuery = (obj) => obj.type === "query";
+  const queries = Object.values(modelDef.contents).filter(isNamedQuery).map((query) => ({
+    name: query.as || query.name,
+    annotations: [
+      ...query.annotations?.blockNotes ?? [],
+      ...query.annotations?.notes ?? []
+    ].map((note) => note.text),
+    givens: (query.givenUsage ?? []).map((usage) => registry[usage.id]?.name).filter((name) => name !== undefined)
+  }));
+  const viewGivens = new Map;
+  const sourceFields = new Map;
+  const drills = [];
+  for (const obj of Object.values(modelDef.contents)) {
+    if (!isSourceDef(obj))
+      continue;
+    const sourceName = obj.as || obj.name;
+    const fieldNames = new Set;
+    sourceFields.set(sourceName, fieldNames);
+    const sourceGivens = new Set;
+    collectGivenRefs(obj.filterList, sourceGivens);
+    for (const field of obj.fields) {
+      const fieldName = field.as || field.name;
+      fieldNames.add(fieldName);
+      if (field.type === "turtle") {
+        const refs = new Set(sourceGivens);
+        collectGivenRefs(field.pipeline, refs);
+        viewGivens.set(normalizeTileExpression(`${sourceName} -> ${fieldName}`), Array.from(refs));
+        continue;
+      }
+      const drill = readDrillTag([
+        ...field.annotations?.blockNotes ?? [],
+        ...field.annotations?.notes ?? []
+      ].map((note) => note.text));
+      if (drill) {
+        drills.push({ ...drill, source: sourceName, dimension: fieldName });
+      }
+    }
+  }
+  return {
+    modelPath,
+    modelAnnotations: ownModelNotes(modelDef),
+    queries,
+    givens,
+    viewGivens,
+    sourceFields,
+    drills
+  };
+}
+function readDrillTag(annotations) {
+  const drill = motlyTag(annotations)?.tag("drill");
+  if (!drill)
+    return;
+  const to = tagTextArray(drill, "to") ?? [tagText(drill, "to")].filter(isString2);
+  const given = tagText(drill, "given");
+  return given === undefined ? { to } : { to, given };
+}
+function isString2(value) {
+  return value !== undefined;
+}
+function tagTextArray(tag, ...path5) {
+  const items = tag?.array(...path5);
+  return items?.map((item) => tagText(item)).filter(isString2);
+}
+function resolveTileGivens(tile, facts) {
+  return referencedTileGivens(tile, facts)?.filter((name) => facts.givens.has(name));
+}
+function referencedTileGivens(tile, facts) {
+  const normalized = normalizeTileExpression(tile);
+  return facts.viewGivens.get(normalized) ?? facts.queries.find((query) => query.name === normalized)?.givens;
+}
+function buildGivenSpecs(names, declarations) {
+  const specs = [];
+  for (const name of new Set(names)) {
+    const declaration = declarations.get(name);
+    if (!declaration)
+      continue;
+    specs.push(givenSpec(declaration));
+  }
+  return specs;
+}
+function givenSpec(declaration) {
+  return {
+    name: declaration.name,
+    type: declaration.type,
+    default: declaration.type.startsWith("filter<") && declaration.default !== undefined ? unwrapFilterLiteral(declaration.default) : declaration.default,
+    annotations: declaration.annotations.filter((text) => /^##?\(/.test(text)),
+    ...readGivenControlSpec(declaration.annotations)
+  };
+}
+function factsCarryArtifactTag(facts) {
+  if (motlyTag(facts.modelAnnotations)?.tag("artifact"))
+    return true;
+  return facts.queries.some((query) => Boolean(motlyTag(query.annotations)?.tag("artifact")));
+}
+function buildDashboardManifest(facts) {
+  const name = dashboardSlug(facts.modelPath);
+  const base = {
+    name,
+    entryFile: facts.modelPath
+  };
+  const modelTag = motlyTag(facts.modelAnnotations);
+  const declaredType = (name2) => facts.givens.get(name2)?.type;
+  const composite = modelTag ? readArtifactTag(modelTag, declaredType) : undefined;
+  if (composite?.tiles?.length) {
+    const tiles = composite.tiles.map((query) => {
+      const givenNames = resolveTileGivens(query, facts);
+      return givenNames ? { query, givenNames } : { query };
+    });
+    const doc = docCommentTitleAndDescription(facts.modelAnnotations, composite.title);
+    return {
+      ...base,
+      title: doc.title ?? name,
+      description: doc.description,
+      tiles,
+      dashboardColumns: composite.dashboardColumns,
+      startingGivens: composite.givens,
+      autorun: composite.autorun,
+      givens: buildGivenSpecs(tiles.some((tile) => tile.givenNames === undefined) ? Array.from(facts.givens.keys()) : tiles.flatMap((tile) => tile.givenNames ?? []), facts.givens)
+    };
+  }
+  for (const query of facts.queries) {
+    const tag = motlyTag(query.annotations);
+    const artifact = tag ? readArtifactTag(tag, declaredType) : undefined;
+    if (!artifact)
+      continue;
+    const doc = docCommentTitleAndDescription(query.annotations, artifact.title);
+    return {
+      ...base,
+      title: doc.title ?? name,
+      description: doc.description,
+      query: query.name,
+      dashboardColumns: artifact.dashboardColumns,
+      startingGivens: artifact.givens,
+      autorun: artifact.autorun,
+      givens: buildGivenSpecs(query.givens, facts.givens)
+    };
+  }
+  return;
+}
+function plainTileParts(tile) {
+  const piped = /^(\w+)\s*->\s*(\w+)$/.exec(tile.trim());
+  if (piped)
+    return { source: piped[1], view: piped[2] };
+  const bare = /^\w+$/.exec(tile.trim());
+  return bare ? { name: tile.trim() } : undefined;
+}
+function lintDashboard(facts, manifest) {
+  const findings = [];
+  const slug = manifest.name;
+  const add = (message, severity = "warn") => findings.push({ subject: slug, message, severity });
+  const ownAnnotations = manifest.tiles ? facts.modelAnnotations : facts.queries.find((query) => query.name === manifest.query)?.annotations ?? [];
+  const ownTag = motlyTag(ownAnnotations);
+  const artifactTag = ownTag?.tag("artifact");
+  const lintTargets = new Set([...facts.modelAnnotations, ...ownAnnotations]);
+  for (const message of new Set(motlyParseErrors([...lintTargets]))) {
+    add(`Annotation ${describeParseFailure(message)}, so that line had no ` + `effect on this dashboard.`);
+  }
+  for (const [tag, key, written] of [
+    [artifactTag, "dashboard_columns", "dashboard_columns"],
+    [ownTag?.tag("dashboard"), "columns", "# dashboard { columns=… }"]
+  ]) {
+    if (!tag?.has(key))
+      continue;
+    if (positiveInteger(tagNumeric(tag, key)) !== undefined)
+      continue;
+    const raw = tagText(tag, key);
+    add(`${written} must be a positive integer, got ` + `${raw === undefined ? "a value that could not be read" : JSON.stringify(raw)}. ` + (manifest.dashboardColumns === undefined ? `The grid falls back to the renderer default.` : `The grid uses ${manifest.dashboardColumns} instead.`));
+  }
+  for (const { query: tile } of manifest.tiles ?? []) {
+    const parts = plainTileParts(tile);
+    if (!parts)
+      continue;
+    const resolved = referencedTileGivens(tile, facts) !== undefined || "name" in parts && facts.queries.some((query) => query.name === parts.name);
+    if (!resolved) {
+      const detail = "source" in parts ? facts.sourceFields.has(parts.source) ? `source "${parts.source}" has no view "${parts.view}"` : `no source "${parts.source}" in this file` : `no query named "${parts.name}" in this file`;
+      add(`tile "${tile}" does not resolve: ${detail}.`, "error");
+    }
+    const unbindable = (referencedTileGivens(tile, facts) ?? []).filter((name) => !facts.givens.has(name));
+    for (const name of unbindable) {
+      add(`tile "${tile}" filters by given "${name}", which this file does ` + `not import, so no control is shown for it and it stays at its ` + `default. Add it to an import in ${facts.modelPath}.`);
+    }
+  }
+  if (manifest.query !== undefined) {
+    const query = facts.queries.find((q) => q.name === manifest.query);
+    for (const name of query?.givens ?? []) {
+      if (facts.givens.has(name))
+        continue;
+      add(`query "${manifest.query}" filters by given "${name}", which this ` + `file does not import, so no control is shown for it and it ` + `stays at its default. Add it to an import in ` + `${facts.modelPath}.`);
+    }
+  }
+  for (const name of Object.keys(manifest.startingGivens ?? {})) {
+    if (facts.givens.has(name))
+      continue;
+    add(`'artifact { givens { ${name}=… } }' sets a starting value for given ` + `"${name}", which this file does not import, so the value is ` + `dropped at query time and the dashboard opens at the ` + `declaration's default. Add it to an import in ${facts.modelPath}.`);
+  }
+  for (const spec of manifest.givens) {
+    const suggest = spec.suggest;
+    if (!suggest) {
+      const declared = motlyTag(facts.givens.get(spec.name)?.annotations ?? [])?.tag("suggest");
+      if (declared) {
+        const has = (key) => tagText(declared, key) !== undefined;
+        const missing = has("dimension") ? `it names a dimension but no query= or source= to read it from` : has("source") ? `source= alone names no column to read options from` : `it names neither a query= nor a source=`;
+        add(`given "${spec.name}" declares a suggest that cannot fetch ` + `options: ${missing}. Use query=, source= with dimension=, ` + `or query= with dimension=. No control options are offered ` + `for it.`, "error");
+      }
+      continue;
+    }
+    if (suggest.query !== undefined && !facts.queries.some((query) => query.name === suggest.query)) {
+      add(`given "${spec.name}" suggests options from query ` + `"${suggest.query}", which this file does not define.`, "error");
+    }
+    if (suggest.source !== undefined) {
+      const fields = facts.sourceFields.get(suggest.source);
+      if (!fields) {
+        add(`given "${spec.name}" suggests options from source ` + `"${suggest.source}", which this file does not define.`, "error");
+      } else if (suggest.dimension !== undefined && !fields.has(suggest.dimension)) {
+        add(`given "${spec.name}" suggests options from ` + `"${suggest.source} -> ${suggest.dimension}", but that ` + `source has no field "${suggest.dimension}".`, "error");
+      }
+    }
+  }
+  return findings;
+}
+function describeParseFailure(message) {
+  if (message === UNSAFE_TO_PARSE) {
+    return `was refused rather than parsed (${message}), which can be caused by something outside this file`;
+  }
+  if (message === ENV_REFERENCE_DROPPED) {
+    return `was dropped rather than parsed (${message}), so nothing on that line took effect`;
+  }
+  if (message === ANNOTATION_TOO_LONG) {
+    return `was refused rather than parsed (${message})`;
+  }
+  return `does not parse (${message})`;
+}
+function lintUndiscoveredDashboard(facts) {
+  const subject = dashboardSlug(facts.modelPath);
+  const messages = [
+    ...motlyParseErrors(facts.modelAnnotations),
+    ...facts.queries.flatMap((query) => motlyParseErrors(query.annotations))
+  ].map((message) => `Tag ${describeParseFailure(message)}, so the whole tag is discarded ` + `and this file is treated as a shared include rather than a dashboard.`);
+  const findings = Array.from(new Set(messages), (message) => ({
+    subject,
+    message,
+    severity: "error"
+  }));
+  if (findings.length > 0)
+    return findings;
+  const modelArtifact = motlyTag(facts.modelAnnotations)?.tag("artifact");
+  if (modelArtifact) {
+    const tiles = modelArtifact.array("tiles");
+    findings.push({
+      subject,
+      message: (tiles === undefined ? `Model-level '## artifact' declares no tiles=, ` : `Model-level '## artifact' declares an empty tiles=, `) + `so this file produces no dashboard. A composite dashboard needs ` + `tiles=["source -> view", …]; for a single-query dashboard put ` + `the '# artifact' tag on the query instead.`,
+      severity: "error"
+    });
+  }
+  return findings;
+}
+function lintGivenTags(facts) {
+  const findings = new Map;
+  for (const file of facts) {
+    for (const [name, declaration] of file.givens) {
+      for (const message of motlyParseErrors(declaration.annotations)) {
+        findings.set(`${name}|${message}`, {
+          subject: name,
+          message: `given "${name}" has an annotation that ` + `${describeParseFailure(message)}, so the whole line is ` + `discarded and the given ` + `loses any label, control, range or suggest it declared. ` + `It still accepts values; only its presentation is lost.`,
+          severity: "error"
+        });
+      }
+    }
+  }
+  return Array.from(findings.values());
+}
+function lintDrillTargets(facts, knownSlugs) {
+  const findings = new Map;
+  for (const file of facts) {
+    for (const drill of file.drills) {
+      const where = `${drill.source}.${drill.dimension}`;
+      if (drill.to.length === 0) {
+        findings.set(where, {
+          subject: where,
+          message: `# drill on ${where} names no destination (to=…).`,
+          severity: "error"
+        });
+        continue;
+      }
+      for (const destination of drill.to) {
+        if (destination === "self" || knownSlugs.has(destination))
+          continue;
+        findings.set(`${where}|${destination}`, {
+          subject: where,
+          message: `# drill on ${where} targets "${destination}", which is not ` + `a dashboard in this package.`,
+          severity: "error"
+        });
+      }
+    }
+  }
+  return Array.from(findings.values());
+}
+function drillGivenName(drill) {
+  return drill.given ?? drill.dimension;
+}
+function lintSelfDrills(facts) {
+  const surfaced = new Set;
+  for (const file of facts) {
+    for (const name of file.givens.keys())
+      surfaced.add(name.toLowerCase());
+  }
+  const findings = new Map;
+  for (const file of facts) {
+    for (const drill of file.drills) {
+      if (!drill.to.includes("self"))
+        continue;
+      const given = drillGivenName(drill);
+      if (surfaced.has(given.toLowerCase()))
+        continue;
+      const where = `${drill.source}.${drill.dimension}`;
+      findings.set(where, {
+        subject: where,
+        message: `# drill on ${where} has to=self, but no model in this ` + `package declares a given "${given}" for the clicked value to ` + `filter on, so the drill cannot fire anywhere. Declare it, or ` + `point the tag at a given that exists with given=.`,
+        severity: "error"
+      });
+    }
+  }
+  return Array.from(findings.values());
+}
+var DASHBOARDS_DIR = "dashboards", COMPONENT_FILE_SUFFIXES, MODEL_FILE_SUFFIX2 = ".malloy", PUBLISHER_OWNED_TAGS, UNKNOWN_RENDER_TAG;
+var init_dashboard = __esm(() => {
+  init_annotations();
+  init_given();
+  init_motly();
+  COMPONENT_FILE_SUFFIXES = [".jsx", ".tsx"];
+  PUBLISHER_OWNED_TAGS = ["artifact", "drill"];
+  UNKNOWN_RENDER_TAG = /^Unknown render tag '([^']+)'/;
+});
+
 // ../../node_modules/pump/index.js
 var require_pump = __commonJS((exports, module) => {
   var once = require_once2();
@@ -248056,79 +248897,6 @@ function filterFreshManifest(entries, now) {
   return { manifest, nextStaleSince };
 }
 
-// src/service/annotations.ts
-import { Annotations } from "@malloydata/malloy";
-function isReservedRoute(route) {
-  return route === "" || !/[\p{L}\p{N}]/u.test(route);
-}
-function ownModelAnnotations(modelDef) {
-  return foldModelAnnotations(modelDef, (id) => id === modelDef.modelID || id.startsWith("internal://"));
-}
-function modelAnnotations(modelDef) {
-  return foldModelAnnotations(modelDef, () => true);
-}
-function foldModelAnnotations(modelDef, admits) {
-  const registry = modelDef.modelAnnotations ?? {};
-  const visited = new Set;
-  const order = [];
-  const visit = (id) => {
-    if (!admits(id))
-      return;
-    if (visited.has(id))
-      return;
-    visited.add(id);
-    const entry = registry[id];
-    if (!entry)
-      return;
-    for (const dep of entry.inheritsFrom)
-      visit(dep);
-    order.push(id);
-  };
-  visit(modelDef.modelID);
-  let folded;
-  for (const id of order) {
-    const own = registry[id].ownNotes;
-    if (!own.notes?.length && !own.blockNotes?.length)
-      continue;
-    folded = {
-      notes: own.notes,
-      blockNotes: own.blockNotes,
-      inherits: folded
-    };
-  }
-  return folded ?? {};
-}
-function ownModelNotes(modelDef) {
-  const registry = modelDef.modelAnnotations ?? {};
-  const isSameDocument = (id) => id === modelDef.modelID || id.startsWith("internal://");
-  const seen = new Set;
-  const texts = [];
-  const visit = (id) => {
-    if (seen.has(id) || !isSameDocument(id))
-      return;
-    seen.add(id);
-    const entry = registry[id];
-    if (!entry)
-      return;
-    for (const dep of entry.inheritsFrom)
-      visit(dep);
-    texts.push(...ownLevelNoteTexts(entry.ownNotes));
-  };
-  visit(modelDef.modelID);
-  return texts;
-}
-function annotationTexts(annote) {
-  const texts = new Annotations(annote).texts();
-  return texts.length > 0 ? texts : undefined;
-}
-function ownLevelNoteTexts(annote) {
-  return ownLevelNotes(annote).map((note) => note.text);
-}
-function ownLevelNotes(annote) {
-  return [...annote?.blockNotes ?? [], ...annote?.notes ?? []];
-}
-var init_annotations = () => {};
-
 // src/service/incremental_declaration.ts
 function safeTag(source) {
   try {
@@ -248485,6 +249253,19 @@ function readPreaggregateAnnotation(measure) {
       continue;
     declared = true;
     const grainText = tag.text("preaggregate", "grain") ?? tag.text("grain");
+    const namespaceText = tag.text("preaggregate", "namespace") ?? tag.text("namespace");
+    let namespace;
+    if (namespaceText !== undefined) {
+      const candidate = namespaceText.trim();
+      if (!isSpliceableNamespace(candidate)) {
+        errors2.push({
+          kind: "invalid_namespace",
+          message: `Measure \`${name}\` declares \`#@ preaggregate namespace="${candidate}"\`, which is not a plain namespace. Use letters, digits, underscore, dollar or hyphen per part, dot-separated for a qualified one (\`analytics\`, \`my-project.analytics\`) — the rollup's own table name is generated and appended, so a namespace needing quotes cannot be joined to it.`
+        });
+        continue;
+      }
+      namespace = candidate;
+    }
     if (grainText === undefined) {
       errors2.push({
         kind: "missing_grain",
@@ -248500,7 +249281,11 @@ function readPreaggregateAnnotation(measure) {
       });
       continue;
     }
-    grains.set(dimensions.join("\x00"), { dimensions, text: grainText });
+    grains.set(dimensions.join("\x00"), {
+      dimensions,
+      text: grainText,
+      namespace
+    });
   }
   return {
     declared,
@@ -248511,6 +249296,7 @@ function readPreaggregateAnnotation(measure) {
 }
 var NEGATION;
 var init_preaggregation_annotation = __esm(() => {
+  init_preaggregation_synthesis();
   NEGATION = /#@\s*-\s*preaggregate\b/;
 });
 
@@ -248524,7 +249310,7 @@ function walk(node, found) {
       found.aggregates.push({ function: node.function });
       break;
     case "filteredExpr":
-      found.filtered = true;
+      found.filtered += 1;
       break;
     case "all":
     case "exclude":
@@ -248577,7 +249363,7 @@ function classifyMeasureAdditivity(measure) {
   }
   const found = {
     aggregates: [],
-    filtered: false,
+    filtered: 0,
     ungrouped: false,
     analytic: false
   };
@@ -248588,8 +249374,13 @@ function classifyMeasureAdditivity(measure) {
   if (found.analytic) {
     return nonAdditive("analytic", `Measure \`${name}\` contains a window function, which is computed across result rows rather than within a group, so it cannot be pre-aggregated. Remove \`#@ preaggregate\` from it.`);
   }
-  if (found.filtered) {
-    return nonAdditive("filtered_aggregate", `Measure \`${name}\` applies a filter to its aggregate, which this version cannot pre-aggregate. Define the aggregate as its own measure and apply the filter in a view, or remove \`#@ preaggregate\` from it.`);
+  let aggregateRoot = measure.e;
+  if (found.filtered > 0) {
+    const root = measure.e;
+    if (found.filtered !== 1 || root.node !== "filteredExpr" || root.kids.e.node !== "aggregate" || !root.kids.filterList.every((c) => c.expressionType === "scalar")) {
+      return nonAdditive("filtered_aggregate", `Measure \`${name}\` applies a filter this version cannot pre-aggregate: a filter is supported only when written directly on the measure's single aggregate, as \`amount.sum() { where: … }\` (several conditions go in ONE \`where:\`, comma-separated, not chained). If the filter sits under a wrapper or refines a derived measure, pre-aggregate the bare filtered aggregate as its own measure and do the rest in a view, or remove \`#@ preaggregate\` from it.`);
+    }
+    aggregateRoot = root.kids.e;
   }
   if (found.aggregates.length === 0) {
     return nonAdditive("no_aggregate_found", `Measure \`${name}\` does not compute a single plain aggregate, and only \`sum\`, \`count\`, \`min\` and \`max\` can be re-aggregated from a stored partial. If it is derived from other measures, pre-aggregate those instead and compute this one in a view.`);
@@ -248597,10 +249388,10 @@ function classifyMeasureAdditivity(measure) {
   if (found.aggregates.length > 1) {
     return nonAdditive("multiple_aggregates", `Measure \`${name}\` combines ${found.aggregates.length} aggregates, and a ratio or difference of aggregates cannot be re-aggregated from a single stored column. Pre-aggregate each aggregate as its own measure and combine them in a view.`);
   }
-  if (measure.e.node !== "aggregate") {
+  if (aggregateRoot.node !== "aggregate") {
     return nonAdditive("aggregate_not_at_root", `Measure \`${name}\` wraps its aggregate in a further expression, so re-aggregating a stored partial would not reproduce it. Pre-aggregate the bare aggregate as its own measure and do the rest in a view.`);
   }
-  const fn = measure.e.function;
+  const fn = aggregateRoot.function;
   if (!isAdditiveAggregate(fn)) {
     const hint = fn === "avg" ? " Pre-aggregate a `sum` and a `count` instead, and divide them in a view." : fn === "distinct" ? " A distinct count cannot be merged from per-group partials." : "";
     return nonAdditive("unsupported_aggregate", `Measure \`${name}\` uses \`${fn}\`, which cannot be re-aggregated from a stored partial; only \`sum\`, \`count\`, \`min\` and \`max\` can.${hint}`);
@@ -248618,6 +249409,7 @@ var init_preaggregation_classifier = __esm(() => {
 });
 
 // src/service/preaggregation_synthesis.ts
+import { Annotations as Annotations3 } from "@malloydata/malloy";
 import { createHash as createHash2 } from "node:crypto";
 function grainDigest(grainDimensions) {
   return createHash2("sha256").update(grainDimensions.join("\x00")).digest("hex").slice(0, 8);
@@ -248626,10 +249418,40 @@ function rollupSourceName(baseSourceName, grainDimensions) {
   const slug = grainDimensions.join("_").slice(0, NAME_SLUG_LIMIT);
   return `${baseSourceName}__preagg__${slug}__${grainDigest(grainDimensions)}`;
 }
+function isSpliceableNamespace(namespace) {
+  return namespace.split(".").every((s) => NAMESPACE_SEGMENT.test(s));
+}
 function baseAlias(baseSourceName) {
   return `${baseSourceName}${BASE_ALIAS_SUFFIX}`;
 }
+function persistNamespace(persistName) {
+  if (!persistName)
+    return;
+  const lastDot = persistName.lastIndexOf(".");
+  if (lastDot <= 0)
+    return;
+  if (persistName.slice(lastDot + 1).trim() === "")
+    return;
+  const candidate = persistName.slice(0, lastDot);
+  return isSpliceableNamespace(candidate) ? candidate : undefined;
+}
+function basePersistNamespace(source) {
+  if (!source.annotations)
+    return;
+  try {
+    const tag = new Annotations3(source.annotations).parseAsTag("@").tag;
+    if (!tag.has("persist"))
+      return;
+    const storage = tag.text("persist", "storage") ?? tag.text("storage");
+    if (storage !== undefined && storage.trim() !== "")
+      return;
+    return persistNamespace(tag.text("persist", "name") ?? tag.text("name"));
+  } catch {
+    return;
+  }
+}
 function planSourcePreaggregation(baseSourceName, source) {
+  const inheritedNamespace = basePersistNamespace(source);
   const byGrain = new Map;
   for (const field of source.fields ?? []) {
     const declaration = readPreaggregateAnnotation(field);
@@ -248650,12 +249472,14 @@ function planSourcePreaggregation(baseSourceName, source) {
         partialName: `${name}${PARTIAL_SUFFIX}`,
         reaggregate: additivity.reaggregate
       });
+      entry.namespace ??= grain.namespace;
       byGrain.set(key, entry);
     }
   }
-  return [...byGrain.values()].map(({ grainDimensions, measures }) => ({
+  return [...byGrain.values()].map(({ grainDimensions, measures, namespace }) => ({
     baseSourceName,
     rollupSourceName: rollupSourceName(baseSourceName, grainDimensions),
+    namespace: namespace ?? inheritedNamespace,
     grainDimensions,
     measures: [...measures].sort((a, b) => a.name.localeCompare(b.name))
   })).sort((a, b) => a.rollupSourceName.localeCompare(b.rollupSourceName));
@@ -248673,7 +249497,8 @@ function emitRollup(plan) {
 `);
   const merged = plan.measures.map((m) => `    ${m.name} is ${m.partialName}.${m.reaggregate}()`).join(`
 `);
-  return `#@ persist
+  const persist = plan.namespace ? `#@ persist name="${plan.namespace}.${plan.rollupSourceName}"` : "#@ persist";
+  return `${persist}
 source: ${plan.rollupSourceName} is ${alias} -> {
   group_by:
 ${plan.grainDimensions.map((d) => `    ${d}`).join(`
@@ -248706,10 +249531,11 @@ ${plans.map(emitRollup).join(`
 ${composites}
 `;
 }
-var BASE_ALIAS_SUFFIX = "__preagg_base", PARTIAL_SUFFIX = "__partial", NAME_SLUG_LIMIT = 40;
+var BASE_ALIAS_SUFFIX = "__preagg_base", PARTIAL_SUFFIX = "__partial", NAME_SLUG_LIMIT = 40, NAMESPACE_SEGMENT;
 var init_preaggregation_synthesis = __esm(() => {
   init_preaggregation_annotation();
   init_preaggregation_classifier();
+  NAMESPACE_SEGMENT = /^[A-Za-z_][A-Za-z0-9_$-]*$/;
 });
 
 // src/service/preaggregation_compile.ts
@@ -248758,7 +249584,7 @@ var init_preaggregation_compile = __esm(() => {
 });
 
 // src/service/build_plan.ts
-import { Annotations as Annotations3 } from "@malloydata/malloy";
+import { Annotations as Annotations4 } from "@malloydata/malloy";
 function deriveColumns(persistSource) {
   try {
     return persistSource._explore.intrinsicFields.filter((f) => f.isAtomicField()).map((f) => ({
@@ -248957,7 +249783,7 @@ function detectDroppedPersistSources(malloyModel, recognizedNames) {
         continue;
       let isPersist = false;
       try {
-        isPersist = new Annotations3(def.annotations).parseAsTag("@").tag.has("persist");
+        isPersist = new Annotations4(def.annotations).parseAsTag("@").tag.has("persist");
       } catch {
         continue;
       }
@@ -249335,21 +250161,6 @@ var init_filter = __esm(() => {
   };
 });
 
-// src/service/given.ts
-function malloyGivenToApi(given) {
-  const type = given.type;
-  const renderedType = type.type === "filter expression" ? `filter<${type.filterType}>` : type.type;
-  return {
-    name: given.name,
-    type: renderedType,
-    annotations: given.annotations.forRoute(undefined).filter((note) => !isReservedRoute(note.route)).map((note) => note.text),
-    default: given._internal?.defaultText
-  };
-}
-var init_given = __esm(() => {
-  init_annotations();
-});
-
 // src/service/model_limits.ts
 function resolveModelQueryRowLimit(userLimit, { defaultLimit, maxRows }) {
   const requested = userLimit && userLimit > 0 ? userLimit : defaultLimit;
@@ -249497,6 +250308,8 @@ function validateSourcePreaggregation(sourceName, source) {
     });
   }
   const declaredFields = [];
+  const namespacesByGrain = new Map;
+  const grainTextByKey = new Map;
   for (const field of fields) {
     const name = fieldName(field);
     const declaration = readPreaggregateAnnotation(field);
@@ -249556,8 +250369,26 @@ function validateSourcePreaggregation(sourceName, source) {
         if (violation)
           violations.push(violation);
       }
+      if (grain.namespace !== undefined && additivity.additive) {
+        const key = grain.dimensions.join("\x00");
+        const named = namespacesByGrain.get(key) ?? new Map;
+        if (!named.has(grain.namespace))
+          named.set(grain.namespace, name);
+        namespacesByGrain.set(key, named);
+        grainTextByKey.set(key, grain.text);
+      }
     }
   }
+  for (const [key, named] of namespacesByGrain) {
+    if (named.size < 2)
+      continue;
+    const choices = [...named.entries()].map(([ns, measure]) => `\`${ns}\` (on \`${measure}\`)`).join(", ");
+    violations.push({
+      code: "conflicting_namespace",
+      sourceName,
+      message: `Measures on \`${sourceName}\` declare \`#@ preaggregate\` at the grain \`${grainTextByKey.get(key)}\` with different namespaces: ${choices}. One grain is one rollup table, so it can only be created in one of them. Give every measure at this grain the same \`namespace=\`, or move one to a different grain.`
+    });
+  }
   const fanout = declaredFields.length > 0 ? fields.filter(isFanoutJoin) : [];
   if (fanout.length > 0) {
     const joins = fanout.map((f) => `\`${fieldName(f)}\``).join(", ");
@@ -249586,7 +250417,7 @@ var init_preaggregation_validation = __esm(() => {
 });
 
 // src/service/gate_registry_walk.ts
-import { isSourceDef } from "@malloydata/malloy";
+import { isSourceDef as isSourceDef2 } from "@malloydata/malloy";
 function resolveDeclaredSource(struct, modelDef) {
   if (!modelDef)
     return { kind: "none" };
@@ -249598,7 +250429,7 @@ function resolveDeclaredSource(struct, modelDef) {
     const declared = entry.type === "source_registry_reference" ? modelDef.contents[entry.name] : entry;
     if (declared === struct)
       continue;
-    if (!declared || !isSourceDef(declared)) {
+    if (!declared || !isSourceDef2(declared)) {
       sawBrokenEntry = true;
       continue;
     }
@@ -249633,7 +250464,7 @@ function resolveQuerySourceBase(struct, modelDef) {
     return;
   const ref = duck.query?.structRef;
   const base = typeof ref === "string" ? modelDef?.contents[ref] : ref;
-  return base && isSourceDef(base) ? base : undefined;
+  return base && isSourceDef2(base) ? base : undefined;
 }
 function resolveCompositeResolvedBase(struct) {
   const duck = struct;
@@ -249693,7 +250524,7 @@ var init_gate_registry_walk = __esm(() => {
 // src/service/source_extraction.ts
 import {
   isJoined as isJoined2,
-  isSourceDef as isSourceDef2
+  isSourceDef as isSourceDef3
 } from "@malloydata/malloy";
 function joinFieldNamesUnresolvableDeclaration(field, modelDef) {
   const ids = [field.referenceID, field.sourceID].filter((id) => !!id);
@@ -249704,7 +250535,7 @@ function joinFieldNamesUnresolvableDeclaration(field, modelDef) {
     if (!entry)
       continue;
     const declared = entry.type === "source_registry_reference" ? modelDef.contents[entry.name] : entry;
-    if (declared && isSourceDef2(declared))
+    if (declared && isSourceDef3(declared))
       return false;
   }
   return true;
@@ -249717,7 +250548,7 @@ function extractSourcesFromModelDef(modelDef, givens, onParseError) {
   const nearMissAuthorize = [];
   const sweptStructs = [];
   for (const obj of Object.values(modelDef.contents)) {
-    if (!isSourceDef2(obj))
+    if (!isSourceDef3(obj))
       continue;
     const struct = obj;
     sweptStructs.push(obj);
@@ -249735,7 +250566,7 @@ function extractSourcesFromModelDef(modelDef, givens, onParseError) {
     const entry = value.entry;
     if (entry.type === "source_registry_reference")
       continue;
-    if (!isSourceDef2(entry))
+    if (!isSourceDef3(entry))
       continue;
     sweptStructs.push(entry);
     for (const note of ownLevelNotes(entry.annotations)) {
@@ -249760,7 +250591,7 @@ function extractSourcesFromModelDef(modelDef, givens, onParseError) {
   if (containsAuthorizeAnnotationTag((modelAnnotations(modelDef).notes ?? []).map((note) => note.text))) {
     misplacedAuthorize.push({ kind: "file" });
   }
-  const sources = Object.values(modelDef.contents).filter((obj) => isSourceDef2(obj)).map((sourceObj) => {
+  const sources = Object.values(modelDef.contents).filter((obj) => isSourceDef3(obj)).map((sourceObj) => {
     const struct = sourceObj;
     const sourceName = struct.as || struct.name;
     const annotations = annotationTexts(struct.annotations);
@@ -249818,7 +250649,7 @@ function extractSourcesFromModelDef(modelDef, givens, onParseError) {
         continue;
       }
       const fieldName2 = field.as || field.name;
-      if (isJoined2(field) && isSourceDef2(field)) {
+      if (isJoined2(field) && isSourceDef3(field)) {
         const joinedStruct = field;
         if (joinFieldNamesUnresolvableDeclaration(joinedStruct, modelDef)) {
           continue;
@@ -249879,10 +250710,10 @@ import {
   API,
   FixedConnectionMap,
   InMemoryURLReader as InMemoryURLReader2,
-  isSourceDef as isSourceDef3,
+  isSourceDef as isSourceDef4,
   MalloyConfig as MalloyConfig2,
   MalloyError as MalloyError2,
-  Annotations as Annotations4,
+  Annotations as Annotations5,
   modelDefToModelInfo,
   Runtime as Runtime2
 } from "@malloydata/malloy";
@@ -249970,8 +250801,10 @@ var init_model = __esm(() => {
   init_annotations();
   init_build_plan();
   init_authorize();
+  init_dashboard();
   init_filter();
   init_given();
+  init_motly();
   init_model_limits();
   init_json_utils();
   init_query_metadata();
@@ -250158,7 +250991,7 @@ var init_model = __esm(() => {
       if (!modelDef)
         return byName;
       for (const entry of Object.values(modelDef.contents)) {
-        if (!isSourceDef3(entry))
+        if (!isSourceDef4(entry))
           continue;
         const name = entry.as ?? entry.name;
         byName.set(name, this.collectEntryPointGates(entry, modelDef, new Set, true));
@@ -250179,14 +251012,14 @@ var init_model = __esm(() => {
         try {
           const structs = [];
           for (const obj of Object.values(modelDef.contents)) {
-            if (isSourceDef3(obj))
+            if (isSourceDef4(obj))
               structs.push(obj);
           }
           for (const value of Object.values(modelDef.sourceRegistry ?? {})) {
             const entry = value.entry;
             if (entry.type === "source_registry_reference")
               continue;
-            if (isSourceDef3(entry))
+            if (isSourceDef4(entry))
               structs.push(entry);
           }
           structs.push(...derivedStructsReachable(structs, modelDef));
@@ -250518,7 +251351,7 @@ var init_model = __esm(() => {
       }
       if (struct.sourceID) {
         for (const [key, value] of Object.entries(modelDef.contents)) {
-          if (isSourceDef3(value) && value.sourceID === struct.sourceID) {
+          if (isSourceDef4(value) && value.sourceID === struct.sourceID) {
             return key;
           }
         }
@@ -250533,7 +251366,7 @@ var init_model = __esm(() => {
       if (ownNotes.length === 0)
         return;
       for (const value of Object.values(modelDef.contents)) {
-        if (!isSourceDef3(value) || value === struct || exclude.has(value)) {
+        if (!isSourceDef4(value) || value === struct || exclude.has(value)) {
           continue;
         }
         const candidateNotes = [
@@ -250576,7 +251409,7 @@ var init_model = __esm(() => {
       const copy = structuredClone(modelDef);
       for (const { graftTarget, condition } of grafts) {
         const target = copy.contents[graftTarget];
-        if (!target || !isSourceDef3(target)) {
+        if (!target || !isSourceDef4(target)) {
           throw new Error(`graft target "${graftTarget}" is not a source in this model`);
         }
         target.filterList = [...target.filterList ?? [], condition];
@@ -250605,7 +251438,7 @@ var init_model = __esm(() => {
       if (duck.type === "query_source" && modelDef) {
         const ref = duck.query?.structRef;
         const base = typeof ref === "string" ? modelDef.contents[ref] : ref;
-        if (base && isSourceDef3(base)) {
+        if (base && isSourceDef4(base)) {
           return this.filterListContainsCode(base, modelDef, code, depth + 1);
         }
       }
@@ -250820,6 +251653,11 @@ var init_model = __esm(() => {
     getQueries() {
       return this.curateForDiscovery(this.queries);
     }
+    getDashboardModelFacts() {
+      if (!this.modelDef)
+        return;
+      return readDashboardModelFacts(this.modelPath, this.modelDef, (this.givens ?? []).map((given) => given.name).filter((name) => name !== undefined));
+    }
     hasEmptyDiscoverySurface() {
       if (!this.discoveryCurationEnabled)
         return false;
@@ -251005,9 +251843,37 @@ var init_model = __esm(() => {
         throw new ModelNotFoundError(`${this.modelPath} is not a valid model name.  Model files must end in .malloy.`);
       }
     }
-    getNotebookError() {
+    getCompilationError() {
       return this.compilationError;
     }
+    getNotebookError() {
+      return this.getCompilationError();
+    }
+    getNotebookListing() {
+      if (this.modelType !== "notebook")
+        return {};
+      const annotations = this.modelDef ? ownModelNotes(this.modelDef) : [];
+      const doc = docCommentTitleAndDescription(annotations, tagText(motlyTag(annotations), "title"));
+      return {
+        title: doc.title ?? this.firstMarkdownHeading(),
+        description: doc.description
+      };
+    }
+    firstMarkdownHeading() {
+      for (const cell of this.runnableNotebookCells ?? []) {
+        if (cell.type !== "markdown")
+          continue;
+        for (const line of cell.text.split(`
+`)) {
+          const trimmed2 = line.trim();
+          if (trimmed2.length === 0)
+            continue;
+          const heading = /^#{1,6}\s+(.+)$/.exec(trimmed2);
+          return heading ? heading[1] : undefined;
+        }
+      }
+      return;
+    }
     async getNotebook() {
       if (this.compilationError) {
         throw this.compilationError;
@@ -251466,7 +252332,7 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
       if (!this.modelDef)
         return;
       try {
-        return new Annotations4(ownModelAnnotations(this.modelDef)).parseAsTag().tag;
+        return new Annotations5(ownModelAnnotations(this.modelDef)).parseAsTag().tag;
       } catch {
         return;
       }
@@ -251476,12 +252342,12 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
         return;
       try {
         const entry = this.modelDef.contents?.[sourceName];
-        if (!entry || !isSourceDef3(entry))
+        if (!entry || !isSourceDef4(entry))
           return;
         const def = entry;
         if (!def.annotations)
           return;
-        return new Annotations4(def.annotations).parseAsTag("@").tag;
+        return new Annotations5(def.annotations).parseAsTag("@").tag;
       } catch {
         return;
       }
@@ -251514,6 +252380,7 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
         };
       });
       const allAnnotations = this.modelDef ? ownModelNotes(this.modelDef) : [];
+      const notebookTag = motlyTag(allAnnotations);
       const notebook = {
         type: "notebook",
         packageName: this.packageName,
@@ -251523,6 +252390,8 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
         sources: this.modelDef && this.sources,
         queries: this.modelDef && this.queries,
         annotations: allAnnotations,
+        autorun: readAutorun(notebookTag),
+        startingGivens: readStartingGivens(notebookTag, (name) => (this.givens ?? []).find((g) => g.name === name)?.type),
         notebookCells
       };
       return notebook;
@@ -253933,7 +254802,7 @@ var require_luxon = __commonJS((exports) => {
       return defaultZone2;
     } else if (input instanceof Zone) {
       return input;
-    } else if (isString2(input)) {
+    } else if (isString3(input)) {
       const lowered = input.toLowerCase();
       if (lowered === "default")
         return defaultZone2;
@@ -254308,7 +255177,7 @@ var require_luxon = __commonJS((exports) => {
   function isInteger(o) {
     return typeof o === "number" && o % 1 === 0;
   }
-  function isString2(o) {
+  function isString3(o) {
     return typeof o === "string";
   }
   function isDate2(o) {
@@ -274205,6 +275074,30 @@ class ConnectionController {
   }
 }
 
+// src/controller/dashboard.controller.ts
+init_errors();
+
+class DashboardController {
+  environmentStore;
+  constructor(environmentStore) {
+    this.environmentStore = environmentStore;
+  }
+  async listDashboards(environmentName, packageName) {
+    const environment = await this.environmentStore.getEnvironment(environmentName, false);
+    const p = await environment.getPackage(packageName, false);
+    return p.listDashboards();
+  }
+  async getDashboard(environmentName, packageName, dashboardName) {
+    const environment = await this.environmentStore.getEnvironment(environmentName, false);
+    const p = await environment.getPackage(packageName, false);
+    const dashboard = p.getDashboard(dashboardName);
+    if (!dashboard) {
+      throw new DashboardNotFoundError(`Dashboard ${dashboardName} does not exist in package ${packageName}`);
+    }
+    return dashboard;
+  }
+}
+
 // src/controller/database.controller.ts
 class DatabaseController {
   environmentStore;
@@ -274421,6 +275314,8 @@ init_errors();
 init_logger();
 init_query_metadata();
 var import_render_validator = __toESM(require_dist11(), 1);
+init_dashboard();
+
 class QueryController {
   environmentStore;
   constructor(environmentStore) {
@@ -274471,7 +275366,7 @@ class QueryController {
           }
         }
       }, compactJson ? "compact" : "full", bypassAuthorize), getQueryTimeoutMs());
-      const renderLogs = import_render_validator.validateRenderTags(result);
+      const renderLogs = filterPublisherOwnedRenderLogs(import_render_validator.validateRenderTags(result));
       return {
         result: serializedResult,
         resource: `${API_PREFIX}/environments/${environmentName}/packages/${packageName}/models/${modelPath}/query`,
@@ -283132,6 +284027,7 @@ class CronEvaluator {
 }
 
 // src/service/package.ts
+init_dashboard();
 init_quoting();
 init_model();
 
@@ -283199,6 +284095,8 @@ class Package {
   sourceEligibility = undefined;
   incrementalPolicySources = [];
   renderTagWarnings = [];
+  dashboardWarnings = [];
+  dashboards = new Map;
   manifestWarnings = [];
   static meter = publisherMeter();
   static packageLoadHistogram = this.meter.createHistogram("malloy_package_load_duration", {
@@ -283405,6 +284303,7 @@ class Package {
     });
     const pkg = new Package(environmentName, packageName, packagePath, packageConfig, databases, models, malloyConfig);
     pkg.renderTagWarnings = renderTagWarnings;
+    await pkg.discoverDashboards();
     pkg.manifestWarnings = outcome.packageMetadata.manifestWarnings ?? [];
     pkg.wireFreshnessResolvers();
     try {
@@ -283543,6 +284442,7 @@ class Package {
     }
     const allWarnings = [
       ...this.renderTagWarnings,
+      ...this.dashboardWarnings,
       ...this.storageWarnings(),
       ...this.droppedPersistWarnings(),
       ...this.emptyDiscoveryWarnings(),
@@ -283954,6 +284854,7 @@ class Package {
     this.packageMetadata.manifestLocation = outcome.packageMetadata.manifestLocation ?? null;
     this.applyDiscoveryPolicyToModels();
     this.applyQueryBoundaryToModels();
+    await this.discoverDashboards();
     this.recordManifestBinding(entries);
     this.wireFreshnessResolvers();
     const invalidMsg = this.formatInvalidExplores();
@@ -283994,15 +284895,271 @@ class Package {
     }));
     return values;
   }
+  isQueryableEntryPoint(modelPath) {
+    if (!this.queryBoundaryActive())
+      return true;
+    const exploreSet = this.exploreSet();
+    return exploreSet ? exploreSet.has(modelPath) : true;
+  }
+  servableEntryPoints() {
+    if (!this.queryBoundaryActive())
+      return () => true;
+    const exploreSet = this.exploreSet();
+    return (modelPath) => exploreSet ? exploreSet.has(modelPath) : true;
+  }
+  queryBoundaryActive() {
+    if (this.packageMetadata.queryableSources === "all")
+      return false;
+    return this.exploresDeclared();
+  }
+  async claimsToBeADashboard(modelPath) {
+    try {
+      const source = await fs7.readFile(safeJoinUnderRoot(this.packagePath, modelPath), "utf8");
+      return /^[ \t]*##?[ \t]*artifact\b/m.test(source);
+    } catch {
+      return false;
+    }
+  }
+  async discoverDashboards() {
+    const discovered = new Map;
+    const factsByPath = new Map;
+    const allFacts = new Map;
+    const heldBack = [];
+    const unconventionalSlugs = [];
+    const droppedByError = [];
+    const dashboardSlugs = new Set;
+    for (const modelPath of Array.from(this.models.keys()).sort()) {
+      const model = this.models.get(modelPath);
+      if (!model)
+        continue;
+      let facts;
+      try {
+        facts = model.getDashboardModelFacts();
+        if (facts)
+          allFacts.set(modelPath, facts);
+      } catch (err) {
+        logger.warn("Reading a model's dashboard facts failed", {
+          packageName: this.packageName,
+          modelPath,
+          error: errMessage(err)
+        });
+      }
+      if (!isDashboardModelPath(modelPath))
+        continue;
+      const name = dashboardSlug(modelPath);
+      let manifest;
+      if (facts) {
+        try {
+          manifest = buildDashboardManifest(facts);
+        } catch (err) {
+          logger.warn("Dashboard discovery failed", {
+            packageName: this.packageName,
+            modelPath,
+            error: errMessage(err)
+          });
+          if (factsCarryArtifactTag(facts)) {
+            droppedByError.push({ modelPath, name });
+            dashboardSlugs.add(name);
+          }
+          continue;
+        }
+        if (!manifest) {
+          factsByPath.set(modelPath, facts);
+          continue;
+        }
+      } else {
+        const error = model.getCompilationError();
+        if (!error || !await this.claimsToBeADashboard(modelPath)) {
+          if (!error && await this.claimsToBeADashboard(modelPath)) {
+            logger.warn("Dashboard file produced no facts and no error", {
+              packageName: this.packageName,
+              modelPath
+            });
+            droppedByError.push({ modelPath, name });
+            dashboardSlugs.add(name);
+          }
+          continue;
+        }
+        manifest = {
+          name,
+          title: name,
+          autorun: true,
+          entryFile: modelPath,
+          givens: [],
+          error: error.message
+        };
+      }
+      dashboardSlugs.add(name);
+      if (!this.isQueryableEntryPoint(modelPath)) {
+        heldBack.push({ modelPath, name });
+        continue;
+      }
+      if (!matchesDocumentedDashboardName(name)) {
+        unconventionalSlugs.push({ modelPath, name });
+      }
+      discovered.set(name, manifest);
+      if (facts)
+        factsByPath.set(modelPath, facts);
+    }
+    this.dashboards = discovered;
+    this.dashboardWarnings = await this.lintDashboards(factsByPath, allFacts, heldBack, unconventionalSlugs, dashboardSlugs, droppedByError);
+    for (const warning of this.dashboardWarnings) {
+      logger.warn("Dashboard lint", {
+        packageName: this.packageName,
+        model: warning.model,
+        detail: warning.message
+      });
+    }
+  }
+  async lintDashboards(factsByPath, allFacts, heldBack, unconventionalSlugs, knownSlugs, droppedByError) {
+    const warnings = [];
+    const withheldDrills = new Map;
+    try {
+      for (const { modelPath, name } of droppedByError) {
+        warnings.push({
+          model: modelPath,
+          subject: name,
+          message: `"${modelPath}" carries an artifact tag but could not be ` + `read, so it is not served and there is no dashboard ` + `"${name}". The cause is in the server log. Reload the ` + `package to try again.`,
+          severity: "error"
+        });
+      }
+      for (const { modelPath, name } of unconventionalSlugs) {
+        warnings.push({
+          model: modelPath,
+          subject: name,
+          message: `is served, but "${name}" is outside the conventional ` + `dashboard name shape (letters, digits, "-" and "_"). This ` + `server routes it and its published URL carries the name ` + `encoded, so the dashboard works. The convention is worth ` + `keeping anyway: a name outside it has to be percent-encoded ` + `by every caller that builds the URL by hand. Rename the ` + `file if that matters to yours.`,
+          severity: "warn"
+        });
+      }
+      for (const { modelPath, name } of heldBack) {
+        for (const file of allFacts.values()) {
+          for (const drill of file.drills) {
+            if (!drill.to.includes(name))
+              continue;
+            const where = `${drill.source}.${drill.dimension}`;
+            withheldDrills.set(`${where}|${name}`, {
+              subject: where,
+              message: `# drill on ${where} targets "${name}", which IS a ` + `dashboard in this package but is not served (see the ` + `finding on "${modelPath}"), so the click has nowhere ` + `to land.`,
+              severity: "error"
+            });
+          }
+        }
+        warnings.push({
+          model: modelPath,
+          subject: name,
+          message: `is a dashboard, but "${modelPath}" is not listed in ` + `'explores' and this package sets ` + `queryableSources: "declared", so its query would be ` + `refused. It is not served. Add it to 'explores', or set ` + `queryableSources: "all" to keep the curated surface for ` + `discovery only. Listing it is not always sufficient on its ` + `own: the queryable sources are the union of every listed ` + `file's export closure, so a tile reading a source that only ` + `an UNLISTED file exports is still refused. List that file ` + `too, or re-export the source from one already listed.`,
+          severity: "warn"
+        });
+      }
+      for (const [modelPath, facts] of factsByPath) {
+        const manifest = this.dashboards.get(dashboardSlug(modelPath));
+        const findings = manifest ? lintDashboard(facts, manifest) : lintUndiscoveredDashboard(facts);
+        for (const finding of findings) {
+          warnings.push({ model: modelPath, ...finding });
+        }
+      }
+      const drillFacts = Array.from(allFacts.values());
+      for (const finding of withheldDrills.values()) {
+        warnings.push(finding);
+      }
+      for (const finding of lintDrillTargets(drillFacts, knownSlugs)) {
+        warnings.push(finding);
+      }
+      for (const finding of lintSelfDrills(drillFacts)) {
+        warnings.push(finding);
+      }
+      for (const finding of lintGivenTags(drillFacts)) {
+        warnings.push(finding);
+      }
+      for (const finding of await this.unsupportedComponentWarnings()) {
+        warnings.push(finding);
+      }
+    } catch (err) {
+      logger.warn("Dashboard lint failed", {
+        packageName: this.packageName,
+        error: errMessage(err)
+      });
+      warnings.push({
+        message: `Dashboard lint stopped early, so this list is incomplete: an ` + `unknown subset of the curation, dashboard, drill, given and ` + `unsupported-component checks did not run. Treat a missing ` + `finding of any of those kinds as unknown rather than clean, ` + `including the absence of a "held back from the listing" ` + `finding. Reload the package to run the lint again. The ` + `dashboards themselves are unaffected, because they are ` + `discovered before the lint runs. An operator can find the ` + `cause in the server log under "Dashboard lint failed".`,
+        severity: "warn"
+      });
+    }
+    return warnings;
+  }
+  async unsupportedComponentWarnings() {
+    const dir = safeJoinUnderRoot(this.packagePath, DASHBOARDS_DIR);
+    let entries;
+    try {
+      entries = await fs7.readdir(dir);
+    } catch {
+      return [];
+    }
+    const warnings = [];
+    for (const entry of entries.sort()) {
+      const suffix = COMPONENT_FILE_SUFFIXES.find((s) => entry.endsWith(s));
+      if (!suffix)
+        continue;
+      const base = entry.slice(0, -suffix.length);
+      warnings.push({
+        model: `${DASHBOARDS_DIR}/${entry}`,
+        subject: base,
+        message: `Custom dashboard components are not supported, so ` + `"${DASHBOARDS_DIR}/${entry}" is ignored. Any ` + `${DASHBOARDS_DIR}/${base}${MODEL_FILE_SUFFIX} beside it still ` + `renders from its tags. For a page that runs its own code, use ` + `an HTML data app in the package's public/ directory.`,
+        severity: "warn"
+      });
+    }
+    return warnings;
+  }
+  listDashboards() {
+    const servable = this.servableEntryPoints();
+    return Array.from(this.dashboards.values()).filter((manifest) => servable(manifest.entryFile)).map((manifest) => ({
+      resource: this.dashboardResource(manifest.name),
+      packageName: this.packageName,
+      name: manifest.name,
+      path: manifest.entryFile,
+      title: manifest.title,
+      description: manifest.description,
+      error: manifest.error
+    }));
+  }
+  getDashboard(name) {
+    const manifest = this.dashboards.get(name);
+    if (manifest && !this.isQueryableEntryPoint(manifest.entryFile)) {
+      return;
+    }
+    if (!manifest)
+      return;
+    return {
+      resource: this.dashboardResource(manifest.name),
+      packageName: this.packageName,
+      name: manifest.name,
+      path: manifest.entryFile,
+      title: manifest.title,
+      description: manifest.description,
+      error: manifest.error,
+      query: manifest.query,
+      tiles: manifest.tiles,
+      dashboardColumns: manifest.dashboardColumns,
+      startingGivens: manifest.startingGivens,
+      autorun: manifest.autorun,
+      givens: manifest.givens
+    };
+  }
+  dashboardResource(name) {
+    return `${API_PREFIX}/environments/${this.environmentName}/packages/${this.packageName}/dashboards/${encodeURIComponent(name)}`;
+  }
   async listNotebooks() {
     return await Promise.all(Array.from(this.models.keys()).filter((modelPath) => {
       return modelPath.endsWith(NOTEBOOK_FILE_SUFFIX);
     }).map(async (modelPath) => {
-      const error = this.models.get(modelPath)?.getNotebookError();
+      const model = this.models.get(modelPath);
+      const error = model?.getNotebookError();
+      const listing = model?.getNotebookListing() ?? {};
       return {
         environmentName: this.environmentName,
         packageName: this.packageName,
         path: modelPath,
+        title: listing.title,
+        description: listing.description,
         error: error?.message
       };
     }));
@@ -290026,6 +291183,7 @@ function registerDocsSearchTool(mcpServer, _environmentStore) {
 // src/mcp/tools/execute_query_tool.ts
 init_config();
 init_logger();
+init_dashboard();
 
 // src/mcp/query_envelope.ts
 init_json_utils();
@@ -290204,7 +291362,7 @@ function registerExecuteQueryTool(mcpServer, environmentStore) {
         queryCorrelationId
       } = await runWithQueryTimeout((abortSignal) => query ? model.getQueryResults(undefined, undefined, query, filterParams, undefined, givens, abortSignal, queryMetadataInput, "compact") : model.getQueryResults(sourceName, queryName, undefined, filterParams, undefined, givens, abortSignal, queryMetadataInput, "compact"), getQueryTimeoutMs());
       const { validateRenderTags: validateRenderTags2 } = await Promise.resolve().then(() => __toESM(require_dist11(), 1));
-      const renderLogs = validateRenderTags2(result);
+      const renderLogs = filterPublisherOwnedRenderLogs(validateRenderTags2(result));
       const resultUri = buildMalloyUri({
         environment: environmentName,
         package: packageName,
@@ -291316,6 +292474,7 @@ Every skill in this deployment, by what it is for. Start at a driver; it routes
 | Skill | Use when... |
 |-------|-------------|
 | \`skill:malloy-publish\` | Moving a finished model into a served package (local-to-served handoff) |
+| \`skill:malloy-dashboards\` | Building a dashboard: a tagged \`.malloy\` file in a package's \`dashboards/\` directory, with filter controls and drill-through |
 | \`skill:malloy-html-data-apps\` | Building an in-package HTML data app (a \`public/\` directory the package serves) |
 | \`skill:malloy-html-data-app-runtime\` | Writing the JavaScript that drives that app |
 | \`skill:malloy-html-data-app-embedding\` | Embedding a served page into a host application |
@@ -291667,7 +292826,408 @@ Use \`+\` to modify existing views: \`run: source -> my_view + { limit: 15, wher
 
 Step complete. Output: analysis \`.malloy\` file with views, insights, and reusable building blocks. For chart/renderer details, see \`skill:malloy-gotchas-rendering\` or call \`search_malloy_docs\`. To formalize into a model, hand off to the modeling skill (\`skill:malloy-model\`).
 
-Publishing is out of scope for now: open-source Publisher serves the model from disk, and self-hosters publish via git plus their host's publish path.` }, { name: "malloy-charts", description: 'Chart selection guidance and renderer reference for Malloy views. Use when choosing visualization types, adding chart annotations, user asks "what chart should I use", "how should I visualize this", or when deciding between bar_chart, line_chart, scatter_chart, etc.', body: '# Chart Selection for Malloy\n\n> Malloy uses Vega-Lite under the hood. `#` tags control visualization. Call `search_malloy_docs` with topic "rendering" for the full tag reference (or see https://docs.malloydata.dev/documentation/visualizations/overview).\n\n> **Tool names** are written bare here - `get_context`, `execute_query`, `search_malloy_docs`. The exact prefixed name depends on the host surface; match each against the tools you actually have.\n\n## Decision Tree: Which Chart?\n\n| Data Shape | Default Choice |\n|-----------|---------------|\n| Aggregates only (no group_by) | `# big_value` |\n| 1 time column + 1 measure | `# line_chart` |\n| 1 category + 1 measure | `# bar_chart` |\n| 2 numeric columns | `# scatter_chart` |\n| Geographic (US states) + 1 measure | `# shape_map` |\n| Route data (lat/lon pairs) | `# segment_map` |\n| Multiple perspectives | `# dashboard` with `nest:` |\n| Nested query to pivot | `# pivot` |\n| Filtered aggregates side-by-side | `# flatten` |\n| Detailed rows | Default table (no annotation) |\n\n| Goal | Renderer |\n|------|---------|\n| Compare categories | `# bar_chart` (sort by value, limit ~15) |\n| Show composition | `# bar_chart.stack` |\n| Trend over time | `# line_chart` |\n| Highlight KPIs | `# big_value` with `# label` |\n| Correlation | `# scatter_chart` |\n| Compare dimensions | `# dashboard` (nest chart views) |\n| Before/after | `# transpose` or `# pivot` |\n| Multiple metrics per category | Default table, `# flatten`, or `y=[\'a\',\'b\']` |\n\n**Constraints:**\n- ONE aggregate per chart view (charts render only the first; use `y=[\'a\',\'b\']` for multi-measure)\n- No fixed scale on measure definitions: use `# currency` not `# currency=usd0m`\n- One tag per line\n- Alias joined fields in `group_by` before `order_by`\n- Define measures in source, not in views\n\n\n## Chart Types\n\n### `# bar_chart`\n\n**Data shape:** `group_by` = x-axis, `aggregate` = y-axis, optional 2nd `group_by` = series.\n\n```malloy\n# bar_chart\nview: by_carrier is { group_by: carrier, aggregate: flight_count, order_by: flight_count desc, limit: 10 }\n\n# bar_chart.stack\nview: by_region is { group_by: category, region, aggregate: revenue }\n\n# bar_chart { y=[\'revenue\',\'cost\'] }\nview: rev_vs_cost is { group_by: category, aggregate: revenue, cost }\n```\n\n**Key properties:** `.stack`, `.size` (spark/xs/sm/md/lg/xl/2xl), `.x`, `.x.limit`, `.y` (supports `y=[\'a\',\'b\']`), `.series`, `.series.limit` (default 20), `.title`, `.subtitle`, `.x.independent`, `.y.independent`\n\n**Field role tags:** `# x`, `# y`, `# series` on individual fields to assign roles explicitly.\n\n### `# line_chart`\n\n**Data shape:** `group_by` (temporal/numeric) = x-axis, `aggregate` = y-axis, optional 2nd `group_by` = series.\n\n```malloy\n# line_chart\nview: trend is { group_by: order_month, aggregate: revenue, order_by: order_month }\n\n# line_chart { size=spark }\nview: mini_trend is { group_by: order_month, aggregate: revenue, order_by: order_month }\n```\n\n**Key properties:** `.zero_baseline`, `.interpolate` (e.g., `step`), `.size`, `.y` (supports `y=[\'a\',\'b\']`), `.series.limit` (default 12), `.title`, `.subtitle`\n\n### `# scatter_chart`\n\n**Data shape:** Fields by position: x, y, color, size (bubble), shape.\n\n```malloy\n# scatter_chart\nview: correlation is { group_by: customer_id, aggregate: avg_price, total_quantity }\n```\n\n### `# shape_map`\n\nChoropleth. US states only. Fields: state name, value.\n\n```malloy\n# shape_map\nview: by_state is { group_by: state, aggregate: revenue }\n```\n\n### `# segment_map`\n\nRoute map. US only. Fields: start_lat, start_lon, end_lat, end_lon, color.\n\n\n## Layout Types\n\n### `# big_value`\n\nKPI cards. Aggregates only, no `group_by`.\n\n```malloy\n# big_value\nview: summary is {\n  aggregate:\n    # label="Revenue"\n    # currency\n    revenue\n    # label="Orders"\n    # number=auto\n    order_count\n}\n```\n\n**Properties:** `.size`, `.sparkline=<nested_view_name>`, `.comparison_field`, `.comparison_label`, `.down_is_good`\n\n### `# dashboard`\n\nCard-based multi-tile layout. Apply to a view whose body is a nested query; the view\'s own fields lay out automatically:\n\n- `group_by` dimensions -> a row header (repeats once per row; omit for a single block)\n- `aggregate` measures -> KPI cards, one per measure\n- each `nest:` -> a tile, rendered by the tag above it (`# table` default, or `# bar_chart` / `# line_chart` / `# big_value`)\n\n**Two modes.** Flex (default): tiles flow and wrap; `# break` forces a new row. Columns: `# dashboard { columns=N }` lays tiles into N equal columns, `# colspan=n` widens a tile, `# break` starts a new row, overflow wraps.\n\n```malloy\n// Flex: measures become KPI cards, the nest becomes a tile\n# dashboard\nview: overview is {\n  group_by: category\n  # currency\n  aggregate:\n    avg_retail is retail_price.avg()\n    sum_retail is retail_price.sum()\n  nest:\n    # bar_chart\n    by_brand is { group_by: brand, aggregate: avg_retail is retail_price.avg(), limit: 10 }\n}\n\n// Columns: # colspan widens tiles, # break ends a row\n# dashboard { columns=12 }\nview: layout is {\n  group_by: category\n  # currency\n  aggregate:\n    # colspan=4\n    avg_retail is retail_price.avg()\n    # colspan=4\n    sum_retail is retail_price.sum()\n    # colspan=4\n    max_retail is retail_price.max()\n  nest:\n    # break\n    # colspan=6\n    # bar_chart\n    # subtitle="Top brands"\n    by_brand_chart is { group_by: brand, aggregate: avg_retail is retail_price.avg(), limit: 8 }\n    # colspan=6\n    by_brand_table is { group_by: brand, aggregate: product_count is count(), limit: 8 }\n}\n```\n\n**Tags:** `# dashboard { columns=N }` (columns mode), `{ gap=PX }` (tile spacing, default 16; never a mode), `{ table.max_height=PX|none }` (cap table tiles). On a measure or nest: `# colspan=N` (columns mode only), `# break` (both modes), `# subtitle="..."` (tile), `# borderless` (drop card chrome), `# label="..."` (card title).\n\nFor rich KPI cards (sparklines, comparison deltas, several metrics on one card) nest a `# big_value` view instead of relying on the dashboard\'s own measures:\n\n```malloy\n# dashboard\nview: kpis is {\n  group_by: category\n  nest:\n    # big_value\n    revenue_card is {\n      aggregate:\n        # label="Revenue"\n        # currency\n        # big_value { sparkline=trend }\n        total_revenue is retail_price.sum()\n      # line_chart { size=spark y.independent=true }\n      # hidden\n      nest: trend is { group_by: bucket is floor(id / 100)::number, aggregate: total_revenue is retail_price.sum(), order_by: bucket, limit: 20 }\n    }\n}\n```\n\n**Rules:** `# dashboard` needs a nested-query view (no effect on a scalar). `# colspan` works only in columns mode and is ignored (warns) in flex. `columns` is any positive integer; a `# colspan` over the column count clamps to a full row. Style tiles via the instance theme, or theme the views inside with `# theme.*` (see Theming below).\n\n### `# pivot`\n\nPivot nested results into columns. Max 30 pivot columns.\n\n```malloy\nview: sales is {\n  group_by: product, aggregate: total\n  nest: # pivot\n    by_quarter is { group_by: quarter, aggregate: revenue }\n}\n```\n\n### `# transpose`\n\nSwap rows/columns. Good for period comparisons.\n\n```malloy\n# transpose\nview: comparison is {\n  aggregate:\n    # label="This Month"\n    current_revenue\n    # label="Last Month"\n    prior_revenue\n}\n```\n\n### `# list` / `# list_detail`\n\nList renders as comma-separated values. List_detail shows `value (detail)` pairs.\n\n### `# flatten`\n\nCollapse nested record into parent table as columns. Use for side-by-side filtered aggregates:\n\n```malloy\nview: segments is {\n  group_by: product, aggregate: total_revenue\n  nest: # flatten\n    enterprise is { where: segment = \'Enterprise\', aggregate: # label="Enterprise" revenue }\n  nest: # flatten\n    smb is { where: segment = \'SMB\', aggregate: # label="SMB" revenue }\n}\n```\n\n### `# table`\n\nDefault (implicit). Use explicitly for `.size=fill` property.\n\n\n## Field Formatting Tags\n\n| Tag | Use For | Shorthand |\n|-----|---------|-----------|\n| `# number` | Numeric formatting | `=auto` (K/M/B), `=id` (no commas), `=1k`, `=1m` |\n| `# percent` | Percentages | (none needed) |\n| `# currency` | Money | `=usd2m` (USD, 2 decimals, millions); scale only in views |\n| `# duration` | Time durations | `=seconds`, `=minutes`, `=hours`, `=days` |\n| `# data_volume` | Storage sizes | `=bytes`, `=kb`, `=mb`, `=gb` |\n| `# link` | Hyperlinks | `.url_template="https://example.com/$$"` |\n| `# image` | Inline images | `.height=40px`, `.width=100px` |\n\n**Currency codes:** `usd` ($), `eur`, `gbp`. **Scale:** K/M/B/T/Q or `auto`.\n**Number suffix styles:** `word` ("42.5 million"), `letter` ("42.5M"), `scientific`.\n\n## Utility Tags\n\n| Tag | Purpose |\n|-----|---------|\n| `# hidden` | Hide from output (still usable for sorting/references) |\n| `# label="..."` | Override display name |\n| `# description="..."` | Tooltip text |\n| `# tooltip` | Include nested view in chart tooltip |\n| `# break` | Force new dashboard row |\n| `# column { width=sm }` | Table column width |\n\n## Model-Level Defaults\n\n```malloy\n## viz.line_chart.defaults.y.independent=true\n## viz.bar_chart.defaults.stack\n```\n\n## Theming\n\nPublisher styles charts and tables from one structured theme. The instance sets it (in `publisher.config.json`\'s `theme` block or the **Settings, then Theme** editor); a model overrides it per result with `# theme.*` annotations, or model-wide with `## theme.*`. Per-chart annotations use the same nested `palette.*` / `font.*` vocabulary as the config, not flat key names, and they win over the instance theme for the keys they set. The forms:\n\n| Annotation | Controls | Modes |\n|-----------|----------|-------|\n| `# theme.palette.series` | Categorical series colors (array) | shared |\n| `# theme.palette.background.{light,dark}` | Chart canvas + table background | per-mode |\n| `# theme.palette.tableHeader.{light,dark}` | Table header text color | per-mode |\n| `# theme.palette.tableHeaderBackground.{light,dark}` | Table header row background | per-mode |\n| `# theme.palette.tableBody.{light,dark}` | Table body text color | per-mode |\n| `# theme.palette.tile.{light,dark}` | Dashboard tile background | per-mode |\n| `# theme.palette.tileTitle.{light,dark}` | Dashboard tile title color | per-mode |\n| `# theme.palette.mapColor.{light,dark}` | Choropleth gradient (`# shape_map` / `# segment_map`) | per-mode |\n| `# theme.font.family` | Font for all rendered text | shared |\n| `# theme.font.size` | Table font size (px) | shared |\n\nThe seven `palette.*` color keys each take a `.light` and/or `.dark` variant so dark mode gets its own value. `palette.series`, `font.family`, and `font.size` are single values shared across modes.\n\n```malloy\n// Model-wide defaults (## applies to every view in the model):\n## theme.palette.series = ["#14b3cb", "#e47404", "#1474a4"]\n## theme.font.family = "Inter, sans-serif"\n\n// Per-view override (# applies to this result only; beats the instance theme):\n# theme.palette.background.light = "#fafafa"\n# theme.palette.background.dark = "#111111"\n# theme.palette.tableHeader.dark = "#94a3b8"\nview: revenue_by_month is {\n  group_by: month\n  aggregate: revenue\n}\n```\n\n**Precedence**, highest to lowest, per key: `# theme.*` on the view, then `## theme.*` model default, then the instance theme, then Publisher\'s built-in defaults. A per-chart annotation overrides the instance for the keys it sets; unset keys fall through to the instance. (This is the reverse of a bare `@malloydata/render` embed, where the embedder wins: Publisher reads the annotation itself and layers it on top.)\n\nQuote values that contain spaces or a leading `#`. The light/dark default (`defaultMode`) and the toggle lock (`allowUserToggle`) are instance-only: set them in the config `theme` block or the editor, not as annotations. The malloy-gotchas-rendering skill lists the annotation forms that look valid but do nothing.\n\n\n## Advanced Patterns\n\n### Sparklines in KPI Cards\n\n```malloy\n# big_value { sparkline=trend }\nview: revenue_kpi is {\n  aggregate: # label="Revenue" # currency revenue\n  nest: # line_chart { size=spark } # hidden\n    trend is { group_by: order_date, aggregate: revenue, order_by: order_date }\n}\n```\n\n### KPIs with Comparison Deltas\n\n```malloy\n# big_value { comparison_field=prior_month comparison_label="vs Last Month" }\nview: rev_delta is {\n  aggregate: # label="Revenue" # currency revenue, # hidden prior_month\n}\n```\n\nUse `down_is_good=true` for metrics where decrease is positive (churn, defects).\n\n### Inline Mini-Charts in Table Rows\n\n```malloy\nview: carriers is {\n  group_by: carrier, aggregate: flight_count\n  nest: # line_chart { size=spark }\n    trend is { group_by: month, aggregate: flight_count, order_by: month }\n}\n```\n\n### Multi-Measure Series\n\n```malloy\n# bar_chart { y=[\'revenue\',\'cost\'] }\nview: rev_vs_cost is { group_by: quarter, aggregate: revenue, cost }\n```\n\n### Hierarchical Drill-Down\n\n```malloy\n# list_detail\nview: explorer is {\n  group_by: region, aggregate: revenue\n  nest: # bar_chart\n    by_category is { group_by: category, aggregate: revenue, order_by: revenue desc, limit: 10 }\n}\n```\n\n### Distribution (Histogram)\n\nThere is no auto-binning function: `autobin(...)` does not exist and fails with `Unknown function \'autobin\'`. Bin by arithmetic, choosing the width from the column\'s actual range: query `min`, `max` and a few percentiles first, and say in the view\'s doc where the width came from. A bin width nobody derived is a business decision in disguise.\n\n```malloy\n# bar_chart\nview: price_dist is {\n  group_by: bucket is floor(price / 20) * 20   // 20 is the bin width, from the observed range\n  aggregate: order_count is count()\n  order_by: bucket\n}\n```\n\n\n## Patterns for Missing Chart Types\n\n| Desired | Malloy Approximation |\n|---------|---------------------|\n| Pie/donut | `# bar_chart` sorted by value |\n| Treemap | Nested table with `order_by: desc` |\n| Heatmap | `# pivot` with color values |\n| Stacked area | `# line_chart` with series (overlaid lines) |\n| Funnel | `# bar_chart` with ordered stages |\n| Gauge/bullet | `# big_value` with `.comparison_field` |\n\n\n## Chart Annotations on Queries with `nest:`\n\nA top-level chart tag (e.g., `# bar_chart`) renders only the outer query; any `nest:` views are silently hidden from the rendering (still in raw data). To show nests, use `# dashboard` on the outer query with chart tags on each nest. Otherwise, drop the `nest:`.\n\n\n## Common Mistakes\n\n| Mistake | Fix |\n|---------|-----|\n| Two aggregates in chart | ONE aggregate, or use `y=[\'a\',\'b\']` |\n| `# currency=usd0m` on measure | `# currency` (no scale) on defs; scale only in views |\n| Chart annotation on `nest:` line | Put on the **view definition** |\n| Tags on same line | One tag per line |\n| Sparkline not showing | Add `# hidden` to nested view AND reference in `.sparkline=` |\n| Pivot > 30 columns | Filter/limit the nested group_by |\n\nNOTE: The term \'constructor\' is a reserved term in Vega-Lite. If the word \'constructor\' appears in the query, it will cause the rendering to fail. Never use it in a query and avoid using it as a dimension in a model.\n\nFor more patterns, call `search_malloy_docs` with topics like "bar charts", "line charts", "dashboards", "histograms", "percent of total", "comparing timeframes", or "pivots".\n\n## Further Reading\n\n- [Visualizations Overview](https://docs.malloydata.dev/documentation/visualizations/overview) - Official docs\n- [Bar Charts](https://docs.malloydata.dev/documentation/visualizations/bar_charts) - Stacked, grouped, series\n- [Bump Charts Blog](https://docs.malloydata.dev/blog/2023-10-26-malloy-bump-chart/) - Ranking over time\n- [Dataviz is Hierarchical](https://docs.malloydata.dev/blog/2024-02-29-hierarchical-viz/) - Nested data visualization philosophy' }, { name: "malloy-debug", description: 'Fix Malloy compile errors and understand error messages. Use when encountering errors in .malloy files, user says "fix this error", "malloy error", "compile error", "syntax error", or sees 20+ cascading errors.', body: `# Debugging Malloy Errors
+Publishing is out of scope for now: open-source Publisher serves the model from disk, and self-hosters publish via git plus their host's publish path.` }, { name: "malloy-charts", description: 'Chart selection guidance and renderer reference for Malloy views. Use when choosing visualization types, adding chart annotations, user asks "what chart should I use", "how should I visualize this", or when deciding between bar_chart, line_chart, scatter_chart, etc.', body: '# Chart Selection for Malloy\n\n> Malloy uses Vega-Lite under the hood. `#` tags control visualization. Call `search_malloy_docs` with topic "rendering" for the full tag reference (or see https://docs.malloydata.dev/documentation/visualizations/overview).\n\n> **Tool names** are written bare here - `get_context`, `execute_query`, `search_malloy_docs`. The exact prefixed name depends on the host surface; match each against the tools you actually have.\n\n## Decision Tree: Which Chart?\n\n| Data Shape | Default Choice |\n|-----------|---------------|\n| Aggregates only (no group_by) | `# big_value` |\n| 1 time column + 1 measure | `# line_chart` |\n| 1 category + 1 measure | `# bar_chart` |\n| 2 numeric columns | `# scatter_chart` |\n| Geographic (US states) + 1 measure | `# shape_map` |\n| Route data (lat/lon pairs) | `# segment_map` |\n| Multiple perspectives | `# dashboard` with `nest:` |\n| Nested query to pivot | `# pivot` |\n| Filtered aggregates side-by-side | `# flatten` |\n| Detailed rows | Default table (no annotation) |\n\n| Goal | Renderer |\n|------|---------|\n| Compare categories | `# bar_chart` (sort by value, limit ~15) |\n| Show composition | `# bar_chart.stack` |\n| Trend over time | `# line_chart` |\n| Highlight KPIs | `# big_value` with `# label` |\n| Correlation | `# scatter_chart` |\n| Compare dimensions | `# dashboard` (nest chart views) |\n| Before/after | `# transpose` or `# pivot` |\n| Multiple metrics per category | Default table, `# flatten`, or `y=[\'a\',\'b\']` |\n\n**Constraints:**\n- ONE aggregate per chart view (charts render only the first; use `y=[\'a\',\'b\']` for multi-measure)\n- No fixed scale on measure definitions: use `# currency` not `# currency=usd0m`\n- One tag per line\n- Alias joined fields in `group_by` before `order_by`\n- Define measures in source, not in views\n\n\n## Chart Types\n\n### `# bar_chart`\n\n**Data shape:** `group_by` = x-axis, `aggregate` = y-axis, optional 2nd `group_by` = series.\n\n```malloy\n# bar_chart\nview: by_carrier is { group_by: carrier, aggregate: flight_count, order_by: flight_count desc, limit: 10 }\n\n# bar_chart.stack\nview: by_region is { group_by: category, region, aggregate: revenue }\n\n# bar_chart { y=[\'revenue\',\'cost\'] }\nview: rev_vs_cost is { group_by: category, aggregate: revenue, cost }\n```\n\n**Key properties:** `.stack`, `.size` (spark/xs/sm/md/lg/xl/2xl), `.x`, `.x.limit`, `.y` (supports `y=[\'a\',\'b\']`), `.series`, `.series.limit` (default 20), `.title`, `.subtitle`, `.x.independent`, `.y.independent`\n\n**Field role tags:** `# x`, `# y`, `# series` on individual fields to assign roles explicitly.\n\n### `# line_chart`\n\n**Data shape:** `group_by` (temporal/numeric) = x-axis, `aggregate` = y-axis, optional 2nd `group_by` = series.\n\n```malloy\n# line_chart\nview: trend is { group_by: order_month, aggregate: revenue, order_by: order_month }\n\n# line_chart { size=spark }\nview: mini_trend is { group_by: order_month, aggregate: revenue, order_by: order_month }\n```\n\n**Key properties:** `.zero_baseline`, `.interpolate` (e.g., `step`), `.size`, `.y` (supports `y=[\'a\',\'b\']`), `.series.limit` (default 12), `.title`, `.subtitle`\n\n### `# scatter_chart`\n\n**Data shape:** Fields by position: x, y, color, size (bubble), shape.\n\n```malloy\n# scatter_chart\nview: correlation is { group_by: customer_id, aggregate: avg_price, total_quantity }\n```\n\n### `# shape_map`\n\nChoropleth. US states only. Fields: state name, value.\n\n```malloy\n# shape_map\nview: by_state is { group_by: state, aggregate: revenue }\n```\n\n### `# segment_map`\n\nRoute map. US only. Fields: start_lat, start_lon, end_lat, end_lon, color.\n\n\n## Layout Types\n\n### `# big_value`\n\nKPI cards. Aggregates only, no `group_by`.\n\n```malloy\n# big_value\nview: summary is {\n  aggregate:\n    # label="Revenue"\n    # currency\n    revenue\n    # label="Orders"\n    # number=auto\n    order_count\n}\n```\n\n**Properties:** `.size`, `.sparkline=<nested_view_name>`, `.comparison_field`, `.comparison_label`, `.down_is_good`\n\n### `# dashboard`\n\nCard-based multi-tile layout. Apply to a view whose body is a nested query; the view\'s own fields lay out automatically:\n\n- `group_by` dimensions -> a row header (repeats once per row; omit for a single block)\n- `aggregate` measures -> KPI cards, one per measure\n- each `nest:` -> a tile, rendered by the tag above it (`# table` default, or `# bar_chart` / `# line_chart` / `# big_value`)\n\n**Two modes.** Flex (default): tiles flow and wrap; `# break` forces a new row. Columns: `# dashboard { columns=N }` lays tiles into N equal columns, `# colspan=n` widens a tile, `# break` starts a new row, overflow wraps.\n\n```malloy\n// Flex: measures become KPI cards, the nest becomes a tile\n# dashboard\nview: overview is {\n  group_by: category\n  # currency\n  aggregate:\n    avg_retail is retail_price.avg()\n    sum_retail is retail_price.sum()\n  nest:\n    # bar_chart\n    by_brand is { group_by: brand, aggregate: avg_retail is retail_price.avg(), limit: 10 }\n}\n\n// Columns: # colspan widens tiles, # break ends a row\n# dashboard { columns=12 }\nview: layout is {\n  group_by: category\n  # currency\n  aggregate:\n    # colspan=4\n    avg_retail is retail_price.avg()\n    # colspan=4\n    sum_retail is retail_price.sum()\n    # colspan=4\n    max_retail is retail_price.max()\n  nest:\n    # break\n    # colspan=6\n    # bar_chart\n    # subtitle="Top brands"\n    by_brand_chart is { group_by: brand, aggregate: avg_retail is retail_price.avg(), limit: 8 }\n    # colspan=6\n    by_brand_table is { group_by: brand, aggregate: product_count is count(), limit: 8 }\n}\n```\n\n**Tags:** `# dashboard { columns=N }` (columns mode), `{ gap=PX }` (tile spacing, default 16; never a mode), `{ table.max_height=PX|none }` (cap table tiles). On a measure or nest: `# colspan=N` (columns mode only), `# break` (both modes), `# subtitle="..."` (tile), `# borderless` (drop card chrome), `# label="..."` (card title).\n\nFor rich KPI cards (sparklines, comparison deltas, several metrics on one card) nest a `# big_value` view instead of relying on the dashboard\'s own measures:\n\n```malloy\n# dashboard\nview: kpis is {\n  group_by: category\n  nest:\n    # big_value\n    revenue_card is {\n      aggregate:\n        # label="Revenue"\n        # currency\n        # big_value { sparkline=trend }\n        total_revenue is retail_price.sum()\n      # line_chart { size=spark y.independent=true }\n      # hidden\n      nest: trend is { group_by: bucket is floor(id / 100)::number, aggregate: total_revenue is retail_price.sum(), order_by: bucket, limit: 20 }\n    }\n}\n```\n\n**Rules:** `# dashboard` needs a nested-query view (no effect on a scalar). `# colspan` works only in columns mode and is ignored (warns) in flex. `columns` is any positive integer; a `# colspan` over the column count clamps to a full row. Style tiles via the instance theme, or theme the views inside with `# theme.*` (see Theming below).\n\n### `# pivot`\n\nPivot nested results into columns. Max 30 pivot columns.\n\n```malloy\nview: sales is {\n  group_by: product, aggregate: total\n  nest: # pivot\n    by_quarter is { group_by: quarter, aggregate: revenue }\n}\n```\n\n### `# transpose`\n\nSwap rows/columns. Good for period comparisons.\n\n```malloy\n# transpose\nview: comparison is {\n  aggregate:\n    # label="This Month"\n    current_revenue\n    # label="Last Month"\n    prior_revenue\n}\n```\n\n### `# list` / `# list_detail`\n\nList renders as comma-separated values. List_detail shows `value (detail)` pairs.\n\n### `# flatten`\n\nCollapse nested record into parent table as columns. Use for side-by-side filtered aggregates:\n\n```malloy\nview: segments is {\n  group_by: product, aggregate: total_revenue\n  nest: # flatten\n    enterprise is { where: segment = \'Enterprise\', aggregate: # label="Enterprise" revenue }\n  nest: # flatten\n    smb is { where: segment = \'SMB\', aggregate: # label="SMB" revenue }\n}\n```\n\n### `# table`\n\nDefault (implicit). Use explicitly for `.size=fill` property.\n\n\n## Field Formatting Tags\n\n| Tag | Use For | Shorthand |\n|-----|---------|-----------|\n| `# number` | Numeric formatting | `=auto` (K/M/B), `=id` (no commas), `=1k`, `=1m` |\n| `# percent` | Percentages | (none needed) |\n| `# currency` | Money | `=usd2m` (USD, 2 decimals, millions); scale only in views |\n| `# duration` | Time durations | `=seconds`, `=minutes`, `=hours`, `=days` |\n| `# data_volume` | Storage sizes | `=bytes`, `=kb`, `=mb`, `=gb` |\n| `# link` | Hyperlinks | `.url_template="https://example.com/$$"` |\n| `# image` | Inline images | `.height=40px`, `.width=100px` |\n\n**Currency codes:** `usd` ($), `eur`, `gbp`. **Scale:** K/M/B/T/Q or `auto`.\n**Number suffix styles:** `word` ("42.5 million"), `letter` ("42.5M"), `scientific`.\n\n## Utility Tags\n\n| Tag | Purpose |\n|-----|---------|\n| `# hidden` | Hide from output (still usable for sorting/references) |\n| `# label="..."` | Override display name |\n| `# description="..."` | Tooltip text |\n| `# tooltip` | Include nested view in chart tooltip |\n| `# break` | Force new dashboard row |\n| `# column { width=sm }` | Table column width |\n\n## Model-Level Defaults\n\n```malloy\n## viz.line_chart.defaults.y.independent=true\n## viz.bar_chart.defaults.stack\n```\n\n## Theming\n\nPublisher styles charts and tables from one structured theme. The instance sets it (in `publisher.config.json`\'s `theme` block or the **Settings, then Theme** editor); a model overrides it per result with `# theme.*` annotations, or model-wide with `## theme.*`. Per-chart annotations use the same nested `palette.*` / `font.*` vocabulary as the config, not flat key names, and they win over the instance theme for the keys they set. The forms:\n\n| Annotation | Controls | Modes |\n|-----------|----------|-------|\n| `# theme.palette.series` | Categorical series colors (array) | shared |\n| `# theme.palette.background.{light,dark}` | Chart canvas + table background | per-mode |\n| `# theme.palette.tableHeader.{light,dark}` | Table header text color | per-mode |\n| `# theme.palette.tableHeaderBackground.{light,dark}` | Table header row background | per-mode |\n| `# theme.palette.tableBody.{light,dark}` | Table body text color | per-mode |\n| `# theme.palette.tile.{light,dark}` | Dashboard tile background | per-mode |\n| `# theme.palette.tileTitle.{light,dark}` | Dashboard tile title color | per-mode |\n| `# theme.palette.mapColor.{light,dark}` | Choropleth gradient (`# shape_map` / `# segment_map`) | per-mode |\n| `# theme.font.family` | Font for all rendered text | shared |\n| `# theme.font.size` | Table font size (px) | shared |\n\nThe seven `palette.*` color keys each take a `.light` and/or `.dark` variant so dark mode gets its own value. `palette.series`, `font.family`, and `font.size` are single values shared across modes.\n\n```malloy\n// Model-wide defaults (## applies to every view in the model):\n## theme.palette.series = ["#14b3cb", "#e47404", "#1474a4"]\n## theme.font.family = "Inter, sans-serif"\n\n// Per-view override (# applies to this result only; beats the instance theme):\n# theme.palette.background.light = "#fafafa"\n# theme.palette.background.dark = "#111111"\n# theme.palette.tableHeader.dark = "#94a3b8"\nview: revenue_by_month is {\n  group_by: month\n  aggregate: revenue\n}\n```\n\n**Precedence**, highest to lowest, per key: `# theme.*` on the view, then `## theme.*` model default, then the instance theme, then Publisher\'s built-in defaults. A per-chart annotation overrides the instance for the keys it sets; unset keys fall through to the instance. (This is the reverse of a bare `@malloydata/render` embed, where the embedder wins: Publisher reads the annotation itself and layers it on top.)\n\nQuote values that contain spaces or a leading `#`. The light/dark default (`defaultMode`) and the toggle lock (`allowUserToggle`) are instance-only: set them in the config `theme` block or the editor, not as annotations. The malloy-gotchas-rendering skill lists the annotation forms that look valid but do nothing.\n\n\n## Advanced Patterns\n\n### Sparklines in KPI Cards\n\n```malloy\n# big_value { sparkline=trend }\nview: revenue_kpi is {\n  aggregate: # label="Revenue" # currency revenue\n  nest: # line_chart { size=spark } # hidden\n    trend is { group_by: order_date, aggregate: revenue, order_by: order_date }\n}\n```\n\n### KPIs with Comparison Deltas\n\n```malloy\n# big_value { comparison_field=prior_month comparison_label="vs Last Month" }\nview: rev_delta is {\n  aggregate: # label="Revenue" # currency revenue, # hidden prior_month\n}\n```\n\nUse `down_is_good=true` for metrics where decrease is positive (churn, defects).\n\n### Inline Mini-Charts in Table Rows\n\n```malloy\nview: carriers is {\n  group_by: carrier, aggregate: flight_count\n  nest: # line_chart { size=spark }\n    trend is { group_by: month, aggregate: flight_count, order_by: month }\n}\n```\n\n### Multi-Measure Series\n\n```malloy\n# bar_chart { y=[\'revenue\',\'cost\'] }\nview: rev_vs_cost is { group_by: quarter, aggregate: revenue, cost }\n```\n\n### Hierarchical Drill-Down\n\n```malloy\n# list_detail\nview: explorer is {\n  group_by: region, aggregate: revenue\n  nest: # bar_chart\n    by_category is { group_by: category, aggregate: revenue, order_by: revenue desc, limit: 10 }\n}\n```\n\n### Distribution (Histogram)\n\nThere is no auto-binning function: `autobin(...)` does not exist and fails with `Unknown function \'autobin\'`. Bin by arithmetic, choosing the width from the column\'s actual range: query `min`, `max` and a few percentiles first, and say in the view\'s doc where the width came from. A bin width nobody derived is a business decision in disguise.\n\n```malloy\n# bar_chart\nview: price_dist is {\n  group_by: bucket is floor(price / 20) * 20   // 20 is the bin width, from the observed range\n  aggregate: order_count is count()\n  order_by: bucket\n}\n```\n\n\n## Patterns for Missing Chart Types\n\n| Desired | Malloy Approximation |\n|---------|---------------------|\n| Pie/donut | `# bar_chart` sorted by value |\n| Treemap | Nested table with `order_by: desc` |\n| Heatmap | `# pivot` with color values |\n| Stacked area | `# line_chart` with series (overlaid lines) |\n| Funnel | `# bar_chart` with ordered stages |\n| Gauge/bullet | `# big_value` with `.comparison_field` |\n\n\n## Chart Annotations on Queries with `nest:`\n\nA top-level chart tag (e.g., `# bar_chart`) renders only the outer query; any `nest:` views are silently hidden from the rendering (still in raw data). To show nests, use `# dashboard` on the outer query with chart tags on each nest. Otherwise, drop the `nest:`.\n\n\n## Common Mistakes\n\n| Mistake | Fix |\n|---------|-----|\n| Two aggregates in chart | ONE aggregate, or use `y=[\'a\',\'b\']` |\n| `# currency=usd0m` on measure | `# currency` (no scale) on defs; scale only in views |\n| Chart annotation on `nest:` line | Put on the **view definition** |\n| Tags on same line | One tag per line |\n| Sparkline not showing | Add `# hidden` to nested view AND reference in `.sparkline=` |\n| Pivot > 30 columns | Filter/limit the nested group_by |\n\nNOTE: The term \'constructor\' is a reserved term in Vega-Lite. If the word \'constructor\' appears in the query, it will cause the rendering to fail. Never use it in a query and avoid using it as a dimension in a model.\n\nFor more patterns, call `search_malloy_docs` with topics like "bar charts", "line charts", "dashboards", "histograms", "percent of total", "comparing timeframes", or "pivots".\n\n## Further Reading\n\n- [Visualizations Overview](https://docs.malloydata.dev/documentation/visualizations/overview) - Official docs\n- [Bar Charts](https://docs.malloydata.dev/documentation/visualizations/bar_charts) - Stacked, grouped, series\n- [Bump Charts Blog](https://docs.malloydata.dev/blog/2023-10-26-malloy-bump-chart/) - Ranking over time\n- [Dataviz is Hierarchical](https://docs.malloydata.dev/blog/2024-02-29-hierarchical-viz/) - Nested data visualization philosophy' }, { name: "malloy-dashboards", description: "Build or modify a Malloy Publisher dashboard, a tagged .malloy file in a package's dashboards/ directory, with auto-rendered filter controls, a grid layout, and # drill click-through. Use when the user asks for a dashboard, a filterable operational view, or drill-through between views, and no code is wanted.", body: `# Publisher Dashboards
+
+> A \`dashboards/*.malloy\` file **is** a dashboard. It imports the model, either declares one query and applies its own filtering or names views that already do, and tags the layout. Publisher discovers it at package load, renders the filter controls from the givens it references, offers \`# drill\` click-through between pages, and serves it at \`/<env>/<pkg>/dashboards/<name>\`. No code, no build step.
+
+## When this is the right tool
+
+| The user wants                                       | Use                                              |
+| ---------------------------------------------------- | ------------------------------------------------ |
+| A recurring, at-a-glance view behind shared filters  | this skill (a dashboard)                         |
+| A narrative, with prose between the numbers          | a notebook (\`skill:malloy-notebooks\`)            |
+| Custom design, branding, or interactions beyond tags | an HTML data app (\`skill:malloy-html-data-apps\`) |
+| The model itself: sources, measures, joins           | \`skill:malloy-modeling\`                          |
+
+Notebooks and dashboards run the same engine, so **interactivity is not the axis**: both get filter
+controls, URL-addressable state, Apply batching, and \`# drill\`. Pick on the shape of the document.
+Scanned at a glance is a dashboard; read top to bottom is a notebook.
+
+## Build sequence
+
+1. **READ THE MODEL FIRST.** Get the real source, view, dimension, and given names from the package:
+   \`malloy_getContext\` if you have it, otherwise the REST model endpoint or the \`.malloy\` files.
+   Never guess a name. A guessed field in a query fails the whole package load, not just that one
+   dashboard; a guessed tile or suggest source is quieter, and only shows up in the package warnings.
+2. **DECIDE THE FORM** (below): single-query if the page is one filtered result with parts;
+   composite if the views already exist and the job is choosing which to show together.
+3. **DECLARE THE GIVENS** the dashboard will filter by, in the model (usually \`givens.malloy\`), with
+   their control tags: see "Filter controls" below for the syntax and what each tag renders as. Skip
+   if they already exist, since a given is a model concern and dashboards share them.
+4. **COMPOSE THE FILE** for \`dashboards/\`, following the template below, but do not save it yet.
+   Import every given it filters by, and every source or query any of those givens names in a
+   \`suggest\`. Both are per-file, and getting the suggest wrong does not error: the control still
+   looks like a picker but has no options, and says so underneath, "Could not load the options for
+   this control". The package warnings name it too.
+5. **COMPILE IT** with \`malloy_compile\` (or \`POST …/models/<path>/compile\`), against the source text,
+   before you save, at the path the file will have. **Editing one that already exists needs
+   \`"scope": "file"\`**, which compiles your source AS that file; the default appends it instead, so
+   every imported name and the query name collide with the saved copy and you get a wall of
+   already-defined errors that reads as broken Malloy rather than a wrong scope. **Editing a shared
+   include wants \`"scope": "package"\`**, which recompiles every file as saved: \`file\` only checks the
+   one you are editing, so renaming a source in \`_shared.malloy\` passes it while breaking every
+   composite that imports it. A clean compile is not a working dashboard: some tag mistakes surface
+   at step 6, and some only when you look at the page in step 7. (The third scope, \`append\`, is the
+   default and is what a not-yet-saved file gets.)
+6. **SAVE IT, RELOAD, AND READ THE MANIFEST AND THE WARNINGS.** \`malloy_reloadPackage\`, or
+   \`GET …/packages/<pkg>?reload=true\`. Check the status the reload returns as well as the warnings:
+   a 424 means the package did not load and your edit is not live. **The \`warnings\` key is absent
+   when there are none**, so an empty response is the pass, not a sign you are reading the wrong
+   field. Then read \`GET …/packages/<pkg>/dashboards/<name>\`: its \`givens\` are exactly the controls
+   that will render, which catches a given you imported but never referenced before you open the page,
+   and its \`query\` is the name to run in step 7. See "Read the lint" below.
+7. **OPEN IT AND LOOK.** Not optional; see "What 'done' means".
+
+## The two forms
+
+**Single-query:** one query whose result is the dashboard. Reach for this by default.
+
+\`\`\`malloy
+##! experimental.givens
+import { order_items, products } from '../storefront.malloy'
+import { CATEGORY, MIN_SALE } from '../givens.malloy'
+
+#" Revenue and margin at a glance, and where they come from.
+# artifact { title="Business Overview" } dashboard { columns=12 }
+query: overview is order_items -> {
+  where: products.category ~ $CATEGORY and sale_price ~ $MIN_SALE
+
+  aggregate:
+    # label="Revenue"
+    # currency
+    # colspan=3
+    total_sales
+    # label="Gross margin"
+    # currency
+    # colspan=3
+    total_margin
+    # label="Orders"
+    # colspan=3
+    order_count
+    # label="Avg order value"
+    # currency
+    # colspan=3
+    avg_order_value
+
+  nest:
+    # break
+    # colspan=6
+    # label="Revenue by month"
+    sales_by_month
+    # colspan=6
+    # label="Revenue by state"
+    sales_by_state
+  nest:
+    # colspan=12
+    # label="Category performance"
+    by_category
+}
+\`\`\`
+
+The \`#"\` line above the tag is a doc comment, and it is the page's description. If you leave \`title=\`
+off the artifact tag, it becomes the title instead, so write it as one, not as a sentence about the
+page. **It belongs to the query, so it only works on this form.** Putting a \`#"\` above a
+model-level \`##\` tag fails the whole package load with "Object annotation not connected to any
+object", and a composite has no description as a result.
+
+**Composite:** a list of views that already exist, each run separately into one grid. The tag is
+model-level (\`##\`) because there is no query of its own to hang a \`#\` tag on.
+
+\`\`\`malloy
+##! experimental.givens
+## artifact { title="Seasonality" tiles=["scoped_sales -> sales_by_month", "scoped_sales -> sales_by_year", "scoped_sales -> seasonality"] dashboard_columns=3 }
+import { scoped_sales } from './_shared.malloy'
+import { products } from '../storefront.malloy'
+import { CATEGORY, SINCE } from '../givens.malloy'
+\`\`\`
+
+A composite has no query, so the filtering it applies must live in what it composes: a source that
+already has the givens applied. Put it in an untagged \`dashboards/_shared.malloy\`, which discovery
+treats as a shared include rather than a dashboard. **It has to apply every given the composite
+imports**: a given the composite imports but nothing references gets no control, silently, at reload
+200 with no warning. Note \`SINCE\` is a \`date\` rather than a \`filter<>\`, so it compares with \`>=\`
+rather than \`~\`. Save the include before you compile the dashboard that imports it, since an importer
+compiled against a sibling that is not on disk fails with an \`import-error\`.
+
+\`\`\`malloy
+##! experimental.givens
+import { order_items } from '../storefront.malloy'
+import { CATEGORY, SINCE } from '../givens.malloy'
+
+source: scoped_sales is order_items extend {
+  where: products.category ~ $CATEGORY and created_at >= $SINCE
+}
+\`\`\`
+
+Its tiles are equal-width (there is no per-tile colspan), and each one takes a single column, so
+**\`dashboard_columns\` is how many tiles you want per row**, not a number of twelfths. Three tiles want
+\`dashboard_columns=3\`. Setting it to 12 out of habit gives you twelve columns and three tiles a
+twelfth of the page wide. Use the single-query form when one tile deserves more room than the others.
+
+**Write \`dashboard_columns=N\` on a composite and \`# dashboard { columns=N }\` on a single query.**
+A composite forgives the mix, since both spellings feed the manifest field it
+lays out from, but **a single query tagged \`dashboard_columns\` silently loses its whole layout**, and
+the manifest reports the count either way: see "Losing the grid". A composite's tiles also keep their
+own field names on their axes and column headers, and the Layout section's remedy, inlining the view,
+is not open to you here: naming existing views is the whole point of the form. \`tiles=\` on a
+single-query artifact tag is dropped the same way, silently.
+
+## Layout: the four tags that make a page line up
+
+This section is the **single-query** form only. A composite has no colspans and counts tiles per row,
+above. Cards and tiles share one grid, so copy this recipe, and use the same count on every
+single-query dashboard in the package so they read as one product:
+
+1. **\`columns=12\`** on the \`# dashboard\` tag. Twelve divides by 2, 3, 4 and 6, so a row is even with
+   three cards or four.
+2. **A \`# colspan\` on every card and tile, summing to 12 per row.** Four cards at 3, three at 4, two
+   tiles at 6, a full-width table at 12. Omit them and every item falls to a single column, a twelfth
+   of the width, which is too narrow for a line chart to draw in at all.
+3. **\`# break\` on the first tile after the cards.** Otherwise it flows into the columns left beside
+   the cards and the next tile wraps. Not needed per row: once a row sums to 12 the next item wraps
+   on its own.
+4. **\`# label="…"\` on every nest and every aggregate**, including the aggregates inside a table
+   nest, whose column headers are field names too. The heading is otherwise the view's or field's
+   name, and a wide table full of \`total_sales\` and \`order_item_count\` is the most visible thing
+   between a rough page and a finished one. A view nested **by name** is the exception: you can label
+   the tile, but its own field names still reach the chart axes and the column headers, so inline it
+   if you want those labelled too.
+
+Then the traps:
+
+- **No \`# size=fill\` on a dashboard tile.** Inside a dashboard it measures against the container the
+  whole grid was handed, not the tile, so it yields a chart thousands of pixels tall. Tiles already
+  size to their colspan.
+- **A KPI card's label is one line that ellipses** rather than wrapping, so a long label in a narrow
+  card is truncated with no other sign. Widen the card or shorten the label.
+- **A ratio needs a number format.** \`order_count / customer_count\` renders as \`10.695\` on a card;
+  \`# number="#,##0.0"\` is the precision it actually carries.
+- **A \`# shape_map\` legend is titled with the measure's field _name_, not its \`# label\`.** Rename it
+  in the view: \`aggregate: revenue is total_sales\`. Renaming drops the measure's own format tags
+  though, so \`# currency\` becomes plain digits unless you re-tag it at the rename. Prefer \`# label=\`
+  anywhere the legend is not the problem.
+- **A series legend sizes itself from the longer of the series label and its widest value**, then
+  truncates both. A 4-character label over 4-digit years clips to \`20…\`; \`# label="Order year"\`
+  instead of \`"Year"\` buys the room. A legend showing \`…\` is this, not a data problem.
+
+The last two are upstream renderer behavior, cheap to work around in the model.
+
+The same tags govern a \`# dashboard\` **view** run in a notebook cell, since both surfaces render
+through the same code, so a view laid out this way looks the same in a cell as on a dashboard page.
+Height is the one thing the surface decides: a single-query dashboard renders at its natural height,
+a composite's tiles are each capped, and in a notebook a chart cell is capped and a table cell hugs
+its rows.
+
+## The rules that actually bite
+
+- **The filename is the dashboard's name:** its URL slug, its listing name, and its \`# drill\`
+  target. The query inside can be called anything, and sometimes must be (a query named \`regions\`
+  collides with an imported \`regions\` source).
+- **Importing a given is what makes it bindable.** Malloy's given namespace is per-file. A given the
+  dashboard file does not import gets no control and cannot be sent to it, even when the \`where:\`
+  that references it lives up an import chain. A composite must import the givens its tiles use.
+- **A suggest's source or query has to resolve in the dashboard file too.** \`suggest { source=products … }\`
+  means the dashboard imports \`products\`.
+- **A model-level \`##\` tag must be on one line.** Wrapping one always breaks it, but how you find
+  out depends on what follows. If the continuation is not valid Malloy you get a compile error. If it
+  happens to be, an \`import\` say, the file compiles clean, quietly stops being a dashboard and
+  becomes a shared include, and only the package warnings tell you. Match on the shape rather than the
+  words: the message may say a tag "does not parse", or was "refused" or "dropped rather than parsed",
+  and on a file that still built it opens "Annotation" rather than "Tag". See "Losing the grid" below.
+- **In a \`# dashboard\` view, fields render by role.** A top-level \`aggregate:\` measure is a KPI card,
+  so do not nest a \`# big_value\` view to get one. Each \`nest:\` is a tile. Give every KPI a
+  \`# label=\`, or the card is headed \`total_sales\`.
+- **Only table cells are marked drillable.** See "Drill".
+
+\`skill:malloy-gotchas-rendering\` covers the renderer tags in depth; \`skill:malloy-charts\` covers
+choosing them.
+
+## Filter controls
+
+Controls come from the \`given:\` declarations the query references, and the tags on the declaration
+are the control contract, declared once and identical on every dashboard and in every notebook that
+uses them:
+
+\`\`\`malloy
+##! experimental.givens
+
+# label="Category" control=select suggest { source=products dimension=category }
+given: CATEGORY :: filter<string> is f''
+
+# label="Brand" control=multiselect suggest { query=brand_suggest dimension=brand }
+given: BRAND :: filter<string> is f''
+
+# label="Minimum line total" range_min=0 range_max=250
+given: MIN_SALE :: filter<number> is f''
+
+# label="Ordered since"
+given: SINCE :: date is @2023-01-01
+\`\`\`
+
+A sixth tag, \`description\`, is part of the contract and has two spellings that do different things:
+\`# description="…"\` publishes to the API but Publisher's own UI does not render it, while
+\`#(description="…")\` renders as helper text under the control but complains about any multi-word
+value, that the prefix "is not a well-formed route", because a route ends at the first space. That
+complaint is a **compile** diagnostic on a compile that still succeeds, not a package warning, so
+step 6 will not show it. Pick by which reader you care about.
+
+\`control=select\`/\`multiselect\` with a \`suggest\` renders a picker filled from the data;
+\`range_min\`/\`range_max\` on a \`filter<number>\` renders a slider; a \`date\` or \`timestamp\` renders a
+date picker. Which controls appear is per-dashboard, decided by which givens the query references.
+\`skill:malloy-modeling\` and \`docs/givens.md\` cover givens themselves.
+
+Two per-dashboard options on the artifact tag:
+
+- \`autorun=false\` batches control changes behind an Apply button. Add it once a page is slow enough
+  that a reader notices two round trips.
+- \`givens { CATEGORY=f'Outerwear' }\` sets starting values, not a redeclaration. A URL parameter wins.
+
+A notebook takes both at the file level, as \`## autorun=false\` and \`## givens { CATEGORY=f'Outerwear' }\`,
+and behaves identically.
+
+## Drill
+
+\`# drill\` goes on a model **dimension**, never on a dashboard:
+
+\`\`\`malloy
+# drill { to=["category", "self"] given=CATEGORY }
+dimension: category is products.category
+\`\`\`
+
+\`to=<slug>\` navigates to that dashboard with the clicked value written into the named given;
+\`to=self\` filters in place; two or more destinations pop a menu.
+
+Declaring it on the dimension is the point: every result that groups by it becomes clickable, in a
+dashboard tile and in a notebook cell alike. So when a view is meant to be drilled, group by the
+tagged dimension. Declaring \`dimension: category is products.category\` and grouping by \`category\`
+gives the identical output field name and the identical numbers, and carries the tag.
+
+**Always write \`given=\`.** Without it the given name is the dimension name **verbatim**, so a
+\`dimension: category\` seeds a given called \`category\` rather than a declared \`given: CATEGORY\`. A
+\`to=self\` survives that, because a surface folds case when it looks up its own given. A \`to=<slug>\`
+does not: it navigates, still looks like it worked, and arrives as \`?category=…\`, which the
+destination drops by exact match, so you land on an unfiltered page. Nothing errors, and the lint
+folds case when it checks, so it stays green too. That silence is specific to a name that folds onto
+a declared given. A \`to=self\` whose name matches nothing at all is caught loudly and is not offered;
+a \`to=<slug>\` is not checked either way.
+
+A drill only lands somewhere useful if the destination declares a control for the given being
+seeded. **No lint checks that.** It verifies that the target slug is a dashboard in the package, and
+for \`to=self\` that some model declares the given, and stops there. Nothing reads the destination's
+own givens, so click it and look.
+
+Cells in a drillable **table** column show it: pointer cursor, and a blue underline on hover. They are
+in the tab order and carry a button role too, so a keyboard reaches them, focus is styled the way
+hover is, and Enter or Space fires the drill. Chart marks get no such affordance in either Publisher
+or Malloyyo, so a dashboard meant to be drilled wants at least one untagged (table) tile. A destination the
+surface cannot honor is not marked and not offered, which is why a \`to=self\` reads as plain text in a
+document that declares no control for its given.
+
+**One thing quietly switches the marking off, per column: another tile rendering a column with the
+same header.** Put a "revenue by category" chart beside a drillable \`category\` table, which is the
+obvious thing to build, and that column's cells stop being marked. Marking matches columns by their
+rendered header text, so a name a non-drillable field also shows is dropped rather than risk painting
+a dead link. Only a **non-drillable** column suppresses: a second tile that groups by the same tagged
+dimension is fine, which is the arrangement the paragraph above already recommends. **Other drillable
+columns on the same page keep their marking**, so counting marked cells will not tell you: look at the
+column you care about. The clicks still work, so this is invisible
+unless you hover. Give the two different headings with \`# label=\`. A transposed table is never marked
+either, for a different reason.
+
+## Losing the grid
+
+A single-query dashboard can come out with its layout wrong in two visibly different ways, and the
+reload is 200 and the manifest reports the column count you asked for in both.
+
+**Not a dashboard at all: one plain nested table**, every \`# colspan\` and \`# break\` dropped. Either
+you tagged a single query with \`dashboard_columns=N\`, which only a composite reads, or a \`f'…'\`
+filter literal in a \`givens { … }\`
+block shares a line with \`# dashboard\`. For the second, put \`# dashboard\` on its own line: writing it
+first on the line does not help, a plain \`'Outerwear'\` or a bare date is fine, and the composite form
+is immune because its layout comes from the manifest rather than a re-parse.
+
+**A dashboard, but nothing lines up**: you wrote \`# colspan\` without \`columns=N\`, so the items flow
+side by side at their natural widths instead of aligning to a grid.
+
+To tell them apart, run the dashboard's own query, \`{"queryName": "<the manifest's query>"}\`, and read
+\`renderLogs\` on the response. Like \`warnings\`, the key is absent when there is nothing to say.
+Single-query dashboards have no \`tiles\` in their manifest, so there is no tile query to run:
+
+| render log | what it means |
+|---|---|
+| \`Unknown render tag 'colspan'\` | the renderer never saw a \`# dashboard\` tag. It does **not** say which of the two causes; check both |
+| \`Ignored # colspan … only applies in columns mode\` | it saw the tag but there is no count |
+
+Neither reaches the package warnings, so step 6 will not show either. A **wrapped \`##\` tag** is the
+one failure in this family that does: the file is absent from the listing and the package warnings
+say "Tag does not parse (Unclosed '{')".
+
+## Read the lint
+
+Package warnings after a reload are the dashboard's test suite. Fix all of them:
+
+- \`# drill … targets "x", which is not a dashboard in this package\`: a dead click.
+- \`to=self, but no model in this package declares a given "X"\`: the clicked value has nowhere to go.
+- \`given "X" suggests options from source "y", which this file does not define\`: the dropdown will
+  be empty, so import it.
+- \`filters by given "X", which this file does not import, so no control is shown for it\`: the trap
+  under "Importing a given is what makes it bindable", which the lint now names for you, with the file
+  to fix.
+- A tile that does not resolve to a real view, or a non-positive \`dashboard_columns\`.
+
+Findings carry a \`severity\`, but \`warn\` is the ordinary default and tells you nothing about how bad
+one is. Read the text, not the severity and not the count. One message is worth recognising because
+it changes what the rest of the list means: **"Dashboard lint stopped early, so this list is
+incomplete"**. A dashboard withheld from \`explores\` also loses its own findings, so a short list for a
+withheld file is not a clean bill of health.
+
+**Read the status the reload itself returns, not the listing.** One dashboard that fails to compile
+fails the whole package load, and the reload answers **424** with the compile error. A package that
+was already serving then keeps serving its previous version, so the listing still answers 200 and
+looks perfectly healthy while your edit has silently not taken effect.
+
+**If you did not catch the 424, \`GET /api/v0/status\` still knows.** A package serving an older model
+than its files appears in \`loadErrors\` with **\`stale: true\`**, the compile message, and the time it
+failed, and the entry clears on the next reload that compiles. That is the one check that works after
+the fact, so make it the first thing you run when a page will not change. A package that never loaded
+at all appears there too, without \`stale\`, and is absent from the listing entirely.
+
+If the reload is 200 and the others are listed but yours is not, discovery skipped the file instead,
+usually a missing or misspelled \`# artifact\` tag, which is the same mechanism that deliberately skips
+an untagged shared include. There is a second cause if the package's \`publisher.json\` carries an
+\`explores\` list: a dashboard whose file is missing from it is withheld rather than served, and the
+warning says so and names the fix. The list is what matters, not the \`queryableSources\` setting, which
+is \`declared\` by default; a package with no \`explores\` list withholds nothing. Where there is one, a
+\`suggest\` source has to be queryable as well as resolvable, so it needs to be on the list too.
+
+**A clean reload is not proof the tags are right.** The checks above read names and resolve them; the
+separate warning for a tag that does not *parse* is syntax only: it carries no
+position and says nothing about a name that does not resolve. It catches *a* malformed tag; its
+absence is not evidence there are none. That is why the last step is opening the page, not reading
+the warning list.
+
+## What "done" means
+
+- Every source, view, and field name came from the model you read in step 1.
+- The reload returned **200**, not 424. A 424 means the page you are about to look at is the old one.
+- The package reloads with **zero** dashboard warnings, and your dashboard is in the listing at all.
+- **The page is a dashboard and its items line up.** This is the check the others cannot make for
+  you: all of them pass both on a page that has become one plain nested table and on a dashboard whose
+  items do not align. See "Losing the grid" for which you have.
+- You opened the page and every tile shows real numbers: not stuck loading, not an error, not an
+  empty state you did not intend.
+- Each control renders as the widget you intended (a select shows options; a slider is a slider),
+  and changing one changes the numbers.
+- If you added a \`# drill\`, you clicked it and landed where you meant to, with the given seeded.
+- On a single-query dashboard, every card and tile carries a colspan, each row's colspans sum to
+  \`columns\`, and the rows end flush with each other. On a composite, the tiles fill the row rather
+  than leaving a gap. Nothing is clipped, no tile is thousands of pixels tall, and no legend or card
+  label ends in \`…\`.
+
+## Reference
+
+- \`docs/dashboards.md\`: the full guide this skill condenses.
+- \`docs/givens.md\`: the givens the controls are generated from.` }, { name: "malloy-debug", description: 'Fix Malloy compile errors and understand error messages. Use when encountering errors in .malloy files, user says "fix this error", "malloy error", "compile error", "syntax error", or sees 20+ cascading errors.', body: `# Debugging Malloy Errors
 
 > **Tool names** are written bare here - \`get_context\`, \`execute_query\`, \`search_malloy_docs\`. The exact prefixed name depends on the host surface; match each against the tools you actually have.
 
@@ -292088,7 +293648,7 @@ view: overview is {
 - **Only seven palette keys take light/dark.** \`background\`, \`tableHeader\`, \`tableHeaderBackground\`, \`tableBody\`, \`tile\`, \`tileTitle\`, and \`mapColor\` each accept a \`.light\` and/or \`.dark\` variant. \`palette.series\`, \`font.family\`, and \`font.size\` are single values shared across modes; a \`.light\`/\`.dark\` on them does nothing.
 - **\`# theme.palette.mapColor.{light,dark}\` recolors choropleths only.** It sets the saturated end of the \`# shape_map\` / \`# segment_map\` gradient (per mode). Rect-mark heatmaps keep their built-in scheme.
 - **\`defaultMode\` and \`allowUserToggle\` are instance-only.** No per-chart annotation controls the light/dark default or the toggle lock; set them in the config \`theme\` block or the editor.
-- **Environment-level theming is not applied yet.** Only the instance theme and the \`# theme.*\` / \`## theme.*\` per-chart annotations take effect today.` }, { name: "malloy-html-data-app-embedding", description: "Embed an in-package HTML data app into a host page or another application, including auto-sizing and auth. Read when embedding a Publisher page via Publisher.embed.", body: '# Embedding an HTML Data App\n\n> `Publisher.embed(selector, { src })` drops a package page into a host page as a sandboxed, auto-resizing iframe. Same-origin embeds authenticate with the browser\'s cookies; cross-origin embeds need a signed token.\n\n## The host-page pattern\n\n```html\n<script src="https://your-publisher/sdk/publisher.js"></script>\n<div id="dashboard"></div>\n<script>\n  const handle = Publisher.embed("#dashboard", {\n    src: "https://your-publisher/environments/demo/packages/sales/index.html",\n  });\n  // handle.destroy() removes the iframe and detaches its listeners.\n</script>\n```\n\n`embed(selector, options)` returns `{ iframe, destroy() }`. Options: `src` (required), `token` (a signed token for cross-origin auth, appended as `embed_token`), `height` (omit to auto-size; a number is treated as pixels), and `allow` (the iframe permissions policy).\n\n## Sizing and the resize contract\n\nOmit `height` and the frame auto-sizes. The embedded page measures its real content height and posts a `publisher:resize` message to the host, which resizes the iframe and accepts that message only from the iframe it created. You write none of this; it ships in `/sdk/publisher.js`, so the embedded page only has to load that script.\n\nDo not rely on `body { min-height: 100vh }` to drive the frame height. The runtime deliberately measures the content\'s bottom edge, not the viewport, to avoid a grow-forever loop.\n\n## Auth\n\n- Same-origin or same-tenant: pass no token. The browser\'s cookies authenticate the iframe.\n- Cross-origin: mint a short-lived signed token server-side and pass it as `options.token`. The runtime appends it to the iframe URL as `embed_token`; the embedded page must read it (from `location.search`) and call `Publisher.setToken(token)`. Because it rides in the URL, it can land in browser history, Referer headers, and server logs, so keep it short-lived and scoped to that one embed, and never put a long-lived or admin token in client HTML.\n\n## Guardrails (v1)\n\n- The iframe is sandboxed (`allow-scripts allow-same-origin allow-forms`). Design for that: no top-level navigation, no popups.\n- Embedded author JavaScript runs with the viewing user\'s data authority, so treat everything under `public/` as strictly first-party code: do not load untrusted third-party scripts, and do not move query results off to other hosts. Tighter per-embed isolation is planned.' }, { name: "malloy-html-data-app-runtime", description: "Write the JavaScript that drives an in-package HTML data app, calling Publisher.query, building queries from filter state, and handling results and errors. Read before writing the page's data code.", body: '# HTML Data App Runtime\n\n> `Publisher.query(modelPath, malloy)` returns an array of plain row objects. Build the Malloy string, let the model do the work, and render the rows with whatever front-end code you like.\n\nThe runtime loads from the root-relative `<script src="/sdk/publisher.js">` and adds one global, `window.Publisher`.\n\n## The query contract\n\n| Call | Returns | Use for |\n|---|---|---|\n| `Publisher.query(modelPath, malloy, opts?)` | `Promise<Array>` of rows | driving your own charts and tables |\n| `Publisher.queryFull(modelPath, malloy, opts?)` | `Promise<MalloyResult>` | handing to `<malloy-render>` |\n\n- `modelPath` is the model FILE path within the package, with `/` separators (`"subscriptions.malloy"`, `"models/events.malloy"`). It is not the source name.\n- `malloy` is any query string, written in standard Malloy. This skill covers only the JavaScript glue, not Malloy syntax.\n- `opts` (all optional): `sourceName`, `queryName`, `givens` (a `{ name: value }` map bound to the model\'s Malloy `given:` runtime parameters for this query; safe parameterization, values are bound by the runtime, not string-interpolated), `filterParams` (values for the model\'s legacy `#(filter)` source filters), `bypassFilters`, and `environment` / `package` (only if the page is served from outside `/environments/<env>/packages/<pkg>/`). `givens` and `filterParams` compose (both apply).\n\n## Structure the app as modules, not one inline script\n\nPast a single tile, an inline `<script>` becomes unmaintainable and untestable. Split the work, and load it without a build step: put your shared libraries first as plain globals, then one ES-module entry point that `import`s your own files.\n\n```html\n<!-- Globals first: the runtime, then any vendored chart library. -->\n<script src="/sdk/publisher.js"></script>\n<script src="./vendor/chart.umd.js"></script>\n<!-- One module entry; it imports the rest. ES modules resolve with no bundler. -->\n<script type="module" src="./app.js"></script>\n```\n\nA separation that keeps each piece testable and changeable on its own:\n\n- **`format.js`**. Pure functions only: number/date formatting, a series-align-by-month helper, status thresholds. No DOM, no globals. This is the file `node --test` can cover directly.\n- **`charts.js`**. Turns a prepared data object into a drawn chart; the only file that touches the chart library.\n- **`tiles.js`**. Your tiles as *data*: for each, its model/source/view (and target source, if any), plus a pure `build(rows)` that shapes query rows for the chart. This is the single source of truth for what each tile queries.\n- **`app.js`**. The thin entry point: reads `tiles.js`, runs the queries, wires results to the DOM. Adding a tile means adding a `tiles.js` entry, not editing `app.js`.\n\nDeclare each tile\'s source and view names once, in `tiles.js`, and have everything else (render code, any agent prompt, tests) read from there. A second copy of those names in another file is the classic drift bug, and a *derived* name (`okr_4_4_2_targets` invented from a tile code) is simply wrong: a target source may have an irregular name or not exist at all. Read the model; don\'t compute names.\n\n## Patterns that work\n\nThese run against the example `html-data-app` package (source `subscriptions`; views `plan_mix`, `mrr_by_industry`, `kpis`). Swap in your own model and view names.\n\nRun a named view:\n\n```js\nconst rows = await Publisher.query("subscriptions.malloy", "run: subscriptions -> plan_mix");\n```\n\nRefine a view from UI state by appending a `where:`. Restrict the values to ones you control (for example a dropdown populated from the model\'s own distinct values) and escape each interpolated value with a backslash before quotes and backslashes (Malloy rejects the SQL-style `\'\'` doubling). An unescaped apostrophe in a value breaks out of the literal:\n\n```js\nfunction whereClause(state) {\n  const q = (s) => s.replace(/\\\\/g, "\\\\\\\\").replace(/\'/g, "\\\\\'"); // backslash-escape for Malloy\n  const parts = [];\n  if (state.plan) parts.push(`plan = \'${q(state.plan)}\'`);\n  if (state.industry) parts.push(`industry = \'${q(state.industry)}\'`);\n  return parts.length ? `where: ${parts.join(", ")}` : "";\n}\nconst rows = await Publisher.query(\n  "subscriptions.malloy",\n  `run: subscriptions -> plan_mix + { ${whereClause(state)} }`,\n);\n```\n\nDo not interpolate free-text or otherwise untrusted input into the query string. Route parameterized input through `opts.givens` (or the legacy `opts.filterParams`) instead: those values are bound by the runtime as typed parameters, not string-interpolated, so they can\'t inject query syntax. (One nuance: a `filter<T>`-typed given takes Malloy filter syntax as its value, so validate it against a known set like any other input; scalar givens carry no syntax at all.) `opts.givens` is safe *parameterization*, not an authorization boundary: a client-supplied given is client-trusted unless a server upstream (a trusted gateway, or an operator\'s per-package config) strips or finalizes it. Where you must build query text from input, constrain it to a known set and escape it, or keep the filtering in model-defined views.\n\nKPI or single-row view. Destructure element zero:\n\n```js\nconst [kpis] = await Publisher.query("subscriptions.malloy", "run: subscriptions -> kpis");\nel.textContent = kpis.active_mrr;   // the result is an array; kpis.active_mrr, not rows.active_mrr\n```\n\nRefresh a dashboard. Fire the tiles together:\n\n```js\nconst [planMix, byIndustry, kpisRows] = await Promise.all([\n  Publisher.query("subscriptions.malloy", "run: subscriptions -> plan_mix"),\n  Publisher.query("subscriptions.malloy", "run: subscriptions -> mrr_by_industry"),\n  Publisher.query("subscriptions.malloy", "run: subscriptions -> kpis"),\n]);\n```\n\nPrefer defining the views in the model (one per tile, pre-aggregated and sorted) over building long query strings in JS.\n\nGet the numbers right. The fastest way to ship a wrong-but-convincing dashboard is to paper over missing data:\n\n- **Missing is not zero.** When you join two series (actuals to a separately-keyed target) and a key is absent, leave it `null` so the chart skips it. Do not `|| 0`, which plots a real-looking zero and reads as "we hit nothing that month." Align on a normalized key (`"YYYY-MM"`), and let the renderer omit null points:\n\n  ```js\n  // monthKey/monthLabel are your own format.js helpers: monthKey normalizes a\n  // date to a "YYYY-MM" string; monthLabel formats it for display.\n  // target may not cover every actual month; an absent month stays null, never 0.\n  const target = new Map(planRows.map((r) => [monthKey(r.plan_month), Number(r.target_revenue)]));\n  const data = actualRows.map((r) => ({\n    label: monthLabel(r.order_month),\n    actual: Number(r.revenue),\n    target: target.has(monthKey(r.order_month)) ? target.get(monthKey(r.order_month)) : null,\n  }));\n  ```\n\n- **"Current" means latest non-null.** For a KPI scorecard, scan back to the last month that actually has data rather than reading the final row, which may be an incomplete current month.\n- **Guard division in Malloy, not after.** `avg(paid / nullif(active, 0))`. A `nullif` in the query beats catching `Infinity`/`NaN` in JS.\n- **Convert units explicitly.** If the model stores a 0 to 1 fraction and you show a percent, multiply once in `build()` and comment it. Mismatched units are a silent off-by-100.\n\nLoading, empty, and error states. Handle all three; a bare `.then()` that assumes rows leaves the page blank when the query is slow or fails:\n\n```js\nconst el = document.getElementById("out");\nel.textContent = "Loading...";\nPublisher.query("subscriptions.malloy", "run: subscriptions -> plan_mix")\n  .then((rows) => {\n    if (!rows.length) { el.textContent = "No data."; return; }\n    render(rows);\n  })\n  .catch((err) => {\n    el.textContent = `Query failed (${err.status ?? ""}): ${err.response?.message ?? err.message}`;\n  });\n```\n\nRender through `<malloy-render>`. `queryFull` returns the full Malloy result envelope (the JSON form of the server\'s result, not a live result object) to hand to the component:\n\n```js\nconst el = document.querySelector("malloy-render");\nel.result = await Publisher.queryFull("subscriptions.malloy", "run: subscriptions -> plan_mix");\n```\n\nPublisher does not serve or bundle `<malloy-render>`; you must obtain a built component bundle matched to your model\'s Malloy version and vendor it into `public/` yourself, then confirm it accepts the envelope as-is. The shipped example renders rows with a plain chart library instead, so this path is not exercised there. A view tagged in the model (for example `# bar_chart`) drives how it draws.\n\nValidate every query before wiring it into render code, using whatever query tool your environment provides, or by POSTing the query to a running Publisher at `/api/v0/environments/<env>/packages/<pkg>/models/<modelPath>/query` with body `{"compactJson":true,"query":"..."}`, or by running `Publisher.query` once and logging the rows. Malloy names result columns after the `group_by` / `aggregate` field names (`group_by: plan` gives a `plan` column; `aggregate: account_count` gives an `account_count` column), so confirm those names against real output before you read them.\n\nIf you validate the rendered page in a headless browser (Playwright or Puppeteer), do not wait for network idle: `publisher.js` holds the live-reload SSE stream open, so the page never reaches it. Wait on `domcontentloaded` or `load` plus a content selector instead.\n\n## Context, auth, live reload (all automatic)\n\n- Context. A page served under `/environments/<env>/packages/<pkg>/...` infers its environment and package, so `query` needs no env or package args. Serving from elsewhere? Pass `opts.environment` and `opts.package`.\n- Auth. By default the runtime sends cookies (`credentials: include`), so a signed-in user is authenticated with no code. For a bearer token, call `Publisher.setToken(token)` first; `Publisher.setToken(null)` reverts to cookies.\n- Live reload. Under `--watch-env`, the page reloads on package changes by itself. Nothing to wire.\n\n## When the app fails\n\n| Symptom | Likely cause and fix |\n|---|---|\n| 404 or "model not found" | `modelPath` wrong. It is the file path (`"subscriptions.malloy"`), with `/` separators, not the source name. |\n| "source/view not defined" | View or source name guessed. Read the model (your environment\'s context tool, or open the `.malloy` file) and use the real names. |\n| Promise rejects, message starts `Publisher.query:` | Read `error.status` and `error.response` for the server\'s reason (compile error, missing required parameter, permission). |\n| Empty array when you expect rows | Filter value mismatch (case, spelling, type, or a non-ASCII character like `≤` or an en-dash in the literal). Copy the literal verbatim from the model, do not retype the user\'s paraphrase, and confirm it with a distinct-values query (`run: src -> { group_by: the_dimension }`). Quote strings, use `@` for dates. |\n| 400 on a given (ungated source) | An unknown given name (check spelling; names are case-sensitive), a required given left unset, or a value that doesn\'t fit the declared type. Malloy rejects it when preparing the query; supply declared givens via `opts.givens` with the right shape (see the givens type table). |\n| 403 on a query that should be allowed, when passing givens to a gated source | On a source with `#(authorize)`, a bad given (unknown name or wrong-typed value) fails closed in the authorize check, so it looks like access denied rather than validation. Check the given names and values against the model. |\n| KPI shows `undefined` | The result is an array. Read `rows[0].field` (or destructure `const [k] = ...`), not `rows.field`. |\n| Page loads in dev but is not listed or not served | The file is not under the package\'s `public/` directory. Publisher serves only `public/`; a page written anywhere else (for example `/tmp`) is never reachable at `/environments/<env>/packages/<pkg>/<file>`. |\n| Queries fail only when embedded cross-origin | Cookies are not sent cross-site. Serve same-origin, or pass a bearer token. |\n| No live reload | Watch mode is off. Start with `--watch-env <env>`; without it the events stream reports `mode: disabled` and never reloads. |' }, { name: "malloy-html-data-apps", description: "Build or modify an in-package HTML data app for a Malloy Publisher package (a public/ directory the package serves). Use when the user wants a hand-authored HTML dashboard or web page backed by a package's Malloy models, with no build step.", body: `# In-Package HTML Data Apps
+- **Environment-level theming is not applied yet.** Only the instance theme and the \`# theme.*\` / \`## theme.*\` per-chart annotations take effect today.` }, { name: "malloy-html-data-app-embedding", description: "Embed an in-package HTML data app into a host page or another application, including auto-sizing and auth. Read when embedding a Publisher page via Publisher.embed.", body: '# Embedding an HTML Data App\n\n> `Publisher.embed(selector, { src })` drops a package page into a host page as a sandboxed, auto-resizing iframe. Same-origin embeds authenticate with the browser\'s cookies; cross-origin embeds need a signed token.\n\n## The host-page pattern\n\n```html\n<script src="https://your-publisher/sdk/publisher.js"></script>\n<div id="dashboard"></div>\n<script>\n  const handle = Publisher.embed("#dashboard", {\n    src: "https://your-publisher/environments/demo/packages/sales/index.html",\n  });\n  // handle.destroy() removes the iframe and detaches its listeners.\n</script>\n```\n\n`embed(selector, options)` returns `{ iframe, destroy() }`. Options: `src` (required), `token` (a signed token for cross-origin auth, appended as `embed_token`), `height` (omit to auto-size; a number is treated as pixels), and `allow` (the iframe permissions policy).\n\n## Sizing and the resize contract\n\nOmit `height` and the frame auto-sizes. The embedded page measures its real content height and posts a `publisher:resize` message to the host, which resizes the iframe and accepts that message only from the iframe it created. You write none of this; it ships in `/sdk/publisher.js`, so the embedded page only has to load that script.\n\nDo not rely on `body { min-height: 100vh }` to drive the frame height. The runtime deliberately measures the content\'s bottom edge, not the viewport, to avoid a grow-forever loop.\n\n## Auth\n\n- Same-origin or same-tenant: pass no token. The browser\'s cookies authenticate the iframe.\n- Cross-origin: mint a short-lived signed token server-side and pass it as `options.token`. The runtime appends it to the iframe URL as `embed_token`; the embedded page must read it (from `location.search`) and call `Publisher.setToken(token)`. Because it rides in the URL, it can land in browser history, Referer headers, and server logs, so keep it short-lived and scoped to that one embed, and never put a long-lived or admin token in client HTML.\n\n## Guardrails (v1)\n\n- The iframe is sandboxed (`allow-scripts allow-same-origin allow-forms`). Design for that: no top-level navigation, no popups.\n- Embedded author JavaScript runs with the viewing user\'s data authority, so treat everything under `public/` as strictly first-party code: do not load untrusted third-party scripts, and do not move query results off to other hosts. Tighter per-embed isolation is planned.' }, { name: "malloy-html-data-app-runtime", description: "Write the JavaScript that drives an in-package HTML data app, calling Publisher.query, building queries from filter state, and handling results and errors. Read before writing the page's data code.", body: '# HTML Data App Runtime\n\n> `Publisher.query(modelPath, malloy)` returns an array of plain row objects. Build the Malloy string, let the model do the work, and render the rows with whatever front-end code you like.\n\nThe runtime loads from the root-relative `<script src="/sdk/publisher.js">` and adds one global, `window.Publisher`.\n\n## The query contract\n\n| Call | Returns | Use for |\n|---|---|---|\n| `Publisher.query(modelPath, malloy, opts?)` | `Promise<Array>` of rows | driving your own charts and tables |\n| `Publisher.queryFull(modelPath, malloy, opts?)` | `Promise<MalloyResult>` | handing to `<malloy-render>` |\n\n- `modelPath` is the model FILE path within the package, with `/` separators (`"subscriptions.malloy"`, `"models/events.malloy"`). It is not the source name.\n- `malloy` is any query string, written in standard Malloy. This skill covers only the JavaScript glue, not Malloy syntax.\n- `opts` (all optional): `sourceName`, `queryName` (`queryName` runs a saved query, with `sourceName` qualifying the source a view hangs off; `sourceName` on its own is a 400), `givens` (a `{ name: value }` map bound to the model\'s Malloy `given:` runtime parameters for this query; safe parameterization, values are bound by Publisher server-side, not string-interpolated), `filterParams` (values for the model\'s legacy `#(filter)` source filters), `bypassFilters`, and `environment` / `package` (only if the page is served from outside `/environments/<env>/packages/<pkg>/`). `givens` and `filterParams` compose (both apply).\n\n## Structure the app as modules, not one inline script\n\nPast a single tile, an inline `<script>` becomes unmaintainable and untestable. Split the work, and load it without a build step: put your shared libraries first as plain globals, then one ES-module entry point that `import`s your own files.\n\n```html\n<!-- Globals first: the runtime, then any vendored chart library. -->\n<script src="/sdk/publisher.js"></script>\n<script src="./vendor/chart.umd.js"></script>\n<!-- One module entry; it imports the rest. ES modules resolve with no bundler. -->\n<script type="module" src="./app.js"></script>\n```\n\nA separation that keeps each piece testable and changeable on its own:\n\n- **`format.js`**. Pure functions only: number/date formatting, a series-align-by-month helper, status thresholds. No DOM, no globals. This is the file `node --test` can cover directly.\n- **`charts.js`**. Turns a prepared data object into a drawn chart; the only file that touches the chart library.\n- **`tiles.js`**. Your tiles as *data*: for each, its model/source/view (and target source, if any), plus a pure `build(rows)` that shapes query rows for the chart. This is the single source of truth for what each tile queries.\n- **`app.js`**. The thin entry point: reads `tiles.js`, runs the queries, wires results to the DOM. Adding a tile means adding a `tiles.js` entry, not editing `app.js`.\n\nDeclare each tile\'s source and view names once, in `tiles.js`, and have everything else (render code, any agent prompt, tests) read from there. A second copy of those names in another file is the classic drift bug, and a *derived* name (`okr_4_4_2_targets` invented from a tile code) is simply wrong: a target source may have an irregular name or not exist at all. Read the model; don\'t compute names.\n\n## Patterns that work\n\nThese assume a `subscriptions.malloy` model whose `subscriptions` source defines the views `plan_mix`, `mrr_by_industry`, and `kpis`. The names are illustrative; swap in your own model and view names.\n\nRun a named view:\n\n```js\nconst rows = await Publisher.query("subscriptions.malloy", "run: subscriptions -> plan_mix");\n```\n\nRefine a view from UI state by appending a `where:`. Restrict the values to ones you control (for example a dropdown populated from the model\'s own distinct values) and escape each interpolated value with a backslash before quotes and backslashes (Malloy rejects the SQL-style `\'\'` doubling). An unescaped apostrophe in a value breaks out of the literal:\n\n```js\nfunction whereClause(state) {\n  const q = (s) => s.replace(/\\\\/g, "\\\\\\\\").replace(/\'/g, "\\\\\'"); // backslash-escape for Malloy\n  const parts = [];\n  if (state.plan) parts.push(`plan = \'${q(state.plan)}\'`);\n  if (state.industry) parts.push(`industry = \'${q(state.industry)}\'`);\n  return parts.length ? `where: ${parts.join(", ")}` : "";\n}\nconst rows = await Publisher.query(\n  "subscriptions.malloy",\n  `run: subscriptions -> plan_mix + { ${whereClause(state)} }`,\n);\n```\n\nDo not interpolate free-text or otherwise untrusted input into the query string. Route parameterized input through `opts.givens` (or the legacy `opts.filterParams`) instead: Publisher binds those values server-side as typed parameters, so they are never concatenated into query text and can\'t inject query syntax. (One nuance: a `filter<T>`-typed given takes Malloy filter syntax as its value, so validate it against a known set like any other input; scalar givens carry no syntax at all.) `opts.givens` is safe *parameterization*, not an authorization boundary: a client-supplied given is client-trusted unless a trusted tier upstream sets it from verified identity. Publisher has no per-package control that strips or finalizes one; identity-bound givens are a planned milestone, not a shipped feature. Where you must build query text from input, constrain it to a known set and escape it, or keep the filtering in model-defined views.\n\nKPI or single-row view. Destructure element zero:\n\n```js\nconst [kpis] = await Publisher.query("subscriptions.malloy", "run: subscriptions -> kpis");\nel.textContent = kpis.active_mrr;   // the result is an array; kpis.active_mrr, not rows.active_mrr\n```\n\nRefresh a dashboard. Fire the tiles together:\n\n```js\nconst [planMix, byIndustry, kpisRows] = await Promise.all([\n  Publisher.query("subscriptions.malloy", "run: subscriptions -> plan_mix"),\n  Publisher.query("subscriptions.malloy", "run: subscriptions -> mrr_by_industry"),\n  Publisher.query("subscriptions.malloy", "run: subscriptions -> kpis"),\n]);\n```\n\nPrefer defining the views in the model (one per tile, pre-aggregated and sorted) over building long query strings in JS.\n\nGet the numbers right. The fastest way to ship a wrong-but-convincing dashboard is to paper over missing data:\n\n- **Missing is not zero.** When you join two series (actuals to a separately-keyed target) and a key is absent, leave it `null` so the chart skips it. Do not `|| 0`, which plots a real-looking zero and reads as "we hit nothing that month." Align on a normalized key (`"YYYY-MM"`), and let the renderer omit null points:\n\n  ```js\n  // monthKey/monthLabel are your own format.js helpers: monthKey normalizes a\n  // date to a "YYYY-MM" string; monthLabel formats it for display.\n  // target may not cover every actual month; an absent month stays null, never 0.\n  const target = new Map(planRows.map((r) => [monthKey(r.plan_month), Number(r.target_revenue)]));\n  const data = actualRows.map((r) => ({\n    label: monthLabel(r.order_month),\n    actual: Number(r.revenue),\n    target: target.has(monthKey(r.order_month)) ? target.get(monthKey(r.order_month)) : null,\n  }));\n  ```\n\n- **"Current" means latest non-null.** For a KPI scorecard, scan back to the last month that actually has data rather than reading the final row, which may be an incomplete current month.\n- **Guard division in Malloy, not after.** `avg(paid / nullif(active, 0))`. A `nullif` in the query beats catching `Infinity`/`NaN` in JS.\n- **Convert units explicitly.** If the model stores a 0 to 1 fraction and you show a percent, multiply once in `build()` and comment it. Mismatched units are a silent off-by-100.\n\nLoading, empty, and error states. Handle all three; a bare `.then()` that assumes rows leaves the page blank when the query is slow or fails:\n\n```js\nconst el = document.getElementById("out");\nel.textContent = "Loading...";\nPublisher.query("subscriptions.malloy", "run: subscriptions -> plan_mix")\n  .then((rows) => {\n    if (!rows.length) { el.textContent = "No data."; return; }\n    render(rows);\n  })\n  .catch((err) => {\n    el.textContent = `Query failed (${err.status ?? ""}): ${err.response?.message ?? err.message}`;\n  });\n```\n\nRender through `<malloy-render>`. `queryFull` returns the full Malloy result envelope (the JSON form of the server\'s result, not a live result object) to hand to the component:\n\n```js\nconst el = document.querySelector("malloy-render");\nel.result = await Publisher.queryFull("subscriptions.malloy", "run: subscriptions -> plan_mix");\n```\n\nPublisher does not serve or bundle `<malloy-render>`; you must obtain a built component bundle matched to your model\'s Malloy version and vendor it into `public/` yourself, then confirm it accepts the envelope as-is. The `storefront` example draws with Chart.js and has no `<malloy-render>` element in its pages, so the component itself is not exercised there. A view tagged in the model (for example `# bar_chart`) drives how it draws.\n\nValidate every query before wiring it into render code, using whatever query tool your environment provides, or by POSTing the query to a running Publisher at `/api/v0/environments/<env>/packages/<pkg>/models/<modelPath>/query` with body `{"compactJson":true,"query":"..."}`, or by running `Publisher.query` once and logging the rows. Malloy names result columns after the `group_by` / `aggregate` field names (`group_by: plan` gives a `plan` column; `aggregate: account_count` gives an `account_count` column), so confirm those names against real output before you read them.\n\nIf you validate the rendered page in a headless browser (Playwright or Puppeteer), do not wait for network idle: `publisher.js` holds the live-reload SSE stream open, so the page never reaches it. Wait on `domcontentloaded` or `load` plus a content selector instead.\n\n## Context, auth, live reload (all automatic)\n\n- Context. A page served under `/environments/<env>/packages/<pkg>/...` infers its environment and package, so `query` needs no env or package args. Serving from elsewhere? Pass `opts.environment` and `opts.package`.\n- Auth. By default the runtime sends cookies (`credentials: include`), so a signed-in user is authenticated with no code. For a bearer token, call `Publisher.setToken(token)` first; `Publisher.setToken(null)` reverts to cookies.\n- Live reload. Under `--watch-env`, the page reloads on package changes by itself. Nothing to wire.\n\n## When the app fails\n\n| Symptom | Likely cause and fix |\n|---|---|\n| 404 or "model not found" | `modelPath` wrong. It is the file path (`"subscriptions.malloy"`), with `/` separators, not the source name. |\n| "source/view not defined" | View or source name guessed. Read the model (your environment\'s context tool, or open the `.malloy` file) and use the real names. |\n| Promise rejects, message starts `Publisher.query:` | Read `error.status` and `error.response` for the server\'s reason (compile error, missing required parameter, permission). |\n| Empty array when you expect rows | Filter value mismatch (case, spelling, type, or a non-ASCII character like `≤` or an en-dash in the literal). Copy the literal verbatim from the model, do not retype the user\'s paraphrase, and confirm it with a distinct-values query (`run: src -> { group_by: the_dimension }`). Quote strings, use `@` for dates. |\n| 400 on a given (ungated source) | An unknown given name (check spelling; names are case-sensitive), a required given left unset, or a value that doesn\'t fit the declared type. Malloy rejects it when preparing the query; supply declared givens via `opts.givens` with the right shape (see the givens type table). |\n| 403 on a query that should be allowed, when passing givens to a gated source | On a source with `#(authorize)`, a bad given (unknown name or wrong-typed value) fails closed in the authorize check, so it looks like access denied rather than validation. Check the given names and values against the model. |\n| KPI shows `undefined` | The result is an array. Read `rows[0].field` (or destructure `const [k] = ...`), not `rows.field`. |\n| Page loads in dev but is not listed or not served | The file is not under the package\'s `public/` directory. Publisher serves only `public/`; a page written anywhere else (for example `/tmp`) is never reachable at `/environments/<env>/packages/<pkg>/<file>`. |\n| Queries fail only when embedded cross-origin | Cookies are not sent cross-site. Serve same-origin, or pass a bearer token. |\n| No live reload | Watch mode is off. Start with `--watch-env <env>`; without it the events stream reports `mode: disabled` and never reloads. |' }, { name: "malloy-html-data-apps", description: "Build or modify an in-package HTML data app for a Malloy Publisher package (a public/ directory the package serves). Use when the user wants a hand-authored HTML dashboard or web page backed by a package's Malloy models, with no build step.", body: `# In-Package HTML Data Apps
 
 > A package becomes a web app by adding a \`public/\` directory. Publisher serves those files and gives the page \`Publisher.query(...)\` to run Malloy against the package's models. No build step, no npm, no framework.
 
@@ -292126,7 +293686,7 @@ The agent orchestrates these. Each query and chart step hands off to a focused s
 1. READ THE MODEL FIRST. Get the model's real source and view names, through your environment's context tool if it has one, or by opening the \`.malloy\` file directly. Never guess field or view names.
 2. SCAFFOLD the package (template below).
 3. WRITE THE QUERIES with \`skill:malloy-html-data-app-runtime\`. Validate each before pasting it into the page, using whatever query tool your environment provides or a running Publisher (see \`skill:malloy-html-data-app-runtime\`). Malloy syntax questions go to \`skill:malloy-queries\`.
-4. CHOOSE CHARTS with \`skill:malloy-charts\` when rendering through \`<malloy-render>\`; otherwise it is your own chart library drawing the returned rows. Vendor any chart library into \`public/\` and load it locally, not from a CDN. Two reasons: embedded author JavaScript runs with the viewing user's data authority, and a blocked CDN (agent sandboxes and many corporate networks block them) is easy to miss, because the script never runs and the charts come up empty. The \`html-data-app\` and \`storefront\` examples both ship their chart library in \`public/vendor/\` and load it from \`public/index.html\` as \`./vendor/chart.umd.js\`. Copy that, but resolve the path against the page's own directory: a page in a subdirectory (\`public/reports/index.html\`) needs \`../vendor/chart.umd.js\`. A wrong relative path 404s and leaves the charts blank, which is the failure you are trying to avoid.
+4. CHOOSE CHARTS with \`skill:malloy-charts\` when rendering through \`<malloy-render>\`; otherwise it is your own chart library drawing the returned rows. Vendor any chart library into \`public/\` and load it locally, not from a CDN. Two reasons: embedded author JavaScript runs with the viewing user's data authority, and a blocked CDN (agent sandboxes and many corporate networks block them) is easy to miss, because the script never runs and the charts come up empty. The \`storefront\` example ships its chart library in \`public/vendor/\` and loads it from \`public/index.html\` as \`./vendor/chart.umd.js\`. Copy that, but resolve the path against the page's own directory: a page in a subdirectory (\`public/reports/index.html\`) needs \`../vendor/chart.umd.js\`. A wrong relative path 404s and leaves the charts blank, which is the failure you are trying to avoid.
 5. EMBED (optional) with \`skill:malloy-html-data-app-embedding\`.
 6. PREVIEW with the local authoring loop (below).
 7. VERIFY before you call it done (see "What 'done' means" below). This step is not optional.
@@ -292163,7 +293723,7 @@ You are building for someone who cannot tell a correct dashboard from a broken o
 { "name": "my-package", "version": "0.0.1", "description": "..." }
 \`\`\`
 
-\`public/index.html\` is a NEW file you create (make the \`public/\` directory if it does not exist). Load the runtime root-relative, then query. The examples below use the shipped \`html-data-app\` package (source \`subscriptions\`); swap in your own model and a view it defines.
+\`public/index.html\` is a NEW file you create (make the \`public/\` directory if it does not exist). Load the runtime root-relative, then query. The examples below assume a \`subscriptions.malloy\` model with a \`subscriptions\` source; the names are illustrative, so swap in your own model and a view it defines.
 
 Start with the smallest page that proves the wiring, dumping the rows:
 
@@ -297623,7 +299183,12 @@ var ASSET_EXTENSIONS = new Set([
   "woff2",
   "xlsx"
 ]);
-var SPA_OWNED_SEGMENTS = new Set(["data-apps", "pages", "workbook"]);
+var SPA_OWNED_SEGMENTS = new Set([
+  "dashboards",
+  "data-apps",
+  "pages",
+  "workbook"
+]);
 function extensionOf(segment) {
   const dot = segment.lastIndexOf(".");
   if (dot <= 0 || dot === segment.length - 1)
@@ -297772,6 +299337,7 @@ var memoryGovernor = memoryGovernorConfig ? new PackageMemoryGovernor(memoryGove
 memoryGovernor?.start();
 environmentStore.setMemoryGovernor(memoryGovernor);
 var packageController = new PackageController(environmentStore);
+var dashboardController = new DashboardController(environmentStore);
 var databaseController = new DatabaseController(environmentStore);
 var queryController = new QueryController(environmentStore);
 var compileController = new CompileController(environmentStore);
@@ -298487,6 +300053,32 @@ app.get(`${API_PREFIX2}/environments/:environmentName/packages/:packageName/mode
     res.status(status).json(json);
   }
 });
+app.get(`${API_PREFIX2}/environments/:environmentName/packages/:packageName/dashboards`, async (req, res) => {
+  if (req.query.versionId) {
+    setVersionIdError2(res);
+    return;
+  }
+  try {
+    res.status(200).json(await dashboardController.listDashboards(req.params.environmentName, req.params.packageName));
+  } catch (error) {
+    logger.error(error);
+    const { json, status } = internalErrorToHttpError(error);
+    res.status(status).json(json);
+  }
+});
+app.get(`${API_PREFIX2}/environments/:environmentName/packages/:packageName/dashboards/:dashboardName`, async (req, res) => {
+  if (req.query.versionId) {
+    setVersionIdError2(res);
+    return;
+  }
+  try {
+    res.status(200).json(await dashboardController.getDashboard(req.params.environmentName, req.params.packageName, req.params.dashboardName));
+  } catch (error) {
+    logger.error(error);
+    const { json, status } = internalErrorToHttpError(error);
+    res.status(status).json(json);
+  }
+});
 app.get(`${API_PREFIX2}/environments/:environmentName/packages/:packageName/notebooks`, async (req, res) => {
   if (req.query.versionId) {
     setVersionIdError2(res);