happyskills 1.9.0 → 1.10.1

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.10.1] - 2026-06-09
+
+### Fixed
+
+- Fix `uninstall` leaving deep transitive dependencies stranded. Orphan pruning ran a single pass, so removing a skill (or kit / constellation core) pruned its direct dependencies but left behind any *grandchild* dependency whose only parent was one of those now-pruned dependencies — it accumulated as unused cruft in `.agents/skills/` and the lock file. Pruning now cascades to a fixed point, removing the full chain of newly-orphaned dependencies. The data-loss guard is preserved: a dependency that any surviving skill still declares (e.g. a shared satellite like `happyskills-design`) is never pruned, and directly-installed (`__root__`) skills are never swept up.
+
+## [1.10.0] - 2026-06-06
+
+### Added
+
+- Add the `resolve` command — `happyskills resolve "<intent>"` maps a natural-language intent to the skill that owns it, whether that skill is installed, and how to install it if not. It matches the intent against installed skills' declared capabilities first (deterministic); if none match, it falls back to registry search gated on the server's `match_quality` (returning a `probabilistic_match`-flagged suggestion for a strong/good hit, or a graceful empty result for gibberish). Read-only; no auth required for public skills.
+- Extend `happyskills schema --json` with a skill-declared capability registry: a top-level `data.skills[]` (each installed skill's `capabilities` declarations — `name`, `slug`, `version`, `bundled`, and `capabilities[]`) plus a per-command `owner_skill` field. Both are aggregated from installed skills' `skill.json` `capabilities`, never a hardcoded table, so an agent can map a command or intent to its owning skill deterministically.
+
+### Changed
+
+- Broaden `next_step.route_to_skill` coverage so a mis-routed recovery names the skill that should handle it: `VALIDATION_FAILED`, `DEPENDENCY_VALIDATION_FAILED`, `MISSING_CHANGELOG_ENTRY`, and `CHANGELOG_SOURCE_UNREADABLE` now route to `happyskills-publish`, and a new `CONFLICT` default routes to `happyskills-sync` (joining the existing `DRIFT_DETECTED` / `DIVERGED`). No new `error.code` or `next_step.action` values.
+
 ## [1.9.0] - 2026-06-06
 
 ### Fixed

package/package.json

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

package/src/commands/resolve.js

@@ -0,0 +1,325 @@
+'use strict'
+// happyskills resolve "<intent>" — spec 260606-01 Phase 4b.
+//
+// Read-only intent resolver. Given a natural-language intent, return a grounded
+// envelope naming the capability, its owning skill, whether that skill is
+// installed, and (when not) how to install it. CLI-only orchestration over the
+// §4.1 skill-declared ownership map (deterministic) + the existing registry
+// search endpoint (probabilistic fallback). No server-side endpoint, no in-CLI
+// LLM call — the matching is string/registry-based; the *agent* supplies the
+// intelligence by calling `resolve` and reading the result.
+//
+// Resolution order (deterministic-first):
+//   2a. Match the intent against INSTALLED skills' declared capability.intents.
+//       A confident local match returns installed:true — fully deterministic.
+//   2b. Otherwise query the registry for a skill/capability covering the intent
+//       and return the top candidate with installed:false + an install command.
+//       HONEST CAVEAT: step 2b leans on semantic registry search, which is
+//       PROBABILISTIC. `resolve` grounds it in the real registry rather than the
+//       LLM's memory — it does not make it deterministic. Do not over-trust a
+//       not-installed match.
+
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { build_ownership } = require('./schema')
+const repos_api = require('../api/repos')
+const { print_help, print_info, print_hint } = require('../ui/output')
+const { bold, dim, cyan, gray } = require('../ui/colors')
+const { emit_envelope } = require('../ui/envelope')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills resolve "<intent>" [options]
+
+Resolve a natural-language intent to the HappySkills skill that owns it, whether
+that skill is installed, and how to install it if not.
+
+Resolution is deterministic-first: a confident match against an INSTALLED skill's
+declared capabilities returns installed:true and is fully deterministic. If no
+installed skill matches, resolve falls back to the registry — that step is
+semantic search and is PROBABILISTIC; treat a not-installed match as a grounded
+suggestion, not a guarantee.
+
+Arguments:
+  intent            A natural-language description of what you want to do
+
+Options:
+  --json            Output as JSON envelope (default for non-TTY callers)
+
+Examples:
+  happyskills resolve "how many people installed my skills"
+  happyskills resolve "invite alice to my workspace" --json`
+
+// ── deterministic local matcher (pure; exported for tests) ───────────────────
+
+const STOPWORDS = new Set([
+	'a', 'an', 'the', 'my', 'me', 'i', 'to', 'of', 'for', 'is', 'are', 'be',
+	'do', 'does', 'did', 'how', 'what', 'which', 'can', 'could', 'would', 'you',
+	'please', 'with', 'on', 'in', 'it', 'this', 'that', 'and', 'or', 'your',
+	'we', 'us', 'am', 'have', 'has', 'had', 'about', 'into', 'from', 'so',
+])
+
+const tokenize = (s) => String(s || '')
+	.toLowerCase()
+	.replace(/[^a-z0-9]+/g, ' ')
+	.split(' ')
+	.filter(t => t.length >= 2 && !STOPWORDS.has(t))
+
+// Coverage of an intent phrase's significant tokens by the query token set,
+// plus the raw count of shared tokens (used by the confidence gate).
+const score_intent = (query_set, intent_phrase) => {
+	const it = [...new Set(tokenize(intent_phrase))]
+	if (it.length === 0) return { score: 0, shared: 0 }
+	let shared = 0
+	for (const t of it) if (query_set.has(t)) shared++
+	return { score: shared / it.length, shared }
+}
+
+// Best (skill, capability, intent) match across all declared capabilities of the
+// installed skills. Returns null when nothing overlaps. A query token that
+// equals one of a capability's owned command names is treated as a strong
+// signal (score floored to 1).
+const match_local = (intent, skills) => {
+	const query_set = new Set(tokenize(intent))
+	if (query_set.size === 0) return null
+	let best = null
+	for (const skill of skills || []) {
+		for (const cap of skill.capabilities || []) {
+			for (const phrase of cap.intents || []) {
+				const { score, shared } = score_intent(query_set, phrase)
+				if (shared > 0 && (!best || score > best.score || (score === best.score && shared > best.shared))) {
+					best = { skill, capability: cap, intent_phrase: phrase, score, shared }
+				}
+			}
+			// Command-name hit — ONLY when the query IS essentially the bare
+			// command (a single content token, e.g. "publish" or "stats").
+			// Command names are often common English words (access, check, list,
+			// star, status, diff, pull, update...), so matching one inside a
+			// longer, unrelated query produces confident false positives — e.g.
+			// "access the database" → collab, "check the weather" → core. Gating
+			// on a single-token query keeps bare-command resolution while leaving
+			// multi-word phrasing to the intent matcher.
+			if (query_set.size === 1) {
+				for (const cmd of cap.commands || []) {
+					if (query_set.has(cmd.toLowerCase())) {
+						const cand = { skill, capability: cap, intent_phrase: cap.intents?.[0] || cmd, score: 1, shared: 1 }
+						if (!best || cand.score > best.score) best = cand
+					}
+				}
+			}
+		}
+	}
+	return best
+}
+
+// Confidence gate. Deliberately coarse — this is a deterministic floor, not a
+// ranker (spec §6.5: do not tune ranking). Two shared significant tokens at ≥50%
+// coverage, OR a near-exact single-strong match (≥80% coverage).
+const is_confident = (m) => !!m && ((m.shared >= 2 && m.score >= 0.5) || m.score >= 0.8)
+
+// Registry-fallback relevance floor (pure; exported for tests).
+// Semantic search almost always returns SOMETHING, so taking items[0] blindly
+// turns gibberish into a confident install instruction for an unrelated skill
+// (spec §3 Phase-4b requires gibberish → graceful empty). relevance_score is
+// uniformly ~0.03 on the pre-launch registry (untuned, spec §6.5) so it is NOT
+// a usable floor — the server's own match_quality bucketing is. Accept only a
+// strong/good top match; partial/weak/absent → null → graceful path.
+const ACCEPTABLE_REGISTRY_QUALITY = new Set(['strong', 'good'])
+
+const registry_candidate = (items) => {
+	const top = items && items.length ? items[0] : null
+	if (!top) return null
+	return ACCEPTABLE_REGISTRY_QUALITY.has(top.match_quality) ? top : null
+}
+
+// ── next_step builders (pure; exported for tests) ────────────────────────────
+
+// Installed: the owning skill is present — name it via route_to_skill so the
+// agent lets it fire. Reuses the existing continuation action present_to_user.
+const installed_next_step = (owner_skill, trigger) => ({
+	kind:         'continuation',
+	action:       'present_to_user',
+	route_to_skill: owner_skill,
+	instructions: `The capability is owned by \`${owner_skill}\`, which is installed. Present the match to the principal — the skill will handle the request when the intent is re-stated.`,
+	context:      { ...(trigger ? { trigger } : {}) },
+})
+
+// Not installed: route to install. Reuses the existing routing action
+// install_first; route_to_skill names the owning skill.
+const not_installed_next_step = (owner_skill, slug) => ({
+	kind:         'routing',
+	action:       'install_first',
+	route_to_skill: owner_skill,
+	instructions: `The owning skill is not installed. Install it, then re-state the intent so it can handle the request.`,
+	context:      { commands: [`npx happyskills install ${slug} --json`] },
+})
+
+// Nothing confidently matched — a valid, graceful outcome (never a crash, never
+// an invented error code).
+const empty_next_step = () => ({
+	kind:         'continuation',
+	action:       'present_to_user',
+	instructions: `No installed capability or registry skill confidently matches this intent. Present this honestly to the principal — consider rephrasing, or search the registry directly with \`happyskills search\`.`,
+	context:      {},
+})
+
+// ── resolution ───────────────────────────────────────────────────────────────
+
+const resolve_intent = (intent) => catch_errors('Resolve failed', async () => {
+	const [, ownership] = await build_ownership()
+	const skills = ownership?.skills || []
+	const installed_slugs = new Set(skills.map(s => s.slug))
+
+	// 2a — deterministic local match against installed capabilities.
+	const local = match_local(intent, skills)
+	if (is_confident(local)) {
+		return {
+			data: {
+				intent,
+				capability:  local.capability.id,
+				summary:     local.capability.summary || null,
+				owner_skill: local.skill.name,
+				slug:        local.skill.slug,
+				installed:   true,
+				resolution:  'installed_capability',
+			},
+			next_step: installed_next_step(local.skill.name, local.intent_phrase),
+			warnings:  [],
+		}
+	}
+
+	// 2b — registry search fallback (PROBABILISTIC). Public read; no auth required.
+	const [search_errors, response] = await repos_api.dispatch_search(intent, { limit: 5 })
+	if (search_errors) throw e('Registry search failed', search_errors)
+	const items = Array.isArray(response) ? response : (response?.data || response?.results || [])
+	const top = registry_candidate(items)
+
+	if (top) {
+		const owner = top.workspace_slug || top.owner || null
+		const slug = owner ? `${owner}/${top.name}` : top.name
+		const already_installed = installed_slugs.has(slug)
+		return {
+			data: {
+				intent,
+				capability:  null,
+				summary:     top.description || null,
+				owner_skill: top.name,
+				slug,
+				installed:   already_installed,
+				resolution:  'registry_search',
+			},
+			next_step: already_installed
+				? installed_next_step(top.name, null)
+				: not_installed_next_step(top.name, slug),
+			warnings: [{
+				code:    'probabilistic_match',
+				message: 'This match comes from semantic registry search and is probabilistic — verify it fits the intent before trusting a not-installed result.',
+			}],
+		}
+	}
+
+	// No match anywhere — graceful empty result.
+	return {
+		data: {
+			intent,
+			capability:  null,
+			summary:     null,
+			owner_skill: null,
+			slug:        null,
+			installed:   false,
+			resolution:  'none',
+		},
+		next_step: empty_next_step(),
+		warnings:  [],
+	}
+})
+
+const print_human = (result) => {
+	const d = result.data
+	if (d.resolution === 'none') {
+		print_info(`No skill confidently owns: "${d.intent}"`)
+		print_hint('Try rephrasing, or run `happyskills search "<terms>"` to browse the registry.')
+		return
+	}
+	const where = d.installed ? cyan('installed') : dim('not installed')
+	console.log(`\n${bold(d.owner_skill)}  ${where}`)
+	if (d.summary) console.log(`  ${d.summary}`)
+	if (d.capability) console.log(`  ${dim('capability: ' + d.capability)}`)
+	if (!d.installed && d.slug) {
+		console.log(`\n  ${gray('Install with:')} happyskills install ${d.slug}`)
+	}
+	if (d.resolution === 'registry_search') {
+		console.log(`\n  ${dim('(registry match — semantic search is probabilistic; verify it fits.)')}`)
+	}
+	console.log('')
+}
+
+const run = (args) => catch_errors('Resolve failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const intent = args._.join(' ').trim()
+	if (!intent) {
+		throw new UsageError('An intent is required. Example: happyskills resolve "how many people installed my skills".')
+	}
+
+	const [errors, result] = await resolve_intent(intent)
+	if (errors) throw e('Resolve failed', errors)
+
+	if (args.flags.json) {
+		emit_envelope({ data: result.data, next_step: result.next_step, warnings: result.warnings })
+		return
+	}
+	print_human(result)
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+const schema = {
+	name:     'resolve',
+	audience: 'consumer',
+	purpose:  'Resolve a natural-language intent to the owning skill, whether it is installed, and how to install it. Deterministic against installed capabilities; probabilistic registry fallback otherwise.',
+	mutation: false,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'intent', required: true, type: 'string', description: 'Natural-language description of what you want to do' },
+		],
+		flags: [
+			{ name: 'json', type: 'boolean', default: false, description: 'Output as JSON envelope' },
+		],
+	},
+	output: {
+		data_shape: {
+			intent:      'string',
+			capability:  'string|null',
+			summary:     'string|null',
+			owner_skill: 'string|null',
+			slug:        'string|null',
+			installed:   'boolean',
+			resolution:  'installed_capability | registry_search | none',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',   next_step: { kind: 'routing',  action: 'discover_schema' } },
+		{ code: 'NETWORK_ERROR', next_step: { kind: 'recovery', action: 'retry' } },
+	],
+	examples: [
+		'happyskills resolve "how many people installed my skills" --json',
+		'happyskills resolve "invite alice to my workspace" --json',
+	],
+}
+
+module.exports = {
+	run,
+	schema,
+	// pure helpers (exported for tests)
+	tokenize,
+	score_intent,
+	match_local,
+	is_confident,
+	registry_candidate,
+	installed_next_step,
+	not_installed_next_step,
+	empty_next_step,
+	resolve_intent,
+}

package/src/commands/resolve.test.js

@@ -0,0 +1,169 @@
+'use strict'
+// Tests for `happyskills resolve` — spec 260606-01 Phase 4b.
+// Pure-function coverage (deterministic matcher + next_step builders) plus an
+// envelope-conformance check: every next_step resolve can emit must be a valid
+// six-key envelope with a closed-enum action. No network — 2b is not exercised.
+
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+
+const {
+	tokenize,
+	score_intent,
+	match_local,
+	is_confident,
+	registry_candidate,
+	installed_next_step,
+	not_installed_next_step,
+	empty_next_step,
+} = require('./resolve')
+const { build_envelope } = require('../ui/envelope')
+const { validate_envelope } = require('../schema/envelope_validator')
+const { NEXT_STEP_ACTION_SET } = require('../constants/next_step_actions')
+
+// Fixture mirroring the real skill-declared capabilities (a subset).
+const SKILLS = [
+	{
+		name: 'happyskills-stats', slug: 'happyskillsai/happyskills-stats', bundled: false,
+		capabilities: [{
+			id: 'usage-stats',
+			summary: 'report your own HappySkills usage',
+			intents: ['how many people installed my skills', 'show my usage', 'my install or search history'],
+			commands: ['stats'],
+		}],
+	},
+	{
+		name: 'happyskills-collab', slug: 'happyskillsai/happyskills-collab', bundled: false,
+		capabilities: [{
+			id: 'workspace-collaboration',
+			summary: 'invite members and grant access',
+			intents: ['invite someone to my workspace', 'grant or revoke skill access'],
+			commands: ['people', 'groups', 'access'],
+		}],
+	},
+	{
+		name: 'happyskills-publish', slug: 'happyskillsai/happyskills-publish', bundled: true,
+		capabilities: [{
+			id: 'publish-skill',
+			summary: 'publish and release skills',
+			intents: ['publish my skill', 'release my skill'],
+			commands: ['publish', 'release', 'bump'],
+		}],
+	},
+]
+
+describe('resolve — tokenize', () => {
+	it('lowercases, strips punctuation, drops stopwords and short tokens', () => {
+		assert.deepEqual(tokenize('How many people installed MY skills?'), ['many', 'people', 'installed', 'skills'])
+	})
+	it('returns empty for pure stopwords / noise', () => {
+		assert.deepEqual(tokenize('how do I'), [])
+	})
+})
+
+describe('resolve — score_intent', () => {
+	it('exact phrase scores 1.0 with full shared count', () => {
+		const q = new Set(tokenize('how many people installed my skills'))
+		const { score, shared } = score_intent(q, 'how many people installed my skills')
+		assert.equal(score, 1)
+		assert.equal(shared, 4)
+	})
+	it('partial overlap scores between 0 and 1', () => {
+		const q = new Set(tokenize('invite alice to my workspace'))
+		const { score, shared } = score_intent(q, 'invite someone to my workspace')
+		assert.ok(score > 0 && score < 1)
+		assert.equal(shared, 2) // invite, workspace
+	})
+	it('no overlap scores 0', () => {
+		const q = new Set(tokenize('asdfqwer nonsense'))
+		assert.deepEqual(score_intent(q, 'publish my skill'), { score: 0, shared: 0 })
+	})
+})
+
+describe('resolve — match_local + confidence gate', () => {
+	it('routes a stats intent to happyskills-stats (confident)', () => {
+		const m = match_local('how many people installed my skills', SKILLS)
+		assert.equal(m.skill.name, 'happyskills-stats')
+		assert.equal(m.capability.id, 'usage-stats')
+		assert.equal(is_confident(m), true)
+	})
+	it('routes a collab intent to happyskills-collab (confident)', () => {
+		const m = match_local('invite alice to my workspace', SKILLS)
+		assert.equal(m.skill.name, 'happyskills-collab')
+		assert.equal(is_confident(m), true)
+	})
+	it('a bare command word ("publish") routes via command-name match', () => {
+		const m = match_local('publish', SKILLS)
+		assert.equal(m.skill.name, 'happyskills-publish')
+		assert.equal(is_confident(m), true)
+	})
+	it('gibberish yields no confident match', () => {
+		const m = match_local('asdfqwer zzz', SKILLS)
+		assert.equal(is_confident(m), false) // null or low-overlap
+	})
+	it('does not cross-wire collab and stats intents', () => {
+		assert.equal(match_local('grant or revoke skill access', SKILLS).skill.name, 'happyskills-collab')
+		assert.equal(match_local('show my usage', SKILLS).skill.name, 'happyskills-stats')
+	})
+	// Durable guard: command names are common English words (access, publish,
+	// stats...). A longer, unrelated query that merely CONTAINS one must NOT be
+	// a confident match — only a bare-command query may use the command shortcut.
+	it('does not confidently match an out-of-domain query that merely contains a command word', () => {
+		assert.equal(is_confident(match_local('access the production database', SKILLS)), false)
+		assert.equal(is_confident(match_local('publish a blog post about marketing', SKILLS)), false)
+		assert.equal(is_confident(match_local('show me the stats of the football game', SKILLS)), false)
+	})
+})
+
+describe('resolve — registry relevance floor (2b)', () => {
+	// Durable guard: semantic search almost always returns SOMETHING, so the
+	// registry fallback must gate on the server's match_quality, never blindly
+	// take items[0] (which turned gibberish into a confident install_first).
+	it('rejects a partial/weak top match (→ null → graceful path)', () => {
+		assert.equal(registry_candidate([{ name: 'abc-xyz-classifier', match_quality: 'partial' }]), null)
+		assert.equal(registry_candidate([{ name: 'x', match_quality: 'weak' }]), null)
+	})
+	it('rejects a top match with no match_quality (defensive)', () => {
+		assert.equal(registry_candidate([{ name: 'x', relevance_score: 0.9 }]), null)
+	})
+	it('accepts a strong or good top match', () => {
+		assert.equal(registry_candidate([{ name: 'happyskills-collab', match_quality: 'strong' }]).name, 'happyskills-collab')
+		assert.equal(registry_candidate([{ name: 'database', match_quality: 'good' }]).name, 'database')
+	})
+	it('returns null for an empty result set', () => {
+		assert.equal(registry_candidate([]), null)
+		assert.equal(registry_candidate(null), null)
+	})
+})
+
+describe('resolve — next_step builders emit valid envelopes', () => {
+	const assert_valid = (next_step) => {
+		const env = build_envelope({ data: { ok: 1 }, next_step })
+		const { ok, errors } = validate_envelope(env)
+		assert.ok(ok, `envelope invalid: ${JSON.stringify(errors)}`)
+		assert.ok(NEXT_STEP_ACTION_SET.has(env.next_step.action), `action ${env.next_step.action} not in closed enum`)
+		return env
+	}
+
+	it('installed → continuation/present_to_user with route_to_skill', () => {
+		const env = assert_valid(installed_next_step('happyskills-stats', 'show my usage'))
+		assert.equal(env.next_step.kind, 'continuation')
+		assert.equal(env.next_step.action, 'present_to_user')
+		assert.equal(env.next_step.route_to_skill, 'happyskills-stats')
+	})
+
+	it('not installed → routing/install_first with the install command', () => {
+		const env = assert_valid(not_installed_next_step('happyskills-collab', 'happyskillsai/happyskills-collab'))
+		assert.equal(env.next_step.kind, 'routing')
+		assert.equal(env.next_step.action, 'install_first')
+		assert.equal(env.next_step.route_to_skill, 'happyskills-collab')
+		assert.equal(env.next_step.context.commands[0], 'npx happyskills install happyskillsai/happyskills-collab --json')
+	})
+
+	it('empty → continuation/present_to_user, ok:true (graceful, no invented code)', () => {
+		const env = assert_valid(empty_next_step())
+		assert.equal(env.ok, true)
+		assert.equal(env.next_step.action, 'present_to_user')
+		assert.deepEqual(env.error, {})
+	})
+})

package/src/commands/schema.js

@@ -10,8 +10,12 @@
 // yet (defensive, additive). The schema lives next to the implementation
 // so there's no drift.
 
+const path = require('path')
 const { error: { catch_errors } } = require('puffy-core')
-const { COMMANDS, COMMAND_ALIASES, CLI_VERSION } = require('../constants')
+const { COMMANDS, COMMAND_ALIASES, CLI_VERSION, SKILL_JSON } = require('../constants')
+const { read_lock, get_all_locked_skills } = require('../lock/reader')
+const { skills_dir, skill_install_dir, find_project_root, lock_root } = require('../config/paths')
+const { read_json } = require('../utils/fs')
 const { ERROR_CODE_LIST } = require('../constants/error_codes')
 const {
 	NEXT_STEP_ACTION_LIST,
@@ -103,10 +107,90 @@ const load_command_schema = (name) => {
 	return default_schema(name)
 }
 
-const build_command_registry = () => {
+// ── Skill-declared capability ownership (spec 260606-01 Phase 4a) ────────────
+// Each installed skill MAY declare a `capabilities` array in its skill.json:
+//   [{ id, summary, intents: [...], commands: [...] }]
+// We aggregate these from the locally-installed skills (project + global lock)
+// and expose two derived shapes:
+//   - data.skills[]               — the capability registry, one entry per
+//                                   declaring skill (name, slug, bundled, caps)
+//   - data.commands[].owner_skill — command → owning skill, DERIVED from the
+//                                   `commands` field of each declared capability
+// Ownership is skill-DECLARED and CLI-AGGREGATED. There is deliberately NO
+// hardcoded skill-family or command→skill table here (spec §5 — the one
+// architectural rule). `bundled` is derived generically: a skill is bundled
+// when it appears as a dependency of any other installed skill (i.e. it arrives
+// pulled-in rather than installed on its own) — family-agnostic, lock-derived.
+// This generalizes the spec's "membership in core's dependencies" to "any
+// installed skill's dependencies" precisely so the CLI never names a family.
+
+const read_installed_manifests = (is_global) => catch_errors('Failed to read installed skills', async () => {
+	const project_root = find_project_root()
+	const base_dir = skills_dir(is_global, project_root)
+	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
+	const locked = get_all_locked_skills(lock_data)
+	const entries = await Promise.all(Object.keys(locked).map(async (slug) => {
+		const short = slug.split('/')[1] || slug
+		const dir = skill_install_dir(base_dir, short)
+		const [, manifest] = await read_json(path.join(dir, SKILL_JSON))
+		if (!manifest) return null
+		return { slug, short, manifest }
+	}))
+	return entries.filter(Boolean)
+})
+
+const normalise_capabilities = (caps) =>
+	(Array.isArray(caps) ? caps : []).map(c => ({
+		id:       c && c.id ? c.id : null,
+		summary:  c && c.summary ? c.summary : '',
+		intents:  c && Array.isArray(c.intents) ? c.intents : [],
+		commands: c && Array.isArray(c.commands) ? c.commands : [],
+	}))
+
+const build_ownership = () => catch_errors('Failed to build skill ownership', async () => {
+	// Merge project + global installs; project precedence on duplicate slug.
+	const [, project_entries] = await read_installed_manifests(false)
+	const [, global_entries]  = await read_installed_manifests(true)
+	const by_slug = new Map()
+	for (const e of [...(global_entries || []), ...(project_entries || [])]) by_slug.set(e.slug, e)
+	// Sort by slug so command_owner tie-breaks (first-declarer-wins) are stable.
+	const all = [...by_slug.values()].sort((a, b) => a.slug.localeCompare(b.slug))
+
+	// bundled = appears as a dependency of any installed skill.
+	const dep_slugs = new Set()
+	for (const { manifest } of all) {
+		const deps = manifest && manifest.dependencies
+		if (deps && typeof deps === 'object') for (const k of Object.keys(deps)) dep_slugs.add(k)
+	}
+
+	const skills = []
+	const command_owner = {}
+	for (const { slug, short, manifest } of all) {
+		const caps = normalise_capabilities(manifest.capabilities)
+		if (caps.length === 0) continue
+		const name = manifest.name || short
+		skills.push({
+			name,
+			slug,
+			version:      manifest.version || null,
+			bundled:      dep_slugs.has(slug),
+			capabilities: caps,
+		})
+		// Derive command → owner_skill from declared capability.commands.
+		// First declarer wins (orthogonal by design; deterministic via slug sort).
+		for (const cap of caps) {
+			for (const cmd of cap.commands) {
+				if (!(cmd in command_owner)) command_owner[cmd] = name
+			}
+		}
+	}
+	return { skills, command_owner }
+})
+
+const build_command_registry = (command_owner = {}) => {
 	const all = [...COMMANDS]
 	if (!all.includes('schema')) all.push('schema')
-	return all.map(load_command_schema)
+	return all.map(name => ({ ...load_command_schema(name), owner_skill: command_owner[name] || null }))
 }
 
 const build_error_code_list = () => ERROR_CODE_LIST.map(code => ({ code }))
@@ -114,11 +198,12 @@ const build_error_code_list = () => ERROR_CODE_LIST.map(code => ({ code }))
 const build_next_step_action_list = () =>
 	NEXT_STEP_ACTION_LIST.map(action => ({ action, kind: ACTION_KIND[action] || null }))
 
-const build_schema_payload = () => ({
+const build_schema_payload = (ownership = { skills: [], command_owner: {} }) => ({
 	envelope_schema_version: ENVELOPE_SCHEMA_VERSION,
 	envelope_schema_uri:     'https://schemas.happyskills.dev/envelope/v1.json',
 	cli_version:             CLI_VERSION,
-	commands:                build_command_registry(),
+	commands:                build_command_registry(ownership.command_owner),
+	skills:                  ownership.skills || [],
 	error_codes:             build_error_code_list(),
 	next_step_actions:       build_next_step_action_list(),
 	next_step_kinds:         [...NEXT_STEP_KINDS],
@@ -149,7 +234,8 @@ const run = (args) => catch_errors('Schema command failed', async () => {
 		print_help(HELP_TEXT)
 		return process.exit(EXIT_CODES.SUCCESS)
 	}
-	const payload = build_schema_payload()
+	const [, ownership] = await build_ownership()
+	const payload = build_schema_payload(ownership || { skills: [], command_owner: {} })
 	if (args.flags.json) {
 		emit_envelope({ data: payload })
 		return
@@ -170,7 +256,8 @@ const schema = {
 		envelope_schema_version: 'string',
 		envelope_schema_uri:     'string',
 		cli_version:             'string',
-		commands:                'array<CommandSchema>',
+		commands:                'array<CommandSchema & { owner_skill: string|null }>',
+		skills:                  'array<{ name: string, slug: string, version: string|null, bundled: boolean, capabilities: array<{ id: string|null, summary: string, intents: string[], commands: string[] }> }>',
 		error_codes:             'array<{ code: string }>',
 		next_step_actions:       'array<{ action: string, kind: string }>',
 		next_step_kinds:         'array<string>',
@@ -182,4 +269,4 @@ const schema = {
 	],
 }
 
-module.exports = { run, schema, build_schema_payload }
+module.exports = { run, schema, build_schema_payload, build_ownership }

package/src/constants/next_step_by_error_code.js

@@ -151,20 +151,28 @@ const NEXT_STEP_BY_ERROR_CODE = Object.freeze({
 		{ commands: [`npx happyskills pull ${ctx.skill || '<skill>'} --rebase --json`] },
 		{ route_to_skill: 'happyskills-sync' }
 	),
+	// Spec 260606-01 § 4.2 — these recoveries clearly belong to a sibling skill
+	// (validate/changelog are publish-pre-flight territory), so name it via
+	// route_to_skill. Literal slugs mirror the DRIFT_DETECTED/DIVERGED style:
+	// these factories are a static map with no runtime access to the async
+	// ownership map, and `happyskills-publish` is the published slug that owns
+	// the `validate`/`bump`/`publish`/`release` commands (per the §4.1 map).
 	VALIDATION_FAILED: (_msg, ctx = {}) => recovery(
 		FIX_VALIDATION_ERRORS,
 		'Validation failed. Fix the listed errors and re-run.',
 		{
 			...(ctx.validation_errors ? { validation_errors: ctx.validation_errors } : {}),
 			...(ctx.skill ? { commands: [`npx happyskills validate ${ctx.skill} --json`] } : {}),
-		}
+		},
+		{ route_to_skill: 'happyskills-publish' }
 	),
 	DEPENDENCY_VALIDATION_FAILED: (_msg, ctx = {}) => recovery(
 		FIX_VALIDATION_ERRORS,
 		'Dependency validation failed. Fix the listed dependency issues and re-run.',
 		{
 			...(ctx.validation_errors ? { validation_errors: ctx.validation_errors } : {}),
-		}
+		},
+		{ route_to_skill: 'happyskills-publish' }
 	),
 	MISSING_CHANGELOG_ENTRY: (_msg, ctx = {}) => recovery(
 		PROVIDE_CHANGELOG,
@@ -173,13 +181,13 @@ const NEXT_STEP_BY_ERROR_CODE = Object.freeze({
 			...(ctx.target_version ? { target_version: ctx.target_version } : {}),
 			...(ctx.current_top_entry ? { current_top_entry: ctx.current_top_entry } : {}),
 		},
-		{ principal_authorization_required: true }
+		{ principal_authorization_required: true, route_to_skill: 'happyskills-publish' }
 	),
 	CHANGELOG_SOURCE_UNREADABLE: () => recovery(
 		PROVIDE_CHANGELOG,
 		'CHANGELOG.md could not be read. Restore the file and re-run.',
 		{},
-		{ principal_authorization_required: true }
+		{ principal_authorization_required: true, route_to_skill: 'happyskills-publish' }
 	),
 
 	// Decision-kind defaults
@@ -226,6 +234,17 @@ const NEXT_STEP_BY_ERROR_CODE = Object.freeze({
 			...(ctx.candidates ? { candidates: ctx.candidates } : {}),
 		}
 	),
+	// Spec 260606-01 § 4.2 — unresolved merge conflicts are sync territory.
+	// Default factory (commands MAY still override with a richer next_step).
+	CONFLICT: (_msg, ctx = {}) => decision(
+		RESOLVE_CONFLICTS,
+		'Unresolved merge conflicts are present. Resolve the conflict markers, then retry the operation.',
+		{
+			...(ctx.conflict_files ? { conflict_files: ctx.conflict_files } : {}),
+			...(ctx.skill ? { commands: [`npx happyskills status ${ctx.skill} --json`] } : {}),
+		},
+		{ route_to_skill: 'happyskills-sync' }
+	),
 
 	// Confirmation-kind defaults
 	LOCAL_EDITS_PRESENT: (_msg, ctx = {}) => confirmation(

package/src/constants.js

@@ -51,6 +51,7 @@ const COMMANDS = [
 	'visibility',
 	'list',
 	'search',
+	'resolve',
 	'star',
 	'unstar',
 	'check',

package/src/engine/uninstaller.js

@@ -36,6 +36,37 @@ const find_orphans = (skills, removed_skill) => {
 	return orphans
 }
 
+// Cascading orphan detection. `find_orphans` is single-pass by design (its unit
+// contract): it only reports the DIRECT orphans of `removed_skill`. But pruning a
+// direct orphan A can in turn strand A's own private sub-dependency B — a grandchild
+// that nothing else needs once A is gone. A single pass leaves B behind because A is
+// still in the map (so A both counts as a live requester of B and, via its
+// `dependencies`, as a "surviving declarer" of B).
+//
+// This wrapper closes that gap WITHOUT weakening the data-loss guard. It runs
+// `find_orphans` to a fixed point over a shrinking working copy: each round, the
+// orphans found are physically removed from the map, so the next round sees them as
+// gone — both as requesters (`skills[r]` is now false) and as declarers
+// (`declared_by_survivor` no longer finds them). A skill that ANY surviving skill
+// still declares is never pruned, exactly as before — only skills whose entire
+// requirement chain has been removed cascade out. Terminates because every round
+// deletes at least one entry from a finite map.
+const find_orphans_cascading = (skills, removed_skill) => {
+	const working = { ...skills }
+	delete working[removed_skill]
+
+	const all_orphans = []
+	let round = find_orphans(working, removed_skill)
+	while (round.length > 0) {
+		for (const name of round) {
+			all_orphans.push(name)
+			delete working[name]
+		}
+		round = find_orphans(working, removed_skill)
+	}
+	return all_orphans
+}
+
 const uninstall = (skill, options = {}) => catch_errors('Uninstall failed', async () => {
 	const { global: is_global = false, project_root, agents: agents_flag } = options
 
@@ -64,7 +95,7 @@ const uninstall = (skill, options = {}) => catch_errors('Uninstall failed', asyn
 		}
 	}
 
-	const orphans = find_orphans(all_skills, skill)
+	const orphans = find_orphans_cascading(all_skills, skill)
 	const to_remove = [skill, ...orphans]
 
 	for (const name of to_remove) {
@@ -97,4 +128,4 @@ const uninstall = (skill, options = {}) => catch_errors('Uninstall failed', asyn
 	return { removed: to_remove, orphans_pruned: orphans }
 })
 
-module.exports = { uninstall, find_orphans }
+module.exports = { uninstall, find_orphans, find_orphans_cascading }

package/src/engine/uninstaller.test.js

@@ -1,6 +1,6 @@
 const { describe, it } = require('node:test')
 const assert = require('node:assert')
-const { find_orphans } = require('./uninstaller')
+const { find_orphans, find_orphans_cascading } = require('./uninstaller')
 
 describe('find_orphans', () => {
 	it('returns empty when all skills have requesters in the skills map', () => {
@@ -134,3 +134,122 @@ describe('find_orphans', () => {
 		assert.ok(result.includes('happyskillsai/happyskills-design'))
 	})
 })
+
+describe('find_orphans_cascading', () => {
+	it('cascades: prunes a grandchild stranded once its only parent is orphaned', () => {
+		// Kit K -> A -> B. B is A's private sub-dependency (not listed directly by the
+		// kit). Uninstalling K must prune A (direct orphan) AND B (cascaded orphan).
+		// This is the exact case single-pass find_orphans leaves stranded.
+		const skills = {
+			'acme/_kit-x': { requested_by: ['__root__'], dependencies: { 'acme/a': '^1.0.0' } },
+			'acme/a':      { requested_by: ['acme/_kit-x'], dependencies: { 'acme/b': '^1.0.0' } },
+			'acme/b':      { requested_by: ['acme/_kit-x'], dependencies: {} }
+		}
+		const result = find_orphans_cascading(skills, 'acme/_kit-x')
+		assert.ok(result.includes('acme/a'), 'direct orphan A should be pruned')
+		assert.ok(result.includes('acme/b'), 'cascaded orphan B should be pruned')
+	})
+
+	it('still protects a shared dependency a surviving skill declares (no over-pruning under cascade)', () => {
+		// The data-loss guard must survive the cascade: design is declared by the
+		// surviving happyskills, so uninstalling create-release-skill must NOT prune it
+		// even though we now iterate to a fixed point.
+		const skills = {
+			'happyskillsai/happyskills': {
+				requested_by: ['__root__'],
+				dependencies: { 'happyskillsai/happyskills-design': '^0.1.0' }
+			},
+			'nicolasdao/create-release-skill': {
+				requested_by: ['__root__'],
+				dependencies: { 'happyskillsai/happyskills-design': '^0.9.0' }
+			},
+			'happyskillsai/happyskills-design': {
+				requested_by: ['nicolasdao/create-release-skill']
+			}
+		}
+		const result = find_orphans_cascading(skills, 'nicolasdao/create-release-skill')
+		assert.ok(!result.includes('happyskillsai/happyskills-design'))
+	})
+
+	it('never prunes a user-installed (__root__) skill, even mid-cascade', () => {
+		// K -> A, but A is ALSO directly installed by the user. Removing K orphans
+		// nothing the user still wants: A is __root__-anchored and stays.
+		const skills = {
+			'acme/_kit-x': { requested_by: ['__root__'], dependencies: { 'acme/a': '^1.0.0' } },
+			'acme/a':      { requested_by: ['__root__', 'acme/_kit-x'], dependencies: {} }
+		}
+		const result = find_orphans_cascading(skills, 'acme/_kit-x')
+		assert.deepStrictEqual(result, [])
+	})
+
+	it('halts the cascade at a still-shared mid-chain dependency', () => {
+		// K -> A -> B, but B is ALSO required by an unrelated surviving skill S.
+		// Removing K prunes A, but B must stay because S still needs it.
+		const skills = {
+			'acme/_kit-x': { requested_by: ['__root__'], dependencies: { 'acme/a': '^1.0.0' } },
+			'acme/a':      { requested_by: ['acme/_kit-x'], dependencies: { 'acme/b': '^1.0.0' } },
+			'acme/s':      { requested_by: ['__root__'], dependencies: { 'acme/b': '^1.0.0' } },
+			'acme/b':      { requested_by: ['acme/_kit-x', 'acme/s'], dependencies: {} }
+		}
+		const result = find_orphans_cascading(skills, 'acme/_kit-x')
+		assert.ok(result.includes('acme/a'), 'A is orphaned')
+		assert.ok(!result.includes('acme/b'), 'B is still needed by surviving acme/s')
+	})
+
+	it('constellation: uninstalling the core prunes bundled satellites, keeps shared + opt-in ones', () => {
+		// Models the real happyskills constellation: the core declares 5 bundled
+		// satellites as dependencies. happyskills-design is ALSO declared by a surviving
+		// skill (create-release-skill). collab + stats are OPT-IN — installed directly
+		// (__root__), never dependencies of the core.
+		const skills = {
+			'happyskillsai/happyskills': {
+				requested_by: ['__root__'],
+				dependencies: {
+					'happyskillsai/happyskills-design': '^0.1.0',
+					'happyskillsai/happyskills-publish': '^0.1.0',
+					'happyskillsai/happyskills-sync': '^0.1.0',
+					'happyskillsai/happyskills-search': '^0.1.0',
+					'happyskillsai/happyskills-help': '^0.1.0'
+				}
+			},
+			'nicolasdao/create-release-skill': {
+				requested_by: ['__root__'],
+				dependencies: { 'happyskillsai/happyskills-design': '^0.9.0' }
+			},
+			'happyskillsai/happyskills-design':  { requested_by: ['happyskillsai/happyskills', 'nicolasdao/create-release-skill'], dependencies: {} },
+			'happyskillsai/happyskills-publish': { requested_by: ['happyskillsai/happyskills'], dependencies: {} },
+			'happyskillsai/happyskills-sync':    { requested_by: ['happyskillsai/happyskills'], dependencies: {} },
+			'happyskillsai/happyskills-search':  { requested_by: ['happyskillsai/happyskills'], dependencies: {} },
+			'happyskillsai/happyskills-help':    { requested_by: ['happyskillsai/happyskills'], dependencies: {} },
+			'happyskillsai/happyskills-collab':  { requested_by: ['__root__'], dependencies: {} },
+			'happyskillsai/happyskills-stats':   { requested_by: ['__root__'], dependencies: {} }
+		}
+		const result = find_orphans_cascading(skills, 'happyskillsai/happyskills').sort()
+		assert.deepStrictEqual(result, [
+			'happyskillsai/happyskills-help',
+			'happyskillsai/happyskills-publish',
+			'happyskillsai/happyskills-search',
+			'happyskillsai/happyskills-sync'
+		])
+		// design is shared (create-release-skill still declares it) → kept
+		assert.ok(!result.includes('happyskillsai/happyskills-design'))
+		// collab + stats are opt-in (__root__) → never swept up by a core uninstall
+		assert.ok(!result.includes('happyskillsai/happyskills-collab'))
+		assert.ok(!result.includes('happyskillsai/happyskills-stats'))
+	})
+
+	it('matches find_orphans for a flat kit (no nested sub-dependencies)', () => {
+		// The common curated-kit case: K directly lists A, B, C and none depend on each
+		// other. Single-pass and cascading must agree — cascade changes nothing here.
+		const skills = {
+			'acme/_kit-x': { requested_by: ['__root__'], dependencies: { 'acme/a': '^1', 'acme/b': '^1', 'acme/c': '^1' } },
+			'acme/a':      { requested_by: ['acme/_kit-x'], dependencies: {} },
+			'acme/b':      { requested_by: ['acme/_kit-x'], dependencies: {} },
+			'acme/c':      { requested_by: ['acme/_kit-x'], dependencies: {} }
+		}
+		const single = find_orphans(skills, 'acme/_kit-x').sort()
+		const cascaded = find_orphans_cascading(skills, 'acme/_kit-x').sort()
+		assert.deepStrictEqual(cascaded, ['acme/a', 'acme/b', 'acme/c'])
+		assert.deepStrictEqual(cascaded, single)
+	})
+})