happyskills 1.0.2 → 1.2.0

package/src/commands/uninstall.js

@@ -93,4 +93,33 @@ const run = (args) => catch_errors('Uninstall failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'uninstall',
+	audience: 'consumer',
+	purpose:  'Remove one or more skills and prune their orphaned dependencies.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [ { name: 'skills', required: true, type: 'string[]', pattern: '<owner>/<name>' } ],
+		flags: [
+			{ name: 'global',  alias: 'g',       type: 'boolean', default: false,     description: 'Remove from global scope' },
+			{ 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, removed: string[], orphans_pruned: string[] } | { skill: string, status: "failed", error: { code: string, message: string } }>',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR', next_step: { kind: 'routing', action: 'discover_schema' } },
+	],
+	examples: [
+		'happyskills uninstall acme/deploy-aws',
+		'happyskills uninstall acme/deploy-aws acme/monitor acme/logging',
+	],
+}
+
+module.exports = { run, schema }

package/src/commands/update.js

@@ -333,4 +333,43 @@ const run = (args) => catch_errors('Update failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name: 'update',
+	audience: 'consumer',
+	purpose: 'Bring installed skills up to date by batch-checking the registry and re-installing only outdated skills.',
+	mutation: true,
+	interactive_in_text_mode: true,
+	input: {
+		positional: [{ name: 'skill', required: false, type: 'string', pattern: '<owner>/<name>' }],
+		flags: [
+			{ name: 'all', type: 'boolean', default: false },
+			{ name: 'force', type: 'boolean', default: false },
+			{ name: 'global', type: 'boolean', default: false },
+			{ name: 'yes', type: 'boolean', default: false },
+			{ name: 'agents', type: 'string', default: null },
+			{ name: 'json', type: 'boolean', default: false }
+		]
+	},
+	output: {
+		data_shape: {
+			results: 'array<{ skill: string, installed: string, latest: string, status: string }>',
+			outdated_count: 'number',
+			up_to_date_count: 'number',
+			drift_count: 'number',
+			updated: 'array<{ skill: string, from: string, to: string }>',
+			skipped: 'array<{ skill: string, reason: string, suggestion: string }>',
+			already_up_to_date: 'array<{ skill: string, version: string }>',
+			symlink_repairs: 'array',
+			errors: 'array<{ skill: string, message: string }>'
+		}
+	},
+	errors: [
+		{ code: 'USAGE_ERROR', next_step: { kind: 'routing', action: 'discover_schema' } }
+	],
+	examples: [
+		'happyskills update acme/deploy-aws',
+		'happyskills up --all -y --json'
+	]
+}
+
+module.exports = { run, schema }

package/src/commands/validate.js

@@ -232,4 +232,40 @@ const run = (args) => catch_errors('Validate failed', async () => {
 	process.exit(has_errors ? EXIT_CODES.ERROR : EXIT_CODES.SUCCESS)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'validate',
+	audience: 'author',
+	purpose:  'Validate a local skill against all agentskills.io spec rules (structure, cross-file, file sizes, changelog, dependencies).',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'skill-name', required: true, type: 'string', pattern: '<skill-name>' },
+		],
+		flags: [
+			{ name: 'global', short: 'g', type: 'boolean', default: false },
+			{ name: 'json',   type: 'boolean', default: false },
+		],
+	},
+	output: {
+		data_shape: {
+			skill:          'string',
+			valid:          'boolean',
+			errors:         'array',
+			warnings:       'array',
+			checks_passed:  'number',
+			checks_failed:  'number',
+			checks_warned:  'number',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',      next_step: { kind: 'routing',   action: 'discover_schema'      } },
+		{ code: 'VALIDATION_FAILED', next_step: { kind: 'recovery',  action: 'fix_validation_errors' } },
+	],
+	examples: [
+		'happyskills validate my-skill',
+		'happyskills v my-skill --json',
+	],
+}
+
+module.exports = { run, schema }

package/src/commands/versions.js

@@ -89,4 +89,37 @@ const run = (args) => catch_errors('Versions failed', async () => {
 	print_table(['VERSION', 'PUBLISHED', 'COMMIT', 'MESSAGE'], rows)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run, extract_version, sort_refs }
+const schema = {
+	name:     'versions',
+	audience: 'consumer',
+	purpose:  'List all published versions of a skill from the registry, newest first.',
+	mutation: false,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'skill', required: true, type: 'string', pattern: '<owner>/<name>' },
+		],
+		flags: [
+			{ name: 'limit', type: 'number', default: null },
+			{ name: 'json',  type: 'boolean', default: false },
+		],
+	},
+	output: {
+		data_shape: {
+			skill:    'string',
+			count:    'number',
+			versions: 'array<{ version: string, ref: string, commit: string, message: string, published_at: string|null }>',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',  next_step: { kind: 'routing',  action: 'discover_schema' } },
+		{ code: 'NOT_FOUND' },
+		{ code: 'NETWORK_ERROR', next_step: { kind: 'recovery', action: 'retry' } },
+	],
+	examples: [
+		'happyskills versions acme/deploy-aws',
+		'happyskills versions acme/deploy-aws --limit 20 --json',
+	],
+}
+
+module.exports = { run, extract_version, sort_refs, schema }

package/src/commands/visibility.js

@@ -76,4 +76,36 @@ const run = (args) => catch_errors('Visibility failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'visibility',
+	audience: 'author',
+	purpose:  'Check or set a skill\'s visibility (public, private, workspace) in the registry.',
+	mutation: true,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [
+			{ name: 'skill',      required: true,  type: 'string', pattern: '<owner>/<name>' },
+			{ name: 'visibility', required: false, type: 'string', pattern: 'public|private|workspace' },
+		],
+		flags: [
+			{ name: 'json', type: 'boolean', default: false },
+		],
+	},
+	output: {
+		data_shape: {
+			skill:      'string',
+			visibility: 'string',
+		},
+	},
+	errors: [
+		{ code: 'USAGE_ERROR',   next_step: { kind: 'routing',  action: 'discover_schema' } },
+		{ code: 'AUTH_REQUIRED', next_step: { kind: 'recovery', action: 'login'           } },
+		{ code: 'NOT_FOUND' },
+	],
+	examples: [
+		'happyskills visibility acme/deploy-aws',
+		'happyskills visibility acme/deploy-aws public',
+	],
+}
+
+module.exports = { run, schema }

package/src/commands/whoami.js

@@ -67,4 +67,33 @@ const run = (args) => catch_errors('Whoami failed', async () => {
 	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
-module.exports = { run }
+const schema = {
+	name:     'whoami',
+	audience: 'account',
+	purpose:  'Show the currently authenticated user and their workspaces.',
+	mutation: false,
+	interactive_in_text_mode: false,
+	input: {
+		positional: [],
+		flags: [
+			{ name: 'json', type: 'boolean', default: false }
+		]
+	},
+	output: {
+		data_shape: {
+			username: 'string',
+			email: 'string',
+			workspaces: 'array'
+		}
+	},
+	errors: [
+		{ code: 'AUTH_REQUIRED', next_step: { kind: 'recovery', action: 'login' } },
+		{ code: 'NETWORK_ERROR', next_step: { kind: 'recovery', action: 'retry' } }
+	],
+	examples: [
+		'happyskills whoami',
+		'happyskills whoami --json'
+	]
+}
+
+module.exports = { run, schema }

package/src/constants/error_codes.js

@@ -14,6 +14,7 @@
 // Auth & permission ────────────────────────────────────────────────────────
 const AUTH_REQUIRED          = 'AUTH_REQUIRED'
 const INVALID_CREDENTIALS    = 'INVALID_CREDENTIALS'
+const AUTH_FAILED            = 'AUTH_FAILED'
 const EXPIRED_TOKEN          = 'EXPIRED_TOKEN'
 const INTERACTIVE_REQUIRED   = 'INTERACTIVE_REQUIRED'
 const FORBIDDEN              = 'FORBIDDEN'
@@ -109,6 +110,13 @@ const WRITE_FAILED              = 'WRITE_FAILED'
 const PUBLISH_FAILED            = 'PUBLISH_FAILED'
 const RANKING_SCHEMA_MISMATCH   = 'RANKING_SCHEMA_MISMATCH'
 
+// pull --rebase pipeline (client-side, spec 260523-02) ──────────────────────
+const COMPARE_FAILED            = 'COMPARE_FAILED'
+const CLONE_BASE_FAILED         = 'CLONE_BASE_FAILED'
+const CLONE_REMOTE_FAILED       = 'CLONE_REMOTE_FAILED'
+const READ_LOCAL_FAILED         = 'READ_LOCAL_FAILED'
+const SWAP_FAILED               = 'SWAP_FAILED'
+
 // Internal ─────────────────────────────────────────────────────────────────
 const INTERNAL_ERROR        = 'INTERNAL_ERROR'
 const PERSIST_FAILED        = 'PERSIST_FAILED'
@@ -147,7 +155,8 @@ const NOT_COMMUNITY_LISTED    = 'NOT_COMMUNITY_LISTED'
 const UNKNOWN_CODE          = 'UNKNOWN_CODE'
 
 const ERROR_CODES = Object.freeze({
-	AUTH_REQUIRED, INVALID_CREDENTIALS, EXPIRED_TOKEN, INTERACTIVE_REQUIRED,
+	AUTH_REQUIRED, INVALID_CREDENTIALS, AUTH_FAILED, EXPIRED_TOKEN,
+	INTERACTIVE_REQUIRED,
 	FORBIDDEN, INSUFFICIENT_ACCESS, LAST_OWNER, ORG_RESTRICTED,
 	NETWORK_ERROR, RATE_LIMITED, DB_UNAVAILABLE, GITHUB_UNAVAILABLE,
 	EMBEDDING_UNAVAILABLE, REGISTRY_UNAVAILABLE,
@@ -172,6 +181,8 @@ const ERROR_CODES = Object.freeze({
 	AUTHORIZATION_PENDING,
 	COMMAND_NOT_FOUND, MIN_CLI_VERSION, SNAPSHOT_FAILED, WRITE_FAILED,
 	PUBLISH_FAILED, RANKING_SCHEMA_MISMATCH,
+	COMPARE_FAILED, CLONE_BASE_FAILED, CLONE_REMOTE_FAILED, READ_LOCAL_FAILED,
+	SWAP_FAILED,
 	INTERNAL_ERROR, PERSIST_FAILED, VERIFICATION_FAILED,
 	NO_COGNITO_USER, COGNITO_SYNC_FAILED, COGNITO_UNLINK_FAILED,
 	ALREADY_HAS_PASSWORD, EMAIL_ALIAS_CONFLICT, ALREADY_APPROVED,

package/src/constants/next_step_actions.js

@@ -31,6 +31,8 @@ const PROVIDE_CHANGELOG        = 'provide_changelog'
 const SELF_UPDATE              = 'self_update'
 const SHOW_FORMAT              = 'show_format'
 const RETRY_RANK               = 'retry_rank'
+const RETRY_OR_ABANDON         = 'retry_or_abandon'
+const REVIEW_PUBLISH_ERROR     = 'review_publish_error'
 
 // kind: clarification
 const CLARIFY_QUERY            = 'clarify_query'
@@ -45,6 +47,7 @@ const SPECIFY_WORKSPACE              = 'specify_workspace'
 const SPECIFY_BUMP_TYPE              = 'specify_bump_type'
 const RESOLVE_BUMP_DISAGREEMENT      = 'resolve_bump_disagreement'
 const PICK_VERSION                   = 'pick_version'
+const RESOLVE_UNKNOWN_DRIFT          = 'resolve_unknown_drift'
 
 // kind: confirmation
 const CONFIRM_DISCARD_OR_SNAPSHOT_FIRST = 'confirm_discard_or_snapshot_first'
@@ -59,6 +62,7 @@ const ATTACH_SCREENSHOT        = 'attach_screenshot'   // § 15.3.4
 
 // kind: routing
 const INSTALL_FIRST            = 'install_first'
+const DISCOVER_SCHEMA          = 'discover_schema'
 
 // kind lookup ──────────────────────────────────────────────────────────────
 const ACTION_KIND = Object.freeze({
@@ -71,6 +75,8 @@ const ACTION_KIND = Object.freeze({
 	[SELF_UPDATE]:                        RECOVERY,
 	[SHOW_FORMAT]:                        RECOVERY,
 	[RETRY_RANK]:                         RECOVERY,
+	[RETRY_OR_ABANDON]:                   RECOVERY,
+	[REVIEW_PUBLISH_ERROR]:               RECOVERY,
 
 	[CLARIFY_QUERY]:                      CLARIFICATION,
 
@@ -83,6 +89,7 @@ const ACTION_KIND = Object.freeze({
 	[SPECIFY_BUMP_TYPE]:                  DECISION,
 	[RESOLVE_BUMP_DISAGREEMENT]:          DECISION,
 	[PICK_VERSION]:                       DECISION,
+	[RESOLVE_UNKNOWN_DRIFT]:              DECISION,
 
 	[CONFIRM_DISCARD_OR_SNAPSHOT_FIRST]:  CONFIRMATION,
 	[CONFIRM_CASCADE]:                    CONFIRMATION,
@@ -94,19 +101,22 @@ const ACTION_KIND = Object.freeze({
 	[ATTACH_SCREENSHOT]:                  CONTINUATION,
 
 	[INSTALL_FIRST]:                      ROUTING,
+	[DISCOVER_SCHEMA]:                    ROUTING,
 })
 
 const NEXT_STEP_ACTIONS = Object.freeze({
 	LOGIN, RETRY, RECONCILE_FIRST, PULL_REBASE_FIRST, FIX_VALIDATION_ERRORS,
 	PROVIDE_CHANGELOG, SELF_UPDATE, SHOW_FORMAT, RETRY_RANK,
+	RETRY_OR_ABANDON, REVIEW_PUBLISH_ERROR,
 	CLARIFY_QUERY,
 	RESOLVE_REGRESSION, RESOLVE_MISSING_SKILL_JSON, RESOLVE_MISSING_DIR,
 	RESOLVE_CONFLICTS, RESOLVE_PATCH_REJECTIONS, SPECIFY_WORKSPACE,
 	SPECIFY_BUMP_TYPE, RESOLVE_BUMP_DISAGREEMENT, PICK_VERSION,
+	RESOLVE_UNKNOWN_DRIFT,
 	CONFIRM_DISCARD_OR_SNAPSHOT_FIRST, CONFIRM_CASCADE, CONFIRM_DESTRUCTIVE,
 	PASS_YES_FLAG,
 	RANK_DIGESTS_INLINE, PRESENT_TO_USER, ATTACH_SCREENSHOT,
-	INSTALL_FIRST,
+	INSTALL_FIRST, DISCOVER_SCHEMA,
 })
 
 const NEXT_STEP_ACTION_LIST = Object.freeze(Object.values(NEXT_STEP_ACTIONS).slice().sort())

package/src/constants/next_step_by_error_code.js

@@ -9,9 +9,9 @@
 // applies — agent falls back to "explain to principal").
 
 const {
-	RECOVERY, DECISION, CONFIRMATION,
+	RECOVERY, DECISION, CONFIRMATION, ROUTING,
 	LOGIN, RETRY, RECONCILE_FIRST, PULL_REBASE_FIRST, FIX_VALIDATION_ERRORS,
-	PROVIDE_CHANGELOG, SELF_UPDATE, SHOW_FORMAT,
+	PROVIDE_CHANGELOG, SELF_UPDATE, SHOW_FORMAT, DISCOVER_SCHEMA,
 	RESOLVE_REGRESSION, RESOLVE_MISSING_SKILL_JSON, RESOLVE_MISSING_DIR,
 	RESOLVE_CONFLICTS, RESOLVE_PATCH_REJECTIONS, SPECIFY_WORKSPACE,
 	SPECIFY_BUMP_TYPE, RESOLVE_BUMP_DISAGREEMENT, PICK_VERSION,
@@ -45,12 +45,25 @@ const confirmation = (action, instructions, context = {}) => ({
 	principal_authorization_required: true,
 })
 
+const routing = (action, instructions, context = {}, opts = {}) => ({
+	kind:         ROUTING,
+	action,
+	instructions,
+	context,
+	...(opts.route_to_skill ? { route_to_skill: opts.route_to_skill } : {}),
+})
+
 const NEXT_STEP_BY_ERROR_CODE = Object.freeze({
 	AUTH_REQUIRED: () => recovery(
 		LOGIN,
 		'Sign in to HappySkills, then re-run the command.',
 		{ commands: ['npx happyskills login --browser --json'] }
 	),
+	AUTH_FAILED: () => recovery(
+		LOGIN,
+		'The sign-in attempt did not complete. Start the login flow again, then re-run the command.',
+		{ commands: ['npx happyskills login --browser --json'] }
+	),
 	EXPIRED_TOKEN: () => recovery(
 		LOGIN,
 		'Your session has expired. Sign in again, then re-run the command.',
@@ -86,13 +99,21 @@ const NEXT_STEP_BY_ERROR_CODE = Object.freeze({
 		'The embedding service is temporarily unavailable. Retry shortly.',
 		{ retry_after_seconds: 10, max_attempts: 3 }
 	),
-	COMMAND_NOT_FOUND: (_msg, ctx = {}) => recovery(
-		SHOW_FORMAT,
-		'The command does not exist. Suggest the principal run `happyskills --help` to see available commands, or pick from the suggestion if it matches their intent.',
+	COMMAND_NOT_FOUND: (_msg, ctx = {}) => routing(
+		DISCOVER_SCHEMA,
+		'The command does not exist. Run `happyskills schema --json` to discover every available command with its exact input, output, and error contract. If a suggestion is present and it matches the intent, you may re-run with that command instead.',
 		{
 			got: ctx.got,
 			...(ctx.suggestion ? { suggestion: ctx.suggestion } : {}),
-			commands: ['npx happyskills --help'],
+			commands: ['npx happyskills schema --json'],
+		}
+	),
+	USAGE_ERROR: (_msg, ctx = {}) => routing(
+		DISCOVER_SCHEMA,
+		'The command was invoked with invalid arguments or flags. Run `happyskills schema --json` to see the exact input contract for every command, then re-run with corrected arguments.',
+		{
+			...(ctx.got ? { got: ctx.got } : {}),
+			commands: ['npx happyskills schema --json'],
 		}
 	),
 	INVALID_SLUG: () => recovery(

package/src/constants/next_step_by_error_code.test.js

@@ -0,0 +1,30 @@
+'use strict'
+// Unit coverage for the schema-discovery routing defaults. A generic agent
+// that reaches for the conventional `help` fallback must be routed to the
+// `schema --json` surface — the machine-readable contract is what gives it
+// clarity and correctness on how to use the CLI, not just discoverability.
+
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+const { next_step_for_error } = require('./next_step_by_error_code')
+const { DISCOVER_SCHEMA, ROUTING, kind_for_action } = require('./next_step_actions')
+
+describe('next_step_by_error_code — schema discovery routing', () => {
+	it('discover_schema is a routing-kind action', () => {
+		assert.strictEqual(kind_for_action(DISCOVER_SCHEMA), ROUTING)
+	})
+
+	for (const code of ['COMMAND_NOT_FOUND', 'USAGE_ERROR']) {
+		it(`${code} routes the agent to \`schema --json\``, () => {
+			const ns = next_step_for_error(code, 'boom', { got: 'foo' })
+			assert.ok(ns, `${code} must produce a next_step`)
+			assert.strictEqual(ns.kind, ROUTING)
+			assert.strictEqual(ns.action, DISCOVER_SCHEMA)
+			assert.ok(Array.isArray(ns.context.commands))
+			assert.ok(
+				ns.context.commands.some(c => c.includes('schema --json')),
+				`${code} next_step must point at \`happyskills schema --json\``
+			)
+		})
+	}
+})

package/src/index.js

@@ -206,7 +206,7 @@ const run = (argv) => {
 		if (suggestion) {
 			console.error(dim(`  Did you mean: happyskills ${suggestion}?`))
 		} else {
-			console.error(dim(`  Run happyskills --help for available commands.`))
+			console.error(dim(`  Run happyskills --help for available commands, or happyskills schema --json for the full machine-readable surface.`))
 		}
 		return process.exit(EXIT_CODES.USAGE)
 	}

package/src/integration/cli.test.js

@@ -280,14 +280,27 @@ describe('CLI — --json: stdout is always valid JSON', () => {
 		assert.ok(typeof env.error.message === 'string' && env.error.message.length > 0)
 	})
 
-	it('unknown command with --json emits the COMMAND_NOT_FOUND envelope', () => {
+	it('unknown command with --json routes the agent to schema discovery', () => {
 		const { stdout, code } = run(['not-a-command', '--json'])
 		assert.strictEqual(code, 2)
 		const env = parse_json_output(stdout, 'unknown-command --json')
 		assert_error_envelope(env, 'COMMAND_NOT_FOUND', 'unknown command')
-		// Recovery hint: show_format with --help in commands[].
-		assert.strictEqual(env.next_step.action, 'show_format')
-		assert.ok(env.next_step.context.commands.some(c => c.includes('--help')))
+		// Routing hint: discover_schema, pointing at `schema --json`. A confused
+		// agent that hit a bad command is handed the full machine-readable surface.
+		assert.strictEqual(env.next_step.kind, 'routing')
+		assert.strictEqual(env.next_step.action, 'discover_schema')
+		assert.ok(env.next_step.context.commands.some(c => c.includes('schema --json')))
+	})
+
+	it('usage error with --json routes the agent to schema discovery', () => {
+		// `--json --text` is mutually exclusive → USAGE_ERROR with no command-
+		// specific next_step, so the default discover_schema routing applies.
+		const { stdout, code } = run(['--json', '--text'])
+		assert.strictEqual(code, 2)
+		const env = parse_json_output(stdout, 'usage-error --json')
+		assert_error_envelope(env, 'USAGE_ERROR', 'mutually exclusive')
+		assert.strictEqual(env.next_step.action, 'discover_schema')
+		assert.ok(env.next_step.context.commands.some(c => c.includes('schema --json')))
 	})
 
 	it('network error produces an envelope with code NETWORK_ERROR + retry next_step', () => {

package/src/integration/schema.test.js

@@ -94,6 +94,37 @@ describe('happyskills schema --json', () => {
 		}
 	})
 
+	it('no command returns the stub purpose (anti-stub guard — spec 260602-01)', () => {
+		const { stdout } = run(['schema', '--json'])
+		const env = parse_envelope(stdout, 'schema --json anti-stub')
+		const stubbed = env.data.commands.filter(c => /no curated purpose/i.test(c.purpose))
+		assert.deepStrictEqual(
+			stubbed.map(c => c.name),
+			[],
+			`these commands still return the stub purpose and need a curated schema export: ${stubbed.map(c => c.name).join(', ')}`
+		)
+	})
+
+	it('every command carries a non-empty examples array of strings', () => {
+		const { stdout } = run(['schema', '--json'])
+		const env = parse_envelope(stdout, 'schema --json examples')
+		for (const cmd of env.data.commands) {
+			assert.ok(Array.isArray(cmd.examples) && cmd.examples.length > 0, `command.examples must be a non-empty array for ${cmd.name}`)
+			for (const ex of cmd.examples) {
+				assert.ok(typeof ex === 'string' && ex.length > 0, `command.examples[] entries must be non-empty strings for ${cmd.name}`)
+			}
+		}
+	})
+
+	it('every command.input exposes positional and flags arrays', () => {
+		const { stdout } = run(['schema', '--json'])
+		const env = parse_envelope(stdout, 'schema --json input shape')
+		for (const cmd of env.data.commands) {
+			assert.ok(Array.isArray(cmd.input.positional), `command.input.positional must be an array for ${cmd.name}`)
+			assert.ok(Array.isArray(cmd.input.flags), `command.input.flags must be an array for ${cmd.name}`)
+		}
+	})
+
 	it('every command.errors[].code is in the closed enum, and the kind/action pair is valid', () => {
 		const { stdout } = run(['schema', '--json'])
 		const env = parse_envelope(stdout, 'schema --json error refs')

package/src/ui/output.js

@@ -44,8 +44,15 @@ const format_help = (text) => {
 	}).join('\n')
 }
 
+// Every --help (global and per-command) ends with a pointer to `schema
+// --json`. An agent that reaches for the conventional `help` as a fallback
+// then discovers the machine-readable surface, which is what it actually
+// wants for clarity and correctness on how to use the CLI.
+const SCHEMA_HINT = 'For the complete machine-readable CLI surface — every command\'s inputs, outputs, and error contracts in one call — run: happyskills schema --json'
+
 const print_help = (text) => {
 	console.log(format_help(text))
+	if (!is_json_mode()) console.log(dim(`\n${SCHEMA_HINT}`))
 }
 
 // Visible length of a string, ignoring ANSI escape codes