docs(plugin-auth,client): 两处仓内文档不再把四条不存在的 auth 端点写成已注册路由 (#5772)

[baozhoutao]

Fixes #5772

docs-only, skip-changeset requested（两份仓内开发文档，发布不可见，无 changeset）。

前提复核（改前对 origin/main 实读）

issue 的前提成立，两处都还在 a3a884d7a（当时的 origin/main）上：

• packages/plugins/plugin-auth/IMPLEMENTATION_SUMMARY.md:89-94 —— 标题就是 "API Routes Registered"，列 POST /api/v1/auth/login / register / logout 与 GET /api/v1/auth/session；
• packages/client/CLIENT_SERVER_INTEGRATION_TESTS.md:642 —— MSW 示例 rest.post('/api/v1/auth/login', …)。

四条端点确实一条都不存在，逐条核对了三个独立事实源：

1. packages/plugins/plugin-auth/src/auth-route-ledger.ts（Enumerate the /auth/** dynamic route family — 54 SDK methods rest on a prefix claim, not a route #3656）逐条枚举 55 条 SDK 可达路由 + 完整 mounted inventory，四个名字零命中；真名分别是 POST /api/v1/auth/sign-in/email（auth.login）、POST /api/v1/auth/sign-up/email（auth.register）、POST /api/v1/auth/sign-out（auth.logout）、GET /api/v1/auth/get-session（auth.me）。
2. packages/client/src/index.ts:2109-2170 的 SDK 实现打的就是这四条真名（login 注释即 "Uses better-auth endpoint: POST /sign-in/email"）。
3. packages/plugins/plugin-auth/src/auth-plugin.ts:2109 是单条 catch-all rawApp.all(${basePath}/*) 整体转发给 better-auth，前面另挂了 ObjectStack 自有的 /config、/bootstrap-status、/admin/* 等；没有任何 login/register/logout/session 显式路由。

改动

IMPLEMENTATION_SUMMARY.md：整节改名为 "API Routes"，采纳 issue 的防再漂建议 —— 指向 src/auth-route-ledger.ts 这一单一事实源（并说明台账由 auth-route-ledger.conformance.test.ts 对活的 auth.api 表校验），只保留四条核心路由的真名作最小示例，端点名与 content/docs/api/plugin-endpoints.mdx 完全一致；末尾明写这四个旧名字不存在，唯一让 /auth/login 看起来可达的遗留显式挂载在 runtime dispatcher 里、对任何调用方都只 500、已在 #5085 删除。手抄整表会再漂，指向台账不会 —— 被删掉的那一节本身就是证据。

同文件 :35 的 "Route registration - HTTP endpoints for login, register, logout, session" 是同一处虚假声明的另一种拼写（同一文件、同一缺陷，属本 issue 面），一并改为「auth base path 整体转发给 better-auth」并链到上面那节。

CLIENT_SERVER_INTEGRATION_TESTS.md：MSW 示例改用真实端点 POST /api/v1/auth/sign-in/email，注释里写清四个 SDK 方法各自打到哪条路由、台账文件在哪。示例的响应体未动（{ success, data: { token, user, expiresAt } }）—— 那不是本 issue 的判读面，且 SDK 的 login 对 data 包封与 better-auth 的顶层 { token, user } 两种形状都做归一（index.ts:2131），示例照旧可用。

验收：改后 git grep 的逐条判定

git grep -n "api/v1/auth/login" -- '*.md' 改后剩两条，均判定为框定正确、留：

命中	判定
.changeset/auth-unknown-subpath-clean-404.md:10	#5085 自己的 changeset，POST /api/v1/auth/login 出现在实测输出块里，正文明写该路由「could not work for any caller」「It is deleted」。这是在记录一条被删除的路由，不是声称它存在 —— 留。
packages/plugins/plugin-auth/IMPLEMENTATION_SUMMARY.md:116	本 PR 新写的否定句（「唯一那条遗留挂载……已在 #5085 删除」）—— 按构造即正确框定。

放宽到 git grep -n "auth/login" -- '*.md' '*.mdx'，另外三条同样留：content/docs/api/plugin-endpoints.mdx:18（"There is no /auth/login route"，本来就是对的）、CLIENT_SERVER_INTEGRATION_TESTS.md:641（本 PR 新写的否定注释）、packages/plugins/plugin-auth/ARCHITECTURE.md:74（实读确认 :74 与 :79 都在 "#### Before (Manual Approach)" 代码块内，下面紧接 "#### After (Direct Forwarding)" 的 wildcard 写法，框定正确 —— issue 已论证不改，本 PR 未动）。

git grep -nE "auth/(register|logout|session)" -- '*.md' '*.mdx' 的其余命中全部是 CHANGELOG/changeset 里 #4251 的「auth/session slot lookups」，指服务槽位不是路由，非本类。

验证

纯 markdown，无代码面、无测试面。跑的是与改动面相关的门：

node scripts/check-nul-bytes.mjs
→ check-nul-bytes: OK (scanned 5687 tracked text file(s); ... no raw ASCII control bytes).

grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' <两个文件>   → 无命中

node scripts/check-doc-authoring.mjs --self-test && node scripts/check-doc-authoring.mjs
→ ✓ doc authoring guard: 362 files clean — no bare metadata literals.

node scripts/docs-audit/check-audit-scope.mjs --self-test && node scripts/docs-audit/check-audit-scope.mjs
→ ✓ docs-accuracy-audit scope is in sync with content/docs/: 178 hand-written doc(s).

另核对了两条新增相对链接在磁盘上都解析得到：./src/auth-route-ledger.ts、../../../content/docs/api/plugin-endpoints.mdx。

关联：#5085（发现现场）、#3656（auth 路由台账的来源）。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 6, 2026 6:40am

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/client, @objectstack/plugin-auth.

21 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/ai/skills-reference.mdx (via packages/client)
• content/docs/api/client-sdk.mdx (via @objectstack/client)
• content/docs/api/data-flow.mdx (via @objectstack/client)
• content/docs/api/environment-routing.mdx (via @objectstack/client)
• content/docs/api/error-catalog.mdx (via @objectstack/client)
• content/docs/deployment/cli.mdx (via @objectstack/plugin-auth)
• content/docs/deployment/production-readiness.mdx (via @objectstack/plugin-auth)
• content/docs/getting-started/your-first-project.mdx (via @objectstack/client)
• content/docs/kernel/contracts/cache-service.mdx (via @objectstack/plugin-auth)
• content/docs/kernel/runtime-services/data-service.mdx (via packages/client)
• content/docs/kernel/runtime-services/index.mdx (via packages/client)
• content/docs/kernel/services-checklist.mdx (via @objectstack/plugin-auth)
• content/docs/permissions/authentication.mdx (via @objectstack/client, @objectstack/plugin-auth)
• content/docs/permissions/sso.mdx (via @objectstack/plugin-auth)
• content/docs/plugins/index.mdx (via @objectstack/plugin-auth)
• content/docs/plugins/packages.mdx (via @objectstack/client, @objectstack/plugin-auth)
• content/docs/protocol/kernel/realtime-protocol.mdx (via @objectstack/client)
• content/docs/releases/implementation-status.mdx (via @objectstack/client, @objectstack/plugin-auth)
• content/docs/releases/v16.mdx (via @objectstack/client)
• content/docs/releases/v17.mdx (via @objectstack/client)
• content/docs/releases/v9.mdx (via @objectstack/plugin-auth)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.