happyskills 0.54.0 → 1.0.0

package/src/commands/postlex.test.js

@@ -172,25 +172,32 @@ describe('determine_next_step', () => {
 		rationale:      '',
 	}))
 
-	it('emits present_to_user when top 3 are all strong/good', () => {
+	// Per spec 260525-cli-default-json § 7.1 the closed action names are
+	// "clarify_query" (kind=clarification) and "present_to_user"
+	// (kind=continuation). Tests below use those — the older bare "clarify"
+	// label is deprecated.
+
+	it('emits present_to_user (kind=continuation) when top 3 are all strong/good', () => {
 		const ns = determine_next_step(fo(['strong', 'good', 'strong']), 'q', 0)
 		assert.equal(ns.action, 'present_to_user')
+		assert.equal(ns.kind, 'continuation')
 	})
 
-	it('emits clarify when top 3 include a partial AND budget remains', () => {
+	it('emits clarify_query (kind=clarification) when top 3 include a partial AND budget remains', () => {
 		const ns = determine_next_step(fo(['strong', 'partial', 'good']), 'q', 0)
-		assert.equal(ns.action, 'clarify')
-		assert.equal(ns.max_turns_remaining, 2)
+		assert.equal(ns.action, 'clarify_query')
+		assert.equal(ns.kind, 'clarification')
+		// max_turns_remaining + suggested_questions live inside context (spec § 4.5).
+		assert.equal(ns.context.max_turns_remaining, 2)
 		assert.equal(ns.context.clarification_turns_used, 0)
-		// Always includes a "Just search anyway" option.
-		const last = ns.suggested_questions[0].options[ns.suggested_questions[0].options.length - 1]
+		const last = ns.context.suggested_questions[0].options[ns.context.suggested_questions[0].options.length - 1]
 		assert.match(last.label, /search anyway/i)
 	})
 
-	it('emits clarify when top 3 include a weak/null AND budget remains', () => {
+	it('emits clarify_query when top 3 include a weak/null AND budget remains', () => {
 		const ns = determine_next_step(fo(['weak', 'good', null]), 'q', 1)
-		assert.equal(ns.action, 'clarify')
-		assert.equal(ns.max_turns_remaining, 1)
+		assert.equal(ns.action, 'clarify_query')
+		assert.equal(ns.context.max_turns_remaining, 1)
 	})
 
 	it('emits present_to_user with budget-spent note when budget exhausted', () => {
@@ -201,7 +208,7 @@ describe('determine_next_step', () => {
 
 	it('clamps clarification_turns_used to [0, 2]', () => {
 		const ns_neg = determine_next_step(fo(['partial', 'partial', 'partial']), 'q', -1)
-		assert.equal(ns_neg.max_turns_remaining, 2)
+		assert.equal(ns_neg.context.max_turns_remaining, 2)
 		const ns_big = determine_next_step(fo(['partial', 'partial', 'partial']), 'q', 99)
 		assert.equal(ns_big.action, 'present_to_user')
 	})
@@ -218,16 +225,28 @@ describe('determine_next_step', () => {
 })
 
 // ─── build_retry_envelope ─────────────────────────────────────────────────
+// Envelope contract: six-key { ok, data, error, next_step, warnings, meta }
+// with data={}, error.code=RANKING_SCHEMA_MISMATCH (closed enum), kind=recovery,
+// action=retry_rank, exit_code mirrored on meta (NOT on error).
+
+const { validate_envelope } = require('../schema/envelope_validator')
 
 describe('build_retry_envelope', () => {
-	it('produces a retry_rank envelope with all required fields', () => {
+	it('produces a retry_rank envelope conforming to the closed schema', () => {
 		const env = build_retry_envelope('the query', 'ranking missing field rationale', 1, 0)
-		assert.equal(env.data, null)
-		assert.equal(env.error.code, 'ranking_schema_mismatch')
-		assert.equal(env.error.exit_code, 0)
+		const { ok, errors } = validate_envelope(env)
+		assert.equal(ok, true, `envelope failed validation: ${JSON.stringify(errors)}`)
+		assert.equal(env.ok, false, 'retry envelope is a failure (ok=false)')
+		assert.deepEqual(env.data, {}, 'data must be the empty object, never null')
+		assert.equal(env.error.code, 'RANKING_SCHEMA_MISMATCH')
+		assert.equal(typeof env.error.message, 'string')
+		assert.equal('exit_code' in env.error, false, 'exit_code lives on meta, not error')
+		assert.equal(env.next_step.kind, 'recovery')
 		assert.equal(env.next_step.action, 'retry_rank')
 		assert.equal(env.next_step.context.clarification_turns_used, 1)
 		assert.equal(env.next_step.context.retry_count, 1)
+		assert.equal(env.meta.command, 'postlex')
+		assert.ok(env.meta.exit_code > 0, 'retry envelope must mirror a non-zero exit code')
 	})
 
 	it('increments retry_count on each call', () => {
@@ -344,8 +363,16 @@ describe('normalize_data_rows', () => {
 // ─── extract_data_array_from_search_output (v0.48.0) ──────────────────────
 
 describe('extract_data_array_from_search_output', () => {
-	it('extracts data.results from the canonical envelope shape', () => {
-		const env = { data: { query: 'q', mode: 'semantic', results: [{ name: 'foo' }] }, error: null, next_step: null }
+	it('extracts data.results from the canonical (spec 260525) envelope shape', () => {
+		// Canonical envelope: every key always an object, never null.
+		const env = {
+			ok: true,
+			data: { query: 'q', mode: 'semantic', results: [{ name: 'foo' }] },
+			error: {},
+			next_step: {},
+			warnings: [],
+			meta: { command: 'search', exit_code: 0, envelope_schema_version: '1.0.0' },
+		}
 		const r = extract_data_array_from_search_output(env)
 		assert.equal(r.length, 1)
 		assert.equal(r[0].name, 'foo')
@@ -380,9 +407,12 @@ describe('parse_input with --search-output', () => {
 	it('extracts data.results from a full search envelope passed as the third argument', () => {
 		const ranking = JSON.stringify({ ranking: [{ rank: 1, candidate_id: 1, rationale: 'top' }] })
 		const search_out = JSON.stringify({
+			ok: true,
 			data: { query: 'q', mode: 'semantic', results: [{ name: 'deploy-aws', workspace_slug: 'acme' }] },
-			error: null,
-			next_step: null,
+			error: {},
+			next_step: {},
+			warnings: [],
+			meta: { command: 'search', exit_code: 0, envelope_schema_version: '1.0.0' },
 		})
 		const r = parse_input(ranking, null, search_out)
 		assert.equal(r.parse_error, null)

package/src/commands/pull.js

@@ -125,7 +125,11 @@ const run = (args) => catch_errors('Pull failed', async () => {
 				next_step: result.next_step || null,
 				error: result.error || null
 			})
-			if (result.next_step) process.exit(EXIT_CODES.ERROR)
+			// Spec § 9.1 — exit code reflects whether the OPERATION succeeded,
+			// not whether a next_step is present. Success-with-followup (data
+			// populated, next_step set, error empty) is exit 0. A populated
+			// error is the signal for non-zero exit.
+			if (result.error && result.error.code) process.exit(EXIT_CODES.ERROR)
 			return
 		}
 		if (result.error) {

package/src/commands/reconcile.js

@@ -58,6 +58,52 @@ const resolve_lock_entry = (raw, project_root, is_global) => catch_errors('Faile
 	return { full, lock_entry, lock_data }
 })
 
+// Expand the internal { action, context: {...} } reconcile result into the
+// closed-enum six-key next_step shape (spec § 4.5 / § 7). Returns {} for
+// the no-followup case.
+const NEXT_STEP_INSTRUCTIONS = {
+	resolve_regression: 'Disk version is older than lock. Pick one of the listed options and re-run with --apply <option>.',
+	resolve_missing_skill_json: 'skill.json is missing. Pick one of the listed restore options and re-run with --apply <option>.',
+	resolve_missing_dir: 'The skill directory is missing. Pick one of the listed options and re-run with --apply <option>.',
+	install_first: 'Skill is not in the lock file. Install it first, then re-run reconcile.',
+}
+const NEXT_STEP_KINDS_MAP = {
+	resolve_regression:         'decision',
+	resolve_missing_skill_json: 'decision',
+	resolve_missing_dir:        'decision',
+	install_first:              'routing',
+}
+const enrich_reconcile_next_step = (ns, full) => {
+	if (!ns || typeof ns !== 'object') return {}
+	const action = ns.action
+	if (!action) return {}
+	const kind = NEXT_STEP_KINDS_MAP[action] || 'decision'
+	if (action === 'install_first') {
+		return {
+			kind,
+			action,
+			instructions: NEXT_STEP_INSTRUCTIONS.install_first,
+			context: { commands: [`npx happyskills install ${full} --json`] },
+			route_to_skill: 'happyskills',
+		}
+	}
+	const opts = ns.context?.options || []
+	return {
+		kind,
+		action,
+		instructions: NEXT_STEP_INSTRUCTIONS[action] || 'Pick one of the listed options and re-run.',
+		context: {
+			options: opts,
+			...(ns.context?.drift ? { drift: ns.context.drift } : {}),
+			commands: opts.length > 0
+				? [`npx happyskills reconcile ${full} --apply ${opts[0]} --json`]
+				: undefined,
+		},
+		principal_authorization_required: true,
+		route_to_skill: 'happyskills-sync',
+	}
+}
+
 const apply_restore_from_lock_version = ({ skill_dir, lock_entry }) => catch_errors('Failed to restore from lock', async () => {
 	const [read_err, manifest] = await read_manifest(skill_dir)
 	if (read_err) throw e('Failed to read skill.json', read_err)
@@ -197,10 +243,12 @@ const run = (args) => catch_errors('Reconcile failed', async () => {
 	if (recon_err) throw e('Reconcile failed', recon_err)
 
 	if (args.flags.json) {
-		const envelope = { data: result.data }
-		if (result.next_step !== undefined) envelope.next_step = result.next_step
-		if (result.hint !== undefined) envelope.hint = result.hint
-		print_json(envelope)
+		const { emit_envelope } = require('../ui/envelope')
+		// Inline the human-readable hint into data so the envelope's
+		// next_step slot remains reserved for actionable protocol followups.
+		const data = result.hint !== undefined ? { ...result.data, hint: result.hint } : result.data
+		const next_step = enrich_reconcile_next_step(result.next_step, full)
+		emit_envelope({ data, next_step })
 		return
 	}
 

package/src/commands/release.js

@@ -217,11 +217,14 @@ const orchestrate = (args) => catch_errors('Release failed', async () => {
 				drift: target_info.drift
 			}),
 			next_step: {
-				action: 'reconcile_first',
+				kind:         'recovery',
+				action:       'reconcile_first',
+				instructions: 'Drift must be resolved before release. Run reconcile, follow its next_step, then retry release.',
 				context: {
-					reconcile_command: `npx happyskills reconcile ${lock_key} --json`,
-					skill: lock_key
-				}
+					commands: [`npx happyskills reconcile ${lock_key} --json`],
+					skill:    lock_key,
+				},
+				route_to_skill: 'happyskills-sync',
 			}
 		})
 		return { code: EXIT_CODES.ERROR, envelope: restored }
@@ -229,14 +232,26 @@ const orchestrate = (args) => catch_errors('Release failed', async () => {
 	if (target_info.status === 'missing_version') {
 		const restored = await restore_and({
 			...envelope_error('MISSING_VERSION', '--no-bump was passed but disk is not ahead of lock; nothing to publish.'),
-			next_step: { action: 'specify_bump_type', context: { current_version: manifest.version } }
+			next_step: {
+				kind:         'decision',
+				action:       'specify_bump_type',
+				instructions: 'No target version determined. Pick a bump type and re-run.',
+				context:      { options: ['patch', 'minor', 'major'], current_version: manifest.version },
+				principal_authorization_required: true,
+			}
 		})
 		return { code: EXIT_CODES.USAGE, envelope: restored }
 	}
 	if (target_info.status === 'invalid_bump') {
 		const restored = await restore_and({
 			...envelope_error('INVALID_BUMP', `--bump "${target_info.bump}" is not patch/minor/major or a valid semver.`),
-			next_step: { action: 'specify_bump_type', context: { current_version: manifest.version } }
+			next_step: {
+				kind:         'decision',
+				action:       'specify_bump_type',
+				instructions: 'The bump value is not valid. Pick a bump type and re-run.',
+				context:      { options: ['patch', 'minor', 'major'], current_version: manifest.version, got: target_info.bump },
+				principal_authorization_required: true,
+			}
 		})
 		return { code: EXIT_CODES.USAGE, envelope: restored }
 	}
@@ -244,8 +259,11 @@ const orchestrate = (args) => catch_errors('Release failed', async () => {
 		const restored = await restore_and({
 			...envelope_error('MISSING_VERSION', 'No --bump provided and no CHANGELOG entry indicates an intended next version.'),
 			next_step: {
-				action: 'specify_bump_type',
-				context: { current_version: manifest.version, options: ['patch', 'minor', 'major', 'explicit-version'] }
+				kind:         'decision',
+				action:       'specify_bump_type',
+				instructions: 'No target version provided. Pick a bump type and re-run.',
+				context:      { options: ['patch', 'minor', 'major'], current_version: manifest.version },
+				principal_authorization_required: true,
 			}
 		})
 		return { code: EXIT_CODES.USAGE, envelope: restored }
@@ -254,12 +272,15 @@ const orchestrate = (args) => catch_errors('Release failed', async () => {
 		const restored = await restore_and({
 			...envelope_error('BUMP_DISAGREEMENT', `--bump ${target_info.requested_bump} disagrees with the disk version ${target_info.disk_version}.`),
 			next_step: {
-				action: 'resolve_bump_disagreement',
+				kind:         'decision',
+				action:       'resolve_bump_disagreement',
+				instructions: 'The --bump value disagrees with the disk version. Pick one and re-run.',
 				context: {
-					disk_version: target_info.disk_version,
+					disk_version:   target_info.disk_version,
 					requested_bump: target_info.requested_bump,
-					lock_version: target_info.lock_version
-				}
+					lock_version:   target_info.lock_version,
+				},
+				principal_authorization_required: true,
 			}
 		})
 		return { code: EXIT_CODES.USAGE, envelope: restored }
@@ -299,7 +320,13 @@ const orchestrate = (args) => catch_errors('Release failed', async () => {
 			if (cf_err || !cf_content) {
 				const restored = await restore_and({
 					...envelope_error('CHANGELOG_SOURCE_UNREADABLE', `Could not read --changelog-from "${changelog_from}".`),
-					next_step: { action: 'provide_changelog' }
+					next_step: {
+						kind:         'recovery',
+						action:       'provide_changelog',
+						instructions: 'The --changelog-from file could not be read. Provide a readable file and re-run.',
+						context:      {},
+						principal_authorization_required: true,
+					}
 				})
 				return { code: EXIT_CODES.USAGE, envelope: restored }
 			}
@@ -311,8 +338,11 @@ const orchestrate = (args) => catch_errors('Release failed', async () => {
 			const restored = await restore_and({
 				...envelope_error('MISSING_CHANGELOG_ENTRY', `CHANGELOG.md does not contain a ## [${target_version}] entry.`),
 				next_step: {
-					action: 'provide_changelog',
-					context: { target_version, current_top_entry: cl_top }
+					kind:         'recovery',
+					action:       'provide_changelog',
+					instructions: 'CHANGELOG.md is missing an entry for the target version. Add the entry and re-run release.',
+					context:      { target_version, current_top_entry: cl_top },
+					principal_authorization_required: true,
 				}
 			})
 			return { code: EXIT_CODES.USAGE, envelope: restored }

package/src/commands/schema.js

@@ -0,0 +1,179 @@
+'use strict'
+// happyskills schema — machine-readable description of the CLI surface.
+// Spec 260525-cli-default-json § 10. A generic agent without HappySkills
+// skills installed can learn every command, every error code, and every
+// next_step.action in one call.
+//
+// Generation strategy: each command module MAY export a `schema` object
+// alongside `run`. When that's missing we fall back to a minimal stub so
+// the surface is always discoverable even if a command hasn't been audited
+// yet (defensive, additive). The schema lives next to the implementation
+// so there's no drift.
+
+const { error: { catch_errors } } = require('puffy-core')
+const { COMMANDS, COMMAND_ALIASES, CLI_VERSION } = require('../constants')
+const { ERROR_CODE_LIST } = require('../constants/error_codes')
+const {
+	NEXT_STEP_ACTION_LIST,
+	NEXT_STEP_KINDS,
+	ACTION_KIND,
+} = require('../constants/next_step_actions')
+const { ENVELOPE_SCHEMA_VERSION } = require('../schema/envelope_validator')
+const { print_help } = require('../ui/output')
+const { emit_envelope } = require('../ui/envelope')
+const { exit_with_error } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills schema [options]
+
+Emit a machine-readable description of the CLI surface — every command,
+its input contract, output envelope shape, error codes, and next_step
+actions. Designed for agentic discovery.
+
+Options:
+  --json            Output as JSON envelope (default for non-TTY callers)
+  --text            Output as a human-readable listing
+
+Examples:
+  happyskills schema --json
+  happyskills schema --text`
+
+// Compute aliases by walking COMMAND_ALIASES in reverse — each command
+// gets the list of aliases that resolve to it.
+const aliases_for = (name) => {
+	const out = []
+	for (const [alias, canonical] of Object.entries(COMMAND_ALIASES)) {
+		if (canonical === name) out.push(alias)
+	}
+	return out
+}
+
+// Audience inference fallback when a command module doesn't export schema.
+// Mapping aligns with docs/cli-commands-*.md taxonomy.
+const AUDIENCE_HINT = {
+	// consumer
+	init: 'consumer', install: 'consumer', uninstall: 'consumer',
+	list: 'consumer', check: 'consumer', status: 'consumer',
+	update: 'consumer', search: 'consumer', postlex: 'consumer',
+	diff: 'consumer', pull: 'consumer', snapshot: 'consumer',
+	reconcile: 'consumer', enable: 'consumer', disable: 'consumer',
+	versions: 'consumer', changelog: 'consumer', bump: 'consumer',
+	// author
+	publish: 'author', convert: 'author', fork: 'author',
+	validate: 'author', delete: 'author', visibility: 'author',
+	release: 'author',
+	// account
+	login: 'account', logout: 'account', whoami: 'account',
+	setup: 'account', config: 'account', people: 'account',
+	groups: 'account', access: 'account', agents: 'account',
+	feedback: 'account', 'self-update': 'account',
+	// system
+	schema: 'system',
+}
+
+const default_schema = (name) => ({
+	name,
+	aliases: aliases_for(name),
+	audience: AUDIENCE_HINT[name] || 'consumer',
+	purpose: `(no curated purpose for "${name}" yet)`,
+	mutation: ![
+		'list', 'check', 'status', 'search', 'postlex', 'diff', 'versions',
+		'changelog', 'whoami', 'schema',
+	].includes(name),
+	interactive_in_text_mode: false,
+	input: { positional: [], flags: [] },
+	output: { data_shape: {} },
+	errors: [],
+})
+
+// Load the per-command schema export. Misses fall back to default_schema.
+// We deliberately swallow errors inside the require so a broken module
+// doesn't crash `schema --json`.
+const load_command_schema = (name) => {
+	try {
+		const mod = require(`./${name}`)
+		if (mod && mod.schema && typeof mod.schema === 'object') {
+			return { ...default_schema(name), ...mod.schema, aliases: mod.schema.aliases || aliases_for(name) }
+		}
+	} catch (_) {
+		// ignored — fall through to default
+	}
+	return default_schema(name)
+}
+
+const build_command_registry = () => {
+	const all = [...COMMANDS]
+	if (!all.includes('schema')) all.push('schema')
+	return all.map(load_command_schema)
+}
+
+const build_error_code_list = () => ERROR_CODE_LIST.map(code => ({ code }))
+
+const build_next_step_action_list = () =>
+	NEXT_STEP_ACTION_LIST.map(action => ({ action, kind: ACTION_KIND[action] || null }))
+
+const build_schema_payload = () => ({
+	envelope_schema_version: ENVELOPE_SCHEMA_VERSION,
+	envelope_schema_uri:     'https://schemas.happyskills.dev/envelope/v1.json',
+	cli_version:             CLI_VERSION,
+	commands:                build_command_registry(),
+	error_codes:             build_error_code_list(),
+	next_step_actions:       build_next_step_action_list(),
+	next_step_kinds:         [...NEXT_STEP_KINDS],
+})
+
+const print_text_listing = (payload) => {
+	const groups = { consumer: [], author: [], account: [], system: [] }
+	for (const cmd of payload.commands) {
+		const bucket = groups[cmd.audience] || groups.consumer
+		bucket.push(cmd)
+	}
+	console.log(`happyskills v${payload.cli_version} — CLI surface (envelope schema v${payload.envelope_schema_version})`)
+	console.log('')
+	for (const [audience, list] of Object.entries(groups)) {
+		if (list.length === 0) continue
+		console.log(audience.toUpperCase())
+		for (const cmd of list.sort((a, b) => a.name.localeCompare(b.name))) {
+			const aliases = cmd.aliases && cmd.aliases.length ? `  (${cmd.aliases.join(', ')})` : ''
+			console.log(`  ${cmd.name.padEnd(14)} ${cmd.purpose}${aliases}`)
+		}
+		console.log('')
+	}
+	console.log(`For the full machine-readable contract: happyskills schema --json`)
+}
+
+const run = (args) => catch_errors('Schema command failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+	const payload = build_schema_payload()
+	if (args.flags.json) {
+		emit_envelope({ data: payload })
+		return
+	}
+	print_text_listing(payload)
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+// Schema for `schema` itself — recursive but harmless. § 10.
+const schema = {
+	name:     'schema',
+	aliases:  [],
+	audience: 'system',
+	purpose:  'Emit a machine-readable description of the CLI surface.',
+	mutation: false,
+	interactive_in_text_mode: false,
+	input: { positional: [], flags: [{ name: 'json', type: 'boolean' }, { name: 'text', type: 'boolean' }] },
+	output: { data_shape: {
+		envelope_schema_version: 'string',
+		envelope_schema_uri:     'string',
+		cli_version:             'string',
+		commands:                'array<CommandSchema>',
+		error_codes:             'array<{ code: string }>',
+		next_step_actions:       'array<{ action: string, kind: string }>',
+		next_step_kinds:         'array<string>',
+	} },
+	errors: [],
+}
+
+module.exports = { run, schema, build_schema_payload }

package/src/commands/search.js

@@ -129,7 +129,7 @@ const STRONG_TIERS = new Set(['strong', 'good'])
 
 const build_search_next_step = (response, query, opts) => {
 	const { with_rerank, clarification_turns_used } = opts
-	if (!with_rerank) return null
+	if (!with_rerank) return {}
 
 	const mode = response?.mode || null
 	const digests = Array.isArray(response?.rerank_digests) ? response.rerank_digests : null
@@ -138,17 +138,19 @@ const build_search_next_step = (response, query, opts) => {
 	const turns_remaining = 2 - turns_used
 
 	// Non-semantic modes (slug, scoped, exact-FTS) don't support rerank — server
-	// returns no digests. No envelope; agent just renders.
-	if (mode !== 'semantic') return null
+	// returns no digests. Empty next_step; agent just renders.
+	if (mode !== 'semantic') return {}
 
 	// Semantic + digests present → the protocol's primary path.
 	if (digests && digests.length > 0) {
 		return {
+			kind:         'continuation',
 			action:       'rank_digests_inline',
 			instructions: `Rank these candidates by how well their \`digest\` matches the query, using \`data.rerank_system_prompt\` as your system instructions. Emit JSON matching \`data.rerank_response_schema\`. Aim for ~20 items (10-30 acceptable; fewer if remaining candidates aren't clearly differentiated). Then pipe the result to \`npx happyskills postlex --query "${query}" --ranking - --clarification-turns-used ${turns_used}\`.`,
 			context: {
 				original_query:           query,
 				clarification_turns_used: turns_used,
+				commands: [`npx happyskills postlex --query "${query}" --ranking - --clarification-turns-used ${turns_used} --json`],
 			},
 		}
 	}
@@ -158,36 +160,38 @@ const build_search_next_step = (response, query, opts) => {
 	if (match_notice) {
 		if (turns_remaining <= 0) {
 			return {
+				kind:         'continuation',
 				action:       'present_to_user',
 				instructions: 'No top result is a strong match and the clarification budget (2 turns) is spent. Render `data.results` honestly: note the weak signal and present what you have so the user can decide. Do NOT ask another clarifying question.',
-				context:      null,
+				context:      { original_query: query, clarification_turns_used: turns_used },
 			}
 		}
 		return {
-			action: 'clarify',
-			instructions: `The search returned weak results. Ask the user one of \`suggested_questions\` using your agent's question mechanism, then re-run \`npx happyskills search "<refined query>" --with-rerank --json --limit 50 --clarification-turns-used ${turns_used + 1}\`. The last option is always "Just search anyway" — honor it by re-running with the original query unchanged.`,
-			suggested_questions: [
-				{
-					question: 'Quick clarification — what specifically are you looking for?',
-					options: [
-						{ label: 'A workflow or how-to guide',                       refined_query_hint: 'workflow' },
-						{ label: 'A specific tool or library',                       refined_query_hint: 'tool' },
-						{ label: 'A platform-specific recipe (AWS / GCP / Vercel)',  refined_query_hint: 'platform' },
-						{ label: 'Just search anyway',                               refined_query_hint: null },
-					],
-				},
-			],
-			max_turns_remaining: turns_remaining,
+			kind:         'clarification',
+			action:       'clarify_query',
+			instructions: `The search returned weak results. Ask the user one of \`context.suggested_questions\` using your agent's question mechanism, then re-run \`npx happyskills search "<refined query>" --with-rerank --json --limit 50 --clarification-turns-used ${turns_used + 1}\`. The last option is always "Just search anyway" — honor it by re-running with the original query unchanged.`,
 			context: {
 				original_query:           query,
 				clarification_turns_used: turns_used,
+				max_turns_remaining:      turns_remaining,
+				suggested_questions: [
+					{
+						question: 'Quick clarification — what specifically are you looking for?',
+						options: [
+							{ label: 'A workflow or how-to guide',                       refined_query_hint: 'workflow' },
+							{ label: 'A specific tool or library',                       refined_query_hint: 'tool' },
+							{ label: 'A platform-specific recipe (AWS / GCP / Vercel)',  refined_query_hint: 'platform' },
+							{ label: 'Just search anyway',                               refined_query_hint: null },
+						],
+					},
+				],
 			},
+			principal_authorization_required: true,
 		}
 	}
 
-	// Semantic, no digests, no match_notice (defensive — shouldn't normally
-	// happen). Agent renders the baseline results.
-	return null
+	// Semantic, no digests, no match_notice (defensive). Empty next_step.
+	return {}
 }
 
 const run_smart_search = (args, query, options) => catch_errors('Smart search failed', async () => {
@@ -234,7 +238,7 @@ const run_smart_search = (args, query, options) => catch_errors('Smart search fa
 			rerank_prompt_version: response?.rerank_prompt_version || null,
 		})
 	}
-	if (with_rerank && next_step?.action === 'clarify') {
+	if (with_rerank && next_step?.action === 'clarify_query') {
 		fire_discovery_telemetry({
 			event:       'clarify_triggered',
 			intent_id,