clarity-theme 0.1.1 → 0.1.3

package/README.zh-CN.md

@@ -1,51 +1,45 @@
 # Clarity Theme
 
+[![CI](https://github.com/iicemeta/clarity-theme/actions/workflows/ci.yml/badge.svg)](https://github.com/iicemeta/clarity-theme/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/clarity-theme)](https://www.npmjs.com/package/clarity-theme)
+[![License: MIT](https://img.shields.io/npm/l/clarity-theme)](./LICENSE)
+
 [English](./README.md) | **简体中文**
 
 Clarity Theme 是一个从 [L33Z22L11/blog-v3](https://github.com/L33Z22L11/blog-v3) 抽取出来的可复用 **Nuxt 4 Layer 博客主题**。它提供通用的博客 UI、页面结构、Markdown/MDC 渲染、SEO 集成以及 feed/服务端输出；你的项目只需要提供全部站点数据与内容。
 
-## 功能特性
-
-- 通过一条 `extends` 配置即可完成 Nuxt 4 Layer 安装
-- 带默认值校验的站点配置，并严格拒绝未知字段
-- 用于文章元数据与站点地图数据的 Nuxt Content 集合工厂
-- Markdown、MDC 组件、Shiki 代码高亮、KaTeX、Mermaid、ABC 乐谱与富图片
-- 文章列表、归档、分页、目录（TOC）、搜索、主题切换、小部件、预览与 404 路由
-- Atom、OPML、统计、robots、sitemap 与 LLMs 输出
-- 由使用方配置驱动的 Twikoo、head 脚本与反镜像集成
-- UI 默认值、app config 覆盖、自定义 Shiki 主题与同路径组件覆盖
-- 自动化的 workspace、tarball 消费者、SSR、浏览器、水合、纯度、契约、peer 与上游同步检查
-
-## 环境要求
+## 为什么选择 Clarity？
 
-| 运行时 | 版本 |
-| --- | --- |
-| Node.js | `^22.19 \|\| ^24.11 \|\| >=26` |
-| pnpm | 12.4.1，或适用于你项目的兼容包管理器 |
-| Nuxt peer | `^4.5.2` |
-| Vue peer | `^3.5.42` |
+Clarity 取代传统的 sync fork 工作流。你不需要把上游数千行代码合并进博客仓库，而是以 Layer 方式消费主题，只维护自己的文件：
 
-Clarity 已通过 npm 注册表以 `clarity-theme` 分发。它属于应用运行时的一部分（Nuxt 构建与静态生成会直接加载 Layer），因此请将其安装为常规依赖（dependency），而不是开发依赖（devDependency）；生产环境安装也必须能解析到它。
+- **一条 `extends` 配置**即可安装完整的博客应用骨架
+- **Theme 与 Consumer 分离**：文章、友链、重定向、部署配置、密钥与依赖补丁永远不会进入主题包
+- **配置带校验**：`clarity.config.ts` 由 schema 校验，提供默认值并严格拒绝未知字段
+- **Content 工厂**：Nuxt Content 集合与文章 schema 由你的配置派生
+- **富渲染**：Markdown、MDC 组件、Shiki 代码高亮、KaTeX、Mermaid、ABC 乐谱与富图片
+- **完整输出**：文章列表、归档、分页、目录（TOC）、搜索、主题切换、小部件、Atom、OPML、统计、robots、sitemap 与 LLMs
+- **集成仍归你所有**：Twikoo、head 脚本与反镜像均由消费方配置驱动
+- **覆盖而无需 fork**：UI app config 覆盖、同路径组件覆盖、自定义 Shiki 主题与消费方 CSS
 
-## 安装
+## 选择你的路径
 
-```bash
-pnpm add clarity-theme
-```
+| 起点 | 文档 |
+| --- | --- |
+| 新博客 | [创建项目](./docs/getting-started/new-project.zh-CN.md) |
+| 现有 blog-v3 站点 | [从 blog-v3 迁移](./docs/getting-started/migration-from-blog-v3.zh-CN.md) · Agent Skill：`migrate-blog-v3-to-clarity` |
+| 手动接入现有 Nuxt 应用 | [手动安装](./docs/getting-started/manual-installation.zh-CN.md) |
 
-### Git commit 安装（开发回退方式）
+如需 Agent 协助迁移，直接让你的 Agent 使用 `migrate-blog-v3-to-clarity` Skill。完整 Skill 位于 [`skills/migrate-blog-v3-to-clarity`](./skills/migrate-blog-v3-to-clarity/SKILL.md)。
 
-如需使用未发布的 commit、本地调试，或在发布前审查某个具体变更，可以直接从 GitHub 安装：
+## 快速开始
 
 ```bash
-pnpm add github:iicemeta/clarity-theme#<commit>
+pnpm create clarity-theme@beta my-blog
+cd my-blog
+pnpm dev
 ```
 
-该方式仅用于开发场景。正式站点应使用已发布的 npm 版本，以保证安装可复现并被发布验证矩阵覆盖。
-
-## 快速开始
-
-### 1. 继承 Layer
+创建包以独立的 `create-clarity-theme` npm 包分发；当前初始预发布位于 `@beta` dist-tag。完整参数见 [`create-clarity-theme/README.md`](./create-clarity-theme/README.md)。手动接入只需四个文件：
 
 ```ts
 // nuxt.config.ts
@@ -54,8 +48,6 @@ export default defineNuxtConfig({
 })
 ```
 
-### 2. 定义站点配置
-
 ```ts
 // clarity.config.ts
 import { defineClarityConfig } from 'clarity-theme/config'
@@ -65,18 +57,11 @@ export default defineClarityConfig({
 		title: 'My Blog',
 		description: 'Notes about technology and life',
 		url: 'https://example.com/',
-		author: {
-			name: 'My Name',
-			avatar: '/avatar.webp',
-		},
+		author: { name: 'My Name', avatar: '/avatar.webp' },
 	},
 })
 ```
 
-`site.title`、`site.description`、`site.url` 与 `site.author.name` 为必填项。article、feed、stats、integration、feature 与 changelog 分组均为可选，并使用文档中记载的默认值。
-
-### 3. 创建 Content schema
-
 ```ts
 // content.config.ts
 import { createClarityContentConfig } from 'clarity-theme/content'
@@ -85,227 +70,47 @@ import clarityConfig from './clarity.config'
 export default createClarityContentConfig(clarityConfig)
 ```
 
-文章放在 `content/posts/` 下，其他 Content 页面放在 `content/` 下。
-
-### 4. 可选：提供友链数据
-
-```ts
-// feeds.ts
-import type { FeedGroup } from 'clarity-theme/config'
-
-const feeds: FeedGroup[] = []
-
-export default feeds
-```
-
-如果没有这个文件，友链页面和 OPML 输出会使用空数据，并且构建时会记录一条警告。
-
-### 5. 生成或开发
-
 ```bash
+pnpm add clarity-theme
 pnpm dev
-pnpm generate
-```
-
-从现有 blog-v3 项目完整迁移的操作流程，见[迁移指南](./docs/MIGRATION.zh-CN.md)。主题数据与用户内容是被刻意分开的：这个包永远不会携带你的文章、友链、重定向、部署配置或包补丁。
-
-## 从 blog-v3 迁移
-
-完整的人工迁移指南见[迁移指南](./docs/MIGRATION.zh-CN.md)。如果你希望让当前 Agent 使用 `migrate-blog-v3-to-clarity` Skill 自动执行迁移，可以直接使用下面的提示词：
-
-```markdown
-请使用 `migrate-blog-v3-to-clarity` Skill，把当前这个 blog-v3 项目迁移到 Clarity Theme。
-
-要求：
-
-1. 先只读扫描项目，不立即修改。
-2. 判断当前项目是否属于支持的 blog-v3 结构。
-3. 检查 blog.config.ts、app/app.config.ts、content.config.ts、nuxt.config.ts、feeds.ts、redirects.json、patches、content、public、custom components、server、modules。
-4. 生成迁移计划，并把所有风险项标出来。
-5. 不修改文章正文和 frontmatter。
-6. 不删除 content、public、redirects、patches 或未知自定义代码。
-7. 能自动迁移的部分自动处理。
-8. 需要人工判断的部分暂停修改并记录原因。
-9. 迁移完成后执行 typecheck、generate 和兼容性验证。
-10. 最后输出完整 migration report，包括修改文件、保留配置、人工处理项和测试结果。
-
-整个过程只使用当前 Agent 串行执行，不启动并行 Agent。
-```
-
-## 基础配置
-
-| 文件 | 职责 |
-| --- | --- |
-| `clarity.config.ts` | 站点身份、文章语义、友链、统计、集成、功能开关、更新日志 |
-| `app/app.config.ts` | 仅限可选的响应式 UI 覆盖 |
-| `content.config.ts` | Nuxt Content 集合/schema |
-| `feeds.ts` | 可选的友链数据 |
-| 使用方 `runtimeConfig` | 环境相关配置，以及唯一合法的密钥存放位置 |
-
-逐字段的默认值、可见性与示例见[配置说明](./docs/CONFIGURATION.zh-CN.md)。
-
-可选分组示例：
-
-```ts
-export default defineClarityConfig({
-	site: {
-		title: 'My Blog',
-		description: 'A Nuxt blog',
-		url: 'https://example.com/',
-		author: { name: 'My Name' },
-	},
-	article: {
-		defaultCategory: 'Uncategorized',
-		categories: {
-			Tech: { icon: 'tabler:code', color: '#7777ff' },
-		},
-		types: { tech: {}, story: {} },
-	},
-	feed: { limit: 50, enableStyle: true },
-	features: {
-		atom: true,
-		opml: true,
-		stats: true,
-		antiMirror: false,
-	},
-})
 ```
 
-绝不要把 token 或私有部署凭据放在 `clarity.config.ts` 或 `app/app.config.ts` 中；这两者都可能影响生成的客户端产物。
+文章放在 `content/posts/` 下，其他 Content 页面放在 `content/` 下。可选的 `feeds.ts` 友链数据与部署说明见[手动安装](./docs/getting-started/manual-installation.zh-CN.md)。
 
-## 公共 API
+## 环境要求
 
-| 入口 | API |
+| 运行时 | 版本 |
 | --- | --- |
-| `clarity-theme` | Nuxt Layer 根入口 |
-| `clarity-theme/config` | `defineClarityConfig()` 与配置/schema 类型 |
-| `clarity-theme/content` | `createClarityContentConfig()` 与 `ArticleSchema` |
-| `clarity-theme/schema` | 全部 `clarity*` Zod schema 及派生类型 |
-| `clarity-theme/img` | 头像/favicon/图片 URL 辅助函数 |
-
-Layer 还暴露了 `useClarityConfig()`、`useClaritySite()`、`useClarityArticle()` 与 `useClaritySiteFeedEntry()` 运行时自动导入，以及 `#clarity/feeds` 注入。它们是 Layer 契约，而不是独立的包子路径。
-
-确切的导出/类型边界记录在 [API 文档](./docs/API.zh-CN.md) 中。
-
-## 自定义
-
-### UI 配置
-
-```ts
-// app/app.config.ts
-export default defineAppConfig({
-	clarity: {
-		header: { emojiTail: ['📝'] },
-		pagination: { perPage: 10 },
-		nav: [
-			{
-				title: '',
-				items: [
-					{ icon: 'tabler:files', text: 'Articles', url: '/' },
-					{ icon: 'tabler:link', text: 'Friends', url: '/link' },
-					{ icon: 'tabler:archive', text: 'Archive', url: '/archive' },
-				],
-			},
-		],
-	},
-})
-```
-
-对象会深度合并；数组会整体替换主题的值。
-
-### 组件
-
-在使用方项目中创建同路径的 Layer 相对组件即可替换，例如：
-
-```text
-app/components/content/Badge.vue
-```
-
-使用方组件优先于 Layer 组件。Nuxt 目前会针对这种有意的覆盖模式输出重名警告。
-
-### Shiki 主题
-
-在使用方项目中提供 `app/shiki.config.ts`。只有当该文件不存在时，才会使用主题的回退配置。
-
-UI 分组、同路径组件覆盖、CSS 覆盖、服务端/路由自定义与 Shiki 归属详见[自定义说明](./docs/CUSTOMIZATION.zh-CN.md)。
-
-## 兼容性与验证
-
-验证套件覆盖：
-
-- Playground 静态生成
-- 独立的 `pnpm pack` 消费者安装
-- Node 与 TypeScript 中的五个包导出
-- 三种配置分支
-- Markdown/MDC/代码/数学公式/Mermaid/乐谱/图片渲染
-- 生产 SSR、真实浏览器渲染与开发水合
-- 搜索、分页、归档、TOC、SEO、robots、sitemap、LLMs、Atom、OPML、统计、固定链接、404、Twikoo 分支、反镜像注入、UI 覆盖与组件覆盖
-- 主题纯度、peer 依赖、同步工具与上游漂移
-
-生成的发布矩阵见[兼容性说明](./docs/COMPATIBILITY.zh-CN.md)。当前的精确数量、已知限制、技术债与发布阻塞项见[项目状态](./docs/PROJECT-STATUS.zh-CN.md)与[路线图](./docs/ROADMAP.zh-CN.md)。发布前必须在确切的 commit 上重新按顺序运行整套验证；早先的结果不能替代。
+| Node.js | `^22.19 \|\| ^24.11 \|\| >=26` |
+| pnpm | 12.4.1，或适用于你项目的兼容包管理器 |
+| Nuxt peer | `^4.5.2` |
+| Vue peer | `^3.5.42` |
 
-站点相关的依赖补丁刻意由使用方持有；见[补丁说明](./docs/PATCHES.zh-CN.md)。
+Clarity 属于应用运行时的一部分（Nuxt 构建与静态生成会直接加载 Layer），因此请将其安装为常规依赖，而不是开发依赖。
 
 ## 文档
 
-| 文档 | 用途 |
-| --- | --- |
-| [项目状态](./docs/PROJECT-STATUS.zh-CN.md) | 当前快照、已验证能力、限制、技术债、缺口与里程碑 |
-| [路线图](./docs/ROADMAP.zh-CN.md) | 按优先级排序的 P0/P1/P2 技术债清单、延后决策与里程碑顺序 |
-| [迁移指南](./docs/MIGRATION.zh-CN.md) | 在采用 Clarity 的同时保留 blog-v3 的内容、配置、重定向、补丁、自定义代码与资源 |
-| [架构](./docs/ARCHITECTURE.zh-CN.md) | 主题/使用方边界与构建/运行时数据流 |
-| [API](./docs/API.zh-CN.md) | 公共包/Layer API 与内部实现的边界 |
-| [配置说明](./docs/CONFIGURATION.zh-CN.md) | 字段级 Clarity 配置契约与示例 |
-| [自定义说明](./docs/CUSTOMIZATION.zh-CN.md) | UI、组件、Shiki、CSS、服务端与路由覆盖 |
-| [兼容性说明](./docs/COMPATIBILITY.zh-CN.md) | 生成的发布兼容性矩阵 |
-| [上游同步](./docs/UPSTREAM.zh-CN.md) | 基线、manifest、命令、冲突与工作流 |
-| [补丁说明](./docs/PATCHES.zh-CN.md) | 使用方补丁归属与当前结论 |
-| [发布审计](./docs/RELEASE-AUDIT.zh-CN.md) | 收尾前工程审计与剩余发布门槛 |
-| [发布清单](./docs/RELEASE-CHECKLIST.zh-CN.md) | 确切的最终检查、剩余阻塞项与验证证据 |
-| [发布指南](./docs/PUBLISHING.zh-CN.md) | 版本管理、tag、GitHub Release、OIDC 发布、provenance 与回滚策略 |
-| [更新日志](./CHANGELOG.md) | 面向使用者的发布历史 |
-| [抽取历史](./docs/history/2026-09-layer-extraction.zh-CN.md) | 历史阶段与一次性差分验证 |
+所有文档都有对应的简体中文版本（同名 `*.zh-CN.md` 文件）。入口见[文档索引](./docs/README.zh-CN.md)：
+
+- **入门** — [创建新项目](./docs/getting-started/new-project.zh-CN.md)、[手动安装](./docs/getting-started/manual-installation.zh-CN.md)、[从 blog-v3 迁移](./docs/getting-started/migration-from-blog-v3.zh-CN.md)
+- **指南** — [配置](./docs/guides/configuration.zh-CN.md)、[内容](./docs/guides/content.zh-CN.md)、[自定义](./docs/guides/customization.zh-CN.md)、[集成](./docs/guides/integrations.zh-CN.md)
+- **参考** — [公共 API](./docs/reference/api.zh-CN.md)、[路由与输出](./docs/reference/routes-and-outputs.zh-CN.md)、[兼容性矩阵](./docs/reference/compatibility.zh-CN.md)
+- **概念** — [架构](./docs/concepts/architecture.zh-CN.md)
+- **维护者** — [开发](./docs/maintainers/development.zh-CN.md)、[测试](./docs/maintainers/testing.zh-CN.md)、[上游同步](./docs/maintainers/upstream-sync.zh-CN.md)、[补丁](./docs/maintainers/patches.zh-CN.md)、[发布](./docs/maintainers/publishing.zh-CN.md)、[发布清单](./docs/maintainers/release-checklist.zh-CN.md)、[项目状态](./docs/maintainers/project-status.zh-CN.md)、[路线图](./docs/maintainers/roadmap.zh-CN.md)、[文档规则](./docs/maintainers/documentation.zh-CN.md)
+- **发布历史** — [CHANGELOG](./CHANGELOG.md)；历史记录位于 [docs/history](./docs/history/)
 
 ## 开发
 
 ```bash
-pnpm install              # 主题 + playground workspace
-pnpm dev                  # Playground 开发服务器
-pnpm generate             # Playground 静态生成
-pnpm lint
+pnpm install        # Theme + playground workspace
+pnpm dev            # Playground dev server
+pnpm generate       # Playground static generation
+pnpm lint           # ESLint + Stylelint
 pnpm typecheck
-pnpm verify               # 纯度/静态泄漏检查
-pnpm peers check
-pnpm test:sync
-pnpm test:migration
-pnpm test:contract
-pnpm test:consumer
-pnpm test:compatibility
-```
-
-CI 从包元数据推导 Node 与 pnpm 版本。它先在固定的 Node 矩阵上运行 lint/typecheck/verify/sync/migration/contract/peers，再在主 Node 版本上运行 playground 生成、真实消费者验收与渲染兼容性。另有一个每周工作流只检测并报告上游漂移。
-
-确切的 CI 阶段与权限见[项目状态 → CI](./docs/PROJECT-STATUS.zh-CN.md#10-ci)。
-
-## 上游同步
-
-Clarity 从一个上游 Nuxt 博客抽取而来，并在 `sync-manifest.json` 中记录确切的已审查基线。同步工具区分可直接包含的路径、使用方持有的排除项、经过转换的主题契约与人工审查路径；未知的上游变更会阻止 apply。使用：
-
-```bash
-pnpm sync:check   # 比较 manifest 基线与远端
-pnpm sync:diff    # 对上游变更分类
-pnpm sync:apply   # 事务式应用已审查的 include-only 变更
-pnpm sync:verify  # 重新运行主题纯度与基线检查
 ```
 
-每周工作流只检测并报告漂移，绝不会 apply、commit 或 push 变更。见[上游同步](./docs/UPSTREAM.zh-CN.md)。
-
-## 发布状态
-
-Clarity Theme 是一个 **v0.1.1 门禁 npm 发布版本**。Layer/包边界、已校验配置、Content 工厂、渲染管线、服务端输出、playground、真实消费者验收、兼容性矩阵、三层 CI、上游同步基线、发布门禁与 OIDC 发布工作流均已实现。剩余的人工发布步骤见[发布检查清单](./docs/RELEASE-CHECKLIST.zh-CN.md)。
-
-[路线图](./docs/ROADMAP.zh-CN.md)中的 v0.1.0 正确性门禁已解决：服务端/客户端配置已拆分、功能关闭路由在运行时返回 404、反镜像导航已在真实浏览器中验证、no-op 随机固定链接字段已移除，多模式统计已增加回归测试。其余推迟事项记录在路线图与发布说明中。
+完整验证矩阵、上游同步与发布流程见[开发](./docs/maintainers/development.zh-CN.md)与[测试](./docs/maintainers/testing.zh-CN.md)。
 
 ## 许可证
 
-主题代码采用 MIT 许可证。上游博客的文章不包含在本包中。
+主题代码为 MIT。上游博客的文章不包含在本包中。

package/nuxt.config.ts

@@ -12,13 +12,13 @@ const toThemePath = (path: string) => join(themeDir, path).replaceAll('\\', '/')
 function pluginPath(path: string) {
 	// 插件必须是 .mjs：@nuxt/content 以 Node 原生方式加载，
 	// 不允许 node_modules 内的 TS 文件（TS 剥离限制）
-	return pathToFileURL(join(themeDir, 'remark-plugins', `${path}.mjs`)).href
+	return pathToFileURL(join(themeDir, 'src', 'remark-plugins', `${path}.mjs`)).href
 }
 
 /**
  * Clarity Theme Layer 配置
  *
- * 站点数据（SEO、favicon、scripts 等）由 modules/clarity-config
+ * 站点数据（SEO、favicon、scripts 等）由 src/modules/clarity-config
  * 读取消费项目的 clarity.config.ts 后统一注入，此处仅包含 Theme 自身能力。
  */
 export default defineNuxtConfig({
@@ -50,18 +50,18 @@ export default defineNuxtConfig({
 	compatibilityDate: '2024-08-03',
 
 	components: [
-		{ path: toThemePath('app/components/partial'), prefix: 'Z' },
-		toThemePath('app/components'),
+		{ path: toThemePath('src/components/partial'), prefix: 'Z' },
+		toThemePath('src/components'),
 	],
 
 	// @keep-sorted
 	css: [
-		toThemePath('app/assets/css/animation.scss'),
-		toThemePath('app/assets/css/article.scss'),
-		toThemePath('app/assets/css/color.scss'),
-		toThemePath('app/assets/css/font.scss'),
-		toThemePath('app/assets/css/main.scss'),
-		toThemePath('app/assets/css/reusable.scss'),
+		toThemePath('src/assets/css/animation.scss'),
+		toThemePath('src/assets/css/article.scss'),
+		toThemePath('src/assets/css/color.scss'),
+		toThemePath('src/assets/css/font.scss'),
+		toThemePath('src/assets/css/main.scss'),
+		toThemePath('src/assets/css/reusable.scss'),
 	],
 
 	// @keep-sorted
@@ -72,6 +72,9 @@ export default defineNuxtConfig({
 
 	// @keep-sorted
 	modules: [
+		// 必须最先运行：把 src/ 仅应用到 Clarity 自身 layer，避免静态
+		// srcDir / serverDir / dir.* 经 c12 合并泄漏到 consumer root 配置。
+		toThemePath('src/modules/clarity-source-layout'),
 		'@bikariya/image-viewer',
 		'@bikariya/modals',
 		'@bikariya/shiki',
@@ -84,7 +87,7 @@ export default defineNuxtConfig({
 		'@vueuse/nuxt',
 		// Layer 配置中的相对 module 路径会以消费项目为基准解析，必须使用绝对路径；
 		// 且 clarity-config 必须先于 nuxt-llms 运行：后者在 setup 时读取注入的 llms 站点配置
-		toThemePath('modules/clarity-config'),
+		toThemePath('src/modules/clarity-config'),
 		'nuxt-llms',
 	],
 
@@ -112,8 +115,8 @@ export default defineNuxtConfig({
 		nodeTsConfig: {
 			// @keep-sorted
 			include: [
-				'../config/**/*.ts',
-				'../remark-plugins/**/*.ts',
+				'../src/config/**/*.ts',
+				'../src/remark-plugins/**/*.ts',
 			],
 		},
 	},
@@ -122,7 +125,7 @@ export default defineNuxtConfig({
 		css: {
 			preprocessorOptions: {
 				scss: {
-					additionalData: `@use "${toThemePath('app/assets/css/_variable.scss')}" as *;`,
+					additionalData: `@use "${toThemePath('src/assets/css/_variable.scss')}" as *;`,
 				},
 			},
 		},
@@ -189,7 +192,7 @@ ${homepage}
 
 	icon: {
 		customCollections: [
-			{ prefix: 'clarity', dir: toThemePath('app/assets/icons') },
+			{ prefix: 'clarity', dir: toThemePath('src/assets/icons') },
 		],
 		clientBundle: {
 			scan: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clarity-theme",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Clarity Theme — 从 blog-v3 提取的可复用 Nuxt 4 Layer 博客主题",
   "license": "MIT",
   "publishConfig": {
@@ -18,36 +18,29 @@
   "exports": {
     ".": "./nuxt.config.ts",
     "./config": {
-      "types": "./config/index.d.mts",
-      "default": "./config/index.mjs"
+      "types": "./src/config/index.d.mts",
+      "default": "./src/config/index.mjs"
     },
     "./content": {
-      "types": "./config/content.d.mts",
-      "default": "./config/content.mjs"
+      "types": "./src/config/content.d.mts",
+      "default": "./src/config/content.mjs"
     },
     "./img": {
-      "types": "./img/index.d.mts",
-      "default": "./img/index.mjs"
+      "types": "./src/img/index.d.mts",
+      "default": "./src/img/index.mjs"
     },
     "./schema": {
-      "types": "./config/schema.d.mts",
-      "default": "./config/schema.mjs"
+      "types": "./src/config/schema.d.mts",
+      "default": "./src/config/schema.mjs"
     }
   },
   "main": "./nuxt.config.ts",
   "files": [
     "LICENSE",
     "README.md",
-    "app",
-    "config",
-    "img",
-    "modules",
     "nuxt.config.ts",
     "package.json",
-    "public",
-    "remark-plugins",
-    "server",
-    "shared"
+    "src"
   ],
   "engines": {
     "node": "^22.19 || ^24.11 || >=26"
@@ -112,6 +105,7 @@
     "@nuxt/hints": "^1.1.4",
     "@stylistic/stylelint-plugin": "^5.2.1",
     "@types/hast": "^3.0.5",
+    "@types/mdast": "^4.0.4",
     "@zinkawaii/stylelint-config": "^0.5.2",
     "cspell": "^10.2.2",
     "eslint": "^10.10.0",
@@ -132,9 +126,10 @@
     "dev": "pnpm --dir playground dev",
     "build": "pnpm --dir playground build",
     "generate": "pnpm --dir playground generate",
-    "lint": "eslint && stylelint \"app/**/*.{vue,scss}\" \"playground/app/**/*.vue\"",
-    "lint:fix": "eslint --fix && stylelint \"app/**/*.{vue,scss}\" \"playground/app/**/*.vue\" --fix",
+    "lint": "eslint && stylelint \"src/**/*.{vue,scss}\" \"playground/app/**/*.vue\"",
+    "lint:fix": "eslint --fix && stylelint \"src/**/*.{vue,scss}\" \"playground/app/**/*.vue\" --fix",
     "typecheck": "pnpm --dir playground typecheck",
+    "docs:check": "node scripts/check-docs.mjs",
     "verify": "node scripts/verify-theme.mjs",
     "test:sync": "node --test tests/sync-upstream.test.mjs",
     "test:migration": "node --test tests/migration-skill.test.mjs",
@@ -142,6 +137,9 @@
     "test:release": "pnpm verify && pnpm test:consumer && pnpm test:compatibility",
     "test:consumer": "node scripts/test-consumer.mjs",
     "test:compatibility": "node scripts/test-compatibility.mjs",
+    "test:create": "pnpm --dir create-clarity-theme test",
+    "test:create:e2e": "pnpm --dir create-clarity-theme test:e2e",
+    "test:create:tarball": "pnpm --dir create-clarity-theme test:tarball",
     "test:registry-consumer": "node scripts/test-registry-consumer.mjs",
     "release:check": "node scripts/release-check.mjs",
     "sync:check": "node scripts/sync-upstream.mjs check",

package/{app → src}/app.config.ts

@@ -2,7 +2,7 @@
  * Clarity Theme UI 默认配置。
  *
  * 站点数据（标题、作者、文章分类等）来自根目录 clarity.config.ts，
- * 由 modules/clarity-config 注入到 appConfig.clarity 中。
+ * 由 src/modules/clarity-config 注入到 appConfig.clarity 中。
  *
  * 消费项目可在自己的 app/app.config.ts 中按需覆盖任意键。
  */

package/{app → src}/components/widget/BlogTech.vue

@@ -27,6 +27,8 @@ const ciPlatform = computed(() => {
 
 const service = computed(() => ([
 	...ci ? [{ label: '构建平台', value: ciPlatform }] : [],
+	{ label: '图片存储', value: () => [h(Icon, { name: 'devicon:cloudflare' }), ' R2'] },
+	{ label: '软件协议', value: 'MIT' },
 	{ label: '文章许可', value: clarity.site.copyright?.abbr || '未配置' },
 	{ label: '规范域名', value: getDomain(clarity.site.url) },
 ]))

package/{app → src}/composables/useArticle.ts

@@ -1,5 +1,5 @@
-import type { MetaSlotsTree } from '../../remark-plugins/rehype-meta-slots'
-import type { ClarityContentRow } from '../../shared/types/content'
+import type { MetaSlotsTree } from '../remark-plugins/rehype-meta-slots'
+import type { ClarityContentRow } from '../shared/types/content'
 import type { ArticleOrderType, ArticleProps } from '../types/article'
 import { orderBy } from 'es-toolkit/array'
 

package/{config → src/config}/app.ts

@@ -1,4 +1,4 @@
-import type { NavItem } from '../app/types/nav'
+import type { NavItem } from '../types/nav'
 import type { ClarityPublicConfig } from './public'
 
 export interface NavGroup {

package/{config → src/config}/define.mjs

@@ -13,7 +13,7 @@ export function defineClarityConfig(config) {
 			.join('\n')
 		throw new Error(
 			`clarity.config.ts 校验失败：\n${issues}\n`
-			+ '未知字段会被拒绝：请检查拼写，或参考 docs/config-api-audit.md 的字段归属表。',
+			+ '未知字段会被拒绝：请检查拼写，或参考 docs/guides/configuration.md 的字段契约。',
 			{ cause: result.error },
 		)
 	}

package/{config → src/config}/define.ts

@@ -15,7 +15,7 @@ export function defineClarityConfig(config: ClarityConfigInput): ClarityConfig {
 			.join('\n')
 		throw new Error(
 			`clarity.config.ts 校验失败：\n${issues}\n`
-			+ '未知字段会被拒绝：请检查拼写，或参考 docs/config-api-audit.md 的字段归属表。',
+			+ '未知字段会被拒绝：请检查拼写，或参考 docs/guides/configuration.md 的字段契约。',
 			{ cause: result.error },
 		)
 	}

package/{config → src/config}/feeds.empty.ts

@@ -1,4 +1,4 @@
-import type { FeedGroup } from '../app/types/feed'
+import type { FeedGroup } from '../types/feed'
 
 /** 消费项目未提供 feeds.ts 时的空数据兜底 */
 const emptyFeeds: FeedGroup[] = []

package/{config → src/config}/index.ts

@@ -1,4 +1,4 @@
-export type { Nav, NavItem } from '../app/types/nav'
+export type { Nav, NavItem } from '../types/nav'
 export type { ClarityAppConfig, ClarityUiConfig, ClarityUiConfigInput, NavGroup } from './app'
 export { defineClarityConfig } from './define'
 export type { Arch, FeedEntry, FeedGroup } from './feed'

package/{config → src/config}/public.ts

@@ -10,7 +10,7 @@ import type {
 /**
  * 由 clarity.config.ts 注入 appConfig 的客户端可见配置。
  *
- * 可见性约定（详见 docs/config-api-audit.md）：
+ * 可见性约定（详见 docs/guides/configuration.md）：
  * - 只有客户端渲染确实需要的字段进入 appConfig；
  * - feed、完整 stats、features 与 site.author.email 等服务端/构建期字段
  *   改由 Nitro 私有 runtimeConfig 提供（config/server.ts），不进入客户端 bundle；

package/{img → src/img}/index.ts

@@ -1,8 +1,8 @@
 /**
  * `clarity-theme/img` 类型真源。
  *
- * 类型实现复用 `app/utils/img.ts`（Layer 内部与包导出共享同一份签名），
+ * 类型实现复用 `src/utils/img.ts`（Layer 内部与包导出共享同一份签名），
  * 运行时实现在同目录 index.mjs：Node 原生 TS 剥离不允许
  * node_modules 内的 TS 文件，因此包入口运行时必须是 .mjs。
  */
-export * from '../app/utils/img'
+export * from '../utils/img'