Tell one canonical wiring story across the docs

[KayleeWilliams]

Stacked on #182 → #167. The docs consistency pass from the roadmap audit (#157, Principle 2): existing configs keep working, and one canonical format is the documented path everywhere.

The contradiction

The quickstart's step 2 taught the manual source as createDocsSource({ contentDir: "./docs", baseUrl: "https://example.com" }) — while claiming the manual steps show "the same wiring" init generated. But init scaffolds lib/source.ts as a zero-arg createDocsProject() that reads content root, navigation, and (since #182) baseUrl from the config. A reader following the manual path built a different, drift-prone integration from the one the scaffold gives them, on the page whose whole point is that they are the same thing.

The same drift ran wider: the build-a-docs-site path picker labelled raw createDocsSource() "Most cases" and never mentioned createDocsProject or the adapters; the source reference led with legacy groups:; several pages restated --base-url/contentDir in snippets the config now owns; and a few root leadtype.config.ts examples used defineDocsConfig where the config-model ownership table says defineLeadtypeConfig.

Page by page

• docs/quickstart.mdx — step 1's config now carries baseUrl (the same two fields init writes); step 2 is the exact scaffolded zero-arg createDocsProject() with the jiti note; step 3 uses the leadtype/next adapter helpers init wires; steps 4–5 drop the restated --base-url. The manual path now genuinely is the wiring init generates.
• docs/pipeline/build-a-docs-site.mdx — table and mermaid diagram flipped project-first: the config feeds both createDocsProject() and leadtype generate; createDocsSource() is the labelled escape hatch. Root config example switched to defineLeadtypeConfig with a site-owned baseUrl; the docs:generate script drops --base-url.
• docs/reference/project.mdx (new) — reference for createDocsProject() and resolveProject(): zero-arg discovery rule (root leadtype.config.*, else docs.config.* inside the docs dir, and the project-root-from-basename rule), the options tables, baseUrl precedence (argument > config > deployment-URL env fallbacks), the diagnostics-vs-throws contract, the ProjectDiagnostic shape with the stable ids, cache-only remote collections naming leadtype sync, and navigationOrigin. Every claim checked against config/project.ts / project/index.ts on this branch — one correction from the audit note: there is no "mixed" origin value in the code; the type is explicit | inherited | groups | inferred, and that is what the page documents. Registered in the reference nav in docs/docs.config.ts.
• docs/reference/source.mdx — top-of-page callout pointing most apps at createDocsProject(); lead example now uses canonical nav; groups moved under an explicit Legacy callout; nav added to the options table.
• docs/pipeline/configure-sources.mdx — new multi-repo section showing the gitSource() + sparse + nested collections shape (mirroring apps/c15t-example/leadtype.config.ts); the "multiple local folders" answer is now config collections, with repeated --docs-dir flags kept as a labelled legacy callout; root config examples switched to defineLeadtypeConfig; generate commands stop restating --base-url.
• docs/pipeline/use-the-source-primitive.mdx — TL;DR reordered: zero-arg createDocsProject() first, primitive as the fallback for content no config describes. The recently-added jiti note and all framework recipes kept.
• docs/concepts/architecture.mdx + docs/how-it-works.mdx — package map and vocabulary now name createDocsProject/resolveProject as the primary runtime entry; "source primitive" redefined as the lower-level function the project is built on.
• skills/setup-agent-ready-docs.md — two-line touch-up: init offered up front as the scaffold for steps 2–4, doctor added to the verify step; the config gains baseUrl and the generate command stops restating it.
• Sweep stragglers — index.mdx pipeline card, agent-setup-prompts (both prompts now scaffold createDocsProject()/defineLeadtypeConfig, canonical routePrefix instead of legacy prefix), localize-docs (per-locale sources via createDocsProject({ locale }) instead of re-handing the config back), sync-docs-across-repos and reference/markdown root configs to defineLeadtypeConfig, collections.mdx lead example likewise.

What stayed documented as legacy, and why

Per Principle 2, nothing was deleted — legacy shapes are confined, not erased. groups keeps a full explanation under an explicit Legacy callout in the source reference (and its rename story stays in the config-model table); repeated --docs-dir flags keep a labelled legacy callout in configure-sources with their exact semantics; deprecated-name behavior (prefix, sourceConfig, schema) remains documented in concepts/config-model, untouched here. They just no longer appear anywhere as the recommended path.

Deliberately untouched for conflict avoidance: docs/reference/doctor.mdx (#181) and docs/concepts/config-model.mdx / the CLI flag rows of docs/reference/cli.mdx (#182, in this base).

Verification

• bun x leadtype lint docs --format github --error-unknown --max-warnings 0 (the exact CI invocation): 54 files scanned, 0 errors, 0 warnings — including snippet typechecking against the built dist/.
• bun x leadtype doctor --src . --docs-dir docs: exit 0.
• bun run --filter leadtype test: 843 pass (56 files); bun run --filter leadtype-evals test: 46 pass. The pre-commit hook re-ran the full suite: 889 pass.
• docs/paths.lock.json regenerated. Entries updated for every page this PR edits, plus integrate-with-fumadocs: its entry was one of the three stale-at-Resolve the project once instead of in every command #167 hashes Make baseUrl a config field instead of a repeated knob #182 left alone, and the package test suite regenerates the lockfile against the current tree, so its refreshed hash is committed here — the other two stale entries (collections, use-the-source-primitive) belong to pages this PR edits anyway. The lockfile is now fully consistent with the tree.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 1024c67d-b208-4ef1-b6ce-23e6c21a3852

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[KayleeWilliams]

Coordination note: #179 (sibling branch) adds "mixed" as a project-level navigation origin (DoctorReport.navigation.origin becomes NavigationOrigin | "mixed"). This page's navigationOrigin section documents the four per-collection values, which stays correct — but once #179 merges, add the project-level mixed value here (one line) so the reference matches doctor's report.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4deb76db1b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[pullfrog]

Important

The jiti claim is wrong in two places: leadtype init never installs it, and a scaffold without it throws on first render. A reader who trusts the docs over the adjacent bun add jiti gets a broken app.

Reviewed changes — full read of the 17-file docs diff, with every API claim on the new reference page traced back to packages/leadtype/src.

• New docs/reference/project.mdx — canonical reference for createDocsProject() / resolveProject(): discovery order, options tables, baseUrl precedence, the diagnostics-vs-throws split, ProjectDiagnostic ids, and navigationOrigin. Registered in the reference nav and present in paths.lock.json.
• Canonical entry point flipped — quickstart step 2, build-a-docs-site, use-the-source-primitive, architecture, how-it-works and index now lead with zero-arg createDocsProject(); createDocsSource() is relabelled an escape hatch rather than "most cases".
• --base-url dropped from documented commands — every leadtype generate invocation now relies on the config's baseUrl, which #182 put in place.
• Legacy shapes confined, not deleted — groups moved under a Legacy callout in the source reference, repeated --docs-dir flags kept in a labelled callout in configure-sources.
• Naming sweep — root-config examples switched to defineLeadtypeConfig, prefix → routePrefix, plus a new gitSource() multi-repo section.

I verified the load-bearing accuracy claims rather than assuming them. All of the following check out against this branch: every createDocsProject/resolveProject option name, type and default (project/index.ts:88-130); all seven diagnostic ids verbatim; the explicit | inherited | groups | inferred union; baseUrl precedence arg > config > env (generate.ts:1796, internal/docs-url.ts:179-207), so dropping --base-url is safe; --name/--summary falling back to config product (generate.ts:580-589); the inheritConfig whitelist excluding baseUrl (config/inherit.ts:44-56), making the "never inherited from the source" comment true; and every rewritten snippet's imports and call shapes, including createLoadPageData's internal slug ?? [] which makes dropping the old ?? [] correct. The three new internal anchors all resolve.

ℹ️ Nitpicks

• docs/quickstart.mdx:118 — "the exact lib/source.ts that init scaffolds" holds for Next only. Nuxt scaffolds a lazily-memoized getSource() (init-templates.ts:338-350), and Astro/SvelteKit write to src/lib/source.ts. Since step 3 is framed as "the only step that varies by framework", a Nuxt reader hits a contradiction one step early.
• docs/reference/project.mdx:62 — the env fallback list skips two real steps: PORTLESS_URL and the browser's location.origin both sit ahead of http://localhost:<PORT> (internal/docs-url.ts:179-207).

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 14b6ed0288

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[pullfrog]

ℹ️ No blocking issues in the new commit — all three prior threads are genuinely fixed. One inline correction and one sweep straggler below.

Reviewed changes — the delta since the prior pullfrog review at 4deb76db, i.e. commit 14b6ed02.

• Corrected the jiti ownership claim in both places — docs/quickstart.mdx:120 and docs/reference/project.mdx:26 now say init reminds you to install it rather than installs it. This matches the code: jiti is in deps for every framework plan (init-templates.ts:145/244/334/439), so init.ts:342-344 does print "Ensure these are installed: … jiti", while init.ts:321-326 still patches only scripts["docs:generate"].
• Added the missing typeTableBasePath to the c15t gitSource() snippet — docs/pipeline/configure-sources.mdx:289 now carries the top-level typeTableBasePath: "content-fixtures/c15t" with its clone-root comment, matching apps/c15t-example/leadtype.config.ts:69 field-for-field. Copied as written, the type tables the sparse: ["docs", "packages"] comment promises now actually resolve.
• Extended the baseUrl sweep to localize-docs — the defineDocsConfig example gained baseUrl, and its leadtype generate command dropped --base-url, bringing the page in line with quickstart and configure-sources.
• Reworded the resolveProject() scope claim — no longer asserts flatly that it is "the one pipeline behind generate"; see the inline note, the replacement overshoots in the other direction.

ℹ️ The --base-url sweep stops short of a page this PR edits

docs/pipeline/sync-docs-across-repos.mdx:86 still reads "docs:generate": "leadtype generate --src . --out public --base-url https://docs.example.com --sync" — the same docs:generate script that build-a-docs-site.mdx:81 just had --base-url removed from, describing the same pinned-source production shape. Nothing breaks (the flag is still a valid override), but two pages this PR touches now tell different stories about where the base URL lives, which is the exact drift the PR exists to close.

Technical details

# `--base-url` still restated in a `docs:generate` script on a page this PR edits

## Affected sites
- `docs/pipeline/sync-docs-across-repos.mdx:86` — `docs:generate` script keeps `--base-url https://docs.example.com`, while the parallel script at `docs/pipeline/build-a-docs-site.mdx:81` was changed to `leadtype generate --src . --out public --sync` in this PR. Both pages document the pinned remote-collection shape.

## Required outcome
Every `leadtype generate` invocation on a page this PR touches reads its base URL from the config, matching the story quickstart, configure-sources, localize-docs and build-a-docs-site now tell.

## Open questions for the human
The same straggler exists on pages outside this PR's stated scope — `deploy-generated-artifacts.mdx:36`, `generate-static-artifacts.mdx:51/91/104/148/158`, `search/add-search.mdx:21`, `reference/openapi.mdx:52`, `generate-rss-atom-feeds.mdx:51`, `aeo/optimize-docs-for-agents.mdx:41`. Worth deciding whether they are a follow-up PR or belong here, since a reader who lands on any of them gets the pre-#182 story.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 29ca04e111

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[pullfrog]

Important

The new multi-collection generateStaticParams snippet emits params that include the route prefix, so under the catch-all location every other Next example in these docs uses it renders /docs/docs/quickstart. The paragraph's diagnosis is right; the one-liner it prescribes is not usable as written.

Reviewed changes — the delta since the prior pullfrog review at 14b6ed02, i.e. commit 29ca04e1, which touches docs/reference/project.mdx and its paths.lock.json hash only.

• Narrowed the resolveProject() / generate claim — the sentence now says generate "performs the same resolution steps" and the unlanded sync-consolidation reference is gone. That matches the branch: generate.ts composes config/load + inherit + normalize + infer from the same modules without importing resolveProject. This retires the one open thread from the last review.
• Rewrote the configPath / configDir option rows — now documents that the two are alternatives and that configDir wins as the project root when both are passed. Traced and accurate: createDocsProject maps configDir onto resolveProject's cwd (project/index.ts:243), cwd beats the config-path-derived root (config/project.ts:309-311), and the fallback content root becomes <configDir>/docs (config/project.ts:316,457-461) — while normalizeDocsConfig still receives configDir: path.dirname(options.configPath) (config/project.ts:325-327), so relative paths do stay anchored to configPath's directory.
• Added multi-collection static-params guidance to "What it returns" — a new paragraph plus snippet steering readers away from createGenerateStaticParams for projects with several route prefixes. See the inline comment.

The facts behind the new paragraph all check out: createGenerateStaticParams maps page.slug verbatim (next/index.ts:321), listPages() spreads each source's page through unchanged (project/index.ts:376), and slug is derived from the relative path with no mount applied while urlPath is mount-aware (source/index.ts:300-309) — so two collection index pages really do both yield { slug: [] }. It is only the prescribed replacement that doesn't land.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

Important

The prior thread is genuinely fixed — both layouts are now correct and the route topology is stated. But the "single-collection projects are fine" carve-out that frames them is still too broad: a single collection with mounts fails identically, and that is the shape this repo's own docs/docs.config.ts uses.

Reviewed changes — the delta since the prior pullfrog review at 29ca04e1, i.e. commit 7456896f, which touches docs/reference/project.mdx, docs/pipeline/use-the-source-primitive.mdx, docs/pipeline/configure-sources.mdx, and the paths.lock.json hashes.

• Replaced the multi-collection static-params snippet with two named layouts — a per-collection catch-all fed by project.getSource(key), and a merged site-root catch-all derived from urlPath, each with its route location stated in the fence comment. The follow-up paragraph now spells out the prefixed-route misrouting (/docs/changelog/1-0) and the optional-catch-all collision with a static app/page.tsx. This resolves the thread from the last review.
• Widened the adapter enumeration — the paragraph now names all five static-params helpers rather than Next's alone. Verified: createGenerateStaticParams (next/index.ts:316-323) maps page.slug directly, and createGetStaticPaths, createPrerenderRoutes, createEntries, createStaticParams all route through listJoinedSlugs (internal/framework.ts:77-82), which does the same. leadtype/fumadocs builds a synchronous files list rather than a route-enumeration helper, so its absence from the list is correct.
• Documented resolveInclude as the exception to the merged view — accurate: project/index.ts:489-500 binds it to getSource(project.collections[0]?.key), and source/index.ts:798-809 defaults fromDir to that collection's own content root. config/project.ts:371 iterates Object.entries(declared), so "first-declared" holds.
• Qualified the adapter claim in use-the-source-primitive.mdx and pointed it at the reference — the second site the last review asked to reach.
• Pinned baseUrl ownership to the docs UI repo in configure-sources.mdx — the ownership bullet now names it and the multi-repo example carries baseUrl: "https://acme.dev". Both claims check out: config/inherit.ts:44-57 has no baseUrl in the inherit whitelist (and SourceOwnedConfigFields doesn't declare one), and the fallback chain in internal/docs-url.ts:179-207 really does terminate at http://localhost:<PORT> after the deployment-URL env vars.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6c680f1bda

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5d1a2ab615

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[pullfrog]

Important

The new Fumadocs scoping is a real correction — the merged-project failure mode is stated accurately and the per-collection recipe is right. But the single-collection carve-out that replaces it is still one condition short: a single collection with mounts fails the same way, and that is the shape apps/fumadocs-example ships.

Reviewed changes — the delta since the prior pullfrog review at 7456896f. A git range-diff against 6c680f1 shows commits 2–4 unchanged and commit 1 replayed onto a new base tip with no content delta of its own, so the reviewable surface is one commit, 5d1a2ab "Scope fumadocsSource to one collection at a time" (3 files, +20/−4). Everything else in the 18-file diff is base-branch absorption from dx/base-url-config.

• Scoped the Fumadocs project wiring to a single collection — integrate-with-fumadocs.mdx:25 now says a config-described project is a DocsSource "for a single-collection project", and the new paragraph at :38 explains why a merged project isn't: fumadocsSource() maps each page to its collection-local slug and relativePath. Verified against fumadocs/index.ts:122-132, which builds slugs: meta.slug verbatim, and :134, which reads meta.json only from leadtype.contentDir — which project/index.ts:520-523 binds to collections[0]. The prefix-drop and index-page-collision claims both follow.
• Added a per-collection recipe — lib/changelog-source.ts feeding project.getSource("changelog") into its own fumadocsSource() / loader({ baseUrl: "/changelog" }). Correct, and getSource is genuinely synchronous (project/index.ts:380-388), so the un-awaited call in the snippet is right. One nit on the fence directive, inline.
• Carved leadtype/fumadocs out of the adapter enumeration in build-a-docs-site.mdx:100 — accurate that it is not interchangeable with the five static-params adapters, since it builds a synchronous files list rather than enumerating routes. It carries the same over-broad single-collection clause, covered inline.
• Refreshed the two docs/paths.lock.json hashes for the touched pages. No path changes.

I ran the docs lint against the locally built CLI to check the new snippets: node packages/leadtype/dist/cli.js lint docs --error-unknown --max-warnings 0 → "All 54 files pass."

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

mounts don't survive this path, so the single-collection carve-out is too broad. fumadocsSource() hands fumadocs slugs: meta.slug (fumadocs/index.ts:122-132), and slug is derived from the relative path with no mount applied (source/index.ts:305) while urlPath is mount-aware (source/index.ts:306-314). A single collection with mounts: [{ pathPrefix: "changelog", urlPrefix: "/changelog" }] therefore yields ['changelog','1-0'] under loader({ baseUrl: "/docs" }) — served at /docs/changelog/1-0, while the generated sitemap and llms.txt advertise /changelog/1-0. That is docs/docs.config.ts:289 and apps/fumadocs-example/lib/source.ts, which is why apps/fumadocs-example/app/changelog/[[...slug]]/page.tsx:72-77 hand-writes generateStaticParams instead of using the wiring this page describes.

Technical details

# The single-collection carve-out omits `mounts` on the Fumadocs surface

## Affected sites
- `docs/integrations/integrate-with-fumadocs.mdx:25` — "A single-collection project is one — so the content root, navigation, `mounts`, and OpenAPI overlay come from the config rather than being restated here". `mounts` is named explicitly as something that carries over, which is the inverse of what happens.
- `docs/pipeline/build-a-docs-site.mdx:100` — "Pass `project.getSource(key)` into one `fumadocsSource()` / `loader()` per collection, or use it with a single-collection project." Same condition, same gap.

## Evidence
- `packages/leadtype/src/fumadocs/index.ts:122-132` builds each page file as `slugs: meta.slug`. Nothing mount-aware reaches fumadocs.
- `packages/leadtype/src/source/index.ts:305` derives `slug` from `outputRelativePath` with no mounts argument; `:306-314` computes `urlPath` through `toDocsUrlPath(relativePath, mounts)`. A mount splits the two exactly the way a `routePrefix` does.
- `docs/docs.config.ts:289` — this repo's own single-source config carries `mounts: [{ pathPrefix: "changelog", urlPrefix: "/changelog" }]`.
- `apps/fumadocs-example/lib/source.ts` is the wiring at `:27-36` verbatim (`fumadocsSource({ source: project })` → `loader({ baseUrl: "/docs" })`), and `apps/fumadocs-example/app/changelog/[[...slug]]/page.tsx:72-77` filters `page.urlPath.startsWith("/changelog/")` and emits `page.slug.slice(1)` by hand — the concrete cost of the gap.
- `docs/pipeline/configure-sources.mdx:17` lists "One docs folder with mounted subtrees" as a first-class shape, so this is a documented common case, not an edge.
- PR #184 (`740699f8`) does not close this: it adds `DocsSource.routePrefix` and reworks the five static-params adapters, but `packages/leadtype/src/fumadocs/index.ts` is not among its 13 files and the `meta.slug` derivation in `source/index.ts` is untouched. The deferral that resolved the earlier `use-the-source-primitive.mdx` thread doesn't extend to this surface.

## Required outcome
A reader with one collection can tell from the sentence whether their project is in the safe case. The condition is "a single-collection project whose pages' `urlPath` matches the loader's `baseUrl`" — i.e. no mounts moving a subtree off the route's own prefix — not "a single-collection project".

## Suggested approach (optional)
State the condition in terms of `urlPath` rather than collection count, and note that a mounted subtree needs its own `loader()` at the mount's `urlPrefix` the same way a second collection does. The per-collection recipe added just below generalizes to mounts with a `listPages()` filter on the prefix, which is what `apps/fumadocs-example` ships.

[pullfrog]

nit: this // @noErrors isn't needed, and it opts a brand-new snippet out of the repo's own snippet:types check while the near-identical sibling at :27-36 stays checked. Deleting the line leaves the lint at "All 54 files pass", and a control substitution of project.getSource(123) does fail it — × [error snippet:types] ts snippet fails typechecking: Argument of type 'number' is not assignable to parameter of type 'string'. (line 46) — so the fence really is verified against the built leadtype types once the directive is gone.

[pullfrog]

ℹ️ No new issues — the corrected missing-config sentence matches the throw the code actually produces. One wording nit inline.

Reviewed changes — the delta since the prior pullfrog review at 5d1a2ab: one commit, 06e0291 "Document the missing-config error createDocsProject actually throws", touching one sentence in docs/reference/project.mdx plus that page's paths.lock.json hash.

• Corrected the missing-config error description — docs/reference/project.mdx:37 no longer promises a list of searched paths. Traced end-to-end and accurate: config.missing is pushed at level: "warn" (config/project.ts:614-618), so the blocking level: "error" check at project/index.ts:276-286 never fires on this path and execution reaches :289-292, which throws no docs config found from "${project.rootDir}". Pass `config`, or add a leadtype.config.* / docs.config.* file. — one root directory plus the two globs, exactly as the sentence now says. It holds on both branches into that throw: with no content roots at all resolveProject returns emptyProject(rootDir, diagnostics) (config/project.ts:626-627), and with a docs/ tree but no config file resolveConfiglessProject still leaves config null — either way createDocsProject lands on the same message. This closes the Codex thread the author replied to.
• Refreshed the /docs/reference/project lockfile hash — the only other change in the delta; no path additions or removals.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

nit: rootDir is a real field on ResolvedProject (config/project.ts:121), but it isn't part of what this page documents — the resolveProject() return snippet at :135-140 lists configPath, collections, sources, inference and diagnostics, and there's no rootDir row in either options table. A reader chasing project.rootDir finds no referent, while the error itself just interpolates the resolved project root, which reads plainer stated as such.

Suggested change

	If neither file exists, `createDocsProject` throws naming `project.rootDir` and the two filename globs (`leadtype.config.*` / `docs.config.*`); `resolveProject` reports a `config.missing` diagnostic whose fix is `leadtype init`.
	If neither file exists, `createDocsProject` throws naming the project root it searched from and the two filename globs (`leadtype.config.*` / `docs.config.*`); `resolveProject` reports a `config.missing` diagnostic whose fix is `leadtype init`.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 06e0291f56

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Include mounted routes in the Fumadocs limitation

The fresh case not covered by the multi-collection workaround is a single Fumadocs collection with mounts: for example, docs/changelog/v1.mdx mounted at /changelog is still mapped here to the collection-local slug changelog/v1, so loader({ baseUrl: "/docs" }) routes it as /docs/changelog/v1 while urlPath and generated artifacts advertise /changelog/v1. This contradicts the preceding promise that mounts come through for a single-collection project; document that this adapter does not preserve mounts or make its page mapping mount-aware.

Useful? React with 👍 / 👎.