hd-garden 0.13.3 → 0.14.2

package/app/components/garden/blocks.tsx

@@ -1,15 +1,12 @@
 "use client";
+import { AuthorRich as Rich } from "./AuthorRich";
 
-import { useEffect, useRef, type ReactNode } from "react";
-import ReactMarkdown from "react-markdown";
+import { type ReactNode } from "react";
 import { useUi, useUiLang } from "../UiLang";
-import { langOf, ui } from "../../lib/i18n";
-import { interactiveUiSource } from "../../../ui/core/garden-fence.mjs";
-import { markdownPlugins } from "../../lib/markdown-plugins";
 import { compileUiBlock } from "../../../ui/core/compile.mjs";
 import { splitCompareLine } from "../../../ui/garden/compare-line.mjs";
 import { RuntimeLangProvider, UiErrorCard, UiFigure, type Diagnostic, type UiPayload } from "../../../ui/react";
-import { FullscreenFrame, SandboxFrame } from "./chrome";
+import { FullscreenFrame } from "./chrome";
 import { SourceMark, VerdictIcon } from "./patterns";
 
 const BASE_PATH = (process.env.NEXT_PUBLIC_BASE_PATH ?? "").replace(/\/+$/u, "");
@@ -20,13 +17,7 @@ function publicSrc(src: string) {
   return `${BASE_PATH}${src}`;
 }
 
-function Rich({ text }: { text: string }) {
-  return (
-    <ReactMarkdown remarkPlugins={markdownPlugins} components={{ p: ({ children }) => <>{children}</> }}>
-      {String(text ?? "")}
-    </ReactMarkdown>
-  );
-}
+
 
 function hostOf(url: string) {
   try {
@@ -265,188 +256,11 @@ export function GardenChart({ props }: { props: Record<string, unknown> }) {
   );
 }
 
-function htmlHasScript(source: string) {
-  return /<script\b(?![^>]*\btype\s*=\s*["']application\/json["'])/iu.test(source);
-}
-
-function isLightWidget(source: string) {
-  return /data-g="(?:quiz|calc|tabs|stepper|kvplay)"|class="[^"]*\b(?:g-steps|g-faq|g-quiz|g-tabs|g-play|g-calc)\b/iu.test(source);
-}
-
-function bindGardenWidgets(root: HTMLElement) {
-  const attr = root.closest("[lang]")?.getAttribute("lang");
-  const t = ui(attr ? langOf(attr) : undefined);
-  root.querySelectorAll<HTMLElement>("[data-g=tabs]").forEach((widget) => {
-    const list = widget.querySelector<HTMLElement>(":scope > [role=tablist]");
-    const tabs = [...(list?.querySelectorAll<HTMLElement>(":scope > [role=tab]") ?? [])];
-    const select = (index: number, focus = false) => {
-      tabs.forEach((tab, tabIndex) => {
-        const on = index === tabIndex;
-        tab.setAttribute("aria-selected", String(on));
-        tab.tabIndex = on ? 0 : -1;
-        const panel = document.getElementById(tab.getAttribute("aria-controls") || "");
-        if (panel) panel.hidden = !on;
-      });
-      if (focus) tabs[index]?.focus();
-    };
-    tabs.forEach((tab, index) => {
-      tab.addEventListener("click", () => select(index));
-      tab.addEventListener("keydown", (event) => {
-        const count = tabs.length;
-        const next = event.key === "ArrowRight" ? (index + 1) % count
-          : event.key === "ArrowLeft" ? (index - 1 + count) % count
-            : event.key === "Home" ? 0
-              : event.key === "End" ? count - 1 : -1;
-        if (next < 0) return;
-        event.preventDefault();
-        select(next, true);
-      });
-    });
-  });
-
-  root.querySelectorAll<HTMLFormElement>("[data-g=quiz]").forEach((form) => {
-    const out = form.querySelector<HTMLElement>(".g-quiz-out");
-    const explain = form.querySelector<HTMLElement>(".g-quiz-ex");
-    form.addEventListener("submit", (event) => {
-      event.preventDefault();
-      if (!out) return;
-      const chosen = form.querySelector<HTMLInputElement>("input:checked");
-      if (!chosen) {
-        out.className = "g-quiz-out";
-        out.textContent = t.pickAnswer;
-        return;
-      }
-      const correct = chosen.value === form.dataset.answer;
-      out.className = `g-quiz-out ${correct ? "ok" : "no"}`;
-      out.textContent = correct ? t.correct : t.wrong;
-      if (explain) explain.hidden = !correct;
-    });
-  });
-
-  root.querySelectorAll<HTMLElement>("[data-g=stepper]").forEach((stepper) => {
-    const panels = [...stepper.querySelectorAll<HTMLElement>("[data-step]")];
-    const dots = [...stepper.querySelectorAll<HTMLElement>(".g-stepper-dots i")];
-    const count = stepper.querySelector(".g-stepper-n");
-    const title = stepper.querySelector(".g-stepper-t");
-    const prev = stepper.querySelector<HTMLButtonElement>("[data-prev]");
-    const next = stepper.querySelector<HTMLButtonElement>("[data-next]");
-    let index = 0;
-    const show = () => {
-      panels.forEach((panel, panelIndex) => { panel.hidden = panelIndex !== index; });
-      if (count) count.textContent = `${index + 1} / ${panels.length}`;
-      if (title) title.textContent = panels[index]?.dataset.title || "";
-      dots.forEach((dot, dotIndex) => dot.classList.toggle("on", dotIndex <= index));
-      if (prev) prev.disabled = index === 0;
-      if (next) next.disabled = index === panels.length - 1;
-    };
-    prev?.addEventListener("click", () => { if (index > 0) { index -= 1; show(); } });
-    next?.addEventListener("click", () => { if (index < panels.length - 1) { index += 1; show(); } });
-    show();
-  });
-
-  root.querySelectorAll<HTMLElement>("[data-g=calc]").forEach((calc) => {
-    const raw = calc.querySelector("script[type='application/json'], script[type=\"application/json\"]")?.textContent;
-    if (!raw) return;
-    const spec = JSON.parse(raw) as {
-      formula: string;
-      vars: Record<string, { fixed?: number; values?: number[]; label?: string }>;
-      format?: string;
-      unit?: string;
-      show?: string;
-    };
-    const names = Object.keys(spec.vars);
-    const fn = new Function(...names, `return (${spec.formula})`) as (...args: number[]) => number;
-    const read = (key: string) => {
-      const variable = spec.vars[key];
-      if (variable?.fixed !== undefined) return Number(variable.fixed);
-      const field = calc.querySelector<HTMLInputElement | HTMLSelectElement>(`[data-k="${key}"]:checked`)
-        ?? calc.querySelector<HTMLInputElement | HTMLSelectElement>(`[data-k="${key}"]`);
-      if (!field) return 0;
-      if (variable?.values && field instanceof HTMLInputElement && field.type === "range") {
-        const value = variable.values[Number(field.value)] ?? variable.values[0];
-        const output = field.parentElement?.querySelector("output");
-        if (output) output.textContent = String(value);
-        field.setAttribute("aria-valuetext", String(value));
-        return Number(value);
-      }
-      const value = Number(field.value);
-      const output = field.parentElement?.querySelector("output");
-      if (output && field instanceof HTMLInputElement && field.type === "range") output.textContent = field.value;
-      return value;
-    };
-    const run = () => {
-      const values = Object.fromEntries(names.map((key) => [key, read(key)]));
-      const result = fn(...names.map((key) => values[key]));
-      const out = calc.querySelector("[data-out]");
-      if (out) {
-        out.textContent = spec.format === "GB"
-          ? `${(result / 2 ** 30).toFixed(2)} GB`
-          : `${Math.round(result * 1e4) / 1e4}${spec.unit ? ` ${spec.unit}` : ""}`;
-      }
-      const equation = calc.querySelector("[data-calc]");
-      if (equation && spec.show) {
-        const shown = spec.show.replace(/\{(\w+)\}/g, (_, key: string) => String(values[key]));
-        equation.textContent = `${shown} = ${spec.format === "GB" ? `${Math.round(result).toLocaleString("en-US")} ${t.bytes}` : String(Math.round(result * 1e4) / 1e4)}`;
-      }
-    };
-    calc.addEventListener("input", run);
-    calc.addEventListener("change", run);
-    run();
-  });
-}
-
-function StaticGardenHtml({ code }: { code: string }) {
-  const ref = useRef<HTMLDivElement>(null);
-  useEffect(() => {
-    const host = ref.current;
-    if (!host) return;
-    const root = host.shadowRoot ?? host.attachShadow({ mode: "open" });
-    root.innerHTML = code;
-  }, [code]);
-  return (
-    <div
-      className="g-html"
-      ref={ref}
-      suppressHydrationWarning
-      dangerouslySetInnerHTML={{ __html: `<template shadowrootmode="open">${code}</template>` }}
-    />
-  );
-}
-
-function LightGardenHtml({ code }: { code: string }) {
-  const ref = useRef<HTMLDivElement>(null);
-  useEffect(() => {
-    const host = ref.current;
-    if (host) bindGardenWidgets(host);
-  }, [code]);
-  return <div className="g-widget" ref={ref} dangerouslySetInnerHTML={{ __html: code }} />;
-}
-
-export function GardenHtml({ props, children }: { props: Record<string, unknown>; children?: string }) {
-  const code = typeof props.code === "string" ? props.code : children || "";
-  const t = useUi();
-  const title = String(props.title ?? "HTML");
-  if (!code && typeof props.src === "string") {
-    return <p className="g-embed-note">{t.htmlAt(String(props.src))}</p>;
-  }
-  if (htmlHasScript(code)) {
-    return <SandboxFrame html={code} title={title} />;
-  }
-  if (isLightWidget(code)) {
-    const view = <LightGardenHtml code={code} />;
-    return /class="[^"]*\bg-play\b|data-g="calc"/iu.test(code) ? <FullscreenFrame label={title}>{view}</FullscreenFrame> : view;
-  }
-  return <FullscreenFrame label={title}><StaticGardenHtml code={code} /></FullscreenFrame>;
-}
-
-export function GardenInteractive({ block }: { block: { id?: string | null; props: Record<string, unknown>; children?: string; uiSource?: string } }) {
+export function GardenInteractive({ block, renderScene }: { renderScene?: (source: string) => React.ReactNode; block: { id?: string | null; props: Record<string, unknown>; children?: string; uiSource?: string; payload?: UiPayload | null } }) {
   const t = useUi();
   const lang = useUiLang();
-  // Prefer DIL-lowered uiSource from compose/dil.mjs; else build from PascalCase children (TEMP legacy).
-  const built = interactiveUiSource({ id: block.id ?? null, props: block.props, children: block.children ?? "" });
-  const source = typeof block.uiSource === "string" && block.uiSource.trim() ? block.uiSource : built.source;
-  const header = built.header;
-  const { payload, check } = compileUiBlock(source);
+  const { payload, check } = block.payload ? {payload:block.payload,check:{header:{id:block.payload.id,caption:block.payload.caption},diagnostics:[]}} : compileUiBlock(block.uiSource ?? "");
+  const header = {id:payload?.id??block.id,caption:payload?.caption??block.props.caption};
   if (!payload) {
     return (
       <RuntimeLangProvider lang={lang}>
@@ -462,7 +276,7 @@ export function GardenInteractive({ block }: { block: { id?: string | null; prop
     <RuntimeLangProvider lang={lang}>
     <FullscreenFrame label={String(header.caption || t.interactive)}>
       <div className="g-play">
-        <UiFigure payload={payload as UiPayload} />
+        <UiFigure payload={payload as UiPayload} host={renderScene ? {renderScene} : undefined} />
       </div>
     </FullscreenFrame>
     </RuntimeLangProvider>
@@ -479,9 +293,7 @@ export function GardenIdea({ text }: { text: string }) {
   );
 }
 
-export function GardenLegacy({ suggestion }: { suggestion: string }) {
-  return <p className="g-embed-note">{suggestion}</p>;
-}
+
 
 export function GardenUnknown({ name }: { name: string }) {
   const t = useUi();

package/app/components/garden/file-icons.tsx

@@ -1,6 +1,6 @@
 export { safeFileHref } from "../../../ui/garden/file-block.mjs";
 
-// Icons for `garden file`. No hooks: used by the server card and the client drawer alike.
+// Icons for Compose file. No hooks: used by the server card and the client drawer alike.
 const PAGE = "M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8z";
 const FOLD = "M14 3v5h5";
 const MARKS: Record<string, string> = {

package/app/components/garden/patterns.tsx

@@ -1,76 +1,18 @@
 "use client";
+import { hasIcon, iconSvg } from "../../../ui/compose/icons.mjs";
+import { AuthorRich as Rich } from "./AuthorRich";
 
-import { createContext, useContext, useEffect, useId, useRef, useState, type ComponentType, type CSSProperties, type ReactNode } from "react";
+import { createContext, useContext, useEffect, useId, useRef, useState, type CSSProperties, type ReactNode } from "react";
 import { sourceIcon } from "../../../ui/garden/source-icon.mjs";
 import { circled, labelFits, legendLine, placeMarks, relationKeyAction, RELATION_COMPACT_WIDTH, RELATION_LABEL_FONT_MIN, relationEdges, relationHeights, relationIndex, relationLayout, relationLines, type RelationEdge as Edge } from "../../../ui/garden/relations.mjs";
-import ReactMarkdown from "react-markdown";
-import {
-  Bell,
-  BookOpen,
-  ChartBar,
-  ChatCircle,
-  CheckCircle,
-  Clock,
-  Eye,
-  FileText,
-  Flag,
-  Flask,
-  Gear,
-  Heart,
-  Lightbulb,
-  LinkSimple,
-  MagnifyingGlass,
-  MapPin,
-  Question,
-  ShieldCheck,
-  Star,
-  Target,
-  User,
-  Wallet,
-  XCircle,
-  type IconProps,
-} from "@phosphor-icons/react/ssr";
+import {CheckCircle, XCircle} from "@phosphor-icons/react/ssr";
 import { useUi, useUiLang } from "../UiLang";
-import { markdownPlugins } from "../../lib/markdown-plugins";
 
-function Rich({ text }: { text: string }) {
-  return (
-    <ReactMarkdown remarkPlugins={markdownPlugins} components={{ p: ({ children }) => <>{children}</> }}>
-      {String(text ?? "")}
-    </ReactMarkdown>
-  );
-}
 
-/** Line icons an author can name in `icon:`. Unknown names draw nothing. */
-export const GARDEN_ICONS: Record<string, ComponentType<IconProps>> = {
-  search: MagnifyingGlass,
-  eye: Eye,
-  heart: Heart,
-  chat: ChatCircle,
-  shield: ShieldCheck,
-  wallet: Wallet,
-  bell: Bell,
-  check: CheckCircle,
-  x: XCircle,
-  star: Star,
-  flag: Flag,
-  clock: Clock,
-  idea: Lightbulb,
-  book: BookOpen,
-  link: LinkSimple,
-  user: User,
-  chart: ChartBar,
-  gear: Gear,
-  file: FileText,
-  pin: MapPin,
-  flask: Flask,
-  target: Target,
-  question: Question,
-};
 
-export function GardenIcon({ name, size = 18 }: { name: unknown; size?: number }) {
-  const Icon = typeof name === "string" ? GARDEN_ICONS[name.trim().toLowerCase()] : undefined;
-  return Icon ? <Icon className="g-ic" size={size} weight="regular" aria-hidden="true" /> : null;
+export function GardenIcon({name,size=18}:{name:unknown;size?:number}) {
+  if(!hasIcon(String(name)))return null;
+  return <span aria-hidden="true" dangerouslySetInnerHTML={{__html:iconSvg(String(name)).replace('class="g-compose-icon"',`class="g-compose-icon" style="width:${size}px;height:${size}px"`)}}/>;
 }
 
 const textsOf = (value: unknown) => (value == null ? [] : Array.isArray(value) ? value.map(String) : [String(value)]);

package/app/lib/rehype-garden-blocks.mjs

@@ -0,0 +1,30 @@
+const FLOW_TAGS = new Set(['garden-block', 'garden-refdemo', 'garden-codediff']);
+
+/** Custom elements are phrasing content to the HTML parser, but render as flow.
+ * Lift them before React renders them into figures/divs inside a paragraph. */
+export function rehypeGardenBlocks() {
+  return tree => {
+    function visit(parent) {
+      if (!Array.isArray(parent.children)) return;
+      parent.children = parent.children.flatMap(node => {
+        visit(node);
+        if (node.type !== 'element' || node.tagName !== 'p' || !node.children.some(child => child.type === 'element' && FLOW_TAGS.has(child.tagName))) return [node];
+        const result = [];
+        let prose = [];
+        const flush = () => {
+          if (prose.some(child => child.type !== 'text' || child.value.trim())) result.push({...node, children:prose});
+          prose = [];
+        };
+        for (const child of node.children) {
+          if (child.type === 'element' && FLOW_TAGS.has(child.tagName)) {
+            flush();
+            result.push(child);
+          } else prose.push(child);
+        }
+        flush();
+        return result;
+      });
+    }
+    visit(tree);
+  };
+}

package/app/lib/remark-garden.mjs

@@ -94,10 +94,6 @@ function rewriteChildren(node, nextScope) {
     if (child?.type === "code") {
       const record = fenceNodeToRecord(child);
       const kind = classifyFence({ ...record, body: child.value, line: 1, endLine: 1 });
-      if (kind.kind === "legacy") {
-        next.push(gardenElement({ legacy: true, from: kind.lang || record.lang, suggestion: kind.suggestion }));
-        continue;
-      }
       if (kind.kind === "garden" && kind.block?.name === "compose" && !kind.block.error && kind.block.mode !== "play") {
         next.push(htmlElement(renderCompose(kind.block.props, { scope: nextScope() })));
         continue;

package/app/lib/ui-model.ts

@@ -9,8 +9,8 @@ import converter from "../../ui/prompt/recipes/converter.md?raw";
 import plan from "../../ui/prompt/recipes/plan.md?raw";
 import dataChart from "../../ui/prompt/recipes/data-chart.md?raw";
 import codeWalkthrough from "../../ui/prompt/recipes/code-walkthrough.md?raw";
-import { findBlocks, intentHash, setCompiled, splitUiBody } from "../../ui/core/fence.mjs";
-import { checkUiBlock } from "../../ui/core/validate.mjs";
+import { findBlocks } from "../../ui/core/fence.mjs";
+import { checkComposeFence } from "../../ui/core/scan.mjs";
 import { buildPrompt, RECIPE_FILES } from "../../ui/prompt/build.mjs";
 
 const recipeText: Record<string, string> = {
@@ -91,7 +91,7 @@ async function complete(messages: Message[]) {
 }
 
 function extract(content: string) {
-  const fence = findBlocks(content).find((block) => block.lang === "ui" && block.closed);
+  const fence = findBlocks(content).find((block) => block.lang === "garden-compose" && block.closed);
   const before = fence ? content.slice(0, fence.start) : content;
   const note = /^提醒[:：]\s*(.+)$/mu.exec(before)?.[1]?.trim() ?? null;
   return { fence, note };
@@ -122,14 +122,13 @@ export async function draftUiBlock(input: { mode: "create" | "revise"; instructi
     const { fence, note } = extract(reply.content);
     if (!fence) {
       if (round === 2) break;
-      messages.push({ role: "assistant", content: reply.content }, { role: "user", content: "回复里没有 ui 围栏。请只回复一个完整的 ui 围栏。" });
+      messages.push({ role: "assistant", content: reply.content }, { role: "user", content: "回复里没有 garden compose 围栏。请只回复一个完整的 garden compose 围栏。" });
       continue;
     }
     // lineOffset 1: in the workbench editor the fence starts on line 1.
-    const check = checkUiBlock(fence.body, { lineOffset: 1, skipData: true });
+    const check = checkComposeFence(fence, {skipData:true});
     const errors = (check.diagnostics as DraftDiagnostic[]).filter((item) => item.severity === "error");
-    const { header } = splitUiBody(fence.body);
-    const stamped = typeof header?.intent === "string" ? setCompiled(fence.raw, intentHash(header.intent)) : fence.raw;
+    const stamped = fence.raw;
     if (!errors.length || round === 2) {
       return { fence: stamped, note, diagnostics: check.diagnostics as DraftDiagnostic[], rounds: round, usage };
     }
@@ -137,9 +136,9 @@ export async function draftUiBlock(input: { mode: "create" | "revise"; instructi
       { role: "assistant", content: reply.content },
       {
         role: "user",
-        content: `程序校验发现这些问题：\n${errors.map((item) => `- 第 ${item.line} 行 ${item.code}：${item.message}`).join("\n")}\n请修正后重新给出完整的 ui 围栏，格式不变。`,
+        content: `程序校验发现这些问题：\n${errors.map((item) => `- 第 ${item.line} 行 ${item.code}：${item.message}`).join("\n")}\n请修正后重新给出完整的 garden compose 围栏，格式不变。`,
       },
     );
   }
-  return { fence: null, note: null, diagnostics: [], rounds: 2, usage, error: "模型没有给出 ui 围栏", raw: lastContent };
+  return { fence: null, note: null, diagnostics: [], rounds: 2, usage, error: "模型没有给出 garden compose 围栏", raw: lastContent };
 }

package/app/styles/a2.css

@@ -367,6 +367,18 @@ html[data-theme="dark"] .column-reading-page .e-content {
   margin-top: 28px;
 }
 
+/* H4 sits below H3: same sans family, smaller size, still bold. */
+.markdown-body h4 {
+  font: 600 var(--fs-body) / 1.55 var(--sans);
+  color: var(--ink);
+  letter-spacing: 0;
+  margin: 28px 0 10px;
+}
+
+.markdown-body h3 + h4 {
+  margin-top: 18px;
+}
+
 .sec-no {
   color: var(--blue);
   font-variant-numeric: tabular-nums;
@@ -377,6 +389,10 @@ html[data-theme="dark"] .column-reading-page .e-content {
   margin: 0 0 22px;
 }
 
+.markdown-body > :is(ul, ol) + p {
+  margin-top: 22px;
+}
+
 .markdown-body strong {
   font-weight: 600;
   color: var(--ink);
@@ -1631,7 +1647,7 @@ html[data-theme="dark"] .g-quiz-out.no { color: #f29aab; }
   .g-range { grid-template-columns: 84px minmax(0, 1fr) 54px; gap: 8px; }
 }
 
-/* ---- garden file: a download card, a group of rows, a preview drawer ---- */
+/* ---- Compose files: a download card, a group of rows, a preview drawer ---- */
 .gf { margin: 24px 0; border: 1px solid var(--rule); border-radius: 12px; background: transparent; font-family: var(--sans); }
 .gf-title { padding: 14px 16px 0; font-size: 14px; font-weight: 600; line-height: 1.4; color: var(--muted); }
 .gf-row { display: flex; align-items: center; gap: 14px; padding: 14px 16px; }

package/bin/garden.mjs

@@ -2,6 +2,8 @@
 import { randomBytes } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { startDev } from "../scripts/dev-server.mjs";
+import { installSiteGuide } from "../scripts/site-guide.mjs";
+import { installManagedSkills } from "../scripts/managed-skills.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import { createRequire } from "node:module";
@@ -202,6 +204,7 @@ async function ensureSiteKit(destinationRoot = siteRoot) {
   const lang = siteCliLang(destinationRoot);
   if (!samePath(destinationRoot, gardenPackageRoot)) {
     const added = [];
+    if (installSiteGuide({ engineRoot: gardenPackageRoot, siteRoot: destinationRoot, lang })) added.push("AGENTS.md");
     if (
       copyIfMissing(
         path.join(gardenPackageRoot, "templates", "site", lang === "en" ? "Makefile.en" : "Makefile"),
@@ -283,11 +286,17 @@ async function prepare() {
   await ensureSiteKit();
 }
 
-async function sync() {
+async function sync({ refreshLinks = false } = {}) {
   if (!fs.existsSync(path.join(siteRoot, "site.config.yaml"))) {
     fail(`当前目录不是 Garden 站点（缺少 site.config.yaml）：${siteRoot}`);
   }
   await prepare();
+  // Same path as `garden links` / formal build: collect Markdown URLs (incl. drafts),
+  // refresh link-assets.json + public assets, then regenerate. Failures keep usable cache.
+  if (refreshLinks && process.env.GARDEN_OFFLINE !== "1") {
+    const links = spawnSync(process.execPath, [path.join(gardenPackageRoot, "scripts/link-assets.mjs"), "--dev"], { cwd: siteRoot, env: siteEnv(), stdio: "inherit" });
+    if (links.status !== 0) console.warn("链接资源：刷新失败，沿用可用缓存");
+  }
   runNode("scripts/build-content.mjs");
 }
 
@@ -320,7 +329,7 @@ function ensureDevGitHubLogin() {
 async function runVinext(vinextArgs, { copyDist = false } = {}) {
   const cwd = vinextRoot();
   if (vinextArgs[0] === "dev") {
-    const { finished } = await startDev({ cwd, executable: resolveVinext(), args: vinextArgs.slice(1), env: siteEnv(), prepare: sync });
+    const { finished } = await startDev({ cwd, executable: resolveVinext(), args: vinextArgs.slice(1), env: siteEnv(), prepare: () => sync({ refreshLinks: true }) });
     const result = await finished;
     if (result.status !== 0) process.exit(result.status || 1);
     return;
@@ -341,7 +350,7 @@ const EN_TEMPLATE_VARIANTS = new Set(["site.config.en.yaml", "Makefile.en", "REA
 function copyTemplate(from, to) {
   fs.mkdirSync(to, { recursive: true });
   for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
-    if (entry.name === ".git" || EN_TEMPLATE_VARIANTS.has(entry.name)) continue;
+    if (entry.name === ".git" || entry.name === "AGENTS.md" || entry.name === "AGENTS.en.md" || EN_TEMPLATE_VARIANTS.has(entry.name)) continue;
     const source = path.join(from, entry.name);
     const destination = path.join(to, entry.name);
     if (entry.isDirectory()) copyTemplate(source, destination);
@@ -414,6 +423,7 @@ async function initSite() {
       fs.copyFileSync(enWorkflow, workflowDest);
     }
   }
+  installSiteGuide({ engineRoot: gardenPackageRoot, siteRoot: destination, lang });
   writeEngineDependency(destination);
   process.stdout.write(lang === "en" ? `Created site: ${destination}\n` : `已创建站点：${destination}\n`);
   installSkill(destination, { lang });
@@ -466,34 +476,10 @@ async function editorsCommand(argv) {
   if (status) process.exit(status);
 }
 
-function packagedSkills() {
-  const root = path.join(gardenPackageRoot, ".agents", "skills");
-  if (!fs.existsSync(root)) return [];
-  return fs.readdirSync(root, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(root, entry.name, "SKILL.md")))
-    .map((entry) => entry.name);
-}
-
-function installSkill(destinationRoot = siteRoot, { onlyMissing = false, lang = siteCliLang(destinationRoot) } = {}) {
-  const names = packagedSkills();
-  if (!names.length) fail("Garden 包里没有 skill。");
-  const installed = [];
-  for (const name of names) {
-    const to = path.join(destinationRoot, ".agents", "skills", name);
-    if (onlyMissing && fs.existsSync(path.join(to, "SKILL.md"))) continue;
-    fs.cpSync(path.join(gardenPackageRoot, ".agents", "skills", name), to, { recursive: true });
-    // English sites get the English skill text; files without a translation keep the packaged copy.
-    const english = path.join(gardenPackageRoot, "templates", "skills-en", name);
-    if (lang === "en" && fs.existsSync(english)) fs.cpSync(english, to, { recursive: true, force: true });
-    installed.push(name);
-  }
-  if (installed.length) {
-    process.stdout.write(
-      lang === "en"
-        ? `Installed skills: ${installed.join(", ")}\n`
-        : `已安装 skill：${installed.join("、")}\n`,
-    );
-  }
+function installSkill(destinationRoot = siteRoot, { lang = siteCliLang(destinationRoot) } = {}) {
+  // Managed kits update recursively even on automatic sync; local edits are backed up.
+  const installed = installManagedSkills({ engineRoot: gardenPackageRoot, siteRoot: destinationRoot, lang });
+  process.stdout.write(lang === "en" ? `Installed skills: ${installed.join(", ")}\n` : `已安装 skill：${installed.join("、")}\n`);
 }
 
 function help() {
@@ -504,14 +490,16 @@ function help() {
   garden sync             只从 Markdown 生成索引
   garden new              创建文章草稿
   garden embed            拉取外链摘要
-  garden links            重新拉取外链图标（build 时会自动做）
-  garden images           读取新的远程图片尺寸，写入 image-sizes.json（build 时会自动做）
-  garden files            读取 garden file 里远程文件的大小，写入 file-sizes.json（build 时会自动做）
+  garden links            重新拉取外链图标与卡片元数据（dev / build 时也会自动做）
+  garden images           读取新的远程图片尺寸，写入 .garden/image-sizes.json（build 时会自动做）
+  garden files            读取 Compose <file> 里远程文件的大小，写入 file-sizes.json（build 时会自动做）
   garden init [目录]      创建只含稿和配置的新站点
   garden check <文章.md>  检查一篇博文的硬性结构
+  garden verify [文章.md|--diff] 全量/单篇/改动文档严格预检（包含草稿；make check 使用）
   garden ui <子命令>      Intelligent UI：scan、check、apply、prompt、schema、catalog
   garden hooks            安装提交前检查（检查暂存稿件里的 ui 块）
   garden editors install  安装 Intelligent UI 插件到 VS Code / Cursor 与 Typora（--vscode、--typora、--yes）
+  garden agents           仅在缺失时安装站点 AGENTS.md，保留已有指南
   garden skill            把引擎自带的 skill 装进当前站点
   garden pages:validate   检查 dist/client
   garden pages:prepare    写入公开产物仓库
@@ -542,7 +530,7 @@ async function main() {
       if (process.env.GARDEN_OFFLINE !== "1") runNode("scripts/link-assets.mjs");
       // Remote image sizes: only new images are probed; the rest come from image-sizes.json.
       if (process.env.GARDEN_OFFLINE !== "1") runNode("scripts/image-sizes.mjs");
-      // Sizes of remote files in garden file blocks; failures fall back to file-sizes.json.
+      // Sizes of remote files in Compose file components; failures fall back to file-sizes.json.
       if (process.env.GARDEN_OFFLINE !== "1") runNode("scripts/file-sizes.mjs");
       await runVinext(["build", ...rest], { copyDist: true });
       // /favicon.ico from the site's own icon (brand.favicon).
@@ -576,6 +564,9 @@ async function main() {
     case "embed":
       runNode("scripts/fetch-embed.mjs", rest);
       break;
+    case "verify":
+      runNode("scripts/check-site.mjs", rest);
+      break;
     case "check":
       runNode("scripts/check-post.mjs", rest);
       break;
@@ -591,6 +582,14 @@ async function main() {
     case "init":
       await initSite();
       break;
+    case "agents": {
+      if (samePath(siteRoot, gardenPackageRoot)) fail("This command is for a Garden site, not the engine repository.");
+      if (!fs.existsSync(path.join(siteRoot, "site.config.yaml"))) fail("Not a Garden site: missing site.config.yaml");
+      const lang = siteCliLang(siteRoot);
+      const created = installSiteGuide({ engineRoot: gardenPackageRoot, siteRoot, lang });
+      process.stdout.write(lang === "en" ? (created ? "Created AGENTS.md\n" : "Kept existing AGENTS.md\n") : (created ? "已创建 AGENTS.md\n" : "保留已有 AGENTS.md\n"));
+      break;
+    }
     case "skill":
     case "skills":
       installSkill();