@farming-labs/docs 0.2.106 → 0.2.107

package/dist/{agent-CaCWThBY.mjs → agent-B0eRMIyt.mjs}

@@ -40,6 +40,7 @@ const DEFAULT_COMPRESSION_BASE_URL = "https://api.farming-labs.dev";
 const DEFAULT_COMPRESSION_MODEL = "docs-cloud-compress-v1";
 const DEFAULT_COMPRESSION_AGGRESSIVENESS = .3;
 const DEFAULT_DOCS_CLOUD_API_KEY_ENV = "DOCS_CLOUD_API_KEY";
+const MAX_COMPRESSION_INPUT_CHARACTERS = 2e5;
 const INDEX_PAGE_BASENAMES = new Set([
 	"index",
 	"page",
@@ -76,6 +77,10 @@ function parseAgentCompactArgs(argv) {
 			parsed.dryRun = true;
 			continue;
 		}
+		if (arg === "--check") {
+			parsed.check = true;
+			continue;
+		}
 		if (arg === "--changed") {
 			parsed.changed = true;
 			continue;
@@ -414,7 +419,7 @@ function inspectAgentCompactionState(page, target, defaults) {
 		tokenBudget
 	};
 }
-function protectForCompression(input) {
+function protectForCompression(input, protectInlineCode = true) {
 	const segments = [];
 	const stash = (value) => {
 		const token = `__DOCS_SAFE_${segments.length}__`;
@@ -424,14 +429,21 @@ function protectForCompression(input) {
 	let result = input;
 	result = result.replace(/```[\s\S]*?```/g, stash);
 	result = result.replace(/\[[^\]]+\]\([^)]+\)/g, stash);
-	result = result.replace(/`[^`\n]+`/g, stash);
+	if (protectInlineCode) result = result.replace(/`[^`\n]+`/g, stash);
 	result = result.replace(/^(URL|Description|Related):[^\n]*$/gm, stash);
 	result = result.replace(/https?:\/\/[^\s)]+/g, stash);
 	for (let index = 0; index < segments.length; index += 1) result = result.replace(`__DOCS_SAFE_${index}__`, `<docs_safe>${segments[index]}</docs_safe>`);
 	return result;
 }
+function buildCompressionInput(input) {
+	const fullyProtected = protectForCompression(input);
+	if (fullyProtected.length <= MAX_COMPRESSION_INPUT_CHARACTERS) return fullyProtected;
+	const withoutInlineCodeProtection = protectForCompression(input, false);
+	if (withoutInlineCodeProtection.length <= MAX_COMPRESSION_INPUT_CHARACTERS) return withoutInlineCodeProtection;
+	throw new Error(`Docs Cloud compression input is ${withoutInlineCodeProtection.length} characters after adaptive protection; the maximum is ${MAX_COMPRESSION_INPUT_CHARACTERS}. Split or shorten the source page before compacting it.`);
+}
 function sanitizeCompressedOutput(output) {
-	return output.replace(/<\/?docs_safe>/g, "");
+	return output.replace(/<\/?docs_safe>/g, "").replace(/[ \t]+$/gm, "");
 }
 async function compressDocument(input, options) {
 	const apiKey = resolveCompressionApiKey(options.apiKey, options.apiKeyEnv);
@@ -440,7 +452,7 @@ async function compressDocument(input, options) {
 	if (aggressiveness < 0 || aggressiveness > 1) throw new Error("Aggressiveness must be between 0.0 and 1.0.");
 	const payload = {
 		model: options.model ?? DEFAULT_COMPRESSION_MODEL,
-		input: protectForCompression(input),
+		input: buildCompressionInput(input),
 		compression_settings: {
 			aggressiveness,
 			...options.maxOutputTokens !== void 0 ? { max_output_tokens: options.maxOutputTokens } : {},
@@ -515,7 +527,8 @@ async function compactAgentDocs(options = {}) {
 	if (resolvedOptions.all && resolvedOptions.pages && resolvedOptions.pages.length > 0) throw new Error("Use either --all or specific page arguments, not both.");
 	if (resolvedOptions.includeMissing && !resolvedOptions.stale) throw new Error("Use --include-missing together with --stale.");
 	const requestedPages = resolvedOptions.pages?.filter((value) => value.trim().length > 0) ?? [];
-	if (!resolvedOptions.all && requestedPages.length === 0 && !resolvedOptions.stale && !resolvedOptions.changed) throw new Error("Pass --all, --changed, --stale, or at least one docs page slug/path to compact.");
+	if (resolvedOptions.check && (resolvedOptions.all || resolvedOptions.stale || resolvedOptions.changed || resolvedOptions.includeMissing || resolvedOptions.dryRun || requestedPages.length > 0)) throw new Error("Use --check by itself; it inspects every compactable docs page without writing.");
+	if (!resolvedOptions.all && requestedPages.length === 0 && !resolvedOptions.stale && !resolvedOptions.changed && !resolvedOptions.check) throw new Error("Pass --all, --changed, --stale, or at least one docs page slug/path to compact.");
 	const pages = await createFilesystemDocsMcpSource({
 		rootDir,
 		entry,
@@ -523,7 +536,7 @@ async function compactAgentDocs(options = {}) {
 		siteTitle
 	}).getPages();
 	if (pages.length === 0) throw new Error(`No docs content was found under ${contentDir}.`);
-	const selectedPages = resolveSelectedPages(pages, scanDocsPageTargets(rootDir, contentDir, entry), entry, requestedPages, resolvedOptions.all === true || resolvedOptions.stale === true && requestedPages.length === 0 || resolvedOptions.changed === true && requestedPages.length === 0);
+	const selectedPages = resolveSelectedPages(pages, scanDocsPageTargets(rootDir, contentDir, entry), entry, requestedPages, resolvedOptions.all === true || resolvedOptions.check === true || resolvedOptions.stale === true && requestedPages.length === 0 || resolvedOptions.changed === true && requestedPages.length === 0);
 	const filteredPages = resolvedOptions.changed ? filterChangedPages(rootDir, contentDir, selectedPages) : selectedPages;
 	if (filteredPages.length === 0) {
 		if (resolvedOptions.changed) {
@@ -532,6 +545,27 @@ async function compactAgentDocs(options = {}) {
 		}
 		throw new Error("No compactable docs pages matched the request.");
 	}
+	if (resolvedOptions.check) {
+		let fresh = 0;
+		let stale = 0;
+		let modified = 0;
+		let unknown = 0;
+		let requiredMissing = 0;
+		let optionalMissing = 0;
+		for (const { page, target } of filteredPages) {
+			const state = inspectAgentCompactionState(page, target, resolvedOptions);
+			if (state.status === "fresh") fresh += 1;
+			else if (state.status === "stale") stale += 1;
+			else if (state.status === "modified" || state.status === "stale-modified") modified += 1;
+			else if (state.status === "unknown") unknown += 1;
+			else if (state.tokenBudget !== void 0) requiredMissing += 1;
+			else optionalMissing += 1;
+		}
+		const summary = `${fresh} fresh, ${stale} stale, ${modified} modified, ${unknown} unknown, ${requiredMissing} required missing, and ${optionalMissing} optional missing`;
+		if (stale > 0 || requiredMissing > 0) throw new Error(`Agent compaction freshness check failed: ${summary}. Run docs agent compact --stale --include-missing, then review generated changes.`);
+		console.log(pc.green(`Agent compaction freshness check passed: ${summary}.`));
+		return;
+	}
 	let created = 0;
 	let overwritten = 0;
 	let processed = 0;
@@ -598,6 +632,7 @@ ${pc.dim("Examples:")}
   ${pc.cyan("npx @farming-labs/docs@latest agent compact --changed")}
   ${pc.cyan("npx @farming-labs/docs@latest agent compact --stale")}
   ${pc.cyan("npx @farming-labs/docs@latest agent compact --stale --include-missing")}
+  ${pc.cyan("npx @farming-labs/docs@latest agent compact --check")}
 
 ${pc.dim("Per-page override:")}
   Add ${pc.cyan("agent.tokenBudget")} to a page frontmatter block to override the compact output target for that page.
@@ -608,6 +643,7 @@ ${pc.dim("Options:")}
   ${pc.cyan("--changed")}                Compact only docs pages changed in the current git working tree
   ${pc.cyan("--stale")}                  Re-compact only stale generated agent.md files
   ${pc.cyan("--include-missing")}        With ${pc.cyan("--stale")}, also create missing agent.md files for explicit pages or pages that define ${pc.cyan("agent.tokenBudget")}
+  ${pc.cyan("--check")}                  Check generated agent.md freshness without an API key, network request, or file write
   ${pc.cyan("--config <path>")}          Use a custom docs config path instead of ${pc.dim("docs.config.ts[x]")}
   ${pc.cyan("--api-key <key>")}          Use an API key directly; prefer ${pc.dim("cloud.apiKey.env")}
   ${pc.cyan("--api-key-env <name>")}     Env var name for the Docs Cloud API key; prefer ${pc.dim("cloud.apiKey.env")}

package/dist/cli/index.d.mts

@@ -11,5 +11,6 @@ declare function parseCommandAlias(rawCommand?: string): {
 };
 /** Parse flags like --template next, --name my-docs, --theme concrete, --entry docs, --framework astro (exported for tests). */
 declare function parseFlags(argv: string[]): Record<string, string | boolean | undefined>;
+declare function printAgentHelp(): void;
 //#endregion
-export { formatCliError, parseCommandAlias, parseFlags };
+export { formatCliError, parseCommandAlias, parseFlags, printAgentHelp };

package/dist/cli/index.mjs

@@ -154,7 +154,8 @@ async function main() {
 	} else if (parsedCommand.command === "mcp") {
 		const { runMcp } = await import("../mcp-DsjWxF7g.mjs");
 		await runMcp(mcpOptions);
-	} else if (parsedCommand.command === "agent" && subcommand === "feedback") {
+	} else if (parsedCommand.command === "agent" && (subcommand === "--help" || subcommand === "-h")) printAgentHelp();
+	else if (parsedCommand.command === "agent" && subcommand === "feedback") {
 		const { parseAgentFeedbackImproveArgs, printAgentFeedbackImproveHelp, runAgentFeedbackImprove } = await import("../feedback-DWVUMrxy.mjs");
 		const feedbackOptions = parseAgentFeedbackImproveArgs(args.slice(2));
 		if (feedbackOptions.help) {
@@ -179,7 +180,7 @@ async function main() {
 		}
 		await runAgentMaintenancePropose(proposeOptions);
 	} else if (parsedCommand.command === "agent" && subcommand === "compact") {
-		const { compactAgentDocs, parseAgentCompactArgs, printAgentCompactHelp } = await import("../agent-CaCWThBY.mjs").then((n) => n.t);
+		const { compactAgentDocs, parseAgentCompactArgs, printAgentCompactHelp } = await import("../agent-B0eRMIyt.mjs").then((n) => n.t);
 		const agentCompactOptions = parseAgentCompactArgs(args.slice(2));
 		if (agentCompactOptions.help) {
 			printAgentCompactHelp();
@@ -197,16 +198,7 @@ async function main() {
 	} else if (parsedCommand.command === "agent") {
 		console.error(pc.red(`Unknown agent subcommand: ${subcommand ?? "(missing)"}`));
 		console.error();
-		const { printAgentCompactHelp } = await import("../agent-CaCWThBY.mjs").then((n) => n.t);
-		const { printAgentExportHelp } = await import("../agent-export-GcTZPLfB.mjs");
-		const { printAgentFeedbackImproveHelp } = await import("../feedback-DWVUMrxy.mjs");
-		const { printAgentFeedbackEvaluationsHelp } = await import("../feedback-evals-k0sFDdms.mjs");
-		const { printAgentMaintenanceProposeHelp } = await import("../propose-DJOiHu9Y.mjs");
-		printAgentCompactHelp();
-		printAgentExportHelp();
-		printAgentFeedbackImproveHelp();
-		printAgentFeedbackEvaluationsHelp();
-		printAgentMaintenanceProposeHelp();
+		printAgentHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "agents" && subcommand === "generate") {
 		const { generateAgents, parseAgentsGenerateArgs, printAgentsGenerateHelp } = await import("../agents-e1SYT64z.mjs");
@@ -240,7 +232,7 @@ async function main() {
 		printSkillScaffoldHelp();
 		process.exit(1);
 	} else if (parsedCommand.command === "doctor") {
-		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-CtK1CRPj.mjs");
+		const { parseDoctorArgs, printDoctorHelp, runDoctor } = await import("../doctor-CPGUlDVt.mjs");
 		const doctorOptions = parseDoctorArgs(args.slice(1));
 		if (doctorOptions.help) {
 			printDoctorHelp();
@@ -248,7 +240,7 @@ async function main() {
 		}
 		await runDoctor(doctorOptions);
 	} else if (parsedCommand.command === "review") {
-		const { parseReviewArgs, printReviewHelp, runReview } = await import("../review-XI9FXeos.mjs");
+		const { parseReviewArgs, printReviewHelp, runReview } = await import("../review-BvjSFiD_.mjs");
 		const reviewOptions = parseReviewArgs(args.slice(1));
 		if (reviewOptions.help) {
 			printReviewHelp();
@@ -334,6 +326,22 @@ async function main() {
 		process.exit(1);
 	}
 }
+function printAgentHelp() {
+	console.log(`${pc.bold("docs agent")} — Agent documentation utilities
+
+Usage:
+  docs agent <command> [options]
+
+Commands:
+  ${pc.cyan("compact")}         Generate or refresh page-level ${pc.dim("agent.md")} files
+  ${pc.cyan("export")}          Export or check a static Agent Bundle
+  ${pc.cyan("feedback")}        Cluster recurring agent feedback into improvement drafts
+  ${pc.cyan("feedback-evals")}  Create reviewed evaluation candidates and regression baselines
+  ${pc.cyan("propose")}         Combine recurring signals into maintenance proposals
+
+Run ${pc.cyan("docs agent <command> --help")} for command-specific options.
+`);
+}
 function printHelp() {
 	console.log(`
 ${pc.bold("@farming-labs/docs")} — Documentation framework CLI
@@ -415,6 +423,7 @@ ${pc.dim("Options for agent compact:")}
   ${pc.cyan("agent compact --all")}                 Compact every folder-based docs page
   ${pc.cyan("agent compact --changed")}             Compact only docs pages changed in the current git working tree
   ${pc.cyan("agent compact --stale")}               Refresh only stale generated ${pc.dim("agent.md")} files
+  ${pc.cyan("agent compact --check")}               Fail when generated ${pc.dim("agent.md")} files are stale or required files are missing
   ${pc.cyan("--page <slug|path>")}                  Repeatable explicit page flag; positional page args work too
   ${pc.cyan("--include-missing")}                   With ${pc.cyan("--stale")}, also create explicit or token-budget pages missing ${pc.dim("agent.md")}
   ${pc.cyan("--api-key <key>")}                     Use an API key directly; prefer ${pc.dim("cloud.apiKey.env")}
@@ -550,4 +559,4 @@ main().catch((err) => {
 });
 
 //#endregion
-export { formatCliError, parseCommandAlias, parseFlags };
+export { formatCliError, parseCommandAlias, parseFlags, printAgentHelp };

package/dist/{doctor-CtK1CRPj.mjs → doctor-CPGUlDVt.mjs}

@@ -1,4 +1,4 @@
-import { i as scanDocsPageTargets, n as compactAgentDocs, r as inspectAgentCompactionState } from "./agent-CaCWThBY.mjs";
+import { i as scanDocsPageTargets, n as compactAgentDocs, r as inspectAgentCompactionState } from "./agent-B0eRMIyt.mjs";
 import { f as PAGE_AGENT_CONTRACT_FIELDS } from "./markdown-sections-BKy4labo.mjs";
 import { d as httpLinkHeaderHasTargetRelation, f as AGENT_SKILL_ARCHIVE_MAX_UNCOMPRESSED_BYTES, p as readAgentSkillDocumentFromTar } from "./prompt-references-1Wce71c7.mjs";
 import { A as buildDocsAgentDiscoverySpec, At as DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE, F as buildDocsMcpEndpointCandidates, Gn as getDocsMcpProtectedResourceMetadataRoutes, Jn as isDocsMcpOAuthScopeToken, Lt as resolveDocsSitemapConfig, M as buildDocsConfigMap, 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, cr as resolveDocsOkfTrustMetadata, h as DEFAULT_LLMS_FULL_TXT_ROUTE, i as DEFAULT_AGENT_FEEDBACK_ROUTE, jt as DEFAULT_SITEMAP_XML_ROUTE, kt as DEFAULT_SITEMAP_MD_ROUTE, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, mn as resolveAskAISearchRequestConfig, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, sr as resolveDocsOkfConfig, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, x as DEFAULT_SKILL_MD_ROUTE } from "./agent-DCTGj6J7.mjs";
@@ -16,7 +16,7 @@ import "./code-blocks-D90CCJFs.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, v as resolveDocsProjectRoot } from "./config-DrZ3fXgf.mjs";
 import { t as detectFramework } from "./utils-Cc1SrVza.mjs";
-import { i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-De4KwoYr.mjs";
+import { i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-Bnlljxq3.mjs";
 import { t as analyzeConfiguredAgentSkillsProgressiveDisclosure } from "./agent-skills-progressive-disclosure-DL-q4JZo.mjs";
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import path from "node:path";

package/dist/{golden-evaluations-De4KwoYr.mjs → golden-evaluations-Bnlljxq3.mjs}

@@ -43,6 +43,9 @@ const DEFAULT_DOCS_COMMANDS = [
 	"skills scaffold",
 	"agent compact",
 	"agent export",
+	"agent feedback",
+	"agent feedback-evals",
+	"agent propose",
 	"agents generate",
 	"doctor",
 	"review",

package/dist/{review-XI9FXeos.mjs → review-BvjSFiD_.mjs}

@@ -9,7 +9,7 @@ import { createFilesystemDocsMcpSource, getDocsConfigSchema, resolveDocsMcpConfi
 import "./code-blocks-D90CCJFs.mjs";
 import { _ as resolveDocsContentDir, g as resolveDocsConfigPath, h as readTopLevelStringProperty, s as loadDocsConfigModuleResultWithProjectEnv } from "./config-DrZ3fXgf.mjs";
 import { t as detectFramework } from "./utils-Cc1SrVza.mjs";
-import { a as extractAgentBlocks, i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-De4KwoYr.mjs";
+import { a as extractAgentBlocks, i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-Bnlljxq3.mjs";
 import { t as analyzeConfiguredAgentSkillsProgressiveDisclosure } from "./agent-skills-progressive-disclosure-DL-q4JZo.mjs";
 import matter from "gray-matter";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";

package/package.json

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