Merge pull request 'docs(cache): set Vercel edge Cache-Control for HTML pages (RFC#562 step 1)' (#56) from docs/rfc562-cache-headers into main

docs(cache): set Vercel edge Cache-Control for HTML pages (RFC#562 step 1)

Merged via 2-eye review (core-devops + core-security APPROVED).

content/docs/plugins.mdx

@@ -35,7 +35,7 @@ runtime.
 | Shape | Description |
 |-------|-------------|
 | agentskills.io format | `SKILL.md` + optional scripts, hooks, and `plugin.yaml` manifest |
-| MCP server | Model Context Protocol server — works with any MCP-compatible AI agent (Claude Code, Cursor, etc.). See the [MCP Server guide](/docs/mcp-server) for setup and available tools. |
+| MCP server | Model Context Protocol server (coming soon for more runtimes) |
 
 The shape is orthogonal to the source. A `github://` plugin and a `local://`
 plugin can both be agentskills.io format. The per-runtime adapter inside the

next.config.mjs

@@ -2,9 +2,33 @@ import { createMDX } from 'fumadocs-mdx/next';
 
 const withMDX = createMDX();
 
+// HTML pages: short edge cache + long stale-while-revalidate. Lets Vercel Edge
+// serve repeat navigations from cache (~5 min fresh, 24 h stale-while-revalidate
+// in the background) while keeping the browser revalidating on every nav. The
+// negative lookahead leaves Next.js's own _next/static (immutable, hash-named)
+// and _next/image cache headers untouched.
+const HTML_CACHE_CONTROL =
+  'public, max-age=0, s-maxage=300, stale-while-revalidate=86400';
+
 /** @type {import('next').NextConfig} */
 const config = {
   reactStrictMode: true,
+  async headers() {
+    return [
+      {
+        // Match every path except Next.js internals and API routes — those
+        // already have correct cache headers (immutable for hashed assets,
+        // app-controlled for /api).
+        source: '/((?!_next/static|_next/image|api/).*)',
+        headers: [
+          {
+            key: 'Cache-Control',
+            value: HTML_CACHE_CONTROL,
+          },
+        ],
+      },
+    ];
+  },
 };
 
 export default withMDX(config);