@tanstack/intent 0.0.29 → 0.0.33

package/dist/index.mjs

@@ -1,13 +1,133 @@
 import { a as parseFrontmatter, n as findSkillFiles, o as resolveDepDir, r as getDeps } from "./utils-COlDcU72.mjs";
-import "./workspace-patterns-Cndd-7vB.mjs";
-import { t as scanForIntents } from "./scanner-B-bbXBLY.mjs";
-import { t as checkStaleness } from "./staleness-SY7-mZMH.mjs";
-import "./project-context-D6A5sBBO.mjs";
-import { r as runSetupGithubActions, t as runEditPackageJson } from "./setup-B4ZwN5Hg.mjs";
+import "./skill-paths-8k9K9y26.mjs";
+import { t as scanForIntents } from "./scanner-CW59cxE_.mjs";
+import "./workspace-patterns-BN2A_60g.mjs";
+import { t as readIntentArtifacts } from "./artifact-coverage-wLNVX8yC.mjs";
+import { n as checkStaleness } from "./staleness-PdgakrCQ.mjs";
+import { i as parseSkillUse, n as formatSkillUse, r as isSkillUseParseError, t as SkillUseParseError } from "./skill-use-uwGleSOz.mjs";
+import { n as isResolveSkillUseError, r as resolveSkillUse, t as ResolveSkillUseError } from "./resolver-D2CgIYGg.mjs";
+import "./project-context-IDLpJU3S.mjs";
+import { r as runSetupGithubActions, t as runEditPackageJson } from "./setup-DfLsziXU.mjs";
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { execFileSync, execSync } from "node:child_process";
 
+//#region src/workflow-review.ts
+function collectStaleReviewItems(reports) {
+	const items = [];
+	for (const report of reports) {
+		for (const skill of report.skills ?? []) {
+			if (!skill?.needsReview) continue;
+			items.push({
+				type: "stale-skill",
+				library: report.library,
+				subject: skill.name,
+				reasons: skill.reasons ?? []
+			});
+		}
+		for (const signal of report.signals ?? []) {
+			if (signal?.needsReview === false) continue;
+			items.push({
+				type: signal?.type ?? "review-signal",
+				library: signal?.library ?? report.library,
+				subject: signal?.packageName ?? signal?.packageRoot ?? signal?.skill ?? signal?.artifactPath ?? signal?.subject ?? report.library,
+				reasons: signal?.reasons ?? [],
+				artifactPath: signal?.artifactPath,
+				packageName: signal?.packageName,
+				packageRoot: signal?.packageRoot,
+				skill: signal?.skill
+			});
+		}
+	}
+	return items;
+}
+function createFailedStaleReviewItem(library) {
+	return {
+		type: "stale-check-failed",
+		library,
+		subject: "intent stale --json",
+		reasons: ["The stale check command failed. Review the workflow logs before updating skills."]
+	};
+}
+function buildStaleReviewBody(items) {
+	const grouped = /* @__PURE__ */ new Map();
+	for (const item of items) grouped.set(item.type, (grouped.get(item.type) ?? 0) + 1);
+	const signalRows = [...grouped.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([type, count]) => `| \`${type}\` | ${count} |`);
+	const itemRows = items.map((item) => {
+		const subject = item.subject ? `\`${item.subject}\`` : "-";
+		const reasons = item.reasons?.length ? item.reasons.join("; ") : "-";
+		return `| \`${item.type}\` | ${subject} | \`${item.library}\` | ${reasons} |`;
+	});
+	const prompt = [
+		"You are helping maintain Intent skills for this repository.",
+		"",
+		"Goal:",
+		"Resolve the Intent skill review signals below while preserving the existing scope, taxonomy, and maintainer-reviewed artifacts.",
+		"",
+		"Review signals:",
+		JSON.stringify(items, null, 2),
+		"",
+		"Required workflow:",
+		"1. Read the existing `_artifacts/*domain_map.yaml`, `_artifacts/*skill_tree.yaml`, and generated `skills/**/SKILL.md` files.",
+		"2. Read each flagged package package.json, public exports, README/docs if present, and source entry points.",
+		"3. Compare flagged packages against the existing domains, skills, tasks, packages, covers, sources, tensions, and cross-references in the artifacts.",
+		"4. For each signal, decide whether it means existing skill coverage, a missing generated skill, a new skill candidate, out-of-scope coverage, or deferred work.",
+		"",
+		"Maintainer questions:",
+		"Before editing skills or artifacts, ask the maintainer:",
+		"1. For each flagged package, is this package user-facing enough to need agent guidance?",
+		"2. If yes, should it extend an existing skill or become a new skill?",
+		"3. If it extends an existing skill, which current skill should own it?",
+		"4. If it is out of scope, what short reason should be recorded in artifact coverage ignores?",
+		"5. Are any of these packages experimental or unstable enough to exclude for now?",
+		"",
+		"Decision rules:",
+		"- Do not auto-generate skills.",
+		"- Do not create broad new skill areas without maintainer confirmation.",
+		"- Prefer adding package coverage to an existing skill when the package is an implementation variant of an existing domain.",
+		"- Create a new skill only when the package introduces a distinct developer task or failure mode.",
+		"- Preserve current naming, path, and package layout conventions.",
+		"- Keep generated skills under the package-local `skills/` directory.",
+		"- Keep repo-root `_artifacts` as the reviewed plan.",
+		"",
+		"If maintainer confirms updates:",
+		"1. Update the relevant `_artifacts/*domain_map.yaml` or `_artifacts/*skill_tree.yaml`.",
+		"2. Update or create `SKILL.md` files only for confirmed coverage changes.",
+		"3. Keep `sources` aligned between artifact skill entries and SKILL frontmatter.",
+		"4. Bump `library_version` only for skills whose covered source package version changed.",
+		"5. Run `npx @tanstack/intent@latest validate` on touched skill directories.",
+		"6. Summarize every package as one of: existing-skill coverage, new skill, ignored, or deferred."
+	].join("\n");
+	return [
+		"## Intent Skill Review Needed",
+		"",
+		"Intent found skills, artifact coverage, or workspace package coverage that need maintainer review.",
+		"",
+		"### Summary",
+		"",
+		"| Signal | Count |",
+		"| --- | ---: |",
+		...signalRows,
+		"",
+		"### Review Items",
+		"",
+		"| Signal | Subject | Library | Reason |",
+		"| --- | --- | --- | --- |",
+		...itemRows,
+		"",
+		"### Agent Prompt",
+		"",
+		"Paste this into your coding agent:",
+		"",
+		"```text",
+		prompt,
+		"```",
+		"",
+		"This PR is a review reminder only. It does not update skills automatically."
+	].join("\n");
+}
+
+//#endregion
 //#region src/feedback.ts
 const META_FEEDBACK_REPO = "TanStack/intent";
 const SECRET_PATTERNS = [
@@ -271,4 +391,4 @@ function submitMetaFeedback(payload, opts) {
 }
 
 //#endregion
-export { checkStaleness, containsSecrets, findSkillFiles, getDeps, hasGhCli, metaToMarkdown, parseFrontmatter, resolveDepDir, resolveFrequency, runEditPackageJson, runSetupGithubActions, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload };
+export { ResolveSkillUseError, SkillUseParseError, buildStaleReviewBody, checkStaleness, collectStaleReviewItems, containsSecrets, createFailedStaleReviewItem, findSkillFiles, formatSkillUse, getDeps, hasGhCli, isResolveSkillUseError, isSkillUseParseError, metaToMarkdown, parseFrontmatter, parseSkillUse, readIntentArtifacts, resolveDepDir, resolveFrequency, resolveSkillUse, runEditPackageJson, runSetupGithubActions, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload };

package/dist/install-PUnIfBNC.mjs

@@ -0,0 +1,542 @@
+import { i as parseSkillUse, n as formatSkillUse } from "./skill-use-uwGleSOz.mjs";
+import { t as resolveProjectContext } from "./project-context-IDLpJU3S.mjs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { parse } from "yaml";
+import { fileURLToPath } from "node:url";
+
+//#region src/cli-error.ts
+const CLI_FAILURE = Symbol("CliFailure");
+function fail(message, exitCode = 1) {
+	throw {
+		[CLI_FAILURE]: true,
+		message,
+		exitCode
+	};
+}
+function isCliFailure(value) {
+	return !!value && typeof value === "object" && CLI_FAILURE in value;
+}
+
+//#endregion
+//#region src/cli-output.ts
+function printWarnings(warnings) {
+	if (warnings.length === 0) return;
+	console.log("Warnings:");
+	for (const warning of warnings) console.log(`  ⚠ ${warning}`);
+}
+
+//#endregion
+//#region src/cli-support.ts
+const INTENT_CHECK_SKILLS_WORKFLOW_VERSION = 2;
+function getMetaDir() {
+	return join(dirname(fileURLToPath(import.meta.url)), "..", "meta");
+}
+function getCheckSkillsWorkflowAdvisories(root) {
+	const workflowPath = join(root, ".github", "workflows", "check-skills.yml");
+	if (!existsSync(workflowPath)) return [];
+	let content;
+	try {
+		content = readFileSync(workflowPath, "utf8");
+	} catch {
+		return [];
+	}
+	const versionMatch = content.match(/intent-workflow-version:\s*(\d+)/);
+	if ((versionMatch ? Number(versionMatch[1]) : 0) >= INTENT_CHECK_SKILLS_WORKFLOW_VERSION) return [];
+	return [`Intent workflow update available: run \`npx @tanstack/intent@latest setup\` to refresh ${relative(process.cwd(), workflowPath) || workflowPath}.`];
+}
+async function scanIntentsOrFail(options) {
+	const { scanForIntents } = await import("./scanner-DlkcbVye.mjs");
+	try {
+		return scanForIntents(void 0, options);
+	} catch (err) {
+		fail(err instanceof Error ? err.message : String(err));
+	}
+}
+function scanOptionsFromGlobalFlags(options) {
+	if (options.global && options.globalOnly) fail("Use either --global or --global-only, not both.");
+	if (options.globalOnly) return { scope: "global" };
+	if (options.global) return { scope: "local-and-global" };
+	return { scope: "local" };
+}
+async function resolveStaleTargets(targetDir) {
+	const resolvedRoot = targetDir ? resolve(process.cwd(), targetDir) : process.cwd();
+	const context = resolveProjectContext({
+		cwd: process.cwd(),
+		targetPath: targetDir
+	});
+	const workflowAdvisories = getCheckSkillsWorkflowAdvisories(context.workspaceRoot ?? context.packageRoot ?? resolvedRoot);
+	const { buildWorkspaceCoverageSignals, checkStaleness, readPackageName } = await import("./staleness-DpbmYod4.mjs");
+	const isWorkspaceRootTarget = context.workspaceRoot !== null && resolvedRoot === context.workspaceRoot;
+	if (context.packageRoot && !isWorkspaceRootTarget && (context.targetSkillsDir !== null || context.workspaceRoot === null)) return {
+		reports: [await checkStaleness(context.packageRoot, readPackageName(context.packageRoot), context.workspaceRoot ?? context.packageRoot)],
+		workflowAdvisories
+	};
+	const { findPackagesWithSkills, findWorkspacePackages, findWorkspaceRoot } = await import("./workspace-patterns-x-dLZxx4.mjs");
+	const workspaceRoot = findWorkspaceRoot(resolvedRoot);
+	if (workspaceRoot) {
+		const packageDirsWithSkills = findPackagesWithSkills(workspaceRoot);
+		const allPackageDirs = findWorkspacePackages(workspaceRoot);
+		const reports = await Promise.all(packageDirsWithSkills.map((packageDir) => checkStaleness(packageDir, readPackageName(packageDir), workspaceRoot)));
+		const { readIntentArtifacts } = await import("./artifact-coverage-BAN2W6aH.mjs");
+		const coverageSignals = buildWorkspaceCoverageSignals({
+			artifactRoot: workspaceRoot,
+			artifacts: existsSync(join(workspaceRoot, "_artifacts")) ? readIntentArtifacts(workspaceRoot) : null,
+			packageDirs: allPackageDirs
+		});
+		if (coverageSignals.length > 0) reports.push({
+			library: relative(process.cwd(), workspaceRoot) || "workspace",
+			currentVersion: null,
+			skillVersion: null,
+			versionDrift: null,
+			skills: [],
+			signals: coverageSignals
+		});
+		if (reports.length > 0) return {
+			reports,
+			workflowAdvisories
+		};
+	}
+	if (existsSync(join(resolvedRoot, "skills"))) return {
+		reports: [await checkStaleness(resolvedRoot, readPackageName(resolvedRoot))],
+		workflowAdvisories
+	};
+	const staleResult = await scanIntentsOrFail();
+	return {
+		reports: await Promise.all(staleResult.packages.map((pkg) => checkStaleness(pkg.packageRoot, pkg.name))),
+		workflowAdvisories
+	};
+}
+
+//#endregion
+//#region src/commands/install-writer.ts
+const INTENT_SKILLS_START = "<!-- intent-skills:start -->";
+const INTENT_SKILLS_END = "<!-- intent-skills:end -->";
+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();
+}
+function readManagedBlock(content) {
+	const start = content.indexOf(INTENT_SKILLS_START);
+	const errors = [];
+	if (start === -1) errors.push("Missing intent-skills start marker.");
+	const endMarkerStart = start === -1 ? content.indexOf(INTENT_SKILLS_END) : content.indexOf(INTENT_SKILLS_END, start);
+	if (endMarkerStart === -1) errors.push("Missing intent-skills end marker.");
+	const hasMarker = start !== -1 || endMarkerStart !== -1;
+	if (errors.length > 0 || start === -1 || endMarkerStart === -1) return {
+		errors,
+		hasMarker,
+		managedBlock: null
+	};
+	const end = endMarkerStart + 26;
+	return {
+		errors,
+		hasMarker,
+		managedBlock: {
+			end,
+			start,
+			text: content.slice(start, end)
+		}
+	};
+}
+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: []
+		};
+		return {
+			errors: [],
+			skills: parsed.skills
+		};
+	} catch (err) {
+		return {
+			errors: [`Managed block contains invalid YAML: ${err instanceof Error ? err.message : String(err)}`],
+			skills: []
+		};
+	}
+}
+function verifyIntentSkillsBlockFile({ expectedBlock, expectedMappingCount, targetPath }) {
+	const errors = [];
+	if (!existsSync(targetPath)) return {
+		errors: [`Agent config file was not created: ${targetPath}`],
+		ok: false
+	};
+	const { managedBlock, errors: markerErrors } = readManagedBlock(readFileSync(targetPath, "utf8"));
+	errors.push(...markerErrors);
+	if (!managedBlock) return {
+		errors,
+		ok: false
+	};
+	const block = managedBlock.text;
+	if (normalizeBlock(block) !== normalizeBlock(expectedBlock)) errors.push("Managed block does not match generated mappings.");
+	if (expectedMappingCount === void 0) return {
+		errors,
+		ok: errors.length === 0
+	};
+	const { skills, 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") {
+			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));
+		}
+	}
+	return {
+		errors,
+		ok: errors.length === 0
+	};
+}
+function resolveIntentSkillsBlockTargetPath(root, mappingCount) {
+	if (mappingCount === 0) return null;
+	return findExistingConfigWithManagedBlock(root)?.filePath ?? join(root, "AGENTS.md");
+}
+function compareNames(a, b) {
+	return a.name.localeCompare(b.name);
+}
+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 `npx @tanstack/intent@latest load <use>`.",
+		"skills:"
+	];
+	let mappingCount = 0;
+	for (const pkg of [...scanResult.packages].sort(compareNames)) for (const skill of [...pkg.skills].sort(compareNames)) {
+		if (!isActionableSkill(skill)) continue;
+		mappingCount++;
+		lines.push(`  - when: ${quoteYamlString(formatWhen(pkg.name, skill))}`);
+		lines.push(`    use: ${quoteYamlString(formatSkillUse(pkg.name, skill.name))}`);
+	}
+	if (mappingCount === 0) lines[2] = "skills: []";
+	lines.push(INTENT_SKILLS_END);
+	return {
+		block: `${lines.join("\n")}\n`,
+		mappingCount
+	};
+}
+function buildIntentSkillGuidanceBlock() {
+	return {
+		block: `${[
+			INTENT_SKILLS_START,
+			"## Skill Loading",
+			"",
+			"Before substantial work:",
+			"- Skill check: run `npx @tanstack/intent@latest list`, or use skills already listed in context.",
+			"- Skill guidance: if one local skill clearly matches the task, run `npx @tanstack/intent@latest load <package>#<skill>` and follow the returned `SKILL.md`.",
+			"- 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
+		].join("\n")}\n`,
+		mappingCount: 0
+	};
+}
+function detectNewline(content) {
+	return content.includes("\r\n") ? "\r\n" : "\n";
+}
+function withNewlineStyle(content, newline) {
+	return newline === "\n" ? content : content.replace(/\n/g, newline);
+}
+function findExistingConfigWithManagedBlock(root) {
+	for (const file of SUPPORTED_AGENT_CONFIG_FILES) {
+		const filePath = join(root, file);
+		if (!existsSync(filePath)) continue;
+		const content = readFileSync(filePath, "utf8");
+		const { managedBlock, errors, hasMarker } = readManagedBlock(content);
+		if (managedBlock) return {
+			content,
+			filePath,
+			managedBlock
+		};
+		if (hasMarker) throw new Error(`Invalid intent-skills block in ${filePath}: ${errors.join(" ")}`);
+	}
+	return null;
+}
+function replaceManagedBlock(content, managedBlock, block) {
+	const newline = detectNewline(content);
+	const styledBlock = withNewlineStyle(block.trimEnd(), newline);
+	return `${content.slice(0, managedBlock.start)}${styledBlock}${content.slice(managedBlock.end)}`;
+}
+function writeIntentSkillsBlock({ block, mappingCount, root, skipWhenEmpty = true }) {
+	if (mappingCount === 0 && skipWhenEmpty) return {
+		mappingCount,
+		status: "skipped",
+		targetPath: null
+	};
+	const existingTarget = findExistingConfigWithManagedBlock(root);
+	const targetPath = existingTarget?.filePath ?? join(root, "AGENTS.md");
+	if (existingTarget) {
+		const nextContent = replaceManagedBlock(existingTarget.content, existingTarget.managedBlock, block);
+		if (nextContent === existingTarget.content) return {
+			mappingCount,
+			status: "unchanged",
+			targetPath
+		};
+		writeFileSync(targetPath, nextContent);
+		return {
+			mappingCount,
+			status: "updated",
+			targetPath
+		};
+	}
+	if (existsSync(targetPath)) {
+		const currentContent = readFileSync(targetPath, "utf8");
+		const newline = detectNewline(currentContent);
+		const separator = currentContent === "" ? "" : newline;
+		writeFileSync(targetPath, `${withNewlineStyle(block, newline)}${separator}${currentContent}`);
+		return {
+			mappingCount,
+			status: "updated",
+			targetPath
+		};
+	}
+	mkdirSync(dirname(targetPath), { recursive: true });
+	writeFileSync(targetPath, block);
+	return {
+		mappingCount,
+		status: "created",
+		targetPath
+	};
+}
+
+//#endregion
+//#region src/commands/install.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.
+
+Hard rules:
+- Do not report success until a file was created or updated, or an existing mapping block was confirmed.
+- 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.
+- 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.
+
+Follow these steps in order:
+
+1. CHECK FOR EXISTING MAPPINGS
+   Search the project's agent config files (AGENTS.md, CLAUDE.md, .cursorrules,
+   .github/copilot-instructions.md) for a block delimited by:
+     <!-- intent-skills:start -->
+     <!-- intent-skills:end -->
+   - If found: show the user the current mappings, keep that file as the source of truth,
+     and ask "What would you like to update?" Then skip to step 4 with their requested changes.
+   - If not found: continue to step 2.
+
+2. DISCOVER AVAILABLE SKILLS
+   Run: \`npx @tanstack/intent@latest list\`
+   This scans project-local node_modules by default and outputs each package and skill's name,
+   description, and source.
+   If the user explicitly wants globally installed skills included, run:
+   \`npx @tanstack/intent@latest list --global\`
+   This works best in Node-compatible environments (npm, pnpm, Bun, or Deno npm interop
+   with node_modules enabled).
+   If no skills are found, do not create a config file. Report: "No intent-enabled skills found."
+
+3. SCAN THE REPOSITORY
+   Build a picture of the project's structure and patterns:
+   - Read package.json for library dependencies
+   - Survey the directory layout (src/, app/, routes/, components/, api/, etc.)
+   - Note recurring patterns (routing, data fetching, auth, UI components, etc.)
+
+   Mapping coverage rule:
+   - Create mappings for all discovered actionable skills.
+   - Do not omit an actionable skill only because the repo does not currently appear to use it.
+   - Do not map reference, meta, maintainer, or maintainer-only skills by default.
+   - Include slash-named sub-skills when no parent mapping exists, or when they describe distinct user tasks.
+   - If the proposed block would exceed 12 mappings, show the full discovered list and ask which packages
+     or skill groups to include before writing.
+   - Add one fallback note telling the agent to run \`npx @tanstack/intent@latest list\` for less common local skills.
+
+   Based on the repository scan and the coverage rule, propose the skill-to-task mappings.
+   For each one explain:
+   - The task or code area (in plain language the user would recognise)
+   - Which skill applies and why
+
+   Then ask: "What other tasks do you commonly use AI coding agents for?
+   I'll create mappings for those too."
+   Also ask: "I'll default to AGENTS.md unless you want another supported config file.
+   Do you have a preference?"
+
+4. WRITE THE MAPPINGS BLOCK
+   Once you have the full set of mappings, write or update the agent config file.
+   - If you found an existing intent-skills block, update that file in place.
+   - Otherwise prefer AGENTS.md by default, unless the user asked for another supported file.
+   - Do not stop after discovery. If skills were found, the task is incomplete until this file exists
+     and contains the managed block.
+
+   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"
+<!-- 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\`
+   - 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>\`
+   - 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
+
+5. VERIFY AND REPORT
+   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 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
+
+   Final response must include:
+   - The target file path
+   - Whether it was created, updated, or already contained a valid block
+   - The number of mappings
+   - The verification result`;
+function formatTargetPath(targetPath) {
+	return relative(process.cwd(), targetPath) || targetPath;
+}
+function formatMappingCount(mappingCount) {
+	return `${mappingCount} ${mappingCount === 1 ? "mapping" : "mappings"}`;
+}
+function printNoActionableSkills(warnings) {
+	console.log("No intent-enabled skills found.");
+	printWarnings(warnings);
+}
+function printPlacementTip(targetPath) {
+	console.log(`Tip: Keep the intent-skills block near the top of ${formatTargetPath(targetPath)} so agents read it before task-specific instructions.`);
+}
+function printWriteResult({ mappingCount, status, targetPath }) {
+	const target = formatTargetPath(targetPath);
+	if (mappingCount === 0) {
+		switch (status) {
+			case "created":
+				console.log(`Created ${target} with skill loading guidance.`);
+				break;
+			case "updated":
+				console.log(`Updated ${target} with skill loading guidance.`);
+				break;
+			case "unchanged":
+				console.log(`No changes to ${target}; skill loading guidance already current.`);
+				break;
+		}
+		return;
+	}
+	switch (status) {
+		case "created":
+			console.log(`Created ${target} with ${formatMappingCount(mappingCount)}.`);
+			break;
+		case "updated":
+			console.log(`Updated ${target} with ${formatMappingCount(mappingCount)}.`);
+			break;
+		case "unchanged":
+			console.log(`No changes to ${target}; ${formatMappingCount(mappingCount)} already current.`);
+			break;
+	}
+}
+async function runInstallCommand(options, scanIntentsOrFail$1) {
+	if (options.printPrompt) {
+		console.log(INSTALL_PROMPT);
+		return;
+	}
+	scanOptionsFromGlobalFlags(options);
+	if (!options.map) {
+		const generated$1 = buildIntentSkillGuidanceBlock();
+		if (options.dryRun) {
+			const targetPath = resolveIntentSkillsBlockTargetPath(process.cwd(), 1);
+			console.log(`Generated skill loading guidance for ${formatTargetPath(targetPath)}.`);
+			console.log(generated$1.block);
+			return;
+		}
+		const result$1 = writeIntentSkillsBlock({
+			...generated$1,
+			root: process.cwd(),
+			skipWhenEmpty: false
+		});
+		if (!result$1.targetPath) fail("Install guidance target was not created.");
+		const verification$1 = verifyIntentSkillsBlockFile({
+			expectedBlock: generated$1.block,
+			targetPath: result$1.targetPath
+		});
+		const target$1 = formatTargetPath(result$1.targetPath);
+		if (!verification$1.ok) fail([`Install verification failed for ${target$1}:`, ...verification$1.errors.map((error) => `- ${error}`)].join("\n"));
+		printWriteResult(result$1);
+		printPlacementTip(result$1.targetPath);
+		return;
+	}
+	const scanResult = await scanIntentsOrFail$1(scanOptionsFromGlobalFlags(options));
+	const generated = buildIntentSkillsBlock(scanResult);
+	if (options.dryRun) {
+		const targetPath = resolveIntentSkillsBlockTargetPath(process.cwd(), generated.mappingCount);
+		if (!targetPath) {
+			printNoActionableSkills(scanResult.warnings);
+			return;
+		}
+		console.log(`Generated ${formatMappingCount(generated.mappingCount)} for ${formatTargetPath(targetPath)}.`);
+		console.log(generated.block);
+		printWarnings(scanResult.warnings);
+		return;
+	}
+	const result = writeIntentSkillsBlock({
+		...generated,
+		root: process.cwd()
+	});
+	if (!result.targetPath) {
+		printNoActionableSkills(scanResult.warnings);
+		return;
+	}
+	const target = formatTargetPath(result.targetPath);
+	const verification = verifyIntentSkillsBlockFile({
+		expectedBlock: generated.block,
+		expectedMappingCount: generated.mappingCount,
+		targetPath: result.targetPath
+	});
+	if (!verification.ok) fail([`Install verification failed for ${target}:`, ...verification.errors.map((error) => `- ${error}`)].join("\n"));
+	printWriteResult(result);
+	printPlacementTip(result.targetPath);
+	printWarnings(scanResult.warnings);
+}
+
+//#endregion
+export { scanIntentsOrFail as a, fail as c, resolveStaleTargets as i, isCliFailure as l, runInstallCommand as n, scanOptionsFromGlobalFlags as o, getMetaDir as r, printWarnings as s, INSTALL_PROMPT as t };