@orizm/cli 3.1.0 → 3.3.0-beta.0

package/dist/docs/get-started/get-started-with-starter.md

@@ -0,0 +1,218 @@
+<!-- source: docs/src/app/get-started/get-started-with-starter/page.mdx -->
+
+# Starter ではじめる
+
+このドキュメントはCMSやWebサイトの開発者向けガイドです。開発者コンソールから新しいプロジェクトを立ち上げ、CMSとWebサイトをOrizmに接続する手順を説明します。
+
+> [!NOTE]
+> 以降の作業には開発者コンソールへのログインが必要です。
+> サポートチームに連絡するか、サインアップ済みのメンバーから招待を受けてください。
+
+## プロジェクトの作成
+
+ブラウザで [開発者コンソール](https://app.orizm.com) にアクセスします。
+
+ログインすると現在のプロジェクト一覧が表示されます。
+
+![プロジェクト一覧画面](./developer-console-organization-projects.png)
+
+**New project** をクリックしてプロジェクトを作成します。
+
+![プロジェクトの作成ダイアログ](./developer-console-create-project.png)
+
+Nameはプロジェクトの識別子です。すべてのOrizmプロジェクトで一意となり、作成後は変更できません。
+
+**Create** をクリックしてプロジェクトを作成します。
+
+## Starterのセットアップ
+
+プロジェクトのホームにStarterをダウンロードする手順が記載されています。この手順に従ってStarterをダウンロードします。ダウンロードしたZIPファイルを任意のディレクトリに展開します。
+
+次にStarterに必要な依存パッケージをインストールします。
+
+```sh copy
+pnpm install --frozen-lockfile
+```
+
+## プロジェクトの設定
+
+作成したプロジェクトの設定を行います。
+
+1. プロジェクトページのSettingsタブを開く
+1. GeneralセクションのCMS SettingsのCMS URLに `http://localhost:3000` を設定
+1. 続けてAllow Originsに `http://localhost:3000` を追加
+1. Saveをクリックして設定を保存
+
+![CMS Settings](./project-settings.png)
+
+## 環境変数の設定
+
+Starterに環境変数を設定し、プロジェクトに接続します。
+
+### Orizm CLI
+
+Orizm CLIはプロジェクトのデータベースやバケット、認可ルールなどの設定を適用するために使用します。
+
+`packages/orizm/.env.local` ファイルを作成し、以下の内容を設定します。
+
+```sh copy filename="packages/orizm/.env.local"
+ORIZM_BASE_URL=https://app.orizm.com
+ORIZM_API_KEY=<Developer API Key>
+ORIZM_PROJECT=<あなたのプロジェクト名>
+```
+
+#### API キー
+
+CLI が使う Developer API Key を生成します。
+
+開発者コンソールでプロジェクトを開き **Settings** から **Developer Keys** を開くことでキーの管理ができます。新しい Developer API Key を作成して環境変数にセットしてください。
+
+#### プロジェクト名
+
+開発者コンソールでプロジェクトを開き **Settings** の **Project Name** セクションを確認します。ここに正確なプロジェクト名が表示されています。
+
+### CMS
+
+`apps/cms/.env.local` ファイルを以下の内容で作成します。
+
+```sh copy filename="apps/cms/.env.local"
+NEXT_PUBLIC_VERCEL_ENV=development
+NEXT_PUBLIC_CONSUMER_ORIGIN=http://localhost:3001
+NEXT_PUBLIC_ORIZM_BASE_URL=https://app.orizm.com
+NEXT_PUBLIC_ORIZM_PROJECT=<あなたのプロジェクト名>
+ORIZM_CLIENT_ID=<Orizm Console から OAuth Client ID を取得>
+ORIZM_CLIENT_SECRET=<Orizm Console から OAuth Client Secret を取得>
+ORIZM_CONSUMER_CMS_COMMUNICATION_KEY=local
+NEXTAUTH_SECRET=<ランダムな文字列を設定>
+```
+
+> [!WARNING]
+> __`ORIZM_CONSUMER_CMS_COMMUNICATION_KEY` に関する注意事項__
+>
+> この環境変数はCMSとConsumerの両方で設定します。どちらも必ず同じ値を設定してください。デフォルトでは `consumer_cms_communication_key` という値が使用されます。本番環境にデプロイする際はデフォルト値ではなくランダムな文字列を使用してください。
+>
+> ```sh copy filename="ランダム文字列の生成"
+> openssl rand -base64 32
+> ```
+>
+
+このほかにどのような環境変数があるのか知りたい場合は `apps/cms/src/env.ts` を参照してください。
+
+#### OAuth Client の設定
+
+CMSにログインするために必要な設定をします。
+
+開発者コンソールでプロジェクトを開き **Settings** の **OAuth Clients** を開きます。ここで OAuth2.0 クライアントの管理ができます。
+
+クライアント **Default OAuth2.0 Client** を開き **Client ID** と **Client Secret** をそれぞれ環境変数 `ORIZM_CLIENT_ID` と `ORIZM_CLIENT_SECRET` にセットしてください。
+
+**Redirect URIs** のセクションにOAuth2認証後に呼び出されるコールバックURLを記述して **Save** で保存してください。ローカル開発環境の場合は `http://localhost:3000/api/auth/callback/Orizm` のように指定します。
+
+### Consumer
+
+Webサイトのための環境変数を設定します。
+
+OrizmではWebサイトのように、CMSからコンテンツを取得するアプリケーションやAPIを _Consumer_ と呼びます。
+
+`apps/consumer/.env.local` ファイルを以下の内容で作成します。
+
+```sh copy filename="apps/consumer/.env.local"
+NEXT_PUBLIC_VERCEL_ENV=<development>
+NEXT_PUBLIC_CMS_ORIGIN=http://localhost:3000
+NEXT_PUBLIC_ORIZM_BASE_URL=https://app.orizm.com
+NEXT_PUBLIC_ORIZM_PROJECT=<あなたのプロジェクト名>
+ORIZM_CONSUMER_KEY=<Orizm Console から Consumer API Key を取得>
+ORIZM_BASIC_AUTH_USER=<Basicを設定する際のID>
+ORIZM_BASIC_AUTH_PASS=<Basicを設定する際のパスワード>
+ORIZM_WEBHOOK_KEY=local
+ORIZM_CONSUMER_CMS_COMMUNICATION_KEY=local
+```
+
+このほかにどのような環境変数があるのか知りたい場合は `apps/consumer/src/env.ts` を参照してください。
+
+#### Consumer API Key を取得
+
+WebサイトからOrizmに保存されたコンテンツにアクセスするには Consumer API Key が必要です。
+
+開発者コンソールでプロジェクトを開き **API Keys** から **Orizm Keys** を開くことでキーの管理ができます。
+
+新しい Consumer API Key を作成します。作成前に `Allow reading draft content with this key` にチェックを入れます。このオプションが有効なAPI Keyは下書きコンテンツにアクセスできます。
+
+![Consumer API Key を取得する](./developer-console-create-consumer-key.png)
+
+作成したAPI Keyを環境変数 `ORIZM_CONSUMER_KEY` にセットしてください。
+
+> [!WARNING]
+> `Allow reading draft content with this key`
+> が有効なキーはサーバーサイドで使用してください。クライアントサイドで使用するとブラウザの開発者ツールなどを通してWebサイトの閲覧者にキーが漏洩します。クライアントサイドからコンテンツへアクセスする場合は下書きコンテンツへのアクセス権が無効なキーを使用してください。
+
+## プロジェクトにスキーマを適用
+
+CMSやWebサイトを立ち上げる前に、プロジェクト上にデータベースやバケット、アクセス権限を適用します。
+
+Orizmでは特別な設定ファイル `orizm.config.ts` でデータベースのテーブルやデータ構造などのスキーマを定義します。CLIでそれらの設定をプロジェクトに適用します。
+
+以下のコマンドを実行して、プロジェクトにスキーマを適用します。
+
+```sh copy
+pnpm run orizm:push
+```
+
+成功するとStarterの動作に必要なデータベースが作成されます。開発者コンソールの **Tables** を開くとテーブルを確認できます。
+
+同時に先ほどのコマンドでスキーマに基づいてTypeScriptの型定義やクライアントコードが生成されます。このコードを使用することでタイプセーフな開発が可能です。
+
+スキーマの適用はせずにコード生成のみ実行する方法もあります。
+
+```sh copy
+pnpm run orizm:gen
+```
+
+Starter では `packages/orizm` ディレクトリに配置されたサブパッケージ `@repo/orizm` でプロジェクトのスキーマを管理しています。モノレポの仕組みを通じてCMSやConsumerからこれらを参照します。
+
+## AIコーディングエージェントの設定（任意）
+
+Claude Code などの AI コーディングエージェントを併用する場合は、次のコマンドでエージェント向けの設定を行えます。
+
+```sh copy
+pnpm exec orizm agent init
+```
+
+これにより、プロジェクトルートの `AGENTS.md` と `CLAUDE.md` に Orizm ドキュメントへの参照が設定されます。エージェントは、プロジェクトで使っている `@orizm/cli` のバージョンと整合したドキュメントを参照し、Orizm の SDK・CLI・フォルダ規約に沿ったコードを生成できるようになります。
+
+> [!NOTE]
+> ドキュメントのURLを毎回貼る手間なく、最初から規約に沿ったコード生成が期待できます。詳しくは [agent コマンド](../features/cli/commands/agent.md) を参照してください。
+
+## Starterを起動
+
+Starterを起動します。以下のコマンドで開発サーバーを実行します。
+
+```sh copy
+pnpm run dev
+```
+
+起動するとポート `3000` でCMSに、`3001` でConsumerにアクセスできるようになります。
+
+| Apps     | URL                   |
+| -------- | --------------------- |
+| CMS      | http://localhost:3000 |
+| Consumer | http://localhost:3001 |
+
+## 招待とログイン
+
+CMSにログインするにはアカウントが必要です。
+
+開発者コンソールでプロジェクトを開き **Users** タブに移動します。CMSにログインするためのアカウントを管理できます。
+
+あなたのメールアドレスで新しいユーザーを作成してください。
+
+> [!NOTE]
+> Orizmでは開発者コンソールにログインできる開発者アカウントと、CMSにログインできるユーザーアカウントを別のアカウントとして管理しています。
+> 詳しくは [ユーザーモデル](../resources/user-model.md)
+> についてのページを参照してください。
+
+## 次は
+
+Orizmを利用した開発の準備が整いました。
+
+CMSやWebサイトをさらにカスタマイズしたり、好きなホスティング環境にデプロイしてください。

package/dist/docs/index.md

@@ -0,0 +1,89 @@
+# Orizm docs (v3.3.0-beta.0)
+
+Bundled Orizm docs, version-matched to the installed `@orizm/cli`.
+Read the relevant page before generating Orizm code. Files are relative to this directory.
+
+Starter Kit v2: edit only `apps/cms`, `apps/consumer`, `packages/design-editor`.
+`packages/orizm` is generated from `orizm.config.ts` — never edit it by hand.
+
+## features
+
+- [Orizm CLI](./features/cli.md)
+- [認証](./features/cli/authentication.md)
+- [コマンドリファレンス](./features/cli/commands.md)
+- [agent — AI コーディングエージェント連携](./features/cli/commands/agent.md)
+- [auth — サインイン](./features/cli/commands/auth.md)
+- [bucket — バケット](./features/cli/commands/bucket.md)
+- [codegen — コード生成](./features/cli/commands/codegen.md)
+- [content — コンテンツ](./features/cli/commands/content.md)
+- [key — APIキー](./features/cli/commands/key.md)
+- [link — プロジェクトのリンク](./features/cli/commands/link.md)
+- [org — 組織](./features/cli/commands/org.md)
+- [project-user — プロジェクトユーザー](./features/cli/commands/project-user.md)
+- [project — プロジェクト](./features/cli/commands/project.md)
+- [schema — スキーマ定義](./features/cli/commands/schema.md)
+- [webhook — Webhook](./features/cli/commands/webhook.md)
+- [環境変数と接続先](./features/cli/configuration.md)
+- [出力とスクリプティング](./features/cli/output.md)
+- [プロジェクトのリンク](./features/cli/project-linking.md)
+- [クイックスタート](./features/cli/quickstart.md)
+- [アカウントの操作](./features/cms-sdk/account.md)
+- [認証](./features/cms-sdk/auth.md)
+- [バケットの操作](./features/cms-sdk/bucket.md)
+- [CMS CLI](./features/cms-sdk/cli.md)
+- [コンテンツの取得](./features/cms-sdk/fetch-contents.md)
+- [CMS SDKのインストール](./features/cms-sdk/install.md)
+- [プロジェクトユーザーの管理](./features/cms-sdk/management-user.md)
+- [CMS SDK v2 への移行](./features/cms-sdk/migrate-to-v2.md)
+- [コンテンツの操作](./features/cms-sdk/mutation-contents.md)
+- [開発者コンソールとは](./features/console.md)
+- [監査ログ](./features/console/audit-logs.md)
+- [バケット](./features/console/bucket.md)
+- [プロジェクトの作成](./features/console/create-project.md)
+- [APIキーの生成](./features/console/generate-api-key.md)
+- [プロジェクトユーザー管理](./features/console/invite-project-users.md)
+- [テーブルの管理](./features/console/management-tables.md)
+- [組織メンバーの管理](./features/console/organization-member-management.md)
+- [スキーマ履歴管理](./features/console/schema-history.md)
+- [Consumer CLI](./features/consumer-sdk/cli.md)
+- [コンテンツの取得](./features/consumer-sdk/fetch-contents.md)
+- [Consumer SDKのインストール](./features/consumer-sdk/install.md)
+- [CMS SDK v2 への移行](./features/consumer-sdk/migrate-to-v2.md)
+- [デザインエディターとは](./features/design-editor/about.md)
+- [はじめに](./features/design-editor/getting-started.md)
+- [インストール](./features/design-editor/install.md)
+- [プロパティエディター](./features/design-editor/prop-editor.md)
+- [スキーマ定義ガイド](./features/design-editor/schema.md)
+- [検索辞書](./features/dictionary.md)
+- [下書き管理](./features/draft.md)
+- [フォーム管理の概要](./features/form/about.md)
+- [フォームエディター](./features/form/editor.md)
+- [受信データの管理](./features/form/submission.md)
+- [全文検索](./features/full-text-search.md)
+- [履歴管理](./features/history.md)
+- [スキーマとは](./features/schema/about.md)
+- [権限](./features/schema/authority.md)
+- [バケット](./features/schema/bucket.md)
+- [データベース](./features/schema/database.md)
+- [テーブルモジュール](./features/schema/table-module.md)
+- [Webhook](./features/webhook.md)
+- [Next.js でキャッシュを再検証する](./features/webhook/revalidate-nextjs.md)
+
+## get-started
+
+- [モデルを追加する](./get-started/add-model-starter.md)
+- [Starter ではじめる](./get-started/get-started-with-starter.md)
+
+## overview
+
+- [Introduction](./introduction.md)
+
+## resources
+
+- [CLI移行ガイド (SDK CLI → v2)](./resources/cli-migration-guide.md)
+- [CLI移行ガイド (v2→v3)](./resources/cli-v2-to-v3-migration-guide.md)
+- [Vercelへデプロイ](./resources/deploy-to-vercel.md)
+- [制限事項](./resources/limits.md)
+- [プライベートレジストリ](./resources/private-registry.md)
+- [Orizm の稼働状況](./resources/status.md)
+- [Orizm のユーザーモデル](./resources/user-model.md)

package/dist/docs/introduction.md

@@ -0,0 +1,140 @@
+<!-- source: docs/src/app/page.mdx -->
+
+# Introduction
+
+Orizm は CMS構築を強力にサポートするための BaaS (Backend as a Service) とライブラリの集合です。
+
+Orizm を使ってCMSを構築することで、CMS利用者に対して、SaaS型のヘッドレスCMSよりも最適化された編集体験を提供することができます。
+
+また、開発者は、フルスクラッチでCMSを構築する場合と比べて、より短時間でCMSの開発が行えます。また、データベース、フォーム、検索システムなど、サイト構築に必要なリソースを一箇所に集約することができます。
+
+## Orizmのアーキテクチャ
+
+Orizmは、複数のアプリケーションが連携して動作するシステムです。以下に主要なアプリケーションとその関係性を説明します。
+
+```mermaid
+flowchart TB
+    subgraph Orizm["Orizm (BaaS)"]
+        Database["Database<br/>(テーブル)"]
+        Bucket["Bucket<br/>(ストレージ)"]
+        Auth["Auth<br/>(認証)"]
+    end
+
+    subgraph Console[" "]
+        ConsoleLabel["Console<br/>(開発者向けコンソール)"]
+        CLI["@orizm/cli"]
+        ConsoleLabel ~~~ CLI
+    end
+
+    subgraph CMS[" "]
+        CMSLabel["CMS<br/>(編集画面)"]
+        CMSSDK["@orizm/cms-sdk"]
+        CMSLabel ~~~ CMSSDK
+    end
+
+    subgraph Consumer[" "]
+        ConsumerLabel["Consumer<br/>(公開サイト)"]
+        ConsumerSDK["@orizm/consumer-sdk"]
+        ConsumerLabel ~~~ ConsumerSDK
+    end
+
+    Developer["開発者"]
+    CMSUser["CMS利用者"]
+    Visitor["サイト閲覧者"]
+
+    Developer --> Console
+    CMSUser --> CMS
+    Visitor --> Consumer
+
+    Console --> Orizm
+    CMS -->|Management API| Orizm
+    Consumer -->|Consumer API| Orizm
+```
+
+### Orizm (BaaS)
+
+Orizmの中核となるバックエンドサービスです。以下の機能を提供します。
+
+- **Database**: コンテンツを保存するためのテーブル
+- **Bucket**: 画像やファイルを保存するためのストレージ
+- **Auth**: ユーザー認証・認可機能
+- **Webhook**: コンテンツ更新時の通知機能
+- **全文検索**: コンテンツの検索機能
+
+開発者は `orizm.config.ts` でスキーマ（テーブル構造、バケット、権限など）を定義し、CLIを使ってOrizmに適用します。
+
+### Console（開発者コンソール）
+
+[開発者コンソール](https://app.orizm.com)は、開発者向けの管理ツールです。
+
+**主な機能:**
+
+- プロジェクトの作成・管理
+- スキーマ（テーブル・バケット）の確認
+- APIキーの発行・管理
+- CMS利用者アカウントの管理
+
+開発者コンソールは技術者向けのツールであり、CMS利用者が直接使用することは想定されていません。
+
+### CMS（編集画面）
+
+CMSは、コンテンツ編集者（CMS利用者）向けのWebアプリケーションです。開発者がカスタマイズして構築します。
+
+**主な機能:**
+
+- コンテンツの作成・編集・削除
+- 下書き・公開のワークフロー管理
+- 画像・ファイルのアップロード
+- CMS利用者の管理（権限がある場合）
+
+**使用するSDK:** `@orizm/cms-sdk`
+
+**使用するAPI:** Management API
+
+CMS SDKは認証されたCMS利用者のセッション、またはManagement API Keyを使ってOrizmにアクセスします。コンテンツの読み取りだけでなく、作成・更新・削除も可能です。
+
+### Consumer（公開サイト）
+
+Consumerは、一般のサイト閲覧者向けに公開コンテンツを配信するWebサイトやアプリケーションです。
+
+**主な機能:**
+
+- 公開済みコンテンツの表示
+- 全文検索
+- フォームからのデータ送信
+
+**使用するSDK:** `@orizm/consumer-sdk`
+
+**使用するAPI:** Consumer API
+
+Consumer SDKはConsumer API Keyを使ってOrizmにアクセスします。コンテンツの読み取り専用であり、更新機能はありません。これにより、万が一APIキーが露出した場合でも、コンテンツが改ざんされるリスクを軽減できます。
+
+### CMS SDKとConsumer SDKの違い
+
+| 項目                   | CMS SDK                                  | Consumer SDK                   |
+| ---------------------- | ---------------------------------------- | ------------------------------ |
+| パッケージ名           | `@orizm/cms-sdk`                         | `@orizm/consumer-sdk`          |
+| 対象ユーザー           | CMS利用者（編集者）                      | サイト閲覧者                   |
+| 認証方法               | ユーザーセッション or Management API Key | Consumer API Key               |
+| 下書きコンテンツ       | デフォルトで取得可能                     | オプションで取得可能（要権限） |
+| コンテンツの作成・更新 | 可能                                     | 不可                           |
+| 用途                   | CMS編集画面                              | 公開サイト                     |
+
+### ユーザーモデル
+
+Orizmでは、開発者アカウントとCMS利用者アカウントを完全に分離して管理しています。これにより、複雑な権限管理を避けて高いセキュリティを実現しています。
+
+詳細は[ユーザーモデル](./resources/user-model.md)を参照してください。
+
+## スターターキット
+
+Orizmでは、SDKを利用してCMSやConsumerを0から開発することも可能ですが、CMSやConsumer開発に必要なセットアップが完了した状態の**スターターキット**を利用して開発することができます。
+スターターキットの利用を公式では推奨しています。
+
+詳細は[スターターキット](./get-started/get-started-with-starter.md)を参照してください。
+
+## このドキュメントの目的
+
+このドキュメントは、Orizmを利用してCMSやサイトを構築する **開発者** のガイドとなることを目的としています。
+
+Starterプロジェクトを使って最初のOrizmベースのCMSと、サイトを立ち上げる手順を示します。その他、よりカスタマイズするために、各機能の詳細を解説しています。

package/dist/docs/manifest.json

@@ -0,0 +1,6 @@
+{
+  "version": "3.3.0-beta.0",
+  "generatedAt": "2026-09-10T05:03:49.643Z",
+  "pages": 70,
+  "source": "orizm-docs"
+}

package/dist/docs/resources/cli-migration-guide.md

@@ -0,0 +1,82 @@
+<!-- source: docs/src/app/resources/cli-migration-guide/page.mdx -->
+
+# CLI移行ガイド (SDK CLI → v2)
+
+このガイドでは @orizm/cms-sdk や @orizm/consumer-sdk に同梱されている CLI から @orizm/cli (v2) に移行する方法を説明します。
+
+> [!NOTE]
+> このガイドは **Orizm CLI v2** への移行を説明します。Orizm CLI を v2 から v3 へ移行する場合は [CLI移行ガイド (v2→v3)](./cli-v2-to-v3-migration-guide.md) を参照してください。
+
+## 新しいCLIのインストール
+
+このガイドは v2 への移行を扱うため、バージョンを明示して v2 をインストールします（最新版は v3 です）。
+
+```sh npm2yarn copy
+npm install @orizm/cli@2 --save-dev
+```
+
+@orizm/cli については、[CLI](../features/cli.md) を参照してください。
+
+## 破壊的変更
+
+### コマンドの変更
+
+CLI のコマンドは以下のように変更されました。
+
+| 旧コマンド              | 新コマンド              |
+| ----------------------- | ----------------------- |
+| orizm-cms update        | orizm push              |
+| orizm-cms generate      | orizm cms generate      |
+| orizm-consumer generate | orizm consumer generate |
+| orizm-consumer pull     | orizm consumer pull     |
+
+### orizm-cms update コマンド
+
+`orizm-cms update` コマンドは、CMS のデータを Orizm にプッシュするためのコマンドでした。このコマンドは `orizm push` コマンドに置き換えられました。
+
+新しい push コマンドでは以下のように挙動が変更されます。
+
+- これまでの `orizm-cms update` コマンドでは、プロジェクトへスキーマを適用するとともに、CMS向けのクライアントや型定義のコード生成を行っていました。
+- 新しい `orizm push` コマンドでは、Orizmプロジェクトへスキーマを適用することに特化し、CMS向けのクライアントや型定義のコード生成は行いません。
+- CMS向けのクライアントや型定義のコード生成を行う場合は、`orizm cms generate` コマンドを使用する必要があります。
+
+例えば、これまで npm-scripts で以下のように `orizm-cms update` コマンドを実行していた場合、
+
+```json filename="package.json"
+{
+  "scripts": {
+    "orizm:update": "orizm-cms update"
+  }
+}
+```
+
+これをこれまでと同じ挙動に保ちたい場合は、以下のように変更します。
+
+```json filename="package.json"
+{
+  "scripts": {
+    "orizm:update": "orizm push && orizm cms generate"
+  }
+}
+```
+
+### orizm-consumer pull コマンド
+
+`orizm-consumer pull` コマンドは、プロジェクトの最新のスキーマをもとに、Consumer向けのクライアントや型定義を生成するためのコマンドでした。
+このコマンドは `orizm consumer pull` コマンドに置き換えられました。
+
+新しい `orizm consumer pull` コマンドでは、以下のように挙動が変更されます。
+
+- これまでは環境変数 `ORIZM_CONSUMER_KEY` に Consumer APIキーを指定する必要がありました。
+- 新しい `orizm consumer pull` コマンドでは環境変数 `ORIZM_CONSUMER_KEY` の代わりに、 `ORIZM_API_KEY` に **Developer APIキー** を指定します。
+
+### 環境変数ファイルのデフォルトパス
+
+これまでSDK同梱のCLIでは以下のように、環境変数ファイルのデフォルトパスが決まっていました。
+
+| SDK                 | 環境変数ファイルのデフォルトパス |
+| ------------------- | -------------------------------- |
+| @orizm/cms-sdk      | `./.env.x.local`                 |
+| @orizm/consumer-sdk | `./.env.x-consumer-cli.local`    |
+
+新しいCLIでは、`./.env` がデフォルトパスになります。

package/dist/docs/resources/cli-v2-to-v3-migration-guide.md

@@ -0,0 +1,138 @@
+<!-- source: docs/src/app/resources/cli-v2-to-v3-migration-guide/page.mdx -->
+
+# CLI移行ガイド (v2→v3)
+
+このガイドでは @orizm/cli v2 から v3 への移行方法を説明します。
+
+> [!WARNING]
+> v3 には破壊的変更が含まれます。OAuth2 認証への移行、`.env`
+> ファイルの自動読み込み廃止、プロジェクトコンテキストの `.orizm/project.json`
+> への移行、コマンド体系の変更、生成コードの構造変更（`types.ts`
+> の廃止）が行われました。
+
+## `orizm auth login` への切替
+
+v3 では OAuth2 認証が基本になります。ブラウザでログインし、トークンをローカルに保存して以降のコマンドで利用します。
+
+### ログインする
+
+```sh copy
+orizm auth login
+```
+
+デフォルトブラウザが起動して認証画面が開きます。認証が完了すると、トークンが `~/.config/orizm/auth.json`（Windows は `%APPDATA%/orizm/auth.json`）に保存されます。
+
+### ログイン状態を確認する
+
+```sh copy
+orizm auth status
+```
+
+ログイン中のユーザーや接続先を表示します。
+
+### ログアウトする
+
+```sh copy
+orizm auth logout
+```
+
+ローカルのトークンを破棄します。
+
+## `.env` の自動読み込み廃止と API キーの継続利用
+
+v2 では CLI が `.env` ファイルを自動で読み込んでいましたが、v3 では **`.env` の自動読み込みを廃止** しました。
+
+CI や自動化スクリプトで API キーを使い続ける場合は、`ORIZM_API_KEY` を環境変数として明示的に設定してください。OAuth2 トークンが存在しない場合に API キー認証へフォールバックします。
+
+GitHub Actions では次のように設定します。
+
+```yaml copy filename=".github/workflows/example.yml"
+- run: orizm schema push --yes
+  env:
+    ORIZM_API_KEY: ${{ secrets.ORIZM_API_KEY }}
+```
+
+ローカルで引き続き `.env` を使いたい場合は、`dotenv-cli` や `direnv` などのラッパーを利用してください。
+
+```sh copy
+dotenv -e .env -- orizm schema push
+```
+
+## `.orizm/project.json` への移行
+
+v3 ではプロジェクトコンテキストを `.orizm/project.json` で管理します（Vercel CLI の `vercel link` と同じ方式）。
+
+`orizm link` を実行すると、所属する Organization と Project を対話的に選択して `.orizm/project.json` を生成します。初回実行時には `.gitignore` への `.orizm/` の追記を促されます。
+
+```sh copy
+orizm link
+```
+
+CI など対話できない環境では、`ORIZM_PROJECT` 環境変数または `--project` フラグでプロジェクトを指定します。プロジェクトコンテキストは次の順序で解決されます。
+
+1. `--project <name>` フラグ
+2. `ORIZM_PROJECT` 環境変数
+3. `.orizm/project.json` の `projectName`
+
+## 生成コードの構造変更（`types.ts` の廃止）
+
+v2 の `orizm cms generate` / `orizm consumer generate` は、出力先ディレクトリに **`types.ts`（型定義）と `client.ts`（クライアント）の 2 ファイル** を生成していました。`client.ts` は `import * as Models from "./types"` で `types.ts` の型を参照する構造です。
+
+v3 の `orizm codegen cms` / `orizm codegen consumer` は、**型定義とクライアントを単一のファイルに統合** して出力します。`types.ts` は生成されなくなり、型は生成ファイルから直接 export されます。
+
+型定義の内容（プロパティ名や `__Descriptor` などの構造）は v2 と v3 で同一です。変わったのは「型がどのファイルに置かれ、どこから import するか」だけなので、移行は出力先の指定と import 文の調整で完結します。
+
+> [!WARNING]
+> v2 が生成した `types.ts` は v3 では
+> **更新されません**。古いまま残すとスキーマ変更が型に反映されず実体と乖離するため、移行時に必ず削除してください。
+
+### 出力先に単一ファイルを指定する
+
+v3 では `--output` に出力ファイルのパスを指定します。v2 で `client.ts` を出力していたディレクトリの `client.ts` をそのまま指定すると、クライアントの import 元（`./orizm/client`）を変えずに済みます。
+
+```sh copy
+orizm codegen cms --output src/orizm/client.ts
+orizm codegen consumer --output src/lib/orizm/client.ts
+```
+
+### `types.ts` からの import を生成ファイルに置き換える
+
+型を `types.ts` から import していた箇所を、生成ファイル（`client.ts`）からの import に変更します。
+
+```diff
+- import { Article, ArticleCreateInput } from "./orizm/types";
++ import { Article, ArticleCreateInput } from "./orizm/client";
+```
+
+クライアント本体（`CMSClient` / `OrizmClient`）の import 元は v2 と同じ `client.ts` のままで変更不要です。
+
+### 古い `types.ts` を削除する
+
+`import` の置き換えが終わったら、v2 が生成した `types.ts` を削除します。
+
+```sh copy
+rm src/orizm/types.ts
+```
+
+## 接続先の環境変数
+
+接続先を切り替えるための環境変数は次のとおりです。
+
+| 環境変数                 | 用途                                                                                                     | デフォルト              |
+| ------------------------ | -------------------------------------------------------------------------------------------------------- | ----------------------- |
+| `ORIZM_BASE_URL`         | Developer API の base URL。ローカル / staging / production を切り替える                                  | `https://app.orizm.com` |
+| `ORIZM_OAUTH_ISSUER_URL` | OAuth2 認証サーバーの URL。本番 / staging は通常省略。ローカルで認証サーバーが別ポートのときだけ指定する | `ORIZM_BASE_URL` と同じ |
+
+## 旧→新コマンド対応表
+
+コマンドは noun-first 体系（`orizm <noun> <verb>`）へ整理されました。v2 のコマンドは次のように変わります。
+
+| v2                          | v3                              |
+| --------------------------- | ------------------------------- |
+| `orizm push`                | `orizm schema push`             |
+| `orizm cms generate`        | `orizm codegen cms`             |
+| `orizm cms pull`            | `orizm codegen cms --pull`      |
+| `orizm consumer generate`   | `orizm codegen consumer`        |
+| `orizm consumer pull`       | `orizm codegen consumer --pull` |
+| `orizm config validate`     | `orizm schema validate`         |
+| `orizm config generate-erd` | `orizm schema erd`              |