@topogram/cli 0.3.65 → 0.3.67

package/src/generator/context/task-mode.js

@@ -338,7 +338,7 @@ function importAdoptMode(graph, options = {}) {
     write_scope: {
       safe_to_edit: ["candidates/**"],
       generator_owned: ["artifacts/**", "apps/**"],
-      human_owned_review_required: ["topogram/**"],
+      human_owned_review_required: ["topo/**"],
       out_of_bounds: [".git/**", "node_modules/**"]
     },
     verification_targets: {
@@ -384,7 +384,7 @@ function diffReviewMode(graph, options = {}) {
     write_scope: {
       safe_to_edit: [],
       generator_owned: ["artifacts/**", "apps/**"],
-      human_owned_review_required: ["topogram/**", "examples/maintained/proof-app/**"],
+      human_owned_review_required: ["topo/**", "examples/maintained/proof-app/**"],
       out_of_bounds: [".git/**", "node_modules/**"]
     },
     verification_targets: slice?.verification_targets || recommendedVerificationTargets(graph, [], {

package/src/generator/sdlc/doc-page.js

@@ -47,7 +47,7 @@ export function generateSdlcDocPage(graph, options = {}) {
     type: "sdlc_doc_page",
     version: 1,
     document_id: doc.id,
-    output_path: `topogram/docs-generated/sdlc/${doc.id}.md`,
+    output_path: `topo/docs-generated/sdlc/${doc.id}.md`,
     markdown
   };
 }

package/src/generator/surfaces/databases/lifecycle-shared.js

@@ -99,7 +99,7 @@ function renderEmptySnapshotForProjection(projection) {
 
 function renderDbLifecycleEnvExample(projection, plan) {
   const engine = plan.engine || (dbProfileForProjection(projection).startsWith("sqlite") ? "sqlite" : "postgres");
-  const inputPath = "../../../../topogram";
+  const inputPath = "../../../../topo";
   if (engine === "sqlite") {
     return `DATABASE_URL=file:./var/${projection.id}.sqlite\nTOPOGRAM_INPUT_PATH=${inputPath}\n`;
   }

package/src/generator/surfaces/native/swiftui-templates/README.generated.md

@@ -22,5 +22,5 @@ Configure the API base URL and optional auth token via scheme environment variab
 From `engine/`:
 
 ```bash
-topogram emit swiftui-app ./topogram --projection proj_ios_surface__swiftui --write --out-dir ./app/ios-swiftui
+topogram emit swiftui-app ./topo --projection proj_ios_surface__swiftui --write --out-dir ./app/ios-swiftui
 ```

package/src/import/core/context.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { readJsonIfExists, readTextIfExists } from "./shared.js";
+import { resolveWorkspaceContext } from "../../workspace-paths.js";
 
 export function findNearestGitRoot(startDir) {
   let currentDir = path.resolve(startDir);
@@ -19,13 +20,10 @@ export function findNearestGitRoot(startDir) {
 }
 
 export function normalizeWorkspacePaths(inputPath) {
+  const context = resolveWorkspaceContext(inputPath);
   const absolute = path.resolve(inputPath);
-  const inputExists = fs.existsSync(absolute);
-  const topogramChild = path.join(absolute, "topogram");
-  const hasTopogramChild = fs.existsSync(topogramChild) && fs.statSync(topogramChild).isDirectory();
-  const isTopogramDir = path.basename(absolute) === "topogram" && inputExists;
-  const topogramRoot = isTopogramDir ? absolute : hasTopogramChild ? topogramChild : path.join(absolute, "topogram");
-  const workspaceRoot = isTopogramDir ? path.dirname(topogramRoot) : absolute;
+  const topogramRoot = context.topoRoot;
+  const workspaceRoot = context.projectRoot;
   const repoRoot = findNearestGitRoot(workspaceRoot);
   return {
     inputRoot: absolute,
@@ -33,7 +31,7 @@ export function normalizeWorkspacePaths(inputPath) {
     workspaceRoot,
     exampleRoot: workspaceRoot,
     repoRoot,
-    bootstrappedTopogramRoot: !fs.existsSync(topogramRoot)
+    bootstrappedTopogramRoot: context.bootstrappedTopoRoot
   };
 }
 

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

@@ -47,6 +47,119 @@ export function capabilityHintsForScreen(screen) {
   return rawHints.map(normalizeCapabilityHint).filter(Boolean);
 }
 
+/**
+ * @param {string|null|undefined} screenId
+ * @returns {string}
+ */
+function screenConceptStem(screenId) {
+  return String(screenId || "")
+    .replace(/_(list|index|table|grid|results|detail|show|create|new|edit|form)$/, "")
+    .replace(/^(list|show|create|edit)_/, "");
+}
+
+/**
+ * @param {string|null|undefined} screenId
+ * @param {string} eventName
+ * @returns {string}
+ */
+function eventPayloadShapeId(screenId, eventName) {
+  const stem = screenConceptStem(screenId) || idHintify(String(screenId || "widget"));
+  return `shape_event_${idHintify(`${stem}_${eventName}`)}`;
+}
+
+/**
+ * @param {string|null|undefined} routePath
+ * @returns {{ name: string, field_type: string, required: boolean }[]}
+ */
+function routeParamFields(routePath) {
+  const fields = [];
+  const pathText = String(routePath || "");
+  const routeParamPattern = /[:{]([A-Za-z_][A-Za-z0-9_]*)}?/g;
+  for (const match of pathText.matchAll(routeParamPattern)) {
+    fields.push({
+      name: idHintify(match[1]),
+      field_type: "string",
+      required: true
+    });
+  }
+  return fields.length > 0 ? fields : [{ name: "id", field_type: "string", required: true }];
+}
+
+/**
+ * @param {any} sourceScreen
+ * @param {any[]} screens
+ * @returns {any|null}
+ */
+function matchingDetailScreen(sourceScreen, screens) {
+  const sourceStem = screenConceptStem(sourceScreen?.id_hint);
+  if (!sourceStem) {
+    return null;
+  }
+  return screens.find((screen) =>
+    screen?.id_hint !== sourceScreen?.id_hint &&
+    screen?.screen_kind === "detail" &&
+    screenConceptStem(screen.id_hint) === sourceStem
+  ) || null;
+}
+
+/**
+ * @param {any} screen
+ * @param {any[]} screens
+ * @returns {any[]}
+ */
+function inferredEventsForWidgetScreen(screen, screens) {
+  const detailScreen = matchingDetailScreen(screen, screens);
+  if (!detailScreen) {
+    return [];
+  }
+  return [{
+    name: "row_select",
+    kind: "selection",
+    action: "navigate",
+    target_screen: detailScreen.id_hint,
+    payload_shape: eventPayloadShapeId(screen?.id_hint, "row_select"),
+    confidence: "medium",
+    evidence: detailScreen.provenance || [],
+    payload_fields: routeParamFields(detailScreen.route_path),
+    requires_payload_shape_review: true
+  }];
+}
+
+/**
+ * @param {any[]} widgets
+ * @returns {any[]}
+ */
+function deriveUiWidgetEventShapeCandidates(widgets) {
+  return widgets.flatMap((widget) =>
+    (widget.inferred_events || [])
+      .filter((/** @type {any} */ event) => event.payload_shape)
+      .map((/** @type {any} */ event) => makeCandidateRecord({
+        kind: "shape",
+        idHint: event.payload_shape,
+        label: `${widget.label || widget.id_hint} ${event.name || "event"} payload`,
+        confidence: event.confidence || widget.confidence || "low",
+        sourceKind: "ui_widget_event",
+        sourceOfTruth: "candidate",
+        provenance: [
+          ...(widget.provenance || []),
+          ...(event.evidence || [])
+        ],
+        track: "ui",
+        widget_id: widget.id_hint,
+        event_name: event.name,
+        fields: event.payload_fields || [{ name: "id", field_type: "string", required: true }],
+        missing_decisions: [
+          "confirm selected row identity fields",
+          "confirm event payload shape name"
+        ],
+        notes: [
+          "Imported widget event payload shapes are review-only.",
+          "Adopt with the widget when the event binding is accepted."
+        ]
+      }))
+  );
+}
+
 /**
  * @param {any} candidates
  * @returns {any[]}
@@ -95,6 +208,7 @@ function deriveUiWidgetCandidates(candidates) {
     const pattern = collectionPatternFromPresentations(presentations);
     const widgetStem = idHintify(`${screen.id_hint}_results`);
     const loadCapability = loadCapabilityForScreen(screen);
+    const inferredEvents = inferredEventsForWidgetScreen(screen, screens);
     return makeCandidateRecord({
       kind: "widget",
       idHint: `widget_${widgetStem}`,
@@ -109,10 +223,13 @@ function deriveUiWidgetCandidates(candidates) {
       data_prop: "rows",
       data_source: loadCapability,
       inferred_props: [{ name: "rows", type: "array", required: true, source: loadCapability }],
-      inferred_events: [],
+      inferred_events: inferredEvents,
       inferred_region: "results",
       inferred_pattern: pattern,
-      evidence: screen.provenance || [],
+      evidence: [
+        ...(screen.provenance || []),
+        ...inferredEvents.flatMap((event) => event.evidence || [])
+      ],
       missing_decisions: [
         "confirm widget reuse boundary",
         "confirm prop names and data source",
@@ -160,11 +277,14 @@ export function normalizeCandidatesForTrack(track, candidates) {
   if (track === "ui") {
     const explicitWidgets = uiWidgetCandidates(candidates);
     const derivedWidgets = deriveUiWidgetCandidates(candidates);
+    const widgets = dedupeCandidateRecords([...explicitWidgets, ...derivedWidgets], idHint);
+    const eventShapes = deriveUiWidgetEventShapeCandidates(widgets);
     return {
       screens: dedupeCandidateRecords(candidates.screens || [], idHint),
       routes: dedupeCandidateRecords(candidates.routes || [], idHint),
       actions: dedupeCandidateRecords(candidates.actions || [], idHint),
-      widgets: dedupeCandidateRecords([...explicitWidgets, ...derivedWidgets], idHint),
+      widgets,
+      shapes: dedupeCandidateRecords([...(candidates.shapes || []), ...eventShapes], idHint),
       stacks: [...new Set(candidates.stacks || [])].sort()
     };
   }

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

@@ -21,11 +21,12 @@ export function reportMarkdown(track, candidates) {
   }
   if (track === "ui") {
     const widgets = uiWidgetCandidates(candidates);
+    const shapes = candidates.shapes || [];
     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"}\` evidence ${(widget.evidence || widget.provenance || []).length} missing decisions ${(widget.missing_decisions || []).length}`
+      `- \`${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}`
     );
     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- 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 \`topogram/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- 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`
     );
   }
   if (track === "verification") {
@@ -45,6 +46,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\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- Stacks: ${candidates.ui?.stacks?.length ? candidates.ui.stacks.join(", ") : "none"}\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\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## 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/ui-drafts.js

@@ -49,22 +49,73 @@ function renderWidgetCandidate(widget) {
     "confirm prop names and data source",
     "confirm events and behavior"
   ];
+  const inferredEvents = Array.isArray(widget.inferred_events) ? widget.inferred_events : [];
+  const eventLines = inferredEvents
+    .filter((/** @type {any} */ event) => event.name && event.payload_shape)
+    .map((/** @type {any} */ event) => `    ${event.name} ${event.payload_shape}`);
+  const selectionEvent = inferredEvents.find((/** @type {any} */ event) => event.name);
+  const inferredEventComments = inferredEvents.length > 0
+    ? `${inferredEvents.map((/** @type {any} */ event) =>
+        `  # Inferred event: ${event.name || "event"} ${event.action || "action"} ${event.target_screen || event.target || "target"}; review payload shape ${event.payload_shape || "before adding an events block"}.`
+      ).join("\n")}\n`
+    : "";
+  const behaviorBlock = eventLines.length > 0
+    ? `  events {\n${eventLines.join("\n")}\n  }\n  behavior [selection]\n  behaviors {\n    selection mode single emits ${selectionEvent?.name || "row_select"}\n  }\n`
+    : "";
   return `widget ${widget.id_hint} {
   # Import metadata: confidence ${widget.confidence || "unknown"}; evidence ${evidenceCount}; inferred pattern ${widget.pattern || widget.inferred_pattern || "search_results"}; inferred region ${widget.region || widget.inferred_region || "results"}.
   # Missing decisions: ${missingDecisions.join("; ")}.
+${inferredEventComments}  # Event declarations are draft bindings and require payload shape review before adoption.
   name "${widget.label || widget.id_hint}"
   description "Candidate reusable widget inferred from imported UI evidence. Review props, behavior, events, and reuse before adoption."
   category collection
   props {
     ${widget.data_prop || "rows"} array required
   }
-  patterns [${widget.pattern || "search_results"}]
+${behaviorBlock}  patterns [${widget.pattern || "search_results"}]
   regions [${widget.region || "results"}]
   status proposed
 }
 `;
 }
 
+/**
+ * @param {any} shape
+ * @returns {string}
+ */
+function renderShapeCandidate(shape) {
+  const fields = Array.isArray(shape.fields) && shape.fields.length > 0
+    ? shape.fields
+    : [{ name: "id", field_type: "string", required: true }];
+  return `shape ${shape.id_hint} {
+  # Import metadata: confidence ${shape.confidence || "unknown"}; source ${shape.source_kind || "unknown"}.
+  # Missing decisions: ${(shape.missing_decisions || ["confirm event payload fields"]).join("; ")}.
+  name "${shape.label || shape.id_hint}"
+  description "Candidate event payload shape inferred from imported UI interaction evidence."
+  fields {
+${fields.map((/** @type {any} */ field) => {
+    const fieldName = typeof field === "string" ? field : field.name;
+    const fieldType = typeof field === "string" ? "string" : (field.field_type || field.type || "string");
+    const requiredness = typeof field === "string" || field.required ? "required" : "optional";
+    return `    ${fieldName} ${fieldType} ${requiredness}`;
+  }).join("\n")}
+  }
+  status proposed
+}
+`;
+}
+
+/**
+ * @param {any} widget
+ * @returns {string}
+ */
+function widgetEventDirectives(widget) {
+  return (widget.inferred_events || [])
+    .filter((/** @type {any} */ event) => event.name && event.action && (event.target_screen || event.target) && event.payload_shape)
+    .map((/** @type {any} */ event) => ` event ${event.name} ${event.action} ${event.target_screen || event.target}`)
+    .join("");
+}
+
 /**
  * @param {any[]} widgetCandidates
  * @param {Record<string, any>} allCandidates
@@ -78,7 +129,7 @@ function uiWidgetLinesForCandidates(widgetCandidates, allCandidates) {
       const dataBinding = dataSource
         ? ` data ${widget.data_prop || "rows"} from ${dataSource}`
         : "";
-      return `    screen ${widget.screen_id} region ${widget.region} widget ${widget.id_hint}${dataBinding}`;
+      return `    screen ${widget.screen_id} region ${widget.region} widget ${widget.id_hint}${dataBinding}${widgetEventDirectives(widget)}`;
     });
 }
 
@@ -99,6 +150,7 @@ export function draftUiProjectionFiles(context, candidates, allCandidates = {})
   /** @type {any[]} */
   const actions = ui.actions || [];
   const widgetCandidates = [...uiWidgetCandidates(ui)].sort((a, b) => a.id_hint.localeCompare(b.id_hint));
+  const shapeCandidates = [...(ui.shapes || [])].sort((a, b) => String(a.id_hint || "").localeCompare(String(b.id_hint || "")));
   const shell = actions.find((entry) => entry.kind === "ui_shell")?.shell_kind || "topbar";
   const navigationPatterns = uniqueSorted(actions.filter((entry) => entry.kind === "navigation").map((entry) => entry.navigation_pattern));
   const presentations = uniqueSorted(actions.filter((entry) => entry.kind === "ui_presentation").map((entry) => entry.presentation));
@@ -308,6 +360,7 @@ ${uiWebLines.length > 0 ? `  web_hints {\n${uiWebLines.join("\n")}\n  }\n\n` : "
 - Draft UI contract projection: \`candidates/app/ui/drafts/proj-ui-contract.tg\`
 - Draft web surface projection: \`candidates/app/ui/drafts/proj-web-surface.tg\`
 - Draft widget candidates: ${widgetCandidates.length}
+- Draft event payload shape candidates: ${shapeCandidates.length}
 - Imported screens: ${screens.length}
 - Imported routes: ${(ui.routes || []).length}
 - Imported UI actions/presentations: ${actions.length}
@@ -330,6 +383,9 @@ ${uiWebLines.length > 0 ? `  web_hints {\n${uiWebLines.join("\n")}\n  }\n\n` : "
     "candidates/app/ui/drafts/proj-web-surface.tg": ensureTrailingNewline(uiWebDraft),
     "candidates/app/ui/drafts/README.md": ensureTrailingNewline(coverage)
   };
+  for (const shape of shapeCandidates) {
+    files[`candidates/app/ui/drafts/shapes/${widgetCandidateFileName(shape)}`] = ensureTrailingNewline(renderShapeCandidate(shape));
+  }
   for (const widget of widgetCandidates) {
     files[`candidates/app/ui/drafts/widgets/${widgetCandidateFileName(widget)}`] = ensureTrailingNewline(renderWidgetCandidate(widget));
   }

package/src/new-project/constants.js

@@ -31,7 +31,7 @@ export const SURFACE_ORDER = new Map([
  * @returns {string}
  */
 export function unsupportedTemplateSymlinkMessage(templateId, relativePath) {
-  return `Template '${templateId}' contains unsupported symlink '${relativePath}'. Template packs must copy real files because Topogram records hashes for copied topogram/ and implementation/ content; symlinks can point outside the trusted template root. Replace the symlink with a real file or directory before running topogram new or topogram template check.`;
+  return `Template '${templateId}' contains unsupported symlink '${relativePath}'. Template packs must copy real files because Topogram records hashes for copied workspace and implementation/ content; symlinks can point outside the trusted template root. Replace the symlink with a real file or directory before running topogram new or topogram template check.`;
 }
 
 /**

package/src/new-project/create.js

@@ -4,6 +4,7 @@ import path from "node:path";
 
 import { defaultGeneratorPolicy, writeGeneratorPolicy } from "../generator-policy.js";
 import { writeTemplateTrustRecord } from "../template-trust.js";
+import { DEFAULT_TOPO_FOLDER_NAME } from "../workspace-paths.js";
 import { DEFAULT_TEMPLATE_NAME } from "./constants.js";
 import { writeProjectTemplateMetadata } from "./metadata.js";
 import { assertProjectOutsideEngine, copyTopogramWorkspace, ensureCreatableProjectRoot, writeAgentsGuide, writeExplainScript, writeProjectPackage, writeProjectReadme } from "./project-files.js";
@@ -52,7 +53,7 @@ export function createNewProject({
   }
 
   ensureCreatableProjectRoot(projectRoot);
-  copyTopogramWorkspace(template.root, projectRoot);
+  const workspaceCopy = copyTopogramWorkspace(template.root, projectRoot);
   const projectConfig = writeProjectTemplateMetadata(projectRoot, template, templateProvenance);
   writeProjectPackage(projectRoot, engineRoot, template);
   writeExplainScript(projectRoot);
@@ -63,6 +64,12 @@ export function createNewProject({
   writeGeneratorPolicy(projectRoot, defaultGeneratorPolicy());
 
   const warnings = [];
+  if (workspaceCopy.legacyWorkspace) {
+    warnings.push(
+      `Template '${template.manifest.id}' still ships legacy topogram/ source. Copied it into this project as ${DEFAULT_TOPO_FOLDER_NAME}/. ` +
+        "This one-release package-ingress bridge will be removed after first-party packages migrate."
+    );
+  }
   if (template.manifest.includesExecutableImplementation) {
     writeTemplateTrustRecord(projectRoot, projectConfig);
     warnings.push(
@@ -76,7 +83,7 @@ export function createNewProject({
     projectRoot,
     templateName: template.manifest.id,
     template: projectConfig.template,
-    topogramPath: path.join(projectRoot, "topogram"),
+    topogramPath: path.join(projectRoot, DEFAULT_TOPO_FOLDER_NAME),
     appPath: path.join(projectRoot, "app"),
     warnings
   };

package/src/new-project/project-files.js

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { githubRepoSlug } from "../topogram-config.js";
+import { DEFAULT_TOPO_FOLDER_NAME, DEFAULT_WORKSPACE_PATH, resolvePackageWorkspace } from "../workspace-paths.js";
 import { cliDependencyForProject, generatorDependenciesForTemplate, isSameOrInside, packageNameFromPath, writeProjectNpmConfig } from "./package-spec.js";
 
 /** @typedef {import("./types.js").CreateNewProjectOptions} CreateNewProjectOptions */
@@ -54,16 +55,17 @@ export function ensureCreatableProjectRoot(projectRoot) {
 /**
  * @param {string} templateRoot
  * @param {string} projectRoot
- * @returns {void}
+ * @returns {{ legacyWorkspace: boolean }}
  */
 export function copyTopogramWorkspace(templateRoot, projectRoot) {
-  const topogramRoot = path.join(projectRoot, "topogram");
-  fs.cpSync(path.join(templateRoot, "topogram"), topogramRoot, { recursive: true });
-
-  fs.cpSync(
-    path.join(templateRoot, "topogram.project.json"),
-    path.join(projectRoot, "topogram.project.json")
-  );
+  const templateWorkspace = resolvePackageWorkspace(templateRoot);
+  const topoRoot = path.join(projectRoot, DEFAULT_TOPO_FOLDER_NAME);
+  fs.cpSync(templateWorkspace.root, topoRoot, { recursive: true });
+
+  const projectConfigPath = path.join(templateRoot, "topogram.project.json");
+  const projectConfig = JSON.parse(fs.readFileSync(projectConfigPath, "utf8"));
+  projectConfig.workspace = DEFAULT_WORKSPACE_PATH;
+  fs.writeFileSync(path.join(projectRoot, "topogram.project.json"), `${JSON.stringify(projectConfig, null, 2)}\n`, "utf8");
   const implementationRoot = path.join(templateRoot, "implementation");
   if (fs.existsSync(implementationRoot)) {
     fs.cpSync(
@@ -72,6 +74,7 @@ export function copyTopogramWorkspace(templateRoot, projectRoot) {
       { recursive: true }
     );
   }
+  return { legacyWorkspace: templateWorkspace.legacy };
 }
 
 /**
@@ -148,7 +151,7 @@ export function writeExplainScript(projectRoot) {
 Topogram app workflow
 
 1. Edit:
-   topogram/
+   topo/
    topogram.project.json
 
 2. Start with project guidance:
@@ -179,8 +182,8 @@ Or run self-contained local runtime verification:
 Useful inspection:
    npm run agent:brief
    npm run check:json
-   topogram emit ui-widget-contract ./topogram --json
-   topogram emit widget-conformance-report ./topogram --json
+   topogram emit ui-widget-contract ./topo --json
+   topogram emit widget-conformance-report ./topo --json
    npm run doctor
    npm run source:status
    npm run source:status:remote
@@ -257,7 +260,7 @@ ${provenanceLines.join("\n")}
 ${workflowCommands.join("\n")}
 \`\`\`
 
-Edit \`topogram/\` and \`topogram.project.json\`, then regenerate with \`npm run generate\`.
+Edit the workspace folder \`${DEFAULT_TOPO_FOLDER_NAME}/\` and \`topogram.project.json\`, then regenerate with \`npm run generate\`.
 Generated app code is written to \`app/\`.
 Use \`topogram emit <target>\` to inspect contracts, reports, snapshots, and other artifacts without regenerating the app.
 Agents should start with \`AGENTS.md\` and \`npm run agent:brief\`. The direct \`topogram agent brief --json\` command is the canonical machine-readable first-run guidance.
@@ -315,7 +318,7 @@ npm run query:show -- widget-behavior
 
 ## Edit Rules
 
-- Edit \`topogram/**\` and \`topogram.project.json\` first.
+- Edit \`topo/**\` and \`topogram.project.json\` first.
 - Review policy files before editing \`topogram.template-policy.json\` or \`topogram.generator-policy.json\`.
 - Do not make lasting edits under generated-owned \`app/**\`; use \`npm run generate\` to replace generated output.
 - If an output is changed to maintained ownership, agents may edit that app code directly after reading focused query packets.

package/src/new-project/template-resolution.js

@@ -6,6 +6,7 @@ import os from "node:os";
 import path from "node:path";
 
 import { assertSafeNpmSpec, localNpmrcEnv } from "../npm-safety.js";
+import { DEFAULT_TOPO_FOLDER_NAME, LEGACY_TOPOGRAM_FOLDER_NAME, resolvePackageWorkspace } from "../workspace-paths.js";
 import { GENERATOR_LABELS, SURFACE_ORDER, TEMPLATE_MANIFEST, unsupportedTemplateSymlinkMessage } from "./constants.js";
 import { isLocalTemplateSpec, packageNameFromSpec } from "./package-spec.js";
 
@@ -106,21 +107,22 @@ function assertTemplateTreeHasNoSymlinks(root, currentDir, label, templateId) {
  */
 export function validateTemplateRoot(templateRoot) {
   const manifest = readTemplateManifest(templateRoot);
-  const topogramRoot = path.join(templateRoot, "topogram");
+  const workspace = resolvePackageWorkspace(templateRoot);
+  const topogramRoot = workspace.root;
   const projectConfigPath = path.join(templateRoot, "topogram.project.json");
   if (fs.existsSync(topogramRoot) && fs.lstatSync(topogramRoot).isSymbolicLink()) {
-    throw new Error(unsupportedTemplateSymlinkMessage(manifest.id, "topogram"));
+    throw new Error(unsupportedTemplateSymlinkMessage(manifest.id, workspace.legacy ? LEGACY_TOPOGRAM_FOLDER_NAME : DEFAULT_TOPO_FOLDER_NAME));
   }
   if (fs.existsSync(projectConfigPath) && fs.lstatSync(projectConfigPath).isSymbolicLink()) {
     throw new Error(unsupportedTemplateSymlinkMessage(manifest.id, "topogram.project.json"));
   }
   if (!fs.existsSync(topogramRoot) || !fs.statSync(topogramRoot).isDirectory()) {
-    throw new Error(`Template '${manifest.id}' is missing topogram/.`);
+    throw new Error(`Template '${manifest.id}' is missing ${DEFAULT_TOPO_FOLDER_NAME}/.`);
   }
   if (!fs.existsSync(projectConfigPath) || !fs.statSync(projectConfigPath).isFile()) {
     throw new Error(`Template '${manifest.id}' is missing topogram.project.json.`);
   }
-  assertTemplateTreeHasNoSymlinks(templateRoot, topogramRoot, "topogram", manifest.id);
+  assertTemplateTreeHasNoSymlinks(templateRoot, topogramRoot, workspace.legacy ? LEGACY_TOPOGRAM_FOLDER_NAME : DEFAULT_TOPO_FOLDER_NAME, manifest.id);
   if (manifest.includesExecutableImplementation) {
     const implementationRoot = path.join(templateRoot, "implementation");
     if (fs.existsSync(implementationRoot) && fs.lstatSync(implementationRoot).isSymbolicLink()) {

package/src/new-project/template-snapshots.js

@@ -7,6 +7,7 @@ import path from "node:path";
 import { MAX_TEXT_DIFF_BYTES, TEMPLATE_FILES_MANIFEST } from "./constants.js";
 import { stableJsonStringify } from "./json.js";
 import { candidateProjectTemplateMetadata } from "./metadata.js";
+import { DEFAULT_TOPO_FOLDER_NAME, resolvePackageWorkspace } from "../workspace-paths.js";
 
 /** @typedef {import("./types.js").CreateNewProjectOptions} CreateNewProjectOptions */
 /** @typedef {import("./types.js").TemplateUpdatePlanOptions} TemplateUpdatePlanOptions */
@@ -235,6 +236,24 @@ export function fileHash(file) {
   };
 }
 
+/**
+ * @param {string} relativePath
+ * @param {{ absolutePath: string|null, content: string|null }} file
+ * @returns {{ sha256: string, size: number }}
+ */
+function templateOwnedFileHash(relativePath, file) {
+  if (relativePath !== "topogram.project.json" || file.content !== null) {
+    return fileHash(file);
+  }
+  if (!file.absolutePath) {
+    return fileHash(file);
+  }
+  return fileHash({
+    absolutePath: null,
+    content: `${stableJsonStringify(JSON.parse(fs.readFileSync(file.absolutePath, "utf8")))}\n`
+  });
+}
+
 /**
  * @param {ResolvedTemplate} template
  * @param {Record<string, any>|null} [currentProjectConfig]
@@ -242,14 +261,24 @@ export function fileHash(file) {
  */
 export function candidateTemplateFiles(template, currentProjectConfig = null) {
   const files = new Map();
-  for (const rootName of ["topogram", "implementation"]) {
-    const root = path.join(template.root, rootName);
-    if (!fs.existsSync(root)) {
-      continue;
-    }
+  const templateWorkspace = resolvePackageWorkspace(template.root);
+  /** @type {string[]} */
+  const workspaceFiles = [];
+  collectFiles(template.root, templateWorkspace.root, workspaceFiles);
+  for (const sourceRelativePath of workspaceFiles) {
+    const workspaceRelative = path.relative(templateWorkspace.root, path.join(template.root, sourceRelativePath)).replace(/\\/g, "/");
+    const targetRelativePath = path.posix.join(DEFAULT_TOPO_FOLDER_NAME, workspaceRelative);
+    files.set(targetRelativePath, {
+      path: targetRelativePath,
+      content: null,
+      absolutePath: path.join(template.root, sourceRelativePath)
+    });
+  }
+  const implementationRoot = path.join(template.root, "implementation");
+  if (fs.existsSync(implementationRoot)) {
     /** @type {string[]} */
     const relativeFiles = [];
-    collectFiles(template.root, root, relativeFiles);
+    collectFiles(template.root, implementationRoot, relativeFiles);
     for (const relativePath of relativeFiles) {
       files.set(relativePath, {
         path: relativePath,
@@ -259,6 +288,7 @@ export function candidateTemplateFiles(template, currentProjectConfig = null) {
     }
   }
   const candidateProjectConfig = JSON.parse(fs.readFileSync(path.join(template.root, "topogram.project.json"), "utf8"));
+  candidateProjectConfig.workspace = `./${DEFAULT_TOPO_FOLDER_NAME}`;
   candidateProjectConfig.template = candidateProjectTemplateMetadata(template, currentProjectConfig);
   files.set("topogram.project.json", {
     path: "topogram.project.json",
@@ -276,7 +306,7 @@ export function candidateTemplateFiles(template, currentProjectConfig = null) {
  */
 export function currentTemplateOwnedFiles(projectRoot, includeImplementation, projectConfig) {
   const files = new Map();
-  for (const rootName of includeImplementation ? ["topogram", "implementation"] : ["topogram"]) {
+  for (const rootName of includeImplementation ? [DEFAULT_TOPO_FOLDER_NAME, "implementation"] : [DEFAULT_TOPO_FOLDER_NAME]) {
     const root = path.join(projectRoot, rootName);
     if (!fs.existsSync(root)) {
       continue;
@@ -323,7 +353,7 @@ export function includesTemplateImplementation(projectConfig) {
 export function currentTemplateOwnedFileHashes(projectRoot, projectConfig) {
   const files = currentTemplateOwnedFiles(projectRoot, includesTemplateImplementation(projectConfig), projectConfig);
   return new Map([...files.entries()].map(([relativePath, file]) => {
-    const hash = fileHash(file);
+    const hash = templateOwnedFileHash(relativePath, file);
     return [relativePath, { path: relativePath, ...hash }];
   }));
 }

package/src/new-project/template-updates.js

@@ -343,7 +343,7 @@ export function applyTemplateUpdateFileAction(options) {
         code: "template_file_not_current",
         message: `Cannot accept current file '${relativePath}' because it is not a current template-owned file.`,
         path: path.join(options.projectRoot, relativePath),
-        suggestedFix: "Pass a file under topogram/, topogram.project.json, or trusted implementation/.",
+        suggestedFix: "Pass a file under topo/, topogram.project.json, or trusted implementation/.",
         step: "accept-current"
       }));
       return templateUpdateFileActionResult(diagnostics, null, options.action, relativePath, applied, accepted, deleted, conflicts, current);