happyskills 1.20.1 → 1.21.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.21.0] - 2026-07-13
+
+### Added
+
+- Add the flat `happyskills profile` command (spec 260710-01, full parity with the web profile editor — no UI-only flows). View or edit a workspace's public `/w/<slug>/` page: `--tagline`, `--location`, `--website`, the six social-link flags (`--github` … `--mastodon`, each an https URL, `""` clears), the markdown bio (`--readme` / `--readme-file`), pinned skills by NAME (`--pin "a,b"` — replaces the set; names are resolved to ids against the workspace's public skills), the expertise-map `--hide-map`/`--show-map` toggle, and the `--public`/`--private` visibility toggle — a refusal for zero public skills surfaces the API's `publish_first` routing `next_step` (`route_to_skill: happyskills-publish`). `--avatar <path>` uploads a JPEG/PNG/WebP (magic-byte sniffed, 8 MB cap) through initiate → Content-Type-signed S3 PUT → complete; `--crop x,y,size` (normalized 0..1) crops the upload, or alone re-crops the RETAINED original with no re-upload. With no positional the command targets your personal workspace. Ships a full `schema` entry, so `happyskills schema --json` exposes the whole surface.
+- Add `publish_first` (kind `routing`) to the closed `next_step.action` enum, byte-identical with the API mirror. Bumped `ENVELOPE_SCHEMA_VERSION` to `1.2.0` (additive: one new next_step action — same precedent as 1.1.0's `complete_manual_setup`).
+- Support **structured config values**: a `skill.json` `config` field's `type` may now be `object` or `array`, not just a scalar — so a skill can declare a setting that has no scalar form (a theme, a named palette library). An `env` var stays scalar-only (a `.env` value is always a string; a structured type there is now a validation error). A field authored by the skill's own UI rather than by a human declares **`prompt: false`** and is skipped at install; an object/array field is never prompted regardless, since there is no sensible terminal prompt for "a map of named palettes". An unprompted field still applies its author default and still raises the fail-loud warning when it is `required` with no default.
+- Add **`happyskills skills-config set` / `unset`** — the deterministic writer, which the subsystem had been missing (only a reader shipped, so a skill that needed to persist its own config had no path but hand-editing JSON). Writes one key atomically and key-scoped, preserving every other skill's block, the skill's other keys, and `envFile`. `--value <scalar>` for a scalar field; **`--json-value <json>`** for an object/array (`--json-value -` reads it from stdin, for a value too large to shell-quote). `--root <dir>` writes to a directory that is not a HappySkills project, creating the file if absent; **`--global`** writes to `~/.agents/skills-config.json` — the right home for a user-level preference that should follow the user across every project. `set` **refuses** a key the skill declared `secret: true` (`FORBIDDEN_FIELD`) — that file is committed, and a secret in it is a leak.
+- Add **`happyskills skills-config validate`** — a deterministic checker for the consumer file. Because `skills-config.json` stays hand-editable by design, an LLM can and eventually will break it; this makes a hand-edit *recoverable*. Every result says **where** (the field path; for a syntax error the line, column, and the offending source line with a caret) and **how to fix it** (an imperative `fix`), naming the actual mistake — trailing comma, single quotes, unquoted key, comment, unclosed bracket, empty file — rather than emitting a generic "invalid JSON". Also catches a **secret sitting in the committed file** as a hard error (without echoing the value), an `envFile` that is absolute or not gitignored, a value contradicting its declared type, and an undeclared field.
+- Add an **opt-in, author-declared `schema`** on a config field (a hand-rolled JSON-Schema subset — no new dependency): `type`, `enum`, `const`, `properties`, `required`, `additionalProperties`, `patternProperties`, `items`, `minItems`, `maxItems`, `pattern`, `minLength`, `maxLength`, `minimum`, `maximum`. When declared, `skills-config set` **refuses** a violating value and `validate` reports **every** violation with the exact addressable path (`palettes.Acme.palette[2]`) and a fix — so an agent repairs the value and re-runs until it converges, instead of discovering the problem at runtime. When absent, content opacity stands: the value is stored verbatim and never inspected. This does not put a contract on our side of the wire — the schema ships *inside* the skill and versions *with* it, so it cannot drift from the skill's real contract. The author's own schema is validated at authoring time by `happyskills validate` (an uncompilable regex, an unknown keyword, or a keyword applied to the wrong type — a `minLength` on an array, which would silently validate nothing — is an error before publish, never at the consumer's).
+
+### Fixed
+
+- **Close a lost-update race on `skills-config.json` and `skills-lock.json`.** An atomic replace (write-temp + rename) protects a *reader* from a torn file but does nothing about two concurrent *read-modify-write* cycles: the second writer computes its next state from a pre-race snapshot and atomically replaces the file, silently erasing the first write. Both report success; one is gone. `skills-lock.json` was the worse case — `installer.js` read the lock and wrote it back **after a full network download**, a multi-second window, so two concurrent `happyskills install` runs could leave a skill on disk but absent from the lock. New `utils/file_lock.js` (a `mkdir`-based exclusive lock, stale-breaking and timeout-bounded) plus `lock/writer.js`'s new **`mutate_lock`**, which lets the caller do its slow work unlocked and then **re-reads the file inside the critical section** — so the lock is never held across a network fetch. All ten lock-write sites across seven files migrated; a static guard test fails the build if any production file calls or imports the raw `write_lock` again.
+- **Distinguish ABSENT from CORRUPT when reading `skills-config.json` and `skills-lock.json`.** Both readers returned `null` for a file that existed but did not parse, making it indistinguishable from a missing one. For config, `skills-config get` therefore reported `ok: true` with an empty config and zero warnings — so an agent concluded nothing had ever been set and could overwrite the values the broken file still held. For the lock it was worse: writers merged their update into `null`, producing a map containing only their own entry, and replaced the whole file — **one unparseable byte and the next `install` erased every other skill from the lock.** Both now stat the path first (absent → `null`; present-but-unparseable → throw `VALIDATION_FAILED` with a `fix_validation_errors` next_step pointing at `skills-config validate`), the corrupt file is never overwritten, and the sixteen lock callers that silently discarded the error now propagate it.
+- **Stop discarding the typed error when re-throwing a puffy-core chain.** `throw errors[0]` surfaces the generic *wrapper*, not the `CliError` deeper in the array where the `error.code` and `next_step` live — so writing to a corrupt config returned a bare `INTERNAL_ERROR` ("Failed to run the locked section for …") with no recovery action. Re-thrown with `wrap_errors` so the typed cause survives.
+
 ## [1.20.1] - 2026-07-09
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.20.1",
+	"version": "1.21.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/profiles.js

@@ -0,0 +1,76 @@
+// API bindings for the /w/ workspace profile surface (spec 260710-01
+// § II.4.3). Thin wrappers over the shared client — every response is the
+// canonical six-key response envelope; the client unwraps `data`.
+
+const { error: { catch_errors } } = require('puffy-core')
+const client = require('./client')
+
+const enc = encodeURIComponent
+
+const get_profile = (slug) => catch_errors(`Failed to load profile ${slug}`, async () => {
+	const [errors, data] = await client.get(`/workspaces/${enc(slug)}/profile?limit=100`)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const patch_profile = (slug, fields) => catch_errors(`Failed to update profile ${slug}`, async () => {
+	const [errors, data] = await client.patch(`/workspaces/${enc(slug)}/profile`, fields)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const set_visibility = (slug, is_public) => catch_errors(`Failed to set profile visibility for ${slug}`, async () => {
+	const [errors, data] = await client.put(`/workspaces/${enc(slug)}/profile:visibility`, { is_public })
+	if (errors) {
+		const err = errors[errors.length - 1]
+		// The publish-first precondition (§ II.4.3): surface the API's routing
+		// next_step instead of the generic fix_validation_errors default.
+		if (err && err.code === 'VALIDATION_FAILED' && err.details && err.details.public_skills === 0) {
+			err.next_step = {
+				kind: 'routing',
+				action: 'publish_first',
+				instructions: 'Publish at least one public skill, then re-run this visibility toggle. The public profile is the payoff for a public body of work.',
+				context: { commands: ['npx happyskills release --json'] },
+				route_to_skill: 'happyskills-publish',
+			}
+		}
+		throw err
+	}
+	return data
+})
+
+const avatar_initiate = (slug, bytes, content_type) => catch_errors('Failed to initiate the avatar upload', async () => {
+	const [errors, data] = await client.post(`/workspaces/${enc(slug)}/avatar:initiate`, { bytes, content_type })
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const avatar_complete = (slug, upload_id, crop) => catch_errors('Failed to complete the avatar upload', async () => {
+	const [errors, data] = await client.post(`/workspaces/${enc(slug)}/avatar:complete`, { upload_id, crop: crop || null })
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const recrop_avatar = (slug, crop) => catch_errors('Failed to re-crop the avatar', async () => {
+	const [errors, data] = await client.patch(`/workspaces/${enc(slug)}/profile:crop`, { crop })
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+// The caller's app username — resolves the default workspace when the
+// positional is omitted (`happyskills profile` = your own profile).
+const own_username = () => catch_errors('Failed to resolve your username', async () => {
+	const [errors, data] = await client.get('/me/bootstrap')
+	if (errors) throw errors[errors.length - 1]
+	return data && data.user && data.user.username
+})
+
+module.exports = {
+	get_profile,
+	patch_profile,
+	set_visibility,
+	avatar_initiate,
+	avatar_complete,
+	recrop_avatar,
+	own_username,
+}

package/src/commands/agents.js

@@ -148,7 +148,10 @@ const _add = async (raw_args, args) => {
 	const is_json = args.flags.json || false
 	const base_dir = skills_dir(is_global, project_root)
 
-	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
+	const [lock_data_err, lock_data] = await read_lock(lock_root(is_global, project_root))
+	// A corrupt lock must not be read as "nothing installed" — that lie would have us
+	// report an empty project, or reinstall over a lock we simply failed to parse.
+	if (lock_data_err) throw e('Failed to read the lock file', lock_data_err)
 
 	const per_agent = []
 

package/src/commands/check.js

@@ -30,7 +30,10 @@ const run = (args) => catch_errors('Check failed', async () => {
 	}
 
 	const project_root = find_project_root()
-	const [, lock_data] = await read_lock(project_root)
+	const [lock_data_err, lock_data] = await read_lock(project_root)
+	// A corrupt lock must not be read as "nothing installed" — that lie would have us
+	// report an empty project, or reinstall over a lock we simply failed to parse.
+	if (lock_data_err) throw e('Failed to read the lock file', lock_data_err)
 	const skills = get_all_locked_skills(lock_data)
 	const entries = Object.entries(skills)
 

package/src/commands/convert.js

@@ -9,7 +9,7 @@ const { parse_frontmatter } = require('../utils/skill_scanner')
 const { read_manifest } = require('../manifest/reader')
 const { write_manifest } = require('../manifest/writer')
 const { read_lock } = require('../lock/reader')
-const { write_lock, update_lock_skills } = require('../lock/writer')
+const { mutate_lock, update_lock_skills } = require('../lock/writer')
 const { hash_directory } = require('../lock/integrity')
 const { verify_lock_disk_consistency } = require('../lock/verify')
 const { skills_dir, find_project_root, lock_root } = require('../config/paths')
@@ -183,7 +183,10 @@ const run = (args) => catch_errors('Convert failed', async () => {
 
 	pub_spinner.update('Updating lock file...')
 	const lock_dir = lock_root(is_global, project_root)
-	const [, lock_data] = await read_lock(lock_dir)
+	const [lock_data_err, lock_data] = await read_lock(lock_dir)
+	// A corrupt lock must not be read as "nothing installed" — that lie would have us
+	// report an empty project, or reinstall over a lock we simply failed to parse.
+	if (lock_data_err) throw e('Failed to read the lock file', lock_data_err)
 	const [, integrity] = await hash_directory(skill_dir)
 
 	const full_name = `${workspace.slug}/${skill_name}`
@@ -198,8 +201,7 @@ const run = (args) => catch_errors('Convert failed', async () => {
 		}
 	}
 
-	const new_skills = update_lock_skills(lock_data, updates)
-	const [lock_err] = await write_lock(lock_dir, new_skills)
+	const [lock_err] = await mutate_lock(lock_dir, (current) => update_lock_skills(current, updates))
 	if (lock_err) { pub_spinner.fail('Failed to write lock file'); throw e('Lock write failed', lock_err) }
 
 	// Post-write verification — convert wrote both skill.json and the lock,

package/src/commands/disable.js

@@ -61,7 +61,10 @@ const run = (args) => catch_errors('Disable failed', async () => {
 	if (agents_err) throw e('Agent resolution failed', agents_err)
 	const { agents } = agents_result
 
-	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
+	const [lock_data_err, lock_data] = await read_lock(lock_root(is_global, project_root))
+	// A corrupt lock must not be read as "nothing installed" — that lie would have us
+	// report an empty project, or reinstall over a lock we simply failed to parse.
+	if (lock_data_err) throw e('Failed to read the lock file', lock_data_err)
 	const locked_skills = get_all_locked_skills(lock_data)
 
 	const results = []

package/src/commands/enable.js

@@ -61,7 +61,10 @@ const run = (args) => catch_errors('Enable failed', async () => {
 	if (agents_err) throw e('Agent resolution failed', agents_err)
 	const { agents } = agents_result
 
-	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
+	const [lock_data_err, lock_data] = await read_lock(lock_root(is_global, project_root))
+	// A corrupt lock must not be read as "nothing installed" — that lie would have us
+	// report an empty project, or reinstall over a lock we simply failed to parse.
+	if (lock_data_err) throw e('Failed to read the lock file', lock_data_err)
 	const locked_skills = get_all_locked_skills(lock_data)
 
 	const results = []

package/src/commands/install.js

@@ -64,7 +64,10 @@ const run = (args) => catch_errors('Install failed', async () => {
 	if (skills_raw.length === 0) {
 		const [manifest_err, manifest] = await read_manifest()
 		if (manifest_err) {
-			const [, lock_data] = await read_lock(base_options.project_root)
+			const [lock_data_err, lock_data] = await read_lock(base_options.project_root)
+			// A corrupt lock must not be read as "nothing installed" — that lie would have us
+			// report an empty project, or reinstall over a lock we simply failed to parse.
+			if (lock_data_err) throw e('Failed to read the lock file', lock_data_err)
 			if (lock_data && lock_data.skills && Object.keys(lock_data.skills).length > 0) {
 				const [errors, result] = await install_from_lock(lock_data, base_options)
 				if (errors) throw e('Install from lock failed', errors)
@@ -131,7 +134,10 @@ const run = (args) => catch_errors('Install failed', async () => {
 			// refuse before contacting the registry. Spec § 8.5 + envelope
 			// integration test (install_fresh.test.js).
 			if (dir_present) {
-				const [, lock_data_pre] = await read_lock(base_options.project_root)
+				const [lock_data_pre_err, lock_data_pre] = await read_lock(base_options.project_root)
+				// A corrupt lock must not be read as "nothing installed" — that lie would have us
+				// report an empty project, or reinstall over a lock we simply failed to parse.
+				if (lock_data_pre_err) throw e('Failed to read the lock file', lock_data_pre_err)
 				let has_local_edits = false
 				if (lock_data_pre) {
 					const all = get_all_locked_skills(lock_data_pre)
@@ -179,7 +185,10 @@ const run = (args) => catch_errors('Install failed', async () => {
 
 			// (3) Snapshot before wiping. Always — so a failed install is reversible.
 			if (dir_present) {
-				const [, lock_data_pre] = await read_lock(base_options.project_root)
+				const [lock_data_pre_err, lock_data_pre] = await read_lock(base_options.project_root)
+				// A corrupt lock must not be read as "nothing installed" — that lie would have us
+				// report an empty project, or reinstall over a lock we simply failed to parse.
+				if (lock_data_pre_err) throw e('Failed to read the lock file', lock_data_pre_err)
 				const [snap_err, snap] = await snapshot_storage.create({
 					skill_dir,
 					workspace: owner,

package/src/commands/list.js

@@ -48,7 +48,10 @@ const scope_label = (is_global) => (is_global ? 'Global' : 'Local')
 const gather_scope = (is_global, project_root, agents_flag) => catch_errors('Gather scope failed', async () => {
 	const base_dir = skills_dir(is_global, project_root)
 
-	const [, lock_data] = await read_lock(lock_root(is_global, project_root))
+	const [lock_data_err, lock_data] = await read_lock(lock_root(is_global, project_root))
+	// A corrupt lock must not be read as "nothing installed" — that lie would have us
+	// report an empty project, or reinstall over a lock we simply failed to parse.
+	if (lock_data_err) throw e('Failed to read the lock file', lock_data_err)
 	const skills = get_all_locked_skills(lock_data)
 	const managed_entries = Object.entries(skills)
 

package/src/commands/profile.js

@@ -0,0 +1,350 @@
+// happyskills profile — view and edit a workspace's public /w/ profile page
+// (spec 260710-01, Open Decision 4 = FULL CLI PARITY: every profile field, the
+// visibility toggle, and the avatar are agent-reachable — no UI-only flows).
+//
+// FLAT command by design (one file-named verb, flags for everything — never a
+// nested noun/verb family). One invocation may combine several edits; they run
+// in a deterministic order: field PATCH → visibility PUT → avatar/crop → final
+// GET, and the emitted envelope carries the final profile state.
+
+const fs = require('fs')
+const path = require('path')
+const { error: { catch_errors } } = require('puffy-core')
+const profiles_api = require('../api/profiles')
+const { require_token } = require('../auth/token_store')
+const { print_help, print_json, print_success, print_label, print_info } = require('../ui/output')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const SOCIAL_KEYS = ['github', 'twitter', 'linkedin', 'youtube', 'bluesky', 'mastodon']
+const MAX_AVATAR_BYTES = 8 * 1000 * 1000
+
+const HELP_TEXT = `Usage: happyskills profile [workspace] [options]
+
+View or edit a workspace's public profile page (happyskills.ai/w/<workspace>/).
+With no options, shows the profile. With no [workspace], uses your personal
+workspace. Every edit the web UI can make is available here.
+
+Arguments:
+  workspace             Workspace slug (defaults to your personal workspace)
+
+Profile fields (pass "" to clear a field):
+  --tagline <text>      One-line tagline (max 160 chars)
+  --location <text>     Location (max 120 chars)
+  --website <url>       Website (https:// URL)
+  --github <url>        Social links — each an https:// URL
+  --twitter <url>       (also: --linkedin, --youtube, --bluesky, --mastodon)
+  --readme <markdown>   The About section, inline markdown
+  --readme-file <path>  The About section, read from a markdown file
+  --pin <names>         Comma-separated skill names to pin (REPLACES the pinned
+                        set; "" unpins everything)
+  --hide-map            Hide the auto-generated expertise map from the public page
+  --show-map            Show it again
+
+Visibility:
+  --public              Make the profile public (requires >= 1 public skill).
+                        Public means indexed and in the sitemap.
+  --private             Make it private again
+
+Avatar:
+  --avatar <path>       Upload a JPEG/PNG/WebP image (max 8 MB). The centre
+                        square is shown by default; the ORIGINAL is kept so you
+                        can re-crop later without re-uploading.
+  --crop <x,y,size>     Crop square, normalized 0..1 (e.g. 0.1,0.05,0.8).
+                        With --avatar: applied to the new upload.
+                        Alone: re-crops the existing avatar from the kept original.
+
+Other:
+  --json                Output as JSON (the canonical envelope)
+
+Examples:
+  happyskills profile
+  happyskills profile nicolasdao --json
+  happyskills profile --tagline "Ships agent skills" --location "Sydney"
+  happyskills profile --avatar ./me.jpg --crop 0.1,0,0.8
+  happyskills profile --public
+  happyskills profile --pin "update-doc,pg-guard"`
+
+// ── pure helpers (exported for tests) ───────────────────────────────────────
+
+const sniff_content_type = (buf) => {
+	if (!buf || buf.length < 12) return null
+	if (buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return 'image/jpeg'
+	if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) return 'image/png'
+	if (buf.slice(0, 4).toString('latin1') === 'RIFF' && buf.slice(8, 12).toString('latin1') === 'WEBP') return 'image/webp'
+	return null
+}
+
+const parse_crop = (raw) => {
+	const parts = String(raw || '').split(',').map(s => Number(s.trim()))
+	if (parts.length !== 3 || parts.some(n => !Number.isFinite(n))) {
+		throw new UsageError('--crop must be three numbers "x,y,size" in 0..1 (e.g. --crop 0.1,0.05,0.8).')
+	}
+	const [x, y, size] = parts
+	if (x < 0 || y < 0 || size <= 0 || size > 1 || x + size > 1.0001 || y + size > 1.0001) {
+		throw new UsageError('--crop values must satisfy 0 <= x, 0 <= y, 0 < size <= 1, x+size <= 1, y+size <= 1.')
+	}
+	return { x, y, size }
+}
+
+// Collect the PATCHable fields from flags. `undefined` = untouched; '' = clear.
+const collect_field_edits = (flags) => {
+	const fields = {}
+	const str_flag = (name) => {
+		const v = flags[name]
+		if (v === undefined) return undefined
+		if (v === true) throw new UsageError(`--${name} needs a value (use --${name} "" to clear it).`)
+		return String(v)
+	}
+
+	const tagline = str_flag('tagline')
+	if (tagline !== undefined) fields.tagline = tagline || null
+	const location = str_flag('location')
+	if (location !== undefined) fields.location = location || null
+	const website = str_flag('website')
+	if (website !== undefined) fields.website_url = website || null
+
+	const socials = {}
+	let socials_touched = false
+	for (const key of SOCIAL_KEYS) {
+		const v = str_flag(key)
+		if (v === undefined) continue
+		socials_touched = true
+		socials[key] = v || ''
+	}
+	if (socials_touched) fields.social_links = socials
+
+	if (flags['hide-map'] && flags['show-map']) throw new UsageError('--hide-map and --show-map are mutually exclusive.')
+	if (flags['hide-map']) fields.expertise_map_hidden = true
+	if (flags['show-map']) fields.expertise_map_hidden = false
+
+	const readme_inline = str_flag('readme')
+	const readme_file = str_flag('readme-file')
+	if (readme_inline !== undefined && readme_file !== undefined) {
+		throw new UsageError('Pass --readme OR --readme-file, not both.')
+	}
+	if (readme_inline !== undefined) fields.profile_readme = readme_inline || null
+	if (readme_file !== undefined) fields.__readme_file = readme_file   // resolved by the caller (fs)
+
+	const pin = str_flag('pin')
+	if (pin !== undefined) fields.__pin_names = pin.trim() ? pin.split(',').map(s => s.trim()).filter(Boolean) : []
+
+	return fields
+}
+
+// ── the command ─────────────────────────────────────────────────────────────
+
+const upload_avatar = async (slug, avatar_path, crop) => {
+	const abs = path.resolve(avatar_path)
+	if (!fs.existsSync(abs)) throw new UsageError(`Avatar file not found: ${avatar_path}`)
+	const buf = fs.readFileSync(abs)
+	if (buf.length > MAX_AVATAR_BYTES) {
+		throw new UsageError(`The image is too large (max ${Math.round(MAX_AVATAR_BYTES / 1000 / 1000)} MB). Resize it and try again.`)
+	}
+	const content_type = sniff_content_type(buf)
+	if (!content_type) {
+		throw new UsageError('This image format is not supported yet. Save it as JPEG, PNG, or WebP and try again.')
+	}
+
+	const [init_err, init] = await profiles_api.avatar_initiate(slug, buf.length, content_type)
+	if (init_err) throw init_err[init_err.length - 1]
+
+	// Raw PUT to the presigned URL — the Content-Type MUST match the signed one.
+	const res = await fetch(init.upload_url, {
+		method: 'PUT',
+		headers: { 'Content-Type': init.required_content_type || content_type },
+		body: buf,
+	})
+	if (!res.ok) throw new Error(`The image upload failed (S3 ${res.status}). Please retry.`)
+
+	const [complete_err, completed] = await profiles_api.avatar_complete(slug, init.upload_id, crop)
+	if (complete_err) throw complete_err[complete_err.length - 1]
+	return completed
+}
+
+const resolve_pin_ids = async (slug, names) => {
+	if (names.length === 0) return []
+	const [err, profile] = await profiles_api.get_profile(slug)
+	if (err) throw err[err.length - 1]
+	const by_name = new Map((profile.skills || []).map(s => [s.name, s.id]))
+	const missing = names.filter(n => !by_name.has(n))
+	if (missing.length > 0) {
+		throw new UsageError(`Cannot pin ${missing.join(', ')} — not among this workspace's public skills. Pins take PUBLIC skill names.`)
+	}
+	return names.map(n => by_name.get(n))
+}
+
+const render_text = (profile) => {
+	const ws = profile.workspace
+	const t = profile.totals
+	print_label('Workspace', `${ws.display_name} (@${ws.slug})`)
+	print_label('Profile', ws.is_public ? `PUBLIC — https://happyskills.ai/w/${ws.slug}/` : 'private (only editors can see it)')
+	if (ws.tagline) print_label('Tagline', ws.tagline)
+	if (ws.location) print_label('Location', ws.location)
+	if (ws.website_url) print_label('Website', ws.website_url)
+	const socials = Object.entries(ws.social_links || {})
+	if (socials.length) print_label('Links', socials.map(([k, v]) => `${k}: ${v}`).join('  '))
+	print_label('Adoption', `${t.installs} installs · ${t.stars} stars${t.forks ? ` · ${t.forks} forks` : ''}`)
+	print_label('Skills', `${t.skills.original} authored${t.skills.claimed ? ` · ${t.skills.claimed} claimed` : ''}${t.skills.community_listed ? ` · ${t.skills.community_listed} community-listed` : ''}`)
+	if (ws.avatar) print_label('Avatar', 'set')
+	if (profile.expertise_map) {
+		const spine = profile.expertise_map.platform_family
+			.map(e => `${e.value} (${e.skills} skills, ${e.installs} installs)`)
+			.join(', ')
+		print_label('Expertise', spine || '(not enough scored skills yet)')
+	}
+	if ((ws.pinned || []).length) {
+		const pinned_names = (profile.skills || []).filter(s => s.pinned).map(s => s.name)
+		print_label('Pinned', pinned_names.join(', '))
+	}
+}
+
+const run = (args) => catch_errors('Profile command failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+	const flags = args.flags
+
+	if (flags.public && flags.private) throw new UsageError('--public and --private are mutually exclusive.')
+
+	const fields = collect_field_edits(flags)
+	const wants_visibility = !!flags.public || !!flags.private
+	const wants_avatar = flags.avatar !== undefined
+	const wants_recrop = flags.crop !== undefined && !wants_avatar
+	const crop = flags.crop !== undefined ? parse_crop(flags.crop) : null
+	const is_edit = Object.keys(fields).length > 0 || wants_visibility || wants_avatar || wants_recrop
+
+	// Reads of a PUBLIC profile work anonymously; anything else needs a session.
+	if (is_edit || !args._[0]) await require_token()
+
+	let slug = args._[0]
+	if (!slug) {
+		const [me_err, username] = await profiles_api.own_username()
+		if (me_err) throw me_err[me_err.length - 1]
+		if (!username) throw new Error('Could not resolve your personal workspace — pass the workspace slug explicitly.')
+		slug = username
+	}
+
+	const performed = []
+
+	// 1. Field edits (one PATCH).
+	if (fields.__readme_file !== undefined) {
+		const readme_path = path.resolve(fields.__readme_file)
+		if (!fs.existsSync(readme_path)) throw new UsageError(`README file not found: ${fields.__readme_file}`)
+		fields.profile_readme = fs.readFileSync(readme_path, 'utf8') || null
+		delete fields.__readme_file
+	}
+	if (fields.__pin_names !== undefined) {
+		fields.pinned_repo_ids = await resolve_pin_ids(slug, fields.__pin_names)
+		delete fields.__pin_names
+	}
+	if (Object.keys(fields).length > 0) {
+		const [patch_err] = await profiles_api.patch_profile(slug, fields)
+		if (patch_err) throw patch_err[patch_err.length - 1]
+		performed.push('fields_updated')
+	}
+
+	// 2. Visibility (one guarded PUT — the publish-first precondition surfaces
+	// as a structured error with a publish_first next_step).
+	if (wants_visibility) {
+		const [vis_err, vis] = await profiles_api.set_visibility(slug, !!flags.public)
+		if (vis_err) throw vis_err[vis_err.length - 1]
+		performed.push(vis.is_public ? 'made_public' : 'made_private')
+	}
+
+	// 3. Avatar upload / re-crop (async server-side processing → 202).
+	if (wants_avatar) {
+		await upload_avatar(slug, String(flags.avatar), crop)
+		performed.push('avatar_processing')
+	} else if (wants_recrop) {
+		const [crop_err] = await profiles_api.recrop_avatar(slug, crop)
+		if (crop_err) throw crop_err[crop_err.length - 1]
+		performed.push('avatar_recrop_processing')
+	}
+
+	// 4. Final state (also the plain view when nothing was edited).
+	const [get_err, profile] = await profiles_api.get_profile(slug)
+	if (get_err) throw get_err[get_err.length - 1]
+
+	if (flags.json) {
+		print_json({
+			data: {
+				...profile,
+				...(performed.length ? { performed } : {}),
+				public_url: profile.workspace.is_public ? `https://happyskills.ai/w/${profile.workspace.slug}/` : null,
+			},
+		})
+		return
+	}
+
+	render_text(profile)
+	if (performed.includes('avatar_processing') || performed.includes('avatar_recrop_processing')) {
+		print_info('Your photo is processing — it appears on the profile in a few seconds. The original is kept so you can re-crop later (`--crop x,y,size`) without re-uploading.')
+	}
+	if (performed.includes('made_public')) {
+		print_success(`Your profile is live: https://happyskills.ai/w/${profile.workspace.slug}/`)
+	} else if (performed.length) {
+		print_success('Profile updated.')
+	}
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+const schema = {
+	name:     'profile',
+	audience: 'consumer',
+	purpose:  'View and edit a workspace public profile page (/w/<slug>/): tagline, location, links, bio, pinned skills, expertise-map visibility, the public toggle, and the avatar. Full parity with the web editor.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'workspace', required: false, type: 'string', pattern: '<slug>', description: 'Defaults to your personal workspace' },
+		],
+		flags: [
+			{ name: 'tagline', type: 'string' },
+			{ name: 'location', type: 'string' },
+			{ name: 'website', type: 'string', pattern: 'https://…' },
+			{ name: 'github', type: 'string', pattern: 'https://…' },
+			{ name: 'twitter', type: 'string', pattern: 'https://…' },
+			{ name: 'linkedin', type: 'string', pattern: 'https://…' },
+			{ name: 'youtube', type: 'string', pattern: 'https://…' },
+			{ name: 'bluesky', type: 'string', pattern: 'https://…' },
+			{ name: 'mastodon', type: 'string', pattern: 'https://…' },
+			{ name: 'readme', type: 'string', description: 'About section markdown, inline' },
+			{ name: 'readme-file', type: 'string', description: 'About section markdown, from a file' },
+			{ name: 'pin', type: 'string', description: 'Comma-separated PUBLIC skill names; replaces the pinned set' },
+			{ name: 'hide-map', type: 'boolean', default: false },
+			{ name: 'show-map', type: 'boolean', default: false },
+			{ name: 'public', type: 'boolean', default: false, description: 'Requires >= 1 public skill; public ⇒ indexed + in the sitemap' },
+			{ name: 'private', type: 'boolean', default: false },
+			{ name: 'avatar', type: 'string', description: 'Path to a JPEG/PNG/WebP image (max 8 MB); centre-square crop by default' },
+			{ name: 'crop', type: 'string', pattern: 'x,y,size (normalized 0..1)', description: 'With --avatar: crop the upload. Alone: re-crop the kept original.' },
+			{ name: 'json', type: 'boolean', default: false },
+		],
+	},
+	output: {
+		data_shape: {
+			workspace:     'object — slug, display_name, is_public, tagline, location, website_url, social_links, profile_readme, avatar, pinned',
+			totals:        'object — installs, stars, forks, skills{original,claimed,community_listed}',
+			skills:        'array — public skills with adoption counts and listing_status',
+			expertise_map: 'object|null — platform-vetted, evidence-carrying; null when hidden or below the 3-skill floor',
+			timeline:      'array — {date, count} over ORIGINAL skills only',
+			performed:     'array<string> — edits applied this invocation (present only after an edit)',
+			public_url:    'string|null',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',       next_step: { kind: 'routing',  action: 'discover_schema' } },
+		{ code: 'AUTH_REQUIRED',     next_step: { kind: 'recovery', action: 'login' } },
+		{ code: 'VALIDATION_FAILED', next_step: { kind: 'routing',  action: 'publish_first' }, when: 'toggling --public with zero public skills' },
+		{ code: 'NOT_FOUND',         when: 'workspace missing, or the profile is private and you are not an editor' },
+	],
+	examples: [
+		'happyskills profile',
+		'happyskills profile nicolasdao --json',
+		'happyskills profile --tagline "Ships agent skills" --location Sydney',
+		'happyskills profile --avatar ./me.jpg --crop 0.1,0,0.8',
+		'happyskills profile --public',
+	],
+}
+
+module.exports = { run, schema, collect_field_edits, parse_crop, sniff_content_type }