@malloy-publisher/skills 0.1.33 → 0.1.34

package/package.json

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

package/skills/eval-diagnose/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eval-diagnose
 description: 'Diagnose why a scored answer failed and who owns the fix, then cluster the failures by shared root cause. Walk dataset, agent-call, get_context/model, get_context/retrieval, construction, then model-definition. Append issue events to the file ledger, linked by traceId, one per cluster. Use after eval-answer, when triaging a run, or before changing a model. Does not edit the model (eval-improve).'
-version: 0.1.33
+version: 0.1.34
 ---
 
 # 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.33
+version: 0.1.34
 ---
 
 # 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.33
+version: 0.1.34
 ---
 
 # 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.33
+version: 0.1.34
 ---
 
 # 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.33
+version: 0.1.34
 ---
 
 # The Evaluation Loop

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

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

package/skills/eval-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.33
+version: 0.1.34
 ---
 
 # Report a Run

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.33
+version: 0.1.34
 ---
 <!-- Copyright (c) Credible Data Inc. SPDX-License-Identifier: MIT -->
 

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.33
+version: 0.1.34
 ---
 
 <!-- Copyright (c) Credible Data Inc. SPDX-License-Identifier: MIT -->
@@ -110,4 +110,8 @@ This is different from a genuine ambiguity about WHICH metric they meant; there,
 
 Answer in plain language, lead with the number that was asked for, and show the supporting rows. State the assumptions you made (filter values, date ranges, any ad-hoc field). Acknowledge caveats the verification step surfaced, and say so if you could not fully verify something. When the result lends itself to a chart, say which Malloy render tag fits and why (load `skill:malloy-charts`), for example `# bar_chart` for a category breakdown or `# line_chart` for a trend over time.
 
-End with a short **Next steps**: one or two specific deeper analyses the data could support (a finer breakdown, a comparison, a different angle), concrete to what you just found. If a notebook-authoring skill is available to you, you can also offer to capture the analysis as a Malloy notebook so it can be re-run and shared.
+**A table in your answer uses the result's own columns and values.** Show the rows that carry the finding, and add no column the query didn't return: a rank, a share or a difference you work out by hand is a number nothing checked. When a derived figure matters, compute it in the query and show that.
+
+**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 that it returned N of M sources, never present the N as everything: if the result carries a `next_offset`, pass it back as `offset` for the rest; if it doesn't, do what its warning says (narrow the search, or 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 them, and don't add a total it didn't report unless the user asked for one; 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 (a finer breakdown, a comparison, a different angle), concrete to what you just found. Keep it unless your host's instructions say it shows follow-up suggestions of its own: those then carry the next steps, and a section repeating them reads as a second answer. If a notebook-authoring skill is available to you, you can also offer to capture the analysis as a Malloy notebook so it can be re-run and shared.

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

@@ -1,7 +1,7 @@
 ---
 name: malloy-analysis-pitfalls
 description: Checks to run on a query and its numbers before a result is presented - wrong grain, fan-out, invented field names, mismatched filters, count vs distinct. The common data-analysis pitfalls.
-version: 0.1.33
+version: 0.1.34
 ---
 <!-- Copyright (c) Credible Data Inc. SPDX-License-Identifier: MIT -->
 

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.33
+version: 0.1.34
 ---
 <!--
 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 query cells. There is no dedicated report tool: you author the notebook directly. 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 `.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. There is no dedicated report tool: you author the notebook directly. 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`.
 
 > **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.
 
@@ -34,6 +34,8 @@ Markdown cells own narrative; query cells own a single Malloy query whose chart
 
 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 `#"`.
 
+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.
+
 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:
 
 ```malloy

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.33
+version: 0.1.34
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -185,7 +185,7 @@ view: analysis_summary is {
 
 Document insights as view descriptions: `#(doc) Top 10% of customers drive 62% of revenue.`
 
-Present to user: top 3-5 insights, supporting views, open questions, and recommended next steps.
+Present to user: top 3-5 insights, supporting views, open questions, and recommended next steps (unless your host's instructions say it shows follow-up suggestions of its own, which then carry them).
 
 **Ready to formalize?** Hand off to the modeling skill's "Starting from Analysis" workflow (`skill:malloy-model`).
 
@@ -235,7 +235,7 @@ For complete chart reference including scatter_chart, shape_map, sparklines, and
 
 # NOTEBOOKS (.malloy)
 
-A notebook is `notebooks/<slug>.malloy` with `## artifact { kind=notebook title="..." }`. Prose is `##(markdown) text` or a `##|(markdown)` ... `|##` block; each `run:` is a query cell.
+A notebook is `notebooks/<slug>.malloy` with `## artifact { kind=notebook title="..." }`. The format to author is a one-column layout of tiles: `tiles=[…]` in the tag lists prose blocks (`intro { kind=text }`, body in a `##|(markdown) intro` ... `|##` block) and `"source -> view"` queries, and `skill:malloy-notebooks` has the full format. The example below is the older cell form, which Publisher still reads: prose is `##(markdown) text` or a `##|(markdown)` ... `|##` block, and each `run:` is a query cell.
 
 ```malloy
 ## artifact { kind=notebook title="Sales analysis" }
@@ -250,7 +250,7 @@ run: order_analysis -> summary
 
 **A `.malloy` notebook compiles as a model**, so the linter and `/compile` report its errors before you save. An existing `.malloynb` is not covered: its errors show only when a cell runs. Never write a new `.malloynb`.
 
-A notebook is also the home for a polished, narrated report: alternate `##(markdown)` prose (the story) with `run:` cells (the views), and let each `run:` carry its chart tags. For the full format and report-authoring conventions, see `skill:malloy-notebooks`.
+A notebook is also the home for a polished, narrated report: alternate prose (the story) with queries (the views), and let each view carry its chart tags. For the full format and report-authoring conventions, see `skill:malloy-notebooks`.
 
 ### Interactive Filters
 

package/skills/malloy-charts/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-charts
 description: Chart selection for a Malloy view, plus the renderer reference for bar_chart, line_chart, scatter_chart, maps and layouts. For choosing a visualization or adding a chart annotation.
-version: 0.1.33
+version: 0.1.34
 ---
 <!--
 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.33
+version: 0.1.34
 ---
 
 <!--
@@ -128,18 +128,20 @@ Three things the form costs, so you are not surprised by them:
 - **Filtering lives on the tiles**, not on the page: each view's `+ { where: ... }` names the
   controls it answers to. Below is why, and the one thing that does not work.
 
-### Text tiles: prose between tiles (decided, not rendered yet)
+### Text tiles: prose between tiles
 
-Prose between tiles is a named `(markdown)` block that `tiles=` lists with `kind=text`:
+Prose between tiles is a named `(markdown)` block that `tiles=` lists with `kind=text`; it renders as a tile of its own, and its body is markdown:
 
 ```malloy
-## artifact { title="Storefront overview" tiles=[intro { kind=text colspan=12 }, "overview -> kpis"] } dashboard { columns=12 }
+## artifact { title="Storefront overview" tiles=[intro { kind=text colspan=6 break }, "overview -> kpis"] } dashboard { columns=12 }
 ##|(markdown) intro
 ## How to read this page
 |##
 ```
 
-The name is one bare word on the opener line, the body starts on the next line, and the `|##` closer sits at the opener's column. Keep the parentheses: `##|markdown` draws a malformed-route warning. Publisher does not render text tiles yet, so a listed block is left out of the page and the lint says so; write one when the page needs the prose, and expect the tile to appear once rendering ships. A `(markdown)` block that no `tiles` entry names is a lint finding too, so delete it rather than leave it. The dashboard's own description is separate: the unnamed `"` notes above `## artifact`. Earlier spellings are still read: `##|(text) name` is a text tile, like `##|(markdown) name`. Write `(markdown)`.
+The entry is `name { kind=text colspan=6 break }`: `colspan` and `break` lay it out like a query tile, and nothing else on the entry is read. The name is one bare word on the opener line, the body starts on the next line, and the `|##` closer sits at the opener's column. A heading goes inside the block, because a bare `## Heading` line is a model tag. Keep the parentheses: `##|markdown` draws a malformed-route warning. The lint reports an entry with no block, a block written twice, and a `(markdown)` block that no `tiles` entry names, so delete the last rather than leave it. The dashboard's own description is separate: the unnamed `"` notes above `## artifact`. Earlier spellings are still read: `##|(text) name` is a text tile, like `##|(markdown) name`. Write `(markdown)`.
+
+In the API a text tile has `kind: "text"`, a `name` and `markdown`, and no `query`; code that runs a dashboard's tiles skips it.
 
 ### Also served: `# artifact` on a `query:`
 
@@ -361,8 +363,9 @@ Two per-dashboard options on the artifact tag:
   that a reader notices two round trips.
 - `givens { CATEGORY=f'Outerwear' }` sets starting values, not a redeclaration. A URL parameter wins.
 
-A notebook takes both at the file level, as `## autorun=false` and `## givens { CATEGORY=f'Outerwear' }`,
-and behaves identically.
+A served `.malloy` notebook takes both inside its `## artifact { … }` tag, as `autorun=false` and
+`givens { CATEGORY=f'Outerwear' }`, and behaves identically. A file-level `## autorun=false` does
+nothing there; only a legacy `.malloynb` reads options at the file level.
 
 ## Drill
 

package/skills/malloy-data-app-design/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-data-app-design
 description: Decide what a data app should be before building it - who opens it, the decision it serves, which archetype it is, the forms that answer its questions, and the depth (drill-down, shared scope, linkable state) that makes it a tool rather than a page of charts. Read at the START of any data-app request, before scaffolding a package or writing a tile, and when an existing app feels flat, generic, or like a list of every view in the model.
-version: 0.1.33
+version: 0.1.34
 ---
 <!--
 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.33
+version: 0.1.34
 ---
 <!--
 Copyright (c) Credible Data Inc.

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.33
+version: 0.1.34
 ---
 <!--
 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.33
+version: 0.1.34
 ---
 <!--
 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 runtime filters, declare given: parameters (see the malloy-model skill); #(filter) is deprecated. Filters are a runtime/modeling construct (governance, latency, correctness), not a documentation tag.'
-version: 0.1.33
+version: 0.1.34
 ---
 <!--
 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 get_context, and running a first grounded query.
-version: 0.1.33
+version: 0.1.34
 ---
 <!--
 Copyright (c) Credible Data Inc.

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

@@ -1,7 +1,7 @@
 ---
 name: malloy-gotchas-modeling
 description: Common Malloy modeling mistakes, for writing source definitions, dimensions, measures or joins - reserved words, NULL checks, date functions, type casts, field management (extend except/accept/rename vs include public/internal/private), query-based source gotchas.
-version: 0.1.33
+version: 0.1.34
 ---
 <!--
 Copyright (c) Credible Data Inc.

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

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

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

@@ -1,7 +1,7 @@
 ---
 name: malloy-gotchas-rendering
 description: Common Malloy renderer mistakes, for adding chart annotations and formatting tags or building dashboards - tag syntax, scale rules, sparkline setup, big_value patterns.
-version: 0.1.33
+version: 0.1.34
 ---
 <!--
 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.33
+version: 0.1.34
 ---
 <!--
 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: The JavaScript that drives an in-package HTML data app - calling Publisher.query, building queries from filter state, handling results and errors. For writing the page's data code.
-version: 0.1.33
+version: 0.1.34
 ---
 <!--
 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.33
+version: 0.1.34
 ---
 <!--
 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.33
+version: 0.1.34
 ---
 <!--
 Copyright (c) Credible Data Inc.

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

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.33
+version: 0.1.34
 ---
 
 <!--

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.33
+version: 0.1.34
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -200,6 +200,8 @@ gets unwieldy.
 - **Check for duplicate rows** before building measures
 - When both a combined table (all types) and filtered/split tables exist, prefer the split tables
 - **DRY: define measures/dimensions in base source files, not inline in views**
+- **Lay out a new file the same way throughout**: two-space indentation, no tabs, one blank line between top-level declarations (consecutive `import` lines stay together), no trailing whitespace, and a long line broken after a comma or before an operator, at whatever width the project keeps to. In a project whose files already use another layout (tabs, four spaces), a new file matches them.
+- **An edit keeps the file's own layout**: change only the lines the request needs, and never reindent or rewrap a line you weren't asked to change, so the diff shows the change and nothing else.
 - **Never write a threshold, tier boundary, or bucket cutoff you chose yourself.** Every boundary in a `pick` expression or filtered measure is user-supplied, distribution-derived (query `min`/`p25`/`p50`/`p75`/`p95` first and show the evidence; see `skill:malloy-define` § Data-driven proposals), or explicitly flagged as an assumption in its `#(doc)`. A hardcoded cutoff nobody confirmed is a business decision shipped as fact.
 
 ## Parameterizing sources with `given:` (preferred)
@@ -362,9 +364,9 @@ Load the relevant reference file when you encounter these scenarios:
 
 Step complete. Output: base source files (`.malloy`, one per table) and joined source files (`.malloy`, one per analytical domain).
 
-**Suggest next steps to the user:**
+**Suggest next steps to the user**, unless your host's instructions say it shows follow-up suggestions of its own:
 
-- Open the model in the browser to see it live: `http://localhost:4000/<environmentName>/<packageName>` for the package, or `http://localhost:4000/<environmentName>/<packageName>/<modelPath>` for a single model file. First confirm the running server actually serves this package (it is in the loaded `publisher.config.json`, or mounted live with `--server_root . --watch-env <env>`); a package the server has not loaded returns a 404, so do not hand over a link to a package that was just authored but never loaded.
+- Open the model to see it live. On a local Publisher server that is `http://localhost:4000/<environmentName>/<packageName>` for the package, or `http://localhost:4000/<environmentName>/<packageName>/<modelPath>` for a single model file. First confirm the running server actually serves this package (it is in the loaded `publisher.config.json`, or mounted live with `--server_root . --watch-env <env>`); a package the server has not loaded returns a 404, so do not hand over a link to a package that was just authored but never loaded.
 - Build a notebook with interactive filters over the model (see `skill:malloy-notebooks`).
 - Run analysis questions against the model (see `skill:malloy-analysis`).
 - When you're ready to serve the model, publishing is out of scope for open-source Publisher v1: self-hosters commit the package to git and use their host's publish path.

package/skills/malloy-model/reference/analysis-to-model.md

@@ -11,7 +11,7 @@ When you've been doing analysis, writing queries, building views, creating noteb
 
 ## Step 1: IDENTIFY, what belongs in a model?
 
-Scan your analysis `.malloy` files and notebooks (`notebooks/*.malloy`, or an existing `.malloynb`). A `notebooks/*.malloy` with an `## artifact { kind=notebook }` tag is a notebook, not a model file to restructure: lift its reusable definitions into a model and leave the notebook to import them. For each dimension, measure, join, or calculation, ask: **is this a reusable building block?**
+Scan your analysis `.malloy` files and notebooks (`notebooks/*.malloy`, or an existing `.malloynb`). A `notebooks/*.malloy` with an `## artifact { kind=notebook … }` tag (a `tiles=[…]` layout, or `run:` cells) is a notebook, not a model file to restructure: lift its reusable definitions into a model and leave the notebook to import them. For each dimension, measure, join, or calculation, ask: **is this a reusable building block?**
 
 A measure or dimension belongs in a model if it meets ANY of these criteria:
 

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.33
+version: 0.1.34
 ---
 
 <!--

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.33
+version: 0.1.34
 ---
 <!--
 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.33
+version: 0.1.34
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -16,7 +16,7 @@ Steps to follow when the user asks a question:
 
 1. Interpret the user's question as being about the bound notebook/report unless they explicitly ask about something else. Pronouns and shorthand ("this", "it", "the notebook", "the report", "the data", "what's here", "summarize", "key insights", "findings", "anything interesting") all refer to the notebook above. Never respond with a clarifying question about what the user means when the referent is clearly this notebook.
 2. Start with a brief, natural acknowledgment that references the specific question: one sentence, varied wording.
-3. The notebook above IS your context. Its code cells define the queries the user cares about. For any question:
+3. The notebook above IS your context. Its code cells define the queries the user cares about (for a notebook written as a tile layout, the cells are its tiles: each query tile is one code cell and each text tile one markdown cell). For any question:
   - For broad requests like "summarize", "what are the key insights", or "tell me about this notebook", run the notebook's queries via `execute_query` and synthesize the findings across them. Do NOT ask the user to be more specific.
   - 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.

package/skills/malloy-notebooks/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-notebooks
-description: Create Malloy notebooks (a .malloy file under notebooks/) for interactive data stories and reports. Use when user asks to "create a notebook", "make a notebook", "data story", or needs to build reports/visualizations that read top to bottom. Legacy .malloynb files are read, not newly authored.
-version: 0.1.33
+description: Create Malloy notebooks (a .malloy file under notebooks/, written as a one-column layout of tiles) for interactive data stories and reports. Use when user asks to "create a notebook", "make a notebook", "data story", or needs to build reports/visualizations that read top to bottom. Legacy .malloynb files are read, not newly authored.
+version: 0.1.34
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -10,7 +10,7 @@ SPDX-License-Identifier: MIT
 
 # Malloy Notebooks
 
-Files: `notebooks/<slug>.malloy`. Existing `.malloynb` files are still read and served, but a new notebook is never a `.malloynb`.
+Files: `notebooks/<slug>.malloy`. Author a notebook as a one-column layout of tiles (next section). Notebooks written as `run:` cells, and existing `.malloynb` files, are still read and served, but a new notebook is never a `.malloynb`.
 
 ## Scope: when to use this skill vs `skill:malloy-analysis-report`
 
@@ -20,11 +20,63 @@ For **ad-hoc reports** generated by an analysis agent, combining queries into a
 
 ## What makes a file a notebook
 
-A **notebook** is a `.malloy` file directly under the package's top-level `notebooks/` directory (not a subdirectory) whose model-level notes include `## artifact { kind=notebook … }`. The directory decides the surface; the artifact tag turns the file into a notebook. A `.malloy` file under `notebooks/` with no artifact tag is a shared include, not a notebook, and is left out of the notebook list. Publisher serves the notebook at `/<env>/<pkg>/notebooks/<slug>` and lists it beside any `.malloynb` files.
+A **notebook** is a `.malloy` file directly under the package's top-level `notebooks/` directory (not a subdirectory) whose model-level notes include `## artifact { kind=notebook … }`. The artifact tag turns the file into a notebook. A `.malloy` file under `notebooks/` with no artifact tag is a shared include, not a notebook, and is left out of the notebook list. Publisher serves the notebook at `/<env>/<pkg>/notebooks/<slug>` and lists it beside any `.malloynb` files. The tag's `kind=` decides the document's kind, not the folder.
 
 The file is ordinary Malloy: it compiles as one model, it is validated by the same `/compile` call as any model, and its cells run against the whole file (every `import` and `given:` in scope).
 
-## The five authoring rules
+## Author a notebook as a layout of tiles
+
+A notebook is a dashboard with one column. Its artifact tag lists the tiles in reading order, each either a query (`"source -> view"`, always a quoted string) or a prose block (`name { kind=text }`, a bare name), and the file defines the views and the prose:
+
+```malloy
+##! experimental.givens
+##" One category at a time: how it sells across the year and which brands carry it.
+##| artifact { kind=notebook title="Category review"
+  tiles=[
+    intro { kind=text },
+    "category_tiles -> revenue_trend",
+    "category_tiles -> brand_ranking"
+  ]
+}
+|##
+import { order_items, products } from "../storefront.malloy"
+
+#(description="Narrow to one product category")
+# label="Category" control=select suggest { source=products dimension=category }
+given: CATEGORY :: filter<string> is f''
+
+##|(markdown) intro
+## Category review
+
+Pick a **Category** in the controls above and every chart below re-runs for it.
+|##
+
+source: category_tiles is order_items extend {
+  # line_chart
+  # label="Revenue by month"
+  view: revenue_trend is sales_by_month + { where: category ~ $CATEGORY }
+
+  # bar_chart
+  # label="Top brands"
+  view: brand_ranking is top_brands + { where: category ~ $CATEGORY }
+}
+```
+
+- **The tag is one line (`## artifact { … }`) or a `##|` … `|##` block** with the same text inside, the form to use once the list is long: one tile per line, `}` on its own line, `|##` closing at the opener's column. Both read, lint and edit the same, and the builder keeps whichever form the file has. `tiles=[…]` is the notebook: tiles render top to bottom in list order, one column wide. `dashboard { columns }` other than 1 has no effect on a notebook, and a `colspan` or `break` on a tile entry is ignored with a warning (`notebook-tile-layout-ignored`).
+- **Quote every query entry.** `"orders_tiles -> headline"` is a string; `orders_tiles -> headline` unquoted does not parse, and the lint says so (`notebook-artifact-unparsed`) rather than reading the file as a cell notebook.
+- **A query tile is a `view:` on a source**, named as `"source -> view"`. Put the views on a `<source>_tiles` extension as thin wrappers (`view: revenue_trend is sales_by_month + { where: … }`): the modelled view keeps its chart tag, the wrapper says which controls the tile answers to and carries the tile's `# label`. A `run:` in a layout notebook is never shown, and the lint reports it (`notebook-layout-run`): define a view, list it in `tiles`, and delete the `run:`.
+- **A prose tile is a `##|(markdown) name` block** listed as `name { kind=text }`. The name is one bare word on the opener line, the body starts on the next line (a heading goes inside the block), and `|##` closes it at the opener's column. Every text entry needs its block, and every named block needs an entry written with `{ kind=text }`: a bare `intro` without it is the query-tile form (it names a `query:` in the file), so a block of that name is not shown.
+- **Place the file in one order: header, imports and givens, then the prose blocks in tile order, then the `<source>_tiles` extension.** Tiles read in `tiles=[…]` order wherever their blocks sit; grouping the blocks before the extension is the convention the builder writes, and it inserts a new block after the last one.
+- **Chart tags go on the view** (`# line_chart`, `# label="…"`), as on a dashboard; the `malloy-dashboards` skill has the tag set and the lint.
+- **Givens work as in any notebook**: declare `given:` above the view that reads it as `$NAME`, with the controls tags shown.
+- **Tiles run through the model query endpoint**, and the notebook also carries cells made from its tiles, so cell runs, `get_context` and notebook chat work on it as on any notebook.
+- **The tag's `kind=` decides the document's kind, not the folder.** Keep notebooks in `notebooks/` and dashboards in `dashboards/`; a file in the other folder works, and the lint notes it (`notebook-other-folder`). An untagged `.malloy` file in `notebooks/` is a shared include.
+
+The rest of this skill (the header rules, `given:`, charts, style) applies to both forms. The sections on cells describe the older form, where the file is a sequence of `run:` statements and `(markdown)` notes: Publisher still reads it, and a person saving it in the Console converts it to a layout.
+
+## The five authoring rules (cell notebooks)
+
+Rules 1 and 4 hold for both forms; rules 2, 3 and 5 are about `run:` cells and prose notes.
 
 1. **The header is `##!` flags, `//` comments and unnamed `"` notes (the description), then `## artifact { kind=notebook … }`.** Nothing else goes above the tag. A statement or a tag above `## artifact` is an error, and the notebook is served with that error instead of opening.
 2. **Prose is a `(markdown)` annotation, and the number of `#` says what it belongs to.** Floating markdown is a cell of its own: `##(markdown) text` (contiguous lines with no blank line between them merge into one cell) or a `##|(markdown)` block, with the body starting on the next line and the `|##` closer at the opener's column. Attached markdown, `#(markdown) text` or a `#|(markdown)` … `|#` block, belongs to the statement below it and renders with that cell. Keep the parentheses: `##| markdown` reads its prose as ordinary tags, and `##|markdown` draws a malformed-route warning. No body line starts with `|##`, and a blank line follows the closer. A `## Heading` line is model tags, not prose: write a heading inside a `##|(markdown)` block.
@@ -83,7 +135,7 @@ Imports are file-wide: declare them at the top, before the cells that use them.
 ##(markdown) RIGHT: frames the question and lets the query answer it. How is revenue trending?
 ```
 
-## A complete notebook
+## A complete cell notebook
 
 One notebook with all three prose forms: floating markdown cells, attached markdown headers, and a `#"` caption.
 
@@ -133,7 +185,7 @@ The `##|(markdown)` block and each `##(markdown)` line are floating markdown cel
 
 Interactive parameters are common and important. Add them to most notebooks. **Use `given:`.** Never add a `#(filter)` annotation, even if the model you are extending already has some: it is deprecated and the notebook does not render it (see below).
 
-A notebook's parameter surface comes from the `given:` declarations the file declares or imports. Publisher's notebook UI renders a Parameters panel above the notebook: declared givens become parameter inputs, the values a user sets are forwarded to Malloy's runtime, and every query cell re-executes with those values applied. A `given:` is read by the cells below it, so declare it before the first cell that uses it.
+A notebook's parameter surface comes from the `given:` declarations the file declares or imports. Publisher's notebook UI renders a Filters panel above the notebook: declared givens become parameter inputs, the values a user sets are forwarded to Malloy's runtime, and every query cell re-executes with those values applied. A `given:` is read by the cells below it, so declare it before the first cell that uses it.
 
 The widget for each parameter follows the given's declared Malloy type (`string`, `string[]`, `number`, `boolean`, `date`/`timestamp`, `filter<T>`); see `docs/givens.md` for the full type table. A `#(description="...")` annotation on the given renders as helper text under its input. It draws a cosmetic `malformed-route` warning that you can ignore; see `docs/givens.md` § Annotations. A control tag (`control=select suggest { source=… dimension=… }`) goes on the `given:` as shown in the complete notebook above.
 
@@ -143,7 +195,7 @@ The widget for each parameter follows the given's declared Malloy type (`string`
 
 `#(filter)` is deprecated, and the notebook no longer renders controls for it. A model that uses `#(filter)` is not filterable from a notebook, and a cell whose source has a `required` `#(filter)` fails, because nothing in the notebook can supply the value. Never add a `#(filter)` annotation. To make such a model filterable, migrate it to givens: `malloy-model` § Legacy: reading an existing `#(filter)` model has the mapping, including `required`.
 
-## Notebook Style: Iterative Analysis (Default)
+## Notebook Style: Iterative Analysis
 
 **Build a story.** Each query should reveal something that motivates the next query. Start broad, then drill into what's interesting. Frame questions in markdown, let queries answer them.
 
@@ -183,27 +235,55 @@ run: source -> my_view + { where: status = 'active', limit: 10 }
 ```malloy
 ##! experimental.givens
 ##" [One-line description of the notebook.]
-## artifact { kind=notebook title="[Title]" }
+##| artifact { kind=notebook title="[Title]"
+  tiles=[
+    intro { kind=text },
+    "main_source_tiles -> broad_tile",
+    "main_source_tiles -> drill_tile"
+  ]
+}
+|##
 import "model.malloy"
 
-##|(markdown)
-# [Title]
+##|(markdown) intro
 [Framing question: what are we trying to understand?]
 |##
 
-##(markdown) [First question: start broad]
-
-run: main_source -> [broad query]
-
-##(markdown) [Next question: motivated by what the first query reveals]
-
-run: main_source -> [drill into finding]
-
-##(markdown) [Deeper question]
-
-run: main_source -> [further breakdown]
+source: main_source_tiles is main_source extend {
+  view: broad_tile is [broad view]
+  view: drill_tile is [drill view]
+}
 ```
 
+Define each listed view on the `_tiles` extension (thin wrappers over the modelled views), and compile with `"scope": "file"`.
+
+## Editing in the Console
+
+A person can edit a `notebooks/*.malloy` notebook in the Console (an **Edit** button; **New** on the
+package page starts one). A layout notebook is edited in place: tiles are reordered, added and
+removed, text blocks and the tag are rewritten, and everything else in the file survives byte for
+byte. A cell notebook opens converted and unsaved, and Save writes the conversion: each `run:`
+becomes a `view:` on a `<source>_tiles` extension appended to the file (a `query:` used by exactly
+one run is folded into its view), each prose note becomes a `##|(markdown) text_N` block, and
+definitions, imports, givens and comments stay where they were. Undo save puts the original text
+back. Write a cell notebook so it converts:
+
+- Every `run:` is `<source> -> <view or query body>` with a named source. An inline `extend` before
+  the arrow, a source that is not a name, or a refinement (`q + { … }`) of a multi-stage query is
+  refused, and so is a run that resolves through more than ten named queries.
+- A chart line the editor does not model (for example `# bar_chart { size=spark }`) is kept, and the
+  Viz type picker is disabled for that tile with the reason shown.
+- The editor opens a notebook **read-only**, saying why, when it cannot place cells one by one:
+  two statements or notes on one line, text after a block closer, a comment straddling two cells, a
+  lone carriage return (use LF or CRLF), a statement above the `## artifact` tag, a statement no
+  cell can hold, or a tag value Malloy cannot read, such as a malformed date literal
+  (`@2024-13-01`).
+- A save whose text declares a real `#(authorize)` or `#(access_filter)` gate outside prose is
+  refused with a 400. Put gates in a model file the notebook imports.
+
+Viz type choices are From the view, Table, Line, Bar, Big value, Scatter, Shape map and Segment map.
+Every choice is listed; one the view cannot render is disabled with its reason beside it.
+
 ## Existing `.malloynb` files
 
 A `.malloynb` notebook (cells delimited by `>>>markdown` and `>>>malloy`) is a deprecated format. Publisher keeps read-only support so existing notebooks still open and run, and the bundled examples no longer ship one. **Do not create a new `.malloynb`.** To give a story a new home, write a `.malloy` notebook as above. Two things to know when maintaining an existing one:
@@ -227,7 +307,11 @@ A `.malloynb` notebook (cells delimited by `>>>markdown` and `>>>malloy`) is a d
 | A `#` tag separated from its `run:` by another statement | Render tags sit directly above the `run:`. Move the tag. |
 | `#(markdown)` or `#"` as the last thing in the file | Trailing prose is `##(markdown)`; both need a statement below them. |
 | `given:` used before it is declared | A cell reads only the givens declared above it. Move the `given:` up. |
-| `##|(markdown) name` block in a notebook | A name means something only on a dashboard, where the block is a text tile. Drop it: `##|(markdown)`. |
+| `##|(markdown) name` block in a cell notebook | A name means something only where a `tiles=[name { kind=text }]` entry lists the block (a dashboard or a layout notebook). In a cell notebook, drop it: `##|(markdown)`. |
+| `run:` in a notebook that lists `tiles=[…]` | Never shown. Define a `view:`, list `source -> view` in `tiles`, delete the `run:`. |
+| `tiles=[intro { kind=text }, orders_tiles -> headline]` (entry not quoted) | Every `source -> view` entry is a quoted string: `"orders_tiles -> headline"`. A text entry is a bare name followed by `{ kind=text }`. Unquoted, the tag does not parse and no tile is read. |
+| A bare `intro` in `tiles` for a `##|(markdown) intro` block | A bare name is the query-tile form for a `query:`. Write `intro { kind=text }`. |
+| `colspan` or `break` on a tile entry of a notebook | Ignored (a notebook is one column) and reported as `notebook-tile-layout-ignored`. Remove them. |
 | `#(filter) {"type": "Star"}` (JSON-blob form, on a dimension) | Unsupported legacy syntax, and `#(filter)` in any form is deprecated. Declare a `given:` on the model's source instead. |
 | Data-specific insights in markdown | Don't write "Revenue grew 23%." Frame questions instead. Data refreshes will make findings stale. |
 | `import` inside a `run:` cell | Imports are file-wide, put them at the top. An in-query import is rejected: `file imports are not permitted in a restricted query`. |
@@ -246,4 +330,4 @@ A `.malloynb` notebook (cells delimited by `>>>markdown` and `>>>malloy`) is a d
 
 ## Done
 
-Step complete. Output: a `notebooks/<slug>.malloy` file with an `## artifact { kind=notebook }` tag.
+Step complete. Output: a `notebooks/<slug>.malloy` file with an `## artifact { kind=notebook tiles=[…] }` tag.

package/skills/malloy-patterns/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-patterns
 description: An index of what search_malloy_docs covers - language reference, common patterns (YoY, cohorts, percent of total), rendering - for picking a topic worth searching before querying the docs.
-version: 0.1.33
+version: 0.1.34
 ---
 <!--
 Copyright (c) Credible Data Inc.

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

@@ -1,7 +1,7 @@
 ---
 name: malloy-phrase-detection
 description: How to phrase search_text on a get_context call so retrieval returns the fields you need instead of a truncated catalog. Covers target-type classification and decomposition patterns.
-version: 0.1.33
+version: 0.1.34
 ---
 <!-- Copyright (c) Credible Data Inc. SPDX-License-Identifier: MIT -->
 

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

@@ -1,7 +1,7 @@
 ---
 name: malloy-powerbi-review
 description: Move a Power BI semantic model (TMDL, PBIP, or .pbix) onto Malloy - read their model, transpile its DAX, and prove the numbers match. Use when Power BI artifacts are present, when a user wants to migrate or switch off Power BI, and whenever a specific DAX measure has to become Malloy - CALCULATE, ALL/ALLSELECTED/ALLEXCEPT, RANKX and top-N, time intelligence, USERELATIONSHIP, calculation groups, what-if parameters, or an RLS role. Carries a worked, executed transpile per construct and states what each port costs. Works with or without a database connection.
-version: 0.1.33
+version: 0.1.34
 ---
 <!--
 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.33
+version: 0.1.34
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -123,7 +123,7 @@ With a valid `publisher.json` in place, confirm the package is in the flat, publ
 
 ## Package Structure
 
-All model `.malloy` files must be in the package root (flat layout: the publisher does not support cross-directory imports yet). Notebooks are the exception: they live under `notebooks/`.
+All model `.malloy` files must be in the package root (flat layout: the publisher does not support cross-directory imports yet). Notebooks are the exception: they live under `notebooks/` (and dashboards under `dashboards/`).
 
 ```
 <package-name>/
@@ -139,7 +139,7 @@ All model `.malloy` files must be in the package root (flat layout: the publishe
 
 Publishable contents:
 - `.malloy` files - Semantic model definitions (base sources + joined sources)
-- `notebooks/*.malloy` files with an `## artifact { kind=notebook }` tag - Notebooks for exploration/documentation (see `skill:malloy-notebooks`). An existing `.malloynb` is still served; never write a new one.
+- `notebooks/*.malloy` files with an `## artifact { kind=notebook … }` tag - Notebooks for exploration/documentation, written as a one-column layout of tiles or as older `run:` cells (see `skill:malloy-notebooks`). The tag's `kind=` decides whether a file is a notebook or a dashboard, not its folder. An existing `.malloynb` is still served; never write a new one.
 - Data files (CSV/Parquet/XLSX) - Embedded data published with package
 
 ## Version Management

package/skills/malloy-queries/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-queries
 description: Malloy query patterns and syntax, for writing or debugging a query - dates, aggregates vs dimensions, join paths, filters, string matching, chart annotations, and the errors a SQL habit produces.
-version: 0.1.33
+version: 0.1.34
 ---
 <!--
 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.33
+version: 0.1.34
 ---
 <!--
 Copyright (c) Credible Data Inc.

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

@@ -8,7 +8,7 @@ SPDX-License-Identifier: MIT
 **Dimension:** `structure`
 **Rules:** 5
 
-Applies to the organization of `.malloy` files within a package. Skip a file for structural review if it's a notebook (a `.malloynb`, or a `notebooks/*.malloy` with an `## artifact { kind=notebook }` tag), which has its own conventions, or a one-off sandbox script.
+Applies to the organization of `.malloy` files within a package. Skip a file for structural review if it's a notebook (a `.malloynb`, or a `notebooks/*.malloy` with an `## artifact { kind=notebook … }` tag, whether written as a `tiles=[…]` layout or as `run:` cells), which has its own conventions, or a one-off sandbox script.
 
 For every rule, the linked instruction-skill section is the canonical source for rationale and examples.
 

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

@@ -6,7 +6,7 @@ SPDX-License-Identifier: MIT
 # Rubric: Style & Naming
 
 **Dimension:** `style`
-**Rules:** 3
+**Rules:** 4
 
 Style findings are almost always `nit` severity, aggregate them in the output rather than listing per-site.
 
@@ -49,6 +49,15 @@ For every rule, the linked instruction-skill section is the canonical source for
 
 ---
 
+## Y-04: Lay a file out one way, and keep an edit to the lines it changes
+
+- **Severity:** nit (non-blocking) · **Category:** style · LLM-judgment
+- **Detection:** in a new file, tab indentation or indentation that is not two spaces (unless the project's other files use that layout), trailing whitespace, or top-level declarations not separated by one blank line (consecutive `import` lines are one group, not a fault). In a diff, lines reindented or rewrapped that the change did not need: they bury the real change.
+- **Fix:** in a new file, the project's existing layout, or two-space when it has none; in an edited file, keep the file's own layout (a tab-indented file stays tab-indented) and revert reflowed lines the edit did not need. Don't flag a line width unless the project states one.
+- **See:** `skill:malloy-model` § Key Rules
+
+---
+
 ## Aggregation in the output
 
 Rather than listing every occurrence inline, roll style findings up in "Suggested Follow-ups":

package/skills/malloy-review/reference/severity-taxonomy.md

@@ -121,6 +121,7 @@ The rubric files set the default severity per rule. Defaults (can be overridden
 | Access modifier missing when flag is on (G-02) | `major` | `blocking` (governance) |
 | `public: *` used (G-01, documentation discipline) | `minor` | `non-blocking` |
 | Business-language naming suggestion (Y-02) | `nit` | `non-blocking` |
+| Inconsistent layout, or an edit that reflows lines it didn't need (Y-04) | `nit` | `non-blocking` |
 
 ## ID conventions
 

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.33
+version: 0.1.34
 ---
 
 <!--

package/skills/malloy-source-unreachable/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: malloy-source-unreachable
 description: Work out why a source is missing from get_context, or why a query against it was refused with a 404 or a 403, and what to do next. Use when a source you expect is absent from discovery, when execute_query answers "No queryable source", when a query that used to work stops working, or when deciding whether a package's curation is hiding something you need.
-version: 0.1.33
+version: 0.1.34
 ---
 <!-- Copyright (c) Credible Data Inc. SPDX-License-Identifier: MIT -->