docs: add @amamo/mdx documentation site with @amamo/doctrine

Bootstrap apps/docs with @amamo/doctrine to ship a public MDX documentation
site. Eight pages in English and 简体中文 cover installation, configuration,
the compiler API, the Vite 8 and Next 16 adapters, the security model, and
the supported native targets.

- apps/docs: doctrine-based site, build wired through pnpm filter
- root package.json: add docs:dev / docs:build and check:docs, the latter
  appended to the existing check pipeline
- pnpm-workspace.yaml: include apps/* alongside the existing allowBuilds
- .github/workflows/docs.yml: workflow_dispatch deploy to GitHub Pages,
  mirroring ../verso (configure-pages -> build -> deploy-pages)
- ignore **/dist/**, **/.doctrine/**, **/node_modules/**, **/.DS_Store,
  and docs/superpowers/ in git, oxfmt, and oxlint so build artifacts and
  internal plans stay out of the repo

Author: jikkai

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Docs
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: pnpm/action-setup@v6
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Configure GitHub Pages
+        id: pages
+        uses: actions/configure-pages@v6
+
+      - name: Build static documentation
+        run: pnpm --filter @amamo/mdx-docs build
+        env:
+          DOCS_SITE_URL: ${{ format('{0}/', steps.pages.outputs.base_url) }}
+
+      - name: Upload documentation
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: apps/docs/dist
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    timeout-minutes: 10
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

.gitignore

@@ -1,8 +1,13 @@
 /dist/
 /node_modules/
+**/node_modules/
 /target/
 **/.amamo-mdx/
 **/.next/
+**/.doctrine/
+**/.DS_Store
+**/dist/
+docs/superpowers/
 fixtures/next/out/
 /*.node
 /native.d.ts

.oxfmtrc.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./node_modules/oxfmt/configuration_schema.json",
-  "ignorePatterns": ["Cargo.lock", "pnpm-lock.yaml"],
+  "ignorePatterns": ["Cargo.lock", "pnpm-lock.yaml", "**/dist/**", "**/.doctrine/**"],
   "semi": false,
   "singleQuote": true
 }

apps/docs/docs/compiler-api.mdx

@@ -0,0 +1,145 @@
+---
+title: Compiler API
+description: Drive the compiler directly with createCompiler, build, transform, remove, and dispose.
+order: 4
+---
+
+The Vite and Next adapters both run on top of the same `ICompiler`. The root API exposes that
+interface so a host application can drive the compiler directly — for example, a build script
+that runs before Vite, a test harness, or a static site generator.
+
+## Construction
+
+```ts
+import { createCompiler } from '@amamo/mdx'
+import config from './amamo.config.js'
+
+const compiler = await createCompiler(config)
+```
+
+`createCompiler` is async because it loads the native binding and the configured highlighter. The
+config is normalized on construction; later edits are not picked up.
+
+The returned object implements `ICompiler`:
+
+```ts
+interface ICompiler {
+  build(): Promise<IBuildResult>
+  dispose(): Promise<void>
+  remove(file: string): Promise<number>
+  transform(file: string): Promise<ITransformResult>
+}
+```
+
+## build
+
+```ts
+const result = await compiler.build()
+```
+
+Discovers every collection, parses and validates every record, renders code blocks, prunes the
+cache, and writes the generated module, the private loader index, and every configured manifest.
+The compiler coalesces concurrent calls, so calling `build()` twice in quick succession is safe.
+
+```ts
+interface IBuildResult {
+  cached: number
+  compiled: number
+  discovered: number
+  outputsWritten: number
+}
+```
+
+- `discovered` is the number of MDX files found across all collections.
+- `compiled` is the number of files that produced fresh cache records.
+- `cached` is `discovered - compiled`.
+- `outputsWritten` is the number of generated files actually written; the rest were byte-for-byte
+  identical to the existing output and left untouched.
+
+`build()` is a superset of the work the adapters do at startup. Calling it explicitly is useful
+when the generated module is consumed by code that is not the Vite or Next adapter.
+
+## transform
+
+```ts
+const result = await compiler.transform('content/posts/hello.mdx')
+```
+
+Re-parses a single file, validates its frontmatter, and writes any new generated output that
+depends on it. The result is the freshly compiled record and a `cached` flag that mirrors the
+cache behavior of the underlying batch.
+
+```ts
+interface ITransformResult {
+  cached: boolean
+  code: string
+  map: null
+  outputsWritten: number
+  record: IDocumentRecord
+}
+```
+
+`code` is the JavaScript source the host application should treat as the document's module body.
+`map` is currently always `null`; the compiler reserves the field for a future source map. The
+full `record` exposes the parsed frontmatter, the derived fields, the diagnostics, the cache key,
+and the SHA-256 hash of the input bytes.
+
+`transform` rejects with an `AmamoMdxError` whose `diagnostics` field lists every problem the
+compiler found. Frontmatter schema violations, missing media, and unknown code-block languages all
+surface as diagnostics.
+
+## remove
+
+```ts
+const removed = await compiler.remove('content/posts/deleted.mdx')
+```
+
+Removes a file from the cache and rewrites any generated output that referenced it. Returns the
+number of generated files actually rewritten. Calling `remove` on a path that is not part of any
+collection is a no-op and returns `0`.
+
+`remove` is the delete-side counterpart of `transform`. The Vite and Next adapters wire it to the
+underlying file system watcher.
+
+## dispose
+
+```ts
+await compiler.dispose()
+```
+
+Releases the highlighter and any open file handles. After `dispose`, the compiler is unusable;
+calling any other method rejects. The compiler is also a process-wide singleton from the adapter's
+point of view, so do not share a disposed instance across requests.
+
+## Errors and diagnostics
+
+Most failures are not thrown as JavaScript exceptions; they are returned as `IDiagnostic[]`
+inside an `AmamoMdxError`:
+
+```ts
+class AmamoMdxError extends Error {
+  readonly diagnostics: IDiagnostic[]
+}
+
+interface IDiagnostic {
+  code: string
+  file?: string
+  hint?: string
+  message: string
+  range?: { start; end }
+  severity: 'error' | 'warning'
+}
+```
+
+The compiler's own plumbing rejects the surrounding `Promise`; it is the caller's job to decide
+whether to surface a single message, a list of file:line diagnostics, or to fail the build.
+
+## Generated module
+
+After `build()` the generated module lives at `<generatedDirectory>/collections.mjs`. It exports
+a tree of named records that the host application can `import` directly. The companion
+`collections.d.mts` provides the same shape to TypeScript.
+
+The private loader index at `<generatedDirectory>/index.json` exposes the same records to the Vite
+and Next adapters without forcing them through the public module — they need a key lookup, not
+the full bundle.

apps/docs/docs/compiler-api.zh-CN.mdx

@@ -0,0 +1,136 @@
+---
+title: 编译器 API
+description: 用 createCompiler、build、transform、remove、dispose 直接驱动编译器。
+order: 4
+---
+
+Vite 和 Next 适配器都跑在同一份 `ICompiler` 之上。根 API 把这个接口直接暴露出来,让宿主
+应用可以自己驱动编译器 —— 比如在 Vite 之前先跑一遍的构建脚本、测试夹具,或者一个静态站点
+生成器。
+
+## 构造
+
+```ts
+import { createCompiler } from '@amamo/mdx'
+import config from './amamo.config.js'
+
+const compiler = await createCompiler(config)
+```
+
+`createCompiler` 是异步的,因为要加载原生绑定和配置的高亮器。配置在构造时被归一化,之后再
+改不会被感知。
+
+返回的对象实现 `ICompiler`:
+
+```ts
+interface ICompiler {
+  build(): Promise<IBuildResult>
+  dispose(): Promise<void>
+  remove(file: string): Promise<number>
+  transform(file: string): Promise<ITransformResult>
+}
+```
+
+## build
+
+```ts
+const result = await compiler.build()
+```
+
+发现所有集合,解析并校验每条记录,渲染代码块,清理缓存,然后写入生成模块、私有加载器索引
+以及每个配置的 manifest。编译器会合并并发调用,所以快速连调 `build()` 两次是安全的。
+
+```ts
+interface IBuildResult {
+  cached: number
+  compiled: number
+  discovered: number
+  outputsWritten: number
+}
+```
+
+- `discovered` 是所有集合中发现的 MDX 文件数。
+- `compiled` 是产生了新缓存记录的文件数。
+- `cached` 等于 `discovered - compiled`。
+- `outputsWritten` 是实际写入的生成文件数;其余与现有产物字节一致,未触碰。
+
+`build()` 涵盖了适配器在启动时做的工作的完整超集。在生成的模块被非 Vite / 非 Next 的
+代码消费时,显式调它很有用。
+
+## transform
+
+```ts
+const result = await compiler.transform('content/posts/hello.mdx')
+```
+
+重新解析单个文件,校验其 frontmatter,并写入任何依赖它的生成产物。结果是刚编译的记录,以及
+一个反映底层批处理缓存行为的 `cached` 标记。
+
+```ts
+interface ITransformResult {
+  cached: boolean
+  code: string
+  map: null
+  outputsWritten: number
+  record: IDocumentRecord
+}
+```
+
+`code` 是宿主应用应视为该文档模块体的 JavaScript 源码。`map` 当前总是 `null`,编译器为
+未来的 source map 保留了这个字段。`record` 暴露了解析后的 frontmatter、derived 字段、
+诊断信息、缓存键以及源字节的 SHA-256 哈希。
+
+`transform` 在出错时以 `AmamoMdxError` 拒绝,`diagnostics` 字段列出编译器发现的所有问题。
+frontmatter schema 违规、媒体缺失、未知代码块语言都以诊断形式出现。
+
+## remove
+
+```ts
+const removed = await compiler.remove('content/posts/deleted.mdx')
+```
+
+从缓存中移除一个文件,并重写任何引用过它的生成产物。返回实际被重写的生成文件数。对不属于
+任何集合的路径调用 `remove` 是 no-op,返回 `0`。
+
+`remove` 是 `transform` 在删除侧的对应操作。Vite 和 Next 适配器把它接到底层文件系统的
+watcher 上。
+
+## dispose
+
+```ts
+await compiler.dispose()
+```
+
+释放高亮器以及任何打开的文件句柄。`dispose` 之后编译器不可再用;再调其它方法会被拒绝。
+从适配器的视角看,编译器是进程级单例,所以不要把一个已 dispose 的实例跨请求共享。
+
+## 错误与诊断
+
+大多数失败不以 JavaScript 异常抛出,而是作为 `IDiagnostic[]` 放在 `AmamoMdxError` 里返回:
+
+```ts
+class AmamoMdxError extends Error {
+  readonly diagnostics: IDiagnostic[]
+}
+
+interface IDiagnostic {
+  code: string
+  file?: string
+  hint?: string
+  message: string
+  range?: { start; end }
+  severity: 'error' | 'warning'
+}
+```
+
+编译器自身的内部管道会让外层 `Promise` 拒绝;具体怎么呈现给用户由调用方决定 —— 是单条
+消息,还是 `file:line` 形式的诊断列表,或直接让构建失败。
+
+## 生成模块
+
+`build()` 之后,生成模块位于 `<generatedDirectory>/collections.mjs`。它导出一棵具名
+记录的树,宿主应用可以直接 `import`。配套的 `collections.d.mts` 给 TypeScript 提供了同样
+的形状。
+
+私有加载器索引位于 `<generatedDirectory>/index.json`,Vite 和 Next 适配器用它来按路径
+查找已编译的记录,而不必走公开模块 —— 它们需要的是 key 查找,不是整个 bundle。