blume 2.0.2 → 2.1.0

package/src/ai/site-skill.ts

@@ -0,0 +1,274 @@
+import { hasGeneratedChangelog } from "../astro/pages.ts";
+import {
+  mountBasePath,
+  normalizeBasePath,
+  withBasePath,
+} from "../core/base-path.ts";
+import { CHANGELOG_INDEX_ROUTE } from "../core/changelog-index.ts";
+import { discoverPagesSync } from "../core/custom-pages.ts";
+import type { BlumeProject } from "../core/project-graph.ts";
+import { absoluteUrl } from "../core/site-url.ts";
+import type { NavNode, PageRecord } from "../core/types.ts";
+import { resolveReferences } from "../openapi/references.ts";
+import { docsPhrase } from "./ai-catalog.ts";
+import { API_PAGES_PATH } from "./api/paths.ts";
+import { asciiSlugify } from "./mcp/discovery.ts";
+import {
+  SKILL_DESCRIPTION_MAX,
+  generatesSiteSkill,
+  skillMdArtifact,
+} from "./skills.ts";
+import type { SkillArtifact } from "./skills.ts";
+
+/**
+ * The site's own agent skill (`agents.skillMd`): a `SKILL.md` in the Agent
+ * Skills format, built from what the build already knows — the site's title
+ * and description, how to read any page as Markdown, llms.txt and the MCP
+ * server, the API references, and a map of the docs with each page's one-line
+ * description. No model writes it, so it costs nothing and is current with
+ * every build: a guide to the docs rather than a summary of the product. A
+ * hand-written skill of the same name in `agents.skills` replaces it.
+ */
+
+/** The most pages the map lists; llms.txt holds the rest. */
+export const MAX_SKILL_PAGES = 200;
+
+/** The Agent Skills spec caps a skill name at 64 characters. */
+const NAME_MAX = 64;
+
+/** Where the site skill is served besides the discovery index. */
+export const SKILL_MD_PATH = "/skill.md";
+
+/**
+ * The site skill's name: the title as a skill name (lowercase alphanumerics
+ * and single hyphens), else the site's host, for a title with no Latin
+ * letters in it.
+ */
+export const siteSkillName = (project: BlumeProject): string => {
+  const { site } = project.config.deployment.options;
+  const fromTitle = asciiSlugify(project.config.title);
+  const name =
+    fromTitle || asciiSlugify(site ? new URL(site).hostname : "") || "docs";
+  return name.slice(0, NAME_MAX).replace(/-+$/u, "");
+};
+
+/** A title as Markdown link text (brackets escaped, as in llms.txt). */
+const linkText = (title: string): string =>
+  title.replaceAll(/[\\[\]]/gu, String.raw`\$&`);
+
+/**
+ * Current-version, default-locale pages worth listing: not API operations,
+ * and not changelog entries, which the changelog index covers in one line.
+ */
+const mappedPages = (project: BlumeProject): PageRecord[] => {
+  const defaultLocale = project.config.i18n?.defaultLocale;
+  return project.graph.pages.filter(
+    (page) =>
+      !(
+        page.meta.ai.exclude ||
+        page.meta.draft ||
+        page.meta.sidebar.hidden ||
+        page.meta.seo.noindex ||
+        page.version !== "" ||
+        page.source.name === "openapi" ||
+        page.contentType === "changelog"
+      ) &&
+      (defaultLocale === undefined || page.locale === defaultLocale)
+  );
+};
+
+/** Renders the page map, listing each page once, up to the cap. */
+class PageMap {
+  readonly #byRoute: Map<string, PageRecord>;
+  readonly #listed = new Set<string>();
+  readonly #url: (route: string) => string;
+
+  constructor(pages: PageRecord[], url: (route: string) => string) {
+    this.#byRoute = new Map(pages.map((page) => [page.route, page]));
+    this.#url = url;
+  }
+
+  /** How many listable pages the cap left out. */
+  get omitted(): number {
+    return this.#byRoute.size - this.#listed.size;
+  }
+
+  /** The Markdown link line for a route, or nothing when it isn't listed. */
+  line(route: string): string[] {
+    const page = this.#byRoute.get(route);
+    if (
+      !page ||
+      this.#listed.has(route) ||
+      this.#listed.size >= MAX_SKILL_PAGES
+    ) {
+      return [];
+    }
+    this.#listed.add(route);
+    const summary = page.description ? `: ${page.description}` : "";
+    return [`- [${linkText(page.title)}](${this.#url(route)})${summary}`];
+  }
+
+  /** One navigation level: its loose pages, then each group under a heading. */
+  level(nodes: NavNode[], depth: number): string[] {
+    const list: string[] = [];
+    const groups: string[] = [];
+    for (const node of nodes) {
+      if (node.kind === "page") {
+        list.push(...this.line(node.route));
+        continue;
+      }
+      const blocks = [
+        ...(node.route ? this.line(node.route) : []),
+        ...this.level(node.children, depth + 1),
+      ];
+      if (blocks.length > 0) {
+        groups.push(
+          "",
+          `${"#".repeat(Math.min(depth, 6))} ${node.label}`,
+          "",
+          ...blocks
+        );
+      }
+    }
+    return [...list, ...groups];
+  }
+
+  /** Pages the navigation doesn't reach, in route order. */
+  rest(): string[] {
+    return [...this.#byRoute.keys()]
+      .toSorted((a, b) => a.localeCompare(b))
+      .flatMap((route) => this.line(route));
+  }
+}
+
+/** The "Reading the docs" bullets: every agent surface the site serves. */
+const surfaceLines = (
+  project: BlumeProject,
+  url: (path: string) => string
+): string[] => {
+  const { agents } = project.config;
+  const lines = [
+    `- Any page as Markdown: add \`.md\` to its URL (the home page is ${url("/index.md")}). Every page link below already points at the Markdown.`,
+  ];
+  if (agents.llmsTxt.enabled) {
+    lines.push(
+      `- [llms.txt](${url("/llms.txt")}): every page with a one-line summary.`,
+      `- [llms-full.txt](${url("/llms-full.txt")}): every page in one file, for when you need all of it.`
+    );
+  }
+  if (agents.mcp.enabled) {
+    lines.push(
+      `- MCP server at ${url(agents.mcp.route)}, with \`search_docs\`, \`get_page\`, \`list_pages\`, and \`get_navigation\`. Connect it to search the docs instead of guessing URLs.`
+    );
+  }
+  if (agents.api) {
+    lines.push(
+      `- [JSON API](${url(API_PAGES_PATH)}): the page index, with each page as JSON and Markdown.`
+    );
+  }
+  const userPages = project.context.pagesRoot
+    ? discoverPagesSync(project.context.pagesRoot)
+    : [];
+  if (hasGeneratedChangelog(project, userPages)) {
+    lines.push(
+      `- [Changelog](${url(`${CHANGELOG_INDEX_ROUTE}.md`)}): release notes, newest first.`
+    );
+  }
+  return lines;
+};
+
+/** The "API reference" bullets, one per rendered reference. */
+const referenceLines = (
+  project: BlumeProject,
+  url: (path: string) => string
+): string[] =>
+  resolveReferences(project.config).map((reference) => {
+    // Scalar renders its own page with no Markdown mirror; Blume-rendered
+    // references are pages like any other, one per operation.
+    const route =
+      reference.kind === "scalar"
+        ? reference.route
+        : withBasePath(reference.basePath, reference.route);
+    const pages =
+      reference.kind === "scalar"
+        ? ""
+        : ", with a page per operation (add `.md` for its Markdown)";
+    return `- [${linkText(reference.label)}](${url(route)})${pages}.`;
+  });
+
+/** The skill's frontmatter `description`: what it's for and when to use it. */
+const skillDescription = (project: BlumeProject): string => {
+  const { description, title } = project.config;
+  const summary = description ? ` ${description.trim()}` : "";
+  return `Read ${docsPhrase(title, "docs")} instead of answering from memory.${summary} Use when a task involves ${title}: how it works, how to set it up or configure it, or its API.`.slice(
+    0,
+    SKILL_DESCRIPTION_MAX
+  );
+};
+
+/** The site skill's `SKILL.md`. */
+const skillMarkdown = (project: BlumeProject, name: string): string => {
+  const { config } = project;
+  const { site = "" } = config.deployment.options;
+  const base = normalizeBasePath(config.deployment.options.base);
+  // Mounted and encoded like llms.txt's links.
+  const url = (path: string): string =>
+    encodeURI(absoluteUrl(site, mountBasePath(base, path)));
+  const markdownUrl = (route: string): string =>
+    url(route === "/" ? "/index.md" : `${route}.md`);
+
+  const map = new PageMap(mappedPages(project), markdownUrl);
+  const pages = [
+    ...map.level(project.graph.navigation.sidebar, 3),
+    ...map.rest(),
+  ];
+  const { omitted } = map;
+  if (omitted > 0) {
+    pages.push(
+      "",
+      config.agents.llmsTxt.enabled
+        ? `…and ${omitted} more. [llms.txt](${url("/llms.txt")}) lists every page.`
+        : `…and ${omitted} more.`
+    );
+  }
+  const references = referenceLines(project, url);
+
+  return [
+    "---",
+    `name: ${name}`,
+    `description: ${JSON.stringify(skillDescription(project))}`,
+    "---",
+    "",
+    `# ${config.title}`,
+    "",
+    ...(config.description ? [config.description.trim(), ""] : []),
+    `This skill points you at ${docsPhrase(config.title, "docs")}, at ${url("/")}. When a task involves ${config.title}, read the relevant page before relying on what you remember: the docs are the source of truth, and they change.`,
+    "",
+    "## Reading the docs",
+    "",
+    ...surfaceLines(project, url),
+    ...(references.length > 0
+      ? ["", "## API reference", "", ...references]
+      : []),
+    ...(pages.length > 0 ? ["", "## Pages", "", ...pages] : []),
+    "",
+  ]
+    .join("\n")
+    .replaceAll(/\n{3,}/gu, "\n\n");
+};
+
+/**
+ * The generated site skill, or `null` when `agents.skillMd` is off or there
+ * is no `deployment.site` to make its links absolute.
+ */
+export const buildSiteSkill = (project: BlumeProject): SkillArtifact | null => {
+  if (!generatesSiteSkill(project.config)) {
+    return null;
+  }
+  const name = siteSkillName(project);
+  return skillMdArtifact(
+    name,
+    skillDescription(project),
+    skillMarkdown(project, name)
+  );
+};

package/src/ai/skills.ts

@@ -29,7 +29,7 @@ const AGENT_SKILLS_SCHEMA =
 const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
 const SKILL_NAME_MAX = 64;
 /** The Agent Skills spec caps `description` at 1024 characters. */
-const DESCRIPTION_MAX = 1024;
+export const SKILL_DESCRIPTION_MAX = 1024;
 
 /** One publishable skill artifact plus its index entry. */
 export interface SkillArtifact {
@@ -142,7 +142,7 @@ const skillMeta = (raw: string, dirName: string): SkillMetaResult => {
     };
   }
   return {
-    meta: { description: description.slice(0, DESCRIPTION_MAX), name },
+    meta: { description: description.slice(0, SKILL_DESCRIPTION_MAX), name },
   };
 };
 
@@ -151,11 +151,16 @@ const skillMeta = (raw: string, dirName: string): SkillMetaResult => {
  * hold a `SKILL.md` (the layout `npx skills add` consumes). Subdirectories
  * without one are ignored silently — the directory may hold other assets —
  * while a present-but-invalid skill earns a warning so it isn't dropped
- * behind the publisher's back.
+ * behind the publisher's back. Two directories declaring the same `name`
+ * would publish to the same artifact path under two index entries, so the
+ * first directory in sorted order keeps the name and the other is skipped
+ * with a warning naming both.
  */
 export const collectSkills = async (dir: string): Promise<CollectedSkills> => {
   const skills: SkillArtifact[] = [];
   const warnings: string[] = [];
+  /** Skill name → the directory that claimed it first. */
+  const owners = new Map<string, string>();
   const items = await readdir(dir, { withFileTypes: true });
   for (const item of items.toSorted((a, b) => (a.name < b.name ? -1 : 1))) {
     if (!item.isDirectory() || item.name.startsWith(".")) {
@@ -177,6 +182,14 @@ export const collectSkills = async (dir: string): Promise<CollectedSkills> => {
       }
       continue;
     }
+    const owner = owners.get(meta.name);
+    if (owner) {
+      warnings.push(
+        `Skills "${owner}" and "${item.name}" both declare the name "${meta.name}"; publishing "${owner}" and skipping "${item.name}".`
+      );
+      continue;
+    }
+    owners.set(meta.name, item.name);
     // A lone SKILL.md ships verbatim; supporting resources ship as an
     // archive so the skill's relative references resolve after unpacking.
     const single = entries.length === 1;
@@ -193,6 +206,39 @@ export const collectSkills = async (dir: string): Promise<CollectedSkills> => {
   return { skills, warnings };
 };
 
+/** A skill that is one `SKILL.md`, published verbatim. */
+export const skillMdArtifact = (
+  name: string,
+  description: string,
+  markdown: string
+): SkillArtifact => {
+  const content = new TextEncoder().encode(markdown);
+  return {
+    content,
+    description: description.slice(0, SKILL_DESCRIPTION_MAX),
+    digest: sha256(content),
+    name,
+    path: `${name}/SKILL.md`,
+    type: "skill-md",
+  };
+};
+
+/**
+ * Whether the build generates the site's own skill (`agents.skillMd`): on,
+ * and with a `deployment.site` to make its links absolute, since an installed
+ * skill is read away from the site.
+ */
+export const generatesSiteSkill = (config: ResolvedConfig): boolean =>
+  config.agents.skillMd && Boolean(config.deployment.options.site);
+
+/**
+ * Whether a skills discovery index is served: from `agents.skills`, or for
+ * the generated site skill alone. On an advertised config (see
+ * `advertisedConfig`), both are already switched off when nothing published.
+ */
+export const servesSkillsIndex = (config: ResolvedConfig): boolean =>
+  Boolean(config.agents.skills) || generatesSiteSkill(config);
+
 /**
  * The discovery index (v0.2.0 schema). Artifact URLs are path-absolute under
  * `deployment.base` — the RFC resolves them against the index origin.

package/src/ai/tar.ts

@@ -22,42 +22,169 @@ export interface TarEntry {
   path: string;
 }
 
-/** ustar `name` field capacity; skill layouts are shallow, so no `prefix`. */
+/** ustar `name` field capacity. */
 const NAME_MAX = 100;
+/** ustar `prefix` field capacity; `prefix/name` reaches 255 bytes. */
+const PREFIX_MAX = 155;
+
+/** ustar header byte offsets nanotar leaves for us to patch. */
+const CHECKSUM_OFFSET = 148;
+const CHECKSUM_SIZE = 8;
+const TYPEFLAG_OFFSET = 156;
+const PREFIX_OFFSET = 345;
+const BLOCK_SIZE = 512;
+
+/** The two zero blocks that mark the end of an archive. */
+const END_OF_ARCHIVE = 2 * BLOCK_SIZE;
+/** tar's default record size (20 blocks), which the archive is padded to. */
+const RECORD_SIZE = 20 * BLOCK_SIZE;
+
+/** The PAX extended-header typeflag (`x`). */
+const PAX_TYPEFLAG = 0x78;
 
 const encoder = new TextEncoder();
 
+const byteLength = (value: string): number => encoder.encode(value).byteLength;
+
+/** `value` cut to at most `max` UTF-8 bytes, on a character boundary. */
+const truncateBytes = (value: string, max: number): string =>
+  value.slice(0, encoder.encodeInto(value, new Uint8Array(max)).read);
+
+/** One header nanotar writes, plus the fields it cannot. */
+interface Block {
+  content: Uint8Array;
+  mode: string;
+  name: string;
+  /** The PAX extended header ahead of an over-long path. */
+  pax?: boolean;
+  /** ustar `prefix`, joined to `name` with a `/` by readers. */
+  prefix?: string;
+}
+
+/**
+ * Split a path over the `name` field at a `/` so the head fits `prefix` and
+ * the tail fits `name`. The longest head that fits leaves the shortest tail,
+ * so if that tail is still too long no split works.
+ */
+const splitUstar = (
+  path: string
+): { name: string; prefix: string } | undefined => {
+  let slash = path.lastIndexOf("/");
+  while (slash > 0 && byteLength(path.slice(0, slash)) > PREFIX_MAX) {
+    slash = path.lastIndexOf("/", slash - 1);
+  }
+  const name = path.slice(slash + 1);
+  if (slash <= 0 || byteLength(name) > NAME_MAX) {
+    return undefined;
+  }
+  return { name, prefix: path.slice(0, slash) };
+};
+
+/**
+ * A PAX `path` record: `"<length> path=<value>\n"`, where the decimal length
+ * counts the whole record including its own digits.
+ */
+const paxPathRecord = (path: string): Uint8Array => {
+  const body = ` path=${path}\n`;
+  const size = byteLength(body);
+  const length = size + String(size + String(size).length).length;
+  return encoder.encode(`${length}${body}`);
+};
+
+/**
+ * The header blocks for one entry. A path that fits `name` is written as is;
+ * up to 255 bytes it splits across `prefix` and `name`; beyond that (or with
+ * no usable split) a PAX extended header carries the full path and the ustar
+ * `name` holds a truncated fallback for readers that ignore PAX.
+ */
+const entryBlocks = (entry: TarEntry): Block[] => {
+  const mode = entry.executable ? "755" : "644";
+  const file = { content: entry.content, mode };
+  if (byteLength(entry.path) <= NAME_MAX) {
+    return [{ ...file, name: entry.path }];
+  }
+  const split = splitUstar(entry.path);
+  if (split) {
+    return [{ ...file, ...split }];
+  }
+  const base = entry.path.slice(entry.path.lastIndexOf("/") + 1);
+  return [
+    {
+      content: paxPathRecord(entry.path),
+      mode: "644",
+      name: truncateBytes(`PaxHeader/${base}`, NAME_MAX),
+      pax: true,
+    },
+    { ...file, name: truncateBytes(base, NAME_MAX) },
+  ];
+};
+
+/** Recompute a patched header's checksum (nanotar's octal format). */
+const writeChecksum = (header: Uint8Array): void => {
+  header.fill(0x20, CHECKSUM_OFFSET, CHECKSUM_OFFSET + CHECKSUM_SIZE);
+  const sum = header.reduce((total, byte) => total + byte, 0);
+  header.fill(0, CHECKSUM_OFFSET, CHECKSUM_OFFSET + CHECKSUM_SIZE);
+  encoder.encodeInto(
+    sum.toString(8),
+    header.subarray(CHECKSUM_OFFSET, CHECKSUM_OFFSET + CHECKSUM_SIZE)
+  );
+};
+
 /**
  * Build a gzipped ustar archive of the given files, in the given order. Paths
- * longer than the ustar `name` field or escaping the archive root throw to
- * surface a programming error — nanotar would silently truncate an oversized
- * name into a corrupt archive, so the validation stays here.
+ * escaping the archive root throw to surface a programming error.
  */
 export const buildTarGz = (entries: readonly TarEntry[]): Uint8Array => {
   for (const entry of entries) {
-    if (encoder.encode(entry.path).byteLength > NAME_MAX) {
-      throw new Error(`tar path exceeds ${NAME_MAX} bytes: ${entry.path}`);
-    }
     if (entry.path.startsWith("/") || entry.path.split("/").includes("..")) {
       throw new Error(`tar path must be archive-relative: ${entry.path}`);
     }
   }
+  const blocks = entries.flatMap(entryBlocks);
   const tar = createTar(
-    entries.map((entry) => ({
+    blocks.map((block) => ({
       // Root-owned, epoch-mtime, empty owner names: every field a rebuild
       // could vary is pinned so the archive bytes are a function of content.
       attrs: {
         gid: 0,
         group: "",
-        mode: entry.executable ? "755" : "644",
+        mode: block.mode,
         mtime: 0,
         uid: 0,
         user: "",
       },
-      data: entry.content,
-      name: entry.path,
+      data: block.content,
+      name: block.name,
     }))
   );
+  // nanotar writes neither `prefix` nor the PAX typeflag, so patch those
+  // headers in place and re-sum them.
+  let offset = 0;
+  for (const block of blocks) {
+    const header = tar.subarray(offset, offset + BLOCK_SIZE);
+    if (block.prefix) {
+      encoder.encodeInto(
+        block.prefix,
+        header.subarray(PREFIX_OFFSET, PREFIX_OFFSET + PREFIX_MAX)
+      );
+      writeChecksum(header);
+    }
+    if (block.pax) {
+      header[TYPEFLAG_OFFSET] = PAX_TYPEFLAG;
+      writeChecksum(header);
+    }
+    offset +=
+      BLOCK_SIZE * (1 + Math.ceil(block.content.byteLength / BLOCK_SIZE));
+  }
+  // nanotar pads the entries to a whole record but writes no end-of-archive
+  // marker, so entries ending within two blocks of a record boundary leave
+  // fewer than the two zero blocks readers expect (GNU tar warns "A lone zero
+  // block"). Pad to the first record that fits both; for every other archive
+  // that is the size nanotar already wrote, so its bytes are unchanged.
+  const archive = new Uint8Array(
+    Math.ceil((offset + END_OF_ARCHIVE) / RECORD_SIZE) * RECORD_SIZE
+  );
+  archive.set(tar.subarray(0, offset));
   // Sync gzip with a pinned level; Node writes no timestamp into the header.
-  return new Uint8Array(gzipSync(tar, { level: 9 }));
+  return new Uint8Array(gzipSync(archive, { level: 9 }));
 };

package/src/ai/write-skill.ts

@@ -0,0 +1,97 @@
+import { existsSync } from "node:fs";
+
+import { join, relative, resolve } from "pathe";
+
+import type { BlumeProject } from "../core/project-graph.ts";
+import { siteSkillName } from "./site-skill.ts";
+
+/**
+ * `blume skill`'s logic, kept out of the command module so it runs (and is
+ * covered) in-process. Writing a product skill is judgment work — what the
+ * product is, which tasks matter, where it bites — so it lives in the
+ * `blume-write-skill` skill, shipped inside the package. This module only
+ * works out where the skill goes and writes the prompt that points a coding
+ * agent at the skill and the docs.
+ */
+
+/** The skill's directory inside the published package. */
+export const WRITE_SKILL_DIR = join("skills", "blume-write-skill");
+
+/** Where `agents.skills` points when the config doesn't set it. */
+const DEFAULT_SKILLS_DIR = "skills";
+
+/** Where the skill goes, and what the agent needs to know to write it. */
+export interface SkillPlan {
+  /** The `agents.skills` value to add, when the config has none. */
+  configure?: string;
+  /** The config file to add it to, relative to the project root. */
+  configFile: string;
+  /** The content root, relative to the project root. */
+  contentRoot: string;
+  /** Whether a skill is already there to update. */
+  exists: boolean;
+  /** Where to write the skill, relative to the project root. */
+  file: string;
+  /** The skill's name: the generated site skill's, so it replaces it. */
+  name: string;
+  /** The site's URL, for the skill's absolute links. */
+  site?: string;
+  title: string;
+}
+
+/** Plan the skill for a scanned project. */
+export const planSkill = (project: BlumeProject): SkillPlan => {
+  const { config, context } = project;
+  const name = siteSkillName(project);
+  const file = resolve(
+    context.root,
+    config.agents.skills ?? DEFAULT_SKILLS_DIR,
+    name,
+    "SKILL.md"
+  );
+  const plan: SkillPlan = {
+    configFile: context.configFile
+      ? relative(context.root, context.configFile)
+      : "blume.config.ts",
+    contentRoot: relative(context.root, context.contentRoot) || ".",
+    exists: existsSync(file),
+    file: relative(context.root, file),
+    name,
+    site: config.deployment.options.site,
+    title: config.title,
+  };
+  return config.agents.skills
+    ? plan
+    : { ...plan, configure: `./${DEFAULT_SKILLS_DIR}` };
+};
+
+/** The prompt that hands the plan to a coding agent. */
+export const writeSkillPrompt = (
+  plan: SkillPlan,
+  options: { skillDir: string; version: string }
+): string => {
+  const { skillDir, version } = options;
+  const lines = [
+    `Write the agent skill for the ${plan.title} docs, a Blume ${version} site.`,
+    "",
+    `Follow the blume-write-skill skill: read ${join(skillDir, "SKILL.md")} first and work through its workflow.`,
+    "",
+    plan.exists
+      ? `A skill already exists at ${plan.file}. Update it against the current docs rather than starting over, and keep what's still true.`
+      : `Write it to ${plan.file}.`,
+    `Its frontmatter \`name\` must be \`${plan.name}\`: that's the name of the skill Blume generates for this site, and a skill with the same name replaces it.`,
+  ];
+  if (plan.configure) {
+    lines.push(
+      `Then set \`agents.skills: "${plan.configure}"\` in ${plan.configFile} so the build publishes it.`
+    );
+  }
+  lines.push(
+    "",
+    `The docs source is in ${plan.contentRoot}.`,
+    plan.site
+      ? `The site is served at ${plan.site}, so link pages as ${plan.site.replace(/\/$/u, "")}<route>.md.`
+      : `The config has no \`deployment.site\`, and the skill's links must be absolute. Ask me for the site's URL, and set it as \`deployment.site\` in ${plan.configFile}.`
+  );
+  return lines.join("\n");
+};

package/src/analytics/head.ts

@@ -12,6 +12,7 @@ import { hightouchHead } from "./hightouch.ts";
 import { hotjarHead } from "./hotjar.ts";
 import { logrocketHead } from "./logrocket.ts";
 import { mixpanelHead } from "./mixpanel.ts";
+import { oneDollarStatsHead } from "./one-dollar-stats.ts";
 import { pirschHead } from "./pirsch.ts";
 import { plausibleHead } from "./plausible.ts";
 import { posthogHead } from "./posthog.ts";
@@ -92,6 +93,9 @@ const adapterScripts = (
     case "mixpanel": {
       return mixpanelHead(adapter.options);
     }
+    case "one-dollar-stats": {
+      return oneDollarStatsHead(adapter.options);
+    }
     case "pirsch": {
       return pirschHead(adapter.options);
     }

package/src/analytics/index.ts

@@ -58,6 +58,11 @@ export type {
   MixpanelOptions,
   MixpanelRegion,
 } from "./mixpanel.ts";
+export { oneDollarStats } from "./one-dollar-stats.ts";
+export type {
+  OneDollarStatsAdapter,
+  OneDollarStatsOptions,
+} from "./one-dollar-stats.ts";
 export { pirsch } from "./pirsch.ts";
 export type { PirschAdapter, PirschOptions } from "./pirsch.ts";
 export { plausible } from "./plausible.ts";