happyskills 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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
+
+- Fix first-time installs leaving a skill unlinked and invisible. When no agent was configured or detected (empty project, fresh machine, no `--agents` / `HAPPYSKILLS_AGENTS` / config / `~/.<agent>/skills/`), `install` wrote files to `.agents/skills/` but created no agent symlink and said nothing — the skill was installed yet invisible to every agent runtime. Agent resolution now falls back to Claude Code when nothing else is detected, links the skill, and surfaces a notice in both human output and the `--json` `warnings[]`. Target a different agent with `--agents` or `happyskills agents add <agent>`.
+- Stop telling signed-in users they are "not logged in." When a private skill or dependency was inaccessible, the CLI showed an authentication error pointing to `happyskills login` even when the user was already signed in — the real issue was missing access. The `install` `access_denied` skipped-dependency warning and every 401-derived error are now session-state aware: a signed-in user is told their account lacks access and to ask the owner to grant it, while a genuinely signed-out user is prompted to sign in. Also corrects the `check`, `publish`, and `whoami` hints.
+
 ## [1.8.0] - 2026-06-05
 
 ### Changed

package/package.json

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

package/src/agents/detector.js

@@ -116,8 +116,19 @@ const resolve_agents = (agents_flag, options = {}) => catch_errors('Agent resolu
 	// 5. Home-physical fallback (legacy auto-detect)
 	const [errors, home_detected] = await detect_agents({ global: true })
 	if (errors) throw errors[0]
+	if (home_detected.length > 0) {
+		return { agents: home_detected, source: 'home' }
+	}
 
-	return { agents: home_detected, source: 'home' }
+	// 6. Default — nothing was configured or detected anywhere (the first-run
+	//    case: empty project, fresh machine, no flag/env/config). Returning an
+	//    empty list here is the trap: physical files would land in .agents/skills/
+	//    but no agent symlink is created, so the skill is installed yet invisible
+	//    to every agent runtime. Fall back to Claude Code — the primary agent —
+	//    and tag the source as 'default' so callers can tell the user a default
+	//    was chosen and how to target a different agent. resolve_agents never
+	//    returns an empty agent list.
+	return { agents: [get_agent('claude')], source: 'default' }
 })
 
 module.exports = { detect_agents, resolve_agents }

package/src/agents/detector.test.js

@@ -0,0 +1,60 @@
+'use strict'
+const { describe, it, beforeEach, afterEach } = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+
+const { resolve_agents } = require('./detector')
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-detector-test-'))
+const cleanup = (dir) => fs.rmSync(dir, { recursive: true, force: true })
+
+describe('resolve_agents', () => {
+	let tmp
+	let saved_env
+
+	beforeEach(() => {
+		tmp = make_tmp()
+		// Isolate from the host's HAPPYSKILLS_AGENTS preference.
+		saved_env = process.env.HAPPYSKILLS_AGENTS
+		delete process.env.HAPPYSKILLS_AGENTS
+	})
+	afterEach(() => {
+		cleanup(tmp)
+		if (saved_env === undefined) delete process.env.HAPPYSKILLS_AGENTS
+		else process.env.HAPPYSKILLS_AGENTS = saved_env
+	})
+
+	it('honors the --agents flag (source: flag)', async () => {
+		const [errors, result] = await resolve_agents('claude,cursor', { project_root: tmp })
+		assert.equal(errors, null)
+		assert.equal(result.source, 'flag')
+		assert.deepEqual(result.agents.map(a => a.id), ['claude', 'cursor'])
+	})
+
+	it('reads HAPPYSKILLS_AGENTS when no flag is passed (source: env)', async () => {
+		process.env.HAPPYSKILLS_AGENTS = 'cursor'
+		const [errors, result] = await resolve_agents(undefined, { project_root: tmp })
+		assert.equal(errors, null)
+		assert.equal(result.source, 'env')
+		assert.deepEqual(result.agents.map(a => a.id), ['cursor'])
+	})
+
+	// The first-run trap regression guard: with nothing configured or detected,
+	// resolve_agents must NEVER return an empty agent list. An empty list is what
+	// left skills installed-but-invisible (no .claude/skills symlink) for new
+	// users. The fallback is Claude Code, tagged source: 'default'.
+	it('never returns an empty agent list — falls back to Claude Code', async () => {
+		const [errors, result] = await resolve_agents(undefined, { project_root: tmp })
+		assert.equal(errors, null)
+		assert.ok(result.agents.length >= 1, 'resolve_agents must return at least one agent')
+		// On a clean environment (no project/home agent dirs, no config) this is
+		// the default branch. On a dev machine an agent may be detected via home
+		// or config — in that case the source differs but the never-empty
+		// invariant above still holds.
+		if (result.source === 'default') {
+			assert.deepEqual(result.agents.map(a => a.id), ['claude'])
+		}
+	})
+})

package/src/api/client.js

@@ -27,10 +27,12 @@ const request = (method, path, options = {}) => catch_errors(`API ${method} ${pa
 		headers['X-Intent-Envelope'] = active_envelope
 	}
 
+	let token_attached = false
 	if (auth) {
 		const [, token_data] = await load_token()
 		if (token_data) {
 			headers['Authorization'] = `Bearer ${token_data.id_token}`
+			token_attached = true
 		}
 	}
 
@@ -83,7 +85,15 @@ const request = (method, path, options = {}) => catch_errors(`API ${method} ${pa
 		const err_details = data?.error?.details
 
 		if (res.status === 401) {
-			const err = new AuthError(err_msg)
+			// The API answers 401 for a private resource the caller can't see —
+			// which happens BOTH when nobody is signed in AND when a signed-in
+			// user simply lacks access (private repos return 401/404 so their
+			// existence isn't leaked). Telling a signed-in user to "log in" is
+			// wrong, so the message depends on whether we actually sent a token.
+			const message = token_attached
+				? 'Access denied. Your account does not have access to this private resource, or your session has expired. If you are already signed in, ask the owner to grant you access; otherwise run `happyskills login`.'
+				: 'You are not signed in. Run `happyskills login` to access private skills.'
+			const err = new AuthError(message)
 			if (err_details) err.details = err_details
 			throw err
 		}

package/src/api/client.test.js

@@ -10,7 +10,11 @@
 const { describe, it } = require('node:test')
 const assert = require('node:assert/strict')
 const crypto = require('node:crypto')
+const os = require('node:os')
+const path = require('node:path')
+const fs = require('node:fs')
 const client = require('./client')
+const { save_token } = require('../auth/token_store')
 
 const EMPTY_SHA = crypto.createHash('sha256').update('').digest('hex')
 
@@ -51,3 +55,70 @@ describe('api client — x-amz-content-sha256 (CloudFront OAC SigV4 payload hash
 		assert.equal(c.headers['x-amz-content-sha256'], undefined)
 	})
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 401 messaging is login-state aware. The API returns 401 for a private resource
+// the caller can't see — which happens BOTH when nobody is signed in AND when a
+// signed-in user simply lacks access. The CLI must never tell a signed-in user
+// to log in. token_store reads XDG_CONFIG_HOME lazily, so we point it at a temp
+// dir to control whether a token gets attached.
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Stub fetch to return a 401 envelope regardless of input.
+const with_401 = async (fn) => {
+	const orig = global.fetch
+	global.fetch = async () => ({
+		ok: false,
+		status: 401,
+		headers: { get: () => null },
+		json: async () => ({ error: { code: 'AUTH_REQUIRED', message: 'Unauthorized' } }),
+	})
+	try { return await fn() } finally { global.fetch = orig }
+}
+
+const with_tmp_config = async (fn) => {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'hs-client-401-'))
+	const orig = process.env.XDG_CONFIG_HOME
+	process.env.XDG_CONFIG_HOME = dir
+	try { await fn(dir) } finally {
+		if (orig !== undefined) process.env.XDG_CONFIG_HOME = orig
+		else delete process.env.XDG_CONFIG_HOME
+		fs.rmSync(dir, { recursive: true, force: true })
+	}
+}
+
+describe('api client — 401 message never tells a signed-in user to log in', () => {
+	// client.request is wrapped in puffy-core catch_errors, so it RETURNS
+	// [errors, result] rather than throwing. Pull the AuthError out of the chain.
+	const auth_error_from = (errors) => {
+		assert.ok(errors, 'expected an error tuple')
+		const err = errors.find(e => e && e.name === 'AuthError')
+		assert.ok(err, 'expected an AuthError in the error chain')
+		return err
+	}
+
+	it('signed-in 401 → access-denied wording, NOT "log in"', async () => {
+		await with_tmp_config(async () => {
+			// A valid (non-expired) token → an Authorization header is attached.
+			await save_token({ id_token: 'a.b.c', access_token: 'x', refresh_token: 'r', expires_in: 3600 })
+			await with_401(async () => {
+				const [errors] = await client.get('/repos/acme/private-skill')
+				const err = auth_error_from(errors)
+				assert.match(err.message, /access denied|does not have access/i)
+				assert.doesNotMatch(err.message, /you are not signed in/i)
+			})
+		})
+	})
+
+	it('not-signed-in 401 → tells the user to sign in', async () => {
+		await with_tmp_config(async () => {
+			// No token saved → no Authorization header attached.
+			await with_401(async () => {
+				const [errors] = await client.get('/repos/acme/private-skill')
+				const err = auth_error_from(errors)
+				assert.match(err.message, /not signed in/i)
+				assert.match(err.message, /happyskills login/)
+			})
+		})
+	})
+})

package/src/auth/identity.js

@@ -42,7 +42,7 @@ const render_identity_text = (identity) => {
 	if (identity.workspace_error) {
 		console.log()
 		print_warn(`Failed to list workspaces: ${identity.workspace_error}`)
-		print_hint('Check your authentication with happyskills login')
+		print_hint('This is usually a temporary connection issue — try again in a moment.')
 	} else if (identity.workspaces && identity.workspaces.length > 0) {
 		console.log()
 		print_label('Workspaces', '')

package/src/commands/check.js

@@ -201,8 +201,8 @@ const run = (args) => catch_errors('Check failed', async () => {
 	}
 	if (no_access.length > 0) {
 		console.log()
-		print_warn('Some skills require authentication.')
-		print_hint(`Run ${code('happyskills login')} to refresh your session.`)
+		print_warn(`${no_access.length} installed skill(s) are private and your account can't access them.`)
+		print_hint(`If you're signed in, ask the owner to grant you access. If not, run ${code('happyskills login')}.`)
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 

package/src/commands/publish.js

@@ -73,7 +73,7 @@ const run = (args) => catch_errors('Publish failed', async () => {
 
 	// Verify auth early — fail fast before validation and upload
 	const [ws_err, workspaces] = await workspaces_api.list_workspaces()
-	if (ws_err) throw e('Authentication failed — run \'happyskills login\' to re-authenticate.', ws_err)
+	if (ws_err) throw e('Could not load your workspaces before publishing — check your connection, or run `happyskills login` if your session has expired.', ws_err)
 
 	const [dir_err, dir] = await resolve_skill_dir(skill_name)
 	if (dir_err) throw e(`Skill "${skill_name}" not found`, dir_err)

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/installer.js

@@ -14,6 +14,7 @@ const { ensure_dir, remove_dir, file_exists, read_json } = require('../utils/fs'
 const { SKILL_JSON, SKILL_TYPES } = require('../constants')
 const { resolve_agents, link_to_agents, verify_and_repair_symlinks } = require('../agents')
 const { is_skill_enabled } = require('../agents/status')
+const { load_token } = require('../auth/token_store')
 const { create_spinner } = require('../ui/spinner')
 const { print_success, print_warn, print_info } = require('../ui/output')
 const { emit_batch } = require('../utils/analytics')
@@ -24,6 +25,36 @@ const _format_warnings = (missing_deps) => (missing_deps || []).map(dep => {
 	return `Missing system dependency: ${dep.name} required by ${dep.skill}${hint}`
 })
 
+// Build the warning shown when private dependencies are skipped for lack of
+// access. The server returns these because the skill is private and the caller
+// can't see it — which is NOT the same as "not logged in". A signed-in user is
+// most often simply missing access, so the wording is keyed on `logged_in`:
+// we never tell a logged-in user to log in. Pure + exported so the wording is
+// unit-testable. Returns { warn_lines: string[], hint: string }.
+const format_access_denied_lines = (access_denied, logged_in) => {
+	const noun = access_denied.length === 1 ? 'dependency' : 'dependencies'
+	const them = access_denied.length === 1 ? 'it' : 'them'
+	const head = logged_in
+		? `${access_denied.length} private ${noun} skipped — your account doesn't have access:`
+		: `${access_denied.length} private ${noun} skipped — you're not signed in:`
+	const warn_lines = [head, ...access_denied.map(s => `  ${s.skill} (required by ${s.required_by})`)]
+	const hint = logged_in
+		? `Ask the owner to grant you access to ${them}, then re-run install.`
+		: `Sign in, then re-run install: happyskills login`
+	return { warn_lines, hint }
+}
+
+// First-run transparency. When agent resolution falls all the way through to the
+// Claude Code default (nothing was configured or detected — empty project, fresh
+// machine, no flag/env/config), we must tell the user a default was chosen rather
+// than silently linking. Returns the machine-readable warning for the --json
+// `warnings[]`; empty unless the default actually drove a link (linked_count > 0),
+// so kit-only installs (nothing agent-invocable to link) stay quiet.
+const _format_default_agent_warnings = (agents_source, linked_count) =>
+	(agents_source === 'default' && linked_count > 0)
+		? ['No agent was configured; linked to Claude Code by default. Use --agents or `happyskills agents add <agent>` to target a different agent.']
+		: []
+
 // Circular dependencies the resolver broke automatically. The install is safe and terminates,
 // but the author should remove one edge — so we surface a warning rather than failing silently.
 const _format_cycle_warnings = (cycles) => (cycles || []).map(({ from, to }) =>
@@ -66,7 +97,7 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 	// Resolve target agents
 	const [agents_err, agents_result] = await resolve_agents(agents_flag, { global: is_global, project_root })
 	if (agents_err) throw e('Agent resolution failed', agents_err)
-	const { agents } = agents_result
+	const { agents, source: agents_source } = agents_result
 	const temp_dir = tmp_dir(base_dir)
 	const lock_dir = lock_root(is_global, project_root)
 
@@ -342,7 +373,12 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 
 		const linked_count = downloaded.length - disabled_skills.size
 		if (agents.length > 0 && linked_count > 0) {
-			print_info(`Linked to: ${agents.map(a => a.display_name).join(', ')}`)
+			if (agents_source === 'default') {
+				print_warn('No agent was configured — linked to Claude Code by default.')
+				print_info('Target a different agent with --agents (e.g. --agents cursor) or run: happyskills agents add cursor')
+			} else {
+				print_info(`Linked to: ${agents.map(a => a.display_name).join(', ')}`)
+			}
 		}
 
 		const [, missing_deps] = await check_system_dependencies(packages)
@@ -361,11 +397,12 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 			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`)
+				// Detect the session state so we never tell a logged-in user to
+				// log in (see format_access_denied_lines for the rationale).
+				const [, token_data] = await load_token()
+				const { warn_lines, hint } = format_access_denied_lines(access_denied, !!token_data)
+				for (const line of warn_lines) print_warn(line)
+				print_info(hint)
 			}
 			if (not_found.length > 0) {
 				print_warn(`${not_found.length} dependenc${not_found.length === 1 ? 'y' : 'ies'} skipped (not found in registry):`)
@@ -386,7 +423,8 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 		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' }))
-		const warnings = [..._format_warnings(missing_deps), ...cycle_warnings]
+		const default_agent_warnings = _format_default_agent_warnings(agents_source, linked_count)
+		const warnings = [..._format_warnings(missing_deps), ...cycle_warnings, ...default_agent_warnings]
 		const forced = forced_pkgs.map(p => ({ skill: p.skill, version: p.version }))
 
 		const linked_agents = agents.map(a => a.id)
@@ -446,4 +484,4 @@ const install_from_lock = (lock_data, options = {}) => catch_errors('Install fro
 	return { source: 'skills-lock.json', installed: all_installed, skipped: all_skipped, warnings: all_warnings }
 })
 
-module.exports = { install, install_from_manifest, install_from_lock, merge_requested_by }
+module.exports = { install, install_from_manifest, install_from_lock, merge_requested_by, format_access_denied_lines, _format_default_agent_warnings }

package/src/engine/installer.test.js

@@ -1,6 +1,6 @@
 const { describe, it } = require('node:test')
 const assert = require('node:assert')
-const { merge_requested_by } = require('./installer')
+const { merge_requested_by, format_access_denied_lines, _format_default_agent_warnings } = require('./installer')
 
 describe('merge_requested_by', () => {
 	it('records the root skill for a fresh dependency', () => {
@@ -39,3 +39,63 @@ describe('merge_requested_by', () => {
 		assert.deepStrictEqual(merge_requested_by([], 'a/dep', 'a/root'), ['a/root'])
 	})
 })
+
+describe('format_access_denied_lines (skipped private-dependency wording)', () => {
+	const one = [{ skill: 'acme/secret', required_by: 'acme/_kit-x' }]
+	const two = [
+		{ skill: 'acme/secret', required_by: 'acme/_kit-x' },
+		{ skill: 'acme/other', required_by: 'acme/_kit-x' },
+	]
+
+	it('signed-in: blames access (not auth) and points to the owner — never "log in"', () => {
+		const { warn_lines, hint } = format_access_denied_lines(one, true)
+		// The reported bug: a logged-in user was told they were not logged in.
+		assert.match(warn_lines[0], /your account doesn't have access/)
+		assert.doesNotMatch(warn_lines[0], /not signed in|log ?in/i)
+		assert.match(hint, /ask the owner/i)
+		assert.doesNotMatch(hint, /happyskills login/)
+		// The offending skill is still listed for the user.
+		assert.match(warn_lines[1], /acme\/secret \(required by acme\/_kit-x\)/)
+	})
+
+	it('signed-out: says not signed in and points to login', () => {
+		const { warn_lines, hint } = format_access_denied_lines(one, false)
+		assert.match(warn_lines[0], /you're not signed in/)
+		assert.match(hint, /happyskills login/)
+		assert.doesNotMatch(hint, /ask the owner/i)
+	})
+
+	it('pluralizes the count and noun', () => {
+		assert.match(format_access_denied_lines(one, true).warn_lines[0], /^1 private dependency /)
+		assert.match(format_access_denied_lines(two, true).warn_lines[0], /^2 private dependencies /)
+		// One warn line per skipped dependency, plus the header.
+		assert.equal(format_access_denied_lines(two, true).warn_lines.length, 3)
+	})
+})
+
+describe('_format_default_agent_warnings (first-run default-agent transparency)', () => {
+	// Regression guard for the first-run trap: when nothing is configured or
+	// detected, resolve_agents falls back to Claude Code (source: 'default').
+	// The install must NOT be silent about that — it surfaces a warning so the
+	// human is told and an operating agent can report it. Before the fix the
+	// install completed with zero agent links and zero feedback.
+	it('emits a warning when the Claude default drove a link', () => {
+		const w = _format_default_agent_warnings('default', 1)
+		assert.equal(w.length, 1)
+		assert.match(w[0], /linked to Claude Code by default/)
+		// Tells the user how to target a different agent (no silent magic).
+		assert.match(w[0], /--agents|happyskills agents add/)
+	})
+
+	it('stays silent when an agent was actually configured/detected', () => {
+		assert.deepEqual(_format_default_agent_warnings('flag', 1), [])
+		assert.deepEqual(_format_default_agent_warnings('env', 2), [])
+		assert.deepEqual(_format_default_agent_warnings('project', 1), [])
+		assert.deepEqual(_format_default_agent_warnings('config', 1), [])
+		assert.deepEqual(_format_default_agent_warnings('home', 3), [])
+	})
+
+	it('stays silent when the default fired but nothing was linked (e.g. kit-only install)', () => {
+		assert.deepEqual(_format_default_agent_warnings('default', 0), [])
+	})
+})