用途
shadcn-parity 用于在 udecode/plate 仓库中克隆 shadcn 的实现模式，实现“source-by-source parity”（逐源对照一致）。当用户提出“shadcn parity”、要求镜像 shadcn、复制 shadcn 时使用。
核心契约
当用户要求 shadcn parity 时，应将 ../shadcn 作为 registry 行为和模式的唯一事实来源。不要提供“受 shadcn 启发”的版本，也不要在上游 shadcn 已有模型时另造一个 Plate 专有模型。规则是：上游 schema 优先、上游 resolver 行为优先、上游文件/布局模式优先、上游命名空间语义优先；只有当仓库存在真实约束时才允许 Plate 偏离。
Plate 并不 fork shadcn CLI。不要将 Plate 描述为拥有自定义安装器。Plate 拥有的是围绕上游 shadcn 契约的 registry 与模板同步层。如果发生偏离，必须明确说明原因。
所有权边界
Shadcn 拥有契约，包括：registry item schema；如 @acme/button 这类第三方 registry 的命名空间语义；普通项、命名空间项、URL 和本地文件的 resolver 行为；本地文件 add 行为；components.json registry 语义。
Plate 拥有内容与交付，包括：apps/www/src/registry/* 下的 registry 源文件；apps/www/scripts/build-registry.mts 中的 registry 构建逻辑；apps/www/public/r 与 apps/www/public/rd 下生成的 registry 输出；模板 components.json 中配置的 @plate 命名空间；模板同步工具 tooling/scripts/update-template.sh 与 tooling/scripts/prepare-local-template-registry.mjs。
重要边界：shadcn 拥有 registry item 如何被解析与安装；Plate 拥有 registry 包含什么以及本地模板同步如何喂给它。Plate 的 registry 构建是自定义的，但目标仍是在 item 与 resolver 边界上与上游保持一致。
Registry 规则
Registry item 应尽可能贴近上游 RegistryItem 形态。在构建或修改 Plate registry item 时应：先查看 ../shadcn；在适用时复制上游文件/布局/辅助模式；优先采用上游命名与依赖结构，而非 Plate 专有的新奇做法；将动态的 Plate 特性行为保留在构建或同步工具中，而不是放进伪造的 registry 数据模型。
依赖规则：当上游存在 shadcn registry item 时，优先使用 button、command、popover 之类的裸名称；当命名空间已覆盖该场景时，非默认 registry 优先使用上游命名空间语法而非原始 URL；registry 源码中 Plate 自依赖优先使用显式 @plate/；公开生成的 registry item JSON 必须将 Plate 自依赖重写为同基址 item URL，例如 https://platejs.org/r/.json，以便直接 URL 安装能从同一 registry 基址解析传递性的 Plate item；保留旧有的 localhost 和绝对 Plate item URL 作为可接受的输入兼容性，用于本地文件同步适配器；将 @shadcn/* 仅视为兼容性输入，不要写入 Plate registry 源码或生成输出；如果上游未暴露某个小型独立 item，应使用小型 Plate registry item，而不是为了抽取一个内部文件而拖入庞大的上游依赖；不要将兼容性 hack 扩展为新的约定。
不要为了补偿 Plate registry 问题而 fork shadcn CLI。应修复 registry 数据或 Plate 同步工具。
模板规则
模板安装仍由 shadcn CLI 作为安装器，Plate 提供 registry。规则包括：保持 templates/*/components.json 与 shadcn registry 语义一致；将 components.json 中的 @plate 视为 Plate item 的安装入口；当生成输出错误时，优先修复 registry 而非仅打模板补丁；在发明自定义规则前，先将 Plate 输出与 ../shadcn 对比。
本地模板同步：--local 使用本地文件模式而非 localhost；本地同步通过从 apps/www/public/rd 准备 JSON 镜像来工作；本地同步的目的是喂给上游 shadcn 本地文件安装流程，而不是替代它。如果某项改动会让公开安装更干净却破坏本地文件同步，应指出并同时修复两端。
当前差异
以下是当前真实存在的 Plate 差异，应视为约束，而非可扩散的模式：Plate 从 apps/www 而非上游 shadcn 基础设施发布 registry；本地模板同步使用准备好的 JSON 镜像和本地文件模式；模板安装入口使用 components.json 中的 @plate registry；旧的生成 registry 输出可能仍包含绝对 Plate 自 URL，应视为兼容性输入而非源契约。
危险信号
出现以下情况应停下重新评估：将 Plate 描述为 shadcn CLI 的 fork；发明新的 Plate 专有 registry schema；用原始 URL 泛滥替代上游命名空间行为；在数据本身有错时通过增加安装器逻辑来解决 registry 问题；不检查 registry 源是否为真正问题就手工修补模板。