@malloy-publisher/skills 0.1.10 → 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.10",
+   "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.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

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.10
+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.10
+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.10
+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 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. See `skill:malloy-model` § Legacy: Parameterizable Filters. 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: 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.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

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.10
+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.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

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.10
+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.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

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.10
+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.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

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.10
+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:

package/skills/malloy-gotchas-modeling/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-gotchas-modeling
 description: Common Malloy modeling mistakes and how to avoid them. Read BEFORE writing source definitions, dimensions, measures, or joins. Covers reserved words, NULL checks, date functions, type casts, field management (extend except/accept/rename vs include public/internal/private), and query-based source gotchas.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -282,6 +282,46 @@ source: facts is conn.table('orders') -> { group_by: user_id, aggregate: total i
 
 If a project's standards file specifies a stricter policy (e.g., a `search_malloy_docs` rationale comment requirement above every `conn.sql()` block), defer to that.
 
+## Relative Data-File Paths: Set an Absolute `workingDirectory`
+
+`duckdb.table('data/x.csv')` is resolved against the DuckDB connection's `workingDirectory`, not
+against the model file. Publisher sets that to the package root, so relative paths work there with
+no config at all. Every other host reads it from `malloy-config.json`, and **a relative value there
+is resolved against the process's current directory** - not the config file's directory, and not the
+VS Code workspace root. `canonicalizeConfigPath` in `malloy-db-duckdb/src/duckdb_config.ts` calls
+`canonicalizePath` with no `baseDirectory`, which is a bare `path.resolve(input)`.
+
+So the same config works or fails depending on which directory the editor or shell was launched
+from. That is why this breaks intermittently and appears to be a model bug.
+
+```json
+// WRONG: resolved against the process cwd, so it works from the repo root and
+// fails from anywhere else - including however your editor happened to launch
+{"connections": {"duckdb": {"is": "duckdb", "workingDirectory": "malloy"}}}
+
+// RIGHT: absolute, so the cwd cannot change the answer
+{"connections": {"duckdb": {"is": "duckdb", "workingDirectory": "/abs/path/to/pkg"}}}
+```
+
+Point it at the directory the model's table paths are written relative to - the package root, the
+one holding `data/`. Keep the model's paths relative (`data/x.csv`) so Publisher still serves it;
+only the config carries the absolute path.
+
+**The symptom, and the cascade.** One `IO Error` at the `source:` line, then a "not defined" error
+for every field of that source:
+
+```
+line 87: IO Error: No files found that match the pattern "data/product_usage.csv"
+line 91: 'org_slug' is not defined
+line 93: Reference to undefined value active_users
+```
+
+Those field errors are not real. Fix the first error and they all go. Do not start renaming
+columns.
+
+**Check the config before the model** when a source that Publisher queries fine fails in the editor
+or CLI with a missing-file error. The model is the same file; the resolution base is not.
+
 ## JSON Files: Read Them In Place Like CSV
 
 ```malloy
@@ -407,5 +447,5 @@ Call `search_malloy_docs` BEFORE first use of any of these. Don't guess the synt
 - Window functions (`calculate`)
 - `percentile` or statistical functions: but see the hard limit above, raw-SQL aggregates (`sql_number` / `is_aggregate` / `percentile_cont!`) do **not** compile as measures in this build; there is no scalar median (`stddev` is the exception and does work as a measure)
 - Time interval functions (`days()`, `months()`): always `unit(start to end)`, and calendar units need date operands (see above)
-- Query-based sources (`from()`)
+- Query-based sources (`source: x is (q -> {...}) extend {...}`; `from()` was removed and no longer parses)
 - `!` operator / `sql_number()`

package/skills/malloy-gotchas-queries/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-gotchas-queries
 description: Common Malloy query and view mistakes. Read BEFORE writing views, queries, or notebooks. Covers chart constraints, aggregate filters, joined field aliasing, method syntax, and time truncation vs extraction.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

package/skills/malloy-gotchas-rendering/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-gotchas-rendering
 description: Common Malloy renderer annotation mistakes. Read BEFORE adding chart annotations, formatting tags, or building dashboards. Covers tag syntax, scale rules, sparkline setup, and big_value patterns.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

package/skills/malloy-html-data-app-embedding/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-html-data-app-embedding
 description: Embed an in-package HTML data app into a host page or another application, including auto-sizing and auth. Read when embedding a Publisher page via Publisher.embed.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

package/skills/malloy-html-data-app-runtime/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-html-data-app-runtime
 description: Write the JavaScript that drives an in-package HTML data app, calling Publisher.query, building queries from filter state, and handling results and errors. Read before writing the page's data code.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

package/skills/malloy-html-data-apps/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-html-data-apps
 description: Build or modify an in-package HTML data app for a Malloy Publisher package (a public/ directory the package serves). Use when the user wants a hand-authored HTML dashboard or web page backed by a package's Malloy models, with no build step.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

package/skills/malloy-lookml-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-lookml-review
 description: Analyze LookML files as prior art for Malloy modeling. Used during Step 1 (DISCOVER) when .lkml files are present. Coordinates reference files that extract business logic, relationships, and curation decisions. Works with or without a database connection.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

package/skills/malloy-lookml-review/reference/_concepts.md

@@ -41,7 +41,7 @@ Reference table for translating LookML constructs to Malloy. Referenced by multi
 | `+view:` (refinement) | User decides: consolidate or `extend` | Malloy `extend` serves the same purpose |
 | `derived_table: { sql: ... }` (perf-only) | Use base table directly | PDT optimization is Looker-specific |
 | `derived_table: { sql: ... }` (transformation) | Flag for user | Recommend base table + dims or upstream dbt |
-| `derived_table: { explore_source: ... }` (NDT) | `from(source -> { group_by:, aggregate: }) extend { }` | Computed source pattern |
+| `derived_table: { explore_source: ... }` (NDT) | `(source -> { group_by:, aggregate: }) extend { }` | Computed source pattern |
 | `value_format: "$#,##0.00"` | `# currency` | Map to Malloy render tags |
 | `value_format: "0.00%"` | `# percent` | Map to Malloy render tags |
 | `value_format_name: decimal_2` | `# number="0.00"` | Map to Malloy render tags |

package/skills/malloy-lookml-review/reference/build-derived-tables.md

@@ -12,7 +12,7 @@ SPDX-License-Identifier: MIT
 ```
 derived_table:
 ├── explore_source: → NDT path
-│   ├── Simple aggregation → Malloy from() extend {}
+│   ├── Simple aggregation → Malloy (query) extend {}
 │   ├── With derived_column: (window functions) → Malloy window function patterns
 │   ├── Chained NDTs → dependency ordering, multi-stage computed source
 │   └── With bind_filters → flag, no direct Malloy equivalent
@@ -25,10 +25,12 @@ derived_table:
 
 ### Simple Aggregation NDT
 
-Express the aggregation as a Malloy query, then build a source from it:
+Express the aggregation as a Malloy query, then build a source from it by
+wrapping the query in parentheses and extending it (`from(...)` was removed from
+the language and no longer parses):
 
 ```malloy
-source: source_name is from(
+source: source_name is (
   base_source -> {
     group_by: group_field
     aggregate:

package/skills/malloy-materialization/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-materialization
 description: Add and debug Malloy Persistence materializations in a package - persist an expensive source so queries read a pre-built table. Read this whenever the user wants to materialize a source, add a persist annotation, speed up a slow source, or asks why a persist source isn't building.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -124,13 +124,28 @@ bound, only the first is:
 
 - **`materialization.freshness` `{ "window": "24h", "fallback": "live" }` is the bound.** The serve path
   re-checks freshness per query, so once the artifact ages past the window it drops out of the serving set
-  and the query recomputes live, correctly filtered - whether or not a rebuild ever lands. Two details
+  and the query recomputes live, correctly filtered - whether or not a rebuild ever lands. Three details
   decide whether you actually get that. **`fallback` must be `live`**: under `stale_ok` a stale artifact
   keeps being served, which voids the bound, and window and fallback resolve *independently* per layer,
-  so a package-level `stale_ok` silently defeats a window you set on the source. And prefer the
+  so a package-level `stale_ok` silently defeats a window you set on the source. That is a statement about
+  **layers**, which do not combine - not about siblings, below. Prefer the
   **per-source** spelling `#@ persist name="..." freshness.window="24h" freshness.fallback="live"` over
   the package-wide `materialization.freshness` key: the gated source is what needs the bound, and setting
-  it package-wide forces every other persisted source to recompute once stale too.
+  it package-wide forces every other persisted source to recompute once stale too. And **a
+  content-identical sibling shares the artifact, so it shares the window**: reuse is keyed on the
+  content-addressed `sourceEntityId`, which folds the connection and the SQL but *not* the source name, so
+  two persist sources whose bodies compute the same SQL resolve to one table carrying one freshness
+  policy. The tightest window any of them declares governs all of them - a sibling declaring nothing
+  cannot loosen yours, and yours pulls that sibling's reads off the table once it lapses. A sibling's
+  `stale_ok` cannot void your bound either: the fold keeps whichever fallback bounds staleness, so the
+  layer rule above does not carry over here. If two sources need genuinely different windows, give them
+  genuinely different SQL.
+
+  Both of those are properties of the **host** that assembles the manifest, not of the annotation. Where
+  the host does not fold, which sibling's policy reaches the wire is unspecified; and a host that folds at
+  manifest-assembly time typically applies it when a version's manifest is next published rather than
+  retroactively to manifests already distributed - so you can declare the window correctly and not have it
+  in force yet.
 - **A cron alone is not a bound.** A failed build or a stopped scheduler leaves the source serving its old
   decisions indefinitely. `freshness` and `schedule` are mutually exclusive; for a gated source, take the
   window.

package/skills/malloy-materialization-tuning/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-materialization-tuning
 description: Optimize a package's Malloy Persistence materializations for cost and performance using the malloy-pub CLI and the materialization history. Recommend what to persist, what to stop persisting, and how to schedule/scope it. Use when the user asks to make a package cheaper or faster, tune persistence, decide what to materialize, or review persist/schedule choices.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

package/skills/malloy-model/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-model
 description: Build Malloy semantic models with base source and joined source files. Use when creating or modifying .malloy files, user asks to "create a malloy model", "add dimensions", "add measures", "create a source", or any Malloy model authoring task.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -112,10 +112,12 @@ extend {
 
 ### Computed Source (from Query)
 
+Wrap the query in parentheses and extend it. `from(...)` was removed from the language and no longer parses (`unexpected 'from'`).
+
 ```malloy
 import "orders.malloy"
 
-source: user_order_facts is from(
+source: user_order_facts is (
   orders -> {
     group_by: customer_id
     aggregate:

package/skills/malloy-model-as-you-go/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-model-as-you-go
 description: After answering a data question, write down what the answer assumed so the next reader can trust the number. A field with a #(doc) in the model when you can edit it, an extend in the notebook when you can only author reports, or a stated assumption plus a Malloy snippet when you can only chat. Use after every answered question that rested on a judgment call, and whenever a question is asked against tables that have no model yet.
-version: 0.1.10
+version: 0.1.12
 ---
 
 <!--

package/skills/malloy-modeling/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-modeling
 description: Build semantic models with Malloy for the Malloy Publisher. Read this skill whenever the user asks about modeling data or specifically mentions Malloy.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

package/skills/malloy-notebook-chat/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-notebook-chat
 description: Steps to follow when the chat is bound to a notebook or saved report. The notebook's cells are the agent's primary context, answer from it, run its queries, and only reach for get_context when the user asks about something outside it.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -21,5 +21,5 @@ Steps to follow when the user asks a question:
   - If the question can be answered by a query already in the notebook, run that cell's query via `execute_query` (exact code, or a minor variation like adding a filter or changing a group_by).
   - If the question asks for an analysis that is clearly NOT in the notebook (new source, different package, different domain), then, and only then, call `get_context` to explore.
   - Do NOT call `get_context` as a default first step. The notebook already tells you what's available.
-4. Before writing or modifying a query, read the `malloy-queries` skill for syntax patterns. When you tweak a query (add a `where:` clause, change a `group_by`, etc.), do NOT add `#(filter)` annotations: filters live on the source's model file and are inherited by this notebook automatically. Query-level `where:` filtering inside a cell is fine; declaring new filter UI is a model change, not a chat-time change.
+4. Before writing or modifying a query, read the `malloy-queries` skill for syntax patterns. When you tweak a query (add a `where:` clause, change a `group_by`, etc.), do NOT add `#(filter)` annotations or `given:` declarations: both live on the source's model file and are inherited by this notebook automatically. Query-level `where:` filtering inside a cell is fine; declaring a new runtime parameter is a model change, not a chat-time change.
 5. Summarize insights from query results. Do not echo raw rows: the user sees them rendered.

package/skills/malloy-notebooks/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-notebooks
 description: Create Malloy notebooks (.malloynb) for interactive dashboards and data stories. Use when user asks to "create a notebook", "make a dashboard notebook", "write a malloynb", "data story", or needs to build reports/visualizations.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

package/skills/malloy-patterns/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-patterns
 description: Index of Malloy documentation topics. Use to discover what's available in search_malloy_docs. Covers language reference (sources, queries, views, fields, aggregates, joins, filters, expressions, functions), common patterns (YoY, cohorts, percent of total), rendering, and experimental features.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

package/skills/malloy-phrase-detection/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-phrase-detection
 description: How to construct search targets for the get_context tool. Covers target-type classification and non-obvious decomposition patterns. Read the tool description for field definitions and the end-to-end workflow.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

package/skills/malloy-publish/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-publish
 description: Package Malloy models for serving by Malloy Publisher. Use when user asks to "publish", "package", "deploy", or wants to share models with others.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

package/skills/malloy-queries/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-queries
 description: Malloy query patterns, syntax rules, and chart annotation reference. Consult before writing or debugging any query. Covers dates, aggregates vs dimensions, join paths, filters, string matching, and common error patterns.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

package/skills/malloy-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-review
 description: Malloy semantic-model code review. Invoke when the user asks to review, audit, or critique a `.malloy` file, a folder of Malloy models, or a GitHub PR that touches Malloy. Enforces project modeling standards and emits a navigable review file.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.

package/skills/malloy-review/reference/rubric-structure.md

@@ -29,7 +29,7 @@ For every rule, the linked instruction-skill section is the canonical source for
 - **Why this isn't a correctness rule.** The Malloy compiler auto-synthesizes a UUID-based `__distinct_key` for any `join_one:` target without a declared PK (`packages/malloy/src/model/field_instance.ts:644-670`, `query_query.ts:946-951`), so symmetric aggregation is correct either way, see the C-07 entry in `rubric-correctness.md`'s "Rules we dropped" section. The `with` shortcut, which DOES require a declared PK, errors at compile time and surfaces as a diagnostic. The actual silent-correctness hazard ("declared PK isn't actually unique in the data") is `rubric-correctness.md` § C-12.
 - **What this rule catches.** A discoverability / hygiene gap: when a source has a natural primary key, declaring it lets downstream code use the `with` shortcut, makes grain explicit in the model, and gives tooling a stable identifier per row. Treat as a recommendation, not a merge gate.
 - **Detection:** for every `source:` declaration, check whether its body contains a `primary_key:` clause. Skip flagging when:
-  - The source is a query-based / computed source (`source: x is t -> {...}` or `source: x is from(...)`) where grain is determined by the `group_by` columns, declaring a `primary_key:` on the result is fine but not required.
+  - The source is a query-based / computed source (`source: x is t -> {...}` or `source: x is (t -> {...}) extend {...}`) where grain is determined by the `group_by` columns, declaring a `primary_key:` on the result is fine but not required.
   - The source represents an event/log table or a denormalized analytical source where no natural PK exists. Both situations are legitimate; the LLM should recognize them and skip the finding.
 - **Fix (when the source does have a natural PK):** declare it, `primary_key: <col>` inside `extend {}`. When there isn't a natural PK, leave it undeclared; if the absence is non-obvious, a one-line `#(doc)` on the source explaining the grain helps future readers.
 - **See:** `skill:malloy-model` § Key Rules · `rubric-correctness.md` § C-12 (the related correctness rule that checks whether a declared PK is actually unique in the data) · `rubric-style.md` § Y-03 (`join_one:` style consistency, which is the other consequence of declared-vs-undeclared PKs)

package/skills/malloy-scope/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-scope
 description: Present discovery findings and propose an analytical scope before modeling. Use after inspecting a package's model and data, to classify tables and recommend an analytical focus the user can pick from.
-version: 0.1.10
+version: 0.1.12
 ---
 <!--
 Copyright (c) Credible Data Inc.