happyskills 1.18.0 → 1.20.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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
+
+- Add constellation-aware shared secrets. A non-kit skill that declares `sharedEnv: true` in `skill.json` now shares a single `./secrets/<core>.env` across itself and its skill-dependencies on install, instead of scaffolding an identical per-skill secrets file for every member (the redundant, drift-prone case for related skills). A consumer-set `envFile` still wins, standalone installs and kits are unaffected, and a collision guard warns when two shared members declare the same secret name with a different type. `happyskills validate` now checks `sharedEnv` (must be a boolean; error on a kit; warning when `true` without dependencies). Documented in `docs/skill-format.md` §4.6.
+
 ## [1.18.0] - 2026-07-05
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.18.0",
+	"version": "1.20.0",
 	"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/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,14 +72,61 @@ 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)
 
+	// Constellation shared-env pre-pass (spec: `sharedEnv`). A non-kit package that declares
+	// `sharedEnv: true` is a constellation root: it and every skill-dependency being installed
+	// share ONE derived `.env` (`./secrets/<root>.env`) instead of a redundant, drift-prone file
+	// each. Kits (unrelated bundles) are excluded and keep per-member files. Deterministic: sorted
+	// iteration, first root wins, and a consumer's own envFile pointer (honored in the loop below)
+	// always overrides the shared default.
+	const pkg_keys = new Set((packages || []).map(p => p.skill))
+	const manifest_by_key = new Map()
+	for (const pkg of packages || []) {
+		const pkg_name = pkg.skill.split('/')[1]
+		const [, m] = await read_json(path.join(skill_install_dir(base_dir, pkg_name), SKILL_JSON))
+		if (m) manifest_by_key.set(pkg.skill, m)
+	}
+
+	const shared_env_file_by_key = new Map()
+	for (const root_key of [...pkg_keys].sort()) {
+		const m = manifest_by_key.get(root_key)
+		if (!m || m.sharedEnv !== true || m.type === 'kit') continue
+		const shared_file = `./secrets/${root_key.split('/')[1]}.env`
+		const dep_keys = Object.keys(as_object(m.dependencies) || {})
+		for (const member_key of [root_key, ...dep_keys]) {
+			if (pkg_keys.has(member_key) && !shared_env_file_by_key.has(member_key)) shared_env_file_by_key.set(member_key, shared_file)
+		}
+	}
+
+	// Collision guard: within one shared file, two members declaring the same secret NAME with a
+	// different `type` may not mean the same secret. Warn once so the author reconciles.
+	const shared_secret_seen = new Map() // `${file}\0${name}` -> { type, owner }
+	for (const member_key of [...shared_env_file_by_key.keys()].sort()) {
+		const shared_file = shared_env_file_by_key.get(member_key)
+		const env = as_object((manifest_by_key.get(member_key) || {}).env) || {}
+		for (const [var_name, spec] of Object.entries(env)) {
+			if (!spec || spec.secret !== true) continue
+			const seen_key = `${shared_file}\0${var_name}`
+			const this_type = spec.type === undefined ? null : spec.type
+			const prev = shared_secret_seen.get(seen_key)
+			if (prev) {
+				if (prev.type !== this_type) warnings.push(`Shared-env collision: secret "${var_name}" is declared by ${prev.owner} and ${member_key} with different types in ${shared_file} — verify they are the same secret.`)
+			} else {
+				shared_secret_seen.set(seen_key, { type: this_type, owner: member_key })
+			}
+		}
+	}
+
 	for (const pkg of packages || []) {
 		const key = pkg.skill
 		const name = key.split('/')[1]
-		const install_dir = skill_install_dir(base_dir, name)
-		const [, manifest] = await read_json(path.join(install_dir, SKILL_JSON))
+		const manifest = manifest_by_key.get(key)
 		if (!manifest) continue
 
 		const config_schema = as_object(manifest.config)
@@ -114,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)
@@ -122,7 +169,7 @@ const configure_installed_skills = (packages, options = {}) => catch_errors('Fai
 
 		let env_file_rel = (existing_entry && existing_entry.envFile) || null
 		if (secret_names.length) {
-			env_file_rel = env_file_rel || `./secrets/${name}.env`
+			env_file_rel = env_file_rel || shared_env_file_by_key.get(key) || `./secrets/${name}.env`
 			// Resolve the (possibly consumer-chosen) envFile relative to the config root.
 			const env_abs = path.resolve(config_root, env_file_rel)
 			const [scaffold_err] = await ensure_env_names(env_abs, secret_names.map(s => s.name))
@@ -136,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}`)
+				}
 			}
 		}
 
@@ -147,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 || {})) {
@@ -166,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,147 @@ 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' } } }
+
+	it('routes a shared-env core and its dependency members to ONE derived envFile', async () => {
+		write_skill(base_dir, 'cloudflare', {
+			sharedEnv: true,
+			dependencies: { 'nicolasdao/cloudflare-deploy': '^0.1.0', 'nicolasdao/cloudflare-config': '^0.1.0' },
+			...TOKEN_ENV
+		})
+		write_skill(base_dir, 'cloudflare-deploy', TOKEN_ENV)
+		write_skill(base_dir, 'cloudflare-config', TOKEN_ENV)
+
+		const [err] = await configure_installed_skills(
+			[{ skill: 'nicolasdao/cloudflare' }, { skill: 'nicolasdao/cloudflare-deploy' }, { skill: 'nicolasdao/cloudflare-config' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+
+		const cfg = JSON.parse(read(path.join(config_root, 'skills-config.json')))
+		assert.strictEqual(cfg['nicolasdao/cloudflare'].envFile, './secrets/cloudflare.env')
+		assert.strictEqual(cfg['nicolasdao/cloudflare-deploy'].envFile, './secrets/cloudflare.env')
+		assert.strictEqual(cfg['nicolasdao/cloudflare-config'].envFile, './secrets/cloudflare.env')
+
+		// exactly ONE shared secrets file — the redundant per-member files are not created
+		assert.ok(fs.existsSync(path.join(config_root, 'secrets', 'cloudflare.env')))
+		assert.ok(!fs.existsSync(path.join(config_root, 'secrets', 'cloudflare-deploy.env')))
+		assert.ok(!fs.existsSync(path.join(config_root, 'secrets', 'cloudflare-config.env')))
+
+		// the shared file carries the token name exactly once
+		const env_content = read(path.join(config_root, 'secrets', 'cloudflare.env'))
+		assert.strictEqual((env_content.match(/CLOUDFLARE_API_TOKEN=/g) || []).length, 1)
+	})
+
+	it('respects a consumer-set envFile over the shared default', async () => {
+		fs.writeFileSync(
+			path.join(config_root, 'skills-config.json'),
+			JSON.stringify({ 'nicolasdao/cloudflare-deploy': { envFile: './my-secrets/cf.env' } }, null, '\t')
+		)
+		write_skill(base_dir, 'cloudflare', { sharedEnv: true, dependencies: { 'nicolasdao/cloudflare-deploy': '^0.1.0' }, ...TOKEN_ENV })
+		write_skill(base_dir, 'cloudflare-deploy', TOKEN_ENV)
+
+		const [err] = await configure_installed_skills(
+			[{ skill: 'nicolasdao/cloudflare' }, { skill: 'nicolasdao/cloudflare-deploy' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+
+		const cfg = JSON.parse(read(path.join(config_root, 'skills-config.json')))
+		assert.strictEqual(cfg['nicolasdao/cloudflare-deploy'].envFile, './my-secrets/cf.env') // consumer override wins
+		assert.strictEqual(cfg['nicolasdao/cloudflare'].envFile, './secrets/cloudflare.env')
+	})
+
+	it('does NOT share when the core lacks sharedEnv (regression: per-skill files)', async () => {
+		write_skill(base_dir, 'cloudflare', { dependencies: { 'nicolasdao/cloudflare-deploy': '^0.1.0' }, ...TOKEN_ENV })
+		write_skill(base_dir, 'cloudflare-deploy', TOKEN_ENV)
+
+		const [err] = await configure_installed_skills(
+			[{ skill: 'nicolasdao/cloudflare' }, { skill: 'nicolasdao/cloudflare-deploy' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+
+		const cfg = JSON.parse(read(path.join(config_root, 'skills-config.json')))
+		assert.strictEqual(cfg['nicolasdao/cloudflare'].envFile, './secrets/cloudflare.env')
+		assert.strictEqual(cfg['nicolasdao/cloudflare-deploy'].envFile, './secrets/cloudflare-deploy.env')
+	})
+
+	it('does NOT share for a kit (kit members keep isolated secrets)', async () => {
+		write_skill(base_dir, '_kit-x', { type: 'kit', sharedEnv: true, dependencies: { 'acme/a': '^1.0.0' } })
+		write_skill(base_dir, 'a', TOKEN_ENV)
+
+		const [err] = await configure_installed_skills(
+			[{ skill: 'acme/_kit-x' }, { skill: 'acme/a' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+
+		const cfg = JSON.parse(read(path.join(config_root, 'skills-config.json')))
+		assert.strictEqual(cfg['acme/a'].envFile, './secrets/a.env') // NOT the kit's file
+	})
+
+	it('warns when two shared members declare the same secret with a different type', async () => {
+		write_skill(base_dir, 'core', {
+			sharedEnv: true,
+			dependencies: { 'acme/sat': '^1.0.0' },
+			env: { TOK: { required: true, secret: true, type: 'string' } }
+		})
+		write_skill(base_dir, 'sat', { env: { TOK: { required: true, secret: true, type: 'integer' } } })
+
+		const [err, result] = await configure_installed_skills(
+			[{ skill: 'acme/core' }, { skill: 'acme/sat' }],
+			{ base_dir, config_root, interactive: false }
+		)
+		assert.ifError(err)
+		assert.ok(result.warnings.some(w => /TOK/.test(w) && /shared/i.test(w)), 'a same-name/different-type shared secret must warn')
+	})
+})
+
 describe('configure_installed_skills — reconcile on update (only_required)', () => {
 	it('re-prompts exactly the newly-required field and leaves existing values untouched', async () => {
 		// v1: only `channel` config. Consumer sets it.

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, [])
+	})
+})

package/src/validation/skill_json_rules.js

@@ -277,6 +277,40 @@ const validate_env = (manifest) => {
 	return results
 }
 
+// sharedEnv (constellation-only). When a non-kit skill sets `sharedEnv: true`, the CLI points the
+// skill AND its skill-dependencies at one shared `.env` on install — a constellation shares a
+// config namespace, so its members should not each scaffold an identical secrets file. Forbidden
+// on kits: a kit bundles unrelated skills, which keep isolated secrets. A no-op without deps.
+const validate_shared_env = (manifest) => {
+	const results = []
+	if (manifest.sharedEnv === undefined) return results
+
+	if (typeof manifest.sharedEnv !== 'boolean') {
+		results.push(result('sharedEnv', 'type', 'error', 'sharedEnv must be a boolean'))
+		return results
+	}
+
+	if (manifest.sharedEnv !== true) {
+		results.push(result('sharedEnv', 'valid', 'pass', 'sharedEnv is false'))
+		return results
+	}
+
+	if (manifest.type === SKILL_TYPES.KIT) {
+		results.push(result('sharedEnv', 'kit_forbidden', 'error', 'sharedEnv is not allowed on a kit — kit members bundle unrelated skills and keep isolated secrets. Use sharedEnv only on a constellation core.'))
+		return results
+	}
+
+	const deps = manifest.dependencies
+	const dep_count = deps && typeof deps === 'object' && !Array.isArray(deps) ? Object.keys(deps).length : 0
+	if (dep_count === 0) {
+		results.push(result('sharedEnv', 'no_dependencies', 'warning', 'sharedEnv: true has no effect without dependencies — it shares one .env across the skill and its skill-dependencies (a constellation).'))
+		return results
+	}
+
+	results.push(result('sharedEnv', 'valid', 'pass', 'sharedEnv: true — the skill and its dependencies will share one .env on install'))
+	return results
+}
+
 const validate_skill_json = (skill_dir) => catch_errors('Failed to validate skill.json', async () => {
 	const results = []
 	const json_path = path.join(skill_dir, SKILL_JSON)
@@ -308,6 +342,7 @@ const validate_skill_json = (skill_dir) => catch_errors('Failed to validate skil
 	results.push(...validate_system_dependencies(manifest))
 	results.push(...validate_config(manifest))
 	results.push(...validate_env(manifest))
+	results.push(...validate_shared_env(manifest))
 
 	const is_kit = manifest.type === SKILL_TYPES.KIT
 	if (is_kit) {

package/src/validation/skill_json_rules.test.js

@@ -69,6 +69,40 @@ describe('validate_skill_json — name', () => {
 	})
 })
 
+describe('validate_skill_json — sharedEnv', () => {
+	it('errors when sharedEnv is not a boolean', async () => {
+		write_json(tmp, { name: 'core', version: '1.0.0', sharedEnv: 'yes', dependencies: { 'a/b': '^1.0.0' } })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'sharedEnv' && r.rule === 'type')
+		assert.strictEqual(check.severity, 'error')
+	})
+
+	it('errors when a kit declares sharedEnv: true', async () => {
+		write_json(tmp, { name: '_kit-x', version: '1.0.0', type: 'kit', sharedEnv: true, dependencies: { 'a/b': '^1.0.0' } })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'sharedEnv' && r.rule === 'kit_forbidden')
+		assert.strictEqual(check.severity, 'error')
+	})
+
+	it('warns when sharedEnv: true has no dependencies', async () => {
+		write_json(tmp, { name: 'core', version: '1.0.0', sharedEnv: true })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'sharedEnv' && r.rule === 'no_dependencies')
+		assert.strictEqual(check.severity, 'warning')
+	})
+
+	it('passes for sharedEnv: true with dependencies', async () => {
+		write_json(tmp, { name: 'core', version: '1.0.0', sharedEnv: true, dependencies: { 'a/b': '^1.0.0' } })
+		const [err, data] = await validate_skill_json(tmp)
+		assert.ifError(err)
+		const check = data.results.find(r => r.field === 'sharedEnv' && r.rule === 'valid')
+		assert.strictEqual(check.severity, 'pass')
+	})
+})
+
 describe('validate_skill_json — version', () => {
 	it('errors when version is missing', async () => {
 		write_json(tmp, { name: 'my-skill' })