happyskills 0.54.0 → 1.0.0

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-05-29
+
+### Added
+
+- **Universal response envelope on every `--json` command** (spec 260525-cli-default-json). All structured output now emits a canonical six-key shape — `{ ok, data, error, next_step, warnings, meta }` — with `ok` derived from error presence, `data` always an object, and the process exit code mirrored into `meta.exit_code`. Agents can determine success/failure and the recovery path without parsing prose.
+- **`happyskills schema --json` command** — emits a machine-readable description of the entire CLI surface: every command, the closed `error_codes`, `next_step_actions`, and `next_step_kinds` enums. A generic agent can discover the full CLI contract in one call.
+- **Closed enums for the envelope** — `error.code` (state/auth/network/validation/etc.), `next_step.kind` (six kinds: recovery, clarification, decision, confirmation, continuation, routing), and `next_step.action` (~27 actions). Shipped as `cli/src/constants/{error_codes,next_step_actions}.js`, kept byte-identical with the API.
+- **Hand-rolled envelope validator** (`cli/src/schema/envelope_validator.js`) — enforces the closed schema, the `dependentRequired` clusters (code+message, kind+action+instructions), and the derived invariants. No new runtime dependency.
+- **Mode resolution** — `--json` / `--text` explicit flags, `CI=true` and non-TTY auto-flip to JSON, interactive TTY defaults to text. `--json` + `--text` together is a usage error.
+
+### Changed
+
+- **BREAKING: `--json` output format.** Every command's JSON output moved from the legacy `{ data }` / `{ error: { code, message, exit_code } }` shapes to the six-key envelope. `exit_code` now lives on `meta.exit_code`, not inside `error`. Consumers that parsed the old shapes must update — this is why the release is `1.0.0`.
+- **CLI consumes the new API envelope** while remaining backward-compatible with the current (pre-envelope) API. The `search`, `feedback`, and device-login clients detect the envelope and translate; against the old API they fall through to the legacy path, so the new CLI works against both.
+- **`error.code` is a closed enum end-to-end** — unknown codes from a newer API coerce to `UNKNOWN_CODE` with the original preserved under `error.details.original_code`.
+- **Per-command `next_step` recoveries** now use the closed action enum across `install`, `reconcile`, `release`, `search`, `postlex`, `validate`, `delete`, and `feedback` (e.g. `VERSION_NOT_FOUND` → `pick_version`, `LOCAL_EDITS_PRESENT` → `confirm_discard_or_snapshot_first`, `DRIFT_DETECTED` → `reconcile_first`).
+- **`install --fresh` pre-flight reordered** so the local-edit safety check runs before the registry call — local edits are protected even when the registry is unreachable.
+
+### Fixed
+
+- **`error.details` is now propagated** from API errors into the envelope (previously dropped) — e.g. `RATE_LIMITED`'s `retry_after_seconds` now reaches the caller.
+- **Batch per-row failures fold into `data.results`** for `install` and `uninstall` instead of a silently-dropped top-level `errors` key — each row carries its own `status` and `error`.
+- **Exit-code mirror corrected** for `pull --rebase` (success-with-followup no longer forces a non-zero exit) and `postlex` (a retry envelope's process exit now matches its `meta.exit_code`).
+
 ## [0.54.0] - 2026-05-26
 
 ### Added

package/package.json

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

package/src/api/auth.js

@@ -32,9 +32,25 @@ const device_start = () => catch_errors('Device auth start failed', async () =>
 })
 
 const device_token = (device_code) => catch_errors('Device auth token failed', async () => {
-	const [errors, data] = await client.post('/auth/device/token', { device_code }, { auth: false })
+	// Opt out of auto-unwrap so the caller can detect AUTHORIZATION_PENDING
+	// via the envelope's `error.code` slot on HTTP 202 (spec § 15.3.2). The
+	// new envelope keeps `error.code` at the same path the legacy ad-hoc
+	// body used, but moves the success token payload under `data` — so we
+	// flatten on success here and surface the error envelope on pending.
+	const [errors, raw] = await client.post('/auth/device/token', { device_code }, { auth: false, unwrap: false })
 	if (errors) throw errors[errors.length - 1]
-	return data
+	if (raw && typeof raw === 'object' && 'meta' in raw) {
+		if (raw.error && raw.error.code) {
+			// Pending / expired — surface the error slot so the poller can
+			// branch on error.code (works for both old + new shapes).
+			return { error: raw.error }
+		}
+		// Success: hoist token fields out of data so save_token sees the
+		// same shape it always has.
+		return raw.data || {}
+	}
+	// Legacy fallback (older API deploys without the envelope).
+	return raw
 })
 
 const refresh = (refresh_token) => catch_errors('Token refresh failed', async () => {

package/src/api/client.js

@@ -69,9 +69,16 @@ const request = (method, path, options = {}) => catch_errors(`API ${method} ${pa
 	if (!res.ok) {
 		const err_code = data?.error?.code || 'UNKNOWN'
 		const err_msg = data?.error?.message || `Request failed with status ${res.status}`
+		// Spec § 15.3.3 — propagate the API's error.details into the CLI's
+		// thrown ApiError. Previously dropped on the floor; RATE_LIMITED
+		// endpoints carry retry_after_seconds / max_per_window / window_hours
+		// inside details that never reached the user.
+		const err_details = data?.error?.details
 
 		if (res.status === 401) {
-			throw new AuthError(err_msg)
+			const err = new AuthError(err_msg)
+			if (err_details) err.details = err_details
+			throw err
 		}
 
 		if (res.status === 429) {
@@ -81,18 +88,37 @@ const request = (method, path, options = {}) => catch_errors(`API ${method} ${pa
 				: 'API rate limit reached. Please wait and try again.'
 			const err = new ApiError(retry_msg, 429, 'RATE_LIMITED')
 			err.retry_after = retry_after ? parseInt(retry_after) : null
+			if (err_details) err.details = { ...err.details, ...err_details }
 			throw err
 		}
 
-		throw new ApiError(err_msg, res.status, err_code)
+		const err = new ApiError(err_msg, res.status, err_code)
+		if (err_details) err.details = { ...err.details, ...err_details }
+		throw err
 	}
 
 	// Auto-unwrap `{ data: ... }` envelope by default. Callers that need the
 	// full response (e.g. endpoints that emit top-level metadata fields
 	// alongside `data` — see `dispatch_search` for `/repos:search`'s
 	// `mode` / `rerank_digests` / `match_notice` fields) pass `unwrap: false`.
+	//
+	// Second-layer unwrap: the new envelope's `normalise_data` helper wraps
+	// array payloads as `{ results: [...] }` so the top-level `data` slot
+	// stays an object (spec 260525-cli-default-json § 4.3). When the wrapper
+	// is the SOLE content (`Object.keys(d) === ['results']` and `results`
+	// is an array), strip it so the caller sees the bare array — preserves
+	// the legacy contract for `list_members`, `list_groups`, `search_users`,
+	// `get_refs`, etc. Multi-key shapes (search's `{results, mode, …}`,
+	// check_updates' `{results: <object-map>}`) are returned untouched.
 	if (!unwrap) return data
-	return data?.data !== undefined ? data.data : data
+	const inner = data?.data !== undefined ? data.data : data
+	if (inner && typeof inner === 'object' && !Array.isArray(inner)) {
+		const keys = Object.keys(inner)
+		if (keys.length === 1 && keys[0] === 'results' && Array.isArray(inner.results)) {
+			return inner.results
+		}
+	}
+	return inner
 })
 
 const get = (path, options) => request('GET', path, options)

package/src/api/feedback.js

@@ -7,13 +7,22 @@
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const client = require('./client')
 
-// POST /feedback — does NOT unwrap, so the caller can read `next_step` which
-// the API places alongside `feedback` inside `data`. (Our envelope is
-// `{ data: { feedback, next_step } }`.)
+// POST /feedback — opts out of the client's auto-unwrap so we can read
+// both the data slot (with the feedback row) AND the top-level next_step
+// (spec § 15.3.4: API now hoists next_step out of data). Returns the
+// CANONICAL envelope-shaped next_step verbatim so the CLI command can
+// pass it straight through to emit_envelope.
 const create_feedback = (payload) => catch_errors('Create feedback failed', async () => {
-	const [errors, data] = await client.post('/feedback', payload)
+	const [errors, raw] = await client.post('/feedback', payload, { unwrap: false })
 	if (errors) throw errors[errors.length - 1]
-	return data   // { feedback, next_step }
+	if (raw && typeof raw === 'object' && 'meta' in raw && raw.data && !Array.isArray(raw.data)) {
+		return {
+			feedback: raw.data.feedback,
+			next_step: raw.next_step && raw.next_step.action ? raw.next_step : null,
+		}
+	}
+	// Legacy fallback for older API deploys.
+	return raw && raw.data ? raw.data : raw
 })
 
 const initiate_attachment_upload = (feedback_id, payload) => catch_errors('Initiate attachment upload failed', async () => {

package/src/api/repos.js

@@ -145,18 +145,36 @@ const dispatch_search = (query, options = {}) => catch_errors('Search failed', a
 		workspace_slugs: options.workspace_slug ? options.workspace_slug.split(',').map(s => s.trim()).filter(Boolean) : null,
 		scope: options.workspace_slug ? null : (options.scope || null),
 	}
-	// Spec 260521-01 v2 § 5.1 — opt-in rerank digests for the discovery
-	// protocol. Server returns digests + system prompt + json_schema only
-	// when this is true AND the dispatcher routes to mode='semantic'.
 	if (options.with_rerank_digests) body.with_rerank_digests = true
-	// `/repos:search` returns top-level metadata alongside `data` —
-	// `mode`, `match_notice`, `workspace_match`, and (when opted-in)
-	// `rerank_digests`, `rerank_system_prompt`, `rerank_prompt_version`,
-	// `rerank_response_schema`. The client's default unwrap would drop these
-	// fields entirely. Opt out so the caller sees the full envelope.
-	const [errors, data] = await client.post('/repos:search', body, { auth: true, unwrap: false })
+	const [errors, raw] = await client.post('/repos:search', body, { auth: true, unwrap: false })
 	if (errors) throw errors[errors.length - 1]
-	return data
+	// Spec 260525 § 15.3.1 — the API now emits the canonical envelope:
+	//   { ok, data: { query, mode, results, match_notice, workspace_match,
+	//                 workspace_candidates, intent_id },
+	//     next_step: { kind, action: 'rank_digests_inline',
+	//                  context: { rerank_digests, rerank_system_prompt,
+	//                             rerank_prompt_version, rerank_response_schema } },
+	//     ... }
+	// The CLI's downstream (build_search_next_step + the search command) was
+	// written against the LEGACY flat shape — so we flatten here. This keeps
+	// the wire contract clean while letting the command code stay terse.
+	if (raw && typeof raw === 'object' && 'meta' in raw && 'data' in raw && raw.data && !Array.isArray(raw.data)) {
+		const data = raw.data
+		const rerank_ctx = raw.next_step?.context || {}
+		return {
+			data: Array.isArray(data.results) ? data.results : [],
+			mode: data.mode || null,
+			match_notice: data.match_notice || null,
+			workspace_match: data.workspace_match,
+			workspace_candidates: data.workspace_candidates,
+			intent_id: data.intent_id,
+			rerank_digests: rerank_ctx.rerank_digests || null,
+			rerank_system_prompt: rerank_ctx.rerank_system_prompt || null,
+			rerank_prompt_version: rerank_ctx.rerank_prompt_version || null,
+			rerank_response_schema: rerank_ctx.rerank_response_schema || null,
+		}
+	}
+	return raw
 })
 
 // Deprecated alias — kept for backwards compatibility with older code paths.

package/src/api/translate.js

@@ -0,0 +1,90 @@
+'use strict'
+// Post-Session-3 translator: near-identity. The public API now emits the
+// canonical six-key envelope natively (spec 260525-cli-default-json § 11),
+// so this module only stamps the CLI's local `meta.cli_version` on top of
+// the response — meta.api_version is preserved verbatim. Forward-compat
+// for unknown error codes still routes through UNKNOWN_CODE per § 5.2.
+//
+// This file will be deleted no later than two CLI releases after Session
+// 3. Keeping it as a stamp lets the dispatch layer stay symmetric with the
+// old shape until every caller has migrated.
+
+const { build_envelope } = require('../ui/envelope')
+const { ERROR_CODE_SET, ERROR_CODES } = require('../constants/error_codes')
+
+const is_plain_object = (x) => x !== null && typeof x === 'object' && !Array.isArray(x)
+
+// Detect whether the response already speaks the new envelope. If yes, we
+// stamp cli_version and pass-through. Otherwise we fall back to the
+// Session-2 reshape path (kept inline below for any straggler endpoint
+// that hasn't migrated yet — every public-API route is migrated as of
+// Session 3, but admin_api / older deploys aren't).
+const looks_like_envelope = (r) =>
+	is_plain_object(r) && 'ok' in r && 'data' in r && 'error' in r
+	&& 'next_step' in r && 'warnings' in r && 'meta' in r
+
+const stamp_cli_version = (env, ctx = {}) => {
+	const cli_meta = { ...env.meta }
+	if (ctx.command) cli_meta.command = ctx.command
+	if (ctx.exit_code_override != null) cli_meta.exit_code = ctx.exit_code_override
+	return { ...env, meta: cli_meta }
+}
+
+const rewrite_unknown_error_code = (env) => {
+	if (!env.error || !env.error.code) return env
+	if (ERROR_CODE_SET.has(env.error.code)) return env
+	const original_code = env.error.code
+	return {
+		...env,
+		error: {
+			...env.error,
+			code: ERROR_CODES.UNKNOWN_CODE,
+			details: { ...(env.error.details || {}), original_code },
+		},
+	}
+}
+
+const translate_api_envelope = (api_response, ctx = {}) => {
+	const command = ctx.command || 'api'
+
+	if (looks_like_envelope(api_response)) {
+		return stamp_cli_version(rewrite_unknown_error_code(api_response), { command, exit_code_override: ctx.exit_code_override })
+	}
+
+	// Legacy fallback. Same logic as Session 2's translator, kept for any
+	// endpoint that hasn't migrated yet. Removable after Session 3 ships.
+	if (is_plain_object(api_response?.error) && api_response.error.code) {
+		const code = ERROR_CODE_SET.has(api_response.error.code)
+			? api_response.error.code
+			: ERROR_CODES.UNKNOWN_CODE
+		const error_payload = {
+			code,
+			message: api_response.error.message || `API error: ${code}`,
+		}
+		if (api_response.error.details) error_payload.details = api_response.error.details
+		if (code === ERROR_CODES.UNKNOWN_CODE && api_response.error.code) {
+			error_payload.details = { ...(error_payload.details || {}), original_code: api_response.error.code }
+		}
+		return build_envelope({
+			data: api_response.data || {},
+			error: error_payload,
+			next_step: api_response.next_step || {},
+			meta_overrides: { command, ...(ctx.exit_code_override != null ? { exit_code: ctx.exit_code_override } : {}) },
+		})
+	}
+
+	let data = api_response?.data
+	if (!is_plain_object(data)) {
+		if (Array.isArray(data)) data = { results: data }
+		else if (data == null) data = {}
+		else data = { value: data }
+	}
+
+	return build_envelope({
+		data,
+		next_step: api_response?.next_step || null,
+		meta_overrides: { command, ...(ctx.exit_code_override != null ? { exit_code: ctx.exit_code_override } : {}) },
+	})
+}
+
+module.exports = { translate_api_envelope }

package/src/commands/delete.js

@@ -54,7 +54,21 @@ const run = (args) => catch_errors('Delete failed', async () => {
 
 	if (args.flags.json) {
 		if (!args.flags.yes) {
-			throw new CliError('Confirmation required. Use -y or --yes to confirm deletion in JSON mode.', EXIT_CODES.ERROR)
+			const { ERROR_CODES } = require('../constants/error_codes')
+			throw new CliError(`Confirmation required to delete ${skill}. Re-run with -y to proceed.`, {
+				code: ERROR_CODES.CONFIRMATION_REQUIRED,
+				exit_code: 1,
+				next_step: {
+					kind:         'confirmation',
+					action:       'confirm_destructive',
+					instructions: 'Deleting a skill is irreversible. Re-run with -y to confirm.',
+					context: {
+						would_remove: [skill],
+						commands: [`npx happyskills delete ${skill} --json -y`],
+					},
+					principal_authorization_required: true,
+				},
+			})
 		}
 	} else {
 		const confirmed = await _ask_confirmation(skill)

package/src/commands/feedback.js

@@ -252,8 +252,8 @@ const run = (args) => catch_errors('Feedback command failed', async () => {
 	print_success(`Feedback recorded (#${short_id}).`)
 	if (attachments.length > 0) {
 		print_info(`Uploaded ${attachments.length} attachment${attachments.length === 1 ? '' : 's'}.`)
-	} else if (next_step && next_step.attachments_supported && attach_paths.length === 0) {
-		print_hint(`Pass --attach <path> to add a screenshot (max ${next_step.max_attachments}).`)
+	} else if (next_step && next_step.context && next_step.context.attachments_supported && attach_paths.length === 0) {
+		print_hint(`Pass --attach <path> to add a screenshot (max ${next_step.context.max_attachments}).`)
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 

package/src/commands/init.js

@@ -87,7 +87,11 @@ const run = (args) => catch_errors('Init failed', async () => {
 
 	const [, json_exists] = await file_exists(path.join(dir, SKILL_JSON))
 	if (json_exists) {
-		throw new CliError(`${SKILL_JSON} already exists at ${dir}`, EXIT_CODES.ERROR)
+		const { ERROR_CODES } = require('../constants/error_codes')
+		throw new CliError(`${SKILL_JSON} already exists at ${dir}`, {
+			code: ERROR_CODES.ALREADY_EXISTS,
+			exit_code: 1,
+		})
 	}
 
 	const [dir_err] = await ensure_dir(dir)

package/src/commands/install.js

@@ -115,37 +115,22 @@ const run = (args) => catch_errors('Install failed', async () => {
 	// mode surfaces BEFORE any disk mutation.
 	const fresh_snapshots = []
 	if (base_options.fresh) {
+		const { CliError } = require('../utils/errors')
+		const { ERROR_CODES } = require('../constants/error_codes')
 		for (const { skill, version: inline_version } of parsed) {
 			const requested = flag_version || inline_version
 			if (!requested || requested === 'latest') continue
 
-			// (1) Verify the version exists on the registry. Hard-fail if not.
 			const [owner, name] = skill.split('/')
-			const [refs_err, refs] = await get_refs(owner, name)
-			if (refs_err) {
-				// Network failure or skill-not-found. Treat both as VERSION_NOT_FOUND
-				// because we cannot prove the version exists.
-				throw new UsageError(
-					`VERSION_NOT_FOUND: Cannot verify that ${skill}@${requested} exists on the registry (registry unreachable or skill unknown). ` +
-					`--fresh would wipe local content; refusing without confirmation.`
-				)
-			}
-			const available = (refs || []).map(r => extract_version(r.name)).filter(Boolean)
-			if (!available.includes(requested)) {
-				throw new UsageError(
-					`VERSION_NOT_FOUND: ${skill}@${requested} is not on the registry. ` +
-					`Available versions: ${available.join(', ') || '(none)'}. ` +
-					`This was previously a silent-fallback footgun (issue 260523-02 § 2.3) — --fresh now hard-fails.`
-				)
-			}
-
-			// (2) Snapshot before wiping. Always — so a failed install is reversible.
 			const base_dir = skills_dir(base_options.global, base_options.project_root)
 			const skill_dir = skill_install_dir(base_dir, name)
 			const [, dir_present] = await file_exists(skill_dir)
+
+			// (1) Local-edit check FIRST. The local-state gate is structurally
+			// earlier than the network call: if the disk would be clobbered, we
+			// refuse before contacting the registry. Spec § 8.5 + envelope
+			// integration test (install_fresh.test.js).
 			if (dir_present) {
-				// (3) Local-edit check. Compare on-disk hash to lock baseline; if
-				// they disagree, require explicit --force-discard-local.
 				const [, lock_data_pre] = await read_lock(base_options.project_root)
 				let has_local_edits = false
 				if (lock_data_pre) {
@@ -157,11 +142,44 @@ const run = (args) => catch_errors('Install failed', async () => {
 					}
 				}
 				if (has_local_edits && !args.flags['force-discard-local']) {
-					throw new UsageError(
-						`LOCAL_EDITS_PRESENT: ${skill} has local edits that would be destroyed by --fresh. ` +
-						`Snapshot first (\`happyskills snapshot create ${skill}\`) and pass --force-discard-local to proceed.`
+					throw new CliError(
+						`${skill} has local edits that would be destroyed by --fresh.`,
+						{
+							code:      ERROR_CODES.LOCAL_EDITS_PRESENT,
+							exit_code: 1,
+							context:   { skill, version: requested },
+						}
 					)
 				}
+			}
+
+			// (2) Verify the version exists on the registry. Hard-fail if not.
+			const [refs_err, refs] = await get_refs(owner, name)
+			if (refs_err) {
+				throw new CliError(
+					`Cannot verify that ${skill}@${requested} exists on the registry (registry unreachable or skill unknown). --fresh would wipe local content; refusing without confirmation.`,
+					{
+						code:      ERROR_CODES.VERSION_NOT_FOUND,
+						exit_code: 2,
+						context:   { skill, requested },
+					}
+				)
+			}
+			const available = (refs || []).map(r => extract_version(r.name)).filter(Boolean)
+			if (!available.includes(requested)) {
+				throw new CliError(
+					`${skill}@${requested} is not on the registry. Available: ${available.join(', ') || '(none)'}.`,
+					{
+						code:      ERROR_CODES.VERSION_NOT_FOUND,
+						exit_code: 2,
+						context:   { skill, requested, available },
+					}
+				)
+			}
+
+			// (3) Snapshot before wiping. Always — so a failed install is reversible.
+			if (dir_present) {
+				const [, lock_data_pre] = await read_lock(base_options.project_root)
 				const [snap_err, snap] = await snapshot_storage.create({
 					skill_dir,
 					workspace: owner,
@@ -208,9 +226,17 @@ const run = (args) => catch_errors('Install failed', async () => {
 	const snapshot_by_skill = Object.fromEntries(fresh_snapshots.map(s => [s.skill, s.snapshot_id]))
 
 	if (args.flags.json) {
-		const items = results.map(({ skill, result }) => {
+		// Spec 260525-cli-default-json § 4.3 rules 2 + 4:
+		//   - No shape-flipping between single and batch — always emit
+		//     `data.results: [...]` so skills iterate uniformly.
+		//   - Per-row failures live inside `data.results[i].error`, not at
+		//     the envelope root (top-level `error` is reserved for whole-
+		//     operation failures). Pre-fix the `errors:` plural was a top-
+		//     level key that the print_json retrofit silently dropped.
+		const success_rows = results.map(({ skill, result }) => {
 			const item = {
 				skill,
+				status: 'installed',
 				version: result.version,
 				installed: result.installed || [],
 				skipped: result.skipped || [],
@@ -221,12 +247,12 @@ const run = (args) => catch_errors('Install failed', async () => {
 			if (snapshot_by_skill[skill]) item.snapshot_id = snapshot_by_skill[skill]
 			return item
 		})
-		const data = results.length === 1 && failures.length === 0 ? items[0] : items
-		if (failures.length > 0) {
-			print_json({ data, errors: failures })
-		} else {
-			print_json({ data })
-		}
+		const failure_rows = failures.map(({ skill, error }) => ({
+			skill,
+			status: 'failed',
+			error: { code: 'INTERNAL_ERROR', message: error }
+		}))
+		print_json({ data: { results: [...success_rows, ...failure_rows] } })
 		return
 	}
 

package/src/commands/postlex.js

@@ -178,61 +178,70 @@ const determine_next_step = (final_ordering, query, clarification_turns_used) =>
 
 	if (all_strong || final_ordering.length === 0) {
 		return {
+			kind:         'continuation',
 			action:       'present_to_user',
 			instructions: 'Render `data.final_ordering` as a table to the user, with skill name, slug, description, and rationale. Include `data.formulated_query` in your preamble.',
-			context:      null,
+			context:      { original_query: query, clarification_turns_used: turns_used },
 		}
 	}
 
 	if (turns_remaining <= 0) {
 		return {
+			kind:         'continuation',
 			action:       'present_to_user',
 			instructions: 'Even after reranking, no top result is a strong match — but the clarification budget (2 turns) is spent. Render `data.final_ordering` honestly: note that no result was a strong match, 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: `After reranking, no top result is a strong match. Ask the user one of \`suggested_questions\` using your agent's question mechanism (e.g. AskUserQuestion in Claude Code), then re-run search with the refined query and add --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: 'After reranking I still don\'t have a strong match. Could you narrow the scope a bit?',
-				options: [
-					{ label: 'Focus on a specific stack (Node / Python / Go / etc.)',  refined_query_hint: 'stack-specific' },
-					{ label: 'Focus on a specific platform (AWS / GCP / Vercel / etc.)', refined_query_hint: 'platform-specific' },
-					{ label: 'Broaden the search — show me more options',                refined_query_hint: 'broader' },
-					{ label: 'Just search anyway',                                       refined_query_hint: null },
-				],
-			},
-		],
-		max_turns_remaining: turns_remaining,
+		kind:         'clarification',
+		action:       'clarify_query',
+		instructions: `After reranking, no top result is a strong match. Ask the user one of \`context.suggested_questions\` using your agent's question mechanism (e.g. AskUserQuestion in Claude Code), then re-run search with the refined query and add --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: 'After reranking I still don\'t have a strong match. Could you narrow the scope a bit?',
+					options: [
+						{ label: 'Focus on a specific stack (Node / Python / Go / etc.)',  refined_query_hint: 'stack-specific' },
+						{ label: 'Focus on a specific platform (AWS / GCP / Vercel / etc.)', refined_query_hint: 'platform-specific' },
+						{ label: 'Broaden the search — show me more options',                refined_query_hint: 'broader' },
+						{ label: 'Just search anyway',                                       refined_query_hint: null },
+					],
+				},
+			],
 		},
+		principal_authorization_required: true,
 	}
 }
 
 // Envelope used when the LLM's ranking is malformed and we need to ask it
-// to re-emit. The CLI exits 0 — the protocol continues via the envelope.
-const build_retry_envelope = (query, reason, clarification_turns_used, retry_count) => ({
-	data:  null,
-	error: {
-		code:      'ranking_schema_mismatch',
-		message:   reason,
-		exit_code: 0,
-	},
-	next_step: {
-		action:       'retry_rank',
-		instructions: 'Your ranking failed validation. Re-emit a JSON object matching the `rerank_response_schema` from the original search response, then re-pipe to `happyskills postlex --query "<q>" --ranking -`. Max one retry — if it fails again, render the search results without rerank (the API\'s relevance_score order is the fallback).',
-		context: {
-			original_query:           query,
-			clarification_turns_used: clarification_turns_used | 0,
-			retry_count:              (retry_count | 0) + 1,
+// to re-emit. Returns the canonical six-key envelope (spec § 4) so postlex
+// can be unit-tested against the closed schema.
+const build_retry_envelope = (query, reason, clarification_turns_used, retry_count) => {
+	const { build_envelope } = require('../ui/envelope')
+	return build_envelope({
+		data: {},
+		error: {
+			code:    'RANKING_SCHEMA_MISMATCH',
+			message: reason,
+		},
+		next_step: {
+			kind:         'recovery',
+			action:       'retry_rank',
+			instructions: 'Your ranking failed validation. Re-emit a JSON object matching the `rerank_response_schema` from the original search response, then re-pipe to `happyskills postlex --query "<q>" --ranking -`. Max one retry — if it fails again, render the search results without rerank (the API\'s relevance_score order is the fallback).',
+			context: {
+				original_query:           query,
+				clarification_turns_used: clarification_turns_used | 0,
+				retry_count:              (retry_count | 0) + 1,
+			},
 		},
-	},
-})
+		meta_overrides: { command: 'postlex' },
+	})
+}
 
 // ─── I/O helpers ───────────────────────────────────────────────────────────
 
@@ -405,7 +414,10 @@ const run = (args) => catch_errors('Postlex failed', async () => {
 		process.stderr.write(`postlex: ${parse_error}\n`)
 		const env = build_retry_envelope(query, parse_error, clarification_turns_used, 0)
 		print_json(env)
-		return process.exit(EXIT_CODES.SUCCESS)
+		// Spec § 9.2 — process exit code must mirror meta.exit_code. The
+		// retry envelope carries error.code=RANKING_SCHEMA_MISMATCH which
+		// maps to a non-zero exit; honor that rather than forcing 0.
+		return process.exit(env.meta.exit_code)
 	}
 
 	// Validate per-item