happyskills 0.46.0 → 0.47.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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 `--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.
+- 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
+
+### Fixed
+- Fix `happyskills agents add` ignoring two categories of skills that should be mirrored into the newly added agent's folder: **kits** (skills with `type: kit` in the lock file — previously excluded by a copy-pasted "not agent-invocable" filter that conflated *invocation routing* with *filesystem presence*) and **locally-authored skills that were never published** (skills scaffolded via `happyskills init` and kept under source control but not pushed to the registry — they exist on disk in `.agents/skills/<name>/` but have no lock entry, so the lock-based enumeration missed them). The `add` subcommand now enumerates `.agents/skills/<name>/` directories directly, so anything physically present in the canonical location — regardless of whether it's lock-managed, a kit, or a private local-only skill — is symlinked into the new agent's folder.
+- Fix `happyskills agents remove` ignoring the same two categories — it previously read short names from the lock file, so a project containing kits or unpublished skills would leave dangling symlinks in the removed agent's folder. The subcommand now reads canonical names from `.agents/skills/<name>/` so every skill that could have been mirrored can also be unlinked.
+- Fix `happyskills agents list` undercounting the `Linked` column for the same reason — count is now against the canonical on-disk list so kits and unpublished skills are included.
+
 ## [0.46.0] - 2026-05-20
 
 ### Added

package/package.json

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

@@ -145,6 +145,10 @@ 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
 	const [errors, data] = await client.post('/repos:search', body, { auth: true })
 	if (errors) throw errors[errors.length - 1]
 	return data

package/src/api/telemetry.js

@@ -0,0 +1,37 @@
+// Fire-and-forget telemetry client for the discovery protocol.
+// Spec 260521-01 v2 § 5.3 — POST /telemetry/discovery accepts event-discriminated
+// payloads. The CLI fires these on protocol transitions; the API logs them as
+// structured CloudWatch events. Aggregation lives entirely in CloudWatch Insights.
+//
+// Invariants (spec § 6):
+//   - MUST NOT block the CLI's primary work. 2-second timeout, all errors swallowed.
+//   - MUST NOT affect exit codes. A network failure here is silently ignored.
+
+const { API_URL, CLI_VERSION } = require('../constants')
+
+const TELEMETRY_TIMEOUT_MS = 2000
+
+// fire_discovery_telemetry — POST a beacon. Returns a promise that always
+// resolves (never rejects) so callers can safely fire-and-forget without try/catch.
+const fire_discovery_telemetry = (payload) => {
+	const base = process.env.HAPPYSKILLS_API_URL || API_URL
+	const body = JSON.stringify({
+		client:     `happyskills-cli@${CLI_VERSION}`,
+		agent_hint: null,
+		...payload,
+	})
+
+	const controller = new AbortController()
+	const timer = setTimeout(() => controller.abort(), TELEMETRY_TIMEOUT_MS)
+
+	return fetch(`${base}/telemetry/discovery`, {
+		method:  'POST',
+		headers: { 'content-type': 'application/json' },
+		body,
+		signal:  controller.signal,
+	})
+		.catch(() => {})  // swallow network errors, abort errors, etc.
+		.finally(() => clearTimeout(timer))
+}
+
+module.exports = { fire_discovery_telemetry }

package/src/commands/agents.js

@@ -11,7 +11,7 @@ const { find_project_root, lock_root, skills_dir, skill_install_dir, agent_skill
 const { print_help, print_json, print_success, print_warn, print_info, print_table, code } = require('../ui/output')
 const { green, dim } = require('../ui/colors')
 const { exit_with_error, UsageError } = require('../utils/errors')
-const { EXIT_CODES, SKILL_TYPES } = require('../constants')
+const { EXIT_CODES } = require('../constants')
 
 const HELP_TEXT = `Usage: happyskills agents <subcommand> [args] [options]
 
@@ -63,26 +63,70 @@ const _parse_agent_ids = (raw_args) => {
 }
 
 /**
- * For each installed skill, decide whether it should be mirrored into the
- * newly added agent. A skill is mirrored when it is currently enabled — i.e.,
- * a symlink for it exists in at least one *other* already-configured agent.
+ * Enumerate every skill physically present in the canonical .agents/skills/
+ * directory for the given scope. Covers all three categories of "skill that
+ * lives in this project":
+ *   1. Lock-managed skills (installed from the registry)
+ *   2. Kits (lock-managed or not — kits have a SKILL.md without frontmatter,
+ *      so a frontmatter-aware scan would miss them; we enumerate directories
+ *      directly to catch them)
+ *   3. Locally-authored skills that were created via `happyskills init` but
+ *      never published — they exist on disk but have no lock entry
  *
- * When no other agent folders exist yet (fresh project bootstrap), every
- * non-kit installed skill is mirrored.
+ * Returns short directory names (e.g. "deploy-aws"), not owner-qualified names.
+ */
+const _list_canonical_skill_names = async (is_global, project_root) => {
+	const base_dir = skills_dir(is_global, project_root)
+	try {
+		const entries = await fs.promises.readdir(base_dir, { withFileTypes: true })
+		return entries
+			.filter(e => (e.isDirectory() || e.isSymbolicLink()) && !e.name.startsWith('.'))
+			.map(e => e.name)
+	} catch {
+		return []
+	}
+}
+
+/**
+ * Build a short-name → display-name map from the lock file so on-disk skills
+ * that happen to be lock-managed are shown with their owner-qualified name.
+ * Skills not in the lock fall back to their short directory name.
+ */
+const _build_display_name_map = (lock_data) => {
+	const lock_skills = get_all_locked_skills(lock_data)
+	const map = new Map()
+	for (const full_name of Object.keys(lock_skills)) {
+		const short = full_name.split('/')[1] || full_name
+		map.set(short, full_name)
+	}
+	return map
+}
+
+/**
+ * For each skill physically present in the canonical .agents/skills/ directory,
+ * decide whether it should be mirrored into the newly added agent. A skill is
+ * mirrored when it is currently enabled — i.e., a symlink for it exists in at
+ * least one *other* already-configured agent.
+ *
+ * When no other agent folders exist yet (fresh project bootstrap), every skill
+ * present on disk is mirrored.
+ *
+ * Includes kits (which have SKILL.md without frontmatter — still need agent
+ * symlinks for filesystem parity) AND locally-authored skills that were never
+ * published (no lock entry, but legitimate project skills).
  */
 const _select_skills_to_mirror = async (lock_data, is_global, project_root, new_agent) => {
-	const all = get_all_locked_skills(lock_data)
-	const installed = Object.entries(all).filter(([, data]) => data && data.type !== SKILL_TYPES.KIT)
+	const display_names = _build_display_name_map(lock_data)
+	const candidates = await _list_canonical_skill_names(is_global, project_root)
 
-	// Find any *other* agents that are already configured in this scope
 	const [, all_detected] = await detect_agents({ global: is_global, project_root })
 	const other_detected = (all_detected || []).filter(a => a.id !== new_agent.id)
 
 	const selected = []
 	const skipped_disabled = []
 
-	for (const [full_name, data] of installed) {
-		const short = full_name.split('/')[1] || full_name
+	for (const short of candidates) {
+		const full_name = display_names.get(short) || short
 
 		if (other_detected.length === 0) {
 			selected.push({ full_name, short })
@@ -105,7 +149,6 @@ const _add = async (raw_args, args) => {
 	const base_dir = skills_dir(is_global, project_root)
 
 	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
-	const has_lock = !!(lock_data && lock_data.skills && Object.keys(lock_data.skills).length > 0)
 
 	const per_agent = []
 
@@ -113,11 +156,6 @@ const _add = async (raw_args, args) => {
 		const target_root = agent_skills_dir(agent, is_global, project_root)
 		await fs.promises.mkdir(target_root, { recursive: true })
 
-		if (!has_lock) {
-			per_agent.push({ agent_id: agent.id, status: 'configured', linked: [], skipped_disabled: [] })
-			continue
-		}
-
 		const { selected, skipped_disabled } = await _select_skills_to_mirror(lock_data, is_global, project_root, agent)
 		const linked = []
 
@@ -160,9 +198,7 @@ const _remove = async (raw_args, args) => {
 	const project_root = find_project_root()
 	const is_json = args.flags.json || false
 
-	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
-	const all = get_all_locked_skills(lock_data)
-	const short_names = Object.keys(all).map(k => k.split('/')[1] || k)
+	const short_names = await _list_canonical_skill_names(is_global, project_root)
 
 	const per_agent = []
 
@@ -235,9 +271,7 @@ const _list = async (args) => {
 	const [, detected] = await detect_agents({ global: is_global, project_root })
 	const detected_ids = new Set((detected || []).map(a => a.id))
 
-	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
-	const all = get_all_locked_skills(lock_data)
-	const short_names = Object.keys(all).map(k => k.split('/')[1] || k)
+	const short_names = await _list_canonical_skill_names(is_global, project_root)
 
 	const rows = []
 	for (const agent of AGENTS) {

package/src/commands/postlex.js

@@ -0,0 +1,402 @@
+// happyskills postlex — apply deterministic post-lex slug-overlap promotion
+// to an LLM-emitted ranking, then emit a `next_step` envelope telling the
+// agent what to do next.
+//
+// Spec 260521-01 v2 § 5.2 — this command is the deterministic safety net
+// for the rerank protocol. Frontier model emits ranking → postlex finalizes
+// → agent renders. The envelope makes the protocol legible to the agent
+// without piling conditional logic into SKILL.md.
+
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const fs = require('fs')
+const { print_help, print_table, print_json } = require('../ui/output')
+const { bold, dim, cyan, yellow, gray } = require('../ui/colors')
+const { exit_with_error, UsageError, CliError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+const { slug_token_set, compute_lex_tier } = require('../utils/slug_tokens')
+const { fire_discovery_telemetry } = require('../api/telemetry')
+
+const HELP_TEXT = `Usage: happyskills postlex --query <q> --ranking <file|-> [options]
+
+Apply deterministic slug-overlap promotion to an LLM-emitted ranking and
+print the final ordering. Intended for use inside the rerank protocol —
+the LLM ranks candidates returned by \`happyskills search --with-rerank\`,
+then pipes the result here for the deterministic finalization step.
+
+The command emits a \`next_step\` envelope describing what the agent should
+do next. See references/discovery-protocol.md in the happyskills-help skill
+for the full envelope contract.
+
+Required:
+  --query <q>                 The original search query (used for slug-overlap)
+  --ranking <file|->          Path to the ranking JSON, or \`-\` for stdin
+
+Optional:
+  --data <file>               Separate data file (when --ranking does not embed it)
+  --clarification-turns-used <N>
+                              Clarification budget already spent (0-2, default 0)
+  --original-query <q>        Original user query (opaque context from prior step)
+  --json                      Output as JSON (default: human-readable table)
+
+Input shape (stdin or --ranking file):
+  { "ranking": [{ "rank": 1, "candidate_id": 5, "rationale": "..." }, ...],
+    "data":    [{ "name": "...", "workspace_slug": "...", ... }, ...] }
+
+Examples:
+  echo '{"ranking":[...],"data":[...]}' | happyskills postlex --query "deploy aws" --ranking -
+  happyskills postlex --query "deploy aws" --ranking r.json --data d.json --json`
+
+// ─── Pure logic — exported for unit testing ────────────────────────────────
+
+// Validate the ranking shape. Returns { valid_items, dropped } — invalid
+// entries are dropped with a reason rather than crashing.
+const validate_ranking = (ranking, data) => {
+	const valid_items = []
+	const dropped = []
+	if (!Array.isArray(ranking)) return { valid_items, dropped: [{ reason: 'ranking is not an array' }] }
+	if (!Array.isArray(data))    return { valid_items, dropped: [{ reason: 'data is not an array' }] }
+	for (const item of ranking) {
+		if (!item || typeof item !== 'object') {
+			dropped.push({ item, reason: 'not an object' })
+			continue
+		}
+		const cid = item.candidate_id
+		if (!Number.isInteger(cid) || cid < 1 || cid > data.length) {
+			dropped.push({ candidate_id: cid, reason: 'candidate_id out of range' })
+			continue
+		}
+		const row = data[cid - 1]
+		if (!row || typeof row.name !== 'string' || !row.name) {
+			dropped.push({ candidate_id: cid, reason: 'data row missing name' })
+			continue
+		}
+		valid_items.push(item)
+	}
+	return { valid_items, dropped }
+}
+
+// The canonical 30-line post-lex algorithm. Pure. Returns an object capturing
+// the reorder + telemetry signal — callers join with `data` to render.
+const apply_postlex = (query, ranking, data) => {
+	const q = slug_token_set(query)
+	const top10 = ranking.slice(0, 10).map(item => ({
+		...item,
+		_name: data[item.candidate_id - 1].name,
+	}))
+	const exact = top10
+		.map(r => ({ r, tier: compute_lex_tier(q, slug_token_set(r._name)) }))
+		.filter(x => x.tier === 'exact')
+		.sort((a, b) => a.r.rank - b.r.rank)
+	const exact_match_count_in_window = exact.length
+	if (exact.length === 0 || exact[0].r.rank === 1) {
+		return { reordered: ranking, promoted: false, promoted_from_rank: null, exact_match_count_in_window }
+	}
+	const winner_id = exact[0].r.candidate_id
+	const winner_idx = ranking.findIndex(x => x.candidate_id === winner_id)
+	const promoted_from_rank = ranking[winner_idx]?.rank ?? null
+	const reordered = [...ranking]
+	const [moved] = reordered.splice(winner_idx, 1)
+	reordered.unshift(moved)
+	return {
+		reordered: reordered.map((x, i) => ({ ...x, rank: i + 1 })),
+		promoted: true,
+		promoted_from_rank,
+		exact_match_count_in_window,
+	}
+}
+
+// Join the reordered ranking with the data rows. Output is the user-facing
+// `final_ordering` — only the rows the LLM included in its ranking.
+const build_final_ordering = (reordered, data) =>
+	reordered.map(item => {
+		const row = data[item.candidate_id - 1]
+		return {
+			rank:           item.rank,
+			candidate_id:   item.candidate_id,
+			slug:           row.workspace_slug ? `${row.workspace_slug}/${row.name}` : row.name,
+			name:           row.name,
+			workspace_slug: row.workspace_slug || null,
+			description:    row.description || '',
+			version:        row.latest_version || row.version || '-',
+			match_quality:  row.match_quality || null,
+			quality_score:  row.quality_score != null ? row.quality_score : null,
+			star_count:     row.star_count || 0,
+			rationale:      item.rationale || '',
+		}
+	})
+
+const STRONG_TIERS = new Set(['strong', 'good'])
+
+// Decide which envelope to emit based on the top-3 of final_ordering and the
+// clarification budget. Returns a `next_step` object (or null when no protocol
+// applies).
+const determine_next_step = (final_ordering, query, clarification_turns_used) => {
+	const top3 = final_ordering.slice(0, 3)
+	const all_strong = top3.length > 0 && top3.every(r => STRONG_TIERS.has(r.match_quality))
+	const turns_used = Math.max(0, Math.min(2, clarification_turns_used | 0))
+	const turns_remaining = 2 - turns_used
+
+	if (all_strong || final_ordering.length === 0) {
+		return {
+			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,
+		}
+	}
+
+	if (turns_remaining <= 0) {
+		return {
+			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,
+		}
+	}
+
+	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,
+		context: {
+			original_query:           query,
+			clarification_turns_used: turns_used,
+		},
+	}
+}
+
+// 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,
+		},
+	},
+})
+
+// ─── I/O helpers ───────────────────────────────────────────────────────────
+
+const read_stdin_sync = () => {
+	try {
+		return fs.readFileSync(0, 'utf8')
+	} catch {
+		return ''
+	}
+}
+
+const parse_input = (raw_ranking_input, raw_data_input) => {
+	// Accept either combined `{ranking, data}` from stdin/one file, or
+	// separate `{ranking: ...}`/`{data: ...}` (or bare arrays) from two files.
+	const parse_one = (raw, label) => {
+		if (raw == null || raw === '') return { value: null, parse_error: `${label} input is empty` }
+		try {
+			return { value: JSON.parse(raw), parse_error: null }
+		} catch (parse_err) {
+			return { value: null, parse_error: `${label} is not valid JSON: ${parse_err.message}` }
+		}
+	}
+
+	const ranking_parse = parse_one(raw_ranking_input, 'ranking')
+	if (ranking_parse.parse_error) return { ranking: null, data: null, parse_error: ranking_parse.parse_error }
+
+	const ranking_obj = ranking_parse.value
+
+	let ranking = null
+	let data = null
+
+	if (Array.isArray(ranking_obj)) {
+		ranking = ranking_obj
+	} else if (ranking_obj && typeof ranking_obj === 'object') {
+		ranking = Array.isArray(ranking_obj.ranking) ? ranking_obj.ranking : null
+		if (Array.isArray(ranking_obj.data)) data = ranking_obj.data
+	}
+
+	if (raw_data_input != null) {
+		const data_parse = parse_one(raw_data_input, 'data')
+		if (data_parse.parse_error) return { ranking, data, parse_error: data_parse.parse_error }
+		const data_obj = data_parse.value
+		if (Array.isArray(data_obj)) data = data_obj
+		else if (data_obj && Array.isArray(data_obj.data)) data = data_obj.data
+		else return { ranking, data: null, parse_error: 'data file does not contain a data array' }
+	}
+
+	if (!Array.isArray(ranking)) return { ranking: null, data, parse_error: 'ranking field is missing or not an array' }
+	if (!Array.isArray(data))    return { ranking, data: null, parse_error: 'data field is missing or not an array' }
+	return { ranking, data, parse_error: null }
+}
+
+const read_file = (path) => {
+	try {
+		return { content: fs.readFileSync(path, 'utf8'), err: null }
+	} catch (read_err) {
+		return { content: null, err: read_err.message }
+	}
+}
+
+const MATCH_QUALITY_LABELS = {
+	strong:  { label: 'Strong match',  color: cyan },
+	good:    { label: 'Good match',    color: cyan },
+	partial: { label: 'Partial match', color: yellow },
+	weak:    { label: 'Weak match',    color: yellow },
+}
+
+const format_human_row = (row) => {
+	const match = row.match_quality ? MATCH_QUALITY_LABELS[row.match_quality] : null
+	const match_str = match ? match.color(match.label) : ''
+	const stars_str = `★ ${row.star_count}`
+	const meta_parts = [match_str, stars_str].filter(Boolean).join(' · ')
+
+	const num = `  ${String(row.rank).padStart(2)}. `
+	const name_and_meta = `${bold(row.slug)}${meta_parts ? `  ${dim(meta_parts)}` : ''}`
+	const desc = row.description ? `      ${row.description}` : ''
+	const rationale = row.rationale ? `      ${dim('Why: ' + row.rationale)}` : ''
+	const lines = [`${num}${name_and_meta}`]
+	if (desc) lines.push(desc)
+	if (rationale) lines.push(rationale)
+	return lines.join('\n')
+}
+
+// ─── Orchestration ─────────────────────────────────────────────────────────
+
+const run = (args) => catch_errors('Postlex failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const query                       = args.flags.query
+	const ranking_path                = args.flags.ranking
+	const data_path                   = args.flags.data
+	const clarification_turns_used    = parseInt(args.flags['clarification-turns-used'] || '0', 10) || 0
+
+	if (!query || typeof query !== 'string')
+		throw new UsageError('--query is required.')
+	if (!ranking_path || typeof ranking_path !== 'string')
+		throw new UsageError('--ranking is required (path to file, or `-` for stdin).')
+
+	// Read inputs
+	const raw_ranking = ranking_path === '-'
+		? read_stdin_sync()
+		: (() => {
+			const r = read_file(ranking_path)
+			if (r.err) throw new UsageError(`Cannot read --ranking file: ${r.err}`)
+			return r.content
+		})()
+	const raw_data = data_path
+		? (() => {
+			const r = read_file(data_path)
+			if (r.err) throw new UsageError(`Cannot read --data file: ${r.err}`)
+			return r.content
+		})()
+		: null
+
+	// Parse
+	const { ranking, data, parse_error } = parse_input(raw_ranking, raw_data)
+	if (parse_error) {
+		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)
+	}
+
+	// Validate per-item
+	const { valid_items, dropped } = validate_ranking(ranking, data)
+	for (const d of dropped) {
+		process.stderr.write(`postlex: dropping ranking entry — ${d.reason}${d.candidate_id != null ? ` (candidate_id=${d.candidate_id})` : ''}\n`)
+	}
+	if (valid_items.length === 0) {
+		throw new CliError('No candidates matched the data array — every ranking entry was dropped.', EXIT_CODES.ERROR)
+	}
+
+	// Apply algorithm
+	const { reordered, promoted, promoted_from_rank, exact_match_count_in_window } =
+		apply_postlex(query, valid_items, data)
+	const final_ordering = build_final_ordering(reordered, data)
+
+	// Decide next_step
+	const next_step = determine_next_step(final_ordering, query, clarification_turns_used)
+
+	// Fire telemetry — rerank_completed first (the rerank step succeeded);
+	// clarify_triggered separately if applicable.
+	fire_discovery_telemetry({
+		event:                       'rerank_completed',
+		query,
+		promoted,
+		promoted_from_rank,
+		exact_match_count_in_window,
+	})
+	if (next_step.action === 'clarify') {
+		fire_discovery_telemetry({
+			event:        'clarify_triggered',
+			query,
+			reason:       'post_rerank_weak',
+			turn_number:  clarification_turns_used + 1,
+		})
+	}
+
+	// Emit envelope
+	const envelope = {
+		data: {
+			final_ordering,
+			postlex_promoted:            promoted,
+			promoted_from_rank,
+			exact_match_count_in_window,
+			formulated_query:            query,
+		},
+		error: null,
+		next_step,
+	}
+
+	if (args.flags.json) {
+		print_json(envelope)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	// Human-readable output
+	console.log(`\n${bold(`Reranked results for: "${query}"`)}\n`)
+	if (promoted) {
+		console.log(`  ${dim(`(post-lex promoted exact slug match from rank ${promoted_from_rank} → 1)`)}\n`)
+	}
+	final_ordering.forEach((row, i) => {
+		console.log(format_human_row(row))
+		if (i < final_ordering.length - 1) console.log('')
+	})
+	if (next_step.action === 'clarify') {
+		console.log(`\n  ${yellow('No top result is a strong match. Suggested clarification:')}`)
+		console.log(`  ${dim(next_step.suggested_questions[0].question)}`)
+	} else if (next_step.action === 'present_to_user' && !final_ordering.slice(0, 3).every(r => STRONG_TIERS.has(r.match_quality))) {
+		console.log(`\n  ${yellow('No top result is a strong match (clarification budget spent).')}`)
+	}
+	console.log(`\n${gray(`Showing ${final_ordering.length} result${final_ordering.length === 1 ? '' : 's'}.`)}\n`)
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = {
+	run,
+	// Exported for unit testing — pure functions only.
+	validate_ranking,
+	apply_postlex,
+	build_final_ordering,
+	determine_next_step,
+	build_retry_envelope,
+	parse_input,
+}