happyskills 1.16.0 → 1.16.3

package/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.16.3] - 2026-07-03
+
+### Fixed
+
+- `happyskills install` no longer reports a skill as "already installed" when its **declared dependency closure is not materialized on disk**. The pre-resolve skip check previously inspected only the requested skill's own directory + integrity, so a lock entry carrying a populated `dependencies` map whose skills were never installed (e.g. a kit entry written by `publish`, which records `manifest.dependencies` but installs nothing) would short-circuit every `install` — the missing transitive dependencies were never backfilled and the lock stayed permanently out of sync with `.agents/skills/`. The skip check now walks the locked dependency graph (cycle-safe, transitive) via `dependency_closure_satisfied` and only skips when every reachable dependency is both locked **and** present on disk; otherwise it declines the skip and re-resolves so the missing skills are installed. This makes `install` self-healing: re-running it repairs a partial lock without needing `--fresh`.
+
+## [1.16.2] - 2026-07-03
+
+### Changed
+
+- `happyskills init` and `happyskills fork` no longer scaffold a `keywords` field in the generated `skill.json`. `keywords` is a deprecated, platform-ignored manifest field — discovery labels are derived server-side from the skill's `description` + `SKILL.md` (the platform-owned taxonomy), so an author-supplied keyword list has no effect on search, ranking, or filtering. The scaffold previously emitted an empty `keywords: []`, which baited enrichment agents into populating a no-op field; omitting it removes the bait. The field remains accepted on publish for backward compatibility.
+- `happyskills update --all` now checks **every installed skill**, not just top-level (`__root__`) ones. Previously a bundled dependency — e.g. a HappySkills family satellite (`happyskills-design/publish/sync/search/help`) installed transitively under `happyskills` — was skipped by `--all` and only refreshed when its parent happened to be reinstalled, so a satellite that advanced on the registry while its parent didn't stayed stale even though `check` and the daily update nudge flagged it. `update --all` now mirrors `check` and the nudge and refreshes those drifted transitive skills directly. `update <owner/name>` and the `--all-scopes` per-scope behavior are unchanged.
+
+## [1.16.1] - 2026-07-02
+
+### Fixed
+
+- Make the passive daily skill-update check watch **every** installed skill, not just top-level (`__root__`) ones. Bundled family satellites installed as transitive dependencies (e.g. `happyskills-design`, `happyskills-help`) are recorded in the lock as `requested_by: [<parent>]`, so the previous `__root__`-only filter silently never nudged when they fell behind the registry — even though the check already spans both the project-local and global locks. Candidate selection now mirrors `happyskills check` (every installed skill), so an outdated bundled satellite is surfaced both in the stderr nudge and in the `SKILLS_UPDATE_AVAILABLE` envelope warning.
+
+### Changed
+
+- The "installed skills behind the registry" nudge now names the outdated skills in its suggested command (`npx happyskills update <owner/name> …`, grouped by scope so global skills get `-g`) instead of suggesting `update --all` — which only re-checks top-level skills and therefore could never refresh an outdated bundled satellite.
+
 ## [1.16.0] - 2026-07-01
 
 ### Changed

package/package.json

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

package/src/commands/fork.js

@@ -83,12 +83,14 @@ const run = (args) => catch_errors('Fork failed', async () => {
 	const [, original_manifest] = await read_manifest(dest)
 	const is_kit = (original_manifest?.type) === SKILL_TYPES.KIT
 	const forked_name = is_kit && !name.startsWith(KIT_PREFIX) ? `${KIT_PREFIX}${name}` : name
+	// No `keywords` field — it is a deprecated, platform-ignored skill.json field
+	// (docs/skill-format.md § 4.3). A fork starts clean; discovery labels are derived
+	// server-side from description + SKILL.md, not from an author-supplied keyword list.
 	const forked_manifest = {
 		name: forked_name,
 		version: '0.1.0',
 		type: is_kit ? SKILL_TYPES.KIT : SKILL_TYPES.SKILL,
 		description: '',
-		keywords: [],
 		forked_from: {
 			repo: skill,
 			version: latest_version,

package/src/commands/init.js

@@ -58,11 +58,15 @@ Add the skills this kit bundles and why they work well together.
 Describe the project type or workflow this kit is designed for.
 `
 
+// Note: no `keywords` field. It is a deprecated skill.json field (docs/skill-format.md
+// § 4.3) — the platform-owned taxonomy derives discovery labels server-side from the
+// skill's description + SKILL.md, so an author-supplied keyword list is ignored by
+// search, ranking, and filtering. Emitting an empty `keywords: []` here only baited the
+// enrichment agent into populating a field with no effect; omitting it removes the bait.
 const create_manifest = (name, is_kit = false) => ({
 	name,
 	version: '0.1.0',
 	description: '',
-	keywords: [],
 	type: is_kit ? SKILL_TYPES.KIT : SKILL_TYPES.SKILL,
 	dependencies: {}
 })
@@ -181,4 +185,4 @@ const schema = {
 	],
 }
 
-module.exports = { run, schema }
+module.exports = { run, schema, create_manifest }

package/src/commands/init.test.js

@@ -0,0 +1,29 @@
+'use strict'
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+
+const { create_manifest } = require('./init')
+
+// `keywords` is a deprecated skill.json field — not read by search, ranking, or
+// the platform-owned taxonomy (docs/skill-format.md § 4.3, docs/taxonomy.md § 1).
+// The scaffold must NOT emit an empty `keywords` key: a present-but-empty field is
+// bait that leads the enrichment agent to populate a field the platform ignores.
+describe('create_manifest', () => {
+	it('does not emit a keywords key for a skill scaffold', () => {
+		const manifest = create_manifest('my-skill')
+		assert.ok(!('keywords' in manifest), 'scaffold must not include the deprecated keywords field')
+	})
+
+	it('does not emit a keywords key for a kit scaffold', () => {
+		const manifest = create_manifest('_kit-my-kit', true)
+		assert.ok(!('keywords' in manifest), 'kit scaffold must not include the deprecated keywords field')
+	})
+
+	it('still emits the fields the enrichment workflow fills', () => {
+		const manifest = create_manifest('my-skill')
+		assert.strictEqual(manifest.name, 'my-skill')
+		assert.strictEqual(manifest.version, '0.1.0')
+		assert.strictEqual(manifest.description, '')
+		assert.deepStrictEqual(manifest.dependencies, {})
+	})
+})

package/src/commands/update.js

@@ -25,7 +25,7 @@ Arguments:
   owner/skill       Update a specific skill (optional)
 
 Options:
-  --all             Update all installed root-level skills
+  --all             Update all installed skills (roots and their dependencies)
   --all-scopes      Update BOTH project-local and global skills (in that order),
                     reporting per-scope results. Overrides -g.
   --force           Re-install regardless of version. Also overwrites skills
@@ -66,6 +66,18 @@ const confirm_prompt = (question) => new Promise((resolve) => {
 	})
 })
 
+// Selects which locked skills `update` should consider. With an explicit target, only
+// that skill (if locked). For --all, EVERY installed skill — not just top-level
+// (__root__) ones — so a bundled family satellite installed as a transitive dependency
+// (e.g. happyskills-help under happyskills) is refreshed too. Without this, `update --all`
+// would report staleness (via check/the nudge) it could not resolve. Keeps --all
+// consistent with `check` and the passive drift nudge. A null value is a removed-skill
+// tombstone — skip it. Pure + exported for unit testing.
+const select_update_candidates = (skills, target_skill) =>
+	target_skill
+		? (skills && skills[target_skill] ? [[target_skill, skills[target_skill]]] : [])
+		: Object.entries(skills || {}).filter(([, d]) => d && typeof d === 'object')
+
 /**
  * Run the full update flow for ONE scope (project-local or global) and return
  * `{ scope, data }` — where `data` is exactly the JSON `data` payload that
@@ -89,12 +101,8 @@ const run_scope = (scope_is_global, ctx) => catch_errors('Update scope failed',
 	const skills = get_all_locked_skills(lock_data)
 	const base_dir = skills_dir(scope_is_global, project_root)
 
-	// Determine which skills to consider.
-	// For --all, only root-level skills (transitive deps come along through their parents).
-	// For a specific target, allow any locked skill.
-	const candidates = target_skill
-		? (skills[target_skill] ? [[target_skill, skills[target_skill]]] : [])
-		: Object.entries(skills).filter(([, data]) => data && data.requested_by?.includes('__root__'))
+	// Determine which skills to consider (see select_update_candidates).
+	const candidates = select_update_candidates(skills, target_skill)
 
 	if (candidates.length === 0) {
 		// A missing target is only a hard error in single-scope mode. Across
@@ -433,4 +441,4 @@ const schema = {
 	]
 }
 
-module.exports = { run, schema }
+module.exports = { run, schema, select_update_candidates }

package/src/commands/update.test.js

@@ -0,0 +1,36 @@
+const { test } = require('node:test')
+const assert = require('node:assert')
+
+const { select_update_candidates } = require('./update')
+
+// A normal-user family install: core is __root__, the bundled satellites are transitive
+// dependencies of core (requested_by: [core]). This is what a plain `happyskills setup`
+// produces — the case where the __root__-only filter used to hide the satellites.
+const FAMILY_LOCK = {
+	'happyskillsai/happyskills':      { version: '2.5.4', requested_by: ['__root__'] },
+	'happyskillsai/happyskills-help': { version: '0.8.2', requested_by: ['happyskillsai/happyskills'] },
+	'happyskillsai/happyskills-sync': { version: '0.6.3', requested_by: ['happyskillsai/happyskills'] },
+}
+
+test('update --all considers transitive family satellites, not just __root__ skills', () => {
+	// Coherence fix: `check` and the passive nudge already watch every installed skill;
+	// `update --all` must too, or it reports staleness it cannot resolve via the obvious verb.
+	const names = select_update_candidates(FAMILY_LOCK, undefined).map(([n]) => n)
+	assert.ok(names.includes('happyskillsai/happyskills-help'),
+		'`update --all` must be able to refresh a bundled satellite installed as a transitive dependency')
+	assert.ok(names.includes('happyskillsai/happyskills'), 'root skills are still included')
+})
+
+test('update <target> selects only that skill (root or transitive), or none if unlocked', () => {
+	assert.deepStrictEqual(
+		select_update_candidates(FAMILY_LOCK, 'happyskillsai/happyskills-help').map(([n]) => n),
+		['happyskillsai/happyskills-help'])
+	assert.deepStrictEqual(select_update_candidates(FAMILY_LOCK, 'acme/not-installed'), [])
+})
+
+test('select_update_candidates skips null (removed-skill) tombstones', () => {
+	const lock = { 'acme/root': { version: '1.0.0', requested_by: ['__root__'] }, 'acme/removed': null }
+	const names = select_update_candidates(lock, undefined).map(([n]) => n)
+	assert.ok(names.includes('acme/root'))
+	assert.ok(!names.includes('acme/removed'))
+})

package/src/engine/installer.js

@@ -8,7 +8,7 @@ const { check_system_dependencies } = require('./system_deps')
 const { hash_directory, verify_integrity } = require('../lock/integrity')
 const { read_lock, get_locked_skill } = require('../lock/reader')
 const { write_lock, update_lock_skills } = require('../lock/writer')
-const { verify_lock_disk_consistency } = require('../lock/verify')
+const { verify_lock_disk_consistency, dependency_closure_satisfied } = require('../lock/verify')
 const { skills_dir, tmp_dir, skill_install_dir, lock_root } = require('../config/paths')
 const { ensure_dir, remove_dir, file_exists, read_json } = require('../utils/fs')
 const { SKILL_JSON, SKILL_TYPES } = require('../constants')
@@ -110,7 +110,18 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 			const [, exists] = await file_exists(install_dir)
 			if (exists) {
 				const [, valid] = locked.integrity ? await verify_integrity(install_dir, locked.integrity) : [null, true]
-				if (valid !== false) {
+				// The skill itself is present and intact — but "already installed"
+				// must also mean its declared dependency closure is materialized on
+				// disk. A lock entry can carry a `dependencies` map whose skills were
+				// never installed (e.g. a kit entry written by `publish`, which
+				// records deps but installs nothing). Skipping such an entry leaves
+				// the lock and `.agents/skills/` permanently out of sync. If any
+				// transitive dep is missing, decline the skip and fall through to
+				// resolution so the missing deps get backfilled.
+				const [, closure] = valid !== false
+					? await dependency_closure_satisfied(lock_data, skill, (s) => skill_install_dir(base_dir, s.split('/')[1]))
+					: [null, { satisfied: false, missing: [] }]
+				if (valid !== false && closure && closure.satisfied) {
 					// Verify and repair symlinks even for already-installed skills (skip kits — not agent-invocable)
 					if (agents.length > 0 && locked.type !== SKILL_TYPES.KIT) {
 						const name = skill.split('/')[1]
@@ -134,7 +145,8 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 						forced: []
 					}
 				}
-				// integrity mismatch — fall through to reinstall at locked version
+				// integrity mismatch or an incomplete dependency closure — fall
+				// through to re-resolve and reinstall/backfill at the locked version
 			}
 		}
 	}

package/src/integration/install_dep_closure.test.js

@@ -0,0 +1,122 @@
+'use strict'
+/**
+ * Integration test — install must not report "already installed" for a skill whose
+ * locked dependency closure is not materialized on disk.
+ *
+ * The production bug: a `skills-lock.json` recorded a kit as an installed root
+ * skill (`requested_by: ['__root__']`, valid integrity, present on disk) with a
+ * populated `dependencies` map — but those dependencies were never resolved into
+ * their own lock entries and never landed under `.agents/skills/`. Every
+ * subsequent `install` then hit the pre-resolve skip check, which inspected only
+ * the kit's own directory + integrity and returned "already installed" BEFORE
+ * dependency resolution ran. The missing deps were never backfilled: the lock and
+ * the on-disk `.agents/skills/` were permanently out of sync.
+ *
+ * These tests run the REAL CLI with an unreachable registry (localhost:0). That
+ * isolates the skip decision from the network:
+ *   - If the skip fires, the command SUCCEEDS with "already installed" and never
+ *     touches the network (the buggy behavior).
+ *   - If the skip is correctly declined, the command falls through to resolution
+ *     and FAILS on the unreachable registry (the fixed behavior).
+ * We assert on that difference, plus the inverse: a fully-materialized closure
+ * must still skip (no over-triggering, fast-path preserved).
+ */
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const { spawnSync } = require('child_process')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const CLI = path.resolve(__dirname, '../../bin/happyskills.js')
+const NODE = process.execPath
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-dep-closure-test-'))
+const run = (args, opts) => {
+	const result = spawnSync(NODE, [CLI, ...args, '--text'], {
+		env: { ...process.env, NO_COLOR: '1', HAPPYSKILLS_API_URL: 'http://localhost:0', CI: '', ...(opts?.env || {}) },
+		encoding: 'utf-8',
+		timeout: 15000,
+		cwd: opts?.cwd
+	})
+	return { stdout: result.stdout || '', stderr: result.stderr || '', code: result.status }
+}
+
+// Write a skill directory under <root>/.agents/skills/<name> and return the dir.
+const write_skill = (root, name, manifest) => {
+	const dir = path.join(root, '.agents', 'skills', name)
+	fs.mkdirSync(dir, { recursive: true })
+	fs.writeFileSync(path.join(dir, 'SKILL.md'), `---\nname: ${name}\ndescription: dep-closure test skill\n---\nbody\n`)
+	fs.writeFileSync(path.join(dir, 'skill.json'), JSON.stringify(manifest, null, '\t'))
+	return dir
+}
+
+// Build a project whose lock records `kit` as a __root__ skill (valid integrity,
+// on disk) with the given dependency map. `present_deps` names the deps that are
+// ALSO created on disk + locked; any dep in the map but not in present_deps is
+// declared-but-missing.
+const scaffold = async ({ kit, kit_deps, present_deps }) => {
+	const { hash_directory, clear_integrity_cache } = require('../lock/integrity')
+	const root = make_tmp()
+	const skills = {}
+
+	const kit_dir = write_skill(root, kit, {
+		name: kit, version: '1.0.0', type: 'kit',
+		description: 'dep-closure test kit',
+		dependencies: Object.fromEntries(kit_deps.map(d => [`acme/${d}`, '*']))
+	})
+	clear_integrity_cache()
+	const [, kit_integrity] = await hash_directory(kit_dir)
+	skills[`acme/${kit}`] = {
+		version: '1.0.0', ref: 'refs/tags/v1.0.0', commit: 'c', integrity: kit_integrity,
+		base_commit: 'c', base_integrity: kit_integrity,
+		requested_by: ['__root__'],
+		dependencies: Object.fromEntries(kit_deps.map(d => [`acme/${d}`, '*'])),
+		type: 'kit'
+	}
+
+	for (const dep of present_deps) {
+		const dep_dir = write_skill(root, dep, { name: dep, version: '1.0.0', type: 'skill', description: 'dep' })
+		clear_integrity_cache()
+		const [, dep_integrity] = await hash_directory(dep_dir)
+		skills[`acme/${dep}`] = {
+			version: '1.0.0', ref: 'refs/tags/v1.0.0', commit: 'c', integrity: dep_integrity,
+			base_commit: 'c', base_integrity: dep_integrity,
+			requested_by: [`acme/${kit}`], dependencies: {}, type: 'skill'
+		}
+	}
+
+	fs.writeFileSync(
+		path.join(root, 'skills-lock.json'),
+		JSON.stringify({ lockVersion: 2, generatedAt: new Date().toISOString(), skills }, null, '\t')
+	)
+	return { root, cleanup: () => fs.rmSync(root, { recursive: true, force: true }) }
+}
+
+describe('install — dependency-closure skip guard', () => {
+	it('does NOT report "already installed" when a locked dependency was never materialized', async () => {
+		// kit declares acme/dep-a but dep-a is neither locked nor on disk.
+		const ctx = await scaffold({ kit: 'thekit', kit_deps: ['dep-a'], present_deps: [] })
+		try {
+			const { code, stdout, stderr } = run(['install', 'acme/thekit'], { cwd: ctx.root })
+			const out = stdout + stderr
+			// Fixed behavior: the skip is declined, so install falls through to
+			// resolution and fails against the unreachable registry.
+			assert.doesNotMatch(out, /already installed/i,
+				'must not claim already-installed while a declared dependency is missing')
+			assert.notStrictEqual(code, 0, 'must attempt resolution (and fail on the unreachable registry), not skip')
+		} finally { ctx.cleanup() }
+	})
+
+	it('still skips (already installed, no network) when the whole closure is present', async () => {
+		// Regression guard: a fully-materialized closure must keep the fast path —
+		// skip without any resolution/network call, even with the registry down.
+		const ctx = await scaffold({ kit: 'fullkit', kit_deps: ['dep-a'], present_deps: ['dep-a'] })
+		try {
+			const { code, stdout, stderr } = run(['install', 'acme/fullkit'], { cwd: ctx.root })
+			const out = stdout + stderr
+			assert.match(out, /already installed/i, 'a complete closure must still short-circuit')
+			assert.strictEqual(code, 0, 'skip path must not touch the network')
+		} finally { ctx.cleanup() }
+	})
+})

package/src/lock/verify.js

@@ -118,6 +118,58 @@ const detect_ahead_state = (lock_entry, install_dir) => catch_errors('Failed to
 	}
 })
 
+// dependency_closure_satisfied — walk the locked dependency graph starting at
+// `skill` and confirm every reachable skill is BOTH present in the lock AND
+// materialized on disk. Returns { satisfied: bool, missing: [full skill names] }.
+//
+// This closes the "lock declares deps that were never installed" gap. A lock
+// entry can carry a populated `dependencies` map whose referenced skills have no
+// lock entry and no install directory — e.g. an entry authored by `publish`
+// (which records `manifest.dependencies` but installs nothing), or any install
+// that recorded a root skill while its transitive deps were skipped. In that
+// state the lock and `.agents/skills/` are out of sync.
+//
+// The install skip-check ("already installed") uses this to decide whether a
+// locked-and-present root is actually COMPLETE. If any transitive dependency is
+// missing, the caller must decline the skip and re-resolve so the missing deps
+// get backfilled — the lock must always match what is on disk.
+//
+// `resolve_dir(full_skill_name)` maps `owner/name` to its install directory.
+// Cycle-safe via a visited set. A dependency that is referenced but absent from
+// the lock, or locked but missing on disk, is reported in `missing`.
+const dependency_closure_satisfied = (lock_data, skill, resolve_dir) => catch_errors('Failed to verify dependency closure', async () => {
+	const skills = (lock_data && lock_data.skills) || {}
+	const missing = []
+	const visited = new Set()
+	const queue = [skill]
+
+	while (queue.length > 0) {
+		const current = queue.shift()
+		if (visited.has(current)) continue
+		visited.add(current)
+
+		const entry = skills[current]
+		if (!entry) {
+			// Referenced as a dependency but never locked.
+			missing.push(current)
+			continue
+		}
+
+		const [, dir_present] = await file_exists(resolve_dir(current))
+		if (!dir_present) {
+			// Locked but not materialized on disk.
+			missing.push(current)
+			continue
+		}
+
+		for (const dep_name of Object.keys(entry.dependencies || {})) {
+			if (!visited.has(dep_name)) queue.push(dep_name)
+		}
+	}
+
+	return { satisfied: missing.length === 0, missing }
+})
+
 // Plain-language description of a drift result, suitable for the principal-facing
 // table cell (status column). Returns null when ok or ahead.
 const describe_drift = (verify_result) => {
@@ -179,5 +231,6 @@ module.exports = {
 	detect_ahead_state,
 	describe_drift,
 	classify_lock_disk,
-	parse_changelog_top_version
+	parse_changelog_top_version,
+	dependency_closure_satisfied
 }

package/src/lock/verify.test.js

@@ -10,7 +10,8 @@ const {
 	detect_ahead_state,
 	describe_drift,
 	classify_lock_disk,
-	parse_changelog_top_version
+	parse_changelog_top_version,
+	dependency_closure_satisfied
 } = require('./verify')
 
 const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-verify-test-'))
@@ -276,6 +277,113 @@ describe('classify_lock_disk', () => {
 	})
 })
 
+describe('dependency_closure_satisfied', () => {
+	// A skill directory is "present" iff it exists on disk. We model the disk with a
+	// temp root and create a sub-dir per skill that is supposed to be installed.
+	const make_root = () => make_tmp()
+	const present = (root, skill) => {
+		const dir = path.join(root, skill.replace('/', '__'))
+		fs.mkdirSync(dir, { recursive: true })
+		return dir
+	}
+	const resolver = (root) => (skill) => path.join(root, skill.replace('/', '__'))
+
+	const lock = (skills) => ({ lockVersion: 2, skills })
+
+	it('is satisfied when the root and its whole locked dep closure are present on disk', async () => {
+		const root = make_root()
+		try {
+			present(root, 'acme/kit')
+			present(root, 'acme/dep-a')
+			present(root, 'acme/dep-b')
+			const data = lock({
+				'acme/kit': { version: '1.0.0', dependencies: { 'acme/dep-a': '*', 'acme/dep-b': '*' } },
+				'acme/dep-a': { version: '1.0.0', dependencies: {} },
+				'acme/dep-b': { version: '1.0.0', dependencies: {} }
+			})
+			const [err, result] = await dependency_closure_satisfied(data, 'acme/kit', resolver(root))
+			assert.strictEqual(err, null)
+			assert.deepEqual(result, { satisfied: true, missing: [] })
+		} finally { cleanup(root) }
+	})
+
+	it('is NOT satisfied when a declared dependency has no lock entry (the kit-deps-never-installed bug)', async () => {
+		// This is the exact production shape: the kit is locked + on disk, its
+		// `dependencies` map is populated, but those deps were never resolved into
+		// their own lock entries and never landed on disk.
+		const root = make_root()
+		try {
+			present(root, 'acme/kit')
+			const data = lock({
+				'acme/kit': { version: '1.0.0', dependencies: { 'acme/dep-a': '*', 'acme/dep-b': '*' } }
+			})
+			const [err, result] = await dependency_closure_satisfied(data, 'acme/kit', resolver(root))
+			assert.strictEqual(err, null)
+			assert.strictEqual(result.satisfied, false)
+			assert.deepEqual(result.missing.sort(), ['acme/dep-a', 'acme/dep-b'])
+		} finally { cleanup(root) }
+	})
+
+	it('is NOT satisfied when a dependency is locked but its directory is missing on disk', async () => {
+		const root = make_root()
+		try {
+			present(root, 'acme/kit')
+			// acme/dep-a is locked but NOT created on disk.
+			const data = lock({
+				'acme/kit': { version: '1.0.0', dependencies: { 'acme/dep-a': '*' } },
+				'acme/dep-a': { version: '1.0.0', dependencies: {} }
+			})
+			const [err, result] = await dependency_closure_satisfied(data, 'acme/kit', resolver(root))
+			assert.strictEqual(err, null)
+			assert.strictEqual(result.satisfied, false)
+			assert.deepEqual(result.missing, ['acme/dep-a'])
+		} finally { cleanup(root) }
+	})
+
+	it('walks transitively — a missing dep-of-a-dep still fails the closure', async () => {
+		const root = make_root()
+		try {
+			present(root, 'acme/kit')
+			present(root, 'acme/dep-a')
+			// acme/dep-a depends on acme/deep, which is neither locked nor on disk.
+			const data = lock({
+				'acme/kit': { version: '1.0.0', dependencies: { 'acme/dep-a': '*' } },
+				'acme/dep-a': { version: '1.0.0', dependencies: { 'acme/deep': '*' } }
+			})
+			const [err, result] = await dependency_closure_satisfied(data, 'acme/kit', resolver(root))
+			assert.strictEqual(err, null)
+			assert.strictEqual(result.satisfied, false)
+			assert.deepEqual(result.missing, ['acme/deep'])
+		} finally { cleanup(root) }
+	})
+
+	it('is cycle-safe (A → B → A) and does not loop forever', async () => {
+		const root = make_root()
+		try {
+			present(root, 'acme/a')
+			present(root, 'acme/b')
+			const data = lock({
+				'acme/a': { version: '1.0.0', dependencies: { 'acme/b': '*' } },
+				'acme/b': { version: '1.0.0', dependencies: { 'acme/a': '*' } }
+			})
+			const [err, result] = await dependency_closure_satisfied(data, 'acme/a', resolver(root))
+			assert.strictEqual(err, null)
+			assert.deepEqual(result, { satisfied: true, missing: [] })
+		} finally { cleanup(root) }
+	})
+
+	it('is satisfied for a leaf skill with no dependencies', async () => {
+		const root = make_root()
+		try {
+			present(root, 'acme/solo')
+			const data = lock({ 'acme/solo': { version: '1.0.0', dependencies: {} } })
+			const [err, result] = await dependency_closure_satisfied(data, 'acme/solo', resolver(root))
+			assert.strictEqual(err, null)
+			assert.deepEqual(result, { satisfied: true, missing: [] })
+		} finally { cleanup(root) }
+	})
+})
+
 describe('describe_drift', () => {
 	it('returns null for ok results', () => {
 		assert.strictEqual(describe_drift({ ok: true }), null)

package/src/ui/envelope.test.js

@@ -34,7 +34,7 @@ test('drift set → appends a SKILLS_UPDATE_AVAILABLE warning without touching d
 		assert.strictEqual(env.warnings[0].code, 'SKILLS_UPDATE_AVAILABLE')
 		assert.match(env.warnings[0].message, /2 installed skill\(s\) behind the registry/)
 		assert.match(env.warnings[0].message, /acme\/x, acme\/y/)
-		assert.match(env.warnings[0].message, /npx happyskills update --all/)
+		assert.match(env.warnings[0].message, /npx happyskills update acme\/x acme\/y/)
 	})
 })
 

package/src/utils/skill_update_check.js

@@ -44,9 +44,19 @@ const write_scope = (key, outdated) => {
 	}
 }
 
+// Selects which locked skills to check for registry drift: EVERY installed skill,
+// not just __root__ entries. A bundled family satellite (e.g. happyskills-help) is
+// pulled in as a transitive dependency of core — its lock entry reads
+// requested_by:['happyskillsai/happyskills'], NOT ['__root__'] — so a __root__-only
+// filter silently never nudged about it even when it fell behind. Mirrors the
+// "check every installed skill" enumeration in commands/check.js. A null value is a
+// removed-skill tombstone — skip it. Extracted as a pure function for unit testing.
+const select_drift_candidates = (skills) =>
+	Object.entries(skills || {}).filter(([, d]) => d && typeof d === 'object')
+
 // Background refresh — NOT awaited, all errors swallowed. Reads the lock directly
 // (NOT via lock/reader.read_lock, which prints a stderr warning on version mismatch
-// — unwanted noise from a silent background task), batch-checks root skills against
+// — unwanted noise from a silent background task), batch-checks every installed skill against
 // the registry, and records ONLY the genuinely-outdated ones. It never reads the
 // working tree, so it can never mistake an `ahead` (locally-bumped, unpublished) or
 // regression-drifted skill for "outdated": a local bump leaves base_commit untouched,
@@ -60,8 +70,7 @@ const refresh_cache = (key, opts) => {
 		const lock_path = lock_file_path(lock_root(opts.is_global, opts.project_root))
 		const [, lock_data] = await read_json(lock_path)
 		const skills = (lock_data && lock_data.skills) || {}
-		const candidates = Object.entries(skills)
-			.filter(([, d]) => d && Array.isArray(d.requested_by) && d.requested_by.includes('__root__'))
+		const candidates = select_drift_candidates(skills)
 
 		if (candidates.length === 0) { write_scope(key, []); return }
 
@@ -140,11 +149,17 @@ const format_skill_drift = (verdict) => {
 	const items = verdict.outdated
 	const names = items.slice(0, 3).map(s => s.skill).join(', ')
 	const more = items.length > 3 ? `, +${items.length - 3} more` : ''
-	let cmd
-	if (verdict.has_global && verdict.has_local) cmd = 'npx happyskills update --all (and add -g for the global ones)'
-	else if (verdict.has_global) cmd = 'npx happyskills update --all -g'
-	else cmd = 'npx happyskills update --all'
-	return `${items.length} installed skill(s) behind the registry (${names}${more}). Run: ${cmd}`
+	// Name the outdated skills explicitly rather than suggesting `update --all`.
+	// `update --all` only re-checks __root__ skills, so it can never refresh a bundled
+	// satellite installed as a transitive dependency — but `update <owner/name>` fixes
+	// ANY locked skill. Group by scope: a global skill needs -g, and one update run
+	// writes a single scope. Items with no scope default to local.
+	const local = items.filter(i => i.scope !== 'global').map(i => i.skill)
+	const global = items.filter(i => i.scope === 'global').map(i => i.skill)
+	const cmds = []
+	if (local.length) cmds.push(`npx happyskills update ${local.join(' ')}`)
+	if (global.length) cmds.push(`npx happyskills update ${global.join(' ')} -g`)
+	return `${items.length} installed skill(s) behind the registry (${names}${more}). Run: ${cmds.join('  &&  ')}`
 }
 
-module.exports = { check_skills_for_update, format_skill_drift, get_cache_path, scope_key }
+module.exports = { check_skills_for_update, format_skill_drift, select_drift_candidates, get_cache_path, scope_key }

package/src/utils/skill_update_check.test.js

@@ -4,7 +4,7 @@ const fs = require('fs')
 const os = require('os')
 const path = require('path')
 
-const { check_skills_for_update, format_skill_drift, get_cache_path, scope_key } = require('./skill_update_check')
+const { check_skills_for_update, format_skill_drift, select_drift_candidates, get_cache_path, scope_key } = require('./skill_update_check')
 
 const PROJECT_ROOT = '/proj'
 const PKEY = scope_key({ is_global: false, project_root: PROJECT_ROOT })
@@ -53,7 +53,7 @@ test('project-only drift → verdict flagged local, no -g in the message', () =>
 		assert.strictEqual(v.outdated.length, 1)
 		assert.strictEqual(v.has_local, true)
 		assert.strictEqual(v.has_global, false)
-		assert.match(format_skill_drift(v), /update --all$/)
+		assert.match(format_skill_drift(v), /Run: npx happyskills update acme\/x$/)
 	})
 })
 
@@ -64,7 +64,7 @@ test('global-only drift → verdict flagged global, message uses -g', () => {
 		assert.ok(v)
 		assert.strictEqual(v.has_local, false)
 		assert.strictEqual(v.has_global, true)
-		assert.match(format_skill_drift(v), /update --all -g$/)
+		assert.match(format_skill_drift(v), /Run: npx happyskills update happyskillsai\/happyskills -g$/)
 	})
 })
 
@@ -75,7 +75,9 @@ test('drift in BOTH scopes → merged, both flags set, message mentions -g for g
 		assert.strictEqual(v.outdated.length, 2)
 		assert.strictEqual(v.has_local, true)
 		assert.strictEqual(v.has_global, true)
-		assert.match(format_skill_drift(v), /add -g for the global ones/)
+		const msg = format_skill_drift(v)
+		assert.match(msg, /npx happyskills update acme\/x/)
+		assert.match(msg, /npx happyskills update happyskillsai\/happyskills -g/)
 	})
 })
 
@@ -116,3 +118,38 @@ test('localhost:0 test API sentinel short-circuits to null', () => {
 		assert.strictEqual(check_skills_for_update({ project_root: PROJECT_ROOT }), null)
 	})
 })
+
+// ─── Regression: the passive check must watch the WHOLE installed family ─────────
+// A bundled family satellite (design/publish/sync/search/help) is installed as a
+// transitive dependency of core, so its lock entry is requested_by:[core], NOT
+// [__root__]. A __root__-only enumeration silently never nudged about it even when it
+// fell behind the registry — the gap this suite pins shut. See docs/cli-overview.md § 3.
+
+test('select_drift_candidates watches transitive dependencies, not just __root__ skills', () => {
+	const skills = {
+		'happyskillsai/happyskills':      { version: '2.5.4', base_commit: 'aaa', requested_by: ['__root__'] },
+		'happyskillsai/happyskills-help': { version: '0.8.2', base_commit: 'bbb', requested_by: ['happyskillsai/happyskills'] },
+	}
+	const names = select_drift_candidates(skills).map(([n]) => n)
+	assert.ok(names.includes('happyskillsai/happyskills-help'),
+		'a bundled satellite pulled in as a transitive dependency must still be checked for updates')
+})
+
+test('select_drift_candidates keeps __root__ skills and skips null (removed-skill) tombstones', () => {
+	const skills = {
+		'acme/root':    { version: '1.0.0', requested_by: ['__root__'] },
+		'acme/removed': null,
+	}
+	const names = select_drift_candidates(skills).map(([n]) => n)
+	assert.ok(names.includes('acme/root'))
+	assert.ok(!names.includes('acme/removed'))
+})
+
+test('format_skill_drift names the skills (works for transitive deps), never suggests update --all', () => {
+	// `update --all` only re-checks __root__ skills, so it can never refresh a bundled
+	// satellite. The remedy must name the skill: `update <owner/name>` fixes ANY locked skill.
+	const verdict = { outdated: [{ skill: 'happyskillsai/happyskills-help', installed: '0.8.2', latest: '0.9.0', scope: 'local' }], has_local: true, has_global: false }
+	const msg = format_skill_drift(verdict)
+	assert.match(msg, /npx happyskills update happyskillsai\/happyskills-help/)
+	assert.doesNotMatch(msg, /update --all/)
+})