@valentia-ai-skills/framework 2.0.3 → 2.0.5

package/README.md

@@ -65,16 +65,28 @@ npx ai-skills help           # Show help
 #### Legacy Codebase Intelligence Scanner
 
 ```bash
-# Upload a legacy codebase intelligence package to your team's Skills Console
-npx ai-skills upload-legacy-scan --path ./my-project-intelligence/
+# Add / refresh a project by uploading a scan intelligence package
+npx ai-skills legacy-projects add --path ./my-project-intelligence/
 
-# Validate the package payload without uploading (dry run)
-npx ai-skills upload-legacy-scan --path ./my-project-intelligence/ --dry-run
+# Validate the payload without uploading (dry run)
+npx ai-skills legacy-projects add --path ./my-project-intelligence/ --dry-run
 
 # Supply an explicit auth token instead of going through OTP
-npx ai-skills upload-legacy-scan --path ./my-project-intelligence/ --token <your-token>
+npx ai-skills legacy-projects add --path ./my-project-intelligence/ --token <your-token>
+
+# List all legacy projects for your team
+npx ai-skills legacy-projects list
+
+# Show detailed status + document counts for a project
+npx ai-skills legacy-projects status "My Project"
+
+# Delete a project and all its documents (irreversible — prompts for confirmation)
+npx ai-skills legacy-projects remove "My Project"
 ```
 
+> `upload-legacy-scan` is also available as a direct alias:
+> `npx ai-skills upload-legacy-scan --path ./my-project-intelligence/`
+
 The `--path` directory must contain a `manifest.json` file. See the [Legacy Scanner](#legacy-codebase-intelligence-scanner) section below for the required format.
 
 ### Environment Variables
@@ -85,6 +97,7 @@ The `--path` directory must contain a `manifest.json` file. See the [Legacy Scan
 | `AI_SKILLS_ANALYZE_URL` | Override the analyze commit function URL |
 | `AI_SKILLS_SCAN_URL` | Override the scan results function URL |
 | `AI_SKILLS_UPLOAD_LEGACY_URL` | Override the upload-legacy-scan Edge Function URL |
+| `AI_SKILLS_MANAGE_LEGACY_URL` | Override the manage-legacy-projects Edge Function URL |
 
 ---
 
@@ -276,9 +289,10 @@ The framework supports ingesting intelligence packages generated by legacy codeb
 ### How It Works
 
 1. **Scan** — A compatible scanner tool analyses an existing codebase and produces an intelligence folder
-2. **Upload** — `npx ai-skills upload-legacy-scan --path <folder>` packages and ships the output to your team's console
-3. **Review** — Tech leads review auto-generated skills, approve or request revisions per skill, and publish approved skills into the active toolkit
-4. **Rescan** — Re-running the upload on the same project name appends a new version, preserving history
+2. **Add** — `npx ai-skills legacy-projects add --path <folder>` uploads the package, creating the project if it doesn't exist or replacing its documents if it does
+3. **Review** — Tech leads review auto-generated skills, reports, and diagrams in the Skills Console, approving or flagging each document
+4. **Promote** — Approved skills are promoted into the team's active toolkit and distributed on the next `npx ai-skills update`
+5. **Rescan** — Re-running `add` on the same project name replaces all documents with the latest scan output
 
 ### Intelligence Package Format
 
@@ -318,18 +332,34 @@ my-project-intelligence/
 
 ### Skills Console — Legacy Scanners View
 
-After upload, each project appears in the **Legacy Scanners** section of the Skills Console with:
+After upload, each project appears in the **Legacy Scanners** section of the Skills Console with five tabs:
 
-- **Overview** — project stats, completeness score, tech stack
-- **Modules** — per-skill approval workflow (approve / needs revision)
-- **API Registry** — searchable endpoint documentation
-- **Business Rules** — searchable rule catalogue
-- **Architecture** — interactive Mermaid diagrams
-- **Risk Report** — severity-categorised risk sections
-- **Reproduction Guide** — interactive onboarding checklist
+| Tab | Contents |
+|-----|----------|
+| **Overview** | Project stats, completeness score, tech stack, interactive reproduction guide |
+| **Skills** | Per-skill approval workflow — approve or flag each extracted skill |
+| **Reports** | Searchable reports: API registry, business rules, data models, risk report, etc. |
+| **Architecture** | Interactive Mermaid architecture and ER diagrams |
+| **All Files** | Full document list with category filter + content copy |
 
 Approved skills are promoted into the team's standard toolkit and distributed on the next `npx ai-skills update`.
 
+### Managing Projects from the CLI
+
+```bash
+# Add a new project (or refresh an existing one)
+npx ai-skills legacy-projects add --path ./my-project-intelligence/
+
+# List all projects with status, module count, and completeness score
+npx ai-skills legacy-projects list
+
+# Inspect a specific project — shows document counts per category
+npx ai-skills legacy-projects status "My Project"
+
+# Permanently delete a project and all its documents
+npx ai-skills legacy-projects remove "My Project"
+```
+
 ---
 
 ## Architecture

package/bin/cli.js

@@ -1415,18 +1415,23 @@ async function cmdUploadLegacyScan() {
 
   // ── Read skill files ──
   const skillPayload = [];
+  let modulePriority = 1;
   for (const skillEntry of (manifest.skills || [])) {
-    const skillFile = skillEntry.file || skillEntry.path; // accept both field names
+    const skillFile = skillEntry.file || skillEntry.path;
     if (!skillEntry.name || !skillFile) continue;
     const skillFilePath = path.join(resolvedPath, skillFile);
     if (!fs.existsSync(skillFilePath)) {
       console.log(c("yellow", `  ⚠ Skill file not found: ${skillFile} — skipping`));
       continue;
     }
+    const isMaster = (skillEntry.type || "module") === "master";
     skillPayload.push({
+      category: "skill",
+      document_type: isMaster ? "master" : "module",
       name: skillEntry.name,
-      type: skillEntry.type || "module",
       content: fs.readFileSync(skillFilePath, "utf-8"),
+      priority: isMaster ? 0 : modulePriority++,
+      metadata: {},
     });
   }
   console.log(`Skills: ${c("green", skillPayload.length.toString())} module(s)`);
@@ -1434,7 +1439,7 @@ async function cmdUploadLegacyScan() {
   // ── Read diagram files ──
   const diagramPayload = [];
   for (const diagramEntry of (manifest.diagrams || [])) {
-    const diagramFile = diagramEntry.file || diagramEntry.path; // accept both field names
+    const diagramFile = diagramEntry.file || diagramEntry.path;
     if (!diagramEntry.name || !diagramFile) continue;
     const diagramFilePath = path.join(resolvedPath, diagramFile);
     if (!fs.existsSync(diagramFilePath)) {
@@ -1442,9 +1447,12 @@ async function cmdUploadLegacyScan() {
       continue;
     }
     diagramPayload.push({
+      category: "diagram",
+      document_type: diagramEntry.type || "architecture",
       name: diagramEntry.name,
-      type: diagramEntry.type || "architecture",
       content: fs.readFileSync(diagramFilePath, "utf-8"),
+      priority: 0,
+      metadata: {},
     });
   }
   // Auto-discover .mmd/.mermaid files from diagrams/ subdirectory if manifest listed none
@@ -1455,9 +1463,12 @@ async function cmdUploadLegacyScan() {
         if (/\.(mmd|mermaid)$/i.test(file)) {
           const name = file.replace(/\.(mmd|mermaid)$/i, "");
           diagramPayload.push({
+            category: "diagram",
+            document_type: "architecture",
             name,
-            type: "architecture",
             content: fs.readFileSync(path.join(diagramsDir, file), "utf-8"),
+            priority: 0,
+            metadata: {},
           });
         }
       }
@@ -1468,17 +1479,18 @@ async function cmdUploadLegacyScan() {
   }
   console.log(`Diagrams: ${c("green", diagramPayload.length.toString())} file(s)`);
 
-  // ── Read report files ──
-  const reportsPayload = {};
+  // ── 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"],
+    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"],
   };
 
@@ -1490,23 +1502,36 @@ async function cmdUploadLegacyScan() {
       ];
       const found = reportPaths.find((p) => fs.existsSync(p));
       if (found) {
-        reportsPayload[key] = fs.readFileSync(found, "utf-8");
+        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;
       }
     }
   }
 
-  const reportCount = Object.keys(reportsPayload).length;
+  const reportCount = reportPayload.length;
   console.log(`Reports: ${c("green", reportCount.toString())} file(s)\n`);
 
+  // ── Build unified documents array ──
+  const documentsPayload = [...skillPayload, ...diagramPayload, ...reportPayload];
+
   // ── Dry run: print summary and exit ──
   if (dryRun) {
     console.log(c("yellow", "Dry run — payload summary:"));
     const stats = manifest.statistics || {};
     console.log(`  Project name: ${projectName}`);
-    console.log(`  Modules: ${skillPayload.length}`);
-    console.log(`  Diagrams: ${diagramPayload.length}`);
-    console.log(`  Reports: ${reportCount}`);
+    console.log(`  Documents total: ${documentsPayload.length}`);
+    console.log(`  — Skills: ${skillPayload.length}`);
+    console.log(`  — Diagrams: ${diagramPayload.length}`);
+    console.log(`  — Reports/Guides: ${reportCount}`);
     if (stats.completeness_score !== undefined) {
       console.log(`  Completeness: ${stats.completeness_score}%`);
     }
@@ -1526,13 +1551,13 @@ async function cmdUploadLegacyScan() {
       email = await ask(`${c("bold", "Work email:")} `);
       const otpResult = await requestOtpForEmail(email);
       email = otpResult.email;
-      await verifyOtp(email); // we only need the OTP verification, not the toolkit
+      await verifyOtp(email);
     }
   }
 
   // ── Upload ──
   console.log(c("dim", `Uploading to Valentia (${projectName})...\n`));
-  process.stdout.write(`  ${c("dim", "→")} Sending ${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)...`);
 
   let result;
   try {
@@ -1541,9 +1566,7 @@ async function cmdUploadLegacyScan() {
       {
         project_name: projectName,
         manifest,
-        skills: skillPayload,
-        diagrams: diagramPayload,
-        reports: reportsPayload,
+        documents: documentsPayload,
         email,
       },
       authToken
@@ -1558,12 +1581,9 @@ async function cmdUploadLegacyScan() {
 
   console.log(c("green", "✓ Upload complete!\n"));
   console.log(`  Project ID: ${c("bold", result.project_id)}`);
-  console.log(`  Skills created: ${c("bold", (result.skills_created || []).length.toString())}`);
-  if (result.storage_urls?.diagrams?.length) {
-    console.log(`  Diagrams stored: ${c("dim", result.storage_urls.diagrams.length.toString())}`);
-  }
-  if (result.storage_urls?.reports?.length) {
-    console.log(`  Reports stored: ${c("dim", result.storage_urls.reports.length.toString())}`);
+  console.log(`  Documents created: ${c("bold", (result.documents_created || 0).toString())}`);
+  if (result.skills_count > 0) {
+    console.log(`  Skills: ${c("dim", result.skills_count.toString())}`);
   }
   if (result.console_url) {
     console.log(`\n  View in console: ${c("bold", result.console_url)}`);
@@ -1571,6 +1591,115 @@ async function cmdUploadLegacyScan() {
   console.log("");
 }
 
+// ── Legacy Projects Command ──
+
+const MANAGE_LEGACY_PROJECTS_URL =
+  process.env.AI_SKILLS_MANAGE_LEGACY_URL ||
+  "https://znshdhjquohrzvbnloki.supabase.co/functions/v1/manage-legacy-projects";
+
+async function cmdLegacyProjects() {
+  const subcommand = process.argv[3] || "list";
+  const args = process.argv.slice(4);
+
+  // Resolve email
+  const config = loadConfig();
+  let email = config?.email;
+  if (!email) {
+    console.log(c("yellow", "No saved config. Run 'npx ai-skills setup' first."));
+    process.exit(1);
+  }
+
+  if (subcommand === "list") {
+    console.log(c("blue", "\n━━━ Legacy Projects ━━━\n"));
+    let result;
+    try {
+      result = await fetchJSONWithAuth(MANAGE_LEGACY_PROJECTS_URL, { action: "list", email }, null);
+    } catch (err) {
+      console.log(c("red", `✗ ${err.message}`));
+      process.exit(1);
+    }
+    const projects = result.projects || [];
+    if (projects.length === 0) {
+      console.log(c("dim", "No legacy projects found.\n"));
+      return;
+    }
+    for (const p of projects) {
+      const statusColor = p.status === "fully_approved" ? "green" : p.status === "partially_approved" ? "yellow" : "dim";
+      const scanDate = p.last_scanned_at ? new Date(p.last_scanned_at).toLocaleDateString() : "?";
+      console.log(`  ${c("bold", p.name)}`);
+      console.log(`    Status: ${c(statusColor, p.status)}  |  ${p.module_count} modules  |  ${p.completeness_score}%  |  Scanned: ${scanDate}`);
+      console.log(`    ${c("dim", p.console_url)}`);
+      console.log("");
+    }
+    console.log(c("dim", `  ${projects.length} project(s)\n`));
+
+  } else if (subcommand === "status") {
+    const projectName = args[0];
+    if (!projectName) {
+      console.log(c("red", "Usage: npx ai-skills legacy-projects status <project-name>"));
+      process.exit(1);
+    }
+    console.log(c("blue", `\n━━━ Legacy Project: ${projectName} ━━━\n`));
+    let result;
+    try {
+      result = await fetchJSONWithAuth(MANAGE_LEGACY_PROJECTS_URL, { action: "status", email, project_name: projectName }, null);
+    } catch (err) {
+      console.log(c("red", `✗ ${err.message}`));
+      process.exit(1);
+    }
+    const p = result.project;
+    const docs = result.documents || {};
+    const statusColor = p.status === "fully_approved" ? "green" : p.status === "partially_approved" ? "yellow" : "dim";
+    console.log(`  Project: ${c("bold", p.name)}`);
+    console.log(`  Status:  ${c(statusColor, p.status)}`);
+    console.log(`  Completeness: ${p.completeness_score}%`);
+    console.log(`  Modules: ${p.module_count}  |  Endpoints: ${p.total_endpoints}  |  Rules: ${p.total_business_rules}`);
+    console.log(`  Scanned:      ${p.last_scanned_at ? new Date(p.last_scanned_at).toLocaleDateString() : "?"}`);
+    console.log("");
+    if (Object.keys(docs).length > 0) {
+      console.log(c("bold", "  Documents:"));
+      for (const [cat, counts] of Object.entries(docs)) {
+        console.log(`    ${cat.padEnd(10)} ${counts.total} total, ${counts.approved} approved, ${counts.pending} pending`);
+      }
+    }
+    console.log(`\n  Console: ${c("dim", p.console_url)}\n`);
+
+  } else if (subcommand === "add") {
+    // Delegate to upload-legacy-scan — argv flags (--path, --dry-run, --token) are preserved
+    await cmdUploadLegacyScan();
+    return;
+
+  } else if (subcommand === "remove") {
+    const projectName = args[0];
+    if (!projectName) {
+      console.log(c("red", "Usage: npx ai-skills legacy-projects remove <project-name>"));
+      process.exit(1);
+    }
+    const confirm = await ask(`${c("red", `Delete "${projectName}" and all its documents? This cannot be undone. Type the project name to confirm: `)} `);
+    if (confirm.trim() !== projectName) {
+      console.log(c("yellow", "Cancelled.\n"));
+      return;
+    }
+    let result;
+    try {
+      result = await fetchJSONWithAuth(MANAGE_LEGACY_PROJECTS_URL, { action: "remove", email, project_name: projectName }, null);
+    } catch (err) {
+      console.log(c("red", `✗ ${err.message}`));
+      process.exit(1);
+    }
+    if (result.removed) {
+      console.log(c("green", `✓ "${result.name}" deleted.\n`));
+    } else {
+      console.log(c("red", "Failed to delete project."));
+    }
+
+  } else {
+    console.log(c("red", `Unknown subcommand: ${subcommand}`));
+    console.log(c("dim", "Usage: npx ai-skills legacy-projects add --path <dir> | list | status <name> | remove <name>\n"));
+    process.exit(1);
+  }
+}
+
 // ── Main ──
 
 const command = process.argv[2] || "setup";
@@ -1583,6 +1712,7 @@ switch (command) {
   case "doctor": cmdDoctor(); break;
   case "analyze": cmdAnalyze(); break;
   case "upload-legacy-scan": cmdUploadLegacyScan(); break;
+  case "legacy-projects": cmdLegacyProjects(); break;
   case "help": case "--help": case "-h":
     console.log(`
 ${c("blue", "AI Skills Framework")} — @valentia-ai-skills/framework
@@ -1594,6 +1724,10 @@ Usage:
   npx ai-skills list     List locally bundled skills
   npx ai-skills analyze  Analyze last commit against active skills
   npx ai-skills upload-legacy-scan  Upload a legacy codebase intelligence package
+  npx ai-skills legacy-projects add --path <dir>   Upload a scan package and add / refresh the project
+  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
   npx ai-skills doctor   Health check (config + API + tools)
 
 Flags:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentia-ai-skills/framework",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "AI development skills framework centralized coding standards, security patterns, and SOPs for AI-assisted development. Works with Claude Code, Cursor, Copilot, Windsurf, and any AI coding tool.",
   "keywords": [
     "ai-skills",

package/skills/global/aisupportapp-project-architecture/SKILL.md

@@ -3,7 +3,7 @@ name: aisupportapp/project-architecture
 description: Auto-generated project-architecture for aisupportapp. Created by project-scanner.
 version: 1.0.0
 scope: project
-last_reviewed: 2026-03-28
+last_reviewed: 2026-03-29
 ---
 
 ---

package/skills/global/aisupportapp-project-conventions/SKILL.md

@@ -3,7 +3,7 @@ name: aisupportapp/project-conventions
 description: Auto-generated project-conventions for aisupportapp. Created by project-scanner.
 version: 1.0.0
 scope: project
-last_reviewed: 2026-03-28
+last_reviewed: 2026-03-29
 ---
 
 ---

package/skills/global/aisupportapp-project-workflows/SKILL.md

@@ -3,7 +3,7 @@ name: aisupportapp/project-workflows
 description: Auto-generated project-workflows for aisupportapp. Created by project-scanner.
 version: 1.0.0
 scope: project
-last_reviewed: 2026-03-28
+last_reviewed: 2026-03-29
 ---
 
 ---

package/skills/global/aisupportapp-test-installation/SKILL.md

@@ -3,7 +3,7 @@ name: aisupportapp/test-installation
 description: No description
 version: 1.0.0
 scope: project
-last_reviewed: 2026-03-28
+last_reviewed: 2026-03-29
 ---
 
 # Skill Name

package/skills/global/api-design/SKILL.md

@@ -3,7 +3,7 @@ name: api-design
 description: No description
 version: 1.0.0
 scope: global
-last_reviewed: 2026-03-28
+last_reviewed: 2026-03-29
 ---
 
 ---

package/skills/global/appointment-oas-app/SKILL.md

@@ -3,7 +3,7 @@ name: appointment-oas-app
 description: No description
 version: 1.0.1
 scope: global
-last_reviewed: 2026-03-28
+last_reviewed: 2026-03-29
 ---
 
 ---

package/skills/global/code-standards/SKILL.md

@@ -3,7 +3,7 @@ name: code-standards
 description: No description
 version: 1.0.0
 scope: global
-last_reviewed: 2026-03-28
+last_reviewed: 2026-03-29
 ---
 
 ---

package/skills/global/codebase-legacy-intelligence/SKILL.md

@@ -3,7 +3,7 @@ name: codebase-legacy-intelligence
 description: A complete project Ecosystem Builder
 version: 1.0.0
 scope: global
-last_reviewed: 2026-03-28
+last_reviewed: 2026-03-29
 ---
 
 ---

package/skills/global/project-scanner/SKILL.md

@@ -11,7 +11,7 @@ description: Reverse-engineer any codebase into AI-ready skill files. Use this s
   auto-trigger.
 version: 1.0.0
 scope: global
-last_reviewed: 2026-03-28
+last_reviewed: 2026-03-29
 ---
 
 # Project Scanner

package/skills/global/viteapp-core-workflows/SKILL.md

@@ -3,7 +3,7 @@ name: viteapp/core-workflows
 description: No description
 version: 1.0.0
 scope: project
-last_reviewed: 2026-03-28
+last_reviewed: 2026-03-29
 ---
 
 # Skill Name