@agent-native/core 0.153.9 → 0.154.0

package/corpus/templates/design/app/pages/DesignSystemSetup.tsx

@@ -43,6 +43,8 @@ import { cn } from "@/lib/utils";
 interface GitHubLink {
   id: string;
   url: string;
+  ref?: string;
+  include?: string[];
 }
 
 interface UploadedFile {
@@ -73,6 +75,12 @@ interface BuilderIndexInput {
   projectName?: string;
   description?: string;
   githubRepoUrl?: string;
+  githubSources?: Array<{
+    repoUrl: string;
+    ref?: string;
+    include?: string[];
+    exclude?: string[];
+  }>;
   connectedProjectId?: string;
   codeFiles?: Array<{
     filename: string;
@@ -93,6 +101,8 @@ export default function DesignSystemSetup() {
   const [websiteUrl, setWebsiteUrl] = useState("");
   const [websiteUrls, setWebsiteUrls] = useState<string[]>([]);
   const [githubUrl, setGithubUrl] = useState("");
+  const [githubRef, setGithubRef] = useState("");
+  const [githubPaths, setGithubPaths] = useState("");
   const [githubLinks, setGithubLinks] = useState<GitHubLink[]>([]);
   const [codeFiles, setCodeFiles] = useState<UploadedFile[]>([]);
   const [docFiles, setDocFiles] = useState<UploadedFile[]>([]);
@@ -308,10 +318,24 @@ export default function DesignSystemSetup() {
       setValidationError(t("designSystemSetup.errors.githubUrl"));
       return;
     }
-    setGithubLinks((prev) => [...prev, { id: crypto.randomUUID(), url }]);
+    const include = githubPaths
+      .split(/[\n,]/)
+      .map((path) => path.trim().replace(/^\/+|\/+$/g, ""))
+      .filter(Boolean);
+    setGithubLinks((prev) => [
+      ...prev,
+      {
+        id: crypto.randomUUID(),
+        url,
+        ...(githubRef.trim() ? { ref: githubRef.trim() } : {}),
+        ...(include.length > 0 ? { include: [...new Set(include)] } : {}),
+      },
+    ]);
     setGithubUrl("");
+    setGithubRef("");
+    setGithubPaths("");
     setValidationError(null);
-  }, [githubUrl, t]);
+  }, [githubPaths, githubRef, githubUrl, t]);
 
   const removeGithubLink = useCallback((id: string) => {
     setGithubLinks((prev) => prev.filter((l) => l.id !== id));
@@ -441,12 +465,26 @@ export default function DesignSystemSetup() {
     const normalizedWebsiteUrls = pendingWebsiteUrl
       ? [...websiteUrls, pendingWebsiteUrl]
       : websiteUrls;
+    const pendingGithubInclude = githubPaths
+      .split(/[\n,]/)
+      .map((path) => path.trim().replace(/^\/+|\/+$/g, ""))
+      .filter(Boolean);
     const normalizedGithubLinks = pendingGithubUrl
-      ? [...githubLinks, { id: "pending", url: pendingGithubUrl }]
+      ? [
+          ...githubLinks,
+          {
+            id: "pending",
+            url: pendingGithubUrl,
+            ...(githubRef.trim() ? { ref: githubRef.trim() } : {}),
+            ...(pendingGithubInclude.length > 0
+              ? { include: [...new Set(pendingGithubInclude)] }
+              : {}),
+          },
+        ]
       : githubLinks;
 
-    const isSingleGithubSource =
-      normalizedGithubLinks.length === 1 &&
+    const isGithubOnlySource =
+      normalizedGithubLinks.length > 0 &&
       normalizedWebsiteUrls.length === 0 &&
       codeFiles.length === 0 &&
       !builderIndexResult &&
@@ -455,10 +493,7 @@ export default function DesignSystemSetup() {
       assets.length === 0 &&
       !selectedProjectId;
 
-    if (isSingleGithubSource) {
-      const githubRepoUrl = normalizedGithubLinks[0]?.url;
-      if (!githubRepoUrl) return;
-
+    if (isGithubOnlySource) {
       setValidationError(null);
       try {
         await indexSystemMutation.mutateAsync({
@@ -467,7 +502,11 @@ export default function DesignSystemSetup() {
             [notes.trim(), customInstructions.trim()]
               .filter(Boolean)
               .join("\n\n") || undefined,
-          githubRepoUrl,
+          githubSources: normalizedGithubLinks.map((link) => ({
+            repoUrl: link.url,
+            ...(link.ref ? { ref: link.ref } : {}),
+            ...(link.include?.length ? { include: link.include } : {}),
+          })),
         });
         toast.success(t("designSystemSetup.githubIndexStarted"));
         navigate("/design-systems");
@@ -507,7 +546,15 @@ export default function DesignSystemSetup() {
 
     if (normalizedGithubLinks.length > 0) {
       parts.push(
-        `\n## Connect Code: GitHub Repositories\nStart Builder DSI indexing for each repository with \`index-design-system-with-builder\`:\n${normalizedGithubLinks.map((l) => `- ${l.url}`).join("\n")}\n\nBuilder is the source of truth for repo/code design-system indexing. The action also creates a local selectable proxy design system for Design flows. If Builder is not connected, stop and tell me to connect Builder (free tier available) from Settings instead of asking me to paste repository credentials into chat.`,
+        `\n## Connect Code: GitHub Repositories\nMake one call to \`index-design-system-with-builder\` with \`githubSources\` set to this JSON array:\n\n\`\`\`json\n${JSON.stringify(
+          normalizedGithubLinks.map((link) => ({
+            repoUrl: link.url,
+            ...(link.ref ? { ref: link.ref } : {}),
+            ...(link.include?.length ? { include: link.include } : {}),
+          })),
+          null,
+          2,
+        )}\n\`\`\`\n\nBuilder is the source of truth for repo/code design-system indexing. The action creates one local selectable proxy design system for Design flows. If Builder is not connected, stop and tell me to connect Builder (free tier available) from Settings instead of asking me to paste repository credentials into chat.`,
       );
     }
 
@@ -629,6 +676,8 @@ export default function DesignSystemSetup() {
     websiteUrl,
     websiteUrls,
     githubUrl,
+    githubRef,
+    githubPaths,
     githubLinks,
     codeFiles,
     builderIndexResult,
@@ -935,6 +984,22 @@ export default function DesignSystemSetup() {
                     {t("designSystemSetup.add")}
                   </Button>
                 </div>
+                <div className="grid gap-2 sm:grid-cols-2">
+                  <Input
+                    value={githubRef}
+                    onChange={(e) => setGithubRef(e.target.value)}
+                    placeholder={t("designSystemSetup.githubRef")}
+                    aria-label={t("designSystemSetup.githubRef")}
+                    className="bg-accent/50 border-border"
+                  />
+                  <Input
+                    value={githubPaths}
+                    onChange={(e) => setGithubPaths(e.target.value)}
+                    placeholder={t("designSystemSetup.githubPaths")}
+                    aria-label={t("designSystemSetup.githubPaths")}
+                    className="bg-accent/50 border-border"
+                  />
+                </div>
                 <p className="mt-2 text-xs text-muted-foreground/80">
                   {t("designSystemSetup.privateRepoPrefix")}{" "}
                   <a
@@ -954,6 +1019,13 @@ export default function DesignSystemSetup() {
                       >
                         <IconCheck className="w-3.5 h-3.5 text-green-400/60 shrink-0" />
                         <span className="truncate flex-1">{link.url}</span>
+                        {link.ref || link.include?.length ? (
+                          <span className="shrink-0 text-[10px] text-muted-foreground/70">
+                            {[link.ref, link.include?.join(", ")]
+                              .filter(Boolean)
+                              .join(" · ")}
+                          </span>
+                        ) : null}
                         <button
                           onClick={() => removeGithubLink(link.id)}
                           className="text-muted-foreground/70 hover:text-muted-foreground shrink-0 cursor-pointer"

package/corpus/templates/design/app/pages/DesignSystems.tsx

@@ -109,6 +109,8 @@ interface DesignSystemData {
   logos?: Array<{ url?: string; name?: string; variant?: string }>;
   defaults?: Record<string, unknown>;
   notes?: unknown;
+  /** The source system's own named vocabulary; absent on kits predating it. */
+  tokens?: unknown;
 }
 
 export default function DesignSystems() {
@@ -1105,10 +1107,22 @@ function getDetailTokens(
   const borders = data?.borders ?? {};
   const defaults = data?.defaults ?? {};
   const logos = data?.logos ?? [];
+  const namedTokenCount = Array.isArray(data?.tokens) ? data.tokens.length : 0;
   return [
     ...objectPreviewItems(t("designSystems.tokenPreview.spacing"), spacing),
     ...objectPreviewItems(t("designSystems.tokenPreview.borders"), borders),
     ...objectPreviewItems(t("designSystems.tokenPreview.defaults"), defaults),
+    // The seven color roles are a summary of an import, not its extent. Without
+    // this the panel renders a 200-token system identically to a 7-token one,
+    // which reads as "it only captured a few colors".
+    namedTokenCount > 0
+      ? {
+          label: t("designSystems.tokenPreview.namedTokens"),
+          value: t("designSystems.tokenPreview.savedCount", {
+            count: namedTokenCount,
+          }),
+        }
+      : null,
     logos.length > 0
       ? {
           label: t("designSystems.tokenPreview.logos"),

package/corpus/templates/design/app/pages/design-editor/generation-prompt-directives.ts

@@ -121,10 +121,12 @@ export async function loadDesignSystemGenerationContext(
 export function designIntakeQuestionDirectives(
   designId: string,
   designSystemId?: string | null,
+  referenceImageCount = 0,
 ): string[] {
   return [
     `This is a new UI-started design for design id "${designId}". The design shell already exists - DO NOT call create-design.`,
     ...designSystemGenerationDirectives(designSystemId),
+    ...referenceImageDirectives(referenceImageCount),
     "First, call `show-design-questions` with 4-6 tailored questions and then stop. Do NOT call generate-design or present-design-variants until the user submits or skips the questions.",
     "Make the questions feel like Claude Design intake: form factor, aesthetic direction, important features/content, special interactions/polish, and whether to explore variations. Omit or rephrase anything the user's prompt already answered.",
     "Use concise option chips with `allowOther: true`; include a practical `Decide for me` option where useful. Use `multiSelect: true` for feature/interactions questions.",
@@ -159,13 +161,33 @@ export function designVariantGenerationDirectives(
   ];
 }
 
+/**
+ * An attached UI screenshot is the specification. Reproducing it is the whole
+ * job, so these directives ship in the same prompt as the image — the skill
+ * body is not in the system prompt and loses every conflict against directives
+ * that are.
+ */
+export function referenceImageDirectives(
+  referenceImageCount: number,
+): string[] {
+  if (referenceImageCount < 1) return [];
+  return [
+    `The user attached ${referenceImageCount} reference image(s) to this message. Treat any image showing a UI as a layout specification to reproduce, not as loose inspiration.`,
+    "Match its regions and their positions, navigation pattern, information hierarchy, density, component grammar (tabs vs pills, cards vs rows, sidebar vs topbar), and approximate proportions. Briefly name what you see before building so a misread can be corrected early.",
+    "Do NOT substitute your own composition, palette, or font for something the image or the linked design system already specifies — including choices a generic quality heuristic would discourage. Deviate only where the image is genuinely unreadable, and say so when you do.",
+    "Do NOT call `show-design-questions` or `present-design-variants` about anything the image already answers; the direction is chosen. Generate the one design it specifies.",
+  ];
+}
+
 export function designGenerationDirectives(
   designId: string,
   designSystemId?: string | null,
+  referenceImageCount = 0,
 ): string[] {
   return [
     `Use the \`generate-design --designId="${designId}"\` action with exactly one complete, renderable \`index.html\` file first. The design already exists - DO NOT call create-design.`,
     ...designSystemGenerationDirectives(designSystemId),
+    ...referenceImageDirectives(referenceImageCount),
     'If the user asked to explore variations, call `present-design-variants` with 2-5 concise directions. Prefer label, description, accentColor, and feature bullets; omit large content HTML when needed because the action can render compact representative screens. Wait for their chat pick, delete each unchosen variant screen at most once, call `get-design-snapshot` exactly once with `fileId` for the kept screen, then call `edit-design` exactly once on that same `fileId` in a bounded pass. Use `mode: "replace-file"` when expanding the representative placeholder into a complete but compact product UI in the chosen direction. Prioritize the primary workflow and render secondary details as visible controls, states, or affordances if the feature list is too large for one reliable edit. Do not repeat delete/snapshot cycles. Do not call `generate-design` after a variant pick. Stop after the first successful `edit-design` save. Otherwise generate one polished first direction.',
     'Responsive behavior is mandatory for every web design: use a mobile-first layout, include a viewport meta tag, stack or collapse desktop columns at narrow widths, and never rely on a fixed-width desktop shell. Default to a desktop primary artboard. For a Desktop or Both/responsive intake answer, pass `primaryViewport: "desktop"` and `canvasFrames` with width 1440 and height 1024; pass `primaryViewport: "mobile"` only when the user explicitly chooses a mobile-primary artboard.',
     "Keep the first pass bounded enough to finish quickly: one self-contained Alpine.js + Tailwind CDN HTML document, polished but concise. Add 3-6 tweaks only when they naturally fit the design.",

package/corpus/templates/design/changelog/2026-08-13-a-screen-that-would-render-behind-an-invisible-alpine-overla.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-13
+---
+
+A screen whose Alpine overlay would cover it on load — `x-cloak` without its hiding rule, or a broken Alpine script URL — is now caught when it is saved instead of shipping as a blank or covered design.

package/corpus/templates/design/changelog/2026-08-13-attach-a-ui-screenshot-and-the-design-is-reproduced-not-rein.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-13
+---
+
+Attach a UI screenshot and the design is reproduced from it instead of being reinterpreted as three alternative directions.

package/corpus/templates/design/changelog/2026-08-13-linking-a-design-system-means-you-never-get-generic-directio.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-13
+---
+
+Linking a design system means you never get generic direction cards: exploring variants without real HTML is now refused for that design rather than rendering placeholder screens that ignore your tokens.

package/corpus/templates/design/changelog/2026-08-13-the-design-audit-now-reports-when-a-screen-ignores-its-linke.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-08-13
+---
+
+The design audit now reports when a screen uses none of its linked design system's fonts, colors, or token names.

package/corpus/templates/design/changelog/2026-08-13-the-design-system-preview-now-shows-how-many-named-tokens-we.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-13
+---
+
+The design system preview now shows how many named tokens were captured, so a large imported system no longer looks like a handful of colors.

package/corpus/templates/design/changelog/2026-08-13-your-design-system-prompt-and-reference-screenshots-now-reac.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-13
+---
+
+Your design system, original prompt, and reference screenshots now reach the turn that actually generates the design, instead of being spent on the questions step.

package/corpus/templates/design/server/lib/builder-design-system-proxy.ts

@@ -2,6 +2,8 @@ import {
   createBuilderDesignSystemProxyFields,
   localBuilderDesignSystemId,
   type BuilderDesignSystemIndexResult,
+  type BuilderDesignSystemGitHubSource,
+  type BuilderDesignSystemSourceKind,
 } from "@agent-native/core/server";
 import { and, eq, isNull } from "drizzle-orm";
 import { nanoid } from "nanoid";
@@ -14,12 +16,18 @@ export async function upsertBuilderProxyDesignSystem({
   orgId,
   projectName,
   description,
+  sourceKind,
+  githubSources,
+  localDesignSystemId: requestedLocalDesignSystemId,
 }: {
   result: BuilderDesignSystemIndexResult;
   ownerEmail: string;
   orgId?: string | null;
   projectName?: string;
   description?: string;
+  sourceKind?: BuilderDesignSystemSourceKind;
+  githubSources?: BuilderDesignSystemGitHubSource[];
+  localDesignSystemId?: string;
 }) {
   const db = getDb();
   const now = new Date().toISOString();
@@ -31,6 +39,9 @@ export async function upsertBuilderProxyDesignSystem({
     projectName,
     description,
     surface: "design",
+    sourceKind,
+    githubSources,
+    syncedAt: githubSources?.length ? now : undefined,
   });
   const [existing] = await db
     .select({
@@ -39,7 +50,12 @@ export async function upsertBuilderProxyDesignSystem({
       orgId: schema.designSystems.orgId,
     })
     .from(schema.designSystems)
-    .where(eq(schema.designSystems.id, baseLocalDesignSystemId))
+    .where(
+      eq(
+        schema.designSystems.id,
+        requestedLocalDesignSystemId ?? baseLocalDesignSystemId,
+      ),
+    )
     .limit(1);
   const existingBelongsToScope =
     existing?.ownerEmail === ownerEmail &&
@@ -47,7 +63,7 @@ export async function upsertBuilderProxyDesignSystem({
   const localDesignSystemId =
     existing && !existingBelongsToScope
       ? `${baseLocalDesignSystemId}-${nanoid(8)}`
-      : baseLocalDesignSystemId;
+      : (requestedLocalDesignSystemId ?? baseLocalDesignSystemId);
   if (existingBelongsToScope) {
     await db
       .update(schema.designSystems)

package/corpus/templates/design/shared/design-review.ts

@@ -24,6 +24,7 @@ export const A11Y_FINDING_CATEGORIES = [
   "reduced-motion",
   "role",
   "token-drift",
+  "design-system-drift",
   "other",
 ] as const;
 

package/corpus/templates/design/shared/html-integrity.ts

@@ -32,6 +32,8 @@ export type DesignHtmlIntegrityIssue =
   | "close-tag-orphaned"
   | "content-truncated"
   | "runtime-missing"
+  | "runtime-alpine-missing"
+  | "runtime-cloak-missing"
   | "url-backed-screen-replaced";
 
 /**
@@ -86,6 +88,10 @@ const DOCUMENT_SHAPE_MESSAGES: Partial<
     "an editor-managed <style>/<script> block appears more than once; there must be exactly one of each",
   "url-backed-screen-replaced":
     "this screen's content is its live route URL, and the write would replace it with document markup — that permanently unbinds the screen from the running app. Edit the app's own source instead",
+  "runtime-cloak-missing":
+    "this document uses x-cloak without the CSS rule that keeps Alpine-controlled content hidden before Alpine starts",
+  "runtime-alpine-missing":
+    "this document uses x-cloak but does not load Alpine.js, so the hidden state can never be removed",
 };
 
 export function describeDesignHtmlIntegrityIssue(
@@ -141,6 +147,19 @@ export function describeDesignHtmlIntegrityIssue(
         `<script src="…@tailwindcss/browser@4"> or a <style type="text/tailwindcss">). ` +
         `Utility classes will not apply and the design renders unstyled.`
       );
+    case "runtime-alpine-missing":
+      return (
+        `the document uses x-cloak on <${detail.tag ?? "element"}> at ${at}, ` +
+        `but no script source contains Alpine.js. The element will remain ` +
+        `hidden forever; load Alpine.js before relying on x-cloak.`
+      );
+    case "runtime-cloak-missing":
+      return (
+        `the document uses x-cloak on <${detail.tag ?? "element"}> at ${at}, ` +
+        `but no style block defines [x-cloak] { display: none !important; }. ` +
+        `Alpine-controlled overlays can flash or cover the entire screen before ` +
+        `Alpine starts. Add that exact hiding rule to the document.`
+      );
     default:
       return `the document structure is invalid (${detail.issue}) at ${at}.`;
   }
@@ -1077,6 +1096,85 @@ function collectManagedMarkerIssue(
   return null;
 }
 
+/**
+ * The selector may sit anywhere in a comma-separated list, and any of the three
+ * hidings below is a correct pre-Alpine hide. Matching only
+ * `[x-cloak] { display: none }` rejects documents that render perfectly.
+ */
+const X_CLOAK_RULE =
+  /\[x-cloak\][^{}]*\{[^}]*(?:display\s*:\s*none|visibility\s*:\s*hidden|@apply[^;}]*\bhidden\b)/i;
+const ALPINE_RUNTIME = /\balpinejs\b/i;
+const INLINE_PRE_HIDE = /(?:display\s*:\s*none|visibility\s*:\s*hidden)/i;
+
+/**
+ * `x-cloak` is an Alpine convention, not a runtime feature: it only works
+ * when the authored document also supplies the CSS rule that hides the node
+ * before Alpine initializes. A missing rule is especially dangerous for
+ * fixed overlays, which can make a correct screen look completely replaced.
+ */
+function collectInteractiveRuntimeIssues(
+  parsed: ParsedDocument,
+  locate: Locator,
+): DesignHtmlIntegrityIssueDetail[] {
+  const cloaked = parsed.elements.find((element) =>
+    element.attrs.some(
+      (attribute) => attribute.name.toLowerCase() === "x-cloak",
+    ),
+  );
+  if (!cloaked) return [];
+
+  const hasAlpineRuntime = parsed.elements.some(
+    (element) =>
+      element.tagName === "script" &&
+      ALPINE_RUNTIME.test(attributeOf(element, "src") ?? ""),
+  );
+
+  // A linked stylesheet is content this parser cannot read, so its rules are
+  // unknown — not missing. Reporting "no rule defined" here would be the
+  // coercion this whole module exists to prevent.
+  const hasUnreadableStylesheet = parsed.elements.some(
+    (element) =>
+      element.tagName === "link" &&
+      /\bstylesheet\b/i.test(attributeOf(element, "rel") ?? "") &&
+      (attributeOf(element, "href") ?? "").trim().length > 0,
+  );
+
+  const hasCloakRule =
+    hasUnreadableStylesheet ||
+    INLINE_PRE_HIDE.test(attributeOf(cloaked, "style") ?? "") ||
+    parsed.elements.some((element) => {
+      if (element.tagName !== "style") return false;
+      const css = childrenOf(element)
+        .filter((node) => node.nodeName === "#text")
+        .map((node) => (node as DefaultTreeAdapterTypes.TextNode).value)
+        .join("\n");
+      return X_CLOAK_RULE.test(css);
+    });
+
+  const attribute = cloaked.attrs.find(
+    (entry) => entry.name.toLowerCase() === "x-cloak",
+  );
+  const offset =
+    locationOf(cloaked)?.attrs?.[attribute?.name ?? ""]?.startOffset ??
+    locationOf(cloaked)?.startOffset ??
+    0;
+  const detail = {
+    line: locate(offset).line,
+    column: locate(offset).column,
+    excerpt: locate(offset).excerpt,
+    tag: cloaked.tagName,
+    attribute: "x-cloak",
+  };
+  return [
+    ...(hasAlpineRuntime
+      ? []
+      : [{ issue: "runtime-alpine-missing" as const, ...detail }]),
+    ...(hasCloakRule
+      ? []
+      : [{ issue: "runtime-cloak-missing" as const, ...detail }]),
+  ];
+}
+
 /**
  * Reported, never enforced: legitimate fragments and token-only screens carry no
  * runtime of their own, so blocking here would reject valid work.
@@ -1142,10 +1240,45 @@ export function inspectDesignHtmlDocumentIntegrity(
   const marker = collectManagedMarkerIssue(parsed);
   if (marker) return { valid: false, issue: marker };
 
+  const interactiveRuntime = collectInteractiveRuntimeIssues(parsed, locate);
+  if (interactiveRuntime.length > 0) {
+    return {
+      valid: false,
+      issue: interactiveRuntime[0]!.issue,
+      detail: interactiveRuntime,
+    };
+  }
+
   const advisory = collectAdvisoryIssues(parsed, locate);
   return advisory.length > 0 ? { valid: true, advisory } : { valid: true };
 }
 
+const RUNTIME_ISSUES: ReadonlySet<DesignHtmlIntegrityIssue> = new Set([
+  "runtime-alpine-missing",
+  "runtime-cloak-missing",
+]);
+
+/**
+ * The runtime issues are the one class an edit may carry forward. A screen
+ * saved before these checks existed still renders, and the person dragging on
+ * the canvas did not author its markup and cannot add a CSS rule — refusing
+ * their unrelated edit strands the screen. Block what the edit introduces;
+ * the create path still refuses to author the defect in the first place.
+ */
+function introducedRuntimeIssues(
+  next: DesignHtmlIntegrityIssueDetail[],
+  previousContent: string,
+): DesignHtmlIntegrityIssueDetail[] {
+  if (next.length === 0 || !previousContent.trim()) return next;
+  const inherited = new Set(
+    collectInteractiveRuntimeIssues(
+      parseDocument(previousContent),
+      createLocator(previousContent),
+    ).map((entry) => entry.issue),
+  );
+  return next.filter((entry) => !inherited.has(entry.issue));
+}
+
 /**
  * Fail closed only for document edits. Standalone Alpine fragments remain
  * supported. Existing malformed documents can still be repaired: a candidate
@@ -1186,6 +1319,19 @@ export function assertDesignHtmlEditIntegrity(args: {
         detail: structural,
       });
     }
+    const interactiveRuntime = introducedRuntimeIssues(
+      collectInteractiveRuntimeIssues(
+        parseDocument(args.nextContent),
+        createLocator(args.nextContent),
+      ),
+      args.previousContent,
+    );
+    if (interactiveRuntime.length > 0) {
+      throw new DesignHtmlIntegrityError(interactiveRuntime[0]!.issue, {
+        filename: args.filename,
+        detail: interactiveRuntime,
+      });
+    }
     return;
   }
   if (previousIsDocument && !nextIsDocument) {
@@ -1195,6 +1341,17 @@ export function assertDesignHtmlEditIntegrity(args: {
   }
   const result = inspectDesignHtmlDocumentIntegrity(args.nextContent);
   if (!result.valid) {
+    if (result.issue && RUNTIME_ISSUES.has(result.issue)) {
+      const introduced = introducedRuntimeIssues(
+        result.detail ?? [],
+        args.previousContent,
+      );
+      if (introduced.length === 0) return;
+      throw new DesignHtmlIntegrityError(introduced[0]!.issue, {
+        filename: args.filename,
+        detail: introduced,
+      });
+    }
     throw new DesignHtmlIntegrityError(result.issue ?? "document-root", {
       filename: args.filename,
       detail: result.detail,
@@ -1227,6 +1384,20 @@ export function assertDesignHtmlWellFormed(args: {
       detail: structural,
     });
   }
+  // Fragments are checked too, unlike the document-shape rules above: a screen
+  // is rendered as its own `srcdoc`, so nothing injects Alpine or a `[x-cloak]`
+  // rule around it. A sketch that omits them is broken exactly as a full
+  // document would be.
+  const interactiveRuntime = collectInteractiveRuntimeIssues(
+    parseDocument(args.content),
+    createLocator(args.content),
+  );
+  if (interactiveRuntime.length > 0) {
+    throw new DesignHtmlIntegrityError(interactiveRuntime[0]!.issue, {
+      filename: args.filename,
+      detail: interactiveRuntime,
+    });
+  }
 }
 
 export function assertDesignHtmlCreateIntegrity(args: {

package/corpus/templates/mail/app/lib/utils.ts

@@ -194,5 +194,5 @@ export function formatShortcut(key: string): string {
       if (lower === "space") return "Space";
       return token.length === 1 ? token.toUpperCase() : token;
     })
-    .join("+");
+    .join(" ");
 }

package/corpus/templates/plan/app/pages/PlansPage.tsx

@@ -23,6 +23,7 @@ import {
   ErrorReportActions,
   type ErrorReportDebugItem,
 } from "@agent-native/core/client/ui";
+import { docsUrl } from "@agent-native/core/shared";
 import {
   useSetHeaderActions,
   useSetPageTitle,
@@ -388,8 +389,10 @@ const ENABLE_PLAN_STATUS_FEATURE = false;
 const GITHUB_LIGHT_CANVAS_BACKGROUND = "#ffffff";
 const GITHUB_DARK_CANVAS_BACKGROUND = "#0d1117";
 const LOCAL_PLAN_OWNER_EMAIL = "local@agent-native.local";
-const PLAN_DOCS_URL = "https://www.agent-native.com/docs/template-plan";
-const LOCAL_FILES_DOCS_URL = `${PLAN_DOCS_URL}#local-files`;
+const PLAN_DOCS_URL = docsUrl("template-plan");
+const LOCAL_FILES_DOCS_URL = docsUrl("template-plan-local-and-desktop", {
+  hash: "local-files",
+});
 const AUTO_DEV_COMMENT_EMAILS = new Set(["dev@local.test", "dev@local"]);
 const CURRENT_USER_FALLBACK_NAME = "You";
 const CURRENT_USER_FALLBACK_INITIALS = "You";

package/corpus/templates/slides/.agents/skills/design-systems/SKILL.md

@@ -72,12 +72,16 @@ Builder indexing flow.
 
 ### Source: connected code, GitHub, or `design.md`
 
-For any other reusable source — connected code, a GitHub repo, local
-code/design files, or an optional `design.md` — use Builder-backed DSI
-indexing through `index-design-system-with-builder`. Pass readable `design.md`
-content as `designMd`, and use the returned local design system id in the rest
-of the Slides flow. Call `get-design-system` before generation so Builder docs
-and tokens are hydrated when available.
+For any other reusable source - connected code, a GitHub repo, local
+code/design files, or an optional `design.md` - use Builder-backed DSI
+indexing through `index-design-system-with-builder`. Pass GitHub sources as one
+`githubSources` array; each source may pin a branch/tag/commit and include
+repository-relative files or folders. Pass readable `design.md` content as
+`designMd`, and use the returned local design system id in the rest of the
+Slides flow. Call `get-design-system` before generation so Builder docs and
+tokens are hydrated when available. For a saved GitHub-backed system, call
+`sync-design-system-with-builder --id <localDesignSystemId>` to replay its
+persisted source scope after upstream changes.
 
 Never create a duplicate local design system from raw Figma or code sources.
 Builder owns the indexed brand kit; a second local copy drifts from it and