happyskills 1.19.0 → 1.20.1

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.20.1] - 2026-07-09
+
+### Changed
+
+- Raise the publish bundle cap `MAX_TOTAL_SIZE` from 1 MB to 2 MB (`cli/src/config/limits.js`, mirroring `api/app/config/limits.js`; per-file `MAX_FILE_SIZE` unchanged at 1 MB). Affects the `validate`/`publish` pre-flight (`max_total_size` rule) and the streaming archive-install extraction cap. Guarded by the new root contract test `test/limits-mirror.test.js`. **Release after (or with) the API bump of the same constant so production never sees a CLI cap higher than the API's** (docs/architecture.md § 9).
+
+## [1.20.0] - 2026-07-06
+
+### Added
+
+- Add post-install manual-setup support (`setupGuide` + `complete_manual_setup`). A `config`/`env` field can declare a `setupGuide` (a path to a reference explaining how a human obtains the value — e.g. minting a scoped API token in a provider dashboard, something the agent can't do) and an optional `verify` command. On install/update, when a `required` field with a `setupGuide` is still unset, `install` now emits a `next_step` with the new closed action **`complete_manual_setup`** (kind `continuation`), carrying `context.pending[]` = `{ skill, var, guide, verify, target }`, plus a human-readable "ACTION REQUIRED" banner in text mode. The requirement re-surfaces in `warnings` on every reinstall/update until satisfied (self-healing). `validate` gains two checks: a `setupGuide` must resolve to a real file in the skill, and a `required` secret with no `setupGuide` in a skill whose text mentions manual credential setup gets an advisory warning. Bumped `ENVELOPE_SCHEMA_VERSION` to `1.1.0` (additive: one new next_step action).
+
 ## [1.19.0] - 2026-07-06
 
 ### Added

package/package.json

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

package/src/commands/install.js

@@ -234,6 +234,17 @@ const run = (args) => catch_errors('Install failed', async () => {
 
 	const snapshot_by_skill = Object.fromEntries(fresh_snapshots.map(s => [s.skill, s.snapshot_id]))
 
+	// Manual-setup requirements aggregated across everything installed: required credentials/config
+	// a HUMAN must satisfy (the agent can't — e.g. mint a scoped API token in a dashboard). Surfaced
+	// as a `complete_manual_setup` next_step so the piloting skill guides the principal; the same
+	// state re-surfaces on every reinstall (via configure's warnings) until it is resolved.
+	const setup_pending = results.flatMap(({ result }) => result.setup_pending || [])
+	const manual_setup_next_step = setup_pending.length ? {
+		action: 'complete_manual_setup',
+		instructions: `${setup_pending.length} credential(s) need manual setup only a human can do before ${setup_pending.length === 1 ? 'this skill works' : 'these skills work'}: ${setup_pending.map(p => p.var).join(', ')}. For EACH: read its guide, walk the user through it in plain language, then run its verify command. Do not report the install as complete until this is done.`,
+		context: { pending: setup_pending }
+	} : null
+
 	if (args.flags.json) {
 		// Spec 260525-cli-default-json § 4.3 rules 2 + 4:
 		//   - No shape-flipping between single and batch — always emit
@@ -261,10 +272,23 @@ const run = (args) => catch_errors('Install failed', async () => {
 			status: 'failed',
 			error: { code: 'INTERNAL_ERROR', message: error }
 		}))
-		print_json({ data: { results: [...success_rows, ...failure_rows] } })
+		print_json({
+			data: { results: [...success_rows, ...failure_rows] },
+			...(manual_setup_next_step ? { next_step: manual_setup_next_step } : {})
+		})
 		return
 	}
 
+	if (setup_pending.length) {
+		console.log()
+		print_warn('⚠  ACTION REQUIRED — install is not finished. A human must complete manual setup:')
+		for (const p of setup_pending) {
+			print_warn(`   ${p.skill} · ${p.var} — the agent cannot do this for you.`)
+			print_warn(`     → guide:  ${p.guide}`)
+			if (p.verify) print_warn(`     → verify: ${p.verify}`)
+		}
+	}
+
 	console.log()
 	print_hint(`See what's installed: ${code('happyskills list')}`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })

package/src/commands/validate.js

@@ -8,6 +8,7 @@ const { validate_file_sizes } = require('../validation/file_size_rules')
 const { validate_changelog_version } = require('../validation/changelog_rules')
 const { validate_dependencies } = require('../validation/dependency_rules')
 const { validate_config_usage } = require('../validation/config_usage_rules')
+const { validate_setup_guides } = require('../validation/setup_guide_rules')
 const { file_exists, read_json } = require('../utils/fs')
 const { skills_dir, find_project_root, lock_root } = require('../config/paths')
 const { read_lock, get_all_locked_skills } = require('../lock/reader')
@@ -181,6 +182,8 @@ const run = (args) => catch_errors('Validate failed', async () => {
 	if (cl_err) throw cl_err
 	const [cfg_err, cfg_results] = await validate_config_usage(skill_dir, json_data.manifest, md_data.content)
 	if (cfg_err) throw cfg_err
+	const [sg_err, sg_results] = await validate_setup_guides(skill_dir, json_data.manifest, md_data.content)
+	if (sg_err) throw sg_err
 
 	// Dependency validation — registry checks when authenticated
 	let dep_results = []
@@ -222,7 +225,7 @@ const run = (args) => catch_errors('Validate failed', async () => {
 		}
 	}
 
-	const all_results = [...md_data.results, ...json_data.results, ...cross_results, ...marker_results, ...size_results, ...cl_results, ...(cfg_results || []), ...dep_results]
+	const all_results = [...md_data.results, ...json_data.results, ...cross_results, ...marker_results, ...size_results, ...cl_results, ...(cfg_results || []), ...(sg_results || []), ...dep_results]
 	const type_label = is_kit ? ' [kit]' : ''
 
 	if (args.flags.json) {

package/src/config/limits.js

@@ -3,7 +3,7 @@
 // validation will be rejected by the API.
 
 const MAX_FILE_SIZE = 1 * 1024 * 1024   // 1 MB per file
-const MAX_TOTAL_SIZE = 1 * 1024 * 1024  // 1 MB per skill bundle (also the decompressed-archive cap — SUP-04)
+const MAX_TOTAL_SIZE = 2 * 1024 * 1024  // 2 MB per skill bundle (also the decompressed-archive cap — SUP-04)
 const MAX_FILE_COUNT = 1000             // max entries per archive (zip-bomb / DoS guard; real skills have <100 files) — SUP-04
 
 module.exports = {

package/src/constants/next_step_actions.js

@@ -60,6 +60,7 @@ const PASS_YES_FLAG                     = 'pass_yes_flag'
 const RANK_DIGESTS_INLINE      = 'rank_digests_inline'
 const PRESENT_TO_USER          = 'present_to_user'
 const ATTACH_SCREENSHOT        = 'attach_screenshot'   // § 15.3.4
+const COMPLETE_MANUAL_SETUP    = 'complete_manual_setup'
 
 // kind: routing
 const INSTALL_FIRST            = 'install_first'
@@ -101,6 +102,7 @@ const ACTION_KIND = Object.freeze({
 	[RANK_DIGESTS_INLINE]:                CONTINUATION,
 	[PRESENT_TO_USER]:                    CONTINUATION,
 	[ATTACH_SCREENSHOT]:                  CONTINUATION,
+	[COMPLETE_MANUAL_SETUP]:              CONTINUATION,
 
 	[INSTALL_FIRST]:                      ROUTING,
 	[DISCOVER_SCHEMA]:                    ROUTING,
@@ -117,7 +119,7 @@ const NEXT_STEP_ACTIONS = Object.freeze({
 	RESOLVE_UNKNOWN_DRIFT, ORGANIZE_MATCHED_SKILLS,
 	CONFIRM_DISCARD_OR_SNAPSHOT_FIRST, CONFIRM_CASCADE, CONFIRM_DESTRUCTIVE,
 	PASS_YES_FLAG,
-	RANK_DIGESTS_INLINE, PRESENT_TO_USER, ATTACH_SCREENSHOT,
+	RANK_DIGESTS_INLINE, PRESENT_TO_USER, ATTACH_SCREENSHOT, COMPLETE_MANUAL_SETUP,
 	INSTALL_FIRST, DISCOVER_SCHEMA,
 })
 

package/src/engine/installer.js

@@ -400,6 +400,7 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 		)
 		if (config_err) print_warn(`Skill configuration step failed: ${config_err[0]?.message || 'unknown error'}`)
 		const config_warnings = config_result?.warnings || []
+		const config_setup_pending = config_result?.setup_pending || []
 
 		const linked_count = downloaded.length - disabled_skills.size
 		if (agents.length > 0 && linked_count > 0) {
@@ -458,7 +459,7 @@ const install = (skill, options = {}) => catch_errors('Install failed', async ()
 		const forced = forced_pkgs.map(p => ({ skill: p.skill, version: p.version }))
 
 		const linked_agents = agents.map(a => a.id)
-		return { skill, version: packages[0]?.version, no_op: false, installed, skipped, skipped_deps, warnings, forced, packages: packages_to_install.length, linked_agents }
+		return { skill, version: packages[0]?.version, no_op: false, installed, skipped, skipped_deps, warnings, forced, packages: packages_to_install.length, linked_agents, setup_pending: config_setup_pending }
 	} catch (err) {
 		await remove_dir(temp_dir)
 		throw err

package/src/integration/schema.test.js

@@ -51,13 +51,13 @@ describe('happyskills schema --json', () => {
 		const env = parse_envelope(stdout, 'schema --json')
 		assert_success_envelope(env, 'schema --json')
 		assert.strictEqual(env.meta.command, 'schema')
-		assert.strictEqual(env.meta.envelope_schema_version, '1.0.0')
+		assert.strictEqual(env.meta.envelope_schema_version, '1.1.0')
 	})
 
 	it('data.envelope_schema_version + envelope_schema_uri are exposed', () => {
 		const { stdout } = run(['schema', '--json'])
 		const env = parse_envelope(stdout, 'schema --json envelope meta')
-		assert.strictEqual(env.data.envelope_schema_version, '1.0.0')
+		assert.strictEqual(env.data.envelope_schema_version, '1.1.0')
 		assert.strictEqual(env.data.envelope_schema_uri, 'https://schemas.happyskills.dev/envelope/v1.json')
 		assert.ok(typeof env.data.cli_version === 'string')
 	})

package/src/schema/envelope_validator.js

@@ -18,7 +18,7 @@ const {
 	ACTION_KIND,
 } = require('../constants/next_step_actions')
 
-const ENVELOPE_SCHEMA_VERSION = '1.0.0'
+const ENVELOPE_SCHEMA_VERSION = '1.1.0'
 
 const TOP_LEVEL_KEYS = ['ok', 'data', 'error', 'next_step', 'warnings', 'meta']
 const TOP_LEVEL_KEY_SET = new Set(TOP_LEVEL_KEYS)

package/src/skills_config/configure.js

@@ -72,6 +72,10 @@ const secret_is_set = (env_abs, name) => catch_errors('Failed to check secret pr
 const configure_installed_skills = (packages, options = {}) => catch_errors('Failed to configure installed skills', async () => {
 	const { base_dir, config_root, interactive = false, only_required = false, ask = question_prompt } = options
 	const warnings = []
+	// Manual-setup requirements the human must satisfy (a required field that declares a
+	// `setupGuide` and is still unset). The install command turns a non-empty list into a
+	// `next_step.action: complete_manual_setup` so the agent guides the principal through it.
+	const setup_pending = []
 
 	const [, existing_config_file] = await read_skills_config(config_root)
 
@@ -157,7 +161,7 @@ const configure_installed_skills = (packages, options = {}) => catch_errors('Fai
 		const secret_names = []
 		for (const [var_name, spec] of Object.entries(env_schema || {})) {
 			if (spec && spec.secret) {
-				secret_names.push({ name: var_name, required: spec.required === true })
+				secret_names.push({ name: var_name, required: spec.required === true, setupGuide: spec.setupGuide, verify: spec.verify })
 				continue
 			}
 			await maybe_prompt(var_name, spec)
@@ -179,7 +183,18 @@ const configure_installed_skills = (packages, options = {}) => catch_errors('Fai
 
 			for (const secret of secret_names.filter(s => s.required)) {
 				const [, is_set] = await secret_is_set(env_abs, secret.name)
-				if (!is_set) warnings.push(`Required secret ${secret.name} for ${key} is not set — add it to ${env_file_rel}`)
+				if (is_set) continue
+				if (secret.setupGuide) {
+					// Human-only setup (e.g. mint a scoped API token in a dashboard) — record it so
+					// the install command can surface a `complete_manual_setup` next_step, and point
+					// the warning at the guide so the requirement re-fires (with the how-to) on every
+					// reinstall/update until it is satisfied.
+					const guide_abs = path.join(skill_install_dir(base_dir, name), secret.setupGuide)
+					setup_pending.push({ skill: key, var: secret.name, kind: 'env', guide: guide_abs, verify: secret.verify || null, target: env_file_rel })
+					warnings.push(`Required secret ${secret.name} for ${key} needs manual setup — follow ${secret.setupGuide}, then add it to ${env_file_rel}`)
+				} else {
+					warnings.push(`Required secret ${secret.name} for ${key} is not set — add it to ${env_file_rel}`)
+				}
 			}
 		}
 
@@ -190,7 +205,13 @@ const configure_installed_skills = (packages, options = {}) => catch_errors('Fai
 			if (!spec || spec.required !== true) return
 			if (spec.default !== undefined) return
 			if (Object.prototype.hasOwnProperty.call(overrides, field)) return
-			warnings.push(`Required config "${field}" for ${key} is not set — no value provided and the skill declares no default.`)
+			if (spec.setupGuide) {
+				const guide_abs = path.join(skill_install_dir(base_dir, name), spec.setupGuide)
+				setup_pending.push({ skill: key, var: field, kind: 'config', guide: guide_abs, verify: spec.verify || null, target: null })
+				warnings.push(`Required config "${field}" for ${key} needs manual setup — follow ${spec.setupGuide}.`)
+			} else {
+				warnings.push(`Required config "${field}" for ${key} is not set — no value provided and the skill declares no default.`)
+			}
 		}
 		for (const [field, spec] of Object.entries(config_schema || {})) warn_required_unset(field, spec)
 		for (const [var_name, spec] of Object.entries(env_schema || {})) {
@@ -209,7 +230,7 @@ const configure_installed_skills = (packages, options = {}) => catch_errors('Fai
 		}
 	}
 
-	return { warnings }
+	return { warnings, setup_pending }
 })
 
 module.exports = { configure_installed_skills }

package/src/skills_config/configure.test.js

@@ -127,6 +127,49 @@ describe('configure_installed_skills — interactive overrides', () => {
 	})
 })
 
+describe('configure_installed_skills — manual setup (setupGuide)', () => {
+	it('records setup_pending + a guide-pointed warning for an unmet required secret with a setupGuide', async () => {
+		write_skill(base_dir, 'cloudflare', {
+			env: { CLOUDFLARE_API_TOKEN: { required: true, secret: true, setupGuide: 'references/token-model.md', verify: 'node scripts/cf.js rest GET /user/tokens/verify' } }
+		})
+		const [err, result] = await configure_installed_skills(
+			[{ skill: 'nicolasdao/cloudflare' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+		assert.strictEqual(result.setup_pending.length, 1)
+		const p = result.setup_pending[0]
+		assert.strictEqual(p.skill, 'nicolasdao/cloudflare')
+		assert.strictEqual(p.var, 'CLOUDFLARE_API_TOKEN')
+		assert.ok(p.guide.endsWith('references/token-model.md'))
+		assert.strictEqual(p.verify, 'node scripts/cf.js rest GET /user/tokens/verify')
+		// the warning points at the guide (so it re-fires with the how-to on reinstall)
+		assert.ok(result.warnings.some(w => /manual setup/.test(w) && /references\/token-model\.md/.test(w)))
+	})
+
+	it('does NOT record setup_pending once the secret is set (idempotent — no nagging)', async () => {
+		write_skill(base_dir, 'cloudflare', {
+			env: { CLOUDFLARE_API_TOKEN: { required: true, secret: true, setupGuide: 'references/token-model.md' } }
+		})
+		const [err] = await configure_installed_skills([{ skill: 'nicolasdao/cloudflare' }], { base_dir, config_root, interactive: false })
+		assert.ifError(err)
+		// set the secret in the scaffolded env file
+		const envPath = path.join(config_root, 'secrets', 'cloudflare.env')
+		fs.writeFileSync(envPath, 'CLOUDFLARE_API_TOKEN=abc123\n')
+		const [err2, result2] = await configure_installed_skills([{ skill: 'nicolasdao/cloudflare' }], { base_dir, config_root, interactive: false })
+		assert.ifError(err2)
+		assert.strictEqual(result2.setup_pending.length, 0)
+	})
+
+	it('a required secret WITHOUT a setupGuide keeps the plain unset warning and no setup_pending', async () => {
+		write_skill(base_dir, 'plain', { env: { API_KEY: { required: true, secret: true } } })
+		const [err, result] = await configure_installed_skills([{ skill: 'acme/plain' }], { base_dir, config_root, interactive: false })
+		assert.ifError(err)
+		assert.strictEqual(result.setup_pending.length, 0)
+		assert.ok(result.warnings.some(w => /API_KEY/.test(w) && /is not set/.test(w)))
+	})
+})
+
 describe('configure_installed_skills — constellation sharedEnv', () => {
 	const TOKEN_ENV = { env: { CLOUDFLARE_API_TOKEN: { required: true, secret: true, description: 'CF token' } } }
 

package/src/validation/setup_guide_rules.js

@@ -0,0 +1,96 @@
+'use strict'
+// setupGuide validation — the post-install manual-setup feature (spec: setupGuide + complete_manual_setup).
+//
+// A skill can attach a `setupGuide` (a reference file) to a `config`/`env` field whose value a HUMAN
+// must obtain manually (e.g. create a scoped API token in a provider dashboard — something the agent
+// cannot do). On install, when such a required field is unmet, the CLI emits
+// `next_step.action: complete_manual_setup` pointing at the guide. This validator does two things:
+//
+//   1. CORRECTNESS — every declared `setupGuide` must be a non-empty string that resolves to a file
+//      inside the skill. A dangling pointer would make the install-time next_step reference nothing.
+//   2. AUTHORING FLOOR — a deterministic nudge: a required SECRET with no `setupGuide`, in a skill
+//      whose instructions mention manual credential setup (dashboard / token / OAuth / permissions),
+//      is flagged as an advisory `warning` so the author considers adding a guide. Gated on the text
+//      signal so simple skills (a token the user already has) are NOT nagged. The LLM design skill is
+//      the precision layer on top of this floor.
+
+const path = require('path')
+const fs = require('fs')
+const { error: { catch_errors } } = require('puffy-core')
+const { file_exists, read_file } = require('../utils/fs')
+
+const as_object = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : null)
+
+const result = (file, field, rule, severity, message, value) => ({
+	file, field, rule, severity, message, ...(value !== undefined ? { value } : {})
+})
+
+// Signals in the skill's own instructions that obtaining a credential is a manual, human-only chore.
+const MANUAL_SETUP_SIGNAL = /dashboard|console|create a token|create an? api|api token|api key|oauth|sign in to|log ?in to|navigate to|grant .*permission|permission group|client secret|service account/i
+
+// Recursively collect files under a directory (best-effort; references are text/markdown).
+const collect_files = (dir) => {
+	const out = []
+	const walk = (d) => {
+		for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+			const full = path.join(d, entry.name)
+			if (entry.isDirectory()) walk(full)
+			else out.push(full)
+		}
+	}
+	try { walk(dir) } catch { /* unreadable dir — nothing to scan */ }
+	return out
+}
+
+// Every declared config/env field, flattened to { name, spec, kind }.
+const collect_fields = (manifest) => {
+	const out = []
+	const cfg = as_object(manifest && manifest.config) || {}
+	const env = as_object(manifest && manifest.env) || {}
+	for (const [name, spec] of Object.entries(cfg)) out.push({ name, spec: as_object(spec) || {}, kind: 'config' })
+	for (const [name, spec] of Object.entries(env)) out.push({ name, spec: as_object(spec) || {}, kind: 'env' })
+	return out
+}
+
+const validate_setup_guides = (skill_dir, manifest, skill_md_content) => catch_errors('Failed to validate setup guides', async () => {
+	if (!manifest) return []
+	const results = []
+	const fields = collect_fields(manifest)
+
+	// 1. Correctness — every declared setupGuide resolves to a real file inside the skill.
+	for (const { name, spec, kind } of fields) {
+		if (spec.setupGuide === undefined) continue
+		if (typeof spec.setupGuide !== 'string' || !spec.setupGuide.trim()) {
+			results.push(result('skill.json', 'setupGuide', 'setup_guide_type', 'error', `${kind} "${name}" setupGuide must be a non-empty string path`, name))
+			continue
+		}
+		const [, exists] = await file_exists(path.join(skill_dir, spec.setupGuide))
+		if (!exists) {
+			results.push(result('skill.json', 'setupGuide', 'setup_guide_missing', 'error', `${kind} "${name}" setupGuide points to "${spec.setupGuide}", which does not exist in the skill`, name))
+		}
+	}
+
+	// 2. Authoring floor — a required secret with no setupGuide, when the skill's text signals manual setup.
+	const has_required_secret_without_guide = fields.some(f => f.kind === 'env' && f.spec.secret === true && f.spec.required === true && !f.spec.setupGuide)
+	if (has_required_secret_without_guide) {
+		let text = String(skill_md_content || '')
+		const refs_dir = path.join(skill_dir, 'references')
+		const [, refs_exists] = await file_exists(refs_dir)
+		if (refs_exists) {
+			for (const file of collect_files(refs_dir)) {
+				const [, content] = await read_file(file)
+				if (content) text += '\n' + content
+			}
+		}
+		if (MANUAL_SETUP_SIGNAL.test(text)) {
+			for (const { name, spec, kind } of fields) {
+				if (kind !== 'env' || spec.secret !== true || spec.required !== true || spec.setupGuide) continue
+				results.push(result('skill.json', 'setupGuide', 'setup_guide_suggested', 'warning', `required secret "${name}" has no setupGuide, and the skill's instructions mention manual credential setup — if obtaining it needs human steps (a dashboard, creating a token, OAuth, granting permissions), add a setupGuide pointing to a reference that explains how, so install can surface it.`, name))
+			}
+		}
+	}
+
+	return results
+})
+
+module.exports = { validate_setup_guides }

package/src/validation/setup_guide_rules.test.js

@@ -0,0 +1,78 @@
+'use strict'
+const { describe, it, beforeEach, afterEach } = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+const { validate_setup_guides } = require('./setup_guide_rules')
+
+const make_tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hs-setupguide-'))
+let dir
+beforeEach(() => { dir = make_tmp() })
+afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }) })
+
+const write_ref = (rel, body = 'guide\n') => {
+	const p = path.join(dir, rel)
+	fs.mkdirSync(path.dirname(p), { recursive: true })
+	fs.writeFileSync(p, body)
+}
+
+describe('validate_setup_guides — correctness', () => {
+	it('errors when a declared setupGuide points to a missing file', async () => {
+		const manifest = { env: { TOK: { required: true, secret: true, setupGuide: 'references/token.md' } } }
+		const [err, results] = await validate_setup_guides(dir, manifest, '# skill\n')
+		assert.ifError(err)
+		const r = results.find(x => x.rule === 'setup_guide_missing')
+		assert.ok(r && r.severity === 'error', 'missing setupGuide file must be an error')
+	})
+
+	it('passes when the setupGuide file exists', async () => {
+		write_ref('references/token.md')
+		const manifest = { env: { TOK: { required: true, secret: true, setupGuide: 'references/token.md' } } }
+		const [err, results] = await validate_setup_guides(dir, manifest, '# skill\n')
+		assert.ifError(err)
+		assert.ok(!results.some(x => x.rule === 'setup_guide_missing'), 'existing guide must not error')
+		assert.ok(!results.some(x => x.rule === 'setup_guide_suggested'), 'declared guide suppresses the floor')
+	})
+
+	it('errors when setupGuide is not a non-empty string', async () => {
+		const manifest = { env: { TOK: { required: true, secret: true, setupGuide: '' } } }
+		const [err, results] = await validate_setup_guides(dir, manifest, '# skill\n')
+		assert.ifError(err)
+		assert.ok(results.some(x => x.rule === 'setup_guide_type' && x.severity === 'error'))
+	})
+})
+
+describe('validate_setup_guides — authoring floor', () => {
+	it('warns when a required secret has no setupGuide AND the text signals manual setup', async () => {
+		const manifest = { env: { CLOUDFLARE_API_TOKEN: { required: true, secret: true } } }
+		const md = '# skill\nCreate an API token in the Cloudflare dashboard and grant these permissions.'
+		const [err, results] = await validate_setup_guides(dir, manifest, md)
+		assert.ifError(err)
+		const r = results.find(x => x.rule === 'setup_guide_suggested')
+		assert.ok(r && r.severity === 'warning' && /CLOUDFLARE_API_TOKEN/.test(r.value || r.message))
+	})
+
+	it('does NOT warn when there is no manual-setup signal in the text (avoid nagging simple skills)', async () => {
+		const manifest = { env: { SOME_TOKEN: { required: true, secret: true } } }
+		const md = '# skill\nThis skill formats text. It needs a token you already have.'
+		const [err, results] = await validate_setup_guides(dir, manifest, md)
+		assert.ifError(err)
+		assert.ok(!results.some(x => x.rule === 'setup_guide_suggested'), 'no signal → no floor warning')
+	})
+
+	it('does NOT warn for a required NON-secret (only secrets trigger the floor)', async () => {
+		const manifest = { env: { REGION: { required: true, secret: false } } }
+		const md = '# skill\nConfigure it in the dashboard console.'
+		const [err, results] = await validate_setup_guides(dir, manifest, md)
+		assert.ifError(err)
+		assert.ok(!results.some(x => x.rule === 'setup_guide_suggested'))
+	})
+
+	it('returns nothing for a skill with no config/env', async () => {
+		const [err, results] = await validate_setup_guides(dir, {}, '# skill\n')
+		assert.ifError(err)
+		assert.deepStrictEqual(results, [])
+	})
+})