@elytracms/cli 0.0.80 → 0.0.82

package/README.md

@@ -29,7 +29,8 @@ elytra doctor   Diagnose the active deployment's readiness and print each fix.
                 by NAME only — values are never read into the report or printed.
                 When the publish revalidate pair is set, also sends a signed
                 no-op ping to the endpoint to prove the publish → live chain
-                end to end. Also reports the generated-previews artifacts
+                end to end. Also checks your cms/ route set for URL conflicts
+                (see below), and reports the generated-previews artifacts
                 (manifest present, image files present, no strays — warnings
                 only; previews are optional). Read-only; exits non-zero if any
                 check fails.
@@ -175,3 +176,90 @@ has no `pairWith` escalation because its real partner lives on a plane this
 doctor cannot read. Missing it is a warning: draft preview is closed
 everywhere (401 on both sides) until it's set — a project that never uses
 draft preview may legitimately leave it unset.
+
+## Route conflicts (`elytra doctor`)
+
+Routes are code, so a route conflict is a build-time bug, and `elytra doctor`
+reports it: two routes that would match the exact same URLs fail the run with
+the offending ids and patterns named. Nothing about this needs a deployment —
+the check runs in playground mode too.
+
+The doctor reads the route set from your project's `cms/index.ts` (the
+`collections` + `routes` your `elytra.config.ts` passes through). That tree is
+plain, React-free TypeScript by convention, so the CLI imports it natively —
+no bundler, no Vite, no dev server. Two consequences worth knowing:
+
+- It needs a Node that runs TypeScript natively (**≥22.18**). On an older Node
+  the check reports "not checked here" and names the version — never a false
+  pass.
+- If the route set cannot be read for any reason (no `cms/index.ts`, a module
+  that throws, an import the CLI cannot resolve such as a `tsconfig` path
+  alias, TypeScript syntax Node cannot strip, or a `routes` export of the
+  wrong shape), the check reports **why**, as "not checked here". It never
+  crashes the doctor and never claims your routes are fine.
+
+### Conflicting hierarchy mounts
+
+A hierarchy mount (`/:path*`, `/docs/:path*`) is not a router route: it is pulled
+out of the router and resolved per request against a collection's composed page
+tree. So the route-conflict check above cannot see mounts at all, and a second
+row — `mount-conflicts` — judges them by what they declare instead:
+
+- **Two collections mounted at the same path fail the run.** They claim an
+  identical URL space, and the only thing separating them is declaration order.
+- **A mount nested inside another's URL space is a warning.** It is a real
+  shadow, but only where the outer collection's tree actually composes a path
+  into the inner mount's prefix — that is content, which a CLI cannot see, so
+  naming the precedence is honest and failing your build on it would not be.
+
+The precedence being named is worth stating plainly, because nothing else does:
+**mounts are tried in declaration order, not by specificity**, and the first
+whose collection resolves a document for that URL wins. A root mount declared
+first therefore outranks a deeper one — the opposite of how ordinary routes
+behave, where more static segments always win. Declare the more specific mount
+first.
+
+### Declarations that serve nothing
+
+A third row — `unreachable-routes` — asks a different question from the two
+above: not "do two declarations fight?" but "can this declaration ever serve
+anything at all?" Three shapes trip it, all of which used to 404 silently with
+no issue raised anywhere:
+
+- **An all-dynamic route over a mount's URL space** — a **warning**. `/:slug`
+  matches *every* one-segment URL, so the `/:path*` mount is consulted there
+  only where the route resolves no document. Nothing is unconditionally
+  unreachable (the resolver falls through — see *Precedence* below), but
+  precedence at that depth is then decided by your **content**: a page whose
+  composed path collides with a post slug is silently shadowed, and neither
+  side is told. `/blog/:slug` is fine and always was: a static segment claims
+  only the namespace you carved out. It is the *all*-dynamic pattern that takes
+  a whole depth.
+- **A mount on a collection that cannot back it** — no `parent` self-relation,
+  so there are no nested paths to compose, or the collection is not declared at
+  all. The resolver skips such a mount silently; every URL under it 404s. This
+  one **fails** the run: no content and no ordering can make it work.
+- **A catch-all with a dynamic prefix** (`/:lang/:path*`) — also a **failure**.
+  It is dead in both directions: every router drops it as a catch-all, and no
+  mount is built from it because a mount prefix must be static. For per-locale
+  mounts, declare one mount per locale instead:
+  `{ pattern: '/de/:path*', locale: 'de' }`.
+
+### Precedence: a match is not a result
+
+A route always wins over a mount **for the URLs it can actually serve**. When a
+route matches a URL but resolves no document there — no post with that slug, or
+none published in this perspective — the resolver falls through to the hierarchy
+mounts instead of returning 404. So declaring `/blog/:slug` does not take the
+`/blog/*` namespace away from your page tree: a page at `blog/kid` is served,
+and it stops being served the moment a *post* with slug `kid` exists.
+
+The consequence worth knowing: which collection serves such a URL depends on
+what exists, not on the routes alone, and it is evaluated per perspective — a
+draft-only post wins in preview while the published page still serves live.
+
+**Redirect loops are not checked here.** Since EC-303 redirects are editorial
+data in the backend, not code — a CLI has no editorial data. The studio checks
+them (and route conflicts, and the route-side half of `unreachable-routes`)
+live, at the section-rail foot, because it holds both the config routes and the
+redirects rail.

package/index.js

@@ -1,6 +1,23 @@
 #!/usr/bin/env node
 import { argv, exit } from 'node:process'
-import { run } from './src/cli.js'
+import { engineBuildFailureMessage } from './src/engine-build-failure.js'
+
+/**
+ * EC-503: `src/cli.js`'s static graph reaches `@elytracms/core`'s COMPILED dist
+ * (doctor + routes-check), so an absent or half-written engine build kills every
+ * command — including `--help` — before a line of this file's code would run.
+ * Loading that graph dynamically is what makes the failure catchable at all; the
+ * leaf import above has no engine dependency and therefore always loads.
+ */
+let run
+try {
+  ;({ run } = await import('./src/cli.js'))
+} catch (error) {
+  const attributed = engineBuildFailureMessage(error)
+  if (attributed === null) throw error
+  console.error(attributed)
+  exit(1)
+}
 
 run(argv.slice(2))
   .then((code) => exit(code))

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elytracms/cli",
   "author": "finaldream <hi@finaldream.de>",
-  "version": "0.0.80",
+  "version": "0.0.82",
   "description": "The Elytra CLI — run a consuming repo's studio, frontend, and Convex backend under one command.",
   "license": "MIT",
   "type": "module",
@@ -17,7 +17,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@elytracms/core": "^0.0.80"
+    "@elytracms/core": "^0.0.82"
   },
   "devDependencies": {
     "vitest": "^4.1.10"

package/src/cli.js

@@ -29,9 +29,10 @@ Commands:
              values never shown — config, membership) and print each fix. When the
              instant-publish revalidate pair is set, also sends a signed no-op ping
              to the endpoint to prove the publish → live chain end to end. Also
-             reports the generated-previews artifacts (manifest/files present;
-             hash staleness lives in \`elytra previews --check\`). Exit non-zero
-             if any check fails. Read-only. Optional: --url <convex url>.
+             checks your cms/ routes for URL conflicts, and reports the
+             generated-previews artifacts (manifest/files present; hash staleness
+             lives in \`elytra previews --check\`). Exit non-zero if any check
+             fails. Read-only. Optional: --url <convex url>.
   previews   Render every canvas-eligible component's fixtures against YOUR theme
              (headless Chromium via Playwright — an optional install) and write
              committed preview images (studio/public/elytra-previews/) plus an
@@ -110,9 +111,14 @@ Diagnose the active deployment's readiness (URL, reachability, auth signing
 keys, expected deployment env vars — set/missing by NAME, values never shown
 — config, membership) and print each fix. When the instant-publish
 revalidate pair is set, also sends a signed no-op ping to the endpoint to
-prove the publish → live chain end to end. Also reports the
-generated-previews artifacts (manifest/files present; hash staleness lives
-in \`elytra previews --check\`). Exit non-zero if any check fails. Read-only.
+prove the publish → live chain end to end. Also checks the route set in your
+cms/ for URL conflicts (routes are code — redirect loops are editorial data
+and are checked in the studio), and reports the generated-previews artifacts
+(manifest/files present; hash staleness lives in \`elytra previews --check\`).
+With studio/ deps installed, config validity is checked for real: doctor
+executes elytra.config.ts through your studio's own Vite (takes a few
+seconds); without deps it stays an honest "unknown" with the reason.
+Exit non-zero if any check fails. Read-only.
 
 Options:
   --url <convex url>   Diagnose this deployment instead of the one resolved
@@ -454,7 +460,9 @@ export async function run(argv, { cwd = process.cwd(), env = process.env, emit =
   const command = decision.subcommand
 
   // `doctor` is a read-only diagnostic: it needs the repo root + env + network, but not
-  // installed deps — so it is not blocked by a missing node_modules.
+  // installed deps — so it is not blocked by a missing node_modules. (EC-495: WITH
+  // installed studio deps it additionally executes elytra.config.ts through the
+  // consumer's own Vite for a real config-valid answer — opportunistic, never required.)
   if (command === 'doctor') {
     const project = inspectProject(cwd, env)
     if (!project.root) {
@@ -470,6 +478,8 @@ export async function run(argv, { cwd = process.cwd(), env = process.env, emit =
       // EC-399: where `convex env list` runs (name enumeration — presence only),
       // and whether the AI provider-key expectation applies.
       studioDir: project.apps.studio ? join(project.root, 'studio') : undefined,
+      // EC-469: where the project's `cms/` route set is read from (code, not backend).
+      root: project.root,
       aiRouteConfigured: project.hasAiRoute,
       exec,
     })

package/src/config-harness.js

@@ -0,0 +1,256 @@
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { createServer as createNetServer } from 'node:net'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+/**
+ * The consumer-Vite harness (EC-495) — the ONE mechanism by which this CLI
+ * executes a consumer's `elytra.config.ts`, shared by `elytra previews`
+ * (EC-440, the original) and `elytra doctor`'s `config-valid` check.
+ *
+ * Node-native TypeScript is deliberately NOT the mechanism: every real config
+ * transitively imports `.tsx` component barrels via `./components`, which no
+ * Node version or flag executes (EC-474, measured on node 24.18 and 26.3 —
+ * `ERR_UNKNOWN_FILE_EXTENSION`; the React-free `cms/` tree in
+ * `routes-check.js` is the only place native stripping works). Instead the
+ * CLI boots the CONSUMER STUDIO APP'S OWN Vite programmatically — resolved
+ * from `studio/`'s node_modules, with a minimal inline config (the studio's
+ * `vite.config.ts`, with its app plugins/ports/env wiring, is deliberately
+ * NOT loaded: `configFile: false`) — serves virtual modules that import the
+ * config by `/@fs/` path, and `ssrLoadModule`s them node-side. The consumer's
+ * own toolchain does the executing; the CLI never grows a bundler dependency.
+ *
+ * Everything here is opportunistic by contract: the CLI works without
+ * installed deps (`cli.js` — doctor is not blocked by a missing
+ * node_modules), so every "can't" degrades to a reason string, never a crash.
+ */
+
+// --- Shared plumbing ---------------------------------------------------------------
+
+/** Conventional config file name at the project root (mirrors `WORKSPACE_CONFIG_FILE`). */
+export const CONFIG_FILE = 'elytra.config.ts'
+
+/** Resolve a module specifier from a directory's own node_modules world. */
+export function resolveFromDir(dir, specifier) {
+  return createRequire(join(dir, 'package.json')).resolve(specifier)
+}
+
+/** First free port in [start, start+span) — never a hardcoded single port. */
+export async function pickPort(start = 5440, span = 30) {
+  for (let port = start; port < start + span; port += 1) {
+    const free = await new Promise((resolve) => {
+      const probe = createNetServer()
+      probe.once('error', () => resolve(false))
+      probe.listen(port, '127.0.0.1', () => probe.close(() => resolve(true)))
+    })
+    if (free) return port
+  }
+  throw new Error(`No free port in ${start}–${start + span - 1}.`)
+}
+
+/**
+ * An inline Vite plugin serving virtual modules from an id → source map. The
+ * shared half of both harness plugins: previews adds its HTML middleware on
+ * top; doctor needs nothing else.
+ */
+export function virtualModulesPlugin(name, modules) {
+  return {
+    name,
+    resolveId(id) {
+      return Object.hasOwn(modules, id) ? id : null
+    },
+    load(id) {
+      return Object.hasOwn(modules, id) ? modules[id] : null
+    },
+  }
+}
+
+/**
+ * Boot the consumer studio's Vite with the minimal inline harness config —
+ * the exact boot `elytra previews` has always used (EC-440): the studio dir
+ * as root (so bare imports resolve from the CONSUMER's node_modules), an
+ * ephemeral loopback port with `strictPort` (failing loudly beats silently
+ * walking onto a dev server's port — the studio's own 5180 is never touched
+ * because the studio `vite.config.ts` is never loaded), and automatic JSX so
+ * `.tsx` component barrels transform without the app's React plugin.
+ */
+export async function startConsumerVite({ root, studioDir, port, plugins }) {
+  const vite = await import(pathToFileURL(resolveFromDir(studioDir, 'vite')).href)
+  const server = await vite.createServer({
+    configFile: false,
+    root: studioDir,
+    mode: 'development',
+    appType: 'custom',
+    logLevel: 'warn',
+    plugins,
+    server: {
+      port,
+      strictPort: true,
+      host: '127.0.0.1',
+      fs: { allow: [vite.searchForWorkspaceRoot(studioDir), root] },
+    },
+    esbuild: { jsx: 'automatic' },
+  })
+  await server.listen()
+  return server
+}
+
+// --- Doctor's config check (EC-495) --------------------------------------------------
+
+/** The doctor's virtual check module id. */
+const CONFIG_CHECK_ID = 'virtual:elytra-config-check'
+
+/**
+ * The check module's source: import the engine's resolver from the CONSUMER's
+ * installed core, then dynamically import the config INSIDE the check so a
+ * throwing config is attributed to the config (`config-error`) and never
+ * conflated with a broken harness (`harness-error` — e.g. an installed core
+ * too old to export these functions). The result crosses `ssrLoadModule`
+ * in-process, functions intact — nothing here is serialized.
+ */
+function configCheckModuleSource(configPath) {
+  const configImport = JSON.stringify(`/@fs/${configPath}`)
+  const file = JSON.stringify(CONFIG_FILE)
+  return [
+    `import { extractWorkspaceConfigExport, resolveWorkspaceConfig } from '@elytracms/core/studio-core'`,
+    `export async function runCheck() {`,
+    `  let mod`,
+    `  try {`,
+    `    mod = await import(${configImport})`,
+    `  } catch (error) {`,
+    `    return { kind: 'config-error', error }`,
+    `  }`,
+    `  try {`,
+    `    const extracted = extractWorkspaceConfigExport(mod, ${file})`,
+    `    if ('issue' in extracted) {`,
+    `      return { kind: 'resolved', result: { ok: false, projects: [], issues: [extracted.issue] } }`,
+    `    }`,
+    `    return { kind: 'resolved', result: resolveWorkspaceConfig(extracted.value, { file: ${file} }) }`,
+    `  } catch (error) {`,
+    `    return { kind: 'harness-error', error }`,
+    `  }`,
+    `}`,
+  ].join('\n')
+}
+
+/**
+ * The modules the check needs from the CONSUMER's own installed world: `vite`
+ * (the executor) and the exact `@elytracms/core` SUBPATH the virtual check
+ * module imports. Named separately so a half-installed repo says which is
+ * missing. The subpath is load-bearing, not cosmetic: `@elytracms/core` is a
+ * subpath-only package with no `"."` export, so probing the bare specifier
+ * reports `ERR_PACKAGE_PATH_NOT_EXPORTED` on a FULLY installed repo (measured
+ * against `apps/demo` 2026-08-01, where it produced a false "deps not
+ * installed"). Probe what you are going to import.
+ */
+const REQUIRED_CONSUMER_DEPS = ['vite', '@elytracms/core/studio-core']
+
+/**
+ * PURE precondition core: can the harness run at all, and if not, why exactly?
+ * Everything impure is injected (`exists` for the two conventional paths,
+ * `resolveDep` for the consumer's module world), so every degrade branch is
+ * deterministically testable without a filesystem or a real node_modules.
+ * Returns `null` when the harness may proceed, else the `unavailable` outcome
+ * with ITS OWN reason — the three cases the contract distinguishes.
+ */
+export function configHarnessPrecondition({ configPath, studioDir, exists, resolveDep }) {
+  if (!exists(configPath)) {
+    return { kind: 'unavailable', reason: `No ${CONFIG_FILE} found at the project root — config validity was not evaluated here.` }
+  }
+  if (!studioDir || !exists(join(studioDir, 'package.json'))) {
+    return {
+      kind: 'unavailable',
+      reason:
+        `No studio/ app found — doctor executes ${CONFIG_FILE} through the studio app's own Vite; ` +
+        'the studio boot and `elytra build` validate it too.',
+    }
+  }
+  for (const dep of REQUIRED_CONSUMER_DEPS) {
+    try {
+      resolveDep(studioDir, dep)
+    } catch {
+      return {
+        kind: 'unavailable',
+        reason:
+          `The studio's dependencies are not installed (${dep} could not be resolved from studio/) — ` +
+          'run `pnpm install`, then re-run `elytra doctor` for a real config check.',
+      }
+    }
+  }
+  return null
+}
+
+/** An error's message, newline-collapsed and capped — legible in a one-line report row, never a stack dump. */
+function errorSummary(error) {
+  const message = error instanceof Error ? error.message : String(error)
+  const collapsed = message
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join(' ')
+  return collapsed.length > 300 ? `${collapsed.slice(0, 300)}…` : collapsed || 'unknown error'
+}
+
+/**
+ * Execute a project's `elytra.config.ts` through the consumer studio's own
+ * Vite and resolve it with the engine's `resolveWorkspaceConfig`. Never
+ * throws; read-only toward the consumer project (no installs, no writes).
+ * Returns exactly one of:
+ *
+ *   - `{ kind: 'resolved', result, file }` — the config EXECUTED; `result` is
+ *     the engine's `WorkspaceConfigResult` (`ok` may still be false: that is a
+ *     definitive INVALID, not an unavailability).
+ *   - `{ kind: 'config-error', error, file }` — the config file itself threw
+ *     on import (syntax error, a throwing top-level statement, a broken
+ *     import). A definitive FAIL with the error surfaced.
+ *   - `{ kind: 'unavailable', reason }` — the harness could not run at all
+ *     (no studio app, deps not installed, Vite failed to boot, or the check
+ *     itself broke). An honest `unknown`, with the specific reason.
+ *
+ * The boot costs seconds, not milliseconds — `log` announces it so a quiet
+ * pause in the doctor output is explained (`elytra doctor` is a diagnostic;
+ * the price is right).
+ */
+export async function executeWorkspaceConfig({
+  root,
+  studioDir,
+  port,
+  log = () => {},
+  exists = existsSync,
+  resolveDep = resolveFromDir,
+} = {}) {
+  const configPath = join(root, CONFIG_FILE)
+  const blocked = configHarnessPrecondition({ configPath, studioDir, exists, resolveDep })
+  if (blocked) return blocked
+
+  log(`Executing ${CONFIG_FILE} through the studio's own Vite for the config check (this takes a few seconds)…`)
+
+  let server
+  try {
+    const chosenPort = port ?? (await pickPort())
+    server = await startConsumerVite({
+      root,
+      studioDir,
+      port: chosenPort,
+      plugins: [virtualModulesPlugin('elytra-config-check', { [CONFIG_CHECK_ID]: configCheckModuleSource(configPath) })],
+    })
+  } catch (error) {
+    return { kind: 'unavailable', reason: `The studio's Vite could not start (${errorSummary(error)}) — config validity was not evaluated here.` }
+  }
+  try {
+    const { runCheck } = await server.ssrLoadModule(CONFIG_CHECK_ID)
+    const outcome = await runCheck()
+    if (outcome.kind === 'config-error') {
+      return { kind: 'config-error', error: errorSummary(outcome.error), file: CONFIG_FILE }
+    }
+    if (outcome.kind === 'harness-error') {
+      return { kind: 'unavailable', reason: `The config check could not run (${errorSummary(outcome.error)}) — config validity was not evaluated here.` }
+    }
+    return { kind: 'resolved', result: outcome.result, file: CONFIG_FILE }
+  } catch (error) {
+    return { kind: 'unavailable', reason: `The config check could not run (${errorSummary(error)}) — config validity was not evaluated here.` }
+  } finally {
+    await server.close()
+  }
+}

package/src/doctor.js

@@ -7,8 +7,10 @@ import {
   probeAuthSigningKeys,
   probeRevalidateEndpoint,
 } from '@elytracms/core/export-sync/deployment-ready'
+import { executeWorkspaceConfig } from './config-harness.js'
 import { convexEnvGet, defaultConvexExec } from './provision.js'
 import { gatherPreviewsArtifacts, previewsDoctorChecks } from './previews.js'
+import { loadProjectRoutes, routesDoctorChecks } from './routes-check.js'
 
 /**
  * `elytra doctor` (EC-259) — the pre-boot counterpart to the studio's boot
@@ -19,8 +21,12 @@ import { gatherPreviewsArtifacts, previewsDoctorChecks } from './previews.js'
  * the studio reports it `unknown`; node has no such limit).
  *
  * Read-only: it only fetches the deployment's public URL and its public JWKS endpoint.
- * It never writes env, never provisions. Facts it can't gather from a bundler-less CLI
- * (config validity, resolved collections, the auth session) are omitted → `unknown`.
+ * It never writes env, never provisions. The auth `session` is never gathered here →
+ * the user checks stay `unknown`. Config validity + resolved collections are gathered
+ * OPPORTUNISTICALLY (EC-495): when `studio/` and its installed deps exist, the config
+ * is executed through the consumer studio's own Vite (the `elytra previews` harness —
+ * see `config-harness.js`) and resolved with the engine's `resolveWorkspaceConfig`;
+ * otherwise those facts are omitted with the specific reason → an honest `unknown`.
  */
 
 // --- Target resolution -------------------------------------------------------
@@ -77,8 +83,9 @@ export async function probeReachable(url, fetchImpl = fetch) {
 
 /**
  * Gather the readiness facts a node CLI can definitively produce for a target. The
- * app/user facts are intentionally omitted (the CLI doesn't execute `elytra.config.ts`
- * and has no auth session) → the contract renders them `unknown`.
+ * user facts are intentionally omitted (no auth session) → `unknown`; the app facts
+ * (config/collections) are gathered separately via the consumer-Vite harness when it
+ * is available (EC-495, {@link configFactsFromOutcome}).
  */
 export async function gatherFacts(target, { fetchImpl = fetch } = {}) {
   if (target.kind === 'playground') return { backend: { kind: 'playground' } }
@@ -92,7 +99,75 @@ export async function gatherFacts(target, { fetchImpl = fetch } = {}) {
     reachable,
     authKeys,
     // A configured URL means a deployment is wired; leave `provisioned` unset (→ ok).
-    // config/collections/session omitted → the app + user checks surface as `unknown`.
+    // session omitted → the user checks surface as `unknown`; config/collections are
+    // merged in by the caller from the EC-495 harness outcome (or stay omitted).
+  }
+}
+
+// --- Config facts via the consumer-Vite harness (EC-495) -------------------------------
+
+/**
+ * One located line for a workspace-config issue: `projects.0.slug: message`.
+ * The path grammar matches the issue's own `path` (config-object addressing).
+ */
+export function formatConfigIssue(issue) {
+  const path = (issue.path ?? []).join('.')
+  return path.length > 0 ? `${path}: ${issue.message}` : issue.message
+}
+
+/**
+ * PURE decision core (EC-495): map a config-harness outcome
+ * ({@link executeWorkspaceConfig}'s union) onto the `DeploymentReadinessFacts`
+ * fields the shared contract consumes. The three honest shapes, and never a
+ * fourth:
+ *
+ *   - `resolved`  → `config` with a real `valid`; on a valid config also the
+ *     first project's `collections` (what the studio mounts — consumers are
+ *     single-project; a multi-project workspace is judged by its first, the
+ *     studio's own default active project).
+ *   - `config-error` → `config.valid: false` with the surfaced `error` (the
+ *     config threw — a definitive fail, not an unavailability).
+ *   - `unavailable` (or no outcome) → NO `config` fact, reason in
+ *     `configUnavailableDetail` → the contract renders `unknown` + why.
+ *
+ * EC-490: `firstIssue` is carried on a VALID config too. A config can resolve
+ * (`ok: true`) and still return warning-severity issues — the resolver's first one
+ * is EC-490's "this project declares no locales, `['en']` was applied". Withholding
+ * the message there is what made the whole warning channel invisible: the contract
+ * renders it as `warn` (see `appChecks`), and a `warn` without its message is a
+ * count nobody can act on.
+ */
+export function configFactsFromOutcome(outcome) {
+  if (!outcome || outcome.kind === 'unavailable') {
+    return outcome?.reason !== undefined ? { configUnavailableDetail: outcome.reason } : {}
+  }
+  if (outcome.kind === 'config-error') {
+    return { config: { valid: false, source: outcome.file, error: outcome.error } }
+  }
+  const { result, file } = outcome
+  const issues = Array.isArray(result?.issues) ? result.issues : []
+  const valid = result?.ok === true
+  // The first ERROR names what failed; with none (a valid config, or an
+  // error-less list) the first issue stands in.
+  const firstIssue = issues.find((issue) => issue.severity === 'error') ?? issues[0]
+  const config = {
+    valid,
+    source: file,
+    issueCount: issues.length,
+    ...(firstIssue ? { firstIssue: formatConfigIssue(firstIssue) } : {}),
+  }
+  const project = valid ? result.projects?.[0] : undefined
+  const collections = project?.collections
+  // EC-524: the `componentIds` fact was gathered here for EC-508's presentation
+  // check, which resolved a collection's declared `presentation.wrapper` against
+  // the registry. The wrapper left config entirely (a detail wrapper is a page
+  // template and templates are code), so the check now reads collection FIELDS
+  // alone and nothing consumes the registry ids. Gathering them was removed
+  // rather than left dangling — neither the fact nor the harness reduction ever
+  // shipped (both landed after the 0.0.81 staging commit).
+  return {
+    config,
+    ...(collections ? { collections } : {}),
   }
 }
 
@@ -236,6 +311,22 @@ const BUCKET_TITLE = {
   previews: 'Previews',
 }
 
+/**
+ * Splice extra checks into an existing bucket's run, right after that bucket's last
+ * check (EC-469). {@link formatReport} opens a bucket heading whenever `check.bucket`
+ * changes, so appending an `app` check after the `user`/`previews` ones would print
+ * "App:" twice. Bucket absent from the report → the extras go at the end. Pure.
+ */
+export function spliceBucketChecks(checks, bucket, extra) {
+  if (extra.length === 0) return [...checks]
+  let last = -1
+  for (let i = 0; i < checks.length; i++) {
+    if (checks[i].bucket === bucket) last = i
+  }
+  if (last === -1) return [...checks, ...extra]
+  return [...checks.slice(0, last + 1), ...extra, ...checks.slice(last + 1)]
+}
+
 /**
  * Render a `DeploymentReadinessReport` as the bucketed doctor report (pure — no I/O,
  * no color, so it's directly testable). Failing AND warning checks print their
@@ -284,6 +375,20 @@ export function formatReport(report) {
  * findings there are warnings (previews are optional); input-hash STALENESS needs
  * the component registry and lives in `elytra previews --check` (the ratified
  * split). `previewsArtifacts` is injectable for tests.
+ *
+ * EC-469: when a project `root` is known, the `app` bucket also reports ROUTE
+ * CONFLICTS, read from the project's React-free `cms/` tree (see `routes-check.js`).
+ * That check CAN fail — a conflict is deterministic in code — so it participates in
+ * the exit code; a route set that cannot be read reports `unknown` with its reason and
+ * never fails. `routeFacts` is injectable for tests.
+ *
+ * EC-495: when a project `root` is known, `config-valid` + `asset-collection` get a
+ * REAL answer by executing `elytra.config.ts` through the consumer studio's own Vite
+ * (see `config-harness.js`) — opportunistic and read-only: without `studio/` or its
+ * installed deps the checks stay honest `unknown`s carrying the reason, and the CLI's
+ * works-without-node_modules contract is untouched. A resolved config also hands the
+ * route checks the same collections the studio actually mounts (superseding the
+ * `cms/index.ts` re-export). `configOutcome` is injectable for tests.
  */
 export async function runDoctor({
   env = {},
@@ -291,9 +396,12 @@ export async function runDoctor({
   log = (l) => console.log(l),
   url,
   studioDir,
+  root,
   aiRouteConfigured = false,
   exec,
   previewsArtifacts,
+  routeFacts,
+  configOutcome,
 } = {}) {
   const target = resolveDoctorTarget(env, { url })
 
@@ -321,16 +429,40 @@ export async function runDoctor({
     })
     if (revalidateProbe) facts.revalidateProbe = revalidateProbe
   }
+
+  // EC-495: execute the config through the consumer studio's own Vite when possible
+  // (announced by the harness itself — the boot costs seconds). Merged BEFORE the
+  // contract composes the report so `config-valid`/`asset-collection` are real checks.
+  let configFacts = {}
+  if (configOutcome !== undefined || root !== undefined) {
+    const outcome = configOutcome ?? (await executeWorkspaceConfig({ root, studioDir, log }))
+    configFacts = configFactsFromOutcome(outcome)
+    Object.assign(facts, configFacts)
+  }
+
   const report = checkDeploymentReady(facts)
 
   // EC-440: the previews bucket (repo artifacts, backend-independent). Appended to
   // the shared report before formatting so it wears the same glyph/fix conventions;
-  // its checks are ok/warn/unknown only, so `report.ok` (the exit code) is unchanged.
+  // its checks are ok/warn/unknown only, so the exit code is unchanged by them.
   const artifacts = previewsArtifacts ?? (studioDir ? gatherPreviewsArtifacts(studioDir) : undefined)
-  const merged = artifacts
-    ? { ...report, checks: [...report.checks, ...previewsDoctorChecks(artifacts)] }
-    : report
+  let checks = artifacts ? [...report.checks, ...previewsDoctorChecks(artifacts)] : [...report.checks]
+
+  // EC-469: the route-conflict check, spliced into the `app` bucket it belongs to.
+  // Backend-independent (routes are CODE) — it runs in playground mode too.
+  // EC-495: a resolved config supersedes the `cms/index.ts` collections re-export —
+  // the route checks judge mounts against the same collections the studio mounts.
+  if (root !== undefined || routeFacts !== undefined) {
+    const loaded = routeFacts ?? (await loadProjectRoutes(root))
+    const enriched = configFacts.collections ? { ...loaded, collections: configFacts.collections } : loaded
+    checks = spliceBucketChecks(checks, 'app', routesDoctorChecks(enriched))
+  }
+
+  // One rule for the exit code, the same one `checkDeploymentReady` applies: a
+  // report is ok when nothing FAILED. Recomputed over the merged set so an appended
+  // bucket's failure can never be silently dropped from the exit code.
+  const merged = { ok: !checks.some((c) => c.status === 'fail'), checks }
 
   log(formatReport(merged))
-  return report.ok ? 0 : 1
+  return merged.ok ? 0 : 1
 }