@topogram/cli 0.3.76 → 0.3.77

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topogram/cli",
-  "version": "0.3.76",
+  "version": "0.3.77",
   "description": "Topogram CLI for checking Topogram workspaces and generating app bundles.",
   "license": "Apache-2.0",
   "repository": {

package/src/adoption/plan/index.js

@@ -741,7 +741,18 @@ export function buildAgentAdoptionPlan(adoptionPlan, maintainedBoundaryArtifact
     mapping_suggestions: [{
       type: "manual_project_config_review",
       id: seam.id_hint || seam.seam_id,
-      reason: "Review the inferred database migration strategy before editing topogram.project.json."
+      reason: "Review the inferred database migration strategy before editing topogram.project.json.",
+      project_config_target: seam.project_config_target || {
+        file: "topogram.project.json",
+        path: "topology.runtimes[].migration"
+      },
+      proposed_runtime_migration: seam.proposed_runtime_migration || null,
+      missing_decisions: seam.missing_decisions || [],
+      evidence: seam.evidence || seam.provenance || [],
+      manual_next_steps: seam.manual_next_steps || [
+        "Review evidence and missing decisions.",
+        "Manually copy the accepted migration strategy into topogram.project.json."
+      ]
     }],
     available_actions: ADOPTION_STATE_VOCABULARY
   }));

package/src/cli/commands/import/workspace.js

@@ -115,6 +115,7 @@ export function importCandidateCounts(summary) {
     apiRoutes: candidates.api?.routes?.length || 0,
     uiScreens: candidates.ui?.screens?.length || 0,
     uiRoutes: candidates.ui?.routes?.length || 0,
+    uiFlows: candidates.ui?.flows?.length || 0,
     uiWidgets: candidates.ui?.widgets?.length || candidates.ui?.components?.length || 0,
     uiShapes: candidates.ui?.shapes?.length || 0,
     cliCommands: candidates.cli?.commands?.length || 0,

package/src/cli.js

@@ -63,18 +63,18 @@ const inputPath = commandArgs && Object.prototype.hasOwnProperty.call(commandArg
 const cliOptions = parseCliOptions(args, commandArgs);
 
 try {
-  process.exit(await runCliDispatch({
+  process.exitCode = await runCliDispatch({
     args,
     commandArgs,
     inputPath,
     cliOptions,
     executablePath: path.resolve(process.argv[1] || fileURLToPath(import.meta.url))
-  }));
+  });
 } catch (error) {
   if (error.validation) {
     console.error(formatValidationErrors(error.validation));
   } else {
     console.error(error.message);
   }
-  process.exit(1);
+  process.exitCode = 1;
 }

package/src/import/core/runner/candidates.js

@@ -284,6 +284,7 @@ export function normalizeCandidatesForTrack(track, candidates) {
       screens: dedupeCandidateRecords(candidates.screens || [], idHint),
       routes: dedupeCandidateRecords(candidates.routes || [], idHint),
       actions: dedupeCandidateRecords(candidates.actions || [], idHint),
+      flows: dedupeCandidateRecords(candidates.flows || [], idHint),
       widgets,
       shapes: dedupeCandidateRecords([...(candidates.shapes || []), ...eventShapes], idHint),
       stacks: [...new Set(candidates.stacks || [])].sort()
@@ -330,6 +331,7 @@ export function enrichUiWidgetDataSources(uiCandidates, allCandidates) {
   const { components, ...canonicalCandidates } = uiCandidates;
   return {
     ...canonicalCandidates,
+    flows: dedupeCandidateRecords(canonicalCandidates.flows || [], (/** @type {any} */ flow) => flow.id_hint),
     widgets: widgets.map((widget) => {
       const dataSource = inferredDataSourceForWidget(widget, allCandidates);
       const dataProp = widget.data_prop || "rows";

package/src/import/core/runner/reports.js

@@ -10,9 +10,12 @@ import { uiWidgetCandidates } from "./candidates.js";
  */
 export function reportMarkdown(track, candidates) {
   if (track === "db") {
-    const seamLines = (candidates.maintained_seams || []).map((/** @type {any} */ seam) =>
-      `- \`${seam.id_hint}\` tool \`${seam.tool}\` confidence ${seam.confidence || "unknown"} schema \`${seam.schemaPath || "none"}\` migrations \`${seam.migrationsPath || "review-required"}\` missing decisions ${(seam.missing_decisions || []).length}`
-    );
+    const seamLines = (candidates.maintained_seams || []).flatMap((/** @type {any} */ seam) => [
+      `- \`${seam.id_hint}\` tool \`${seam.tool}\` confidence ${seam.confidence || "unknown"} schema \`${seam.schemaPath || "none"}\` migrations \`${seam.migrationsPath || "review-required"}\` missing decisions ${(seam.missing_decisions || []).length}`,
+      `  - project config target: \`${seam.project_config_target?.path || "topology.runtimes[].migration"}\``,
+      `  - evidence: ${(seam.evidence || []).slice(0, 3).map((/** @type {string} */ item) => `\`${item}\``).join(", ") || "_none_"}`,
+      `  - manual next: ${(seam.manual_next_steps || []).slice(0, 2).join(" ")}`
+    ]);
     return ensureTrailingNewline(
       `# DB Import Report\n\n- Entities: ${candidates.entities.length}\n- Enums: ${candidates.enums.length}\n- Relations: ${candidates.relations.length}\n- Indexes: ${candidates.indexes.length}\n- Maintained DB migration seams: ${(candidates.maintained_seams || []).length}\n\n## Maintained DB Migration Seam Candidates\n\n${seamLines.length ? seamLines.join("\n") : "- none"}\n`
     );
@@ -25,11 +28,15 @@ export function reportMarkdown(track, candidates) {
   if (track === "ui") {
     const widgets = uiWidgetCandidates(candidates);
     const shapes = candidates.shapes || [];
+    const flows = candidates.flows || [];
     const widgetLines = widgets.map((widget) =>
       `- \`${widget.id_hint}\` confidence ${widget.confidence || "unknown"} pattern \`${widget.pattern || widget.inferred_pattern || "unknown"}\` region \`${widget.region || widget.inferred_region || "unknown"}\` events ${(widget.inferred_events || []).length} evidence ${(widget.evidence || widget.provenance || []).length} missing decisions ${(widget.missing_decisions || []).length}`
     );
+    const flowLines = flows.map((/** @type {any} */ flow) =>
+      `- \`${flow.id_hint}\` type \`${flow.flow_type}\` confidence ${flow.confidence || "unknown"} routes ${(flow.route_paths || []).map((/** @type {string} */ route) => `\`${route}\``).join(", ") || "_none_"} missing decisions ${(flow.missing_decisions || []).length}`
+    );
     return ensureTrailingNewline(
-      `# UI Import Report\n\n- Screens: ${candidates.screens.length}\n- Routes: ${candidates.routes.length}\n- Actions: ${candidates.actions.length}\n- Widgets: ${widgets.length}\n- Event payload shapes: ${shapes.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n\n## Widget Candidates\n\n${widgetLines.length ? widgetLines.join("\n") : "- none"}\n\n## Next Validation\n\n- Review candidates under \`topo/candidates/app/ui/drafts/widgets/**\`.\n- Run \`topogram import plan <path>\` before adoption.\n- After adoption, run \`topogram check <path>\`, \`topogram widget check <path>\`, and \`topogram widget behavior <path>\`.\n`
+      `# UI Import Report\n\n- Screens: ${candidates.screens.length}\n- Routes: ${candidates.routes.length}\n- Actions: ${candidates.actions.length}\n- Flow candidates: ${flows.length}\n- Widgets: ${widgets.length}\n- Event payload shapes: ${shapes.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n\n## Flow Candidates\n\n${flowLines.length ? flowLines.join("\n") : "- none"}\n\n## Widget Candidates\n\n${widgetLines.length ? widgetLines.join("\n") : "- none"}\n\n## Next Validation\n\n- Review flow candidates in \`topo/candidates/app/ui/candidates.json\` before adding shared UI contract behavior.\n- Review candidates under \`topo/candidates/app/ui/drafts/widgets/**\`.\n- Run \`topogram import plan <path>\` before adoption.\n- After adoption, run \`topogram check <path>\`, \`topogram widget check <path>\`, and \`topogram widget behavior <path>\`.\n`
     );
   }
   if (track === "cli") {
@@ -57,6 +64,6 @@ export function reportMarkdown(track, candidates) {
  */
 export function appReportMarkdown(candidates, tracks) {
   return ensureTrailingNewline(
-    `# App Import Report\n\nTracks: ${tracks.join(", ")}\n\n## DB\n\n- Entities: ${candidates.db?.entities?.length || 0}\n- Enums: ${candidates.db?.enums?.length || 0}\n- Relations: ${candidates.db?.relations?.length || 0}\n- Maintained DB migration seams: ${candidates.db?.maintained_seams?.length || 0}\n\n## API\n\n- Capabilities: ${candidates.api?.capabilities?.length || 0}\n- Routes: ${candidates.api?.routes?.length || 0}\n- Stacks: ${candidates.api?.stacks?.length ? candidates.api.stacks.join(", ") : "none"}\n\n## UI\n\n- Screens: ${candidates.ui?.screens?.length || 0}\n- Routes: ${candidates.ui?.routes?.length || 0}\n- Actions: ${candidates.ui?.actions?.length || 0}\n- Widgets: ${uiWidgetCandidates(candidates.ui).length}\n- Event payload shapes: ${candidates.ui?.shapes?.length || 0}\n- Stacks: ${candidates.ui?.stacks?.length ? candidates.ui.stacks.join(", ") : "none"}\n\n## CLI\n\n- Commands: ${candidates.cli?.commands?.length || 0}\n- Capabilities: ${candidates.cli?.capabilities?.length || 0}\n- CLI surfaces: ${candidates.cli?.surfaces?.length || 0}\n\n## Workflows\n\n- Workflows: ${candidates.workflows?.workflows?.length || 0}\n- States: ${candidates.workflows?.workflow_states?.length || 0}\n- Transitions: ${candidates.workflows?.workflow_transitions?.length || 0}\n\n## Verification\n\n- Verifications: ${candidates.verification?.verifications?.length || 0}\n- Scenarios: ${candidates.verification?.scenarios?.length || 0}\n- Frameworks: ${candidates.verification?.frameworks?.length ? candidates.verification.frameworks.join(", ") : "none"}\n- Scripts: ${candidates.verification?.scripts?.length || 0}\n`
+    `# App Import Report\n\nTracks: ${tracks.join(", ")}\n\n## DB\n\n- Entities: ${candidates.db?.entities?.length || 0}\n- Enums: ${candidates.db?.enums?.length || 0}\n- Relations: ${candidates.db?.relations?.length || 0}\n- Maintained DB migration seams: ${candidates.db?.maintained_seams?.length || 0}\n\n## API\n\n- Capabilities: ${candidates.api?.capabilities?.length || 0}\n- Routes: ${candidates.api?.routes?.length || 0}\n- Stacks: ${candidates.api?.stacks?.length ? candidates.api.stacks.join(", ") : "none"}\n\n## UI\n\n- Screens: ${candidates.ui?.screens?.length || 0}\n- Routes: ${candidates.ui?.routes?.length || 0}\n- Actions: ${candidates.ui?.actions?.length || 0}\n- Flow candidates: ${candidates.ui?.flows?.length || 0}\n- Widgets: ${uiWidgetCandidates(candidates.ui).length}\n- Event payload shapes: ${candidates.ui?.shapes?.length || 0}\n- Stacks: ${candidates.ui?.stacks?.length ? candidates.ui.stacks.join(", ") : "none"}\n\n## CLI\n\n- Commands: ${candidates.cli?.commands?.length || 0}\n- Capabilities: ${candidates.cli?.capabilities?.length || 0}\n- CLI surfaces: ${candidates.cli?.surfaces?.length || 0}\n\n## Workflows\n\n- Workflows: ${candidates.workflows?.workflows?.length || 0}\n- States: ${candidates.workflows?.workflow_states?.length || 0}\n- Transitions: ${candidates.workflows?.workflow_transitions?.length || 0}\n\n## Verification\n\n- Verifications: ${candidates.verification?.verifications?.length || 0}\n- Scenarios: ${candidates.verification?.scenarios?.length || 0}\n- Frameworks: ${candidates.verification?.frameworks?.length ? candidates.verification.frameworks.join(", ") : "none"}\n- Scripts: ${candidates.verification?.scripts?.length || 0}\n`
   );
 }

package/src/import/core/runner/tracks.js

@@ -102,7 +102,7 @@ function initialCandidatesForTrack(track) {
     return { capabilities: [], routes: [], stacks: [] };
   }
   if (track === "ui") {
-    return { screens: [], routes: [], actions: [], stacks: [] };
+    return { screens: [], routes: [], actions: [], flows: [], stacks: [] };
   }
   if (track === "cli") {
     return { commands: [], capabilities: [], surfaces: [] };

package/src/import/core/shared/files.js

@@ -6,12 +6,17 @@ import { relativeTo } from "../../../path-helpers.js";
 export const DEFAULT_IGNORED_DIRS = new Set([
   ".git",
   ".next",
+  ".tmp",
   ".turbo",
   ".yarn",
+  ".cache",
+  ".parcel-cache",
+  ".svelte-kit",
   "build",
   "coverage",
   "dist",
   "node_modules",
+  "out",
   "tmp"
 ]);
 
@@ -82,6 +87,54 @@ export function normalizeImportRelativePath(paths, filePath) {
   return relativeTo(paths.repoRoot, filePath);
 }
 
+/**
+ * @param {import("./types.d.ts").ImportPaths} paths
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function importSourcePathRelativeToWorkspace(paths, filePath) {
+  return relativeTo(paths.workspaceRoot, filePath).replaceAll(path.sep, "/");
+}
+
+/**
+ * @param {import("./types.d.ts").ImportPaths} paths
+ * @param {string} filePath
+ * @returns {"runtime_source"|"parser_config"|"docs"|"tests"|"fixtures"|"generated_output"}
+ */
+export function classifyImportSourcePath(paths, filePath) {
+  const relativePath = importSourcePathRelativeToWorkspace(paths, filePath);
+  const basename = path.basename(relativePath).toLowerCase();
+  if (/(^|\/)(\.tmp|tmp|temp|dist|build|coverage|out|generated|docs-generated|snapshots?)(\/|$)/i.test(relativePath)) {
+    return "generated_output";
+  }
+  if (/(^|\/)[^/]*templates?[^/]*(\/|$)/i.test(relativePath)) {
+    return "fixtures";
+  }
+  if (/(^|\/)(test|tests|__tests__|spec|specs|mocks?)(\/|$)|\.(test|spec)\.(js|jsx|ts|tsx|mjs|cjs)$/i.test(relativePath)) {
+    return "tests";
+  }
+  if (/(^|\/)(fixture|fixtures|examples?)(\/|$)/i.test(relativePath)) {
+    return "fixtures";
+  }
+  if (/(^|\/)(doc|docs|documentation|guides?)(\/|$)|^(readme|changelog|contributing|license)(\.[a-z0-9]+)?$/i.test(relativePath) || /^(readme|changelog|contributing|license)(\.[a-z0-9]+)?$/i.test(basename)) {
+    return "docs";
+  }
+  if (/(^|\/)(package\.json|openapi\.(json|ya?ml)|swagger\.(json|ya?ml)|drizzle\.config\.(ts|js|mjs|cjs)|tsconfig\.json)$/i.test(relativePath)) {
+    return "parser_config";
+  }
+  return "runtime_source";
+}
+
+/**
+ * @param {import("./types.d.ts").ImportPaths} paths
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isPrimaryImportSource(paths, filePath) {
+  const sourceType = classifyImportSourcePath(paths, filePath);
+  return sourceType === "runtime_source" || sourceType === "parser_config";
+}
+
 /**
  * @param {import("./types.d.ts").ImportPaths} paths
  * @param {string} filePath
@@ -130,6 +183,9 @@ export function canonicalSourceRank(paths, filePath, kind) {
       rank += penalty.weight;
     }
   }
+  if (!isPrimaryImportSource(paths, filePath)) {
+    rank += 1000;
+  }
   return rank;
 }
 

package/src/import/core/shared/next-app.js

@@ -10,7 +10,7 @@ import {
   normalizeEndpointPathForMatch,
   normalizeOpenApiPath
 } from "./api-routes.js";
-import { entityIdForRoute, screenIdForRoute, screenKindForRoute, uiCapabilityHintsForRoute } from "./ui-routes.js";
+import { entityIdForRoute, inferNonResourceUiFlow, screenIdForRoute, screenKindForRoute, uiCapabilityHintsForRoute } from "./ui-routes.js";
 
 /**
  * @param {string} rootDir
@@ -48,7 +48,7 @@ export function inferNextAppRoutes(rootDir) {
  */
 export function nextScreenKindForRoute(routePath) {
   const normalized = String(routePath || "");
-  if (/\/(login|register|setup)$/.test(normalized)) return "flow";
+  if (inferNonResourceUiFlow(normalized) || /\/(login|register|setup)$/.test(normalized)) return "flow";
   return screenKindForRoute(routePath);
 }
 

package/src/import/core/shared/ui-routes.js

@@ -5,6 +5,51 @@ import { relativeTo } from "../../../path-helpers.js";
 import { canonicalCandidateTerm } from "./candidates.js";
 import { listFilesRecursive, readTextIfExists } from "./files.js";
 
+const NON_RESOURCE_FLOW_DEFINITIONS = [
+  {
+    flow_type: "auth",
+    concept_id: "flow_auth",
+    pattern: /\/(login|log-in|signin|sign-in|sign_in|logout|log-out|register|signup|sign-up|forgot-password|reset-password|password-reset)(\/|$)/i,
+    confidence: "medium",
+    missing_decisions: ["confirm auth provider and session lifecycle", "confirm success and failure destinations"]
+  },
+  {
+    flow_type: "onboarding_wizard",
+    concept_id: "flow_onboarding",
+    pattern: /\/(onboarding|setup|welcome|get-started|getting-started|wizard|stepper)(\/|$)/i,
+    confidence: "medium",
+    missing_decisions: ["confirm step order and completion criteria", "confirm resumability and exit behavior"]
+  },
+  {
+    flow_type: "settings_preferences",
+    concept_id: "flow_settings",
+    pattern: /\/(settings|preferences|profile|account|billing|security)(\/|$)/i,
+    confidence: "medium",
+    missing_decisions: ["confirm settings ownership boundary", "confirm save, validation, and permission behavior"]
+  },
+  {
+    flow_type: "dashboard_reporting",
+    concept_id: "flow_dashboard",
+    pattern: /\/(dashboard|reports|reporting|analytics|insights|metrics)(\/|$)/i,
+    confidence: "medium",
+    missing_decisions: ["confirm reporting data sources", "confirm refresh cadence and empty states"]
+  },
+  {
+    flow_type: "search_filter",
+    concept_id: "flow_search",
+    pattern: /\/(search|results|explore|browse|discover)(\/|$)/i,
+    confidence: "medium",
+    missing_decisions: ["confirm searchable resources", "confirm filter, sorting, and pagination behavior"]
+  },
+  {
+    flow_type: "bulk_review",
+    concept_id: "flow_bulk_review",
+    pattern: /\/(review|reviews|approvals|approval|moderation|queue|bulk)(\/|$)/i,
+    confidence: "medium",
+    missing_decisions: ["confirm bulk action eligibility", "confirm review outcomes and audit requirements"]
+  }
+];
+
 /**
  * @param {string} routePath
  * @returns {any}
@@ -23,12 +68,72 @@ export function routeSegments(routePath) {
 export function screenKindForRoute(routePath) {
   const normalized = String(routePath || "");
   const segments = routeSegments(normalized);
+  if (inferNonResourceUiFlow(normalized)) return "flow";
   if (/\/new$/.test(normalized)) return "form";
   if (/\/:?[A-Za-z0-9_]+\/edit$/.test(normalized)) return "form";
   if (segments.length >= 2 && !/\/new$/.test(normalized) && !/\/edit$/.test(normalized)) return "detail";
   return "list";
 }
 
+/**
+ * @param {string} routePath
+ * @returns {any}
+ */
+export function inferNonResourceUiFlow(routePath) {
+  const normalized = String(routePath || "");
+  for (const definition of NON_RESOURCE_FLOW_DEFINITIONS) {
+    if (definition.pattern.test(normalized)) {
+      return {
+        flow_type: definition.flow_type,
+        concept_id: definition.concept_id,
+        confidence: definition.confidence,
+        missing_decisions: definition.missing_decisions
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} routePath
+ * @param {string} screenId
+ * @returns {any}
+ */
+export function uiFlowIdForRoute(routePath, screenId) {
+  const flow = inferNonResourceUiFlow(routePath);
+  if (!flow) return null;
+  return `flow_${canonicalCandidateTerm(screenId || flow.flow_type).replace(/-/g, "_")}`;
+}
+
+/**
+ * @param {string} routePath
+ * @param {string} screenId
+ * @param {string} screenKind
+ * @returns {any}
+ */
+export function proposedUiContractAdditionsForFlow(routePath, screenId, screenKind) {
+  return {
+    projection_type: "ui_contract",
+    screens: [
+      {
+        id: screenId,
+        kind: screenKind || "flow",
+        title: screenId
+      }
+    ],
+    screen_routes: [
+      {
+        screen: screenId,
+        path: routePath
+      }
+    ],
+    notes: [
+      "Review-only flow recovery proposal.",
+      "Promote into the shared UI contract only after confirming behavior, state, and ownership decisions."
+    ]
+  };
+}
+
 /**
  * @param {string} routePath
  * @returns {any}
@@ -37,6 +142,7 @@ export function screenIdForRoute(routePath) {
   const segments = routeSegments(routePath);
   const resource = canonicalCandidateTerm(segments[0] || "home");
   const kind = screenKindForRoute(routePath);
+  if (kind === "flow") return canonicalCandidateTerm(segments.join("_") || "home").replace(/-/g, "_");
   if (kind === "form" && /\/new$/.test(routePath)) return `${resource}_create`;
   if (kind === "form" && /\/edit$/.test(routePath)) return `${resource}_edit`;
   if (kind === "detail") return `${resource}_detail`;

package/src/import/core/shared.js

@@ -19,6 +19,9 @@ export {
   listFilesRecursive,
   importSearchRoots,
   normalizeImportRelativePath,
+  importSourcePathRelativeToWorkspace,
+  classifyImportSourcePath,
+  isPrimaryImportSource,
   canonicalSourceRank,
   selectPreferredImportFiles,
   findImportFiles
@@ -38,6 +41,9 @@ export {
   screenIdForRoute,
   uiCapabilityHintsForRoute,
   entityIdForRoute,
+  inferNonResourceUiFlow,
+  uiFlowIdForRoute,
+  proposedUiContractAdditionsForFlow,
   inferReactRoutes,
   inferSvelteRoutes,
   inferNavigationStructure,

package/src/import/extractors/api/generic-route-fallback.js

@@ -1,4 +1,4 @@
-import { findImportFiles, inferRouteAuthHint, inferRouteCapabilityId, inferRouteQueryParams, makeCandidateRecord, normalizeOpenApiPath, relativeTo } from "../../core/shared.js";
+import { findImportFiles, inferRouteAuthHint, inferRouteCapabilityId, inferRouteQueryParams, isPrimaryImportSource, makeCandidateRecord, normalizeOpenApiPath, relativeTo } from "../../core/shared.js";
 
 function extractHandlerContext(text, handlerName) {
   if (!handlerName) return "";
@@ -19,6 +19,7 @@ function inferServerRoutes(context) {
     context.paths,
     (filePath) =>
       /\.(ts|tsx|js|jsx|mjs|cjs)$/.test(filePath) &&
+      isPrimaryImportSource(context.paths, filePath) &&
       /(server|api|routes|src)/i.test(filePath)
   );
   for (const filePath of routeFiles) {

package/src/import/extractors/api/openapi.js

@@ -1,4 +1,4 @@
-import { findImportFiles, makeCandidateRecord, normalizeOpenApiPath, relativeTo, selectPreferredImportFiles, slugify, titleCase } from "../../core/shared.js";
+import { findImportFiles, isPrimaryImportSource, makeCandidateRecord, normalizeOpenApiPath, relativeTo, selectPreferredImportFiles, slugify, titleCase } from "../../core/shared.js";
 
 function openApiRefName(ref) {
   return typeof ref === "string" ? ref.split("/").pop() || null : null;
@@ -196,7 +196,7 @@ export const openApiExtractor = {
   detect(context) {
     const files = selectPreferredImportFiles(
       context.paths,
-      findImportFiles(context.paths, (filePath) => /(openapi|swagger)\.(json|ya?ml)$/i.test(filePath)),
+      findImportFiles(context.paths, (filePath) => /(openapi|swagger)\.(json|ya?ml)$/i.test(filePath) && isPrimaryImportSource(context.paths, filePath)),
       "openapi"
     );
     return {
@@ -207,7 +207,7 @@ export const openApiExtractor = {
   extract(context) {
     const openApiFiles = selectPreferredImportFiles(
       context.paths,
-      findImportFiles(context.paths, (filePath) => /(openapi|swagger)\.(json|ya?ml)$/i.test(filePath)),
+      findImportFiles(context.paths, (filePath) => /(openapi|swagger)\.(json|ya?ml)$/i.test(filePath) && isPrimaryImportSource(context.paths, filePath)),
       "openapi"
     );
     const findings = [];

package/src/import/extractors/cli/generic.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import {
   findImportFiles,
   idHintify,
+  isPrimaryImportSource,
   makeCandidateRecord,
   normalizeImportRelativePath,
   readJsonIfExists,
@@ -33,7 +34,7 @@ function normalizePath(value) {
  */
 function isAuthoritativeCliSource(paths, filePath) {
   const normalized = normalizePath(normalizeImportRelativePath(paths, filePath));
-  return !NON_AUTHORITATIVE_CLI_PATH_PATTERN.test(normalized);
+  return isPrimaryImportSource(paths, filePath) && !NON_AUTHORITATIVE_CLI_PATH_PATTERN.test(normalized);
 }
 
 /**

package/src/import/extractors/db/drizzle.js

@@ -5,6 +5,7 @@ import {
   dedupeCandidateRecords,
   findImportFiles,
   idHintify,
+  isPrimaryImportSource,
   makeCandidateRecord,
   relativeTo,
   slugify,
@@ -167,7 +168,10 @@ function parseDrizzleTables(schemaText) {
 }
 
 function drizzleConfigFiles(context) {
-  return findImportFiles(context.paths, (filePath) => /drizzle\.config\.(ts|js|mjs|cjs)$/i.test(path.basename(filePath)));
+  return findImportFiles(context.paths, (filePath) =>
+    /drizzle\.config\.(ts|js|mjs|cjs)$/i.test(path.basename(filePath)) &&
+    isPrimaryImportSource(context.paths, filePath)
+  );
 }
 
 function configuredSchemaFiles(context, configFiles) {
@@ -184,15 +188,21 @@ function configuredSchemaFiles(context, configFiles) {
   return files;
 }
 
+function isDrizzleSchemaSource(context, filePath) {
+  const text = context.helpers.readTextIfExists(filePath) || "";
+  return /\b(?:pgTable|sqliteTable|mysqlTable)\s*\(/.test(text);
+}
+
 function findDrizzleSchemaFiles(context) {
   const configFiles = drizzleConfigFiles(context);
   const conventionalSchemaFiles = findImportFiles(context.paths, (filePath) =>
-    /(?:^|\/)(?:src\/db\/schema|src\/schema|db\/schema|schema)\.(ts|js|mjs|cjs)$/i.test(relativeTo(context.paths.workspaceRoot, filePath).replaceAll(path.sep, "/"))
+    /(?:^|\/)(?:src\/db\/schema|src\/schema|db\/schema|schema)\.(ts|js|mjs|cjs)$/i.test(relativeTo(context.paths.workspaceRoot, filePath).replaceAll(path.sep, "/")) &&
+    isPrimaryImportSource(context.paths, filePath)
   );
   return [...new Set([
     ...configuredSchemaFiles(context, configFiles),
     ...conventionalSchemaFiles
-  ])].sort();
+  ])].filter((filePath) => isDrizzleSchemaSource(context, filePath)).sort();
 }
 
 export const drizzleExtractor = {

package/src/import/extractors/db/maintained-seams.js

@@ -2,7 +2,7 @@
 
 import path from "node:path";
 
-import { findImportFiles, makeCandidateRecord, relativeTo } from "../../core/shared.js";
+import { findImportFiles, isPrimaryImportSource, makeCandidateRecord, relativeTo } from "../../core/shared.js";
 
 /** @param {string} value @returns {string} */
 function toPosix(value) {
@@ -86,6 +86,13 @@ function maintainedDbSeamCandidate(context, options) {
     ...(options.migrationsPath ? { migrationsPath: options.migrationsPath } : {})
   };
   const idHint = `seam_${options.tool}_db_migrations`;
+  const manualNextSteps = [
+    "Review evidence, match_reasons, and missing_decisions before accepting this seam.",
+    `Confirm database runtime '${runtimeId}' and projection '${projectionId}' are the right topology targets for the maintained app.`,
+    "If accepted, copy proposed_runtime_migration into the matching database runtime's migration block in topogram.project.json.",
+    "Keep ownership 'maintained' and apply 'never'; import must not apply migrations or patch maintained app files.",
+    "After editing topogram.project.json, run topogram check . --json and the maintained app's migration verification."
+  ];
 
   return makeCandidateRecord({
     kind: "maintained_db_migration_seam",
@@ -112,6 +119,13 @@ function maintainedDbSeamCandidate(context, options) {
     match_reasons: options.matchReasons,
     missing_decisions: options.missingDecisions,
     proposed_runtime_migration: proposedRuntimeMigration,
+    manual_next_steps: manualNextSteps,
+    project_config_target: {
+      file: "topogram.project.json",
+      path: `topology.runtimes[id=${runtimeId}].migration`,
+      runtime_id: runtimeId,
+      projection_id: projectionId
+    },
     maintained_modules: [options.schemaPath, options.migrationsPath].filter(Boolean),
     emitted_dependencies: [snapshotPath, projectionId],
     allowed_change_classes: ["proposal_only"],
@@ -125,7 +139,10 @@ export function inferPrismaMaintainedDbSeams(context, prismaFiles) {
     return [];
   }
   const schemaPath = appRelativePath(context, prismaFiles[0]);
-  const migrationFiles = /** @type {string[]} */ (findImportFiles(context.paths, /** @param {string} filePath */ (filePath) => toPosix(filePath).includes("/prisma/migrations/")));
+  const migrationFiles = /** @type {string[]} */ (findImportFiles(context.paths, /** @param {string} filePath */ (filePath) =>
+    toPosix(filePath).includes("/prisma/migrations/") &&
+    isPrimaryImportSource(context.paths, filePath)
+  ));
   const migrationsPath = firstMarkedDirectory(context, migrationFiles, [["prisma", "migrations"]]);
   return [
     maintainedDbSeamCandidate(context, {
@@ -150,8 +167,14 @@ export function inferDrizzleMaintainedDbSeams(context, schemaFiles) {
   if (!schemaFiles.length) {
     return [];
   }
-  const configFiles = /** @type {string[]} */ (findImportFiles(context.paths, /** @param {string} filePath */ (filePath) => /drizzle\.config\.(ts|js|mjs|cjs)$/i.test(path.basename(filePath))));
-  const drizzleFiles = /** @type {string[]} */ (findImportFiles(context.paths, /** @param {string} filePath */ (filePath) => appRelativePath(context, filePath).startsWith("drizzle/")));
+  const configFiles = /** @type {string[]} */ (findImportFiles(context.paths, /** @param {string} filePath */ (filePath) =>
+    /drizzle\.config\.(ts|js|mjs|cjs)$/i.test(path.basename(filePath)) &&
+    isPrimaryImportSource(context.paths, filePath)
+  ));
+  const drizzleFiles = /** @type {string[]} */ (findImportFiles(context.paths, /** @param {string} filePath */ (filePath) =>
+    appRelativePath(context, filePath).startsWith("drizzle/") &&
+    isPrimaryImportSource(context.paths, filePath)
+  ));
   const configuredOutPath = drizzleOutPathFromConfig(context, configFiles);
   const migrationsPath = configuredOutPath ||
     firstMarkedDirectory(context, drizzleFiles, [["drizzle"]]);

package/src/import/extractors/db/prisma.js

@@ -1,5 +1,6 @@
 import {
   findImportFiles,
+  isPrimaryImportSource,
   makeCandidateRecord,
   normalizePrismaType,
   relativeTo,
@@ -113,7 +114,10 @@ export const prismaExtractor = {
   id: "db.prisma",
   track: "db",
   detect(context) {
-    const files = findImportFiles(context.paths, (filePath) => filePath.endsWith("/prisma/schema.prisma") || filePath.endsWith("prisma/schema.prisma"));
+    const files = findImportFiles(context.paths, (filePath) =>
+      (filePath.endsWith("/prisma/schema.prisma") || filePath.endsWith("prisma/schema.prisma")) &&
+      isPrimaryImportSource(context.paths, filePath)
+    );
     return {
       score: files.length > 0 ? 100 : 0,
       reasons: files.length > 0 ? ["Found Prisma schema"] : []
@@ -122,7 +126,10 @@ export const prismaExtractor = {
   extract(context) {
     const prismaFiles = selectPreferredImportFiles(
       context.paths,
-      findImportFiles(context.paths, (filePath) => filePath.endsWith("/prisma/schema.prisma") || filePath.endsWith("prisma/schema.prisma")),
+      findImportFiles(context.paths, (filePath) =>
+        (filePath.endsWith("/prisma/schema.prisma") || filePath.endsWith("prisma/schema.prisma")) &&
+        isPrimaryImportSource(context.paths, filePath)
+      ),
       "prisma"
     );
     const findings = [];

package/src/import/extractors/db/sql.js

@@ -1,4 +1,4 @@
-import { canonicalCandidateTerm, findImportFiles, makeCandidateRecord, relativeTo, selectPreferredImportFiles, slugify, titleCase, idHintify } from "../../core/shared.js";
+import { canonicalCandidateTerm, findImportFiles, isPrimaryImportSource, makeCandidateRecord, relativeTo, selectPreferredImportFiles, slugify, titleCase, idHintify } from "../../core/shared.js";
 import { inferSqlMaintainedDbSeams } from "./maintained-seams.js";
 
 function parseTableConstraint(line, tableName) {
@@ -105,14 +105,14 @@ export const sqlExtractor = {
   id: "db.sql",
   track: "db",
   detect(context) {
-    const files = findImportFiles(context.paths, (filePath) => filePath.endsWith(".sql"));
+    const files = findImportFiles(context.paths, (filePath) => filePath.endsWith(".sql") && isPrimaryImportSource(context.paths, filePath));
     return {
       score: files.length > 0 ? 80 : 0,
       reasons: files.length > 0 ? ["Found SQL schema or migration files"] : []
     };
   },
   extract(context) {
-    const allSqlFiles = findImportFiles(context.paths, (filePath) => filePath.endsWith(".sql"));
+    const allSqlFiles = findImportFiles(context.paths, (filePath) => filePath.endsWith(".sql") && isPrimaryImportSource(context.paths, filePath));
     const schemaSqlFiles = allSqlFiles.filter((filePath) => !/migration/i.test(filePath) && !/\/src\/test\//i.test(filePath));
     const migrationSqlFiles = allSqlFiles.filter((filePath) => /migration/i.test(filePath));
     const sqlFiles =

package/src/import/extractors/ui/next-app-router.js

@@ -1,4 +1,4 @@
-import { dedupeCandidateRecords, inferNextAppRoutes, makeCandidateRecord, nextScreenIdForRoute, nextScreenKindForRoute, uiCapabilityHintsForNextRoute, entityIdForNextRoute, conceptIdForNextRoute, relativeTo, titleCase, idHintify } from "../../core/shared.js";
+import { dedupeCandidateRecords, inferNextAppRoutes, inferNonResourceUiFlow, makeCandidateRecord, nextScreenIdForRoute, nextScreenKindForRoute, proposedUiContractAdditionsForFlow, uiCapabilityHintsForNextRoute, entityIdForNextRoute, conceptIdForNextRoute, relativeTo, titleCase, idHintify, uiFlowIdForRoute } from "../../core/shared.js";
 
 export const nextAppRouterUiExtractor = {
   id: "ui.next-app-router",
@@ -13,7 +13,7 @@ export const nextAppRouterUiExtractor = {
   extract(context) {
     const routes = inferNextAppRoutes(context.paths.workspaceRoot, context.helpers);
     const findings = [];
-    const candidates = { screens: [], routes: [], actions: [], stacks: [] };
+    const candidates = { screens: [], routes: [], actions: [], flows: [], stacks: [] };
     if (routes.length > 0) {
       findings.push({
         kind: "next_app_routes",
@@ -26,9 +26,10 @@ export const nextAppRouterUiExtractor = {
         const provenance = `${relativeTo(context.paths.repoRoot, route.file)}#${route.path}`;
         const screenId = nextScreenIdForRoute(route.path);
         const screenKind = nextScreenKindForRoute(route.path);
-        const capabilityHints = uiCapabilityHintsForNextRoute(route.path);
-        const entityId = entityIdForNextRoute(route.path);
-        const conceptId = conceptIdForNextRoute(route.path);
+        const flow = inferNonResourceUiFlow(route.path);
+        const capabilityHints = flow ? { load: null, submit: null, primary_action: null } : uiCapabilityHintsForNextRoute(route.path);
+        const entityId = flow ? null : entityIdForNextRoute(route.path);
+        const conceptId = flow?.concept_id || conceptIdForNextRoute(route.path);
         candidates.screens.push(makeCandidateRecord({
           kind: "screen",
           idHint: screenId,
@@ -56,6 +57,25 @@ export const nextAppRouterUiExtractor = {
           concept_id: conceptId,
           path: route.path
         }));
+        if (flow) {
+          candidates.flows.push(makeCandidateRecord({
+            kind: "ui_flow",
+            idHint: uiFlowIdForRoute(route.path, screenId),
+            label: `${titleCase(flow.flow_type)} Flow`,
+            confidence: flow.confidence,
+            sourceKind: "route_code",
+            sourceOfTruth: "candidate",
+            provenance,
+            track: "ui",
+            flow_type: flow.flow_type,
+            concept_id: flow.concept_id,
+            screen_ids: [screenId],
+            route_paths: [route.path],
+            evidence: [provenance],
+            missing_decisions: flow.missing_decisions,
+            proposed_ui_contract_additions: proposedUiContractAdditionsForFlow(route.path, screenId, screenKind)
+          }));
+        }
         if (capabilityHints.primary_action) {
           candidates.actions.push(makeCandidateRecord({
             kind: "ui_action",
@@ -77,6 +97,7 @@ export const nextAppRouterUiExtractor = {
     candidates.screens = dedupeCandidateRecords(candidates.screens, (record) => record.id_hint);
     candidates.routes = dedupeCandidateRecords(candidates.routes, (record) => record.id_hint);
     candidates.actions = dedupeCandidateRecords(candidates.actions, (record) => record.id_hint);
+    candidates.flows = dedupeCandidateRecords(candidates.flows, (record) => record.id_hint);
     candidates.stacks = [...new Set(candidates.stacks)].sort();
     return { findings, candidates };
   }

package/src/import/extractors/ui/next-pages-router.js

@@ -3,9 +3,12 @@ import path from "node:path";
 import {
   dedupeCandidateRecords,
   findImportFiles,
+  inferNonResourceUiFlow,
   makeCandidateRecord,
+  proposedUiContractAdditionsForFlow,
   relativeTo,
   titleCase,
+  uiFlowIdForRoute,
   idHintify
 } from "../../core/shared.js";
 
@@ -70,7 +73,7 @@ export const nextPagesRouterUiExtractor = {
     const pageFiles = findImportFiles(context.paths, (filePath) => /src\/pages\/.+\.(tsx|ts|jsx|js|mdx)$/i.test(filePath))
       .filter((filePath) => !/\/api\//.test(filePath) && !/\/_(app|document|error)\./.test(filePath) && !/\/404\./.test(filePath));
     const findings = [];
-    const candidates = { screens: [], routes: [], actions: [], stacks: [] };
+    const candidates = { screens: [], routes: [], actions: [], flows: [], stacks: [] };
     if (pageFiles.length > 0) {
       const routes = [];
       for (const filePath of pageFiles) {
@@ -78,6 +81,7 @@ export const nextPagesRouterUiExtractor = {
         const text = context.helpers.readTextIfExists(filePath) || "";
         const hooks = inferTrpcHooks(text);
         const screen = screenFromRouteAndHooks(routePath, hooks);
+        const flow = inferNonResourceUiFlow(routePath);
         const provenance = `${relativeTo(context.paths.repoRoot, filePath)}#${routePath}`;
         routes.push(routePath);
         candidates.screens.push(makeCandidateRecord({
@@ -88,11 +92,11 @@ export const nextPagesRouterUiExtractor = {
           sourceKind: "route_code",
           provenance,
           track: "ui",
-          entity_id: screen.entity,
-          concept_id: screen.concept,
-          screen_kind: screen.kind,
+          entity_id: flow ? null : screen.entity,
+          concept_id: flow?.concept_id || screen.concept,
+          screen_kind: flow ? "flow" : screen.kind,
           route_path: routePath,
-          capability_hints: hooks.map((hook) => capabilityHint(hook.router, hook.procedure))
+          capability_hints: flow ? [] : hooks.map((hook) => capabilityHint(hook.router, hook.procedure))
         }));
         candidates.routes.push(makeCandidateRecord({
           kind: "ui_route",
@@ -103,10 +107,29 @@ export const nextPagesRouterUiExtractor = {
           provenance,
           track: "ui",
           screen_id: screen.id,
-          entity_id: screen.entity,
-          concept_id: screen.concept,
+          entity_id: flow ? null : screen.entity,
+          concept_id: flow?.concept_id || screen.concept,
           path: routePath
         }));
+        if (flow) {
+          candidates.flows.push(makeCandidateRecord({
+            kind: "ui_flow",
+            idHint: uiFlowIdForRoute(routePath, screen.id),
+            label: `${titleCase(flow.flow_type)} Flow`,
+            confidence: flow.confidence,
+            sourceKind: "route_code",
+            sourceOfTruth: "candidate",
+            provenance,
+            track: "ui",
+            flow_type: flow.flow_type,
+            concept_id: flow.concept_id,
+            screen_ids: [screen.id],
+            route_paths: [routePath],
+            evidence: [provenance],
+            missing_decisions: flow.missing_decisions,
+            proposed_ui_contract_additions: proposedUiContractAdditionsForFlow(routePath, screen.id, "flow")
+          }));
+        }
         for (const hook of hooks.filter((hook) => hook.hook === "Mutation")) {
           const capability = capabilityHint(hook.router, hook.procedure);
           candidates.actions.push(makeCandidateRecord({
@@ -135,6 +158,7 @@ export const nextPagesRouterUiExtractor = {
     candidates.screens = dedupeCandidateRecords(candidates.screens, (record) => record.id_hint);
     candidates.routes = dedupeCandidateRecords(candidates.routes, (record) => record.id_hint);
     candidates.actions = dedupeCandidateRecords(candidates.actions, (record) => record.id_hint);
+    candidates.flows = dedupeCandidateRecords(candidates.flows, (record) => record.id_hint);
     candidates.stacks = [...new Set(candidates.stacks)].sort();
     return { findings, candidates };
   }

package/src/import/extractors/ui/react-router.js

@@ -2,14 +2,17 @@ import {
   dedupeCandidateRecords,
   detectUiPresentationFeatures,
   entityIdForRoute,
+  inferNonResourceUiFlow,
   inferNavigationStructure,
   inferReactRoutes,
   makeCandidateRecord,
   navigationPatternsFromStructure,
+  proposedUiContractAdditionsForFlow,
   relativeTo,
   shellKindFromNavigation,
   screenIdForRoute,
   screenKindForRoute,
+  uiFlowIdForRoute,
   uiCapabilityHintsForRoute,
   titleCase,
   idHintify
@@ -29,7 +32,7 @@ export const reactRouterUiExtractor = {
   },
   extract(context) {
     const findings = [];
-    const candidates = { screens: [], routes: [], actions: [], stacks: [] };
+    const candidates = { screens: [], routes: [], actions: [], flows: [], stacks: [] };
     const roots = [
       path.join(context.paths.workspaceRoot, "apps", "web"),
       path.join(context.paths.workspaceRoot, "examples", "maintained", "proof-app")
@@ -75,16 +78,20 @@ export const reactRouterUiExtractor = {
       for (const routePath of routes) {
         const screenId = screenIdForRoute(routePath);
         const screenKind = screenKindForRoute(routePath);
-        const capabilityHints = uiCapabilityHintsForRoute(routePath);
+        const flow = inferNonResourceUiFlow(routePath);
+        const capabilityHints = flow ? { load: null, submit: null, primary_action: null } : uiCapabilityHintsForRoute(routePath);
+        const entityId = flow ? null : entityIdForRoute(routePath);
+        const routeProvenance = `${provenance}#${routePath}`;
         candidates.screens.push(makeCandidateRecord({
           kind: "screen",
           idHint: screenId,
           label: titleCase(screenId),
           confidence: "medium",
           sourceKind: "route_code",
-          provenance: `${provenance}#${routePath}`,
+          provenance: routeProvenance,
           track: "ui",
-          entity_id: entityIdForRoute(routePath),
+          entity_id: entityId,
+          concept_id: flow?.concept_id || entityId,
           screen_kind: screenKind,
           route_path: routePath,
           capability_hints: capabilityHints
@@ -95,12 +102,32 @@ export const reactRouterUiExtractor = {
           label: routePath,
           confidence: "medium",
           sourceKind: "route_code",
-          provenance: `${provenance}#${routePath}`,
+          provenance: routeProvenance,
           track: "ui",
           screen_id: screenId,
-          entity_id: entityIdForRoute(routePath),
+          entity_id: entityId,
+          concept_id: flow?.concept_id || entityId,
           path: routePath
         }));
+        if (flow) {
+          candidates.flows.push(makeCandidateRecord({
+            kind: "ui_flow",
+            idHint: uiFlowIdForRoute(routePath, screenId),
+            label: `${titleCase(flow.flow_type)} Flow`,
+            confidence: flow.confidence,
+            sourceKind: "route_code",
+            sourceOfTruth: "candidate",
+            provenance: routeProvenance,
+            track: "ui",
+            flow_type: flow.flow_type,
+            concept_id: flow.concept_id,
+            screen_ids: [screenId],
+            route_paths: [routePath],
+            evidence: [routeProvenance],
+            missing_decisions: flow.missing_decisions,
+            proposed_ui_contract_additions: proposedUiContractAdditionsForFlow(routePath, screenId, screenKind)
+          }));
+        }
         if (capabilityHints.primary_action) {
           candidates.actions.push(makeCandidateRecord({
             kind: "ui_action",
@@ -133,6 +160,7 @@ export const reactRouterUiExtractor = {
     candidates.screens = dedupeCandidateRecords(candidates.screens, (record) => record.id_hint);
     candidates.routes = dedupeCandidateRecords(candidates.routes, (record) => record.id_hint);
     candidates.actions = dedupeCandidateRecords(candidates.actions, (record) => record.id_hint);
+    candidates.flows = dedupeCandidateRecords(candidates.flows, (record) => record.id_hint);
     candidates.stacks = [...new Set(candidates.stacks)].sort();
     return { findings, candidates };
   }

package/src/import/extractors/ui/sveltekit.js

@@ -2,14 +2,17 @@ import {
   dedupeCandidateRecords,
   detectUiPresentationFeatures,
   entityIdForRoute,
+  inferNonResourceUiFlow,
   inferNavigationStructure,
   inferSvelteRoutes,
   makeCandidateRecord,
   navigationPatternsFromStructure,
+  proposedUiContractAdditionsForFlow,
   relativeTo,
   shellKindFromNavigation,
   screenIdForRoute,
   screenKindForRoute,
+  uiFlowIdForRoute,
   uiCapabilityHintsForRoute,
   titleCase
 } from "../../core/shared.js";
@@ -28,7 +31,7 @@ export const svelteKitUiExtractor = {
   },
   extract(context) {
     const findings = [];
-    const candidates = { screens: [], routes: [], actions: [], stacks: [] };
+    const candidates = { screens: [], routes: [], actions: [], flows: [], stacks: [] };
     const roots = [
       path.join(context.paths.workspaceRoot, "apps", "web-sveltekit"),
       path.join(context.paths.workspaceRoot, "apps", "local-stack", "web")
@@ -74,16 +77,20 @@ export const svelteKitUiExtractor = {
       for (const routePath of routes) {
         const screenId = screenIdForRoute(routePath);
         const screenKind = screenKindForRoute(routePath);
-        const capabilityHints = uiCapabilityHintsForRoute(routePath);
+        const flow = inferNonResourceUiFlow(routePath);
+        const capabilityHints = flow ? { load: null, submit: null, primary_action: null } : uiCapabilityHintsForRoute(routePath);
+        const entityId = flow ? null : entityIdForRoute(routePath);
+        const routeProvenance = `${provenance}#${routePath}`;
         candidates.screens.push(makeCandidateRecord({
           kind: "screen",
           idHint: screenId,
           label: titleCase(screenId),
           confidence: "medium",
           sourceKind: "route_code",
-          provenance: `${provenance}#${routePath}`,
+          provenance: routeProvenance,
           track: "ui",
-          entity_id: entityIdForRoute(routePath),
+          entity_id: entityId,
+          concept_id: flow?.concept_id || entityId,
           screen_kind: screenKind,
           route_path: routePath,
           capability_hints: capabilityHints
@@ -94,12 +101,32 @@ export const svelteKitUiExtractor = {
           label: routePath,
           confidence: "medium",
           sourceKind: "route_code",
-          provenance: `${provenance}#${routePath}`,
+          provenance: routeProvenance,
           track: "ui",
           screen_id: screenId,
-          entity_id: entityIdForRoute(routePath),
+          entity_id: entityId,
+          concept_id: flow?.concept_id || entityId,
           path: routePath
         }));
+        if (flow) {
+          candidates.flows.push(makeCandidateRecord({
+            kind: "ui_flow",
+            idHint: uiFlowIdForRoute(routePath, screenId),
+            label: `${titleCase(flow.flow_type)} Flow`,
+            confidence: flow.confidence,
+            sourceKind: "route_code",
+            sourceOfTruth: "candidate",
+            provenance: routeProvenance,
+            track: "ui",
+            flow_type: flow.flow_type,
+            concept_id: flow.concept_id,
+            screen_ids: [screenId],
+            route_paths: [routePath],
+            evidence: [routeProvenance],
+            missing_decisions: flow.missing_decisions,
+            proposed_ui_contract_additions: proposedUiContractAdditionsForFlow(routePath, screenId, screenKind)
+          }));
+        }
       }
       for (const feature of features) {
         candidates.actions.push(makeCandidateRecord({
@@ -117,6 +144,7 @@ export const svelteKitUiExtractor = {
     candidates.screens = dedupeCandidateRecords(candidates.screens, (record) => record.id_hint);
     candidates.routes = dedupeCandidateRecords(candidates.routes, (record) => record.id_hint);
     candidates.actions = dedupeCandidateRecords(candidates.actions, (record) => record.id_hint);
+    candidates.flows = dedupeCandidateRecords(candidates.flows, (record) => record.id_hint);
     candidates.stacks = [...new Set(candidates.stacks)].sort();
     return { findings, candidates };
   }

package/src/import/extractors/ui/swiftui.js

@@ -3,6 +3,7 @@ import {
   dedupeCandidateRecords,
   findImportFiles,
   idHintify,
+  isPrimaryImportSource,
   makeCandidateRecord,
   relativeTo,
   titleCase
@@ -117,7 +118,7 @@ export const swiftUiExtractor = {
   id: "ui.swiftui",
   track: "ui",
   detect(context) {
-    const files = findImportFiles(context.paths, (filePath) => /\.swift$/i.test(filePath))
+    const files = findImportFiles(context.paths, (filePath) => /\.swift$/i.test(filePath) && isPrimaryImportSource(context.paths, filePath))
       .filter((filePath) => /:\s*View\b/.test(context.helpers.readTextIfExists(filePath) || ""));
     return {
       score: files.length > 0 ? 84 : 0,
@@ -125,7 +126,7 @@ export const swiftUiExtractor = {
     };
   },
   extract(context) {
-    const files = findImportFiles(context.paths, (filePath) => /\.swift$/i.test(filePath))
+    const files = findImportFiles(context.paths, (filePath) => /\.swift$/i.test(filePath) && isPrimaryImportSource(context.paths, filePath))
       .filter((filePath) => /:\s*View\b/.test(context.helpers.readTextIfExists(filePath) || ""));
     const findings = [];
     const candidates = { screens: [], routes: [], actions: [], stacks: [] };

package/src/workflows/reconcile/bundle-core/index.js

@@ -39,6 +39,7 @@ export function getOrCreateCandidateBundle(bundles, conceptId, label) {
       screens: [],
       uiRoutes: [],
       uiActions: [],
+      uiFlows: [],
       workflows: [],
       verifications: [],
       workflowStates: [],
@@ -337,6 +338,7 @@ export function renderCandidateBundleReadme(bundle, proposalSurfaces = []) {
     `Screens: ${bundle.screens.length}`,
     `UI routes: ${bundle.uiRoutes.length}`,
     `UI actions: ${bundle.uiActions.length}`,
+    `UI flows: ${(bundle.uiFlows || []).length}`,
     `Workflows: ${bundle.workflows.length}`,
     `Verifications: ${bundle.verifications.length}`,
     `Workflow states: ${bundle.workflowStates.length}`,
@@ -455,6 +457,16 @@ export function renderCandidateBundleReadme(bundle, proposalSurfaces = []) {
         lines.push(`    - label ${candidate.label}`);
         lines.push(`    - kind ${candidate.kind}`);
         lines.push(`    - why matched ${candidate.match_reasons.length ? candidate.match_reasons.join("; ") : "dependency overlap with maintained seam evidence"}`);
+        lines.push(`    - missing decisions ${(candidate.missing_decisions || []).length ? candidate.missing_decisions.join("; ") : "none"}`);
+        lines.push(`    - project config target \`${candidate.project_config_target?.path || "topology.runtimes[].migration"}\``);
+        lines.push(`    - evidence ${(candidate.evidence || []).slice(0, 3).map((/** @type {string} */ item) => `\`${item}\``).join(", ") || "_none_"}`);
+        lines.push("    - proposed runtime migration");
+        lines.push("      ```json");
+        lines.push(`      ${JSON.stringify(candidate.proposed_runtime_migration || {}, null, 2).replace(/\n/g, "\n      ")}`);
+        lines.push("      ```");
+        for (const step of candidate.manual_next_steps || []) {
+          lines.push(`    - manual next: ${step}`);
+        }
       }
     }
   }
@@ -554,6 +566,13 @@ export function renderCandidateBundleReadme(bundle, proposalSurfaces = []) {
       lines.push(`- \`${entry.id_hint}\` ${entry.screen_kind} at \`${entry.route_path}\``);
     }
   }
+  if ((bundle.uiFlows || []).length > 0) {
+    lines.push("", "## UI Flow Evidence", "");
+    for (const entry of bundle.uiFlows) {
+      lines.push(`- \`${entry.id_hint}\` ${entry.flow_type || "flow"} routes ${(entry.route_paths || []).map((/** @type {string} */ item) => `\`${item}\``).join(", ") || "_none_"}`);
+      lines.push(`  - missing decisions ${(entry.missing_decisions || []).length ? entry.missing_decisions.join("; ") : "none"}`);
+    }
+  }
   if (bundle.workflows.length > 0) {
     lines.push("", "## Workflow Evidence", "");
     for (const entry of bundle.workflows) {
@@ -578,7 +597,7 @@ export function renderMaintainedSeamCandidatesInline(bundle) {
   return entries
     .map((/** @type {any} */ surface) => {
       const seams = (surface.maintained_seam_candidates || [])
-        .map((/** @type {any} */ candidate) => `\`${candidate.seam_id}\` (${candidate.status}, ${candidate.ownership_class}, confidence=${candidate.confidence})`)
+        .map((/** @type {any} */ candidate) => `\`${candidate.seam_id}\` (${candidate.status}, ${candidate.ownership_class}, confidence=${candidate.confidence}, missing decisions=${(candidate.missing_decisions || []).length})`)
         .join(", ");
       return `${surface.id}: ${seams}`;
     })

package/src/workflows/reconcile/candidate-model.js

@@ -22,6 +22,7 @@ import {
   renderCandidateEntity,
   renderCandidateEnum,
   renderCandidateShape,
+  renderCandidateUiFlowDoc,
   renderCandidateUiReportDoc,
   renderCandidateVerification,
   renderCandidateWidget,
@@ -83,8 +84,9 @@ export function bestContextBundleForCandidate(bundles, candidate) {
 export function buildCandidateModelBundles(graph, appImport, topogramRoot) {
   const dbCandidates = appImport.candidates.db || { entities: [], enums: [], maintained_seams: [] };
   const apiCandidates = appImport.candidates.api || { capabilities: [] };
-  const uiCandidates = appImport.candidates.ui || { screens: [], routes: [], actions: [], widgets: [], shapes: [] };
+  const uiCandidates = appImport.candidates.ui || { screens: [], routes: [], actions: [], flows: [], widgets: [], shapes: [] };
   const uiWidgetCandidates = uiCandidates.widgets || uiCandidates.components || [];
+  const uiFlowCandidates = uiCandidates.flows || [];
   const uiShapeCandidates = uiCandidates.shapes || [];
   const uiShapeCandidatesById = new Map(uiShapeCandidates.map((/** @type {any} */ shape) => [shape.id || shape.id_hint, shape]));
   const workflowCandidates = appImport.candidates.workflows || { workflows: [], workflow_states: [], workflow_transitions: [] };
@@ -209,6 +211,11 @@ export function buildCandidateModelBundles(graph, appImport, topogramRoot) {
     const bundle = getOrCreateCandidateBundle(bundles, conceptId, bundleLabelFromConceptId(conceptId || entry.screen_id || entry.id_hint));
     bundle.uiActions.push(entry);
   }
+  for (const entry of uiFlowCandidates) {
+    const conceptId = entry.concept_id || `flow_${canonicalCandidateTerm(entry.flow_type || entry.id_hint)}`;
+    const bundle = getOrCreateCandidateBundle(bundles, conceptId, bundleLabelFromConceptId(conceptId || entry.id_hint));
+    bundle.uiFlows.push(entry);
+  }
   /** @param {WorkflowRecord} entry @returns {any} */
   function widgetConceptId(entry) {
     if (entry.entity_id || entry.concept_id) {
@@ -334,6 +341,7 @@ export function buildCandidateModelBundles(graph, appImport, topogramRoot) {
       bundle.screens.length > 0 ||
       bundle.uiRoutes.length > 0 ||
       bundle.uiActions.length > 0 ||
+      bundle.uiFlows.length > 0 ||
       bundle.workflows.length > 0 ||
       bundle.verifications.length > 0 ||
       bundle.workflowStates.length > 0 ||
@@ -354,6 +362,7 @@ export function buildCandidateModelBundles(graph, appImport, topogramRoot) {
         screens: bundle.screens.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
         uiRoutes: bundle.uiRoutes.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
         uiActions: bundle.uiActions.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
+        uiFlows: bundle.uiFlows.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
         workflows: bundle.workflows.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
         verifications: bundle.verifications.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
         workflowStates: bundle.workflowStates.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
@@ -499,6 +508,9 @@ export function buildCandidateModelFiles(graph, appImport, topogramRoot) {
       const actions = bundle.uiActions.filter((/** @type {any} */ action) => action.screen_id === screen.id_hint);
       files[`${bundleRoot}/docs/reports/ui-${screen.id_hint}.md`] = renderCandidateUiReportDoc(screen, routes, actions);
     }
+    for (const flow of bundle.uiFlows || []) {
+      files[`${bundleRoot}/docs/reports/ui-flow-${flow.id_hint}.md`] = renderCandidateUiFlowDoc(flow);
+    }
     for (const patch of bundle.projectionPatches || []) {
       files[`${bundleRoot}/${patch.patch_rel_path}`] = renderProjectionPatchDoc(patch);
     }

package/src/workflows/reconcile/impacts/adoption-plan.js

@@ -156,6 +156,19 @@ export function buildBundleAdoptionPlan(bundle, canonicalShapeIndex) {
       canonical_rel_path: `docs/reports/ui-${screen.id_hint}.md`
     });
   }
+  for (const flow of bundle.uiFlows || []) {
+    steps.push({
+      action: "promote_ui_flow_report",
+      item: `ui_flow_${flow.id_hint}`,
+      target: null,
+      confidence: flow.confidence || "medium",
+      inference_summary: `Review non-resource UI flow candidate ${flow.id_hint}.`,
+      source_kind: flow.source_kind || "route_code",
+      source_path: `candidates/reconcile/model/bundles/${bundle.slug}/docs/reports/ui-flow-${flow.id_hint}.md`,
+      canonical_rel_path: `docs/reports/ui-flow-${flow.id_hint}.md`,
+      track: "ui"
+    });
+  }
   for (const patch of bundle.projectionPatches || []) {
     for (const hint of patch.missing_auth_permissions || []) {
       steps.push({

package/src/workflows/reconcile/renderers.js

@@ -283,6 +283,39 @@ export function renderCandidateUiReportDoc(screen, routes, actions) {
   return renderMarkdownDoc(metadata, body);
 }
 
+/** @param {WorkflowRecord} flow @returns {any} */
+export function renderCandidateUiFlowDoc(flow) {
+  /** @type {WorkflowRecord} */
+  const metadata = {
+    id: `ui_flow_${flow.id_hint}`,
+    kind: "report",
+    title: `${flow.label || flow.id_hint} Review`,
+    status: "inferred",
+    source_of_truth: "imported",
+    confidence: flow.confidence || "medium",
+    review_required: true,
+    provenance: flow.provenance || flow.evidence || [],
+    tags: ["import", "ui", "flow"]
+  };
+  const body = [
+    "Candidate non-resource UI flow imported from brownfield route evidence.",
+    "",
+    `Flow: \`${flow.id_hint}\` (${flow.flow_type || "unknown"})`,
+    `Screens: ${(flow.screen_ids || []).map((/** @type {string} */ item) => `\`${item}\``).join(", ") || "_none_"}`,
+    `Routes: ${(flow.route_paths || []).map((/** @type {string} */ item) => `\`${item}\``).join(", ") || "_none_"}`,
+    `Missing decisions: ${(flow.missing_decisions || []).length ? flow.missing_decisions.join("; ") : "none"}`,
+    "",
+    "Proposed UI contract additions:",
+    "",
+    "```json",
+    JSON.stringify(flow.proposed_ui_contract_additions || {}, null, 2),
+    "```",
+    "",
+    "Review this flow before promoting it into shared UI contract behavior."
+  ].join("\n");
+  return renderMarkdownDoc(metadata, body);
+}
+
 /** @param {WorkflowRecord} widget @returns {any} */
 export function renderCandidateWidget(widget) {
   const propName = widget.data_prop || "rows";

package/src/workflows/reconcile/workflow.js

@@ -262,6 +262,7 @@ export function reconcileWorkflow(inputPath, options = {}) {
       widgets: bundle.widgets.map((/** @type {any} */ entry) => entry.id_hint),
       cli_surfaces: (bundle.cliSurfaces || []).map((/** @type {any} */ entry) => entry.id_hint),
       screens: bundle.screens.map((/** @type {any} */ entry) => entry.id_hint),
+      ui_flows: (bundle.uiFlows || []).map((/** @type {any} */ entry) => entry.id_hint),
       workflows: bundle.workflows.map((/** @type {any} */ entry) => entry.id_hint),
       docs: bundle.docs.map((/** @type {any} */ entry) => entry.id),
       maintained_seam_candidates: (agentAdoptionPlan.imported_proposal_surfaces || [])
@@ -284,7 +285,7 @@ export function reconcileWorkflow(inputPath, options = {}) {
     : "## Promoted Canonical Items";
   files["candidates/reconcile/report.json"] = `${stableStringify(report)}\n`;
   const candidateModelBundlesMarkdown = report.candidate_model_bundles.length
-    ? report.candidate_model_bundles.map((/** @type {any} */ bundle) => `- \`${bundle.slug}\` (${bundle.actors.length} actors, ${bundle.roles.length} roles, ${bundle.entities.length} entities, ${bundle.enums.length} enums, ${bundle.capabilities.length} capabilities, ${bundle.shapes.length} shapes, ${bundle.widgets.length} widgets, ${bundle.cli_surfaces.length} CLI surfaces, ${bundle.screens.length} screens, ${bundle.workflows.length} workflows, ${bundle.docs.length} docs)
+    ? report.candidate_model_bundles.map((/** @type {any} */ bundle) => `- \`${bundle.slug}\` (${bundle.actors.length} actors, ${bundle.roles.length} roles, ${bundle.entities.length} entities, ${bundle.enums.length} enums, ${bundle.capabilities.length} capabilities, ${bundle.shapes.length} shapes, ${bundle.widgets.length} widgets, ${bundle.cli_surfaces.length} CLI surfaces, ${bundle.screens.length} screens, ${(bundle.ui_flows || []).length} UI flows, ${bundle.workflows.length} workflows, ${bundle.docs.length} docs)
   - primary concept \`${bundle.operator_summary.primaryConcept}\`${bundle.operator_summary.primaryEntityId ? `, primary entity \`${bundle.operator_summary.primaryEntityId}\`` : ""}
   - participants ${bundle.operator_summary.participants.label}
   - main capabilities ${summarizeBundleSurface(bundle, bundle.operator_summary.capabilityIds)}