@mhmdreza-rafiei/agentry 0.2.2 → 0.3.1

package/dist/_chunks/discovery.mjs

@@ -0,0 +1,614 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, join, relative, resolve, sep } from "node:path";
+import { xdgCache } from "xdg-basedir";
+function isLocalPath(source) {
+	if (!source) return false;
+	if (source === "." || source === "..") return true;
+	if (source.startsWith("./") || source.startsWith("../") || source.startsWith("/") || source.startsWith("~")) return true;
+	try {
+		return existsSync(source) && statSync(source).isDirectory();
+	} catch {
+		return false;
+	}
+}
+const SAFE_REF$1 = /^[a-zA-Z0-9][\w./-]*$/;
+function parseGithubTreeUrl(url) {
+	const m = url.match(/^https?:\/\/github\.com\/([\w.-]+\/[\w.-]+?)\/tree\/([^/]+)\/(.+)$/);
+	if (!m) return null;
+	const ref = m[2];
+	if (!SAFE_REF$1.test(ref)) throw new Error(`Invalid git ref in source URL: "${ref}"`);
+	return {
+		ownerRepo: m[1],
+		ref,
+		subpath: m[3].replace(/\/+$/, "")
+	};
+}
+function redactUrl(url) {
+	return url.replace(/:\/\/([^/@]+)@/g, "://***@");
+}
+function parseSource(source) {
+	if (!source || typeof source !== "string") throw new Error("Empty source.");
+	const raw = source;
+	if (isLocalPath(source)) return {
+		kind: "local",
+		raw,
+		url: null,
+		subpath: "",
+		local: resolve(source.replace(/^~/, homedir()))
+	};
+	const tree = parseGithubTreeUrl(source);
+	if (tree) return {
+		kind: "github-url",
+		raw,
+		url: `https://github.com/${tree.ownerRepo}.git`,
+		subpath: tree.subpath,
+		ref: tree.ref,
+		local: null
+	};
+	let m = source.match(/^https?:\/\/github\.com\/([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/);
+	if (m) return {
+		kind: "github-url",
+		raw,
+		url: `https://github.com/${m[1]}.git`,
+		subpath: "",
+		local: null
+	};
+	m = source.match(/^https?:\/\/gitlab\.com\/([\w./-]+?)(?:\.git)?\/?$/);
+	if (m) return {
+		kind: "gitlab-url",
+		raw,
+		url: `https://gitlab.com/${m[1]}.git`,
+		subpath: "",
+		local: null
+	};
+	if (source.startsWith("git@") || /^https?:\/\/.*\.git$/.test(source)) return {
+		kind: "git-url",
+		raw,
+		url: source,
+		subpath: "",
+		local: null
+	};
+	if (/^[\w.-]+\/[\w.-]+$/.test(source)) return {
+		kind: "github-shorthand",
+		raw,
+		url: `https://github.com/${source}.git`,
+		subpath: "",
+		local: null
+	};
+	if (/^https?:\/\//i.test(source)) return {
+		kind: "web-url",
+		raw,
+		url: source,
+		subpath: "",
+		local: null
+	};
+	throw new Error(`Cannot parse source "${source}". Use author/repo, a GitHub/GitLab URL, a git URL, a skill website URL, or a local path.`);
+}
+function sourceIdentity(source) {
+	try {
+		const p = parseSource(source);
+		if (p.kind === "local" && p.local) return `local:${resolve(p.local).replace(/\\/g, "/").toLowerCase()}`;
+		if (p.kind === "web-url") return `web:${(p.url || "").toLowerCase()}`;
+		return `git:${(p.url || "").replace(/\.git$/i, "").replace(/\/+$/, "").toLowerCase()}${p.subpath ? `/${p.subpath.replace(/^\/+|\/+$/g, "")}` : ""}${p.ref ? `@${p.ref}` : ""}`;
+	} catch {
+		return `raw:${source.trim().toLowerCase()}`;
+	}
+}
+function sourcesEqual(a, b) {
+	if (!a || !b) return false;
+	if (a === b) return true;
+	return sourceIdentity(a) === sourceIdentity(b);
+}
+function isExplicitSource(arg) {
+	if (!arg) return false;
+	if (isLocalPath(arg)) return true;
+	if (/^https?:\/\//i.test(arg)) return true;
+	if (arg.startsWith("git@")) return true;
+	if (/^https?:\/\/.*\.git$/i.test(arg)) return true;
+	return false;
+}
+function isOwnerRepoShape(arg) {
+	return /^[\w.-]+\/[\w.-]+$/.test(arg);
+}
+function cacheRoot() {
+	return join(xdgCache ?? join(homedir(), ".cache"), "agentry", "repos");
+}
+function cacheKey(parsed) {
+	const id = sourceIdentity(parsed.raw);
+	return createHash("sha256").update(id).digest("hex").slice(0, 20);
+}
+function cacheDirFor(parsed) {
+	return join(cacheRoot(), cacheKey(parsed));
+}
+function saveToCache(parsed, clonedRoot) {
+	const dest = cacheDirFor(parsed);
+	try {
+		rmSync(dest, {
+			recursive: true,
+			force: true
+		});
+		mkdirSync(join(dest, ".."), { recursive: true });
+		cpSync(clonedRoot, dest, { recursive: true });
+	} catch {}
+}
+const SAFE_REF = /^[a-zA-Z0-9][\w./-]*$/;
+function cloneTo(url, dest, ref) {
+	if (ref && !SAFE_REF.test(ref)) throw new Error(`Invalid git ref: "${ref}"`);
+	execFileSync("git", [
+		"clone",
+		"--quiet",
+		...ref ? [
+			"--branch",
+			ref,
+			"--depth",
+			"1"
+		] : ["--depth", "1"],
+		url,
+		dest
+	], { stdio: [
+		"ignore",
+		"ignore",
+		"pipe"
+	] });
+}
+function assertInsideRoot(root, candidate) {
+	const base = resolve(root);
+	const resolved = resolve(candidate);
+	const prefix = base.endsWith(sep) ? base : base + sep;
+	const a = resolved.toLowerCase();
+	const b = base.toLowerCase();
+	const p = prefix.toLowerCase();
+	if (a !== b && !a.startsWith(p)) throw new Error(`Path escapes source root: "${candidate}"`);
+	return resolved;
+}
+function withSubpath(root, subpath, cleanupRoot) {
+	const cleanup = () => rmSync(cleanupRoot, {
+		recursive: true,
+		force: true
+	});
+	if (!subpath) return {
+		root,
+		cleanup
+	};
+	let sub;
+	try {
+		sub = assertInsideRoot(root, join(root, subpath));
+	} catch (e) {
+		cleanup();
+		throw e;
+	}
+	if (!existsSync(sub)) {
+		cleanup();
+		throw new Error(`Subpath "${subpath}" not found.`);
+	}
+	return {
+		root: sub,
+		cleanup
+	};
+}
+async function resolveSource(source, opts = {}) {
+	const parsed = typeof source === "string" ? parseSource(source) : source;
+	if (parsed.kind === "local" && parsed.local) {
+		if (!existsSync(parsed.local)) throw new Error(`Path not found: ${parsed.raw}`);
+		return {
+			root: parsed.local,
+			cleanup: () => {}
+		};
+	}
+	if (parsed.kind === "web-url" && parsed.url) {
+		const { resolveWebSource } = await import("./web.mjs");
+		return resolveWebSource(parsed.url, opts);
+	}
+	const url = parsed.url;
+	if (!url) throw new Error(`Cannot resolve source "${parsed.raw}".`);
+	const safeUrl = redactUrl(url);
+	const tmp = mkdtempSync(join(tmpdir(), "agentry-src-"));
+	try {
+		cloneTo(url, tmp, parsed.ref);
+	} catch (e) {
+		rmSync(tmp, {
+			recursive: true,
+			force: true
+		});
+		const detail = e.stderr ? e.stderr.toString().trim() : e.message;
+		const cached = cacheDirFor(parsed);
+		const cacheOk = existsSync(cached) && existsSync(join(cached, ".git"));
+		if (cacheOk && opts.confirmCache) {
+			if (await opts.confirmCache({
+				url: safeUrl,
+				cacheDir: cached,
+				error: detail
+			})) {
+				const work = mkdtempSync(join(tmpdir(), "agentry-src-"));
+				cpSync(cached, work, { recursive: true });
+				return {
+					...withSubpath(work, parsed.subpath, work),
+					fromCache: true
+				};
+			}
+		}
+		throw new Error(`git clone failed for ${safeUrl}\n${detail}${cacheOk ? "\n(A local cache exists — re-run interactively to load it, or pass -y to auto-use cache.)" : ""}`);
+	}
+	saveToCache(parsed, tmp);
+	return withSubpath(tmp, parsed.subpath, tmp);
+}
+const DEFAULT_IGNORES = [
+	".git",
+	".github",
+	"node_modules",
+	".agents",
+	".agentry",
+	".cursor",
+	".claude",
+	".vscode",
+	"dist",
+	"build",
+	".DS_Store"
+];
+function parseIgnorePattern(pattern) {
+	const trimmed = pattern.trim();
+	if (!trimmed || trimmed.startsWith("#")) return null;
+	const isDirOnly = trimmed.endsWith("/");
+	let p = isDirOnly ? trimmed.slice(0, -1) : trimmed;
+	const isRootAnchored = p.startsWith("/");
+	if (isRootAnchored) p = p.slice(1);
+	let regexStr = "";
+	for (let i = 0; i < p.length; i++) {
+		const char = p[i];
+		if (char === "*") if (p[i + 1] === "*") {
+			regexStr += ".*";
+			i++;
+			if (p[i + 1] === "/") i++;
+		} else regexStr += "[^/]*";
+		else if (char === "?") regexStr += "[^/]";
+		else if ([
+			".",
+			"+",
+			"^",
+			"$",
+			"{",
+			"}",
+			"(",
+			")",
+			"|",
+			"[",
+			"]",
+			"\\"
+		].includes(char)) regexStr += "\\" + char;
+		else regexStr += char;
+	}
+	let regex;
+	if (isRootAnchored) regex = new RegExp(`^${regexStr}(/.*)?$`, "i");
+	else if (p.includes("/")) regex = new RegExp(`(^|/)${regexStr}(/.*)?$`, "i");
+	else regex = new RegExp(`(^|/)${regexStr}($|/)`, "i");
+	return {
+		raw: trimmed,
+		isDirOnly,
+		regex
+	};
+}
+function parseIgnoreFile(content) {
+	return content.split(/\r?\n/).map((line) => parseIgnorePattern(line)).filter((r) => r !== null);
+}
+function loadIgnoreRules(root) {
+	const candidates = [".agentryignore", ".agentry.ignore"];
+	const rules = [];
+	for (const name of candidates) {
+		const file = join(root, name);
+		if (existsSync(file)) try {
+			const text = readFileSync(file, "utf8");
+			rules.push(...parseIgnoreFile(text));
+		} catch {}
+	}
+	return rules;
+}
+function isDefaultIgnored(relPath) {
+	return relPath.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "").split("/").some((s) => DEFAULT_IGNORES.includes(s));
+}
+function createIgnoreMatcher(root) {
+	const fileRules = loadIgnoreRules(root);
+	return (relPath, isDirectory = false) => {
+		if (!relPath || relPath === "." || relPath === "./") return false;
+		const normalized = relPath.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+		if (!normalized) return false;
+		if (isDefaultIgnored(normalized)) return true;
+		for (const rule of fileRules) {
+			if (rule.isDirOnly && !isDirectory) {
+				if (rule.regex.test(normalized + "/")) return true;
+				continue;
+			}
+			if (rule.regex.test(normalized)) return true;
+		}
+		return false;
+	};
+}
+const SKILL_MARKER = "SKILL.md";
+const AGENT_MARKER = "AGENT.md";
+const RULE_MARKER = "RULE.md";
+const CURSORRULES_MARKER = ".cursorrules";
+const FILE_EXT = ".mdc";
+const PROFILE_EXTS = [".yaml", ".yml"];
+const KIND_DIRS = {
+	skill: "skills",
+	rule: "rules",
+	agent: "agents",
+	profile: "profiles",
+	script: "scripts"
+};
+const ROOT_SKIP = /* @__PURE__ */ new Set([
+	".",
+	"node_modules",
+	"skills",
+	"rules",
+	"agents",
+	"profiles",
+	"scripts"
+]);
+function entries(dir) {
+	try {
+		return readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+}
+function firstHeading(md) {
+	const m = md.match(/^#\s+(.+)$/m);
+	return m ? m[1].trim() : "";
+}
+function frontmatterName(md) {
+	const fm = md.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!fm) return "";
+	const m = fm[1].match(/^name:\s*(.+)$/m);
+	return m ? m[1].trim().replace(/^['"]|['"]$/g, "") : "";
+}
+function frontmatterDescription(md) {
+	const fm = md.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!fm) return "";
+	const lines = fm[1].split(/\r?\n/);
+	for (let i = 0; i < lines.length; i++) {
+		const dm = lines[i].match(/^description:\s*(.*)$/);
+		if (!dm) continue;
+		let val = dm[1].trim();
+		if (val === "" || val === ">" || val === "|" || val === ">-" || val === "|-") {
+			const collected = [];
+			for (let j = i + 1; j < lines.length; j++) if (/^\s+\S/.test(lines[j])) collected.push(lines[j].trim());
+			else break;
+			val = collected.join(" ");
+		}
+		return val.trim();
+	}
+	return "";
+}
+function readDescription(filePath) {
+	try {
+		const md = readFileSync(filePath, "utf8");
+		return frontmatterDescription(md) || firstHeading(md);
+	} catch {
+		return "";
+	}
+}
+function folderDescription(dir) {
+	for (const f of [SKILL_MARKER, "README.md"]) {
+		const p = join(dir, f);
+		if (existsSync(p)) {
+			const d = readDescription(p);
+			if (d) return d;
+		}
+	}
+	return "";
+}
+function makeArtifact(kind, category, name, srcPath, isFile) {
+	return {
+		kind,
+		category,
+		name,
+		id: category ? `${category}/${name}` : name,
+		dir: srcPath,
+		isFile,
+		description: isFile ? readDescription(srcPath) : folderDescription(srcPath)
+	};
+}
+function rel(root, fullPath) {
+	return relative(root, fullPath).replace(/\\/g, "/");
+}
+function collectSkills(root, base, out, matcher) {
+	for (const child of entries(base)) {
+		if (!child.isDirectory()) continue;
+		const childDir = join(base, child.name);
+		if (matcher(rel(root, childDir), true)) continue;
+		if (existsSync(join(childDir, SKILL_MARKER))) out.push(makeArtifact("skill", null, child.name, childDir, false));
+		else for (const item of entries(childDir)) {
+			if (!item.isDirectory()) continue;
+			const itemDir = join(childDir, item.name);
+			if (matcher(rel(root, itemDir), true)) continue;
+			if (existsSync(join(itemDir, SKILL_MARKER))) out.push(makeArtifact("skill", child.name, item.name, itemDir, false));
+		}
+	}
+}
+function collectMdc(root, kind, base, out, matcher) {
+	for (const child of entries(base)) {
+		const childPath = join(base, child.name);
+		if (child.isFile() && child.name.endsWith(FILE_EXT)) {
+			if (matcher(rel(root, childPath), false)) continue;
+			out.push(makeArtifact(kind, null, child.name.slice(0, -4), childPath, true));
+		} else if (child.isDirectory()) {
+			if (matcher(rel(root, childPath), true)) continue;
+			for (const item of entries(childPath)) {
+				const itemPath = join(childPath, item.name);
+				if (item.isFile() && item.name.endsWith(FILE_EXT)) {
+					if (matcher(rel(root, itemPath), false)) continue;
+					out.push(makeArtifact(kind, child.name, item.name.slice(0, -4), itemPath, true));
+				}
+			}
+		}
+	}
+}
+function collectProfiles(root, base, out, matcher) {
+	for (const child of entries(base)) {
+		const childPath = join(base, child.name);
+		if (child.isFile() && PROFILE_EXTS.some((e) => child.name.endsWith(e))) {
+			if (matcher(rel(root, childPath), false)) continue;
+			const stem = child.name.replace(/\.(yaml|yml)$/, "");
+			out.push(makeArtifact("profile", null, stem, childPath, true));
+		} else if (child.isDirectory()) {
+			if (matcher(rel(root, childPath), true)) continue;
+			for (const item of entries(childPath)) {
+				const itemPath = join(childPath, item.name);
+				if (item.isFile() && PROFILE_EXTS.some((e) => item.name.endsWith(e))) {
+					if (matcher(rel(root, itemPath), false)) continue;
+					const stem = item.name.replace(/\.(yaml|yml)$/, "");
+					out.push(makeArtifact("profile", child.name, stem, itemPath, true));
+				}
+			}
+		}
+	}
+}
+function collectScripts(root, base, out, matcher) {
+	for (const child of entries(base)) {
+		if (!child.isDirectory()) continue;
+		const childDir = join(base, child.name);
+		if (matcher(rel(root, childDir), true)) continue;
+		if (entries(childDir).some((e) => e.isFile())) out.push(makeArtifact("script", null, child.name, childDir, false));
+		else for (const item of entries(childDir)) {
+			const itemDir = join(childDir, item.name);
+			if (!item.isDirectory() || matcher(rel(root, itemDir), true)) continue;
+			if (entries(itemDir).some((e) => e.isFile())) out.push(makeArtifact("script", child.name, item.name, join(childDir, item.name), false));
+		}
+	}
+}
+function collectRootSkills(root, out, matcher) {
+	const rootSkillFile = join(root, SKILL_MARKER);
+	if (existsSync(rootSkillFile) && !matcher(SKILL_MARKER, false)) {
+		let name = "";
+		try {
+			name = frontmatterName(readFileSync(rootSkillFile, "utf8"));
+		} catch {}
+		if (!name) name = basename(root) || "skill";
+		out.push(makeArtifact("skill", null, name, root, false));
+	}
+	for (const child of entries(root)) {
+		if (!child.isDirectory() || child.name.startsWith(".") || ROOT_SKIP.has(child.name)) continue;
+		const childDir = join(root, child.name);
+		if (matcher(child.name, true)) continue;
+		if (existsSync(join(childDir, SKILL_MARKER))) out.push(makeArtifact("skill", null, child.name, childDir, false));
+		else for (const item of entries(childDir)) {
+			if (!item.isDirectory()) continue;
+			const itemDir = join(childDir, item.name);
+			if (matcher(rel(root, itemDir), true)) continue;
+			if (existsSync(join(itemDir, SKILL_MARKER))) out.push(makeArtifact("skill", child.name, item.name, itemDir, false));
+		}
+	}
+}
+function collectRootMdc(kind, root, out, matcher) {
+	if (kind === "agent") {
+		const rootAgent = join(root, AGENT_MARKER);
+		if (existsSync(rootAgent) && !matcher(AGENT_MARKER, false)) {
+			let name = "";
+			try {
+				name = frontmatterName(readFileSync(rootAgent, "utf8"));
+			} catch {}
+			out.push(makeArtifact("agent", null, name || "agent", rootAgent, true));
+		}
+	}
+	if (kind === "rule") {
+		const rootRule = join(root, RULE_MARKER);
+		if (existsSync(rootRule) && !matcher(RULE_MARKER, false)) {
+			let name = "";
+			try {
+				name = frontmatterName(readFileSync(rootRule, "utf8"));
+			} catch {}
+			out.push(makeArtifact("rule", null, name || "rule", rootRule, true));
+		}
+		const cursorRules = join(root, CURSORRULES_MARKER);
+		if (existsSync(cursorRules) && !matcher(CURSORRULES_MARKER, false)) out.push(makeArtifact("rule", null, "cursorrules", cursorRules, true));
+	}
+	for (const child of entries(root)) {
+		const childPath = join(root, child.name);
+		if (child.isFile() && child.name.endsWith(FILE_EXT) && !child.name.startsWith(".")) {
+			if (matcher(child.name, false)) continue;
+			out.push(makeArtifact(kind, null, child.name.slice(0, -4), childPath, true));
+		} else if (child.isDirectory() && !child.name.startsWith(".") && !ROOT_SKIP.has(child.name)) {
+			if (matcher(child.name, true)) continue;
+			for (const item of entries(childPath)) {
+				const itemPath = join(childPath, item.name);
+				if (item.isFile() && item.name.endsWith(FILE_EXT)) {
+					if (matcher(rel(root, itemPath), false)) continue;
+					out.push(makeArtifact(kind, child.name, item.name.slice(0, -4), itemPath, true));
+				}
+			}
+		}
+	}
+}
+function collectRootProfiles(root, out, matcher) {
+	const localProfileDir = join(root, "profile");
+	if (existsSync(localProfileDir) && !matcher("profile", true)) collectProfiles(root, localProfileDir, out, matcher);
+	for (const child of entries(root)) {
+		if (!child.isFile()) continue;
+		if (matcher(child.name, false)) continue;
+		const lower = child.name.toLowerCase();
+		if (lower === "profile.yaml" || lower === "profile.yml" || lower.endsWith(".profile.yaml") || lower.endsWith(".profile.yml")) {
+			const stem = child.name.replace(/\.(profile\.)?(yaml|yml)$/i, "");
+			out.push(makeArtifact("profile", null, stem, join(root, child.name), true));
+		}
+	}
+}
+function collectRootScripts(root, out, matcher) {
+	const localScriptDir = join(root, "script");
+	if (existsSync(localScriptDir) && !matcher("script", true)) collectScripts(root, localScriptDir, out, matcher);
+	if (!existsSync(join(root, SKILL_MARKER))) {
+		for (const sf of [
+			"run.sh",
+			"script.sh",
+			"run.js",
+			"main.py"
+		]) if (existsSync(join(root, sf)) && !matcher(sf, false)) {
+			const name = basename(root) || "script";
+			out.push(makeArtifact("script", null, name, root, false));
+			break;
+		}
+	}
+}
+function listKind(root, kind) {
+	const out = [];
+	const matcher = createIgnoreMatcher(root);
+	const base = join(root, KIND_DIRS[kind]);
+	if (existsSync(base) && !matcher(KIND_DIRS[kind], true)) if (kind === "skill") collectSkills(root, base, out, matcher);
+	else if (kind === "profile") collectProfiles(root, base, out, matcher);
+	else if (kind === "script") collectScripts(root, base, out, matcher);
+	else collectMdc(root, kind, base, out, matcher);
+	if (kind === "skill") collectRootSkills(root, out, matcher);
+	else if (kind === "agent" || kind === "rule") collectRootMdc(kind, root, out, matcher);
+	else if (kind === "profile") collectRootProfiles(root, out, matcher);
+	else if (kind === "script") collectRootScripts(root, out, matcher);
+	const seen = /* @__PURE__ */ new Set();
+	return out.filter((a) => seen.has(a.id) ? false : seen.add(a.id)).sort((a, b) => a.id.localeCompare(b.id));
+}
+function listAll(root) {
+	return [
+		"skill",
+		"rule",
+		"agent",
+		"profile",
+		"script"
+	].flatMap((k) => listKind(root, k));
+}
+function select(root, kind, selector) {
+	const items = listKind(root, kind);
+	if (!selector) return items;
+	if (selector.includes("/")) return items.filter((a) => a.id === selector);
+	const byCategory = items.filter((a) => a.category === selector);
+	if (byCategory.length) return byCategory;
+	return items.filter((a) => a.name === selector);
+}
+function selectAll(root, selector) {
+	const items = listAll(root);
+	if (!selector) return items;
+	if (selector.includes("/")) return items.filter((a) => a.id === selector);
+	const byCategory = items.filter((a) => a.category === selector);
+	if (byCategory.length) return byCategory;
+	return items.filter((a) => a.name === selector);
+}
+export { DEFAULT_IGNORES, createIgnoreMatcher, frontmatterName, isExplicitSource, isOwnerRepoShape, listAll, listKind, parseSource, resolveSource, select, selectAll, sourcesEqual };

package/dist/_chunks/theme2.mjs

@@ -85,34 +85,35 @@ function printHelp() {
 		`${badge()}  ${dim("install agents, skills, rules, scripts & profiles")}`,
 		"",
 		h("Usage"),
-		`  ${cmd("agentry")} ${flag("add")}     ${dim("<kind> <source> [selector] [options]")}`,
-		`  ${cmd("agentry")} ${flag("add")}     ${dim("profile <name> [source] [options]")}`,
-		`  ${cmd("agentry")} ${flag("remove")}  ${dim("<kind> [source] [selector] [options]")}`,
-		`  ${cmd("agentry")} ${flag("list")}    ${dim("[source] [kind] [selector]")}`,
-		`  ${cmd("agentry")} ${flag("update")}  ${dim("[kind] [source] [selector]")}`,
-		`  ${cmd("agentry")} ${flag("init")}    ${dim("<kind> [name] [category] [options]")}`,
+		`  ${cmd("agentry")} ${flag("add")}          ${dim("[kind] <source> [selector] [options]")}`,
+		`  ${cmd("agentry")} ${flag("add from")}     ${dim("<url> [selector] [options]")}`,
+		`  ${cmd("agentry")} ${flag("add")}          ${dim("profile <name> [source] [options]")}`,
+		`  ${cmd("agentry")} ${flag("remove")}       ${dim("[kind] [source] [selector] [options]")}`,
+		`  ${cmd("agentry")} ${flag("list")}         ${dim("[source] [kind] [selector]")}`,
+		`  ${cmd("agentry")} ${flag("update")}       ${dim("[kind] [source] [selector]")}`,
+		`  ${cmd("agentry")} ${flag("init")}         ${dim("<kind> [name] [category] [options]")}`,
 		`  ${cmd("agentry")} ${flag("uninstall")}`,
 		"",
 		h("Kinds"),
 		bullet(`${c.bold("skill")}  ${c.bold("rule")}  ${c.bold("agent")}  ${c.bold("profile")}  ${c.bold("script")}  ${dim("(or all)")}`),
-		dim("  Plurals accepted: skills → skill, agents → agent, …"),
+		dim("  Plurals accepted: skills → skill, agents → agent, … (optional on add/remove)"),
 		"",
 		h("Sources"),
 		bullet(`${cmd("author/repo")}              ${dim("GitHub shorthand")}`),
 		bullet(`${cmd("https://github.com/…")}     ${dim("GitHub URL or /tree/<ref>/<dir>")}`),
+		bullet(`${cmd("https://awesomeskill.ai/…")} ${dim("Skill directory/hub website")}`),
 		bullet(`${cmd("https://gitlab.com/…")}     ${dim("GitLab URL")}`),
 		bullet(`${cmd("git@host:owner/repo.git")}  ${dim("any git URL")}`),
 		bullet(`${cmd("./path")} ${dim("|")} ${cmd("/path")} ${dim("|")} ${cmd("~/path")}  ${dim("local directory")}`),
 		"",
 		h("Examples"),
-		bullet(`${cmd("agentry add skills")} mhmdreza-rafiei/agent-tools`),
+		bullet(`${cmd("agentry add")} mhmdreza-rafiei/agent-tools`),
+		bullet(`${cmd("agentry add from")} https://awesomeskill.ai/skill/vercel-labs-agent-skills-web-design-guidelines`),
 		bullet(`${cmd("agentry add skills")} mhmdreza-rafiei/agent-tools enhance-prompt ${flag("-a")} cursor`),
 		bullet(`${cmd("agentry list")}`),
 		bullet(`${cmd("agentry list skills")}`),
 		bullet(`${cmd("agentry list")} mhmdreza-rafiei/agent-tools`),
-		bullet(`${cmd("agentry list")} mhmdreza-rafiei/agent-tools skills`),
-		bullet(`${cmd("agentry list")} mhmdreza-rafiei/agent-tools skills enhance-prompt`),
-		bullet(`${cmd("agentry remove skills")} enhance-prompt`),
+		bullet(`${cmd("agentry remove")} enhance-prompt`),
 		bullet(`${cmd("agentry remove skills")} mhmdreza-rafiei/agent-tools`),
 		bullet(`${cmd("agentry update skills")} mhmdreza-rafiei/agent-tools`),
 		bullet(`${cmd("agentry init skill")} enhance-prompt prompt ${flag("--reference")}`),
@@ -130,20 +131,15 @@ function printHelp() {
 		`      ${flag("--all")}        ${dim("Install everything to all agents, no prompts")}`,
 		`  ${flag("-y, --yes")}        ${dim("Don't prompt (scope defaults to project)")}`,
 		`      ${flag("--description")} ${dim("<t>")}  ${dim("init: frontmatter description")}`,
-		`      ${flag("--alwaysApply")} ${dim("init rule: alwaysApply: true")}`,
-		`      ${flag("--reference")}  ${dim("init skill: add references/TEMPLATE.md")}`,
-		`      ${flag("--no-reference")} ${dim("init skill: skip references/")}`,
+		`      ${flag("--alwaysApply")}    ${dim("init rule: alwaysApply: true")}`,
+		`      ${flag("--reference")}      ${dim("init skill: include references/TEMPLATE.md")}`,
+		`      ${flag("--no-reference")}   ${dim("init skill: omit references/ folder")}`,
 		`      ${flag("--skills")} ${dim("[src]")} ${dim("init profile: include skills (optional source)")}`,
 		`      ${flag("--agents")} ${dim("[src]")} ${dim("init profile: include agents")}`,
 		`      ${flag("--rules")} ${dim("[src]")}  ${dim("init profile: include rules")}`,
 		`      ${flag("--scripts")} ${dim("[src]")} ${dim("init profile: include scripts")}`,
-		`  ${flag("-v, --version")}    ${dim("Print version")}`,
-		`  ${flag("-h, --help")}       ${dim("Show this help")}`,
-		"",
-		dim("Tip: omit --agent to pick providers interactively (universal locked + searchable list)."),
-		dim("Tip: remove/update accept a GitHub repo or local path to filter by install source."),
 		""
 	];
-	process.stdout.write(lines.join("\n"));
+	process.stdout.write(lines.join("\n") + "\n");
 }
 export { PALETTE, animateLogo, badge, delay, logo, printHelp, sky, tagline, theme };