happyskills 0.49.0 → 0.51.0

package/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.51.0] - 2026-05-25
+
+### Added
+
+- **`list --json` now splits unclaimed on-disk skills into `data.drafts[]` and `data.external[]`** (`cli/src/commands/list.js`, `cli/src/utils/skill_scanner.js`). Drafts are skills scaffolded by `init` — they have a HappySkills-shaped `skill.json` (non-empty `name`, valid-semver `version`, `type` of `"skill"` or `"kit"`) and a `SKILL.md`, but no entry in `skills-lock.json` yet because the user hasn't published. External skills are genuinely foreign — they have a `SKILL.md` but no manifest or a foreign-shaped one, and they require `convert` before they can be published. Each draft entry includes `{ name, description, version, type }`; external entries keep the existing `{ name, description }` shape. Human output gains a `draft (unpublished)` row label and a closing hint pointing at `happyskills release` so the principal sees what to do next without having to read the docs.
+- **`is_happyskills_shaped_manifest()` exported from `cli/src/utils/skill_scanner.js`** — small predicate that other call sites (e.g. `happyskills-publish`'s pre-flight) can use to classify a found-on-disk skill the same way `list` does.
+
+### Rationale
+
+Spec 260522-02: when a user scaffolded a skill with `npx happyskills init` and immediately asked an LLM agent to "publish it", the previous `list --json` output reported the skill under `data.external[]` — the same bucket used for genuinely-foreign skills. Routing skills (notably `happyskills-publish`) read this as "external, must `convert` first", inserted a redundant `convert` step into the happy path, and surfaced the words `external` and `convert` to a user who had created their skill with the official tool five minutes earlier. That violated the mission's principal-surface promise of "no unexplained jargon" and "consistency over novelty". The CLI fix is a data-layer split (`data.drafts[]` vs `data.external[]`) so every consumer — routing skills, human output, future tooling — can tell the two states apart at the source. The companion routing-skill fix lands in `happyskills-publish@0.5.0` (in the same monorepo change set), which now reads `data.drafts` and routes drafts straight to `release` without ever mentioning `convert` or `external` to the user.
+
+## [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.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.49.0",
+	"version": "0.51.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/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 }

package/src/commands/init.js

@@ -133,7 +133,7 @@ const run = (args) => catch_errors('Init failed', async () => {
 		print_info(`Linked to: ${agents_result.agents.map(a => a.display_name).join(', ')}`)
 	}
 	console.log()
-	print_hint(`Edit these files, then run ${code('happyskills publish')} to share.`)
+	print_hint(`Edit these files, then run ${code(`happyskills release ${final_name} --workspace <slug>`)} to publish.`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
 module.exports = { run }

package/src/commands/list.js

@@ -51,16 +51,23 @@ const run = (args) => catch_errors('List failed', async () => {
 
 	const [, disk_skills] = await scan_skills_dir(base_dir)
 	const managed_names = new Set(managed_short_names)
-	const external_skills = (disk_skills || []).filter(s => !managed_names.has(s.name))
+	// Unclaimed skills (on disk, not in lock) split into two coherent buckets:
+	//   - drafts   → scaffolded by `init`, HappySkills-shaped skill.json present.
+	//                Publish/release pick these up directly — no `convert` needed.
+	//   - external → genuinely foreign (no skill.json, or foreign-shaped).
+	//                `convert` is the path to bring these into the managed set.
+	const unclaimed = (disk_skills || []).filter(s => !managed_names.has(s.name))
+	const draft_skills = unclaimed.filter(s => s.is_draft)
+	const external_skills = unclaimed.filter(s => !s.is_draft)
 
 	// Scan agent-specific dirs for skills placed directly in agent folders (not symlinked from .agents/skills/)
-	const all_known_names = new Set([...managed_names, ...external_skills.map(s => s.name)])
+	const all_known_names = new Set([...managed_names, ...draft_skills.map(s => s.name), ...external_skills.map(s => s.name)])
 	const [, agent_orphans] = await scan_agent_orphan_skills(AGENTS, is_global, project_root, all_known_names)
 	const orphan_skills = agent_orphans || []
 
-	if (managed_entries.length === 0 && external_skills.length === 0 && orphan_skills.length === 0) {
+	if (managed_entries.length === 0 && draft_skills.length === 0 && external_skills.length === 0 && orphan_skills.length === 0) {
 		if (args.flags.json) {
-			print_json({ data: { skills: {}, external: [], agent_orphans: [] } })
+			print_json({ data: { skills: {}, drafts: [], external: [], agent_orphans: [] } })
 			return
 		}
 		print_info('No skills installed.')
@@ -123,13 +130,19 @@ const run = (args) => catch_errors('List failed', async () => {
 			}
 			skills_map[name] = entry
 		}
+		const drafts = draft_skills.map(s => ({
+			name: s.name,
+			description: s.description || '',
+			version: s.version || null,
+			type: s.type || SKILL_TYPES.SKILL
+		}))
 		const external = external_skills.map(s => ({ name: s.name, description: s.description || '' }))
 		const agent_orphan_list = orphan_skills.map(s => ({
 			name: s.name,
 			description: s.description || '',
 			agents: s.agents
 		}))
-		print_json({ data: { skills: skills_map, external, agent_orphans: agent_orphan_list } })
+		print_json({ data: { skills: skills_map, drafts, external, agent_orphans: agent_orphan_list } })
 		return
 	}
 
@@ -153,6 +166,11 @@ const run = (args) => catch_errors('List failed', async () => {
 		rows.push([display_name, data.version, source, status_label, enabled_label])
 	}
 
+	for (const s of draft_skills) {
+		const type_label = s.type === SKILL_TYPES.KIT ? `${s.name} [kit]` : s.name
+		rows.push([type_label, s.version || '-', 'draft', 'unpublished', '-'])
+	}
+
 	for (const s of external_skills) {
 		rows.push([s.name, '-', 'external', 'installed', '-'])
 	}
@@ -175,6 +193,10 @@ const run = (args) => catch_errors('List failed', async () => {
 		console.log()
 		print_info(`${ahead_count} skill(s) ahead of lock — bumped locally, not yet published. Run publish when ready.`)
 	}
+	if (draft_skills.length > 0) {
+		console.log()
+		print_info(`${draft_skills.length} draft(s) ready to publish — run ${code('happyskills release <name>')} to ship.`)
+	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
 module.exports = { run }

package/src/constants.js

@@ -77,7 +77,8 @@ const COMMANDS = [
 	'postlex',
 	'snapshot',
 	'reconcile',
-	'release'
+	'release',
+	'feedback'
 ]
 
 module.exports = {

package/src/index.js

@@ -116,6 +116,7 @@ Commands:
   snapshot <sub>           Capture and restore skill state (create, list, restore, delete, prune)
   reconcile <owner/skill>  Diagnose and repair lock-vs-disk drift
   release <skill-name>     Atomic release: snapshot + validate + bump + publish
+  feedback <category>      Lodge feedback (bug, wish, compliment, question, other)
 
 Global flags:
   --help                   Show help for a command

package/src/integration/cli.test.js

@@ -379,7 +379,7 @@ describe('CLI — --json: success responses use { data } envelope', () => {
 // ─── --json flag: existing commands use { data } envelope ─────────────────────
 
 describe('CLI — --json: existing json commands now use { data } envelope', () => {
-	it('list --json returns { data: { skills, external } }', () => {
+	it('list --json returns { data: { skills, drafts, external } }', () => {
 		// Run in a temp dir with no lock file — produces empty result
 		const tmp = make_tmp()
 		try {
@@ -388,14 +388,51 @@ describe('CLI — --json: existing json commands now use { data } envelope', ()
 			const out = parse_json_output(stdout, 'list --json empty')
 			assert.ok('data' in out, 'should have top-level "data" key')
 			assert.ok('skills' in out.data, 'data.skills should exist')
+			assert.ok('drafts' in out.data, 'data.drafts should exist')
 			assert.ok('external' in out.data, 'data.external should exist')
 			assert.ok(typeof out.data.skills === 'object' && !Array.isArray(out.data.skills))
+			assert.ok(Array.isArray(out.data.drafts))
 			assert.ok(Array.isArray(out.data.external))
 		} finally {
 			fs.rmSync(tmp, { recursive: true, force: true })
 		}
 	})
 
+	it('list --json classifies init-scaffolded skills as drafts, foreign-shaped ones as external', () => {
+		// Two on-disk skills, no lock file:
+		//   - "my-draft"   has a HappySkills-shaped skill.json (init-style)
+		//   - "my-foreign" has only SKILL.md (foreign / hand-rolled)
+		const tmp = make_tmp()
+		try {
+			const draft_dir = path.join(tmp, '.agents', 'skills', 'my-draft')
+			fs.mkdirSync(draft_dir, { recursive: true })
+			fs.writeFileSync(path.join(draft_dir, 'SKILL.md'), '---\nname: my-draft\ndescription: a draft skill\n---\n\n# my-draft\n')
+			fs.writeFileSync(path.join(draft_dir, 'skill.json'), JSON.stringify({
+				name: 'my-draft',
+				version: '0.1.0',
+				type: 'skill',
+				description: '',
+				keywords: [],
+				dependencies: {}
+			}))
+
+			const foreign_dir = path.join(tmp, '.agents', 'skills', 'my-foreign')
+			fs.mkdirSync(foreign_dir, { recursive: true })
+			fs.writeFileSync(path.join(foreign_dir, 'SKILL.md'), '---\nname: my-foreign\ndescription: a foreign skill\n---\n\n# my-foreign\n')
+
+			const { stdout, code } = run(['list', '--json'], {}, { cwd: tmp })
+			assert.strictEqual(code, 0)
+			const out = parse_json_output(stdout, 'list --json mixed')
+			assert.strictEqual(out.data.drafts.length, 1, 'should have exactly one draft')
+			assert.strictEqual(out.data.drafts[0].name, 'my-draft')
+			assert.strictEqual(out.data.drafts[0].version, '0.1.0')
+			assert.strictEqual(out.data.external.length, 1, 'should have exactly one external')
+			assert.strictEqual(out.data.external[0].name, 'my-foreign')
+		} finally {
+			fs.rmSync(tmp, { recursive: true, force: true })
+		}
+	})
+
 	it('search --json usage error returns { error } not raw text', () => {
 		const { stdout, code } = run(['search', '--json'])
 		assert.strictEqual(code, 2)

package/src/utils/image_compression.js

@@ -0,0 +1,70 @@
+// Spec 260524-01 § 8.3 — CLI-side image compression for feedback attachments.
+//
+// FOOTPRINT DISCIPLINE (D8): this module cherry-picks @jimp/core +
+// @jimp/js-jpeg + @jimp/js-png + @jimp/plugin-resize from jimp 1.x. We
+// deliberately do NOT depend on the `jimp` meta-package — that pulls in
+// BMP, GIF, TIFF, blur, color, mask, threshold, dither, print, hash, blit,
+// circle, contain, cover, crop, displace, fisheye, flip, mask, quantize,
+// rotate, and a half-dozen more plugins we don't need.
+//
+// WEBP NOTE: jimp 1.x does NOT ship a WebP codec sub-package. CLI accepts
+// PNG and JPEG only; the web surface still accepts WebP via
+// `browser-image-compression`. Spec § 8.3's fallback explicitly anticipates
+// this drop ("drop @jimp/webp" — but in practice there's no such package).
+//
+// LAZY-LOAD: this module is dynamically imported only when the feedback
+// command actually has --attach arguments (see commands/feedback.js). Every
+// other CLI command — install, search, publish, etc. — pays zero require
+// cost for jimp.
+
+const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+
+const MAX_DIMENSION = 2000
+const JPEG_QUALITY = 80
+
+const get_default = (m) => (m && m.default !== undefined) ? m.default : m
+
+let _Jimp = null
+
+const get_jimp = () => {
+	if (_Jimp) return _Jimp
+	const { createJimp } = require('@jimp/core')
+	const jpeg = get_default(require('@jimp/js-jpeg'))
+	const png = get_default(require('@jimp/js-png'))
+	const resize = get_default(require('@jimp/plugin-resize'))
+	_Jimp = createJimp({ formats: [jpeg, png], plugins: [resize] })
+	return _Jimp
+}
+
+// Returns { buffer, bytes, width, height } — JPEG-encoded, longest side
+// ≤ 2000 px, quality 80. Accepts PNG or JPEG input.
+const compress_image = (file_path) => catch_errors('Image compression failed', async () => {
+	const Jimp = get_jimp()
+	let img
+	try {
+		img = await Jimp.read(file_path)
+	} catch (err) {
+		throw e(`Could not read image at ${file_path} — only PNG and JPEG are supported on the CLI`, [err])
+	}
+
+	const { width, height } = img.bitmap
+	if (width > MAX_DIMENSION || height > MAX_DIMENSION) {
+		// scale proportionally so longest side = MAX_DIMENSION
+		if (width >= height) {
+			img.resize({ w: MAX_DIMENSION })
+		} else {
+			img.resize({ h: MAX_DIMENSION })
+		}
+	}
+
+	const buffer = await img.getBuffer('image/jpeg', { quality: JPEG_QUALITY })
+
+	return {
+		buffer,
+		bytes: buffer.length,
+		width: img.bitmap.width,
+		height: img.bitmap.height
+	}
+})
+
+module.exports = { compress_image, MAX_DIMENSION, JPEG_QUALITY }

package/src/utils/scrub_secrets.js

@@ -0,0 +1,49 @@
+// Spec 260524-01 § 12 — Secret scrubbing applied to feedback `client_context`
+// before it leaves the CLI. Must match the rules in web/src/lib/scrub-secrets.js.
+//
+// Rules:
+//   1. Strip OpenAI API keys (sk-...)
+//   2. Strip GitHub tokens (ghp_..., gho_...)
+//   3. Strip Cognito JWT-shaped tokens (eyJ...)
+//   4. Strip values for env-var keys ending in _TOKEN, _KEY, _SECRET, _PASSWORD
+//
+// The replacement is the literal string `<redacted>` so callers can see that
+// a value WAS present and got stripped — vs missing entirely.
+
+const REDACTED = '<redacted>'
+
+const PATTERNS = [
+	/sk-[A-Za-z0-9_-]{20,}/g,      // OpenAI keys
+	/ghp_[A-Za-z0-9]{30,}/g,       // GitHub personal access tokens
+	/gho_[A-Za-z0-9]{30,}/g,       // GitHub OAuth tokens
+	/eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g  // JWT shape
+]
+
+const SENSITIVE_KEY = /(_TOKEN|_KEY|_SECRET|_PASSWORD|_API_KEY)$/i
+
+const scrub_string = (value) => {
+	let out = value
+	for (const re of PATTERNS) out = out.replace(re, REDACTED)
+	return out
+}
+
+// Recursively walk an object, scrubbing string values and redacting values
+// whose key looks sensitive (e.g. `OPENAI_API_KEY`).
+const scrub = (value) => {
+	if (value == null) return value
+	if (typeof value === 'string') return scrub_string(value)
+	if (typeof value !== 'object') return value
+	if (Array.isArray(value)) return value.map(scrub)
+
+	const out = {}
+	for (const [key, v] of Object.entries(value)) {
+		if (typeof v === 'string' && SENSITIVE_KEY.test(key)) {
+			out[key] = REDACTED
+		} else {
+			out[key] = scrub(v)
+		}
+	}
+	return out
+}
+
+module.exports = { scrub, scrub_string, REDACTED }

package/src/utils/skill_scanner.js

@@ -1,9 +1,25 @@
 const fs = require('fs')
 const path = require('path')
 const { error: { catch_errors } } = require('puffy-core')
+const { valid: valid_semver } = require('./semver')
+const { SKILL_JSON, SKILL_TYPES } = require('../constants')
 
 const SKIP_ENTRIES = new Set(['.tmp', '.DS_Store', '.install.lock'])
 
+// A disk-resident, unclaimed skill is a "draft" when it has a HappySkills-shaped
+// skill.json next to its SKILL.md — i.e. the file `init` already produced.
+// "HappySkills-shaped" means: a non-empty `name`, a valid-semver `version`, and
+// a `type` of "skill" or "kit". This is the minimum surface `release`/`publish`
+// can pick up on a no-lock-entry first publish without an intermediate `convert`.
+const is_happyskills_shaped_manifest = (manifest) => {
+	if (!manifest || typeof manifest !== 'object') return false
+	if (typeof manifest.name !== 'string' || !manifest.name.trim()) return false
+	if (!valid_semver(manifest.version)) return false
+	const t = manifest.type
+	if (t && t !== SKILL_TYPES.SKILL && t !== SKILL_TYPES.KIT) return false
+	return true
+}
+
 const parse_frontmatter = (content) => {
 	const match = content.match(/^---\n([\s\S]*?)\n---/)
 	if (!match) return null
@@ -44,9 +60,25 @@ const scan_skills_dir = (base_dir) => catch_errors('Failed to scan skills direct
 		const frontmatter = parse_frontmatter(content)
 		if (!frontmatter || !frontmatter.name) continue
 
+		// Detect whether this skill has a HappySkills-shaped manifest. If yes,
+		// callers can classify it as a "draft" (scaffolded by `init`, not yet
+		// claimed in the lock) rather than "external" (genuinely foreign).
+		let manifest = null
+		try {
+			const raw = await fs.promises.readFile(path.join(dir, SKILL_JSON), 'utf-8')
+			manifest = JSON.parse(raw)
+		} catch {
+			// No skill.json — genuinely external. manifest stays null.
+		}
+
+		const is_draft = is_happyskills_shaped_manifest(manifest)
+
 		skills.push({
 			name: frontmatter.name,
-			description: frontmatter.description || ''
+			description: frontmatter.description || '',
+			is_draft,
+			version: is_draft ? manifest.version : null,
+			type: is_draft ? (manifest.type || SKILL_TYPES.SKILL) : null
 		})
 	}
 
@@ -129,4 +161,4 @@ const scan_agent_orphan_skills = (agents, is_global, project_root, known_names)
 	return [...by_name.values()]
 })
 
-module.exports = { scan_skills_dir, scan_agent_orphan_skills, parse_frontmatter }
+module.exports = { scan_skills_dir, scan_agent_orphan_skills, parse_frontmatter, is_happyskills_shaped_manifest }