diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 24e916f..a340a9f 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -23,6 +23,10 @@ concurrency:
 jobs:
   build:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
     steps:
       - name: Checkout
         uses: actions/checkout@v7
@@ -52,6 +56,9 @@ jobs:
   deploy:
     needs: build
     runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
diff --git a/docs-site/en/guide/faq.md b/docs-site/en/guide/faq.md
index 5e9083b..4ced8ce 100644
--- a/docs-site/en/guide/faq.md
+++ b/docs-site/en/guide/faq.md
@@ -62,3 +62,14 @@ Use `data/mapping.json` from `migrate` preview. Keys are **storage paths**, not
 ## Docs vs README?
 
 This **VitePress site** is the full guide; README is a short overview. Online: <https://o96u.github.io/PicHost/>
+
+If you get 404, GitHub Pages may not be deployed yet: set **Settings → Pages → Source** to **GitHub Actions** and ensure the `docs` workflow `deploy` job succeeded. See [Local dev · Publish to GitHub Pages](./local-dev.md#publish-to-github-pages).
+
+## What should the GitHub repo About say?
+
+For **main**:
+
+- **Description**: `Self-hosted image hosting — Docker, multi-user, S3/R2 storage, Twikoo/EasyImage compatible.`
+- **Website**: `https://o96u.github.io/PicHost/` (docs, not a live demo)
+
+Do not claim the app runs on Cloudflare Pages/Workers. The **cloudflare** branch demo is [pic.roven.cc](https://pic.roven.cc).
diff --git a/docs-site/en/guide/local-dev.md b/docs-site/en/guide/local-dev.md
index 7fca011..67dbf37 100644
--- a/docs-site/en/guide/local-dev.md
+++ b/docs-site/en/guide/local-dev.md
@@ -52,3 +52,15 @@ npm run docs:preview
 ```
 
 Sources live in `docs-site/`; screenshot sources are in `docs/screenshots/` (including `login.png`), copied to `docs-site/public/screenshots/` before build.
+
+## Publish to GitHub Pages
+
+Live docs: <https://o96u.github.io/PicHost/>
+
+**First-time setup** (if deploy fails or the site 404s):
+
+1. Repo **Settings → Pages**
+2. **Build and deployment → Source** → **GitHub Actions** (not “Deploy from a branch”)
+3. Push to `main` or run the `docs` workflow manually from Actions
+
+Allow 1–2 minutes after a successful deploy. If the `deploy` job fails immediately, Pages is usually not enabled yet.
diff --git a/docs-site/guide/faq.md b/docs-site/guide/faq.md
index 1a29ff6..00d8c06 100644
--- a/docs-site/guide/faq.md
+++ b/docs-site/guide/faq.md
@@ -63,3 +63,14 @@ PicHost 双域名隔离**只对已配置的网站域、图片域做路径分流*
 ## 文档与仓库 README 哪个为准？
 
 **本 VitePress 文档站** 为完整用户指南；README 保留摘要与快速开始。在线地址：<https://o96u.github.io/PicHost/>
+
+若访问 404，说明 GitHub Pages 尚未部署成功：请在仓库 **Settings → Pages** 将 Source 设为 **GitHub Actions**，并确认 `docs` workflow 的 deploy 步骤已通过。详见 [本地开发 · 发布到 GitHub Pages](./local-dev.md#发布到-github-pages)。
+
+## GitHub 仓库 About 怎么写？
+
+**main** 分支建议：
+
+- **Description**：`Self-hosted image hosting — Docker, multi-user, S3/R2 storage, Twikoo/EasyImage compatible.`
+- **Website**：`https://o96u.github.io/PicHost/`（文档站，非图床演示）
+
+勿写「部署在 Cloudflare Pages/Workers」—— PicHost 应用跑在 Docker/VPS；**cloudflare** 分支在线演示为 [pic.roven.cc](https://pic.roven.cc)。
diff --git a/docs-site/guide/local-dev.md b/docs-site/guide/local-dev.md
index dcec8fa..289cb1a 100644
--- a/docs-site/guide/local-dev.md
+++ b/docs-site/guide/local-dev.md
@@ -52,3 +52,15 @@ npm run docs:preview  # 预览构建结果
 ```
 
 文档源码在 `docs-site/`；截图源文件在 `docs/screenshots/`（含 `login.png` 登录页），构建前会复制到 `docs-site/public/screenshots/`。
+
+## 发布到 GitHub Pages
+
+在线文档地址：<https://o96u.github.io/PicHost/>
+
+**首次启用**（部署 job 失败、访问 404 时检查）：
+
+1. 仓库 **Settings → Pages**
+2. **Build and deployment → Source** 选择 **GitHub Actions**（不要选 Deploy from a branch）
+3. 推送 `main` 触发 `docs` workflow，或在 Actions 页手动 **Run workflow**
+
+构建成功后约 1–2 分钟可访问。`docs` workflow 的 `deploy` 步骤失败且日志提示 Pages 未启用时，多为未完成上述设置。