@farming-labs/docs 0.2.105 → 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.105",
+  "version": "0.2.107",
   "description": "Modern, flexible MDX-based docs framework — core types, config, and CLI",
   "keywords": [
     "docs",

package/styles/themes/shadcn.css

@@ -13,13 +13,43 @@
   --fd-framework-article-padding: 32px 0 64px;
 }
 
-#nd-docs-layout:not([data-fd-framework]) article#nd-page {
+#nd-docs-layout:not([data-fd-framework]) article#nd-page,
+#nd-docs-layout[data-fd-browser-adapter] article#nd-page {
   width: 100%;
   max-width: calc(var(--fd-content-width, 640px) + 64px);
   padding: 32px 32px 64px;
   justify-self: center;
 }
 
+#nd-docs-layout[data-fd-browser-adapter] .fd-below-title-block {
+  margin: 0.75rem 0 2.5rem;
+}
+
+#nd-docs-layout[data-fd-browser-adapter] .fd-title-separator {
+  margin: 0 0 0.75rem;
+}
+
+#nd-docs-layout[data-fd-browser-adapter] .fd-page-actions,
+#nd-docs-layout[data-fd-browser-adapter] [data-page-actions] {
+  margin: 0 0 0.625rem;
+}
+
+#nd-docs-layout[data-fd-browser-adapter] .fd-page-meta {
+  margin: 0;
+}
+
+@media (max-width: 1279px) {
+  #nd-docs-layout[data-fd-browser-adapter] {
+    --fd-toc-width: 0px !important;
+  }
+}
+
+@media (max-width: 767px) {
+  #nd-docs-layout[data-fd-browser-adapter] {
+    --fd-sidebar-width: 0px !important;
+  }
+}
+
 :root {
   --color-fd-primary: oklch(0 0 0);
   --color-fd-primary-foreground: oklch(0.985 0 0);
@@ -136,10 +166,10 @@ button[data-search-full],
 [data-search-full],
 .fd-sidebar-search-btn,
 .fd-search-trigger-mobile {
-  min-height: 2rem;
-  border: 0 !important;
+  min-height: 2.25rem;
+  border: 1px solid var(--fd-shadcn-soft-border) !important;
   border-radius: calc(var(--radius) * 0.8) !important;
-  background: var(--fd-shadcn-control) !important;
+  background: color-mix(in oklab, var(--fd-shadcn-control) 82%, transparent) !important;
   color: var(--color-fd-muted-foreground) !important;
   box-shadow: none !important;
   font-size: 0.8125rem !important;
@@ -154,14 +184,101 @@ button[data-search-full]:hover,
   color: var(--color-fd-foreground) !important;
 }
 
+#nd-docs-layout .fd-sidebar-search-ai-row {
+  display: flex;
+  width: 100%;
+  align-items: stretch;
+  gap: 0.5rem;
+}
+
+#nd-docs-layout .fd-sidebar-search-ai-row .fd-sidebar-search-btn {
+  display: flex;
+  min-width: 0;
+  flex: 1 1 auto;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.5rem 0.625rem !important;
+  cursor: pointer;
+  transition:
+    background-color 150ms,
+    border-color 150ms,
+    color 150ms;
+}
+
+#nd-docs-layout .fd-sidebar-search-ai-row .fd-sidebar-search-btn > svg {
+  width: 1rem;
+  height: 1rem;
+  flex: 0 0 auto;
+  opacity: 0.72;
+}
+
+#nd-docs-layout
+  .fd-sidebar-search-ai-row
+  .fd-sidebar-search-btn
+  > span:not(.fd-sidebar-search-kbd) {
+  min-width: 0;
+  flex: 0 1 auto;
+  overflow: hidden;
+  text-align: left;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+button[data-search-full] > :is(div, span):has(> kbd),
+[data-search-full] > :is(div, span):has(> kbd),
+.fd-sidebar-search-kbd {
+  display: inline-flex !important;
+  min-width: 0 !important;
+  height: 1.375rem !important;
+  flex: 0 0 auto !important;
+  align-items: center !important;
+  justify-content: center !important;
+  gap: 0.125rem !important;
+  margin-inline-start: auto !important;
+  border: 1px solid var(--fd-shadcn-soft-border) !important;
+  border-radius: calc(var(--radius) * 0.55) !important;
+  background: var(--color-fd-background) !important;
+  box-shadow:
+    0 1px 2px rgb(0 0 0 / 6%),
+    inset 0 -1px 0 color-mix(in oklab, var(--color-fd-border) 70%, transparent) !important;
+  padding: 0 0.375rem !important;
+  line-height: 1 !important;
+}
+
 button[data-search-full] kbd,
 [data-search-full] kbd,
 .fd-sidebar-search-kbd kbd {
+  min-width: 0 !important;
   border: 0 !important;
   background: transparent !important;
   color: var(--color-fd-muted-foreground) !important;
+  font-family: var(--fd-font-mono, "Geist Mono", ui-monospace, monospace) !important;
   font-size: 0.6875rem !important;
   font-weight: 500 !important;
+  line-height: 1 !important;
+  padding: 0 !important;
+}
+
+#nd-docs-layout .fd-sidebar-search-ai-row .fd-sidebar-ai-btn {
+  width: 2.25rem;
+  min-width: 2.25rem;
+  min-height: 2.25rem;
+  border: 1px solid var(--fd-shadcn-soft-border) !important;
+  border-radius: calc(var(--radius) * 0.8) !important;
+  background: color-mix(in oklab, var(--fd-shadcn-control) 82%, transparent) !important;
+  color: var(--color-fd-muted-foreground) !important;
+  box-shadow: none !important;
+}
+
+#nd-docs-layout .fd-sidebar-search-ai-row .fd-sidebar-ai-btn:hover {
+  border-color: var(--color-fd-border) !important;
+  background: var(--fd-shadcn-control-hover) !important;
+  color: var(--color-fd-foreground) !important;
+}
+
+#nd-docs-layout .fd-sidebar-search-ai-row :is(.fd-sidebar-search-btn, .fd-sidebar-ai-btn):focus-visible {
+  outline: 2px solid var(--color-fd-ring);
+  outline-offset: 2px;
 }
 
 aside#nd-sidebar,
@@ -555,6 +672,7 @@ aside#nd-sidebar button.text-fd-muted-foreground,
 }
 
 .fd-docs-content article h2,
+.fd-page-body h2,
 #nd-page h2,
 .fd-docs-content h2 {
   color: var(--color-fd-foreground) !important;
@@ -562,10 +680,11 @@ aside#nd-sidebar button.text-fd-muted-foreground,
   font-weight: 600 !important;
   letter-spacing: -0.015em !important;
   line-height: 1.4 !important;
-  margin-top: 2.25rem;
+  margin: 2.75rem 0 1rem !important;
 }
 
 .fd-docs-content article h3,
+.fd-page-body h3,
 #nd-page h3,
 .fd-docs-content h3 {
   color: var(--color-fd-foreground) !important;
@@ -573,6 +692,7 @@ aside#nd-sidebar button.text-fd-muted-foreground,
   font-weight: 600 !important;
   letter-spacing: -0.01em !important;
   line-height: 1.45 !important;
+  margin: 2rem 0 0.75rem !important;
 }
 
 #nd-page :is(h1, h2, h3, h4) > a.peer,
@@ -602,13 +722,36 @@ aside#nd-sidebar button.text-fd-muted-foreground,
 }
 
 .fd-docs-content,
+.fd-page-body,
 #nd-page .prose {
   color: var(--color-fd-foreground);
   font-size: 0.9375rem;
   line-height: 1.75;
 }
 
+#nd-docs-layout :is(.fd-docs-content, .fd-page-body, #nd-page .prose) p {
+  margin: 0 0 1.25rem;
+}
+
+#nd-docs-layout
+  :is(.fd-docs-content, .fd-page-body, #nd-page .prose)
+  :is(ul, ol):not(:where(.not-prose, .not-prose *)) {
+  margin: 0 0 1.5rem;
+}
+
+#nd-docs-layout
+  :is(.fd-docs-content, .fd-page-body, #nd-page .prose)
+  li:not(:where(.not-prose, .not-prose *))
+  + li {
+  margin-top: 0.5rem;
+}
+
+#nd-docs-layout :is(.fd-docs-content, .fd-page-body, #nd-page .prose) .fd-table-wrapper {
+  margin: 1.25rem 0 2.5rem !important;
+}
+
 .fd-docs-content :is(p, li, td, blockquote),
+.fd-page-body :is(p, li, td, blockquote),
 #nd-page .prose :is(p, li, td, blockquote) {
   color: var(--color-fd-foreground);
   line-height: 1.75;
@@ -635,7 +778,7 @@ aside#nd-sidebar button.text-fd-muted-foreground,
 .fd-page-nav-card,
 .fd-page-nav a,
 #nd-page > div[class~="@container"] > a {
-  border: 0 !important;
+  border: 1px solid var(--fd-shadcn-soft-border) !important;
   border-radius: calc(var(--radius) * 0.8) !important;
   background: var(--fd-shadcn-control) !important;
   color: var(--color-fd-foreground) !important;
@@ -674,7 +817,7 @@ aside#nd-sidebar button.text-fd-muted-foreground,
   display: grid !important;
   grid-template-columns: repeat(2, minmax(0, 1fr)) !important;
   gap: 0.75rem !important;
-  margin-top: 1.5rem !important;
+  margin-top: 2.25rem !important;
   padding-top: 0 !important;
   border-top: 0 !important;
 }
@@ -688,12 +831,34 @@ aside#nd-sidebar button.text-fd-muted-foreground,
 #nd-page > div[class~="@container"] > a {
   display: flex !important;
   min-width: 0;
-  min-height: 4rem !important;
+  min-height: 4.75rem !important;
   flex-direction: column !important;
   justify-content: center !important;
-  gap: 0.125rem !important;
-  padding: 0.75rem !important;
+  gap: 0.375rem !important;
+  padding: 0.875rem 1rem !important;
+  background: var(--color-fd-card) !important;
+  box-shadow: 0 1px 2px rgb(0 0 0 / 4%) !important;
   text-decoration: none !important;
+  transition:
+    background-color 150ms,
+    border-color 150ms,
+    color 150ms,
+    box-shadow 150ms !important;
+}
+
+.fd-page-nav-card:hover,
+.fd-page-nav a:hover,
+#nd-page > div[class~="@container"] > a:hover {
+  border-color: var(--color-fd-border) !important;
+  background: color-mix(in oklab, var(--color-fd-accent) 72%, var(--color-fd-card)) !important;
+  box-shadow: 0 1px 3px rgb(0 0 0 / 7%) !important;
+}
+
+.fd-page-nav-card:focus-visible,
+.fd-page-nav a:focus-visible,
+#nd-page > div[class~="@container"] > a:focus-visible {
+  outline: 2px solid var(--color-fd-ring);
+  outline-offset: 2px;
 }
 
 .fd-page-nav-next,
@@ -703,6 +868,9 @@ aside#nd-sidebar button.text-fd-muted-foreground,
 
 .fd-page-nav-title,
 #nd-page > div[class~="@container"] > a > div:first-child {
+  display: inline-flex !important;
+  align-items: center !important;
+  gap: 0.375rem !important;
   min-height: 0 !important;
   color: var(--color-fd-foreground) !important;
   font-size: 0.8125rem !important;
@@ -710,6 +878,13 @@ aside#nd-sidebar button.text-fd-muted-foreground,
   line-height: 1.35 !important;
 }
 
+.fd-page-nav-title svg {
+  width: 0.875rem;
+  height: 0.875rem;
+  flex: 0 0 auto;
+  color: var(--color-fd-muted-foreground);
+}
+
 .fd-page-nav-description,
 #nd-page > div[class~="@container"] > a > p:last-child {
   min-height: 0 !important;
@@ -814,7 +989,7 @@ aside#nd-sidebar button.text-fd-muted-foreground,
   outline-offset: -2px !important;
 }
 
-:is(.fd-docs-content, #nd-page .prose)
+:is(.fd-docs-content, .fd-page-body, #nd-page .prose)
   [data-orientation="horizontal"]:has(> [role="tablist"]) {
   overflow: hidden;
   border: 1px solid var(--fd-shadcn-soft-border) !important;
@@ -823,15 +998,18 @@ aside#nd-sidebar button.text-fd-muted-foreground,
   box-shadow: none !important;
 }
 
-:is(.fd-docs-content, #nd-page .prose)
+:is(.fd-docs-content, .fd-page-body, #nd-page .prose)
   [data-orientation="horizontal"]:has(> [role="tablist"])
   > [role="tabpanel"] {
   background: var(--color-fd-card) !important;
 }
 
 .fd-docs-content pre,
+.fd-page-body pre,
 .fd-docs-content .shiki,
+.fd-page-body .shiki,
 .fd-docs-content [data-codeblock],
+.fd-page-body [data-codeblock],
 figure.shiki,
 .fd-codeblock,
 .fd-ai-code-block {
@@ -869,6 +1047,7 @@ figure.shiki,
 }
 
 .fd-docs-content pre,
+.fd-page-body pre,
 figure.shiki pre,
 .fd-codeblock pre {
   background: transparent !important;
@@ -877,19 +1056,28 @@ figure.shiki pre,
 
 /* Compact code surfaces modeled after the current shadcn docs. */
 figure.shiki,
-.fd-docs-content figure.shiki {
-  margin-block: 1.25rem !important;
-  border: 0 !important;
-  border-radius: calc(var(--radius) * 1.8) !important;
+.fd-docs-content figure.shiki,
+.fd-page-body figure.shiki {
+  margin: 1.5rem 0 2rem !important;
+  border: 1px solid var(--fd-shadcn-soft-border) !important;
+  border-radius: calc(var(--radius) * 0.9) !important;
   background: var(--fd-shadcn-code) !important;
   padding-block: 0 !important;
 }
 
+/* Framework browser shells intentionally clear Shiki backgrounds so token
+ * colors can be themed. Restore only the code surface at equal specificity. */
+:is(html.dark, body.dark) #nd-docs-layout[data-fd-framework] figure.shiki,
+#nd-docs-layout[data-fd-framework].dark figure.shiki {
+  background: var(--fd-shadcn-code) !important;
+}
+
 figure.shiki pre,
-.fd-docs-content figure.shiki pre {
+.fd-docs-content figure.shiki pre,
+.fd-page-body figure.shiki pre {
   max-width: 100%;
   margin: 0 !important;
-  padding: 0.625rem 0.75rem !important;
+  padding: 0.75rem 0 !important;
   overflow-x: auto !important;
   overscroll-behavior-inline: contain;
   scrollbar-color: color-mix(in oklab, var(--color-fd-foreground) 18%, transparent)
@@ -898,16 +1086,18 @@ figure.shiki pre,
 }
 
 figure.shiki pre > code,
-.fd-docs-content figure.shiki pre > code {
+.fd-docs-content figure.shiki pre > code,
+.fd-page-body figure.shiki pre > code {
   font-family: var(--fd-font-mono, "Geist Mono", ui-monospace, monospace) !important;
-  font-size: 0.875rem !important;
+  font-size: 0.8125rem !important;
   font-variant-ligatures: none;
-  line-height: 1.75 !important;
+  line-height: 1.6 !important;
   tab-size: 2;
 }
 
 figure.shiki pre > code > :is(.line, [data-line]) {
-  min-height: 1.53125rem;
+  min-height: 1.3rem;
+  padding-inline: 1rem 3rem !important;
 }
 
 figure.shiki pre > code > :is(.line, [data-line])[data-highlighted-line] {
@@ -1068,7 +1258,8 @@ article :not(pre) > code,
 
 @media (max-width: 767px) {
   figure.shiki pre,
-  .fd-docs-content figure.shiki pre {
+  .fd-docs-content figure.shiki pre,
+  .fd-page-body figure.shiki pre {
     padding: 0.625rem 0.75rem !important;
   }
 }
@@ -1128,8 +1319,8 @@ article :not(pre) > code,
   font-weight: 600;
 }
 
-:is(.fd-docs-content, #nd-page .prose) blockquote {
-  margin: 1.25rem 0 !important;
+:is(.fd-docs-content, .fd-page-body, #nd-page .prose) blockquote {
+  margin: 1.5rem 0 2rem !important;
   border-inline-start: 2px solid var(--color-fd-border) !important;
   background: transparent !important;
   color: var(--color-fd-muted-foreground) !important;
@@ -1137,19 +1328,19 @@ article :not(pre) > code,
   padding: 0.125rem 0 0.125rem 1rem !important;
 }
 
-:is(.fd-docs-content, #nd-page .prose) blockquote :is(p, li) {
+:is(.fd-docs-content, .fd-page-body, #nd-page .prose) blockquote :is(p, li) {
   color: inherit !important;
 }
 
-:is(.fd-docs-content, #nd-page .prose) details {
+:is(.fd-docs-content, .fd-page-body, #nd-page .prose) details {
   overflow: hidden;
-  margin: 1rem 0;
+  margin: 1.5rem 0 2rem;
   border: 1px solid var(--fd-shadcn-soft-border);
   border-radius: calc(var(--radius) * 1.2);
   background: var(--color-fd-card);
 }
 
-:is(.fd-docs-content, #nd-page .prose) details > summary {
+:is(.fd-docs-content, .fd-page-body, #nd-page .prose) details > summary {
   min-height: 2.75rem;
   cursor: pointer;
   color: var(--color-fd-card-foreground);
@@ -1159,19 +1350,19 @@ article :not(pre) > code,
   transition: background-color 150ms ease;
 }
 
-:is(.fd-docs-content, #nd-page .prose) details > summary:hover {
+:is(.fd-docs-content, .fd-page-body, #nd-page .prose) details > summary:hover {
   background: color-mix(in oklab, var(--color-fd-accent) 55%, transparent);
 }
 
-:is(.fd-docs-content, #nd-page .prose) details[open] > summary {
+:is(.fd-docs-content, .fd-page-body, #nd-page .prose) details[open] > summary {
   border-bottom: 1px solid var(--fd-shadcn-soft-border);
 }
 
-:is(.fd-docs-content, #nd-page .prose) details > :not(summary) {
+:is(.fd-docs-content, .fd-page-body, #nd-page .prose) details > :not(summary) {
   margin-inline: 1rem;
 }
 
-:is(.fd-docs-content, #nd-page .prose)
+:is(.fd-docs-content, .fd-page-body, #nd-page .prose)
   [data-orientation="vertical"][class~="divide-y"] {
   overflow: hidden;
   border: 1px solid var(--fd-shadcn-soft-border) !important;
@@ -1180,7 +1371,7 @@ article :not(pre) > code,
   box-shadow: none !important;
 }
 
-:is(.fd-docs-content, #nd-page .prose)
+:is(.fd-docs-content, .fd-page-body, #nd-page .prose)
   [data-orientation="vertical"][class~="divide-y"]
   [data-radix-collection-item] {
   min-height: 2.75rem;
@@ -1190,7 +1381,7 @@ article :not(pre) > code,
   transition: background-color 150ms ease;
 }
 
-:is(.fd-docs-content, #nd-page .prose)
+:is(.fd-docs-content, .fd-page-body, #nd-page .prose)
   [data-orientation="vertical"][class~="divide-y"]
   [data-radix-collection-item]:hover {
   background: color-mix(in oklab, var(--color-fd-accent) 55%, transparent) !important;
@@ -1211,7 +1402,7 @@ article :not(pre) > code,
   box-shadow: 0 0 0 4px var(--color-fd-background);
 }
 
-:is(.fd-docs-content, #nd-page .prose) kbd {
+:is(.fd-docs-content, .fd-page-body, #nd-page .prose) kbd {
   display: inline-flex;
   min-width: 1.5rem;
   min-height: 1.5rem;
@@ -1228,7 +1419,8 @@ article :not(pre) > code,
   box-shadow: 0 1px 0 color-mix(in oklab, var(--color-fd-border) 80%, transparent);
 }
 
-:is(.fd-docs-content, #nd-page .prose) hr {
+:is(.fd-docs-content, .fd-page-body, #nd-page .prose) hr {
+  margin: 3rem 0 !important;
   border-color: var(--fd-shadcn-soft-border) !important;
 }
 
@@ -1666,7 +1858,8 @@ article :not(pre) > code,
     --fd-framework-article-padding: 24px 16px 48px;
   }
 
-  #nd-docs-layout:not([data-fd-framework]) article#nd-page {
+  #nd-docs-layout:not([data-fd-framework]) article#nd-page,
+  #nd-docs-layout[data-fd-browser-adapter] article#nd-page {
     max-width: 100%;
     padding: 24px 16px 48px;
   }
@@ -1685,6 +1878,7 @@ article :not(pre) > code,
   }
 
   .fd-docs-content,
+  .fd-page-body,
   #nd-page .prose {
     font-size: 0.9375rem;
   }