@agent-native/core 0.75.5 → 0.76.1

package/dist/templates/workspace-core/.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/dist/vite/action-types-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-types-plugin.d.ts","sourceRoot":"","sources":["../../src/vite/action-types-plugin.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AA6TnC;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAuC1C;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAG1E"}
+{"version":3,"file":"action-types-plugin.d.ts","sourceRoot":"","sources":["../../src/vite/action-types-plugin.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAuUnC;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAuC1C;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAG1E"}

package/dist/vite/action-types-plugin.js

@@ -74,6 +74,14 @@ const CORE_SHARING_ACTIONS = [
         name: "context-report",
         specifier: "@agent-native/core/agent/context-xray/actions/context-report",
     },
+    {
+        name: "get-localization-preference",
+        specifier: "@agent-native/core/localization/actions/get-localization-preference",
+    },
+    {
+        name: "set-localization-preference",
+        specifier: "@agent-native/core/localization/actions/set-localization-preference",
+    },
 ];
 function isRuntimeSourceFile(filename) {
     if (!/\.(ts|js)$/.test(filename))

package/dist/vite/action-types-plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"action-types-plugin.js","sourceRoot":"","sources":["../../src/vite/action-types-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,MAAM,IAAI,CAAC;AAGpB,oEAAoE;AACpE,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;IACzB,SAAS;IACT,KAAK;IACL,YAAY;IACZ,WAAW;IACX,UAAU;CACX,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,oBAAoB,GAA+C;IACvE;QACE,IAAI,EAAE,gBAAgB;QACtB,SAAS,EAAE,mDAAmD;KAC/D;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,SAAS,EAAE,qDAAqD;KACjE;IACD;QACE,IAAI,EAAE,sBAAsB;QAC5B,SAAS,EAAE,yDAAyD;KACrE;IACD;QACE,IAAI,EAAE,yBAAyB;QAC/B,SAAS,EAAE,4DAA4D;KACxE;IACD;QACE,IAAI,EAAE,cAAc;QACpB,SAAS,EAAE,qDAAqD;KACjE;IACD;QACE,IAAI,EAAE,sBAAsB;QAC5B,SAAS,EACP,oEAAoE;KACvE;IACD;QACE,IAAI,EAAE,aAAa;QACnB,SAAS,EAAE,2DAA2D;KACvE;IACD;QACE,IAAI,EAAE,eAAe;QACrB,SAAS,EAAE,6DAA6D;KACzE;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,SAAS,EAAE,+DAA+D;KAC3E;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,SAAS,EAAE,8DAA8D;KAC1E;CACF,CAAC;AAEF,SAAS,mBAAmB,CAAC,QAAgB;IAC3C,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/C,IAAI,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,yBAAyB,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,eAAe,CAAC,UAAkB;IACzC,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QACxB,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAC1C,MAAM,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QACzC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACvC,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QACvC,mEAAmE;QACnE,yEAAyE;QACzE,wEAAwE;QACxE,qEAAqE;QACrE,8BAA8B;QAC9B,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YACnE,MAAM,sBAAsB,GAC1B,oDAAoD,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACrE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,sBAAsB,EAAE,CAAC;gBACjE,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,OAAO,CAAC,IAAY;IAC3B,OAAO,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,cAAc,CAAC,OAAe,EAAE,OAAe;IACtD,MAAM,QAAQ,GAAG,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC;QACrC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC;QACnC,CAAC,CAAC,EAAE,CAAC;IACP,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACrC,CAAC;AACH,CAAC;AAED,SAAS,2BAA2B,CAAC,WAAmB;IACtD,IAAI,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACpC,IAAI,aAAa,GAAkB,IAAI,CAAC;IACxC,IAAI,WAAW,GAAkB,IAAI,CAAC;IAEtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QAC/C,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;gBAC1D,MAAM,QAAQ,GAAG,GAAG,EAAE,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC;gBACtD,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACxD,aAAa,GAAG,GAAG,CAAC;oBACpB,WAAW,GAAG,QAAQ,CAAC;oBACvB,MAAM;gBACR,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,0CAA0C;YAC5C,CAAC;QACH,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;IAED,IAAI,CAAC,aAAa,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAEhD,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,cAAc,EAAE,WAAW,CAAC,CAAC;IACjE,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC;QACjD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC;QAC7D,OAAO,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;IACvD,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;IACzD,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,IAAI,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC/B,KAAK,MAAM,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,WAAW,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;YACzE,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;gBAAE,SAAS;YACnC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;YACpD,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;gBACpD,KAAK,MAAM,GAAG,IAAI,EAAE,CAAC,WAAW,CAAC,QAAQ,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;oBACpE,IAAI,GAAG,CAAC,WAAW,EAAE;wBAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;gBACxE,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;QACrD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC;YAAE,SAAS;QACtC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;YAC1D,IAAI,GAAG,EAAE,IAAI,KAAK,WAAW,EAAE,CAAC;gBAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;gBACnD,OAAO,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;YACvD,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,iCAAiC;QACnC,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,SAAS,uBAAuB,CAC9B,UAAkB,EAClB,WAAmB;IAEnB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IACvD,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAE5E,MAAM,WAAW,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;IAChD,MAAM,mBAAmB,GAAG,2BAA2B,CAAC,WAAW,CAAC,CAAC;IACrE,MAAM,oBAAoB,GAAG,mBAAmB;QAC9C,CAAC,CAAC,eAAe,CAAC,mBAAmB,CAAC;QACtC,CAAC,CAAC,EAAE,CAAC;IAEP,2EAA2E;IAC3E,wDAAwD;IACxD,MAAM,mBAAmB,GAAG,IAAI,GAAG,CACjC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,CACpD,CAAC;IACF,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAE3D,MAAM,aAAa,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC1C,MAAM,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QACzC,OAAO;YACL,IAAI;YACJ,OAAO,EAAE,GAAG,aAAa,IAAI,IAAI,EAAE;SACpC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,IAAI,mBAAmB,EAAE,CAAC;QACxB,KAAK,MAAM,CAAC,IAAI,oBAAoB,EAAE,CAAC;YACrC,MAAM,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;YACzC,IAAI,qBAAqB,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,SAAS;YAC9C,MAAM,OAAO,GAAG,IAAI;iBACjB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,IAAI,CAAC,CAAC;iBACtD,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACvB,aAAa,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;YACtC,qBAAqB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,MAAM,WAAW,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;QAC1D,OAAO,QAAQ,IAAI,iCAAiC,OAAO,MAAM,CAAC;IACpE,CAAC,CAAC,CAAC;IAEH,0EAA0E;IAC1E,0EAA0E;IAC1E,KAAK,MAAM,KAAK,IAAI,oBAAoB,EAAE,CAAC;QACzC,IAAI,qBAAqB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,SAAS;QACpD,WAAW,CAAC,IAAI,CACd,QAAQ,KAAK,CAAC,IAAI,iCAAiC,KAAK,CAAC,SAAS,MAAM,CACzE,CAAC;QACF,qBAAqB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IAED,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;EAerB,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;;;;;CAKvB,CAAC;IAEA,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAAE,YAAY,CAAC,CAAC;IAErE,2EAA2E;IAC3E,uEAAuE;IACvE,oEAAoE;IACpE,2DAA2D;IAC3D,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAAU,CAAC;IAC7C,KAAK,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,aAAa,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC5B,OAAO,CAAC,IAAI,CAAC,eAAe,KAAK,UAAU,OAAO,IAAI,CAAC,CAAC;QACxD,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,KAAK,GAAG,CAAC,CAAC;QACrD,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IACD,wEAAwE;IACxE,0EAA0E;IAC1E,wDAAwD;IACxD,iEAAiE;IACjE,KAAK,MAAM,KAAK,IAAI,oBAAoB,EAAE,CAAC;QACzC,IAAI,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,SAAS;QACjD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAClC,OAAO,CAAC,IAAI,CAAC,eAAe,KAAK,UAAU,KAAK,CAAC,SAAS,IAAI,CAAC,CAAC;QAChE,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,GAAG,CAAC,CAAC;QAC3D,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAED,MAAM,eAAe,GAAG;;;;EAIxB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;;;EAGlB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;;;;CAInB,CAAC;IAEA,2EAA2E;IAC3E,4EAA4E;IAC5E,wDAAwD;IACxD,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,qBAAqB,CAAC,EAAE,eAAe,CAAC,CAAC;IAE1E,sCAAsC;IACtC,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IAC3D,IAAI,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QACjC,MAAM,SAAS,GAAG,EAAE,CAAC,YAAY,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QAC1D,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YACtC,EAAE,CAAC,cAAc,CAAC,aAAa,EAAE,iBAAiB,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,WAAW,GAAG,EAAE,CAAC;IACrB,IAAI,UAAU,GAAG,EAAE,CAAC;IACpB,IAAI,mBAAmB,GAAkB,IAAI,CAAC;IAE9C,OAAO;QACL,IAAI,EAAE,2BAA2B;QACjC,cAAc,CAAC,MAAM;YACnB,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC;YAC1B,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;YAClD,mBAAmB,GAAG,2BAA2B,CAAC,WAAW,CAAC,CAAC;QACjE,CAAC;QACD,UAAU;YACR,uBAAuB,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;QACnD,CAAC;QACD,eAAe,CAAC,MAAM;YACpB,sBAAsB;YACtB,uBAAuB,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;YAEjD,gCAAgC;YAChC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;YAC/B,MAAM,YAAY,GAAG,CAAC,IAAY,EAAE,EAAE;gBACpC,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;gBACjD,MAAM,kBAAkB,GAAG,mBAAmB;oBAC5C,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,mBAAmB,CAAC;oBACtC,CAAC,CAAC,KAAK,CAAC;gBACV,IAAI,CAAC,YAAY,IAAI,kBAAkB,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;oBACpE,uBAAuB,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;gBACnD,CAAC;YACH,CAAC,CAAC;YACF,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YACxB,IAAI,mBAAmB;gBAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;YAC1D,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;YAChC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;YACnC,qEAAqE;YACrE,uEAAuE;YACvE,6CAA6C;QAC/C,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gCAAgC,CAAC,WAAmB;IAClE,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IACxD,uBAAuB,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;AACnD,CAAC","sourcesContent":["/**\n * Vite plugin that generates end-to-end type-safe action types AND a runtime\n * registry of static imports so bundlers (Nitro on Netlify/Vercel/AWS-Lambda,\n * Rolldown, etc.) include every action file in the server bundle.\n *\n * Watches the `actions/` directory and emits:\n *   - `.generated/action-types.d.ts` — type-only module that augments the\n *     `ActionRegistry` interface in `@agent-native/core/client`, giving\n *     `useActionQuery`/`useActionMutation` full inference.\n *   - `.generated/actions-registry.ts` — runtime registry keyed by action\n *     name, with static `import` statements for every action. Templates\n *     import this file from their `server/plugins/agent-chat.ts` so Nitro\n *     bundles the actions into the server function; without it the runtime\n *     `fs.readdirSync` inside `autoDiscoverActions` finds nothing in a\n *     bundled serverless function and every action route 404s.\n */\nimport path from \"path\";\nimport fs from \"fs\";\nimport type { Plugin } from \"vite\";\n\n/** Files to skip during discovery (matches action-discovery.ts). */\nconst SKIP_FILES = new Set([\n  \"helpers\",\n  \"run\",\n  \"db-connect\",\n  \"db-status\",\n  \"registry\",\n]);\n\n/**\n * Framework-level sharing actions that must ALWAYS be in the generated\n * registry, even when the template's `actions/` directory doesn't contain\n * them. Each entry maps the action name to the bare-specifier import path so\n * bundlers see a static import and pull the module into the server bundle.\n *\n * Order matters: templates can override by defining a same-named file in\n * their own `actions/` directory — the merge below is skip-existing.\n */\nconst CORE_SHARING_ACTIONS: Array<{ name: string; specifier: string }> = [\n  {\n    name: \"share-resource\",\n    specifier: \"@agent-native/core/sharing/actions/share-resource\",\n  },\n  {\n    name: \"unshare-resource\",\n    specifier: \"@agent-native/core/sharing/actions/unshare-resource\",\n  },\n  {\n    name: \"list-resource-shares\",\n    specifier: \"@agent-native/core/sharing/actions/list-resource-shares\",\n  },\n  {\n    name: \"set-resource-visibility\",\n    specifier: \"@agent-native/core/sharing/actions/set-resource-visibility\",\n  },\n  {\n    name: \"upload-image\",\n    specifier: \"@agent-native/core/file-upload/actions/upload-image\",\n  },\n  {\n    name: \"context-manifest-get\",\n    specifier:\n      \"@agent-native/core/agent/context-xray/actions/context-manifest-get\",\n  },\n  {\n    name: \"context-pin\",\n    specifier: \"@agent-native/core/agent/context-xray/actions/context-pin\",\n  },\n  {\n    name: \"context-evict\",\n    specifier: \"@agent-native/core/agent/context-xray/actions/context-evict\",\n  },\n  {\n    name: \"context-restore\",\n    specifier: \"@agent-native/core/agent/context-xray/actions/context-restore\",\n  },\n  {\n    name: \"context-report\",\n    specifier: \"@agent-native/core/agent/context-xray/actions/context-report\",\n  },\n];\n\nfunction isRuntimeSourceFile(filename: string): boolean {\n  if (!/\\.(ts|js)$/.test(filename)) return false;\n  if (/\\.d\\.ts$/.test(filename)) return false;\n  if (/\\.(test|spec)\\.(ts|js)$/.test(filename)) return false;\n  return true;\n}\n\nfunction scanActionFiles(actionsDir: string): string[] {\n  let files: string[];\n  try {\n    files = fs.readdirSync(actionsDir);\n  } catch {\n    return [];\n  }\n  return files.filter((f) => {\n    if (!isRuntimeSourceFile(f)) return false;\n    const name = f.replace(/\\.(ts|js)$/, \"\");\n    if (name.startsWith(\"_\")) return false;\n    if (SKIP_FILES.has(name)) return false;\n    // Only include files that actually call defineAction or explicitly\n    // re-export a package action. CLI scripts or example templates that live\n    // in actions/ but don't export an action would otherwise drag their own\n    // (often app/, browser-only, or fs-only) imports into the serverless\n    // bundle and fail to resolve.\n    try {\n      const content = fs.readFileSync(path.join(actionsDir, f), \"utf-8\");\n      const reexportsDefaultAction =\n        /export\\s*\\{\\s*default\\s*\\}\\s*from\\s*[\"'][^\"']+[\"']/.test(content);\n      if (!content.includes(\"defineAction\") && !reexportsDefaultAction) {\n        return false;\n      }\n    } catch {\n      return false;\n    }\n    return true;\n  });\n}\n\nfunction toIdent(name: string): string {\n  return \"a_\" + name.replace(/[^a-zA-Z0-9_]/g, \"_\");\n}\n\nfunction writeIfChanged(outFile: string, content: string): void {\n  const existing = fs.existsSync(outFile)\n    ? fs.readFileSync(outFile, \"utf-8\")\n    : \"\";\n  if (existing !== content) {\n    fs.mkdirSync(path.dirname(outFile), { recursive: true });\n    fs.writeFileSync(outFile, content);\n  }\n}\n\nfunction findWorkspaceCoreActionsDir(projectRoot: string): string | null {\n  let dir = path.resolve(projectRoot);\n  let workspaceRoot: string | null = null;\n  let packageName: string | null = null;\n\n  for (let i = 0; i < 20; i++) {\n    const pkgPath = path.join(dir, \"package.json\");\n    if (fs.existsSync(pkgPath)) {\n      try {\n        const pkg = JSON.parse(fs.readFileSync(pkgPath, \"utf-8\"));\n        const declared = pkg?.[\"agent-native\"]?.workspaceCore;\n        if (typeof declared === \"string\" && declared.length > 0) {\n          workspaceRoot = dir;\n          packageName = declared;\n          break;\n        }\n      } catch {\n        // Keep walking on malformed package.json.\n      }\n    }\n    const parent = path.dirname(dir);\n    if (parent === dir) break;\n    dir = parent;\n  }\n\n  if (!workspaceRoot || !packageName) return null;\n\n  const nm = path.join(workspaceRoot, \"node_modules\", packageName);\n  if (fs.existsSync(path.join(nm, \"package.json\"))) {\n    const actionsDir = path.join(fs.realpathSync(nm), \"actions\");\n    return fs.existsSync(actionsDir) ? actionsDir : null;\n  }\n\n  const packagesDir = path.join(workspaceRoot, \"packages\");\n  const candidates: string[] = [];\n  if (fs.existsSync(packagesDir)) {\n    for (const entry of fs.readdirSync(packagesDir, { withFileTypes: true })) {\n      if (!entry.isDirectory()) continue;\n      candidates.push(path.join(packagesDir, entry.name));\n      if (entry.name.startsWith(\"@\")) {\n        const scopeDir = path.join(packagesDir, entry.name);\n        for (const sub of fs.readdirSync(scopeDir, { withFileTypes: true })) {\n          if (sub.isDirectory()) candidates.push(path.join(scopeDir, sub.name));\n        }\n      }\n    }\n  }\n\n  for (const candidate of candidates) {\n    const pkgPath = path.join(candidate, \"package.json\");\n    if (!fs.existsSync(pkgPath)) continue;\n    try {\n      const pkg = JSON.parse(fs.readFileSync(pkgPath, \"utf-8\"));\n      if (pkg?.name === packageName) {\n        const actionsDir = path.join(candidate, \"actions\");\n        return fs.existsSync(actionsDir) ? actionsDir : null;\n      }\n    } catch {\n      // Ignore malformed package.json.\n    }\n  }\n\n  return null;\n}\n\n/**\n * Scan the actions directory and emit the types + runtime registry files.\n * Only writes files whose content has changed, to avoid triggering rebuilds.\n */\nfunction generateActionArtifacts(\n  actionsDir: string,\n  projectRoot: string,\n): void {\n  const outDir = path.resolve(projectRoot, \".generated\");\n  const relActionsDir = path.relative(outDir, actionsDir).replace(/\\\\/g, \"/\");\n\n  const actionFiles = scanActionFiles(actionsDir);\n  const workspaceActionsDir = findWorkspaceCoreActionsDir(projectRoot);\n  const workspaceActionFiles = workspaceActionsDir\n    ? scanActionFiles(workspaceActionsDir)\n    : [];\n\n  // Pre-compute template action names — used for skip-existing logic in both\n  // the type declarations and the runtime registry below.\n  const templateActionNames = new Set<string>(\n    actionFiles.map((f) => f.replace(/\\.(ts|js)$/, \"\")),\n  );\n  const registeredActionNames = new Set(templateActionNames);\n\n  const actionSources = actionFiles.map((f) => {\n    const name = f.replace(/\\.(ts|js)$/, \"\");\n    return {\n      name,\n      relPath: `${relActionsDir}/${name}`,\n    };\n  });\n\n  if (workspaceActionsDir) {\n    for (const f of workspaceActionFiles) {\n      const name = f.replace(/\\.(ts|js)$/, \"\");\n      if (registeredActionNames.has(name)) continue;\n      const relPath = path\n        .relative(outDir, path.join(workspaceActionsDir, name))\n        .replace(/\\\\/g, \"/\");\n      actionSources.push({ name, relPath });\n      registeredActionNames.add(name);\n    }\n  }\n\n  // --- types file ---------------------------------------------------------\n  const typeEntries = actionSources.map(({ name, relPath }) => {\n    return `    \"${name}\": ActionEntry<typeof import(\"${relPath}\")>;`;\n  });\n\n  // Also declare types for framework-level sharing actions so callers don't\n  // need `as any` casts (same skip-existing logic as the runtime registry).\n  for (const entry of CORE_SHARING_ACTIONS) {\n    if (registeredActionNames.has(entry.name)) continue;\n    typeEntries.push(\n      `    \"${entry.name}\": ActionEntry<typeof import(\"${entry.specifier}\")>;`,\n    );\n    registeredActionNames.add(entry.name);\n  }\n\n  const typesContent = `// AUTO-GENERATED by @agent-native/core — do not edit manually.\n// Regenerated when files in actions/ change.\n// This file augments the ActionRegistry interface so that useActionQuery and\n// useActionMutation infer the correct types from your action definitions.\n\n/** Extract the return type and parameter type from a defineAction module. */\ntype ActionEntry<T> = T extends { default: { run: (...args: infer A) => infer R } }\n  ? {\n      result: Awaited<R>;\n      params: A extends [infer P, ...any[]] ? P : Record<string, any>;\n    }\n  : { result: any; params: Record<string, any> };\n\ndeclare module \"@agent-native/core/client\" {\n  interface ActionRegistry {\n${typeEntries.join(\"\\n\")}\n  }\n}\n\nexport {};\n`;\n\n  writeIfChanged(path.join(outDir, \"action-types.d.ts\"), typesContent);\n\n  // --- runtime registry ---------------------------------------------------\n  // Static imports of each action's default export so bundlers see every\n  // action and include it in the server bundle. Normalization matches\n  // `loadActionsIntoRegistry` in server/action-discovery.ts.\n  const imports: string[] = [];\n  const entries: string[] = [];\n  const runtimeActionNames = new Set<string>();\n  for (const { name, relPath } of actionSources) {\n    const ident = toIdent(name);\n    imports.push(`import * as ${ident} from \"${relPath}\";`);\n    entries.push(`  ${JSON.stringify(name)}: ${ident},`);\n    runtimeActionNames.add(name);\n  }\n  // Framework-level sharing actions — only added when the template hasn't\n  // provided a same-named file (skip-existing merge). Static imports ensure\n  // bundlers pull these modules into the server bundle so\n  // `/_agent-native/actions/share-resource` (etc.) always resolve.\n  for (const entry of CORE_SHARING_ACTIONS) {\n    if (runtimeActionNames.has(entry.name)) continue;\n    const ident = toIdent(entry.name);\n    imports.push(`import * as ${ident} from \"${entry.specifier}\";`);\n    entries.push(`  ${JSON.stringify(entry.name)}: ${ident},`);\n    runtimeActionNames.add(entry.name);\n  }\n\n  const registryContent = `// AUTO-GENERATED by @agent-native/core — do not edit manually.\n// Static-import registry of every action file. Bundlers (Nitro, Rolldown)\n// see these imports and include the action modules in the server bundle.\n// The agent-chat plugin normalizes each module into an ActionEntry shape.\n${imports.join(\"\\n\")}\n\nconst modules: Record<string, unknown> = {\n${entries.join(\"\\n\")}\n};\n\nexport default modules;\n`;\n\n  // Always write the registry — even when the template has no actions/ files\n  // we still emit imports for the framework-level sharing actions so they get\n  // mounted on every template that consumes the registry.\n  writeIfChanged(path.join(outDir, \"actions-registry.ts\"), registryContent);\n\n  // Ensure .generated/ is in .gitignore\n  const gitignorePath = path.join(projectRoot, \".gitignore\");\n  if (fs.existsSync(gitignorePath)) {\n    const gitignore = fs.readFileSync(gitignorePath, \"utf-8\");\n    if (!gitignore.includes(\".generated\")) {\n      fs.appendFileSync(gitignorePath, \"\\n.generated/\\n\");\n    }\n  }\n}\n\n/**\n * Vite plugin that watches `actions/` and generates type-safe action types.\n *\n * Add to your Vite config (auto-included by `defineConfig` from `@agent-native/core`):\n *\n * ```ts\n * import { actionTypesPlugin } from \"@agent-native/core/vite/action-types-plugin\";\n * plugins: [actionTypesPlugin()]\n * ```\n */\nexport function actionTypesPlugin(): Plugin {\n  let projectRoot = \"\";\n  let actionsDir = \"\";\n  let workspaceActionsDir: string | null = null;\n\n  return {\n    name: \"agent-native-action-types\",\n    configResolved(config) {\n      projectRoot = config.root;\n      actionsDir = path.resolve(projectRoot, \"actions\");\n      workspaceActionsDir = findWorkspaceCoreActionsDir(projectRoot);\n    },\n    buildStart() {\n      generateActionArtifacts(actionsDir, projectRoot);\n    },\n    configureServer(server) {\n      // Generate on startup\n      generateActionArtifacts(actionsDir, projectRoot);\n\n      // Watch for changes in actions/\n      const watcher = server.watcher;\n      const handleChange = (file: string) => {\n        const inAppActions = file.startsWith(actionsDir);\n        const inWorkspaceActions = workspaceActionsDir\n          ? file.startsWith(workspaceActionsDir)\n          : false;\n        if ((inAppActions || inWorkspaceActions) && /\\.(ts|js)$/.test(file)) {\n          generateActionArtifacts(actionsDir, projectRoot);\n        }\n      };\n      watcher.add(actionsDir);\n      if (workspaceActionsDir) watcher.add(workspaceActionsDir);\n      watcher.on(\"add\", handleChange);\n      watcher.on(\"unlink\", handleChange);\n      // Don't regenerate on content changes — only file additions/removals\n      // affect the registry. Return type changes are picked up by TypeScript\n      // from the source files via typeof import().\n    },\n  };\n}\n\n/**\n * Public helper to regenerate the types + registry from a non-Vite context\n * (e.g. the Nitro deploy build, where Vite plugins don't run).\n */\nexport function generateActionRegistryForProject(projectRoot: string): void {\n  const actionsDir = path.resolve(projectRoot, \"actions\");\n  generateActionArtifacts(actionsDir, projectRoot);\n}\n"]}
+{"version":3,"file":"action-types-plugin.js","sourceRoot":"","sources":["../../src/vite/action-types-plugin.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Vite plugin that generates end-to-end type-safe action types AND a runtime\n * registry of static imports so bundlers (Nitro on Netlify/Vercel/AWS-Lambda,\n * Rolldown, etc.) include every action file in the server bundle.\n *\n * Watches the `actions/` directory and emits:\n *   - `.generated/action-types.d.ts` — type-only module that augments the\n *     `ActionRegistry` interface in `@agent-native/core/client`, giving\n *     `useActionQuery`/`useActionMutation` full inference.\n *   - `.generated/actions-registry.ts` — runtime registry keyed by action\n *     name, with static `import` statements for every action. Templates\n *     import this file from their `server/plugins/agent-chat.ts` so Nitro\n *     bundles the actions into the server function; without it the runtime\n *     `fs.readdirSync` inside `autoDiscoverActions` finds nothing in a\n *     bundled serverless function and every action route 404s.\n */\nimport path from \"path\";\nimport fs from \"fs\";\nimport type { Plugin } from \"vite\";\n\n/** Files to skip during discovery (matches action-discovery.ts). */\nconst SKIP_FILES = new Set([\n  \"helpers\",\n  \"run\",\n  \"db-connect\",\n  \"db-status\",\n  \"registry\",\n]);\n\n/**\n * Framework-level sharing actions that must ALWAYS be in the generated\n * registry, even when the template's `actions/` directory doesn't contain\n * them. Each entry maps the action name to the bare-specifier import path so\n * bundlers see a static import and pull the module into the server bundle.\n *\n * Order matters: templates can override by defining a same-named file in\n * their own `actions/` directory — the merge below is skip-existing.\n */\nconst CORE_SHARING_ACTIONS: Array<{ name: string; specifier: string }> = [\n  {\n    name: \"share-resource\",\n    specifier: \"@agent-native/core/sharing/actions/share-resource\",\n  },\n  {\n    name: \"unshare-resource\",\n    specifier: \"@agent-native/core/sharing/actions/unshare-resource\",\n  },\n  {\n    name: \"list-resource-shares\",\n    specifier: \"@agent-native/core/sharing/actions/list-resource-shares\",\n  },\n  {\n    name: \"set-resource-visibility\",\n    specifier: \"@agent-native/core/sharing/actions/set-resource-visibility\",\n  },\n  {\n    name: \"upload-image\",\n    specifier: \"@agent-native/core/file-upload/actions/upload-image\",\n  },\n  {\n    name: \"context-manifest-get\",\n    specifier:\n      \"@agent-native/core/agent/context-xray/actions/context-manifest-get\",\n  },\n  {\n    name: \"context-pin\",\n    specifier: \"@agent-native/core/agent/context-xray/actions/context-pin\",\n  },\n  {\n    name: \"context-evict\",\n    specifier: \"@agent-native/core/agent/context-xray/actions/context-evict\",\n  },\n  {\n    name: \"context-restore\",\n    specifier: \"@agent-native/core/agent/context-xray/actions/context-restore\",\n  },\n  {\n    name: \"context-report\",\n    specifier: \"@agent-native/core/agent/context-xray/actions/context-report\",\n  },\n  {\n    name: \"get-localization-preference\",\n    specifier:\n      \"@agent-native/core/localization/actions/get-localization-preference\",\n  },\n  {\n    name: \"set-localization-preference\",\n    specifier:\n      \"@agent-native/core/localization/actions/set-localization-preference\",\n  },\n];\n\nfunction isRuntimeSourceFile(filename: string): boolean {\n  if (!/\\.(ts|js)$/.test(filename)) return false;\n  if (/\\.d\\.ts$/.test(filename)) return false;\n  if (/\\.(test|spec)\\.(ts|js)$/.test(filename)) return false;\n  return true;\n}\n\nfunction scanActionFiles(actionsDir: string): string[] {\n  let files: string[];\n  try {\n    files = fs.readdirSync(actionsDir);\n  } catch {\n    return [];\n  }\n  return files.filter((f) => {\n    if (!isRuntimeSourceFile(f)) return false;\n    const name = f.replace(/\\.(ts|js)$/, \"\");\n    if (name.startsWith(\"_\")) return false;\n    if (SKIP_FILES.has(name)) return false;\n    // Only include files that actually call defineAction or explicitly\n    // re-export a package action. CLI scripts or example templates that live\n    // in actions/ but don't export an action would otherwise drag their own\n    // (often app/, browser-only, or fs-only) imports into the serverless\n    // bundle and fail to resolve.\n    try {\n      const content = fs.readFileSync(path.join(actionsDir, f), \"utf-8\");\n      const reexportsDefaultAction =\n        /export\\s*\\{\\s*default\\s*\\}\\s*from\\s*[\"'][^\"']+[\"']/.test(content);\n      if (!content.includes(\"defineAction\") && !reexportsDefaultAction) {\n        return false;\n      }\n    } catch {\n      return false;\n    }\n    return true;\n  });\n}\n\nfunction toIdent(name: string): string {\n  return \"a_\" + name.replace(/[^a-zA-Z0-9_]/g, \"_\");\n}\n\nfunction writeIfChanged(outFile: string, content: string): void {\n  const existing = fs.existsSync(outFile)\n    ? fs.readFileSync(outFile, \"utf-8\")\n    : \"\";\n  if (existing !== content) {\n    fs.mkdirSync(path.dirname(outFile), { recursive: true });\n    fs.writeFileSync(outFile, content);\n  }\n}\n\nfunction findWorkspaceCoreActionsDir(projectRoot: string): string | null {\n  let dir = path.resolve(projectRoot);\n  let workspaceRoot: string | null = null;\n  let packageName: string | null = null;\n\n  for (let i = 0; i < 20; i++) {\n    const pkgPath = path.join(dir, \"package.json\");\n    if (fs.existsSync(pkgPath)) {\n      try {\n        const pkg = JSON.parse(fs.readFileSync(pkgPath, \"utf-8\"));\n        const declared = pkg?.[\"agent-native\"]?.workspaceCore;\n        if (typeof declared === \"string\" && declared.length > 0) {\n          workspaceRoot = dir;\n          packageName = declared;\n          break;\n        }\n      } catch {\n        // Keep walking on malformed package.json.\n      }\n    }\n    const parent = path.dirname(dir);\n    if (parent === dir) break;\n    dir = parent;\n  }\n\n  if (!workspaceRoot || !packageName) return null;\n\n  const nm = path.join(workspaceRoot, \"node_modules\", packageName);\n  if (fs.existsSync(path.join(nm, \"package.json\"))) {\n    const actionsDir = path.join(fs.realpathSync(nm), \"actions\");\n    return fs.existsSync(actionsDir) ? actionsDir : null;\n  }\n\n  const packagesDir = path.join(workspaceRoot, \"packages\");\n  const candidates: string[] = [];\n  if (fs.existsSync(packagesDir)) {\n    for (const entry of fs.readdirSync(packagesDir, { withFileTypes: true })) {\n      if (!entry.isDirectory()) continue;\n      candidates.push(path.join(packagesDir, entry.name));\n      if (entry.name.startsWith(\"@\")) {\n        const scopeDir = path.join(packagesDir, entry.name);\n        for (const sub of fs.readdirSync(scopeDir, { withFileTypes: true })) {\n          if (sub.isDirectory()) candidates.push(path.join(scopeDir, sub.name));\n        }\n      }\n    }\n  }\n\n  for (const candidate of candidates) {\n    const pkgPath = path.join(candidate, \"package.json\");\n    if (!fs.existsSync(pkgPath)) continue;\n    try {\n      const pkg = JSON.parse(fs.readFileSync(pkgPath, \"utf-8\"));\n      if (pkg?.name === packageName) {\n        const actionsDir = path.join(candidate, \"actions\");\n        return fs.existsSync(actionsDir) ? actionsDir : null;\n      }\n    } catch {\n      // Ignore malformed package.json.\n    }\n  }\n\n  return null;\n}\n\n/**\n * Scan the actions directory and emit the types + runtime registry files.\n * Only writes files whose content has changed, to avoid triggering rebuilds.\n */\nfunction generateActionArtifacts(\n  actionsDir: string,\n  projectRoot: string,\n): void {\n  const outDir = path.resolve(projectRoot, \".generated\");\n  const relActionsDir = path.relative(outDir, actionsDir).replace(/\\\\/g, \"/\");\n\n  const actionFiles = scanActionFiles(actionsDir);\n  const workspaceActionsDir = findWorkspaceCoreActionsDir(projectRoot);\n  const workspaceActionFiles = workspaceActionsDir\n    ? scanActionFiles(workspaceActionsDir)\n    : [];\n\n  // Pre-compute template action names — used for skip-existing logic in both\n  // the type declarations and the runtime registry below.\n  const templateActionNames = new Set<string>(\n    actionFiles.map((f) => f.replace(/\\.(ts|js)$/, \"\")),\n  );\n  const registeredActionNames = new Set(templateActionNames);\n\n  const actionSources = actionFiles.map((f) => {\n    const name = f.replace(/\\.(ts|js)$/, \"\");\n    return {\n      name,\n      relPath: `${relActionsDir}/${name}`,\n    };\n  });\n\n  if (workspaceActionsDir) {\n    for (const f of workspaceActionFiles) {\n      const name = f.replace(/\\.(ts|js)$/, \"\");\n      if (registeredActionNames.has(name)) continue;\n      const relPath = path\n        .relative(outDir, path.join(workspaceActionsDir, name))\n        .replace(/\\\\/g, \"/\");\n      actionSources.push({ name, relPath });\n      registeredActionNames.add(name);\n    }\n  }\n\n  // --- types file ---------------------------------------------------------\n  const typeEntries = actionSources.map(({ name, relPath }) => {\n    return `    \"${name}\": ActionEntry<typeof import(\"${relPath}\")>;`;\n  });\n\n  // Also declare types for framework-level sharing actions so callers don't\n  // need `as any` casts (same skip-existing logic as the runtime registry).\n  for (const entry of CORE_SHARING_ACTIONS) {\n    if (registeredActionNames.has(entry.name)) continue;\n    typeEntries.push(\n      `    \"${entry.name}\": ActionEntry<typeof import(\"${entry.specifier}\")>;`,\n    );\n    registeredActionNames.add(entry.name);\n  }\n\n  const typesContent = `// AUTO-GENERATED by @agent-native/core — do not edit manually.\n// Regenerated when files in actions/ change.\n// This file augments the ActionRegistry interface so that useActionQuery and\n// useActionMutation infer the correct types from your action definitions.\n\n/** Extract the return type and parameter type from a defineAction module. */\ntype ActionEntry<T> = T extends { default: { run: (...args: infer A) => infer R } }\n  ? {\n      result: Awaited<R>;\n      params: A extends [infer P, ...any[]] ? P : Record<string, any>;\n    }\n  : { result: any; params: Record<string, any> };\n\ndeclare module \"@agent-native/core/client\" {\n  interface ActionRegistry {\n${typeEntries.join(\"\\n\")}\n  }\n}\n\nexport {};\n`;\n\n  writeIfChanged(path.join(outDir, \"action-types.d.ts\"), typesContent);\n\n  // --- runtime registry ---------------------------------------------------\n  // Static imports of each action's default export so bundlers see every\n  // action and include it in the server bundle. Normalization matches\n  // `loadActionsIntoRegistry` in server/action-discovery.ts.\n  const imports: string[] = [];\n  const entries: string[] = [];\n  const runtimeActionNames = new Set<string>();\n  for (const { name, relPath } of actionSources) {\n    const ident = toIdent(name);\n    imports.push(`import * as ${ident} from \"${relPath}\";`);\n    entries.push(`  ${JSON.stringify(name)}: ${ident},`);\n    runtimeActionNames.add(name);\n  }\n  // Framework-level sharing actions — only added when the template hasn't\n  // provided a same-named file (skip-existing merge). Static imports ensure\n  // bundlers pull these modules into the server bundle so\n  // `/_agent-native/actions/share-resource` (etc.) always resolve.\n  for (const entry of CORE_SHARING_ACTIONS) {\n    if (runtimeActionNames.has(entry.name)) continue;\n    const ident = toIdent(entry.name);\n    imports.push(`import * as ${ident} from \"${entry.specifier}\";`);\n    entries.push(`  ${JSON.stringify(entry.name)}: ${ident},`);\n    runtimeActionNames.add(entry.name);\n  }\n\n  const registryContent = `// AUTO-GENERATED by @agent-native/core — do not edit manually.\n// Static-import registry of every action file. Bundlers (Nitro, Rolldown)\n// see these imports and include the action modules in the server bundle.\n// The agent-chat plugin normalizes each module into an ActionEntry shape.\n${imports.join(\"\\n\")}\n\nconst modules: Record<string, unknown> = {\n${entries.join(\"\\n\")}\n};\n\nexport default modules;\n`;\n\n  // Always write the registry — even when the template has no actions/ files\n  // we still emit imports for the framework-level sharing actions so they get\n  // mounted on every template that consumes the registry.\n  writeIfChanged(path.join(outDir, \"actions-registry.ts\"), registryContent);\n\n  // Ensure .generated/ is in .gitignore\n  const gitignorePath = path.join(projectRoot, \".gitignore\");\n  if (fs.existsSync(gitignorePath)) {\n    const gitignore = fs.readFileSync(gitignorePath, \"utf-8\");\n    if (!gitignore.includes(\".generated\")) {\n      fs.appendFileSync(gitignorePath, \"\\n.generated/\\n\");\n    }\n  }\n}\n\n/**\n * Vite plugin that watches `actions/` and generates type-safe action types.\n *\n * Add to your Vite config (auto-included by `defineConfig` from `@agent-native/core`):\n *\n * ```ts\n * import { actionTypesPlugin } from \"@agent-native/core/vite/action-types-plugin\";\n * plugins: [actionTypesPlugin()]\n * ```\n */\nexport function actionTypesPlugin(): Plugin {\n  let projectRoot = \"\";\n  let actionsDir = \"\";\n  let workspaceActionsDir: string | null = null;\n\n  return {\n    name: \"agent-native-action-types\",\n    configResolved(config) {\n      projectRoot = config.root;\n      actionsDir = path.resolve(projectRoot, \"actions\");\n      workspaceActionsDir = findWorkspaceCoreActionsDir(projectRoot);\n    },\n    buildStart() {\n      generateActionArtifacts(actionsDir, projectRoot);\n    },\n    configureServer(server) {\n      // Generate on startup\n      generateActionArtifacts(actionsDir, projectRoot);\n\n      // Watch for changes in actions/\n      const watcher = server.watcher;\n      const handleChange = (file: string) => {\n        const inAppActions = file.startsWith(actionsDir);\n        const inWorkspaceActions = workspaceActionsDir\n          ? file.startsWith(workspaceActionsDir)\n          : false;\n        if ((inAppActions || inWorkspaceActions) && /\\.(ts|js)$/.test(file)) {\n          generateActionArtifacts(actionsDir, projectRoot);\n        }\n      };\n      watcher.add(actionsDir);\n      if (workspaceActionsDir) watcher.add(workspaceActionsDir);\n      watcher.on(\"add\", handleChange);\n      watcher.on(\"unlink\", handleChange);\n      // Don't regenerate on content changes — only file additions/removals\n      // affect the registry. Return type changes are picked up by TypeScript\n      // from the source files via typeof import().\n    },\n  };\n}\n\n/**\n * Public helper to regenerate the types + registry from a non-Vite context\n * (e.g. the Nitro deploy build, where Vite plugins don't run).\n */\nexport function generateActionRegistryForProject(projectRoot: string): void {\n  const actionsDir = path.resolve(projectRoot, \"actions\");\n  generateActionArtifacts(actionsDir, projectRoot);\n}\n"]}

package/docs/AGENTS.md

@@ -49,6 +49,7 @@ For source examples, read matching files under
 | Define or call app operations         | `content/actions.md`, `content/client.md`                                                                |
 | Add SQL data, schema, or access rules | `content/database.md`, `content/security.md`, `content/sharing.md`                                       |
 | Keep the UI and agent in sync         | `content/context-awareness.md`, `content/client.md`                                                      |
+| Localize UI copy and language choices | `content/internationalization.md`, `content/client.md`                                                   |
 | Build headless or chat-first apps     | `content/pure-agent-apps.md`, `content/agent-surfaces.md`, `content/using-your-agent.md`                 |
 | Add automations or scheduled work     | `content/automations.md`, `content/recurring-jobs.md`                                                    |
 | Compose apps or call sibling agents   | `content/a2a-protocol.md`, `content/multi-app-workspace.md`, `content/workspace.md`                      |

package/docs/content/client.md

@@ -129,6 +129,21 @@ and `submit` for those.
 
 `useAgentChatContext()` returns `{ items, set, remove, clear, refresh }`.
 
+## openAgentSettings(section?) {#openagentsettings}
+
+Use `openAgentSettings()` when an app settings page or setup card should open
+the agent sidebar's Settings tab. Pass a section id such as `"llm"`, `"secrets"`,
+`"automations"`, `"voice"`, or `"limits"` to open a specific section.
+
+```ts
+import { openAgentSettings } from "@agent-native/core/client";
+
+openAgentSettings();
+openAgentSettings("secrets");
+```
+
+Prefer this helper over dispatching `agent-panel:open-settings` directly.
+
 ```tsx
 import { useAgentChatContext } from "@agent-native/core/client";
 

package/docs/content/internationalization.md

@@ -0,0 +1,145 @@
+---
+title: "Internationalization"
+description: "Localize Agent Native apps with shared locale catalogs, a language picker, browser-language fallback, and locale-aware docs content."
+---
+
+# Internationalization
+
+Agent Native apps can localize framework and template UI through the shared
+`@agent-native/core/client/i18n` runtime. The framework stores the user's
+language choice in SQL settings, exposes it as actions, and falls back to
+English when an app has not translated a string yet.
+
+## Runtime
+
+Use the provider through `AppProviders`:
+
+```tsx
+import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
+import { i18nCatalog } from "./i18n";
+
+const LOCALE_INIT_SCRIPT = getLocaleInitScript();
+
+<script
+  data-agent-native-locale-init
+  dangerouslySetInnerHTML={{ __html: LOCALE_INIT_SCRIPT }}
+/>;
+
+<AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+  <Outlet />
+</AppProviders>;
+```
+
+`getLocaleInitScript()` sets the initial `lang`, `dir`, and
+`window.__AGENT_NATIVE_LOCALE__` before React hydrates. Public SSR routes can
+call `resolveLocaleFromRequest()` from `@agent-native/core/server` and pass the
+resolved locale/catalog into that script to avoid hydration mismatches.
+
+## Catalogs
+
+Each localized template keeps catalogs under `app/i18n/`:
+
+```ts
+// app/i18n/index.ts
+import enUS from "./en-US";
+import type { AgentNativeI18nCatalog } from "@agent-native/core/client";
+
+export const i18nCatalog = {
+  sourceLocale: "en-US",
+  messages: enUS,
+  loadMessages: async (locale) => {
+    switch (locale) {
+      case "zh-CN":
+        return (await import("./zh-CN")).default;
+      default:
+        return null;
+    }
+  },
+} satisfies AgentNativeI18nCatalog;
+```
+
+Always bundle `en-US`. Dynamic-import non-English catalogs so users only
+download the active locale. The supported locale codes are `en-US`, `zh-CN`,
+`es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN`, and `ar-SA`.
+
+## UI
+
+Use `useT()` for interface strings and put `<LanguagePicker />` on the app's
+`/settings` page. Sidebar apps should expose **Settings** in the app sidebar;
+the header language icon is only a shortcut.
+
+```tsx
+import {
+  LanguagePicker,
+  openAgentSettings,
+  useT,
+} from "@agent-native/core/client";
+
+function SettingsPage() {
+  const t = useT();
+  return (
+    <>
+      <h2>{t("settings.languageTitle")}</h2>
+      <LanguagePicker label={t("settings.languageLabel")} />
+
+      <h2>{t("settings.agentTitle")}</h2>
+      <p>{t("settings.agentDescription")}</p>
+      <button type="button" onClick={() => openAgentSettings()}>
+        {t("settings.openAgentSettings")}
+      </button>
+    </>
+  );
+}
+```
+
+The "Agent settings" control should open the right agent sidebar's Settings tab
+for model, API key, automation, voice, and other framework-level controls.
+Apps may duplicate high-value framework settings in their own settings page
+when the setting is central to the app, but the sidebar settings tab remains the
+source of truth.
+
+Use `useFormatters()` for dates, numbers, relative time, and lists. Do not put
+locale-sensitive date/number formatting inside translation strings.
+
+## Docs Site Content {#docs-site-content}
+
+Public docs pages use the same core provider, but with
+`persistPreference={false}` so anonymous docs traffic uses localStorage and the
+browser language instead of SQL settings actions. The English source remains in
+`packages/core/docs/content/*.md`. Localized page overrides live next to it under
+`packages/core/docs/content/locales/<locale>/<slug>.md`.
+
+Use the same BCP-47 locale codes as app catalogs. Keep the same slug as the
+English source, preserve stable anchors with `{#anchor}` on translated headings,
+and leave routes, action names, protocol fields, env vars, and provider names
+untranslated. If a locale has no translated Markdown for a page, the docs site
+falls back to English for that page while still localizing navigation and chrome.
+
+## Actions And Persistence
+
+Every app inherits:
+
+- `get-localization-preference` — read the current user's `{ locale }`
+- `set-localization-preference` — set `"system"` or a supported locale
+
+The durable value lives in user-scoped SQL settings under `localization`.
+`localStorage` is only used for pre-hydration and anonymous fallback. The active
+locale is mirrored into application state as ambient context so agents can see
+the current interface language.
+
+## Guard
+
+Run:
+
+```bash
+pnpm guard:i18n-catalogs
+```
+
+The guard verifies supported locale filenames, key parity, placeholder parity,
+stale keys, and CLDR plural categories through `Intl.PluralRules`. It checks
+structure, not translation quality; high-visibility strings still need human
+review.
+
+Do not translate stable identifiers such as action names, routes, enum values,
+app-state keys, database values, protocol fields, env var names, or provider
+names.

package/docs/content/locales/ar-SA/internationalization.md

@@ -0,0 +1,102 @@
+---
+title: "التدويل"
+description: "قم بتعريب تطبيقات Agent Native باستخدام كتالوجات locale مشتركة، واختيار اللغة، والرجوع إلى لغة المتصفح، ومحتوى docs حسب locale."
+---
+
+# التدويل
+
+يمكن لتطبيقات Agent Native تعريب واجهة framework و templates عبر runtime المشترك `@agent-native/core/client/i18n`. يخزن framework اختيار لغة المستخدم في SQL settings، ويعرضه كـ actions، ويرجع إلى English عندما لا تكون string مترجمة في التطبيق بعد.
+
+## Runtime {#runtime}
+
+استخدم provider عبر `AppProviders`:
+
+```tsx
+import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
+import { i18nCatalog } from "./i18n";
+
+const LOCALE_INIT_SCRIPT = getLocaleInitScript();
+
+<script
+  data-agent-native-locale-init
+  dangerouslySetInnerHTML={{ __html: LOCALE_INIT_SCRIPT }}
+/>;
+
+<AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+  <Outlet />
+</AppProviders>;
+```
+
+يضبط `getLocaleInitScript()` قيم `lang` و `dir` و `window.__AGENT_NATIVE_LOCALE__` قبل React hydration. يمكن لمسارات SSR العامة استدعاء `resolveLocaleFromRequest()` من `@agent-native/core/server` وتمرير locale/catalog الناتج إلى script لتجنب hydration mismatches.
+
+## Catalogs {#catalogs}
+
+كل template مترجم يحتفظ بالكتالوجات تحت `app/i18n/`:
+
+```ts
+// app/i18n/index.ts
+import enUS from "./en-US";
+import type { AgentNativeI18nCatalog } from "@agent-native/core/client";
+
+export const i18nCatalog = {
+  sourceLocale: "en-US",
+  messages: enUS,
+  loadMessages: async (locale) => {
+    switch (locale) {
+      case "zh-CN":
+        return (await import("./zh-CN")).default;
+      default:
+        return null;
+    }
+  },
+} satisfies AgentNativeI18nCatalog;
+```
+
+احزم `en-US` دائماً. استخدم dynamic import للكتالوجات غير English حتى ينزل المستخدمون locale النشط فقط. locale codes المدعومة هي `en-US` و `zh-CN` و `es-ES` و `fr-FR` و `de-DE` و `ja-JP` و `ko-KR` و `pt-BR` و `hi-IN` و `ar-SA`.
+
+## UI {#ui}
+
+استخدم `useT()` لنصوص الواجهة و `<LanguagePicker />` في settings:
+
+```tsx
+import { LanguagePicker, useT } from "@agent-native/core/client";
+
+function SettingsLanguageCard() {
+  const t = useT();
+  return (
+    <>
+      <h2>{t("settings.languageTitle")}</h2>
+      <LanguagePicker label={t("settings.languageLabel")} />
+    </>
+  );
+}
+```
+
+استخدم `useFormatters()` للتواريخ، والأرقام، والوقت النسبي، والقوائم. لا تضع تنسيق التاريخ أو الرقم المعتمد على locale داخل strings المترجمة.
+
+## محتوى موقع docs {#docs-site-content}
+
+تستخدم صفحات docs العامة نفس core provider، لكن مع `persistPreference={false}` حتى يستخدم زوار docs المجهولون localStorage ولغة المتصفح بدلاً من SQL settings actions. يبقى مصدر English في `packages/core/docs/content/*.md`. توجد overrides المترجمة في `packages/core/docs/content/locales/<locale>/<slug>.md`.
+
+استخدم نفس BCP-47 locale codes الخاصة بكتالوجات التطبيقات. حافظ على نفس slug الموجود في مصدر English، واحفظ anchors ثابتة باستخدام `{#anchor}` على headings المترجمة، ولا تترجم routes أو action names أو protocol fields أو env vars أو provider names. إذا لم يملك locale ملف Markdown مترجماً لصفحة ما، يعود موقع docs إلى English لتلك الصفحة مع استمرار تعريب navigation و chrome.
+
+## Actions والاستمرارية {#actions-and-persistence}
+
+كل تطبيق يرث:
+
+- `get-localization-preference` — يقرأ `{ locale }` للمستخدم الحالي
+- `set-localization-preference` — يضبط `"system"` أو locale مدعوماً
+
+القيمة الدائمة موجودة في SQL settings بنطاق المستخدم تحت `localization`. يستخدم `localStorage` فقط قبل hydration وللرجوع المجهول. ينعكس locale النشط في application state كسياق محيط حتى تتمكن agents من رؤية لغة الواجهة الحالية.
+
+## Guard {#guard}
+
+شغّل:
+
+```bash
+pnpm guard:i18n-catalogs
+```
+
+يتحقق guard من أسماء ملفات locale المدعومة، و key parity، و placeholder parity، و stale keys، وفئات CLDR plural عبر `Intl.PluralRules`. هو يتحقق من البنية لا جودة الترجمة؛ strings البارزة ما زالت تحتاج مراجعة بشرية.
+
+لا تترجم المعرفات الثابتة مثل action names أو routes أو enum values أو app-state keys أو database values أو protocol fields أو env var names أو provider names.

package/docs/content/locales/de-DE/internationalization.md

@@ -0,0 +1,102 @@
+---
+title: "Internationalisierung"
+description: "Lokalisiere Agent Native Apps mit gemeinsamen Locale-Katalogen, Sprachauswahl, Browser-Fallback und locale-bewussten Docs."
+---
+
+# Internationalisierung
+
+Agent Native Apps können Framework- und Template-UI über die gemeinsame Runtime `@agent-native/core/client/i18n` lokalisieren. Das Framework speichert die Sprachwahl des Benutzers in SQL-Settings, stellt sie als actions bereit und fällt auf English zurück, wenn eine App einen String noch nicht übersetzt hat.
+
+## Runtime {#runtime}
+
+Verwende den Provider über `AppProviders`:
+
+```tsx
+import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
+import { i18nCatalog } from "./i18n";
+
+const LOCALE_INIT_SCRIPT = getLocaleInitScript();
+
+<script
+  data-agent-native-locale-init
+  dangerouslySetInnerHTML={{ __html: LOCALE_INIT_SCRIPT }}
+/>;
+
+<AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+  <Outlet />
+</AppProviders>;
+```
+
+`getLocaleInitScript()` setzt das anfängliche `lang`, `dir` und `window.__AGENT_NATIVE_LOCALE__`, bevor React hydriert. Öffentliche SSR-Routen können `resolveLocaleFromRequest()` aus `@agent-native/core/server` aufrufen und den aufgelösten locale/catalog an das Script übergeben, um Hydration-Abweichungen zu vermeiden.
+
+## Kataloge {#catalogs}
+
+Jedes lokalisierte Template hält Kataloge unter `app/i18n/`:
+
+```ts
+// app/i18n/index.ts
+import enUS from "./en-US";
+import type { AgentNativeI18nCatalog } from "@agent-native/core/client";
+
+export const i18nCatalog = {
+  sourceLocale: "en-US",
+  messages: enUS,
+  loadMessages: async (locale) => {
+    switch (locale) {
+      case "zh-CN":
+        return (await import("./zh-CN")).default;
+      default:
+        return null;
+    }
+  },
+} satisfies AgentNativeI18nCatalog;
+```
+
+Bundle immer `en-US`. Importiere Nicht-English-Kataloge dynamisch, damit Benutzer nur den aktiven locale herunterladen. Unterstützte locale codes sind `en-US`, `zh-CN`, `es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN` und `ar-SA`.
+
+## UI {#ui}
+
+Verwende `useT()` für UI-Texte und `<LanguagePicker />` in den Settings:
+
+```tsx
+import { LanguagePicker, useT } from "@agent-native/core/client";
+
+function SettingsLanguageCard() {
+  const t = useT();
+  return (
+    <>
+      <h2>{t("settings.languageTitle")}</h2>
+      <LanguagePicker label={t("settings.languageLabel")} />
+    </>
+  );
+}
+```
+
+Verwende `useFormatters()` für Datumswerte, Zahlen, relative Zeiten und Listen. Lege locale-abhängige Datums- oder Zahlenformatierung nicht in Übersetzungsstrings ab.
+
+## Docs-Site-Inhalt {#docs-site-content}
+
+Öffentliche Docs-Seiten verwenden denselben core provider, aber mit `persistPreference={false}`, damit anonymer Docs-Traffic localStorage und die Browsersprache nutzt statt SQL-Settings-actions. Die English-Quelle bleibt in `packages/core/docs/content/*.md`. Lokalisierte Seiten-Overrides liegen unter `packages/core/docs/content/locales/<locale>/<slug>.md`.
+
+Verwende dieselben BCP-47 locale codes wie App-Kataloge. Behalte denselben slug wie die English-Quelle, bewahre stabile Anker mit `{#anchor}` auf übersetzten Überschriften und übersetze keine routes, action names, protocol fields, env vars oder provider names. Wenn ein locale keine übersetzte Markdown-Datei für eine Seite hat, fällt die Docs-Site für diese Seite auf English zurück, lokalisiert aber weiterhin Navigation und Chrome.
+
+## Actions und Persistenz {#actions-and-persistence}
+
+Jede App erbt:
+
+- `get-localization-preference` — liest `{ locale }` des aktuellen Benutzers
+- `set-localization-preference` — setzt `"system"` oder einen unterstützten locale
+
+Der dauerhafte Wert liegt in benutzerbezogenen SQL-Settings unter `localization`. `localStorage` wird nur für Pre-Hydration und anonymen Fallback genutzt. Der aktive locale wird als Umgebungskontext in application state gespiegelt, damit agents die aktuelle UI-Sprache sehen.
+
+## Guard {#guard}
+
+Ausführen:
+
+```bash
+pnpm guard:i18n-catalogs
+```
+
+Der Guard prüft unterstützte locale-Dateinamen, key parity, placeholder parity, stale keys und CLDR-Pluralkategorien über `Intl.PluralRules`. Er prüft Struktur, nicht Übersetzungsqualität; gut sichtbare Strings brauchen weiterhin menschliche Prüfung.
+
+Übersetze keine stabilen Bezeichner wie action names, routes, enum values, app-state keys, database values, protocol fields, env var names oder provider names.

package/docs/content/locales/es-ES/internationalization.md

@@ -0,0 +1,102 @@
+---
+title: "Internacionalización"
+description: "Localiza apps Agent Native con catálogos compartidos, selector de idioma, fallback al navegador y contenido de docs por locale."
+---
+
+# Internacionalización
+
+Las apps Agent Native pueden localizar la UI del framework y de las plantillas con el runtime compartido `@agent-native/core/client/i18n`. El framework guarda la elección de idioma del usuario en settings SQL, la expone como actions y vuelve a English cuando una app aún no tradujo una cadena.
+
+## Runtime {#runtime}
+
+Usa el provider a través de `AppProviders`:
+
+```tsx
+import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
+import { i18nCatalog } from "./i18n";
+
+const LOCALE_INIT_SCRIPT = getLocaleInitScript();
+
+<script
+  data-agent-native-locale-init
+  dangerouslySetInnerHTML={{ __html: LOCALE_INIT_SCRIPT }}
+/>;
+
+<AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+  <Outlet />
+</AppProviders>;
+```
+
+`getLocaleInitScript()` define el `lang`, `dir` y `window.__AGENT_NATIVE_LOCALE__` iniciales antes de que React hidrate. Las rutas SSR públicas pueden llamar a `resolveLocaleFromRequest()` desde `@agent-native/core/server` y pasar el locale/catalog resuelto al script para evitar desajustes de hydration.
+
+## Catálogos {#catalogs}
+
+Cada plantilla localizada mantiene catálogos en `app/i18n/`:
+
+```ts
+// app/i18n/index.ts
+import enUS from "./en-US";
+import type { AgentNativeI18nCatalog } from "@agent-native/core/client";
+
+export const i18nCatalog = {
+  sourceLocale: "en-US",
+  messages: enUS,
+  loadMessages: async (locale) => {
+    switch (locale) {
+      case "zh-CN":
+        return (await import("./zh-CN")).default;
+      default:
+        return null;
+    }
+  },
+} satisfies AgentNativeI18nCatalog;
+```
+
+Incluye siempre `en-US`. Importa dinámicamente los catálogos que no sean English para que cada usuario descargue solo el locale activo. Los locale codes admitidos son `en-US`, `zh-CN`, `es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN` y `ar-SA`.
+
+## UI {#ui}
+
+Usa `useT()` para textos de interfaz y `<LanguagePicker />` en settings:
+
+```tsx
+import { LanguagePicker, useT } from "@agent-native/core/client";
+
+function SettingsLanguageCard() {
+  const t = useT();
+  return (
+    <>
+      <h2>{t("settings.languageTitle")}</h2>
+      <LanguagePicker label={t("settings.languageLabel")} />
+    </>
+  );
+}
+```
+
+Usa `useFormatters()` para fechas, números, tiempo relativo y listas. No pongas formatos sensibles al locale dentro de cadenas traducidas.
+
+## Contenido del sitio de docs {#docs-site-content}
+
+Las páginas públicas de docs usan el mismo core provider, pero con `persistPreference={false}` para que el tráfico anónimo use localStorage y el idioma del navegador en vez de actions de settings SQL. La fuente English queda en `packages/core/docs/content/*.md`. Las páginas localizadas que sobrescriben esa fuente viven en `packages/core/docs/content/locales/<locale>/<slug>.md`.
+
+Usa los mismos BCP-47 locale codes que los catálogos de app. Conserva el mismo slug que la fuente English, preserva anclas estables con `{#anchor}` en headings traducidos y no traduzcas routes, action names, protocol fields, env vars ni provider names. Si un locale no tiene Markdown traducido para una página, el sitio cae a English para esa página mientras sigue localizando la navegación y el chrome.
+
+## Actions y persistencia {#actions-and-persistence}
+
+Cada app hereda:
+
+- `get-localization-preference` — lee el `{ locale }` del usuario actual
+- `set-localization-preference` — define `"system"` o un locale admitido
+
+El valor durable vive en settings SQL con alcance de usuario bajo `localization`. `localStorage` solo se usa para pre-hydration y fallback anónimo. El locale activo se refleja en application state como contexto ambiental para que los agents vean el idioma actual de la interfaz.
+
+## Guard {#guard}
+
+Ejecuta:
+
+```bash
+pnpm guard:i18n-catalogs
+```
+
+El guard verifica nombres de archivos locale admitidos, key parity, placeholder parity, stale keys y categorías plurales CLDR mediante `Intl.PluralRules`. Revisa estructura, no calidad de traducción; las cadenas de alta visibilidad necesitan revisión humana.
+
+No traduzcas identificadores estables como action names, routes, enum values, app-state keys, database values, protocol fields, env var names o provider names.