happyskills 1.13.1 → 1.15.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.15.0] - 2026-06-30
+
+### Changed
+
+- Make `happyskills match` **version-precise**: it now matches each local skill against **all** published versions of a skill, not just the latest. A local copy that is byte-identical to an *older* release is reported as `certified` at that exact version (the result carries `match.version`, `match.latest_version`, and `match.is_latest`) — instead of being diffed against head and misreported as `likely`/drift just because you're a few versions behind. The text output gains an "identical to an older published version (you are behind)" line listing each such skill as `name → owner/skill @ <version> (latest <latest>)`. Mechanically, the match funnel now also sends the whole-skill `tree_sha`s in the same batched `POST /repos:match` call and certifies on a cross-version tree match (with a fallback to the previous head-only behavior for older API servers). Requires API ≥ 5.18.0 (the `tree_shas` axis on `POST /repos:match`). (Spec 260629-03 §4.8.)
+
+## [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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.13.1",
+	"version": "1.15.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/repos.js

@@ -213,4 +213,29 @@ 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 + tree shas. Returns
+// { results: [{ skill_md_sha, candidates }], name_results: [{ name, candidates }],
+//   tree_results: [{ tree_sha, candidates }] } — multi-key, so the client's
+// single-key unwrap leaves it intact. `tree_results` (spec §4.8) matches the
+// whole-skill content address across ALL versions, so a local copy identical to
+// an older release is pinned to that exact version instead of drifting vs head.
+const match = (hashes, names, tree_shas) => catch_errors('Catalog match lookup failed', async () => {
+	const [errors, data] = await client.post('/repos:match', { hashes, names: names || [], tree_shas: tree_shas || [] })
+	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/commands/match.js

@@ -0,0 +1,196 @@
+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`)
+
+	// A certified match to an OLDER version is still an exact match — surface the
+	// version gap so the principal knows it is the real skill, just behind.
+	const behind = data.certified.filter(en => en.match && en.match.latest_version && en.match.is_latest === false)
+	if (behind.length) {
+		print_info('\nIdentical to an older published version (you are behind):')
+		for (const en of behind) {
+			const where = en.match ? `${en.match.workspace}/${en.match.name}` : '(catalog)'
+			print_info(`  ${en.local.name} → ${where} @ ${en.match.version} (latest ${en.match.latest_version})`)
+		}
+	}
+
+	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) => {

package/src/constants.js

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

package/src/integration/api_envelope.test.js

@@ -90,7 +90,13 @@ const run_cli = (args, env_override = {}) => new Promise((resolve) => {
 	const has_mode_flag = args.includes('--json') || args.includes('--text')
 	const final_args = has_mode_flag ? args : [...args, '--text']
 	const child = spawn(NODE, [CLI, ...final_args], {
-		env: { ...process.env, NO_COLOR: '1', CI: '', ...env_override },
+		// Isolate the CLI config dir so the spawned binary never reads the
+		// developer's real ~/.config/happyskills credentials. A stored (expired)
+		// token would otherwise make an authed command (e.g. a search POST)
+		// attempt a token refresh against the stub's missing /auth/refresh route
+		// and fail with NETWORK_ERROR — a machine-state-dependent flake. A test
+		// that needs a specific config dir overrides this via env_override (last).
+		env: { ...process.env, NO_COLOR: '1', CI: '', XDG_CONFIG_HOME: make_tmp(), ...env_override },
 	})
 	let stdout = ''
 	let stderr = ''

package/src/match/diff.js

@@ -0,0 +1,41 @@
+'use strict'
+// Manifest diff (spec 260629-03 §4.7). Joins a local manifest against a catalog
+// manifest on `path` with ZERO blob downloads — both sides are just
+// [{ path, blob_sha }] lists. The differing-file list is the load-bearing
+// artifact (not the single similarity %): it's what tells the principal exactly
+// what changed (e.g. "only LICENSE differs").
+
+// local_files / catalog_files: [{ path, blob_sha }]
+const diff_manifests = (local_files, catalog_files) => {
+	const local = new Map((local_files || []).map(f => [f.path, f.blob_sha]))
+	const catalog = new Map((catalog_files || []).map(f => [f.path, f.blob_sha]))
+	const all = new Set([...local.keys(), ...catalog.keys()])
+
+	const identical = []
+	const modified = []
+	const added = []   // present locally, absent in the catalog skill
+	const removed = [] // present in the catalog skill, absent locally
+
+	for (const p of all) {
+		const l = local.get(p)
+		const c = catalog.get(p)
+		if (l !== undefined && c !== undefined) (l === c ? identical : modified).push(p)
+		else if (l !== undefined) added.push(p)
+		else removed.push(p)
+	}
+
+	const total = all.size
+	const similarity = total === 0 ? 1 : identical.length / total
+	const differing = [...modified, ...added, ...removed].sort()
+
+	return {
+		similarity,
+		identical: identical.sort(),
+		modified: modified.sort(),
+		added: added.sort(),
+		removed: removed.sort(),
+		differing,
+	}
+}
+
+module.exports = { diff_manifests }

package/src/match/funnel.js

@@ -0,0 +1,191 @@
+'use strict'
+// The match funnel + tier classification (spec 260629-03 §4.7).
+//
+// Stages, cheapest signal first, NO blob downloads to classify:
+//   1. hash + name — ONE batched POST /repos:match for ALL local skills.
+//   2. tree SHA    — local.tree_sha === a candidate's tree_sha ⇒ certified
+//                    (byte-identical, zero further work).
+//   3. manifest    — for non-certified hash/name candidates, fetch the narrowed
+//                    source-of-truth manifest (bounded fan-out, no blob content)
+//                    and diff per-file. A hash match means SKILL.md is identical
+//                    by construction → favor `near` and just list the differing
+//                    files. A name-only match is `near` above the similarity
+//                    threshold, else `likely`.
+//   4. semantic    — skills with no hash/name match fall back to the deployed
+//                    semantic search (bounded), labeled `possible` (clearly low
+//                    confidence), else `unmatched`.
+//
+// Closed tier set: certified · near · likely · possible · unmatched.
+
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { bounded, DEFAULT_CONCURRENCY } = require('../utils/concurrency')
+const { diff_manifests } = require('./diff')
+
+// Identical-file fraction above which a NAME-only match is promoted to `near`.
+const DEFAULT_THRESHOLD = 0.5
+// Mirror of the server cap (MATCH_MAX_MANIFESTS) so we chunk manifest requests.
+const MANIFEST_CHUNK = 50
+
+const key_of = (c) => `${String(c.workspace).toLowerCase()}/${c.name}@${c.version}`
+
+const local_view = (skill) => ({
+	name: skill.name,
+	dir: skill.dir,
+	file_count: skill.file_count,
+	skill_md_sha: skill.skill_md_sha,
+	tree_sha: skill.tree_sha,
+})
+
+const match_view = (c) => ({
+	workspace: c.workspace,
+	name: c.name,
+	version: c.version,
+	tree_sha: c.tree_sha,
+	is_source_of_truth: !!c.is_source_of_truth,
+	// Cross-version probe carries the repo head so a certified-but-older match
+	// can be surfaced as "certified @ 0.3.0 (latest 0.3.2)". Null when the
+	// candidate came from the legacy head-only path (older server).
+	latest_version: c.latest_version || null,
+	is_latest: c.latest_version ? c.version === c.latest_version : null,
+})
+
+// deps: { match(hashes,names), manifests(repo_versions), semantic_search?(query) }
+// opts: { threshold, concurrency }
+const run_funnel = (skills, deps, opts = {}) =>
+	catch_errors('Match funnel failed', async () => {
+		const threshold = typeof opts.threshold === 'number' ? opts.threshold : DEFAULT_THRESHOLD
+		const concurrency = opts.concurrency || DEFAULT_CONCURRENCY
+		const buckets = { certified: [], near: [], likely: [], possible: [], unmatched: [] }
+		const warnings = []
+
+		if (!skills.length) return { buckets, warnings }
+
+		// ── Stage 1: one batched match for the whole folder ──────────────────
+		// Hashes, names AND whole-skill tree shas ride the same call. The tree
+		// probe (spec §4.8) is what lets an OLDER local copy match its exact
+		// published version instead of drifting against head.
+		const hashes = [...new Set(skills.map(s => s.skill_md_sha).filter(Boolean))]
+		const names = [...new Set(skills.map(s => s.name).filter(Boolean))]
+		const tree_shas = [...new Set(skills.map(s => s.tree_sha).filter(Boolean))]
+		const [m_err, match_data] = await deps.match(hashes, names, tree_shas)
+		if (m_err) throw e('Stage 1 /repos:match failed', m_err)
+
+		const by_hash = new Map((match_data.results || []).map(r => [r.skill_md_sha, r.candidates || []]))
+		const by_name = new Map((match_data.name_results || []).map(r => [String(r.name).toLowerCase(), r.candidates || []]))
+		const by_tree = new Map((match_data.tree_results || []).map(r => [r.tree_sha, r.candidates || []]))
+
+		// ── Stage 2: classify; collect the narrowed manifest set ─────────────
+		const pending = []          // needs a manifest diff
+		const none = []             // no hash/name match → semantic stage
+		const manifest_needs = new Map()
+
+		for (const skill of skills) {
+			const tree_cands = (skill.tree_sha && by_tree.get(skill.tree_sha)) || []
+			const hash_cands = (skill.skill_md_sha && by_hash.get(skill.skill_md_sha)) || []
+			const name_cands = by_name.get(String(skill.name || '').toLowerCase()) || []
+
+			// Certified = byte-identical to SOME published version. The cross-version
+			// tree probe is authoritative and pins the EXACT version (even an older
+			// one — candidates are source-of-truth + newest-matching first). Fall
+			// back to head tree-SHA equality from a hash/name candidate so an older
+			// server with no tree_results still certifies a head-identical skill.
+			const certified = tree_cands[0] || [...hash_cands, ...name_cands].find(c => c.tree_sha === skill.tree_sha)
+			if (certified) {
+				buckets.certified.push({ local: local_view(skill), match: match_view(certified) })
+				continue
+			}
+			if (hash_cands.length) {
+				const sot = hash_cands[0] // API returns source-of-truth first
+				manifest_needs.set(key_of(sot), { workspace: sot.workspace, name: sot.name, version: sot.version })
+				pending.push({ skill, cand: sot, via: 'hash' })
+				continue
+			}
+			if (name_cands.length) {
+				const sot = name_cands[0]
+				manifest_needs.set(key_of(sot), { workspace: sot.workspace, name: sot.name, version: sot.version })
+				pending.push({ skill, cand: sot, via: 'name' })
+				continue
+			}
+			none.push(skill)
+		}
+
+		// ── Stage 3: bounded manifest fetch (chunked to the server cap) ──────
+		const manifest_by_key = new Map()
+		const needs = [...manifest_needs.values()]
+		if (needs.length) {
+			const chunks = []
+			for (let i = 0; i < needs.length; i += MANIFEST_CHUNK) chunks.push(needs.slice(i, i + MANIFEST_CHUNK))
+			const results = await bounded(chunks.map(chunk => () => deps.manifests(chunk)), concurrency)
+			for (const r of results) {
+				if (r && r.error) { warnings.push({ code: 'MANIFEST_FETCH_FAILED', message: String((r.error && r.error.message) || r.error) }); continue }
+				const [err, data] = r || [null, null]
+				if (err || !data) { warnings.push({ code: 'MANIFEST_FETCH_FAILED', message: 'A manifest batch could not be fetched.' }); continue }
+				for (const m of (data.manifests || [])) manifest_by_key.set(key_of(m), m)
+				for (const w of (data.warnings || [])) warnings.push(w)
+			}
+		}
+
+		// ── finalize the hash/name candidates with their diffs ───────────────
+		for (const { skill, cand, via } of pending) {
+			const m = manifest_by_key.get(key_of(cand))
+			const diff = m ? diff_manifests(skill.files, m.files) : null
+			const entry = {
+				local: local_view(skill),
+				match: match_view(cand),
+				differing_files: diff ? diff.differing : null,
+				similarity: diff ? diff.similarity : null,
+			}
+			if (via === 'hash') {
+				// SKILL.md identical by construction → the difference is ancillary.
+				buckets.near.push(entry)
+			} else if (diff && diff.similarity >= threshold) {
+				buckets.near.push(entry)
+			} else {
+				buckets.likely.push(entry)
+			}
+		}
+
+		// ── Stage 4: semantic fallback for the rest (bounded) ────────────────
+		// deps.semantic_search returns the api-client tuple [err, hits] (hits is
+		// an array, or { results: [...] }); a failure degrades the skill to
+		// `unmatched` with a surfaced warning — never a silent drop.
+		if (none.length && typeof deps.semantic_search === 'function') {
+			// The thunk ALWAYS resolves (carrying its skill), so a search that
+			// rejects can't strand the skill — it still lands in `unmatched` with a
+			// surfaced warning, never silently dropped from `data`.
+			const results = await bounded(
+				none.map(skill => () =>
+					deps.semantic_search(skill.name).then(res => ({ skill, res })).catch(error => ({ skill, error }))),
+				concurrency
+			)
+			for (const r of results) {
+				const { skill, res, error } = r || {}
+				if (!skill) continue // defensive: bounded never yields a bare {error} here
+				const tuple_err = Array.isArray(res) ? res[0] : null
+				if (error || tuple_err) {
+					warnings.push({ code: 'SEMANTIC_SEARCH_FAILED', message: String((error && error.message) || 'A semantic lookup failed.') })
+					buckets.unmatched.push({ local: local_view(skill) })
+					continue
+				}
+				const data = Array.isArray(res) ? res[1] : res
+				const hits = Array.isArray(data) ? data : (data && Array.isArray(data.results) ? data.results : [])
+				if (hits[0]) buckets.possible.push({ local: local_view(skill), match: semantic_match_view(hits[0]) })
+				else buckets.unmatched.push({ local: local_view(skill) })
+			}
+		} else {
+			for (const skill of none) buckets.unmatched.push({ local: local_view(skill) })
+		}
+
+		return { buckets, warnings }
+	})
+
+// A semantic hit shape varies by search response; normalize the fields the
+// match report cares about, leaving missing ones null.
+const semantic_match_view = (hit) => ({
+	workspace: hit.workspace_slug || hit.workspace || null,
+	name: hit.name || null,
+	version: hit.version || null,
+	score: typeof hit.score === 'number' ? hit.score : null,
+})
+
+module.exports = { run_funnel, DEFAULT_THRESHOLD, MANIFEST_CHUNK }

package/src/match/funnel.test.js

@@ -0,0 +1,203 @@
+'use strict'
+// Spec 260629-03 §4.7 — the match funnel + tier classification. Network is
+// mocked (deps injected). The four "done when" guarantees:
+//   - identical → certified with ZERO blob fetches (the funnel never fetches
+//     blob content at all; classification is hash/tree/manifest only)
+//   - LICENSE-only diff → near, listing LICENSE as the sole differing file
+//   - SKILL.md differs (name-only, low similarity) → demoted to likely
+//   - semantic-only → possible
+
+const { test } = require('node:test')
+const assert = require('node:assert/strict')
+const { run_funnel } = require('./funnel')
+const { diff_manifests } = require('./diff')
+
+const skill = (over) => ({
+	name: 'webapp-testing', dir: '/local/webapp-testing', file_count: 2,
+	skill_md_sha: 'h_skillmd', tree_sha: 't_local',
+	files: [{ path: 'SKILL.md', blob_sha: 'b_skill' }, { path: 'LICENSE', blob_sha: 'b_lic_local' }],
+	...over,
+})
+const cand = (over) => ({ workspace: 'anthropics', name: 'webapp-testing', version: '1.0.0', tree_sha: 't_remote', skill_md_sha: 'h_skillmd', is_source_of_truth: true, ...over })
+
+// A deps double that records calls.
+const make_deps = ({ results = [], name_results = [], tree_results = [], manifests = [], semantic = null } = {}) => {
+	const calls = { match: 0, manifests: 0, semantic: 0, blob: 0 }
+	return {
+		calls,
+		match: async () => { calls.match++; return [null, { results, name_results, tree_results }] },
+		manifests: async () => { calls.manifests++; return [null, { manifests, warnings: [] }] },
+		...(semantic ? { semantic_search: async (q) => { calls.semantic++; return semantic(q) } } : {}),
+	}
+}
+
+test('identical content → certified, with zero manifest/blob fetches', async () => {
+	const deps = make_deps({ results: [{ skill_md_sha: 'h_skillmd', candidates: [cand({ tree_sha: 't_local' })] }] })
+	const [err, out] = await run_funnel([skill()], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.certified.length, 1)
+	assert.equal(out.buckets.certified[0].match.workspace, 'anthropics')
+	assert.equal(deps.calls.manifests, 0, 'certified needs no manifest fetch')
+	assert.equal(deps.calls.blob, 0, 'the funnel never fetches blob content')
+})
+
+test('hash match, only LICENSE differs → near, listing LICENSE as the sole differing file', async () => {
+	const deps = make_deps({
+		results: [{ skill_md_sha: 'h_skillmd', candidates: [cand({ tree_sha: 't_remote' })] }],
+		manifests: [{ workspace: 'anthropics', name: 'webapp-testing', version: '1.0.0', tree_sha: 't_remote',
+			files: [{ path: 'SKILL.md', blob_sha: 'b_skill' }, { path: 'LICENSE', blob_sha: 'b_lic_remote' }] }],
+	})
+	const [err, out] = await run_funnel([skill()], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.certified.length, 0)
+	assert.equal(out.buckets.near.length, 1)
+	assert.deepEqual(out.buckets.near[0].differing_files, ['LICENSE'])
+	assert.equal(deps.calls.manifests, 1)
+})
+
+test('name-only match with low similarity (SKILL.md differs) → likely', async () => {
+	// No hash candidate; a name candidate whose manifest shares almost nothing.
+	const local = skill({ skill_md_sha: 'h_local_only', tree_sha: 't_local', files: [{ path: 'SKILL.md', blob_sha: 'x1' }, { path: 'a.md', blob_sha: 'x2' }] })
+	const deps = make_deps({
+		name_results: [{ name: 'webapp-testing', candidates: [cand({ skill_md_sha: 'h_other', tree_sha: 't_remote' })] }],
+		manifests: [{ workspace: 'anthropics', name: 'webapp-testing', version: '1.0.0', tree_sha: 't_remote',
+			files: [{ path: 'SKILL.md', blob_sha: 'y1' }, { path: 'b.md', blob_sha: 'y2' }, { path: 'c.md', blob_sha: 'y3' }] }],
+	})
+	const [err, out] = await run_funnel([local], deps, { threshold: 0.5 })
+	assert.equal(err, null)
+	assert.equal(out.buckets.near.length, 0)
+	assert.equal(out.buckets.likely.length, 1)
+	assert.equal(out.buckets.likely[0].match.name, 'webapp-testing')
+})
+
+test('name-only match above the threshold → near', async () => {
+	const local = skill({ skill_md_sha: 'h_local_only', files: [{ path: 'SKILL.md', blob_sha: 'x1' }, { path: 'a.md', blob_sha: 'shared' }] })
+	const deps = make_deps({
+		name_results: [{ name: 'webapp-testing', candidates: [cand({ skill_md_sha: 'h_other', tree_sha: 't_remote' })] }],
+		manifests: [{ workspace: 'anthropics', name: 'webapp-testing', version: '1.0.0', tree_sha: 't_remote',
+			files: [{ path: 'SKILL.md', blob_sha: 'x1' }, { path: 'a.md', blob_sha: 'shared' }] }],
+	})
+	const [err, out] = await run_funnel([local], deps, { threshold: 0.5 })
+	assert.equal(err, null)
+	assert.equal(out.buckets.near.length, 1)
+})
+
+test('no hash/name match, semantic hit → possible', async () => {
+	const local = skill({ name: 'novel-skill', skill_md_sha: 'h_novel' })
+	const deps = make_deps({ semantic: async () => [null, [{ workspace_slug: 'someone', name: 'similar-thing', version: '2.1.0', score: 0.7 }]] })
+	const [err, out] = await run_funnel([local], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.possible.length, 1)
+	assert.equal(out.buckets.possible[0].match.workspace, 'someone')
+	assert.equal(deps.calls.semantic, 1)
+})
+
+test('no match at all (no semantic dep) → unmatched', async () => {
+	const local = skill({ name: 'novel-skill', skill_md_sha: 'h_novel' })
+	const deps = make_deps({}) // no semantic_search
+	const [err, out] = await run_funnel([local], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.unmatched.length, 1)
+	assert.equal(out.buckets.possible.length, 0)
+})
+
+test('Stage 1 is ONE batched call regardless of skill count (no N+1)', async () => {
+	const deps = make_deps({ results: [{ skill_md_sha: 'h_skillmd', candidates: [cand({ tree_sha: 't_local' })] }] })
+	await run_funnel([skill(), skill({ dir: '/b' }), skill({ dir: '/c' })], deps)
+	assert.equal(deps.calls.match, 1, 'the whole folder resolves in one /repos:match call')
+})
+
+// ── Tier 1: cross-version tree probe (spec 260629-03 §4.8) ───────────────────
+
+test('local tree byte-identical to an OLDER published version → certified at that exact version', async () => {
+	// HEAD is 0.3.2 (a DIFFERENT tree — this is the drift the bug surfaced); the
+	// local copy is byte-identical to 0.3.0. The cross-version tree probe must
+	// pin it to 0.3.0 and certify it — NOT diff it against head and call it likely.
+	const local = skill({ name: 'tiny-gemini-image', skill_md_sha: 'h_old', tree_sha: 't_v030' })
+	const deps = make_deps({
+		// hash/name discovery still points at HEAD (head's tree differs from local)
+		name_results: [{ name: 'tiny-gemini-image', candidates: [cand({ name: 'tiny-gemini-image', version: '0.3.2', tree_sha: 't_v032', skill_md_sha: 'h_head' })] }],
+		tree_results: [{ tree_sha: 't_v030', candidates: [
+			{ workspace: 'nicolasdao', name: 'tiny-gemini-image', version: '0.3.0', tree_sha: 't_v030', skill_md_sha: 'h_old', is_source_of_truth: true, latest_version: '0.3.2' },
+		] }],
+	})
+	const [err, out] = await run_funnel([local], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.certified.length, 1, 'an older byte-identical version is certified, not likely')
+	assert.equal(out.buckets.likely.length, 0)
+	assert.equal(out.buckets.near.length, 0)
+	assert.equal(out.buckets.certified[0].match.version, '0.3.0', 'pinned to the EXACT matching version, not head')
+	assert.equal(out.buckets.certified[0].match.latest_version, '0.3.2', 'carries the latest version so the caller can show "behind by"')
+	assert.equal(out.buckets.certified[0].match.is_latest, false)
+	assert.equal(deps.calls.manifests, 0, 'an exact tree match needs no manifest diff')
+})
+
+test('the local tree probe is sent in the SAME batched match call (no extra round-trip)', async () => {
+	const deps = make_deps({ tree_results: [{ tree_sha: 't_local', candidates: [
+		{ workspace: 'anthropics', name: 'webapp-testing', version: '1.0.0', tree_sha: 't_local', is_source_of_truth: true, latest_version: '1.0.0' },
+	] }] })
+	const [err, out] = await run_funnel([skill(), skill({ dir: '/b' })], deps)
+	assert.equal(err, null)
+	assert.equal(deps.calls.match, 1, 'hashes + names + tree_shas all ride one /repos:match call')
+	assert.equal(out.buckets.certified.length, 2)
+	assert.equal(out.buckets.certified[0].match.is_latest, true, 'matching head is is_latest:true')
+})
+
+test('backward-compat: a server with no tree_results still certifies a head-identical skill', async () => {
+	// Older server returns no tree_results; the funnel falls back to head tree
+	// equality from the hash/name candidate so existing behavior is preserved.
+	const deps = make_deps({ results: [{ skill_md_sha: 'h_skillmd', candidates: [cand({ tree_sha: 't_local' })] }] })
+	const [err, out] = await run_funnel([skill()], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.certified.length, 1)
+	assert.equal(out.buckets.certified[0].match.version, '1.0.0')
+})
+
+test('a failed manifest batch becomes a warning, not a thrown error', async () => {
+	const deps = {
+		calls: {},
+		match: async () => [null, { results: [{ skill_md_sha: 'h_skillmd', candidates: [cand({ tree_sha: 't_remote' })] }], name_results: [] }],
+		manifests: async () => { throw new Error('network boom') },
+	}
+	const [err, out] = await run_funnel([skill()], deps)
+	assert.equal(err, null, 'one bad batch does not abort the run')
+	assert.ok(out.warnings.some(w => w.code === 'MANIFEST_FETCH_FAILED'))
+	// hash match still lands in near, just without a differing-file list.
+	assert.equal(out.buckets.near.length, 1)
+	assert.equal(out.buckets.near[0].differing_files, null)
+})
+
+test('certified is tree-SHA equality even via a NAME match (skill has no SKILL.md → null hash)', async () => {
+	// A skill.json-only local skill (no SKILL.md) → skill_md_sha null, so it can
+	// only be found by name — but if its tree is byte-identical it is still certified.
+	const local = skill({ name: 'no-skillmd', skill_md_sha: null, tree_sha: 't_local', files: [{ path: 'skill.json', blob_sha: 'sj' }] })
+	const deps = make_deps({ name_results: [{ name: 'no-skillmd', candidates: [cand({ name: 'no-skillmd', tree_sha: 't_local' })] }] })
+	const [err, out] = await run_funnel([local], deps)
+	assert.equal(err, null)
+	assert.equal(out.buckets.certified.length, 1, 'byte-identical (tree equal) is certified even when matched by name')
+	assert.equal(out.buckets.near.length, 0)
+	assert.equal(out.buckets.likely.length, 0)
+})
+
+test('a semantic search that REJECTS still lands the skill in unmatched (never silently dropped)', async () => {
+	const local = skill({ name: 'novel-skill', skill_md_sha: 'h_novel' })
+	const deps = make_deps({ semantic: async () => { throw new Error('search exploded') } })
+	const [err, out] = await run_funnel([local], deps)
+	assert.equal(err, null, 'a rejecting semantic lookup does not abort the run')
+	assert.equal(out.buckets.unmatched.length, 1, 'the skill is reported as unmatched, not dropped from data')
+	assert.equal(out.buckets.unmatched[0].local.name, 'novel-skill')
+	assert.ok(out.warnings.some(w => w.code === 'SEMANTIC_SEARCH_FAILED'))
+})
+
+test('diff_manifests classifies identical / modified / added / removed', () => {
+	const d = diff_manifests(
+		[{ path: 'SKILL.md', blob_sha: 'a' }, { path: 'keep', blob_sha: 'k' }, { path: 'local-only', blob_sha: 'z' }],
+		[{ path: 'SKILL.md', blob_sha: 'b' }, { path: 'keep', blob_sha: 'k' }, { path: 'remote-only', blob_sha: 'r' }],
+	)
+	assert.deepEqual(d.modified, ['SKILL.md'])
+	assert.deepEqual(d.identical, ['keep'])
+	assert.deepEqual(d.added, ['local-only'])
+	assert.deepEqual(d.removed, ['remote-only'])
+	assert.deepEqual(d.differing, ['SKILL.md', 'local-only', 'remote-only'].sort())
+	assert.equal(d.similarity, 1 / 4)
+})

package/src/match/scanner.js

@@ -0,0 +1,129 @@
+'use strict'
+// Local skill scanner + fileset normalization (spec 260629-03 §4.6).
+//
+// Walks a folder, discovers each skill (a dir containing SKILL.md and/or
+// skill.json), and fingerprints it the SAME way the publish path does — so the
+// locally-computed tree_sha lines up byte-for-byte with the catalog's stored
+// tree_sha and a byte-identical skill matches as `certified`.
+//
+// Normalization is the #1 correctness risk (spec §6 #2): a globally-installed
+// skill carries install cruft (.DS_Store, .git, agent lock files) and is often
+// a symlink (multi-agent installs share one copy). If the local fileset differs
+// from what the push path includes, the tree_sha never matches and identical
+// skills look "different". So we reuse `collect_files` / the EXCLUDE rules the
+// push path uses, and we resolve symlinked skill roots to their real content.
+
+const fs = require('fs')
+const path = require('path')
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { collect_files } = require('../utils/file_collector')
+const { hash_tree } = require('../utils/git_hash')
+
+const has_manifest = (dir) =>
+	fs.existsSync(path.join(dir, 'SKILL.md')) || fs.existsSync(path.join(dir, 'skill.json'))
+
+// Directories we never descend into while hunting for skill roots — the same
+// install/VCS cruft the push fileset excludes, plus any dotdir.
+const SKIP_DIRS = new Set(['node_modules', '.git'])
+
+// Discover skill roots under `root`. A skill root is the FIRST directory on a
+// path that has a SKILL.md/skill.json — we do NOT descend past it, so a skill's
+// own references/ subdir is never mistaken for a separate skill. `fs.statSync`
+// follows symlinks, so a symlinked skill dir (the multi-agent install case)
+// resolves to its real target; we dedupe by realpath so a symlink + its target
+// don't both count.
+const find_skill_roots = (root) => {
+	const roots = []
+	const seen_real = new Set()
+
+	const add = (dir) => {
+		let real
+		try { real = fs.realpathSync(dir) } catch { real = dir }
+		if (seen_real.has(real)) return
+		seen_real.add(real)
+		roots.push(dir)
+	}
+
+	const walk = (dir) => {
+		if (has_manifest(dir)) { add(dir); return }
+		let entries
+		try { entries = fs.readdirSync(dir, { withFileTypes: true }) } catch { return }
+		for (const ent of entries) {
+			if (SKIP_DIRS.has(ent.name) || ent.name.startsWith('.')) continue
+			const full = path.join(dir, ent.name)
+			let st
+			try { st = fs.statSync(full) } catch { continue } // follows symlinks; skip broken
+			if (st.isDirectory()) walk(full)
+		}
+	}
+
+	walk(root)
+	return roots
+}
+
+// Read the skill's declared name from skill.json (the field the catalog matches
+// on); fall back to the directory basename when absent or unreadable.
+const read_skill_name = (skill_dir) => {
+	const fallback = path.basename(skill_dir)
+	try {
+		const raw = fs.readFileSync(path.join(skill_dir, 'skill.json'), 'utf8')
+		const json = JSON.parse(raw)
+		return (json && typeof json.name === 'string' && json.name.trim()) ? json.name.trim() : fallback
+	} catch {
+		return fallback
+	}
+}
+
+// Fingerprint one skill root into the shape the funnel consumes.
+const fingerprint_skill = (skill_dir) =>
+	catch_errors(`Failed to fingerprint skill at ${skill_dir}`, async () => {
+		const [err, files] = await collect_files(skill_dir)
+		if (err) throw e(`Failed to read skill files at ${skill_dir}`, err)
+
+		// Normalize separators to '/' so the fingerprint is identical to the
+		// stored (POSIX-path) tree regardless of the host OS.
+		const norm = files.map(f => ({ path: f.path.split(path.sep).join('/'), blob_sha: f.sha }))
+
+		// Manifest: [{ path, blob_sha }], sorted for stable comparison/diff.
+		const manifest = norm
+			.map(f => ({ path: f.path, blob_sha: f.blob_sha }))
+			.sort((a, b) => a.path.localeCompare(b.path))
+
+		// skill_md_sha = the blob hash of the ROOT SKILL.md (case-insensitive
+		// match, exactly like the server's compute_skill_md_sha). Null when the
+		// skill has no SKILL.md (it can then only name/semantic-match).
+		const skill_md_entry = manifest.find(f => f.path.toLowerCase() === 'skill.md')
+		const skill_md_sha = skill_md_entry ? skill_md_entry.blob_sha : null
+
+		// tree_sha = the whole-skill fingerprint, computed with the EXACT server
+		// algorithm (git_hash.hash_tree mirrors api/app/utils/git_objects).
+		const tree_sha = hash_tree(norm.map(f => ({ path: f.path, sha: f.blob_sha })))
+
+		return {
+			dir: skill_dir,
+			name: read_skill_name(skill_dir),
+			skill_md_sha,
+			tree_sha,
+			files: manifest,
+			file_count: manifest.length,
+		}
+	})
+
+// Scan a folder → fingerprints for every skill found. Returns
+// { skills: [...], errored: [{ dir, error }] } — a single unreadable skill never
+// aborts the scan (CLAUDE.md no-silent-failures: failures are surfaced, not
+// dropped).
+const scan_folder = (folder) =>
+	catch_errors(`Failed to scan folder ${folder}`, async () => {
+		const roots = find_skill_roots(folder)
+		const skills = []
+		const errored = []
+		for (const dir of roots) {
+			const [err, skill] = await fingerprint_skill(dir)
+			if (err) errored.push({ dir, error: err })
+			else skills.push(skill)
+		}
+		return { skills, errored }
+	})
+
+module.exports = { scan_folder, fingerprint_skill, find_skill_roots, has_manifest, read_skill_name }

package/src/match/scanner.test.js

@@ -0,0 +1,93 @@
+'use strict'
+// Spec 260629-03 §4.6 — local skill scanner + fileset normalization.
+//
+// The load-bearing assertion (§6 #2): the scanner's locally-computed tree_sha
+// must equal what the PUSH path produces for the same content — otherwise a
+// byte-identical skill shows as "different" and the `certified` tier is broken.
+// We prove that by computing the expected tree_sha/skill_md_sha with the
+// SERVER's canonical git_objects (imported across the monorepo), independent of
+// the CLI's mirror. We also prove cruft (.DS_Store) is excluded and a symlinked
+// skill resolves to its real content (deduped).
+
+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')
+
+const { scan_folder, find_skill_roots, fingerprint_skill } = require('./scanner')
+// The canonical server algorithm — the reference the CLI mirror must match.
+const { hash_tree: canon_tree, hash_blob: canon_blob } = require('../../../api/app/utils/git_objects')
+
+let root
+const w = (p, content) => { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, content) }
+
+before(() => {
+	root = fs.mkdtempSync(path.join(os.tmpdir(), 'match-scan-'))
+
+	// alpha — a clean skill: SKILL.md + a nested reference file.
+	w(path.join(root, 'skills/alpha/SKILL.md'), '# Alpha\nDoes alpha things.\n')
+	w(path.join(root, 'skills/alpha/references/guide.md'), 'detailed guide\n')
+	w(path.join(root, 'skills/alpha/skill.json'), JSON.stringify({ name: 'alpha-skill', version: '1.0.0', type: 'skill' }))
+
+	// beta — carries install cruft that MUST be excluded from the fingerprint.
+	w(path.join(root, 'skills/beta/SKILL.md'), '# Beta\n')
+	w(path.join(root, 'skills/beta/.DS_Store'), 'macos cruft\n')
+
+	// gamma-real + a symlink to it — the multi-agent install shape.
+	w(path.join(root, 'links/gamma-real/SKILL.md'), '# Gamma\n')
+	w(path.join(root, 'links/gamma-real/extra.txt'), 'x\n')
+	fs.symlinkSync(path.join(root, 'links/gamma-real'), path.join(root, 'links/gamma'), 'dir')
+})
+
+after(() => { try { fs.rmSync(root, { recursive: true, force: true }) } catch {} })
+
+// Expected fingerprint computed from a known fileset using the SERVER algorithm.
+// canon_tree returns { sha, buffer } — we compare the hex sha.
+const expected_tree = (entries) => canon_tree(entries.map(en => ({ path: en.path, sha: canon_blob(Buffer.from(en.content)) }))).sha
+
+test('discovers each skill root and does not descend past it (references/ is not a separate skill)', () => {
+	const roots = find_skill_roots(path.join(root, 'skills'))
+	const names = roots.map(r => path.basename(r)).sort()
+	assert.deepEqual(names, ['alpha', 'beta'])
+})
+
+test('alpha: tree_sha + skill_md_sha equal the values the PUSH path would produce (server algorithm)', async () => {
+	const [err, skill] = await fingerprint_skill(path.join(root, 'skills/alpha'))
+	assert.equal(err, null)
+	assert.equal(skill.name, 'alpha-skill', 'name comes from skill.json')
+
+	const files = [
+		{ path: 'SKILL.md', content: '# Alpha\nDoes alpha things.\n' },
+		{ path: 'references/guide.md', content: 'detailed guide\n' },
+		{ path: 'skill.json', content: JSON.stringify({ name: 'alpha-skill', version: '1.0.0', type: 'skill' }) },
+	]
+	assert.equal(skill.tree_sha, expected_tree(files), 'CLI tree_sha must match the server hash_tree byte-for-byte')
+	assert.equal(skill.skill_md_sha, canon_blob(Buffer.from('# Alpha\nDoes alpha things.\n')), 'skill_md_sha = git-blob hash of SKILL.md')
+	assert.deepEqual([...skill.files.map(f => f.path)].sort(), ['SKILL.md', 'references/guide.md', 'skill.json'].sort())
+})
+
+test('beta: .DS_Store cruft is excluded from the manifest and the tree_sha', async () => {
+	const [err, skill] = await fingerprint_skill(path.join(root, 'skills/beta'))
+	assert.equal(err, null)
+	assert.ok(!skill.files.some(f => f.path.includes('.DS_Store')), '.DS_Store must not be in the manifest')
+	// tree_sha matches a tree of ONLY SKILL.md — proving the cruft never entered the hash.
+	assert.equal(skill.tree_sha, expected_tree([{ path: 'SKILL.md', content: '# Beta\n' }]))
+})
+
+test('a symlinked skill resolves to real content and is counted once (dedupe by realpath)', async () => {
+	const [err, result] = await scan_folder(path.join(root, 'links'))
+	assert.equal(err, null)
+	assert.equal(result.skills.length, 1, 'symlink + its target must not both count')
+	assert.equal(result.skills[0].tree_sha, expected_tree([
+		{ path: 'SKILL.md', content: '# Gamma\n' },
+		{ path: 'extra.txt', content: 'x\n' },
+	]), 'fingerprint reflects the real (symlink-followed) content')
+})
+
+test('scan_folder surfaces all skills with no false errors', async () => {
+	const [err, result] = await scan_folder(path.join(root, 'skills'))
+	assert.equal(err, null)
+	assert.equal(result.skills.length, 2)
+	assert.equal(result.errored.length, 0)
+})

package/src/utils/concurrency.js

@@ -0,0 +1,28 @@
+'use strict'
+// Bounded-concurrency wrapper over core-async's `throttle` — the ONE place the
+// match pipeline (and any future fan-out) imports concurrency from (spec
+// 260629-03 §4.5). `throttle` keeps at most `limit` task thunks in flight and
+// pulls the next the instant a slot frees (no fixed-batch head-of-line
+// blocking). Crucially, a FAILED task resolves to `{ error }` instead of
+// throwing — so one bad skill never aborts the whole scan. Callers MUST
+// partition the `{ error }` results and surface them (never drop them silently
+// — CLAUDE.md no-silent-failures).
+//
+// Bounded concurrency is also rate-limit safety: an unbounded fan-out of ~70
+// manifest/blob fetches can trip the API RateLimited alarm (see memory
+// project_rate_limit_observability_and_nudge). Keep the default modest.
+
+const { throttle } = require('core-async')
+
+const DEFAULT_CONCURRENCY = 6
+
+// Deliberately NOT catch_errors-wrapped: it returns throttle's results array
+// verbatim (order-preserving; a failed task is `{ error }`, not a throw) so
+// callers keep the per-task error partition. Wrapping it would collapse that to
+// a single [errors, result] and lose which task failed.
+const bounded = (tasks, limit = DEFAULT_CONCURRENCY) => {
+	const n = Number.isInteger(limit) && limit > 0 ? limit : DEFAULT_CONCURRENCY
+	return throttle(Array.isArray(tasks) ? tasks : [], n)
+}
+
+module.exports = { bounded, DEFAULT_CONCURRENCY }

package/src/utils/concurrency.test.js

@@ -0,0 +1,53 @@
+'use strict'
+// Spec 260629-03 §4.5 — bounded() over core-async throttle. The three load-
+// bearing guarantees: never exceed the limit, complete every task in order, and
+// a throwing task yields `{ error }` WITHOUT rejecting the whole batch (so one
+// bad skill never aborts a match scan). Run with: node --test.
+
+const { test } = require('node:test')
+const assert = require('node:assert/strict')
+const { bounded, DEFAULT_CONCURRENCY } = require('./concurrency')
+
+test('never exceeds the limit, completes every task, preserves order', async () => {
+	let inflight = 0, peak = 0
+	const mk = (i) => async () => {
+		inflight++; peak = Math.max(peak, inflight)
+		await new Promise(r => setTimeout(r, 5))
+		inflight--
+		return i
+	}
+	const tasks = Array.from({ length: 20 }, (_, i) => mk(i))
+	const res = await bounded(tasks, 4)
+	assert.ok(peak <= 4, `peak concurrency ${peak} must not exceed the limit of 4`)
+	assert.deepEqual(res, Array.from({ length: 20 }, (_, i) => i), 'all tasks complete, order preserved')
+})
+
+test('a throwing task yields { error } without rejecting the batch', async () => {
+	const tasks = [
+		async () => 'ok-0',
+		async () => { throw new Error('boom-1') },
+		async () => 'ok-2',
+	]
+	const res = await bounded(tasks, 2)
+	assert.equal(res[0], 'ok-0')
+	assert.ok(res[1] && res[1].error instanceof Error, 'failed task is partitioned as { error }')
+	assert.match(res[1].error.message, /boom-1/)
+	assert.equal(res[2], 'ok-2', 'sibling tasks still complete')
+})
+
+test('defaults to DEFAULT_CONCURRENCY and tolerates a bad limit', async () => {
+	assert.equal(DEFAULT_CONCURRENCY, 6)
+	let inflight = 0, peak = 0
+	const mk = () => async () => {
+		inflight++; peak = Math.max(peak, inflight)
+		await new Promise(r => setTimeout(r, 5))
+		inflight--
+	}
+	await bounded(Array.from({ length: 12 }, mk), 0) // 0 is invalid → falls back to the default
+	assert.ok(peak <= DEFAULT_CONCURRENCY, `bad limit must fall back to ${DEFAULT_CONCURRENCY}, peak was ${peak}`)
+})
+
+test('empty / non-array input resolves to an empty array', async () => {
+	assert.deepEqual(await bounded([], 4), [])
+	assert.deepEqual(await bounded(undefined, 4), [])
+})

package/src/utils/git_hash.js

@@ -6,4 +6,32 @@ const hash_blob = (buf) => {
 	return crypto.createHash('sha256').update(header).update(buf).digest('hex')
 }
 
-module.exports = { hash_blob }
+// Git-tree hash over a flat entry list — an EXACT byte-for-byte mirror of the
+// server's canonical `hash_tree` in api/app/utils/git_objects.js. The server
+// builds the tree from the flat file list the CLI pushes, so the CLI never had
+// a tree hash of its own; `happyskills match` needs one to reproduce a skill's
+// catalog `tree_sha` locally and compare it (spec 260629-03 §4.6). Identity:
+// equal tree_sha ⇒ byte-identical skill. Cross-package import is impossible
+// (separate npm packages), so this is a deliberate mirror — if the server
+// algorithm ever changes, change it here too (the e2e journey
+// match-local-skills.spec.js proves the two stay byte-aligned end-to-end).
+//
+// Entries: [{ path, sha }] (sha = the file's blob hash). Sorted by
+// path.localeCompare, serialized as `<mode> <path>\0<32-byte-binary-sha>`,
+// wrapped in `tree <len>\0`, then sha256'd. mode defaults to '100644' (the
+// server never sends a mode either).
+const hash_tree = (entries) => {
+	const sorted = [...entries].sort((a, b) => a.path.localeCompare(b.path))
+	const parts = sorted.map(entry => {
+		const mode = entry.mode || '100644'
+		const prefix = Buffer.from(`${mode} ${entry.path}\0`)
+		const sha_bin = Buffer.from(entry.sha, 'hex')
+		return Buffer.concat([prefix, sha_bin])
+	})
+	const content = Buffer.concat(parts)
+	const header = Buffer.from(`tree ${content.length}\0`)
+	const full = Buffer.concat([header, content])
+	return crypto.createHash('sha256').update(full).digest('hex')
+}
+
+module.exports = { hash_blob, hash_tree }