caruso 0.5.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c64aeb60f2cf2507b6b3cad6756d9730775931e2b059384f3c43febceec1aec3
+  data.tar.gz: ba8c515ffa913873789826bb4f704445106cc8cfbf7cbedb39ab50f68289ef83
+SHA512:
+  metadata.gz: d81e5ab8c88206fb14523eb0a906dfd1cb4fe98e2154580242d9cd63e7d73127497d623adb0fcf5b17c32d77cf9c1091f1bd3fab49eeeef9de1fa367d149fac8
+  data.tar.gz: 52d8eb203ad04f396b66a00b54e5235bc3f609ea394036e7d76adaf16bc9a46bc77017901a4836f3ba2451ff905f91edea747b2845c86330b32b96a38012f981

data/.rspec

@@ -0,0 +1,4 @@
+--require spec_helper
+--color
+--format documentation
+--order random

data/.rubocop.yml

@@ -0,0 +1,146 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'vendor/**/*'
+    - 'pkg/**/*'
+    - 'tmp/**/*'
+    - 'node_modules/**/*'
+    - '.git/**/*'
+
+# Prefer single quotes for consistency
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+# Documentation is nice but not mandatory for small projects
+Style/Documentation:
+  Enabled: false
+
+# Block length is fine for tests and Rake tasks
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - 'Rakefile'
+    - '*.gemspec'
+
+# Method length - reasonable limit
+Metrics/MethodLength:
+  Max: 25
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/caruso/cli.rb'  # CLI command methods can be longer
+
+# Line length - modern screens can handle more
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+# Allow longer parameter lists for complex methods
+Metrics/ParameterLists:
+  Max: 6
+
+# ABC size - complexity metric
+Metrics/AbcSize:
+  Max: 20
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/caruso/cli.rb'  # Plugin install/list methods are complex by nature
+    - 'lib/caruso/fetcher.rb'  # Marketplace loading handles multiple sources
+
+# Class length is fine for main classes
+Metrics/ClassLength:
+  Max: 150
+  Exclude:
+    - 'spec/**/*'
+
+# Prefer descriptive block parameter names
+Lint/UnusedBlockArgument:
+  AllowUnusedKeywordArguments: true
+
+# Allow rescue in modifier form for simple cases
+Style/RescueModifier:
+  Enabled: false
+
+# Prefer modern hash syntax
+Style/HashSyntax:
+  EnforcedStyle: ruby19
+
+# Frozen string literals - enable for performance
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+# Prefer explicit return in some cases for clarity
+Style/RedundantReturn:
+  Enabled: false
+
+# Allow both semantic and compact style for conditionals
+Style/IfUnlessModifier:
+  Enabled: false
+
+# Allow parallel assignment for readability
+Style/ParallelAssignment:
+  Enabled: false
+
+# Perl-style regex backrefs are fine and more concise
+Style/PerlBackrefs:
+  Enabled: false
+
+# Trailing whitespace should be removed
+Layout/TrailingWhitespace:
+  Enabled: true
+
+# Naming conventions
+Naming/MethodName:
+  Enabled: true
+  EnforcedStyle: snake_case
+
+# Prefer raise over fail
+Style/SignalException:
+  EnforcedStyle: only_raise
+
+# Modern Ruby features
+Style/HashEachMethods:
+  Enabled: true
+
+Style/HashTransformKeys:
+  Enabled: true
+
+Style/HashTransformValues:
+  Enabled: true
+
+# Security
+Security/Eval:
+  Enabled: true
+
+Security/Open:
+  Enabled: true
+
+# Gemspec cops
+Gemspec/RequireMFA:
+  Enabled: false  # MFA is good but not mandatory for all projects
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false  # We keep dev dependencies in gemspec for gem distribution
+
+Gemspec/OrderedDependencies:
+  Enabled: true  # Keep dependencies alphabetically sorted
+
+# Allow complex install method in CLI
+Metrics/CyclomaticComplexity:
+  Max: 12
+  Exclude:
+    - 'lib/caruso/cli.rb'
+
+Metrics/PerceivedComplexity:
+  Max: 12
+  Exclude:
+    - 'lib/caruso/cli.rb'
+
+# Duplicate branches are acceptable for error handling with different contexts
+Lint/DuplicateBranch:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,213 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.5.3] - 2025-11-23
+
+### Changed
+- Updated GitHub Actions workflow to only trigger on version tags (`v*`) instead of every push to main
+
+### Fixed
+- Added debugging to verify RubyGems API token is loaded correctly in CI/CD
+
+### Note
+- This release and versions 0.5.0-0.5.2 were used to test and configure continuous deployment to RubyGems and GitHub Packages
+
+## [0.5.2] - 2025-11-23
+
+### Note
+- Testing continuous deployment workflow
+
+## [0.5.1] - 2025-11-23
+
+### Note
+- Testing continuous deployment workflow
+
+## [0.5.0] - 2025-11-23
+
+### Changed
+- Removed automatic `.gitignore` editing - developers now manage their own .gitignore
+- Improved `caruso init` output to clearly show which files should be committed vs gitignored
+- Updated CLI output to provide recommended .gitignore entries without modifying the file
+
+### Added
+- Clear VCS documentation in README explaining which files to track
+- Example `.gitignore` snippet in README for easy copy-paste
+- Helpful init output showing "(commit this)" and "(add to .gitignore)" labels
+
+### Removed
+- `update_gitignore` method from ConfigManager
+- Automatic .gitignore modification during initialization
+
+## [0.4.0] - 2025-11-23
+
+### Changed
+- **BREAKING**: Marketplace names now read from `marketplace.json` `name` field (required)
+- **BREAKING**: Removed optional `NAME` parameter from `marketplace add` command
+- Cache directory now based on URL for stability, while marketplace name comes from manifest
+- Marketplace.json `name` field is now the authoritative source of truth for marketplace identity
+
+### Fixed
+- Marketplace name resolution now matches Claude Code behavior
+- `https://github.com/anthropics/claude-code` correctly resolves to `claude-code-plugins` (from manifest)
+- Local directory marketplace paths now properly detected and processed
+
+### Added
+- `Fetcher#extract_marketplace_name` public method for reading marketplace names from manifest
+- Support for directory paths in marketplace URLs (auto-detects `.claude-plugin/marketplace.json`)
+- Clear error message when marketplace.json is missing required `name` field
+- Comprehensive test fixtures for offline testing (`spec/fixtures/test-marketplace/`, `spec/fixtures/other-marketplace/`)
+
+### Implementation Details
+This release aligns with Claude Code specification where marketplace `name` field is required. The implementation follows a clean approach with no defensive fallbacks - if marketplace.json is invalid, it fails with a clear error rather than guessing.
+
+Cache directories remain URL-based (`~/.caruso/marketplaces/claude-code/`) for stability, while logical marketplace names (`claude-code-plugins`) come from the manifest, properly decoupling these concerns.
+
+## [0.3.0] - 2025-11-22
+
+### Changed
+- **BREAKING**: Refactored state management to use centralized `ConfigManager`
+- **BREAKING**: Split configuration into `caruso.json` (project settings) and `.caruso.local.json` (local state)
+- **BREAKING**: Plugins now installed to `.cursor/rules/caruso/` vendor directory
+- **BREAKING**: Removed `ManifestManager` class and `.cursor/rules/caruso.json` manifest file
+- Updated `init` command to create both config files and add local config to `.gitignore`
+- Updated plugin installation to use composite keys (`plugin@marketplace`) for uniqueness
+- Improved `uninstall` command to rely on strict file tracking in `.caruso.local.json`
+
+### Added
+- Vendor directory strategy for better separation of managed vs user files
+- Deterministic file tracking for robust uninstalls
+- Support for multiple marketplaces with same plugin names via composite keys
+
+## [0.2.0] - 2025-11-22
+
+### Added
+- **MarketplaceRegistry**: New persistent registry at `~/.caruso/known_marketplaces.json` tracking marketplace metadata
+- `marketplace info NAME` command to view detailed marketplace information (source, URL, location, last updated, ref, cache status)
+- Support for Git ref/branch pinning via `--ref` option on `marketplace add` command
+- Marketplace source type tracking (git, github, url, local, directory)
+- SSH authentication error detection with helpful error messages
+- Registry schema validation with corruption handling and automatic backups
+- `CARUSO_TESTING_SKIP_CLONE` environment variable for testing without network access
+
+### Changed
+- **BREAKING**: Marketplace cache moved from `/tmp/caruso_cache/` to `~/.caruso/marketplaces/<marketplace-name>/`
+- **BREAKING**: No backwards compatibility with previous cache location (clean break)
+- Marketplace metadata now persists across system reboots in registry
+- Fetcher tracks marketplace updates with timestamps
+- Comprehensive test suite with 22 new MarketplaceRegistry unit tests (all passing)
+
+### Fixed
+- Made `clone_git_repo` public for CLI access
+- Integration tests now skip Git cloning in test mode for reliable offline testing
+- All 158 test examples passing (0 failures)
+
+### Implementation Details
+This release adopts Claude Code's proven architecture patterns:
+- Persistent cache in `~/.caruso/` following XDG-style conventions
+- Metadata registry for tracking marketplace state
+- Git ref support for version pinning
+- Graceful error handling for network and authentication issues
+
+## [0.1.4] - 2025-11-21
+
+### Added
+- Support for custom component paths in marketplace entries (`commands`, `agents`, `skills` arrays)
+- Comprehensive unit test suite for fetcher with 9 tests covering all component types
+- Support for both string and array formats for custom component paths
+- File deduplication when paths appear in both default and custom locations
+
+### Changed
+- Fetcher now handles custom paths for all component types (commands, agents, skills) consistently
+- Custom paths now supplement (rather than replace) default directories as per specification
+- Test suite improvements with better success assertions and deterministic timing
+
+### Fixed
+- Plugin installation from anthropics/skills marketplace now works correctly
+- Integration tests reduced from 17 failures to 0 with proper assertions
+- Test isolation issues resolved for more reliable test runs
+
+### Added (Development)
+- Aruba for professional CLI testing
+- RuboCop as development dependency for code quality
+- Comprehensive improvement checklist in IMPROVEMENTS.md
+
+### Changed (Development)
+- Consolidated all dependencies to gemspec (removed duplication in Gemfile)
+- Updated RSpec to 3.13 for consistency
+- Simplified Gemfile to only contain source and gemspec
+
+## [0.1.3] - 2025-11-20
+
+### Changed
+- Updated caruso gem metadata and dependencies
+
+### Fixed
+- Improved error handling for missing marketplaces
+- Enhanced error messages when plugins are not found
+- Better error handling throughout plugin operations
+
+## [0.1.2] - 2025-11-20
+
+### Added
+- Rake tasks for automated semantic version bumping (`rake bump:patch`, `rake bump:minor`, `rake bump:major`)
+- Script to automate version management workflow
+
+### Fixed
+- Require `time` in config manager
+- Add `lib` directory to executable load path
+
+## [0.1.1] - 2025-11-19
+
+### Added
+- Cursor frontmatter now includes `alwaysApply: false` metadata
+- Ensures `globs: []` is set in Cursor frontmatter for proper scoping
+
+### Changed
+- Updated README mission statement to clarify Claude Code plugin conversion
+- Adapter now returns created filenames for proper plugin registration
+
+### Improved
+- Enhanced `init` command `--ide` flag tests
+- Better plugin network error handling in tests
+- Refactored file validation test setup
+
+## [0.1.0] - 2025-11-19
+
+### Added
+- Initial release of Caruso gem
+- Marketplace management commands (`marketplace add`, `marketplace list`, `marketplace remove`)
+- Plugin installation and uninstallation (`plugin install`, `plugin uninstall`, `plugin list`)
+- Configuration management with `.caruso.json`
+- Manifest tracking for installed plugins
+- Support for Cursor IDE integration
+- Git-based marketplace cloning and plugin fetching
+- Comprehensive integration test suite with RSpec
+- Documentation in README and TESTING.md
+
+### Features
+- Initialize Caruso in a project with `caruso init --ide=cursor`
+- Add multiple marketplaces from GitHub repositories
+- Install plugins from configured marketplaces
+- Track installed plugins in manifest file
+- Automatic conversion of Claude Code plugins to Cursor Rules format
+- Plugin metadata preservation and frontmatter injection
+
+[Unreleased]: https://github.com/pcomans/caruso/compare/v0.5.3...HEAD
+[0.5.3]: https://github.com/pcomans/caruso/releases/tag/v0.5.3
+[0.5.2]: https://github.com/pcomans/caruso/releases/tag/v0.5.2
+[0.5.1]: https://github.com/pcomans/caruso/releases/tag/v0.5.1
+[0.5.0]: https://github.com/pcomans/caruso/releases/tag/v0.5.0
+[0.4.0]: https://github.com/pcomans/caruso/releases/tag/v0.4.0
+[0.3.0]: https://github.com/pcomans/caruso/releases/tag/v0.3.0
+[0.2.0]: https://github.com/pcomans/caruso/releases/tag/v0.2.0
+[0.1.4]: https://github.com/pcomans/caruso/releases/tag/v0.1.4
+[0.1.3]: https://github.com/pcomans/caruso/releases/tag/v0.1.3
+[0.1.2]: https://github.com/pcomans/caruso/releases/tag/v0.1.2
+[0.1.1]: https://github.com/pcomans/caruso/releases/tag/v0.1.1
+[0.1.0]: https://github.com/pcomans/caruso/releases/tag/v0.1.0

data/CLAUDE.md

@@ -0,0 +1,276 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Mission
+
+Caruso is a Ruby gem CLI that bridges the gap between AI coding assistants. It fetches "steering documentation" (commands, agents, skills) from Claude Code Marketplaces and converts them to formats compatible with other IDEs, currently Cursor.
+
+## Source of Truth: Claude Code Documentation
+
+**IMPORTANT:** The official Claude Code marketplace and plugin specifications are located in `/Users/philipp/code/caruso/reference/`:
+
+- `marketplace.md` - Marketplace structure and specification
+- `plugins.md` - Plugin format and configuration
+- `plugins_reference.md` - Component configuration fields and metadata
+
+**These reference documents are the authoritative source for:**
+- Marketplace.json schema and plugin metadata format
+- Component configuration fields (`commands`, `agents`, `skills`, `hooks`, `mcpServers`)
+- Expected directory structures and file patterns
+- Metadata requirements and validation rules
+
+When implementing features or fixing bugs related to marketplace compatibility, **always consult these reference files first**. If the implementation conflicts with the reference docs, the reference docs are correct and the code should be updated to match.
+
+## Development Commands
+
+### Build and Install
+```bash
+# Build the gem
+gem build caruso.gemspec
+
+# Install locally
+gem install caruso-*.gem
+
+# Verify installation
+caruso version
+```
+
+### Testing
+```bash
+# Run offline tests only (default)
+bundle exec rake spec
+# or
+bundle exec rspec
+
+# Run all tests including live marketplace integration
+bundle exec rake spec:all
+# or
+RUN_LIVE_TESTS=1 bundle exec rspec
+
+# Run only live tests
+bundle exec rake spec:live
+
+# Run specific test file
+bundle exec rspec spec/integration/plugin_spec.rb
+
+# Run specific test
+bundle exec rspec spec/integration/plugin_spec.rb:42
+```
+
+**Important:** Live tests (tagged with `:live`) interact with real marketplaces (anthropics/skills) and require network access. They can be slow (~7 minutes). Marketplace cache is stored in `~/.caruso/marketplaces/`. Integration tests set `CARUSO_TESTING_SKIP_CLONE=true` to skip Git cloning for fast offline testing.
+
+### Linting
+```bash
+bundle exec rubocop
+```
+
+### Version Management
+```bash
+# Bump patch version (0.1.3 → 0.1.4)
+bundle exec rake bump:patch
+
+# Bump minor version (0.1.4 → 0.2.0)
+bundle exec rake bump:minor
+
+# Bump major version (0.1.4 → 1.0.0)
+bundle exec rake bump:major
+```
+
+## Architecture
+
+### Core Pipeline: Fetch → Adapt → Track
+
+Caruso follows a three-stage pipeline for plugin management:
+
+1. **Fetch** (`Fetcher`) - Clones Git repositories, resolves marketplace.json, finds plugin markdown files
+2. **Adapt** (`Adapter`) - Converts Claude Code markdown to target IDE format with metadata injection
+3. **Track** (`ConfigManager`) - Records installations in `caruso.json` and `.caruso.local.json`
+
+### Key Components
+
+#### ConfigManager (`lib/caruso/config_manager.rb`)
+Manages configuration and state. Splits data between:
+
+**1. Project Config (`caruso.json`)**
+- `ide`: Target IDE (currently only "cursor" supported)
+- `target_dir`: Where to write converted files (`.cursor/rules` for Cursor)
+- `marketplaces`: Name → URL mapping
+- `plugins`: Name → metadata (marketplace source)
+- `version`: Config schema version
+
+**2. Local Config (`.caruso.local.json`)**
+- `installed_files`: Plugin Name → Array of file paths
+- `initialized_at`: Timestamp
+
+Must run `caruso init --ide=cursor` before other commands. ConfigManager handles loading/saving both files and ensures `.caruso.local.json` is gitignored.
+
+#### MarketplaceRegistry (`lib/caruso/marketplace_registry.rb`)
+Manages persistent marketplace metadata registry at `~/.caruso/known_marketplaces.json`. Contains:
+- `source`: Marketplace type (git, github, url, local, directory)
+- `url`: Original marketplace URL
+- `install_location`: Local cache path (e.g., `~/.caruso/marketplaces/skills/`)
+- `last_updated`: ISO8601 timestamp of last update
+- `ref`: Optional Git ref/branch/tag for pinning
+
+**Key features:**
+- **Schema validation**: Validates required fields and timestamp format on load
+- **Corruption handling**: Backs up corrupted registry to `.corrupted.<timestamp>` and continues with empty registry
+- **Timestamp tracking**: Updates `last_updated` when marketplace cache is refreshed
+- **Source type tracking**: Enables future support for multiple marketplace sources
+
+This registry enables persistent tracking of marketplace state across reboots, unlike the previous `/tmp` approach.
+
+#### Fetcher (`lib/caruso/fetcher.rb`)
+Resolves and fetches plugins from marketplaces. Supports:
+- GitHub repos: `https://github.com/owner/repo`
+- Git URLs: Any Git-cloneable URL
+- Local paths: `./path/to/marketplace` or `./path/to/marketplace.json`
+
+**Key behavior:**
+- Clones Git repos to `~/.caruso/marketplaces/<marketplace-name>/` (persistent across reboots)
+- Registers marketplace metadata in `~/.caruso/known_marketplaces.json` (via MarketplaceRegistry)
+- Supports Git ref/branch pinning for version control
+- Reads `marketplace.json` to find available plugins
+- Supports custom component paths: plugins can specify `commands`, `agents`, `skills` arrays pointing to non-standard locations
+- Scans standard directories: `{commands,agents,skills}/**/*.md`
+- Excludes README.md and LICENSE.md files
+- **Custom paths supplement (not replace) default directories** - this is critical
+- Detects SSH authentication errors and provides helpful error messages
+
+**marketplace.json structure:**
+```json
+{
+  "plugins": [
+    {
+      "name": "document-skills",
+      "description": "Work with documents",
+      "source": "./document-skills",
+      "skills": ["./document-skills/xlsx", "./document-skills/pdf"]
+    }
+  ]
+}
+```
+
+The `commands`, `agents`, and `skills` fields accept:
+- String: `"./custom/path"`
+- Array: `["./path1", "./path2"]`
+
+Both files and directories are supported. Fetcher recursively finds all `.md` files.
+
+#### Adapter (`lib/caruso/adapter.rb`)
+Converts Claude Code markdown files to target IDE format. For Cursor:
+- Renames `.md` → `.mdc`
+- Injects YAML frontmatter with required Cursor metadata:
+  - `globs: []` - Enables semantic search (Apply Intelligently)
+  - `alwaysApply: false` - Prevents auto-application to every chat
+  - `description` - Preserved from original or generated
+- Preserves existing frontmatter if present, adds missing fields
+- Handles special case: `SKILL.md` → named after parent directory to avoid collisions
+
+Returns array of created filenames (not full paths) for manifest tracking.
+
+#### CLI (`lib/caruso/cli.rb`)
+Thor-based CLI with nested commands:
+- `caruso init [PATH] --ide=cursor`
+- `caruso marketplace add URL [--ref=BRANCH]` - Add marketplace with optional Git ref pinning (name comes from marketplace.json)
+- `caruso marketplace list` - List configured marketplaces
+- `caruso marketplace remove NAME` - Remove marketplace from manifest and registry
+- `caruso marketplace update [NAME]` - Update marketplace cache (all if no name given)
+- `caruso marketplace info NAME` - Show detailed marketplace information from registry
+- `caruso plugin install|uninstall|list|update|outdated`
+
+**Important patterns:**
+- All commands except `init` require existing `caruso.json` (enforced by `load_config` helper)
+- Plugin install format: `plugin@marketplace` or just `plugin` (if only one marketplace configured)
+- Update commands refresh marketplace cache (git pull) before fetching latest plugin files
+- Marketplace add eagerly clones repos unless `CARUSO_TESTING_SKIP_CLONE` env var is set (used in tests)
+- **Marketplace names always come from marketplace.json `name` field (required)** - no custom names allowed
+- Errors use descriptive messages with suggestions (e.g., "use 'caruso marketplace add <url>'")
+
+### Data Flow Example
+
+User runs: `caruso plugin install document-skills@skills`
+
+1. **CLI** parses command, loads config from `caruso.json`
+2. **ConfigManager** looks up marketplace "skills" URL
+3. **Fetcher** clones/updates marketplace repo to `~/.caruso/marketplaces/skills/`
+4. **Fetcher** registers/updates marketplace metadata in MarketplaceRegistry
+5. **Fetcher** reads `marketplace.json`, finds document-skills plugin
+6. **Fetcher** scans standard directories + custom paths from `skills: [...]` array
+7. **Fetcher** returns list of `.md` file paths
+8. **Adapter** converts each file: adds frontmatter, renames to `.mdc`, writes to `.cursor/rules/caruso/`
+9. **Adapter** returns created filenames
+10. **ConfigManager** records plugin in `caruso.json` and files in `.caruso.local.json`
+11. **CLI** prints success message
+
+### Testing Architecture
+
+Uses **Aruba** for CLI integration testing. Test structure:
+- `spec/unit/` - Direct class testing (ConfigManager, Fetcher logic)
+- `spec/integration/` - Full CLI workflow tests via Aruba subprocess execution
+
+**Aruba helpers in spec_helper.rb:**
+- `init_caruso(ide: "cursor")` - Runs init command with success assertion
+- `add_marketplace(url, name)` - Adds marketplace with success assertion
+- `config_file`, `manifest_file`, `load_config`, `load_manifest` - File access helpers
+- `mdc_files` - Glob for `.cursor/rules/*.mdc` files
+
+**Critical testing pattern:**
+```ruby
+run_command("caruso plugin install foo@bar")
+expect(last_command_started).to be_successfully_executed  # Always verify success first!
+manifest = load_manifest  # Then access results
+```
+
+**Why this matters:** If command fails, manifest might not exist (nil). Always assert success before accessing command results to prevent confusing test failures.
+
+**Live tests:**
+- Tagged with `:live` metadata
+- Run only when `RUN_LIVE_TESTS=1` environment variable set
+- Interact with real anthropics/skills marketplace
+- Cache cleared once at test suite start for performance
+- Use `sleep` for timestamp resolution (not `Timecop`) because Caruso runs as subprocess
+
+**Timecop limitation:** Cannot mock time in subprocesses. When testing timestamp updates in plugin reinstall scenarios, use `sleep 1.1` (ISO8601 has second precision) instead of `Timecop.travel`.
+
+## Marketplace Compatibility
+
+Caruso supports the Claude Code marketplace specification with custom component paths:
+
+- Standard structure: `{commands,agents,skills}/**/*.md`
+- Custom paths: `"commands": ["./custom/path"]` in marketplace.json
+- Both string and array formats supported
+- Custom paths **supplement** defaults (they don't replace)
+
+Example: anthropics/skills marketplace uses custom paths:
+```json
+{
+  "name": "document-skills",
+  "skills": ["./document-skills/xlsx", "./document-skills/pdf"]
+}
+```
+
+Fetcher will scan both:
+1. `./document-skills/skills/**/*.md` (default)
+2. `./document-skills/xlsx/**/*.md` (custom)
+3. `./document-skills/pdf/**/*.md` (custom)
+
+Results are deduplicated with `.uniq`.
+
+## Release Process
+
+1. Run tests: `bundle exec rake spec:all`
+2. Bump version: `bundle exec rake bump:patch` (or minor/major)
+3. Update CHANGELOG.md with release notes
+4. Commit: `git commit -m "chore: Bump version to X.Y.Z"`
+5. Tag: `git tag -a vX.Y.Z -m "Release version X.Y.Z"`
+6. Build: `gem build caruso.gemspec`
+7. Install and test: `gem install caruso-X.Y.Z.gem && caruso version`
+8. Push: `git push origin main --tags`
+
+Version is managed in `lib/caruso/version.rb`.
+
+# Memory
+- The goal is a clean, correct, consistent implementation. Never implement fallbacks that hide errors or engage in defensive programming.
+- Treat the vendor directory .cursor/rules/caruso/ as a build artifact