@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ja-JP/faq.md

@@ -0,0 +1,142 @@
+---
+title: "FAQ"
+description: "エージェント ネイティブについてよくある質問 — エージェント ネイティブとは何なのか、誰向けなのか、何を構築できるのか、どのように機能するのかなどです。"
+---
+
+# FAQ
+
+エージェント ネイティブに関するよくある質問を、「探しているだけです」から「現在認証を接続しているところです」までまとめました。
+
+## 基本 {#general}
+
+### エージェントネイティブとは何ですか? {#what-is-agent-native}
+
+エージェントネイティブは、AI エージェントとその周囲の製品表面が対等なパートナーとなるアプリを構築するためのフレームワークです。そのサーフェスは、1 つのカスタム アクションを備えたヘッドレス エージェントとして開始し、リッチ チャットに成長したり、完全な UI になることができます。不変条件は、エージェントと人間が同じ actions、データベース、状態を共有することです。完全な説明については、[What Is Agent-Native?](/docs/what-is-agent-native) を参照してください。
+
+### これは誰のためのものですか? {#who-is-this-for}
+
+エージェント ネイティブは、実際のアプリと AI エージェントが同じデータと actions から動作することを望む人向けです。一般的なパスは次のとおりです。
+
+- メール、カレンダー、フォーム、プラン、または設定なしで完成した別のテンプレートが必要な場合は、**ホストされたアプリを使用します**。[template gallery](/templates) から始めてください。
+- ユーザーがすぐに会話できる基本的なアプリが必要な場合は、**チャットから始めます**。次に、actions と画面で拡張します。[Getting Started](/docs/getting-started) または [Chat](/docs/template-chat) から始めます。
+- **プリミティブファーストで開始** UI にコミットする前に 1 つのアクションとヘッドレスアプリエージェントループが必要な場合は、[Getting Started](/docs/getting-started) から開始します。
+- 認証、データベース、UI、エージェント actions がすでに接続されている独自の SaaS 製品が必要な場合は、**テンプレートをフォークしてカスタマイズします**。[Templates](/docs/cloneable-saas) を参照してください。
+- **最初から構築** 新しいエージェント駆動製品のフレームワーク プリミティブが必要な場合は、[Getting Started](/docs/getting-started) から始めます。
+- **別のエージェントまたはコード ツールを接続します** Claude、ChatGPT、Codex、カーソル、または GitHub Copilot / VS Code でエージェント ネイティブ アプリを使用する場合は、「[External Agents](/docs/external-agents) および [Skills Guide](/docs/skills-guide)」を参照してください。
+
+### これは、既存のアプリに AI を追加することとどう違うのですか? {#how-is-this-different}
+
+ほとんどのアプリは後付けで AI を追加していますが、実際にアプリ内で何かを行うことはできません。エージェント ネイティブ アプリでは、エージェントは UI と同じ actions、データベース、状態を共有する第一級市民であるため、ボタンで実行できることはすべて実行でき、アプリ自体のコードを変更することもできます。 [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder) を参照してください。
+
+```an-diagram title="Bolted-on AI vs. agent-native" summary="A bolted-on chat sidebar lives in its own world. An agent-native agent shares the same actions, database, and state as the UI."
+{
+  "html": "<div class=\"diagram-vs\"><div class=\"diagram-col\"><span class=\"diagram-pill warn\">Bolted-on AI</span><div class=\"diagram-node\">Chat sidebar</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>separate AI world<br><small class=\"diagram-muted\">can't touch the app</small></div><div class=\"diagram-box diagram-muted\">App UI &amp; data</div></div><div class=\"diagram-divider\" aria-hidden=\"true\"></div><div class=\"diagram-col\"><span class=\"diagram-pill ok\">Agent-native</span><div class=\"diagram-row2\"><div class=\"diagram-node\">UI</div><div class=\"diagram-node\">Agent</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>shared actions, DB &amp; state</div></div></div>",
+  "css": ".diagram-vs{display:flex;align-items:stretch;gap:18px;flex-wrap:wrap}.diagram-vs .diagram-col{display:flex;flex-direction:column;gap:8px;align-items:center;flex:1;min-width:200px}.diagram-vs .diagram-row2{display:flex;gap:8px}.diagram-vs .diagram-arrow{font-size:20px;line-height:1}.diagram-vs .diagram-divider{width:1px;align-self:stretch;background:currentColor;opacity:.15}"
+}
+```
+
+### オープンソースですか? {#is-this-open-source}
+
+はい。フレームワークとすべてのテンプレートはオープンソースです。すべてをローカルで実行したり、セルフホストしたり、管理されたホスティング、コラボレーション、チーム機能のために Builder.io のクラウドを使用したりできます。
+
+### 料金はいくらですか? {#how-much}
+
+フレームワーク自体は無料です。実際に発生する 2 つのコスト:
+
+- **AI の使用法。** 独自の API キー (Anthropic、OpenAI など) を持参し、モデル プロバイダーに直接支払います。弊社からの値上げはありません。
+- **ホスティング** ホストの料金に応じて。ほとんどのテンプレートは、小規模なワークロードの無料枠 (Netlify、Vercel、Cloudflare) で問題なく動作します。
+
+これらを一切管理したくない場合は、`agent-native.com` のホスト バージョン (Builder.io によって運営) で、推論とホスティングがシートごとのプランにバンドルされています。
+
+### これを自分でホストできますか? {#can-i-self-host}
+
+はい。ノードを実行する任意のホスト (Netlify、Vercel、Cloudflare、AWS、Deno Deploy、独自のサーバー)、および任意の SQL データベース (Postgres、SQLite、Turso、D1) を選択します。フレームワークは移植できるように構築されています。 [Deployment](/docs/deployment) を参照してください。
+
+### どの AI モデルをサポートしていますか? {#what-models}
+
+Anthropic Claude、OpenAI (GPT-5 ファミリー)、Google Gemini、および OpenAI API シェイプを話すプロバイダー (Ollama 経由のローカル モデルを含む)。モデルは設定で構成します。切り替えは構成の変更であり、コードの書き換えではありません。フレームワークの最も重いテスト済みパスは Claude であるため、これがデフォルトの推奨事項です。
+
+### AI/ML について知る必要がありますか? {#do-i-need-to-know-ai}
+
+いいえ。モデルをトレーニングしたり、微調整したり、埋め込みを処理したりすることはありません。通常の Web アプリを構築しますが、ホストされたバージョンでは、ほとんど何も構築しません。フレームワークは、メッセージのルーティング、actions の実行、状態の同期など、エージェントの統合を処理します。
+
+### 既存のアプリをエージェントネイティブに移行できますか? {#can-i-use-existing-code}
+
+可能ですが、エージェントネイティブは最初から構築した場合に最適に機能します。アーキテクチャ (共有データベース、ポーリング同期、actions、アプリケーションの状態) は、全体にわたって統合される必要があります。テンプレートから開始してカスタマイズすることをお勧めします。これは、デスクトップ ファーストからモバイル ファーストへの移行のようなものだと考えてください。改造することはできますが、ネイティブに構築する方が優れています。
+
+## テンプレートと作成できるもの {#templates}
+
+### どのようなテンプレートが利用可能ですか? {#what-templates-are-available}
+
+このフレームワークには、[Chat](/docs/template-chat)、[Mail](/docs/template-mail)、[Calendar](/docs/template-calendar)、[Forms](/docs/template-forms)、[Plan](/docs/template-plan) (ビジュアル プランと PR の要約)、[Analytics](/docs/template-analytics)、[Dispatch](/docs/template-dispatch) などの本番環境に対応したテンプレートが付属しています。それぞれは、UI、エージェント actions、データベース スキーマ、AI 命令を備えた完全なアプリで、すぐに使用できます。完全なカタログについては、[Templates](/docs/cloneable-saas) を参照してください。
+
+### テンプレートをカスタマイズできますか? {#can-i-customize-templates}
+
+それが要点です。テンプレートをフォークし、エージェントに依頼してカスタマイズします。 「フォームに優先度フィールドを追加します。」 「Salesforce インスタンスに接続します。」 「当社のブランドに合わせて配色を変更してください。」エージェントがコードを変更すると、アプリは時間の経過とともに進化します。
+
+### テンプレートでカバーされていないものを構築できますか? {#build-from-scratch}
+
+はい。基本的なチャット アプリが必要な場合は、`npx @agent-native/core@latest create my-chat-app --template chat` を実行します。耐久性のあるチャット スレッド、actions、認証、SQL に基づくランタイム状態、および独自の画面を追加する余地が得られます。 UI を持たない最小のアクション優先アプリが必要な場合は、`npx @agent-native/core@latest create my-agent --headless` を実行します。 [Getting Started](/docs/getting-started)、[Pure-Agent Apps](/docs/pure-agent-apps)、および [Chat](/docs/template-chat) を参照してください。
+
+### テンプレートをフォークせずに試してみることはできますか? {#try-with-a-skill}
+
+はい — 1 つのコマンドですでに使用しているコーディング エージェントにスキルをインストールします。スキャフォールドは必要ありません。チュートリアルについては、[Skills Guide](/docs/skills-guide#app-backed-skills) を参照してください。
+
+## エージェントの機能 {#agent-capabilities}
+
+### エージェントは本当にアプリ自身のコードを変更できますか? {#can-the-agent-modify-code}
+
+はい、それは機能です。エージェントはコンポーネント、ルート、スタイル、actions を安全に編集できます。 「コホート分析グラフの追加」を依頼すると、エージェントがそれを作成します。 「Stripe アカウントに接続してください」と要求すると、エージェントが統合を作成します。すべては通常の Git 追跡コードであるため、不適切な変更は簡単に元に戻すことができます。
+
+### ユーザーはアプリの外部からエージェントと会話できますか? {#external-channels}
+
+はい。同じエージェントが、Web UI、Slack、Telegram、電子メール、および他のエージェント ([A2A](/docs/a2a-protocol) 経由) で実行されます。それは同じメモリと同じ actions を持つ同じエージェントであり、異なるチャネルを通じて到達しただけです。 [Messaging the agent](/docs/messaging) を参照してください。
+
+### エージェント同士は会話できますか? {#can-agents-talk-to-each-other}
+
+はい、[A2A (Agent-to-Agent) protocol](/docs/a2a-protocol) 経由です。すべてのエージェント ネイティブ アプリは、自動的に A2A エンドポイントを取得します。メール アプリから、分析エージェントにタグを付けてデータをクエリできます。エージェントは、利用可能な他のエージェントを検出し、プロトコル経由でそれらを呼び出し、UI に結果を表示します。設定は必要ありません。エージェント カードはテンプレートの actions から自動生成されます。
+
+### エージェントはアプリで何を確認できますか? {#what-can-the-agent-see}
+
+エージェントは、ユーザーが現在何を表示しているかを常に把握しています。 UI は、ルートが変更されるたびに、どのビューが開いているか、どの項目が選択されているかなど、ナビゲーション状態をデータベースに書き込みます。エージェントはアクションを実行する前にこれを読みます。電子メールが開封されている場合、エージェントはどの電子メールを認識しているかがわかります。スライドが選択されている場合、エージェントはどのスライドであるかを認識します。 [Context Awareness](/docs/context-awareness) を参照してください。
+
+## 開発に関する質問 {#development}
+
+### エージェント ネイティブで動作する AI コーディング ツールはどれですか? {#which-ai-tools-work}
+
+プロジェクトの指示を読み取る AI コーディング ツール。このフレームワークは、汎用標準として AGENTS.md を使用し、特定のツールのシンボリックリンクを自動作成します。
+
+- **Claude コード** — CLAUDE.md を読み取ります (CLI セットアップによって AGENTS.md からシンボリックリンクされます)
+- **Cursor** — AGENTS.md を直接読み取るか、プロジェクト内に存在する場合は `.cursorrules` (カーソルの従来の場所) を読み取ります
+- **Windsurf** — .windsurfrules を読み取ります (CLI セットアップによって AGENTS.md からシンボリックリンクされます)
+- **Codex、Gemini、その他** — 埋め込みエージェント パネルを介して動作します
+- **Builder.io** — ビジュアル編集とコラボレーションを備えたクラウドホスト型エージェント
+
+### 独自のデータベースを使用できますか? {#can-i-use-my-own-database}
+
+はい。 `DATABASE_URL` を設定すると、フレームワークがそれを自動検出します。サポートされているデータベースには、SQLite、Postgres (Neon、Supabase、plain)、Turso (libSQL)、Cloudflare D1 が含まれます。すべての SQL は、Drizzle ORM を介して方言に依存しません。同じコードがどこでも機能します。
+
+### どこに導入できますか? {#where-can-i-deploy}
+
+どこでも。サーバーは Nitro 上で実行され、任意のデプロイメント ターゲット (Node.js、Cloudflare Workers/Pages、Netlify、Vercel、Deno Deploy、AWS Lambda、および Bun) にコンパイルされます。管理された展開に Builder.io のホスティングを使用することもできます。 [Deployment guide](/docs/deployment) を参照してください。
+
+## アーキテクチャ {#architecture}
+
+### なぜ WebSocket ではなく SSE とポーリングを使用するのですか? {#why-polling-not-websockets}
+
+SSE は、同一プロセス書き込みでブラウザへの即時パスを提供し、軽量のバージョン カウンター ポーリングはフォールバックのままです。これは、永続的なソケットが利用できない可能性があるサーバーレスやエッジを含むすべてのデプロイメント環境で動作するためです。 [Key Concepts — Live sync](/docs/key-concepts#polling-sync) を参照してください。
+
+```an-diagram title="SSE first, polling fallback" summary="Same-process writes stream instantly; a version-counter poll keeps serverless, edge, and cross-process writes convergent."
+{
+  "html": "<div class=\"diagram-transport\"><div class=\"diagram-box\" data-rough>DB write</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-node\">SSE<br><small class=\"diagram-muted\">/_agent-native/events &middot; instant</small></div><div class=\"diagram-node\">Poll<br><small class=\"diagram-muted\">/_agent-native/poll &middot; universal fallback</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Browser refetch</div></div>",
+  "css": ".diagram-transport{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-transport .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-transport .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+### UI が LLM を直接呼び出せないのはなぜですか? {#why-no-inline-llm-calls}
+
+AI は非決定的であるため、ワンショット ボタンではなく、フィードバックを提供して反復するための会話フローが必要です。エージェントは、コードベース、指示、skills、インライン コールにはない履歴をすでに持っています。すべてをエージェント経由でルーティングすることで、Slack、Telegram、または別のエージェントからアプリを駆動できるようになります。 [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge) を参照してください。
+
+### これがライブラリではなくフレームワークであるのはなぜですか? {#why-framework-not-library}
+
+共有データベース、ライブ同期、actions システム、およびアプリケーションの状態は、それらが根本から接続されているためにのみ機能します。UI はエージェントの変更に即座に反応し、エージェントは通信し、エージェントはユーザーが見ているものを理解します。図書館はあなたに作品を提供します。これは建築です。 [Key Concepts](/docs/key-concepts) を参照してください。

package/docs/content/locales/ja-JP/file-uploads.md

@@ -0,0 +1,122 @@
+---
+title: "ファイルのアップロード"
+description: "ファイル アップロード ストレージを構成します — 開発用の SQL フォールバック、本番用の Builder.io またはカスタム プロバイダー。"
+---
+
+# ファイルのアップロード
+
+このフレームワークは、構成可能なプロバイダーを通じてアップロードをルーティングするファイル アップロードの抽象化を提供します。テンプレートは `uploadFile()` を呼び出し、URL を返します。ストレージ バックエンドはアプリケーション コードを変更せずに交換可能です。
+
+## 仕組み {#how-it-works}
+
+アップロード リクエストは `POST /_agent-native/file-upload` に送信され、アクティブなプロバイダーにディスパッチされます。どのプロバイダーが設定されているかは、`GET /_agent-native/file-upload/status` で確認できます。
+
+プロバイダーの解決順序は次のとおりです:
+
+1. **ユーザー登録プロバイダー** — `registerFileUploadProvider()` 経由で登録されたカスタムプロバイダー
+2. **Builder.io プロバイダー** — 組み込み、Builder.io が接続されると自動的にアクティブ化されます
+3. **SQL フォールバック** — ファイルをデータベースに Base64 として保存します (開発には問題ありませんが、運用には問題ありません)
+
+```an-diagram title="Provider resolution order" summary="uploadFile() picks the first configured provider in order. The SQL fallback always exists so uploads work with zero setup."
+{
+  "html": "<div class=\"diagram-upload\"><div class=\"diagram-box\" data-rough>uploadFile()<br><small class=\"diagram-muted\">POST /_agent-native/file-upload</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-step\"><span class=\"diagram-pill accent\">1</span><div class=\"diagram-node\">User-registered<br><small class=\"diagram-muted\">registerFileUploadProvider() — S3, R2, GCS…</small></div></div><div class=\"diagram-step\"><span class=\"diagram-pill\">2</span><div class=\"diagram-node\">Builder.io<br><small class=\"diagram-muted\">auto when connected — CDN-served</small></div></div><div class=\"diagram-step\"><span class=\"diagram-pill warn\">3</span><div class=\"diagram-node\">SQL fallback<br><small class=\"diagram-muted\">base64 in DB — dev only</small></div></div></div></div>",
+  "css": ".diagram-upload{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-upload .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-upload .diagram-step{display:flex;align-items:center;gap:8px}.diagram-upload .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```an-api title="The upload endpoint" method="POST" path="/_agent-native/file-upload"
+{
+  "method": "POST",
+  "path": "/_agent-native/file-upload",
+  "summary": "Upload a file through the active provider and get back a public URL.",
+  "description": "Dispatches to the first configured provider in resolution order. Check the active provider at `GET /_agent-native/file-upload/status`.",
+  "request": { "contentType": "multipart/form-data" },
+  "responses": [
+    { "status": "200", "description": "{ url, id?, provider } — the public URL and which provider handled it." }
+  ]
+}
+```
+
+## デフォルト: SQL フォールバック {#sql-fallback}
+
+プロバイダーが構成されていない場合、ファイルはリソース システムを介して SQL データベースに Base64 データとして保存されます。これは、ローカル開発ではそのまま使用できますが、運用環境では推奨されません。ファイルが大きいとデータベースが肥大化し、CDN がありません。
+
+フォールバックが使用されると、1 回限りの警告がログに記録されます。
+
+## Builder.io ホスティング {#builder-hosting}
+
+アプリが Builder.io に接続されている場合、ファイルのアップロードは Builder のアセット ホスティングに自動的にルーティングされます。ファイルは、構成を必要とせずに CDN から提供されます。これは推奨される運用環境設定です。
+
+## カスタムプロバイダー {#custom-providers}
+
+任意のストレージ バックエンド (S3、Cloudflare R2、GCS など) を使用するには、サーバー プラグインにカスタム プロバイダーを登録します。
+
+```ts
+// server/plugins/file-upload.ts
+import { registerFileUploadProvider } from "@agent-native/core/file-upload";
+
+export default defineNitroPlugin(() => {
+  registerFileUploadProvider({
+    id: "s3",
+    name: "Amazon S3",
+    isConfigured: () => !!process.env.S3_BUCKET,
+    upload: async ({ data, filename, mimeType }) => {
+      const key = `uploads/${Date.now()}-${filename}`;
+      await s3Client.putObject({
+        Bucket: process.env.S3_BUCKET!,
+        Key: key,
+        Body: data,
+        ContentType: mimeType,
+      });
+      return {
+        url: `https://${process.env.S3_BUCKET}.s3.amazonaws.com/${key}`,
+        provider: "s3",
+      };
+    },
+  });
+});
+```
+
+## API をアップロード {#upload-api}
+
+`FileUploadProvider` インターフェイス:
+
+```ts
+interface FileUploadProvider {
+  id: string; // Unique id, e.g. "s3"
+  name: string; // Human-readable name
+  isConfigured: () => boolean; // True when ready (env vars set, etc.)
+  upload: (input: FileUploadInput) => Promise<FileUploadResult>;
+}
+
+interface FileUploadInput {
+  data: Uint8Array | Buffer; // File contents
+  filename?: string; // Original filename
+  mimeType?: string; // MIME type, e.g. "image/png"
+  ownerEmail?: string; // For per-user scoping in fallback
+}
+
+interface FileUploadResult {
+  url: string; // Public URL for the uploaded file
+  id?: string; // Provider-specific id
+  provider: string; // Which provider handled it
+}
+```
+
+actions またはサーバー コードで `@agent-native/core/file-upload` の `uploadFile()` を使用します。
+
+```ts
+import { uploadFile } from "@agent-native/core/file-upload";
+
+const result = await uploadFile({
+  data: fileBuffer,
+  filename: "photo.jpg",
+  mimeType: "image/jpeg",
+});
+
+if (result) {
+  // Provider handled it — result.url is the public URL
+} else {
+  // No provider configured — handle SQL fallback yourself, or skip
+}
+```

package/docs/content/locales/ja-JP/frames.md

@@ -0,0 +1,153 @@
+---
+title: "フレーム"
+description: "ローカル開発フレーム、埋め込みエージェント パネル、クラウド フレーム - AI エージェントがアプリと一緒に実行される方法。"
+---
+
+# フレーム
+
+すべてのエージェント ネイティブ アプリは、アプリ UI の隣に AI エージェントを使用して実行されます。 **フレーム**は
+両方をホストするラッパー: アプリを表示し、エージェントに場所を提供します
+チャット、実行、および (開発内で) コードの編集。 3 つのフレームがあり、1 つのランタイムを共有します。
+
+- **埋め込みエージェント パネル** — `@agent-native/core` のすべてのアプリ内に同梱されています。
+  これは、開発中および運用中にアプリ自体がレンダリングするサイドバーです。
+- **ローカル開発フレーム** — 実行中のアプリを iframe にロードする薄いラッパー
+  同じエージェント パネルとその横に統合された CLI 端末を追加します。中古
+  このリポジトリ内のテンプレートのローカル開発用。
+- **Builder.io クラウド フレーム** — コラボレーションを備えた管理されたホスト型フレーム
+  視覚的な編集と並列エージェントの実行。
+
+アプリのコードは、どのフレームがホストするかに関係なく同一です。エージェントが話す
+どの場合でも同じ actions とアプリケーションの状態を介してアプリに送信されます。
+
+```an-diagram title="Three frames, one runtime" summary="Your app and the agent panel are the same in every frame; only the wrapper around them changes."
+{
+  "html": "<div class=\"diagram-frames\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">Embedded panel</span><small class=\"diagram-muted\">ships in every app · dev + prod</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Local dev frame</span><small class=\"diagram-muted\">app in an iframe + panel + CLI terminal</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Builder.io cloud frame</span><small class=\"diagram-muted\">hosted: collaboration · visual edit · parallel runs</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>Same runtime<br><small class=\"diagram-muted\">your app · actions · application state</small></div></div>",
+  "css": ".diagram-frames{display:flex;flex-direction:column;gap:10px;align-items:stretch}.diagram-frames .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.diagram-frames .diagram-arrow{font-size:22px;line-height:1;align-self:center}"
+}
+```
+
+## 埋め込みエージェント パネル {#embedded-agent}
+
+埋め込みパネルは、アプリがレンダリングするエージェント サイドバーです。
+`@agent-native/core` — インストールする個別のパッケージはありません — 同一です
+開発および本番環境のコンポーネント。
+
+- `@agent-native/core/client` から `AgentPanel` としてエクスポートされ、
+  製品版のみのバリアント `ProductionAgentPanel`。
+- 完全なチャット / CLI / ワークスペース サーフェスを提供するため、エージェントの入力はオンのままです
+  フレームワーク内の他の場所で使用される共有コンポーザ スタック。
+- 毎ターン `application_state.navigation` を読み取るので、どれであるかはすでにわかっています
+  現在の状況と何が選択されているかを確認します。「これ」について改めて説明する必要はありません。
+
+### アプリ vs コード ツール モード {#tool-modes}
+
+パネルは 2 つのツール モードのいずれかで実行されます:
+
+- **アプリ モード** — エージェントはアプリ独自のツール (actions のみ) を持ちます
+  `defineAction` で定義され、ナビゲーションとコンテキストも追加されます。ファイルシステムがない、または
+  シェルアクセス。これがエンドユーザーに得られるものです。
+- **コード モード** — 共有コーディング ツール (`bash`、`read`、`edit`、`write`) を追加します
+  アプリ ツール上でデータベースにアクセスできるため、エージェントはアプリの変更を行うことができます
+  独自のソース。コードリクエストはゲートされます: メッセージにコードが必要な場合
+  (`type: "code"`)、コード対応フレームが接続されていない場合、パネルには
+  コード変更には Agent Native デスクトップまたは Builder が必要であることを説明するダイアログ;
+  フレームが接続されると、リクエストはフレームとコードエージェントにルーティングされます
+  インジケーターは、動作中は表示されます (`useSendToAgentChat`)。正規版
+  コーディング ツール リストと共有 UI コントラクトについては、
+  [Agent-Native Code UI](/docs/code-agents-ui).
+
+```an-diagram title="Code-request gating" summary="A code-typed message needs a code-capable frame. With one connected, the request routes there; without one, the panel explains code changes need Desktop or Builder."
+{
+  "html": "<div class=\"diagram-gate\"><div class=\"diagram-node\" data-rough>message<br><small class=\"diagram-muted\">type: \\\"code\\\"</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>code-capable frame connected?</div><div class=\"diagram-col\"><div class=\"diagram-pill ok\">yes &rarr; route to frame, show code-agent indicator</div><div class=\"diagram-pill warn\">no &rarr; dialog: needs Desktop or Builder</div></div></div>",
+  "css": ".diagram-gate{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-gate .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-gate .diagram-arrow{font-size:22px;line-height:1}.diagram-gate .center{text-align:center}"
+}
+```
+
+「コード モード」はエージェント機能の切り替えであり、環境開発モードとは異なります
+(`NODE_ENV` / Vite)。クライアントフックは`useCodeMode()`です。 (
+後方互換エイリアスの [Compatibility notes](#compatibility))
+
+ローカル開発フレームでは、設定歯車がこれらのモード間を切り替えます。切り替え
+オフ コード モードでは、フレーム自体のサイドバーが非表示になり、アプリのアプリ内エージェントが表示されます
+代わりに iframe 内のサイドバーを使用すると、エンド ユーザーに表示される内容を正確にプレビューできます。
+
+## 統合ターミナルと CLI スイッチング {#cli-terminal}
+
+開発中のパネルには埋め込み端末 (`AgentTerminal`、同様) が含まれています
+from `@agent-native/core/client`) PTY サーバーによってバックアップされます。実際の
+アプリのすぐ横に CLI をコーディングし、それらを切り替えます。端末が再起動します
+選択した CLI と。
+
+サポートされている CLI は、コア CLI レジストリから取得されます
+(`packages/core/src/terminal/cli-registry.ts`)。以下のコマンドのみが許可されます
+生成するため — PTY サーバーは、要求されたコマンドをレジストリと照合して検証します
+インジェクションを防止する許可リスト:
+
+| CLI            | コマンド   | パッケージをインストール    |
+| -------------- | ---------- | --------------------------- |
+| Claude コード  | `claude`   | `@anthropic-ai/claude-code` |
+| Builder.io     | `builder`  | (内蔵)                      |
+| Codex          | `codex`    | `@openai/codex`             |
+| ジェミニ CLI   | `gemini`   | `@google/gemini-cli`        |
+| オープンコード | `opencode` | `opencode-ai`               |
+
+選択した CLI が `PATH` で見つからない場合、端末はフォールバックして実行します
+`npx --yes <install-package>@latest` まで (インストール パッケージが存在する場合)。
+デフォルトのコマンドは `claude` です。エージェント パネルの設定から CLI を任意の場所に切り替えます。
+時間。
+
+## Builder.io クラウド フレーム {#cloud-frame}
+
+[Builder.io](https://www.builder.io) は、
+クラウド内の同じアプリと同じエージェント パネル:
+
+- リアルタイム コラボレーション - 複数のユーザーが同時に視聴し、対話できます。
+- ビジュアル編集、役割、権限。
+- 反復を高速化するための並列エージェント実行。
+- 全員が 1 つのホスト環境を共有する、チームでの使用に適しています。
+
+埋め込みパネルからのコード リクエストは、同様に Builder フレームにルーティングされます
+それらはローカルの開発フレームにルーティングされるため、上記の開発対製品の動作は次のようになります
+両方で一貫しています。
+
+## ランタイム API {#runtime-apis}
+
+これらは `@agent-native/core` に同梱されており、アプリが通信するために使用するものです
+どのフレームがホストしているかに関係なく、エージェント:
+
+1. **メッセージを送信** — `sendToAgentChat()` はエージェントにメッセージを送信します。
+   `useSendToAgentChat()` フックは、説明されているコードリクエスト ゲートでラップします
+   上で、レンダリングする `codeRequiredDialog` 要素を返します。
+   完全な使用方法とオプションについては [Drop-in Agent](/docs/drop-in-agent)。
+2. **生成状態** — `useAgentChatGenerating()` は、エージェントの状態を追跡します
+   実行中であるため、UI はエージェントに直接ポーリングせずに進行状況を表示できます。
+3. **ポーリング同期** — データベースに基づく同期により、エージェントの実行時に UI キャッシュが最新の状態に保たれます
+   データまたはアプリケーションの状態を変更します。
+4. **アクション システム** — `pnpm action <name>` は同じ呼び出し可能にディスパッチします
+   エージェントは actions をツールとして呼び出すため、エージェントが実行できることはすべて実行できます
+   スクリプト。
+
+## 実行中 {#running}
+
+埋め込みエージェント パネルはすべてのアプリの一部です。テンプレートを足場にして
+すでにそこにあります:
+
+```bash
+npx @agent-native/core@latest create my-app --template mail --standalone
+cd my-app
+pnpm dev
+```
+
+ローカル開発フレーム (フレームワーク リポジトリ内のプライベート `@agent-native/frame` パッケージ) は、npm に公開されていない内部ツール パッケージです。アクティブなアプリの開発サーバーを iframe にロードし、その横に埋め込みパネルをマウントし、`app` クエリ パラメーターを介してアプリを選択します。統合された CLI 端末には、端末に必要なローカル コードと PTY アクセスを提供する Agent Native デスクトップが必要です。これがないと、パネルにチャット サーフェスが表示され、CLI を使用するためにデスクトップを開くように求められます。
+
+## 互換性に関するメモ {#compatibility}
+
+「コード モード」の概念は以前は「開発モード」と呼ばれていたため、いくつかの後方互換性があります
+名は保持されます。古い統合を維持していない限り、これらは無視してかまいません。
+コード:
+
+- 基になる `AGENT_MODE` 環境変数、`/_agent-native/agent-chat/mode`
+  エンドポイント (ペイロード キーは依然として `devMode`)、および `agent-chat.mode`
+  設定キーは変更されません。
+- `useDevMode()` は、`useCodeMode()` の非推奨のエイリアスとして残ります。

package/docs/content/locales/ja-JP/getting-started.md

@@ -0,0 +1,199 @@
+---
+title: "はじめに"
+description: "エージェント アプリを作成し、命令、skills、actions を理解してから、エージェントが最初のアクションを呼び出す様子を観察します。"
+---
+
+# はじめに
+
+Agent-Native アプリは、AI エージェントと UI に同じ actions、データ、および
+状態。基本的なエージェントは、それをガイドする命令 (skills) から作成されます。
+再現可能な動作と、実際の作業を可能にする actions。
+
+**完全なアプリから開始したいですか?** 豊富なテンプレートの 1 つを複製します —
+[Chat](/docs/template-chat), [Mail](/docs/template-mail),
+[Calendar](/docs/template-calendar), [Content](/docs/template-content),
+[Analytics](/docs/template-analytics)、および [many more](/docs/cloneable-saas) —
+それぞれがカスタマイズしたフル機能のアプリです。
+
+ゼロから構築しますか?事前の唯一の選択肢は、UI が必要かどうかです —
+その後のすべて (命令の作成、skills の追加、actions の定義、実行
+エージェント）はどちらの方法でも同じです。
+
+```an-file-tree title="A basic Agent-Native agent"
+{
+  "entries": [
+    { "path": "AGENTS.md", "note": "always-on instructions: purpose, rules, tone, and the map of what the agent can do" },
+    { "path": ".agents/skills/customer-research/SKILL.md", "note": "a reusable playbook the agent loads when the task matches" },
+    { "path": "actions/summarize-week.ts", "note": "typed code the agent, UI, CLI, HTTP, MCP, A2A, jobs, and webhooks can run" }
+  ]
+}
+```
+
+これは、チャット UI、ヘッドレス エージェント、または完全なアプリから開始するかどうかに当てはまります。
+UI は表面を変更します。命令、skills、および actions はエージェントに
+指導と行動。
+
+## 1.アプリを作成します
+
+[Node.js 22+](https://nodejs.org) と [pnpm](https://pnpm.io) が必要です。
+
+フラグなしで `create` を実行すると、どのように開始するかを尋ねられます (完全なテンプレート、
+チャット、またはヘッドレス) 他の何よりも前に:
+
+```bash
+npx @agent-native/core@latest create my-app
+```
+
+または、フラグを渡してプロンプトをスキップします。
+
+**UI が必要ですか?** チャット テンプレートから開始します。作業エージェントに加えて
+カスタマイズ可能なチャット UI、追加したすべてのアクションが自動的にチャットに表示されます:
+
+```bash
+npx @agent-native/core@latest create my-app --template chat
+```
+
+**単なるヘッドレス プリミティブですか?** ヘッドレスで開始します — 同じ actions とエージェント
+ループ、UI シェルなし:
+
+```bash
+npx @agent-native/core@latest create my-agent --headless
+```
+
+次に、作成したフォルダーからインストールします。
+
+```bash
+cd my-agent # or my-app if you chose the Chat template
+pnpm install
+```
+
+ここからは、この 2 つは同じです。
+
+## 2.アクションを追加
+
+アクションとは、エージェント (および UI) が呼び出すことができる 1 つの操作です。両方の足場
+このサンプルが同梱されています:
+
+```an-annotated-code title="最初の action"
+{
+  "filename": "actions/hello.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { z } from \"zod\";\n\nexport default defineAction({\n  description: \"ローカルエージェントから挨拶します。\",\n  schema: z.object({\n    name: z.string().default(\"world\"),\n  }),\n  http: { method: \"GET\" },\n  readOnly: true,\n  run: async ({ name }) => {\n    return { message: `Hello, ${name}!` };\n  },\n});",
+  "annotations": [
+    { "lines": "5", "label": "ツール説明", "note": "エージェントは `description` を読み、いつツールとして呼び出すかを判断します。" },
+    { "lines": "6-8", "label": "型付き契約", "note": "1 つの zod `schema` が、エージェント、UI、HTTP、MCP、A2A のすべての入力を検証します。" },
+    { "lines": "9", "label": "HTTP verb", "note": "Opt this action into an auto-mounted HTTP endpoint." },
+    { "lines": "10", "label": "Read-only", "note": "`readOnly` marks the action as safe to call without approval and cacheable for queries." },
+    { "lines": "11-13", "label": "One implementation", "note": "The `run` body is the single source of truth that every surface executes." }
+  ]
+}
+```
+
+`hello` をドメイン内の最初の実際の操作に置き換えます。一度定義すれば、
+あらゆる表面がそれを拾います。
+
+毎ターン適用されるガイダンスとして `AGENTS.md` を使用してください。
+エージェントには、再利用可能なワークフローまたはドメイン プロシージャが必要です。
+エージェントには、データの読み取り、書き込み、API の呼び出しなどを行うための、型指定されたテスト可能な方法が必要です。
+承認を実行します。
+
+## 3.実行してください
+
+アクションを直接呼び出します:
+
+```bash
+pnpm action hello --name Steve
+```
+
+または、エージェントに電話してもらうよう依頼してください。
+
+```bash
+pnpm agent "Call the hello action for Steve and explain what happened."
+```
+
+チャット テンプレートから開始した場合は、アプリを実行し、同じエージェントを使用します。
+ブラウザ — 定義したすべてのアクションをすでに呼び出すことができます:
+
+```bash
+pnpm dev
+```
+
+その 1 つのアクションは、チャット UI、CLI、HTTP、MCP、A2A からアクセスできるようになりました。
+スケジュールされたジョブ、および webhooks。一度定義すれば、どこからでも呼び出すことができます。
+
+```an-diagram title="One action, every surface" summary="A single defineAction file fans out to every consumer with no extra wiring."
+{
+  "html": "<div class=\"diagram-fan\"><div class=\"diagram-box\" data-rough>defineAction</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-surfaces\"><span class=\"diagram-pill\">Chat UI</span><span class=\"diagram-pill\">CLI</span><span class=\"diagram-pill\">HTTP</span><span class=\"diagram-pill\">MCP</span><span class=\"diagram-pill\">A2A</span><span class=\"diagram-pill\">Scheduled jobs</span><span class=\"diagram-pill\">Webhooks</span></div></div>",
+  "css": ".diagram-fan{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-fan .diagram-surfaces{display:flex;flex-wrap:wrap;gap:8px;max-width:420px}.diagram-fan .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 状態は組み込まれています
+
+ヘッドレスはステートレスを意味するものではありません。 Actions、セッション、アプリケーションの状態、スレッド、
+実行履歴と資格情報はすべて SQL に存在します。ローカルでは、
+`data/app.db`;運用環境では、`DATABASE_URL` を設定します。参照
+[Deployment](/docs/deployment).
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Headless is still a real app.** The app-agent loop persists sessions, threads, runs, settings, and credentials in SQL — it is not a stateless prompt. You can add a UI later without touching your actions or state."
+}
+```
+
+## UI をカスタマイズ
+
+チャット テンプレートから開始した場合は、UI を編集できます。チャット自体
+`<AgentChatSurface>` コンポーネント上に構築された 1 つの小さなルートです:
+
+```tsx
+// app/routes/_index.tsx
+import { AgentChatSurface } from "@agent-native/core/client";
+
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-full" />;
+}
+```
+
+- **`app/routes/_index.tsx`** — チャット ページ。提案を変更します。空白
+  状態、レイアウト。
+- **`app/root.tsx`** — アプリシェル。
+  エージェント。
+- `<AgentSidebar>` を使用してエージェントを任意の画面にドロップし、手動で操作します
+  `sendToAgentChat()` でボタンを押すか、
+  `useActionMutation()`.
+
+完全なコンポーネント セットについては、[Drop-in Agent](/docs/drop-in-agent) を参照してください。
+[Native Chat UI](/docs/native-chat-ui) はアクションの結果をテーブルとしてレンダリングします。
+プレーンテキストの代わりにグラフと入力されたカード。
+
+**ヘッドレスで始めましたが、後で UI が必要ですか?** チャット テンプレートは UI オンランプです —
+その `app/` レイヤー (React ルーター + Vite) はまさにヘッドレス足場です
+は除外されます。最もクリーンな方法は、チャットから開始 (または再スキャフォールディング) することです
+テンプレート; `actions/`、エージェント、および SQL の状態は変更されずに引き継がれます。参照
+間にあるすべてのサーフェスに対して [Agent Surfaces](/docs/agent-surfaces)。
+
+## プロジェクトの構造
+
+```text
+my-app/
+  actions/         # Agent-callable actions
+  app/             # React frontend (UI templates only; omitted when headless)
+  server/          # Nitro API server (routes, plugins)
+  AGENTS.md        # Always-on agent instructions
+  .agents/         # Skills the agent can pull in when relevant
+  data/app.db      # Local SQLite state when DATABASE_URL is unset
+```
+
+## 次にどこに行くか
+
+- **[Key Concepts](/docs/key-concepts)** — コア アーキテクチャ: SQL、actions、
+  同期とコンテキスト認識。
+- **[Actions](/docs/actions)** — 完全なアクション API: スキーマ、HTTP、認証、
+  承認。
+- **[Agent Surfaces](/docs/agent-surfaces)** — ヘッドレス、チャット、埋め込みサイドカー
+  および完全なアプリ。
+- **[Drop-in Agent](/docs/drop-in-agent)** — エージェント チャットを React アプリに追加します。
+- **[Deployment](/docs/deployment)** — アプリを独自のドメインに配置します。
+- **[FAQ](/docs/faq)** — セットアップと製品に関する質問。