@topogram/cli 0.3.78 → 0.3.79

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

@@ -97,6 +97,30 @@ export function summarizeJourneyDoc(doc) {
   };
 }
 
+/**
+ * @param {import("./types.d.ts").ContextStatement} journey
+ * @returns {any}
+ */
+export function summarizeJourney(journey) {
+  return {
+    id: journey.id,
+    kind: journey.kind,
+    name: journey.name || journey.id,
+    description: journey.description || null,
+    status: journey.status || null,
+    goal: journey.goal || null,
+    actors: stableSortedStrings(journey.actors || []),
+    relatedCapabilities: stableSortedStrings(journey.relatedCapabilities || []),
+    relatedWorkflows: stableSortedStrings(journey.relatedWorkflows || []),
+    relatedProjections: stableSortedStrings(journey.relatedProjections || []),
+    relatedWidgets: stableSortedStrings(journey.relatedWidgets || []),
+    stepCount: (journey.steps || []).length,
+    alternateCount: (journey.alternates || []).length,
+    reviewBoundary: reviewBoundaryForJourneyDocPolicy(journey),
+    ownership_boundary: defaultOwnershipBoundary()
+  };
+}
+
 /**
  * @param {import("./types.d.ts").ContextStatement} statement
  * @returns {any}
@@ -163,6 +187,8 @@ export function summarizeStatement(statement) {
       };
     case "widget":
       return summarizeComponent(statement);
+    case "journey":
+      return summarizeJourney(statement);
     case "shape":
       return {
         id: statement.id,

package/src/generator/context/shared.d.ts

@@ -34,6 +34,7 @@ export function summarizeById(...args: any[]): any;
 export function summarizeDocsByIds(...args: any[]): any;
 export function summarizeDocument(...args: any[]): any;
 export function summarizeDomain(...args: any[]): any;
+export function summarizeJourneyLikeByIds(...args: any[]): any;
 export function summarizePitch(...args: any[]): any;
 export function summarizePlan(...args: any[]): any;
 export function summarizeProjection(...args: any[]): any;

package/src/generator/context/shared.js

@@ -20,6 +20,7 @@ export {
   summarizeById,
   summarizeStatementsByIds,
   summarizeDocsByIds,
+  summarizeJourneyLikeByIds,
   workspaceInventory
 } from "./shared/relationships.js";
 export {

package/src/generator/context/slice/core.js

@@ -20,6 +20,7 @@ import {
   relatedWorkflowDocsForCapability,
   summarizeById,
   summarizeDocsByIds,
+  summarizeJourneyLikeByIds,
   summarizeProjection,
   summarizeStatementsByIds,
   verificationIdsForTarget,
@@ -87,7 +88,7 @@ function capabilitySlice(graph, capabilityId) {
       entities: summarizeStatementsByIds(graph, entities),
       rules: summarizeStatementsByIds(graph, rules),
       workflows: summarizeDocsByIds(graph, workflows),
-      journeys: summarizeDocsByIds(graph, journeys),
+      journeys: summarizeJourneyLikeByIds(graph, journeys),
       projections: summarizeStatementsByIds(graph, projections)
     },
     verification: summarizeStatementsByIds(graph, verifications),
@@ -118,9 +119,12 @@ function workflowSlice(graph, workflowId) {
     ];
   }))].sort();
   const rules = [...new Set(capabilities.flatMap(/** @param {string} capabilityId */ (capabilityId) => relatedRulesForTarget(graph, capabilityId)))].sort();
-  const journeys = (graph.docs || [])
-    .filter(/** @param {any} doc */ (doc) => doc.kind === "journey" && (doc.relatedWorkflows || []).includes(workflowId))
-    .map(/** @param {any} doc */ (doc) => doc.id)
+  const journeys = [
+    ...(graph.byKind?.journey || []),
+    ...(graph.docs || []).filter(/** @param {any} doc */ (doc) => doc.kind === "journey")
+  ]
+    .filter(/** @param {any} journey */ (journey) => (journey.relatedWorkflows || []).includes(workflowId))
+    .map(/** @param {any} journey */ (journey) => journey.id)
     .sort();
   const verifications = verificationIdsForTarget(graph, [...capabilities, ...entities, workflowId]);
 
@@ -143,7 +147,7 @@ function workflowSlice(graph, workflowId) {
       capabilities: summarizeStatementsByIds(graph, capabilities),
       entities: summarizeStatementsByIds(graph, entities),
       rules: summarizeStatementsByIds(graph, rules),
-      journeys: summarizeDocsByIds(graph, journeys)
+      journeys: summarizeJourneyLikeByIds(graph, journeys)
     },
     verification: summarizeStatementsByIds(graph, verifications),
     verification_targets: recommendedVerificationTargets(graph, [...capabilities, ...entities, workflowId], {

package/src/generator/context/slice/sdlc.js

@@ -49,9 +49,16 @@ import {
 export function journeySlice(graph, journeyId) {
   const journey = getJourneyDoc(graph, journeyId);
   const capabilities = [...(journey.relatedCapabilities || [])].sort();
+  const entities = [...(journey.relatedEntities || [])].sort();
+  const rules = [...(journey.relatedRules || [])].sort();
   const workflows = [...(journey.relatedWorkflows || [])].sort();
   const projections = [...(journey.relatedProjections || [])].sort();
-  const verifications = verificationIdsForTarget(graph, [...capabilities, ...workflows, ...projections, journeyId]);
+  const widgets = [...(journey.relatedWidgets || [])].sort();
+  const declaredVerifications = [...(journey.relatedVerifications || [])].sort();
+  const verifications = [...new Set([
+    ...declaredVerifications,
+    ...verificationIdsForTarget(graph, [...capabilities, ...workflows, ...projections, ...widgets, journeyId])
+  ])].sort();
 
   return {
     type: "context_slice",
@@ -63,14 +70,36 @@ export function journeySlice(graph, journeyId) {
     summary: summarizeById(graph, journeyId),
     depends_on: {
       capabilities,
+      entities,
+      rules,
       workflows,
       projections,
+      widgets,
       verifications
     },
+    steps: (journey.steps || []).map(/** @param {any} step */ (step) => ({
+      id: step.id,
+      intent: step.intent,
+      commands: [...(step.commands || [])],
+      expects: [...(step.expects || [])],
+      after: [...(step.after || [])],
+      notes: step.notes || null
+    })),
+    alternates: (journey.alternates || []).map(/** @param {any} alternate */ (alternate) => ({
+      id: alternate.id,
+      from: alternate.from,
+      condition: alternate.condition,
+      commands: [...(alternate.commands || [])],
+      expects: [...(alternate.expects || [])],
+      notes: alternate.notes || null
+    })),
     related: {
       capabilities: summarizeStatementsByIds(graph, capabilities),
+      entities: summarizeStatementsByIds(graph, entities),
+      rules: summarizeStatementsByIds(graph, rules),
       workflows: summarizeDocsByIds(graph, workflows),
-      projections: summarizeStatementsByIds(graph, projections)
+      projections: summarizeStatementsByIds(graph, projections),
+      widgets: summarizeStatementsByIds(graph, widgets)
     },
     verification: summarizeStatementsByIds(graph, verifications),
     verification_targets: recommendedVerificationTargets(graph, [...capabilities, ...workflows, ...projections, journeyId], {

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

@@ -325,7 +325,7 @@ function importAdoptMode(graph, options = {}) {
   return {
     type: "context_task_mode",
     version: 1,
-    mode: "import-adopt",
+    mode: "extract-adopt",
     summary: {
       focus: "Proposal review and adoption planning",
       preferred_start: "adoption-plan.agent.json",
@@ -450,7 +450,7 @@ function verificationMode(graph, options = {}) {
 export function generateContextTaskMode(graph, options = {}) {
   const mode = String(options.modeId || "").trim();
   if (!mode) {
-    throw new Error("context-task-mode requires --mode <modeling|maintained-app-edit|import-adopt|diff-review|verification>");
+    throw new Error("context-task-mode requires --mode <modeling|maintained-app-edit|extract-adopt|diff-review|verification>");
   }
 
   if (mode === "modeling") {
@@ -459,7 +459,7 @@ export function generateContextTaskMode(graph, options = {}) {
   if (mode === "maintained-app-edit") {
     return maintainedAppEditMode(graph, options);
   }
-  if (mode === "import-adopt") {
+  if (mode === "extract-adopt") {
     return importAdoptMode(graph, options);
   }
   if (mode === "diff-review") {

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

@@ -17,12 +17,12 @@ export function reportMarkdown(track, candidates) {
       `  - manual next: ${(seam.manual_next_steps || []).slice(0, 2).join(" ")}`
     ]);
     return ensureTrailingNewline(
-      `# DB Import Report\n\n- Entities: ${candidates.entities.length}\n- Enums: ${candidates.enums.length}\n- Relations: ${candidates.relations.length}\n- Indexes: ${candidates.indexes.length}\n- Maintained DB migration seams: ${(candidates.maintained_seams || []).length}\n\n## Maintained DB Migration Seam Candidates\n\n${seamLines.length ? seamLines.join("\n") : "- none"}\n`
+      `# DB Extract Report\n\n- Entities: ${candidates.entities.length}\n- Enums: ${candidates.enums.length}\n- Relations: ${candidates.relations.length}\n- Indexes: ${candidates.indexes.length}\n- Maintained DB migration seams: ${(candidates.maintained_seams || []).length}\n\n## Maintained DB Migration Seam Candidates\n\n${seamLines.length ? seamLines.join("\n") : "- none"}\n`
     );
   }
   if (track === "api") {
     return ensureTrailingNewline(
-      `# API Import Report\n\n- Capabilities: ${candidates.capabilities.length}\n- Routes: ${candidates.routes.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n`
+      `# API Extract Report\n\n- Capabilities: ${candidates.capabilities.length}\n- Routes: ${candidates.routes.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n`
     );
   }
   if (track === "ui") {
@@ -36,7 +36,7 @@ export function reportMarkdown(track, candidates) {
       `- \`${flow.id_hint}\` type \`${flow.flow_type}\` confidence ${flow.confidence || "unknown"} routes ${(flow.route_paths || []).map((/** @type {string} */ route) => `\`${route}\``).join(", ") || "_none_"} missing decisions ${(flow.missing_decisions || []).length}`
     );
     return ensureTrailingNewline(
-      `# UI Import Report\n\n- Screens: ${candidates.screens.length}\n- Routes: ${candidates.routes.length}\n- Actions: ${candidates.actions.length}\n- Flow candidates: ${flows.length}\n- Widgets: ${widgets.length}\n- Event payload shapes: ${shapes.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n\n## Flow Candidates\n\n${flowLines.length ? flowLines.join("\n") : "- none"}\n\n## Widget Candidates\n\n${widgetLines.length ? widgetLines.join("\n") : "- none"}\n\n## Next Validation\n\n- Review flow candidates in \`topo/candidates/app/ui/candidates.json\` before adding shared UI contract behavior.\n- Review candidates under \`topo/candidates/app/ui/drafts/widgets/**\`.\n- Run \`topogram import plan <path>\` before adoption.\n- After adoption, run \`topogram check <path>\`, \`topogram widget check <path>\`, and \`topogram widget behavior <path>\`.\n`
+      `# UI Extract Report\n\n- Screens: ${candidates.screens.length}\n- Routes: ${candidates.routes.length}\n- Actions: ${candidates.actions.length}\n- Flow candidates: ${flows.length}\n- Widgets: ${widgets.length}\n- Event payload shapes: ${shapes.length}\n- Stacks: ${candidates.stacks.length ? candidates.stacks.join(", ") : "none"}\n\n## Flow Candidates\n\n${flowLines.length ? flowLines.join("\n") : "- none"}\n\n## Widget Candidates\n\n${widgetLines.length ? widgetLines.join("\n") : "- none"}\n\n## Next Validation\n\n- Review flow candidates in \`topo/candidates/app/ui/candidates.json\` before adding shared UI contract behavior.\n- Review candidates under \`topo/candidates/app/ui/drafts/widgets/**\`.\n- Run \`topogram extract plan <path>\` before adoption.\n- After adoption, run \`topogram check <path>\`, \`topogram widget check <path>\`, and \`topogram widget behavior <path>\`.\n`
     );
   }
   if (track === "cli") {
@@ -44,7 +44,7 @@ export function reportMarkdown(track, candidates) {
       `- \`${command.command_id || command.id_hint}\` usage \`${command.usage || "unknown"}\` effects ${(command.effects || []).map((/** @type {any} */ effect) => `\`${effect}\``).join(", ") || "_none_"}`
     );
     return ensureTrailingNewline(
-      `# CLI Import Report\n\n- Commands: ${candidates.commands.length}\n- Capabilities: ${candidates.capabilities.length}\n- CLI surfaces: ${candidates.surfaces.length}\n\n## Command Candidates\n\n${commandLines.length ? commandLines.join("\n") : "- none"}\n`
+      `# CLI Extract Report\n\n- Commands: ${candidates.commands.length}\n- Capabilities: ${candidates.capabilities.length}\n- CLI surfaces: ${candidates.surfaces.length}\n\n## Command Candidates\n\n${commandLines.length ? commandLines.join("\n") : "- none"}\n`
     );
   }
   if (track === "verification") {

package/src/import/provenance.js

@@ -4,7 +4,7 @@ import path from "node:path";
 
 import { listFilesRecursive, relativeTo } from "./core/shared.js";
 
-export const TOPOGRAM_IMPORT_FILE = ".topogram-import.json";
+export const TOPOGRAM_IMPORT_FILE = ".topogram-extract.json";
 
 function fileHash(filePath) {
   const bytes = fs.readFileSync(filePath);
@@ -42,22 +42,22 @@ export function writeTopogramImportRecord(projectRoot, input) {
   const timestamp = input.timestamp || new Date().toISOString();
   const record = {
     version: "0.1",
-    kind: "brownfield-import",
-    importedAt: input.importedAt || timestamp,
+    kind: "brownfield-extract",
+    extractedAt: input.importedAt || timestamp,
     ...(input.refreshedAt ? { refreshedAt: input.refreshedAt } : {}),
     source: {
       path: path.resolve(input.sourceRoot),
       hashAlgorithm: "sha256",
       ignoredRoots: (input.ignoredRoots || []).map((item) => path.resolve(item))
     },
-    import: {
+    extract: {
       tracks: input.tracks || [],
       findingsCount: input.findingsCount || 0,
       candidateCounts: input.candidateCounts || {}
     },
     ownership: {
-      importedArtifacts: "project-owned",
-      note: "Topogram artifacts created by import are editable after import. Source hashes record the brownfield app evidence trusted at import time."
+      extractedArtifacts: "project-owned",
+      note: "Topogram artifacts created by extraction are editable after extraction. Source hashes record the brownfield app evidence trusted at extraction time."
     },
     ...(input.refresh ? { refresh: input.refresh } : {}),
     files: input.files || []
@@ -79,11 +79,11 @@ export function buildTopogramImportStatus(projectRoot) {
       source: null,
       content: { changed: [], added: [], removed: [] },
       diagnostics: [{
-        code: "topogram_import_missing",
+        code: "topogram_extract_missing",
         severity: "error",
-        message: `${TOPOGRAM_IMPORT_FILE} was not found. This workspace does not have brownfield import provenance.`,
+        message: `${TOPOGRAM_IMPORT_FILE} was not found. This workspace does not have brownfield extraction provenance.`,
         path: importPath,
-        suggestedFix: "Run `topogram import <app-path> --out <target>` to create an imported Topogram workspace."
+        suggestedFix: "Run `topogram extract <app-path> --out <target>` to create an extracted Topogram workspace."
       }],
       errors: [`${TOPOGRAM_IMPORT_FILE} was not found.`]
     };
@@ -92,7 +92,7 @@ export function buildTopogramImportStatus(projectRoot) {
   const source = JSON.parse(fs.readFileSync(importPath, "utf8"));
   const sourceRoot = path.resolve(source.source?.path || "");
   if (!sourceRoot || !fs.existsSync(sourceRoot) || !fs.statSync(sourceRoot).isDirectory()) {
-    const message = `Imported source path was not found: ${source.source?.path || "unknown"}`;
+    const message = `Extracted source path was not found: ${source.source?.path || "unknown"}`;
     return {
       ok: false,
       exists: true,
@@ -101,11 +101,11 @@ export function buildTopogramImportStatus(projectRoot) {
       source,
       content: { changed: [], added: [], removed: [] },
       diagnostics: [{
-        code: "topogram_import_source_missing",
+      code: "topogram_extract_source_missing",
         severity: "error",
         message,
         path: source.source?.path || null,
-        suggestedFix: "Restore the imported source path or rerun import from the current brownfield app location."
+        suggestedFix: "Restore the extracted source path or rerun extract from the current brownfield app location."
       }],
       errors: [message]
     };
@@ -147,12 +147,12 @@ export function buildTopogramImportStatus(projectRoot) {
     source,
     content,
     diagnostics: clean ? [] : [{
-      code: "topogram_import_source_changed",
+      code: "topogram_extract_source_changed",
       severity: "error",
-      message: "Imported source files changed since they were trusted for this import.",
+      message: "Extracted source files changed since they were trusted for this extraction.",
       path: sourceRoot,
-      suggestedFix: "Review the source changes. If they should drive Topogram changes, rerun import or update the Topogram artifacts manually."
+      suggestedFix: "Review the source changes. If they should drive Topogram changes, rerun extract or update the Topogram artifacts manually."
     }],
-    errors: clean ? [] : ["Imported source files changed since import."]
+    errors: clean ? [] : ["Extracted source files changed since extraction."]
   };
 }

package/src/init-project.js

@@ -0,0 +1,215 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { defaultSdlcPolicy, SDLC_POLICY_FILE } from "./sdlc/policy.js";
+import { DEFAULT_TOPO_FOLDER_NAME, DEFAULT_WORKSPACE_PATH, PROJECT_CONFIG_FILE } from "./workspace-paths.js";
+
+/**
+ * @typedef {Object} InitProjectOptions
+ * @property {string} [targetPath]
+ * @property {boolean} [withSdlc]
+ */
+
+/**
+ * @typedef {Object} InitProjectResult
+ * @property {boolean} ok
+ * @property {string} projectRoot
+ * @property {string} workspaceRoot
+ * @property {string} projectConfigPath
+ * @property {string[]} created
+ * @property {string[]} skipped
+ * @property {Record<string, any>} projectConfig
+ * @property {{ enabled: boolean, path: string|null }} sdlc
+ */
+
+/**
+ * @param {string} projectRoot
+ * @param {string} targetPath
+ * @returns {string}
+ */
+function relativeProjectPath(projectRoot, targetPath) {
+  const relative = path.relative(projectRoot, targetPath);
+  return relative ? relative.split(path.sep).join("/") : ".";
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string} filePath
+ * @param {string} content
+ * @param {string[]} created
+ * @param {string[]} skipped
+ * @returns {void}
+ */
+function writeIfMissing(projectRoot, filePath, content, created, skipped) {
+  if (fs.existsSync(filePath)) {
+    skipped.push(relativeProjectPath(projectRoot, filePath));
+    return;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, "utf8");
+  created.push(relativeProjectPath(projectRoot, filePath));
+}
+
+/**
+ * @returns {Record<string, any>}
+ */
+function defaultMaintainedProjectConfig() {
+  return {
+    version: "0.1",
+    workspace: DEFAULT_WORKSPACE_PATH,
+    outputs: {
+      app: {
+        path: ".",
+        ownership: "maintained"
+      }
+    },
+    topology: {
+      runtimes: []
+    }
+  };
+}
+
+/**
+ * @returns {string}
+ */
+function initializedReadme() {
+  return `# Topogram Project
+
+Initialized with \`topogram init\`.
+
+This repository is treated as a maintained app or workspace: Topogram will not
+overwrite source code under \`./\`. Use \`topogram emit\` for contracts, reports,
+snapshots, and proposals, and edit maintained app code directly after reading
+focused query packets.
+
+## First Commands
+
+\`\`\`bash
+topogram agent brief --json
+topogram check --json
+topogram query list --json
+\`\`\`
+
+To adopt enforced SDLC after initialization, run:
+
+\`\`\`bash
+topogram sdlc policy init .
+\`\`\`
+
+## Source
+
+- \`topo/\` is the project-owned Topogram workspace.
+- \`topogram.project.json\` declares workspace, output ownership, and runtime topology.
+- Output \`app\` points at \`.\` with \`maintained\` ownership.
+`;
+}
+
+/**
+ * @returns {string}
+ */
+function initializedAgentsGuide() {
+  return `# Agent Guide
+
+This repository was initialized with \`topogram init\`.
+
+Start with:
+
+\`\`\`bash
+topogram agent brief --json
+topogram check --json
+topogram query list --json
+\`\`\`
+
+Edit \`topo/**\` and \`topogram.project.json\` for Topogram source. The project
+output is maintained, so app/source files under \`./\` are human-owned and may be
+edited directly after reading focused packets.
+
+Use \`topogram emit <target>\` for contracts, reports, snapshots, migration
+plans, and agent context. Do not expect \`topogram generate\` to overwrite this
+maintained app unless output ownership is deliberately changed.
+
+If \`topogram.sdlc-policy.json\` exists, use SDLC commands for task and status
+work before protected edits:
+
+\`\`\`bash
+topogram sdlc policy explain --json
+topogram sdlc prep commit . --json
+\`\`\`
+`;
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {void}
+ */
+function assertInitTarget(projectRoot) {
+  if (fs.existsSync(projectRoot) && !fs.statSync(projectRoot).isDirectory()) {
+    throw new Error(`Cannot initialize Topogram at '${projectRoot}' because it is not a directory.`);
+  }
+  const configPath = path.join(projectRoot, PROJECT_CONFIG_FILE);
+  if (fs.existsSync(configPath)) {
+    throw new Error(`Refusing to initialize Topogram because ${PROJECT_CONFIG_FILE} already exists.`);
+  }
+  const workspaceRoot = path.join(projectRoot, DEFAULT_TOPO_FOLDER_NAME);
+  if (fs.existsSync(workspaceRoot)) {
+    if (!fs.statSync(workspaceRoot).isDirectory()) {
+      throw new Error(`Refusing to initialize Topogram because ${DEFAULT_TOPO_FOLDER_NAME}/ exists and is not a directory.`);
+    }
+    const entries = fs.readdirSync(workspaceRoot).filter(/** @param {string} entry */ (entry) => entry !== ".DS_Store");
+    if (entries.length > 0) {
+      throw new Error(`Refusing to initialize Topogram because ${DEFAULT_TOPO_FOLDER_NAME}/ already exists and is not empty.`);
+    }
+  }
+}
+
+/**
+ * @param {InitProjectOptions} [options]
+ * @returns {InitProjectResult}
+ */
+export function initTopogramProject(options = {}) {
+  const projectRoot = path.resolve(options.targetPath || ".");
+  assertInitTarget(projectRoot);
+  fs.mkdirSync(projectRoot, { recursive: true });
+
+  /** @type {string[]} */
+  const created = [];
+  /** @type {string[]} */
+  const skipped = [];
+  const workspaceRoot = path.join(projectRoot, DEFAULT_TOPO_FOLDER_NAME);
+  fs.mkdirSync(workspaceRoot, { recursive: true });
+  created.push(DEFAULT_TOPO_FOLDER_NAME);
+
+  writeIfMissing(projectRoot, path.join(workspaceRoot, ".gitkeep"), "", created, skipped);
+  const projectConfig = defaultMaintainedProjectConfig();
+  const projectConfigPath = path.join(projectRoot, PROJECT_CONFIG_FILE);
+  fs.writeFileSync(projectConfigPath, `${JSON.stringify(projectConfig, null, 2)}\n`, "utf8");
+  created.push(PROJECT_CONFIG_FILE);
+  writeIfMissing(projectRoot, path.join(projectRoot, "README.md"), initializedReadme(), created, skipped);
+  writeIfMissing(projectRoot, path.join(projectRoot, "AGENTS.md"), initializedAgentsGuide(), created, skipped);
+  const sdlcPolicyPath = path.join(projectRoot, SDLC_POLICY_FILE);
+  if (options.withSdlc) {
+    writeIfMissing(
+      projectRoot,
+      sdlcPolicyPath,
+      `${JSON.stringify(defaultSdlcPolicy(), null, 2)}\n`,
+      created,
+      skipped
+    );
+  }
+
+  return {
+    ok: true,
+    projectRoot,
+    workspaceRoot,
+    projectConfigPath,
+    created,
+    skipped,
+    projectConfig,
+    sdlc: {
+      enabled: options.withSdlc ? fs.existsSync(sdlcPolicyPath) : false,
+      path: options.withSdlc ? sdlcPolicyPath : null
+    }
+  };
+}

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 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.`;
+  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 copy or topogram template check.`;
 }
 
 /**

package/src/new-project/create.js

@@ -36,7 +36,7 @@ export function createNewProject({
   templateProvenance = null
 }) {
   if (!targetPath) {
-    throw new Error("topogram new requires <path>.");
+    throw new Error("topogram copy requires <target>.");
   }
   const projectRoot = path.resolve(targetPath);
   assertProjectOutsideEngine(projectRoot, engineRoot);
@@ -68,7 +68,7 @@ export function createNewProject({
     writeTemplateTrustRecord(projectRoot, projectConfig);
     warnings.push(
       `Template '${template.manifest.id}' copied implementation/ code into this project. ` +
-        "topogram new did not execute it, but topogram generate may load it later. " +
+        "topogram copy did not execute it, but topogram generate may load it later. " +
         "Recorded local trust in .topogram-template-trust.json."
     );
   }

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

@@ -247,7 +247,7 @@ export function writeProjectReadme(projectRoot, projectConfig) {
   provenanceLines.push(`- Executable implementation: \`${template.includesExecutableImplementation ? "yes" : "no"}\``);
   const readme = `# ${packageNameFromPath(projectRoot)}
 
-Generated by \`topogram new\`.
+Copied by \`topogram copy\`.
 
 ## Template
 
@@ -263,7 +263,7 @@ Edit the workspace folder \`${DEFAULT_TOPO_FOLDER_NAME}/\` and \`topogram.projec
 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.
-${template.includesExecutableImplementation ? "\nThis template copied `implementation/` code. `topogram new` did not execute it; review `implementation/`, `topogram.template-policy.json`, and `.topogram-template-trust.json` before regenerating after edits.\n" : ""}
+${template.includesExecutableImplementation ? "\nThis template copied `implementation/` code. `topogram copy` did not execute it; review `implementation/`, `topogram.template-policy.json`, and `.topogram-template-trust.json` before regenerating after edits.\n" : ""}
 `;
   fs.writeFileSync(path.join(projectRoot, "README.md"), readme, "utf8");
 }
@@ -339,12 +339,12 @@ npm run query:show -- widget-behavior
 
 - Local edits to template-derived Topogram files are project-owned.
 - Use \`npm run source:status\` and \`npm run template:update:recommend\` before applying template updates.
-${hasImplementation ? "- This project has executable `implementation/` code. `topogram new` did not execute it. Do not refresh trust until the implementation has been reviewed.\n" : "- This template does not declare executable implementation code.\n"}
-## Import And Adoption
+${hasImplementation ? "- This project has executable `implementation/` code. `topogram copy` did not execute it. Do not refresh trust until the implementation has been reviewed.\n" : "- This template does not declare executable implementation code.\n"}
+## Extract And Adopt
 
-- If \`.topogram-import.json\` exists, agents should run \`topogram import check . --json\`, \`topogram import plan . --json\`, \`topogram import adopt --list . --json\`, \`topogram import status . --json\`, and \`topogram import history . --verify --json\`.
-- Import JSON payloads expose \`workspaceRoot\`; prefer it as the canonical project-owned workspace path.
-- Imported Topogram files are project-owned after adoption; source hashes record trusted import evidence at the time of import.
+- If \`.topogram-extract.json\` exists, agents should run \`topogram extract check . --json\`, \`topogram extract plan . --json\`, \`topogram adopt --list . --json\`, \`topogram extract status . --json\`, and \`topogram extract history . --verify --json\`.
+- Extract JSON payloads expose \`workspaceRoot\`; prefer it as the canonical project-owned workspace path.
+- Extracted Topogram files are project-owned after adoption; source hashes record trusted source evidence at the time of extraction.
 
 ## Verification Gates
 

package/src/reconcile/journeys.js

@@ -28,9 +28,11 @@ function primaryEntityIdForBundle(bundle) {
 
 function canonicalJourneyCoverage(graph) {
   const journeyDocs = (graph?.docs || []).filter((doc) => doc.kind === "journey");
+  const journeyStatements = graph?.byKind?.journey || [];
+  const journeys = [...journeyStatements, ...journeyDocs];
   return {
-    byEntityId: new Set(journeyDocs.flatMap((doc) => doc.relatedEntities || [])),
-    byCapabilityId: new Set(journeyDocs.flatMap((doc) => doc.relatedCapabilities || []))
+    byEntityId: new Set(journeys.flatMap((journey) => journey.relatedEntities || [])),
+    byCapabilityId: new Set(journeys.flatMap((journey) => journey.relatedCapabilities || []))
   };
 }
 
@@ -42,7 +44,10 @@ function collectJourneyGenerationContext(graph) {
   const uiSharedScreens = projections
     .filter((projection) => projection.type === "ui_contract")
     .flatMap((projection) => (projection.uiScreens || []).map((screen) => ({ ...screen, projectionId: projection.id })));
-  const canonicalJourneys = (graph.docs || []).filter((doc) => doc.kind === "journey");
+  const canonicalJourneys = [
+    ...(graph.byKind?.journey || []),
+    ...(graph.docs || []).filter((doc) => doc.kind === "journey")
+  ];
   const coveredEntityIds = new Set(canonicalJourneys.flatMap((doc) => doc.relatedEntities || []));
 
   return entities