happyskills 0.35.5 → 0.37.0

package/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.37.0] - 2026-04-25
+
+### Added
+- Add unified content diffs to `diff` command — fetches base and local/remote file content for changed files, computes line-by-line unified diffs using the Myers O(ND) algorithm, and includes them in both CLI and JSON output
+- Add `--no-content` flag to `diff` command to skip content diffs and show only the file list (previous behavior)
+- Add `text_diff.js` utility module — lightweight Myers diff with unified diff formatting, no external dependencies
+- Add colored CLI diff output (red/green/cyan) matching standard unified diff conventions
+
+### Changed
+- Change `diff` JSON output to include `diff` field on each changed file entry with the unified diff text. For `both_modified` files, `local_diff` and `remote_diff` fields are provided instead
+
+## [0.36.0] - 2026-04-17
+
+### Added
+- Add 6 dependency validation rules to `validate` command: `dep-self-reference` (skill depends on itself), `dep-exists` (all declared deps exist in registry), `dep-visibility-direct` (public skill's direct deps must be public), `dep-visibility-transitive` (full transitive tree visibility check), `dep-visibility-workspace` (warning for workspace-scoped deps on public skills), `dep-circular` (DFS cycle detection on the full dependency tree). Registry checks run when authenticated; local-only checks run otherwise with an info message suggesting login.
+- Add `extract_root_cause()` and `format_error_chain()` utilities in `utils/errors.js` for cleaner error diagnostics across all commands
+
+### Changed
+- Replace ad-hoc dependency existence check in `publish` with the new validation rules — dependency visibility errors now block publish with clear, actionable messages
+- Change `install` resolver to return `{ packages, skipped }` instead of a flat packages array. Installer prints categorized warnings for skipped deps after install: access-denied suggests `happyskills login`, not-found lists missing skill names. `skipped_deps` is included in the result object and JSON output.
+- Show root cause in `install` error messages (e.g. "Access denied: nicolasdao/init-mission") instead of the generic wrapper ("Install failed"). JSON mode error output now includes a `details` array with the full error chain.
+
+### Fixed
+- Fix `search --workspace <slug>` triggering AuthError when not logged in — only `--mine` and `--personal` flags require authentication; `--workspace` returns public skills without auth
+
 ## [0.35.5] - 2026-04-11
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.35.5",
+	"version": "0.37.0",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/api/repos.js

@@ -10,7 +10,7 @@ const search = (query, options = {}) => catch_errors('Search failed', async () =
 	if (options.workspace) params.set('workspace', options.workspace)
 	if (options.tags) params.set('tags', options.tags)
 	if (options.type) params.set('type', options.type)
-	const needs_auth = (options.scope && options.scope !== 'public') || options.workspace
+	const needs_auth = options.scope && options.scope !== 'public'
 	const [errors, data] = await client.get(`/repos/search?${params}`, { auth: needs_auth || false })
 	if (errors) throw errors[errors.length - 1]
 	return data

package/src/commands/diff.js

@@ -2,19 +2,20 @@ const fs = require('fs')
 const path = require('path')
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const repos_api = require('../api/repos')
-const { detect_status } = require('../merge/detector')
 const { classify_changes } = require('../merge/comparator')
 const { build_report } = require('../merge/report')
 const { hash_blob } = require('../utils/git_hash')
+const { unified_diff } = require('../utils/text_diff')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
 const { find_project_root, lock_root, skills_dir, skill_install_dir } = require('../config/paths')
 const { print_help, print_info, print_json, print_warn, code } = require('../ui/output')
+const { red, green, cyan, bold } = require('../ui/colors')
 const { exit_with_error, UsageError } = require('../utils/errors')
 const { EXIT_CODES } = require('../constants')
 
 const HELP_TEXT = `Usage: happyskills diff <owner/skill> [options]
 
-Show file-level differences for a skill.
+Show file-level differences for a skill with unified diffs.
 
 Arguments:
   owner/skill       Skill to diff (required)
@@ -22,6 +23,7 @@ Arguments:
 Options:
   --remote          Show base vs remote changes (default: local vs base)
   --full            Show three-way diff (base vs local vs remote)
+  --no-content      Show only file list without content diffs
   -g, --global      Diff globally installed skill
   --json            Output as JSON
 
@@ -30,7 +32,8 @@ Aliases: d
 Examples:
   happyskills diff acme/deploy-aws
   happyskills diff acme/deploy-aws --remote
-  happyskills diff acme/deploy-aws --full`
+  happyskills diff acme/deploy-aws --full
+  happyskills diff acme/deploy-aws --no-content`
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -64,6 +67,98 @@ const STATUS_LABELS = {
 	local_only_deleted: 'D (local)'
 }
 
+const DIFF_CLASSIFICATIONS = new Set([
+	'local_only_modified', 'local_only_added', 'local_only_deleted',
+	'remote_only_modified', 'remote_only_added', 'remote_only_deleted',
+	'both_modified'
+])
+
+// ─── Content diff enrichment ─────────────────────────────────────────────────
+
+/**
+ * Enrich report file entries with unified diffs for changed files.
+ *
+ * Memory strategy:
+ * - Only decode/read content for files whose SHAs actually differ
+ * - Local file reads run concurrently via Promise.all
+ * - All content maps are cleared after diffs are computed
+ *
+ * @param {object} report - The merge report with file entries
+ * @param {Array} base_clone_files - Raw clone response files (with base64 content)
+ * @param {string|null} skill_dir - Local skill directory (null if local content not needed)
+ * @param {Array|null} remote_clone_files - Raw remote clone files (null if not needed)
+ */
+const enrich_with_diffs = (report, base_clone_files, skill_dir, remote_clone_files) => catch_errors('Failed to compute content diffs', async () => {
+	const changed = report.files.filter(f => DIFF_CLASSIFICATIONS.has(f.classification))
+	if (changed.length === 0) return
+
+	const changed_paths = new Set(changed.map(f => f.path))
+
+	// Build base content map — only decode changed paths from the clone response
+	const base_map = new Map()
+	for (const f of (base_clone_files || [])) {
+		if (changed_paths.has(f.path) && f.content) {
+			base_map.set(f.path, Buffer.from(f.content, 'base64').toString('utf-8'))
+		}
+	}
+
+	// Build remote content map — same selective decode
+	const remote_map = new Map()
+	for (const f of (remote_clone_files || [])) {
+		if (changed_paths.has(f.path) && f.content) {
+			remote_map.set(f.path, Buffer.from(f.content, 'base64').toString('utf-8'))
+		}
+	}
+
+	// Read local content concurrently — only files that exist locally
+	const local_map = new Map()
+	if (skill_dir) {
+		const needs_local = changed.filter(f => f.local_sha)
+		const results = await Promise.all(needs_local.map(async f => {
+			try {
+				const content = await fs.promises.readFile(path.join(skill_dir, f.path), 'utf-8')
+				return { path: f.path, content }
+			} catch {
+				return null
+			}
+		}))
+		for (const r of results) {
+			if (r) local_map.set(r.path, r.content)
+		}
+	}
+
+	// Compute unified diffs — CPU-only, no I/O
+	for (const f of changed) {
+		const base = base_map.get(f.path) ?? ''
+		const local = local_map.get(f.path) ?? ''
+		const remote = remote_map.get(f.path) ?? ''
+
+		switch (f.classification) {
+		case 'local_only_modified':
+		case 'local_only_added':
+		case 'local_only_deleted':
+			f.diff = unified_diff(base, local, `base/${f.path}`, `local/${f.path}`)
+			break
+		case 'remote_only_modified':
+		case 'remote_only_added':
+		case 'remote_only_deleted':
+			f.diff = unified_diff(base, remote, `base/${f.path}`, `remote/${f.path}`)
+			break
+		case 'both_modified':
+			f.local_diff = unified_diff(base, local, `base/${f.path}`, `local/${f.path}`)
+			f.remote_diff = unified_diff(base, remote, `base/${f.path}`, `remote/${f.path}`)
+			break
+		}
+	}
+
+	// Flush content maps to release memory
+	base_map.clear()
+	remote_map.clear()
+	local_map.clear()
+})
+
+// ─── CLI output ──────────────────────────────────────────────────────────────
+
 const print_file_table = (classified) => {
 	const lines = []
 	for (const [category, label] of Object.entries(STATUS_LABELS)) {
@@ -84,6 +179,44 @@ const print_file_table = (classified) => {
 	}
 }
 
+const print_colored_diff = (diff_text) => {
+	if (!diff_text) return
+	for (const line of diff_text.split('\n')) {
+		if (line.startsWith('---') || line.startsWith('+++')) {
+			console.log(bold(line))
+		} else if (line.startsWith('@@')) {
+			console.log(cyan(line))
+		} else if (line.startsWith('+')) {
+			console.log(green(line))
+		} else if (line.startsWith('-')) {
+			console.log(red(line))
+		} else {
+			console.log(line)
+		}
+	}
+}
+
+const print_report_diffs = (report) => {
+	const has_diffs = report.files.some(f => f.diff || f.local_diff || f.remote_diff)
+	if (!has_diffs) return
+
+	console.log('')
+	for (const f of report.files) {
+		if (f.diff) {
+			print_colored_diff(f.diff)
+			console.log('')
+		}
+		if (f.local_diff) {
+			print_colored_diff(f.local_diff)
+			console.log('')
+		}
+		if (f.remote_diff) {
+			print_colored_diff(f.remote_diff)
+			console.log('')
+		}
+	}
+}
+
 // ─── Main ─────────────────────────────────────────────────────────────────────
 
 const run = (args) => catch_errors('Diff failed', async () => {
@@ -99,6 +232,7 @@ const run = (args) => catch_errors('Diff failed', async () => {
 
 	const is_global = args.flags.global || false
 	const mode = args.flags.full ? 'full' : args.flags.remote ? 'remote' : 'local'
+	const skip_content = args.flags['no-content'] || false
 	const project_root = find_project_root()
 
 	// Read lock
@@ -114,29 +248,33 @@ const run = (args) => catch_errors('Diff failed', async () => {
 	const base_dir = skills_dir(is_global, project_root)
 	const skill_dir = skill_install_dir(base_dir, repo)
 
-	// Always need base files
+	// Always need base files — keep full clone response for content diffs
 	const [base_err, base_clone] = await repos_api.clone(owner, repo, null, { commit: lock_entry.base_commit })
 	if (base_err) throw e('Failed to fetch base files', base_err)
 	const base_files = (base_clone.files || []).map(f => ({ path: f.path, sha: f.sha }))
 
 	if (mode === 'local') {
-		// Local vs base — use classify_changes with base as the "remote" side
 		const [local_err, local_files] = await build_local_entries(skill_dir)
 		if (local_err) throw e('Failed to read local files', local_err)
 
 		const classified = classify_changes(base_files, local_files, base_files)
+		const report = build_report(skill_name, lock_entry.version, lock_entry.version, classified)
+
+		if (!skip_content) {
+			const [enrich_err] = await enrich_with_diffs(report, base_clone.files, skill_dir, null)
+			if (enrich_err) throw e('Content diff failed', enrich_err)
+		}
 
 		if (args.flags.json) {
-			const report = build_report(skill_name, lock_entry.version, lock_entry.version, classified)
 			print_json({ data: { mode, report } })
 		} else {
 			print_file_table(classified)
+			print_report_diffs(report)
 		}
 		return
 	}
 
 	if (mode === 'remote') {
-		// Base vs remote — get head commit via compare, clone at that commit
 		const [cmp_err, cmp_data] = await repos_api.compare(owner, repo, lock_entry.base_commit)
 		if (cmp_err) throw e('Compare failed', cmp_err)
 
@@ -145,17 +283,23 @@ const run = (args) => catch_errors('Diff failed', async () => {
 		const remote_files = (remote_clone.files || []).map(f => ({ path: f.path, sha: f.sha }))
 
 		const classified = classify_changes(base_files, base_files, remote_files)
+		const report = build_report(skill_name, lock_entry.version, cmp_data.head_version, classified)
+
+		if (!skip_content) {
+			const [enrich_err] = await enrich_with_diffs(report, base_clone.files, null, remote_clone.files)
+			if (enrich_err) throw e('Content diff failed', enrich_err)
+		}
 
 		if (args.flags.json) {
-			const report = build_report(skill_name, lock_entry.version, cmp_data.head_version, classified)
 			print_json({ data: { mode, report } })
 		} else {
 			print_file_table(classified)
+			print_report_diffs(report)
 		}
 		return
 	}
 
-	// Full three-way diff — get head commit via compare
+	// Full three-way diff
 	const [cmp_err, cmp_data] = await repos_api.compare(owner, repo, lock_entry.base_commit)
 	if (cmp_err) throw e('Compare failed', cmp_err)
 
@@ -169,10 +313,16 @@ const run = (args) => catch_errors('Diff failed', async () => {
 	const classified = classify_changes(base_files, local_files, remote_files)
 	const report = build_report(skill_name, lock_entry.version, cmp_data.head_version, classified)
 
+	if (!skip_content) {
+		const [enrich_err] = await enrich_with_diffs(report, base_clone.files, skill_dir, remote_clone.files)
+		if (enrich_err) throw e('Content diff failed', enrich_err)
+	}
+
 	if (args.flags.json) {
 		print_json({ data: { mode, report } })
 	} else {
 		print_file_table(classified)
+		print_report_diffs(report)
 		if (report.summary.conflicted > 0) {
 			console.error('')
 			print_warn(`${report.summary.conflicted} file(s) modified on both sides`)

package/src/commands/install.js

@@ -107,7 +107,8 @@ const run = (args) => catch_errors('Install failed', async () => {
 		const version = flag_version || inline_version
 		const [errors, result] = await install(skill, { ...base_options, version })
 		if (errors) {
-			const msg = errors[0]?.message || errors.message || String(errors)
+			const chain = errors?.map ? errors.map(x => x?.message).filter(Boolean) : [errors?.message || String(errors)]
+			const msg = chain[chain.length - 1] || chain[0] || 'Unknown error'
 			print_warn(`Failed to install ${skill}: ${msg}`)
 			failures.push({ skill, error: msg })
 		} else {
@@ -116,7 +117,8 @@ const run = (args) => catch_errors('Install failed', async () => {
 	}
 
 	if (results.length === 0 && failures.length > 0) {
-		throw new Error(`All ${failures.length} install(s) failed.`)
+		const detail = failures.map(f => `${f.skill}: ${f.error}`).join('; ')
+		throw new Error(detail)
 	}
 
 	if (args.flags.json) {
@@ -125,6 +127,7 @@ const run = (args) => catch_errors('Install failed', async () => {
 			version: result.version,
 			installed: result.installed || [],
 			skipped: result.skipped || [],
+			skipped_deps: result.skipped_deps || [],
 			warnings: result.warnings || [],
 			forced: result.forced || []
 		}))

package/src/commands/publish.js

@@ -18,6 +18,7 @@ const { validate_skill_json } = require('../validation/skill_json_rules')
 const { validate_cross } = require('../validation/cross_rules')
 const { validate_no_conflict_markers } = require('../validation/conflict_marker_rules')
 const { validate_file_sizes } = require('../validation/file_size_rules')
+const { validate_dependencies } = require('../validation/dependency_rules')
 const { create_spinner } = require('../ui/spinner')
 const { print_help, print_success, print_error, print_warn, print_hint, print_json, code, summarize_warnings } = require('../ui/output')
 const { exit_with_error, UsageError, CliError } = require('../utils/errors')
@@ -144,21 +145,46 @@ const run = (args) => catch_errors('Publish failed', async () => {
 
 	if (manifest.dependencies && Object.keys(manifest.dependencies).length > 0) {
 		spinner.update('Checking dependencies...')
-		const dep_entries = Object.keys(manifest.dependencies)
-		const dep_results = await Promise.all(dep_entries.map(async (dep) => {
-			const parts = dep.split('/')
-			if (parts.length !== 2) return { dep, missing: true }
-			const [dep_owner, dep_name] = parts
-			const [err] = await repos_api.get_repo(dep_owner, dep_name, { auth: true })
-			return { dep, missing: !!err }
-		}))
-		const missing = dep_results.filter(r => r.missing)
-		if (missing.length > 0) {
-			spinner.fail('Dependency check failed')
-			for (const { dep } of missing) {
-				print_warn(`Dependency "${dep}" not found in the registry.`)
+		const full_name = `${workspace.slug}/${manifest.name}`
+		const [dep_err, dep_results] = await validate_dependencies(dir, manifest, {
+			registry: true,
+			visibility,
+			full_name
+		})
+		if (!dep_err && dep_results) {
+			const dep_errors = dep_results.filter(r => r.severity === 'error')
+			const dep_warnings = dep_results.filter(r => r.severity === 'warning')
+
+			if (dep_errors.length > 0) {
+				spinner.fail('Dependency check failed')
+				if (is_json_mode()) {
+					const structured = dep_errors.map(({ severity, ...rest }) => rest)
+					print_json({
+						error: {
+							code: 'DEPENDENCY_VALIDATION_FAILED',
+							message: `${dep_errors.length} dependency error(s) found. Fix these issues and try again.`,
+							exit_code: EXIT_CODES.ERROR,
+							validation_errors: structured
+						}
+					})
+					return process.exit(EXIT_CODES.ERROR)
+				}
+				for (const r of dep_errors) {
+					print_error(r.message)
+				}
+				return process.exit(EXIT_CODES.ERROR)
 			}
+
+			if (dep_warnings.length > 0 && !is_json_mode()) {
+				for (const r of dep_warnings) {
+					print_warn(r.message)
+				}
+			}
+
+			// Accumulate dep warnings for JSON output
+			validation_warnings.push(...dep_warnings)
 		}
+		spinner.update('Preparing to publish...')
 	}
 
 	// Read base_commit and merge_parents from lock file for divergence check

package/src/commands/search.js

@@ -236,7 +236,7 @@ const run = (args) => catch_errors('Search failed', async () => {
 
 	const scope = mine ? 'mine' : personal ? 'personal' : undefined
 
-	if (has_scope_flag) {
+	if (mine || personal) {
 		const [, token_data] = await load_token()
 		if (!token_data) {
 			throw new AuthError('Authentication required. Run `happyskills login` first.')

package/src/commands/validate.js

@@ -6,9 +6,12 @@ const { validate_cross } = require('../validation/cross_rules')
 const { validate_no_conflict_markers } = require('../validation/conflict_marker_rules')
 const { validate_file_sizes } = require('../validation/file_size_rules')
 const { validate_changelog_version } = require('../validation/changelog_rules')
+const { validate_dependencies } = require('../validation/dependency_rules')
 const { file_exists, read_json } = require('../utils/fs')
-const { skills_dir, find_project_root } = require('../config/paths')
-const { print_help, print_json } = require('../ui/output')
+const { skills_dir, find_project_root, lock_root } = require('../config/paths')
+const { read_lock, get_all_locked_skills } = require('../lock/reader')
+const { load_token } = require('../auth/token_store')
+const { print_help, print_json, print_info } = require('../ui/output')
 const { bold, green, yellow, red, dim } = require('../ui/colors')
 const { exit_with_error, UsageError } = require('../utils/errors')
 const { EXIT_CODES, SKILL_MD, SKILL_JSON, SKILL_TYPES } = require('../constants')
@@ -154,7 +157,47 @@ const run = (args) => catch_errors('Validate failed', async () => {
 	const [cl_err, cl_results] = await validate_changelog_version(skill_dir, json_data.manifest)
 	if (cl_err) throw cl_err
 
-	const all_results = [...md_data.results, ...json_data.results, ...cross_results, ...marker_results, ...size_results, ...cl_results]
+	// Dependency validation — registry checks when authenticated
+	let dep_results = []
+	const manifest = json_data.manifest || {}
+	if (manifest.dependencies && Object.keys(manifest.dependencies).length > 0) {
+		const [, token_data] = await load_token()
+		const has_registry = !!token_data
+
+		// Resolve the full owner/name for registry lookups
+		let full_name = null
+		let visibility = 'private'
+		if (has_registry) {
+			const project_root = find_project_root()
+			const [, lock_data] = await read_lock(lock_root(is_global, project_root))
+			if (lock_data) {
+				const all_skills = get_all_locked_skills(lock_data)
+				const suffix = `/${skill_name}`
+				const lock_key = Object.keys(all_skills).find(k => k.endsWith(suffix))
+				if (lock_key) full_name = lock_key
+			}
+			// Try to get visibility from registry if we have the full name
+			if (full_name) {
+				const repos_api = require('../api/repos')
+				const [owner, name] = full_name.split('/')
+				const [, repo_data] = await repos_api.get_repo(owner, name, { auth: true })
+				if (repo_data) visibility = repo_data.visibility || 'private'
+			}
+		}
+
+		const [dep_err, dep_result] = await validate_dependencies(skill_dir, manifest, {
+			registry: has_registry,
+			visibility,
+			full_name
+		})
+		if (!dep_err && dep_result) dep_results = dep_result
+
+		if (!has_registry && !args.flags.json) {
+			print_info('Dependency registry checks skipped (not logged in). Log in for full validation.')
+		}
+	}
+
+	const all_results = [...md_data.results, ...json_data.results, ...cross_results, ...marker_results, ...size_results, ...cl_results, ...dep_results]
 	const type_label = is_kit ? ' [kit]' : ''
 
 	if (args.flags.json) {

package/src/engine/installer.js

@@ -73,14 +73,17 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 	const spinner = create_spinner(`Resolving dependencies for ${skill}...`)
 
 	let packages
+	let skipped_deps = []
 	if (force) {
 		const [errors, result] = await resolve_with_force(skill, version || 'latest', {})
 		if (errors) { spinner.fail('Resolution failed'); throw e('Resolution failed', errors) }
-		packages = result
+		packages = result.packages
+		skipped_deps = result.skipped || []
 	} else {
 		const [errors, result] = await resolve(skill, version || 'latest', {})
 		if (errors) { spinner.fail('Resolution failed'); throw e('Resolution failed', errors) }
-		packages = result
+		packages = result.packages
+		skipped_deps = result.skipped || []
 	}
 
 	// Filter out packages already installed at the resolved version (handles @latest efficiently)
@@ -270,6 +273,29 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 			}
 		}
 
+		// Warn about skipped dependencies (access-denied, not found, etc.)
+		if (skipped_deps.length > 0) {
+			const access_denied = skipped_deps.filter(s => s.reason === 'access_denied')
+			const not_found = skipped_deps.filter(s => s.reason === 'not_found')
+			const other = skipped_deps.filter(s => s.reason !== 'access_denied' && s.reason !== 'not_found')
+			if (access_denied.length > 0) {
+				print_warn(`${access_denied.length} dependenc${access_denied.length === 1 ? 'y' : 'ies'} skipped (private, requires login):`)
+				for (const s of access_denied) {
+					print_warn(`  ${s.skill} (required by ${s.required_by})`)
+				}
+				print_info(`Log in to install: happyskills login`)
+			}
+			if (not_found.length > 0) {
+				print_warn(`${not_found.length} dependenc${not_found.length === 1 ? 'y' : 'ies'} skipped (not found in registry):`)
+				for (const s of not_found) {
+					print_warn(`  ${s.skill} (required by ${s.required_by})`)
+				}
+			}
+			for (const s of other) {
+				print_warn(`Skipped ${s.skill}: ${s.message}`)
+			}
+		}
+
 		const installed_set = new Set(packages_to_install.map(p => p.skill))
 		const installed = packages_to_install.map(p => ({ skill: p.skill, version: p.version }))
 		const skipped = packages.filter(p => !installed_set.has(p.skill)).map(p => ({ skill: p.skill, version: p.version, reason: 'already installed' }))
@@ -277,7 +303,7 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 		const forced = forced_pkgs.map(p => ({ skill: p.skill, version: p.version }))
 
 		const linked_agents = agents.map(a => a.id)
-		return { skill, version: packages[0]?.version, no_op: false, installed, skipped, warnings, forced, packages: packages_to_install.length, linked_agents }
+		return { skill, version: packages[0]?.version, no_op: false, installed, skipped, skipped_deps, warnings, forced, packages: packages_to_install.length, linked_agents }
 	} catch (err) {
 		await remove_dir(temp_dir)
 		throw err

package/src/engine/resolver.js

@@ -12,7 +12,7 @@ const resolve = (skill, version, installed = {}) => catch_errors('Dependency res
 		throw new Error(`Dependency conflicts detected:\n${conflict_msg}\n\nUse --force to install anyway (takes highest version).`)
 	}
 
-	return result.packages || []
+	return { packages: result.packages || [], skipped: result.skipped || [] }
 })
 
 const resolve_with_force = (skill, version, installed = {}) => catch_errors('Forced resolution failed', async () => {
@@ -30,7 +30,7 @@ const resolve_with_force = (skill, version, installed = {}) => catch_errors('For
 		}
 	}
 
-	return packages
+	return { packages, skipped: result.skipped || [] }
 })
 
 module.exports = { resolve, resolve_with_force }

package/src/utils/errors.js

@@ -49,15 +49,32 @@ const is_usage_error = (err) => {
 	return false
 }
 
+const extract_root_cause = (err) => {
+	if (!Array.isArray(err)) return err?.message || 'An unexpected error occurred'
+	// Walk the error array to find the deepest, most specific message.
+	// catch_errors wraps errors outermost-first: [outermost, ..., root_cause].
+	// We prefer the last error (root cause) for the user-facing message,
+	// but fall back to the first CliError if one exists.
+	const messages = err.map(x => x?.message).filter(Boolean)
+	if (messages.length === 0) return 'An unexpected error occurred'
+	// The last message is typically the root cause (deepest in the chain)
+	return messages[messages.length - 1]
+}
+
+const format_error_chain = (err) => {
+	if (!Array.isArray(err)) return [err?.stack || err?.message || String(err)]
+	return err.map(x => x?.stack || x?.message || String(x)).filter(Boolean)
+}
+
 const get_error_info = (err) => {
 	let target = err
 	if (Array.isArray(err)) {
-		target = err.find(e => e instanceof CliError) || err[0]
+		target = err.find(e => e instanceof CliError) || err[err.length - 1] || err[0]
 	}
 
 	let code = 'ERROR'
 	let exit_code = EXIT_CODES.ERROR
-	const message = target?.message || 'An unexpected error occurred'
+	const message = extract_root_cause(err)
 
 	if (target instanceof UsageError) {
 		code = 'USAGE_ERROR'; exit_code = EXIT_CODES.USAGE
@@ -80,7 +97,10 @@ const exit_with_error = (err) => {
 
 	if (is_json_mode()) {
 		const { code, message, exit_code } = get_error_info(err)
-		console.log(JSON.stringify({ error: { code, message, exit_code } }, null, 2))
+		const chain = format_error_chain(err)
+		const json_err = { code, message, exit_code }
+		if (chain.length > 1) json_err.details = chain
+		console.log(JSON.stringify({ error: json_err }, null, 2))
 		process.exit(exit_code)
 		return
 	}
@@ -89,33 +109,11 @@ const exit_with_error = (err) => {
 	const { write_error_log } = require('./logger')
 
 	const log_path = is_usage_error(err) ? null : write_error_log(err)
+	const { message, exit_code } = get_error_info(err)
 
-	if (err instanceof CliError) {
-		print_error(err.message)
-		print_log_hint(log_path)
-		process.exit(err.exit_code)
-		return
-	}
-
-	if (Array.isArray(err)) {
-		for (const e of err) {
-			if (e instanceof CliError) {
-				print_error(e.message)
-				print_log_hint(log_path)
-				process.exit(e.exit_code)
-				return
-			}
-		}
-		print_error(err[0]?.message || 'An unexpected error occurred')
-		print_log_hint(log_path)
-		process.exit(EXIT_CODES.ERROR)
-		return
-	}
-
-	const message = err.message || 'An unexpected error occurred'
 	print_error(message)
 	print_log_hint(log_path)
-	process.exit(EXIT_CODES.ERROR)
+	process.exit(exit_code)
 }
 
 module.exports = { CliError, UsageError, AuthError, NetworkError, ApiError, exit_with_error }