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>

5 files changed, 244 insertions, 0 deletions

diff --git a/Documentation/source/reference/api.rst b/Documentation/source/reference/api.rst
new file mode 100644
index 0000000..85081aa
--- /dev/null
+++ b/Documentation/source/reference/api.rst
@@ -0,0 +1,53 @@
+API Reference
+=============
+
+Search Index
+------------
+
+Path
+   ``/api/search``
+
+Purpose
+   Provides search data for the frontend search experience.
+
+Rules
+   Return public published content only. Keep the response shape stable for the
+   search client.
+
+Comments
+--------
+
+Path
+   ``/api/comments/[...comment]``
+
+Purpose
+   Handles Fuma Comments operations.
+
+Rules
+   Authentication and authorization belong on the server side. Client code
+   should not decide comment privileges.
+
+Auth
+----
+
+Path
+   ``/api/auth/[...all]``
+
+Purpose
+   Handles better-auth routes for OAuth and session behavior.
+
+Rules
+   Keep provider configuration in ``src/server/auth`` and environment
+   validation in ``src/env.js``.
+
+Feed
+----
+
+Path
+   ``/rss.xml``
+
+Purpose
+   Publishes feed output for readers and feed clients.
+
+Rules
+   Include published content only and keep route references canonical.
diff --git a/Documentation/source/reference/commands.rst b/Documentation/source/reference/commands.rst
new file mode 100644
index 0000000..8268400
--- /dev/null
+++ b/Documentation/source/reference/commands.rst
@@ -0,0 +1,96 @@
+Command Reference
+=================
+
+Application
+-----------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 24 52
+
+   * - Command
+     - Description
+   * - ``pnpm dev``
+     - Start the Next.js development server.
+   * - ``pnpm build``
+     - Build the production application.
+   * - ``pnpm start``
+     - Start a built production server.
+   * - ``pnpm preview``
+     - Build and start the production server.
+
+Quality
+-------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 24 52
+
+   * - Command
+     - Description
+   * - ``pnpm lint``
+     - Run project link validation and Biome linting.
+   * - ``pnpm check``
+     - Run Biome checks.
+   * - ``pnpm format``
+     - Format files with Biome.
+   * - ``pnpm test``
+     - Run Vitest once.
+   * - ``pnpm test:watch``
+     - Run Vitest in watch mode.
+   * - ``pnpm test:coverage``
+     - Run tests with coverage.
+
+Data and CMS
+------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 28 48
+
+   * - Command
+     - Description
+   * - ``pnpm db:generate``
+     - Generate Drizzle migration files.
+   * - ``pnpm db:migrate``
+     - Apply Drizzle migrations.
+   * - ``pnpm db:push``
+     - Push Drizzle schema changes directly.
+   * - ``pnpm db:studio``
+     - Open Drizzle Studio.
+   * - ``pnpm payload:generate``
+     - Generate Payload TypeScript types.
+   * - ``pnpm payload:migrate``
+     - Run Payload migrations.
+   * - ``pnpm payload:migrate:create``
+     - Create a Payload migration.
+
+Email
+-----
+
+.. list-table::
+   :header-rows: 1
+   :widths: 24 52
+
+   * - Command
+     - Description
+   * - ``pnpm email:dev``
+     - Start React Email preview server on port 3001.
+   * - ``pnpm email:build``
+     - Build email templates.
+   * - ``pnpm email:export``
+     - Export email templates.
+
+Documentation
+-------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 28 48
+
+   * - Command
+     - Description
+   * - ``make -C Documentation html``
+     - Build Sphinx HTML documentation.
+   * - ``make -C Documentation clean``
+     - Remove generated Sphinx build output.
diff --git a/Documentation/source/reference/glossary.rst b/Documentation/source/reference/glossary.rst
new file mode 100644
index 0000000..d2d648b
--- /dev/null
+++ b/Documentation/source/reference/glossary.rst
@@ -0,0 +1,32 @@
+Glossary
+========
+
+App Router
+   Next.js routing model used by this project under ``src/app``.
+
+better-auth
+   Authentication library used for OAuth and sessions.
+
+BlogPost
+   Normalized frontend post shape returned by ``src/lib/payload-posts.ts``.
+
+Drizzle
+   TypeScript ORM used for application-owned database tables.
+
+Fuma Comments
+   Comment UI and server package used for post discussions.
+
+Fumadocs
+   MDX content and UI tooling used by the site.
+
+Lexical
+   Rich text editor used by Payload CMS.
+
+Payload
+   CMS used for posts, users, media, and the admin interface.
+
+Sphinx
+   Documentation generator used for ``Documentation/source``.
+
+Tag
+   Topic label stored on posts and used for tag index and filtered post pages.
diff --git a/Documentation/source/reference/index.rst b/Documentation/source/reference/index.rst
new file mode 100644
index 0000000..1f52bcf
--- /dev/null
+++ b/Documentation/source/reference/index.rst
@@ -0,0 +1,13 @@
+Reference
+=========
+
+Reference pages collect stable facts that are useful during implementation and
+review.
+
+.. toctree::
+   :maxdepth: 2
+
+   commands
+   routes
+   api
+   glossary
diff --git a/Documentation/source/reference/routes.rst b/Documentation/source/reference/routes.rst
new file mode 100644
index 0000000..93bcfd3
--- /dev/null
+++ b/Documentation/source/reference/routes.rst
@@ -0,0 +1,50 @@
+Route Reference
+===============
+
+Public Pages
+------------
+
+.. code-block:: text
+
+   /
+   /posts
+   /posts/[slug]
+   /tags
+   /tags/[tag]
+   /about
+   /login
+
+Admin and Payload
+-----------------
+
+.. code-block:: text
+
+   /admin
+   /api/[...slug]
+   /api/graphql
+   /api/graphql-playground
+
+Application APIs
+----------------
+
+.. code-block:: text
+
+   /api/auth/[...all]
+   /api/comments/[...comment]
+   /api/search
+
+Generated Assets
+----------------
+
+.. code-block:: text
+
+   /rss.xml
+   /banner.png
+   /og/[...slug]
+
+Route Ownership
+---------------
+
+Routes under ``src/app/(main)`` belong to the public application. Routes under
+``src/app/(payload)`` belong to Payload CMS integration and should be changed
+with care because they affect the admin and CMS API surface.