@robosoft/skillhub-cli 0.1.2 → 0.3.3

package/bin/skillhub.mjs

@@ -1,34 +1,73 @@
 #!/usr/bin/env node
 
 import fs from "node:fs/promises";
+import fsSync from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import crypto from "node:crypto";
 import process from "node:process";
 import readline from "node:readline/promises";
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const BUNDLED_REGISTRY_DIR = path.join(PACKAGE_ROOT, "skillhub-registry");
+
 const CONFIG_FILE = "skillhub.json";
 const LOCK_FILE = "skillhub.lock.json";
 const DEFAULT_TARGET = "ai";
+const GENERATED_START = "<!-- skillhub:start -->";
+const GENERATED_END = "<!-- skillhub:end -->";
+
 const TARGETS = {
   ai: {
-    label: ".ai/skills",
-    skillsDir: ".ai/skills",
+    label: "Generic AI",
+    sections: {
+      skills: ".ai/skills",
+      rules: ".ai/rules",
+      domain: ".ai/domain",
+    },
     adapters: { agentsMd: true, cursorRules: false, claude: false, githubCopilot: false },
   },
   cursor: {
-    label: ".cursor/skills",
-    skillsDir: ".cursor/skills",
+    label: "Cursor",
+    sections: {
+      skills: ".cursor/skills",
+      rules: ".cursor/rules",
+      domain: ".cursor/domain",
+    },
     adapters: { agentsMd: false, cursorRules: true, claude: false, githubCopilot: false },
   },
   claude: {
-    label: ".claude/skills",
-    skillsDir: ".claude/skills",
+    label: "Claude",
+    sections: {
+      skills: ".claude/skills",
+      rules: ".claude/rules",
+      domain: ".claude/domain",
+    },
     adapters: { agentsMd: false, cursorRules: false, claude: true, githubCopilot: false },
   },
 };
-const DEFAULT_SKILLS_DIR = TARGETS[DEFAULT_TARGET].skillsDir;
-const GENERATED_START = "<!-- skillhub:start -->";
-const GENERATED_END = "<!-- skillhub:end -->";
+
+const SECTION_ALIASES = {
+  skill: "skills",
+  skills: "skills",
+  sk: "skills",
+  rule: "rules",
+  rules: "rules",
+  rl: "rules",
+  domain: "domain",
+  domains: "domain",
+  knowledge: "domain",
+  "domain-knowledge": "domain",
+  dk: "domain",
+};
+
+const SECTION_SINGULAR = {
+  skills: "skill",
+  rules: "rule",
+  domain: "domain",
+};
 
 const colors = {
   reset: "\x1b[0m",
@@ -95,7 +134,7 @@ function normalizeSlashes(value) {
 function safeJoin(root, relativePath) {
   const target = path.resolve(root, relativePath);
   const normalizedRoot = path.resolve(root);
-  if (!target.startsWith(normalizedRoot)) {
+  if (target !== normalizedRoot && !target.startsWith(`${normalizedRoot}${path.sep}`)) {
     throw new Error(`Unsafe path detected: ${relativePath}`);
   }
   return target;
@@ -141,11 +180,8 @@ function normalizeTarget(value) {
     ai: "ai",
     cursor: "cursor",
     cursorrules: "cursor",
-    ".cursor": "cursor",
     claude: "claude",
     cloude: "claude",
-    ".claude": "claude",
-    ".cloude": "claude",
   };
 
   const target = aliases[normalized] || normalized;
@@ -156,17 +192,24 @@ function normalizeTarget(value) {
   return target;
 }
 
-async function askTarget(defaultTarget = DEFAULT_TARGET) {
-  if (!process.stdin.isTTY || !process.stdout.isTTY) {
-    return defaultTarget;
+function normalizeSection(value, fallback = "skills") {
+  const raw = String(value || fallback).trim().toLowerCase();
+  const normalized = SECTION_ALIASES[raw] || raw;
+  if (!TARGETS.ai.sections[normalized]) {
+    throw new Error(`Invalid section "${value}". Use: skill, rule, or domain.`);
   }
+  return normalized;
+}
+
+async function askTarget(defaultTarget = DEFAULT_TARGET) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return defaultTarget;
 
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   try {
-    console.log(paint("bold", "Where should SkillHub install skill files?"));
-    console.log(`  1. ${TARGETS.ai.skillsDir} ${paint("dim", "(generic AI folder + AGENTS.md)")}`);
-    console.log(`  2. ${TARGETS.cursor.skillsDir} ${paint("dim", "(Cursor rules)")}`);
-    console.log(`  3. ${TARGETS.claude.skillsDir} ${paint("dim", "(Claude project instructions)")}`);
+    console.log(paint("bold", "Where should SkillHub attach project knowledge?"));
+    console.log(`  1. .ai ${paint("dim", "(generic AI folder + AGENTS.md)")}`);
+    console.log(`  2. .cursor ${paint("dim", "(Cursor skills/rules/domain)")}`);
+    console.log(`  3. .claude ${paint("dim", "(Claude skills/rules/domain)")}`);
 
     const answer = await rl.question(`Choose target [1/2/3 or ai/cursor/claude] (${defaultTarget}): `);
     const raw = answer.trim();
@@ -180,10 +223,14 @@ async function askTarget(defaultTarget = DEFAULT_TARGET) {
   }
 }
 
+function targetSections(target) {
+  return { ...TARGETS[normalizeTarget(target) || DEFAULT_TARGET].sections };
+}
+
 function getConfigTarget(config) {
   if (config?.target) return normalizeTarget(config.target);
 
-  const skillsDir = config?.skillsDir || DEFAULT_SKILLS_DIR;
+  const skillsDir = config?.skillsDir || config?.sections?.skills || TARGETS.ai.sections.skills;
   if (skillsDir.startsWith(".cursor/")) return "cursor";
   if (skillsDir.startsWith(".claude/") || skillsDir.startsWith(".cloude/")) return "claude";
   return "ai";
@@ -194,42 +241,141 @@ function applyTargetToConfig(config, targetValue, { preserveExistingAdapters = f
   const targetConfig = TARGETS[target];
 
   config.target = target;
-  config.skillsDir = targetConfig.skillsDir;
+  config.sections = targetSections(target);
+  config.skillsDir = config.sections.skills; // backward compatibility
+  config.rulesDir = config.sections.rules;
+  config.domainDir = config.sections.domain;
   config.adapters = preserveExistingAdapters
     ? { ...targetConfig.adapters, ...(config.adapters || {}) }
-    : { ...targetConfig.adapters, ...(target === "ai" ? { agentsMd: true } : {}) };
+    : { ...targetConfig.adapters };
 
   return config;
 }
 
-function parseSkillSpec(spec) {
-  if (!spec || spec.trim().length === 0) {
-    throw new Error("Skill name is required.");
+function defaultInstalled() {
+  return { skills: {}, rules: {}, domain: {} };
+}
+
+function normalizeInstalled(value = {}) {
+  return {
+    skills: { ...(value.skills || {}) },
+    rules: { ...(value.rules || {}) },
+    domain: { ...(value.domain || {}) },
+  };
+}
+
+function defaultConfig(projectRoot, target = DEFAULT_TARGET) {
+  const config = {
+    $schema: "https://skillhub.local/schema/skillhub.schema.json",
+    project: path.basename(projectRoot),
+    registry: "./skillhub-registry",
+    target: DEFAULT_TARGET,
+    sections: targetSections(DEFAULT_TARGET),
+    skillsDir: TARGETS.ai.sections.skills,
+    rulesDir: TARGETS.ai.sections.rules,
+    domainDir: TARGETS.ai.sections.domain,
+    skills: {}, // backward compatibility
+    installed: defaultInstalled(),
+    adapters: {},
+  };
+
+  return applyTargetToConfig(config, target);
+}
+
+function defaultLock() {
+  return {
+    lockfileVersion: 2,
+    updatedAt: now(),
+    installed: defaultInstalled(),
+    skills: {}, // backward compatibility
+  };
+}
+
+async function readProjectConfig(projectRoot) {
+  const configPath = path.join(projectRoot, CONFIG_FILE);
+  const config = await readJson(configPath, null);
+  if (!config) throw new Error(`No ${CONFIG_FILE} found. Run: skillhub init`);
+
+  const target = getConfigTarget(config);
+  config.target = target;
+  config.sections = { ...targetSections(target), ...(config.sections || {}) };
+
+  // Migrate the older Cursor default. Rules should live directly under .cursor/rules,
+  // not under an extra .cursor/rules/skillhub namespace.
+  if (target === "cursor" && config.sections.rules === ".cursor/rules/skillhub") {
+    config.sections.rules = TARGETS.cursor.sections.rules;
   }
 
+  config.skillsDir = config.sections.skills || config.skillsDir || TARGETS[target].sections.skills;
+  config.rulesDir = config.sections.rules || config.rulesDir || TARGETS[target].sections.rules;
+  config.domainDir = config.sections.domain || config.domainDir || TARGETS[target].sections.domain;
+  config.adapters = config.adapters || TARGETS[target].adapters;
+  config.installed = normalizeInstalled(config.installed || { skills: config.skills || {} });
+  config.skills = config.installed.skills;
+
+  return config;
+}
+
+async function readProjectLock(projectRoot) {
+  const lock = (await readJson(path.join(projectRoot, LOCK_FILE), null)) || defaultLock();
+  lock.installed = normalizeInstalled(lock.installed || { skills: lock.skills || {} });
+  lock.skills = lock.installed.skills;
+  return lock;
+}
+
+function parseArtifactSpec(spec) {
+  if (!spec || spec.trim().length === 0) throw new Error("Name is required.");
+
   const trimmed = spec.trim();
   const atIndex = trimmed.lastIndexOf("@");
+  if (atIndex > 0) return { name: trimmed.slice(0, atIndex).replace(/\.md$/i, ""), version: trimmed.slice(atIndex + 1) };
+  return { name: trimmed.replace(/\.md$/i, ""), version: null };
+}
 
-  if (atIndex > 0) {
-    return {
-      name: trimmed.slice(0, atIndex),
-      version: trimmed.slice(atIndex + 1),
-    };
-  }
+function lastPathSegment(value) {
+  const parts = String(value || "")
+    .replace(/\\/g, "/")
+    .split("/")
+    .map((part) => part.trim())
+    .filter(Boolean);
+  return parts.at(-1) || String(value || "").trim();
+}
+
+function localArtifactName(section, requestedName, manifest, flags = {}) {
+  if (flags.as) return String(flags.as).trim().replace(/\.md$/i, "");
+
+  // Registry paths can be namespaced, for example frontend/antipattern.
+  // The namespace is only used to resolve the item from SkillHub. Locally we install
+  // the artifact by its leaf name: antipattern.md, app/, web-app.md.
+  const candidate = requestedName || manifest?.name || "";
+  const leaf = lastPathSegment(candidate);
+  return leaf || lastPathSegment(manifest?.name) || SECTION_SINGULAR[section];
+}
+
+function installedEntryVersion(entry) {
+  if (!entry) return null;
+  if (typeof entry === "string") return entry;
+  return entry.version || null;
+}
+
+function installedEntryLocalName(key, entry) {
+  if (!entry || typeof entry === "string") return lastPathSegment(key);
+  return entry.localName || lastPathSegment(entry.name || key);
+}
 
-  return { name: trimmed, version: null };
+function installedEntrySpec(key, entry) {
+  if (!entry || typeof entry === "string") return key;
+  return entry.name || entry.sourceName || key;
 }
 
 function sortVersions(versions) {
   return versions.sort((left, right) => {
     const a = left.split(".").map((part) => Number.parseInt(part, 10) || 0);
     const b = right.split(".").map((part) => Number.parseInt(part, 10) || 0);
-
     for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
       const diff = (b[index] ?? 0) - (a[index] ?? 0);
       if (diff !== 0) return diff;
     }
-
     return right.localeCompare(left);
   });
 }
@@ -239,7 +385,8 @@ async function listFiles(root, current = root) {
   const files = [];
 
   for (const entry of entries) {
-    if (entry.name === "node_modules" || entry.name === ".git") continue;
+    if (entry.name === "node_modules" || entry.name === ".git" || entry.name === ".DS_Store") continue;
+    if (entry.name.startsWith("._")) continue;
 
     const fullPath = path.join(current, entry.name);
     if (entry.isDirectory()) {
@@ -252,22 +399,18 @@ async function listFiles(root, current = root) {
   return files.sort();
 }
 
-async function readSkillPackageFiles(packageDir) {
+async function readPackageFiles(packageDir) {
   const filePaths = await listFiles(packageDir);
   const files = [];
-
   for (const relativePath of filePaths) {
-    const fullPath = path.join(packageDir, relativePath);
-    const content = await fs.readFile(fullPath, "utf8");
-    files.push({ path: relativePath, content });
+    files.push({ path: relativePath, content: await fs.readFile(path.join(packageDir, relativePath), "utf8") });
   }
-
   return files;
 }
 
 function checksumFiles(files) {
   const hash = crypto.createHash("sha256");
-  for (const file of files.sort((a, b) => a.path.localeCompare(b.path))) {
+  for (const file of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
     hash.update(file.path);
     hash.update("\0");
     hash.update(file.content);
@@ -276,231 +419,316 @@ function checksumFiles(files) {
   return `sha256-${hash.digest("hex")}`;
 }
 
-function defaultConfig(projectRoot, target = DEFAULT_TARGET) {
-  const config = {
-    $schema: "https://skillhub.local/schema/skillhub.schema.json",
-    project: path.basename(projectRoot),
-    registry: "./skillhub-registry",
-    target: DEFAULT_TARGET,
-    skillsDir: DEFAULT_SKILLS_DIR,
-    skills: {},
-    adapters: {},
-  };
-
-  return applyTargetToConfig(config, target);
-}
+function resolveRegistry(projectRoot, config, flags = {}, options = {}) {
+  const { fallbackToBundled = true } = options;
+  const hasFlagRegistry = Boolean(flags.registry);
+  const hasEnvRegistry = Boolean(process.env.SKILLHUB_REGISTRY);
+  const value = flags.registry || process.env.SKILLHUB_REGISTRY || config.registry || "./skillhub-registry";
 
-function defaultLock() {
-  return {
-    lockfileVersion: 1,
-    updatedAt: now(),
-    skills: {},
-  };
-}
+  if (value.startsWith("http://") || value.startsWith("https://")) return value.replace(/\/$/, "");
 
-async function readProjectConfig(projectRoot) {
-  const configPath = path.join(projectRoot, CONFIG_FILE);
-  const config = await readJson(configPath, null);
-  if (!config) {
-    throw new Error(`No ${CONFIG_FILE} found. Run: skillhub init`);
+  const resolved = path.resolve(projectRoot, value);
+  const isDefaultLocalRegistry = value === "./skillhub-registry" || value === "skillhub-registry";
+  if (fallbackToBundled && !hasFlagRegistry && !hasEnvRegistry && isDefaultLocalRegistry && !fsSync.existsSync(resolved) && fsSync.existsSync(BUNDLED_REGISTRY_DIR)) {
+    return BUNDLED_REGISTRY_DIR;
   }
 
-  config.target = getConfigTarget(config);
-  config.skillsDir = config.skillsDir || TARGETS[config.target].skillsDir;
-  config.adapters = config.adapters || TARGETS[config.target].adapters;
-  return config;
+  return resolved;
 }
 
-function resolveRegistry(projectRoot, config, flags = {}) {
-  const value = flags.registry || process.env.SKILLHUB_REGISTRY || config.registry || "./skillhub-registry";
-
-  if (value.startsWith("http://") || value.startsWith("https://")) {
-    return value.replace(/\/$/, "");
-  }
+function firstHeading(content) {
+  const line = content.split(/\r?\n/).find((item) => item.trim().startsWith("# "));
+  return line ? line.replace(/^#\s+/, "").trim() : null;
+}
 
-  return path.resolve(projectRoot, value);
+async function readOptionalJson(filePath) {
+  return (await exists(filePath)) ? readJson(filePath) : null;
 }
 
-async function loadLocalSkill(registryPath, name, requestedVersion) {
-  const skillRoot = safeJoin(registryPath, name);
+function defaultManifest(section, name, version, files) {
+  const entryFile = section === "skills" ? "SKILL.md" : section === "rules" ? "RULE.md" : "DOMAIN.md";
+  const entry = files.find((file) => file.path === entryFile) || files[0];
+  const title = entry ? firstHeading(entry.content) : name;
+  return {
+    name,
+    version: version || "1.0.0",
+    type: SECTION_SINGULAR[section],
+    section,
+    description: title ? `${title} ${SECTION_SINGULAR[section]}` : `Reusable ${SECTION_SINGULAR[section]} knowledge package`,
+    entry: entry?.path || entryFile,
+  };
+}
 
-  if (!(await exists(skillRoot))) {
-    throw new Error(`Skill "${name}" was not found in registry: ${registryPath}`);
-  }
+async function loadVersionedPackage(baseDir, manifestName, requestedVersion) {
+  if (!(await exists(baseDir))) return null;
 
   let packageDir;
   let version = requestedVersion;
-
   if (requestedVersion) {
-    packageDir = path.join(skillRoot, requestedVersion);
-  } else if (await exists(path.join(skillRoot, "skill.json"))) {
-    packageDir = skillRoot;
+    const versionedDir = path.join(baseDir, requestedVersion);
+    if (await exists(versionedDir)) {
+      packageDir = versionedDir;
+    } else if (await exists(path.join(baseDir, manifestName)) || await exists(path.join(baseDir, "skill.json"))) {
+      // Unversioned registry package. Use the package folder but keep the requested version in metadata.
+      packageDir = baseDir;
+    } else {
+      packageDir = versionedDir;
+    }
+  } else if (await exists(path.join(baseDir, manifestName))) {
+    packageDir = baseDir;
+  } else if (await exists(path.join(baseDir, "skill.json"))) {
+    packageDir = baseDir;
+    manifestName = "skill.json";
   } else {
-    const entries = await fs.readdir(skillRoot, { withFileTypes: true });
+    const entries = await fs.readdir(baseDir, { withFileTypes: true });
     const versions = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
-    if (versions.length === 0) {
-      throw new Error(`Skill "${name}" has no versions in registry.`);
-    }
+    if (versions.length === 0) return null;
     version = sortVersions(versions)[0];
-    packageDir = path.join(skillRoot, version);
+    packageDir = path.join(baseDir, version);
   }
 
-  if (!(await exists(packageDir))) {
-    throw new Error(`Skill "${name}@${requestedVersion}" was not found.`);
+  if (!(await exists(packageDir))) return null;
+  return { packageDir, version };
+}
+
+async function loadLocalArtifact(registryPath, section, name, requestedVersion) {
+  const singular = SECTION_SINGULAR[section];
+  const manifestName = `${singular}.json`;
+  const entryName = section === "skills" ? "SKILL.md" : section === "rules" ? "RULE.md" : "DOMAIN.md";
+  const sectionDir = safeJoin(registryPath, section);
+
+  if (!(await exists(registryPath))) throw new Error(`Registry not found: ${registryPath}`);
+
+  // Flat file style: registry/rules/code-standards.md, registry/rules/frontend/antipattern.md, or registry/domain/api.md
+  if (section !== "skills") {
+    const flatFile = safeJoin(sectionDir, `${name}.md`);
+    if (await exists(flatFile)) {
+      const content = await fs.readFile(flatFile, "utf8");
+      const files = [{ path: entryName, content }];
+      return { manifest: defaultManifest(section, name, requestedVersion || "1.0.0", files), files, source: normalizeSlashes(path.relative(process.cwd(), flatFile)) || flatFile };
+    }
   }
 
-  const manifestPath = path.join(packageDir, "skill.json");
-  if (!(await exists(manifestPath))) {
-    throw new Error(`Missing skill.json in ${packageDir}`);
+  // Section package style: registry/skills/react/SKILL.md or registry/rules/frontend/RULE.md
+  const sectionPackageBase = safeJoin(sectionDir, name);
+  const sectionPackage = await loadVersionedPackage(sectionPackageBase, manifestName, requestedVersion);
+  if (sectionPackage) {
+    const files = await readPackageFiles(sectionPackage.packageDir);
+    const manifest = (await readOptionalJson(path.join(sectionPackage.packageDir, manifestName))) ||
+      (section === "skills" ? await readOptionalJson(path.join(sectionPackage.packageDir, "skill.json")) : null) ||
+      defaultManifest(section, name, sectionPackage.version || requestedVersion || "1.0.0", files);
+    validateArtifactManifest(section, manifest, files);
+    return {
+      manifest: { ...manifest, name: manifest.name || name, version: manifest.version || sectionPackage.version || "1.0.0", type: manifest.type || singular, section },
+      files,
+      source: normalizeSlashes(path.relative(process.cwd(), sectionPackage.packageDir)) || sectionPackage.packageDir,
+    };
   }
 
-  const manifest = await readJson(manifestPath);
-  const files = await readSkillPackageFiles(packageDir);
+  // Backward compatible skill registry style: registry/nextjs-clean-architecture/1.0.0/skill.json
+  if (section === "skills") {
+    const legacyBase = safeJoin(registryPath, name);
+    const legacyPackage = await loadVersionedPackage(legacyBase, "skill.json", requestedVersion);
+    if (legacyPackage) {
+      const files = await readPackageFiles(legacyPackage.packageDir);
+      const manifest = (await readOptionalJson(path.join(legacyPackage.packageDir, "skill.json"))) || defaultManifest(section, name, legacyPackage.version || "1.0.0", files);
+      validateArtifactManifest(section, manifest, files);
+      return { manifest: { ...manifest, type: "skill", section }, files, source: normalizeSlashes(path.relative(process.cwd(), legacyPackage.packageDir)) || legacyPackage.packageDir };
+    }
+  }
 
-  validateSkillManifest(manifest, files);
+  throw new Error(`${SECTION_SINGULAR[section]} "${name}" was not found in registry: ${registryPath}`);
+}
 
-  return {
-    manifest: {
-      ...manifest,
-      name: manifest.name || name,
-      version: manifest.version || version || "0.0.0",
-    },
-    files,
-    source: normalizeSlashes(path.relative(process.cwd(), packageDir)) || packageDir,
-  };
+function encodePathParts(value) {
+  return String(value)
+    .split("/")
+    .filter(Boolean)
+    .map((part) => encodeURIComponent(part))
+    .join("/");
 }
 
-async function loadRemoteSkill(registryUrl, name, requestedVersion) {
-  const versionPath = requestedVersion ? requestedVersion : "latest";
-  const url = `${registryUrl}/skills/${encodeURIComponent(name)}/${encodeURIComponent(versionPath)}`;
+async function fetchJsonIfOk(url) {
   const response = await fetch(url);
+  if (!response.ok) return null;
+  return response.json();
+}
 
-  if (!response.ok) {
-    throw new Error(`Registry returned ${response.status} for ${url}`);
+async function loadRemoteArtifact(registryUrl, section, name, requestedVersion) {
+  const versionPath = requestedVersion || "latest";
+  const itemPath = encodePathParts(name);
+  const version = encodeURIComponent(versionPath);
+
+  const urls = [
+    // Recommended web app contract:
+    // GET https://your-skillhub-app.com/api/skillhub/rules/frontend/antipattern/latest
+    `${registryUrl}/api/skillhub/${section}/${itemPath}/${version}`,
+
+    // Registry-only contract:
+    // GET https://your-registry.com/rules/frontend/antipattern/latest
+    `${registryUrl}/${section}/${itemPath}/${version}`,
+
+    // Legacy encoded-name contract:
+    `${registryUrl}/${section}/${encodeURIComponent(name)}/${version}`,
+  ];
+
+  let payload = null;
+  let usedUrl = null;
+  for (const url of urls) {
+    payload = await fetchJsonIfOk(url);
+    if (payload) {
+      usedUrl = url;
+      break;
+    }
   }
 
-  const payload = await response.json();
-  const manifest = payload.manifest || payload.skill || payload;
-  const files = payload.files || [];
-
-  validateSkillManifest(manifest, files);
+  if (!payload) {
+    throw new Error(`Remote ${SECTION_SINGULAR[section]} "${name}" was not found. Tried: ${urls.join(", ")}`);
+  }
 
-  return {
-    manifest,
-    files,
-    source: url,
-  };
+  const manifest = payload.manifest || payload[SECTION_SINGULAR[section]] || payload;
+  const files = payload.files || [];
+  validateArtifactManifest(section, manifest, files);
+  return { manifest: { ...manifest, name: manifest.name || name, section, type: manifest.type || SECTION_SINGULAR[section] }, files, source: usedUrl };
 }
 
-async function loadSkill(registry, name, requestedVersion) {
+async function loadArtifact(registry, section, name, requestedVersion) {
   if (registry.startsWith("http://") || registry.startsWith("https://")) {
-    return loadRemoteSkill(registry, name, requestedVersion);
+    return loadRemoteArtifact(registry, section, name, requestedVersion);
   }
+  return loadLocalArtifact(registry, section, name, requestedVersion);
+}
+
+function validateArtifactManifest(section, manifest, files) {
+  if (!manifest || typeof manifest !== "object") throw new Error("Invalid manifest.");
+  if (!manifest.name) throw new Error("Manifest must include name.");
+  if (!manifest.version) throw new Error("Manifest must include version.");
+
+  const required = section === "skills" ? "SKILL.md" : section === "rules" ? "RULE.md" : "DOMAIN.md";
+  const hasRequired = files.some((file) => file.path === required || file.path.endsWith(`/${required}`));
+  if (!hasRequired && files.length === 0) throw new Error(`${manifest.name}@${manifest.version} has no files.`);
+}
 
-  return loadLocalSkill(registry, name, requestedVersion);
+function cursorRuleContent(content, title) {
+  if (content.trimStart().startsWith("---")) return content;
+  return `---\ndescription: ${title}\nalwaysApply: true\n---\n\n${content}`;
 }
 
-function validateSkillManifest(manifest, files) {
-  if (!manifest || typeof manifest !== "object") {
-    throw new Error("Invalid skill manifest.");
+async function writeArtifactFiles(projectRoot, config, section, artifactName, files) {
+  const target = getConfigTarget(config);
+  const baseDir = config.sections?.[section] || TARGETS[target].sections[section];
+
+  if (section === "skills") {
+    const targetDir = path.join(projectRoot, baseDir, artifactName);
+    await fs.rm(targetDir, { recursive: true, force: true });
+    await ensureDir(targetDir);
+
+    // Skills are capability packages. Project rules must be attached explicitly with
+    // `skillhub rule ...`, so we do not copy a skill package's internal rules folder
+    // into the IDE skill folder. This keeps .cursor/skills/app focused on the skill
+    // itself while .cursor/rules remains the single place for rules.
+    const skillFiles = files.filter((file) => {
+      const relativePath = normalizeSlashes(file.path);
+      return relativePath !== "rules" && !relativePath.startsWith("rules/");
+    });
+
+    for (const file of skillFiles) {
+      const targetPath = safeJoin(targetDir, file.path);
+      await ensureDir(path.dirname(targetPath));
+      await fs.writeFile(targetPath, file.content, "utf8");
+    }
+    return `${baseDir}/${artifactName}`;
   }
 
-  if (!manifest.name) throw new Error("skill.json must include name.");
-  if (!manifest.version) throw new Error("skill.json must include version.");
+  const entryName = section === "rules" ? "RULE.md" : "DOMAIN.md";
+  const singleEntry = files.length === 1 && files[0].path === entryName;
 
-  const hasSkillMd = files.some((file) => file.path === "SKILL.md");
-  if (!hasSkillMd) {
-    throw new Error(`${manifest.name}@${manifest.version} must include SKILL.md.`);
+  if (singleEntry) {
+    const targetPath = safeJoin(path.join(projectRoot, baseDir), `${artifactName}.md`);
+    await ensureDir(path.dirname(targetPath));
+    await fs.writeFile(targetPath, files[0].content, "utf8");
+    return `${baseDir}/${artifactName}.md`;
   }
-}
 
-async function writeSkillFiles(projectRoot, skillsDir, skillName, files) {
-  const targetDir = path.join(projectRoot, skillsDir, skillName);
+  const targetDir = path.join(projectRoot, baseDir, artifactName);
   await fs.rm(targetDir, { recursive: true, force: true });
   await ensureDir(targetDir);
-
   for (const file of files) {
     const targetPath = safeJoin(targetDir, file.path);
     await ensureDir(path.dirname(targetPath));
     await fs.writeFile(targetPath, file.content, "utf8");
   }
-
-  return targetDir;
-}
-
-async function updateAdapters(projectRoot, config, lock) {
-  const adapters = config.adapters || {};
-  const skillsDir = config.skillsDir || DEFAULT_SKILLS_DIR;
-  const installed = Object.entries(lock.skills || {}).sort(([a], [b]) => a.localeCompare(b));
-
-  if (adapters.agentsMd) {
-    await updateAgentsMd(projectRoot, skillsDir, installed);
-  }
-
-  if (adapters.cursorRules) {
-    await updateCursorRules(projectRoot, skillsDir, installed);
-  }
-
-  if (adapters.claude) {
-    await updateClaudeMd(projectRoot, skillsDir, installed);
-  }
-
-  if (adapters.githubCopilot) {
-    await updateCopilotInstructions(projectRoot, skillsDir, installed);
-  }
+  return `${baseDir}/${artifactName}`;
 }
 
-function generatedSkillList(skillsDir, installed) {
-  if (installed.length === 0) {
-    return "No SkillHub skills installed yet.";
+function generatedArtifactList(lock) {
+  const installed = normalizeInstalled(lock.installed || { skills: lock.skills || {} });
+  const sections = [
+    ["Skills", "skills"],
+    ["Rules", "rules"],
+    ["Domain Knowledge", "domain"],
+  ];
+
+  const lines = [];
+  for (const [title, section] of sections) {
+    const entries = Object.entries(installed[section] || {}).sort(([a], [b]) => a.localeCompare(b));
+    lines.push(`## ${title}`);
+    if (entries.length === 0) {
+      lines.push("No entries installed.");
+    } else {
+      for (const [name, meta] of entries) {
+        const version = installedEntryVersion(meta);
+        const installTo = typeof meta === "string" ? "" : `: ${meta.installTo}`;
+        const localName = installedEntryLocalName(name, meta);
+        const label = localName && localName !== name ? `${name} → ${localName}` : name;
+        lines.push(`- ${label}@${version}${installTo}`);
+      }
+    }
+    lines.push("");
   }
-
-  return installed
-    .map(([name, meta]) => `- ${name}@${meta.version}: ${skillsDir}/${name}/SKILL.md`)
-    .join("\n");
+  return lines.join("\n").trim();
 }
 
 async function replaceGeneratedBlock(filePath, generatedBlock, defaultPrefix = "") {
   let content = defaultPrefix;
-
-  if (await exists(filePath)) {
-    content = await fs.readFile(filePath, "utf8");
-  }
+  if (await exists(filePath)) content = await fs.readFile(filePath, "utf8");
 
   const block = `${GENERATED_START}\n${generatedBlock.trim()}\n${GENERATED_END}`;
   const pattern = new RegExp(`${GENERATED_START}[\\s\\S]*?${GENERATED_END}`);
-
-  if (pattern.test(content)) {
-    content = content.replace(pattern, block);
-  } else {
-    const separator = content.trim().length > 0 ? "\n\n" : "";
-    content = `${content.trimEnd()}${separator}${block}\n`;
-  }
+  if (pattern.test(content)) content = content.replace(pattern, block);
+  else content = `${content.trimEnd()}${content.trim().length > 0 ? "\n\n" : ""}${block}\n`;
 
   await ensureDir(path.dirname(filePath));
   await fs.writeFile(filePath, content, "utf8");
 }
 
-async function updateAgentsMd(projectRoot, skillsDir, installed) {
-  const body = `# SkillHub Instructions\n\nWhen working in this project, read and follow the installed skills below before generating or changing code.\n\n${generatedSkillList(skillsDir, installed)}`;
-  await replaceGeneratedBlock(path.join(projectRoot, "AGENTS.md"), body, "# Project Agents\n");
-}
+async function updateAdapters(projectRoot, config, lock) {
+  const adapters = config.adapters || {};
+  const target = getConfigTarget(config);
+  const body = `# SkillHub Project Knowledge\n\nBefore editing this project, read and follow the attached SkillHub knowledge packages.\n\n${generatedArtifactList(lock)}`;
 
-async function updateCursorRules(projectRoot, skillsDir, installed) {
-  const body = `---\ndescription: SkillHub installed project skills\nalwaysApply: true\n---\n\n# SkillHub Rules\n\nFollow these installed skill files before editing code:\n\n${generatedSkillList(skillsDir, installed)}`;
-  await ensureDir(path.join(projectRoot, ".cursor/rules"));
-  await fs.writeFile(path.join(projectRoot, ".cursor/rules/skillhub.mdc"), `${body}\n`, "utf8");
-}
+  if (adapters.agentsMd) {
+    await replaceGeneratedBlock(path.join(projectRoot, "AGENTS.md"), body, "# Project Agents\n");
+  }
 
-async function updateClaudeMd(projectRoot, skillsDir, installed) {
-  const body = `# SkillHub Instructions\n\nFollow the installed skills below before generating or changing code:\n\n${generatedSkillList(skillsDir, installed)}`;
-  await replaceGeneratedBlock(path.join(projectRoot, "CLAUDE.md"), body, "# Claude Project Instructions\n");
-  await replaceGeneratedBlock(path.join(projectRoot, ".claude/skillhub.md"), body, "# Claude SkillHub Instructions\n");
-}
+  if (adapters.cursorRules) {
+    const cursorBody = `---\ndescription: SkillHub installed project knowledge\nalwaysApply: true\n---\n\n${body}\n\nUse the linked skill, rule, and domain files as the source of truth.`;
+    await ensureDir(path.join(projectRoot, ".cursor/rules"));
+    await fs.writeFile(path.join(projectRoot, ".cursor/rules/skillhub.md"), `${cursorBody}\n`, "utf8");
+  }
 
-async function updateCopilotInstructions(projectRoot, skillsDir, installed) {
-  const body = `# SkillHub Instructions\n\nUse these installed skill files as project coding guidance:\n\n${generatedSkillList(skillsDir, installed)}`;
-  await replaceGeneratedBlock(path.join(projectRoot, ".github/copilot-instructions.md"), body, "# GitHub Copilot Instructions\n");
+  if (adapters.claude) {
+    await replaceGeneratedBlock(path.join(projectRoot, "CLAUDE.md"), body, "# Claude Project Instructions\n");
+    await replaceGeneratedBlock(path.join(projectRoot, ".claude/skillhub.md"), body, "# Claude SkillHub Instructions\n");
+  }
+
+  if (adapters.githubCopilot) {
+    await replaceGeneratedBlock(path.join(projectRoot, ".github/copilot-instructions.md"), body, "# GitHub Copilot Instructions\n");
+  }
+
+  await ensureDir(path.join(projectRoot, TARGETS[target].sections.skills));
+  await ensureDir(path.join(projectRoot, TARGETS[target].sections.rules));
+  await ensureDir(path.join(projectRoot, TARGETS[target].sections.domain));
 }
 
 async function commandInit(projectRoot, flags) {
@@ -512,17 +740,12 @@ async function commandInit(projectRoot, flags) {
   if (await exists(configPath)) {
     config = await readProjectConfig(projectRoot);
     warn(`${CONFIG_FILE} already exists.`);
-
     if (requestedTarget) {
       const previousTarget = getConfigTarget(config);
       applyTargetToConfig(config, requestedTarget);
       if (flags.registry) config.registry = flags.registry;
       await writeJson(configPath, config);
-      if (previousTarget === requestedTarget) {
-        ok(`${CONFIG_FILE} already uses target ${requestedTarget}`);
-      } else {
-        ok(`Updated ${CONFIG_FILE} target: ${previousTarget} → ${requestedTarget}`);
-      }
+      ok(previousTarget === requestedTarget ? `${CONFIG_FILE} already uses target ${requestedTarget}` : `Updated ${CONFIG_FILE} target: ${previousTarget} → ${requestedTarget}`);
     } else if (flags.registry) {
       config.registry = flags.registry;
       await writeJson(configPath, config);
@@ -539,202 +762,339 @@ async function commandInit(projectRoot, flags) {
     ok(`Created ${CONFIG_FILE}`);
   }
 
-  if (await exists(lockPath)) {
-    warn(`${LOCK_FILE} already exists.`);
-  } else {
-    await writeJson(lockPath, defaultLock());
+  const lock = (await exists(lockPath)) ? await readProjectLock(projectRoot) : defaultLock();
+  if (await exists(lockPath)) warn(`${LOCK_FILE} already exists.`);
+  else {
+    await writeJson(lockPath, lock);
     ok(`Created ${LOCK_FILE}`);
   }
 
-  await ensureDir(path.join(projectRoot, config.skillsDir));
-  ok(`Created ${config.skillsDir}`);
-
+  await updateAdapters(projectRoot, config, lock);
+  ok(`Created ${config.sections.skills}`);
+  ok(`Created ${config.sections.rules}`);
+  ok(`Created ${config.sections.domain}`);
   info(`Target: ${config.target}`);
-  info("Next: skillhub install nextjs-clean-architecture");
+  info("Next: skillhub rule frontend/antipattern");
 }
 
-async function commandInstall(projectRoot, spec, flags = {}) {
+async function persistInstall(projectRoot, config, lock, section, sourceName, localName, artifact, installTo) {
   const configPath = path.join(projectRoot, CONFIG_FILE);
   const lockPath = path.join(projectRoot, LOCK_FILE);
+  const checksum = checksumFiles(artifact.files);
+
+  config.installed = normalizeInstalled(config.installed);
+  config.installed[section][sourceName] = {
+    name: sourceName,
+    localName,
+    version: artifact.manifest.version,
+    installTo,
+  };
+  config.skills = config.installed.skills;
+
+  lock.installed = normalizeInstalled(lock.installed);
+  lock.installed[section][sourceName] = {
+    name: sourceName,
+    localName,
+    version: artifact.manifest.version,
+    source: artifact.source,
+    installTo,
+    checksum,
+    installedAt: now(),
+  };
+  lock.skills = lock.installed.skills;
+  lock.updatedAt = now();
+
+  await writeJson(configPath, config);
+  await writeJson(lockPath, lock);
+  await updateAdapters(projectRoot, config, lock);
+}
+
+async function commandAttach(projectRoot, sectionValue, spec, flags = {}) {
+  const section = normalizeSection(sectionValue || flags.type || flags.section || "skills");
+  if (!spec) throw new Error(`${SECTION_SINGULAR[section]} name is required.`);
+
   const config = await readProjectConfig(projectRoot);
   if (flags.target || flags.to) {
     applyTargetToConfig(config, flags.target || flags.to);
   }
-  const lock = (await readJson(lockPath, null)) || defaultLock();
-  const registry = resolveRegistry(projectRoot, config, flags);
-  const { name, version } = parseSkillSpec(spec);
-
-  info(`Resolving ${name}${version ? `@${version}` : ""}`);
-  const skill = await loadSkill(registry, name, version);
-  const skillName = skill.manifest.name;
-  const skillsDir = config.skillsDir || DEFAULT_SKILLS_DIR;
-  const checksum = checksumFiles(skill.files);
 
-  await writeSkillFiles(projectRoot, skillsDir, skillName, skill.files);
+  const lock = await readProjectLock(projectRoot);
+  const registry = resolveRegistry(projectRoot, config, flags);
+  const { name, version } = parseArtifactSpec(spec);
+
+  info(`Resolving ${SECTION_SINGULAR[section]} ${name}${version ? `@${version}` : ""}`);
+  const artifact = await loadArtifact(registry, section, name, version);
+  const sourceName = name;
+  const artifactName = localArtifactName(section, sourceName, artifact.manifest, flags);
+  const installTo = await writeArtifactFiles(projectRoot, config, section, artifactName, artifact.files);
+  await persistInstall(projectRoot, config, lock, section, sourceName, artifactName, artifact, installTo);
+
+  ok(`Attached ${SECTION_SINGULAR[section]} ${sourceName}@${artifact.manifest.version}`);
+  if (sourceName !== artifactName) info(`Local name: ${artifactName}`);
+  info(`Files written to ${installTo}`);
+}
 
-  config.skills = config.skills || {};
-  config.skills[skillName] = skill.manifest.version;
-  await writeJson(configPath, config);
+async function commandInstall(projectRoot, positional, flags = {}) {
+  if (positional.length === 0) {
+    await commandSync(projectRoot, flags);
+    return;
+  }
 
-  lock.updatedAt = now();
-  lock.skills = lock.skills || {};
-  lock.skills[skillName] = {
-    version: skill.manifest.version,
-    source: skill.source,
-    installTo: `${skillsDir}/${skillName}`,
-    checksum,
-    installedAt: now(),
-  };
-  await writeJson(lockPath, lock);
+  let section = flags.type || flags.section || "skills";
+  let spec = positional[0];
 
-  await updateAdapters(projectRoot, config, lock);
+  if (positional.length >= 2 && SECTION_ALIASES[positional[0]]) {
+    section = positional[0];
+    spec = positional[1];
+  }
 
-  ok(`Installed ${skillName}@${skill.manifest.version}`);
-  info(`Files written to ${skillsDir}/${skillName}`);
+  await commandAttach(projectRoot, section, spec, flags);
 }
 
 async function commandSync(projectRoot, flags = {}) {
-  const configPath = path.join(projectRoot, CONFIG_FILE);
   const config = await readProjectConfig(projectRoot);
   if (flags.target || flags.to) {
     applyTargetToConfig(config, flags.target || flags.to);
-    await writeJson(configPath, config);
+    await writeJson(path.join(projectRoot, CONFIG_FILE), config);
   }
-  const skills = Object.entries(config.skills || {});
 
-  if (skills.length === 0) {
-    warn("No skills configured in skillhub.json.");
+  const installed = normalizeInstalled(config.installed || { skills: config.skills || {} });
+  const entries = [
+    ...Object.entries(installed.skills).map(([key, entry]) => ["skills", `${installedEntrySpec(key, entry)}@${installedEntryVersion(entry)}`, installedEntryLocalName(key, entry)]),
+    ...Object.entries(installed.rules).map(([key, entry]) => ["rules", `${installedEntrySpec(key, entry)}@${installedEntryVersion(entry)}`, installedEntryLocalName(key, entry)]),
+    ...Object.entries(installed.domain).map(([key, entry]) => ["domain", `${installedEntrySpec(key, entry)}@${installedEntryVersion(entry)}`, installedEntryLocalName(key, entry)]),
+  ];
+
+  if (entries.length === 0) {
+    warn("No SkillHub knowledge configured in skillhub.json.");
     return;
   }
 
-  for (const [name, version] of skills) {
-    await commandInstall(projectRoot, `${name}@${version}`, flags);
+  for (const [section, spec, localName] of entries) {
+    await commandAttach(projectRoot, section, spec, { ...flags, as: flags.as || localName });
   }
 
-  ok(`Synced ${skills.length} skill${skills.length === 1 ? "" : "s"}.`);
+  ok(`Synced ${entries.length} item${entries.length === 1 ? "" : "s"}.`);
 }
 
 async function commandList(projectRoot) {
-  const lock = await readJson(path.join(projectRoot, LOCK_FILE), null);
+  const lock = await readProjectLock(projectRoot);
+  const installed = normalizeInstalled(lock.installed || { skills: lock.skills || {} });
+  const hasAny = Object.values(installed).some((items) => Object.keys(items).length > 0);
 
-  if (!lock || !lock.skills || Object.keys(lock.skills).length === 0) {
-    warn("No skills installed yet.");
+  if (!hasAny) {
+    warn("No SkillHub knowledge attached yet.");
     return;
   }
 
-  console.log(paint("bold", "Installed SkillHub skills"));
-  for (const [name, meta] of Object.entries(lock.skills).sort(([a], [b]) => a.localeCompare(b))) {
-    console.log(`- ${name}@${meta.version} ${paint("dim", `→ ${meta.installTo}`)}`);
+  console.log(paint("bold", "Attached SkillHub knowledge"));
+  for (const [title, section] of [["Skills", "skills"], ["Rules", "rules"], ["Domain", "domain"]]) {
+    const entries = Object.entries(installed[section] || {}).sort(([a], [b]) => a.localeCompare(b));
+    if (entries.length === 0) continue;
+    console.log(`\n${paint("bold", title)}`);
+    for (const [name, meta] of entries) {
+      const version = installedEntryVersion(meta);
+      const installTo = typeof meta === "string" ? "" : ` → ${meta.installTo}`;
+      const localName = installedEntryLocalName(name, meta);
+      const label = localName && localName !== name ? `${name} → ${localName}` : name;
+      console.log(`- ${label}@${version}${paint("dim", installTo)}`);
+    }
   }
 }
 
-async function commandRemove(projectRoot, skillName) {
-  if (!skillName) throw new Error("Skill name is required.");
+async function commandRemove(projectRoot, sectionValue, name) {
+  let section = normalizeSection(sectionValue || "skills");
+  let artifactName = name;
+  if (!artifactName) {
+    artifactName = sectionValue;
+    section = "skills";
+  }
+  if (!artifactName) throw new Error("Name is required.");
 
-  const configPath = path.join(projectRoot, CONFIG_FILE);
-  const lockPath = path.join(projectRoot, LOCK_FILE);
   const config = await readProjectConfig(projectRoot);
-  const lock = (await readJson(lockPath, null)) || defaultLock();
-  const skillsDir = config.skillsDir || DEFAULT_SKILLS_DIR;
-  const installedPath = lock.skills?.[skillName]?.installTo || `${skillsDir}/${skillName}`;
-
-  delete config.skills?.[skillName];
-  delete lock.skills?.[skillName];
+  const lock = await readProjectLock(projectRoot);
+  config.installed = normalizeInstalled(config.installed);
+  lock.installed = normalizeInstalled(lock.installed);
+
+  const sectionLock = lock.installed[section] || {};
+  const sectionConfig = config.installed[section] || {};
+  const key = sectionLock[artifactName] || sectionConfig[artifactName]
+    ? artifactName
+    : Object.keys({ ...sectionConfig, ...sectionLock }).find((candidate) => installedEntryLocalName(candidate, sectionLock[candidate] || sectionConfig[candidate]) === artifactName);
+
+  if (!key) throw new Error(`${SECTION_SINGULAR[section]} "${artifactName}" is not attached.`);
+
+  const installedPath = sectionLock[key]?.installTo || sectionConfig[key]?.installTo;
+  delete config.installed[section]?.[key];
+  delete lock.installed[section]?.[key];
+  config.skills = config.installed.skills;
+  lock.skills = lock.installed.skills;
   lock.updatedAt = now();
 
-  await fs.rm(path.join(projectRoot, installedPath), { recursive: true, force: true });
-  await writeJson(configPath, config);
-  await writeJson(lockPath, lock);
+  if (installedPath) await fs.rm(path.join(projectRoot, installedPath), { recursive: true, force: true });
+  await writeJson(path.join(projectRoot, CONFIG_FILE), config);
+  await writeJson(path.join(projectRoot, LOCK_FILE), lock);
   await updateAdapters(projectRoot, config, lock);
 
-  ok(`Removed ${skillName}`);
+  ok(`Removed ${SECTION_SINGULAR[section]} ${artifactName}`);
 }
 
 async function commandTarget(projectRoot, targetValue, flags = {}) {
-  const configPath = path.join(projectRoot, CONFIG_FILE);
-  const lockPath = path.join(projectRoot, LOCK_FILE);
   const config = await readProjectConfig(projectRoot);
   const target = normalizeTarget(targetValue || flags.target || flags.to) || await askTarget(getConfigTarget(config));
-
   applyTargetToConfig(config, target);
-  await writeJson(configPath, config);
-  await ensureDir(path.join(projectRoot, config.skillsDir));
+  await writeJson(path.join(projectRoot, CONFIG_FILE), config);
 
-  const lock = (await readJson(lockPath, null)) || defaultLock();
+  const lock = await readProjectLock(projectRoot);
   await updateAdapters(projectRoot, config, lock);
 
   ok(`SkillHub target set to ${target}`);
-  info(`Skill files will be installed to ${config.skillsDir}`);
-  if (Object.keys(lock.skills || {}).length > 0) {
-    info("Run: skillhub sync");
-  }
+  info(`Skills: ${config.sections.skills}`);
+  info(`Rules: ${config.sections.rules}`);
+  info(`Domain: ${config.sections.domain}`);
+  if (Object.values(lock.installed || {}).some((items) => Object.keys(items).length > 0)) info("Run: skillhub sync");
 }
 
-async function commandCreate(projectRoot, name, flags = {}) {
-  if (!name) throw new Error("Skill name is required.");
-
-  const config = (await readJson(path.join(projectRoot, CONFIG_FILE), null)) || defaultConfig(projectRoot);
-  const registry = resolveRegistry(projectRoot, config, flags);
+function titleFromName(name) {
+  return String(name)
+    .replace(/[-_]+/g, " ")
+    .replace(/\b\w/g, (char) => char.toUpperCase());
+}
 
-  if (registry.startsWith("http://") || registry.startsWith("https://")) {
-    throw new Error("Cannot create a skill inside a remote registry. Use --registry ./path");
+async function commandCreate(projectRoot, positional, flags = {}) {
+  let section = "skills";
+  let name = positional[0];
+  if (positional.length >= 2 && SECTION_ALIASES[positional[0]]) {
+    section = normalizeSection(positional[0]);
+    name = positional[1];
   }
-
-  const version = flags.version || "1.0.0";
-  const category = flags.category || "general";
-  const packageDir = path.join(registry, name, version);
-
-  if (await exists(packageDir)) {
-    throw new Error(`Skill already exists: ${packageDir}`);
+  if (!name && process.stdin.isTTY && process.stdout.isTTY) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      const sectionAnswer = await rl.question("Create which section? [skill/rule/domain] (skill): ");
+      section = normalizeSection(sectionAnswer || "skill");
+      name = (await rl.question(`${SECTION_SINGULAR[section]} name: `)).trim();
+      if (!flags.description) flags.description = (await rl.question("Description: ")).trim();
+    } finally {
+      rl.close();
+    }
   }
+  if (!name) throw new Error("Name is required. Example: skillhub create skill frontend-app");
 
-  await ensureDir(path.join(packageDir, "rules"));
-  await ensureDir(path.join(packageDir, "checklist"));
+  const config = (await readJson(path.join(projectRoot, CONFIG_FILE), null)) || defaultConfig(projectRoot);
+  const registry = resolveRegistry(projectRoot, config, flags, { fallbackToBundled: false });
+  if (registry.startsWith("http://") || registry.startsWith("https://")) throw new Error("Cannot create inside a remote registry. Use --registry ./skillhub-registry");
 
-  await writeJson(path.join(packageDir, "skill.json"), {
-    name,
-    version,
-    description: flags.description || `Reusable ${name} project skill`,
-    category,
-    tags: [category],
-    entry: "SKILL.md",
-    compatibleWith: ["cursor", "claude", "chatgpt", "github-copilot"],
-  });
+  const version = flags.version || "1.0.0";
+  const description = flags.description || `Reusable ${SECTION_SINGULAR[section]} for ${titleFromName(name)}`;
+  const sectionDir = path.join(registry, section);
+
+  if (section === "skills") {
+    const packageDir = path.join(sectionDir, name);
+    if (await exists(packageDir)) throw new Error(`Skill already exists: ${packageDir}`);
+    await ensureDir(path.join(packageDir, "templates"));
+    await writeJson(path.join(packageDir, "skill.json"), {
+      name,
+      version,
+      type: "skill",
+      section: "skills",
+      description,
+      category: flags.category || "development",
+      tags: (flags.tags ? String(flags.tags).split(",") : ["ai", "development"]).map((item) => item.trim()).filter(Boolean),
+      entry: "SKILL.md",
+      compatibleWith: ["cursor", "claude", "codex", "gemini", "opencode"],
+    });
+    await fs.writeFile(path.join(packageDir, "SKILL.md"), `# ${titleFromName(name)}\n\n## Description\n\n${description}\n\n## When to Use\n\nUse this skill when the user asks for ${titleFromName(name).toLowerCase()} work.\n\n## Workflow\n\n1. Understand the requirement and constraints.\n2. Inspect the existing project structure before changing code.\n3. Propose the smallest safe implementation plan.\n4. Implement using project conventions.\n5. Validate with build, lint, tests, or manual checks.\n\n## Rules\n\n- Follow installed project rules first.\n- Use installed domain knowledge when relevant.\n- Do not invent APIs, paths, or product behavior.\n- Keep changes scoped to the user request.\n\n## Output\n\nExplain changed files, validation performed, and any remaining risks.\n`, "utf8");
+    ok(`Created skill ${name}@${version}`);
+    info(`Location: ${packageDir}`);
+    return;
+  }
 
-  await fs.writeFile(
-    path.join(packageDir, "SKILL.md"),
-    `# ${name}\n\n## Purpose\n\nDescribe when this skill should be used.\n\n## Rules\n\n1. Add your first rule.\n2. Add examples and edge cases.\n3. Keep outputs consistent across projects.\n\n## Definition of Done\n\n- Requirements are clear\n- Implementation follows project standards\n- Tests or validation steps are documented\n`,
-    "utf8",
-  );
+  await ensureDir(sectionDir);
+  const fileName = `${name}.md`;
+  const targetPath = path.join(sectionDir, fileName);
+  if (await exists(targetPath)) throw new Error(`${SECTION_SINGULAR[section]} already exists: ${targetPath}`);
+  const heading = section === "rules" ? `${titleFromName(name)} Rules` : `${titleFromName(name)} Domain Knowledge`;
+  const body = flags.content || `# ${heading}\n\n## Purpose\n\n${description}\n\n## Guidance\n\n- Add concrete project knowledge here.\n- Include examples, naming conventions, edge cases, and decision rules.\n- Keep this file factual and maintainable.\n`;
+  await fs.writeFile(targetPath, body, "utf8");
+  ok(`Created ${SECTION_SINGULAR[section]} ${name}@${version}`);
+  info(`Location: ${targetPath}`);
+}
 
-  await fs.writeFile(path.join(packageDir, "rules/main.md"), `# ${name} Rules\n\n- Add project-specific rules here.\n`, "utf8");
-  await fs.writeFile(path.join(packageDir, "checklist/definition-of-done.md"), `# Definition of Done\n\n- [ ] Rules followed\n- [ ] Code reviewed\n- [ ] Edge cases checked\n`, "utf8");
+async function commandValidate(projectRoot, positional, flags = {}) {
+  let section = flags.type || flags.section || "skills";
+  let spec = positional[0];
+  if (positional.length >= 2 && SECTION_ALIASES[positional[0]]) {
+    section = positional[0];
+    spec = positional[1];
+  }
+  section = normalizeSection(section);
+  if (!spec) throw new Error(`${SECTION_SINGULAR[section]} name or path is required.`);
+
+  let artifact;
+  if (spec.includes("/") || spec.includes("\\") || spec.startsWith(".")) {
+    const packagePath = path.resolve(projectRoot, spec);
+    if ((await fs.stat(packagePath)).isFile()) {
+      const entryName = section === "skills" ? "SKILL.md" : section === "rules" ? "RULE.md" : "DOMAIN.md";
+      const files = [{ path: entryName, content: await fs.readFile(packagePath, "utf8") }];
+      artifact = { manifest: defaultManifest(section, path.basename(packagePath, path.extname(packagePath)), "1.0.0", files), files };
+    } else {
+      const files = await readPackageFiles(packagePath);
+      artifact = { manifest: defaultManifest(section, path.basename(packagePath), "1.0.0", files), files };
+    }
+  } else {
+    const config = await readProjectConfig(projectRoot);
+    const registry = resolveRegistry(projectRoot, config, flags);
+    const { name, version } = parseArtifactSpec(spec);
+    artifact = await loadArtifact(registry, section, name, version);
+  }
 
-  ok(`Created ${name}@${version}`);
-  info(`Location: ${packageDir}`);
+  validateArtifactManifest(section, artifact.manifest, artifact.files);
+  ok(`Valid ${SECTION_SINGULAR[section]}: ${artifact.manifest.name}@${artifact.manifest.version}`);
+  info(`Files: ${artifact.files.length}`);
+  info(`Checksum: ${checksumFiles(artifact.files)}`);
 }
 
-async function commandValidate(projectRoot, specOrPath, flags = {}) {
-  if (!specOrPath) throw new Error("Skill name or path is required.");
+async function collectRegistryNames(sectionDir, section) {
+  if (!(await exists(sectionDir))) return [];
+  const files = await listFiles(sectionDir);
+  const names = new Set();
 
-  let skill;
-  if (specOrPath.includes("/") || specOrPath.includes("\\") || specOrPath.startsWith(".")) {
-    const packageDir = path.resolve(projectRoot, specOrPath);
-    const manifest = await readJson(path.join(packageDir, "skill.json"));
-    const files = await readSkillPackageFiles(packageDir);
-    validateSkillManifest(manifest, files);
-    skill = { manifest, files };
+  if (section === "skills") {
+    for (const file of files) {
+      if (file.endsWith("/SKILL.md") || file === "SKILL.md") {
+        names.add(normalizeSlashes(path.dirname(file)));
+      }
+      if (file.endsWith("/skill.json") || file === "skill.json") {
+        names.add(normalizeSlashes(path.dirname(file)));
+      }
+    }
   } else {
-    const config = await readProjectConfig(projectRoot);
-    const registry = resolveRegistry(projectRoot, config, flags);
-    const { name, version } = parseSkillSpec(specOrPath);
-    skill = await loadSkill(registry, name, version);
+    for (const file of files) {
+      if (file.toLowerCase().endsWith(".md")) {
+        names.add(file.replace(/\.md$/i, ""));
+      }
+    }
   }
 
-  const checksum = checksumFiles(skill.files);
-  ok(`Valid skill: ${skill.manifest.name}@${skill.manifest.version}`);
-  info(`Files: ${skill.files.length}`);
-  info(`Checksum: ${checksum}`);
+  return [...names].filter((name) => name && name !== ".").sort();
+}
+
+async function commandSearch(projectRoot, query, flags = {}) {
+  const config = (await readJson(path.join(projectRoot, CONFIG_FILE), null)) || defaultConfig(projectRoot);
+  const registry = resolveRegistry(projectRoot, config, flags);
+  if (registry.startsWith("http://") || registry.startsWith("https://")) throw new Error("Remote search is not supported in this CLI build yet. Use your web app search UI, then fetch by path with skillhub rule/skill/domain.");
+  const needle = String(query || "").toLowerCase();
+
+  console.log(paint("bold", "SkillHub registry"));
+  for (const section of ["skills", "rules", "domain"]) {
+    const sectionDir = path.join(registry, section);
+    const names = (await collectRegistryNames(sectionDir, section))
+      .filter((name) => !needle || name.toLowerCase().includes(needle));
+    if (names.length === 0) continue;
+    console.log(`\n${paint("bold", section)}`);
+    for (const name of names) console.log(`- ${name}`);
+  }
 }
 
 function toWords(value) {
@@ -747,34 +1107,25 @@ function toWords(value) {
 }
 
 function toKebabCase(value) {
-  return toWords(value)
-    .map((word) => word.toLowerCase())
-    .join("-");
+  return toWords(value).map((word) => word.toLowerCase()).join("-");
 }
 
 function toCamelCase(value) {
   const words = toWords(value).map((word) => word.toLowerCase());
-  return words
-    .map((word, index) => (index === 0 ? word : `${word.charAt(0).toUpperCase()}${word.slice(1)}`))
-    .join("");
+  return words.map((word, index) => (index === 0 ? word : `${word.charAt(0).toUpperCase()}${word.slice(1)}`)).join("");
 }
 
 function toPascalCase(value) {
-  return toWords(value)
-    .map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1).toLowerCase()}`)
-    .join("");
+  return toWords(value).map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1).toLowerCase()}`).join("");
 }
 
 function toTitleCase(value) {
-  return toWords(value)
-    .map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1).toLowerCase()}`)
-    .join(" ");
+  return toWords(value).map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1).toLowerCase()}`).join(" ");
 }
 
 function templateVariables(name, flags = {}) {
   const baseName = name || flags.name;
-  if (!baseName) throw new Error("Generator name is required. Example: skillhub generate shadcn-crud-generator feature users");
-
+  if (!baseName) throw new Error("Generator name is required. Example: skillhub generate frontend-app feature users");
   return {
     name: baseName,
     kebabName: flags.kebabName || toKebabCase(baseName),
@@ -793,12 +1144,8 @@ async function commandGenerate(projectRoot, skillName, templateName, resourceNam
   if (!templateName) throw new Error("Template name is required.");
 
   const config = await readProjectConfig(projectRoot);
-  const skillsDir = config.skillsDir || DEFAULT_SKILLS_DIR;
-  const templateDir = path.join(projectRoot, skillsDir, skillName, "templates", templateName);
-
-  if (!(await exists(templateDir))) {
-    throw new Error(`Template not found: ${skillsDir}/${skillName}/templates/${templateName}. Install the skill first.`);
-  }
+  const templateDir = path.join(projectRoot, config.sections.skills, skillName, "templates", templateName);
+  if (!(await exists(templateDir))) throw new Error(`Template not found: ${config.sections.skills}/${skillName}/templates/${templateName}. Attach the skill first.`);
 
   const variables = templateVariables(resourceName || flags.name, flags);
   const outDir = path.resolve(projectRoot, flags.out || `src/features/${variables.kebabName}`);
@@ -814,21 +1161,16 @@ async function commandGenerate(projectRoot, skillName, templateName, resourceNam
     const targetPath = safeJoin(outDir, renderedRelativePath);
     const sourcePath = path.join(templateDir, relativePath);
     const content = await fs.readFile(sourcePath, "utf8");
-
-    if ((await exists(targetPath)) && !flags.force) {
-      throw new Error(`File already exists: ${targetPath}. Use --force to overwrite.`);
-    }
-
+    if ((await exists(targetPath)) && !flags.force) throw new Error(`File already exists: ${targetPath}. Use --force to overwrite.`);
     await ensureDir(path.dirname(targetPath));
     await fs.writeFile(targetPath, renderTemplate(content, variables), "utf8");
     ok(`Generated ${normalizeSlashes(path.relative(projectRoot, targetPath))}`);
   }
-
   info(`Template variables: ${JSON.stringify(variables)}`);
 }
 
 function printHelp() {
-  console.log(`\n${paint("bold", "SkillHub CLI")}\n\nInstall reusable AI/project skills into any codebase.\n\n${paint("bold", "Usage")}\n  skillhub <command> [options]\n\n${paint("bold", "Commands")}\n  init                         Create skillhub.json, lockfile, and chosen skills folder\n  target [ai|cursor|claude]    Change where skills are installed\n  install <skill[@version]>    Install a skill from the registry\n  sync                         Reinstall all skills from skillhub.json\n  list                         Show installed skills\n  remove <skill>               Remove an installed skill\n  create <skill>               Scaffold a new local skill package\n  validate <skill|path>        Validate skill.json and SKILL.md\n  generate <skill> <template> <name>  Generate files from a skill template\n\n${paint("bold", "Targets")}\n  ai                            Install to .ai/skills and update AGENTS.md\n  cursor                        Install to .cursor/skills and update .cursor/rules/skillhub.mdc\n  claude                        Install to .claude/skills and update CLAUDE.md + .claude/skillhub.md\n\n${paint("bold", "Options")}\n  --target <ai|cursor|claude>   Install target. Alias: --to\n  --registry <path|url>         Registry location. Default: ./skillhub-registry\n  --version <version>           Version used by create. Default: 1.0.0\n  --category <name>             Category used by create. Default: general\n  --yes                         Use default init target without prompting\n\n${paint("bold", "Examples")}\n  skillhub init --target cursor\n  skillhub init --target claude\n  skillhub install nextjs-clean-architecture --target cursor\n  skillhub target claude\n  skillhub sync\n  skillhub create api-security-rules --category security\n`);
+  console.log(`\n${paint("bold", "SkillHub CLI")}\n\nFetch SkillHub web-app knowledge into any codebase: skills, rules, and domain knowledge.\n\n${paint("bold", "Usage")}\n  skillhub <command> [options]\n\n${paint("bold", "Commands")}\n  init                              Create skillhub.json and target folders\n  target [ai|cursor|claude]         Change where knowledge is attached\n  attach <skill|rule|domain> <name> Attach a registry item to this project\n  install <name>                    Attach a skill. Alias for attach skill <name>\n  install <rule|domain> <name>      Attach rule/domain using install syntax\n  sync                              Reinstall all configured knowledge\n  list                              Show attached knowledge\n  remove [section] <name>           Remove attached knowledge\n  create [skill|rule|domain] <name> Create a local registry item\n  validate [section] <name|path>    Validate registry item\n  search [query]                    Search local/bundled registry\n  generate <skill> <template> <name> Generate files from an attached skill template\n\n${paint("bold", "Targets")}\n  ai       .ai/skills, .ai/rules, .ai/domain + AGENTS.md\n  cursor   .cursor/skills, .cursor/rules, .cursor/domain + .cursor/rules/skillhub.md\n  claude   .claude/skills, .claude/rules, .claude/domain + CLAUDE.md\n\n${paint("bold", "Options")}\n  --target <ai|cursor|claude>        Install target. Alias: --to\n  --registry <path|url>              Registry location. Default: ./skillhub-registry; falls back to bundled registry\n  --type <skill|rule|domain>         Section for install/validate\n  --version <version>                Version used by create. Default: 1.0.0\n  --description <text>               Description used by create\n  --category <name>                  Category used by create skill\n  --tags <a,b,c>                     Tags used by create skill\n  --yes                              Use default init target without prompting\n\n${paint("bold", "Examples")}\n  skillhub init --target cursor\n  skillhub attach skill frontend-app\n  skillhub attach rule code-standards\n  skillhub attach domain frontend-architecture\n  skillhub install frontend-app --target claude\n  skillhub create skill frontend-app --description "Develop production frontend apps"\n  skillhub create rule react-query-rules\n  skillhub create domain ott-video-cms\n  skillhub search react\n`);
 }
 
 async function main() {
@@ -845,9 +1187,22 @@ async function main() {
     case "init":
       await commandInit(projectRoot, flags);
       break;
+    case "attach":
+    case "use":
+      await commandAttach(projectRoot, positional[0], positional[1], flags);
+      break;
+    case "skill":
+    case "skills":
+    case "rule":
+    case "rules":
+    case "domain":
+    case "domains":
+    case "knowledge":
+      await commandAttach(projectRoot, command, positional[0], flags);
+      break;
     case "install":
     case "add":
-      await commandInstall(projectRoot, positional[0], flags);
+      await commandInstall(projectRoot, positional, flags);
       break;
     case "target":
     case "configure":
@@ -862,13 +1217,16 @@ async function main() {
       break;
     case "remove":
     case "rm":
-      await commandRemove(projectRoot, positional[0]);
+      await commandRemove(projectRoot, positional[0], positional[1]);
       break;
     case "create":
-      await commandCreate(projectRoot, positional[0], flags);
+      await commandCreate(projectRoot, positional, flags);
       break;
     case "validate":
-      await commandValidate(projectRoot, positional[0], flags);
+      await commandValidate(projectRoot, positional, flags);
+      break;
+    case "search":
+      await commandSearch(projectRoot, positional[0], flags);
       break;
     case "generate":
     case "gen":
@@ -885,13 +1243,12 @@ main().catch((error) => {
 });
 
 export {
-  parseSkillSpec,
+  normalizeTarget,
+  normalizeSection,
+  parseArtifactSpec,
   checksumFiles,
   sortVersions,
-  validateSkillManifest,
+  validateArtifactManifest,
   defaultConfig,
-  normalizeTarget,
   applyTargetToConfig,
 };
-
-// Let people run this file through `node packages/skillhub-cli/bin/skillhub.mjs`.