@bovinphang/frontend-craft 2.7.0 → 2.8.0

package/skills/fec-e2e-testing/references/e2e-ci-reporting.md

@@ -1,6 +1,6 @@
-# E2E CI 与报告
+#E2E CI & Reporting
 
-## CI 集成（示例）
+## CI integration (example)
 
 ```yaml
 # .github/workflows/e2e.yml
@@ -29,34 +29,34 @@ jobs:
           retention-days: 30
 ```
 
-Cypress：固定 `CYPRESS_baseUrl` 或配置文件中的 `baseUrl`，失败截图/视频同样建议上传 artifact。
+Cypress: Fixed `CYPRESS_baseUrl` or `baseUrl` in the configuration file. Failure screenshots/videos are also recommended to upload artifacts.
 
-## E2E 报告模板（Markdown）
+## E2E report template (Markdown)
 
-输出或归档测试报告时可采用下列结构，便于复盘：
+The following structure can be used when outputting or archiving test reports to facilitate review:
 
 ```markdown
-# E2E 测试报告
+# E2E test report
 
-**日期：** YYYY-MM-DD HH:mm
-**耗时：** X 分 Y 秒
-**结果：** 通过 / 失败
+**Date:** YYYY-MM-DD HH:mm
+**Time taken:** X minutes Y seconds
+**Result:** Pass/Fail
 
-## 摘要
+## Summary
 
-- 总计 X | 通过 Y | 失败 Z | 不稳定/跳过 说明
+- Total X | Pass Y | Fail Z | Unstable/Skip Description
 
-## 失败用例
+## Failed use case
 
-### 用例名
+### Use case name
 
-- **文件：** `tests/e2e/xxx.spec.ts:行号`
-- **错误：** 简述断言或超时信息
-- **截图/Trace：** 路径或 artifact 名称
-- **建议修复：** 可执行结论
+- **File:** `tests/e2e/xxx.spec.ts:line number`
+- **ERROR:** Brief assertion or timeout information
+- **Screenshot/Trace:** path or artifact name
+- **Suggested fix:** Executable conclusion
 
-## 产物
+## Product
 
-- HTML 报告：`playwright-report/index.html`
-- Trace / 视频 / 截图：CI artifact 或本地 `test-results/`
+- HTML report: `playwright-report/index.html`
+- Trace / Video / Screenshot: CI artifact or local `test-results/`
 ```

package/skills/fec-e2e-testing/references/e2e-special-scenarios.md

@@ -1,11 +1,11 @@
-# E2E 特殊场景
+#E2E Special Scenario
 
-## Web3 / 钱包注入（Playwright）
+## Web3/Wallet Injection (Playwright)
 
-在 **`page.goto` 之前**通过 `context.addInitScript` 注入 mock，避免依赖真实插件：
+Inject mock through `context.addInitScript` before **`page.goto` to avoid relying on real plugins:
 
 ```typescript
-test("连接钱包", async ({ page, context }) => {
+test("Connect wallet", async ({ page, context }) => {
   await context.addInitScript(() => {
     (window as unknown as { ethereum?: unknown }).ethereum = {
       isMetaMask: true,
@@ -24,16 +24,16 @@ test("连接钱包", async ({ page, context }) => {
 });
 ```
 
-链 ID、账户列表与业务契约保持一致即可。
+Just keep the chain ID, account list and business contract consistent.
 
-## 金融或高风险操作
+## Financial or high-risk operations
 
-- **禁止**在真实生产环境执行真实资金操作；使用 **staging、mock 或 `test.skip`**。
-- 断言**预览金额、成功态**与**关键接口 200** 后再结束用例，超时给足（如链上确认场景）。
+- **It is prohibited** to perform real fund operations in a real production environment; use **staging, mock or `test.skip`**.
+- Assert **preview amount**, success status** and **key interface 200** before ending the use case, with sufficient timeout (such as on-chain confirmation scenario).
 
 ```typescript
-test("下单预览与成功态", async ({ page }) => {
-  test.skip(process.env.NODE_ENV === "production", "生产环境跳过真实交易");
+test("Order preview and success status", async ({ page }) => {
+  test.skip(process.env.NODE_ENV === "production", "The production environment skips real transactions");
 
   await page.goto("/markets/demo");
   await page.getByTestId("position-yes").click();

package/skills/fec-e2e-testing/references/e2e-visual-regression.md

@@ -1,33 +1,33 @@
-# E2E 视觉回归测试
+#E2E visual regression testing
 
-通过截图快照对比检测非预期的 UI 变化。适用于 CSS 重构、设计 Token 更新、组件改版等场景。
+Detect unexpected UI changes through screenshot comparison. Suitable for CSS refactoring, design token update, component revision and other scenarios.
 
-## 基础用法
+## Basic usage
 
 ```typescript
 import { test, expect } from "@playwright/test";
 
-test("首页布局与基线一致", async ({ page }) => {
+test("Homepage layout is consistent with baseline", async ({ page }) => {
   await page.goto("/");
   await page.waitForLoadState("networkidle");
 
-  // 全页截图对比 - 首次运行自动生成基线
+  // Compare full-page screenshots - automatically generate a baseline for the first run
   await expect(page).toHaveScreenshot("homepage-full.png", {
     fullPage: true,
-    maxDiffPixels: 100, // 允许的轻微像素差异（抗锯齿等）
+    maxDiffPixels: 100, // Slight pixel differences allowed (anti-aliasing, etc.)
   });
 });
 
-test("按钮组件视觉一致", async ({ page }) => {
+test("Button components are visually consistent", async ({ page }) => {
   await page.goto("/components/buttons");
   const submitButton = page.getByTestId("submit-button");
   await expect(submitButton).toHaveScreenshot("submit-button.png");
 });
 ```
 
-## 屏蔽动态内容
+## Block dynamic content
 
-时间、随机 ID、第三方广告等动态元素会导致误报，使用 `mask` 屏蔽：
+Dynamic elements such as time, random IDs, and third-party ads can cause false positives. Use `mask` to block them:
 
 ```typescript
 await expect(page).toHaveScreenshot("dashboard.png", {
@@ -39,9 +39,9 @@ await expect(page).toHaveScreenshot("dashboard.png", {
 });
 ```
 
-## 禁用动画
+## Disable animation
 
-CSS 动画会导致截图不一致，注入样式禁用动画后再截图：
+CSS animation will cause inconsistent screenshots. Inject the style to disable animation before taking screenshots:
 
 ```typescript
 await page.addStyleTag({
@@ -51,10 +51,10 @@ await page.addStyleTag({
 await expect(page).toHaveScreenshot("animated-page.png");
 ```
 
-## 基线管理
+## Baseline management
 
-- **首次运行**: `npx playwright test` 失败但自动生成基线到 `tests/` 目录
-- **更新基线**: UI 有意变更时 `npx playwright test --update-snapshots`
-- **CI 一致性**: 基线必须在与 CI 相同的 OS（Linux/Ubuntu）上生成，字体渲染在 macOS 与 Linux 间存在差异
-- **多浏览器**: 每个 project 独立生成基线（Chromium/Firefox/WebKit 渲染结果不同）
-- **基线文件**: 纳入 `.gitignore` 或 Git LFS 管理，避免仓库膨胀
+- **First run**: `npx playwright test` fails but automatically generates baseline into `tests/` directory
+- **Update baseline**: `npx playwright test --update-snapshots` when the UI is intentionally changed
+- **CI consistency**: Baseline must be generated on the same OS (Linux/Ubuntu) as CI, font rendering differs between macOS and Linux
+- **Multi-browser**: Each project generates a baseline independently (Chromium/Firefox/WebKit rendering results are different)
+- **Baseline file**: Incorporate into `.gitignore` or Git LFS management to avoid warehouse expansion

package/skills/fec-e2e-testing/references/playwright-patterns.md

@@ -1,6 +1,6 @@
-# Playwright / Cypress E2E 模式
+# Playwright / Cypress E2E Mode
 
-## 目录结构
+## Directory structure
 
 ```text
 tests/
@@ -46,8 +46,8 @@ export class ItemsPage {
 import { expect, test } from "@playwright/test";
 import { ItemsPage } from "../pages/ItemsPage";
 
-test.describe("商品搜索", () => {
-  test("按关键词搜索有结果", async ({ page }) => {
+test.describe("Product Search", () => {
+  test("Search by keyword and there are results", async ({ page }) => {
     const itemsPage = new ItemsPage(page);
     await itemsPage.goto();
     await itemsPage.search("test");
@@ -84,7 +84,7 @@ export default defineConfig({
 });
 ```
 
-## Flaky 调试
+## Flaky Debugging
 
 ```bash
 npx playwright test path/to/spec.ts --repeat-each=10
@@ -92,4 +92,4 @@ npx playwright test path/to/spec.ts --retries=3
 npx playwright show-trace path/to/trace.zip
 ```
 
-常见原因：竞态、网络时序、动画、测试数据污染、跨测试状态泄露。
+Common reasons: race conditions, network timing, animation, test data pollution, cross-test state leakage.

package/skills/fec-form-handling/SKILL.md

@@ -1,21 +1,21 @@
 ---
 name: fec-form-handling
-description: Use when building or reviewing substantial forms with React Hook Form, Zod schemas, typed validation, dynamic fields, controlled third-party inputs, file upload, multi-step flows, dependent validation, or form performance. Do not use for trivial 1-3 field forms without validation; Chinese triggers include 表单, 表单校验, 动态字段.
+description: Use when building or reviewing substantial forms with React Hook Form, Zod schemas, typed validation, dynamic fields, controlled third-party inputs, file upload, multi-step flows, dependent validation, or form performance. Do not use for trivial 1-3 field forms without validation; Chinese triggers include form, form validation, dynamic fields.
 ---
 
-# 表单处理
+# Form processing
 
 ## Purpose
 
-管理表单状态、校验和提交，避免复杂表单输入卡顿。
+Manage form status, verification and submission to avoid lags in complex form input.
 
 ## Procedure
 
-1. 先识别框架、项目既有表单库、schema 校验库、组件库和复杂度；10+ 字段、动态字段、联动校验、文件上传、多步流程或输入卡顿时再引入专门表单方案。
-2. 按项目栈选型：React 可考虑 React Hook Form + Zod；Vue 可考虑 vee-validate / FormKit + Zod、Yup 或 Valibot；简单表单可用框架原生状态和基础校验。
-3. 用运行时 schema 或明确校验函数守住外部输入边界；TypeScript 类型可从 schema 推导，但不要只写 TS 类型。
-4. 明确默认值、字段注册、受控/非受控边界和组件库适配；错误提示用 `aria-invalid`、`aria-describedby` 和 `role="alert"`。
-5. 提交时处理 loading、服务端错误、重复提交和 reset；大型表单用局部订阅和子组件隔离控制重渲染。
+1. First identify the framework, existing form library of the project, schema verification library, component library and complexity; then introduce special form solutions when there are 10+ fields, dynamic fields, linkage verification, file upload, multi-step process or input lag.
+2. Select according to project stack: React can consider React Hook Form + Zod; Vue can consider vee-validate / FormKit + Zod, Yup or Valibot; simple forms can use the framework's native state and basic verification.
+3. Use runtime schema or explicit validation functions to guard external input boundaries; TypeScript types can be deduced from the schema, but don’t just write TS types.
+4. Clarify default values, field registration, controlled/uncontrolled boundaries and component library adaptation; use `aria-invalid`, `aria-describedby` and `role="alert"` for error prompts.
+5. Handle loading, server-side errors, repeated submissions and resets when submitting; use local subscriptions and sub-component isolation to control re-rendering of large forms.
 
 ## React Quick Start
 
@@ -25,8 +25,8 @@ import { useForm } from "react-hook-form";
 import { z } from "zod";
 
 const loginSchema = z.object({
-  email: z.string().email("请输入有效的邮箱地址"),
-  password: z.string().min(8, "密码至少 8 个字符"),
+  email: z.string().email("Please enter a valid email address"),
+  password: z.string().min(8, "Password must be at least 8 characters"),
 });
 
 type LoginForm = z.infer<typeof loginSchema>;
@@ -43,34 +43,34 @@ export function LoginFormView() {
 
   return (
     <form onSubmit={handleSubmit((data) => api.login(data))} noValidate>
-      <label htmlFor="email">邮箱</label>
+      <label htmlFor="email">Email</label>
       <input id="email" {...register("email")} aria-invalid={!!errors.email} />
       {errors.email && <span role="alert">{errors.email.message}</span>}
 
-      <label htmlFor="password">密码</label>
+      <label htmlFor="password">Password</label>
       <input id="password" type="password" {...register("password")} />
       {errors.password && <span role="alert">{errors.password.message}</span>}
 
       <button disabled={isSubmitting}>
-        {isSubmitting ? "提交中..." : "提交"}
+        {isSubmitting ? "Submitting..." : "Submitting"}
       </button>
     </form>
   );
 }
 ```
 
-## 详细参考
+## Detailed reference
 
-涉及是否需要表单库、框架选型、`Controller`、`useFieldArray`、联动校验、文件上传、多步表单、异步校验和性能模式时，加载 [references/advanced-form-patterns.md](references/advanced-form-patterns.md)。
+When it comes to whether you need a form library, framework selection, `Controller`, `useFieldArray`, linkage verification, file upload, multi-step form, asynchronous verification and performance mode, load [references/advanced-form-patterns.md](references/advanced-form-patterns.md).
 
 ## Constraints
 
-- 沿用仓库既有表单库、schema 库和组件库适配方式，不为单个表单引入第二套体系。
-- 默认值必须完整，避免 undefined 触发受控/非受控警告或初始化抖动。
-- reset 应传服务器返回或明确的完整默认对象。
-- 异步校验必须 debounce 或放到提交边界，避免每次键入请求。
-- schema 级联动校验的错误 path 必须指向实际字段。
+- Inherit the existing form library, schema library and component library adaptation method of the warehouse, and do not introduce a second system for a single form.
+- Default values must be complete to avoid undefined triggering controlled/uncontrolled warnings or initialization flutter.
+- reset should be passed the full default object returned by the server or explicit.
+- Asynchronous validation must be debounced or placed on a commit boundary to avoid typing requests every time.
+- The error path of schema cascade dynamic verification must point to the actual field.
 
 ## Expected Output
 
-产出类型安全、可访问、提交状态明确的表单；复杂字段和文件上传有 schema 约束，输入过程无明显卡顿，服务端错误能回填到用户可理解的位置。
+The output form is type-safe, accessible, and has a clear submission status; complex fields and file uploads have schema constraints, there is no obvious lag in the input process, and server-side errors can be backfilled to a position that the user can understand.

package/skills/fec-form-handling/references/advanced-form-patterns.md

@@ -1,33 +1,33 @@
-# 高级表单模式
+# Advanced form mode
 
-## 先判断是否需要表单库
+## First determine whether a form library is needed
 
-- 1-3 个字段、无复杂校验、无动态字段、无组件库适配压力的表单，可用框架原生状态、浏览器约束校验和轻量提交状态。
-- 需要动态字段、跨字段校验、多步流程、文件上传、异步校验、服务端错误回填或明显输入卡顿时，再引入专门表单方案。
-- 表单库只管理字段状态和校验流程，不替代 API 错误映射、权限判断、可访问性标注或服务端最终校验。
+- A form with 1-3 fields, no complex validation, no dynamic fields, and no component library adaptation pressure. The native state of the framework, browser constraint verification, and lightweight submission state are available.
+- When dynamic fields, cross-field verification, multi-step processes, file uploads, asynchronous verification, server-side error backfilling or obvious input lag are required, a special form solution will be introduced.
+- The form library only manages field status and verification process, and does not replace API error mapping, permission judgment, accessibility annotation or server-side final verification.
 
-## 选型参考
+## Selection reference
 
-先沿用项目已有表单库、schema 库和组件库适配方式；新增依赖时再按场景选择。
+First, use the existing form library, schema library and component library adaptation method of the project; when adding new dependencies, select them according to the scenario.
 
-| 场景 | 候选方案 | 注意点 |
+| Scenarios | Alternative solutions | Notes |
 | --- | --- | --- |
-| React 复杂表单 | React Hook Form + Zod | 非受控优先，第三方受控组件用 `Controller`。 |
-| Vue 复杂表单 | vee-validate / FormKit + Zod、Yup 或 Valibot | 不要为 Vue 项目引入 React-only 表单 API；优先沿用项目既有 Vue 表单库。 |
-| 简单表单 | 框架原生状态 + 基础校验 | 避免为了 1-3 个字段引入重型表单体系。 |
-| 多步表单 | 分步 schema + 最终提交 schema | 明确跨步数据保存、返回上一步和最终校验策略。 |
-| 文件上传 | 表单库字段状态 + `FormData` | 校验文件数量、大小、类型；不要把 `File` JSON 序列化。 |
-| 异步校验 | 提交边界校验或 debounce 字段校验 | 避免每次键入请求；处理竞态和旧响应覆盖。 |
-
-## 通用实现原则
-
-- 运行时 schema 或校验函数负责外部输入边界；TypeScript 类型不能替代运行时校验。
-- 默认值、reset 数据和服务端回填数据要形状一致，避免字段在受控/非受控之间切换。
-- 字段错误要能映射到具体字段；全局错误用于提交失败、权限或服务不可用等非字段问题。
-- 组件库适配层要透传 value、onChange、onBlur、name/ref 或等价字段注册能力。
-- 提交时保护 loading、重复提交、取消/过期请求、服务端错误回填和成功后 reset。
-- 文件上传使用 `FormData` 或直传流程，前端校验只做体验保护，服务端仍需最终校验。
-- 性能优化优先使用字段级订阅、局部组件拆分和延迟校验，不要全表单 watch 后驱动整页重渲染。
+| React complex form | React Hook Form + Zod | Uncontrolled first, use `Controller` for third-party controlled components. |
+| Vue complex forms | vee-validate / FormKit + Zod, Yup or Valibot | Do not introduce React-only form API into Vue projects; give priority to using the existing Vue form library of the project. |
+| Simple form | Framework native state + basic validation | Avoid introducing heavy form system for 1-3 fields. |
+| Multi-step form | Step-by-step schema + final submission schema | Clear step-by-step data saving, return to the previous step and final verification strategies. |
+| File upload | Form library field status + `FormData` | Verify file quantity, size, type; do not serialize `File` JSON. |
+| Asynchronous validation | Submit bounds validation or debounce field validation | Avoid each type request; handle race conditions and old response overwrites. |
+
+## General implementation principles
+
+- The runtime schema or validation function is responsible for external input bounds; TypeScript types are not a substitute for runtime validation.
+- The default value, reset data and server-side backfill data must have the same shape to avoid fields switching between controlled/uncontrolled.
+- Field errors must be mapped to specific fields; global errors are used for non-field problems such as submission failure, permissions or service unavailability.
+- The component library adaptation layer must transparently transmit value, onChange, onBlur, name/ref or equivalent field registration capabilities.
+- Protect loading, duplicate submissions, cancellation/expiration requests, server-side error backfill and reset after success when submitting.
+- File upload uses `FormData` or direct transfer process. Front-end verification is only for experience protection, and the server still needs final verification.
+- Performance optimization prioritizes the use of field-level subscriptions, partial component splitting, and delayed verification. Do not watch the entire form and then drive the entire page to re-render.
 
 ## React Hook Form Controller
 
@@ -35,7 +35,7 @@
 <Controller
   name="role"
   control={control}
-  rules={{ required: "请选择角色" }}
+  rules={{ required: "Please select a role" }}
   render={({ field, fieldState }) => (
     <>
       <Select {...field} options={roleOptions} />
@@ -45,9 +45,9 @@
 />
 ```
 
-用于不暴露原生 `ref` 的 Select、DatePicker、RichEditor 等组件。
+Used for components such as Select, DatePicker, RichEditor, etc. that do not expose native `ref`.
 
-## React Hook Form 动态字段
+## React Hook Form dynamic fields
 
 ```tsx
 const { fields, append, remove } = useFieldArray({
@@ -58,14 +58,14 @@ const { fields, append, remove } = useFieldArray({
 {fields.map((field, index) => (
   <div key={field.id}>
     <input {...register(`contacts.${index}.name`)} />
-    <button type="button" onClick={() => remove(index)}>删除</button>
+    <button type="button" onClick={() => remove(index)}>Delete</button>
   </div>
 ))}
 ```
 
-`key` 必须使用 `field.id`，不要使用数组 index。
+`key` must use `field.id`, do not use array index.
 
-## Zod 联动校验
+## Zod linkage verification
 
 ```ts
 const schema = z
@@ -74,28 +74,28 @@ const schema = z
     confirmPassword: z.string().min(8),
   })
   .refine((data) => data.password === data.confirmPassword, {
-    message: "两次密码不一致",
+    message: "The two passwords are inconsistent",
     path: ["confirmPassword"],
   });
 ```
 
-## Zod 文件上传校验
+## Zod file upload verification
 
 ```ts
 const schema = z.object({
   avatar: z
     .instanceof(FileList)
-    .refine((files) => files.length > 0, "请上传头像")
-    .refine((files) => files[0]?.size <= 5 * 1024 * 1024, "文件大小不超过 5MB")
-    .refine((files) => ["image/jpeg", "image/png"].includes(files[0]?.type), "仅支持 JPG/PNG"),
+    .refine((files) => files.length > 0, "Please upload an avatar")
+    .refine((files) => files[0]?.size <= 5 * 1024 * 1024, "The file size does not exceed 5MB")
+    .refine((files) => ["image/jpeg", "image/png"].includes(files[0]?.type), "Only JPG/PNG is supported"),
 });
 ```
 
-提交时用 `FormData`，不要把 `File` JSON 序列化。
+Use `FormData` when submitting, do not serialize `File` JSON.
 
-## 性能
+## Performance
 
-- 用 `useWatch` 或字段级订阅替代全表单 watch。
-- 大表单拆成 memoized 子组件或框架等价的局部更新单元。
-- 高频输入不要每次键入触发网络校验。
-- 多步表单要明确每步 schema 和跨步最终 schema。
+- Replace full form watch with `useWatch` or field level subscription.
+- Split large forms into memoized sub-components or framework-equivalent local update units.
+- For high-frequency input, do not trigger network verification every time you type.
+- For multi-step forms, the schema of each step and the final schema of the step must be clear.

package/skills/fec-image-generation/SKILL.md

@@ -1,56 +1,81 @@
 ---
 name: fec-image-generation
-description: Use when generating or editing diagrams, charts, visual assets, posters, UI mockups, product images, infographics, academic figures, comics, avatars, storyboards, brand boards, or image-edit workflows, especially when exported PNGs need visual QA and bounded self-repair. Prefer deterministic Mermaid/SVG/HTML/canvas sources for text-heavy diagrams; do not use for ordinary UI polish without generated imagery. Chinese triggers include 图片生成, 图像编辑, 图表生成, 架构图, ER 图, UML, 序列图, 海报, UI 样机, 产品图, 信息图, 学术图, 漫画, 头像, 分镜, 品牌板, PNG 自检, 自动修复.
+description: Use when generating or editing diagrams, charts, visual assets, posters, UI mockups, product images, infographics, academic figures, comics, avatars, storyboards, brand boards, or image-edit workflows, especially when exported PNGs need visual QA and bounded self-repair. Prefer deterministic Mermaid/SVG/HTML/canvas sources for text-heavy diagrams; use HTML technical diagrams for browser-ready system blueprints, architecture, deployment topology, agent runtime, memory flow, before-after architecture, workflow, sequence, data-flow, lifecycle, runbook, PII/data-lineage, and state-machine diagrams. Do not use for ordinary UI polish without generated imagery.
 ---
 
-# 图片生成与图表工作流
+# Image generation and chart workflow
 
 ## Purpose
 
-生成或编辑图表、视觉资产和图片工作流，并对导出的 PNG 做可复查的自检与修复迭代。
+Generate or edit diagrams, visual assets, and image workflows, and perform reviewable self-checks and repair iterations on exported PNGs.
 
 ## Procedure
 
-1. 判断产物类型
-   - 文本、结构和连线准确性优先时，用 Mermaid、SVG、HTML/CSS、canvas 或图表库生成可编辑源，再导出 PNG。
-   - 审美、质感、照片、插画、漫画、产品图或品牌氛围优先时，用图片生成或编辑工具，再把最终资产保存到项目或报告目录。
+1. Determine product type
+   - When accuracy of text, structure, and connections is a priority, use Mermaid, SVG, HTML/CSS, canvas, or a graphics library to generate editable sources and then export as PNG.
+   - Use HTML technical diagrams when the user needs a browser-ready single file with dark/light theme support for system blueprints, architecture, deployment topology, agent runtime, memory flow, before-after architecture, workflow, sequence, data-flow, lifecycle, runbook, state-machine, or PII/data-lineage diagrams.
+   - Use the HTML `workflow` route for process maps, approvals, automation runs, exception paths, and cyclical operating flows that need readable start/end, decision, actor, numbered-step, and summary treatment without requiring diagrams.net.
+   - Use themed HTML technical diagrams when a system, agent, memory, data, or tool-call map needs semantic node shapes, flow-aware arrows, and a browser-ready source that can still be exported and QA-checked.
+   - Use the interactive live diagram route when the user benefits from watching nodes and edges appear incrementally in a local browser, or when they want to drag, relabel, remove, zoom, and export a quick diagram during the session.
+   - When aesthetics, texture, photos, illustrations, comics, product images or brand atmosphere are priorities, use image generation or editing tools, and then save the final assets to the project or report directory.
 
-2. 明确输入与约束
-   - 收集受众、用途、尺寸、语言、必须出现的文本、品牌限制、可编辑源格式、导出格式和禁用元素。
-   - 对海报、UI 样机、品牌板和产品图，先写出一行视觉读取：目标用户、场景、可信感来源、主视觉锚点。
+2. Clarify inputs and constraints
+   - Collect audience, purpose, dimensions, language, required text, branding restrictions, editable source format, export format, and disabled elements.
+   - For posters, UI mockups, brand boards and product images, first write a line of visual reading: target users, scenarios, sources of credibility, and main visual anchors.
 
-3. 选择生成路线
-   - ER 图、UML 类图、序列图、技术架构图、ML/深度学习、流程图等，优先按 [diagram-workflows.md](references/diagram-workflows.md) 建立结构化源。
-   - 海报、UI 样机、产品图、信息图、学术图、漫画、头像、分镜、品牌板和图像编辑，按 [artifact-routing.md](references/artifact-routing.md) 选择生成、编辑或混合路线。
+3. Select Generate Route
+   - ER diagrams, UML class diagrams, sequence diagrams, technical architecture diagrams, ML/deep learning, flow charts, etc., give priority to creating structured sources according to [diagram-workflows.md](references/diagram-workflows.md).
+   - For themed browser-ready system blueprints, architecture, workflow, sequence, data-flow and lifecycle diagrams, read [html-technical-diagrams.md](references/html-technical-diagrams.md), then render JSON IR with [tech-diagram-render.mjs](scripts/tech-diagram-render.mjs). For process workflows, model participants as `lanes`, ordered actions as `nodes`, and exception or loop paths as `edges` with optional `waypoints`:
+     ```bash
+     node skills/fec-image-generation/scripts/tech-diagram-render.mjs --input diagram.json --output diagram.html --type architecture --manifest diagram.layout.json
+     ```
+   - For agent and memory diagrams, prefer `architecture` IR with semantic node types such as `agent`, `model`, `memory`, `vectorstore`, `graphdb`, `tool`, `document`, `queue`, `browser`, `user`, and `gateway`. Add connection `flow` values (`control`, `data`, `read`, `write`, `async`, `feedback`) when arrow meaning matters; two or more flow types produce an automatic flow legend.
+   - Use optional `visual.style` for source-owned theme direction: `default`, `terminal`, `blueprint`, `minimal`, `glass`, `warm`, `openai`, or `editorial-dark`. Treat these as delivery themes, not brand guarantees.
+   - When README-friendly SVG, PNG, JPG, or JPEG artifacts are needed from generated HTML/SVG sources, export with [export-diagram.mjs](scripts/export-diagram.mjs):
+     ```bash
+     node skills/fec-image-generation/scripts/export-diagram.mjs --input diagram.html --format svg
+     node skills/fec-image-generation/scripts/export-diagram.mjs --input diagram.html --format png --output diagram.png --scale 2
+     ```
+   - For live interactive sketches, start [interactive-diagram-server.mjs](scripts/interactive-diagram-server.mjs), open the served [interactive-diagram.html](assets/interactive-diagram.html) page with a unique `?s=session-id`, then POST small JSON commands to `/cmd?s=session-id`:
+     ```bash
+     node skills/fec-image-generation/scripts/interactive-diagram-server.mjs --port 6100
+     curl -s "http://127.0.0.1:6100/cmd?s=checkout-flow" -d '{"cmd":"init","title":"Checkout Flow","direction":"TB"}'
+     curl -s "http://127.0.0.1:6100/cmd?s=checkout-flow" -d '{"cmd":"node","id":"cart","label":"Review cart","type":"process"}'
+     ```
+   - Use the draw.io studio workflow instead when the priority is editable `.drawio` source, official diagrams.net shapes, or long-term manual editing.
+   - Posters, UI mockups, product graphics, infographics, academic graphics, comics, avatars, storyboards, brand boards and image editing, press [artifact-routing.md](references/artifact-routing.md) to choose generate, edit or hybrid routing.
 
-4. 导出并自检 PNG
-   - 每次交付前都读取导出的 PNG，检查主体是否真实渲染、文字是否截断、连线是否堆叠、节点是否重叠。
-   - 有布局 manifest 时运行：
+4. Export and self-check PNG
+   - Read the exported PNG before each delivery to check whether the main body is truly rendered, whether the text is truncated, whether the connections are stacked, and whether the nodes overlap.
+   - Run when there is a layout manifest:
      ```bash
      node skills/fec-image-generation/scripts/png-qa.mjs --png output.png --manifest layout.json --format markdown
      ```
-   - 没有 manifest 时仍运行 PNG 基础检查：
+   - Still running PNG basic checks without manifest:
      ```bash
      node skills/fec-image-generation/scripts/png-qa.mjs --png output.png --format json
      ```
 
-5. 自动修复循环
-   - 默认最多 2 轮；用户明确要求时可提高到 5 轮软上限。
-   - 修复对象是源文件、prompt、布局参数或导出尺寸，不直接破坏性修改 PNG 像素。
-   - 按 [png-qa-autofix.md](references/png-qa-autofix.md) 把问题转成具体修复：增大画布、换行、移动节点、分层连线、调整 padding 或重导出。
+5. Automatic repair loop
+   - Default maximum of 2 rounds; can be increased to a soft cap of 5 rounds when explicitly requested by the user.
+   - The repair object is the source file, prompt, layout parameter or export size, and does not directly destructively modify PNG pixels.
+   - Click [png-qa-autofix.md](references/png-qa-autofix.md) to turn the problem into a specific fix: increase the canvas, wrap lines, move nodes, layer connections, adjust padding or re-export.
 
-6. 交付记录
-   - 说明最终源文件、PNG 路径、生成路线、QA 轮次、发现并修复的问题、仍需人工确认的文字或品牌风险。
+6. Delivery records
+   - Describe final source files, PNG paths, build routes, QA rounds, issues found and fixed, text or branding risks that still require manual confirmation.
 
 ## Constraints
 
-- 文本密集图不要只靠位图模型生成；必须保留可编辑结构化源。
-- 不把截图、假数据或占位图当成最终产品图，除非用户明确要求概念稿。
-- 不直接覆盖原图；编辑工作流默认输出新文件。
-- 不为追求美观牺牲可读标签、连线归属、图例、坐标轴和可访问替代说明。
-- PNG helper 只做检测和建议；修复必须回到源、prompt 或布局参数。
-- 自检结果不能替代人工确认专有名词、公式、论文图注、品牌规范和合规信息。
+- Text-intensive images should not be generated solely from bitmap models; editable structured sources must be retained.
+- HTML technical diagrams must keep the JSON source and generated HTML; exported PNG/SVG/JPG files are delivery artifacts, not the source of truth. Use `.drawio` instead when official vendor icons or long-term manual editing are the priority.
+- Themed semantic diagrams are implemented through the Frontend Craft renderer. Do not add Python, shell, cairosvg, rsvg-convert, Puppeteer, CDN capture libraries, copied SVG templates, or external icon packs as required dependencies for this route.
+- Interactive live diagrams are session-time previews. Save JSON/SVG/PNG exports when the diagram becomes a deliverable, and switch to HTML technical diagrams or `.drawio` when long-term source ownership matters.
+- Do not treat screenshots, fake data, or placeholder images as final product images unless the user explicitly requests a concept draft.
+- The original image is not directly overwritten; the editing workflow outputs a new file by default.
+- Readable labels, line attributions, legends, axes, and accessible alternative descriptions are not sacrificed for aesthetics.
+- PNG helper only does detection and suggestions; fixes must go back to source, prompt, or layout parameters.
+- Self-check results cannot replace manual confirmation of proper nouns, formulas, paper illustrations, brand specifications and compliance information.
 
 ## Expected Output
 
-产出可编辑源、最终 PNG 或编辑后图片，并附带生成路线与 QA 结果。图表应结构清晰、标签不截断、连线不混乱；视觉资产应匹配用途、尺寸、品牌语气和交付路径。
+Produce editable source, final PNG or edited image with generated routes and QA results. Diagrams should be clearly structured, with uncensored labels and uncluttered connections; visual assets should match purpose, size, brand tone, and delivery path.