agents-inc 0.152.1 → 0.153.0

package/dist/commands/doctor.js

@@ -2,58 +2,591 @@
 import {
   detectProject,
   loadSource
-} from "../chunk-STMHDOZD.js";
-import "../chunk-SBHBBZKF.js";
-import "../chunk-IHUY4M22.js";
-import "../chunk-QZZJFYUQ.js";
+} from "../chunk-F7Z5I6GU.js";
+import "../chunk-REKOWTIB.js";
+import "../chunk-NXGMM5YN.js";
+import "../chunk-FRWKCE6R.js";
 import {
   filterExcludedEntries,
   listAgentMdFiles
-} from "../chunk-E5X6RJ4E.js";
+} from "../chunk-FIHTAFST.js";
 import {
   BaseCommand,
   EXIT_CODES
-} from "../chunk-KR65TPKC.js";
-import "../chunk-ZL7PFNHN.js";
+} from "../chunk-X5XJ6WKO.js";
+import "../chunk-TY6CAOL7.js";
+import "../chunk-K3O3YQYG.js";
 import {
+  checkMatrixHealth,
+  configDirsInPlay,
+  declaresNoContent,
   discoverLocalSkills,
   effectivelyExcludedSkillIds,
+  findConfigLoadFailures,
+  getInstalledPluginsRegistryPath,
+  getProjectConfigPath,
+  getProjectPluginsDir,
   getStackSkillIds,
+  getUserPluginsDir,
   getVerifiedPluginInstallPaths,
   installBaseDir,
   isHomeDirectory,
+  isLocalSource,
+  isRecord,
+  listRegisteredPluginInstalls,
+  loadConfig,
+  loadProjectConfigFromDir,
+  loadProjectSourceConfig,
+  loadSkillsMatrixFromSource,
   parseMarketplacePluginRef,
   resolveInstallPaths,
-  validateProjectConfig
-} from "../chunk-EEPELKOM.js";
+  resolvePrimarySourceEntry,
+  validateAgentFrontmatter,
+  validateAllPlugins,
+  validatePlugin,
+  validateProjectConfig,
+  validateSkillFrontmatter
+} from "../chunk-NXQAY5U7.js";
 import {
+  agentYamlGenerationSchema,
   directoryExists,
   fileExists,
+  formatZodErrors,
   getErrorMessage,
-  setVerbose
-} from "../chunk-PMM2MYMA.js";
+  glob,
+  listDirectories,
+  metadataValidationSchema,
+  parseFrontmatter,
+  readFile,
+  readSkillMetadata,
+  setVerbose,
+  skillCategoriesFileSchema,
+  skillRulesFileSchema,
+  splitMetadataValidationIssues,
+  stackConfigValidationSchema,
+  stacksConfigSchema,
+  validateSkillMetadata
+} from "../chunk-U2YSGBHA.js";
 import {
   matrix
-} from "../chunk-WKTHWQKM.js";
+} from "../chunk-35VOK7XE.js";
 import "../chunk-VASLW636.js";
 import {
   CLAUDE_SRC_DIR,
   CLI_INVOKE_COMMAND,
   DEFAULT_BRANDING,
+  DIRS,
   EJECT_SOURCE,
   LOCAL_SKILLS_PATH,
+  PLUGIN_MANIFEST_DIR,
+  SKILLS_DIR_PATH,
+  SKILL_CATEGORIES_PATH,
+  SKILL_RULES_PATH,
+  STACKS_FILE_PATH,
   STANDARD_FILES,
   UI_SYMBOLS
-} from "../chunk-76ADG7LQ.js";
-import "../chunk-UBEDZ4FD.js";
+} from "../chunk-R54KIGN2.js";
+import "../chunk-VZRO7RYT.js";
 
 // src/cli/commands/doctor.ts
-import os from "os";
+import os2 from "os";
+import path3 from "path";
+
+// src/cli/lib/source-validator.ts
 import path from "path";
+import { parse as parseYaml } from "yaml";
+import "zod";
+async function isSourceRepo(dir) {
+  const sourceConfig = await loadProjectSourceConfig(dir);
+  return directoryExists(path.join(dir, sourceConfig?.skillsDir ?? SKILLS_DIR_PATH));
+}
+function isSnakeCase(key) {
+  return /[a-z]_[a-z]/.test(key);
+}
+function checkSnakeCaseKeys(rawMetadata, relPath) {
+  if (!isRecord(rawMetadata)) return [];
+  return Object.keys(rawMetadata).filter(isSnakeCase).map((key) => ({
+    severity: "error",
+    file: relPath,
+    message: `Key '${key}' uses snake_case \u2014 use camelCase instead`
+  }));
+}
+function checkDirNameMatchesSkillId(skillId, relPath, dirName) {
+  if (skillId === dirName) return [];
+  return [
+    {
+      severity: "warning",
+      file: relPath,
+      message: `Directory name '${dirName}' does not match skill id '${skillId}'`
+    }
+  ];
+}
+async function checkSkillDirName(skillsDir, skillsDirRelPath, skillDir) {
+  const dirName = path.basename(skillDir);
+  const skillMdRelPath = path.join(skillsDirRelPath, skillDir, STANDARD_FILES.SKILL_MD);
+  try {
+    const content = await readFile(path.join(skillsDir, skillDir, STANDARD_FILES.SKILL_MD));
+    const frontmatter = parseFrontmatter(content, skillMdRelPath);
+    if (frontmatter === null) {
+      return [
+        {
+          severity: "warning",
+          file: skillMdRelPath,
+          message: `Cannot verify directory name '${dirName}': missing or invalid ${STANDARD_FILES.SKILL_MD} frontmatter`
+        }
+      ];
+    }
+    return checkDirNameMatchesSkillId(frontmatter.name, skillMdRelPath, dirName);
+  } catch (error) {
+    return [
+      {
+        severity: "warning",
+        file: skillMdRelPath,
+        message: `Cannot verify directory name '${dirName}': ${getErrorMessage(error)}`
+      }
+    ];
+  }
+}
+function validateSkillFilePairs(skillMdDirs, metadataDirs, skillsDir) {
+  const missingMetadata = [...skillMdDirs].filter((dir) => !metadataDirs.has(dir)).map((dir) => ({
+    severity: "error",
+    file: path.join(skillsDir, dir),
+    message: `Missing ${STANDARD_FILES.METADATA_YAML} \u2014 skill directory has ${STANDARD_FILES.SKILL_MD} but no metadata`
+  }));
+  const missingSkillMd = [...metadataDirs].filter((dir) => !skillMdDirs.has(dir)).map((dir) => ({
+    severity: "error",
+    file: path.join(skillsDir, dir),
+    message: `Missing ${STANDARD_FILES.SKILL_MD} \u2014 skill directory has ${STANDARD_FILES.METADATA_YAML} but no SKILL.md`
+  }));
+  return [...missingMetadata, ...missingSkillMd];
+}
+async function validateSource(sourcePath) {
+  const issues = [];
+  const resolvedPath = path.isAbsolute(sourcePath) ? sourcePath : path.resolve(sourcePath);
+  if (!await directoryExists(resolvedPath)) {
+    issues.push({
+      severity: "error",
+      file: resolvedPath,
+      message: "Source directory does not exist"
+    });
+    return buildResult(issues, 0);
+  }
+  const sourceProjectConfig = await loadProjectSourceConfig(resolvedPath);
+  const skillsDirRelPath = sourceProjectConfig?.skillsDir ?? SKILLS_DIR_PATH;
+  const skillsDir = path.join(resolvedPath, skillsDirRelPath);
+  if (!await directoryExists(skillsDir)) {
+    issues.push({
+      severity: "error",
+      file: skillsDir,
+      message: "Skills directory does not exist"
+    });
+    return buildResult(issues, 0);
+  }
+  const skillMdFiles = await glob(`**/${STANDARD_FILES.SKILL_MD}`, skillsDir);
+  const metadataFiles = await glob(`**/${STANDARD_FILES.METADATA_YAML}`, skillsDir);
+  const skillMdDirs = new Set(skillMdFiles.map((f) => path.dirname(f)));
+  const metadataDirs = new Set(metadataFiles.map((f) => path.dirname(f)));
+  issues.push(...validateSkillFilePairs(skillMdDirs, metadataDirs, skillsDir));
+  const validMetadataFiles = metadataFiles.filter((f) => skillMdDirs.has(path.dirname(f)));
+  for (const metadataFile of validMetadataFiles) {
+    issues.push(...await validateOneSkill(skillsDir, skillsDirRelPath, metadataFile));
+  }
+  issues.push(...await checkCrossReferences(resolvedPath));
+  const extraIssues = await Promise.all([
+    validateStacks(resolvedPath),
+    validateAgents(resolvedPath),
+    validateConfigFiles(resolvedPath)
+  ]);
+  issues.push(...extraIssues.flat());
+  return buildResult(issues, validMetadataFiles.length);
+}
+async function validateOneSkill(skillsDir, skillsDirRelPath, metadataFile) {
+  const relPath = path.join(skillsDirRelPath, metadataFile);
+  let rawMetadata;
+  try {
+    rawMetadata = parseYaml(await readFile(path.join(skillsDir, metadataFile)));
+  } catch (error) {
+    return [
+      {
+        severity: "error",
+        file: relPath,
+        message: `Failed to parse YAML: ${getErrorMessage(error)}`
+      }
+    ];
+  }
+  return [
+    ...checkSnakeCaseKeys(rawMetadata, relPath),
+    ...checkMetadataSchema(rawMetadata, relPath),
+    // Independent of metadata validity — the id lives in SKILL.md frontmatter
+    ...await checkSkillDirName(skillsDir, skillsDirRelPath, path.dirname(metadataFile))
+  ];
+}
+function checkMetadataSchema(rawMetadata, relPath) {
+  const result = validateSkillMetadata(rawMetadata);
+  if (result.success) return [];
+  const { errors, warnings } = splitMetadataValidationIssues(result.error, rawMetadata);
+  return [
+    ...errors.map((message) => ({ severity: "error", file: relPath, message })),
+    ...warnings.map((message) => ({ severity: "warning", file: relPath, message }))
+  ];
+}
+async function checkCrossReferences(resolvedPath) {
+  try {
+    await loadSkillsMatrixFromSource({ sourceFlag: resolvedPath, skipExtraSources: true });
+    return checkMatrixHealth(matrix).map((healthIssue) => ({
+      severity: healthIssue.severity,
+      file: SKILL_CATEGORIES_PATH,
+      message: healthIssue.details
+    }));
+  } catch (error) {
+    return [
+      {
+        severity: "warning",
+        file: SKILL_CATEGORIES_PATH,
+        message: `Cross-reference validation skipped: failed to load categories/rules: ${getErrorMessage(error)}`
+      }
+    ];
+  }
+}
+async function validateStacks(resolvedPath) {
+  const stacksDir = path.join(resolvedPath, DIRS.stacks);
+  if (!await directoryExists(stacksDir)) return [];
+  const [skillMetaIssues, configIssues] = await Promise.all([
+    validateYamlFiles({
+      baseDir: stacksDir,
+      relBaseDir: DIRS.stacks,
+      pattern: `**/skills/**/${STANDARD_FILES.METADATA_YAML}`,
+      schema: metadataValidationSchema
+    }),
+    validateYamlFiles({
+      baseDir: stacksDir,
+      relBaseDir: DIRS.stacks,
+      pattern: `*/${STANDARD_FILES.CONFIG_YAML}`,
+      schema: stackConfigValidationSchema
+    })
+  ]);
+  return [...skillMetaIssues, ...configIssues];
+}
+async function validateAgents(resolvedPath) {
+  const agentsDir = path.join(resolvedPath, DIRS.agents);
+  if (!await directoryExists(agentsDir)) return [];
+  return validateYamlFiles({
+    baseDir: agentsDir,
+    relBaseDir: DIRS.agents,
+    pattern: `**/${STANDARD_FILES.AGENT_METADATA_YAML}`,
+    schema: agentYamlGenerationSchema
+  });
+}
+async function validateConfigFiles(resolvedPath) {
+  const results = await Promise.all([
+    validateTsConfig(resolvedPath, SKILL_CATEGORIES_PATH, skillCategoriesFileSchema),
+    validateTsConfig(resolvedPath, SKILL_RULES_PATH, skillRulesFileSchema),
+    validateTsConfig(resolvedPath, STACKS_FILE_PATH, stacksConfigSchema)
+  ]);
+  return results.flat();
+}
+async function validateYamlFiles(opts) {
+  const issues = [];
+  const files = await glob(opts.pattern, opts.baseDir);
+  for (const relFile of files) {
+    const absPath = path.join(opts.baseDir, relFile);
+    const displayPath = path.join(opts.relBaseDir, relFile);
+    let parsed;
+    try {
+      parsed = parseYaml(await readFile(absPath));
+    } catch {
+      issues.push({ severity: "error", file: displayPath, message: "Failed to parse YAML" });
+      continue;
+    }
+    const result = opts.schema.safeParse(parsed);
+    if (result.success) continue;
+    issues.push(
+      ...formatZodErrors(result.error).map((message) => ({
+        severity: "error",
+        file: displayPath,
+        message
+      }))
+    );
+  }
+  return issues;
+}
+async function validateTsConfig(resolvedPath, relConfigPath, schema) {
+  const absPath = path.join(resolvedPath, relConfigPath);
+  if (!await fileExists(absPath)) return [];
+  try {
+    const loaded = await loadConfig(absPath, schema);
+    if (loaded === null) {
+      return [{ severity: "error", file: relConfigPath, message: "Config has no default export" }];
+    }
+    return [];
+  } catch (error) {
+    return [
+      { severity: "error", file: relConfigPath, message: formatLoadError(relConfigPath, error) }
+    ];
+  }
+}
+function formatLoadError(relConfigPath, error) {
+  const raw = getErrorMessage(error);
+  const stripped = raw.replace(/Failed to load config from '[^']+':\s*/, "");
+  return `Failed to load ${relConfigPath}: ${stripped}`;
+}
+function buildResult(issues, skillCount) {
+  const errorCount = issues.filter((i) => i.severity === "error").length;
+  const warningCount = issues.filter((i) => i.severity === "warning").length;
+  return { issues, skillCount, errorCount, warningCount };
+}
+
+// src/cli/lib/content-validator.ts
+import os from "os";
+import path2 from "path";
+var CWD_SOURCE_NAME = "current directory";
+var NOTHING_VALIDATED = { count: 0, issues: [], notes: [] };
+function mergeValidations(parts) {
+  return parts.reduce(
+    (acc, part) => ({
+      count: acc.count + part.count,
+      issues: [...acc.issues, ...part.issues],
+      notes: [...acc.notes, ...part.notes]
+    }),
+    NOTHING_VALIDATED
+  );
+}
+function displayDir(absolutePath) {
+  const home = os.homedir();
+  if (absolutePath === home) return "~";
+  if (absolutePath.startsWith(home + path2.sep)) {
+    return `~${path2.sep}${path2.relative(home, absolutePath)}`;
+  }
+  return absolutePath;
+}
+function toIssues(file, result) {
+  return [
+    ...result.errors.map((message) => ({ severity: "error", file, message })),
+    ...result.warnings.map((message) => ({ severity: "warning", file, message }))
+  ];
+}
+var CONFIG_UNREADABLE = "exists but could not be loaded";
+async function validateProjectConfigFile(projectDir) {
+  const [present, failures] = await Promise.all([
+    countExistingConfigs(projectDir),
+    findConfigLoadFailures(projectDir)
+  ]);
+  return { count: present, issues: failures.map(toUnreadableConfigIssue), notes: [] };
+}
+function toUnreadableConfigIssue(failure) {
+  return {
+    severity: "error",
+    file: displayDir(failure.configPath),
+    message: `${CONFIG_UNREADABLE}: ${failure.reason}`
+  };
+}
+async function countExistingConfigs(projectDir) {
+  const present = await Promise.all(
+    configDirsInPlay(projectDir).map((dir) => fileExists(getProjectConfigPath(dir)))
+  );
+  return present.filter(Boolean).length;
+}
+async function validateRegisteredSources(projectDir) {
+  const primary = await resolvePrimarySourceEntry(projectDir);
+  const registered = [primary];
+  const remote = registered.filter((source) => !isLocalSource(source.url));
+  const local = await localSourcesToValidate(projectDir, registered);
+  const outcomes = await Promise.all(local.map(validateOneSource));
+  return {
+    count: local.length,
+    issues: outcomes.flatMap((outcome) => outcome.issues),
+    notes: [
+      ...outcomes.map((outcome) => outcome.note),
+      ...remote.map((source) => `${source.name} (${source.url}) \u2014 skipped (remote source)`)
+    ]
+  };
+}
+async function localSourcesToValidate(projectDir, registered) {
+  const local = registered.filter((source) => isLocalSource(source.url));
+  const alreadyCovered = local.some(
+    (source) => path2.resolve(projectDir, source.url) === projectDir
+  );
+  if (alreadyCovered || !await isSourceRepo(projectDir)) return local;
+  return [...local, { name: CWD_SOURCE_NAME, url: projectDir }];
+}
+async function validateOneSource(source) {
+  const label = `${source.name} (${source.url})`;
+  try {
+    const result = await validateSource(source.url);
+    return { note: `${label} \u2014 ${result.skillCount} skills`, issues: result.issues };
+  } catch (error) {
+    return {
+      note: `${label} \u2014 failed`,
+      issues: [{ severity: "error", file: source.url, message: getErrorMessage(error) }]
+    };
+  }
+}
+async function validateInstalledPlugins(projectDir) {
+  const dirs = [
+    getUserPluginsDir(),
+    ...isHomeDirectory(projectDir) ? [] : [getProjectPluginsDir(projectDir)]
+  ];
+  return mergeValidations(await Promise.all(dirs.map(validatePluginsDirectory)));
+}
+async function validatePluginsDirectory(pluginsDir) {
+  if (!await directoryExists(pluginsDir)) return NOTHING_VALIDATED;
+  if (await fileExists(getInstalledPluginsRegistryPath(pluginsDir))) {
+    const registryValidation = await validateRegistryPlugins(pluginsDir);
+    if (registryValidation !== void 0) return registryValidation;
+  }
+  const pluginDirs = await findPluginDirectories(pluginsDir);
+  if (pluginDirs.length === 0) return NOTHING_VALIDATED;
+  const { results } = await validateAllPlugins(pluginsDir);
+  return {
+    count: results.length,
+    issues: results.flatMap(({ name, result }) => toIssues(name, result)),
+    notes: []
+  };
+}
+async function validateRegistryPlugins(pluginsDir) {
+  let installs;
+  try {
+    installs = await listRegisteredPluginInstalls(pluginsDir);
+  } catch (error) {
+    return {
+      count: 0,
+      issues: [
+        {
+          severity: "error",
+          file: displayDir(getInstalledPluginsRegistryPath(pluginsDir)),
+          message: getErrorMessage(error)
+        }
+      ],
+      notes: []
+    };
+  }
+  if (installs.length === 0) return void 0;
+  const results = await Promise.all(
+    installs.map(
+      async ({ pluginKey, installPath }) => toIssues(pluginKey, await validatePlugin(installPath))
+    )
+  );
+  return { count: installs.length, issues: results.flat(), notes: [] };
+}
+async function findPluginDirectories(pluginsDir) {
+  const entries = await listDirectories(pluginsDir);
+  const checks = await Promise.all(
+    entries.map(async (name) => ({
+      name,
+      isPlugin: await directoryExists(path2.join(pluginsDir, name, PLUGIN_MANIFEST_DIR))
+    }))
+  );
+  return checks.filter((check) => check.isPlugin).map((check) => check.name);
+}
+async function validateInstalledSkills(projectDir) {
+  return mergeValidations(
+    await Promise.all(installedDirs(projectDir, "skillsDir").map(validateSkillsDirectory))
+  );
+}
+async function validateInstalledAgents(projectDir) {
+  return mergeValidations(
+    await Promise.all(installedDirs(projectDir, "agentsDir").map(validateAgentsDirectory))
+  );
+}
+function installedDirs(projectDir, key) {
+  const global = resolveInstallPaths(projectDir, "global")[key];
+  if (isHomeDirectory(projectDir)) return [global];
+  return [global, resolveInstallPaths(projectDir, "project")[key]];
+}
+async function listInstalledArtifacts(projectDir) {
+  const [skills, agents] = await Promise.all([
+    listAcrossScopes(installedDirs(projectDir, "skillsDir"), listDirectories),
+    listAcrossScopes(installedDirs(projectDir, "agentsDir"), listAgentMdFiles)
+  ]);
+  return { skills, agents };
+}
+async function listAcrossScopes(dirs, listEntries) {
+  const perDir = await Promise.all(dirs.map((dir) => listDisplayPaths(dir, listEntries)));
+  return perDir.flat();
+}
+async function listDisplayPaths(dir, listEntries) {
+  if (!await directoryExists(dir)) return [];
+  const entries = await listEntries(dir);
+  return entries.map((entry) => displayDir(path2.join(dir, entry)));
+}
+async function validateSkillsDirectory(skillsDir) {
+  if (!await directoryExists(skillsDir)) return NOTHING_VALIDATED;
+  const skillDirs = await listDirectories(skillsDir);
+  if (skillDirs.length === 0) return NOTHING_VALIDATED;
+  const results = await Promise.all(
+    skillDirs.map(async (name) => {
+      const skillDir = path2.join(skillsDir, name);
+      return toIssues(displayDir(skillDir), await validateInstalledSkill(skillDir));
+    })
+  );
+  return { count: skillDirs.length, issues: results.flat(), notes: [] };
+}
+async function validateAgentsDirectory(agentsDir) {
+  if (!await directoryExists(agentsDir)) return NOTHING_VALIDATED;
+  const agentFiles = await listAgentMdFiles(agentsDir);
+  if (agentFiles.length === 0) return NOTHING_VALIDATED;
+  const results = await Promise.all(
+    agentFiles.map(async (fileName) => {
+      const agentPath = path2.join(agentsDir, fileName);
+      return toIssues(displayDir(agentPath), await validateAgentFrontmatter(agentPath));
+    })
+  );
+  return { count: agentFiles.length, issues: results.flat(), notes: [] };
+}
+async function validateInstalledSkill(skillDir) {
+  const skillMdPath = path2.join(skillDir, STANDARD_FILES.SKILL_MD);
+  const metadataPath = path2.join(skillDir, STANDARD_FILES.METADATA_YAML);
+  const errors = [];
+  const warnings = [];
+  if (!await fileExists(skillMdPath)) {
+    errors.push(`Missing ${STANDARD_FILES.SKILL_MD}`);
+  } else {
+    const frontmatterResult = await validateSkillFrontmatter(skillMdPath);
+    errors.push(...frontmatterResult.errors);
+    warnings.push(...frontmatterResult.warnings);
+  }
+  if (!await fileExists(metadataPath)) {
+    errors.push(`Missing ${STANDARD_FILES.METADATA_YAML}`);
+  } else {
+    const metadataResult = await validateInstalledSkillMetadata(metadataPath);
+    errors.push(...metadataResult.errors);
+    warnings.push(...metadataResult.warnings);
+  }
+  return { valid: errors.length === 0, errors, warnings };
+}
+async function validateInstalledSkillMetadata(metadataPath) {
+  const read = await readSkillMetadata(metadataPath);
+  if (!read.usable) {
+    return {
+      valid: false,
+      errors: [`${STANDARD_FILES.METADATA_YAML}: ${read.reason}`],
+      warnings: []
+    };
+  }
+  const metadata = read.metadata;
+  const result = validateSkillMetadata(metadata);
+  if (result.success) {
+    return { valid: true, errors: [], warnings: [] };
+  }
+  const { errors, warnings } = splitMetadataValidationIssues(result.error, metadata);
+  return {
+    valid: errors.length === 0,
+    errors: errors.map((e) => `${STANDARD_FILES.METADATA_YAML}: ${e}`),
+    warnings: warnings.map((w) => `${STANDARD_FILES.METADATA_YAML}: ${w}`)
+  };
+}
+
+// src/cli/commands/doctor.ts
 import { countBy, unique } from "remeda";
 var CONFIG_TS_REL = `${CLAUDE_SRC_DIR}/${STANDARD_FILES.CONFIG_TS}`;
-function checkConfigValid(config) {
-  if (!config) {
+async function resolveConfigState(detected, projectDir) {
+  if (detected?.config) return { kind: "loaded", config: detected.config };
+  const loaded = await loadProjectConfigFromDir(projectDir);
+  if (!loaded) return { kind: "absent" };
+  return declaresNoContent(loaded.config) ? { kind: "declares-nothing", config: loaded.config } : { kind: "loaded", config: loaded.config };
+}
+function checkConfigValid(state) {
+  if (state.kind === "absent") {
     return {
       result: {
         kind: "config",
@@ -64,6 +597,17 @@ function checkConfigValid(config) {
       config: null
     };
   }
+  if (state.kind === "declares-nothing") {
+    return {
+      result: {
+        kind: "config-empty",
+        status: "warn",
+        message: `${CONFIG_TS_REL} is valid but declares no skills and no agents`
+      },
+      config: state.config
+    };
+  }
+  const { config } = state;
   const validation = validateProjectConfig(config);
   if (!validation.valid) {
     return {
@@ -111,20 +655,15 @@ async function checkSkillsResolved(config, matrix2, projectDir) {
   }
   const [localResult, globalResult] = await Promise.all([
     discoverLocalSkills(projectDir),
-    !isHomeDirectory(projectDir) ? discoverLocalSkills(os.homedir()) : null
+    !isHomeDirectory(projectDir) ? discoverLocalSkills(os2.homedir()) : null
   ]);
   const localSkillIds = /* @__PURE__ */ new Set([
     ...localResult?.skills.map((s) => s.id) ?? [],
     ...globalResult?.skills.map((s) => s.id) ?? []
   ]);
-  const missingSkills = [];
-  for (const skillId of uniqueSkills) {
-    const inMatrix = skillId in matrix2.skills;
-    const inLocal = localSkillIds.has(skillId);
-    if (!inMatrix && !inLocal) {
-      missingSkills.push(skillId);
-    }
-  }
+  const missingSkills = uniqueSkills.filter(
+    (skillId) => !(skillId in matrix2.skills) && !localSkillIds.has(skillId)
+  );
   if (missingSkills.length > 0) {
     return {
       kind: "skills",
@@ -140,7 +679,7 @@ async function checkSkillsResolved(config, matrix2, projectDir) {
   };
 }
 async function checkAgentsCompiled(config, projectDir) {
-  const agents = config.agents ?? [];
+  const agents = config.agents;
   if (agents.length === 0) {
     return {
       kind: "agents",
@@ -153,7 +692,7 @@ async function checkAgentsCompiled(config, projectDir) {
   const agentChecks = await Promise.all(
     agents.map(async (agent) => {
       const agentsDir = agent.scope === "global" ? globalAgentsDir : projectAgentsDir;
-      const agentPath = path.join(agentsDir, `${agent.name}.md`);
+      const agentPath = path3.join(agentsDir, `${agent.name}.md`);
       return { name: agent.name, compiled: await fileExists(agentPath) };
     })
   );
@@ -190,30 +729,21 @@ async function checkNoOrphans(config, projectDir) {
   const projectMdFiles = projectExists ? await listAgentMdFiles(projectAgentsDir) : [];
   const globalMdFiles = globalExists ? await listAgentMdFiles(globalAgentsDir) : [];
   const activeProjectAgents = new Set(
-    (config.agents ?? []).filter((a) => a.scope === "project" && !a.excluded).map((a) => a.name)
+    config.agents.filter((a) => a.scope === "project" && !a.excluded).map((a) => a.name)
   );
   const knownGlobalAgents = new Set(
-    (config.agents ?? []).filter((a) => a.scope === "global").map((a) => a.name)
+    config.agents.filter((a) => a.scope === "global").map((a) => a.name)
   );
   const knownProjectDirAgents = scopesShareAgentsDir ? /* @__PURE__ */ new Set([...activeProjectAgents, ...knownGlobalAgents]) : activeProjectAgents;
-  const orphanedFiles = [];
-  for (const file of projectMdFiles) {
-    const agentName = file.replace(/\.md$/, "");
-    if (!knownProjectDirAgents.has(agentName)) {
-      orphanedFiles.push(agentName);
-    }
-  }
-  for (const file of globalMdFiles) {
-    const agentName = file.replace(/\.md$/, "");
-    if (!knownGlobalAgents.has(agentName)) {
-      orphanedFiles.push(agentName);
-    }
-  }
+  const orphanedFiles = [
+    ...orphanedAgentNames(projectMdFiles, knownProjectDirAgents),
+    ...orphanedAgentNames(globalMdFiles, knownGlobalAgents)
+  ];
   if (orphanedFiles.length > 0) {
     return {
       kind: "orphans",
       status: "warn",
-      message: `${orphanedFiles.length} orphaned agent file${orphanedFiles.length === 1 ? "" : "s"}`,
+      message: plural(orphanedFiles.length, "orphaned agent file"),
       details: orphanedFiles.map((f) => `- ${f}.md (not in config)`)
     };
   }
@@ -223,8 +753,29 @@ async function checkNoOrphans(config, projectDir) {
     message: "No orphaned agent files"
   };
 }
+function orphanedAgentNames(mdFiles, knownAgents) {
+  return mdFiles.map((fileName) => fileName.replace(/\.md$/, "")).filter((agentName) => !knownAgents.has(agentName));
+}
+async function checkUnownedInstallation(projectDir) {
+  const { skills, agents } = await listInstalledArtifacts(projectDir);
+  if (skills.length === 0 && agents.length === 0) return skippedResult("orphans");
+  return {
+    kind: "orphans-unowned",
+    status: "fail",
+    // The per-line "(not in config)" the other verdict repeats is said once here instead:
+    // with no configuration it is true of every line, and there are as many lines as files.
+    message: `${countedArtifacts(skills, agents)} installed here, and no configuration declares them`,
+    details: [...skills, ...agents].map((artifact) => `- ${artifact}`)
+  };
+}
+function countedArtifacts(skills, agents) {
+  return [
+    ...skills.length > 0 ? [plural(skills.length, "skill")] : [],
+    ...agents.length > 0 ? [plural(agents.length, "agent")] : []
+  ].join(" and ");
+}
 async function checkSkillsInstalled(config, projectDir) {
-  const skills = config.skills ?? [];
+  const skills = config.skills;
   const ejectSkills = skills.filter((s) => s.source === EJECT_SOURCE);
   if (ejectSkills.length === 0) {
     return {
@@ -236,7 +787,7 @@ async function checkSkillsInstalled(config, projectDir) {
   const skillChecks = await Promise.all(
     ejectSkills.map(async (skill) => {
       const baseDir = installBaseDir(projectDir, skill.scope);
-      const skillMdPath = path.join(baseDir, LOCAL_SKILLS_PATH, skill.id, STANDARD_FILES.SKILL_MD);
+      const skillMdPath = path3.join(baseDir, LOCAL_SKILLS_PATH, skill.id, STANDARD_FILES.SKILL_MD);
       return { id: skill.id, installed: await fileExists(skillMdPath) };
     })
   );
@@ -245,7 +796,7 @@ async function checkSkillsInstalled(config, projectDir) {
     return {
       kind: "installed",
       status: "warn",
-      message: `${missingSkills.length} skill${missingSkills.length === 1 ? "" : "s"} missing from disk`,
+      message: `${plural(missingSkills.length, "skill")} missing from disk`,
       details: missingSkills.map((s) => `- ${s} (not found in ${LOCAL_SKILLS_PATH}/)`)
     };
   }
@@ -280,7 +831,7 @@ async function checkPluginSkillsInstalled(config, projectDir) {
     return {
       kind: "plugins",
       status: "warn",
-      message: `${missingSkills.length} skill${missingSkills.length === 1 ? "" : "s"} not installed as plugins`,
+      message: `${plural(missingSkills.length, "skill")} not installed as plugins`,
       details: missingSkills.map((s) => `- ${s} (no enabled plugin found)`)
     };
   }
@@ -313,7 +864,82 @@ async function checkSourceReachable(projectDir) {
     };
   }
 }
+var CONFIG_CHECK = {
+  kind: "content-config",
+  name: "Config",
+  noun: "config",
+  run: validateProjectConfigFile
+};
+var CONTENT_CHECKS = [
+  {
+    kind: "content-sources",
+    name: "Sources",
+    noun: "source",
+    // The registered sources are the ones config.ts names.
+    readsConfig: true,
+    run: validateRegisteredSources
+  },
+  {
+    kind: "content-plugins",
+    name: "Plugins",
+    noun: "plugin",
+    readsConfig: false,
+    run: validateInstalledPlugins
+  },
+  {
+    kind: "content-skills",
+    name: "Skills",
+    noun: "skill",
+    readsConfig: false,
+    run: validateInstalledSkills
+  },
+  {
+    kind: "content-agents",
+    name: "Agents",
+    noun: "agent",
+    readsConfig: false,
+    run: validateInstalledAgents
+  }
+];
+function contentStatus(errors, warnings) {
+  if (errors > 0) return "fail";
+  if (warnings > 0) return "warn";
+  return "pass";
+}
+function contentMessage(noun, count, errors, warnings) {
+  if (errors === 0 && warnings === 0) {
+    return count === 0 ? `No ${noun}s to validate` : `${plural(count, noun)} validated`;
+  }
+  return `${plural(count, noun)}: ${plural(errors, "error")}, ${plural(warnings, "warning")}`;
+}
+function formatContentIssue(issue) {
+  const marker = issue.severity === "error" ? "ERROR" : "WARN";
+  return `- [${marker}] ${issue.file}: ${issue.message}`;
+}
+function toContentResult(check, validation) {
+  const errors = validation.issues.filter((issue) => issue.severity === "error").length;
+  const warnings = validation.issues.length - errors;
+  return {
+    kind: check.kind,
+    status: contentStatus(errors, warnings),
+    message: contentMessage(check.noun, validation.count, errors, warnings),
+    details: [
+      ...validation.notes.map((note) => `- ${note}`),
+      ...validation.issues.map(formatContentIssue)
+    ]
+  };
+}
 var CHECK_WIDTH = 20;
+var SECTION_INDENT = "  ";
+var ROW_INDENT = "    ";
+var SECTION_CONTENT = "Content checks";
+var SECTION_OPERATIONAL = "Operational checks";
+var SKIP_AFTER_CONTENT_ERRORS = "Skipped \u2014 fix the content errors above first";
+var SKIP_NO_INSTALLATION = "Skipped \u2014 no installation here (skills source repository)";
+var SKIP_CONFIG_UNREADABLE = "Skipped \u2014 the configuration that names them cannot be read";
+function plural(count, word) {
+  return `${count} ${word}${count === 1 ? "" : "s"}`;
+}
 function formatCheckName(name) {
   return name.padEnd(CHECK_WIDTH);
 }
@@ -334,21 +960,20 @@ function formatStatus(status) {
   }
 }
 function formatCheckLine(name, result) {
-  const headerLine = `  ${formatCheckName(name)}${formatStatus(result.status)}  ${result.message}`;
+  const headerLine = `${ROW_INDENT}${formatCheckName(name)}${formatStatus(result.status)}  ${result.message}`;
   const detailLines = (result.details ?? []).map(
-    (detail) => `  ${" ".repeat(CHECK_WIDTH)}   ${detail}`
+    (detail) => `${ROW_INDENT}${" ".repeat(CHECK_WIDTH)}   ${detail}`
   );
   return [headerLine, ...detailLines];
 }
 function formatSummary(results) {
   const counts = countBy(results, (r) => r.status);
-  const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
   const parts = [
     `${counts.pass ?? 0} passed`,
     plural(counts.warn ?? 0, "warning"),
     plural(counts.fail ?? 0, "error")
   ];
-  return `  Summary: ${parts.join(", ")}`;
+  return `${SECTION_INDENT}Summary: ${parts.join(", ")}`;
 }
 var TIPS = [
   {
@@ -361,6 +986,31 @@ var TIPS = [
     status: "fail",
     tip: `  Tip: Run '${CLI_INVOKE_COMMAND} init' to create or fix configuration`
   },
+  {
+    // The remedy for a valid config with nothing in it. Not the tip above: there is nothing to
+    // create and nothing to fix. `init` on this config opens the wizard rather than the dashboard
+    // — that is what the detection returning null is FOR — so it is the way to fill it in.
+    kind: "config-empty",
+    status: "warn",
+    tip: `  Tip: Nothing is configured yet \u2014 run '${CLI_INVOKE_COMMAND} init' to choose skills and sub-agents`
+  },
+  {
+    // The one remedy that applies to a config that cannot be read. `init` does not clear such a
+    // file — it refuses it — so the tip above would send the reader in a circle; this is the same
+    // way out `edit` and `init` themselves name, worded the same way.
+    kind: "content-config",
+    status: "fail",
+    tip: `  Tip: There is no automatic repair \u2014 recreate the configuration: '${CLI_INVOKE_COMMAND} uninstall' still works on a config it cannot read, then '${CLI_INVOKE_COMMAND} init'`
+  },
+  {
+    // Printed beside the config tip above, which says how to get a configuration back and
+    // nothing about the files that outlived the old one. Both halves are named with what they
+    // actually do: `uninstall` matches skill directories by their own `forked-from` metadata,
+    // so it clears them without a config — and identifies compiled agents only through one.
+    kind: "orphans-unowned",
+    status: "fail",
+    tip: `  Tip: Nothing declares the files above \u2014 '${CLI_INVOKE_COMMAND} init' writes a configuration that can own them again, or '${CLI_INVOKE_COMMAND} uninstall' removes the installed skills (the compiled agents outlive it: identifying them needs the configuration that is gone)`
+  },
   {
     kind: "skills",
     status: "fail",
@@ -383,6 +1033,15 @@ function formatTips(results) {
 function skippedResult(kind) {
   return { kind, status: "skip", message: "Skipped (config invalid)" };
 }
+function sourceUnreachableSkillsResult() {
+  return { kind: "skills", status: "skip", message: "Skipped (source unreachable)" };
+}
+function skippedContentResult(kind) {
+  return { kind, status: "skip", message: SKIP_CONFIG_UNREADABLE };
+}
+function runContentCheck(check, projectDir) {
+  return safeCheck(check.kind, async () => toContentResult(check, await check.run(projectDir)));
+}
 async function safeCheck(kind, fn) {
   try {
     return await fn();
@@ -394,15 +1053,15 @@ var Doctor = class _Doctor extends BaseCommand {
   static summary = "Diagnose common configuration issues";
   static description = `Run diagnostic checks on your ${DEFAULT_BRANDING.NAME} configuration to identify issues with config validity, skill resolution, agent compilation, and source connectivity.`;
   static examples = ["<%= config.bin %> <%= command.id %>"];
-  // Override parent baseFlags to drop --source (not relevant for diagnostics)
-  static baseFlags = {};
   static flags = {};
   async run() {
     await this.parse(_Doctor);
     setVerbose(true);
     const projectDir = process.cwd();
     this.printHeader();
-    const results = await this.runAllChecks(projectDir);
+    const contentResults = await this.runContentChecks(projectDir);
+    const operationalResults = await this.runOperationalChecks(projectDir, contentResults);
+    const results = [...contentResults, ...operationalResults];
     this.printResults(results);
     if (results.some((r) => r.status === "fail")) {
       this.exit(EXIT_CODES.ERROR);
@@ -412,24 +1071,70 @@ var Doctor = class _Doctor extends BaseCommand {
     this.log("");
     this.log(`${DEFAULT_BRANDING.NAME} Doctor`);
     this.log("");
-    this.log("  Checking configuration health...");
+    this.log(`${SECTION_INDENT}Checking configuration health...`);
     this.log("");
   }
-  async runAllChecks(projectDir) {
+  /**
+   * The config is checked first and alone. A check that reads it to know what to validate would
+   * otherwise ask a file already reported as unreadable — and asking is what emitted the loader's
+   * own failure line once per read, spliced between these rows. Everything that walks installed
+   * content on disk still runs: it says something true whatever the config is in.
+   */
+  async runContentChecks(projectDir) {
+    this.log(`${SECTION_INDENT}${SECTION_CONTENT}`);
+    const configResult = await runContentCheck(CONFIG_CHECK, projectDir);
+    const configUnreadable = configResult.status === "fail";
+    const rows = await Promise.all(
+      CONTENT_CHECKS.map(async (check) => ({
+        name: check.name,
+        result: check.readsConfig && configUnreadable ? skippedContentResult(check.kind) : await runContentCheck(check, projectDir)
+      }))
+    );
+    const allRows = [{ name: CONFIG_CHECK.name, result: configResult }, ...rows];
+    for (const row of allRows) {
+      this.logCheck(row.name, row.result);
+    }
+    return allRows.map((row) => row.result);
+  }
+  /**
+   * The operational layer runs only when it can say something the reader can act on:
+   * not after content errors (its findings would be their cascades), and not in a
+   * source repository with nothing installed (a marketplace author has no install
+   * for it to describe).
+   */
+  async runOperationalChecks(projectDir, contentResults) {
+    this.log("");
+    this.log(`${SECTION_INDENT}${SECTION_OPERATIONAL}`);
+    if (contentResults.some((r) => r.status === "fail")) {
+      this.log(`${ROW_INDENT}${SKIP_AFTER_CONTENT_ERRORS}`);
+      return [];
+    }
     const detected = await detectProject(projectDir);
-    const { result: configResult, config } = checkConfigValid(detected?.config ?? null);
+    if (!detected && await this.isUninstalledSourceRepo(projectDir)) {
+      this.log(`${ROW_INDENT}${SKIP_NO_INSTALLATION}`);
+      return [];
+    }
+    return this.runAllChecks(projectDir, await resolveConfigState(detected, projectDir));
+  }
+  /**
+   * A config file that exists but failed to load also detects as "no project", and
+   * that is a finding rather than an absence — so the skip requires no config file
+   * at all, not merely no usable one.
+   */
+  async isUninstalledSourceRepo(projectDir) {
+    if (await fileExists(getProjectConfigPath(projectDir))) return false;
+    return isSourceRepo(projectDir);
+  }
+  async runAllChecks(projectDir, configState) {
+    const { result: configResult, config } = checkConfigValid(configState);
     this.logCheck("Config Valid", configResult);
     const sourceResult = await safeCheck("source", () => checkSourceReachable(projectDir));
     const filteredConfig = config ? filterExcludedEntries(config) : null;
-    const skillsResult = !config ? skippedResult("skills") : sourceResult.status === "fail" ? {
-      kind: "skills",
-      status: "skip",
-      message: "Skipped (source unreachable)"
-    } : await safeCheck("skills", () => checkSkillsResolved(config, matrix, projectDir));
+    const skillsResult = await this.resolveSkillsCheck(config, sourceResult, projectDir);
     this.logCheck("Skills Resolved", skillsResult);
     const agentsResult = filteredConfig ? await safeCheck("agents", () => checkAgentsCompiled(filteredConfig, projectDir)) : skippedResult("agents");
     this.logCheck("Agents Compiled", agentsResult);
-    const orphansResult = config ? await safeCheck("orphans", () => checkNoOrphans(config, projectDir)) : skippedResult("orphans");
+    const orphansResult = await this.resolveOrphansCheck(config, configState, projectDir);
     this.logCheck("No Orphans", orphansResult);
     const installedResult = filteredConfig ? await safeCheck("installed", () => checkSkillsInstalled(filteredConfig, projectDir)) : skippedResult("installed");
     this.logCheck("Skills Installed", installedResult);
@@ -446,6 +1151,30 @@ var Doctor = class _Doctor extends BaseCommand {
       sourceResult
     ];
   }
+  /**
+   * The orphan row, and which question it can answer. With a config it names the compiled
+   * agents that config does not; with no config at all every installed file is unowned and it
+   * names all of them. It skips for the one state left — a config that loads and fails
+   * validation — because there the file that says who owns what has already been rejected, and
+   * an installation must not be called stranded on the strength of one nobody can trust.
+   */
+  async resolveOrphansCheck(config, configState, projectDir) {
+    if (config) return safeCheck("orphans", () => checkNoOrphans(config, projectDir));
+    if (configState.kind === "absent") {
+      return safeCheck("orphans", () => checkUnownedInstallation(projectDir));
+    }
+    return skippedResult("orphans");
+  }
+  /**
+   * The skills row, and the two states in which it cannot be computed: no config to read the
+   * skills out of, and a source that never loaded — so there is no populated matrix to resolve
+   * them against, and every configured skill would be reported "not found".
+   */
+  async resolveSkillsCheck(config, sourceResult, projectDir) {
+    if (!config) return skippedResult("skills");
+    if (sourceResult.status === "fail") return sourceUnreachableSkillsResult();
+    return safeCheck("skills", () => checkSkillsResolved(config, matrix, projectDir));
+  }
   logCheck(name, result) {
     for (const line of formatCheckLine(name, result)) {
       this.log(line);