@valentia-ai-skills/framework 2.0.6 → 2.0.8

package/bin/cli.js

@@ -17,6 +17,7 @@ const path = require("path");
 const readline = require("readline");
 const https = require("https");
 const http = require("http");
+const { pathToFileURL } = require("url");
 
 // ── Constants ──
 
@@ -31,6 +32,24 @@ const ANALYZE_FUNCTION_URL =
   process.env.AI_SKILLS_ANALYZE_URL || "https://znshdhjquohrzvbnloki.supabase.co/functions/v1/analyze-commit";
 const SCAN_FUNCTION_URL =
   process.env.AI_SKILLS_SCAN_URL || "https://znshdhjquohrzvbnloki.supabase.co/functions/v1/scan-results";
+const UPLOAD_CODE_AUDIT_URL =
+  process.env.AI_SKILLS_UPLOAD_CODE_AUDIT_URL ||
+  "https://znshdhjquohrzvbnloki.supabase.co/functions/v1/upload-code-audit";
+const MANAGE_CODE_AUDITS_URL =
+  process.env.AI_SKILLS_MANAGE_CODE_AUDITS_URL ||
+  "https://znshdhjquohrzvbnloki.supabase.co/functions/v1/manage-code-audits";
+
+let codeAuditConfigPromise = null;
+
+async function loadCodeAuditConfig() {
+  if (!codeAuditConfigPromise) {
+    const configUrl = pathToFileURL(
+      path.join(__dirname, "..", "skills-console", "code-audit-config.js")
+    ).href;
+    codeAuditConfigPromise = import(configUrl);
+  }
+  return codeAuditConfigPromise;
+}
 
 // ── Language Detection ──
 
@@ -1321,6 +1340,320 @@ function fetchJSONWithAuth(url, body, token) {
   });
 }
 
+function walkFiles(rootPath) {
+  const files = [];
+
+  function visit(currentPath) {
+    const entries = fs.readdirSync(currentPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const absolutePath = path.join(currentPath, entry.name);
+      if (entry.isDirectory()) {
+        visit(absolutePath);
+      } else if (entry.isFile()) {
+        files.push(absolutePath);
+      }
+    }
+  }
+
+  visit(rootPath);
+  return files.sort();
+}
+
+function countLines(content) {
+  if (!content) return 0;
+  return content.split(/\r?\n/).length;
+}
+
+function coerceNumber(value, fallback = 0) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : fallback;
+}
+
+function normalizeAuditFindingCount(value) {
+  const source = value && typeof value === "object" ? value : {};
+  return {
+    critical: Math.max(0, coerceNumber(source.critical, 0)),
+    high: Math.max(0, coerceNumber(source.high, 0)),
+    medium: Math.max(0, coerceNumber(source.medium, 0)),
+    low: Math.max(0, coerceNumber(source.low, 0)),
+  };
+}
+
+function normalizeAuditScoreEntry(rawEntry, fallbackWeight, codeAuditConfig) {
+  if (typeof rawEntry === "number") {
+    const score = Math.max(0, Math.min(100, Math.round(rawEntry)));
+    return {
+      score,
+      grade: codeAuditConfig.gradeFromCodeAuditScore(score),
+      weight: fallbackWeight,
+      finding_count: normalizeAuditFindingCount({}),
+    };
+  }
+
+  const entry = rawEntry && typeof rawEntry === "object" ? rawEntry : {};
+  const score = Math.max(
+    0,
+    Math.min(
+      100,
+      Math.round(
+        coerceNumber(
+          entry.score ??
+          entry.value ??
+          entry.category_score,
+          0
+        )
+      )
+    )
+  );
+
+  return {
+    score,
+    grade: String(
+      entry.grade ??
+      entry.category_grade ??
+      codeAuditConfig.gradeFromCodeAuditScore(score)
+    ).toUpperCase(),
+    weight:
+      entry.weight === undefined || entry.weight === null
+        ? fallbackWeight
+        : coerceNumber(entry.weight, fallbackWeight ?? 0),
+    finding_count: normalizeAuditFindingCount(
+      entry.finding_count ??
+      entry.findings ??
+      entry.severity_counts ??
+      {}
+    ),
+  };
+}
+
+async function normalizeAuditManifestForCli(manifest) {
+  const codeAuditConfig = await loadCodeAuditConfig();
+  const summary = manifest.summary && typeof manifest.summary === "object" ? manifest.summary : {};
+  const overall = manifest.overall && typeof manifest.overall === "object" ? manifest.overall : {};
+  const rawScores =
+    (manifest.scores && typeof manifest.scores === "object" ? manifest.scores : null) ||
+    (manifest.category_scores && typeof manifest.category_scores === "object" ? manifest.category_scores : null) ||
+    (manifest.categories && typeof manifest.categories === "object" ? manifest.categories : null) ||
+    (summary.scores && typeof summary.scores === "object" ? summary.scores : null) ||
+    {};
+
+  const scores = {};
+  for (const definition of codeAuditConfig.getCodeAuditDashboardDefinitions()) {
+    if (!definition.scoreKey) continue;
+    scores[definition.scoreKey] = normalizeAuditScoreEntry(
+      rawScores[definition.scoreKey] ?? rawScores[definition.documentType] ?? {},
+      definition.weight ?? null,
+      codeAuditConfig
+    );
+  }
+
+  const severitySource =
+    (manifest.findings && typeof manifest.findings === "object" ? manifest.findings : null) ||
+    (manifest.finding_summary && typeof manifest.finding_summary === "object" ? manifest.finding_summary : null) ||
+    (summary.findings && typeof summary.findings === "object" ? summary.findings : null) ||
+    {};
+  const normalizedCounts = normalizeAuditFindingCount(severitySource);
+
+  const overallScore = Math.max(
+    0,
+    Math.min(
+      100,
+      Math.round(
+        coerceNumber(
+          manifest.overall_score ??
+          manifest.overallScore ??
+          overall.score ??
+          summary.overall_score,
+          0
+        )
+      )
+    )
+  );
+
+  const overallGrade = String(
+    manifest.overall_grade ??
+    manifest.overallGrade ??
+    overall.grade ??
+    summary.overall_grade ??
+    codeAuditConfig.gradeFromCodeAuditScore(overallScore)
+  ).toUpperCase();
+
+  return {
+    audited_at:
+      manifest.audited_at ??
+      manifest.auditedAt ??
+      manifest.generated_at ??
+      manifest.generatedAt ??
+      summary.audited_at ??
+      new Date().toISOString(),
+    tech_stack:
+      (manifest.tech_stack && typeof manifest.tech_stack === "object" ? manifest.tech_stack : null) ||
+      (manifest.techStack && typeof manifest.techStack === "object" ? manifest.techStack : null) ||
+      (manifest.stack && typeof manifest.stack === "object" ? manifest.stack : null) ||
+      {},
+    overall_score: overallScore,
+    overall_grade: overallGrade,
+    scores,
+    finding_count: normalizedCounts,
+    total_findings:
+      coerceNumber(
+        severitySource.total ??
+        manifest.total_findings ??
+        summary.total_findings,
+        0
+      ) ||
+      normalizedCounts.critical +
+        normalizedCounts.high +
+        normalizedCounts.medium +
+        normalizedCounts.low,
+    is_healthcare: Boolean(
+      manifest.is_healthcare ??
+      manifest.isHealthcare ??
+      summary.is_healthcare ??
+      false
+    ),
+  };
+}
+
+function validateAuditManifestForCli(summary, codeAuditConfig) {
+  const missing = [];
+  if (!summary.audited_at) missing.push("audited_at");
+  if (summary.overall_score === undefined || summary.overall_score === null) missing.push("overall_score");
+  if (!summary.overall_grade) missing.push("overall_grade");
+
+  const missingScores = codeAuditConfig
+    .getCodeAuditDashboardDefinitions()
+    .map((definition) => definition.scoreKey)
+    .filter((scoreKey) => scoreKey && !summary.scores[scoreKey]);
+
+  if (missing.length > 0) {
+    return `manifest.json missing required fields: ${missing.join(", ")}`;
+  }
+
+  if (missingScores.length > 0) {
+    return `manifest.scores missing required categories: ${missingScores.join(", ")}`;
+  }
+
+  return null;
+}
+
+function formatScoreDelta(delta) {
+  if (delta === null || delta === undefined) return "n/a";
+  const numericDelta = Number(delta);
+  if (!Number.isFinite(numericDelta)) return String(delta);
+  return numericDelta > 0 ? `+${numericDelta}` : `${numericDelta}`;
+}
+
+const BUILTIN_REPORT_SPECS = {
+  overview: {
+    category: "guide",
+    name: "Overview",
+    fileNames: ["OVERVIEW.md", "overview.md"],
+  },
+  api_registry: {
+    category: "report",
+    name: "API Registry",
+    fileNames: ["API_REGISTRY.md", "api_registry.md"],
+  },
+  business_rules: {
+    category: "report",
+    name: "Business Rules",
+    fileNames: ["BUSINESS_RULES.md", "business_rules.md"],
+  },
+  data_models: {
+    category: "report",
+    name: "Data Models",
+    fileNames: ["DATA_MODELS.md", "data_models.md"],
+  },
+  dependencies: {
+    category: "report",
+    name: "Dependencies",
+    fileNames: ["DEPENDENCIES.md", "dependencies.md"],
+  },
+  env_config: {
+    category: "report",
+    name: "Env Config",
+    fileNames: ["ENV_CONFIG.md", "env_config.md"],
+  },
+  risk_report: {
+    category: "report",
+    name: "Risk Report",
+    fileNames: ["RISK_REPORT.md", "risk_report.md"],
+  },
+  glossary: {
+    category: "report",
+    name: "Glossary",
+    fileNames: ["GLOSSARY.md", "glossary.md"],
+  },
+  reproduction_guide: {
+    category: "guide",
+    name: "Reproduction Guide",
+    fileNames: ["REPRODUCTION_GUIDE.md", "reproduction_guide.md"],
+  },
+};
+
+function titleizeReportKey(value) {
+  return String(value || "")
+    .replace(/\.[^.]+$/, "")
+    .replace(/[_-]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/\b\w/g, (char) => char.toUpperCase());
+}
+
+function normalizeDocumentType(value) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/\.[^.]+$/, "")
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  return normalized || "report";
+}
+
+function toPosixRelative(rootPath, filePath) {
+  return path.relative(rootPath, filePath).split(path.sep).join("/");
+}
+
+function findLegacyDocumentPath(rootPath, relativeFile) {
+  if (!relativeFile) return null;
+  const candidates = [path.join(rootPath, relativeFile)];
+  if (!relativeFile.includes("/") && !relativeFile.includes("\\")) {
+    candidates.push(path.join(rootPath, "reports", relativeFile));
+  }
+  return candidates.find((candidate) => fs.existsSync(candidate)) || null;
+}
+
+function normalizeManifestReportEntries(manifestReports) {
+  if (!manifestReports) return [];
+
+  if (Array.isArray(manifestReports)) {
+    return manifestReports.map((entry, index) => {
+      if (typeof entry === "string") {
+        return { file: entry, sourceKey: `report_${index + 1}` };
+      }
+      if (entry && typeof entry === "object") {
+        return { ...entry, sourceKey: entry.sourceKey || entry.document_type || entry.name || `report_${index + 1}` };
+      }
+      return null;
+    }).filter(Boolean);
+  }
+
+  if (typeof manifestReports === "object") {
+    return Object.entries(manifestReports).map(([key, value]) => {
+      if (typeof value === "string") {
+        return { file: value, sourceKey: key };
+      }
+      if (value && typeof value === "object") {
+        return { ...value, sourceKey: key };
+      }
+      return null;
+    }).filter(Boolean);
+  }
+
+  return [];
+}
+
 async function cmdUploadLegacyScan() {
   console.log(c("blue", "\n━━━ AI Skills Framework — Upload Legacy Scan ━━━\n"));
 
@@ -1480,45 +1813,109 @@ async function cmdUploadLegacyScan() {
   console.log(`Diagrams: ${c("green", diagramPayload.length.toString())} file(s)`);
 
   // ── Read report/guide files ──
-  const GUIDE_TYPES = new Set(["overview", "reproduction_guide"]);
   const reportPayload = [];
-  const reportFileMap = {
-    overview:           ["OVERVIEW.md", "overview.md"],
-    api_registry:       ["API_REGISTRY.md", "api_registry.md"],
-    business_rules:     ["BUSINESS_RULES.md", "business_rules.md"],
-    data_models:        ["DATA_MODELS.md", "data_models.md"],
-    dependencies:       ["DEPENDENCIES.md", "dependencies.md"],
-    env_config:         ["ENV_CONFIG.md", "env_config.md"],
-    risk_report:        ["RISK_REPORT.md", "risk_report.md"],
-    glossary:           ["GLOSSARY.md", "glossary.md"],
-    reproduction_guide: ["REPRODUCTION_GUIDE.md", "reproduction_guide.md"],
-  };
+  const usedReportPaths = new Set();
+  const usedReportTypes = new Set();
+  const manifestReportEntries = normalizeManifestReportEntries(manifest.reports);
+  let customReportCount = 0;
 
-  for (const [key, candidates] of Object.entries(reportFileMap)) {
-    for (const candidate of candidates) {
-      const reportPaths = [
-        path.join(resolvedPath, candidate),
-        path.join(resolvedPath, "reports", candidate),
-      ];
-      const found = reportPaths.find((p) => fs.existsSync(p));
-      if (found) {
-        const isGuide = GUIDE_TYPES.has(key);
-        const displayName = key.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
-        reportPayload.push({
-          category: isGuide ? "guide" : "report",
-          document_type: key,
-          name: displayName,
-          content: fs.readFileSync(found, "utf-8"),
-          priority: 0,
-          metadata: {},
-        });
-        break;
+  function addReportDocument({ category, documentType, name, absolutePath, relativePath, source }) {
+    if (!absolutePath || usedReportPaths.has(absolutePath) || usedReportTypes.has(documentType)) {
+      return false;
+    }
+
+    reportPayload.push({
+      category,
+      document_type: documentType,
+      name,
+      content: fs.readFileSync(absolutePath, "utf-8"),
+      priority: 0,
+      metadata: {
+        source_path: relativePath,
+        source_origin: source,
+      },
+    });
+    usedReportPaths.add(absolutePath);
+    usedReportTypes.add(documentType);
+    if (!(documentType in BUILTIN_REPORT_SPECS)) {
+      customReportCount += 1;
+    }
+    return true;
+  }
+
+  for (const entry of manifestReportEntries) {
+    const absolutePath = findLegacyDocumentPath(resolvedPath, entry.file || entry.path);
+    if (!absolutePath) {
+      if (entry.file || entry.path) {
+        console.log(c("yellow", `  ⚠ Report file not found: ${entry.file || entry.path} — skipping`));
       }
+      continue;
+    }
+
+    const inferredType = normalizeDocumentType(entry.document_type || entry.slug || entry.id || entry.sourceKey || path.basename(absolutePath, path.extname(absolutePath)));
+    const builtinSpec = BUILTIN_REPORT_SPECS[inferredType];
+    const requestedCategory = String(entry.category || entry.type || "").trim().toLowerCase();
+
+    if (!builtinSpec && requestedCategory && requestedCategory !== "report") {
+      console.log(c("yellow", `  ⚠ Custom report "${entry.name || inferredType}" must use type/category "report" — skipping`));
+      continue;
+    }
+
+    addReportDocument({
+      category: builtinSpec?.category || "report",
+      documentType: builtinSpec ? inferredType : inferredType,
+      name: entry.name || builtinSpec?.name || titleizeReportKey(inferredType),
+      absolutePath,
+      relativePath: toPosixRelative(resolvedPath, absolutePath),
+      source: "manifest",
+    });
+  }
+
+  for (const [documentType, spec] of Object.entries(BUILTIN_REPORT_SPECS)) {
+    const found = spec.fileNames
+      .map((candidate) => findLegacyDocumentPath(resolvedPath, candidate))
+      .find(Boolean);
+    if (found) {
+      addReportDocument({
+        category: spec.category,
+        documentType,
+        name: spec.name,
+        absolutePath: found,
+        relativePath: toPosixRelative(resolvedPath, found),
+        source: "builtin",
+      });
     }
   }
 
-  const reportCount = reportPayload.length;
-  console.log(`Reports: ${c("green", reportCount.toString())} file(s)\n`);
+  const reportsDir = path.join(resolvedPath, "reports");
+  if (fs.existsSync(reportsDir)) {
+    for (const file of fs.readdirSync(reportsDir).sort()) {
+      if (!/\.md$/i.test(file)) continue;
+      const absolutePath = path.join(reportsDir, file);
+      if (usedReportPaths.has(absolutePath)) continue;
+
+      const documentType = normalizeDocumentType(path.basename(file, path.extname(file)));
+      const builtinSpec = BUILTIN_REPORT_SPECS[documentType];
+
+      addReportDocument({
+        category: builtinSpec?.category || "report",
+        documentType,
+        name: builtinSpec?.name || titleizeReportKey(documentType),
+        absolutePath,
+        relativePath: toPosixRelative(resolvedPath, absolutePath),
+        source: "auto",
+      });
+    }
+  }
+
+  const reportCount = reportPayload.filter((doc) => doc.category === "report").length;
+  const guideCount = reportPayload.filter((doc) => doc.category === "guide").length;
+  const reportSummary = guideCount > 0 ? `${reportCount} report(s), ${guideCount} guide(s)` : `${reportCount} report(s)`;
+  console.log(`Reports: ${c("green", reportSummary)}`);
+  if (customReportCount > 0) {
+    console.log(c("dim", `  Included ${customReportCount} custom report(s) from manifest entries or reports/.`));
+  }
+  console.log("");
 
   // ── Build unified documents array ──
   const documentsPayload = [...skillPayload, ...diagramPayload, ...reportPayload];
@@ -1531,7 +1928,8 @@ async function cmdUploadLegacyScan() {
     console.log(`  Documents total: ${documentsPayload.length}`);
     console.log(`  — Skills: ${skillPayload.length}`);
     console.log(`  — Diagrams: ${diagramPayload.length}`);
-    console.log(`  — Reports/Guides: ${reportCount}`);
+    console.log(`  — Reports: ${reportCount}`);
+    console.log(`  — Guides: ${guideCount}`);
     if (stats.completeness_score !== undefined) {
       console.log(`  Completeness: ${stats.completeness_score}%`);
     }
@@ -1557,7 +1955,7 @@ async function cmdUploadLegacyScan() {
 
   // ── Upload ──
   console.log(c("dim", `Uploading to Valentia (${projectName})...\n`));
-  process.stdout.write(`  ${c("dim", "→")} Sending ${documentsPayload.length} documents (${skillPayload.length} skills, ${diagramPayload.length} diagrams, ${reportCount} reports)...`);
+  process.stdout.write(`  ${c("dim", "→")} Sending ${documentsPayload.length} documents (${skillPayload.length} skills, ${diagramPayload.length} diagrams, ${reportCount} reports, ${guideCount} guides)...`);
 
   let result;
   try {
@@ -1665,22 +2063,33 @@ async function cmdLegacyProjects() {
     console.log(`\n  Console: ${c("dim", p.console_url)}\n`);
 
   } else if (subcommand === "add") {
-    // Download a legacy project's skills from the console and install them
-    // into the developer's local AI tools (Claude Code, Cursor, Copilot, Windsurf).
+    // Download a legacy project from the console and reconstruct the complete
+    // intelligence package folder structure — the exact same layout produced
+    // by the scanner so existing legacy-reading skills can work on it.
+    //
+    // Output:
+    //   <outputDir>/<project-slug>/
+    //     manifest.json
+    //     MASTER_SKILL.md          (master skill, if present)
+    //     modules/<name>/SKILL.md  (module skills)
+    //     diagrams/<name>.mmd
+    //     OVERVIEW.md / API_REGISTRY.md / RISK_REPORT.md … (reports/guides)
+
     const projectName = args[0];
     if (!projectName) {
-      console.log(c("red", "Usage: npx ai-skills legacy-projects add <project-name> [--path <dir>]"));
-      console.log(c("dim", "  Downloads the project's skills from the console and installs them into your AI tools.\n"));
+      console.log(c("red", "Usage: npx ai-skills legacy-projects add <project-name> [--path <output-dir>]"));
+      console.log(c("dim", "  Downloads the project intelligence package and recreates the original folder structure.\n"));
       process.exit(1);
     }
 
-    // Optional --path flag to also save raw files to a local directory
-    let outputPath = null;
+    // --path defaults to current working directory
+    let outputBase = process.cwd();
     for (let i = 1; i < args.length; i++) {
-      if (args[i] === "--path" && args[i + 1]) outputPath = args[++i];
+      if (args[i] === "--path" && args[i + 1]) outputBase = args[++i];
     }
 
-    console.log(c("blue", `\n━━━ Install Legacy Project: ${projectName} ━━━\n`));
+    console.log(c("blue", `\n━━━ Download Legacy Project: ${projectName} ━━━\n`));
+
     let result;
     try {
       result = await fetchJSONWithAuth(MANAGE_LEGACY_PROJECTS_URL, { action: "download", email, project_name: projectName }, null);
@@ -1693,80 +2102,141 @@ async function cmdLegacyProjects() {
     const documents = result.documents || [];
 
     if (documents.length === 0) {
-      console.log(c("yellow", "No documents found for this project.\n  Check the project name or upload a scan first with:\n  npx ai-skills upload-legacy-scan --path <dir>\n"));
+      console.log(c("yellow", `No documents found for "${projectName}".\n  Check the project name with:  npx ai-skills legacy-projects list\n`));
       return;
     }
 
-    const skillDocs = documents.filter((d) => d.category === "skill");
-    const reportDocs = documents.filter((d) => d.category === "report" || d.category === "guide");
+    const skillDocs   = documents.filter((d) => d.category === "skill");
+    const reportDocs  = documents.filter((d) => d.category === "report");
+    const guideDocs   = documents.filter((d) => d.category === "guide");
     const diagramDocs = documents.filter((d) => d.category === "diagram");
 
-    console.log(`  Project:  ${c("bold", project.name)}`);
-    console.log(`  Status:   ${project.status}  |  ${project.completeness_score}% complete`);
-    console.log(`  Skills:   ${skillDocs.length}   Reports: ${reportDocs.length}   Diagrams: ${diagramDocs.length}\n`);
+    console.log(`  Project:   ${c("bold", project.name)}`);
+    console.log(`  Status:    ${project.status}  |  ${project.completeness_score}% complete`);
+    console.log(`  Skills:    ${skillDocs.length}   Reports: ${reportDocs.length}   Guides: ${guideDocs.length}   Diagrams: ${diagramDocs.length}\n`);
+
+    // ── Create project root folder ──
+    const projectSlug = project.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+    const projectDir = path.resolve(outputBase, `${projectSlug}-intelligence`);
+    mkdirp(projectDir);
+    console.log(`  Saving to: ${c("bold", projectDir)}\n`);
+
+    // ── Skill documents ──
+    const masterDoc = skillDocs.find((d) => d.document_type === "master");
+    const moduleDocs = skillDocs.filter((d) => d.document_type !== "master").sort((a, b) => a.priority - b.priority);
+
+    if (masterDoc) {
+      fs.writeFileSync(path.join(projectDir, "MASTER_SKILL.md"), masterDoc.content);
+      console.log(`  ${c("green", "✓")} MASTER_SKILL.md`);
+    }
+
+    if (moduleDocs.length > 0) {
+      const modulesDir = path.join(projectDir, "modules");
+      mkdirp(modulesDir);
+      for (const doc of moduleDocs) {
+        const safeName = doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+        const modDir = path.join(modulesDir, safeName);
+        mkdirp(modDir);
+        fs.writeFileSync(path.join(modDir, "SKILL.md"), doc.content);
+        console.log(`  ${c("green", "✓")} modules/${safeName}/SKILL.md`);
+      }
+    }
+
+    // ── Report & guide documents — preserve built-ins, keep custom reports under reports/ ──
+    const REPORT_FILENAMES = Object.fromEntries(
+      Object.entries(BUILTIN_REPORT_SPECS).map(([documentType, spec]) => [documentType, spec.fileNames[0]])
+    );
+    const customReportsDir = path.join(projectDir, "reports");
+    const manifestReports = [];
 
-    // ── Install skill documents into local AI tools ──
-    if (skillDocs.length > 0) {
-      const tools = detectTools();
-      if (tools.length === 0) {
-        console.log(c("yellow", "  ⚠  No AI tools detected — install Claude Code, Cursor, Copilot, or Windsurf first.\n"));
-      } else {
-        // Build skill objects in the format installSkillsForTool expects
-        const skills = skillDocs.map((doc) => ({
-          name: `legacy-${doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")}`,
-          scope: "global",  // global so filterSkillsForProject passes them through
-          content: doc.content,
-        }));
-
-        console.log(`  Installing into detected AI tools:\n`);
-        for (const toolKey of tools) {
-          const tool = TOOL_CONFIGS[toolKey];
-          const count = installSkillsForTool(toolKey, skills);
-          console.log(`    ${c("green", "✓")} ${tool.name}: ${count} skill(s)`);
-        }
-        console.log("");
+    for (const doc of [...reportDocs, ...guideDocs]) {
+      const metadataPath = doc.metadata?.source_path ? String(doc.metadata.source_path).replace(/^\/+/, "") : "";
+      let relativePath = REPORT_FILENAMES[doc.document_type] || "";
+
+      if (!relativePath && metadataPath) {
+        relativePath = metadataPath;
       }
-    } else {
-      console.log(c("dim", "  No skills in this project (reports/diagrams only).\n"));
-    }
-
-    // ── Optionally save the full raw package to --path ──
-    if (outputPath) {
-      const resolved = path.resolve(outputPath);
-      mkdirp(resolved);
-
-      if (skillDocs.length > 0) {
-        const modulesDir = path.join(resolved, "modules");
-        mkdirp(modulesDir);
-        for (const doc of skillDocs) {
-          const safeName = doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-          const docDir = path.join(modulesDir, safeName);
-          mkdirp(docDir);
-          fs.writeFileSync(path.join(docDir, "SKILL.md"), doc.content);
-        }
+      if (!relativePath) {
+        const safeName = doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || doc.document_type;
+        relativePath = `reports/${safeName}.md`;
       }
 
-      for (const doc of reportDocs) {
-        const fileName = doc.document_type.toUpperCase() + ".md";
-        fs.writeFileSync(path.join(resolved, fileName), doc.content);
+      if (relativePath.includes("/") || relativePath.includes("\\")) {
+        mkdirp(path.dirname(path.join(projectDir, relativePath)));
       }
+      fs.writeFileSync(path.join(projectDir, relativePath), doc.content);
+      console.log(`  ${c("green", "✓")} ${relativePath}`);
+
+      if (doc.document_type in BUILTIN_REPORT_SPECS) {
+        manifestReports.push({
+          file: relativePath,
+          document_type: doc.document_type,
+          name: doc.name,
+          type: doc.category,
+        });
+      } else {
+        mkdirp(customReportsDir);
+        manifestReports.push({
+          file: relativePath,
+          document_type: doc.document_type,
+          name: doc.name,
+          type: "report",
+        });
+      }
+    }
 
-      if (diagramDocs.length > 0) {
-        const diagramsDir = path.join(resolved, "diagrams");
-        mkdirp(diagramsDir);
-        for (const doc of diagramDocs) {
-          const safeName = doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-          fs.writeFileSync(path.join(diagramsDir, `${safeName}.mmd`), doc.content);
-        }
+    // ── Diagram documents ──
+    if (diagramDocs.length > 0) {
+      const diagramsDir = path.join(projectDir, "diagrams");
+      mkdirp(diagramsDir);
+      for (const doc of diagramDocs) {
+        const safeName = doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+        const ext = doc.document_type === "mermaid" ? "mmd" : "mmd";
+        const diagramFile = `${safeName}.${ext}`;
+        fs.writeFileSync(path.join(diagramsDir, diagramFile), doc.content);
+        console.log(`  ${c("green", "✓")} diagrams/${diagramFile}`);
       }
+    }
 
-      console.log(`  ${c("green", "✓")} Raw files saved to: ${c("bold", resolved)}\n`);
+    // ── Reconstruct manifest.json ──
+    const manifestSkills = [];
+    if (masterDoc) {
+      manifestSkills.push({ name: masterDoc.name, type: "master", file: "MASTER_SKILL.md" });
     }
+    for (const doc of moduleDocs) {
+      const safeName = doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+      manifestSkills.push({ name: doc.name, type: "module", file: `modules/${safeName}/SKILL.md` });
+    }
+
+    const manifestDiagrams = diagramDocs.map((doc) => {
+      const safeName = doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+      return { name: doc.name, file: `diagrams/${safeName}.mmd`, type: doc.document_type };
+    });
 
-    console.log(c("green", `✓ "${project.name}" is ready. Restart your AI tool to activate the skills.\n`));
-    if (result.project?.console_url) {
-      console.log(`  Console: ${c("dim", result.project.console_url)}\n`);
+    const manifest = {
+      project: project.name,
+      scanned_at: project.last_scanned_at || new Date().toISOString(),
+      downloaded_at: new Date().toISOString(),
+      source: "valentia-skills-console",
+      tech_stack: project.tech_stack || {},
+      skills: manifestSkills,
+      diagrams: manifestDiagrams,
+      reports: manifestReports,
+      statistics: {
+        total_modules: moduleDocs.length,
+        total_diagrams: diagramDocs.length,
+        completeness_score: project.completeness_score,
+      },
+    };
+    fs.writeFileSync(path.join(projectDir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+    console.log(`  ${c("green", "✓")} manifest.json`);
+
+    console.log(c("green", `\n✓ "${project.name}" downloaded — ${documents.length} file(s)\n`));
+    console.log(`  Folder: ${c("bold", projectDir)}`);
+    if (project.console_url) {
+      console.log(`  Console: ${c("dim", project.console_url)}`);
     }
+    console.log("");
     return;
 
   } else if (subcommand === "remove") {
@@ -1800,6 +2270,297 @@ async function cmdLegacyProjects() {
   }
 }
 
+// ── Code Audit Commands ──
+
+async function cmdUploadCodeAudit() {
+  console.log(c("blue", "\n━━━ AI Skills Framework — Upload Code Audit ━━━\n"));
+
+  const args = process.argv.slice(3);
+  let auditPath = null;
+  let authToken = null;
+  let dryRun = false;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--path" && args[i + 1]) auditPath = args[++i];
+    else if (args[i] === "--token" && args[i + 1]) authToken = args[++i];
+    else if (args[i] === "--dry-run") dryRun = true;
+  }
+
+  if (!auditPath) {
+    console.log(c("red", "✗ --path is required."));
+    console.log(c("dim", "  Usage: npx ai-skills upload-code-audit --path ./CodeMatters/\n"));
+    process.exit(1);
+  }
+
+  const resolvedPath = path.resolve(auditPath);
+  if (!fs.existsSync(resolvedPath)) {
+    console.log(c("red", `✗ Path not found: ${resolvedPath}`));
+    process.exit(1);
+  }
+
+  const manifestPath = path.join(resolvedPath, "manifest.json");
+  if (!fs.existsSync(manifestPath)) {
+    console.log(c("red", `✗ manifest.json not found in ${resolvedPath}`));
+    console.log(c("dim", "  The CodeMatters folder must contain a manifest.json file.\n"));
+    process.exit(1);
+  }
+
+  const codeAuditConfig = await loadCodeAuditConfig();
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+  } catch (err) {
+    console.log(c("red", `✗ Failed to parse manifest.json: ${err.message}`));
+    process.exit(1);
+  }
+
+  const manifestSummary = await normalizeAuditManifestForCli(manifest);
+  const manifestError = validateAuditManifestForCli(manifestSummary, codeAuditConfig);
+  if (manifestError) {
+    console.log(c("red", `✗ ${manifestError}`));
+    process.exit(1);
+  }
+
+  const projectName =
+    manifest.project_name ??
+    manifest.project ??
+    manifest.name ??
+    manifest.repository_name;
+
+  if (!projectName || typeof projectName !== "string") {
+    console.log(c("red", "✗ manifest.json missing required field: project_name"));
+    process.exit(1);
+  }
+
+  console.log(`Project: ${c("bold", projectName)}`);
+  console.log(`Audited: ${c("dim", manifestSummary.audited_at)}`);
+  console.log(`Overall: ${c("bold", `${manifestSummary.overall_score}/100 (${manifestSummary.overall_grade})`)}`);
+  if (manifestSummary.tech_stack && Object.keys(manifestSummary.tech_stack).length > 0) {
+    const stackSummary = Object.entries(manifestSummary.tech_stack)
+      .filter(([, value]) => value)
+      .map(([key, value]) => `${key}: ${value}`)
+      .join(", ");
+    console.log(`Stack: ${c("cyan", stackSummary)}`);
+  }
+
+  const allFiles = walkFiles(resolvedPath);
+  const includedFiles = allFiles.filter((absolutePath) => {
+    const relativePath = path.relative(resolvedPath, absolutePath).split(path.sep).join("/");
+    if (relativePath === "manifest.json") return false;
+    return /\.(md|markdown|mmd|mermaid)$/i.test(absolutePath);
+  });
+
+  const documentsPayload = [];
+  for (const absolutePath of includedFiles) {
+    const relativePath = path.relative(resolvedPath, absolutePath).split(path.sep).join("/");
+    const fileName = path.basename(absolutePath);
+    const ext = path.extname(fileName).toLowerCase();
+    const content = fs.readFileSync(absolutePath, "utf-8");
+    const documentType = ext === ".mmd" || ext === ".mermaid"
+      ? "diagram"
+      : codeAuditConfig.inferCodeAuditDocumentType(fileName);
+    const definition = codeAuditConfig.getCodeAuditDocumentConfig(documentType);
+    const scoreEntry = definition?.scoreKey ? manifestSummary.scores[definition.scoreKey] : null;
+
+    documentsPayload.push({
+      name: fileName,
+      relative_path: `./${relativePath}`,
+      document_type: documentType,
+      category: ext === ".mmd" || ext === ".mermaid"
+        ? "diagram"
+        : definition?.category || codeAuditConfig.inferCodeAuditDocumentCategory(documentType),
+      content,
+      line_count: countLines(content),
+      category_score: scoreEntry?.score ?? null,
+      category_grade: scoreEntry?.grade ?? null,
+      finding_count: scoreEntry?.finding_count ?? null,
+    });
+  }
+
+  const manifestContent = fs.readFileSync(manifestPath, "utf-8");
+  documentsPayload.push({
+    name: "manifest.json",
+    relative_path: "./manifest.json",
+    document_type: "manifest",
+    category: "meta",
+    content: manifestContent,
+    line_count: countLines(manifestContent),
+    category_score: null,
+    category_grade: null,
+    finding_count: null,
+  });
+
+  const overviewCount = documentsPayload.filter((doc) => doc.category === "overview").length;
+  const reportCount = documentsPayload.filter((doc) => doc.category === "audit-report").length;
+  const planCount = documentsPayload.filter((doc) => doc.category === "plan").length;
+  const diagramCount = documentsPayload.filter((doc) => doc.category === "diagram").length;
+  const metaCount = documentsPayload.filter((doc) => doc.category === "meta").length;
+
+  console.log(`Documents: ${c("green", documentsPayload.length.toString())} file(s)`);
+  console.log(c("dim", `  Overview: ${overviewCount}  Reports: ${reportCount}  Plans: ${planCount}  Diagrams: ${diagramCount}  Meta: ${metaCount}`));
+  console.log(`Findings: ${c("dim", `critical ${manifestSummary.finding_count.critical}, high ${manifestSummary.finding_count.high}, medium ${manifestSummary.finding_count.medium}, low ${manifestSummary.finding_count.low}`)}`);
+  console.log("");
+
+  if (dryRun) {
+    console.log(c("yellow", "Dry run — payload summary:"));
+    console.log(`  Project name: ${projectName}`);
+    console.log(`  Audited at:   ${manifestSummary.audited_at}`);
+    console.log(`  Overall:      ${manifestSummary.overall_score}/100 (${manifestSummary.overall_grade})`);
+    console.log(`  Documents:    ${documentsPayload.length}`);
+    console.log(c("dim", "\nNo data was uploaded. Remove --dry-run to upload.\n"));
+    return;
+  }
+
+  let email = null;
+  if (!authToken) {
+    const config = loadConfig();
+    if (config?.email) {
+      email = config.email;
+      console.log(c("dim", `Using saved email: ${email}`));
+    } else {
+      console.log(c("yellow", "No saved config found. Enter your email to authenticate."));
+      email = await ask(`${c("bold", "Work email:")} `);
+      const otpResult = await requestOtpForEmail(email);
+      email = otpResult.email;
+      await verifyOtp(email);
+    }
+  }
+
+  console.log(c("dim", `Uploading audit to Valentia (${projectName})...\n`));
+  process.stdout.write(`  ${c("dim", "→")} Sending ${documentsPayload.length} documents...`);
+
+  let result;
+  try {
+    result = await fetchJSONWithAuth(
+      UPLOAD_CODE_AUDIT_URL,
+      {
+        project_name: projectName,
+        manifest,
+        documents: documentsPayload,
+        email,
+      },
+      authToken
+    );
+    console.log(c("green", " done!\n"));
+  } catch (err) {
+    console.log(c("red", " failed!"));
+    console.log(c("red", `\n✗ Upload failed: ${err.message}`));
+    console.log(c("dim", "  Retry with --dry-run to validate your payload without uploading.\n"));
+    process.exit(1);
+  }
+
+  console.log(c("green", "✓ Upload complete!\n"));
+  console.log(`  Audit ID: ${c("bold", result.audit_id)}`);
+  console.log(`  Overall:  ${c("bold", `${result.overall_score}/100 (${result.overall_grade})`)}`);
+  console.log(`  Documents stored: ${c("bold", String(result.documents_stored || 0))}`);
+  if (result.previous_audit) {
+    console.log(`  Previous audit: ${c("dim", `${result.previous_audit.score}/100 (${result.previous_audit.grade || "?"})`)}`);
+    console.log(`  Delta: ${c("dim", result.previous_audit.delta || "0")}`);
+  }
+  if ((result.storage_backups_failed || 0) > 0) {
+    console.log(c("yellow", `  Storage backups skipped for ${result.storage_backups_failed} document(s)`));
+  }
+  if (result.console_url) {
+    console.log(`\n  View in console: ${c("bold", result.console_url)}`);
+  }
+  console.log("");
+}
+
+async function cmdAuditStatus() {
+  const args = process.argv.slice(3);
+  let projectName = null;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--project" && args[i + 1]) projectName = args[++i];
+    else if (!projectName) projectName = args[i];
+  }
+
+  if (!projectName) {
+    console.log(c("red", "Usage: npx ai-skills audit-status --project <project-name>"));
+    process.exit(1);
+  }
+
+  const config = loadConfig();
+  const email = config?.email;
+  if (!email) {
+    console.log(c("yellow", "No saved config. Run 'npx ai-skills setup' first."));
+    process.exit(1);
+  }
+
+  const codeAuditConfig = await loadCodeAuditConfig();
+
+  console.log(c("blue", `\n━━━ Code Audit Status: ${projectName} ━━━\n`));
+
+  let result;
+  try {
+    result = await fetchJSONWithAuth(
+      MANAGE_CODE_AUDITS_URL,
+      { action: "status", email, project_name: projectName },
+      null
+    );
+  } catch (err) {
+    console.log(c("red", `✗ ${err.message}`));
+    process.exit(1);
+  }
+
+  const audit = result.audit;
+  const overallColor =
+    audit.overall_score >= 90 ? "green" :
+    audit.overall_score >= 75 ? "blue" :
+    audit.overall_score >= 60 ? "yellow" :
+    audit.overall_score >= 40 ? "yellow" :
+    "red";
+  const categories = Array.isArray(result.categories) ? result.categories : [];
+  const categoryByType = Object.fromEntries(categories.map((category) => [category.document_type, category]));
+  const history = Array.isArray(result.history) ? result.history : [];
+
+  console.log(`  Project: ${c("bold", result.project_name)}`);
+  console.log(`  Overall: ${c(overallColor, `${audit.overall_score}/100 (${audit.overall_grade})`)}`);
+  console.log(`  Status:  ${audit.status}`);
+  console.log(`  Audited: ${new Date(audit.audited_at).toLocaleString()}`);
+  console.log(`  Findings: critical ${audit.critical_count}  high ${audit.high_count}  medium ${audit.medium_count}  low ${audit.low_count}  total ${audit.total_findings}`);
+  if (audit.score_delta !== null && audit.score_delta !== undefined) {
+    console.log(`  Delta:   ${formatScoreDelta(audit.score_delta)}`);
+  }
+  if (audit.console_url) {
+    console.log(`  Console: ${c("dim", audit.console_url)}`);
+  }
+  console.log("");
+
+  console.log(c("bold", "  Category Scores"));
+  for (const definition of codeAuditConfig.getCodeAuditDashboardDefinitions()) {
+    const category = categoryByType[definition.documentType];
+    if (!category) continue;
+    const findingCount = category.finding_count || {};
+    console.log(
+      `    ${definition.label.padEnd(16)} ${String(category.score).padStart(3)}/100  ${category.grade || "?"}  ` +
+      `${findingCount.critical || 0}c ${findingCount.high || 0}h ${findingCount.medium || 0}m ${findingCount.low || 0}l`
+    );
+  }
+
+  if (history.length > 0) {
+    console.log(`\n${c("bold", "  Recent History")}`);
+    for (const entry of history.slice(-5)) {
+      console.log(
+        `    ${new Date(entry.audited_at).toLocaleDateString()}  ` +
+        `${String(entry.overall_score).padStart(3)}/100 (${entry.overall_grade})  ` +
+        `findings ${entry.total_findings}  critical ${entry.critical_count}`
+      );
+    }
+  }
+
+  if (result.previous_audit) {
+    console.log(`\n${c("bold", "  Previous Audit")}`);
+    console.log(
+      `    ${new Date(result.previous_audit.audited_at).toLocaleDateString()}  ` +
+      `${result.previous_audit.overall_score}/100 (${result.previous_audit.overall_grade})`
+    );
+  }
+
+  console.log("");
+}
+
 // ── Main ──
 
 const command = process.argv[2] || "setup";
@@ -1811,6 +2572,8 @@ switch (command) {
   case "list": cmdList(); break;
   case "doctor": cmdDoctor(); break;
   case "analyze": cmdAnalyze(); break;
+  case "upload-code-audit": cmdUploadCodeAudit(); break;
+  case "audit-status": cmdAuditStatus(); break;
   case "upload-legacy-scan": cmdUploadLegacyScan(); break;
   case "legacy-projects": cmdLegacyProjects(); break;
   case "help": case "--help": case "-h":
@@ -1823,9 +2586,11 @@ Usage:
   npx ai-skills status   Show installed toolkit, team, and tools
   npx ai-skills list     List locally bundled skills
   npx ai-skills analyze  Analyze last commit against active skills
+  npx ai-skills upload-code-audit  Upload a CodeMatters audit package
+  npx ai-skills audit-status --project <name>   Show latest audit summary for a project
   npx ai-skills upload-legacy-scan  Upload a legacy codebase intelligence package
-  npx ai-skills legacy-projects add <name>             Download project skills → install into AI tools
-  npx ai-skills legacy-projects add <name> --path <dir> Also save raw files to a local directory
+  npx ai-skills legacy-projects add <name>             Download project → recreate intelligence folder locally
+  npx ai-skills legacy-projects add <name> --path <dir> Save to a specific directory (default: cwd)
   npx ai-skills legacy-projects list               List all legacy projects
   npx ai-skills legacy-projects status <name>      Show project status and document counts
   npx ai-skills legacy-projects remove <name>      Delete a project and all its documents
@@ -1833,6 +2598,9 @@ Usage:
 
 Flags:
   analyze --last         Analyze the most recent commit
+  upload-code-audit --path <dir>   Path to CodeMatters folder
+  upload-code-audit --dry-run      Validate payload without uploading
+  upload-code-audit --token <tok>  Explicit auth token
   upload-legacy-scan --path <dir>   Path to intelligence folder
   upload-legacy-scan --dry-run      Validate payload without uploading
   upload-legacy-scan --token <tok>  Explicit auth token
@@ -1841,6 +2609,8 @@ Toolkit includes: skills, agents, commands, hooks, rules, MCP configs.
 
 Environment:
   AI_SKILLS_API_URL      Override the Supabase Edge Function URL
+  AI_SKILLS_UPLOAD_CODE_AUDIT_URL  Override the upload-code-audit Edge Function URL
+  AI_SKILLS_MANAGE_CODE_AUDITS_URL Override the manage-code-audits Edge Function URL
 `); break;
   default:
     console.log(c("red", `Unknown command: ${command}`));