CONTRIBUTING.md:414 「All docs are in `docs/`」与现状不符 —— 站点文档实际在 `content/docs/`,`docs/` 是内部树

[yinlianghui]

修 #3570(PR 见该单)时在同一节读到的第三处过期陈述。#3570 的文件面被 PM 明确限定为「Documentation 节的那两处 + 一句提示」,本处不在其中,按 Prime Directive #10 未在那个 PR 里改,另立本单。

现文(CONTRIBUTING.md:412-414,### Writing Documentation)

We use fumadocs for documentation. All docs are in docs/.

与现状对不上

• 站点(fumadocs)的文档源根本不是 docs/。apps/site/source.config.ts:6 写的是 dir: '../../content/docs' —— 已发布的 183 篇文档全在 content/docs/**;
• 仓库根的 docs/ 是内部材料树(adr/、audits/、ARCHITECTURE.md、screenshots/),不进站点、没有 /docs/... 路由;
• 这个区分在别处是被当作前提写死的:.github/workflows/check-links.yml 的头注释专门记了 check-links.yml(Lychee)扫的是 docs/**(15 个文件),不是站点文档 content/docs/**(183 个文件) #3449 的教训 —— lychee 的扫描面曾经只指向仓库根 docs/**,「had therefore never scanned a single published page」;scripts/check-doc-links.mjs 的 SCAN_ROOTS 也是把 content/docs(docs 路由语义)和其余磁盘路径分开的。

也就是说:唯独 CONTRIBUTING.md 这句还停在搬迁前,而它恰好是新贡献者「文档该写在哪」的第一落点。照它做的人会把新页面放进 docs/,站点上永远不出现,链接门禁也不看那棵树(SCAN_ROOTS 里没有它)。

为什么门禁抓不到

这是散文里的一句目录名断言,不是链接 —— check-doc-links.mjs 只解析 markdown 链接,docs/ 写在反引号里(反而会被 stripCode() 抹掉)。没有任何检查会因为这句话变假而变红,只能靠人读到。

复现(只读,离线)

grep -n 'All docs are in' CONTRIBUTING.md
grep -n 'dir:' apps/site/source.config.ts     # => dir: '../../content/docs'
ls docs/                                       # => adr audits ARCHITECTURE.md screenshots ...
ls content/docs/                               # => api blocks components core fields guide layout plugins rfcs utilities

建议

把这句改成如实的两句:站点文档写在 content/docs/**(fumadocs collection,baseUrl: '/docs');仓库根 docs/ 放 ADR / 审计等不发布的内部材料。顺带确认紧随其后的 pnpm site:dev / pnpm site:build 两条命令仍然有效(本单未逐条核实这两条)。

关联

#3570(同节两处过期陈述,PR 在飞)、#3545(同节 3 条死链)、#3449(lychee 扫描面曾指错到 docs/** 的同源错误)、#3536 / #3572(SCAN_ROOTS 扫描面扩展)。

⚠️ 本单未认领,留给 PM 分诊。

[claude]

Triage: pm:queue. No domain:* — objectui is a whole-repo seat, so routing is the repo, not a domain lane. Repo-local prose fix, no packages/spec surface, not feature-level, not cross-repo ⇒ no transfer to the objectstack backlog.

Why queueable rather than a finding: one file, one sentence, four offline read-only repro commands in the body, and the correct replacement text is already drafted. The landing site is CONTRIBUTING.md:414 alone (the suggested "confirm pnpm site:dev / site:build still work" is a verification step inside the same edit, not extra scope).

Premise re-checked against origin/main: CONTRIBUTING.md:414 still reads "We use fumadocs for documentation. All docs are in docs/." — verified after #3585 landed. Last touches on that file: #3585 (#3570's PR, merged) and #3571 (#3545's, merged).

Dedupe + collision check (three repos, issues + PRs): no duplicate. The near neighbours are all closed or merged, so the collision that would have blocked this card is already gone:

• CONTRIBUTING.md 的 Documentation 一节有两处与仓库现状不符:门禁描述指错工具/触发条件,"✅ 正确链接示例" 里 3 条路由是死的 #3570 — closed, its PR docs(contributing): 按现状改写链接门禁分工,换掉三条死的"正确示例"路由 (#3570) #3585 merged; it rewrote the other two stale statements in this same ### Writing Documentation section. Its scope was explicitly fenced to exclude this sentence, which is why this card exists.
• CONTRIBUTING.md / ROADMAP.md 共 3 条死链:处在 check-doc-links 与 lychee 的双重扫描盲区 #3545 / docs: 修正 CONTRIBUTING.md / ROADMAP.md 的 3 条死链 #3571 — merged, dead-link fixes in the same file.
• check-links.yml(Lychee)扫的是 docs/**(15 个文件),不是站点文档 content/docs/**(183 个文件) #3449, check-doc-links 门禁两向扩展:扫描面扩到 examples/** + 根 README,可判定 href 形态扩到指向本仓的 GitHub 绝对 URL #3536 / check-doc-links 扫描面第三扩:CONTRIBUTING.md + ROADMAP.md + docs/**(实测 70 链接、今日零死链、纯配置三行) #3572 — the same-root docs/** vs content/docs/** scan-surface family, cross-linked for context only.

No gate can catch this (a directory-name assertion inside backticks, stripped by stripCode() before the link checker sees it), so the fix is prose-only with no test to add.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[yinlianghui]

认领(PM 分诊晋级;同文件串行条件已满足 —— PR #3585 已落 main)— 会话 session_01GTRjn8xBqp75dk7kFupVRt,分支 claude/issue-3584-contrib-docs-dir。

按正文修:CONTRIBUTING.md:414 附近「All docs are in docs/」改写为现实(站点源 = content/docs/,锚点 apps/site/source.config.ts:6;根 docs/ 是 ADR/审计内部树)—— 措辞按机制不按枚举,读全节保证与 #3585 刚改写的门禁分工段连贯。文件面:CONTRIBUTING.md 仅该处。越界即停。

---

Generated by Claude Code

[yinlianghui]

验收:ACCEPT — PR #3597(恰 1 文件,+5/-3)。要点:前瞻性措辞纪律(刻意不写"门禁不扫 docs/"—— #3589 落地当天即假)背书;用导出 SCAN_ROOTS 预演未来 4 根扫描面(0 broken)补上"空绿"的证据缺口;相邻 bash 注释的最小改动在围栏内且必要;#3596(三条不存在的命令,同迁移滞后类)已核存在,⚠️ 同文件等本 PR 落 main 再派。PR 转 ready + auto-merge。

---

Generated by Claude Code