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.
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, #(authorize), 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. |
| Doc | Read it when you want to… |
|---|
| publisher-app.md | Navigate the built-in web app and see how the constructs surface. |
| explorer.md | Build queries with the no-code visual query builder. |
| 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 App 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: + #(authorize)). |
| authorize.md | Gate who can query a whole source with #(authorize). |
| discovery-and-access.md | Control what is discoverable and queryable (explores / queryableSources) — 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. |
| 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. |
The complete user guide lives at
docs.malloydata.dev/documentation/user_guides/publishing.