@elytracms/cli 0.0.81 → 0.0.83

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.81",
+  "version": "0.0.83",
   "description": "The Elytra CLI — run a consuming repo's studio, frontend, and Convex backend under one command.",
   "license": "MIT",
   "type": "module",
@@ -14,10 +14,10 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22.18.0"
   },
   "dependencies": {
-    "@elytracms/core": "^0.0.81"
+    "@elytracms/core": "^0.0.83"
   },
   "devDependencies": {
     "vitest": "^4.1.10"

package/src/cli.js

@@ -115,6 +115,9 @@ 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:
@@ -457,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) {

package/src/config-harness.js

@@ -0,0 +1,320 @@
+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.
+ */
+/**
+ * React specifiers the automatic-JSX transform injects, aliased to the STUDIO's
+ * own copies (EC-537).
+ *
+ * `jsx: 'automatic'` below rewrites every transformed `.tsx` to import
+ * `react/jsx-dev-runtime`, and Vite resolves a bare specifier from the
+ * IMPORTER's directory. A consumer's page-builder components live at their repo
+ * root, outside `studioDir` — so on a repo whose root `package.json` does not
+ * declare react, every one of them fails to resolve and `config-valid` reports
+ * a config that "could not be executed", taking `asset-collection` and
+ * `presentation-targets` down with it.
+ *
+ * Measured 2026-08-02 on a real `create-elytra@0.0.82` scaffold, both
+ * directions: with react at the root `✓ config-valid` (11 ok); with react
+ * removed, `✗ Cannot find module 'react/jsx-dev-runtime' imported from
+ * components/marketing/hero.tsx` and three checks lost. Both production
+ * consumers hit exactly this on upgrading and both added react to their root.
+ *
+ * That was a workaround for a requirement the HARNESS invented: automatic JSX is
+ * our transform setting, chosen for our convenience, in a boot whose only job is
+ * to *evaluate* a config — nothing here mounts or renders. So the package that
+ * mandated React supplies it. The studio always has react (it is a React app),
+ * and resolving from `studioDir` is what this harness already does for `vite`
+ * itself, one line above.
+ *
+ * Opportunistic by contract, like everything else in this file: a specifier that
+ * cannot be resolved is simply left unaliased rather than throwing, so a partial
+ * install degrades to the previous behaviour instead of crashing the CLI.
+ */
+export function reactRuntimeFromStudioPlugin(studioDir) {
+  // Resolve THROUGH VITE, from a studio-side importer — never to a raw path.
+  //
+  // The obvious implementation is `resolve.alias` to
+  // `createRequire(studioDir).resolve('react/jsx-dev-runtime')`. That was tried
+  // first and is wrong twice over (both measured 2026-08-02): `createRequire`
+  // returns the **CJS** entry, and an absolute-path alias bypasses Vite's
+  // exports-map/condition/interop handling entirely, so its SSR runner
+  // evaluates CommonJS as ESM — `elytra previews` died with
+  // `ReferenceError: module is not defined` at `react/index.js:9`, then at
+  // `react/jsx-dev-runtime.js:9` when the alias was narrowed.
+  //
+  // Handing Vite a studio-side *importer* instead lets its own resolver do the
+  // work — right conditions, right ESM build — while only changing WHERE the
+  // lookup starts. That is the whole intent: not a different React, just one
+  // that can be found.
+  const importer = join(studioDir, '__elytra-harness__.js')
+  return {
+    name: 'elytra:react-runtime-from-studio',
+    async resolveId(id, from) {
+      if (id !== 'react/jsx-runtime' && id !== 'react/jsx-dev-runtime') return null
+      // Only rescue importers OUTSIDE the studio (the consumer's root-level
+      // components). Anything already inside studio/ resolves on its own, and
+      // intercepting it would be a silent no-op at best.
+      if (from === undefined || from.startsWith(studioDir)) return null
+      const resolved = await this.resolve(id, importer, { skipSelf: true })
+      return resolved ?? null
+    },
+  }
+}
+
+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',
+    // EC-537 — the rescue runs BEFORE the caller's plugins so nothing downstream
+    // has to know about it. `dedupe` rides along: once the consumer's components
+    // and the studio can both resolve React, they must agree on ONE copy.
+    plugins: [reactRuntimeFromStudioPlugin(studioDir), ...(plugins ?? [])],
+    resolve: { dedupe: ['react', 'react-dom'] },
+    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,6 +7,7 @@ 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'
@@ -20,8 +21,12 @@ import { loadProjectRoutes, routesDoctorChecks } from './routes-check.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 -------------------------------------------------------
@@ -78,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' } }
@@ -93,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 } : {}),
   }
 }
 
@@ -307,6 +381,14 @@ export function formatReport(report) {
  * 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 = {},
@@ -319,6 +401,7 @@ export async function runDoctor({
   exec,
   previewsArtifacts,
   routeFacts,
+  configOutcome,
 } = {}) {
   const target = resolveDoctorTarget(env, { url })
 
@@ -346,6 +429,17 @@ 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
@@ -356,9 +450,12 @@ export async function runDoctor({
 
   // 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 facts = routeFacts ?? (await loadProjectRoutes(root))
-    checks = spliceBucketChecks(checks, 'app', routesDoctorChecks(facts))
+    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

package/src/engine-build-failure.js

@@ -0,0 +1,88 @@
+import { existsSync } from 'node:fs'
+
+/**
+ * EC-503 — attribute "the engine has no build output" to its real cause.
+ *
+ * This CLI loads the engine's COMPILED output under plain Node: `doctor.js`
+ * imports `@elytracms/core/export-sync/deployment-ready` and `routes-check.js`
+ * imports `@elytracms/core/cms-core`, both of which resolve to
+ * `@elytracms/core/dist/...` (no bundler, no `development` export condition).
+ * Those are static imports at the top of `src/cli.js`'s graph, so when that dist
+ * is absent or half-written NOTHING runs — `elytra --help` itself dies with a raw
+ * `ERR_MODULE_NOT_FOUND` stack naming a compiled file the developer never wrote
+ * (measured 2026-08-01: moved `dist/export-sync/deployment-ready.js` aside, ran
+ * `elytra --help`, got the stack and exit 1).
+ *
+ * The state is easy to reach and has nothing to do with the person who hits it:
+ * every package build starts by DELETING dist (`rmSync('dist')` then `tsc`), so
+ * any `pnpm build` / `pnpm verify` / `pnpm typecheck` that dies partway — for a
+ * reason anywhere in the workspace — leaves the tree in it. The tool you would
+ * reach for to find out what is wrong is the tool that stops working, and its
+ * error names the wrong thing.
+ *
+ * So the CLI's job here is not to recover — it genuinely cannot run without the
+ * engine — but to FAIL WITH THE TRUE CAUSE AND ONE COMMAND. This module is the
+ * pure decision core; `index.js` is the impure shell that catches and prints it.
+ */
+
+/** `ERR_MODULE_NOT_FOUND` carries the unresolvable file on `url`; older shapes only in the message. */
+function missingUrlOf(error) {
+  if (typeof error?.url === 'string') return error.url
+  const match = /Cannot find module '([^']+)'/.exec(String(error?.message ?? ''))
+  return match ? match[1] : undefined
+}
+
+/**
+ * Split an `@elytracms/<pkg>/…/dist/…` path into the package name and the
+ * package root. Returns `undefined` for anything that is not an engine dist
+ * path — a missing module elsewhere is somebody else's bug and must keep its
+ * own error verbatim.
+ */
+export function parseEngineDistPath(path) {
+  if (typeof path !== 'string') return undefined
+  const match = /(.*\/@elytracms\/([^/]+))\/dist\//.exec(path.replace(/^file:\/\//, ''))
+  if (!match) return undefined
+  return { packageName: `@elytracms/${match[2]}`, packageRoot: decodeURIComponent(match[1]) }
+}
+
+/**
+ * Is this package a LINKED workspace checkout rather than an installed tarball?
+ * Discriminated by what the published artifact contains: `@elytracms/core` ships
+ * `files: ["dist"]` and `@elytracms/studio` ships `["dist","convex","src/styles"]`
+ * — neither publishes `src/lib`, so its presence means a source checkout. Path
+ * shape is NOT usable here: pnpm's workspace link makes a linked package resolve
+ * through `node_modules/@elytracms/…` exactly like an installed one (measured —
+ * the failing url was `packages/cli/node_modules/@elytracms/core/dist/…`).
+ */
+export function isLinkedWorkspacePackage(packageRoot, exists = existsSync) {
+  return exists(`${packageRoot}/src/lib`) || exists(`${packageRoot}/src/index.ts`) || exists(`${packageRoot}/tsconfig.build.json`)
+}
+
+/**
+ * The attributed message for an engine-dist load failure, or `null` when the
+ * error is anything else (which must then propagate untouched — swallowing a
+ * real bug behind a friendly line is the failure mode this whole file exists to
+ * avoid at one level up).
+ */
+export function engineBuildFailureMessage(error, { exists = existsSync } = {}) {
+  if (error?.code !== 'ERR_MODULE_NOT_FOUND') return null
+  const parsed = parseEngineDistPath(missingUrlOf(error))
+  if (!parsed) return null
+  const { packageName, packageRoot } = parsed
+  const fix = isLinkedWorkspacePackage(packageRoot, exists)
+    ? `  pnpm --filter ${packageName} build`
+    : '  pnpm install --force        (the installed package is incomplete)'
+  return [
+    `elytra: ${packageName} has no usable build output, so no elytra command can run.`,
+    '',
+    `  missing: ${missingUrlOf(error)}`,
+    '',
+    'The CLI loads the engine’s compiled output under plain Node. A package build',
+    'DELETES its dist before writing it, so any interrupted `pnpm build` / `pnpm verify`',
+    '— for any reason, anywhere in the workspace — leaves it missing or half-written.',
+    '',
+    'Fix:',
+    fix,
+    '',
+  ].join('\n')
+}

package/src/previews.js

@@ -1,9 +1,8 @@
 import { createHash } from 'node:crypto'
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } 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'
+import { pickPort, resolveFromDir, startConsumerVite, virtualModulesPlugin } from './config-harness.js'
 
 /**
  * `elytra previews` (EC-440) — build-time fixture-preview generation.
@@ -19,9 +18,8 @@ import { pathToFileURL } from 'node:url'
  *     the blocks-panel tile);
  *   - a previews manifest to `studio/elytra-previews.json` (importable next to
  *     `studio.config.tsx`) carrying per entry: componentId, fixture, URL, and
- *     an input hash (manifest prop/slot shape + fixture props + engine
- *     version) — no timestamps, so unchanged inputs re-serialize to the same
- *     bytes.
+ *     an input hash (manifest prop/slot shape + fixture props) — no
+ *     timestamps, so unchanged inputs re-serialize to the same bytes.
  *
  * Idempotence: an entry whose input hash matches the existing manifest AND
  * whose image file exists is skipped entirely (screenshots are not guaranteed
@@ -29,10 +27,9 @@ import { pathToFileURL } from 'node:url'
  * compare); the manifest is only written when its bytes change. A re-run with
  * unchanged inputs therefore rewrites nothing.
  *
- * Harness: the CLI boots the consumer studio app's own Vite PROGRAMMATICALLY
- * (resolved from the studio dir; a minimal inline config — the studio's
- * `vite.config.ts`, with its app plugins/env, is deliberately NOT loaded) and
- * serves a DATA-FREE render page that imports exactly the consumer registry
+ * Harness: the shared consumer-Vite boot (`config-harness.js`, EC-495 — one
+ * mechanism for this command and `elytra doctor`'s config check) plus a
+ * DATA-FREE render page that imports exactly the consumer registry
  * (`elytra.config.ts`) and the consumer theme. Enumeration + hashing run
  * node-side through the same Vite (`ssrLoadModule`), so `--check` needs no
  * browser; rendering drives headless Chromium via Playwright — an ON-DEMAND
@@ -53,8 +50,13 @@ export const PREVIEWS_DIR = join('public', 'elytra-previews')
 export const PREVIEWS_MANIFEST_FILE = 'elytra-previews.json'
 /** Root-relative URL prefix the manifest entries carry. */
 export const PREVIEWS_URL_PREFIX = '/elytra-previews/'
-/** Manifest format version (mirrors `@elytracms/studio`'s PREVIEWS_MANIFEST_VERSION). */
-export const PREVIEWS_MANIFEST_VERSION = 1
+/**
+ * Manifest format version (mirrors `@elytracms/studio`'s PREVIEWS_MANIFEST_VERSION).
+ * `2` (EC-502): the entry hash no longer includes the engine version, so v1 hashes
+ * are not comparable with v2 ones — a version mismatch is reported as itself
+ * ("regenerate"), never as N bogus `stale` entries.
+ */
+export const PREVIEWS_MANIFEST_VERSION = 2
 
 /** Capture geometry: 1280×800 CSS pixels (a desktop render), shot at 0.5 → 640×400 (16/10). */
 export const CAPTURE = { width: 1280, height: 800, scale: 0.5 }
@@ -107,14 +109,28 @@ function sortValue(value) {
 /**
  * The staleness input hash: sha-256 over the stable-serialized render inputs —
  * the manifest's prop/slot shape + the fixture's own props/slotChildren (from
- * the studio's `previewEntriesForConfig`) + the installed engine version.
- * Implementation and theme drift are deliberately NOT hashed (the ratified
- * split: those are caught by regeneration runs, e.g. in the consumer's build).
+ * the studio's `previewEntriesForConfig`). Implementation and theme drift are
+ * deliberately NOT hashed (the ratified EC-440 split: those are caught by
+ * regeneration runs, e.g. in the consumer's build).
+ *
+ * **EC-502 — the engine version was removed from this hash.** It made every
+ * release invalidate every committed preview in every repo, so `elytra previews
+ * --check` was red on a healthy tree for a reason that had nothing to do with any
+ * entry. Measured on `apps/demo` 2026-08-01: all 23 committed hashes reproduced
+ * byte-identically at the manifest's recorded engine (0.0.70) against today's
+ * inputs — 0 entries had drifted, yet all 23 reported `stale`, burying the ONE
+ * real problem (a new fixture with no image) at line 12 of 24.
+ *
+ * The engine version is engine IMPLEMENTATION, and implementation is the exact
+ * category the ratified split already puts outside `--check`'s remit; treating the
+ * engine's as an ERROR while a consumer component's is not even a warning was
+ * incoherent, and the incoherence is what produced the permanent red. It is still
+ * recorded in the manifest (which engine rendered these images) and still reported
+ * on every `--check` run — as a WARNING that does not fail the gate. See
+ * {@link checkPreviews}.
  */
-export function previewEntryHash(hashInput, engineVersion) {
-  return createHash('sha256')
-    .update(stableStringify({ engine: engineVersion, input: hashInput }), 'utf8')
-    .digest('hex')
+export function previewEntryHash(hashInput) {
+  return createHash('sha256').update(stableStringify({ input: hashInput }), 'utf8').digest('hex')
 }
 
 /** Serialize the previews manifest deterministically (sorted entry keys, LF, trailing newline). */
@@ -165,17 +181,45 @@ export function planPreviewRun({ specs, existing, files }) {
 
 /**
  * `--check` verdicts: compare the enumerated entry set (+ fresh hashes)
- * against the committed manifest + image files. Every problem names its
- * entry; an empty list is green.
+ * against the committed manifest + image files.
+ *
+ * Two channels, and the distinction is the whole point (EC-502):
+ *
+ *   - **problems** fail the gate (exit 1). Each one means an artifact does not
+ *     match what the config declares: a fixture with no preview, a preview whose
+ *     declared inputs changed, a manifest entry whose image is gone, an entry or
+ *     file nothing enumerates any more.
+ *   - **warnings** are reported and do NOT fail. Today that is exactly one:
+ *     `engine-drift` — these images were rendered by a different engine version.
+ *     True and worth saying, but it is implementation drift, the same category
+ *     the ratified EC-440 split already leaves to regeneration runs; as a failure
+ *     it fired on every entry of every repo on every release and taught people
+ *     that red means nothing.
+ *
+ * A manifest written by an older FORMAT version is its own problem: its hashes were
+ * computed under different semantics, so comparing them would print one meaningless
+ * `stale` line per entry. Say the real thing once, and skip the hash comparison
+ * (entry-set and file checks still run — they are version-independent).
  */
-export function checkPreviews({ specs, manifest, files }) {
+export function checkPreviews({ specs, manifest, files, engine }) {
   const problems = []
+  const warnings = []
   if (!manifest) {
     for (const spec of specs) {
       problems.push({ kind: 'missing', componentId: spec.componentId, fixture: spec.fixture })
     }
-    return { ok: specs.length === 0, problems }
+    return { ok: specs.length === 0, problems, warnings }
+  }
+
+  const version = typeof manifest.version === 'number' ? manifest.version : 0
+  const comparableHashes = version === PREVIEWS_MANIFEST_VERSION
+  if (!comparableHashes) {
+    problems.push({ kind: 'manifest-version', from: version, to: PREVIEWS_MANIFEST_VERSION })
+  }
+  if (engine !== undefined && manifest.engine !== undefined && manifest.engine !== engine) {
+    warnings.push({ kind: 'engine-drift', from: manifest.engine, to: engine })
   }
+
   const entryByKey = new Map(manifest.entries.map((e) => [key(e), e]))
   const specKeys = new Set(specs.map((s) => key(s)))
 
@@ -186,7 +230,7 @@ export function checkPreviews({ specs, manifest, files }) {
       continue
     }
     const file = fileOfUrl(entry.url)
-    if (entry.hash !== spec.hash) {
+    if (comparableHashes && entry.hash !== spec.hash) {
       problems.push({ kind: 'stale', componentId: spec.componentId, fixture: spec.fixture })
     } else if (!file || !files.includes(file)) {
       problems.push({ kind: 'missing-file', componentId: spec.componentId, fixture: spec.fixture, file })
@@ -203,7 +247,7 @@ export function checkPreviews({ specs, manifest, files }) {
       problems.push({ kind: 'orphan-file', file })
     }
   }
-  return { ok: problems.length === 0, problems }
+  return { ok: problems.length === 0, problems, warnings }
 }
 
 /** One line per problem, stable order, for `--check` output. */
@@ -215,10 +259,24 @@ export function formatCheckProblems(problems) {
     'orphan-entry': 'orphaned  ',
     'orphan-file': 'stray file',
   }
-  return problems.map((p) =>
-    p.kind === 'orphan-file'
+  return problems.map((p) => {
+    if (p.kind === 'manifest-version') {
+      return `  ✗ manifest   written in format v${p.from}, this CLI writes v${p.to} — hashes are not comparable; regenerate`
+    }
+    return p.kind === 'orphan-file'
       ? `  ✗ ${label[p.kind]} ${p.file}`
-      : `  ✗ ${label[p.kind]} ${p.componentId} · ${p.fixture}${p.file ? ` (${p.file})` : ''}`,
+      : `  ✗ ${label[p.kind]} ${p.componentId} · ${p.fixture}${p.file ? ` (${p.file})` : ''}`
+  })
+}
+
+/** One line per warning — reported, never fatal (EC-502). */
+export function formatCheckWarnings(warnings) {
+  return warnings.map((w) =>
+    w.kind === 'engine-drift'
+      ? `  ! engine     these images were rendered by engine ${w.from}; installed is ${w.to}. ` +
+        'Declared inputs are unchanged, so this does not fail the check — ' +
+        'run `elytra previews` when you want the images re-rendered.'
+      : `  ! ${w.kind}`,
   )
 }
 
@@ -332,11 +390,6 @@ export function previewsDoctorChecks(artifacts) {
 
 // --- Impure plumbing ---------------------------------------------------------------
 
-/** Resolve a module specifier from a directory's own node_modules world. */
-function resolveFromDir(dir, specifier) {
-  return createRequire(join(dir, 'package.json')).resolve(specifier)
-}
-
 /**
  * The engine version for the input hash — read from the `@elytracms/studio`
  * (fallback `@elytracms/core`) package the CONSUMER has installed, never
@@ -390,68 +443,52 @@ const HARNESS_HTML = `<!doctype html>
 `
 
 /**
- * The inline Vite plugin serving the DATA-FREE harness: two virtual modules
- * (the browser render entry; the node-side enumeration) that import exactly
- * the consumer config + theme + the studio previews modules — no studio app
- * code, no persistence, no auth, no env.
+ * The inline Vite plugins serving the DATA-FREE harness: two virtual modules
+ * (the browser render entry; the node-side enumeration — via the shared
+ * {@link virtualModulesPlugin}) that import exactly the consumer config +
+ * theme + the studio previews modules — no studio app code, no persistence,
+ * no auth, no env — plus the middleware serving the render page itself.
  */
-function harnessPlugin({ configPath, themePath }) {
+function harnessPlugins({ configPath, themePath }) {
   const configImport = `/@fs/${configPath}`
   const themeImport = `/@fs/${themePath}`
-  return {
-    name: 'elytra-previews-harness',
-    resolveId(id) {
-      return id === ENTRY_ID || id === ENUMERATE_ID ? id : null
-    },
-    load(id) {
-      if (id === ENTRY_ID) {
-        return [
-          `import '${themeImport}'`,
-          `import config from '${configImport}'`,
-          `import { mountPreviewHarness } from '@elytracms/studio/previews/harness'`,
-          `mountPreviewHarness(config)`,
-        ].join('\n')
-      }
-      if (id === ENUMERATE_ID) {
-        return [
-          `import config from '${configImport}'`,
-          `import { previewEntriesForConfig } from '@elytracms/studio/previews/enumerate'`,
-          `export const entries = previewEntriesForConfig(config)`,
-        ].join('\n')
-      }
-      return null
-    },
-    configureServer(server) {
-      server.middlewares.use((req, res, next) => {
-        if (!req.url || req.url.split('?')[0] !== HARNESS_PATH) return next()
-        server
-          .transformIndexHtml(req.url, HARNESS_HTML)
-          .then((html) => {
-            res.setHeader('content-type', 'text/html')
-            res.end(html)
-          })
-          .catch(next)
-      })
+  return [
+    virtualModulesPlugin('elytra-previews-harness', {
+      [ENTRY_ID]: [
+        `import '${themeImport}'`,
+        `import config from '${configImport}'`,
+        `import { mountPreviewHarness } from '@elytracms/studio/previews/harness'`,
+        `mountPreviewHarness(config)`,
+      ].join('\n'),
+      [ENUMERATE_ID]: [
+        `import config from '${configImport}'`,
+        `import { previewEntriesForConfig } from '@elytracms/studio/previews/enumerate'`,
+        `export const entries = previewEntriesForConfig(config)`,
+      ].join('\n'),
+    }),
+    {
+      name: 'elytra-previews-harness-page',
+      configureServer(server) {
+        server.middlewares.use((req, res, next) => {
+          if (!req.url || req.url.split('?')[0] !== HARNESS_PATH) return next()
+          server
+            .transformIndexHtml(req.url, HARNESS_HTML)
+            .then((html) => {
+              res.setHeader('content-type', 'text/html')
+              res.end(html)
+            })
+            .catch(next)
+        })
+      },
     },
-  }
-}
-
-/** First free port in [start, start+span) — never a hardcoded single port. */
-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}.`)
+  ]
 }
 
-/** Boot the consumer studio's Vite with the minimal inline harness config. */
+/** Boot the shared consumer-Vite harness with the previews page + modules. */
 async function startHarnessServer({ root, studioDir, port }) {
-  const vite = await import(pathToFileURL(resolveFromDir(studioDir, 'vite')).href)
+  // Resolve vite first so a missing toolchain names vite (the same failure
+  // order as before the boot moved to the shared config-harness).
+  resolveFromDir(studioDir, 'vite')
   const tailwindEntry = resolveFromDir(studioDir, '@tailwindcss/vite')
   const tailwind = (await import(pathToFileURL(tailwindEntry).href)).default
 
@@ -464,22 +501,12 @@ async function startHarnessServer({ root, studioDir, port }) {
     )
   }
 
-  const server = await vite.createServer({
-    configFile: false,
-    root: studioDir,
-    mode: 'development',
-    appType: 'custom',
-    logLevel: 'warn',
-    plugins: [tailwind(), harnessPlugin({ configPath, themePath })],
-    server: {
-      port,
-      strictPort: true,
-      host: '127.0.0.1',
-      fs: { allow: [vite.searchForWorkspaceRoot(studioDir), root] },
-    },
-    esbuild: { jsx: 'automatic' },
+  const server = await startConsumerVite({
+    root,
+    studioDir,
+    port,
+    plugins: [tailwind(), ...harnessPlugins({ configPath, themePath })],
   })
-  await server.listen()
   return { server, url: `http://127.0.0.1:${port}${HARNESS_PATH}` }
 }
 
@@ -587,7 +614,8 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
   const imagesDir = join(studioDir, PREVIEWS_DIR)
 
   log(`Elytra previews — fixture preview ${check ? 'staleness check' : 'generation'}`)
-  log(`Engine version (hash input): ${engine}`)
+  // EC-502: recorded on the manifest, NOT hashed into the entries.
+  log(`Engine version (recorded on the manifest): ${engine}`)
 
   const chosenPort = port ? Number(port) : await pickPort()
   let harness
@@ -604,7 +632,7 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
     const specs = entries.map((entry) => ({
       componentId: entry.componentId,
       fixture: entry.fixture,
-      hash: previewEntryHash(entry.hashInput, engine),
+      hash: previewEntryHash(entry.hashInput),
     }))
     log(`Enumerated ${specs.length} fixture preview(s) from elytra.config.ts.`)
 
@@ -612,7 +640,15 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
     const existing = parsePreviewsManifest(artifacts.manifestText)
 
     if (check) {
-      const { ok, problems } = checkPreviews({ specs, manifest: existing, files: artifacts.files })
+      const { ok, problems, warnings } = checkPreviews({
+        specs,
+        manifest: existing,
+        files: artifacts.files,
+        engine,
+      })
+      // Warnings print on BOTH verdicts — a green run that still has something to
+      // say says it, and a red run does not swallow it.
+      for (const line of formatCheckWarnings(warnings)) log(line)
       if (ok) {
         log(`✓ ${specs.length} preview(s) up to date (hashes match, all files present).`)
         return 0

package/src/project.js

@@ -6,9 +6,12 @@ import { dirname, join } from 'node:path'
  * executing: a consuming repo's layout (`studio/`, `frontend/`, root
  * `elytra.config.ts`) and its `.env` are the source of truth — the same `.env`
  * the studio itself reads to resolve its backend (`VITE_ELYTRA_MODE` /
- * `VITE_CONVEX_URL`). We deliberately do NOT load the TS config (no TS runtime
- * dependency); the paths are conventional and the operative backend signal lives
- * in env regardless.
+ * `VITE_CONVEX_URL`). Detection deliberately does NOT load the config: it must work
+ * before `pnpm install`, the paths are conventional, and the operative backend signal
+ * lives in env regardless. (Commands that need the config's CONTENTS execute it
+ * through the consumer's own Vite instead — `config-harness.js`, EC-440/EC-495 — and
+ * degrade honestly when that is unavailable. Node-native TS is not an option: real
+ * configs import `.tsx` barrels, EC-474.)
  */
 
 /** Walk up from `start` until a directory containing `elytra.config.ts` is found. */

package/src/routes-check.js

@@ -42,12 +42,16 @@ import {
  * catch-all with a dynamic prefix that every router drops and no mount is built from.
  * All three were measured to resolve `notFound` with zero issues on every surface.
  *
- * **Loading the routes.** Doctor deliberately executes no `elytra.config.ts` (it
- * imports React components). But a project's `cms/` tree is React-free by convention
- * — measured across `apps/demo`, the scaffold template, and both real consumer repos:
- * every external import is `import type`, erased by Node's own TypeScript support. So
- * doctor imports `cms/index.ts` natively, with no bundler and no Vite, and reads the
- * same `collections` + `routes` that `elytra.config.ts` passes straight through.
+ * **Loading the routes.** This check runs with NO bundler and NO installed deps: a
+ * project's `cms/` tree is React-free by convention — measured across `apps/demo`, the
+ * scaffold template, and both real consumer repos: every external import is
+ * `import type`, erased by Node's own TypeScript support. So doctor imports
+ * `cms/index.ts` natively and reads the same `collections` + `routes` that
+ * `elytra.config.ts` passes straight through. (`elytra.config.ts` itself is NOT
+ * loadable this way — it imports `.tsx` component barrels, which no Node version
+ * executes, EC-474. Where the consumer's deps ARE installed, EC-495's Vite harness
+ * executes the full config and `runDoctor` hands the collections it resolved to these
+ * checks in place of the `cms/index.ts` re-export; this loader stays the floor.)
  *
  * Two things stand in the way, and both are handled rather than assumed away:
  *
@@ -171,7 +175,13 @@ export async function loadProjectRoutes(root, { importModule } = {}) {
   const entry = join(root, CMS_ENTRY)
   if (!existsSync(entry)) {
     return {
-      unavailable: `No ${CMS_ENTRY} found — routes are declared in the project's cms/ directory.`,
+      // EC-533: state what this FALLBACK looked for, not what a project must contain.
+      // Elytra requires one thing of a repo — an `elytra.config.ts` of the right shape
+      // — and no blessed module paths (EC-532). `cms/index.ts` is the scaffold's own
+      // convention, which is all this bundler-free loader can find on its own; where
+      // the project's deps are installed, EC-495's Vite harness executes the real
+      // config and this floor is never reached.
+      unavailable: `Routes not checked: no ${CMS_ENTRY} to read without a bundler (this is the scaffold's convention, not a requirement — your routes may be declared elsewhere).`,
     }
   }