docs: refactor readme

4 files changed, 230 insertions, 339 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..2e81737
--- /dev/null
+++ b/README
@@ -0,0 +1,115 @@
+Next blog
+=========
+
+A full-stack blog built with Next.js 15 and Payload CMS. Ships authentication, comments, search, RSS, and an email template out of the box.
+
+Overview
+--------
+
+Frontend uses Next.js App Router with Tailwind and shadcn, plus fumadocs layout pieces for navigation, pagination, and search.
+Content is managed by Payload CMS (payload.config.ts) with support for rich text, tags, cover images, and publish states.
+Authentication relies on better-auth with Google and GitHub; sessions and comments are stored in Postgres through Drizzle ORM.
+Comments use @fuma-comment, and the site generates both /rss.xml feeds and /api/search indexes.
+
+Features
+--------
+
+Post management: Payload admin (/admin) creates drafts or published posts with cover images, tags, and scheduled publish time.
+Blog experience: paginated lists, a tag hub, rich post detail rendering, a share button, and one-click copy link.
+Social and interaction: Google or GitHub login, better-auth session management, Fuma Comment stored locally.
+Enhancements: RSS feed, on-the-fly search index, automatic Open Graph banners, and sitemap via next-sitemap.
+Email template: emails/newsletter-welcome.tsx using React Email with Tailwind, ready for Resend.
+Ops friendly: .env validation, start-database.sh to boot local Postgres, unified Drizzle and Payload scripts for schema.
+
+Tech Stack
+----------
+
+Framework: Next.js 15 (App Router) with server components and hybrid static/dynamic rendering.
+UI: Tailwind CSS 4 with shadcn and fumadocs-ui for navigation, pagination, sections, and theming.
+Content: Payload CMS for Posts, Users, and Media with Lexical rich text.
+Data: PostgreSQL and Drizzle ORM; auth and comments tables are prefixed blog_*.
+Auth: better-auth with OAuth (Google/GitHub), sessions, and an extra role field.
+Email: Resend with React Email, welcome template styled by Tailwind.
+
+Quickstart
+----------
+
+1. Install toolchain. Node 20+ recommended. Use pnpm locked by pnpm-lock.yaml.
+2. Set environment variables. Copy .env.example to .env and fill DATABASE_URL, PAYLOAD_SECRET, BETTER_AUTH_SECRET, and OAuth keys if needed.
+3. Start Postgres locally. Run ./start-database.sh (Docker/Podman) or connect to your own Postgres instance.
+4. Install dependencies and build schema. Run pnpm install; pnpm db:generate && pnpm db:migrate for Drizzle; pnpm payload:migrate for Payload CMS.
+5. Run the dev server. pnpm dev (defaults to port 3000; Payload Admin at /admin, blog at /).
+6. Optional extras. pnpm payload:generate for types; pnpm email:dev -p 3001 to preview the email template.
+Payload in development pre-fills <admin@example.com> / admin123 on the login form.
+
+Core Modules
+------------
+
+Content model lives in payload.config.ts, defining Posts, Users, and Media with cover uploads, tag arrays, publish time, and status.
+Data fetching is wrapped in src/lib/payload-posts.ts for post queries, tag stats, pagination, and slug helpers.
+Pages and layout reside under src/app/(main); _components includes Hero, CTA, and post list UI.
+Auth and comments sit in src/server/auth (better-auth + Drizzle) and src/server/comments storing into blog_comments tables.
+Search and feed live in src/app/(main)/api/search/route.ts (indexes) and src/app/(main)/rss.xml/route.ts (Atom/RSS).
+Email template is emails/newsletter-welcome.tsx, a React Email component that accepts a posts array.
+
+Project structure (excerpt)
+---------------------------
+
+src/
+  app/
+    (main)/(home)/page.tsx               Home with hero, recent posts, CTA
+    (main)/(home)/posts/[slug]/page.tsx  Post detail with comments and share
+    (main)/(home)/posts/page.tsx         Paginated posts list
+    (main)/(home)/tags/page.tsx          Tag hub
+    (main)/api/search/route.ts           Search index API
+    (main)/rss.xml/route.ts              Atom/RSS feed
+    (payload)/admin/...                  Payload CMS admin
+  lib/                                   Data and utilities (payload-posts, metadata, auth-client)
+  server/                                better-auth and Drizzle schema plus comment storage
+  emails/                                React Email templates
+
+Environment variables
+---------------------
+
+Required or commonly used:
+  DATABASE_URL: Postgres connection string, e.g. postgresql://user:pass@localhost:5432/blog
+  PAYLOAD_SECRET: Secret used by Payload CMS for JWT
+  BETTER_AUTH_SECRET: better-auth session secret
+  BETTER_AUTH_URL: Auth callback base, local is <http://localhost:3000>
+  NEXT_PUBLIC_SERVER_URL: Base URL for links, OG, and RSS
+  RESEND_API_KEY / RESEND_AUDIENCE_ID / EMAIL_FROM: Needed for sending emails
+  GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET: Needed if enabling Google login
+  GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET: Needed if enabling GitHub login
+  NEXT_PUBLIC_UMAMI_URL / NEXT_PUBLIC_UMAMI_WEBSITE_ID: Optional analytics
+
+Scripts
+-------
+
+pnpm dev                  Start Next.js dev server (includes Payload routes).
+pnpm build                Build production output.
+pnpm preview              Preview the production build.
+pnpm db:generate          Generate Drizzle migrations for auth and comments.
+pnpm db:migrate           Run Drizzle migrations.
+pnpm payload:migrate      Sync Payload CMS tables.
+pnpm lint                 Run quality checks (biome).
+pnpm format               Format source (biome).
+pnpm email:dev            Preview React Email templates locally.
+
+Routes and APIs
+---------------
+
+/                       Home with hero, latest posts, and CTA.
+/posts                 Paginated posts; /posts/[slug] for detail with rich text, comments, and share.
+/tags                  Tag cloud with counts.
+/login                 Google or GitHub login entry.
+/admin                 Payload CMS admin.
+/api/search            Search index endpoint (fumadocs search).
+/rss.xml               Atom/RSS feed.
+
+Developer notes
+---------------
+
+Prefer ./start-database.sh to boot Postgres locally; the script warns if the port is in use.
+Auth and comment tables use the blog_prefix; keep drizzle.config.ts tablesFilter in sync.
+Payload dev mode pre-fills <admin@example.com> / admin123 to speed up admin login.
+If you only need to browse the UI without real data, set SKIP_ENV_VALIDATION=1 and disable features needing external services; full env is recommended for complete coverage.
diff --git a/README-zh b/README-zh
new file mode 100644
index 0000000..ce565f3
--- /dev/null
+++ b/README-zh
@@ -0,0 +1,115 @@
+Next blog
+=========
+
+基于 Next.js 15 与 Payload CMS 的全栈博客，内置认证、评论、搜索、RSS 和邮件模板。
+
+项目简介
+--------
+
+前端使用 Next.js App Router 配合 Tailwind 和 shadcn，并借助 fumadocs 的组件搭建导航、分页与搜索。
+内容由 Payload CMS（payload.config.ts）管理，支持富文本、标签、封面图与发布状态。
+认证使用 better-auth，支持 Google 和 GitHub；会话与评论通过 Drizzle ORM 写入 Postgres。
+评论集成 @fuma-comment，站点同时生成 /rss.xml 订阅源与 /api/search 搜索索引。
+
+主要特性
+--------
+
+文章管理：Payload 后台 /admin 可创建草稿或已发布文章，支持封面、标签与定时发布时间。
+博客体验：列表分页、标签聚合页、文章详情富文本渲染、分享按钮、一键复制链接。
+社交与互动：Google 或 GitHub 登录，better-auth 会话管理，Fuma Comment 评论存储在本地数据库。
+增强能力：RSS 输出、站内搜索索引、自动 Open Graph Banner、next-sitemap 生成站点地图。
+邮件模板：emails/newsletter-welcome.tsx 提供 React Email + Tailwind 的欢迎邮件，可接入 Resend。
+运维友好：.env 校验、start-database.sh 一键启动本地 Postgres，统一的 Drizzle 与 Payload 脚本。
+
+技术栈
+------
+
+框架：Next.js 15（App Router），服务端组件，静态与动态混合渲染。
+UI：Tailwind CSS 4、shadcn、fumadocs-ui，用于导航、分页、Section 和主题。
+内容：Payload CMS 管理 Posts、Users、Media，使用 Lexical 富文本。
+数据：PostgreSQL 与 Drizzle ORM，认证与评论表以 blog_* 作为前缀。
+认证：better-auth + OAuth（Google/GitHub），包含会话和额外角色字段。
+邮件：Resend 与 React Email，Tailwind 样式的欢迎模板。
+
+快速开始
+--------
+
+1. 安装工具链。推荐 Node 20+，使用 pnpm（已锁定 pnpm-lock.yaml）。
+2. 配置环境变量。复制 .env.example 为 .env，填写 DATABASE_URL、PAYLOAD_SECRET、BETTER_AUTH_SECRET，如需社交登录补齐 OAuth。
+3. 启动 Postgres。运行 ./start-database.sh（依赖 Docker/Podman），或连接自带的 Postgres 实例。
+4. 安装依赖并生成结构。执行 pnpm install；pnpm db:generate && pnpm db:migrate 处理 Drizzle；pnpm payload:migrate 同步 Payload CMS。
+5. 运行开发服务器。pnpm dev（默认 3000，后台 /admin，博客 /）。
+6. 可选步骤。pnpm payload:generate 生成类型；pnpm email:dev -p 3001 预览邮件模板。
+开发模式下，Payload 登录框会预填 admin@example.com / admin123。
+
+核心模块
+--------
+
+内容模型位于 payload.config.ts，定义文章、用户、媒体，支持封面上传、标签数组、发布时间与状态。
+数据访问封装在 src/lib/payload-posts.ts，用于文章查询、标签统计、分页与 slug 工具。
+页面与布局在 src/app/(main)，_components 内含 Hero、CTA、文章列表等 UI。
+认证与评论位于 src/server/auth（better-auth + Drizzle）和 src/server/comments（写入 blog_comments 表）。
+搜索与订阅在 src/app/(main)/api/search/route.ts（索引）与 src/app/(main)/rss.xml/route.ts（Atom/RSS）。
+邮件模板是 emails/newsletter-welcome.tsx，可接受文章数组渲染卡片。
+
+项目结构（节选）
+----------------
+
+src/
+  app/
+    (main)/(home)/page.tsx               首页：Hero、最近文章、CTA
+    (main)/(home)/posts/[slug]/page.tsx  文章详情、评论、分享
+    (main)/(home)/posts/page.tsx         分页文章列表
+    (main)/(home)/tags/page.tsx          标签聚合
+    (main)/api/search/route.ts           搜索索引接口
+    (main)/rss.xml/route.ts              Atom/RSS 输出
+    (payload)/admin/...                  Payload CMS 后台
+  lib/                                   数据与工具（payload-posts、metadata、auth-client）
+  server/                                better-auth 与 Drizzle schema，评论存储
+  emails/                                React Email 模板
+
+环境变量
+--------
+
+常用或必填项：
+  DATABASE_URL：Postgres 连接串，例如 postgresql://user:pass@localhost:5432/blog
+  PAYLOAD_SECRET：Payload CMS 的 JWT 密钥
+  BETTER_AUTH_SECRET：better-auth 会话密钥
+  BETTER_AUTH_URL：认证回调地址，本地可用 http://localhost:3000
+  NEXT_PUBLIC_SERVER_URL：生成链接、OG、RSS 的基础地址
+  RESEND_API_KEY / RESEND_AUDIENCE_ID / EMAIL_FROM：发送邮件所需
+  GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET：启用 Google 登录时必填
+  GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET：启用 GitHub 登录时必填
+  NEXT_PUBLIC_UMAMI_URL / NEXT_PUBLIC_UMAMI_WEBSITE_ID：可选分析
+
+常用脚本
+--------
+
+pnpm dev                  启动 Next.js 开发服务器（含 Payload routes）
+pnpm build                构建生产包
+pnpm preview              预览生产构建
+pnpm db:generate          生成 Drizzle 迁移（认证/评论表）
+pnpm db:migrate           执行 Drizzle 迁移
+pnpm payload:migrate      同步 Payload CMS 数据表
+pnpm lint                 质量检查（biome）
+pnpm format               代码格式化（biome）
+pnpm email:dev            本地预览 React Email 模板
+
+页面与接口
+----------
+
+/                        首页，Hero、最新文章、CTA
+/posts                   文章分页；/posts/[slug] 展示详情、富文本、评论、分享
+/tags                    标签云与计数
+/login                   Google/GitHub 登录入口
+/admin                   Payload CMS 后台
+/api/search              站内搜索索引接口（fumadocs search）
+/rss.xml                 Atom/RSS 订阅
+
+开发提示
+--------
+
+优先使用 ./start-database.sh 启动本地 Postgres，脚本会提示端口占用。
+认证与评论表使用 blog_ 前缀，保持 drizzle.config.ts 中的 tablesFilter 一致。
+开发模式下 Payload 自动填充 <admin@example.com> / admin123，便于快速登录。
+只想浏览 UI 时可设置 SKIP_ENV_VALIDATION=1，并关闭依赖外部服务的功能；完整环境更可靠。
diff --git a/README-zh.md b/README-zh.md
deleted file mode 100644
index a6b1d10..0000000
--- a/README-zh.md
+++ /dev/null
@@ -1,170 +0,0 @@
-<div align="center">
-  <h1>shadcn blog</h1>
-  <p>基于 Next.js 15 + Payload CMS 的全栈博客，内置认证、评论、搜索、RSS 与邮件模版。</p>
-  <p>
-    <img src="https://img.shields.io/badge/Next.js-15-black" alt="Next.js 15" />
-    <img src="https://img.shields.io/badge/React-19-61dafb" alt="React 19" />
-    <img src="https://img.shields.io/badge/Database-PostgreSQL-336791" alt="PostgreSQL" />
-    <img src="https://img.shields.io/badge/CMS-Payload-blueviolet" alt="Payload CMS" />
-  </p>
-</div>
-
-## 目录
-
-- [目录](#目录)
-- [项目简介](#项目简介)
-- [主要特性](#主要特性)
-- [技术栈](#技术栈)
-- [快速开始](#快速开始)
-- [核心模块速览](#核心模块速览)
-- [环境变量](#环境变量)
-- [常用脚本](#常用脚本)
-- [页面与接口](#页面与接口)
-- [开发提示](#开发提示)
-
-## 项目简介
-
-- 前端采用 Next.js App Router，UI 基于 tailwind + shadcn，并用 fumadocs 的布局组件快速搭建导航、分页、搜索等。
-- 内容源由 Payload CMS 提供（`payload.config.ts`），支持富文本、标签、封面图与发布状态。
-- 认证使用 better-auth（Google/GitHub 登录），会话与评论数据通过 Drizzle ORM 写入 Postgres。
-- 评论系统集成 `@fuma-comment`，同时生成 `/rss.xml` 订阅源和 `/api/search` 搜索索引。
-
-## 主要特性
-
-- 文章管理：Payload 后台（`/admin`）可创建草稿/已发布文章，支持封面、标签与定时发布时间。
-- 博客体验：列表分页、标签聚合页、文章详情页富文本渲染、分享按钮、一键复制链接。
-- 社交与互动：Google/GitHub 登录、基于 better-auth 的会话管理，Fuma Comment 评论组件存储在本地数据库。
-- 增强功能：RSS 输出、站内搜索索引、自动 Open Graph/OG Banner、站点地图（`next-sitemap`）。
-- 邮件模版：`emails/newsletter-welcome.tsx` 提供 React Email/Tailwind 的欢迎邮件示例，可通过 Resend 发送。
-- 运维友好：`.env` 校验、`start-database.sh` 一键启动本地 Postgres、Drizzle/Payload 脚本统一管理数据库。
-
-## 技术栈
-
-<table>
-  <tr>
-    <th>领域</th>
-    <th>选择</th>
-    <th>说明</th>
-  </tr>
-  <tr>
-    <td>框架</td>
-    <td>Next.js 15 (App Router)</td>
-    <td>服务端组件、动态/静态混合渲染</td>
-  </tr>
-  <tr>
-    <td>UI</td>
-    <td>tailwindcss 4 + shadcn + fumadocs-ui</td>
-    <td>快速搭建导航、分页、Section、主题切换</td>
-  </tr>
-  <tr>
-    <td>内容</td>
-    <td>Payload CMS</td>
-    <td>Posts/Users/Media 集合，Lexical 富文本</td>
-  </tr>
-  <tr>
-    <td>数据</td>
-    <td>PostgreSQL + Drizzle ORM</td>
-    <td>认证与评论表（前缀 <code>blog_*</code>）</td>
-  </tr>
-  <tr>
-    <td>认证</td>
-    <td>better-auth + OAuth (Google/GitHub)</td>
-    <td>社交登录、会话、额外角色字段</td>
-  </tr>
-  <tr>
-    <td>邮件</td>
-    <td>Resend + React Email</td>
-    <td>欢迎邮件模版、Tailwind 样式</td>
-  </tr>
-</table>
-
-## 快速开始
-
-1) 安装依赖与 Node  
-   - 推荐 Node 20+，包管理器使用 `pnpm`（已锁定 `pnpm-lock.yaml`）。
-2) 配置环境变量  
-   - 复制 `.env.example` 为 `.env`，至少填写 `DATABASE_URL`、`PAYLOAD_SECRET`、`BETTER_AUTH_SECRET`，如需社交登录再补齐 OAuth。
-3) 启动本地数据库（Postgres）  
-   - `./start-database.sh`（依赖 Docker/Podman）或使用自带的 Postgres 实例。
-4) 安装依赖并生成数据库结构  
-   - `pnpm install`  
-   - `pnpm db:generate && pnpm db:migrate`（Drizzle 认证/评论表）  
-   - `pnpm payload:migrate`（Payload CMS 表）
-5) 运行开发服务  
-   - `pnpm dev`（默认监听 3000，Payload Admin `/admin`，博客 `/`）。
-6) 可选：生成 Payload Types 与邮件预览  
-   - `pnpm payload:generate`  
-   - `pnpm email:dev -p 3001` 查看邮件模版。
-
-> 开发模式下 Payload 会自动填充 `admin@example.com` / `admin123` 登录框，无需手动创建账户。
-
-## 核心模块速览
-
-- 内容模型：`payload.config.ts` 定义 Posts/Users/Media，文章支持封面上传、标签数组、发布时间与状态。
-- 数据获取：`src/lib/payload-posts.ts` 统一封装文章查询、标签统计、分页与 slug 获取，供页面调用。
-- 页面与布局：`src/app/(main)` 为站点主入口，`_components` 目录包含 Hero、CTA、Post 列表等 UI。
-- 认证与评论：`src/server/auth`（better-auth + Drizzle），`src/server/comments` 将评论存入 `blog_comments` 表。
-- 搜索与订阅：`src/app/(main)/api/search/route.ts` 动态生成索引；`src/app/(main)/rss.xml/route.ts` 输出 Atom feed。
-- 邮件：`emails/newsletter-welcome.tsx` React Email 模版，可传入最新文章数组渲染卡片。
-
-项目结构（节选）：
-
-```text
-src/
-├── app/
-│   ├── (main)/(home)/page.tsx           # 首页：Hero、最近文章、CTA
-│   ├── (main)/(home)/posts/[slug]/page.tsx  # 文章详情 + 评论 + 分享
-│   ├── (main)/(home)/posts/page.tsx     # 分页文章列表
-│   ├── (main)/(home)/tags/page.tsx      # 标签聚合
-│   ├── (main)/api/search/route.ts       # 站内搜索索引
-│   ├── (main)/rss.xml/route.ts          # Atom/RSS 输出
-│   └── (payload)/admin/...              # Payload CMS 后台
-├── lib/                                 # 数据与工具（payload-posts、metadata、auth-client）
-├── server/                              # better-auth + Drizzle schema + comment storage
-└── emails/                              # React Email 模版
-```
-
-## 环境变量
-
-<details>
-<summary>必填与可选</summary>
-
-| 变量 | 说明 |
-| --- | --- |
-| `DATABASE_URL` | Postgres 连接串，例如 `postgresql://user:pass@localhost:5432/blog` |
-| `PAYLOAD_SECRET` | Payload CMS 用于 JWT 加密的密钥 |
-| `BETTER_AUTH_SECRET` | better-auth session 密钥 |
-| `BETTER_AUTH_URL` | 认证回调地址（本地可设 `http://localhost:3000`） |
-| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | 启用 Google 登录时必填 |
-| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` | 启用 GitHub 登录时必填 |
-| `RESEND_API_KEY` / `RESEND_AUDIENCE_ID` / `EMAIL_FROM` | 发送邮件时必填 |
-| `NEXT_PUBLIC_SERVER_URL` | 生成链接、OG、RSS 的基础地址 |
-| `NEXT_PUBLIC_UMAMI_URL` / `NEXT_PUBLIC_UMAMI_WEBSITE_ID` | 可选，埋点统计 |
-
-</details>
-
-## 常用脚本
-
-- `pnpm dev`：启动 Next.js 开发服务器（含 Payload routes）。
-- `pnpm build` / `pnpm preview`：构建与预览生产版本。
-- `pnpm db:generate` / `pnpm db:migrate`：生成并执行 Drizzle 迁移（认证/评论表）。
-- `pnpm payload:migrate`：同步 Payload CMS 数据表。
-- `pnpm lint` / `pnpm format`：质量与格式检查（biome）。
-- `pnpm email:dev`：本地预览 React Email 模版。
-
-## 页面与接口
-
-- `/`：首页，展示 Hero、最新文章、CTA。
-- `/posts`：文章分页列表；`/posts/[slug]`：详情页、富文本、评论、分享。
-- `/tags`：标签云与计数。
-- `/login`：Google/GitHub 登录入口。
-- `/admin`：Payload CMS 后台。
-- `/api/search`：搜索索引接口（fumadocs search）。
-- `/rss.xml`：Atom/RSS 订阅。
-
-## 开发提示
-
-- 本地优先运行 `./start-database.sh` 启动 Postgres；若端口占用脚本会提示。
-- 认证与评论表前缀为 `blog_`，确保 `drizzle.config.ts` 里的 `tablesFilter` 与迁移脚本保持一致。
-- Payload 在开发环境会预填 `admin@example.com` / `admin123`，方便快速登录后台。
-- 如果只想浏览前端而不接入真实数据，可设置 `SKIP_ENV_VALIDATION=1` 并禁用需要外部服务的功能，但推荐补齐变量以覆盖所有页面。
diff --git a/README.md b/README.md
deleted file mode 100644
index 24e47a8..0000000
--- a/README.md
+++ /dev/null
@@ -1,169 +0,0 @@
-<div align="center">
-  <h1>shadcn blog</h1>
-  <p>A full-stack blog built with Next.js 15 + Payload CMS, shipping auth, comments, search, RSS, and email templates out of the box.</p>
-  <p>
-    <img src="https://img.shields.io/badge/Next.js-15-black" alt="Next.js 15" />
-    <img src="https://img.shields.io/badge/React-19-61dafb" alt="React 19" />
-    <img src="https://img.shields.io/badge/Database-PostgreSQL-336791" alt="PostgreSQL" />
-    <img src="https://img.shields.io/badge/CMS-Payload-blueviolet" alt="Payload CMS" />
-  </p>
-</div>
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Features](#features)
-- [Tech Stack](#tech-stack)
-- [Quickstart](#quickstart)
-- [Core Modules](#core-modules)
-- [Environment Variables](#environment-variables)
-- [Scripts](#scripts)
-- [Routes & APIs](#routes--apis)
-- [Developer Notes](#developer-notes)
-
-## Overview
-
-- Frontend uses Next.js App Router with Tailwind + shadcn, and fumadocs layout pieces for navigation, pagination, and search.
-- Content is managed by Payload CMS (`payload.config.ts`), supporting rich text, tags, cover images, and publish states.
-_- Authentication via better-auth (Google/GitHub), sessions and comments stored in Postgres through Drizzle ORM._
-- Comments are powered by `@fuma-comment`, and the site generates both `/rss.xml` feeds and `/api/search` indexes.
-
-## Features
-
-- Post management: Payload admin (`/admin`) creates drafts/published posts with cover image, tags, and scheduled publish time.
-- Blog UX: paginated lists, tag hub, rich post detail rendering, share button, one-click copy link.
-- Social & interaction: Google/GitHub login, better-auth session management, Fuma Comment stored locally.
-- Enhancements: RSS feed, on-the-fly search index, automatic Open Graph/OG banners, sitemap via `next-sitemap`.
-- Email template: `emails/newsletter-welcome.tsx` using React Email + Tailwind, ready for Resend.
-- Ops-friendly: `.env` validation, `start-database.sh` to boot local Postgres, unified Drizzle/Payload scripts for schema.
-
-## Tech Stack
-
-<table>
-  <tr>
-    <th>Area</th>
-    <th>Choice</th>
-    <th>Notes</th>
-  </tr>
-  <tr>
-    <td>Framework</td>
-    <td>Next.js 15 (App Router)</td>
-    <td>Server Components with hybrid static/dynamic rendering</td>
-  </tr>
-  <tr>
-    <td>UI</td>
-    <td>Tailwind CSS 4 + shadcn + fumadocs-ui</td>
-    <td>Navigation, pagination, sections, theming</td>
-  </tr>
-  <tr>
-    <td>Content</td>
-    <td>Payload CMS</td>
-    <td>Posts/Users/Media collections, Lexical rich text</td>
-  </tr>
-  <tr>
-    <td>Data</td>
-    <td>PostgreSQL + Drizzle ORM</td>
-    <td>Auth and comments tables (prefix <code>blog_*</code>)</td>
-  </tr>
-  <tr>
-    <td>Auth</td>
-    <td>better-auth + OAuth (Google/GitHub)</td>
-    <td>Social login, sessions, extra role field</td>
-  </tr>
-  <tr>
-    <td>Email</td>
-    <td>Resend + React Email</td>
-    <td>Welcome template, Tailwind styling</td>
-  </tr>
-</table>
-
-## Quickstart
-
-1) Install toolchain  
-   - Node 20+ recommended, use `pnpm` (locked by `pnpm-lock.yaml`).
-2) Set environment variables  
-   - Copy `.env.example` to `.env`; fill `DATABASE_URL`, `PAYLOAD_SECRET`, `BETTER_AUTH_SECRET`, and OAuth keys if needed.
-3) Start Postgres locally  
-   - `./start-database.sh` (Docker/Podman) or your own Postgres instance.
-4) Install deps and build schema  
-   - `pnpm install`  
-   - `pnpm db:generate && pnpm db:migrate` (Drizzle auth/comments tables)  
-   - `pnpm payload:migrate` (Payload CMS tables)
-5) Run dev server  
-   - `pnpm dev` (default :3000; Payload Admin `/admin`, blog `/`).
-6) Optional extras  
-   - `pnpm payload:generate` (types)  
-   - `pnpm email:dev -p 3001` (preview email template).
-
-> In development, Payload pre-fills `admin@example.com` / `admin123` on the login form.
-
-## Core Modules
-
-- Content model: `payload.config.ts` defines Posts/Users/Media with cover uploads, tag arrays, publish time, and status.
-- Data fetching: `src/lib/payload-posts.ts` wraps post queries, tag stats, pagination, and slug helpers for pages.
-- Pages & layout: `src/app/(main)` hosts the site; `_components` includes Hero, CTA, and post list UI.
-- Auth & comments: `src/server/auth` (better-auth + Drizzle) and `src/server/comments` storing into `blog_comments` tables.
-- Search & feed: `src/app/(main)/api/search/route.ts` builds indexes; `src/app/(main)/rss.xml/route.ts` emits Atom/RSS.
-- Email: `emails/newsletter-welcome.tsx` React Email template that accepts a posts array.
-
-Project structure (excerpt):
-
-```text
-src/
-├── app/
-│   ├── (main)/(home)/page.tsx               # Home: hero, recent posts, CTA
-│   ├── (main)/(home)/posts/[slug]/page.tsx  # Post detail + comments + share
-│   ├── (main)/(home)/posts/page.tsx         # Paginated posts list
-│   ├── (main)/(home)/tags/page.tsx          # Tag hub
-│   ├── (main)/api/search/route.ts           # Search index API
-│   ├── (main)/rss.xml/route.ts              # Atom/RSS feed
-│   └── (payload)/admin/...                  # Payload CMS admin
-├── lib/                                     # Data + utilities (payload-posts, metadata, auth-client)
-├── server/                                  # better-auth + Drizzle schema + comment storage
-└── emails/                                  # React Email templates
-```
-
-## Environment Variables
-
-<details>
-<summary>Required & optional</summary>
-
-| Variable | Description |
-| --- | --- |
-| `DATABASE_URL` | Postgres connection string, e.g. `postgresql://user:pass@localhost:5432/blog` |
-| `PAYLOAD_SECRET` | Secret used by Payload CMS for JWT |
-| `BETTER_AUTH_SECRET` | better-auth session secret |
-| `BETTER_AUTH_URL` | Auth callback base (local: `http://localhost:3000`) |
-| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | Required if enabling Google login |
-| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` | Required if enabling GitHub login |
-| `RESEND_API_KEY` / `RESEND_AUDIENCE_ID` / `EMAIL_FROM` | Required for sending emails |
-| `NEXT_PUBLIC_SERVER_URL` | Base URL for links/OG/RSS |
-| `NEXT_PUBLIC_UMAMI_URL` / `NEXT_PUBLIC_UMAMI_WEBSITE_ID` | Optional analytics |
-
-</details>
-
-## Scripts
-
-- `pnpm dev`: Start Next.js dev server (includes Payload routes).
-- `pnpm build` / `pnpm preview`: Build and preview production.
-- `pnpm db:generate` / `pnpm db:migrate`: Generate and run Drizzle migrations (auth/comments).
-- `pnpm payload:migrate`: Sync Payload CMS tables.
-- `pnpm lint` / `pnpm format`: Quality and formatting checks (biome).
-- `pnpm email:dev`: Preview React Email templates locally.
-
-## Routes & APIs
-
-- `/`: Home with hero, latest posts, CTA.
-- `/posts`: Paginated posts; `/posts/[slug]`: detail with rich text, comments, share.
-- `/tags`: Tag cloud with counts.
-- `/login`: Google/GitHub login entry.
-- `/admin`: Payload CMS admin.
-- `/api/search`: Search index endpoint (fumadocs search).
-- `/rss.xml`: Atom/RSS feed.
-
-## Developer Notes
-
-- Prefer `./start-database.sh` to boot Postgres locally; the script warns if the port is in use.
-- Auth/comment tables use the `blog_` prefix—keep `drizzle.config.ts` `tablesFilter` in sync.
-- Payload dev mode pre-fills `admin@example.com` / `admin123` to speed up admin login.
-- If you only need to browse the UI without real data, set `SKIP_ENV_VALIDATION=1` and disable features needing external services; full env is recommended for complete coverage.