Tidy the contributor docs, templates and internal package READMEs #486

Summary

Small gaps in the contributor and community files. Each item is a short text change. They show contributors where to ask, what CI does on a fork pull request, that the design system is locked, and which workflows exist.

• Severity: Low. Each gap costs a reader little time, and none blocks a step.
• Area: README.md, docs/README.md, CONTRIBUTING.md, .github/, CHANGELOG.md, packages/
• Source: docs and README review of 2026-10-14. Five review agents each covered one docs area. A separate agent then checked each finding against the code and tried to refute it. Every item below survived that check. "Checked" lists the evidence.

Items

1. GitHub Discussions is turned on, but the README Support list does not name it as a place to ask questions.

• Where: README.md:362
• Severity: low
• Checked: README.md:362-369 lists Discord, Twitter, the GitHub repo, email, Privacy and Terms. It does not name GitHub Discussions. gh repo view returns hasDiscussionsEnabled: true, and the repo has a "Q&A" category in use. .github/ISSUE_TEMPLATE/feature_request.md:31 asks people to search "existing issues and discussions first", but no public doc links there. CONTRIBUTING.md §Getting Help (line 420) does not name Discussions either. Severity is low: the gap only hides questions that were already answered.
• Fix: In README.md §Support, add one line: "- 💬 Questions and ideas: GitHub Discussions". Add the same line to CONTRIBUTING.md §Getting Help. Make the security reporting channel reachable, and make SECURITY.md agree with itself #481 item 4 and Tidy the contributor docs, templates and internal package READMEs #486 item 1 each add one line to README §Support. Whichever lands second keeps the other's line. This item owns CONTRIBUTING.md §Getting Help. Replace the expired Discord invite in the docs and the app #480 changes only the Discord invite code in both lists.

2. The hub's Conventions line says every page opens with a scope line, but three listed pages do not.

• Where: docs/README.md:64
• Severity: low
• Checked: docs/README.md:64 says "Each page opens with one line stating what it covers and what it does not." Of the 17 tracked docs/.md pages, every guide page follows it: api/, mcp/, self-hosting/, roadmap/* and RUNBOOK-backend.md. Three pages do not. docs/DEMO.md opens with an image. docs/adr/0002-mobile-chat-pane.md opens with "Status: Accepted · Date: 2026-07-29". docs/adr/0001-document-swarm.md opens with decision context. Changing those pages is the wrong fix. DEMO.md is the Markdown source of the live https://docs.plus/demo page (docs/README.md:35), so a scope line would show on the demo. ADRs follow the usual decision-record form. Narrowing the rule is the smallest fix.
• Fix: In docs/README.md:64, replace the line with: "- Each guide page opens with one line stating what it covers and what it does not. Decision records and DEMO.md follow their own form."

3. CONTRIBUTING does not tell an outside contributor what CI does on a fork pull request.

• Where: CONTRIBUTING.md:413
• Severity: low
• Checked: gh api repos/docs-plus/docs.plus/actions/permissions/fork-pr-contributor-approval returns {"approval_policy":"all_external_contributors"}. So CI on a fork pull request waits until a maintainer approves the run. In .github/workflows/chatroom-e2e.yml:42-44, the job runs on a pull request only when head.repo.full_name == github.repository. So it skips every fork pull request, and runs on push to main after merge (.github/workflows/chatroom-e2e.yml:18-19). scripts/test-chatroom.sh:8-11 exits unless NEXT_PUBLIC_VIRTUOSO_LICENSE is set, so a contributor without that commercial license cannot run the suite. CONTRIBUTING.md:388-418 (§Creating a Pull Request, §Pull Request Review Process) says nothing about run approval or the skipped suite. Neither does .github/PULL_REQUEST_TEMPLATE.md. The Fix lists no CI jobs, so it cannot drift from .github/workflows/prod.docs.plus.yml.
• Fix: Under 'Pull Request Review Process' in CONTRIBUTING.md, add: 'CI on a fork pull request starts only after a maintainer approves the run. The chatroom browser tests need a commercial license secret, so they skip fork pull requests and run on main after merge.'

4. CONTRIBUTING invites UI and design work but never says the design system is locked and maintainer-owned.

• Where: CONTRIBUTING.md:70
• Severity: low
• Checked: CONTRIBUTING.md:70 says "🎨 UI/UX: Improve design, accessibility, user experience". The words "design system" appear nowhere in CONTRIBUTING.md, .github/PULL_REQUEST_TEMPLATE.md or .github/ISSUE_TEMPLATE/*. The lock is real: .cursor/docs/design-system.md:9-17 (§Change protocol (locked)), AGENTS.md:169 and .github/CODEOWNERS. CONTRIBUTING.md:87 says to skim the rule files for your area, and AGENTS.md:17 maps webapp UI to design-system.md. A careful contributor finds the rule in two hops, but not from the line that invites UI work. The worst case is a reworked or rejected pull request.
• Fix: After CONTRIBUTING.md line 70, add one sentence: "UI work follows the locked design system in .cursor/docs/design-system.md. Do not add or change a token, color, radius or shadow; open an issue first."

5. The 'Active workflows' list misses five workflows, and it points at a gitignored file and a missing branch.

• Where: .github/WORKFLOWS.md:5
• Severity: low
• Checked: .github/WORKFLOWS.md lists 6 workflows under "Active workflows" (lines 7-40). ls .github/workflows shows 11. These 5 are missing from the list:
• chatroom-e2e.yml runs on pull_request and push to main (path-filtered), and on workflow_dispatch.
• lockstep-guard.yml runs on pull_request when extensions/extension-*/package.json changes. The lockstep-bypass label skips it.
• discord-release.yml runs on release published and prereleased.
• backend-ci.yml and quality-lint.yml are workflow_call only. .github/workflows/prod.docs.plus.yml:266 and :185 call them. .github/workflows/stage.docs.plus.yml:56 also calls quality-lint.yml.

Line 91 says "Workflow docs roadmap: Notes/CI_CD_Improvement_Roadmap.md". .gitignore ignores Notes/, so no outside reader can open that file.

Line 18 says "Triggers: push to dev, PR to dev". That matches .github/workflows/stage.docs.plus.yml. But git ls-remote --heads origin dev finds no dev branch. So only a manual workflow_dispatch (.github/workflows/stage.docs.plus.yml:23) can run this workflow.

Severity is low. The file is a maintainer reference, and each missing workflow explains itself in its header or error output.

• Fix: In .github/WORKFLOWS.md §Active workflows, add one bullet each:
• chatroom-e2e.yml: chatroom browser tests on a PR or push to main when webapp, extension or package code changes, plus workflow_dispatch.
• lockstep-guard.yml: fails a PR that changes an extension package.json when the publishable extension versions differ. The lockstep-bypass label skips it.
• discord-release.yml: posts a published release or prerelease to Discord.

Add one line saying that backend-ci.yml and quality-lint.yml are reusable (workflow_call) and are called by the prod and stage workflows.

On line 18, add: "No dev branch exists now, so only a manual workflow_dispatch runs this workflow."

Delete line 91, the Notes/CI_CD_Improvement_Roadmap.md pointer.

6. The bug template asks for the Bun version but not which product the bug is in or its version.

• Where: .github/ISSUE_TEMPLATE/bug_report.md:31
• Severity: low
• Checked: .github/ISSUE_TEMPLATE/bug_report.md:27-32 holds the Environment block: "- OS:", "- Browser:", "- Bun version:", "- Branch/commit:". Nothing asks which product has the bug, or its version. Only two templates exist, and there is no config.yml. So bugs in the npm @docs.plus/extension-* packages use this same form. Their version matters: CHANGELOG.md:70 tells extension users to raise @tiptap/core and @tiptap/pm to ^3.31.3. An extension user has no Bun version or branch to report. The form also does not ask a self-hoster for the release version.
• Fix: In .github/ISSUE_TEMPLATE/bug_report.md, add one line under "## Environment", before "- OS:". The line is: "- Where: docs.plus website / self-hosted (version or commit) / npm extension (package@version and @tiptap/core version)". Change "- Bun version:" to "- Bun version (self-host or local dev only):".

7. The CHANGELOG link references are stale after the v2.1.0 release.

• Where: CHANGELOG.md:913
• Severity: low
• Checked: CHANGELOG.md:913 reads "[Unreleased]: v2.0.0...HEAD". Line 914 defines only "[2.0.0]". The headings "## [2.1.0] — 2026-10-13" (line 13) and "## [2.0.1] — 2026-08-31" (line 673) have no link definitions. So they render as plain bracketed text. Tags v2.0.1 and v2.1.0 exist, and both have GitHub Releases. So the Unreleased compare link shows all 2.0.1 and 2.1.0 changes as unreleased. v2.0.1 is not an ancestor of main, but its releases/tag link still resolves.
• Fix: In CHANGELOG.md, change line 913 to "[Unreleased]: v2.1.0...HEAD". Add "[2.1.0]: https://github.com/docs-plus/docs.plus/releases/tag/v2.1.0" and "[2.0.1]: https://github.com/docs-plus/docs.plus/releases/tag/v2.0.1" above the existing "[2.0.0]" line.

8. The internal README says extensions share one popover surface, but each extension bundles its own controller.

• Where: packages/floating-popover/README.md:3
• Severity: low
• Checked: packages/floating-popover/src/controller.ts:84 holds the controller in a module variable: let defaultController = createPopoverController(). Both extensions list @docs.plus/floating-popover as a devDependency. extensions/extension-hyperlink/tsup.config.ts:9 marks only @tiptap/core and @tiptap/pm as external. So each extension dist inlines its own controller. The webapp has no alias to extension source; it loads each dist/index.js through package exports. So a link popover and a media toolbar can be open at once. extensions/extension-hyperlink/docs/api.md:113 already says a host that loads both extensions "gets two controllers". packages/floating-tooltip/README.md:3 states the same per-bundle rule.
• Fix: In packages/floating-popover/README.md:3, find the clause that starts "so multiple extensions share one floating surface". Replace it, through "mutually exclusive).", with: "so multiple extensions share one popover engine. The controller is per consuming bundle, so only one popover per bundle is open at a time. A host loading both extensions has two controllers."

9. The "Current Usage" table leaves out the four package shims that use this config.

• Where: packages/eslint-config/README.md:71
• Severity: low
• Checked: The "Current Usage" table (lines 73-79) lists root, webapp, admin-dashboard, hocuspocus.server and extension-*. Four more shims exist. packages/document-swarm/eslint.config.js imports ../eslint-config/index.js. packages/floating-popover, floating-tooltip and playground each have an eslint.config.js that imports ../eslint-config/library.js. A reader who uses the table to learn which packages are linted gets an incomplete list. Line 5, "ESLint 9 flat config", is correct: packages/eslint-config/package.json:19 takes "eslint": "catalog:", and the catalog pins ESLint 9 by design (AGENTS.md:192).
• Fix: In the "Current Usage" table, add rows: document-swarm | eslint.config.js | index.js; floating-popover, floating-tooltip, playground | eslint.config.js | library.js. Leave line 5 as it is.

10. One workspace package declares ISC in an MIT repository, and it is not marked private.

• Where: packages/supabase/package.json:17
• Severity: low
• Checked: packages/supabase/package.json:17 has "license": "ISC", and the file has no "private" field. The root package.json is {"private":true,"license":"MIT"}, and LICENSE is MIT. CONTRIBUTING.md:354 says "A merged contribution ships under the repository license, MIT." Every other package under apps/* and packages/* has "private": true, and either "license": "MIT" or no license field. Only the five extensions/* packages leave out "private", because npm publishes them, and all five say MIT. The harm is a misleading license field and a small risk of an accidental publish.
• Fix: In packages/supabase/package.json, add "private": true. Then delete the "license" field, or set it to "MIT", as Decision 2 rules.

11. CODEOWNERS assigns an owner to a file that no longer exists.

• Where: .github/CODEOWNERS:9
• Severity: low
• Checked: .github/CODEOWNERS:9 reads /scripts/hooks/design-system-lock.ts @HMarzban. ls scripts/hooks shows only commit-msg.sh, post-merge.sh, pre-commit.sh and pre-push.sh. Commit 09c2af1 (2026-10-10) deleted the file by maintainer ruling. CODEOWNERS last changed in 740bdba (2026-10-01), before that delete. git grep design-system-lock finds only this line. The line matches no file, so it protects nothing. The settled rule "Never loosen .github/CODEOWNERS" still applies, so the fix needs a maintainer ruling.
• Fix: If Decision 1 says yes, delete line 9 (/scripts/hooks/design-system-lock.ts @HMarzban) from .github/CODEOWNERS. The file was removed in 09c2af1, so this takes away no real protection.

Decisions

1. Item 11: delete the dead CODEOWNERS line? Recommended: yes. It names scripts/hooks/design-system-lock.ts, which 09c2af194 removed, so it protects nothing. AGENTS.md says never to loosen .github/CODEOWNERS, so only the maintainer makes this change.
2. Item 10: delete the license field in packages/supabase/package.json, or set it to MIT? Recommended: delete it, like most internal packages. Add "private": true either way.

Acceptance criteria

• Item 1 is fixed as its Fix says, or a comment here says why not.
• Item 2 is fixed as its Fix says, or a comment here says why not.
• Item 3 is fixed as its Fix says, or a comment here says why not.
• Item 4 is fixed as its Fix says, or a comment here says why not.
• Item 5 is fixed as its Fix says, or a comment here says why not.
• Item 6 is fixed as its Fix says, or a comment here says why not.
• Item 7 is fixed as its Fix says, or a comment here says why not.
• Item 8 is fixed as its Fix says, or a comment here says why not.
• Item 9 is fixed as its Fix says, or a comment here says why not.
• Item 10 is fixed as its Fix says, or a comment here says why not.
• Item 11 is fixed as its Fix says, or a comment here says why not.

Verify

1. Every new or changed link in the diff resolves.

Related

• Run only reviewed main-branch workflows on the production runner #437 pins the stage runner group to refs/heads/dev. Item 5 shows that branch does not exist.

Generated by Claude Code