Docs sites — boundary
The hard rule for which of the three Fumadocs sites a given doc belongs in. Read once so you never write a doc in the wrong place.
The monorepo has three Fumadocs sites. They are deliberately separate. Putting a doc in the wrong one is the single most common docs mistake; this page exists to make the rule unambiguous.
The three sites
| Site | Package | Owns | Read by |
|---|---|---|---|
apps/dev-docs (this one) | @today/dev-docs | how this monorepo runs | new contributors + AI agents |
apps/webview-bridge-docs | @today/webview-bridge-docs | the WebView Bridge wire contract + web SDK | native client implementers + web SDK users |
design-system/docs | @today/tdx-docs | the TDX design system (tokens, ui, opal) for consumers | product developers using TDX |
The decision table
| If your doc is about... | It belongs in... |
|---|---|
The TDX Button component's props or usage | design-system/docs |
| A new TDX design token | design-system/docs |
| A new TDX Opal flow primitive | design-system/docs |
The WebView Bridge track capability's payload shape | apps/webview-bridge-docs → contract |
How to write web code that calls @today/webview-bridge | apps/webview-bridge-docs → web SDK |
| How iOS should implement the bridge | apps/webview-bridge-docs → platforms |
Why this repo uses tsgo --build instead of tsc --noEmit | apps/dev-docs → toolchain |
The PR-A...PR-Z letter convention | apps/dev-docs → workflow |
How scripts/affected.ts works | apps/dev-docs → workflow |
The Better-Auth oauthProviderClient.onRequest injection quirk | apps/dev-docs → architecture |
| How to run Playwright smoke tests locally | apps/dev-docs → toolchain → testing |
The OpalShaderShell used by the three auth pages | apps/dev-docs → architecture (it's a cross-package shell, not a TDX primitive) |
The chat runtime's MessageStore API | apps/web/docs/chat/ — single-app local docs, not any Fumadocs site |
How to write a new .claude/skills/ skill | apps/dev-docs → automation |
The principle
When a doc could plausibly live in two sites, choose the one closest to the code it describes, and link from the other site:
- Component / contract / package reference → near the published package
(
design-system/docs,webview-bridge-docs, or the package'sREADME.md). - Repo-wide operations and cross-package architecture → this site.
- Single-app deep internals that one team owns → local
apps/<app>/docs/.
Cross-site linking is encouraged: this site has a chapter on the bridge from
the repo-wide architecture angle ("which apps mount the bridge, how the
fallback is wired"), but it points to apps/webview-bridge-docs for the
contract itself. Don't paste the wire contract into multiple sites — pick one
home and link.
Why three sites instead of one
Each site has a distinct publishing audience:
webview-bridge-docsis read by external native teams who may not even have the rest of this monorepo checked out. It needs to be self-contained.design-system/docsis read by product developers and designers who want a zero-friction component reference. It should not be cluttered with build toolchain details.dev-docsis read by people working in this repo. It expects you to have the repo open in your editor.
Mixing these would either dilute the audience-specific surfaces or force every reader to filter out 80% of the content. The cost is one extra Vercel project per site; the benefit is each site stays focused.
Renaming, deprecating, or splitting a site
This site is the canonical place to record any change to the docs-site topology. If a future PR adds a fourth site, splits one, or merges two, update this page in the same PR — otherwise contributors will keep writing into the wrong one.