fix: avoid Mintlify Frame embeds on Pages docs

docs/conversation/the-loop.mdx

@@ -13,9 +13,7 @@ Claude Code 不一样：你说一个需求，它可能连续执行十几步操
 
 这背后的机制叫做 **Agentic Loop**（智能体循环），核心实现在 `src/query.ts` 的 `queryLoop()` 异步生成器函数（第 241 行）。它是一个 `while(true)` 无限循环，每次迭代代表一次"思考→行动→观察"周期。
 
-<Frame caption="Agentic Loop 循环示意">
-  <img src="/docs/images/agentic-loop.png" alt="Agentic Loop 循环图" />
-</Frame>
+> 图示：[`Agentic Loop 循环图（PNG）`](/docs/images/agentic-loop.png)
 
 ## 循环的完整结构
 

docs/introduction/architecture-overview.mdx

@@ -10,9 +10,7 @@ keywords: ["Claude Code 架构", "五层架构", "QueryEngine", "Agentic Loop",
 
 Claude Code 从上到下分为五个层次，每一层职责清晰、边界分明：
 
-<Frame caption="Claude Code 五层架构">
-  <img src="/docs/images/architecture-layers.png" alt="Claude Code 五层架构图" />
-</Frame>
+> 图示：[`Claude Code 五层架构图（PNG）`](/docs/images/architecture-layers.png)
 
 | 层次 | 职责 | 入口源码 | 关键词 |
 |------|------|---------|--------|
@@ -24,9 +22,7 @@ Claude Code 从上到下分为五个层次，每一层职责清晰、边界分
 
 ## 一条主数据流的源码追踪
 
-<Frame caption="核心数据流">
-  <img src="/docs/images/data-flow.png" alt="Claude Code 核心数据流" />
-</Frame>
+> 图示：[`Claude Code 核心数据流图（PNG）`](/docs/images/data-flow.png)
 
 整个系统的运转可以浓缩为一条核心数据流，以下是每一步对应的源码路径：
 

docs/research/project-capability-atlas.mdx

@@ -24,9 +24,7 @@ keywords: ["Claude Code", "reverse engineering", "能力图谱", "skills", "MCP"
 
 ## 核心图谱区
 
-<Frame caption="项目能力全景图">
-  <img src="/docs/images/research/capability-overview.svg" alt="Claude Code 能力全景图" />
-</Frame>
+> 图示：[`Claude Code 能力全景图（SVG）`](/docs/images/research/capability-overview.svg)
 
 ```mermaid
 flowchart LR
@@ -50,9 +48,7 @@ flowchart LR
 
 ## 模块地图区
 
-<Frame caption="能力矩阵">
-  <img src="/docs/images/research/capability-matrix.svg" alt="Claude Code 能力矩阵图" />
-</Frame>
+> 图示：[`Claude Code 能力矩阵图（SVG）`](/docs/images/research/capability-matrix.svg)
 
 ```mermaid
 flowchart TD
@@ -103,9 +99,7 @@ flowchart TD
 
 ## 社区核验区
 
-<Frame caption="社区观点核验图">
-  <img src="/docs/images/research/community-verdicts.svg" alt="Claude Code 社区观点核验图" />
-</Frame>
+> 图示：[`Claude Code 社区观点核验图（SVG）`](/docs/images/research/community-verdicts.svg)
 
 | 社区共识 | Verdict | 当前仓库里的证据 |
 |---|---|---|

scripts/docs-static-compat.test.mjs

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'bun:test';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+async function listMdxFiles(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const entryPath = join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...(await listMdxFiles(entryPath)));
+      continue;
+    }
+
+    if (entry.name.endsWith('.mdx')) {
+      files.push(entryPath);
+    }
+  }
+
+  return files;
+}
+
+describe('docs static export compatibility', () => {
+  it('avoids Mintlify Frame embeds that break on GitHub Pages refresh', async () => {
+    const files = await listMdxFiles(join(process.cwd(), 'docs'));
+    const offenders = [];
+
+    for (const file of files) {
+      const content = await readFile(file, 'utf8');
+
+      if (content.includes('<Frame')) {
+        offenders.push(file);
+      }
+    }
+
+    expect(offenders).toEqual([]);
+  });
+});