@agent-native/core 0.101.5 → 0.101.6

package/corpus/templates/clips/changelog/2026-07-15-hovering-a-truncated-folder-name-now-shows-the-full-name.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-15
+---
+
+Hovering a truncated folder name now shows the full name.

package/corpus/templates/clips/changelog/2026-07-15-space-creation-controls-are-now-shown-only-to-organization-a.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-15
+---
+
+Space creation controls are now shown only to organization admins and owners.

package/corpus/templates/clips/changelog/2026-07-15-vocabulary-terms-can-now-be-deleted-from-the-dictation-dicti.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-15
+---
+
+Vocabulary terms can now be deleted from the dictation dictionary.

package/corpus/templates/clips/desktop/src/styles.css

@@ -1220,6 +1220,28 @@ body[data-clips-route="recording-pill"] #root {
   flex-direction: column;
   gap: 6px;
   margin-bottom: 4px;
+  max-height: 280px;
+  overflow-y: auto;
+  overflow-x: hidden;
+  overscroll-behavior: contain;
+  padding-right: 2px;
+}
+
+.popover-list::-webkit-scrollbar {
+  width: 4px;
+}
+
+.popover-list::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.popover-list::-webkit-scrollbar-thumb {
+  background: var(--border-strong);
+  border-radius: 999px;
+}
+
+.popover-list::-webkit-scrollbar-thumb:hover {
+  background: var(--fg-subtle);
 }
 
 .popover-list-item {
@@ -1471,7 +1493,7 @@ body[data-clips-route="recording-pill"] #root {
    content isn't flush with the panel edge. Must follow `.setup` so it wins
    over the shorthand padding above. */
 .setup.popover-view {
-  padding-bottom: 26px;
+  padding-bottom: 16px;
 }
 
 .setup h2 {

package/corpus/templates/clips/desktop/src-tauri/src/whisper_speech.rs

@@ -495,14 +495,22 @@ mod macos {
         let mut out = Vec::new();
         for segment in state.as_iter() {
             let text = segment.to_string();
-            if is_speech(&text) && segment.no_speech_probability() < MAX_NO_SPEECH_PROBABILITY {
-                // whisper timestamps are in centiseconds → ms.
-                out.push((
-                    segment.start_timestamp() * 10,
-                    segment.end_timestamp() * 10,
-                    text,
-                ));
+            if !is_speech(&text) || segment.no_speech_probability() >= MAX_NO_SPEECH_PROBABILITY {
+                continue;
+            }
+            // Low average token confidence means whisper was guessing —
+            // typically a mis-detected-language hallucination that reads
+            // fluently but scores poorly. Drop it.
+            let confidence = segment_confidence(&segment);
+            if confidence < MIN_AVG_TOKEN_PROBABILITY {
+                continue;
             }
+            // whisper timestamps are in centiseconds → ms.
+            out.push((
+                segment.start_timestamp() * 10,
+                segment.end_timestamp() * 10,
+                text,
+            ));
         }
         out
     }
@@ -530,6 +538,40 @@ mod macos {
     const VOICE_RMS_THRESHOLD: f32 = 0.006;
     /// A second, model-level gate for ambient/no-speech Whisper segments.
     const MAX_NO_SPEECH_PROBABILITY: f32 = 0.72;
+    /// Minimum average per-token probability for a segment to count as real
+    /// speech. On noisy/near-silent audio whisper mis-detects the language and
+    /// decodes fluent-looking gibberish in another language — but those tokens
+    /// are low-confidence under the hood. Dropping segments below this cutoff
+    /// removes that wrong-language garbage while keeping genuine multilingual
+    /// speech (which decodes with high confidence).
+    const MIN_AVG_TOKEN_PROBABILITY: f32 = 0.55;
+
+    /// Average the model's per-token probability across a segment. Returns 0.0
+    /// for an empty segment so it is treated as low-confidence. Special tokens
+    /// (timestamps, `[_BEG_]`, …) render as `[_…]` and are skipped so they
+    /// don't skew the average toward the text tokens we actually care about.
+    fn segment_confidence(segment: &whisper_rs::WhisperSegment<'_>) -> f32 {
+        let mut sum = 0.0f32;
+        let mut count = 0u32;
+        for i in 0..segment.n_tokens() {
+            let Some(token) = segment.get_token(i) else {
+                continue;
+            };
+            let is_special = token
+                .to_str_lossy()
+                .map(|t| t.starts_with("[_"))
+                .unwrap_or(false);
+            if is_special {
+                continue;
+            }
+            sum += token.token_probability();
+            count += 1;
+        }
+        if count == 0 {
+            return 0.0;
+        }
+        sum / count as f32
+    }
 
     fn partial_inference_due(
         emit_partials: bool,

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

@@ -6,7 +6,7 @@ import {
   getRequestOrgId,
 } from "@agent-native/core/server/request-context";
 import { and, desc, eq, sql } from "drizzle-orm";
-import type { H3Event } from "h3";
+import { HTTPError, type H3Event } from "h3";
 
 import { getDb, schema } from "../db/index.js";
 
@@ -120,7 +120,10 @@ export async function requireOrganizationAccess(
   const email = getCurrentOwnerEmail();
   const role = await getOrganizationRoleForEmail(resolvedOrganizationId, email);
   if (!role || !organizationRoleAllowed(role, allowedRoles)) {
-    throw new Error("Organization not found or access denied");
+    throw new HTTPError({
+      statusCode: 403,
+      statusMessage: "Organization not found or access denied",
+    });
   }
   return { organizationId: resolvedOrganizationId, email, role };
 }

package/dist/collab/struct-routes.d.ts

@@ -13,8 +13,8 @@
  * Body: { json: any, fieldName?: string, type?: "map"|"array", requestSource?: string }
  */
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/observability/routes.d.ts

@@ -62,7 +62,7 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;
 //# sourceMappingURL=routes.d.ts.map

package/dist/progress/routes.d.ts

@@ -15,7 +15,7 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;
 //# sourceMappingURL=routes.d.ts.map

package/dist/resources/handlers.d.ts

@@ -49,11 +49,11 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>;
 /** POST /_agent-native/resources/upload — upload a file as a resource */
 export declare function handleUploadResource(event: any): Promise<import("./store.js").Resource | {
@@ -74,10 +74,10 @@ export declare function handleUploadResource(event: any): Promise<import("./stor
     runId: string | null;
     expiresAt: number | null;
     metadata: string | null;
+    error?: undefined;
     url: string;
     provider: string;
     storageSetupRequired?: undefined;
-    error?: undefined;
 } | {
     error: string;
     storageSetupRequired: boolean;

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,11 +27,11 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
+    error?: undefined;
 }>>;
 export {};
 //# sourceMappingURL=agent-engine-api-key-route.d.ts.map

package/docs/content/locales/ar-SA/pure-agent-apps.mdx

@@ -68,9 +68,9 @@ Automation-first app هو Agent-Native app بلا متصفح من أجل schedul
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## أضف الدردشة لاحقاً {#add-chat-later}
+## أضف واجهة مستخدم لاحقاً {#add-chat-later}
 
-يختار `--headless` السقالة الأولية فقط، ولا يوجد أمر `agent-native` يحوّل مشروعاً قائماً بلا واجهة إلى تطبيق دردشة في مكانه. عندما يحتاج الأشخاص إلى محادثة في المتصفح، استخدم [قالب Chat](/docs/template-chat) كمرجع للترحيل: احتفظ بالـ actions وبيانات SQL والتعليمات والمهارات، ثم أضف shell المتصفح وserver plugins و`<AgentChatSurface>` وplugin للدردشة يحمّل actions الحالية. تحقّق من `pnpm typecheck` ومن محادثة تستدعي action قائمة. استخدم `agent-native add` لمخططات التكامل، لا لهذا التحويل.
+يختار `--headless` السقالة الأولية فقط، ولا يوجد أمر `agent-native` يحوّل مشروعاً قائماً بلا واجهة إلى تطبيق متصفح في مكانه. عندما يحتاج الأشخاص إلى واجهة مستخدم، استخدم [قالب Chat](/docs/template-chat) كمرجع للترحيل: احتفظ بالـ actions وبيانات SQL والتعليمات والمهارات، ثم أضف shell المتصفح وserver plugins. وإذا كانت الواجهة محادثة، أضف `<AgentChatSurface>` وplugin للدردشة يحمّل actions الحالية. تحقّق من `pnpm typecheck` ومن تدفق واجهة يستدعي action قائمة. استخدم `agent-native add` لمخططات التكامل، لا لهذا التحويل.
 
 ## ما هي الخطوة التالية
 

package/docs/content/locales/de-DE/pure-agent-apps.mdx

@@ -70,9 +70,9 @@ Die Box, das Gerüst, der Repo-Zugriff und die Lauffreigabe sind jetzt an einem
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## Chat später hinzufügen {#add-chat-later}
+## Später eine UI hinzufügen {#add-chat-later}
 
-`--headless` wählt nur das anfängliche Scaffold; es gibt keinen `agent-native`-Befehl, der ein bestehendes action-only-Projekt direkt in eine Chat-App umwandelt. Wenn Menschen eine Browser-Unterhaltung brauchen, nutze das [Chat-Template](/docs/template-chat) als Migrationsreferenz: Behalte Actions, SQL-Daten, Anweisungen und Skills bei und übernimm Browser-Shell, Server-Plugins, `<AgentChatSurface>` sowie ein Chat-Plugin, das die vorhandenen Actions lädt. Prüfe `pnpm typecheck` und einen Chat-Turn, der eine vorhandene Action aufruft. `agent-native add` ist für Integrations-Blaupausen gedacht, nicht für diese Umwandlung.
+`--headless` wählt nur das anfängliche Scaffold; es gibt keinen `agent-native`-Befehl, der ein bestehendes action-only-Projekt direkt in eine Browser-App umwandelt. Wenn Menschen eine UI brauchen, nutze das [Chat-Template](/docs/template-chat) als Migrationsreferenz: Behalte Actions, SQL-Daten, Anweisungen und Skills bei und übernimm Browser-Shell und Server-Plugins. Für eine Chat-Oberfläche kommen `<AgentChatSurface>` und ein Chat-Plugin hinzu, das die vorhandenen Actions lädt. Prüfe `pnpm typecheck` und einen UI-Ablauf, der eine vorhandene Action aufruft. `agent-native add` ist für Integrations-Blaupausen gedacht, nicht für diese Umwandlung.
 
 ## Was kommt als nächstes
 

package/docs/content/locales/es-ES/pure-agent-apps.mdx

@@ -70,9 +70,9 @@ la caja, el andamio, el acceso al repositorio y el uso compartido de ejecuciones
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## Añade chat más adelante {#add-chat-later}
+## Añade una UI más adelante {#add-chat-later}
 
-`--headless` solo elige el scaffold inicial; no hay un comando de `agent-native` que convierta en el sitio un proyecto existente solo de acciones en una app de chat. Cuando las personas necesiten una conversación en el navegador, usa la [plantilla Chat](/docs/template-chat) como referencia de migración: conserva las actions, los datos SQL, las instrucciones y las skills, y añade el shell del navegador, los plugins de servidor, `<AgentChatSurface>` y un plugin de chat que cargue las actions existentes. Comprueba `pnpm typecheck` y un turno de chat que llame una action existente. `agent-native add` es para planos de integración, no para esta conversión.
+`--headless` solo elige el scaffold inicial; no hay un comando de `agent-native` que convierta en el sitio un proyecto existente solo de acciones en una app de navegador. Cuando las personas necesiten una UI, usa la [plantilla Chat](/docs/template-chat) como referencia de migración: conserva las actions, los datos SQL, las instrucciones y las skills, y añade el shell del navegador y los plugins de servidor. Para una superficie de chat, añade `<AgentChatSurface>` y un plugin de chat que cargue las actions existentes. Comprueba `pnpm typecheck` y un flujo de UI que llame una action existente. `agent-native add` es para planos de integración, no para esta conversión.
 
 ## ¿Qué sigue?
 

package/docs/content/locales/fr-FR/pure-agent-apps.mdx

@@ -68,9 +68,9 @@ la boîte, l'échafaudage, l'accès au dépôt et le partage d'exécution se tro
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## Ajouter le chat plus tard {#add-chat-later}
+## Ajouter une UI plus tard {#add-chat-later}
 
-`--headless` choisit seulement le scaffold initial ; aucune commande `agent-native` ne convertit directement un projet existant fondé uniquement sur des actions en application de chat. Quand les personnes ont besoin d'une conversation dans le navigateur, utilisez le [modèle Chat](/docs/template-chat) comme référence de migration : conservez les actions, les données SQL, les instructions et les skills, puis ajoutez le shell navigateur, les plugins serveur, `<AgentChatSurface>` et un plugin de chat qui charge les actions existantes. Vérifiez `pnpm typecheck` et un tour de chat appelant une action existante. `agent-native add` sert aux blueprints d'intégration, pas à cette conversion.
+`--headless` choisit seulement le scaffold initial ; aucune commande `agent-native` ne convertit directement un projet existant fondé uniquement sur des actions en application navigateur. Quand les personnes ont besoin d'une UI, utilisez le [modèle Chat](/docs/template-chat) comme référence de migration : conservez les actions, les données SQL, les instructions et les skills, puis ajoutez le shell navigateur et les plugins serveur. Pour une surface de chat, ajoutez `<AgentChatSurface>` et un plugin de chat qui charge les actions existantes. Vérifiez `pnpm typecheck` et un flux UI appelant une action existante. `agent-native add` sert aux blueprints d'intégration, pas à cette conversion.
 
 ## Quelle est la prochaine étape
 

package/docs/content/locales/hi-IN/pure-agent-apps.mdx

@@ -68,9 +68,9 @@ Automation-first app scheduled jobs, queues, scripts, integration workers और
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## बाद में chat जोड़ें {#add-chat-later}
+## बाद में UI जोड़ें {#add-chat-later}
 
-`--headless` केवल शुरुआती scaffold चुनता है; कोई `agent-native` command किसी मौजूदा action-only project को in-place chat app में नहीं बदलती। जब लोगों को browser conversation चाहिए, [Chat template](/docs/template-chat) को migration reference की तरह उपयोग करें: actions, SQL data, instructions और skills रखें, फिर browser shell, server plugins, `<AgentChatSurface>` और मौजूदा actions लोड करने वाला chat plugin जोड़ें। `pnpm typecheck` और एक ऐसा chat turn जाँचें जो किसी मौजूदा action को call करे। `agent-native add` integration blueprints के लिए है, इस conversion के लिए नहीं।
+`--headless` केवल शुरुआती scaffold चुनता है; कोई `agent-native` command किसी मौजूदा action-only project को in-place browser app में नहीं बदलती। जब लोगों को UI चाहिए, [Chat template](/docs/template-chat) को migration reference की तरह उपयोग करें: actions, SQL data, instructions और skills रखें, फिर browser shell और server plugins जोड़ें। Chat surface के लिए `<AgentChatSurface>` और मौजूदा actions लोड करने वाला chat plugin भी जोड़ें। `pnpm typecheck` और एक ऐसा UI flow जाँचें जो किसी मौजूदा action को call करे। `agent-native add` integration blueprints के लिए है, इस conversion के लिए नहीं।
 
 ## आगे क्या है
 

package/docs/content/locales/ja-JP/pure-agent-apps.mdx

@@ -68,9 +68,9 @@ Automation-first app は、scheduled jobs、queues、scripts、integration worke
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## 後からチャットを追加する {#add-chat-later}
+## 後から UI を追加する {#add-chat-later}
 
-`--headless` が選ぶのは初期 scaffold だけで、既存の action-only プロジェクトをその場で Chat アプリに変換する `agent-native` コマンドはありません。ブラウザーでの会話が必要になったら、移行の参照として [Chat template](/docs/template-chat) を使います。actions、SQL データ、instructions、skills は保持し、browser shell、server plugins、`<AgentChatSurface>`、既存 actions を読み込む chat plugin を追加してください。`pnpm typecheck` と既存 action を呼ぶ chat turn を確認します。`agent-native add` は integration blueprints 用であり、この変換用ではありません。
+`--headless` が選ぶのは初期 scaffold だけで、既存の action-only プロジェクトをその場でブラウザーアプリに変換する `agent-native` コマンドはありません。UI が必要になったら、移行の参照として [Chat template](/docs/template-chat) を使います。actions、SQL データ、instructions、skills は保持し、browser shell と server plugins を追加してください。チャット surface には `<AgentChatSurface>` と既存 actions を読み込む chat plugin も追加します。`pnpm typecheck` と既存 action を呼ぶ UI フローを確認します。`agent-native add` は integration blueprints 用であり、この変換用ではありません。
 
 ## 次は何ですか
 

package/docs/content/locales/ko-KR/pure-agent-apps.mdx

@@ -66,9 +66,9 @@ Automation-first app은 scheduled jobs, queues, scripts, integration workers, ex
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## 나중에 채팅 추가하기 {#add-chat-later}
+## 나중에 UI 추가하기 {#add-chat-later}
 
-`--headless`는 초기 scaffold만 선택하며, 기존 action-only 프로젝트를 제자리에서 Chat 앱으로 변환하는 `agent-native` 명령은 없습니다. 브라우저 대화가 필요해지면 [Chat 템플릿](/docs/template-chat)을 마이그레이션 기준으로 사용하세요. actions, SQL 데이터, instructions, skills를 유지하고 browser shell, server plugins, `<AgentChatSurface>`, 기존 actions를 로드하는 chat plugin을 추가합니다. `pnpm typecheck`와 기존 action을 호출하는 chat turn을 확인하세요. `agent-native add`는 이 변환이 아니라 integration blueprints용입니다.
+`--headless`는 초기 scaffold만 선택하며, 기존 action-only 프로젝트를 제자리에서 브라우저 앱으로 변환하는 `agent-native` 명령은 없습니다. UI가 필요해지면 [Chat 템플릿](/docs/template-chat)을 마이그레이션 기준으로 사용하세요. actions, SQL 데이터, instructions, skills를 유지하고 browser shell과 server plugins를 추가합니다. Chat surface에는 `<AgentChatSurface>`와 기존 actions를 로드하는 chat plugin도 추가합니다. `pnpm typecheck`와 기존 action을 호출하는 UI flow를 확인하세요. `agent-native add`는 이 변환이 아니라 integration blueprints용입니다.
 
 ## 다음 단계
 

package/docs/content/locales/pt-BR/pure-agent-apps.mdx

@@ -68,9 +68,9 @@ a caixa, o scaffold, o acesso ao repositório e o compartilhamento de execução
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## Adicione chat depois {#add-chat-later}
+## Adicione uma UI depois {#add-chat-later}
 
-`--headless` escolhe somente o scaffold inicial; não há um comando `agent-native` que converta no lugar um projeto existente apenas com actions em um app de chat. Quando as pessoas precisarem de uma conversa no navegador, use o [template Chat](/docs/template-chat) como referência de migração: mantenha as actions, os dados SQL, as instructions e as skills e adicione o shell do navegador, os server plugins, `<AgentChatSurface>` e um chat plugin que carregue as actions existentes. Verifique `pnpm typecheck` e um turno de chat que chame uma action existente. `agent-native add` é para integration blueprints, não para essa conversão.
+`--headless` escolhe somente o scaffold inicial; não há um comando `agent-native` que converta no lugar um projeto existente apenas com actions em um app de navegador. Quando as pessoas precisarem de uma UI, use o [template Chat](/docs/template-chat) como referência de migração: mantenha as actions, os dados SQL, as instructions e as skills e adicione o shell do navegador e os server plugins. Para uma superfície de chat, adicione `<AgentChatSurface>` e um chat plugin que carregue as actions existentes. Verifique `pnpm typecheck` e um fluxo de UI que chame uma action existente. `agent-native add` é para integration blueprints, não para essa conversão.
 
 ## O que vem a seguir
 

package/docs/content/locales/zh-CN/pure-agent-apps.mdx

@@ -66,9 +66,9 @@ Automation-first app 是无浏览器的 Agent-Native app，用于 scheduled jobs
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## 稍后添加聊天 {#add-chat-later}
+## 稍后添加 UI {#add-chat-later}
 
-`--headless` 只选择初始 scaffold；没有可将现有仅 actions 项目原地转换为聊天应用的 `agent-native` 命令。当用户需要浏览器对话时，请将 [Chat 模板](/docs/template-chat) 用作迁移参考：保留 actions、SQL 数据、instructions 和 skills，并添加浏览器 shell、server plugins、`<AgentChatSurface>` 以及加载现有 actions 的 chat plugin。验证 `pnpm typecheck`，并完成一次调用现有 action 的聊天。`agent-native add` 用于 integration blueprints，不用于此转换。
+`--headless` 只选择初始 scaffold；没有可将现有仅 actions 项目原地转换为浏览器应用的 `agent-native` 命令。当用户需要 UI 时，请将 [Chat 模板](/docs/template-chat) 用作迁移参考：保留 actions、SQL 数据、instructions 和 skills，并添加浏览器 shell 和 server plugins。对于聊天界面，再添加 `<AgentChatSurface>` 以及加载现有 actions 的 chat plugin。验证 `pnpm typecheck`，并完成一次调用现有 action 的 UI 流程。`agent-native add` 用于 integration blueprints，不用于此转换。
 
 ## 下一步是什么
 

package/docs/content/locales/zh-TW/pure-agent-apps.mdx

@@ -66,9 +66,9 @@ Automation-first app 是無瀏覽器的 Agent-Native app，用於 scheduled jobs
 
 → [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
 
-## 稍後新增聊天 {#add-chat-later}
+## 稍後新增 UI {#add-chat-later}
 
-`--headless` 只會選擇初始 scaffold；沒有可將現有僅 actions 專案原地轉換為聊天應用程式的 `agent-native` 命令。當使用者需要瀏覽器對話時，請將 [Chat 範本](/docs/template-chat) 作為遷移參考：保留 actions、SQL 資料、instructions 和 skills，並新增瀏覽器 shell、server plugins、`<AgentChatSurface>` 與載入現有 actions 的 chat plugin。請驗證 `pnpm typecheck`，並完成一次呼叫現有 action 的聊天。`agent-native add` 用於 integration blueprints，不用於此轉換。
+`--headless` 只會選擇初始 scaffold；沒有可將現有僅 actions 專案原地轉換為瀏覽器應用程式的 `agent-native` 命令。當使用者需要 UI 時，請將 [Chat 範本](/docs/template-chat) 作為遷移參考：保留 actions、SQL 資料、instructions 和 skills，並新增瀏覽器 shell 與 server plugins。對於聊天介面，再新增 `<AgentChatSurface>` 與載入現有 actions 的 chat plugin。請驗證 `pnpm typecheck`，並完成一次呼叫現有 action 的 UI 流程。`agent-native add` 用於 integration blueprints，不用於此轉換。
 
 ## 下一步是什麼
 

package/docs/content/pure-agent-apps.mdx

@@ -95,22 +95,66 @@ The `--headless` flag only chooses the initial scaffold. It does not choose a
 different architecture. You can later move the same `actions/`, instructions,
 skills, and SQL state into a chat app or full application surface.
 
-## Add chat later {#add-chat-later}
+## Add a UI later {#add-chat-later}
 
 `--headless` is not a permanent runtime mode, and there is no `agent-native`
-command that converts an existing action-only project into a chat app in place.
-When people need a browser conversation surface, use the [Chat template](/docs/template-chat)
-as the migration reference and keep the durable action and database contract:
-
-1. Scaffold a temporary Chat app with the framework version you are migrating
-   to: `npx @agent-native/core@latest create my-chat-reference --template chat`.
-2. Bring its browser shell, server plugins, and UI dependencies into the
-   existing project. In particular, add the full-page `<AgentChatSurface>` and
-   an `agent-chat` plugin that loads the existing action registry.
-3. Keep your action names, Zod schemas, SQL data, instructions, and skills.
-   Chat calls those same actions; it does not replace them.
-4. Verify both surfaces: run `pnpm typecheck`, start the browser app with
-   `pnpm dev`, then complete one chat turn that calls an existing action.
+command that converts an existing action-only project into a browser app in
+place. When people need a UI, use the [Chat template](/docs/template-chat) as
+the migration reference and keep the durable action and database contract:
+
+<Diagram id="doc-block-ui-later" title="One contract, multiple surfaces" summary={"Start with a headless workflow, then add a browser UI without rewriting the actions, data, instructions, or skills underneath."}>
+
+```html
+<div class="diagram-ui-path">
+  <div class="diagram-panel" data-rough>
+    <span class="diagram-pill accent">Start headless</span
+    ><small class="diagram-muted">jobs · CLI · external agents</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel" data-rough>
+    <span class="diagram-pill">Add a UI</span
+    ><small class="diagram-muted">chat · routes · durable pages</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel ok" data-rough>
+    <span class="diagram-pill ok">Keep the contract</span
+    ><small class="diagram-muted">actions · SQL · instructions · skills</small>
+  </div>
+</div>
+```
+
+```css
+.diagram-ui-path {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 14px;
+  flex-wrap: wrap;
+}
+.diagram-ui-path .diagram-panel {
+  display: flex;
+  min-width: 150px;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+  text-align: center;
+}
+.diagram-ui-path .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+1. Scaffold the first workflow with `npx @agent-native/core@latest create my-agent --headless`.
+2. When a browser surface becomes useful, bring in the template's shell, server
+   plugins, and UI dependencies. For chat, that includes `<AgentChatSurface>`
+   and an `agent-chat` plugin that loads the existing action registry.
+3. Keep your action names, Zod schemas, SQL data, instructions, and skills. A
+   UI calls those same actions; it does not replace them.
+4. Verify both surfaces with `pnpm typecheck`, `pnpm dev`, and one UI flow that
+   calls an existing action.
 
 Use `agent-native add` for integration blueprints, not for this conversion.
 Choose chat when people need conversational steering, approvals, or durable

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.101.5",
+  "version": "0.101.6",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -335,8 +335,8 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
-    "@agent-native/toolkit": "^0.4.10",
-    "@agent-native/recap-cli": "0.4.0"
+    "@agent-native/recap-cli": "0.4.0",
+    "@agent-native/toolkit": "^0.4.10"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",