clarity-theme 0.1.0 → 0.1.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 Zhilu
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2024 Zhilu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.md

@@ -25,14 +25,24 @@ Clarity Theme is a reusable **Nuxt 4 Layer blog theme** extracted from [L33Z22L1
 | Nuxt peer | `^4.5.2` |
 | Vue peer | `^3.5.42` |
 
-The package is not currently available from the npm registry. Install it as a Git dependency pinned to a reviewed commit until the first package release is published. Clarity is part of your application runtime, so install it as a regular dependency rather than a development dependency.
+Clarity is available from the npm registry as `clarity-theme`. It is part of your application runtime (the Nuxt build and static generation load the Layer directly), so install it as a regular dependency rather than a development dependency; a production install must still be able to resolve it.
 
 ## Installation
 
+```bash
+pnpm add clarity-theme
+```
+
+### Git commit installation (development fallback)
+
+For unreleased commits, local debugging, or reviewing a specific change before it is published, install directly from GitHub instead:
+
 ```bash
 pnpm add github:iicemeta/clarity-theme#<commit>
 ```
 
+This path is intended for development only. Released sites should consume the published npm version so installs are reproducible and covered by the release verification matrix.
+
 ## Quick Start
 
 ### 1. Extend the Layer
@@ -83,7 +93,9 @@ Place articles under `content/posts/` and other Content pages under `content/`.
 // feeds.ts
 import type { FeedGroup } from 'clarity-theme/config'
 
-export default [] satisfies FeedGroup[]
+const feeds: FeedGroup[] = []
+
+export default feeds
 ```
 
 Without this file, the friend page and OPML output use empty data and the build logs a warning.
@@ -229,8 +241,61 @@ All documents are also available in 简体中文 as sibling `*.zh-CN.md` files.
 | [Patches](./docs/PATCHES.md) | Consumer patch ownership and current conclusions |
 | [Release audit](./docs/RELEASE-AUDIT.md) | Pre-closing engineering audit and remaining release gates |
 | [Release checklist](./docs/RELEASE-CHECKLIST.md) | Exact final checks, remaining blockers, and verification evidence |
+| [Publishing](./docs/PUBLISHING.md) | Versioning, tags, GitHub Releases, OIDC publishing, provenance, and rollback policy |
+| [Changelog](./CHANGELOG.md) | Consumer-facing release history |
 | [Extraction history](./docs/history/2026-09-layer-extraction.md) | Historical phases and one-time differential validation |
 
+## Repository Layout
+
+The repository root is the engineering layer; all Theme runtime source lives
+under `src/`:
+
+```
+clarity-theme/
+├─ src/                  # Theme runtime source (Layer srcDir)
+│  ├─ assets/ components/ composables/ layouts/ middleware/
+│  ├─ pages/ plugins/ stores/ types/ utils/
+│  ├─ app.config.ts app.vue error.vue shiki.config.ts
+│  ├─ config/            # config API sources (npm ./config ./content ./schema)
+│  ├─ img/               # img API sources (npm ./img)
+│  ├─ modules/           # source-layout bootstrap + clarity-config modules
+│  ├─ public/ server/ shared/ remark-plugins/
+├─ skills/               # Agent workflow skills (not part of the npm package)
+├─ docs/                 # Human documentation
+├─ playground/           # Workspace-linked development consumer
+├─ scripts/  tests/      # Verification and tooling
+└─ nuxt.config.ts, package.json, sync-manifest.json, …
+```
+
+`nuxt.config.ts` stays at the package root. Its first module,
+`src/modules/clarity-source-layout`, applies the `src/` directory metadata to
+the Clarity layer only; static `srcDir`/`serverDir`/`dir.*` values are not
+used because c12 would merge them into consumer root config. npm, Git-commit,
+and local-directory installs therefore resolve the same layout without
+overriding a consumer's own application directories.
+
+The npm package, the Agent skill, and the docs are three separate concerns:
+
+- **`clarity-theme` (npm package)** — the runtime Nuxt Layer installed with
+  `extends: ['clarity-theme']`. Its `files` field ships only `src/` plus the
+  root entry files; dev assets never enter the tarball.
+- **`skills/migrate-blog-v3-to-clarity`** — the canonical Agent workflow for
+  migrating an existing blog-v3 project. It is versioned with the repository
+  but intentionally **not** bundled into the npm package.
+- **`docs/`** — human-readable documentation mirrored in English and Chinese.
+
+### Installing the migration skill
+
+```bash
+npx skills add iicemeta/clarity-theme --list   # discover available skills
+npx skills add iicemeta/clarity-theme --skill migrate-blog-v3-to-clarity
+```
+
+For development, `npx skills add ./skills --list` discovers the local copy.
+To migrate a blog-v3 site with an Agent, ask it to use the
+`migrate-blog-v3-to-clarity` skill; the human walkthrough remains
+[Migration](./docs/MIGRATION.md).
+
 ## Development
 
 ```bash
@@ -246,6 +311,7 @@ pnpm test:migration
 pnpm test:contract
 pnpm test:consumer
 pnpm test:compatibility
+pnpm pack --dry-run       # inspect the npm tarball without writing it
 ```
 
 CI derives Node and pnpm versions from package metadata. It runs lint/typecheck/verify/sync/migration/contract/peers on the fixed Node matrix, then playground generate, real consumer acceptance, and rendering compatibility on the primary Node version. A separate weekly workflow only detects and reports upstream drift.
@@ -267,9 +333,9 @@ The weekly workflow only detects and reports drift. It never applies, commits, o
 
 ## Release Status
 
-Clarity Theme is a **v0.1.0 pre-publish Layer candidate**. The Layer/package boundary, validated configuration, Content factory, rendering pipeline, server outputs, playground, real-consumer acceptance, compatibility matrix, three-layer CI, and upstream-sync baseline are implemented.
+Clarity Theme is a **v0.1.2 gated npm release**. The Layer/package boundary, validated configuration, Content factory, rendering pipeline, server outputs, playground, real-consumer acceptance, compatibility matrix, three-layer CI, upstream-sync baseline, release gate, and OIDC publish workflow are implemented. See the [release checklist](./docs/RELEASE-CHECKLIST.md) for the exact remaining manual publication steps.
 
-The first npm release is intentionally still blocked by the P0 correctness items in [Roadmap](./docs/ROADMAP.md)—especially the server/client configuration split, feature-off route semantics, anti-mirror navigation verification, and the no-op random-permalink contract—and by an exact-commit release run. Migration documentation and repeatability are being completed in this release-closing phase.
+The v0.1.0 correctness gates from [Roadmap](./docs/ROADMAP.md) are resolved: server/client configuration is split, feature-off routes return 404 at runtime, anti-mirror navigation is verified in a real browser, the no-op random-permalink field is removed, and multi-pattern stats are covered by a regression test. Remaining deferred items are recorded in the roadmap and release notes.
 
 ## License
 

package/README.zh-CN.md

@@ -25,14 +25,24 @@ Clarity Theme 是一个从 [L33Z22L11/blog-v3](https://github.com/L33Z22L11/blog
 | Nuxt peer | `^4.5.2` |
 | Vue peer | `^3.5.42` |
 
-该包目前尚未发布到 npm 注册表。在第一个包版本发布之前，请以锁定到已审查 commit 的 Git 依赖方式安装。Clarity 属于应用运行时的一部分，因此请将其安装为常规依赖（dependency），而不是开发依赖（devDependency）。
+Clarity 已通过 npm 注册表以 `clarity-theme` 分发。它属于应用运行时的一部分（Nuxt 构建与静态生成会直接加载 Layer），因此请将其安装为常规依赖（dependency），而不是开发依赖（devDependency）；生产环境安装也必须能解析到它。
 
 ## 安装
 
+```bash
+pnpm add clarity-theme
+```
+
+### Git commit 安装（开发回退方式）
+
+如需使用未发布的 commit、本地调试，或在发布前审查某个具体变更，可以直接从 GitHub 安装：
+
 ```bash
 pnpm add github:iicemeta/clarity-theme#<commit>
 ```
 
+该方式仅用于开发场景。正式站点应使用已发布的 npm 版本，以保证安装可复现并被发布验证矩阵覆盖。
+
 ## 快速开始
 
 ### 1. 继承 Layer
@@ -83,7 +93,9 @@ export default createClarityContentConfig(clarityConfig)
 // feeds.ts
 import type { FeedGroup } from 'clarity-theme/config'
 
-export default [] satisfies FeedGroup[]
+const feeds: FeedGroup[] = []
+
+export default feeds
 ```
 
 如果没有这个文件，友链页面和 OPML 输出会使用空数据，并且构建时会记录一条警告。
@@ -250,8 +262,58 @@ UI 分组、同路径组件覆盖、CSS 覆盖、服务端/路由自定义与 Sh
 | [补丁说明](./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) | 历史阶段与一次性差分验证 |
 
+## 仓库结构
+
+仓库根目录是工程管理层；Theme 的全部运行时源码统一放在 `src/`：
+
+```
+clarity-theme/
+├─ src/                  # Theme 运行时源码（Layer srcDir）
+│  ├─ assets/ components/ composables/ layouts/ middleware/
+│  ├─ pages/ plugins/ stores/ types/ utils/
+│  ├─ app.config.ts app.vue error.vue shiki.config.ts
+│  ├─ config/            # config API 源码（npm ./config ./content ./schema）
+│  ├─ img/               # img API 源码（npm ./img）
+│  ├─ modules/           # source-layout 引导模块 + clarity-config 模块
+│  ├─ public/ server/ shared/ remark-plugins/
+├─ skills/               # Agent 工作流 Skill（不进入 npm 包）
+├─ docs/                 # 人工文档
+├─ playground/           # workspace 链接的开发用消费项目
+├─ scripts/  tests/      # 验证与工具脚本
+└─ nuxt.config.ts、package.json、sync-manifest.json、…
+```
+
+`nuxt.config.ts` 保留在包根目录。它最先加载的
+`src/modules/clarity-source-layout` 只为 Clarity 自身 layer 应用 `src/`
+目录元数据；不静态声明 `srcDir`/`serverDir`/`dir.*`，是因为 c12 会把它们
+合并进未显式覆盖这些键的 consumer root 配置。因此 npm 安装、Git commit
+安装与本地目录安装解析到同一份布局，同时不会覆盖 consumer 自己的
+应用目录。
+
+npm 包、Agent Skill 与文档三者职责分离：
+
+- **`clarity-theme`（npm 包）** — 运行时 Nuxt Layer，通过
+  `extends: ['clarity-theme']` 使用。`files` 只发布 `src/` 与根入口文件，
+  开发资产不会进入 tarball。
+- **`skills/migrate-blog-v3-to-clarity`** — 迁移既有 blog-v3 项目的
+  Agent 工作流 Skill。它与仓库一起版本化，但**刻意不**打进 npm 包。
+- **`docs/`** — 中英双语的人工文档。
+
+### 安装迁移 Skill
+
+```bash
+npx skills add iicemeta/clarity-theme --list   # 发现可用 Skill
+npx skills add iicemeta/clarity-theme --skill migrate-blog-v3-to-clarity
+```
+
+开发环境可用 `npx skills add ./skills --list` 发现本地副本。让 Agent 迁移
+blog-v3 站点时，请让它使用 `migrate-blog-v3-to-clarity` Skill；人工流程
+见[迁移指南](./docs/MIGRATION.zh-CN.md)。
+
 ## 开发
 
 ```bash
@@ -267,6 +329,7 @@ pnpm test:migration
 pnpm test:contract
 pnpm test:consumer
 pnpm test:compatibility
+pnpm pack --dry-run       # 不落盘检查 npm tarball
 ```
 
 CI 从包元数据推导 Node 与 pnpm 版本。它先在固定的 Node 矩阵上运行 lint/typecheck/verify/sync/migration/contract/peers，再在主 Node 版本上运行 playground 生成、真实消费者验收与渲染兼容性。另有一个每周工作流只检测并报告上游漂移。
@@ -288,9 +351,9 @@ pnpm sync:verify  # 重新运行主题纯度与基线检查
 
 ## 发布状态
 
-Clarity Theme 是一个 **v0.1.0 发布前 Layer 候选版本**。Layer/包边界、已校验配置、Content 工厂、渲染管线、服务端输出、playground、真实消费者验收、兼容性矩阵、三层 CI 与上游同步基线均已实现。
+Clarity Theme 是一个 **v0.1.2 门禁 npm 发布版本**。Layer/包边界、已校验配置、Content 工厂、渲染管线、服务端输出、playground、真实消费者验收、兼容性矩阵、三层 CI、上游同步基线、发布门禁与 OIDC 发布工作流均已实现。剩余的人工发布步骤见[发布检查清单](./docs/RELEASE-CHECKLIST.zh-CN.md)。
 
-首次 npm 发布仍被[路线图](./docs/ROADMAP.zh-CN.md)中的 P0 正确性事项刻意阻塞——尤其是服务端/客户端配置拆分、功能关闭时的路由语义、反镜像导航验证与 no-op 随机固定链接契约——同时还需要一次在确切 commit 上的发布运行。迁移文档与可复现性正在本次收尾阶段完成。
+[路线图](./docs/ROADMAP.zh-CN.md)中的 v0.1.0 正确性门禁已解决：服务端/客户端配置已拆分、功能关闭路由在运行时返回 404、反镜像导航已在真实浏览器中验证、no-op 随机固定链接字段已移除，多模式统计已增加回归测试。其余推迟事项记录在路线图与发布说明中。
 
 ## 许可证