neon 8.11.4 → 8.12.1

package/README.md

@@ -58,6 +58,13 @@ of them is Homebrew, the warning recommends `brew uninstall neonctl`, which
 leaves `neon` running the other install, such as npm. While duplicates remain, the update notice is held back;
 `NO_UPDATE_NOTIFIER=1` silences both.
 
+Commands also warn once a day when Neon agent skills are behind their source, in this
+directory's `skills-lock.json` or the user-level skills lock (see
+[`neon skills status`](#install-neon-agent-skills-skills)). This warning runs without a
+terminal too, so coding agents see it. It checks GitHub once a day in the background and
+follows the same CI, machine-readable output, standalone binary, and
+`NO_UPDATE_NOTIFIER=1` rules.
+
 ## Connect
 
 Run the following command to authenticate a connection to Neon:
@@ -973,8 +980,14 @@ $ neon skills --global
 $ neon skills update
 $ neon skills update -y
 $ neon skills update --global -y
+
+# Check whether installed Neon skills are behind their source.
+$ neon skills status
+$ neon skills status --global
 ```
 
+`neon skills status` compares each Neon skill in this directory's `skills-lock.json` (or, with `--global`, the user-level skills lock) with the skill folder on its source repository's default branch, and prints `up to date`, `outdated`, or `not found upstream` per skill. It reads GitHub anonymously; set `GITHUB_TOKEN` or `GH_TOKEN` if the GitHub API rate limit is reached. Skills installed through an agent plugin are not in either lock and are not listed.
+
 On a TTY the command asks which agents and which skills, then installs. Detected agents start selected from project-folder markers such as `.cursor`. Default skills start selected. `neon-postgres-agent-platforms` is offered and starts unselected.
 
 `-y` skips those questions and installs the default skills into detected agents: project-folder markers such as `.cursor`, else the agent driving the CLI. `--agent` / `-a` names coding agents and skips the agent picker. `--skill` / `-s` names specific skills and skips the skill picker; it does not select agents. `--global -y` uses installed apps, else the host CLI agent. Without a TTY, pass `-y`, or `--skill <name>` (add `--agent <name>` to name agents). If `-y` finds no agent, it exits: pass `--agent <name>`, run from a supported agent, or omit `-y` in a terminal to pick.
@@ -1565,7 +1578,7 @@ Global options are supported with any Neon CLI command.
 
 - <a id="analytics"></a>`--analytics`
 
-  Analytics are enabled by default to gather information about the CLI commands and options that are used by our customers. This data collection assists in offering support, and allows for a better understanding of typical usage patterns so that we can improve user experience. Neon does not collect user-defined data, such as project IDs or command payloads, except the question passed to `neon ask --prompt` and the query passed to `neon docs search`. The Neon search service records each `neon docs search` query with the CLI version and the detected coding agent; with `--no-analytics` it records nothing. When the CLI fails on an internal bug (a JavaScript `TypeError`, `ReferenceError`, `RangeError`, or `SyntaxError`), it also sends that error to Neon's Sentry: the error type, the message only when it is a standard JavaScript message that names nothing but code (any other message is replaced), the stack trace with file paths cut to the package (`neon/dist/...`), the CLI and Node.js versions, and whether it ran in CI or a coding agent. To opt-out of analytics data collection and error reports, specify `--no-analytics` or `--analytics false`.
+  Analytics are enabled by default to gather information about the CLI commands and options that are used by our customers. This data collection assists in offering support, and allows for a better understanding of typical usage patterns so that we can improve user experience. Neon does not collect user-defined data, such as project IDs or command payloads, except the question passed to `neon ask --prompt` and the query passed to `neon docs search`. Each successful command also reports the Neon agent skills recorded in the user-level skills lock and in the current directory's `skills-lock.json`: the skill names, their lock hashes, and whether each is behind its source, read from local files without a network request. The Neon search service records each `neon docs search` query with the CLI version and the detected coding agent; with `--no-analytics` it records nothing. When the CLI fails on an internal bug (a JavaScript `TypeError`, `ReferenceError`, `RangeError`, or `SyntaxError`), it also sends that error to Neon's Sentry: the error type, the message only when it is a standard JavaScript message that names nothing but code (any other message is replaced), the stack trace with file paths cut to the package (`neon/dist/...`), the CLI and Node.js versions, and whether it ran in CI or a coding agent. To opt-out of analytics data collection and error reports, specify `--no-analytics` or `--analytics false`.
 
 - <a id="version"></a>`-v, --version`
 

package/dist/_chunks/{skills-DyiBXKS3.js → skills-BP6pIm7O.js}

@@ -10,9 +10,10 @@ import { noPassthrough } from "../utils/flags.js";
 import { AGENT_SKILLS_SKIP_MESSAGE } from "../init/copy.js";
 import { canPickAgentsInteractively, skippableAgentPicker } from "../utils/agent_picker.js";
 import { skillsHelpValues, skillsYesHelp } from "../skills/catalog.js";
+import { lockPath, neonSkillsUpdateCommand, readLockedSkills, refreshSkillsCheckCache, scopeLabel, skillsCheckCachePath, skillsStatusRows } from "../skills/freshness.js";
 import { confirmSkillsUpdate } from "../skills/wizard.js";
 import { assertSkillsCanRun, resolveSkillsPlan } from "../skills/plan.js";
-import { assertSkillsNode, neonSkillsRetryCommand, neonSkillsUpdateRetryCommand, runSkillsCli, skillsAddArgs, skillsMetadata, skillsUpdateArgs, skillsUpdateDetail, skillsUpdateHadNothing } from "../skills/run.js";
+import { assertSkillsNode, neonSkillsRetryCommand, runSkillsCli, skillsAddArgs, skillsMetadata, skillsUpdateArgs, skillsUpdateDetail, skillsUpdateHadNothing } from "../skills/run.js";
 //#region src/commands/skills.ts
 var skills_exports = /* @__PURE__ */ __exportAll({
 	aliases: () => aliases,
@@ -24,7 +25,6 @@ var skills_exports = /* @__PURE__ */ __exportAll({
 	reportSkillsInstall: () => reportSkillsInstall,
 	skillsInstallError: () => skillsInstallError
 });
-const scopeLabel = (scope) => scope === "project" ? "this directory" : "user-level";
 const coerceAgents = (value) => {
 	if (value === void 0) return [];
 	const list = Array.isArray(value) ? value : [value];
@@ -60,7 +60,17 @@ const builder = (argv) => argv.usage("$0 skills [command] [options]").command("u
 	const skills = args.skill;
 	if (Array.isArray(skills) && skills.length > 0) throw new Error("neon skills update does not take --skill. It refreshes every installed skill in this directory (or --global).");
 	return true;
-}), (args) => updateHandler(args)).options({
+}), (args) => updateHandler(args)).command("status", "Check whether installed Neon skills match their source", (yargs) => yargs.usage("$0 skills status [options]").options({ global: {
+	type: "boolean",
+	default: false,
+	describe: "Check user-level skills (skills CLI -g). Default is this directory"
+} }).example("$0 skills status", "Neon skills in this directory's skills-lock.json").example("$0 skills status --global", "User-level Neon skills").strict().hide("agent").hide("skill").hide("yes").check((args) => {
+	noPassthrough("skills status")(args);
+	const agents = args.agent;
+	const skills = args.skill;
+	if (Array.isArray(agents) && agents.length > 0 || Array.isArray(skills) && skills.length > 0) throw new Error("neon skills status does not take --agent or --skill. It checks every Neon skill in this directory (or --global).");
+	return true;
+}), (args) => statusHandler(args)).options({
 	yes: {
 		alias: "y",
 		type: "boolean",
@@ -249,7 +259,28 @@ const updateHandler = async (props) => {
 		title: "Skills"
 	});
 	out.end();
-	if (failure !== void 0) throw new Error(failure.includes("needs npx (Node.js)") || failure.includes("needs Node.js") ? failure : `${failure}\nRetry with: ${neonSkillsUpdateRetryCommand(scope === "global")}`);
+	if (failure !== void 0) throw new Error(failure.includes("needs npx (Node.js)") || failure.includes("needs Node.js") ? failure : `${failure}\nRetry with: ${neonSkillsUpdateCommand(scope)}`);
+};
+const statusHandler = async (props) => {
+	const scope = props.global === true ? "global" : "project";
+	const skills = readLockedSkills(lockPath(scope, process.cwd()), scope);
+	const folders = skills.length === 0 ? {} : await refreshSkillsCheckCache({
+		cachePath: skillsCheckCachePath(props.configDir),
+		skills
+	});
+	const rows = skillsStatusRows(skills, folders);
+	const out = writer(props);
+	out.write(rows, {
+		fields: [
+			"scope",
+			"skill",
+			"status"
+		],
+		title: "Skills",
+		emptyMessage: scope === "project" ? "No Neon skills in this directory's skills-lock.json. For user-level skills, run: neon skills status --global" : "No user-level Neon skills in the skills CLI lock."
+	});
+	out.end();
+	if (rows.some((row) => row.status === "outdated")) log.info("Update them: %s", neonSkillsUpdateCommand(scope));
 };
 //#endregion
 export { handler as a, skillsInstallError as c, describe as i, skills_exports as l, builder as n, installSkills as o, command as r, reportSkillsInstall as s, aliases as t };

package/dist/analytics.js

@@ -296,6 +296,8 @@ const trackEvent = (event, properties) => {
 	});
 	log.debug("Sent CLI event: %s", event);
 };
+/** Whether this process sends telemetry: analytics is on and the client was created. */
+const isAnalyticsActive = () => client !== void 0;
 /**
 * Tracks cli_command_success. The account fields come from the lookup, which may still be in
 * flight when the command finishes, so they are read when the event is sent.
@@ -354,4 +356,4 @@ const getAnalyticsEventProperties = (args) => ({
 	githubEnvVars: getGithubEnvVars(process.env)
 });
 //#endregion
-export { analyticsIdentity, analyticsMiddleware, closeAnalytics, commandSuccessProperties, getAnalyticsEventProperties, getErrorAnalyticsEventProperties, initAnalyticsClientMiddleware, recordCommandSuccessExtras, recordScaffoldedTemplate, sendError, storedCredentialAttribution, takeCommandSuccessExtras, telemetryCredential, trackCommandSuccess, trackEvent, useAnalyticsClientForTests };
+export { analyticsIdentity, analyticsMiddleware, closeAnalytics, commandSuccessProperties, getAnalyticsEventProperties, getErrorAnalyticsEventProperties, initAnalyticsClientMiddleware, isAnalyticsActive, recordCommandSuccessExtras, recordScaffoldedTemplate, sendError, storedCredentialAttribution, takeCommandSuccessExtras, telemetryCredential, trackCommandSuccess, trackEvent, useAnalyticsClientForTests };

package/dist/commands/index.js

@@ -8,7 +8,7 @@ import { u as projects_exports } from "../_chunks/projects-BwI2Uo0z.js";
 import { a as link_exports } from "../_chunks/link-BgtkOBws.js";
 import { o as mcp_exports } from "../_chunks/mcp-Bo-7TKc7.js";
 import { c as plugins_exports } from "../_chunks/plugins-DqD7BDO1.js";
-import { l as skills_exports } from "../_chunks/skills-DyiBXKS3.js";
+import { l as skills_exports } from "../_chunks/skills-BP6pIm7O.js";
 import { t as bootstrap_exports } from "../_chunks/bootstrap-wPZWa1sT.js";
 import { r as branches_exports } from "../_chunks/branches-BNa1xX1L.js";
 import { n as bucket_exports } from "../_chunks/bucket-BCdryTkD.js";

package/dist/commands/skills.js

@@ -1 +1 @@
-export { t as aliases, n as builder, r as command, i as describe, a as handler, o as installSkills, s as reportSkillsInstall, c as skillsInstallError } from "../_chunks/skills-DyiBXKS3.js";
+export { t as aliases, n as builder, r as command, i as describe, a as handler, o as installSkills, s as reportSkillsInstall, c as skillsInstallError } from "../_chunks/skills-BP6pIm7O.js";

package/dist/index.js

@@ -6,7 +6,7 @@ import { r as defaultDir } from "./_chunks/paths-DMq0Lt7a.js";
 import { ensureConfigDir } from "./config.js";
 import { currentContextFile, enrichFromContext } from "./context.js";
 import { NETWORK_ERROR_MESSAGE, isNetworkError, matchErrorCode } from "./errors.js";
-import { analyticsMiddleware, closeAnalytics, initAnalyticsClientMiddleware, sendError, takeCommandSuccessExtras, trackCommandSuccess } from "./analytics.js";
+import { analyticsMiddleware, closeAnalytics, initAnalyticsClientMiddleware, isAnalyticsActive, recordCommandSuccessExtras, sendError, takeCommandSuccessExtras, trackCommandSuccess } from "./analytics.js";
 import { AuthRefreshError, defaultClientID } from "./auth.js";
 import { getCliName } from "./utils/cli_name.js";
 import { c as ensureAuth } from "./_chunks/auth-CIUtXByB.js";
@@ -15,7 +15,7 @@ import { UsageError, failOnUsageError, isBareParentCommand, showHelp, showUsageE
 import { lazyCommands, preloadCommand } from "./commands/manifest.js";
 import { rewriteUnknownAgentArg } from "./init/plan.js";
 import { recoverFromSSO } from "./sso_recovery.js";
-import { notifyIfUpdateAvailable } from "./update_notifier.js";
+import { notifyIfUpdateAvailable, shouldRunSkillsNotifier } from "./update_notifier.js";
 import { fillInArgs, resolveApiKeyFromEnv } from "./utils/middlewares.js";
 import { collapseRepeatedFlags, declaredOptions } from "./utils/repeated_flags.js";
 import { stagingFeaturesEnabledForArgv } from "./utils/staging.js";
@@ -208,19 +208,38 @@ async function handleError(msg, err, canRetry) {
 	await preloadCommand(builder, hideBin(process.argv));
 	while (attempts < MAX_ATTEMPTS) try {
 		const args = await builder.argv;
+		const configDir = typeof args.configDir === "string" ? args.configDir : defaultDir;
+		if (isAnalyticsActive()) {
+			const { readSkillsTelemetry } = await import("./skills/freshness.js");
+			const skills = readSkillsTelemetry({
+				configDir,
+				cwd: process.cwd()
+			});
+			if (skills !== void 0) recordCommandSuccessExtras({ skills });
+		}
 		trackCommandSuccess(args);
 		if (args._.length === 0 || args.help) {
 			await showHelp(builder);
 			process.exit(0);
 		}
 		await closeAnalytics();
-		notifyIfUpdateAvailable({
+		const notifier = {
 			commandPath: args._.map(String),
-			configDir: typeof args.configDir === "string" ? args.configDir : defaultDir,
+			configDir,
 			currentBranch: Boolean(args.currentBranch),
-			currentVersion: pkg_default.version,
 			output: typeof args.output === "string" ? args.output : "table"
+		};
+		notifyIfUpdateAvailable({
+			...notifier,
+			currentVersion: pkg_default.version
 		});
+		if (shouldRunSkillsNotifier(notifier)) {
+			const { notifyIfSkillsOutdated } = await import("./skills/freshness.js");
+			notifyIfSkillsOutdated({
+				configDir: notifier.configDir,
+				cwd: process.cwd()
+			});
+		}
 		break;
 	} catch (err) {
 		takeCommandSuccessExtras();

package/dist/init/tooling.js

@@ -7,7 +7,7 @@ import { detectAgent } from "./detect_host.js";
 import { AgentSelectionSkipped, canPickAgentsInteractively } from "../utils/agent_picker.js";
 import { a as mcpInstallError, s as reportMcpInstall } from "../_chunks/mcp-Bo-7TKc7.js";
 import { l as reportPluginsInstall, o as installPlugins, s as pluginsInstallError } from "../_chunks/plugins-DqD7BDO1.js";
-import { c as skillsInstallError, o as installSkills, s as reportSkillsInstall } from "../_chunks/skills-DyiBXKS3.js";
+import { c as skillsInstallError, o as installSkills, s as reportSkillsInstall } from "../_chunks/skills-BP6pIm7O.js";
 import { runAuthenticatedMcp } from "./auth.js";
 import { raceSigint } from "./cancelled.js";
 import { pickAgentSetupInteractively } from "./wizard.js";

package/dist/skills/check_worker.js

@@ -0,0 +1,17 @@
+import { globalLockPath, projectLockPath, readLockedSkills, refreshSkillsCheckCache } from "./freshness.js";
+import { pathToFileURL } from "node:url";
+//#region src/skills/check_worker.ts
+const run = async () => {
+	const [cachePath, cwd] = process.argv.slice(2);
+	if (cachePath === void 0 || cwd === void 0) return;
+	try {
+		await refreshSkillsCheckCache({
+			cachePath,
+			skills: [...readLockedSkills(globalLockPath(), "global"), ...readLockedSkills(projectLockPath(cwd), "project")]
+		});
+	} catch {}
+};
+const entry = process.argv[1];
+if (entry !== void 0 && import.meta.url === pathToFileURL(entry).href) run();
+//#endregion
+export {};

package/dist/skills/freshness.js

@@ -0,0 +1,397 @@
+import { log } from "../log.js";
+import { writeJsonFile } from "../utils/json_file.js";
+import { showNotice } from "../notices.js";
+import { AGENT_SKILLS_SOURCE, PLATFORMS_SKILLS_SOURCE } from "./catalog.js";
+import { closeSync, constants, existsSync, fstatSync, openSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { spawn } from "node:child_process";
+//#region src/skills/freshness.ts
+const DAY_MS = 864e5;
+const CACHE_FILE = "skills-check.json";
+const FETCH_TIMEOUT_MS = 1e4;
+const NEON_SOURCES = /* @__PURE__ */ new Set([AGENT_SKILLS_SOURCE, PLATFORMS_SKILLS_SOURCE]);
+const scopeLabel = (scope) => scope === "project" ? "this directory" : "user-level";
+const neonSkillsUpdateCommand = (scope) => scope === "global" ? "neon skills update --global -y" : "neon skills update -y";
+/** Where the skills CLI keeps its user-level lock. */
+const globalLockPath = (env = process.env) => env.XDG_STATE_HOME ? join(env.XDG_STATE_HOME, "skills", ".skill-lock.json") : join(homedir(), ".agents", ".skill-lock.json");
+const projectLockPath = (cwd) => join(cwd, "skills-lock.json");
+const lockPath = (scope, cwd) => scope === "global" ? globalLockPath() : projectLockPath(cwd);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The Agent Skills name rule. A lock is repository content, and names reach the terminal. */
+const SKILL_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const skillFolder = (skillPath) => skillPath.replace(/\\/g, "/").replace(/\/?SKILL\.md$/i, "");
+/**
+* The global lock's `skillFolderHash` is usually a tree SHA, but the skills CLI stores a
+* content SHA-256 there when it installed from a Git clone; it tells them apart by length.
+*/
+const parseSkillsLock = (raw, scope) => {
+	const value = JSON.parse(raw);
+	if (!isRecord(value) || !isRecord(value.skills)) return [];
+	const field = scope === "global" ? "skillFolderHash" : "computedHash";
+	const skills = [];
+	for (const [skill, entry] of Object.entries(value.skills)) {
+		if (!isRecord(entry)) continue;
+		const { source, skillPath, ref } = entry;
+		const hash = entry[field];
+		if (!SKILL_NAME.test(skill) || typeof source !== "string" || !NEON_SOURCES.has(source) || typeof skillPath !== "string" || typeof hash !== "string" || hash === "") continue;
+		const folder = skillFolder(skillPath);
+		if (folder === "") continue;
+		const hashKind = scope === "global" && /^[0-9a-f]{40}$/i.test(hash) ? "tree" : "content";
+		skills.push({
+			scope,
+			skill,
+			source,
+			folder,
+			hash,
+			hashKind,
+			pinned: ref !== void 0
+		});
+	}
+	return skills;
+};
+const readAllLockedSkills = (path, scope) => {
+	if (!existsSync(path)) return [];
+	const raw = readLockFile(path);
+	try {
+		return parseSkillsLock(raw, scope);
+	} catch {
+		throw new Error(`${path} is not valid JSON.`);
+	}
+};
+/** The skills the update check covers: every Neon skill in the lock except pinned ones. */
+const readLockedSkills = (path, scope) => readAllLockedSkills(path, scope).filter((skill) => !skill.pinned);
+const MAX_LOCK_BYTES = 1048576;
+/**
+* A project lock is repository content: a FIFO would block the open and `/dev/zero` the read,
+* on every command run in that directory.
+*/
+const readLockFile = (path) => {
+	const fd = openSync(path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+	try {
+		const stat = fstatSync(fd);
+		if (!stat.isFile()) throw new Error(`${path} is not a regular file.`);
+		if (stat.size > MAX_LOCK_BYTES) throw new Error(`${path} is larger than ${MAX_LOCK_BYTES} bytes.`);
+		return readFileSync(fd, "utf8");
+	} finally {
+		closeSync(fd);
+	}
+};
+const folderKey = ({ source, folder }) => `${source}:${folder}`;
+/** `undefined` when the remote side has not been fetched yet. */
+const skillStatus = (skill, remote) => {
+	if (remote?.missing === true) return "not found upstream";
+	const latest = skill.hashKind === "tree" ? remote?.tree : remote?.content;
+	if (latest === void 0) return void 0;
+	return latest === skill.hash ? "up to date" : "outdated";
+};
+const parseRemoteFolder = (value) => {
+	if (!isRecord(value)) return void 0;
+	const { tree, content, missing, pending } = value;
+	if (tree !== void 0 && typeof tree !== "string" || content !== void 0 && typeof content !== "string" || missing !== void 0 && missing !== true || pending !== void 0 && pending !== true) return;
+	return {
+		...tree === void 0 ? {} : { tree },
+		...content === void 0 ? {} : { content },
+		...missing === void 0 ? {} : { missing },
+		...pending === void 0 ? {} : { pending }
+	};
+};
+const parseSkillsCheckCache = (raw) => {
+	try {
+		const value = JSON.parse(raw);
+		if (!isRecord(value) || typeof value.checkedAt !== "number" || !Number.isFinite(value.checkedAt) || !isRecord(value.folders)) return;
+		const folders = {};
+		for (const [key, entry] of Object.entries(value.folders)) {
+			const folder = parseRemoteFolder(entry);
+			if (folder !== void 0) folders[key] = folder;
+		}
+		const { attemptedAt } = value;
+		return {
+			checkedAt: value.checkedAt,
+			...typeof attemptedAt === "number" && Number.isFinite(attemptedAt) ? { attemptedAt } : {},
+			folders
+		};
+	} catch {
+		return;
+	}
+};
+const readSkillsCheckCache = (cachePath) => {
+	try {
+		return parseSkillsCheckCache(readFileSync(cachePath, "utf8"));
+	} catch {
+		return;
+	}
+};
+const skillsCheckCachePath = (configDir) => join(configDir, CACHE_FILE);
+/**
+* The digest the skills CLI writes to `computedHash`: every file's folder-relative path and
+* then its bytes, in `localeCompare` order of path.
+*/
+const skillContentHash = (files) => {
+	const hash = createHash("sha256");
+	for (const file of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
+		hash.update(file.path);
+		hash.update(file.bytes);
+	}
+	return hash.digest("hex");
+};
+const gitBlobSha = (bytes) => createHash("sha1").update(`blob ${bytes.byteLength}\0`).update(bytes).digest("hex");
+const isTreeEntry = (value) => isRecord(value) && typeof value.path === "string" && typeof value.mode === "string" && typeof value.type === "string" && typeof value.sha === "string";
+const githubHeaders = (env) => {
+	const token = env.GITHUB_TOKEN || env.GH_TOKEN;
+	return {
+		Accept: "application/vnd.github+json",
+		"User-Agent": "neon-cli",
+		...token ? { Authorization: `Bearer ${token}` } : {}
+	};
+};
+const fetchTree = async (source, env) => {
+	const response = await fetch(`https://api.github.com/repos/${source}/git/trees/HEAD?recursive=1`, {
+		headers: githubHeaders(env),
+		signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+	});
+	if (!response.ok) {
+		if ((response.status === 403 || response.status === 429) && response.headers.get("x-ratelimit-remaining") === "0") throw new Error(`GitHub API rate limit reached while checking ${source}. Set GITHUB_TOKEN and retry.`);
+		throw new Error(`GitHub returned ${response.status} for the file tree of ${source}.`);
+	}
+	const body = await response.json();
+	if (!isRecord(body) || !Array.isArray(body.tree)) throw new Error(`GitHub returned an unexpected file tree for ${source}.`);
+	if (body.truncated === true) throw new Error(`GitHub truncated the file tree of ${source}.`);
+	return body.tree.filter(isTreeEntry);
+};
+/** The files the skills CLI hashes: regular files, outside `.git` and `node_modules`. */
+const folderFiles = (tree, folder) => tree.filter((entry) => {
+	if (entry.type !== "blob" || entry.mode === "120000") return false;
+	if (!entry.path.startsWith(`${folder}/`)) return false;
+	const dirs = entry.path.slice(folder.length + 1).split("/").slice(0, -1);
+	return !dirs.includes(".git") && !dirs.includes("node_modules");
+});
+const fetchContentHash = async (source, folder, tree) => {
+	const files = await Promise.all(folderFiles(tree, folder).map(async (entry) => {
+		const path = entry.path.split("/").map(encodeURIComponent).join("/");
+		const response = await fetch(`https://raw.githubusercontent.com/${source}/HEAD/${path}`, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+		if (!response.ok) throw new Error(`GitHub returned ${response.status} for ${entry.path} in ${source}.`);
+		const bytes = new Uint8Array(await response.arrayBuffer());
+		if (gitBlobSha(bytes) !== entry.sha) throw new Error(`${source} changed during the check. Retry.`);
+		return {
+			path: entry.path.slice(folder.length + 1),
+			bytes
+		};
+	}));
+	return skillContentHash(files);
+};
+/**
+* The folders to fetch: the given skills, plus every folder already in the cache so
+* results for other directories stay current.
+*/
+const folderRequests = (skills, previous) => {
+	const requests = /* @__PURE__ */ new Map();
+	const add = (request) => {
+		const key = folderKey(request);
+		const existing = requests.get(key);
+		requests.set(key, {
+			...request,
+			content: request.content || existing?.content === true
+		});
+	};
+	for (const [key, remote] of Object.entries(previous)) {
+		const split = key.lastIndexOf(":");
+		const source = key.slice(0, split);
+		if (split <= 0 || !NEON_SOURCES.has(source)) continue;
+		add({
+			source,
+			folder: key.slice(split + 1),
+			content: remote.content !== void 0
+		});
+	}
+	for (const skill of skills) add({
+		source: skill.source,
+		folder: skill.folder,
+		content: skill.hashKind === "content"
+	});
+	return [...requests.values()];
+};
+/**
+* Fetches the default-branch state of every requested skill folder and writes it to the
+* cache. File contents are downloaded only for folders whose tree changed since the cache.
+*/
+const refreshSkillsCheckCache = async ({ cachePath, skills, env = process.env, now = Date.now() }) => {
+	const previous = readSkillsCheckCache(cachePath)?.folders ?? {};
+	const requests = folderRequests(skills, previous);
+	const folders = {};
+	for (const source of new Set(requests.map((request) => request.source))) {
+		const tree = await fetchTree(source, env);
+		for (const request of requests) {
+			if (request.source !== source) continue;
+			const key = folderKey(request);
+			const node = tree.find((entry) => entry.type === "tree" && entry.path === request.folder);
+			if (node === void 0) {
+				folders[key] = { missing: true };
+				continue;
+			}
+			const prior = previous[key];
+			let content = prior?.tree === node.sha ? prior.content : void 0;
+			if (request.content && content === void 0) content = await fetchContentHash(source, request.folder, tree);
+			folders[key] = {
+				tree: node.sha,
+				...content === void 0 ? {} : { content }
+			};
+		}
+	}
+	writeJsonFile(cachePath, {
+		checkedAt: now,
+		folders
+	}, "skills check cache");
+	return folders;
+};
+const skillsStatusRows = (skills, folders) => skills.map((skill) => {
+	const status = skillStatus(skill, folders[folderKey(skill)]);
+	if (status === void 0) throw new Error(`No result for ${skill.skill} from ${skill.source}. Retry the check.`);
+	return {
+		scope: scopeLabel(skill.scope),
+		skill: skill.skill,
+		status
+	};
+});
+const formatSkillsNotice = (outdated) => {
+	if (outdated.length === 0) return void 0;
+	const scopes = ["global", "project"].filter((scope) => outdated.some((skill) => skill.scope === scope));
+	return [
+		"Neon agent skills have updates:",
+		...scopes.map((scope) => `  ${scopeLabel(scope)}: ${outdated.filter((skill) => skill.scope === scope).map((skill) => skill.skill).join(", ")}`),
+		"Update them:",
+		...scopes.map((scope) => `  ${neonSkillsUpdateCommand(scope)}`)
+	].join("\n");
+};
+/**
+* `pending` folders are left alone until the next daily check. A lock written after the last
+* check (an install or an update) holds back the warning and checks every skill again,
+* because the cache can be older than what was just installed.
+*/
+const planSkillsCheck = ({ skills, cache, lockModifiedAt, now }) => {
+	const remote = (skill) => cache?.folders[folderKey(skill)];
+	const settled = (skill) => remote(skill)?.pending !== true;
+	const lockChanged = cache !== void 0 && lockModifiedAt > cache.checkedAt;
+	const outdated = lockChanged ? [] : skills.filter((skill) => settled(skill) && skillStatus(skill, remote(skill)) === "outdated");
+	const toCheck = skills.filter((skill) => settled(skill) && (lockChanged || skillStatus(skill, remote(skill)) === void 0));
+	return {
+		outdated,
+		toCheck,
+		refresh: cache === void 0 || toCheck.length > 0 || now - (cache.attemptedAt ?? cache.checkedAt) >= DAY_MS
+	};
+};
+const spawnSkillsCheckWorker = (cachePath, cwd) => {
+	const workerPath = fileURLToPath(new URL("./check_worker.js", import.meta.url));
+	if (!existsSync(workerPath)) return;
+	try {
+		const child = spawn(process.execPath, [
+			workerPath,
+			cachePath,
+			cwd
+		], {
+			detached: true,
+			stdio: "ignore",
+			windowsHide: true
+		});
+		child.on("error", (error) => {
+			log.debug("Skills check failed to start: %s", error.message);
+		});
+		child.unref();
+	} catch (error) {
+		log.debug("Could not start the skills check: %s", error instanceof Error ? error.message : String(error));
+	}
+};
+/** Every Neon skill in the lock, pinned ones included. */
+const readLock = (path, scope) => ({
+	skills: readAllLockedSkills(path, scope),
+	modifiedAt: statSync(path, { throwIfNoEntry: false })?.mtimeMs ?? 0
+});
+const readLocks = (cwd) => ({
+	global: readLock(globalLockPath(), "global"),
+	project: readLock(projectLockPath(cwd), "project")
+});
+/**
+* `outdated` is `null` when the cache cannot answer: no successful check yet, a check still
+* pending for the folder, a lock written after the last check, a folder gone upstream, or a
+* pinned skill.
+*/
+const skillsTelemetry = (locks, cache) => {
+	const scope = ({ skills, modifiedAt }) => {
+		if (skills.length === 0) return { installed: false };
+		const known = cache !== void 0 && cache.checkedAt > 0 && modifiedAt <= cache.checkedAt;
+		return {
+			installed: true,
+			skills: Object.fromEntries(skills.map((skill) => {
+				const remote = cache?.folders[folderKey(skill)];
+				const status = known && !skill.pinned && remote?.pending !== true ? skillStatus(skill, remote) : void 0;
+				return [skill.skill, {
+					hash: skill.hash,
+					outdated: status === "outdated" ? true : status === "up to date" ? false : null
+				}];
+			}))
+		};
+	};
+	return {
+		checkedAt: cache !== void 0 && cache.checkedAt > 0 ? cache.checkedAt : null,
+		global: scope(locks.global),
+		project: scope(locks.project)
+	};
+};
+/**
+* Reads only local files. `undefined` when a lock can't be read, which leaves the property
+* off the event rather than reporting skills as not installed.
+*/
+const readSkillsTelemetry = ({ configDir, cwd }) => {
+	try {
+		return skillsTelemetry(readLocks(cwd), readSkillsCheckCache(skillsCheckCachePath(configDir)));
+	} catch (error) {
+		log.debug("Leaving skills out of telemetry: %s", error instanceof Error ? error.message : String(error));
+		return;
+	}
+};
+/**
+* Warns at most once a day when a Neon skill in the user-level lock or this directory's
+* `skills-lock.json` is behind its source, from a cache a background worker refreshes daily.
+*/
+const notifyIfSkillsOutdated = ({ configDir, cwd, now = Date.now() }) => {
+	let locks;
+	try {
+		locks = readLocks(cwd);
+	} catch (error) {
+		log.debug("Skipping the skills check: %s", error instanceof Error ? error.message : String(error));
+		return;
+	}
+	const skills = [...locks.global.skills, ...locks.project.skills].filter((skill) => !skill.pinned);
+	if (skills.length === 0) return;
+	const cachePath = skillsCheckCachePath(configDir);
+	const cache = readSkillsCheckCache(cachePath);
+	const plan = planSkillsCheck({
+		skills,
+		cache,
+		lockModifiedAt: Math.max(locks.global.modifiedAt, locks.project.modifiedAt),
+		now
+	});
+	const notice = formatSkillsNotice(plan.outdated);
+	if (notice !== void 0) showNotice({
+		configDir,
+		id: "skills",
+		intervalMs: DAY_MS,
+		message: notice,
+		now
+	});
+	if (!plan.refresh) return;
+	const folders = { ...cache?.folders };
+	for (const skill of plan.toCheck) folders[folderKey(skill)] = {
+		...folders[folderKey(skill)],
+		pending: true
+	};
+	if (writeJsonFile(cachePath, {
+		checkedAt: cache?.checkedAt ?? 0,
+		attemptedAt: now,
+		folders
+	}, "skills check cache")) spawnSkillsCheckWorker(cachePath, cwd);
+};
+//#endregion
+export { formatSkillsNotice, globalLockPath, lockPath, neonSkillsUpdateCommand, notifyIfSkillsOutdated, parseSkillsCheckCache, parseSkillsLock, planSkillsCheck, projectLockPath, readLockedSkills, readSkillsTelemetry, refreshSkillsCheckCache, scopeLabel, skillContentHash, skillStatus, skillsCheckCachePath, skillsStatusRows, skillsTelemetry };

package/dist/skills/run.js

@@ -59,7 +59,6 @@ const neonSkillsRetryCommand = (options) => {
 	args.push("-y");
 	return `neon ${args.map(quoteNpxArg).join(" ")}`;
 };
-const neonSkillsUpdateRetryCommand = (global) => global ? "neon skills update --global -y" : "neon skills update -y";
 const quoteNpxArg = (part) => /[\s"'\\*]/.test(part) ? `'${part.replace(/'/g, `'\\''`)}'` : part;
 const npxCommand = (args) => `npx ${args.map(quoteNpxArg).join(" ")}`;
 const ANSI = /\u001b\[[0-9;]*[A-Za-z]/g;
@@ -116,4 +115,4 @@ const runSkillsCli = async (options) => {
 const isCommandMissing = (error) => typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 const isExecaFailure = (error) => typeof error === "object" && error !== null && "shortMessage" in error && typeof error.shortMessage === "string";
 //#endregion
-export { SKILLS_MIN_NODE, assertSkillsNode, neonSkillsRetryCommand, neonSkillsUpdateRetryCommand, nodeMeetsMinimum, npxCommand, quoteNpxArg, runSkillsCli, skillsAddArgs, skillsChildEnv, skillsMetadata, skillsUpdateArgs, skillsUpdateDetail, skillsUpdateHadNothing };
+export { SKILLS_MIN_NODE, assertSkillsNode, neonSkillsRetryCommand, nodeMeetsMinimum, npxCommand, quoteNpxArg, runSkillsCli, skillsAddArgs, skillsChildEnv, skillsMetadata, skillsUpdateArgs, skillsUpdateDetail, skillsUpdateHadNothing };

package/dist/test_utils/fixtures.js

@@ -91,6 +91,7 @@ const test = test$1.extend({
 				...options.cwd ? { cwd: options.cwd } : {},
 				env: {
 					PATH: `${join(process.cwd(), "mocks/bin")}:${process.env.PATH}`,
+					NO_UPDATE_NOTIFIER: "1",
 					...options.env ?? {}
 				}
 			});

package/dist/update_notifier.js

@@ -145,6 +145,20 @@ const shouldRunUpdateNotifier = ({ commandPath, currentBranch, disabled, isCi: r
 	commandPath,
 	currentBranch
 });
+/**
+* The skills notice drops the terminal checks: coding agents run the CLI without a TTY,
+* and they are the ones that act on it. `neon skills` itself reports skill state.
+*/
+const shouldRunSkillsNotifier = ({ commandPath, currentBranch, output }) => commandPath[0] !== "skills" && commandPath[0] !== "skill" && shouldRunUpdateNotifier({
+	commandPath,
+	currentBranch,
+	disabled: "NO_UPDATE_NOTIFIER" in process.env,
+	isCi: isCi(),
+	isPackaged: isPackagedExecutable(),
+	output,
+	stderrIsTty: true,
+	stdoutIsTty: true
+});
 const notifyIfUpdateAvailable = ({ commandPath, configDir, currentBranch, currentVersion, output }) => {
 	if (!shouldRunUpdateNotifier({
 		commandPath,
@@ -204,4 +218,4 @@ const recordLatestVersion = (cachePath, source, latestVersion) => {
 	});
 };
 //#endregion
-export { cacheForUpdateSource, findCliInstalls, formatDuplicateInstallNotice, formatUpdateNotice, notifyIfUpdateAvailable, parseUpdateCheckCache, recordLatestVersion, shouldRefreshUpdateCheck, shouldRunUpdateNotifier, spawnUpdateWorkerProcess, writeUpdateCheckCache };
+export { cacheForUpdateSource, findCliInstalls, formatDuplicateInstallNotice, formatUpdateNotice, notifyIfUpdateAvailable, parseUpdateCheckCache, recordLatestVersion, shouldRefreshUpdateCheck, shouldRunSkillsNotifier, shouldRunUpdateNotifier, spawnUpdateWorkerProcess, writeUpdateCheckCache };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "8.11.4",
+  "version": "8.12.1",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -72,10 +72,10 @@
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
     "yoctocolors": "^2.1.2",
-    "@neon/config-runtime": "1.10.3",
     "@neon/config": "1.9.4",
-    "@neon/sdk": "7.5.0",
-    "@neon/realtime": "0.1.2"
+    "@neon/config-runtime": "1.10.3",
+    "@neon/realtime": "0.1.2",
+    "@neon/sdk": "7.5.0"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0",
@@ -111,11 +111,11 @@
     "tsx": "4.22.3",
     "typescript": "^5.9.0",
     "vitest": "^3.0.9",
+    "@neon-internals/cli-core": "0.0.0",
     "@neon-internals/env-core": "0.0.35",
-    "@neon/functions": "0.11.0",
-    "@neon/env": "1.6.5",
     "@neon/e2e-harness": "0.0.0",
-    "@neon-internals/cli-core": "0.0.0"
+    "@neon/env": "1.6.5",
+    "@neon/functions": "0.11.0"
   },
   "publishConfig": {
     "access": "public",