happyskills 0.54.0 → 1.0.1

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.0.1] - 2026-06-01
+
+### Fixed
+
+- Fix the post-rerank clarification step in `postlex`: the `clarify_triggered` telemetry beacon and the text-mode clarification prompt checked for a `clarify` action and read `suggested_questions` at the wrong depth, but the command emits `clarify_query` with the questions nested under `next_step.context` — so neither fired. The `--json` envelope was already correct; this restores the CLI's own telemetry and human-readable clarification output.
+
+## [1.0.0] - 2026-05-29
+
+### Added
+
+- **Canonical six-key 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 canonical six-key response 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
@@ -157,14 +187,14 @@ This release combines two streams of work: **spec 260523-02 (Skill Update Determ
 ## [0.47.0] - 2026-05-21
 
 ### Added
-- Add `--with-rerank` flag to `happyskills search`. When set, the CLI passes `with_rerank_digests=true` to `POST /repos:search` (via `dispatch_search()`) and wraps the `--json` response in the universal envelope shape `{ data, error, next_step }`. The `data` payload gains four new fields alongside the existing `results`: `rerank_digests`, `rerank_system_prompt`, `rerank_prompt_version`, `rerank_response_schema`, plus `formulated_query`. `next_step.action` is one of `rank_digests_inline` (digests came back — agent ranks them and pipes to `postlex`), `clarify` (semantic match_notice fired and clarification budget remains — agent uses its native question mechanism with a calibrated narrowing question), or `present_to_user` (budget exhausted / non-semantic mode — render results). Silently ignored on non-semantic dispatches (slug-shape, scoped, exact). Combining `--with-rerank --exact` exits 2 (`USAGE_ERROR`). Intended for use inside an agentic session — see the `happyskills-help@0.3.0` skill's `references/discovery-protocol.md` for the envelope contract.
+- Add `--with-rerank` flag to `happyskills search`. When set, the CLI passes `with_rerank_digests=true` to `POST /repos:search` (via `dispatch_search()`) and wraps the `--json` response in the canonical six-key response envelope shape `{ data, error, next_step }`. The `data` payload gains four new fields alongside the existing `results`: `rerank_digests`, `rerank_system_prompt`, `rerank_prompt_version`, `rerank_response_schema`, plus `formulated_query`. `next_step.action` is one of `rank_digests_inline` (digests came back — agent ranks them and pipes to `postlex`), `clarify` (semantic match_notice fired and clarification budget remains — agent uses its native question mechanism with a calibrated narrowing question), or `present_to_user` (budget exhausted / non-semantic mode — render results). Silently ignored on non-semantic dispatches (slug-shape, scoped, exact). Combining `--with-rerank --exact` exits 2 (`USAGE_ERROR`). Intended for use inside an agentic session — see the `happyskills-help@0.3.0` skill's `references/discovery-protocol.md` for the envelope contract.
 - Add `--clarification-turns-used <N>` companion flag on `search`. Carries the clarification budget (0–2, default 0) across re-searches in the discovery protocol's clarification flow. The CLI clamps to the hard cap of 2 and emits `present_to_user` (instead of `clarify`) once the budget is spent.
 - Add new `happyskills postlex` subcommand — deterministic post-lex finalization for the discovery protocol. Takes the LLM's `ranking[]` JSON plus the original `data[]` array (from stdin via `--ranking -`, or from separate `--ranking <file>` + `--data <file>` paths), applies the canonical 30-line slug-overlap promotion algorithm, and emits a `next_step` envelope (`present_to_user` on success, `clarify` if the post-rerank top results are still weak and budget remains, `retry_rank` with an `input_template` when the ranking fails schema validation). Stateless — the agent carries all cross-call state via `--clarification-turns-used` and `next_step.context`. Human-readable output renders only the LLM-ranked subset (the unranked tail is not shown — the LLM chose not to rank those rows). Refuses to crash on out-of-range `candidate_id` values: invalid entries are dropped with a stderr warning; if every entry drops out, exit 1.
 - Add `cli/src/utils/slug_tokens.js` — STOP_TOKENS + `slug_tokens()` + `slug_token_set()` + `compute_lex_tier()`. Byte-identical mirror of `api/app/utils/slug_tokens.js`. The companion test (`slug_tokens.test.js`) cross-imports the API canonical version and asserts STOP_TOKENS set-equality in both directions — fails CI loud if either side drifts. This is the load-bearing invariant from spec 260521-01 v2 § 6: if the CLI's view of which candidate is "exact" disagrees with the API's slug-boost behavior, the post-lex stage promotes the wrong candidate (or none).
 - Add `cli/src/api/telemetry.js` — fire-and-forget client for `POST /telemetry/discovery`. 2-second `AbortController` timeout; all errors swallowed; never affects exit codes. Called from `search` (events `rerank_started` when emitting `rank_digests_inline`, `clarify_triggered` when emitting `clarify`, `clarify_completed` when re-running after a clarify cycle) and from `postlex` (event `rerank_completed` after the algorithm runs, plus `clarify_triggered` when emitting a post-rerank clarify). Server-side aggregation in CloudWatch Insights drives the two key signals: postlex fire rate (0.5%–5% target) and protocol completion rate (≥85% target — `count(rerank_completed)/count(rerank_started)`).
 
 ### Changed
-- `search --json` output is wrapped in the universal envelope `{ data, error, next_step }` when (and only when) `--with-rerank` is set. Plain `search --json` (without the flag) keeps its existing `{ data: { … } }` shape for backward compatibility — no consumer of the existing JSON contract sees a change.
+- `search --json` output is wrapped in the canonical six-key response envelope `{ data, error, next_step }` when (and only when) `--with-rerank` is set. Plain `search --json` (without the flag) keeps its existing `{ data: { … } }` shape for backward compatibility — no consumer of the existing JSON contract sees a change.
 - Argument parser (`parse_args` in `cli/src/index.js`) now treats a literal `-` as a flag value instead of as the prefix of another flag. This is the standard Unix stdin sentinel and lets `happyskills postlex --ranking -` parse correctly. Conservative change: `next.startsWith('-') && next !== '-'` is the new gate, so any flag whose value would previously have been swallowed and replaced with `true` because the next arg happened to be `-` now correctly receives `'-'`. No existing command relied on the previous behavior.
 
 ## [0.46.1] - 2026-05-20

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.54.0",
+	"version": "1.0.1",
 	"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 response 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

@@ -3,7 +3,7 @@
 // Surfaces:
 //   happyskills feedback <category> [body] [--subject "..."] [--attach a,b,c] [--json]
 //
-// --json mode emits the API's response wrapped in the universal CLI envelope:
+// --json mode emits the API's response wrapped in the canonical six-key response envelope:
 //   { data: { feedback, next_step, attachments? }, error: null }
 // The `next_step` envelope is what the `happyskills-help` skill reads to
 // route the post-creation conversation (offer attachment, etc.) — see spec
@@ -240,7 +240,7 @@ const run = (args) => catch_errors('Feedback command failed', async () => {
 	}
 
 	if (json_mode) {
-		// Universal CLI envelope shape. The skill's envelope-reader (per spec
+		// Canonical six-key response envelope shape. The skill's envelope-reader (per spec
 		// § 11) consumes `next_step` at the response root.
 		const data = { feedback, attachments }
 		print_json({ data, error: null, next_step })
@@ -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
 	}