@agentrules/cli 0.0.12 → 0.0.14

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createRequire } from "module";
-import { AGENT_RULES_DIR, API_ENDPOINTS, COMMON_LICENSES, LATEST_VERSION, PLATFORMS, PLATFORM_IDS, PRESET_CONFIG_FILENAME, PRESET_SCHEMA_URL, STATIC_BUNDLE_DIR, buildPresetPublishInput, buildPresetRegistry, createDiffPreview, decodeBundledFile, descriptionSchema, fetchBundle, getPlatformFromDir, isLikelyText, isPlatformDir, isSupportedPlatform, licenseSchema, normalizeBundlePath, normalizePlatformInput, resolvePreset, slugSchema, titleSchema, toUtf8String, validatePresetConfig, verifyBundledFileChecksum } from "@agentrules/core";
+import { AGENT_RULES_DIR, API_ENDPOINTS, COMMON_LICENSES, LATEST_VERSION, PLATFORMS, PLATFORM_IDS, PRESET_CONFIG_FILENAME, PRESET_SCHEMA_URL, STATIC_BUNDLE_DIR, buildPresetPublishInput, buildPresetRegistry, createDiffPreview, decodeBundledFile, descriptionSchema, fetchBundle, getInstallPath, getPlatformFromDir, isLikelyText, isPlatformDir, isSupportedPlatform, licenseSchema, normalizeBundlePath, normalizePlatformInput, resolvePreset, slugSchema, tagsSchema, titleSchema, toUtf8String, validatePresetConfig, verifyBundledFileChecksum } from "@agentrules/core";
 import { Command } from "commander";
 import { basename, dirname, join, relative, resolve, sep } from "path";
 import { exec } from "child_process";
@@ -315,6 +315,49 @@ function relativeTime(date) {
 	if (minutes > 0) return `${minutes}m ago`;
 	return "just now";
 }
+/**
+* Formats an array of files as a tree structure
+*/
+function fileTree(files) {
+	const root = {
+		name: "",
+		children: new Map()
+	};
+	for (const file of files) {
+		const parts = file.path.split("/");
+		let current = root;
+		for (let i = 0; i < parts.length; i++) {
+			const part = parts[i];
+			const isFile = i === parts.length - 1;
+			let child = current.children.get(part);
+			if (!child) {
+				child = {
+					name: part,
+					size: isFile ? file.size : void 0,
+					children: new Map()
+				};
+				current.children.set(part, child);
+			}
+			current = child;
+		}
+	}
+	const lines = [];
+	function renderNode(node, prefix, isLast) {
+		const connector = isLast ? "└── " : "├── ";
+		const sizeStr = node.size !== void 0 ? muted(` (${formatBytes$1(node.size)})`) : "";
+		lines.push(`${prefix}${connector}${node.name}${sizeStr}`);
+		const children = Array.from(node.children.values());
+		const newPrefix = prefix + (isLast ? "    " : "│   ");
+		children.forEach((child, index) => {
+			renderNode(child, newPrefix, index === children.length - 1);
+		});
+	}
+	const topLevel = Array.from(root.children.values());
+	topLevel.forEach((child, index) => {
+		renderNode(child, "", index === topLevel.length - 1);
+	});
+	return lines.join("\n");
+}
 const ui = {
 	theme,
 	symbols,
@@ -354,7 +397,8 @@ const ui = {
 	stripAnsi,
 	truncate,
 	formatBytes: formatBytes$1,
-	relativeTime
+	relativeTime,
+	fileTree
 };
 
 //#endregion
@@ -668,6 +712,34 @@ async function unpublishPreset(baseUrl, token, slug, platform, version$1) {
 	}
 }
 
+//#endregion
+//#region src/lib/api/rule.ts
+async function getRule(baseUrl, slug) {
+	const url = `${baseUrl}${API_ENDPOINTS.rule.get(slug)}`;
+	log.debug(`GET ${url}`);
+	try {
+		const response = await fetch(url);
+		log.debug(`Response status: ${response.status}`);
+		if (!response.ok) {
+			const errorData = await response.json();
+			return {
+				success: false,
+				error: errorData.error || `HTTP ${response.status}`
+			};
+		}
+		const data = await response.json();
+		return {
+			success: true,
+			data
+		};
+	} catch (error$2) {
+		return {
+			success: false,
+			error: `Failed to connect to registry: ${getErrorMessage(error$2)}`
+		};
+	}
+}
+
 //#endregion
 //#region src/lib/api/session.ts
 /**
@@ -1278,7 +1350,7 @@ function parsePresetInput(input, explicitPlatform, explicitVersion) {
 function resolveInstallTarget(platform, options) {
 	const { projectDir, globalDir } = PLATFORMS[platform];
 	if (options.directory) {
-		const customRoot = resolve(expandHome(options.directory));
+		const customRoot = resolve(expandHome$1(options.directory));
 		return {
 			root: customRoot,
 			mode: "custom",
@@ -1288,7 +1360,8 @@ function resolveInstallTarget(platform, options) {
 		};
 	}
 	if (options.global) {
-		const globalRoot = resolve(expandHome(globalDir));
+		if (!globalDir) throw new Error(`Platform "${platform}" does not support global installation`);
+		const globalRoot = resolve(expandHome$1(globalDir));
 		return {
 			root: globalRoot,
 			mode: "global",
@@ -1318,7 +1391,7 @@ async function writeBundleFiles(bundle, target, behavior) {
 		const destResult = computeDestinationPath(file.path, target);
 		const destination = destResult.path;
 		if (!behavior.dryRun) await mkdir(dirname(destination), { recursive: true });
-		const existing = await readExistingFile(destination);
+		const existing = await readExistingFile$1(destination);
 		const relativePath = relativize(destination, target.root);
 		if (!existing) {
 			if (!behavior.dryRun) await writeFile(destination, data);
@@ -1390,7 +1463,7 @@ function computeDestinationPath(pathInput, target) {
 	ensureWithinRoot(destination, target.root);
 	return { path: destination };
 }
-async function readExistingFile(pathname) {
+async function readExistingFile$1(pathname) {
 	try {
 		return await readFile(pathname);
 	} catch (error$2) {
@@ -1419,7 +1492,7 @@ function ensureWithinRoot(candidate, root) {
 	if (candidate === root) return;
 	if (!candidate.startsWith(normalizedRoot)) throw new Error(`Refusing to write outside of ${root}. Derived path: ${candidate}`);
 }
-function expandHome(value) {
+function expandHome$1(value) {
 	if (value.startsWith("~")) {
 		const remainder = value.slice(1);
 		if (!remainder) return homedir();
@@ -1513,7 +1586,7 @@ async function loadPreset(presetDir) {
 	const configObj = configJson;
 	const identifier = typeof configObj?.name === "string" ? configObj.name : configPath;
 	const config = validatePresetConfig(configJson, identifier);
-	const slug = config.name;
+	const name = config.name;
 	const dirName = basename(presetDir);
 	const isConfigInPlatformDir = isPlatformDir(dirName);
 	let filesDir;
@@ -1542,7 +1615,7 @@ async function loadPreset(presetDir) {
 	const files = await collectFiles(filesDir, rootExclude, ignorePatterns);
 	if (files.length === 0) throw new Error(`No files found in ${filesDir}. Presets must include at least one file.`);
 	return {
-		slug,
+		name,
 		config,
 		files,
 		installMessage,
@@ -1729,6 +1802,7 @@ async function initPreset(options) {
 		title,
 		version: 1,
 		description,
+		tags: options.tags ?? [],
 		license,
 		platform
 	};
@@ -1773,6 +1847,20 @@ function check(schema) {
 //#region src/commands/preset/init-interactive.ts
 const DEFAULT_PRESET_NAME = "my-preset";
 /**
+* Parse comma-separated tags string into array
+*/
+function parseTags(input) {
+	return input.split(",").map((tag) => tag.trim().toLowerCase()).filter((tag) => tag.length > 0);
+}
+/**
+* Validator for comma-separated tags input
+*/
+function checkTags(value) {
+	const tags = parseTags(value);
+	const result = tagsSchema.safeParse(tags);
+	if (!result.success) return result.error.issues[0]?.message;
+}
+/**
 * Run interactive init flow with clack prompts.
 *
 * If platformDir is provided, init directly in that directory.
@@ -1855,6 +1943,11 @@ async function initInteractive(options) {
 				validate: check(descriptionSchema)
 			});
 		},
+		tags: () => p.text({
+			message: "Tags (comma-separated, at least one)",
+			placeholder: "e.g., typescript, testing, react",
+			validate: checkTags
+		}),
 		license: async () => {
 			const defaultLicense = licenseOption ?? "MIT";
 			const choice = await p.select({
@@ -1895,6 +1988,7 @@ async function initInteractive(options) {
 		name: result.name,
 		title: result.title,
 		description: result.description,
+		tags: parseTags(result.tags),
 		platform: selectedPlatform,
 		license: result.license,
 		force
@@ -1954,7 +2048,7 @@ async function validatePreset(options) {
 			warnings
 		};
 	}
-	log.debug(`Preset slug: ${preset.name}`);
+	log.debug(`Preset name: ${preset.name}`);
 	const presetDir = dirname(configPath);
 	const platform = preset.platform;
 	log.debug(`Checking platform: ${platform}`);
@@ -2042,7 +2136,7 @@ async function publish(options = {}) {
 	let presetInput;
 	try {
 		presetInput = await loadPreset(presetDir);
-		log.debug(`Loaded preset "${presetInput.slug}" for platform ${presetInput.config.platform}`);
+		log.debug(`Loaded preset "${presetInput.name}" for platform ${presetInput.config.platform}`);
 	} catch (error$2) {
 		const message = getErrorMessage(error$2);
 		spinner$1.fail("Failed to load preset");
@@ -2087,17 +2181,20 @@ async function publish(options = {}) {
 		log.print("");
 		log.print(ui.header("Publish Preview"));
 		log.print(ui.keyValue("Preset", publishInput.title));
-		log.print(ui.keyValue("Slug", publishInput.slug));
+		log.print(ui.keyValue("Name", publishInput.name));
 		log.print(ui.keyValue("Platform", publishInput.platform));
 		log.print(ui.keyValue("Version", version$1 ? `${version$1}.x (auto-assigned minor)` : "1.x (auto-assigned)"));
 		log.print(ui.keyValue("Files", `${fileCount} file${fileCount === 1 ? "" : "s"}`));
 		log.print(ui.keyValue("Size", formatBytes(inputSize)));
 		log.print("");
+		log.print(ui.header("Files to publish", fileCount));
+		log.print(ui.fileTree(publishInput.files));
+		log.print("");
 		log.print(ui.hint("Run without --dry-run to publish."));
 		return {
 			success: true,
 			preview: {
-				slug: publishInput.slug,
+				slug: publishInput.name,
 				platform: publishInput.platform,
 				title: publishInput.title,
 				totalSize: inputSize,
@@ -2130,6 +2227,9 @@ async function publish(options = {}) {
 	const { data } = result;
 	const action = data.isNewPreset ? "Published new preset" : "Published";
 	spinner$1.success(`${action} ${ui.code(data.slug)} ${ui.version(data.version)} (${data.platform})`);
+	log.print("");
+	log.print(ui.header("Published files", fileCount));
+	log.print(ui.fileTree(publishInput.files));
 	const presetName$1 = `${data.slug}.${data.platform}`;
 	const presetRegistryUrl = `${ctx.registry.url}preset/${presetName$1}`;
 	log.info("");
@@ -2225,6 +2325,116 @@ async function discoverPresetDirs(inputDir) {
 	return presetDirs.sort();
 }
 
+//#endregion
+//#region src/commands/rule/add.ts
+async function addRule(options) {
+	const ctx = useAppContext();
+	const dryRun = Boolean(options.dryRun);
+	log.debug(`Fetching rule: ${options.slug}`);
+	const result = await getRule(ctx.registry.url, options.slug);
+	if (!result.success) throw new Error(result.error);
+	const rule = result.data;
+	const platform = rule.platform;
+	const targetPath = resolveTargetPath(platform, rule.type, rule.slug, {
+		global: options.global,
+		directory: options.directory
+	});
+	log.debug(`Target path: ${targetPath}`);
+	const existing = await readExistingFile(targetPath);
+	if (existing !== null) {
+		if (existing === rule.content) return {
+			slug: rule.slug,
+			platform: rule.platform,
+			type: rule.type,
+			title: rule.title,
+			targetPath,
+			status: "unchanged",
+			dryRun
+		};
+		if (!options.force) return {
+			slug: rule.slug,
+			platform: rule.platform,
+			type: rule.type,
+			title: rule.title,
+			targetPath,
+			status: "conflict",
+			dryRun
+		};
+		if (!dryRun) {
+			await mkdir(dirname(targetPath), { recursive: true });
+			await writeFile(targetPath, rule.content, "utf-8");
+		}
+		return {
+			slug: rule.slug,
+			platform: rule.platform,
+			type: rule.type,
+			title: rule.title,
+			targetPath,
+			status: "overwritten",
+			dryRun
+		};
+	}
+	if (!dryRun) {
+		await mkdir(dirname(targetPath), { recursive: true });
+		await writeFile(targetPath, rule.content, "utf-8");
+	}
+	return {
+		slug: rule.slug,
+		platform: rule.platform,
+		type: rule.type,
+		title: rule.title,
+		targetPath,
+		status: "created",
+		dryRun
+	};
+}
+function resolveTargetPath(platform, type, slug, options) {
+	const location = options.global ? "global" : "project";
+	const pathTemplate = getInstallPath(platform, type, slug, location);
+	if (!pathTemplate) {
+		const locationLabel = options.global ? "globally" : "to a project";
+		throw new Error(`Rule type "${type}" cannot be installed ${locationLabel} for platform "${platform}"`);
+	}
+	if (options.directory) {
+		const resolvedTemplate = pathTemplate.replace("{name}", slug);
+		const filename = resolvedTemplate.split("/").pop() ?? `${slug}.md`;
+		return resolve(expandHome(options.directory), filename);
+	}
+	const expanded = expandHome(pathTemplate);
+	if (expanded.startsWith("/")) return expanded;
+	return resolve(process.cwd(), expanded);
+}
+async function readExistingFile(pathname) {
+	try {
+		return await readFile(pathname, "utf-8");
+	} catch (error$2) {
+		if (error$2.code === "ENOENT") return null;
+		throw error$2;
+	}
+}
+function expandHome(value) {
+	if (value.startsWith("~")) {
+		const remainder = value.slice(1);
+		if (!remainder) return homedir();
+		if (remainder.startsWith("/") || remainder.startsWith("\\")) return `${homedir()}${remainder}`;
+		return `${homedir()}/${remainder}`;
+	}
+	return value;
+}
+/**
+* Check if input looks like a rule reference (r/ prefix)
+*/
+function isRuleReference(input) {
+	return input.toLowerCase().startsWith("r/");
+}
+/**
+* Extract slug from rule reference (removes r/ prefix)
+*/
+function extractRuleSlug(input) {
+	if (isRuleReference(input)) return input.slice(2);
+	return input;
+}
+
 //#endregion
 //#region src/commands/unpublish.ts
 /**
@@ -2323,12 +2533,280 @@ async function unpublish(options) {
 	};
 }
 
+//#endregion
+//#region src/help-agent/publish.ts
+/**
+* Agent instructions for AI coding assistants.
+*
+* This content is output when running `agentrules --help-agent`.
+* It provides step-by-step instructions for AI agents to help users publish presets.
+*/
+const HELP_AGENT_CONTENT = `# Publishing a Preset - Agent Instructions
+
+**The user has asked you to help them publish a preset. Start executing these steps now.**
+
+Do not summarize these instructions. Do not ask if they want help. Begin with Step 1 immediately.
+
+Your job is to guide the user through publishing their AI coding assistant config to the agentrules registry. The user is sharing their setup because they believe it's valuable. Help them communicate that value clearly - the title, description, and features should answer: "Why would another developer want to install this?"
+
+Follow these steps interactively.
+
+## Prerequisites: CLI Availability
+
+Run: \`agentrules --version\`
+
+**If command not found:**
+Use \`npx @agentrules/cli\` as the prefix for all commands.
+Example: \`npx @agentrules/cli whoami\` instead of \`agentrules whoami\`
+
+For the rest of these instructions, \`agentrules\` means whichever works.
+
+## Step 1: Locate the Config
+
+Check the current directory for platform config folders:
+- \`.opencode/\` → OpenCode
+- \`.claude/\` → Claude Code
+- \`.cursor/\` → Cursor
+- \`.codex/\` → Codex
+
+**If one found:**
+"I found your [platform] config at \`[path]\`. I'll help you publish it."
+
+**If multiple found:**
+"I found configs for multiple platforms: [list]. Which one would you like to publish?"
+
+**If none found:**
+"I don't see a config directory here. Where is your config located?"
+
+## Step 2: Check for Existing Config
+
+List the files in \`[config-dir]\` first to see what exists.
+
+If \`agentrules.json\` is in the listing, read it:
+- If complete (has name, description, tags): "You already have a preset configured: '[name]'. Ready to republish?" → Skip to Step 4 if yes
+- If missing required fields: Help them add the missing fields
+
+If \`agentrules.json\` is not in the listing, continue to Step 3.
+
+### Check for ignorable files
+
+While reviewing the file listing, look for files/folders that probably shouldn't be published.
+
+**Already ignored by default** (don't suggest these):
+- node_modules
+- .git
+- .DS_Store
+- *.lock
+- package-lock.json
+- bun.lockb
+- pnpm-lock.yaml
+
+**Commonly ignorable** (suggest adding to \`ignore\` field if present):
+- build/, dist/, out/ (build output)
+- .env, .env.* (environment files)
+- *.log (log files)
+- tmp/, temp/ (temporary files)
+- coverage/ (test coverage)
+- .cache/, .turbo/ (cache directories)
+
+If you see any of these or similar files/folders, ask: "I noticed [files]. These are usually not needed in a preset. Want me to add them to the ignore list?"
+
+If yes, include them in the \`ignore\` array when creating agentrules.json.
+
+## Step 3: Create agentrules.json
+
+The goal is to help potential users understand the **value** of this preset - why should they install it? What problem does it solve? How will it improve their workflow?
+
+### 3a. Analyze their config
+
+You already listed files in Step 2. Now read the config files you found (e.g., CLAUDE.md, AGENT_RULES.md, rules/*.md) to understand what the preset does.
+
+Look for:
+- Technologies and frameworks mentioned
+- The main purpose or rules being enforced
+- Who would benefit from this setup
+
+### 3b. Generate all suggestions at once
+
+Based on your analysis, generate suggestions for ALL fields:
+
+- **Name**: lowercase, hyphens, based on repo/directory/theme (1-64 chars)
+- **Title**: Title-cased, compelling name
+- **Description**: Value-focused - who is this for, what problem does it solve? (max 500 chars)
+- **Tags**: For discovery - technologies, frameworks, use cases (1-10 tags)
+- **Features**: Key benefits, not just capabilities (optional, up to 5)
+- **License**: Default to MIT
+
+### 3c. Present a single summary
+
+Show everything in one concise output. Put each field name on its own line, followed by the value on the next line:
+
+"Based on your config, here's what I'd suggest:
+
+**Name**
+typescript-strict-rules
+
+**Title**
+TypeScript Strict Rules
+
+**Description**
+Opinionated TypeScript rules that catch common bugs at dev time and enforce consistent patterns across your team.
+
+**Tags**
+typescript, strict, type-safety
+
+**Features**
+- Catches null/undefined errors before production
+- Enforces consistent code style without manual review
+
+**License**
+MIT
+
+Let me know if you'd like to change anything, or say 'looks good' to continue."
+
+### 3d. Handle feedback
+
+If the user wants changes (e.g., "change the description" or "add a react tag"), update those fields and show the summary again.
+
+When they approve, proceed to create the file.
+
+### Guidelines for good suggestions
+
+**Description** should answer: What problem does this solve? Who benefits?
+- Good: "Opinionated TypeScript rules that catch common bugs at dev time and enforce consistent patterns across your team."
+- Bad: "TypeScript rules with strict settings." (too vague, no value prop)
+
+**Features** should describe benefits, not capabilities:
+- Good: "Catches null/undefined errors before they hit production"
+- Bad: "Strict null checks" (feature, not benefit)
+
+**Tags** should help with discovery:
+- Technologies: typescript, python, rust, go
+- Frameworks: react, nextjs, fastapi, django
+- Use cases: code-review, testing, security, onboarding
+
+### 3e. Create the file
+
+Write \`[config-dir]/agentrules.json\`:
+
+\`\`\`json
+{
+  "$schema": "https://agentrules.directory/schema/agentrules.json",
+  "name": "[name]",
+  "title": "[title]",
+  "version": 1,
+  "description": "[description]",
+  "tags": ["tag1", "tag2"],
+  "license": "[license]",
+  "platform": "[detected-platform]"
+}
+\`\`\`
+
+Include \`"features": [...]\` only if provided.
+Include \`"ignore": ["pattern1", "pattern2"]\` if the user agreed to ignore certain files.
+
+### 3f. Show the file and get approval
+
+After writing the file, show the user:
+
+"I've created the config file at \`[config-dir]/agentrules.json\`:
+
+\`\`\`json
+[show the actual file contents]
+\`\`\`
+
+Take a look and let me know if you'd like to change anything, or say 'looks good' to continue."
+
+Wait for approval before proceeding. If they want changes, edit the file and show it again.
+
+Then validate: \`agentrules validate [config-dir]\`
+
+If errors, fix and retry.
+
+## Step 4: Login
+
+Run: \`agentrules whoami\`
+
+**If output shows "loggedIn": false or "Not logged in":**
+"You need to log in to publish."
+Run: \`agentrules login\`
+This opens a browser for authentication. Wait for completion.
+
+## Step 5: Preview with Dry Run
+
+Run: \`agentrules publish [config-dir] --dry-run\`
+
+Show the user the preview:
+"Here's what will be published:
+- Name: [name]
+- Platform: [platform]
+- Files: [count] files ([size])
+
+Ready to publish?"
+
+If they want changes, help edit agentrules.json and re-run dry-run.
+
+## Step 6: Publish
+
+Run: \`agentrules publish [config-dir]\`
+
+**If successful:**
+Show the URL from the output:
+
+"Published! Your preset is live at: [url]
+
+Share with others:
+\`\`\`
+npx @agentrules/cli add [name]
+\`\`\`"
+
+**If "already exists" error:**
+Ask if they want to increment the \`version\` field in agentrules.json and retry.
+
+**If other errors:**
+Show the error and suggest: \`agentrules validate [config-dir]\`
+
+## Step 7: Tips
+
+**If you used \`npx @agentrules/cli\`:**
+"Tip: Install globally to skip the npx download:
+\`\`\`
+npm i -g @agentrules/cli
+\`\`\`"
+
+## Notes for Agent
+
+- Be conversational and helpful
+- Explain what you're doing at each step
+- Use \`agentrules validate\` to check your work after any config changes
+- Remember whether you used npx for the tip at the end
+- If the user seems confused, explain that agentrules is a registry for sharing AI coding configs
+- The config file must be inside the platform directory (e.g., \`.opencode/agentrules.json\`)
+
+## Schema Reference
+
+**Required fields:**
+- \`name\`: slug format (lowercase, hyphens, 1-64 chars)
+- \`title\`: 1-80 characters
+- \`description\`: 1-500 characters
+- \`tags\`: array, 1-10 items, each lowercase/hyphens, max 35 chars
+- \`license\`: SPDX identifier (e.g., "MIT")
+- \`platform\`: one of \`opencode\`, \`claude\`, \`cursor\`, \`codex\`
+
+**Optional fields:**
+- \`$schema\`: JSON schema URL for validation
+- \`version\`: major version number (default: 1)
+- \`features\`: array, max 5 items, each max 100 chars
+- \`path\`: custom path to files (advanced use)
+- \`ignore\`: patterns to exclude from bundle
+`;
+
 //#endregion
 //#region src/index.ts
 const require = createRequire(import.meta.url);
 const packageJson = require("../package.json");
 const program = new Command();
-program.name("agentrules").description("The AI Agent Directory CLI").version(packageJson.version).option("-v, --verbose", "Enable verbose/debug output").configureOutput({ outputError: (str, write) => write(ui.error(str.trim())) }).hook("preAction", async (thisCommand, actionCommand) => {
+program.name("agentrules").description("The AI Agent Directory CLI").version(packageJson.version).option("-v, --verbose", "Enable verbose/debug output").option("--help-agent", "Output instructions for AI coding assistants").configureOutput({ outputError: (str, write) => write(ui.error(str.trim())) }).hook("preAction", async (thisCommand, actionCommand) => {
 	const opts = thisCommand.opts();
 	if (opts.verbose) log.setVerbose(true);
 	const actionOpts = actionCommand.opts();
@@ -2341,14 +2819,47 @@ program.name("agentrules").description("The AI Agent Directory CLI").version(pac
 		log.debug(`Failed to init context: ${getErrorMessage(error$2)}`);
 	}
 }).showHelpAfterError();
-program.command("add <preset>").description("Download and install a preset from the registry").option("-p, --platform <platform>", "Target platform (opencode, codex, claude, cursor)").option("-V, --version <version>", "Install a specific version").option("-r, --registry <alias>", "Use a specific registry alias").option("-g, --global", "Install to global directory").option("--dir <path>", "Install to a custom directory").option("-f, --force", "Overwrite existing files (backs up originals)").option("-y, --yes", "Alias for --force").option("--dry-run", "Preview changes without writing").option("--skip-conflicts", "Skip conflicting files").option("--no-backup", "Don't backup files before overwriting (use with --force)").action(handle(async (preset, options) => {
-	const platform = options.platform ? normalizePlatformInput(options.platform) : void 0;
+program.command("add <item>").description("Download and install a preset or rule from the registry (use r/<slug> for rules)").option("-p, --platform <platform>", "Target platform (opencode, codex, claude, cursor)").option("-V, --version <version>", "Install a specific version (presets only)").option("-r, --registry <alias>", "Use a specific registry alias").option("-g, --global", "Install to global directory").option("--dir <path>", "Install to a custom directory").option("-f, --force", "Overwrite existing files (backs up originals)").option("-y, --yes", "Alias for --force").option("--dry-run", "Preview changes without writing").option("--skip-conflicts", "Skip conflicting files (presets only)").option("--no-backup", "Don't backup files before overwriting (use with --force)").action(handle(async (item, options) => {
 	const dryRun = Boolean(options.dryRun);
+	if (isRuleReference(item)) {
+		const slug = extractRuleSlug(item);
+		const spinner$2 = await log.spinner(`Fetching rule "${slug}"...`);
+		try {
+			const result$1 = await addRule({
+				slug,
+				global: Boolean(options.global),
+				directory: options.dir,
+				force: Boolean(options.force || options.yes),
+				dryRun
+			});
+			spinner$2.stop();
+			if (result$1.status === "conflict") {
+				log.error(`File already exists: ${result$1.targetPath}. Use ${ui.command("--force")} to overwrite.`);
+				process.exitCode = 1;
+				return;
+			}
+			if (result$1.status === "unchanged") {
+				log.info(`Already up to date: ${ui.path(result$1.targetPath)}`);
+				return;
+			}
+			const verb$1 = dryRun ? "Would install" : "Installed";
+			const action = result$1.status === "overwritten" ? "updated" : "created";
+			log.print(ui.fileStatus(action, result$1.targetPath, { dryRun }));
+			log.print("");
+			log.success(`${verb$1} ${ui.bold(result$1.title)} ${ui.muted(`(${result$1.platform}/${result$1.type})`)}`);
+			if (dryRun) log.print(ui.hint("\nDry run complete. No files were written."));
+		} catch (err) {
+			spinner$2.stop();
+			throw err;
+		}
+		return;
+	}
+	const platform = options.platform ? normalizePlatformInput(options.platform) : void 0;
 	const spinner$1 = await log.spinner("Fetching preset...");
 	let result;
 	try {
 		result = await addPreset({
-			preset,
+			preset: item,
 			platform,
 			version: options.version,
 			global: Boolean(options.global),
@@ -2603,6 +3114,10 @@ program.command("unpublish").description("Remove a preset version from the regis
 	});
 	if (!result.success) process.exitCode = 1;
 }));
+if (process.argv.includes("--help-agent")) {
+	console.log(HELP_AGENT_CONTENT);
+	process.exit(0);
+}
 program.parseAsync(process.argv).then(() => {
 	process.exit(process.exitCode ?? 0);
 }).catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentrules/cli",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "author": "Brian Cheung <bcheung.dev@gmail.com> (https://github.com/bcheung)",
   "license": "MIT",
   "homepage": "https://agentrules.directory",
@@ -48,7 +48,7 @@
     "clean": "rm -rf node_modules dist .turbo"
   },
   "dependencies": {
-    "@agentrules/core": "0.0.9",
+    "@agentrules/core": "0.0.11",
     "@clack/prompts": "^0.11.0",
     "chalk": "^5.4.1",
     "commander": "^12.1.0",