@agentrules/cli 0.0.11 → 0.0.13

package/README.md

@@ -34,7 +34,8 @@ agentrules add <preset> --platform <platform> [options]
 | `-g, --global` | Install to global config directory |
 | `--dir <path>` | Install to a custom directory |
 | `-r, --registry <alias>` | Use a specific registry |
-| `-f, --force` | Overwrite existing files |
+| `-f, --force` | Overwrite existing files (backs up originals to `.bak`) |
+| `--no-backup` | Don't backup files before overwriting (use with `--force`) |
 | `--dry-run` | Preview changes without writing |
 | `--skip-conflicts` | Skip files that already exist |
 
@@ -200,12 +201,32 @@ agentrules publish --dry-run
 
 **Versioning:** Presets use `MAJOR.MINOR` versioning. You set the major version, and the registry auto-increments the minor version on each publish.
 
-### `agentrules unpublish <slug> <platform> <version>`
+### `agentrules unpublish <preset>`
 
 Remove a specific version of a preset from the registry. Requires authentication.
 
 ```bash
-agentrules unpublish my-preset opencode 1.0
+agentrules unpublish <preset> [options]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-p, --platform <platform>` | Target platform (if not in preset string) |
+| `-V, --version <version>` | Version to unpublish (if not in preset string) |
+
+**Examples:**
+
+```bash
+# Full format: slug.platform@version
+agentrules unpublish my-preset.opencode@1.0
+
+# With flags
+agentrules unpublish my-preset --platform opencode --version 1.0
+
+# Mixed: version in string, platform as flag
+agentrules unpublish my-preset@1.0 --platform opencode
 ```
 
 **Note:** Unpublished versions cannot be republished with the same version number.

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, 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";
@@ -8,7 +8,7 @@ import { promisify } from "util";
 import * as client from "openid-client";
 import chalk from "chalk";
 import { chmod, constants } from "fs";
-import { access, constants as constants$1, mkdir, readFile, readdir, rm, stat, writeFile } from "fs/promises";
+import { access, constants as constants$1, copyFile, mkdir, readFile, readdir, rm, stat, writeFile } from "fs/promises";
 import { homedir } from "os";
 import * as p from "@clack/prompts";
 
@@ -221,6 +221,14 @@ function fileStatus(status, filePath, options = {}) {
 	return `${config.style(config.symbol)} ${config.style(pad(label, 14))} ${filePath}`;
 }
 /**
+* Format a backup status line
+* e.g., "↪ backed up    .opencode/AGENT_RULES.md → .opencode/AGENT_RULES.md.bak"
+*/
+function backupStatus(originalPath, backupPath, options = {}) {
+	const label = options.dryRun ? "would backup" : "backed up";
+	return `${theme.info("↪")} ${theme.info(pad(label, 14))} ${originalPath} ${symbols.arrow} ${backupPath}`;
+}
+/**
 * Step indicator for multi-step operations
 * e.g., "[1/3] Fetching registry..."
 */
@@ -307,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,
@@ -335,6 +386,7 @@ const ui = {
 	warning,
 	info: info$1,
 	fileStatus,
+	backupStatus,
 	step,
 	brand,
 	banner,
@@ -345,7 +397,8 @@ const ui = {
 	stripAnsi,
 	truncate,
 	formatBytes: formatBytes$1,
-	relativeTime
+	relativeTime,
+	fileTree
 };
 
 //#endregion
@@ -1209,6 +1262,7 @@ async function addPreset(options) {
 	const writeStats = await writeBundleFiles(bundle, target, {
 		force: Boolean(options.force),
 		skipConflicts: Boolean(options.skipConflicts),
+		noBackup: Boolean(options.noBackup),
 		dryRun
 	});
 	return {
@@ -1216,6 +1270,7 @@ async function addPreset(options) {
 		bundle,
 		files: writeStats.files,
 		conflicts: writeStats.conflicts,
+		backups: writeStats.backups,
 		targetRoot: target.root,
 		targetLabel: target.label,
 		registryAlias,
@@ -1298,6 +1353,7 @@ function resolveInstallTarget(platform, options) {
 async function writeBundleFiles(bundle, target, behavior) {
 	const files = [];
 	const conflicts = [];
+	const backups = [];
 	if (!behavior.dryRun) await mkdir(target.root, { recursive: true });
 	for (const file of bundle.files) {
 		const decoded = decodeBundledFile(file);
@@ -1326,6 +1382,16 @@ async function writeBundleFiles(bundle, target, behavior) {
 			continue;
 		}
 		if (behavior.force) {
+			if (!behavior.noBackup) {
+				const backupPath = `${destination}.bak`;
+				const relativeBackupPath = `${relativePath}.bak`;
+				if (!behavior.dryRun) await copyFile(destination, backupPath);
+				backups.push({
+					originalPath: relativePath,
+					backupPath: relativeBackupPath
+				});
+				log.debug(`Backed up: ${relativePath} → ${relativeBackupPath}`);
+			}
 			if (!behavior.dryRun) await writeFile(destination, data);
 			files.push({
 				path: relativePath,
@@ -1346,7 +1412,8 @@ async function writeBundleFiles(bundle, target, behavior) {
 	}
 	return {
 		files,
-		conflicts
+		conflicts,
+		backups
 	};
 }
 /**
@@ -1621,6 +1688,66 @@ async function detectPlatforms(directory) {
 	return detected;
 }
 /**
+* Resolve the target platform directory for initialization.
+*
+* Detection order (deterministic):
+* 1. If targetDir itself is a platform directory (e.g., ".claude"), use it directly
+* 2. Otherwise, detect platform directories inside targetDir
+*
+* @param targetDir - The target directory (cwd or user-provided path)
+* @param platformOverride - Optional platform to use instead of detecting/inferring
+*/
+async function resolvePlatformDirectory(targetDir, platformOverride) {
+	const targetDirName = basename(targetDir);
+	const targetPlatform = getPlatformFromDir(targetDirName);
+	if (targetPlatform) {
+		const platform$1 = platformOverride ? normalizePlatform(platformOverride) : targetPlatform;
+		return {
+			platformDir: targetDir,
+			platform: platform$1,
+			isTargetPlatformDir: true,
+			detected: []
+		};
+	}
+	const detected = await detectPlatforms(targetDir);
+	let platform;
+	let platformDir;
+	if (platformOverride) {
+		platform = normalizePlatform(platformOverride);
+		const detectedPath = detected.find((d) => d.id === platform)?.path;
+		platformDir = detectedPath ? join(targetDir, detectedPath) : join(targetDir, PLATFORMS[platform].projectDir);
+	} else if (detected.length > 0) {
+		platform = detected[0].id;
+		platformDir = join(targetDir, detected[0].path);
+	} else {
+		platform = "opencode";
+		platformDir = join(targetDir, PLATFORMS.opencode.projectDir);
+	}
+	return {
+		platformDir,
+		platform,
+		isTargetPlatformDir: false,
+		detected
+	};
+}
+/**
+* Check if --platform flag is required for non-interactive mode.
+* Returns the reason if required, so CLI can show appropriate error.
+*/
+function requiresPlatformFlag(resolved) {
+	if (resolved.isTargetPlatformDir) return { required: false };
+	if (resolved.detected.length === 0) return {
+		required: true,
+		reason: "no_platforms"
+	};
+	if (resolved.detected.length > 1) return {
+		required: true,
+		reason: "multiple_platforms",
+		platforms: resolved.detected.map((d) => d.id)
+	};
+	return { required: false };
+}
+/**
 * Initialize a preset in a platform directory.
 *
 * Structure:
@@ -1646,6 +1773,7 @@ async function initPreset(options) {
 		title,
 		version: 1,
 		description,
+		tags: options.tags ?? [],
 		license,
 		platform
 	};
@@ -1690,6 +1818,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.
@@ -1704,30 +1846,36 @@ async function initInteractive(options) {
 	let selectedPlatform;
 	if (explicitPlatformDir) {
 		targetPlatformDir = explicitPlatformDir;
-		const dirName = explicitPlatformDir.split("/").pop() ?? explicitPlatformDir;
+		const dirName = basename(explicitPlatformDir);
 		selectedPlatform = platformOption ?? getPlatformFromDir(dirName) ?? "opencode";
 	} else {
-		const detected = await detectPlatforms(baseDir);
-		const detectedMap = new Map(detected.map((d) => [d.id, d]));
-		if (detected.length > 0) p.note(detected.map((d) => `${d.id} → ${d.path}`).join("\n"), "Detected platform directories");
-		const defaultPlatform = platformOption ?? (detected.length > 0 ? detected[0].id : "opencode");
-		const platformChoice = await p.select({
-			message: "Platform",
-			options: PLATFORM_IDS.map((id) => ({
-				value: id,
-				label: detectedMap.has(id) ? `${id} (detected)` : id,
-				hint: detectedMap.get(id)?.path
-			})),
-			initialValue: defaultPlatform
-		});
-		if (p.isCancel(platformChoice)) {
-			p.cancel("Cancelled");
-			process.exit(0);
+		const resolved = await resolvePlatformDirectory(baseDir, platformOption);
+		if (resolved.isTargetPlatformDir) {
+			targetPlatformDir = resolved.platformDir;
+			selectedPlatform = resolved.platform;
+			p.note(`Detected platform directory: ${resolved.platform}`, "Using current directory");
+		} else {
+			const detectedMap = new Map(resolved.detected.map((d) => [d.id, d]));
+			if (resolved.detected.length > 0) p.note(resolved.detected.map((d) => `${d.id} → ${d.path}`).join("\n"), "Detected platform directories");
+			const platformChoice = await p.select({
+				message: "Platform",
+				options: PLATFORM_IDS.map((id) => ({
+					value: id,
+					label: detectedMap.has(id) ? `${id} (detected)` : id,
+					hint: detectedMap.get(id)?.path
+				})),
+				initialValue: resolved.platform
+			});
+			if (p.isCancel(platformChoice)) {
+				p.cancel("Cancelled");
+				process.exit(0);
+			}
+			selectedPlatform = platformChoice;
+			if (selectedPlatform !== resolved.platform) {
+				const reResolved = await resolvePlatformDirectory(baseDir, selectedPlatform);
+				targetPlatformDir = reResolved.platformDir;
+			} else targetPlatformDir = resolved.platformDir;
 		}
-		selectedPlatform = platformChoice;
-		const detectedInfo = detectedMap.get(selectedPlatform);
-		if (detectedInfo) targetPlatformDir = join(baseDir, detectedInfo.path);
-		else targetPlatformDir = join(baseDir, PLATFORMS[selectedPlatform].projectDir);
 	}
 	const configPath = join(targetPlatformDir, PRESET_CONFIG_FILENAME);
 	if (!force && await fileExists(configPath)) {
@@ -1766,6 +1914,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({
@@ -1806,6 +1959,7 @@ async function initInteractive(options) {
 		name: result.name,
 		title: result.title,
 		description: result.description,
+		tags: parseTags(result.tags),
 		platform: selectedPlatform,
 		license: result.license,
 		force
@@ -2004,6 +2158,9 @@ async function publish(options = {}) {
 		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,
@@ -2041,6 +2198,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("");
@@ -2139,10 +2299,45 @@ async function discoverPresetDirs(inputDir) {
 //#endregion
 //#region src/commands/unpublish.ts
 /**
+* Parses preset input to extract slug, platform, and version.
+* Supports formats:
+* - "my-preset.claude@1.0" (platform and version in string)
+* - "my-preset@1.0" (requires explicit platform)
+* - "my-preset.claude" (requires explicit version)
+*
+* Explicit --platform and --version flags take precedence.
+*/
+function parseUnpublishInput(input, explicitPlatform, explicitVersion) {
+	let normalized = input.toLowerCase().trim();
+	let parsedVersion;
+	const atIndex = normalized.lastIndexOf("@");
+	if (atIndex > 0) {
+		parsedVersion = normalized.slice(atIndex + 1);
+		normalized = normalized.slice(0, atIndex);
+	}
+	const version$1 = explicitVersion ?? parsedVersion;
+	const parts = normalized.split(".");
+	const maybePlatform = parts.at(-1);
+	let slug;
+	let platform;
+	if (maybePlatform && isSupportedPlatform(maybePlatform)) {
+		slug = parts.slice(0, -1).join(".");
+		platform = explicitPlatform ?? maybePlatform;
+	} else {
+		slug = normalized;
+		platform = explicitPlatform;
+	}
+	return {
+		slug,
+		platform,
+		version: version$1
+	};
+}
+/**
 * Unpublishes a preset version from the registry
 */
 async function unpublish(options) {
-	const { slug, platform, version: version$1 } = options;
+	const { slug, platform, version: version$1 } = parseUnpublishInput(options.preset, options.platform, options.version);
 	if (!slug) {
 		log.error("Preset slug is required");
 		return {
@@ -2151,14 +2346,14 @@ async function unpublish(options) {
 		};
 	}
 	if (!platform) {
-		log.error("Platform is required");
+		log.error("Platform is required. Use --platform or specify as <slug>.<platform>@<version>");
 		return {
 			success: false,
 			error: "Platform is required"
 		};
 	}
 	if (!version$1) {
-		log.error("Version is required");
+		log.error("Version is required. Use --version or specify as <slug>.<platform>@<version>");
 		return {
 			success: false,
 			error: "Version is required"
@@ -2199,12 +2394,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();
@@ -2217,7 +2680,7 @@ 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").option("-y, --yes", "Alias for --force").option("--dry-run", "Preview changes without writing").option("--skip-conflicts", "Skip conflicting files").action(handle(async (preset, options) => {
+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;
 	const dryRun = Boolean(options.dryRun);
 	const spinner$1 = await log.spinner("Fetching preset...");
@@ -2231,7 +2694,8 @@ program.command("add <preset>").description("Download and install a preset from
 			directory: options.dir,
 			force: Boolean(options.force || options.yes),
 			dryRun,
-			skipConflicts: Boolean(options.skipConflicts)
+			skipConflicts: Boolean(options.skipConflicts),
+			noBackup: options.backup === false
 		});
 	} catch (err) {
 		spinner$1.stop();
@@ -2241,16 +2705,23 @@ program.command("add <preset>").description("Download and install a preset from
 	const hasBlockingConflicts = result.conflicts.length > 0 && !options.skipConflicts && !dryRun;
 	if (hasBlockingConflicts) {
 		const count$1 = result.conflicts.length === 1 ? "1 file has" : `${result.conflicts.length} files have`;
-		log.error(`${count$1} conflicts. Use ${ui.command("--force")} to overwrite.`);
+		const forceHint = `Use ${ui.command("--force")} to overwrite ${ui.muted("(--no-backup to skip backups)")}`;
+		log.error(`${count$1} conflicts. ${forceHint}`);
 		log.print("");
 		for (const conflict of result.conflicts.slice(0, 3)) {
 			log.print(`  ${ui.muted("•")} ${conflict.path}`);
 			if (conflict.diff) log.print(conflict.diff.split("\n").map((l) => `    ${l}`).join("\n"));
 		}
 		if (result.conflicts.length > 3) log.print(`\n  ${ui.muted(`...and ${result.conflicts.length - 3} more`)}`);
+		log.print("");
+		log.print(forceHint);
 		process.exitCode = 1;
 		return;
 	}
+	if (result.backups.length > 0) {
+		log.print("");
+		for (const backup of result.backups) log.print(ui.backupStatus(backup.originalPath, backup.backupPath, { dryRun }));
+	}
 	log.print("");
 	for (const file of result.files) {
 		const status = file.status === "overwritten" ? "updated" : file.status;
@@ -2291,25 +2762,23 @@ program.command("init").description("Initialize a new preset").argument("[direct
 		log.print(ui.numberedList(nextSteps$1));
 		return;
 	}
-	const targetDirName = basename(targetDir);
-	const targetIsPlatformDir = getPlatformFromDir(targetDirName);
-	let platformDir;
-	let platform;
-	if (targetIsPlatformDir) {
-		platformDir = targetDir;
-		platform = options.platform ?? targetIsPlatformDir;
-	} else {
-		const detected = await detectPlatforms(targetDir);
-		platform = options.platform ?? detected[0]?.id ?? "opencode";
-		const detectedPath = detected.find((d) => d.id === platform)?.path;
-		platformDir = detectedPath ? join(targetDir, detectedPath) : join(targetDir, PLATFORMS[platform].projectDir);
+	const resolved = await resolvePlatformDirectory(targetDir, options.platform);
+	if (!options.platform) {
+		const check$1 = requiresPlatformFlag(resolved);
+		if (check$1.required) {
+			if (check$1.reason === "no_platforms") {
+				const targetDirName = basename(targetDir);
+				log.error(`No platform directory found in "${targetDirName}". Specify --platform (${PLATFORM_IDS.join(", ")}) or run from a platform directory.`);
+			} else log.error(`Multiple platform directories found (${check$1.platforms.join(", ")}). Specify --platform to choose one.`);
+			process.exit(1);
+		}
 	}
 	const result = await initPreset({
-		directory: platformDir,
+		directory: resolved.platformDir,
 		name: options.name ?? defaultName,
 		title: options.title,
 		description: options.description,
-		platform,
+		platform: resolved.platform,
 		license: options.license,
 		force: options.force
 	});
@@ -2464,14 +2933,19 @@ program.command("publish").description("Publish a preset to the registry").argum
 	});
 	if (!result.success) process.exitCode = 1;
 }));
-program.command("unpublish").description("Remove a preset version from the registry").argument("<slug>", "Preset slug (e.g., my-preset)").argument("<platform>", "Platform (e.g., opencode, claude)").argument("<version>", "Version to unpublish (e.g., 1.1, 2.3)").action(handle(async (slug, platform, version$1) => {
+program.command("unpublish").description("Remove a preset version from the registry").argument("<preset>", "Preset to unpublish (e.g., my-preset.claude@1.0 or my-preset@1.0)").option("-p, --platform <platform>", "Target platform (opencode, codex, claude, cursor)").option("-V, --version <version>", "Version to unpublish").action(handle(async (preset, options) => {
+	const platform = options.platform ? normalizePlatformInput(options.platform) : void 0;
 	const result = await unpublish({
-		slug,
+		preset,
 		platform,
-		version: version$1
+		version: options.version
 	});
 	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.11",
+  "version": "0.0.13",
   "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.10",
     "@clack/prompts": "^0.11.0",
     "chalk": "^5.4.1",
     "commander": "^12.1.0",