@malloy-publisher/skills 0.1.9 → 0.1.12

package/package.json

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

package/skills/malloy/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy
 description: Index of all Malloy skills. Use when user asks "malloy help", "what malloy skills are available", "how do I use malloy", or needs guidance on which Malloy skill to use.
-version: 0.1.9
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -42,7 +42,8 @@ Every skill in this deployment, by what it is for. Start at a driver; it routes
 
 | Skill | Use when... |
 |-------|-------------|
-| `skill:malloy-analyze` | Exploratory data analysis: profiling, building views and dashboards |
+| `skill:malloy-model-as-you-go` | After answering a question, writing down what it assumed: a `#(doc)`'d field in the model, an `extend` in the notebook, or a stated assumption plus snippet, depending on what the session can write |
+| `skill:malloy-analyze` | Open-ended exploration with no intent to keep anything: profiling, hypotheses, views |
 | `skill:malloy-charts` | Chart selection and renderer reference for Malloy visualizations |
 | `skill:malloy-notebooks` | Building Malloy notebooks (.malloynb) |
 | `skill:malloy-analysis-report` | Combining validated queries into a notebook report or dashboard |

package/skills/malloy-analysis/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-analysis
 description: Workflow for answering data questions against Malloy semantic models over MCP - structured discovery with get_context, query construction with execute_query, verification, and answer delivery. Use whenever the user asks a data question, wants a metric, a breakdown, a trend, or a chart over a model.
-version: 0.1.9
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

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

@@ -1,7 +1,7 @@
 ---
 name: malloy-analysis-pitfalls
 description: Common data analysis pitfalls to watch for during query construction and result interpretation. Reference this checklist when verifying queries and results to catch errors before presenting an answer.
-version: 0.1.9
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

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

@@ -1,7 +1,7 @@
 ---
 name: malloy-analysis-report
 description: Combine validated Malloy queries into a notebook report or dashboard. Use when the user asks to "create a report", "build a dashboard", "combine these into a report", or wants a persistent multi-query artifact.
-version: 0.1.9
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -24,7 +24,7 @@ Do NOT build the notebook in the same turn as `execute_query`. Explain first, th
 
 ## Filters are inherited from the model, don't declare them in the report
 
-Reports do not (and cannot) define their own filters. If the source has `#(filter)` annotations, Publisher renders the filter widgets, parses caller parameters, and injects `where:` clauses server-side automatically: the report inherits and displays those filters with no extra work. If the analysis needs a knob the source doesn't expose, the right move is to add a `#(filter)` to the source itself (see your modeling workflow's parameterizable-filter guidance for `#(filter)`), not to wedge a filter widget into the report. For curated notebooks with their own per-notebook filter UI on top of the model, see `skill:malloy-notebooks` instead.
+Reports do not (and cannot) define their own filters. 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. Do not add new `#(filter)` annotations; the two exceptions are `required` and `implicit`, which `given:` cannot cover yet. 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.
 
 ## What goes in the report
 

package/skills/malloy-analyze/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-analyze
-description: Explore data for insights and build views/dashboards/notebooks. Use when user asks to "analyze this data", "find insights", "explore for patterns", "what's interesting", "what's driving X", "build a dashboard", "create views", or any analysis task. For EDA exploration, start at Step 1. For building views on an existing model, jump to View Patterns.
-version: 0.1.9
+description: Open-ended exploration with no specific question to answer, and building views/dashboards/notebooks on an existing model. Use when the user asks "what's interesting?", "explore this data", "find insights", "look for patterns", "build a dashboard", or "create views". Not for a specific data question - answering one is `malloy-analysis`, and writing down what the answer assumed is `malloy-model-as-you-go`. For exploration start at Step 1; for views on an existing model jump to View Patterns.
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -254,7 +254,9 @@ A notebook is also the home for a polished, narrated report: alternate `>>>markd
 
 ### Interactive Filters
 
-**Notebooks do NOT define filters themselves.** When you import a model, the model's `#(filter)` annotations on the source are **inherited and displayed automatically**: the publisher renders the filter widgets, parses caller parameters, and injects `where:` clauses server-side. You don't redeclare them in the consumer. If the analysis needs a knob the model doesn't expose, the right move is to add a `#(filter)` to the source itself (see `skill:malloy-model` § Parameterizable Filters with `#(filter)`), not to wedge filtering into the consumer.
+**Notebooks do NOT define filters themselves.** When you import a model, the model's runtime parameters are **inherited and displayed automatically**: the publisher renders the controls, parses caller parameters, and applies them server-side. You don't redeclare them in the consumer. If the analysis needs a knob the model doesn't expose, the right move is to add it to the source itself, not to wedge filtering into the consumer.
+
+**Declare that knob as a `given:`.** `#(filter)` is deprecated in favour of native Malloy `given:` parameters. Do not add new `#(filter)` annotations; the two exceptions are `required` and `implicit`, which `given:` cannot cover yet. See `skill:malloy-model` § Legacy: Parameterizable Filters.
 
 The notebook-level `##(filters)` annotation and the dimension-level `#(filter) {"type": "..."}` JSON-blob form are **unsupported legacy syntax**, don't use them. The only supported form is `#(filter) name=... dimension=... type=...` declared above the source.
 

package/skills/malloy-charts/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-charts
 description: Chart selection guidance and renderer reference for Malloy views. Use when choosing visualization types, adding chart annotations, user asks "what chart should I use", "how should I visualize this", or when deciding between bar_chart, line_chart, scatter_chart, etc.
-version: 0.1.9
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

package/skills/malloy-dashboards/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-dashboards
 description: "Build or modify a Malloy Publisher dashboard, a tagged .malloy file in a package's dashboards/ directory, with auto-rendered filter controls, a grid layout, and # drill click-through. Use when the user asks for a dashboard, a filterable operational view, or drill-through between views, and no code is wanted."
-version: 0.1.9
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -31,8 +31,9 @@ Scanned at a glance is a dashboard; read top to bottom is a notebook.
    `malloy_getContext` if you have it, otherwise the REST model endpoint or the `.malloy` files.
    Never guess a name. A guessed field in a query fails the whole package load, not just that one
    dashboard; a guessed tile or suggest source is quieter, and only shows up in the package warnings.
-2. **DECIDE THE FORM** (below): single-query if the page is one filtered result with parts;
-   composite if the views already exist and the job is choosing which to show together.
+2. **PICK THE VIEWS TO SHOW.** A dashboard is `## artifact { tiles=[…] }` naming existing views, so
+   this is the design step: which views, how wide each sits, what each is called. There is one form,
+   so there is no form to choose.
 3. **DECLARE THE GIVENS** the dashboard will filter by, in the model (usually `givens.malloy`), with
    their control tags: see "Filter controls" below for the syntax and what each tag renders as. Skip
    if they already exist, since a given is a model concern and dashboards share them.
@@ -40,7 +41,11 @@ Scanned at a glance is a dashboard; read top to bottom is a notebook.
    Import every given it filters by, and every source or query any of those givens names in a
    `suggest`. Both are per-file, and getting the suggest wrong does not error: the control still
    looks like a picker but has no options, and says so underneath, "Could not load the options for
-   this control". The package warnings name it too.
+   this control". The package warnings name it too. **A `suggest` naming a `query=` needs that
+   query's own source imported as well**, because an import is not transitive: the query resolves by
+   name, so the file compiles and the package loads, but running the picker fails with
+   `Undefined source '<name>'`. The package warnings name this one too, saying which source to
+   import. Import the source that suggest query reads, not just the query.
 5. **COMPILE IT** with `malloy_compile` (or `POST …/models/<path>/compile`), against the source text,
    before you save, at the path the file will have. **Editing one that already exists needs
    `"scope": "file"`**, which compiles your source AS that file; the default appends it instead, so
@@ -48,7 +53,7 @@ Scanned at a glance is a dashboard; read top to bottom is a notebook.
    already-defined errors that reads as broken Malloy rather than a wrong scope. **Editing a shared
    include wants `"scope": "package"`**, which recompiles every file as saved: `file` only checks the
    one you are editing, so renaming a source in `_shared.malloy` passes it while breaking every
-   composite that imports it. A clean compile is not a working dashboard: some tag mistakes surface
+   dashboard that imports it. A clean compile is not a working dashboard: some tag mistakes surface
    at step 6, and some only when you look at the page in step 7. (The third scope, `append`, is the
    default and is what a not-yet-saved file gets.)
 6. **SAVE IT, RELOAD, AND READ THE MANIFEST AND THE WARNINGS.** `malloy_reloadPackage`, or
@@ -60,9 +65,63 @@ Scanned at a glance is a dashboard; read top to bottom is a notebook.
    and its `query` is the name to run in step 7. See "Read the lint" below.
 7. **OPEN IT AND LOOK.** Not optional; see "What 'done' means".
 
-## The two forms
+## The form
 
-**Single-query:** one query whose result is the dashboard. Reach for this by default.
+A dashboard is `## artifact { tiles=[…] }` at model level: named views, each run as its own query, laid
+out by Publisher into the grid `# dashboard { columns=N }` names.
+
+```malloy
+##! experimental.givens
+## artifact { title="Storefront overview" tiles=["overview -> kpis", "overview -> revenue_trend", "overview -> revenue_by_state"] } dashboard { columns=12 }
+import { scoped_sales } from './_shared.malloy'
+import { products } from '../storefront.malloy'
+import { CATEGORY, SINCE } from '../givens.malloy'
+
+// Layout goes on the VIEW, and a thin re-declaration is the place to put it: the
+// modelled view keeps its chart tag, and this decides how wide it sits here.
+source: overview is scoped_sales extend {
+  # colspan=12
+  # label="Key figures"
+  # big_value
+  view: kpis is {
+    aggregate:
+      # label="Revenue"
+      # currency
+      total_sales
+      # label="Orders"
+      order_count
+  }
+
+  # colspan=8
+  # break
+  # label="Revenue by month"
+  view: revenue_trend is sales_by_month
+
+  # colspan=4
+  # label="Revenue by state"
+  view: revenue_by_state is sales_by_state
+}
+```
+
+Model-level because there is no query of its own to hang a `#` tag on, and model-level for a second
+reason: tiles run as separate queries, which is the only way a page can span unrelated sources. A
+nest's pipeline starts from its own query's source and there is no way to combine two.
+
+Three things the form costs, so you are not surprised by them:
+
+- **A tile expression is a string in an annotation, so the compiler never checks it.** Rename a view
+  and the file still compiles; the tile fails at package load. Read the lint (step 6).
+- **No per-parent-row grouping.** There is no parent query to repeat a grid over.
+- **Filtering lives in what the tiles name**, not on the page. That is the shared include's job,
+  below.
+
+### Also served: `# artifact` on a `query:`
+
+One query whose result is the whole page, laid out by `@malloydata/render` from the query's own
+`# dashboard` tag. This is Malloy's rendering feature, the same thing a notebook cell shows, not a
+second way to build a dashboard, and it cannot span sources. Publisher serves it, so you will meet it
+in existing packages, and the layout tags below are shared with it. Do not author a new dashboard
+this way.
 
 ```malloy
 ##! experimental.givens
@@ -108,25 +167,16 @@ query: overview is order_items -> {
 
 The `#"` line above the tag is a doc comment, and it is the page's description. If you leave `title=`
 off the artifact tag, it becomes the title instead, so write it as one, not as a sentence about the
-page. **It belongs to the query, so it only works on this form.** Putting a `#"` above a
+page. **It belongs to a query, so it only works on the one-query form.** Putting a `#"` above a
 model-level `##` tag fails the whole package load with "Object annotation not connected to any
-object", and a composite has no description as a result.
+object", so a dashboard has no description as a result.
 
-**Composite:** a list of views that already exist, each run separately into one grid. The tag is
-model-level (`##`) because there is no query of its own to hang a `#` tag on.
-
-```malloy
-##! experimental.givens
-## artifact { title="Seasonality" tiles=["scoped_sales -> sales_by_month", "scoped_sales -> sales_by_year", "scoped_sales -> seasonality"] dashboard_columns=3 }
-import { scoped_sales } from './_shared.malloy'
-import { products } from '../storefront.malloy'
-import { CATEGORY, SINCE } from '../givens.malloy'
-```
+### Where the filtering goes
 
-A composite has no query, so the filtering it applies must live in what it composes: a source that
+A dashboard has no query, so the filtering it applies must live in what it composes: a source that
 already has the givens applied. Put it in an untagged `dashboards/_shared.malloy`, which discovery
-treats as a shared include rather than a dashboard. **It has to apply every given the composite
-imports**: a given the composite imports but nothing references gets no control, silently, at reload
+treats as a shared include rather than a dashboard. **It has to apply every given the dashboard
+imports**: a given the dashboard imports but nothing references gets no control, silently, at reload
 200 with no warning. Note `SINCE` is a `date` rather than a `filter<>`, so it compares with `>=`
 rather than `~`. Save the include before you compile the dashboard that imports it, since an importer
 compiled against a sibling that is not on disk fails with an `import-error`.
@@ -141,42 +191,56 @@ source: scoped_sales is order_items extend {
 }
 ```
 
-Its tiles are equal-width (there is no per-tile colspan), and each one takes a single column, so
-**`dashboard_columns` is how many tiles you want per row**, not a number of twelfths. Three tiles want
-`dashboard_columns=3`. Setting it to 12 out of habit gives you twelve columns and three tiles a
-twelfth of the page wide. Use the single-query form when one tile deserves more room than the others.
+**`# dashboard { columns=N }` is the one spelling of the grid width**, on both forms, beside the
+artifact tag. Anything else inside the artifact tag is a package warning naming it, which is what you
+will see if you write `dashboard_columns=N`: nothing reads it, and the grid would otherwise fall back
+to the default width in silence.
 
-**Write `dashboard_columns=N` on a composite and `# dashboard { columns=N }` on a single query.**
-A composite forgives the mix, since both spellings feed the manifest field it
-lays out from, but **a single query tagged `dashboard_columns` silently loses its whole layout**, and
-the manifest reports the count either way: see "Losing the grid". A composite's tiles also keep their
-own field names on their axes and column headers, and the Layout section's remedy, inlining the view,
-is not open to you here: naming existing views is the whole point of the form. `tiles=` on a
-single-query artifact tag is dropped the same way, silently.
+A tile keeps its view's own field names on axes and column headers. `# label` titles the tile; to label
+what is inside it, label the fields in the view.
 
 ## Layout: the four tags that make a page line up
 
-This section is the **single-query** form only. A composite has no colspans and counts tiles per row,
-above. Cards and tiles share one grid, so copy this recipe, and use the same count on every
-single-query dashboard in the package so they read as one product:
+Cards and tiles share one grid, and the same four tags work on both forms: on a `# dashboard` query
+the renderer reads them off each nest, and on a dashboard's `tiles=[…]` Publisher reads them off the
+view each tile names. Copy this recipe and use the same count on every dashboard in the package so
+they read as one product:
 
 1. **`columns=12`** on the `# dashboard` tag. Twelve divides by 2, 3, 4 and 6, so a row is even with
    three cards or four.
 2. **A `# colspan` on every card and tile, summing to 12 per row.** Four cards at 3, three at 4, two
    tiles at 6, a full-width table at 12. Omit them and every item falls to a single column, a twelfth
-   of the width, which is too narrow for a line chart to draw in at all.
+   of the width, which is too narrow for a line chart to draw in at all. A colspan wider than
+   `columns` is clamped, and the package warnings say so.
 3. **`# break` on the first tile after the cards.** Otherwise it flows into the columns left beside
    the cards and the next tile wraps. Not needed per row: once a row sums to 12 the next item wraps
    on its own.
-4. **`# label="…"` on every nest and every aggregate**, including the aggregates inside a table
-   nest, whose column headers are field names too. The heading is otherwise the view's or field's
-   name, and a wide table full of `total_sales` and `order_item_count` is the most visible thing
-   between a rough page and a finished one. A view nested **by name** is the exception: you can label
-   the tile, but its own field names still reach the chart axes and the column headers, so inline it
-   if you want those labelled too.
+4. **`# label="..."` on every nest, tile view, and aggregate**, including the aggregates inside a table
+   nest, whose column headers are field names too. The heading is otherwise derived from the view's or
+   field's name, and a wide table full of `total_sales` and `order_item_count` is the most visible
+   thing between a rough page and a finished one. A view referenced **by name** is the exception: you
+   can label the tile, but its own field names still reach the chart axes and the column headers, so
+   label the fields in the view if you want those too.
+
+On a dashboard, all four go on the view a tile names, which is why a thin re-declaration
+(`view: revenue_trend is sales_by_month`) is the place to put them: the modelled view stays reusable
+and each page decides its own widths. `# subtitle="..."` and `# borderless` go there too and are the
+rest of the set; a tile reads all five exactly as a `# dashboard` nest child does.
+
+**Do not forget `columns=` itself.** What you get without it differs by form, and neither is the page
+you drew. On a dashboard it falls back to a narrow default and every colspan is clamped to it, which
+is the usual reason a page you laid out comes out one item per row, and the package warnings name it.
+On a `# dashboard` query there is no grid at all: the cards flow side by side at their natural widths
+and every colspan is ignored. No package warning says so, because the renderer reports it at query
+time. See "Losing the grid".
 
 Then the traps:
 
+- **A KPI row is authored differently on the two forms.** On a `# dashboard` query a top-level
+  `aggregate:` measure IS the card, and nesting a `# big_value` view to get one renders it embedded,
+  as full-width bars in a single tile. A dashboard has no top-level aggregates, since a tile is one
+  whole result, so there a `# big_value` view IS the KPI row and renders as one. This is the only
+  place the two forms need different Malloy for the same picture.
 - **No `# size=fill` on a dashboard tile.** Inside a dashboard it measures against the container the
   whole grid was handed, not the tile, so it yields a chart thousands of pixels tall. Tiles already
   size to their colspan.
@@ -196,9 +260,9 @@ The last two are upstream renderer behavior, cheap to work around in the model.
 
 The same tags govern a `# dashboard` **view** run in a notebook cell, since both surfaces render
 through the same code, so a view laid out this way looks the same in a cell as on a dashboard page.
-Height is the one thing the surface decides: a single-query dashboard renders at its natural height,
-a composite's tiles are each capped, and in a notebook a chart cell is capped and a table cell hugs
-its rows.
+Height is the one thing the surface decides: a one-query page renders at its natural height, a
+dashboard's tiles are each capped, and in a notebook a chart cell is capped and a table cell hugs its
+rows.
 
 ## The rules that actually bite
 
@@ -207,7 +271,7 @@ its rows.
   collides with an imported `regions` source).
 - **Importing a given is what makes it bindable.** Malloy's given namespace is per-file. A given the
   dashboard file does not import gets no control and cannot be sent to it, even when the `where:`
-  that references it lives up an import chain. A composite must import the givens its tiles use.
+  that references it lives up an import chain. A dashboard must import the givens its tiles use.
 - **A suggest's source or query has to resolve in the dashboard file too.** `suggest { source=products … }`
   means the dashboard imports `products`.
 - **A model-level `##` tag must be on one line.** Wrapping one always breaks it, but how you find
@@ -318,15 +382,14 @@ either, for a different reason.
 
 ## Losing the grid
 
-A single-query dashboard can come out with its layout wrong in two visibly different ways, and the
-reload is 200 and the manifest reports the column count you asked for in both.
+A one-query page can come out with its layout wrong in two visibly different ways, and the reload is
+200 and the manifest reports the column count you asked for in both.
 
-**Not a dashboard at all: one plain nested table**, every `# colspan` and `# break` dropped. Either
-you tagged a single query with `dashboard_columns=N`, which only a composite reads, or a `f'…'`
-filter literal in a `givens { … }`
-block shares a line with `# dashboard`. For the second, put `# dashboard` on its own line: writing it
-first on the line does not help, a plain `'Outerwear'` or a bare date is fine, and the composite form
-is immune because its layout comes from the manifest rather than a re-parse.
+**Not a dashboard at all: one plain nested table**, every `# colspan` and `# break` dropped, because a
+`f'…'` filter literal in a `givens { … }` block shares a line with `# dashboard`. Put `# dashboard` on
+its own line: writing it first on the line does not help, a plain `'Outerwear'` or a bare date is
+fine, and a `tiles=[…]` dashboard is immune because its layout comes from the manifest rather than a
+re-parse.
 
 **A dashboard, but nothing lines up**: you wrote `# colspan` without `columns=N`, so the items flow
 side by side at their natural widths instead of aligning to a grid.
@@ -355,7 +418,9 @@ Package warnings after a reload are the dashboard's test suite. Fix all of them:
 - `filters by given "X", which this file does not import, so no control is shown for it`: the trap
   under "Importing a given is what makes it bindable", which the lint now names for you, with the file
   to fix.
-- A tile that does not resolve to a real view, or a non-positive `dashboard_columns`.
+- A tile that does not resolve to a real view; a non-positive `# dashboard { columns }`; a tile view's
+  `# colspan` that is not a positive integer or is wider than the grid; and any property inside the
+  artifact tag Publisher does not read, `dashboard_columns=` included.
 
 Findings carry a `severity`, but `warn` is the ordinary default and tells you nothing about how bad
 one is. Read the text, not the severity and not the count. One message is worth recognising because
@@ -401,9 +466,8 @@ the warning list.
 - Each control renders as the widget you intended (a select shows options; a slider is a slider),
   and changing one changes the numbers.
 - If you added a `# drill`, you clicked it and landed where you meant to, with the given seeded.
-- On a single-query dashboard, every card and tile carries a colspan, each row's colspans sum to
-  `columns`, and the rows end flush with each other. On a composite, the tiles fill the row rather
-  than leaving a gap. Nothing is clipped, no tile is thousands of pixels tall, and no legend or card
+- Every card and tile carries a colspan, each row's colspans sum to `columns`, and the rows end flush
+  with each other. Nothing is clipped, no tile is thousands of pixels tall, and no legend or card
   label ends in `…`.
 
 ## Reference

package/skills/malloy-debug/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-debug
 description: Fix Malloy compile errors and understand error messages. Use when encountering errors in .malloy files, user says "fix this error", "malloy error", "compile error", "syntax error", or sees 20+ cascading errors.
-version: 0.1.9
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -14,11 +14,12 @@ SPDX-License-Identifier: MIT
 
 ## Get Diagnostics
 
-**Claude Code (in VS Code terminal):** Call `mcp__ide__getDiagnostics` with the file URI.
+Hosts expose errors differently, so take the best path you actually have:
 
-**VS Code Copilot / Cursor:** Use the `ReadLints` tool on the file path, or open the file and check lints in the editor.
+1. **An editor-diagnostics tool**, if your host offers one - call it on the file and read the errors straight out.
+2. **Otherwise, compile by running.** Run any query against the source with your query tool and read the error it returns. Every host that can run Malloy can do this, including chat surfaces with no editor.
 
-**Claude Code (standalone terminal):** No IDE diagnostics available. Ask the user to open the file in VS Code with the Malloy extension and report the errors.
+Only ask the user to open the file in an editor when you know they have the model open in one. On a hosted chat surface there is no local checkout to open, and the query path above is the one that works.
 
 ## Strategy
 
@@ -38,8 +39,10 @@ SPDX-License-Identifier: MIT
 | "Aggregate not allowed in where" | Use `having:` instead |
 | 20+ random errors | Backtick reserved word (`` `Date` ``, `` `Hour` ``, `` `number` ``) |
 | `Can't find field 'X' to set access modifier` | An `include {}` sits before the `extend { rename: }`. Rename first, then `include {}` naming the field by its new name (see `skill:malloy-gotchas-modeling` § Field Management) |
+| `IO Error: No files found that match the pattern "data/x.csv"` | Data-file path, not the model. Relative `duckdb.table()` paths resolve against the DuckDB `workingDirectory`; Publisher sets it to the package root, but a relative `workingDirectory` in `malloy-config.json` resolves against the process cwd. Make it absolute (see `skill:malloy-gotchas-modeling` § Relative Data-File Paths). The "not defined" errors under it are cascade, not real |
 | Import path errors | Check paths: `import "orders.malloy"`. All files should be in the same directory (flat layout) |
-| `from()` errors | Verify the source query returns the expected columns, check that imported sources are defined |
+| `unexpected 'from'` | `from()` was removed from the language. Use the query directly: `source: x is q extend {...}`, or `source: x is (q -> {...}) extend {...}` |
+| Query-based source errors | Verify the source query returns the expected columns, check that imported sources are defined |
 | "Cannot redefine 'X'" | Field already exists from query-based source (`-> { group_by, aggregate }`). Remove the dimension, add only NEW derived fields in `extend {}`. Use `include {}` to add `#(doc)` tags to existing fields. |
 
 ## Gotchas Checklist
@@ -123,4 +126,4 @@ a / b                           a / nullif(b, 0)
 | "Can't find source X" | Add `import "X.malloy"` at top of file (all files in same directory) |
 | Wrong import path | All `.malloy` files should be in the package root (flat layout). Use `import "orders.malloy"`, not `import "../sources/orders.malloy"` |
 | Circular imports | Source A imports Source B which imports Source A. Restructure to break the cycle |
-| `from()` "Can't find field" | Verify the source query's GROUP BY and aggregate fields match what you reference in `extend {}` |
+| Query-based source "Can't find field" | Verify the source query's GROUP BY and aggregate fields match what you reference in `extend {}` |

package/skills/malloy-define/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-define
 description: Propose a source plan and field definitions for a Malloy semantic model. Covers picking which sources to model and at what grain, then proposing the specific renames, dimensions, and measures per source, every proposal backed by querying the data.
-version: 0.1.9
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -160,7 +160,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 `#(filter)` annotations to declare server-side filterable dimensions where appropriate. 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 `given:` parameters to declare runtime-filterable dimensions where appropriate. `#(filter)` is deprecated in favour of native Malloy `given:` parameters. Do not add new `#(filter)` annotations; the two exceptions are `required` and `implicit`, which `given:` cannot cover yet. See `skill:malloy-model` § Legacy: Parameterizable Filters. 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.9
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

package/skills/malloy-document/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-document
 description: 'Add documentation with #(doc) tags to Malloy models so fields and sources are described in plain language. Use when user asks to "add documentation", "add doc tags", "document the model", or wants fields and sources described for natural-language search and discovery. For declaring parameterizable filters with #(filter), see the malloy-model skill. Filters are a runtime/modeling construct (governance, latency, correctness), not a documentation tag.'
-version: 0.1.9
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -15,7 +15,7 @@ Add `#(doc)` tags to describe sources and fields in plain language so they are e
 | Tag | Purpose | Goes on |
 |-----|---------|---------|
 | `#(doc)` | Plain-language description for natural-language search | source, dimension, measure, view, join |
-| `#(filter)` | Declare a parameterizable filter (runtime/modeling concern, see `malloy-model`) | source |
+| `#(filter)` | Deprecated, prefer `given:`. Parameterizable filter (runtime/modeling concern, see `malloy-model`) | source |
 
 `#(doc)` is a standard Malloy annotation. It documents a field or source with a human-readable description that downstream tools can surface and search against.
 
@@ -76,9 +76,11 @@ These are governed models: a threshold nobody confirmed is an assumption, and an
 
 Do not hedge measured facts: `avg_energy is avg(energy)` needs no caveat. Hedge only where a domain expert could reasonably choose differently.
 
-## #(filter): see `malloy-model`
+## #(filter): deprecated, see `malloy-model`
 
-`#(filter)` is also a `#(...)`-shaped annotation, but unlike `#(doc)` it's a **runtime/modeling construct**: it shapes governance, query latency, and correctness, not discoverability. The full reference (syntax, filter types, `required` / `implicit` flags, and when each applies) lives in `malloy-model` § Parameterizable Filters with `#(filter)` alongside the other source-authoring constructs.
+`#(filter)` is deprecated in favour of native Malloy `given:` parameters. Do not add new `#(filter)` annotations; the two exceptions are `required` and `implicit`, which `given:` cannot cover yet. See `skill:malloy-model` § Legacy: Parameterizable Filters.
+
+`#(filter)` is also a `#(...)`-shaped annotation, but unlike `#(doc)` it's a **runtime/modeling construct**: it shapes governance, query latency, and correctness, not discoverability. The full reference (syntax, filter types, `required` / `implicit` flags, and when each applies) lives in `malloy-model` § Legacy: Parameterizable Filters alongside the other source-authoring constructs, next to the `given:` guidance that replaces it.
 
 One rule worth knowing here: filters live on the source, never on the consumer. Ad-hoc reports and notebooks that import a source inherit its filters automatically; they do not (and cannot) declare new ones.
 

package/skills/malloy-getting-started/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-getting-started
 description: First steps for using a Malloy Publisher deployment through its MCP tools. Use when connecting to Publisher for the first time, when you do not yet know the available environments, packages, or models, or when a user asks what data they can explore. Covers verifying the server, discovering data with malloy_getContext, and running a first grounded query.
-version: 0.1.9
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -29,6 +29,56 @@ Two escape hatches worth knowing:
 
 When a user is present, do not route around it by calling the REST API with curl. It appears to work, so the user never learns their session is missing the tools, and you lose what they are for: grounded discovery instead of guessed names, `malloy_compile` instead of throwaway queries, and `malloy_reloadPackage` instead of a restart. Say the tools are missing and let the user fix it in five seconds. Running unattended, with nobody who can reconnect you, is different: there the REST API is the supported interface, not a workaround. Discovery, query, compile, and reload all have REST equivalents (`malloy_searchDocs` and `malloy_getContext`'s plain-English ranking do not; read the bundled skills for syntax and ground from model metadata instead); the running server serves the full spec at `http://localhost:4000/api-doc.yaml`, and AGENTS.md carries the endpoint map.
 
+## 0.5 Ask whether they also use the CLI or the VS Code extension
+
+Publisher is often not the only thing reading the model. The Malloy CLI (`malloy-cli`) and the VS
+Code extension compile the same files, and they do **not** get their connections from
+`publisher.config.json` - they read `malloy-config.json`, found by walking up from the file being
+compiled. So a package that Publisher serves correctly can fail to compile in the editor, on the
+same machine, from the same files.
+
+Ask before the user finds out the hard way:
+
+> Are you also using the Malloy CLI or the VS Code extension on this package?
+
+If yes, and the package reads **local data files**, it needs a `malloy-config.json`. Publisher
+resolves a relative `duckdb.table('data/x.csv')` against the package root on its own, so nothing is
+configured for it; the other two hosts resolve it against the DuckDB connection's
+`workingDirectory`, which has to be set.
+
+**Make that path absolute.** A relative `workingDirectory` is resolved against the process's current
+directory, not the config file's directory and not the VS Code workspace root, so the same config
+compiles from one directory and fails from another:
+
+```json
+// malloy-config.json, beside the model
+{
+  "connections": {
+    "duckdb": {
+      "is": "duckdb",
+      "workingDirectory": "/abs/path/to/package",
+      "securityPolicy": "none"
+    }
+  }
+}
+```
+
+Point it at the directory the model's table paths are written relative to - the one holding `data/`.
+Leave the model's own paths relative so Publisher still serves it; only the config carries the
+absolute path. When this is wrong the editor reports `IO Error: No files found that match the
+pattern "data/x.csv"` on the `source:` line, followed by a "not defined" error for every field of
+that source; those are cascade, not real. The `malloy-gotchas-modeling` skill covers the mechanism
+under § Relative Data-File Paths.
+
+**Remote Credible connections are a different case.** With the Credible extension running and signed
+in, the data is reached through a `publisher` proxy connection - the connection type that forwards
+SQL to a remote Publisher dataplane, and the same type the CLI and the VS Code extensions use - and
+the extension supplies it, so there is nothing to hand-write and no `workingDirectory` involved.
+`workingDirectory` only ever matters for local files that DuckDB opens itself. Worth knowing: those
+access tokens are user-scoped and short-lived, and nothing refreshes them mid-session, so queries
+that start failing auth after a long session mean the token expired, not that the model broke. See
+`docs/connections.md` § Publisher proxy connections.
+
 ## 1. Discover what exists (never guess names)
 
 `malloy_getContext` is progressive. Call it with as much as you know: