happyskills 1.0.2 → 1.1.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-06-02
+
+### Added
+
+- Add `discover_schema` routing action (`next_step.kind: routing`) so a confused agent is steered to the machine-readable CLI surface. Every `--help` output (global and per-command) now ends with a footer pointing to `happyskills schema --json`, and the text-mode unknown-command message points there too — agents reach for the conventional `help`, not the unconventional `schema`, so every help-seeking path now leads back to it. Added to both the CLI and API closed-enum mirrors (additive, non-breaking).
+
+### Changed
+
+- Route the `COMMAND_NOT_FOUND` and `USAGE_ERROR` `--json` envelopes to `discover_schema` (previously `show_format` / none), with `context.commands: ["npx happyskills schema --json"]` — a mistyped-command or bad-flags agent now receives the full CLI contract through the structured `next_step` channel it is already parsing.
+
 ## [1.0.2] - 2026-06-01
 
 ### Fixed

package/package.json

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

package/src/constants/next_step_actions.js

@@ -59,6 +59,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({
@@ -94,6 +95,7 @@ const ACTION_KIND = Object.freeze({
 	[ATTACH_SCREENSHOT]:                  CONTINUATION,
 
 	[INSTALL_FIRST]:                      ROUTING,
+	[DISCOVER_SCHEMA]:                    ROUTING,
 })
 
 const NEXT_STEP_ACTIONS = Object.freeze({
@@ -106,7 +108,7 @@ const NEXT_STEP_ACTIONS = Object.freeze({
 	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,6 +45,14 @@ 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,
@@ -86,13 +94,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/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