@topogram/cli 0.3.78 → 0.3.80

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

@@ -3,46 +3,57 @@
 import { TOPOGRAM_IMPORT_FILE } from "../../../import/provenance.js";
 import { TOPOGRAM_IMPORT_ADOPTIONS_FILE } from "./paths.js";
 
-export function printImportHelp() {
-  console.log("Usage: topogram import <app-path> --out <target> [--from <track[,track]>] [--json]");
-  console.log("   or: topogram import refresh [path] [--from <app-path>] [--dry-run] [--json]");
-  console.log("   or: topogram import diff [path] [--json]");
-  console.log("   or: topogram import check [path] [--json]");
-  console.log("   or: topogram import plan [path] [--json]");
-  console.log("   or: topogram import adopt --list [path] [--json]");
-  console.log("   or: topogram import adopt <selector> [path] [--dry-run|--write] [--force --reason <text>] [--json]");
-  console.log("   or: topogram import status [path] [--json]");
-  console.log("   or: topogram import history [path] [--verify] [--json]");
+export function printExtractHelp() {
+  console.log("Usage: topogram extract <app-path> --out <target> [--from <track[,track]>] [--extractor <id-or-package-or-path>] [--json]");
+  console.log("   or: topogram extract refresh [path] [--from <app-path>] [--dry-run] [--json]");
+  console.log("   or: topogram extract diff [path] [--json]");
+  console.log("   or: topogram extract check [path] [--json]");
+  console.log("   or: topogram extract plan [path] [--json]");
+  console.log("   or: topogram extract status [path] [--json]");
+  console.log("   or: topogram extract history [path] [--verify] [--json]");
   console.log("");
-  console.log("Creates an editable Topogram workspace from a brownfield app without modifying the app.");
+  console.log("Extracts reviewable Topogram candidates from a brownfield app without modifying the app.");
   console.log("");
   console.log("Behavior:");
-  console.log("  - writes raw import candidates under topo/candidates/app");
+  console.log("  - writes raw extraction candidates under topo/candidates/app");
   console.log("  - writes reconcile proposal bundles under topo/candidates/reconcile");
   console.log("  - writes topogram.project.json with maintained ownership and no generated stack binding");
-  console.log(`  - writes ${TOPOGRAM_IMPORT_FILE} with source file hashes from import time`);
-  console.log("  - imported Topogram artifacts are project-owned after creation");
+  console.log(`  - writes ${TOPOGRAM_IMPORT_FILE} with source file hashes from extraction time`);
+  console.log("  - extracted Topogram artifacts are project-owned after creation");
   console.log("  - refresh rewrites only candidate/reconcile artifacts and source provenance");
-  console.log("  - adoption previews never write canonical Topogram files unless --write is passed");
-  console.log("  - adoption writes refuse dirty brownfield source provenance unless --force is passed");
-  console.log(`  - adoption writes append audit receipts to ${TOPOGRAM_IMPORT_ADOPTIONS_FILE}`);
-  console.log("  - forced adoption writes require --reason <text>");
   console.log("");
   console.log("Examples:");
-  console.log("  topogram import ./existing-app --out ./imported-topogram");
-  console.log("  topogram import ./existing-app --out ./imported-topogram --from db,api,ui");
-  console.log("  topogram import ./existing-cli --out ./imported-topogram --from cli");
-  console.log("  topogram import diff ./imported-topogram");
-  console.log("  topogram import refresh ./imported-topogram --from ./existing-app --dry-run");
-  console.log("  topogram import refresh ./imported-topogram --from ./existing-app");
-  console.log("  topogram import check ./imported-topogram");
-  console.log("  topogram import plan ./imported-topogram");
-  console.log("  topogram import adopt --list ./imported-topogram");
-  console.log("  topogram import adopt bundle:task ./imported-topogram --dry-run");
-  console.log("  topogram import adopt bundle:task ./imported-topogram --write");
-  console.log("  topogram import adopt bundle:task ./imported-topogram --write --force --reason \"Reviewed source drift\"");
-  console.log("  topogram import status ./imported-topogram");
-  console.log("  topogram import history ./imported-topogram");
-  console.log("  topogram import history ./imported-topogram --verify");
-  console.log("  topogram import check --json");
+  console.log("  topogram extract ./existing-app --out ./extracted-topogram");
+  console.log("  topogram extract ./existing-app --out ./extracted-topogram --from db,api,ui");
+  console.log("  topogram extract ./existing-cli --out ./extracted-topogram --from cli");
+  console.log("  topogram extract ./existing-cli --out ./extracted-topogram --from cli --extractor @topogram/extractor-node-cli");
+  console.log("  topogram extract ./existing-app --out ./extracted-topogram --extractor-policy ./topogram.extractor-policy.json");
+  console.log("  topogram extract diff ./extracted-topogram");
+  console.log("  topogram extract refresh ./extracted-topogram --from ./existing-app --dry-run");
+  console.log("  topogram extract refresh ./extracted-topogram --from ./existing-app");
+  console.log("  topogram extract check ./extracted-topogram");
+  console.log("  topogram extract plan ./extracted-topogram");
+  console.log("  topogram extract status ./extracted-topogram");
+  console.log("  topogram extract history ./extracted-topogram");
+  console.log("  topogram extract history ./extracted-topogram --verify");
+  console.log("  topogram extract check --json");
+}
+
+export function printAdoptHelp() {
+  console.log("Usage: topogram adopt --list [path] [--json]");
+  console.log("   or: topogram adopt <selector> [path] [--dry-run|--write] [--force --reason <text>] [--json]");
+  console.log("");
+  console.log("Promotes reviewed extraction candidates into canonical topo/ files.");
+  console.log("");
+  console.log("Behavior:");
+  console.log("  - previews never write canonical Topogram files unless --write is passed");
+  console.log("  - writes refuse dirty brownfield source provenance unless --force is passed");
+  console.log(`  - writes append audit receipts to ${TOPOGRAM_IMPORT_ADOPTIONS_FILE}`);
+  console.log("  - forced writes require --reason <text>");
+  console.log("");
+  console.log("Examples:");
+  console.log("  topogram adopt --list ./extracted-topogram");
+  console.log("  topogram adopt bundle:task ./extracted-topogram --dry-run");
+  console.log("  topogram adopt bundle:task ./extracted-topogram --write");
+  console.log("  topogram adopt bundle:task ./extracted-topogram --write --force --reason \"Reviewed source drift\"");
 }

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

@@ -9,7 +9,7 @@ import { TOPOGRAM_IMPORT_FILE } from "../../../import/provenance.js";
 import { shellCommandArg } from "../catalog.js";
 import { resolveTopoRoot, resolveWorkspaceContext } from "../../../workspace-paths.js";
 
-export const TOPOGRAM_IMPORT_ADOPTIONS_FILE = ".topogram-import-adoptions.jsonl";
+export const TOPOGRAM_IMPORT_ADOPTIONS_FILE = ".topogram-adoptions.jsonl";
 
 /**
  * @typedef {Record<string, any>} AnyRecord
@@ -219,7 +219,7 @@ export function readImportAdoptionReceipts(projectRoot) {
       try {
         return JSON.parse(line);
       } catch (error) {
-        throw new Error(`Invalid import adoption receipt JSON at ${historyPath}:${index + 1}.`);
+        throw new Error(`Invalid adoption receipt JSON at ${historyPath}:${index + 1}.`);
       }
     });
 }
@@ -265,5 +265,5 @@ export function importProjectCommandPath(projectRoot) {
  * @returns {string}
  */
 export function importAdoptCommand(projectRoot, selector, write = false) {
-  return `topogram import adopt ${selector} ${importProjectCommandPath(projectRoot)} ${write ? "--write" : "--dry-run"}`;
+  return `topogram adopt ${selector} ${importProjectCommandPath(projectRoot)} ${write ? "--write" : "--dry-run"}`;
 }

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

@@ -76,7 +76,7 @@ export function readImportAdoptionArtifacts(inputPath) {
     reconcileReport: path.join(reconcileRoot, "report.json")
   };
   if (!fs.existsSync(paths.adoptionPlanAgent)) {
-    throw new Error(`No import adoption plan found under '${reconcileRoot}'. Run 'topogram import <app-path> --out <target>' first.`);
+    throw new Error(`No extraction adoption plan found under '${reconcileRoot}'. Run 'topogram extract <app-path> --out <target>' first.`);
   }
   return {
     projectRoot,
@@ -182,10 +182,10 @@ export function summarizeImportAdoption(adoptionPlan, adoptionStatus, projectRoo
     risks: [
       ...(blockedCount > 0 ? [`${blockedCount} adoption item(s) are blocked.`] : []),
       ...(((adoptionPlan.requires_human_review || []).length || surfaces.some((/** @type {AnyRecord} */ item) => item.human_review_required))
-        ? ["Imported proposal items require human review before adoption."]
+        ? ["Extracted proposal items require human review before adoption."]
         : [])
     ],
-    nextCommand: nextBundle ? nextBundle.nextCommand : `topogram import status ${importProjectCommandPath(projectRoot)}`
+    nextCommand: nextBundle ? nextBundle.nextCommand : `topogram extract status ${importProjectCommandPath(projectRoot)}`
   };
 }
 
@@ -209,8 +209,8 @@ export function buildBrownfieldImportPlanPayload(inputPath) {
     },
     ...adoption,
     commands: {
-      check: `topogram import check ${importProjectCommandPath(artifacts.projectRoot)}`,
-      status: `topogram import status ${importProjectCommandPath(artifacts.projectRoot)}`,
+      check: `topogram extract check ${importProjectCommandPath(artifacts.projectRoot)}`,
+      status: `topogram extract status ${importProjectCommandPath(artifacts.projectRoot)}`,
       next: adoption.nextCommand
     }
   };
@@ -221,7 +221,7 @@ export function buildBrownfieldImportPlanPayload(inputPath) {
  * @returns {void}
  */
 export function printBrownfieldImportPlan(payload) {
-  console.log(`Import adoption plan for ${payload.projectRoot}`);
+  console.log(`Extraction adoption plan for ${payload.projectRoot}`);
   console.log(`Proposal items: ${payload.summary.proposalItemCount}`);
   console.log(`Bundles: ${payload.summary.bundleCount}`);
   for (const bundle of payload.bundles) {
@@ -279,9 +279,9 @@ export function buildBrownfieldImportAdoptListPayload(inputPath) {
  * @returns {void}
  */
 export function printBrownfieldImportAdoptList(payload) {
-  console.log(`Import adoption selectors for ${payload.projectRoot}`);
+  console.log(`Adoption selectors for ${payload.projectRoot}`);
   if (payload.selectors.length === 0) {
-    console.log("No adoption selectors are available. Run `topogram import plan` to inspect reconcile artifacts.");
+    console.log("No adoption selectors are available. Run `topogram extract plan` to inspect reconcile artifacts.");
     return;
   }
   for (const selector of payload.selectors) {

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

@@ -34,12 +34,12 @@ import { verifyImportAdoptionReceipts } from "./status-history.js";
 export function readTopogramImportRecord(projectRoot) {
   const importPath = path.join(normalizeProjectRoot(projectRoot), TOPOGRAM_IMPORT_FILE);
   if (!fs.existsSync(importPath)) {
-    throw new Error(`No brownfield import provenance found at '${importPath}'. Run 'topogram import <app-path> --out <target>' first.`);
+    throw new Error(`No brownfield extraction provenance found at '${importPath}'. Run 'topogram extract <app-path> --out <target>' first.`);
   }
   try {
     return { path: importPath, record: JSON.parse(fs.readFileSync(importPath, "utf8")) };
   } catch (error) {
-    throw new Error(`Invalid brownfield import provenance JSON at '${importPath}'.`);
+    throw new Error(`Invalid brownfield extraction provenance JSON at '${importPath}'.`);
   }
 }
 
@@ -48,8 +48,9 @@ export function readTopogramImportRecord(projectRoot) {
  * @returns {string|null}
  */
 export function importTrackValueFromRecord(importRecord) {
-  const tracks = Array.isArray(importRecord.import?.tracks)
-    ? importRecord.import.tracks.map((/** @type {any} */ track) => String(track).trim()).filter(Boolean)
+  const source = importRecord.extract || importRecord.import || {};
+  const tracks = Array.isArray(source.tracks)
+    ? source.tracks.map((/** @type {any} */ track) => String(track).trim()).filter(Boolean)
     : [];
   return tracks.length ? [...new Set(tracks)].join(",") : null;
 }
@@ -283,7 +284,7 @@ export function buildBrownfieldImportRefreshAnalysis(inputPath, options = {}) {
   const projectRoot = normalizeProjectRoot(inputPath);
   const topogramRoot = normalizeTopogramPath(projectRoot);
   if (!fs.existsSync(topogramRoot) || !fs.statSync(topogramRoot).isDirectory()) {
-    throw new Error(`No workspace folder found for imported workspace '${inputPath}'.`);
+    throw new Error(`No workspace folder found for extracted workspace '${inputPath}'.`);
   }
 
   const { record: importRecord } = readTopogramImportRecord(projectRoot);
@@ -291,21 +292,21 @@ export function buildBrownfieldImportRefreshAnalysis(inputPath, options = {}) {
     ? options.sourcePath
     : importRecord.source?.path;
   if (!sourcePath) {
-    throw new Error("No brownfield source path was provided or recorded. Use 'topogram import refresh <workspace> --from <app-path>'.");
+    throw new Error("No brownfield source path was provided or recorded. Use 'topogram extract refresh <workspace> --from <app-path>'.");
   }
   const sourceRoot = path.resolve(sourcePath);
   if (!fs.existsSync(sourceRoot) || !fs.statSync(sourceRoot).isDirectory()) {
     throw new Error(`Cannot refresh from missing app directory '${sourcePath}'.`);
   }
   if (sourceRoot === projectRoot) {
-    throw new Error("Refusing to refresh import from the imported Topogram workspace itself.");
+    throw new Error("Refusing to refresh extraction from the extracted Topogram workspace itself.");
   }
 
   const sourceComparison = compareImportRecordToSource(projectRoot, importRecord, sourceRoot);
   const trackValue = importTrackValueFromRecord(importRecord);
   const importResult = runWorkflow("import-app", sourceRoot, { from: trackValue });
   const candidateCounts = importCandidateCounts(importResult.summary);
-  const candidateCountDeltas = buildCountDeltas(importRecord.import?.candidateCounts || {}, candidateCounts);
+  const candidateCountDeltas = buildCountDeltas((importRecord.extract || importRecord.import)?.candidateCounts || {}, candidateCounts);
   const removedCandidateFiles = {
     rawCandidateFiles: countFilesRecursive(path.join(topogramRoot, "candidates", "app")),
     reconcileFiles: countFilesRecursive(path.join(topogramRoot, "candidates", "reconcile"))
@@ -324,7 +325,7 @@ export function buildBrownfieldImportRefreshAnalysis(inputPath, options = {}) {
     topogramRoot,
     sourcePath: sourceRoot,
     provenancePath: path.join(projectRoot, TOPOGRAM_IMPORT_FILE),
-    importedAt: importRecord.importedAt || null,
+    importedAt: importRecord.extractedAt || importRecord.importedAt || null,
     previousImportStatus: sourceComparison.status,
     sourceDiff: {
       status: sourceComparison.status,
@@ -354,13 +355,13 @@ export function buildBrownfieldImportRefreshAnalysis(inputPath, options = {}) {
 /**
  * @param {string} inputPath
  * @param {{ sourcePath?: string|null, dryRun?: boolean }} [options]
- * @returns {{ ok: boolean, dryRun: boolean, projectRoot: string, workspaceRoot: string, topogramRoot: string, sourcePath: string, provenancePath: string, previousImportStatus: string, currentImportStatus: string, tracks: string[], sourceFiles: number, sourceDiff: Record<string, any>, removedCandidateFiles: Record<string, number>, rawCandidateFiles: number, reconcileFiles: number, writtenFiles: string[], plannedFiles: string[], candidateCounts: Record<string, number>, candidateCountDeltas: Record<string, any>, adoptionPlanDeltas: Record<string, any>, receiptVerification: Record<string, any>, refreshMetadata: Record<string, any>|null, nextCommands: string[] }}
+ * @returns {{ ok: boolean, dryRun: boolean, projectRoot: string, workspaceRoot: string, topogramRoot: string, sourcePath: string, provenancePath: string, previousExtractStatus: string, currentExtractStatus: string, tracks: string[], sourceFiles: number, sourceDiff: Record<string, any>, removedCandidateFiles: Record<string, number>, rawCandidateFiles: number, reconcileFiles: number, writtenFiles: string[], plannedFiles: string[], candidateCounts: Record<string, number>, candidateCountDeltas: Record<string, any>, adoptionPlanDeltas: Record<string, any>, receiptVerification: Record<string, any>, refreshMetadata: Record<string, any>|null, nextCommands: string[] }}
  */
 export function buildBrownfieldImportRefreshPayload(inputPath, options = {}) {
   const analysis = buildBrownfieldImportRefreshAnalysis(inputPath, options);
   const dryRun = Boolean(options.dryRun);
   let provenancePath = analysis.provenancePath;
-  let currentImportStatus = dryRun ? analysis.previousImportStatus : "unknown";
+  let currentExtractStatus = dryRun ? analysis.previousImportStatus : "unknown";
   /** @type {string[]} */
   let writtenFiles = [];
   /** @type {AnyRecord|null} */
@@ -391,7 +392,7 @@ export function buildBrownfieldImportRefreshPayload(inputPath, options = {}) {
       files: collectImportSourceFileRecords(analysis.sourcePath, { excludeRoots: [analysis.projectRoot] })
     });
     provenancePath = provenance.path;
-    currentImportStatus = buildTopogramImportStatus(analysis.projectRoot).status;
+    currentExtractStatus = buildTopogramImportStatus(analysis.projectRoot).status;
     writtenFiles = [
       TOPOGRAM_IMPORT_FILE,
       ...rawCandidateFiles.map((filePath) => `${DEFAULT_TOPO_FOLDER_NAME}/${filePath}`),
@@ -402,15 +403,15 @@ export function buildBrownfieldImportRefreshPayload(inputPath, options = {}) {
     analysis.reconcileFiles = reconcileFiles.length;
   }
   return {
-    ok: dryRun || currentImportStatus === "clean",
+    ok: dryRun || currentExtractStatus === "clean",
     dryRun,
     projectRoot: analysis.projectRoot,
     workspaceRoot: analysis.topogramRoot,
     topogramRoot: analysis.topogramRoot,
     sourcePath: analysis.sourcePath,
     provenancePath,
-    previousImportStatus: analysis.previousImportStatus,
-    currentImportStatus,
+    previousExtractStatus: analysis.previousImportStatus,
+    currentExtractStatus,
     tracks: analysis.tracks,
     sourceFiles: analysis.sourceFiles,
     sourceDiff: analysis.sourceDiff,
@@ -426,11 +427,11 @@ export function buildBrownfieldImportRefreshPayload(inputPath, options = {}) {
     refreshMetadata,
     nextCommands: [
       dryRun
-        ? `topogram import refresh ${importProjectCommandPath(analysis.projectRoot)}`
-        : `topogram import check ${importProjectCommandPath(analysis.projectRoot)}`,
-      `topogram import plan ${importProjectCommandPath(analysis.projectRoot)}`,
-      `topogram import status ${importProjectCommandPath(analysis.projectRoot)}`,
-      `topogram import history ${importProjectCommandPath(analysis.projectRoot)} --verify`
+        ? `topogram extract refresh ${importProjectCommandPath(analysis.projectRoot)}`
+        : `topogram extract check ${importProjectCommandPath(analysis.projectRoot)}`,
+      `topogram extract plan ${importProjectCommandPath(analysis.projectRoot)}`,
+      `topogram extract status ${importProjectCommandPath(analysis.projectRoot)}`,
+      `topogram extract history ${importProjectCommandPath(analysis.projectRoot)} --verify`
     ]
   };
 }
@@ -440,12 +441,12 @@ export function buildBrownfieldImportRefreshPayload(inputPath, options = {}) {
  * @returns {void}
  */
 export function printBrownfieldImportRefresh(payload) {
-  console.log(`${payload.dryRun ? "Previewed" : "Refreshed"} brownfield import candidates for ${payload.projectRoot}.`);
+  console.log(`${payload.dryRun ? "Previewed" : "Refreshed"} brownfield extraction candidates for ${payload.projectRoot}.`);
   console.log(`Source: ${payload.sourcePath}`);
   console.log(`Topogram: ${payload.topogramRoot}`);
-  console.log(`Import provenance: ${payload.provenancePath}`);
-  console.log(`Previous source status: ${payload.previousImportStatus}`);
-  console.log(`Current source status: ${payload.currentImportStatus}`);
+  console.log(`Extraction provenance: ${payload.provenancePath}`);
+  console.log(`Previous source status: ${payload.previousExtractStatus}`);
+  console.log(`Current source status: ${payload.currentExtractStatus}`);
   console.log(`Source diff: changed=${payload.sourceDiff.counts.changed}, added=${payload.sourceDiff.counts.added}, removed=${payload.sourceDiff.counts.removed}`);
   console.log(`Tracked source files: ${payload.sourceFiles}`);
   console.log(`Raw candidate files: ${payload.rawCandidateFiles}`);

package/src/cli/commands/import/status-history.js

@@ -33,7 +33,7 @@ export function buildBrownfieldImportStatusPayload(inputPath) {
     projectRoot: artifacts.projectRoot,
     workspaceRoot: artifacts.topogramRoot,
     topogramRoot: artifacts.topogramRoot,
-    import: importCheck.import,
+    extract: importCheck.extract,
     topogram: importCheck.topogram,
     adoption: {
       status: adoptionStatus,
@@ -52,7 +52,7 @@ export function buildBrownfieldImportStatusPayload(inputPath) {
  * @returns {void}
  */
 export function printBrownfieldImportStatus(payload) {
-  console.log(`Import status: ${payload.import.status}`);
+  console.log(`Extraction status: ${payload.extract.status}`);
   console.log(`Topogram check: ${payload.topogram.ok ? "passed" : "failed"}`);
   console.log(`Adoption: ${payload.adoption.summary.appliedItemCount} applied, ${payload.adoption.summary.pendingItemCount} pending, ${payload.adoption.summary.blockedItemCount} blocked`);
   const next = payload.adoption.nextCommand;
@@ -134,7 +134,7 @@ export function verifyImportAdoptionReceipts(projectRoot, receipts) {
     summary,
     files,
     auditOnly: true,
-    note: "History verification is audit-only. Imported/adopted Topogram files are project-owned, and edits do not make the workspace invalid."
+    note: "History verification is audit-only. Extracted/adopted Topogram files are project-owned, and edits do not make the workspace invalid."
   };
 }
 
@@ -175,7 +175,7 @@ export function buildBrownfieldImportHistoryPayload(inputPath, options = {}) {
  * @returns {void}
  */
 export function printBrownfieldImportHistory(payload) {
-  console.log(`Import adoption history for ${payload.projectRoot}`);
+  console.log(`Adoption history for ${payload.projectRoot}`);
   console.log(`Receipts: ${payload.summary.receiptCount}`);
   console.log(`Forced writes: ${payload.summary.forcedWriteCount}`);
   if (!payload.exists) {

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

@@ -79,23 +79,23 @@ function importedProjectConfig() {
  */
 function importedWorkspaceReadme(sourceRoot, targetRoot, importSummary) {
   return [
-    "# Imported Topogram Workspace",
+    "# Extracted Topogram Workspace",
     "",
-    "This workspace was created from a brownfield app import.",
+    "This workspace was created from a brownfield app extraction.",
     "",
-    `- Imported source: \`${sourceRoot}\``,
+    `- Extracted source: \`${sourceRoot}\``,
     `- Target workspace: \`${targetRoot}\``,
     `- Tracks: ${(importSummary.tracks || []).join(", ") || "none"}`,
     `- Provenance: \`${TOPOGRAM_IMPORT_FILE}\``,
     "",
-    "Imported Topogram artifacts are project-owned after creation. Edit them directly, promote candidates deliberately, and run `topogram check` before generation or maintained-app work.",
+    "Extracted Topogram artifacts are project-owned after creation. Edit them directly, promote candidates deliberately, and run `topogram check` before generation or maintained-app work.",
     "",
     "Useful commands:",
     "",
     "```sh",
-    "topogram import check",
+    "topogram extract check",
     "topogram check",
-    `topogram query import-plan ./${DEFAULT_TOPO_FOLDER_NAME}`,
+    `topogram query extract-plan ./${DEFAULT_TOPO_FOLDER_NAME}`,
     "```",
     ""
   ].join("\n");
@@ -149,24 +149,29 @@ export function countFilesRecursive(rootPath) {
 /**
  * @param {string} sourcePath
  * @param {string} targetPath
- * @param {{ from?: string|null }} [options]
+ * @param {{ from?: string|null, extractorSpecs?: string[], extractorPolicyPath?: string|null, cwd?: string|null }} [options]
  * @returns {{ ok: boolean, sourcePath: string, targetPath: string, workspaceRoot: string, topogramRoot: string, projectConfigPath: string, provenancePath: string, tracks: string[], sourceFiles: number, rawCandidateFiles: number, reconcileFiles: number, writtenFiles: string[], candidateCounts: Record<string, number>, nextCommands: string[] }}
  */
 export function buildBrownfieldImportWorkspacePayload(sourcePath, targetPath, options = {}) {
   const sourceRoot = path.resolve(sourcePath);
   const targetRoot = path.resolve(targetPath);
   if (!fs.existsSync(sourceRoot) || !fs.statSync(sourceRoot).isDirectory()) {
-    throw new Error(`Cannot import missing app directory '${sourcePath}'.`);
+    throw new Error(`Cannot extract missing app directory '${sourcePath}'.`);
   }
   if (sourceRoot === targetRoot) {
-    throw new Error("Refusing to import into the same directory as the brownfield app.");
+    throw new Error("Refusing to extract into the same directory as the brownfield app.");
   }
   ensureEmptyImportTarget(targetRoot);
 
   const topogramRoot = path.join(targetRoot, DEFAULT_TOPO_FOLDER_NAME);
   fs.mkdirSync(topogramRoot, { recursive: true });
   const sourceFiles = collectImportSourceFileRecords(sourceRoot, { excludeRoots: [targetRoot] });
-  const importResult = runWorkflow("import-app", sourceRoot, { from: options.from || null });
+  const importResult = runWorkflow("import-app", sourceRoot, {
+    from: options.from || null,
+    extractorSpecs: options.extractorSpecs || [],
+    extractorPolicyPath: options.extractorPolicyPath || null,
+    cwd: options.cwd || process.cwd()
+  });
   const rawCandidateFiles = writeRelativeFiles(topogramRoot, importResult.files || {});
 
   const projectConfigPath = path.join(targetRoot, "topogram.project.json");
@@ -182,6 +187,7 @@ export function buildBrownfieldImportWorkspacePayload(sourcePath, targetPath, op
     tracks: importResult.summary.tracks || [],
     findingsCount: importResult.summary.findings_count || 0,
     candidateCounts,
+    extractorPackages: importResult.summary.package_extractors || [],
     files: sourceFiles
   });
   const writtenFiles = [
@@ -206,12 +212,12 @@ export function buildBrownfieldImportWorkspacePayload(sourcePath, targetPath, op
     writtenFiles,
     candidateCounts,
     nextCommands: [
-      "topogram import check",
-      "topogram import plan",
-      "topogram import adopt bundle:task --dry-run",
-      "topogram import status",
+      "topogram extract check",
+      "topogram extract plan",
+      "topogram adopt bundle:task --dry-run",
+      "topogram extract status",
       "topogram check",
-      `topogram query import-plan ./${DEFAULT_TOPO_FOLDER_NAME}`
+      `topogram query extract-plan ./${DEFAULT_TOPO_FOLDER_NAME}`
     ]
   };
 }
@@ -221,15 +227,15 @@ export function buildBrownfieldImportWorkspacePayload(sourcePath, targetPath, op
  * @returns {void}
  */
 export function printBrownfieldImportWorkspace(payload) {
-  console.log(`Imported brownfield app to ${payload.targetPath}.`);
+  console.log(`Extracted brownfield app to ${payload.targetPath}.`);
   console.log(`Source: ${payload.sourcePath}`);
   console.log(`Topogram: ${payload.topogramRoot}`);
   console.log(`Project config: ${payload.projectConfigPath}`);
-  console.log(`Import provenance: ${payload.provenancePath}`);
+  console.log(`Extraction provenance: ${payload.provenancePath}`);
   console.log(`Tracked source files: ${payload.sourceFiles}`);
   console.log(`Raw candidate files: ${payload.rawCandidateFiles}`);
   console.log(`Reconcile proposal files: ${payload.reconcileFiles}`);
-  console.log("Imported Topogram artifacts are project-owned after creation; source hashes record the app evidence trusted at import time.");
+  console.log("Extracted Topogram artifacts are project-owned after creation; source hashes record the app evidence trusted at extraction time.");
   console.log("");
   console.log("Next steps:");
   console.log(`  cd ${shellCommandArg(path.relative(process.cwd(), payload.targetPath) || ".")}`);

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

@@ -11,6 +11,7 @@ import {
   buildBrownfieldImportRefreshPayload,
   buildBrownfieldImportStatusPayload,
   buildBrownfieldImportWorkspacePayload,
+  printAdoptHelp,
   printBrownfieldImportAdopt,
   printBrownfieldImportAdoptList,
   printBrownfieldImportCheck,
@@ -20,11 +21,11 @@ import {
   printBrownfieldImportRefresh,
   printBrownfieldImportStatus,
   printBrownfieldImportWorkspace,
-  printImportHelp
+  printExtractHelp
 } from "./import.js";
 
 /**
- * @param {{ commandArgs: Record<string, any>, inputPath: string|null|undefined, outPath?: string|null, fromValue?: string|null, reasonValue?: string|null, refreshAdopted?: boolean, dryRun?: boolean, write?: boolean, force?: boolean, json?: boolean }} context
+ * @param {{ commandArgs: Record<string, any>, inputPath: string|null|undefined, outPath?: string|null, fromValue?: string|null, extractorSpecs?: string[], extractorPolicyPath?: string|null, reasonValue?: string|null, refreshAdopted?: boolean, dryRun?: boolean, write?: boolean, force?: boolean, json?: boolean }} context
  * @returns {number}
  */
 export function runImportCommand(context) {
@@ -33,6 +34,8 @@ export function runImportCommand(context) {
     inputPath,
     outPath = null,
     fromValue = null,
+    extractorSpecs = [],
+    extractorPolicyPath = null,
     reasonValue = null,
     refreshAdopted = false,
     dryRun = false,
@@ -45,10 +48,10 @@ export function runImportCommand(context) {
   if (command === "workspace") {
     if (!outPath) {
       console.error("Missing required --out <target>.");
-      printImportHelp();
+      printExtractHelp();
       return 1;
     }
-    const payload = buildBrownfieldImportWorkspacePayload(inputPath || "", outPath, { from: fromValue });
+    const payload = buildBrownfieldImportWorkspacePayload(inputPath || "", outPath, { from: fromValue, extractorSpecs, extractorPolicyPath, cwd: process.cwd() });
     if (json) {
       console.log(stableStringify(payload));
     } else {
@@ -110,12 +113,12 @@ export function runImportCommand(context) {
   if (command === "adopt") {
     if (!commandArgs.importAdoptSelector || commandArgs.importAdoptSelector.startsWith("-")) {
       console.error("Missing required <selector>.");
-      printImportHelp();
+      printAdoptHelp();
       return 1;
     }
     if (write && dryRun) {
       console.error("Use either --dry-run or --write, not both.");
-      printImportHelp();
+      printAdoptHelp();
       return 1;
     }
     const payload = buildBrownfieldImportAdoptPayload(commandArgs.importAdoptSelector, inputPath || ".", {
@@ -153,5 +156,5 @@ export function runImportCommand(context) {
     return payload.ok ? 0 : 1;
   }
 
-  throw new Error(`Unknown import command '${command}'`);
+  throw new Error(`Unknown extract/adopt command '${command}'`);
 }

package/src/cli/commands/import.js

@@ -1,6 +1,9 @@
 // @ts-check
 
-export { printImportHelp } from "./import/help.js";
+export {
+  printAdoptHelp,
+  printExtractHelp
+} from "./import/help.js";
 export {
   buildBrownfieldImportWorkspacePayload,
   printBrownfieldImportWorkspace

package/src/cli/commands/init.js

@@ -0,0 +1,67 @@
+// @ts-check
+
+import path from "node:path";
+
+import { stableStringify } from "../../format.js";
+import { initTopogramProject } from "../../init-project.js";
+
+/**
+ * @param {string} projectRoot
+ * @param {string} cwd
+ * @returns {string}
+ */
+function displayProjectRoot(projectRoot, cwd) {
+  const relative = path.relative(cwd, projectRoot);
+  return !relative || relative.startsWith("..")
+    ? projectRoot
+    : relative.split(path.sep).join("/");
+}
+
+/**
+ * @param {ReturnType<typeof initTopogramProject>} result
+ * @param {string} cwd
+ * @returns {void}
+ */
+export function printInitProjectResult(result, cwd) {
+  console.log(`Initialized Topogram workspace at ${result.projectRoot}.`);
+  console.log("Workspace: topo/");
+  console.log("Project config: topogram.project.json");
+  console.log("Output ownership: maintained (.)");
+  console.log("Template: none");
+  console.log("Generated app output: none");
+  console.log(`SDLC: ${result.sdlc.enabled ? "adopted/enforced" : "not adopted"}`);
+  if (result.created.length > 0) {
+    console.log(`Created: ${result.created.join(", ")}`);
+  }
+  if (result.skipped.length > 0) {
+    console.log(`Skipped existing files: ${result.skipped.join(", ")}`);
+  }
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  cd ${displayProjectRoot(result.projectRoot, cwd)}`);
+  console.log("  topogram agent brief --json");
+  console.log("  topogram check --json");
+  console.log("  topogram query list --json");
+  if (result.sdlc.enabled) {
+    console.log("  topogram sdlc policy explain --json");
+    console.log("  topogram sdlc prep commit . --json");
+  } else {
+    console.log("  topogram sdlc policy init .");
+  }
+  console.log("  topogram emit <target> ./topo --json");
+}
+
+/**
+ * @param {string} inputPath
+ * @param {{ json?: boolean, cwd?: string, withSdlc?: boolean }} [options]
+ * @returns {number}
+ */
+export function runInitProjectCommand(inputPath, options = {}) {
+  const result = initTopogramProject({ targetPath: inputPath || ".", withSdlc: Boolean(options.withSdlc) });
+  if (options.json) {
+    console.log(stableStringify(result));
+  } else {
+    printInitProjectResult(result, options.cwd || process.cwd());
+  }
+  return 0;
+}

package/src/cli/commands/query/{import-adopt.js → extract-adopt.js}

@@ -38,7 +38,7 @@ export function buildImportPlanForContext(context, queryFamily) {
   }
   const adoptionPlan = readJson(planPath);
   const ast = parsePath(context.inputPath);
-  const taskModeResult = buildTaskMode(ast, {}, "import-adopt");
+  const taskModeResult = buildTaskMode(ast, {}, "extract-adopt");
   if (!resultOk(taskModeResult)) {
     return taskModeResult;
   }
@@ -74,7 +74,7 @@ export function buildImportAdoptAgentContext(context, queryFamily) {
   const topogramRoot = normalizeTopogramPath(context.inputPath);
   const artifacts = requireReconcileArtifacts(topogramRoot, queryFamily);
   const ast = parsePath(context.inputPath);
-  const taskModeResult = buildTaskMode(ast, {}, "import-adopt");
+  const taskModeResult = buildTaskMode(ast, {}, "extract-adopt");
   if (!resultOk(taskModeResult)) {
     return taskModeResult;
   }