@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/ja-JP/database.md

@@ -0,0 +1,183 @@
+---
+title: "データベース"
+description: "ポータブル SQL データベースをエージェント ネイティブ アプリに接続し、プロバイダーに依存しない Drizzle コードを作成します。"
+---
+
+# データベース
+
+エージェント ネイティブ アプリは [Drizzle ORM](https://orm.drizzle.team) を使用し、ポータブル SQL バックエンドをサポートします。ローカル開発以外の場合は、`DATABASE_URL` を設定して、永続的な SQL データベース (Postgres、libSQL/Turso、または別の Drizzle 互換バックエンド) に接続します。この変数の設定が解除されると、アプリは設定ゼロのローカル SQLite ファイルに戻るため、すぐに開発を開始できます。
+
+```an-diagram title="One schema, many backends" summary="App code uses the framework's dialect-agnostic helpers. The dialect is auto-detected from DATABASE_URL at runtime; unset means a local SQLite file."
+{
+  "html": "<div class=\"diagram-db\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">@agent-native/core/db/schema</span><small class=\"diagram-muted\">table · text · integer · real · now</small><small class=\"diagram-muted\">+ Drizzle query DSL</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>DATABASE_URL<br><small class=\"diagram-muted\">dialect auto-detected</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">Postgres<br><small class=\"diagram-muted\">Neon · Supabase</small></span><span class=\"diagram-pill\">libSQL / Turso</span><span class=\"diagram-pill\">Cloudflare D1</span><span class=\"diagram-pill warn\">SQLite file<br><small class=\"diagram-muted\">unset = local dev only</small></span></div></div>",
+  "css": ".diagram-db{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-db .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-db .diagram-arrow{font-size:22px;line-height:1}.diagram-db .diagram-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}"
+}
+```
+
+## ローカルのデフォルト: SQLite ファイル {#default-sqlite}
+
+`DATABASE_URL` が設定されていない場合、アプリは `data/app.db` に SQLite データベースを作成します。これはローカル開発のゼロ構成のデフォルトであり、セットアップは必要ありません。これは開発のみを目的としています。運用環境の場合は、`DATABASE_URL` を永続的な SQL データベースに設定します。
+
+デプロイされたアプリについては、そのローカル ファイルに依存しないでください。コンテナー、サーバーレス関数、およびプレビュー環境はファイルシステムをリセットする場合があります。これは、再起動の間にローカルの SQLite ファイルが消える可能性があることを意味します。運用環境で使用する前に、`DATABASE_URL` を永続的なホスト型データベースに設定します。
+
+## 実稼働データベースへの接続 {#production}
+
+`.env` ファイルまたはデプロイプロバイダー環境で `DATABASE_URL` を設定し、ホストされたデータベースに接続します。 Turso は必要ありません。導入に適した Drizzle 互換の SQL バックエンドを使用してください:
+
+```bash
+# Neon Postgres
+DATABASE_URL=postgres://user:pass@ep-cool-name-123456.us-east-2.aws.neon.tech/mydb?sslmode=require
+
+# Supabase Postgres
+DATABASE_URL=postgres://postgres.xxxx:pass@aws-0-us-east-1.pooler.supabase.com:6543/postgres
+
+# Plain Postgres
+DATABASE_URL=postgres://user:pass@localhost:5432/mydb
+
+# Turso (libSQL)
+DATABASE_URL=libsql://my-db-org.turso.io
+DATABASE_AUTH_TOKEN=your-token
+```
+
+フレームワークは URL から方言を自動検出し、それに応じて Drizzle を構成します。内蔵アダプターは、Postgres URL、libSQL/Turso URL、SQLite ファイル URL、および Cloudflare D1 バインディングをカバーします。一般的な本番環境の選択肢には、Neon、Supabase、Turso/libSQL、プレーン Postgres、耐久性のある SQLite、利用可能な場合は Builder.io で管理された環境が含まれます。
+
+## Builder.io 管理データベース {#builder-managed}
+
+_計画中 (まだ利用可能ではありません):_ Builder.io に接続すると、アプリは接続文字列を必要とせずに、自動的にプロビジョニングされたマネージド データベースを使用できるようになります。
+
+## DB クライアントが存在する場所 {#db-client}
+
+各テンプレートは、`@agent-native/core/db` から `createGetDb(schema)` を呼び出して、遅延シングルトン Drizzle クライアントを作成します。正規の場所は `server/db/index.ts` です:
+
+```ts
+// server/db/index.ts
+import { createGetDb } from "@agent-native/core/db";
+import * as schema from "./schema.js";
+
+export const getDb = createGetDb(schema);
+```
+
+`@agent-native/core` から直接ではなく、このテンプレート ローカル パス (ルート内の `../../server/db/index.js`、actions 内の `../server/db/index.js`) から `getDb` をインポートします。コア エクスポートは、汎用の型なしインスタンスを返します。テンプレートの `getDb()` にはスキーマ タイプが含まれます。 actions とカスタム ルートがそれぞれどのようにインポートするかについては、[Server](/docs/server#request-context) を参照してください。
+
+## 方言に依存しないスキーマとクエリ {#schema}
+
+アプリ データベース コードは、プロバイダー間で実行できるように、Drizzle のスキーマを使用し、DSL をクエリする必要があります。製品コードには、SQLite のみの構文 (`INSERT OR REPLACE`、`AUTOINCREMENT`、`datetime('now')`) または Postgres のみの構文を決して書かないでください。
+
+`@agent-native/core/db/schema` のフレームワークのスキーマ ヘルパーを使用します:
+
+```ts
+import { table, text, integer, real, now } from "@agent-native/core/db/schema";
+
+export const tasks = table("tasks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  priority: integer("priority").notNull().default(0),
+  weight: real("weight"),
+  done: integer("done", { mode: "boolean" }).notNull().default(false),
+  ownerEmail: text("owner_email").notNull(),
+  createdAt: text("created_at").notNull().default(now()),
+});
+```
+
+| ヘルパー  | 目的                                                               |
+| --------- | ------------------------------------------------------------------ |
+| `table`   | テーブルを定義します — `pgTable` または `sqliteTable` に委任します |
+| `text`    | テキスト列、`{ enum: [...] }` をサポート                           |
+| `integer` | 整数列、`{ mode: "boolean" }` は Postgres ブール値にマップされます |
+| `real`    | 浮動列 — SQLite の `real`、Postgres の `double precision`          |
+| `now`     | `.default(now())` の方言に依存しない現在のタイムスタンプ           |
+
+上記の `tasks` テーブルは、すべてのバックエンドで同じ列を定義します。
+
+```an-schema title="The tasks table" summary="Defined once with the framework helpers; the dialect is chosen at runtime from DATABASE_URL."
+{
+  "entities": [
+    {
+      "id": "tasks",
+      "name": "tasks",
+      "note": "Domain table. Add owner_email (or ...ownableColumns()) so SQL-level scoping can filter rows to the authenticated user.",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true, "nullable": false },
+        { "name": "title", "type": "text", "nullable": false },
+        { "name": "priority", "type": "integer", "nullable": false, "note": "default 0" },
+        { "name": "weight", "type": "real", "nullable": true },
+        { "name": "done", "type": "integer (boolean mode)", "nullable": false, "note": "default false; maps to a Postgres boolean" },
+        { "name": "owner_email", "type": "text", "nullable": false, "note": "enables data scoping" },
+        { "name": "created_at", "type": "text", "nullable": false, "note": "default now()" }
+      ]
+    }
+  ]
+}
+```
+
+`drizzle-orm/sqlite-core` または `drizzle-orm/pg-core` から直接インポートしないでください。常に `@agent-native/core/db/schema` を使用してください。
+
+ユーザー向けデータを保存するテーブルには、フレームワークの SQL レベルのスコープで行を認証されたユーザーにフィルターできるように、`owner_email` 列が含まれている必要があります。[Security](/docs/security#data-scoping) を参照してください。他のユーザーまたは組織との共有もサポートするテーブルでは、代わりに `...ownableColumns()` を分散する必要があります。これにより、1 回の呼び出しで `owner_email`、`org_id`、および `visibility` が追加されます。「[Sharing](/docs/sharing#building)」を参照してください。
+
+読み取りと書き込みには、Drizzle のクエリ ビルダーと `drizzle-orm` のポータブル オペレーターを使用します。
+
+```ts
+import { and, desc, eq } from "drizzle-orm";
+import { getDb } from "../server/db/index.js";
+import { tasks } from "../server/db/schema.js";
+
+const db = getDb();
+
+const openTasks = await db
+  .select()
+  .from(tasks)
+  .where(and(eq(tasks.ownerEmail, userEmail), eq(tasks.done, false)))
+  .orderBy(desc(tasks.createdAt));
+
+await db.update(tasks).set({ done: true }).where(eq(tasks.id, taskId));
+```
+
+## 生の SQL 脱出ハッチ {#raw-sql}
+
+生の SQL は、デフォルトのアプリコード API ではありません。追加的な移行、ヘルスチェック、Drizzle では表現できない慎重にレビューされた高度なクエリ、または 1 回限りのメンテナンスの場合にのみ使用してください。パラメータ化され、方言に依存しないようにしてください。 Drizzle スキーマのタイムスタンプの場合は、`.default(now())` を優先します。 SQL の移行の場合は、`runMigrations()` を使用して、フレームワークでサポートされる互換性の書き換えと方言ゲートされたステートメントが一元化された状態を維持できるようにします。
+
+Drizzle クエリ以外の生の SQL が本当に必要な場合:
+
+- `getDbExec()` — Postgres の `?` パラメータを `$1` に自動変換します
+- `isPostgres()` — ランタイム方言チェック
+- `intType()` — 現在の方言の正しい整数型を返します
+
+## 移行とスキーマの更新 {#migrations}
+
+ホスト環境では、複数の展開プレビュー、ブランチ、実稼働サーバーが同じ基盤データベースを共有します。したがって、データベース スキーマの更新は、データ損失やサービスの中断を避けるために厳格な制約に従う必要があります。
+
+### 「破壊的変更ゼロ」ルール
+
+すべてのデータベース スキーマの更新は **厳密に追加的**である必要があります。
+
+- **テーブルや列は削除しないでください。**
+- **テーブルまたは列の名前を変更しないでください。** 列またはテーブルの名前を変更すると、Drizzle へのドロップと作成のシーケンスのように見えます。これにより、既存の実稼働データが完全に削除されます。
+- 列の名前を変更または置換する必要がある場合は、古い列の横に新しい列を追加し、両方から読み取り/書き込みできるようにアプリケーション コードを更新し、データを移行し、アクティブなデプロイメントがその列を参照しなくなった場合にのみ、後のリリースで古い列を廃止します。
+
+> [!WARNING]
+> **運用データベースに対して `drizzle-kit push` を実行しないでください。**
+> テンプレート データベース スキーマは、アプリ固有のドメイン テーブルのみを定義します。中央フレームワーク テーブル (`user`、`session`、`application_state` など) は定義されません。実稼働環境に対して `drizzle-kit push` を実行すると、Drizzle はこれらのフレームワーク テーブルを「スキーマにない」ものとして検出し、削除しようとします。これにより、ただちにシステム全体の障害が発生し、データが失われます。
+
+### 安全な移行パス
+
+スキーマの変更は、直接プッシュするのではなく、アプリケーションの起動時に実行される SQL 移行を介して適用する必要があります。フレームワークの `runMigrations()` ヘルパーを呼び出して、サーバー プラグイン (`server/plugins/db.ts` など) 内で追加の移行を実装します。
+
+```an-annotated-code title="An additive migration plugin"
+{
+  "filename": "server/plugins/db.ts",
+  "language": "ts",
+  "code": "import { runMigrations } from \"@agent-native/core/db\";\n\nexport default runMigrations(\n  [\n    {\n      version: 1,\n      sql: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS sort_order INTEGER NOT NULL DEFAULT 0`,\n    },\n    {\n      // Dialect-gated: runs only on the matching backend. Omit the other key\n      // to make it a no-op on that dialect.\n      version: 2,\n      sql: {\n        postgres: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS tsv tsvector`,\n        sqlite: `SELECT 1`, // no-op; tsvector is Postgres-only\n      },\n    },\n  ],\n  { table: \"my_app_migrations\" },\n);",
+  "annotations": [
+    { "lines": "6-7", "label": "Additive only", "note": "`ADD COLUMN IF NOT EXISTS` is safe to re-run and never drops data. Renames look like drop+create to Drizzle, so add-then-migrate instead." },
+    { "lines": "13-16", "label": "Dialect gating", "note": "Pass an object keyed by dialect to run different SQL per backend. Make the other key a no-op (`SELECT 1`) for Postgres-only or SQLite-only features." },
+    { "lines": "19", "label": "Per-app version table", "note": "Each app tracks its own applied versions so migrations are idempotent across restarts and instances." }
+  ]
+}
+```
+
+## 環境変数 {#environment-variables}
+
+| 変数                  | 目的                                                                         |
+| --------------------- | ---------------------------------------------------------------------------- |
+| `DATABASE_URL`        | 永続的な SQL 接続文字列 (未設定 = ローカル SQLite、ローカル開発でのみ永続的) |
+| `DATABASE_AUTH_TOKEN` | 別のトークンを必要とするプロバイダー用の認証トークン (Turso/libSQL など)     |

package/corpus/core/docs/content/locales/ja-JP/deployment.md

@@ -0,0 +1,349 @@
+---
+title: "展開"
+description: "Nitro プリセット (Node.js、Vercel、Netlify、Cloudflare、AWS など) を使用して、エージェント ネイティブ アプリを任意のプラットフォームにデプロイします。"
+---
+
+# 展開
+
+エージェント ネイティブ アプリは内部で [Nitro](https://nitro.build) を使用します。つまり、プリセットを設定するだけで、設定を変更することなくあらゆるプラットフォームに展開できます。
+
+## 展開する前に: 永続データベースを選択する {#persistent-database}
+
+デプロイされたすべてのアプリには、永続的な SQL データベースが必要です。ローカル開発では、エージェントネイティブは `data/app.db` の SQLite ファイルにフォールバックします。これはマシンでは便利ですが、ファイルシステムがリセットされる可能性のあるコンテナ、プレビュー、またはサーバーレス環境では耐久性がありません。
+
+アプリを運用環境に昇格させる前に、デプロイプロバイダーで `DATABASE_URL` を設定します。エージェントネイティブはスキーマとクエリに Drizzle を使用するため、データ層は Drizzle 互換の SQL バックエンド間で移植可能であり、フレームワークは URL から方言を自動検出します。アダプターのリストと方言の詳細については、[Database](/docs/database#production) を参照してください。
+
+データベース プロバイダーが Turso/libSQL などの別のトークンを必要とする場合にのみ、`DATABASE_AUTH_TOKEN` を使用してください。ワークスペースの場合、すべてのアプリはデフォルトでルート `DATABASE_URL` を継承します。 1 つのアプリが別のデータベースを使用する必要がある場合は、`<APP_NAME>_DATABASE_URL` を設定します。
+
+## ワークスペースの展開: 1 つのオリジン、多数のアプリ {#workspace-deploy}
+
+プロジェクトが [workspace](/docs/multi-app-workspace) の場合、1 つのコマンドでプロジェクト内のすべてのアプリを単一のオリジンに配布できます。
+
+```bash
+npx @agent-native/core@latest deploy
+# https://your-agents.com/mail/*       → apps/mail
+# https://your-agents.com/calendar/*   → apps/calendar
+# https://your-agents.com/forms/*      → apps/forms
+```
+
+各アプリは `APP_BASE_PATH=/<name>` および `VITE_APP_BASE_PATH=/<name>` で構築され、ターゲットの Nitro プリセット用にパッケージ化されます。 Cloudflare Pages がデフォルトのプリセットで、`dist/_worker.js` で生成されたディスパッチャー ワーカーを使用します。 Netlify は、`.netlify/functions-internal/<app>-server` のアプリごとに 1 つの関数と生成されたリダイレクトを使用します。 Vercel は、ビルド出力 API を使用して、ワークスペース レベルの `.vercel/output` を書き込みます。
+
+```an-diagram title="One origin, many apps" summary="Each workspace app is built with its own base path and mounted under a path prefix on a single origin — so login and cross-app A2A are same-origin and free."
+{
+  "html": "<div class=\"diagram-ws\"><div class=\"diagram-panel\" data-rough><strong>https://your-agents.com</strong><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/mail/*</span><small class=\"diagram-muted\">apps/mail</small></div><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/calendar/*</span><small class=\"diagram-muted\">apps/calendar</small></div><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/forms/*</span><small class=\"diagram-muted\">apps/forms</small></div></div><div class=\"diagram-col wins\"><span class=\"diagram-pill ok\">shared login session</span><span class=\"diagram-pill ok\">zero-config cross-app A2A</span></div></div>",
+  "css": ".diagram-ws{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.diagram-ws .diagram-panel{display:flex;flex-direction:column;gap:6px;padding:14px 16px}.diagram-ws .diagram-row{display:flex;align-items:center;gap:8px}.diagram-ws .wins{display:flex;flex-direction:column;gap:8px;align-items:flex-start}"
+}
+```
+
+同一オリジンのデプロイにより、無料で 2 つの大きなメリットが得られます:
+
+- **共有ログイン セッション** — 任意のアプリにログインすると、すべてのアプリがログインします。
+- **ゼロ構成クロスアプリ A2A** — メールからの `@calendar` のタグ付けは同一オリジンフェッチです。兄弟間での CORS、JWT 署名は禁止です。
+
+次のコマンドを使用して出力を公開します。
+
+```bash
+wrangler pages deploy dist
+```
+
+Netlify 統合デプロイの場合は、Netlify プリセットを使用します。
+
+```bash
+npx @agent-native/core@latest deploy --preset netlify
+```
+
+Vercel 統合デプロイの場合は、Vercel プリセットを使用します。
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel
+```
+
+プロバイダーのビルド コマンドを構成する場合は、`--build-only` と同じコマンドを使用します。 Vercel は `npx @agent-native/core@latest deploy --preset vercel --build-only` を実行する必要があります。このコマンドは `.vercel/output` を直接書き込むため、ワークスペースのルーティングに `vercel.json` は必要ありません。
+
+ホストされたワークスペース ビルドには、デプロイ プロバイダー環境で `A2A_SECRET` が必要です。
+これにより、Slack、インバウンド webhooks、およびクロスアプリ A2A が署名を通じて作業を再開します
+バックグラウンドプロセッサ。ローカルの `--build-only` アーティファクト チェックは、これなしでも実行されます。
+
+アプリごとの独立したデプロイは引き続きサポートされています。スタンドアロンの足場と同様に `cd apps/<name> && npx @agent-native/core@latest build` のみです。
+
+## 仕組み {#how-it-works}
+
+`npx @agent-native/core@latest build` を実行すると、Nitro はクライアント SPA とサーバー API の両方を `.output/` に構築します。
+
+```an-file-tree title="Build output"
+{
+  "entries": [
+    { "path": ".output/", "note": "self-contained — copy to any environment and run" },
+    { "path": ".output/public/", "note": "built SPA (static assets)" },
+    { "path": ".output/server/index.mjs", "note": "server entry point" },
+    { "path": ".output/server/chunks/", "note": "server code chunks" }
+  ]
+}
+```
+
+出力は自己完結型です。`.output/` を任意の環境にコピーして実行します。
+
+```an-diagram title="Build to deploy" summary="One source tree builds to a Nitro preset; the same self-contained output runs on Node, Vercel, Netlify, Cloudflare, AWS, or Deno. Every instance points at the same persistent DATABASE_URL."
+{
+  "html": "<div class=\"diagram-deploy\"><div class=\"diagram-box\" data-rough>App source</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">build</span><small class=\"diagram-muted\">Nitro preset</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">Node.js</span><span class=\"diagram-pill\">Vercel</span><span class=\"diagram-pill\">Netlify</span><span class=\"diagram-pill\">Cloudflare</span><span class=\"diagram-pill\">AWS Lambda</span><span class=\"diagram-pill\">Deno</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Persistent DATABASE_URL<br><small class=\"diagram-muted\">shared by every instance</small></div></div>",
+  "css": ".diagram-deploy{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-deploy .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-deploy .diagram-arrow{font-size:22px;line-height:1}.diagram-deploy .diagram-grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:8px}"
+}
+```
+
+## プリセットの設定 {#setting-the-preset}
+
+デフォルトでは、Nitro は Node.js 用にビルドされます。別のプラットフォームをターゲットにするには、`vite.config.ts` でプリセットを設定します。
+
+```ts
+import { defineConfig } from "@agent-native/core/vite";
+
+export default defineConfig({
+  nitro: {
+    preset: "vercel",
+  },
+});
+```
+
+または、ビルド時に `NITRO_PRESET` 環境変数を使用します。
+
+```bash
+NITRO_PRESET=netlify npx @agent-native/core@latest build
+```
+
+## Node.js (デフォルト) {#nodejs}
+
+デフォルトのプリセット。ビルドして実行します:
+
+```bash
+npx @agent-native/core@latest build
+node .output/server/index.mjs
+```
+
+`PORT` を設定してリッスン ポートを構成します (デフォルト: `3000`)。
+
+運用環境の展開には、現在の Node.js LTS ラインを使用します。 2026 年 5 月の時点で、
+は Node.js 24 です。 Node.js 20 は 2026 年 4 月 30 日にサポート終了となり、廃止されました
+アップストリームのセキュリティ アップデートを受け取ります。
+
+### ドッカー {#docker}
+
+```dockerfile
+FROM node:24-slim AS build
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm build
+
+FROM node:24-slim
+WORKDIR /app
+COPY --from=build /app/.output .output
+# data/ is a runtime-created SQLite directory — do not copy a dev DB into prod.
+# For production, set DATABASE_URL to a hosted Postgres or Turso instance.
+RUN mkdir -p /app/data
+ENV PORT=3000
+EXPOSE 3000
+CMD ["node", ".output/server/index.mjs"]
+```
+
+## ヴェルセル {#vercel}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "vercel" },
+});
+```
+
+Vercel CLI または git Push 経由でデプロイします。
+
+```bash
+vercel deploy
+```
+
+ワークスペースの場合、すべてのアプリを 1 つの Vercel Build Output API バンドルにビルドします。
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel
+```
+
+Vercel Git デプロイメントの場合、ビルド コマンドを次のように設定します。
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel --build-only
+```
+
+ワークスペース ビルドは、各アプリの Nitro `vercel` 出力をルート `.vercel/output` にコピーし、各関数に独自のマウント パス環境を与え、`/<app-id>` でアプリを提供するルート構成を書き込みます。
+
+## Netlify {#netlify}
+
+Nitro `netlify` プリセットはうまく機能し、実際に、外部 Postgres (Neon) と通信するテンプレートの場合、Cloudflare Pages よりもはるかに高速なコールド スタート (~200 ミリ秒 TTFB 対 ~9 秒) を実現しました。 `vite.config.ts` でプリセットを設定します:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "netlify" },
+});
+```
+
+…またはビルド時に `NITRO_PRESET=netlify` を設定します。
+
+ワークスペースの場合、次のコマンドを実行して、1 つの Netlify サイトからすべてのアプリをデプロイします。
+
+```bash
+npx @agent-native/core@latest deploy --preset netlify
+```
+
+ワークスペース ビルドは、`dist/_workspace_static/` の下に静的アセットを書き込み、アセットを強制的にリダイレクトせずに各アプリを独自の Netlify 関数にルーティングします。そのため、サーバー関数がアプリのルートを処理する前に、`/mail/assets/...` のようなファイルが静的に提供されます。
+
+## Cloudflare ページ {#cloudflare-pages}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "cloudflare_pages" },
+});
+```
+
+## AWS ラムダ {#aws-lambda}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "aws_lambda" },
+});
+```
+
+## デノデプロイ {#deno-deploy}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "deno_deploy" },
+});
+```
+
+## 環境変数 {#environment-variables}
+
+### ビルド / ランタイム {#env-runtime}
+
+| 変数                        | 説明                                                                                                                                                                                |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PORT`                      | サーバー ポート (Node.js のみ)                                                                                                                                                      |
+| `NITRO_PRESET`              | ビルド時にビルド プリセットをオーバーライドする                                                                                                                                     |
+| `APP_BASE_PATH`             | プレフィックス (例: `/mail`) の下でアプリをマウントします。 `npx @agent-native/core@latest deploy` によって自動的に設定されます。スタンドアロンの場合は未設定のままにしておきます。 |
+| `AGENT_PROD_CODE_EXECUTION` | オプションの実稼働コード実行モード: `off` (デフォルト)、`sandboxed`、または `trusted`。 [Production Code Execution](#production-code-execution) を参照してください。                |
+
+データベース接続変数 (`DATABASE_URL`、`DATABASE_AUTH_TOKEN`、アプリごとの `<APP_NAME>_DATABASE_URL`) は [Database](/docs/database#production) に存在します。
+
+### 本番環境では必須 {#env-required-prod}
+
+これらは、アプリを実際の本番環境にプロモートする前に設定する必要があります。欠損値がある場合は、フェールクローズされる (フレームワークが開始を拒否する/リクエストの処理を拒否する) か、大音量の警告とともに弱い動作に戻ります。
+
+| 変数                     | 説明                                                                                                                                                                                                                                                                                                        |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET`     | 32 文字以上のランダムな文字列。署名セッション Cookie AND は、`OAUTH_STATE_SECRET` および `SECRETS_ENCRYPTION_KEY` のフォールバック HMAC です。必須: 運用環境に存在しない場合、フレームワークは起動時にスローされます。                                                                                      |
+| `BETTER_AUTH_URL`        | このアプリの公開元 (例: `https://mail.example.com`)。 Cookie ドメインと OAuth リダイレクト構築に使用されます。                                                                                                                                                                                              |
+| `ANTHROPIC_API_KEY`      | 組み込み実稼働エージェントの API キー。 **マルチテナント展開**では、ユーザーがユーザーごとのキーを持っていない場合、フレームワークはこれへのフォールバックを拒否します。つまり、自分のキーを持参する必要があります。シングルテナントの自己ホスト型インストールでは、これをグローバル キーとして使用します。 |
+| `OAUTH_STATE_SECRET`     | OAuth 状態エンベロープ用の専用 HMAC キー (Google、Atlassian、Zoom)。設定を解除すると `BETTER_AUTH_SECRET` に戻りますが、一方を回転させてももう一方が無効にならないように、専用の値を使用することをお勧めします。 `openssl rand -hex 32` 経由で生成します。                                                  |
+| `A2A_SECRET`             | アプリ間 A2A JSON ～ RPC の共有 HMAC。これがないと、本番環境ではすべての A2A エンドポイントと `/_agent-native/integrations/process-task` 自己起動エンドポイントは 503 を返します。                                                                                                                          |
+| `SECRETS_ENCRYPTION_KEY` | 暗号化された保存シークレット ボールトの AES-256-GCM キー。 `BETTER_AUTH_SECRET` にフォールバックします。両方が設定されていない場合、本番環境でハード障害が発生します。                                                                                                                                      |
+
+### 認証とアイデンティティ {#env-auth}
+
+OAuth プロバイダー資格情報 (Google、GitHub)、静的 MCP ベアラー フォールバック (`ACCESS_TOKEN` / `ACCESS_TOKENS`)、および電子メール検証の切り替えについては、[Authentication](/docs/authentication) に記載されています。選択した認証モードごとに設定します。
+
+### インバウンド Webhooks {#env-webhooks}
+
+各メッセージング統合には、本番環境で独自の署名シークレットが必要です (シークレットが欠落している場合、ハンドラーは偽造リクエストでフェールクローズされます)。統合ごとの変数は、[Messaging](/docs/messaging) および [Security](/docs/security) にリストされています。ローカル開発のみの場合、`AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS=1` は「警告して受け入れる」に戻ります。本番環境では決して設定しないでください。
+
+### セキュリティ構成 (オプトイン) {#security-config}
+
+デフォルトは厳密です。いくつかのオプトイン フラグにより​​動作が緩和されます (デバッグ スタック トレース、未検証の webhooks、ワークスペース スコープのキー フォールバック、MCP ハブのマルチ組織スイッチ、ランタイム環境変数の書き込み)。これらは、セキュリティのトレードオフとともに [Security](/docs/security) に文書化されています。特にリラックスしたパスが必要な場合を除き、設定しないでください。
+
+### ワークスペース .env の継承 {#env-inheritance}
+
+ワークスペース内では、ルート `.env` がすべてのアプリに自動的にロードされるため、`ANTHROPIC_API_KEY`、`A2A_SECRET`、`BETTER_AUTH_SECRET`、`OAUTH_STATE_SECRET` などの共有キーを設定する必要があるのは 1 回だけです。アプリごとの `apps/<name>/.env` が競合に勝ちます。
+
+### 強力な秘密の生成 {#env-generate-secrets}
+
+「32 文字以上のランダム」とマークされたシークレット (`BETTER_AUTH_SECRET`、`OAUTH_STATE_SECRET`、`A2A_SECRET`、`SECRETS_ENCRYPTION_KEY`) については、次のコマンドを使用して新しい値を生成します。
+
+```bash
+openssl rand -hex 32
+```
+
+すべてのインスタンスの環境変数を置き換えて再デプロイすることで、エンベロープをローテーションします。古いキーで署名されたセッション/OAuth 状態エンベロープは無効になるため、ユーザーは再度サインインする必要がある場合があります。
+
+## 本番エージェント ツール {#production-agent-tools}
+
+運用エージェントは、アプリの登録済み actions とフレームワーク ツールを次のサイトから取得します
+エージェント チャット プラグイン。 raw DB
+ツールのスコープは認証されたユーザー/組織に限定されますが、アプリ所有者は範囲を狭めることができます
+展開にもっと独自性を持たせる必要がある場合に浮上します:
+
+```ts
+// server/plugins/agent-chat.ts
+export default createAgentChatPlugin({
+  // Default: "write" (also true)
+  databaseTools: "read", // "write" | "read" | "off"
+  extensionTools: false,
+});
+```
+
+- `databaseTools: "write"` — デフォルト。 `db-schema`、`db-query`、
+  `db-exec`、および `db-patch`。書き込みの範囲は現在のユーザー/組織に限定されます。
+  スキーマの変更はブロックされます。
+- `databaseTools: "read"` — `db-schema` および `db-query` のみを登録します。エージェント
+  SQL を使用してデータを検査しますが、書き込みには型付きアプリ actions を使用する必要があります。
+- `databaseTools: "off"` または `false` — 生のデータベース ツールを
+  エージェント サーフェスのため、アプリの actions が唯一のデータ アクセス パスになります。
+- `extensionTools: false` — フレームワーク拡張管理 actions を削除し、
+  次のようなアプリに対するプロンプト ガイダンス (`create-extension`、`update-extension` など)
+  エージェントがサンドボックス化されたミニアプリを作成することを望まない。
+
+## 本番コードの実行 {#production-code-execution}
+
+デフォルトでは、実稼働エージェントはコード実行ツールなしで実行されます。アプリ actions、データベース ツール、MCP ツール、ブラウザ/セッション ツール、その他の登録されたフレームワーク ツールを呼び出すことはできますが、シェルやファイルシステムにはアクセスできません。
+
+ノード互換のデプロイメントでは、エージェント チャット プラグインまたは環境オーバーライドを通じて実稼働コードの実行を選択できます。
+
+```ts
+// server/plugins/agent-chat.ts
+export default createAgentChatPlugin({
+  codeExecution: { production: "sandboxed" },
+});
+```
+
+使用可能なモードは次のとおりです:
+
+- `off` — デフォルト。コード実行ツールは実稼働環境に登録されていません。
+- `sandboxed` — `run-code`、スクラブされた環境を備えた分離された Node.js JavaScript ランナー、新しい一時ディレクトリ、出力/時間制限、ローカルホスト ブリッジを、`provider-api-request`、`provider-api-docs`、`provider-api-catalog`、`web-request` などの許可リストに登録された登録ツール、およびリソースにバックアップされたワークスペースに登録します。 `workspaceRead` / `workspaceWrite` で使用されるファイル ブリッジ。
+- `trusted` — `run-code` と完全なコーディング ツール レジストリ (`bash`、`read`、`edit`、`write`) を登録します。これは、ホストへの完全なシェル アクセスが意図的に行われるシングル テナントまたはオペレータ制御の展開にのみ使用してください。
+
+コードを変更せずに特定のデプロイメントのプラグイン オプションをオーバーライドするには、`AGENT_PROD_CODE_EXECUTION=sandboxed` または `AGENT_PROD_CODE_EXECUTION=trusted` を設定します。 `AGENT_PROD_CODE_EXECUTION=off` は、プラグイン オプションで有効になっている場合でもコードの実行を強制的にオフにします。
+
+`run-code` サンドボックスはプロセス レベルの分離であり、OS コンテナーではありません。子プロセス環境からアプリのシークレットを削除し、利用可能な場合はノードのアクセス許可モデルを使用しますが、送信ネットワークはノード自体によってブロックされません。認証された呼び出しは、ツールが公開するブリッジ ヘルパーを経由する必要があります。
+
+## 本番環境での UI の更新 {#updating-ui-in-production}
+
+エージェント ネイティブの中核機能の 1 つは、エージェントがアプリのソース コード (コンポーネント、ルート、スタイル、actions) を変更できることです。ローカル開発中は、エージェントがファイルシステムに完全にアクセスできるため、これはシームレスに機能します。
+
+[production code execution](#production-code-execution) をオフにした標準的な運用環境では、エージェントはアプリ ツール (actions、データベース、MCP) にはアクセスできますが、ファイル システムにはアクセスできません。つまり、エージェントはデータの読み取りと書き込み、actions の実行、および外部サービスとの対話が可能ですが、React コンポーネントを編集したり、デプロイされたインスタンスに新しいルートを追加したりすることはできません。
+
+### Builder.io: 本番環境でのビジュアル編集 {#builderio}
+
+[Builder.io](https://www.builder.io) は、エージェントが運用環境でアプリの UI を変更できる機能を保持するマネージド クラウド環境を提供することで、この問題を解決します。リポジトリを Builder.io に接続し、UI の変更を直接要求します。再デプロイは必要ありません。
+
+**仕組み:**
+
+1. エージェントネイティブ リポジトリを Builder.io に接続します
+2. Builder.io は、エージェント、ビジュアル編集、リアルタイム コラボレーションを備えたクラウド フレームを提供します
+3. エージェントに UI 変更を行うよう促します。コンポーネント、ルート、スタイルはライブで編集されます
+4. 変更はリポジトリにコミットされます
+
+埋め込みエージェント パネルとクラウド フレーム オプションの詳細については、[Frames](/docs/frames) を参照してください。
+
+## マルチインスタンスの展開 {#multi-instance}
+
+エージェント ネイティブ アプリは、Drizzle 経由ですべての状態を SQL に保存し、[polling](/docs/key-concepts#polling-sync) 経由で UI をデータベースと同期します。ファイル システムの状態、スティッキー セッション、メモリ内キャッシュはありません。つまり、マルチインスタンスおよびサーバーレスのデプロイメントはすぐに機能し、すべてのインスタンスを同じ `DATABASE_URL` にポイントすると、それらは自動的に収束します。 [Key Concepts — Data in SQL](/docs/key-concepts#data-in-sql) および [Portability](/docs/key-concepts#hosting-agnostic) を参照してください。