docs: add mkdocs docs site

.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - master
+      - main
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v6
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v8.3.0
+        with:
+          python-version: "3.13"
+      - run: uv run --locked --group docs mkdocs build --strict --clean
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+      - uses: actions/deploy-pages@v5
+        id: deployment

.gitignore

@@ -3,6 +3,7 @@ __pycache__/
 .venv/
 .pytest_cache/
 dist/
+site/
 
 # gettext：.mo 是要 commit 的 ship 產物（無 build step，wheel 直接帶）；.pot 是抽字串模板。
 # 覆蓋全域 ~/.gitignore 的 *.mo / *.pot 規則。

CONTRIBUTING.md

@@ -1,5 +1,6 @@
 # Contributing to RiNG
 
+<!-- --8<-- [start:body] -->
 謝謝你願意幫 RiNG 變好。這份文件整理本 repo 的開發流程、測試方式與送 PR 前的檢查項目。
 
 ## 開發環境
@@ -32,6 +33,19 @@ uv run pytest tests/test_cli.py
 uv run pytest tests/test_cli.py::test_name
 ```
 
+## 文件建置
+
+文件使用 Material for MkDocs 與 `mkdocs-static-i18n`。`uv sync --all-groups` 會安裝文件依賴；本機預覽與正式檢查分別執行：
+
+```sh
+uv run poe docs:serve  # 在本機啟動可自動重載的文件站
+uv run poe docs:build  # 以 strict mode 建置到 site/
+```
+
+台灣華語是預設語言，來源檔使用 `name.md`；英文翻譯使用 `name.en.md`。兩種語言的文件內連結都應寫成未帶語言 suffix 的路徑，例如 `[Session 狀態](session-states.md)`，由 i18n plugin 自動連到目前語言。新增頁面時也要更新 `mkdocs.yml` 的 `nav`；menu 標題翻譯放在 `nav_translations`。
+
+送出文件變更前請執行 strict build。不要 commit `site/` 產物；GitHub Pages workflow 會從 lockfile 安裝 `docs` dependency group 並重新建置。
+
 ## Pre-commit Hooks
 
 建議安裝 hooks，讓格式化、lint、lockfile、commit message 檢查在本機先跑過。
@@ -49,7 +63,7 @@ uv run poe setup-pre-commit
 - Ruff 目標版本是 Python 3.13，行寬 120。
 - Mypy 使用 strict mode；新增 API 時請補齊型別。
 - CLI 行為、輸出格式、hook protocol、JSON keys 會被使用者腳本依賴；改動時請優先維持相容，必要 breaking change 要清楚標示。
-- 專案刻意允許台灣漢語註解與 UI 字串；新增英文 UI 時也要注意 i18n。
+- 專案刻意允許台灣華語註解與 UI 字串；新增英文 UI 時也要注意 i18n。
 
 ## 測試準則
 
@@ -79,16 +93,17 @@ uv run poe all
 改到使用者可見字串時，請更新翻譯檔。
 
 ```sh
-uv run poe i18n-extract
-uv run poe i18n-check
-uv run poe i18n-compile
+uv run poe i18n:extract
+uv run poe i18n:check
+uv run poe i18n:compile
 ```
 
 注意：不要用 `pybabel update`。這會把空 `msgstr` 塞進 `.po`，可能弄壞 i18n 測試。新字串請手動把已翻譯條目加進各語言 `.po`，再重新 compile 並 commit `.po` 與 `.mo`。
 
 ## Commit 與 Changelog
 
-本專案使用 Commitizen / Conventional Commits，commit message 例如：
+本專案使用 [Commitizen](https://commitizen-tools.github.io/commitizen/) /
+[Conventional Commits](https://www.conventionalcommits.org/)，commit message 例如：
 
 ```text
 feat: add webhook retry backoff
@@ -108,6 +123,7 @@ test: cover tmux permission parsing
 - `uv.lock` 與依賴設定一致。
 - 使用者可見字串已處理 i18n。
 - README / docs 已同步更新 CLI 旗標、設定鍵、輸出格式或行為變更。
+- 文件變更已通過 `uv run poe docs:build`，中英文頁面、導覽與內部連結保持同步。
 - 有 breaking change 時，PR 說明清楚列出影響與遷移方式。
 
 ## 回報 Issue
@@ -120,3 +136,4 @@ test: cover tmux permission parsing
 - 若和 hook / focus / permission reply 有關，請附 `ring doctor` 的相關段落。
 
 請不要貼出含有 token、private key、完整私有 transcript 或其他敏感資訊的內容。
+<!-- --8<-- [end:body] -->

docs/contributing.en.md

@@ -0,0 +1,152 @@
+# Contributing to RiNG
+
+Thanks for wanting to help make RiNG better. This page covers the dev workflow, how to test, and
+what to check before opening a PR.
+
+## Dev environment
+
+RiNG needs Python 3.13+; the project manages dependencies and the run environment with `uv`.
+
+```sh
+uv sync --all-groups
+uv run ring
+uv run ring --watch
+```
+
+The PyPI distribution name is `ring-cli`, but the Python module and CLI command are both `ring`.
+
+## Common commands
+
+```sh
+uv run poe format       # ruff check --fix + ruff format
+uv run poe lint         # ruff check + mypy
+uv run poe test         # pytest
+uv run poe cover        # pytest + coverage report
+uv run poe all          # format + lint + coverage
+uv run poe ci           # pre-commit hooks + coverage
+```
+
+Tests run in parallel via `pytest-xdist` by default; to run a single test, invoke pytest directly:
+
+```sh
+uv run pytest tests/test_cli.py
+uv run pytest tests/test_cli.py::test_name
+```
+
+## Documentation
+
+The site uses Material for MkDocs and `mkdocs-static-i18n`. `uv sync --all-groups` installs the documentation dependencies. Preview and validate the site with:
+
+```sh
+uv run poe docs:serve  # local server with live reload
+uv run poe docs:build  # strict build into site/
+```
+
+Taiwanese Mandarin is the default language and uses `name.md`; English translations use `name.en.md`. Links in both languages must omit the locale suffix—for example, `[Session states](session-states.md)`—so the i18n plugin resolves the current language. When adding a page, update `nav` in `mkdocs.yml` and put menu-label translations under `nav_translations`.
+
+Run the strict build before submitting documentation changes. Do not commit `site/`; the GitHub Pages workflow installs the locked `docs` dependency group and rebuilds it.
+
+## Pre-commit hooks
+
+Installing the hooks is recommended, so formatting, lint, lockfile, and commit-message checks all
+run locally first.
+
+```sh
+uv run poe setup-pre-commit
+```
+
+The hooks currently check TOML/YAML, private keys, spelling, `uv.lock`, Ruff, Mypy, Commitizen,
+and more. `no-commit-to-branch` blocks direct commits to protected branches — work on a feature
+branch when needed.
+
+## Code style
+
+- Python source lives in `src/ring/`, tests in `tests/`.
+- Ruff targets Python 3.13, line width 120.
+- Mypy runs in strict mode; add complete types for any new API.
+- CLI behavior, output formats, the hook protocol, and JSON keys are relied on by users' own
+  scripts — prefer compatibility when changing them, and clearly flag any necessary breaking
+  change.
+- The project deliberately allows Taiwanese Mandarin comments and UI strings; mind i18n when
+  adding new English-facing UI too.
+
+## Testing guidelines
+
+Add tests scoped to what you changed:
+
+- CLI args and output: `tests/test_cli.py`
+- TUI / render behavior: `tests/test_tui.py`, `tests/test_render.py`
+- Source discovery: `tests/test_sources.py`, `tests/test_discover.py`
+- Hook / registry / IPC: `tests/test_hook.py`, `tests/test_registry.py`, `tests/test_ipc.py`
+- Notifier / focus / permission reply: `tests/test_notify.py`, `tests/test_focus.py`,
+  `tests/test_permission.py` respectively
+
+Run at least this before opening a PR:
+
+```sh
+uv run poe lint
+uv run poe test
+```
+
+If the change touches cross-module behavior, output formats, or release-related settings, run:
+
+```sh
+uv run poe all
+```
+
+## i18n
+
+If your change touches user-facing strings, update the translation files.
+
+```sh
+uv run poe i18n:extract
+uv run poe i18n:check
+uv run poe i18n:compile
+```
+
+Note: don't use `pybabel update` — it stuffs empty `msgstr` entries into `.po` files and can break
+the i18n tests. Add new strings' translated entries by hand to each language's `.po` file, then
+recompile and commit both the `.po` and `.mo` files.
+
+## Commits and changelog
+
+This project uses [Commitizen](https://commitizen-tools.github.io/commitizen/) /
+[Conventional Commits](https://www.conventionalcommits.org/), e.g.:
+
+```text
+feat: add webhook retry backoff
+fix: keep stale codex sessions hidden
+docs: document hook setup
+test: cover tmux permission parsing
+```
+
+Versioning and the changelog are managed by Commitizen. Regular PRs shouldn't hand-edit
+`CHANGELOG.md` unless you're doing a release / bump.
+
+## PR checklist
+
+Before opening a PR, confirm:
+
+- The change is scoped tightly, with no unrelated formatting or build artifacts mixed in.
+- New features or bug fixes have matching tests, or the PR description explains why they can't be
+  tested.
+- `uv.lock` is consistent with the dependency configuration.
+- User-facing strings have been run through i18n.
+- README / docs have been updated for any changed CLI flags, config keys, output format, or
+  behavior.
+- Documentation changes pass `uv run poe docs:build`, with translated pages, navigation, and
+  internal links kept in sync.
+- Any breaking change is called out clearly in the PR description, with its impact and migration
+  path.
+
+## Reporting an issue
+
+Please include, where possible:
+
+- OS and terminal environment, e.g. macOS + iTerm2, tmux, Linux X11 / Wayland.
+- `ring --version` and how it was installed.
+- The relevant commands and their actual output.
+- If it's related to hooks / focus / permission reply, the relevant section of `ring doctor`.
+
+Please don't paste content containing tokens, private keys, full private transcripts, or other
+sensitive information.

docs/contributing.md

@@ -0,0 +1,3 @@
+# 貢獻指南
+
+--8<-- "CONTRIBUTING.md:body"