docs: add comprehensive documentation for operations

This commit introduces a complete set of documentation files
covering various aspects of the project, including environment
setup, quality checks, command references, and architecture.
The documentation is structured to assist developers and
contributors in understanding the project's configuration,
workflow, and best practices.

Additionally, translations for Simplified and Traditional
Chinese have been added to ensure accessibility for a wider
audience. This enhances the overall usability and
maintainability of the project.

Signed-off-by: Bertrand Yuan <github@bertyuan.com>

8 files changed, 394 insertions, 0 deletions

diff --git a/Documentation/source/ja/architecture.rst b/Documentation/source/ja/architecture.rst
new file mode 100644
index 0000000..1f8464e
--- /dev/null
+++ b/Documentation/source/ja/architecture.rst
@@ -0,0 +1,50 @@
+アーキテクチャ
+==============
+
+レイヤー構成
+------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 34 44
+
+   * - レイヤー
+     - 主なファイル
+     - 責務
+   * - 表示層
+     - ``src/app/(main)``、``src/components``
+     - 公開ページ、ルートハンドラー、共通 UI、リッチテキスト、レイアウト。
+   * - コンテンツアクセス層
+     - ``src/lib/payload-posts.ts``
+     - Payload を問い合わせ、CMS ドキュメントをフロントエンド向けの形に正規化する。
+   * - CMS 管理層
+     - ``payload.config.ts``、``src/payload``
+     - コレクションを定義し、管理画面を提供する。
+   * - 認証とコメント
+     - ``src/server/auth``、``src/server/comments``
+     - OAuth、セッション、コメント保存、コメント権限を扱う。
+   * - データ層
+     - ``src/server/db``、``src/migrations``
+     - Drizzle schema、データベース接続、アプリケーション移行を管理する。
+
+記事読み込みフロー
+------------------
+
+1. ``/posts/[slug]`` ページが記事 slug を受け取る。
+2. Server Component が ``getPostBySlug`` を呼び出す。
+3. ``src/lib/payload-posts.ts`` が Payload client を取得し、``published`` の記事を問い合わせる。
+4. 生の Payload ドキュメントを ``BlogPost`` に変換する。
+5. ページがリッチテキストを表示し、共有やコメントの操作を有効にする。
+
+データ境界
+----------
+
+Payload は編集コンテンツとメディアメタデータを所有します。アプリケーション層は認証、コメント、ルート動作、UI 状態、統合ロジックを所有します。新機能では、編集データは Payload collection に、アカウント・操作・モデレーション・運用記録は Drizzle schema に置く方針です。
+
+既知のリスク
+------------
+
+* 本番環境では Payload secret のデフォルト値を使わない。
+* RSS の正規パスは ``/rss.xml`` に統一する。
+* タグ集計と検索インデックスは現在バッチ読み込みに依存しているため、規模が大きくなったらキャッシュまたは DB 側集計を導入する。
+* コメントのロール方針には、より明確なサーバー側ルールとテストが必要。
diff --git a/Documentation/source/ja/contributing.rst b/Documentation/source/ja/contributing.rst
new file mode 100644
index 0000000..cfd63bc
--- /dev/null
+++ b/Documentation/source/ja/contributing.rst
@@ -0,0 +1,38 @@
+コントリビューション
+====================
+
+作業フロー
+----------
+
+1. 変更を所有するサブシステムを判断する。
+2. 近い実装とテストを読む。
+3. 実行時動作、schema、UI、ドキュメント、運用手順への影響を確認する。
+4. patch は対象の挙動に絞り、無関係なリファクタリングを避ける。
+
+コミットメッセージ
+------------------
+
+推奨形式:
+
+.. code-block:: text
+
+   <type>(<scope>): <short summary>
+
+よく使う type は ``build``、``ci``、``docs``、``feat``、``fix``、``perf``、``refactor``、``test`` です。summary は命令形の現在形で書き、末尾にピリオドを付けません。
+
+コード完全性
+------------
+
+* リリースでは署名付き commit と署名付き tag を優先する。
+* 秘密情報、ローカル DB 状態、ビルド成果物をコミットしない。
+* 依存関係の変更はソース変更と同じ慎重さでレビューする。
+* 重要な変更はブランチで作業し、テストとドキュメントビルドを通す。
+
+提出前チェック
+--------------
+
+.. code-block:: bash
+
+   pnpm lint
+   pnpm test
+   make -C Documentation html
diff --git a/Documentation/source/ja/frontend.rst b/Documentation/source/ja/frontend.rst
new file mode 100644
index 0000000..a85ae22
--- /dev/null
+++ b/Documentation/source/ja/frontend.rst
@@ -0,0 +1,49 @@
+フロントエンド
+==============
+
+ページ責務
+----------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 34 44
+
+   * - ルート
+     - 主なファイル
+     - 責務
+   * - ``/``
+     - ``src/app/(main)/(home)/page.tsx``
+     - Hero、最新記事、Newsletter CTA を含むホーム。
+   * - ``/posts``
+     - ``src/app/(main)/(home)/posts/page.tsx``
+     - 公開済み記事のページ付き一覧。
+   * - ``/posts/[slug]``
+     - ``src/app/(main)/(home)/posts/[slug]/page.tsx``
+     - 記事詳細、リッチテキスト、メタデータ、共有、コメント。
+   * - ``/tags``
+     - ``src/app/(main)/(home)/tags/page.tsx``
+     - タグ一覧と記事数。
+   * - ``/tags/[tag]``
+     - ``src/app/(main)/(home)/tags/[...slug]/page.tsx``
+     - タグで絞り込んだ記事一覧。
+   * - ``/login``
+     - ``src/app/(main)/(auth)/login/page.tsx``
+     - OAuth ログイン入口。
+
+UI 原則
+-------
+
+* 読みやすさを優先し、タイポグラフィ、行幅、コントラストを調整する。
+* 記事、タグ、検索、テーマ切替、アカウント操作にすぐアクセスできるようにする。
+* 点線ボーダー、角マーカー、控えめなモーションという既存の視覚言語を保つ。
+* モバイルとデスクトップで同じ情報階層を維持する。
+
+コンポーネント規約
+------------------
+
+新しいコンポーネントを作る前に ``src/components/ui`` と既存ページの実装を確認します。共通コンポーネントは正規化された props を受け取り、データ取得は Server Component または ``src/lib`` helper に置きます。アイコンのみのボタンには必ずアクセシブルな名前を付けます。
+
+アクセシビリティ
+----------------
+
+カスタム操作にはキーボードフォーカスを残します。アイコンボタンやリンクには読み上げ可能な名前を付けます。ライトテーマとダークテーマの両方で十分なコントラストを保ち、フォームは空・読み込み・成功・エラー状態を扱います。
diff --git a/Documentation/source/ja/getting-started.rst b/Documentation/source/ja/getting-started.rst
new file mode 100644
index 0000000..4d11693
--- /dev/null
+++ b/Documentation/source/ja/getting-started.rst
@@ -0,0 +1,72 @@
+はじめに
+========
+
+このページでは、ローカル開発の基本手順を説明します。依存関係、環境変数、データベース、アプリケーション起動、ドキュメントビルドを扱います。
+
+必要なツール
+------------
+
+次のツールを用意してください。
+
+* Next.js 15 に対応した Node.js;
+* pnpm 10.x;
+* ローカル PostgreSQL 用の Docker または Podman;
+* Git;
+* 任意: Sphinx。
+
+環境変数
+--------
+
+サンプルをコピーします。
+
+.. code-block:: bash
+
+   cp .env.example .env
+
+環境変数は ``src/env.js`` で ``@t3-oss/env-nextjs`` と ``zod`` により検証されます。ローカル UI やドキュメント確認だけであれば ``SKIP_ENV_VALIDATION=1`` を一時的に使えますが、本番では使わないでください。
+
+データベース
+------------
+
+ローカル PostgreSQL を起動します。
+
+.. code-block:: bash
+
+   ./start-database.sh
+
+必要に応じて次を実行します。
+
+.. code-block:: bash
+
+   pnpm payload:migrate
+   pnpm db:push
+
+アプリケーション起動
+--------------------
+
+.. code-block:: bash
+
+   pnpm install
+   pnpm dev
+
+公開サイトは通常 ``http://localhost:3000``、Payload 管理画面は ``/admin`` です。
+
+よく使うチェック
+----------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 24 50
+
+   * - コマンド
+     - 目的
+   * - ``pnpm lint``
+     - コンテンツリンク検証と Biome lint。
+   * - ``pnpm check``
+     - Biome チェック。
+   * - ``pnpm test``
+     - Vitest テスト。
+   * - ``pnpm build``
+     - Next.js アプリケーションのビルドとサイトマップ生成。
+   * - ``make -C Documentation html``
+     - Sphinx ドキュメントのビルド。
diff --git a/Documentation/source/ja/index.rst b/Documentation/source/ja/index.rst
new file mode 100644
index 0000000..3376190
--- /dev/null
+++ b/Documentation/source/ja/index.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+Next Blog ドキュメント（日本語）
+================================
+
+これは Next Blog ドキュメントの日本語版です。保守担当者、コントリビューター、運用担当者に向けて、プロダクトの範囲、アーキテクチャ、フロントエンド規約、運用手順、貢献ルールをまとめています。
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   getting-started
+   architecture
+   frontend
+   operations
+   contributing
+   reference
diff --git a/Documentation/source/ja/introduction.rst b/Documentation/source/ja/introduction.rst
new file mode 100644
index 0000000..731db1e
--- /dev/null
+++ b/Documentation/source/ja/introduction.rst
@@ -0,0 +1,46 @@
+プロジェクト概要
+================
+
+Next Blog は、読む体験を中心にしたフルスタックのブログプラットフォームです。公開サイトは Next.js App Router で構築し、コンテンツ管理には Payload CMS を使います。認証、コメント、アプリケーションデータは PostgreSQL、Drizzle ORM、better-auth、Fuma Comments で扱います。
+
+プロダクト範囲
+--------------
+
+現在の主な機能は次のとおりです。
+
+* Payload CMS による記事の作成、編集、公開;
+* ホーム、記事一覧、記事詳細、タグページ、プロフィールページの表示;
+* Google と GitHub OAuth によるログイン;
+* ログインユーザー向けのコメント機能;
+* 検索インデックス、RSS、サイトマップ、JSON-LD、Open Graph 画像の出力;
+* Newsletter フォームと React Email テンプレート。
+
+このプロジェクトは汎用コミュニティ CMS ではありません。公開側は読書体験に、管理側は編集作業に集中した個人向けの発信基盤です。
+
+主要なロール
+------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 34 36
+
+   * - ロール
+     - 目的
+     - 主な入口
+   * - 訪問者
+     - コンテンツを閲覧して読む。
+     - ``/``、``/posts``、``/posts/[slug]``、``/tags``
+   * - リピーター
+     - タグで絞り込み、更新を追う。
+     - ``/tags/[tag]``、``/rss.xml``
+   * - ログインユーザー
+     - コメントやアカウント関連操作を行う。
+     - ``/login``、``/posts/[slug]``
+   * - コンテンツ管理者
+     - 記事を管理、予約、公開する。
+     - ``/admin``
+
+ドキュメント方針
+----------------
+
+``Documentation/source`` はこのリポジトリの正式な Sphinx ドキュメントソースです。``docs/`` の Markdown は調査メモや下書きとして残せますが、継続的に参照するエンジニアリング文書は reStructuredText としてここに整理します。
diff --git a/Documentation/source/ja/operations.rst b/Documentation/source/ja/operations.rst
new file mode 100644
index 0000000..5436fd4
--- /dev/null
+++ b/Documentation/source/ja/operations.rst
@@ -0,0 +1,65 @@
+運用
+====
+
+環境設定
+--------
+
+主要な環境変数は ``src/env.js`` で検証されます。
+
+.. list-table::
+   :header-rows: 1
+   :widths: 34 44
+
+   * - 変数
+     - 用途
+   * - ``DATABASE_URL``
+     - PostgreSQL 接続文字列。
+   * - ``RESEND_API_KEY``
+     - Resend API key。
+   * - ``RESEND_AUDIENCE_ID``
+     - Resend audience ID。
+   * - ``EMAIL_FROM``
+     - 送信元メールアドレス。
+   * - ``BETTER_AUTH_SECRET``
+     - better-auth secret。本番では必須。
+   * - ``GOOGLE_CLIENT_ID`` / ``GOOGLE_CLIENT_SECRET``
+     - Google OAuth 認証情報。
+   * - ``GITHUB_CLIENT_ID`` / ``GITHUB_CLIENT_SECRET``
+     - GitHub OAuth 認証情報。
+
+データベース手順
+----------------
+
+Payload collection の変更:
+
+.. code-block:: bash
+
+   pnpm payload:migrate:create
+   pnpm payload:migrate
+   pnpm payload:generate
+
+アプリケーション schema の変更:
+
+.. code-block:: bash
+
+   pnpm db:generate
+   pnpm db:migrate
+
+品質チェック
+------------
+
+.. code-block:: bash
+
+   pnpm lint
+   pnpm check
+   pnpm test
+   pnpm build
+
+ドキュメントビルド
+------------------
+
+.. code-block:: bash
+
+   make -C Documentation html
+
+生成される ``Documentation/build`` はコミットしません。
diff --git a/Documentation/source/ja/reference.rst b/Documentation/source/ja/reference.rst
new file mode 100644
index 0000000..aa0600a
--- /dev/null
+++ b/Documentation/source/ja/reference.rst
@@ -0,0 +1,57 @@
+リファレンス
+============
+
+よく使うコマンド
+----------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 26 50
+
+   * - コマンド
+     - 説明
+   * - ``pnpm dev``
+     - 開発サーバーを起動する。
+   * - ``pnpm build``
+     - 本番アプリケーションをビルドする。
+   * - ``pnpm lint``
+     - コンテンツリンク検証と Biome lint を実行する。
+   * - ``pnpm test``
+     - テストを実行する。
+   * - ``pnpm db:migrate``
+     - Drizzle migration を適用する。
+   * - ``pnpm payload:generate``
+     - Payload TypeScript 型を生成する。
+
+ルート
+------
+
+.. code-block:: text
+
+   /
+   /posts
+   /posts/[slug]
+   /tags
+   /tags/[tag]
+   /about
+   /login
+   /admin
+   /api/auth/[...all]
+   /api/comments/[...comment]
+   /api/search
+   /rss.xml
+
+用語
+----
+
+Payload
+   記事、ユーザー、メディア、管理画面を扱う CMS。
+
+Drizzle
+   アプリケーション所有のデータベーステーブルを扱う TypeScript ORM。
+
+better-auth
+   OAuth とセッションを提供する認証ライブラリ。
+
+BlogPost
+   ``src/lib/payload-posts.ts`` が返すフロントエンド向けの正規化済み記事構造。