@farming-labs/docs 0.2.88 → 0.2.89

package/dist/{agent-FyPQ2AZ4.mjs → agent-Jvn1a78y.mjs}

@@ -2,7 +2,7 @@ import { B as findDocsMarkdownPage, at as renderDocsMarkdownDocument } from "./a
 import { v as normalizePageAgentFrontmatter, x as stripGeneratedPageAgentContractMarkdown } from "./markdown-sections-7OoA7ylx.mjs";
 import { c as hashGeneratedAgentContent, d as serializeGeneratedAgentDocument, s as GENERATED_AGENT_PROVENANCE_VERSION, u as parseGeneratedAgentDocument } from "./content-change-hydration-DLBinuFR.mjs";
 import { createFilesystemDocsMcpSource } from "./mcp.mjs";
-import { _ as resolveDocsContentDir, a as loadDocsConfigModule, c as loadProjectEnv, d as readNavTitle, f as readNumberProperty, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral, u as readEnvReferenceProperty } from "./config-Wcdj-D0a.mjs";
+import { _ as resolveDocsContentDir, a as loadDocsConfigModule, c as loadProjectEnv, d as readNavTitle, f as readNumberProperty, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral, u as readEnvReferenceProperty } from "./config-BtxaQTPP.mjs";
 import { createRequire } from "node:module";
 import matter from "gray-matter";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";

package/dist/{agent-export-Di1Ofstb.mjs → agent-export-B4Xos6gi.mjs}

@@ -10,7 +10,7 @@ import "./agent-evals-DCptRrdP.mjs";
 import { createFilesystemDocsMcpSource, resolveDocsMcpConfig } from "./mcp.mjs";
 import "./code-blocks-0wjOsqdJ.mjs";
 import "./server.mjs";
-import { _ as resolveDocsContentDir, a as loadDocsConfigModule, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, m as readTopLevelBooleanProperty, p as readStringProperty, r as extractTopLevelConfigObject, t as extractNestedObjectLiteral } from "./config-Wcdj-D0a.mjs";
+import { _ as resolveDocsContentDir, a as loadDocsConfigModule, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, m as readTopLevelBooleanProperty, p as readStringProperty, r as extractTopLevelConfigObject, t as extractNestedObjectLiteral } from "./config-BtxaQTPP.mjs";
 import { t as detectFramework } from "./utils-DpiIioYb.mjs";
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";

package/dist/{agents-DjUz5voa.mjs → agents-DRCl1URL.mjs}

@@ -8,7 +8,7 @@ import "./agent-evals-DCptRrdP.mjs";
 import { resolveDocsMcpConfig } from "./mcp.mjs";
 import "./code-blocks-0wjOsqdJ.mjs";
 import "./server.mjs";
-import { a as loadDocsConfigModule, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-Wcdj-D0a.mjs";
+import { a as loadDocsConfigModule, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-BtxaQTPP.mjs";
 import { t as detectFramework } from "./utils-DpiIioYb.mjs";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";

package/dist/cli/index.mjs

@@ -108,43 +108,43 @@ async function main() {
 		]
 	};
 	if (!parsedCommand.command || parsedCommand.command === "init") {
-		const { init } = await import("../init-c3WAqoI2.mjs");
+		const { init } = await import("../init-CuLodGjP.mjs");
 		await init(initOptions);
 	} else if (parsedCommand.command === "dev") {
 		const { dev } = await import("../dev-BFBPvjnk.mjs");
 		await dev(devOptions);
 	} else if (parsedCommand.command === "deploy") {
-		const { runCloudDeploy } = await import("../cloud-pdNC-tyj.mjs");
+		const { runCloudDeploy } = await import("../cloud-DwhH_b_q.mjs");
 		await runCloudDeploy(cloudOptions);
 	} else if (parsedCommand.command === "preview") {
-		const { runCloudPreview } = await import("../cloud-pdNC-tyj.mjs");
+		const { runCloudPreview } = await import("../cloud-DwhH_b_q.mjs");
 		await runCloudPreview(cloudOptions);
 	} else if (parsedCommand.command === "cloud" && subcommand === "deploy") {
-		const { runCloudDeploy } = await import("../cloud-pdNC-tyj.mjs");
+		const { runCloudDeploy } = await import("../cloud-DwhH_b_q.mjs");
 		await runCloudDeploy(cloudOptions);
 	} else if (parsedCommand.command === "cloud" && subcommand === "preview") {
-		const { runCloudPreview } = await import("../cloud-pdNC-tyj.mjs");
+		const { runCloudPreview } = await import("../cloud-DwhH_b_q.mjs");
 		await runCloudPreview(cloudOptions);
 	} else if (parsedCommand.command === "cloud" && subcommand === "init") {
-		const { runCloudInit } = await import("../cloud-pdNC-tyj.mjs");
+		const { runCloudInit } = await import("../cloud-DwhH_b_q.mjs");
 		await runCloudInit(cloudOptions);
 	} else if (parsedCommand.command === "cloud" && subcommand === "sync") {
-		const { syncCloudConfig } = await import("../cloud-pdNC-tyj.mjs");
+		const { syncCloudConfig } = await import("../cloud-DwhH_b_q.mjs");
 		await syncCloudConfig(cloudOptions);
 	} else if (parsedCommand.command === "cloud" && subcommand === "check") {
-		const { runCloudCheck } = await import("../cloud-pdNC-tyj.mjs");
+		const { runCloudCheck } = await import("../cloud-DwhH_b_q.mjs");
 		await runCloudCheck(cloudOptions);
 	} else if (parsedCommand.command === "cloud") {
 		console.error(pc.red(`Unknown cloud subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printCloudHelp } = await import("../cloud-pdNC-tyj.mjs");
+		const { printCloudHelp } = await import("../cloud-DwhH_b_q.mjs");
 		printCloudHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "mcp") {
-		const { runMcp } = await import("../mcp-7bvRe9Da.mjs");
+		const { runMcp } = await import("../mcp-D8Hw2blN.mjs");
 		await runMcp(mcpOptions);
 	} else if (parsedCommand.command === "agent" && subcommand === "compact") {
-		const { compactAgentDocs, parseAgentCompactArgs, printAgentCompactHelp } = await import("../agent-FyPQ2AZ4.mjs").then((n) => n.t);
+		const { compactAgentDocs, parseAgentCompactArgs, printAgentCompactHelp } = await import("../agent-Jvn1a78y.mjs").then((n) => n.t);
 		const agentCompactOptions = parseAgentCompactArgs(args.slice(2));
 		if (agentCompactOptions.help) {
 			printAgentCompactHelp();
@@ -152,7 +152,7 @@ async function main() {
 		}
 		await compactAgentDocs(agentCompactOptions);
 	} else if (parsedCommand.command === "agent" && subcommand === "export") {
-		const { exportAgentBundle, parseAgentExportArgs, printAgentExportHelp } = await import("../agent-export-Di1Ofstb.mjs");
+		const { exportAgentBundle, parseAgentExportArgs, printAgentExportHelp } = await import("../agent-export-B4Xos6gi.mjs");
 		const agentExportOptions = parseAgentExportArgs(args.slice(2));
 		if (agentExportOptions.help) {
 			printAgentExportHelp();
@@ -162,13 +162,13 @@ async function main() {
 	} else if (parsedCommand.command === "agent") {
 		console.error(pc.red(`Unknown agent subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printAgentCompactHelp } = await import("../agent-FyPQ2AZ4.mjs").then((n) => n.t);
-		const { printAgentExportHelp } = await import("../agent-export-Di1Ofstb.mjs");
+		const { printAgentCompactHelp } = await import("../agent-Jvn1a78y.mjs").then((n) => n.t);
+		const { printAgentExportHelp } = await import("../agent-export-B4Xos6gi.mjs");
 		printAgentCompactHelp();
 		printAgentExportHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "agents" && subcommand === "generate") {
-		const { generateAgents, parseAgentsGenerateArgs, printAgentsGenerateHelp } = await import("../agents-DjUz5voa.mjs");
+		const { generateAgents, parseAgentsGenerateArgs, printAgentsGenerateHelp } = await import("../agents-DRCl1URL.mjs");
 		const agentsOptions = parseAgentsGenerateArgs(args.slice(2));
 		if (agentsOptions.help) {
 			printAgentsGenerateHelp();
@@ -178,11 +178,11 @@ async function main() {
 	} else if (parsedCommand.command === "agents") {
 		console.error(pc.red(`Unknown agents subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printAgentsGenerateHelp } = await import("../agents-DjUz5voa.mjs");
+		const { printAgentsGenerateHelp } = await import("../agents-DRCl1URL.mjs");
 		printAgentsGenerateHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "skills" && subcommand === "scaffold") {
-		const { parseSkillScaffoldArgs, printSkillScaffoldHelp, scaffoldSkillFromContracts } = await import("../skills-CPDwsMq4.mjs");
+		const { parseSkillScaffoldArgs, printSkillScaffoldHelp, scaffoldSkillFromContracts } = await import("../skills-35ecRZtd.mjs");
 		const skillOptions = parseSkillScaffoldArgs(args.slice(2));
 		if (skillOptions.help) {
 			printSkillScaffoldHelp();
@@ -190,16 +190,16 @@ async function main() {
 		}
 		await scaffoldSkillFromContracts(skillOptions);
 	} else if (parsedCommand.command === "skills" && (subcommand === "--help" || subcommand === "-h")) {
-		const { printSkillScaffoldHelp } = await import("../skills-CPDwsMq4.mjs");
+		const { printSkillScaffoldHelp } = await import("../skills-35ecRZtd.mjs");
 		printSkillScaffoldHelp();
 	} else if (parsedCommand.command === "skills") {
 		console.error(pc.red(`Unknown skills subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printSkillScaffoldHelp } = await import("../skills-CPDwsMq4.mjs");
+		const { printSkillScaffoldHelp } = await import("../skills-35ecRZtd.mjs");
 		printSkillScaffoldHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "doctor") {
-		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-DUnOjP9T.mjs");
+		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-C3IG5hqb.mjs");
 		const doctorOptions = parseDoctorArgs(args.slice(1));
 		if (doctorOptions.help) {
 			printDoctorHelp();
@@ -207,7 +207,7 @@ async function main() {
 		}
 		await runDoctor(doctorOptions);
 	} else if (parsedCommand.command === "review") {
-		const { parseReviewArgs, printReviewHelp, runReview } = await import("../review-DEnzotkg.mjs");
+		const { parseReviewArgs, printReviewHelp, runReview } = await import("../review-R39cQsvi.mjs");
 		const reviewOptions = parseReviewArgs(args.slice(1));
 		if (reviewOptions.help) {
 			printReviewHelp();
@@ -215,7 +215,7 @@ async function main() {
 		}
 		await runReview(reviewOptions);
 	} else if ((parsedCommand.command === "codeblocks" || parsedCommand.command === "code-blocks") && subcommand === "validate") {
-		const { parseCodeBlocksValidateArgs, printCodeBlocksValidateHelp, runCodeBlocksValidate } = await import("../codeblocks-CPA6Ae5r.mjs");
+		const { parseCodeBlocksValidateArgs, printCodeBlocksValidateHelp, runCodeBlocksValidate } = await import("../codeblocks-B5lsz3sx.mjs");
 		const codeBlocksOptions = parseCodeBlocksValidateArgs(args.slice(2));
 		if (codeBlocksOptions.help) {
 			printCodeBlocksValidateHelp();
@@ -225,11 +225,11 @@ async function main() {
 	} else if (parsedCommand.command === "codeblocks" || parsedCommand.command === "code-blocks") {
 		console.error(pc.red(`Unknown codeblocks subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printCodeBlocksValidateHelp } = await import("../codeblocks-CPA6Ae5r.mjs");
+		const { printCodeBlocksValidateHelp } = await import("../codeblocks-B5lsz3sx.mjs");
 		printCodeBlocksValidateHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "search" && subcommand === "sync") {
-		const { syncSearch } = await import("../search-DznddPqw.mjs");
+		const { syncSearch } = await import("../search-3TUBKtz5.mjs");
 		await syncSearch(searchSyncOptions);
 	} else if (parsedCommand.command === "search") {
 		console.error(pc.red(`Unknown search subcommand: ${subcommand ?? "(missing)"}`));
@@ -237,7 +237,7 @@ async function main() {
 		printHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "sitemap" && subcommand === "generate") {
-		const { generateSitemap, parseSitemapGenerateArgs, printSitemapGenerateHelp } = await import("../sitemap-DCsrVSPf.mjs");
+		const { generateSitemap, parseSitemapGenerateArgs, printSitemapGenerateHelp } = await import("../sitemap-DrILEtYo.mjs");
 		const sitemapOptions = parseSitemapGenerateArgs(args.slice(2));
 		if (sitemapOptions.help) {
 			printSitemapGenerateHelp();
@@ -247,11 +247,11 @@ async function main() {
 	} else if (parsedCommand.command === "sitemap") {
 		console.error(pc.red(`Unknown sitemap subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printSitemapGenerateHelp } = await import("../sitemap-DCsrVSPf.mjs");
+		const { printSitemapGenerateHelp } = await import("../sitemap-DrILEtYo.mjs");
 		printSitemapGenerateHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "robots" && subcommand === "generate") {
-		const { generateRobots, parseRobotsGenerateArgs, printRobotsGenerateHelp } = await import("../robots-DXy1xW3D.mjs");
+		const { generateRobots, parseRobotsGenerateArgs, printRobotsGenerateHelp } = await import("../robots-C-Nh0xH6.mjs");
 		const robotsOptions = parseRobotsGenerateArgs(args.slice(2));
 		if (robotsOptions.help) {
 			printRobotsGenerateHelp();
@@ -261,7 +261,7 @@ async function main() {
 	} else if (parsedCommand.command === "robots") {
 		console.error(pc.red(`Unknown robots subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printRobotsGenerateHelp } = await import("../robots-DXy1xW3D.mjs");
+		const { printRobotsGenerateHelp } = await import("../robots-C-Nh0xH6.mjs");
 		printRobotsGenerateHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "downgrade") {
@@ -398,6 +398,8 @@ ${pc.dim("Options for doctor:")}
   ${pc.cyan("doctor --site")}                       Score the current docs app for reader-facing docs quality
   ${pc.cyan("doctor --human")}                      Alias for ${pc.cyan("doctor --site")}
   ${pc.cyan("doctor --json")}                       Print the report as JSON for CI, scripts, and automation
+  ${pc.cyan("doctor --json-output <path>")}         Write the JSON report to a file, including alongside ${pc.cyan("--ci")}
+  ${pc.cyan("doctor --ci")}                         Emit actionable GitHub annotations in GitHub Actions
   ${pc.cyan("doctor --strict")}                     Exit with failure when any doctor check warns or fails
   ${pc.cyan("doctor --agent --fix")}                Refresh stale generated ${pc.dim("agent.md")} files and token-budget missing outputs
   ${pc.cyan("doctor --agent --fix --dry-run")}      Report the fix command without writing generated ${pc.dim("agent.md")} files

package/dist/{cloud-pdNC-tyj.mjs → cloud-DwhH_b_q.mjs}

@@ -1,5 +1,5 @@
 import { n as markCliErrorReported } from "./errors-DbOhkE1h.mjs";
-import { _ as resolveDocsContentDir, a as loadDocsConfigModule, c as loadProjectEnv, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, m as readTopLevelBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-Wcdj-D0a.mjs";
+import { _ as resolveDocsContentDir, a as loadDocsConfigModule, c as loadProjectEnv, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, m as readTopLevelBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-BtxaQTPP.mjs";
 import { i as detectPackageManagerFromProject, t as detectFramework } from "./utils-DpiIioYb.mjs";
 import fs from "node:fs";
 import path from "node:path";

package/dist/{codeblocks-CPA6Ae5r.mjs → codeblocks-B5lsz3sx.mjs}

@@ -1,5 +1,5 @@
 import { a as validateCodeBlocks, r as resolveDocsCodeBlocksValidateConfig } from "./code-blocks-0wjOsqdJ.mjs";
-import { _ as resolveDocsContentDir, a as loadDocsConfigModule, f as readNumberProperty, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-Wcdj-D0a.mjs";
+import { _ as resolveDocsContentDir, a as loadDocsConfigModule, f as readNumberProperty, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-BtxaQTPP.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import pc from "picocolors";
 

package/dist/{config-Wcdj-D0a.mjs → config-BtxaQTPP.mjs}

@@ -82,6 +82,31 @@ function resolveDocsConfigPath(rootDir, explicitPath) {
 	}
 	throw new Error("Could not find docs.config.ts or docs.config.tsx in the current project. Use --config to point at a custom path.");
 }
+/**
+* Resolve the application root that owns a docs config selected from another
+* working directory. This keeps config-relative paths anchored to a nested
+* workspace package without changing the behavior of configs stored below a
+* project's root (for example, src/lib/docs.config.ts).
+*/
+function resolveDocsProjectRoot(rootDir, configPath) {
+	const invocationRoot = resolve(rootDir);
+	const configDir = dirname(resolve(configPath));
+	const relativeConfigDir = relative(invocationRoot, configDir);
+	const configIsInsideInvocationRoot = relativeConfigDir === "" || relativeConfigDir !== ".." && !relativeConfigDir.startsWith(`..${sep}`);
+	const fallbackRoot = configIsInsideInvocationRoot ? invocationRoot : configDir;
+	let currentDir = configDir;
+	while (true) {
+		if (existsSync(join(currentDir, "package.json"))) return currentDir;
+		if (configIsInsideInvocationRoot && currentDir === invocationRoot) return invocationRoot;
+		const parentDir = dirname(currentDir);
+		if (parentDir === currentDir) return fallbackRoot;
+		if (configIsInsideInvocationRoot) {
+			const relativeParent = relative(invocationRoot, parentDir);
+			if (relativeParent === ".." || relativeParent.startsWith(`..${sep}`)) return invocationRoot;
+		}
+		currentDir = parentDir;
+	}
+}
 function readStringProperty(content, key) {
 	return content.match(createPropertyPattern(key, `["']([^"']+)["']`))?.[1];
 }
@@ -366,4 +391,4 @@ async function loadDocsConfigModuleResultWithProjectEnv(rootDir, explicitPath, o
 }
 
 //#endregion
-export { resolveDocsContentDir as _, loadDocsConfigModule as a, loadProjectEnv as c, readNavTitle as d, readNumberProperty as f, resolveDocsConfigPath as g, readTopLevelStringProperty as h, hasTopLevelProperty as i, readBooleanProperty as l, readTopLevelBooleanProperty as m, extractObjectLiteral as n, loadDocsConfigModuleResult as o, readStringProperty as p, extractTopLevelConfigObject as r, loadDocsConfigModuleResultWithProjectEnv as s, extractNestedObjectLiteral as t, readEnvReferenceProperty as u };
+export { resolveDocsContentDir as _, loadDocsConfigModule as a, loadProjectEnv as c, readNavTitle as d, readNumberProperty as f, resolveDocsConfigPath as g, readTopLevelStringProperty as h, hasTopLevelProperty as i, readBooleanProperty as l, readTopLevelBooleanProperty as m, extractObjectLiteral as n, loadDocsConfigModuleResult as o, readStringProperty as p, extractTopLevelConfigObject as r, loadDocsConfigModuleResultWithProjectEnv as s, extractNestedObjectLiteral as t, readEnvReferenceProperty as u, resolveDocsProjectRoot as v };

package/dist/{doctor-DUnOjP9T.mjs → doctor-C3IG5hqb.mjs}

@@ -1,4 +1,4 @@
-import { i as scanDocsPageTargets, n as compactAgentDocs, r as inspectAgentCompactionState } from "./agent-FyPQ2AZ4.mjs";
+import { i as scanDocsPageTargets, n as compactAgentDocs, r as inspectAgentCompactionState } from "./agent-Jvn1a78y.mjs";
 import { d as httpLinkHeaderHasTargetRelation, f as AGENT_SKILL_ARCHIVE_MAX_UNCOMPRESSED_BYTES, p as readAgentSkillDocumentFromTar } from "./prompt-references-B6gxePm8.mjs";
 import { A as buildDocsAgentDiscoverySpec, At as DEFAULT_SITEMAP_XML_ROUTE, F as buildDocsMcpEndpointCandidates, Gn as getDocsMcpProtectedResourceMetadataRoutes, It as resolveDocsSitemapConfig, Jn as isDocsMcpOAuthScopeToken, M as buildDocsConfigMap, Ot as DEFAULT_SITEMAP_MD_ROUTE, Qn as normalizeDocsMcpAuthorizationServerUrls, S as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, T as DOCS_CONFIG_MAP_TOP_LEVEL_KEYS, Un as DEFAULT_MCP_WELL_KNOWN_ROUTE, Vn as DEFAULT_MCP_PUBLIC_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, i as DEFAULT_AGENT_FEEDBACK_ROUTE, kt as DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, pn as resolveAskAISearchRequestConfig, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, x as DEFAULT_SKILL_MD_ROUTE } from "./agent-CTOUI2BK.mjs";
 import { f as PAGE_AGENT_CONTRACT_FIELDS } from "./markdown-sections-7OoA7ylx.mjs";
@@ -13,11 +13,11 @@ import { t as runDocsGoldenTasks } from "./agent-evals-DCptRrdP.mjs";
 import { createFilesystemDocsMcpSource, getDocsConfigSchema, resolveDocsMcpConfig } from "./mcp.mjs";
 import "./code-blocks-0wjOsqdJ.mjs";
 import "./server.mjs";
-import { _ as resolveDocsContentDir, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, r as extractTopLevelConfigObject, s as loadDocsConfigModuleResultWithProjectEnv, t as extractNestedObjectLiteral } from "./config-Wcdj-D0a.mjs";
+import { _ as resolveDocsContentDir, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, r as extractTopLevelConfigObject, s as loadDocsConfigModuleResultWithProjectEnv, t as extractNestedObjectLiteral, v as resolveDocsProjectRoot } from "./config-BtxaQTPP.mjs";
 import { t as detectFramework } from "./utils-DpiIioYb.mjs";
-import { i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-CNDwoUOe.mjs";
+import { i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-DyeYD50F.mjs";
 import { t as analyzeConfiguredAgentSkillsProgressiveDisclosure } from "./agent-skills-progressive-disclosure-BVvj7nM8.mjs";
-import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { gunzipSync } from "node:zlib";
@@ -73,6 +73,23 @@ function parseDoctorArgs(argv) {
 			parsed.json = true;
 			continue;
 		}
+		if (arg.startsWith("--json-output=")) {
+			const value = parseInlineFlag(arg).value;
+			if (!value) throw new Error("Missing value for --json-output.");
+			parsed.jsonOutputPath = value;
+			continue;
+		}
+		if (arg === "--json-output") {
+			const value = argv[index + 1];
+			if (!value || value.startsWith("--")) throw new Error("Missing value for --json-output.");
+			parsed.jsonOutputPath = value;
+			index += 1;
+			continue;
+		}
+		if (arg === "--ci") {
+			parsed.ci = true;
+			continue;
+		}
 		if (arg === "--strict") {
 			parsed.strict = true;
 			continue;
@@ -170,6 +187,8 @@ ${pc.dim("Options:")}
   ${pc.cyan("--human")}            Alias for ${pc.cyan("--site")}
   ${pc.cyan("--only <mode>")}      Run only one doctor suite: ${pc.cyan("agent")} or ${pc.cyan("site")}
   ${pc.cyan("--json")}             Print the report as JSON for CI, scripts, and other agents
+  ${pc.cyan("--json-output <path>")} Write the JSON report to a file; use with ${pc.cyan("--ci")} to keep annotation stdout valid
+  ${pc.cyan("--ci")}               Emit actionable GitHub annotations when running in GitHub Actions
   ${pc.cyan("--strict")}           Exit with failure when any check warns or fails
   ${pc.cyan("--fix")}              Refresh stale generated agent.md files and token-budget missing outputs
   ${pc.cyan("--dry-run")}          With ${pc.cyan("--fix")}, report the compaction command without writing files
@@ -1631,7 +1650,7 @@ async function buildHostedAgentChecks(url, pages) {
 		checks
 	};
 }
-function makeCheck(id, title, status, score, maxScore, detail, recommendation) {
+function makeCheck(id, title, status, score, maxScore, detail, recommendation, findings) {
 	return {
 		id,
 		title,
@@ -1639,19 +1658,38 @@ function makeCheck(id, title, status, score, maxScore, detail, recommendation) {
 		score,
 		maxScore,
 		detail,
-		recommendation
-	};
+		recommendation,
+		findings
+	};
+}
+function toDoctorCommandFindings(findings) {
+	return findings.filter((finding) => finding.category === "command" && Boolean(finding.command) && Boolean(finding.proposedCorrection)).map((finding) => ({
+		code: finding.code,
+		severity: finding.severity,
+		file: finding.file,
+		line: finding.line,
+		command: finding.command,
+		reason: finding.message,
+		proposedCorrection: finding.proposedCorrection
+	}));
 }
 async function inspectAgentReadiness(options = {}) {
-	const rootDir = process.cwd();
-	const files = listProjectFiles(rootDir);
-	const framework = detectFramework(rootDir) ?? detectFrameworkFromFiles(files) ?? "unknown";
+	const invocationRoot = process.cwd();
+	let rootDir = invocationRoot;
+	let files = [];
+	let framework = "unknown";
 	const configCheckMax = 10;
 	let configPath;
 	try {
-		configPath = resolveDocsConfigPath(rootDir, options.configPath);
+		configPath = resolveDocsConfigPath(invocationRoot, options.configPath);
+		rootDir = resolveDocsProjectRoot(invocationRoot, configPath);
+		files = listProjectFiles(rootDir);
+		framework = detectFramework(rootDir) ?? detectFrameworkFromFiles(files) ?? "unknown";
 	} catch (error) {
-		const checks = [makeCheck("config", "Docs config", "fail", 0, configCheckMax, error instanceof Error ? error.message : String(error), "Add docs.config.ts[x] or pass --config so the doctor can inspect the docs app.")];
+		const message = error instanceof Error ? error.message : String(error);
+		const invocationFiles = listProjectFiles(invocationRoot);
+		framework = detectFramework(invocationRoot) ?? detectFrameworkFromFiles(invocationFiles) ?? "unknown";
+		const checks = [makeCheck("config", "Docs config", "fail", 0, configCheckMax, message, "Add docs.config.ts[x] or pass --config so the doctor can inspect the docs app.")];
 		return {
 			mode: "agent",
 			framework,
@@ -1678,7 +1716,7 @@ async function inspectAgentReadiness(options = {}) {
 		};
 	}
 	const configContent = readFileSync(configPath, "utf-8");
-	const configLoad = await loadDocsConfigModuleResultWithProjectEnv(rootDir, options.configPath);
+	const configLoad = await loadDocsConfigModuleResultWithProjectEnv(rootDir, configPath);
 	const config = configLoad.status === "evaluated" ? configLoad.config : void 0;
 	let configuredAgentSkillNames;
 	let configuredAgentSkillsError;
@@ -1727,6 +1765,7 @@ async function inspectAgentReadiness(options = {}) {
 		pages: createAgentUsefulnessPagesFromMcp(rootDir, pages),
 		projectFramework: framework === "unknown" ? void 0 : framework
 	});
+	const commandFindings = toDoctorCommandFindings(usefulness.findings);
 	const evaluationInput = config?.agent?.evaluations;
 	const evaluation = resolveGoldenEvaluationInput(evaluationInput);
 	const evaluationBaseUrl = config ? resolveDocsMetadataBaseUrl(config) : void 0;
@@ -1874,7 +1913,7 @@ async function inspectAgentReadiness(options = {}) {
 	checks.push(makeCheck("agent-context-quality", "Agent context usefulness", contextQualityResult.status, contextQualityResult.score, 15, usefulness.metrics.agentBlocks.total > 0 ? `${usefulness.metrics.agentBlocks.useful}/${usefulness.metrics.agentBlocks.total} agent-only blocks are specific and non-repetitive (${usefulness.metrics.agentBlocks.duplicate} duplicate, ${usefulness.metrics.agentBlocks.boilerplate} boilerplate, ${usefulness.metrics.agentBlocks.generic} generic).` : "No embedded agent-only blocks were present; page contracts and sibling agent.md files remain available as alternatives.", usefulness.metrics.agentBlocks.total > 0 && usefulness.metrics.agentBlocks.useful === usefulness.metrics.agentBlocks.total ? void 0 : "Replace repeated agent-only boilerplate with page-specific constraints, commands, files, expected results, and recovery guidance."));
 	checks.push(makeCheck("agent-task-completeness", "Agent task completeness", taskCompletenessResult.status, taskCompletenessResult.score, 15, `${usefulness.metrics.taskCompleteness.completePages}/${usefulness.metrics.actionablePages} actionable pages include prerequisites, an expected result, and recovery guidance (${usefulness.metrics.taskCompleteness.coverage}% complete).`, usefulness.metrics.actionablePages > 0 && usefulness.metrics.taskCompleteness.coverage >= 80 ? void 0 : "Add prerequisites, observable outcomes or verification expectations, and rollback or resolved failure modes to actionable pages."));
 	checks.push(makeCheck("agent-applicability", "Framework and version applicability", applicabilityResult.status, applicabilityResult.score, 10, `${usefulness.metrics.applicability.conflictingPages} conflicting, ${usefulness.metrics.applicability.ambiguousPages} ambiguous, and ${usefulness.metrics.applicability.mismatchedPages} project-mismatched actionable pages.`, usefulness.metrics.actionablePages > 0 && applicabilityIssueCount === 0 ? void 0 : "Declare consistent framework/version metadata in page frontmatter and agent.appliesTo so retrieval can select the right variant."));
-	checks.push(makeCheck("command-health", "Documented command health", commandHealthResult.status, commandHealthResult.score, 10, `${usefulness.metrics.commands.healthy}/${usefulness.metrics.commands.total} statically inspected commands are healthy; ${usefulness.metrics.commands.unhealthy} are unhealthy and ${usefulness.metrics.commands.unverified} could not be verified safely.`, usefulness.metrics.commands.total > 0 && usefulness.metrics.commands.unhealthy === 0 && usefulness.metrics.commands.unverified === 0 ? void 0 : "Update broken or stale commands and make workspace selectors resolvable so scripts, working directories, package managers, and docs CLI subcommands can be verified."));
+	checks.push(makeCheck("command-health", "Documented command health", commandHealthResult.status, commandHealthResult.score, 10, `${usefulness.metrics.commands.healthy}/${usefulness.metrics.commands.total} statically inspected commands are healthy; ${usefulness.metrics.commands.unhealthy} are unhealthy and ${usefulness.metrics.commands.unverified} could not be verified safely.`, usefulness.metrics.commands.total > 0 && usefulness.metrics.commands.unhealthy === 0 && usefulness.metrics.commands.unverified === 0 ? void 0 : "Update broken or stale commands and make workspace selectors resolvable so scripts, working directories, package managers, and docs CLI subcommands can be verified.", commandFindings));
 	checks.push(makeCheck("related-coverage", "Related-page task coverage", relatedCoverageResult.status, relatedCoverageResult.score, 5, `${usefulness.metrics.related.coveredActionablePages}/${usefulness.metrics.actionablePages} actionable pages link to a valid related docs route; ${usefulness.metrics.related.brokenLinks} related links are broken.`, usefulness.metrics.actionablePages > 0 && usefulness.metrics.related.coverage >= 80 && usefulness.metrics.related.brokenLinks === 0 ? void 0 : "Add and validate related routes on actionable pages so agents can expand context without guessing."));
 	checks.push(makeCheck("compact", "Agent compaction freshness", compactionResult.status, compactionResult.score, 5, `${compactionCoverage.freshGeneratedPages} fresh, ${compactionCoverage.staleGeneratedPages} stale, ${compactionCoverage.modifiedGeneratedPages} modified, ${compactionCoverage.unknownGeneratedPages} unknown, ${compactionCoverage.tokenBudgetMissingPages} token-budget missing, and ${compactionCoverage.otherMissingPages} other missing page${compactionCoverage.otherMissingPages === 1 ? "" : "s"} across compactable docs pages.` + (compactConfigured ? " agent.compact defaults are configured." : " No agent.compact defaults were found in docs config."), compactionResult.recommendation));
 	const averageMetric = (values) => values.length === 0 ? 0 : Math.round(values.reduce((total, value) => total + value, 0) / values.length * 100) / 100;
@@ -1902,15 +1941,22 @@ async function inspectAgentReadiness(options = {}) {
 	};
 }
 async function inspectHumanReadiness(options = {}) {
-	const rootDir = process.cwd();
-	const files = listProjectFiles(rootDir);
-	const framework = detectFramework(rootDir) ?? detectFrameworkFromFiles(files) ?? "unknown";
+	const invocationRoot = process.cwd();
+	let rootDir = invocationRoot;
+	let files = [];
+	let framework = "unknown";
 	const configCheckMax = 10;
 	let configPath;
 	try {
-		configPath = resolveDocsConfigPath(rootDir, options.configPath);
+		configPath = resolveDocsConfigPath(invocationRoot, options.configPath);
+		rootDir = resolveDocsProjectRoot(invocationRoot, configPath);
+		files = listProjectFiles(rootDir);
+		framework = detectFramework(rootDir) ?? detectFrameworkFromFiles(files) ?? "unknown";
 	} catch (error) {
-		const checks = [makeCheck("config", "Docs config", "fail", 0, configCheckMax, error instanceof Error ? error.message : String(error), "Add docs.config.ts[x] or pass --config so the doctor can inspect the docs app.")];
+		const message = error instanceof Error ? error.message : String(error);
+		const invocationFiles = listProjectFiles(invocationRoot);
+		framework = detectFramework(invocationRoot) ?? detectFrameworkFromFiles(invocationFiles) ?? "unknown";
+		const checks = [makeCheck("config", "Docs config", "fail", 0, configCheckMax, message, "Add docs.config.ts[x] or pass --config so the doctor can inspect the docs app.")];
 		return {
 			mode: "human",
 			framework,
@@ -1931,7 +1977,7 @@ async function inspectHumanReadiness(options = {}) {
 		};
 	}
 	const configContent = readFileSync(configPath, "utf-8");
-	const configLoad = await loadDocsConfigModuleResultWithProjectEnv(rootDir, options.configPath);
+	const configLoad = await loadDocsConfigModuleResultWithProjectEnv(rootDir, configPath);
 	const config = configLoad.status === "evaluated" ? configLoad.config : void 0;
 	const entry = config?.entry ?? readTopLevelStringProperty(configContent, "entry") ?? "docs";
 	const contentDir = config?.contentDir ?? resolveDocsContentDir(rootDir, configContent, entry);
@@ -1996,6 +2042,12 @@ function printAgentDoctorReport(report) {
 	for (const check of report.checks) {
 		console.log(`${formatStatus(check.status)} ${check.title} ${pc.dim(`(${check.score}/${check.maxScore})`)}`);
 		console.log(`  ${check.detail}`);
+		for (const finding of check.findings ?? []) {
+			const location = `${finding.file}${finding.line ? `:${finding.line}` : ""}`;
+			console.log(`  ${pc.dim(location)} ${pc.bold("Command:")} ${finding.command}`);
+			console.log(`    ${pc.bold("Reason:")} ${finding.reason}`);
+			console.log(`    ${pc.bold("Proposed correction:")} ${finding.proposedCorrection}`);
+		}
 	}
 	if (report.recommendations.length > 0) {
 		console.log();
@@ -2032,6 +2084,30 @@ function serializeDoctorJsonReport(report) {
 function printDoctorJsonReport(report) {
 	console.log(JSON.stringify(serializeDoctorJsonReport(report), null, 2));
 }
+function writeDoctorJsonReport(report, outputPath) {
+	const resolvedPath = path.resolve(process.cwd(), outputPath);
+	mkdirSync(path.dirname(resolvedPath), { recursive: true });
+	writeFileSync(resolvedPath, `${JSON.stringify(serializeDoctorJsonReport(report), null, 2)}\n`, "utf-8");
+}
+function escapeGitHubAnnotationData(value) {
+	return value.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
+}
+function escapeGitHubAnnotationProperty(value) {
+	return escapeGitHubAnnotationData(value).replaceAll(":", "%3A").replaceAll(",", "%2C");
+}
+function emitDoctorGitHubAnnotations(report) {
+	if (process.env.GITHUB_ACTIONS !== "true" || report.mode !== "agent") return;
+	for (const check of report.checks) for (const finding of check.findings ?? []) {
+		const command = finding.severity === "error" ? "error" : finding.severity === "warning" ? "warning" : "notice";
+		const location = [
+			`file=${escapeGitHubAnnotationProperty(finding.file)}`,
+			finding.line ? `line=${finding.line}` : void 0,
+			`title=${escapeGitHubAnnotationProperty(check.title)}`
+		].filter(Boolean).join(",");
+		const message = `Command: ${finding.command} Reason: ${finding.reason} Proposed correction: ${finding.proposedCorrection}`;
+		console.log(`::${command} ${location}::${escapeGitHubAnnotationData(message)}`);
+	}
+}
 function hasNonPassingDoctorCheck(report) {
 	return report.checks.some((check) => check.status !== "pass");
 }
@@ -2093,15 +2169,18 @@ async function runAgentDoctorFixes(report, options) {
 	return fixes;
 }
 async function runDoctor(options = {}) {
+	if (options.ci && options.json) throw new Error("doctor --ci and --json cannot share stdout. Use --ci --json-output <path> to emit GitHub annotations and persist the JSON report in one run.");
 	if (options.mode === "human") {
 		if (options.fix) throw new Error("doctor --fix is currently only supported with --agent.");
 		const report = await inspectHumanReadiness(options);
 		applyDoctorExitCode(report, options);
+		if (options.jsonOutputPath) writeDoctorJsonReport(report, options.jsonOutputPath);
 		if (options.json) {
 			printDoctorJsonReport(report);
 			return report;
 		}
 		printHumanDoctorReport(report);
+		if (options.ci) emitDoctorGitHubAnnotations(report);
 		return report;
 	}
 	let report = await inspectAgentReadiness(options);
@@ -2117,11 +2196,13 @@ async function runDoctor(options = {}) {
 		};
 	}
 	applyDoctorExitCode(report, options);
+	if (options.jsonOutputPath) writeDoctorJsonReport(report, options.jsonOutputPath);
 	if (options.json) {
 		printDoctorJsonReport(report);
 		return report;
 	}
 	printAgentDoctorReport(report);
+	if (options.ci) emitDoctorGitHubAnnotations(report);
 	return report;
 }
 

package/dist/{golden-evaluations-CNDwoUOe.mjs → golden-evaluations-DyeYD50F.mjs}

@@ -1,6 +1,7 @@
 import { An as normalizeAgentFramework, Cn as findDocsAudienceMdxTags, En as resolveDocsAudienceMdxContent, Nn as normalizeAgentVersion, kn as agentVersionConstraintsOverlap } from "./agent-CTOUI2BK.mjs";
 import { _ as hasStructuredPageAgentContract, v as normalizePageAgentFrontmatter } from "./markdown-sections-7OoA7ylx.mjs";
 import { t as extractCodeBlocksFromMarkdown } from "./code-blocks-0wjOsqdJ.mjs";
+import { isMap, isScalar, isSeq, parseDocument } from "yaml";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
 
@@ -39,6 +40,7 @@ const DEFAULT_DOCS_COMMANDS = [
 	"cloud deploy",
 	"cloud preview",
 	"mcp",
+	"skills scaffold",
 	"agent compact",
 	"agent export",
 	"agents generate",
@@ -519,7 +521,7 @@ function analyzePage(page) {
 		sourcePath: page.sourcePath,
 		route: page.route
 	});
-	const shellCommands = collectPageCommands(page, agent, projectedSource);
+	const shellCommands = collectPageCommands(page, agent);
 	return {
 		page,
 		agent,
@@ -698,7 +700,8 @@ function analyzeCommand(options) {
 		findings.push(commandFinding(options, {
 			code: "command-cwd-outside-root",
 			severity: "error",
-			message: `Command working directory resolves outside the project root: ${commandCwd}`
+			message: `Command working directory resolves outside the project root: ${commandCwd}`,
+			proposedCorrection: `Set cwd to an existing project-relative directory inside the docs project instead of ${JSON.stringify(commandCwd)}.`
 		}));
 		return commandAnalysis(findings);
 	}
@@ -706,7 +709,8 @@ function analyzeCommand(options) {
 		findings.push(commandFinding(options, {
 			code: "command-cwd-missing",
 			severity: "error",
-			message: `Command working directory does not exist: ${commandCwd}`
+			message: `Command working directory does not exist: ${commandCwd}`,
+			proposedCorrection: `Create ${JSON.stringify(commandCwd)} or change cwd to an existing project-relative directory.`
 		}));
 		return commandAnalysis(findings);
 	}
@@ -714,7 +718,8 @@ function analyzeCommand(options) {
 		findings.push(commandFinding(options, {
 			code: "command-unverified",
 			severity: "suggestion",
-			message: "Compound commands, redirections, and shell expansions are not executed or inferred; this command is unverified."
+			message: "Compound commands, redirections, and shell expansions are not executed or inferred; this command is unverified.",
+			proposedCorrection: "Split the shell expression into one independently verifiable command per line and document any redirection or expansion as a separate step."
 		}));
 		return commandAnalysis(findings);
 	}
@@ -724,7 +729,8 @@ function analyzeCommand(options) {
 	if (commandPackageManager && expectedPackageManager && commandPackageManager !== expectedPackageManager) findings.push(commandFinding(options, {
 		code: "command-package-manager-mismatch",
 		severity: "warning",
-		message: `Command uses ${commandPackageManager}, but ${expectedPackageManager} is expected for this project or code block.`
+		message: `Command uses ${commandPackageManager}, but ${expectedPackageManager} is expected for this project or code block.`,
+		proposedCorrection: `Rewrite this command using ${expectedPackageManager}, or explicitly mark the example as a ${commandPackageManager} alternative when that is intentional.`
 	}));
 	const workspaceSelection = readWorkspaceSelection(tokens, commandPackageManager);
 	const workspaceResolution = resolveWorkspaceSelection(workspaceSelection, options.packageManifests, options.rootDir, options.workspaceRoot);
@@ -733,7 +739,8 @@ function analyzeCommand(options) {
 		findings.push(commandFinding(options, {
 			code: "command-unverified",
 			severity: "suggestion",
-			message: `Workspace selector could not be resolved statically (${selectors}); this command is unverified.`
+			message: `Workspace selector could not be resolved statically (${selectors}); this command is unverified.`,
+			proposedCorrection: "Replace the selector with an exact workspace package name or path declared by the nearest workspace manifest."
 		}));
 	}
 	const script = readPackageScript(tokens);
@@ -742,13 +749,15 @@ function analyzeCommand(options) {
 		if (workspaceResolution.status === "none" && packageJsons.length === 0) findings.push(commandFinding(options, {
 			code: "command-unverified",
 			severity: "suggestion",
-			message: `No package.json could be found for package script "${script}"; this command is unverified.`
+			message: `No package.json could be found for package script "${script}"; this command is unverified.`,
+			proposedCorrection: "Set cwd to the package that owns this script, or add a package.json with the documented script."
 		}));
 		for (const packageJson of packageJsons) if (packageJson.scripts.has(script)) verificationEstablished = true;
 		else findings.push(commandFinding(options, {
 			code: "command-script-missing",
 			severity: "error",
-			message: `Command references package script "${script}", but that script is not defined in ${packageJson.relativePath}.`
+			message: `Command references package script "${script}", but that script is not defined in ${packageJson.relativePath}.`,
+			proposedCorrection: `Add a ${JSON.stringify(script)} script to ${packageJson.relativePath}, or replace the command with an existing script from that file.`
 		}));
 	}
 	const docsCommand = readDocsCommand(tokens);
@@ -756,13 +765,15 @@ function analyzeCommand(options) {
 	else findings.push(commandFinding(options, {
 		code: "command-cli-unknown",
 		severity: "error",
-		message: `Command references an unknown docs CLI command: docs ${docsCommand}`
+		message: `Command references an unknown docs CLI command: docs ${docsCommand}`,
+		proposedCorrection: `Replace "docs ${docsCommand}" with the intended supported command listed by "docs --help".`
 	}));
 	if (isStaticallyKnownPackageManagerCommand(tokens) || isVersionProbe(tokens) || isStaticallyValidCurlCommand(tokens) || isStaticallyValidShellBuiltin(tokens, resolvedCwd, options.rootDir) || isStaticallyValidAgentToolCommand(tokens)) verificationEstablished = true;
 	if (!verificationEstablished && findings.length === 0) findings.push(commandFinding(options, {
 		code: "command-unverified",
 		severity: "suggestion",
-		message: "Command form could not be verified statically; this command is unverified."
+		message: "Command form could not be verified statically; this command is unverified.",
+		proposedCorrection: "Use a documented package-manager or docs CLI command, or configure explicit executable-example validation for this command."
 	}));
 	return commandAnalysis(findings);
 }
@@ -780,16 +791,97 @@ function commandAnalysis(findings) {
 		status: "healthy"
 	};
 }
-function collectPageCommands(page, agent, projectedSource) {
+function collectContractCommandLocations(source) {
+	const empty = () => ({
+		commands: [],
+		verification: []
+	});
+	const opening = source.match(/^---[^\S\r\n]*\r?\n/);
+	if (!opening) return empty();
+	const frontmatterOffset = opening[0].length;
+	const remainder = source.slice(frontmatterOffset);
+	const closing = /(?:^|\r?\n)---[^\S\r\n]*(?:\r?\n|$)/.exec(remainder);
+	if (!closing) return empty();
+	try {
+		const document = parseDocument(remainder.slice(0, closing.index), { uniqueKeys: true });
+		if (document.errors.length > 0 || !isMap(document.contents)) return empty();
+		const agent = document.contents.get("agent", true);
+		if (!isMap(agent)) return empty();
+		return {
+			commands: collectContractSequenceLocations(agent.get("commands", true), source, frontmatterOffset),
+			verification: collectContractSequenceLocations(agent.get("verification", true), source, frontmatterOffset)
+		};
+	} catch {
+		return empty();
+	}
+}
+function collectContractSequenceLocations(value, source, frontmatterOffset) {
+	if (!isSeq(value)) return [];
+	const locations = [];
+	for (const item of value.items) {
+		const run = isScalar(item) ? item : isMap(item) ? item.get("run", true) : void 0;
+		if (!isScalar(run) || typeof run.value !== "string") continue;
+		const location = contractScalarLocation(run, source, frontmatterOffset);
+		if (location) locations.push(location);
+	}
+	return locations;
+}
+function contractScalarLocation(scalar, source, frontmatterOffset) {
+	const relativeOffset = scalar.range?.[0];
+	if (typeof scalar.value !== "string" || relativeOffset === void 0) return void 0;
+	const absoluteOffset = frontmatterOffset + relativeOffset;
+	return {
+		run: scalar.value,
+		line: source.slice(0, absoluteOffset).split(/\r?\n/).length
+	};
+}
+function claimContractCommandLine(locations, command, claimedLines) {
+	const location = locations.find((candidate) => candidate.run === command && !claimedLines.has(candidate.line));
+	if (!location) return void 0;
+	claimedLines.add(location.line);
+	return location.line;
+}
+function preserveLineBreaksOnly(value) {
+	return value.replace(/[^\r\n]/g, " ");
+}
+/** Agent projection used for command discovery that keeps original source line numbers stable. */
+function projectAgentCommandSource(source) {
+	const tags = findDocsAudienceMdxTags(source);
+	if (tags.length === 0) return source;
+	const scopes = [];
+	let output = "";
+	let cursor = 0;
+	const visible = () => scopes.every((scope) => scope.only !== "human");
+	for (const tag of tags) {
+		const activeScope = scopes.at(-1);
+		if (tag.closing && activeScope?.name !== tag.name) continue;
+		const content = source.slice(cursor, tag.index);
+		output += visible() ? content : preserveLineBreaksOnly(content);
+		output += preserveLineBreaksOnly(source.slice(tag.index, tag.end));
+		cursor = tag.end;
+		if (tag.closing) scopes.pop();
+		else if (!tag.selfClosing) scopes.push({
+			name: tag.name,
+			only: tag.only
+		});
+	}
+	const remaining = source.slice(cursor);
+	output += visible() ? remaining : preserveLineBreaksOnly(remaining);
+	return output;
+}
+function collectPageCommands(page, agent) {
 	const commands = [];
-	for (const command of agent?.commands ?? []) commands.push(normalizeAgentCommand(command, page.sourcePath));
+	const contractLocations = collectContractCommandLocations(page.source);
+	const claimedContractLines = /* @__PURE__ */ new Set();
+	for (const command of agent?.commands ?? []) commands.push(normalizeAgentCommand(command, page.sourcePath, claimContractCommandLine(contractLocations.commands, typeof command === "string" ? command : command.run, claimedContractLines)));
 	for (const verification of agent?.verification ?? []) if (typeof verification !== "string" && verification.run) commands.push({
 		run: verification.run,
+		line: claimContractCommandLine(contractLocations.verification, verification.run, claimedContractLines),
 		sourcePath: page.sourcePath,
 		source: "contract"
 	});
-	collectMarkdownCommands(commands, projectedSource, page.sourcePath);
-	if (page.agentSource) collectMarkdownCommands(commands, page.agentSource, page.agentSourcePath ?? page.sourcePath);
+	collectMarkdownCommands(commands, projectAgentCommandSource(page.source), page.sourcePath);
+	if (page.agentSource) collectMarkdownCommands(commands, projectAgentCommandSource(page.agentSource), page.agentSourcePath ?? page.sourcePath);
 	return dedupeCommands(commands);
 }
 function collectMarkdownCommands(commands, source, sourcePath) {
@@ -801,30 +893,54 @@ function collectMarkdownCommands(commands, source, sourcePath) {
 	for (const block of blocks) {
 		if (!/^(?:bash|console|sh|shell|zsh)$/i.test(block.language ?? "")) continue;
 		for (const command of shellLines(block.code, block.language)) commands.push({
-			run: command,
-			line: block.lineStart,
+			run: command.run,
+			line: block.lineStart + 1 + command.lineOffset,
 			sourcePath,
 			packageManagerHint: block.packageManager,
 			source: "fence"
 		});
 	}
 }
-function normalizeAgentCommand(command, sourcePath) {
+function normalizeAgentCommand(command, sourcePath, line) {
+	const run = typeof command === "string" ? command : command.run;
 	return typeof command === "string" ? {
-		run: command,
+		run,
+		line,
 		sourcePath,
 		source: "contract"
 	} : {
-		run: command.run,
+		run,
 		cwd: command.cwd,
+		line,
 		sourcePath,
 		source: "contract"
 	};
 }
 function shellLines(code, language) {
-	const lines = code.replace(/\\\s*\r?\n\s*/g, " ").split(/\r?\n/);
-	const promptedConsole = language?.toLowerCase() === "console" && lines.some((line) => /^(?:\$|>)\s+/.test(line.trim()));
-	return lines.map((line) => line.trim()).filter((line) => !promptedConsole || /^(?:\$|>)\s+/.test(line)).map((line) => line.replace(/^(?:\$|>)\s+/, "")).filter((line) => Boolean(line) && !line.startsWith("#") && !/^\w+=\S+$/.test(line));
+	const logicalLines = [];
+	let pending;
+	for (const [lineOffset, physicalLine] of code.split(/\r?\n/).entries()) {
+		const trimmed = physicalLine.trim();
+		if (!pending) pending = {
+			run: "",
+			lineOffset
+		};
+		const continued = /\\\s*$/.test(trimmed);
+		const segment = continued ? trimmed.replace(/\\\s*$/, "").trimEnd() : trimmed;
+		pending.run = `${pending.run}${pending.run && segment ? " " : ""}${segment}`;
+		if (continued) continue;
+		logicalLines.push(pending);
+		pending = void 0;
+	}
+	if (pending) logicalLines.push(pending);
+	const promptedConsole = language?.toLowerCase() === "console" && logicalLines.some((line) => /^(?:\$|>)\s+/.test(line.run.trim()));
+	return logicalLines.map((line) => ({
+		...line,
+		run: line.run.trim()
+	})).filter((line) => !promptedConsole || /^(?:\$|>)\s+/.test(line.run)).map((line) => ({
+		...line,
+		run: line.run.replace(/^(?:\$|>)\s+/, "")
+	})).filter((line) => Boolean(line.run) && !line.run.startsWith("#") && !/^\w+=\S+$/.test(line.run));
 }
 function dedupeCommands(commands) {
 	const seen = /* @__PURE__ */ new Set();

package/dist/{init-c3WAqoI2.mjs → init-CuLodGjP.mjs}

@@ -188,7 +188,7 @@ async function configureDocsCloudOnboarding(options) {
 		enabled = cloudAnswer;
 	}
 	if (!enabled) return;
-	const { initCloudConfig } = await import("./cloud-pdNC-tyj.mjs");
+	const { initCloudConfig } = await import("./cloud-DwhH_b_q.mjs");
 	printDocsCloudOnboardingInstructions(await initCloudConfig({
 		rootDir: options.rootDir,
 		configPath: getDocsCloudConfigPathForFramework(options.framework)

package/dist/{mcp-7bvRe9Da.mjs → mcp-D8Hw2blN.mjs}

@@ -9,7 +9,7 @@ import "./agent-evals-DCptRrdP.mjs";
 import { createFilesystemDocsMcpSource, resolveDocsMcpConfig, runDocsMcpStdio } from "./mcp.mjs";
 import "./code-blocks-0wjOsqdJ.mjs";
 import "./server.mjs";
-import { _ as resolveDocsContentDir, d as readNavTitle, g as resolveDocsConfigPath, i as hasTopLevelProperty, l as readBooleanProperty, n as extractObjectLiteral, o as loadDocsConfigModuleResult, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-Wcdj-D0a.mjs";
+import { _ as resolveDocsContentDir, d as readNavTitle, g as resolveDocsConfigPath, i as hasTopLevelProperty, l as readBooleanProperty, n as extractObjectLiteral, o as loadDocsConfigModuleResult, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-BtxaQTPP.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import pc from "picocolors";

package/dist/mcp.mjs

@@ -13,6 +13,9 @@ import * as z from "zod/v4";
 //#region src/mcp.ts
 const DEFAULT_MCP_VERSION = "0.0.0";
 const DEFAULT_MCP_NAME = "@farming-labs/docs";
+const DOCS_MCP_DISCOVERY_CACHE_TTL_MS = 300 * 1e3;
+const DOCS_MCP_LIST_CACHE_TTL_MS = 300 * 1e3;
+const DOCS_MCP_RESOURCE_CACHE_TTL_MS = 60 * 1e3;
 const DEFAULT_MCP_CONTEXT_TOKEN_BUDGET = 4e3;
 const MIN_MCP_CONTEXT_TOKEN_BUDGET = 256;
 const MAX_MCP_CONTEXT_TOKEN_BUDGET = 32e3;
@@ -2625,7 +2628,7 @@ function durationMs(startedAt) {
 }
 function createDocsMcpContentChangeMonitor(options) {
 	let context;
-	let generation;
+	let state;
 	let timer;
 	let running = false;
 	let closed = false;
@@ -2636,11 +2639,14 @@ function createDocsMcpContentChangeMonitor(options) {
 			if (closed || context === void 0 || options.isActive?.() === false) return;
 			running = true;
 			try {
-				const nextGeneration = await options.readGeneration(context);
-				if (generation && nextGeneration !== generation) {
-					generation = nextGeneration;
-					await options.notify();
-				} else generation = nextGeneration;
+				const nextState = await options.readState(context);
+				const previousState = state;
+				state = nextState;
+				if (previousState && nextState.indexGeneration !== previousState.indexGeneration) await options.notify({
+					context,
+					previous: previousState,
+					current: nextState
+				});
 			} catch {} finally {
 				running = false;
 				schedule();
@@ -2657,9 +2663,9 @@ function createDocsMcpContentChangeMonitor(options) {
 				timer = void 0;
 			}
 			try {
-				generation = await options.readGeneration(nextContext);
+				state = await options.readState(nextContext);
 			} catch {
-				generation = void 0;
+				state = void 0;
 			}
 			schedule();
 		},
@@ -2817,10 +2823,36 @@ async function createDocsMcpServer(options) {
 	});
 	const contentChangesEnabled = resolveDocsContentChangesConfig(options.contentChanges).enabled && resolved.tools.listContentChanges !== false;
 	const contentChangeHydrationEnabled = contentChangesEnabled && resolved.tools.hydrateContentChanges !== false;
+	const cacheScope = options.requestContext?.auth ? "private" : "public";
 	const server = new McpServer({
 		name: resolved.name,
 		version: resolved.version
-	});
+	}, { cacheHints: {
+		"server/discover": {
+			ttlMs: DOCS_MCP_DISCOVERY_CACHE_TTL_MS,
+			cacheScope
+		},
+		"tools/list": {
+			ttlMs: DOCS_MCP_LIST_CACHE_TTL_MS,
+			cacheScope
+		},
+		"prompts/list": {
+			ttlMs: DOCS_MCP_LIST_CACHE_TTL_MS,
+			cacheScope
+		},
+		"resources/list": {
+			ttlMs: DOCS_MCP_LIST_CACHE_TTL_MS,
+			cacheScope
+		},
+		"resources/templates/list": {
+			ttlMs: DOCS_MCP_LIST_CACHE_TTL_MS,
+			cacheScope
+		},
+		"resources/read": {
+			ttlMs: DOCS_MCP_RESOURCE_CACHE_TTL_MS,
+			cacheScope
+		}
+	} });
 	installDocsMcpSdkRegistrationPagination(server, protocolScope);
 	if (contentChangesEnabled) server.server.registerCapabilities({ resources: { subscribe: true } });
 	const registerResource = (name, uri, metadata, callback) => {
@@ -4511,22 +4543,35 @@ function createDocsMcpHttpHandler(options) {
 	});
 	const configuredPollInterval = options.contentChangePollIntervalMs;
 	const contentChangePollIntervalMs = typeof configuredPollInterval === "number" && Number.isFinite(configuredPollInterval) && configuredPollInterval >= 10 ? Math.floor(configuredPollInterval) : DEFAULT_DOCS_MCP_CONTENT_CHANGE_POLL_INTERVAL_MS;
-	async function readMonitoredGeneration(context) {
+	async function readMonitoredState(context) {
 		const locale = options.source.resolveLocale?.(void 0, context);
 		const pages = dedupePages(await options.source.getPages(locale, context));
-		return (await contentChangeFeed.resolve({
+		const result = await contentChangeFeed.resolve({
 			pages: toSearchSourcePages(pages),
 			search: options.search,
 			audience: "agent",
 			locale,
 			baseUrl: options.source.baseUrl ?? (context.request ? new URL(context.request.url).origin : void 0),
 			...context.request ? { request: context.request.clone() } : {}
-		})).indexGeneration;
+		});
+		return {
+			indexGeneration: result.indexGeneration,
+			resourceUris: [
+				"docs://navigation",
+				DOCS_MCP_CONTENT_CHANGES_CURRENT_URI,
+				`docs://changes/${result.indexGeneration}`,
+				...pages.map((page) => toPageResourceUri(page.url))
+			]
+		};
 	}
 	const contentChangeMonitor = createDocsMcpContentChangeMonitor({
 		pollIntervalMs: contentChangePollIntervalMs,
-		readGeneration: readMonitoredGeneration,
-		notify: () => mcpHandler.notify.resourceUpdated(DOCS_MCP_CONTENT_CHANGES_CURRENT_URI),
+		readState: readMonitoredState,
+		notify: ({ previous, current }) => {
+			mcpHandler.notify.resourcesChanged();
+			const affectedUris = new Set([...previous.resourceUris, ...current.resourceUris]);
+			for (const uri of affectedUris) mcpHandler.notify.resourceUpdated(uri);
+		},
 		isActive: () => eventBus.listenerCount > 0,
 		unrefTimer: true
 	});
@@ -4659,21 +4704,34 @@ async function runDocsMcpStdio(options) {
 			requestContext
 		});
 		if (!contentChangesEnabled) return server;
-		const readGeneration = async () => {
+		const readState = async () => {
 			const locale = options.source.resolveLocale?.(void 0, requestContext);
 			const pages = dedupePages(await options.source.getPages(locale, requestContext));
-			return (await contentChangeFeed.resolve({
+			const result = await contentChangeFeed.resolve({
 				pages: toSearchSourcePages(pages),
 				search: options.search,
 				audience: "agent",
 				locale,
 				baseUrl: options.source.baseUrl
-			})).indexGeneration;
+			});
+			return {
+				indexGeneration: result.indexGeneration,
+				resourceUris: [
+					"docs://navigation",
+					DOCS_MCP_CONTENT_CHANGES_CURRENT_URI,
+					`docs://changes/${result.indexGeneration}`,
+					...pages.map((page) => toPageResourceUri(page.url))
+				]
+			};
 		};
 		const monitor = createDocsMcpContentChangeMonitor({
 			pollIntervalMs,
-			readGeneration: () => readGeneration(),
-			notify: () => server.server.sendResourceUpdated({ uri: DOCS_MCP_CONTENT_CHANGES_CURRENT_URI })
+			readState: () => readState(),
+			notify: async ({ previous, current }) => {
+				await server.server.sendResourceListChanged();
+				const affectedUris = new Set([...previous.resourceUris, ...current.resourceUris]);
+				for (const uri of affectedUris) await server.server.sendResourceUpdated({ uri });
+			}
 		});
 		await monitor.start(requestContext);
 		const closeServer = server.close.bind(server);

package/dist/{review-DEnzotkg.mjs → review-R39cQsvi.mjs}

@@ -7,9 +7,9 @@ import "./agent-skills-server-CwmzAzf_.mjs";
 import { c as resolveDocsReviewConfig, o as ensureDocsReviewWorkflow, s as readDocsReviewConfigFromSource, t as runDocsGoldenTasks } from "./agent-evals-DCptRrdP.mjs";
 import { createFilesystemDocsMcpSource, getDocsConfigSchema, resolveDocsMcpConfig } from "./mcp.mjs";
 import "./code-blocks-0wjOsqdJ.mjs";
-import { _ as resolveDocsContentDir, g as resolveDocsConfigPath, h as readTopLevelStringProperty, s as loadDocsConfigModuleResultWithProjectEnv } from "./config-Wcdj-D0a.mjs";
+import { _ as resolveDocsContentDir, g as resolveDocsConfigPath, h as readTopLevelStringProperty, s as loadDocsConfigModuleResultWithProjectEnv } from "./config-BtxaQTPP.mjs";
 import { t as detectFramework } from "./utils-DpiIioYb.mjs";
-import { a as extractAgentBlocks, i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-CNDwoUOe.mjs";
+import { a as extractAgentBlocks, i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-DyeYD50F.mjs";
 import { t as analyzeConfiguredAgentSkillsProgressiveDisclosure } from "./agent-skills-progressive-disclosure-BVvj7nM8.mjs";
 import matter from "gray-matter";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";

package/dist/{robots-DXy1xW3D.mjs → robots-C-Nh0xH6.mjs}

@@ -2,7 +2,7 @@ import "./agent-CTOUI2BK.mjs";
 import "./markdown-sections-7OoA7ylx.mjs";
 import "./standards-discovery-Ckx0tN7B.mjs";
 import { c as renderDocsRobotsGeneratedBlock, f as upsertDocsRobotsGeneratedBlock, i as DOCS_ROBOTS_GENERATED_BLOCK_START, r as DOCS_ROBOTS_GENERATED_BLOCK_END, u as resolveDocsRobotsConfig } from "./robots-DaU38DZw.mjs";
-import { a as loadDocsConfigModule, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, m as readTopLevelBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-Wcdj-D0a.mjs";
+import { a as loadDocsConfigModule, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, m as readTopLevelBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-BtxaQTPP.mjs";
 import { t as detectFramework } from "./utils-DpiIioYb.mjs";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";

package/dist/{search-DznddPqw.mjs → search-3TUBKtz5.mjs}

@@ -10,7 +10,7 @@ import "./agent-evals-DCptRrdP.mjs";
 import { createFilesystemDocsMcpSource } from "./mcp.mjs";
 import "./code-blocks-0wjOsqdJ.mjs";
 import "./server.mjs";
-import { _ as resolveDocsContentDir, c as loadProjectEnv, g as resolveDocsConfigPath, h as readTopLevelStringProperty, s as loadDocsConfigModuleResultWithProjectEnv } from "./config-Wcdj-D0a.mjs";
+import { _ as resolveDocsContentDir, c as loadProjectEnv, g as resolveDocsConfigPath, h as readTopLevelStringProperty, s as loadDocsConfigModuleResultWithProjectEnv } from "./config-BtxaQTPP.mjs";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import pc from "picocolors";

package/dist/{sitemap-DCsrVSPf.mjs → sitemap-DrILEtYo.mjs}

@@ -8,7 +8,7 @@ import "./agent-evals-DCptRrdP.mjs";
 import { createFilesystemDocsMcpSource } from "./mcp.mjs";
 import "./code-blocks-0wjOsqdJ.mjs";
 import "./server.mjs";
-import { _ as resolveDocsContentDir, a as loadDocsConfigModule, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-Wcdj-D0a.mjs";
+import { _ as resolveDocsContentDir, a as loadDocsConfigModule, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-BtxaQTPP.mjs";
 import { t as detectFramework } from "./utils-DpiIioYb.mjs";
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";

package/dist/{skills-CPDwsMq4.mjs → skills-35ecRZtd.mjs}

@@ -9,7 +9,7 @@ import "./agent-evals-DCptRrdP.mjs";
 import { createFilesystemDocsMcpSource } from "./mcp.mjs";
 import "./code-blocks-0wjOsqdJ.mjs";
 import "./server.mjs";
-import { _ as resolveDocsContentDir, a as loadDocsConfigModule, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-Wcdj-D0a.mjs";
+import { _ as resolveDocsContentDir, a as loadDocsConfigModule, d as readNavTitle, g as resolveDocsConfigPath, h as readTopLevelStringProperty, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-BtxaQTPP.mjs";
 import { n as estimateAgentSkillInstructionTokens, r as resolveDocsAgentSkillsProgressiveDisclosureConfig } from "./agent-skills-progressive-disclosure-BVvj7nM8.mjs";
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/docs",
-  "version": "0.2.88",
+  "version": "0.2.89",
   "description": "Modern, flexible MDX-based docs framework — core types, config, and CLI",
   "keywords": [
     "docs",