@malloy-publisher/skills 0.1.36 → 0.1.38

package/package.json

@@ -1,7 +1,7 @@
 {
    "name": "@malloy-publisher/skills",
    "description": "Agent skills for Malloy and the Malloy Publisher",
-   "version": "0.1.36",
+   "version": "0.1.38",
    "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.36
+version: 0.1.38
 ---
 
 # Evaluate One Answer

package/skills/eval-answer/scripts/ledger_test.py

@@ -163,6 +163,9 @@ class WriteContract(unittest.TestCase):
             ledger.event("score", qid="q1", sample=0, phase="baseline",
                          verdict="probably", reason="r")
 
+    # DEPRECATED FEATURE COVERAGE -- delete together with `filterParams`
+    # (see RELEASE_NOTES deprecations). The givens test below is the current
+    # form.
     def test_a_tool_call_records_the_filters_it_ran_under(self):
         """`query`, `modelPath` and `filterParams` are one fact about one call.
 

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.36
+version: 0.1.38
 ---
 
 # Diagnose One Answer

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.36
+version: 0.1.38
 ---
 
 # Import questions into an eval set

package/skills/eval-improve/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eval-improve
 description: 'Make the smallest safe Malloy model edit that closes a diagnosed model-owned gap, with a probe receipt for every factual claim. 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.36
+version: 0.1.38
 ---
 
 # Improve the Model

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.36
+version: 0.1.38
 ---
 
 # The judge

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.36
+version: 0.1.38
 ---
 
 # The Evaluation Loop

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

@@ -1,5 +1,5 @@
 ##" One or more scored runs over one evaluation set: the analytical tables.
-## artifact { kind=notebook title="Eval run" }
+## artifact { layout=linear title="Eval run" }
 import "../eval_run.malloy"
 
 ##|(markdown)

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.36
+version: 0.1.38
 ---
 
 # 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.36
+version: 0.1.38
 ---
 
 <!-- Copyright (c) Credible Data Inc. SPDX-License-Identifier: MIT -->
@@ -16,7 +16,7 @@ You answer data questions against Malloy semantic models reached over MCP; you h
 
 Restate what is being asked: which metric, which breakdown (group-by), which filters, which time range. Decide whether the question is standalone or depends on prior conversation, and what a correct answer would look like: its shape, magnitude and grain. If the question is ambiguous, make the most reasonable assumption and state it rather than stalling. **One exception: when the MODEL ITSELF says the ask is ambiguous** (a source or field doc that names two valid readings and says there is no default), assuming is the wrong move. Ask which the user means, naming both, or return both clearly labelled; naming the ambiguity and then picking one anyway is not resolving it. This applies equally to a follow-up ("more granular", "break that down", "same thing but by week") that refines the SHAPE of an earlier answer and settles no metric nobody has chosen: if no previous turn established which metric, the ambiguity is still open however the question is worded.
 
-**No specific question** ("what's interesting?", "explore this data", "look for patterns")? Orient with step 2 and tell the user what data exists (sources, grain, date range). Then profile: with a question, only the columns it touches; without one, broadly, for surprises (`run: source -> { index: * limit: 100 }`, `min`/`max`/null count of numbers, the top 20 values of each category, date range and gaps, duplicate keys with `having: n > 1`). Offer 3 to 5 hypotheses ranked by likely impact (skew: outliers; time patterns: trend; imbalance: segments; correlated columns: drivers; unexpected nulls: data quality) and ask which to pursue; if the user named one, go straight to it. Investigate each with steps 3 to 5 (`search_malloy_docs` has patterns for window functions, cohorts and percent of total), validate each finding with at least one second check (another metric, the denominator, whether it repeats over time, the raw rows), and report the three to five best insights with evidence, confidence and assumptions. To keep views, offer a dashboard (`malloy-dashboards`); to turn the work into a model, `malloy-model-as-you-go` or `malloy-model`.
+**No specific question** ("what's interesting?", "explore this data", "look for patterns")? Orient with step 2 and tell the user what data exists (sources, grain, date range). Then profile: with a question, only the columns it touches; without one, broadly, for surprises (`run: source -> { index: * limit: 100 }`, `min`/`max`/null count of numbers, the top 20 values of each category, date range and gaps, duplicate keys with `having: n > 1`). Offer 3 to 5 hypotheses ranked by likely impact (skew: outliers; time patterns: trend; imbalance: segments; correlated columns: drivers; unexpected nulls: data quality) and ask which to pursue; if the user named one, go straight to it. Investigate each with steps 3 to 5 (`search_malloy_docs` has patterns for window functions, cohorts and percent of total), validate each finding with at least one second check (another metric, the denominator, whether it repeats over time, the raw rows), and report the three to five best insights with evidence, confidence and assumptions. To keep views, offer a report (`malloy-reports`: a grid for a dashboard, linear for a write-up); to turn the work into a model, `malloy-model-as-you-go` or `malloy-model`.
 
 ## 2. Discover the model (never guess names)
 
@@ -24,6 +24,7 @@ Find the right entities before writing any query.
 
 - If you do not already know which package to work in, confirm the environment and package with the user before continuing.
 - **Load `skill:malloy-phrase-detection`**, then call `get_context` with entity targets that describe the fields the question needs: a `measure` for the metric, a `dimension` for each breakdown or filter, and a `view` if the question sounds like a canned report. **Every target carries a `search_text`**: a target without one enumerates a capped catalog instead of searching, and the cap is blind to your question. The tool description covers what comes back and how to narrow or browse.
+- **A value the user typed (a brand, a city, a product name) is not yet a filter.** Resolve it to the string the data stores before you filter on it: a `dimensional_value` target in that `get_context` call, or, where value search isn't available, a query of the dimension's distinct values. "ray ban" may be stored as `Ray-Ban` and `Ray-Ban Junior`; a `where:` on the user's own spelling, or a regex guessed from it, can match nothing and still return a result.
 - Read the documentation on each returned entity: on an entity it is `description`, on a source it is `docs`, often with a short `one_line_summary` and sometimes a longer `summary`. Which of these a server fills varies, so read the ones your response actually carries and do not go hunting for one that is absent. Authors write it as `#(doc)` in the model, but the response never uses that label, so do not go looking for that either. It is where grain, units, null handling, and any source-level filters are described. Confirm the exact field names against the results before using them.
 - **Read the source's own documentation too, not just each field's.** The source-level `docs` often defines the grain, the universe of rows it represents, how joins behave, and source-level filters or assumptions that apply to every query rooted on it. Factor both the source and the field docstrings into how you build and later verify the query.
 - **Do not rebuild a view that already exists from its description.** A description says what a view does, not how; rebuilding from prose loses what prose does not carry: a denominator, a `partition_by`, an exact filter. Set `entity_name` in the scope to get that entity on its own instead of a ranked sweep. That also returns its `code` (for a view, its definition as written): read it first, with the source's `docs` and the entity's `description`. Then RUN the view and adapt its output rather than writing a replacement; to change a band width or grain, change that one thing and keep the rest. Where a server returns no `code`, the docs plus the view's own output are what you have, and a calculation you cannot see is a reason to reuse the view rather than guess at it.
@@ -118,4 +119,4 @@ Answer in plain language, lead with the number that was asked for, and show the
 
 **A list says whether it is complete.** When you list what exists (packages, sources, fields, values), list all of it or say it is a selection ("the 10 largest of 31"). When `get_context` reports N of M sources, never present the N as everything: pass a returned `next_offset` back as `offset` for the rest, or follow its warning (narrow the search, raise `limit`), or say how many more there are. Never estimate a count you can read off a result ("about 25"). Give counts in the unit the tool reported, and add no total it did not report unless asked; then count it from the list you give or compute it in a query.
 
-End with a short **Next steps**: one or two specific deeper analyses the data could support, concrete to what you just found. Keep it unless your host's instructions say it shows follow-up suggestions of its own, which then carry the next steps. If you can write package files, you can also offer to save the analysis as a dashboard (`malloy-dashboards`) so it can be re-run and shared; if your host has a report tool instead, offer a report. Offer a notebook only when the user asks for one.
+End with a short **Next steps**: one or two specific deeper analyses the data could support, concrete to what you just found. Keep it unless your host's instructions say it shows follow-up suggestions of its own, which then carry the next steps. If you can write package files, you can also offer to save the analysis as a report (`malloy-reports`, at the package root) so it can be re-run and shared: a grid for views read at a glance, linear for a story read top to bottom. If your host has a report tool of its own instead, offer that.

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

@@ -1,7 +1,7 @@
 ---
 name: malloy-analysis-report
-description: Combine validated Malloy queries into a notebook report. Use when the user asks to "create a report", "combine these into a report", or wants a persistent multi-query artifact.
-version: 0.1.36
+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.38
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -10,7 +10,7 @@ SPDX-License-Identifier: MIT
 
 # Creating Reports
 
-An ad-hoc report is a `.malloy` notebook, `notebooks/<slug>.malloy`, that combines markdown narrative with live Malloy queries. An ad-hoc report is written as `run:` cells, which Publisher still reads and which convert to the one-column tile layout when saved in the Console; when the queries are views on a source, `skill:malloy-notebooks` describes the layout form (`tiles=[…]`) to author instead. Load `skill:malloy-notebooks` 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`.
+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.
 
@@ -18,29 +18,29 @@ An ad-hoc report is a `.malloy` notebook, `notebooks/<slug>.malloy`, that combin
 
 1. **Run each query first** via `execute_query` to verify it works and returns expected results.
 2. **Explain the results** to the user as you go: walk through the analysis step by step.
-3. **Then assemble the notebook** once the analysis is validated.
+3. **Then assemble the report** once the analysis is validated.
 
-Do NOT build the notebook in the same turn as `execute_query`. Explain first, then build.
+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
 
-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 curated notebooks with their own per-notebook filter UI on top of the model, see `skill:malloy-notebooks` instead.
+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.
 
 ## 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 notebook 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 cell, 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.
 
-The file starts with `## artifact { kind=notebook title="..." }`, then the `import` for the model file. 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 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 `#"`.
 
-This is the cell format, the quick form for an ad-hoc report; for a notebook that will be kept and edited, write the layout form in `skill:malloy-notebooks` (`## artifact { kind=notebook tiles=[…] }`) instead.
+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.
 
-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 `notebooks/<slug>.malloy`) before saving; a `.malloy` notebook compiles as a model, so its errors come back there. A complete report:
+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:
 
 ```malloy
-## artifact { kind=notebook title="Sales report" }
-import "../order_analysis.malloy"
+## artifact { layout=linear title="Sales report" }
+import "order_analysis.malloy"
 
 ##|(markdown)
 ## Overview
@@ -160,8 +160,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 notebook. For structural rewrites (reordering many cells, changing the narrative arc), rewrite the notebook file. An existing `.malloynb` is read, not edited: to change its story, write a `.malloy` notebook.
+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.
 
 ## IMPORTANT
 
-You CANNOT see the rendered output of notebook 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 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.

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.36
+version: 0.1.38
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -12,7 +12,7 @@ SPDX-License-Identifier: MIT
 
 > 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).
 
-> **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.
+> **This file is about the Malloy renderer's `#` tags.** It applies when the view itself is rendered - a tile or cell in a report (either layout), 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.
 
 > **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.