@agent-native/core 0.138.0 → 0.140.0

package/corpus/templates/clips/actions/invite-member.ts

@@ -24,6 +24,7 @@ import { and, eq, sql } from "drizzle-orm";
 import { z } from "zod";
 
 import { getDb } from "../server/db/index.js";
+import { CLIPS_ORGANIZATION_INVITE_EMAIL_ID } from "../server/lib/emails.js";
 import {
   getCurrentOwnerEmail,
   nanoid,
@@ -67,6 +68,36 @@ async function fetchOrgName(orgId: string): Promise<string> {
   return row?.name ?? "Organization";
 }
 
+export function renderClipsInviteEmail({
+  appName,
+  orgName,
+  inviter,
+  role,
+  inviteUrl,
+}: {
+  appName: string;
+  orgName: string;
+  inviter: string;
+  role: "admin" | "member";
+  inviteUrl: string;
+}) {
+  return {
+    subject: `You're invited to ${orgName} on ${appName}`,
+    ...renderEmail({
+      brandName: appName,
+      preheader: `${inviter} invited you to ${orgName} on ${appName}.`,
+      heading: `You're invited to join ${orgName}`,
+      paragraphs: [
+        `${emailStrong(inviter)} invited you to the ${emailStrong(orgName)} organization on ${emailStrong(appName)} as ${emailStrong(role)}.`,
+        `Click the button below to accept the invite and start collaborating.`,
+      ],
+      cta: { label: "Accept invite", url: inviteUrl },
+      // guard:allow-raw-color — email HTML cannot reference CSS theme tokens; mail clients don't support custom properties.
+      brandColor: "#18181B",
+    }),
+  };
+}
+
 export default defineAction({
   description:
     "Invite someone to the active organization by email. Creates a pending invitation. Role 'admin' maps to admin; all other Clips roles collapse to 'member'. Sends an email when a provider is configured.",
@@ -123,24 +154,17 @@ export default defineAction({
     const orgName = await fetchOrgName(organizationId);
     const inviteUrl = `${baseUrl()}/invite/${token}`;
 
-    const appName = getAppName();
-    const { html, text } = renderEmail({
-      brandName: appName,
-      preheader: `${inviter} invited you to ${orgName} on ${appName}.`,
-      heading: `You're invited to join ${orgName}`,
-      paragraphs: [
-        `${emailStrong(inviter)} invited you to the ${emailStrong(orgName)} organization on ${emailStrong(appName)} as ${emailStrong(role)}.`,
-        `Click the button below to accept the invite and start collaborating.`,
-      ],
-      cta: { label: "Accept invite", url: inviteUrl },
-      brandColor: "#18181B",
-    });
     try {
       await sendEmail({
+        ...renderClipsInviteEmail({
+          appName: getAppName(),
+          orgName,
+          inviter,
+          role,
+          inviteUrl,
+        }),
         to: args.email,
-        subject: `You're invited to ${orgName} on ${appName}`,
-        html,
-        text,
+        templateId: CLIPS_ORGANIZATION_INVITE_EMAIL_ID,
       });
     } catch (err) {
       console.warn("[invite-member] email send failed:", err);

package/corpus/templates/clips/server/lib/emails.ts

@@ -0,0 +1,256 @@
+/**
+ * Catalog entries for the transactional emails Clips sends.
+ *
+ * Registered from `server/plugins/transactional-emails.ts` so Dispatch can list
+ * and preview them without the app having sent anything yet.
+ *
+ * Every entry except the organization invite renders through
+ * `renderClipsTransactionalEmail`, so a preview shows the real template rather
+ * than a copy of it.
+ */
+
+import { defineTransactionalEmail } from "@agent-native/core/email-catalog";
+
+import { renderClipsInviteEmail } from "../../actions/invite-member.js";
+import {
+  CLIPS_ACTIVITY_COMMENT_EMAIL_ID,
+  CLIPS_ACTIVITY_REACTION_EMAIL_ID,
+  CLIPS_FIRST_AGENT_VIEW_EMAIL_ID,
+  CLIPS_FIRST_IMPORT_EMAIL_ID,
+  CLIPS_FIRST_VIEW_EMAIL_ID,
+  CLIPS_MONTHLY_RECAP_EMAIL_ID,
+  CLIPS_TWO_CLIPS_EMAIL_ID,
+  CLIPS_UNVIEWED_REMINDER_EMAIL_ID,
+  renderClipsTransactionalEmail,
+  type ClipsTransactionalEmailInput,
+  type ClipsTransactionalEmailRenderOptions,
+} from "./transactional-email-templates.js";
+
+/** Obviously-fake sample data — these render in a preview pane, never send. */
+const PREVIEW_OPTIONS: ClipsTransactionalEmailRenderOptions = {
+  appUrl: "https://example.com",
+};
+const SAMPLE_RECORDING_ID = "rec_sample";
+const SAMPLE_TITLE = "Onboarding walkthrough";
+const SAMPLE_TO = "sam.rivera@example.com";
+
+function preview(input: ClipsTransactionalEmailInput) {
+  return renderClipsTransactionalEmail(input, PREVIEW_OPTIONS);
+}
+
+export const CLIPS_ORGANIZATION_INVITE_EMAIL_ID = "clips.organization-invite";
+
+/**
+ * How the shared Clips sender resolves From and Reply-To for every kind it
+ * renders, so each entry can say so without restating the mechanism.
+ */
+const CLIPS_SENDER =
+  'From is the configured EMAIL_FROM with the display name "Agent-Native Clips"; on first-party agent-native.com deployments it becomes clips@agent-native.com. Reply-to is hello@agent-native.com.';
+
+let registered = false;
+
+export function registerClipsEmails(): void {
+  if (registered) return;
+  registered = true;
+
+  defineTransactionalEmail({
+    id: CLIPS_FIRST_VIEW_EMAIL_ID,
+    name: "First view on a Clip",
+    trigger:
+      "The background transactional-email sweep finds the first counted view of a Clip by someone other than its owner, recorded after transactional email was switched on. One per Clip.",
+    recipientLabel: "Clip owner",
+    recipient:
+      "The Clip's owner. Suppressed recipient addresses are skipped, and the send is dropped if the owner is no longer the recording's owner at send time.",
+    senderLabel: "Agent-Native Clips",
+    sender: CLIPS_SENDER,
+    preview: () =>
+      preview({
+        kind: "first-view",
+        to: SAMPLE_TO,
+        recordingId: SAMPLE_RECORDING_ID,
+        title: SAMPLE_TITLE,
+        viewerEmail: "alex.chen@example.com",
+      }),
+  });
+
+  defineTransactionalEmail({
+    id: CLIPS_UNVIEWED_REMINDER_EMAIL_ID,
+    name: "Unviewed Clip reminder",
+    trigger:
+      "A direct share is 48 hours old and the recipient still has no counted view of that Clip. Re-checked at send time, so a view in the meantime cancels it.",
+    recipientLabel: "Shared-with address",
+    recipient:
+      "The address the Clip was directly shared with. Requires the share to still exist.",
+    senderLabel: "Sharer via Clips",
+    sender:
+      'Same as the other Clips emails, except the display name becomes "<sharer> (via Agent-Native Clips)" and reply-to is the sharer\'s own address when it is a valid address, falling back to hello@agent-native.com.',
+    preview: () =>
+      preview({
+        kind: "unviewed-reminder",
+        to: SAMPLE_TO,
+        recordingId: SAMPLE_RECORDING_ID,
+        title: SAMPLE_TITLE,
+        senderEmail: "dana.hill@example.com",
+        senderName: "Dana Hill",
+      }),
+  });
+
+  defineTransactionalEmail({
+    id: CLIPS_FIRST_AGENT_VIEW_EMAIL_ID,
+    name: "First agent read of a Clip",
+    trigger:
+      "An AI agent reads one of an owner's Clips for the first time since transactional email was switched on. One per owner, not per Clip.",
+    recipientLabel: "Clip owner",
+    recipient:
+      "The owner of the Clip the agent read. Re-checked at send time against the owner's actual first agent view.",
+    senderLabel: "Agent-Native Clips",
+    sender: CLIPS_SENDER,
+    preview: () =>
+      preview({
+        kind: "first-agent-view",
+        to: SAMPLE_TO,
+        recordingId: SAMPLE_RECORDING_ID,
+        title: SAMPLE_TITLE,
+        agentName: "Claude Code",
+      }),
+  });
+
+  defineTransactionalEmail({
+    id: CLIPS_FIRST_IMPORT_EMAIL_ID,
+    name: "First imported video is ready",
+    trigger:
+      "An owner's first imported (rather than recorded) video finishes processing and becomes ready. One per owner.",
+    recipientLabel: "Clip owner",
+    recipient:
+      "The owner of the imported recording, re-checked at send time so a later import does not resend.",
+    senderLabel: "Agent-Native Clips",
+    sender: CLIPS_SENDER,
+    preview: () =>
+      preview({
+        kind: "first-import",
+        to: SAMPLE_TO,
+        recordingId: SAMPLE_RECORDING_ID,
+        title: "Quarterly demo recording",
+      }),
+  });
+
+  defineTransactionalEmail({
+    id: CLIPS_MONTHLY_RECAP_EMAIL_ID,
+    name: "Monthly Clips recap",
+    trigger:
+      "Once per owner per calendar month, from 14:00 UTC on the 1st, for owners whose Clips had any human views or agent reads in the closed month. Metrics and the top Clip are recomputed at send time.",
+    recipientLabel: "Clip owner",
+    recipient:
+      "The Clip owner whose audience the recap reports. Suppressed addresses are skipped.",
+    senderLabel: "Agent-Native Clips",
+    sender: CLIPS_SENDER,
+    preview: () =>
+      preview({
+        kind: "monthly-recap",
+        to: SAMPLE_TO,
+        month: "2025-02",
+        humanViews: 42,
+        agentSessions: 7,
+        topClip: {
+          recordingId: SAMPLE_RECORDING_ID,
+          title: SAMPLE_TITLE,
+          thumbnailUrl: "https://example.com/thumbnails/sample.png",
+          durationMs: 214_000,
+          recordedAt: "2025-02-11T16:00:00.000Z",
+          humanViews: 18,
+          agentSessions: 4,
+        },
+        copy: {
+          heroLine: "Your clips were watched 42 times. 7 agents read them.",
+          completionNote: "68% average completion · most stopped at 2:31",
+          agentBreakdown: "4 from Claude Code · 3 unidentified",
+        },
+      }),
+  });
+
+  defineTransactionalEmail({
+    id: CLIPS_TWO_CLIPS_EMAIL_ID,
+    name: "Two Clips received",
+    trigger:
+      "A one-time nudge once someone who owns no Clips of their own has had two distinct Clips directly shared with them. The summary line is AI-generated before the job is released to send.",
+    recipientLabel: "Shared-with address",
+    recipient:
+      "The shared-with address. Dropped at send time if they now own a Clip or no longer hold both shares.",
+    senderLabel: "Agent-Native Clips",
+    sender: CLIPS_SENDER,
+    preview: () =>
+      preview({
+        kind: "two-clips",
+        to: SAMPLE_TO,
+        generatedSummary:
+          "Two teammates walked you through the new onboarding flow.",
+      }),
+  });
+
+  defineTransactionalEmail({
+    id: CLIPS_ACTIVITY_COMMENT_EMAIL_ID,
+    name: "Clip comment",
+    trigger:
+      "Someone comments or replies on a Clip. Subject and copy differ slightly for a reply; both send under this id.",
+    recipientLabel: "Owner and thread authors",
+    recipient:
+      "The recording owner, plus every prior author in the thread when the comment is a reply. The list is re-checked against the recording's live ACL and filtered by each user's `emailNotifications` preference; the comment's own author never receives it.",
+    senderLabel: "Agent-Native Clips",
+    sender: CLIPS_SENDER,
+    preview: () =>
+      preview({
+        kind: "activity-comment",
+        to: SAMPLE_TO,
+        recordingId: SAMPLE_RECORDING_ID,
+        title: SAMPLE_TITLE,
+        authorEmail: "alex.chen@example.com",
+        authorName: "Alex Chen",
+        content: "The step at 1:20 is the part new hires always miss.",
+        videoTimestampMs: 80_000,
+        isReply: false,
+      }),
+  });
+
+  defineTransactionalEmail({
+    id: CLIPS_ACTIVITY_REACTION_EMAIL_ID,
+    name: "Clip reaction",
+    trigger: "A viewer reacts with an emoji on a Clip.",
+    recipientLabel: "Clip owner",
+    recipient:
+      "The recording owner plus any extra recipients the caller passes, re-checked against the recording's live ACL and filtered by each user's `emailNotifications` preference. The reacting viewer never receives it.",
+    senderLabel: "Agent-Native Clips",
+    sender: CLIPS_SENDER,
+    preview: () =>
+      preview({
+        kind: "activity-reaction",
+        to: SAMPLE_TO,
+        recordingId: SAMPLE_RECORDING_ID,
+        title: SAMPLE_TITLE,
+        emoji: "🎉",
+        authorEmail: "alex.chen@example.com",
+        authorName: "Alex Chen",
+        videoTimestampMs: 45_000,
+      }),
+  });
+
+  defineTransactionalEmail({
+    id: CLIPS_ORGANIZATION_INVITE_EMAIL_ID,
+    name: "Organization invitation",
+    trigger:
+      "An organization admin runs `invite-member`. Any earlier pending invite for the same address is cancelled first, so a re-invite sends a fresh email with a new token.",
+    recipientLabel: "Invited address",
+    recipient:
+      "The address passed to the action, exactly as typed. One email per invite.",
+    senderLabel: "Default sender",
+    sender:
+      "The configured default sender. This call site sets no `from`, `fromName`, `replyTo`, or `appSender`, so unlike the other Clips emails it does not send as Agent-Native Clips.",
+    preview: () =>
+      renderClipsInviteEmail({
+        appName: "Clips",
+        orgName: "Northwind Design",
+        inviter: "dana.hill@example.com",
+        role: "member",
+        inviteUrl: "https://example.com/invite/sample-token",
+      }),
+  });
+}

package/corpus/templates/clips/server/lib/transactional-email-templates.ts

@@ -86,6 +86,29 @@ export type ClipsTransactionalEmailInput =
       videoTimestampMs?: number | null;
     });
 
+export const CLIPS_FIRST_VIEW_EMAIL_ID = "clips.first-view";
+export const CLIPS_UNVIEWED_REMINDER_EMAIL_ID = "clips.unviewed-reminder";
+export const CLIPS_FIRST_AGENT_VIEW_EMAIL_ID = "clips.first-agent-view";
+export const CLIPS_FIRST_IMPORT_EMAIL_ID = "clips.first-import";
+export const CLIPS_MONTHLY_RECAP_EMAIL_ID = "clips.monthly-recap";
+export const CLIPS_TWO_CLIPS_EMAIL_ID = "clips.two-clips";
+export const CLIPS_ACTIVITY_COMMENT_EMAIL_ID = "clips.activity-comment";
+export const CLIPS_ACTIVITY_REACTION_EMAIL_ID = "clips.activity-reaction";
+
+export const CLIPS_EMAIL_ID_BY_KIND: Record<
+  ClipsTransactionalEmailInput["kind"],
+  string
+> = {
+  "first-view": CLIPS_FIRST_VIEW_EMAIL_ID,
+  "unviewed-reminder": CLIPS_UNVIEWED_REMINDER_EMAIL_ID,
+  "first-agent-view": CLIPS_FIRST_AGENT_VIEW_EMAIL_ID,
+  "first-import": CLIPS_FIRST_IMPORT_EMAIL_ID,
+  "monthly-recap": CLIPS_MONTHLY_RECAP_EMAIL_ID,
+  "two-clips": CLIPS_TWO_CLIPS_EMAIL_ID,
+  "activity-comment": CLIPS_ACTIVITY_COMMENT_EMAIL_ID,
+  "activity-reaction": CLIPS_ACTIVITY_REACTION_EMAIL_ID,
+};
+
 export interface RecapTopClipInput {
   recordingId: string;
   title?: string | null;
@@ -613,6 +636,7 @@ export async function sendClipsTransactionalEmail(
         ? (validReplyTo(input.senderEmail) ?? FRIENDLY_REPLY_TO)
         : FRIENDLY_REPLY_TO,
     timeoutMs: EMAIL_SEND_TIMEOUT_MS,
+    templateId: CLIPS_EMAIL_ID_BY_KIND[input.kind],
   });
 }
 

package/corpus/templates/clips/server/plugins/transactional-email-catalog.ts

@@ -0,0 +1,5 @@
+import { registerClipsEmails } from "../lib/emails.js";
+
+export default function registerTransactionalEmailCatalog(): void {
+  registerClipsEmails();
+}

package/corpus/templates/content/server/lib/comment-notifications.ts

@@ -21,6 +21,10 @@ import { and, eq } from "drizzle-orm";
 
 import { CONTENT_USER_PREFS_KEY } from "../../shared/content-user-prefs.js";
 import { getDb, schema } from "../db/index.js";
+import {
+  CONTENT_DOCUMENT_COMMENT_EMAIL_ID,
+  CONTENT_DOCUMENT_MENTION_EMAIL_ID,
+} from "./emails.js";
 
 export type DocumentCommentNotificationResult = ActivityNotificationResult;
 
@@ -70,6 +74,48 @@ export interface DocumentCommentNotificationInput {
   isReply: boolean;
 }
 
+export function renderDocumentCommentEmail({
+  actor,
+  title,
+  url,
+  content,
+  isReply,
+  wasMentioned,
+}: {
+  actor: string;
+  title: string;
+  url: string;
+  content: string;
+  isReply: boolean;
+  wasMentioned: boolean;
+}) {
+  const lead = wasMentioned
+    ? `${emailStrong(actor)} mentioned you in a comment on ${emailStrong(title)}.`
+    : isReply
+      ? `${emailStrong(actor)} replied in a comment thread on ${emailStrong(title)}.`
+      : `${emailStrong(actor)} commented on ${emailStrong(title)}.`;
+
+  return {
+    subject: wasMentioned
+      ? `${actor} mentioned you on "${title}"`
+      : isReply
+        ? `${actor} replied to a comment on "${title}"`
+        : `${actor} commented on "${title}"`,
+    ...renderEmail({
+      preheader: `${actor} commented on ${title}.`,
+      heading: wasMentioned
+        ? "You were mentioned"
+        : isReply
+          ? "New reply on your document"
+          : "New comment",
+      paragraphs: [lead, `"${excerpt(content)}"`],
+      cta: { label: "Open document", url },
+      footer:
+        "You received this because you own, were mentioned in, or participated in this thread. Turn these off in Documents settings.",
+    }),
+  };
+}
+
 export async function notifyDocumentComment(
   input: DocumentCommentNotificationInput,
 ): Promise<DocumentCommentNotificationResult> {
@@ -112,34 +158,19 @@ async function deliverDocumentCommentEmails(
     logLabel: LOG_LABEL,
     send: async (to) => {
       const wasMentioned = mentioned.has(to);
-      const lead = wasMentioned
-        ? `${emailStrong(actor)} mentioned you in a comment on ${emailStrong(title)}.`
-        : input.isReply
-          ? `${emailStrong(actor)} replied in a comment thread on ${emailStrong(title)}.`
-          : `${emailStrong(actor)} commented on ${emailStrong(title)}.`;
-
-      const { html, text } = renderEmail({
-        preheader: `${actor} commented on ${title}.`,
-        heading: wasMentioned
-          ? "You were mentioned"
-          : input.isReply
-            ? "New reply on your document"
-            : "New comment",
-        paragraphs: [lead, `"${excerpt(input.content)}"`],
-        cta: { label: "Open document", url },
-        footer:
-          "You received this because you own, were mentioned in, or participated in this thread. Turn these off in Documents settings.",
-      });
-
       await sendEmail({
+        ...renderDocumentCommentEmail({
+          actor,
+          title,
+          url,
+          content: input.content,
+          isReply: input.isReply,
+          wasMentioned,
+        }),
         to,
-        subject: wasMentioned
-          ? `${actor} mentioned you on "${title}"`
-          : input.isReply
-            ? `${actor} replied to a comment on "${title}"`
-            : `${actor} commented on "${title}"`,
-        html,
-        text,
+        templateId: wasMentioned
+          ? CONTENT_DOCUMENT_MENTION_EMAIL_ID
+          : CONTENT_DOCUMENT_COMMENT_EMAIL_ID,
       });
     },
   });

package/corpus/templates/content/server/lib/emails.ts

@@ -0,0 +1,70 @@
+/**
+ * Catalog entries for the transactional emails Documents sends.
+ *
+ * Registered from `server/plugins/transactional-emails.ts` so Dispatch can list
+ * and preview them without the app having sent anything yet.
+ */
+
+import { defineTransactionalEmail } from "@agent-native/core/email-catalog";
+
+import { renderDocumentCommentEmail } from "./comment-notifications.js";
+
+/** Obviously-fake sample data — these render in a preview pane, never send. */
+const SAMPLE_TITLE = "Q3 launch brief";
+const SAMPLE_URL = "https://example.com/page/doc_sample";
+const SAMPLE_COMMENT =
+  "Can we tighten the second paragraph? It repeats the intro.";
+
+export const CONTENT_DOCUMENT_COMMENT_EMAIL_ID = "content.document-comment";
+export const CONTENT_DOCUMENT_MENTION_EMAIL_ID = "content.document-mention";
+
+let registered = false;
+
+export function registerContentEmails(): void {
+  if (registered) return;
+  registered = true;
+
+  defineTransactionalEmail({
+    id: CONTENT_DOCUMENT_COMMENT_EMAIL_ID,
+    name: "Document comment",
+    trigger:
+      "Someone posts a comment or a thread reply on a document. Sent to recipients who were not mentioned in it; the copy and subject differ slightly for a reply.",
+    recipientLabel: "Owner and thread authors",
+    recipient:
+      "The document owner, plus every prior author in the thread when the new comment is a reply. The list is re-checked against the document's live ACL and filtered by each user's `emailNotifications` preference; the comment's own author never receives it.",
+    senderLabel: "Default sender",
+    sender:
+      "The configured default sender. This call site sets no `from`, `fromName`, `replyTo`, or `appSender`.",
+    preview: () =>
+      renderDocumentCommentEmail({
+        actor: "Sam Rivera",
+        title: SAMPLE_TITLE,
+        url: SAMPLE_URL,
+        content: SAMPLE_COMMENT,
+        isReply: false,
+        wasMentioned: false,
+      }),
+  });
+
+  defineTransactionalEmail({
+    id: CONTENT_DOCUMENT_MENTION_EMAIL_ID,
+    name: "Document mention",
+    trigger:
+      "A comment or reply mentions someone by email. Sent instead of the plain comment notification to each mentioned recipient.",
+    recipientLabel: "Mentioned users",
+    recipient:
+      "The mentioned addresses supplied by the caller, re-checked against the document's live ACL and filtered by each user's `emailNotifications` preference.",
+    senderLabel: "Default sender",
+    sender:
+      "The configured default sender. This call site sets no `from`, `fromName`, `replyTo`, or `appSender`.",
+    preview: () =>
+      renderDocumentCommentEmail({
+        actor: "Sam Rivera",
+        title: SAMPLE_TITLE,
+        url: SAMPLE_URL,
+        content: SAMPLE_COMMENT,
+        isReply: false,
+        wasMentioned: true,
+      }),
+  });
+}

package/corpus/templates/content/server/plugins/transactional-emails.ts

@@ -0,0 +1,5 @@
+import { registerContentEmails } from "../lib/emails.js";
+
+export default function registerTransactionalEmails(): void {
+  registerContentEmails();
+}

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

@@ -73,6 +73,14 @@ interface DesignSystemData {
     name: string;
     variant: "light" | "dark" | "auto";
   }[];
+  tokens?: {
+    name: string;      // The source system's own name, e.g. "interactive-01"
+    cssVar: string;    // e.g. "--cds-interactive-01"
+    value: string;     // e.g. "#0F62FE" or "0.5rem"
+    type: "color" | "typography" | "spacing" | "radius" | "shadow" | "other";
+    group?: string;    // Collection path, e.g. "Colors/Interactive"
+    source?: string;   // e.g. "Carbon v11" or "globals.css"
+  }[];
   imageStyle?: {
     referenceUrls: string[];
     styleDescription: string;  // e.g., "Clean, minimal product photography"
@@ -82,6 +90,29 @@ interface DesignSystemData {
 }
 ```
 
+### The seven color roles are a summary, not the vocabulary
+
+`colors` exists so a generated page can be themed from any brand. It is **not**
+where a real design system goes. Carbon has `interactive-01`, Material has
+`md-sys-color-primary-container`; mapping those onto `secondary` throws away the
+only name the design team uses, and the Brand Kit page then shows the wrong
+label for a token the user recognises.
+
+So when a source names its tokens, populate **both**: `colors` for generation,
+and `tokens` for the real vocabulary. `tokens` is capped at 500 entries, every
+`cssVar` must be a valid custom property, and values may not contain `;`, `{`,
+`}`, `<`, `>`, or CSS comments — `create-design-system` and
+`update-design-system` reject the whole write and name the offending entries
+rather than storing a partial vocabulary that would read as a smaller system.
+
+`update-design-system` replaces the entire `data` object, so carry the existing
+`tokens` array through any edit or those names are lost.
+
+A kit with no stored `tokens` falls back to whatever names its `customCSS`
+declares, which is why the production templates already display real Carbon,
+Material, and Primer token names. Prefer real stored `tokens` when a source
+gives them to you.
+
 `imageStyle.styleDescription` is not just metadata — fold it into every
 `generate-asset` prompt for a design linked to this system, alongside the
 subject/composition/lighting direction described in the design-generation
@@ -456,7 +487,11 @@ When the user provides multiple sources, call all applicable import actions in p
 3. **Cross-reference with website** — validates colors/fonts are actually deployed
 4. **Documents supplement** — presentations may reveal brand colors not in code
 5. **Images inform mood** — color temperature, density, visual style
-6. **Aggregate into DesignSystemData** — merge all extracted tokens, resolve conflicts
+6. **Aggregate into DesignSystemData** — merge all extracted tokens, resolve
+   conflicts, and carry every extracted name into `tokens`. The import actions
+   return `cssCustomProperties` keyed by the source's real variable names; those
+   keys are the vocabulary, so do not reduce them to the seven `colors` roles and
+   drop the rest.
 7. **Call `create-design-system`** with the combined result
 8. **Link to design** via `update-design --designSystemId`
 
@@ -509,6 +544,14 @@ When generating a design that has a linked design system, replace all default CS
 }
 ```
 
+### Reference named tokens, do not inline their values
+
+`get-design-system` injects the kit's colour tokens and this requirement into
+the generation context, so follow it there: write `var(--cds-link-primary,
+#0f62fe)` rather than the colour. The fallback is required — exports and
+kit-less designs define no custom properties, and a bare `var()` renders
+transparent.
+
 Also update the Google Fonts `<link>` tag to include the design system's fonts:
 
 ```html