happyskills 1.7.1 → 1.9.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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
+
+- Record installs via a cache-immune `install.completed` beacon. The install engine now emits one `install.completed` event per newly-installed skill — the root **and** each transitive dependency — batched into a single `POST /events`, carrying the skill's `repo_id`, version, and a root-vs-dependency flag. Because it fires from the engine, `setup` is now counted too (previously it emitted nothing). This replaces the per-command `install.completed` event and is the new source of truth for install/download counts, fixing the under-count caused by CDN cache hits on the clone endpoint silently skipping the old counting path. Fire-and-forget — a telemetry failure never blocks or fails an install; an already-up-to-date (no-op) install emits nothing. Requires API v5.5.0+ for `repo_id` stamping and download-count crediting; against older APIs the events are still sent (forward-compatible).
+
 ## [1.7.1] - 2026-06-04
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.7.1",
+	"version": "1.9.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/install.js

@@ -214,7 +214,10 @@ const run = (args) => catch_errors('Install failed', async () => {
 			emit_analytics('install.failed', { error_code: 'INSTALL_FAILED', cli_version: CLI_VERSION })
 		} else {
 			results.push({ skill, result })
-			emit_analytics('install.completed', { cli_version: CLI_VERSION })
+			// install.completed is now emitted per-skill from the install engine
+			// (cli/src/engine/installer.js, spec 260604-01) — carrying repo_id,
+			// version, and a root-vs-dependency flag — so setup (which bypasses
+			// this command) is covered too. No per-command emit here.
 		}
 	}
 

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

@@ -14,14 +14,47 @@ 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')
+const { CLI_VERSION } = require('../constants')
 
 const _format_warnings = (missing_deps) => (missing_deps || []).map(dep => {
 	const hint = dep.install_hint ? ` (install: ${dep.install_hint})` : ''
 	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 }) =>
@@ -64,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)
 
@@ -316,11 +349,36 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 			}
 		}
 
+		// Cache-immune install counting (spec 260604-01). Fire one
+		// install.completed beacon per newly-installed skill — root AND each
+		// transitive dependency — batched into a single POST /events. This is the
+		// source of truth for install/download counts: it replaces the clone-
+		// endpoint side-effect that CloudFront cache HITs silently dropped. Only
+		// reached on a genuine install (no_op paths returned earlier and emit
+		// nothing). Fire-and-forget — never blocks or fails the install.
+		emit_batch(downloaded.map(({ pkg }) => {
+			const requested_by = updates[pkg.skill]?.requested_by || []
+			return {
+				event_type: 'install.completed',
+				repo_id: pkg.repo_id || null,
+				metadata: {
+					version: pkg.version,
+					dependency: !requested_by.includes('__root__'),
+					cli_version: CLI_VERSION,
+				},
+			}
+		}))
+
 		spinner.succeed(`Installed ${packages_to_install.length} package(s)`)
 
 		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)
@@ -339,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):`)
@@ -364,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)
@@ -424,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), [])
+	})
+})

package/src/utils/analytics.js

@@ -7,25 +7,35 @@
 
 const { error: { catch_errors } } = require('puffy-core')
 
-const post_event = (event_type, metadata) => catch_errors('Failed to post analytics event', async () => {
+const post_events = (events) => catch_errors('Failed to post analytics events', async () => {
 	const { post } = require('../api/client')
-	// Use unwrap:false so we don't trip on the empty body.
-	await post('/events', { events: [{
-		event_type,
-		metadata: metadata || {},
+	const stamped = events.map(ev => ({
+		event_type: ev.event_type,
+		...(ev.repo_id ? { repo_id: ev.repo_id } : {}),
+		metadata: ev.metadata || {},
 		client_ts: Date.now(),
-	}] }, { auth: true, unwrap: false })
+	}))
+	// Use unwrap:false so we don't trip on the empty body.
+	await post('/events', { events: stamped }, { auth: true, unwrap: false })
 })
 
 // Caller-friendly wrapper. Errors are swallowed — engagement telemetry must
 // never block the user.
-const emit = (event_type, metadata) => {
+const emit = (event_type, metadata) => emit_batch([{ event_type, metadata }])
+
+// Batched emit — sends N events in a single POST /events. Used by the install
+// engine to record one install.completed per installed skill (root + each
+// transitive dependency) in one request (spec 260604-01). Each event may carry
+// a top-level `repo_id` (UUID); per-event metadata is passed through as-is.
+const emit_batch = (events) => {
+	if (!Array.isArray(events) || events.length === 0) return
 	// Don't return the promise — fire-and-forget. Errors stay quiet.
-	post_event(event_type, metadata).then(([errors]) => {
+	post_events(events).then(([errors]) => {
 		if (errors && process.env.HAPPYSKILLS_DEBUG) {
-			process.stderr.write(`[analytics] ${event_type} failed: ${errors[0]?.message || 'unknown'}\n`)
+			const types = events.map(e => e.event_type).join(',')
+			process.stderr.write(`[analytics] ${types} failed: ${errors[0]?.message || 'unknown'}\n`)
 		}
 	}).catch(() => {})
 }
 
-module.exports = { emit }
+module.exports = { emit, emit_batch }

package/src/utils/analytics.test.js

@@ -0,0 +1,89 @@
+// Run with: node --test src/utils/analytics.test.js  (also covered by `npm test`)
+//
+// Unit tests for the batched analytics emitter (spec 260604-01). The install
+// engine fires one install.completed event per installed skill (root + each
+// dependency) batched into a SINGLE POST /events, with repo_id riding the
+// top-level event field and version/dependency/cli_version in metadata. The
+// emitter is fire-and-forget — it must never throw into the caller.
+
+const { describe, it, afterEach } = require('node:test')
+const assert = require('node:assert')
+
+// Stub the API client before requiring the module under test, so we capture the
+// exact POST payload emit_batch produces. analytics.js lazy-requires the client
+// inside the post, so seeding require.cache here is enough.
+const stub_client = (calls) => {
+	const client_path = require.resolve('../api/client')
+	require.cache[client_path] = {
+		id: client_path,
+		filename: client_path,
+		loaded: true,
+		exports: {
+			post: async (path, body, opts) => { calls.push({ path, body, opts }); return [null, null] },
+		},
+	}
+	delete require.cache[require.resolve('./analytics')]
+	return require('./analytics')
+}
+
+const restore = () => {
+	delete require.cache[require.resolve('../api/client')]
+	delete require.cache[require.resolve('./analytics')]
+}
+
+// emit_batch is fire-and-forget — give the microtask/promise chain a tick.
+const tick = () => new Promise(r => setImmediate(r))
+
+describe('emit_batch — install.completed beacon', () => {
+	afterEach(restore)
+
+	it('sends ONE POST /events for N skills, repo_id top-level, version+dependency in metadata', async () => {
+		const calls = []
+		const { emit_batch } = stub_client(calls)
+		emit_batch([
+			{ event_type: 'install.completed', repo_id: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa', metadata: { version: '1.0.0', dependency: false, cli_version: '9.9.9' } },
+			{ event_type: 'install.completed', repo_id: 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb', metadata: { version: '2.0.0', dependency: true, cli_version: '9.9.9' } },
+		])
+		await tick()
+
+		assert.equal(calls.length, 1, 'a constellation install is a single batched request')
+		assert.equal(calls[0].path, '/events')
+		assert.equal(calls[0].opts.auth, true)
+		const evts = calls[0].body.events
+		assert.equal(evts.length, 2)
+		assert.equal(evts[0].repo_id, 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa')
+		assert.equal(evts[0].metadata.dependency, false)
+		assert.equal(evts[0].metadata.version, '1.0.0')
+		assert.equal(evts[1].repo_id, 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb')
+		assert.equal(evts[1].metadata.dependency, true)
+		assert.ok(typeof evts[0].client_ts === 'number', 'each event is timestamped')
+	})
+
+	it('no-ops on an empty batch (zero installed skills → no request)', async () => {
+		const calls = []
+		const { emit_batch } = stub_client(calls)
+		emit_batch([])
+		await tick()
+		assert.equal(calls.length, 0)
+	})
+
+	it('omits repo_id from the wire when it is null/absent', async () => {
+		const calls = []
+		const { emit_batch } = stub_client(calls)
+		emit_batch([{ event_type: 'install.completed', repo_id: null, metadata: { version: '1.0.0' } }])
+		await tick()
+		assert.equal('repo_id' in calls[0].body.events[0], false)
+	})
+
+	it('swallows a client error — telemetry never throws into the install flow', async () => {
+		const client_path = require.resolve('../api/client')
+		require.cache[client_path] = {
+			id: client_path, filename: client_path, loaded: true,
+			exports: { post: async () => { throw new Error('network down') } },
+		}
+		delete require.cache[require.resolve('./analytics')]
+		const { emit_batch } = require('./analytics')
+		assert.doesNotThrow(() => emit_batch([{ event_type: 'install.completed', metadata: {} }]))
+		await tick()
+	})
+})