blume 2.0.2 → 2.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "The open-source docs framework for humans and agents.",
   "keywords": [
     "agents",

package/skills/blume-migrate/references/fumadocs.md

@@ -92,7 +92,7 @@ Trailing heading markers — `[#custom-id]` (pinned anchor), `[!toc]` (hide from
 
 ## i18n
 
-A `loader({ i18n })` setup (locale-suffixed files or locale dirs) → Blume `i18n: { defaultLocale, locales: [{ code, label }] }`. Locale **directories** match Blume's `dir` parser as-is; locale **file suffixes** (`page.cn.mdx`) need restructuring into locale folders. Report whichever transform you apply.
+A `loader({ i18n })` setup (locale-suffixed files or locale dirs) → Blume `i18n: { defaultLocale, locales: [{ code, label }] }`. Locale **directories** match Blume's default `dir` parser as-is; locale **file suffixes** (`page.cn.mdx` beside an unsuffixed default-locale `page.mdx`) match the `dot` parser as-is — add `parser: "dot"`, no file moves. Under `dot` a folder's `meta.ts` serves every locale, so build it from the default locale's `meta.json` and report any translated folder titles in `meta.<lang>.json`. Report whichever transform you apply.
 
 ## Package.json & teardown
 

package/skills/blume-migrate/references/nextra.md

@@ -64,7 +64,7 @@ Nextra enables math via `nextra({ latex: true })` (KaTeX or MathJax). In Blume,
 
 ## i18n
 
-- **v2/v3:** locale **file suffixes** (`index.en.mdx`, `index.zh.mdx`) + `i18n` in `next.config` → restructure into locale **folders** (default locale at the content root, others under `<code>/`), then `i18n: { defaultLocale, locales: [{ code, label }] }`.
+- **v2/v3:** locale **file suffixes** (`index.en.mdx`, `index.zh.mdx`) + `i18n` in `next.config` → match Blume's `dot` parser as-is, default-locale suffix included: `i18n: { defaultLocale, locales: [{ code, label }], parser: "dot" }`, no file moves. Page titles land in each file's own frontmatter, so they stay per-locale, but under `dot` a folder's `meta.ts` serves every locale — build it from the default locale's `_meta` and report translated folder titles from the other locales' `_meta` files.
 - **v4:** `content/<lang>/` dirs already match Blume's `dir` parser — map the locale list, no file moves.
 
 ## Package.json & teardown

package/skills/blume-migrate/scripts/mintlify-codemod.mjs

@@ -219,10 +219,15 @@ const topKey = (line) => {
   return { key: m.groups.key, value: (m.groups.rest ?? "").trim() };
 };
 
-// The line index range [start, endExclusive) of a top-level key's block.
+// The line index range [start, endExclusive) of a top-level key's block: its
+// indented lines plus any `- ` sequence items written flush at column 0,
+// which YAML also reads as the key's value (`keywords:` then `- one`).
 const blockRange = (fm, start) => {
   let end = start + 1;
-  while (end < fm.length && (fm[end] === "" || /^\s/u.test(fm[end]))) {
+  while (
+    end < fm.length &&
+    (fm[end] === "" || /^\s/u.test(fm[end]) || /^-(?:\s|$)/u.test(fm[end]))
+  ) {
     end += 1;
   }
   // Trim trailing blank lines back out so the gap before the next key survives.

package/src/ai/agent-readability.ts

@@ -1,4 +1,4 @@
-import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
 import { repoUrl } from "../core/github.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ContentSignalPolicy, ContentSignals } from "../core/schema.ts";
@@ -173,7 +173,7 @@ export const buildAgentReadability = (
   // `site`; concatenate rather than `new URL()` so the subpath is preserved.
   const deployBase = normalizeBasePath(config.deployment.options.base);
   const abs = (path: string): string => {
-    const based = withBasePath(deployBase, path);
+    const based = mountBasePath(deployBase, path);
     return site ? absoluteUrl(site, based) : based;
   };
 

package/src/ai/ai-catalog.ts

@@ -1,5 +1,9 @@
 import { apiNamePhrase } from "../core/api-name.ts";
-import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import {
+  mountBasePath,
+  normalizeBasePath,
+  withBasePath,
+} from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { absoluteUrl } from "../core/site-url.ts";
 import { resolveReferences } from "../openapi/references.ts";
@@ -227,7 +231,7 @@ export const buildAiCatalog = (
   }
   const deployBase = normalizeBasePath(config.deployment.options.base);
   const abs = (path: string): string =>
-    absoluteUrl(site, withBasePath(deployBase, path));
+    absoluteUrl(site, mountBasePath(deployBase, path));
   const host = publisherHost(site);
   const entries = entrySeeds(config, skills, abs).map((seed): CatalogEntry => {
     const entry: CatalogEntry = {

package/src/ai/api/handlers.ts

@@ -1,4 +1,4 @@
-import { withBasePath } from "../../core/base-path.ts";
+import { mountBasePath } from "../../core/base-path.ts";
 import { absoluteUrl } from "../../core/site-url.ts";
 import type { Navigation } from "../../core/types.ts";
 import type { McpData, McpRoute } from "../mcp/data.ts";
@@ -88,7 +88,7 @@ export const jsonResponse = (payload: ApiPayload, status = 200): Response =>
 
 /** The absolute (or root-relative) URL for a base-less path. */
 const siteUrl = (path: string, context: ApiSiteContext): string => {
-  const based = withBasePath(context.base, path);
+  const based = mountBasePath(context.base, path);
   return context.site ? absoluteUrl(context.site, based) : based;
 };
 

package/src/ai/api/spec.ts

@@ -1,5 +1,5 @@
 import { apiNamePhrase } from "../../core/api-name.ts";
-import { withBasePath } from "../../core/base-path.ts";
+import { mountBasePath } from "../../core/base-path.ts";
 import { absoluteUrl, siteRoot } from "../../core/site-url.ts";
 import {
   API_NAVIGATION_PATH,
@@ -688,7 +688,7 @@ export const buildApiSpec = (input: ApiSpecInput): ApiSpecDocument => {
   if (input.site) {
     document.externalDocs = {
       description: `${input.name} documentation`,
-      url: absoluteUrl(input.site, withBasePath(input.base, "/")),
+      url: absoluteUrl(input.site, mountBasePath(input.base, "/")),
     };
   }
   return document;

package/src/ai/api-catalog.ts

@@ -1,4 +1,8 @@
-import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import {
+  mountBasePath,
+  normalizeBasePath,
+  withBasePath,
+} from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { absoluteUrl } from "../core/site-url.ts";
 import { resolveReferences } from "../openapi/references.ts";
@@ -39,7 +43,7 @@ const linksetEntries = (config: ResolvedConfig): LinksetEntry[] => {
   const site = config.deployment.options.site ?? null;
   const deployBase = normalizeBasePath(config.deployment.options.base);
   const abs = (path: string): string => {
-    const based = withBasePath(deployBase, path);
+    const based = mountBasePath(deployBase, path);
     return site ? absoluteUrl(site, based) : based;
   };
 

package/src/ai/changelog-markdown.ts

@@ -1,4 +1,4 @@
-import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
 import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { absoluteUrl } from "../core/site-url.ts";
@@ -29,7 +29,7 @@ const parseDate = (value: string | undefined): Date | null => {
 /** A row's link: absolute under a configured site, like llms.txt. */
 const entryUrl = (project: BlumeProject, route: string): string => {
   const { base, site } = project.config.deployment.options;
-  const path = withBasePath(normalizeBasePath(base), route);
+  const path = mountBasePath(normalizeBasePath(base), route);
   return encodeURI(site ? absoluteUrl(site, path) : path);
 };
 

package/src/ai/link-headers.ts

@@ -33,24 +33,33 @@ import { OPENAPI_PATH } from "./api/paths.ts";
  * headers. Targets are
  * root-relative under `deployment.base` — RFC 8288 resolves them against the
  * request URL. Returns null when nothing is advertisable.
+ *
+ * `surface` is where the header is sent. A deployed site (`"build"`) serves
+ * every target. The dev server (`"dev"`) serves the routes — the JSON API's
+ * OpenAPI document and the Markdown mirror — but not the files `blume build`
+ * writes after the build (the API and AI catalogs, `agent-readability.json`,
+ * `llms.txt`), so its header leaves those out rather than point agents at
+ * 404s.
  */
 export const buildHomeLinkHeader = (
   config: ResolvedConfig,
-  routePaths: readonly string[]
+  routePaths: readonly string[],
+  surface: "build" | "dev" = "build"
 ): string | null => {
   const deployBase = normalizeBasePath(config.deployment.options.base);
+  const artifacts = surface === "build";
   const links: string[] = [];
   // RFC 9727 §3: the api-catalog relation is how a homepage advertises the
   // well-known catalog. Its type carries the RFC 9727 profile, whose quotes
   // are escaped inside the quoted `type` value (RFC 8288 quoted-string).
-  if (hasApiCatalog(config)) {
+  if (artifacts && hasApiCatalog(config)) {
     links.push(
       `<${deployBase}${API_CATALOG_PATH}>; rel="api-catalog"; type="${API_CATALOG_TYPE.replaceAll('"', String.raw`\"`)}"`
     );
   }
   // The ai-catalog spec's own relation for its well-known document, the
   // header form of the `<link rel="ai-catalog">` every page carries.
-  if (hasAiCatalog(config)) {
+  if (artifacts && hasAiCatalog(config)) {
     links.push(
       `<${deployBase}${AI_CATALOG_PATH}>; rel="ai-catalog"; type="${AI_CATALOG_TYPE}"`
     );
@@ -62,12 +71,12 @@ export const buildHomeLinkHeader = (
       `<${deployBase}${OPENAPI_PATH}>; rel="service-desc"; type="application/json"`
     );
   }
-  if (config.agents.agentReadability) {
+  if (artifacts && config.agents.agentReadability) {
     links.push(
       `<${deployBase}/agent-readability.json>; rel="describedby"; type="application/json"`
     );
   }
-  if (config.agents.llmsTxt.enabled) {
+  if (artifacts && config.agents.llmsTxt.enabled) {
     links.push(
       `<${deployBase}/llms.txt>; rel="describedby"; type="text/plain"`
     );

package/src/ai/llms.ts

@@ -1,4 +1,4 @@
-import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
 import { rewriteRelativeImages } from "../core/content-assets.ts";
 import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
@@ -17,14 +17,22 @@ import type { SkillArtifact } from "./skills.ts";
 import { applyAgentVisibility } from "./visibility.ts";
 
 // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top —
-// with or without a `site` (the mcp.json convention) — so the emitted URL
-// matches where the page is served. Encoded like the sitemap: a route with
-// spaces or non-ASCII must still yield a valid Markdown link.
+// with or without a `site` (the mcp.json convention), and even over a route
+// that starts with the base's own name — so the emitted URL matches where the
+// page is served. Encoded like the sitemap: a route with spaces or non-ASCII
+// must still yield a valid Markdown link.
 const pageUrl = (route: string, site?: string, base = ""): string => {
-  const path = withBasePath(base, route);
+  const path = mountBasePath(base, route);
   return encodeURI(site ? absoluteUrl(site, path) : path);
 };
 
+/**
+ * A title as Markdown link text. An unescaped bracket in it — `[Beta] Webhooks`
+ * — closes or nests the text early, and the line stops being a link.
+ */
+const linkText = (title: string): string =>
+  title.replaceAll(/[\\[\]]/gu, String.raw`\$&`);
+
 /** Inputs only the build has: the published skills, collected once per build. */
 export interface LlmsIndexOptions {
   /**
@@ -176,7 +184,7 @@ export const buildLlmsIndex = (
   const line = (page: PageRecord): string => {
     seen.add(page.route);
     const summary = page.description ? `: ${page.description}` : "";
-    return `- [${page.title}](${pageUrl(page.route, site, base)})${summary}`;
+    return `- [${linkText(page.title)}](${pageUrl(page.route, site, base)})${summary}`;
   };
 
   // One nav level -> Markdown blocks: the level's loose pages as a link list,
@@ -259,7 +267,10 @@ export const buildLlmsIndex = (
     blocks.push(
       "## RSS Feeds",
       feeds
-        .map((feed) => `- [${feed.title}](${pageUrl(feed.path, site, base)})`)
+        .map(
+          (feed) =>
+            `- [${linkText(feed.title)}](${pageUrl(feed.path, site, base)})`
+        )
         .join("\n")
     );
   }

package/src/ai/mcp/discovery.ts

@@ -1,4 +1,4 @@
-import { withBasePath } from "../../core/base-path.ts";
+import { mountBasePath } from "../../core/base-path.ts";
 import { absoluteUrl, siteRoot } from "../../core/site-url.ts";
 import { trimChar } from "../../core/trim.ts";
 import { MCP_TOOLS } from "./tools.ts";
@@ -18,7 +18,7 @@ export interface McpDiscoveryInput {
 const serverUrl = (input: McpDiscoveryInput): string => {
   // The endpoint is a generated Astro page, so it's served under
   // `deployment.base` like every other route (the sitemap/llms.txt convention).
-  const path = withBasePath(input.base, input.route);
+  const path = mountBasePath(input.base, input.route);
   // Concatenate rather than `new URL(path, site)` — a root-absolute path
   // would drop the base path of a subpath deployment (`acme.com/docs`).
   return input.site ? absoluteUrl(input.site, path) : path;

package/src/ai/mcp/query.ts

@@ -1,9 +1,9 @@
 import { z } from "zod";
 
 import {
+  mountBasePath,
   normalizeRoute as normalizePageRoute,
   stripBasePath,
-  withBasePath,
 } from "../../core/base-path.ts";
 import { absoluteUrl } from "../../core/site-url.ts";
 import { trimEnd } from "../../core/trim.ts";
@@ -244,7 +244,7 @@ export const normalizeRoute = (input: string, data: McpData): string => {
 export const urlFor = (route: string, data: McpData): string => {
   // Routes are base-less manifest paths; layer `deployment.base` on top so the
   // URL matches where the page is served (the sitemap/llms.txt convention).
-  const path = withBasePath(data.base, route);
+  const path = mountBasePath(data.base, route);
   // Concatenate rather than `new URL(path, site)` — a root-absolute path
   // would drop the base path of a subpath deployment (`acme.com/docs`).
   return data.site ? absoluteUrl(data.site, path) : path;

package/src/ai/mcp/server.ts

@@ -10,7 +10,7 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 
-import { withBasePath } from "../../core/base-path.ts";
+import { mountBasePath } from "../../core/base-path.ts";
 import { readCappedText } from "../../core/request-body.ts";
 import type { McpData } from "./data.ts";
 import {
@@ -104,7 +104,7 @@ interface PageResource {
 const resourceUri = (route: string, data: McpData): string =>
   data.site
     ? urlFor(route, data)
-    : `${LOCAL_RESOURCE_SCHEME}${withBasePath(data.base, route)}`;
+    : `${LOCAL_RESOURCE_SCHEME}${mountBasePath(data.base, route)}`;
 
 /** The `pages` key a resource URI (either form, or a bare route) names. */
 const resourceRoute = (uri: string, data: McpData): string =>

package/src/ai/openapi-components.ts

@@ -1,3 +1,4 @@
+import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
 import type { ApiOperationRef, OpenApiData } from "../openapi/model.ts";
 import { operationOf, specAddresses, specOf } from "../openapi/model.ts";
 import { asSentence } from "../openapi/sentence.ts";
@@ -20,10 +21,14 @@ const inlineText = (text: string): string =>
     .replaceAll(/\s+/gu, " ")
     .replaceAll(/[\\`*_[\]<>~]/gu, String.raw`\$&`);
 
-/** One operation as a link, for the tag listings. */
+/**
+ * One operation as a link, for the tag listings. `href` is the operation's
+ * served URL: its route under the deployment base.
+ */
 const listItem = (
   signature: string,
-  operation: Pick<ApiOperationRef, "deprecated" | "route" | "summary">
+  href: string,
+  operation: Pick<ApiOperationRef, "deprecated" | "summary">
 ): string => {
   const tail = [
     // Title-like summaries ("Get a flag") need their own period before the
@@ -33,7 +38,7 @@ const listItem = (
   ]
     .filter(Boolean)
     .join(" ");
-  return `- [${inlineCode(signature)}](${linkDestination(operation.route)})${tail ? ` — ${tail}` : ""}`;
+  return `- [${inlineCode(signature)}](${linkDestination(href)})${tail ? ` — ${tail}` : ""}`;
 };
 
 /**
@@ -60,9 +65,16 @@ const listItem = (
  * endpoint and what it does is the part that was missing altogether.
  *
  * `specs` is the parsed `blume:openapi` data — empty when the project has no
- * API reference, in which case every serializer declines.
+ * API reference, in which case every serializer declines. `deployBase` is the
+ * configured `deployment.base`: operation routes carry `basePath` but not it,
+ * and the links written here are made after the agent surfaces rebase the
+ * page's own links, so they take it here, as the rendered page's do.
  */
-export const openapiComponentSerializers = (specs: OpenApiData) => {
+export const openapiComponentSerializers = (
+  specs: OpenApiData,
+  deployBase?: string
+) => {
+  const base = normalizeBasePath(deployBase);
   const spec = (source: EvaluatedValue) =>
     isString(source) ? specOf(specs, source) : undefined;
 
@@ -97,7 +109,11 @@ export const openapiComponentSerializers = (specs: OpenApiData) => {
       const items = Object.values(data.operations)
         .filter((operation) => operation.tagSlug === tag)
         .map((operation) =>
-          listItem(operationSignature(data, operation), operation)
+          listItem(
+            operationSignature(data, operation),
+            mountBasePath(base, operation.route),
+            operation
+          )
         );
       return items.length > 0 ? items.join("\n") : null;
     },

package/src/ai/relative-links.ts

@@ -2,9 +2,10 @@ import { basename } from "pathe";
 
 import {
   isInternalPath,
+  mountBasePath,
   normalizeBasePath,
+  withAuthoredBasePath,
   withBasePath,
-  withComposedBasePath,
 } from "../core/base-path.ts";
 import { nextFenceState } from "../core/code-fences.ts";
 import type { FenceState } from "../core/code-fences.ts";
@@ -16,7 +17,7 @@ import {
   routeOfLinkedFile,
 } from "../core/links.ts";
 import type { RelativeLinkBase } from "../core/links.ts";
-import { localizeHref } from "../core/locale-links.ts";
+import { localizeHref, servesRoute } from "../core/locale-links.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { extractLinks } from "../core/sources/normalize.ts";
 
@@ -27,14 +28,16 @@ import { extractLinks } from "../core/sources/normalize.ts";
  * link lands on `/install`; the rendered page rewrites it to the route it
  * means (`markdown/relative-links.ts`), and the Markdown an agent reads gets
  * the same rewrite from the same resolver (`resolveRelativeHref`), so both
- * point at one page. Root-relative page links (`[x](/guide)`,
- * `<Card href="/guide">`) get what the rendered page gives them too: the
- * `deployment.base` + `basePath` prefix (`markdown/base-links.ts`,
- * `components/content/base-href.ts`) and, on a page in a prefixed locale,
+ * point at one page. Root-relative links (`[x](/guide)`,
+ * `<Card href="/guide">`, `![logo](/logo.png)`) get what the rendered page
+ * gives them too (`markdown/base-links.ts`,
+ * `components/content/base-href.ts`): a page link the `deployment.base` +
+ * `basePath` prefix, a public file (`/spec.pdf`) or image the
+ * `deployment.base` alone, and, on a page in a prefixed locale, a page link
  * that locale's copy of the route when it is served
- * (`components/layout/LocaleLinks.astro`). Inline links, component `href`s,
- * and reference definitions are rewritten; fenced and inline code, images,
- * asset links, and external URLs are left as written.
+ * (`components/layout/LocaleLinks.astro`). Inline links, images, component
+ * `href`s, and reference definitions are rewritten; fenced and inline code,
+ * relative images and asset links, and external URLs are left as written.
  */
 
 /** The page a Markdown text was written for. */
@@ -67,13 +70,6 @@ const MAYBE_RELATIVE =
 const MAYBE_PAGE_LINK =
   /\]\([\t ]*<?(?![a-z][\d+.a-z-]*:|\/\/|#)|^ {0,3}\[[^\]\n]+\]:[\t ]*<?(?![a-z][\d+.a-z-]*:|\/\/|#)|\shref=["'](?![a-z][\d+.a-z-]*:|\/\/|#)/imu;
 
-/**
- * A path whose final segment carries a file extension — a `public/` asset or
- * a raw `.md` twin, which the rendered page neither bases nor localizes (see
- * `markdown/base-links.ts`).
- */
-const ASSET_PATH = /\.[\da-z]+$/iu;
-
 interface Splice {
   column: number;
   length: number;
@@ -109,18 +105,23 @@ const definitionSplice = (
   return { column: lead.length + angled, length: target.length, text: route };
 };
 
-/** Every routed splice in `text`, by 0-based line: links, then definitions. */
+/**
+ * Every routed splice in `text`, by 0-based line: links and images, then
+ * definitions. An image target goes through `imaged`, everything else through
+ * `routed`.
+ */
 const collectSplices = (
   text: string,
   lines: readonly string[],
-  routed: (target: string) => string | undefined
+  routed: (target: string) => string | undefined,
+  imaged: (target: string) => string | undefined
 ): Map<number, Splice[]> => {
   const splices = new Map<number, Splice[]>();
   const add = (index: number, splice: Splice): void => {
     splices.set(index, [...(splices.get(index) ?? []), splice]);
   };
   for (const link of extractLinks(text)) {
-    const route = link.image ? undefined : routed(link.target);
+    const route = (link.image ? imaged : routed)(link.target);
     if (route !== undefined) {
       add(link.line - 1, {
         column: link.column - 1,
@@ -186,14 +187,19 @@ export const relativeLinkRewriter = (
     const navPath = navPathBySource.get(sourcePath) ?? basename(sourcePath);
     const resolveFile = (path: string): string | undefined =>
       routeOfLinkedFile(fileRoutes, { navPath, sourcePath }, path);
+    // A resolved route is one Blume serves, so the deployment base goes on
+    // unconditionally — even over a route that starts with the base's name.
     return (target) => {
       const route = resolveRelativeHref(target, from, resolveFile, (path) =>
         routes.has(path)
       );
-      return route === undefined ? undefined : withBasePath(deployBase, route);
+      return route === undefined ? undefined : mountBasePath(deployBase, route);
     };
   };
 
+  /** Whether a page is served at a based, fragment-less path. */
+  const servesPage = (route: string): boolean => servesRoute(routes, route);
+
   return (text, page) => {
     const locale = localeByRoute.get(page.route);
     // The page's locale moves root links only when it has a URL prefix.
@@ -212,21 +218,31 @@ export const relativeLinkRewriter = (
       return text;
     }
     const relative = relativeRoute(page);
-    // What the rendered page makes of `/guide`: based, then moved into the
+    // What the rendered page makes of `/guide`: based (a public file like
+    // `/spec.pdf` under the deployment base alone), then moved into the
     // page's locale when that route is served.
     const rooted = (target: string): string | undefined => {
-      if (ASSET_PATH.test(target.replace(/[#?].*$/u, ""))) {
-        return undefined;
-      }
-      const based = withComposedBasePath(deployBase, basePath, target);
+      const based = withAuthoredBasePath(
+        deployBase,
+        basePath,
+        target,
+        servesPage
+      );
       const href = localize ? localizeHref(based, localize) : based;
       return href === target ? undefined : href;
     };
     const routed = (target: string): string | undefined =>
       isInternalPath(target) ? rooted(target) : relative?.(target);
+    // An image is always a file: `public/` (or a generated asset endpoint),
+    // served under the deployment base but never `basePath`. A relative one
+    // is left to `core/content-assets.ts`.
+    const imaged = (target: string): string | undefined => {
+      const based = withBasePath(deployBase, target);
+      return based === target ? undefined : based;
+    };
 
     const lines = text.split("\n");
-    const splices = collectSplices(text, lines, routed);
+    const splices = collectSplices(text, lines, routed, imaged);
 
     return lines
       .map((line, index) => {

package/src/ai/serializers.ts

@@ -18,7 +18,8 @@ export const projectComponentSerializers = (
   ({
     ...exampleComponentSerializers(project.examples ?? {}),
     ...openapiComponentSerializers(
-      project.sources.find(isOpenApiSource)?.openApiData() ?? {}
+      project.sources.find(isOpenApiSource)?.openApiData() ?? {},
+      project.config.deployment.options.base
     ),
     ...project.config.agents.markdownComponents,
   }) satisfies Record<string, ComponentMarkdown>;

package/src/ai/skills.ts

@@ -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;