Release/v0.3.0

AGENTS.md

@@ -117,6 +117,38 @@ cd ..\server && dart analyze  # demo backend
 cd d:\FlutterProgram\zero_auth && dart pub publish --dry-run   # 0 warnings
 ```
 
+### Docs site preflight (always run before pushing `website/**`)
+
+The Pages site is **pre-built**: `pages.yml` uploads `docs/` verbatim and never
+builds `website/`. `docs/` is regenerated only by the git pre-commit hook, so an
+uninstalled hook silently ships a stale site — missing pages, and an outdated
+version on the Installation page because `__ZERO_AUTH_VERSION__` is injected at
+build time.
+文档站是**预先构建**的：`pages.yml` 原样上传 `docs/`，从不构建 `website/`。`docs/`
+只由 git pre-commit hook 重建，hook 未安装会导致线上静默停留在旧站点——缺页面，且安装
+页版本号过期（`__ZERO_AUTH_VERSION__` 是在构建时注入的）。
+
+```powershell
+# Once per clone — installs the hook that rebuilds & syncs docs/.
+# 每个克隆仅需一次——安装负责重建并同步 docs/ 的 hook。
+npm --prefix website run setup-hook
+
+# Sanity check — this must return True.
+# 检查——必须返回 True。
+Test-Path .git\hooks\pre-commit
+
+# Recovery — website/ already committed and docs/ still stale.
+# 补救——website/ 改动已提交、docs/ 仍是旧的。
+node website/scripts/sync-docs.mjs --force
+```
+
+> **Symptom → cause / 症状 → 原因:** you changed `website/**` (or bumped the
+> version) but `git status` shows no `docs/` changes ⇒ the hook is missing. Run
+> the setup command above, then the `--force` sync once to catch up.
+>
+> 你改了 `website/**`（或升了版本号）而 `git status` 里没有 `docs/` 变化 ⇒ hook 未安装。
+> 先执行上面的安装命令，再跑一次 `--force` 补构建。
+
 ### Running the demo end to end
 ```powershell
 # Terminal 1 — demo backend

CONTRIBUTING.md

@@ -40,6 +40,25 @@ cd example && flutter analyze && flutter test
 cd ..\server && dart analyze
 ```
 
+## Docs site / 文档站
+
+The Pages site is served from the **pre-built** `docs/` folder; it is regenerated
+from `website/out/` by a git pre-commit hook. The hook must be installed once per
+clone, otherwise edits under `website/` never reach GitHub Pages.
+
+文档站由**预先构建**的 `docs/` 目录提供，它由 git pre-commit hook 从 `website/out/`
+重新生成。每个克隆必须安装一次该 hook，否则你在 `website/` 下的改动永远不会上线。
+
+```powershell
+npm --prefix website run setup-hook
+```
+
+If you changed `website/**` but `git status` shows no `docs/` changes, the hook is
+missing — reinstall it and run `node website/scripts/sync-docs.mjs --force` once.
+
+若你改了 `website/**` 而 `git status` 中没有 `docs/` 变化，说明 hook 未安装——重装它，
+再手动执行一次 `node website/scripts/sync-docs.mjs --force`。
+
 ## Branching & pull requests
 
 - Branch from `main` with a typed prefix: `feat/`, `fix/`, `docs/`, `ci/`,

docs/404.html

@@ -1 +1 @@
-<!DOCTYPE html><html><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width"/><title>404: This page could not be found</title><meta name="next-head-count" content="3"/><link rel="preload" href="/zero_auth/_next/static/css/df9fc72061aac7da.css" as="style"/><link rel="stylesheet" href="/zero_auth/_next/static/css/df9fc72061aac7da.css" data-n-g=""/><noscript data-n-css=""></noscript><script defer="" nomodule="" src="/zero_auth/_next/static/chunks/polyfills-42372ed130431b0a.js"></script><script src="/zero_auth/_next/static/chunks/webpack-ee0888e50db50cb2.js" defer=""></script><script src="/zero_auth/_next/static/chunks/framework-64ad27b21261a9ce.js" defer=""></script><script src="/zero_auth/_next/static/chunks/main-e89c517208c83521.js" defer=""></script><script src="/zero_auth/_next/static/chunks/pages/_app-0cbc53ae873ef8d1.js" defer=""></script><script src="/zero_auth/_next/static/chunks/pages/_error-7a92967bea80186d.js" defer=""></script><script src="/zero_auth/_next/static/xA0AkSUGK7rA_hFr787Ng/_buildManifest.js" defer=""></script><script src="/zero_auth/_next/static/xA0AkSUGK7rA_hFr787Ng/_ssgManifest.js" defer=""></script></head><body><div id="__next"><div style="font-family:system-ui,&quot;Segoe UI&quot;,Roboto,Helvetica,Arial,sans-serif,&quot;Apple Color Emoji&quot;,&quot;Segoe UI Emoji&quot;;height:100vh;text-align:center;display:flex;flex-direction:column;align-items:center;justify-content:center"><div style="line-height:48px"><style>body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}</style><h1 class="next-error-h1" style="display:inline-block;margin:0 20px 0 0;padding-right:23px;font-size:24px;font-weight:500;vertical-align:top">404</h1><div style="display:inline-block"><h2 style="font-size:14px;font-weight:400;line-height:28px">This page could not be found<!-- -->.</h2></div></div></div></div><script id="__NEXT_DATA__" type="application/json">{"props":{"pageProps":{"statusCode":404}},"page":"/_error","query":{},"buildId":"xA0AkSUGK7rA_hFr787Ng","assetPrefix":"/zero_auth","nextExport":true,"isFallback":false,"gip":true,"scriptLoader":[]}</script></body></html>
+<!DOCTYPE html><html><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width"/><title>404: This page could not be found</title><meta name="next-head-count" content="3"/><link rel="preload" href="/zero_auth/_next/static/css/df9fc72061aac7da.css" as="style"/><link rel="stylesheet" href="/zero_auth/_next/static/css/df9fc72061aac7da.css" data-n-g=""/><noscript data-n-css=""></noscript><script defer="" nomodule="" src="/zero_auth/_next/static/chunks/polyfills-42372ed130431b0a.js"></script><script src="/zero_auth/_next/static/chunks/webpack-ee0888e50db50cb2.js" defer=""></script><script src="/zero_auth/_next/static/chunks/framework-64ad27b21261a9ce.js" defer=""></script><script src="/zero_auth/_next/static/chunks/main-e89c517208c83521.js" defer=""></script><script src="/zero_auth/_next/static/chunks/pages/_app-0cbc53ae873ef8d1.js" defer=""></script><script src="/zero_auth/_next/static/chunks/pages/_error-7a92967bea80186d.js" defer=""></script><script src="/zero_auth/_next/static/8slIfVBTb0f8-uhdir3Fp/_buildManifest.js" defer=""></script><script src="/zero_auth/_next/static/8slIfVBTb0f8-uhdir3Fp/_ssgManifest.js" defer=""></script></head><body><div id="__next"><div style="font-family:system-ui,&quot;Segoe UI&quot;,Roboto,Helvetica,Arial,sans-serif,&quot;Apple Color Emoji&quot;,&quot;Segoe UI Emoji&quot;;height:100vh;text-align:center;display:flex;flex-direction:column;align-items:center;justify-content:center"><div style="line-height:48px"><style>body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}</style><h1 class="next-error-h1" style="display:inline-block;margin:0 20px 0 0;padding-right:23px;font-size:24px;font-weight:500;vertical-align:top">404</h1><div style="display:inline-block"><h2 style="font-size:14px;font-weight:400;line-height:28px">This page could not be found<!-- -->.</h2></div></div></div></div><script id="__NEXT_DATA__" type="application/json">{"props":{"pageProps":{"statusCode":404}},"page":"/_error","query":{},"buildId":"8slIfVBTb0f8-uhdir3Fp","assetPrefix":"/zero_auth","nextExport":true,"isFallback":false,"gip":true,"scriptLoader":[]}</script></body></html>

docs/404/index.html

@@ -1 +1 @@
-<!DOCTYPE html><html><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width"/><title>404: This page could not be found</title><meta name="next-head-count" content="3"/><link rel="preload" href="/zero_auth/_next/static/css/df9fc72061aac7da.css" as="style"/><link rel="stylesheet" href="/zero_auth/_next/static/css/df9fc72061aac7da.css" data-n-g=""/><noscript data-n-css=""></noscript><script defer="" nomodule="" src="/zero_auth/_next/static/chunks/polyfills-42372ed130431b0a.js"></script><script src="/zero_auth/_next/static/chunks/webpack-ee0888e50db50cb2.js" defer=""></script><script src="/zero_auth/_next/static/chunks/framework-64ad27b21261a9ce.js" defer=""></script><script src="/zero_auth/_next/static/chunks/main-e89c517208c83521.js" defer=""></script><script src="/zero_auth/_next/static/chunks/pages/_app-0cbc53ae873ef8d1.js" defer=""></script><script src="/zero_auth/_next/static/chunks/pages/_error-7a92967bea80186d.js" defer=""></script><script src="/zero_auth/_next/static/xA0AkSUGK7rA_hFr787Ng/_buildManifest.js" defer=""></script><script src="/zero_auth/_next/static/xA0AkSUGK7rA_hFr787Ng/_ssgManifest.js" defer=""></script></head><body><div id="__next"><div style="font-family:system-ui,&quot;Segoe UI&quot;,Roboto,Helvetica,Arial,sans-serif,&quot;Apple Color Emoji&quot;,&quot;Segoe UI Emoji&quot;;height:100vh;text-align:center;display:flex;flex-direction:column;align-items:center;justify-content:center"><div style="line-height:48px"><style>body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}</style><h1 class="next-error-h1" style="display:inline-block;margin:0 20px 0 0;padding-right:23px;font-size:24px;font-weight:500;vertical-align:top">404</h1><div style="display:inline-block"><h2 style="font-size:14px;font-weight:400;line-height:28px">This page could not be found<!-- -->.</h2></div></div></div></div><script id="__NEXT_DATA__" type="application/json">{"props":{"pageProps":{"statusCode":404}},"page":"/_error","query":{},"buildId":"xA0AkSUGK7rA_hFr787Ng","assetPrefix":"/zero_auth","nextExport":true,"isFallback":false,"gip":true,"scriptLoader":[]}</script></body></html>
+<!DOCTYPE html><html><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width"/><title>404: This page could not be found</title><meta name="next-head-count" content="3"/><link rel="preload" href="/zero_auth/_next/static/css/df9fc72061aac7da.css" as="style"/><link rel="stylesheet" href="/zero_auth/_next/static/css/df9fc72061aac7da.css" data-n-g=""/><noscript data-n-css=""></noscript><script defer="" nomodule="" src="/zero_auth/_next/static/chunks/polyfills-42372ed130431b0a.js"></script><script src="/zero_auth/_next/static/chunks/webpack-ee0888e50db50cb2.js" defer=""></script><script src="/zero_auth/_next/static/chunks/framework-64ad27b21261a9ce.js" defer=""></script><script src="/zero_auth/_next/static/chunks/main-e89c517208c83521.js" defer=""></script><script src="/zero_auth/_next/static/chunks/pages/_app-0cbc53ae873ef8d1.js" defer=""></script><script src="/zero_auth/_next/static/chunks/pages/_error-7a92967bea80186d.js" defer=""></script><script src="/zero_auth/_next/static/8slIfVBTb0f8-uhdir3Fp/_buildManifest.js" defer=""></script><script src="/zero_auth/_next/static/8slIfVBTb0f8-uhdir3Fp/_ssgManifest.js" defer=""></script></head><body><div id="__next"><div style="font-family:system-ui,&quot;Segoe UI&quot;,Roboto,Helvetica,Arial,sans-serif,&quot;Apple Color Emoji&quot;,&quot;Segoe UI Emoji&quot;;height:100vh;text-align:center;display:flex;flex-direction:column;align-items:center;justify-content:center"><div style="line-height:48px"><style>body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}</style><h1 class="next-error-h1" style="display:inline-block;margin:0 20px 0 0;padding-right:23px;font-size:24px;font-weight:500;vertical-align:top">404</h1><div style="display:inline-block"><h2 style="font-size:14px;font-weight:400;line-height:28px">This page could not be found<!-- -->.</h2></div></div></div></div><script id="__NEXT_DATA__" type="application/json">{"props":{"pageProps":{"statusCode":404}},"page":"/_error","query":{},"buildId":"8slIfVBTb0f8-uhdir3Fp","assetPrefix":"/zero_auth","nextExport":true,"isFallback":false,"gip":true,"scriptLoader":[]}</script></body></html>

docs/_next/static/chunks/nextra-page-map-.mjs

@@ -55,6 +55,18 @@ export const pageMap = [{
   frontMatter: {
     "sidebarTitle": "Network Integration"
   }
+}, {
+  name: "Persistence",
+  route: "/Persistence",
+  frontMatter: {
+    "sidebarTitle": "Persistence"
+  }
+}, {
+  name: "Third-Party-Login",
+  route: "/Third-Party-Login",
+  frontMatter: {
+    "sidebarTitle": "Third Party Login"
+  }
 }, {
   name: "Token-Store",
   route: "/Token-Store",