@malloy-publisher/skills 0.1.40 → 0.1.42

package/package.json

@@ -1,7 +1,7 @@
 {
    "name": "@malloy-publisher/skills",
    "description": "Agent skills for Malloy and the Malloy Publisher",
-   "version": "0.1.40",
+   "version": "0.1.42",
    "license": "MIT",
    "type": "module",
    "main": "dist/index.js",

package/skills/eval-answer/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eval-answer
 description: 'Score one analytical answer against a verified golden, and score which of the entities the golden depends on retrieval delivered to the answerer. Run the contamination checklist, re-execute the submitted query yourself, then spawn a judge subagent per skill:eval-judge. Append attempt, tool_call, score, and retrieval_score events to the file ledger (reference/ledger-schema.md). Never explain the failure (eval-diagnose) or edit the model (eval-improve). Use when asked whether an answer was correct, to score a run, or to baseline a model.'
-version: 0.1.40
+version: 0.1.42
 ---
 
 # Evaluate One Answer

package/skills/eval-diagnose/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eval-diagnose
 description: 'Diagnose why a scored answer failed and who owns the fix, then cluster the failures by shared root cause. Walk dataset, agent-call, get_context/model, get_context/retrieval, construction, then model-definition. Append issue events to the file ledger, linked by traceId, one per cluster. Use after eval-answer, when triaging a run, or before changing a model. Does not edit the model (eval-improve).'
-version: 0.1.40
+version: 0.1.42
 ---
 
 # Diagnose One Answer
@@ -282,7 +282,7 @@ with both queries. Otherwise it is still `NOT-RETURNED` / `LOW-RANK`.
 Use when the entity was found and used, and the definition or the data behind it
 is wrong (bad grain, wrong join key, inverted filter). Owner: model. A doc whose
 factual claim the data contradicts (a population statement, a grain claim) is
-also model-definition: the SQL may be right while the stated contract is false,
+also model-definition: the field may compute correctly while its doc is false,
 and an agent that trusts the doc answers wrongly without ever failing a query.
 Probe the claim before writing the issue.
 

package/skills/eval-import/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eval-import
 description: 'Turn a list of questions into an eval set, whatever shape it arrived in: a JSONL a customer sent, a CSV, a spreadsheet export, a markdown doc, an email thread, or a pull from production logs. Classify each item by what came WITH the question (a query, a number, prose criteria, or nothing), write cases.jsonl and set.json per reference/case-format.md, keep the file as it arrived, and seal each question so a later edit is detectable. Never marks a value-bearing golden verified and never invents a question. Use when questions arrive from outside and need to become a set, or before the first run against a set nobody here authored.'
-version: 0.1.40
+version: 0.1.42
 ---
 
 # Import questions into an eval set

package/skills/eval-import/reference/case-format.md

@@ -60,7 +60,7 @@ trusting a name that looks familiar, and write down the mapping you used in
 |---|---|---|
 | `prompt`, `query`, `input`, `nl_question` | the question | `query` is the trap: in half of these it is the SQL or Malloy they ran, not the question |
 | `answer`, `expected`, `output`, `ground_truth` | a golden value, prose, or both mixed in one string | a paragraph under `answer` is criteria, not a value. Classify it, do not store it as a number |
-| `sql`, `malloy`, `gold_query` | their derivation | run it (`SKILL.md` step 3). This is the field that upgrades a typed number into something checkable |
+| `sql`, `malloy`, `gold_query` | their derivation | Malloy: run it (`SKILL.md` step 3). SQL: keep it as evidence of how they got the number, but do not run it; derive the number in Malloy over the truth package instead. Either way, this is the field that upgrades a typed number into something checkable |
 | `criteria`, `rubric`, `assertions`, `must_include` | prose criteria | apply the query test in `SKILL.md` step 4 to EACH one, not to the field |
 | `id`, `case_id`, `uuid` | their id | keep it, prefixed. Two sets from one customer collide otherwise |
 | `difficulty`, `category`, `tags` | their own labels | keep as-is on the case for slicing. Never let one become `split` |

package/skills/eval-improve/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eval-improve
 description: 'Make the smallest safe edit that closes a diagnosed gap the model repo owns: a Malloy model edit, or a package skill under skills/. Every factual claim carries a probe receipt. Use after eval-diagnose, or when asked to fix a model so an agent can discover the right answer. Never accepts its own edit; the acceptance check belongs to eval-loop. Does not decide whether an answer was wrong (eval-answer) or why (eval-diagnose).'
-version: 0.1.40
+version: 0.1.42
 ---
 
 # Improve the Model
@@ -68,7 +68,7 @@ data with no question in front of them?* Reject:
 
 - a field that hard-codes this question's filter and serves no other question
 - this question's text, qid, or expected numbers in a doc, comment, or name
-- a join copied from gold SQL that you have not probed as a real relationship
+- a join copied from a golden's query that you have not probed as a real relationship
 
 The golden is a hypothesis source. The data is still the verifier.
 
@@ -77,12 +77,16 @@ The golden is a hypothesis source. The data is still the verifier.
 Every structural claim needs a query you ran: join key, primary key, filter
 value existence, snapshot assumption, value space, cardinality.
 
-```sql
-SELECT COUNT(*), COUNT(DISTINCT col) FROM t;
-SELECT a.k, COUNT(*) FROM a JOIN b ON … GROUP BY 1 ORDER BY 2 DESC;
-SELECT col, COUNT(*) FROM t GROUP BY 1 ORDER BY 2 DESC LIMIT 5;
+```malloy
+run: t -> { aggregate: row_count is count(), distinct_keys is count(col) }
+run: b -> { group_by: k; aggregate: n is count(); order_by: n desc; limit: 5 }
+run: t -> { group_by: col; aggregate: n is count(); order_by: n desc; limit: 5 }
 ```
 
+Run probes in Malloy, against the raw tables (the truth package, or a bare
+`connection.table()` source), never as SQL. The second line is the join probe:
+any `n` above 1 means `k` is not a key on `b`, so a `join_one` on it fans out.
+
 A false `primary_key` compiles and silently corrupts every aggregate. Of one
 pilot's 11 accepted edits, 4 of 5 wrong ones died to a single
 `COUNT(*)` vs `COUNT(DISTINCT …)` probe that was never run.

package/skills/eval-judge/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eval-judge
 description: 'Decide whether ONE answer matches its golden, and say whether you believe the golden. Read this before emitting any verdict. Covers containment, column pairing, near_match, refusals, and the gold_status judgement. Use when scoring an attempt in an evaluation run; never to conduct a run (eval-loop), diagnose a failure (eval-diagnose) or edit a model (eval-improve).'
-version: 0.1.40
+version: 0.1.42
 ---
 
 # The judge
@@ -135,7 +135,7 @@ Output, exactly this shape:
    plainly the answer explained itself, and however the rubric is worded. Say
    in `why` that you are overriding a rubric clause, so the clause gets fixed.
    This rule exists because a set shipped one: a question asked for sales over
-   the company's season, the answer gave the meteorological window 25% lower
+   the company's season, the answer gave the meteorological window 20% lower
    and said which window it used, and a clause granting `near_match` for a
    stated window kept a materially wrong answer out of the pass rate
    entirely -- the arm reported 100%.

package/skills/eval-loop/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eval-loop
 description: 'Conduct a local Publisher evaluation loop in five steps: scrape/run, eval, diagnose, improve, checkpoint. You are the conductor: import cases into the file ledger, spawn a blind answerer, then run eval-answer, eval-diagnose, and eval-improve. Persistence is plain files: the set in the model package''s evals/ directory, runs in the set''s workdir; checkpoints are git commits of the model repo. `eval.py` runs each step from the set''s eval.toml. Use to score a model, diagnose failures, improve behind an acceptance check, or roll back a bad direction.'
-version: 0.1.40
+version: 0.1.42
 ---
 
 # The Evaluation Loop

package/skills/eval-loop/templates/eval-run-package/README.md

@@ -37,8 +37,8 @@ Both, and the split is not stylistic.
 **`notebooks/eval_run.malloy`** holds the analytical tables: pass rate, cost, effort,
 where the failures are, retrieval, the backlog. Publisher renders it natively, so
 these are Malloy reading the model directly with no JavaScript in between and
-nothing to drift. It is written as `run:` cells, a form Publisher still reads and
-converts to the notebook tile layout if someone saves it in the Console.
+nothing to drift. It is a linear report of text and query tiles, so it opens in
+the Console's builder like any other report.
 
 **`public/index.html`** leads with the score and where every question landed,
 then the diagnosis backlog (failures grouped by shared cause), an effort strip

package/skills/eval-loop/templates/eval-run-package/notebooks/eval_run.malloy

@@ -1,10 +1,38 @@
 ##" One or more scored runs over one evaluation set: the analytical tables.
-## artifact { layout=linear title="Eval run" }
+##| artifact { layout=linear title="Eval run"
+  tiles=[
+    intro { kind=text },
+    the_headline { kind=text },
+    "run_summary",
+    is_the_headline_trustworthy { kind=text },
+    "attempts_tiles -> run_health",
+    what_it_cost { kind=text },
+    "cost",
+    "effort",
+    where_the_failures_are { kind=text },
+    "failures_by_where_to_fix",
+    pass_rate_by_coverage { kind=text },
+    "pass_by_coverage",
+    retrieval_intro { kind=text },
+    "retrieval_as_used",
+    most_missed_intro { kind=text },
+    "most_missed_entities",
+    what_to_do_next { kind=text },
+    "backlog",
+    coverage_gaps_in_the_set_itself { kind=text },
+    "coverage_gaps",
+    refusal_intro { kind=text },
+    "refusal_behaviour",
+    comparing_arms { kind=text },
+    "flips",
+    cases_every_arm_failed { kind=text },
+    "failed_everywhere"
+  ]
+}
+|##
 import "../eval_run.malloy"
 
-##|(markdown)
-# Eval run
-
+##|(markdown) intro
 One or more scored runs over one evaluation set. Publisher renders this natively,
 so every table below is Malloy reading the same model the app reads -- there is no
 second copy of the logic to drift.
@@ -18,7 +46,7 @@ Read it top to bottom: the headline, then whether the headline is trustworthy,
 then where the failures are, then what to do about them.
 |##
 
-##|(markdown)
+##|(markdown) the_headline
 ## 1. The headline
 
 Pass rate over **decided** verdicts -- `match` against `no_match`. Two things are
@@ -34,9 +62,7 @@ answered the same cases. Read `near_matches` too. It is the leading indicator of
 rubrics going vague, and it moves before the pass rate does.
 |##
 
-run: run_summary
-
-##|(markdown)
+##|(markdown) is_the_headline_trustworthy
 ## 2. Is the headline trustworthy?
 
 A pass rate means nothing if the attempts behind it were contaminated, if the
@@ -47,18 +73,7 @@ not evidence about the model. Harness errors are excluded from the rate rather
 than counted as failures: a timeout is the eval failing, not the answerer.
 |##
 
-run: attempts -> {
-  group_by: arm is runs.label
-  aggregate:
-    attempt_count
-    submitted_count
-    contaminated_count
-    harness_errors
-    judge_version is runs.judge_version.max()
-    set_version is runs.set_version.max()
-}
-
-##|(markdown)
+##|(markdown) what_it_cost
 ## 3. What it cost
 
 The claim a semantic model makes is not only that the agent gets the right
@@ -67,11 +82,7 @@ An arm that wins on accuracy while costing three times as much has not obviously
 won.
 |##
 
-run: cost
-
-run: effort
-
-##|(markdown)
+##|(markdown) where_the_failures_are
 ## 4. Where the failures are
 
 Every failure carries exactly one **where to fix**, so these counts sum to the
@@ -94,9 +105,7 @@ tables below disagree with each other.
   neither.
 |##
 
-run: failures_by_where_to_fix
-
-##|(markdown)
+##|(markdown) pass_rate_by_coverage
 ### Pass rate by coverage
 
 Coverage is the ceiling on what any agent can do. A model-shaped problem shows up
@@ -107,9 +116,7 @@ only by assembling it, and the agent could not.
 declined.
 |##
 
-run: pass_by_coverage
-
-##|(markdown)
+##|(markdown) retrieval_intro
 ## 5. Retrieval
 
 **Per-question entity recall**: of the entities each golden answer depends on, how
@@ -119,18 +126,14 @@ terms the answerer chose, so it moves when the answerer changes; use it to
 attribute a failure *within* one arm, not to compare retrieval across arms.
 |##
 
-run: retrieval_as_used
-
-##|(markdown)
+##|(markdown) most_missed_intro
 ### Entities most often needed and not returned
 
 The ranked retrieval backlog. An entity high on this list is one fix that several
 cases are waiting on.
 |##
 
-run: most_missed_entities
-
-##|(markdown)
+##|(markdown) what_to_do_next
 ## 6. What to do next
 
 Failures grouped by shared root cause, ordered by how many cases one edit would
@@ -142,9 +145,7 @@ that nobody stands behind is worse than a blank, because a reviewer has to
 disprove it.
 |##
 
-run: backlog
-
-##|(markdown)
+##|(markdown) coverage_gaps_in_the_set_itself
 ### Coverage gaps in the set itself
 
 Independent of any run: cases the model cannot answer outright, with the entity
@@ -152,9 +153,7 @@ that would close the gap. This is the model-improvement backlog even before an
 agent has attempted anything, and it is the part a customer can act on directly.
 |##
 
-run: coverage_gaps
-
-##|(markdown)
+##|(markdown) refusal_intro
 ## 7. Refusal behaviour
 
 Refusal is scored in both directions, and getting one right while getting the
@@ -167,9 +166,7 @@ other wrong is a common and misleading result.
   looking well-calibrated on the ones above.
 |##
 
-run: refusal_behaviour
-
-##|(markdown)
+##|(markdown) comparing_arms
 ## 8. Comparing arms
 
 Only meaningful with two or more arms loaded.
@@ -182,13 +179,24 @@ one case. What matters is which cases actually moved, and in which direction.
 verdicts to see who won each one.
 |##
 
-run: flips
-
-##|(markdown)
+##|(markdown) cases_every_arm_failed
 ### Cases every arm failed
 
 Changing the answerer will not move these. They are where model and retrieval
 work pays off, and they are the most durable finding in the whole run.
 |##
 
-run: failed_everywhere
+// The one table the model does not name as a query: the run's health, by arm.
+source: attempts_tiles is attempts extend {
+  # label="Run health"
+  view: run_health is {
+    group_by: arm is runs.label
+    aggregate:
+      attempt_count
+      submitted_count
+      contaminated_count
+      harness_errors
+      judge_version is runs.judge_version.max()
+      set_version is runs.set_version.max()
+  }
+}

package/skills/eval-report/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eval-report
 description: 'Write the summary a person reads after an evaluation run: what ran, what it scored, which failures were the MODEL and which were the EVAL itself (out of turns, contaminated, unestablished golden, unreadable judge), what was learned, and what to do next. Every claim links to the artifact behind it. Use at the end of any run, before quoting a number to anyone. Never scores an answer (eval-answer) or decides who owns a failure (eval-diagnose).'
-version: 0.1.40
+version: 0.1.42
 ---
 
 # Report a Run

package/skills/malloy-analysis/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-analysis
 description: "Read before your first get_context call on any business or data question. The required workflow, not background: which source, which rows, how to verify. Skipping it causes confident wrong answers."
-version: 0.1.40
+version: 0.1.42
 ---
 
 <!-- Copyright (c) Credible Data Inc. SPDX-License-Identifier: MIT -->

package/skills/malloy-analysis-report/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: malloy-analysis-report
 description: Combine validated Malloy queries into a report (a linear report, read top to bottom). Use when the user asks to "create a report", "combine these into a report", or wants a persistent multi-query artifact.
-version: 0.1.40
+version: 0.1.42
 ---
+
 <!--
 Copyright (c) Credible Data Inc.
 SPDX-License-Identifier: MIT
@@ -10,9 +11,7 @@ SPDX-License-Identifier: MIT
 
 # Creating Reports
 
-An ad-hoc report is a Publisher **report** with `layout=linear`: a `.malloy` file at the package root, `<slug>.malloy` (unless the user asks for another location), that combines markdown narrative with live Malloy queries. An ad-hoc report is written as `run:` cells, which Publisher reads and which convert to tiles when saved in the Console; when the queries are views on a source, or the report will be kept and edited, `skill:malloy-reports` describes the tile form (`tiles=[…]`) to author instead. Load `skill:malloy-reports` for the full format and authoring rules; this skill covers when to build one and how to design good report content (cells, chart annotations, narrative structure). Never write a new `.malloynb`, and do not create a `notebooks/` or `dashboards/` directory for it.
-
-> **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.
+An ad-hoc report is a Publisher **report** with `layout=linear`: a `.malloy` file at the package root, `<slug>.malloy` (unless the user asks for another location), that combines markdown narrative with live Malloy queries, as text tiles and query tiles read top to bottom. Load `skill:malloy-reports` for the full format and authoring rules; this skill covers when to build one and how to design good report content (tiles, chart annotations, narrative structure). Never write a new `.malloynb`, never write a report as bare `run:` statements (that older form is no longer read), and do not create a `notebooks/` or `dashboards/` directory for it.
 
 ## Before building a report
 
@@ -22,80 +21,107 @@ An ad-hoc report is a Publisher **report** with `layout=linear`: a `.malloy` fil
 
 Do NOT build the report in the same turn as `execute_query`. Explain first, then build.
 
-## Filters are inherited from the model, don't declare them in the report
+## Filters belong to the report, never to the source
+
+An ad-hoc report usually needs no filters: it records an analysis already run. If the user wants one a reader can change (a manufacturer, a date range), declare the given in the report and bind it on its tiles, as `skill:malloy-reports` describes. Do not add a `given:` to the source for it: a model-level `where:` filters every read of the source, chat and every other report included, and the report builder can show such a filter but not change or remove it. A given the source already reads (a gate, a value every query must supply) shows in the report with no work, and stays in the model.
 
-Do not declare filters in an ad-hoc report. If the source declares `given:` parameters (or legacy `#(filter)` annotations), Publisher renders the controls, parses caller parameters, and applies them server-side automatically: the report inherits and displays them with no extra work. If the analysis needs a knob the source doesn't expose, the right move is to add a `given:` to the source itself, not to wedge a filter widget into the report. `#(filter)` is deprecated in favour of native Malloy `given:` parameters. Never add a `#(filter)` annotation: every use, including `required`, `implicit`, and date/number ranges, has a `given:` form. The `malloy-model` skill covers this under § Legacy: Parameterizable Filters. For a curated report with its own filter controls on top of the model, see `skill:malloy-reports` instead.
+Never add a `#(filter)` annotation: it is deprecated, and every use has a `given:` form (`malloy-model` covers the migration).
 
 ## What goes in the report
 
-Do NOT add an H1 heading in any markdown (use H2 and below for sections); the `title` in the `## artifact` tag serves as the title. To redo the structure rather than tweak one cell, rewrite the report file end-to-end.
+Do NOT add an H1 heading in any markdown (use H2 and below for sections); the `title` in the `## artifact` tag serves as the title. To redo the structure rather than tweak one tile, rewrite the report file end-to-end.
 
-Markdown cells own narrative; query cells own a single Malloy query whose chart annotation tells the renderer how to display the result. Markdown supports H2 headings, lists, bold, and inline code. Keep narrative cells short, one idea per cell, so the rendered output reads as a story instead of a wall of text.
+Text tiles own narrative; query tiles own a single Malloy query whose chart annotation tells the renderer how to display the result. Markdown supports H2 headings, lists, bold, and inline code. Keep text tiles short, one idea per tile, so the rendered output reads as a story instead of a wall of text.
 
-The file starts with `## artifact { layout=linear title="..." }`, then the `import` for the model file (relative to the report's own location: `"order_analysis.malloy"` from the package root). Definitions (`import`, `source:`, `query:`, `given:`) come before the first markdown or `run:`. Prose is `##|(markdown)` ... `|##` for a block (body on the lines between) or `##(markdown) text` for one line. Each `run:` is a query cell, and its tags sit directly above it with nothing between. A `#"` directly above the `run:` is its caption. Trailing prose is `##(markdown)`, never `#(markdown)` or `#"`.
+The file has four parts, in this order:
 
-This is the cell format, the quick form for an ad-hoc report; for a report that will be kept and edited, write the tile form in `skill:malloy-reports` (`## artifact { layout=linear tiles=[…] }`) instead.
+1. **The tag**, `##| artifact { layout=linear title="..." tiles=[…] }`, listing every tile in reading order. A text tile is `name { kind=text }`; a query tile is the quoted string `"<extension> -> <view>"`.
+2. **The `import`** of the model file, relative to the report's own location (`"order_analysis.malloy"` from the package root).
+3. **The text tiles**, each a `##|(markdown) name` block: the name on the opener line, the body on the lines below, `|##` closing it.
+4. **One extension of the source**, `source: <source>_tiles is <source> extend { … }`, holding a `view:` per query tile. The view's chart tag and `# label="…"` (the tile's heading) go directly above it.
 
-Each `run:` must be a standalone query (for example `run: source -> { ... }`). The `import` is file-wide: query cells never repeat it. Compile the file with `/compile` (`"scope": "file"`, at the path `<slug>.malloy`) before saving; a report compiles as a model, so its errors come back there. A complete report:
+Compile the file with `/compile` (`"scope": "file"`, at the path `<slug>.malloy`) before saving; a report compiles as a model, so its errors come back there. After saving and reloading, read the package warnings: a tile that names a missing view is reported there, not by the compile. A complete report:
 
 ```malloy
-## artifact { layout=linear title="Sales report" }
+##| artifact { layout=linear title="Sales report"
+  tiles=[
+    overview { kind=text },
+    "order_analysis_tiles -> headline",
+    trend { kind=text },
+    "order_analysis_tiles -> revenue_by_month",
+    breakdown { kind=text },
+    "order_analysis_tiles -> top_categories",
+    takeaways { kind=text }
+  ]
+}
+|##
 import "order_analysis.malloy"
 
-##|(markdown)
+##|(markdown) overview
 ## Overview
-What is driving sales, and which categories carry it? The queries below cover every order in the model.
+What is driving sales, and which categories carry it? The tiles below cover every order in the model.
 |##
 
-# big_value
-run: order_analysis -> {
-  aggregate:
-    # label="Revenue"
-    # currency
-    total_revenue
-
-    # label="Orders"
-    # number=auto
-    order_count
-}
-
-##(markdown) ## Trend: how does revenue move over time?
-
-#" Revenue by month
-# line_chart
-run: order_analysis -> {
-  group_by: order_date.month
-  aggregate: total_revenue
-  order_by: 1
-}
+##|(markdown) trend
+## Trend
+How does revenue move over time?
+|##
 
-##|(markdown)
+##|(markdown) breakdown
 ## Breakdown
 Which categories account for the most revenue?
 |##
 
-#" Top ten categories by revenue
-# bar_chart
-run: order_analysis -> {
-  group_by: category
-  aggregate: total_revenue
-  order_by: total_revenue desc
-  limit: 10
-}
+##|(markdown) takeaways
+## Key takeaways
+What to look at next.
+|##
 
-##(markdown) ## Key takeaways: what to look at next.
+source: order_analysis_tiles is order_analysis extend {
+  # big_value
+  # label="Headline"
+  view: headline is {
+    aggregate:
+      # label="Revenue"
+      # currency
+      total_revenue
+
+      # label="Orders"
+      # number=auto
+      order_count
+  }
+
+  # line_chart
+  # label="Revenue by month"
+  view: revenue_by_month is {
+    group_by: order_date.month
+    aggregate: total_revenue
+    order_by: 1
+  }
+
+  # bar_chart
+  # label="Top ten categories by revenue"
+  view: top_categories is {
+    group_by: category
+    aggregate: total_revenue
+    order_by: total_revenue desc
+    limit: 10
+  }
+}
 ```
 
+When the model already has the view you want, the tile view refines it rather than repeating it: `view: top_categories is by_category + { limit: 10 }`.
+
 A well-structured report typically follows this pattern:
 
 ```
-[Markdown]  ## Overview: what question are we answering, what data is in scope (date range, entity count)
-[Malloy]    KPI cell: headline numbers (e.g., # big_value, or # dashboard with nested # big_value cells)
-[Markdown]  ## Trend: describe what we should look for over time
-[Malloy]    Time-series cell (e.g., # line_chart on a date dimension)
-[Markdown]  ## Breakdown: where the signal is
-[Malloy]    Categorical cell (e.g., # bar_chart on a categorical dimension)
-[Markdown]  ## Key takeaways: what the user should walk away with
+[Text]   ## Overview: what question are we answering, what data is in scope (date range, entity count)
+[Query]  KPI tile: headline numbers (e.g., # big_value, or # dashboard with nested # big_value views)
+[Text]   ## Trend: describe what we should look for over time
+[Query]  Time-series tile (e.g., # line_chart on a date dimension)
+[Text]   ## Breakdown: where the signal is
+[Query]  Categorical tile (e.g., # bar_chart on a categorical dimension)
+[Text]   ## Key takeaways: what the user should walk away with
 ```
 
 Use this as a default; deviate when the analysis warrants. A grounded report names the time range and entity count up front so every number that follows has context.
@@ -105,17 +131,18 @@ Use this as a default; deviate when the analysis warrants. A grounded report nam
 Read `skill:malloy-charts` before picking visualizations: it owns chart-type selection, properties, and the placement rules for chart annotations. `skill:malloy-queries` covers Malloy query patterns and the critical placement rules for chart-annotation tags.
 
 When in doubt:
+
 - KPIs / single numbers -> `# big_value`, often nested inside `# dashboard`.
 - Trend over time -> `# line_chart`, usually on the primary date dimension.
 - Category comparisons -> `# bar_chart`, ordered by the metric.
-- Tabular data with many columns -> a plain table cell with `# table.size=fill`.
+- Tabular data with many columns -> a plain table tile with `# table.size=fill`.
 - Multiple coordinated charts -> `# dashboard` with `nest:` blocks.
 
-Annotations go **before** `run:`, never inside curly braces:
+Annotations go **directly above** the tile's `view:`, never inside its curly braces:
 
 ```malloy
 # bar_chart
-run: source -> {
+view: top_categories is {
   group_by: category
   aggregate: revenue
   order_by: revenue desc
@@ -123,11 +150,11 @@ run: source -> {
 }
 ```
 
-A `# dashboard` cell composes nested views, useful for KPIs alongside a trend in a single cell. Each `nest:` is a tile; any top-level `aggregate:` measures render as KPI cards. For a fixed grid, use `# dashboard { columns=N }` with `# colspan` on each tile (see `skill:malloy-charts`):
+A `# dashboard` tile composes nested views, useful for KPIs alongside a trend in a single tile. Each `nest:` is a tile; any top-level `aggregate:` measures render as KPI cards. For a fixed grid, use `# dashboard { columns=N }` with `# colspan` on each tile (see `skill:malloy-charts`):
 
 ```malloy
 # dashboard { columns=2 }
-run: source -> {
+view: summary is {
   nest:
     # colspan=2
     # big_value
@@ -151,7 +178,8 @@ run: source -> {
 }
 ```
 
-Key rendering rules to keep in mind when shaping a cell:
+Key rendering rules to keep in mind when shaping a tile:
+
 - FIRST `group_by` = x-axis, FIRST `aggregate` = y-axis.
 - Override field roles with `# x`, `# y`, `# series` on individual fields.
 - For multiple measure series, place `# y` above the `aggregate:` keyword.
@@ -160,8 +188,8 @@ Key rendering rules to keep in mind when shaping a cell:
 
 ## Editing an existing report
 
-For small targeted changes (fix one cell, insert one new cell), edit the cell's statement or markdown in place rather than recreating the whole report. For structural rewrites (reordering many cells, changing the narrative arc), rewrite the report file. An existing `.malloynb` is read, not edited: to change its story, write a `.malloy` report. An existing report's tag that says `kind=notebook` is the deprecated spelling of `layout=linear`; fix it when you edit the file.
+For small targeted changes (fix one view, insert one tile), edit that view or text block in place and add its entry to `tiles=[…]`, rather than recreating the whole report. For structural rewrites (reordering many tiles, changing the narrative arc), rewrite the report file. An existing `.malloynb` is read, not edited: to change its story, write a `.malloy` report. A tag that sets `kind=notebook` is no longer read, so the file is not a report (`report-kind-removed`): replace it with `layout=linear` and list the tiles. A linear file with no `tiles=[…]`, written as bare `run:` statements, is no longer a report: rewrite it as tiles (`skill:malloy-reports`, `reference/linear.md`).
 
 ## IMPORTANT
 
-You CANNOT see the rendered output of report cells. Do not claim to see charts, values, or patterns from report cells you haven't explicitly executed via `execute_query`. If you need to analyze results, run the query via `execute_query` first.
+You CANNOT see the rendered output of report tiles. Do not claim to see charts, values, or patterns from report tiles you haven't explicitly executed via `execute_query`. If you need to analyze results, run the query via `execute_query` first.

package/skills/malloy-charts/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-charts
 description: Read before choosing a chart or adding a chart annotation. Chart types, tag syntax and scale rules, KPI cards, dashboards, sparklines, and the renderer mistakes that fail silently.
-version: 0.1.40
+version: 0.1.42
 ---
 <!--
 Copyright (c) Credible Data Inc.

package/skills/malloy-dashboards/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-dashboards
 description: "Renamed to malloy-reports. A dashboard is now a report with layout=grid: a .malloy file with an ## artifact tag, written at the package root. Load malloy-reports instead when the user asks for a dashboard, a filterable view, or drill-through between views."
-version: 0.1.40
+version: 0.1.42
 ---
 
 <!--

package/skills/malloy-define/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-define
 description: Propose scope, a source plan and field definitions for a Malloy model. Which tables and questions, which sources at what grain, then renames, dimensions and measures, each backed by querying data.
-version: 0.1.40
+version: 0.1.42
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -178,7 +178,7 @@ The user will:
 - **Remove** fields they don't need.
 - **Change** priorities.
 
-Once the definitions are confirmed, write them into the `.malloy` model (see your modeling workflow). Use `#(doc)` annotations to document sources and fields, and `given:` parameters to declare runtime-filterable dimensions where appropriate. `#(filter)` is deprecated. Never add a `#(filter)` annotation: every use, including `required`, `implicit`, and date/number ranges, has a `given:` form. See `skill:malloy-model` § Parameterizing sources with `given:`. Keep the confirmed definitions in the conversation; there is no separate plan-file store.
+Once the definitions are confirmed, write them into the `.malloy` model (see your modeling workflow). Use `#(doc)` annotations to document sources and fields, and a `given:` only where the data's meaning or access depends on a runtime value (a gate, a value every query must supply). A filter a reader picks on a dashboard belongs to the report, not the model. `#(filter)` is deprecated. Never add a `#(filter)` annotation: every use, including `required`, `implicit`, and date/number ranges, has a `given:` form. See `skill:malloy-model` § Parameterizing sources with `given:`. Keep the confirmed definitions in the conversation; there is no separate plan-file store.
 
 ## Data-driven proposals
 

package/skills/malloy-discover/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-discover
 description: Silent data discovery for Malloy modeling. Used at Step 1 of the modeling workflow. Scans tables, columns, distributions, and relationships without user interaction. The agent builds an internal picture before presenting anything.
-version: 0.1.40
+version: 0.1.42
 ---
 <!--
 Copyright (c) Credible Data Inc.