happyskills 0.48.0 → 0.50.0

package/CHANGELOG.md

@@ -7,6 +7,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.50.0] - 2026-05-24
+
+### Added
+
+- **New `feedback` command** — `happyskills feedback <category> [body] [--subject "..."] [--attach a,b,c] [--json]`. Lodge a bug report, feature wish, compliment, question, or other feedback against the HappySkills platform from the terminal. Five categories: `bug | wish | compliment | question | other`. The body can be supplied inline or omitted to open `$EDITOR` (vim / nano fallback) — same UX as `git commit`. Optional `--subject` (≤ 200 chars) and `--attach` (comma-separated image paths, max 10, PNG/JPEG accepted on the CLI). Auto-captures `cli_version`, `node_version`, `os`, `arch`, `cwd_is_skill_dir`, and `current_skill` (read from a local `skill.json` if present) into the API's silent `client_context`, with secrets scrubbed before sending. `--json` emits the `{ data: { feedback, attachments }, error: null, next_step }` envelope at the response root — the `next_step` is what the `happyskills-help` skill reads to offer the post-creation attachment follow-up.
+- **Image attachments via cherry-picked jimp 1.x** — `cli/src/utils/image_compression.js` compresses each `--attach` file to ≤ 2000 px longest side / JPEG quality 80 / ≤ 1 MB before upload via the two-step pre-signed S3 flow. Uses `@jimp/core` + `@jimp/js-jpeg` + `@jimp/js-png` + `@jimp/plugin-resize` cherry-picked from the jimp 1.x family — NOT the `jimp` meta-package (which pulls in BMP, GIF, TIFF, blur, color, mask, threshold, dither, print, and a dozen other plugins we don't need). WebP is not supported on the CLI in this release (jimp 1.x ships no WebP codec); the web modal still accepts WebP via `browser-image-compression`. **Lazy-loaded**: jimp is only `require()`d when at least one `--attach` is provided, so every other CLI command (`install`, `search`, `publish`, etc.) pays zero require cost. An early-bail check after compression rejects images that still exceed 1 MB with a clean local error before any initiate round-trip.
+- **New `cli/src/api/feedback.js`** — API client for the new `/feedback` endpoints: `create_feedback`, `initiate_attachment_upload`, `put_attachment_to_s3`, `complete_attachment_upload`, `list_feedback`, `get_feedback`. Follows the existing per-resource module pattern (`api/repos.js`, `api/auth.js`, etc.).
+- **New `cli/src/utils/scrub_secrets.js`** — recursively scrubs OpenAI keys (`sk-…`), GitHub tokens (`ghp_…` / `gho_…`), Cognito JWT-shaped strings (`eyJ…`), and any value whose key matches `/(_TOKEN|_KEY|_SECRET|_PASSWORD|_API_KEY)$/i` before `client_context` leaves the CLI. Applied automatically by the feedback command; reusable from any future command that captures user environment data. Mirror of `web/src/lib/scrub-secrets.js` — the regexes must stay in sync.
+
+### Changed
+
+- **All API calls now send `User-Agent: happyskills-cli/<version>`** (`cli/src/api/client.js`). Required so the API can derive `feedback.source = 'cli'` server-side and never trust the source from the request body. No behaviour change for existing endpoints — none of them inspect User-Agent today; this is forward-compatible plumbing for any future endpoint that wants to know who's calling.
+- **Install size increased from 5.1 MB → ~15 MB** due to jimp 1.x's transitive deps (`zod` 5 MB for runtime type checks; `bare-fs`/`bare-os`/`bare-url` 3.6 MB combined for Bare-runtime polyfills). The cherry-pick keeps jimp itself to 1.4 MB on disk, but the dependency closure dominates. This violates the original spec § 8.3's 8 MB target — accepted as a deliberate trade-off because: (a) **cold-start cost is unaffected** (lazy require means non-feedback commands never load jimp); (b) `npm install -g happyskills` install cost is paid once per machine, not per invocation; (c) the mission-aligned goal of "friction is the enemy of getting feedback at all" outweighs install footprint. A follow-up could investigate shelling out to system `sips` / `magick` to shrink the install — flagged but not in this release.
+
+### Notes
+
+- New gotcha entries documenting browser-direct-to-S3 patterns (signed Content-Type on PUT, response-Content-Type override on GET, SDK v3.729+ checksum opt-out, bucket CORS as CSRF guard) were added to `docs/gotchas/aws-sdk.md` in the same monorepo change set. These pertain to the API and infra; mentioned here for context since the CLI's `--attach` flow is the other client of that pipeline.
+
+## [0.49.0] - 2026-05-23
+
+This release combines two streams of work: **spec 260523-02 (Skill Update Determinism)** which introduces four new CLI primitives plus an `ahead` status to make skill update flows deterministic and safe-to-attempt, AND a **bundle-size enforcement** pass that adds a total-bundle cap to pre-publish validation.
+
+### Added
+
+#### Determinism primitives (spec 260523-02)
+
+- **New `snapshot` command** — capture and restore skill state. Subcommands: `create`, `list`, `restore`, `delete`, `prune`. Snapshots live under `.happyskills/snapshots/<workspace>/<skill>/<snapshot_id>/` and contain a full directory copy plus the lock entry. Default retention 10 per skill; auto-prune on create; configurable via `--keep <n>`. Atomic restore via filesystem rename. Surfaced as the safety net for every non-trivial mutation in the new primitives below.
+- **New `reconcile` command** — deterministic drift repair. Diagnoses the drift subtype and either fixes it on the spot (with `--apply <action>`) or emits a structured `next_step` envelope for operator adjudication. **No-ops on `ahead`** (disk version > lock — that's normal authoring, not drift). Replaces the prose drift-repair procedure that previously routed through `install --fresh`.
+- **New `release` command** — atomic release pipeline. Wraps snapshot + validate + bump (when needed) + changelog verification + publish + lock update + snapshot cleanup as a single deterministic CLI invocation. Recognizes the `ahead` state directly: when `skill.json` is already ahead of lock, the disk version IS the version to publish — no revert, no re-bump. On any failure restores the snapshot and returns a structured `next_step` envelope (`fix_validation_errors`, `specify_bump_type`, `provide_changelog`, `pull_rebase_first`, `specify_workspace`, `reconcile_first`, `resolve_bump_disagreement`).
+- **New `pull --rebase` flag** — snapshot-backed rebase-style pull. Captures local edits as patches, fast-forwards to the registry head, reapplies the patches. On rejection emits a structured envelope with per-file expected/actual context so an operator (LLM) can produce a corrected patch without re-reading the entire file. The standard 3-way merge mode remains the default.
+
+#### Status taxonomy (spec 260523-02 § 10.5)
+
+- **New `ahead` top-level status** in `list`, `status`, and `check` JSON envelopes. Indicates the normal authoring-ahead state (disk version > lock version) — the author has bumped locally and not yet published. Carries an `ahead: { lock_version, disk_version, has_changelog_entry, changelog_version }` object. Replaces the previous false-positive `drift.version_mismatch` classification for this case.
+- **Narrowed `drift` reasons.** The previous `version_mismatch` reason is removed; `drift.reason` now ranges over `regression` (disk semver-LESS than lock), `missing_skill_json`, and `missing_dir`. Drift is now strictly genuine inconsistency in the local install record.
+
+#### `install --fresh` hardening (spec 260523-02 § 8.5)
+
+- **Pre-flight version-existence check.** Before any disk mutation, `install <skill>@<version> --fresh` calls the registry to confirm `<version>` exists. If not (or registry unreachable), hard-fails with `USAGE_ERROR` (exit 2) and a `VERSION_NOT_FOUND` message. **Closes the silent-fallback footgun** documented in spec 260523-02 § 2.3 — previously the CLI quietly installed the latest published version when the requested version was missing, with no error envelope.
+- **Snapshot-first.** When the skill directory exists, `--fresh` now captures a snapshot before wiping and exposes `data.snapshot_id` in the success response so the operator can restore manually if needed.
+- **New `--force-discard-local` flag.** When the skill directory has local edits (integrity hash differs from `base_integrity`), `--fresh` refuses with `LOCAL_EDITS_PRESENT` (exit 2) unless `--force-discard-local` is passed. Makes the "throw away my edits" intent explicit.
+
+#### Bundle-size enforcement
+
+- **New `cli/src/config/limits.js`** — single source of truth for the size limits enforced before publish. Exports `MAX_FILE_SIZE` (1 MB per file) and `MAX_TOTAL_SIZE` (1 MB total bundle). The header comment pins this file as the mirror of `api/app/config/limits.js`; drift between the two will cause the API to reject a publish that the CLI just told the user was fine, so they must be bumped together.
+- **New `max_total_size` validation rule** in `cli/src/validation/file_size_rules.js`. The rule sums the bytes of every non-hidden, non-`node_modules` file under the skill directory and fails pre-publish validation when the total exceeds `MAX_TOTAL_SIZE`. Previously only the per-file `max_file_size` rule existed — a skill made of many sub-1 MB files whose total exceeded the bundle cap would pass `happyskills validate` locally and only fail server-side at `POST /push/initiate` with a `PAYLOAD_TOO_LARGE`. The new rule surfaces the same verdict locally with a clearer message (`"Skill bundle exceeds 1MB limit (X.XX MB)"`) before any presigned-URL or upload work happens.
+
+### Changed
+
+- **`bump` no longer touches the lock file** (spec 260523-02 § 8.6). Previously `bump` updated both `skill.json` and the lock entry atomically. Under the new lock-as-registry-view principle, a local bump is not a registry interaction — the lock catches up at publish time, atomically with registry acceptance. After bump, the skill enters the `ahead` state until the next publish. Hand-editing `skill.json`'s version field is now functionally equivalent to `bump` for the lock contract (both produce `ahead`); `bump` retains its ergonomic advantages (validation, semver arithmetic, remote-exists warning) but is no longer privileged for correctness.
+- **`publish` now writes the lock file on first publish.** Previously the lock-write block was gated on an existing lock file; in fresh projects (no lock yet), first publish succeeded against the registry but left no local lock entry, causing downstream `list`/`status`/`check` to treat the just-published skill as external. Now `publish` initializes a new lock structure if none exists and persists the new entry atomically.
+- **`list`/`status`/`check` human output** updated to surface the `ahead` state distinctly from `drift`. Stale guidance pointing users at `install --fresh` for drift repair replaced with pointers to `reconcile`.
+- **`pull.js`** dispatches to a new `merge/rebase.js` module when `--rebase` is set; the existing 3-way merge mode is unchanged.
+- **`cli/src/validation/file_size_rules.js`** no longer hardcodes its own `1 * 1024 * 1024` literal — it imports `MAX_FILE_SIZE` and `MAX_TOTAL_SIZE` from `cli/src/config/limits.js`. Same numeric behavior for the per-file rule; the user-facing message now interpolates the limit from the constant rather than reading "1MB" verbatim, so a future bump only requires editing the config file.
+- **CLI registers four new commands** in `constants.js` (`snapshot`, `reconcile`, `release`, plus the `pull --rebase` flag on the existing `pull` command). `index.js` help text updated to surface them.
+
+### Fixed
+
+- **Silent first-publish lock-creation bug.** `publish.js`'s lock-write was wrapped in `if (!lock_err && lock_data)` so a fresh project (no lock file) silently never created one even after a successful registry publish. The newly-published skill then appeared as `external` in `list` output. Unrelated to spec 260523-02 in origin but surfaced during its E2E verification.
+
+### Notes for skill authors
+
+- The CLI status taxonomy change is observable: code that depended on `drift.reason === "version_mismatch"` should now branch on `status === "ahead"` for the disk > lock case, or on `drift.reason === "regression"` for disk < lock. All first-party HappySkills skills (`happyskills`, `happyskills-publish`, `happyskills-sync`) have been updated and require this CLI version or newer (`requires.happyskills >= 0.49.0`).
+- The `bump` behavior change is observable but strictly safer. No documented contract was broken: bump's lock-update was internal bookkeeping, not a published interface. Third-party code that depended on `bump` keeping the lock in sync should switch to `release` (which performs the atomic update at publish time as designed).
+- `install --fresh @<missing-version>` previously succeeded with a silent fallback; it now fails fast. Strictly safer — any legitimate caller is rare and would benefit from the explicit error.
+
 ## [0.48.0] - 2026-05-22
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.48.0",
+	"version": "0.50.0",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",
@@ -43,6 +43,10 @@
 		"node": ">=22.0.0"
 	},
 	"dependencies": {
+		"@jimp/core": "^1.6.0",
+		"@jimp/js-jpeg": "^1.6.0",
+		"@jimp/js-png": "^1.6.0",
+		"@jimp/plugin-resize": "^1.6.0",
 		"node-diff3": "^3.2.0",
 		"puffy-core": "^1.3.1",
 		"semver": "^7.6.0",

package/src/api/client.js

@@ -1,15 +1,18 @@
 const { createHash } = require('crypto')
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
-const { API_URL } = require('../constants')
+const { API_URL, CLI_VERSION } = require('../constants')
 const { ApiError, NetworkError, AuthError } = require('../utils/errors')
 const { load_token } = require('../auth/token_store')
 
 const get_base_url = () => process.env.HAPPYSKILLS_API_URL || API_URL
+const USER_AGENT = `happyskills-cli/${CLI_VERSION}`
 
 const request = (method, path, options = {}) => catch_errors(`API ${method} ${path} failed`, async () => {
 	const { body, auth = true, raw_response = false, unwrap = true, headers: extra_headers = {} } = options
 	const url = `${get_base_url()}${path}`
-	const headers = { ...extra_headers }
+	// User-Agent enables the API to identify CLI traffic (e.g. feedback API
+	// derives `source = 'cli'` from this header). Spec 260524-01 § 12.
+	const headers = { 'User-Agent': USER_AGENT, ...extra_headers }
 
 	if (auth) {
 		const [, token_data] = await load_token()

package/src/api/feedback.js

@@ -0,0 +1,71 @@
+// Spec 260524-01 — CLI client for the /feedback API.
+//
+// Returns the full response (envelope unwrapped to `data`) for `create` so the
+// caller can access the `next_step` envelope baked into the API response. The
+// attachment endpoints unwrap normally — callers only need the payload.
+
+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 } }`.)
+const create_feedback = (payload) => catch_errors('Create feedback failed', async () => {
+	const [errors, data] = await client.post('/feedback', payload)
+	if (errors) throw errors[errors.length - 1]
+	return data   // { feedback, next_step }
+})
+
+const initiate_attachment_upload = (feedback_id, payload) => catch_errors('Initiate attachment upload failed', async () => {
+	const [errors, data] = await client.post(`/feedback/${feedback_id}/attachments/initiate`, payload)
+	if (errors) throw errors[errors.length - 1]
+	return data   // { upload_id, storage_key, upload_url, expires_at, original_name }
+})
+
+const complete_attachment_upload = (feedback_id, payload) => catch_errors('Complete attachment upload failed', async () => {
+	const [errors, data] = await client.post(`/feedback/${feedback_id}/attachments/complete`, payload)
+	if (errors) throw errors[errors.length - 1]
+	return data   // { attachment }
+})
+
+const put_attachment_to_s3 = (presigned_url, buffer) => catch_errors('S3 attachment upload failed', async () => {
+	const res = await fetch(presigned_url, {
+		method: 'PUT',
+		body: buffer,
+		headers: {
+			'Content-Type': 'image/jpeg',
+			'Content-Length': buffer.length.toString()
+		}
+	})
+	if (!res.ok) {
+		const text = await res.text().catch(() => '')
+		throw new Error(`S3 PUT failed with status ${res.status}${text ? ': ' + text.slice(0, 200) : ''}`)
+	}
+})
+
+const list_feedback = (query = {}) => catch_errors('List feedback failed', async () => {
+	const params = new URLSearchParams()
+	if (query.limit != null) params.set('limit', String(query.limit))
+	if (query.offset != null) params.set('offset', String(query.offset))
+	if (query.category) params.set('category', query.category)
+	if (query.status) params.set('status', query.status)
+	const qs = params.toString()
+	const [errors, data] = await client.get(`/feedback${qs ? '?' + qs : ''}`)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const get_feedback = (feedback_id) => catch_errors('Get feedback failed', async () => {
+	const [errors, data] = await client.get(`/feedback/${feedback_id}`)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+module.exports = {
+	create_feedback,
+	initiate_attachment_upload,
+	complete_attachment_upload,
+	put_attachment_to_s3,
+	list_feedback,
+	get_feedback
+}

package/src/commands/bump.js

@@ -6,9 +6,6 @@ const { inc, valid } = require('../utils/semver')
 const { resolve_skill_dir } = require('../utils/resolve_skill')
 const { find_project_root } = require('../config/paths')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
-const { write_lock, update_lock_skills } = require('../lock/writer')
-const { hash_directory } = require('../lock/integrity')
-const { verify_lock_disk_consistency } = require('../lock/verify')
 const repos_api = require('../api/repos')
 const { print_help, print_success, print_warn, print_json, code } = require('../ui/output')
 const { exit_with_error, UsageError } = require('../utils/errors')
@@ -52,13 +49,15 @@ const run = (args) => catch_errors('Bump failed', async () => {
 
 	const old_version = manifest.version
 
-	// Read lock file early to resolve full skill name for remote check + lock update
+	// Read lock file only to resolve the full skill name for the remote
+	// existence warning. The lock is NOT updated here — bump only touches
+	// skill.json. The lock catches up at publish time, atomically with
+	// registry acceptance. (Spec 260523-02 § 8.6.)
 	const project_root = find_project_root()
 	const [lock_err, lock_data] = await read_lock(project_root)
 	let lock_key = null
-	let all_skills = null
 	if (!lock_err && lock_data) {
-		all_skills = get_all_locked_skills(lock_data)
+		const all_skills = get_all_locked_skills(lock_data)
 		const suffix = `/${skill_name}`
 		lock_key = Object.keys(all_skills).find(k => k.endsWith(suffix)) || null
 	}
@@ -90,29 +89,10 @@ const run = (args) => catch_errors('Bump failed', async () => {
 	const [write_err] = await write_manifest(dir, manifest)
 	if (write_err) throw e('Failed to update skill.json', write_err)
 
-	if (lock_key && all_skills?.[lock_key]) {
-		const [hash_err, integrity] = await hash_directory(dir)
-		const updated_entry = {
-			...all_skills[lock_key],
-			version: manifest.version,
-			ref: `refs/tags/v${manifest.version}`
-		}
-		if (!hash_err && integrity) updated_entry.integrity = integrity
-		const updated_skills = update_lock_skills(lock_data, { [lock_key]: updated_entry })
-		await write_lock(project_root, updated_skills)
-
-		// Post-write verification — bump touches both files, so confirm they
-		// agree before declaring success. An interrupted bump (e.g. process
-		// killed between write_manifest and write_lock above) is exactly the
-		// failure mode this guard exists to catch.
-		const [, verify_result] = await verify_lock_disk_consistency(updated_entry, dir)
-		if (verify_result && !verify_result.ok) {
-			throw new Error(
-				`Bump completed but lock and disk disagree (lock ${verify_result.expected}, disk ${verify_result.actual || 'none'}). ` +
-				`Re-run ${code(`happyskills install ${lock_key} --fresh`)} to restore.`
-			)
-		}
-	}
+	// § 8.6: bump no longer updates the lock. The lock represents what was
+	// last successfully installed or published from the registry, and a
+	// local bump is not a registry interaction. The skill enters the `ahead`
+	// state (disk version > lock version) until the next publish.
 
 	if (args.flags.json) {
 		const bump_type = BUMP_TYPES.includes(input) ? input : 'explicit'

package/src/commands/check.js

@@ -1,6 +1,6 @@
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const { read_lock, get_all_locked_skills, get_via } = require('../lock/reader')
-const { verify_lock_disk_consistency } = require('../lock/verify')
+const { verify_lock_disk_consistency, detect_ahead_state } = require('../lock/verify')
 const repos_api = require('../api/repos')
 const { print_help, print_table, print_json, print_info, print_success, print_warn, print_hint, code } = require('../ui/output')
 const { green, yellow, red } = require('../ui/colors')
@@ -63,21 +63,39 @@ const run = (args) => catch_errors('Check failed', async () => {
 	// Verify lock-vs-disk consistency for every skill before classifying. Drift
 	// must outrank up-to-date / outdated / conflicts because all those statuses
 	// trust the lock as a baseline — and drift means the baseline is broken.
+	// Also detect the ahead state — disk > lock is normal authoring, not drift,
+	// and should be reported as such per §10.5.
 	const base_dir = skills_dir(false, project_root)
 	const drift_by_skill = {}
+	const ahead_by_skill = {}
 	await Promise.all(to_check.map(async ([name, data]) => {
 		const short_name = name.split('/')[1] || name
 		const dir = skill_install_dir(base_dir, short_name)
 		const [, drift] = await verify_lock_disk_consistency(data, dir)
-		if (drift && !drift.ok) drift_by_skill[name] = drift
+		if (drift && !drift.ok) {
+			drift_by_skill[name] = drift
+			return
+		}
+		const [, ahead] = await detect_ahead_state(data, dir)
+		if (ahead && ahead.ahead) ahead_by_skill[name] = ahead
 	}))
 
+	const build_ahead_obj = (ahead) => ({
+		lock_version: ahead.lock_version,
+		disk_version: ahead.disk_version,
+		has_changelog_entry: ahead.has_changelog_entry || false,
+		changelog_version: ahead.changelog_version || null
+	})
+
 	const results = []
 	if (batch_err) {
 		for (const [name, data] of to_check) {
 			const drift = drift_by_skill[name]
+			const ahead = ahead_by_skill[name]
 			if (drift) {
 				results.push({ skill: name, installed: data.version, latest: '-', status: 'drift', via: get_via(data), drift: { reason: drift.reason, lock_version: drift.expected, disk_version: drift.actual } })
+			} else if (ahead) {
+				results.push({ skill: name, installed: data.version, latest: '-', status: 'ahead', via: get_via(data), ahead: build_ahead_obj(ahead) })
 			} else {
 				results.push({ skill: name, installed: data.version, latest: 'error', status: 'error', via: get_via(data) })
 			}
@@ -88,8 +106,11 @@ const run = (args) => catch_errors('Check failed', async () => {
 			const via = get_via(data)
 			const has_conflicts = (data.conflict_files || []).length > 0
 			const drift = drift_by_skill[name]
+			const ahead = ahead_by_skill[name]
 			if (drift) {
 				results.push({ skill: name, installed: data.version, latest: info?.latest_version || '-', status: 'drift', via, drift: { reason: drift.reason, lock_version: drift.expected, disk_version: drift.actual } })
+			} else if (ahead) {
+				results.push({ skill: name, installed: data.version, latest: info?.latest_version || '-', status: 'ahead', via, ahead: build_ahead_obj(ahead) })
 			} else if (has_conflicts) {
 				results.push({ skill: name, installed: data.version, latest: info?.latest_version || '-', status: 'conflicts', via })
 			} else if (info?.access_denied) {
@@ -112,7 +133,8 @@ const run = (args) => catch_errors('Check failed', async () => {
 		const up_to_date_count = results.filter(r => r.status === 'up-to-date').length
 		const conflicts_count = results.filter(r => r.status === 'conflicts').length
 		const drift_count = results.filter(r => r.status === 'drift').length
-		print_json({ data: { results, outdated_count, up_to_date_count, conflicts_count, drift_count } })
+		const ahead_count = results.filter(r => r.status === 'ahead').length
+		print_json({ data: { results, outdated_count, up_to_date_count, conflicts_count, drift_count, ahead_count } })
 		return
 	}
 
@@ -121,6 +143,7 @@ const run = (args) => catch_errors('Check failed', async () => {
 		'outdated': yellow,
 		'conflicts': red,
 		'drift': red,
+		'ahead': (s) => s,
 		'no-access': yellow,
 		'error': red,
 		'unknown': (s) => s
@@ -153,7 +176,16 @@ const run = (args) => catch_errors('Check failed', async () => {
 			const disk = d.drift?.disk_version || 'none'
 			console.error(`  - ${d.skill} (lock ${d.drift?.lock_version}, disk ${disk})`)
 		}
-		print_hint(`Run ${code('happyskills status')} for details, or ${code('happyskills install <skill> --fresh')} to restore.`)
+		print_hint(`Repair with ${code('happyskills reconcile <skill>')}.`)
+	}
+	const ahead_results = results.filter(r => r.status === 'ahead')
+	if (ahead_results.length > 0) {
+		console.log()
+		print_info(`${ahead_results.length} skill(s) ahead of lock — bumped locally, not yet published.`)
+		for (const a of ahead_results) {
+			console.error(`  - ${a.skill} (lock ${a.ahead?.lock_version}, disk ${a.ahead?.disk_version})`)
+		}
+		print_hint(`Publish with ${code('happyskills publish <skill>')}.`)
 	}
 	if (conflicts.length > 0) {
 		console.log()

package/src/commands/feedback.js

@@ -0,0 +1,260 @@
+// Spec 260524-01 — `happyskills feedback` command.
+//
+// Surfaces:
+//   happyskills feedback <category> [body] [--subject "..."] [--attach a,b,c] [--json]
+//
+// --json mode emits the API's response wrapped in the universal CLI 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
+// § 6.2 + § 11.
+//
+// LAZY-LOAD: jimp / image_compression is only require()d when --attach is
+// present, so the 99% of CLI invocations that don't lodge feedback pay zero
+// startup cost (D8).
+
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { spawnSync } = require('child_process')
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { require_token } = require('../auth/token_store')
+const feedback_api = require('../api/feedback')
+const { scrub } = require('../utils/scrub_secrets')
+const { print_help, print_json, print_success, print_info, print_hint } = require('../ui/output')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES, CLI_VERSION } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills feedback <category> [body] [options]
+
+Lodge feedback with HappySkills — bug reports, feature wishes, compliments,
+questions. Auto-captures CLI version / OS / current skill context silently
+(secrets are scrubbed before sending).
+
+Arguments:
+  category            One of: bug | wish | compliment | question | other
+  body                Your feedback. Omit to open $EDITOR (vim / nano fallback).
+
+Options:
+  --subject "..."     Short title (max 200 chars)
+  --attach <paths>    Comma-separated image paths (max 10, PNG/JPEG accepted).
+                      Each compressed to ≤2000px / quality 80 / JPEG before upload.
+                      Per-image cap after compression: 1 MB (server-enforced).
+  --json              Emit JSON envelope (intended for use inside an agentic
+                      session — see the happyskills-help skill).
+
+Examples:
+  happyskills feedback bug "search returns nothing for partial slugs"
+  happyskills feedback wish "I wish I could export my catalog to JSON"
+  happyskills feedback bug --attach screenshot.png --json
+  happyskills feedback compliment    # → opens $EDITOR for the body`
+
+const VALID_CATEGORIES = new Set(['bug', 'wish', 'compliment', 'question', 'other'])
+
+const try_editor_for_body = () => {
+	const editors = [
+		process.env.EDITOR,
+		process.env.VISUAL,
+		'vim',
+		'nano',
+	].filter(Boolean)
+
+	const tmp = path.join(os.tmpdir(), `happyskills-feedback-${process.pid}-${Date.now()}.txt`)
+	fs.writeFileSync(tmp, '# Write your feedback above this line. Lines starting with # are ignored.\n')
+
+	let succeeded = false
+	for (const editor of editors) {
+		try {
+			const r = spawnSync(editor, [tmp], { stdio: 'inherit' })
+			if (r.status === 0) { succeeded = true; break }
+		} catch (_) {
+			// try next
+		}
+	}
+	if (!succeeded) {
+		try { fs.unlinkSync(tmp) } catch (_) {}
+		throw new UsageError('Could not open an editor. Set $EDITOR, or pass the body as a positional argument.')
+	}
+
+	const raw = fs.readFileSync(tmp, 'utf-8')
+	try { fs.unlinkSync(tmp) } catch (_) {}
+	const body = raw
+		.split('\n')
+		.filter(line => !line.startsWith('#'))
+		.join('\n')
+		.trim()
+	return body
+}
+
+// Best-effort: read a local skill.json if the cwd looks like a skill directory.
+const read_current_skill = () => {
+	try {
+		const p = path.join(process.cwd(), 'skill.json')
+		if (!fs.existsSync(p)) return null
+		const raw = fs.readFileSync(p, 'utf-8')
+		const parsed = JSON.parse(raw)
+		const name = parsed.name || null
+		if (!name) return null
+		// name may be "ns/skill" or just "skill"
+		const slash = name.indexOf('/')
+		return {
+			namespace: slash > 0 ? name.slice(0, slash) : null,
+			name: slash > 0 ? name.slice(slash + 1) : name,
+			version: parsed.version || null
+		}
+	} catch (_) {
+		return null
+	}
+}
+
+const build_client_context = () => {
+	const current_skill = read_current_skill()
+	const ctx = {
+		source: 'cli',
+		cli_version: CLI_VERSION,
+		node_version: process.version,
+		os: process.platform,
+		arch: process.arch,
+		cwd_is_skill_dir: !!current_skill,
+	}
+	if (current_skill) ctx.current_skill = current_skill
+	return scrub(ctx)
+}
+
+const MAX_ATTACHMENTS = 10
+const MAX_ATTACHMENT_BYTES = 1 * 1000 * 1000   // 1 MB post-compression — matches API MAX_FEEDBACK_ATTACHMENT_BYTES
+
+const parse_attach_paths = (raw_value) => {
+	if (!raw_value) return []
+	const items = String(raw_value).split(',').map(s => s.trim()).filter(Boolean)
+	if (items.length > MAX_ATTACHMENTS) {
+		throw new UsageError(`At most ${MAX_ATTACHMENTS} attachments are allowed.`)
+	}
+	for (const p of items) {
+		if (!fs.existsSync(p)) {
+			throw new UsageError(`Attachment not found: ${p}`)
+		}
+	}
+	return items
+}
+
+const upload_attachments = (feedback_id, attach_paths, opts) => catch_errors('Failed to upload attachments', async () => {
+	const { print_progress } = opts
+	// Lazy import — keeps jimp out of the require graph for non-feedback commands.
+	const { compress_image } = require('../utils/image_compression')
+
+	const uploaded = []
+	for (let i = 0; i < attach_paths.length; i++) {
+		const src = attach_paths[i]
+		if (print_progress) print_progress(`Compressing ${path.basename(src)} (${i + 1}/${attach_paths.length})`)
+
+		const [c_err, compressed] = await compress_image(src)
+		if (c_err) throw e(`Failed to compress ${src}`, c_err)
+
+		// Early bail before paying for an initiate round-trip if the compressed
+		// image still exceeds the per-image cap. Server enforces the same limit;
+		// this is a clean local error rather than a 413 round trip away.
+		if (compressed.bytes > MAX_ATTACHMENT_BYTES) {
+			throw new UsageError(`Compressed "${path.basename(src)}" is ${compressed.bytes} bytes — exceeds the ${MAX_ATTACHMENT_BYTES}-byte (1 MB) per-image cap. Try cropping or sending a smaller region.`)
+		}
+
+		const [init_err, init] = await feedback_api.initiate_attachment_upload(feedback_id, {
+			bytes: compressed.bytes,
+			content_type: 'image/jpeg',
+			original_name: path.basename(src),
+		})
+		if (init_err) throw e(`Failed to initiate upload for ${src}`, init_err)
+
+		if (print_progress) print_progress(`Uploading ${path.basename(src)} (${i + 1}/${attach_paths.length})`)
+		const [put_err] = await feedback_api.put_attachment_to_s3(init.upload_url, compressed.buffer)
+		if (put_err) throw e(`S3 upload failed for ${src}`, put_err)
+
+		const [comp_err, comp] = await feedback_api.complete_attachment_upload(feedback_id, {
+			upload_id: init.upload_id,
+			bytes: compressed.bytes,
+			width: compressed.width,
+			height: compressed.height,
+			original_name: path.basename(src),
+		})
+		if (comp_err) throw e(`Failed to confirm upload for ${src}`, comp_err)
+
+		uploaded.push(comp.attachment)
+	}
+	return uploaded
+})
+
+const run = (args) => catch_errors('Feedback command failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const json_mode = !!args.flags.json
+	const category = args._[0]
+	const body_positional = args._.slice(1).join(' ').trim()
+
+	if (!category) {
+		throw new UsageError(`Category is required. One of: ${Array.from(VALID_CATEGORIES).join(' | ')}`)
+	}
+	if (!VALID_CATEGORIES.has(category)) {
+		throw new UsageError(`Invalid category "${category}". Must be one of: ${Array.from(VALID_CATEGORIES).join(' | ')}`)
+	}
+
+	let body = body_positional
+	if (!body) {
+		if (json_mode) {
+			// In agentic / scripted contexts we can't open an editor — fail fast.
+			throw new UsageError('In --json mode the feedback body must be passed as a positional argument; the editor fallback is interactive.')
+		}
+		body = try_editor_for_body()
+		if (!body) {
+			throw new UsageError('No feedback body was entered. Aborted.')
+		}
+	}
+
+	const subject = args.flags.subject && typeof args.flags.subject === 'string' ? args.flags.subject : null
+	const attach_paths = parse_attach_paths(args.flags.attach)
+
+	// Auth required — surfaces a clean AuthError exit code 3 on no/expired token.
+	await require_token()
+
+	const client_context = build_client_context()
+
+	const [create_err, create_result] = await feedback_api.create_feedback({
+		category,
+		subject,
+		body,
+		client_context,
+	})
+	if (create_err) throw e('Failed to create feedback', create_err)
+
+	const { feedback, next_step } = create_result
+
+	// Attachment phase
+	let attachments = []
+	if (attach_paths.length > 0) {
+		const print_progress = json_mode ? null : (msg) => print_info(msg)
+		const [upload_err, uploaded] = await upload_attachments(feedback.id, attach_paths, { print_progress })
+		if (upload_err) throw e('Attachment upload failed', upload_err)
+		attachments = uploaded
+	}
+
+	if (json_mode) {
+		// Universal CLI 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 })
+		return
+	}
+
+	// Human-readable
+	const short_id = String(feedback.id).slice(0, 8)
+	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}).`)
+	}
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+module.exports = { run }