@farming-labs/docs 0.1.37 → 0.1.39

package/dist/cli/index.mjs

@@ -69,7 +69,7 @@ async function main() {
 		searchApiKey: typeof flags["search-api-key"] === "string" ? flags["search-api-key"] : void 0
 	};
 	if (!parsedCommand.command || parsedCommand.command === "init") {
-		const { init } = await import("../init-i5ySLGa2.mjs");
+		const { init } = await import("../init-DHlRFytW.mjs");
 		await init(initOptions);
 	} else if (parsedCommand.command === "mcp") {
 		const { runMcp } = await import("../mcp-DLP94P1H.mjs");

package/dist/index.d.mts

@@ -132,6 +132,8 @@ declare const DEFAULT_LLMS_TXT_ROUTE = "/llms.txt";
 declare const DEFAULT_LLMS_FULL_TXT_ROUTE = "/llms-full.txt";
 declare const DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE = "/.well-known/llms.txt";
 declare const DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE = "/.well-known/llms-full.txt";
+declare const DEFAULT_SKILL_MD_ROUTE = "/skill.md";
+declare const DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE = "/.well-known/skill.md";
 declare const DEFAULT_AGENT_FEEDBACK_ROUTE = "/api/docs/agent/feedback";
 interface DocsAgentFeedbackDiscoveryConfig {
   enabled?: boolean;
@@ -156,6 +158,17 @@ interface DocsAgentDiscoverySpecOptions {
     acceptHeader?: boolean;
   };
 }
+interface DocsSkillDocumentOptions {
+  origin: string;
+  entry?: string;
+  search?: boolean | DocsSearchConfig;
+  mcp: DocsMcpResolvedConfig;
+  feedback?: DocsAgentFeedbackDiscoveryConfig;
+  llms?: DocsLlmsDiscoveryConfig;
+  markdown?: {
+    acceptHeader?: boolean;
+  };
+}
 interface DocsMarkdownPage {
   slug?: string;
   url: string;
@@ -173,6 +186,7 @@ declare function normalizeDocsPathSegment(value: string): string;
 declare function normalizeDocsUrlPath(value: string): string;
 declare function isDocsAgentDiscoveryRequest(url: URL): boolean;
 declare function isDocsMcpRequest(url: URL): boolean;
+declare function isDocsSkillRequest(url: URL): boolean;
 declare function isDocsPublicGetRequest(entry: string, url: URL, request: Request): boolean;
 declare function resolveDocsLlmsTxtFormat(url: URL): "llms" | "llms-full" | null;
 declare function resolveDocsMarkdownRequest(entry: string, url: URL, request: Request): {
@@ -181,6 +195,15 @@ declare function resolveDocsMarkdownRequest(entry: string, url: URL, request: Re
 declare function findDocsMarkdownPage<T extends DocsMarkdownPage>(entry: string, pages: T[], requestedPath: string): T | null;
 declare function renderDocsMarkdownDocument(page: DocsMcpPage | DocsSearchSourcePage): string;
 declare function renderDocsMarkdownDocument(page: DocsMarkdownPage): string;
+declare function renderDocsSkillDocument({
+  origin,
+  entry,
+  search,
+  mcp,
+  feedback,
+  llms,
+  markdown
+}: DocsSkillDocumentOptions): string;
 declare function resolveDocsAgentMdxContent(content: string, audience: "human" | "agent"): string;
 declare function buildDocsAgentDiscoverySpec({
   origin,
@@ -256,6 +279,11 @@ declare function buildDocsAgentDiscoverySpec({
   };
   skills: {
     enabled: boolean;
+    file: string;
+    route: string;
+    wellKnown: string;
+    api: string;
+    generatedFallback: boolean;
     registry: string;
     install: string;
     recommended: {
@@ -295,4 +323,4 @@ declare function buildDocsAgentDiscoverySpec({
   };
 };
 //#endregion
-export { type AIConfig, type AgentFeedbackConfig, type AlgoliaDocsSearchConfig, type ApiReferenceConfig, type ApiReferenceRenderer, type BreadcrumbConfig, type ChangelogConfig, type ChangelogEntrySummary, type ChangelogFrontmatter, type CodeBlockCopyData, type CopyMarkdownConfig, type CustomDocsSearchConfig, DEFAULT_AGENT_FEEDBACK_ROUTE, DEFAULT_AGENT_SPEC_ROUTE, DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, DEFAULT_DOCS_API_ROUTE, DEFAULT_LLMS_FULL_TXT_ROUTE, DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE, DEFAULT_LLMS_TXT_ROUTE, DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE, DEFAULT_MCP_PUBLIC_ROUTE, DEFAULT_MCP_ROUTE, DEFAULT_MCP_WELL_KNOWN_ROUTE, type DocsAgentDiscoverySpecOptions, type DocsAgentFeedbackContext, type DocsAgentFeedbackData, type DocsAgentFeedbackDiscoveryConfig, type DocsConfig, type DocsFeedbackData, type DocsFeedbackValue, type DocsI18nConfig, type DocsLlmsDiscoveryConfig, type DocsMarkdownPage, type DocsMcpConfig, type DocsMcpToolsConfig, type DocsMetadata, type DocsNav, type DocsPathMatch, type DocsRelatedItem, type DocsSearchAdapter, type DocsSearchAdapterContext, type DocsSearchAdapterFactory, type DocsSearchChunkingConfig, type DocsSearchConfig, type DocsSearchDocument, type DocsSearchEmbeddingsConfig, type DocsSearchQuery, type DocsSearchResult, type DocsSearchResultType, type DocsSearchSourcePage, type DocsTheme, type FeedbackConfig, type FontStyle, type GithubConfig, type LastUpdatedConfig, type LlmsTxtConfig, type McpDocsSearchConfig, type OGConfig, type OpenDocsConfig, type OpenDocsProvider, type OpenGraphImage, type OrderingItem, type PageActionsConfig, type PageFrontmatter, type PageOpenGraph, type PageTwitter, type ResolvedChangelogConfig, type ResolvedDocsI18n, type ResolvedDocsRelatedLink, type SidebarComponentProps, type SidebarConfig, type SidebarFolderNode, type SidebarNode, type SidebarPageNode, type SidebarTree, type SimpleDocsSearchConfig, type ThemeToggleConfig, type TypesenseDocsSearchConfig, type TypographyConfig, type UIConfig, buildDocsAgentDiscoverySpec, buildDocsSearchDocuments, buildPageOpenGraph, buildPageTwitter, createAlgoliaSearchAdapter, createCustomSearchAdapter, createMcpSearchAdapter, createSimpleSearchAdapter, createTheme, createTypesenseSearchAdapter, deepMerge, defineDocs, extendTheme, findDocsMarkdownPage, isDocsAgentDiscoveryRequest, isDocsMcpRequest, isDocsPublicGetRequest, normalizeDocsPathSegment, normalizeDocsRelated, normalizeDocsUrlPath, performDocsSearch, renderDocsMarkdownDocument, renderDocsRelatedMarkdownLines, resolveChangelogConfig, resolveDocsAgentMdxContent, resolveDocsI18n, resolveDocsLlmsTxtFormat, resolveDocsLocale, resolveDocsMarkdownRequest, resolveDocsPath, resolveOGImage, resolveSearchRequestConfig, resolveTitle };
+export { type AIConfig, type AgentFeedbackConfig, type AlgoliaDocsSearchConfig, type ApiReferenceConfig, type ApiReferenceRenderer, type BreadcrumbConfig, type ChangelogConfig, type ChangelogEntrySummary, type ChangelogFrontmatter, type CodeBlockCopyData, type CopyMarkdownConfig, type CustomDocsSearchConfig, DEFAULT_AGENT_FEEDBACK_ROUTE, DEFAULT_AGENT_SPEC_ROUTE, DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, DEFAULT_DOCS_API_ROUTE, DEFAULT_LLMS_FULL_TXT_ROUTE, DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE, DEFAULT_LLMS_TXT_ROUTE, DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE, DEFAULT_MCP_PUBLIC_ROUTE, DEFAULT_MCP_ROUTE, DEFAULT_MCP_WELL_KNOWN_ROUTE, DEFAULT_SKILL_MD_ROUTE, DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, type DocsAgentDiscoverySpecOptions, type DocsAgentFeedbackContext, type DocsAgentFeedbackData, type DocsAgentFeedbackDiscoveryConfig, type DocsConfig, type DocsFeedbackData, type DocsFeedbackValue, type DocsI18nConfig, type DocsLlmsDiscoveryConfig, type DocsMarkdownPage, type DocsMcpConfig, type DocsMcpToolsConfig, type DocsMetadata, type DocsNav, type DocsPathMatch, type DocsRelatedItem, type DocsSearchAdapter, type DocsSearchAdapterContext, type DocsSearchAdapterFactory, type DocsSearchChunkingConfig, type DocsSearchConfig, type DocsSearchDocument, type DocsSearchEmbeddingsConfig, type DocsSearchQuery, type DocsSearchResult, type DocsSearchResultType, type DocsSearchSourcePage, type DocsSkillDocumentOptions, type DocsTheme, type FeedbackConfig, type FontStyle, type GithubConfig, type LastUpdatedConfig, type LlmsTxtConfig, type McpDocsSearchConfig, type OGConfig, type OpenDocsConfig, type OpenDocsProvider, type OpenGraphImage, type OrderingItem, type PageActionsConfig, type PageFrontmatter, type PageOpenGraph, type PageTwitter, type ResolvedChangelogConfig, type ResolvedDocsI18n, type ResolvedDocsRelatedLink, type SidebarComponentProps, type SidebarConfig, type SidebarFolderNode, type SidebarNode, type SidebarPageNode, type SidebarTree, type SimpleDocsSearchConfig, type ThemeToggleConfig, type TypesenseDocsSearchConfig, type TypographyConfig, type UIConfig, buildDocsAgentDiscoverySpec, buildDocsSearchDocuments, buildPageOpenGraph, buildPageTwitter, createAlgoliaSearchAdapter, createCustomSearchAdapter, createMcpSearchAdapter, createSimpleSearchAdapter, createTheme, createTypesenseSearchAdapter, deepMerge, defineDocs, extendTheme, findDocsMarkdownPage, isDocsAgentDiscoveryRequest, isDocsMcpRequest, isDocsPublicGetRequest, isDocsSkillRequest, normalizeDocsPathSegment, normalizeDocsRelated, normalizeDocsUrlPath, performDocsSearch, renderDocsMarkdownDocument, renderDocsRelatedMarkdownLines, renderDocsSkillDocument, resolveChangelogConfig, resolveDocsAgentMdxContent, resolveDocsI18n, resolveDocsLlmsTxtFormat, resolveDocsLocale, resolveDocsMarkdownRequest, resolveDocsPath, resolveOGImage, resolveSearchRequestConfig, resolveTitle };

package/dist/index.mjs

@@ -278,6 +278,8 @@ const DEFAULT_LLMS_TXT_ROUTE = "/llms.txt";
 const DEFAULT_LLMS_FULL_TXT_ROUTE = "/llms-full.txt";
 const DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE = "/.well-known/llms.txt";
 const DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE = "/.well-known/llms-full.txt";
+const DEFAULT_SKILL_MD_ROUTE = "/skill.md";
+const DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE = "/.well-known/skill.md";
 const DEFAULT_AGENT_FEEDBACK_ROUTE = "/api/docs/agent/feedback";
 function normalizeDocsPathSegment(value) {
 	return value.replace(/^\/+|\/+$/g, "");
@@ -296,10 +298,15 @@ function isDocsMcpRequest(url) {
 	const pathname = normalizeDocsUrlPath(url.pathname);
 	return pathname === DEFAULT_MCP_ROUTE || pathname === DEFAULT_MCP_PUBLIC_ROUTE || pathname === DEFAULT_MCP_WELL_KNOWN_ROUTE;
 }
+function isDocsSkillRequest(url) {
+	const pathname = normalizeDocsUrlPath(url.pathname);
+	if (pathname === DEFAULT_SKILL_MD_ROUTE || pathname === DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE) return true;
+	return pathname === DEFAULT_DOCS_API_ROUTE && url.searchParams.get("format")?.trim() === "skill";
+}
 function isDocsPublicGetRequest(entry, url, request) {
 	const pathname = normalizeDocsUrlPath(url.pathname);
 	if (pathname === DEFAULT_DOCS_API_ROUTE || pathname === DEFAULT_MCP_ROUTE) return false;
-	return isDocsAgentDiscoveryRequest(url) || resolveDocsLlmsTxtFormat(url) !== null || resolveDocsMarkdownRequest(entry, url, request) !== null;
+	return isDocsAgentDiscoveryRequest(url) || isDocsSkillRequest(url) || resolveDocsLlmsTxtFormat(url) !== null || resolveDocsMarkdownRequest(entry, url, request) !== null;
 }
 function resolveDocsLlmsTxtFormat(url) {
 	const pathname = normalizeDocsUrlPath(url.pathname);
@@ -338,6 +345,40 @@ function renderDocsMarkdownDocument(page) {
 	lines.push("", page.agentFallbackRawContent ?? page.rawContent ?? page.content);
 	return lines.join("\n");
 }
+function renderDocsSkillDocument({ origin, entry = "docs", search, mcp, feedback, llms, markdown }) {
+	const normalizedEntry = normalizeDocsPathSegment(entry) || "docs";
+	const siteTitle = compactSkillText(llms?.siteTitle ?? "Documentation");
+	const siteDescription = llms?.siteDescription ? compactSkillText(llms.siteDescription) : void 0;
+	const llmsEnabled = llms?.enabled ?? true;
+	const searchEnabled = isSearchEnabled(search);
+	const feedbackEnabled = feedback?.enabled ?? false;
+	const feedbackRoute = feedback?.route ?? DEFAULT_AGENT_FEEDBACK_ROUTE;
+	const feedbackSchemaRoute = feedback?.schemaRoute ?? `${feedbackRoute}/schema`;
+	const description = truncateSkillDescription(`Use ${siteTitle} through markdown routes, llms.txt, agent discovery, search, and MCP when available.`);
+	const markdownAcceptHeader = markdown?.acceptHeader === false ? null : "text/markdown";
+	const lines = [
+		"---",
+		"name: docs",
+		`description: ${toYamlString(description)}`,
+		"---",
+		"",
+		`# ${siteTitle} Skill`,
+		"",
+		`Base URL: ${origin}`
+	];
+	if (siteDescription) lines.push(`Description: ${siteDescription}`);
+	lines.push("", "## When To Use", "Use this skill when you need to read or implement against this documentation site.", "", "## Start Here", `- Fetch ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}; fall back to ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE} or ${DEFAULT_AGENT_SPEC_ROUTE}.`, `- Fetch /${normalizedEntry}.md for the root docs page.`, `- Fetch /${normalizedEntry}/{slug}.md for page-specific context.`);
+	if (markdownAcceptHeader) lines.push(`- You can also request ${markdownAcceptHeader} from normal page URLs.`);
+	if (searchEnabled) lines.push(`- Search with ${DEFAULT_DOCS_API_ROUTE}?query={query} when you do not know the page.`);
+	if (llmsEnabled) lines.push(`- Use ${DEFAULT_LLMS_TXT_ROUTE} for a compact docs index.`, `- Use ${DEFAULT_LLMS_FULL_TXT_ROUTE} for full markdown context.`);
+	if (mcp.enabled) lines.push(`- Use ${DEFAULT_MCP_WELL_KNOWN_ROUTE} or ${DEFAULT_MCP_PUBLIC_ROUTE} for MCP tools when your environment supports MCP.`);
+	if (feedbackEnabled) lines.push(`- Read ${feedbackSchemaRoute} before posting agent feedback to ${feedbackRoute}.`);
+	lines.push("", "## Routes", `- Skill document: ${DEFAULT_SKILL_MD_ROUTE}`, `- Skill well-known alias: ${DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE}`, `- Skill API format: ${DEFAULT_DOCS_API_ROUTE}?format=skill`, `- Agent discovery: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE}`, `- Agent discovery fallback: ${DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE}`, `- Markdown root: /${normalizedEntry}.md`, `- Markdown pages: /${normalizedEntry}/{slug}.md`);
+	if (llmsEnabled) lines.push(`- llms.txt: ${DEFAULT_LLMS_TXT_ROUTE}`, `- llms-full.txt: ${DEFAULT_LLMS_FULL_TXT_ROUTE}`, `- llms well-known aliases: ${DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE}, ${DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE}`);
+	if (mcp.enabled) lines.push(`- MCP: ${DEFAULT_MCP_PUBLIC_ROUTE}, ${DEFAULT_MCP_WELL_KNOWN_ROUTE}`);
+	lines.push("", "## Reusable Framework Skills", "For framework setup, CLI, page actions, Ask AI, or configuration work, install the reusable Farming Labs skills:", "", "```sh", "npx skills add farming-labs/docs", "```");
+	return lines.join("\n");
+}
 function resolveDocsAgentMdxContent(content, audience) {
 	const lines = content.split("\n");
 	const output = [];
@@ -461,6 +502,11 @@ function buildDocsAgentDiscoverySpec({ origin, entry = "docs", i18n = null, sear
 		},
 		skills: {
 			enabled: true,
+			file: "skill.md",
+			route: DEFAULT_SKILL_MD_ROUTE,
+			wellKnown: DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE,
+			api: `${DEFAULT_DOCS_API_ROUTE}?format=skill`,
+			generatedFallback: true,
 			registry: "skills.sh",
 			install: "npx skills add farming-labs/docs",
 			recommended: [{
@@ -522,6 +568,17 @@ function isSearchEnabled(search) {
 	if (search && typeof search === "object" && search.enabled === false) return false;
 	return true;
 }
+function compactSkillText(value) {
+	return value.replace(/\s+/g, " ").trim();
+}
+function truncateSkillDescription(value) {
+	const normalized = compactSkillText(value);
+	if (normalized.length <= 1024) return normalized;
+	return `${normalized.slice(0, 1021).trimEnd()}...`;
+}
+function toYamlString(value) {
+	return JSON.stringify(value);
+}
 
 //#endregion
-export { DEFAULT_AGENT_FEEDBACK_ROUTE, DEFAULT_AGENT_SPEC_ROUTE, DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, DEFAULT_DOCS_API_ROUTE, DEFAULT_LLMS_FULL_TXT_ROUTE, DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE, DEFAULT_LLMS_TXT_ROUTE, DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE, DEFAULT_MCP_PUBLIC_ROUTE, DEFAULT_MCP_ROUTE, DEFAULT_MCP_WELL_KNOWN_ROUTE, buildDocsAgentDiscoverySpec, buildDocsSearchDocuments, buildPageOpenGraph, buildPageTwitter, createAlgoliaSearchAdapter, createCustomSearchAdapter, createMcpSearchAdapter, createSimpleSearchAdapter, createTheme, createTypesenseSearchAdapter, deepMerge, defineDocs, extendTheme, findDocsMarkdownPage, isDocsAgentDiscoveryRequest, isDocsMcpRequest, isDocsPublicGetRequest, normalizeDocsPathSegment, normalizeDocsRelated, normalizeDocsUrlPath, performDocsSearch, renderDocsMarkdownDocument, renderDocsRelatedMarkdownLines, resolveChangelogConfig, resolveDocsAgentMdxContent, resolveDocsI18n, resolveDocsLlmsTxtFormat, resolveDocsLocale, resolveDocsMarkdownRequest, resolveDocsPath, resolveOGImage, resolveSearchRequestConfig, resolveTitle };
+export { DEFAULT_AGENT_FEEDBACK_ROUTE, DEFAULT_AGENT_SPEC_ROUTE, DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, DEFAULT_DOCS_API_ROUTE, DEFAULT_LLMS_FULL_TXT_ROUTE, DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE, DEFAULT_LLMS_TXT_ROUTE, DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE, DEFAULT_MCP_PUBLIC_ROUTE, DEFAULT_MCP_ROUTE, DEFAULT_MCP_WELL_KNOWN_ROUTE, DEFAULT_SKILL_MD_ROUTE, DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, buildDocsAgentDiscoverySpec, buildDocsSearchDocuments, buildPageOpenGraph, buildPageTwitter, createAlgoliaSearchAdapter, createCustomSearchAdapter, createMcpSearchAdapter, createSimpleSearchAdapter, createTheme, createTypesenseSearchAdapter, deepMerge, defineDocs, extendTheme, findDocsMarkdownPage, isDocsAgentDiscoveryRequest, isDocsMcpRequest, isDocsPublicGetRequest, isDocsSkillRequest, normalizeDocsPathSegment, normalizeDocsRelated, normalizeDocsUrlPath, performDocsSearch, renderDocsMarkdownDocument, renderDocsRelatedMarkdownLines, renderDocsSkillDocument, resolveChangelogConfig, resolveDocsAgentMdxContent, resolveDocsI18n, resolveDocsLlmsTxtFormat, resolveDocsLocale, resolveDocsMarkdownRequest, resolveDocsPath, resolveOGImage, resolveSearchRequestConfig, resolveTitle };

package/dist/{init-i5ySLGa2.mjs → init-DHlRFytW.mjs}

@@ -1257,7 +1257,7 @@ import { createDocsServer } from "@farming-labs/svelte/server";
 import config from "${svelteServerConfigImport(cfg.useAlias)}";
 
 // preload for production
-const contentFiles = import.meta.glob("/${cfg.entry ?? "docs"}/**/*.{md,mdx,svx}", {
+const contentFiles = import.meta.glob(["/${cfg.entry ?? "docs"}/**/*.{md,mdx,svx}", "/skill.md"], {
   query: "?raw",
   import: "default",
   eager: true,
@@ -1661,7 +1661,7 @@ function astroDocsServerTemplate(cfg) {
 import { createDocsServer } from "@farming-labs/astro/server";
 import config from "${astroServerConfigImport(cfg.useAlias)}";
 
-const contentFiles = import.meta.glob("/${cfg.entry ?? "docs"}/**/*.{md,mdx}", {
+const contentFiles = import.meta.glob(["/${cfg.entry ?? "docs"}/**/*.{md,mdx}", "/skill.md"], {
   query: "?raw",
   import: "default",
   eager: true,

package/package.json

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