@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,323 @@
+---
+title: "ワークスペース"
+description: "Claude ユーザーごとのコード レベルのカスタマイズ — skills、メモリ、命令、カスタム エージェント、スケジュールされたジョブ、MCP サーバー — ファイル システムではなく、SQL によってサポートされます。"
+---
+
+# ワークスペース
+
+> **どのワークスペース ドキュメントですか?** このページでは **カスタマイズ レイヤー**、つまりワークスペースとは何かについて説明します。デプロイメントの形状 (1 つのモノリポジトリ、多数のアプリ) については、[Multi-App Workspaces](/docs/multi-app-workspace) を参照してください。ガバナンス (誰が何を審査、承認、所有するか) については、[Workspace Governance](/docs/workspace-management) を参照してください。
+
+すべてのエージェント ネイティブ アプリには、エージェントを自分のものにするカスタマイズ レイヤーである **ワークスペース** が付属しています。これには、チームの指示 (`AGENTS.md`)、共有学習 (`LEARNINGS.md`)、個人の構造化メモリ (`memory/MEMORY.md`)、エージェントがオンデマンドで取り込む skills、カスタム サブエージェント、スケジュールされたジョブ、接続された MCP サーバーなど、Claude コード / Codex セットアップに期待されるすべてが含まれています。
+
+工夫: **ファイルシステム ファイルではなく、SQL 行です。** 各ユーザーは、データベースに保存された独自のワークスペースを取得します。起動する開発ボックスも、ユーザーごとのコンテナも、マウントするファイルもありません。マルチテナント SaaS は、完全にカスタマイズ可能なエージェントをすべてのユーザーに実質的に無料で提供できます。これは、すべてが行 (個人メモリ、個人 MCP サーバー、個人 skills、個人サブエージェント) であり、共有コードベースがそれらすべてを一度にホストするためです。
+
+```an-diagram title="A Claude-Code workspace, but stored in SQL" summary="The same customization layer — instructions, skills, memory, agents, jobs, MCP — except every file is a row in a shared multi-tenant database."
+{
+  "html": "<div class=\"ws-map\"><div class=\"diagram-card cc\"><span class=\"diagram-pill warn\">Claude Code / Codex</span><small class=\"diagram-muted\">~/.claude/ on a local disk</small><div class=\"ws-files\"><span class=\"diagram-box\">CLAUDE.md</span><span class=\"diagram-box\">skills/</span><span class=\"diagram-box\">memory</span><span class=\"diagram-box\">mcp.json</span></div><small class=\"diagram-muted\">one codebase per developer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card an\"><span class=\"diagram-pill accent\">Agent-native workspace</span><small class=\"diagram-muted\">rows in one SQL database</small><div class=\"ws-rows\"><span class=\"diagram-pill\">AGENTS.md</span><span class=\"diagram-pill\">skills/&hellip;</span><span class=\"diagram-pill\">memory/&hellip;</span><span class=\"diagram-pill\">mcp-servers/&hellip;</span></div><small class=\"diagram-muted\">one codebase, many users, scoped <code>u:&lt;email&gt;:&hellip;</code></small></div></div>",
+  "css": ".ws-map{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.ws-map .diagram-card{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:220px}.ws-map .ws-files,.ws-map .ws-rows{display:flex;flex-wrap:wrap;gap:6px;margin:4px 0}.ws-map .diagram-arrow{font-size:24px}"
+}
+```
+
+| Claude コード / Codex                 | エージェントネイティブのワークスペース                       |
+| ------------------------------------- | ------------------------------------------------------------ |
+| ローカル ディスク上のファイル         | 共有 SQL データベース内の行                                  |
+| 開発者ごとに 1 つのコードベース       | 1 つのコードベースで多数のユーザー                           |
+| 開発ボックスまたはコンテナが必要です  | 任意のサーバーレス/エッジ ホスト上で実行                     |
+| `~/.claude/` でのカスタマイズ         | ユーザーごとのカスタマイズ、スコープ指定された `u:<email>:…` |
+| プロジェクトごと `CLAUDE.md` / skills | アプリごとの `AGENTS.md` + ワークスペース メモリ リソース    |
+| JSON ファイル内の MCP 構成            | JSON の MCP 設定 _または_ スコープごとの設定 UI              |
+
+同じ機能。異なる経済学。これが SaaS にとって重要な理由については、[Templates](/docs/cloneable-saas) を参照してください。
+
+## 概要 {#overview}
+
+リソースには 3 つの実行時スコープがあります。
+
+- **個人** — 単一のユーザー (電子メール) を対象としています。設定、メモ、ユーザーごとのコンテキストに適しています。
+- **共有 / 組織** — アプリまたは組織内のすべてのユーザーに表示されます。アプリ/チームの指示、skills、共有設定に適しています。
+- **Workspace** — ディスパッチ リソースから管理される継承されたグローバル デフォルト。企業の事実、ポジショニング、ブランド ガイドライン、グローバル ガードレール、ワークスペース全体の skills、および共有 MCP サーバーに適しています。アプリは実行時にこれらを読み取ります。各アプリにはコピーされません。
+
+アプリ内のワークスペース パネルには、3 つのスコープすべてが表示されます。個人リソースと共有/組織リソースはそこで編集できます。ワークスペース スコープのリソースは、アプリ パネルでは読み取り専用であり、Dispatch から一元的に編集されるため、同期手順を行わなくても、すべてのアプリで同じ正規ファイルが表示されます。
+
+エージェントが各リソースを使用する方法を制御する正規パス:
+
+| ランタイム リソース                | パス                                        | エージェントによる使用方法                                           |
+| ---------------------------------- | ------------------------------------------- | -------------------------------------------------------------------- |
+| ガードレールの説明                 | `AGENTS.md` または `instructions/<slug>.md` | 受信したすべてのアプリで毎ターンロードされます                       |
+| グローバル skills                  | `skills/<slug>/SKILL.md`                    | ワークスペース skills としてリストされ、オンデマンドで読み取られます |
+| ブランド/会社リソース              | `context/<slug>.md`                         | 毎ターンインデックスが作成され、関連する場合は読む                   |
+| カスタム エージェント プロファイル | `agents/<slug>.md`                          | 再利用可能なローカル エージェント プロファイルとして利用可能         |
+| 共有 HTTP MCP サーバー             | `mcp-servers/<slug>.json`                   | 許可されたアプリの MCP ツール レジストリにロードされます             |
+
+これらのパスは、ワークスペース、組織/アプリ、個人の 3 つのスコープすべてに適用されます。同じパスが複数のレベルに存在する場合、後のスコープが優先されます。
+
+```an-diagram title="Three scopes, one effective file" summary="The runtime resolves the same path across workspace, app, and personal scopes on read — the most specific scope wins."
+{
+  "html": "<div class=\"ws-stack\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Workspace</span><small class=\"diagram-muted\">company-wide defaults from Dispatch</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">Organization / app</span><small class=\"diagram-muted\">team override for one app</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Personal</span><small class=\"diagram-muted\">per-user override &mdash; wins</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">Effective <code>context/brand.md</code></div></div>",
+  "css": ".ws-stack{display:flex;flex-direction:column;align-items:flex-start;gap:8px}.ws-stack .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px;min-width:280px}.ws-stack .diagram-arrow{font-size:20px;align-self:center}.ws-stack code{font-size:.85em}.ws-stack .diagram-box{align-self:center;margin-top:4px}"
+}
+```
+
+## はじめに: 1 分間のウォークスルー {#getting-started}
+
+エージェントの動作を 60 秒以内に変更します。
+
+1. **ワークスペース** タブ → **共有** → `AGENTS.md` を開きます (見つからない場合は、`+` → **ファイル** で作成します)。
+2. ルールを 1 つ追加します。例:
+
+   ```マークダウン
+   ## トーン
+
+   簡潔にしてください。答えを導きましょう。
+   ```
+
+3. 保存し、**チャット**に切り替えて、何でも質問してください。エージェントは新しいルールにすぐに従います。
+
+```an-callout
+{ "tone": "info", "body": "No restart, no redeploy. `AGENTS.md` is read at the start of every turn, so an edit you save now changes the agent's behavior on the very next message." }
+```
+
+**次のステップは必要に応じて実行できます:**
+
+- **Skills** (`+` → **スキル**) — `/skill-name` とのチャットで呼び出される、集中的なハウツー ファイルです。
+- **エージェント** (`+` → **エージェント**) — `@agent-name` で呼び出される再利用可能なサブエージェント ペルソナ。
+- **スケジュールされたタスク** (`+` → **スケジュールされたタスク**) — cron 上で実行されるプロンプト。スケジュールとトリガーについては、[Recurring Jobs](/docs/recurring-jobs) を参照してください。
+- **メモリ** — 共有 `LEARNINGS.md` と個人 `memory/MEMORY.md` により、会話全体で利用可能な耐久性のあるコンテキストが維持されます。
+
+## グローバル リソースと正規パス {#global-resources}
+
+ワークスペース スコープのリソースは、Dispatch の **リソース** ページから管理され、実行時にアプリによって継承されます。コピーや同期の手順はありません。 Dispatch は、次の 2 つの許可スコープをサポートします。
+
+- **すべてのアプリ** — ワークスペース内のすべてのアプリが継承するグローバル リソース。ほとんどの会社、ブランド、ペルソナ、ポジショニング、メッセージング、ガードレール コンテキストは **すべてのアプリ** である必要があります。
+- **選択されたアプリ** — アプリ固有のコンテキストまたはツールのために特定のアプリに付与されたリソース。これらは慎重に使用してください。
+
+パスによって、エージェントがリソースを使用する方法が決まります (上記の [Overview](#overview) の表を参照)。これは、多くのアプリが恩恵を受けるはずの、コア ペルソナ、ポジショニング、メッセージング、会社概要、ブランド ガイドライン、サポート ポリシー、共有 skills ツール、または共有 HTTP MCP ツールの適切なホームです。
+
+新しいワークスペースに役立つスターター パック:
+
+```text
+context/company.md              # what the company does, ICP, products, links
+context/brand.md                # voice, visual identity, spelling, forbidden usage
+context/messaging.md            # positioning, value props, proof points, objections
+instructions/guardrails.md      # compliance, escalation, and approval rules
+skills/company-voice/SKILL.md   # on-demand guidance for customer-facing writing
+agents/<slug>.md                # reusable custom agent profiles
+```
+
+`context/` ファイルを事実に基づいたものにし、簡単に確認できるようにしてください。 `instructions/guardrails.md` に毎ターン適用しなければならないルールを入れます。エージェントが会社の声に合わせてコピーを意図的に変換またはレビューする必要がある場合は、`skills/company-voice/SKILL.md` を使用します。
+
+1 つのアプリまたはチームのグローバルなデフォルトをオーバーライドするには、そのアプリ内に同じパスを使用して共有/組織リソースを作成します。 1 人の個人に対してこれをオーバーライドするには、同じパスを持つ個人リソースを作成します。ワークスペース ファイルをすべてのアプリにコピーしないでください。ランタイムは読み取り時にスタックを解決します。
+
+```text
+workspace context/brand.md
+-> shared/app context/brand.md
+-> personal context/brand.md
+```
+
+`context/` ファイルは短く事実に基づいたものにしてください。エージェントがざっと目を通すことができるいくつかの箇条書きです。
+
+```text
+<!-- context/brand.md -->
+
+# Brand
+
+- Voice: direct, warm, concrete
+- Use: "workspace", "agent", "team"
+- Avoid: unsupported superlatives and vague AI claims
+```
+
+## ワークスペースパネル {#workspace-panel}
+
+エージェント パネルには、チャットと CLI の隣に **ワークスペース** タブが含まれています。すべてのリソースのフォルダー編成ツリー、任意のテキスト ファイル (Markdown、JSON、YAML、プレーン テキスト) のインライン エディター、および `+` メニューの入力された作成フロー (ファイル、Skills、エージェント、スケジュールされたタスク) が表示されます。ユーザーは、継承されたワークスペースのデフォルトを参照し、個人または組織のリソースを作成/編集/削除できます。
+
+リソースを開くと、エディターに `workspace default -> organization/app override -> personal override` スタックを含む **有効なコンテキスト** ストリップが表示されるため、何が継承されたのか、およびオーバーライドがアクティブである理由がわかります。 Dispatch は、コントロール プレーン側からの同じモデルを示します。**リソース** ページで **アプリ内で有効**を使用するか、アプリ カードの **コンテキスト** ダイアログのリソース行で **スタック** を展開します。
+
+ディスパッチ承認ポリシーが有効になっている場合、**すべてのアプリ** リソースを作成、更新、または削除すると、すぐに適用されるのではなく、承認リクエストがキューに入れられます。作成/編集/削除ダイアログには、保存する前に影響プレビューが表示されます。
+
+ワークスペース ツールバーの `?` アイコンをクリックすると、いつでもこれらのドキュメントに戻ることができます。
+
+## エージェントがリソースを使用する方法 {#how-the-agent-uses-resources}
+
+組み込みアプリ エージェントは、統合 `resources` ツールを使用してリソースを管理します。`action: "list"`、`"read"`、`"effective"`、`"write"`、`"promote"`、または `"delete"` を使用します。外部 CLI/コード エージェントは、同等の `pnpm action resource-*` コマンドを使用できます。
+
+すべての会話の開始時に、エージェントは自動的に次の内容を読み上げます。
+
+### AGENTS.md と説明書 {#agents-md}
+
+`AGENTS.md` はデフォルトでシードされ、毎ターン、ワークスペース、共有/組織、個人スコープからこの順序でロードされます。ワークスペースは会社全体のデフォルト、共有/アプリはチーム ルール、個人はユーザーごとの設定です。 `instructions/` の下のファイルは別個のガードレール ドキュメントであり、これも毎ターン適用され (コンプライアンス ルール、エスカレーション ポリシー、ブランド ボイス)、同じ優先順位に従います。通常のチャットと統合によってトリガーされる実行は両方とも、応答する前にそれらを読み込みます。
+
+```text
+AGENTS.md
+instructions/customer-support-guardrails.md
+instructions/legal-review-policy.md
+```
+
+### 参考リソース {#reference-resources}
+
+再利用可能な企業コンテキストは `context/` (ペルソナ、ポジショニング、製品事実、ブランド ガイドライン、競合メモ) の下にあります。エージェントはこれらのインデックスを参照し、タスクがそれに依存している可能性がある場合、`resources` ツール (`action: "read"`) を使用して関連ファイルを読み取ります。 `action: "effective"` を使用して、ワークスペースのデフォルトがアプリまたはユーザーに対してオーバーライドされているかどうかを確認します。
+
+### メモリ {#memory}
+
+ワークスペースには 2 つの現在のメモリ サーフェスがあります:
+
+- プロジェクト全体の規約、修正、永続的なチームの知識のための **共有** スコープ内の `LEARNINGS.md`。
+- 現在のユーザーに関する構造化メモリの **個人** スコープ内の `memory/MEMORY.md`。
+
+リソース システムは、古いワークスペースとの互換性のために個人用 `LEARNINGS.md` もシードしますが、チャットのプリロード パスは共有 `LEARNINGS.md` と個人用 `memory/MEMORY.md` です。
+
+**保存される内容。** エージェントを修正したり (「Y ではなく常に X を使用する」)、好みを共有したり (「簡潔な回答を好みます」)、またはコンテキストを明らかにしたり (「私のチームではこれを「ディスパッチ層」と呼んでいます」) と、エージェントはその学習内容をキャプチャして、間違いを繰り返したり再質問したりすることがなくなります。プロジェクト全体の学習は共有 `LEARNINGS.md` に反映されます。ユーザー固有のメモリは `memory/` の下に置かれます。 `capture-learnings` スキルは、いつ、どのように行うかを詳しく説明します。
+
+**適切な場所。**
+
+| 表面               | スコープ              | 作者                                             | いつ読む                                           |
+| ------------------ | --------------------- | ------------------------------------------------ | -------------------------------------------------- |
+| `AGENTS.md`        | 共有                  | 人間 / リクエストに応じてエージェント            | 毎ターン                                           |
+| `LEARNINGS.md`     | 共有                  | 人間 / リクエストに応じてエージェント            | 毎ターン (共有コピーのみ)                          |
+| `memory/MEMORY.md` | 個人                  | エージェント / 人間                              | 毎ターン                                           |
+| `instructions/…`   | 共有                  | 人間 / リクエストに応じてエージェント            | 毎ターン                                           |
+| `skills/…`         | 共有                  | 人間 / リクエストに応じてエージェント            | オンデマンド (`/slash` コマンド)                   |
+| `context/…`        | 共有                  | 人間 / リクエストに応じてエージェント            | 毎ターンインデックスが作成され、関連する場合は読む |
+| `mcp-servers/…`    | ワークスペース / 共有 | Dispatch またはアプリ ワークスペースを介した人間 | MCP 設定の更新                                     |
+
+ユーザーはこれらのメモリ ファイルを [ワークスペース] タブで直接編集できます。これらは通常のリソースです。エージェントが間違えた行を削除するか、個人の設定を `memory/MEMORY.md` に保持するか、チーム全体のルールを `AGENTS.md` に昇格させます。
+
+これらのサーフェス (`AGENTS.md`、skills、メモリ、カスタム エージェント、MCP サーバー) はすべて、同じ基盤となるリソース形状 (`path` + `scope` + `content`) であり、同じ方法でアドレス指定され、解決されます。
+
+```an-schema title="The workspace resource model" summary="One resource shape backs every workspace file. The runtime keys it by path and scope and resolves the effective value on read."
+{
+  "entities": [
+    {
+      "id": "resource",
+      "name": "workspace resource",
+      "note": "A single file in a user's workspace — instructions, skill, memory, agent, MCP config, or job.",
+      "fields": [
+        { "name": "path", "type": "string", "note": "Canonical path, e.g. AGENTS.md, skills/<slug>/SKILL.md" },
+        { "name": "scope", "type": "workspace | shared | personal", "note": "Which level this row lives at" },
+        { "name": "owner", "type": "string", "nullable": true, "note": "u:<email> for personal scope" },
+        { "name": "content", "type": "text", "note": "Markdown / JSON / YAML body" }
+      ]
+    }
+  ]
+}
+```
+
+## Skills {#skills}
+
+Skills は、`skills/` パス (`skills/<name>/SKILL.md` が望ましい) にある Markdown リソース ファイルで、エージェントにオンデマンドのドメイン知識を提供し、`/skill-name` とのチャットで呼び出されます。 [ワークスペース] タブから追加するか、コード モードで `.agents/skills/` から追加します。
+
+[Skills Guide](/docs/skills-guide) を参照してください。スキルの形式、範囲、検出、およびオーサリングに関する単一のソースです。
+
+## カスタム エージェント {#custom-agents}
+
+カスタム エージェントは、`agents/*.md` の下に Markdown リソースとして保存される再利用可能なローカル サブエージェント プロファイルです。これは、カスタム エージェント形式の正規のホームです。
+
+独自の名前、説明、モデル設定、および命令セットを備えたフォーカスされたデリゲートが必要な場合にこれらを使用します。 skills とは異なり、カスタム エージェントは受動的ガイダンスではありません。カスタム エージェントは、メイン エージェントが `@` のメンションを通じて、またはサブエージェントの生成中に選択することによって呼び出すことができる運用ペルソナです。
+
+### エージェントの形式 {#agent-format}
+
+カスタム エージェントは、YAML フロントマターと Markdown 命令を使用します。
+
+```an-annotated-code title="A custom agent profile"
+{
+  "filename": "agents/design.md",
+  "language": "markdown",
+  "code": "---\nname: Design\ndescription: >-\n  Reviews layouts, interaction patterns, and product UX decisions.\nmodel: inherit\ntools: inherit\ndelegate-default: false\n---\n\n# Role\n\nYou are a focused design agent.\n\n## Responsibilities\n\n- Review layouts and interaction flows\n- Suggest stronger visual direction\n- Be concise and opinionated",
+  "annotations": [
+    { "lines": "2", "label": "@mention handle", "note": "`name` is what appears in the `@`-dropdown and what the main agent delegates to." },
+    { "lines": "3-4", "label": "When to delegate", "note": "The `description` is what the orchestrator reads to decide this profile fits a task." },
+    { "lines": "5", "label": "Model", "note": "`inherit` reuses the main agent's model. Override only when the profile clearly needs a different one." },
+    { "lines": "6", "note": "`tools: inherit` for now — the field is reserved for future per-agent tool policies." }
+  ]
+}
+```
+
+推奨される規則:
+
+- カスタム エージェントを `agents/<slug>.md` に保存します
+- プロファイルに明らかに別のモデルが必要でない限り、`model: inherit` を使用してください
+- 今のところ、`tools: inherit` を保持します。このフィールドは将来のツール ポリシーのために予約されています
+
+### リモート エージェントとカスタム エージェント {#remote-vs-custom-agents}
+
+ワークスペースには 2 つのエージェント タイプがあります:
+
+- **カスタム エージェント** — `agents/*.md` のローカル プロファイル、現在のアプリ/ランタイム内で実行されます
+- **接続されたエージェント** — `remote-agents/*.json` のマニフェストによって記述されたリモート A2A ピア (従来の `agents/*.json` マニフェストは引き続き認識されます)
+
+1 つのアプリ内での委任にはカスタム エージェントを使用します。 A2A 経由で別のアプリを呼び出す必要がある場合は、接続されたエージェントを使用します。
+
+## @ タグ付け {#at-tagging}
+
+ワークスペース項目を参照するには、チャット入力に「`@`」と入力します。カーソルの位置にドロップダウンが表示され、一致するエージェントとファイルが表示されます。矢印キーを使用して移動し、Enter キーを使用して選択します。選択したアイテムは入力内にインライン チップとして表示されます。
+
+メッセージを送信すると、**ファイル/リソース**がエージェントが読み取ることができる参照として渡され、**カスタム エージェント**がプロファイル命令に従ってローカルで実行され、**接続されているエージェント**が A2A 経由で呼び出されます。
+
+## / スラッシュコマンド {#slash-commands}
+
+スキルを呼び出すには、行の先頭に「`/`」と入力します。ドロップダウンには、利用可能な skills がその名前と説明とともに表示されます。いずれかを選択するとインライン チップが追加され、メッセージ送信時にその内容がコンテキストとして含まれます。 skills が設定されていない場合、ドロップダウンはこれらのドキュメントにリンクします。
+
+## コード対アプリモード {#dev-vs-prod}
+
+リソース システムはどちらのモードでも同様に動作します。異なるのは、`@` タグ付けと `/` コマンドで使用できる追加のソースです。
+
+| 機能                           | コードモード                                                                                     | アプリモード                                                             |
+| ------------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| @ タグ付け                     | コードベース ファイル + ワークスペース リソース + カスタム エージェント + 接続されたエージェント | ワークスペース リソース + カスタム エージェント + 接続されたエージェント |
+| /スラッシュコマンド            | .agents/skills/ + リソース skills                                                                | リソース skills のみ                                                     |
+| エージェント ファイル アクセス | ファイルシステム + リソース                                                                      | リソースのみ                                                             |
+| ワークスペースパネル           | フルアクセス                                                                                     | フルアクセス                                                             |
+| AGENTS.md / メモリ             | 利用可能                                                                                         | 利用可能                                                                 |
+
+## ワークスペース接続 {#workspace-connections}
+
+ワークスペース接続を使用すると、アプリは資格情報を重複せずに同じプロバイダー アカウント (Slack、GitHub、HubSpot など) を共有できます。接続は、プロバイダー ID、アカウント ラベル、ステータス、スコープ、アプリの許可、資格情報の参照を SQL に記録します。シークレットは資格情報ストアに残ります。接続は、`SLACK_BOT_TOKEN` などの資格情報キー名のみを指します。
+
+クイックスタート、connection/grant/credentialRef API、具体的な Slack、HubSpot、GitHub の例については、[Workspace Connections](/docs/workspace-connections) を参照してください。
+
+---
+
+# リファレンス
+
+## リソース API {#resource-api}
+
+リソースはサーバー コード、actions、または REST API から管理できます。
+
+### サーバー API {#server-api}
+
+REST エンドポイントは自動的にマウントされました:
+
+| メソッド | エンドポイント                                | 説明                                        |
+| -------- | --------------------------------------------- | ------------------------------------------- |
+| `GET`    | `/_agent-native/resources?scope=all`          | リソースのリスト                            |
+| `GET`    | `/_agent-native/resources?scope=workspace`    | 継承されたワークスペース リソースの一覧表示 |
+| `GET`    | `/_agent-native/resources/tree?scope=all`     | フォルダ ツリーを取得                       |
+| `GET`    | `/_agent-native/resources/effective?path=...` | 効果的な継承スタックを表示する              |
+| `POST`   | `/_agent-native/resources`                    | リソースを作成する                          |
+| `GET`    | `/_agent-native/resources/:id`                | コンテンツを含むリソースを取得              |
+| `PUT`    | `/_agent-native/resources/:id`                | リソースを更新する                          |
+| `DELETE` | `/_agent-native/resources/:id`                | リソースを削除する                          |
+| `POST`   | `/_agent-native/resources/upload`             | ファイルをリソースとしてアップロードする    |
+
+### アクション API {#script-api}
+
+エージェントはこれらの組み込み actions を使用します。自分の actions から呼び出すこともできます:
+
+```bash
+# List all resources
+pnpm action resource-list --scope all
+
+# Read a resource
+pnpm action resource-read --path "skills/my-skill/SKILL.md"
+
+# Read inherited workspace context managed by Dispatch
+pnpm action resource-read --scope workspace --path "context/brand.md"
+
+# Show workspace -> organization/app -> personal precedence for a path
+pnpm action resource-effective --path "context/brand.md"
+
+# Write a resource
+pnpm action resource-write --path "notes/meeting.md" --content "# Meeting Notes..."
+
+# Delete a resource
+pnpm action resource-delete --path "notes/old.md"
+```

package/corpus/core/docs/content/locales/ja-JP/writing-agent-instructions.md

@@ -0,0 +1,173 @@
+---
+title: "エージェントの指示と Skills の作成"
+description: "エージェント ネイティブ アプリまたはテンプレートの優れたエージェント手順を作成する方法: AGENTS.md、skills、およびツールの説明。"
+---
+
+# エージェントの指示と Skills の作成
+
+エージェント ネイティブ アプリにおけるエージェントの動作は、ユーザーが与えた指示によって決まります。 `AGENTS.md` (マップ)、skills (詳細)、およびアクション/ツールの説明 (エージェントが適切なツールを選択する方法) の 3 つのサーフェスでそのガイダンスが伝えられます。散文ではなく、迅速に検索できるようにそれぞれを書きます。
+
+```an-diagram title="Three authored surfaces + one runtime surface" summary="AGENTS.md and tool descriptions load every turn; skills load on demand; application_state is written live by your UI."
+{
+  "html": "<div class=\"diagram-surfaces\"><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">Every turn</span><strong>AGENTS.md</strong><small class=\"diagram-muted\">the map: purpose, core rules, state keys, action + skills index</small></div><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">Every turn</span><strong>Tool descriptions</strong><small class=\"diagram-muted\">drive tool selection — one precise sentence each</small></div><div class=\"diagram-card ondemand\" data-rough><span class=\"diagram-pill\">On demand</span><strong>Skills</strong><small class=\"diagram-muted\">deep how-to, loaded when the description fires</small></div><div class=\"diagram-card runtime\" data-rough><span class=\"diagram-pill ok\">Live</span><strong>application_state</strong><small class=\"diagram-muted\">written by your UI: navigation, selection, focus</small></div></div>",
+  "css": ".diagram-surfaces{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px}.diagram-surfaces .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px}"
+}
+```
+
+## AGENTS.md は小さく、スキミングできるようにしてください {#small-agents-md}
+
+`AGENTS.md` が方向としてロードされます。これは、エージェントが正しく動作するための最小のものであり、すべてが skills に深くプッシュされている必要があります。以下のセクションとその他のセクションを目指してください:
+
+- **目的行** — アプリとは何か、および主要なワークフローについての 1 文。
+- **コア ルール** — 常に保持する必要がある少数の不変条件 (データは SQL、操作は actions を経由し、AI はエージェント チャットを経由し、スキーマの変更は追加的です)。短くて命令的な箇条書き。
+- **アプリケーション状態キー** — ユーザーが見ているものとその形状を知るためにエージェントが読み取る `navigation`/選択/フォーカス キー。
+- **アクション テーブル** — アクション名と目的をまとめたコンパクトなテーブル。
+- **Skills インデックス** — 存在する skills のリストと、それぞれをいつ読み取るか。
+
+セクションが画面を超えて拡大する場合、それはスキルに属します。 `AGENTS.md` は、「難しいことを具体的にどのようにすればよいか」ではなく、「このアプリは何ですか、何ができるでしょうか」と答えます。
+
+```markdown
+# Projects App
+
+One workspace for projects, tasks, and notes. Agent and UI share the same SQL
+data and the same actions.
+
+## Core Rules
+
+- Data lives in SQL via Drizzle. Use actions for all writes.
+- All AI work goes through the agent chat; never call an LLM inline.
+- Schema changes are additive only.
+
+## Application State
+
+- `navigation.view`: `home` | `project`
+- `navigation.projectId`: selected project on a project page
+
+## Actions
+
+| Action           | Purpose                     |
+| ---------------- | --------------------------- |
+| `list-projects`  | List accessible projects    |
+| `create-project` | Create a project            |
+| `update-project` | Rename or archive a project |
+
+## Skills
+
+- `project-imports` — read before importing legacy CSV exports.
+- `sharing` — read before exposing a project to other users.
+```
+
+## 単一ソース AGENTS.md {#single-source}
+
+正規の命令ファイル `AGENTS.md` を 1 つ保持します。クライアントが `CLAUDE.md` を予期している場合は、2 番目のコピーではなく `AGENTS.md` へのシンボリックリンクを作成します。手動で管理された 2 つのファイルが漂流し、エージェントは矛盾したルールを使用することになります。真実の情報源は 1 つで、必要に応じてリンクされます。
+
+## SKILL.md のフロントマターには、いつ AND を記載する必要があります {#skill-frontmatter}
+
+エージェントがスキルを読み取るかどうかを決定するときに参照するのは、`description` だけです。スキルがカバーする内容と、それをいつトリガーするかという 2 つの質問に答える必要があります。トピックを説明するだけの説明は起動されません。
+
+```markdown
+---
+name: project-imports
+description: >-
+  How to import projects from the legacy CSV export. Use when the user uploads
+  a project CSV or asks to migrate projects from the old system.
+---
+```
+
+- 機能を説明してから、明示的な **「Use when…」** 句を追加します。
+- 少し強引になってください。過度にトリガーすると、ロードされないスキルに勝ります。
+- 最大 40 語以内に収めてください。すべての会話のコンテキストにロードされます。
+
+## 段階的な開示 {#progressive-disclosure}
+
+`SKILL.md` を無駄のない必知のレイヤーとして作成します: ルール、その方法、やるべきこと/やってはいけないリスト、およびポインタ。長い例、網羅的なフィールド参照、API の癖、およびエッジケースのテーブルを `references/` ファイルにプッシュし、エージェントが必要な場合にのみ読み取ります。
+
+```text
+.agents/skills/project-imports/
+├── SKILL.md            # rule + happy path + do/don't
+└── references/
+    └── csv-format.md   # full column spec, encodings, edge cases
+```
+
+これにより、常に読み込まれるサーフェスが小さく保たれ、コンテキストを肥大化させることなく深度をスケールできるようになります。完全なスキル形式については、[Skills Guide](/docs/skills-guide) を参照してください。
+
+## アクション指向のテーブルを作成する {#action-tables}
+
+エージェントは、散文よりも速くテーブルをスキャンします。各操作を説明する段落よりも、目的に応じた名前の表を使用することをおすすめします。同じことが、状態キー、フィールド タイプ、および列挙可能なセットにも当てはまります。テーブルはスキミングや比較が可能で、アクションを追加するときに簡単に同期を保つことができます。
+
+## 明確なツールの説明を書きます {#tool-descriptions}
+
+アクションの説明はツールの説明であり、ツールの選択を決定します。それぞれを正確で単一目的の文にします:
+
+- 実装方法ではなく、何を実行し、何を返すかを説明します。
+- エージェントが正しく入力できるように、`.describe()` に各パラメータを記述します。
+- アクションごとに 1 つの責任。説明に「そして…」が必要な場合は分割してください。
+- 読み取り専用 actions (`readOnly: true` または `http: { method: "GET" }`) にマークを付けると、エージェントは自由に電話しても安全であることがわかります。
+
+```ts
+defineAction({
+  description: "Create a project. Returns the new project id and title.",
+  schema: z.object({
+    title: z.string().min(1).describe("Project title shown in the sidebar"),
+  }),
+  // ...
+});
+```
+
+## Skills 対 actions {#skills-vs-actions}
+
+Skills と actions は相補的です。スキルとは、エージェントが読むガイダンスです。
+アクションは、エージェントが実行できるコードです。
+
+| 必要                                                                                         | 使用                             |
+| -------------------------------------------------------------------------------------------- | -------------------------------- |
+| エージェントはワークフロー、ポリシー、チェックリスト、またはルーブリックに従う必要があります | **スキル**                       |
+| エージェントには例、参考資料、またはドメイン固有のルールが必要です                           | **スキル**                       |
+| エージェントはアプリ データの読み取りまたは書き込みを行う必要があります                      | **アクション**                   |
+| エージェントは外部 API に電話するか、承認を実行する必要があります                            | **アクション**                   |
+| エージェントは正しい操作を呼び出していますが、その方法が間違っています                       | **スキル**を向上させる           |
+| エージェントが操作を確実に呼び出すことができません                                           | **アクション**を改善             |
+| エージェントが間違ったツールを選択した                                                       | **アクションの説明**を改善します |
+
+ほとんどの実際の機能は両方を使用します。スキルはタスクへのアプローチ方法を説明します。
+アクションは型指定された操作を提供します。たとえば、`invoice-review` スキル
+`list-invoices` ながらレビュー ポリシーとエスカレーション ルールを説明できる
+`flag-invoice` および `approve-invoice` actions は実際の読み取りと書き込みを行います。
+
+## 製造防止処理をベークし、完了前に検証を行う {#anti-fabrication}
+
+アプリの指示では、誠実さと検証をデフォルトの動作にする必要があります:
+
+- **絶対に捏造しないでください。** データが見つからない場合、またはアクションが失敗した場合は、そう言って回復してください。結果をでっち上げたり、成功を主張したりしないでください。レポートする前に、アクションまたはクエリを通じて実際の値を読み取ります。
+- **完了を宣言する前に確認してください。** 変更後は、書き込みが機能したと仮定するのではなく、リードバック (行を再クエリし、`view-screen` 経由で画面を再読み取り) して確認してください。
+- **諦めないで回復してください。** 回復可能なエラー (クエリの失敗、一時的なフェッチ) が発生した場合は、タスクを放棄するのではなく、入力を再試行するか修正してください。これを捏造防止ルールとは別にしてください。「でっちあげてはいけない」と「最初の間違いでやめてください」を混同しないでください。
+
+これらを `AGENTS.md` のコア ルールとして置き、すべてのターンに適用されるようにします。
+
+## エージェントが見る 4 つの表面 {#four-surfaces}
+
+あなたが作成したすべてのガイダンスは、4 つの表面のいずれかに配置されます。どのサーフェスを使用するかを把握すると、重複や細部の配置ミスを防ぐことができます:
+
+| 表面                             | 誰が書いたのか     | ロード時                                                       | そこに属するもの                                                                  |
+| -------------------------------- | ------------------ | -------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `AGENTS.md` 命令                 | あなた（開発者）   | 毎ターン、オリエンテーションとして                             | 目的、コアルール、状態キー、アクションインデックス、skills インデックス           |
+| Skills (`SKILL.md`)              | あなた（開発者）   | エージェントがスキルが関連していると判断した場合のオンデマンド | 特定のパターンのステップバイステップのハウツー、やるべきこと/やらないことのリスト |
+| アクションの説明 (ツール)        | あなた（開発者）   | 毎ターン、ツールリストとして                                   | アクションの動作、アクションが返す内容、パラメータのセマンティクス                |
+| `application_state` コンテキスト | UI コード (実行時) | 毎ターン、アプリのライブ状態として                             | 現在のナビゲーション、選択範囲、フォーカスされたオブジェクト、URL                 |
+
+**簡単な診断:**
+
+- 「レコードが開いている場合でも、エージェントはどのレコードを処理するかを尋ね続けます」→修正: 現在のアイテム ID を UI から `application_state` (`navigation` キー) に書き込みます。それは `application_state` の差であり、スキルの差ではありません。
+- 「エージェントが間違ったアクションを呼び出しているか、パラメーターを誤って使用しています。」→修正: パラメーターのアクションの `description` および `.describe()` を改善します。これはツールの説明の修正であり、スキルではありません。
+
+## 何がどこに行くのか {#what-goes-where}
+
+- **AGENTS.md** — 毎ターン、アプリ全体に適用されます: 目的、コアルール、状態キー、アクションインデックス、skills インデックス。
+- **Skills** — オンデマンドでロードされる、特定のパターンの再利用可能なハウツー。アプリで作業している全員に適用されます。
+- **メモリ (`memory/MEMORY.md`)** — ユーザーごとの設定と修正。作成されたガイダンスではありません。
+
+## 次は何ですか {#whats-next}
+
+- [Skills Guide](/docs/skills-guide) — スキル ファイル形式、フレームワーク skills、およびアプリベースの skills。
+- [Creating Templates](/docs/creating-templates) — `AGENTS.md` と skills を出荷可能なテンプレートにどのように適合させるか。
+- [The four-area checklist](/docs/key-concepts#four-area-checklist) — すべての特徴が満たさなければならない 4 エリア モデル。