@tanstack/intent 0.0.12 → 0.0.14

package/README.md

@@ -1,23 +1,23 @@
 # @tanstack/intent
 
-Ship compositional knowledge for AI coding agents alongside your npm packages.
+A CLI for library maintainers to generate, validate, and ship [Agent Skills](https://agentskills.io) alongside their npm packages.
 
 ## The problem
 
 Your docs are good. Your types are solid. Your agent still gets it wrong.
 
-Docs target humans who browse. Types check individual API calls but can't encode intent. Training data snapshots the ecosystem as it _was_, mixing versions without flagging which applies. Once a breaking change ships, models contain _both_ versions forever with no way to disambiguate.
+Docs target humans who browse. Types check individual API calls but can't encode intent. Training data snapshots the ecosystem as it _was_, mixing versions with no way to tell which applies. Once a breaking change ships, models develop a permanent split-brain — training data contains _both_ versions forever with no way to disambiguate.
 
 The ecosystem already moves toward agent-readable knowledge — Cursor rules, CLAUDE.md files, skills directories. But delivery is stuck in copy-paste: hunt for a community-maintained rules file, paste it into your config, repeat for every tool. No versioning, no update path, no staleness signal.
 
-## Skills: the fourth artifact
+## Skills: versioned knowledge in npm
 
-You ship code, docs, and types. Skills are the fourth artifact — knowledge encoded for the thing writing most of your code.
-
-Skills are npm packages of knowledge — encoding how tools compose, which patterns fit which goals, and what to avoid. When a library ships skills using `@tanstack/intent`, that knowledge travels with the tool via `npm update` — not the model's training cutoff. Versioned knowledge the maintainer owns, updated when the package updates.
+A skill is a short, versioned document that tells agents how to use a specific capability of your library — correct patterns, common mistakes, and when to apply them. Skills ship inside your npm package and travel with the tool via `npm update` — not the model's training cutoff, not community-maintained rules files, not prompt snippets in READMEs. Versioned knowledge the maintainer owns, updated when the package updates.
 
 Each skill declares its source docs. When those docs change, the CLI flags the skill for review. One source of truth, one derived artifact that stays in sync.
 
+The [Agent Skills spec](https://agentskills.io) is an open standard already adopted by VS Code, GitHub Copilot, OpenAI Codex, Cursor, Claude Code, Goose, Amp, and others.
+
 ## Quick Start
 
 ### For library consumers
@@ -25,15 +25,15 @@ Each skill declares its source docs. When those docs change, the CLI flags the s
 Set up skill-to-task mappings in your project's agent config files (CLAUDE.md, .cursorrules, etc.):
 
 ```bash
-npx @tanstack/intent install
+npx @tanstack/intent@latest install
 ```
 
-No per-library setup. No hunting for rules files. Install the package, run `intent install`, and the agent understands the tool. Update the package, and skills update too.
+No per-library setup. No hunting for rules files. Install the package, run `npx @tanstack/intent@latest install`, and the agent understands the tool. Update the package, and skills update too.
 
 List available skills from installed packages:
 
 ```bash
-npx @tanstack/intent list
+npx @tanstack/intent@latest list
 ```
 
 ### For library maintainers
@@ -41,47 +41,47 @@ npx @tanstack/intent list
 Generate skills for your library by telling your AI coding agent to run:
 
 ```bash
-npx @tanstack/intent scaffold
+npx @tanstack/intent@latest scaffold
 ```
 
-This prints a prompt that walks the agent through domain discovery, skill tree generation, and skill creation — one step at a time with your review at each stage.
+This walks the agent through domain discovery, skill tree generation, and skill creation — one step at a time with your review at each stage.
 
 Validate your skill files:
 
 ```bash
-npx @tanstack/intent validate
+npx @tanstack/intent@latest validate
 ```
 
 Check for skills that have fallen behind their sources:
 
 ```bash
-npx @tanstack/intent stale
+npx @tanstack/intent@latest stale
 ```
 
 Copy CI workflow templates into your repo so validation and staleness checks run on every push:
 
 ```bash
-npx @tanstack/intent setup
+npx @tanstack/intent@latest setup-github-actions
 ```
 
 ## Keeping skills current
 
-The real risk with any derived artifact is staleness. `npx @tanstack/intent stale` flags skills whose source docs have changed, and CI templates catch drift before it ships.
+The real risk with any derived artifact is staleness. `npx @tanstack/intent@latest stale` flags skills whose source docs have changed, and CI templates catch drift before it ships.
 
-The feedback loop runs both directions. `npx @tanstack/intent feedback` lets users submit structured reports when a skill produces wrong output — which skill, which version, what broke. That context flows back to the maintainer, and the fix ships to everyone on the next `npm update`.
+The feedback loop runs both directions. `npx @tanstack/intent@latest feedback` lets users submit structured reports when a skill produces wrong output — which skill, which version, what broke. That context flows back to the maintainer, and the fix ships to everyone on the next `npm update`. Every support interaction produces an artifact that prevents the same class of problem for all future users — not just the one who reported it.
 
 ## CLI Commands
 
-| Command                               | Description                                         |
-| ------------------------------------- | --------------------------------------------------- |
-| `npx @tanstack/intent install`        | Set up skill-to-task mappings in agent config files |
-| `npx @tanstack/intent list [--json]`  | Discover intent-enabled packages                    |
-| `npx @tanstack/intent meta`           | List meta-skills for library maintainers            |
-| `npx @tanstack/intent scaffold`       | Print the guided skill generation prompt            |
-| `npx @tanstack/intent validate [dir]` | Validate SKILL.md files                             |
-| `npx @tanstack/intent setup`          | Copy CI templates, generate shim, create labels     |
-| `npx @tanstack/intent stale [--json]` | Check skills for version drift                      |
-| `npx @tanstack/intent feedback`       | Submit skill feedback                               |
+| Command                                            | Description                                         |
+| -------------------------------------------------- | --------------------------------------------------- |
+| `npx @tanstack/intent@latest install`              | Set up skill-to-task mappings in agent config files |
+| `npx @tanstack/intent@latest list [--json]`        | Discover intent-enabled packages                    |
+| `npx @tanstack/intent@latest meta`                 | List meta-skills for library maintainers            |
+| `npx @tanstack/intent@latest scaffold`             | Print the guided skill generation prompt            |
+| `npx @tanstack/intent@latest validate [dir]`       | Validate SKILL.md files                             |
+| `npx @tanstack/intent@latest setup-github-actions` | Copy CI templates into your repo                    |
+| `npx @tanstack/intent@latest stale [--json]`       | Check skills for version drift                      |
+| `npx @tanstack/intent@latest feedback`             | Submit skill feedback                               |
 
 ## License
 

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { n as parseFrontmatter, t as findSkillFiles } from "./utils-DH3jY3CI.mjs";
-import { t as scanForIntents } from "./scanner-dIYdkHQ1.mjs";
+import { r as parseFrontmatter, t as findSkillFiles } from "./utils-CDJzAdjD.mjs";
+import { t as scanForIntents } from "./scanner-CY40iozO.mjs";
 import { n as printSkillTree, r as printTable, t as computeSkillNameWidth } from "./display-D_XzuGnu.mjs";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
@@ -65,12 +65,33 @@ async function cmdList(args) {
 		for (const w of result.warnings) console.log(`  ⚠ ${w}`);
 	}
 }
-function cmdMeta() {
+function cmdMeta(args) {
 	const metaDir = getMetaDir();
 	if (!existsSync(metaDir)) {
 		console.error("Meta-skills directory not found.");
 		process.exit(1);
 	}
+	if (args.length > 0) {
+		const name = args[0];
+		if (name.includes("..") || name.includes("/") || name.includes("\\")) {
+			console.error(`Invalid meta-skill name: "${name}"`);
+			process.exit(1);
+		}
+		const skillFile = join(metaDir, name, "SKILL.md");
+		if (!existsSync(skillFile)) {
+			console.error(`Meta-skill "${name}" not found.`);
+			console.error(`Run \`npx @tanstack/intent meta\` to list available meta-skills.`);
+			process.exit(1);
+		}
+		try {
+			console.log(readFileSync(skillFile, "utf8"));
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			console.error(`Failed to read meta-skill "${name}": ${msg}`);
+			process.exit(1);
+		}
+		return;
+	}
 	const entries = readdirSync(metaDir, { withFileTypes: true }).filter((e) => e.isDirectory()).filter((e) => existsSync(join(metaDir, e.name, "SKILL.md")));
 	if (entries.length === 0) {
 		console.log("No meta-skills found.");
@@ -290,8 +311,8 @@ This produces: individual SKILL.md files.
 3. For each publishable package, run: \`npx @tanstack/intent add-library-bin\`
 4. For each publishable package, run: \`npx @tanstack/intent edit-package-json\`
 5. Ensure each package has \`@tanstack/intent\` as a devDependency
-6. Create a \`feedback:<skill-name>\` label on the GitHub repo for each skill (use \`gh label create\`)
-7. Add a README note: "If you use an AI agent, run \`npx @tanstack/intent install\`"
+6. Create a \`skill:<skill-name>\` label on the GitHub repo for each skill (use \`gh label create\`)
+7. Add a README note: "If you use an AI agent, run \`npx @tanstack/intent@latest install\`"
 `;
 	console.log(prompt);
 }
@@ -299,7 +320,7 @@ const USAGE = `TanStack Intent CLI
 
 Usage:
   intent list [--json]           Discover intent-enabled packages
-  intent meta                    List meta-skills for maintainers
+  intent meta [name]             List meta-skills, or print one by name
   intent validate [<dir>]        Validate skill files (default: skills/)
   intent install                  Print a skill that guides your coding agent to set up skill-to-task mappings
   intent scaffold                Print maintainer scaffold prompt
@@ -314,7 +335,7 @@ switch (command) {
 		await cmdList(commandArgs);
 		break;
 	case "meta":
-		cmdMeta();
+		cmdMeta(commandArgs);
 		break;
 	case "validate":
 		cmdValidate(commandArgs);
@@ -371,8 +392,8 @@ skills:
 		cmdScaffold();
 		break;
 	case "stale": {
-		const { checkStaleness } = await import("./staleness-B5gUj7FR.mjs");
-		const { scanForIntents: scanStale } = await import("./scanner-DQeiZRzp.mjs");
+		const { checkStaleness } = await import("./staleness-C1h7RuZ9.mjs");
+		const { scanForIntents: scanStale } = await import("./scanner-CECGXgox.mjs");
 		let staleResult;
 		try {
 			staleResult = await scanStale();

package/dist/index.d.mts

@@ -39,9 +39,21 @@ declare function submitMetaFeedback(payload: MetaFeedbackPayload, opts: {
  * Recursively find all SKILL.md files under a directory.
  */
 declare function findSkillFiles(dir: string): string[];
+/**
+ * Read dependencies and peerDependencies (and optionally devDependencies) from
+ * a parsed package.json object.
+ */
+declare function getDeps(pkgJson: Record<string, unknown>, includeDevDeps?: boolean): string[];
+/**
+ * Resolve the directory of a dependency by name. First checks the top-level
+ * node_modules (hoisted layout — npm, yarn, bun), then resolves through the
+ * parent package's real path to handle pnpm's virtual store layout where
+ * transitive deps are siblings in the .pnpm virtual store node_modules.
+ */
+declare function resolveDepDir(depName: string, parentDir: string, parentName: string, nodeModulesDir: string): string | null;
 /**
  * Parse YAML frontmatter from a file. Returns null if no frontmatter or on error.
  */
 declare function parseFrontmatter(filePath: string): Record<string, unknown> | null;
 //#endregion
-export { type AddLibraryBinResult, type AgentName, type EditPackageJsonResult, type FeedbackPayload, type IntentConfig, type IntentPackage, type IntentProjectConfig, type MetaFeedbackPayload, type MetaSkillName, type ScanResult, type SetupGithubActionsResult, type SkillEntry, type SkillStaleness, type StalenessReport, checkStaleness, containsSecrets, findSkillFiles, hasGhCli, metaToMarkdown, parseFrontmatter, resolveFrequency, runAddLibraryBin, runEditPackageJson, runSetupGithubActions, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload };
+export { type AddLibraryBinResult, type AgentName, type EditPackageJsonResult, type FeedbackPayload, type IntentConfig, type IntentPackage, type IntentProjectConfig, type MetaFeedbackPayload, type MetaSkillName, type ScanResult, type SetupGithubActionsResult, type SkillEntry, type SkillStaleness, type StalenessReport, checkStaleness, containsSecrets, findSkillFiles, getDeps, hasGhCli, metaToMarkdown, parseFrontmatter, resolveDepDir, resolveFrequency, runAddLibraryBin, runEditPackageJson, runSetupGithubActions, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload };

package/dist/index.mjs

@@ -1,7 +1,7 @@
-import { n as parseFrontmatter, t as findSkillFiles } from "./utils-DH3jY3CI.mjs";
-import { t as scanForIntents } from "./scanner-dIYdkHQ1.mjs";
-import { t as checkStaleness } from "./staleness-lP6B0O4z.mjs";
-import { n as runEditPackageJson, r as runSetupGithubActions, t as runAddLibraryBin } from "./setup-BYOg-Ii-.mjs";
+import { i as resolveDepDir, n as getDeps, r as parseFrontmatter, t as findSkillFiles } from "./utils-CDJzAdjD.mjs";
+import { t as scanForIntents } from "./scanner-CY40iozO.mjs";
+import { t as checkStaleness } from "./staleness-DJfMKH62.mjs";
+import { n as runEditPackageJson, r as runSetupGithubActions, t as runAddLibraryBin } from "./setup-Nif1-nhS.mjs";
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { execFileSync, execSync } from "node:child_process";
@@ -212,7 +212,7 @@ function submitMetaFeedback(payload, opts) {
 			"--title",
 			`Meta-Skill Feedback: ${payload.metaSkill} (${payload.userRating})`,
 			"--label",
-			`feedback:${payload.metaSkill}`,
+			`skill:${payload.metaSkill}`,
 			"--body",
 			"-"
 		], {
@@ -246,4 +246,4 @@ function submitMetaFeedback(payload, opts) {
 }
 
 //#endregion
-export { checkStaleness, containsSecrets, findSkillFiles, hasGhCli, metaToMarkdown, parseFrontmatter, resolveFrequency, runAddLibraryBin, runEditPackageJson, runSetupGithubActions, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload };
+export { checkStaleness, containsSecrets, findSkillFiles, getDeps, hasGhCli, metaToMarkdown, parseFrontmatter, resolveDepDir, resolveFrequency, runAddLibraryBin, runEditPackageJson, runSetupGithubActions, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload };

package/dist/intent-library.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import "./utils-DH3jY3CI.mjs";
+import "./utils-CDJzAdjD.mjs";
 import { n as printSkillTree, r as printTable, t as computeSkillNameWidth } from "./display-D_XzuGnu.mjs";
-import { t as scanLibrary } from "./library-scanner-V9sTOhrb.mjs";
+import { t as scanLibrary } from "./library-scanner-B1tmOzwf.mjs";
 
 //#region src/intent-library.ts
 async function cmdList() {

package/dist/{library-scanner-V9sTOhrb.mjs → library-scanner-B1tmOzwf.mjs}

@@ -1,4 +1,4 @@
-import { n as parseFrontmatter } from "./utils-DH3jY3CI.mjs";
+import { i as resolveDepDir, n as getDeps, r as parseFrontmatter } from "./utils-CDJzAdjD.mjs";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
 
@@ -24,14 +24,6 @@ function hasIntentBin(pkg) {
 	if (!bin || typeof bin !== "object") return false;
 	return "intent" in bin;
 }
-function getDeps(pkg) {
-	const seen = /* @__PURE__ */ new Set();
-	for (const field of ["dependencies", "peerDependencies"]) {
-		const d = pkg[field];
-		if (d && typeof d === "object") for (const name of Object.keys(d)) seen.add(name);
-	}
-	return [...seen];
-}
 function discoverSkills(skillsDir) {
 	const skills = [];
 	function walk(dir) {
@@ -97,8 +89,8 @@ async function scanLibrary(scriptPath, projectRoot) {
 			skills: existsSync(skillsDir) ? discoverSkills(skillsDir) : []
 		});
 		for (const depName of getDeps(pkg)) {
-			const depDir = join(nodeModulesDir, depName);
-			if (!existsSync(depDir)) continue;
+			const depDir = resolveDepDir(depName, dir, name, nodeModulesDir);
+			if (!depDir) continue;
 			const depPkg = readPkgJson(depDir);
 			if (depPkg && hasIntentBin(depPkg)) processPackage(depName, depDir);
 		}

package/dist/library-scanner.mjs

@@ -1,4 +1,4 @@
-import "./utils-DH3jY3CI.mjs";
-import { t as scanLibrary } from "./library-scanner-V9sTOhrb.mjs";
+import "./utils-CDJzAdjD.mjs";
+import { t as scanLibrary } from "./library-scanner-B1tmOzwf.mjs";
 
 export { scanLibrary };

package/dist/scanner-CECGXgox.mjs

@@ -0,0 +1,4 @@
+import "./utils-CDJzAdjD.mjs";
+import { t as scanForIntents } from "./scanner-CY40iozO.mjs";
+
+export { scanForIntents };

package/dist/{scanner-dIYdkHQ1.mjs → scanner-CY40iozO.mjs}

@@ -1,4 +1,4 @@
-import { n as parseFrontmatter } from "./utils-DH3jY3CI.mjs";
+import { i as resolveDepDir, n as getDeps, r as parseFrontmatter } from "./utils-CDJzAdjD.mjs";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 
@@ -143,31 +143,69 @@ async function scanForIntents(root) {
 			}
 		} else if (!entry.name.startsWith(".")) packageDirs.push({ dirPath });
 	}
-	for (const { dirPath } of packageDirs) {
+	const foundNames = /* @__PURE__ */ new Set();
+	/**
+	* Try to register a package with a skills/ directory. Reads its
+	* package.json, validates intent config, discovers skills, and pushes
+	* to `packages`. Returns true if the package was registered.
+	*/
+	function tryRegister(dirPath, fallbackName) {
 		const skillsDir = join(dirPath, "skills");
-		if (!existsSync(skillsDir)) continue;
-		const pkgJsonPath = join(dirPath, "package.json");
+		if (!existsSync(skillsDir)) return false;
 		let pkgJson;
 		try {
-			pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+			pkgJson = JSON.parse(readFileSync(join(dirPath, "package.json"), "utf8"));
 		} catch {
 			warnings.push(`Could not read package.json for ${dirPath}`);
-			continue;
+			return false;
 		}
-		const pkgName = typeof pkgJson.name === "string" ? pkgJson.name : "unknown";
-		const pkgVersion = typeof pkgJson.version === "string" ? pkgJson.version : "0.0.0";
-		const intent = validateIntentField(pkgName, pkgJson.intent) ?? deriveIntentConfig(pkgJson);
+		const name = typeof pkgJson.name === "string" ? pkgJson.name : fallbackName;
+		if (foundNames.has(name)) return false;
+		const intent = validateIntentField(name, pkgJson.intent) ?? deriveIntentConfig(pkgJson);
 		if (!intent) {
-			warnings.push(`${pkgName} has a skills/ directory but could not determine repo/docs from package.json (add a "repository" field or explicit "intent" config)`);
-			continue;
+			warnings.push(`${name} has a skills/ directory but could not determine repo/docs from package.json (add a "repository" field or explicit "intent" config)`);
+			return false;
 		}
-		const skills = discoverSkills(skillsDir, pkgName);
 		packages.push({
-			name: pkgName,
-			version: pkgVersion,
+			name,
+			version: typeof pkgJson.version === "string" ? pkgJson.version : "0.0.0",
 			intent,
-			skills
+			skills: discoverSkills(skillsDir, name)
 		});
+		foundNames.add(name);
+		return true;
+	}
+	for (const { dirPath } of packageDirs) tryRegister(dirPath, "unknown");
+	const walkVisited = /* @__PURE__ */ new Set();
+	function walkDeps(pkgDir, pkgName) {
+		if (walkVisited.has(pkgName)) return;
+		walkVisited.add(pkgName);
+		let pkgJson;
+		try {
+			pkgJson = JSON.parse(readFileSync(join(pkgDir, "package.json"), "utf8"));
+		} catch {
+			warnings.push(`Could not read package.json for ${pkgName} (skipping dependency walk)`);
+			return;
+		}
+		for (const depName of getDeps(pkgJson)) {
+			if (foundNames.has(depName) || walkVisited.has(depName)) continue;
+			const depDir = resolveDepDir(depName, pkgDir, pkgName, nodeModulesDir);
+			if (!depDir) continue;
+			tryRegister(depDir, depName);
+			walkDeps(depDir, depName);
+		}
+	}
+	for (const pkg of [...packages]) walkDeps(join(nodeModulesDir, pkg.name), pkg.name);
+	let projectPkg = null;
+	try {
+		projectPkg = JSON.parse(readFileSync(join(projectRoot, "package.json"), "utf8"));
+	} catch (err) {
+		if (!(err && typeof err === "object" && "code" in err && err.code === "ENOENT")) warnings.push(`Could not read project package.json: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (projectPkg) for (const depName of getDeps(projectPkg, true)) {
+		if (walkVisited.has(depName)) continue;
+		const depDir = join(nodeModulesDir, depName);
+		if (existsSync(join(depDir, "package.json"))) walkDeps(depDir, depName);
 	}
 	return {
 		packageManager,

package/dist/{setup-BYOg-Ii-.mjs → setup-Nif1-nhS.mjs}

@@ -55,7 +55,21 @@ function getShimContent(ext) {
 // Exposes the intent end-user CLI for consumers of this library.
 // Commit this file, then add to your package.json:
 //   "bin": { "intent": "./bin/intent.${ext}" }
-await import('@tanstack/intent/intent-library')
+try {
+  await import('@tanstack/intent/intent-library')
+} catch (e) {
+  if (e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND') {
+    console.error('@tanstack/intent is not installed.')
+    console.error('')
+    console.error('Install it as a dev dependency:')
+    console.error('  npm add -D @tanstack/intent')
+    console.error('')
+    console.error('Or run directly:')
+    console.error('  npx @tanstack/intent@latest list')
+    process.exit(1)
+  }
+  throw e
+}
 `;
 }
 function detectShimExtension(root) {

package/dist/setup.mjs

@@ -1,3 +1,3 @@
-import { n as runEditPackageJson, r as runSetupGithubActions, t as runAddLibraryBin } from "./setup-BYOg-Ii-.mjs";
+import { n as runEditPackageJson, r as runSetupGithubActions, t as runAddLibraryBin } from "./setup-Nif1-nhS.mjs";
 
 export { runAddLibraryBin, runEditPackageJson, runSetupGithubActions };

package/dist/staleness-C1h7RuZ9.mjs

@@ -0,0 +1,4 @@
+import "./utils-CDJzAdjD.mjs";
+import { t as checkStaleness } from "./staleness-DJfMKH62.mjs";
+
+export { checkStaleness };

package/dist/{staleness-lP6B0O4z.mjs → staleness-DJfMKH62.mjs}

@@ -1,4 +1,4 @@
-import { n as parseFrontmatter, t as findSkillFiles } from "./utils-DH3jY3CI.mjs";
+import { r as parseFrontmatter, t as findSkillFiles } from "./utils-CDJzAdjD.mjs";
 import { readFileSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 

package/dist/utils-CDJzAdjD.mjs

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parse } from "yaml";
+
+//#region src/utils.ts
+/**
+* Recursively find all SKILL.md files under a directory.
+*/
+function findSkillFiles(dir) {
+	const files = [];
+	if (!existsSync(dir)) return files;
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		const fullPath = join(dir, entry.name);
+		if (entry.isDirectory()) files.push(...findSkillFiles(fullPath));
+		else if (entry.name === "SKILL.md") files.push(fullPath);
+	}
+	return files;
+}
+/**
+* Read dependencies and peerDependencies (and optionally devDependencies) from
+* a parsed package.json object.
+*/
+function getDeps(pkgJson, includeDevDeps = false) {
+	const deps = /* @__PURE__ */ new Set();
+	const fields = includeDevDeps ? [
+		"dependencies",
+		"devDependencies",
+		"peerDependencies"
+	] : ["dependencies", "peerDependencies"];
+	for (const field of fields) {
+		const d = pkgJson[field];
+		if (d && typeof d === "object") for (const name of Object.keys(d)) deps.add(name);
+	}
+	return [...deps];
+}
+/**
+* Resolve the directory of a dependency by name. First checks the top-level
+* node_modules (hoisted layout — npm, yarn, bun), then resolves through the
+* parent package's real path to handle pnpm's virtual store layout where
+* transitive deps are siblings in the .pnpm virtual store node_modules.
+*/
+function resolveDepDir(depName, parentDir, parentName, nodeModulesDir) {
+	if (!parentName) return null;
+	const topLevel = join(nodeModulesDir, depName);
+	if (existsSync(join(topLevel, "package.json"))) return topLevel;
+	try {
+		const realParent = realpathSync(parentDir);
+		const segments = parentName.split("/").length;
+		let nmDir = realParent;
+		for (let i = 0; i < segments; i++) nmDir = dirname(nmDir);
+		const nested = join(nmDir, depName);
+		if (existsSync(join(nested, "package.json"))) return nested;
+	} catch (err) {
+		const code = err && typeof err === "object" && "code" in err ? err.code : void 0;
+		if (code !== "ENOENT" && code !== "ENOTDIR") console.warn(`Warning: could not resolve ${depName} from ${parentDir}: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	return null;
+}
+/**
+* Parse YAML frontmatter from a file. Returns null if no frontmatter or on error.
+*/
+function parseFrontmatter(filePath) {
+	let content;
+	try {
+		content = readFileSync(filePath, "utf8");
+	} catch {
+		return null;
+	}
+	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!match?.[1]) return null;
+	try {
+		return parse(match[1]);
+	} catch {
+		return null;
+	}
+}
+
+//#endregion
+export { resolveDepDir as i, getDeps as n, parseFrontmatter as r, findSkillFiles as t };

package/meta/feedback-collection/SKILL.md

@@ -29,7 +29,17 @@ can be improved.
 
 Review your own session transcript. No human interaction needed yet.
 
-### 1a: Gap detection
+### 1a: Skills inventory
+
+Before analyzing gaps and errors, inventory all skills that were available
+during the session:
+
+- **Loaded and used:** Skills you read and actively followed.
+- **Available but not loaded:** Skills that were installed (discoverable via
+  `intent list`) but you never read. This is important — many issues stem from
+  the agent not loading the right skill, not from the skill itself being wrong.
+
+### 1b: Gap detection
 
 Identify moments where the skill was silent and you had to bridge the gap
 yourself — via code reading, search, trial-and-error, or general knowledge.
@@ -40,7 +50,7 @@ For each gap, note:
 - What the skill should have told you
 - How you solved it (code reading, web search, guessing)
 
-### 1b: Error/correction tracking
+### 1c: Error/correction tracking
 
 Identify moments where the skill prescribed an approach that produced an error.
 
@@ -50,7 +60,7 @@ For each error, note:
 - The error or incorrect behavior that resulted
 - The fix you applied
 
-### 1c: Human intervention events
+### 1d: Human intervention events
 
 Identify moments where the human clarified, corrected, or overrode your approach.
 
@@ -60,7 +70,7 @@ For each intervention, note:
 - What the human said or changed
 - Whether the skill could have prevented this
 
-### 1d: Step duration anomalies
+### 1e: Step duration anomalies
 
 Identify steps that consumed disproportionate effort compared to their apparent
 complexity. These signal that the skill should provide a template, snippet, or
@@ -107,21 +117,31 @@ referenced.
 
 [one-sentence summary of what the human asked you to do]
 
+## Skills Inventory
+
+**Loaded and used:**
+
+- [list each skill the agent read and actively followed during the session]
+
+**Available but not loaded:**
+
+- [list skills that were installed/available but the agent never read]
+
 ## What Worked
 
 [patterns/instructions from the skill that were accurate and helpful]
 
 ## What Failed
 
-[from 1b — skill instructions that produced errors]
+[from 1c — skill instructions that produced errors]
 
 ## Missing
 
-[from 1a — gaps where the skill should have covered]
+[from 1b — gaps where the skill should have covered]
 
 ## Self-Corrections
 
-[from 1b fixes + 1c human interventions, combined]
+[from 1c fixes + 1d human interventions, combined]
 
 ## User Comments
 
@@ -136,10 +156,11 @@ referenced.
 | Package          | The npm package the skill lives in (e.g. `@tanstack/query-intent`) |
 | Skill version    | Frontmatter `metadata.version` or `library_version`                |
 | Task             | Summarize the human's original request in one sentence             |
+| Skills Inventory | Which skills were loaded vs. available but not loaded (see below)  |
 | What Worked      | List skill sections/patterns that were correct and useful          |
-| What Failed      | From 1b — skill instructions that produced errors                  |
-| Missing          | From 1a — gaps where the skill was silent                          |
-| Self-Corrections | From 1b fixes + 1c human interventions, combined                   |
+| What Failed      | From 1c — skill instructions that produced errors                  |
+| Missing          | From 1b — gaps where the skill was silent                          |
+| Self-Corrections | From 1c fixes + 1d human interventions, combined                   |
 | Rating           | From Phase 2 sentiment analysis or explicit rating                 |
 | User Comments    | From Phase 2 answers, keep brief                                   |
 
@@ -177,7 +198,7 @@ not contain project-specific details. Before submission:
 Submit directly as a GitHub issue:
 
 ```bash
-gh issue create --repo [owner/repo] --title "Skill Feedback: [skill-name] ([rating])" --label "feedback:[skill-name]" --body-file intent-feedback.md
+gh issue create --repo [owner/repo] --title "Skill Feedback: [skill-name] ([rating])" --label "skill:[skill-name]" --body-file intent-feedback.md
 ```
 
 If the label doesn't exist, omit the `--label` flag — don't let a missing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/intent",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "Ship compositional knowledge for AI coding agents alongside your npm packages",
   "license": "MIT",
   "type": "module",

package/dist/scanner-DQeiZRzp.mjs

@@ -1,4 +0,0 @@
-import "./utils-DH3jY3CI.mjs";
-import { t as scanForIntents } from "./scanner-dIYdkHQ1.mjs";
-
-export { scanForIntents };

package/dist/staleness-B5gUj7FR.mjs

@@ -1,4 +0,0 @@
-import "./utils-DH3jY3CI.mjs";
-import { t as checkStaleness } from "./staleness-lP6B0O4z.mjs";
-
-export { checkStaleness };

package/dist/utils-DH3jY3CI.mjs

@@ -1,39 +0,0 @@
-import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { join } from "node:path";
-import { parse } from "yaml";
-
-//#region src/utils.ts
-/**
-* Recursively find all SKILL.md files under a directory.
-*/
-function findSkillFiles(dir) {
-	const files = [];
-	if (!existsSync(dir)) return files;
-	for (const entry of readdirSync(dir, { withFileTypes: true })) {
-		const fullPath = join(dir, entry.name);
-		if (entry.isDirectory()) files.push(...findSkillFiles(fullPath));
-		else if (entry.name === "SKILL.md") files.push(fullPath);
-	}
-	return files;
-}
-/**
-* Parse YAML frontmatter from a file. Returns null if no frontmatter or on error.
-*/
-function parseFrontmatter(filePath) {
-	let content;
-	try {
-		content = readFileSync(filePath, "utf8");
-	} catch {
-		return null;
-	}
-	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-	if (!match?.[1]) return null;
-	try {
-		return parse(match[1]);
-	} catch {
-		return null;
-	}
-}
-
-//#endregion
-export { parseFrontmatter as n, findSkillFiles as t };