happyskills 1.1.0 → 1.2.0

package/src/commands/install.js

@@ -260,4 +260,38 @@ const run = (args) => catch_errors('Install failed', async () => {
 	print_hint(`See what's installed: ${code('happyskills list')}`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'install',
+	audience: 'consumer',
+	purpose:  'Install one or more skills and their dependencies; without arguments installs all dependencies from skill.json or skills-lock.json.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [ { name: 'skills', required: false, type: 'string[]', pattern: '<owner>/<name>[@<version>]' } ],
+		flags: [
+			{ name: 'global',   alias: 'g',       type: 'boolean', default: false,     description: 'Install globally (~/.agents/skills/)' },
+			{ name: 'version',                    type: 'string',  default: undefined, description: 'Pin to specific version (single skill only)' },
+			{ name: 'force',                      type: 'boolean', default: false,     description: 'Force install on dependency conflicts' },
+			{ name: 'fresh',                      type: 'boolean', default: false,     description: 'Ignore lock file, re-resolve from scratch' },
+			{ name: 'agents',                     type: 'string',  default: undefined, description: 'Target specific agents (comma-separated)' },
+			{ name: 'yes',      alias: 'y',       type: 'boolean', default: false,     description: 'Skip confirmation prompts' },
+			{ name: 'json',                        type: 'boolean', default: false,     description: 'Output as JSON' },
+		],
+	},
+	output: {
+		data_shape: {
+			results: 'array<{ skill: string, status: string, version: string, installed: string[], skipped: string[], skipped_deps: string[], warnings: string[], forced: string[], snapshot_id?: string } | { skill: string, status: "failed", error: { code: string, message: string } }>',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',         next_step: { kind: 'routing',       action: 'discover_schema' } },
+		{ code: 'LOCAL_EDITS_PRESENT', next_step: { kind: 'confirmation',  action: 'confirm_discard_or_snapshot_first' } },
+		{ code: 'VERSION_NOT_FOUND',   next_step: { kind: 'decision',      action: 'pick_version' } },
+	],
+	examples: [
+		'happyskills install acme/deploy-aws',
+		'happyskills install acme/deploy-aws@1.2.0 acme/monitor@latest',
+	],
+}
+
+module.exports = { run, schema }

package/src/commands/list.js

@@ -199,4 +199,32 @@ const run = (args) => catch_errors('List failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'list',
+	audience: 'consumer',
+	purpose:  'List installed skills, showing version, source, drift/ahead status, and agent-enabled state.',
+	mutation: false,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [],
+		flags: [
+			{ name: 'global', alias: 'g', type: 'boolean', default: false, description: 'List globally installed skills' },
+			{ name: 'json',               type: 'boolean', default: false, description: 'Output as JSON' },
+		],
+	},
+	output: {
+		data_shape: {
+			skills:       'object<string, { version: string, type: string, source: string, status: string, enabled: boolean, drift?: object, ahead?: object }>',
+			drafts:       'array<{ name: string, description: string, version: string|null, type: string }>',
+			external:     'array<{ name: string, description: string }>',
+			agent_orphans: 'array<{ name: string, description: string, agents: string[] }>',
+		},
+	},
+	errors: [],
+	examples: [
+		'happyskills list',
+		'happyskills ls --json',
+	],
+}
+
+module.exports = { run, schema }

package/src/commands/login.js

@@ -218,4 +218,37 @@ const run = (args) => catch_errors('Login failed', async () => {
 	print_hint(`Verify your identity: ${code('happyskills whoami')}`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'login',
+	audience: 'account',
+	purpose:  'Authenticate with the HappySkills registry via browser (device flow) or password; returns current auth status when already logged in.',
+	mutation: true,
+	interactive_in_text_mode: true,
+	input: {
+		positional: [],
+		flags: [
+			{ name: 'browser',  type: 'boolean', default: false },
+			{ name: 'password', type: 'boolean', default: false },
+			{ name: 'json',     type: 'boolean', default: false },
+		],
+	},
+	output: {
+		data_shape: {
+			status:   'string',
+			username: 'string',
+			email:    'string',
+		},
+	},
+	errors: [
+		{ code: 'INTERACTIVE_REQUIRED' },
+		{ code: 'INVALID_CREDENTIALS'  },
+		{ code: 'AUTH_FAILED',          next_step: { kind: 'recovery', action: 'login' } },
+		{ code: 'NETWORK_ERROR',        next_step: { kind: 'recovery', action: 'retry' } },
+	],
+	examples: [
+		'happyskills login',
+		'happyskills login --json --browser',
+	],
+}
+
+module.exports = { run, schema }

package/src/commands/logout.js

@@ -30,4 +30,23 @@ const run = (args) => catch_errors('Logout failed', async () => {
 	print_hint(`Log back in: ${code('happyskills login')}`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'logout',
+	audience: 'account',
+	purpose:  'Clear stored authentication credentials from disk.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [],
+		flags: [
+			{ name: 'json', type: 'boolean', default: false }
+		]
+	},
+	output: { data_shape: { status: 'string' } },
+	errors: [],
+	examples: [
+		'happyskills logout'
+	]
+}
+
+module.exports = { run, schema }

package/src/commands/people.js

@@ -159,4 +159,40 @@ const run = (args) => catch_errors('People command failed', async () => {
 	throw new UsageError(`Unknown subcommand: ${sub}. Run happyskills people --help`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name: 'people',
+	audience: 'account',
+	purpose: 'Manage workspace membership: list, add, remove, change roles, and search users.',
+	mutation: true,
+	interactive_in_text_mode: true,
+	input: {
+		positional: [
+			{ name: 'subcommand', required: true, type: 'string', enum: ['list', 'add', 'remove', 'role', 'search'] }
+		],
+		flags: [
+			{ name: 'workspace', alias: 'w', type: 'string' },
+			{ name: 'role', type: 'string' },
+			{ name: 'limit', type: 'number' },
+			{ name: 'yes', alias: 'y', type: 'boolean' },
+			{ name: 'json', type: 'boolean' }
+		]
+	},
+	output: {
+		data_shape: {
+			results: 'array<{ username: string, email: string, role: string, created_at: string }>'
+		}
+	},
+	errors: [
+		{ code: 'AUTH_REQUIRED', next_step: { kind: 'recovery', action: 'login' } },
+		{ code: 'USAGE_ERROR', next_step: { kind: 'routing', action: 'discover_schema' } },
+		{ code: 'NOT_FOUND' },
+		{ code: 'FORBIDDEN' },
+		{ code: 'NETWORK_ERROR', next_step: { kind: 'recovery', action: 'retry' } }
+	],
+	examples: [
+		'happyskills people list -w acme',
+		'happyskills people add -w acme alice --role admin'
+	]
+}
+
+module.exports = { run, schema }

package/src/commands/postlex.js

@@ -518,8 +518,46 @@ const run = (args) => catch_errors('Postlex failed', async () => {
 	console.log(`\n${gray(`Showing ${final_ordering.length} result${final_ordering.length === 1 ? '' : 's'}.`)}\n`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
+const schema = {
+	name:     'postlex',
+	audience: 'consumer',
+	purpose:  'Apply deterministic slug-overlap promotion to an LLM-emitted ranking and emit a next_step envelope; the finalization step of the rerank discovery protocol.',
+	mutation: false,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [],
+		flags: [
+			{ name: 'query',                       type: 'string',  required: true,     description: 'The original search query (used for slug-overlap scoring)' },
+			{ name: 'ranking',                     type: 'string',  required: true,     description: 'Path to ranking JSON, or `-` for stdin' },
+			{ name: 'search-output',               type: 'string',  default: undefined, description: 'Path to full search --with-rerank --json response envelope (recommended)' },
+			{ name: 'data',                        type: 'string',  default: undefined, description: 'Legacy: separate data file when --ranking does not embed it' },
+			{ name: 'clarification-turns-used',    type: 'number',  default: 0,         description: 'Clarification budget already spent (0-2)' },
+			{ name: 'original-query',              type: 'string',  default: undefined, description: 'Original user query (opaque context from prior step)' },
+			{ name: 'json',                         type: 'boolean', default: false,     description: 'Output as JSON' },
+		],
+	},
+	output: {
+		data_shape: {
+			final_ordering:              'array<{ rank: number, candidate_id: number, slug: string, name: string, workspace_slug: string|null, description: string, version: string, match_quality: string|null, quality_score: number|null, star_count: number, rationale: string }>',
+			postlex_promoted:            'boolean',
+			promoted_from_rank:          'number|null',
+			exact_match_count_in_window: 'number',
+			formulated_query:            'string',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',              next_step: { kind: 'routing',  action: 'discover_schema' } },
+		{ code: 'RANKING_SCHEMA_MISMATCH',  next_step: { kind: 'recovery', action: 'retry_rank' } },
+	],
+	examples: [
+		'happyskills postlex --query "deploy aws" --ranking - --search-output /tmp/search-out.json',
+		'happyskills postlex --query "deploy aws" --ranking r.json --data d.json --json',
+	],
+}
+
 module.exports = {
 	run,
+	schema,
 	// Exported for unit testing — pure functions only.
 	validate_ranking,
 	apply_postlex,

package/src/commands/publish.js

@@ -339,4 +339,43 @@ const run = (args) => catch_errors('Publish failed', async () => {
 	print_hint(`Check versions: ${code('happyskills check')}`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'publish',
+	audience: 'author',
+	purpose:  'Push a skill to the registry, resolving the owner workspace from skills-lock.json; optionally bumps the version before publishing.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [ { name: 'skill', required: true, type: 'string', description: 'Name of the installed skill' } ],
+		flags: [
+			{ name: 'bump',      type: 'string',  default: undefined, description: 'Auto-bump version before publishing (patch, minor, major)' },
+			{ name: 'workspace', type: 'string',  default: undefined, description: 'Target workspace (overrides lock file owner)' },
+			{ name: 'public',    type: 'boolean', default: false,     description: 'Publish as public (default is private)' },
+			{ name: 'force',     type: 'boolean', default: false,     description: 'Bypass divergence check (may overwrite remote changes)' },
+			{ name: 'json',      type: 'boolean', default: false,     description: 'Output as JSON' },
+		],
+	},
+	output: {
+		data_shape: {
+			skill:        'string',
+			version:      'string',
+			ref:          'string',
+			commit:       'string | null',
+			bumped_from:  'string | null',
+			warnings:     'string[] | undefined',
+		},
+	},
+	errors: [
+		{ code: 'AUTH_REQUIRED',                next_step: { kind: 'recovery', action: 'login' } },
+		{ code: 'VALIDATION_FAILED',            next_step: { kind: 'recovery', action: 'fix_validation_errors' } },
+		{ code: 'DEPENDENCY_VALIDATION_FAILED', next_step: { kind: 'recovery', action: 'fix_validation_errors' } },
+		{ code: 'USAGE_ERROR',                  next_step: { kind: 'routing',  action: 'discover_schema' } },
+		{ code: 'NETWORK_ERROR',                next_step: { kind: 'recovery', action: 'retry' } },
+	],
+	examples: [
+		'happyskills publish my-skill',
+		'happyskills publish deploy-aws --bump patch',
+	],
+}
+
+module.exports = { run, schema }

package/src/commands/pull.js

@@ -611,4 +611,50 @@ const reconcile_dependencies = (skill_dir, skill_name, lock_data, is_global, pro
 		}
 	})
 
-module.exports = { run }
+const schema = {
+	name: 'pull',
+	audience: 'consumer',
+	purpose: 'Pull remote changes for an installed skill and merge with local files, with optional rebase or conflict-resolution strategies.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [{ name: 'skill', required: true, type: 'string', pattern: '<owner>/<name>' }],
+		flags: [
+			{ name: 'theirs', type: 'string|boolean', default: false },
+			{ name: 'ours', type: 'string|boolean', default: false },
+			{ name: 'force', type: 'boolean', default: false },
+			{ name: 'rebase', type: 'boolean', default: false },
+			{ name: 'global', type: 'boolean', default: false },
+			{ name: 'strict', type: 'boolean', default: false },
+			{ name: 'json', type: 'boolean', default: false },
+			{ name: 'full-report', type: 'boolean', default: false }
+		]
+	},
+	output: {
+		data_shape: {
+			status: 'string',
+			skill: 'string',
+			version: 'string|null',
+			report: 'object',
+			conflict_files: 'array<string>',
+			json_conflicts: 'array<object>',
+			drift: 'object|null',
+			resolution_steps: 'array|null'
+		}
+	},
+	errors: [
+		{ code: 'USAGE_ERROR', next_step: { kind: 'routing', action: 'discover_schema' } },
+		// --rebase pipeline failures — recover by retrying or abandoning to the snapshot
+		{ code: 'COMPARE_FAILED',      next_step: { kind: 'recovery', action: 'retry_or_abandon' } },
+		{ code: 'CLONE_BASE_FAILED',   next_step: { kind: 'recovery', action: 'retry_or_abandon' } },
+		{ code: 'CLONE_REMOTE_FAILED', next_step: { kind: 'recovery', action: 'retry_or_abandon' } },
+		{ code: 'READ_LOCAL_FAILED',   next_step: { kind: 'recovery', action: 'retry_or_abandon' } },
+		{ code: 'SWAP_FAILED',         next_step: { kind: 'recovery', action: 'retry_or_abandon' } }
+	],
+	examples: [
+		'happyskills pull acme/deploy-aws',
+		'happyskills pull acme/deploy-aws --rebase --json'
+	]
+}
+
+module.exports = { run, schema }

package/src/commands/reconcile.js

@@ -274,4 +274,39 @@ const run = (args) => catch_errors('Reconcile failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run, reconcile_one, SUBTYPE_OPTIONS, ACTION_NEXT_STEPS }
+const schema = {
+	name:     'reconcile',
+	audience: 'consumer',
+	purpose:  'Diagnose and repair genuine drift between the lock file and disk (regression, missing files, or unparseable skill.json); the ahead state is not drift and is reported as a non-event.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [ { name: 'skill', required: true, type: 'string', pattern: '<owner>/<name>' } ],
+		flags: [
+			{ name: 'apply',  type: 'string',  default: undefined, description: 'Execute one of the recommended options directly (skips the next_step round-trip)' },
+			{ name: 'global', alias: 'g', type: 'boolean', default: false, description: 'Operate on globally-installed skills' },
+			{ name: 'json',   type: 'boolean', default: false,     description: 'Output as JSON' },
+		],
+	},
+	output: {
+		data_shape: {
+			skill:         'string',
+			no_drift:      'boolean',
+			status:        'string',
+			drift_state:   'string',
+			applied:       '{ applied: string, new_disk_version: string } | undefined',
+			lock_version:  'string | undefined',
+			disk_version:  'string | undefined',
+			ahead:         '{ lock_version: string, disk_version: string, has_changelog_entry: boolean, changelog_version: string | null } | undefined',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR', next_step: { kind: 'routing', action: 'discover_schema' } },
+	],
+	examples: [
+		'happyskills reconcile acme/deploy-aws --json',
+		'happyskills reconcile acme/deploy-aws --apply restore_from_lock_version --json',
+	],
+}
+
+module.exports = { run, reconcile_one, SUBTYPE_OPTIONS, ACTION_NEXT_STEPS, schema }

package/src/commands/release.js

@@ -481,4 +481,54 @@ const run = (args) => catch_errors('Release wrapper failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run, orchestrate, determine_target_version, compute_bump }
+const schema = {
+	name:     'release',
+	audience: 'author',
+	purpose:  'Atomic release pipeline: snapshot, validate, bump version, verify CHANGELOG, and publish in one deterministic command; restores the snapshot on any failure.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [ { name: 'skill', required: true, type: 'string', description: 'Name of the skill to release' } ],
+		flags: [
+			{ name: 'bump',           type: 'string',  default: undefined, description: 'patch | minor | major | explicit semver' },
+			{ name: 'no-bump',        type: 'boolean', default: false,     description: 'Refuse to bump; require disk to already be ahead' },
+			{ name: 'changelog-from', type: 'string',  default: undefined, description: 'Source for the new CHANGELOG entry (auto or file path)' },
+			{ name: 'workspace',      type: 'string',  default: undefined, description: 'Target workspace slug' },
+			{ name: 'public',         type: 'boolean', default: false,     description: 'Publish as public on first publish' },
+			{ name: 'dry-run',        type: 'boolean', default: false,     description: 'Validate and check status without mutating' },
+			{ name: 'json',           type: 'boolean', default: false,     description: 'Output as JSON' },
+		],
+	},
+	output: {
+		data_shape: {
+			published:            'boolean',
+			skill:                'string',
+			version:              'string',
+			workspace:            'string',
+			commit:               'string | null',
+			ref:                  'string',
+			ahead_recognized:     'boolean',
+			bump_applied:         'boolean',
+			warnings:             'string[]',
+			snapshot_id_preserved: 'boolean',
+		},
+	},
+	errors: [
+		{ code: 'VALIDATION_FAILED',        next_step: { kind: 'recovery',  action: 'fix_validation_errors' } },
+		{ code: 'DRIFT_DETECTED',           next_step: { kind: 'recovery',  action: 'reconcile_first' } },
+		{ code: 'MISSING_VERSION',          next_step: { kind: 'decision',  action: 'specify_bump_type' } },
+		{ code: 'INVALID_BUMP',             next_step: { kind: 'decision',  action: 'specify_bump_type' } },
+		{ code: 'BUMP_DISAGREEMENT',        next_step: { kind: 'decision',  action: 'resolve_bump_disagreement' } },
+		{ code: 'CHANGELOG_SOURCE_UNREADABLE', next_step: { kind: 'recovery', action: 'provide_changelog' } },
+		{ code: 'MISSING_CHANGELOG_ENTRY',  next_step: { kind: 'recovery',  action: 'provide_changelog' } },
+		{ code: 'WORKSPACE_UNRESOLVED',     next_step: { kind: 'decision',  action: 'specify_workspace' } },
+		{ code: 'WRITE_FAILED',             next_step: { kind: 'recovery',  action: 'retry' } },
+		{ code: 'PUBLISH_FAILED',           next_step: { kind: 'recovery',  action: 'review_publish_error' } },
+	],
+	examples: [
+		'happyskills release my-skill --workspace acme --json',
+		'happyskills release my-skill --bump patch --workspace acme --json',
+	],
+}
+
+module.exports = { run, orchestrate, determine_target_version, compute_bump, schema }

package/src/commands/schema.js

@@ -84,6 +84,7 @@ const default_schema = (name) => ({
 	input: { positional: [], flags: [] },
 	output: { data_shape: {} },
 	errors: [],
+	examples: [],
 })
 
 // Load the per-command schema export. Misses fall back to default_schema.
@@ -174,6 +175,10 @@ const schema = {
 		next_step_kinds:         'array<string>',
 	} },
 	errors: [],
+	examples: [
+		'happyskills schema --json',
+		'happyskills schema --text',
+	],
 }
 
 module.exports = { run, schema, build_schema_payload }

package/src/commands/search.js

@@ -435,4 +435,49 @@ const run = (args) => catch_errors('Search failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run, build_search_next_step }
+const schema = {
+	name:     'search',
+	audience: 'consumer',
+	purpose:  'Search the skill registry using smart semantic dispatch (natural-language, fuzzy-slug, or fuzzy-scoped); use --with-rerank to get the rerank-protocol envelope for agentic discovery.',
+	mutation: false,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [ { name: 'query', required: false, type: 'string', description: 'Search term (optional with --mine/--personal/--workspace)' } ],
+		flags: [
+			{ name: 'workspace',                  alias: 'w',  type: 'string',  default: undefined, description: 'Search within specific workspace(s) (comma-separated)' },
+			{ name: 'mine',                                     type: 'boolean', default: false,     description: 'Search across all your workspaces' },
+			{ name: 'personal',                                 type: 'boolean', default: false,     description: 'Search only your personal workspace' },
+			{ name: 'tags',                                     type: 'string',  default: undefined, description: 'Filter by tags (comma-separated)' },
+			{ name: 'type',                                     type: 'string',  default: undefined, description: 'Filter by type: skill, kit' },
+			{ name: 'exact',                                    type: 'boolean', default: false,     description: 'Force keyword-only FTS matching' },
+			{ name: 'with-rerank',                              type: 'boolean', default: false,     description: 'Include rerank digests + next_step envelope (agentic discovery protocol)' },
+			{ name: 'clarification-turns-used',                 type: 'number',  default: 0,         description: 'Clarification budget already spent (0-2)' },
+			{ name: 'limit',                                    type: 'number',  required: true,     description: 'Max results (1-50)' },
+			{ name: 'min-quality',                              type: 'number',  default: undefined, description: 'Minimum quality score 0-100' },
+			{ name: 'json',                                     type: 'boolean', default: false,     description: 'Output as JSON' },
+		],
+	},
+	output: {
+		data_shape: {
+			query:            'string',
+			formulated_query: 'string',
+			mode:             'string',
+			results:          'array<{ skill: string, name: string, type: string, description: string, version: string, visibility: string, workspace_slug: string, stars: number, quality_score: number|null, quality_tier: string|null, relevance_score: number|null, match_quality: string|null, tags: string[], download_count: number, created_at: string, updated_at: string, similar_count: number, similar_repos: array }>',
+			count:            'number',
+			rerank_digests:   'array (present when --with-rerank)',
+			rerank_system_prompt: 'string|null (present when --with-rerank)',
+			rerank_response_schema: 'object|null (present when --with-rerank)',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',    next_step: { kind: 'routing',   action: 'discover_schema' } },
+		{ code: 'AUTH_REQUIRED',  next_step: { kind: 'recovery',  action: 'login' } },
+		{ code: 'NETWORK_ERROR',  next_step: { kind: 'recovery',  action: 'retry' } },
+	],
+	examples: [
+		'happyskills search "deploy infra to AWS" --limit 10',
+		'happyskills search "deploy infra to AWS" --with-rerank --json --limit 50',
+	],
+}
+
+module.exports = { run, build_search_next_step, schema }

package/src/commands/self-update.js

@@ -80,4 +80,30 @@ const run = (args) => catch_errors('Self-update failed', async () => {
 	print_hint(`Run ${code('happyskills --version')} to confirm.`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'self-update',
+	audience: 'account',
+	purpose:  'Upgrade the happyskills CLI to the latest version published on npm.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [],
+		flags: [
+			{ name: 'json', type: 'boolean', default: false }
+		]
+	},
+	output: {
+		data_shape: {
+			status: 'string',
+			version: 'string'
+		}
+	},
+	errors: [
+		{ code: 'NETWORK_ERROR', next_step: { kind: 'recovery', action: 'retry' } }
+	],
+	examples: [
+		'happyskills self-update'
+	]
+}
+
+module.exports = { run, schema }

package/src/commands/setup.js

@@ -55,4 +55,35 @@ const run = (args) => catch_errors('Setup failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'setup',
+	audience: 'account',
+	purpose:  'Install (or update) the official HappySkills CLI skill into the local or global agent skills directory.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [],
+		flags: [
+			{ name: 'global',  type: 'boolean', default: false },
+			{ name: 'agents',  type: 'string',  default: null },
+			{ name: 'json',    type: 'boolean', default: false }
+		]
+	},
+	output: {
+		data_shape: {
+			skill: 'string',
+			version: 'string',
+			status: 'string'
+		}
+	},
+	errors: [
+		{ code: 'NETWORK_ERROR', next_step: { kind: 'recovery', action: 'retry' } },
+		{ code: 'REGISTRY_UNAVAILABLE', next_step: { kind: 'recovery', action: 'retry' } }
+	],
+	examples: [
+		'happyskills setup',
+		'happyskills setup -g'
+	]
+}
+
+module.exports = { run, schema }

package/src/commands/snapshot.js

@@ -249,4 +249,41 @@ const run = (args) => catch_errors('Snapshot failed', async () => {
 	if (err) throw err
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'snapshot',
+	audience: 'consumer',
+	purpose:  'Capture and restore skill state — create, list, restore, delete, or prune snapshots as a safety net for every mutation.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'subcommand', required: true, type: 'string', enum: ['create', 'list', 'restore', 'delete', 'prune'] },
+			{ name: 'target',     required: true, type: 'string', description: '<owner/skill> for create/list/prune; <snapshot-id> for restore/delete' },
+		],
+		flags: [
+			{ name: 'note',   type: 'string',  default: undefined, description: 'Attach a note to a new snapshot (create only)' },
+			{ name: 'keep',   type: 'number',  default: 10,        description: 'Retention count for prune' },
+			{ name: 'global', alias: 'g', type: 'boolean', default: false, description: 'Operate on the global snapshot store' },
+			{ name: 'json',   type: 'boolean', default: false,     description: 'Output as JSON' },
+		],
+	},
+	output: {
+		data_shape: {
+			'create':  '{ snapshot_id: string, path: string, note?: string, pruned?: string[] }',
+			'list':    '{ workspace: string, skill: string, snapshots: array<{ snapshot_id: string, timestamp: string, note: string }> }',
+			'restore': '{ workspace: string, skill: string, snapshot_id: string }',
+			'delete':  '{ deleted: boolean, snapshot_id: string, reason?: string }',
+			'prune':   '{ kept: number, deleted: number }',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',      next_step: { kind: 'routing', action: 'discover_schema' } },
+		{ code: 'SNAPSHOT_FAILED' },
+	],
+	examples: [
+		'happyskills snapshot create acme/deploy-aws --note "pre-release" --json',
+		'happyskills snapshot restore snap_20260523T103045Z_abc123 --json',
+	],
+}
+
+module.exports = { run, schema }

package/src/commands/status.js

@@ -224,4 +224,29 @@ const run = (args) => catch_errors('Status failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name: 'status',
+	audience: 'consumer',
+	purpose: 'Show divergence status for installed skills — drift, ahead, modified, outdated, conflicts, or clean.',
+	mutation: false,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [{ name: 'skill', required: false, type: 'string', pattern: '<owner>/<name>' }],
+		flags: [
+			{ name: 'global', type: 'boolean', default: false },
+			{ name: 'json', type: 'boolean', default: false }
+		]
+	},
+	output: {
+		data_shape: {
+			results: 'array<{ skill: string, base_version: string|null, base_commit: string|null, local_modified: boolean, modified_files: array|null, remote_updated: boolean, remote_version: string|null, remote_commit: string|null, conflict_files: array, drift: object|null, ahead: object|null, status: string }>'
+		}
+	},
+	errors: [],
+	examples: [
+		'happyskills status',
+		'happyskills status acme/deploy-aws'
+	]
+}
+
+module.exports = { run, schema }