@malloy-publisher/skills 0.1.0

package/skills/malloy-analyze/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: malloy-analyze
+description: Explore data for insights and build views/dashboards/notebooks. Use when user asks to "analyze this data", "find insights", "explore for patterns", "what's interesting", "what's driving X", "build a dashboard", "create views", or any analysis task. For EDA exploration, start at Step 1. For building views on an existing model, jump to View Patterns.
+---
+
+# Analysis with Malloy
+
+This skill covers two workflows:
+- **EDA exploration** (Steps 1-6): iteratively query data, build hypotheses, validate findings
+- **View/dashboard building**: create views, dashboards, notebooks from an existing model
+
+> **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.
+
+To formalize analysis into a polished semantic model, hand off to the modeling skill's "Starting from Analysis" workflow (`skill:malloy-model`).
+
+## Prerequisites
+
+- The Malloy MCP tools must be configured (`get_context`, `execute_query`, `search_malloy_docs`). If they are not available, **STOP** and ensure your host's MCP server is connected.
+- Call `search_malloy_docs` liberally: it has powerful analysis patterns (window functions, cohorts, percent-of-total, nested drill-downs).
+
+# EDA WORKFLOW
+
+```
+ORIENT → PROFILE → HYPOTHESIZE → INVESTIGATE → VALIDATE → SYNTHESIZE
+                     (user)                      (user)     (user)
+```
+
+## Adaptive Checkpoints
+
+The 6-step structure is a framework, not a rigid script.
+
+| Situation | Adaptation |
+|-----------|------------|
+| **User has a clear hypothesis** ("what's driving churn?") | Skip HYPOTHESIZE, jump to INVESTIGATE on their question |
+| **Open-ended** ("what's interesting?") | Follow all steps. PROFILE and HYPOTHESIZE are essential |
+| **User wants you to just go** ("explore and show me") | Compress checkpoints, present findings at SYNTHESIZE |
+
+## Step 1: ORIENT: Understand the Data
+
+1. Ground yourself with `get_context`. It returns the package's sources, views, and fields (with their docs), so this is where you learn what data exists.
+2. Note the source names, the connection they sit on, and the key tables/fields they expose.
+3. Inspect the existing dimensions, measures, and views the model already defines, then query the data to confirm shape and values.
+4. Create a working analysis file (this grows throughout the session):
+   ```malloy
+   source: main_table is conn.table('schema.table') extend { primary_key: pk }
+   ```
+
+**Output to user:** Brief summary of available data. Ask: *"What questions are you most interested in? Or should I look for what's interesting?"*
+
+## Step 2: PROFILE: Statistical Profiling
+
+**Directed analysis** (user has a question): Profile only columns relevant to their question.
+**Open-ended** (no question yet): Profile broadly, looking for surprises.
+
+### Key Profiling Queries
+
+**Column overview:** `run: source -> { index: * limit: 100 }`
+
+**Numeric distributions:**
+```malloy
+run: source -> {
+  aggregate: min_val is min(col), max_val is max(col), avg_val is avg(col), null_count is count() { where: col is null }
+}
+```
+
+**Categorical breakdown:** `run: source -> { group_by: col, aggregate: n is count(), order_by: n desc, limit: 20 }`
+
+**Time range:** Check earliest/latest dates, gaps, seasonality.
+
+**Duplicates:** `run: source -> { group_by: pk, aggregate: n is count(), having: n > 1, limit: 10 }`
+
+**Add useful profiling dimensions/measures to your analysis file as you go.** Build incrementally.
+
+## Step 3: HYPOTHESIZE: Form Questions
+
+**Skip presentation if user already has a clear question.** Use profiling to refine it and jump to INVESTIGATE.
+
+| Signal from profiling | Hypothesis type |
+|----------------------|-----------------|
+| Skewed distribution | Outlier analysis |
+| Time patterns | Trend/seasonality |
+| Category imbalance | Segment comparison |
+| Correlated columns | Driver analysis |
+| Unexpected NULLs | Data quality |
+
+**CHECKPOINT (open-ended only):** Present 3-5 hypotheses ranked by potential impact. Ask which to pursue.
+
+## Step 4: INVESTIGATE: Deep-Dive
+
+### Outlier Detection
+Search `search_malloy_docs("window functions")` for ranking and percentile patterns.
+
+### Trend Analysis
+```malloy
+# line_chart
+view: trend is { group_by: period is date_col.month, aggregate: key_metric, order_by: period }
+```
+
+### Segment Comparison
+```malloy
+view: segment_comparison is {
+  group_by: segment_dim
+  aggregate: row_count, key_metric
+  nest:
+    # line_chart
+    trend is { group_by: period is date_col.month, aggregate: key_metric, order_by: period }
+}
+```
+
+### Driver Analysis
+```malloy
+run: source -> {
+  group_by: candidate_driver
+  aggregate: row_count, avg_metric is avg(metric_col),
+    high_rate is count() { where: metric_col > threshold } / nullif(count(), 0)
+  order_by: high_rate desc
+}
+```
+
+### Multi-Source Comparison (Source vs Group)
+
+Compare each source to its group average using query-as-source:
+
+```malloy
+query: team_stats is source -> { group_by: team, season, aggregate: team_avg is avg(points) }
+query: driver_stats is source -> { group_by: driver, team, season, aggregate: driver_points is sum(points) }
+
+source: driver_vs_team is from(driver_stats) extend {
+  join_one: ts is from(team_stats) on team = ts.team and season = ts.season
+  dimension: advantage is driver_points - ts.team_avg
+}
+```
+
+### Nested Analysis (Malloy's Superpower)
+
+Use `nest:` for multi-level drill-downs in a single query:
+```malloy
+# dashboard
+view: deep_dive is {
+  nest: # big_value
+    kpis is { aggregate: # label="Total" total_metric, # label="Count" row_count }
+  nest: # bar_chart
+    by_dim is { group_by: dim, aggregate: metric, order_by: metric desc, limit: 10 }
+  nest: # line_chart
+    over_time is { group_by: period is date.month, aggregate: metric, order_by: period }
+}
+```
+
+### Build As You Go
+
+Every useful query should leave an artifact in your `.malloy` file. New dimension? Add it. New measure? Add it. Interesting view? Save it. This file becomes the input for formalizing into a model if the user wants one.
+
+## Step 5: VALIDATE: Triangulate
+
+For each finding, validate with at least ONE of:
+- Cross-check with another metric (revenue spiking? do order counts also?)
+- Check the denominator (high rate from tiny sample?)
+- Examine time consistency (pattern or one-time event?)
+- Look at raw data (`select: * where: condition limit: 20`)
+- Check for data artifacts (NULLs, duplicates, encoding)
+
+**CHECKPOINT:** Present each finding with: the insight, the evidence, confidence level, and assumptions made.
+
+## Step 6: SYNTHESIZE: Compelling Summary
+
+Build a dashboard view that tells the story:
+```malloy
+# dashboard
+view: analysis_summary is {
+  nest: # big_value
+    headlines is { aggregate: ... }
+  nest: # line_chart
+    trend is { ... }
+  nest: # bar_chart
+    breakdown 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.
+
+**Ready to formalize?** Hand off to the modeling skill's "Starting from Analysis" workflow (`skill:malloy-model`).
+
+# VIEW PATTERNS
+
+For building views on an existing model (base + joined source files already exist).
+
+## Starter Views (2-3 max initially)
+
+1. **`summary`**: KPI cards (`# big_value`)
+2. **`by_time`**: Time trend (`# line_chart`)
+3. **`by_category`**: Category breakdown (`# bar_chart`)
+4. **`dashboard`**: Nested view combining the above (`# dashboard`)
+
+**DRY rule:** Do NOT define measures/dimensions inline in views. Reference existing ones from base source files.
+
+## View Annotations
+
+| Annotation | Use For | Notes |
+|-----------|---------|-------|
+| `# big_value` | KPI summary | 2-5 metrics with `# label` on each |
+| `# transpose` | Summary with group_by | Swaps rows/columns |
+| `# dashboard` | Multi-visualization | Tiles nested views |
+| `# line_chart` | Time trend | ONE aggregate only |
+| `# bar_chart` | Category breakdown | ONE aggregate only |
+| (none) | Detailed table | Supports multiple aggregates |
+
+**Rules:**
+- One tag per line, never combine annotations on one line
+- One aggregate per chart view, charts render only the first
+- No fixed scale on measures: use `# currency` (no scale); fixed scale only in views after confirming ranges
+- Place chart annotation on the nested view definition, not on `nest:` itself
+
+For complete chart reference including scatter_chart, shape_map, sparklines, and all configuration options, see `skill:malloy-charts` or call `search_malloy_docs("rendering")`.
+
+## Field-Level Formatting
+
+| Tag | Use For |
+|-----|---------|
+| `# currency` | Monetary values |
+| `# percent` | Rates/percentages |
+| `# number=auto` | Large counts (K/M/B) |
+| `# number=id` | Non-quantity numbers (years, IDs) |
+| `# label="Name"` | Custom display name |
+| `# hidden` | Internal/helper fields |
+| `# duration=seconds` | Time durations |
+
+# NOTEBOOKS (.malloynb)
+
+Cells delimited by `>>>markdown` or `>>>malloy`. **Never use `>>>malloysql`.**
+
+```
+>>>markdown
+# Sales Analysis
+
+>>>malloy
+import "order_analysis.malloy"
+
+>>>malloy
+run: order_analysis -> summary
+```
+
+**Compile errors in `.malloynb` are NOT shown in the linter**: only visible on cell execution.
+
+A notebook is also the home for a polished, narrated report: alternate `>>>markdown` cells (the story) with `>>>malloy` cells (the views), and let the malloy cells carry the chart tags. For the full cell-shape and report-authoring conventions, see `skill:malloy-notebooks`.
+
+### Interactive Filters
+
+**Notebooks do NOT define filters themselves.** When you import a model, the model's `#(filter)` annotations on the source are **inherited and displayed automatically**: the publisher renders the filter widgets, parses caller parameters, and injects `where:` clauses server-side. You don't redeclare them in the consumer. If the analysis needs a knob the model doesn't expose, the right move is to add a `#(filter)` to the source itself (see `skill:malloy-model` § Parameterizable Filters with `#(filter)`), not to wedge filtering into the consumer.
+
+The notebook-level `##(filters)` annotation and the dimension-level `#(filter) {"type": "..."}` JSON-blob form are **unsupported legacy syntax**, don't use them. The only supported form is `#(filter) name=... dimension=... type=...` declared above the source.
+
+### View Refinement
+
+Use `+` to modify existing views: `run: source -> my_view + { limit: 15, where: status = 'active' }`
+
+## Done
+
+Step complete. Output: analysis `.malloy` file with views, insights, and reusable building blocks. For chart/renderer details, see `skill:malloy-gotchas-rendering` or call `search_malloy_docs`. To formalize into a model, hand off to the modeling skill (`skill:malloy-model`).
+
+Publishing is out of scope for now: open-source Publisher serves the model from disk, and self-hosters publish via git plus their host's publish path.

package/skills/malloy-charts/SKILL.md

@@ -0,0 +1,417 @@
+---
+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.
+---
+
+# Chart Selection for Malloy
+
+> Malloy uses Vega-Lite under the hood. `#` tags control visualization. Call `search_malloy_docs` with topic "rendering" for the full tag reference (or see https://docs.malloydata.dev/documentation/visualizations/overview).
+
+> **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.
+
+## Decision Tree: Which Chart?
+
+| Data Shape | Default Choice |
+|-----------|---------------|
+| Aggregates only (no group_by) | `# big_value` |
+| 1 time column + 1 measure | `# line_chart` |
+| 1 category + 1 measure | `# bar_chart` |
+| 2 numeric columns | `# scatter_chart` |
+| Geographic (US states) + 1 measure | `# shape_map` |
+| Route data (lat/lon pairs) | `# segment_map` |
+| Multiple perspectives | `# dashboard` with `nest:` |
+| Nested query to pivot | `# pivot` |
+| Filtered aggregates side-by-side | `# flatten` |
+| Detailed rows | Default table (no annotation) |
+
+| Goal | Renderer |
+|------|---------|
+| Compare categories | `# bar_chart` (sort by value, limit ~15) |
+| Show composition | `# bar_chart.stack` |
+| Trend over time | `# line_chart` |
+| Highlight KPIs | `# big_value` with `# label` |
+| Correlation | `# scatter_chart` |
+| Compare dimensions | `# dashboard` (nest chart views) |
+| Before/after | `# transpose` or `# pivot` |
+| Multiple metrics per category | Default table, `# flatten`, or `y=['a','b']` |
+
+**Constraints:**
+- ONE aggregate per chart view (charts render only the first; use `y=['a','b']` for multi-measure)
+- No fixed scale on measure definitions: use `# currency` not `# currency=usd0m`
+- One tag per line
+- Alias joined fields in `group_by` before `order_by`
+- Define measures in source, not in views
+
+
+## Chart Types
+
+### `# bar_chart`
+
+**Data shape:** `group_by` = x-axis, `aggregate` = y-axis, optional 2nd `group_by` = series.
+
+```malloy
+# bar_chart
+view: by_carrier is { group_by: carrier, aggregate: flight_count, order_by: flight_count desc, limit: 10 }
+
+# bar_chart.stack
+view: by_region is { group_by: category, region, aggregate: revenue }
+
+# bar_chart { y=['revenue','cost'] }
+view: rev_vs_cost is { group_by: category, aggregate: revenue, cost }
+```
+
+**Key properties:** `.stack`, `.size` (spark/xs/sm/md/lg/xl/2xl), `.x`, `.x.limit`, `.y` (supports `y=['a','b']`), `.series`, `.series.limit` (default 20), `.title`, `.subtitle`, `.x.independent`, `.y.independent`
+
+**Field role tags:** `# x`, `# y`, `# series` on individual fields to assign roles explicitly.
+
+### `# line_chart`
+
+**Data shape:** `group_by` (temporal/numeric) = x-axis, `aggregate` = y-axis, optional 2nd `group_by` = series.
+
+```malloy
+# line_chart
+view: trend is { group_by: order_month, aggregate: revenue, order_by: order_month }
+
+# line_chart { size=spark }
+view: mini_trend is { group_by: order_month, aggregate: revenue, order_by: order_month }
+```
+
+**Key properties:** `.zero_baseline`, `.interpolate` (e.g., `step`), `.size`, `.y` (supports `y=['a','b']`), `.series.limit` (default 12), `.title`, `.subtitle`
+
+### `# scatter_chart`
+
+**Data shape:** Fields by position: x, y, color, size (bubble), shape.
+
+```malloy
+# scatter_chart
+view: correlation is { group_by: customer_id, aggregate: avg_price, total_quantity }
+```
+
+### `# shape_map`
+
+Choropleth. US states only. Fields: state name, value.
+
+```malloy
+# shape_map
+view: by_state is { group_by: state, aggregate: revenue }
+```
+
+### `# segment_map`
+
+Route map. US only. Fields: start_lat, start_lon, end_lat, end_lon, color.
+
+
+## Layout Types
+
+### `# big_value`
+
+KPI cards. Aggregates only, no `group_by`.
+
+```malloy
+# big_value
+view: summary is {
+  aggregate:
+    # label="Revenue"
+    # currency
+    revenue
+    # label="Orders"
+    # number=auto
+    order_count
+}
+```
+
+**Properties:** `.size`, `.sparkline=<nested_view_name>`, `.comparison_field`, `.comparison_label`, `.down_is_good`
+
+### `# dashboard`
+
+Card-based multi-tile layout. Apply to a view whose body is a nested query; the view's own fields lay out automatically:
+
+- `group_by` dimensions -> a row header (repeats once per row; omit for a single block)
+- `aggregate` measures -> KPI cards, one per measure
+- each `nest:` -> a tile, rendered by the tag above it (`# table` default, or `# bar_chart` / `# line_chart` / `# big_value`)
+
+**Two modes.** Flex (default): tiles flow and wrap; `# break` forces a new row. Columns: `# dashboard { columns=N }` lays tiles into N equal columns, `# colspan=n` widens a tile, `# break` starts a new row, overflow wraps.
+
+```malloy
+// Flex: measures become KPI cards, the nest becomes a tile
+# dashboard
+view: overview is {
+  group_by: category
+  # currency
+  aggregate:
+    avg_retail is retail_price.avg()
+    sum_retail is retail_price.sum()
+  nest:
+    # bar_chart
+    by_brand is { group_by: brand, aggregate: avg_retail is retail_price.avg(), limit: 10 }
+}
+
+// Columns: # colspan widens tiles, # break ends a row
+# dashboard { columns=12 }
+view: layout is {
+  group_by: category
+  # currency
+  aggregate:
+    # colspan=4
+    avg_retail is retail_price.avg()
+    # colspan=4
+    sum_retail is retail_price.sum()
+    # colspan=4
+    max_retail is retail_price.max()
+  nest:
+    # break
+    # colspan=6
+    # bar_chart
+    # subtitle="Top brands"
+    by_brand_chart is { group_by: brand, aggregate: avg_retail is retail_price.avg(), limit: 8 }
+    # colspan=6
+    by_brand_table is { group_by: brand, aggregate: product_count is count(), limit: 8 }
+}
+```
+
+**Tags:** `# dashboard { columns=N }` (columns mode), `{ gap=PX }` (tile spacing, default 16; never a mode), `{ table.max_height=PX|none }` (cap table tiles). On a measure or nest: `# colspan=N` (columns mode only), `# break` (both modes), `# subtitle="..."` (tile), `# borderless` (drop card chrome), `# label="..."` (card title).
+
+For rich KPI cards (sparklines, comparison deltas, several metrics on one card) nest a `# big_value` view instead of relying on the dashboard's own measures:
+
+```malloy
+# dashboard
+view: kpis is {
+  group_by: category
+  nest:
+    # big_value
+    revenue_card is {
+      aggregate:
+        # label="Revenue"
+        # currency
+        # big_value { sparkline=trend }
+        total_revenue is retail_price.sum()
+      # line_chart { size=spark y.independent=true }
+      # hidden
+      nest: trend is { group_by: bucket is floor(id / 100)::number, aggregate: total_revenue is retail_price.sum(), order_by: bucket, limit: 20 }
+    }
+}
+```
+
+**Rules:** `# dashboard` needs a nested-query view (no effect on a scalar). `# colspan` works only in columns mode and is ignored (warns) in flex. `columns` is any positive integer; a `# colspan` over the column count clamps to a full row. Style tiles via the instance theme, or theme the views inside with `# theme.*` (see Theming below).
+
+### `# pivot`
+
+Pivot nested results into columns. Max 30 pivot columns.
+
+```malloy
+view: sales is {
+  group_by: product, aggregate: total
+  nest: # pivot
+    by_quarter is { group_by: quarter, aggregate: revenue }
+}
+```
+
+### `# transpose`
+
+Swap rows/columns. Good for period comparisons.
+
+```malloy
+# transpose
+view: comparison is {
+  aggregate:
+    # label="This Month"
+    current_revenue
+    # label="Last Month"
+    prior_revenue
+}
+```
+
+### `# list` / `# list_detail`
+
+List renders as comma-separated values. List_detail shows `value (detail)` pairs.
+
+### `# flatten`
+
+Collapse nested record into parent table as columns. Use for side-by-side filtered aggregates:
+
+```malloy
+view: segments is {
+  group_by: product, aggregate: total_revenue
+  nest: # flatten
+    enterprise is { where: segment = 'Enterprise', aggregate: # label="Enterprise" revenue }
+  nest: # flatten
+    smb is { where: segment = 'SMB', aggregate: # label="SMB" revenue }
+}
+```
+
+### `# table`
+
+Default (implicit). Use explicitly for `.size=fill` property.
+
+
+## Field Formatting Tags
+
+| Tag | Use For | Shorthand |
+|-----|---------|-----------|
+| `# number` | Numeric formatting | `=auto` (K/M/B), `=id` (no commas), `=1k`, `=1m` |
+| `# percent` | Percentages | (none needed) |
+| `# currency` | Money | `=usd2m` (USD, 2 decimals, millions); scale only in views |
+| `# duration` | Time durations | `=seconds`, `=minutes`, `=hours`, `=days` |
+| `# data_volume` | Storage sizes | `=bytes`, `=kb`, `=mb`, `=gb` |
+| `# link` | Hyperlinks | `.url_template="https://example.com/$$"` |
+| `# image` | Inline images | `.height=40px`, `.width=100px` |
+
+**Currency codes:** `usd` ($), `eur`, `gbp`. **Scale:** K/M/B/T/Q or `auto`.
+**Number suffix styles:** `word` ("42.5 million"), `letter` ("42.5M"), `scientific`.
+
+## Utility Tags
+
+| Tag | Purpose |
+|-----|---------|
+| `# hidden` | Hide from output (still usable for sorting/references) |
+| `# label="..."` | Override display name |
+| `# description="..."` | Tooltip text |
+| `# tooltip` | Include nested view in chart tooltip |
+| `# break` | Force new dashboard row |
+| `# column { width=sm }` | Table column width |
+
+## Model-Level Defaults
+
+```malloy
+## viz.line_chart.defaults.y.independent=true
+## viz.bar_chart.defaults.stack
+```
+
+## Theming
+
+Publisher styles charts and tables from one structured theme. The instance sets it (in `publisher.config.json`'s `theme` block or the **Settings, then Theme** editor); a model overrides it per result with `# theme.*` annotations, or model-wide with `## theme.*`. Per-chart annotations use the same nested `palette.*` / `font.*` vocabulary as the config, not flat key names, and they win over the instance theme for the keys they set. The forms:
+
+| Annotation | Controls | Modes |
+|-----------|----------|-------|
+| `# theme.palette.series` | Categorical series colors (array) | shared |
+| `# theme.palette.background.{light,dark}` | Chart canvas + table background | per-mode |
+| `# theme.palette.tableHeader.{light,dark}` | Table header text color | per-mode |
+| `# theme.palette.tableHeaderBackground.{light,dark}` | Table header row background | per-mode |
+| `# theme.palette.tableBody.{light,dark}` | Table body text color | per-mode |
+| `# theme.palette.tile.{light,dark}` | Dashboard tile background | per-mode |
+| `# theme.palette.tileTitle.{light,dark}` | Dashboard tile title color | per-mode |
+| `# theme.palette.mapColor.{light,dark}` | Choropleth gradient (`# shape_map` / `# segment_map`) | per-mode |
+| `# theme.font.family` | Font for all rendered text | shared |
+| `# theme.font.size` | Table font size (px) | shared |
+
+The seven `palette.*` color keys each take a `.light` and/or `.dark` variant so dark mode gets its own value. `palette.series`, `font.family`, and `font.size` are single values shared across modes.
+
+```malloy
+// Model-wide defaults (## applies to every view in the model):
+## theme.palette.series = ["#14b3cb", "#e47404", "#1474a4"]
+## theme.font.family = "Inter, sans-serif"
+
+// Per-view override (# applies to this result only; beats the instance theme):
+# theme.palette.background.light = "#fafafa"
+# theme.palette.background.dark = "#111111"
+# theme.palette.tableHeader.dark = "#94a3b8"
+view: revenue_by_month is {
+  group_by: month
+  aggregate: revenue
+}
+```
+
+**Precedence**, highest to lowest, per key: `# theme.*` on the view, then `## theme.*` model default, then the instance theme, then Publisher's built-in defaults. A per-chart annotation overrides the instance for the keys it sets; unset keys fall through to the instance. (This is the reverse of a bare `@malloydata/render` embed, where the embedder wins: Publisher reads the annotation itself and layers it on top.)
+
+Quote values that contain spaces or a leading `#`. The light/dark default (`defaultMode`) and the toggle lock (`allowUserToggle`) are instance-only: set them in the config `theme` block or the editor, not as annotations. The malloy-gotchas-rendering skill lists the annotation forms that look valid but do nothing.
+
+
+## Advanced Patterns
+
+### Sparklines in KPI Cards
+
+```malloy
+# big_value { sparkline=trend }
+view: revenue_kpi is {
+  aggregate: # label="Revenue" # currency revenue
+  nest: # line_chart { size=spark } # hidden
+    trend is { group_by: order_date, aggregate: revenue, order_by: order_date }
+}
+```
+
+### KPIs with Comparison Deltas
+
+```malloy
+# big_value { comparison_field=prior_month comparison_label="vs Last Month" }
+view: rev_delta is {
+  aggregate: # label="Revenue" # currency revenue, # hidden prior_month
+}
+```
+
+Use `down_is_good=true` for metrics where decrease is positive (churn, defects).
+
+### Inline Mini-Charts in Table Rows
+
+```malloy
+view: carriers is {
+  group_by: carrier, aggregate: flight_count
+  nest: # line_chart { size=spark }
+    trend is { group_by: month, aggregate: flight_count, order_by: month }
+}
+```
+
+### Multi-Measure Series
+
+```malloy
+# bar_chart { y=['revenue','cost'] }
+view: rev_vs_cost is { group_by: quarter, aggregate: revenue, cost }
+```
+
+### Hierarchical Drill-Down
+
+```malloy
+# list_detail
+view: explorer is {
+  group_by: region, aggregate: revenue
+  nest: # bar_chart
+    by_category is { group_by: category, aggregate: revenue, order_by: revenue desc, limit: 10 }
+}
+```
+
+### Distribution (Histogram)
+
+Call `search_malloy_docs("autobin")` for syntax:
+```malloy
+# bar_chart
+view: price_dist is { group_by: bucket is autobin(price, 20), aggregate: order_count }
+```
+
+
+## Patterns for Missing Chart Types
+
+| Desired | Malloy Approximation |
+|---------|---------------------|
+| Pie/donut | `# bar_chart` sorted by value |
+| Treemap | Nested table with `order_by: desc` |
+| Heatmap | `# pivot` with color values |
+| Stacked area | `# line_chart` with series (overlaid lines) |
+| Funnel | `# bar_chart` with ordered stages |
+| Gauge/bullet | `# big_value` with `.comparison_field` |
+
+
+## Chart Annotations on Queries with `nest:`
+
+A top-level chart tag (e.g., `# bar_chart`) renders only the outer query; any `nest:` views are silently hidden from the rendering (still in raw data). To show nests, use `# dashboard` on the outer query with chart tags on each nest. Otherwise, drop the `nest:`.
+
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Two aggregates in chart | ONE aggregate, or use `y=['a','b']` |
+| `# currency=usd0m` on measure | `# currency` (no scale) on defs; scale only in views |
+| Chart annotation on `nest:` line | Put on the **view definition** |
+| Tags on same line | One tag per line |
+| Sparkline not showing | Add `# hidden` to nested view AND reference in `.sparkline=` |
+| Pivot > 30 columns | Filter/limit the nested group_by |
+
+NOTE: The term 'constructor' is a reserved term in Vega-Lite. If the word 'constructor' appears in the query, it will cause the rendering to fail. Never use it in a query and avoid using it as a dimension in a model.
+
+For more patterns, call `search_malloy_docs` with topics like "bar charts", "line charts", "dashboards", "autobin", "percent of total", "comparing timeframes", or "pivots".
+
+## Further Reading
+
+- [Visualizations Overview](https://docs.malloydata.dev/documentation/visualizations/overview) - Official docs
+- [Bar Charts](https://docs.malloydata.dev/documentation/visualizations/bar_charts) - Stacked, grouped, series
+- [Bump Charts Blog](https://docs.malloydata.dev/blog/2023-10-26-malloy-bump-chart/) - Ranking over time
+- [Dataviz is Hierarchical](https://docs.malloydata.dev/blog/2024-02-29-hierarchical-viz/) - Nested data visualization philosophy