@myvillage/cli 1.3.0 → 1.5.1

package/src/commands/soulprint.js

@@ -0,0 +1,1379 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import axios from 'axios';
+import pLimit from 'p-limit';
+import { spawn } from 'child_process';
+import { createInterface } from 'readline';
+import { createHash } from 'crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  statSync,
+  createReadStream,
+  createWriteStream,
+} from 'fs';
+import { join, resolve, relative, extname, basename } from 'path';
+import { pipeline } from 'stream/promises';
+import { parse as parseYaml } from 'yaml';
+import { createRequire } from 'module';
+import { isAuthenticated } from '../utils/auth.js';
+import { brand, villageSpinner, success, error, info, header, stripAnsi } from '../utils/brand.js';
+import { relativeTime, truncate } from '../utils/formatters.js';
+import {
+  listDatasets,
+  getDataset,
+  getDatasetDownload,
+  createJob,
+  listJobs,
+  getJob,
+  updateJobStatus,
+  completeJob,
+  failJob,
+  listModels,
+  getModel,
+  publishModel,
+  ingestText,
+  ingestStructured,
+  prepareIngestion,
+  completeIngestion,
+  getUploadUrls,
+  getScriptsManifest,
+} from '../utils/soulprint-api.js';
+import {
+  getSoulprintDir,
+  getDatasetsDir,
+  getModelsDir,
+  getConfigsDir,
+  getLogsDir,
+  getVenvDir,
+  getScriptsDir,
+  isWorkspaceInitialized,
+  readWorkspaceConfig,
+  writeWorkspaceConfig,
+  getLocalDatasetDir,
+  isDatasetDownloaded,
+  getPythonPath,
+  isPythonAvailable,
+  getPythonVersion,
+  detectGPU,
+  getMachineInfo,
+  getJobOutputDir,
+  getJobLogFile,
+  appendJobLog,
+} from '../utils/soulprint-workspace.js';
+
+const require = createRequire(import.meta.url);
+const { version: cliVersion } = require('../../package.json');
+
+// ── Helpers ────────────────────────────────────────────
+
+function padRight(str, len) {
+  const visible = stripAnsi(String(str));
+  if (visible.length >= len) return String(str);
+  return String(str) + ' '.repeat(len - visible.length);
+}
+
+function formatStatus(status) {
+  const map = {
+    COLLECTING: chalk.cyan,
+    READY: brand.green,
+    TRAINING: chalk.yellow,
+    ARCHIVED: brand.teal,
+    CREATED: brand.teal,
+    DOWNLOADING: chalk.cyan,
+    PREPARING: chalk.cyan,
+    EVALUATING: chalk.yellow,
+    COMPLETED: brand.green,
+    FAILED: chalk.red,
+    CANCELLED: brand.teal,
+    DRAFT: brand.teal,
+    VALIDATED: brand.green,
+    PUBLISHED: brand.green,
+    REJECTED: chalk.red,
+  };
+  const colorFn = map[status] || brand.teal;
+  return colorFn(status);
+}
+
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1048576) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1073741824) return `${(bytes / 1048576).toFixed(1)} MB`;
+  return `${(bytes / 1073741824).toFixed(1)} GB`;
+}
+
+function formatProgress(progress) {
+  if (progress == null) return brand.teal('--');
+  const pct = Math.round(progress * 100);
+  return `${pct}%`;
+}
+
+const TYPE_EXTENSIONS = {
+  text: ['.json', '.jsonl'],
+  image: ['.png', '.jpg', '.jpeg', '.webp', '.bmp', '.gif'],
+  audio: ['.wav', '.mp3', '.flac', '.ogg', '.m4a'],
+  structured: ['.json', '.jsonl', '.csv'],
+  multimodal: ['.json', '.jsonl'],
+};
+
+const MIME_TYPES = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.bmp': 'image/bmp',
+  '.gif': 'image/gif',
+  '.wav': 'audio/wav',
+  '.mp3': 'audio/mpeg',
+  '.flac': 'audio/flac',
+  '.ogg': 'audio/ogg',
+  '.m4a': 'audio/mp4',
+  '.json': 'application/json',
+  '.jsonl': 'application/jsonl',
+  '.csv': 'text/csv',
+};
+
+const VALID_METHODS = {
+  text: ['openai-finetune', 'full-finetune', 'lora'],
+  image: ['lora', 'dreambooth'],
+  audio: ['whisper-finetune', 'wav2vec-finetune'],
+  structured: ['llm-finetune', 'gradient-boost', 'sklearn-pipeline'],
+  multimodal: ['clip-finetune'],
+};
+
+const METHOD_SCRIPTS = {
+  'openai-finetune': 'text/finetune_openai.py',
+  'full-finetune': 'text/finetune_local.py',
+  'lora:text': 'text/finetune_local.py',
+  'lora:image': 'image/lora_sdxl.py',
+  'dreambooth': 'image/dreambooth.py',
+  'whisper-finetune': 'audio/whisper_finetune.py',
+  'wav2vec-finetune': 'audio/wav2vec_finetune.py',
+  'llm-finetune': 'structured/llm_classifier.py',
+  'gradient-boost': 'structured/tabular_train.py',
+  'sklearn-pipeline': 'structured/tabular_train.py',
+  'clip-finetune': 'multimodal/clip_finetune.py',
+};
+
+function collectFiles(dir, extensions, recursive = false) {
+  const files = [];
+  function walk(currentDir) {
+    const entries = readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(currentDir, entry.name);
+      if (entry.isDirectory() && recursive) {
+        walk(fullPath);
+      } else if (entry.isFile()) {
+        const ext = extname(entry.name).toLowerCase();
+        if (extensions.includes(ext)) {
+          const stat = statSync(fullPath);
+          files.push({
+            filename: entry.name,
+            fullPath,
+            relativePath: relative(dir, fullPath),
+            size: stat.size,
+            mimeType: MIME_TYPES[ext] || 'application/octet-stream',
+          });
+        }
+      }
+    }
+  }
+  walk(dir);
+  return files;
+}
+
+async function computeSHA256(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = createHash('sha256');
+    const stream = createReadStream(filePath);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('end', () => resolve(`sha256:${hash.digest('hex')}`));
+    stream.on('error', reject);
+  });
+}
+
+function scanArtifacts(dir) {
+  const files = [];
+  function walk(currentDir) {
+    const entries = readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile()) {
+        const stat = statSync(fullPath);
+        files.push({
+          path: relative(dir, fullPath),
+          fullPath,
+          size: stat.size,
+        });
+      }
+    }
+  }
+  walk(dir);
+  return files;
+}
+
+// ── AUTH GUARD ──────────────────────────────────────────
+
+function requireAuth() {
+  if (!isAuthenticated()) {
+    console.log(chalk.red(`  \u2717 Authentication required. Run ${brand.gold("'myvillage login'")} first.\n`));
+    return false;
+  }
+  return true;
+}
+
+function requireWorkspace() {
+  if (!isWorkspaceInitialized()) {
+    console.log(chalk.red(`  \u2717 SoulPrint workspace not initialized. Run ${brand.gold("'myvillage soulprint init'")} first.\n`));
+    return false;
+  }
+  return true;
+}
+
+// ════════════════════════════════════════════════════════
+//  INIT
+// ════════════════════════════════════════════════════════
+
+export async function soulprintInitCommand(options) {
+  if (!requireAuth()) return;
+
+  try {
+    if (isWorkspaceInitialized()) {
+      const { reinit } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'reinit',
+        message: 'SoulPrint workspace already exists. Reinitialize?',
+        default: false,
+      }]);
+      if (!reinit) {
+        info('Cancelled.\n');
+        return;
+      }
+    }
+
+    header('Initializing SoulPrint Studio workspace');
+
+    // Check prerequisites
+    console.log('  Checking prerequisites:');
+    const pythonAvailable = isPythonAvailable();
+    const pythonVer = getPythonVersion();
+    if (pythonAvailable) {
+      success(`${pythonVer} found`);
+    } else {
+      error('Python 3.10+ required. Install it and try again.\n');
+      return;
+    }
+
+    const gpu = detectGPU();
+    if (gpu.type === 'cuda') {
+      success(`CUDA detected (${gpu.name}, ${gpu.vram})`);
+    } else if (gpu.type === 'mps') {
+      success(`MPS available (${gpu.name}, ${gpu.vram})`);
+    } else {
+      info('\u2717 No GPU detected (CPU-only training available)');
+    }
+
+    console.log();
+
+    // Create directory tree
+    const spDir = getSoulprintDir();
+    const dirs = [
+      getDatasetsDir(),
+      getModelsDir(),
+      getConfigsDir(),
+      getLogsDir(),
+      getScriptsDir(),
+    ];
+
+    console.log(`  Creating workspace at ${brand.teal(spDir)}/`);
+    for (const dir of dirs) {
+      mkdirSync(dir, { recursive: true });
+      success(basename(dir) + '/');
+    }
+
+    console.log();
+
+    // Python venv
+    if (!options.skipPython) {
+      const venvDir = getVenvDir();
+      const spinner = villageSpinner('Creating Python virtual environment...').start();
+      try {
+        await new Promise((res, rej) => {
+          const proc = spawn('python3', ['-m', 'venv', venvDir], { stdio: 'pipe' });
+          proc.on('close', (code) => code === 0 ? res() : rej(new Error(`venv creation failed (exit ${code})`)));
+          proc.on('error', rej);
+        });
+        spinner.succeed('Python environment created at ' + brand.teal(venvDir));
+      } catch (err) {
+        spinner.fail(`Python venv creation failed: ${err.message}`);
+        info('You can skip this with --skip-python and install dependencies manually.\n');
+        return;
+      }
+    } else {
+      info('Skipping Python venv setup (--skip-python)');
+    }
+
+    // Download training scripts
+    if (!options.skipScripts) {
+      const spinner = villageSpinner('Downloading training scripts...').start();
+      try {
+        const manifest = await getScriptsManifest();
+        const scriptsDir = getScriptsDir();
+        for (const file of manifest.files || []) {
+          const destDir = join(scriptsDir, file.path.split('/').slice(0, -1).join('/'));
+          mkdirSync(destDir, { recursive: true });
+          const dest = join(scriptsDir, file.path);
+          const response = await axios.get(file.url, { responseType: 'arraybuffer' });
+          writeFileSync(dest, response.data);
+        }
+        spinner.succeed(`Training scripts v${manifest.version || '1.0.0'} downloaded`);
+      } catch (err) {
+        spinner.warn(`Could not download training scripts: ${err.message}`);
+        info('You can download them later or place scripts manually in ' + getScriptsDir());
+      }
+    } else {
+      info('Skipping script download (--skip-scripts)');
+    }
+
+    // Write workspace config
+    writeWorkspaceConfig({
+      version: 1,
+      initializedAt: new Date().toISOString(),
+      cliVersion,
+      pythonVersion: pythonVer,
+      gpu: { type: gpu.type, name: gpu.name, vram: gpu.vram },
+      venvPath: getVenvDir(),
+    });
+
+    console.log();
+    success('SoulPrint Studio workspace initialized!');
+    console.log();
+    console.log('  Next steps:');
+    console.log(`    ${brand.gold('myvillage soulprint datasets list')}       Browse available datasets`);
+    console.log(`    ${brand.gold('myvillage soulprint datasets pull <slug>')} Download a dataset`);
+    console.log(`    ${brand.gold('myvillage soulprint train --help')}         See training options`);
+    console.log();
+  } catch (err) {
+    if (err.isTtyError) {
+      error('Prompts cannot be rendered in this environment.\n');
+      return;
+    }
+    error(`Initialization failed: ${err.message}\n`);
+  }
+}
+
+// ════════════════════════════════════════════════════════
+//  INGEST
+// ════════════════════════════════════════════════════════
+
+export async function soulprintIngestCommand(path, options) {
+  if (!requireAuth()) return;
+
+  try {
+    const dataType = options.type?.toUpperCase();
+    const typeKey = options.type?.toLowerCase();
+    if (!TYPE_EXTENSIONS[typeKey]) {
+      error(`Invalid type "${options.type}". Must be: text, image, audio, structured, multimodal\n`);
+      return;
+    }
+
+    const resolvedPath = resolve(path);
+    if (!existsSync(resolvedPath)) {
+      error(`Path not found: ${resolvedPath}\n`);
+      return;
+    }
+
+    // Resolve files
+    const extensions = TYPE_EXTENSIONS[typeKey];
+    let files;
+    const stat = statSync(resolvedPath);
+    if (stat.isDirectory()) {
+      console.log(`\n  Scanning ${brand.teal(resolvedPath)} for ${typeKey} files...`);
+      files = collectFiles(resolvedPath, extensions, !!options.recursive);
+      if (options.glob) {
+        const pattern = options.glob.toLowerCase();
+        files = files.filter(f => f.filename.toLowerCase().endsWith(pattern.replace('*', '')));
+      }
+    } else {
+      files = [{
+        filename: basename(resolvedPath),
+        fullPath: resolvedPath,
+        relativePath: basename(resolvedPath),
+        size: stat.size,
+        mimeType: MIME_TYPES[extname(resolvedPath).toLowerCase()] || 'application/octet-stream',
+      }];
+    }
+
+    if (files.length === 0) {
+      error(`No ${typeKey} files found. Expected: ${extensions.join(', ')}\n`);
+      return;
+    }
+
+    const totalSize = files.reduce((sum, f) => sum + f.size, 0);
+    info(`Found ${files.length} files (${formatBytes(totalSize)})`);
+
+    // Load companion metadata
+    let captions = null;
+    if (options.captions) {
+      const captionsPath = resolve(options.captions);
+      if (!existsSync(captionsPath)) {
+        error(`Captions file not found: ${captionsPath}\n`);
+        return;
+      }
+      const raw = readFileSync(captionsPath, 'utf-8');
+      try {
+        captions = JSON.parse(raw); // JSON map { filename: caption }
+      } catch {
+        captions = raw.split('\n').filter(l => l.trim()); // line-based
+      }
+      const count = Array.isArray(captions) ? captions.length : Object.keys(captions).length;
+      info(`Captions loaded: ${count} entries from ${basename(captionsPath)}`);
+    }
+
+    let transcriptions = null;
+    if (options.transcriptions) {
+      const transPath = resolve(options.transcriptions);
+      if (!existsSync(transPath)) {
+        error(`Transcriptions file not found: ${transPath}\n`);
+        return;
+      }
+      const raw = readFileSync(transPath, 'utf-8');
+      try {
+        transcriptions = JSON.parse(raw);
+      } catch {
+        transcriptions = raw.split('\n').filter(l => l.trim());
+      }
+    }
+
+    // Validate dataset
+    const spinner = villageSpinner('Validating target dataset...').start();
+    let dataset;
+    try {
+      dataset = await getDataset(options.dataset);
+      spinner.stop();
+    } catch (err) {
+      spinner.fail(`Dataset "${options.dataset}" not found.`);
+      info(`Run ${brand.gold("'myvillage soulprint datasets list'")} to see available datasets.\n`);
+      return;
+    }
+
+    if (dataset.dataType !== dataType) {
+      error(`Dataset "${options.dataset}" is type ${dataset.dataType}, but --type ${typeKey} was specified.\n`);
+      return;
+    }
+    if (dataset.status !== 'COLLECTING') {
+      error(`Dataset "${options.dataset}" is ${dataset.status}. Only COLLECTING datasets accept new data.\n`);
+      return;
+    }
+
+    console.log(`\n  Target dataset: ${brand.gold(dataset.slug)} (${dataset.dataType}, ${dataset.status})\n`);
+
+    // Dry run
+    if (options.dryRun) {
+      console.log(brand.teal('  DRY RUN \u2014 nothing will be uploaded\n'));
+      console.log(`  Files found: ${files.length}`);
+      console.log(`  Total size:  ${formatBytes(totalSize)}`);
+      const extCounts = {};
+      for (const f of files) {
+        const ext = extname(f.filename).toLowerCase();
+        extCounts[ext] = (extCounts[ext] || 0) + 1;
+      }
+      console.log(`  Extensions:  ${Object.entries(extCounts).map(([e, n]) => `${e} (${n})`).join(', ')}`);
+      console.log();
+      return;
+    }
+
+    // Route by type
+    if (typeKey === 'text' || typeKey === 'structured') {
+      await ingestInlineData(files, typeKey, options, dataset);
+    } else {
+      await ingestFileData(files, typeKey, options, dataset, captions, transcriptions);
+    }
+  } catch (err) {
+    const message = err.response?.data?.error || err.message;
+    error(`Ingestion failed: ${message}\n`);
+  }
+}
+
+async function ingestInlineData(files, typeKey, options, dataset) {
+  // Read and parse items from files
+  let allItems = [];
+  for (const file of files) {
+    const raw = readFileSync(file.fullPath, 'utf-8');
+    const ext = extname(file.filename).toLowerCase();
+    if (ext === '.jsonl') {
+      const lines = raw.split('\n').filter(l => l.trim());
+      allItems.push(...lines.map(l => JSON.parse(l)));
+    } else if (ext === '.json') {
+      const parsed = JSON.parse(raw);
+      allItems.push(...(Array.isArray(parsed) ? parsed : [parsed]));
+    } else if (ext === '.csv') {
+      const lines = raw.split('\n').filter(l => l.trim());
+      if (lines.length < 2) return;
+      const headers = lines[0].split(',').map(h => h.trim());
+      for (let i = 1; i < lines.length; i++) {
+        const values = lines[i].split(',').map(v => v.trim());
+        const row = {};
+        headers.forEach((h, idx) => { row[h] = values[idx]; });
+        allItems.push(row);
+      }
+    }
+  }
+
+  console.log(`  Ingesting ${allItems.length} items...\n`);
+
+  const batchSize = 1000;
+  let ingested = 0;
+  for (let i = 0; i < allItems.length; i += batchSize) {
+    const batch = allItems.slice(i, i + batchSize);
+    const payload = {
+      source: options.source || 'CLI',
+      dataset: dataset.slug,
+      items: batch,
+    };
+    if (typeKey === 'text') {
+      await ingestText(payload);
+    } else {
+      await ingestStructured(payload);
+    }
+    ingested += batch.length;
+    const pct = Math.round((ingested / allItems.length) * 100);
+    process.stdout.write(`\r  [${'\u2588'.repeat(Math.floor(pct / 2.5))}${'\u2591'.repeat(40 - Math.floor(pct / 2.5))}] ${pct}% (${ingested.toLocaleString()}/${allItems.length.toLocaleString()})`);
+  }
+
+  console.log();
+  console.log();
+  success(`${allItems.length.toLocaleString()} items ingested into ${dataset.slug}`);
+  console.log(`\n  View in Studio: ${brand.teal(`https://soulprint-studio.myvillageproject.ai/datasets/${dataset.slug}`)}\n`);
+}
+
+async function ingestFileData(files, typeKey, options, dataset, captions, transcriptions) {
+  const concurrency = parseInt(options.concurrency) || 5;
+  const limit = pLimit(concurrency);
+
+  // Build metadata
+  const metadata = {};
+  if (captions) {
+    if (Array.isArray(captions)) {
+      metadata.captions = captions;
+    } else {
+      metadata.captions = files.map(f => captions[f.filename] || null);
+    }
+  }
+  if (transcriptions) {
+    if (Array.isArray(transcriptions)) {
+      metadata.transcriptions = transcriptions;
+    } else {
+      metadata.transcriptions = files.map(f => transcriptions[f.filename] || null);
+    }
+  }
+
+  const spinner = villageSpinner('Preparing ingestion...').start();
+  const preparation = await prepareIngestion({
+    source: options.source || 'CLI',
+    dataType: typeKey.toUpperCase(),
+    dataset: dataset.slug,
+    files: files.map(f => ({ filename: f.filename, size: f.size, mimeType: f.mimeType })),
+    metadata,
+  });
+  spinner.succeed(`Ingestion ${preparation.ingestionId} created`);
+
+  // Upload files
+  const totalFiles = files.length;
+  const totalBytes = files.reduce((sum, f) => sum + f.size, 0);
+  let uploadedFiles = 0;
+
+  console.log(`\n  Uploading ${totalFiles} files to S3...`);
+
+  const checksums = [];
+  const uploadUrls = preparation.uploadUrls;
+
+  const uploads = uploadUrls.map((urlInfo, i) =>
+    limit(async () => {
+      const file = files[i];
+      const checksum = await computeSHA256(file.fullPath);
+      checksums.push({ filename: file.filename, checksum });
+
+      let retries = 0;
+      while (retries < 3) {
+        try {
+          await axios.put(urlInfo.uploadUrl, createReadStream(file.fullPath), {
+            headers: {
+              'Content-Type': file.mimeType || 'application/octet-stream',
+              'Content-Length': file.size,
+            },
+            maxBodyLength: Infinity,
+          });
+          break;
+        } catch (err) {
+          retries++;
+          if (retries >= 3) throw err;
+          await new Promise(r => setTimeout(r, 1000 * Math.pow(2, retries)));
+        }
+      }
+
+      uploadedFiles++;
+      const pct = Math.round((uploadedFiles / totalFiles) * 100);
+      process.stdout.write(`\r  [${'\u2588'.repeat(Math.floor(pct / 2.5))}${'\u2591'.repeat(40 - Math.floor(pct / 2.5))}] ${pct}% (${uploadedFiles}/${totalFiles}) ${formatBytes(totalBytes)}`);
+    })
+  );
+
+  await Promise.all(uploads);
+  console.log();
+
+  // Finalize
+  const finalSpinner = villageSpinner('Finalizing...').start();
+  const result = await completeIngestion(preparation.ingestionId, { checksums });
+  finalSpinner.succeed(`${result.itemCount} items added to ${dataset.slug}`);
+  console.log(`\n  View in Studio: ${brand.teal(`https://soulprint-studio.myvillageproject.ai/datasets/${dataset.slug}`)}\n`);
+}
+
+// ════════════════════════════════════════════════════════
+//  DATASETS LIST
+// ════════════════════════════════════════════════════════
+
+export async function soulprintDatasetListCommand(options) {
+  if (!requireAuth()) return;
+
+  const spinner = villageSpinner('Loading datasets...').start();
+  try {
+    const params = {};
+    if (options.type) params.dataType = options.type.toUpperCase();
+    if (options.status) params.status = options.status.toUpperCase();
+
+    const result = await listDatasets(params);
+    spinner.stop();
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    const datasets = result.datasets || result.data || result;
+    if (!Array.isArray(datasets) || datasets.length === 0) {
+      info('\n  No datasets found.\n');
+      return;
+    }
+
+    header('Datasets on SoulPrint Studio');
+
+    // Table header
+    console.log(
+      `  ${brand.teal(padRight('Name', 28))}${padRight('Type', 14)}${padRight('Status', 14)}${padRight('Items', 10)}${padRight('Version', 10)}`
+    );
+    console.log(brand.darkGold(`  ${'\u2500'.repeat(26)}  ${'\u2500'.repeat(12)}  ${'\u2500'.repeat(12)}  ${'\u2500'.repeat(8)}  ${'\u2500'.repeat(8)}`));
+
+    for (const ds of datasets) {
+      const name = padRight(truncate(ds.name || ds.slug, 26), 28);
+      const type = padRight(ds.dataType, 14);
+      const status = padRight(formatStatus(ds.status), 14);
+      const items = padRight(ds.itemCount?.toLocaleString() || '0', 10);
+      const ver = padRight(`v${ds.currentVersion || 1}`, 10);
+      console.log(`  ${brand.gold(name)}${type}${status}${items}${ver}`);
+    }
+    console.log();
+  } catch (err) {
+    const message = err.response?.data?.error || err.message;
+    spinner.fail(`Failed to load datasets: ${message}`);
+  }
+}
+
+// ════════════════════════════════════════════════════════
+//  DATASETS PULL
+// ════════════════════════════════════════════════════════
+
+export async function soulprintDatasetPullCommand(slug, options) {
+  if (!requireAuth()) return;
+  if (!requireWorkspace()) return;
+
+  try {
+    const version = options.version ? parseInt(options.version) : undefined;
+
+    // Check if already downloaded
+    if (version && isDatasetDownloaded(slug, version) && !options.force) {
+      info(`Dataset ${slug} v${version} is already downloaded locally.`);
+      info(`Use --force to re-download.\n`);
+      return;
+    }
+
+    const spinner = villageSpinner(`Fetching download info for ${slug}...`).start();
+    const downloadInfo = await getDatasetDownload(slug, version);
+    spinner.stop();
+
+    const ver = downloadInfo.version;
+    const itemCount = downloadInfo.itemCount;
+    const totalSize = downloadInfo.totalSizeBytes;
+
+    console.log(`\n  Pulling dataset: ${brand.gold(`${slug} v${ver}`)}`);
+    console.log(`  Items: ${itemCount?.toLocaleString()} | Size: ${formatBytes(totalSize)}\n`);
+
+    const localDir = getLocalDatasetDir(slug, ver);
+    mkdirSync(localDir, { recursive: true });
+
+    // Download manifest
+    if (downloadInfo.manifest?.url) {
+      const manifestResp = await axios.get(downloadInfo.manifest.url, { responseType: 'arraybuffer' });
+      writeFileSync(join(localDir, 'manifest.json'), manifestResp.data);
+    }
+
+    // Download files
+    const urls = downloadInfo.downloadUrls || [];
+    if (urls.length > 0) {
+      const limit = pLimit(5);
+      let downloaded = 0;
+
+      console.log(`  Downloading to ${brand.teal(localDir)}/`);
+
+      const downloads = urls.map(item =>
+        limit(async () => {
+          const destPath = join(localDir, item.path);
+          const destDir = join(localDir, item.path.split('/').slice(0, -1).join('/'));
+          mkdirSync(destDir, { recursive: true });
+
+          const response = await axios.get(item.url, { responseType: 'stream' });
+          await pipeline(response.data, createWriteStream(destPath));
+
+          downloaded++;
+          const pct = Math.round((downloaded / urls.length) * 100);
+          process.stdout.write(`\r  [${'\u2588'.repeat(Math.floor(pct / 2.5))}${'\u2591'.repeat(40 - Math.floor(pct / 2.5))}] ${pct}% (${downloaded.toLocaleString()}/${urls.length.toLocaleString()})`);
+        })
+      );
+
+      await Promise.all(downloads);
+      console.log();
+    }
+
+    // Write manifest if not already present
+    if (!existsSync(join(localDir, 'manifest.json'))) {
+      writeFileSync(join(localDir, 'manifest.json'), JSON.stringify({
+        slug, version: ver, itemCount, totalSizeBytes: totalSize, downloadedAt: new Date().toISOString(),
+      }, null, 2));
+    }
+
+    console.log();
+    success(`Dataset ready at: ${localDir}`);
+
+    // Print split counts if available
+    for (const split of ['train', 'validation', 'test']) {
+      const splitDir = join(localDir, split);
+      if (existsSync(splitDir)) {
+        const count = readdirSync(splitDir).length;
+        info(`${padRight(split + '/', 16)} ${count} items`);
+      }
+    }
+    console.log();
+  } catch (err) {
+    const message = err.response?.data?.error || err.message;
+    error(`Failed to pull dataset: ${message}\n`);
+  }
+}
+
+// ════════════════════════════════════════════════════════
+//  TRAIN
+// ════════════════════════════════════════════════════════
+
+export async function soulprintTrainCommand(options) {
+  if (!requireAuth()) return;
+  if (!requireWorkspace()) return;
+
+  try {
+    const typeKey = options.type?.toLowerCase();
+    if (!VALID_METHODS[typeKey]) {
+      error(`Invalid type "${options.type}". Must be: text, image, audio, structured, multimodal\n`);
+      return;
+    }
+
+    if (options.method && !VALID_METHODS[typeKey].includes(options.method)) {
+      error(`Invalid method "${options.method}" for type "${typeKey}".`);
+      info(`Valid methods: ${VALID_METHODS[typeKey].join(', ')}\n`);
+      return;
+    }
+
+    // If no method specified, prompt
+    let method = options.method;
+    if (!method) {
+      const { selectedMethod } = await inquirer.prompt([{
+        type: 'list',
+        name: 'selectedMethod',
+        message: `Training method for ${typeKey}:`,
+        choices: VALID_METHODS[typeKey].map(m => ({ name: m, value: m })),
+      }]);
+      method = selectedMethod;
+    }
+
+    // Load config YAML if provided
+    let config = {};
+    if (options.config) {
+      const configPath = resolve(options.config);
+      if (!existsSync(configPath)) {
+        error(`Config file not found: ${configPath}\n`);
+        return;
+      }
+      config = parseYaml(readFileSync(configPath, 'utf-8'));
+    }
+
+    // Fetch dataset info
+    const spinner = villageSpinner('Validating dataset...').start();
+    let dataset;
+    try {
+      dataset = await getDataset(options.dataset);
+      spinner.stop();
+    } catch (err) {
+      spinner.fail(`Dataset "${options.dataset}" not found.`);
+      return;
+    }
+
+    const datasetVersion = options.version ? parseInt(options.version) : dataset.currentVersion;
+
+    // Check local download
+    if (!isDatasetDownloaded(options.dataset, datasetVersion)) {
+      const { pullNow } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'pullNow',
+        message: `Dataset "${options.dataset}" v${datasetVersion} not found locally. Download it now?`,
+        default: true,
+      }]);
+      if (pullNow) {
+        await soulprintDatasetPullCommand(options.dataset, { version: String(datasetVersion) });
+      } else {
+        info('Cannot train without a local dataset copy.\n');
+        return;
+      }
+    }
+
+    const localDatasetDir = getLocalDatasetDir(options.dataset, datasetVersion);
+    const baseModel = options.base || config.baseModel || 'default';
+    const jobName = options.name || `${dataset.name} ${method} v${datasetVersion}`;
+
+    // Dry run
+    if (options.dryRun) {
+      header('Training Configuration (Dry Run)');
+      console.log(`  Type:         ${typeKey}`);
+      console.log(`  Dataset:      ${options.dataset} v${datasetVersion}`);
+      console.log(`  Base model:   ${baseModel}`);
+      console.log(`  Method:       ${method}`);
+      console.log(`  Dataset dir:  ${localDatasetDir}`);
+      if (Object.keys(config).length > 0) {
+        console.log(`  Config:       ${JSON.stringify(config, null, 2).split('\n').join('\n                ')}`);
+      }
+      console.log();
+      info('Dry run complete. No job was created.\n');
+      return;
+    }
+
+    // Create job on Studio
+    const machineInfo = getMachineInfo();
+    const createSpinner = villageSpinner('Creating training job on SoulPrint Studio...').start();
+    const jobResult = await createJob({
+      name: jobName,
+      dataType: typeKey.toUpperCase(),
+      datasetSlug: options.dataset,
+      datasetVersion,
+      baseModel,
+      method,
+      config,
+      machineInfo,
+      cliVersion,
+    });
+    const jobId = jobResult.jobId;
+    createSpinner.succeed(`Job registered: ${brand.gold(jobId)}`);
+
+    // Print training summary
+    console.log();
+    console.log(`  Starting ${brand.gold(method)} training:`);
+    console.log(`    Base model: ${baseModel}`);
+    console.log(`    Dataset:    ${options.dataset} v${datasetVersion}`);
+    console.log(`    Method:     ${method}`);
+    if (config.epochs) console.log(`    Epochs:     ${config.epochs}`);
+    console.log(`    Device:     ${machineInfo.gpuType} (${machineInfo.gpu})`);
+    console.log();
+
+    // Resolve Python script
+    const scriptKey = method === 'lora' ? `lora:${typeKey}` : method;
+    const scriptRelPath = METHOD_SCRIPTS[scriptKey];
+    if (!scriptRelPath) {
+      error(`No training script found for method "${method}"\n`);
+      await failJob(jobId, { errorMessage: `No training script for method: ${method}` });
+      return;
+    }
+
+    const scriptPath = join(getScriptsDir(), scriptRelPath);
+    const pythonPath = getPythonPath() || 'python3';
+
+    if (!existsSync(scriptPath)) {
+      error(`Training script not found: ${scriptPath}`);
+      info(`Run ${brand.gold("'myvillage soulprint init'")} to download training scripts.\n`);
+      await failJob(jobId, { errorMessage: `Training script not found: ${scriptRelPath}` });
+      return;
+    }
+
+    // Update status to PREPARING
+    await updateJobStatus(jobId, { status: 'PREPARING' }).catch(() => {});
+
+    const outputDir = getJobOutputDir(jobId);
+    mkdirSync(outputDir, { recursive: true });
+
+    const scriptArgs = [
+      '--dataset-dir', localDatasetDir,
+      '--output-dir', outputDir,
+      '--base-model', baseModel,
+      '--method', method,
+      '--config', JSON.stringify(config),
+      '--job-id', jobId,
+    ];
+
+    // Spawn Python
+    await updateJobStatus(jobId, { status: 'TRAINING' }).catch(() => {});
+
+    let trainingProcess = null;
+    let lastReportTime = 0;
+    let lastReportedEpoch = 0;
+    const REPORT_INTERVAL_MS = 10_000;
+    let finalData = null;
+
+    // SIGINT handler
+    const sigintHandler = async () => {
+      if (trainingProcess) {
+        console.log('\n  Stopping training gracefully...');
+        trainingProcess.kill('SIGTERM');
+        const deadline = Date.now() + 10000;
+        while (Date.now() < deadline && !trainingProcess.killed) {
+          await new Promise(r => setTimeout(r, 500));
+        }
+        if (!trainingProcess.killed) {
+          trainingProcess.kill('SIGKILL');
+        }
+        await updateJobStatus(jobId, { status: 'CANCELLED' }).catch(() => {});
+        console.log('  Training cancelled.');
+      }
+      process.exit(0);
+    };
+    process.on('SIGINT', sigintHandler);
+
+    try {
+      finalData = await new Promise((resolveP, rejectP) => {
+        trainingProcess = spawn(pythonPath, [scriptPath, ...scriptArgs], {
+          env: { ...process.env, PYTHONUNBUFFERED: '1' },
+          cwd: getSoulprintDir(),
+        });
+
+        const rl = createInterface({ input: trainingProcess.stdout });
+        rl.on('line', (line) => {
+          try {
+            const data = JSON.parse(line);
+            if (data.type === 'progress') {
+              // Display
+              const pct = data.totalEpochs ? Math.round((data.epoch / data.totalEpochs) * 100) : 0;
+              process.stdout.write(`\r  Epoch ${data.epoch || '?'}/${data.totalEpochs || '?'} ${'━'.repeat(Math.floor(pct / 5))}${'─'.repeat(20 - Math.floor(pct / 5))} loss: ${data.loss?.toFixed(4) || '?'}  lr: ${data.lr || '?'}  `);
+
+              appendJobLog(jobId, { type: 'progress', ...data });
+
+              // Throttle reports to Studio
+              const now = Date.now();
+              const isEpochBoundary = data.epoch && data.epoch !== lastReportedEpoch;
+              if (now - lastReportTime > REPORT_INTERVAL_MS || isEpochBoundary) {
+                lastReportTime = now;
+                lastReportedEpoch = data.epoch;
+                updateJobStatus(jobId, {
+                  status: 'TRAINING',
+                  progress: data.totalEpochs ? data.epoch / data.totalEpochs : null,
+                  currentEpoch: data.epoch,
+                  totalEpochs: data.totalEpochs,
+                  currentStep: data.step,
+                  totalSteps: data.totalSteps,
+                  metrics: { trainingLoss: data.loss, validationLoss: data.valLoss },
+                  logs: `Epoch ${data.epoch}/${data.totalEpochs} - loss: ${data.loss}`,
+                }).catch(() => {});
+              }
+            } else if (data.type === 'log') {
+              appendJobLog(jobId, data);
+            } else if (data.type === 'complete') {
+              resolveP(data);
+            }
+          } catch {
+            appendJobLog(jobId, { type: 'stdout', message: line });
+          }
+        });
+
+        let stderr = '';
+        trainingProcess.stderr.on('data', (chunk) => {
+          stderr += chunk.toString();
+          appendJobLog(jobId, { type: 'stderr', message: chunk.toString().trim() });
+        });
+
+        trainingProcess.on('close', (code) => {
+          if (code !== 0) {
+            rejectP(new Error(stderr || `Training process exited with code ${code}`));
+          }
+        });
+
+        trainingProcess.on('error', (err) => {
+          rejectP(new Error(`Failed to start training: ${err.message}`));
+        });
+      });
+    } catch (err) {
+      process.removeListener('SIGINT', sigintHandler);
+      console.log();
+      error(`Training failed: ${err.message}`);
+      await failJob(jobId, { errorMessage: err.message }).catch(() => {});
+      info(`Logs saved to: ${getJobLogFile(jobId)}\n`);
+      return;
+    }
+
+    process.removeListener('SIGINT', sigintHandler);
+    console.log();
+    console.log();
+    success('Training complete!');
+    console.log(`  Output: ${brand.teal(outputDir)}`);
+    if (finalData?.finalMetrics) {
+      const m = finalData.finalMetrics;
+      if (m.trainingLoss != null) console.log(`  Final loss: ${m.trainingLoss}`);
+      if (m.fidScore != null) console.log(`  FID score: ${m.fidScore}`);
+      if (m.wer != null) console.log(`  WER: ${m.wer}`);
+      if (m.mae != null) console.log(`  MAE: ${m.mae}`);
+      if (m.r2Score != null) console.log(`  R\u00B2: ${m.r2Score}`);
+    }
+    console.log();
+
+    // Upload artifacts
+    const uploadSpinner = villageSpinner('Uploading artifacts to SoulPrint Studio...').start();
+    try {
+      const artifacts = scanArtifacts(outputDir);
+      const totalArtifactSize = artifacts.reduce((sum, f) => sum + f.size, 0);
+
+      for (const artifact of artifacts) {
+        artifact.checksum = await computeSHA256(artifact.fullPath);
+      }
+
+      const { urls } = await getUploadUrls({
+        jobId,
+        files: artifacts.map(f => ({ path: f.path, size: f.size, checksum: f.checksum })),
+      });
+
+      const uploadLimit = pLimit(3);
+      const artifactUploads = urls.map((urlInfo, i) =>
+        uploadLimit(async () => {
+          const file = artifacts[i];
+          await axios.put(urlInfo.uploadUrl, createReadStream(file.fullPath), {
+            headers: { 'Content-Type': 'application/octet-stream' },
+            maxBodyLength: Infinity,
+          });
+        })
+      );
+      await Promise.all(artifactUploads);
+
+      const completeResult = await completeJob(jobId, {
+        s3Artifacts: `soulprint/models/${jobId}/`,
+        artifactSizeBytes: totalArtifactSize,
+        artifactManifest: artifacts.map(f => ({ path: f.path, size: f.size, checksum: f.checksum })),
+        finalMetrics: finalData?.finalMetrics || {},
+        evalSamples: finalData?.evalSamples || [],
+      });
+
+      uploadSpinner.succeed(`Model registered: ${brand.gold(completeResult.modelId || jobId)}`);
+      console.log(`\n  View in Studio: ${brand.teal(`https://soulprint-studio.myvillageproject.ai/jobs/${jobId}`)}\n`);
+    } catch (err) {
+      uploadSpinner.fail(`Artifact upload failed: ${err.message}`);
+      info(`Artifacts saved locally at: ${outputDir}`);
+      info(`Try again with: ${brand.gold(`myvillage soulprint push ${outputDir} --job ${jobId}`)}\n`);
+    }
+  } catch (err) {
+    if (err.isTtyError) {
+      error('Prompts cannot be rendered in this environment.\n');
+      return;
+    }
+    const message = err.response?.data?.error || err.message;
+    error(`Training setup failed: ${message}\n`);
+  }
+}
+
+// ════════════════════════════════════════════════════════
+//  JOBS
+// ════════════════════════════════════════════════════════
+
+export async function soulprintJobsCommand(options) {
+  if (!requireAuth()) return;
+
+  const spinner = villageSpinner('Loading training jobs...').start();
+  try {
+    const params = {};
+    if (options.status) params.status = options.status.toUpperCase();
+
+    const result = await listJobs(params);
+    spinner.stop();
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    const jobs = result.jobs || result.data || result;
+    if (!Array.isArray(jobs) || jobs.length === 0) {
+      info('\n  No training jobs found.\n');
+      return;
+    }
+
+    header('Training Jobs');
+
+    console.log(
+      `  ${brand.teal(padRight('Job ID', 16))}${padRight('Name', 28)}${padRight('Status', 14)}${padRight('Progress', 10)}${padRight('Started', 12)}`
+    );
+    console.log(brand.darkGold(`  ${'\u2500'.repeat(14)}  ${'\u2500'.repeat(26)}  ${'\u2500'.repeat(12)}  ${'\u2500'.repeat(8)}  ${'\u2500'.repeat(10)}`));
+
+    for (const job of jobs) {
+      const id = padRight(truncate(job.id, 14), 16);
+      const name = padRight(truncate(job.name, 26), 28);
+      const status = padRight(formatStatus(job.status), 14);
+      const progress = padRight(formatProgress(job.progress), 10);
+      const started = padRight(job.startedAt ? relativeTime(job.startedAt) : (job.createdAt ? relativeTime(job.createdAt) : '--'), 12);
+      console.log(`  ${chalk.cyan(id)}${name}${status}${progress}${started}`);
+    }
+    console.log();
+  } catch (err) {
+    const message = err.response?.data?.error || err.message;
+    spinner.fail(`Failed to load jobs: ${message}`);
+  }
+}
+
+export async function soulprintJobDetailCommand(jobId, options) {
+  if (!requireAuth()) return;
+
+  const spinner = villageSpinner(`Loading job ${jobId}...`).start();
+  try {
+    const job = await getJob(jobId);
+    spinner.stop();
+
+    if (options.json) {
+      console.log(JSON.stringify(job, null, 2));
+      return;
+    }
+
+    console.log();
+    console.log(`  ${chalk.bold(`Job: ${job.name}`)} (${chalk.cyan(job.id)})`);
+    console.log(`  Status:   ${formatStatus(job.status)}`);
+    console.log(`  Dataset:  ${brand.gold(job.dataset?.slug || job.datasetId)} v${job.datasetVersion}`);
+    console.log(`  Base:     ${job.baseModel}`);
+    console.log(`  Method:   ${job.method}`);
+
+    if (job.progress != null) {
+      const pct = Math.round(job.progress * 100);
+      const filled = Math.floor(pct / 2.5);
+      console.log();
+      console.log(`  Progress: ${'\u2588'.repeat(filled)}${'\u2591'.repeat(40 - filled)} ${pct}%`);
+      if (job.currentEpoch != null) console.log(`  Epoch:    ${job.currentEpoch}/${job.totalEpochs}`);
+      if (job.currentStep != null) console.log(`  Step:     ${job.currentStep?.toLocaleString()}/${job.totalSteps?.toLocaleString()}`);
+    }
+
+    if (job.metrics) {
+      console.log();
+      console.log('  Metrics:');
+      const m = job.metrics;
+      if (m.trainingLoss != null) console.log(`    Training loss:    ${m.trainingLoss}`);
+      if (m.validationLoss != null) console.log(`    Validation loss:  ${m.validationLoss}`);
+      if (m.accuracy != null) console.log(`    Accuracy:         ${m.accuracy}`);
+      if (m.fidScore != null) console.log(`    FID score:        ${m.fidScore}`);
+      if (m.clipScore != null) console.log(`    CLIP score:       ${m.clipScore}`);
+      if (m.wer != null) console.log(`    WER:              ${m.wer}`);
+      if (m.cer != null) console.log(`    CER:              ${m.cer}`);
+      if (m.mae != null) console.log(`    MAE:              ${m.mae}`);
+      if (m.r2Score != null) console.log(`    R\u00B2:               ${m.r2Score}`);
+      if (m.f1Score != null) console.log(`    F1:               ${m.f1Score}`);
+    }
+
+    if (job.machineInfo) {
+      console.log();
+      console.log(`  Machine: ${job.machineInfo.gpu || 'unknown'} (${job.machineInfo.vram || '?'}) \u2014 ${job.machineInfo.os || 'unknown'}`);
+    }
+    if (job.cliVersion) console.log(`  CLI:     v${job.cliVersion}`);
+    if (job.startedAt) console.log(`  Started: ${job.startedAt}`);
+    if (job.completedAt) console.log(`  Ended:   ${job.completedAt}`);
+    if (job.errorMessage) {
+      console.log();
+      console.log(chalk.red(`  Error: ${job.errorMessage}`));
+    }
+    console.log();
+  } catch (err) {
+    const message = err.response?.data?.error || err.message;
+    spinner.fail(`Failed to load job: ${message}`);
+  }
+}
+
+// ════════════════════════════════════════════════════════
+//  MODELS
+// ════════════════════════════════════════════════════════
+
+export async function soulprintModelsCommand(options) {
+  if (!requireAuth()) return;
+
+  const spinner = villageSpinner('Loading models...').start();
+  try {
+    const params = {};
+    if (options.status) params.status = options.status.toUpperCase();
+    if (options.type) params.dataType = options.type.toUpperCase();
+
+    const result = await listModels(params);
+    spinner.stop();
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    const models = result.models || result.data || result;
+    if (!Array.isArray(models) || models.length === 0) {
+      info('\n  No models found.\n');
+      return;
+    }
+
+    header('Model Registry');
+
+    console.log(
+      `  ${brand.teal(padRight('Name', 28))}${padRight('Type', 14)}${padRight('Status', 14)}${padRight('Base Model', 24)}${padRight('Created', 12)}`
+    );
+    console.log(brand.darkGold(`  ${'\u2500'.repeat(26)}  ${'\u2500'.repeat(12)}  ${'\u2500'.repeat(12)}  ${'\u2500'.repeat(22)}  ${'\u2500'.repeat(10)}`));
+
+    for (const model of models) {
+      const name = padRight(truncate(model.name || model.slug, 26), 28);
+      const type = padRight(model.dataType, 14);
+      const status = padRight(formatStatus(model.status), 14);
+      const base = padRight(truncate(model.baseModel, 22), 24);
+      const created = padRight(model.createdAt ? relativeTime(model.createdAt) : '--', 12);
+      console.log(`  ${brand.gold(name)}${type}${status}${base}${created}`);
+    }
+    console.log();
+  } catch (err) {
+    const message = err.response?.data?.error || err.message;
+    spinner.fail(`Failed to load models: ${message}`);
+  }
+}
+
+// ════════════════════════════════════════════════════════
+//  PUSH
+// ════════════════════════════════════════════════════════
+
+export async function soulprintPushCommand(path, options) {
+  if (!requireAuth()) return;
+
+  try {
+    const resolvedPath = resolve(path);
+    if (!existsSync(resolvedPath)) {
+      error(`Path not found: ${resolvedPath}\n`);
+      return;
+    }
+
+    const typeKey = options.type?.toLowerCase();
+    if (!TYPE_EXTENSIONS[typeKey]) {
+      error(`Invalid type "${options.type}". Must be: text, image, audio, structured, multimodal\n`);
+      return;
+    }
+
+    console.log('\n  Scanning artifacts...');
+    const artifacts = scanArtifacts(resolvedPath);
+    const totalSize = artifacts.reduce((sum, f) => sum + f.size, 0);
+    info(`${artifacts.length} files, ${formatBytes(totalSize)} total`);
+
+    // Compute checksums
+    const checksumSpinner = villageSpinner('Computing checksums...').start();
+    for (const artifact of artifacts) {
+      artifact.checksum = await computeSHA256(artifact.fullPath);
+    }
+    checksumSpinner.stop();
+
+    // Get upload URLs
+    const uploadData = { files: artifacts.map(f => ({ path: f.path, size: f.size, checksum: f.checksum })) };
+    if (options.job) uploadData.jobId = options.job;
+
+    const spinner = villageSpinner('Uploading model artifacts to SoulPrint Studio...').start();
+    const { urls } = await getUploadUrls(uploadData);
+
+    const limit = pLimit(3);
+    let uploadedBytes = 0;
+
+    const uploads = urls.map((urlInfo, i) =>
+      limit(async () => {
+        const file = artifacts[i];
+        await axios.put(urlInfo.uploadUrl, createReadStream(file.fullPath), {
+          headers: { 'Content-Type': 'application/octet-stream' },
+          maxBodyLength: Infinity,
+        });
+        uploadedBytes += file.size;
+      })
+    );
+
+    await Promise.all(uploads);
+    spinner.succeed(`Uploaded ${formatBytes(totalSize)}`);
+
+    // Register model
+    const registerSpinner = villageSpinner('Registering model...').start();
+    const modelPayload = {
+      name: options.name,
+      dataType: typeKey.toUpperCase(),
+      baseModel: options.base || 'unknown',
+      method: options.method || 'unknown',
+      description: options.description || '',
+      s3Artifacts: `soulprint/models/${options.name.toLowerCase().replace(/\s+/g, '-')}/`,
+      artifactSizeBytes: totalSize,
+      artifactManifest: artifacts.map(f => ({ path: f.path, size: f.size, checksum: f.checksum })),
+    };
+    if (options.job) modelPayload.jobId = options.job;
+
+    const client = (await import('../utils/soulprint-api.js')).getSoulprintClient();
+    const response = await client.post('/models', modelPayload);
+    const model = response.data;
+    registerSpinner.succeed(`Model registered: ${brand.gold(model.slug || model.name)}`);
+
+    console.log(`  Status: ${formatStatus('DRAFT')}`);
+    console.log(`  View: ${brand.teal(`https://soulprint-studio.myvillageproject.ai/models/${model.slug || ''}`)}\n`);
+  } catch (err) {
+    const message = err.response?.data?.error || err.message;
+    error(`Push failed: ${message}\n`);
+  }
+}
+
+// ════════════════════════════════════════════════════════
+//  PUBLISH
+// ════════════════════════════════════════════════════════
+
+export async function soulprintPublishCommand(modelSlug, options) {
+  if (!requireAuth()) return;
+
+  try {
+    // Verify model exists and is VALIDATED
+    const spinner = villageSpinner(`Publishing ${modelSlug} to MyVillage Platform...`).start();
+
+    const model = await getModel(modelSlug);
+    if (model.status !== 'VALIDATED') {
+      spinner.fail(`Model "${modelSlug}" is ${model.status}. Only VALIDATED models can be published.`);
+      return;
+    }
+
+    const publishData = {
+      tier: options.tier || 'FREE',
+      isPublic: !!options.public,
+    };
+    if (options.villager) publishData.targetVillagerId = options.villager;
+    if (options.villages) publishData.targetVillageIds = options.villages.split(',').map(s => s.trim());
+
+    const result = await publishModel(modelSlug, publishData);
+    spinner.succeed('Model pushed to portal.myvillageproject.ai');
+
+    if (result.platformModelId) {
+      success(`Platform Model ID: ${result.platformModelId}`);
+    }
+    success('Status: DRAFT (activate in portal admin)');
+
+    if (result.platformUrl) {
+      console.log(`\n  Model available at: ${brand.teal(result.platformUrl)}\n`);
+    } else if (result.platformModelId) {
+      console.log(`\n  Model available at: ${brand.teal(`https://portal.myvillageproject.ai/admin/models/${result.platformModelId}`)}\n`);
+    }
+  } catch (err) {
+    const message = err.response?.data?.error || err.message;
+    error(`Publish failed: ${message}\n`);
+  }
+}