happyskills 1.2.2 → 1.4.0

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-06-03
+
+### Added
+
+- Add `star <owner/name>` and `unstar <owner/name>` commands to curate your favorites. Both require auth and are idempotent (starring an already-starred skill, or unstarring one you haven't starred, succeeds without error).
+- Add `--favorites` flag to `search` — query only the skills you've starred (`scope=favorites`). Routes through the smart dispatcher; a bare `search --favorites` (no query) browses all your starred skills. Requires auth; cannot be combined with `--exact`.
+
+## [1.3.0] - 2026-06-03
+
+### Added
+
+- `login` now returns the full identity payload — `username`, `email`, and `workspaces` — on every success path (`logged_in` and `already_logged_in`), so an agent no longer needs a follow-up `whoami` call after authenticating. Both commands build the block from one shared assembler, so their shapes stay identical. The workspace lookup is best-effort: a failed `GET /workspaces` degrades to an empty list plus `workspace_error` and never fails the login.
+- Detect circular dependencies in the dependency graph. `validate` and `publish` run a `dep-circular` rule that resolves each dependency's published subtree, grafts the local skill's own edges, and DFS-searches for cycles — so it also catches a cycle created by the edge being published. A detected cycle is a hard error that blocks publish. Registry-scoped checks run only when authenticated.
+
+### Changed
+
+- Text-mode `login` now short-circuits when a valid session already exists — it prints the identity block instead of launching a fresh auth flow, mirroring the `--json` path. Run `happyskills logout` to force a fresh login.
+- `install` is now loop-safe: a cycle among already-published skills never causes infinite recursion. Every skill in the tree is still installed, and the CLI prints a circular-dependency warning (also surfaced in `--json` under `warnings`).
+
 ## [1.2.2] - 2026-06-02
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.2.2",
+	"version": "1.4.0",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/api/repos.js

@@ -105,6 +105,21 @@ const patch_repo = (owner, name, fields) => catch_errors(`Failed to update ${own
 	return data
 })
 
+// Star / unstar a repo. Both endpoints are idempotent server-side (starring an
+// already-starred repo, or unstarring an unstarred one, succeeds). The user's
+// own stars power the `favorites` search scope.
+const star = (owner, name) => catch_errors(`Failed to star ${owner}/${name}`, async () => {
+	const [errors, data] = await client.post(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/star`)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
+const unstar = (owner, name) => catch_errors(`Failed to unstar ${owner}/${name}`, async () => {
+	const [errors, data] = await client.del(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/star`)
+	if (errors) throw errors[errors.length - 1]
+	return data
+})
+
 const compare = (owner, repo, base_commit) => catch_errors(`Compare ${owner}/${repo} failed`, async () => {
 	const [errors, data] = await client.post(`/repos/${owner}/${repo}/compare`, { base_commit })
 	if (errors) throw errors[errors.length - 1]
@@ -195,4 +210,4 @@ const semantic_search = (query, options = {}) => catch_errors('Semantic search f
 	return data
 })
 
-module.exports = { search, dispatch_search, semantic_search, resolve_dependencies, clone, push, get_refs, get_repo, check_updates, del_repo, patch_repo, compare, get_blob, get_tree }
+module.exports = { search, dispatch_search, semantic_search, resolve_dependencies, clone, push, get_refs, get_repo, check_updates, del_repo, patch_repo, star, unstar, compare, get_blob, get_tree }

package/src/api/repos.test.js

@@ -169,3 +169,51 @@ describe('repos.get_blob — content integrity verification', () => {
 		assert.strictEqual(data.size, content.length)
 	})
 })
+
+// Capturing client stub: records (method, path) for each call so star/unstar
+// path construction can be asserted. Mirrors stub_client above.
+const stub_client_capture = () => {
+	const calls = []
+	const record = (method) => async (path) => { calls.push([method, path]); return [null, { message: 'ok' }] }
+	const client_path = require.resolve('./client')
+	require.cache[client_path] = {
+		id: client_path,
+		filename: client_path,
+		loaded: true,
+		exports: {
+			get: record('get'),
+			post: record('post'),
+			put: record('put'),
+			patch: record('patch'),
+			del: record('del'),
+			request: record('request'),
+			get_base_url: () => 'http://test'
+		}
+	}
+	delete require.cache[require.resolve('./repos')]
+	return { repos: require('./repos'), calls }
+}
+
+describe('repos.star / repos.unstar — endpoint + path', () => {
+	afterEach(restore)
+
+	it('star() POSTs to /repos/<owner>/<name>/star', async () => {
+		const { repos, calls } = stub_client_capture()
+		const [err] = await repos.star('acme', 'deploy-aws')
+		assert.strictEqual(err, null)
+		assert.deepStrictEqual(calls[0], ['post', '/repos/acme/deploy-aws/star'])
+	})
+
+	it('unstar() DELETEs /repos/<owner>/<name>/star', async () => {
+		const { repos, calls } = stub_client_capture()
+		const [err] = await repos.unstar('acme', 'deploy-aws')
+		assert.strictEqual(err, null)
+		assert.deepStrictEqual(calls[0], ['del', '/repos/acme/deploy-aws/star'])
+	})
+
+	it('URL-encodes owner and name in the star path', async () => {
+		const { repos, calls } = stub_client_capture()
+		await repos.star('acme corp', 'deploy/aws')
+		assert.strictEqual(calls[0][1], `/repos/${encodeURIComponent('acme corp')}/${encodeURIComponent('deploy/aws')}/star`)
+	})
+})

package/src/auth/identity.js

@@ -0,0 +1,58 @@
+const { error: { catch_errors } } = require('puffy-core')
+const workspaces_api = require('../api/workspaces')
+const { print_label, print_warn, print_hint } = require('../ui/output')
+
+// Decode a JWT payload for display only — no signature verification. Returns
+// null on any malformed input.
+const decode_jwt_payload = (token) => {
+	try {
+		const parts = (token || '').split('.')
+		if (parts.length !== 3) return null
+		const payload = Buffer.from(parts[1], 'base64url').toString('utf-8')
+		return JSON.parse(payload)
+	} catch {
+		return null
+	}
+}
+
+// Assemble the canonical identity payload shared by `whoami` and `login`, so
+// the two commands can never disagree on shape or content. Identity fields
+// (username/email) come straight off the in-hand id_token; workspaces are
+// fetched best-effort — a failed lookup degrades to an empty list plus a
+// `workspace_error` string and NEVER fails the caller. A network hiccup must
+// not turn a valid session into an error: the user is logged in regardless.
+const resolve_identity = (token_data) => catch_errors('Resolve identity failed', async () => {
+	const payload = decode_jwt_payload(token_data?.id_token)
+	const email = payload?.email || 'unknown'
+	const username = payload?.['cognito:username'] || payload?.sub || 'unknown'
+
+	const [ws_err, workspaces] = await workspaces_api.list_workspaces()
+	const identity = { username, email, workspaces: ws_err ? [] : (workspaces || []) }
+	if (ws_err) identity.workspace_error = ws_err.map(er => er.message).join(': ')
+	return identity
+})
+
+// Render an identity payload to the human (text-mode) surface. Both `whoami`
+// and `login` use this so the warm output stays content-equal with `--json`:
+// the format differs, the information does not.
+const render_identity_text = (identity) => {
+	print_label('Username', identity.username)
+	print_label('Email', identity.email)
+
+	if (identity.workspace_error) {
+		console.log()
+		print_warn(`Failed to list workspaces: ${identity.workspace_error}`)
+		print_hint('Check your authentication with happyskills login')
+	} else if (identity.workspaces && identity.workspaces.length > 0) {
+		console.log()
+		print_label('Workspaces', '')
+		for (const ws of identity.workspaces) {
+			const type_label = ws.is_owner
+				? ws.type === 'personal' ? ' (personal)' : ' (organization)'
+				: ''
+			console.log(`  ${ws.slug}${type_label}`)
+		}
+	}
+}
+
+module.exports = { decode_jwt_payload, resolve_identity, render_identity_text }

package/src/commands/login.js

@@ -4,8 +4,9 @@ const readline = require('readline')
 const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
 const auth_api = require('../api/auth')
 const { save_token, load_token } = require('../auth/token_store')
+const { resolve_identity, render_identity_text } = require('../auth/identity')
 const { create_spinner } = require('../ui/spinner')
-const { print_help, print_success, print_info, print_hint, print_json, code } = require('../ui/output')
+const { print_help, print_success, print_info, print_json } = require('../ui/output')
 const { exit_with_error } = require('../utils/errors')
 const { EXIT_CODES, CLI_VERSION } = require('../constants')
 const { run_browser_flow } = require('./login_device')
@@ -136,17 +137,6 @@ const run_password_flow = () => catch_errors('Password login failed', async () =
 	await handle_post_login_telemetry()
 })
 
-const decode_jwt_payload = (token) => {
-	try {
-		const parts = token.split('.')
-		if (parts.length !== 3) return null
-		const payload = Buffer.from(parts[1], 'base64url').toString('utf-8')
-		return JSON.parse(payload)
-	} catch {
-		return null
-	}
-}
-
 const run = (args) => catch_errors('Login failed', async () => {
 	if (args.flags._show_help) {
 		print_help(HELP_TEXT)
@@ -156,10 +146,8 @@ const run = (args) => catch_errors('Login failed', async () => {
 	if (args.flags.json) {
 		const [, token_data] = await load_token()
 		if (token_data) {
-			const payload = decode_jwt_payload(token_data.id_token)
-			const email = payload?.email || 'unknown'
-			const username = payload?.['cognito:username'] || payload?.sub || 'unknown'
-			print_json({ data: { status: 'already_logged_in', username, email } })
+			const [, identity] = await resolve_identity(token_data)
+			print_json({ data: { status: 'already_logged_in', ...identity } })
 			return
 		}
 
@@ -181,10 +169,8 @@ const run = (args) => catch_errors('Login failed', async () => {
 		// Browser flow succeeded — read saved token
 		const [, new_token] = await load_token()
 		if (new_token) {
-			const payload = decode_jwt_payload(new_token.id_token)
-			const email = payload?.email || 'unknown'
-			const username = payload?.['cognito:username'] || payload?.sub || 'unknown'
-			print_json({ data: { status: 'logged_in', username, email } })
+			const [, identity] = await resolve_identity(new_token)
+			print_json({ data: { status: 'logged_in', ...identity } })
 		} else {
 			print_json({ error: { code: 'AUTH_FAILED', message: 'Login flow completed but token could not be loaded', exit_code: EXIT_CODES.ERROR } })
 			process.exit(EXIT_CODES.ERROR)
@@ -192,6 +178,20 @@ const run = (args) => catch_errors('Login failed', async () => {
 		return
 	}
 
+	// Text mode short-circuits on an existing session, mirroring the --json
+	// path (which returns `already_logged_in` before consulting any flow flag).
+	// "Already logged in" must mean the same thing in text as in JSON — same
+	// information, different encoding. To force a fresh login, run `logout`
+	// first. The workspace lookup stays best-effort and never fails the check.
+	const [, existing_token] = await load_token()
+	if (existing_token) {
+		const [, identity] = await resolve_identity(existing_token)
+		print_info('You are already logged in.')
+		console.log()
+		render_identity_text(identity)
+		return
+	}
+
 	let use_password = args.flags.password === true
 	let use_browser = args.flags.browser === true
 
@@ -214,8 +214,16 @@ const run = (args) => catch_errors('Login failed', async () => {
 		await handle_post_login_telemetry()
 	}
 
-	console.log()
-	print_hint(`Verify your identity: ${code('happyskills whoami')}`)
+	// Show the same identity block `whoami` shows, so login fully answers
+	// "who am I" on the human surface too — no redundant follow-up call. This
+	// keeps text mode content-equal with `--json` (same information, different
+	// encoding). Best-effort: a workspace lookup failure never fails the login.
+	const [, token_data] = await load_token()
+	if (token_data) {
+		const [, identity] = await resolve_identity(token_data)
+		console.log()
+		render_identity_text(identity)
+	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
 const schema = {
@@ -234,9 +242,10 @@ const schema = {
 	},
 	output: {
 		data_shape: {
-			status:   'string',
-			username: 'string',
-			email:    'string',
+			status:     'string',
+			username:   'string',
+			email:      'string',
+			workspaces: 'array',
 		},
 	},
 	errors: [

package/src/commands/search.js

@@ -16,12 +16,13 @@ fuzzy slug, and "workspace/skill" form goes to fuzzy scoped (both parts are
 typo-tolerant). Use --exact to force keyword-only FTS instead.
 
 Arguments:
-  query               Search term (optional with --mine, --personal, or --workspace)
+  query               Search term (optional with --mine, --personal, --workspace, or --favorites)
 
 Options:
   -w, --workspace <slug>  Search within specific workspace(s) (comma-separated)
   --mine                  Search across all your workspaces
   --personal              Search only your personal workspace
+  --favorites             Search only skills you've starred (requires auth)
   --tags <tags>           Filter by tags (comma-separated)
   --type <type>           Filter by type (skill, kit)
   --exact                 Force keyword-only FTS matching (skip smart routing)
@@ -42,6 +43,8 @@ Examples:
   happyskills search deploy-aws --limit 10                # → fuzzy slug (typo-tolerant)
   happyskills search letta-ai/remotion --limit 5          # → fuzzy scoped
   happyskills search --mine --limit 20
+  happyskills search --favorites --limit 20                # → your starred skills
+  happyskills search deploy --favorites --limit 10         # → favorites matching "deploy"
   happyskills search deploy --workspace acme --limit 50
   happyskills search --type kit --limit 10
   happyskills search deploy --exact --limit 10            # → keyword FTS only`
@@ -380,15 +383,19 @@ const run = (args) => catch_errors('Search failed', async () => {
 	}
 
 	const query = args._.join(' ') || null
-	const { mine, personal, workspace, tags, type } = args.flags
+	const { mine, personal, workspace, tags, type, favorites } = args.flags
 	const is_exact = !!args.flags.exact
 	const with_rerank = !!args.flags['with-rerank']
-	// --smart / -S accepted for backward compat (now the default when a query is provided)
-	const use_smart = query && !is_exact
-	const has_scope_flag = mine || personal || workspace
+	// --smart / -S accepted for backward compat (now the default when a query is provided).
+	// --favorites also forces the smart (POST /repos:search) path even with no query:
+	// favorites is a dispatcher-only scope, so it must never fall through to the
+	// legacy keyword GET, which doesn't understand it. A bare `--favorites` browses
+	// the user's starred skills (list mode).
+	const use_smart = (query || favorites) && !is_exact
+	const has_scope_flag = mine || personal || workspace || favorites
 
 	if (!query && !has_scope_flag && !tags && !type) {
-		throw new UsageError('Please provide a search query or use --mine, --personal, or --workspace.')
+		throw new UsageError('Please provide a search query or use --mine, --personal, --workspace, or --favorites.')
 	}
 
 	if (!args.flags.limit) {
@@ -405,9 +412,15 @@ const run = (args) => catch_errors('Search failed', async () => {
 		throw new UsageError('--with-rerank cannot be combined with --exact. The rerank protocol applies only to semantic-mode dispatches.')
 	}
 
-	const scope = mine ? 'mine' : personal ? 'personal' : undefined
+	// Favorites is a dispatcher-only scope (POST /repos:search); --exact forces the
+	// legacy keyword endpoint, which doesn't support it. Refuse the combination.
+	if (favorites && is_exact) {
+		throw new UsageError('--favorites cannot be combined with --exact. Favorites search uses the smart dispatcher, not keyword-only FTS.')
+	}
+
+	const scope = favorites ? 'favorites' : mine ? 'mine' : personal ? 'personal' : undefined
 
-	if (mine || personal) {
+	if (mine || personal || favorites) {
 		const [, token_data] = await load_token()
 		if (!token_data) {
 			throw new AuthError('Authentication required. Run `happyskills login` first.')

package/src/commands/search.test.js

@@ -9,7 +9,7 @@
 // short names (`clarify`, `present_to_user` alone) no longer apply where the
 // new enum supersedes them.
 
-const { describe, it } = require('node:test')
+const { describe, it, afterEach } = require('node:test')
 const assert = require('node:assert/strict')
 const { build_search_next_step } = require('./search')
 const {
@@ -146,3 +146,62 @@ describe('build_search_next_step — envelope shape', () => {
 		assert.strictEqual(opts[3].refined_query_hint, null)
 	})
 })
+
+// --- search --favorites wiring (spec 260601-02 § 4.3) ---------------------
+// Stub the API client + token store so run() exercises the flag-routing logic
+// without a network call. favorites is a dispatcher-only scope, so the key
+// assertions are: it sets scope='favorites' on dispatch_search (POST) and never
+// falls through to the keyword GET, and a bare --favorites (no query) is allowed.
+
+const stub_search_deps = (capture) => {
+	const repos_path = require.resolve('../api/repos')
+	require.cache[repos_path] = {
+		id: repos_path, filename: repos_path, loaded: true,
+		exports: {
+			dispatch_search: async (query, opts) => {
+				capture.dispatch = { query, opts }
+				return [null, { data: [], mode: 'list', match_notice: null }]
+			},
+			search: async (query, opts) => { capture.keyword = { query, opts }; return [null, []] },
+		},
+	}
+	const token_path = require.resolve('../auth/token_store')
+	require.cache[token_path] = {
+		id: token_path, filename: token_path, loaded: true,
+		exports: {
+			load_token: async () => [null, { token: 'test-token' }],
+			require_token: async () => ({ token: 'test-token' }),
+			save_token: async () => {}, clear_token: async () => {},
+		},
+	}
+	delete require.cache[require.resolve('./search')]
+	return require('./search')
+}
+
+const restore_search_deps = () => {
+	delete require.cache[require.resolve('../api/repos')]
+	delete require.cache[require.resolve('../auth/token_store')]
+	delete require.cache[require.resolve('./search')]
+}
+
+describe('search --favorites — scope wiring', () => {
+	afterEach(restore_search_deps)
+
+	it('bare --favorites (no query) is allowed and dispatches scope=favorites via POST, not keyword GET', async () => {
+		const capture = {}
+		const search = stub_search_deps(capture)
+		await search.run({ _: [], flags: { favorites: true, limit: '20', json: true } })
+		assert.ok(capture.dispatch, 'dispatch_search (POST) must be called for favorites')
+		assert.strictEqual(capture.keyword, undefined, 'keyword GET must NOT be used for favorites')
+		assert.strictEqual(capture.dispatch.opts.scope, 'favorites')
+		assert.strictEqual(capture.dispatch.query, null, 'bare --favorites sends a null query (list mode)')
+	})
+
+	it('--favorites with a query keeps scope=favorites and forwards the query', async () => {
+		const capture = {}
+		const search = stub_search_deps(capture)
+		await search.run({ _: ['deploy'], flags: { favorites: true, limit: '10', json: true } })
+		assert.strictEqual(capture.dispatch.opts.scope, 'favorites')
+		assert.strictEqual(capture.dispatch.query, 'deploy')
+	})
+})

package/src/commands/star.js

@@ -0,0 +1,82 @@
+const { error: { catch_errors } } = require('puffy-core')
+const { star } = require('../api/repos')
+const { require_token } = require('../auth/token_store')
+const { print_help, print_json, print_success } = require('../ui/output')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills star <owner/name> [options]
+
+Star a skill. Your starred skills are your favorites — search them with
+\`happyskills search --favorites\`. Idempotent: starring an already-starred
+skill succeeds without error.
+
+Arguments:
+  owner/name        Skill to star (e.g., acme/deploy-aws)
+
+Options:
+  --json            Output as JSON
+
+Examples:
+  happyskills star acme/deploy-aws
+  happyskills star acme/deploy-aws --json`
+
+const run = (args) => catch_errors('Star failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const skill = args._[0]
+	if (!skill) {
+		throw new UsageError('Please specify a skill to star (e.g., happyskills star acme/deploy-aws).')
+	}
+	if (!skill.includes('/')) {
+		throw new UsageError('Skill must be in owner/name format (e.g., acme/deploy-aws).')
+	}
+
+	await require_token()
+
+	const [owner, name] = skill.split('/')
+	const [errors, result] = await star(owner, name)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data: { starred: true, skill, ...(result || {}) } })
+		return
+	}
+
+	print_success(`Starred "${skill}". Browse your favorites with: happyskills search --favorites`)
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+const schema = {
+	name:     'star',
+	audience: 'consumer',
+	purpose:  'Star a skill. Starred skills power the favorites search scope. Idempotent.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'skill', required: true, type: 'string', pattern: '<owner>/<name>' },
+		],
+		flags: [
+			{ name: 'json', type: 'boolean', default: false },
+		],
+	},
+	output: {
+		data_shape: {
+			starred: 'boolean',
+			skill:   'string',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',   next_step: { kind: 'routing',  action: 'discover_schema' } },
+		{ code: 'AUTH_REQUIRED', next_step: { kind: 'recovery', action: 'login'           } },
+	],
+	examples: [
+		'happyskills star acme/deploy-aws',
+		'happyskills star acme/deploy-aws --json',
+	],
+}
+
+module.exports = { run, schema }

package/src/commands/unstar.js

@@ -0,0 +1,81 @@
+const { error: { catch_errors } } = require('puffy-core')
+const { unstar } = require('../api/repos')
+const { require_token } = require('../auth/token_store')
+const { print_help, print_json, print_success } = require('../ui/output')
+const { exit_with_error, UsageError } = require('../utils/errors')
+const { EXIT_CODES } = require('../constants')
+
+const HELP_TEXT = `Usage: happyskills unstar <owner/name> [options]
+
+Remove a skill from your favorites. Idempotent: unstarring a skill you have
+not starred succeeds without error.
+
+Arguments:
+  owner/name        Skill to unstar (e.g., acme/deploy-aws)
+
+Options:
+  --json            Output as JSON
+
+Examples:
+  happyskills unstar acme/deploy-aws
+  happyskills unstar acme/deploy-aws --json`
+
+const run = (args) => catch_errors('Unstar failed', async () => {
+	if (args.flags._show_help) {
+		print_help(HELP_TEXT)
+		return process.exit(EXIT_CODES.SUCCESS)
+	}
+
+	const skill = args._[0]
+	if (!skill) {
+		throw new UsageError('Please specify a skill to unstar (e.g., happyskills unstar acme/deploy-aws).')
+	}
+	if (!skill.includes('/')) {
+		throw new UsageError('Skill must be in owner/name format (e.g., acme/deploy-aws).')
+	}
+
+	await require_token()
+
+	const [owner, name] = skill.split('/')
+	const [errors, result] = await unstar(owner, name)
+	if (errors) throw errors[errors.length - 1]
+
+	if (args.flags.json) {
+		print_json({ data: { starred: false, skill, ...(result || {}) } })
+		return
+	}
+
+	print_success(`Unstarred "${skill}".`)
+}).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
+
+const schema = {
+	name:     'unstar',
+	audience: 'consumer',
+	purpose:  'Remove a skill from your favorites (unstar). Idempotent.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'skill', required: true, type: 'string', pattern: '<owner>/<name>' },
+		],
+		flags: [
+			{ name: 'json', type: 'boolean', default: false },
+		],
+	},
+	output: {
+		data_shape: {
+			starred: 'boolean',
+			skill:   'string',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',   next_step: { kind: 'routing',  action: 'discover_schema' } },
+		{ code: 'AUTH_REQUIRED', next_step: { kind: 'recovery', action: 'login'           } },
+	],
+	examples: [
+		'happyskills unstar acme/deploy-aws',
+		'happyskills unstar acme/deploy-aws --json',
+	],
+}
+
+module.exports = { run, schema }

package/src/commands/whoami.js

@@ -1,7 +1,7 @@
-const { error: { catch_errors, wrap_errors: e } } = require('puffy-core')
+const { error: { catch_errors } } = require('puffy-core')
 const { require_token } = require('../auth/token_store')
-const workspaces_api = require('../api/workspaces')
-const { print_help, print_label, print_json, print_warn, print_hint } = require('../ui/output')
+const { resolve_identity, render_identity_text } = require('../auth/identity')
+const { print_help, print_json } = require('../ui/output')
 const { exit_with_error } = require('../utils/errors')
 const { EXIT_CODES } = require('../constants')
 
@@ -16,17 +16,6 @@ Examples:
   happyskills whoami
   happyskills whoami --json`
 
-const decode_jwt_payload = (token) => {
-	try {
-		const parts = token.split('.')
-		if (parts.length !== 3) return null
-		const payload = Buffer.from(parts[1], 'base64url').toString('utf-8')
-		return JSON.parse(payload)
-	} catch {
-		return null
-	}
-}
-
 const run = (args) => catch_errors('Whoami failed', async () => {
 	if (args.flags._show_help) {
 		print_help(HELP_TEXT)
@@ -34,37 +23,14 @@ const run = (args) => catch_errors('Whoami failed', async () => {
 	}
 
 	const token_data = await require_token()
-
-	const payload = decode_jwt_payload(token_data.id_token)
-	const email = payload?.email || 'unknown'
-	const username = payload?.['cognito:username'] || payload?.sub || 'unknown'
-
-	const [ws_err, workspaces] = await workspaces_api.list_workspaces()
+	const [, identity] = await resolve_identity(token_data)
 
 	if (args.flags.json) {
-		const json_data = { username, email, workspaces: ws_err ? [] : workspaces }
-		if (ws_err) json_data.workspace_error = ws_err.map(er => er.message).join(': ')
-		print_json({ data: json_data })
+		print_json({ data: identity })
 		return
 	}
 
-	print_label('Username', username)
-	print_label('Email', email)
-
-	if (ws_err) {
-		console.log()
-		print_warn(`Failed to list workspaces: ${ws_err.map(er => er.message).join(': ')}`)
-		print_hint('Check your authentication with happyskills login')
-	} else if (workspaces && workspaces.length > 0) {
-		console.log()
-		print_label('Workspaces', '')
-		for (const ws of workspaces) {
-			const type_label = ws.is_owner
-				? ws.type === 'personal' ? ' (personal)' : ' (organization)'
-				: ''
-			console.log(`  ${ws.slug}${type_label}`)
-		}
-	}
+	render_identity_text(identity)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
 const schema = {

package/src/constants.js

@@ -51,6 +51,8 @@ const COMMANDS = [
 	'visibility',
 	'list',
 	'search',
+	'star',
+	'unstar',
 	'check',
 	'status',
 	'pull',

package/src/engine/installer.js

@@ -22,6 +22,13 @@ const _format_warnings = (missing_deps) => (missing_deps || []).map(dep => {
 	return `Missing system dependency: ${dep.name} required by ${dep.skill}${hint}`
 })
 
+// Circular dependencies the resolver broke automatically. The install is safe and terminates,
+// but the author should remove one edge — so we surface a warning rather than failing silently.
+const _format_cycle_warnings = (cycles) => (cycles || []).map(({ from, to }) =>
+	`Circular dependency detected: ${from} depends on ${to}, which depends back on ${from}. ` +
+	`The install completed safely (the cycle was broken automatically), but you should remove one ` +
+	`direction of the dependency.`)
+
 // Order-preserving, de-duplicated union of requester lists.
 const _union = (...lists) => {
 	const seen = new Set()
@@ -103,16 +110,19 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 
 	let packages
 	let skipped_deps = []
+	let cycles = []
 	if (force) {
 		const [errors, result] = await resolve_with_force(skill, version || 'latest', {})
 		if (errors) { spinner.fail('Resolution failed'); throw e('Resolution failed', errors) }
 		packages = result.packages
 		skipped_deps = result.skipped || []
+		cycles = result.cycles || []
 	} else {
 		const [errors, result] = await resolve(skill, version || 'latest', {})
 		if (errors) { spinner.fail('Resolution failed'); throw e('Resolution failed', errors) }
 		packages = result.packages
 		skipped_deps = result.skipped || []
+		cycles = result.cycles || []
 	}
 
 	// Filter out packages already installed at the resolved version (handles @latest efficiently)
@@ -343,10 +353,15 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 			}
 		}
 
+		// Warn about circular dependencies. The resolver broke the cycle automatically (so the
+		// install is safe and terminates), but the author should still remove one edge.
+		const cycle_warnings = _format_cycle_warnings(cycles)
+		for (const w of cycle_warnings) print_warn(w)
+
 		const installed_set = new Set(packages_to_install.map(p => p.skill))
 		const installed = packages_to_install.map(p => ({ skill: p.skill, version: p.version }))
 		const skipped = packages.filter(p => !installed_set.has(p.skill)).map(p => ({ skill: p.skill, version: p.version, reason: 'already installed' }))
-		const warnings = _format_warnings(missing_deps)
+		const warnings = [..._format_warnings(missing_deps), ...cycle_warnings]
 		const forced = forced_pkgs.map(p => ({ skill: p.skill, version: p.version }))
 
 		const linked_agents = agents.map(a => a.id)

package/src/engine/resolver.js

@@ -12,7 +12,7 @@ const resolve = (skill, version, installed = {}) => catch_errors('Dependency res
 		throw new Error(`Dependency conflicts detected:\n${conflict_msg}\n\nUse --force to install anyway (takes highest version).`)
 	}
 
-	return { packages: result.packages || [], skipped: result.skipped || [] }
+	return { packages: result.packages || [], skipped: result.skipped || [], cycles: result.cycles || [] }
 })
 
 const resolve_with_force = (skill, version, installed = {}) => catch_errors('Forced resolution failed', async () => {
@@ -30,7 +30,7 @@ const resolve_with_force = (skill, version, installed = {}) => catch_errors('For
 		}
 	}
 
-	return { packages, skipped: result.skipped || [] }
+	return { packages, skipped: result.skipped || [], cycles: result.cycles || [] }
 })
 
 module.exports = { resolve, resolve_with_force }

package/src/index.js

@@ -103,6 +103,8 @@ Commands:
   visibility <owner/skill> Check or set visibility (alias: vis)
   list                     List installed skills (alias: ls)
   search <query>           Search the registry (alias: s)
+  star <owner/skill>       Star a skill (add to your favorites)
+  unstar <owner/skill>     Remove a skill from your favorites
   postlex                  Apply deterministic rerank finalization (agent-only; see happyskills-help skill)
   versions <owner/skill>   List all published versions of a skill
   changelog <owner/skill>  Print a skill's CHANGELOG.md

package/src/integration/cli.test.js

@@ -403,6 +403,10 @@ describe('CLI — --json: success envelopes', () => {
 			assert.strictEqual(env.data.status, 'already_logged_in')
 			assert.strictEqual(env.data.username, 'testuser')
 			assert.strictEqual(env.data.email, 'test@example.com')
+			// Content parity with whoami: login carries the workspaces block too.
+			// The dummy API host (localhost:0) is unreachable, so the best-effort
+			// lookup degrades to an empty list — it must never fail the login.
+			assert.ok(Array.isArray(env.data.workspaces), 'login data.workspaces must be an array')
 		} finally {
 			fs.rmSync(tmp_xdg, { recursive: true, force: true })
 		}

package/src/validation/dependency_rules.js

@@ -172,27 +172,40 @@ const check_visibility_transitive = async (manifest, visibility, repos_api) => {
 const check_circular = async (manifest, repos_api) => {
 	const results = []
 	const deps = manifest.dependencies || {}
+	const dep_names = Object.keys(deps)
 
-	if (Object.keys(deps).length === 0) return results
+	if (dep_names.length === 0) return results
 
 	const skill_name = manifest._full_name
 	if (!skill_name) return results
 
-	const [err, data] = await repos_api.resolve_dependencies(skill_name, manifest.version || 'latest', {})
-	if (err) return results
-
-	const packages = data.packages || []
-
-	// Build adjacency map from declared dependencies
+	// Resolve each DIRECT dependency's published subtree — NOT the root's. The root's published
+	// manifest can be stale: when you publish the very edge that closes a cycle, the registry's
+	// view of the root does not yet contain that edge, so resolving the root would hide the
+	// cycle. Resolving the dependencies' subtrees and then grafting the LOCAL (about-to-be-
+	// published) root edges on top reflects the graph as it will be AFTER this publish — which
+	// is exactly what we must validate.
+	const subtrees = await Promise.all(
+		dep_names.map(dep => repos_api.resolve_dependencies(dep, 'latest', {}))
+	)
+
+	// Merge every resolved package into one adjacency map (the registry's current view).
 	const adj = {}
-	for (const pkg of packages) {
-		adj[pkg.skill] = Object.keys(pkg.dependencies || {})
+	for (const [sub_err, data] of subtrees) {
+		if (sub_err || !data) continue
+		for (const pkg of (data.packages || [])) {
+			if (adj[pkg.skill] === undefined) adj[pkg.skill] = Object.keys(pkg.dependencies || {})
+		}
 	}
 
-	// DFS cycle detection
+	// Graft the LOCAL edges for the root. This overrides any stale published view of the root
+	// that a dependency's subtree may have included, making a cycle the new edges create visible.
+	adj[skill_name] = dep_names
+
+	// DFS cycle detection (WHITE/GRAY/BLACK colouring). Start from the root so reported cycles
+	// are rooted at the skill being published; then cover any unreachable nodes defensively.
 	const WHITE = 0, GRAY = 1, BLACK = 2
 	const color = {}
-	const parent = {}
 	const cycles = []
 
 	const dfs = (node, path_so_far) => {
@@ -213,16 +226,20 @@ const check_circular = async (manifest, repos_api) => {
 		color[node] = BLACK
 	}
 
+	dfs(skill_name, [skill_name])
 	for (const node of Object.keys(adj)) {
-		if ((color[node] || WHITE) === WHITE) {
-			dfs(node, [node])
-		}
+		if ((color[node] || WHITE) === WHITE) dfs(node, [node])
 	}
 
 	if (cycles.length > 0) {
+		// De-duplicate identical cycle paths (the same cycle can be reached from multiple starts).
+		const seen = new Set()
 		for (const cycle of cycles) {
+			const key = cycle.join(' → ')
+			if (seen.has(key)) continue
+			seen.add(key)
 			results.push(result('dependencies', 'dep-circular', 'error',
-				`Circular dependency detected: ${cycle.join(' → ')}. ` +
+				`Circular dependency detected: ${key}. ` +
 				`Remove one direction of the dependency to break the cycle.`,
 				cycle))
 		}

package/src/validation/dependency_rules.test.js

@@ -158,6 +158,30 @@ describe('dep-circular (registry)', () => {
 		const check = results.find(r => r.rule === 'dep-circular')
 		assert.strictEqual(check.severity, 'pass')
 	})
+
+	it('detects a cycle created by the very edge being published (stale root view)', async () => {
+		// Registry view: the dependency (acme/b) depends back on the root (acme/a), but the
+		// root's PUBLISHED manifest still has empty deps — the cycle-closing edge (acme/a → acme/b)
+		// exists only in the LOCAL manifest being validated. The check must graft the local edge
+		// onto the resolved subtree, otherwise this cycle slips into the registry undetected.
+		const manifest = { name: 'a', version: '0.2.0', dependencies: { 'acme/b': '*' } }
+		const resolve_result = {
+			packages: [
+				{ skill: 'acme/b', version: '1.0.0', dependencies: { 'acme/a': '*' } },
+				{ skill: 'acme/a', version: '1.0.0', dependencies: {} } // stale: published root has no deps yet
+			],
+			skipped: []
+		}
+		const api = make_mock_api({ 'acme/b': { visibility: 'public' } }, resolve_result)
+		const [err, results] = await validate_dependencies(tmp, manifest, {
+			registry: true, full_name: 'acme/a', repos_api: api
+		})
+		assert.ifError(err)
+		const check = results.find(r => r.rule === 'dep-circular' && r.severity === 'error')
+		assert.ok(check, 'should detect the cycle created by the local closing edge')
+		assert.ok(check.message.includes('acme/a'))
+		assert.ok(check.message.includes('acme/b'))
+	})
 })
 
 describe('dep-visibility-transitive (registry)', () => {