publisher: Instructions file for Codex

Working with Malloy Publisher

Publisher is the analytics engine for Malloy, created and maintained by Credible. It serves one or more Malloy model packages over a REST API and a single MCP endpoint. If you are an AI agent working in this repo, here is what you can do with it and how to start.

The fast path. Everything below is detail on these four steps:

1. Start a server (section 1) and poll GET http://localhost:4000/api/v0/status until operationalState is "serving".
2. Make sure your MCP client is connected to http://localhost:4040/mcp (section 2). If you started the server yourself in this session, your Malloy tools will not appear until the user reconnects the client; unattended, use REST (section 7).
3. Call list_packages for the environment and package names, then get_context scoped to one package with your question (section 4).
4. Run execute_query with the names it returned, verbatim.

What you can do

• Discover what data exists: environments, packages, models, sources, and fields, without knowing any names in advance.
• Answer plain-English questions by running Malloy queries, which Publisher compiles to SQL and runs against the connected database.
• Build and change Malloy models: validate an edit with compile_model, save it, then reload_package to run it by name. The malloy-modeling skill covers the workflow.
• Build a data app: a hand-authored HTML page in a package's public/ directory, backed by that package's models and served by Publisher with no build step. The malloy-html-data-apps skill covers it.
• Review Malloy for correctness with the malloy-review skill.
• Measure whether an agent can actually answer questions against a model, with the eval-loop skill: it scores answers against verified goldens, reports which entities retrieval delivered, diagnoses each failure and who owns it, and builds a servable report. examples/storefront/evals/storefront-tour is a worked example over the bundled storefront package: twelve questions and an answer key, each golden derived twice. Its README has the exact commands. The set is the questions and the key; running it, and whatever the run produces, is yours.
• Build a report: a .malloy file with an ## artifact tag is a report, a page of query and text tiles behind filter controls with drill click-through, no code and no build step. Its layout= is the one choice: grid for a dashboard scanned at a glance, linear for a story read top to bottom. A report can live anywhere in the package; write a new one at the package root unless asked otherwise, and point # drill { to="path/without-extension" } at another report by its path. People who want the classic drag-and-drop feel can build the same file in the Console instead — drag a tile to move it, drag any edge or corner to resize it — and the two are interchangeable, because the builder splices the file rather than owning a layout document of its own. The malloy-reports skill covers it; docs/reports.md is the reference, and docs/choosing-a-surface.md says when to pick a report, which layout, or a data app.
• Govern access: givens declare runtime parameters that drive filter widgets, row-level access decides which rows a caller sees, #(authorize) decides whether a caller may query a source at all, and discovery curation — a package's index.malloy — decides what is visible, and queryable, in the first place. The bundled governed-analytics package shows all four together.
• Materialize for cost and speed: one #@ persist annotation turns an expensive source into a table, rebuilt on demand, from the malloy-pub CLI, or on a cron with the opt-in scheduler; #@ preaggregate rolls a measure up to a coarse grain. The malloy-materialization skill covers it; docs/materialization.md and docs/preaggregation.md are the references.
• Model a warehouse from scratch: add a connection (BigQuery, Snowflake, Postgres, MySQL, SQL Server, Trino, Databricks, MotherDuck, DuckLake, and more), then search_database_schema ranks its tables against a plain-English description and hands back the source: line for each. DuckDB is built in for CSV, Parquet, JSON, and Excel files.
• Browse it all in the Publisher Console, the built-in web UI on the REST port (docs/console.md), where charts and dashboards defined in the model render.