feat(pages): make agents offer pages and answer "what do you want to create?"
Links
- Linear: SUPER-2187 — Pages need onboarding
- Parity study: Pages onboarding — parity study
Summary
- Agents offer a page unprompted.
plugins/superset/skills/page/SKILL.mdnow tells agents to offer publishing when they finish something with a reader and a link: a change walkthrough, a comparison, a report, an incident writeup, verification screenshots. One line, then stop and wait — never a silent publish, and explicitly quiet for ordinary replies. - Five named starters replace the open-ended question. Each pre-fills the prompt through plumbing that already existed and was never used.
- The empty state shows a page before asking for one. A miniature rendered page built from
PageThumbnail's frame, aspect ratio and tokens.
Why / Context
Pages has the hard part working: a teammate pins a comment on a published page and it routes back to an agent that can republish. The cold start is the opposite. PagesGrid rendered an icon, one line of copy and a single Create with AI button; useCreatePageWithAgent teleports you into a fresh workspace; buildPageAgentPrompt then has the agent ask "what do you want to create?".
The parity study compared this to Claude Artifacts, Claude Code Artifacts and Plannotator. We score zero on three rows, and they are the same failure: nothing happens until the user already knows what a page is. Nobody proposes a page to you, nothing suggests what one could be.
How It Works
Item 1 — agents offer a page (plugins/superset/skills/page/SKILL.md)
A new "Offer one before you are asked" section under "When a page is the right surface". It lists the output shapes that earn an offer, gives the one-line form of the offer, and is bounded on both sides so it cannot become a nag: stay quiet for ordinary replies, treat a turned-down offer as a standing preference for the session, and skip the offer entirely when the user asked for a page outright. The frontmatter description also names the unprompted case, so the skill loads when an agent finishes reader-facing output rather than only when someone says "page".
No em dashes anywhere in the file (packages/agent-setup has a test that fails the build on one).
Item 2 — starters (PagesEmptyState/starters.ts)
buildPageAgentPrompt(request?) already had a tested branch for a request and had only ever been called with none. useCreatePageWithAgent now takes a request?: string and forwards it, and each starter sends its own text. The five: walk through a change, compare design options, build an incident timeline, write a status report, draft a proposal.
Request text stays English alongside the rest of pageAgentPrompt.ts (it is agent instruction, not interface copy); the button labels go through Lingui like everything else. Every starter's request ends by naming what the agent still needs to ask for, so the prompt is a shape rather than a guess.
FeatureHeader calls onCreate straight from onClick, so PagesView wraps it (() => handleCreateWithAgent()) — otherwise a MouseEvent would arrive where a request string is expected.
Item 3 — preview (PagesEmptyState/components/PagePreview)
A miniature rendered page inside PageThumbnail's own frame: same bg-muted container, same THUMBNAIL_ASPECT_RATIO, same card footer shape. Inside it: an eyebrow, a title, prose, stat tiles, a column chart, a pinned-comment badge, and "Version 3" in the footer — so the comment loop and the versioning are things you can see rather than read about. Entirely layout and theme tokens, no raster assets, no new colours or spacing scales.
Preview, copy, starters and button are laid out as one block. The "no results" case keeps its own smaller Empty treatment, which is why that branch got simpler rather than richer.
Before / After
Before

After

Both captured over CDP against the dev app in this worktree (renderer :3785, API :3781, signed in as the seeded local dev account), at the same 1180x780 emulated viewport, with FEATURE_FLAGS.PAGES overridden on so the route resolves instead of redirecting to /v2-workspaces.
Manual QA
- Empty state renders the preview, five starters and the button; everything fits above the fold at 1180x780
- Clicking Walk through a change creates a workspace whose generated name is "Create and publish Superset change walkthrough page" — the starter's request reached the prompt
- The plain Create with AI path still sends no request
- The filtered "No pages match" empty state still renders (unchanged copy, no create button, which is how it was)
- Preview is built only from semantic tokens (
border,muted,muted-foreground,foreground,background), so it inverts with the theme
Not verified: the agent's opening turn itself. The terminal in the spawned workspace stayed empty in this local dev stack, so I could not screenshot the difference in what the agent says first. The workspace name above is the evidence that the request is carried; the prompt-level assertion is covered by the tests below.
Testing
bun run lint:fix— cleanbunx sherif --fix— no issuesbun run typecheck— passbun run test— desktop suite: 7556 pass, 36 fail. All 36 fail identically onorigin/mainin this environment (git worktree, shell env and terminal-transport suites); this branch adds 4 passing tests and zero failures.bun run check:i18n— pass, all 16 non-English catalogs translated by hand and committedbun run check:plugins— "All plugins are valid and published"bun test packages/agent-setup/src/bundled-skills.test.ts— 92 pass (covers the em-dash and body-length rules on the skill)
New tests in PagesEmptyState.test.tsx cover: one button per starter plus the blank path, a starter's request reaching buildPageAgentPrompt and displacing the "ask what I want to create" branch, the blank path sending no request, and everything disabling while a workspace is being created.
Design Decisions
- Starter request text is not translated. It is handed to the agent verbatim, so it lives in the same English register as
pageAgentPrompt.ts, which carries the same note. Only the labels are catalog messages. - Illustration over a real thumbnail. There is no page to screenshot in the empty state, and a committed raster would go stale and cost bytes. The preview is markup over the same frame
PageCarduses. - The offer is bounded in the skill, not in code. Item 1 is agent behaviour; putting the restraint in prose beside the trigger is the only place that reaches every agent reading the skill.
Out of Scope
Items 4-7 of the parity study are deliberately not in this PR:
- Teaching the comment loop at publish time, in situ
- Closing the workspace to page loop
- Saying what a page is not, and what org-visible means
- Not building a wizard (a standing constraint, nothing to build)
Summary by cubic
Enhances Pages onboarding so first-time users can feel the product and answer their own "what do you want to create?" prompt.
- Agents now offer to publish reader-facing work (change walkthroughs, comparisons, reports, incident writeups, verification screenshots) with a one-line offer, never publishing silently.
- The empty state shows a miniature rendered page and five named starters that pre-fill the agent prompt; the plain "Create with AI" path still sends no request. The tips are translated, starter text stays in English.
- The "No pages match" filtered state is unchanged.
- Adds cross-locale tests so the remaining ambiguous strings get caught in the same pass.
Summary by CodeRabbit
-
New Features
- Added a new Pages empty state with a preview, “Create with AI,” and guided starter actions.
- Added starter prompts for walkthroughs, design comparisons, incident timelines, status reports, and proposals.
- Custom instructions can now be passed when creating a page with AI.
- Improved filtered results messaging with a clearer “No pages match” state.
-
Bug Fixes
- Creation controls are disabled while a page is being generated.
-
Documentation
- Updated page guidance to offer publication for reader-facing outputs, with confirmation safeguards.
-
Localization
- Added translations for the new page creation experience across supported languages.