@jxsuite/studio 5.5.0 → 5.6.0

package/src/publish/pages-service.ts

@@ -1,11 +1,10 @@
 /// <reference lib="dom" />
 /**
- * Pages-service — Cloudflare Pages publish domain logic over the PAL's
- * `cfApi` passthrough. Works identically on every platform that provides it:
- * the dev server / desktop (user API token via cf-settings → /__studio/cf/proxy)
- * and the cloud platform (hosted OAuth). Publish state is written to
- * project.json `build.deploy` — it travels with the repo, so any Studio can
- * tell whether the publish workflow already exists.
+ * Pages-service — Cloudflare Pages publish domain logic over the PAL's `cfApi` passthrough. Works
+ * identically on every platform that provides it: the dev server / desktop (user API token via
+ * cf-settings → /__studio/cf/proxy) and the cloud platform (hosted OAuth). Publish state is written
+ * to project.json `build.deploy` — it travels with the repo, so any Studio can tell whether the
+ * publish workflow already exists.
  *
  * @license MIT
  */
@@ -13,6 +12,7 @@
 import { updateWranglerConfig } from "@jxsuite/create/scaffold";
 import type { DeployConfig, ProjectConfig } from "@jxsuite/schema/types";
 import { getPlatform } from "../platform";
+import { actIfRequired } from "../account/action-flow";
 import { updateSiteConfig } from "../site-context";
 
 export interface CfAccount {
@@ -52,12 +52,22 @@ export function platformSupportsPublish(): boolean {
   }
 }
 
+/**
+ * One Cloudflare call. A refusal that offers an action (desktop.md §10.4) is offered here, once for
+ * every publish step, and still thrown: the step that asked failed, and its caller reports that in
+ * its own words while the offer says how to fix it.
+ */
 async function cfApi<T>(path: string, init?: { method?: string; body?: unknown }): Promise<T> {
   const api = getPlatform().cfApi;
   if (!api) {
     throw new Error("This platform cannot reach the Cloudflare API");
   }
-  return (await api(path, init)) as T;
+  try {
+    return (await api(path, init)) as T;
+  } catch (error) {
+    void actIfRequired(error);
+    throw error;
+  }
 }
 
 export async function listAccounts(): Promise<CfAccount[]> {

package/src/services/ai-models.ts

@@ -2,17 +2,17 @@
 /**
  * Ai-models.js — available-model listing from the studio AI proxy.
  *
- * Fetches the proxy's /models endpoint (the chat endpoint's sibling), forwarding the
- * stored API key as X-Api-Key and the endpoint override as X-Api-Base-URL so the proxy
- * lists models from the user's chosen provider. Shared by the credentials form and the
- * chat composer's model picker; results are cached module-wide until invalidated (e.g.
- * after credentials change).
+ * Fetches the proxy's /models endpoint (the chat endpoint's sibling), forwarding the stored API key
+ * as X-Api-Key and the endpoint override as X-Api-Base-URL so the proxy lists models from the
+ * user's chosen provider. Shared by the credentials form and the chat composer's model picker;
+ * results are cached module-wide until invalidated (e.g. after credentials change).
  *
  * @license MIT
  */
 
-import type { AiModelsResponse } from "@jxsuite/protocol";
+import type { AiModelsResponse, OfferedAction } from "@jxsuite/protocol";
 import { getPlatform } from "../platform";
+import { offeredActions } from "../platform-errors";
 import { getBaseUrl, getOpenAiKey, hasOpenAiKey, storedModel } from "./ai-settings";
 import { SETTINGS } from "./settings/definitions";
 import { onSettingsChanged } from "./settings/kernel";
@@ -76,6 +76,14 @@ let proxyManaged = false;
 let proxyDefaultModel = "";
 let proxyCode: AiModelsResponse["code"];
 let proxyModelsError = "";
+/** What an `action_required` probe offered; null for every other answer. */
+let proxyAction: ProxyActionOffer | null = null;
+
+/** What a managed backend says the assistant needs first, in the backend's own words. */
+export interface ProxyActionOffer {
+  detail?: string;
+  actions: OfferedAction[];
+}
 
 /**
  * One-shot capability probe shared by every credentials gate, plus the hosts to repaint when it
@@ -118,6 +126,7 @@ export function resetModelCache() {
   proxyDefaultModel = "";
   proxyCode = undefined;
   proxyModelsError = "";
+  proxyAction = null;
   /* The probe's result IS the flags above. Clearing them while keeping the settled promise
      would strand every gate on a permanent "unconfigured, unmanaged" reading — ensureProxyProbe
      would no-op forever and the managed option would vanish until a full reload. */
@@ -278,6 +287,14 @@ export function proxyModelsErrorMessage(): string {
   return proxyModelsError;
 }
 
+/**
+ * The offer the last probe carried — set only when the backend answered `action_required` (ai.md
+ * §2.1), and null for every other answer, so no gate can offer an action the backend did not name.
+ */
+export function proxyActionOffer(): ProxyActionOffer | null {
+  return proxyAction;
+}
+
 /** The proxy's preferred model id ("" when it does not declare one). */
 export function getProxyDefaultModel(): string {
   return proxyDefaultModel;
@@ -369,6 +386,13 @@ export async function fetchAvailableModels(
   proxyDefaultModel = data.defaultModel ?? "";
   proxyCode = data.code;
   proxyModelsError = data.upstreamError !== undefined ? (data.upstreamMessage ?? "") : "";
+  proxyAction =
+    data.code === "action_required"
+      ? {
+          actions: offeredActions(data.actions),
+          ...(typeof data.detail === "string" && data.detail ? { detail: data.detail } : {}),
+        }
+      : null;
   /* Capabilities are kept, not dropped. The backend has reported `toolSupport` all along and the
      ingest mapped `{id, name}` only, so a Workers AI model that cannot call tools looked exactly
      like one that can — the agent loop ran, called nothing, and answered as if that were normal.

package/src/services/ai-system-prompt.ts

@@ -1,8 +1,8 @@
 /**
  * Ai-system-prompt.js — Dynamic system prompt builder for the Jx AI assistant
  *
- * Constructs the system prompt based on the current project context, open document,
- * and available components. The quality of AI output depends critically on this file.
+ * Constructs the system prompt based on the current project context, open document, and available
+ * components. The quality of AI output depends critically on this file.
  *
  * @license MIT
  */
@@ -656,6 +656,75 @@ When asked to build a site with multiple pages:
 
 // ─── System prompt builder ───────────────────────────────────────────────────
 
+const ROLE = `You are an expert Jx builder assistant embedded in Jx Studio. You help users build websites, components, pages, and layouts using the Jx JSON schema. The live jxsuite.com marketing site is built entirely with Jx — you can produce production-quality Jx code.`;
+
+/**
+ * What to do when a tool call fails. Static: it names tools and validation messages, never the
+ * state, so it belongs to the cacheable prefix rather than after the dynamic sections.
+ */
+const ERROR_RECOVERY = `## Error Recovery
+
+If a tool call fails (returns { success: false }):
+1. Read the error message carefully — it includes a "→ Fix:" hint telling you exactly how to correct the error.
+2. Each error points to a specific path in the document and a specific rule violation.
+3. Apply the suggested fix using set_property, delete_node, or add_child as appropriate.
+4. Do NOT re-issue the exact same tool call with the same arguments — you must CHANGE something.
+5. If you see the SAME error after 2 attempts, try a completely different approach (e.g., remove and re-add the node instead of patching it).
+
+### Common validation errors and their fixes:
+
+| Error pattern | What happened | How to fix |
+|---|---|---|
+| "must NOT have additional property" in style | You used a non-camelCase CSS property (e.g. "background-color") or put an HTML attribute directly on the element. | Use camelCase: "backgroundColor". Put aria-*, data-*, role, and other non-IDL attributes inside the "attributes" object: { "attributes": { "aria-label": "..." } } |
+| "must match pattern" on tagName | A custom element tag name doesn't contain a hyphen. | Add a hyphen: "newsletter-form" not "newsletter". Standard HTML elements use their exact name ("div", "p", "input"). |
+| "must be string" | A value is an unquoted number, boolean, or bare word. | Wrap the value in quotes: "10px" not 10px. All CSS values and text must be strings. |
+| "must be number" / "must be integer" | A numeric field (like index, tabIndex) is wrapped in quotes. | Remove the quotes: use 0 not "0". |
+| "must have required property" | A required field is missing from the node. | Add the missing property. Every element must have "tagName". |
+| "must be object" | A field that expects an object (like style or attributes) received a string or other type. | Use {} not a string. |
+| "No node exists at path" | The path you provided doesn't point to an existing node. | Call read_document first to see the current structure and valid paths, then use the correct path. |
+
+### If you keep getting errors:
+- Call read_document again — the document may have changed since you last read it.
+- Remove the problematic node entirely with delete_node, then re-create it correctly with add_child.
+- If the error message points to a different path than you expected, the node might have moved due to previous edits.`;
+
+/** What every section of the prompt is joined with. */
+const SECTION_SEPARATOR = "\n\n---\n\n";
+
+/**
+ * The part of every system prompt that does not depend on the state, byte for byte: the role, the
+ * Jx reference sections, and the error-recovery guidance, each followed by the section separator.
+ *
+ * It exists for providers' prompt caches. A cache matches on a PREFIX of the request, and the
+ * system prompt is the request's first message, so the reference material (most of the prompt's
+ * tokens) only hits when nothing that changes between rounds comes before it. The prompt used to
+ * open with the role, the workflow for the current state and its tool list, so opening a document
+ * or registering one more command tool moved the first changed byte to the second paragraph and
+ * every request after it paid for the whole reference again. Everything dynamic — the mode, the
+ * tool list, the document, project and file summaries — now follows this prefix, and the closing
+ * instructions stay last. {@link buildSystemPrompt} always starts with it, and its tests hold that
+ * for every combination of the state flags.
+ */
+export const SYSTEM_PROMPT_STATIC_PREFIX =
+  [
+    // 1. Role
+    ROLE,
+    // 2. Jx schema reference — kept in ALL modes (pre-project the model plans starter content)
+    JX_SCHEMA_REFERENCE,
+    // 2a. State shape decision tree
+    STATE_SHAPE_DECISION_TREE,
+    // 2b. Real-world patterns
+    REAL_WORLD_PATTERNS,
+    // 2c. Design principles — spacing, type, color, layout, restraint
+    DESIGN_PRINCIPLES,
+    // 2d. Control flow & reactivity — signals, list rendering ($map), conditionals ($switch)
+    CONTROL_FLOW_PATTERNS,
+    // 2e. Multi-page site building — layouts, file-based routing, navigation
+    MULTI_PAGE_PATTERNS,
+    // 3. Error recovery guidance
+    ERROR_RECOVERY,
+  ].join(SECTION_SEPARATOR) + SECTION_SEPARATOR;
+
 /**
  * Build a dynamic system prompt for the AI assistant.
  *
@@ -681,7 +750,7 @@ export function buildSystemPrompt({
 }: BuildSystemPromptOptions = {}) {
   const hasDocument = Boolean(document);
 
-  // 1. Role, state-appropriate workflow, and the tool list for the current state.
+  // The state-appropriate workflow and the tool list for the current state.
   // The list the model is TOLD about and the list the gate will honour are the same filter, so a
   // Refusal is never a surprise to it. The command-projected tools arrive already filtered by
   // Their records' own gates, for the same reason — one function answers both the prompt and the
@@ -695,8 +764,6 @@ export function buildSystemPrompt({
     .map((blurb) => `- ${blurb}`)
     .join("\n");
 
-  const role = `You are an expert Jx builder assistant embedded in Jx Studio. You help users build websites, components, pages, and layouts using the Jx JSON schema. The live jxsuite.com marketing site is built entirely with Jx — you can produce production-quality Jx code.`;
-
   let workflow: string;
   if (!hasProject && !hasDocument) {
     workflow = `No project is open yet. Your first job is to bootstrap one:
@@ -734,23 +801,10 @@ ${ASKING_THE_USER}
 
 Be concise. Don't explain what Jx is unless asked. Just build.`;
 
-  const sections = [`${role}\n\n${workflow}\n\n${closing}`];
-
-  // eslint-disable-next-line unicorn/no-immediate-mutation -- conditional section builder: later sections are pushed only when their context exists
-  sections.push(
-    // 2. Jx schema reference — kept in ALL modes (pre-project the model plans starter content)
-    JX_SCHEMA_REFERENCE,
-    // 3. State shape decision tree
-    STATE_SHAPE_DECISION_TREE,
-    // 4. Real-world patterns
-    REAL_WORLD_PATTERNS,
-    // 4a. Design principles — spacing, type, color, layout, restraint
-    DESIGN_PRINCIPLES,
-    // 4b. Control flow & reactivity — signals, list rendering ($map), conditionals ($switch)
-    CONTROL_FLOW_PATTERNS,
-    // 4c. Multi-page site building — layouts, file-based routing, navigation
-    MULTI_PAGE_PATTERNS,
-  );
+  /* 4. The mode. Everything from here on is a function of what is open right now, so it all follows
+     SYSTEM_PROMPT_STATIC_PREFIX: a provider's prompt cache matches on a prefix, and the first byte
+     that differs between two requests ends the match. */
+  const sections = [`## Current Mode\n\n${workflow}`];
 
   // 5. Current document context
   if (document) {
@@ -758,7 +812,7 @@ Be concise. Don't explain what Jx is unless asked. Just build.`;
     sections.push(`## Current Document\n\n${summary}`);
   }
 
-  // 6. Project context
+  // 5a. Project context
   if (hasProject && (projectConfig || components || projectRoot)) {
     const projectSummary = buildProjectSummary({
       components,
@@ -771,7 +825,7 @@ Be concise. Don't explain what Jx is unless asked. Just build.`;
     }
   }
 
-  // 6a. File inventory — a compact map of the project for cross-file work
+  // 5b. File inventory — a compact map of the project for cross-file work
   if (hasProject && fileInventory && fileInventory.length > 0) {
     const capped = fileInventory.slice(0, FILE_INVENTORY_CAP);
     const more =
@@ -781,34 +835,10 @@ Be concise. Don't explain what Jx is unless asked. Just build.`;
     sections.push(`## Project Files\n\n${capped.join("\n")}${more}`);
   }
 
-  // 7. Error recovery guidance
-  sections.push(`## Error Recovery
-
-If a tool call fails (returns { success: false }):
-1. Read the error message carefully — it includes a "→ Fix:" hint telling you exactly how to correct the error.
-2. Each error points to a specific path in the document and a specific rule violation.
-3. Apply the suggested fix using set_property, delete_node, or add_child as appropriate.
-4. Do NOT re-issue the exact same tool call with the same arguments — you must CHANGE something.
-5. If you see the SAME error after 2 attempts, try a completely different approach (e.g., remove and re-add the node instead of patching it).
-
-### Common validation errors and their fixes:
-
-| Error pattern | What happened | How to fix |
-|---|---|---|
-| "must NOT have additional property" in style | You used a non-camelCase CSS property (e.g. "background-color") or put an HTML attribute directly on the element. | Use camelCase: "backgroundColor". Put aria-*, data-*, role, and other non-IDL attributes inside the "attributes" object: { "attributes": { "aria-label": "..." } } |
-| "must match pattern" on tagName | A custom element tag name doesn't contain a hyphen. | Add a hyphen: "newsletter-form" not "newsletter". Standard HTML elements use their exact name ("div", "p", "input"). |
-| "must be string" | A value is an unquoted number, boolean, or bare word. | Wrap the value in quotes: "10px" not 10px. All CSS values and text must be strings. |
-| "must be number" / "must be integer" | A numeric field (like index, tabIndex) is wrapped in quotes. | Remove the quotes: use 0 not "0". |
-| "must have required property" | A required field is missing from the node. | Add the missing property. Every element must have "tagName". |
-| "must be object" | A field that expects an object (like style or attributes) received a string or other type. | Use {} not a string. |
-| "No node exists at path" | The path you provided doesn't point to an existing node. | Call read_document first to see the current structure and valid paths, then use the correct path. |
-
-### If you keep getting errors:
-- Call read_document again — the document may have changed since you last read it.
-- Remove the problematic node entirely with delete_node, then re-create it correctly with add_child.
-- If the error message points to a different path than you expected, the node might have moved due to previous edits.`);
+  // 6. Closing — last, where a long prompt's final instructions carry the most weight.
+  sections.push(closing);
 
-  return sections.join("\n\n---\n\n");
+  return SYSTEM_PROMPT_STATIC_PREFIX + sections.join(SECTION_SEPARATOR);
 }
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────

package/src/settings/preferences-accounts.ts

@@ -30,7 +30,9 @@ import { clearCfConnection, getCfAccountId, getCfToken } from "../services/cf-se
 import { clearAiProvider, getBaseUrl, hasOpenAiKey } from "../services/ai-settings";
 import { preferredModel, resetModelCache } from "../services/ai-models";
 import { getPlatform, hasPlatform } from "../platform";
-import type { CfConnection } from "../types";
+import { getAccountEntries } from "../account-status";
+import { runOfferedAction } from "../account/action-flow";
+import type { AccountEntry, CfConnection, OfferedAction } from "../types";
 
 /** One thing a row can do besides existing. */
 export interface AccountAction {
@@ -228,11 +230,47 @@ function localCloudflareRecord(): AccountRecord {
   };
 }
 
+// ─── The platform's own rows ─────────────────────────────────────────────────
+
+/**
+ * One row the platform adds (desktop.md §10.4) — a membership, a role, a plan; Studio does not know
+ * which, and draws it in the platform's words.
+ *
+ * Its id is namespaced so no platform can shadow one of Studio's own rows by naming it `github`.
+ * `revoke` does nothing: whatever the row describes is not a credential this app holds, so there is
+ * nothing here to forget, and its verbs are the actions the platform offers with it.
+ */
+function platformAction(action: OfferedAction): AccountAction {
+  const verb: AccountAction = {
+    id: action.id,
+    label: action.label,
+    run: async () => {
+      await runOfferedAction(action);
+    },
+  };
+  if (action.primary) {
+    verb.variant = "accent";
+  }
+  return verb;
+}
+
+function platformRecord(entry: AccountEntry): AccountRecord {
+  return {
+    actions: (entry.actions ?? []).map((action) => platformAction(action)),
+    connected: entry.connected ?? false,
+    detail: entry.detail,
+    id: `platform:${entry.id}`,
+    label: entry.label,
+    revoke: () => {},
+  };
+}
+
 /**
- * The three accounts, always all three.
+ * The three accounts, always all three — then any rows the platform adds.
  *
  * A disconnected account still gets a row: "you are not signed in to GitHub" is information, and a
- * list that hides what is absent cannot answer the question the section exists to answer.
+ * list that hides what is absent cannot answer the question the section exists to answer. The
+ * platform's rows are the platform's to include or leave out; Studio adds none of its own.
  */
 export function listAccounts(): AccountRecord[] {
   const githubToken = githubTokenStored();
@@ -260,6 +298,7 @@ export function listAccounts(): AccountRecord[] {
       revoke: clearAiProvider,
     },
     platformBrokersCf() ? brokeredCloudflareRecord() : localCloudflareRecord(),
+    ...getAccountEntries().map((entry) => platformRecord(entry)),
   ];
 }
 

package/src/settings/preferences-dialog.ts

@@ -19,7 +19,7 @@
  *   this, `clearGithubToken()` had zero callers: signing out of GitHub was not expressible.
  * - **Keyboard** — GENERATED from `commands/reference.ts`'s `shortcutReference()`, the same
  *   projection `docs/studio/interface/shortcuts.md` is built from. The registry is the one place a
- *   chord is declared, so the sheet cannot drift from the app or from the docs. Per CLAUDE.md's
+ *   chord is declared, so the sheet cannot drift from the app or from the docs. Per AGENTS.md's
  *   Screenshot Policy there is deliberately no screenshot of it — photographing generated content
  *   is a bug. It is searchable two ways, because there are two questions ("what is the shortcut for
  *   X" and "what did I just press"), and rebindable — as a LAYER over the registry
@@ -44,6 +44,8 @@
 
 import { CHROME_THEMES, setChromeTheme, shell } from "../shell";
 import { layerHost } from "../ui/layers";
+import { hydrateAccountStatus } from "../account-status";
+import { getPlatform, hasPlatform } from "../platform";
 import { createAiCredentialsForm } from "../ui/ai-credentials-form";
 import { createManagedConnect } from "../ui/ai-managed-connect";
 import { activeRegistry } from "../commands/active-registry";
@@ -563,6 +565,11 @@ export function openPreferences(section?: string): Promise<null> {
      grant can lapse between visits, and a row that repaints the previous answer first is stating
      something it has no reason to believe. */
   resetCfConnectionCache();
+  /* And the platform's own account rows, for the same reason: whatever they report can change
+     between visits. They repaint when the answer lands; until then they show the last one. */
+  if (hasPlatform() && getPlatform().getAccountStatus) {
+    void hydrateAccountStatus().then(repaint);
+  }
   _section = section !== undefined && isPreferencesSection(section) ? section : _section;
   if (_surface) {
     repaint();

package/src/studio.ts

@@ -126,8 +126,10 @@ import {
   openLastSessionOrHome,
   registerFileTreeDnD,
   reloadCleanTab,
+  reloadTabsIfChanged,
 } from "./files/files";
 import { resetIgnoreCache } from "./files/gitignore";
+import { resetAssetVersions } from "./files/asset-versions";
 import { startFsSync } from "./files/fs-events";
 import { invalidateParamValues } from "./page-params";
 import {
@@ -221,6 +223,8 @@ import {
 import { initCssData } from "./panels/style-utils";
 import { initQuickSearch } from "./panels/quick-search";
 import { hydrateAccountStatus } from "./account-status";
+import { showToastNotices, wireActionReports } from "./account/action-flow";
+import { isActionRequired } from "./platform-errors";
 import { hydrateProjectList } from "./project-list";
 import { addRecentProject, hydrateRecentProjects, removeRecentProject } from "./recent-projects";
 import {
@@ -507,6 +511,9 @@ toolbarPanel.mount(toolbarEl, {
 });
 
 initLayers();
+/* Before anything reaches the backend: an `action-required` refusal (desktop.md §10.4) can be the
+   answer to the very first request, and the dialog that offers its actions needs the layers above. */
+wireActionReports();
 initQuickSearch({ openRecentProject: (root: string) => openRecentProject(root) });
 
 /* The pane's four surfaces come from its CELL, not from `document.querySelector`.
@@ -959,6 +966,9 @@ function ensureFsSync() {
       paneContext.resetParamValues();
     },
     onContentChange: reloadCleanTab,
+    /* A reconnect re-reads the clean, non-collab tabs, and leaves every one whose content did not
+       change untouched: most reconnects changed nothing, and a reload is a repaint per tab. */
+    onResyncContent: reloadTabsIfChanged,
     renderLeftPanel,
   });
 }
@@ -979,7 +989,10 @@ if (!_projectParam) {
     // No project is bound yet, so this call only warms the canvasUrl; a backend that refuses it
     // Still gets the render below rather than an unhandled rejection.
     ?.catch((error: unknown) => {
-      console.error("Boot activation failed:", error);
+      // A refusal that offers an action is the action flow's to explain; it is not a fault.
+      if (!isActionRequired(error)) {
+        console.error("Boot activation failed:", error);
+      }
     })
     .then(() => {
       render();
@@ -1022,6 +1035,7 @@ if (_projectParam) {
           }
 
           resetIgnoreCache();
+          resetAssetVersions();
           setProjectState({
             dirs: new Map(),
             expanded: new Set(),
@@ -1188,6 +1202,8 @@ void hydrateProjectList().then(() => {
 // The welcome screen's install prompt. No-op on platforms without getAccountStatus.
 // oxlint-disable-next-line unicorn/prefer-top-level-await -- deliberate fire-and-forget: hydration must not block initial render
 void hydrateAccountStatus().then(() => {
+  // After the status: the platform's one-time notices ride on it (desktop.md §10.4).
+  showToastNotices();
   render();
 });
 
@@ -1355,6 +1371,7 @@ async function openRecentProject(root: string) {
 
     closeAllTabs();
     resetIgnoreCache();
+    resetAssetVersions();
 
     setProjectState({
       ...projectState,

package/src/surfaces/dialog.ts

@@ -96,6 +96,8 @@ export interface DialogSurfacePatch {
    */
   confirmLabel?: string;
   cancelLabel?: string;
+  /** The secondary button's text; the empty string takes the button away. */
+  secondaryLabel?: string;
   /** The sentence under the headline. Cleared by the empty string. */
   message?: string;
   value?: string;
@@ -298,6 +300,9 @@ export function openDialogSurface(options: DialogSurfaceOptions): DialogSurfaceH
       if (patch.cancelLabel !== undefined) {
         scope.cancelLabel = patch.cancelLabel;
       }
+      if (patch.secondaryLabel !== undefined) {
+        scope.secondaryLabel = patch.secondaryLabel;
+      }
       if (patch.message !== undefined) {
         scope.message = patch.message;
         scope.hasMessage = patch.message !== "";

package/src/surfaces/welcome.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioWelcome",
-  "$description": "The Start pane, shown when no project is loaded and no document is open. The adapter hands in the start actions, whether the GitHub App still needs installing, the recent projects with their distinguishing folders and last-opened labels, and the platform's catalogue; the document draws them in the order a first run needs them.",
+  "$description": "The Start pane, shown when no project is loaded and no document is open. The adapter hands in the start actions, whether the GitHub App still needs installing, the platform's own notices with the actions each offers, the recent projects with their distinguishing folders and last-opened labels, and the platform's catalogue; the document draws them in the order a first run needs them.",
   "tagName": "div",
   "attributes": {
     "part": "screen"
@@ -311,6 +311,91 @@
             }
           }
         },
+        {
+          "$prototype": "Array",
+          "items": {
+            "$ref": "#/state/notices"
+          },
+          "key": {
+            "$ref": "$map/item/id"
+          },
+          "map": {
+            "tagName": "section",
+            "attributes": {
+              "part": "section",
+              "data-section": "notice",
+              "data-notice": "${$map.item.id}",
+              "data-level": "${$map.item.level}"
+            },
+            "children": [
+              {
+                "tagName": "h2",
+                "attributes": {
+                  "part": "section-title"
+                },
+                "textContent": "${$map.item.title}"
+              },
+              {
+                "tagName": "p",
+                "attributes": {
+                  "part": "note"
+                },
+                "textContent": "${$map.item.message}"
+              },
+              {
+                "tagName": "div",
+                "attributes": {
+                  "part": "actions"
+                },
+                "children": [
+                  {
+                    "$prototype": "Array",
+                    "items": {
+                      "$ref": "$map/item/actions"
+                    },
+                    "key": {
+                      "$ref": "$map/item/key"
+                    },
+                    "map": {
+                      "tagName": "jx-button",
+                      "$props": {
+                        "variant": {
+                          "$ref": "$map/item/variant"
+                        }
+                      },
+                      "attributes": {
+                        "part": "notice-action",
+                        "data-action": "${$map.item.key}"
+                      },
+                      "onclick": {
+                        "$prototype": "Function",
+                        "body": [
+                          {
+                            "operator": "call",
+                            "target": {
+                              "$ref": "#/state/noticeRun"
+                            },
+                            "value": [
+                              {
+                                "$ref": "$map/item/key"
+                              }
+                            ]
+                          }
+                        ]
+                      },
+                      "children": [
+                        {
+                          "tagName": "span",
+                          "textContent": "${$map.item.label}"
+                        }
+                      ]
+                    }
+                  }
+                ]
+              }
+            ]
+          }
+        },
         {
           "tagName": "div",
           "attributes": {