happyskills 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.14.0] - 2026-06-30
+
+### Added
+
+- Add the `happyskills match <folder>` command — scan a local folder of skills and find which ones already exist in HappySkills, and how your local copy differs. It fingerprints each skill the same way publish does (the `SKILL.md` git-blob hash plus a git tree hash over the normalized fileset, with symlinked skill roots resolved to real content), then matches against the catalog through a staged funnel — one batched `POST /repos:match` for the whole folder, a tree-SHA compare, a bounded `POST /repos:manifests` per-file diff, and a semantic fallback — never downloading file content to classify. Each skill lands in exactly one tier: `certified` (byte-identical), `near` (same skill, some files differ — with the exact differing-file list), `likely` (name match only), `possible` (loose semantic match), or `unmatched`. Read-only: it reports matches and makes no changes, emitting a `next_step` decision (`organize_matched_skills`) pointing at favoriting or kit organization. Flags: `--json`, `--concurrency <N>` (default 6), `--threshold <N>` (default 0.5). Requires API ≥ 5.17.0 (the `POST /repos:match` + `POST /repos:manifests` endpoints).
+
+## [1.13.1] - 2026-06-29
+
+### Fixed
+
+- Stop a transient session-refresh hiccup from becoming a terminal "session expired" auth failure on a **write** (`publish`/`release` and other authenticated writes). When your `id_token` had expired and the automatic refresh blipped (a network/cold-start failure on the refresh call), the CLI would fire the write with no token, the API would answer `401`, and that was rendered as `AUTH_REQUIRED` ("your session has expired … run `happyskills login`") — aborting the command even though an immediate retry succeeds. Now, when valid credentials exist on disk but the token simply couldn't be refreshed at that moment, a write surfaces a **retryable** `NETWORK_ERROR` (a `retry` `next_step`) instead of sending a tokenless request. The guard is deliberately narrow: **reads are unchanged** (a `GET` still degrades to anonymous/public results), a **corrupt/unreadable credentials file** still falls through to re-login (it is not turned into an infinite "please retry" loop), and the genuinely-not-signed-in case (no credentials) is unchanged. (Spec 260629-02.)
+
 ## [1.13.0] - 2026-06-29
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.13.0",
+	"version": "1.14.0",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",
@@ -47,6 +47,7 @@
 		"@jimp/js-jpeg": "1.6.1",
 		"@jimp/js-png": "1.6.1",
 		"@jimp/plugin-resize": "1.6.1",
+		"core-async": "^3.1.0",
 		"node-diff3": "3.2.0",
 		"puffy-core": "1.3.1",
 		"semver": "7.7.4",

package/src/api/client.js

@@ -2,7 +2,7 @@ const { createHash } = require('crypto')
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { API_URL, CLI_VERSION } = require('../constants')
 const { ApiError, NetworkError, AuthError } = require('../utils/errors')
-const { load_token } = require('../auth/token_store')
+const { load_token, credentials_present } = require('../auth/token_store')
 const { get_envelope, set_envelope } = require('../utils/intent')
 
 const get_base_url = () => process.env.HAPPYSKILLS_API_URL || API_URL
@@ -29,10 +29,28 @@ const request = (method, path, options = {}) => catch_errors(`API ${method} ${pa
 
 	let token_attached = false
 	if (auth) {
-		const [, token_data] = await load_token()
+		const [token_err, token_data] = await load_token()
 		if (token_data) {
 			headers['Authorization'] = `Bearer ${token_data.id_token}`
 			token_attached = true
+		} else if (!token_err && credentials_present() && method !== 'GET' && method !== 'HEAD') {
+			// A WRITE (non-GET/HEAD) where load_token returned CLEANLY (no error) with no
+			// token, yet the credentials file still exists. That is uniquely the
+			// TRANSIENT-refresh-failure branch: a real session whose id_token expired and
+			// whose proactive refresh blipped (network / cold start) — load_token preserves
+			// the still-valid file and returns [null, null]. Permanent failures (Cognito
+			// rejected the token) and the no-refresh-token case both DELETE the file, and a
+			// corrupt/unreadable file returns [errors, undefined] (token_err set) — so
+			// guarding on `!token_err && file-present` isolates the genuinely-retryable case
+			// and lets a corrupt file fall through to a tokenless request (→ server 401 →
+			// re-login, which overwrites the bad file) rather than a dead retry loop.
+			// Firing a tokenless WRITE in the transient case makes the API answer 401 and
+			// the CLI render it as a terminal AUTH_REQUIRED "your session has expired" — the
+			// spurious-AUTH_REQUIRED bug (spec 260629-02). Surface a retryable error instead.
+			// Scoped to writes ONLY: a read (GET/HEAD) keeps its pre-existing behavior —
+			// proceed tokenless and degrade to anonymous/public results (spec §6.3: "keep
+			// the read-path behavior unchanged"); a write must not silently lose authorship.
+			throw new NetworkError('Your session could not be refreshed right now (a temporary issue). Please retry.')
 		}
 	}
 

package/src/api/client.test.js

@@ -122,3 +122,156 @@ describe('api client — 401 message never tells a signed-in user to log in', ()
 		})
 	})
 })
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Transient backend failure on a write/publish path (spec 260629-02). The API no
+// longer maps a transient verify/lookup hiccup to a 401 "session expired" — it
+// returns a retryable 503 DB_UNAVAILABLE. The CLI must surface that as a RETRY
+// affordance, NOT collapse it into an AUTH_REQUIRED / "run login" dead-end. This
+// is the operator-facing half of the fix: an authenticated, authorized operator
+// whose publish hit a blip is told to retry (and an immediate retry succeeds),
+// instead of being sent down a pointless re-login path.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const with_503 = async (code, fn) => {
+	const orig = global.fetch
+	global.fetch = async () => ({
+		ok: false,
+		status: 503,
+		headers: { get: () => null },
+		json: async () => ({ error: { code, message: 'Authentication is temporarily unavailable. Please retry.' } }),
+	})
+	try { return await fn() } finally { global.fetch = orig }
+}
+
+describe('api client — transient 503 on publish surfaces retry, not a login dead-end (spec 260629-02)', () => {
+	const { next_step_for_error } = require('../constants/next_step_by_error_code')
+
+	it('a 503 DB_UNAVAILABLE on push preserves the retryable code (NOT AUTH_REQUIRED)', async () => {
+		await with_503('DB_UNAVAILABLE', async () => {
+			const [errors] = await client.post('/repos/acme/deploy/push', { commit: 'x' }, { auth: false })
+			assert.ok(errors, 'expected an error tuple')
+			const err = errors.find(e => e && e.name === 'ApiError')
+			assert.ok(err, 'a 503 must surface as an ApiError, not an AuthError')
+			assert.equal(err.code, 'DB_UNAVAILABLE')
+			assert.notEqual(err.code, 'AUTH_REQUIRED')
+			assert.equal(err.status_code, 503)
+		})
+	})
+
+	it('the operator-facing next_step for that code is RETRY, not login', () => {
+		const next_step = next_step_for_error('DB_UNAVAILABLE', 'whatever', {})
+		assert.equal(next_step.action, 'retry')
+		assert.notEqual(next_step.action, 'login')
+	})
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The ACTUAL 2026-06-29 incident (spec 260629-02 Findings): the operator's session
+// had expired and the CLI's proactive token refresh hit a TRANSIENT failure. On a
+// transient refresh failure, load_token preserves the (still-valid) refresh_token
+// on disk but returns null — so the client fired an authed request WITHOUT a token,
+// the API answered 401 (no-token branch), and the CLI rendered it as AUTH_REQUIRED
+// "session expired". An immediate retry (after the refresh blip cleared) succeeded.
+//
+// The fix: a real session whose token can't be refreshed *right now* (file present
+// but load_token null) must surface a RETRYABLE error, never a tokenless request
+// that turns into a terminal "session expired".
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('api client — transient token-refresh failure → retry, never a tokenless 401 (spec 260629-02)', () => {
+	const auth_path = require.resolve('./auth')
+
+	const write_expired_token = (dir) => {
+		const token = {
+			id_token: 'expired-id-token',
+			access_token: 'expired-access-token',
+			refresh_token: 'still-valid-refresh-token',
+			expires_in: 1,
+			stored_at: new Date(Date.now() - 5000).toISOString(),
+		}
+		fs.mkdirSync(path.join(dir, 'happyskills'), { recursive: true })
+		fs.writeFileSync(path.join(dir, 'happyskills', 'credentials.json'), JSON.stringify(token), { mode: 0o600 })
+	}
+
+	// Make the refresh endpoint fail transiently (NetworkError) for both attempts.
+	const with_transient_refresh = async (fn) => {
+		const { NetworkError } = require('../utils/errors')
+		const orig = require.cache[auth_path]
+		require.cache[auth_path] = {
+			id: auth_path, filename: auth_path, loaded: true,
+			exports: { refresh: async () => [[new NetworkError('refresh endpoint unreachable')], null] },
+		}
+		try { return await fn() } finally {
+			if (orig) require.cache[auth_path] = orig; else delete require.cache[auth_path]
+		}
+	}
+
+	it('expired session + transient refresh blip on a push → retryable NetworkError, no tokenless request, NOT AUTH_REQUIRED', async () => {
+		await with_tmp_config(async (dir) => {
+			write_expired_token(dir)
+			await with_transient_refresh(async () => {
+				let fetched = false
+				const orig_fetch = global.fetch
+				global.fetch = async () => { fetched = true; return { ok: true, status: 200, headers: { get: () => null }, json: async () => ({ data: {} }) } }
+				try {
+					const [errors] = await client.post('/acme/deploy/push', { commit: 'z' })
+					assert.ok(errors, 'expected an error tuple')
+					assert.equal(fetched, false, 'must NOT fire a tokenless authed request when the session merely failed to refresh')
+					assert.ok(errors.find(e => e && e.name === 'NetworkError'), 'a transient refresh failure must surface as a retryable NetworkError')
+					assert.ok(!errors.find(e => e && e.name === 'AuthError'), 'must NOT surface AUTH_REQUIRED / "session expired" for a transient refresh blip')
+				} finally { global.fetch = orig_fetch }
+			})
+		})
+	})
+
+	it('NO credentials at all → proceeds tokenless (anonymous), unchanged', async () => {
+		await with_tmp_config(async () => {
+			// No creds file written → genuinely not signed in.
+			let fetched = false
+			const orig_fetch = global.fetch
+			global.fetch = async () => { fetched = true; return { ok: true, status: 200, headers: { get: () => null }, json: async () => ({ data: {} }) } }
+			try {
+				await client.get('/repos:search')
+				assert.equal(fetched, true, 'with no session, the request still goes out (server decides auth)')
+			} finally { global.fetch = orig_fetch }
+		})
+	})
+
+	it('transient refresh blip on a GET (read) → proceeds tokenless (anonymous), read-path unchanged (spec §6.3)', async () => {
+		await with_tmp_config(async (dir) => {
+			write_expired_token(dir)
+			await with_transient_refresh(async () => {
+				let fetched = false
+				const orig_fetch = global.fetch
+				global.fetch = async () => { fetched = true; return { ok: true, status: 200, headers: { get: () => null }, json: async () => ({ data: {} }) } }
+				try {
+					const [errors] = await client.get('/repos:search')
+					assert.equal(fetched, true, 'a read must still go out tokenless during a refresh blip (degrade to anonymous), not throw')
+					assert.ok(!errors || !errors.find(e => e && e.name === 'NetworkError'), 'reads keep their pre-existing anonymous-degrade behavior')
+				} finally { global.fetch = orig_fetch }
+			})
+		})
+	})
+
+	// A corrupt/unparseable credentials file ALSO leaves the file on disk while
+	// load_token yields no token — but it returns an ERROR (JSON.parse throws),
+	// NOT a clean null like the transient-refresh branch. It must NOT be treated as
+	// a retryable refresh blip (retrying never fixes a corrupt file → a dead loop).
+	// The actionable path is the pre-existing one: proceed tokenless so the server
+	// 401s and the user is steered to re-login (which overwrites the bad file).
+	it('corrupt credentials file → does NOT become a retry loop; proceeds tokenless so re-login is reachable', async () => {
+		await with_tmp_config(async (dir) => {
+			fs.mkdirSync(path.join(dir, 'happyskills'), { recursive: true })
+			fs.writeFileSync(path.join(dir, 'happyskills', 'credentials.json'), 'not-valid-json{{{', { mode: 0o600 })
+			let fetched = false
+			const orig_fetch = global.fetch
+			global.fetch = async () => { fetched = true; return { ok: true, status: 200, headers: { get: () => null }, json: async () => ({ data: {} }) } }
+			try {
+				const [errors] = await client.post('/acme/deploy/push', { commit: 'z' })
+				assert.equal(fetched, true, 'a corrupt creds file must proceed tokenless (server → 401 → login), not throw a retryable error')
+				assert.ok(!errors || !errors.find(e => e && e.name === 'NetworkError'), 'a corrupt creds file must NOT be reported as a transient/retryable refresh failure')
+			} finally { global.fetch = orig_fetch }
+		})
+	})
+})

package/src/api/repos.js

@@ -213,4 +213,26 @@ const semantic_search = (query, options = {}) => catch_errors('Semantic search f
 	return data
 })
 
-module.exports = { search, dispatch_search, semantic_search, resolve_dependencies, clone, push, get_refs, get_repo, check_updates, del_repo, patch_repo, star, unstar, compare, get_blob, get_tree }
+// POST /repos:match — catalog matching for `happyskills match` (spec 260629-03).
+// ONE batch call for the whole folder's hashes + names. Returns
+// { results: [{ skill_md_sha, candidates }], name_results: [{ name, candidates }] }
+// (two keys, so the client's single-key unwrap leaves it intact).
+const match = (hashes, names) => catch_errors('Catalog match lookup failed', async () => {
+	const [errors, data] = await client.post('/repos:match', { hashes, names: names || [] })
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+// POST /repos:manifests — per-file manifests for a narrowed candidate set.
+// unwrap:false so we can surface the envelope's warnings (a repo we couldn't
+// read becomes a warning, not a thrown error) alongside the manifests.
+const manifests = (repo_versions) => catch_errors('Manifests lookup failed', async () => {
+	const [errors, raw] = await client.post('/repos:manifests', { repo_versions }, { unwrap: false })
+	if (errors) throw errors[errors.length - 1]
+	return {
+		manifests: (raw && raw.data && raw.data.manifests) || [],
+		warnings: (raw && raw.warnings) || [],
+	}
+})
+
+module.exports = { search, dispatch_search, semantic_search, resolve_dependencies, clone, push, get_refs, get_repo, check_updates, del_repo, patch_repo, star, unstar, compare, get_blob, get_tree, match, manifests }

package/src/auth/token_store.js

@@ -97,6 +97,15 @@ const load_token = () => catch_errors('Failed to load token', async () => {
 	return data
 })
 
+// Synchronous presence check for the credentials file. Used by the API client to
+// tell "no session at all" (file absent) apart from "a real session whose token
+// could not be refreshed right now" (file present but load_token returned null —
+// the transient-refresh-failure branch preserves the file, whereas permanent /
+// no-refresh-token failures delete it). See spec 260629-02.
+const credentials_present = () => {
+	try { return fs.existsSync(credentials_path()) } catch { return false }
+}
+
 const clear_token = () => catch_errors('Failed to clear token', async () => {
 	const creds_path = credentials_path()
 	try {
@@ -115,4 +124,4 @@ const require_token = async () => {
 	return data
 }
 
-module.exports = { save_token, load_token, clear_token, require_token }
+module.exports = { save_token, load_token, clear_token, require_token, credentials_present }

package/src/commands/match.js

@@ -0,0 +1,185 @@
+const { error: { catch_errors } } = require('puffy-core')
+const fs = require('fs')
+const path = require('path')
+const repos_api = require('../api/repos')
+const { scan_folder } = require('../match/scanner')
+const { run_funnel } = require('../match/funnel')
+const { DEFAULT_CONCURRENCY } = require('../utils/concurrency')
+const { print_help, print_json, print_success, print_info, print_warn } = require('../ui/output')
+const { exit_with_error, CliError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills match <folder> [options]
+
+Scan a folder of skills and find which ones already exist in HappySkills, and
+how your local copy differs. Reports five buckets — no changes are made:
+
+  certified   byte-identical to a catalog skill
+  near        same skill, some files differ (with the differing-file list)
+  likely      a name match (content differs)
+  possible    a loose, semantic-only match
+  unmatched   nothing comparable in the catalog
+
+Arguments:
+  folder              Folder to scan (a single skill, or a folder of skills)
+
+Options:
+  --json              Output as JSON (the six-key envelope)
+  --concurrency N     Max parallel catalog lookups (default ${DEFAULT_CONCURRENCY})
+  --threshold N       Identical-file fraction (0..1) above which a name match
+                      counts as "near" (default 0.5)
+
+Examples:
+  happyskills match ./skills
+  happyskills match ~/.claude/skills --json`
+
+const to_number = (v, fallback) => {
+	const n = Number(v)
+	return Number.isFinite(n) ? n : fallback
+}
+
+const run = (args) => catch_errors('Match failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const folder = args._[0]
+	if (!folder) {
+		throw new CliError('Please specify a folder to match (e.g., happyskills match ./skills).', { code: 'MATCH_FOLDER_NOT_FOUND' })
+	}
+	const abs = path.resolve(folder)
+	if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) {
+		throw new CliError(`Folder not found: ${folder}`, { code: 'MATCH_FOLDER_NOT_FOUND', context: { folder } })
+	}
+
+	const concurrency = Math.max(1, Math.round(to_number(args.flags.concurrency, DEFAULT_CONCURRENCY)))
+	const threshold = Math.min(1, Math.max(0, to_number(args.flags.threshold, 0.5)))
+
+	// ── Scan ─────────────────────────────────────────────────────────────────
+	const [scan_err, scanned] = await scan_folder(abs)
+	if (scan_err) throw scan_err[scan_err.length - 1]
+	if (!scanned.skills.length && !scanned.errored.length) {
+		throw new CliError(`No skills found in ${folder}. A skill is a folder with a SKILL.md or skill.json.`, { code: 'MATCH_NO_SKILLS_FOUND', context: { folder } })
+	}
+
+	// ── Funnel ─────────────────────────────────────────────────────────────────
+	const deps = {
+		match: repos_api.match,
+		manifests: repos_api.manifests,
+		semantic_search: (q) => repos_api.semantic_search(q, { limit: 3 }),
+	}
+	const [funnel_err, funnel] = await run_funnel(scanned.skills, deps, { threshold, concurrency })
+	if (funnel_err) throw funnel_err[funnel_err.length - 1]
+
+	const { buckets, warnings } = funnel
+	const rel = (d) => path.relative(abs, d) || path.basename(d)
+	const errored = scanned.errored.map(en => ({
+		skill: rel(en.dir),
+		error: (en.error && en.error[en.error.length - 1] && en.error[en.error.length - 1].message) || 'Could not read skill',
+	}))
+
+	const summary = {
+		total: scanned.skills.length,
+		certified: buckets.certified.length,
+		near: buckets.near.length,
+		likely: buckets.likely.length,
+		possible: buckets.possible.length,
+		unmatched: buckets.unmatched.length,
+		errored: errored.length,
+	}
+
+	const data = {
+		certified: buckets.certified,
+		near: buckets.near,
+		likely: buckets.likely,
+		possible: buckets.possible,
+		unmatched: buckets.unmatched,
+		errored,
+		summary,
+	}
+
+	// A decision for the principal: what to do with the matched skills. This
+	// command only reports — favoriting and kit-building are separate actions.
+	const matched_total = summary.certified + summary.near + summary.likely + summary.possible
+	const next_step = matched_total > 0 ? {
+		action: 'organize_matched_skills',
+		instructions: 'Report the matched skills to the principal and let them decide what to do with each: add it to favorites, or organize matched skills into a kit. This command only reports matches — it does not change anything.',
+		route_to_skill: 'happyskills-collab',
+		context: {
+			counts: summary,
+			commands: ['npx happyskills star <owner>/<name> --json'],
+			matched: [...buckets.certified, ...buckets.near, ...buckets.likely, ...buckets.possible]
+				.map(en => (en.match && en.match.workspace && en.match.name) ? `${en.match.workspace}/${en.match.name}` : null)
+				.filter(Boolean),
+		},
+	} : null
+
+	const all_warnings = (warnings || []).concat(errored.length ? [{ code: 'SKILLS_UNREADABLE', message: `${errored.length} local skill(s) could not be read; see data.errored.` }] : [])
+
+	if (args.flags.json) {
+		print_json({ data, next_step, warnings: all_warnings })
+		return
+	}
+
+	render_text(data, all_warnings)
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+// Warm, human summary (no leaked internals — no "tree", "blob", "manifest").
+const render_text = (data, warnings) => {
+	const s = data.summary
+	print_info(`Scanned ${s.total} skill${s.total === 1 ? '' : 's'}.`)
+	print_success(`✓ ${s.certified} already in HappySkills, unchanged · ≈ ${s.near} with small differences · ~ ${s.likely + s.possible} loosely matched · ✗ ${s.unmatched} not found`)
+
+	if (data.near.length) {
+		print_info('\nSkills with small differences:')
+		for (const en of data.near) {
+			const where = en.match ? `${en.match.workspace}/${en.match.name}` : '(catalog)'
+			const diff = (en.differing_files && en.differing_files.length)
+				? `differs in: ${en.differing_files.join(', ')}`
+				: 'differs'
+			print_info(`  ${en.local.name} → ${where} — ${diff}`)
+		}
+	}
+	if (data.errored.length) {
+		print_warn(`\n${data.errored.length} skill(s) could not be read:`)
+		for (const en of data.errored) print_warn(`  ${en.skill}: ${en.error}`)
+	}
+	print_info('\nNext: choose which matched skills to add to your favorites, or group them into a kit.')
+}
+
+const schema = {
+	name:     'match',
+	audience: 'consumer',
+	purpose:  'Scan a local folder of skills and match each against the catalog (certified / near / likely / possible / unmatched). Read-only — reports matches, makes no changes.',
+	mutation: false,
+	interactive_in_text_mode: false,
+	owner_skill: 'happyskills-search',
+	input: {
+		positional: [
+			{ name: 'folder', required: true, type: 'string', pattern: '<path>' },
+		],
+		flags: [
+			{ name: 'json', type: 'boolean', default: false },
+			{ name: 'concurrency', type: 'number', default: DEFAULT_CONCURRENCY },
+			{ name: 'threshold', type: 'number', default: 0.5 },
+		],
+	},
+	output: {
+		data_shape: {
+			certified: 'array', near: 'array', likely: 'array',
+			possible: 'array', unmatched: 'array', errored: 'array',
+			summary: 'object',
+		},
+	},
+	errors: [
+		{ code: 'MATCH_FOLDER_NOT_FOUND', next_step: { kind: 'recovery', action: 'retry' } },
+		{ code: 'MATCH_NO_SKILLS_FOUND',  next_step: { kind: 'recovery', action: 'retry' } },
+	],
+	examples: [
+		'happyskills match ./skills',
+		'happyskills match ~/.claude/skills --json',
+	],
+}
+
+module.exports = { run, schema }

package/src/commands/match.test.js

@@ -0,0 +1,119 @@
+'use strict'
+// Spec 260629-03 §4.8 — the `match` command. Asserts the six-key envelope,
+// object-typed data, correct bucket placement, the organize_matched_skills
+// next_step, and that an unreadable local skill lands in errored[] while the
+// others still report. Network + scan are mocked (scan injected so we can force
+// an errored skill deterministically); the REAL funnel + diff run.
+
+const { test, before, after } = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+// ── Mocks (must be set before requiring ./match) ─────────────────────────────
+const scanner_path = require.resolve('../match/scanner')
+const repos_path = require.resolve('../api/repos')
+
+const scan_state = { skills: [], errored: [] }
+require.cache[scanner_path] = {
+	id: scanner_path, filename: scanner_path, loaded: true,
+	exports: { scan_folder: async () => [null, { skills: scan_state.skills, errored: scan_state.errored }] },
+}
+
+const api_state = { results: [], name_results: [], manifests: [], semantic: [] }
+require.cache[repos_path] = {
+	id: repos_path, filename: repos_path, loaded: true,
+	exports: {
+		match: async () => [null, { results: api_state.results, name_results: api_state.name_results }],
+		manifests: async () => [null, { manifests: api_state.manifests, warnings: [] }],
+		semantic_search: async () => [null, api_state.semantic],
+	},
+}
+
+const { run } = require('./match')
+const { schema } = require('./match')
+
+let dir
+before(() => { dir = fs.mkdtempSync(path.join(os.tmpdir(), 'match-cmd-')) })
+after(() => { try { fs.rmSync(dir, { recursive: true, force: true }) } catch {} })
+
+// Capture the envelope emit_envelope writes via console.log.
+const capture = async (fn) => {
+	const orig = console.log
+	let out = ''
+	console.log = (s) => { out += s }
+	try { await fn() } finally { console.log = orig }
+	return JSON.parse(out)
+}
+
+test('emits the six-key envelope; buckets are placed correctly; errored skill is surfaced', async () => {
+	scan_state.skills = [
+		{ name: 'alpha', dir: path.join(dir, 'alpha'), file_count: 1, skill_md_sha: 'h1', tree_sha: 't1', files: [{ path: 'SKILL.md', blob_sha: 'b1' }] },
+		{ name: 'beta', dir: path.join(dir, 'beta'), file_count: 1, skill_md_sha: 'h2', tree_sha: 't2', files: [{ path: 'SKILL.md', blob_sha: 'b2' }] },
+	]
+	scan_state.errored = [{ dir: path.join(dir, 'broken'), error: [new Error('permission denied')] }]
+	// alpha is byte-identical (tree matches) → certified; beta matches nothing → unmatched.
+	api_state.results = [{ skill_md_sha: 'h1', candidates: [{ workspace: 'anthropics', name: 'alpha', version: '1.0.0', tree_sha: 't1', is_source_of_truth: true }] }]
+	api_state.name_results = []
+	api_state.semantic = []
+
+	const env = await capture(() => run({ _: [dir], flags: { json: true } }))
+
+	assert.deepEqual(Object.keys(env).sort(), ['data', 'error', 'meta', 'next_step', 'ok', 'warnings'])
+	assert.equal(env.ok, true)
+	assert.ok(env.data && typeof env.data === 'object' && !Array.isArray(env.data), 'data is an object, never a bare array')
+
+	assert.equal(env.data.certified.length, 1)
+	assert.equal(env.data.certified[0].local.name, 'alpha')
+	assert.equal(env.data.certified[0].match.workspace, 'anthropics')
+	assert.equal(env.data.unmatched.length, 1)
+	assert.equal(env.data.unmatched[0].local.name, 'beta')
+
+	// The unreadable skill is reported, not dropped (no-silent-failures).
+	assert.equal(env.data.errored.length, 1)
+	assert.match(env.data.errored[0].error, /permission denied/)
+	assert.ok(env.warnings.some(w => w.code === 'SKILLS_UNREADABLE'))
+
+	assert.deepEqual(env.data.summary, { total: 2, certified: 1, near: 0, likely: 0, possible: 0, unmatched: 1, errored: 1 })
+})
+
+test('a near match carries its differing-file list and emits the organize_matched_skills decision', async () => {
+	scan_state.skills = [
+		{ name: 'gamma', dir: path.join(dir, 'gamma'), file_count: 2, skill_md_sha: 'hg', tree_sha: 't_local',
+			files: [{ path: 'SKILL.md', blob_sha: 'sm' }, { path: 'LICENSE', blob_sha: 'lic_local' }] },
+	]
+	scan_state.errored = []
+	api_state.results = [{ skill_md_sha: 'hg', candidates: [{ workspace: 'anthropics', name: 'gamma', version: '2.0.0', tree_sha: 't_remote', is_source_of_truth: true }] }]
+	api_state.name_results = []
+	api_state.manifests = [{ workspace: 'anthropics', name: 'gamma', version: '2.0.0', tree_sha: 't_remote',
+		files: [{ path: 'SKILL.md', blob_sha: 'sm' }, { path: 'LICENSE', blob_sha: 'lic_remote' }] }]
+
+	const env = await capture(() => run({ _: [dir], flags: { json: true } }))
+
+	assert.equal(env.data.near.length, 1)
+	assert.deepEqual(env.data.near[0].differing_files, ['LICENSE'])
+	assert.equal(env.next_step.action, 'organize_matched_skills')
+	assert.equal(env.next_step.kind, 'decision', 'kind is auto-derived from the closed enum')
+	assert.equal(env.next_step.route_to_skill, 'happyskills-collab')
+	assert.ok(env.next_step.context.matched.includes('anthropics/gamma'))
+})
+
+test('no matched skills → no decision next_step', async () => {
+	scan_state.skills = [{ name: 'lonely', dir: path.join(dir, 'lonely'), file_count: 1, skill_md_sha: 'hz', tree_sha: 'tz', files: [{ path: 'SKILL.md', blob_sha: 'z' }] }]
+	scan_state.errored = []
+	api_state.results = []; api_state.name_results = []; api_state.semantic = []
+
+	const env = await capture(() => run({ _: [dir], flags: { json: true } }))
+	assert.equal(env.data.unmatched.length, 1)
+	assert.deepEqual(env.next_step, {}, 'no matches ⇒ no decision to make')
+})
+
+test('schema: read-only, owned by happyskills-search, with the documented data shape', () => {
+	assert.equal(schema.name, 'match')
+	assert.equal(schema.mutation, false)
+	assert.equal(schema.owner_skill, 'happyskills-search')
+	for (const k of ['certified', 'near', 'likely', 'possible', 'unmatched', 'errored', 'summary']) {
+		assert.ok(k in schema.output.data_shape, `schema documents data.${k}`)
+	}
+})

package/src/constants/error_codes.js

@@ -117,6 +117,10 @@ const CLONE_REMOTE_FAILED       = 'CLONE_REMOTE_FAILED'
 const READ_LOCAL_FAILED         = 'READ_LOCAL_FAILED'
 const SWAP_FAILED               = 'SWAP_FAILED'
 
+// match command (client-side, spec 260629-03) ──────────────────────────────
+const MATCH_FOLDER_NOT_FOUND    = 'MATCH_FOLDER_NOT_FOUND'
+const MATCH_NO_SKILLS_FOUND     = 'MATCH_NO_SKILLS_FOUND'
+
 // Internal ─────────────────────────────────────────────────────────────────
 const INTERNAL_ERROR        = 'INTERNAL_ERROR'
 const PERSIST_FAILED        = 'PERSIST_FAILED'
@@ -183,6 +187,7 @@ const ERROR_CODES = Object.freeze({
 	PUBLISH_FAILED, RANKING_SCHEMA_MISMATCH,
 	COMPARE_FAILED, CLONE_BASE_FAILED, CLONE_REMOTE_FAILED, READ_LOCAL_FAILED,
 	SWAP_FAILED,
+	MATCH_FOLDER_NOT_FOUND, MATCH_NO_SKILLS_FOUND,
 	INTERNAL_ERROR, PERSIST_FAILED, VERIFICATION_FAILED,
 	NO_COGNITO_USER, COGNITO_SYNC_FAILED, COGNITO_UNLINK_FAILED,
 	ALREADY_HAS_PASSWORD, EMAIL_ALIAS_CONFLICT, ALREADY_APPROVED,

package/src/constants/next_step_actions.js

@@ -48,6 +48,7 @@ const SPECIFY_BUMP_TYPE              = 'specify_bump_type'
 const RESOLVE_BUMP_DISAGREEMENT      = 'resolve_bump_disagreement'
 const PICK_VERSION                   = 'pick_version'
 const RESOLVE_UNKNOWN_DRIFT          = 'resolve_unknown_drift'
+const ORGANIZE_MATCHED_SKILLS        = 'organize_matched_skills'
 
 // kind: confirmation
 const CONFIRM_DISCARD_OR_SNAPSHOT_FIRST = 'confirm_discard_or_snapshot_first'
@@ -90,6 +91,7 @@ const ACTION_KIND = Object.freeze({
 	[RESOLVE_BUMP_DISAGREEMENT]:          DECISION,
 	[PICK_VERSION]:                       DECISION,
 	[RESOLVE_UNKNOWN_DRIFT]:              DECISION,
+	[ORGANIZE_MATCHED_SKILLS]:            DECISION,
 
 	[CONFIRM_DISCARD_OR_SNAPSHOT_FIRST]:  CONFIRMATION,
 	[CONFIRM_CASCADE]:                    CONFIRMATION,
@@ -112,7 +114,7 @@ const NEXT_STEP_ACTIONS = Object.freeze({
 	RESOLVE_REGRESSION, RESOLVE_MISSING_SKILL_JSON, RESOLVE_MISSING_DIR,
 	RESOLVE_CONFLICTS, RESOLVE_PATCH_REJECTIONS, SPECIFY_WORKSPACE,
 	SPECIFY_BUMP_TYPE, RESOLVE_BUMP_DISAGREEMENT, PICK_VERSION,
-	RESOLVE_UNKNOWN_DRIFT,
+	RESOLVE_UNKNOWN_DRIFT, ORGANIZE_MATCHED_SKILLS,
 	CONFIRM_DISCARD_OR_SNAPSHOT_FIRST, CONFIRM_CASCADE, CONFIRM_DESTRUCTIVE,
 	PASS_YES_FLAG,
 	RANK_DIGESTS_INLINE, PRESENT_TO_USER, ATTACH_SCREENSHOT,

package/src/constants/next_step_by_error_code.js

@@ -287,6 +287,19 @@ const NEXT_STEP_BY_ERROR_CODE = Object.freeze({
 			...(ctx.commands ? { commands: ctx.commands } : {}),
 		}
 	),
+
+	// Spec 260629-03 §4.8 — `happyskills match <folder>` input errors. Recovery:
+	// re-run pointed at a real folder that actually contains skills.
+	MATCH_FOLDER_NOT_FOUND: () => recovery(
+		RETRY,
+		'The folder to match was not found. Re-run with a path to an existing directory of skills.',
+		{ commands: ['npx happyskills match <folder> --json'] }
+	),
+	MATCH_NO_SKILLS_FOUND: () => recovery(
+		RETRY,
+		'No skills were found in that folder. Point match at a directory that contains skills (each skill is a folder with a SKILL.md or skill.json).',
+		{ commands: ['npx happyskills match <folder> --json'] }
+	),
 })
 
 const next_step_for_error = (code, message, context) => {