hd-garden 0.14.1 → 0.14.3

package/.agents/skills/garden-compose/SKILL.md

@@ -1,24 +1,21 @@
 ---
 name: garden-compose
-description: "将 Garden 原文与参考效果编译、组合、检查为唯一 garden compose 入口内的布局、Markdown/安全 HTML、语义场景与必要交互。"
+description: "将原文与一句效果或参考图，编译为 Garden Compose 内保真、可验证的说明布局；用于创作、微调及修复。"
 ---
 # Garden Compose
+只处理授权的文章/块；建议请求不写文件。不自动提交、发布、安装依赖或在文章任务中修改技能。
 
-项目技能，只改用户授权的文章/块，不自动改其他文章、安装全局技能、提交或发布。
+## 短决策链：问题 → 约束 → 推荐路线 → 原文 → 验证
+1. 作者只需原文＋一句效果/参考图＋可选不要什么。分开事实、效果与修改范围；保留措辞、顺序、完整段落和资源，不补摘要、数据、因果。普通 Markdown 足够就不加组件。
+2. 选型必读 `references/visual-selection.md`。AI 内部先判断移动阅读任务（扫读/顺序/对照/空间关系），必读 `references/mobile-contract.md`，写桌面＋窄屏约束卡，再取**唯一推荐路线**；不是限定合法组件的白名单。只在事实关系、隐藏内容、阅读顺序等重大取舍不明时询问；其余按已记录默认收敛，不让作者填技术表单。
+3. 按路线只读 `references/layout-recipes.md` 对应小节；陌生组合/参考图再读 `references/rendering-model.md`。需要新组合时读 `references/composition-patterns.md`，仍先建立共享容器。frame/tone/size是正交选择，不因微调换组件家族。
+4. 作者组件只用 `garden compose`；内部静态/语义/交互能力按需读 `references/static-play.md`。语义字段、图标、允许子项以 `npx --no-install garden ui schema` 为准，按需存到 `.garden`，不预读整本目录。Markdown/安全HTML岛保存完整块内容；受限表达式不等于任意JS。
 
-## 先理解关系，再组合
-1. 分开原文事实、读者问题、指定效果与修改范围。只问建议就给建议，不写文件。保留事实、措辞、顺序、完整段落与资源；不补数据、摘要、推断关系或装饰性箭头。
-2. 作者组件只有 **一个 `garden compose` 入口**。在其中选择和组合布局、Markdown/安全 HTML、语义场景和必要交互，不再让作者选择另一种组件围栏。普通正文已清楚时不增加组件。
-3. 先推导「关系 → 共同边界与容器层级 → 宽度/流向/对齐 → 样式 → 真实渲染」。按需读 `references/visual-selection.md`、`references/composition-patterns.md`；不是套有限模板白名单。陌生组合或参考图必须读 `references/rendering-model.md`，再按需查 `references/layout-recipes.md`。标题和全部正文若要共用右栏，必须在同一个右侧容器；仅收集 icon/title/text/divider 不会自动建立关系。
-4. 语义资源、文件、关系、选项卡等和可调参数均在同一 Compose 内；按需读 `references/static-play.md`。只有改变输入确实帮助理解时才加状态。先查实际组件契约，不因没有现成配方就断言不支持。
+## 写入与验证
+1. 必读 `references/workflow.md`：scan，保存id/行号、完整围栏base hash与原文。首次插入意图块和已有块apply不同；未编译意图不是完成品。
+2. 按 `references/rendering-model.md` 的集中禁令与配方生成候选。正文默认继承文章动态字体/字号/行高；不缩字凑版。显式size只响应明确要求或真实层级。框读frames、颜色读colors；不要把场景框、内部边框和底色混为一谈。
+3. 属性级微调优先，但当前apply仍替换完整围栏：候选文件＋稳定id（没有才用scan行号）＋原完整base hash；冲突即重读，不绕过保护。不误伤邻块或改写intent原话。
+4. `scripts/check.mjs` 与 `garden check`保持原契约；有内部约束卡可另跑 `scripts/lint-layout.mjs`（workflow说明）。风险提示不等于语法错误；静态属性可能被丢弃，解析通过不等于生效。
+5. 所有新布局都默认承担移动端责任，不等作者指出手机问题。按mobile-contract先验最窄屏和放大正文，再在完整主题与真实CSS顺序下检查桌面、computed样式、几何及阅读密度；交互另测。分别报告：结构/解析、渲染、浏览器几何/交互、独立AI生成试验。没有对应证据就写未验证。
 
-## 执行与验证
-1. 在站点根目录读 `references/workflow.md`。运行 `node .agents/skills/garden-compose/scripts/scan.mjs content/posts/路径.md`，保存目标 id/行号、原始完整围栏 hash、原文和 diagnostics。对已有正确块不重画。
-2. 属性、默认值、允许子项与图标以 **`npx --no-install garden ui schema`** 为准；需要配方再运行 `npx --no-install garden ui prompt`。把 JSON 存到 `.garden` 后只读取当前需要的组件/图标，不预加载整本手册。静态布局部分属性可能被忽略，须检查归一化结果与真实样式，不能把「解析接受」当作「生效」。
-3. 原文没有围栏时，仅在授权位置首次插入一个 `garden compose` 意图块，保留原文与效果要求，再 scan。该插入不是 apply API；未编译意图不是完成品。候选始终是完整 `garden compose`；编译后原话保留在 intent，不重复展示。
-4. `text/title/caption` 用行内 Markdown 与安全行内 HTML；完整段落、列表、表格、代码块等放 `markdown/html` 内容岛。岛内允许实际白名单 HTML/CSS，不允许脚本、事件与危险 URL。需要执行的独立演示用同一 Compose 的 `sandbox`；DIL 表达式和岛内字面内容的边界见能力参考。不要把受限语言误称任意 HTML/JS，也不要把它误称完全不支持 Markdown/HTML。
-5. 正文默认随**实际文章动态配置**继承字号/字体，不设通用像素基线、不缩字凑版。需要强调才用支持的 size/tone/weight 机制；标题、数值、图标签、caption 和控件保留语义层级。当前其他语义尺寸与上下文看 rendering-model，不把某张截图的 computed 值当全局常量。按需读 colors/frames/examples。
-6. 候选存临时 Markdown，再用 `scripts/apply.mjs` 调权威 CLI 写回：有 id 用 `--id`，否则 scan 的 `--at`；总是加原完整围栏 `--base` hash 和候选 `--file`。原文变了就重新 scan，不移除保护强行覆盖；不使用空 intentHash 定位。
-7. 运行 `scripts/check.mjs`；本地文件另做 `npx --no-install garden check 文章.md`。陌生布局/指定视觉效果还要在完整主题及真实 CSS 顺序下验证桌面、窄屏、几何与实际交互。分别报告「解析通过」「渲染成功」「几何/交互通过」与「独立模型生成可靠性」；手写场景的通过不能证明短提示词可靠。没有浏览器或独立试验就如实写未验证。
-
-脚本只委托本地 CLI，不复制验证器、不下载包、不默认调用模型或改剪贴板。本地 garden 缺失就报告依赖问题，不另装版本。可复用的新经验只提出技能维护候选，文章处理时不自行改技能。
+脚本仅使用已安装本地引擎，不下载包、不默认调用模型或导出全目录。缺依赖就报告；可复用维护经验只提出候选，不在文章任务里自行改技能。

package/.agents/skills/garden-compose/references/engine-gaps.md

@@ -0,0 +1,8 @@
+# Engine follow-ups · 本轮只记录
+按预期收益而非虚构测量排序；skill规则不能替代这些运行时能力，修改需另行授权。
+1. 高：静态未知/无效属性显式诊断。现归一化会丢弃，技能无法完整恢复作者意图。
+2. 高：独立主轴/交叉轴/文字对齐，以及可靠的内容宽图标标题组合；centered-chip候选先跑完整主题几何再决定最小引擎修复。
+3. 中：保留base冲突保护的属性patch/稳定块定位，减少微调必须整围栏替换的负担。
+4. 中：完整主题的几何断言、真实列表间距和动态正文对照；先取证，不假定所有CSS默认错误。默认wrap的row与right箭头已有主题级横→纵同步回退，不能再列为缺失API；nowrap在手机仍横排而箭头转向的上下文需单独核查。
+5. 后续：glyph光学齐平；行盒相等不保证视觉齐平。
+未运行浏览器或独立模型实验时不得把以上能力标成已解决。

package/.agents/skills/garden-compose/references/frames.md

@@ -5,3 +5,9 @@
 - `border="none"`, `background="transparent"`, and `backgroundColor="transparent"` affect different aspects of a supported node. Transparent background is not a border/frame removal API.
 
 Don't add raw CSS to emulate unsupported framing. Don't promise frame:none for every rendering path; confirm the actual generated wrapper.
+
+## 先选择层级，再动旋钮
+1. 静态整个场景：唯一最外层`<figure frame="none">…</figure>`去场景边界；默认card。它不删除内部卡片，也不是Play头语法。
+2. 内部容器：支持的card/box使用border或frame；card frame="text"是无表面的内容壳，不等于删除外场景。
+3. 底色：background token或支持的backgroundColor；transparent不删除border。
+“去外框”默认只改第1层；“无底色留内框”分别改第1、3层并保留第2层。编辑性说明偏向融入文章，独立实验保留必要边界；不因去框更换内容家族。

package/.agents/skills/garden-compose/references/layout-recipes.md

@@ -1,6 +1,6 @@
 # Layout recipes · 布局组合要点
 
-Read only the section matching the requested layout. / 按需读取对应布局小节。
+Read only the section matching the requested layout. / 按需读取对应布局小节；所有配方先读mobile-contract.md决定手机阅读任务，再选择局部结构。
 
 ## Horizontal equal-width cards · 横向等宽卡片
 
@@ -28,6 +28,7 @@ Use `<grid cols={3} gap={3}>` with three direct `<card>` children. `cols` accept
 - **产品**：一款真正的好产品本身长什么样，有哪些绝不能碰的死穴。
 使用 garden compose 来呈现横向等宽卡片。
 </intent>
+<figure frame="none">
 <grid cols={3} gap={3}>
   <card padding={3} radius="md" border="subtle" background="surface">
     <title>人员</title>
@@ -42,6 +43,7 @@ Use `<grid cols={3} gap={3}>` with three direct `<card>` children. `cols` accept
     <text>一款真正的好产品本身长什么样，有哪些绝不能碰的死穴。</text>
   </card>
 </grid>
+</figure>
 ```
 
 Follow workflow.md for id/line/hash safeguards. No default prompt export, clipboard or model call. Structural validation does not prove browser appearance. / 扫描、带 hash 单块写回和复检由 AI 内部完成；不默认导出提示词或调用模型，未看浏览器不声称视觉验收。
@@ -56,6 +58,7 @@ Follow workflow.md for id/line/hash safeguards. No default prompt export, clipbo
 最小语法示意（实施时使用原文；占位文字不是正文素材）：
 ```garden compose
 <intent>语法示意：固定图标列，共用右侧文字列。</intent>
+<figure frame="none">
 <stack gap={3}>
 <row wrap="nowrap" gap={3}>
 <icon name="book-open" size="xl"/>
@@ -74,11 +77,39 @@ Follow workflow.md for id/line/hash safeguards. No default prompt export, clipbo
 </group>
 </row>
 </stack>
+</figure>
 ```
 
-标题用 text + 加粗保证与正文同字号；需要不同标题层级才改用 title 并核对实际字号。图标选真实目录中的合适名字，不要求作者指定。divider 是外层 stack 的子项，不是 list 的直接子项。外框默认保留；确需去框用场景 figure frame="none"，不要误用内部 box 的 border。
+标题用 text + 加粗保证与正文同字号；需要不同标题层级才改用 title 并核对实际字号。图标选真实目录中的合适名字，不要求作者指定。divider 是外层 stack 的子项，不是 list 的直接子项。编辑性段落默认采用外层 figure frame="none" 融入文章；作者明确要独立场景边界时保留。不要误用内部 box 的 border。
 
 上下文、默认值、prose 与 group 的差别及窄屏规则读取 rendering-model.md。检查后的视觉验收：图标列对齐；标题及所有正文段落共用右侧左边界；标题不居中；段落不回到图标列；每两个单元仅一条细线；没有卡片背景、箭头或窄屏横向溢出。
 
 ### Icon-led editorial list: operational summary
-Use this for independent explanations, not a workflow. Derive the alignment hierarchy before selecting leaves: an outer `stack` repeats `row wrap="nowrap"` with a fixed-size direct `icon` and one flexible `group`. Put the bold heading and **every** original paragraph into separate `text` children of that same group. Place `divider` between rows in the outer stack. Do not place the body outside the row, center the ancestor, use a direct list divider, or substitute a nested stack without checking its contextual padding. The tested syntax above is illustrative; substitute real source text and catalog icons. Keep the default frame unless requested otherwise; an explicit outer scene `figure frame="none"` removes only the scene frame. Verify shared heading/body left edges, fixed icon alignment, retained paragraphs, separators and no narrow-screen overflow under the complete article theme.
+Use this for independent explanations, not a workflow. Derive the alignment hierarchy before selecting leaves: an outer `stack` repeats `row wrap="nowrap"` with a fixed-size direct `icon` and one flexible `group`. Put the bold heading and **every** original paragraph into separate `text` children of that same group. Place `divider` between rows in the outer stack. Do not place the body outside the row, center the ancestor, use a direct list divider, or substitute a nested stack without checking its contextual padding. The tested syntax above is illustrative; substitute real source text and catalog icons. For editorial prose prefer an outer frameless figure unless a scene boundary was requested; an explicit outer scene `figure frame="none"` removes only the scene frame. Verify shared heading/body left edges, fixed icon alignment, retained paragraphs, separators and no narrow-screen overflow under the complete article theme.
+
+
+## flow-row / flow-stack · 短阶段与长阶段
+只有原文明确顺序才用箭头。短阶段默认用普通row（保持默认wrap）中的text与right箭头；普通正文基线，不加粗、不缩字凑横排。当前完整主题在≤800px把这种row改成column，并取消right箭头的旋转；底层SVG本来向下，因此实际箭头随之朝下。不能只读data-dir="right"就误报移动端方向错误，要核对computed transform或SVG屏幕向量。
+本轮完整主题1200/500浏览器已验证默认row的横→纵回退。长阶段或明确纵向请求仍用stack与down箭头。不要加nowrap：手机保持横排时主题仍可能把right箭头画向下；只有显式要求、实际验证方向与溢出均正确时才偏离默认。没有必要为默认响应式回退询问作者，也不发明响应式属性。
+作者明确“略小”时仅在文字叶子设sm，勿父子重复缩放；编辑性流程默认外figure frame="none"。不把配方验证扩大到所有主题/字体或未知嵌套。
+
+## centered-chip · 整体居中、图标贴标题（候选，待浏览器验证）
+编辑性说明默认用外figure frame="none"包裹；这与内部frame="text"标题壳不是同一层。关系是“图标＋标题”为一个内容宽整体，正文另占一行；它是局部标题效果，不能默认把整份长清单变成重复居中的大展示单元；不是图标与一个flex:1标题平分整格。
+候选沿用真实文章的结构：`stack align="center" → card frame="text" padding={0} → row align="center" gap={0} wrap="nowrap" → icon inline + text`；正文作为外stack的下一text。frame=text标题壳不是信息卡片。不得把此候选称作跨主题已验证；检查标题壳实际宽度、图文距离、图标与标题行盒、整体中心、长标题、窄屏溢出。icon inline当前另带6px右距，gap=0不等于零距离；row>text仍有flex规则。若失败，记录引擎缺口，不用换字号掩盖。
+
+## prose-list · 正文列表手感
+不需要场景时保留普通Markdown。需要嵌入icon-rail时，把真实Markdown无序/有序列表放右侧group内的markdown岛，保留全部子项和层级。title/text是行内内容，不能用“•”拼出列表。结构上核对ul/li；完整主题另验悬挂缩进、段距和换行，不由AST宣称观感相同。
+
+## frameless-scene · 正交的框选项
+编辑性说明默认外`figure frame="none"`，内card是否有border、background分别决定；独立实验或明确要求场景边界时保留外框。详见frames.md。默认不加size/tone来补救布局，不删事实、不裁正文。
+
+## 内部验收卡（不是作者表单）
+选定路线后在工作笔记记：读者问题、源条目/段落数、共享容器与悬挂、居中对象、相对正文的字号、三层框选择、桌面/窄屏回退、禁止项。唯一推荐不等于凭经验宣称已验证：centered-chip与响应式flow尚须实际浏览器证据；已有icon-rail/equal-cards也须在本次上下文核对。
+
+## 各路线共用的移动责任
+- flow-row：响应式阅读任务声明为reflow时，不用nowrap硬撑阶段标签。row方向和实际绘制箭头必须一起改变；换行/纵排/横滚各自不同，不能只看无外层溢出就判通过。
+- equal-cards：单列后再次核对每项扫读节奏；若原本只是短标签/短问句，优先选择紧凑列表/分组而不是机械重复卡片。显式指定卡片时保留要求，自然段长则自然增长，不删字、不设固定高。
+- icon-rail：nowrap只固定图标＋可收缩右栏的局部关系，不是让整组条目横排；长段落/真列表在右group内自然换行。
+- centered-chip：只承诺局部贴标。完整问句、长标题、双语标签和放大字体必须实测；不自动把所有正文居中。长扫描清单优先开始对齐的连续阅读，必要时用局部重点居中，不通过sm来压高度。
+- prose-list / frameless：保持真实标记、顺序、正文基线和自然段落；去掉无意义的多层场景表面不是删掉所有必要分组。
+同一树能响应式重排时使用已有机制；若需要尚未支持的断点条件对齐/拓扑，不复制两套文字隐藏一套、不发明媒体属性。采用兼容两端且保真的最小方案并注明视觉取舍；无法满足作者明确硬约束时标未完成，而非让作者做设备调参。

package/.agents/skills/garden-compose/references/mobile-contract.md

@@ -0,0 +1,23 @@
+# Mobile contract · 阅读优先的内部编译契约
+作者只提供原文与效果；手机不是额外选项，也不是作者要填写的规格。先识别读者任务，再做视觉配方，最后在真实小屏验证。
+
+## 生成前：两个尺度、一份原文
+AI内部记录：读者扫读/顺序/对照/空间关系；条目数及长短分布；标题与正文的共享边界；整体/局部居中；桌面与窄屏的流向；正文相对字号；框层级；应保留的顺序、完整段落和重点。不让作者选择断点、标签和font-size。
+先从最窄阅读宽度推导可持续结构，再扩展桌面。优先同一内容树重排，不复制两份文字，不删事实、不缩字凑版、不把长内容藏进交互。作者明确的局部效果不自动等于整个场景的阅读模式；居中图标标题不能推导全部长正文居中。
+
+## 三道门，不能互相替代
+1. **结构/源保真**：权威parser/check；原文各叶子及顺序、真实列表、共享容器、未知属性限制。内部约束卡可选mobile，见workflow；不是围栏属性或作者新API。
+2. **浏览器几何**：真实CSS viewport与available content width；当前主题/完整CSS顺序；正文默认及放大字号；每个滚动容器scrollWidth/clientWidth，不只页面外框；最窄叶子的换行与文字宽度；实际SVG屏幕向量和父布局轴；不裁切、遮挡、重叠或隐藏事实。data-dir、DOM存在和无页面横滚都不是充分证据。
+3. **阅读节奏人工审查**：把整组而非一个漂亮单元看完。能否迅速找下一项？有没有多余重复标题、层层表面、每条都成为独立海报、过量空白或居中长段让眼睛反复找起点？很长的真实材料可以跨多屏；禁止用“必须一屏”迫使删字、缩字或隐藏。
+
+## 通用测试矩阵，不是设计硬阈值
+起步样本可用CSS宽375/430/768/1200，以及正常正文和1.25倍正文；这些只是回归采样，不是作者批准的断点或科学最优值。必须记录浏览器实际innerWidth，不把截图物理像素或Chrome窗口参数当CSS viewport。主题已有≤800px机制要按实际CSS理解。
+记录sceneHeight/availableHeight、每项行数、字号相对正文、内部横滚、每项起点及序号可见性；这些是证据，不是把某个比值硬判为不美观。可疑高空白/重复表面/多行短标签要求人工复核；任何“最多几项/最多几屏/字号下限”的新阈值都先是待校准建议，不可伪称用户规则或测量结论。
+
+## 默认修复顺序由AI承担
+错误阅读拓扑/容器 → 不必要nowrap或宽度约束 → 重复框与间距 → 局部对齐。字号最后且只用于真实层级/明确需求，不为修布局来回sm/lg。局部图标栏的nowrap可以合理，不能全局禁用。
+默认wrap的短阶段row已有手机纵排＋箭头转向；不要要求作者决定技术回退。硬nowrap阶段链会保留横向却可能出现向下箭头，并把文字挤成多行；即使没有scroll也失败。
+当只靠现有语法不能同时满足显式硬约束时，交付中记录准确能力缺口与保真取舍，不能假称视觉完成。几何通过后仍需阅读审查，缺浏览器就标移动端待验，不把QA任务退给作者。
+
+## 防止只记住这次两张图
+冻结首稿，先评估再修。回归覆盖短/长顺序、短并列与长扫描清单、多段解释、嵌套真列表、长中英混排/链接和放大字体。独立AI只读原文＋一句效果/参考图，不能看到标准输出。区分同一上下文多例与多次隔离试验，不用一次通过宣称可靠率。

package/.agents/skills/garden-compose/references/rendering-model.md

@@ -10,6 +10,13 @@
 - icon 名查 schema/icons 实际目录；不存在报错。SVG width 属性不等于最终像素：当前 CSS sm13、md15、lg18、xl22px，小卡上下文另有覆盖，必须测 computed/rect。
 - 多段正文分别放 text，或用 markdown/html 岛保存真实 p。text 内空行是 inline break，不是独立段落。图标签有截断/行钳制时不能塞完整正文去丢字。
 
+## 集中禁令与风险分级
+- **必选结构（已选icon-rail）**：icon和一个group同属row，标题与全部正文/列表同属group；分隔线在row之间。不要正文逃出右栏，不用row>stack替代group来碰运气。
+- **无效属性**：stack不因direction="row"变横向；用真实row。未知静态属性可能归一化丢失，当前lint不能从归一化树找回它们；对照源属性与schema，缺少未知属性诊断是引擎需求，不谎称已机器覆盖。
+- **风险而非全局错误**：row>stack的12px顶距、居中row直接title/text的flex:1、center同时改变主轴/交叉轴/文字、nowrap长链、显式size和叠框。这些在其他语境可能有意，必须结合内部约束卡判断，不能一律禁用。
+- **箭头看实际绘制方向**：right是源意图，不必等于当前屏幕方向。真实SVG默认向下；桌面旋转为right，≤800px取消旋转配合默认row转column。先看computed transform/屏幕向量，不把data-dir当几何证据。nowrap让row保持横向却不自动保留箭头旋转，须专项检查。
+- **必须浏览器**：icon glyph光学齐平不是节点矩形相等；内容宽居中、完整主题字号/列表间距、溢出与手机回退不能从AST推断。用computed与rect及截图分别取证。
+
 ## 默认与显式样式
 普通正文默认继承实际文章动态字体/字号；不再使用固定正文像素基线。text/title 的 sm=.875em、lg=1.125em、xl=1.25em，md 保持基线；title 默认 600/1.4。外层 figure 标题18px、caption14px及控件/图标签等是语义角色，不应全局拉成正文。其他语义尺寸及实际上下文见下表与完整主题。显式字体变化必须有信息层级依据，不缩字替代排版。
 

package/.agents/skills/garden-compose/references/visual-selection.md

@@ -2,12 +2,26 @@
 
 Load when choosing how to explain source content, not for every repair. Use the current lowercase Compose surface. / 需要选图时读取，不是每次修复都读。
 
-## Decision procedure · 选型
-Identify the reader question first: “which things?”, “what happens next?”, “what contains what?”, “who sends what?”, “how do options differ?”, “what changes if an input changes?”. Select the relation actually present in the source, not whichever layout looks elaborate. Use one primary relation per scene; split a crowded explanation into adjacent scenes. Honor an explicit requested effect unless unsupported or misleading, in which case explain the concrete conflict.
+## Effect compiler · 效果先收敛
+作者给原文＋一句效果/参考图即可；以下是AI内部动作，不要求作者懂标签。
 
-先确定读者问题，再抽取真实关系。普通清单已足够、只有一句结论、缺少关系/数值、图只会重复文字时保留 Markdown；建议请求只给形式与理由。没有顺序就不画流程，没有因果就不画因果箭头，没有数据就不造图表。不能确定的关系不强行补齐。
+1. 确定读者问题、移动阅读任务和原文真实关系；尊重明确效果。没有顺序不画流程，没有因果不加因果箭头，没有数据不造图表。
+2. 写一张内部几何约束卡（工作笔记/临时JSON即可，非新作者语法）：读者问题；共享容器；悬挂与正文范围；居中的是文字还是图标标题整体；字号相对正文；场景框/内部边框/底色；窄屏回退；不要什么。参考图也先提取这些约束，不能只识别“图标＋文字”。
+3. 全局阅读结构先于局部效果：长清单的任务是连续扫读，不是把每项放大为一个居中展示单元。按mobile-contract检查内容量、长短差异和小屏阅读节奏，再按下表取一条推荐路线，填原文叶子。默认正文基线、开始对齐、自然换行，不新增强调色；只在有意强调时加样式。未知但不影响事实的细节用默认，不把问题推给作者；可能改变事实关系、隐藏内容或阅读顺序时才问。
 
-The forms below are examples accumulated from practice, not an exhaustive taxonomy or a whitelist. If no row matches, use the primitive inventory, operations and discovery protocol in composition-patterns.md to build a faithful new arrangement. Absence from this map is not evidence of an engine limitation. / 下表是持续积累的典型经验，不穷举表示方式；没有匹配项时查基础组件和组合操作，构造并验证新组合，不能据此判定不支持。
+| 效果/读者问题 | 唯一推荐路线 | whenNot / 不这样用 |
+|---|---|---|
+| 图标窄栏、标题正文共左缘 | icon-rail：stack重复row(icon＋group)，divider在row间 | 不把正文放row外；不当流程 |
+| 短阶段从左到右 | flow-row：row＋真实顺序箭头；窄屏/长内容回退flow-stack | 不靠缩字/nowrap强撑手机 |
+| 长阶段或纵向顺序 | flow-stack：stack＋下箭头 | 无顺序的条目不加箭头 |
+| 并列等宽卡片 | equal-cards：grid＋直接card | 非真实共同维度不走compare |
+| 图标贴标题，两者一起居中 | centered-chip：内容宽标题壳＋内部图标标题行，下方正文独立 | 不只给全宽row设center；候选须浏览器验收 |
+| 跟正文一样的列表 | prose-list：普通Markdown；场景内用markdown岛 | 不写假圆点；不为列表手感换到compare |
+| 去外框/留内框 | 原路线＋frameless-scene选项：外figure frame=none | 不把透明底色当去边框，不改错层级 |
+
+这些是**唯一推荐默认**，不是组件白名单；先使用最接近的已验局部结构，确有关系需求再按composition-patterns组合新形式，并保留同样约束和验证。frame/tone是正交选项，不衍生新的配方家族。
+
+边界：普通Markdown优先；compare仅真实共同维度对照。当前只有garden compose围栏，旧garden list不再推荐。Compose内部icon-list仅在需要其原生语义/宿主行为且接受其样式契约时用；普通编辑性图标段落默认icon-rail，不能仅为调字号来回迁移。需要语义/交互时再读static-play，不靠标签同名猜兼容。
 
 ## Capability map · 典型形式与边界
 
@@ -36,3 +50,7 @@ This is a selection map, not a new syntax catalog. For chart attributes use the
 No arbitrary SVG/canvas, custom CSS/JS, general node-id edge routing, automatic graph/tree placement, simulated execution, arbitrary nested rich `compare` items, or full parity between static and Play. A small drawn branch does not imply support for a full flowchart language. `steps` detail toggles and `tabs` are not numerical Play state.
 
 If the requested relation needs unsupported routing/interaction, state the gap and suggest a simpler faithful Compose scene or an existing appropriate article format; do not silently switch engines or invent tags. Validation proves syntax/semantics only; inspect the browser before claiming visual/responsive behavior was verified.
+
+## Mobile is part of compilation · 不是交给作者的QA
+断点自动单列只证明重排，不证明好读。centered-chip是局部贴标结构，不是长清单的全局默认；equal-cards也是按信息关系选择，不是见到N项就生成N张大卡。普通短清单优先prose-list；有独立标题/多段解释才用共享右栏。明确要求的卡片/居中仍须保留其意图，但不能以缩字、硬横排、折叠事实来达成。
+长内容自然跨屏不算失败；要识别的是重复装饰、冗余表面、过量容器间距、窄列拆词和反复居中造成的阅读负担。移动约束由AI内部收敛与验证，不询问作者要断点、字号或方向细节。当前能力确实无法同时满足硬约束时如实标未完成/引擎缺口，不静默改事实或发明属性。

package/.agents/skills/garden-compose/references/workflow.md

@@ -25,3 +25,22 @@ node .agents/skills/garden-compose/scripts/check.mjs content/posts/post.md
 ## Prose outside a fence · 围栏外的原文
 
 Separate the source paragraphs/list items from the requested effect. At the authorized location, create one `garden compose` intent block preserving both verbatim, then scan it. Initial insertion is distinct from replacing a block: `apply` requires a scanned existing target. For existing blocks, use scan → candidate → apply with the original base hash → check. Preserve unrelated prose and render the source once. / 分离原文与效果要求，在授权位置首次创建 `garden compose` 意图块后扫描；已有块始终带原 base hash 写回并复检，不把 apply 当作插入 API，不重复展示原文。
+
+## Local micro-edit · 微调不重画
+scan → 保存稳定id（没有则目标行）与完整围栏base → 仅改候选中的必要属性/叶子 → 审查diff → 带原base apply → rescan/check。去粗先区分源Markdown加粗与title默认600；略小仅在明确要求时改文字叶子size；紧一点改对应容器gap；去外框只改最外figure。不要为了旋钮变化换标签家族或清空intent。稳定id在获授权编辑该块时建立，不全篇加id。并发修改造成base冲突必须重新读取。
+当前没有属性patch或dry-run；apply始终写回完整围栏。最小候选diff不等于局部写入API；保留围栏外字节及完整原文核对。
+
+## Opt-in layout check · 独立的内部约束检查
+原check.mjs的参数/退出状态不变。AI内部约束卡可保存为临时JSON（不是围栏属性/作者新语法）：
+```json
+{"at":90,"base":"扫描所得完整围栏hash","layout":"icon-rail","units":3,"outerFrame":"none"}
+```
+有稳定id用id替代at；base必填。运行：
+```sh
+node .agents/skills/garden-compose/scripts/lint-layout.mjs content/posts/post.md --constraints .garden/layout.json
+```
+仅支持当前静态Compose；复用实际本地hd-garden的scanner和parser，不下载包、不复制解析器。错误退出1，工具/约束输入错误退出2，风险/浏览器待验不使退出失败。只对显式声明的icon-rail/equal-cards和outerFrame做有限结构断言；其他路线仍需人工结构清单。不能从归一化树还原未知属性、推断自然语言效果或验证几何；保真核对另做，不把机器支持范围夸大。
+
+## Mobile acceptance · AI内部，不要求作者补规格
+几何卡补可选`"mobile":{"readingMode":"sequence","reflow":true}`；readingMode可选sequence/scan-list/comparison/spatial，reflow为布尔。lint只在显式reflow的flow-row中拒绝场景顶层流向row的nowrap（不误禁内部贴标row）；icon-rail局部nowrap不被误禁。scan-list的成组居中只给风险提示，不凭AST断言过高或难读。
+浏览器验证遵守mobile-contract：记录实际CSS viewport、内容宽、正常/放大正文、每层滚动与实际箭头向量，并人工审查整组阅读节奏。保留首稿和源hash，失败后的修订单独编号，不能把修后结果算首轮成功。默认check参数/退出状态不变，mobile字段不是runtime DIL属性。

package/.agents/skills/garden-compose/scripts/lint-layout.mjs

@@ -0,0 +1,87 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {createRequire} from 'node:module';
+import {pathToFileURL} from 'node:url';
+const layouts = new Set(['icon-rail','equal-cards','flow-row','flow-stack','centered-chip','prose-list']);
+export function validateCard(card) {
+  const keys = new Set(['id','at','base','layout','units','outerFrame','mobile']);
+  if (!card || typeof card !== 'object' || Array.isArray(card) || Object.keys(card).some(k=>!keys.has(k))) throw new Error('Unknown constraint field/object');
+  if ((typeof card.id==='string' && card.id.length>0) === (Number.isInteger(card.at) && card.at>0)) throw new Error('Choose exactly one nonempty id or positive at line');
+  if (card.id!==undefined && (typeof card.id!=='string'||!card.id)) throw new Error('Invalid id');
+  if (card.at!==undefined && (!Number.isInteger(card.at)||card.at<1)) throw new Error('Invalid at');
+  if (!/^[a-f0-9]{8}$/.test(card.base??'')) throw new Error('base must be the scanned complete fence hash');
+  if (!layouts.has(card.layout)) throw new Error('Unsupported layout recommendation');
+  if (card.units!==undefined && (!Number.isInteger(card.units)||card.units<1)) throw new Error('units must be positive');
+  if (card.outerFrame!==undefined && !['none','card'].includes(card.outerFrame)) throw new Error('Invalid outerFrame');
+  if (card.mobile!==undefined) {
+    const m=card.mobile;
+    if (!m || typeof m!=='object' || Array.isArray(m) || Object.keys(m).some(k=>!['readingMode','reflow'].includes(k))) throw new Error('Invalid mobile constraint');
+    if (m.readingMode!==undefined && !['sequence','scan-list','comparison','spatial'].includes(m.readingMode)) throw new Error('Invalid mobile readingMode');
+    if (m.reflow!==undefined && typeof m.reflow!=='boolean') throw new Error('Invalid mobile reflow');
+  }
+}
+export function inspectLayout(doc, card) {
+  validateCard(card);
+  const diagnostics=[];
+  const add=(severity,code,message)=>diagnostics.push({severity,code,message});
+  if (!Array.isArray(doc?.nodes)) throw new Error('Only normalized static Compose is supported');
+  const nodes=doc.nodes.length===1 && doc.nodes[0].type==='figure' ? doc.nodes[0].children : doc.nodes;
+  if (card.outerFrame && (doc.frame??'card')!==card.outerFrame) add('error','outer-frame','Declared scene frame does not match normalized scene');
+  if (card.layout==='icon-rail') {
+    const stack=nodes.length===1 && nodes[0].type==='stack' ? nodes[0] : null;
+    if (!stack) add('error','rail-container','Recommended rail needs one outer stack');
+    else {
+      const rows=stack.children.filter(n=>n.type==='row');
+      if (!rows.length || stack.children.some(n=>!['row','divider'].includes(n.type))) add('error','rail-outside-body','Only rows and between-row dividers belong in the outer rail');
+      if (card.units!==undefined && rows.length!==card.units) add('error','unit-count','Row count differs from declared source units');
+      for (const [i,n] of stack.children.entries()) if (n.type==='divider' && (stack.children[i-1]?.type!=='row'||stack.children[i+1]?.type!=='row')) add('error','rail-divider','Divider must separate two rows');
+      for (const row of rows) {
+        const icons=row.children.filter(n=>n.type==='icon'), groups=row.children.filter(n=>n.type==='group');
+        if (row.children.length!==2 || icons.length!==1 || groups.length!==1 || row.children[0].type!=='icon') add('error','rail-shared-container','Row needs icon then exactly one shared right-hand group');
+        const group=groups[0];
+        if (group && (group.children.length<2 || !['text','title'].includes(group.children[0].type))) add('error','rail-heading-body','Group needs heading and body/content leaves');
+      }
+    }
+  }
+  if (card.layout==='equal-cards') {
+    const grid=nodes.length===1 && nodes[0].type==='grid' ? nodes[0] : null;
+    if (!grid || !grid.children.length || grid.children.some(n=>n.type!=='card')) add('error','cards-grid','Recommended equal cards need one grid with direct cards');
+    else if (card.units!==undefined && (grid.children.length!==card.units || grid.cols!==Math.min(card.units,6))) add('error','unit-count','Grid cards/columns differ from declared source units');
+  }
+  const visit=(n,parent)=>{
+    if (card.mobile?.reflow===true && card.layout==='flow-row' && nodes.includes(n) && n.type==='row' && n.wrap==='nowrap') add('error','mobile-flow-nowrap','Declared responsive sequence cannot hard-lock its row; inspect painted arrows and narrow label wrapping');
+    if (card.mobile?.readingMode==='scan-list' && ['stack','grid'].includes(n.type) && n.align==='center' && (n.children??[]).filter(c=>['card','group','stack'].includes(c.type)).length>1) add('warning','mobile-scan-centering','Repeated centered scan units require whole-scene density and reading review; AST does not prove a failure');
+    if (parent?.type==='row' && n.type==='stack') add('warning','row-stack-padding','Current theme adds 12px top padding');
+    if (n.type==='row' && n.align==='center' && n.children?.some(c=>['title','text'].includes(c.type))) add('warning','center-flex','Center couples axes/text; direct title/text keep flex:1');
+    if (n.type==='row' && n.wrap==='nowrap') add('warning','nowrap','Browser must verify wrapping and overflow');
+    if (n.size && n.size!=='md') add('warning','normalized-size','Non-baseline normalized size: compare with source intent; normalization does not prove an authored attribute');
+    if (n.type==='card' && parent?.type==='card') add('warning','nested-surface','Check whether nested surfaces are intentional');
+    for (const child of n.children??[]) visit(child,n);
+  };
+  doc.nodes.forEach(n=>visit(n,null));
+  return {ok:!diagnostics.some(d=>d.severity==='error'),diagnostics,coverage:{structural:[...(card.outerFrame?['declared outerFrame']:[]),...(['icon-rail','equal-cards'].includes(card.layout)?[card.layout+' shape']:[]) ,...(card.mobile?.reflow===true&&card.layout==='flow-row'?['declared mobile top-level flow nowrap guard']:[])],notChecked:['source fidelity','unknown source attributes','other route structures','DOM geometry','responsive layout','optical alignment','AI reliability']},browserRequired:true};
+}
+async function main() {
+  const args=process.argv.slice(2);
+  if (args.length!==3 || args[1]!=='--constraints') throw new Error('Usage: lint-layout.mjs post.md --constraints card.json');
+  const card=JSON.parse(fs.readFileSync(args[2],'utf8')); validateCard(card);
+  const cwd=process.cwd();
+  const localManifest=path.join(cwd,'package.json');
+  const local=JSON.parse(fs.readFileSync(localManifest,'utf8'));
+  const root=local.name==='hd-garden'?cwd:path.dirname(createRequire(localManifest).resolve('hd-garden/package.json'));
+  // These exported functions in the installed package are authoritative. No parser copy/fallback/download.
+  const {scanMarkdown,checkComposeFence}=await import(pathToFileURL(path.join(root,'ui/core/scan.mjs')).href);
+  const {scanFences}=await import(pathToFileURL(path.join(root,'ui/core/fence.mjs')).href);
+  const file=path.resolve(args[0]), source=fs.readFileSync(file,'utf8');
+  const blocks=scanMarkdown(source,{markdownPath:file});
+  const matches=blocks.filter(b=>card.id?b.id===card.id:b.startLine===card.at);
+  if (matches.length!==1) throw new Error('Constraint locator must match exactly one block');
+  const block=matches[0];
+  if (block.hash!==card.base) throw new Error('Stale constraint base; rescan before checking');
+  const fence=scanFences(source).find(f=>f.startLine===block.startLine);
+  const parsed=checkComposeFence(fence,{markdownPath:file});
+  if (!parsed.ok) { console.log(JSON.stringify({ok:false,diagnostics:parsed.diagnostics,browserRequired:true},null,2)); process.exitCode=1; return; }
+  const result=inspectLayout(parsed.doc,card);
+  console.log(JSON.stringify(result,null,2)); process.exitCode=result.ok?0:1;
+}
+if (process.argv[1] && import.meta.url===pathToFileURL(path.resolve(process.argv[1])).href) main().catch(error=>{console.error(JSON.stringify({ok:false,code:'layout-input',message:error.message}));process.exitCode=2;});

package/app/admin/preview/[...path]/page.tsx

@@ -75,7 +75,7 @@ export default async function DraftPreviewPage({ params }: { params: Promise<{ p
           草稿预览 · {post}{draft ? " · 草稿" : ""} · <Link href="/admin/ui/blocks">回到交互块</Link>
         </p>
         <h1 className="ui-admin-preview-title">{typeof data.title === "string" ? data.title : post}</h1>
-        {typeof data.description === "string" ? <p className="ui-studio-meta">{data.description}</p> : null}
+        {typeof data.description === "string" && data.description.trim() ? <p className="ui-studio-meta">{data.description}</p> : null}
         <article className="article-body">
           <MarkdownArticle content={proxyAssets(content, post)} numbering={data.numbering === false ? false : undefined} />
         </article>

package/docs/handbook/en/workflow.md

@@ -38,7 +38,7 @@ Three commands check your content at different scopes:
 
 | Code | Severity | Cause and Fix |
 | :--- | :--- | :--- |
-| `missing-title` / `missing-description` | Error | Front Matter is missing a non-empty `title` or `description` |
+| `missing-title` / `invalid-description` | Error | The title is missing or empty, or description is neither a string nor null; a blank description is valid |
 | `unexpected-slug` | Error | Front Matter includes a manual `slug` field (remove `slug`; the filename is the slug) |
 | `date-format` | Error | `date` is not a valid `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or ISO timestamp with timezone |
 | `missing-cover` / `missing-asset` | Error | A local file referenced by `cover`, a Markdown image, or Compose `file` does not exist |

package/docs/handbook/en/writing.md

@@ -36,7 +36,7 @@ references:
 | :--- | :--- | :--- | :--- |
 | `title` | Yes | String | Post title. Write ` \| ` (with spaces on both sides) to split the heading into two lines and scale the font size to fit |
 | `date` | Yes | Date string | Publication date (such as `2026-10-18` or an ISO timestamp with timezone) |
-| `description` | Yes | String | Summary shown in the article deck, archive lists, and search engine descriptions |
+| `description` | No | String | Summary shown in the article deck, archive lists, and search engine descriptions. Empty (`description: ""`), omitted, null, or whitespace-only values hide the summary; Garden does not substitute an excerpt from the body |
 | `updated` | No | Date string | Last updated date, shown in the article meta bar and used for RSS sorting |
 | `publishAt` | No | Date string | Scheduled publish time; included only when earlier than the build time (or when `CONTENT_INCLUDE_DRAFTS=1`) |
 | `tags` | No | String array | Tags for the post; clicking a tag filters `/blog?t=<tag>` |

package/docs/handbook/workflow.md

@@ -38,7 +38,7 @@ order: 40
 
 | 诊断码 | 级别 | 触发原因与修复方法 |
 | :--- | :--- | :--- |
-| `missing-title` / `missing-description` | 错误 | Front Matter 缺少有效的 `title` 或 `description` |
+| `missing-title` / `invalid-description` | 错误 | `title` 缺失或为空，或 `description` 不是字符串／空值；摘要可以留空 |
 | `unexpected-slug` | 错误 | Front Matter 中手写了 `slug` 字段（文件名即标识，删掉 `slug`） |
 | `date-format` | 错误 | `date` 不是合法的 `YYYY-MM-DD`、`YYYY-MM-DD HH:mm:ss` 或带时区的 ISO 时间 |
 | `missing-cover` / `missing-asset` | 错误 | `cover` 封面图、正文图片或 Compose `file` 引用的本地文件不存在 |

package/docs/handbook/writing.md

@@ -36,7 +36,7 @@ references:
 | :--- | :--- | :--- | :--- |
 | `title` | 是 | 字符串 | 文章标题。中间写 `丨`、`｜` 或 ` \| ` 会分成两行并按字数缩放字号 |
 | `date` | 是 | 日期字符串 | 发布日期（如 `2026-10-18` 或带时区的 ISO 时间） |
-| `description` | 是 | 字符串 | 文章摘要，显示在正文开头导语、列表页与搜索引擎摘要中 |
+| `description` | 否 | 字符串 | 文章摘要，显示在正文开头导语、列表页与搜索引擎摘要中；留空（如 `description: ""`）、省略、YAML `null` 或只写空白时，不渲染摘要，也不会自动截取正文替代 |
 | `updated` | 否 | 日期字符串 | 最后更新日期，显示在文章元信息栏并用于 RSS 排序 |
 | `publishAt` | 否 | 日期字符串 | 定时发布时间；早于当前构建时间（或设置 `CONTENT_INCLUDE_DRAFTS=1`）才会发布 |
 | `tags` | 否 | 字符串数组 | 文章标签列表，点击标签会跳转到 `/blog?t=<标签>` 筛选 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hd-garden",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "private": false,
   "description": "用 Markdown 写作、用 GitHub Pages 发布的个人博客引擎。",
   "license": "MIT",
@@ -71,7 +71,8 @@
     "editors:build": "node editors/vscode/build.mjs && node editors/obsidian/build.mjs && node editors/typora/build.mjs",
     "editors:pack": "node scripts/pack-editors.mjs",
     "prepack": "node scripts/pack-editors.mjs",
-    "lint": "node bin/garden.mjs sync && eslint . --ignore-pattern dist --ignore-pattern .next --ignore-pattern .garden --ignore-pattern templates"
+    "lint": "node bin/garden.mjs sync && eslint . --ignore-pattern dist --ignore-pattern .next --ignore-pattern .garden --ignore-pattern templates",
+    "version": "node scripts/sync-editor-version.mjs && git add editors/vscode/package.json editors/vscode/package-lock.json"
   },
   "dependencies": {
     "@cloudflare/vite-plugin": "1.37.1",

package/scripts/build-content.mjs

@@ -409,7 +409,9 @@ function validateAndNormalize(data, content, markdownPath, kind, sourcePath, lin
   }
 
   if (kind === "post") {
-    requireString(data, "description", sourcePath);
+    const description = optionalString(data, "description", sourcePath);
+    // An explicit blank is intentional: never replace it with an excerpt from the body.
+    if (!description) data.description = "";
   }
   if (kind === "thought" && data.mediaType) {
     if (!["image", "audio", "video", "link", "text"].includes(data.mediaType)) {

package/scripts/check-post.mjs

@@ -215,8 +215,8 @@ const checkFile = (filePath) => {
   if (typeof data.title !== "string" || !data.title.trim()) {
     error(errors, "missing-title", 1, `${sourcePath}: front matter 缺少有效的 title`);
   }
-  if (typeof data.description !== "string" || !data.description.trim()) {
-    error(errors, "missing-description", 1, `${sourcePath}: front matter 缺少有效的 description`);
+  if (data.description != null && typeof data.description !== "string") {
+    error(errors, "invalid-description", 1, `${sourcePath}: description 必须是字符串或留空`);
   }
   if (data.slug !== undefined) {
     error(errors, "unexpected-slug", 1, `${sourcePath}: 不要写 slug，文件名就是标识`);

package/scripts/pack-editors.mjs

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import zlib from "node:zlib";
+import { syncEditorVersion } from "./sync-editor-version.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const distDir = path.join(root, "editors", "dist");
@@ -16,7 +17,8 @@ function distReady() {
   const vsixDir = path.join(distDir, "vscode");
   const manifest = path.join(distDir, "typora", "manifest.json");
   if (!fs.existsSync(manifest) || !fs.existsSync(vsixDir)) return false;
-  return fs.readdirSync(vsixDir).some((name) => name.endsWith(".vsix"));
+  const version = syncEditorVersion({ check: true });
+  return fs.existsSync(path.join(vsixDir, `garden-ui-${version}.vsix`));
 }
 
 function withPackLock(fn) {
@@ -166,6 +168,7 @@ function vsixManifest(manifest) {
     <Identity Language="en-US" Id="${xmlEscape(manifest.name)}" Version="${xmlEscape(manifest.version)}" Publisher="${xmlEscape(manifest.publisher)}"/>
     <DisplayName>${xmlEscape(manifest.displayName)}</DisplayName>
     <Description xml:space="preserve">${xmlEscape(manifest.description)}</Description>
+    <Icon>extension/${xmlEscape(manifest.icon)}</Icon>
     <Tags>${xmlEscape(tags)}</Tags>
     <Categories>${xmlEscape(categories)}</Categories>
     <GalleryFlags>Public</GalleryFlags>
@@ -179,6 +182,7 @@ function vsixManifest(manifest) {
   </Installation>
   <Dependencies/>
   <Assets>
+    <Asset Type="Microsoft.VisualStudio.Services.Icons.Default" Path="extension/${xmlEscape(manifest.icon)}" Addressable="true"/>
     <Asset Type="Microsoft.VisualStudio.Code.Manifest" Path="extension/package.json" Addressable="true"/>
   </Assets>
 </PackageManifest>
@@ -188,6 +192,13 @@ function vsixManifest(manifest) {
 function packageVsix() {
   const source = path.join(root, "editors", "vscode");
   const manifest = JSON.parse(fs.readFileSync(path.join(source, "package.json"), "utf8"));
+  syncEditorVersion({ check: true });
+  if (manifest.icon !== "dist/icon.png") throw new Error("VS Code extension icon must be dist/icon.png");
+  const icon = fs.readFileSync(path.join(source, manifest.icon));
+  if (icon.subarray(0, 8).toString("hex") !== "89504e470d0a1a0a" || icon.readUInt32BE(16) < 128 || icon.readUInt32BE(20) < 128)
+    throw new Error("VS Code extension icon must be PNG, at least 128 × 128.");
+  if (!icon.equals(fs.readFileSync(path.join(root, "public/apple-touch-icon.png"))))
+    throw new Error("VS Code extension icon must reuse Garden's canonical public/apple-touch-icon.png.");
   const entries = [];
   const license = path.join(root, "LICENSE");
   if (fs.existsSync(license)) entries.push({ name: "extension/LICENSE", data: fs.readFileSync(license) });

package/scripts/sync-editor-version.mjs

@@ -0,0 +1,28 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const defaultRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+/** Root Garden version is authoritative. npm version runs this before its release commit. */
+export function syncEditorVersion({ root = defaultRoot, check = false } = {}) {
+  const version = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version;
+  if (!/^\d+\.\d+\.\d+$/u.test(version)) throw new Error("Garden editor releases require a stable major.minor.patch version.");
+  for (const name of ["package.json", "package-lock.json"]) {
+    const file = path.join(root, "editors/vscode", name);
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    const versions = name === "package-lock.json" ? [value, value.packages[""]] : [value];
+    if (versions.every((item) => item.version === version)) continue;
+    if (check) throw new Error(`${file} must match Garden ${version}; run node scripts/sync-editor-version.mjs and commit both editor manifests.`);
+    for (const item of versions) item.version = version;
+    fs.writeFileSync(file, JSON.stringify(value, null, 2) + "\n");
+  }
+  return version;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const version = syncEditorVersion({ check: process.argv.includes("--check") });
+  if (process.env.GITHUB_REF_TYPE === "tag" && process.env.GITHUB_REF_NAME !== `v${version}`)
+    throw new Error(`Release tag ${process.env.GITHUB_REF_NAME} does not match Garden v${version}`);
+  process.stdout.write(`Garden / VS Code extension version: ${version}\n`);
+}

package/templates/skills-en/garden-compose/SKILL.md

@@ -1,24 +1,22 @@
 ---
 name: garden-compose
-description: "Compose and verify Garden article layouts, Markdown/safe HTML, semantic scenes and necessary interactions through the single garden compose author entry."
+description: "Compile source prose plus a short effect request or reference image into faithful, verifiable Garden Compose layouts; use for creation, local tuning and repair."
 ---
 # Garden Compose
+Edit only authorized posts/blocks. Advice-only means no writes. Never automatically commit, publish, install dependencies or modify this skill during article work.
 
-Project-local skill. Edit only the authorized post/block; no automatic edits elsewhere, global installation, commits or publishing.
+## Reader question → constraints → recommended route → source leaves → verification
+1. The author supplies prose plus one desired effect/image and optional don'ts. Separate facts, appearance and edit scope. Preserve wording, order, complete paragraphs and resources; invent no summaries, numbers or causal arrows. Keep ordinary Markdown when sufficient.
+2. Read references/visual-selection.md before selection. Read references/mobile-contract.md first: choose the mobile reading task (scan, sequence, comparison or spatial relation), then internally derive the desktop+narrow geometry card: reader question, shared containers, hanging/body scope, centering target, typography relative to body, scene/internal/background layers, narrow-screen fallback and don'ts. This is AI working context, not author paperwork or runtime attributes. Use documented defaults for harmless ambiguity; ask only when facts, hidden content or reading order face material tradeoffs.
+3. Choose one **recommended** route, not a closed component whitelist: icon-rail; short flow-row or long flow-stack; equal-cards; centered-chip; prose-list. frameless-scene is an orthogonal option, as are tone and size. Demand-load the matching references/layout-recipes.md section; unfamiliar layouts/images require references/rendering-model.md. New combinations use references/composition-patterns.md while retaining the same constraints.
+4. Use one garden compose fence. Compare requires real shared comparison dimensions, not unrelated cards. Ordinary icon-led editorial paragraphs default to generic icon-rail; native icon-list is an exception for required semantic/host behavior with its actual styling limitations. Never recommend the removed garden list fence. Read references/static-play.md only for needed semantic/state capabilities; query the actual installed schema for props, children and icons. Markdown/safe HTML islands preserve full blocks; restricted expressions are not arbitrary JS.
 
-## Choose relationships before components
-1. Separate original facts/prose, reader question, requested appearance and authorized location. Advice-only means no file writes. Preserve wording, order, complete paragraphs, data and resources. Do not invent arrows, causal links, summaries or numbers.
-2. Use **one `garden compose` author entry**. Select and combine layouts, Markdown/safe HTML, semantic scenes and necessary interaction inside it. Use ordinary prose when that already communicates the idea.
-3. Work relationship → shared boundaries/hierarchy → width/flow/alignment → style → actual render. Demand-load `references/visual-selection.md` and `references/composition-patterns.md`; unfamiliar combinations or visual references require `references/rendering-model.md`, then `references/layout-recipes.md` as needed. These are transferable operations, not a closed pattern whitelist. A heading and every body paragraph need one shared container to form an aligned right column.
-4. Native resources/files/relations/rich choices and parameter-driven explanations all live inside Compose. Read `references/static-play.md` before choosing state; interaction must improve understanding. A missing recipe is not proof of a missing engine capability.
+## Write and verify
+1. Read references/workflow.md; scan and preserve target id/line, whole-fence base hash and source. Initial insertion is not apply. An uncompiled intent is not finished output.
+2. Follow centralized references/rendering-model.md pitfalls: icon-rail needs icon plus one shared right group containing heading and every paragraph/list; dividers separate rows. row>stack adds contextual top padding; row title/text flex:1 and center couples axes/text. Static unknown attributes may be ignored. Use group where the recipe requires it; do not assume direction="row" changes a stack.
+3. Body defaults inherit actual dynamic article family/size/line height. Do not shrink to fit. Explicit size needs a meaningful hierarchy or explicit author request. Scene frame, internal border and background are separate controls (references/frames.md); colors only as needed. Editorial prose prefers a frameless outer figure; independent experiments may retain a boundary.
+4. For micro-edits, modify only necessary candidate attributes/leaves, not component families. Stable id when available, otherwise freshly scanned line; always original complete-fence base and candidate file. Apply still replaces a whole fence: no attribute-patch or dry-run API. On conflicts rescan, never bypass protection or overwrite neighbors. Distinguish source bold markup from title's default weight.
+5. Run unchanged scripts/check.mjs plus garden check. Optional scripts/lint-layout.mjs uses a scratch constraint JSON and authoritative installed parser; workflow documents its limited structure coverage and exit codes. Risks are not global syntax errors. It cannot recover ignored attributes or prove fidelity/geometry.
+6. Every new layout owns mobile usability without asking the author for device tuning. Validate the narrowest case and enlarged body type first, then desktop under complete theme/CSS order; inspect reading density as well as geometry/computed styles and any actual interaction. centered-chip remains a browser-pending candidate; flow must not leave right arrows in a vertical fallback. Report accepted structure, render, browser geometry/interaction and independent clean-context model reliability separately. Missing evidence means unverified.
 
-## Execute and verify
-1. Read references/workflow.md from the site root. Run `node .agents/skills/garden-compose/scripts/scan.mjs content/posts/post.md`; retain source, diagnostics, target id/line and original whole-fence hash. Do not redraw correct blocks.
-2. `npx --no-install garden ui schema` is the demand-loaded source of actual fields, props/defaults, child contracts and icon names. Use `garden ui prompt` for working recipes. Save JSON under `.garden` and inspect only the needed components/icons. Some unsupported static layout attributes are ignored: inspect normalized output and actual styles, not acceptance alone.
-3. If no fence exists, insert one Compose intent block only at the authorized location, preserving prose and appearance requirements, then scan. Insertion is not apply; uncompiled intent is not a finished scene. Every candidate remains a complete `garden compose` fence, preserving original intent without rendering prose twice.
-4. Inline leaves accept Markdown and safe inline HTML. Use markdown/html islands for full article blocks. Allowlisted article HTML and local CSS are useful, but scripts/events/unsafe URLs are errors. Intentional executable demos use sandbox within Compose. Read `references/static-play.md` for literal-island versus restricted DIL expression boundaries; advertise neither unrestricted HTML/JS nor zero Markdown/HTML support.
-5. Body defaults inherit the **actual dynamic article** font family/size; do not invent a universal pixel baseline or shrink-to-fit. Use supported explicit variation for meaningful emphasis. Semantic values, graph labels, captions and controls retain their hierarchy; consult rendering-model for contextual source/computed sizes. Load colors/frames/examples only as needed.
-6. Store the complete candidate in temporary Markdown, then use scripts/apply.mjs: --id or scanned --at, always original whole-fence --base and candidate --file. Rescan if content changed; never remove conflict protection or target a null intent hash.
-7. Run scripts/check.mjs and garden check for real file paths. Match visuals using complete theme/CSS order, desktop+narrow screenshots, geometry and actual interactions. Separately report accepted markup, successful render, correct geometry/interactions and independently tested model reliability. Hand-authored passing DIL proves capability, not prompt reliability; disclose missing browser/model trials.
-
-Scripts only delegate to the installed CLI; no parser duplication, package downloads, default model calls or clipboard writes. Report missing local dependencies rather than installing another version. Propose reusable skill improvements for normal review; do not modify skills while processing an article.
+Scripts use only the installed local engine, no parser copies, downloads, default model calls or catalog dumps. Report missing dependencies. Shared references are demand-loaded; propose reusable maintenance separately from article editing.