@agentrules/core 0.0.6 → 0.0.8

package/README.md

@@ -2,28 +2,49 @@
 
 Shared types and utilities for the AGENT_RULES ecosystem.
 
+**This package is for developers building custom registries or alternative clients.** If you just want to install or publish presets, use the [CLI](../cli) instead.
+
 ## Installation
 
 ```bash
 npm install @agentrules/core
 ```
 
-## Features
+## What's Included
+
+| Module | Description |
+|--------|-------------|
+| **Types & Schemas** | TypeScript types and Zod schemas for presets, bundles, configs |
+| **Registry Builder** | Build registry artifacts from preset inputs |
+| **Registry Client** | Fetch and resolve presets from registries |
+| **Bundle Utilities** | Encode/decode bundles, verify checksums |
+| **Platform Config** | Platform IDs and directory paths |
 
-- **Types** - TypeScript definitions for presets, bundles, and registry entries
-- **Validation** - Zod schemas for validating `agentrules.json` configs
-- **Registry Builder** - Transform preset inputs into registry JSON artifacts
-- **Bundle Utilities** - Checksum verification, encoding/decoding helpers
-- **Diff Utilities** - Generate previews for file conflicts
+This package contains **pure functions with no environment assumptions**. It doesn't touch the file system or make network requests directly — that's left to the consumer (like the CLI).
 
 ## Usage
 
-### Building Registry Data
+### Validating Preset Config
 
 ```ts
-import { buildRegistryData } from "@agentrules/core";
+import { presetConfigSchema, validatePresetConfig } from "@agentrules/core";
+
+// Using Zod schema directly
+const result = presetConfigSchema.safeParse(jsonData);
+if (!result.success) {
+  console.error(result.error.issues);
+}
+
+// Or use the helper (throws on error)
+const config = validatePresetConfig(jsonData, "my-preset");
+```
+
+### Building Registry Artifacts
 
-const result = await buildRegistryData({
+```ts
+import { buildPresetRegistry } from "@agentrules/core";
+
+const result = await buildPresetRegistry({
   presets: [
     {
       slug: "my-preset",
@@ -32,48 +53,36 @@ const result = await buildRegistryData({
         title: "My Preset",
         version: 1,
         description: "A helpful preset",
+        tags: ["starter"],
         license: "MIT",
         platform: "opencode",
-        path: ".opencode",
+        path: "files",
       },
       files: [
         { path: "AGENT_RULES.md", contents: "# Rules\n" },
-        { path: "config.json", contents: '{"key": "value"}' },
       ],
     },
   ],
 });
 
-// result.entries  → array for registry.json
-// result.index    → object for registry.index.json
-// result.bundles  → bundle payloads
-```
-
-### Validating Preset Config
-
-```ts
-import { validatePresetConfig, presetConfigSchema } from "@agentrules/core";
-
-// Quick validation (throws on error)
-const config = validatePresetConfig(jsonData, "my-preset");
-
-// Zod schema for custom handling
-const result = presetConfigSchema.safeParse(jsonData);
-if (!result.success) {
-  console.error(result.error.issues);
-}
+// result.entries  → Preset[] for registry listing
+// result.index    → PresetIndex for lookups
+// result.bundles  → PresetBundle[] with encoded files
 ```
 
-### Fetching from Registry
+### Fetching from a Registry
 
 ```ts
 import { resolvePreset, fetchBundle } from "@agentrules/core";
 
-const { entry, bundleUrl } = await resolvePreset(
+// Resolve a preset (gets metadata and bundle URL)
+const { preset, bundleUrl } = await resolvePreset(
   "https://agentrules.directory/",
-  "agentic-dev-starter",
+  "my-preset",
   "opencode"
 );
+
+// Fetch the bundle
 const bundle = await fetchBundle(bundleUrl);
 ```
 
@@ -87,45 +96,71 @@ import {
 } from "@agentrules/core";
 
 for (const file of bundle.files) {
+  // Decode base64 contents
   const data = decodeBundledFile(file);
+  
+  // Verify integrity
   await verifyBundledFileChecksum(file, data);
   
+  // Check if it's text or binary
   if (isLikelyText(data)) {
-    console.log(`Text file: ${file.path}`);
+    const text = new TextDecoder().decode(data);
   }
 }
 ```
 
-## Preset Config Format
-
-Presets use `agentrules.json`:
-
-```json
-{
-  "$schema": "https://agentrules.directory/schema/agentrules.json",
-  "name": "my-preset",
-  "title": "My Preset",
-  "version": 1,
-  "description": "Description here",
-  "license": "MIT",
-  "tags": ["starter", "typescript"],
-  "features": ["Feature 1", "Feature 2"],
-  "platform": "opencode",
-  "path": "files"
-}
+### Platform Configuration
+
+```ts
+import { PLATFORMS, PLATFORM_IDS } from "@agentrules/core";
+
+// All supported platform IDs
+console.log(PLATFORM_IDS); // ["opencode", "claude", "cursor", "codex"]
+
+// Get paths for a platform
+const opencode = PLATFORMS.opencode;
+console.log(opencode.projectDir); // ".opencode"
+console.log(opencode.globalDir);  // "~/.config/opencode"
 ```
 
-### Versioning
+## Types
 
-Presets use two-segment versioning (`MAJOR.MINOR`):
-- **Major version**: Set by the publisher in config (defaults to 1)
-- **Minor version**: Auto-incremented by the registry on each publish
+Key types exported:
 
-## Development
+```ts
+import type {
+  // Preset configuration (agentrules.json)
+  PresetConfig,
+  
+  // What clients send to publish
+  PresetPublishInput,
+  
+  // What registries store and return
+  PresetBundle,
+  Preset,
+  PresetIndex,
+  
+  // Bundle file structure
+  BundledFile,
+  
+  // Platform types
+  PlatformId,
+  PlatformConfig,
+} from "@agentrules/core";
+```
 
-```bash
-bun install
-bun run build      # build with tsdown
-bun run test       # run tests
-bun run typecheck  # type checking
+## Schemas
+
+Zod schemas for validation:
+
+```ts
+import {
+  presetConfigSchema,
+  presetBundleSchema,
+  presetPublishInputSchema,
+  platformIdSchema,
+  slugSchema,
+  titleSchema,
+  descriptionSchema,
+} from "@agentrules/core";
 ```

package/dist/index.d.ts

@@ -1,112 +1,6 @@
 import { z } from "zod";
 
-//#region src/types/platform.d.ts
-
-/**
- * Single source of truth for platform IDs.
- * Add new platforms here - types and config will follow.
- */
-declare const PLATFORM_ID_TUPLE: readonly ["opencode", "codex", "claude", "cursor"];
-/** Union type of supported platform IDs, derived from PLATFORM_ID_TUPLE */
-type PlatformId = (typeof PLATFORM_ID_TUPLE)[number];
-/** List of supported platform IDs as a readonly tuple */
-declare const PLATFORM_IDS: readonly ["opencode", "codex", "claude", "cursor"];
-type PlatformConfig = {
-  /** Directory name for project installs (e.g., ".opencode") */
-  projectDir: string;
-  /** Path for global installs (e.g., "~/.config/opencode") */
-  globalDir: string;
-};
-/**
- * Platform-specific configuration.
- * Single source of truth for all platform paths.
- */
-declare const PLATFORMS: Record<PlatformId, PlatformConfig>;
-/**
- * Convention: preset files under this directory map to the platform config directory.
- * e.g., `config/agent.md` → `.opencode/agent.md` (project) or `agent.md` (global)
- */
-declare const CONFIG_DIR_NAME = "config";
-declare function isSupportedPlatform(value: string): value is PlatformId;
-declare function normalizePlatformInput(value: string): PlatformId;
-//#endregion
-//#region src/types/definitions.d.ts
-type PresetConfig = {
-  $schema?: string;
-  name: string;
-  title: string;
-  version?: number;
-  description: string;
-  tags?: string[];
-  features?: string[];
-  license: string;
-  platform: PlatformId;
-  /** Path to config files. Defaults to platform's projectDir (e.g., ".claude") */
-  path?: string;
-};
-type BundledFile = {
-  path: string;
-  /** File size in bytes */
-  size: number;
-  checksum: string;
-  contents: string;
-};
-/**
- * What clients send to publish a preset.
- * Version is optional major version. Registry assigns full MAJOR.MINOR.
- */
-type PublishInput = {
-  slug: string;
-  platform: PlatformId;
-  title: string;
-  description: string;
-  tags: string[];
-  license: string;
-  licenseContent?: string;
-  readmeContent?: string;
-  features?: string[];
-  installMessage?: string;
-  files: BundledFile[];
-  /** Major version. Defaults to 1 if not specified. */
-  version?: number;
-};
-/**
- * What registries store and return.
- * Includes version (required) - full MAJOR.MINOR format assigned by registry.
- */
-type RegistryBundle = Omit<PublishInput, "version"> & {
-  /** Full version in MAJOR.MINOR format (e.g., "1.3", "2.1") */
-  version: string;
-};
-type RegistryEntry = {
-  name: string;
-  slug: string;
-  platform: PlatformId;
-  title: string;
-  version: string;
-  description: string;
-  tags: string[];
-  license: string;
-  features?: string[];
-  bundleUrl: string;
-  fileCount: number;
-  totalSize: number;
-};
-type RegistryIndex = Record<string, RegistryEntry>;
-type RegistryFileInput = {
-  path: string;
-  contents: ArrayBuffer | ArrayBufferView | string;
-};
-type RegistryPresetInput = {
-  slug: string;
-  config: PresetConfig;
-  files: RegistryFileInput[];
-  /** Install message from INSTALL.txt file */
-  installMessage?: string;
-  readmeContent?: string;
-  licenseContent?: string;
-}; //#endregion
-//#region src/types/schema.d.ts
+//#region src/preset/schema.d.ts
 declare const platformIdSchema: z.ZodEnum<{
   opencode: "opencode";
   codex: "codex";
@@ -115,18 +9,10 @@ declare const platformIdSchema: z.ZodEnum<{
 }>;
 declare const titleSchema: z.ZodString;
 declare const descriptionSchema: z.ZodString;
-/** Validate a title string and return error message if invalid, undefined if valid */
-declare function validateTitle(value: string): string | undefined;
-/** Validate a description string and return error message if invalid, undefined if valid */
-declare function validateDescription(value: string): string | undefined;
 declare const slugSchema: z.ZodString;
-/** Validate a slug string and return error message if invalid, undefined if valid */
-declare function validateSlug(value: string): string | undefined;
 declare const COMMON_LICENSES: readonly ["MIT", "Apache-2.0", "GPL-3.0-only", "BSD-3-Clause", "ISC", "Unlicense"];
 type CommonLicense = (typeof COMMON_LICENSES)[number];
 declare const licenseSchema: z.ZodString;
-/** Validate a license string and return error message if invalid, undefined if valid */
-declare function validateLicense(value: string): string | undefined;
 declare const presetConfigSchema: z.ZodObject<{
   $schema: z.ZodOptional<z.ZodString>;
   name: z.ZodString;
@@ -154,7 +40,7 @@ declare const bundledFileSchema: z.ZodObject<{
  * Schema for what clients send to publish a preset.
  * Version is optional major version. Registry assigns full MAJOR.MINOR.
  */
-declare const publishInputSchema: z.ZodObject<{
+declare const presetPublishInputSchema: z.ZodObject<{
   slug: z.ZodString;
   platform: z.ZodEnum<{
     opencode: "opencode";
@@ -182,7 +68,7 @@ declare const publishInputSchema: z.ZodObject<{
  * Schema for what registries store and return.
  * Includes version (required) - full MAJOR.MINOR format assigned by registry.
  */
-declare const registryBundleSchema: z.ZodObject<{
+declare const presetBundleSchema: z.ZodObject<{
   title: z.ZodString;
   description: z.ZodString;
   license: z.ZodString;
@@ -206,7 +92,7 @@ declare const registryBundleSchema: z.ZodObject<{
   }, z.core.$strip>>;
   version: z.ZodString;
 }, z.core.$strip>;
-declare const registryEntrySchema: z.ZodObject<{
+declare const presetSchema: z.ZodObject<{
   title: z.ZodString;
   description: z.ZodString;
   license: z.ZodString;
@@ -225,7 +111,7 @@ declare const registryEntrySchema: z.ZodObject<{
   fileCount: z.ZodNumber;
   totalSize: z.ZodNumber;
 }, z.core.$strip>;
-declare const registryIndexSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+declare const presetIndexSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
   title: z.ZodString;
   description: z.ZodString;
   license: z.ZodString;
@@ -245,6 +131,121 @@ declare const registryIndexSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
   totalSize: z.ZodNumber;
 }, z.core.$strip>>;
 
+//#endregion
+//#region src/platform/types.d.ts
+/**
+ * Single source of truth for platform IDs.
+ * Add new platforms here - types and config will follow.
+ */
+declare const PLATFORM_ID_TUPLE: readonly ["opencode", "codex", "claude", "cursor"];
+/** Union type of supported platform IDs, derived from PLATFORM_ID_TUPLE */
+type PlatformId = (typeof PLATFORM_ID_TUPLE)[number];
+/** Configuration for a platform's directory paths */
+type PlatformConfig = {
+  /** Directory name for project installs (e.g., ".opencode") */
+  projectDir: string;
+  /** Path for global installs (e.g., "~/.config/opencode") */
+  globalDir: string;
+};
+
+//#endregion
+//#region src/platform/config.d.ts
+/** List of supported platform IDs as a readonly tuple */
+declare const PLATFORM_IDS: readonly ["opencode", "codex", "claude", "cursor"];
+/**
+ * Platform-specific configuration.
+ * Single source of truth for all platform paths.
+ */
+declare const PLATFORMS: Record<PlatformId, PlatformConfig>;
+/**
+ * Convention: preset files under this directory map to the platform config directory.
+ * e.g., `config/agent.md` → `.opencode/agent.md` (project) or `agent.md` (global)
+ */
+declare const CONFIG_DIR_NAME = "config";
+
+//#endregion
+//#region src/platform/utils.d.ts
+declare function isSupportedPlatform(value: string): value is PlatformId;
+declare function normalizePlatformInput(value: string): PlatformId;
+
+//#endregion
+//#region src/preset/types.d.ts
+type PresetConfig = {
+  $schema?: string;
+  name: string;
+  title: string;
+  version?: number;
+  description: string;
+  tags?: string[];
+  features?: string[];
+  license: string;
+  platform: PlatformId;
+  /** Path to config files. Defaults to platform's projectDir (e.g., ".claude") */
+  path?: string;
+};
+type BundledFile = {
+  path: string;
+  /** File size in bytes */
+  size: number;
+  checksum: string;
+  contents: string;
+};
+/**
+ * What clients send to publish a preset.
+ * Version is optional major version. Registry assigns full MAJOR.MINOR.
+ */
+type PresetPublishInput = {
+  slug: string;
+  platform: PlatformId;
+  title: string;
+  description: string;
+  tags: string[];
+  license: string;
+  licenseContent?: string;
+  readmeContent?: string;
+  features?: string[];
+  installMessage?: string;
+  files: BundledFile[];
+  /** Major version. Defaults to 1 if not specified. */
+  version?: number;
+};
+/**
+ * What registries store and return.
+ * Includes version (required) - full MAJOR.MINOR format assigned by registry.
+ */
+type PresetBundle = Omit<PresetPublishInput, "version"> & {
+  /** Full version in MAJOR.MINOR format (e.g., "1.3", "2.1") */
+  version: string;
+};
+type Preset = {
+  name: string;
+  slug: string;
+  platform: PlatformId;
+  title: string;
+  version: string;
+  description: string;
+  tags: string[];
+  license: string;
+  features?: string[];
+  bundleUrl: string;
+  fileCount: number;
+  totalSize: number;
+};
+type PresetIndex = Record<string, Preset>;
+type PresetFileInput = {
+  path: string;
+  contents: ArrayBuffer | ArrayBufferView | string;
+};
+type PresetInput = {
+  slug: string;
+  config: PresetConfig;
+  files: PresetFileInput[];
+  /** Install message from INSTALL.txt file */
+  installMessage?: string;
+  readmeContent?: string;
+  licenseContent?: string;
+};
+
 //#endregion
 //#region src/builder/registry.d.ts
 /**
@@ -253,23 +254,23 @@ declare const registryIndexSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
  */
 declare const STATIC_BUNDLE_DIR = "r";
 /**
- * Options for building a PublishInput (for CLI publish command).
+ * Options for building a PresetPublishInput (for CLI publish command).
  */
-type BuildPublishInputOptions = {
-  preset: RegistryPresetInput;
+type BuildPresetPublishInputOptions = {
+  preset: PresetInput;
   /** Major version. Defaults to 1 if not specified. */
   version?: number;
 };
 /**
- * Builds a PublishInput from preset input.
+ * Builds a PresetPublishInput from preset input.
  * Used by CLI to prepare data for publishing to a registry.
  */
-declare function buildPublishInput(options: BuildPublishInputOptions): Promise<PublishInput>;
+declare function buildPresetPublishInput(options: BuildPresetPublishInputOptions): Promise<PresetPublishInput>;
 /**
  * Options for building a static registry.
  */
-type BuildRegistryDataOptions = {
-  presets: RegistryPresetInput[];
+type BuildPresetRegistryOptions = {
+  presets: PresetInput[];
   /**
    * Optional base path or URL prefix for bundle locations.
    * Format: {bundleBase}/{STATIC_BUNDLE_DIR}/{slug}/{platform}
@@ -277,17 +278,17 @@ type BuildRegistryDataOptions = {
    */
   bundleBase?: string;
 };
-type BuildRegistryDataResult = {
-  entries: RegistryEntry[];
-  index: RegistryIndex;
-  bundles: RegistryBundle[];
+type BuildPresetRegistryResult = {
+  entries: Preset[];
+  index: PresetIndex;
+  bundles: PresetBundle[];
 };
 /**
  * Builds a static registry with entries, index, and bundles.
  * Used for building static registry files (e.g., community-presets).
  * Each preset uses its version from config (default: major 1, minor 0).
  */
-declare function buildRegistryData(options: BuildRegistryDataOptions): Promise<BuildRegistryDataResult>;
+declare function buildPresetRegistry(options: BuildPresetRegistryOptions): Promise<BuildPresetRegistryResult>;
 
 //#endregion
 //#region src/builder/utils.d.ts
@@ -308,7 +309,7 @@ declare function toUtf8String(payload: ArrayBuffer | ArrayBufferView): string;
  * Resolved preset with absolute bundle URL
  */
 type ResolvedPreset = {
-  entry: RegistryEntry;
+  preset: Preset;
   bundleUrl: string;
 };
 /**
@@ -324,7 +325,7 @@ declare function resolvePreset(baseUrl: string, slug: string, platform: Platform
 /**
  * Fetches a bundle from an absolute URL or resolves it relative to the registry.
  */
-declare function fetchBundle(bundleUrl: string): Promise<RegistryBundle>;
+declare function fetchBundle(bundleUrl: string): Promise<PresetBundle>;
 
 //#endregion
 //#region src/constants.d.ts
@@ -345,8 +346,8 @@ declare const API_ENDPOINTS: {
   readonly presets: {
     /** Base path for preset operations */
     readonly base: "api/presets";
-    /** Get preset entry by version (defaults to "latest") */
-    readonly entry: (slug: string, platform: string, version?: string) => string;
+    /** Get preset by slug, platform, and version (defaults to "latest") */
+    readonly get: (slug: string, platform: string, version?: string) => string;
     /** Unpublish preset version */
     readonly unpublish: (slug: string, platform: string, version: string) => string;
   };
@@ -372,7 +373,7 @@ declare function createDiffPreview(path: string, currentText: string, incomingTe
 //#endregion
 //#region src/utils/encoding.d.ts
 declare function toPosixPath(pathValue: string): string;
-declare function encodeUtf8(value: string): Uint8Array<ArrayBuffer>;
+declare function encodeUtf8(value: string): Uint8Array<ArrayBufferLike>;
 declare function decodeUtf8(payload: ArrayBuffer | ArrayBufferView): string;
 declare function toUint8Array(payload: ArrayBuffer | ArrayBufferView): Uint8Array<ArrayBufferLike>;
 
@@ -383,4 +384,4 @@ declare function normalizePathFragment(value?: string): string | undefined;
 declare function maybeStripPrefix(pathInput: string, prefix?: string): string;
 
 //#endregion
-export { API_ENDPOINTS, BuildPublishInputOptions, BuildRegistryDataOptions, BuildRegistryDataResult, BundledFile, COMMON_LICENSES, CONFIG_DIR_NAME, CommonLicense, DiffPreviewOptions, LATEST_VERSION, PLATFORMS, PLATFORM_IDS, PRESET_CONFIG_FILENAME, PRESET_SCHEMA_URL, PlatformId, PresetConfig, PublishInput, RegistryBundle, RegistryEntry, RegistryFileInput, RegistryIndex, RegistryPresetInput, ResolvedPreset, STATIC_BUNDLE_DIR, buildPublishInput, buildRegistryData, bundledFileSchema, cleanInstallMessage, createDiffPreview, decodeBundledFile, decodeUtf8, descriptionSchema, encodeItemName, encodeUtf8, fetchBundle, isLikelyText, isSupportedPlatform, licenseSchema, maybeStripPrefix, normalizeBundlePath, normalizePathFragment, normalizePlatformInput, platformIdSchema, presetConfigSchema, publishInputSchema, registryBundleSchema, registryEntrySchema, registryIndexSchema, resolvePreset, slugSchema, titleSchema, toPosixPath, toUint8Array, toUtf8String, validateDescription, validateLicense, validatePresetConfig, validateSlug, validateTitle, verifyBundledFileChecksum };
+export { API_ENDPOINTS, BuildPresetPublishInputOptions, BuildPresetRegistryOptions, BuildPresetRegistryResult, BundledFile, COMMON_LICENSES, CONFIG_DIR_NAME, CommonLicense, DiffPreviewOptions, LATEST_VERSION, PLATFORMS, PLATFORM_IDS, PLATFORM_ID_TUPLE, PRESET_CONFIG_FILENAME, PRESET_SCHEMA_URL, PlatformConfig, PlatformId, Preset, PresetBundle, PresetConfig, PresetFileInput, PresetIndex, PresetInput, PresetPublishInput, ResolvedPreset, STATIC_BUNDLE_DIR, buildPresetPublishInput, buildPresetRegistry, bundledFileSchema, cleanInstallMessage, createDiffPreview, decodeBundledFile, decodeUtf8, descriptionSchema, encodeItemName, encodeUtf8, fetchBundle, isLikelyText, isSupportedPlatform, licenseSchema, maybeStripPrefix, normalizeBundlePath, normalizePathFragment, normalizePlatformInput, platformIdSchema, presetBundleSchema, presetConfigSchema, presetIndexSchema, presetPublishInputSchema, presetSchema, resolvePreset, slugSchema, titleSchema, toPosixPath, toUint8Array, toUtf8String, validatePresetConfig, verifyBundledFileChecksum };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { ZodError, z } from "zod";
 import { createTwoFilesPatch } from "diff";
 
 //#region src/constants.ts
@@ -19,7 +19,7 @@ const LATEST_VERSION = "latest";
 const API_ENDPOINTS = {
 	presets: {
 		base: `${API_PATH}/presets`,
-		entry: (slug, platform, version = LATEST_VERSION) => `${API_PATH}/presets/${encodeURIComponent(slug)}/${encodeURIComponent(platform)}/${encodeURIComponent(version)}`,
+		get: (slug, platform, version = LATEST_VERSION) => `${API_PATH}/presets/${encodeURIComponent(slug)}/${encodeURIComponent(platform)}/${encodeURIComponent(version)}`,
 		unpublish: (slug, platform, version) => `${API_PATH}/presets/${encodeURIComponent(slug)}/${encodeURIComponent(platform)}/${encodeURIComponent(version)}`
 	},
 	auth: {
@@ -30,7 +30,7 @@ const API_ENDPOINTS = {
 };
 
 //#endregion
-//#region src/types/platform.ts
+//#region src/platform/types.ts
 /**
 * Single source of truth for platform IDs.
 * Add new platforms here - types and config will follow.
@@ -41,6 +41,9 @@ const PLATFORM_ID_TUPLE = [
 	"claude",
 	"cursor"
 ];
+
+//#endregion
+//#region src/platform/config.ts
 /** List of supported platform IDs as a readonly tuple */
 const PLATFORM_IDS = PLATFORM_ID_TUPLE;
 /**
@@ -70,6 +73,9 @@ const PLATFORMS = {
 * e.g., `config/agent.md` → `.opencode/agent.md` (project) or `agent.md` (global)
 */
 const CONFIG_DIR_NAME = "config";
+
+//#endregion
+//#region src/platform/utils.ts
 function isSupportedPlatform(value) {
 	return PLATFORM_ID_TUPLE.includes(value);
 }
@@ -80,44 +86,45 @@ function normalizePlatformInput(value) {
 }
 
 //#endregion
-//#region src/types/schema.ts
-const VERSION_REGEX = /^[1-9]\d*\.\d+$/;
-const platformIdSchema = z.enum(PLATFORM_IDS);
-const titleSchema = z.string().trim().min(1).max(120);
-const descriptionSchema = z.string().trim().min(1).max(500);
-/** Validate a title string and return error message if invalid, undefined if valid */
-function validateTitle(value) {
-	const trimmed = value.trim();
-	if (!trimmed) return "Title is required";
-	if (trimmed.length > 120) return "Title must be 120 characters or less";
-	return;
+//#region src/utils/encoding.ts
+function toPosixPath(pathValue) {
+	return pathValue.split("\\").join("/");
 }
-/** Validate a description string and return error message if invalid, undefined if valid */
-function validateDescription(value) {
-	const trimmed = value.trim();
-	if (!trimmed) return "Description is required";
-	if (trimmed.length > 500) return "Description must be 500 characters or less";
-	return;
+function encodeUtf8(value) {
+	if (typeof Buffer !== "undefined") return new Uint8Array(Buffer.from(value, "utf8"));
+	return new TextEncoder().encode(value);
 }
+function decodeUtf8(payload) {
+	const bytes = toUint8Array(payload);
+	if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("utf8");
+	return new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+}
+function toUint8Array(payload) {
+	if (payload instanceof Uint8Array) return payload;
+	if (ArrayBuffer.isView(payload)) return new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength);
+	return new Uint8Array(payload);
+}
+
+//#endregion
+//#region src/preset/schema.ts
+const PLATFORM_ID_SET = new Set(PLATFORM_IDS);
+const VERSION_REGEX = /^[1-9]\d*\.\d+$/;
+const platformIdSchema = z.enum(PLATFORM_IDS);
+const titleSchema = z.string().trim().min(1, "Title is required").max(80, "Title must be 80 characters or less");
+const descriptionSchema = z.string().trim().min(1, "Description is required").max(500, "Description must be 500 characters or less");
 const versionSchema = z.string().trim().regex(VERSION_REGEX, "Version must be in MAJOR.MINOR format (e.g., 1.3)");
 const majorVersionSchema = z.number().int().positive("Major version must be a positive integer");
-const tagSchema = z.string().trim().min(1).max(48);
-const tagsSchema = z.array(tagSchema).max(10);
-const featureSchema = z.string().trim().min(1).max(160);
-const featuresSchema = z.array(featureSchema).max(10);
-const installMessageSchema = z.string().trim().max(4e3);
+const TAG_REGEX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const TAG_ERROR = "Must be lowercase alphanumeric with hyphens (e.g., my-tag)";
+const tagSchema = z.string().trim().min(1, "Tag cannot be empty").max(35, "Tag must be 35 characters or less").regex(TAG_REGEX, TAG_ERROR).refine((tag) => !PLATFORM_ID_SET.has(tag), { message: "Platform names cannot be used as tags (redundant with platform field)" });
+const tagsSchema = z.array(tagSchema).min(1, "At least one tag is required").max(10, "Maximum 10 tags allowed");
+const featureSchema = z.string().trim().min(1, "Feature cannot be empty").max(100, "Feature must be 100 characters or less");
+const featuresSchema = z.array(featureSchema).max(5, "Maximum 5 features allowed");
+const installMessageSchema = z.string().trim().max(2e3, "Install message must be 2000 characters or less");
 const contentSchema = z.string();
 const SLUG_REGEX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const SLUG_ERROR = "Must be lowercase alphanumeric with hyphens (e.g., my-preset)";
-const slugSchema = z.string().trim().min(1).max(64).regex(SLUG_REGEX, SLUG_ERROR);
-/** Validate a slug string and return error message if invalid, undefined if valid */
-function validateSlug(value) {
-	const trimmed = value.trim();
-	if (!trimmed) return "Name is required";
-	if (trimmed.length > 64) return "Name must be 64 characters or less";
-	if (!SLUG_REGEX.test(trimmed)) return SLUG_ERROR;
-	return;
-}
+const slugSchema = z.string().trim().min(1, "Name is required").max(64, "Name must be 64 characters or less").regex(SLUG_REGEX, SLUG_ERROR);
 const COMMON_LICENSES = [
 	"MIT",
 	"Apache-2.0",
@@ -126,14 +133,7 @@ const COMMON_LICENSES = [
 	"ISC",
 	"Unlicense"
 ];
-const licenseSchema = z.string().trim().min(1).max(128);
-/** Validate a license string and return error message if invalid, undefined if valid */
-function validateLicense(value) {
-	const trimmed = value.trim();
-	if (!trimmed) return "License is required";
-	if (trimmed.length > 128) return "License must be 128 characters or less";
-	return;
-}
+const licenseSchema = z.string().trim().min(1, "License is required").max(128, "License must be 128 characters or less");
 const pathSchema = z.string().trim().min(1);
 const presetConfigSchema = z.object({
 	$schema: z.string().optional(),
@@ -157,7 +157,7 @@ const bundledFileSchema = z.object({
 * Schema for what clients send to publish a preset.
 * Version is optional major version. Registry assigns full MAJOR.MINOR.
 */
-const publishInputSchema = z.object({
+const presetPublishInputSchema = z.object({
 	slug: z.string().trim().min(1),
 	platform: platformIdSchema,
 	title: titleSchema,
@@ -175,8 +175,8 @@ const publishInputSchema = z.object({
 * Schema for what registries store and return.
 * Includes version (required) - full MAJOR.MINOR format assigned by registry.
 */
-const registryBundleSchema = publishInputSchema.omit({ version: true }).extend({ version: versionSchema });
-const registryEntrySchema = registryBundleSchema.omit({
+const presetBundleSchema = presetPublishInputSchema.omit({ version: true }).extend({ version: versionSchema });
+const presetSchema = presetBundleSchema.omit({
 	files: true,
 	readmeContent: true,
 	licenseContent: true,
@@ -187,27 +187,7 @@ const registryEntrySchema = registryBundleSchema.omit({
 	fileCount: z.number().int().nonnegative(),
 	totalSize: z.number().int().nonnegative()
 });
-const registryIndexSchema = z.record(z.string(), registryEntrySchema);
-
-//#endregion
-//#region src/utils/encoding.ts
-function toPosixPath(pathValue) {
-	return pathValue.split("\\").join("/");
-}
-function encodeUtf8(value) {
-	if (typeof Buffer !== "undefined") return new Uint8Array(Buffer.from(value, "utf8"));
-	return new TextEncoder().encode(value);
-}
-function decodeUtf8(payload) {
-	const bytes = toUint8Array(payload);
-	if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("utf8");
-	return new TextDecoder("utf-8", { fatal: false }).decode(bytes);
-}
-function toUint8Array(payload) {
-	if (payload instanceof Uint8Array) return payload;
-	if (ArrayBuffer.isView(payload)) return new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength);
-	return new Uint8Array(payload);
-}
+const presetIndexSchema = z.record(z.string(), presetSchema);
 
 //#endregion
 //#region src/builder/utils.ts
@@ -220,16 +200,18 @@ function encodeItemName(slug, platform) {
 	return `${slug}.${platform}`;
 }
 function validatePresetConfig(config, slug) {
-	if (!config || typeof config !== "object") throw new Error(`Invalid preset config for ${slug}`);
-	const preset = config;
-	if (!preset.name || typeof preset.name !== "string") throw new Error(`Preset ${slug} is missing a name`);
-	if (!preset.title || typeof preset.title !== "string") throw new Error(`Preset ${slug} is missing a title`);
-	if (preset.version !== void 0 && typeof preset.version !== "number") throw new Error(`Preset ${slug} has invalid version (must be a positive integer or omitted)`);
-	if (!preset.description || typeof preset.description !== "string") throw new Error(`Preset ${slug} is missing a description`);
-	if (!preset.license || typeof preset.license !== "string") throw new Error(`Preset ${slug} is missing a license (SPDX identifier required)`);
-	if (!preset.platform || typeof preset.platform !== "string") throw new Error(`Preset ${slug} is missing a platform`);
-	if (!PLATFORM_IDS.includes(preset.platform)) throw new Error(`Preset ${slug} has unknown platform: ${preset.platform}. Supported platforms: ${PLATFORM_IDS.join(", ")}`);
-	return preset;
+	try {
+		return presetConfigSchema.parse(config);
+	} catch (e) {
+		if (e instanceof ZodError) {
+			const messages = e.issues.map((issue) => {
+				const path = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+				return `${path}${issue.message}`;
+			});
+			throw new Error(`Invalid preset config for ${slug}:\n  - ${messages.join("\n  - ")}`);
+		}
+		throw e;
+	}
 }
 
 //#endregion
@@ -249,10 +231,10 @@ async function sha256(data) {
 	return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 /**
-* Builds a PublishInput from preset input.
+* Builds a PresetPublishInput from preset input.
 * Used by CLI to prepare data for publishing to a registry.
 */
-async function buildPublishInput(options) {
+async function buildPresetPublishInput(options) {
 	const { preset: presetInput, version } = options;
 	if (!NAME_PATTERN.test(presetInput.slug)) throw new Error(`Invalid slug "${presetInput.slug}". Slugs must be lowercase kebab-case.`);
 	const presetConfig = validatePresetConfig(presetInput.config, presetInput.slug);
@@ -285,7 +267,7 @@ async function buildPublishInput(options) {
 * Used for building static registry files (e.g., community-presets).
 * Each preset uses its version from config (default: major 1, minor 0).
 */
-async function buildRegistryData(options) {
+async function buildPresetRegistry(options) {
 	const bundleBase = normalizeBundleBase(options.bundleBase);
 	const entries = [];
 	const bundles = [];
@@ -442,7 +424,7 @@ async function sha256Hex(payload) {
 * @param version - Version to resolve (defaults to "latest")
 */
 async function resolvePreset(baseUrl, slug, platform, version = LATEST_VERSION) {
-	const apiUrl = new URL(API_ENDPOINTS.presets.entry(slug, platform, version), baseUrl);
+	const apiUrl = new URL(API_ENDPOINTS.presets.get(slug, platform, version), baseUrl);
 	const response = await fetch(apiUrl);
 	if (!response.ok) {
 		if (response.status === 404) {
@@ -452,10 +434,10 @@ async function resolvePreset(baseUrl, slug, platform, version = LATEST_VERSION)
 		throw new Error(`Failed to resolve preset (${response.status} ${response.statusText}).`);
 	}
 	try {
-		const entry = await response.json();
-		const resolvedBundleUrl = new URL(entry.bundleUrl, baseUrl).toString();
+		const preset = await response.json();
+		const resolvedBundleUrl = new URL(preset.bundleUrl, baseUrl).toString();
 		return {
-			entry,
+			preset,
 			bundleUrl: resolvedBundleUrl
 		};
 	} catch (error) {
@@ -506,4 +488,4 @@ function maybeStripPrefix(pathInput, prefix) {
 }
 
 //#endregion
-export { API_ENDPOINTS, COMMON_LICENSES, CONFIG_DIR_NAME, LATEST_VERSION, PLATFORMS, PLATFORM_IDS, PRESET_CONFIG_FILENAME, PRESET_SCHEMA_URL, STATIC_BUNDLE_DIR, buildPublishInput, buildRegistryData, bundledFileSchema, cleanInstallMessage, createDiffPreview, decodeBundledFile, decodeUtf8, descriptionSchema, encodeItemName, encodeUtf8, fetchBundle, isLikelyText, isSupportedPlatform, licenseSchema, maybeStripPrefix, normalizeBundlePath, normalizePathFragment, normalizePlatformInput, platformIdSchema, presetConfigSchema, publishInputSchema, registryBundleSchema, registryEntrySchema, registryIndexSchema, resolvePreset, slugSchema, titleSchema, toPosixPath, toUint8Array, toUtf8String, validateDescription, validateLicense, validatePresetConfig, validateSlug, validateTitle, verifyBundledFileChecksum };
+export { API_ENDPOINTS, COMMON_LICENSES, CONFIG_DIR_NAME, LATEST_VERSION, PLATFORMS, PLATFORM_IDS, PLATFORM_ID_TUPLE, PRESET_CONFIG_FILENAME, PRESET_SCHEMA_URL, STATIC_BUNDLE_DIR, buildPresetPublishInput, buildPresetRegistry, bundledFileSchema, cleanInstallMessage, createDiffPreview, decodeBundledFile, decodeUtf8, descriptionSchema, encodeItemName, encodeUtf8, fetchBundle, isLikelyText, isSupportedPlatform, licenseSchema, maybeStripPrefix, normalizeBundlePath, normalizePathFragment, normalizePlatformInput, platformIdSchema, presetBundleSchema, presetConfigSchema, presetIndexSchema, presetPublishInputSchema, presetSchema, resolvePreset, slugSchema, titleSchema, toPosixPath, toUint8Array, toUtf8String, validatePresetConfig, verifyBundledFileChecksum };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentrules/core",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "author": "Brian Cheung <bcheung.dev@gmail.com> (https://github.com/bcheung)",
   "license": "MIT",
   "homepage": "https://agentrules.directory",