@topogram/cli 0.3.65 → 0.3.67

package/package.json

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

package/src/adoption/plan/index.js

@@ -360,7 +360,7 @@ export function selectorMatchesItem(selector, item) {
   if (selector === "journeys") return item.track === "docs" && String(item.canonical_rel_path || "").startsWith("docs/journeys/");
   if (selector === "workflows") return item.track === "workflows" || item.kind === "decision";
   if (selector === "verification") return item.kind === "verification";
-  if (selector === "ui") return item.track === "ui";
+  if (selector === "ui") return item.track === "ui" || item.kind === "widget" || item.source_kind === "ui_widget_event";
   if (selector.startsWith("bundle:")) return item.bundle === selector.slice("bundle:".length);
   return false;
 }
@@ -467,14 +467,21 @@ export function applyAdoptionSelector(adoptionPlan, selector, writeMode) {
 
   const expandSelectedItemsForDependentShapes = (keys) => {
     const expanded = new Set(keys);
-    const selectedCapabilityBundles = new Set(
-      [...expanded]
-        .map((key) => updatedItems.find((item) => adoptionItemKey(item) === key))
-        .filter((item) => item?.kind === "capability")
-        .map((item) => item.bundle)
-    );
+    const selectedItemsForExpansion = [...expanded]
+      .map((key) => updatedItems.find((item) => adoptionItemKey(item) === key))
+      .filter(Boolean);
+    const selectedCapabilityBundles = new Set(selectedItemsForExpansion
+      .filter((item) => item?.kind === "capability")
+      .map((item) => item.bundle));
+    const selectedWidgetShapeIds = new Set(selectedItemsForExpansion
+      .filter((item) => item?.kind === "widget")
+      .flatMap((item) => item.related_shapes || []));
     for (const item of updatedItems) {
-      if (item.kind === "shape" && item.status !== "skipped" && selectedCapabilityBundles.has(item.bundle)) {
+      if (
+        item.kind === "shape" &&
+        item.status !== "skipped" &&
+        (selectedCapabilityBundles.has(item.bundle) || selectedWidgetShapeIds.has(item.item))
+      ) {
         expanded.add(adoptionItemKey(item));
       }
     }
@@ -640,6 +647,7 @@ export function buildAgentAdoptionPlan(adoptionPlan, maintainedBoundaryArtifact
       requirements: {
         related_docs: [...new Set(item.related_docs || [])].sort(),
         related_capabilities: [...new Set(item.related_capabilities || [])].sort(),
+        related_shapes: [...new Set(item.related_shapes || [])].sort(),
         related_rules: [...new Set(item.related_rules || [])].sort(),
         related_workflows: [...new Set(item.related_workflows || [])].sort()
       },
@@ -653,8 +661,12 @@ export function buildAgentAdoptionPlan(adoptionPlan, maintainedBoundaryArtifact
       item: item.item,
       kind: item.kind,
       track: item.track || null,
+      source_kind: item.source_kind || null,
+      widget_id: item.widget_id || null,
+      event_name: item.event_name || null,
       source_path: item.source_path || null,
       canonical_rel_path: item.canonical_rel_path || null,
+      related_shapes: [...new Set(item.related_shapes || [])].sort(),
       review_boundary: reviewBoundaryForImportProposal(item),
       current_state: currentState,
       recommended_state: inferRecommendedAdoptionState(item),
@@ -670,6 +682,7 @@ export function buildAgentAdoptionPlan(adoptionPlan, maintainedBoundaryArtifact
       requirements: {
         related_docs: [...new Set(item.related_docs || [])].sort(),
         related_capabilities: [...new Set(item.related_capabilities || [])].sort(),
+        related_shapes: [...new Set(item.related_shapes || [])].sort(),
         related_rules: [...new Set(item.related_rules || [])].sort(),
         related_workflows: [...new Set(item.related_workflows || [])].sort(),
         blocking_dependencies: [...(item.blocking_dependencies || [])]

package/src/adoption/reporting.js

@@ -347,7 +347,7 @@ export function buildPromotedCanonicalItems(planItems, selectedItems, writtenCan
       track: item.track || null,
       source_path: item.source_path || null,
       canonical_rel_path: normalizeReportPath(item.canonical_rel_path),
-      canonical_path: item.canonical_path || `topogram/${normalizeReportPath(item.canonical_rel_path)}`,
+      canonical_path: item.canonical_path || `topo/${normalizeReportPath(item.canonical_rel_path)}`,
       suggested_action: item.suggested_action || null,
       change_type: updatedSet.has(normalizeReportPath(item.canonical_rel_path)) ? "update" : "create"
     }))

package/src/agent-brief.js

@@ -20,6 +20,7 @@ import {
   getTemplateTrustStatus,
   TEMPLATE_TRUST_FILE
 } from "./template-trust.js";
+import { DEFAULT_TOPO_FOLDER_NAME, resolveTopoRoot, resolveWorkspaceContext } from "./workspace-paths.js";
 
 /**
  * @typedef {{ path: string, reason: string, required: boolean, exists: boolean }} AgentBriefReadItem
@@ -36,12 +37,7 @@ import {
  * @returns {string}
  */
 export function normalizeAgentTopogramPath(inputPath) {
-  const resolved = path.resolve(inputPath || "./topogram");
-  if (path.basename(resolved) === "topogram") {
-    return resolved;
-  }
-  const nested = path.join(resolved, "topogram");
-  return fs.existsSync(nested) && fs.statSync(nested).isDirectory() ? nested : resolved;
+  return resolveTopoRoot(inputPath || ".");
 }
 
 /**
@@ -49,17 +45,7 @@ export function normalizeAgentTopogramPath(inputPath) {
  * @returns {string}
  */
 function normalizeProjectRoot(inputPath) {
-  const resolved = path.resolve(inputPath || ".");
-  if (path.basename(resolved) === "topogram") {
-    return path.dirname(resolved);
-  }
-  if (fs.existsSync(path.join(resolved, "topogram.project.json"))) {
-    return resolved;
-  }
-  if (fs.existsSync(path.join(resolved, "topogram"))) {
-    return resolved;
-  }
-  return path.dirname(normalizeAgentTopogramPath(inputPath));
+  return resolveWorkspaceContext(inputPath || ".").projectRoot;
 }
 
 /**
@@ -325,7 +311,7 @@ export function buildAgentBrief(inputPath, workspaceAst) {
   const generatorDiagnostics = generatorPolicyDiagnosticsForBindings(generatorPolicyInfo, generatorBindings, "agent-brief");
   const importSummary = readImportSummary(configDir);
 
-  const topogramReadPath = path.resolve(topogramRoot) === path.resolve(projectRoot) ? "." : "topogram/";
+  const topogramReadPath = path.resolve(topogramRoot) === path.resolve(projectRoot) ? "." : `${DEFAULT_TOPO_FOLDER_NAME}/`;
   const readOrder = [
     readItem(projectRoot, "AGENTS.md", "Human-readable first-run guidance generated with this project.", false),
     readItem(projectRoot, "README.md", "Project workflow and template provenance summary.", true),
@@ -394,7 +380,7 @@ export function buildAgentBrief(inputPath, workspaceAst) {
     first_commands: firstCommands,
     edit_boundaries: {
       safe_paths: [
-        "topogram/**",
+        `${DEFAULT_TOPO_FOLDER_NAME}/**`,
         "topogram.project.json",
         "topogram.template-policy.json",
         GENERATOR_POLICY_FILE,
@@ -405,8 +391,8 @@ export function buildAgentBrief(inputPath, workspaceAst) {
     },
     workflows: buildWorkflows(config, Boolean(importSummary)),
     file_organization: {
-      small: ["topogram/actors", "topogram/entities", "topogram/shapes", "topogram/capabilities", "topogram/widgets", "topogram/projections", "topogram/verifications"],
-      large: ["topogram/domains/<domain>", "topogram/shared", "topogram/domains/<domain>/widgets", "topogram/domains/<domain>/projections"],
+      small: [`${DEFAULT_TOPO_FOLDER_NAME}/actors`, `${DEFAULT_TOPO_FOLDER_NAME}/entities`, `${DEFAULT_TOPO_FOLDER_NAME}/shapes`, `${DEFAULT_TOPO_FOLDER_NAME}/capabilities`, `${DEFAULT_TOPO_FOLDER_NAME}/widgets`, `${DEFAULT_TOPO_FOLDER_NAME}/projections`, `${DEFAULT_TOPO_FOLDER_NAME}/verifications`],
+      large: [`${DEFAULT_TOPO_FOLDER_NAME}/domains/<domain>`, `${DEFAULT_TOPO_FOLDER_NAME}/shared`, `${DEFAULT_TOPO_FOLDER_NAME}/domains/<domain>/widgets`, `${DEFAULT_TOPO_FOLDER_NAME}/domains/<domain>/projections`],
       parserRule: "Folder layout is for humans and agents; Topogram flattens statements into one graph."
     },
     topology: {

package/src/agent-ops/query-builders/change-risk/review-packets.js

@@ -21,7 +21,7 @@ export function buildCanonicalWritesPayloadForImportPlan(proposalSurfaces = [])
         current_state: surface.current_state,
         recommended_state: surface.recommended_state,
         canonical_rel_path: surface.canonical_rel_path,
-        canonical_path: `topogram/${surface.canonical_rel_path}`
+        canonical_path: `topo/${surface.canonical_rel_path}`
       }))
   };
 }
@@ -55,7 +55,7 @@ export function buildReviewPacketPayloadForImportPlan({ importPlan, risk }) {
       .map((surface) => ({
         id: surface.id,
         canonical_rel_path: surface.canonical_rel_path,
-        canonical_path: `topogram/${surface.canonical_rel_path}`
+        canonical_path: `topo/${surface.canonical_rel_path}`
       })),
     review_groups: importPlan.review_groups || [],
     write_scope: importPlan.write_scope || null,

package/src/agent-ops/query-builders/common.js

@@ -1,5 +1,5 @@
 export function canonicalWriteCandidatesFromWriteScope(writeScope) {
-  return (writeScope?.safe_to_edit || []).filter((entry) => entry === "topogram/**" || String(entry).startsWith("topogram/"));
+  return (writeScope?.safe_to_edit || []).filter((entry) => entry === "topo/**" || String(entry).startsWith("topo/"));
 }
 
 export function summarizeDiffArtifact(diffArtifact) {
@@ -91,7 +91,7 @@ export function componentBehaviorQueryCommand(target = {}) {
   if (target.target !== "widget-behavior-report") {
     return null;
   }
-  const parts = ["topogram", "query", "widget-behavior", "./topogram"];
+  const parts = ["topogram", "query", "widget-behavior", "./topo"];
   if (target.projection_id) {
     parts.push("--projection", target.projection_id);
   }

package/src/agent-ops/query-builders/multi-agent.js

@@ -28,7 +28,7 @@ export function canonicalTargetsForProposalSurfaces(proposalSurfaces = []) {
   return stableSortedStrings(
     proposalSurfaces
       .filter((surface) => surface.canonical_rel_path)
-      .map((surface) => `topogram/${surface.canonical_rel_path}`)
+      .map((surface) => `topo/${surface.canonical_rel_path}`)
   );
 }
 

package/src/agent-ops/query-builders/workflow-presets-core.js

@@ -8,6 +8,7 @@ import {
   stableOrderedUnion,
   stableSortedStrings
 } from "./common.js";
+import { DEFAULT_TOPO_FOLDER_NAME, resolveTopoRoot } from "../../workspace-paths.js";
 export function workflowPresetReviewClass(preset) {
   const categories = stableSortedStrings([
     ...(preset?.review_policy?.escalate_categories || []),
@@ -178,12 +179,12 @@ export function loadWorkflowPresetArtifacts(workspaceRoot) {
   if (!workspaceRoot) {
     return { provider_presets: [], team_presets: [], provider_manifests: [] };
   }
-  const topogramRoot = path.basename(workspaceRoot) === "topogram" ? workspaceRoot : path.join(workspaceRoot, "topogram");
+  const topogramRoot = resolveTopoRoot(workspaceRoot);
   const providerDir = path.join(topogramRoot, "candidates", "providers", "workflow-presets");
   const providerManifestDir = path.join(topogramRoot, "candidates", "providers", "manifests");
   const teamDirs = [
     path.join(topogramRoot, "workflow-presets"),
-    path.join(topogramRoot, "topogram", "workflow-presets")
+    path.join(topogramRoot, DEFAULT_TOPO_FOLDER_NAME, "workflow-presets")
   ];
 
   const providerPresets = readJsonArtifactsFromDir(providerDir)

package/src/archive/jsonl.js

@@ -1,7 +1,7 @@
 // Year-bucketed JSONL archive I/O.
 //
-// File layout: `<project-or-topogram-root>/topogram/_archive/{kind}s-{year}.jsonl`
-// or `<topogram-root>/_archive/{kind}s-{year}.jsonl`
+// File layout: `<project-root>/topo/_archive/{kind}s-{year}.jsonl`
+// or `<workspace-root>/_archive/{kind}s-{year}.jsonl`
 // (e.g. `tasks-2026.jsonl`, `bugs-2026.jsonl`).
 //
 // Each line is a self-contained archived statement. The format is JSONL so

package/src/archive/resolver-bridge.js

@@ -1,7 +1,7 @@
 // Bridge between archived JSONL entries and the live resolver graph.
 //
 // At workspace load time the resolver bridge:
-//   1. Walks `topogram/_archive/*.jsonl`
+//   1. Walks the workspace `_archive/*.jsonl`
 //   2. Builds a flat list of frozen entries (each with `archived: true`)
 //   3. Returns `{ entries, byId }` so the caller can merge them into the
 //      registry / graph

package/src/archive/unarchive.js

@@ -19,6 +19,7 @@ import {
   parseArchiveFile,
   rewriteArchiveFile
 } from "./jsonl.js";
+import { resolveTopoRoot } from "../workspace-paths.js";
 
 const REOPEN_STATUSES = {
   bug: "open",
@@ -83,7 +84,7 @@ export function unarchive(workspaceRoot, id, options = {}) {
 
   const { file, entries, entry } = found;
   const reopenStatus = options.status || REOPEN_STATUSES[entry.kind] || "draft";
-  const targetDir = options.targetDir || path.join(workspaceRoot, "topogram", `${entry.kind}s`);
+  const targetDir = options.targetDir || path.join(resolveTopoRoot(workspaceRoot), `${entry.kind}s`);
   if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true });
   const targetFile = path.join(targetDir, `${entry.id}.tg`);
 

package/src/catalog/copy.js

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { installPackageSpec } from "../new-project.js";
+import { DEFAULT_TOPO_FOLDER_NAME, DEFAULT_WORKSPACE_PATH, resolvePackageWorkspace } from "../workspace-paths.js";
 import { catalogEntryPackageSpec } from "./entries.js";
 import { copyPath, ensureEmptyDirectory } from "./files.js";
 import { writeTopogramSourceRecord } from "./provenance.js";
@@ -26,20 +27,24 @@ export function copyCatalogTopogramEntry(entry, targetPath, options = {}) {
       `Catalog topogram entry '${entry.id}' package '${packageSpec}' contains implementation/, which is not allowed for v1 topogram entries.`
     );
   }
-  const topogramRoot = path.join(packageRoot, "topogram");
-  if (!fs.existsSync(topogramRoot) || !fs.statSync(topogramRoot).isDirectory()) {
-    throw new Error(`Catalog topogram entry '${entry.id}' package '${packageSpec}' is missing topogram/.`);
-  }
+  const packageWorkspace = resolvePackageWorkspace(packageRoot);
 
   const resolvedTarget = path.resolve(targetPath);
   ensureEmptyDirectory(resolvedTarget);
   /** @type {string[]} */
   const files = [];
-  copyPath(topogramRoot, path.join(resolvedTarget, "topogram"), "topogram", files);
+  copyPath(packageWorkspace.root, path.join(resolvedTarget, DEFAULT_TOPO_FOLDER_NAME), DEFAULT_TOPO_FOLDER_NAME, files);
   for (const fileName of ["topogram.project.json", "README.md"]) {
     const sourcePath = path.join(packageRoot, fileName);
     if (fs.existsSync(sourcePath) && fs.statSync(sourcePath).isFile()) {
-      copyPath(sourcePath, path.join(resolvedTarget, fileName), fileName, files);
+      if (fileName === "topogram.project.json") {
+        const projectConfig = JSON.parse(fs.readFileSync(sourcePath, "utf8"));
+        projectConfig.workspace = DEFAULT_WORKSPACE_PATH;
+        fs.writeFileSync(path.join(resolvedTarget, fileName), `${JSON.stringify(projectConfig, null, 2)}\n`, "utf8");
+        files.push(fileName);
+      } else {
+        copyPath(sourcePath, path.join(resolvedTarget, fileName), fileName, files);
+      }
     }
   }
   const provenance = writeTopogramSourceRecord(resolvedTarget, {

package/src/catalog/provenance.js

@@ -5,6 +5,7 @@ import path from "node:path";
 
 import { TOPOGRAM_SOURCE_FILE } from "./constants.js";
 import { collectFiles, fileHash } from "./files.js";
+import { DEFAULT_TOPO_FOLDER_NAME } from "../workspace-paths.js";
 
 /**
  * @param {string} projectRoot
@@ -107,7 +108,7 @@ export function buildTopogramSourceStatus(projectRoot) {
 function collectSourceFileRecords(projectRoot) {
   /** @type {string[]} */
   const files = [];
-  for (const sourceRoot of ["topogram", "topogram.project.json", "README.md"]) {
+  for (const sourceRoot of [DEFAULT_TOPO_FOLDER_NAME, "topogram.project.json", "README.md"]) {
     const sourcePath = path.join(projectRoot, sourceRoot);
     if (fs.existsSync(sourcePath)) {
       collectFiles(sourcePath, sourceRoot, files);

package/src/cli/command-parsers/project.js

@@ -43,5 +43,8 @@ export function parseProjectCommandArgs(args) {
   if (args[0] === "package" && args[1] === "update-cli") {
     return { packageCommand: "update-cli", inputPath: args.includes("--latest") ? "latest" : args[2] };
   }
+  if (args[0] === "migrate" && args[1] === "workspace-folder") {
+    return { migrateCommand: "workspace-folder", inputPath: commandPath(args, 2, ".") };
+  }
   return null;
 }

package/src/cli/command-parsers/shared.js

@@ -12,7 +12,7 @@
  * @param {string} [fallback]
  * @returns {string}
  */
-export function commandPath(args, index, fallback = "./topogram") {
+export function commandPath(args, index, fallback = "./topo") {
   const value = args[index];
   return value && !value.startsWith("-") ? value : fallback;
 }

package/src/cli/commands/agent.js

@@ -14,12 +14,12 @@ export function printAgentHelp() {
   console.log("");
   console.log("Prints read-only first-run guidance for humans and agents working in a Topogram project.");
   console.log("");
-  console.log("Defaults: path is ./topogram. The command validates the Topogram and project config, but does not write files, generate apps, load generator adapters, or execute template implementation.");
+  console.log("Defaults: path is ./topo. The command validates the Topogram and project config, but does not write files, generate apps, load generator adapters, or execute template implementation.");
   console.log("");
   console.log("Examples:");
   console.log("  topogram agent brief");
   console.log("  topogram agent brief --json");
-  console.log("  topogram agent brief ./topogram --json");
+  console.log("  topogram agent brief ./topo --json");
 }
 
 /**

package/src/cli/commands/check.js

@@ -30,12 +30,12 @@ export function printCheckHelp() {
   console.log("");
   console.log("Validates Topogram files, project configuration, topology, generator compatibility, generator policy, output ownership, and template policy.");
   console.log("");
-  console.log("Defaults: path is ./topogram.");
+  console.log("Defaults: path is ./topo.");
   console.log("");
   console.log("Examples:");
   console.log("  topogram check");
   console.log("  topogram check --json");
-  console.log("  topogram check ./topogram");
+  console.log("  topogram check ./topo");
 }
 
 /**
@@ -234,7 +234,7 @@ export function combineProjectValidationResults(...results) {
  * @returns {Promise<number>}
  */
 export async function runCheckCommand(inputPath, options = {}) {
-  const topogramPath = inputPath || "./topogram";
+  const topogramPath = inputPath || "./topo";
   const ast = parsePath(topogramPath);
   const resolved = resolveWorkspace(ast);
   const implementation = await loadImplementationProvider(topogramPath).catch(() => null);

package/src/cli/commands/doctor.js

@@ -1,8 +1,5 @@
 // @ts-check
 
-import fs from "node:fs";
-import path from "node:path";
-
 import {
   catalogSourceOrDefault,
   isCatalogSourceDisabled
@@ -26,6 +23,7 @@ import {
   readInstalledCliPackageVersion,
   readProjectCliDependencySpec
 } from "./package.js";
+import { resolveTopoRoot } from "../../workspace-paths.js";
 
 /**
  * @returns {void}
@@ -67,12 +65,7 @@ function messageFromError(error) {
  * @returns {string}
  */
 function normalizeTopogramPath(inputPath) {
-  const absolute = path.resolve(inputPath);
-  if (path.basename(absolute) === "topogram") {
-    return absolute;
-  }
-  const candidate = path.join(absolute, "topogram");
-  return fs.existsSync(candidate) ? candidate : absolute;
+  return resolveTopoRoot(inputPath);
 }
 
 /**

package/src/cli/commands/generator-policy/runner.js

@@ -26,7 +26,7 @@ import {
  */
 export function runGeneratorPolicyCommand(context) {
   const { commandArgs, inputPath, json } = context;
-  const projectPath = inputPath || "./topogram";
+  const projectPath = inputPath || "./topo";
   if (commandArgs.generatorPolicyCommand === "init") {
     const payload = buildGeneratorPolicyInitPayload(projectPath);
     if (json) {

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

@@ -17,8 +17,8 @@ export function printImportHelp() {
   console.log("Creates an editable Topogram workspace from a brownfield app without modifying the app.");
   console.log("");
   console.log("Behavior:");
-  console.log("  - writes raw import candidates under topogram/candidates/app");
-  console.log("  - writes reconcile proposal bundles under topogram/candidates/reconcile");
+  console.log("  - writes raw import candidates under topo/candidates/app");
+  console.log("  - writes reconcile proposal bundles under topo/candidates/reconcile");
   console.log("  - writes topogram.project.json with maintained ownership and no generated stack binding");
   console.log(`  - writes ${TOPOGRAM_IMPORT_FILE} with source file hashes from import time`);
   console.log("  - imported Topogram artifacts are project-owned after creation");

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

@@ -7,6 +7,7 @@ import path from "node:path";
 import { stableStringify } from "../../../format.js";
 import { TOPOGRAM_IMPORT_FILE } from "../../../import/provenance.js";
 import { shellCommandArg } from "../catalog.js";
+import { resolveTopoRoot, resolveWorkspaceContext } from "../../../workspace-paths.js";
 
 export const TOPOGRAM_IMPORT_ADOPTIONS_FILE = ".topogram-import-adoptions.jsonl";
 
@@ -19,12 +20,7 @@ export const TOPOGRAM_IMPORT_ADOPTIONS_FILE = ".topogram-import-adoptions.jsonl"
  * @returns {string}
  */
 export function normalizeTopogramPath(inputPath) {
-  const absolute = path.resolve(inputPath);
-  if (path.basename(absolute) === "topogram") {
-    return absolute;
-  }
-  const candidate = path.join(absolute, "topogram");
-  return fs.existsSync(candidate) ? candidate : absolute;
+  return resolveTopoRoot(inputPath);
 }
 
 /**
@@ -32,11 +28,7 @@ export function normalizeTopogramPath(inputPath) {
  * @returns {string}
  */
 export function normalizeProjectRoot(inputPath) {
-  const absolute = path.resolve(inputPath);
-  if (path.basename(absolute) === "topogram") {
-    return path.dirname(absolute);
-  }
-  return absolute;
+  return resolveWorkspaceContext(inputPath).projectRoot;
 }
 
 /**

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

@@ -40,7 +40,15 @@ export const BROWNFIELD_BROAD_ADOPT_SELECTORS = [
   },
   { selector: "workflows", kind: "track", label: "workflows", matches: (/** @type {AnyRecord} */ item) => item.track === "workflows" || item.kind === "decision" },
   { selector: "verification", kind: "kind", label: "verification", matches: (/** @type {AnyRecord} */ item) => item.kind === "verification" },
-  { selector: "ui", kind: "track", label: "UI reports and widgets", matches: (/** @type {AnyRecord} */ item) => item.track === "ui" }
+  {
+    selector: "ui",
+    kind: "track",
+    label: "UI reports, widgets, and event shapes",
+    matches: (/** @type {AnyRecord} */ item) =>
+      item.track === "ui" ||
+      item.kind === "widget" ||
+      item.source_kind === "ui_widget_event"
+  }
 ];
 
 /**

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

@@ -12,6 +12,7 @@ import {
   writeTopogramImportRecord
 } from "../../../import/provenance.js";
 import { runWorkflow } from "../../../workflows.js";
+import { DEFAULT_TOPO_FOLDER_NAME } from "../../../workspace-paths.js";
 import {
   countByField,
   importProjectCommandPath,
@@ -240,7 +241,7 @@ export function buildRefreshPreviewReconcile(projectRoot, topogramRoot, importFi
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "topogram-import-refresh-preview."));
   try {
     const tempProjectRoot = path.join(tempRoot, "workspace");
-    const tempTopogramRoot = path.join(tempProjectRoot, "topogram");
+    const tempTopogramRoot = path.join(tempProjectRoot, DEFAULT_TOPO_FOLDER_NAME);
     fs.mkdirSync(tempProjectRoot, { recursive: true });
     fs.cpSync(topogramRoot, tempTopogramRoot, { recursive: true });
     const projectConfigPath = path.join(projectRoot, "topogram.project.json");
@@ -282,7 +283,7 @@ export function buildBrownfieldImportRefreshAnalysis(inputPath, options = {}) {
   const projectRoot = normalizeProjectRoot(inputPath);
   const topogramRoot = normalizeTopogramPath(projectRoot);
   if (!fs.existsSync(topogramRoot) || !fs.statSync(topogramRoot).isDirectory()) {
-    throw new Error(`No topogram directory found for imported workspace '${inputPath}'.`);
+    throw new Error(`No workspace folder found for imported workspace '${inputPath}'.`);
   }
 
   const { record: importRecord } = readTopogramImportRecord(projectRoot);
@@ -315,8 +316,8 @@ export function buildBrownfieldImportRefreshAnalysis(inputPath, options = {}) {
   const receiptVerification = verifyImportAdoptionReceipts(projectRoot, readImportAdoptionReceipts(projectRoot));
   const plannedFiles = [
     TOPOGRAM_IMPORT_FILE,
-    ...Object.keys(importResult.files || {}).map((filePath) => `topogram/${filePath}`),
-    ...previewReconcile.reconcileFilePaths.map((/** @type {string} */ filePath) => `topogram/${filePath}`)
+    ...Object.keys(importResult.files || {}).map((filePath) => `${DEFAULT_TOPO_FOLDER_NAME}/${filePath}`),
+    ...previewReconcile.reconcileFilePaths.map((/** @type {string} */ filePath) => `${DEFAULT_TOPO_FOLDER_NAME}/${filePath}`)
   ].sort((a, b) => a.localeCompare(b));
   const analysis = /** @type {AnyRecord} */ ({
     projectRoot,
@@ -393,8 +394,8 @@ export function buildBrownfieldImportRefreshPayload(inputPath, options = {}) {
     currentImportStatus = buildTopogramImportStatus(analysis.projectRoot).status;
     writtenFiles = [
       TOPOGRAM_IMPORT_FILE,
-      ...rawCandidateFiles.map((filePath) => `topogram/${filePath}`),
-      ...reconcileFiles.map((filePath) => `topogram/${filePath}`)
+      ...rawCandidateFiles.map((filePath) => `${DEFAULT_TOPO_FOLDER_NAME}/${filePath}`),
+      ...reconcileFiles.map((filePath) => `${DEFAULT_TOPO_FOLDER_NAME}/${filePath}`)
     ].sort((a, b) => a.localeCompare(b));
     analysis.removedCandidateFiles = removedCandidateFiles;
     analysis.rawCandidateFiles = rawCandidateFiles.length;

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

@@ -10,6 +10,7 @@ import {
   writeTopogramImportRecord
 } from "../../../import/provenance.js";
 import { runWorkflow } from "../../../workflows.js";
+import { DEFAULT_TOPO_FOLDER_NAME, DEFAULT_WORKSPACE_PATH } from "../../../workspace-paths.js";
 import { shellCommandArg } from "../catalog.js";
 
 /**
@@ -57,6 +58,7 @@ export function writeRelativeFiles(outDir, files) {
 function importedProjectConfig() {
   return {
     version: "0.1",
+    workspace: DEFAULT_WORKSPACE_PATH,
     outputs: {
       maintained_app: {
         path: "./app",
@@ -93,7 +95,7 @@ function importedWorkspaceReadme(sourceRoot, targetRoot, importSummary) {
     "```sh",
     "topogram import check",
     "topogram check",
-    "topogram query import-plan ./topogram",
+    `topogram query import-plan ./${DEFAULT_TOPO_FOLDER_NAME}`,
     "```",
     ""
   ].join("\n");
@@ -113,6 +115,7 @@ export function importCandidateCounts(summary) {
     uiScreens: candidates.ui?.screens?.length || 0,
     uiRoutes: candidates.ui?.routes?.length || 0,
     uiWidgets: candidates.ui?.widgets?.length || candidates.ui?.components?.length || 0,
+    uiShapes: candidates.ui?.shapes?.length || 0,
     workflows: candidates.workflows?.workflows?.length || 0,
     verifications: candidates.verification?.verifications?.length || 0
   };
@@ -155,7 +158,7 @@ export function buildBrownfieldImportWorkspacePayload(sourcePath, targetPath, op
   }
   ensureEmptyImportTarget(targetRoot);
 
-  const topogramRoot = path.join(targetRoot, "topogram");
+  const topogramRoot = path.join(targetRoot, DEFAULT_TOPO_FOLDER_NAME);
   fs.mkdirSync(topogramRoot, { recursive: true });
   const sourceFiles = collectImportSourceFileRecords(sourceRoot, { excludeRoots: [targetRoot] });
   const importResult = runWorkflow("import-app", sourceRoot, { from: options.from || null });
@@ -180,8 +183,8 @@ export function buildBrownfieldImportWorkspacePayload(sourcePath, targetPath, op
     "README.md",
     "topogram.project.json",
     TOPOGRAM_IMPORT_FILE,
-    ...rawCandidateFiles.map((filePath) => `topogram/${filePath}`),
-    ...reconcileFiles.map((filePath) => `topogram/${filePath}`)
+    ...rawCandidateFiles.map((filePath) => `${DEFAULT_TOPO_FOLDER_NAME}/${filePath}`),
+    ...reconcileFiles.map((filePath) => `${DEFAULT_TOPO_FOLDER_NAME}/${filePath}`)
   ].sort((a, b) => a.localeCompare(b));
   return {
     ok: true,
@@ -202,7 +205,7 @@ export function buildBrownfieldImportWorkspacePayload(sourcePath, targetPath, op
       "topogram import adopt bundle:task --dry-run",
       "topogram import status",
       "topogram check",
-      "topogram query import-plan ./topogram"
+      `topogram query import-plan ./${DEFAULT_TOPO_FOLDER_NAME}`
     ]
   };
 }