@tanstack/intent 0.2.1 → 0.3.1

package/dist/{install-Bv2qdHwd.mjs → command-BMdho_4n.mjs}

@@ -1,26 +1,34 @@
-import { t as detectPackageManager } from "./package-manager-Dw7lYcI0.mjs";
-import { i as parseSkillUse, n as formatSkillUse } from "./skill-use-B2xRF1i9.mjs";
-import { t as fail } from "./cli-error-DDAO6DIL.mjs";
-import { a as noticeOptionsFromGlobalFlags, l as printNotices, n as coreOptionsFromGlobalFlags, u as printWarnings } from "./cli-support-z64kSJOO.mjs";
-import { t as formatIntentCommand } from "./command-runner-B5OofX0E.mjs";
+import { t as detectPackageManager } from "./package-manager-C63Zi9q1.mjs";
+import { i as parseSkillUse, n as formatSkillUse } from "./use-plp2M918.mjs";
+import { t as fail } from "./cli-error-BebkXaTJ.mjs";
+import { t as formatIntentCommand } from "./command-runner-BFvtjLMh.mjs";
+import { a as noticeOptionsFromGlobalFlags, l as printNotices, n as coreOptionsFromGlobalFlags, u as printWarnings } from "./support-D7lyVf_J.mjs";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { parse } from "yaml";
-//#region src/commands/install-writer.ts
+//#region src/skills/categories.ts
+const MAINTAINER_TYPES = new Set(["maintainer", "maintainer-only"]);
+function getSkillCategory(skill) {
+	const type = skill.type?.trim().toLowerCase();
+	if (type === "reference") return "reference";
+	if (type === "meta") return "meta";
+	if (type && MAINTAINER_TYPES.has(type)) return "maintainer";
+	return "task";
+}
+function isGeneratedMappingSkill(skill) {
+	return getSkillCategory(skill) === "task";
+}
+//#endregion
+//#region src/commands/install/guidance.ts
 const INTENT_SKILLS_START = "<!-- intent-skills:start -->";
 const INTENT_SKILLS_END = "<!-- intent-skills:end -->";
+const LOCAL_PATH_VALUE_PATTERN = /(?:^|[\s"'])(?:\.{1,2}[\\/]|~[\\/]|[A-Za-z]:[\\/]|\/(?:Users|home|private|tmp|var\/folders)[\\/]|[^\s"']*(?:node_modules|\.pnpm|\.bun|\.yarn|\.intent)[\\/])/i;
 const SUPPORTED_AGENT_CONFIG_FILES = [
 	"AGENTS.md",
 	"CLAUDE.md",
 	".cursorrules",
 	".github/copilot-instructions.md"
 ];
-const NON_ACTIONABLE_SKILL_TYPES = new Set([
-	"maintainer",
-	"maintainer-only",
-	"meta",
-	"reference"
-]);
 function normalizeBlock(content) {
 	return content.replace(/\r\n/g, "\n").trimEnd();
 }
@@ -51,21 +59,27 @@ function parseSkillsList(block) {
 	const yamlBody = normalizeBlock(block).split("\n").filter((line) => line !== INTENT_SKILLS_START && line !== INTENT_SKILLS_END).join("\n");
 	try {
 		const parsed = parse(yamlBody);
-		if (!parsed || !Array.isArray(parsed.skills)) return {
-			errors: ["Managed block must contain a skills list."],
-			skills: []
+		if (!parsed || !Array.isArray(parsed.tanstackIntent)) return {
+			errors: ["Managed block must contain a tanstackIntent list."],
+			mappings: []
 		};
 		return {
 			errors: [],
-			skills: parsed.skills
+			mappings: parsed.tanstackIntent
 		};
 	} catch (err) {
 		return {
 			errors: [`Managed block contains invalid YAML: ${err instanceof Error ? err.message : String(err)}`],
-			skills: []
+			mappings: []
 		};
 	}
 }
+function containsLocalPathValue(value) {
+	return LOCAL_PATH_VALUE_PATTERN.test(value);
+}
+function parseLoadedSkillUse(command) {
+	return command.match(/(?:^|&&|\|\||;|\|)\s*(?:bunx\s+@tanstack\/intent(?:@latest)?|pnpm\s+exec\s+intent|pnpm\s+dlx\s+@tanstack\/intent(?:@latest)?|npx\s+@tanstack\/intent(?:@latest)?|yarn\s+dlx\s+@tanstack\/intent(?:@latest)?|intent)\s+load\s+([^\s|;&]+)/i)?.[1] ?? null;
+}
 function verifyIntentSkillsBlockFile({ expectedBlock, expectedMappingCount, targetPath }) {
 	const errors = [];
 	if (!existsSync(targetPath)) return {
@@ -80,27 +94,44 @@ function verifyIntentSkillsBlockFile({ expectedBlock, expectedMappingCount, targ
 	};
 	const block = managedBlock.text;
 	if (normalizeBlock(block) !== normalizeBlock(expectedBlock)) errors.push("Managed block does not match generated mappings.");
+	if (containsLocalPathValue(block)) errors.push("Managed block must not include local file paths.");
 	if (expectedMappingCount === void 0) return {
 		errors,
 		ok: errors.length === 0
 	};
-	const { skills, errors: parseErrors } = parseSkillsList(block);
+	const { mappings, errors: parseErrors } = parseSkillsList(block);
 	errors.push(...parseErrors);
-	if (skills.length !== expectedMappingCount) errors.push(`Expected ${expectedMappingCount} skill mappings, found ${skills.length}.`);
-	for (const skill of skills) {
-		if (!skill || typeof skill !== "object") {
+	if (mappings.length !== expectedMappingCount) errors.push(`Expected ${expectedMappingCount} skill mappings, found ${mappings.length}.`);
+	for (const mappingValue of mappings) {
+		if (!mappingValue || typeof mappingValue !== "object") {
 			errors.push("Each skill mapping must be an object.");
 			continue;
 		}
-		const mapping = skill;
-		if (mapping.load !== void 0) errors.push("Skill mappings must use compact `use` entries, not `load`.");
-		if (typeof mapping.when !== "string" || mapping.when.trim() === "") errors.push("Each skill mapping must include a non-empty `when` field.");
-		if (typeof mapping.use !== "string") errors.push("Each skill mapping must include a `use` field.");
-		else try {
-			parseSkillUse(mapping.use);
-		} catch (err) {
-			errors.push(err instanceof Error ? err.message : String(err));
+		const mapping = mappingValue;
+		if (mapping.use !== void 0) errors.push("Skill mappings must use `id` entries, not `use`.");
+		if (mapping.when !== void 0) errors.push("Skill mappings must use compact `for` entries, not `when`.");
+		let parsedId = null;
+		if (typeof mapping.id !== "string") errors.push("Each skill mapping must include an `id` field.");
+		else {
+			try {
+				parsedId = parseSkillUse(mapping.id);
+			} catch (err) {
+				errors.push(err instanceof Error ? err.message : String(err));
+			}
+			if (containsLocalPathValue(mapping.id)) errors.push("Skill mapping `id` must not include local file paths.");
+		}
+		if (typeof mapping.run !== "string" || mapping.run.trim() === "") errors.push("Each skill mapping must include a non-empty `run` field.");
+		else {
+			const loadedSkillUse = parseLoadedSkillUse(mapping.run);
+			if (!loadedSkillUse) errors.push("Each skill mapping `run` must load its `id`.");
+			else if (parsedId) {
+				const expectedSkillUse = formatSkillUse(parsedId.packageName, parsedId.skillName);
+				if (loadedSkillUse !== expectedSkillUse) errors.push(`Skill mapping \`run\` must load matching \`id\` ${expectedSkillUse}.`);
+			}
+			if (containsLocalPathValue(mapping.run)) errors.push("Skill mapping `run` must not include local file paths.");
 		}
+		if (typeof mapping.for !== "string" || mapping.for.trim() === "") errors.push("Each skill mapping must include a non-empty `for` field.");
+		else if (containsLocalPathValue(mapping.for)) errors.push("Skill mapping `for` must not include local file paths.");
 	}
 	return {
 		errors,
@@ -117,27 +148,24 @@ function compareNames(a, b) {
 function quoteYamlString(value) {
 	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t")}"`;
 }
-function isActionableSkill(skill) {
-	const type = skill.type?.trim().toLowerCase();
-	return !type || !NON_ACTIONABLE_SKILL_TYPES.has(type);
-}
 function formatWhen(packageName, skill) {
 	return skill.description.replace(/\s+/g, " ").trim() || `Use ${packageName} ${skill.name}`;
 }
 function buildIntentSkillsBlock(scanResult) {
 	const lines = [
 		INTENT_SKILLS_START,
-		`# Skill mappings - load \`use\` with \`${formatIntentCommand(scanResult.packageManager, "load <use>")}\`.`,
-		"skills:"
+		"# TanStack Intent - before editing files, run the matching guidance command.",
+		"tanstackIntent:"
 	];
 	let mappingCount = 0;
 	for (const pkg of [...scanResult.packages].sort(compareNames)) for (const skill of [...pkg.skills].sort(compareNames)) {
-		if (!isActionableSkill(skill)) continue;
+		if (!isGeneratedMappingSkill(skill)) continue;
 		mappingCount++;
-		lines.push(`  - when: ${quoteYamlString(formatWhen(pkg.name, skill))}`);
-		lines.push(`    use: ${quoteYamlString(formatSkillUse(pkg.name, skill.name))}`);
+		lines.push(`  - id: ${quoteYamlString(formatSkillUse(pkg.name, skill.name))}`);
+		lines.push(`    run: ${quoteYamlString(formatIntentCommand(scanResult.packageManager, `load ${formatSkillUse(pkg.name, skill.name)}`))}`);
+		lines.push(`    for: ${quoteYamlString(formatWhen(pkg.name, skill))}`);
 	}
-	if (mappingCount === 0) lines[2] = "skills: []";
+	if (mappingCount === 0) lines[2] = "tanstackIntent: []";
 	lines.push(INTENT_SKILLS_END);
 	return {
 		block: `${lines.join("\n")}\n`,
@@ -152,9 +180,10 @@ function buildIntentSkillGuidanceBlock(packageManager = "unknown") {
 			INTENT_SKILLS_START,
 			"## Skill Loading",
 			"",
-			"Before substantial work:",
-			`- Skill check: run \`${listCommand}\`, or use skills already listed in context.`,
-			`- Skill guidance: if one local skill clearly matches the task, run \`${loadCommand}\` and follow the returned \`SKILL.md\`.`,
+			"Before editing files for a substantial task:",
+			`- Run \`${listCommand}\` from the workspace root to see available local skills.`,
+			`- If a listed skill matches the task, run \`${loadCommand}\` before changing files.`,
+			"- Use the loaded `SKILL.md` guidance while making the change.",
 			"- Monorepos: when working across packages, run the skill check from the workspace root and prefer the local skill for the package being changed.",
 			"- Multiple matches: prefer the most specific local skill for the package or concern you are changing; load additional skills only when the task spans multiple packages or concerns.",
 			INTENT_SKILLS_END
@@ -230,7 +259,7 @@ function writeIntentSkillsBlock({ block, mappingCount, root, skipWhenEmpty = tru
 	};
 }
 //#endregion
-//#region src/commands/install.ts
+//#region src/commands/install/command.ts
 const INSTALL_PROMPT = `You are an AI assistant helping a developer set up skill-to-task mappings for their project.
 
 Goal: create or update one agent config file with an intent-skills mapping block.
@@ -240,7 +269,7 @@ Hard rules:
 - If skills are discovered and no mapping block exists, create AGENTS.md unless the user asks for another supported config file.
 - If a mapping block already exists in a supported config file, update that file.
 - Preserve all content outside the managed block unchanged.
-- Store compact \`use\` values in the managed block; do not write \`load\` paths.
+- Store compact \`id\` values and runnable \`run\` commands in the managed block; do not write local paths.
 - Never write absolute local file paths, node_modules paths, or package-manager-internal paths in the managed block.
 - Verify the target file before your final response.
 
@@ -300,19 +329,20 @@ Follow these steps in order:
    Use this exact block:
 
 <!-- intent-skills:start -->
-# Skill mappings - load \`use\` with \`npx @tanstack/intent@latest load <use>\`.
-skills:
-  - when: "describe the task or code area here"
-    use: "@scope/package#skill-name"
+# TanStack Intent - before editing files, run the matching guidance command.
+tanstackIntent:
+  - id: "@scope/package#skill-name"
+    run: "npx @tanstack/intent@latest load @scope/package#skill-name"
+    for: "describe the task or code area here"
 <!-- intent-skills:end -->
 
    Rules:
-   - Use the user's own words for \`when\` descriptions
-   - Use compact \`use\` values in \`<package>#<skill>\` format
-   - Do not include \`load\`
+   - Use the user's own words for \`for\` descriptions
+   - Use compact \`id\` values in \`<package>#<skill>\` format
+   - Include a \`run\` command that loads the matching \`id\`
    - Do not include machine-specific directories such as \`/Users/...\`, \`/home/...\`, \`/private/...\`,
      drive letters, temp workspace paths, \`.pnpm/\`, \`.bun/\`, or \`.yarn/\`.
-   - Agents should load \`use\` at runtime with \`npx @tanstack/intent@latest load <use>\`
+   - Agents should run the \`run\` command before editing matching files
    - Keep entries concise - this block is read on every agent task
    - Preserve all content outside the block tags unchanged
    - If the user is on Deno, note that this setup is best-effort today and relies on npm interop
@@ -321,9 +351,9 @@ skills:
    Before reporting completion:
    - Confirm the target file exists
    - Confirm it contains both managed block markers
-   - Confirm every mapping has \`when\` and \`use\`
-   - Confirm every \`use\` parses as \`<package>#<skill>\`
-   - Confirm no mapping includes \`load\`
+  - Confirm every mapping has \`id\`, \`run\`, and \`for\`
+  - Confirm every \`id\` parses as \`<package>#<skill>\`
+  - Confirm every \`run\` command loads the matching \`id\`
    - Confirm no path-like machine-specific values are stored in the managed block
    - Confirm every discovered actionable skill is mapped, skipped by rule, or deferred by user choice
 

package/dist/{command-runner-B5OofX0E.mjs → command-runner-BFvtjLMh.mjs}

@@ -1,4 +1,4 @@
-//#region src/command-runner.ts
+//#region src/shared/command-runner.ts
 const runnerByPackageManager = {
 	bun: "bunx @tanstack/intent@latest",
 	npm: "npx @tanstack/intent@latest",

package/dist/{core-DaAr5MBD.mjs → core-Bqyle4Vm.mjs}

@@ -1,11 +1,11 @@
-import { d as toPosixPath, i as getDeps, u as resolveDepDir } from "./utils-6FtqhOYf.mjs";
-import { n as scanIntentPackageAtRoot, r as createIntentFsCache } from "./scanner-C5bzzri5.mjs";
-import { n as findWorkspacePackages } from "./workspace-patterns-BDoJIWk-.mjs";
-import { i as parseSkillUse, n as formatSkillUse } from "./skill-use-B2xRF1i9.mjs";
-import { t as resolveProjectContext } from "./project-context-oi_m7paK.mjs";
-import { o as warningMentionsPackage, r as getEffectiveExcludePatterns, t as compileExcludePatterns } from "./excludes-ByvSbmmj.mjs";
-import { i as resolveSkillUse, r as resolveSkillEntry, t as ResolveSkillUseError } from "./resolver-Uwx8B5jv.mjs";
-import { a as checkLoadAllowed, o as readSkillSourcesConfig, s as scanForPolicedIntents } from "./source-policy-D__bcpoU.mjs";
+import { d as toPosixPath, i as getDeps, u as resolveDepDir } from "./utils-Bw7HwOo5.mjs";
+import { n as findWorkspacePackages } from "./workspace-patterns-hW0v_meY.mjs";
+import { n as scanIntentPackageAtRoot, r as createIntentFsCache } from "./scanner-B1pcLFee.mjs";
+import { i as parseSkillUse, n as formatSkillUse } from "./use-plp2M918.mjs";
+import { t as resolveProjectContext } from "./project-context-CALU5-15.mjs";
+import { o as warningMentionsPackage, r as getEffectiveExcludePatterns, t as compileExcludePatterns } from "./excludes-BEi9N7Ys.mjs";
+import { i as resolveSkillUse, r as resolveSkillEntry, t as ResolveSkillUseError } from "./resolver-6i-WBbh8.mjs";
+import { a as checkLoadAllowed, o as readSkillSourcesConfig, s as scanForPolicedIntents } from "./source-policy-CzZqrSTS.mjs";
 import { existsSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 //#region src/core/markdown.ts
@@ -328,7 +328,7 @@ function resolveSkillUseFastPath(parsedUse, options, context = resolveProjectCon
 	return resolveFromPackageRoots(getWorkspaceLoadFastPathCandidateDirs(parsedUse.packageName, context, fsCache), parsedUse, cwd, fsCache);
 }
 //#endregion
-//#region src/core.ts
+//#region src/core/intent-core.ts
 var IntentCoreError = class extends Error {
 	constructor(code, message, options = {}) {
 		super(message);
@@ -360,7 +360,7 @@ function listIntentSkills(options = {}) {
 	const scanOptions = toScanOptions(options);
 	const fsCache = createIntentFsCache();
 	const projectContext = resolveProjectContext({ cwd });
-	const { scan, excludePatterns } = scanForPolicedIntents({
+	const { hiddenSourceCount, hiddenSources, scan, excludePatterns } = scanForPolicedIntents({
 		cwd,
 		scanOptions: withFsCache(scanOptions, fsCache),
 		coreOptions: options,
@@ -390,6 +390,8 @@ function listIntentSkills(options = {}) {
 			packageRoot: pkg.packageRoot,
 			skillCount: pkg.skills.length
 		})),
+		hiddenSourceCount,
+		hiddenSources,
 		warnings: scan.warnings,
 		notices: scan.notices,
 		conflicts: scan.conflicts

package/dist/core.d.mts

@@ -1,13 +1,19 @@
-import { _ as VersionConflict, c as PackageManager, d as ScanScope, f as ScanStats, s as IntentPackage } from "./types-ByXUTBJ2.mjs";
+import { _ as VersionConflict, c as PackageManager, d as ScanScope, f as ScanStats, s as IntentPackage } from "./types-Bx6-umBo.mjs";
 
 //#region src/core/types.d.ts
 interface IntentCoreOptions {
+  audience?: IntentAudience;
   cwd?: string;
   debug?: boolean;
   global?: boolean;
   globalOnly?: boolean;
   exclude?: Array<string>;
 }
+type IntentAudience = 'agent' | 'human';
+interface IntentHiddenSourceSummary {
+  name: string;
+  skillCount: number;
+}
 interface IntentSkillSummary {
   use: string;
   packageName: string;
@@ -30,6 +36,8 @@ interface IntentSkillList {
   packageManager: PackageManager;
   skills: Array<IntentSkillSummary>;
   packages: Array<IntentPackageSummary>;
+  hiddenSourceCount: number;
+  hiddenSources: Array<IntentHiddenSourceSummary>;
   warnings: Array<string>;
   notices: Array<string>;
   conflicts: Array<VersionConflict>;
@@ -75,7 +83,7 @@ interface LoadedIntentSkillDebug {
 }
 type IntentCoreErrorCode = 'invalid-options' | 'invalid-skill-use' | 'package-not-found' | 'package-excluded' | 'package-not-listed' | 'skill-excluded' | 'skill-not-found' | 'skill-path-outside-package' | 'skill-file-not-found';
 //#endregion
-//#region src/core.d.ts
+//#region src/core/intent-core.d.ts
 declare class IntentCoreError extends Error {
   readonly code: IntentCoreErrorCode;
   readonly suggestedSkills?: Array<string>;

package/dist/core.mjs

@@ -1,2 +1,2 @@
-import { i as resolveIntentSkill, n as listIntentSkills, r as loadIntentSkill, t as IntentCoreError } from "./core-DaAr5MBD.mjs";
+import { i as resolveIntentSkill, n as listIntentSkills, r as loadIntentSkill, t as IntentCoreError } from "./core-Bqyle4Vm.mjs";
 export { IntentCoreError, listIntentSkills, loadIntentSkill, resolveIntentSkill };

package/dist/{display-CnpA7XuV.mjs → display-Dc1feMcZ.mjs}

@@ -1,5 +1,5 @@
-import { n as isStableLoadPath, t as formatRuntimeSkillLookupHint } from "./skill-paths-Bm1P6IYe.mjs";
-//#region src/display.ts
+import { n as isStableLoadPath, t as formatRuntimeSkillLookupHint } from "./paths-B0KW7rmz.mjs";
+//#region src/shared/display.ts
 function padColumn(text, width) {
 	return text.length >= width ? text + "  " : text.padEnd(width);
 }

package/dist/{edit-package-json-D8xfcy2X.mjs → edit-package-json-CdnA7_TA.mjs}

@@ -1,6 +1,6 @@
-//#region src/commands/edit-package-json.ts
+//#region src/commands/setup/edit-package-json.ts
 async function runEditPackageJsonCommand(root) {
-	const { runEditPackageJsonAll } = await import("./setup.mjs");
+	const { runEditPackageJsonAll } = await import("./setup-DFajGERl.mjs");
 	runEditPackageJsonAll(root);
 }
 //#endregion

package/dist/{exclude-DbHwcgQQ.mjs → exclude-IfSv-XI_.mjs}

@@ -1,5 +1,5 @@
-import { t as compileExcludePatterns } from "./excludes-ByvSbmmj.mjs";
-import { t as fail } from "./cli-error-DDAO6DIL.mjs";
+import { t as compileExcludePatterns } from "./excludes-BEi9N7Ys.mjs";
+import { t as fail } from "./cli-error-BebkXaTJ.mjs";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 //#region src/commands/exclude.ts

package/dist/{excludes-ByvSbmmj.mjs → excludes-BEi9N7Ys.mjs}

@@ -1,4 +1,4 @@
-import { t as resolveProjectContext } from "./project-context-oi_m7paK.mjs";
+import { t as resolveProjectContext } from "./project-context-CALU5-15.mjs";
 import { readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 //#region src/core/package-json.ts

package/dist/{setup-github-actions-IxZTZihi.mjs → github-actions-D41VZqWh.mjs}

@@ -1,6 +1,6 @@
-//#region src/commands/setup-github-actions.ts
+//#region src/commands/setup/github-actions.ts
 async function runSetupGithubActionsCommand(root, metaDir) {
-	const { runSetupGithubActions } = await import("./setup.mjs");
+	const { runSetupGithubActions } = await import("./setup-DFajGERl.mjs");
 	runSetupGithubActions(root, metaDir);
 }
 //#endregion

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { _ as VersionConflict, a as IntentArtifactWarning, g as StalenessSignal, h as StalenessReport, i as IntentArtifactSkill, l as ScanOptions, m as SkillStaleness, n as IntentArtifactFile, o as IntentConfig, p as SkillEntry, r as IntentArtifactSet, s as IntentPackage, t as IntentArtifactCoverageIgnore, u as ScanResult } from "./types-ByXUTBJ2.mjs";
-import { i as runEditPackageJson, o as runSetupGithubActions, r as SetupGithubActionsResult, t as EditPackageJsonResult } from "./setup-CdfBc7Oe.mjs";
+import { _ as VersionConflict, a as IntentArtifactWarning, g as StalenessSignal, h as StalenessReport, i as IntentArtifactSkill, l as ScanOptions, m as SkillStaleness, n as IntentArtifactFile, o as IntentConfig, p as SkillEntry, r as IntentArtifactSet, s as IntentPackage, t as IntentArtifactCoverageIgnore, u as ScanResult } from "./types-Bx6-umBo.mjs";
+import { i as runEditPackageJson, o as runSetupGithubActions, r as SetupGithubActionsResult, t as EditPackageJsonResult } from "./project-setup-Bvmg5uYy.mjs";
 import { closeSync, existsSync, lstatSync, openSync, readFileSync, readSync, readdirSync, realpathSync } from "node:fs";
 
-//#region src/utils.d.ts
+//#region src/shared/utils.d.ts
 /**
  * The subset of `node:fs` the scanner reads through. Under Yarn PnP this is
  * swapped for Yarn's libzip-patched `fs` so reads can reach files inside
@@ -40,16 +40,16 @@ declare function resolveDepDir(depName: string, parentDir: string): string | nul
  */
 declare function parseFrontmatter(filePath: string, fs?: ReadFs): Record<string, unknown> | null;
 //#endregion
-//#region src/scanner.d.ts
+//#region src/discovery/scanner.d.ts
 declare function scanForIntents(root?: string, options?: ScanOptions): ScanResult;
 //#endregion
-//#region src/staleness.d.ts
+//#region src/staleness/check.d.ts
 declare function checkStaleness(packageDir: string, packageName?: string, artifactRoot?: string): Promise<StalenessReport>;
 //#endregion
-//#region src/artifact-coverage.d.ts
+//#region src/staleness/artifact-coverage.d.ts
 declare function readIntentArtifacts(root: string): IntentArtifactSet | null;
 //#endregion
-//#region src/workflow-review.d.ts
+//#region src/staleness/workflow-review.d.ts
 interface StaleReviewItem {
   type: string;
   library: string;
@@ -64,7 +64,7 @@ declare function collectStaleReviewItems(reports: Array<StalenessReport>): Array
 declare function createFailedStaleReviewItem(library: string): StaleReviewItem;
 declare function buildStaleReviewBody(items: Array<StaleReviewItem>): string;
 //#endregion
-//#region src/skill-use.d.ts
+//#region src/skills/use.d.ts
 interface SkillUse {
   packageName: string;
   skillName: string;
@@ -79,7 +79,7 @@ declare function isSkillUseParseError(error: unknown): error is SkillUseParseErr
 declare function formatSkillUse(packageName: string, skillName: string): string;
 declare function parseSkillUse(value: string): SkillUse;
 //#endregion
-//#region src/resolver.d.ts
+//#region src/skills/resolver.d.ts
 interface ResolveSkillResult {
   packageName: string;
   skillName: string;

package/dist/index.mjs

@@ -1,9 +1,9 @@
-import { c as parseFrontmatter, i as getDeps, r as findSkillFiles, u as resolveDepDir } from "./utils-6FtqhOYf.mjs";
-import { t as scanForIntents } from "./scanner-C5bzzri5.mjs";
-import { t as readIntentArtifacts } from "./artifact-coverage-DFtI6V_H.mjs";
-import { n as checkStaleness } from "./staleness-DoZU3lzy.mjs";
-import { n as collectStaleReviewItems, r as createFailedStaleReviewItem, t as buildStaleReviewBody } from "./workflow-review-B4AfwtHH.mjs";
-import { i as parseSkillUse, n as formatSkillUse, r as isSkillUseParseError, t as SkillUseParseError } from "./skill-use-B2xRF1i9.mjs";
-import { i as resolveSkillUse, n as isResolveSkillUseError, t as ResolveSkillUseError } from "./resolver-Uwx8B5jv.mjs";
-import { r as runSetupGithubActions, t as runEditPackageJson } from "./setup-Cx1r2y-1.mjs";
+import { c as parseFrontmatter, i as getDeps, r as findSkillFiles, u as resolveDepDir } from "./utils-Bw7HwOo5.mjs";
+import { t as scanForIntents } from "./scanner-B1pcLFee.mjs";
+import { t as readIntentArtifacts } from "./artifact-coverage-DerRKsWw.mjs";
+import { n as checkStaleness } from "./staleness-I_jAT1Ge.mjs";
+import { n as collectStaleReviewItems, r as createFailedStaleReviewItem, t as buildStaleReviewBody } from "./workflow-review-CEwwmDdD.mjs";
+import { i as parseSkillUse, n as formatSkillUse, r as isSkillUseParseError, t as SkillUseParseError } from "./use-plp2M918.mjs";
+import { i as resolveSkillUse, n as isResolveSkillUseError, t as ResolveSkillUseError } from "./resolver-6i-WBbh8.mjs";
+import { r as runSetupGithubActions, t as runEditPackageJson } from "./setup-D5qLjoqf.mjs";
 export { ResolveSkillUseError, SkillUseParseError, buildStaleReviewBody, checkStaleness, collectStaleReviewItems, createFailedStaleReviewItem, findSkillFiles, formatSkillUse, getDeps, isResolveSkillUseError, isSkillUseParseError, parseFrontmatter, parseSkillUse, readIntentArtifacts, resolveDepDir, resolveSkillUse, runEditPackageJson, runSetupGithubActions, scanForIntents };

package/dist/{list-C-eGocZP.mjs → list-DUXFVM5r.mjs}

@@ -1,6 +1,7 @@
-import { n as listIntentSkills } from "./core-DaAr5MBD.mjs";
-import { a as noticeOptionsFromGlobalFlags, l as printNotices, n as coreOptionsFromGlobalFlags, o as printDebugInfo, u as printWarnings } from "./cli-support-z64kSJOO.mjs";
-import { t as formatIntentCommand } from "./command-runner-B5OofX0E.mjs";
+import { n as listIntentSkills } from "./core-Bqyle4Vm.mjs";
+import { c as detectIntentAudience } from "./source-policy-CzZqrSTS.mjs";
+import { t as formatIntentCommand } from "./command-runner-BFvtjLMh.mjs";
+import { a as noticeOptionsFromGlobalFlags, l as printNotices, n as coreOptionsFromGlobalFlags, o as printDebugInfo, u as printWarnings } from "./support-D7lyVf_J.mjs";
 //#region src/commands/list.ts
 function printListDebug(result) {
 	if (!result.debug) return;
@@ -45,8 +46,21 @@ function getPackageSkills(pkg, skillsByPackageRoot) {
 function formatLoadCommand(skill, packageManager, scopeFlag) {
 	return formatIntentCommand(packageManager, `load ${skill.use}${scopeFlag}`);
 }
+function printHiddenSources(result, audience) {
+	if (audience === "agent") {
+		console.log("Hidden skill sources are not revealed in agent sessions. Run this command outside the agent session to review candidates.");
+		return;
+	}
+	if (result.hiddenSources.length === 0) return;
+	console.log("\nHidden skill sources:\n");
+	for (const source of result.hiddenSources) console.log(`  ${source.name} (${source.skillCount} ${source.skillCount === 1 ? "skill" : "skills"})`);
+}
 async function runListCommand(options) {
-	const result = listIntentSkills(coreOptionsFromGlobalFlags(options));
+	const audience = detectIntentAudience();
+	const result = listIntentSkills({
+		...coreOptionsFromGlobalFlags(options),
+		audience
+	});
 	const noticeOptions = noticeOptionsFromGlobalFlags(options);
 	printListDebug(result);
 	if (options.json) {
@@ -54,9 +68,10 @@ async function runListCommand(options) {
 		console.log(JSON.stringify(jsonResult, null, 2));
 		return;
 	}
-	const { computeSkillNameWidth, printSkillTree, printTable } = await import("./display-CnpA7XuV.mjs");
+	const { computeSkillNameWidth, printSkillTree, printTable } = await import("./display-Dc1feMcZ.mjs");
 	if (result.packages.length === 0) {
 		console.log("No intent-enabled packages found.");
+		if (options.showHidden && result.hiddenSourceCount > 0) printHiddenSources(result, audience);
 		if (result.warnings.length > 0) {
 			console.log();
 			printWarnings(result.warnings);
@@ -77,6 +92,7 @@ async function runListCommand(options) {
 		String(pkg.skillCount)
 	]));
 	printVersionConflicts(result);
+	if (options.showHidden) printHiddenSources(result, audience);
 	const skillsByPackageRoot = groupSkillsByPackageRoot(result.skills);
 	const nameWidth = computeSkillNameWidth(result.packages.map((pkg) => getPackageSkills(pkg, skillsByPackageRoot).map((skill) => ({
 		name: skill.skillName,

package/dist/{load-DDNrmeBz.mjs → load-DieqITz5.mjs}

@@ -1,6 +1,6 @@
-import { t as fail } from "./cli-error-DDAO6DIL.mjs";
-import { i as resolveIntentSkill, r as loadIntentSkill, t as IntentCoreError } from "./core-DaAr5MBD.mjs";
-import { n as coreOptionsFromGlobalFlags, o as printDebugInfo } from "./cli-support-z64kSJOO.mjs";
+import { t as fail } from "./cli-error-BebkXaTJ.mjs";
+import { i as resolveIntentSkill, r as loadIntentSkill, t as IntentCoreError } from "./core-Bqyle4Vm.mjs";
+import { n as coreOptionsFromGlobalFlags, o as printDebugInfo } from "./support-D7lyVf_J.mjs";
 //#region src/commands/load.ts
 function printLoadDebug(loaded) {
 	if (!loaded.debug) return;

package/dist/{meta-CF4XIYOo.mjs → meta-Dk7d0N2J.mjs}

@@ -1,4 +1,4 @@
-import { t as fail } from "./cli-error-DDAO6DIL.mjs";
+import { t as fail } from "./cli-error-BebkXaTJ.mjs";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 //#region src/commands/meta.ts
@@ -15,7 +15,7 @@ async function runMetaCommand(name, metaDir) {
 		}
 		return;
 	}
-	const { parseFrontmatter } = await import("./utils-BKBDYbCx.mjs");
+	const { parseFrontmatter } = await import("./utils-BpmAIjiN.mjs");
 	const entries = readdirSync(metaDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).filter((entry) => existsSync(join(metaDir, entry.name, "SKILL.md")));
 	if (entries.length === 0) {
 		console.log("No meta-skills found.");

package/dist/{package-manager-Dw7lYcI0.mjs → package-manager-C63Zi9q1.mjs}

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-//#region src/package-manager.ts
+//#region src/discovery/package-manager.ts
 function readPackageManagerField(dir) {
 	try {
 		const parsed = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));

package/dist/{skill-paths-Bm1P6IYe.mjs → paths-B0KW7rmz.mjs}

@@ -1,7 +1,7 @@
-import { d as toPosixPath } from "./utils-6FtqhOYf.mjs";
+import { d as toPosixPath } from "./utils-Bw7HwOo5.mjs";
 import { existsSync } from "node:fs";
 import { join, relative } from "node:path";
-//#region src/skill-paths.ts
+//#region src/skills/paths.ts
 function isAbsolutePath(path) {
 	return path.startsWith("/") || path.startsWith("\\") || /^[A-Za-z]:[\\/]/.test(path);
 }

package/dist/{project-context-oi_m7paK.mjs → project-context-CALU5-15.mjs}

@@ -1,4 +1,4 @@
-import { a as readWorkspacePatterns, r as findWorkspaceRoot } from "./workspace-patterns-BDoJIWk-.mjs";
+import { a as readWorkspacePatterns, r as findWorkspaceRoot } from "./workspace-patterns-hW0v_meY.mjs";
 import { existsSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 //#region src/core/project-context.ts

package/dist/{setup-CdfBc7Oe.d.mts → project-setup-Bvmg5uYy.d.mts}

@@ -1,10 +1,10 @@
-//#region src/workspace-patterns.d.ts
+//#region src/setup/workspace-patterns.d.ts
 declare function readWorkspacePatterns(root: string): Array<string> | null;
 declare function resolveWorkspacePackages(root: string, patterns: Array<string>): Array<string>;
 declare function findWorkspaceRoot(start: string): string | null;
 declare function findPackagesWithSkills(root: string): Array<string>;
 //#endregion
-//#region src/setup.d.ts
+//#region src/setup/project-setup.d.ts
 interface EditPackageJsonResult {
   added: Array<string>;
   alreadyPresent: Array<string>;

package/dist/{resolver-Uwx8B5jv.mjs → resolver-6i-WBbh8.mjs}

@@ -1,6 +1,6 @@
-import { i as parseSkillUse } from "./skill-use-B2xRF1i9.mjs";
-import { o as warningMentionsPackage } from "./excludes-ByvSbmmj.mjs";
-//#region src/resolver.ts
+import { i as parseSkillUse } from "./use-plp2M918.mjs";
+import { o as warningMentionsPackage } from "./excludes-BEi9N7Ys.mjs";
+//#region src/skills/resolver.ts
 var ResolveSkillUseError = class extends Error {
 	constructor({ availablePackages = [], availableSkills = [], code, packageName, skillName, suggestedSkills = [], use }) {
 		super(formatResolveSkillUseErrorMessage({