thomasjvu · thomasjvu · Jun 25, 2026 · Jun 25, 2026
diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs
@@ -3,7 +3,12 @@ import { readdir } from 'fs/promises';
 import { join } from 'path';
 
 import { getContentCollection } from '../shared/content-collections.js';
-import { documentationTree, frameworkDocPaths, homepageConfig } from '../shared/documentation-config.js';
+import {
+  documentationTree,
+  frameworkDocPaths,
+  homepageConfig,
+  openapiConfig,
+} from '../shared/documentation-config.js';
 import { resolveCollectionContentRoot, resolveMonorepoRoot } from './lib/collectionContentRoot.mjs';
 import { buildDocsContentPath } from '../shared/docsRouting.js';
 import { getDirectoryAliasEntries } from '../shared/seo.js';
@@ -157,6 +162,7 @@ async function main() {
   const { llmsTxt, llmsFullTxt } = createLlmsArtifacts({
     documentationTree,
     homepageConfig,
+    openapiConfig,
     rootDir,
   });
 

diff --git a/scripts/lib/mdxShortcodes.mjs b/scripts/lib/mdxShortcodes.mjs
@@ -159,12 +159,20 @@ function transformCharacterNote(node) {
     className: 'papers-character-note__avatar',
     src: characterNoteAvatars[safeType],
     alt: '',
-    width: 96,
-    height: 96,
+    width: 48,
+    height: 48,
     loading: 'lazy',
     decoding: 'async',
   });
 
+  const avatarSlot = createElement(
+    'div',
+    {
+      className: 'papers-character-note__avatar-slot',
+    },
+    [avatar]
+  );
+
   const body = createElement(
     'div',
     {
@@ -179,7 +187,7 @@ function transformCharacterNote(node) {
       className: `papers-character-note papers-character-note--${safeType}`,
       role: 'note',
     },
-    [avatar, body]
+    [avatarSlot, body]
   );
 }
 

diff --git a/scripts/lib/seoArtifacts.mjs b/scripts/lib/seoArtifacts.mjs
@@ -1,4 +1,4 @@
-import { documentationTree, homepageConfig } from '../../shared/documentation-config.js';
+import { documentationTree, homepageConfig, openapiConfig } from '../../shared/documentation-config.js';
 import {
   buildAbsoluteUrl,
   DEFAULT_OG_IMAGE_PATH,
@@ -233,6 +233,33 @@ export function createAllCollectionSeoRouteEntries(collections, artifactsByColle
     entries.push(...collectionEntries);
   }
 
+  if (openapiConfig.enabled && openapiConfig.specs.length > 0) {
+    const routePrefix = openapiConfig.routePrefix || '/api';
+
+    for (const spec of openapiConfig.specs) {
+      const routePath =
+        spec.id === openapiConfig.defaultSpecId
+          ? routePrefix
+          : `${routePrefix}/${spec.id}`;
+
+      if (routeMap.has(routePath)) {
+        continue;
+      }
+
+      routeMap.set(routePath, true);
+      entries.push({
+        routePath,
+        canonicalPath: routePath,
+        title: `${spec.label} | ${options.siteName || getHomeMetadataDefaults().siteName}`,
+        description:
+          spec.description || `Interactive OpenAPI reference for ${spec.label}.`,
+        type: 'article',
+        includeInSitemap: true,
+        noIndex: false,
+      });
+    }
+  }
+
   return entries;
 }
 

diff --git a/shared/documentation-config.js b/shared/documentation-config.js
@@ -343,4 +343,10 @@ export const documentationTree = [
     path: 'llms',
     tags: ['llms', 'ai', 'reference'],
   },
+  {
+    type: 'file',
+    name: 'Agent Skill.md',
+    path: 'skill',
+    tags: ['skill', 'agent', 'reference'],
+  },
 ];
diff --git a/src/components/CodeBlock.module.css b/src/components/CodeBlock.module.css
@@ -1,6 +1,6 @@
 /* Theme-driven code block chrome — shape tokens live on each theme's tokens.css */
 .codeBlockContainer {
-  margin: 2rem 0;
+  margin: 1.5rem 0;
   border-radius: var(--code-block-radius, 12px);
   clip-path: var(--code-block-clip-path, none);
   overflow: hidden;
@@ -62,9 +62,9 @@
   display: flex;
   justify-content: space-between;
   align-items: center;
-  padding: 0.75rem 1.25rem 0.5rem;
-  background-color: var(--code-header-bg);
-  border-bottom: var(--code-block-header-divider, 1px solid var(--code-border-color));
+  padding: 0.75rem 1.25rem 0;
+  background-color: var(--code-bg);
+  border-bottom: none;
 }
 
 .codeBlockLanguage {
@@ -84,9 +84,9 @@
   padding: 0.375rem;
   min-width: 1.75rem;
   min-height: 1.75rem;
-  border: 1px solid var(--code-copy-border, var(--code-border-color));
+  border: none;
   border-radius: var(--code-block-radius, 6px);
-  background-color: var(--code-copy-bg, var(--code-bg));
+  background-color: transparent;
   color: var(--code-copy-text, var(--code-text-color));
   font-family: var(--mono-font);
   font-size: var(--code-label-size);
@@ -97,9 +97,10 @@
 }
 
 .codeBlockCopyBtn:hover {
-  background-color: var(--code-copy-hover-bg, var(--code-header-bg));
-  border-color: var(--code-copy-hover-border, rgba(var(--primary-color-rgb), 0.22));
+  background-color: transparent;
+  border-color: transparent;
   color: var(--code-copy-text, var(--code-text-color));
+  opacity: 0.72;
 }
 
 .codeBlockCopyBtn:focus {
@@ -115,9 +116,9 @@
 
 .codeBlockContent {
   margin: 0;
-  padding: 0 0 0.25rem;
+  padding: 0;
   min-height: calc(
-    var(--code-block-min-lines, 0) * var(--code-line-height) * var(--code-font-size) + 2.5rem
+    var(--code-block-min-lines, 0) * var(--code-line-height) * var(--code-font-size) + 1.5rem
   );
   background-color: var(--code-bg);
   font-family: var(--mono-font) !important;

diff --git a/src/components/MarkdownRenderer.tsx b/src/components/MarkdownRenderer.tsx
@@ -99,8 +99,20 @@ function resolveInternalHref(
 
   if (href.startsWith('/')) {
     const parsed = new URL(href, 'https://docs.local');
-    const docPath = parsed.pathname.replace(/^\/+/, '');
-    return buildResolvedDocsHref(docPath, `${parsed.search}${parsed.hash}`, context);
+    const pathname = parsed.pathname.replace(/\/+$/, '') || '/';
+    const suffix = `${parsed.search}${parsed.hash}`;
+
+    if (
+      pathname === '/docs' ||
+      pathname.startsWith('/docs/') ||
+      pathname === '/dev-docs' ||
+      pathname.startsWith('/dev-docs/')
+    ) {
+      return pathname + suffix;
+    }
+
+    const docPath = pathname.replace(/^\/+/, '');
+    return buildResolvedDocsHref(docPath, suffix, context);
   }
 
   const { pathname, suffix } = splitPathSuffix(href);

diff --git a/src/components/Navigation.tsx b/src/components/Navigation.tsx
@@ -26,7 +26,6 @@ const navItems: NavItem[] = [
   { label: 'Design System', href: '/docs/developer-guides/design-system' },
   { label: 'Deployment', href: '/docs/deployment/overview' },
   { label: 'LLMs.txt', href: '/docs/llms' },
-  { label: 'Agent Skill', href: '/docs/skill' },
 ];
 
 const bracketAnimationConfig = {
@@ -427,7 +426,7 @@ export default function Navigation({
                       href={link.href}
                       target="_blank"
                       rel="noopener noreferrer"
-                      className={`social-link flex items-center gap-1 ${UI_CLASSES.button}`}
+                      className="social-link flex items-center gap-1"
                       style={{
                         color: 'var(--muted-color)',
                       }}

diff --git a/src/components/OpenApiSpecSelector.tsx b/src/components/OpenApiSpecSelector.tsx
@@ -1,5 +1,7 @@
 import { Link, useLocation } from 'react-router-dom';
 
+import { buildOpenApiRoutePath } from '../lib/openapi';
+
 type OpenApiSpecConfig = {
   id: string;
   label: string;
@@ -11,24 +13,12 @@ type OpenApiSpecSelectorProps = {
   specs: OpenApiSpecConfig[];
   activeSpecId: string;
   defaultSpecId: string;
-  pagePath: string;
 };
 
-function buildSpecHref(specId: string, defaultSpecId: string, pagePath: string) {
-  const basePath = `/docs/${pagePath}`;
-
-  if (specId === defaultSpecId) {
-    return basePath;
-  }
-
-  return `${basePath}/${specId}`;
-}
-
 export default function OpenApiSpecSelector({
   specs,
   activeSpecId,
   defaultSpecId,
-  pagePath,
 }: OpenApiSpecSelectorProps) {
   const location = useLocation();
 
@@ -37,9 +27,9 @@ export default function OpenApiSpecSelector({
   }
 
   return (
-    <div className="mb-4 flex flex-wrap gap-2" role="tablist" aria-label="OpenAPI specifications">
+    <div className="flex flex-wrap gap-2" role="tablist" aria-label="OpenAPI specifications">
       {specs.map((spec) => {
-        const href = buildSpecHref(spec.id, defaultSpecId, pagePath);
+        const href = buildOpenApiRoutePath(spec.id === defaultSpecId ? null : spec.id);
         const isActive = spec.id === activeSpecId;
 
         return (

diff --git a/src/components/docs/DocumentationPage.tsx b/src/components/docs/DocumentationPage.tsx
@@ -377,19 +377,11 @@ const DocumentationPage = React.memo(
                     >
                       P
                     </span>
-                    <span className="min-w-0">
-                      <span
-                        className="block truncate text-sm uppercase tracking-[0.28em]"
-                        style={{ color: 'var(--muted-color)', fontFamily: 'var(--mono-font)' }}
-                      >
-                        Docs
-                      </span>
-                      <span
-                        className="block truncate text-lg font-black uppercase tracking-[0.18em]"
-                        style={{ color: 'var(--text-color)', fontFamily: 'var(--mono-font)' }}
-                      >
-                        {siteName}
-                      </span>
+                    <span
+                      className="min-w-0 truncate text-lg font-black uppercase tracking-[0.18em]"
+                      style={{ color: 'var(--text-color)', fontFamily: 'var(--mono-font)' }}
+                    >
+                      {siteName}
                     </span>
                   </Link>