jamdesk 1.1.32 → 1.1.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.32",
+  "version": "1.1.34",
   "description": "CLI for Jamdesk — build, preview, and deploy documentation sites from MDX. Dev server with hot reload, 50+ components, OpenAPI support, AI search, and Mintlify migration",
   "keywords": [
     "jamdesk",

package/vendored/app/[[...slug]]/page.tsx

@@ -41,6 +41,7 @@ import { PanelWrapper } from '@/components/mdx/PanelWrapper';
 import { ViewWrapper } from '@/components/mdx/View';
 import { getLatexRemarkPlugins, getLatexRehypePlugins } from '@/lib/latex-config';
 import { getTypographyRemarkPlugins } from '@/lib/typography-config';
+import { remarkVisibility } from '@/lib/remark-visibility';
 import { recmaCompoundComponents } from '@/lib/recma-compound-components';
 import { extractInlineComponents } from '@/lib/process-mdx-with-exports';
 import { buildEndpointFromMdx } from '@/lib/build-endpoint-from-mdx';
@@ -698,7 +699,7 @@ export default async function DocPage({ params }: PageProps) {
                   // Keep expression props (e.g. cols={2}) compatible under next-mdx-remote v6.
                   ...mdxSecurityOptions,
                   mdxOptions: {
-                    remarkPlugins: [remarkGfm, ...getTypographyRemarkPlugins(config), ...getLatexRemarkPlugins(config)],
+                    remarkPlugins: [remarkGfm, [remarkVisibility, { audience: 'humans' }], ...getTypographyRemarkPlugins(config), ...getLatexRemarkPlugins(config)],
                     rehypePlugins: [rehypeNoZoomToData, rehypeClassToClassName, rehypeCodeMeta, createShikiRehypePlugin(highlighter, config), rehypeRestoreDataTitle, ...getLatexRehypePlugins(config), rehypeSlug],
                     recmaPlugins: [recmaCompoundComponents],
                   },
@@ -724,7 +725,7 @@ export default async function DocPage({ params }: PageProps) {
         // Keep expression props (e.g. cols={2}) compatible under next-mdx-remote v6.
         ...mdxSecurityOptions,
         mdxOptions: {
-          remarkPlugins: [remarkGfm, ...getTypographyRemarkPlugins(config), ...getLatexRemarkPlugins(config)],
+          remarkPlugins: [remarkGfm, [remarkVisibility, { audience: 'humans' }], ...getTypographyRemarkPlugins(config), ...getLatexRemarkPlugins(config)],
           rehypePlugins: [rehypeNoZoomToData, rehypeClassToClassName, rehypeCodeMeta, createShikiRehypePlugin(highlighter, config), rehypeRestoreDataTitle, ...getLatexRehypePlugins(config), rehypeSlug],
           recmaPlugins: [recmaCompoundComponents],
         },

package/vendored/app/api/markdown-export/[project]/[...slug]/route.ts

@@ -0,0 +1,76 @@
+import { NextResponse } from 'next/server';
+import {
+  fetchMdxContent,
+  R2_NOT_FOUND_ERROR_NAMES,
+  R2_NOT_FOUND_MESSAGE_PREFIX,
+} from '@/lib/r2-content';
+import { filterVisibility } from '@/lib/visibility-filter';
+import { VALID_SLUG_RE } from '@/lib/middleware-helpers';
+import {
+  acceptsMarkdown,
+  MARKDOWN_CACHE_PUBLIC,
+  MARKDOWN_CACHE_PRIVATE,
+} from '@/lib/content-negotiation';
+
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+/**
+ * Production `.md` export (and `Accept: text/markdown` canonical URLs).
+ * Fetches raw MDX from R2 via the existing in-memory-cached fetcher,
+ * applies the audience=agents filter, and returns as text/markdown with
+ * the same security headers the legacy /api/r2 path applied to .mdx.
+ */
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ project: string; slug: string[] }> }
+) {
+  const { project, slug } = await params;
+
+  // Defense in depth: the proxy always resolves `project` from the domain
+  // resolver before routing here, but anything reachable via direct URL
+  // must be locked to the slug character set.
+  if (!VALID_SLUG_RE.test(project)) {
+    return new NextResponse('Bad request', { status: 400 });
+  }
+
+  const pagePath = slug.join('/');
+
+  let raw: string;
+  try {
+    raw = await fetchMdxContent(project, pagePath);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : '';
+    const name = err instanceof Error ? err.name : '';
+    if (
+      msg.startsWith(R2_NOT_FOUND_MESSAGE_PREFIX) ||
+      R2_NOT_FOUND_ERROR_NAMES.has(name)
+    ) {
+      return new NextResponse('Not found', { status: 404 });
+    }
+    return new NextResponse('Upstream unavailable', { status: 502 });
+  }
+
+  const filtered = filterVisibility(raw, 'agents');
+
+  // Two paths reach this handler via proxy rewrite:
+  //   (a) `.md` URL: unique CDN cache key, safe to share.
+  //   (b) canonical URL + `Accept: text/markdown`: shares a cache key with
+  //       the HTML page. Cloudflare ignores `Vary: Accept` on public entries,
+  //       so a cached markdown response would poison browser requests.
+  const cacheControl = acceptsMarkdown(request.headers.get('accept'))
+    ? MARKDOWN_CACHE_PRIVATE
+    : MARKDOWN_CACHE_PUBLIC;
+
+  return new NextResponse(filtered, {
+    headers: {
+      'Content-Type': 'text/markdown; charset=utf-8',
+      'Content-Disposition': 'inline',
+      'Cache-Control': cacheControl,
+      'Vary': 'Accept',
+      'X-Robots-Tag': 'noindex, nofollow',
+      'X-Frame-Options': 'DENY',
+      'Content-Security-Policy': "default-src 'none'",
+    },
+  });
+}

package/vendored/app/api/raw-content/[...slug]/route.ts

@@ -1,21 +1,22 @@
 import { getContentLoader } from '@/lib/content-loader';
+import { filterVisibility } from '@/lib/visibility-filter';
 import { NextResponse } from 'next/server';
 
 /**
- * Serve raw MDX content for local dev mode.
- * In production ISR mode, .md URLs are handled by middleware → R2 instead.
+ * Dev `.md` route. Applies the visibility filter with audience='agents'
+ * — strips for="humans" blocks, unwraps for="agents" blocks. Code-block-safe.
+ * Production `.md` goes through /api/markdown-export/[project]/[...slug].
  */
 export async function GET(
   _request: Request,
   { params }: { params: Promise<{ slug: string[] }> }
 ) {
   const { slug } = await params;
-  const pagePath = slug.join('/');
-
   try {
     const loader = getContentLoader();
-    const content = await loader.getContent(pagePath);
-    return new NextResponse(content, {
+    const raw = await loader.getContent(slug.join('/'));
+    const filtered = filterVisibility(raw, 'agents');
+    return new NextResponse(filtered, {
       headers: {
         'Content-Type': 'text/markdown; charset=utf-8',
         'Content-Disposition': 'inline',

package/vendored/components/mdx/MDXComponents.tsx

@@ -31,6 +31,7 @@ import { Columns } from './Columns';
 import { View, ViewProvider, ViewSelector, ViewWrapper } from './View';
 import { YouTube } from './YouTube';
 import { Video } from './Video';
+import { Visibility } from './Visibility';
 
 /**
  * Extract language from a pre element for tab label
@@ -229,6 +230,12 @@ export const MDXComponents = {
   YouTube,
   // Video player for local video files
   Video,
+  // Audience-conditional content. Filtered at MDX-compile time by
+  // lib/remark-visibility.ts for the HTML render path and by
+  // lib/visibility-filter.ts for text surfaces (.md export, llms-full.txt,
+  // search index). This React component is a fail-closed fallback for
+  // any <Visibility> that slips past both filters.
+  Visibility,
   // Sized images from preprocess-mdx (![alt](url =WIDTHx) syntax).
   // These are output as <SizedImage> JSX so they go through component mapping
   // (raw <img> JSX in MDX bypasses the components provider).

package/vendored/components/mdx/Visibility.tsx

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react';
+
+interface VisibilityProps {
+  for: 'humans' | 'agents';
+  children?: ReactNode;
+}
+
+/**
+ * <Visibility for="humans|agents"> — audience-conditional content.
+ *
+ * Filtering is normally done at MDX-compile time by `lib/remark-visibility.ts`
+ * (HTML render, snippets) or at the text level by `lib/visibility-filter.ts`
+ * (.md export, llms-full.txt). This React component is a defensive passthrough
+ * so if the filter ever misses (dynamic import, future MDX form, writer bug),
+ * the component still fails-closed for agents and fails-visible for humans.
+ */
+export function Visibility({ for: audience, children }: VisibilityProps) {
+  if (audience === 'agents') return null;
+  return <>{children}</>;
+}

package/vendored/lib/content-negotiation.ts

@@ -0,0 +1,29 @@
+/**
+ * True if the Accept header contains a `text/markdown` offer with a
+ * non-zero q-value (or no q-value). Scans offers individually so
+ * `text/markdown;q=0` ("explicitly not markdown") doesn't trigger a match.
+ *
+ * Shared between the proxy (for URL rewriting) and the markdown-export
+ * route handler (for cache policy decisions) so both layers agree on
+ * what counts as an agent-facing request.
+ */
+export function acceptsMarkdown(accept: string | null | undefined): boolean {
+  if (!accept) return false;
+  // Browsers never send text/markdown; short-circuit on the ~99% hot path
+  // without allocating a lowercased copy or splitting into offers.
+  if (accept.search(/text\/markdown/i) === -1) return false;
+  return accept
+    .toLowerCase()
+    .split(',')
+    .some(offer => {
+      const [type, ...params] = offer.trim().split(';').map(s => s.trim());
+      if (type !== 'text/markdown') return false;
+      const qParam = params.find(p => p.startsWith('q='));
+      if (!qParam) return true;
+      const q = Number.parseFloat(qParam.slice(2));
+      return Number.isFinite(q) && q > 0;
+    });
+}
+
+export const MARKDOWN_CACHE_PUBLIC = 'public, max-age=3600, s-maxage=86400';
+export const MARKDOWN_CACHE_PRIVATE = 'private, no-store';

package/vendored/lib/preprocess-mdx.ts

@@ -8,6 +8,7 @@
 
 import { ASSET_PREFIX, appendAssetVersion } from './docs-types';
 import { checkForDeprecatedComponents } from './deprecated-components';
+import { filterVisibility } from './visibility-filter';
 
 /**
  * JSX components that contain markdown content requiring special preprocessing.
@@ -35,6 +36,7 @@ const JSX_CONTENT_COMPONENTS = [
   'View',
   'Varning',
   'Avertissement',
+  'Visibility',
 ] as const;
 
 /**
@@ -935,6 +937,11 @@ export function preprocessMdx(content: string, options?: { assetVersion?: string
   let processed = content;
   const assetVersion = options?.assetVersion;
 
+  // Audience filter (code-block-safe). The remark plugin in page.tsx is the
+  // primary line of defense for HTML render; this backs up snippet files
+  // that flow through preprocessMdx independently.
+  processed = filterVisibility(processed, 'humans');
+
   // Strip snippet imports
   processed = stripSnippetImports(processed);
 

package/vendored/lib/process-mdx-with-exports.ts

@@ -12,6 +12,7 @@ import remarkParse from 'remark-parse';
 import remarkMdx from 'remark-mdx';
 import { VFile } from 'vfile';
 import { remarkExtractExports } from './remark-extract-exports';
+import { remarkVisibility } from './remark-visibility';
 import { compileInlineComponents } from './mdx-inline-components';
 import { remarkExtractParamFields } from './remark-extract-param-fields';
 import type { ExtractedParam } from './remark-extract-param-fields';
@@ -30,6 +31,7 @@ interface ProcessResult {
 const mdxProcessor = unified()
   .use(remarkParse)
   .use(remarkMdx)
+  .use(remarkVisibility, { audience: 'humans' })
   .use(remarkExtractExports)
   .use(remarkExtractParamFields);
 

package/vendored/lib/r2-content.ts

@@ -9,6 +9,12 @@ import type { DocsConfig } from './docs-types';
 
 export type { DocsConfig };
 
+export const R2_NOT_FOUND_ERROR_NAMES: ReadonlySet<string> = new Set([
+  'NoSuchKey',
+  'AccessDenied',
+]);
+export const R2_NOT_FOUND_MESSAGE_PREFIX = 'Page not found';
+
 export function evictOldest<K, V>(cache: Map<K, V>, maxSize: number): void {
   if (cache.size <= maxSize) return;
   const toDelete = cache.size - maxSize;
@@ -23,6 +29,8 @@ export function evictOldest<K, V>(cache: Map<K, V>, maxSize: number): void {
 export function clearConfigCache(_projectSlug?: string): void {}
 export function getConfigCacheSize(): number { return 0; }
 
+export function isR2NotFound(_err: unknown): boolean { return false; }
+
 let fetchDocsConfigWarned = false;
 export async function fetchDocsConfig(_projectSlug: string): Promise<DocsConfig | null> {
   if (!fetchDocsConfigWarned) {

package/vendored/lib/remark-visibility.ts

@@ -0,0 +1,86 @@
+/**
+ * remark-visibility
+ *
+ * MDX AST plugin that strips or unwraps <Visibility for="humans|agents">
+ * elements based on the consuming audience. Run this plugin BEFORE
+ * remarkExtractExports so exports inside filtered-out blocks are
+ * dropped along with the block.
+ *
+ * Unlike the text-level filter in lib/visibility-filter.ts, this plugin
+ * is safe for:
+ *   - code blocks (mdast `code` nodes aren't traversed as JSX)
+ *   - nested <Visibility> elements
+ *   - JSX expressions
+ */
+
+import type { Root, RootContent } from 'mdast';
+import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx';
+
+type JsxEl = MdxJsxFlowElement | MdxJsxTextElement;
+
+export interface RemarkVisibilityOptions {
+  audience: 'humans' | 'agents';
+}
+
+function isVisibility(node: unknown): node is JsxEl {
+  if (!node || typeof node !== 'object') return false;
+  const n = node as { type?: string; name?: string };
+  return (
+    (n.type === 'mdxJsxFlowElement' || n.type === 'mdxJsxTextElement') &&
+    n.name === 'Visibility'
+  );
+}
+
+function getForAttr(node: JsxEl): string | null {
+  for (const attr of node.attributes ?? []) {
+    if (attr.type === 'mdxJsxAttribute' && attr.name === 'for') {
+      if (typeof attr.value === 'string') return attr.value.toLowerCase();
+      // Expression-valued attribute — treat as unknown, leave alone.
+      return null;
+    }
+  }
+  return null;
+}
+
+export function remarkVisibility(options: RemarkVisibilityOptions) {
+  const { audience } = options;
+  return function transform(tree: Root): void {
+    visitInPlace(tree, audience);
+  };
+}
+
+function visitInPlace(
+  parent: { children?: RootContent[] },
+  audience: 'humans' | 'agents',
+): void {
+  if (!Array.isArray(parent.children)) return;
+
+  const next: RootContent[] = [];
+  for (const child of parent.children) {
+    if (isVisibility(child)) {
+      const target = getForAttr(child);
+      if (target === null) {
+        visitInPlace(child as unknown as { children?: RootContent[] }, audience);
+        next.push(child);
+        continue;
+      }
+      if (target !== 'humans' && target !== 'agents') {
+        visitInPlace(child as unknown as { children?: RootContent[] }, audience);
+        next.push(child);
+        continue;
+      }
+      if (target === audience) {
+        // Unwrap: recurse first so nested <Visibility> get filtered, then splice in children.
+        visitInPlace(child as unknown as { children?: RootContent[] }, audience);
+        next.push(...((child.children ?? []) as RootContent[]));
+      }
+      // Else: drop entirely.
+      continue;
+    }
+
+    visitInPlace(child as unknown as { children?: RootContent[] }, audience);
+    next.push(child);
+  }
+
+  parent.children = next;
+}

package/vendored/lib/search.ts

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { parseFrontmatterLenient } from './frontmatter-utils';
+import { filterVisibility } from './visibility-filter';
 
 export interface SearchResult {
   id: string;
@@ -79,8 +80,9 @@ export function buildSearchIndex(): SearchResult[] {
         const fileContents = fs.readFileSync(filePath, 'utf8');
         const { data, content } = parseFrontmatterLenient(fileContents);
 
-        // Extract sections from content
-        const sections = extractSections(content);
+        // Filter for="agents" content out of the search index.
+        const visibleContent = filterVisibility(content, 'humans');
+        const sections = extractSections(visibleContent);
 
         sections.forEach((section, idx) => {
           const cleanContent = stripMarkdown(section.content);

package/vendored/lib/snippet-loader-isr.ts

@@ -14,6 +14,7 @@ import * as jsxRuntime from 'react/jsx-runtime';
 import { transform } from '@babel/standalone';
 import { fetchSnippet } from './r2-content';
 import { extractSnippetImports } from './preprocess-mdx';
+import { filterVisibility } from './visibility-filter';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AnyComponent = React.ComponentType<any>;
@@ -240,8 +241,10 @@ async function compileSnippet(
     return cached.result;
   }
 
-  // Fetch from R2
-  const source = await fetchSnippet(projectSlug, snippetPath);
+  // Fetch from R2 and strip <Visibility for="agents"> blocks before compiling.
+  // Filter before caching so cached components are already audience-filtered.
+  const rawSource = await fetchSnippet(projectSlug, snippetPath);
+  const source = filterVisibility(rawSource, 'humans');
 
   // Check for 'use client' directive
   const trimmed = source.trimStart();

package/vendored/lib/static-artifacts.ts

@@ -7,6 +7,7 @@
 
 import type { NavigationConfig } from './docs-types.js';
 import { RECURSE_KEYS } from './enhance-navigation.js';
+import { filterVisibility } from './visibility-filter.js';
 
 /**
  * Page metadata for artifact generation.
@@ -313,7 +314,7 @@ export function generateLlmsFullTxt(options: LlmsFullTxtOptions): string {
       parts.push(`*${page.frontmatter.description}*\n\n`);
     }
 
-    const content = page.content.trim();
+    const content = filterVisibility(page.content, 'agents').trim();
     if (content) {
       parts.push(`${content}\n\n`);
     }
@@ -676,7 +677,11 @@ export function generateSearchData(pages: SearchPageInfo[]): string {
     const pathWithoutExt = page.path.replace(/\.mdx?$/, '');
     const slug = pathWithoutExt.replace(/\\/g, '/');
     const pageType = inferPageType(slug);
-    const sections = extractSections(page.content);
+    // Filter for="agents" content out of the search index — the site
+    // search is a human-facing surface, so agent-only content must not
+    // leak into autocomplete.
+    const visibleContent = filterVisibility(page.content, 'humans');
+    const sections = extractSections(visibleContent);
 
     sections.forEach((section, idx) => {
       const cleanContent = stripMarkdown(section.content);

package/vendored/lib/visibility-filter.ts

@@ -0,0 +1,162 @@
+/**
+ * Visibility text-level filter — used by the prod `.md` export route, the
+ * search-index generator, and the CJS build scripts, which can't run the
+ * MDX AST pipeline.
+ *
+ * For HTML render and snippets, the remark plugin at `lib/remark-visibility.ts`
+ * is used instead (AST-safe; handles nested tags and JSX expressions).
+ *
+ * This filter preserves:
+ *   - Fenced code blocks (``` and ~~~), with or without trailing whitespace
+ *     after the closer
+ *   - CommonMark indented code blocks (4+ spaces or tab, preceded by a
+ *     blank line or start-of-string)
+ *   - Inline code (`...`)
+ *
+ * KNOWN LIMITATION: this filter is not nesting-safe. A non-greedy regex
+ * always consumes to the first </Visibility>. The fixpoint loop handles
+ * sibling blocks produced by unwrap, but nested <Visibility> in the text
+ * surface (.md export, llms-full.txt) produces mangled output. Customer
+ * docs discourage nesting. For the HTML render surface the remark plugin
+ * handles nesting correctly.
+ */
+
+export type VisibilityAudience = 'humans' | 'agents';
+
+// Attribute region tolerates `>` inside quoted values (writer-legal MDX
+// like `<Visibility title="a>b">`). We alternate quoted strings vs
+// non-special chars so `>` in a quoted value can't prematurely close the
+// tag. Pattern: `"..."`, `'...'`, or a char that's not `>`/`"`/`'`.
+const VISIBILITY_TAG =
+  /<Visibility\s+((?:"[^"]*"|'[^']*'|[^>"'])*?)(?:\/>|>([\s\S]*?)<\/Visibility>)/g;
+// Anchor `for` on whitespace / start-of-attrs so attributes like
+// `data-for="x"` or `my-for="x"` can't collide.
+const FOR_ATTR = /(?:^|\s)for\s*=\s*["']([^"']+)["']/;
+
+// Closing fence tolerates trailing whitespace (CommonMark §4.5).
+const FENCED_BLOCK = /(^|\n)(```|~~~)[^\n]*\n[\s\S]*?\n\2[ \t]*(?=\n|$)/g;
+const INLINE_CODE = /`[^`\n]+`/g;
+const INDENTED_LINE = /^(?: {4,}|\t)/;
+// Cheap pre-check: indented code blocks require a \n followed by 4+ spaces
+// or a tab. If neither appears, skip the line-split + per-line scan below.
+const INDENT_PRECHECK = /\n(?: {4}|\t)/;
+
+// Fixpoint-loop cap. Depth of re-matches in any real document is <<10;
+// this guards against pathological / adversarial input.
+const MAX_PASSES = 16;
+
+// CommonMark indented code blocks (4+ spaces or a tab, preceded by a blank
+// line or start-of-string). Returns half-open offset ranges. Trailing blank
+// lines inside a block are excluded from the preserved range.
+function findIndentedCodeRanges(content: string): Array<[number, number]> {
+  if (!INDENT_PRECHECK.test(content) && !INDENTED_LINE.test(content)) {
+    return [];
+  }
+  const ranges: Array<[number, number]> = [];
+  const lines = content.split('\n');
+  const offsets: number[] = new Array(lines.length + 1);
+  offsets[0] = 0;
+  for (let i = 0; i < lines.length; i++) {
+    offsets[i + 1] = offsets[i] + lines[i].length + 1;
+  }
+
+  let blockStart = -1;
+  let trailingBlanks = 0;
+  let prevBlank = true; // start-of-string qualifies as "blank" for trigger
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const isBlank = line.trim() === '';
+    const isIndented = INDENTED_LINE.test(line);
+    if (blockStart < 0) {
+      if (prevBlank && isIndented && !isBlank) {
+        blockStart = i;
+        trailingBlanks = 0;
+      }
+    } else if (isIndented && !isBlank) {
+      trailingBlanks = 0;
+    } else if (isBlank) {
+      trailingBlanks++;
+    } else {
+      ranges.push([offsets[blockStart], offsets[i - trailingBlanks]]);
+      blockStart = -1;
+      trailingBlanks = 0;
+    }
+    prevBlank = isBlank;
+  }
+  if (blockStart >= 0) {
+    const end = lines.length - trailingBlanks;
+    ranges.push([offsets[blockStart], offsets[end]]);
+  }
+  return ranges;
+}
+
+function transformInlineAware(content: string, fn: (text: string) => string): string {
+  const out: string[] = [];
+  let last = 0;
+  for (const m of content.matchAll(INLINE_CODE)) {
+    const idx = m.index ?? 0;
+    out.push(fn(content.slice(last, idx)));
+    out.push(m[0]);
+    last = idx + m[0].length;
+  }
+  out.push(fn(content.slice(last)));
+  return out.join('');
+}
+
+function transformOutsideIndentedCode(content: string, fn: (text: string) => string): string {
+  const ranges = findIndentedCodeRanges(content);
+  if (ranges.length === 0) return transformInlineAware(content, fn);
+  const parts: string[] = [];
+  let last = 0;
+  for (const [start, end] of ranges) {
+    parts.push(transformInlineAware(content.slice(last, start), fn));
+    parts.push(content.slice(start, end));
+    last = end;
+  }
+  parts.push(transformInlineAware(content.slice(last), fn));
+  return parts.join('');
+}
+
+// Apply a transform only to regions OUTSIDE fenced, indented, and inline code.
+function transformOutsideCodeBlocks(
+  content: string,
+  fn: (text: string) => string,
+): string {
+  const parts: string[] = [];
+  let last = 0;
+  for (const m of content.matchAll(FENCED_BLOCK)) {
+    const idx = m.index ?? 0;
+    parts.push(transformOutsideIndentedCode(content.slice(last, idx), fn));
+    parts.push(m[0]);
+    last = idx + m[0].length;
+  }
+  parts.push(transformOutsideIndentedCode(content.slice(last), fn));
+  return parts.join('');
+}
+
+function filterVisibilityRaw(content: string, audience: VisibilityAudience): string {
+  return content.replace(VISIBILITY_TAG, (match, attrs: string, inner: string | undefined) => {
+    const forMatch = attrs.match(FOR_ATTR);
+    if (!forMatch) return match;
+    const target = forMatch[1].toLowerCase();
+    if (target !== 'humans' && target !== 'agents') return match;
+    if (target === audience) return inner ?? '';
+    return '';
+  });
+}
+
+/**
+ * Filter <Visibility> blocks from MDX text. Safe for fenced, indented, and
+ * inline code. Iterates to a fixpoint so unwrap passes surface newly-
+ * adjacent tags.
+ */
+export function filterVisibility(content: string, audience: VisibilityAudience): string {
+  let prev: string;
+  let out = content;
+  for (let i = 0; i < MAX_PASSES; i++) {
+    prev = out;
+    out = transformOutsideCodeBlocks(prev, t => filterVisibilityRaw(t, audience));
+    if (out === prev) break;
+  }
+  return out;
+}

package/vendored/scripts/build-search-index.cjs

@@ -23,6 +23,7 @@ const matter = require('gray-matter');
 const os = require('os');
 const { create, insertMultiple } = require('@orama/orama');
 const { persist } = require('@orama/plugin-data-persistence');
+const { filterVisibility } = require('./visibility-filter.cjs');
 
 // Concurrency control for parallel file processing
 const CONCURRENCY = parseInt(process.env.SEARCH_INDEX_CONCURRENCY || '') || os.cpus().length * 2;
@@ -256,7 +257,9 @@ async function buildSearchIndex() {
     try {
       const fileContents = await fsPromises.readFile(filePath, 'utf8');
       const { data, content } = parseFrontmatterLenient(fileContents);
-      const sections = extractSections(content);
+      // Filter for="agents" content out of the search index.
+      const visibleContent = filterVisibility(content, 'humans');
+      const sections = extractSections(visibleContent);
 
       const docs = [];
       const normalizedSlug = slug.replace(/\\/g, '/');

package/vendored/scripts/visibility-filter.cjs

@@ -0,0 +1,125 @@
+/**
+ * CJS mirror of lib/visibility-filter.ts.
+ *
+ * Used by CJS build scripts (generate-llms-full.cjs, build-search-index.cjs)
+ * that can't import the ESM TypeScript source. Behavior must stay
+ * byte-for-byte identical to the TS filter so that runtime and build-time
+ * outputs match (see `__tests__/lib/visibility-filter.test.ts` for the
+ * behaviors we pin).
+ */
+
+'use strict';
+
+const VIS_TAG =
+  /<Visibility\s+((?:"[^"]*"|'[^']*'|[^>"'])*?)(?:\/>|>([\s\S]*?)<\/Visibility>)/g;
+const VIS_FOR = /(?:^|\s)for\s*=\s*["']([^"']+)["']/;
+const VIS_FENCED = /(^|\n)(```|~~~)[^\n]*\n[\s\S]*?\n\2[ \t]*(?=\n|$)/g;
+const VIS_INLINE = /`[^`\n]+`/g;
+const VIS_INDENTED_LINE = /^(?: {4,}|\t)/;
+const VIS_INDENT_PRECHECK = /\n(?: {4}|\t)/;
+const VIS_MAX_PASSES = 16;
+
+function findIndentedCodeRanges(content) {
+  if (!VIS_INDENT_PRECHECK.test(content) && !VIS_INDENTED_LINE.test(content)) {
+    return [];
+  }
+  const ranges = [];
+  const lines = content.split('\n');
+  const offsets = new Array(lines.length + 1);
+  offsets[0] = 0;
+  for (let i = 0; i < lines.length; i++) {
+    offsets[i + 1] = offsets[i] + lines[i].length + 1;
+  }
+
+  let blockStart = -1;
+  let trailingBlanks = 0;
+  let prevBlank = true;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const isBlank = line.trim() === '';
+    const isIndented = VIS_INDENTED_LINE.test(line);
+    if (blockStart < 0) {
+      if (prevBlank && isIndented && !isBlank) {
+        blockStart = i;
+        trailingBlanks = 0;
+      }
+    } else if (isIndented && !isBlank) {
+      trailingBlanks = 0;
+    } else if (isBlank) {
+      trailingBlanks++;
+    } else {
+      ranges.push([offsets[blockStart], offsets[i - trailingBlanks]]);
+      blockStart = -1;
+      trailingBlanks = 0;
+    }
+    prevBlank = isBlank;
+  }
+  if (blockStart >= 0) {
+    const end = lines.length - trailingBlanks;
+    ranges.push([offsets[blockStart], offsets[end]]);
+  }
+  return ranges;
+}
+
+function filterVisibilityRaw(content, audience) {
+  return content.replace(VIS_TAG, (match, attrs, inner) => {
+    const m = attrs.match(VIS_FOR);
+    if (!m) return match;
+    const t = m[1].toLowerCase();
+    if (t !== 'humans' && t !== 'agents') return match;
+    if (t === audience) return inner == null ? '' : inner;
+    return '';
+  });
+}
+
+function transformInlineAware(content, fn) {
+  const out = [];
+  let last = 0;
+  for (const m of content.matchAll(VIS_INLINE)) {
+    const idx = m.index ?? 0;
+    out.push(fn(content.slice(last, idx)));
+    out.push(m[0]);
+    last = idx + m[0].length;
+  }
+  out.push(fn(content.slice(last)));
+  return out.join('');
+}
+
+function transformOutsideIndentedCode(content, fn) {
+  const ranges = findIndentedCodeRanges(content);
+  if (ranges.length === 0) return transformInlineAware(content, fn);
+  const parts = [];
+  let last = 0;
+  for (const [start, end] of ranges) {
+    parts.push(transformInlineAware(content.slice(last, start), fn));
+    parts.push(content.slice(start, end));
+    last = end;
+  }
+  parts.push(transformInlineAware(content.slice(last), fn));
+  return parts.join('');
+}
+
+function filterVisibilityOnce(content, audience) {
+  const parts = [];
+  let last = 0;
+  for (const m of content.matchAll(VIS_FENCED)) {
+    const idx = m.index ?? 0;
+    parts.push(transformOutsideIndentedCode(content.slice(last, idx), t => filterVisibilityRaw(t, audience)));
+    parts.push(m[0]);
+    last = idx + m[0].length;
+  }
+  parts.push(transformOutsideIndentedCode(content.slice(last), t => filterVisibilityRaw(t, audience)));
+  return parts.join('');
+}
+
+function filterVisibility(content, audience) {
+  let out = content;
+  for (let i = 0; i < VIS_MAX_PASSES; i++) {
+    const prev = out;
+    out = filterVisibilityOnce(prev, audience);
+    if (out === prev) break;
+  }
+  return out;
+}
+
+module.exports = { filterVisibility };

package/vendored/workspace-package-lock.json

@@ -2980,19 +2980,19 @@
       "license": "MIT"
     },
     "node_modules/electron-to-chromium": {
-      "version": "1.5.343",
-      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.343.tgz",
-      "integrity": "sha512-YHnQ3MXI08icvL9ZKnEBy05F2EQ8ob01UaMOuMbM8l+4UcAq6MPPbBTJBbsBUg3H8JeZNt+O4fjsoWth3p6IFg==",
+      "version": "1.5.344",
+      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.344.tgz",
+      "integrity": "sha512-4MxfbmNDm+KPh066EZy+eUnkcDPcZ35wNmOWzFuh/ijvHsve6kbLTLURy88uCNK5FbpN+yk2nQY6BYh1GEt+wg==",
       "license": "ISC"
     },
     "node_modules/enhanced-resolve": {
-      "version": "5.20.1",
-      "resolved": "https://registry.npmjs.org/enhanced-resolve/-/enhanced-resolve-5.20.1.tgz",
-      "integrity": "sha512-Qohcme7V1inbAfvjItgw0EaxVX5q2rdVEZHRBrEQdRZTssLDGsL8Lwrznl8oQ/6kuTJONLaDcGjkNP247XEhcA==",
+      "version": "5.21.0",
+      "resolved": "https://registry.npmjs.org/enhanced-resolve/-/enhanced-resolve-5.21.0.tgz",
+      "integrity": "sha512-otxSQPw4lkOZWkHpB3zaEQs6gWYEsmX4xQF68ElXC/TWvGxGMSGOvoNbaLXm6/cS/fSfHtsEdw90y20PCd+sCA==",
       "license": "MIT",
       "dependencies": {
         "graceful-fs": "^4.2.4",
-        "tapable": "^2.3.0"
+        "tapable": "^2.3.3"
       },
       "engines": {
         "node": ">=10.13.0"