@sporesec/arcana 3.0.0 → 3.0.2

package/dist/cli.js

@@ -127,6 +127,9 @@ export function createCli() {
         .option("-a, --all", "Validate all installed skills")
         .option("-f, --fix", "Auto-fix common issues")
         .option("-j, --json", "Output as JSON")
+        .option("--source <dir>", "Validate from source directory instead of install dir")
+        .option("--cross", "Run cross-validation (marketplace sync, companions, orphans)")
+        .option("--min-score <n>", "Minimum quality score (0-100), fail if any skill scores below", parseInt)
         .action(async (skill, opts) => {
         const { validateCommand } = await import("./commands/validate.js");
         return validateCommand(skill, opts);
@@ -213,6 +216,7 @@ export function createCli() {
         .description("Audit skill quality (code examples, BAD/GOOD pairs, structure)")
         .option("-a, --all", "Audit all installed skills")
         .option("-j, --json", "Output as JSON")
+        .option("--source <dir>", "Audit from source directory instead of install dir")
         .action(async (skill, opts) => {
         const { auditCommand } = await import("./commands/audit.js");
         return auditCommand(skill, opts);

package/dist/commands/audit.d.ts

@@ -1,4 +1,4 @@
-interface AuditResult {
+export interface AuditResult {
     skill: string;
     rating: "PERFECT" | "STRONG" | "ADEQUATE" | "WEAK";
     score: number;
@@ -12,5 +12,5 @@ export declare function auditSkill(skillDir: string, skillName: string): AuditRe
 export declare function auditCommand(skill: string | undefined, opts: {
     all?: boolean;
     json?: boolean;
+    source?: string;
 }): Promise<void>;
-export {};

package/dist/commands/audit.js

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { getInstallDir } from "../utils/fs.js";
 import { extractFrontmatter, parseFrontmatter } from "../utils/frontmatter.js";
 import { ui, banner } from "../utils/ui.js";
@@ -76,9 +76,25 @@ export function auditSkill(skillDir, skillName) {
     });
     if (hasExtras)
         score += 10;
-    // Rating
+    // 9. Section diversity (3+ unique ## headings)
+    const uniqueHeadings = new Set((body.match(/^## .+$/gm) || []).map((h) => h.toLowerCase()));
+    const goodDiversity = uniqueHeadings.size >= 3;
+    checks.push({
+        name: "Section diversity (3+ unique headings)",
+        passed: goodDiversity,
+        detail: `${uniqueHeadings.size} unique sections`,
+    });
+    if (goodDiversity)
+        score += 5;
+    // 10. Numbered steps (task decomposition signal)
+    const numberedSteps = (body.match(/^\d+\.\s/gm) || []).length;
+    const hasSteps = numberedSteps >= 3;
+    checks.push({ name: "Has numbered steps (3+)", passed: hasSteps, detail: `${numberedSteps} steps` });
+    if (hasSteps)
+        score += 5;
+    // Rating (max possible: 110)
     let rating;
-    if (score >= 85)
+    if (score >= 90)
         rating = "PERFECT";
     else if (score >= 65)
         rating = "STRONG";
@@ -91,8 +107,8 @@ export function auditSkill(skillDir, skillName) {
 export async function auditCommand(skill, opts) {
     if (!opts.json)
         banner();
-    const installDir = getInstallDir();
-    if (!existsSync(installDir)) {
+    const baseDir = opts.source ? resolve(opts.source) : getInstallDir();
+    if (!existsSync(baseDir)) {
         if (opts.json) {
             console.log(JSON.stringify({ results: [] }));
         }
@@ -104,7 +120,14 @@ export async function auditCommand(skill, opts) {
     }
     let skills;
     if (opts.all) {
-        skills = readdirSync(installDir).filter((d) => statSync(join(installDir, d)).isDirectory());
+        skills = readdirSync(baseDir).filter((d) => {
+            try {
+                return statSync(join(baseDir, d)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
     }
     else if (skill) {
         skills = [skill];
@@ -123,7 +146,7 @@ export async function auditCommand(skill, opts) {
     }
     const results = [];
     for (const name of skills.sort()) {
-        const skillDir = join(installDir, name);
+        const skillDir = join(baseDir, name);
         if (!existsSync(skillDir)) {
             results.push({ skill: name, rating: "WEAK", score: 0, checks: [{ name: "Exists", passed: false }] });
             continue;
@@ -144,7 +167,7 @@ export async function auditCommand(skill, opts) {
                 : r.rating === "ADEQUATE"
                     ? ui.warn
                     : ui.error;
-        console.log(`  ${ratingColor(`[${r.rating}]`)} ${ui.bold(r.skill)} ${ui.dim(`(${r.score}/100)`)}`);
+        console.log(`  ${ratingColor(`[${r.rating}]`)} ${ui.bold(r.skill)} ${ui.dim(`(${r.score}/110)`)}`);
         for (const check of r.checks) {
             if (!check.passed) {
                 const detail = check.detail ? ` ${ui.dim(`(${check.detail})`)}` : "";

package/dist/commands/uninstall.js

@@ -5,6 +5,7 @@ import chalk from "chalk";
 import { getSkillDir, listSymlinks, readSkillMeta } from "../utils/fs.js";
 import { renderBanner } from "../utils/help.js";
 import { validateSlug } from "../utils/validate.js";
+import { backupSkill } from "../utils/backup.js";
 export async function uninstallCommand(skillNames, opts = {}) {
     if (opts.json) {
         return uninstallJson(skillNames);
@@ -49,7 +50,8 @@ async function uninstallOneInteractive(skillName, skipConfirm) {
         }
     }
     const spin = p.spinner();
-    spin.start(`Removing ${skillName}...`);
+    spin.start(`Backing up and removing ${skillName}...`);
+    backupSkill(skillName);
     rmSync(skillDir, { recursive: true, force: true });
     const symlinksRemoved = removeSymlinksFor(skillName);
     spin.stop(`Removed ${chalk.bold(skillName)}`);
@@ -88,6 +90,7 @@ async function uninstallMultipleInteractive(skillNames, skipConfirm) {
     for (let i = 0; i < toRemove.length; i++) {
         const skillName = toRemove[i];
         spin.start(`Removing ${chalk.bold(skillName)} (${i + 1}/${toRemove.length})...`);
+        backupSkill(skillName);
         rmSync(getSkillDir(skillName), { recursive: true, force: true });
         totalSymlinks += removeSymlinksFor(skillName);
     }

package/dist/commands/validate.d.ts

@@ -2,4 +2,7 @@ export declare function validateCommand(skill: string | undefined, opts: {
     all?: boolean;
     fix?: boolean;
     json?: boolean;
+    source?: string;
+    cross?: boolean;
+    minScore?: number;
 }): Promise<void>;

package/dist/commands/validate.js

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { getInstallDir } from "../utils/fs.js";
 import { validateSkillDir, fixSkillFrontmatter } from "../utils/frontmatter.js";
 import { atomicWriteSync } from "../utils/atomic.js";
@@ -8,8 +8,8 @@ import { scanSkillContent } from "../utils/scanner.js";
 export async function validateCommand(skill, opts) {
     if (!opts.json)
         banner();
-    const installDir = getInstallDir();
-    if (!existsSync(installDir)) {
+    const baseDir = opts.source ? resolve(opts.source) : getInstallDir();
+    if (!existsSync(baseDir)) {
         if (opts.json) {
             console.log(JSON.stringify({ results: [] }));
         }
@@ -21,7 +21,14 @@ export async function validateCommand(skill, opts) {
     }
     let skills;
     if (opts.all) {
-        skills = readdirSync(installDir).filter((d) => statSync(join(installDir, d)).isDirectory());
+        skills = readdirSync(baseDir).filter((d) => {
+            try {
+                return statSync(join(baseDir, d)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
     }
     else if (skill) {
         skills = [skill];
@@ -40,7 +47,7 @@ export async function validateCommand(skill, opts) {
     }
     const results = [];
     for (const name of skills) {
-        const skillDir = join(installDir, name);
+        const skillDir = join(baseDir, name);
         if (!existsSync(skillDir)) {
             results.push({ skill: name, valid: false, errors: ["Not installed"], warnings: [], infos: [] });
             continue;
@@ -85,10 +92,42 @@ export async function validateCommand(skill, opts) {
                 /* skip if unreadable */
             }
         }
-        results.push(result);
+        // Quality scoring (when --min-score is set)
+        const entry = { ...result };
+        if (opts.minScore !== undefined) {
+            const { auditSkill } = await import("./audit.js");
+            const audit = auditSkill(skillDir, name);
+            entry.qualityScore = audit.score;
+            entry.qualityRating = audit.rating;
+            if (audit.score < opts.minScore) {
+                entry.valid = false;
+                entry.errors.push(`Quality score ${audit.score} below minimum ${opts.minScore} (${audit.rating})`);
+            }
+        }
+        results.push(entry);
+    }
+    // Cross-validation (when --cross is set)
+    let crossIssues = [];
+    if (opts.cross) {
+        const { crossValidate } = await import("../utils/quality.js");
+        const marketplacePaths = opts.source
+            ? [
+                resolve(opts.source, "..", ".claude-plugin", "marketplace.json"),
+                resolve(opts.source, ".claude-plugin", "marketplace.json"),
+            ]
+            : [resolve(baseDir, "..", ".claude-plugin", "marketplace.json")];
+        const marketplacePath = marketplacePaths.find((p) => existsSync(p));
+        if (marketplacePath) {
+            crossIssues = crossValidate(baseDir, marketplacePath);
+        }
+        else if (!opts.json) {
+            console.log(ui.warn("  Could not find marketplace.json for cross-validation"));
+        }
     }
+    const hasErrors = results.some((r) => !r.valid);
+    const hasCrossErrors = crossIssues.some((i) => i.level === "error");
     if (opts.json) {
-        console.log(JSON.stringify({
+        const output = {
             results: results.map((r) => ({
                 skill: r.skill,
                 valid: r.valid,
@@ -96,12 +135,28 @@ export async function validateCommand(skill, opts) {
                 warnings: r.warnings,
                 infos: r.infos,
                 fixed: r.fixed ?? false,
+                ...(r.qualityScore !== undefined && { qualityScore: r.qualityScore, qualityRating: r.qualityRating }),
             })),
-        }, null, 2));
-        if (results.some((r) => !r.valid))
+        };
+        if (opts.cross && crossIssues.length > 0) {
+            output.crossValidation = crossIssues;
+        }
+        const scores = results.filter((r) => r.qualityScore !== undefined).map((r) => r.qualityScore);
+        if (scores.length > 0) {
+            output.summary = {
+                total: results.length,
+                passed: results.filter((r) => r.valid).length,
+                failed: results.filter((r) => !r.valid).length,
+                averageScore: Math.round(scores.reduce((a, b) => a + b, 0) / scores.length),
+                belowThreshold: opts.minScore ? results.filter((r) => (r.qualityScore ?? 0) < opts.minScore).length : 0,
+            };
+        }
+        console.log(JSON.stringify(output, null, 2));
+        if (hasErrors || hasCrossErrors)
             process.exit(1);
         return;
     }
+    // Human-readable output
     let passed = 0;
     let warned = 0;
     let failed = 0;
@@ -109,7 +164,8 @@ export async function validateCommand(skill, opts) {
     for (const r of results) {
         const icon = r.valid ? (r.warnings.length > 0 ? ui.warn("[!!]") : ui.success("[OK]")) : ui.error("[XX]");
         const fixTag = r.fixed ? ui.cyan(" [fixed]") : "";
-        console.log(`  ${icon} ${ui.bold(r.skill)}${fixTag}`);
+        const scoreTag = r.qualityScore !== undefined ? ui.dim(` (${r.qualityScore}/100 ${r.qualityRating})`) : "";
+        console.log(`  ${icon} ${ui.bold(r.skill)}${fixTag}${scoreTag}`);
         for (const err of r.errors) {
             console.log(ui.error(`    Error: ${err}`));
         }
@@ -131,6 +187,15 @@ export async function validateCommand(skill, opts) {
         if (r.fixed)
             fixed++;
     }
+    // Cross-validation output
+    if (opts.cross && crossIssues.length > 0) {
+        console.log();
+        console.log(ui.bold("  Cross-validation:"));
+        for (const issue of crossIssues) {
+            const icon = issue.level === "error" ? ui.error("[XX]") : ui.warn("[!!]");
+            console.log(`  ${icon} ${issue.skill}: ${issue.detail}`);
+        }
+    }
     console.log();
     const parts = [];
     if (passed > 0)
@@ -141,8 +206,10 @@ export async function validateCommand(skill, opts) {
         parts.push(ui.error(`${failed} failed`));
     if (fixed > 0)
         parts.push(ui.cyan(`${fixed} fixed`));
+    if (hasCrossErrors)
+        parts.push(ui.error(`${crossIssues.filter((i) => i.level === "error").length} cross-validation errors`));
     console.log(`  ${parts.join(ui.dim(" | "))}`);
     console.log();
-    if (failed > 0)
+    if (failed > 0 || hasCrossErrors)
         process.exit(1);
 }

package/dist/interactive/browse.js

@@ -48,7 +48,7 @@ export async function browseByCategory(allSkills, providerName) {
             };
         });
         const category = await p.select({
-            message: "Browse by category",
+            message: "Browse > Select category",
             options: [...categoryOptions, { value: "__back", label: "Back" }],
         });
         handleCancel(category);
@@ -85,7 +85,7 @@ async function categorySkillList(categoryName, skillNames, allSkills, providerNa
         }
         extraOptions.push({ value: "__back", label: "Back to categories" });
         const picked = await p.select({
-            message: `${categoryName} (${validSkills.length} skills)`,
+            message: `Browse > ${categoryName}`,
             options: [...options, ...extraOptions],
         });
         handleCancel(picked);

package/dist/interactive/health.js

@@ -3,40 +3,47 @@ import chalk from "chalk";
 import { runDoctorChecks } from "../commands/doctor.js";
 import { handleCancel } from "./helpers.js";
 export async function checkHealth() {
-    const checks = runDoctorChecks();
-    p.log.step(chalk.bold("Environment Health Check"));
-    for (const check of checks) {
-        const icon = check.status === "pass" ? chalk.green("OK") : check.status === "warn" ? chalk.yellow("!!") : chalk.red("XX");
-        p.log.info(`${icon}  ${chalk.bold(check.name)}: ${check.message}`);
-        if (check.fix)
-            p.log.info(chalk.dim(`    Fix: ${check.fix}`));
-    }
-    const fails = checks.filter((c) => c.status === "fail").length;
-    const warns = checks.filter((c) => c.status === "warn").length;
-    if (fails > 0) {
-        p.log.error(`${fails} issue${fails > 1 ? "s" : ""} found`);
-    }
-    else if (warns > 0) {
-        p.log.warn(`${warns} warning${warns > 1 ? "s" : ""}`);
-    }
-    else {
-        p.log.success("All checks passed");
-        return;
-    }
-    // Offer fixes once
-    const fixChecks = checks.filter((c) => c.fix && c.status !== "pass");
-    if (fixChecks.length === 0)
-        return;
-    const fixOptions = fixChecks.map((c) => {
-        const cmd = c.fix.replace(/^Run:\s*/, "");
-        return { value: cmd, label: `Run: ${cmd}`, hint: c.name };
-    });
-    const fixAction = await p.select({
-        message: "Run a fix?",
-        options: [...fixOptions, { value: "__skip", label: "Skip" }],
-    });
-    handleCancel(fixAction);
-    if (fixAction !== "__skip") {
+    while (true) {
+        const checks = runDoctorChecks();
+        p.log.step(chalk.bold("Environment Health Check"));
+        for (const check of checks) {
+            const icon = check.status === "pass" ? chalk.green("OK") : check.status === "warn" ? chalk.yellow("!!") : chalk.red("XX");
+            p.log.info(`${icon}  ${chalk.bold(check.name)}: ${check.message}`);
+            if (check.fix)
+                p.log.info(chalk.dim(`    Fix: ${check.fix}`));
+        }
+        const fails = checks.filter((c) => c.status === "fail").length;
+        const warns = checks.filter((c) => c.status === "warn").length;
+        if (fails > 0) {
+            p.log.error(`${fails} issue${fails > 1 ? "s" : ""} found`);
+        }
+        else if (warns > 0) {
+            p.log.warn(`${warns} warning${warns > 1 ? "s" : ""}`);
+        }
+        else {
+            p.log.success("All checks passed");
+            return;
+        }
+        const fixChecks = checks.filter((c) => c.fix && c.status !== "pass");
+        if (fixChecks.length === 0)
+            return;
+        const fixOptions = fixChecks.map((c) => {
+            const cmd = c.fix.replace(/^Run:\s*/, "");
+            return { value: cmd, label: `Run: ${cmd}`, hint: c.name };
+        });
+        const fixAction = await p.select({
+            message: "Run a fix?",
+            options: [
+                ...fixOptions,
+                { value: "__recheck", label: "Re-check now" },
+                { value: "__back", label: "Back to menu" },
+            ],
+        });
+        handleCancel(fixAction);
+        if (fixAction === "__back")
+            return;
+        if (fixAction === "__recheck")
+            continue;
         const cmd = fixAction;
         const SAFE_PREFIXES = ["arcana ", "git config "];
         if (!SAFE_PREFIXES.some((pre) => cmd.startsWith(pre))) {
@@ -52,6 +59,6 @@ export async function checkHealth() {
                 // Non-zero exit expected for some commands
             }
         }
-        p.log.info(chalk.dim("Run health check again to verify."));
+        // Loop continues, re-runs checks automatically
     }
 }

package/dist/interactive/helpers.d.ts

@@ -4,6 +4,20 @@ export declare function handleCancel(value: unknown): void;
 export declare function countInstalled(): number;
 export declare function truncate(str: string, max: number): string;
 export declare function getInstalledNames(): string[];
+export declare function getTokenEstimate(skillName: string): {
+    tokens: number;
+    kb: number;
+};
+export declare function getTotalTokenBudget(): {
+    totalKB: number;
+    totalTokens: number;
+    count: number;
+    skills: {
+        name: string;
+        tokens: number;
+        kb: number;
+    }[];
+};
 export declare function buildMenuOptions(installedCount: number, _availableCount: number): {
     value: string;
     label: string;

package/dist/interactive/helpers.js

@@ -2,7 +2,7 @@ import { existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import * as p from "@clack/prompts";
 import chalk from "chalk";
-import { getInstallDir } from "../utils/fs.js";
+import { getInstallDir, getSkillDir, getDirSize } from "../utils/fs.js";
 import { clearProviderCache } from "../registry.js";
 export const AMBER = chalk.hex("#d4943a");
 export function cancelAndExit() {
@@ -45,21 +45,48 @@ export function getInstalledNames() {
     })
         .sort();
 }
+export function getTokenEstimate(skillName) {
+    const dir = getSkillDir(skillName);
+    if (!existsSync(dir))
+        return { tokens: 0, kb: 0 };
+    const bytes = getDirSize(dir);
+    return { tokens: Math.round(bytes / 4), kb: Math.round(bytes / 1024) };
+}
+export function getTotalTokenBudget() {
+    const names = getInstalledNames();
+    const skills = names.map((name) => {
+        const est = getTokenEstimate(name);
+        return { name, tokens: est.tokens, kb: est.kb };
+    });
+    skills.sort((a, b) => b.tokens - a.tokens);
+    const totalKB = skills.reduce((sum, s) => sum + s.kb, 0);
+    const totalTokens = skills.reduce((sum, s) => sum + s.tokens, 0);
+    return { totalKB, totalTokens, count: names.length, skills };
+}
 export function buildMenuOptions(installedCount, _availableCount) {
     const isNew = installedCount === 0;
     const options = [];
     if (isNew) {
-        options.push({ value: "setup", label: AMBER("Get Started"), hint: "detect project, install recommended skills" });
+        options.push({
+            value: "setup",
+            label: AMBER("Get Started"),
+            hint: "detect project, install recommended skills",
+        });
     }
     else {
-        options.push({ value: "installed", label: "Manage installed skills", hint: `${installedCount} installed` });
+        options.push({
+            value: "installed",
+            label: "Your skills",
+            hint: `${installedCount} installed, manage & update`,
+        });
     }
-    options.push({ value: "browse", label: "Browse skills by category" });
-    options.push({ value: "search", label: "Search for a skill" });
+    options.push({ value: "browse", label: "Browse marketplace" });
+    options.push({ value: "search", label: "Search skills" });
     if (!isNew) {
         options.push({ value: "setup", label: "Get Started", hint: "detect project, add more skills" });
     }
-    options.push({ value: "health", label: "Check environment health" });
+    options.push({ value: "health", label: "Health check" });
+    options.push({ value: "optimize", label: "Token budget" });
     options.push({ value: "ref", label: "CLI reference" });
     options.push({ value: "exit", label: "Exit" });
     return options;

package/dist/interactive/manage.js

@@ -35,7 +35,7 @@ export async function manageInstalled(allSkills, providerName) {
             hint: `${g.skills.length} installed`,
         }));
         const picked = await p.select({
-            message: `Installed skills (${names.length})`,
+            message: `Your skills > Select category`,
             options: [
                 ...options,
                 { value: "__update", label: chalk.cyan("Check for updates") },
@@ -78,7 +78,7 @@ async function installedCategoryList(categoryName, installedNames, allSkills, pr
             };
         });
         const picked = await p.select({
-            message: `${categoryName} (${stillInstalled.length} installed)`,
+            message: `Your skills > ${categoryName}`,
             options: [...options, { value: "__back", label: "Back" }],
         });
         handleCancel(picked);
@@ -108,7 +108,7 @@ async function bulkUninstall(installedNames) {
         return;
     let removed = 0;
     for (const name of names) {
-        if (doUninstall(name))
+        if (doUninstall(name).success)
             removed++;
     }
     p.log.success(`Removed ${removed} skill${removed !== 1 ? "s" : ""}`);

package/dist/interactive/menu.js

@@ -11,6 +11,7 @@ import { searchFlow } from "./search.js";
 import { quickSetup } from "./setup.js";
 import { manageInstalled } from "./manage.js";
 import { checkHealth } from "./health.js";
+import { optimizeInteractive } from "./optimize-flow.js";
 export async function showInteractiveMenu(version) {
     const config = loadConfig();
     const providerName = config.defaultProvider;
@@ -93,6 +94,9 @@ export async function showInteractiveMenu(version) {
                 case "health":
                     await checkHealth();
                     break;
+                case "optimize":
+                    await optimizeInteractive();
+                    break;
                 case "ref":
                     p.note(getCliReference(), "CLI Reference");
                     break;

package/dist/interactive/optimize-flow.d.ts

@@ -0,0 +1 @@
+export declare function optimizeInteractive(): Promise<void>;

package/dist/interactive/optimize-flow.js

@@ -0,0 +1,36 @@
+import * as p from "@clack/prompts";
+import chalk from "chalk";
+import { getTotalTokenBudget, AMBER, handleCancel } from "./helpers.js";
+export async function optimizeInteractive() {
+    const budget = getTotalTokenBudget();
+    const barWidth = 30;
+    const maxTokens = 200_000;
+    const pct = Math.min(100, Math.round((budget.totalTokens / maxTokens) * 100));
+    const filled = Math.round((pct / 100) * barWidth);
+    const bar = AMBER("█".repeat(filled)) + chalk.dim("░".repeat(barWidth - filled));
+    const lines = [];
+    lines.push(`${bar}  ${pct}% of 200K context window`);
+    lines.push("");
+    lines.push(`${chalk.bold(String(budget.count))} skills installed, ${chalk.bold(String(budget.totalKB))} KB total (~${(budget.totalTokens / 1000).toFixed(0)}K tokens)`);
+    if (budget.skills.length > 0) {
+        lines.push("");
+        lines.push(chalk.dim("Largest skills:"));
+        for (const s of budget.skills.slice(0, 7)) {
+            const pctOfTotal = budget.totalTokens > 0 ? Math.round((s.tokens / budget.totalTokens) * 100) : 0;
+            lines.push(`  ${s.name.padEnd(32)} ${String(s.kb).padStart(4)} KB  ${String(pctOfTotal).padStart(3)}%`);
+        }
+    }
+    p.note(lines.join("\n"), "Token Budget");
+    const action = await p.select({
+        message: "What next?",
+        options: [
+            { value: "full", label: "Run full optimization report" },
+            { value: "__back", label: "Back" },
+        ],
+    });
+    handleCancel(action);
+    if (action === "full") {
+        const { optimizeCommand } = await import("../commands/optimize.js");
+        await optimizeCommand({ json: false });
+    }
+}

package/dist/interactive/search.js

@@ -51,7 +51,7 @@ async function searchResultsPicker(results, allSkills, providerName) {
             hint: truncate(skill.description, 50),
         }));
         const picked = await p.select({
-            message: "Pick a skill for details",
+            message: `Search > Results`,
             options: [...options, { value: "__search", label: "Search again" }, { value: "__back", label: "Back" }],
         });
         handleCancel(picked);

package/dist/interactive/skill-detail.d.ts

@@ -1,5 +1,8 @@
 import type { SkillInfo } from "../types.js";
 declare function doInstall(skillName: string, providerName: string): Promise<boolean>;
-declare function doUninstall(skillName: string): boolean;
+declare function doUninstall(skillName: string): {
+    success: boolean;
+    backupPath?: string;
+};
 export declare function skillDetailFlow(skillName: string, allSkills: SkillInfo[], providerName: string): Promise<"back" | "menu">;
 export { doInstall, doUninstall };

package/dist/interactive/skill-detail.js

@@ -1,12 +1,13 @@
 import { existsSync, rmSync } from "node:fs";
 import * as p from "@clack/prompts";
 import chalk from "chalk";
-import { isSkillInstalled, readSkillMeta, getSkillDir } from "../utils/fs.js";
-import { getProvider } from "../registry.js";
+import { isSkillInstalled, readSkillMeta, getSkillDir, getDirSize } from "../utils/fs.js";
 import { appendHistory } from "../utils/history.js";
 import { installOneCore } from "../utils/install-core.js";
+import { backupSkill } from "../utils/backup.js";
 import { removeSymlinksFor } from "../commands/uninstall.js";
 import { ui } from "../utils/ui.js";
+import { getProvider } from "../registry.js";
 import { handleCancel } from "./helpers.js";
 import { getCategoryFor, getRelatedSkills } from "./categories.js";
 async function doInstall(skillName, providerName) {
@@ -35,69 +36,93 @@ async function doInstall(skillName, providerName) {
 function doUninstall(skillName) {
     const skillDir = getSkillDir(skillName);
     if (!existsSync(skillDir))
-        return false;
+        return { success: false };
     try {
+        const backupPath = backupSkill(skillName);
         rmSync(skillDir, { recursive: true, force: true });
         removeSymlinksFor(skillName);
         appendHistory("uninstall", skillName);
-        return true;
+        return { success: true, backupPath: backupPath ?? undefined };
     }
     catch {
-        return false;
+        return { success: false };
     }
 }
+function getTokenEstimate(skillName) {
+    const dir = getSkillDir(skillName);
+    if (!existsSync(dir))
+        return { tokens: 0, kb: 0 };
+    const bytes = getDirSize(dir);
+    return { tokens: Math.round(bytes / 4), kb: Math.round(bytes / 1024) };
+}
 export async function skillDetailFlow(skillName, allSkills, providerName) {
     const info = allSkills.find((s) => s.name === skillName);
     const installed = isSkillInstalled(skillName);
     const meta = installed ? readSkillMeta(skillName) : null;
-    // Build info block
+    // Build info block with visual hierarchy
     const lines = [];
-    lines.push(`${chalk.bold(skillName)} ${info ? `v${info.version}` : ""}`);
+    // Header
+    lines.push(`${chalk.bold(skillName)} ${info ? chalk.dim(`v${info.version}`) : ""}`);
     if (info?.description)
-        lines.push(info.description);
+        lines.push(chalk.dim(info.description));
     lines.push("");
+    // Status (most important, shown first)
+    if (installed && meta) {
+        const date = meta.installedAt ? new Date(meta.installedAt).toLocaleDateString() : "";
+        const est = getTokenEstimate(skillName);
+        const tokenStr = est.tokens > 0 ? `  ~${(est.tokens / 1000).toFixed(1)}K tokens` : "";
+        lines.push(`${chalk.green("Installed")}  v${meta.version}${date ? `  ${date}` : ""}${tokenStr}`);
+    }
+    else {
+        lines.push(chalk.dim("Not installed"));
+    }
+    lines.push("");
+    // Aligned metadata
+    const metadata = [];
     if (info?.verified)
-        lines.push(`Trust: ${chalk.green("Verified")} (official)`);
+        metadata.push(["Trust", chalk.green("Verified (official)")]);
     else
-        lines.push(`Trust: Community`);
+        metadata.push(["Trust", "Community"]);
     if (info?.author)
-        lines.push(`Author: ${info.author}`);
+        metadata.push(["Author", info.author]);
     if (info?.tags && info.tags.length > 0)
-        lines.push(`Tags: ${info.tags.join(", ")}`);
+        metadata.push(["Tags", info.tags.join(", ")]);
     const category = getCategoryFor(skillName);
     if (category)
-        lines.push(`Category: ${category}`);
-    if (info?.source)
-        lines.push(`Source: ${info.source}`);
-    if (info?.companions && info.companions.length > 0) {
-        lines.push(`Companions: ${info.companions.join(", ")}`);
-    }
-    if (info?.conflicts && info.conflicts.length > 0) {
-        lines.push(`${chalk.red("Conflicts:")} ${info.conflicts.join(", ")}`);
-    }
-    if (installed && meta) {
-        const date = meta.installedAt ? new Date(meta.installedAt).toLocaleDateString() : "";
-        lines.push(`Status: ${chalk.green("installed")} (v${meta.version}${date ? `, ${date}` : ""})`);
-    }
-    else {
-        lines.push(`Status: ${chalk.dim("not installed")}`);
+        metadata.push(["Category", category]);
+    const maxLabel = Math.max(...metadata.map(([k]) => k.length));
+    for (const [key, val] of metadata) {
+        lines.push(`${chalk.dim(key.padEnd(maxLabel + 1))} ${val}`);
     }
+    // Relations
     const related = getRelatedSkills(skillName);
-    if (related.length > 0) {
-        lines.push(`Related: ${related.join(", ")}`);
+    const hasRelations = (info?.companions && info.companions.length > 0) ||
+        (info?.conflicts && info.conflicts.length > 0) ||
+        related.length > 0;
+    if (hasRelations) {
+        lines.push("");
+        if (info?.companions && info.companions.length > 0) {
+            lines.push(`${chalk.dim("Works with:")} ${info.companions.join(", ")}`);
+        }
+        if (info?.conflicts && info.conflicts.length > 0) {
+            lines.push(`${chalk.red("Conflicts:")}  ${info.conflicts.join(", ")}`);
+        }
+        if (related.length > 0) {
+            lines.push(`${chalk.dim("Related:")}    ${related.join(", ")}`);
+        }
     }
     p.note(lines.join("\n"), skillName);
     // Action menu
     const actions = [];
     if (installed) {
-        actions.push({ value: "reinstall", label: "Reinstall (overwrite)" });
-        actions.push({ value: "uninstall", label: "Uninstall (remove files)" });
+        actions.push({ value: "reinstall", label: "Update to latest" });
+        actions.push({ value: "uninstall", label: "Uninstall" });
     }
     else {
         actions.push({ value: "install", label: "Install this skill" });
     }
-    actions.push({ value: "back", label: "Back" });
-    const action = await p.select({ message: "Action", options: actions });
+    actions.push({ value: "__back", label: "Back" });
+    const action = await p.select({ message: `${skillName} > Action`, options: actions });
     handleCancel(action);
     switch (action) {
         case "install":
@@ -106,12 +131,21 @@ export async function skillDetailFlow(skillName, allSkills, providerName) {
             return "back";
         }
         case "uninstall": {
+            // Dry-run preview
+            const skillDir = getSkillDir(skillName);
+            const size = getDirSize(skillDir);
+            p.log.info(chalk.dim(`  Will remove: ${skillDir}`));
+            p.log.info(chalk.dim(`  Size: ${(size / 1024).toFixed(0)} KB (${meta?.fileCount ?? "?"} files)`));
+            p.log.info(chalk.dim(`  A backup will be created before removal.`));
             const ok = await p.confirm({ message: `Uninstall ${chalk.bold(skillName)}?` });
             handleCancel(ok);
             if (ok) {
-                const success = doUninstall(skillName);
-                if (success) {
+                const result = doUninstall(skillName);
+                if (result.success) {
                     p.log.success(`Removed ${chalk.bold(skillName)}`);
+                    if (result.backupPath) {
+                        p.log.info(chalk.dim(`  Backup: ${result.backupPath}`));
+                    }
                 }
                 else {
                     p.log.error(`Failed to remove ${skillName}`);

package/dist/utils/backup.d.ts

@@ -0,0 +1,3 @@
+export declare function getBackupDir(): string;
+export declare function backupSkill(skillName: string): string | null;
+export declare function pruneOldBackups(skillName: string): void;

package/dist/utils/backup.js

@@ -0,0 +1,32 @@
+import { existsSync, mkdirSync, cpSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { getSkillDir } from "./fs.js";
+const BACKUP_DIR = join(homedir(), ".arcana", "backups");
+const MAX_BACKUPS_PER_SKILL = 10;
+export function getBackupDir() {
+    return BACKUP_DIR;
+}
+export function backupSkill(skillName) {
+    const skillDir = getSkillDir(skillName);
+    if (!existsSync(skillDir))
+        return null;
+    mkdirSync(BACKUP_DIR, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const dest = join(BACKUP_DIR, `${skillName}_${timestamp}`);
+    cpSync(skillDir, dest, { recursive: true });
+    pruneOldBackups(skillName);
+    return dest;
+}
+export function pruneOldBackups(skillName) {
+    if (!existsSync(BACKUP_DIR))
+        return;
+    const prefix = `${skillName}_`;
+    const entries = readdirSync(BACKUP_DIR)
+        .filter((d) => d.startsWith(prefix))
+        .sort();
+    while (entries.length > MAX_BACKUPS_PER_SKILL) {
+        const oldest = entries.shift();
+        rmSync(join(BACKUP_DIR, oldest), { recursive: true, force: true });
+    }
+}

package/dist/utils/frontmatter.js

@@ -138,13 +138,16 @@ export function validateSkillDir(skillDir, skillName) {
         return result;
     }
     if (!parsed.description) {
-        result.warnings.push("Missing description in frontmatter");
+        result.valid = false;
+        result.errors.push("Missing description in frontmatter");
     }
     else if (parsed.description.length < MIN_DESC_LENGTH) {
-        result.warnings.push(`Description too short (${parsed.description.length} chars, recommend ${MIN_DESC_LENGTH}+)`);
+        result.valid = false;
+        result.errors.push(`Description too short (${parsed.description.length} chars, minimum ${MIN_DESC_LENGTH})`);
     }
     else if (parsed.description.length > MAX_DESC_LENGTH) {
-        result.warnings.push(`Description too long (${parsed.description.length} chars, max ${MAX_DESC_LENGTH})`);
+        result.valid = false;
+        result.errors.push(`Description too long (${parsed.description.length} chars, max ${MAX_DESC_LENGTH})`);
     }
     // Check for non-standard fields (metadata is invalid per spec)
     const standardFields = ["name", "description"];
@@ -181,11 +184,11 @@ export function validateSkillDir(skillDir, skillName) {
         result.warnings.push("SKILL.md body is very short (less than 50 chars)");
     }
     if (extracted.body.trim().length >= 50 && !extracted.body.includes("##")) {
-        result.infos.push("Body has no ## headings (recommended for structure)");
+        result.warnings.push("Body has no ## headings (required for structure)");
     }
     // Check for code blocks (quality signal)
     if (extracted.body.trim().length >= 50 && !extracted.body.includes("```")) {
-        result.infos.push("No code blocks found (procedural skills should include code examples)");
+        result.warnings.push("No code blocks found (skills must include code examples)");
     }
     // Check for BAD/GOOD pattern examples
     const hasPattern = /(?:BAD|GOOD|WRONG|RIGHT|AVOID|PREFER|DO NOT|INSTEAD)/i.test(extracted.body) ||

package/dist/utils/quality.d.ts

@@ -0,0 +1,27 @@
+import type { MarketplacePlugin } from "../types.js";
+export interface CrossValidationIssue {
+    level: "error" | "warning";
+    category: "marketplace-drift" | "orphan" | "companion" | "duplicate-desc";
+    skill: string;
+    detail: string;
+}
+/**
+ * Jaccard word-level similarity between two strings.
+ * Returns 0.0 (completely different) to 1.0 (identical).
+ */
+export declare function jaccardSimilarity(a: string, b: string): number;
+/**
+ * Validate companion references in marketplace plugins.
+ * Every companion must reference an existing plugin name.
+ */
+export declare function validateCompanions(plugins: MarketplacePlugin[]): CrossValidationIssue[];
+/**
+ * Check description sync between SKILL.md frontmatter and marketplace.json.
+ * Returns an issue if similarity is below 0.5.
+ */
+export declare function validateDescriptionSync(skillName: string, frontmatterDesc: string, marketplaceDesc: string): CrossValidationIssue | null;
+/**
+ * Cross-validate skill directories against marketplace.json.
+ * Checks: orphans, companions, description drift, near-duplicates.
+ */
+export declare function crossValidate(skillsDir: string, marketplacePath: string): CrossValidationIssue[];

package/dist/utils/quality.js

@@ -0,0 +1,174 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { extractFrontmatter, parseFrontmatter } from "./frontmatter.js";
+/**
+ * Jaccard word-level similarity between two strings.
+ * Returns 0.0 (completely different) to 1.0 (identical).
+ */
+export function jaccardSimilarity(a, b) {
+    const wordsA = new Set(a.toLowerCase().split(/\s+/).filter(Boolean));
+    const wordsB = new Set(b.toLowerCase().split(/\s+/).filter(Boolean));
+    if (wordsA.size === 0 && wordsB.size === 0)
+        return 1.0;
+    if (wordsA.size === 0 || wordsB.size === 0)
+        return 0.0;
+    let intersection = 0;
+    for (const w of wordsA) {
+        if (wordsB.has(w))
+            intersection++;
+    }
+    const union = wordsA.size + wordsB.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+/**
+ * Validate companion references in marketplace plugins.
+ * Every companion must reference an existing plugin name.
+ */
+export function validateCompanions(plugins) {
+    const issues = [];
+    const names = new Set(plugins.map((p) => p.name));
+    for (const plugin of plugins) {
+        if (!plugin.companions)
+            continue;
+        for (const companion of plugin.companions) {
+            if (!names.has(companion)) {
+                issues.push({
+                    level: "error",
+                    category: "companion",
+                    skill: plugin.name,
+                    detail: `Companion "${companion}" does not exist in marketplace`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Check description sync between SKILL.md frontmatter and marketplace.json.
+ * Returns an issue if similarity is below 0.5.
+ */
+export function validateDescriptionSync(skillName, frontmatterDesc, marketplaceDesc) {
+    if (!frontmatterDesc || !marketplaceDesc)
+        return null;
+    const similarity = jaccardSimilarity(frontmatterDesc, marketplaceDesc);
+    if (similarity < 0.5) {
+        return {
+            level: "warning",
+            category: "marketplace-drift",
+            skill: skillName,
+            detail: `Description drift (${Math.round(similarity * 100)}% similarity) between SKILL.md and marketplace.json`,
+        };
+    }
+    return null;
+}
+/**
+ * Cross-validate skill directories against marketplace.json.
+ * Checks: orphans, companions, description drift, near-duplicates.
+ */
+export function crossValidate(skillsDir, marketplacePath) {
+    const issues = [];
+    // Load marketplace
+    let marketplace;
+    try {
+        marketplace = JSON.parse(readFileSync(marketplacePath, "utf-8"));
+    }
+    catch {
+        issues.push({
+            level: "error",
+            category: "orphan",
+            skill: "marketplace.json",
+            detail: "Cannot read or parse marketplace.json",
+        });
+        return issues;
+    }
+    const pluginNames = new Set(marketplace.plugins.map((p) => p.name));
+    const pluginMap = new Map(marketplace.plugins.map((p) => [p.name, p]));
+    // Get skill directories
+    let skillDirs;
+    try {
+        skillDirs = readdirSync(skillsDir).filter((d) => {
+            try {
+                return statSync(join(skillsDir, d)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        issues.push({
+            level: "error",
+            category: "orphan",
+            skill: "skills/",
+            detail: "Cannot read skills directory",
+        });
+        return issues;
+    }
+    const dirNames = new Set(skillDirs);
+    // 1. Orphan directories (dir exists, no marketplace entry)
+    for (const dir of skillDirs) {
+        if (!pluginNames.has(dir)) {
+            issues.push({
+                level: "error",
+                category: "orphan",
+                skill: dir,
+                detail: "Skill directory exists but no marketplace.json entry",
+            });
+        }
+    }
+    // 2. Orphan entries (marketplace entry, no dir)
+    for (const name of pluginNames) {
+        if (!dirNames.has(name)) {
+            issues.push({
+                level: "error",
+                category: "orphan",
+                skill: name,
+                detail: "Marketplace entry exists but no skill directory",
+            });
+        }
+    }
+    // 3. Companion validation
+    issues.push(...validateCompanions(marketplace.plugins));
+    // 4. Description drift (SKILL.md frontmatter vs marketplace.json)
+    for (const dir of skillDirs) {
+        const plugin = pluginMap.get(dir);
+        if (!plugin)
+            continue;
+        const skillMd = join(skillsDir, dir, "SKILL.md");
+        if (!existsSync(skillMd))
+            continue;
+        try {
+            const content = readFileSync(skillMd, "utf-8");
+            const extracted = extractFrontmatter(content);
+            if (!extracted)
+                continue;
+            const parsed = parseFrontmatter(extracted.raw);
+            if (!parsed?.description)
+                continue;
+            const driftIssue = validateDescriptionSync(dir, parsed.description, plugin.description);
+            if (driftIssue)
+                issues.push(driftIssue);
+        }
+        catch {
+            /* skip unreadable */
+        }
+    }
+    // 5. Near-duplicate descriptions across skills
+    const descriptions = marketplace.plugins.map((p) => ({ name: p.name, desc: p.description }));
+    for (let i = 0; i < descriptions.length; i++) {
+        for (let j = i + 1; j < descriptions.length; j++) {
+            const a = descriptions[i];
+            const b = descriptions[j];
+            const sim = jaccardSimilarity(a.desc, b.desc);
+            if (sim > 0.85) {
+                issues.push({
+                    level: "warning",
+                    category: "duplicate-desc",
+                    skill: a.name,
+                    detail: `Near-duplicate description with ${b.name} (${Math.round(sim * 100)}% similarity)`,
+                });
+            }
+        }
+    }
+    return issues;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sporesec/arcana",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Universal AI development CLI. Skills, scaffolding, diagnostics, and analytics for every agent.",
   "bin": {
     "arcana": "dist/index.js"