@topogram/cli 0.3.65 → 0.3.67

package/src/cli/commands/migrate.js

@@ -0,0 +1,153 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { stableStringify } from "../../format.js";
+import {
+  DEFAULT_TOPO_FOLDER_NAME,
+  DEFAULT_WORKSPACE_PATH,
+  LEGACY_TOPOGRAM_FOLDER_NAME,
+  PROJECT_CONFIG_FILE
+} from "../../workspace-paths.js";
+
+/**
+ * @param {string|null|undefined} inputPath
+ * @returns {string}
+ */
+function projectRootForMigration(inputPath) {
+  const absolute = path.resolve(inputPath || ".");
+  const base = path.basename(absolute);
+  if (base === DEFAULT_TOPO_FOLDER_NAME || base === LEGACY_TOPOGRAM_FOLDER_NAME) {
+    return path.dirname(absolute);
+  }
+  return absolute;
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {string[]}
+ */
+function caseCollisionEntries(projectRoot) {
+  if (!fs.existsSync(projectRoot) || !fs.statSync(projectRoot).isDirectory()) {
+    return [];
+  }
+  return fs.readdirSync(projectRoot)
+    .filter((/** @type {string} */ entry) => entry.toLowerCase() === DEFAULT_TOPO_FOLDER_NAME && entry !== DEFAULT_TOPO_FOLDER_NAME);
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {{ write: boolean, path: string|null, before: any|null, after: any|null }}
+ */
+function plannedProjectConfigUpdate(projectRoot) {
+  const configPath = path.join(projectRoot, PROJECT_CONFIG_FILE);
+  if (!fs.existsSync(configPath)) {
+    return { write: false, path: null, before: null, after: null };
+  }
+  const before = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  const after = { ...before };
+  const currentWorkspace = before.workspace;
+  if (currentWorkspace == null || currentWorkspace === "./topogram" || currentWorkspace === "topogram") {
+    after.workspace = DEFAULT_WORKSPACE_PATH;
+  }
+  return {
+    write: JSON.stringify(before) !== JSON.stringify(after),
+    path: configPath,
+    before,
+    after
+  };
+}
+
+/**
+ * @param {string|null|undefined} inputPath
+ * @param {{ write?: boolean, json?: boolean }} [options]
+ * @returns {number}
+ */
+export function runMigrateCommand(inputPath, options = {}) {
+  const projectRoot = projectRootForMigration(inputPath);
+  const legacyPath = path.join(projectRoot, LEGACY_TOPOGRAM_FOLDER_NAME);
+  const topoPath = path.join(projectRoot, DEFAULT_TOPO_FOLDER_NAME);
+  const write = Boolean(options.write);
+  /** @type {Array<Record<string, any>>} */
+  const diagnostics = [];
+  /** @type {Array<Record<string, any>>} */
+  const actions = [];
+
+  if (fs.existsSync(legacyPath) && fs.lstatSync(legacyPath).isSymbolicLink()) {
+    diagnostics.push({ severity: "error", message: `Refusing to migrate symlinked ${LEGACY_TOPOGRAM_FOLDER_NAME}/ at ${legacyPath}.` });
+  }
+  const collisions = caseCollisionEntries(projectRoot);
+  if (collisions.length > 0) {
+    diagnostics.push({ severity: "error", message: `Refusing to migrate because case-conflicting topo path(s) exist: ${collisions.join(", ")}.` });
+  }
+  if (fs.existsSync(legacyPath) && fs.existsSync(topoPath)) {
+    diagnostics.push({ severity: "error", message: `Refusing to migrate because both ${LEGACY_TOPOGRAM_FOLDER_NAME}/ and ${DEFAULT_TOPO_FOLDER_NAME}/ exist.` });
+  }
+  if (!fs.existsSync(legacyPath) && !fs.existsSync(topoPath)) {
+    diagnostics.push({ severity: "error", message: `No ${LEGACY_TOPOGRAM_FOLDER_NAME}/ or ${DEFAULT_TOPO_FOLDER_NAME}/ workspace folder found at ${projectRoot}.` });
+  }
+  if (fs.existsSync(topoPath) && fs.statSync(topoPath).isDirectory() && fs.readdirSync(topoPath).length > 0 && fs.existsSync(legacyPath)) {
+    diagnostics.push({ severity: "error", message: `Refusing to overwrite non-empty ${DEFAULT_TOPO_FOLDER_NAME}/ at ${topoPath}.` });
+  }
+
+  if (fs.existsSync(legacyPath) && diagnostics.length === 0) {
+    actions.push({
+      kind: "rename",
+      from: legacyPath,
+      to: topoPath
+    });
+  }
+  const configUpdate = plannedProjectConfigUpdate(projectRoot);
+  if (configUpdate.write) {
+    actions.push({
+      kind: "update_config",
+      path: configUpdate.path,
+      workspace: DEFAULT_WORKSPACE_PATH
+    });
+  }
+
+  const ok = diagnostics.filter((diagnostic) => diagnostic.severity === "error").length === 0;
+  if (ok && write) {
+    for (const action of actions) {
+      if (action.kind === "rename") {
+        fs.renameSync(action.from, action.to);
+      }
+      if (action.kind === "update_config" && configUpdate.path && configUpdate.after) {
+        fs.writeFileSync(configUpdate.path, `${JSON.stringify(configUpdate.after, null, 2)}\n`, "utf8");
+      }
+    }
+  }
+
+  const payload = {
+    ok,
+    dryRun: !write,
+    projectRoot,
+    legacyPath,
+    topoPath,
+    actions,
+    diagnostics,
+    errors: diagnostics.filter((diagnostic) => diagnostic.severity === "error").map((diagnostic) => diagnostic.message)
+  };
+  if (options.json) {
+    console.log(stableStringify(payload));
+  } else if (payload.ok) {
+    console.log(write ? "Workspace folder migration complete." : "Workspace folder migration dry run.");
+    if (actions.length === 0) {
+      console.log("No changes needed.");
+    }
+    for (const action of actions) {
+      if (action.kind === "rename") {
+        console.log(`Rename: ${action.from} -> ${action.to}`);
+      }
+      if (action.kind === "update_config") {
+        console.log(`Update ${action.path}: workspace ${DEFAULT_WORKSPACE_PATH}`);
+      }
+    }
+  } else {
+    for (const error of payload.errors) {
+      console.error(error);
+    }
+  }
+  return payload.ok ? 0 : 1;
+}

package/src/cli/commands/query/definitions.js

@@ -40,7 +40,7 @@ export function queryDefinitions() {
       selectors: ["capability", "workflow", "projection", "widget", "entity", "journey", "domain"],
       args: ["[path]", "[selectors]", "[--json]"],
       output: "context_slice",
-      example: "topogram query slice ./topogram --widget widget_data_grid"
+      example: "topogram query slice ./topo --widget widget_data_grid"
     },
     {
       name: "verification-targets",
@@ -49,7 +49,7 @@ export function queryDefinitions() {
       selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "from-topogram"],
       args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "verification_targets",
-      example: "topogram query verification-targets ./topogram --widget widget_data_grid"
+      example: "topogram query verification-targets ./topo --widget widget_data_grid"
     },
     {
       name: "widget-behavior",
@@ -58,7 +58,7 @@ export function queryDefinitions() {
       selectors: ["projection", "widget"],
       args: ["[path]", "[--projection <id>]", "[--widget <id>]", "[--json]"],
       output: "widget_behavior_report",
-      example: "topogram query widget-behavior ./topogram --projection proj_web_surface --widget widget_data_grid --json"
+      example: "topogram query widget-behavior ./topo --projection proj_web_surface --widget widget_data_grid --json"
     },
     {
       name: "change-plan",
@@ -67,7 +67,7 @@ export function queryDefinitions() {
       selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
       args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "change_plan_query",
-      example: "topogram query change-plan ./topogram --widget widget_data_grid"
+      example: "topogram query change-plan ./topo --widget widget_data_grid"
     },
     {
       name: "review-packet",
@@ -76,7 +76,7 @@ export function queryDefinitions() {
       selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
       args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "review_packet_query",
-      example: "topogram query review-packet ./topogram --widget widget_data_grid"
+      example: "topogram query review-packet ./topo --widget widget_data_grid"
     },
     {
       name: "resolved-workflow-context",
@@ -85,7 +85,7 @@ export function queryDefinitions() {
       selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "provider", "preset", "from-topogram"],
       args: ["[path]", "[--mode <id>]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "resolved_workflow_context_query",
-      example: "topogram query resolved-workflow-context ./topogram --mode modeling --widget widget_data_grid --json"
+      example: "topogram query resolved-workflow-context ./topo --mode modeling --widget widget_data_grid --json"
     },
     {
       name: "single-agent-plan",
@@ -94,7 +94,7 @@ export function queryDefinitions() {
       selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
       args: ["[path]", "[--mode <id>]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "single_agent_plan_query",
-      example: "topogram query single-agent-plan ./topogram --mode modeling --widget widget_data_grid --json"
+      example: "topogram query single-agent-plan ./topo --mode modeling --widget widget_data_grid --json"
     },
     {
       name: "risk-summary",
@@ -103,7 +103,7 @@ export function queryDefinitions() {
       selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
       args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "risk_summary_query",
-      example: "topogram query risk-summary ./topogram --widget widget_data_grid"
+      example: "topogram query risk-summary ./topo --widget widget_data_grid"
     },
     {
       name: "proceed-decision",
@@ -112,7 +112,7 @@ export function queryDefinitions() {
       selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
       args: ["[path]", "[--mode <id>]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "proceed_decision_query",
-      example: "topogram query proceed-decision ./topogram --mode verification"
+      example: "topogram query proceed-decision ./topo --mode verification"
     },
     {
       name: "write-scope",
@@ -121,7 +121,7 @@ export function queryDefinitions() {
       selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "from-topogram"],
       args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "write_scope_query",
-      example: "topogram query write-scope ./topogram --widget widget_data_grid"
+      example: "topogram query write-scope ./topo --widget widget_data_grid"
     }
   ];
 }

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

@@ -6,6 +6,7 @@ import path from "node:path";
 import { generateWorkspace } from "../../../generator.js";
 import { formatValidationErrors } from "../../../validator.js";
 import { buildChangePlanPayload } from "../../../agent-ops/query-builders.js";
+import { resolveTopoRoot } from "../../../workspace-paths.js";
 
 /**
  * @typedef {Record<string, any>} AnyRecord
@@ -16,12 +17,7 @@ import { buildChangePlanPayload } from "../../../agent-ops/query-builders.js";
  * @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);
 }
 
 /**

package/src/cli/commands/source.js

@@ -1,6 +1,5 @@
 // @ts-check
 
-import fs from "node:fs";
 import path from "node:path";
 
 import { stableStringify } from "../../format.js";
@@ -18,6 +17,7 @@ import {
   localTemplatePackageStatus
 } from "./package.js";
 import { buildTemplateOwnedBaselineStatus } from "./template.js";
+import { resolveTopoRoot, resolveWorkspaceContext } from "../../workspace-paths.js";
 
 /**
  * @typedef {Record<string, any>} AnyRecord
@@ -43,12 +43,7 @@ export function printSourceHelp() {
  * @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);
 }
 
 /**
@@ -56,11 +51,7 @@ 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/template/check.js

@@ -11,6 +11,7 @@ import {
   validateProjectConfig,
   validateProjectOutputOwnership
 } from "../../../project-config.js";
+import { resolveTopoRoot } from "../../../workspace-paths.js";
 import {
   buildTemplateUpdatePlan,
   createNewProject,
@@ -91,12 +92,12 @@ function diagnosticForTemplateCreateFailure(message, templateSpec, step) {
       step
     });
   }
-  if (message.includes("is missing topogram/")) {
+  if (message.includes("is missing topo/") || message.includes("is missing topogram/")) {
     return templateCheckDiagnostic({
       code: "template_topogram_missing",
       message,
-      path: localTemplatePath(templateSpec, "topogram"),
-      suggestedFix: "Add a topogram/ directory with the reusable Topogram source files.",
+      path: localTemplatePath(templateSpec, "topo"),
+      suggestedFix: "Add a topo/ directory with the reusable Topogram source files.",
       step
     });
   }
@@ -105,7 +106,7 @@ function diagnosticForTemplateCreateFailure(message, templateSpec, step) {
       code: "template_project_config_missing",
       message,
       path: localTemplatePath(templateSpec, "topogram.project.json"),
-      suggestedFix: "Add topogram.project.json beside topogram/ with outputs and topology.runtimes.",
+      suggestedFix: "Add topogram.project.json beside topo/ with outputs and topology.runtimes.",
       step
     });
   }
@@ -320,7 +321,7 @@ export function buildTemplateCheckPayload(templateSpec) {
     template: projectConfigInfo.config.template?.id || null
   }));
 
-  const ast = parsePath(path.join(projectRoot, "topogram"));
+  const ast = parsePath(resolveTopoRoot(projectRoot));
   const resolved = resolveWorkspace(ast);
   const projectValidation = combineProjectValidationResults(
     validateProjectConfig(projectConfigInfo.config, resolved.ok ? resolved.graph : null, { configDir: projectConfigInfo.configDir }),

package/src/cli/commands/template-runner.js

@@ -77,7 +77,7 @@ export function runTemplateCommand(context) {
   }
 
   if (command === "status") {
-    const projectConfigInfo = loadProjectConfig(inputPath || "./topogram");
+    const projectConfigInfo = loadProjectConfig(inputPath || "./topo");
     if (!projectConfigInfo) {
       throw new Error("Cannot inspect template status without topogram.project.json.");
     }
@@ -108,7 +108,7 @@ export function runTemplateCommand(context) {
   }
 
   if (command === "policy:init") {
-    const projectConfigInfo = loadProjectConfig(inputPath || "./topogram");
+    const projectConfigInfo = loadProjectConfig(inputPath || "./topo");
     if (!projectConfigInfo) {
       throw new Error("Cannot initialize template policy without topogram.project.json.");
     }
@@ -131,7 +131,7 @@ export function runTemplateCommand(context) {
   }
 
   if (command === "policy:check") {
-    const payload = buildTemplatePolicyCheckPayload(inputPath || "./topogram");
+    const payload = buildTemplatePolicyCheckPayload(inputPath || "./topo");
     if (json) {
       console.log(stableStringify(payload));
     } else {
@@ -141,7 +141,7 @@ export function runTemplateCommand(context) {
   }
 
   if (command === "policy:explain") {
-    const payload = buildTemplatePolicyExplainPayload(inputPath || "./topogram");
+    const payload = buildTemplatePolicyExplainPayload(inputPath || "./topo");
     if (json) {
       console.log(stableStringify(payload));
     } else {
@@ -151,7 +151,7 @@ export function runTemplateCommand(context) {
   }
 
   if (command === "policy:pin") {
-    const payload = buildTemplatePolicyPinPayload(inputPath || "./topogram", commandArgs.templatePolicyPinSpec);
+    const payload = buildTemplatePolicyPinPayload(inputPath || "./topo", commandArgs.templatePolicyPinSpec);
     if (json) {
       console.log(stableStringify(payload));
     } else {
@@ -178,7 +178,7 @@ export function runTemplateCommand(context) {
   if (command === "update") {
     const payload = buildTemplateUpdateCliPayload({
       args,
-      inputPath: inputPath || "./topogram",
+      inputPath: inputPath || "./topo",
       templateIndex: args.indexOf("--template"),
       templateName,
       useLatestTemplate: args.includes("--latest"),

package/src/cli/commands/trust.js

@@ -205,7 +205,7 @@ export function runTrustDiffCommand(inputPath, options = {}) {
  * @returns {number}
  */
 export function runTrustCommand(context) {
-  const inputPath = context.inputPath || "./topogram";
+  const inputPath = context.inputPath || "./topo";
   if (context.commandArgs.trustCommand === "template") {
     return runTrustTemplateCommand(inputPath, { force: Boolean(context.commandArgs.force) });
   }

package/src/cli/commands/workflow.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import { stableStringify } from "../../format.js";
 import { parsePath } from "../../parser.js";
 import { formatValidationErrors, validateWorkspace } from "../../validator.js";
+import { resolveTopoRoot } from "../../workspace-paths.js";
 import { runWorkflow } from "../../workflows.js";
 
 /**
@@ -13,7 +14,11 @@ import { runWorkflow } from "../../workflows.js";
  * @returns {number}
  */
 export function runValidateCommand(inputPath) {
-  const ast = parsePath(inputPath || ".");
+  const requestedPath = inputPath || ".";
+  const targetPath = fs.existsSync(requestedPath) && fs.statSync(requestedPath).isFile()
+    ? requestedPath
+    : resolveTopoRoot(requestedPath);
+  const ast = parsePath(targetPath);
   const result = validateWorkspace(ast);
   if (!result.ok) {
     console.error(formatValidationErrors(result));

package/src/cli/dispatcher.js

@@ -10,6 +10,7 @@ import { runGenerateAppCommand } from "./commands/generate.js";
 import { runGeneratorCommand } from "./commands/generator.js";
 import { runGeneratorPolicyCommand } from "./commands/generator-policy.js";
 import { runImportCommand } from "./commands/import-runner.js";
+import { runMigrateCommand } from "./commands/migrate.js";
 import { runNewProjectCommand } from "./commands/new.js";
 import { runPackageCommand } from "./commands/package.js";
 import { runParseCommand, runResolveCommand } from "./commands/inspect.js";
@@ -145,7 +146,7 @@ export async function runCliDispatch(context) {
     return 1;
   }
 
-  if ((shouldCheck || shouldWidgetCheck || shouldWidgetBehavior || shouldAgentBrief || shouldValidate || commandArgs?.generatorPolicyCommand || commandArgs?.trustCommand || generateTarget === "app-bundle") && inputPath) {
+  if ((shouldCheck || shouldWidgetCheck || shouldWidgetBehavior || shouldAgentBrief || shouldValidate || commandArgs?.generatorPolicyCommand || commandArgs?.trustCommand || commandArgs?.queryName || commandArgs?.workflowPresetCommand || generateTarget) && inputPath) {
     inputPath = normalizeTopogramPath(inputPath);
   }
   const effectiveInputPath = commandInputPath(inputPath);
@@ -241,6 +242,10 @@ export async function runCliDispatch(context) {
     return runPackageCommand({ commandArgs, inputPath, json: emitJson });
   }
 
+  if (commandArgs?.migrateCommand) {
+    return runMigrateCommand(inputPath, { write: shouldWrite, json: emitJson });
+  }
+
   if (commandArgs?.importCommand) {
     return runImportCommand({
       commandArgs,

package/src/cli/help.js

@@ -28,6 +28,7 @@ export function printUsage(options = {}) {
   console.log("   or: topogram catalog doctor [--json] [--catalog <path-or-source>]");
   console.log("   or: topogram catalog check <path-or-url> [--json]");
   console.log("   or: topogram catalog copy <id> <target> [--version <version>] [--json] [--catalog <path-or-source>]");
+  console.log("   or: topogram migrate workspace-folder [path] [--dry-run|--write] [--json]");
   console.log("   or: topogram package update-cli <version|--latest> [--json]");
   console.log("   or: topogram import <app-path> --out <target> [--from <track[,track]>] [--json]");
   console.log("   or: topogram import refresh [path] [--from <app-path>] [--dry-run] [--json]");
@@ -79,9 +80,9 @@ export function printUsage(options = {}) {
   console.log("  topogram agent brief --json");
   console.log("  topogram query list");
   console.log("  topogram query show widget-behavior");
-  console.log("  topogram query widget-behavior ./topogram --projection proj_web_surface --json");
+  console.log("  topogram query widget-behavior ./topo --projection proj_web_surface --json");
   console.log("  topogram emit ui-widget-contract --widget widget_data_grid --json");
-  console.log("  topogram emit widget-conformance-report ./topogram --projection proj_web_surface --json");
+  console.log("  topogram emit widget-conformance-report ./topo --projection proj_web_surface --json");
   console.log("  topogram generator list");
   console.log("  topogram generator show @topogram/generator-react-web");
   console.log("  topogram generator check ./generator-package");
@@ -136,7 +137,7 @@ export function printUsage(options = {}) {
   console.log("  topogram template update --check");
   console.log("  topogram template update --apply");
   console.log("");
-  console.log("Defaults: check/generate use ./topogram, and generate writes ./app.");
+  console.log("Defaults: check/generate use ./topo, and generate writes ./app.");
   console.log("Default starter: hello-web from the catalog. Run `topogram template list` for catalog aliases.");
   console.log("Generated app commands are emitted into the output package.json.");
   console.log("Run `topogram help <command>` for command-specific help.");
@@ -231,13 +232,13 @@ export function printGenerateHelp() {
   console.log("Usage: topogram generate [path] [--out <path>]");
   console.log("   or: topogram generate app [path] [--out <path>]");
   console.log("");
-  console.log("Defaults: path is ./topogram and app generation writes ./app.");
+  console.log("Defaults: path is ./topo and app generation writes ./app.");
   console.log("Use `topogram emit <target>` for contracts, reports, snapshots, migration plans, and other artifacts.");
   console.log("");
   console.log("Examples:");
   console.log("  topogram generate");
-  console.log("  topogram generate ./topogram --out ./app");
-  console.log("  topogram generate app ./topogram --out ./app");
+  console.log("  topogram generate ./topo --out ./app");
+  console.log("  topogram generate app ./topo --out ./app");
 }
 
 /**
@@ -249,7 +250,7 @@ export function printEmitHelp() {
   console.log("");
   console.log("Emits named contracts, reports, snapshots, migration plans, and other artifacts.");
   console.log("");
-  console.log("Defaults: path is ./topogram. Emit prints to stdout unless --write is passed. --write writes ./artifacts unless --out-dir is supplied.");
+  console.log("Defaults: path is ./topo. Emit prints to stdout unless --write is passed. --write writes ./artifacts unless --out-dir is supplied.");
   console.log("");
   console.log("Common artifact targets:");
   console.log("  ui-widget-contract");
@@ -268,10 +269,10 @@ export function printEmitHelp() {
   console.log("");
   console.log("Examples:");
   console.log("  topogram emit ui-widget-contract --widget widget_data_grid --json");
-  console.log("  topogram emit widget-conformance-report ./topogram --projection proj_web_surface --json");
-  console.log("  topogram emit widget-behavior-report ./topogram --projection proj_web_surface --json");
-  console.log("  topogram emit db-schema-snapshot ./topogram --projection proj_db_postgres --json");
-  console.log("  topogram emit sql-migration ./topogram --projection proj_db_postgres --from-snapshot ./state/current.json");
+  console.log("  topogram emit widget-conformance-report ./topo --projection proj_web_surface --json");
+  console.log("  topogram emit widget-behavior-report ./topo --projection proj_web_surface --json");
+  console.log("  topogram emit db-schema-snapshot ./topo --projection proj_db_postgres --json");
+  console.log("  topogram emit sql-migration ./topo --projection proj_db_postgres --from-snapshot ./state/current.json");
   console.log("  topogram emit ui-widget-contract --write --out-dir ./contracts");
 }
 
@@ -284,13 +285,13 @@ export function printWidgetHelp() {
   console.log("");
   console.log("Checks projection widget_bindings usage against reusable widget contracts and behavior realizations.");
   console.log("");
-  console.log("Defaults: path is ./topogram.");
+  console.log("Defaults: path is ./topo.");
   console.log("");
   console.log("Examples:");
   console.log("  topogram widget check");
   console.log("  topogram widget check --projection proj_web_surface");
-  console.log("  topogram widget check ./topogram --widget widget_data_grid --json");
+  console.log("  topogram widget check ./topo --widget widget_data_grid --json");
   console.log("  topogram widget behavior");
   console.log("  topogram widget behavior --projection proj_web_surface");
-  console.log("  topogram widget behavior ./topogram --widget widget_data_grid --json");
+  console.log("  topogram widget behavior ./topo --widget widget_data_grid --json");
 }

package/src/cli/migration-guidance.js

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

package/src/cli/output-safety.js

@@ -5,6 +5,7 @@ import os from "node:os";
 import path from "node:path";
 
 import { outputOwnershipForPath } from "../project-config.js";
+import { DEFAULT_TOPO_FOLDER_NAME } from "../workspace-paths.js";
 
 export const GENERATED_OUTPUT_SENTINEL = ".topogram-generated.json";
 
@@ -103,5 +104,5 @@ export function topogramInputPathForGeneration(inputPath) {
   if (isSameOrInside(REPO_ROOT, absolute)) {
     return `./${path.relative(REPO_ROOT, absolute).replace(/\\/g, "/")}`;
   }
-  return path.basename(absolute) === "topogram" ? "./topogram" : ".";
+  return path.basename(absolute) === DEFAULT_TOPO_FOLDER_NAME ? `./${DEFAULT_TOPO_FOLDER_NAME}` : ".";
 }

package/src/cli/path-normalization.js

@@ -1,19 +1,13 @@
 // @ts-check
 
-import fs from "node:fs";
-import path from "node:path";
+import { resolveTopoRoot, resolveWorkspaceContext } from "../workspace-paths.js";
 
 /**
  * @param {string} inputPath
  * @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);
 }
 
 /**
@@ -21,9 +15,5 @@ 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/generator/context/domain-page.js

@@ -118,7 +118,7 @@ export function generateDomainPage(graph, options = {}) {
     version: 1,
     focus: { kind: "domain", id: domain.id },
     output: {
-      path: `topogram/docs-generated/domains/${domain.id}.md`,
+      path: `topo/docs-generated/domains/${domain.id}.md`,
       contents: lines.join("\n") + "\n"
     },
     summary

package/src/generator/context/shared/maintained-boundary.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { resolveWorkspaceContext } from "../../../workspace-paths.js";
 
 import { parseDocFile } from "../../../workspace-docs.js";
 import {
@@ -49,8 +50,7 @@ export function relativePathFromGraph(graph, targetPath) {
  * @returns {any}
  */
 function workspaceRootFromGraph(graph) {
-  const root = path.resolve(graph.root);
-  return path.basename(root) === "topogram" ? path.dirname(root) : root;
+  return resolveWorkspaceContext(graph.root).projectRoot;
 }
 
 /**

package/src/generator/context/shared/metrics.js

@@ -34,7 +34,7 @@ export function percentOf(part, whole) {
  */
 export function buildDefaultWriteScope() {
   return {
-    safe_to_edit: ["topogram/**", "candidates/**"],
+    safe_to_edit: ["topo/**", "candidates/**"],
     generator_owned: ["artifacts/**", "apps/**"],
     human_owned_review_required: ["examples/maintained/proof-app/**"],
     out_of_bounds: [".git/**", "node_modules/**"]
@@ -54,7 +54,7 @@ export function buildMaintainedWriteScope(graph, maintainedFiles = []) {
       ...maintainedFiles,
       "examples/maintained/proof-app/**"
     ]),
-    out_of_bounds: ["topogram/**"]
+    out_of_bounds: ["topo/**"]
   };
 }