blume 1.4.1 → 1.4.3

package/src/components/layout/search/types.ts

@@ -84,6 +84,38 @@ export const highlight = (text: string, query: string): string => {
     .join("");
 };
 
+// Either a tag-shaped run — an opening `<` with a letter or `/` after it,
+// through the closing `>` (or end of string for an unterminated tag) — or a
+// lone `<`. A run can't span a later `<` (`[^<>]`), so between the two
+// alternatives every `<` in the input lands inside a captured run.
+const ANGLE_RUN = /(?<run><\/?[a-z][^<>]*>?|<)/iu;
+const BARE_MARK = /^<\/?mark>$/iu;
+
+/**
+ * Reduce provider-supplied excerpt markup to the `<mark>` highlighting the
+ * dialog expects. Remote excerpts (Pagefind's index, hosted engines) are
+ * rendered via `innerHTML`, so the output alphabet is pinned: bare
+ * `<mark>`/`</mark>` tags (attributes make even a mark untrusted), text, and
+ * entities. Tag-shaped runs are dropped; every other `<` is escaped, which
+ * renders identically but can't be parsed as markup (`<!--` would otherwise
+ * open a comment in `innerHTML` and swallow the rest of the excerpt). Split on
+ * runs covering every `<` rather than deleting tags in place: a deletion can
+ * splice the text around it into a fresh tag (`<<b>script>` → `<script>`),
+ * while here no `<` survives outside a run, so the only ones emitted are the
+ * bare mark tags. String-level on purpose: this also runs under DOM-less
+ * tests, where DOMPurify/DOMParser don't exist.
+ */
+export const sanitizeExcerpt = (html: string): string =>
+  html
+    .split(ANGLE_RUN)
+    .map((part, index) => {
+      if (index % 2 === 0 || BARE_MARK.test(part)) {
+        return part;
+      }
+      return part === "<" ? "&lt;" : "";
+    })
+    .join("");
+
 /** First index in `text` where any query token matches (case-insensitive). */
 const matchIndex = (text: string, query: string): number => {
   const tokens = queryTokens(query);

package/src/components/openapi/panel.ts

@@ -6,6 +6,8 @@
  * theme.
  */
 
+import { copyText, createCopyFlash } from "../copy-feedback.ts";
+
 class BlumePanelTabs extends HTMLElement {
   connectedCallback() {
     const tabs = [
@@ -36,18 +38,19 @@ class BlumePanelTabs extends HTMLElement {
     }
 
     if (copy) {
+      const flash = createCopyFlash((copied) => {
+        if (copied) {
+          copy.dataset.copied = "true";
+        } else {
+          delete copy.dataset.copied;
+        }
+      }, "Copied");
       copy.addEventListener("click", async () => {
         const active = panels.find(
           (panel) => !panel.classList.contains("hidden")
         );
-        try {
-          await navigator.clipboard.writeText(active?.textContent ?? "");
-          copy.dataset.copied = "true";
-          setTimeout(() => {
-            delete copy.dataset.copied;
-          }, 1500);
-        } catch {
-          // Clipboard unavailable (insecure context); silently ignore.
+        if (await copyText(active?.textContent ?? "")) {
+          flash();
         }
       });
     }

package/src/components/raf-throttle.ts

@@ -0,0 +1,21 @@
+/**
+ * Coalesce a high-frequency event handler (resize, scroll) into at most one
+ * call per animation frame — the toc-element scroll pattern, shared. Calls
+ * landing while a frame is pending are dropped; the handler runs once on the
+ * next frame with the latest state. Layout reads inside `fn` then happen once
+ * per frame instead of once per event, without the settle lag a debounce
+ * would add to position-tracking handlers.
+ */
+export const rafThrottle = (fn: () => void): (() => void) => {
+  let ticking = false;
+  return () => {
+    if (ticking) {
+      return;
+    }
+    ticking = true;
+    requestAnimationFrame(() => {
+      ticking = false;
+      fn();
+    });
+  };
+};

package/src/components/slug.ts

@@ -0,0 +1,14 @@
+import { slug } from "github-slugger";
+
+/**
+ * Slug a component's title into a DOM id (accordions, tabs, changelog
+ * updates), replacing three identical per-component copies. github-slugger —
+ * already what heading anchors use, both here and in Satteri's own
+ * heading-ids — so a component id slugs exactly like a heading with the same
+ * text (unicode letters kept, `user_id` keeps its underscore, `C#` keeps
+ * nothing extra dropped). Stateless on purpose: components render across many
+ * pages in one build process, so a stateful slugger would leak duplicate
+ * suffixes between pages — same-page duplicates are de-duplicated client-side
+ * by each component's own script.
+ */
+export const componentSlug = (value: string): string => slug(value);

package/src/core/base-path.ts

@@ -12,6 +12,8 @@
  * `components/islands/base-path.ts` and serves `deployment.base` via `BASE_URL`.
  */
 
+import { trimEnd } from "./trim.ts";
+
 /**
  * Canonicalize a configured base path to either `""` (none) or `/seg[/seg…]`
  * (leading slash, no trailing slash, collapsed inner slashes). A blank value or
@@ -33,10 +35,25 @@ export const normalizeBasePath = (input?: string): string => {
  * `/docs` and `/docs/` as the same page) and collapse an empty path to `/`.
  */
 export const normalizePath = (path: string): string => {
-  const trimmed = path.replace(/\/+$/u, "");
+  const trimmed = trimEnd(path, "/");
   return trimmed === "" ? "/" : trimmed;
 };
 
+/**
+ * Canonicalize a route-ish string (a configured route, a page path, an agent-
+ * supplied route) to `/` or `/seg[/seg…]`: trimmed, exactly one leading slash,
+ * no trailing slash. The shared spelling of what openapi/references,
+ * ai/ask-context, and ai/mcp/server each hand-rolled with slightly different
+ * regexes.
+ */
+export const normalizeRoute = (input: string): string => {
+  const trimmed = trimEnd(input.trim(), "/");
+  if (trimmed === "") {
+    return "/";
+  }
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+};
+
 /**
  * Whether a link target is a root-relative internal path (`/x`) — the only
  * shape a base path applies to. Protocol-relative (`//host`), absolute URLs,

package/src/core/config-input.ts

@@ -205,6 +205,8 @@ export interface SanitySource {
 /** A Notion database; pages become entries, blocks become MDX. */
 export interface NotionSource {
   type: "notion";
+  /** Max concurrent Notion API requests; default 3 (Notion's per-integration pace). */
+  concurrency?: number;
   /** Notion database id. */
   database: string;
   /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
@@ -653,6 +655,12 @@ export interface AskConfig {
    * limiting, and streaming. Accepts an absolute URL or root-relative path.
    */
   endpoint?: string;
+  /**
+   * Extra system-prompt text appended to the built-in instructions — use it
+   * for identity, language, or tone. The built-in grounding behavior (answer
+   * from the retrieved excerpts, cite pages as Markdown links) is preserved.
+   */
+  instructions?: string;
   /** Model id to use. Defaults to `openai/gpt-5.5`. */
   model?: string;
   /** Which backend routes the request. Defaults to `gateway`. */

package/src/core/data.ts

@@ -107,6 +107,13 @@ export interface BlumeDataConfig {
   /** `dateFormat`: `Intl.DateTimeFormat` options for the date stamps. */
   dateFormat: ResolvedConfig["dateFormat"];
   description: string | undefined;
+  /**
+   * Which agent-discovery resources exist for the layout to advertise in every
+   * page's `<head>` (`seo.agentReadability`, `ai.llmsTxt.enabled`) — the HTML
+   * counterpart of the homepage-only HTTP `Link` header, for agents that enter
+   * on a deep page (see `ai/link-headers.ts`).
+   */
+  discovery: { agentReadability: boolean; llmsTxt: boolean };
   favicon: BlumeFavicon;
   feedback: boolean;
   i18n: BlumeDataI18n | null;

package/src/core/frontmatter.ts

@@ -28,13 +28,57 @@ const withYamlEngine = <O>(options: O): O =>
     },
   }) as O;
 
+/**
+ * True when a document's leading `---` line is a CommonMark thematic break,
+ * not a front matter fence. Two shapes qualify (mirroring
+ * `linesWithoutFrontMatter` in `sources/normalize.ts`):
+ *   - the next line is blank (or absent) — YAML metadata starts on the very
+ *     next line, so a gap means the body *opens* with a divider (e.g. a
+ *     Notion page whose first block is one);
+ *   - no closing `---` line follows — gray-matter would swallow the whole
+ *     document as one unclosed YAML block and hand it to js-yaml, which
+ *     crashes on ordinary Markdown (`> quote` → "a line break is expected").
+ */
+const opensWithThematicBreak = (input: string): boolean => {
+  const [first = "", second] = input.split(/\r?\n/u, 2);
+  if (!/^-{3}\s*$/u.test(first)) {
+    return false;
+  }
+  if (second === undefined || second.trim() === "") {
+    return true;
+  }
+  // gray-matter closes the block at the next line-leading `---`; matching its
+  // search exactly keeps this guard from firing on any document it parses.
+  return !input.includes("\n---", 1);
+};
+
+/**
+ * The parse result for a document with no front matter: the input passes
+ * through as content, untouched. Shaped like gray-matter's own no-matter
+ * result (every Blume call site reads only `content` and `data`).
+ */
+const passthrough = (input: string): ReturnType<typeof baseMatter> =>
+  ({
+    content: input,
+    data: {},
+    excerpt: "",
+    isEmpty: false,
+    language: "",
+    matter: "",
+    orig: input,
+    // Recomposing a file with no matter and empty data is the content itself.
+    stringify: (): string => input,
+  }) as unknown as ReturnType<typeof baseMatter>;
+
 // Every helper that parses or emits YAML (`read`, `stringify`) must be
 // re-wrapped here — Object.assign copies gray-matter's own helpers, which use
 // its default `safeLoad` engine and would reintroduce the crash. `test` only
 // checks for a delimiter, so the copied original is safe.
 const matter = Object.assign(
   (input: MatterInput, options?: MatterOptions) =>
-    baseMatter(input, withYamlEngine(options)),
+    typeof input === "string" && opensWithThematicBreak(input)
+      ? passthrough(input)
+      : baseMatter(input, withYamlEngine(options)),
   baseMatter,
   {
     read: (filepath: ReadArgs[0], options?: ReadArgs[1]) =>

package/src/core/probe.ts

@@ -1,3 +1,5 @@
+import pMap from "p-map";
+
 import type { DiagnosticSeverity } from "./types.ts";
 
 export const PROBE_CONCURRENCY = 8;
@@ -113,24 +115,10 @@ export const probeAll = async (
   options: { concurrency?: number; timeoutMs?: number } = {}
 ): Promise<Map<string, ProbeResult>> => {
   const unique = [...new Set(urls)];
-  const results = new Map<string, ProbeResult>();
-  const limit = Math.min(
-    options.concurrency ?? PROBE_CONCURRENCY,
-    unique.length
+  const entries = await pMap(
+    unique,
+    async (url) => [url, await probe(url, options)] as const,
+    { concurrency: Math.max(1, options.concurrency ?? PROBE_CONCURRENCY) }
   );
-
-  let cursor = 0;
-  const worker = async (): Promise<void> => {
-    while (cursor < unique.length) {
-      const url = unique[cursor];
-      cursor += 1;
-      if (url !== undefined) {
-        // oxlint-disable-next-line no-await-in-loop -- bounded-concurrency pool
-        results.set(url, await probe(url, options));
-      }
-    }
-  };
-  await Promise.all(Array.from({ length: limit }, worker));
-
-  return results;
+  return new Map(entries);
 };

package/src/core/project-graph.ts

@@ -262,6 +262,17 @@ export const scanProject = async (
     discoverFolderMeta(metaSources, { localeDirs }),
   ]);
 
+  // Folder meta contributed by the sources themselves (the OpenAPI source
+  // labels each tag directory with the spec's own tag name). It applies to
+  // every locale, so it merges into the shared map — beneath user-authored
+  // entries, which are spread last and win.
+  const sharedFolderMeta = new Map([
+    ...loaded.flatMap(({ folderMeta: sourceMeta }) =>
+      Object.entries(sourceMeta ?? {})
+    ),
+    ...folderMeta.shared,
+  ]);
+
   const {
     diagnostics: contentDiagnostics,
     droppedPages,
@@ -301,7 +312,7 @@ export const scanProject = async (
     folderMeta: folderMeta.meta,
     i18n: config.i18n,
     navigation: config.navigation,
-    sharedFolderMeta: folderMeta.shared,
+    sharedFolderMeta,
   });
   const manifest = buildManifest({ config, context, graph });
 

package/src/core/schema.ts

@@ -304,6 +304,8 @@ const sanitySourceSchema = z.object({
 
 /** A Notion database; pages become entries, blocks become MDX. */
 const notionSourceSchema = z.object({
+  /** Max concurrent Notion API requests; default 3 (Notion's per-integration pace). */
+  concurrency: z.number().positive().optional(),
   database: z.string(),
   /** Opt-in dev polling interval (seconds); omit to freeze for the session. */
   pollInterval: z.number().positive().optional(),
@@ -780,6 +782,10 @@ const aiConfigSchema = z.strictObject({
       // and host Ask AI in an existing backend. Absolute URLs and root-relative
       // paths are both valid; the built-in request/stream contract is unchanged.
       endpoint: askEndpointSchema.optional(),
+      // Extra system-prompt text (identity, language, tone) appended to the
+      // built-in instructions, so the grounding contract — answer from the
+      // retrieved excerpts, cite pages as Markdown links — stays intact.
+      instructions: z.string().trim().min(1).optional(),
       model: z.string().default("openai/gpt-5.5"),
       provider: z.enum(askAiProviders).default("gateway"),
       // Empty-state prompts shown before the first question. Each renders as a

package/src/core/site-url.ts

@@ -0,0 +1,27 @@
+import { joinURL } from "ufo";
+
+import { trimEnd } from "./trim.ts";
+
+/**
+ * Absolute-URL building for the configured `deployment.site`, shared by every
+ * emitter that prints site URLs (sitemap, RSS, robots, llms.txt, the MCP and
+ * agent-discovery documents). One implementation replaces eight per-file
+ * copies that had drifted across three different trailing-slash treatments.
+ *
+ * Deliberately not `new URL(path, site)`: a root-absolute path would drop the
+ * base path of a subpath deployment (`acme.com/docs`). ufo's `joinURL` joins
+ * without that footgun; the site is first trimmed with the ReDoS-safe
+ * `trimEnd` loop so even a malformed `site` with piled-up trailing slashes
+ * joins cleanly.
+ */
+
+/** The configured site with any trailing slashes dropped. */
+export const siteRoot = (site: string): string => trimEnd(site, "/");
+
+/** `site` + root-absolute `path` (already carrying any deployment base). */
+export const absoluteUrl = (site: string, path: string): string => {
+  const root = siteRoot(site);
+  // joinURL folds a lone "/" away entirely; the homepage keeps its slash
+  // (`https://example.com/`), matching what every emitter always printed.
+  return path === "/" ? `${root}/` : joinURL(root, path);
+};

package/src/core/sources/cache.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 
 import { join } from "pathe";
@@ -6,14 +7,15 @@ import { BlumeError } from "../diagnostics.ts";
 import type { Diagnostic } from "../types.ts";
 import type { SourceEntry, SourceLoadResult } from "./types.ts";
 
-/** Small, stable content hash for cache/HMR bookkeeping (non-bitwise). */
-export const hashText = (text: string): string => {
-  let hash = 5381;
-  for (let i = 0; i < text.length; i += 1) {
-    hash = (hash * 33 + (text.codePointAt(i) ?? 0)) % 2_147_483_647;
-  }
-  return hash.toString(36);
-};
+/**
+ * Small, stable content hash for cache/HMR bookkeeping — and for staged asset
+ * *filenames* (see sources/assets.ts and content-assets.ts), where a collision
+ * silently serves the wrong file. 64 bits of SHA-256 keeps those names
+ * collision-safe at any realistic asset count; the old 31-bit DJB2 hash had a
+ * ~46k-item birthday bound.
+ */
+export const hashText = (text: string): string =>
+  createHash("sha256").update(text).digest("hex").slice(0, 16);
 
 /** A stable digest of a source's entries, for change detection while polling. */
 export const entriesDigest = (entries: SourceEntry[]): string =>

package/src/core/sources/github-releases.ts

@@ -85,6 +85,26 @@ const NON_PROSE = new Set(["code", "heading", "html", "thematicBreak"]);
  * content kept — then cut at a word boundary to fit the search snippet cap.
  * Undefined when the notes have no prose at all.
  */
+/**
+ * The longest prefix of `text` that fits `max` UTF-16 units without cutting
+ * inside a grapheme cluster. A bare `String#slice` counts code units, so it
+ * can split a surrogate pair (emitting a lone surrogate — invalid Unicode —
+ * into a meta description) or halve an emoji sequence. Grapheme segmentation
+ * is rule-based (UAX #29), so unlike word segmentation it does not drift
+ * across ICU builds.
+ */
+const graphemePrefix = (text: string, max: number): string => {
+  let end = 0;
+  const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+  for (const { index, segment } of graphemes.segment(text)) {
+    if (index + segment.length > max) {
+      break;
+    }
+    end = index + segment.length;
+  }
+  return text.slice(0, end);
+};
+
 const releaseDescription = (body: string): string | undefined => {
   const tree = fromMarkdown(body.replaceAll(CHANGESET_HASH, "$<mark>"), {
     extensions: [gfm()],
@@ -108,7 +128,7 @@ const releaseDescription = (body: string): string | undefined => {
   }
   // Cut before the cap at a word boundary (kept only when it doesn't drop the
   // summary under the minimum), shed any dangling punctuation, and mark the cut.
-  const slice = text.slice(0, DESCRIPTION_MAX - 1);
+  const slice = graphemePrefix(text, DESCRIPTION_MAX - 1);
   const boundary = slice.lastIndexOf(" ");
   const head = (
     boundary >= DESCRIPTION_MIN ? slice.slice(0, boundary) : slice

package/src/core/sources/normalize.ts

@@ -28,12 +28,19 @@ const groupLabel = (segment: string): string | null =>
  * anchor ids are *not* slugged here — they use a `github-slugger` in
  * {@link extractHeadings}, matching the renderer (see `markdown/heading-anchors`)
  * so `blume validate` checks anchors against the exact rendered heading ids.
+ *
+ * The keep-class is Unicode letters/marks/numbers, not `\w`: ASCII slugs are
+ * unchanged, but a CJK/Cyrillic/accented slug keeps its characters instead of
+ * collapsing to `""` (which forced Sanity/Notion routes onto their opaque
+ * document-id fallbacks) or dropping accents (`café` → `caf`). NFC first so a
+ * macOS-NFD `é` (e + combining mark) slugs identically to the composed form.
  */
 export const slugify = (text: string): string =>
   text
+    .normalize("NFC")
     .toLowerCase()
     .trim()
-    .replaceAll(/[^\w\s-]/gu, "")
+    .replaceAll(/[^\p{L}\p{M}\p{N}\s_-]/gu, "")
     .replaceAll(/[\s_]+/gu, "-")
     .replaceAll(/-+/gu, "-")
     .replaceAll(/^-|-$/gu, "");
@@ -55,6 +62,18 @@ const titleCase = (value: string): string =>
     .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
     .join(" ");
 
+/**
+ * Strip characters that cannot survive the route → URL → output-file round
+ * trip. A `:` ahead of the first `/` makes `new URL()` read the segment as a
+ * scheme (`Guide: Architecture.md` → `guide:`), which crashes Astro's
+ * prerender write with "The URL must be of scheme file"; control characters
+ * (an embedded newline in a filename) are silently dropped by the URL parser,
+ * desyncing the route from its output path. Both are legal in macOS/Linux
+ * filenames, so they are removed here rather than rejected.
+ */
+const sanitizeSegment = (segment: string): string =>
+  segment.replaceAll(/[:\p{Cc}]/gu, "");
+
 /** Fold one raw path part into the accumulating route segments/groups. */
 const addRouteSegment = (
   part: string,
@@ -75,7 +94,12 @@ const addRouteSegment = (
   if (clean === "index") {
     return;
   }
-  segments.push(clean);
+  const safe = sanitizeSegment(clean);
+  // A part that was nothing but stripped characters cannot name a segment.
+  if (safe === "") {
+    return;
+  }
+  segments.push(safe);
 };
 
 /** Convert a content-root-relative path into URL + nav metadata. */

package/src/core/sources/notion.ts

@@ -1,5 +1,6 @@
 import { setTimeout as sleep } from "node:timers/promises";
 
+import pLimit from "p-limit";
 import { join } from "pathe";
 
 import { BlumeError } from "../diagnostics.ts";
@@ -96,6 +97,12 @@ export interface NotionSourceOptions {
   prefix?: string;
   /** The Notion database id. */
   database: string;
+  /**
+   * Maximum concurrent Notion API requests. Notion allows an average of 3
+   * requests per second per integration, so a large database must pace its
+   * block-tree fan-out or every request 429s. Default 3.
+   */
+  concurrency?: number;
   /** Integration token; defaults to `NOTION_TOKEN`. */
   token?: string;
   properties?: NotionPropertyMap;
@@ -141,12 +148,15 @@ const RATE_LIMITED = 429;
 const MAX_RETRIES = 4;
 const BASE_DELAY_MS = 500;
 const SECOND_MS = 1000;
+const DEFAULT_CONCURRENCY = 3;
 
 /**
  * Retry a Notion API call on a `429 rate_limited`, honoring the `Retry-After`
  * header and otherwise backing off exponentially. A large workspace fans out
  * many concurrent block-children requests, so without this a single 429 would
- * reject the batch and abort the whole import.
+ * reject the batch and abort the whole import. The exponential wait is
+ * jittered so calls rate-limited together don't retry in lockstep and trip
+ * the limit again as a herd.
  */
 const withNotionRetry = async <T>(
   call: () => Promise<T>,
@@ -163,7 +173,9 @@ const withNotionRetry = async <T>(
       (error as { headers?: Record<string, string> }).headers?.["retry-after"]
     );
     const wait =
-      retryAfter > 0 ? retryAfter * SECOND_MS : BASE_DELAY_MS * 2 ** attempt;
+      retryAfter > 0
+        ? retryAfter * SECOND_MS
+        : BASE_DELAY_MS * 2 ** attempt * (1 + Math.random());
     await sleep(wait);
     return withNotionRetry(call, attempt + 1);
   }
@@ -252,6 +264,16 @@ export const notionSource = (
   ctx?: SourceContext
 ): ContentSource => {
   const props = options.properties ?? {};
+  // A FIFO semaphore: at most N calls run at once, the rest queue. Notion's
+  // rate limit is per-integration (an average of 3 req/s), and a large
+  // database fans out one block-children request per page plus one per nested
+  // container — an unbounded burst guarantees 429s that even the retry loop
+  // can't recover from, so every API call funnels through this limiter.
+  const limit = pLimit(Math.max(1, options.concurrency ?? DEFAULT_CONCURRENCY));
+  // Every Notion API call goes through the limiter, inside the retry — so a
+  // call sleeping through a backoff doesn't hold a slot while it waits.
+  const notionCall = <T>(call: () => Promise<T>): Promise<T> =>
+    withNotionRetry(() => limit(call));
   const cache = snapshotCache(
     ctx?.cacheDir ?? join(".blume", "cache", options.name)
   );
@@ -284,7 +306,7 @@ export const notionSource = (
     blockId: string
   ): Promise<NotionBlock[]> =>
     collectAll((cursor) =>
-      withNotionRetry(() =>
+      notionCall(() =>
         client.blocks.children.list({ block_id: blockId, start_cursor: cursor })
       )
     );
@@ -458,12 +480,12 @@ export const notionSource = (
   };
 
   // Hoisted out of `load` so the retry closure doesn't nest past the linter's
-  // 4-level limit (source factory → queryDatabase → withNotionRetry callback).
+  // 4-level limit (source factory → queryDatabase → notionCall callback).
   const queryDatabase = (
     client: NotionClientLike,
     cursor?: string
   ): Promise<NotionList<NotionPage>> =>
-    withNotionRetry(() =>
+    notionCall(() =>
       client.databases.query({
         database_id: options.database,
         start_cursor: cursor,

package/src/core/sources/portable-text.ts

@@ -45,12 +45,27 @@ const HEADING_STYLES: Record<string, string> = {
   h6: "###### ",
 };
 
+// Markdown/raw-HTML structure characters. Portable Text spans are *plain
+// text* — formatting arrives as marks, never as syntax in the text — so a
+// literal `*`, `_`, `[`, backtick, `~`, or `<` typed in the CMS must render
+// as itself. Unescaped, it opened emphasis or a code span mid-paragraph, and
+// `<` let CMS prose inject raw HTML into the rendered page. CommonMark
+// backslash-escapes every ASCII punctuation character, so `\*` is always the
+// literal asterisk.
+const MARKDOWN_SPECIALS = /[\\`*_[\]~<]/gu;
+
+const escapeText = (text: string): string =>
+  text.replaceAll(MARKDOWN_SPECIALS, String.raw`\$&`);
+
 /** Wrap a span's text in Markdown for its marks (decorators + link defs). */
 const renderSpan = (
   span: PortableTextSpan,
   defs: Map<string, PortableTextMarkDef>
 ): string => {
-  let text = span.text ?? "";
+  // Code spans stay verbatim: their text is literal inside the backticks,
+  // and backslash escapes would render as backslashes.
+  const isCode = span.marks?.includes("code") ?? false;
+  let text = isCode ? (span.text ?? "") : escapeText(span.text ?? "");
   if (!span.marks || span.marks.length === 0) {
     return text;
   }

package/src/core/sources/resolve.ts

@@ -86,6 +86,7 @@ const buildSource = (
   if (def.type === "notion") {
     return notionSource(
       {
+        concurrency: def.concurrency,
         database: def.database,
         name,
         pollInterval: def.pollInterval,

package/src/core/sources/types.ts

@@ -1,4 +1,8 @@
-import type { FrontmatterExtend, ResolvedI18nConfig } from "../schema.ts";
+import type {
+  FolderMeta,
+  FrontmatterExtend,
+  ResolvedI18nConfig,
+} from "../schema.ts";
 import type { Diagnostic } from "../types.ts";
 
 /**
@@ -40,6 +44,14 @@ export interface SourceLoadResult {
   entries: SourceEntry[];
   /** Source-level diagnostics (e.g. an offline cache fallback warning). */
   diagnostics: Diagnostic[];
+  /**
+   * Folder meta the source derives for the sidebar groups its entries create,
+   * keyed by locale-stripped group path (the `meta.ts` key space). The OpenAPI
+   * source labels each tag directory with the spec's own tag name, so the
+   * sidebar shows `OAuth2`/`Größe` instead of a re-humanized slug. Merged
+   * beneath user-authored meta files, which always win.
+   */
+  folderMeta?: Record<string, FolderMeta>;
 }
 
 /**

package/src/deploy/cloudflare-negotiation.ts

@@ -276,6 +276,20 @@ const redirectFor = (pathname) => {
   return Object.hasOwn(REDIRECTS, path) ? REDIRECTS[path] : null;
 };
 
+// \`_redirects\` semantics, which the static layer applies to these same
+// paths: the request's query string is forwarded unless the destination
+// carries its own, and a destination fragment stays after the query.
+const redirectLocation = (destination, search) => {
+  const hashIndex = destination.indexOf("#");
+  const bare = hashIndex === -1 ? destination : destination.slice(0, hashIndex);
+  if (!search || bare.includes("?")) {
+    return destination;
+  }
+  return hashIndex === -1
+    ? bare + search
+    : bare + search + destination.slice(hashIndex);
+};
+
 const parseAccept = (accept) =>
   accept.split(",").map((part) => {
     const segments = part.trim().split(";");
@@ -355,7 +369,7 @@ export default {
     const redirect = redirectFor(url.pathname);
     if (redirect !== null) {
       return new Response(null, {
-        headers: { location: redirect[0] },
+        headers: { location: redirectLocation(redirect[0], url.search) },
         status: redirect[1],
       });
     }