Build a page from a question (starter blueprint)

Slug: viz-page-from-query Type: agent_blueprint Source: code-defined; appears in every tenant's agent_blueprint://list automatically. Fork via agents.fork_blueprint to customize. Outputs: one Page (a pages row — NOT an artifact)

The Build-a-page starter turns a plain-language question into a published, data-bound Page — the page analog of the artifact-emitting starters. Give it a question; it decides whether the answer is one full-bleed visualization or a small dashboard, picks catalog components, grounds the SQL in your real column values, authors the spec, validates it, and publishes a Page you open in the console over live data.

It is the blueprint wrapper around the same pages authoring loop documented in Authoring a Page via MCP — packaged so an agent can go from question to published page in one recipe.

When to use it

• Someone asks "show me X" and the right answer is a chart or a small dashboard, not prose — a win-rate gauge, a pipeline funnel, ACV-by-stage bars.
• You want a repeatable "question → published page" path an agent can walk, instead of hand-authoring a spec each time.
• You want the page authored against the tenant's REAL data (stage names, categories), not guessed labels.

What it produces

One Page (stored on the pages table, not platform_artifacts). The blueprint's data output carries the new page's identifiers so a downstream caller can open it:

{
  "page_id": "<uuid>",
  "slug": "<url-safe-slug>",
}

Open it in the console, or read it back over page://<id>. The page renders live, per-viewer, scoped to what the viewer is allowed to see (see Page data model).

Inputs

How it runs

4 top-level steps:

1. plan — llm. Read the question and decide the page SHAPE (single full-bleed viz vs small dashboard), which catalog viz types fit, and what each needs from the data.
2. probe_data — tool (data.query). Run ONE grounding query over the interactions view (e.g. SELECT DISTINCT deal_stage_normalized ...) so the authored SQL uses the tenant's REAL column values, not guessed labels.
3. author_page — llm. Author the full PageSpec (catalog node tree + $query / $value bindings) AND its tenant-agnostic declared_queries (SELECT-only over interactions). Composes prompt://pages/page_authoring (the spec contract + the validate→fix loop) + prompt://researcher/metric_grounding (so every number is grounded).
4. create_page — tool (pages.create). Publish the authored spec + declared queries. The host validates the spec before it persists; on a validation_failed rejection the agent reads the per-stage verdict, fixes the offending node / query in author_page, and retries.

The blueprint composes catalog-only pages — it never emits a Custom sandbox node (that needs pages:admin, off the default bundle). Its policy.tool_allowlist (data.query, pages.create) is GUIDANCE the reading agent respects as it walks the recipe; the API key's scope grammar is the real safety boundary. On the interactive MCP surface there is no run-blueprint tool that enforces the allowlist — the conversational agent IS the runner. (The headless SDK runner that powers unattended/scheduled/backtest runs auths against /mcp with a least-privilege scoped token, so the scope grammar bounds it too. See docs/blueprint-runner-sdk.md.)

Who can run it (important)

Authoring a Page needs the pages:write scope, which is on the MCP customer-agent bundle — so this starter runs from an MCP client (Claude Desktop, Cursor, an external agent) whose key carries pages:write.

It is not reachable from the in-app copilot or the other Anthropic-side profiles: none of their scope bundles grant pages:*, by design. Page authoring lives on the MCP surface, not the in-app agent surface. If you walk this recipe from the in-app copilot it will fail at the create_page step.

Forking it

Any tenant can fork this starter via agents.fork_blueprint (or artifacts.create artifact_type=agent_blueprint). Common forks:

• Pin the layout — hardcode prefer_single_viz and drop the input if your team always wants single-viz (or always wants dashboards).
• Add a non-SQL source — extend author_page to bind a cluster_search or kb_search query (a page query can draw from those too, not just SQL).
• Pre-seed a template — start author_page from a vetted page_template://<slug> instead of a blank spec.

Limits

• Page SQL is SELECT-only over the whitelisted views and must be tenant-agnostic (no business_id — the host injects the tenant filter + the per-viewer access predicate). The same validator as the Data Explorer rejects anything else.
• Rendering happens in the console, for a human viewer — there is no "run this page and give me the pixels" step. The blueprint ends at pages.create; opening the page is a separate console / page:// read.
• The created page is a draft; it shows for everyone the page's grants allow (no grants ⇒ every member who can see the Pages section).