@malloy-publisher/skills 0.1.13 → 0.1.16

package/README.md

@@ -53,11 +53,11 @@ skill points to for detail it does not inline. Start with `malloy-getting-starte
 `malloy-review` to check Malloy for correctness.
 
 A few skills (`malloy-modeling`, `malloy-publish`, `malloy-document`, `malloy-getting-started`, and
-the `malloy` index) are written for a Publisher host and name Publisher's `malloy_*` MCP tools
+the `malloy` index) are written for a Publisher host and name Publisher's MCP tools
 directly. The rest describe Malloy itself and refer to tools by bare name (`get_context`,
 `execute_query`, `search_malloy_docs`), because the prefix depends on the
-host. `search_database_schema` maps the same way if a shared skill starts using it. On Publisher those are `malloy_getContext`, `malloy_executeQuery`, `malloy_searchDocs`, and
-`malloy_searchDatabaseSchema`.
+host. `search_database_schema` maps the same way if a shared skill starts using it. On Publisher those are `get_context`, `execute_query`, `search_malloy_docs`, and
+`search_database_schema`.
 
 ## Versioning
 

package/package.json

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

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

@@ -21,7 +21,7 @@ The log is a JSON object:
     "toolUses": [
       {"name": "Read", "input": {"path": "..."}},
       {"name": "Shell", "input": {"command": "..."}},
-      {"name": "malloy_getContext", "input": {}}
+      {"name": "get_context", "input": {}}
     ],
     "reportedCalls": 4
   }
@@ -148,7 +148,7 @@ def check(
         name = _tool_name(entry) or f"use[{i}]"
         hay = _haystack(entry)
         hits = _matches(hay, needles)
-        # modelPath on malloy_executeQuery is required, not a file read --
+        # modelPath on execute_query is required, not a file read --
         # including when the MCP call rides over Shell as a curl JSON-RPC.
         if model_needles and _is_host_file_tool(name) and not _is_mcp_transport(hay):
             hits.extend(_matches(hay, model_needles))

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """Pull search terms and entity ids out of a get_context exchange. Stdlib only.
 
-`malloy_getContext` has more than one request shape and more than one response
+`get_context` has more than one request shape and more than one response
 shape, and an extractor written against the one you happen to see first will
 silently return nothing for the others -- scoring every attempt at zero recall
 while the agent was in fact handed exactly what it needed.

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """python mcp_payload_test.py
 
-The fixtures are trimmed copies of real `malloy_getContext` exchanges. The
+The fixtures are trimmed copies of real `get_context` exchanges. The
 regression they exist for: an extractor written against the flat `results`
 shape returned [] for the nested one, which scored attempts that had received
 everything at 0% recall and moved three baseline failures off "query

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

package/skills/eval-diagnose/scripts/diagnose.py

@@ -61,9 +61,9 @@ import ledger  # noqa: E402
 from ledger import read_jsonl  # noqa: E402
 
 SKILLS_ROOT = pathlib.Path(__file__).resolve().parent.parent.parent
-DIAGNOSE_TOOLS = ("mcp__publisher__malloy_getContext",
-                  "mcp__publisher__malloy_executeQuery",
-                  "mcp__publisher__malloy_compile",
+DIAGNOSE_TOOLS = ("mcp__publisher__get_context",
+                  "mcp__publisher__execute_query",
+                  "mcp__publisher__compile_model",
                   "Read", "Grep", "Glob")
 # The platform target: a hosted MCP server. Its NAME has to match the one
 # run_baseline.py's answerer used, because that name is the OAuth cache key --

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.13
+version: 0.1.16
 ---
 
 # Improve the Model

package/skills/eval-improve/scripts/improve.py

@@ -65,17 +65,17 @@ import ledger  # noqa: E402
 from ledger import read_jsonl  # noqa: E402
 
 SKILLS_ROOT = pathlib.Path(__file__).resolve().parent.parent.parent
-IMPROVE_TOOLS = ("mcp__publisher__malloy_getContext",
-                 "mcp__publisher__malloy_executeQuery",
-                 "mcp__publisher__malloy_compile",
-                 "mcp__publisher__malloy_reloadPackage",
+IMPROVE_TOOLS = ("mcp__publisher__get_context",
+                 "mcp__publisher__execute_query",
+                 "mcp__publisher__compile_model",
+                 "mcp__publisher__reload_package",
                  "Read", "Edit", "Write", "Grep", "Glob",
                  "Bash(bash ./sync_and_reload.sh)")
 
 RELOAD = """curl -s -m 60 -X POST "{mcp_url}" \\
   -H "Content-Type: application/json" \\
   -H "Accept: application/json, text/event-stream" \\
-  -d '{{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{{"name":"malloy_reloadPackage","arguments":{{"environmentName":"{environment}","packageName":"{package}"}}}}}}' \\
+  -d '{{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{{"name":"reload_package","arguments":{{"environmentName":"{environment}","packageName":"{package}"}}}}}}' \\
   | grep -o '"sourceContentSha":"[^"]*"' | head -1"""
 
 SYNC_SCRIPT = """#!/bin/bash

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.13
+version: 0.1.16
 ---
 
 # 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 under the model package''s evals/ directory; checkpoints are git commits of the model repo. Use to score a model, diagnose failures, improve behind an acceptance check, or roll back a bad direction.'
-version: 0.1.13
+version: 0.1.16
 ---
 
 # The Evaluation Loop
@@ -202,7 +202,7 @@ the run measure something other than what it names:
      default. Where that exists, point `--mcp-url` at the proxy on localhost
      and no OAuth step is needed, because the extension holds it. Check what
      the proxy actually exposes before relying on it: the same proxy may serve
-     a local Publisher's `malloy_*` tools instead, and then `--hosted-tools` is
+     a local Publisher's tools instead, and then `--hosted-tools` is
      naming tools that are not there. This route is not available to someone
      running the CLI alone.
 

package/skills/eval-loop/reference/running-a-run.md

@@ -76,7 +76,7 @@ chases `ModuleNotFoundError` three times.
 Two failure modes worth pre-empting, because both produce a clean-looking run:
 
 - **Pre-approve the tools.** A headless answerer that has to ask permission for
-  `malloy_getContext` stalls until the timeout and lands as a harness error.
+  `get_context` stalls until the timeout and lands as a harness error.
 - **Check the served revision is the one you edited.** Publisher serves a
   snapshot copy, so a model fix can be absent from the run that is supposed to
   measure it. Query the changed measure once before spending an arm on it.

package/skills/eval-loop/scripts/run_baseline.py

@@ -74,9 +74,9 @@ import urllib.parse
 import urllib.request
 from typing import Any
 
-ANSWER_TOOLS = ("mcp__publisher__malloy_getContext",
-                "mcp__publisher__malloy_executeQuery",
-                "mcp__publisher__malloy_compile")
+ANSWER_TOOLS = ("mcp__publisher__get_context",
+                "mcp__publisher__execute_query",
+                "mcp__publisher__compile_model")
 # The platform target: a hosted MCP server exposing the same two operations
 # under its own names. The CLI addresses a tool as `mcp__<server>__<tool>`, so
 # both halves are configuration -- `--hosted-mcp-server` names the server (which
@@ -210,15 +210,20 @@ def next_run_label(out: pathlib.Path, set_name: str, phase: str) -> str:
     return f"{stem}-{n:02d}"
 
 
-# Tools only the open-source Publisher exposes. A shared skill refers to an MCP
-# tool by its BARE name (`get_context`, `execute_query`) precisely so it reads
-# correctly on any host; a skill naming these is a host/router skill written for
-# Publisher, and on a hosted target it teaches the answerer tools it does not
-# have. That does not error -- the answerer simply reads instructions for a
-# different surface -- so it has to be said out loud or the run quietly measures
-# a different system than the one it names.
-PUBLISHER_ONLY_TOOLS = ("malloy_getContext", "malloy_executeQuery",
-                        "malloy_compile", "malloy_reloadPackage")
+# Tools only the open-source Publisher exposes. A skill naming these is a
+# host/router skill written for Publisher, and on a hosted target it teaches the
+# answerer tools it does not have. That does not error -- the answerer simply
+# reads instructions for a different surface -- so it has to be said out loud or
+# the run quietly measures a different system than the one it names.
+#
+# Keyed on tools Publisher HAS and a hosted target does not. It used to be keyed
+# on the `malloy_` prefix, on the reasoning that a bare name was the portable
+# spelling and a prefixed one meant Publisher. That distinction is gone:
+# Publisher's tools are bare names now, so `get_context` and `execute_query` are
+# what BOTH surfaces call them and neither can mark a skill as Publisher-only.
+# Authoring, catalog and health have no hosted counterpart, so they still can.
+PUBLISHER_ONLY_TOOLS = ("compile_model", "reload_package",
+                        "list_packages", "get_status")
 
 
 def publisher_only_skills(names: list[str],
@@ -411,8 +416,8 @@ Package: {package}
 
 Question: {question}
 
-Use malloy_getContext to find the entities you need, then malloy_executeQuery to
-run a Malloy query against the model. Base the answer only on what the model
+Use get_context to find the entities you need, then execute_query to run a
+Malloy query against the model. Base the answer only on what the model
 returns. If the model genuinely cannot answer the question, say so plainly and
 name the specific data that is missing rather than substituting a proxy.
 
@@ -601,9 +606,9 @@ def run_answerer(case: dict[str, Any], a: argparse.Namespace,
                     answer.append(c["text"])
                 elif c.get("type") == "tool_use":
                     name = c["name"]
-                    # Both surfaces: Publisher's malloy_getContext/
-                    # malloy_executeQuery and a hosted server's get_context/
-                    # execute_query.
+                    # Both surfaces answer to the bare names now. The old
+                    # malloy_-prefixed names stay matched so a run recorded
+                    # against an older Publisher still parses.
                     if (name.endswith("malloy_getContext")
                             or name.endswith("__get_context")):
                         n_get += 1
@@ -1124,7 +1129,7 @@ def main(argv: list[str] | None = None) -> int:
             print(f"  ! {len(mismatched)} answerer skill(s) name Publisher-only "
                   f"tools on a PLATFORM run: {', '.join(mismatched)}")
             print(f"    The answerer holds mcp__{a.hosted_mcp_server}__* tools "
-                  f"and will be told to call malloy_* ones. Point "
+                  f"and will be told to call Publisher-only ones. Point "
                   f"--answerer-manifest at a manifest written for this host, or "
                   f"--skills-root at the checkout that ships it.")
     print(f"answerer skills: "

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

@@ -128,7 +128,7 @@ which is the fastest way to see a compile failure. Notebooks are listed by
 `404 "<file> is a notebook"`. A notebook fetched from `notebooks/<file>` reports
 its cells' compiled schemas under `modelInfo`, but only the cells it treats as
 anonymous queries -- do not read a low count there as cells failing to compile. To
-verify every cell, run each named query through `malloy_executeQuery`.
+verify every cell, run each named query through `execute_query`.
 
 Pass `--mcp_port` explicitly. It defaults to 4040 and any other local Publisher
 already holds it; the server logs `Port 4040 in use` and carries on without an MCP
@@ -141,13 +141,13 @@ nothing.
 
 It serves a **snapshot copy** under `publisher_data/<env>/<pkg>/`. The `location`
 in `publisher.config.json` is a one-time import source, not a live mount, and
-`malloy_reloadPackage` does **not** re-fetch from it -- it answers
+`reload_package` does **not** re-fetch from it -- it answers
 `mode: in-place`, re-reading the snapshot. So the working recipe is sync then
 reload:
 
 ```bash
 rsync -a --delete <location>/ "$SERVER_ROOT/publisher_data/<env>/<pkg>/"
-# then malloy_reloadPackage {environmentName, packageName}
+# then reload_package {environmentName, packageName}
 ```
 
 Sync the whole package. A new model over stale CSVs fails with a column-not-found

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.13
+version: 0.1.16
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -99,4 +99,4 @@ Publishing is out of scope for open-source Publisher v1. Self-hosters move a fin
 
 ## Syntax Help
 
-Call `malloy_searchDocs` with your question. Use `skill:malloy-patterns` to discover available topics.
+Call `search_malloy_docs` with your question. Use `skill:malloy-patterns` to discover available topics.

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.13
+version: 0.1.16
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -23,8 +23,7 @@ Restate what is being asked: which metric, which breakdown (group-by), which fil
 Find the right entities before writing any query.
 
 - If you do not already know which package to work in, confirm the environment and package with the user before continuing.
-- Call `get_context` with a plain-English description of the question (for example "revenue by product category"). It returns the most relevant sources, views, and dimension/measure fields, the model each lives in, and their `#(doc)` descriptions. Start here so you target the right source and reuse an existing `view:` instead of scanning everything.
-- Drill down: call `get_context` again scoped to a single source to focus on the fields and views within it. Even when you know an entity's name, use a descriptive search rather than just echoing the name.
+- Call `get_context` with entity targets that describe the fields the question needs: a `measure` for the metric, a `dimension` for each breakdown or filter, and a `view` if the question sounds like a canned report. `skill:malloy-phrase-detection` covers how to phrase them; the tool description covers what comes back and how to narrow or browse.
 - Read the `#(doc)` on each returned entity: it is where grain, units, null handling, and any source-level filters are described. Confirm the exact field names against the results before using them.
 - **Read the source's own docstring too, not just each field's.** The source-level `#(doc)` often defines the grain, the universe of rows it represents, how joins behave, and source-level filters or assumptions that apply to every query rooted on it. Factor both the source and the field docstrings into how you build and later verify the query.
 - When unsure of Malloy syntax, call `search_malloy_docs` (for example "window functions", "histograms") rather than guessing. For decomposing a multi-part question into retrieval targets, load `skill:malloy-phrase-detection`.
@@ -84,4 +83,4 @@ Never re-run the exact same query expecting a different result: a given query al
 
 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. You can also offer to capture the analysis as a Malloy notebook (`skill:malloy-notebooks`) so it can be re-run and shared.
+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.

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

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.13
+version: 0.1.16
 ---
 <!--
 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.13
+version: 0.1.16
 ---
 <!--
 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.13
+version: 0.1.16
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -28,7 +28,7 @@ Scanned at a glance is a dashboard; read top to bottom is a notebook.
 ## Build sequence
 
 1. **READ THE MODEL FIRST.** Get the real source, view, dimension, and given names from the package:
-   `malloy_getContext` if you have it, otherwise the REST model endpoint or the `.malloy` files.
+   `get_context` if you have it, otherwise the REST model endpoint or the `.malloy` files.
    Never guess a name. A guessed field in a query fails the whole package load, not just that one
    dashboard; a guessed tile or suggest source is quieter, and only shows up in the package warnings.
 2. **PICK THE VIEWS TO SHOW.** A dashboard is `## artifact { tiles=[…] }` naming existing views, so
@@ -46,7 +46,7 @@ Scanned at a glance is a dashboard; read top to bottom is a notebook.
    name, so the file compiles and the package loads, but running the picker fails with
    `Undefined source '<name>'`. The package warnings name this one too, saying which source to
    import. Import the source that suggest query reads, not just the query.
-5. **COMPILE IT** with `malloy_compile` (or `POST …/models/<path>/compile`), against the source text,
+5. **COMPILE IT** with `compile_model` (or `POST …/models/<path>/compile`), against the source text,
    before you save, at the path the file will have. **Editing one that already exists needs
    `"scope": "file"`**, which compiles your source AS that file; the default appends it instead, so
    every imported name and the query name collide with the saved copy and you get a wall of
@@ -56,7 +56,7 @@ Scanned at a glance is a dashboard; read top to bottom is a notebook.
    dashboard that imports it. A clean compile is not a working dashboard: some tag mistakes surface
    at step 6, and some only when you look at the page in step 7. (The third scope, `append`, is the
    default and is what a not-yet-saved file gets.)
-6. **SAVE IT, RELOAD, AND READ THE MANIFEST AND THE WARNINGS.** `malloy_reloadPackage`, or
+6. **SAVE IT, RELOAD, AND READ THE MANIFEST AND THE WARNINGS.** `reload_package`, or
    `GET …/packages/<pkg>?reload=true`. Check the status the reload returns as well as the warnings:
    a 424 means the package did not load and your edit is not live. **The `warnings` key is absent
    when there are none**, so an empty response is the pass, not a sign you are reading the wrong

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.13
+version: 0.1.16
 ---
 <!--
 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.13
+version: 0.1.16
 ---
 <!--
 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.13
+version: 0.1.16
 ---
 <!--
 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.13
+version: 0.1.16
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -184,7 +184,7 @@ After writing `#(doc)` tags, present any that required judgment to the user for
 | `total` | "Total order amount in USD" | Medium | Could be gross or net, verified with sample query |
 | `status` | "Order status: pending, shipped, delivered" | High | Values confirmed via a query of distinct values |
 
-Only flag fields where the description required assumptions about business meaning, units, or valid values. When in doubt about valid values, run a quick query against the data to confirm them before writing the description. Use `malloy_getContext` to ground yourself in the package's sources and fields and `malloy_executeQuery` to check distinct values, for example `run: source -> { group_by: status }`.
+Only flag fields where the description required assumptions about business meaning, units, or valid values. When in doubt about valid values, run a quick query against the data to confirm them before writing the description. Use `get_context` to ground yourself in the package's sources and fields and `execute_query` to check distinct values, for example `run: source -> { group_by: status }`.
 
 ## Done
 

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.13
+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.16
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -14,7 +14,7 @@ Goal: go from "connected" to a correct, grounded answer without guessing any nam
 
 ## 0. Confirm the tools are reachable
 
-At minimum you need `malloy_getContext`, `malloy_executeQuery`, and `malloy_searchDocs`. Authoring a model also needs `malloy_compile` and `malloy_reloadPackage` (see section 4); an older Publisher may not serve those two.
+At minimum you need `get_context`, `list_packages`, `execute_query`, and `search_malloy_docs`. Authoring a model also needs `compile_model` and `reload_package` (see section 4); an older Publisher may not serve those two.
 
 If none of the tools are there, either the server is not running or your client connected before it was. Start the server (`npx @malloy-publisher/server --port 4000`, or `bun run build && bun run start` from a clone) and wait until `curl -s http://localhost:4000/api/v0/status` reports `operationalState: serving`. If the point is to author models against a local package, add `--watch-env <env>`: without it Publisher copies local packages at boot and serves the copies, so saved edits are never read.
 
@@ -25,9 +25,9 @@ If you started the server yourself in this session, the tools still will not app
 Two escape hatches worth knowing:
 
 - **When the session cannot be relaunched from the workspace directory** (a project `.mcp.json` is only discovered by sessions that *start* in its directory), register the server at user scope so the directory stops mattering: `claude mcp add --transport http malloy http://localhost:4040/mcp -s user` (use the MCP port the server actually bound; its startup log prints it). Caveat: for sessions that do start in the workspace, the project `.mcp.json` shadows the user-scoped entry, so prefer the project file when it is discoverable.
-- **Do not trust an existing `.mcp.json`'s URL blindly.** The file outlives the server that wrote it, and a boot that failed partway (for example, the REST port was taken) can leave it pointing at a dead port while a live server sits on another. If connecting fails or answers look wrong, confirm identity with `malloy_getContext`, which names the environment and packages you are really talking to; that check works on every platform, which the port check does not (`lsof -iTCP:4040 -sTCP:LISTEN` on macOS and Linux, `netstat -ano | findstr :4040` on Windows).
+- **Do not trust an existing `.mcp.json`'s URL blindly.** The file outlives the server that wrote it, and a boot that failed partway (for example, the REST port was taken) can leave it pointing at a dead port while a live server sits on another. If connecting fails or answers look wrong, confirm identity with `list_packages`, which names the environment and packages you are really talking to; that check works on every platform, which the port check does not (`lsof -iTCP:4040 -sTCP:LISTEN` on macOS and Linux, `netstat -ano | findstr :4040` on Windows).
 
-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.
+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, `compile_model` instead of throwaway queries, and `reload_package` 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 (`search_malloy_docs` and `get_context`'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
 
@@ -81,41 +81,57 @@ that start failing auth after a long session mean the token expired, not that th
 
 ## 1. Discover what exists (never guess names)
 
-`malloy_getContext` is progressive. Call it with as much as you know:
+Two tools, in this order.
 
-- No arguments: the available environments, each with its package names.
-- `environmentName` only: the packages in that environment.
-- `environmentName` + `packageName`: that package's sources.
-- `environmentName` + `packageName` + `query` (plain English): the sources, views, named queries, and dimension/measure fields most relevant to the question.
+`list_packages` takes no arguments and returns every environment with its packages. That is where the environment and package names come from. It is also the only place a package that failed to load shows up, with the reason; a package missing from a plain listing looks like one that does not exist.
 
-Use the names it returns exactly. Do not invent environments, packages, sources, or fields.
+`get_context` retrieves against one package. Give it a `search_targets` entry per concept the question needs, and a `scopes` entry naming the environment and package:
+
+```json
+{
+  "search_targets": [
+    {"target_type": "measure", "search_text": "total revenue"},
+    {"target_type": "dimension", "search_text": "the product category"}
+  ],
+  "scopes": [{"environment": "examples", "package": "storefront"}]
+}
+```
+
+**One call answers.** The response groups the fields that matched under the sources holding them, so describing the fields is the whole search: there is no second call to drill into a source. Two variations are worth knowing:
+
+- Omit a target's `search_text` to enumerate that type instead of ranking it. A lone `{"target_type": "source"}` is the catalog browse, which returns a thin card per source (a one-line summary rather than the full doc) and pages with `offset` and `next_offset`.
+- Add `source` to the scope to narrow to one source, which is also how to read that source's full doc after a browse.
+
+`scopes` is required and takes exactly one entry, because retrieval is indexed per package.
+
+Use the names it returns exactly. Do not invent environments, packages, sources, or fields. A field reached through a join is named by its full dotted path; pass it verbatim rather than rebuilding it.
 
 ## 2. Run the query
 
-Call `malloy_executeQuery` with the `environmentName`, `packageName`, and `modelPath` from the context results, plus either:
+A retrieval response is a `sources` array. Each entry's `source_info.resource_id` carries `environment`, `package`, and `model_path`; pass them to `execute_query` as `environmentName`, `packageName`, and `modelPath`, plus either:
 
-- a named view or query: pass its `name` as `queryName` (with `sourceName` for a view), or
+- a named view or query: pass its `name` as `queryName` (with the card's `resource_id.source` as `sourceName` for a view), or
 - an ad-hoc query: pass Malloy code as `query`.
 
 The result is JSON. Charts and dashboards defined in the model render in the Publisher UI at http://localhost:4000.
 
 ## 3. When you need Malloy syntax
 
-Use `malloy_searchDocs` for language questions (filters, aggregates, joins, nesting, renderers).
+Use `search_malloy_docs` for language questions (filters, aggregates, joins, nesting, renderers).
 
-If the data you want is in a connected database but not yet in any package, use `malloy_searchDatabaseSchema` instead of `malloy_getContext`: it walks a connection's schemas and tables and ranks them against a plain-English description, and hands back the `source:` line to start a model from. It returns names and types only, so to see what a column actually contains run `malloy_executeQuery` against a model in a package that uses the same connection, with an ad-hoc query like `run: my_conn.table('sales.orders') -> { group_by: order_status }`. That tool needs an existing model to run against, so a table you have not modelled yet has none of its own.
+If the data you want is in a connected database but not yet in any package, use `search_database_schema` instead of `get_context`: it walks a connection's schemas and tables and ranks them against a plain-English description, and hands back the `source:` line to start a model from. It returns names and types only, so to see what a column actually contains run `execute_query` against a model in a package that uses the same connection, with an ad-hoc query like `run: my_conn.table('sales.orders') -> { group_by: order_status }`. That tool needs an existing model to run against, so a table you have not modelled yet has none of its own.
 
 ## 4. What else you can do here
 
 Answering questions is the start, not the whole surface. When the user asks what is possible, say so rather than offering queries alone. Switch skills for the deeper work:
 
-- `malloy-modeling`: build or change a model. Validate the edit with `malloy_compile`, save it, then `malloy_reloadPackage` so the new sources and views run by name without restarting the server.
+- `malloy-modeling`: build or change a model. Validate the edit with `compile_model`, save it, then `reload_package` so the new sources and views run by name without restarting the server.
 - `malloy-analysis`: explore a package and answer data questions.
 - `malloy-html-data-apps`: build a data app, a hand-authored HTML page in the package's `public/` directory that Publisher serves, backed by the package's models and needing no build step.
 - `malloy-review`: check Malloy for correctness.
 
 ## Contract
 
-- Ground every query in `malloy_getContext` results. If a name is not in the results, do not use it.
-- Start broad and narrow down: environments, then packages, then sources, then query.
+- Ground every query in `get_context` results. If a name is not in the results, do not use it.
+- With an environment and package in hand, ask the question in one call: the matching sources come back with their fields nested. `list_packages` and the catalog browse are for finding a name you are missing, not steps to walk first.
 - Confirm the environment and package before running a query.

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.13
+version: 0.1.16
 ---
 <!--
 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. 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.13
+version: 0.1.16
 ---
 <!--
 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.13
+version: 0.1.16
 ---
 <!--
 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.13
+version: 0.1.16
 ---
 <!--
 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.13
+version: 0.1.16
 ---
 <!--
 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.13
+version: 0.1.16
 ---
 <!--
 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.13
+version: 0.1.16
 ---
 <!--
 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.13
+version: 0.1.16
 ---
 <!--
 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.13
+version: 0.1.16
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -20,7 +20,7 @@ Assumes the `malloy-pub` CLI is on PATH and points at the server (`--url` or `MA
 
 Establish what the package persists today and how it is governed.
 
-- **Persist sources:** the sources annotated `#@ persist name="…"` in the package's `.malloy` files. Read the models (or `malloy_getContext` the package) to list them.
+- **Persist sources:** the sources annotated `#@ persist name="…"` in the package's `.malloy` files. Read the models (or `get_context` the package) to list them.
 - **Schedule + scope:**
 
   ```bash

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

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.13
+version: 0.1.16
 ---
 
 <!--

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.13
+version: 0.1.16
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -15,10 +15,10 @@ SPDX-License-Identifier: MIT
 ## Pre-Flight Checklist
 
 1. **Discover first**: ground yourself before writing ANY code, with the tool that matches what you are modelling.
-   - Modelling data **already in a package**: `malloy_getContext` returns that package's sources, views, and fields (with their docs).
-   - Modelling **a database with no package yet**: `malloy_getContext` has nothing to return, so use `malloy_searchDatabaseSchema` instead. It walks the connection's schemas and tables, ranks them against a plain-English description, and gives you each table's columns plus the `source:` line to start from. Take those names verbatim into step 5.
+   - Modelling data **already in a package**: `get_context` returns that package's sources, views, and fields (with their docs).
+   - Modelling **a database with no package yet**: `get_context` has nothing to return, so use `search_database_schema` instead. It walks the connection's schemas and tables, ranks them against a plain-English description, and gives you each table's columns plus the `source:` line to start from. Take those names verbatim into step 5.
    Never guess field names either way.
-2. **Search docs proactively**: call `malloy_searchDocs` BEFORE writing unfamiliar patterns (window functions, query-based sources, pipelines). Don't guess. Malloy syntax is specific and SQL intuition is often wrong.
+2. **Search docs proactively**: call `search_malloy_docs` BEFORE writing unfamiliar patterns (window functions, query-based sources, pipelines). Don't guess. Malloy syntax is specific and SQL intuition is often wrong.
 3. **Use `skill:malloy-patterns`** to discover available doc topics (YoY, cohorts, rendering, window functions).
 4. **Check diagnostics** after writing: fix the FIRST error first, errors cascade.
 5. **Read the gotcha skills**: `skill:malloy-gotchas-modeling`, `skill:malloy-gotchas-queries`, and `skill:malloy-gotchas-rendering` prevent the most common mistakes.
@@ -66,7 +66,7 @@ DISCOVER → SCOPE → SOURCES → DEFINITIONS → BUILD BASE → BUILD JOINED
 
 | Step | Skill | What Happens |
 |------|-------|-------------|
-| 1. Discover | `skill:malloy-discover` | Read the model and data; scan sources, fields, distributions; detect prior art. With no package yet, start from `malloy_searchDatabaseSchema` to find the tables in the connection |
+| 1. Discover | `skill:malloy-discover` | Read the model and data; scan sources, fields, distributions; detect prior art. With no package yet, start from `search_database_schema` to find the tables in the connection |
 | 2. Propose Scope | `skill:malloy-scope` | Present findings, user selects focus |
 | 3. Propose Sources | `skill:malloy-define` | Propose source plan, user confirms architecture |
 | 4. Propose Definitions | `skill:malloy-define` | Propose fields per base source, user confirms logic |
@@ -136,28 +136,28 @@ Ensure the Publisher MCP tools are configured before modeling. No server yet? `s
 
 | Tool | Purpose |
 |------|---------|
-| `malloy_getContext` | Ground yourself in a package: its sources, views, and fields |
-| `malloy_executeQuery` | Run ad-hoc queries for validation |
-| `malloy_compile` | Compile-check a change and get diagnostics back without running a query |
-| `malloy_reloadPackage` | Recompile a package from disk so a saved edit becomes queryable by name |
-| `malloy_searchDocs` | Search Malloy docs (call BEFORE unfamiliar patterns) |
-| `malloy_searchDatabaseSchema` | Find the tables in a database connection by plain-English description, when modelling data that is not in a package yet. Returns each table's columns and the `source:` line to start from. Names and types only: no row value is returned |
+| `get_context` | Ground yourself in a package: its sources, views, and fields |
+| `execute_query` | Run ad-hoc queries for validation |
+| `compile_model` | Compile-check a change and get diagnostics back without running a query |
+| `reload_package` | Recompile a package from disk so a saved edit becomes queryable by name |
+| `search_malloy_docs` | Search Malloy docs (call BEFORE unfamiliar patterns) |
+| `search_database_schema` | Find the tables in a database connection by plain-English description, when modelling data that is not in a package yet. Returns each table's columns and the `source:` line to start from. Names and types only: no row value is returned |
 
-Never guess field names. Ground yourself with `malloy_getContext` to see the sources and fields a package defines.
+Never guess field names. Ground yourself with `get_context` to see the sources and fields a package defines.
 
 ### The edit-and-run loop
 
 Publisher compiles each configured package at boot and serves that cached model, so a source or view you add afterwards is not queryable by name until you reload the package. The loop is:
 
-1. **Validate** the change with `malloy_compile`, picking the scope that matches what you are doing:
+1. **Validate** the change with `compile_model`, picking the scope that matches what you are doing:
    - Adding a new definition or query: the default (`scope: "append"`) compiles your text in the model's namespace. Note its diagnostic positions land in the model-plus-your-text concatenation.
    - **Editing an existing definition: `scope: "file"`**, with the whole edited file as `source`. It compiles your text AS the file (append would collide with "Cannot redefine"), and diagnostics land at the true line numbers of your text.
    - Before saving a change other files import: `scope: "package"` with the edited file as `source` runs reload's worker compiler over every `.malloy` and `.malloynb` file against your edit, so a rename that breaks an importer surfaces now instead of at reload. Each diagnostic carries `model`, the file it points at; files hidden from discovery can appear. If `modelPath` does not exactly match an existing file, a warning says the source was treated as new.
 2. **Save** it to the package's model file.
-3. **Reload** with `malloy_reloadPackage`.
-4. **Run** the new view with `malloy_executeQuery`.
+3. **Reload** with `reload_package`.
+4. **Run** the new view with `execute_query`.
 
-A reload that fails to compile is safe: your files are left alone and the previously compiled model keeps serving, with the compile errors returned to you. Compile first anyway for faster feedback, and a `scope: "package"` dry-run with no `source` uses reload's compiler and file selection (imports across files, every `.malloy` and `.malloynb` file as saved) without touching the served model. Keep the source of truth outside `publisher_data/`, which is not version-controlled and is wiped by a `--init` restart. If these tools are missing, the Publisher you are connected to predates them; fall back to validating with a throwaway `malloy_executeQuery`. An older Publisher that has `malloy_compile` but rejects `scope` supports only the append behavior.
+A reload that fails to compile is safe: your files are left alone and the previously compiled model keeps serving, with the compile errors returned to you. Compile first anyway for faster feedback, and a `scope: "package"` dry-run with no `source` uses reload's compiler and file selection (imports across files, every `.malloy` and `.malloynb` file as saved) without touching the served model. Keep the source of truth outside `publisher_data/`, which is not version-controlled and is wiped by a `--init` restart. If these tools are missing, the Publisher you are connected to predates them; fall back to validating with a throwaway `execute_query`. An older Publisher that has `compile_model` but rejects `scope` supports only the append behavior.
 
 ## SQL-to-Malloy Quick Reference
 

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

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.13
+version: 0.1.16
 ---
 <!--
 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.13
+version: 0.1.16
 ---
 <!--
 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.13
+version: 0.1.16
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -10,31 +10,15 @@ SPDX-License-Identifier: MIT
 
 # Search Target Construction for `get_context`
 
-The `get_context` tool description defines each field and the two-phase workflow (source discovery, then per-source entity drill-down). This skill focuses on the parts you won't get right by default: classifying concepts into target types and splitting ambiguous phrases.
+The `get_context` tool description defines each field and what a call returns. This skill focuses on the parts you won't get right by default: classifying concepts into target types and splitting ambiguous phrases.
 
 > **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.
 
-**Scope of this skill:** the patterns below mostly apply to **phase 2 (entity drill-down)**, building `dimension` / `measure` / `view` targets for a call scoped to a single source. Phase 1 (source discovery) is simpler: one or a few `source` targets describing the data domain, or a single `source` target with null `search_text` for listing. See the tool description for phase-1 guidance.
+**Scope of this skill:** the patterns below build `dimension` / `measure` / `view` targets. Phrasing for `source` targets is covered at the end.
 
 **A note on matching:** `get_context` searches over the model (sources, fields, views, and their descriptions), not the distinct categorical *values* stored in the data. To find which literal values a categorical dimension holds, target the dimension, then query its distinct values with `execute_query` (see the patterns below).
 
-## Authoring `search_text` for `source` targets (phase 1)
-
-Aim for **3-8 words that name the entity and its business process**. Don't include filter values, time ranges, or aggregations: those belong in phase-2 targets.
-
-| Too vague | Over-specific (phase-2-ish) | Good |
-|---|---|---|
-| `"orders"` | `"total order revenue by customer last year"` | `"customer order history and line items"` |
-| `"customer data"` | `"premium subscribers who churned in NYC"` | `"subscriber accounts and churn"` |
-| `"metrics"` | `"monthly revenue variance by account"` | `"sales pipeline and revenue forecasts"` |
-
-Heuristics:
-
-1. **Translate, don't echo.** "How did sales go last month?" becomes `"sales order revenue"`, not `"sales last month"`.
-2. **Differentiate by data shape or business process, not by the user's industry, brand, or product category.** Prefer `"order fulfillment and shipping"` over `"ecommerce data"` when multiple commerce-ish packages exist. Do NOT add words like `"eyewear"`, `"subscription box"`, `"Acme Corp"`, or the user's specific vertical/brand. Source summaries describe data structure, not the customer's vertical, so those words add noise and can hurt matching.
-3. **Retry with alternative phrasings** if the right source isn't in the results before concluding it's missing.
-
-## Authoring `search_text` for entity targets (phase 2)
+## Authoring `search_text` for entity targets
 
 Write `search_text` as a brief semantic **description** of what you're looking for, not an echo of the user's word. This applies even when you already know the entity name from a prior result: still describe it, don't just repeat the name.
 
@@ -48,7 +32,7 @@ One target per concept is enough: the tool handles phrasing variants internally.
   - "total revenue" becomes `"the total revenue or sales amount"`
 - **`view`**: pre-built analysis. Include one whenever the question sounds like a canned report (summary, breakdown, top-N, trend).
   - "sales summary" becomes `"a summary of sales metrics"`
-- **`source`**: data domain. Used during source discovery, not drill-down (see tool description).
+- **`source`**: data domain, for a question that names a subject area rather than fields (phrasing below).
 
 **Resolving categorical values (no value-search target in v1).** When the user names a literal value like "premium" or "New York City", target the *dimension* it lives on (`"the subscription tier"`, `"the city where the subscriber lives"`). Then confirm the exact stored string by querying that dimension's distinct values with `execute_query` before you filter on it. The data may store `"Premium"`, `"PREMIUM"`, `"NYC"`, or `"New York"`, and only the data tells you which.
 
@@ -64,11 +48,11 @@ These are the rules you won't apply correctly by default:
 6. **"Top N" without a named measure, add a ranking measure.** "top 6 products" becomes a measure for the ranking concept (`"the performance metric for a product"`) plus a dimension for the entity. If the measure is explicit ("top products by total sales"), use it directly and skip the generic ranking measure.
 7. **Multiple values for one concept, one dimension target.** Several values ("premium and basic") still map to a single dimension target for the parent field; enumerate the exact stored values with `execute_query`.
 
-## Worked example (drill-down call)
+## Worked example
 
 **User:** "Customer churn in NYC over the last year for premium and basic subscribers"
 
-After source discovery surfaces a `subscriptions` source, the drill-down targets for the call scoped to it (`scopes` set to that source) are:
+The targets for this question:
 
 | target_type | search_text |
 |---|---|
@@ -78,4 +62,22 @@ After source discovery surfaces a `subscriptions` source, the drill-down targets
 | `dimension` | `"the tier of the subscription"` |
 | `view` | `"subscriber churn or retention analysis"` |
 
-Key moves: time ("last year") becomes a dimension on the cancellation date; "NYC" and "premium/basic subscribers" do not get their own value targets, they resolve to the city and tier dimensions. Once `get_context` returns those dimensions, run `execute_query` to read their distinct values and confirm the exact strings to filter on ("New York City" vs "NYC", "premium" vs "Premium"). One `view` target is included to surface any canned churn analysis.
+Key moves: time ("last year") becomes a dimension on the cancellation date; "NYC" and "premium/basic subscribers" do not get their own value targets, they resolve to the city and tier dimensions. One `view` target is included to surface any canned churn analysis.
+
+The response returns the source these fields live on (here `subscriptions`) with the matched fields on its card. Then run `execute_query` to read the city and tier dimensions' distinct values and confirm the exact strings to filter on ("New York City" vs "NYC", "premium" vs "Premium").
+
+## Authoring `search_text` for `source` targets
+
+Aim for **3-8 words that name the entity and its business process**. Don't include filter values, time ranges, or aggregations: those belong in entity targets.
+
+| Too vague | Over-specific (entity-shaped) | Good |
+|---|---|---|
+| `"orders"` | `"total order revenue by customer last year"` | `"customer order history and line items"` |
+| `"customer data"` | `"premium subscribers who churned in NYC"` | `"subscriber accounts and churn"` |
+| `"metrics"` | `"monthly revenue variance by account"` | `"sales pipeline and revenue forecasts"` |
+
+Heuristics:
+
+1. **Translate, don't echo.** "How did sales go last month?" becomes `"sales order revenue"`, not `"sales last month"`.
+2. **Differentiate by data shape or business process, not by the user's industry, brand, or product category.** Prefer `"order fulfillment and shipping"` over `"ecommerce data"` when multiple commerce-ish packages exist. Do NOT add words like `"eyewear"`, `"subscription box"`, `"Acme Corp"`, or the user's specific vertical/brand. Source summaries describe data structure, not the customer's vertical, so those words add noise and can hurt matching.
+3. **Retry with alternative phrasings** if the right source isn't in the results before concluding it's missing.

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.13
+version: 0.1.16
 ---
 <!--
 Copyright (c) Credible Data Inc.
@@ -77,7 +77,7 @@ Two optional fields opt the package into curation:
 
 **Why curate here:** declaring `explores` routes agents to the well-documented curated sources instead of raw tables, and `queryableSources: "declared"` keeps them from reaching the hidden sources by name. The two axes compose: list a file in `explores` for its models to be discoverable, and `export` a source within that file for it to be a landing point.
 
-> **Not access control.** `queryableSources` gates the query surface (the query endpoints, REST and MCP alike), not compile and not raw file retrieval by exact path: `/compile` and `malloy_compile` are deliberately exempt, because compile is the authoring loop and the boundary is discovery curation. It doesn't restrict *who* may query, only *what* is queryable by name. Queryable sources are the union of every `explores`-listed file's `export {}` closure, whichever listed model path a query addresses them through. To gate access by caller-supplied identity/role, use `#(authorize)` on the source, see `skill:malloy-model` § Access Control and `docs/authorize.md`. Discovery curation and `#(authorize)` are independent layers.
+> **Not access control.** `queryableSources` gates the query surface (the query endpoints, REST and MCP alike), not compile and not raw file retrieval by exact path: `/compile` and `compile_model` are deliberately exempt, because compile is the authoring loop and the boundary is discovery curation. It doesn't restrict *who* may query, only *what* is queryable by name. Queryable sources are the union of every `explores`-listed file's `export {}` closure, whichever listed model path a query addresses them through. To gate access by caller-supplied identity/role, use `#(authorize)` on the source, see `skill:malloy-model` § Access Control and `docs/authorize.md`. Discovery curation and `#(authorize)` are independent layers.
 
 The manifest also carries a `scope` field (`"package"` | `"version"`, default `"package"`) controlling whether persisted/materialized artifacts are shared across published versions or owned by a single version, and a `materialization` field configuring that persistence policy (a cron `schedule` or a `freshness` window). Both are unrelated to discovery curation; there is no per-source `sharing` or `schedule` field, that was retired in favor of the single package-level `scope` and `materialization`.
 

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

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