@mettlecast/domain-cli 0.2.60 → 0.2.62

package/src/builder/build-registry.ts

@@ -1,22 +1,24 @@
 import { relative, resolve } from 'node:path';
 import type {
   DomainRegistry,
-  ApiRegistryEntry,
-  ApiVersionSnapshot,
+  ActionRegistryEntry,
   SchemaSnapshot,
   WebhookRegistryEntry,
   SubscriberRegistryEntry,
   ScheduleRegistryEntry,
   JobRegistryEntry,
-  ActionRegistryEntry,
   IntegrationRegistryEntry,
   EventRegistryEntry,
   DomainRegistryEntry,
   SerialDeploymentConfig,
-} from '@mettlecast/domain-cdk-packer';
+} from '../types.js';
 import { walkDomainDir } from '../utils/file-helpers.js';
 import { loadModuleExports, type RawPrimitiveExport } from './load-module.js';
 
+// Issue #4689: the legacy `defineApi` primitive was removed from
+// `@mettlecast/domain-runtime`. The only HTTP endpoint surface in
+// the new registry is `actions[]` whose `exposure.type === 'api'`.
+
 type ActionBackendAccess = 'private' | 'domain' | 'platform';
 
 type ActionExposure =
@@ -190,9 +192,8 @@ export async function buildRegistry(domainRoot: string): Promise<BuildResult> {
     defaultDeployment: deployment(domainRaw),
   };
 
-  const [apiExports, webhookExports, subscriberExports, actionExports,
+const [webhookExports, subscriberExports, actionExports,
          scheduleExports, jobExports, integrationExports, eventExports] = await Promise.all([
-    Promise.all(paths.apis.map(load)),
     Promise.all(paths.webhooks.map(load)),
     Promise.all(paths.subscribers.map(load)),
     Promise.all(paths.actions.map(load)),
@@ -202,43 +203,6 @@ export async function buildRegistry(domainRoot: string): Promise<BuildResult> {
     paths.publishes ? load(paths.publishes) : Promise.resolve([]),
   ]);
 
-  const VALID_API_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']);
-
-  const apis: ApiRegistryEntry[] = paths.apis.flatMap((filePath, i) =>
-    (apiExports[i] ?? [])
-      .filter(e => e['_kind'] === 'api')
-      .map(e => {
-        const rawMethod = typeof e['method'] === 'string' ? e['method'].toUpperCase() : '';
-        if (!rawMethod || !VALID_API_METHODS.has(rawMethod)) {
-          warnings.push(`${relPath(filePath)}: defineApi "${e['id']}" has invalid or missing method "${rawMethod || '(none)'}". Use one of: ${[...VALID_API_METHODS].join(', ')}.`);
-        }
-        const rawVersions = e['versions'] as Record<string, { input?: unknown; output?: unknown }> | undefined;
-        const versionSnapshots: ApiVersionSnapshot[] = rawVersions
-          ? Object.entries(rawVersions).map(([ver, v]) => ({
-              version: ver,
-              requestSchema: isJsonSchema(v?.input) ? (v.input as SchemaSnapshot) : undefined,
-              responseSchema: isJsonSchema(v?.output) ? (v.output as SchemaSnapshot) : undefined,
-            }))
-          : [];
-        const latestVersion = versionSnapshots[versionSnapshots.length - 1];
-        return {
-          id: String(e['id']),
-          kind: 'api' as const,
-          handlerFile: relPath(filePath),
-          path: String(e['path']),
-          method: VALID_API_METHODS.has(rawMethod) ? rawMethod : 'GET',
-          authType: ((e['auth'] as { type?: string } | undefined)?.type as 'jwt' | 'api-key' | 'none' | undefined) ?? 'jwt',
-          description: typeof e['description'] === 'string' ? e['description'] : undefined,
-          deployment: deployment(e),
-          outboundAccess: outboundAccess(e),
-          requestSchema: latestVersion?.requestSchema,
-          responseSchema: latestVersion?.responseSchema,
-          versions: versionSnapshots.length > 0 ? versionSnapshots : undefined,
-          examples: (e['examples'] as { request?: Record<string, unknown>; response?: Record<string, unknown> } | undefined),
-        };
-      })
-  );
-
   const webhooks: WebhookRegistryEntry[] = paths.webhooks.flatMap((filePath, i) =>
     (webhookExports[i] ?? [])
       .filter(e => e['_kind'] === 'webhook')
@@ -374,7 +338,6 @@ export async function buildRegistry(domainRoot: string): Promise<BuildResult> {
     schemaVersion: '1',
     domainRoot,
     domain,
-    apis,
     webhooks,
     subscribers,
     schedules,

package/src/builder/build-types.ts

@@ -1,4 +1,4 @@
-import type { DomainRegistry } from '@mettlecast/domain-cdk-packer';
+import type { DomainRegistry } from '../types.js';
 
 /**
  * Generate a .d.ts file declaring typed `ctx.actions.call(actionId, input)`

package/src/cli.ts

@@ -13,6 +13,8 @@ import { runAddModule } from './commands/add-module.js';
 import { runBuildFlows } from './commands/build-flows.js';
 import { runDoctor } from './commands/doctor.js';
 import { runCheckHashes } from './commands/check-hashes.js';
+import { runUpdateAll } from './commands/update-all.js';
+import { runRegenerateModulesHashes } from './commands/regenerate-modules-hashes.js';
 import { runUpgradeBackend } from './commands/upgrade-backend.js';
 import { runAddPage } from './commands/add-page.js';
 import { runCreateProject } from './commands/create-project.js';
@@ -73,7 +75,7 @@ program
 
 program
   .command('dev <domain>')
-  .description('Start a local HTTP server simulating API Gateway for all defineApi handlers')
+  .description('Start a local HTTP server simulating API Gateway for all API-exposed defineAction handlers')
   .option('--port <n>', 'Port to listen on', '3000')
   .action(async (domain: string, opts: { port?: string }) => {
     await runDev({ domainRoot: domain, port: opts.port ? parseInt(opts.port, 10) : 3000 });
@@ -195,11 +197,29 @@ program
 program
   .command('check-hashes')
   .description('Verify infra/modules/ has not been hand-edited since last scaffold')
-  .action(async () => {
-    const result = await runCheckHashes({});
+  .option('--write', 'Regenerate modules-hashes.json from current disk state instead of verifying')
+  .action(async (opts: { write?: boolean }) => {
+    const result = await runCheckHashes({ write: opts.write });
     process.exit(result.ok ? 0 : 1);
   });
 
+program
+  .command('update-all')
+  .description('Full refresh: build all domains, build catalog, build flows, build UI, regenerate hashes, run doctor')
+  .option('--project-root <path>', 'Root of the project (defaults to cwd)')
+  .action(async (opts: { projectRoot?: string }) => {
+    const result = await runUpdateAll({ projectRoot: opts.projectRoot });
+    process.exit(result.success ? 0 : 1);
+  });
+
+program
+  .command('regenerate-modules-hashes')
+  .description('Walk infra/modules/, compute SHA256 hashes, and write .mc/modules-hashes.json')
+  .option('--project-root <path>', 'Root of the project (defaults to cwd)')
+  .action(async (opts: { projectRoot?: string }) => {
+    await runRegenerateModulesHashes({ projectRoot: opts.projectRoot });
+  });
+
 program
   .command('upgrade-backend <target-major>')
   .description('Run jscodeshift/ts-morph migrations between major versions of domain-runtime')

package/src/commands/add-api.ts

@@ -96,7 +96,7 @@ export async function runAddApi(opts: AddApiOptions): Promise<void> {
     throw new Error(`Domain "${opts.domain}" not found at ${domainDir}`);
   }
 
-  const apiFilePath = join(domainDir, 'api', `${opts.id}.ts`);
+  const apiFilePath = join(domainDir, 'actions', `${opts.id}.ts`);
 
   // Refuse if API already exists
   try {
@@ -124,7 +124,7 @@ export async function runAddApi(opts: AddApiOptions): Promise<void> {
   await writeFile(apiFilePath, apiContent);
 
   // Create fixture with the input schema's default shape as the example payload
-  const apiTestDir = join(domainDir, 'api', '__tests__');
+  const apiTestDir = join(domainDir, 'actions', '__tests__');
   await mkdir(apiTestDir, { recursive: true });
   await writeFile(
     join(apiTestDir, `${opts.id}.fixture.json`),

package/src/commands/add-domain.ts

@@ -51,18 +51,18 @@ export async function runAddDomain(opts: AddDomainOptions): Promise<void> {
   }
 
   // Create directory structure
-  await mkdir(join(domainDir, 'api', '__tests__'), { recursive: true });
+  await mkdir(join(domainDir, 'actions', '__tests__'), { recursive: true });
   await mkdir(join(domainDir, 'subscribers'), { recursive: true });
   await mkdir(join(domainDir, 'publishes'), { recursive: true });
 
   // Write skeleton files
   await writeFile(join(domainDir, 'domain.config.ts'), domainConfigTemplate(opts.id, opts.tenancy));
   await writeFile(
-    join(domainDir, 'api', 'example.ts'),
+    join(domainDir, 'actions', 'example.ts'),
     apiSkeletonTemplate(opts.id, 'example', opts.tenancy)
   );
   await writeFile(
-    join(domainDir, 'api', '__tests__', 'example.fixture.json'),
+    join(domainDir, 'actions', '__tests__', 'example.fixture.json'),
     apiFixtureSkeleton(opts.id, 'example')
   );
   await writeFile(join(domainDir, 'publishes', 'events.ts'), eventsSkeletonTemplate(opts.id));
@@ -94,7 +94,7 @@ export async function runAddDomain(opts: AddDomainOptions): Promise<void> {
   cliLogger.info({ id: opts.id, dir: domainDir }, 'Domain scaffolded');
   // eslint-disable-next-line no-console
   console.log(
-    `\n✓ Domain "${opts.id}" added at ${domainDir}\nNext: edit api/example.ts, ` +
+    `\n✓ Domain "${opts.id}" added at ${domainDir}\nNext: edit actions/example.ts, ` +
       `then run \`mc-domain-module build ${opts.id}\` to generate the registry.`
   );
 }

package/src/commands/add-fixture-factory.ts

@@ -47,21 +47,20 @@ export async function runAddFixtureFactory(options: AddFixtureFactoryOptions): P
   const domain = options.domain;
   const apiId = options.apiId;
 
-  const apiFile = join(projectRoot, 'domains', domain, 'api', `${apiId}.ts`);
+  const apiFile = join(projectRoot, 'domains', domain, 'actions', `${apiId}.ts`);
   await access(apiFile).catch(() => {
-    throw new Error(`API file not found: ${apiFile}. Run add-api first.`);
+    throw new Error(`Action file not found: ${apiFile}. Run add-api first.`);
   });
 
-  // Read the API file to extract the input type name
+  // Read the action file to extract the input type name
   const content = await readFile(apiFile, 'utf8');
-  const outputTypeArg = content.match(/import\s+\{\s*[\w\s,]*\s*\}\s+from\s+['"]@mettlecast/);
 
-  const factoryFile = join(projectRoot, 'domains', domain, 'api', '__tests__', `${apiId}.factory.ts`);
+  const factoryFile = join(projectRoot, 'domains', domain, 'actions', '__tests__', `${apiId}.factory.ts`);
   const factoryContent = FACTORY_TEMPLATE
     .replace(/\{domain\}/g, domain)
     .replace(/\{apiId\}/g, apiId);
 
-  await mkdir(join(projectRoot, 'domains', domain, 'api', '__tests__'), { recursive: true });
+  await mkdir(join(projectRoot, 'domains', domain, 'actions', '__tests__'), { recursive: true });
   await writeFile(factoryFile, factoryContent, 'utf8');
 
   cliLogger.info({ factoryFile }, 'add-fixture-factory: factory written');

package/src/commands/build-catalog.ts

@@ -2,27 +2,18 @@ import { readFile, writeFile, readdir, mkdir } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { cliLogger } from '../utils/logger.js';
 
-/** A single API entry in the catalog. */
-export interface CatalogApi {
-  id: string;
-  domainId: string;
-  path: string;
-  method: string;
-  authType: string;
-  description?: string;
-  requestSchema?: Record<string, unknown>;
-  responseSchema?: Record<string, unknown>;
-  versions?: Array<{ version: string; requestSchema?: Record<string, unknown>; responseSchema?: Record<string, unknown> }>;
-  examples?: { request?: Record<string, unknown>; response?: Record<string, unknown> };
-}
-
 /** A single action entry in the catalog. */
 export interface CatalogAction {
   id: string;
   domainId: string;
-  visibility: string;
+  backendAccess: string;
+  exposure: Record<string, unknown>;
+  exposureDeclared?: boolean;
   idempotent: boolean;
   description?: string;
+  handlerFile?: string;
+  deployment?: Record<string, unknown>;
+  outboundAccess?: string;
   inputSchema?: Record<string, unknown>;
   outputSchema?: Record<string, unknown>;
 }
@@ -83,7 +74,6 @@ export interface DomainCatalog {
   version: 2;
   generatedAt: string;
   domains: CatalogDomain[];
-  apis: CatalogApi[];
   actions: CatalogAction[];
   events: CatalogEvent[];
   subscribers: CatalogSubscriber[];
@@ -118,7 +108,6 @@ export async function runBuildCatalog(registryDir?: string): Promise<DomainCatal
     version: 2,
     generatedAt: new Date().toISOString(),
     domains: [],
-    apis: [],
     actions: [],
     events: [],
     subscribers: [],
@@ -152,30 +141,19 @@ export async function runBuildCatalog(registryDir?: string): Promise<DomainCatal
       description: domainEntry['description'] as string | undefined,
     });
 
-    const apis = (registry['apis'] as Record<string, unknown>[] | undefined) ?? [];
-    for (const api of apis) {
-      catalog.apis.push({
-        id: String(api['id']),
-        domainId,
-        path: String(api['path']),
-        method: String(api['method'] ?? 'ANY'),
-        authType: String(api['authType'] ?? 'jwt'),
-        description: api['description'] as string | undefined,
-        requestSchema: api['requestSchema'] as Record<string, unknown> | undefined,
-        responseSchema: api['responseSchema'] as Record<string, unknown> | undefined,
-        versions: api['versions'] as CatalogApi['versions'],
-        examples: api['examples'] as CatalogApi['examples'],
-      });
-    }
-
     const actions = (registry['actions'] as Record<string, unknown>[] | undefined) ?? [];
     for (const action of actions) {
       catalog.actions.push({
         id: String(action['id']),
         domainId,
-        visibility: String(action['visibility'] ?? 'private'),
+        backendAccess: String(action['backendAccess'] ?? 'private'),
+        exposure: (action['exposure'] as Record<string, unknown> | undefined) ?? { type: 'internal' },
+        exposureDeclared: action['exposureDeclared'] as boolean | undefined,
         idempotent: Boolean(action['idempotent'] ?? false),
         description: action['description'] as string | undefined,
+        handlerFile: action['handlerFile'] as string | undefined,
+        deployment: action['deployment'] as Record<string, unknown> | undefined,
+        outboundAccess: action['outboundAccess'] as string | undefined,
         inputSchema: action['inputSchema'] as Record<string, unknown> | undefined,
         outputSchema: action['outputSchema'] as Record<string, unknown> | undefined,
       });
@@ -241,7 +219,7 @@ export async function runBuildCatalog(registryDir?: string): Promise<DomainCatal
   await writeFile(outPath, JSON.stringify(catalog), 'utf8');
 
   cliLogger.info(
-    { outPath, domains: catalog.domains.length, apis: catalog.apis.length, actions: catalog.actions.length, events: catalog.events.length, jobs: catalog.jobs.length, schedules: catalog.schedules.length, integrations: catalog.integrations.length },
+    { outPath, domains: catalog.domains.length, actions: catalog.actions.length, events: catalog.events.length, jobs: catalog.jobs.length, schedules: catalog.schedules.length, integrations: catalog.integrations.length },
     'Domain catalog written'
   );
 

package/src/commands/build.ts

@@ -1,6 +1,6 @@
 import { writeFile, mkdir, readdir, readFile } from 'node:fs/promises';
 import { join, resolve, basename } from 'node:path';
-import type { DomainRegistry } from '@mettlecast/domain-cdk-packer';
+import type { DomainRegistry } from '../types.js';
 import { buildRegistry } from '../builder/build-registry.js';
 import { buildActionsTypes } from '../builder/build-types.js';
 import { cliLogger } from '../utils/logger.js';
@@ -40,7 +40,8 @@ export async function runBuild(options: BuildOptions): Promise<string> {
   await mkdir(join(outFile, '..'), { recursive: true });
   await writeFile(outFile, JSON.stringify(registry), 'utf8');
 
-  cliLogger.info({ outFile, apis: registry.apis.length, events: registry.events.length }, 'Registry written');
+  const apiExposedActions = registry.actions.filter(action => action.exposure.type === 'api').length;
+  cliLogger.info({ outFile, apiExposedActions, events: registry.events.length }, 'Registry written');
 
   // Discover all sibling registries and emit aggregated types
   const registryDir = join(outFile, '..');

package/src/commands/check-hashes.ts

@@ -9,6 +9,8 @@ import { cliLogger } from '../utils/logger.js';
 export interface CheckHashesOptions {
   /** Root directory of the project (defaults to cwd). */
   projectRoot?: string;
+  /** If true, regenerate .mc/modules-hashes.json from current infra/modules/ before checking. */
+  write?: boolean;
 }
 
 /**
@@ -57,6 +59,16 @@ interface ModulesHashesManifest {
  */
 export async function runCheckHashes(opts: CheckHashesOptions = {}): Promise<CheckHashesResult> {
   const root = opts.projectRoot ?? process.cwd();
+
+  // --write bootstraps the manifest from current infra/modules/ before verification.
+  // Must run before the manifest read below so it can create a missing manifest.
+  if (opts.write) {
+    const { runRegenerateModulesHashes } = await import('./regenerate-modules-hashes.js');
+    const outPath = await runRegenerateModulesHashes({ projectRoot: root });
+    cliLogger.info({ outPath }, 'modules-hashes.json regenerated');
+    return { ok: true, drifted: [], missing: [], unexpected: [] };
+  }
+
   const manifestPath = join(root, '.mc', 'modules-hashes.json');
   const modulesDir = join(root, 'infra', 'modules');
 

package/src/commands/dev.ts

@@ -55,7 +55,7 @@ export async function startDev(options: DevOptions): Promise<DevHandle> {
   }
 
   cliLogger.info(
-    { domain: registry.domain.id, apis: registry.apis.length, port },
+    { domain: registry.domain.id, apiActions: registry.actions.filter(a => a.exposure?.type === 'api').length, port },
     'Starting local dev server'
   );
 

package/src/commands/doctor.ts

@@ -121,8 +121,10 @@ async function checkHandlersUseResult(projectRoot: string): Promise<DoctorCheck>
     const missing: string[] = [];
     for (const file of apiFiles) {
       const content = await readFile(file, 'utf8');
-      // A file contains a handler export — check the return type
-      if (/defineApi\s*\(/.test(content)) {
+      // A file contains a handler export — check the return type.
+      // Issue #4689: defineApi was removed. The action-first
+      // contract uses defineAction with exposure.type='api'.
+      if (/defineAction\s*\(/.test(content)) {
         // Look for Result<T> in the handler's return type annotation
         if (!/: .*Result</.test(content)) {
           missing.push(relative(projectRoot, file));
@@ -448,49 +450,64 @@ async function checkNoCrossDomainImports(projectRoot: string): Promise<DoctorChe
 async function checkApisHaveVersions(projectRoot: string): Promise<DoctorCheck> {
   try {
     const domainsDir = join(projectRoot, 'domains');
-    const allApiFiles: string[] = [];
+    const allActionFiles: string[] = [];
 
-    // Find all API files in all domains
+    // Find API-exposed action files in both actions/ and api/ directories.
+    // Issue #4689: defineApi was removed. API-exposed actions live in
+    // domains/*/actions/ but legacy api/ directories may still exist.
     const entries = await readdir(domainsDir, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
-      const apiDir = join(domainsDir, entry.name, 'api');
-      const apiFiles = findFiles(apiDir, /\.ts$/);
-      allApiFiles.push(...apiFiles);
+      for (const dir of ['actions', 'api']) {
+        const actionDir = join(domainsDir, entry.name, dir);
+        const files = findFiles(actionDir, /\.ts$/);
+        allActionFiles.push(...files);
+      }
     }
-    const apiFiles = allApiFiles;
 
-    if (apiFiles.length === 0) {
+    // Only consider files that define an API-exposed action (defineAction
+    // with exposure.type === 'api' or exposure: { type: 'api' }).
+    const apiExposedFiles: string[] = [];
+    for (const file of allActionFiles) {
+      const content = await readFile(file, 'utf8');
+      if (/defineAction\s*\(/.test(content) && /exposure\s*:\s*\{\s*type\s*:\s*['"]api['"]/.test(content)) {
+        apiExposedFiles.push(file);
+      }
+    }
+
+    if (apiExposedFiles.length === 0) {
       return {
         name: 'APIs declare versions',
         status: 'PASS',
-        message: 'No APIs found (optional)',
+        message: 'No API-exposed actions found (optional)',
         kNodeRef: 'K:runbook:add-domain',
       };
     }
 
-    // Simple heuristic: grep for 'versions:' in each API file
-    let missingVersions = 0;
-    for (const file of apiFiles) {
+    // Issue #4689: action-first contract requires input/output Zod schemas
+    // with `.default({...})` example data. Check that each API-exposed
+    // action file contains `.default(` (indicating example data).
+    let missingDefaults = 0;
+    for (const file of apiExposedFiles) {
       const content = await readFile(file, 'utf8');
-      if (!content.includes('versions:')) {
-        missingVersions++;
+      if (!content.includes('.default(')) {
+        missingDefaults++;
       }
     }
 
-    if (missingVersions === 0) {
+    if (missingDefaults === 0) {
       return {
         name: 'APIs declare versions',
         status: 'PASS',
-        message: `All ${apiFiles.length} API files declare versions`,
+        message: `All ${apiExposedFiles.length} API-exposed action(s) have .default() example data`,
         kNodeRef: 'K:runbook:add-domain',
       };
     } else {
       return {
         name: 'APIs declare versions',
         status: 'FAIL',
-        message: `${missingVersions}/${apiFiles.length} API files missing versions: field`,
-        fixHint: 'Add versions: { v1: { ... } } to defineApi calls',
+        message: `${missingDefaults}/${apiExposedFiles.length} API-exposed action(s) missing .default() example data. Add \`.default({...})\` to the top-level input and output Zod schemas in each defineAction({ exposure: { type: 'api', ... } }) call.`,
+        fixHint: "Add `input` and `output` Zod schemas with `.default({...})` to defineAction({ exposure: { type: 'api', ... } }) calls",
         kNodeRef: 'K:runbook:add-domain',
       };
     }
@@ -498,7 +515,7 @@ async function checkApisHaveVersions(projectRoot: string): Promise<DoctorCheck>
     return {
       name: 'APIs declare versions',
       status: 'WARN',
-      message: `Could not check API versions: ${String(err)}`,
+      message: `Could not check API schemas: ${String(err)}`,
       kNodeRef: 'K:runbook:add-domain',
     };
   }
@@ -507,30 +524,42 @@ async function checkApisHaveVersions(projectRoot: string): Promise<DoctorCheck>
 async function checkApisHaveTenancy(projectRoot: string): Promise<DoctorCheck> {
   try {
     const domainsDir = join(projectRoot, 'domains');
-    const allApiFiles: string[] = [];
+    const allActionFiles: string[] = [];
 
-    // Find all API files in all domains
+    // Find API-exposed action files in both actions/ and api/ directories.
+    // Issue #4689: defineApi was removed. Tenancy is now declared on the
+    // action's exposure block via `exposure.tenancy`.
     const entries = await readdir(domainsDir, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
-      const apiDir = join(domainsDir, entry.name, 'api');
-      const apiFiles = findFiles(apiDir, /\.ts$/);
-      allApiFiles.push(...apiFiles);
+      for (const dir of ['actions', 'api']) {
+        const actionDir = join(domainsDir, entry.name, dir);
+        const files = findFiles(actionDir, /\.ts$/);
+        allActionFiles.push(...files);
+      }
     }
-    const apiFiles = allApiFiles;
 
-    if (apiFiles.length === 0) {
+    // Only consider files that define an API-exposed action.
+    const apiExposedFiles: string[] = [];
+    for (const file of allActionFiles) {
+      const content = await readFile(file, 'utf8');
+      if (/defineAction\s*\(/.test(content) && /exposure\s*:\s*\{\s*type\s*:\s*['"]api['"]/.test(content)) {
+        apiExposedFiles.push(file);
+      }
+    }
+
+    if (apiExposedFiles.length === 0) {
       return {
         name: 'APIs declare tenancy',
         status: 'PASS',
-        message: 'No APIs found (optional)',
+        message: 'No API-exposed actions found (optional)',
         kNodeRef: 'K:convention:tier-1-foundations',
       };
     }
 
-    // Simple heuristic: grep for 'tenancy:' in each API file
+    // Check for `tenancy:` anywhere in each API-exposed action file.
     let missingTenancy = 0;
-    for (const file of apiFiles) {
+    for (const file of apiExposedFiles) {
       const content = await readFile(file, 'utf8');
       if (!content.includes('tenancy:')) {
         missingTenancy++;
@@ -541,15 +570,15 @@ async function checkApisHaveTenancy(projectRoot: string): Promise<DoctorCheck> {
       return {
         name: 'APIs declare tenancy',
         status: 'PASS',
-        message: `All ${apiFiles.length} API files declare tenancy`,
+        message: `All ${apiExposedFiles.length} API-exposed action(s) declare tenancy`,
         kNodeRef: 'K:convention:tier-1-foundations',
       };
     } else {
       return {
         name: 'APIs declare tenancy',
         status: 'FAIL',
-        message: `${missingTenancy}/${apiFiles.length} API files missing tenancy: field`,
-        fixHint: "Add tenancy: 'required' | 'none' | 'system' to defineApi calls",
+        message: `${missingTenancy}/${apiExposedFiles.length} API-exposed action(s) missing tenancy. Tenancy must be declared on the action's exposure block: \`exposure.tenancy: 'required' | 'none' | 'system'\`.`,
+        fixHint: "Add `exposure.tenancy: 'required' | 'none' | 'system'` to defineAction({ exposure: { type: 'api', ... } }) calls",
         kNodeRef: 'K:convention:tier-1-foundations',
       };
     }
@@ -584,9 +613,9 @@ async function checkScaffoldConfigMatchesDisk(projectRoot: string): Promise<Doct
     } catch {
       return {
         name: 'scaffold-config.json matches on-disk',
-        status: 'FAIL',
-        message: 'Could not read .mc/scaffold-config.json',
-        fixHint: 'Ensure .mc/scaffold-config.json exists and is valid JSON',
+        status: 'WARN',
+        message: '.mc/scaffold-config.json not found or unreadable — skipping domain list sync check (expected on fresh clones before first scaffold)',
+        fixHint: 'Run mc-domain-module update-all to regenerate scaffold metadata',
         kNodeRef: 'K:runbook:add-domain',
       };
     }
@@ -699,7 +728,7 @@ async function checkRootLevelFlows(projectRoot: string): Promise<DoctorCheck> {
     }
     return {
       name: 'No root-level flows (deprecated)',
-      status: 'WARN',
+      status: 'FAIL',
       message: `${flowFiles.length} flow(s) still in root-level flows/: ${flowFiles.join(', ')}`,
       fixHint: 'Move these flows to domains/{owningDomain}/flows/ and delete the root-level copies.',
       kNodeRef: 'K:convention:flow-vs-subscriber-rule',
@@ -873,7 +902,7 @@ async function checkAllRoutesUseTanStackRouter(projectRoot: string): Promise<Doc
 
 /**
  * Check W5-4: Lambda handler files contain initOtel() call.
- * Scans `domains/*\/api/*.ts` and FAILs if any handler is missing initOtel().
+  * Scans `domains/*\/actions/*.ts` and `domains/*\/api/*.ts` and FAILs if any handler is missing initOtel().
  */
 async function checkOtelInitInLambdas(projectRoot: string): Promise<DoctorCheck> {
   try {
@@ -890,9 +919,11 @@ async function checkOtelInitInLambdas(projectRoot: string): Promise<DoctorCheck>
     const handlerFiles: string[] = [];
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
-      const apiDir = join(domainsDir, entry.name, 'api');
-      const files = findFiles(apiDir, /\.ts$/);
-      handlerFiles.push(...files);
+      for (const dir of ['actions', 'api']) {
+        const handlerDir = join(domainsDir, entry.name, dir);
+        const files = findFiles(handlerDir, /\.ts$/);
+        handlerFiles.push(...files);
+      }
     }
 
     if (handlerFiles.length === 0) {