@agent-native/core 0.75.5 → 0.76.1

package/corpus/core/src/localization/actions/set-localization-preference.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { putUserSetting } from "../../settings/user-settings.js";
+import {
+  LOCALIZATION_SETTING_KEY,
+  normalizeLocalePreference,
+  type LocalizationPreference,
+} from "../shared.js";
+
+export default defineAction({
+  description:
+    "Set the current user's interface language preference to 'system' or a supported BCP-47 locale.",
+  schema: z.object({
+    locale: z
+      .string()
+      .describe("Language preference: 'system' or a supported BCP-47 locale."),
+  }),
+  run: async (args, ctx): Promise<LocalizationPreference> => {
+    if (!ctx?.userEmail) throw new Error("Not authenticated.");
+    const locale = normalizeLocalePreference(args.locale);
+    if (!locale) {
+      throw new Error(
+        "Unsupported locale. Use system, en-US, zh-CN, es-ES, fr-FR, de-DE, ja-JP, ko-KR, pt-BR, hi-IN, or ar-SA.",
+      );
+    }
+    const value: LocalizationPreference & Record<string, unknown> = { locale };
+    await putUserSetting(ctx.userEmail, LOCALIZATION_SETTING_KEY, value);
+    return value;
+  },
+});

package/corpus/core/src/localization/index.ts

@@ -0,0 +1,2 @@
+export * from "./shared.js";
+export * from "./server.js";

package/corpus/core/src/localization/server.ts

@@ -0,0 +1,131 @@
+import {
+  DEFAULT_LOCALE,
+  LOCALE_HYDRATION_GLOBAL,
+  LOCALE_STORAGE_KEY,
+  SUPPORTED_LOCALES,
+  localeDirection,
+  normalizeLocaleCode,
+  normalizeLocalizationPreference,
+  resolveLocaleFromPreference,
+  type LocaleCode,
+  type LocalePreference,
+  type LocalizationPreference,
+} from "./shared.js";
+
+interface RequestLike {
+  headers?: Headers | Record<string, string | string[] | undefined> | null;
+}
+
+type HeaderMap = Headers | Record<string, string | string[] | undefined>;
+
+export interface ResolvedRequestLocale {
+  locale: LocaleCode;
+  preference: LocalizationPreference;
+  dir: "ltr" | "rtl";
+}
+
+export interface ResolveLocaleFromRequestOptions {
+  request?: Request | RequestLike | null;
+  acceptLanguage?: string | null;
+  preference?: LocalizationPreference | LocalePreference | null;
+  fallback?: LocaleCode;
+}
+
+export interface LocaleInitScriptOptions {
+  locale?: LocaleCode;
+  preference?: LocalizationPreference | LocalePreference;
+  messages?: Record<string, unknown> | null;
+}
+
+function readHeader(
+  headers: HeaderMap | undefined | null,
+  key: string,
+): string | null {
+  if (!headers) return null;
+  if (typeof (headers as Headers).get === "function") {
+    return (headers as Headers).get(key);
+  }
+  const lowerKey = key.toLowerCase();
+  for (const [name, value] of Object.entries(headers)) {
+    if (name.toLowerCase() !== lowerKey) continue;
+    if (Array.isArray(value)) return value.join(",");
+    return value ?? null;
+  }
+  return null;
+}
+
+export function parseAcceptLanguage(header: string | null | undefined) {
+  if (!header) return [];
+  return header
+    .split(",")
+    .map((part) => {
+      const [tag, ...params] = part.trim().split(";");
+      const q = params
+        .map((param) => param.trim())
+        .find((param) => param.startsWith("q="));
+      const weight = q ? Number.parseFloat(q.slice(2)) : 1;
+      return {
+        tag,
+        weight: Number.isFinite(weight) ? weight : 0,
+      };
+    })
+    .filter((entry) => entry.tag && entry.weight > 0)
+    .sort((a, b) => b.weight - a.weight)
+    .map((entry) => entry.tag);
+}
+
+export function resolveLocaleFromRequest(
+  options: ResolveLocaleFromRequestOptions = {},
+): ResolvedRequestLocale {
+  const header =
+    options.acceptLanguage ??
+    readHeader(options.request?.headers, "accept-language");
+  const candidates = parseAcceptLanguage(header);
+  const preference = normalizeLocalizationPreference(
+    options.preference ?? { locale: "system" },
+  );
+  const locale =
+    preference.locale === "system"
+      ? resolveLocaleFromPreference(preference, [
+          ...candidates,
+          options.fallback ?? DEFAULT_LOCALE,
+        ])
+      : (normalizeLocaleCode(preference.locale) ??
+        options.fallback ??
+        DEFAULT_LOCALE);
+  return {
+    locale,
+    preference,
+    dir: localeDirection(locale),
+  };
+}
+
+export function getLocaleInitScript(options: LocaleInitScriptOptions = {}) {
+  const safeLocale = normalizeLocaleCode(options.locale) ?? DEFAULT_LOCALE;
+  const shouldStorePreference = options.preference !== undefined;
+  const safePreference = normalizeLocalizationPreference(
+    options.preference ?? { locale: "system" },
+  );
+  const payload = {
+    locale: safeLocale,
+    preference: safePreference,
+    dir: localeDirection(safeLocale),
+    messages: options.messages ?? undefined,
+  };
+
+  return `(function(){try{var supported=${JSON.stringify(
+    SUPPORTED_LOCALES,
+  )};var payload=${JSON.stringify(
+    payload,
+  )};var shouldStorePreference=${JSON.stringify(
+    shouldStorePreference,
+  )};function valid(x){return supported.indexOf(x)>=0}function canon(x){if(typeof x!=='string'||!x)return null;try{var c=Intl.getCanonicalLocales(x)[0];if(valid(c))return c;var lang=c&&c.split('-')[0].toLowerCase();for(var i=0;i<supported.length;i++){if(supported[i].split('-')[0].toLowerCase()===lang)return supported[i]}}catch(e){}return null}function storageGet(k){try{return window.localStorage.getItem(k)}catch(e){return null}}function storageSet(k,v){try{window.localStorage.setItem(k,v)}catch(e){}}var stored=storageGet(${JSON.stringify(
+    LOCALE_STORAGE_KEY,
+  )});var pref=payload.preference&&payload.preference.locale;var locale=payload.locale;if(!valid(locale)){locale=null}if(!locale&&stored&&stored!=='system'){locale=canon(stored)}if(!locale&&pref&&pref!=='system'){locale=canon(pref)}if(!locale){var langs=navigator.languages&&navigator.languages.length?navigator.languages:[navigator.language];for(var j=0;j<langs.length&&!locale;j++){locale=canon(langs[j])}}if(!locale)locale=${JSON.stringify(
+    DEFAULT_LOCALE,
+  )};var root=document.documentElement;root.setAttribute('lang',locale);root.setAttribute('dir',locale==='ar-SA'?'rtl':'ltr');root.setAttribute('data-locale',locale);payload.locale=locale;payload.dir=locale==='ar-SA'?'rtl':'ltr';window[${JSON.stringify(
+    LOCALE_HYDRATION_GLOBAL,
+  )}]=payload;if(shouldStorePreference&&pref){storageSet(${JSON.stringify(
+    LOCALE_STORAGE_KEY,
+  )},pref)}}catch(e){}})();`;
+}

package/corpus/core/src/localization/shared.ts

@@ -0,0 +1,163 @@
+export const SUPPORTED_LOCALES = [
+  "en-US",
+  "zh-CN",
+  "es-ES",
+  "fr-FR",
+  "de-DE",
+  "ja-JP",
+  "ko-KR",
+  "pt-BR",
+  "hi-IN",
+  "ar-SA",
+] as const;
+
+export type LocaleCode = (typeof SUPPORTED_LOCALES)[number];
+export type LocalePreference = "system" | LocaleCode;
+
+export interface LocaleMetadata {
+  code: LocaleCode;
+  englishName: string;
+  nativeName: string;
+  dir: "ltr" | "rtl";
+}
+
+export interface LocalizationPreference {
+  locale: LocalePreference;
+}
+
+export const DEFAULT_LOCALE: LocaleCode = "en-US";
+export const LOCALIZATION_SETTING_KEY = "localization";
+export const LOCALE_STORAGE_KEY = "agent-native:locale-preference";
+export const LOCALE_HYDRATION_GLOBAL = "__AGENT_NATIVE_LOCALE__";
+
+export const LOCALE_METADATA: Record<LocaleCode, LocaleMetadata> = {
+  "en-US": {
+    code: "en-US",
+    englishName: "English",
+    nativeName: "English",
+    dir: "ltr",
+  },
+  "zh-CN": {
+    code: "zh-CN",
+    englishName: "Chinese (Simplified)",
+    nativeName: "简体中文",
+    dir: "ltr",
+  },
+  "es-ES": {
+    code: "es-ES",
+    englishName: "Spanish",
+    nativeName: "Español",
+    dir: "ltr",
+  },
+  "fr-FR": {
+    code: "fr-FR",
+    englishName: "French",
+    nativeName: "Français",
+    dir: "ltr",
+  },
+  "de-DE": {
+    code: "de-DE",
+    englishName: "German",
+    nativeName: "Deutsch",
+    dir: "ltr",
+  },
+  "ja-JP": {
+    code: "ja-JP",
+    englishName: "Japanese",
+    nativeName: "日本語",
+    dir: "ltr",
+  },
+  "ko-KR": {
+    code: "ko-KR",
+    englishName: "Korean",
+    nativeName: "한국어",
+    dir: "ltr",
+  },
+  "pt-BR": {
+    code: "pt-BR",
+    englishName: "Portuguese (Brazil)",
+    nativeName: "Português (Brasil)",
+    dir: "ltr",
+  },
+  "hi-IN": {
+    code: "hi-IN",
+    englishName: "Hindi",
+    nativeName: "हिन्दी",
+    dir: "ltr",
+  },
+  "ar-SA": {
+    code: "ar-SA",
+    englishName: "Arabic",
+    nativeName: "العربية",
+    dir: "rtl",
+  },
+};
+
+const SUPPORTED_LOCALE_SET = new Set<string>(SUPPORTED_LOCALES);
+
+export function isLocaleCode(value: unknown): value is LocaleCode {
+  return typeof value === "string" && SUPPORTED_LOCALE_SET.has(value);
+}
+
+export function normalizeLocaleCode(value: unknown): LocaleCode | null {
+  if (typeof value !== "string" || value.trim().length === 0) return null;
+  try {
+    for (const canonical of Intl.getCanonicalLocales(value.trim())) {
+      if (isLocaleCode(canonical)) return canonical;
+      const language = canonical.split("-")[0]?.toLowerCase();
+      const match = SUPPORTED_LOCALES.find(
+        (locale) => locale.split("-")[0]?.toLowerCase() === language,
+      );
+      if (match) return match;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+export function normalizeLocalePreference(
+  value: unknown,
+): LocalePreference | null {
+  if (value === "system") return "system";
+  return normalizeLocaleCode(value);
+}
+
+export function normalizeLocalizationPreference(
+  value: unknown,
+): LocalizationPreference {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const locale = normalizeLocalePreference(
+      (value as { locale?: unknown }).locale,
+    );
+    if (locale) return { locale };
+  }
+  const locale = normalizeLocalePreference(value);
+  return { locale: locale ?? "system" };
+}
+
+export function localeDirection(locale: LocaleCode): "ltr" | "rtl" {
+  return LOCALE_METADATA[locale]?.dir ?? "ltr";
+}
+
+export function resolveLocaleFromCandidates(
+  candidates: Iterable<unknown>,
+): LocaleCode {
+  for (const candidate of candidates) {
+    const normalized = normalizeLocaleCode(candidate);
+    if (normalized) return normalized;
+  }
+  return DEFAULT_LOCALE;
+}
+
+export function resolveLocaleFromPreference(
+  preference: LocalizationPreference | LocalePreference | unknown,
+  systemCandidates: Iterable<unknown> = [],
+): LocaleCode {
+  const normalized =
+    typeof preference === "string"
+      ? normalizeLocalePreference(preference)
+      : normalizeLocalizationPreference(preference).locale;
+  if (normalized && normalized !== "system") return normalized;
+  return resolveLocaleFromCandidates(systemCandidates);
+}

package/corpus/core/src/server/action-discovery.ts

@@ -575,6 +575,14 @@ export async function mergeCoreSharingActions(
       "context-report",
       () => import("../agent/context-xray/actions/context-report.js"),
     ],
+    [
+      "get-localization-preference",
+      () => import("../localization/actions/get-localization-preference.js"),
+    ],
+    [
+      "set-localization-preference",
+      () => import("../localization/actions/set-localization-preference.js"),
+    ],
     [
       "change-appearance",
       () => import("../appearance/actions/change-appearance.js"),

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -152,6 +152,7 @@ import {
 } from "../a2a/auth-policy.js";
 import {
   AGENT_CHAT_PROCESS_RUN_PATH,
+  extractProcessRunId,
   prepareProcessRunRequest,
 } from "../agent/durable-background.js";
 import {
@@ -7174,6 +7175,14 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
               status: run.status,
               heartbeatAt: run.heartbeatAt,
               lastProgressAt: run.lastProgressAt,
+              // Durable-background diagnostics: how the run was dispatched and
+              // the last reached `_process-run` worker stage (JSON
+              // `{stage,detail?,at}`). Surfaced here so a silent background
+              // worker death is diagnosable from the client WITHOUT the
+              // unreadable Netlify background-function logs — read
+              // `/runs/active?threadId=...` and inspect `diagStage`.
+              dispatchMode: run.dispatchMode ?? null,
+              diagStage: run.diagStage ?? null,
               // Server clock so the client computes "stuck" elapsed time
               // server-relative, immune to client clock skew.
               serverNow: Date.now(),
@@ -7791,6 +7800,19 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             setResponseStatus(event, 405);
             return { error: "Method not allowed" };
           }
+          // DIAGNOSTIC: load the run-store diagnostic recorder. Each stage we
+          // reach is written onto the run row (diag_stage) so a silent failure
+          // INSIDE the Netlify background function — whose logs we cannot read —
+          // is still diagnosable from the client via /runs/active. Best-effort:
+          // the import + every record call is wrapped so diagnostics can never
+          // break the worker path.
+          const diag = await import("../agent/run-store.js")
+            .then((m) => ({
+              record: m.recordRunDiagnostic,
+              stages: m.RUN_DIAG_STAGE,
+            }))
+            .catch(() => null);
+
           // Consume the body ONCE (h3 v2's web Request stream is single-use).
           let processBody: any;
           try {
@@ -7800,6 +7822,18 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             return { error: "Invalid request body" };
           }
 
+          // Record "the route handler was entered" against the run BEFORE auth
+          // runs. This is the proof the bg-fn invocation actually reached Nitro
+          // (vs. dying at the function entry / never being invoked). The runId
+          // is parsed without authenticating so we can attach it even on a
+          // subsequent auth failure.
+          const diagRunId = extractProcessRunId(processBody);
+          if (diag && diagRunId) {
+            await diag
+              .record(diagRunId, diag.stages.routeEntered)
+              .catch(() => {});
+          }
+
           // Validate + HMAC-authenticate the self-dispatch and prepare the
           // background-worker body. Pure decision (unit-tested in
           // durable-background.spec.ts); the route only wires it to h3.
@@ -7808,10 +7842,36 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             getHeader(event, "authorization"),
           );
           if (!prepared.ok) {
+            // DIAGNOSTIC: record the auth/validation failure ONTO the run
+            // before returning the error status. Without this, a 401 (e.g.
+            // A2A_SECRET missing/mismatched in the bg-fn env, or the path not
+            // bypassing session auth) inside the unreadable bg function would
+            // leave the run to time out with NO clue. The detail carries the
+            // status + whether A2A_SECRET is even present in this isolate.
+            if (diag && prepared.runId) {
+              const a2aPresent = Boolean(
+                process.env.A2A_SECRET && process.env.A2A_SECRET.length > 0,
+              );
+              await diag
+                .record(
+                  prepared.runId,
+                  diag.stages.authFailed,
+                  `status=${prepared.status} error=${prepared.error} a2aSecretPresent=${a2aPresent}`,
+                )
+                .catch(() => {});
+            }
             setResponseStatus(event, prepared.status);
             return { error: prepared.error };
           }
 
+          // DIAGNOSTIC: auth + body validation passed. Reaching here proves the
+          // request was authenticated and we are about to invoke the worker.
+          if (diag) {
+            await diag
+              .record(prepared.runId, diag.stages.authPassed)
+              .catch(() => {});
+          }
+
           // Stash the verified+augmented body for the handler — the body stream
           // is already consumed, so the handler reads this instead.
           (event as any).context = (event as any).context ?? {};
@@ -7821,6 +7881,17 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
             return await invokeAgentChatHandler(event);
           } catch (err: any) {
             console.error("[agent-chat] _process-run failed:", err);
+            // DIAGNOSTIC: the worker invocation threw at the route boundary —
+            // record the message so the failure cause is readable client-side.
+            if (diag) {
+              await diag
+                .record(
+                  prepared.runId,
+                  diag.stages.routeThrew,
+                  err instanceof Error ? err.message : String(err),
+                )
+                .catch(() => {});
+            }
             setResponseStatus(event, 500);
             return { error: "process-run failed" };
           }

package/corpus/core/src/server/auth.ts

@@ -1627,6 +1627,19 @@ function createAuthGuardFn(): (
       return;
     }
 
+    // Durable-background AGENT-CHAT processor. The foreground POST self-dispatches
+    // a long chat turn here (through the Netlify `-background` function, which
+    // rewrites its default url to this path); the route HMAC-verifies the
+    // dispatch (same internal-token scheme as agent-teams above) plus an atomic
+    // SQL claim. The self-dispatch carries ONLY a Bearer HMAC token and NO
+    // session cookie, so without this bypass the blanket 401-for-/_agent-native/*
+    // gate below blocks the worker before `prepareProcessRunRequest` ever runs —
+    // the run is never claimed, its heartbeat never starts, and it times out with
+    // no visible progress. Exact path only (mirrors agent-teams).
+    if (p === "/_agent-native/agent-chat/_process-run") {
+      return;
+    }
+
     // Read-only agent chat share links. The random token is the bearer secret;
     // the route returns a sanitized transcript plus bounded run summaries and
     // exposes no write surface, live event stream, tool payloads, or owner APIs.

package/corpus/core/src/server/index.ts

@@ -78,6 +78,14 @@ export {
 } from "./identity-sso.js";
 export { requireEnvKey, type MissingKeyResponse } from "./missing-key.js";
 export { verifyCaptcha, type CaptchaVerifyResult } from "./captcha.js";
+export {
+  getLocaleInitScript,
+  parseAcceptLanguage,
+  resolveLocaleFromRequest,
+  type LocaleInitScriptOptions,
+  type ResolveLocaleFromRequestOptions,
+  type ResolvedRequestLocale,
+} from "../localization/server.js";
 export {
   createProductionAgentHandler,
   type ActionEntry,

package/corpus/core/src/templates/default/.agents/skills/adding-a-feature/SKILL.md

@@ -86,6 +86,10 @@ Instruction examples may name secret keys like `SLACK_WEBHOOK`, but must use
 placeholders such as `${keys.SLACK_WEBHOOK}` or `<SLACK_WEBHOOK>`. Do not paste
 real keys, internal data, or customer data into instructions as examples.
 
+If the feature adds or changes visible UI copy, prompts, toasts, labels, empty
+states, or formatting, read `internationalization` and update the app's i18n
+catalogs in the same change.
+
 For app-backed skills, declare skill visibility in the app-skill manifest:
 
 - `internal` — only the app's own agents should use it.
@@ -177,3 +181,4 @@ TL;DR: spread `ownableColumns()` into the resource table, pair it with `createSh
 - **create-skill** — How to create skills for new patterns (area 3 in detail)
 - **storing-data** — Where to store the feature's data
 - **real-time-sync** — How the UI stays in sync when the agent writes data
+- **internationalization** — How to update localized UI copy and catalogs

package/corpus/core/src/templates/default/.agents/skills/internationalization/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: internationalization
+description: >-
+  How to add or edit localized UI copy in agent-native apps. Use when adding,
+  removing, or changing user-visible interface text, prompts, toasts, labels,
+  empty states, or date/number/list formatting.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Internationalization
+
+## Rule
+
+Visible framework/template UI copy belongs in the app's i18n catalog, not
+inline in components. When you add or edit UI text, update the English source
+catalog first, update existing locale catalogs, and run the i18n guard.
+
+## Catalogs
+
+Templates use `app/i18n/`:
+
+- `en-US.ts` is the canonical source tree and fallback.
+- Other locale files keep the same non-plural keys and the same placeholders.
+- `index.ts` exports an `AgentNativeI18nCatalog` with English bundled and
+  non-English catalogs loaded by dynamic import.
+
+Use BCP-47 filenames from the supported set: `en-US`, `zh-CN`, `es-ES`,
+`fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN`, `ar-SA`.
+
+## UI Pattern
+
+- Wrap apps with `AppProviders i18n={{ catalog: i18nCatalog }}`.
+- Read strings with `useT()` and keep keys stable.
+- Sidebar apps should expose a `/settings` route in the app sidebar. Put
+  `<LanguagePicker />` in that settings page, usually in a Language or General
+  section, and keep the header language icon only as a quick-access shortcut.
+- Settings pages should include an "Agent settings" row/card that calls
+  `openAgentSettings()` from `@agent-native/core/client` to open the right
+  agent sidebar's Settings tab. Localize the title, description, and button.
+- Use `useFormatters()` for dates, numbers, relative time, and lists instead
+  of embedding formatted values in translation strings.
+- Do not translate stable identifiers: action names, route names, enum values,
+  app-state keys, database values, protocol fields, env var names, or provider
+  names.
+
+## Plurals And Placeholders
+
+Plural strings use i18next/CLDR suffixes. Do not force every locale to copy
+English plural categories:
+
+- English uses `_one` and `_other`.
+- Chinese and Japanese usually use `_other`.
+- Arabic uses `_zero`, `_one`, `_two`, `_few`, `_many`, and `_other`.
+
+Keep interpolation placeholders identical across locales, such as
+`{{count}}`, `{{name}}`, or ICU-style `{count}` arguments.
+
+## RTL
+
+New UI should be RTL-safe. Prefer logical CSS utilities/properties such as
+`ms-*`, `me-*`, `ps-*`, `pe-*`, `start-*`, `end-*`, `text-start`, and
+`text-end` when direction matters. Avoid hardcoded left/right positioning for
+new localized UI unless it is genuinely physical.
+
+## Verification
+
+Run:
+
+```bash
+pnpm guard:i18n-catalogs
+```
+
+For broader changes, also run the affected template tests and `pnpm typecheck`.
+Machine translation is only a starting point; high-visibility strings need
+human review.

package/corpus/core/src/templates/default/.agents/skills/self-modifying-code/SKILL.md

@@ -66,6 +66,11 @@ el.dataset.selectedId = selectedItem?.id || "";
 
 **Use configuration-driven rendering** — Extract visual decisions (colors, layouts, sizes) into JSON config files in `data/`. The agent can modify the config (Tier 1) instead of the component source (Tier 2).
 
+**Keep localized copy in catalogs** — When editing visible UI copy, labels,
+toasts, empty states, prompts, or formatting, read `internationalization` and
+update `app/i18n/en-US.ts` plus existing locale catalogs instead of leaving new
+inline strings in components.
+
 ## Don't
 
 - Don't modify `.env` files or files containing secrets
@@ -80,3 +85,4 @@ el.dataset.selectedId = selectedItem?.id || "";
 - **actions** — The agent can create or modify actions to add new capabilities
 - **delegate-to-agent** — Self-modification requests come through the agent chat
 - **real-time-sync** — Database writes trigger change events to update the UI
+- **internationalization** — UI copy, language catalogs, locale switching, and RTL-safe edits

package/corpus/core/src/templates/default/AGENTS.md

@@ -143,21 +143,22 @@ repackage, or proxy an action.
 
 Skills in `.agents/skills/` provide detailed guidance for each architectural rule. Read them before making changes.
 
-| Skill                 | When to read                                                                      |
-| --------------------- | --------------------------------------------------------------------------------- |
-| `agent-native-docs`   | Before using advanced Agent Native framework APIs or generated-app features       |
-| `adding-a-feature`    | **Read first when adding ANY new feature** — the four-area parity checklist       |
-| `real-time-sync`      | Before wiring data fetching for anything the agent can mutate (must auto-refresh) |
-| `storing-data`        | Before storing or reading any app state                                           |
-| `delegate-to-agent`   | Before adding LLM calls or AI delegation                                          |
-| `actions`             | Before creating or modifying actions                                              |
-| `self-modifying-code` | Before editing source, components, or styles                                      |
-| `capture-learnings`   | Before recording user preferences or corrections                                  |
-| `frontend-design`     | Before building or restyling any UI component, page, or layout                    |
-| `shadcn-ui`           | Before adding, updating, or debugging shadcn/ui components                        |
-| `agent-engines`       | Before switching LLM providers or registering a custom engine                     |
-| `notifications`       | Before surfacing alerts/progress to the user or adding channels                   |
-| `progress`            | Before running any task that takes more than a few seconds                        |
+| Skill                  | When to read                                                                      |
+| ---------------------- | --------------------------------------------------------------------------------- |
+| `agent-native-docs`    | Before using advanced Agent Native framework APIs or generated-app features       |
+| `adding-a-feature`     | **Read first when adding ANY new feature** — the four-area parity checklist       |
+| `real-time-sync`       | Before wiring data fetching for anything the agent can mutate (must auto-refresh) |
+| `storing-data`         | Before storing or reading any app state                                           |
+| `internationalization` | Before adding or editing visible UI copy, prompts, toasts, labels, or formatting  |
+| `delegate-to-agent`    | Before adding LLM calls or AI delegation                                          |
+| `actions`              | Before creating or modifying actions                                              |
+| `self-modifying-code`  | Before editing source, components, or styles                                      |
+| `capture-learnings`    | Before recording user preferences or corrections                                  |
+| `frontend-design`      | Before building or restyling any UI component, page, or layout                    |
+| `shadcn-ui`            | Before adding, updating, or debugging shadcn/ui components                        |
+| `agent-engines`        | Before switching LLM providers or registering a custom engine                     |
+| `notifications`        | Before surfacing alerts/progress to the user or adding channels                   |
+| `progress`             | Before running any task that takes more than a few seconds                        |
 
 ## When Adding Features