@malloy-publisher/server 0.8.1 → 0.8.2

package/dist/server.mjs

@@ -176433,6 +176433,15 @@ function internalErrorToHttpError(error) {
     return httpError(404, error.message);
   } else if (error instanceof NotQueryableError) {
     return httpError(404, error.message);
+  } else if (error instanceof QueryCompileError) {
+    return {
+      status: 400,
+      json: {
+        code: 400,
+        message: error.message,
+        problems: error.problems.map(toQueryTextProblem)
+      }
+    };
   } else if (error instanceof MalloyError) {
     return httpError(400, error.message);
   } else if (error instanceof TableNotFoundError) {
@@ -176491,7 +176500,15 @@ function httpError(code, message, reason) {
     }
   };
 }
-var GENERIC_INTERNAL_MESSAGE = "Internal server error.", GENERIC_UPSTREAM_MESSAGE = "Upstream connection error.", MAX_LOGGED_DETAIL_CHARS = 2000, NotImplementedError, BadRequestError, InvalidArgumentError, CompileRefusedError, EnvironmentNotFoundError, PackageNotFoundError, ModelNotFoundError, DashboardNotFoundError, ConnectionNotFoundError, TableNotFoundError, ConnectionError, DestinationNotFoundError, ConnectionAuthError, UnsupportedCatalogFormatError, ModelCompilationError, PackageManifestError, MaterializationEligibilityError, PublisherConfigError, FrozenConfigError, AccessDeniedError, NotQueryableError, OffSurfaceError, MaterializationNotFoundError, MaterializationConflictError, WriteConflictError, WriteRolledBackError, InvalidStateTransitionError, ServiceUnavailableError, PayloadTooLargeError, ResponseUnserializableError, QueryTimeoutError;
+function toQueryTextProblem(problem) {
+  return {
+    message: problem.message,
+    severity: problem.severity,
+    code: problem.code,
+    ...problem.at ? { at: { range: problem.at.range } } : {}
+  };
+}
+var GENERIC_INTERNAL_MESSAGE = "Internal server error.", GENERIC_UPSTREAM_MESSAGE = "Upstream connection error.", MAX_LOGGED_DETAIL_CHARS = 2000, NotImplementedError, BadRequestError, InvalidArgumentError, CompileRefusedError, EnvironmentNotFoundError, PackageNotFoundError, ModelNotFoundError, DashboardNotFoundError, ConnectionNotFoundError, TableNotFoundError, ConnectionError, DestinationNotFoundError, ConnectionAuthError, UnsupportedCatalogFormatError, ModelCompilationError, PackageManifestError, MaterializationEligibilityError, PublisherConfigError, FrozenConfigError, AccessDeniedError, QueryCompileError, NotQueryableError, OffSurfaceError, MaterializationNotFoundError, MaterializationConflictError, WriteConflictError, WriteRolledBackError, InvalidStateTransitionError, ServiceUnavailableError, PayloadTooLargeError, ResponseUnserializableError, QueryTimeoutError;
 var init_errors = __esm(() => {
   init_constants();
   init_logger();
@@ -176598,6 +176615,12 @@ var init_errors = __esm(() => {
       this.name = "AccessDeniedError";
     }
   };
+  QueryCompileError = class QueryCompileError extends MalloyError {
+    constructor(message, problems) {
+      super(message, problems);
+      this.name = "QueryCompileError";
+    }
+  };
   NotQueryableError = class NotQueryableError extends Error {
     constructor(message) {
       super(message);
@@ -265368,6 +265391,690 @@ var require_src139 = __commonJS((exports) => {
   } });
 });
 
+// src/service/query_text.ts
+import { ParseUtil } from "@malloydata/malloy-tag";
+function extractRunTargetSourceName(query) {
+  return extractRunTargetSourceNames(query).at(-1);
+}
+function extractRunTargetSourceNames(query) {
+  if (!query)
+    return [];
+  const tokens = tokenize(stripMalloyCommentsAndLiterals(query));
+  const targets = [];
+  for (let k = 0;k + 1 < tokens.count; k++) {
+    if (!isWord(tokens, k, "run") || !textIs(tokens, k + 1, ":"))
+      continue;
+    let j = k + 2;
+    while (textIs(tokens, j, "(") && tokens.kind[j] === PUNCT)
+      j++;
+    if (isName(tokens, j))
+      targets.push(textOf(tokens, j));
+  }
+  if (targets.length > 0)
+    return targets;
+  for (let k = 0;k + 2 < tokens.count; k++) {
+    if (isName(tokens, k) && textIs(tokens, k + 1, "-") && textIs(tokens, k + 2, ">") && tokens.start[k + 2] === tokens.start[k + 1] + 1 && opensLine(tokens, k)) {
+      return [textOf(tokens, k)];
+    }
+  }
+  return [];
+}
+function opensLine(tokens, k) {
+  if (k === 0)
+    return true;
+  const from = tokens.end[k - 1];
+  const to = tokens.start[k];
+  for (let at = from;at < to; at++) {
+    const code = tokens.source.charCodeAt(at);
+    if (code === 10 || code === 13)
+      return true;
+  }
+  return false;
+}
+function malloyIdentifiers(text) {
+  return [...scanIdentifiers(stripMalloyCommentsAndLiterals(text))];
+}
+function buildSourceAliasMap(query) {
+  const aliasOf = new Map;
+  readDefinitions(query, (keyword, name, base) => {
+    if (keyword === "source" && base !== UNREADABLE_BASE) {
+      aliasOf.set(name, base);
+    }
+  });
+  return aliasOf;
+}
+function stripMalloyCommentsAndLiterals(text) {
+  if (typeof text !== "string")
+    throw new TypeError("query text must be a string");
+  const parts = [];
+  let copied = 0;
+  const blank = (from, to) => {
+    const end = Math.min(to, text.length);
+    if (from >= end)
+      return;
+    parts.push(text.slice(copied, from));
+    let run = from;
+    for (let k = from;k < end; k++) {
+      if (text.charCodeAt(k) < 32) {
+        let slashes = k;
+        while (slashes > run && text.charCodeAt(slashes - 1) === 92)
+          slashes--;
+        parts.push(" ".repeat(slashes - run), text.slice(slashes, k + 1));
+        run = k + 1;
+      }
+    }
+    let tail = end;
+    if (end < text.length && text.charCodeAt(end) < 32) {
+      while (tail > run && text.charCodeAt(tail - 1) === 92)
+        tail--;
+    }
+    parts.push(" ".repeat(tail - run), text.slice(tail, end));
+    copied = end;
+  };
+  const inert = (from, to) => {
+    parts.push(text.slice(copied, from), "~".repeat(to - from));
+    copied = to;
+  };
+  const scan = new StringScan(text);
+  const sqlResume = [];
+  let depth = 0;
+  const sql = (from) => {
+    const stop = sqlStop(text, from);
+    blank(from, stop.bodyEnd);
+    if (stop.opensCode) {
+      sqlResume.push(depth);
+      depth++;
+    }
+    return stop.end;
+  };
+  let prefixAt = -1;
+  let blankedSince = -1;
+  const marks = [];
+  const trivia = (from, to) => {
+    blank(from, to);
+    if (prefixAt < 0)
+      return;
+    for (let k = Math.min(to, text.length) - 1;k >= from; k--) {
+      if (text.charCodeAt(k) >= 32) {
+        blankedSince = k;
+        break;
+      }
+    }
+  };
+  let i = 0;
+  while (i < text.length) {
+    const code = text.charCodeAt(i);
+    if (text.startsWith("--", i) || text.startsWith("//", i) || code === 35) {
+      const end = code === 35 ? skipAnnotation(text, i, trivia) : lineTrivia(text, i, trivia);
+      if (end >= 0) {
+        i = end;
+        continue;
+      }
+    } else if (text.startsWith("/*", i)) {
+      const close = text.indexOf("*/", i + 2);
+      const end = close === -1 ? text.length : close + 2;
+      trivia(i, end);
+      i = end;
+      continue;
+    }
+    if (prefixAt >= 0 && !isLexerSpace(code)) {
+      if ((code === 39 || code === 34 || code === 96) && blankedSince >= 0) {
+        marks.push(blankedSince);
+      }
+      prefixAt = -1;
+      blankedSince = -1;
+    }
+    if (code === 123) {
+      depth++;
+      i++;
+      continue;
+    }
+    if (code === 125) {
+      depth--;
+      i++;
+      if (sqlResume.length > 0 && sqlResume[sqlResume.length - 1] === depth) {
+        sqlResume.pop();
+        i = sql(i);
+      }
+      continue;
+    }
+    if (text.startsWith('"""', i)) {
+      i = sql(i + 3);
+      continue;
+    }
+    if (code === 39 || code === 34 || code === 96) {
+      const close = scan.stringClose(i);
+      if (close < 0) {
+        i++;
+        continue;
+      }
+      if (code !== 96)
+        blank(i + 1, close);
+      i = close + 1;
+      continue;
+    }
+    const prefixed = scan.prefixedLiteral(i);
+    if (prefixed) {
+      const { open, quote, bodyEnd, end } = prefixed;
+      const tick = text.charCodeAt(open) === 96;
+      if (tick)
+        inert(open, open + quote);
+      blank(open + quote, bodyEnd);
+      if (tick && text.charCodeAt(bodyEnd) === 96)
+        inert(bodyEnd, end);
+      i = end;
+      continue;
+    }
+    const letter = code | 32;
+    if ((letter === 102 || letter === 115) && !continuesToken(text, i)) {
+      prefixAt = i;
+    }
+    i++;
+  }
+  parts.push(text.slice(copied));
+  let out = parts.join("");
+  for (const at of marks)
+    out = `${out.slice(0, at)}~${out.slice(at + 1)}`;
+  return out;
+}
+function lineTrivia(text, i, blank) {
+  const end = toEndOfLine(text, i);
+  if (end >= 0)
+    blank(i, end);
+  return end;
+}
+function lineEnd(text, i) {
+  let at = i;
+  while (at < text.length) {
+    const code = text.charCodeAt(at);
+    if (code === 10 || code === 13)
+      return at;
+    at++;
+  }
+  return at;
+}
+function toEndOfLine(text, i) {
+  const end = lineEnd(text, i);
+  if (text.charCodeAt(end) === 13 && text.charCodeAt(end + 1) !== 10) {
+    return -1;
+  }
+  return end;
+}
+function nextLine(text, i) {
+  const end = lineEnd(text, i);
+  if (text.charCodeAt(end) === 13 && text.charCodeAt(end + 1) === 10) {
+    return end + 2;
+  }
+  return Math.min(end + 1, text.length);
+}
+function skipAnnotation(text, i, blank) {
+  const end = toEndOfLine(text, i);
+  if (end < 0)
+    return -1;
+  const closer = text.startsWith("##|", i) ? "|##" : text.startsWith("#|", i) ? "|#" : undefined;
+  if (!closer) {
+    blank(i, end);
+    return end;
+  }
+  let column = 0;
+  for (let at2 = text.lastIndexOf(`
+`, i - 1) + 1;at2 < i; at2++) {
+    if ((text.charCodeAt(at2) & 64512) !== 56320)
+      column++;
+  }
+  let at = nextLine(text, i);
+  blank(i, at);
+  while (at < text.length) {
+    const closes = closesBlock(text, at, column, closer);
+    const after = nextLine(text, at);
+    blank(at, after);
+    at = after;
+    if (closes)
+      break;
+  }
+  return at;
+}
+function closesBlock(text, at, column, closer) {
+  for (let c = 0;c < column; c++) {
+    const code = text.charCodeAt(at + c);
+    if (code !== 32 && code !== 9)
+      return false;
+  }
+  const from = at + column;
+  if (!text.startsWith(closer, from))
+    return false;
+  return closer !== "|#" || text.charCodeAt(from + 2) !== 35;
+}
+function sqlStop(text, from) {
+  const reach = [false, false, false, false];
+  let furthest = from;
+  const mark = (at) => {
+    reach[at & 3] = true;
+    furthest = Math.max(furthest, at);
+  };
+  mark(from);
+  let stop = {
+    bodyEnd: text.length,
+    end: text.length,
+    opensCode: false
+  };
+  let found = false;
+  for (let j = from;j < text.length && j <= furthest; j++) {
+    if (!reach[j & 3])
+      continue;
+    reach[j & 3] = false;
+    const code = text.charCodeAt(j);
+    const next = text.charCodeAt(j + 1);
+    if (code === 34 && next === 34 && text.charCodeAt(j + 2) === 34) {
+      if (!found || j + 3 > stop.end) {
+        stop = { bodyEnd: j, end: j + 3, opensCode: false };
+      }
+      found = true;
+      continue;
+    }
+    if (code === 37 && next === 123) {
+      if (!found || j + 2 > stop.end) {
+        stop = { bodyEnd: j, end: j + 2, opensCode: true };
+      }
+      found = true;
+      continue;
+    }
+    if (code === 92) {
+      mark(j + 1);
+      mark(j + 2);
+    } else if (code === 34) {
+      mark(next === 34 ? j + 3 : j + 2);
+    } else if (code === 37) {
+      mark(j + 2);
+    } else {
+      mark(j + 1);
+    }
+  }
+  return stop;
+}
+function isLexerSpace(code) {
+  return code === 32 || code === 9 || code === 10 || code === 11 || code === 13 || code === 160;
+}
+
+class StringScan {
+  text;
+  stringFailedAt = [-1, -1, -1];
+  tripleUnclosedFrom = [Infinity, Infinity, Infinity];
+  constructor(text) {
+    this.text = text;
+  }
+  stringClose(i) {
+    const text = this.text;
+    const quote = text.charCodeAt(i);
+    const slot = quoteSlot(quote);
+    if (i < this.stringFailedAt[slot])
+      return -1;
+    let j = i + 1;
+    while (j < text.length) {
+      const code = text.charCodeAt(j);
+      if (code === quote)
+        return j;
+      if (code === 92) {
+        if (j + 1 >= text.length || text.charCodeAt(j + 1) === 10)
+          break;
+        j += 2;
+        continue;
+      }
+      if (code < 32 && code !== 9)
+        break;
+      j++;
+    }
+    this.stringFailedAt[slot] = j;
+    return -1;
+  }
+  prefixedLiteral(i) {
+    const text = this.text;
+    const code = text.charCodeAt(i);
+    if (code === 47) {
+      if (text.charCodeAt(i + 1) !== 39)
+        return;
+      return this.raw(i + 1, 39, false);
+    }
+    const letter = code | 32;
+    if (letter !== 102 && letter !== 114 && letter !== 115)
+      return;
+    if (continuesToken(text, i))
+      return;
+    if (letter === 114) {
+      return text.charCodeAt(i + 1) === 39 ? this.raw(i + 1, 39, false) : undefined;
+    }
+    let open = i + 1;
+    while (open < text.length && isLexerSpace(text.charCodeAt(open)))
+      open++;
+    const quote = text.charCodeAt(open);
+    if (letter === 115) {
+      return quote === 39 || quote === 34 ? this.raw(open, quote, true) : undefined;
+    }
+    if (quote !== 39 && quote !== 34 && quote !== 96)
+      return;
+    if (text.charCodeAt(open + 1) === quote && text.charCodeAt(open + 2) === quote) {
+      const close = this.tripleClose(open + 3, quote);
+      if (close >= 0) {
+        return { open, quote: 3, bodyEnd: close, end: close + 3 };
+      }
+    }
+    return this.raw(open, quote, true);
+  }
+  raw(open, quote, endsAtNewline) {
+    const text = this.text;
+    let j = open + 1;
+    while (j < text.length) {
+      const code = text.charCodeAt(j);
+      if (code === 10) {
+        return endsAtNewline ? { open, quote: 1, bodyEnd: j, end: j + 1 } : undefined;
+      }
+      if (code === 92) {
+        if (j + 1 >= text.length || text.charCodeAt(j + 1) === 10) {
+          return;
+        }
+        j += 2;
+        continue;
+      }
+      if (code === quote)
+        return { open, quote: 1, bodyEnd: j, end: j + 1 };
+      j++;
+    }
+    return;
+  }
+  tripleClose(body, quote) {
+    const text = this.text;
+    const slot = quoteSlot(quote);
+    if (body >= this.tripleUnclosedFrom[slot])
+      return -1;
+    let j = body;
+    while (j < text.length) {
+      const code = text.charCodeAt(j);
+      if (code === 92) {
+        j += 2;
+        continue;
+      }
+      if (code === quote && text.charCodeAt(j + 1) === quote && text.charCodeAt(j + 2) === quote) {
+        return j;
+      }
+      j++;
+    }
+    this.tripleUnclosedFrom[slot] = body;
+    return -1;
+  }
+}
+function quoteSlot(quote) {
+  return quote === 39 ? 0 : quote === 34 ? 1 : 2;
+}
+function continuesToken(text, i) {
+  if (i === 0)
+    return false;
+  let at = i - 1;
+  if ((text.charCodeAt(at) & 64512) === 56320 && at > 0)
+    at--;
+  const code = text.charCodeAt(at);
+  return code === 36 || isNameCode(code, text, at);
+}
+function buildDerivationBaseMap(query) {
+  const out = new Map;
+  readDefinitions(query, (_keyword, name, base) => addEdge(out, name, base));
+  return out;
+}
+function readDefinitions(query, onItem) {
+  const tokens = tokenize(stripMalloyCommentsAndLiterals(query));
+  let depth = 0;
+  for (let i = 0;i < tokens.count; i++) {
+    if (isPunct(tokens, i, "{"))
+      depth++;
+    else if (isPunct(tokens, i, "}"))
+      depth--;
+    if (depth !== 0 || !isStatementKeyword(tokens, i))
+      continue;
+    const keyword = isWord(tokens, i, "source") ? "source" : isWord(tokens, i, "query") ? "query" : undefined;
+    if (!keyword)
+      continue;
+    readStatementItems(tokens, i + 2, false, (name, base) => onItem(keyword, name, base));
+  }
+}
+function isNameCode(code, text, at) {
+  if (code < 128) {
+    return code >= 48 && code <= 57 || code >= 65 && code <= 90 || code >= 97 && code <= 122 || code === 95;
+  }
+  return NAME_CHAR.test(String.fromCodePoint(text.codePointAt(at)));
+}
+function isSpaceCode(code, text, at) {
+  if (code < 128)
+    return code === 32 || code >= 9 && code <= 13;
+  return SPACE_CHAR.test(String.fromCodePoint(text.codePointAt(at)));
+}
+function unitsAt(text, at) {
+  return text.codePointAt(at) > 65535 ? 2 : 1;
+}
+function tokenize(text) {
+  const size = text.length + 1;
+  const tokens = {
+    source: text,
+    count: 0,
+    kind: new Uint8Array(size),
+    start: new Int32Array(size),
+    end: new Int32Array(size),
+    partner: new Int32Array(size).fill(-1),
+    decoded: new Map
+  };
+  const push = (kind, start, end) => {
+    const index = tokens.count++;
+    tokens.kind[index] = kind;
+    tokens.start[index] = start;
+    tokens.end[index] = end;
+    return index;
+  };
+  const open = [];
+  const scan = new StringScan(text);
+  let i = 0;
+  while (i < text.length) {
+    const code = text.charCodeAt(i);
+    if (isSpaceCode(code, text, i)) {
+      i += unitsAt(text, i);
+      continue;
+    }
+    const close = code === 96 ? scan.stringClose(i) : -1;
+    if (close >= 0) {
+      const index2 = push(QUOTED, i + 1, close);
+      const inner = text.slice(i + 1, close);
+      if (inner.includes("\\")) {
+        tokens.decoded.set(index2, ParseUtil.parseString(inner));
+      }
+      i = close + 1;
+      continue;
+    }
+    if (isNameCode(code, text, i)) {
+      let j = i + unitsAt(text, i);
+      while (j < text.length && isNameCode(text.charCodeAt(j), text, j)) {
+        j += unitsAt(text, j);
+      }
+      push(NAME, i, j);
+      i = j;
+      continue;
+    }
+    const units = unitsAt(text, i);
+    const index = push(PUNCT, i, i + units);
+    if (code === 40 || code === 91 || code === 123) {
+      open.push(index);
+    } else if (code === 41 || code === 93 || code === 125) {
+      const at = open.pop();
+      if (at !== undefined) {
+        tokens.partner[at] = index;
+        tokens.partner[index] = at;
+      }
+    }
+    i += units;
+  }
+  return tokens;
+}
+function textOf(tokens, i) {
+  return tokens.decoded.get(i) ?? tokens.source.slice(tokens.start[i], tokens.end[i]);
+}
+function textIs(tokens, i, char) {
+  return i >= 0 && i < tokens.count && tokens.end[i] - tokens.start[i] === 1 && tokens.source.charCodeAt(tokens.start[i]) === char.charCodeAt(0);
+}
+function isPunct(tokens, i, char) {
+  return textIs(tokens, i, char) && tokens.kind[i] === PUNCT;
+}
+function isName(tokens, i) {
+  return i >= 0 && i < tokens.count && tokens.kind[i] !== PUNCT;
+}
+function isWord(tokens, i, word) {
+  if (i < 0 || i >= tokens.count || tokens.kind[i] !== NAME || tokens.end[i] - tokens.start[i] !== word.length) {
+    return false;
+  }
+  const from = tokens.start[i];
+  for (let k = 0;k < word.length; k++) {
+    const code = tokens.source.charCodeAt(from + k);
+    const lower = code >= 65 && code <= 90 ? code + 32 : code;
+    if (lower !== word.charCodeAt(k))
+      return false;
+  }
+  return true;
+}
+function isStatementKeyword(tokens, i) {
+  return i < tokens.count && tokens.kind[i] === NAME && textIs(tokens, i + 1, ":") && !textIs(tokens, i + 2, ":") && !textIs(tokens, i - 1, ":") && !textIs(tokens, i - 1, ".");
+}
+function readBase(tokens, i) {
+  let j = i;
+  while (textIs(tokens, j, "(") && tokens.kind[j] === PUNCT)
+    j++;
+  if (!isName(tokens, j) || isLiteralPrefix(tokens, j))
+    return UNREADABLE_BASE;
+  return textOf(tokens, j);
+}
+function isLiteralPrefix(tokens, i) {
+  if (!(isWord(tokens, i, "f") || isWord(tokens, i, "s") || isWord(tokens, i, "r"))) {
+    return false;
+  }
+  return ["'", '"', "`", "~"].some((quote) => isPunct(tokens, i + 1, quote));
+}
+function readStatementItems(tokens, start, shorthand, onItem) {
+  let atItemStart = true;
+  let i = start;
+  while (i < tokens.count) {
+    if (tokens.kind[i] === PUNCT) {
+      if (textIs(tokens, i, ";"))
+        return;
+      if (tokens.partner[i] > i) {
+        i = tokens.partner[i] + 1;
+        atItemStart = false;
+        continue;
+      }
+      if (textIs(tokens, i, ")") || textIs(tokens, i, "]") || textIs(tokens, i, "}")) {
+        return;
+      }
+      atItemStart = textIs(tokens, i, ",");
+      i++;
+      continue;
+    }
+    if (isStatementKeyword(tokens, i))
+      return;
+    let k = i + 1;
+    if (textIs(tokens, k, "(") && tokens.partner[k] > k) {
+      k = tokens.partner[k] + 1;
+    }
+    if (isWord(tokens, k, "is")) {
+      onItem(textOf(tokens, i), readBase(tokens, k + 1));
+      i = k + 1;
+    } else {
+      if (shorthand && atItemStart) {
+        const name = textOf(tokens, i);
+        onItem(name, name);
+      }
+      i++;
+    }
+    atItemStart = false;
+  }
+}
+function addEdge(map, name, base) {
+  const bases = map.get(name) ?? new Set;
+  bases.add(base);
+  map.set(name, bases);
+}
+function buildJoinBaseMap(query) {
+  const out = new Map;
+  const tokens = tokenize(stripMalloyCommentsAndLiterals(query));
+  for (let i = 0;i < tokens.count; i++) {
+    if (!isStatementKeyword(tokens, i))
+      continue;
+    if (!/^join_(?:one|many|cross)$/i.test(textOf(tokens, i)))
+      continue;
+    readStatementItems(tokens, i + 2, true, (alias, base) => addEdge(out, alias, base));
+  }
+  return out;
+}
+function buildIsEdgeMap(query) {
+  const out = new Map;
+  const tokens = tokenize(stripMalloyCommentsAndLiterals(query));
+  for (let k = 1;k < tokens.count; k++) {
+    if (!isWord(tokens, k, "is"))
+      continue;
+    let n = k - 1;
+    if (textIs(tokens, n, ")") && tokens.kind[n] === PUNCT && tokens.partner[n] >= 0) {
+      n = tokens.partner[n] - 1;
+    }
+    if (!isName(tokens, n))
+      continue;
+    addEdge(out, textOf(tokens, n), readBase(tokens, k + 1));
+  }
+  return out;
+}
+function scanIdentifiers(text) {
+  const tokens = tokenize(text);
+  const names = new Set;
+  for (let i = 0;i < tokens.count; i++) {
+    if (isName(tokens, i))
+      names.add(textOf(tokens, i));
+  }
+  return names;
+}
+function collectIdentifierNames(text) {
+  const names = scanIdentifiers(text);
+  for (const name of scanIdentifiers(stripMalloyCommentsAndLiterals(text))) {
+    names.add(name);
+  }
+  return names;
+}
+function formatProblem(problem) {
+  const start = problem.at?.range?.start;
+  return start?.line === undefined ? problem.message : `line ${start.line + 1}:${(start.character ?? 0) + 1} ${problem.message}`;
+}
+function locateProblemsInCallerText(problems, callerText, prefixLines) {
+  const callerLines = callerText.split(`
+`).length;
+  return problems.map((problem) => {
+    const at = problem.at;
+    if (!at)
+      return problem;
+    const start = at.range.start.line - prefixLines;
+    const end = at.range.end.line - prefixLines;
+    const inCallerText = at.url.startsWith("internal://") && start >= 0 && end < callerLines;
+    if (!inCallerText) {
+      const { at: _dropped, ...unlocated } = problem;
+      return unlocated;
+    }
+    return {
+      ...problem,
+      at: {
+        ...at,
+        range: {
+          start: { ...at.range.start, line: start },
+          end: { ...at.range.end, line: end }
+        }
+      }
+    };
+  });
+}
+var UNREADABLE_BASE = "`", PUNCT = 0, NAME = 1, QUOTED = 2, NAME_CHAR, SPACE_CHAR;
+var init_query_text = __esm(() => {
+  NAME_CHAR = /\p{Alphabetic}/u;
+  SPACE_CHAR = /\s/u;
+});
+
 // ../../node_modules/lunr/lunr.js
 var require_lunr = __commonJS((exports, module) => {
   (function() {
@@ -267793,9 +268500,9 @@ function endOfDelimited(text, start) {
     for (;; ) {
       const newline = text.indexOf(`
 `, lineStart);
-      const lineEnd = newline === -1 ? text.length : newline;
-      if (text.slice(lineStart, lineEnd).trim() === ">>>")
-        return lineEnd;
+      const lineEnd2 = newline === -1 ? text.length : newline;
+      if (text.slice(lineStart, lineEnd2).trim() === ">>>")
+        return lineEnd2;
       if (newline === -1)
         return text.length;
       lineStart = newline + 1;
@@ -274386,7 +275093,7 @@ function parseFilterAnnotation(annotation) {
     return null;
   }
   const body = trimmed2.slice(ANNOTATION_PREFIX.length).trim();
-  const tokens = tokenize(body);
+  const tokens = tokenize2(body);
   let name;
   let dimension;
   let type;
@@ -274525,7 +275232,7 @@ function injectFilterRefinement(query, filterClause) {
   return `${query.trimEnd()}
 + {where: ${filterClause}}`;
 }
-function tokenize(input) {
+function tokenize2(input) {
   const tokens = [];
   let current = "";
   let inQuote = false;
@@ -274626,660 +275333,6 @@ var init_json_utils = __esm(() => {
   MAX_SAFE_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
 });
 
-// src/service/query_text.ts
-import { ParseUtil } from "@malloydata/malloy-tag";
-function extractRunTargetSourceName(query) {
-  return extractRunTargetSourceNames(query).at(-1);
-}
-function extractRunTargetSourceNames(query) {
-  if (!query)
-    return [];
-  const tokens = tokenize2(stripMalloyCommentsAndLiterals(query));
-  const targets = [];
-  for (let k = 0;k + 1 < tokens.count; k++) {
-    if (!isWord(tokens, k, "run") || !textIs(tokens, k + 1, ":"))
-      continue;
-    let j = k + 2;
-    while (textIs(tokens, j, "(") && tokens.kind[j] === PUNCT)
-      j++;
-    if (isName(tokens, j))
-      targets.push(textOf(tokens, j));
-  }
-  if (targets.length > 0)
-    return targets;
-  for (let k = 0;k + 2 < tokens.count; k++) {
-    if (isName(tokens, k) && textIs(tokens, k + 1, "-") && textIs(tokens, k + 2, ">") && tokens.start[k + 2] === tokens.start[k + 1] + 1 && opensLine(tokens, k)) {
-      return [textOf(tokens, k)];
-    }
-  }
-  return [];
-}
-function opensLine(tokens, k) {
-  if (k === 0)
-    return true;
-  const from = tokens.end[k - 1];
-  const to = tokens.start[k];
-  for (let at = from;at < to; at++) {
-    const code = tokens.source.charCodeAt(at);
-    if (code === 10 || code === 13)
-      return true;
-  }
-  return false;
-}
-function malloyIdentifiers(text) {
-  return [...scanIdentifiers(stripMalloyCommentsAndLiterals(text))];
-}
-function buildSourceAliasMap(query) {
-  const aliasOf = new Map;
-  readDefinitions(query, (keyword, name, base) => {
-    if (keyword === "source" && base !== UNREADABLE_BASE) {
-      aliasOf.set(name, base);
-    }
-  });
-  return aliasOf;
-}
-function stripMalloyCommentsAndLiterals(text) {
-  if (typeof text !== "string")
-    throw new TypeError("query text must be a string");
-  const parts = [];
-  let copied = 0;
-  const blank = (from, to) => {
-    const end = Math.min(to, text.length);
-    if (from >= end)
-      return;
-    parts.push(text.slice(copied, from));
-    let run = from;
-    for (let k = from;k < end; k++) {
-      if (text.charCodeAt(k) < 32) {
-        let slashes = k;
-        while (slashes > run && text.charCodeAt(slashes - 1) === 92)
-          slashes--;
-        parts.push(" ".repeat(slashes - run), text.slice(slashes, k + 1));
-        run = k + 1;
-      }
-    }
-    let tail = end;
-    if (end < text.length && text.charCodeAt(end) < 32) {
-      while (tail > run && text.charCodeAt(tail - 1) === 92)
-        tail--;
-    }
-    parts.push(" ".repeat(tail - run), text.slice(tail, end));
-    copied = end;
-  };
-  const inert = (from, to) => {
-    parts.push(text.slice(copied, from), "~".repeat(to - from));
-    copied = to;
-  };
-  const scan = new StringScan(text);
-  const sqlResume = [];
-  let depth = 0;
-  const sql = (from) => {
-    const stop = sqlStop(text, from);
-    blank(from, stop.bodyEnd);
-    if (stop.opensCode) {
-      sqlResume.push(depth);
-      depth++;
-    }
-    return stop.end;
-  };
-  let prefixAt = -1;
-  let blankedSince = -1;
-  const marks = [];
-  const trivia = (from, to) => {
-    blank(from, to);
-    if (prefixAt < 0)
-      return;
-    for (let k = Math.min(to, text.length) - 1;k >= from; k--) {
-      if (text.charCodeAt(k) >= 32) {
-        blankedSince = k;
-        break;
-      }
-    }
-  };
-  let i = 0;
-  while (i < text.length) {
-    const code = text.charCodeAt(i);
-    if (text.startsWith("--", i) || text.startsWith("//", i) || code === 35) {
-      const end = code === 35 ? skipAnnotation(text, i, trivia) : lineTrivia(text, i, trivia);
-      if (end >= 0) {
-        i = end;
-        continue;
-      }
-    } else if (text.startsWith("/*", i)) {
-      const close = text.indexOf("*/", i + 2);
-      const end = close === -1 ? text.length : close + 2;
-      trivia(i, end);
-      i = end;
-      continue;
-    }
-    if (prefixAt >= 0 && !isLexerSpace(code)) {
-      if ((code === 39 || code === 34 || code === 96) && blankedSince >= 0) {
-        marks.push(blankedSince);
-      }
-      prefixAt = -1;
-      blankedSince = -1;
-    }
-    if (code === 123) {
-      depth++;
-      i++;
-      continue;
-    }
-    if (code === 125) {
-      depth--;
-      i++;
-      if (sqlResume.length > 0 && sqlResume[sqlResume.length - 1] === depth) {
-        sqlResume.pop();
-        i = sql(i);
-      }
-      continue;
-    }
-    if (text.startsWith('"""', i)) {
-      i = sql(i + 3);
-      continue;
-    }
-    if (code === 39 || code === 34 || code === 96) {
-      const close = scan.stringClose(i);
-      if (close < 0) {
-        i++;
-        continue;
-      }
-      if (code !== 96)
-        blank(i + 1, close);
-      i = close + 1;
-      continue;
-    }
-    const prefixed = scan.prefixedLiteral(i);
-    if (prefixed) {
-      const { open: open2, quote, bodyEnd, end } = prefixed;
-      const tick = text.charCodeAt(open2) === 96;
-      if (tick)
-        inert(open2, open2 + quote);
-      blank(open2 + quote, bodyEnd);
-      if (tick && text.charCodeAt(bodyEnd) === 96)
-        inert(bodyEnd, end);
-      i = end;
-      continue;
-    }
-    const letter = code | 32;
-    if ((letter === 102 || letter === 115) && !continuesToken(text, i)) {
-      prefixAt = i;
-    }
-    i++;
-  }
-  parts.push(text.slice(copied));
-  let out = parts.join("");
-  for (const at of marks)
-    out = `${out.slice(0, at)}~${out.slice(at + 1)}`;
-  return out;
-}
-function lineTrivia(text, i, blank) {
-  const end = toEndOfLine(text, i);
-  if (end >= 0)
-    blank(i, end);
-  return end;
-}
-function lineEnd(text, i) {
-  let at = i;
-  while (at < text.length) {
-    const code = text.charCodeAt(at);
-    if (code === 10 || code === 13)
-      return at;
-    at++;
-  }
-  return at;
-}
-function toEndOfLine(text, i) {
-  const end = lineEnd(text, i);
-  if (text.charCodeAt(end) === 13 && text.charCodeAt(end + 1) !== 10) {
-    return -1;
-  }
-  return end;
-}
-function nextLine(text, i) {
-  const end = lineEnd(text, i);
-  if (text.charCodeAt(end) === 13 && text.charCodeAt(end + 1) === 10) {
-    return end + 2;
-  }
-  return Math.min(end + 1, text.length);
-}
-function skipAnnotation(text, i, blank) {
-  const end = toEndOfLine(text, i);
-  if (end < 0)
-    return -1;
-  const closer = text.startsWith("##|", i) ? "|##" : text.startsWith("#|", i) ? "|#" : undefined;
-  if (!closer) {
-    blank(i, end);
-    return end;
-  }
-  let column = 0;
-  for (let at2 = text.lastIndexOf(`
-`, i - 1) + 1;at2 < i; at2++) {
-    if ((text.charCodeAt(at2) & 64512) !== 56320)
-      column++;
-  }
-  let at = nextLine(text, i);
-  blank(i, at);
-  while (at < text.length) {
-    const closes = closesBlock(text, at, column, closer);
-    const after = nextLine(text, at);
-    blank(at, after);
-    at = after;
-    if (closes)
-      break;
-  }
-  return at;
-}
-function closesBlock(text, at, column, closer) {
-  for (let c = 0;c < column; c++) {
-    const code = text.charCodeAt(at + c);
-    if (code !== 32 && code !== 9)
-      return false;
-  }
-  const from = at + column;
-  if (!text.startsWith(closer, from))
-    return false;
-  return closer !== "|#" || text.charCodeAt(from + 2) !== 35;
-}
-function sqlStop(text, from) {
-  const reach = [false, false, false, false];
-  let furthest = from;
-  const mark = (at) => {
-    reach[at & 3] = true;
-    furthest = Math.max(furthest, at);
-  };
-  mark(from);
-  let stop = {
-    bodyEnd: text.length,
-    end: text.length,
-    opensCode: false
-  };
-  let found = false;
-  for (let j = from;j < text.length && j <= furthest; j++) {
-    if (!reach[j & 3])
-      continue;
-    reach[j & 3] = false;
-    const code = text.charCodeAt(j);
-    const next = text.charCodeAt(j + 1);
-    if (code === 34 && next === 34 && text.charCodeAt(j + 2) === 34) {
-      if (!found || j + 3 > stop.end) {
-        stop = { bodyEnd: j, end: j + 3, opensCode: false };
-      }
-      found = true;
-      continue;
-    }
-    if (code === 37 && next === 123) {
-      if (!found || j + 2 > stop.end) {
-        stop = { bodyEnd: j, end: j + 2, opensCode: true };
-      }
-      found = true;
-      continue;
-    }
-    if (code === 92) {
-      mark(j + 1);
-      mark(j + 2);
-    } else if (code === 34) {
-      mark(next === 34 ? j + 3 : j + 2);
-    } else if (code === 37) {
-      mark(j + 2);
-    } else {
-      mark(j + 1);
-    }
-  }
-  return stop;
-}
-function isLexerSpace(code) {
-  return code === 32 || code === 9 || code === 10 || code === 11 || code === 13 || code === 160;
-}
-
-class StringScan {
-  text;
-  stringFailedAt = [-1, -1, -1];
-  tripleUnclosedFrom = [Infinity, Infinity, Infinity];
-  constructor(text) {
-    this.text = text;
-  }
-  stringClose(i) {
-    const text = this.text;
-    const quote = text.charCodeAt(i);
-    const slot = quoteSlot(quote);
-    if (i < this.stringFailedAt[slot])
-      return -1;
-    let j = i + 1;
-    while (j < text.length) {
-      const code = text.charCodeAt(j);
-      if (code === quote)
-        return j;
-      if (code === 92) {
-        if (j + 1 >= text.length || text.charCodeAt(j + 1) === 10)
-          break;
-        j += 2;
-        continue;
-      }
-      if (code < 32 && code !== 9)
-        break;
-      j++;
-    }
-    this.stringFailedAt[slot] = j;
-    return -1;
-  }
-  prefixedLiteral(i) {
-    const text = this.text;
-    const code = text.charCodeAt(i);
-    if (code === 47) {
-      if (text.charCodeAt(i + 1) !== 39)
-        return;
-      return this.raw(i + 1, 39, false);
-    }
-    const letter = code | 32;
-    if (letter !== 102 && letter !== 114 && letter !== 115)
-      return;
-    if (continuesToken(text, i))
-      return;
-    if (letter === 114) {
-      return text.charCodeAt(i + 1) === 39 ? this.raw(i + 1, 39, false) : undefined;
-    }
-    let open2 = i + 1;
-    while (open2 < text.length && isLexerSpace(text.charCodeAt(open2)))
-      open2++;
-    const quote = text.charCodeAt(open2);
-    if (letter === 115) {
-      return quote === 39 || quote === 34 ? this.raw(open2, quote, true) : undefined;
-    }
-    if (quote !== 39 && quote !== 34 && quote !== 96)
-      return;
-    if (text.charCodeAt(open2 + 1) === quote && text.charCodeAt(open2 + 2) === quote) {
-      const close = this.tripleClose(open2 + 3, quote);
-      if (close >= 0) {
-        return { open: open2, quote: 3, bodyEnd: close, end: close + 3 };
-      }
-    }
-    return this.raw(open2, quote, true);
-  }
-  raw(open2, quote, endsAtNewline) {
-    const text = this.text;
-    let j = open2 + 1;
-    while (j < text.length) {
-      const code = text.charCodeAt(j);
-      if (code === 10) {
-        return endsAtNewline ? { open: open2, quote: 1, bodyEnd: j, end: j + 1 } : undefined;
-      }
-      if (code === 92) {
-        if (j + 1 >= text.length || text.charCodeAt(j + 1) === 10) {
-          return;
-        }
-        j += 2;
-        continue;
-      }
-      if (code === quote)
-        return { open: open2, quote: 1, bodyEnd: j, end: j + 1 };
-      j++;
-    }
-    return;
-  }
-  tripleClose(body, quote) {
-    const text = this.text;
-    const slot = quoteSlot(quote);
-    if (body >= this.tripleUnclosedFrom[slot])
-      return -1;
-    let j = body;
-    while (j < text.length) {
-      const code = text.charCodeAt(j);
-      if (code === 92) {
-        j += 2;
-        continue;
-      }
-      if (code === quote && text.charCodeAt(j + 1) === quote && text.charCodeAt(j + 2) === quote) {
-        return j;
-      }
-      j++;
-    }
-    this.tripleUnclosedFrom[slot] = body;
-    return -1;
-  }
-}
-function quoteSlot(quote) {
-  return quote === 39 ? 0 : quote === 34 ? 1 : 2;
-}
-function continuesToken(text, i) {
-  if (i === 0)
-    return false;
-  let at = i - 1;
-  if ((text.charCodeAt(at) & 64512) === 56320 && at > 0)
-    at--;
-  const code = text.charCodeAt(at);
-  return code === 36 || isNameCode(code, text, at);
-}
-function buildDerivationBaseMap(query) {
-  const out = new Map;
-  readDefinitions(query, (_keyword, name, base) => addEdge(out, name, base));
-  return out;
-}
-function readDefinitions(query, onItem) {
-  const tokens = tokenize2(stripMalloyCommentsAndLiterals(query));
-  let depth = 0;
-  for (let i = 0;i < tokens.count; i++) {
-    if (isPunct(tokens, i, "{"))
-      depth++;
-    else if (isPunct(tokens, i, "}"))
-      depth--;
-    if (depth !== 0 || !isStatementKeyword(tokens, i))
-      continue;
-    const keyword = isWord(tokens, i, "source") ? "source" : isWord(tokens, i, "query") ? "query" : undefined;
-    if (!keyword)
-      continue;
-    readStatementItems(tokens, i + 2, false, (name, base) => onItem(keyword, name, base));
-  }
-}
-function isNameCode(code, text, at) {
-  if (code < 128) {
-    return code >= 48 && code <= 57 || code >= 65 && code <= 90 || code >= 97 && code <= 122 || code === 95;
-  }
-  return NAME_CHAR.test(String.fromCodePoint(text.codePointAt(at)));
-}
-function isSpaceCode(code, text, at) {
-  if (code < 128)
-    return code === 32 || code >= 9 && code <= 13;
-  return SPACE_CHAR.test(String.fromCodePoint(text.codePointAt(at)));
-}
-function unitsAt(text, at) {
-  return text.codePointAt(at) > 65535 ? 2 : 1;
-}
-function tokenize2(text) {
-  const size = text.length + 1;
-  const tokens = {
-    source: text,
-    count: 0,
-    kind: new Uint8Array(size),
-    start: new Int32Array(size),
-    end: new Int32Array(size),
-    partner: new Int32Array(size).fill(-1),
-    decoded: new Map
-  };
-  const push = (kind, start, end) => {
-    const index = tokens.count++;
-    tokens.kind[index] = kind;
-    tokens.start[index] = start;
-    tokens.end[index] = end;
-    return index;
-  };
-  const open2 = [];
-  const scan = new StringScan(text);
-  let i = 0;
-  while (i < text.length) {
-    const code = text.charCodeAt(i);
-    if (isSpaceCode(code, text, i)) {
-      i += unitsAt(text, i);
-      continue;
-    }
-    const close = code === 96 ? scan.stringClose(i) : -1;
-    if (close >= 0) {
-      const index2 = push(QUOTED, i + 1, close);
-      const inner = text.slice(i + 1, close);
-      if (inner.includes("\\")) {
-        tokens.decoded.set(index2, ParseUtil.parseString(inner));
-      }
-      i = close + 1;
-      continue;
-    }
-    if (isNameCode(code, text, i)) {
-      let j = i + unitsAt(text, i);
-      while (j < text.length && isNameCode(text.charCodeAt(j), text, j)) {
-        j += unitsAt(text, j);
-      }
-      push(NAME, i, j);
-      i = j;
-      continue;
-    }
-    const units = unitsAt(text, i);
-    const index = push(PUNCT, i, i + units);
-    if (code === 40 || code === 91 || code === 123) {
-      open2.push(index);
-    } else if (code === 41 || code === 93 || code === 125) {
-      const at = open2.pop();
-      if (at !== undefined) {
-        tokens.partner[at] = index;
-        tokens.partner[index] = at;
-      }
-    }
-    i += units;
-  }
-  return tokens;
-}
-function textOf(tokens, i) {
-  return tokens.decoded.get(i) ?? tokens.source.slice(tokens.start[i], tokens.end[i]);
-}
-function textIs(tokens, i, char) {
-  return i >= 0 && i < tokens.count && tokens.end[i] - tokens.start[i] === 1 && tokens.source.charCodeAt(tokens.start[i]) === char.charCodeAt(0);
-}
-function isPunct(tokens, i, char) {
-  return textIs(tokens, i, char) && tokens.kind[i] === PUNCT;
-}
-function isName(tokens, i) {
-  return i >= 0 && i < tokens.count && tokens.kind[i] !== PUNCT;
-}
-function isWord(tokens, i, word) {
-  if (i < 0 || i >= tokens.count || tokens.kind[i] !== NAME || tokens.end[i] - tokens.start[i] !== word.length) {
-    return false;
-  }
-  const from = tokens.start[i];
-  for (let k = 0;k < word.length; k++) {
-    const code = tokens.source.charCodeAt(from + k);
-    const lower = code >= 65 && code <= 90 ? code + 32 : code;
-    if (lower !== word.charCodeAt(k))
-      return false;
-  }
-  return true;
-}
-function isStatementKeyword(tokens, i) {
-  return i < tokens.count && tokens.kind[i] === NAME && textIs(tokens, i + 1, ":") && !textIs(tokens, i + 2, ":") && !textIs(tokens, i - 1, ":") && !textIs(tokens, i - 1, ".");
-}
-function readBase(tokens, i) {
-  let j = i;
-  while (textIs(tokens, j, "(") && tokens.kind[j] === PUNCT)
-    j++;
-  if (!isName(tokens, j) || isLiteralPrefix(tokens, j))
-    return UNREADABLE_BASE;
-  return textOf(tokens, j);
-}
-function isLiteralPrefix(tokens, i) {
-  if (!(isWord(tokens, i, "f") || isWord(tokens, i, "s") || isWord(tokens, i, "r"))) {
-    return false;
-  }
-  return ["'", '"', "`", "~"].some((quote) => isPunct(tokens, i + 1, quote));
-}
-function readStatementItems(tokens, start, shorthand, onItem) {
-  let atItemStart = true;
-  let i = start;
-  while (i < tokens.count) {
-    if (tokens.kind[i] === PUNCT) {
-      if (textIs(tokens, i, ";"))
-        return;
-      if (tokens.partner[i] > i) {
-        i = tokens.partner[i] + 1;
-        atItemStart = false;
-        continue;
-      }
-      if (textIs(tokens, i, ")") || textIs(tokens, i, "]") || textIs(tokens, i, "}")) {
-        return;
-      }
-      atItemStart = textIs(tokens, i, ",");
-      i++;
-      continue;
-    }
-    if (isStatementKeyword(tokens, i))
-      return;
-    let k = i + 1;
-    if (textIs(tokens, k, "(") && tokens.partner[k] > k) {
-      k = tokens.partner[k] + 1;
-    }
-    if (isWord(tokens, k, "is")) {
-      onItem(textOf(tokens, i), readBase(tokens, k + 1));
-      i = k + 1;
-    } else {
-      if (shorthand && atItemStart) {
-        const name = textOf(tokens, i);
-        onItem(name, name);
-      }
-      i++;
-    }
-    atItemStart = false;
-  }
-}
-function addEdge(map, name, base) {
-  const bases = map.get(name) ?? new Set;
-  bases.add(base);
-  map.set(name, bases);
-}
-function buildJoinBaseMap(query) {
-  const out = new Map;
-  const tokens = tokenize2(stripMalloyCommentsAndLiterals(query));
-  for (let i = 0;i < tokens.count; i++) {
-    if (!isStatementKeyword(tokens, i))
-      continue;
-    if (!/^join_(?:one|many|cross)$/i.test(textOf(tokens, i)))
-      continue;
-    readStatementItems(tokens, i + 2, true, (alias, base) => addEdge(out, alias, base));
-  }
-  return out;
-}
-function buildIsEdgeMap(query) {
-  const out = new Map;
-  const tokens = tokenize2(stripMalloyCommentsAndLiterals(query));
-  for (let k = 1;k < tokens.count; k++) {
-    if (!isWord(tokens, k, "is"))
-      continue;
-    let n = k - 1;
-    if (textIs(tokens, n, ")") && tokens.kind[n] === PUNCT && tokens.partner[n] >= 0) {
-      n = tokens.partner[n] - 1;
-    }
-    if (!isName(tokens, n))
-      continue;
-    addEdge(out, textOf(tokens, n), readBase(tokens, k + 1));
-  }
-  return out;
-}
-function scanIdentifiers(text) {
-  const tokens = tokenize2(text);
-  const names = new Set;
-  for (let i = 0;i < tokens.count; i++) {
-    if (isName(tokens, i))
-      names.add(textOf(tokens, i));
-  }
-  return names;
-}
-function collectIdentifierNames(text) {
-  const names = scanIdentifiers(text);
-  for (const name of scanIdentifiers(stripMalloyCommentsAndLiterals(text))) {
-    names.add(name);
-  }
-  return names;
-}
-var UNREADABLE_BASE = "`", PUNCT = 0, NAME = 1, QUOTED = 2, NAME_CHAR, SPACE_CHAR;
-var init_query_text = __esm(() => {
-  NAME_CHAR = /\p{Alphabetic}/u;
-  SPACE_CHAR = /\s/u;
-});
-
 // src/service/caller_joins.ts
 import { isSourceDef as isSourceDef6 } from "@malloydata/malloy";
 function isCallerAuthored(location, region, authorUrls) {
@@ -276709,6 +276762,25 @@ function isGivenBindingFailure(err) {
   const problems = err?.problems;
   return Array.isArray(problems) && problems.some((p) => isGivenCode(p?.code));
 }
+function queryCompileError(error, callerText) {
+  const problems = locateProblemsInCallerText(error.problems, callerText, AD_HOC_QUERY_PREFIX.split(`
+`).length - 1);
+  return new QueryCompileError(describeProblems(problems, error), problems);
+}
+function describeProblems(problems, error) {
+  const errors2 = problems.filter((p) => p.severity === "error");
+  if (errors2.length === 0)
+    return error.message;
+  return errors2.map(formatProblem).join("; ");
+}
+async function compileErrorOf(runnable) {
+  try {
+    await runnable.getPreparedQuery();
+    return;
+  } catch (error) {
+    return error instanceof MalloyError4 ? error : undefined;
+  }
+}
 function bindingsAllowDegradeToLive(bindings) {
   return bindings.length > 0 && bindings.every((b) => b.origin === "preaggregate" || b.freshnessFallback === "live");
 }
@@ -276801,7 +276873,8 @@ function joinOutline(field) {
     fields: fields.map((inner) => inner && typeof inner === "object" ? joinOutline(inner) : inner)
   };
 }
-var MALLOY_VERSION, REQUEST_CHAIN_MAX_NAMES = 64, NO_PREAGGREGATE_VIOLATIONS, Model, SOURCE_IDENTITY_KEYS;
+var MALLOY_VERSION, REQUEST_CHAIN_MAX_NAMES = 64, AD_HOC_QUERY_PREFIX = `
+`, NO_PREAGGREGATE_VIOLATIONS, Model, SOURCE_IDENTITY_KEYS;
 var init_model = __esm(() => {
   init_telemetry();
   init_materialization_metrics();
@@ -276863,6 +276936,7 @@ var init_model = __esm(() => {
     compilationError;
     filterMap;
     givens;
+    notebookCellDeclaredGivens = [];
     declaredQueryMetadataMemo;
     declaredSourceQueryMetadataMemo;
     preaggregateViolationsMemo;
@@ -276902,6 +276976,15 @@ var init_model = __esm(() => {
       this.compilationError = compilationError;
       this.filterMap = filterMap ?? new Map;
       this.givens = givens;
+      this.notebookCellDeclaredGivens = (this.runnableNotebookCells ?? []).map((cell) => {
+        if (!cell.modelDef)
+          return;
+        const registry = cell.modelDef.givens ?? {};
+        return {
+          ids: new Set(Object.keys(registry)),
+          names: new Set(Object.values(registry).map((g) => g.name))
+        };
+      });
       try {
         this.entryPointGatesBySource = this.computeEntryPointGatesBySource();
       } catch {
@@ -276994,18 +277077,23 @@ var init_model = __esm(() => {
     getAccessFilter(sourceName) {
       return this.sources?.find((source) => source.name === sourceName)?.accessFilter ?? [];
     }
-    filterGivensToModelSurface(givens) {
+    filterGivensToModelSurface(givens, cellDeclared) {
       if (!givens)
         return givens;
       const surfaceNames = new Set((this.givens ?? []).map((g) => g.name));
       const filtered = {};
       for (const [name, value] of Object.entries(givens)) {
         const authorizeOnly = !surfaceNames.has(name) && this.authorizeReferencedGivenNames.has(name);
-        if (!authorizeOnly)
+        const outOfCellScope = cellDeclared !== undefined && surfaceNames.has(name) && !cellDeclared.names.has(name) && !this.cellDeclaresGivenId(name, cellDeclared);
+        if (!authorizeOnly && !outOfCellScope)
           filtered[name] = value;
       }
       return filtered;
     }
+    cellDeclaresGivenId(surfaceName, cellDeclared) {
+      const entry = this.modelDef?.contents[surfaceName];
+      return entry?.type === "given" && cellDeclared.ids.has(entry.id);
+    }
     computeAuthorizeReferencedGivenNames() {
       const names = new Set;
       const addExprs = (exprs) => {
@@ -278174,6 +278262,19 @@ var init_model = __esm(() => {
       }
       return "deferred";
     }
+    queryTextSourcesQueryable(query) {
+      const queryable = (name) => this.isCuratedSource(name) || this.derivesFromCurated(name, query);
+      const runTargets = extractRunTargetSourceNames(query);
+      if (runTargets.length === 0)
+        return false;
+      if (!runTargets.every(queryable))
+        return false;
+      for (const declared of buildDerivationBaseMap(query).keys()) {
+        if (!queryable(declared))
+          return false;
+      }
+      return true;
+    }
     assertQueryBoundaryCompiled(compiledSource, query, derivationContext) {
       const { mode, exploresDeclared } = this.queryBoundary;
       if (mode === "all" || !exploresDeclared)
@@ -278847,6 +278948,23 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
         });
         throw new BadRequestError(`Invalid query: ${errorMessage}`);
       }
+      if (!sourceName && !queryName && query && liveRunnable && runnable === liveRunnable) {
+        const compileError = await compileErrorOf(liveRunnable);
+        if (compileError && !isGivenBindingFailure(compileError)) {
+          if (boundary === "deferred" && !this.queryTextSourcesQueryable(query)) {
+            const explainable = extractRunTargetSourceNames(query).some((t) => this.declaresSource(t) && !this.isCuratedSource(t) && !this.derivesFromCurated(t, query));
+            throw this.notQueryable("Query target is not queryable.", explainable, "source");
+          }
+          this.queryExecutionHistogram.record(performance.now() - startTime, this.queryMetricAttributes({
+            environment: queryMetadataInput?.environment,
+            queryName,
+            sourceName,
+            status: "error",
+            servedFrom
+          }));
+          throw queryCompileError(compileError, query);
+        }
+      }
       const compiledSource = await this.resolveAuthorizeSourceFromRunnable(runnable);
       if (boundary === "deferred") {
         this.assertQueryBoundaryCompiled(compiledSource, query);
@@ -279259,7 +279377,7 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
           const cellMaxRows = getMaxQueryRows();
           const cellMaxBytes = getMaxResponseBytes();
           const buildManifest = this.withoutPreaggregateEntries(this.resolveFreshBuildManifest());
-          const cellSurfaceGivens = this.filterGivensToModelSurface(givens);
+          const cellSurfaceGivens = this.filterGivensToModelSurface(givens, this.notebookCellDeclaredGivens[cellIndex]);
           const preparedCell = await runnableToExecute.getPreparedResult({
             givens: cellSurfaceGivens,
             buildManifest
@@ -301724,6 +301842,7 @@ function recordDashboardWrite(outcome, durationMs) {
 
 // src/controller/dashboard.controller.ts
 init_path_safety();
+init_query_text();
 function outcomeOf(error) {
   if (error instanceof WriteConflictError)
     return "conflict";
@@ -301734,10 +301853,6 @@ function outcomeOf(error) {
   return "refused";
 }
 var DASHBOARD_FILE = /^dashboards\/[^/]+\.malloy$/;
-var describeProblem = (problem) => {
-  const start = problem.at?.range?.start;
-  return start?.line === undefined ? problem.message : `line ${start.line + 1}:${(start.character ?? 0) + 1} ${problem.message}`;
-};
 var contentHashOf = (text) => createHash2("sha256").update(text, "utf8").digest("hex");
 
 class DashboardController {
@@ -301786,7 +301901,7 @@ class DashboardController {
     const { problems } = await environment.compileSource(packageName, modelPath, body.source, false, undefined, "file");
     const errors2 = problems.filter((problem) => problem.severity === "error");
     if (errors2.length > 0) {
-      throw new CompileRefusedError(`The dashboard does not compile, so it was not written: ` + errors2.map(describeProblem).join("; "));
+      throw new CompileRefusedError(`The dashboard does not compile, so it was not written: ` + errors2.map(formatProblem).join("; "));
     }
     const { previous } = await environment.writeModelFileTransactional(packageName, modelPath, body.source, (current) => {
       if (body.expectedHash === undefined) {
@@ -321492,7 +321607,7 @@ a permanent parallel mechanism.`
     {
       name: "eval-answer/ledger-schema",
       description: "The eval ledger: files and events. Reference detail for the eval-answer skill.",
-      body: "# The eval ledger: files and events\n\nThe ledger is plain files in the model package's git repository. There is no\neval API and no eval database. The conductor (`skill:eval-loop`) reads and\nwrites these files directly; the stages share them as their contract.\n`eval-answer` writes `attempt`, `tool_call`, and `score`. An engine-side\n`eval-retrieval` skill, which does not ship here, writes `retrieval_score` and\n`probe`; both stay in this contract so one validator covers every run\ndirectory.\n`eval-diagnose` writes `issue` and `issue_status`. `eval-improve` writes\n`candidate`. `eval-loop` writes `acceptance_check`, further `issue_status`, and\n`checkpoint`.\n\n**The contract is code: `eval-answer/scripts/ledger.py`.** Every script that\nwrites `run.json` or `events.jsonl` builds its lines through that module, so a\nfield rename that reaches only one writer fails at write time. This document\nis the human-readable rendering; where the two disagree, the module is right\nand this file is the bug. Check any run directory with:\n\n```\npython3 skills/eval-answer/scripts/ledger.py validate <runDir>\n```\n\nErrors are broken identity (missing `run.json`, a missing required field, two\nscores for one attempt); warnings are missing comparison pins (a run without\n`skillsVersion` still measures, but cannot anchor an A/B on that pin) and\ngrandfathered unknown fields on old runs.\n\n## Layout\n\n```\nevals/<set>/\n  set.json                  # set metadata (below)\n  cases.jsonl               # one case per line\n  judge-regressions.jsonl   # judge verdicts a human overruled\n  runs/<runId>/\n    run.json                # run config, the attribution pins\n    events.jsonl            # append-only event lines\n    artifacts/              # prediction CSVs, judge outputs, transcripts\n```\n\nThe set directory lives in the SAME git repository as the model it evaluates,\nso a checkpoint (a git commit) pins the model and the ledger together. Never\nplace `evals/` inside the directory tree the answerer's package serves: gold\nin the served tree is a contamination path.\n\nRules that make the ledger trustworthy:\n\n- `events.jsonl` is append-only. Never edit a line. To void one, append a new\n  event whose payload marks the old one `voided`. One sanctioned exception: a\n  re-runnable stage (diagnose, improve) replaces ITS OWN prior events, keyed by\n  issue id, through `ledger.replace_events()` -- so a crash-and-rerun does not\n  duplicate issues. A stage never touches another stage's lines.\n- A stage never rewrites another stage's fields.\n- One artifact directory per attempt (`qid` plus `sample`). Never overwrite a\n  previous attempt's prediction CSV.\n- End-of-run numbers come from counting event lines (`jq` over\n  `events.jsonl`), never from arithmetic recalled in prose.\n\n## `set.json`\n\n| Field | Notes |\n|---|---|\n| `name` | Set name; also the directory name. |\n| `description` | |\n| `datasetVersion` | Integer. Bump on any golden repair or case change. Runs record the version they scored against. |\n| `targetModelPath` | Model path within the package. |\n| `truthPackage` | Name of the package holding the semantics-free sources every golden is re-derived from -- a package NAME, not an object. Without it `verify_goldens.py` re-derives nothing: it reports \"nothing to re-derive against\" and **exits 3**, which a caller must read as unverified rather than as a pass. The checks that need no truth server -- rubric figures, verification axis, stale rubric claims, set names -- still run and still report. `init_truth_package.py` scaffolds the package. |\n| `truthModel` | Model file inside that package. Default `truth.malloy`. |\n| `targetPackage` | Name of the package UNDER TEST. `verify_goldens.py` refuses a \"truth\" server that also serves it, because an answerer on that server can retrieve the raw truth sources beside the model and quietly change what is under test. `run_baseline.py` and `improve.py` pass the package they were given, so this field is the fallback for a direct call; without either the guard cannot fire. |\n| `truthTableRewrite` | Boolean, default false. Rewrites `duckdb.table('data/x.parquet')` refs to bare `x` in canonical queries, for a truth package whose tables are registered rather than read from files. |\n\n## `cases.jsonl`\n\nOne JSON object per line:\n\n| Field | Notes |\n|---|---|\n| `qid` | Stable case id. |\n| `question` | Exact text the answerer will see. |\n| `split` | `dev` or `holdout`. Frozen at import. Diagnose and improve read `dev` only; the acceptance check runs both. |\n| `tags` | list |\n| `state` | `candidate` / `selected` / `excluded`. |\n| `source` | Where the case came from. |\n| `golden` | `status` (`verified` / `provisional` / `invalid` / `ambiguous` / `verified_wrong`, the last being a key a person has established is wrong, which `run_baseline.py` drops from every aggregate), `kind`, `value` or `path` (artifact under the set directory), `canonicalQuery` (runs against the **truth** package, never the model under test), `verifiedBy`, and `verification` -- `{primaryAxis, variesAxis, note}` naming what the second derivation varied. **A golden is written only after two differently shaped derivations agree** (the truth query and a second one that varies a different axis -- group by something else, sum a different way, take a different route through the raw tables); `gold/<qid>.json` holds both (`truthRows`, `verifyRows`, `agreement`). Two derivations that vary the same axis share every other blind spot: that is how a golden that summed three overlapping time slices, 3x too high, passed its check. `verify_goldens.py` re-derives the value, reads the accepting clause of the rubric against the rows, and flags a second derivation that names no axis. **The question asks for data, never for an interpretation of it**, and either fixes the grain or the rubric accepts a correct figure at any stated grain (`skill:eval-judge` rules 10 and 11). |\n| `golden.kind` | What the key IS. A value (`scalar`, rows), `unanswerable`, or `criteria`: prose with no value, where the author's criteria are the whole key. `criteria` is the one kind that is legitimately `verified` on arrival, because there is no derivation to perform and nothing that can be numerically wrong; an imported key holding a VALUE is `provisional` until re-derived (`skill:eval-import`). **`verify_goldens.py --promote` is the only thing that writes `golden.status`**: it marks a `provisional` golden `verified` when its value re-derived cleanly from the truth package AND a second derivation exists. `--refresh` rewrites a drifted VALUE and never changes a status; `invalid` and `ambiguous` are settled by a person through the golden side door. |\n| `golden.rubric` | **On the golden, not on the case.** The prose the judge is shown as `CASE RUBRIC`, naming what counts as correct and what does not. `run_baseline.py` reads `golden.rubric`; a rubric written at the case's top level is silently not passed, the judge is told `CASE RUBRIC: none`, and it then scores from the golden value and the answer alone -- which reads as a judge that ignores its instructions. |\n| `golden.mustState` | **On the golden, not on the case.** What the answer has to say out loud. Read from `golden.mustState` by the run-package builder. |\n| `goldenRevision` | Integer. Bump on every golden change; `score` events stamp the revision they compared against. |\n| `expectedEntities` | `required`: entity ids (`kind:source:name`) the answer cannot be produced without. `requiredAnyOf`: a list of **groups**, each a list of ids of which any one suffices -- for a case the model can answer through more than one route. Naming only one route scores the other as a retrieval miss and steers the fix to the docs for an entity whose docs were never the problem. `acceptable`: ids that are not noise if returned. An entity counts as delivered when returned under its exact id, under the same type and name on a sibling source, or by name in a returned source's documentation; `score_retrieval.py` records the route per entity as `delivery`. |\n\n## Term files (`eval-retrieval` only)\n\nA customer set has no term file. The engine-side `eval-retrieval` skill keeps\n`intents.jsonl` fixtures -- search term, entity type, a description of what the\nsearcher meant, a validity flag -- beside its own scripts, for evaluating the\nengine against fixed inputs. Their shape and the `retrieval_score` events they\nproduce are documented there and validated here.\n\n## `run.json`\n\nThe attribution pins. Two runs are comparable only when these match where it\nmatters. Two runs with different `target` values are comparable on answer\nverdicts only if the same model version reached both, which is rarely worth\nassuming:\n\nRequired fields are the run's **identity** -- every run ever written carries\nthem. The rest are optional in the schema, but the **comparison pins** are\nwarned about when absent, because a run missing one cannot take part in an A/B\non that axis.\n\n| Field | Notes |\n|---|---|\n| `runId` *(required)* | Directory name. |\n| `target` *(required)* | Which server answered, and how it reached the data: `local`, `local-proxied`, or `platform`. Decides what an improve step is even allowed to do (see `skill:eval-loop`). |\n| `answererModel` *(required)* | |\n| `phase` / `started` *(required)* | |\n| `judgeModel` / `judgeVersion` / `rubricSha` *(pins)* | The judge's model, and the version + content sha of `skill:eval-judge`. |\n| `judgePromptSha` *(pin)* | Content sha of the prompt the judge is SHOWN, which is the harness's own template and not the skill file `rubricSha` covers. The template carries the golden rendering, the evidence blocks and the tie-breaking rules, so two runs whose prompts differed compared as the same judge -- the blind spot that let a golden-rendering defect run through three arms with every test passing, because the tests covered the code paths and not the text the model sees. Absent on runs written before it existed. |\n| `datasetVersion` *(pin)* | From `set.json` at run time. |\n| `modelSha` *(pin)* | Content sha of the `model.malloy` snapshot in the run directory -- the bytes the answerer actually queried. A git sha is not enough: a snapshot host serves a copy, often of a dirty tree no commit names. |\n| `skillsVersion` *(pin)* | HEAD of the checkout the agents' skills were loaded from, dirty-marked (`ledger.skills_git_sha(root)`). The skills are the doctrine the agents load; a run that cannot name their version cannot anchor a skills A/B. |\n| `skillsRoot` / `harnessVersion` | Which checkout supplied the doctrine (`--skills-root`, e.g. a Publisher checkout for the open-source skills; default this one), and this checkout's own HEAD. The eval-* skills always come from the harness checkout, whatever `skillsRoot` says. Two runs whose `skillsRoot` differ are a skills A/B only if their manifests name the same skills. |\n| `diagnoserModel` / `improverModel` | Written by `diagnose.py` / `improve.py` when those stages run, so the run names every LLM that touched it. Absent on a run that was only answered and judged. |\n| `modelGitSha` | Commit of the model repo, from `--model-repo`; `-dirty` suffix when that path had uncommitted changes -- fine for a band measurement, not for an A/B pin. **Null unless `--model-repo` names the repo.** It cannot be inferred: Publisher serves a COPY under `publisher_data/`, so the tree around the served file is the server's storage, not the model's history, and the field named that until 2026-09-03. `modelSha` above is the pin that always works; this is the pointer to where those bytes are versioned, and absent beats wrong. |\n| `modelRepo` | The path `--model-repo` named, so a reader can tell an absent pin from an unrecorded one. |\n| `modelDir` | The package directory `--model-dir` named, when it was: the path the `-dirty` marker on `modelGitSha` was decided over. Absent means the whole repo, where any unrelated untracked file marks the model dirty. |\n| `environment` / `package` / `modelPath` | What was served, and from where. On a platform target `environment` is the organization and `package` is the workspace the MCP URL is scoped to. |\n| `scope` | Platform target only: the `environment/package[@version]` the answerer was told to pass as an explicit `scopes` entry on every `get_context` / `execute_query` call. A workspace can serve many packages (a personal workspace serves every package the user can read), so without this the run also measures whether retrieval picks the right package -- a different measurement. Absent means unscoped. |\n| `targetVersion` *(pin)* | Platform target only: the published version the answers came from. Both hosted tools default an omitted version to the PINNED one, meaning whatever the workspace serves at the moment of the call, so this only describes the run when `--scope` carries it to every call. `--target-version` supplies it when the scope omits it; a scope naming a different version is refused rather than treated as an override, because a run cannot say which build answered if two pins disagree. |\n| `mcpUrl` / `publisher` | The endpoints the answerer and the re-execution used. |\n| `predictionsReExecuted` | Whether re-execution was POSSIBLE: the server was serving the bytes this run is pinned to. It is one bool for the whole run and says nothing about any given query, so it reads stronger than it is; `reExecution` below is what actually happened. |\n| `reExecution` | `{attempted, ok, failed, noQuery, notReExecuted, notJudged, missing}` over the run's predictions. `failed` means the query ran and the server returned an error, which is a different thing from an answer with no query at all. `notJudged` is a case the judge was never handed: a golden refused before judging (`provisional`, `invalid`, `ambiguous`, `verified_wrong`, missing), an attempt that submitted nothing, or every case under `--no-judge`. Those used to land in `missing` and read as corrupt artifacts on a freshly imported set. `ok`, `failed`, `noQuery`, `notReExecuted`, `notJudged` and `missing` partition the cases, so they sum to the case count; `attempted` is `ok + failed` and sits outside that sum. |\n| `retrievalMode` | Which retriever answered: `semantic`, `lexical`, `mixed` (it changed mid-run, so nothing can be averaged across it) or `unreported` (nothing ranked, which on a configured server means no embedding provider). Only a RANKING call names a retriever, so a call that enumerates a type or looks a name up is `unreported` on a fully semantic server and must not make the run read as `mixed`. Local retrieval degrades to lexical SILENTLY without an embedding key, and a pair compared across that reads as a model change, so `flip_table.py` refuses the pair unless both sides match. |\n| `retrievalCalls` | `{semantic, lexical, unreported}` call counts behind `retrievalMode`. `unreported` counts the calls that did not rank, which is a different thing from calls that fell back. |\n| `retrievalGate` | What the pre-arm retrieval gate found, or why it did not run. A run is held until `get_context` answers semantic twice in a row, because the first calls after a restart are lexical by design and an arm started immediately measures two retrievers. `not run (no answering phase)` under `--rebuild`/`--rejudge`, and `skipped by --no-retrieval-gate` when the operator opted out -- which is a different fact from a gate that passed, and the field is what tells them apart. |\n| `coverageReport` | The `check_coverage.py --out` report this run read, when `--coverage` named one: its path, the model version it was stamped with, its `agentModel`, and `decided` of `cases`. Coverage is a read of the MODEL, so it is measured separately and costs a judge call per case; the run does not run it, it consumes it. Its per-case verdict then beats the authored `coverage` label in retrieval attribution, and each `score_retrieval` row records `coverage_source` (`measured`, `authored`, `none`) so nobody has to guess which one charged the failure. Absent when no report was given, which is a different fact from a report that found everything covered. |\n| `label` | `<set>-<phase>-<nn>`, assigned by `run_baseline.py` from the set name, the run's phase and the next free number beside it (`ecommerce-baseline-01`, `ecommerce-baseline-02`, `ecommerce-blind_gate-01`). The A/A pair is two runs of the same phase; the post-edit arms are two runs of `blind_gate`. Hand-typed names do not survive one afternoon of runs -- `base`, `rejudged2`, `r3`, `post1` sort wrongly, group not at all, and cannot be matched to an arm. `--label` overrides for a run that genuinely needs a human name. |\n| `effort` | |\n| `maxTurns` / `answererTimeout` *(pins)* | The answerer's turn cap and per-attempt timeout, as the arm ran them. `skill:eval-loop` step 6 lists the call budget among the pins to freeze for a whole run, and nothing wrote one, so no two runs could be compared on the setting that decides whether a case got to finish at all. Distinct from `callBudget`, which no harness has ever written. Size the cap from a pilot rather than taking the default: on a 29-case arm at the default 30, completed attempts had a median of 17 turns and a 90th percentile of 26, and the four cases that ran past it were recorded as wrong answers. |\n| `truncated` / `contaminated` | The qids excluded for a HARNESS-owned reason: the cap cut the answer off, or the attempt breached isolation. Both leave the denominator, both are named here rather than only in the console, and either one makes `status` `incomplete`. |\n| `answererCostUsd` / `judgeCostUsd` | What the arm cost, split by role. The judge's half was discarded until 2026-09-02, so every \"cost per arm\" quoted before then was the answerer alone. Per-case judge cost is on each `score` event. |\n| `answererCostCopiedFrom` | The run whose attempts `answererCostUsd` was COPIED from, when this run spawned no answerer -- a `--rejudge`, a `--rebuild`, a `--from`. Those copy the source's attempt events verbatim, `cost_usd` included, so the figure is right about the attempts and wrong as this run's spend: one re-judge reported $17.56 of answering that never happened. Null when this run paid, so a total over several run files can skip the copies. |\n| `goldenCheck` | What `verify_goldens.py` said before the run started: `N ok, M drifted, K other finding(s)`, or why it did not run (no truth server on a platform target; `--skip-golden-check`; rebuild). A run that started on a drifted set says so here rather than pretending its verdicts mean something. `run_baseline` calls `verify()` without a model, so the set-name audit (check 5) does not run in-arm; the trailing `N stale entity name(s)` is the in-arm lint's own count, and `entity-name lint not run` says there was no model text to lint against. Without it the field read `0 other finding(s)` for a check that never happened. |\n| `staleEntityNames` | The `expectedEntities` names that appear nowhere in the served model, from the in-arm lint. Each one depresses the run's own recall on every case listing it, so a stale set reads as a retrieval failure until someone checks by hand. `null` when there was no model text to lint against (a platform target), which is a different fact from `[]`. |\n| `status` | `complete`; `aborted` when four consecutive attempts errored or found the server dead and the harness stopped rather than spend the rest of the budget on attempts nobody will trust; or `incomplete` when the arm ran to the end and still cannot report a rate, because `truncated` or `contaminated` is non-empty. `incomplete` is a third state, not a soft `complete`: the arm did everything asked of it and the number is still unearned. It does NOT stop the run being compared: `flip_table.py` scores the cases both arms did, and names the ones this arm left unscored -- an excluded case carries no verdict, so it can never be counted as a flip. |\n| `packageSha` / `servedRevision` *(pins)* | Taken from the server, not recomputed: `sourceContentSha` is a content hash over EVERY model path in the package, so an edit to an imported file moves it where a sha of the one `--model-path` does not; `servedRevision` is minted per load, so it identifies a load rather than content and is a poor pin alone. Measured: `publisher.json`'s `version` moves neither, and nothing in Publisher reads it -- it is not in the Package API schema and never returned, so it pins nothing. |\n| `datasetSha` *(pin)* | Content hash of `set.json` + `cases.jsonl`. Deliberately SEPARATE from the model's sha: a golden repair is not a model change, and one pin covering both would make every answer-key fix read as an edit to the model, which is the distinction an A/B rests on. Automatic, so nobody has to remember it; `datasetVersion` stays beside it as the human-readable sequence. **Local targets only.** A hosted target that publishes IMMUTABLE versions needs none of this: the set rides inside the version, and immutability -- not hashing -- is what makes a pin trustworthy. There, `targetVersion` alone identifies model and set together. |\n| `doubtedGoldens` | The cases whose golden is not believed: `qid`, `gold_status` (`suspect` or `verified_wrong`), `gold_note`, and `declaredBy` (`judge` or `set`). A status the SET declared is a key somebody already settled, not an opinion the judge formed this run, and attributing both to the judge claimed a judgement that never happened. **Read this before diagnose.** These are dataset issues, not model failures, and they go through the golden side door in `skill:eval-loop`. Empty list when no key is in doubt from either source. Written from the same scan that prints the end-of-run warning, because a warning that lives only in console text is one scrollback away from sending a modelling agent at a model that is already right. |\n| `mode` / `setName` / `serverVersion` / `traceMode` / `callBudget` | Defined and accepted, **not yet written by any harness** -- kept in the schema for the platform target and the conductor, which need them. (`targetVersion` and `status` were in this list and are both written now.) |\n\n## Events\n\nEvery line in `events.jsonl` is **flat**: `{ \"kind\": ..., <fields> }`, one\nJSON object per line, with an optional `at` ISO timestamp. Case-scoped kinds\n(`attempt`, `tool_call`, `score`) carry `qid`, `sample`, `phase` on the line;\nrun-level kinds do not. (An earlier draft of this document nested fields under\na `payload` with a `caseId`; no writer ever did that, and 23 run directories\nexist in the flat shape, so the flat shape is the contract.) `kind` is one of:\n`attempt`, `tool_call`, `score`, `retrieval_score`, `issue`, `issue_status`,\n`candidate`, `acceptance_check`, `checkpoint`.\n\n### `attempt`\n\n| Field | Type | Notes |\n|---|---|---|\n| `qid` | string | |\n| `sample` | int or null | Which repeat. Required even when null. |\n| `phase` | string | `baseline` / `loop` / `blind_gate` / `canary` / `final`. `phase` lives here, on the attempt, not in run config. |\n| `question_sha` | string | Hash of the exact text the answerer saw, so two runs can be compared on whether they asked the same thing. A case may carry `questionSha`, the seal stamped at conversion, and that wins when present; the ecommerce set writes a 16-char prefix of it, and a set without one left this null. Neither form proves the question was not edited, since both follow the case as it now reads: that comparison is check 6 of `verify_goldens.py`. |\n| `submitted` | bool | False when there was no final query. Not a wrong answer. |\n| `final_query` | string or null | Required to replay. A named view is recorded as the Malloy it stands for, `run: <source> -> <view>`, so every consumer sees one shape and the query re-executes. |\n| `final_query_source` | string or null | How `final_query` was chosen: `declared` (the answer printed it), `last_ok` (the last call the server answered) or `last`. `last` is a warning: a trailing sanity probe may be standing in for the answer's own query. |\n| `servedRevision` | string or null | From the package actually queried. |\n| `n_get_context` / `n_execute` / `n_execute_errors` | int | |\n| `host_tool_uses` | int | EVERY tool use the host logged, MCP calls included. It counted only the non-MCP ones until 2026-09-03, which made the under-report check below true of almost every clean attempt. |\n| `mcp_tool_uses` | int or null | The MCP subset: `get_context` plus `execute_query`. Null on a run written before the split. |\n| `reported_calls` | int | MCP calls the answerer claimed. `reported_calls > host_tool_uses` is the under-report floor from `skill:eval-answer`: the answerer cannot have made more calls than the host logged. `validate_run` warns on it, and only for runs that carry `mcp_tool_uses`, because the field meant something narrower before. |\n| `contaminated` | bool or `\"unknown\"` | `\"unknown\"` when no host log exists. Read it with `ledger.is_contaminated`, never for truthiness: runs written before 2026-09-03 carry the strings `\"true\"`/`\"false\"`, and `bool(\"false\")` is True. `ledger.event` now rejects those strings on write; `validate_run` grandfathers them on read as a warning. |\n| `contamination_reasons` | list | Empty when clean. |\n| `input_tokens` / `output_tokens` / `cache_read_tokens` / `cache_write_tokens` | int or null | Answerer token usage, the four counts that reprice a run from its own ledger. Null when the host does not report it. `cost_usd` beside them comes from the CLI's `total_cost_usd`, which prices cache reads and writes at their rates, so it was always cache-inclusive; what was missing was the breakdown that reproduces it. `cache_write_tokens` (`cache_creation_input_tokens` upstream) was never captured before 2026-09-15, and on one analysed run cache writes were 44% of the agent's cost, the single largest line. **Read `input_tokens` with care:** it counts only the tokens after the last cache breakpoint. One run recorded 224 for 24 questions beside 2.4M cache reads; the 224 is not the context volume, and a token total that omits the cache columns is not a size. |\n| `cost_usd` | float or null | Answerer cost for this attempt. |\n| `num_turns` / `wall_seconds` | int, float or null | |\n| `answer_text` | string or null | The answer the judge scored. Kept so a verdict can be re-read without the transcript. |\n| `skills_invoked` | list of string | The skills the answerer invoked through the `Skill` tool, deduplicated and sorted, counted from its own transcript. Always a list on a run that recorded it, so an EMPTY list is the finding: the arm granted a manifest and the agent reached for none of it. Absent on runs written before 2026-09-15, which is why every reader takes `or []`. Only explicit `Skill` calls are counted, and only skills the arm granted -- one outside `--answerer-skills` is a contamination breach and lands in `contamination_reasons` instead. What it is for: a manifest names what an arm GRANTED, and comparing two arms' doctrine is meaningless if the doctrine never loaded. |\n| `transcriptPath` | string | The answerer's transcript under `artifacts/`. |\n\nToken counts sit here rather than being derived later because the claim a\nsemantic model makes is about cost as well as correctness -- that a documented\nmodel reaches a good answer in fewer turns and tokens than working from raw\nschema. A ledger that counts calls but not tokens can state half of that.\n\n### `tool_call`\n\nOne event per MCP `get_context` or `execute_query` the attempt made.\n\n| Field | Type | Notes |\n|---|---|---|\n| `tool` | string | `get_context` or `execute_query`. |\n| `traceId` | string or null | `get_context` only; look up in your host's trace store. |\n| `targets` | string, list or null | **What the answerer asked for**: the search terms it sent to `get_context`. Null for `execute_query`. |\n| `rankedSummary` | object | Copied at capture so evidence survives trace eviction: `entityIds` (identity, in response order), `hits` (one row per entity: `entity_id`, `source`, `relevance`, `matched_targets`, `position`, `position_in_source`), `resultCount`, `docTokens`. **There is no rank.** This field previously documented `ranks` and \"per-target `targets` with within-target ranks\"; no writer ever wrote either, and what `ranks` did hold was `range(1, n+1)` over a list already flattened source-card by source-card -- a position, not a rank, and not even a relevance order, since the response sorts globally and then buckets into cards. Ask relevance questions of `hits[].relevance`. |\n| `rankedSummary.hits[].matched_targets` | list or null | Which of the caller's search targets matched this entity, each with the server's own relevance. **`null` means no attribution was published**, which is not the same as `[]`: the server attaches it to entities only (a source card's attribution is discarded before an entity object exists) and only on the semantic path, because a lexical score is relative to its own query and comparing two of them means nothing. A lexical run therefore cannot say which target found what, and a reader must report that as unavailable rather than as \"never asked\". |\n| `retrieval_mode` | string or null | `get_context` only: the `retrieval` field of the response that answered, `semantic` or `lexical`. Null when the server named none, which means no embedding provider. Recorded per call because the semantic path can fall over partway through a run. |\n| `query` | string or null | `execute_query` only: the Malloy the call sent, so the final query can be chosen by which call the server actually answered. |\n| `modelPath` | string or null | `execute_query` only: the model file the call named. A source does not resolve outside the file that declares it, so re-execution needs this. |\n| `error` | string or null | |\n\nNever persist `execute_query` result rows, givens, or credentials.\n\n`targets` records the request; `rankedSummary` records the response. Without\nboth, a low per-attempt recall has two readings that cannot be told apart: the\nanswerer searched for the wrong thing, or it searched well and retrieval ranked\nthe right entity too low. Those have opposite owners -- `agent-skill` and\n`retrieval` -- so a ledger holding only the response cannot attribute the\nfailure, and any recall computed from it is a blend of answerer behaviour and\nretrieval quality.\n\nThat blend is also why per-attempt recall is **not** comparable across arms: a\nstronger answerer searches better and scores higher retrieval recall without\nretrieval having changed. Use it for attribution within an arm. Comparing\nretrieval itself between engine versions is `eval-retrieval`'s job, with fixed\nterms, and is not something a customer run reports.\n\n### `score`\n\nThe answer judge's verdict for one attempt (protocol in\n`skill:eval-judge`). Every attempt in a scored run gets exactly one.\n\n| Field | Type | Notes |\n|---|---|---|\n| `verdict` | string or null | `match` / `near_match` / `no_match` / `needs_human`; null when the attempt is not scorable. Only `match` and `no_match` are decisions; see below. |\n| `reason` | string | Why, from the judge; for a null verdict, why not scorable, and it is ALWAYS one of these: `not_submitted`, `answerer_truncated`, `contaminated`, `judge_unparseable`, `no_saved_verdict`, `judge_error: <text>`, or `golden_<status>` -- `golden_missing`, `golden_provisional`, `golden_invalid`, `golden_ambiguous`, `golden_verified_wrong`. A null verdict never arrives without one: a nulling that does not say which of these it was is indistinguishable from the field being dropped on the write path, and was read as exactly that from a real run. The `golden_*` reasons and `answerer_truncated` are decided before the judge is called, so neither an unestablished key nor a cut-off attempt costs a judge call. |\n| `confidence` | int or null | 1 to 10. Confidence of 5 or lower forces `needs_human`. |\n| `column_pairing` | object or null | The judge's named gold-to-prediction column correspondence. |\n| `judge_version` / `rubric_sha` | string | Pins which rubric produced this verdict. |\n| `golden_revision` | int | From the case at score time. |\n| `contaminated` | bool or `\"unknown\"` | Copied from the attempt; true or unknown means `verdict: null`. |\n| `must_not_use_hits` | list or null | Entries of `golden.mustNotUse` a script found in the final query. A hit forces `verdict: no_match`. Decided by `check_must_not_use.py`, never by the judge: it is a question about query text. Only a BARE name vetoes; an entry with a connective (`X as ...`, `X through ...`) objects to a use of X rather than to X, and goes to the judge with the prose entries and a path's bare leaf. |\n| `judge_verdict` | string or null | What the judge said when a MECHANICAL override replaced it: a `must_not_use_hits` veto, or contamination voiding the verdict. Null otherwise, so the judge's own agreement rate stays measurable across both. When a case is vetoed AND contaminated this still holds the judge's read, not the veto's `no_match`. |\n| `artifactPath` | string | The full judge output under `artifacts/`. |\n| `gold_status` | string | `verified` / `verified_benign` / `suspect` / `verified_wrong`, and never anything else: the case file's `golden.status` is a DIFFERENT vocabulary that shares only `verified` and `verified_wrong`, and only those two fall back into this field. A `provisional` / `invalid` / `ambiguous` key is reported through the verdict's `reason` (`golden_<status>`) instead, so nothing downstream has to match on two vocabularies in one field. **From the judge**, which scored against the golden as written and reports separately whether it believes it; falls back to the case's standing `golden.status` when the judge does not say, written onto the verdict itself so the run summary and the aggregates see it too. `verified_wrong` excludes the case from run aggregates -- from the judge OR from the case file; assigning the fallback into a copy of the verdict meant a key the set had marked wrong stayed in the aggregates unless the judge independently agreed. `suspect` and `verified_wrong` route to the golden side door as `dataset` issues, never to improve. |\n| `gold_note` | string or null | The judge's evidence for a non-`verified` status: the two values, or the model line against the rubric sentence. Null when `verified`. |\n\nA `golden_*` reason means the ANSWER KEY is not something a verdict can be\nissued against. A golden the set stamps `provisional`, `invalid` or `ambiguous`\nis refused, as is a case with no golden at all and one the set marks\n`verified_wrong`; a golden with NO `status` is unguarded rather than\nunscorable, because sets that predate the field would otherwise score zero of\nzero. A golden holding no value is not refused either: that is how a\n`kind: unanswerable` case and a `kind: criteria` golden are written. This\nmatters most for an imported set, because `skill:eval-import` stamps\n`provisional` on every golden it writes and enforces it -- so a set is\nunscorable by construction until its keys are re-derived, and `run_baseline`\nrefuses to spend at all when every case in a set is in that state.\n\n`not_submitted` means the attempt produced NOTHING to judge: no answer text and\nno query. An attempt that wrote prose without querying **is judged**, and\nagainst a golden that holds a value an answer containing none of it is\n`no_match` (`skill:eval-judge`, `reference/refusal.md` rule 10). Excusing those\nas unscorable dropped a confident refusal on an answerable case out of the pass\nrate, which is the one thing the answerable-sounds-unanswerable cases exist to\nmeasure. A refusal is exempt only where `golden.kind` is `unanswerable`, and\nthere naming the gap is the pass and a confident number is the fail.\n\n`answerer_truncated` means the answerer hit the run's `maxTurns` cap and the\nCLI returned whatever it had, which is usually a sentence stopping mid-thought.\nIt is refused BEFORE the golden gate and before a saved verdict is reused, so\n`--rebuild` over a run made without this re-derives the right ledger from its\ntranscripts. A cap is a harness setting, so a case cut off by one says nothing\nabout whether the model could answer it: measured on one 29-case arm, four\nattempts ended at exactly 31 turns and each was judged as a wrong answer, one\nof them on the text \"Let me build the correct monthly trend query.\"\n\n`contaminated` means the attempt breached isolation (`contamination_reasons`\nnames how) and the verdict is withheld rather than lost. The judge's own read\nmoves to `judge_verdict`. Before this reason was written, a voided verdict kept\nthe judge's prose in `reason` beside `verdict: null`, and a run report\nreasonably concluded the ledger was dropping the field -- it recovered nine\n\"lost\" verdicts by re-parsing the stored judge replies, every one of which had\nbeen voided on purpose.\n\nBoth are HARNESS-owned, not model-owned, and a run containing either reports\n`status: incomplete` in `run.json` and **prints no pass rate**. `unscorable`\n(no established golden) and `judge_unparseable` do not suppress the rate: the\nfirst is a dataset state no arm can fix, and the second already has a retry.\n\nAggregates count decided verdicts only. `match` and `no_match` are the pass and\nthe fail; **`near_match`, `needs_human` and null are none of the above** and stay\nout of acceptance arithmetic. `near_match` is excluded because it means \"defensibly\ndifferent\", and an arguable verdict that moves a pass rate is a measurement\nartefact rather than a result (`skill:eval-judge` rule 7). Report its count:\nit rising is how a set tells you its rubrics are going vague.\n\nThis applies to `score`. On `retrieval_score` below, `near_match` **is** counted\ntowards recall and precision, because an overlapping entity is a genuine\nretrieval success. The two are different questions that share a word.\n\n### `retrieval_score` (written by `eval-retrieval`, not by a customer run)\n\nOne per term judged in a fixed-term replay (run-level; no `caseId`).\n\n| Field | Type | Notes |\n|---|---|---|\n| `intentId` / `term` / `entityType` | string | From the term file. |\n| `in_scope` | bool | Does THIS model version represent the concept? False is a coverage gap, not a retrieval failure. |\n| `judgments` | list | Per returned entity: `entityId`, `rank`, `level` (`match` / `near_match` / `no_match`), `confidence`, `why`. Empty when nothing returned. |\n| `judge_version` / `rubric_sha` | string | |\n| `traceId` | string or null | The `get_context` call judged. |\n\nRun-level metrics fall out by counting:\n\n- `coverage` = in-scope terms / valid terms -- a property of the model and its\n  data, reported on its own, never as a retrieval number.\n- `recall` (on in-scope terms) = fraction whose judgments contain a `match`.\n- `precision@N` = `match` judgments / judged, with N stated.\n\n### `issue`\n\n| Field | Type | Notes |\n|---|---|---|\n| `issue_id` | string | Stable across status events. |\n| `qids` | list | Affected cases. |\n| `primary_code` / `contributing_codes` | string / list | From `skill:eval-diagnose`, verbatim. An event written before the codes were renamed may carry a retired one: `COVERAGE` is now `MISSING`, `NO-DISAMBIG` is `AMBIGUOUS`, and `CONVENTION` is `RULE_UNWRITTEN`. Read those as the new name; nothing rewrites old events. |\n| `component` | string | `dataset` / `agent-call` / `get_context/model` / `get_context/retrieval` / `construction` / `model-definition`. |\n| `owner` | string | `model` / `retrieval` / `agent-skill` / `dataset`. Environment failures stop the run; they are never diagnosed, so there is no environment owner. |\n| `severity` / `confidence` | string | |\n| `sufficiency` | string | `sufficient` / `insufficient` / `unknown`. |\n| `traceIds` | list | |\n| `diagnosis` | string | Written before any edit exists. |\n\n### `issue_status`\n\n`issue_id` plus `status`: `open` / `batched` / `fixed` / `rejected` /\n`deferred`. Readers take the latest event for that `issue_id`. Do not invent\na status column.\n\n### `candidate`\n\nWritten by `eval-improve`, for every proposed edit, accepted or not. A\nrejected direction keeps its record.\n\n| Field | Notes |\n|---|---|\n| `issue_ids` | |\n| `files` | Paths the edit touched. |\n| `diffSummary` | One line per file. |\n| `probes` | Query and result for each factual claim. |\n| `meaningChanged` | Entities whose *meaning* the edit changed; `[]` for a docs-only edit. |\n| `goldenSuspect` | Each `{qid, entity, stored, rederived}`: a golden this edit may have invalidated. Reported by the improver, never repaired by it. **Non-empty halts the acceptance check** until adjudicated through the golden side door. |\n| `goldenAudit` | The set's `verify_goldens.py` run against the edited model: `{ran, clean, model, tail}`. Catches drift and rubric-vs-model contradictions only; a golden whose value silently moved is invisible to it, which is why `goldenSuspect` exists alongside. |\n\n### `acceptance_check`\n\nCalled `gate` before 2026-09-03. `ledger.py` reads the old kind as this one, so\nrun directories written earlier still validate and nothing rewrites them.\n\nWritten by `eval-loop`, one per acceptance check decision, BEFORE any checkpoint commit.\n\n| Field | Notes |\n|---|---|\n| `issue_ids` | |\n| `decision` | `accepted` / `rejected`. |\n| `class` | `docs` / `definition` / `retrieval` / `justified`. |\n| `baselineRunId` / `finalRunIds` | Plural: acceptance needs two independent runs. |\n| `regressions` | Case ids whose verdict got worse vs baseline. Must be empty to accept. |\n| `holdoutDelta` | Confident-verdict delta on the holdout slice. |\n| `reason` | Including independent deterministic justification when that is the basis. |\n\n### `checkpoint`\n\nWritten by `eval-loop` after an accepted acceptance check, or when a restore runs. The\nmodel bytes live in git, not in this payload.\n\n| Field | Notes |\n|---|---|\n| `action` | `created` / `restored`. |\n| `label` | |\n| `modelGitSha` | The commit this checkpoint names (create), or the commit restored to. |\n| `issueIds` | Issues the accepted edit closed. Empty on restore. |\n\n## `judge-regressions.jsonl`\n\nAppend a line whenever a human overrules a judge verdict: the case or intent,\nthe judge's verdict, the human's, and why. Re-run this file against the judge\nwhenever `skill:eval-judge` or the judge model changes; a rubric change that\nflips old human-settled verdicts is a judge regression, not new truth."
+      body: "# The eval ledger: files and events\n\nThe ledger is plain files in the model package's git repository. There is no\neval API and no eval database. The conductor (`skill:eval-loop`) reads and\nwrites these files directly; the stages share them as their contract.\n`eval-answer` writes `attempt`, `tool_call`, and `score`. An engine-side\n`eval-retrieval` skill, which does not ship here, writes `retrieval_score` and\n`probe`; both stay in this contract so one validator covers every run\ndirectory.\n`eval-diagnose` writes `issue` and `issue_status`. `eval-improve` writes\n`candidate`. `eval-loop` writes `acceptance_check`, further `issue_status`, and\n`checkpoint`.\n\n**The contract is code: `eval-answer/scripts/ledger.py`.** Every script that\nwrites `run.json` or `events.jsonl` builds its lines through that module, so a\nfield rename that reaches only one writer fails at write time. This document\nis the human-readable rendering; where the two disagree, the module is right\nand this file is the bug. Check any run directory with:\n\n```\npython3 skills/eval-answer/scripts/ledger.py validate <runDir>\n```\n\nErrors are broken identity (missing `run.json`, a missing required field, two\nscores for one attempt); warnings are missing comparison pins (a run without\n`skillsVersion` still measures, but cannot anchor an A/B on that pin) and\ngrandfathered unknown fields on old runs.\n\n## Layout\n\n```\nevals/<set>/\n  set.json                  # set metadata (below)\n  cases.jsonl               # one case per line\n  judge-regressions.jsonl   # judge verdicts a human overruled\n  runs/<runId>/\n    run.json                # run config, the attribution pins\n    events.jsonl            # append-only event lines\n    artifacts/              # prediction CSVs, judge outputs, transcripts\n```\n\nThe set directory lives in the SAME git repository as the model it evaluates,\nso a checkpoint (a git commit) pins the model and the ledger together. Never\nplace `evals/` inside the directory tree the answerer's package serves: gold\nin the served tree is a contamination path.\n\nRules that make the ledger trustworthy:\n\n- `events.jsonl` is append-only. Never edit a line. To void one, append a new\n  event whose payload marks the old one `voided`. One sanctioned exception: a\n  re-runnable stage (diagnose, improve) replaces ITS OWN prior events, keyed by\n  issue id, through `ledger.replace_events()` -- so a crash-and-rerun does not\n  duplicate issues. A stage never touches another stage's lines.\n- A stage never rewrites another stage's fields.\n- One artifact directory per attempt (`qid` plus `sample`). Never overwrite a\n  previous attempt's prediction CSV.\n- End-of-run numbers come from counting event lines (`jq` over\n  `events.jsonl`), never from arithmetic recalled in prose.\n\n## `set.json`\n\n| Field | Notes |\n|---|---|\n| `name` | Set name; also the directory name. |\n| `description` | |\n| `datasetVersion` | Integer. Bump on any golden repair or case change. Runs record the version they scored against. |\n| `targetModelPath` | Model path within the package. |\n| `truthPackage` | Name of the package holding the semantics-free sources every golden is re-derived from -- a package NAME, not an object. Without it `verify_goldens.py` re-derives nothing: it reports \"nothing to re-derive against\" and **exits 3**, which a caller must read as unverified rather than as a pass. The checks that need no truth server -- rubric figures, verification axis, stale rubric claims, set names -- still run and still report. `init_truth_package.py` scaffolds the package. |\n| `truthModel` | Model file inside that package. Default `truth.malloy`. |\n| `targetPackage` | Name of the package UNDER TEST. `verify_goldens.py` refuses a \"truth\" server that also serves it, because an answerer on that server can retrieve the raw truth sources beside the model and quietly change what is under test. `run_baseline.py` and `improve.py` pass the package they were given, so this field is the fallback for a direct call; without either the guard cannot fire. |\n| `truthTableRewrite` | Boolean, default false. Rewrites `duckdb.table('data/x.parquet')` refs to bare `x` in canonical queries, for a truth package whose tables are registered rather than read from files. |\n\n## `cases.jsonl`\n\nOne JSON object per line:\n\n| Field | Notes |\n|---|---|\n| `qid` | Stable case id. |\n| `question` | Exact text the answerer will see. |\n| `split` | `dev` or `holdout`. Frozen at import. Diagnose and improve read `dev` only; the acceptance check runs both. |\n| `tags` | list |\n| `state` | `candidate` / `selected` / `excluded`. |\n| `source` | Where the case came from. |\n| `golden` | `status` (`verified` / `provisional` / `invalid` / `ambiguous` / `verified_wrong`, the last being a key a person has established is wrong, which `run_baseline.py` drops from every aggregate), `kind`, `value` or `path` (artifact under the set directory), `canonicalQuery` (runs against the **truth** package, never the model under test), `verifiedBy`, and `verification` -- `{primaryAxis, variesAxis, note}` naming what the second derivation varied. **A golden is written only after two differently shaped derivations agree** (the truth query and a second one that varies a different axis -- group by something else, sum a different way, take a different route through the raw tables); `gold/<qid>.json` holds both (`truthRows`, `verifyRows`, `agreement`). Two derivations that vary the same axis share every other blind spot: that is how a golden that summed three overlapping time slices, 3x too high, passed its check. `verify_goldens.py` re-derives the value, reads the accepting clause of the rubric against the rows, and flags a second derivation that names no axis. **The question asks for data, never for an interpretation of it**, and either fixes the grain or the rubric accepts a correct figure at any stated grain (`skill:eval-judge` rules 10 and 11). |\n| `golden.kind` | What the key IS. A value (`scalar`, rows), `unanswerable`, or `criteria`: prose with no value, where the author's criteria are the whole key. `criteria` is the one kind that is legitimately `verified` on arrival, because there is no derivation to perform and nothing that can be numerically wrong; an imported key holding a VALUE is `provisional` until re-derived (`skill:eval-import`). **`verify_goldens.py --promote` is the only thing that writes `golden.status`**: it marks a `provisional` golden `verified` when its value re-derived cleanly from the truth package AND a second derivation exists. `--refresh` rewrites a drifted VALUE and never changes a status; `invalid` and `ambiguous` are settled by a person through the golden side door. |\n| `golden.rubric` | **On the golden, not on the case.** The prose the judge is shown as `CASE RUBRIC`, naming what counts as correct and what does not. `run_baseline.py` reads `golden.rubric`; a rubric written at the case's top level is silently not passed, the judge is told `CASE RUBRIC: none`, and it then scores from the golden value and the answer alone -- which reads as a judge that ignores its instructions. |\n| `golden.mustState` | **On the golden, not on the case.** What the answer has to say out loud. Read from `golden.mustState` by the run-package builder. |\n| `goldenRevision` | Integer. Bump on every golden change; `score` events stamp the revision they compared against. |\n| `expectedEntities` | `required`: entity ids (`kind:source:name`) the answer cannot be produced without. `requiredAnyOf`: a list of **groups**, each a list of ids of which any one suffices -- for a case the model can answer through more than one route. Naming only one route scores the other as a retrieval miss and steers the fix to the docs for an entity whose docs were never the problem. `acceptable`: ids that are not noise if returned. An entity counts as delivered when returned under its exact id, under the same type and name on a sibling source, or by name in a returned source's documentation; `score_retrieval.py` records the route per entity as `delivery`. |\n\n## Term files (`eval-retrieval` only)\n\nA customer set has no term file. The engine-side `eval-retrieval` skill keeps\n`intents.jsonl` fixtures -- search term, entity type, a description of what the\nsearcher meant, a validity flag -- beside its own scripts, for evaluating the\nengine against fixed inputs. Their shape and the `retrieval_score` events they\nproduce are documented there and validated here.\n\n## `run.json`\n\nThe attribution pins. Two runs are comparable only when these match where it\nmatters. Two runs with different `target` values are comparable on answer\nverdicts only if the same model version reached both, which is rarely worth\nassuming:\n\nRequired fields are the run's **identity** -- every run ever written carries\nthem. The rest are optional in the schema, but the **comparison pins** are\nwarned about when absent, because a run missing one cannot take part in an A/B\non that axis.\n\n| Field | Notes |\n|---|---|\n| `runId` *(required)* | Directory name. |\n| `target` *(required)* | Which server answered, and how it reached the data: `local`, `local-proxied`, or `platform`. Decides what an improve step is even allowed to do (see `skill:eval-loop`). |\n| `answererModel` *(required)* | |\n| `phase` / `started` *(required)* | |\n| `judgeModel` / `judgeVersion` / `rubricSha` *(pins)* | The judge's model, and the version + content sha of `skill:eval-judge`. |\n| `judgePromptSha` *(pin)* | Content sha of the prompt the judge is SHOWN, which is the harness's own template and not the skill file `rubricSha` covers. The template carries the golden rendering, the evidence blocks and the tie-breaking rules, so two runs whose prompts differed compared as the same judge -- the blind spot that let a golden-rendering defect run through three arms with every test passing, because the tests covered the code paths and not the text the model sees. Absent on runs written before it existed. |\n| `datasetVersion` *(pin)* | From `set.json` at run time. |\n| `modelSha` *(pin)* | Content sha of the `model.malloy` snapshot in the run directory -- the bytes the answerer actually queried. A git sha is not enough: a snapshot host serves a copy, often of a dirty tree no commit names. |\n| `skillsVersion` *(pin)* | HEAD of the checkout the agents' skills were loaded from, dirty-marked (`ledger.skills_git_sha(root)`). The skills are the doctrine the agents load; a run that cannot name their version cannot anchor a skills A/B. |\n| `skillsRoot` / `harnessVersion` | Which checkout supplied the doctrine (`--skills-root`, e.g. a Publisher checkout for the open-source skills; default this one), and this checkout's own HEAD. The eval-* skills always come from the harness checkout, whatever `skillsRoot` says. Two runs whose `skillsRoot` differ are a skills A/B only if their manifests name the same skills. |\n| `diagnoserModel` / `improverModel` | Written by `diagnose.py` / `improve.py` when those stages run, so the run names every LLM that touched it. Absent on a run that was only answered and judged. |\n| `modelGitSha` | Commit of the model repo, from `--model-repo`; `-dirty` suffix when `--model-dir` (or the whole repo, without it) had uncommitted changes -- fine for a band measurement, not for an A/B pin. Null when git cannot answer for the scope (a path outside the repo): absent beats wrong. **Null unless `--model-repo` names the repo.** It cannot be inferred: Publisher serves a COPY under `publisher_data/`, so the tree around the served file is the server's storage, not the model's history, and the field named that until 2026-09-03. `modelSha` above is the pin that always works; this is the pointer to where those bytes are versioned, and absent beats wrong. |\n| `modelRepo` | The path `--model-repo` named, so a reader can tell an absent pin from an unrecorded one. |\n| `modelDir` | The package directory `--model-dir` named, when it was: the path the `-dirty` marker on `modelGitSha` was decided over. Absent means the whole repo, where any unrelated untracked file marks the model dirty. |\n| `environment` / `package` / `modelPath` | What was served, and from where. On a platform target `environment` is the organization and `package` is the workspace the MCP URL is scoped to. |\n| `scope` | Platform target only: the `environment/package[@version]` the answerer was told to pass as an explicit `scopes` entry on every `get_context` / `execute_query` call. A workspace can serve many packages (a personal workspace serves every package the user can read), so without this the run also measures whether retrieval picks the right package -- a different measurement. Absent means unscoped. |\n| `targetVersion` *(pin)* | Platform target only: the published version the answers came from. Both hosted tools default an omitted version to the PINNED one, meaning whatever the workspace serves at the moment of the call, so this only describes the run when `--scope` carries it to every call. `--target-version` supplies it when the scope omits it; a scope naming a different version is refused rather than treated as an override, because a run cannot say which build answered if two pins disagree. |\n| `mcpUrl` / `publisher` | The endpoints the answerer and the re-execution used. |\n| `predictionsReExecuted` | Whether re-execution was POSSIBLE: the server was serving the bytes this run is pinned to. It is one bool for the whole run and says nothing about any given query, so it reads stronger than it is; `reExecution` below is what actually happened. |\n| `reExecution` | `{attempted, ok, failed, noQuery, notReExecuted, notJudged, missing}` over the run's predictions. `failed` means the query ran and the server returned an error, which is a different thing from an answer with no query at all. `notJudged` is a case the judge was never handed: a golden refused before judging (`provisional`, `invalid`, `ambiguous`, `verified_wrong`, missing), an attempt that submitted nothing, or every case under `--no-judge`. Those used to land in `missing` and read as corrupt artifacts on a freshly imported set. `ok`, `failed`, `noQuery`, `notReExecuted`, `notJudged` and `missing` partition the cases, so they sum to the case count; `attempted` is `ok + failed` and sits outside that sum. |\n| `retrievalMode` | Which retriever answered: `semantic`, `lexical`, `mixed` (it changed mid-run, so nothing can be averaged across it) or `unreported` (nothing ranked, which on a configured server means no embedding provider). Only a RANKING call names a retriever, so a call that enumerates a type or looks a name up is `unreported` on a fully semantic server and must not make the run read as `mixed`. Local retrieval degrades to lexical SILENTLY without an embedding key, and a pair compared across that reads as a model change, so `flip_table.py` refuses the pair unless both sides match. |\n| `retrievalCalls` | `{semantic, lexical, unreported}` call counts behind `retrievalMode`. `unreported` counts the calls that did not rank, which is a different thing from calls that fell back. |\n| `retrievalGate` | What the pre-arm retrieval gate found, or why it did not run. A run is held until `get_context` answers semantic twice in a row, because the first calls after a restart are lexical by design and an arm started immediately measures two retrievers. `not run (no answering phase)` under `--rebuild`/`--rejudge`, and `skipped by --no-retrieval-gate` when the operator opted out -- which is a different fact from a gate that passed, and the field is what tells them apart. |\n| `coverageReport` | The `check_coverage.py --out` report this run read, when `--coverage` named one: its path, the model version it was stamped with, its `agentModel`, and `decided` of `cases`. Coverage is a read of the MODEL, so it is measured separately and costs a judge call per case; the run does not run it, it consumes it. Its per-case verdict then beats the authored `coverage` label in retrieval attribution, and each `score_retrieval` row records `coverage_source` (`measured`, `authored`, `none`) so nobody has to guess which one charged the failure. Absent when no report was given, which is a different fact from a report that found everything covered. |\n| `label` | `<set>-<phase>-<nn>`, assigned by `run_baseline.py` from the set name, the run's phase and the next free number beside it (`ecommerce-baseline-01`, `ecommerce-baseline-02`, `ecommerce-blind_gate-01`). The A/A pair is two runs of the same phase; the post-edit arms are two runs of `blind_gate`. Hand-typed names do not survive one afternoon of runs -- `base`, `rejudged2`, `r3`, `post1` sort wrongly, group not at all, and cannot be matched to an arm. `--label` overrides for a run that genuinely needs a human name. |\n| `effort` | |\n| `maxTurns` / `answererTimeout` *(pins)* | The answerer's turn cap and per-attempt timeout, as the arm ran them. `skill:eval-loop` step 6 lists the call budget among the pins to freeze for a whole run, and nothing wrote one, so no two runs could be compared on the setting that decides whether a case got to finish at all. Distinct from `callBudget`, which no harness has ever written. Size the cap from a pilot rather than taking the default: on a 29-case arm at the default 30, completed attempts had a median of 17 turns and a 90th percentile of 26, and the four cases that ran past it were recorded as wrong answers. |\n| `truncated` / `contaminated` | The qids excluded for a HARNESS-owned reason: the cap cut the answer off, or the attempt breached isolation. Both leave the denominator, both are named here rather than only in the console, and either one makes `status` `incomplete`. |\n| `answererCostUsd` / `judgeCostUsd` | What the arm cost, split by role. The judge's half was discarded until 2026-09-02, so every \"cost per arm\" quoted before then was the answerer alone. Per-case judge cost is on each `score` event. |\n| `answererCostCopiedFrom` | The run whose attempts `answererCostUsd` was COPIED from, when this run spawned no answerer -- a `--rejudge`, a `--rebuild`, a `--from`. Those copy the source's attempt events verbatim, `cost_usd` included, so the figure is right about the attempts and wrong as this run's spend: one re-judge reported $17.56 of answering that never happened. Null when this run paid, so a total over several run files can skip the copies. |\n| `goldenCheck` | What `verify_goldens.py` said before the run started: `N ok, M drifted, K other finding(s)`, or why it did not run (no truth server on a platform target; `--skip-golden-check`; rebuild). A run that started on a drifted set says so here rather than pretending its verdicts mean something. `run_baseline` calls `verify()` without a model, so the set-name audit (check 5) does not run in-arm; the trailing `N stale entity name(s)` is the in-arm lint's own count, and `entity-name lint not run` says there was no model text to lint against. Without it the field read `0 other finding(s)` for a check that never happened. |\n| `staleEntityNames` | The `expectedEntities` names that appear nowhere in the served model, from the in-arm lint. Each one depresses the run's own recall on every case listing it, so a stale set reads as a retrieval failure until someone checks by hand. `null` when there was no model text to lint against (a platform target), which is a different fact from `[]`. |\n| `status` | `complete`; `aborted` when four consecutive attempts errored or found the server dead and the harness stopped rather than spend the rest of the budget on attempts nobody will trust; or `incomplete` when the arm ran to the end and still cannot report a rate, because `truncated` or `contaminated` is non-empty. `incomplete` is a third state, not a soft `complete`: the arm did everything asked of it and the number is still unearned. It does NOT stop the run being compared: `flip_table.py` scores the cases both arms did, and names the ones this arm left unscored -- an excluded case carries no verdict, so it can never be counted as a flip. |\n| `packageSha` / `servedRevision` *(pins)* | Taken from the server, not recomputed: `sourceContentSha` is a content hash over EVERY model path in the package, so an edit to an imported file moves it where a sha of the one `--model-path` does not; `servedRevision` is minted per load, so it identifies a load rather than content and is a poor pin alone. Measured: `publisher.json`'s `version` moves neither, and nothing in Publisher reads it -- it is not in the Package API schema and never returned, so it pins nothing. |\n| `datasetSha` *(pin)* | Content hash of `set.json` + `cases.jsonl`. Deliberately SEPARATE from the model's sha: a golden repair is not a model change, and one pin covering both would make every answer-key fix read as an edit to the model, which is the distinction an A/B rests on. Automatic, so nobody has to remember it; `datasetVersion` stays beside it as the human-readable sequence. **Local targets only.** A hosted target that publishes IMMUTABLE versions needs none of this: the set rides inside the version, and immutability -- not hashing -- is what makes a pin trustworthy. There, `targetVersion` alone identifies model and set together. |\n| `doubtedGoldens` | The cases whose golden is not believed: `qid`, `gold_status` (`suspect` or `verified_wrong`), `gold_note`, and `declaredBy` (`judge` or `set`). A status the SET declared is a key somebody already settled, not an opinion the judge formed this run, and attributing both to the judge claimed a judgement that never happened. **Read this before diagnose.** These are dataset issues, not model failures, and they go through the golden side door in `skill:eval-loop`. Empty list when no key is in doubt from either source. Written from the same scan that prints the end-of-run warning, because a warning that lives only in console text is one scrollback away from sending a modelling agent at a model that is already right. |\n| `mode` / `setName` / `serverVersion` / `traceMode` / `callBudget` | Defined and accepted, **not yet written by any harness** -- kept in the schema for the platform target and the conductor, which need them. (`targetVersion` and `status` were in this list and are both written now.) |\n\n## Events\n\nEvery line in `events.jsonl` is **flat**: `{ \"kind\": ..., <fields> }`, one\nJSON object per line, with an optional `at` ISO timestamp. Case-scoped kinds\n(`attempt`, `tool_call`, `score`) carry `qid`, `sample`, `phase` on the line;\nrun-level kinds do not. (An earlier draft of this document nested fields under\na `payload` with a `caseId`; no writer ever did that, and 23 run directories\nexist in the flat shape, so the flat shape is the contract.) `kind` is one of:\n`attempt`, `tool_call`, `score`, `retrieval_score`, `issue`, `issue_status`,\n`candidate`, `acceptance_check`, `checkpoint`.\n\n### `attempt`\n\n| Field | Type | Notes |\n|---|---|---|\n| `qid` | string | |\n| `sample` | int or null | Which repeat. Required even when null. |\n| `phase` | string | `baseline` / `loop` / `blind_gate` / `canary` / `final`. `phase` lives here, on the attempt, not in run config. |\n| `question_sha` | string | Hash of the exact text the answerer saw, so two runs can be compared on whether they asked the same thing. A case may carry `questionSha`, the seal stamped at conversion, and that wins when present; the ecommerce set writes a 16-char prefix of it, and a set without one left this null. Neither form proves the question was not edited, since both follow the case as it now reads: that comparison is check 6 of `verify_goldens.py`. |\n| `submitted` | bool | False when there was no final query. Not a wrong answer. |\n| `final_query` | string or null | Required to replay. A named view is recorded as the Malloy it stands for, `run: <source> -> <view>`, so every consumer sees one shape and the query re-executes. |\n| `final_query_source` | string or null | How `final_query` was chosen: `declared` (the answer printed it), `last_ok` (the last call the server answered) or `last`. `last` is a warning: a trailing sanity probe may be standing in for the answer's own query. |\n| `servedRevision` | string or null | From the package actually queried. |\n| `n_get_context` / `n_execute` / `n_execute_errors` | int | |\n| `host_tool_uses` | int | EVERY tool use the host logged, MCP calls included. It counted only the non-MCP ones until 2026-09-03, which made the under-report check below true of almost every clean attempt. |\n| `mcp_tool_uses` | int or null | The MCP subset: `get_context` plus `execute_query`. Null on a run written before the split. |\n| `reported_calls` | int | MCP calls the answerer claimed. `reported_calls > host_tool_uses` is the under-report floor from `skill:eval-answer`: the answerer cannot have made more calls than the host logged. `validate_run` warns on it, and only for runs that carry `mcp_tool_uses`, because the field meant something narrower before. |\n| `contaminated` | bool or `\"unknown\"` | `\"unknown\"` when no host log exists. Read it with `ledger.is_contaminated`, never for truthiness: runs written before 2026-09-03 carry the strings `\"true\"`/`\"false\"`, and `bool(\"false\")` is True. `ledger.event` now rejects those strings on write; `validate_run` grandfathers them on read as a warning. |\n| `contamination_reasons` | list | Empty when clean. |\n| `input_tokens` / `output_tokens` / `cache_read_tokens` / `cache_write_tokens` | int or null | Answerer token usage, the four counts that reprice a run from its own ledger. Null when the host does not report it. `cost_usd` beside them comes from the CLI's `total_cost_usd`, which prices cache reads and writes at their rates, so it was always cache-inclusive; what was missing was the breakdown that reproduces it. `cache_write_tokens` (`cache_creation_input_tokens` upstream) was never captured before 2026-09-15, and on one analysed run cache writes were 44% of the agent's cost, the single largest line. **Read `input_tokens` with care:** it counts only the tokens after the last cache breakpoint. One run recorded 224 for 24 questions beside 2.4M cache reads; the 224 is not the context volume, and a token total that omits the cache columns is not a size. |\n| `cost_usd` | float or null | Answerer cost for this attempt. |\n| `num_turns` / `wall_seconds` | int, float or null | |\n| `answer_text` | string or null | The answer the judge scored. Kept so a verdict can be re-read without the transcript. |\n| `skills_invoked` | list of string | The skills the answerer invoked through the `Skill` tool, deduplicated and sorted, counted from its own transcript. Always a list on a run that recorded it, so an EMPTY list is the finding: the arm granted a manifest and the agent reached for none of it. Absent on runs written before 2026-09-15, which is why every reader takes `or []`. Only explicit `Skill` calls are counted, and only skills the arm granted -- one outside `--answerer-skills` is a contamination breach and lands in `contamination_reasons` instead. What it is for: a manifest names what an arm GRANTED, and comparing two arms' doctrine is meaningless if the doctrine never loaded. |\n| `transcriptPath` | string | The answerer's transcript under `artifacts/`. |\n\nToken counts sit here rather than being derived later because the claim a\nsemantic model makes is about cost as well as correctness -- that a documented\nmodel reaches a good answer in fewer turns and tokens than working from raw\nschema. A ledger that counts calls but not tokens can state half of that.\n\n### `tool_call`\n\nOne event per MCP `get_context` or `execute_query` the attempt made.\n\n| Field | Type | Notes |\n|---|---|---|\n| `tool` | string | `get_context` or `execute_query`. |\n| `traceId` | string or null | `get_context` only; look up in your host's trace store. |\n| `targets` | string, list or null | **What the answerer asked for**: the search terms it sent to `get_context`. Null for `execute_query`. |\n| `rankedSummary` | object | Copied at capture so evidence survives trace eviction: `entityIds` (identity, in response order), `hits` (one row per entity: `entity_id`, `source`, `relevance`, `matched_targets`, `position`, `position_in_source`), `resultCount`, `docTokens`. **There is no rank.** This field previously documented `ranks` and \"per-target `targets` with within-target ranks\"; no writer ever wrote either, and what `ranks` did hold was `range(1, n+1)` over a list already flattened source-card by source-card -- a position, not a rank, and not even a relevance order, since the response sorts globally and then buckets into cards. Ask relevance questions of `hits[].relevance`. |\n| `rankedSummary.hits[].matched_targets` | list or null | Which of the caller's search targets matched this entity, each with the server's own relevance. **`null` means no attribution was published**, which is not the same as `[]`: the server attaches it to entities only (a source card's attribution is discarded before an entity object exists) and only on the semantic path, because a lexical score is relative to its own query and comparing two of them means nothing. A lexical run therefore cannot say which target found what, and a reader must report that as unavailable rather than as \"never asked\". |\n| `retrieval_mode` | string or null | `get_context` only: the `retrieval` field of the response that answered, `semantic` or `lexical`. Null when the server named none, which means no embedding provider. Recorded per call because the semantic path can fall over partway through a run. |\n| `query` | string or null | `execute_query` only: the Malloy the call sent, so the final query can be chosen by which call the server actually answered. |\n| `modelPath` | string or null | `execute_query` only: the model file the call named. A source does not resolve outside the file that declares it, so re-execution needs this. |\n| `error` | string or null | |\n\nNever persist `execute_query` result rows, givens, or credentials.\n\n`targets` records the request; `rankedSummary` records the response. Without\nboth, a low per-attempt recall has two readings that cannot be told apart: the\nanswerer searched for the wrong thing, or it searched well and retrieval ranked\nthe right entity too low. Those have opposite owners -- `agent-skill` and\n`retrieval` -- so a ledger holding only the response cannot attribute the\nfailure, and any recall computed from it is a blend of answerer behaviour and\nretrieval quality.\n\nThat blend is also why per-attempt recall is **not** comparable across arms: a\nstronger answerer searches better and scores higher retrieval recall without\nretrieval having changed. Use it for attribution within an arm. Comparing\nretrieval itself between engine versions is `eval-retrieval`'s job, with fixed\nterms, and is not something a customer run reports.\n\n### `score`\n\nThe answer judge's verdict for one attempt (protocol in\n`skill:eval-judge`). Every attempt in a scored run gets exactly one.\n\n| Field | Type | Notes |\n|---|---|---|\n| `verdict` | string or null | `match` / `near_match` / `no_match` / `needs_human`; null when the attempt is not scorable. Only `match` and `no_match` are decisions; see below. |\n| `reason` | string | Why, from the judge; for a null verdict, why not scorable, and it is ALWAYS one of these: `not_submitted`, `answerer_truncated`, `contaminated`, `judge_unparseable`, `no_saved_verdict`, `judge_error: <text>`, or `golden_<status>` -- `golden_missing`, `golden_provisional`, `golden_invalid`, `golden_ambiguous`, `golden_verified_wrong`. A null verdict never arrives without one: a nulling that does not say which of these it was is indistinguishable from the field being dropped on the write path, and was read as exactly that from a real run. The `golden_*` reasons and `answerer_truncated` are decided before the judge is called, so neither an unestablished key nor a cut-off attempt costs a judge call. |\n| `confidence` | int or null | 1 to 10. Confidence of 5 or lower forces `needs_human`. |\n| `column_pairing` | object or null | The judge's named gold-to-prediction column correspondence. |\n| `judge_version` / `rubric_sha` | string | Pins which rubric produced this verdict. |\n| `golden_revision` | int | From the case at score time. |\n| `contaminated` | bool or `\"unknown\"` | Copied from the attempt; true or unknown means `verdict: null`. |\n| `must_not_use_hits` | list or null | Entries of `golden.mustNotUse` a script found in the final query. A hit forces `verdict: no_match`. Decided by `check_must_not_use.py`, never by the judge: it is a question about query text. Only a BARE name vetoes; an entry with a connective (`X as ...`, `X through ...`) objects to a use of X rather than to X, and goes to the judge with the prose entries and a path's bare leaf. |\n| `judge_verdict` | string or null | What the judge said when a MECHANICAL override replaced it: a `must_not_use_hits` veto, or contamination voiding the verdict. Null otherwise, so the judge's own agreement rate stays measurable across both. When a case is vetoed AND contaminated this still holds the judge's read, not the veto's `no_match`. |\n| `artifactPath` | string | The full judge output under `artifacts/`. |\n| `gold_status` | string | `verified` / `verified_benign` / `suspect` / `verified_wrong`, and never anything else: the case file's `golden.status` is a DIFFERENT vocabulary that shares only `verified` and `verified_wrong`, and only those two fall back into this field. A `provisional` / `invalid` / `ambiguous` key is reported through the verdict's `reason` (`golden_<status>`) instead, so nothing downstream has to match on two vocabularies in one field. **From the judge**, which scored against the golden as written and reports separately whether it believes it; falls back to the case's standing `golden.status` when the judge does not say, written onto the verdict itself so the run summary and the aggregates see it too. `verified_wrong` excludes the case from run aggregates -- from the judge OR from the case file; assigning the fallback into a copy of the verdict meant a key the set had marked wrong stayed in the aggregates unless the judge independently agreed. `suspect` and `verified_wrong` route to the golden side door as `dataset` issues, never to improve. |\n| `gold_note` | string or null | The judge's evidence for a non-`verified` status: the two values, or the model line against the rubric sentence. Null when `verified`. |\n\nA `golden_*` reason means the ANSWER KEY is not something a verdict can be\nissued against. A golden the set stamps `provisional`, `invalid` or `ambiguous`\nis refused, as is a case with no golden at all and one the set marks\n`verified_wrong`; a golden with NO `status` is unguarded rather than\nunscorable, because sets that predate the field would otherwise score zero of\nzero. A golden holding no value is not refused either: that is how a\n`kind: unanswerable` case and a `kind: criteria` golden are written. This\nmatters most for an imported set, because `skill:eval-import` stamps\n`provisional` on every golden it writes and enforces it -- so a set is\nunscorable by construction until its keys are re-derived, and `run_baseline`\nrefuses to spend at all when every case in a set is in that state.\n\n`not_submitted` means the attempt produced NOTHING to judge: no answer text and\nno query. An attempt that wrote prose without querying **is judged**, and\nagainst a golden that holds a value an answer containing none of it is\n`no_match` (`skill:eval-judge`, `reference/refusal.md` rule 10). Excusing those\nas unscorable dropped a confident refusal on an answerable case out of the pass\nrate, which is the one thing the answerable-sounds-unanswerable cases exist to\nmeasure. A refusal is exempt only where `golden.kind` is `unanswerable`, and\nthere naming the gap is the pass and a confident number is the fail.\n\n`answerer_truncated` means the answerer hit the run's `maxTurns` cap and the\nCLI returned whatever it had, which is usually a sentence stopping mid-thought.\nIt is refused BEFORE the golden gate and before a saved verdict is reused, so\n`--rebuild` over a run made without this re-derives the right ledger from its\ntranscripts. A cap is a harness setting, so a case cut off by one says nothing\nabout whether the model could answer it: measured on one 29-case arm, four\nattempts ended at exactly 31 turns and each was judged as a wrong answer, one\nof them on the text \"Let me build the correct monthly trend query.\"\n\n`contaminated` means the attempt breached isolation (`contamination_reasons`\nnames how) and the verdict is withheld rather than lost. The judge's own read\nmoves to `judge_verdict`. Before this reason was written, a voided verdict kept\nthe judge's prose in `reason` beside `verdict: null`, and a run report\nreasonably concluded the ledger was dropping the field -- it recovered nine\n\"lost\" verdicts by re-parsing the stored judge replies, every one of which had\nbeen voided on purpose.\n\nBoth are HARNESS-owned, not model-owned, and a run containing either reports\n`status: incomplete` in `run.json` and **prints no pass rate**. `unscorable`\n(no established golden) and `judge_unparseable` do not suppress the rate: the\nfirst is a dataset state no arm can fix, and the second already has a retry.\n\nAggregates count decided verdicts only. `match` and `no_match` are the pass and\nthe fail; **`near_match`, `needs_human` and null are none of the above** and stay\nout of acceptance arithmetic. `near_match` is excluded because it means \"defensibly\ndifferent\", and an arguable verdict that moves a pass rate is a measurement\nartefact rather than a result (`skill:eval-judge` rule 7). Report its count:\nit rising is how a set tells you its rubrics are going vague.\n\nThis applies to `score`. On `retrieval_score` below, `near_match` **is** counted\ntowards recall and precision, because an overlapping entity is a genuine\nretrieval success. The two are different questions that share a word.\n\n### `retrieval_score` (written by `eval-retrieval`, not by a customer run)\n\nOne per term judged in a fixed-term replay (run-level; no `caseId`).\n\n| Field | Type | Notes |\n|---|---|---|\n| `intentId` / `term` / `entityType` | string | From the term file. |\n| `in_scope` | bool | Does THIS model version represent the concept? False is a coverage gap, not a retrieval failure. |\n| `judgments` | list | Per returned entity: `entityId`, `rank`, `level` (`match` / `near_match` / `no_match`), `confidence`, `why`. Empty when nothing returned. |\n| `judge_version` / `rubric_sha` | string | |\n| `traceId` | string or null | The `get_context` call judged. |\n\nRun-level metrics fall out by counting:\n\n- `coverage` = in-scope terms / valid terms -- a property of the model and its\n  data, reported on its own, never as a retrieval number.\n- `recall` (on in-scope terms) = fraction whose judgments contain a `match`.\n- `precision@N` = `match` judgments / judged, with N stated.\n\n### `issue`\n\n| Field | Type | Notes |\n|---|---|---|\n| `issue_id` | string | Stable across status events. |\n| `qids` | list | Affected cases. |\n| `primary_code` / `contributing_codes` | string / list | From `skill:eval-diagnose`, verbatim. An event written before the codes were renamed may carry a retired one: `COVERAGE` is now `MISSING`, `NO-DISAMBIG` is `AMBIGUOUS`, and `CONVENTION` is `RULE_UNWRITTEN`. Read those as the new name; nothing rewrites old events. |\n| `component` | string | `dataset` / `agent-call` / `get_context/model` / `get_context/retrieval` / `construction` / `model-definition`. |\n| `owner` | string | `model` / `retrieval` / `agent-skill` / `dataset`. Environment failures stop the run; they are never diagnosed, so there is no environment owner. |\n| `severity` / `confidence` | string | |\n| `sufficiency` | string | `sufficient` / `insufficient` / `unknown`. |\n| `traceIds` | list | |\n| `diagnosis` | string | Written before any edit exists. |\n\n### `issue_status`\n\n`issue_id` plus `status`: `open` / `batched` / `fixed` / `rejected` /\n`deferred`. Readers take the latest event for that `issue_id`. Do not invent\na status column.\n\n### `candidate`\n\nWritten by `eval-improve`, for every proposed edit, accepted or not. A\nrejected direction keeps its record.\n\n| Field | Notes |\n|---|---|\n| `issue_ids` | |\n| `files` | Paths the edit touched. |\n| `diffSummary` | One line per file. |\n| `probes` | Query and result for each factual claim. |\n| `meaningChanged` | Entities whose *meaning* the edit changed; `[]` for a docs-only edit. |\n| `goldenSuspect` | Each `{qid, entity, stored, rederived}`: a golden this edit may have invalidated. Reported by the improver, never repaired by it. **Non-empty halts the acceptance check** until adjudicated through the golden side door. |\n| `goldenAudit` | The set's `verify_goldens.py` run against the edited model: `{ran, clean, model, tail}`. Catches drift and rubric-vs-model contradictions only; a golden whose value silently moved is invisible to it, which is why `goldenSuspect` exists alongside. |\n\n### `acceptance_check`\n\nCalled `gate` before 2026-09-03. `ledger.py` reads the old kind as this one, so\nrun directories written earlier still validate and nothing rewrites them.\n\nWritten by `eval-loop`, one per acceptance check decision, BEFORE any checkpoint commit.\n\n| Field | Notes |\n|---|---|\n| `issue_ids` | |\n| `decision` | `accepted` / `rejected`. |\n| `class` | `docs` / `definition` / `retrieval` / `justified`. |\n| `baselineRunId` / `finalRunIds` | Plural: acceptance needs two independent runs. |\n| `regressions` | Case ids whose verdict got worse vs baseline. Must be empty to accept. |\n| `holdoutDelta` | Confident-verdict delta on the holdout slice. |\n| `reason` | Including independent deterministic justification when that is the basis. |\n\n### `checkpoint`\n\nWritten by `eval-loop` after an accepted acceptance check, or when a restore runs. The\nmodel bytes live in git, not in this payload.\n\n| Field | Notes |\n|---|---|\n| `action` | `created` / `restored`. |\n| `label` | |\n| `modelGitSha` | The commit this checkpoint names (create), or the commit restored to. |\n| `issueIds` | Issues the accepted edit closed. Empty on restore. |\n\n## `judge-regressions.jsonl`\n\nAppend a line whenever a human overrules a judge verdict: the case or intent,\nthe judge's verdict, the human's, and why. Re-run this file against the judge\nwhenever `skill:eval-judge` or the judge model changes; a rubric change that\nflips old human-settled verdicts is a judge regression, not new truth."
     },
     {
       name: "eval-diagnose",
@@ -324671,10 +324786,14 @@ python3 skills/eval-loop/scripts/run_baseline.py \\
 python3 skills/eval-loop/scripts/run_baseline.py \\
   --set <repo>/evals/ecommerce --out results/<arm> \\
   --parallel 4 --truth-publisher http://localhost:4881 \\
-  --model-repo <repo>   # the checkout the MODEL is versioned in, recorded as
-                        # modelGitSha. It cannot be inferred: Publisher serves
-                        # a copy under publisher_data/, whose surrounding tree
-                        # is the server's storage, not the model's history.
+  --model-repo <repo> --model-dir <package>   # the checkout the MODEL is
+                        # versioned in, recorded as modelGitSha, and the package
+                        # directory inside it the -dirty marker is decided over
+                        # (relative to the repo). Without --model-dir any
+                        # untracked file anywhere in the repo marks the model
+                        # dirty. The repo cannot be inferred: Publisher serves a
+                        # copy under publisher_data/, whose surrounding tree is
+                        # the server's storage, not the model's history.
 #    the run names itself <set>-<phase>-<nn> (ecommerce-baseline-01, then -02
 #    for the second arm of the A/A). Pass --label only for a run that needs a
 #    human name; hand-typed arm names stop being readable within an afternoon.
@@ -325298,6 +325417,7 @@ This table is a catalogue of what exists, not of what is loaded. A host that ins
 |-------|-------------|
 | \`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-data-app-design\` | Deciding what a data app should be, before building it: audience, archetype, chart forms and depth |
 | \`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 |
@@ -325706,7 +325826,7 @@ Publishing is out of scope for now: open-source Publisher serves the model from
     {
       name: "malloy-charts",
       description: "Chart selection for a Malloy view, plus the renderer reference for bar_chart, line_chart, scatter_chart, maps and layouts. For choosing a visualization or adding a chart annotation.",
-      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'
+      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> **This file is about the Malloy renderer\'s `#` tags.** It applies when the view itself is rendered - a notebook, a dashboard, an explore result. It does **not** apply to an app that draws its own charts with a vendored chart library: there the tag vocabulary is irrelevant and the full form vocabulary is available, so the approximations below (a funnel as a bar chart, a treemap as a nested table) are the wrong advice. Design to whichever vocabulary the surface actually uses.\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",
@@ -326205,6 +326325,700 @@ the warning list.
 
 - \`docs/dashboards.md\`: the full guide this skill condenses.
 - \`docs/givens.md\`: the givens the controls are generated from.`
+    },
+    {
+      name: "malloy-data-app-design",
+      description: "Decide what a data app should be before building it - who opens it, the decision it serves, which archetype it is, the forms that answer its questions, and the depth (drill-down, shared scope, linkable state) that makes it a tool rather than a page of charts. Read at the START of any data-app request, before scaffolding a package or writing a tile, and when an existing app feels flat, generic, or like a list of every view in the model.",
+      body: `# Designing a Data App
+
+> An app that replaces a BI dashboard is shaped by a **job**, not by a model. The model tells you what is *available*; the job tells you what to build. Enumerating a model produces the same KPI-row-plus-chart-grid every time, which is the single most common failure of a generated data app.
+
+> **Tool names** are written bare here - \`get_context\`, \`execute_query\`. The exact prefixed name depends on the host surface; match each against the tools you actually have.
+
+This skill produces a **design brief**: the audience, the decision, the archetype, the tile forms, and the depth plan. That brief is the input to building the app. It does not cover wiring, queries, or the runtime.
+
+## Why this comes first
+
+A data app is asked for in one line ("build a dashboard for X") and the model is right there, so the tempting move is to read the model and turn each view into a tile. That path is what makes every app look alike, and the sameness is structural, not cosmetic: a tile per view yields a KPI row, a line chart, a bar chart, and a table, in sections named after the model's subject areas, whatever the domain.
+
+The apps that hold up against Looker or Sigma are not better-decorated versions of that. They are shaped differently because they answer a specific recurring question for a specific person. So spend the first few minutes on the brief. It is cheap, and it is the difference between a page someone screenshots once and a tool they open on Monday.
+
+**The anti-pattern, stated plainly:** a tile per view is enumeration, not design. If your tile list can be derived mechanically from the model's view list, you have not designed anything yet.
+
+## 1. Establish the job
+
+Answer these four before choosing anything. Ask the user what you cannot infer - this is a **decision**, not a rule: propose what you believe from the model and the request, and confirm the parts that change the build.
+
+| Question | Why it changes the app |
+|---|---|
+| **Who opens this, and how often?** | An exec opening it monthly wants a verdict. An analyst in it daily wants pivots and exports. The same numbers, two different apps. |
+| **What decision does it serve?** | "Which accounts do I call this week", "do we ship or hold", "where did margin go". A named decision tells you what belongs on the first screen. |
+| **What 2-3 numbers settle that decision?** | These lead. Everything else is supporting evidence or a drill target. An app with fifteen equal-weight tiles has no answer. |
+| **What does the user do next, in the app?** | The answer is the depth plan (§4). "Nothing" is a legitimate answer only for a true monitor. |
+
+If the user cannot name the decision, that is worth surfacing rather than papering over: an app without a decision behind it becomes a data dump, and no amount of design rescues it. Offer to build the most defensible general view for the audience and say plainly that is what you are doing.
+
+### If the app already exists
+
+Most requests are "make this better", not "build me one". The brief is the same, but an existing app carries constraints a new one does not, and you find them by looking rather than by asking:
+
+- **Find the tests and docs that describe the current app first.** A test that asserts exact label text, a README that names a section, a screenshot in a doc: any of these turns a wording change into a broken build. Search for the app's strings before you change them.
+- **Read the app against the brief you just wrote, not against your taste.** Say which tiles serve the decision, which do not, and which are missing. That list is the change; anything else is redecoration.
+- **Say what you are keeping.** A redesign that silently drops a tile someone relies on is worse than one that keeps it and explains why.
+
+### When nobody can answer
+
+You may be running unattended, or the person who asked is not reachable. Do not stall, and do not quietly skip the brief: **write it down, state the assumption it rests on, and build.** Put the brief where the work lands (a comment at the top of the tile definitions, a note in the app, the handover message), so the first reviewer sees what you assumed and can correct it in one reply. An unanswered question is a reason to record the assumption, not to abandon the step.
+
+## 2. Pick the archetype
+
+Archetype drives layout, navigation, and how much depth is warranted. Pick one deliberately; do not default.
+
+| Archetype | The job | Shape | Depth |
+|---|---|---|---|
+| **Monitor** | Is anything wrong right now? | One screen, scannable, status-forward. Thresholds and deltas, not raw levels. | Shallow by design. Drill only into an anomaly. |
+| **Scorecard** | Are we hitting the target? | Metric per row: actual, target, variance, trend. Period selector. | Drill from a miss to its drivers. |
+| **Explorer** | What is going on in this population? | Ranked lists and distributions, an entity detail view, comparison. | Deep. Drill-down and compare are the point. |
+| **Workbench** | Do the recurring work of a role. | Multi-page behind nav, one page per subject. Shared period/unit controls. | Deep. Cross-page state, entity drawers, export. |
+| **Briefing** | Explain what happened and why. | Narrative order, prose between the numbers, few tiles, each carrying an argument. | Shallow. Links out rather than drills in. |
+
+Notes that matter in practice:
+
+- **A monitor is not a small workbench.** Do not grow one into the other by adding sections. If the user needs both, they are two apps, or two pages with different designs.
+- **Explorer and workbench are where BI tools are actually replaced.** They are also where the archetype gets skipped and a flat one-pager appears instead. If the job is "explore the population" or "do my job here", commit to the depth.
+- **Briefing is legitimate and under-used.** When the ask is "explain the quarter", prose with four well-chosen numbers beats twenty tiles.
+
+\`reference/archetypes.md\` has a layout sketch for each, what leads the page, the depth that belongs, the failure mode that turns it back into a generic dashboard, and a table for deciding between two that seem close. Read the entry for the one you picked before laying anything out - "multi-page behind nav" and "narrative order" are easy to nod at and hard to produce from the phrase alone, and an archetype that stays abstract collapses back into a card grid.
+
+Say which archetype you picked and why, in one line, before you build. It is the sentence the user can most usefully disagree with.
+
+## 3. Choose forms by question, not by data shape
+
+A form is chosen by the **question it answers**. Reaching for line/bar/table by default is how a rich model comes out flat. The table below is the vocabulary to choose from; pick the row whose question matches, then check the misuse column before committing.
+
+### First, inventory the model. The table alone will not change what you build.
+
+A vocabulary list is a lookup, and nobody looks up what they think they already know. Measured on a real build: an agent that had this exact table in context still shipped an app with a scatter, a sparkline and a table - three forms out of eighteen. It reached for more only when told to, and then found them immediately, because **the forms were sitting in fields it had not enumerated**.
+
+So before you choose a single tile, write the inventory down:
+
+1. **List every dimension and measure the model exposes - and then look at the underlying table columns too.** Not the named views: views are someone else's earlier answer to a different question. And a model's \`extend\` block is a curated subset, so the columns it did not promote are exactly where an unused form hides. On a real build the single best tile came from a \`release_date\` column the model never declared as a dimension; a model-first reading would have missed it entirely. Where your host gives you a schema tool, run it; otherwise \`run: <source> -> { select: *; limit: 1 }\` shows you the columns.
+2. **Check the model's own measures against the raw values before you trust one.** A declared measure is someone's earlier reading of the data, and it can be wrong in a way that inverts your headline. Profile the column a measure depends on - its distinct values, its null count - and confirm the measure means what its name says. Pay particular attention to any predicate of the form \`!= null\`, \`is not null\` or a boolean derived from one: a column whose "absent" case is a **sentinel string** rather than a null breaks them silently. On a real build, \`cleared_count is count() { where: clearance_status != null }\` counted every row whose status was the literal string \`'Not cleared'\`, reporting 95.6% of cases cleared where the truth was 16.6%. Nothing in the app would have looked broken. If a measure is wrong, do not use it: define what you need in the app's queries, say in the app that you did, and tell whoever owns the model.
+3. **Mark the ones no line, bar or table can show well.** A part-to-whole breakdown (several measures that sum to a total), a paired value per entity (home/away, before/after, actual/target), a per-row distribution, a second entity reference on the same row (an opponent, a referrer, a parent), a date that supports a calendar or a cohort, a flag that splits a population.
+4. **For each, name the question it answers** and take the form from the table below.
+
+That is the step that changes the output. A field like \`points_second_chance\` next to three sibling scoring columns *is* a composition bar; \`home_wins\` and \`away_wins\` on one row *is* a dumbbell; a margin column *is* a distribution. None of these are visible if you start from the view list.
+
+**The test:** if your app has three or fewer distinct forms and the model exposes more than about fifteen fields, you enumerated rather than designed. Go back to step 3.
+
+These forms assume the app draws its own charts with a vendored chart library, where any form is available. An app that renders through the Malloy renderer's chart tags instead is working with a narrower vocabulary - it has no native treemap, funnel, or bullet, and a chart-tag skill will offer approximations for them. Design to whichever vocabulary the app actually uses, and do not carry the renderer's substitutions into an app that could draw the real form.
+
+| The question | Form | Misused when |
+|---|---|---|
+| How did this move over time? | Line, or area for one cumulative series | Categories on the x-axis. That is a bar chart. |
+| Which categories are biggest? | Ranked horizontal bars | More than ~15 bars, or a category axis with an inherent order (use a line). |
+| How does one entity score across many criteria? | Radar | Axes on different scales. Normalize, or do not use it. |
+| Where did the total go, step by step? | Waterfall | Steps that are not additive to the total. |
+| How does actual sit against target? | Bullet, or bar with target marker | A second bar for target, which reads as a category rather than a threshold. |
+| What is the distribution, not the average? | Histogram, box, or strip | Small n, where individual points are more honest. |
+| How do two measures relate, and who are the outliers? | Scatter, bubble for a third | Dense overplotting with no encoding of density. |
+| How does a cohort behave over its life? | Retention/cohort heatmap | Cohorts too small to read as rates. |
+| Where do people drop out of a sequence? | Funnel | Steps that are not strictly sequential or not a subset of the prior. |
+| How did rank change between two points? | Slope, or bump for many periods | More than ~20 entities, which becomes spaghetti. |
+| How does a total break into parts, with magnitude? | Treemap | Parts that do not sum to a meaningful whole. |
+| Where does volume flow between stages? | Sankey | Cycles, or more than a few stages. |
+| How do two groups compare on one axis? | Diverging bars | **Disjoint category vocabularies.** See the trap below. |
+| Composition as a share of a countable whole | Waffle | Continuous quantities, where it implies false discreteness. |
+| How much do two or three sets overlap? | Venn / upset | More than three sets, where upset is the only readable option. |
+| The same small chart across many facets | Small multiples | Facets with wildly different y-ranges and a shared axis. |
+| One number, in context | Big value with sparkline and delta | A number with no comparison, which carries no information. |
+| The records themselves | Table, sortable, with inline bars | Used as the default because no form was chosen. |
+
+Two traps worth naming, because they produce charts that are *readable and wrong*:
+
+- **Diverging bars on disjoint vocabularies.** If the positive and negative sides are drawn from different taxonomies (an NLP model whose praise labels and complaint labels do not overlap), a diverging chart keyed on a shared label renders nearly every row one-sided and implies a balance the data does not contain. Use two ranked lists side by side.
+- **A shared axis across different scales.** Mixing a 0-7 rating with a 0-10 rating on one radar, or two measures with different units on one y-axis, silently lets the larger scale dominate. Normalize, use a second axis explicitly labeled, or split the chart.
+
+Pie and donut are absent from that table on purpose. They answer "what is the composition" worse than a ranked bar or a waffle at almost every n. Use one only when parts-of-whole is the entire message and there are two or three parts.
+
+## 4. Plan the depth
+
+This is what separates a tool from a page. Decide which of these the app gets, from the "what does the user do next" answer in §1. A monitor may take none; an explorer or workbench should take most.
+
+| Pattern | What it gives the user | Decide it when |
+|---|---|---|
+| **Drill-down** | A number leads to the rows behind it | Any tile where "why is that number that?" is the obvious next question |
+| **Shared scope** | Clicking a category filters the other tiles | The app has a dimension the whole page should agree on |
+| **Linkable state** | A view someone can paste into Slack | Always, unless the app has no state at all |
+| **Entity detail** | One row's profile, trend, and actions | The population has entities a user cares about individually |
+| **Comparison** | Two or more entities side by side, same definitions | Users pick between things, rather than just monitoring them |
+| **Provenance** | The query behind a number, on demand | The number will be challenged by someone who did not build the app |
+
+The one that shapes the model rather than the page is **drill-down**. A drill target is a parameterised source that extends the spine, so every inherited measure comes back already filtered to that entity and the panel names a *view* rather than recomputing anything. That keeps one definition of every number, so a drawer and a question asked of an agent answer the same way, and it keeps drill logic out of hand-built query strings in the page, which is where drift starts. Plan it while you are still deciding the tiles: retrofitting drill onto an app whose numbers were computed in JavaScript means rewriting both.
+
+\`reference/depth-patterns.md\` carries the mechanics for all six - the state bus, URL-hash rules, the parameterised-source traps, the five parts of a correct drawer, and safe cross-filtering. Read it before building any of them: each has a failure that is quiet rather than obvious, and the two that bite hardest (a stale drill response painting one entity's numbers under another's title, and a filtered dashboard with no visible chips) look like bad data rather than bugs.
+
+Also decide what the app does **not** do. An explorer that cannot export, or a monitor with no link to the runbook, is usually a gap rather than a choice.
+
+## 5. Design for consistency without a shared kit
+
+There is no shipped component library. Consistency comes from a **token contract**: define the tokens in CSS, and have every chart read them at runtime rather than hardcoding color. That is what lets one app carry a client's identity while still looking like it was built on purpose.
+
+Three rules do the load-bearing work here:
+
+- **Chart code reads tokens at runtime; never a hex literal in a chart config.** \`getComputedStyle(document.documentElement).getPropertyValue('--c1')\` and friends. The payoff is that a client re-skin or a theme toggle is a token swap and the charts follow. If you do support a theme toggle, re-push chart options after the swap rather than reloading the page, since most chart libraries bake resolved colors at construction time and will otherwise keep the old palette.
+- **The same rule covers type, spacing and motion, not just color.** A font-size, spacing value, radius or duration that is not a token is a bug, exactly like a hex literal in a chart config. This is the half of the contract that rots when nobody states it: measured across three shipped data apps, each had 12 to 17 distinct ad-hoc font sizes and no type tokens at all. Sizes a half-point apart (10.5px, 11.5px, 13.5px) are the symptom - nobody designs those, you arrive at them by nudging one label at a time. Define a **closed**, ratio-based scale of eight type steps and pick the nearest one. Unlike a stray hex literal, a 12.5px is invisible on sight, so this rule only holds if you actually check it - grep the stylesheet for raw \`font-size:\` values before you call the app done, and expect the answer to be zero. Grep the JavaScript too: \`style.fontSize\`, \`style.padding\` and a hex literal in a chart config are the same violation wearing different clothes, and a chart-heavy app drifts there first because the stylesheet stays clean.
+- **Hierarchy through size and weight, not boxes.** The 2-3 numbers from §1 should be visibly primary, and the gap between them and everything else should come from the type scale rather than from per-tile judgment. If every tile is the same card at the same size, you have built a grid, not a hierarchy, and the reader has no way to tell what the app is for.
+
+\`reference/token-contract.md\` has the full list of tokens to define, a worked example, and the craft rules (domain conventions, formatting at the edge, tile captions) to follow when writing the stylesheet.
+
+**The contract is the floor, not the ceiling.** It buys consistency, and an app can satisfy every rule in it and still look like a generated admin panel: one surface colour used for every tile, a uniform grid, library-default charts, an accent that never appears at scale. That has been measured on a real build - every token rule green, and the page still read as generic. \`reference/visual-craft.md\` is the difference between consistent and designed: surface elevation rather than one flat plane, an accent that carries something structural, charts with direct labelling and annotation instead of library defaults, density that earns its space, motion as feedback, and type with enough contrast to separate the answer from the interface. Read it whenever the app is meant to feel like a product someone chose rather than a dashboard someone generated - which, for anything replacing a BI tool, is always.
+
+## What "done" means for the design
+
+Before building, you should be able to state, in a few lines:
+
+- who opens it, how often, and the decision it serves
+- the archetype, and why that one
+- the 2-3 numbers that lead, and what is supporting
+- for each tile: the question it answers and the form that answers it, with any default form you rejected and why
+- the depth plan: what drills into what, what shares scope, what goes in the URL
+- the token contract the app will use
+
+Hand that brief over before scaffolding. It is short, the user can correct it in one message, and correcting it then is far cheaper than rebuilding a finished app that answered the wrong question.
+
+## Reference files over MCP
+
+This skill's \`reference/\` files are served as separate prompts, one per file, fetched only when you ask for them. Where the text above says to read \`reference/<name>.md\`, get the prompt named \`malloy-data-app-design/<name>\` instead.
+
+Available: archetypes, depth-patterns, token-contract, visual-craft.`
+    },
+    {
+      name: "malloy-data-app-design/archetypes",
+      description: "The five archetypes. Reference detail for the malloy-data-app-design skill.",
+      body: `# The five archetypes
+
+> Expanded from \`SKILL.md\` §2. Read when you have picked an archetype and need to know what it actually looks like, or when you are deciding between two that seem close.
+
+Each entry below gives the job, what leads the page, the depth that belongs, and the failure mode that turns it back into a generic dashboard. Where the arrangement itself is the point, there is a layout sketch: those are shapes, not templates, so copy the hierarchy rather than the box count.
+
+Anything below that says "drawer", "drill", or "cross-filter" has its mechanics in \`reference/depth-patterns.md\`; read that before building one.
+
+## Monitor
+
+**Job:** is anything wrong right now? Opened often, read in seconds, usually not read at all when things are fine.
+
+**Leads with:** state, not level. "3 breaching" beats a chart of the metric. Deltas and thresholds, not raw numbers.
+
+**Depth:** shallow on purpose. Drill into an anomaly and nothing else. Linkable state so an alert can point at the exact view.
+
+**Fails when** it grows sections. Each added section costs scan time, which is the only thing a monitor sells. If the reader has to look for the problem, it has stopped being a monitor.
+
+## Scorecard
+
+**Job:** are we hitting the target? Read on a cadence, by someone accountable for the number.
+
+**Leads with:** variance to target, sorted so the misses are at the top. An alphabetical metric list buries the thing the reader came for.
+
+**Depth:** drill from a miss to its drivers - the split by the one dimension that explains it. Name that dimension per metric while designing; if there is no useful split, say so rather than inventing one.
+
+**Fails when** every metric gets equal weight and the reader has to compute variance themselves. A scorecard whose rows are just current values is a KPI grid.
+
+## Explorer
+
+**Job:** what is going on in this population, and which entities deserve attention? Used by an analyst who arrives with a question the app's author did not anticipate.
+
+\`\`\`
+[ scope bar: active filters as removable chips        ]
+[ ranked list: the entities, by the measure that matters ]
+[ distribution: where this entity sits among the rest    ]
+[ click any row -> entity drawer: profile, trend,        ]
+[   composition, add-to-comparison                       ]
+[ comparison tray: collected entities, side by side      ]
+\`\`\`
+
+**Leads with:** the ranked population, not a total. A total is the one number an explorer's user already knows.
+
+**Depth:** deep, and this is where it is the point. Drill-down, entity detail, comparison, cross-filtering, all backed by parameterised detail sources so every panel inherits one definition.
+
+**Fails when** it is built as a flat page of aggregate charts. If a user cannot get from "this bar is tall" to the rows behind it, they will export to a spreadsheet and you have lost.
+
+## Workbench
+
+**Job:** do the recurring work of a role. Opened daily by the same person, who knows exactly where everything is.
+
+\`\`\`
+[ sidebar nav ][ shared controls: period, unit, as-of     ]
+[ one page     ][ page content, dense, tables welcome      ]
+[  per subject ][ every page obeys the shared controls     ]
+[  area        ][ drill panel over the top for one entity  ]
+\`\`\`
+
+**Leads with:** whatever that page's subject leads with. A workbench has no single front page; the overview is one page among several, not the app.
+
+**Depth:** deep, and specifically *cross-page*: state shared across pages, an entity drawer reachable from anywhere, export, and linkable state so a colleague can be sent one exact view. Density is a feature here - this user wants more on screen, not less.
+
+**Fails when** it is one long scrolling page with headings instead of real navigation, or when each page invents its own period control. Shared controls that do not apply everywhere are worse than no shared controls.
+
+## Briefing
+
+**Job:** explain what happened and why, to someone who was not watching. Read once, start to finish.
+
+\`\`\`
+[ the headline finding, in a sentence                 ]
+[ the one number that carries it, large               ]
+[ prose: what happened                                ]
+[ chart: the evidence for that claim                  ]
+[ prose: why, and what was ruled out                  ]
+[ chart: the driver                                   ]
+[ what to do about it / what to watch                 ]
+\`\`\`
+
+**Leads with:** the conclusion. A briefing that opens with methodology has buried its point.
+
+**Depth:** shallow. Link out to an explorer or workbench for anyone who wants to dig; do not build the digging into the briefing itself.
+
+**Fails when** it becomes a dashboard with captions. The test: remove the prose. If the page still makes the same argument, the prose was decoration and the form should have been something else; if the argument collapses, the prose is doing its job.
+
+## Choosing between two that seem close
+
+| If you are torn | Ask | Decide by |
+|---|---|---|
+| Monitor vs scorecard | Is the reader checking for problems, or reporting against a commitment? | Problems -> monitor. Commitment -> scorecard. |
+| Scorecard vs explorer | Is the metric list fixed and agreed, or is the question open? | Fixed -> scorecard. Open -> explorer. |
+| Explorer vs workbench | One population, or several subject areas? | One -> explorer. Several -> workbench. |
+| Workbench vs several apps | Do the pages share controls and a user, or just a data source? | Share a user -> one workbench. Share only data -> separate apps. |
+| Anything vs briefing | Will this be read once, or repeatedly? | Once -> briefing. Repeatedly -> the other one. |
+
+When two genuinely apply to different audiences, that is two apps, not one app with a mode switch. The compromise app serves neither, and it is the most common way a good brief still produces a generic result.`
+    },
+    {
+      name: "malloy-data-app-design/depth-patterns",
+      description: "Depth patterns. Reference detail for the malloy-data-app-design skill.",
+      body: `# Depth patterns
+
+> The mechanics behind the depth plan in \`SKILL.md\` §4. Read when building drill-down, cross-filtering, linkable state, or an entity drawer. Each pattern names the bug you get by skipping a part, because every one of these fails quietly rather than loudly.
+
+## Shared state with a subscriber bus
+
+Any app with a control that more than one tile obeys (a period selector, a unit toggle, a cross-filter) needs one place to hold that state and one way to tell tiles it changed. Without it, each tile grows its own copy and they drift out of sync.
+
+\`\`\`js
+const state = { month: null, period: "m", unit: "k" };
+const subs = [];
+const emit = () => { subs.forEach((fn) => fn()); syncControls(); writeHash(); };
+
+// Each tile registers its own redraw and never reads another tile's state.
+subs.push(() => redrawRevenue());
+\`\`\`
+
+Three rules keep this from turning into a tangle:
+
+- **Tiles subscribe; they do not push.** A tile reads \`state\` and redraws. Only a control calls \`emit()\`.
+- **\`emit()\` also writes the URL.** State that is not in the URL is state a user cannot share (see below).
+- **A tile that is expensive to redraw should check whether its slice of state actually changed.** A unit toggle does not need a refetch, only a reformat, and refetching on every keystroke of a filter is how an app becomes slow.
+
+## Linkable state
+
+Put page, period, and filters in the URL hash and read them on load. This is the single cheapest thing that gets an app adopted: a view someone can paste into Slack beats one the recipient has to re-navigate.
+
+\`\`\`js
+// #pnl?m=2026-06&p=q&u=eur
+function writeHash() {
+  if (!state.month) return;
+  const p = new URLSearchParams({ m: state.month });
+  if (state.period !== "m") p.set("p", state.period);   // omit defaults: shorter, and
+  if (state.unit === "eur") p.set("u", "eur");          // the default can change later
+  history.replaceState(null, "", \`#\${currentPage}?\${p}\`);
+}
+\`\`\`
+
+Use \`replaceState\`, not \`pushState\`, for filter changes: every tweak of a dropdown becoming a back-button step makes the back button useless. Reserve \`pushState\` for navigation the user would expect to undo, like opening a different page.
+
+**Key the URL on a name, not a position.** A row index or a group number is only stable if the query that produced it has a total order, and "sort by size" is not one: two groups of equal size come back in whichever order the warehouse returns them, so the index in the URL points at a different thing on each load. That failure is invisible in testing, because it needs a tie. Either key on something stable (the entity's name or id) or give the query a tie-breaker (\`order_by: size desc, name\`). Validating the value on read does not catch this, because the value is perfectly valid and simply means something else.
+
+**Validate on read.** A hash is user-editable, so treat it as untrusted input: check a page id against the known list and a period against the known set, and fall back to the default rather than trusting it into a query.
+
+## Drill-down: the model side
+
+A drill target is a **parameterised source that extends the spine**, so every inherited measure and view comes back already filtered to that entity. The drill panel then names a *view* and recomputes nothing.
+
+\`\`\`malloy
+##! experimental.parameters
+
+source: product_detail(pid::number is 0) is products extend {
+  where: product_id = pid
+  view: profile is { ... }
+}
+\`\`\`
+
+The flag is per-file and required: without it the parameter list is a parse error, and a \`.malloy\` file that fails to parse fails the **whole package load**, so every tile goes blank rather than just the drill.
+
+Two traps worth knowing before you build several of these:
+
+- **A persisted rollup is still read through a wrapper.** Extending or wrapping a persisted source keeps the persist annotation and still reads the built table, so a parameterised detail source over a rollup does not silently recompute it. The pattern is safe, and a slow drill is almost never the wrapper: look first at a missing filter or a grain that is not actually aggregated.
+- **An inherited view can be meaningless under a parameter.** A source scoped to one entity inherits views that only make sense across many: a sentiment split on a single-sentiment theme collapses to 0% or 100%, a share-of-total becomes 100%. Declare purpose-built views on the detail source for those, and say in the source's doc comment which inherited views not to use.
+
+### When you cannot change the model
+
+Often you can't: the model is owned by another team, synced from somewhere else, or the brief scopes you to the app. The parameterised source is still the right answer to *propose* - say so, because it is a small model change that removes a whole class of drift - but you may have to ship without it.
+
+Falling back to query strings built in the app is legitimate. What makes it safe is keeping the drill queries under the same discipline as the tile queries, not treating them as one-off strings:
+
+- **Put them in the same module** as the tile queries, next to the tile they drill from. A drill query that lives in the render code is the drift the pattern warns about.
+- **Share one filter builder and one definition of every derived measure.** If a rate is pooled in a tile, the same helper must pool it in the drawer. Two spellings of the same measure is how a drawer quietly disagrees with the row that opened it.
+- **Assert it.** A unit test over the query strings - every one filters to the entity, every rate uses the shared helper - costs a few lines and catches the drift that code review will not.
+
+Write down that you did this and why. A reader who later sees hand-built drill queries should find the reason, not assume the pattern was unknown.
+
+## Drill-down: the panel side
+
+An entity drawer has six parts. Skipping any one produces a bug that only shows up in use, not in a screenshot.
+
+\`\`\`js
+const drill = { entity: null, charts: [], returnFocus: null };
+
+function openDrill(entity) {
+  drill.entity = entity;
+  drill.returnFocus = document.activeElement;   // 1. remember where focus came from
+  panel.hidden = false;
+  requestAnimationFrame(() => {
+    panel.classList.add("is-open");
+    document.addEventListener("keydown", onTab);  // 2. trap Tab inside the panel
+    renderDrill();
+  });
+}
+
+function renderDrill() {
+  const entity = drill.entity;
+  loadRows(entity).then((rows) => {
+    if (drill.entity !== entity) return;   // 3. stale-response guard
+    paint(rows);
+  });
+}
+
+function closeDrill() {
+  drill.entity = null;
+  panel.classList.remove("is-open");
+  document.removeEventListener("keydown", onTab);
+  drill.charts.forEach((c) => c.destroy());     // 4. tear charts down
+  drill.charts = [];
+  drill.returnFocus?.focus();                   // 5. give focus back
+}
+\`\`\`
+
+What each part prevents:
+
+1. **Return focus** - without it, closing the drawer drops a keyboard user at the top of the document, losing their place in a long table.
+2. **Focus trap** - without it, Tab walks out of the open drawer into the page behind it, which is invisible to a mouse user and completely breaks a keyboard one. Close on Escape too.
+3. **Stale-response guard** - the real bug. Click entity A, then quickly click entity B: A's slower query resolves last and paints A's numbers under B's title. It is intermittent, looks like bad data rather than a race, and is close to impossible to diagnose from a screenshot. Compare the entity you are about to paint against the one currently open, and drop the response if they differ.
+4. **A closed panel that still takes clicks.** If the drawer's own CSS sets \`display\` (a \`grid\` or \`flex\` layout on the panel itself), that wins over the \`hidden\` attribute, so the panel stays in the layout at zero opacity and swallows every click aimed at the page behind it. Nothing looks wrong; the app simply stops responding in that region. Guard it once, globally: \`[hidden] { display: none !important }\`.
+5. **Chart teardown** - most chart libraries keep a registry and attach resize listeners; reopening a drawer twenty times without destroying leaks memory and can leave ghost tooltips from the old instance.
+6. Also re-render the drawer when the global filter changes underneath it, or it silently shows numbers for a period the rest of the page has moved off.
+
+## Cross-filtering (shared scope)
+
+Clicking a category filters the other tiles. Express scope as a \`where:\` refinement on the **same named view** each tile already runs, so a filtered tile and an unfiltered one still share one definition.
+
+\`\`\`js
+function scopeWhere(ignore) {
+  const parts = Object.entries(SCOPE)
+    .filter(([k]) => !ignore?.includes(k))
+    .map(([k, v]) => \`\${k} = \${lit(v.value)}\`);
+  return parts.length ? \` + { where: \${parts.join(" and ")} }\` : "";
+}
+\`\`\`
+
+Three requirements, in order of how badly they bite:
+
+- **Every active filter is visible and removable.** A chip per filter, with an X, and a clear-all. A filtered dashboard with no visible chips silently lies to the next person who looks at it - they read filtered numbers as totals. This is the one non-negotiable part of cross-filtering.
+- **A tile ignores its own dimension.** The tile you clicked to set \`category = X\` should not then filter itself to X, or it collapses to a single bar. That is what the \`ignore\` argument is for.
+- **Escape interpolated values correctly, or avoid interpolating.** Malloy escapes with a backslash, not by doubling quotes - \`''\` closes the string and opens a new one, so a value like \`Land O'Lakes\` produces a malformed query. Prefer binding the value as a typed runtime parameter (a \`given:\`, declared behind \`##! experimental.givens\`, and passed by the runtime rather than pasted into the string) over building query text at all; where you must interpolate, constrain values to a known set and backslash-escape quotes and backslashes.
+
+## Comparison
+
+Collect entities into a tray, then compare them side by side. Back it with a source parameterised on the **pair**, returning one row per entity, so both sides use identical definitions rather than two separately-written queries that might not agree.
+
+\`\`\`malloy
+##! experimental.parameters
+
+source: head_to_head(a::number is 0, b::number is 0) is products extend {
+  where: product_id = a or product_id = b
+  view: scorecard is { group_by: product_id, ... }
+}
+\`\`\`
+
+Persist the tray across navigation (session storage is enough), or a user who found three interesting entities on three different pages cannot actually compare them - which is the whole point of collecting.
+
+## Provenance
+
+Let a tile show the query behind its number, pulled from the tile's own definition rather than retyped. It costs one chip per tile and it is what makes a number defensible to someone who did not build the app. It also pays off when handing context to an agent: the exact query string the tile ran is far more useful than the name of the source it came from.`
+    },
+    {
+      name: "malloy-data-app-design/token-contract",
+      description: "The token contract. Reference detail for the malloy-data-app-design skill.",
+      body: `# The token contract
+
+Read when setting up an app's stylesheet, or when reskinning one for a client.
+
+There is no shipped component library, so visual consistency across apps comes from every app defining the same *kinds* of token and every chart reading them at runtime. The values are free - that is what carries a client's identity. The contract is the shape.
+
+## What to define on \`:root\`
+
+| Group | Tokens |
+|---|---|
+| Surfaces | page background, card surface, a raised and a sunken variant, border, strong border |
+| Text | strong, default, muted, soft - a real ramp, not one color at three opacities |
+| Semantic | positive, negative, warning, each with a soft background variant for fills and badges |
+| Chart palette | a categorical ramp of 6-8, ordered so the first is the brand accent, plus grid and axis-tick colors |
+| **Type** | a **closed** size scale of exactly 8 steps, plus the weights, line-heights and letter-spacings you actually use |
+| **Spacing** | a scale (4 / 8 / 12 / 16 / 24 / 32 / 48), not a single step that gets multiplied and divided in place |
+| Structure | a radius scale (small, default, large), a shadow for cards and a deeper one for popovers |
+| **Motion** | two transition durations (fast, base), one easing, and a separate duration for any looping animation |
+
+**Every one of these groups needs the same mechanical rule, or half the contract quietly rots.** The colour half of this contract holds up in practice because it carries a rule you can check by grep - never a hex literal in a chart config. Type, spacing and motion have no such rule in most apps, and they are exactly where real apps drift: measured across three shipped data apps, each had 12 to 17 distinct ad-hoc font sizes and zero type tokens. The giveaway is half-point sizes (10.5px, 11.5px, 13.5px) - nobody designs those, you land on them by nudging one label at a time. So state the rule the same way for every group:
+
+> A font-size, spacing value, radius, duration or colour that is not a token is a bug, the same as a hex literal in a chart config.
+
+The scale being **closed** is what does the work. Eight type steps you must choose from produces hierarchy; an open-ended "define a type ramp" produces fourteen sizes a half-point apart. Pick the step nearest your intent and move on - if two things want to differ by half a point, they are the same step.
+
+Build the scale on a **ratio**, not by listing sizes that feel right. Four steps inside a 3px range is the same crowding as half-points, one notch coarser: they invite the same nudging, and nothing in the scale tells you which to reach for. Roughly 1.2x between steps at the small end, widening toward the display sizes, gives steps that are visibly different from each other.
+
+## The values are a decision, and the default is the problem
+
+The contract fixes the *shape* of the palette. It does not choose the colours, and left unchosen an app lands on the same one every time: a cold blue-grey ground somewhere around \`#0e1015\`, slate surfaces, and a mid-blue accent near \`#56a7e8\`. That combination is the house style of every admin panel ever generated. It is not wrong; it is *unchosen*, and a reader can tell the difference immediately.
+
+Measured on two real builds: both agents produced almost exactly that palette unprompted, and both apps read as generic until the hue was repitched deliberately.
+
+So make two decisions on purpose and write down the reason:
+
+- **Pick a temperature for the neutrals.** Warm greys (a paper-toned light ground, a warm charcoal dark one) read differently from the default cool slate and cost nothing. A data page is read for a long time; warmth is easier to sit with, and it stops the page looking like a framework default.
+- **Derive the accent from something.** The domain, the client's brand, the material the data is about. An accent chosen for a reason is defensible and usually more distinctive than a stock blue. If nothing suggests one, a warm accent against cool neutrals (or the reverse) at least reads as a choice.
+
+The test is whether you can say *why* this hue and not another. "It is the default" is the answer that produces the generic app.
+
+A worked example. The neutrals here are deliberately **warm** and the accent is a burnt orange rather than the default indigo, to show what "chosen" looks like - swap both for whatever your own reason produces; what you must not do is leave them at the framework default:
+
+\`\`\`css
+:root {
+  --bg: #f4f1ee;          /* warm paper, not cool #f4f5f8 */
+  --surface: #fefdfc;
+  --surface-2: #f7f4f1;
+  --border: #e6e0da;
+
+  --text-strong: #17130f;  /* warm ink, so text sits on the paper */
+  --text: #4a423b;
+  --text-muted: #7d746b;
+
+  --positive: #0e9f6e;  --positive-soft: #e3f6ef;
+  --negative: #dc2626;  --negative-soft: #fdeaea;
+  --warn: #d97706;
+
+  --c1: #d95a12; --c2: #2f7ec9; --c3: #12805a; --c4: #8250d4;
+  --c5: #a76d0a; --c6: #c73641; --c7: #17909e; --c8: #7d746b;
+  --grid: #efeae4;
+  --tick: #9c9289;
+
+  /* Type: a closed scale, ratio-based. Pick the nearest step; never invent one between two. */
+  --fs-xs: 10px;  --fs-sm: 12px;  --fs-md: 14px;  --fs-base: 16px;
+  --fs-lg: 20px;  --fs-xl: 26px;  --fs-2xl: 34px; --fs-3xl: 46px;
+  --fw-normal: 400; --fw-medium: 500; --fw-semi: 600; --fw-bold: 700;
+  --fw-display: 800;   /* the headline numbers; see visual-craft.md on type contrast */
+  --lh-tight: 1.2; --lh-body: 1.5;
+  /* Tracking, or the nudging just migrates here from font-size. */
+  --tr-tight: -0.01em; --tr-display: -0.02em; --tr-caps: 0.05em;
+
+  /* Spacing: a scale, not one step multiplied in place. */
+  --sp-1: 4px;  --sp-2: 8px;  --sp-3: 12px; --sp-4: 16px;
+  --sp-5: 24px; --sp-6: 32px; --sp-7: 48px;
+
+  --radius: 10px;
+  /* Warm-toned shadows too, or they grey the paper. */
+  --shadow-card: 0 1px 2px rgba(60, 44, 32, 0.05);
+  --shadow-pop: 0 8px 28px rgba(60, 44, 32, 0.12);
+
+  --dur-fast: 120ms; --dur-base: 200ms; --dur-loop: 1400ms;
+  --ease: cubic-bezier(0.32, 0.72, 0, 1);
+
+  /* Component dimensions. The spacing scale governs gaps and padding; an
+     intrinsic size like a table row height is its own token, not a violation. */
+  --row-h: 34px;
+}
+\`\`\`
+
+The spacing scale covers **gaps and padding**. A component's intrinsic dimension - a table row height, a control height, a sidebar width - will not always land on that ladder, and forcing it there makes rows cramped or loose. Give each such dimension its own named token instead, and use it everywhere that component appears; the rule is one source of truth per value, not that every value divides by four.
+
+Honour the viewer's motion preference wherever you use those durations:
+
+\`\`\`css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;   /* or an infinite loop still loops, just faster */
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+\`\`\`
+
+Charts then resolve their colors from the contract rather than carrying literals:
+
+\`\`\`js
+const token = (n) => getComputedStyle(document.documentElement).getPropertyValue(n).trim();
+const palette = () => ["--c1","--c2","--c3","--c4","--c5","--c6","--c7","--c8"].map(token);
+\`\`\`
+
+## Craft rules that carry most of the visual quality
+
+- **Respect domain convention.** Finance shows negatives in parentheses, zero as a dash, and usually wants a unit toggle (units vs thousands vs millions); ops wants thresholds, staleness, and a clear "as of" time. Getting these wrong is what marks an app as generic to the people who live in the domain, regardless of how good the layout is.
+- **Format at the edge, once.** Currency, percent, compact notation, and date labels belong in one shared formatter module, not re-derived per tile. Divergent rounding between two tiles showing the same measure is a bug users notice and lose trust over.
+- **Every tile states what it is.** A title, plus a subtitle giving the definition or the window ("trailing 8 weeks", "excludes internal users"). A number whose definition is not on screen invites the wrong conclusion, and the person drawing it is rarely the person who built the model.
+- **Reserve space for async content.** Give each tile its height before its query resolves, or the page reflows as tiles land and anything the user was reading jumps.`
+    },
+    {
+      name: "malloy-data-app-design/visual-craft",
+      description: "Visual craft. Reference detail for the malloy-data-app-design skill.",
+      body: `# Visual craft
+
+> \`token-contract.md\` is the floor: it buys **consistency**, and an app can satisfy every rule in it and still look like an internal admin tool. This file is the ceiling. Read it when the app should feel like a product someone chose, not a dashboard someone generated.
+
+The failure this prevents is specific and it is easy to miss, because nothing about it is *wrong*: every tile is the same rounded rectangle, on the same surface, with the same border, laid out in a uniform grid. Tokens are all correct. Hierarchy exists on paper - the lead tiles are bigger - but they are the same object bigger, so the page still reads flat. Measured on a real build, that app cleared every token rule and still read as generic.
+
+Seven things separate that from an app that feels designed. None of them is decoration; each is doing a job.
+
+## 1. Fewer containers, then elevation
+
+**Start by deleting boxes.** One \`--surface\` used eleven times is a grid of boxes, and the fix is not a better box or a taller ladder: it is that most content does not want a container at all. Sections separated by a hairline and generous whitespace on a single canvas read as a designed page; the same sections wrapped in eleven bordered, shadowed rectangles read as a generated one, no matter how good the tokens are.
+
+This is the correction that mattered most on a real build. An app that satisfied every rule in this file, with a full four-level ladder and no \`.card\` class anywhere, still read as generic because every tile sat in its own container. Redrawing it as one sheet divided by hairlines, with exactly one lifted surface (the drawer), was the single biggest change.
+
+So the order is:
+
+1. **Default to no container.** A heading, a subtitle and the content, on the page ground. Let whitespace and a hairline do the separating.
+2. **Add a container only when something must read as a separate plane** - something that floats over the page (a drawer, a popover, a tray), or one region that genuinely leads (a hero band).
+3. **Then** give the few surfaces you kept a real elevation difference, using the ladder below.
+
+A useful check: count the bordered rectangles on your first screen. More than two or three and you are almost certainly boxing things that would read better as bare sections.
+
+Where you do keep a surface, a designed page has a small, deliberate **elevation ladder**, and a level says what a thing is.
+
+| Level | What sits here | How it reads |
+|---|---|---|
+| 0 | page ground | the darkest (or lightest) plane, nothing floats on it directly |
+| 1 | ordinary tiles | the working surface, subtle border, minimal shadow |
+| 2 | the lead tiles, an open drawer | lifted: lighter surface, a real shadow, often a soft gradient |
+| 3 | popovers, menus, tooltips | clearly above everything, strongest shadow, no border needed |
+
+Three things make a level read as lifted, and you generally want at least two:
+
+- **A lighter surface**, not a different hue. A gradient of 2-4% over the base surface is enough, and it beats a flat fill because the top edge catches light.
+- **A shadow that matches the level.** A 1px shadow at level 2 is indistinguishable from level 1, which is why the "shadow-card / shadow-pop" pair in the contract is a minimum, not a palette.
+- **A hairline highlight on the top edge** (\`inset 0 1px 0 rgba(255,255,255,.06)\` on dark). This is the cheapest trick in the file and it does more than a shadow: it is what makes a surface look like a physical panel rather than a coloured rectangle.
+
+Borders are for *separation*, not elevation. A tile that is lifted needs less border, not more.
+
+Elevation has consequences for what sits *inside* a panel, and both of these bite immediately: a sticky table header inside a tile needs its own opaque surface background, or rows scroll visibly underneath it, and it needs a stacking context, or in-cell bars and chips draw over it.
+
+## 2. The accent must appear at scale, or the app is monochrome
+
+A palette with a brand accent that only ever appears on a 2px hairline and a sort arrow reads as grey. The accent has to carry something structural: the selected row, the primary series in every chart, the focused control, the active nav item, the one number that matters most on the page.
+
+The discipline that keeps this from turning gaudy: **one accent moment per region**, where a region is the unit the eye scans as a group - a row of lead tiles is one region, not three; a table is one; a chart is one. The eye should be able to find "the thing this section is about" without reading. If two things in a region are accented, neither is.
+
+Reserve the semantic colours (positive/negative) for *values*, never for chrome. A green button and a green number in the same view means green stopped meaning anything.
+
+## 3. Charts need craft, not just a correct type
+
+A correct chart type drawn with library defaults is the single biggest tell of a generated app.
+
+**This section applies to a chart you draw by hand as well.** A small SVG written directly is often the right call for a sparkline, a gauge or a single annotated shape, and it does not escape any of the rules below: hand-drawn text still collides with the marks it labels, still needs a measured gutter, and still needs the grid turned down. The only thing that changes is that there is no library default to turn down, which makes it easier to get right and easier to forget. The chart is usually the largest object on the page and it is where the least design attention goes.
+
+- **Label the data directly.** A legend makes the reader look away from the marks and back again. Put the series name at the end of its line, the category on its bar, the notable points on the scatter. A legend is a fallback for when direct labelling genuinely will not fit. Expect to hand-write this: most chart libraries have no direct-label or annotation layer, so it is a small custom plugin drawing on the canvas. Two traps make the first attempt look broken - text drawn at the plot's right edge prints *over* the marks, so reserve a gutter in the layout and draw past the edge into it, and that gutter has to be **measured** with the same font or the longest label clips.
+- **A scatter where you cannot identify a point is a texture, not a chart.** Label the outliers and the extremes, at minimum. If the user has selected an entity, that point is accented and every other point recedes.
+- **Recede the grid.** Gridlines should be the faintest thing in the frame - they are scaffolding, not data. Kill the ones you do not need entirely, and never draw a border around the whole plot.
+- **Annotate the meaning.** A quadrant chart with unlabelled quadrants makes every reader derive the same insight from scratch. "Good offence, poor defence" in the corner costs nothing and is the actual content.
+- **Turn the library's defaults down before anything else.** Every chart library ships weights tuned to be visible in a demo: thick bars in a saturated primary, 1px gridlines at full opacity, heavy axis lines, large points. A chart left at those defaults is recognisable as a default from across the room, however good the form choice was. Concretely: bars and lines take the palette token rather than the library colour, gridlines drop to the faintest token you have (or disappear), axis lines and tick marks go off, and point radius comes down until the marks stop competing with each other. This is usually a dozen lines of options and it is the difference between "a chart" and "a designed chart".
+- **Ink goes to data.** Axis lines, tick marks, and borders are almost always too heavy at library defaults. Turn them down until the data is the only confident thing in the frame.
+
+## 4. Density: a number earns its space
+
+A 44px number with a large empty region under it is not emphasis, it is unfinished layout. Emphasis comes from *contrast with its neighbours*, not from absolute size, so a big number in a sparse card reads as smaller than a medium number in a dense one.
+
+Two rules of thumb:
+
+**Three equal KPI cards across the top is the most recognisable generated-app tell there is.** Every generated dashboard opens with it, and it is wrong twice over: three identical containers repeated side by side is repetition rather than a headline, and three equal-weight numbers mean the page has no subject. Build **one hero band** instead - a single region, panels divided by hairlines rather than gaps, and the leading number given a genuinely larger type step than its two supporting neighbours. The reader should be able to tell which number the page is about without reading a word.
+
+- **A lead tile should carry its supporting evidence,** not just its headline: the number, a comparison (versus last period, versus the field), and a small trend. That is what fills the space honestly, and it is more useful than the number alone.
+- **Give the hero at most a third of the first screen.** If the three lead tiles push the actual content below the fold, the page has led with its title rather than its substance. An explorer especially should show the population immediately.
+
+The most common structural cause of a sparse-looking page is not typographic at all, and it is invisible in a stylesheet diff: **a card whose content has a fixed height, sitting in a stretch-aligned grid row next to a taller sibling.** The card stretches, the content does not, and the difference becomes dead space under a chart. Either let the content flex to fill its card, or stop the row from stretching. Check this first when a page looks empty but every tile is correct.
+
+**An in-cell encoding needs its own column, not the cell behind the number.** A magnitude bar drawn *behind* a value is the muddiness problem again - a translucent wash under text that reads as a rendering artefact - and a short rule *under* each number is thirty unrelated stubs. What works is a narrow column of its own holding a diverging rule anchored at a shared zero: it becomes one scale you can scan down the table, and the number stays clean. Drop the encoding only if you cannot give it that column.
+
+Tables are where density pays. A stat table with generous row height wastes the one format that can show twenty things at once - tighten the rows, right-align the numbers, use tabular figures, and let the table be dense on purpose.
+
+## 5. Motion is feedback, not decoration
+
+Every state change the user causes should be acknowledged, and nothing else should move.
+
+- **Hover states on everything interactive**, and they must be visible: a surface shift, not a 2% opacity change nobody perceives. A row that opens a drawer on click must look clickable before the click.
+- **Transitions belong on state, not on load.** Animating *content* in on first paint delays the thing the reader came for. Animating a drawer open, a filter chip appearing, a sort re-ordering: those are feedback, and they are still right when the state came from the URL on first load.
+- **Focus states are not optional and not the browser default.** A keyboard user needs a visible ring drawn from the accent.
+- Keep it fast. Anything over ~250ms on a UI transition feels sluggish; the contract's \`--dur-fast\` / \`--dur-base\` pair exists so these stay consistent.
+
+## 6. Type carries personality
+
+The default stack at 400/600/700 is the house style of every admin panel. Two cheap decisions move an app a long way:
+
+- **Pair a display face with the UI face.** Numbers are usually the subject in a data app: setting the headline figures in something with character (a tighter grotesque, a condensed face, or the same family at a much heavier weight with tight tracking) separates "the answer" from "the interface" before anyone reads a word. **Bundle the face with the app** - a font file in the package, never a CDN or a hosted-fonts stylesheet, for the same reason chart libraries are vendored: the page may be served somewhere with no network egress, and a font that silently fails to load takes the whole typographic idea with it. A *variable* font is the cheap win here, since one file buys the heavy display weight the contract's regular ceiling otherwise blocks.
+- **Use tabular figures everywhere numbers align**, and proportional ones inside prose and names. Mixed tabular figures in a proper noun look broken.
+
+If the app uses one family, get the contrast from weight and tracking instead: display numbers at the heaviest weight with negative tracking, labels small at uppercase with positive tracking, body in the middle. The gap between the extremes is what reads as designed.
+
+**Vendor assets, and inline the small ones.** A chart library gets copied into the package; a logo or icon mark should be **inlined into the markup** rather than linked, for two reasons. A linked file fails silently to a blank square when the page is served from somewhere with no network egress, which is exactly where these apps run. And an inlined SVG can carry \`fill="currentColor"\` instead of a baked hex, so the mark follows a theme swap like everything else. Strip any XML prolog, DOCTYPE and editor metadata first, and keep the source file and its licence alongside the vendored library.
+
+## 7. It has to survive a narrower window
+
+A data app is a wide layout full of the two things that refuse to shrink: tables and charts. It will be opened in a half-screen window, an embedded panel, and a laptop narrower than yours, and the failure is not subtle - text prints on top of a plot.
+
+**Collisions do not show up as page overflow.** This is the trap. The obvious check is \`document.documentElement.scrollWidth > clientWidth\`, and on a real build that came back clean at every width *while a standings table was visibly overlapping the scatter chart beside it*. A grid column clips nothing by default, so its content happily draws over the neighbour without widening the document.
+
+The obvious next idea is to compare bounding rects instead, and **that lies too, in exactly the case the fix below creates**. Once you cap a table's container and let it scroll inside itself, the table's own rect is legitimately wider than its container while being visually clipped - so a naive rect comparison reports a collision on every scrollable table on the page. Measured on a real build: false positives at four widths, all of them fine. If you automate this at all, walk the ancestors and ignore overflow inside a **scrollable** box (\`overflow-x: auto | scroll\`), where the content is reachable. Do not extend that to a clipping box (\`hidden\`, \`contain\`): content lost inside one of those is a real bug, and suppressing it is how you stop seeing the thing you were looking for.
+
+**The only check that does not lie is rendering at several widths and looking at the screenshots.** Automate the capture, not the judgement.
+
+Three rules carry most of it:
+
+- **A table will exceed its grid column.** Its min-content width is the sum of its columns, so \`grid-template-columns: minmax(0, 1fr)\` is not enough on its own: the track can shrink while the table inside it does not. Cap the table's container explicitly and let it scroll inside itself. This is the single most common collision in a data app.
+- **Give up the least useful thing first, in stages.** Two breakpoints that collapse every two-column band at once turn a wide page into a very tall one - three full-width headline panels, each with a sparkline stretched across the sheet. A workable progression: narrow the chrome first, then let the headline drop a column, then stack the content bands, then turn a side rail into a top bar, and only then let wide tables scroll.
+- **A chart's minimum useful width is a design decision, not a default.** A sparkline stretched over a full sheet flattens into a horizon and stops reading as a trend; cap it. A scatter below roughly 320px cannot carry axis labels and marks at once; stack it instead.
+
+Also check the things that live outside the normal flow, because they are easy to forget and they are where the real breakage hides: an off-canvas drawer (does it become full-width, and does its internal grid drop to two columns?), a fixed bottom tray (does it wrap?), a sticky header (does it still clear the content?), and any element whose width is set in JavaScript rather than CSS.
+
+## The check
+
+Before calling the visual pass done, look at a screenshot of the first screen and answer honestly:
+
+- Can you tell what the page is *about* in one second, without reading?
+- Is there anything on screen that a reader would call the focal point?
+- How many bordered rectangles are on the first screen? More than two or three means you are boxing things that should be bare sections.
+- Does the page open with three equal KPI cards? If so it has no subject yet.
+- Could you tell the palette was chosen, or is it the default cool slate and mid-blue?
+- Do the charts look like the library's defaults - thick saturated bars, full-opacity gridlines, visible axis lines?
+- Could you identify a specific entity in each chart, or only see a shape?
+- Does the accent appear anywhere that matters?
+- Would you describe the page as dense, or as large elements with gaps between them?
+- Does it still hold together at 1200px and at 900px? (Render it and look. An overflow check will not catch a collision.)
+
+A "no" to most of these describes an app that satisfies the token contract and nothing more, which is exactly the app this file exists to prevent.
+
+## When restyling is not working, build a mockup instead
+
+If two passes over an existing app have produced "better, but still generic", stop restyling it. Editing inside the app's own markup keeps reproducing the app's structure: the cards are already there, the interactions constrain the layout, and every change becomes a local correction to something that is wrong globally.
+
+Build a **static mockup** instead - one self-contained HTML file, real numbers pasted in from a handful of queries, no framework, no live data, no interaction. It costs an hour and it removes every constraint that was keeping the design where it was. On a real build this is what surfaced a side rail replacing the top bar and a single canvas replacing eleven cards; neither was reachable by editing the running app, and both ported back cleanly afterwards because the app's render targets were stable ids.
+
+Two things make the port work: **use real numbers in the mockup** (fake data hides the widths that will actually break), and **agree the mockup before porting**, because the port is mechanical and the design decisions are not.`
     },
     {
       name: "malloy-debug",
@@ -326713,7 +327527,7 @@ Do not rely on \`body { min-height: 100vh }\` to drive the frame height. The run
     {
       name: "malloy-html-data-app-runtime",
       description: "The JavaScript that drives an in-package HTML data app - calling Publisher.query, building queries from filter state, handling results and errors. For 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 gated source, a bad given (unknown name or wrong-typed value) fails closed, so it looks like access denied rather than validation. A `#(authorize)` lock also answers 403 for a caller it simply does not admit. 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. |'
+      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 gated source, a bad given (unknown name or wrong-typed value) fails closed, so it looks like access denied rather than validation. A `#(authorize)` lock also answers 403 for a caller it simply does not admit. 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| A NEW file under `public/` 404s while the rest of the app serves | The server loaded the package **before** `public/` existed, and it is not watching. Without `--watch-env` the package is COPIED into `publisher_data/<env>/<pkg>/` at load and static files are served from that copy, so a file you add afterwards is never seen. Restart with `--watch-env <env>`, or mirror the file into the served copy. Verified by writing a probe file into the real package and getting a 404 while the copy served fine - and note the existing row below sends you looking under `public/`, which is exactly the wrong place for this one. |\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",
@@ -326753,35 +327567,37 @@ Only \`public/\` is reachable over the web, at \`/environments/<env>/packages/<p
 
 The agent orchestrates these. Each query and chart step hands off to a focused skill.
 
-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 \`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.
+1. DESIGN IT FIRST with \`skill:malloy-data-app-design\`: who opens it, the decision it serves, the archetype, the form each tile takes, and the depth plan. Skipping this is what produces an app that enumerates the model - a KPI row and a chart grid, whatever the domain - instead of one that answers a question. Hand the brief to the user before scaffolding.
+2. READ THE MODEL. 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.
+3. SCAFFOLD the package (template below).
+4. 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\`.
+5. 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.
+6. EMBED (optional) with \`skill:malloy-html-data-app-embedding\`.
+7. PREVIEW with the local authoring loop (below).
+8. VERIFY before you call it done (see "What 'done' means" below). This step is not optional.
 
-The scaffold in step 2 only proves the wiring. It is the start, not the deliverable. What you ship is a production app that meets the recipe below.
+The scaffold in step 3 only proves the wiring. It is the start, not the deliverable. What you ship is a production app that meets the recipe below.
 
 ## What "done" means (production recipe)
 
 A data app you can defend has all of these. Build to this list, not to the scaffold.
 
-- **Real names, never guessed.** Every source, view, and field name comes from the model you read in step 1. A name you derived or assumed is a bug waiting to surface as an empty tile.
+- **Real names, never guessed.** Every source, view, and field name comes from the model you read in step 2. A name you derived or assumed is a bug waiting to surface as an empty tile.
+- **A real name is not the same as a correct measure.** Using the model's declared measures is right by default, but a wrong one fails far more quietly than a wrong name: an empty tile is obvious, a plausible wrong number is not. Before a measure reaches a headline, confirm it against the raw column values (\`skill:malloy-data-app-design\` step 2 of the inventory). The case that bites is a predicate like \`!= null\` over a column whose "absent" value is a sentinel string - measured on a real build, that reported 95.6% of police cases cleared where the true figure was 16.6%, and every check in this skill still passed.
 - **DOM-only - never \`innerHTML\` with interpolated values.** Build every element with \`createElement\` + \`textContent\`; do not assign \`innerHTML\` (or \`insertAdjacentHTML\`, \`document.write\`) with any string that contains a model value. Query results render any markup they contain - an XSS vector, and blocked outright under a Trusted-Types CSP. This is a hard build rule, not a lint suggestion: an app that interpolates a model value into \`innerHTML\` is not done.
 - **Modular, not one inline blob.** Split the page into modules per \`skill:malloy-html-data-app-runtime\` (pure formatting helpers, a chart layer, your tile/query definitions as data, a thin entry point). One source of truth for each tile's model/source/view, no parallel maps that drift.
 - **Every tile handles loading, empty, and error on its own.** One failing query must not blank the page. (\`skill:malloy-html-data-app-runtime\`.)
 - **Defensible numbers.** Missing ≠ zero (omit the point, don't plot a fake 0); show the latest non-null value for "current"; guard division with \`nullif\`; convert units explicitly. (\`skill:malloy-html-data-app-runtime\`.)
 - **Visible assumptions.** When you assume something (two sources joined by month, an in-month proxy that differs from a certified definition) or a metric is incomplete, say so *in the app*: a caption, a footnote, a placeholder card with the reason. The non-technical user cannot see your reasoning; bury a caveat and you have misled them. Don't silently drop a metric you couldn't model. Show a placeholder that names what's missing and why.
-- **Looks decent.** Give it real layout, type, and color: a styled card grid with a clear hierarchy, not raw unstyled tables.
-- **Vendored libraries.** Chart and helper libraries live in \`public/\`, loaded locally (step 4).
-- **Lazy-load below the fold (once there are many tiles).** Don't fire every tile's query on load. \`reference/lazy-load.md\` is the recipe: \`IntersectionObserver\` (rootMargin ~240px) + a small concurrency cap + reserve each tile's height so lazy tiles don't reflow. Includes the verification trap - on a short/tall-default viewport all tiles intersect at once and you get a false "everything deferred" pass, so test on a deliberately small viewport.
+- **Built to the design brief, not to the model's shape.** The app matches the archetype, forms, and depth plan from step 1 (\`skill:malloy-data-app-design\`), carries a real token contract (surfaces, text ramp, semantic colors, a categorical chart palette) that the chart code reads at runtime rather than hardcoding, and puts visible weight on the two or three numbers that lead. A uniform grid of same-size cards, or a tile per view, means the brief was skipped.
+- **Vendored libraries.** Chart and helper libraries live in \`public/\`, loaded locally (step 5).
+- **Lazy-load below the fold, once the page has more than about eight query-backed tiles.** ("Many" is not decidable; that is the threshold.) Tiles sitting below the fold is *why* the technique works, not a second trigger for it - almost every real data app scrolls, so reading it as one makes the rule "always" and contradicts the count. Under that threshold, firing every tile at once is cheaper than the machinery. Don't fire every tile's query on load. \`reference/lazy-load.md\` is the recipe: \`IntersectionObserver\` (rootMargin ~240px) + a small concurrency cap + reserve each tile's height so lazy tiles don't reflow. Includes the verification trap - on a short/tall-default viewport all tiles intersect at once and you get a false "everything deferred" pass, so test on a deliberately small viewport.
 
 ### Verify before you call it done
 
 You are building for someone who cannot tell a correct dashboard from a broken one. Verification is your job, not theirs.
 
-- **Validate every query against the model before wiring it in** (step 3): confirm it compiles and that the column names match what your render code reads.
+- **Validate every query against the model before wiring it in** (step 4): confirm it compiles and that the column names match what your render code reads.
 - **Load the finished page and confirm every tile shows real numbers**: not stuck on "Loading…", not an error, not an empty state you didn't intend. In a headless browser, wait on \`load\` plus a content selector, not network idle (\`publisher.js\` holds an SSE stream open; see \`skill:malloy-html-data-app-runtime\`). Don't hand-roll this each time - \`reference/verification-harness.md\` is a copy-adaptable recipe: a mock \`sdk/publisher.js\` returning canned rows keyed by \`(model, query)\`, a \`python3 -m http.server\` webroot, and Playwright assertions (KPIs non-null, no \`.is-error\`, no stuck \`.kit-skeleton\`, a chart/table present). It also documents the false-"stuck skeleton" trap (assert after the mock's async delay, never on \`networkidle\`).
 - **Unit-test any non-trivial pure logic** (a month-join, a de-cumulation, a unit conversion). Keep that logic in DOM-free helpers so \`node --test\` can cover it, and run it.
 
@@ -326856,6 +327672,10 @@ Run a local Publisher from the directory that holds your \`publisher.config.json
 npx @malloy-publisher/server --server_root . --port 4000 --watch-env <env>
 \`\`\`
 
+**\`--watch-env\` is not optional if you are adding \`public/\` to a package that is already loaded.** Without it the server COPIES each package into \`publisher_data/<env>/<pkg>/\` at load time and serves static files from that copy, so a \`public/\` directory you create afterwards is never seen: every file in it 404s while the rest of the app serves normally. This is the most expensive mistake in this skill, because it looks like your page is broken rather than like the server is stale,.
+
+If you did not start the server (someone handed you a running one), **probe before you build**: write a throwaway file into the package's \`public/\`, request it, and see whether you get 200 or 404. If it 404s, either restart with \`--watch-env <env>\` or mirror your files into the served copy after every edit.
+
 \`--watch-env <env>\` (or \`PUBLISHER_WATCH=<env>\`) mounts that environment's local-dir packages in place (a symlink, not a copy) and watches them: editing a \`.malloy\` recompiles the package, and editing a \`public/\` file live-reloads any open page over an SSE stream. Nothing to wire in the page. The app is served at \`http://localhost:4000/environments/<env>/packages/<pkg>/index.html\`.
 
 \`publisher.config.json\` (at \`--server_root\`) declares the environment, its packages, and its connections:
@@ -326980,9 +327800,11 @@ await page.waitForFunction((n) => document.querySelectorAll(".tile .value").leng
 
 > Scaffolding to verify a finished data app end-to-end without a live warehouse. Referenced from \`SKILL.md\` ("Verify before you call it done"). You are building for someone who cannot tell a correct dashboard from a broken one; this harness is how you check, so they don't have to.
 
-The app talks to the world through exactly one seam: \`window.Publisher.query(modelPath, malloy)\`. Mock that seam and you can load the real page in a real browser with canned data, then assert on what actually rendered.
+**If you have a live Publisher serving real data, verify against that first.** It is strictly the stronger check: it exercises the real queries, the real column names and the real edge cases (empty results, nulls, a season with no data) that canned fixtures are exactly the thing to miss. Mock only what the live server cannot give you.
+
+The mock below is for when there is no live server, or when you need a specific shape on demand - an empty result, a failing query, a tile whose data does not exist yet. The app talks to the world through exactly one seam: \`window.Publisher.query(modelPath, malloy)\`. Mock that seam and you can load the real page in a real browser with canned data, then assert on what actually rendered.
 
-## 1. Mock \`sdk/publisher.js\`
+## 1. Mock \`sdk/publisher.js\` (when there is no live server)
 
 Serve a stand-in at the same root-relative path the page loads (\`/sdk/publisher.js\`). It returns canned rows keyed by \`(modelPath, query)\`, and (this is the part that bites) it reproduces the **async delay** of the real runtime, so your assertions exercise the loading→loaded transition instead of racing a synchronous stub.
 
@@ -327028,7 +327850,14 @@ server=$!
 trap 'kill "$server" 2>/dev/null; rm -rf "$webroot"' EXIT   # always tear the server down
 \`\`\`
 
-## 2. Drive it with Playwright and assert on the rendered DOM
+## 2. Drive it in a REAL browser and assert on the rendered DOM
+
+**It must be a real browser engine. jsdom cannot verify this app, and it fails in the most dangerous possible way.** jsdom does not execute \`<script type="module">\` at all, and it reports no error for it - so a run comes back with no console errors, no error tiles and no stuck skeletons, which looks like a clean pass while *none of your code ran*. That is exactly the false green this document exists to prevent, and it is worse because \`skill:malloy-html-data-app-runtime\` requires the ES-module entry point that breaks it. jsdom also lacks \`fetch\` (the query promise rejects and boot hangs), \`ResizeObserver\` (chart libraries throw, and it surfaces as your own error state), and a 2D canvas.
+
+Playwright is the example below. If it is not installed and cannot be fetched - which is common in agent sandboxes - use the CDP harness at the end of this file instead. It needs nothing but a browser you already have and a WebSocket.
+
+
+> **If your page lazy-loads (and \`SKILL.md\` says it should past about eight tiles), a whole-page "no skeletons anywhere" predicate will time out and report a failure that is not real.** Below-fold tiles are *supposed* to still be skeletons. The wait below is therefore scoped to tiles currently in the viewport, which is correct for both a lazy and a non-lazy page. The trade runs the dangerous way, so be explicit about it: **this predicate cannot fail on a tile it cannot see**, so a below-fold tile that never resolves passes silently. On a lazy page the viewport wait is necessary but **not sufficient** - the scroll-and-assert loop in \`reference/lazy-load.md\` is what actually covers the deferred tiles, and a lazy page is not verified without it.
 
 \`\`\`js
 // verify.mjs: node verify.mjs   (assumes the server above is on :4173)
@@ -327047,35 +327876,46 @@ await page.goto("http://localhost:4173/index.html", { waitUntil: "load" });
 // false "stuck skeleton" / "empty value" FAIL. "Resolved" = every tile has a
 // value and no skeleton remains. This single wait subsumes the DELAY_MS delay
 // AND the stuck-skeleton check; if it times out, a tile really is stuck.
-// NOTE: assumes a NON-lazy page, every tile loads on open. For a lazy-loaded
-// page (reference/lazy-load.md) below-fold tiles legitimately keep their
-// skeletons until scrolled in, so this wait would (correctly) time out. Test a
-// lazy page with the scroll-and-assert loop in lazy-load.md instead.
+// SCOPED TO THE VIEWPORT on purpose - see the warning above this block.
 await page.waitForFunction(() => {
-  const tiles = [...document.querySelectorAll(".tile")];
+  // Only tiles that are actually on screen are expected to have resolved. On a
+  // non-lazy page that is every tile; on a lazy page it is the ones above the
+  // fold, and the rest resolve as you scroll. Filtering here means the SAME
+  // predicate works for both, instead of timing out on the lazy page that
+  // SKILL.md tells you to build.
+  const onScreen = (el) => {
+    const r = el.getBoundingClientRect();
+    return r.bottom > 0 && r.top < innerHeight;
+  };
+  const tiles = [...document.querySelectorAll(".tile")].filter(onScreen);
   // Assert PER TILE, not global counts. \`.tile .value\` count >= tile count
   // false-FAILs a chart/table tile (it has no .value) and false-PASSes when one
   // multi-.value KPI tile inflates the total enough to mask a silently-empty
   // sibling. "Resolved" = each tile shows its OWN content: a value, a chart, a
   // table row, or its error state.
   return tiles.length > 0 &&
-    document.querySelectorAll(".kit-skeleton").length === 0 &&
+    tiles.every((t) => !t.querySelector(".kit-skeleton")) &&
     tiles.every((t) => t.querySelector(".value, canvas, table tbody tr, .is-error"));
 }, null, { timeout: 5000 });
 
 // Per tile: flag any tile that is content-empty (nothing rendered at all) or
 // whose KPI values are blank/"NaN". A global .value sweep would let a valueless
 // tile vanish; walking tiles keeps every one accountable.
-const tileReport = await page.$$eval(".tile", (tiles) =>
-  tiles.map((t, i) => {
-    const vals = [...t.querySelectorAll(".value")].map((e) => e.textContent.trim());
-    return {
-      i,
-      empty: !t.querySelector(".value, canvas, table tbody tr, .is-error"),
-      errored: !!t.querySelector(".is-error"),
-      badVals: vals.filter((v) => !v || /^(loading|nan|undefined|null)$/i.test(v)),
-    };
-  }));
+const tileReport = await page.$$eval(".tile", (all) =>
+  // Scoped to the viewport, exactly like the wait above. A whole-page sweep
+  // reports every below-fold tile as empty on a lazy page, which just moves
+  // the false failure from the wait into the assertion.
+  all
+    .filter((t) => { const r = t.getBoundingClientRect(); return r.bottom > 0 && r.top < innerHeight; })
+    .map((t, i) => {
+      const vals = [...t.querySelectorAll(".value")].map((e) => e.textContent.trim());
+      return {
+        i,
+        empty: !t.querySelector(".value, canvas, table tbody tr, .is-error"),
+        errored: !!t.querySelector(".is-error"),
+        badVals: vals.filter((v) => !v || /^(loading|nan|undefined|null)$/i.test(v)),
+      };
+    }));
 
 const problems = [];
 const emptyTiles = tileReport.filter((t) => t.empty);
@@ -327088,9 +327928,114 @@ if (errors.length) problems.push(\`console/page errors: \${errors.join(" | ")}\`
 
 await browser.close();
 if (problems.length) { console.error("FAIL:\\n- " + problems.join("\\n- ")); process.exit(1); }
-console.log(\`OK: all \${tileReport.length} tiles rendered content\`);
+console.log(\`OK: all \${tileReport.length} on-screen tiles rendered content\`);
 \`\`\`
 
+## 3. When Playwright is not available: drive Chrome over CDP
+
+Agent sandboxes frequently have a browser but no Playwright and no way to install one. The DevTools Protocol needs only a WebSocket, and **Node 22+ has one built in**, so this path installs nothing. The snippet below was run end to end against a real app before it was written down.
+
+\`\`\`sh
+# Launch once. Pick a port nobody else is on, and your own profile directory so
+# you never collide with a browser the user is already running.
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \\
+  --headless=new --remote-debugging-port=9333 --no-first-run \\
+  --user-data-dir=/tmp/verify-profile about:blank &
+\`\`\`
+
+\`\`\`js
+// verify.mjs - node verify.mjs <app-url> [port]. No dependencies on Node 22+.
+const APP_URL = process.argv[2] ?? "http://localhost:4173/index.html";
+const PORT = process.argv[3] ?? 9333;
+
+const targets = await (await fetch(\`http://localhost:\${PORT}/json/list\`)).json();
+const page = targets.find((t) => t.type === "page");
+const sock = new WebSocket(page.webSocketDebuggerUrl);
+
+let id = 0;
+const pending = new Map();
+const errors = [];
+const send = (method, params = {}) =>
+  new Promise((res, rej) => { const i = ++id; pending.set(i, { res, rej });
+    sock.send(JSON.stringify({ id: i, method, params })); });
+
+sock.addEventListener("message", (ev) => {
+  const msg = JSON.parse(ev.data);
+  if (msg.id && pending.has(msg.id)) {
+    const { res, rej } = pending.get(msg.id);
+    pending.delete(msg.id);
+    // REJECT on a protocol error. Resolving with undefined turns a mistyped
+    // method into a predicate that is merely false, and then waitFor burns its
+    // whole timeout and blames the page.
+    if (msg.error) rej(new Error(\`CDP: \${msg.error.message}\`));
+    else res(msg.result);
+    return;
+  }
+  if (msg.method === "Runtime.exceptionThrown") errors.push(msg.params?.exceptionDetails?.text ?? "exception");
+  if (msg.method === "Runtime.consoleAPICalled" && msg.params.type === "error") errors.push("console.error");
+});
+
+await new Promise((r) => sock.addEventListener("open", r, { once: true }));
+await send("Page.enable");
+await send("Runtime.enable");
+await send("Emulation.setDeviceMetricsOverride",
+  { width: 1512, height: 982, deviceScaleFactor: 2, mobile: false });
+await send("Page.navigate", { url: APP_URL });
+
+const evaluate = async (expr) =>
+  (await send("Runtime.evaluate", { expression: expr, returnByValue: true, awaitPromise: true }))
+    .result?.value;
+
+// There is no waitForFunction here; poll your own predicate.
+async function waitFor(expr, timeoutMs = 30000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await evaluate(expr)) return true;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  throw new Error(\`timed out waiting for: \${expr}\`);
+}
+
+const ONSCREEN = \`(el) => { const r = el.getBoundingClientRect(); return r.bottom > 0 && r.top < innerHeight; }\`;
+
+await waitFor(\`document.querySelectorAll('.tile').length > 0
+  && [...document.querySelectorAll('.tile')].filter(\${ONSCREEN})
+       .every((t) => t.querySelector('.value, canvas, table tbody tr, .is-error'))\`);
+
+console.log(await evaluate(\`(() => {
+  const onScreen = \${ONSCREEN};
+  const tiles = [...document.querySelectorAll('.tile')].filter(onScreen);
+  // A canvas reports width 300 untouched, so "has a width" proves nothing.
+  // Read the pixels: a blank chart is the failure this is looking for.
+  const canvases = [...document.querySelectorAll('canvas')].filter(onScreen);
+  const painted = canvases.filter((c) => {
+    try { return c.getContext('2d').getImageData(0, 0, c.width, c.height).data.some((v) => v !== 0); }
+    catch { return false; }
+  }).length;
+  return JSON.stringify({
+    onScreenTiles: tiles.length,
+    errorTiles: tiles.filter((t) => t.querySelector('.is-error')).length,
+    stuck: tiles.filter((t) => t.querySelector('.kit-skeleton')).length,
+    // Word boundaries on every alternation, or legitimate copy containing
+    // "undefined" trips the check.
+    badValues: /\\\\bNaN\\\\b|\\\\bundefined\\\\b|\\\\bInfinity\\\\b/.test(document.body.innerText),
+    onScreenCanvases: canvases.length,
+    canvasesPainted: painted,
+  });
+})()\`));
+console.log("runtime errors:", errors.length ? errors : "none");
+
+sock.close();
+\`\`\`
+
+Everything here is scoped to the viewport, for the reason in section 2: a whole-page sweep hard-fails a lazy page. Scroll and re-run the report to cover the deferred tiles.
+
+Three things bite on this path, and each makes a correct page look broken:
+
+- **\`captureBeyondViewport: true\` rasterises canvases at the wrong scale.** A full-page capture squashes every chart into a corner and you will "fix" a bug that does not exist. Use viewport-only \`Page.captureScreenshot\` and scroll between shots.
+- **Switch themes by clicking the app's own control**, not by setting an attribute on the root. Setting the attribute skips whatever re-resolves chart colours, so the charts keep their construction-time palette and you get a screenshot that looks like a real theming bug.
+- **Kill the browser when you finish** and use a port nobody else is on. A stray headless Chrome holding a profile directory is a confusing thing to debug later.
+
 ## Gotchas (each cost a real debugging cycle)
 
 - **Wait out the mock's async delay before asserting.** Asserting immediately after \`load\` reads the skeleton, not the resolved tile, and reports a false "stuck skeleton." Wait until every tile shows its own resolved content (the per-tile \`waitForFunction\` above), never on \`networkidle\`, because \`publisher.js\` keeps the live-reload SSE stream open, so the page never reaches network idle.
@@ -328600,7 +329545,7 @@ Steps to follow when the user asks a question:
     {
       name: "malloy-notebooks",
       description: 'Create Malloy notebooks (.malloynb) for interactive dashboards and data stories. Use when user asks to "create a notebook", "make a dashboard notebook", "write a malloynb", "data story", or needs to build reports/visualizations.',
-      body: "# Malloy Notebooks\n\nFiles: `.malloynb`\n\n## Scope: when to use this skill vs `skill:malloy-analysis-report`\n\nThis skill is for **curated `.malloynb` notebooks**. Interactive parameter widgets render automatically from the `given:` declarations on the models it imports (or, in older models, from deprecated `#(filter)` annotations). The notebook itself never declares parameters or filters.\n\nFor **ad-hoc reports** generated by an analysis agent, combining queries into a quick narrative artifact, use `skill:malloy-analysis-report` instead. Ad-hoc reports also inherit whatever the source declares.\n\n## Important Limitations\n\n**Compile errors in `.malloynb` files are NOT shown in the IDE linter.** You will only see errors when cells are executed. Be extra careful with syntax and test queries in the model first if unsure.\n\n## Multiple Models & Cross-Model Joins\n\nA published `.malloynb` runs each `run:` cell against the whole notebook, which compiles with **all** its `import`s in scope. So a notebook can import several `.malloy` models, and a single cell can reference, and **join**, sources from different imported files. Import each model you need in a setup cell at the top; no \"re-export\" wrapper model is required.\n\n**When the package root holds an `index.malloy`, cells read only what it exports.** A cell over a source `index.malloy` does not export answers 404, even when the notebook imports that source's file. A source an earlier cell derives from an exported one (`source: mine is customers extend { ... }`) still works. A cell's own source over a raw table (`duckdb.table(...)`) is refused. To use a source in a notebook, add it to the `export { ... }` in `index.malloy`. A package with no `index.malloy` and no legacy `explores` has no such limit.\n\n```\n>>>malloy\nimport \"flights.malloy\"\nimport \"carriers.malloy\"\n\n>>>malloy\n// joins `flights` (from flights.malloy) to `carriers` (from carriers.malloy)\nrun: flights extend {\n  join_one: carriers on carrier = carriers.code\n} -> {\n  group_by: carriers.nickname\n  aggregate: flight_count\n}\n```\n\nTwo things still hold:\n\n- **Imports are notebook-wide, declare them at the top, never inside a `run:` cell.** A cell's query runs as a *restricted query* against the already-compiled notebook, so its imports must already be in place. You can't `import` a model inside a query cell to scope it there; an in-query import is rejected (`file imports are not permitted in a restricted query`).\n- **Compile errors surface only at publish/render, not in the IDE linter** (see above). Verify a multi-model notebook by publishing to a scratch environment and loading it, rather than relying only on single-model query checks.\n\n## No Data-Specific Insights in Markdown\n\n**Notebooks must NOT contain findings about current data values.** Data refreshes will make these stale. Use markdown for framing questions and structural narrative, not for stating results.\n\n```\n>>>markdown\n## WRONG: will become stale when data refreshes\nRevenue spiked 23% in March. Electronics drove 60% of the spike.\n\n>>>markdown\n## RIGHT: frames the question, lets the query answer it\nHow is revenue trending? Which categories are driving changes?\n```\n\n## Cell Syntax\n\nCells delimited by `>>>markdown` or `>>>malloy`:\n\n```\n>>>markdown\n# Sales Analysis\nOverview of sales trends.\n\n>>>malloy\nimport \"sales_model.malloy\"\n\n>>>markdown\n## Summary\n\n>>>malloy\nrun: orders -> summary\n\n>>>markdown\n## Monthly Trend\n\n>>>malloy\n# line_chart\nrun: orders -> by_month\n```\n\n**NEVER create `>>>malloysql` cells.** Only use `>>>malloy` and `>>>markdown`.\n\n## Interactive Parameters (`given:`)\n\nInteractive parameters are common and important. Add them to most notebooks. **Use `given:` for anything new.** The older `#(filter)` mechanism still works and is documented below, but it is deprecated: do not reach for it just because you saw it in an existing model.\n\nA notebook's parameter surface comes from the `given:` declarations on the models it imports, not from anything declared in the `.malloynb` itself. When an imported model declares givens, Publisher's notebook UI automatically renders a Parameters panel above the notebook: declared givens become parameter inputs, the values a user sets are forwarded to Malloy's runtime, and every cell re-executes against the model with those values applied.\n\nThe widget for each parameter follows the given's declared Malloy type (`string`, `string[]`, `number`, `boolean`, `date`/`timestamp`, `filter<T>`); see `docs/givens.md` for the full type table. A `#(description=\"...\")` annotation on the given renders as helper text under its input.\n\n```malloy\n##! experimental.givens\n\n#(description=\"Two-letter IATA carrier code to spotlight\")\ngiven: carrier :: string is 'WN'\n\nsource: spotlight_carrier is duckdb.table('data/carriers.parquet') extend {\n  view: by_name is {\n    where: code = $carrier\n    select: code, name, nickname\n    limit: 1\n  }\n}\n```\n\nDeclare givens at the **top of the model file**, before the source that uses them, not in the notebook. `malloy-model` § Access Control covers the syntax and the `#(authorize)`/`#(access_filter)` gating story built on top of givens.\n\n## Legacy: `#(filter)` annotations\n\n> **Deprecated. Read this before copying the example below.** `#(filter)` is server-side `where:` injection, superseded by native Malloy `given:` above. Do NOT add new `#(filter)` annotations; declare runtime parameters as givens instead. `docs/givens.md` has the migration recipes. What follows is here so you can read and maintain models that already use it.\n\nFilters are declared **once, on the model's source**. The notebook itself does not declare or list filters. Publisher reads the source's filter metadata and renders the widgets above the notebook automatically, then injects `where:` clauses server-side on every cell.\n\nDeclarations live in the `.malloy` model file, above the source, using key=value parameters. The full reference (syntax, filter types, `required` / `implicit` flags) lives with the `#(filter)` guidance in the `malloy-model` skill's Parameterizable Filters section. Short example:\n\n```malloy\n#(filter) name=Manufacturer dimension=Manufacturer type=in\n#(filter) name=OrderStatus dimension=order_status type=in\n#(filter) name=Recall_After dimension=\"Report Received Date\" type=greater_than\n#(filter) name=Recall_Before dimension=\"Report Received Date\" type=less_than\nsource: recalls is duckdb.table('data/auto_recalls.csv') extend {\n  measure:\n    recall_count is count()\n}\n```\n\n`#(filter)` lines go **above** the `source:` declaration and reference dimensions by name (use `dimension=`). `name` defaults to the dimension name and only needs to be set when two filters target the same dimension (e.g. a date range). `type` is the comparator: `equal`, `in`, `like`, `greater_than`, `less_than`.\n\n## Notebook Style: Iterative Analysis (Default)\n\n**Build a story.** Each query should reveal something that motivates the next query. Start broad, then drill into what's interesting. Frame questions in markdown, let queries answer them.\n\n**Pattern:** Question, Query, Next Question, Drill\n\n```\n>>>markdown\n## How is revenue trending?\n\n>>>malloy\n# line_chart\nrun: orders -> { group_by: order_month; aggregate: revenue }\n\n>>>markdown\n## What's driving the biggest changes?\n\n>>>malloy\n# bar_chart\nrun: orders -> { group_by: category; aggregate: revenue; order_by: revenue desc; limit: 10 }\n\n>>>markdown\n## How does the top category break down?\n\n>>>malloy\nrun: orders -> { aggregate: order_count, avg_order_value; where: category = 'Electronics' }\n```\n\n**When to use other styles:**\n- **Dashboard with filters:** User asks for \"filterable dashboard\". Show key KPIs and breakdowns with interactive filters.\n- **EDA/summary:** User asks for \"overview\". Run views like `summary`, `by_month`, `by_category` in sequence.\n\n## View Refinement\n\nTo add `limit`, `where`, or other options to an existing view, use `+`:\n\n```malloy\nrun: source -> my_view + { limit: 15 }\nrun: source -> my_view + { where: status = 'active', limit: 10 }\n```\n\n## Template\n\n```\n>>>markdown\n# [Title]\n[Framing question: what are we trying to understand?]\n\n>>>malloy\nimport \"model.malloy\"\n\n>>>markdown\n## [First question: start broad]\n\n>>>malloy\nrun: main_source -> [broad query]\n\n>>>markdown\n## [Next question: motivated by what the first query reveals]\n\n>>>malloy\nrun: main_source -> [drill into finding]\n\n>>>markdown\n## [Deeper question]\n\n>>>malloy\nrun: main_source -> [further breakdown]\n```\n\n## Common Mistakes\n\n| Mistake | Fix |\n|---------|-----|\n| `view_name { limit: 10 }` | Use `+`: `view_name + { limit: 10 }` |\n| `# currency` on non-money | Only use `# currency` for monetary values |\n| `#(filter) {\"type\": \"Star\"}` (JSON-blob form, on a dimension) | Unsupported legacy syntax. `#(filter)` goes **above the source** with key=value parameters (`name=`, `dimension=`, `type=`). See the `malloy-model` skill's Parameterizable Filters section. |\n| `##(filters) [...]` annotation in the notebook | Unsupported. The notebook does not declare or list filters. Publisher renders widgets automatically from the source's `#(filter)` annotations. |\n| Creating MalloySQL cells | **NEVER use `>>>malloysql`**, only `>>>malloy` and `>>>markdown` |\n| Data-specific insights in markdown | Don't write \"Revenue grew 23%.\" Frame questions instead. Data refreshes will make findings stale. |\n| `import` inside a `run:` cell (to scope a model to that cell) | Imports are notebook-wide, put them in a setup cell at the top. An in-query import is rejected: `file imports are not permitted in a restricted query` (see Multiple Models & Cross-Model Joins). |\n| Cross-model join inside a single ad-hoc report cell | A `skill:malloy-analysis-report` cell renders against a single model, so a cross-model join there won't render. Build a published `.malloynb` (which runs against the whole notebook) for a cross-model join. |\n\n## Best Practices\n\n1. Start with markdown framing the question\n2. Import each model the notebook needs in a setup cell at the top, cells can reference and join sources across all imports (see Multiple Models & Cross-Model Joins); verify a multi-model notebook by publishing to a scratch environment\n3. Each query should follow from what the previous one could reveal\n4. One query per cell\n5. Charts render only the FIRST aggregate\n6. Add interactive filters to most notebooks by declaring `#(filter)` on the model's source (see Interactive Filters), or prefer `given:` runtime parameters for new models (see Runtime Parameters)\n7. Never include data-specific findings in markdown. Frame questions, let queries answer\n\n## Done\n\nStep complete. Output: `.malloynb` notebook file."
+      body: "# Malloy Notebooks\n\nFiles: `.malloynb`\n\n## Scope: when to use this skill vs `skill:malloy-analysis-report`\n\nThis skill is for **curated `.malloynb` notebooks**. Interactive parameter widgets render automatically from the `given:` declarations on the models it imports (or, in older models, from deprecated `#(filter)` annotations). The notebook itself never declares parameters or filters.\n\nFor **ad-hoc reports** generated by an analysis agent, combining queries into a quick narrative artifact, use `skill:malloy-analysis-report` instead. Ad-hoc reports also inherit whatever the source declares.\n\n## Important Limitations\n\n**Compile errors in `.malloynb` files are NOT shown in the IDE linter.** You will only see errors when cells are executed. Be extra careful with syntax and test queries in the model first if unsure.\n\n## Multiple Models & Cross-Model Joins\n\nA published `.malloynb` runs each `run:` cell against the whole notebook, which compiles with **all** its `import`s in scope. So a notebook can import several `.malloy` models, and a single cell can reference, and **join**, sources from different imported files. Import each model you need in a setup cell at the top; no \"re-export\" wrapper model is required.\n\n**When the package root holds an `index.malloy`, cells read only what it exports.** A cell over a source `index.malloy` does not export answers 404, even when the notebook imports that source's file. A source an earlier cell derives from an exported one (`source: mine is customers extend { ... }`) still works. A cell's own source over a raw table (`duckdb.table(...)`) is refused. To use a source in a notebook, add it to the `export { ... }` in `index.malloy`. A package with no `index.malloy` and no legacy `explores` has no such limit.\n\n```\n>>>malloy\nimport \"flights.malloy\"\nimport \"carriers.malloy\"\n\n>>>malloy\n// joins `flights` (from flights.malloy) to `carriers` (from carriers.malloy)\nrun: flights extend {\n  join_one: carriers on carrier = carriers.code\n} -> {\n  group_by: carriers.nickname\n  aggregate: flight_count\n}\n```\n\nTwo things still hold:\n\n- **Imports are notebook-wide, declare them at the top, never inside a `run:` cell.** A cell's query runs as a *restricted query* against the already-compiled notebook, so its imports must already be in place. You can't `import` a model inside a query cell to scope it there; an in-query import is rejected (`file imports are not permitted in a restricted query`).\n- **Compile errors surface only at publish/render, not in the IDE linter** (see above). Verify a multi-model notebook by publishing to a scratch environment and loading it, rather than relying only on single-model query checks.\n\n## No Data-Specific Insights in Markdown\n\n**Notebooks must NOT contain findings about current data values.** Data refreshes will make these stale. Use markdown for framing questions and structural narrative, not for stating results.\n\n```\n>>>markdown\n## WRONG: will become stale when data refreshes\nRevenue spiked 23% in March. Electronics drove 60% of the spike.\n\n>>>markdown\n## RIGHT: frames the question, lets the query answer it\nHow is revenue trending? Which categories are driving changes?\n```\n\n## Cell Syntax\n\nCells delimited by `>>>markdown` or `>>>malloy`:\n\n```\n>>>markdown\n# Sales Analysis\nOverview of sales trends.\n\n>>>malloy\nimport \"sales_model.malloy\"\n\n>>>markdown\n## Summary\n\n>>>malloy\nrun: orders -> summary\n\n>>>markdown\n## Monthly Trend\n\n>>>malloy\n# line_chart\nrun: orders -> by_month\n```\n\n**NEVER create `>>>malloysql` cells.** Only use `>>>malloy` and `>>>markdown`.\n\n## Interactive Parameters (`given:`)\n\nInteractive parameters are common and important. Add them to most notebooks. **Use `given:` for anything new.** The older `#(filter)` mechanism still works and is documented below, but it is deprecated: do not reach for it just because you saw it in an existing model.\n\nA notebook's parameter surface comes from the `given:` declarations on the models it imports, not from anything declared in the `.malloynb` itself. When an imported model declares givens, Publisher's notebook UI automatically renders a Parameters panel above the notebook: declared givens become parameter inputs, the values a user sets are forwarded to Malloy's runtime, and every cell re-executes against the model with those values applied. A cell that runs before the notebook's `import` of a given ignores that given's value.\n\nThe widget for each parameter follows the given's declared Malloy type (`string`, `string[]`, `number`, `boolean`, `date`/`timestamp`, `filter<T>`); see `docs/givens.md` for the full type table. A `#(description=\"...\")` annotation on the given renders as helper text under its input.\n\n```malloy\n##! experimental.givens\n\n#(description=\"Two-letter IATA carrier code to spotlight\")\ngiven: carrier :: string is 'WN'\n\nsource: spotlight_carrier is duckdb.table('data/carriers.parquet') extend {\n  view: by_name is {\n    where: code = $carrier\n    select: code, name, nickname\n    limit: 1\n  }\n}\n```\n\nDeclare givens at the **top of the model file**, before the source that uses them, not in the notebook. `malloy-model` § Access Control covers the syntax and the `#(authorize)`/`#(access_filter)` gating story built on top of givens.\n\n## Legacy: `#(filter)` annotations\n\n> **Deprecated. Read this before copying the example below.** `#(filter)` is server-side `where:` injection, superseded by native Malloy `given:` above. Do NOT add new `#(filter)` annotations; declare runtime parameters as givens instead. `docs/givens.md` has the migration recipes. What follows is here so you can read and maintain models that already use it.\n\nFilters are declared **once, on the model's source**. The notebook itself does not declare or list filters. Publisher reads the source's filter metadata and renders the widgets above the notebook automatically, then injects `where:` clauses server-side on every cell.\n\nDeclarations live in the `.malloy` model file, above the source, using key=value parameters. The full reference (syntax, filter types, `required` / `implicit` flags) lives with the `#(filter)` guidance in the `malloy-model` skill's Parameterizable Filters section. Short example:\n\n```malloy\n#(filter) name=Manufacturer dimension=Manufacturer type=in\n#(filter) name=OrderStatus dimension=order_status type=in\n#(filter) name=Recall_After dimension=\"Report Received Date\" type=greater_than\n#(filter) name=Recall_Before dimension=\"Report Received Date\" type=less_than\nsource: recalls is duckdb.table('data/auto_recalls.csv') extend {\n  measure:\n    recall_count is count()\n}\n```\n\n`#(filter)` lines go **above** the `source:` declaration and reference dimensions by name (use `dimension=`). `name` defaults to the dimension name and only needs to be set when two filters target the same dimension (e.g. a date range). `type` is the comparator: `equal`, `in`, `like`, `greater_than`, `less_than`.\n\n## Notebook Style: Iterative Analysis (Default)\n\n**Build a story.** Each query should reveal something that motivates the next query. Start broad, then drill into what's interesting. Frame questions in markdown, let queries answer them.\n\n**Pattern:** Question, Query, Next Question, Drill\n\n```\n>>>markdown\n## How is revenue trending?\n\n>>>malloy\n# line_chart\nrun: orders -> { group_by: order_month; aggregate: revenue }\n\n>>>markdown\n## What's driving the biggest changes?\n\n>>>malloy\n# bar_chart\nrun: orders -> { group_by: category; aggregate: revenue; order_by: revenue desc; limit: 10 }\n\n>>>markdown\n## How does the top category break down?\n\n>>>malloy\nrun: orders -> { aggregate: order_count, avg_order_value; where: category = 'Electronics' }\n```\n\n**When to use other styles:**\n- **Dashboard with filters:** User asks for \"filterable dashboard\". Show key KPIs and breakdowns with interactive filters.\n- **EDA/summary:** User asks for \"overview\". Run views like `summary`, `by_month`, `by_category` in sequence.\n\n## View Refinement\n\nTo add `limit`, `where`, or other options to an existing view, use `+`:\n\n```malloy\nrun: source -> my_view + { limit: 15 }\nrun: source -> my_view + { where: status = 'active', limit: 10 }\n```\n\n## Template\n\n```\n>>>markdown\n# [Title]\n[Framing question: what are we trying to understand?]\n\n>>>malloy\nimport \"model.malloy\"\n\n>>>markdown\n## [First question: start broad]\n\n>>>malloy\nrun: main_source -> [broad query]\n\n>>>markdown\n## [Next question: motivated by what the first query reveals]\n\n>>>malloy\nrun: main_source -> [drill into finding]\n\n>>>markdown\n## [Deeper question]\n\n>>>malloy\nrun: main_source -> [further breakdown]\n```\n\n## Common Mistakes\n\n| Mistake | Fix |\n|---------|-----|\n| `view_name { limit: 10 }` | Use `+`: `view_name + { limit: 10 }` |\n| `# currency` on non-money | Only use `# currency` for monetary values |\n| `#(filter) {\"type\": \"Star\"}` (JSON-blob form, on a dimension) | Unsupported legacy syntax. `#(filter)` goes **above the source** with key=value parameters (`name=`, `dimension=`, `type=`). See the `malloy-model` skill's Parameterizable Filters section. |\n| `##(filters) [...]` annotation in the notebook | Unsupported. The notebook does not declare or list filters. Publisher renders widgets automatically from the source's `#(filter)` annotations. |\n| Creating MalloySQL cells | **NEVER use `>>>malloysql`**, only `>>>malloy` and `>>>markdown` |\n| Data-specific insights in markdown | Don't write \"Revenue grew 23%.\" Frame questions instead. Data refreshes will make findings stale. |\n| `import` inside a `run:` cell (to scope a model to that cell) | Imports are notebook-wide, put them in a setup cell at the top. An in-query import is rejected: `file imports are not permitted in a restricted query` (see Multiple Models & Cross-Model Joins). |\n| Cross-model join inside a single ad-hoc report cell | A `skill:malloy-analysis-report` cell renders against a single model, so a cross-model join there won't render. Build a published `.malloynb` (which runs against the whole notebook) for a cross-model join. |\n\n## Best Practices\n\n1. Start with markdown framing the question\n2. Import each model the notebook needs in a setup cell at the top, cells can reference and join sources across all imports (see Multiple Models & Cross-Model Joins); verify a multi-model notebook by publishing to a scratch environment\n3. Each query should follow from what the previous one could reveal\n4. One query per cell\n5. Charts render only the FIRST aggregate\n6. Add interactive filters to most notebooks by declaring `#(filter)` on the model's source (see Interactive Filters), or prefer `given:` runtime parameters for new models (see Runtime Parameters)\n7. Never include data-specific findings in markdown. Frame questions, let queries answer\n\n## Done\n\nStep complete. Output: `.malloynb` notebook file."
     },
     {
       name: "malloy-patterns",
@@ -328931,7 +329876,7 @@ having: count() > 20
 Wrong: \`group_by: total_sales\` (where \`total_sales\` is \`sum(price)\`)
 Right: \`group_by: category; aggregate: total_sales\`
 
-**Scalar functions are not aggregates.** \`concat()\`, \`substring()\`, arithmetic on raw fields, etc. belong in \`group_by:\` or \`select:\`, never \`aggregate:\`.
+**Scalar functions are not aggregates.** \`concat()\`, \`substr()\`, arithmetic on raw fields, etc. belong in \`group_by:\` or \`select:\`, never \`aggregate:\`.
 
 Wrong: \`aggregate: full_name is concat(first_name, ' ', last_name)\`
 Right: \`group_by: full_name is concat(first_name, ' ', last_name)\`
@@ -329014,6 +329959,10 @@ Read the error against the tables above and below. Most failures match a known p
 |---|---|
 | \`Cannot compare a timestamp to a number\` | Comparing \`date.year\` to an integer. Use \`date >= @2020-01-01\` instead. |
 | \`no viable alternative at input '<word>'\` | Often a \`;\` between fields within one clause - fields under one \`aggregate:\`/\`group_by:\` are comma- or newline-separated (the error points at the field right after the \`;\`). |
+| \`unexpected '<field>', expected 'not' or 'null'\` | A **reserved word used as a name**, in a multi-line \`aggregate:\` / \`group_by:\` list. \`second\`, \`minute\`, \`hour\`, \`day\`, \`week\`, \`month\`, \`quarter\`, \`year\` are reserved. On its own line the compiler says so plainly (\`'second' is a reserved word, so to use it as a name you must quote it\`), but as a later entry in a multi-line list the parser has already committed, and the error points at the NEXT field instead - so you read it as a problem with the line below. Rename the field or backtick it. Verified against the compiler both ways. |
+| \`'logical operator' Can't use type <string\\|date\\|...>\` | **Any \`?\` apply combined with \`and\` needs parentheses**, not just the alternation form. \`where: t ? 'a' | 'b' and flag\` swallows \`and flag\` into the alternation list, and \`where: d ? @2015 and x = 'y'\` fails the same way with \`Can't use type date\`. Wrap the apply: \`where: (d ? @2015) and x = 'y'\`. The error names the *type on the left of the apply*, so it points at a clause that is perfectly fine and tells you nothing about the missing parentheses; on a date column it can also surface a spurious second error about \`!= null\` on an unrelated line. |
+| \`Circular reference to '<name>' in definition\` | A **measure aliased to its own name** (\`aggregate: games is games\`), which compiles fine until a \`having:\` references it. Alias to a different name, or drop the alias entirely. |
+| \`Unknown function '<name>'. Use '<name>!(...)' to call a SQL function directly.\` | The function does not exist in Malloy (\`substring\` is \`substr\`; there is no \`median\`). **In an ad-hoc query the suggested fix is a dead end**: a query sent to a server is compiled in restricted mode, so \`median!(...)\` then fails with "direct SQL function calls are not permitted" and following the error message costs two round trips. A saved model file is not compiled that way, so the same call is allowed there and fails only on its own merits. Use the Malloy spelling, or express it another way (an ordered \`limit\` for a median-like value); reach for \`!(...)\` only in a model file, and only knowing it pins you to one dialect. |
 | \`'<field_name>' is not defined\` | Field doesn't exist in the source. Re-check against the model definition; you may have stripped a join prefix. |
 | \`field is a bar chart, but is not a repeated record\` | Chart annotation placed inside \`{ }\`. Move \`# bar_chart\` above \`run:\` / \`view:\` / \`nest:\`. |
 | \`Parser enountered unexpected statement\` | Spelled that way by the compiler. Most often a chart annotation left as the last line inside \`{ }\` - move it above \`run:\`. Also syntax Malloy doesn't allow in that position (e.g., \`pick\` inside a nested view). |