snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/ja/developers/extend/apps/getting-started/concepts.mdx

@@ -0,0 +1,102 @@
+---
+title: 概念
+description: Twenty アプリの動作 — エンティティモデル、サンドボックス化、およびインストールライフサイクル。
+icon: sitemap
+---
+
+Twenty アプリは、カスタムオブジェクト、ロジック、UI コンポーネント、AI 機能でワークスペースを拡張する TypeScript パッケージです。 それらは、完全なサンドボックス化と権限制御のもとで Twenty プラットフォーム上で実行されます。
+
+## アプリの仕組み
+
+アプリは、`twenty-sdk` パッケージの `defineEntity()` 関数を使って宣言された**エンティティ**の集合です。 SDK はビルド時に AST 解析によってこれらの宣言を検出し、**マニフェスト**を生成します—アプリがワークスペースに追加する内容を完全に記述したものです。 これらの関数はビルド時に設定を検証し、IDE の自動補完と型安全性を提供します。
+
+```
+your-app/
+├── src/
+│   ├── application-config.ts    ← defineApplication (required, one per app)
+│   ├── roles/                   ← defineRole
+│   ├── objects/                 ← defineObject
+│   ├── fields/                  ← defineField
+│   ├── logic-functions/         ← defineLogicFunction
+│   ├── front-components/        ← defineFrontComponent
+│   ├── skills/                  ← defineSkill
+│   ├── agents/                  ← defineAgent
+│   ├── views/                   ← defineView
+│   ├── navigation-menu-items/   ← defineNavigationMenuItem
+│   └── page-layouts/            ← definePageLayout
+├── public/                      ← Static assets (images, icons)
+└── package.json
+```
+
+<Note>
+  **ファイル構成は自由です。** エンティティの検出は AST ベースです—ファイルの場所に関係なく、SDK は `export default defineEntity(...)` の呼び出しを見つけます。 上記のフォルダー構成は慣例であり、必須条件ではありません。
+</Note>
+
+## エンティティタイプ
+
+| エンティティ            | 目的                                                | ドキュメント                                                                                                 |
+| ----------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| **アプリケーション**      | アプリの識別情報、デフォルトロール、変数                              | [Application Config](/l/ja/developers/extend/apps/config/application)                                       |
+| **ロール**           | オブジェクトとフィールドの権限セット                                | [Roles & Permissions](/l/ja/developers/extend/apps/config/roles)                                            |
+| **Object**        | フィールドを持つカスタムレコードタイプ                               | [Objects](/l/ja/developers/extend/apps/data/objects)                                                        |
+| **フィールド**         | 他のアプリのオブジェクトにフィールドを追加                             | [Extending Objects](/l/ja/developers/extend/apps/data/extending-objects)                                    |
+| **リレーション**        | オブジェクト間の双方向リンク                                    | [Relations](/l/ja/developers/extend/apps/data/relations)                                                    |
+| **ロジック関数**        | トリガーを備えたサーバーサイド TypeScript                        | [ロジック関数](/l/ja/developers/extend/apps/logic/logic-functions)                                                |
+| **スキル**           | 再利用可能な AI エージェントの指示                               | [スキルとエージェント](/l/ja/developers/extend/apps/logic/skills-and-agents)                                          |
+| **エージェント**        | カスタムプロンプトを備えた AI エージェント                           | [スキルとエージェント](/l/ja/developers/extend/apps/logic/skills-and-agents)                                          |
+| **接続プロバイダー**      | サードパーティ API 用の OAuth 資格情報                         | [Connections](/l/ja/developers/extend/apps/logic/connections)                                               |
+| **ビュー**           | 事前設定済みのレコード一覧ビュー                                  | [Views](/l/ja/developers/extend/apps/layout/views)                                                          |
+| **ナビゲーションメニュー項目** | カスタムのサイドバー項目                                      | [Navigation Menu Items](/l/ja/developers/extend/apps/layout/navigation-menu-items)                          |
+| **ページレイアウト**      | レコードの詳細ページ上のタブとウィジェット                             | [Page Layouts](/l/ja/developers/extend/apps/layout/page-layouts)                                            |
+| **フロントコンポーネント**   | Twenty 内でサンドボックス化された React UI                     | [フロントコンポーネント](/l/ja/developers/extend/apps/layout/front-components)                                         |
+| **共有依存関係**        | アプリのフロントコンポーネント間で共有される依存関係で、package.json 内で宣言されます | [共有依存関係](/l/ja/developers/extend/apps/layout/front-components#sharing-dependencies-across-front-components) |
+| **コマンドメニュー項目**    | クイックアクションと Cmd+K エントリ                             | [Command Menu Items](/l/ja/developers/extend/apps/layout/command-menu-items)                                |
+
+## サンドボックス化
+
+* **ロジック関数**は、サーバー上の分離された Node.js プロセスで実行されます。 これらは、実行をトリガーしたユーザーまたはアプリ自体として動作する型付き API クライアントを介してのみデータにアクセスします。 [呼び出しで使用されるアクセス権](/l/ja/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses)を参照してください。
+* **フロントコンポーネント**は Remote DOM を用いた Web Workers 内で実行されます—メインページからサンドボックス化されつつ、ネイティブの DOM 要素（iframe ではありません）をレンダリングします。 メッセージパッシング型のホスト API を介して Twenty と通信します。
+* **権限**は API レベルで強制されます。 `defineApplicationRole()` で宣言されたロールから派生した 2 つのランタイムトークンが挿入されます。デフォルトのトークンは、実行の背後にユーザーがいる場合は常に、そのトリガーとなったユーザーが実行できる操作にさらに制限されます。
+
+## アプリのライフサイクル
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Development                                             │
+│   npx create-twenty-app → yarn twenty dev (live sync)   │
+├─────────────────────────────────────────────────────────┤
+│ Build & Deploy                                          │
+│   yarn twenty dev:build → yarn twenty app:publish        │
+├─────────────────────────────────────────────────────────┤
+│ Install flow                                            │
+│   upload → [pre-install] → metadata migration →         │
+│   generate SDK → [post-install] → … → [uninstall]       │
+├─────────────────────────────────────────────────────────┤
+│ Publish                                                 │
+│   npm publish → appears in Twenty marketplace           │
+└─────────────────────────────────────────────────────────┘
+```
+
+* **`yarn twenty dev`** — ソースファイルを監視し、接続された Twenty サーバーへ変更をライブ同期します。 スキーマが変更されると、型付き API クライアントは自動的に再生成されます。
+* **`yarn twenty dev:build`** — TypeScript をコンパイルし、esbuild でロジック関数とフロントコンポーネントをバンドルして、マニフェストを生成します。
+* **プリ/ポストインストールおよびアンインストールフック** — インストール中またはアンインストール直前に実行されるオプションの関数。 詳細は [Install Hooks](/l/ja/developers/extend/apps/config/install-hooks) を参照してください。
+
+## 次のステップ
+
+<CardGroup cols={2}>
+  <Card title="設定" icon="screwdriver-wrench" href="/l/ja/developers/extend/apps/config/overview">
+    アプリの識別情報、デフォルトロール、およびインストールフックとアンインストールフック。
+  </Card>
+  <Card title="データ" icon="database" href="/l/ja/developers/extend/apps/data/overview">
+    オブジェクト、フィールド、および双方向リレーション。
+  </Card>
+  <Card title="ロジック" icon="bolt" href="/l/ja/developers/extend/apps/logic/overview">
+    ロジック関数、スキル、エージェント、OAuth 接続。
+  </Card>
+  <Card title="レイアウト" icon="table-columns" href="/l/ja/developers/extend/apps/layout/overview">
+    ビュー、ナビゲーション、ページレイアウト、フロントコンポーネント。
+  </Card>
+  <Card title="オペレーション" icon="rocket" href="/l/ja/developers/extend/apps/operations/overview">
+    CLI、テスト、リモート、CI、アプリの公開。
+  </Card>
+</CardGroup>

packages/twenty-docs/l/ja/developers/extend/apps/getting-started/local-server.mdx

@@ -0,0 +1,87 @@
+---
+title: ローカルサーバー
+description: ローカルの Twenty Docker サーバーを管理します — 起動、停止、アップグレード、並列テスト用インスタンス、および手動での SDK セットアップ。
+icon: server
+---
+
+## ローカルサーバーの管理
+
+ローカルの Twenty コンテナを操作するには `yarn twenty docker:*` を使用します:
+
+| コマンド                                   | 機能                          |
+| -------------------------------------- | --------------------------- |
+| `yarn twenty docker:start`             | サーバーを起動します（必要に応じてイメージを取得）   |
+| `yarn twenty docker:start 2.2.0`       | 特定のサーバーバージョンを起動する           |
+| `yarn twenty docker:start --port 3030` | カスタムポートで起動                  |
+| `yarn twenty docker:stop`              | サーバーを停止します（データは保持）          |
+| `yarn twenty docker:status`            | URL、バージョン、ログイン資格情報を表示       |
+| `yarn twenty docker:logs`              | サーバーログをストリーム表示              |
+| `yarn twenty docker:reset`             | データを消去してクリーンに開始             |
+| `yarn twenty docker:upgrade`           | `twenty-app-dev` の最新イメージを取得 |
+| `yarn twenty docker:upgrade 2.2.0`     | 特定のバージョンにアップグレードする          |
+
+データは再起動をまたいで、2 つの Docker ボリューム（PostgreSQL 用の `twenty-app-dev-data`、ファイル用の `twenty-app-dev-storage`）に永続化されます。 `reset` を使用して、すべてを消去します。
+
+## サーバーのバージョンを固定する
+
+バージョンが指定されていない場合、`docker:start` は `package.json` 内のアプリの `engines.twenty` の範囲からバージョンを解決します。これは、アプリのインストール時にサーバーが検証に使用する範囲と同じです。 このコマンドは、その範囲を満たす最新の公開済み `twenty-app-dev` イメージを起動し、フィールドが存在しない場合や公開済みバージョンが一致しない場合は `latest` にフォールバックします。
+
+```json filename="package.json"
+{
+  "engines": {
+    "twenty": ">=2.2.0"
+  }
+}
+```
+
+単回の実行でその範囲を上書きするには、バージョンを明示的に指定します: `yarn twenty docker:start 2.3.0`。 すでに別バージョンのコンテナが存在する場合、`docker:start` はその場でアップグレードします（データボリュームを保持したままコンテナを再作成します）。
+
+## サーバーイメージのアップグレード
+
+`yarn twenty docker:upgrade` は最新のイメージを取得してダイジェストを比較し、実際に変更があった場合にのみコンテナを再作成します。 ボリュームは保持されます — 置き換えられるのはコンテナだけです。 新しいイメージが取得され、コンテナが稼働中だった場合、アップグレードは自動的に新しいコンテナを起動します。その後、`yarn twenty docker:start` を実行して、正常稼働になるまで待機します。
+
+```bash filename="Terminal"
+yarn twenty docker:upgrade            # Latest
+yarn twenty docker:upgrade 2.2.0      # Specific version
+```
+
+`yarn twenty docker:status` で実行中のバージョンを確認できます。コンテナの `APP_VERSION` が表示されます。
+
+## テスト用インスタンスを並行実行する
+
+任意の `docker:*` コマンドに `--test` を指定すると、完全に分離された第2のインスタンスを管理できます。統合テストの実行や、メインの開発データに触れることなく試す際に便利です。
+
+| コマンド                                | 機能                               |
+| ----------------------------------- | -------------------------------- |
+| `yarn twenty docker:start --test`   | テスト用インスタンスを起動します（デフォルトはポート2021）。 |
+| `yarn twenty docker:stop --test`    | 停止する                             |
+| `yarn twenty docker:status --test`  | ステータスを表示                         |
+| `yarn twenty docker:logs --test`    | ログをストリーム表示                       |
+| `yarn twenty docker:reset --test`   | データを消去                           |
+| `yarn twenty docker:upgrade --test` | イメージをアップグレード                     |
+
+テスト用インスタンスは、専用のボリューム（`twenty-app-dev-test-data`、`twenty-app-dev-test-storage`）と設定を備えた独自の Docker コンテナ（`twenty-app-dev-test`）内で実行されるため、メインのインスタンスと競合することなく並行して実行できます。 `--test` と `--port` を併用して、2021 を上書きできます。
+
+## 手動セットアップ（スキャフォルダーなし）
+
+既存プロジェクトに SDK を追加する場合はスキャフォルダーを省略します:
+
+```bash filename="Terminal"
+yarn add twenty-sdk twenty-client-sdk
+```
+
+`package.json` にスクリプトを追加します:
+
+```json filename="package.json"
+{
+  "scripts": {
+    "twenty": "twenty"
+  }
+}
+```
+
+これで `yarn twenty dev`、`yarn twenty docker:start` などを実行できます。
+
+<Note>
+`twenty-sdk` をグローバルインストールしないでください — プロジェクトごとに固定し、各アプリがそれぞれのバージョンを使用するようにします。
+</Note>

packages/twenty-docs/l/ja/developers/extend/apps/getting-started/project-structure.mdx

@@ -0,0 +1,79 @@
+---
+title: プロジェクト構成
+description: スキャフォールドされた Twenty アプリに含まれているもの — ファイルやフォルダー、およびそれぞれの役割について説明します。
+icon: folder-tree
+---
+
+`npx create-twenty-app` で生成された新しいアプリは、次のような構成になります。
+
+```text filename="my-twenty-app/"
+my-twenty-app/
+  package.json
+  src/
+    application-config.ts                   # Required — your app's entry point
+    default-role.ts                         # Permissions for logic functions
+    constants/
+      universal-identifiers.ts              # Auto-generated UUIDs and metadata
+    front-components/
+      main-page.tsx                         # Welcome page component
+    navigation-menu-items/
+      main-page.navigation-menu-item.ts     # Sidebar entry for the welcome page
+    page-layouts/
+      main-page.page-layout.ts              # Standalone page hosting the component
+    __tests__/
+      application-config.test.ts            # Unit test
+      global-setup.ts                       # Integration test setup (sync + uninstall)
+      schema.integration-test.ts            # Integration test against a live server
+  .github/workflows/
+    ci.yml                                  # Lint, typecheck, unit + integration tests
+    cd.yml                                  # Deploy + install on push to main
+    publish.yml                             # Publish to npm on version tags (with provenance)
+  public/
+    logo.svg                                # Static assets
+  vitest.config.ts                          # Integration test runner config
+  vitest.unit.config.ts                     # Unit test runner config
+  tsconfig.json, tsconfig.spec.json
+  .nvmrc, .yarnrc.yml, .oxlintrc.json
+  README.md, AGENTS.md, CLAUDE.md, CHANGELOG.md, SETUP.md
+```
+
+## 主要ファイル
+
+| ファイル / フォルダー                                                               | 目的                                                                        |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `src/application-config.ts`                                                | **必須。** アプリのメイン設定ファイルです。                                                  |
+| `src/default-role.ts`                                                      | ロジック関数がアクセスできる範囲を制御するデフォルトのロールです。                                         |
+| `src/constants/universal-identifiers.ts`                                   | 自動生成される UUID とアプリのメタデータ（表示名、説明）。                                          |
+| `src/front-components/`, `src/navigation-menu-items/`, `src/page-layouts/` | スターター用のウェルカムページ：スタンドアロンのページレイアウトによってレンダリングされ、サイドバーからアクセスできるフロントコンポーネントです。 |
+| `src/__tests__/`                                                           | ユニットテストと、（グローバルセットアップ付きで）実際のサーバーに対してアプリを同期する統合テスト。                        |
+| `public/`                                                                  | アプリとともに提供される静的アセット（画像、フォント）。                                              |
+| `AGENTS.md` / `CLAUDE.md`                                                  | アプリ上で作業する AI コーディングエージェント向けのガイダンス。                                        |
+| `CHANGELOG.md` / `SETUP.md`                                                | 主な変更の履歴とローカル開発用のセットアップ手順。                                                 |
+
+<Note>
+**ファイル構成は自由です。** 上記のフォルダーはあくまで慣習であり、SDK はファイルがどこにあっても、`export default defineEntity(...)` 呼び出しに対する AST 解析によってエンティティを検出します。
+</Note>
+
+## 依存関係
+
+Twenty の両方の SDK パッケージは、`dependencies` ではなく `devDependencies` の下に属します。
+
+```json filename="package.json"
+{
+  "dependencies": {},
+  "devDependencies": {
+    "twenty-client-sdk": "2.20.0",
+    "twenty-sdk": "2.20.0",
+    "twenty-ui": "1.0.0-alpha.1"
+  }
+}
+```
+
+スキャフォルダーは `twenty-sdk` と `twenty-client-sdk` を自身のバージョンに固定します — アップグレードする際はこの 2 つを同期させてください。
+
+* **`twenty-sdk`** は、`twenty` CLI とビルド／スキャフォールディング用のツールを提供します。 これは開発時とビルド時にのみ実行され、公開済みアプリのランタイムによってインポートされることは決してありません。
+* **`twenty-client-sdk`** はアプリのコード（`CoreApiClient`、`MetadataApiClient`、`RestApiClient`）によってインポートされますが、Twenty がランタイムで提供します — ロジック関数は生成された SDK レイヤーからそれを取得し、フロントエンドコンポーネントはサーバー提供のモジュールから解決します。 インストール済みのコピーは型チェックとデプロイ時のビルドにのみ使用されるため、デプロイされたバンドルに同梱される必要はありません。
+
+どちらかのパッケージを `dependencies` の下に置いたままだと、インストールされたアプリのランタイムバンドルに取り込まれてしまい、不要な重荷になります。 いずれかがまだ `dependencies` の下にリストされている場合、`twenty dev:build` は警告を出力します。
+
+アプリ独自のランタイム依存関係（ロジック関数が実際にランタイムでインポートするライブラリ）は、通常どおり `dependencies` の下に追加してください。 ツリーを軽量に保ちましょう。`dependencies` は、展開後の上限が 250MB のランタイムレイヤーにインストールされます。それを超えると同期またはインストールは失敗し、`dependencies` のサイズエラーになります。UI ライブラリや開発ツールは `devDependencies` に含めてください。

packages/twenty-docs/l/ja/developers/extend/apps/getting-started/quick-start.mdx

@@ -0,0 +1,166 @@
+---
+title: クイックスタート
+icon: rocket
+description: 数分で最初の Twenty アプリを作成しましょう。
+---
+
+## 前提条件
+
+* **Node.js 24.5+** — [こちらからダウンロード](https://nodejs.org/)
+* **Yarn 4** — Corepack 経由で Node.js に同梱されています。 有効化: `corepack enable`
+* **Docker** — [こちらからダウンロード](https://www.docker.com/products/docker-desktop/)。 ローカルの Twenty サーバーを実行するために必要です。 すでに別の場所で Twenty が稼働している場合はスキップしてください。
+
+Twenty アプリの構築は 3 つのフェーズで構成されます。 スキャフォルダーはそれらをハッピーパスの 1 つのコマンドにまとめますが、各フェーズは別個の概念です — 何かが失敗したとき、いまどのフェーズにいるかが分かると、直すべき箇所が特定できます。
+
+| フェーズ            | やること                    | ツール                                 | 結果                       |
+| --------------- | ----------------------- | ----------------------------------- | ------------------------ |
+| **1. スキャフォールド** | アプリのソースコードを生成する         | `npx create-twenty-app`             | ディスク上の TypeScript プロジェクト |
+| **2. サーバーを起動**  | 同期先となる Twenty サーバーを起動する | Docker + `yarn twenty docker:start` | 稼働中の Twenty インスタンス       |
+| **3. 同期**       | コードをサーバーにライブ同期する        | `yarn twenty dev`                   | 変更が UI に反映されます           |
+
+---
+
+## フェーズ 1 — プロジェクトをスキャフォールドする
+
+テンプレートから新しいアプリを作成します:
+
+```bash filename="Terminal"
+npx create-twenty-app@latest my-twenty-app
+```
+
+スキャフォルダーは非対話型であり、ディレクトリ名がアプリ名になります。 生成されるメタデータをカスタマイズするには、`--display-name` と `--description` を指定します（後から `src/constants/universal-identifiers.ts` 内で編集することもできます）。 これにより、`my-twenty-app/` にスターターの `application-config.ts`、デフォルトロール、CI/CD ワークフロー、および統合テストを含む TypeScript プロジェクトが生成されます。
+
+**このフェーズ後:** マシン上にアプリのソースコードがあります。 まだ実行はされていません — それはフェーズ 2 です。
+
+---
+
+## フェーズ 2 — ローカルの Twenty サーバーを起動する
+
+アプリは同期先としての Twenty サーバーを必要とします。 サーバーは、UI、GraphQL API、PostgreSQL を備えた完全な Twenty インスタンスで、Docker 上でローカルに実行されます。 ローカルのコードは定義をそのサーバーにアップロードし、UI に反映されます。
+
+スキャフォルダーが環境を自動的に起動します。Docker が動作している状態で、`twentycrm/twenty-app-dev` イメージを取得し、ポート `2020` で起動して、事前にデモデータが投入されたワークスペース（`tim@apple.dev`）に対して CLI を認証します — サインインは不要です。
+
+既存の Twenty サーバーに接続する場合は、代わりに `--url \<your-server-url>` を指定してください。 リモートサーバーは OAuth で認証されます。ブラウザーが開き、サインインして **Authorize** をクリックすると、CLI にワークスペースへのアクセス権が付与されます。 （ローカルでも `--authentication-method oauth` を指定して OAuth を利用できます。その場合は `tim@apple.dev` / `tim@apple.dev` でサインインします。）
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/login.png" alt="Twenty のログイン画面" />
+</div>
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/authorize.png" alt="Twenty CLI の承認画面" />
+</div>
+
+ターミナルにセットアップ完了のメッセージが表示されます。
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/scaffolded.png" alt="アプリのスキャフォルドに成功しました。" />
+</div>
+
+**このフェーズ後:** あなたの CLI が同期を許可された Twenty サーバーが [http://localhost:2020](http://localhost:2020) で稼働しています。
+
+<Note>
+Docker がインストールされていない、または起動していない場合、スキャフォルダーが OS に合った開始コマンドを案内します。 Docker が起動したら、`yarn twenty docker:start` で再開できます — 再スキャフォールドは不要です。
+</Note>
+
+---
+
+## フェーズ 3 — 変更を同期する
+
+ここが、最も多くの時間を費やす内側のループです。
+
+```bash filename="Terminal"
+cd my-twenty-app
+yarn twenty dev
+```
+
+これは `src/` を監視し、変更のたびに再ビルドして、その結果をサーバーに同期します。 ファイルを編集して保存すると、数秒以内にサーバーに変更が反映されます。 ターミナルにライブステータスパネルが表示されます。
+
+より詳細な出力（ビルドログ、同期リクエスト、エラートレース）が必要な場合は、`--verbose` フラグを使用します。
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/dev.png" alt="開発モードのターミナル出力" />
+</div>
+
+ブラウザーで [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer) を開きます。 **Your Apps** にアプリが表示されるはずです。
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Your Apps リストに My twenty app が表示されている様子" />
+</div>
+
+**My twenty app** をクリックすると、その **application registration**（アプリを記述するサーバーレベルのレコード。名前、識別子、OAuth 認証情報、ソース）が表示されます。 同一サーバー上では、1 つの登録を複数のワークスペースにインストールできます。
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="アプリケーション登録の詳細" />
+</div>
+
+ワークスペースへのインストールを確認するには **View installed app** をクリックします。 **About** タブには現在のバージョンと管理オプションが表示されます。
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="インストール済みのアプリ" />
+</div>
+
+**このフェーズ後:** ライブな開発ループが確立しています。 `src/` 内の任意のファイルを編集すると、UI に反映されます。
+
+### CI やスクリプト向けの一回限りの同期
+
+ウォッチャーなしで同じパイプラインを 1 回だけ実行するには、`plan` と `apply` を使用します。
+
+```bash filename="Terminal"
+yarn twenty plan   # preview the metadata changes without applying them
+yarn twenty apply  # show the plan, then apply it
+```
+
+| コマンド                | 動作                                                                                          | 使用する場面                                       |
+| ------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `yarn twenty dev`   | ソースファイルを監視し、変更のたびに再同期します。 停止するまで実行し続けます。                                                    | 対話的なローカル開発。                                  |
+| `yarn twenty apply` | ビルドと同期を一度だけ実行し、成功時はコード `0`、失敗時は `1` で終了します。 破壊的な変更がある場合に確認を求めます（スキップするには `--force` を指定します）。 | CI、pre-commit フック、AI エージェント、スクリプト化されたワークフロー。 |
+| `yarn twenty plan`  | メタデータの変更をビルドして出力しますが、**実際には適用しません**。                                                        | 同期によってどのような変更が行われるかを、実行を確定する前に確認します。         |
+
+すべてのモードで、認証済みのリモートが必要です。 `plan` の詳細については、[Syncing & recovery](/l/ja/developers/extend/apps/operations/sync-and-recovery#previewing-changes-plan) を参照してください。
+
+<Note>
+`yarn twenty dev --once` および `yarn twenty dev --once --dry-run` は非推奨であり、それぞれ `yarn twenty apply` および `yarn twenty plan` のエイリアスです。
+</Note>
+
+### Dev モードのオプション
+
+| フラグ                                   | 説明                                        |
+| ------------------------------------- | ----------------------------------------- |
+| `--force`                             | 確認なしで破壊的な変更（削除）を適用します。                    |
+| `--debounceMs \<ms>` | ファイル変更のデバウンス遅延をミリ秒単位で設定します (既定値: `1000`)。 |
+| `--verbose` / `--debug`               | 詳細なビルドログ、同期リクエスト、およびエラートレースを表示します。        |
+
+## 構築できるもの
+
+アプリは**エンティティ**で構成されており、それぞれが単一の `export default` を持つ TypeScript ファイルとして定義されます:
+
+| エンティティ           | 機能                                                               |
+| ---------------- | ---------------------------------------------------------------- |
+| **オブジェクトとフィールド** | カスタムデータモデル（ポストカード、請求書など） 型付きフィールド                                |
+| **ロジック関数**       | HTTP ルート、cron スケジュール、またはデータベースイベントによってトリガーされるサーバーサイドの TypeScript |
+| **フロントコンポーネント**  | Twenty の UI（サイドパネル、ウィジェット、コマンドメニュー）内でレンダリングされる React コンポーネント     |
+| **スキルとエージェント**   | AI 機能 — 再利用可能な指示と自律型アシスタント                                       |
+| **ビューとナビゲーション**  | 事前設定済みのリストビューとサイドバーのメニュー項目                                       |
+| **ページレイアウト**     | タブとウィジェットを備えたカスタムのレコード詳細ページ                                      |
+
+完全なリファレンス: [Concepts](/l/ja/developers/extend/apps/getting-started/concepts)。
+
+## 次のステップ
+
+<CardGroup cols={2}>
+  <Card title="設定" icon="screwdriver-wrench" href="/l/ja/developers/extend/apps/config/overview">
+    アプリケーション ID、デフォルトロール、インストールおよびアンインストールフック、公開アセット。
+  </Card>
+  <Card title="データ" icon="database" href="/l/ja/developers/extend/apps/data/overview">
+    オブジェクト、フィールド、および双方向リレーション。
+  </Card>
+  <Card title="ロジック" icon="bolt" href="/l/ja/developers/extend/apps/logic/overview">
+    ロジック関数、スキル、エージェント、および OAuth 接続。
+  </Card>
+  <Card title="レイアウト" icon="table-columns" href="/l/ja/developers/extend/apps/layout/overview">
+    ビュー、ナビゲーション、ページレイアウト、フロントコンポーネント。
+  </Card>
+  <Card title="オペレーション" icon="rocket" href="/l/ja/developers/extend/apps/operations/overview">
+    CLI、テスト、リモート、CI、およびアプリの公開。
+  </Card>
+</CardGroup>

packages/twenty-docs/l/ja/developers/extend/apps/getting-started/scaffolding.mdx

@@ -0,0 +1,63 @@
+---
+title: スキャフォルディング
+description: yarn twenty dev:add を使用して対話的にエンティティファイルを生成します — オブジェクト、フィールド、ビュー、ロジック関数などを作成できます。
+icon: wand-magic-sparkles
+---
+
+エンティティファイルを手作業で作成する代わりに、対話型スキャフォルダーを使用します：
+
+```bash filename="Terminal"
+yarn twenty dev:add
+```
+
+これによりエンティティタイプの選択を促され、必要なフィールドの設定を順を追って案内されたあと、安定した `universalIdentifier` と正しい `defineEntity()` 呼び出しを含む、すぐに利用できるファイルが作成されます。
+
+最初のプロンプトをスキップするために、エンティティタイプを直接渡すこともできます：
+
+```bash filename="Terminal"
+yarn twenty dev:add object
+yarn twenty dev:add logicFunction
+yarn twenty dev:add frontComponent
+```
+
+## 利用可能なエンティティタイプ
+
+| エンティティタイプ     | コマンド                                       | 生成されたファイル                                                 |
+| ------------- | ------------------------------------------ | --------------------------------------------------------- |
+| オブジェクト        | `yarn twenty dev:add object`               | `src/objects/\<name>.ts`                 |
+| フィールド         | `yarn twenty dev:add field`                | `src/fields/\<name>.ts`                  |
+| ロジック関数        | `yarn twenty dev:add logicFunction`        | `src/logic-functions/\<name>.ts`         |
+| フロントコンポーネント   | `yarn twenty dev:add frontComponent`       | `src/front-components/\<name>.tsx`       |
+| ロール           | `yarn twenty dev:add role`                 | `src/roles/\<name>.ts`                   |
+| スキル           | `yarn twenty dev:add skill`                | `src/skills/\<name>.ts`                  |
+| エージェント        | `yarn twenty dev:add agent`                | `src/agents/\<name>.ts`                  |
+| ビュー           | `yarn twenty dev:add view`                 | `src/views/\<name>.ts`                   |
+| ナビゲーションメニュー項目 | `yarn twenty dev:add navigationMenuItem`   | `src/navigation-menu-items/\<name>.ts`   |
+| ページレイアウト      | `yarn twenty dev:add pageLayout`           | `src/page-layouts/\<name>.ts`            |
+| ページレイアウトタブ    | `yarn twenty dev:add pageLayoutTab`        | `src/page-layout-tabs/\<name>.ts`        |
+| コマンドメニュー項目    | `yarn twenty dev:add commandMenuItem`      | `src/command-menu-items/\<name>.ts`      |
+| ビューフィールド      | `yarn twenty dev:add viewField`            | `src/view-fields/\<name>.ts`             |
+| 接続プロバイダー      | `yarn twenty dev:add connectionProvider`   | `src/connection-providers/\<name>.ts`    |
+| タイムライン活動タイプ   | `yarn twenty dev:add timelineActivityType` | `src/timeline-activity-types/\<name>.ts` |
+
+## スキャフォルダーが生成するもの
+
+各エンティティタイプには固有のテンプレートがあります。 例えば、`yarn twenty dev:add object` は次の項目の入力を求めます：
+
+1. **名前（単数）** — 例：`invoice`
+2. **名前（複数）** — 例：`invoices`
+3. **ラベル（単数）** — 名前から自動入力（例：`Invoice`）
+4. **ラベル（複数）** — 自動入力（例：`Invoices`）
+5. **ビューとナビゲーション項目を作成しますか？** — はいと回答すると、スキャフォルダーは新しいオブジェクトに対応するビューとサイドバーリンクも生成します。
+
+他のエンティティタイプはより簡単なプロンプトで、ほとんどは名前のみを尋ねます。
+
+`field` エンティティタイプはより詳細で、フィールド名、ラベル、タイプ（`TEXT`、`NUMBER`、`SELECT`、`RELATION` など、利用可能なすべてのフィールドタイプのリストから選択）、および対象オブジェクトの `universalIdentifier` を尋ねます。
+
+## 出力パスのカスタマイズ
+
+`--path` フラグを使用して、生成ファイルをカスタムの場所に配置します：
+
+```bash filename="Terminal"
+yarn twenty dev:add logicFunction --path src/custom-folder
+```

packages/twenty-docs/l/ja/developers/extend/apps/getting-started/troubleshooting.mdx

@@ -0,0 +1,14 @@
+---
+title: トラブルシューティング
+description: 初回実行時によく発生する問題 — Docker、Node のバージョン、Yarn、依存関係。
+icon: wrench
+---
+
+* **Docker のエラー** — `yarn twenty docker:start` の前に Docker Desktop（またはデーモン）が起動していることを確認してください。 エラーメッセージに、OS に適した起動コマンドが表示されます。
+* **誤った Node のバージョン** — 24.5 以上が必要です（`engines.node: ^24.5.0`）。 `node -v` で確認してください。
+* **Yarn 4 が見つからない** — `corepack enable` を実行してください。
+* **依存関係の破損** — `rm -rf node_modules && yarn install`。
+* **`twenty-sdk` が v2.8.0 へのアップグレード後にエラーになる** — v2.8.0 で `dependencies` から `devDependencies` に移動しました。 [Project Structure → Dependencies](/l/ja/developers/extend/apps/getting-started/project-structure#dependencies) を参照してください。
+* **`twenty dev:build` は `dependencies` 配下の `twenty-client-sdk` について警告します** — これは Twenty によって実行時に提供されるため、`twenty-sdk` と同様に `devDependencies` へ移動する必要があります。 [Project Structure → Dependencies](/l/ja/developers/extend/apps/getting-started/project-structure#dependencies) を参照してください。
+
+行き詰まりましたか？ [Twenty の Discord](https://discord.com/channels/1130383047699738754/1130386664812982322)でヘルプを依頼してください。