Start at the project README for the 60-second quick start. This folder holds the
deeper reference. If you're an AI agent, read AGENTS.md first — it's the canonical
guide to running Publisher and connecting over MCP.
Publisher is created and maintained by Credible, the company
behind the AI Analytics Engine. For where the open-source engine ends and Credible's hosted engine
begins, see credibledata.com/malloy.
Three runnable packages ship in the default examples environment, plus one standalone React app —
every doc below points back to one of them, and each example's README points back to the docs.
| Example |
What it shows |
| storefront |
A complete ecommerce model — joins, measures, # dashboard views, and a no-build HTML app. The flagship first-open package. |
| governed-analytics |
Givens, #(access_filter), row-level access, and discovery curation in one small package. |
| html-data-app |
A no-build SaaS-subscriptions dashboard served from a package's public/ directory. |
| data-app |
Advanced/internal: a standalone React app built on the SDK, reading from storefront. Not a served package — run it with Vite. |
| Doc |
Read it when you want to… |
| architecture.md |
Understand how Malloy, Render, Publisher, and the SDK fit together. |
| api-overview.md |
Understand the REST + MCP surfaces and the resource hierarchy. |
| packages.md |
Understand the package format: publisher.json, models, data files, and how a package gets served. |
| scaffolding.md |
Scaffold a package with npm create — the @latest rule, the workspace it writes, seeding from a file. |
| dbt-roadmap.md |
See how Malloy and dbt fit together, where the gaps are, and the plan to close them. |
| Doc |
Read it when you want to… |
| console.md |
Navigate the Publisher Console, the built-in web UI, and see how constructs surface. |
| explorer.md |
Build queries with the no-code visual query builder. |
| choosing-a-surface.md |
Pick between a report (and its layout, linear or grid) and an HTML data app. |
| reports.md |
Build a report, linear or grid, by dragging tiles in the Console or by writing its .malloy file. |
| ai-agents.md |
Connect an AI agent, over MCP or (unattended) over REST, and ground it in your models. |
| html-data-apps.md |
Ship a no-build HTML dashboard inside a package, hosted by Publisher. |
| embedded-data-apps.md |
Advanced/internal: the React SDK the Console is built from. |
Runtime parameters and access control all build on one mechanism — givens. Start
there for the primitive, then follow the application you need.
| Doc |
Read it when you want to… |
| givens.md |
Learn the base mechanism — declare runtime parameters, drive filter widgets, and reach access control. |
| row-level-access.md |
Restrict which rows a caller sees (given-scoped where: + #(access_filter)). |
| authorize.md |
Gate who can query a source, and which rows they get, with #(access_filter). |
| discovery-and-access.md |
Control what is discoverable and queryable (index.malloy) — the visibility axis. |
| security-posture.md |
Understand what Publisher does and does not defend against, before deploying it or adding a feature. |
| Doc |
Read it when you want to… |
| deployment.md |
Run a built server via npx, Docker, or Docker Compose. |
| connections.md |
Connect BigQuery, Snowflake, Postgres, DuckDB, and more. |
| materialization.md |
Persist Malloy sources into tables — the publish-gate rules, on-demand + scheduled builds, the malloy-pub CLI, and standalone-vs-hosted behavior. |
| preaggregation.md |
Roll a measure up to a coarse grain with #@ preaggregate so covered queries read a small table — what can be pre-aggregated, what routes, and what it costs. |
| query-metadata.md |
Tag the statements Publisher sends so the backend's own reporting can attribute them — layers, the contract, and correlating an API call with a backend query. Off unless PUBLISHER_QUERY_METADATA=on. |
| ducklake.md |
Attach a DuckLake catalog (read-only), understand catalog-format compatibility, and run offline / air-gapped. |
| persist-storage-tutorial.md |
Materialize a #@ persist source into a DuckLake storage destination and serve queries from it (the storage= tier + the PERSIST_STORAGE_MODE switch). |
| theming.md |
Customize colors, fonts, and light/dark mode. |
| configuration.md |
Look up an env var / CLI flag, or tune the OOM guards. |
| Doc |
Read it when you want to… |
| development.md |
Build and hack on Publisher from a clone. |
| agent-skills/ |
Author or contribute the bundled agent skills. |
| ../SECURITY.md |
Report a security vulnerability, or check what's in scope. |
| malloyyo-dashboards-design.md |
Design doc: the grammar and architecture behind Publisher's dashboards, now grid reports. |
| dashboard-builder-plan.md |
Plan: the dashboard builder and the .malloy notebook — research, gaps against the state of the art, how the builder is built, the notebook format and its builder, and the steps for each gap. |
| reports-design.md |
Design doc: dashboards and notebooks as one document type, the report, with a linear or grid layout, anywhere in a package. |
The complete user guide lives at
docs.malloydata.dev/documentation/user_guides/publishing.